mythik 0.0.1 → 0.1.0

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

@@ -0,0 +1,40 @@
+---
+id: primitive-signature
+title: `signature` — signature pad
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#signature]
+---
+
+# `signature`
+
+Canvas signature capture.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `width` | number | — | Canvas width |
+| `height` | number | — | Canvas height |
+| `lineColor` | string | — | Pen color |
+| `lineWidth` | number | — | Pen width |
+| `label` | string | — | Label text |
+
+## Events
+
+`on.sign`.
+
+## Examples
+
+```json
+{ "type": "signature", "props": { "width": 400, "height": 200, "lineColor": "#0F172A", "lineWidth": 2 },
+  "on": { "sign": { "action": "setState", "params": { "statePath": "/form/signature", "value": { "$state": "/ui/lastSignature" } } } }
+}
+```
+
+## Related concepts
+
+- [[@action-set-state]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § signature`

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

@@ -0,0 +1,48 @@
+---
+id: primitive-skeleton
+title: `skeleton` — loading placeholder
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#skeleton, docs/consumer/reference-doc.md#skeleton-primitive]
+---
+
+# `skeleton`
+
+Loading placeholder. Auto-skeleton activates automatically when the spec has
+`fetch` in `initialActions` + `/ui/loading: true` + empty target — no
+configuration needed (see [[@concept-skeleton-auto]]). Use the explicit
+`skeleton` primitive for custom loading layouts.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `"text" \| "circle" \| "rect"` | `"rect"` | Shape |
+| `width` | string/number | `"100%"` | Width (px or %) |
+| `height` | number | `16` | Height in px |
+| `count` | number | `1` | Number of shapes |
+| `gap` | number | `8` | Gap between shapes (when count > 1) |
+
+## Examples
+
+Manual skeleton list:
+```json
+{ "type": "skeleton", "props": {
+  "variant": "text", "width": "80%", "height": 16, "count": 3, "gap": 8
+}, "visible": { "$state": "/ui/loading" } }
+```
+
+## Constraints
+
+- Set `skeleton: false` on elements that show static content during
+  loading.
+- `autoSkeleton={false}` on `MythikRenderer` disables auto-skeleton entirely.
+
+## Related concepts
+
+- [[@concept-skeleton-auto]]
+- [[@concept-skeleton-manual]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § skeleton`
+- `docs/consumer/reference-doc.md § Skeleton Primitive`

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

@@ -0,0 +1,47 @@
+---
+id: primitive-slider
+title: `slider` — numeric range
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#slider, docs/consumer/reference-doc.md#rule-109]
+---
+
+# `slider`
+
+Numeric range slider with min/max/step.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | expression | — | Bind via `$bindState` |
+| `min` | number | `0` | Minimum value |
+| `max` | number | `100` | Maximum value |
+| `step` | number | `1` | Step increment |
+| `label` | string/expression | — | Label text (display-only — does NOT append value) |
+| `disabled` | boolean/expression | `false` | Disable |
+
+## Examples
+
+```json
+{ "type": "slider", "props": {
+  "value": { "$bindState": "/dna/roundness" },
+  "min": 0, "max": 100, "step": 1,
+  "label": { "$template": "Roundness: ${/dna/roundness}%" }
+}}
+```
+
+## Constraints / Anti-patterns
+
+- **`label` is display-only** — does NOT append the current value.
+  Use `$template` to include it (rule 109).
+
+## Related concepts
+
+- [[@expression-template]]
+- [[@expression-bindstate]]
+- [[@action-update-tokens]] — typical use-case pattern
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § slider`
+- `docs/consumer/reference-doc.md § rule 109`

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

@@ -0,0 +1,33 @@
+---
+id: primitive-spacer
+title: `spacer` — empty space
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#spacer]
+---
+
+# `spacer`
+
+Renders empty space. Use when `gap` on a parent stack/grid isn't expressive
+enough.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | number | — | Pixel size |
+| `direction` | `"vertical"` \| `"horizontal"` | — | Orientation |
+
+## Examples
+
+```json
+{ "type": "spacer", "props": { "size": 24, "direction": "vertical" } }
+```
+
+## Related concepts
+
+- [[@primitive-stack]] — `gap` is usually preferable
+- [[@primitive-divider]] — for visible separation
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § spacer`

package/docs/wiki/compiled/primitive-spatial-map.md

@@ -0,0 +1,26 @@
+---
+id: primitive-spatial-map
+title: Primitive - spatial-map
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md, docs/consumer/ai-context.md, docs/consumer/reference-doc.md]
+---
+
+# Primitive - spatial-map
+
+`spatial-map` is the generic SVG/data-first primitive for two-dimensional layouts: floor plans, seating maps, parking maps, warehouse locations, hospital beds, office maps, and similar domains.
+
+It knows geometry, zones, items, status, selection, edit policy, snap guides, and action dispatch. It does not encode restaurant-specific workflows.
+
+Core capabilities:
+
+- asymmetric viewBox layouts, not just square grids,
+- zones and items with rect/circle/ellipse/polygon/path shapes,
+- item selection through `/ui/selectedSpatialItem`,
+- zone selection through `/ui/selectedSpatialZone`,
+- JSON action dispatch for item/zone/canvas interactions,
+- edit mode with move, resize, rotate, keyboard controls, snap guides, and shape editing for polygon zones,
+- lazy change contexts under `/ui/spatialItemChange` and `/ui/spatialZoneChange`.
+
+Use `{ "$state": "/path" }` expressions for dynamic `items`, `zones`, `mode`, and `statusStyles`. Do not invent `*Path` prop aliases.
+
+Related: [[@concept-spatial-map-editor]], [[@concept-spatial-map-zones]], [[@concept-editor-sessions]].

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

