mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/pattern-tx-delete.md

@@ -0,0 +1,50 @@
+---
+id: pattern-tx-delete
+title: Pattern — DELETE transaction
+kind: pattern
+sources: [docs/consumer/ai-context.md#transactions-optimistic-updates, docs/consumer/reference-doc.md#delete--remove-item-from-list]
+---
+
+# Pattern — DELETE transaction
+
+Remove an item by id. No `onSuccess` (re-fetch would re-add a deleted row
+flashing into UI then back out).
+
+## Template
+
+```json
+{
+  "transaction": {
+    "before": [
+      { "action": "closeModal", "params": { "id": "{{CONFIRM_MODAL_ID}}" } }
+    ],
+    "optimistic": [
+      { "action": "setState", "params": {
+        "statePath": "{{ARRAY_PATH}}",
+        "value": { "$array": "remove", "source": { "$state": "{{ARRAY_PATH}}" },
+          "where": { "field": "id", "eq": { "$state": "/ui/deleteId" } }
+        }
+      }}
+    ],
+    "confirm": [
+      { "action": "fetch", "params": {
+        "method": "DELETE",
+        "url": { "$template": "{{API_URL}}?id=eq.${/ui/deleteId}" }
+      }}
+    ],
+    "onError": [
+      { "action": "showNotification", "params": { "type": "error", "message": "Could not delete {{ENTITY}}." } }
+    ]
+  }
+}
+```
+
+## Related concepts
+
+- [[@concept-transactions]]
+- [[@expression-array]] — `remove`
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Transactions → CRUD variations`
+- `docs/consumer/reference-doc.md § Transaction Templates → DELETE`

package/docs/wiki/compiled/pattern-tx-toggle.md

@@ -0,0 +1,45 @@
+---
+id: pattern-tx-toggle
+title: Pattern — TOGGLE transaction
+kind: pattern
+sources: [docs/consumer/ai-context.md#transactions-optimistic-updates, docs/consumer/reference-doc.md#toggle--flip-a-boolean-value]
+---
+
+# Pattern — TOGGLE transaction
+
+Flip a boolean value. **No `before` phase** — there's no modal to close.
+
+## Template
+
+```json
+{
+  "transaction": {
+    "optimistic": [
+      { "action": "setState", "params": {
+        "statePath": "{{BOOLEAN_PATH}}",
+        "value": { "$not": { "$state": "{{BOOLEAN_PATH}}" } }
+      }}
+    ],
+    "confirm": [
+      { "action": "fetch", "params": {
+        "method": "PATCH",
+        "url": { "$template": "{{API_URL}}?id=eq.{{ITEM_ID}}" },
+        "body": { "{{FIELD}}": { "$state": "{{BOOLEAN_PATH}}" } }
+      }}
+    ],
+    "onError": [
+      { "action": "showNotification", "params": { "type": "error", "message": "Could not update." } }
+    ]
+  }
+}
+```
+
+## Related concepts
+
+- [[@concept-transactions]]
+- [[@expression-and-or-not]] — `$not` for boolean toggle
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Transactions → CRUD variations`
+- `docs/consumer/reference-doc.md § Transaction Templates → TOGGLE`

package/docs/wiki/compiled/pattern-tx-update.md

@@ -0,0 +1,68 @@
+---
+id: pattern-tx-update
+title: Pattern — UPDATE transaction
+kind: pattern
+sources: [docs/consumer/ai-context.md#transactions-optimistic-updates, docs/consumer/reference-doc.md#update--edit-item-in-list]
+---
+
+# Pattern — UPDATE transaction
+
+Edit an existing item by id. **No `onSuccess` needed** — optimistic data is
+already correct; re-fetch causes a visible flash.
+
+## Template
+
+```json
+{
+  "transaction": {
+    "before": [
+      { "action": "closeModal", "params": { "id": "{{MODAL_ID}}" } }
+    ],
+    "optimistic": [
+      { "action": "setState", "params": {
+        "statePath": "{{ARRAY_PATH}}",
+        "value": { "$array": "replace", "source": { "$state": "{{ARRAY_PATH}}" },
+          "where": { "field": "id", "eq": { "$state": "/form/editId" } },
+          "value": {
+            "id": { "$state": "/form/editId" },
+            "{{FIELD_1}}": { "$state": "/form/{{FIELD_1}}" },
+            "{{FIELD_2}}": { "$state": "/form/{{FIELD_2}}" }
+          }
+        }
+      }}
+    ],
+    "confirm": [
+      { "action": "fetch", "params": {
+        "method": "PATCH",
+        "url": { "$template": "{{API_URL}}?id=eq.${/form/editId}" },
+        "headers": { "Prefer": "return=representation" },
+        "body": {
+          "{{FIELD_1}}": { "$state": "/form/{{FIELD_1}}" },
+          "{{FIELD_2}}": { "$state": "/form/{{FIELD_2}}" }
+        },
+        "target": "/tx/result"
+      }}
+    ],
+    "onError": [
+      { "action": "showNotification", "params": { "type": "error", "message": "Could not update {{ENTITY}}." } }
+    ]
+  }
+}
+```
+
+## Notes
+
+- **No `onSuccess`** — optimistic data is correct; re-fetch causes flash.
+- `optimistic`: `$array: "replace"` by id.
+- `confirm`: PATCH `?id=eq.${id}` (PostgREST URL filter).
+
+## Related concepts
+
+- [[@concept-transactions]]
+- [[@pattern-tx-create]]
+- [[@expression-array]] — `replace`
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Transactions → CRUD variations`
+- `docs/consumer/reference-doc.md § Transaction Templates → UPDATE`

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

@@ -0,0 +1,46 @@
+---
+id: primitive-accordion
+title: `accordion` — collapsible section
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#accordion, docs/consumer/reference-doc.md#rule-156]
+---
+
+# `accordion`
+
+Collapsible section with header + content. Optional `badge` indicator.
+Children render inside.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | string/expression | — | Header |
+| `defaultOpen` | boolean | `false` | Open on mount |
+| `badge` | string/number/boolean | — | Indicator next to title. `true` = solid dot, number/string = pill with text. Falsy hides |
+
+## Examples
+
+Reactive badge:
+```json
+{ "type": "accordion", "props": {
+  "title": "Modified fields",
+  "badge": { "$state": "/modified/section1" }
+}, "children": ["field1", "field2"] }
+```
+
+## Notes
+
+- **React Native glass support:** when `identity.surface === 'glass'`, RN
+  primitives (accordion, input, modal, select, textarea) wrap content in
+  `<BlurView>` from `expo-blur`. No spec changes needed.
+
+## Related concepts
+
+- [[@expression-state]]
+- [[@concept-identity-glass-rn]]
+- [[@concept-identity-surface]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § accordion`
+- `docs/consumer/reference-doc.md § rule 156`

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

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

package/docs/wiki/compiled/primitive-audio-player.md

@@ -0,0 +1,27 @@
+---
+id: primitive-audio-player
+title: `audio-player`
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#audio-player]
+---
+
+# `audio-player`
+
+Audio player.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `src` | string/expression | — | Audio URL |
+| `label` | string | — | Player label |
+
+## Examples
+
+```json
+{ "type": "audio-player", "props": { "src": { "$state": "/recording/url" }, "label": "Voice memo" } }
+```
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § audio-player`

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

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

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

@@ -0,0 +1,58 @@
+---
+id: primitive-box
+title: `box` — generic container
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#box, docs/consumer/reference-doc.md]
+---
+
+# `box`
+
+Generic container element. Common-prop carrier for `style`, `visible`, etc.
+The `surface` prop hooks into the identity system to consume per-type surface
+treatment (border, shadow, bg, borderRadius).
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | string | — | CSS class |
+| `surface` | string | — | `"card"` (stat cards, form cards), `"modal"` (overlays); omit for plain layout div |
+
+## Examples
+
+Card with identity-driven surface:
+```json
+"stat-card": {
+  "type": "box",
+  "props": { "surface": "card" },
+  "style": { "padding": 24 },
+  "children": ["value", "label"]
+}
+```
+
+Plain layout box (no surface treatment):
+```json
+"row": { "type": "box", "style": { "display": "flex", "gap": 12 }, "children": ["a", "b"] }
+```
+
+## Constraints / Anti-patterns
+
+- **Use `surface="card"` on card-like containers.** Without it, the box
+  ignores identity surface treatment and looks inconsistent (rule 40).
+- **Use `surface="modal"` for overlay panels** — see also
+  [[@antipattern-overflow-hidden-with-shadow]] when adding `box-shadow`
+  hover with overflow.
+- The `backgroundBlobs` prop was REMOVED in the current LayerBackground contract. App-level
+  background lives at `tokens.identity.background` — see
+  [[@antipattern-background-blobs-prop]].
+
+## Related concepts
+
+- [[@concept-identity-surface]]
+- [[@concept-element-properties]]
+- [[@pattern-identity-aware-spec]]
+- [[@concept-layer-background]] — app-level backgrounds
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § box`

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

@@ -0,0 +1,55 @@
+---
+id: primitive-button
+title: `button`
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#button]
+---
+
+# `button`
+
+Pressable button. Built-in CSS transitions — only add `hover`/`active`/`focus`
+for custom behavior beyond defaults.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | string/expression | — | Button text |
+| `variant` | string | — | `primary`, `secondary`, `destructive`, `ghost`, or custom from tokens |
+| `disabled` | boolean/expression | `false` | Disable |
+| `className` | string | — | CSS class |
+
+## Examples
+
+Primary action:
+```json
+{ "type": "button", "props": { "label": "Save", "variant": "primary" },
+  "on": { "press": { "action": "submitForm", "params": { "formId": "f", "url": "..." } } }
+}
+```
+
+Conditional label:
+```json
+{ "type": "button", "props": {
+  "label": { "$cond": { "$auth": "loading" }, "$then": "Signing in...", "$else": "Login" },
+  "disabled": { "$auth": "loading" }
+}}
+```
+
+## Notes
+
+- `variant` lives in `props`, not as a top-level field. See
+  [[@antipattern-element-variant-top-level]].
+- `tokens.identity.gradients.buttons = true` applies primary→accent
+  gradient automatically — see [[@concept-identity-gradients]].
+
+## Related concepts
+
+- [[@concept-component-variants]]
+- [[@concept-identity-surface]]
+- [[@concept-interactive-states]]
+- [[@primitive-touchable]] — invisible alternative
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § button`

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

@@ -0,0 +1,39 @@
+---
+id: primitive-camera
+title: `camera` — capture from camera
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#camera]
+---
+
+# `camera`
+
+Camera capture (photo or video).
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | string | — | Button label |
+| `accept` | string | — | `image/*` or `video/*` |
+| `disabled` | boolean/expression | `false` | Disable |
+
+## Events
+
+`on.capture`.
+
+## Examples
+
+```json
+{ "type": "camera", "props": { "accept": "image/*", "label": "Take photo" },
+  "on": { "capture": { "action": "uploadFile", "params": { "bucket": "photos", "target": "/form/photoUrl" } } }
+}
+```
+
+## Related concepts
+
+- [[@action-upload-file]]
+- [[@primitive-file-upload]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § camera`

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

@@ -0,0 +1,62 @@
+---
+id: primitive-checkbox
+title: `checkbox`
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#checkbox, docs/consumer/reference-doc.md#rule-123]
+---
+
+# `checkbox`
+
+Custom-rendered checkbox (div+SVG, not native browser). Surface-aware:
+adapts to identity surface treatment (bold=thick border, neo=inset shadow,
+flat=no border). Unchecked uses `t.surface.input`; checked fills with
+primary while preserving surface border.
+
+## 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": "checkbox", "props": {
+  "checked": { "$bindState": "/form/agreed" },
+  "label": "I agree"
+}}
+```
+
+In a list (per-row):
+```json
+"select-checkbox": {
+  "type": "checkbox",
+  "props": { "checked": { "$selection": "selected" } },
+  "on": { "change": { "action": "toggleSelection", "params": { "statePath": "/selectedIds", "value": { "$item": "id" } } } }
+}
+```
+
+## Constraints / Anti-patterns
+
+- **Use `checked`, NOT `value`.** See
+  [[@antipattern-checkbox-toggle-value]].
+- Focus uses `t.surface.inputFocus` which never includes
+  `backgroundColor` (prevents overwriting checked primary bg).
+
+## Related concepts
+
+- [[@expression-bindstate]]
+- [[@expression-selection]]
+- [[@primitive-toggle]]
+- [[@concept-identity-surface]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § checkbox`
+- `docs/consumer/reference-doc.md § rule 123`

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

@@ -0,0 +1,31 @@
+---
+id: primitive-divider
+title: `divider` — visual separator
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#divider]
+---
+
+# `divider`
+
+Renders a visual separator line.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `direction` | `"horizontal"` \| `"vertical"` | `"horizontal"` | Orientation |
+
+## Examples
+
+```json
+{ "type": "divider" }
+{ "type": "divider", "props": { "direction": "vertical" } }
+```
+
+## Related concepts
+
+- [[@primitive-spacer]] — invisible spacing
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § divider`

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

@@ -0,0 +1,44 @@
+---
+id: primitive-drawer
+title: `drawer` — side panel overlay
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#drawer]
+---
+
+# `drawer`
+
+Side-panel overlay. Engine-managed via `/ui/drawers/{elementId}`. Use
+`openDrawer` / `closeDrawer`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `visible` | — | — | Managed by engine — do NOT set |
+| `side` | string | `right` | `left` or `right` |
+| `width` | number | `300` | Width in pixels |
+
+## Examples
+
+```json
+"detail-drawer": {
+  "type": "drawer",
+  "props": { "side": "right", "width": 400 },
+  "children": ["drawer-content"]
+}
+```
+
+## Constraints / Anti-patterns
+
+- **Don't set `visible`** (rule 10) — see
+  [[@antipattern-modal-drawer-visible]].
+
+## Related concepts
+
+- [[@action-drawer]]
+- [[@path-ui-modals-drawers]]
+- [[@pattern-cross-screen-data-flow]] — typical drawer-with-row-detail use
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § drawer`

package/docs/wiki/compiled/primitive-file-upload.md

@@ -0,0 +1,65 @@
+---
+id: primitive-file-upload
+title: `file-upload`
+kind: primitive
+sources: [docs/consumer/ai-context-primitives.md#file-upload, docs/consumer/reference-doc.md#file-upload]
+---
+
+# `file-upload`
+
+God-primitive: preview, progress, validation, drop zone, auto/manual upload
+modes. Use the `uploadFile` action wired to `on.upload`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `accept` | string | `"*"` | MIME types or extensions (`image/*`, `.pdf,.docx`) |
+| `maxSize` | number | `10485760` | Max file size in bytes |
+| `multiple` | boolean | `false` | Allow multiple files |
+| `maxFiles` | number | `10` | Max file count |
+| `preview` | boolean | `true` | Show file previews |
+| `dropZone` | boolean | `false` | Drop-zone UI |
+| `autoUpload` | boolean | `true` | Upload immediately on selection |
+| `label` | string/expression | — | Button/zone label (supports `$i18n`) |
+| `disabled` | boolean/expression | `false` | Disable |
+
+## Events
+
+`on.upload`.
+
+## Examples
+
+Auto-upload avatar:
+```json
+{
+  "type": "file-upload",
+  "props": { "accept": "image/*", "maxSize": 5242880, "autoUpload": true },
+  "on": { "upload": { "action": "uploadFile", "params": { "bucket": "avatars", "target": "/form/avatarUrl" } } }
+}
+```
+
+Manual multi-file upload (in submit chain):
+```json
+{
+  "type": "file-upload",
+  "props": { "accept": ".pdf,.docx,.xlsx", "multiple": true, "autoUpload": false }
+}
+```
+
+## Constraints / Anti-patterns
+
+- **Always set `accept` and `maxSize`.** Defaults protect, explicit is safer.
+- **Read URLs from `target`, NOT `/ui/uploads/*`** (rule 55) — internal state.
+
+## Related concepts
+
+- [[@action-upload-file]]
+- [[@concept-storage-adapter]]
+- [[@pattern-file-upload-auto]] / [[@pattern-file-upload-manual]]
+- [[@path-uploads]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § file-upload`
+- `docs/consumer/reference-doc.md § File Upload`