@once-ui-system/core 1.7.12 → 1.8.0

package/ai/spec.json

@@ -1,7 +1,7 @@
 {
  "name": "@once-ui-system/core",
- "version": "1.7.12",
- "generated": "2026-07-05",
+ "version": "1.8.0",
+ "generated": "2026-07-29",
  "format": "props are 'type', 'type = default', or '!type' (required). Components with 'mixins' also accept all props of those mixins. 'extends' means all props of that component are accepted.",
  "tokens": {
   "StaticSpacingToken": "\"0\" | \"1\" | \"2\" | \"4\" | \"8\" | \"12\" | \"16\" | \"20\" | \"24\" | \"32\" | \"40\" | \"48\" | \"56\" | \"64\" | \"80\" | \"104\" | \"128\" | \"160\"",
@@ -15,10 +15,10 @@
   "Colors": "`${ColorScheme}-${ColorWeight}` | `${ColorScheme}-alpha-${ColorWeight}`",
   "RadiusSize": "TShirtSizes | \"full\" | \"none\"",
   "TextType": "\"body\" | \"heading\" | \"display\" | \"label\" | \"code\"",
-  "TextWeight": "\"default\" | \"strong\"",
+  "TextWeight": "\"default\" | \"normal\" | \"medium\" | \"strong\"",
   "TextSize": "TShirtSizes",
   "TextVariant": "`${TextType}-${TextWeight}-${TextSize}`",
-  "IconName": "\"chevronUp\" | \"chevronDown\" | \"chevronRight\" | \"chevronLeft\" | \"chevronsLeftRight\" | \"refresh\" | \"light\" | \"dark\" | \"help\" | \"info\" | \"warning\" | \"danger\" | \"checkbox\" | \"check\" | \"copy\" | \"eyeDropper\" | \"clipboard\" | \"person\" | \"close\" | \"link\" | \"arrowUpRight\" | \"minus\" | \"plus\" | \"calendar\" | \"eye\" | \"eyeOff\" | \"search\" | \"security\" | \"sparkle\" | \"computer\" | \"minimize\" | \"maximize\" | \"smiley\" | \"paw\" | \"food\" | \"ball\" | \"world\" | \"gift\" | \"symbol\" | \"flag\" | \"wordmark\" | \"enter\" | \"play\" | \"pause\" | \"screen\" | \"document\" | \"radialGauge\" | \"linearGauge\" | \"opacity\""
+  "IconName": "\"chevronUp\" | \"chevronDown\" | \"chevronRight\" | \"chevronLeft\" | \"chevronsLeftRight\" | \"refresh\" | \"light\" | \"dark\" | \"help\" | \"info\" | \"warning\" | \"danger\" | \"checkbox\" | \"check\" | \"copy\" | \"eyeDropper\" | \"clipboard\" | \"person\" | \"close\" | \"link\" | \"arrowUpRight\" | \"minus\" | \"plus\" | \"calendar\" | \"eye\" | \"eyeOff\" | \"search\" | \"security\" | \"sparkle\" | \"computer\" | \"minimize\" | \"maximize\" | \"smiley\" | \"paw\" | \"food\" | \"ball\" | \"world\" | \"gift\" | \"symbol\" | \"flag\" | \"wordmark\" | \"enter\" | \"play\" | \"pause\" | \"volume\" | \"volumeOff\" | \"screen\" | \"document\" | \"radialGauge\" | \"linearGauge\" | \"edit\" | \"trash\" | \"mail\" | \"download\""
  },
  "mixins": {
   "CommonProps": {
@@ -42,21 +42,6 @@
    "dark": "boolean",
    "light": "boolean"
   },
-  "FlexBreakpointProps": {
-   "direction": "\"row\" | \"column\" | \"row-reverse\" | \"column-reverse\"",
-   "horizontal": "\"start\" | \"center\" | \"end\" | \"between\" | \"around\" | \"even\" | \"stretch\"",
-   "vertical": "\"start\" | \"center\" | \"end\" | \"between\" | \"around\" | \"even\" | \"stretch\"",
-   "center": "boolean",
-   "overflow": "CSSProperties[\"overflow\"]",
-   "overflowX": "CSSProperties[\"overflowX\"]",
-   "overflowY": "CSSProperties[\"overflowY\"]",
-   "top": "SpacingToken",
-   "right": "SpacingToken",
-   "bottom": "SpacingToken",
-   "left": "SpacingToken",
-   "aspectRatio": "CSSProperties[\"aspectRatio\"]",
-   "style": "CSSProperties"
-  },
   "FlexProps": {
    "direction": "\"row\" | \"column\" | \"row-reverse\" | \"column-reverse\"",
    "horizontal": "\"start\" | \"center\" | \"end\" | \"between\" | \"around\" | \"even\" | \"stretch\"",
@@ -65,18 +50,6 @@
    "wrap": "boolean",
    "flex": "FlexValue"
   },
-  "GridBreakpointProps": {
-   "columns": "GridProps[\"columns\"]",
-   "overflow": "CSSProperties[\"overflow\"]",
-   "overflowX": "CSSProperties[\"overflowX\"]",
-   "overflowY": "CSSProperties[\"overflowY\"]",
-   "top": "SpacingToken",
-   "right": "SpacingToken",
-   "bottom": "SpacingToken",
-   "left": "SpacingToken",
-   "aspectRatio": "CSSProperties[\"aspectRatio\"]",
-   "style": "CSSProperties"
-  },
   "GridProps": {
    "columns": "GridSize",
    "rows": "GridSize"
@@ -367,8 +340,8 @@
   "BlobFx": {
    "group": "components",
    "extends": [
-    "Flex",
-    "Row"
+    "Row",
+    "Flex"
    ],
    "mixins": [
     "CommonProps",
@@ -385,8 +358,8 @@
   "Banner": {
    "group": "components",
    "extends": [
-    "Flex",
-    "Row"
+    "Row",
+    "Flex"
    ],
    "mixins": [
     "CommonProps",
@@ -546,6 +519,7 @@
     "translateY": "SpacingToken | number",
     "aspectRatio": "string = original",
     "sizes": "string",
+    "unoptimized": "boolean = false",
     "revealedByDefault": "boolean = false",
     "thumbnail": "ThumbnailItem = { scaling: 1, height: \"80\", sizes: \"120px\" }",
     "play": "{ auto?: boolean; interval?: number; controls?: boolean; progress?: boolean; } = { auto: false, interval: 3000, controls: true }"
@@ -571,6 +545,7 @@
     "fill": "boolean = false",
     "aspectRatio": "string = 16 / 9",
     "sizes": "string",
+    "unoptimized": "boolean = false",
     "indicator": "boolean = true"
    }
   },
@@ -681,7 +656,8 @@
    "props": {
     "isChecked": "boolean",
     "isIndeterminate": "boolean = false",
-    "onToggle": "() => void"
+    "onToggle": "() => void",
+    "hoverable": "boolean = true"
    }
   },
   "Chip": {
@@ -736,7 +712,8 @@
    "props": {
     "leftContent": "!SideContent",
     "rightContent": "!SideContent",
-    "aspectRatio": "string"
+    "aspectRatio": "string",
+    "unoptimized": "boolean"
    }
   },
   "ContextMenu": {
@@ -753,8 +730,8 @@
     "className": "string",
     "onSelect": "(value: string) => void",
     "closeAfterClick": "boolean = true",
-    "isOpen": "boolean",
-    "onOpenChange": "(isOpen: boolean) => void",
+    "open": "boolean",
+    "onOpenChange": "(open: boolean) => void",
     "selectedOption": "string",
     "disabled": "boolean = false"
    }
@@ -880,6 +857,8 @@
     "footer": "ReactNode",
     "base": "boolean",
     "stack": "boolean",
+    "flush": "boolean = false",
+    "hideClose": "boolean = false",
     "onHeightChange": "(height: number) => void",
     "minHeight": "number",
     "closeOnClickaway": "boolean = true"
@@ -1155,8 +1134,8 @@
   "HoverCard": {
    "group": "components",
    "extends": [
-    "Flex",
-    "Animation"
+    "Animation",
+    "Flex"
    ],
    "mixins": [
     "CommonProps",
@@ -1215,8 +1194,8 @@
   "InfiniteScroll": {
    "group": "components",
    "extends": [
-    "Flex",
-    "Row"
+    "Row",
+    "Flex"
    ],
    "mixins": [
     "CommonProps",
@@ -1538,8 +1517,8 @@
   "OgCard": {
    "group": "components",
    "extends": [
-    "Flex",
-    "Card"
+    "Card",
+    "Flex"
    ],
    "mixins": [
     "CommonProps",
@@ -1552,6 +1531,7 @@
    "props": {
     "url": "string",
     "sizes": "string = 320px",
+    "unoptimized": "boolean = false",
     "size": "CondensedTShirtSizes = m",
     "ogData": "Partial<OgData> | null",
     "direction": "\"column\" | \"row\" | \"column-reverse\" | \"row-reverse\" = column",
@@ -1696,7 +1676,8 @@
     "name": "string",
     "value": "string",
     "disabled": "boolean",
-    "onToggle": "() => void"
+    "onToggle": "() => void",
+    "hoverable": "boolean = true"
    }
   },
   "RevealFx": {
@@ -1768,8 +1749,8 @@
   "ScrollContainer": {
    "group": "components",
    "extends": [
-    "Flex",
-    "Row"
+    "Row",
+    "Flex"
    ],
    "mixins": [
     "CommonProps",
@@ -1804,8 +1785,8 @@
   "SegmentedControl": {
    "group": "components",
    "extends": [
-    "Flex",
-    "Scroller"
+    "Scroller",
+    "Flex"
    ],
    "mixins": [
     "CommonProps",
@@ -1836,7 +1817,7 @@
     "options": "!SelectOptionType[]",
     "value": "string | string[] = ",
     "emptyState": "ReactNode = No results",
-    "onSelect": "(value: any) => void",
+    "onSelect": "(value: string | string[]) => void",
     "placement": "Placement",
     "searchable": "boolean = false",
     "className": "string",
@@ -1937,8 +1918,8 @@
   "SplitView": {
    "group": "components",
    "extends": [
-    "Flex",
-    "Row"
+    "Row",
+    "Flex"
    ],
    "mixins": [
     "CommonProps",
@@ -2046,8 +2027,23 @@
     "StyleProps"
    ],
    "props": {
-    "data": "!{ headers: { content: ReactNode; key: string; sortable?: boolean; }[]; rows: ReactNode[][]; }",
-    "onRowClick": "(rowIndex: number) => void"
+    "data": "!{ headers: TableHeader[]; rows: ReactNode[][]; }",
+    "onRowClick": "(rowIndex: number) => void",
+    "searchable": "boolean = false",
+    "searchPlaceholder": "string = Search...",
+    "striped": "boolean = false",
+    "hoverable": "boolean = true",
+    "compact": "boolean = false",
+    "loading": "boolean = false",
+    "emptyState": "ReactNode",
+    "actions": "TableAction[]",
+    "stickyHeader": "boolean = false",
+    "rowClassName": "(rowIndex: number) => string",
+    "cellClassName": "(rowIndex: number, cellIndex: number) => string",
+    "paginated": "boolean = false",
+    "defaultPageSize": "number = 10",
+    "pageSizeOptions": "number[] = [5, 10, 20, 50]",
+    "loadingState": "ReactNode"
    }
   },
   "Tag": {
@@ -2199,8 +2195,8 @@
   "Tooltip": {
    "group": "components",
    "extends": [
-    "Flex",
-    "Row"
+    "Row",
+    "Flex"
    ],
    "mixins": [
     "CommonProps",
@@ -2234,8 +2230,8 @@
   "ThemeSwitcher": {
    "group": "components",
    "extends": [
-    "Flex",
-    "Row"
+    "Row",
+    "Flex"
    ],
    "mixins": [
     "CommonProps",
@@ -2356,7 +2352,7 @@
     "className": "string"
    }
   },
-  "HeadingLink": {
+  "HeadingNav": {
    "group": "modules",
    "extends": [
     "Flex"
@@ -2370,13 +2366,10 @@
     "StyleProps"
    ],
    "props": {
-    "id": "!string",
-    "as": "!\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\"",
-    "children": "!React.ReactNode",
-    "style": "React.CSSProperties"
+    "header": "boolean = true"
    }
   },
-  "HeadingNav": {
+  "HeadingLink": {
    "group": "modules",
    "extends": [
     "Flex"
@@ -2390,14 +2383,17 @@
     "StyleProps"
    ],
    "props": {
-    "header": "boolean = true"
+    "id": "!string",
+    "as": "!\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\"",
+    "children": "!React.ReactNode",
+    "style": "React.CSSProperties"
    }
   },
   "ChartHeader": {
    "group": "modules",
    "extends": [
-    "Flex",
-    "Column"
+    "Column",
+    "Flex"
    ],
    "mixins": [
     "CommonProps",

package/dist/AGENTS.md

@@ -0,0 +1,53 @@
+# @once-ui-system/core — agent harness
+
+This package ships an agent-first codegen harness under `ai/`. Use it when **writing Once UI code**, not full MDX documentation pages.
+
+## Entry point
+
+```
+@once-ui-system/core/ai/manifest.json
+```
+
+Or from disk:
+
+```
+node_modules/@once-ui-system/core/ai/manifest.json
+```
+
+## Bootstrap workflow
+
+1. Read `ai/manifest.json`
+2. Load bootstrap files: `ai/rules.compact.md` + `ai/catalog.json` (~6KB)
+3. Match intent via `ai/tasks/index.json` → e.g. `ai/tasks/pricing.json`
+4. Fetch component slices listed in the task bundle (`ai/components/*.json`)
+5. Read the gold example referenced by the task; for production fidelity, read Pro blocks from `ai/examples/blocks/manifest.json`
+6. Validate generated code: `npx once-ui-validate-ai-code path/to/file.tsx`
+
+## npm exports
+
+```tsx
+// Readable paths (version-pinned to your install)
+import manifest from '@once-ui-system/core/ai/manifest.json';
+```
+
+```bash
+# One-time project setup (writes AGENTS.md + Cursor rule in consumer app)
+npx once-ui-init-agent
+```
+
+## Remote fallback
+
+If you cannot read `node_modules`, use the docs host (may not match your installed version exactly):
+
+- https://docs.once-ui.com/ai/manifest.json
+- https://docs.once-ui.com/ai/rules.compact.md
+- https://docs.once-ui.com/once-ui/ai-coding
+
+## Key rules (summary)
+
+- Use `Column` / `Row`, not `Flex` unless direction changes at breakpoints
+- Use `fill`, not `fillWidth fillHeight`; use `center`, not `horizontal="center" vertical="center"`
+- Static panels: `Column background="surface" border="neutral-alpha-weak" radius="l" padding="24"`
+- `Card` is interactive only (`href` or `onClick`)
+
+Full rules: `@once-ui-system/core/ai/rules.compact.md`

package/dist/README.md

@@ -35,6 +35,33 @@ Learn how to set up and build with Once UI at [docs.once-ui.com](https://docs.on
 npm install @once-ui-system/core
 ```
 
+## AI codegen harness
+
+This package includes an agent-first harness under `ai/` for generating Once UI code with minimal context (~6–10KB per task).
+
+| Resource | Path |
+|----------|------|
+| Entry point | `@once-ui-system/core/ai/manifest.json` |
+| Compact rules | `@once-ui-system/core/ai/rules.compact.md` |
+| Component catalog | `@once-ui-system/core/ai/catalog.json` |
+| Task bundles | `@once-ui-system/core/ai/tasks/index.json` |
+
+**One-time setup in your app** (writes project `AGENTS.md` + Cursor rule):
+
+```bash
+npx once-ui-init-agent
+```
+
+**Validate generated code:**
+
+```bash
+npx once-ui-validate-ai-code src/app/page.tsx
+```
+
+Full guide: [docs.once-ui.com/once-ui/ai-coding](https://docs.once-ui.com/once-ui/ai-coding)
+
+Machine-readable discovery: see the `onceUi` field in this package's `package.json`.
+
 ## Authors
 
 Built and maintained by [**Lorant One**](https://lorant.one).

package/dist/agent/once-ui-codegen.mdc

@@ -0,0 +1,27 @@
+---
+description: Load Once UI agent harness before generating UI code
+globs: "**/*.{tsx,jsx}"
+alwaysApply: false
+---
+
+# Once UI codegen harness
+
+Before generating or editing Once UI UI code in this project:
+
+1. Read `@once-ui-system/core/ai/manifest.json` (or `node_modules/@once-ui-system/core/ai/manifest.json`)
+2. Load bootstrap files from the manifest: `rules.compact.md` + `catalog.json`
+3. Resolve intent via `ai/tasks/index.json` → fetch the matching task bundle
+4. Fetch only the component slices listed in that task (`ai/components/*.json`)
+5. Read the task's gold example; for production layouts, read matching Pro blocks from `ai/examples/blocks/manifest.json`
+6. Validate output: `npx once-ui-validate-ai-code path/to/file.tsx`
+
+## Do not
+
+- Use full documentation MDX pages for codegen (too large; use the harness)
+- Use `Flex direction="column"` when `Column` works; same for `Row`
+- Use `fillWidth fillHeight` when `fill` works
+- Use `Card` for static panels (use the surface recipe on `Column`)
+
+## Remote fallback
+
+https://docs.once-ui.com/ai/manifest.json