@@ -0,0 +1,46 @@
+---
+id: primitive-stack
+title: `stack` — flexbox container
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#stack]
+---
+
+# `stack`
+
+Flexbox container. The default layout primitive for vertical/horizontal
+arrangements.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `direction` | string | `vertical` | `vertical` or `horizontal` |
+| `gap` | number | — | Space between children (px) |
+| `align` | string | — | Cross-axis: `start`, `center`, `end`, `stretch` |
+| `justify` | string | — | Main-axis: `start`, `center`, `end`, `between`, `around` |
+| `className` | string | — | CSS class |
+
+## Examples
+
+Vertical stack with consistent gap:
+```json
+{ "type": "stack", "props": { "direction": "vertical", "gap": 16 }, "children": ["row1", "row2"] }
+```
+
+Responsive direction:
+```json
+{ "type": "stack", "props": {
+  "direction": { "$breakpoint": { "sm": "vertical", "md": "horizontal" } },
+  "gap": { "$breakpoint": { "sm": 12, "md": 24 } }
+}}
+```
+
+## Related concepts
+
+- [[@primitive-grid]] — for 2D layouts
+- [[@expression-breakpoint]] — responsive
+- [[@primitive-spacer]] — manual spacing alternative
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § stack`

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

@@ -0,0 +1,127 @@
+---
+id: primitive-table
+title: `table`
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#table, docs/consumer/reference-doc.md#table-primitive-enhanced]
+---
+
+# `table`
+
+Feature-rich table — sorting, pagination, grouping, selection, formatting,
+column actions. Enable features with flags rather than composing from
+primitives.
+
+## Top-level props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | array/expression | — | Row data array |
+| `columns` | array | — | Column definitions (see below) |
+| `sorting` | object | — | `{ enabled, mode, default, state }` |
+| `pagination` | object | — | `{ enabled, pageSize, mode, state, totalItems }` |
+| `selection` | object | — | `{ enabled, mode, state }` |
+| `groupBy` | object | — | `{ field, header, footer, expanded, collapsible }` |
+| `stickyHeader` | boolean | `false` | Sticky table header |
+| `emptyState` | object | — | `{ icon, message }` |
+| `rowStyle` | object/expression | — | Per-row style |
+| `onRowClick` | action / array / function | — | Action(s) on row click; accepts spec ActionBinding(s) or a programmatic callback |
+| `headerStyle` | object | — | Header row style |
+| `cellStyle` | object | — | Default cell style |
+| `grandTotal` | boolean | `false` | Show grand total row |
+
+## Column props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `key` / `field` | string | — | Data field name (both accepted) |
+| `label` | string | — | Column header |
+| `width` | string | — | CSS grid: `fr` / `px` / `%` |
+| `align` | string | `left` | `left` / `center` / `right` |
+| `format` | string | — | `currency` / `number` / `percent` / `date` |
+| `formatOptions` | object | — | `{ currency, locale, decimals }` |
+| `sortable` | boolean | `true` | Allow sorting |
+| `visible` | boolean | `true` | Show/hide column |
+| `actions` | array | — | `[{ icon, color, onPress }]` |
+
+## Sorting / Pagination modes
+
+- **`client`** — sorts/slices internally.
+- **`server`** — writes `{ field, direction }` (sorting) or page number
+  (pagination) to `state` path. **`state` is required when mode is `server`.**
+
+## GroupBy
+
+`footer: "subtotal"` auto-sums numeric columns.
+
+## Row interactions
+
+`onRowClick` and `columns[].actions[].onPress` share the same row-context
+contract. Before dispatching the action chain, the framework writes the
+clicked row to `/ui/selectedRow`. Action params resolve lazily at click
+time, so `$state` / `$template` reads against `/ui/selectedRow/<key>` see
+the fresh row.
+
+## Examples
+
+Full table:
+```json
+{
+  "type": "table",
+  "props": {
+    "data": { "$state": "/items" },
+    "columns": [
+      { "key": "name", "label": "Name", "width": "2fr" },
+      { "key": "amount", "label": "Amount", "align": "right",
+        "format": "currency", "formatOptions": { "currency": "HNL", "locale": "es-HN" } }
+    ],
+    "sorting": { "enabled": true, "default": { "field": "amount", "direction": "desc" }, "mode": "client" },
+    "pagination": { "enabled": true, "pageSize": 20, "mode": "client" },
+    "selection": { "enabled": true, "mode": "multiple", "state": "/selectedIds" },
+    "stickyHeader": true,
+    "onRowClick": { "action": "openDrawer", "params": { "id": "detail" } }
+  }
+}
+```
+
+Column action with row context:
+```json
+"columns": [{
+  "id": "actions-col",
+  "actions": [{
+    "icon": "pencil-simple",
+    "onPress": [{
+      "action": "openModal",
+      "params": { "id": "edit-modal", "itemId": { "$state": "/ui/selectedRow/id" } }
+    }]
+  }]
+}]
+```
+
+Row click with row context in params:
+```json
+"onRowClick": [{
+  "action": "openDrawer",
+  "params": { "id": "detail", "itemId": { "$state": "/ui/selectedRow/id" } }
+}]
+```
+
+## Constraints / Anti-patterns
+
+- **`onRowClick` and column actions write the row to `/ui/selectedRow`
+  automatically** before dispatch (no `setState` needed). See
+  [[@path-ui-selected-row]].
+- **Use `/ui/selectedRow/<key>`, NOT `$row` literal** — see
+  [[@antipattern-row-literal]].
+- Row interaction params resolve at press time via `lazyActionPaths`. See
+
+## Related concepts
+
+- [[@path-ui-selected-row]]
+- [[@concept-expression-timing]]
+- [[@expression-format]]
+- [[@action-selection]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § Table`
+- `docs/consumer/reference-doc.md § Table Primitive (Enhanced)`

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

