Merge branch 'main' into fix/circular-reference-protection

Author: senrecep

.changeset/tailwind-v4.md

@@ -0,0 +1,44 @@
+---
+"@geajs/ui": minor
+---
+
+### @geajs/ui (minor)
+
+- **Tailwind CSS v4**: Upgraded from Tailwind CSS v3 to v4. The CSS-based configuration system replaces the old JavaScript preset.
+- Migration steps:
+  1. **Update dependencies**
+    ```bash
+    npm install -D tailwindcss@4 @tailwindcss/vite
+    npm uninstall autoprefixer postcss
+    ```
+
+  2. **Update `vite.config.ts`** — add `@tailwindcss/vite` as a plugin and remove any inline PostCSS Tailwind config
+    ```ts
+    // vite.config.ts
+    import tailwindcss from '@tailwindcss/vite'
+
+    export default defineConfig({
+      plugins: [tailwindcss()],
+    })
+    ```
+
+  3. **Remove the old `@geajs/ui` preset/PostCSS wiring** — delete `postcss.config.js` if it only existed for Tailwind v3, and only remove `tailwind.config.js` if it contained no project-specific configuration
+
+  4. **Remove `@tailwind` directives** from any CSS files you own (e.g. `@tailwind base; @tailwind components; @tailwind utilities;`). You don't have to `@import "tailwindcss";` in your own CSS, just make sure the theme file is imported first.
+    ```ts
+    // main.ts
+    import '@geajs/ui/style.css'
+    import './style.css' 
+    ```
+
+  5. **Remove manual CSS resets** — if your project has a global reset like `* { margin: 0; padding: 0; }` outside a CSS layer, it will silently override Tailwind v4 utilities. In v4, all utilities live inside `@layer utilities`, and unlayered styles always win over layered styles regardless of specificity. Tailwind v4's Preflight already handles these resets inside `@layer base`, so the manual reset is redundant and should be removed
+    ```css
+    /* Remove this — Tailwind v4 Preflight already does it */
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    ```
+
+  6. **Check [Tailwind CSS upgrade guide](https://tailwindcss.com/docs/upgrade-guide#changes-from-v3)** for needed changes in your custom components

.cursor/skills/gea-ui-components/SKILL.md

@@ -15,34 +15,21 @@ Read `reference.md` in this skill directory for the full component API with prop
 
 ```bash
 npm install @geajs/core @geajs/ui
-npm install -D vite @geajs/vite-plugin
+npm install -D vite @geajs/vite-plugin tailwindcss @tailwindcss/vite
 ```
 
 ### Vite config
 
 ```js
 import { defineConfig } from 'vite'
 import { geaPlugin } from '@geajs/vite-plugin'
+import tailwindcss from '@tailwindcss/vite'
 
 export default defineConfig({
-  plugins: [geaPlugin()],
+  plugins: [geaPlugin(), tailwindcss()],
 })
 ```
 
-### Tailwind config
-
-```js
-import geaPreset from '@geajs/ui/tailwind-preset'
-
-export default {
-  presets: [geaPreset],
-  content: [
-    './src/**/*.{tsx,ts,jsx,js}',
-    './node_modules/@geajs/ui/dist/**/*.js',
-  ],
-}
-```
-
 ### Import styles
 
 ```ts

.cursor/skills/react-to-gea-migration/reference.md

@@ -51,11 +51,13 @@ Complete side-by-side conversion reference with real examples from the Jira clon
   "type": "module",
   "dependencies": {
     "@geajs/core": "^1.0.0",
-    "@geajs/ui": "^0.1.0"
+    "@geajs/ui": "^0.2.0"
   },
   "devDependencies": {
     "@geajs/vite-plugin": "^1.0.0",
+    "@tailwindcss/vite": "^4.0.0",
     "vite": "^8.0.0",
+    "tailwindcss": "^4.0.0",
     "typescript": "~5.8.0"
   }
 }
@@ -92,6 +94,7 @@ import { dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { defineConfig } from 'vite'
 import { geaPlugin } from '@geajs/vite-plugin'
+import tailwindcss from '@tailwindcss/vite'
 import { mockApiMiddleware } from './mock-api.ts'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -100,6 +103,7 @@ export default defineConfig({
   root: __dirname,
   plugins: [
     geaPlugin(),
+    tailwindcss(),
     {
       name: 'mock-api',
       configureServer(server) {
@@ -151,7 +155,7 @@ ReactDOM.render(<App />, document.getElementById('root'))
 
 ```ts
 import App from './App'
-import '../../../packages/gea-ui/src/styles/theme.css'
+import '@geajs/ui/style.css'
 import './styles.css'
 
 const root = document.getElementById('app')
@@ -507,7 +511,7 @@ export default class Board extends Component {
                 class={`board-filters-avatar ${filtersStore.userIds.includes(user.id) ? 'active' : ''}`}
                 click={() => filtersStore.toggleUserId(user.id)}
               >
-                <Avatar src={user.avatarUrl} name={user.name} class="!h-8 !w-8" />
+                <Avatar src={user.avatarUrl} name={user.name} class="h-8! w-8!" />
               </div>
             ))}
           </div>
