mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/primitive-grid.md

@@ -0,0 +1,48 @@
+---
+id: primitive-grid
+title: `grid` — CSS grid container
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#grid]
+---
+
+# `grid`
+
+CSS Grid container. Use for 2D layouts (cards in rows, dashboards).
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `columns` | number/string/expression | — | CSS grid columns (number or template string) |
+| `rows` | string | — | CSS grid rows template |
+| `gap` | number | — | Gap between cells (px) |
+| `areas` | string | — | CSS grid-template-areas |
+| `className` | string | — | CSS class |
+
+## Examples
+
+Responsive columns:
+```json
+{ "type": "grid", "props": {
+  "columns": { "$breakpoint": { "sm": 1, "md": 2, "lg": 3 } },
+  "gap": 24
+}, "children": ["card-1", "card-2", "card-3"] }
+```
+
+Template areas:
+```json
+{ "type": "grid", "props": {
+  "areas": "'sidebar header' 'sidebar content'",
+  "columns": "240px 1fr",
+  "rows": "60px 1fr"
+}, "children": [...] }
+```
+
+## Related concepts
+
+- [[@primitive-stack]] — 1D alternative
+- [[@expression-breakpoint]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § grid`

package/docs/wiki/compiled/primitive-icon.md

@@ -0,0 +1,106 @@
+---
+id: primitive-icon
+title: `icon` — icon glyph
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#icon, docs/consumer/reference-doc.md#icon-primitive]
+---
+
+# `icon`
+
+Renders an icon glyph by name (kebab-case, library-agnostic). Apps connect
+a library via `plugins.setIconRenderer(Component)` from `MythikApp.onPlugins`.
+The built-in primitive keeps identity wrapping and calls the registered
+renderer with `{ name, size, weight, color, style }`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `name` | string | `"circle"` | Icon name (kebab-case: `pencil-simple`, `trash`, `moon`) |
+| `size` | number | `24` | Width/height in pixels |
+| `weight` | string | `"regular"` | `thin`, `light`, `regular`, `bold`, `fill`, `duotone` |
+| `color` | string | — | CSS color value (supports `$token`) |
+
+## Examples
+
+```json
+{ "type": "icon", "props": { "name": "pencil-simple", "size": 16, "weight": "bold" } }
+```
+
+Conditional theme icon:
+```json
+{ "type": "icon", "props": {
+  "name": { "$cond": { "$state": "/preferences/theme", "eq": "dark" }, "$then": "sun", "$else": "moon" },
+  "size": 16, "weight": "bold"
+}}
+```
+
+Inside a button:
+```json
+"edit-btn": {
+  "type": "button", "props": { "style": { "display": "inline-flex", "alignItems": "center" } },
+  "children": ["edit-icon"],
+  "on": { "press": { "action": "openModal", "params": { "id": "edit-modal" } } }
+},
+"edit-icon": { "type": "icon", "props": { "name": "pencil-simple", "size": 16, "weight": "bold", "color": { "$token": "colors.textMuted" } } }
+```
+
+## Identity defaults
+
+`identity.icons.weight` is the framework-level default; spec `weight`
+overrides. `identity.icons.container` (`'circle'`/`'square'`/`'rounded-square'`) auto-wraps unless `container={false}` in spec.
+`containerColor`: `'primary'|'accent'|'muted'|'surface'`.
+
+## Host renderer recipe
+
+```tsx
+const PHOSPHOR_ICONS = { calendar: Calendar, trash: Trash } as const;
+
+function PhosphorIcon({ name, size, weight, color, style }) {
+  const Icon = PHOSPHOR_ICONS[name as keyof typeof PHOSPHOR_ICONS] ?? Circle;
+  return <Icon size={size} weight={weight} color={color} style={style} />;
+}
+
+<MythikApp
+  appSpec={appSpec}
+  specStore={specStore}
+  onPlugins={(plugins) => plugins.setIconRenderer(PhosphorIcon)}
+/>;
+```
+
+Lucide uses the same pattern: map Mythik kebab-case names to imported
+Lucide components and render the selected component with `size`, `color`,
+and `style`.
+
+## Troubleshooting
+
+If the placeholder circle renders, verify:
+
+- `onPlugins` calls `plugins.setIconRenderer(...)`.
+- The consumer is installed from a tarball/package that includes the
+  `applyPlugins()` icon renderer fix.
+- Published-package validation is not accidentally using source aliases.
+
+## Advanced override
+
+`plugins.overridePrimitive('icon', ...)` is still supported for full
+replacement, but it bypasses the built-in identity wrapper. It must return
+a Mythik `RenderNode`, not JSX:
+
+```ts
+plugins.overridePrimitive('icon', (props, children) => ({
+  type: 'icon',
+  props: { ...props, _component: CustomIcon },
+  children,
+}));
+```
+
+## Related concepts
+
+- [[@concept-identity-icons]]
+- [[@expression-token]] — for color
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § icon`
+- `docs/consumer/reference-doc.md § Icon Primitive`

package/docs/wiki/compiled/primitive-image.md

@@ -0,0 +1,49 @@
+---
+id: primitive-image
+title: `image` — image
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#image]
+---
+
+# `image`
+
+Renders an image. Identity hooks: `corners` defaults from
+`identity.images.corners`; `overlay` adds gradient or color tint; `border`
+optional 1px frame.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `src` | string/expression | — | Image URL |
+| `alt` | string | — | Alt text |
+| `aspectRatio` | number | — | Width/height ratio |
+| `placeholder` | string | — | Placeholder while loading |
+
+## Examples
+
+```json
+{ "type": "image", "props": { "src": "/logo.png", "alt": "Logo", "aspectRatio": 16/9 } }
+```
+
+Avatar with state-driven URL:
+```json
+{ "type": "image", "props": {
+  "src": { "$template": "/avatars/${ /auth/user/id }.png" },
+  "alt": { "$auth": "name" }
+}}
+```
+
+## Identity defaults
+
+`identity.images.corners` (`'match-card'` uses card radius, `'circle'`,
+`'square'`, `'rounded'`), `identity.images.overlay`, `identity.images.border`
+all apply. Spec `style.borderRadius` or `overlay="none"` overrides.
+
+## Related concepts
+
+- [[@concept-identity-images]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § image`

package/docs/wiki/compiled/primitive-input.md

@@ -0,0 +1,81 @@
+---
+id: primitive-input
+title: `input` — text input
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#input]
+---
+
+# `input`
+
+Single-line text input. Supports `type` (text, password, email, number,
+date, tel, url, color), validators (`checks`), and display masks (`format`).
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | expression | — | Bind via `$bindState` |
+| `type` | string | `text` | `text`, `password`, `email`, `number`, `date`, `tel`, `url`, `color` |
+| `placeholder` | string/expression | — | Placeholder text |
+| `label` | string/expression | — | Field label |
+| `disabled` | boolean/expression | `false` | Disable input |
+| `readOnly` | boolean | `false` | Read-only mode |
+| `required` | boolean | `false` | Visual required indicator |
+| `format` | string | — | `phone`, `currency` — display format |
+| `formatOptions` | object | — | `{ currency, locale, decimals }` |
+| `selectOnFocus` | boolean | `false` | Select all text on focus |
+| `checks` | array | — | Inline validators |
+| `validateOn` | string | — | `blur` or `change` |
+
+## Events
+
+`on.change`, `on.submit` (fires on Enter — use for login/search).
+
+## Examples
+
+Basic email input:
+```json
+{ "type": "input", "props": {
+  "type": "email",
+  "value": { "$bindState": "/form/email" },
+  "label": "Email"
+}}
+```
+
+Currency display mask:
+```json
+{ "type": "input", "props": {
+  "type": "number",
+  "value": { "$bindState": "/form/amount" },
+  "format": "currency",
+  "formatOptions": { "currency": "USD" }
+}}
+```
+
+Login submit on Enter:
+```json
+{ "type": "input", "props": { "type": "password", "value": { "$bindState": "/login/password" } },
+  "on": { "submit": { "action": "login", "params": { ... } } }
+}
+```
+
+Color picker:
+```json
+{ "type": "input", "props": { "type": "color", "value": { "$bindState": "/form/color" } } }
+```
+
+## Constraints / Anti-patterns
+
+- **Use `type`, NOT `inputType`.** See [[@antipattern-input-type-name]].
+- **`label` is display-only** — does NOT auto-prepend the value.
+
+## Related concepts
+
+- [[@expression-bindstate]]
+- [[@concept-validation-checks]]
+- [[@concept-forms]]
+- [[@concept-identity-label-style]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § input`

package/docs/wiki/compiled/primitive-kanban-board.md

@@ -0,0 +1,30 @@
+---
+id: primitive-kanban-board
+title: `kanban-board`
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#kanban-board]
+---
+
+# `kanban-board`
+
+Board-style layout (columns of cards).
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `columns` | array | — | Column definitions |
+
+## Examples
+
+(Schema details limited in raw — see source-of-truth `react/src/primitives/`
+when needed.)
+
+## Related concepts
+
+- [[@primitive-table]]
+- [[@concept-where-to-look]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § kanban-board`

package/docs/wiki/compiled/primitive-line-chart.md

@@ -0,0 +1,33 @@
+---
+id: primitive-line-chart
+title: `line-chart`
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#line-chart]
+---
+
+# `line-chart`
+
+Line chart. Data is `[{ label, value }]`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | array/expression | — | `[{ label, value }]` |
+| `height` | number | `200` | Chart height |
+| `color` | string | — | Line color |
+
+## Examples
+
+```json
+{ "type": "line-chart", "props": { "data": { "$state": "/timeSeries" }, "color": { "$token": "colors.primary" } } }
+```
+
+## Related concepts
+
+- [[@primitive-bar-chart]]
+- [[@primitive-area-chart]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § line-chart`

package/docs/wiki/compiled/primitive-list.md

@@ -0,0 +1,34 @@
+---
+id: primitive-list
+title: `list` — list container
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#list]
+---
+
+# `list`
+
+List container. Use with `repeat` to iterate items.
+
+## Props
+
+No specific props besides common (`style`, `visible`, `permission`).
+
+## Examples
+
+```json
+"task-list": {
+  "type": "list",
+  "repeat": { "statePath": "/tasks", "key": "id" },
+  "children": ["task-row"]
+}
+```
+
+## Related concepts
+
+- [[@concept-repeat]]
+- [[@primitive-stack]] — frequently used as a list-style container too
+- [[@primitive-table]] — for tabular data
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § list`

package/docs/wiki/compiled/primitive-modal.md

@@ -0,0 +1,51 @@
+---
+id: primitive-modal
+title: `modal` — overlay dialog
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#modal, docs/consumer/reference-doc.md#modal--drawer-auto-visibility]
+---
+
+# `modal`
+
+Overlay dialog. **Engine-managed visibility** via `/ui/modals/{elementId}`.
+Use `openModal` / `closeModal` actions.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `visible` | — | — | Managed by engine — do NOT set |
+| `title` | string/expression | — | Modal header (rendered as h2) |
+
+## Examples
+
+```json
+"my-modal": {
+  "type": "modal",
+  "props": { "title": "Confirm" },
+  "children": ["content"]
+}
+```
+
+Open from a button:
+```json
+"on": { "press": { "action": "openModal", "params": { "id": "my-modal" } } }
+```
+
+## Constraints / Anti-patterns
+
+- **Don't set `visible`.** Engine binds visibility to `/ui/modals/{id}`.
+  See [[@antipattern-modal-drawer-visible]].
+- **In transactions, `closeModal` belongs in `before` phase** — not
+  rolled back on error.
+
+## Related concepts
+
+- [[@action-modal]]
+- [[@path-ui-modals-drawers]]
+- [[@concept-identity-surface]] — modals always use opaque `surface.modal`
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § modal`
+- `docs/consumer/reference-doc.md § Modal & Drawer Auto-Visibility`

package/docs/wiki/compiled/primitive-pie-chart.md

@@ -0,0 +1,32 @@
+---
+id: primitive-pie-chart
+title: `pie-chart`
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#pie-chart]
+---
+
+# `pie-chart`
+
+Pie chart. Optional `donut` style.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | array/expression | — | `[{ label, value, color? }]` |
+| `size` | number | — | Diameter in pixels |
+| `donut` | boolean | `false` | Donut style |
+
+## Examples
+
+```json
+{ "type": "pie-chart", "props": { "data": { "$state": "/breakdown" }, "size": 240, "donut": true } }
+```
+
+## Related concepts
+
+- [[@primitive-bar-chart]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § pie-chart`

package/docs/wiki/compiled/primitive-screen-outlet.md

@@ -0,0 +1,42 @@
+---
+id: primitive-screen-outlet
+title: `screen-outlet` — nested screen content slot
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#screen-outlet, docs/consumer/ai-context.md#appspec--navigation]
+---
+
+# `screen-outlet`
+
+Pseudo-primitive that renders the active nested screen content inside an
+AppSpec layout. Place it where the current screen should appear.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `style` | object | — | CSS styles |
+
+## Examples
+
+In an AppSpec layout (sidebar + outlet):
+```json
+"layout": {
+  "root": "shell",
+  "elements": {
+    "shell": { "type": "stack", "props": { "direction": "horizontal" }, "children": ["sidebar", "screen-outlet"] },
+    "sidebar": { "type": "box", "children": ["nav"] },
+    "screen-outlet": { "type": "screen-outlet", "style": { "flex": 1 } }
+  }
+}
+```
+
+## Related concepts
+
+- [[@concept-app-spec]]
+- [[@concept-navigation]]
+- [[@path-app-screens]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § screen-outlet`
+- `docs/consumer/ai-context.md § AppSpec & Navigation`

package/docs/wiki/compiled/primitive-screen.md

@@ -0,0 +1,43 @@
+---
+id: primitive-screen
+title: `screen` — top-level screen wrapper
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#screen]
+---
+
+# `screen`
+
+Top-level screen wrapper in AppSpec apps. RN-specific — provides the screen
+chrome (title bar, navigation integration).
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | string | — | Screen title |
+
+## Examples
+
+```json
+{ "type": "screen", "props": { "title": "Dashboard" }, "children": [...] }
+```
+
+Used as a platform-specific root:
+```json
+{
+  "root": { "$platform": { "web": "layout-web", "native": "layout-native" } },
+  "elements": {
+    "layout-native": { "type": "screen", "props": { "title": "Dashboard" }, "children": [...] }
+  }
+}
+```
+
+## Related concepts
+
+- [[@expression-platform]]
+- [[@primitive-screen-outlet]]
+- [[@concept-app-spec]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § screen`

package/docs/wiki/compiled/primitive-scroll.md

@@ -0,0 +1,33 @@
+---
+id: primitive-scroll
+title: `scroll` — scrollable container
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#scroll]
+---
+
+# `scroll`
+
+Scrollable container. Set `maxHeight` to enable scrolling.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `direction` | string | `vertical` | `vertical` or `horizontal` |
+| `maxHeight` | string/number | — | Max height (enables scroll) |
+| `className` | string | — | CSS class |
+
+## Examples
+
+```json
+{ "type": "scroll", "props": { "maxHeight": 400 }, "children": ["long-list"] }
+```
+
+## Related concepts
+
+- [[@primitive-stack]]
+- [[@primitive-table]] — already scrollable
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § scroll`

package/docs/wiki/compiled/primitive-select.md

@@ -0,0 +1,76 @@
+---
+id: primitive-select
+title: `select` — dropdown
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#select, docs/consumer/reference-doc.md#rule-117, docs/consumer/reference-doc.md#rule-225]
+---
+
+# `select`
+
+Dropdown picker. Options accept either string array or `[{ label, value }]`
+objects.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | expression | — | Bind via `$bindState` |
+| `options` | array | — | Strings or `[{ label, value }]` objects |
+| `placeholder` | string | — | Placeholder text |
+| `label` | string/expression | — | Field label |
+| `disabled` | boolean/expression | `false` | Disable |
+| `required` | boolean | `false` | Visual indicator |
+
+## Events
+
+`on.change`.
+
+## Examples
+
+Plain string options:
+```json
+{ "type": "select", "props": {
+  "options": ["Low", "Medium", "High"],
+  "value": { "$bindState": "/form/priority" }
+}}
+```
+
+Label/value pairs:
+```json
+{ "type": "select", "props": {
+  "options": [
+    { "label": "Low", "value": "low" },
+    { "label": "Medium", "value": "medium" },
+    { "label": "High", "value": "high" }
+  ],
+  "value": { "$bindState": "/form/priority" }
+}}
+```
+
+State-driven options:
+```json
+{ "type": "select", "props": {
+  "options": { "$state": "/presets/available" },
+  "value": { "$bindState": "/ui/currentPreset" }
+}}
+```
+
+## Notes
+
+- **Listbox portals to `document.body`** (rule 225) — the dropdown panel
+  uses `React.createPortal` so nested stacking contexts can't occlude it.
+  Position uses `position: fixed` synced via `getBoundingClientRect()`.
+- **Dropdown uses `surface.modal`, NOT `surface.card`** (rule 117) — needs
+  opaque background for readability across all surface modes (in
+  `outlined`, card has transparent bg).
+
+## Related concepts
+
+- [[@expression-bindstate]]
+- [[@concept-preset-dropdown-pattern]]
+- [[@concept-identity-surface]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § select`
+- `docs/consumer/reference-doc.md § rules 117, 225`