@@ -0,0 +1,52 @@
+---
+id: primitive-tabs
+title: `tabs`
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#tabs]
+---
+
+# `tabs`
+
+Tab navigation. Children render below tabs. Use `visible` conditions on
+children with `$state` on the active tab key to show/hide tab content.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | expression | — | Active tab key, bind via `$bindState` |
+| `items` | array | — | `[{ key, label, icon? }]` tab definitions |
+
+## Events
+
+`on.change`.
+
+## Examples
+
+```json
+{
+  "type": "tabs",
+  "props": {
+    "value": { "$bindState": "/ui/activeTab" },
+    "items": [
+      { "key": "overview", "label": "Overview", "icon": "chart-bar" },
+      { "key": "sales", "label": "Sales" }
+    ]
+  },
+  "children": ["overview-panel", "sales-panel"]
+},
+"overview-panel": {
+  "type": "box",
+  "visible": { "$state": "/ui/activeTab", "eq": "overview" },
+  "children": [...]
+}
+```
+
+## Related concepts
+
+- [[@expression-bindstate]]
+- [[@concept-visibility]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § tabs`

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

@@ -0,0 +1,59 @@
+---
+id: primitive-text
+title: `text` — text content
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#text]
+---
+
+# `text`
+
+Renders text content. `variant` controls the semantic tag and typography
+identity (heading h2, body p, caption span, label, mono code).
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `content` | string/expression | — | Text content |
+| `variant` | string | — | `heading` (h2), `body` (p), `caption` (span), `label` (label), `mono` (code) |
+| `className` | string | — | CSS class |
+
+## Examples
+
+```json
+{ "type": "text", "props": { "content": "Hello", "variant": "heading" } }
+```
+
+Interpolated content:
+```json
+{ "type": "text", "props": { "content": { "$template": "Hello, ${/user/name}!" } } }
+```
+
+Conditional color:
+```json
+{ "type": "text",
+  "props": { "content": "Status" },
+  "style": { "color": { "$cond": { "$state": "/ok" }, "$then": "green", "$else": "red" } }
+}
+```
+
+## Constraints
+
+- Inherits color from the parent surface container (`color: 'inherit'`)
+  — surface containers set `color: c.text` so text adapts to dark/colored
+  schemes automatically. See [[@concept-identity-color-scheme]].
+- Heading variant participates in
+  [[@concept-identity-typography-hierarchy]],
+  [[@concept-identity-text-decoration]], and
+  [[@concept-identity-gradients]].
+
+## Related concepts
+
+- [[@expression-template]]
+- [[@expression-format]]
+- [[@expression-i18n]]
+- [[@concept-identity-typography-hierarchy]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § text`

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

@@ -0,0 +1,44 @@
+---
+id: primitive-textarea
+title: `textarea` — multi-line text input
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#textarea]
+---
+
+# `textarea`
+
+Multi-line text input.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | expression | — | Bind via `$bindState` |
+| `placeholder` | string/expression | — | Placeholder |
+| `label` | string/expression | — | Field label |
+| `rows` | number | `3` | Visible rows |
+| `disabled` | boolean/expression | `false` | Disable |
+| `readOnly` | boolean | `false` | Read-only |
+
+## Events
+
+`on.change`.
+
+## Examples
+
+```json
+{ "type": "textarea", "props": {
+  "value": { "$bindState": "/form/description" },
+  "label": "Description",
+  "rows": 6
+}}
+```
+
+## Related concepts
+
+- [[@expression-bindstate]]
+- [[@primitive-input]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § textarea`

package/docs/wiki/compiled/primitive-toast-container.md

@@ -0,0 +1,44 @@
+---
+id: primitive-toast-container
+title: `toast-container` — toast positioning override
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#toast-container, docs/consumer/reference-doc.md#toast-notifications]
+---
+
+# `toast-container`
+
+Override default toast positioning/duration. **Optional** — toasts render
+automatically without this element using top-right defaults.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `store` | string | — | State path for toast data |
+| `position` | string | `"top-right"` | `top-right`/`top-left`/`top-center`/`bottom-right`/`bottom-left`/`bottom-center` |
+| `duration` | number | `4000` | Default auto-dismiss time in ms |
+| `maxVisible` | number | `5` | Max toasts shown at once |
+| `offset` | number | `24` | Distance from viewport edge |
+| `gap` | number | `8` | Space between toasts |
+
+## Examples
+
+```json
+"notifications": {
+  "type": "toast-container",
+  "props": {
+    "position": "bottom-center",
+    "duration": 6000,
+    "maxVisible": 3
+  }
+}
+```
+
+## Related concepts
+
+- [[@action-show-notification]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § toast-container`
+- `docs/consumer/reference-doc.md § Toast Notifications`

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

@@ -0,0 +1,46 @@
+---
+id: primitive-toggle
+title: `toggle` — boolean switch
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#toggle]
+---
+
+# `toggle`
+
+Boolean switch (visual switch, not checkbox). Bind via `checked`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `checked` | boolean/expression | — | Bind via `$bindState`. **NOT `value`** |
+| `label` | string/expression | — | Label text |
+| `disabled` | boolean/expression | `false` | Disable |
+
+## Events
+
+`on.change`.
+
+## Examples
+
+```json
+{ "type": "toggle", "props": {
+  "checked": { "$bindState": "/preferences/darkMode" },
+  "label": "Dark Mode"
+}}
+```
+
+## Constraints / Anti-patterns
+
+- **Use `checked`, NOT `value`.** See
+  [[@antipattern-checkbox-toggle-value]].
+
+## Related concepts
+
+- [[@primitive-checkbox]]
+- [[@expression-bindstate]]
+- [[@action-toggle-theme]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § toggle`

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

@@ -0,0 +1,40 @@
+---
+id: primitive-touchable
+title: `touchable` — invisible tap area
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#touchable]
+---
+
+# `touchable`
+
+Invisible tap area. Use when wrapping arbitrary content with press behavior
+(rows, custom cards, image overlays).
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | string | — | CSS class |
+
+## Events
+
+`on.press`.
+
+## Examples
+
+```json
+{ "type": "touchable",
+  "style": { "padding": 12 },
+  "on": { "press": { "action": "openModal", "params": { "id": "edit" } } },
+  "children": ["card-content"]
+}
+```
+
+## Related concepts
+
+- [[@primitive-button]] — when you need a label
+- [[@concept-interactive-states]] — typical hover/active pairing
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § touchable`