@@ -555,7 +559,7 @@ Key differences:
 - Store is imported directly — no prop drilling or context consumers.
 - `<Fragment>` replaced with a wrapper `<div>`.
 - Route-based modal replaced with route params check in the parent `Project` layout.
-- `@geajs/ui` `Avatar` replaces custom Avatar with `src`, `name`, and CSS override `class="!h-8 !w-8"`.
+- `@geajs/ui` `Avatar` replaces custom Avatar with `src`, `name`, and CSS override `class="h-8! w-8!"`.
 - **Filter function is pure** — defined outside the component, takes all parameters explicitly. Store values are passed in from `template()` to ensure the compiler tracks them.
 
 ### Gea: Project as a router layout with `page` prop
@@ -814,10 +818,10 @@ Important: `@geajs/ui` Select always uses array values. For single select, wrap
 ```tsx
 import { Avatar } from '@geajs/ui'
 
-<Avatar src={user.avatarUrl} name={user.name} class="!h-8 !w-8" />
+<Avatar src={user.avatarUrl} name={user.name} class="h-8! w-8!" />
 ```
 
-Use CSS `!important` (or Tailwind's `!` prefix if using Tailwind) to override default Avatar dimensions.
+Use CSS `!important` (or Tailwind's `!` suffix if using Tailwind) to override default Avatar dimensions.
 
 ### Using Link with onNavigate
 
@@ -1103,10 +1107,10 @@ export const StyledButton = styled(Button)`
 .avatar-sm { width: 32px !important; height: 32px !important; }
 ```
 
-Or if using Tailwind, use the `!` prefix shorthand:
+Or if using Tailwind, use the `!` suffix shorthand:
 
 ```tsx
-<Avatar src={user.avatarUrl} name={user.name} class="!h-8 !w-8" />
+<Avatar src={user.avatarUrl} name={user.name} class="h-8! w-8!" />
 ```
 
 ---
@@ -1508,7 +1512,7 @@ export default class IssueCard extends Component {
           </div>
           <div class="issue-card-footer-right">
             {assignees.map((user: any) => (
-              <Avatar key={user.id} src={user.avatarUrl} name={user.name} class="!h-6 !w-6" />
+              <Avatar key={user.id} src={user.avatarUrl} name={user.name} class="h-6! w-6!" />
             ))}
           </div>
         </div>
@@ -1715,7 +1719,7 @@ export default class CommentCreate extends Component {
         {!this.isFormOpen && (
           <div class="comment-create-collapsed">
             <div class="comment-create-fake" click={() => this.openForm()}>
-              <Avatar src={user?.avatarUrl} name={user?.name || ''} class="!h-8 !w-8" />
+              <Avatar src={user?.avatarUrl} name={user?.name || ''} class="h-8! w-8!" />
               <span class="comment-create-placeholder">Add a comment...</span>
             </div>
             <p class="comment-pro-tip">
@@ -2093,7 +2097,7 @@ When porting styled-components to plain CSS, copy every value verbatim — `17px
 
 ### 13. Overriding `@geajs/ui` component dimensions
 
-`@geajs/ui` components have default dimensions. Override them with `!important` in your CSS, or with Tailwind's `!` prefix if using Tailwind:
+`@geajs/ui` components have default dimensions. Override them with `!important` in your CSS, or with Tailwind's `!` suffix if using Tailwind:
 
 ```css
 .avatar-sm { width: 32px !important; height: 32px !important; }

docs/gea-ui/getting-started.md

@@ -14,78 +14,51 @@ npm install @geajs/core
 
 ## Tailwind CSS Setup
 
-@geajs/ui uses [Tailwind CSS](https://tailwindcss.com/) **v3** for styling and ships a preset that defines the design token system (colors, border radius, etc.).
+@geajs/ui uses [Tailwind CSS](https://tailwindcss.com/) **v4** for styling. The theme CSS shipped with the library sets up Tailwind and all design tokens.
 
-::: warning
-Tailwind CSS v4 is **not yet supported**. Make sure you install Tailwind CSS v3.
-:::
-
-### 1. Install Tailwind CSS v3
+### 1. Install Tailwind and its Vite plugin
 
 ```bash
-npm install -D tailwindcss@3 postcss autoprefixer
-```
-
-Create a `postcss.config.js` in your project root:
-
-```js
-// postcss.config.js
-export default {
-  plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
-  },
-}
+npm install -D tailwindcss @tailwindcss/vite
 ```
 
-### 2. Add the Tailwind Preset
+Add the plugin to your `vite.config.ts`:
 
-```js
-// tailwind.config.js
-import geaPreset from '@geajs/ui/tailwind-preset'
+```ts
+import tailwindcss from '@tailwindcss/vite'
+import { defineConfig } from 'vite'
 
-export default {
-  presets: [geaPreset],
-  content: [
-    './src/**/*.{tsx,ts,jsx,js}',
-    './node_modules/@geajs/ui/dist/**/*.mjs',
-  ],
-}
+export default defineConfig({
+  plugins: [tailwindcss()],
+})
 ```
 
-The preset configures:
-
-- **Semantic colors** — `primary`, `secondary`, `destructive`, `muted`, `accent`, `popover`, `card`, `border`, `input`, `ring`, `background`, `foreground` — all driven by CSS custom properties.
-- **Border radius** — `lg`, `md`, `sm` tokens tied to a single `--radius` variable.
-- **Dark mode** — enabled via the `dark` class strategy.
-
-### 3. Import the Theme CSS
+### 2. Import the Theme CSS
 
-The theme stylesheet defines the CSS custom properties that the preset references. Import it once in your entry point:
+Import the theme stylesheet once in your entry point. It sets up Tailwind, all semantic color tokens, and dark mode support:
 
 ```ts
 // main.ts
 import '@geajs/ui/style.css'
 ```
 
-You also need a CSS file that includes Tailwind's directives. Create a `src/style.css` (or similar) and import it in your entry point:
+### 3. (Optional) Extend with Your Own CSS
+
+If you need additional Tailwind utilities or custom styles, create a CSS file and import it after the theme:
 
 ```css
 /* src/style.css */
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+/* your custom theme extensions or utilities */
 ```
 
 ```ts
 // main.ts
+// make sure the theme is imported first
 import '@geajs/ui/style.css'
 import './style.css'
 ```
 
-### 4. Include @geajs/ui in Tailwind's Content Paths
-
-Make sure `node_modules/@geajs/ui/dist/**/*.mjs` is listed in your `content` array (shown above). This allows Tailwind to scan @geajs/ui's component source and include the utility classes they use.
+You don't have to `@import "tailwindcss";` in your CSS file, it is already loaded by the theme.
 
 ## Minimal Example
 

docs/gea-ui/theming.md

@@ -40,7 +40,7 @@ The theme stylesheet (`@geajs/ui/style.css`) defines variables in HSL format on
 }
 ```
 
-Each variable holds the HSL values without the `hsl()` wrapper. The Tailwind preset references them as `hsl(var(--primary))`, so you only need to provide the three numbers (hue, saturation, lightness).
+Each variable holds the HSL values without the `hsl()` wrapper. The theme CSS maps them to Tailwind utilities via `@theme inline` (e.g. `hsl(var(--primary))`), so you only need to provide the three numbers (hue, saturation, lightness).
 
 ## Available Tokens
 
@@ -147,13 +147,14 @@ Styled components also apply semantic class names (`dialog-trigger`, `tabs-conte
 
 ## Border Radius
 
-The `--radius` variable controls the base radius. The Tailwind preset derives three tokens from it:
+The `--radius` variable controls the base radius. The theme derives four tokens from it:
 
 | Token | Value |
 | --- | --- |
 | `rounded-lg` | `var(--radius)` |
 | `rounded-md` | `calc(var(--radius) - 2px)` |
 | `rounded-sm` | `calc(var(--radius) - 4px)` |
+| `rounded-xs` | `calc(var(--radius) - 6px)` |
 
 Change `--radius` once and all components update:
 

examples/chat/styles.css

@@ -1,9 +1,3 @@
-* {
-  margin: 0;
-  padding: 0;
-  box-sizing: border-box;
-}
-
 body {
   font-family: 'Inter', system-ui, sans-serif;
   background: hsl(var(--background));

examples/dashboard/styles.css

@@ -1,9 +1,3 @@
-* {
-  margin: 0;
-  padding: 0;
-  box-sizing: border-box;
-}
-
 body {
   font-family: 'Inter', system-ui, sans-serif;
   background-color: hsl(var(--background));

examples/docs/app.tsx

@@ -2076,15 +2076,15 @@ export default class App extends Component {
                 <Dialog title="Confirm Delete" description="This cannot be undone." triggerLabel="Open Dialog">
                   <div style={{ display: 'flex', gap: '0.5rem', justifyContent: 'flex-end', marginTop: '1rem' }}>
                     <button
-                      class="inline-flex items-center justify-center gap-2 whitespace-nowrap font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground h-8 rounded-md px-3 text-xs"
+                      class="inline-flex items-center justify-center gap-2 whitespace-nowrap font-medium transition-colors focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 border border-input bg-background shadow-xs hover:bg-accent hover:text-accent-foreground h-8 rounded-md px-3 text-xs"
                       type="button"
                       data-part="close-trigger"
                       click={() => (this.dialogAction = 'Cancel clicked')}
                     >
                       Cancel
                     </button>
                     <button
-                      class="inline-flex items-center justify-center gap-2 whitespace-nowrap font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90 h-8 rounded-md px-3 text-xs"
+                      class="inline-flex items-center justify-center gap-2 whitespace-nowrap font-medium transition-colors focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 bg-destructive text-destructive-foreground shadow-xs hover:bg-destructive/90 h-8 rounded-md px-3 text-xs"
                       type="button"
                       data-part="close-trigger"
                       click={() => (this.dialogAction = 'Delete clicked')}

examples/docs/styles.css

@@ -1,9 +1,3 @@
-* {
-  margin: 0;
-  padding: 0;
-  box-sizing: border-box;
-}
-
 body {
   font-family: 'Inter', system-ui, sans-serif;
   background-color: hsl(var(--background));