mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/expression-date.md

@@ -0,0 +1,66 @@
+---
+id: expression-date
+title: `$date` — date operations
+kind: expression
+sources: [docs/consumer/ai-context.md#math--data, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$date` — date operations
+
+Operations on dates. `now`, `today`, `age`, `diff`, `format`, `add`. Units:
+`days`, `months`, `years`, `hours`, `minutes`. Patterns: `short`, `long`,
+`numeric`, `time`, `datetime`.
+
+## Shape / Signature
+
+```json
+{ "$date": "now" }
+{ "$date": "today" }
+{ "$date": "age", "from": <expr> }
+{ "$date": "diff", "from": <expr>, "to": <expr>, "unit": "days" }
+{ "$date": "format", "value": <expr>, "pattern": "short" }
+{ "$date": "add", "value": <expr>, "amount": 7, "unit": "days" }
+```
+
+## Examples
+
+Current timestamp:
+```json
+{ "$date": "now" }
+```
+
+Patient age:
+```json
+{ "$date": "age", "from": { "$state": "/patient/birthDate" } }
+```
+
+Days between two dates:
+```json
+{ "$date": "diff", "from": { "$state": "/start" }, "to": { "$state": "/end" }, "unit": "days" }
+```
+
+Format a date:
+```json
+{ "$date": "format", "value": { "$state": "/createdAt" }, "pattern": "short" }
+```
+
+Date arithmetic — 7 days from now:
+```json
+{ "$date": "add", "value": { "$date": "now" }, "amount": 7, "unit": "days" }
+```
+
+## Constraints / Anti-patterns
+
+- `now` returns the current instant; `today` returns midnight of the
+  current day in the active locale.
+- For currency-style number formatting, use [[@expression-format]].
+
+## Related concepts
+
+- [[@expression-format]] — formatting dates inside `$format`
+- [[@expression-math]] — combine with arithmetic
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → Math & Data → $date`
+- `docs/consumer/reference-doc.md § Expression Types → $date`

package/docs/wiki/compiled/expression-format.md

@@ -0,0 +1,79 @@
+---
+id: expression-format
+title: `$format` — value formatting
+kind: expression
+sources: [docs/consumer/ai-context.md#math--data, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$format` — value formatting
+
+Formats values for display. Operations: `currency`, `number`, `percent`,
+`phone`, `uppercase`, `lowercase`, `capitalize`, `truncate`. Extended options
+for `currency` and `number` (locale, notation, signDisplay, useGrouping).
+
+## Shape / Signature
+
+```json
+{ "$format": "<op>", "value": <expr>, "<...op-specific>": ... }
+```
+
+## Examples
+
+Currency:
+```json
+{ "$format": "currency", "value": { "$state": "/price" }, "currency": "USD" }
+{ "$format": "currency", "value": 1234, "currency": "HNL", "locale": "es-HN" }
+```
+
+Number with options:
+```json
+{ "$format": "number", "value": 1234.5, "decimals": 2 }
+{ "$format": "number", "value": 1234567, "notation": "compact" }
+{ "$format": "number", "value": -500, "signDisplay": "always", "decimals": 2 }
+```
+
+Percent:
+```json
+{ "$format": "percent", "value": 0.75 }
+```
+
+Strings:
+```json
+{ "$format": "uppercase", "value": { "$state": "/name" } }
+{ "$format": "capitalize", "value": "hello world" }
+{ "$format": "truncate", "value": "long text...", "length": 20 }
+```
+
+Phone (display mask, stores raw digits):
+```json
+{ "$format": "phone", "value": { "$state": "/phone" } }
+```
+
+## Extended options for currency / number
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `locale` | string \| Expression | context locale | Override locale per-field |
+| `notation` | `"standard"` \| `"compact"` \| `"scientific"` \| `"engineering"` | `"standard"` | Number notation style |
+| `signDisplay` | `"auto"` \| `"always"` \| `"exceptZero"` \| `"negative"` | `"auto"` | Sign display mode |
+| `useGrouping` | boolean | `true` | Thousands separator on/off |
+
+All optional — existing specs work unchanged.
+
+## Constraints / Anti-patterns
+
+- Use `$format` only in props/derive — not in transactions or `$template`
+  (see [[@concept-expression-contexts]]).
+- For per-locale formatting, set `locale` (e.g. `"es-HN"`) — overrides the
+  context locale per-field.
+
+## Related concepts
+
+- [[@expression-math]]
+- [[@expression-date]]
+- [[@concept-export-action]] — same column-format options
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → Math & Data → $format`
+- `docs/consumer/reference-doc.md § Expression Types → $format`

package/docs/wiki/compiled/expression-group.md

@@ -0,0 +1,84 @@
+---
+id: expression-group
+title: `$group` — group context (inside groupBy)
+kind: expression
+sources: [docs/consumer/ai-context.md#group--selection-inside-repeat, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$group` — group context
+
+Inside a `repeat` with `groupBy` (or `groupKey` + `groupItems`), `$group`
+reads aggregates over the current group. Operations: `key`, `count`, `index`,
+`items`, `sum`, `avg`, `min`, `max`, plus dot-notation for pre-grouped
+objects.
+
+## Shape / Signature
+
+```json
+{ "$group": "key" }
+{ "$group": "count" }
+{ "$group": "sum", "field": "amount" }
+{ "$group": "subtotal.total" }
+```
+
+| Op | Returns | Available in |
+|---|---|---|
+| `key` | Group key value (e.g., "Institution A") | groupHeader, groupFooter |
+| `count` | Number of items in group | groupHeader, groupFooter |
+| `index` | Group index (0-based) | groupHeader, groupFooter |
+| `items` | Array of items in group | groupHeader, groupFooter |
+| `sum` | Σ field across group items | groupHeader, groupFooter |
+| `avg` | Average of field | groupHeader, groupFooter |
+| `min` | Minimum of field | groupHeader, groupFooter |
+| `max` | Maximum of field | groupHeader, groupFooter |
+| `dot.path` | Pre-grouped object access | groupHeader, groupFooter |
+
+## Examples
+
+Group header showing key + count:
+```json
+"category-header": {
+  "type": "text",
+  "props": {
+    "content": {
+      "$let": {
+        "k": { "$group": "key" },
+        "c": { "$group": "count" }
+      },
+      "$in": { "$template": "${k} (${c})" }
+    }
+  }
+}
+```
+
+Group footer subtotal:
+```json
+"category-subtotal": {
+  "type": "text",
+  "props": {
+    "content": { "$format": "currency", "value": { "$group": "sum", "field": "amount" } }
+  }
+}
+```
+
+Pre-grouped data dot access:
+```json
+{ "$group": "subtotal.total" }
+```
+
+## Constraints / Anti-patterns
+
+- **Only valid inside `repeat` with `groupBy` or `groupKey`.** Throws an
+  error if used outside.
+- For per-row data inside the repeat children, use [[@expression-item-index]].
+
+## Related concepts
+
+- [[@concept-repeat-grouped]] — full groupBy/groupKey contract
+- [[@expression-item-index]] — per-row context
+- [[@expression-array]] — equivalent ops on plain arrays
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → Group & Selection`
+- `docs/consumer/reference-doc.md § Expression Types → $group`

package/docs/wiki/compiled/expression-i18n.md

@@ -0,0 +1,53 @@
+---
+id: expression-i18n
+title: `$i18n` — translation key
+kind: expression
+sources: [docs/consumer/ai-context.md#values--formatting, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$i18n` — translation key
+
+`$i18n` resolves a translation key for the active locale. Optional `args`
+object passes interpolation values to the translation entry.
+
+## Shape / Signature
+
+```json
+{ "$i18n": "key" }
+{ "$i18n": "key", "args": { "name": <expr>, ... } }
+```
+
+## Examples
+
+Simple key:
+```json
+{ "type": "text", "props": { "content": { "$i18n": "patient.name" } } }
+```
+
+With args:
+```json
+{ "$i18n": "welcome", "args": { "name": { "$state": "/user/name" } } }
+```
+
+Auth screen with i18n:
+```json
+"title": { "type": "text", "props": { "content": { "$i18n": "auth.login" } } }
+```
+
+## Constraints / Anti-patterns
+
+- Translations live in `appSpec.translations.<locale>.<key>` (or screen-level
+  for screen-spec apps).
+- Active locale comes from `/preferences/locale` — toggle via `setLocale`
+  action.
+- Missing keys produce undefined / fallback per host-app config.
+
+## Related concepts
+
+- [[@action-set-locale]] — change active locale
+- [[@concept-app-spec]] — `translations` field in AppSpec
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → Values & Formatting → $i18n`
+- `docs/consumer/reference-doc.md § Expression Types → $i18n`

package/docs/wiki/compiled/expression-item-index.md

@@ -0,0 +1,72 @@
+---
+id: expression-item-index
+title: `$item` / `$index` — repeat context
+kind: expression
+sources: [docs/consumer/ai-context.md#expressions, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$item` / `$index` — repeat context (read-only)
+
+Inside a `repeat` block, `$item` reads a field from the current item; `$index`
+returns the position. Works in `props`, `style`, `visible`, and `on` (event
+params are pre-resolved with item context). For two-way binding to a current
+item field, use [[@expression-binditem]].
+
+## Shape / Signature
+
+```json
+{ "$item": "<fieldName>" }
+{ "$item": "" }       // returns the whole item
+{ "$index": true }
+```
+
+## Examples
+
+Display item field:
+```json
+{ "type": "text", "props": { "content": { "$item": "title" } } }
+```
+
+Whole item passed to a template prop:
+```json
+{ "type": "row-template", "props": { "row": { "$item": "" } } }
+```
+
+Conditional style based on item priority:
+```json
+"style": { "color": {
+  "$cond": { "$item": "priority", "eq": "urgent" },
+  "$then": "#EF4444",
+  "$else": "#22C55E"
+}}
+```
+
+Index in a label:
+```json
+{ "$let": { "n": { "$index": true } }, "$in": { "$template": "Row #${n}" } }
+```
+
+## Constraints / Anti-patterns
+
+- **`$item` in `$template` does NOT work directly.** Capture in `$let`
+  first — see [[@concept-expression-contexts]] and [[@expression-let-ref]].
+- **`$item` in transaction phases does NOT resolve.** Capture row data
+  via `setState` before the transaction fires.
+- **`$item` only inside `repeat`.** Outside `repeat` returns undefined.
+- For event-handler params inside `repeat`, the binding wrapper is
+  eagerly resolved so `$item` binds to the row being rendered. Inner
+  `$state`/`$template` inside params stay lazy.
+
+## Related concepts
+
+- [[@expression-binditem]] — two-way binding equivalent
+- [[@expression-let-ref]] — bridge `$item` into `$template`
+- [[@concept-repeat]] — `repeat` config
+- [[@concept-expression-contexts]] — where `$item` resolves
+- [[@concept-expression-timing]] — eager vs lazy semantics inside repeat
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → State & Binding`
+- `docs/consumer/ai-context-patterns.md § Expression Resolution Contexts`
+- `docs/consumer/reference-doc.md § Expression Types → $item / $index`

package/docs/wiki/compiled/expression-let-ref.md

@@ -0,0 +1,87 @@
+---
+id: expression-let-ref
+title: `$let` / `$ref` — named bindings
+kind: expression
+sources: [docs/consumer/ai-context.md#named-bindings, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$let` / `$ref` — named bindings
+
+`$let` defines named bindings; `$in` is the expression that uses them.
+References use `$ref`. Use to define a value once and reference it multiple
+times — particularly useful when `$item` or a complex expression must be
+captured for use in `$template`.
+
+## Shape / Signature
+
+Object form (no inter-binding refs):
+```json
+{
+  "$let": { "name1": <expr>, "name2": <expr> },
+  "$in": <expr-using-$ref>
+}
+```
+
+Array form (preserves order — use when stored in JSONB):
+```json
+{
+  "$let": [
+    ["filtered", { "$array": "filter", ... }],
+    ["count", { "$array": "count", "source": { "$ref": "filtered" } }]
+  ],
+  "$in": { "$ref": "count" }
+}
+```
+
+## Examples
+
+Capture `$item` for `$template` (the most common use):
+```json
+{
+  "$let": { "x": { "$item": "name" } },
+  "$in": { "$template": "Editing: ${x}" }
+}
+```
+
+Multi-step computation:
+```json
+{
+  "$let": {
+    "total": { "$array": "count", "source": { "$state": "/items" } },
+    "label": { "$template": "${total} items" }
+  },
+  "$in": { "$ref": "label" }
+}
+```
+
+In a composite template:
+```json
+"stat-card": {
+  "type": "text",
+  "defaults": { "label": "Count", "value": 0 },
+  "props": {
+    "content": {
+      "$let": { "l": { "$prop": "label" }, "v": { "$prop": "value" } },
+      "$in": { "$template": "${l}: ${v}" }
+    }
+  }
+}
+```
+
+## Constraints / Anti-patterns
+
+- **Use array form when storing in JSONB.** Object key order is not
+  preserved by JSONB — if bindings reference each other via `$ref`, use
+  the array form to guarantee evaluation order. See rule 4.
+- Object form is fine when bindings don't reference each other.
+
+## Related concepts
+
+- [[@expression-prop]] — `$prop` inside templates needs `$let` to bridge into `$template`
+- [[@expression-template]] — primary consumer of `$let` bindings
+- [[@expression-item-index]] — `$item` doesn't work inside `$template` directly
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → Named Bindings`
+- `docs/consumer/reference-doc.md § Expression Types → $let / $ref`

package/docs/wiki/compiled/expression-math.md

@@ -0,0 +1,67 @@
+---
+id: expression-math
+title: `$math` — arithmetic operations
+kind: expression
+sources: [docs/consumer/ai-context.md#math--data, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$math` — arithmetic operations
+
+Arithmetic over expressions. Operations: `add`, `subtract`, `multiply`, `divide`,
+`round`, `floor`, `ceil`, `abs`, `min`, `max`, `mod`. Undefined args coerce to
+`0` (prevents NaN propagation).
+
+## Shape / Signature
+
+Binary/n-ary operations use `args`:
+```json
+{ "$math": "add", "args": [<expr>, <expr>, ...] }
+```
+
+Unary operations use `value`:
+```json
+{ "$math": "round", "value": 3.14159, "decimals": 2 }
+```
+
+## Examples
+
+Multiply two state values:
+```json
+{ "$math": "multiply", "args": [{ "$state": "/price" }, { "$state": "/qty" }] }
+```
+
+Calculate average price (used in derive):
+```json
+"/stats/avg": {
+  "$math": "divide",
+  "args": [
+    { "$array": "sum", "source": { "$state": "/items" }, "field": "price" },
+    { "$array": "count", "source": { "$state": "/items" } }
+  ]
+}
+```
+
+Round to 2 decimals:
+```json
+{ "$math": "round", "value": { "$state": "/total" }, "decimals": 2 }
+```
+
+## Constraints / Anti-patterns
+
+- **Undefined args → 0.** If a state path doesn't exist yet,
+  `$math` treats it as `0`. Prevents NaN in the UI but masks data
+  loading order issues — use `visible` conditions or
+  `initialActions` to ensure data exists before rendering.
+- The spec author is responsible for data availability; `$math` is
+  responsible for never producing NaN.
+
+## Related concepts
+
+- [[@expression-array]] — `sum`, `count`, etc.
+- [[@expression-format]] — currency/number formatting after math
+- [[@concept-derive]] — typical `$math` consumer
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → Math & Data → $math`
+- `docs/consumer/reference-doc.md § Expression Types → $math`

package/docs/wiki/compiled/expression-platform.md

@@ -0,0 +1,68 @@
+---
+id: expression-platform
+title: `$platform` — cross-platform value
+kind: expression
+sources: [docs/consumer/ai-context.md#responsive--cross-platform, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$platform` — cross-platform value
+
+`$platform` resolves to different values based on the current platform
+(`web`, `ios`, `android`). Reads `/ui/device/platform` from state.
+**`native` is an alias** matching ios + android. Specific platform keys take
+priority over `native`.
+
+## Shape / Signature
+
+```json
+{ "$platform": { "web": <value>, "native": <value>, "ios"?: <value>, "android"?: <value> } }
+```
+
+## Examples
+
+Platform-specific styling:
+```json
+"style": { "backdropFilter": { "$platform": { "web": "blur(24px)", "native": null } } }
+```
+
+Different layouts per platform (root-level):
+```json
+{
+  "root": { "$platform": { "web": "layout-web", "native": "layout-native" } },
+  "elements": {
+    "layout-web": { "type": "stack", "style": { "backdropFilter": "blur(24px)" } },
+    "layout-native": { "type": "screen", "props": { "title": "Dashboard" } },
+    "shared-form": { "type": "stack", "children": ["..."] }
+  }
+}
+```
+
+Platform-specific overrides for ios:
+```json
+{ "$platform": { "web": "hover-card", "ios": "ios-card", "android": "android-card" } }
+```
+
+## When to use `$platform` vs `$breakpoint`
+
+| Use | Pick |
+|---|---|
+| Same component, different sizing (columns, gaps, padding) | [[@expression-breakpoint]] |
+| Different implementation per platform (CSS blur vs BlurView, hover vs press, web sidebar vs native tabs) | `$platform` |
+
+## Constraints / Anti-patterns
+
+- **If no key matches, resolves to `undefined`.** Always provide keys for
+  all target platforms (or include `native` as fallback).
+- Root-level `$platform` enables platform-divergent layouts while
+  state/initialActions/forms remain shared — only presentation branches.
+
+## Related concepts
+
+- [[@expression-breakpoint]] — responsive layout (different axis)
+- [[@path-ui-device]] — auto-tracked `/ui/device/platform`
+- [[@concept-identity-glass-rn]] — RN BlurView wrapping for `glass` surface
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → Responsive & Cross-Platform → $platform`
+- `docs/consumer/reference-doc.md § Expression Types → $platform`

package/docs/wiki/compiled/expression-prop.md

@@ -0,0 +1,89 @@
+---
+id: expression-prop
+title: `$prop` — template/element-def prop reference
+kind: expression
+sources: [docs/consumer/ai-context.md#expressions, docs/consumer/ai-context-custom-elements.md#elementrendernode, docs/consumer/ai-context-runtime-semantics.md#14-prop-cascade-layer-3-custom-elements]
+---
+
+# `$prop` — template/element-def prop reference
+
+`$prop` references a prop passed to a template OR a custom element. Inside a
+template's body or a custom element's `render` tree, `$prop` reads from the
+nearest enclosing element's merged props (consumer props + defaults).
+
+## Shape / Signature
+
+```json
+{ "$prop": "<propName>" }
+```
+
+## Examples
+
+Inside a template body:
+```json
+"templates": {
+  "monetary-col": {
+    "type": "text",
+    "defaults": { "color": "#0F172A", "currency": "HNL" },
+    "props": {
+      "content": { "$format": "currency", "value": { "$prop": "value" }, "currency": { "$prop": "currency" } }
+    },
+    "style": { "color": { "$prop": "color" } }
+  }
+}
+```
+
+Inside a custom element render tree:
+```json
+{
+  "type": "rating-stars",
+  "props": { "max": { "type": "number", "default": 5 } },
+  "render": {
+    "type": "icon",
+    "props": { "name": "star" },
+    "repeat": { "count": { "$prop": "max" } }
+  }
+}
+```
+
+Action-chain prop (Layer 3 custom element):
+```json
+"render": {
+  "type": "touchable",
+  "on": { "press": { "$prop": "onSelect" } }
+}
+```
+
+## Resolution scope
+
+`$prop` is **nearest-enclosing-scoped**:
+- Inside a template: resolves against THAT template's merged props.
+- Inside a custom element render tree: resolves against THAT custom
+  element's merged props.
+- Nesting a custom element pushes a new prop context — outer's props are
+  shadowed, NOT inherited.
+
+## Constraints / Anti-patterns
+
+- **`$prop` in `$template` needs `$let` to bridge.** `$template` references
+  `${name}` only resolve `$let` bindings. Use `$let` to capture `$prop` first.
+- **Pass values explicitly when nested access is needed.** Don't assume
+  `$prop` reaches into outer custom-element props.
+- `$prop` is resolved **eagerly** at each cascade level with the consumer's
+  values. Inner `$state`/`$template` inside a consumer-supplied `$prop`
+  action chain stay LAZY (resolved at dispatch).
+
+## Related concepts
+
+- [[@concept-prop-cascade]] — full cascade contract
+- [[@concept-templates]] — template prop usage
+- [[@concept-custom-elements]] — Layer 3 authoring
+- [[@concept-custom-element-prop-cascade]] — nesting semantics
+- [[@concept-custom-element-action-props]] — action-chain props
+- [[@expression-let-ref]] — bridge `$prop` into `$template`
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → State & Binding → $prop`
+- `docs/consumer/ai-context-custom-elements.md` (full)
+- `docs/consumer/ai-context-runtime-semantics.md § 1.4`