@rippling/pebble-sdui-web 0.26.1 → 0.26.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -32,9 +32,9 @@ export interface TemplateRef {
32
32
  }
33
33
  /**
34
34
  * Valid interpolation value inside a $template tagged template.
35
- * Accepts any expression ref that can be stringified at runtime.
35
+ * Runtime templates resolve state paths, not repeat item or index refs.
36
36
  */
37
- export type TemplateInterpolation = StateRef<unknown> | ItemRef<unknown> | IndexRef | null | undefined;
37
+ export type TemplateInterpolation = StateRef<unknown> | null | undefined;
38
38
  /** Conditional expression with typed branches. Uses T directly to avoid circular PropValue recursion. */
39
39
  export interface CondRef<T> {
40
40
  readonly $cond: unknown;
@@ -1,2 +1,2 @@
1
- "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function I($,w){const p={},m=new Map,h=new WeakMap,b=new WeakSet,f=new Set;let S=0;function t(n,s=new WeakSet){var l;const o=n;if(s.has(o))return;s.add(o);const e=n;if(e.id!==void 0){const r=m.get(e.id);if(r&&r!==o)throw new Error(`Duplicate element id: ${e.id}`);m.set(e.id,o),f.add(e.id)}(l=e.children)==null||l.forEach(r=>t(r,s)),Object.values(e.slots??{}).forEach(r=>r.forEach(u=>t(u,s)))}function a(){let n;do n=`element-${S}`,S+=1;while(f.has(n));return f.add(n),n}function c(n){const s=n,o=h.get(s);if(o)return o;const l=n.id??a();return h.set(s,l),l}function d(n){const s=n,o=c(n);if(b.has(s))return o;b.add(s);const e=n,l=e.children?e.children.map(u=>d(u)):[],r={type:e.type,props:e.props,children:l};return e.slots&&(r.slots=Object.fromEntries(Object.entries(e.slots).map(([u,g])=>[u,g.map(x=>d(x))]))),e.visible!==void 0&&(r.visible=e.visible),e.on&&(r.on=e.on),e.watch&&(r.watch=e.watch),e.repeat&&(r.repeat=e.repeat),p[o]=r,o}t($);const i=d($);return JSON.parse(JSON.stringify({root:i,elements:p,state:w}))}function E($){const w=$.state;function p(t){return{$state:t}}function m(t){return{$bindState:t}}function h(t,...a){let c=t[0];for(let d=0;d<a.length;d+=1){const i=a[d];!i||typeof i!="object"?c+="":"$state"in i?c+=`\${${i.$state}}`:"$item"in i?c+=`\${$item.${i.$item}}`:"$index"in i&&(c+="${$index}"),c+=t[d+1]}return{$template:c}}function b(t,a,c){return{$cond:t,$then:a,$else:c}}function f(t,a){return[{statePath:t,key:a},{$(i){return{$item:i}},$bind(i){return{$bindItem:i}},$index(){return{$index:!0}}}]}function S(t){return I(t,w)}return{$state:p,$bindState:m,$template:h,$cond:b,repeat:f,render:S}}exports.createSpec=E;exports.renderElementTree=I;
1
+ "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function g(p,S){const $={},m=new Map,h=new WeakMap,b=new WeakSet,u=new Set;let w=0;function t(n,c=new WeakSet){var l;const o=n;if(c.has(o))return;c.add(o);const e=n;if(e.id!==void 0){const r=m.get(e.id);if(r&&r!==o)throw new Error(`Duplicate element id: ${e.id}`);m.set(e.id,o),u.add(e.id)}(l=e.children)==null||l.forEach(r=>t(r,c)),Object.values(e.slots??{}).forEach(r=>r.forEach(f=>t(f,c)))}function a(){let n;do n=`element-${w}`,w+=1;while(u.has(n));return u.add(n),n}function s(n){const c=n,o=h.get(c);if(o)return o;const l=n.id??a();return h.set(c,l),l}function d(n){const c=n,o=s(n);if(b.has(c))return o;b.add(c);const e=n,l=e.children?e.children.map(f=>d(f)):[],r={type:e.type,props:e.props,children:l};return e.slots&&(r.slots=Object.fromEntries(Object.entries(e.slots).map(([f,E])=>[f,E.map(I=>d(I))]))),e.visible!==void 0&&(r.visible=e.visible),e.on&&(r.on=e.on),e.watch&&(r.watch=e.watch),e.repeat&&(r.repeat=e.repeat),$[o]=r,o}t(p);const i=d(p);return JSON.parse(JSON.stringify({root:i,elements:$,state:S}))}function y(p){const S=p.state;function $(t){return{$state:t}}function m(t){return{$bindState:t}}function h(t,...a){let s=t[0];for(let d=0;d<a.length;d+=1){const i=a[d];if(i==null)s+="";else if(typeof i=="object"&&"$state"in i&&typeof i.$state=="string")s+=`\${${i.$state}}`;else throw new TypeError("$template only supports state refs, null, and undefined");s+=t[d+1]}return{$template:s}}function b(t,a,s){return{$cond:t,$then:a,$else:s}}function u(t,a){return[{statePath:t,key:a},{$(i){return{$item:i}},$bind(i){return{$bindItem:i}},$index(){return{$index:!0}}}]}function w(t){return g(t,S)}return{$state:$,$bindState:m,$template:h,$cond:b,repeat:u,render:w}}exports.createSpec=y;exports.renderElementTree=g;
2
2
  //# sourceMappingURL=spec.cjs.map
@@ -1 +1 @@
1
- {"version":3,"file":"spec.cjs","sources":["../../../sdui-core/src/spec.ts"],"sourcesContent":["/**\n * createSpec - Factory for state-bound expression helpers + render\n *\n * Mirrors Python SDK's StateHandle + render module.\n */\n\nimport type {\n StatePaths,\n ValueAt,\n ArrayPaths,\n ArrayItemAt,\n ItemPaths,\n ItemValueAt,\n} from './paths';\nimport type {\n StateRef,\n BindStateRef,\n ItemRef,\n BindItemRef,\n IndexRef,\n TemplateRef,\n TemplateInterpolation,\n CondRef,\n PropValue,\n} from './expressions';\nimport type { VisibilityBinding } from './conditions';\nimport type { ElementNode, RepeatBinding } from './elements';\nimport type { InternalElementNode } from './component-utils';\n\n/** Typed accessor for repeat item fields. */\nexport interface ItemAccessor<TItem> {\n /** Read a field from the current repeat item. */\n $<P extends ItemPaths<TItem>>(path: P): ItemRef<ItemValueAt<TItem, P>>;\n /** Two-way bind to a field on the current repeat item. */\n $bind<P extends ItemPaths<TItem>>(\n path: P\n ): BindItemRef<ItemValueAt<TItem, P>>;\n /** Current repeat index (number). */\n $index(): IndexRef;\n}\n\nexport interface FlatUIElement {\n type: string;\n props: Record<string, unknown>;\n children?: string[];\n slots?: Record<string, string[]>;\n visible?: unknown;\n on?: Record<string, unknown>;\n watch?: Record<string, unknown>;\n repeat?: { statePath: string; key?: string };\n}\n\nexport interface FlatSpec {\n root: string;\n elements: Record<string, FlatUIElement>;\n state?: Record<string, unknown>;\n}\n\nexport type Spec = FlatSpec;\nexport type CoreSpec = FlatSpec;\n\n/**\n * Flatten an element tree into a flat spec format.\n * Uses JSON round-trip to strip Symbol properties and undefined values,\n * ensuring clean serialization.\n */\nexport function renderElementTree(root: ElementNode, state?: object): FlatSpec {\n const elements: Record<string, FlatUIElement> = {};\n const explicitIds = new Map<string, object>();\n const elementIds = new WeakMap<object, string>();\n const emitted = new WeakSet<object>();\n const usedIds = new Set<string>();\n let nextGeneratedId = 0;\n\n function collectExplicitIds(\n node: ElementNode,\n seen = new WeakSet<object>()\n ): void {\n const nodeObject = node as unknown as object;\n if (seen.has(nodeObject)) {\n return;\n }\n seen.add(nodeObject);\n\n const n = node as unknown as InternalElementNode;\n if (n.id !== undefined) {\n const existing = explicitIds.get(n.id);\n if (existing && existing !== nodeObject) {\n throw new Error(`Duplicate element id: ${n.id}`);\n }\n explicitIds.set(n.id, nodeObject);\n usedIds.add(n.id);\n }\n\n n.children?.forEach(child => collectExplicitIds(child, seen));\n Object.values(n.slots ?? {}).forEach(slotChildren =>\n slotChildren.forEach(child => collectExplicitIds(child, seen))\n );\n }\n\n function allocateGeneratedId(): string {\n let id: string;\n do {\n id = `element-${nextGeneratedId}`;\n nextGeneratedId += 1;\n } while (usedIds.has(id));\n\n usedIds.add(id);\n return id;\n }\n\n function elementId(node: ElementNode): string {\n const nodeObject = node as unknown as object;\n const existing = elementIds.get(nodeObject);\n if (existing) {\n return existing;\n }\n\n const n = node as unknown as InternalElementNode;\n const id = n.id ?? allocateGeneratedId();\n elementIds.set(nodeObject, id);\n return id;\n }\n\n function flatten(node: ElementNode): string {\n const nodeObject = node as unknown as object;\n const id = elementId(node);\n if (emitted.has(nodeObject)) {\n return id;\n }\n emitted.add(nodeObject);\n\n const n = node as unknown as InternalElementNode;\n const childIds: string[] = n.children\n ? n.children.map(child => flatten(child))\n : [];\n\n const flatElement: FlatUIElement = {\n type: n.type,\n props: n.props,\n children: childIds,\n };\n if (n.slots) {\n flatElement.slots = Object.fromEntries(\n Object.entries(n.slots).map(([name, slotChildren]) => [\n name,\n slotChildren.map(child => flatten(child)),\n ])\n );\n }\n\n if (n.visible !== undefined) {\n flatElement.visible = n.visible;\n }\n if (n.on) {\n flatElement.on = n.on;\n }\n if (n.watch) {\n flatElement.watch = n.watch;\n }\n if (n.repeat) {\n flatElement.repeat = n.repeat;\n }\n\n elements[id] = flatElement;\n return id;\n }\n\n collectExplicitIds(root);\n const rootId = flatten(root);\n\n return JSON.parse(\n JSON.stringify({\n root: rootId,\n elements,\n state,\n })\n ) as FlatSpec;\n}\n\nexport interface SpecContext<TState> {\n /** Read-only reference to a state path. */\n $state<P extends StatePaths<TState>>(path: P): StateRef<ValueAt<TState, P>>;\n\n /** Two-way binding to a state path. */\n $bindState<P extends StatePaths<TState>>(\n path: P\n ): BindStateRef<ValueAt<TState, P>>;\n\n /** String template expression (tagged template literal). */\n $template(\n strings: TemplateStringsArray,\n ...values: TemplateInterpolation[]\n ): TemplateRef;\n\n /** Conditional expression with typed branches. */\n $cond<T>(\n condition: VisibilityBinding | boolean,\n then: PropValue<T>,\n else_: PropValue<T>\n ): CondRef<T>;\n\n /**\n * Create a repeat binding for an array state path.\n * Returns [RepeatBinding, ItemAccessor<T>].\n */\n repeat<P extends ArrayPaths<TState>>(\n statePath: P,\n key?: string\n ): [RepeatBinding, ItemAccessor<ArrayItemAt<TState, P>>];\n\n /** Flatten an element tree into the flat spec format. */\n render(root: ElementNode): FlatSpec;\n}\n\nexport function createSpec<TState extends object>(config: {\n state: TState;\n}): SpecContext<TState> {\n const initialState = config.state;\n\n function $state(path: string): unknown {\n return { $state: path };\n }\n\n function $bindState(path: string): unknown {\n return { $bindState: path };\n }\n\n /**\n * Build a template string from a tagged template literal.\n * Converts expression refs ($state, $item, $index) into template variables.\n */\n function $template(\n strings: TemplateStringsArray,\n ...values: unknown[]\n ): unknown {\n let result = strings[0];\n for (let i = 0; i < values.length; i += 1) {\n const val = values[i];\n if (!val || typeof val !== 'object') {\n result += '';\n } else if ('$state' in val) {\n result += `\\${${val.$state}}`;\n } else if ('$item' in val) {\n result += `\\${$item.${val.$item}}`;\n } else if ('$index' in val) {\n result += '${$index}';\n }\n result += strings[i + 1];\n }\n return { $template: result };\n }\n\n function $cond(condition: unknown, then: unknown, else_: unknown): unknown {\n return { $cond: condition, $then: then, $else: else_ };\n }\n\n /**\n * Create a repeat binding for array iteration.\n * Returns [RepeatBinding, ItemAccessor] tuple.\n *\n * Type safety is enforced at the createSpec boundary through type parameters.\n * Internal implementations use `any` to work with the opaque branded types.\n */\n function repeat(\n statePath: string,\n key?: string\n ): [unknown, ItemAccessor<unknown>] {\n const repeatBinding = { statePath, key } as unknown as RepeatBinding;\n\n const itemAccessor: ItemAccessor<unknown> = {\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n $(path: string): any {\n return { $item: path };\n },\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n $bind(path: string): any {\n return { $bindItem: path };\n },\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n $index(): any {\n return { $index: true };\n },\n };\n\n return [repeatBinding, itemAccessor];\n }\n\n function render(root: ElementNode): FlatSpec {\n return renderElementTree(root, initialState);\n }\n\n return {\n $state,\n $bindState,\n $template,\n $cond,\n repeat,\n render,\n } as unknown as SpecContext<TState>;\n}\n"],"names":["renderElementTree","root","state","elements","explicitIds","elementIds","emitted","usedIds","nextGeneratedId","collectExplicitIds","node","seen","nodeObject","n","existing","_a","child","slotChildren","allocateGeneratedId","id","elementId","flatten","childIds","flatElement","name","rootId","createSpec","config","initialState","$state","path","$bindState","$template","strings","values","result","i","val","$cond","condition","then","else_","repeat","statePath","key","render"],"mappings":"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"}
1
+ {"version":3,"file":"spec.cjs","sources":["../../../sdui-core/src/spec.ts"],"sourcesContent":["/**\n * createSpec - Factory for state-bound expression helpers + render\n *\n * Mirrors Python SDK's StateHandle + render module.\n */\n\nimport type {\n StatePaths,\n ValueAt,\n ArrayPaths,\n ArrayItemAt,\n ItemPaths,\n ItemValueAt,\n} from './paths';\nimport type {\n StateRef,\n BindStateRef,\n ItemRef,\n BindItemRef,\n IndexRef,\n TemplateRef,\n TemplateInterpolation,\n CondRef,\n PropValue,\n} from './expressions';\nimport type { VisibilityBinding } from './conditions';\nimport type { ElementNode, RepeatBinding } from './elements';\nimport type { InternalElementNode } from './component-utils';\n\n/** Typed accessor for repeat item fields. */\nexport interface ItemAccessor<TItem> {\n /** Read a field from the current repeat item. */\n $<P extends ItemPaths<TItem>>(path: P): ItemRef<ItemValueAt<TItem, P>>;\n /** Two-way bind to a field on the current repeat item. */\n $bind<P extends ItemPaths<TItem>>(\n path: P\n ): BindItemRef<ItemValueAt<TItem, P>>;\n /** Current repeat index (number). */\n $index(): IndexRef;\n}\n\nexport interface FlatUIElement {\n type: string;\n props: Record<string, unknown>;\n children?: string[];\n slots?: Record<string, string[]>;\n visible?: unknown;\n on?: Record<string, unknown>;\n watch?: Record<string, unknown>;\n repeat?: { statePath: string; key?: string };\n}\n\nexport interface FlatSpec {\n root: string;\n elements: Record<string, FlatUIElement>;\n state?: Record<string, unknown>;\n}\n\nexport type Spec = FlatSpec;\nexport type CoreSpec = FlatSpec;\n\n/**\n * Flatten an element tree into a flat spec format.\n * Uses JSON round-trip to strip Symbol properties and undefined values,\n * ensuring clean serialization.\n */\nexport function renderElementTree(root: ElementNode, state?: object): FlatSpec {\n const elements: Record<string, FlatUIElement> = {};\n const explicitIds = new Map<string, object>();\n const elementIds = new WeakMap<object, string>();\n const emitted = new WeakSet<object>();\n const usedIds = new Set<string>();\n let nextGeneratedId = 0;\n\n function collectExplicitIds(\n node: ElementNode,\n seen = new WeakSet<object>()\n ): void {\n const nodeObject = node as unknown as object;\n if (seen.has(nodeObject)) {\n return;\n }\n seen.add(nodeObject);\n\n const n = node as unknown as InternalElementNode;\n if (n.id !== undefined) {\n const existing = explicitIds.get(n.id);\n if (existing && existing !== nodeObject) {\n throw new Error(`Duplicate element id: ${n.id}`);\n }\n explicitIds.set(n.id, nodeObject);\n usedIds.add(n.id);\n }\n\n n.children?.forEach(child => collectExplicitIds(child, seen));\n Object.values(n.slots ?? {}).forEach(slotChildren =>\n slotChildren.forEach(child => collectExplicitIds(child, seen))\n );\n }\n\n function allocateGeneratedId(): string {\n let id: string;\n do {\n id = `element-${nextGeneratedId}`;\n nextGeneratedId += 1;\n } while (usedIds.has(id));\n\n usedIds.add(id);\n return id;\n }\n\n function elementId(node: ElementNode): string {\n const nodeObject = node as unknown as object;\n const existing = elementIds.get(nodeObject);\n if (existing) {\n return existing;\n }\n\n const n = node as unknown as InternalElementNode;\n const id = n.id ?? allocateGeneratedId();\n elementIds.set(nodeObject, id);\n return id;\n }\n\n function flatten(node: ElementNode): string {\n const nodeObject = node as unknown as object;\n const id = elementId(node);\n if (emitted.has(nodeObject)) {\n return id;\n }\n emitted.add(nodeObject);\n\n const n = node as unknown as InternalElementNode;\n const childIds: string[] = n.children\n ? n.children.map(child => flatten(child))\n : [];\n\n const flatElement: FlatUIElement = {\n type: n.type,\n props: n.props,\n children: childIds,\n };\n if (n.slots) {\n flatElement.slots = Object.fromEntries(\n Object.entries(n.slots).map(([name, slotChildren]) => [\n name,\n slotChildren.map(child => flatten(child)),\n ])\n );\n }\n\n if (n.visible !== undefined) {\n flatElement.visible = n.visible;\n }\n if (n.on) {\n flatElement.on = n.on;\n }\n if (n.watch) {\n flatElement.watch = n.watch;\n }\n if (n.repeat) {\n flatElement.repeat = n.repeat;\n }\n\n elements[id] = flatElement;\n return id;\n }\n\n collectExplicitIds(root);\n const rootId = flatten(root);\n\n return JSON.parse(\n JSON.stringify({\n root: rootId,\n elements,\n state,\n })\n ) as FlatSpec;\n}\n\nexport interface SpecContext<TState> {\n /** Read-only reference to a state path. */\n $state<P extends StatePaths<TState>>(path: P): StateRef<ValueAt<TState, P>>;\n\n /** Two-way binding to a state path. */\n $bindState<P extends StatePaths<TState>>(\n path: P\n ): BindStateRef<ValueAt<TState, P>>;\n\n /** String template expression (tagged template literal). */\n $template(\n strings: TemplateStringsArray,\n ...values: TemplateInterpolation[]\n ): TemplateRef;\n\n /** Conditional expression with typed branches. */\n $cond<T>(\n condition: VisibilityBinding | boolean,\n then: PropValue<T>,\n else_: PropValue<T>\n ): CondRef<T>;\n\n /**\n * Create a repeat binding for an array state path.\n * Returns [RepeatBinding, ItemAccessor<T>].\n */\n repeat<P extends ArrayPaths<TState>>(\n statePath: P,\n key?: string\n ): [RepeatBinding, ItemAccessor<ArrayItemAt<TState, P>>];\n\n /** Flatten an element tree into the flat spec format. */\n render(root: ElementNode): FlatSpec;\n}\n\nexport function createSpec<TState extends object>(config: {\n state: TState;\n}): SpecContext<TState> {\n const initialState = config.state;\n\n function $state(path: string): unknown {\n return { $state: path };\n }\n\n function $bindState(path: string): unknown {\n return { $bindState: path };\n }\n\n /**\n * Build a template string from a tagged template literal.\n * Converts state refs into runtime template variables.\n */\n function $template(\n strings: TemplateStringsArray,\n ...values: unknown[]\n ): unknown {\n let result = strings[0];\n for (let i = 0; i < values.length; i += 1) {\n const val = values[i];\n if (val === null || val === undefined) {\n result += '';\n } else if (\n typeof val === 'object' &&\n '$state' in val &&\n typeof val.$state === 'string'\n ) {\n result += `\\${${val.$state}}`;\n } else {\n throw new TypeError(\n '$template only supports state refs, null, and undefined'\n );\n }\n result += strings[i + 1];\n }\n return { $template: result };\n }\n\n function $cond(condition: unknown, then: unknown, else_: unknown): unknown {\n return { $cond: condition, $then: then, $else: else_ };\n }\n\n /**\n * Create a repeat binding for array iteration.\n * Returns [RepeatBinding, ItemAccessor] tuple.\n *\n * Type safety is enforced at the createSpec boundary through type parameters.\n * Internal implementations use `any` to work with the opaque branded types.\n */\n function repeat(\n statePath: string,\n key?: string\n ): [unknown, ItemAccessor<unknown>] {\n const repeatBinding = { statePath, key } as unknown as RepeatBinding;\n\n const itemAccessor: ItemAccessor<unknown> = {\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n $(path: string): any {\n return { $item: path };\n },\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n $bind(path: string): any {\n return { $bindItem: path };\n },\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n $index(): any {\n return { $index: true };\n },\n };\n\n return [repeatBinding, itemAccessor];\n }\n\n function render(root: ElementNode): FlatSpec {\n return renderElementTree(root, initialState);\n }\n\n return {\n $state,\n $bindState,\n $template,\n $cond,\n repeat,\n render,\n } as unknown as SpecContext<TState>;\n}\n"],"names":["renderElementTree","root","state","elements","explicitIds","elementIds","emitted","usedIds","nextGeneratedId","collectExplicitIds","node","seen","nodeObject","n","existing","_a","child","slotChildren","allocateGeneratedId","id","elementId","flatten","childIds","flatElement","name","rootId","createSpec","config","initialState","$state","path","$bindState","$template","strings","values","result","i","val","$cond","condition","then","else_","repeat","statePath","key","render"],"mappings":"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"}
package/dist/core/spec.js CHANGED
@@ -1,92 +1,100 @@
1
- function E($, x) {
2
- const p = {}, m = /* @__PURE__ */ new Map(), h = /* @__PURE__ */ new WeakMap(), b = /* @__PURE__ */ new WeakSet(), f = /* @__PURE__ */ new Set();
1
+ function g(p, I) {
2
+ const $ = {}, h = /* @__PURE__ */ new Map(), m = /* @__PURE__ */ new WeakMap(), b = /* @__PURE__ */ new WeakSet(), u = /* @__PURE__ */ new Set();
3
3
  let w = 0;
4
- function t(n, s = /* @__PURE__ */ new WeakSet()) {
4
+ function e(n, s = /* @__PURE__ */ new WeakSet()) {
5
5
  var l;
6
6
  const o = n;
7
7
  if (s.has(o))
8
8
  return;
9
9
  s.add(o);
10
- const e = n;
11
- if (e.id !== void 0) {
12
- const r = m.get(e.id);
13
- if (r && r !== o)
14
- throw new Error(`Duplicate element id: ${e.id}`);
15
- m.set(e.id, o), f.add(e.id);
10
+ const t = n;
11
+ if (t.id !== void 0) {
12
+ const i = h.get(t.id);
13
+ if (i && i !== o)
14
+ throw new Error(`Duplicate element id: ${t.id}`);
15
+ h.set(t.id, o), u.add(t.id);
16
16
  }
17
- (l = e.children) == null || l.forEach((r) => t(r, s)), Object.values(e.slots ?? {}).forEach(
18
- (r) => r.forEach((u) => t(u, s))
17
+ (l = t.children) == null || l.forEach((i) => e(i, s)), Object.values(t.slots ?? {}).forEach(
18
+ (i) => i.forEach((f) => e(f, s))
19
19
  );
20
20
  }
21
21
  function a() {
22
22
  let n;
23
23
  do
24
24
  n = `element-${w}`, w += 1;
25
- while (f.has(n));
26
- return f.add(n), n;
25
+ while (u.has(n));
26
+ return u.add(n), n;
27
27
  }
28
28
  function c(n) {
29
- const s = n, o = h.get(s);
29
+ const s = n, o = m.get(s);
30
30
  if (o)
31
31
  return o;
32
32
  const l = n.id ?? a();
33
- return h.set(s, l), l;
33
+ return m.set(s, l), l;
34
34
  }
35
35
  function d(n) {
36
36
  const s = n, o = c(n);
37
37
  if (b.has(s))
38
38
  return o;
39
39
  b.add(s);
40
- const e = n, l = e.children ? e.children.map((u) => d(u)) : [], r = {
41
- type: e.type,
42
- props: e.props,
40
+ const t = n, l = t.children ? t.children.map((f) => d(f)) : [], i = {
41
+ type: t.type,
42
+ props: t.props,
43
43
  children: l
44
44
  };
45
- return e.slots && (r.slots = Object.fromEntries(
46
- Object.entries(e.slots).map(([u, I]) => [
47
- u,
48
- I.map((S) => d(S))
45
+ return t.slots && (i.slots = Object.fromEntries(
46
+ Object.entries(t.slots).map(([f, E]) => [
47
+ f,
48
+ E.map((S) => d(S))
49
49
  ])
50
- )), e.visible !== void 0 && (r.visible = e.visible), e.on && (r.on = e.on), e.watch && (r.watch = e.watch), e.repeat && (r.repeat = e.repeat), p[o] = r, o;
50
+ )), t.visible !== void 0 && (i.visible = t.visible), t.on && (i.on = t.on), t.watch && (i.watch = t.watch), t.repeat && (i.repeat = t.repeat), $[o] = i, o;
51
51
  }
52
- t($);
53
- const i = d($);
52
+ e(p);
53
+ const r = d(p);
54
54
  return JSON.parse(
55
55
  JSON.stringify({
56
- root: i,
57
- elements: p,
58
- state: x
56
+ root: r,
57
+ elements: $,
58
+ state: I
59
59
  })
60
60
  );
61
61
  }
62
- function O($) {
63
- const x = $.state;
64
- function p(t) {
65
- return { $state: t };
62
+ function x(p) {
63
+ const I = p.state;
64
+ function $(e) {
65
+ return { $state: e };
66
66
  }
67
- function m(t) {
68
- return { $bindState: t };
67
+ function h(e) {
68
+ return { $bindState: e };
69
69
  }
70
- function h(t, ...a) {
71
- let c = t[0];
70
+ function m(e, ...a) {
71
+ let c = e[0];
72
72
  for (let d = 0; d < a.length; d += 1) {
73
- const i = a[d];
74
- !i || typeof i != "object" ? c += "" : "$state" in i ? c += `\${${i.$state}}` : "$item" in i ? c += `\${$item.${i.$item}}` : "$index" in i && (c += "${$index}"), c += t[d + 1];
73
+ const r = a[d];
74
+ if (r == null)
75
+ c += "";
76
+ else if (typeof r == "object" && "$state" in r && typeof r.$state == "string")
77
+ c += `\${${r.$state}}`;
78
+ else
79
+ throw new TypeError(
80
+ "$template only supports state refs, null, and undefined"
81
+ );
82
+ c += e[d + 1];
75
83
  }
76
84
  return { $template: c };
77
85
  }
78
- function b(t, a, c) {
79
- return { $cond: t, $then: a, $else: c };
86
+ function b(e, a, c) {
87
+ return { $cond: e, $then: a, $else: c };
80
88
  }
81
- function f(t, a) {
82
- return [{ statePath: t, key: a }, {
89
+ function u(e, a) {
90
+ return [{ statePath: e, key: a }, {
83
91
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
84
- $(i) {
85
- return { $item: i };
92
+ $(r) {
93
+ return { $item: r };
86
94
  },
87
95
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
88
- $bind(i) {
89
- return { $bindItem: i };
96
+ $bind(r) {
97
+ return { $bindItem: r };
90
98
  },
91
99
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
92
100
  $index() {
@@ -94,20 +102,20 @@ function O($) {
94
102
  }
95
103
  }];
96
104
  }
97
- function w(t) {
98
- return E(t, x);
105
+ function w(e) {
106
+ return g(e, I);
99
107
  }
100
108
  return {
101
- $state: p,
102
- $bindState: m,
103
- $template: h,
109
+ $state: $,
110
+ $bindState: h,
111
+ $template: m,
104
112
  $cond: b,
105
- repeat: f,
113
+ repeat: u,
106
114
  render: w
107
115
  };
108
116
  }
109
117
  export {
110
- O as createSpec,
111
- E as renderElementTree
118
+ x as createSpec,
119
+ g as renderElementTree
112
120
  };
113
121
  //# sourceMappingURL=spec.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"spec.js","sources":["../../../sdui-core/src/spec.ts"],"sourcesContent":["/**\n * createSpec - Factory for state-bound expression helpers + render\n *\n * Mirrors Python SDK's StateHandle + render module.\n */\n\nimport type {\n StatePaths,\n ValueAt,\n ArrayPaths,\n ArrayItemAt,\n ItemPaths,\n ItemValueAt,\n} from './paths';\nimport type {\n StateRef,\n BindStateRef,\n ItemRef,\n BindItemRef,\n IndexRef,\n TemplateRef,\n TemplateInterpolation,\n CondRef,\n PropValue,\n} from './expressions';\nimport type { VisibilityBinding } from './conditions';\nimport type { ElementNode, RepeatBinding } from './elements';\nimport type { InternalElementNode } from './component-utils';\n\n/** Typed accessor for repeat item fields. */\nexport interface ItemAccessor<TItem> {\n /** Read a field from the current repeat item. */\n $<P extends ItemPaths<TItem>>(path: P): ItemRef<ItemValueAt<TItem, P>>;\n /** Two-way bind to a field on the current repeat item. */\n $bind<P extends ItemPaths<TItem>>(\n path: P\n ): BindItemRef<ItemValueAt<TItem, P>>;\n /** Current repeat index (number). */\n $index(): IndexRef;\n}\n\nexport interface FlatUIElement {\n type: string;\n props: Record<string, unknown>;\n children?: string[];\n slots?: Record<string, string[]>;\n visible?: unknown;\n on?: Record<string, unknown>;\n watch?: Record<string, unknown>;\n repeat?: { statePath: string; key?: string };\n}\n\nexport interface FlatSpec {\n root: string;\n elements: Record<string, FlatUIElement>;\n state?: Record<string, unknown>;\n}\n\nexport type Spec = FlatSpec;\nexport type CoreSpec = FlatSpec;\n\n/**\n * Flatten an element tree into a flat spec format.\n * Uses JSON round-trip to strip Symbol properties and undefined values,\n * ensuring clean serialization.\n */\nexport function renderElementTree(root: ElementNode, state?: object): FlatSpec {\n const elements: Record<string, FlatUIElement> = {};\n const explicitIds = new Map<string, object>();\n const elementIds = new WeakMap<object, string>();\n const emitted = new WeakSet<object>();\n const usedIds = new Set<string>();\n let nextGeneratedId = 0;\n\n function collectExplicitIds(\n node: ElementNode,\n seen = new WeakSet<object>()\n ): void {\n const nodeObject = node as unknown as object;\n if (seen.has(nodeObject)) {\n return;\n }\n seen.add(nodeObject);\n\n const n = node as unknown as InternalElementNode;\n if (n.id !== undefined) {\n const existing = explicitIds.get(n.id);\n if (existing && existing !== nodeObject) {\n throw new Error(`Duplicate element id: ${n.id}`);\n }\n explicitIds.set(n.id, nodeObject);\n usedIds.add(n.id);\n }\n\n n.children?.forEach(child => collectExplicitIds(child, seen));\n Object.values(n.slots ?? {}).forEach(slotChildren =>\n slotChildren.forEach(child => collectExplicitIds(child, seen))\n );\n }\n\n function allocateGeneratedId(): string {\n let id: string;\n do {\n id = `element-${nextGeneratedId}`;\n nextGeneratedId += 1;\n } while (usedIds.has(id));\n\n usedIds.add(id);\n return id;\n }\n\n function elementId(node: ElementNode): string {\n const nodeObject = node as unknown as object;\n const existing = elementIds.get(nodeObject);\n if (existing) {\n return existing;\n }\n\n const n = node as unknown as InternalElementNode;\n const id = n.id ?? allocateGeneratedId();\n elementIds.set(nodeObject, id);\n return id;\n }\n\n function flatten(node: ElementNode): string {\n const nodeObject = node as unknown as object;\n const id = elementId(node);\n if (emitted.has(nodeObject)) {\n return id;\n }\n emitted.add(nodeObject);\n\n const n = node as unknown as InternalElementNode;\n const childIds: string[] = n.children\n ? n.children.map(child => flatten(child))\n : [];\n\n const flatElement: FlatUIElement = {\n type: n.type,\n props: n.props,\n children: childIds,\n };\n if (n.slots) {\n flatElement.slots = Object.fromEntries(\n Object.entries(n.slots).map(([name, slotChildren]) => [\n name,\n slotChildren.map(child => flatten(child)),\n ])\n );\n }\n\n if (n.visible !== undefined) {\n flatElement.visible = n.visible;\n }\n if (n.on) {\n flatElement.on = n.on;\n }\n if (n.watch) {\n flatElement.watch = n.watch;\n }\n if (n.repeat) {\n flatElement.repeat = n.repeat;\n }\n\n elements[id] = flatElement;\n return id;\n }\n\n collectExplicitIds(root);\n const rootId = flatten(root);\n\n return JSON.parse(\n JSON.stringify({\n root: rootId,\n elements,\n state,\n })\n ) as FlatSpec;\n}\n\nexport interface SpecContext<TState> {\n /** Read-only reference to a state path. */\n $state<P extends StatePaths<TState>>(path: P): StateRef<ValueAt<TState, P>>;\n\n /** Two-way binding to a state path. */\n $bindState<P extends StatePaths<TState>>(\n path: P\n ): BindStateRef<ValueAt<TState, P>>;\n\n /** String template expression (tagged template literal). */\n $template(\n strings: TemplateStringsArray,\n ...values: TemplateInterpolation[]\n ): TemplateRef;\n\n /** Conditional expression with typed branches. */\n $cond<T>(\n condition: VisibilityBinding | boolean,\n then: PropValue<T>,\n else_: PropValue<T>\n ): CondRef<T>;\n\n /**\n * Create a repeat binding for an array state path.\n * Returns [RepeatBinding, ItemAccessor<T>].\n */\n repeat<P extends ArrayPaths<TState>>(\n statePath: P,\n key?: string\n ): [RepeatBinding, ItemAccessor<ArrayItemAt<TState, P>>];\n\n /** Flatten an element tree into the flat spec format. */\n render(root: ElementNode): FlatSpec;\n}\n\nexport function createSpec<TState extends object>(config: {\n state: TState;\n}): SpecContext<TState> {\n const initialState = config.state;\n\n function $state(path: string): unknown {\n return { $state: path };\n }\n\n function $bindState(path: string): unknown {\n return { $bindState: path };\n }\n\n /**\n * Build a template string from a tagged template literal.\n * Converts expression refs ($state, $item, $index) into template variables.\n */\n function $template(\n strings: TemplateStringsArray,\n ...values: unknown[]\n ): unknown {\n let result = strings[0];\n for (let i = 0; i < values.length; i += 1) {\n const val = values[i];\n if (!val || typeof val !== 'object') {\n result += '';\n } else if ('$state' in val) {\n result += `\\${${val.$state}}`;\n } else if ('$item' in val) {\n result += `\\${$item.${val.$item}}`;\n } else if ('$index' in val) {\n result += '${$index}';\n }\n result += strings[i + 1];\n }\n return { $template: result };\n }\n\n function $cond(condition: unknown, then: unknown, else_: unknown): unknown {\n return { $cond: condition, $then: then, $else: else_ };\n }\n\n /**\n * Create a repeat binding for array iteration.\n * Returns [RepeatBinding, ItemAccessor] tuple.\n *\n * Type safety is enforced at the createSpec boundary through type parameters.\n * Internal implementations use `any` to work with the opaque branded types.\n */\n function repeat(\n statePath: string,\n key?: string\n ): [unknown, ItemAccessor<unknown>] {\n const repeatBinding = { statePath, key } as unknown as RepeatBinding;\n\n const itemAccessor: ItemAccessor<unknown> = {\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n $(path: string): any {\n return { $item: path };\n },\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n $bind(path: string): any {\n return { $bindItem: path };\n },\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n $index(): any {\n return { $index: true };\n },\n };\n\n return [repeatBinding, itemAccessor];\n }\n\n function render(root: ElementNode): FlatSpec {\n return renderElementTree(root, initialState);\n }\n\n return {\n $state,\n $bindState,\n $template,\n $cond,\n repeat,\n render,\n } as unknown as SpecContext<TState>;\n}\n"],"names":["renderElementTree","root","state","elements","explicitIds","elementIds","emitted","usedIds","nextGeneratedId","collectExplicitIds","node","seen","_a","nodeObject","n","existing","child","slotChildren","allocateGeneratedId","id","elementId","flatten","childIds","flatElement","name","rootId","createSpec","config","initialState","$state","path","$bindState","$template","strings","values","result","i","val","$cond","condition","then","else_","repeat","statePath","key","render"],"mappings":"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"}
1
+ {"version":3,"file":"spec.js","sources":["../../../sdui-core/src/spec.ts"],"sourcesContent":["/**\n * createSpec - Factory for state-bound expression helpers + render\n *\n * Mirrors Python SDK's StateHandle + render module.\n */\n\nimport type {\n StatePaths,\n ValueAt,\n ArrayPaths,\n ArrayItemAt,\n ItemPaths,\n ItemValueAt,\n} from './paths';\nimport type {\n StateRef,\n BindStateRef,\n ItemRef,\n BindItemRef,\n IndexRef,\n TemplateRef,\n TemplateInterpolation,\n CondRef,\n PropValue,\n} from './expressions';\nimport type { VisibilityBinding } from './conditions';\nimport type { ElementNode, RepeatBinding } from './elements';\nimport type { InternalElementNode } from './component-utils';\n\n/** Typed accessor for repeat item fields. */\nexport interface ItemAccessor<TItem> {\n /** Read a field from the current repeat item. */\n $<P extends ItemPaths<TItem>>(path: P): ItemRef<ItemValueAt<TItem, P>>;\n /** Two-way bind to a field on the current repeat item. */\n $bind<P extends ItemPaths<TItem>>(\n path: P\n ): BindItemRef<ItemValueAt<TItem, P>>;\n /** Current repeat index (number). */\n $index(): IndexRef;\n}\n\nexport interface FlatUIElement {\n type: string;\n props: Record<string, unknown>;\n children?: string[];\n slots?: Record<string, string[]>;\n visible?: unknown;\n on?: Record<string, unknown>;\n watch?: Record<string, unknown>;\n repeat?: { statePath: string; key?: string };\n}\n\nexport interface FlatSpec {\n root: string;\n elements: Record<string, FlatUIElement>;\n state?: Record<string, unknown>;\n}\n\nexport type Spec = FlatSpec;\nexport type CoreSpec = FlatSpec;\n\n/**\n * Flatten an element tree into a flat spec format.\n * Uses JSON round-trip to strip Symbol properties and undefined values,\n * ensuring clean serialization.\n */\nexport function renderElementTree(root: ElementNode, state?: object): FlatSpec {\n const elements: Record<string, FlatUIElement> = {};\n const explicitIds = new Map<string, object>();\n const elementIds = new WeakMap<object, string>();\n const emitted = new WeakSet<object>();\n const usedIds = new Set<string>();\n let nextGeneratedId = 0;\n\n function collectExplicitIds(\n node: ElementNode,\n seen = new WeakSet<object>()\n ): void {\n const nodeObject = node as unknown as object;\n if (seen.has(nodeObject)) {\n return;\n }\n seen.add(nodeObject);\n\n const n = node as unknown as InternalElementNode;\n if (n.id !== undefined) {\n const existing = explicitIds.get(n.id);\n if (existing && existing !== nodeObject) {\n throw new Error(`Duplicate element id: ${n.id}`);\n }\n explicitIds.set(n.id, nodeObject);\n usedIds.add(n.id);\n }\n\n n.children?.forEach(child => collectExplicitIds(child, seen));\n Object.values(n.slots ?? {}).forEach(slotChildren =>\n slotChildren.forEach(child => collectExplicitIds(child, seen))\n );\n }\n\n function allocateGeneratedId(): string {\n let id: string;\n do {\n id = `element-${nextGeneratedId}`;\n nextGeneratedId += 1;\n } while (usedIds.has(id));\n\n usedIds.add(id);\n return id;\n }\n\n function elementId(node: ElementNode): string {\n const nodeObject = node as unknown as object;\n const existing = elementIds.get(nodeObject);\n if (existing) {\n return existing;\n }\n\n const n = node as unknown as InternalElementNode;\n const id = n.id ?? allocateGeneratedId();\n elementIds.set(nodeObject, id);\n return id;\n }\n\n function flatten(node: ElementNode): string {\n const nodeObject = node as unknown as object;\n const id = elementId(node);\n if (emitted.has(nodeObject)) {\n return id;\n }\n emitted.add(nodeObject);\n\n const n = node as unknown as InternalElementNode;\n const childIds: string[] = n.children\n ? n.children.map(child => flatten(child))\n : [];\n\n const flatElement: FlatUIElement = {\n type: n.type,\n props: n.props,\n children: childIds,\n };\n if (n.slots) {\n flatElement.slots = Object.fromEntries(\n Object.entries(n.slots).map(([name, slotChildren]) => [\n name,\n slotChildren.map(child => flatten(child)),\n ])\n );\n }\n\n if (n.visible !== undefined) {\n flatElement.visible = n.visible;\n }\n if (n.on) {\n flatElement.on = n.on;\n }\n if (n.watch) {\n flatElement.watch = n.watch;\n }\n if (n.repeat) {\n flatElement.repeat = n.repeat;\n }\n\n elements[id] = flatElement;\n return id;\n }\n\n collectExplicitIds(root);\n const rootId = flatten(root);\n\n return JSON.parse(\n JSON.stringify({\n root: rootId,\n elements,\n state,\n })\n ) as FlatSpec;\n}\n\nexport interface SpecContext<TState> {\n /** Read-only reference to a state path. */\n $state<P extends StatePaths<TState>>(path: P): StateRef<ValueAt<TState, P>>;\n\n /** Two-way binding to a state path. */\n $bindState<P extends StatePaths<TState>>(\n path: P\n ): BindStateRef<ValueAt<TState, P>>;\n\n /** String template expression (tagged template literal). */\n $template(\n strings: TemplateStringsArray,\n ...values: TemplateInterpolation[]\n ): TemplateRef;\n\n /** Conditional expression with typed branches. */\n $cond<T>(\n condition: VisibilityBinding | boolean,\n then: PropValue<T>,\n else_: PropValue<T>\n ): CondRef<T>;\n\n /**\n * Create a repeat binding for an array state path.\n * Returns [RepeatBinding, ItemAccessor<T>].\n */\n repeat<P extends ArrayPaths<TState>>(\n statePath: P,\n key?: string\n ): [RepeatBinding, ItemAccessor<ArrayItemAt<TState, P>>];\n\n /** Flatten an element tree into the flat spec format. */\n render(root: ElementNode): FlatSpec;\n}\n\nexport function createSpec<TState extends object>(config: {\n state: TState;\n}): SpecContext<TState> {\n const initialState = config.state;\n\n function $state(path: string): unknown {\n return { $state: path };\n }\n\n function $bindState(path: string): unknown {\n return { $bindState: path };\n }\n\n /**\n * Build a template string from a tagged template literal.\n * Converts state refs into runtime template variables.\n */\n function $template(\n strings: TemplateStringsArray,\n ...values: unknown[]\n ): unknown {\n let result = strings[0];\n for (let i = 0; i < values.length; i += 1) {\n const val = values[i];\n if (val === null || val === undefined) {\n result += '';\n } else if (\n typeof val === 'object' &&\n '$state' in val &&\n typeof val.$state === 'string'\n ) {\n result += `\\${${val.$state}}`;\n } else {\n throw new TypeError(\n '$template only supports state refs, null, and undefined'\n );\n }\n result += strings[i + 1];\n }\n return { $template: result };\n }\n\n function $cond(condition: unknown, then: unknown, else_: unknown): unknown {\n return { $cond: condition, $then: then, $else: else_ };\n }\n\n /**\n * Create a repeat binding for array iteration.\n * Returns [RepeatBinding, ItemAccessor] tuple.\n *\n * Type safety is enforced at the createSpec boundary through type parameters.\n * Internal implementations use `any` to work with the opaque branded types.\n */\n function repeat(\n statePath: string,\n key?: string\n ): [unknown, ItemAccessor<unknown>] {\n const repeatBinding = { statePath, key } as unknown as RepeatBinding;\n\n const itemAccessor: ItemAccessor<unknown> = {\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n $(path: string): any {\n return { $item: path };\n },\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n $bind(path: string): any {\n return { $bindItem: path };\n },\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n $index(): any {\n return { $index: true };\n },\n };\n\n return [repeatBinding, itemAccessor];\n }\n\n function render(root: ElementNode): FlatSpec {\n return renderElementTree(root, initialState);\n }\n\n return {\n $state,\n $bindState,\n $template,\n $cond,\n repeat,\n render,\n } as unknown as SpecContext<TState>;\n}\n"],"names":["renderElementTree","root","state","elements","explicitIds","elementIds","emitted","usedIds","nextGeneratedId","collectExplicitIds","node","seen","_a","nodeObject","n","existing","child","slotChildren","allocateGeneratedId","id","elementId","flatten","childIds","flatElement","name","rootId","createSpec","config","initialState","$state","path","$bindState","$template","strings","values","result","i","val","$cond","condition","then","else_","repeat","statePath","key","render"],"mappings":"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"}
@@ -308,28 +308,27 @@ Example:
308
308
  }
309
309
  ```
310
310
 
311
- Use templates when a string prop needs runtime interpolation from state, repeated item fields, or indexes.
311
+ Use templates when a string prop needs runtime interpolation from state. Use `$item` and `$index` as separate expressions in compatible repeated-child props; combine them with text only through a composition expression supported by the target runtime.
312
312
 
313
313
  ## Repeat
314
314
 
315
- Repeat renders an element once per item in an array state path.
316
-
317
- Conceptually, a repeated element says:
318
-
319
- - which array state path to iterate
320
- - which field identifies each item, if a key is provided
321
- - which item fields the repeated element reads or binds
315
+ Repeat keeps the bound container in place and renders its children once per item in an array state path. Put item references on those children.
322
316
 
323
317
  Example shape:
324
318
 
325
319
  ```json
326
320
  {
327
- "repeat": {
328
- "statePath": "/todos",
329
- "key": "id"
330
- },
331
- "props": {
332
- "text": { "$item": "title" }
321
+ "root": "todo-list",
322
+ "elements": {
323
+ "todo-list": {
324
+ "type": "VStack",
325
+ "repeat": { "statePath": "/todos", "key": "id" },
326
+ "children": ["todo-title"]
327
+ },
328
+ "todo-title": {
329
+ "type": "Text",
330
+ "props": { "text": { "$item": "title" } }
331
+ }
333
332
  }
334
333
  }
335
334
  ```
@@ -110,7 +110,7 @@ Creates a string expression from refs.
110
110
 
111
111
  Purpose:
112
112
 
113
- - build runtime strings from state, repeat item refs, or repeat indexes
113
+ - build runtime strings from state refs
114
114
  - serialize as a JSON-renderer `$template` expression
115
115
 
116
116
  ✅ Correct:
@@ -133,7 +133,7 @@ Text({
133
133
  });
134
134
  ```
135
135
 
136
- Why it fails: template interpolations accept expression refs, `null`, or `undefined`; plain literal interpolation is not part of the typed surface.
136
+ Why it fails: template interpolations accept state refs, `null`, or `undefined`. Plain literals, item refs, and index refs are not supported inside `$template`.
137
137
 
138
138
  ## `$cond(condition, thenValue, elseValue)`
139
139
 
@@ -172,7 +172,7 @@ Creates a repeat binding and item accessor for an array state path.
172
172
 
173
173
  Purpose:
174
174
 
175
- - render one element per item in a runtime array
175
+ - render a container's children once per item in a runtime array
176
176
  - access repeated item fields with `item.$()`
177
177
  - bind repeated item fields with `item.$bind()`
178
178
  - access repeat index with `item.$index()`
@@ -186,11 +186,10 @@ interface AppState {
186
186
 
187
187
  const [todoRepeat, todo] = repeat('/todos', 'id');
188
188
 
189
- Text({
189
+ VStack({
190
190
  repeat: todoRepeat,
191
- props: {
192
- text: todo.$('title'),
193
- },
191
+ props: { gap: 'space300' },
192
+ children: [Text({ props: { text: todo.$('title') } })],
194
193
  });
195
194
  ```
196
195
 
@@ -164,7 +164,7 @@ Rendered prop shape:
164
164
  }
165
165
  ```
166
166
 
167
- Put plain words directly in the template string. Use interpolations only for SDK expression refs.
167
+ Put plain words directly in the template string; interpolate only state refs, `null`, or `undefined`. In repeated children, use an item ref directly for a plain value. On web runtimes with standard directives, use `$concat('Task: ', item.$('title'))` for combined text instead of interpolating item or index refs in `$template`.
168
168
 
169
169
  ## Show Or Hide Components With Conditions
170
170
 
@@ -230,7 +230,7 @@ Both branches should resolve to the same prop type.
230
230
 
231
231
  ## Repeat Over Runtime Lists
232
232
 
233
- Use `repeat(path, key?)` when JSON-render should render one element per item in a state array.
233
+ Use `repeat(path, key?)` to render a container's children once per item in a state array. To repeat a Card, put it inside that container.
234
234
 
235
235
  ```ts
236
236
  interface Todo {
@@ -253,11 +253,16 @@ const { repeat } = createSpec<AppState>({
253
253
 
254
254
  const [todoRepeat, todo] = repeat('/todos', 'id');
255
255
 
256
- Text({
256
+ VStack({
257
257
  repeat: todoRepeat,
258
- props: {
259
- text: todo.$('title'),
260
- },
258
+ props: { gap: 'space300' },
259
+ children: [
260
+ Card({
261
+ id: 'todo-card',
262
+ props: { padding: 'space300' },
263
+ children: [Text({ props: { text: todo.$('title') } })],
264
+ }),
265
+ ],
261
266
  });
262
267
  ```
263
268
 
@@ -265,17 +270,16 @@ Rendered shape includes:
265
270
 
266
271
  ```json
267
272
  {
273
+ "type": "VStack",
268
274
  "repeat": {
269
275
  "statePath": "/todos",
270
276
  "key": "id"
271
277
  },
272
- "props": {
273
- "text": { "$item": "title" }
274
- }
278
+ "children": ["todo-card"]
275
279
  }
276
280
  ```
277
281
 
278
- Use `todo.$bind('field')` only when the repeated component should write back to that item field. Use `todo.$index()` when the UI needs the current item index.
282
+ Use `todo.$bind('field')` only when a repeated child should write back to that item field. Use `todo.$index()` when the UI needs the current item index.
279
283
 
280
284
  ## Use Components From A Catalog
281
285
 
package/dist/sdk-docs.cjs CHANGED
@@ -500,10 +500,7 @@ A **condition** controls visibility or conditional expressions. Conditions can c
500
500
 
501
501
  ## Repeat
502
502
 
503
- A **repeat** renders an element once per item in a list state path. It provides:
504
-
505
- - a repeat binding attached to the repeated component
506
- - an item accessor for \`$item\`, \`$bindItem\`, and \`$index\`
503
+ A **repeat** keeps the bound container in place and renders its children once per item in a list state path. Attach it to a child-capable container, and use \`$item\`, \`$bindItem\`, or \`$index\` in the repeated children.
507
504
 
508
505
  Use repeat for data-driven lists instead of manually creating fixed children when the list length is dynamic.
509
506
 
@@ -1282,8 +1279,8 @@ const { $state, $bindState, $template, $cond, repeat } = specContext;
1282
1279
  Use \`$state(path)\` for read-only runtime refs.
1283
1280
 
1284
1281
  \`\`\`ts
1285
- const nameRef = $state('user.name');
1286
- // Renders as: { "$state": "user.name" }
1282
+ const nameRef = $state('/user/name');
1283
+ // Renders as: { "$state": "/user/name" }
1287
1284
  \`\`\`
1288
1285
 
1289
1286
  The path is type checked against \`AppState\`. Invalid paths should fail TypeScript type checking.
@@ -1293,8 +1290,8 @@ The path is type checked against \`AppState\`. Invalid paths should fail TypeScr
1293
1290
  Use \`$bindState(path)\` when a component should write back to state.
1294
1291
 
1295
1292
  \`\`\`ts
1296
- const nameBinding = $bindState('user.name');
1297
- // Renders as: { "$bindState": "user.name" }
1293
+ const nameBinding = $bindState('/user/name');
1294
+ // Renders as: { "$bindState": "/user/name" }
1298
1295
  \`\`\`
1299
1296
 
1300
1297
  Use bindings only for props documented as writable, such as form values or selected values.
@@ -1304,11 +1301,11 @@ Use bindings only for props documented as writable, such as form values or selec
1304
1301
  \`$template\` is a tagged template helper for string interpolation.
1305
1302
 
1306
1303
  \`\`\`ts
1307
- const greeting = $template\`Hello \${$state('user.name')}!\`;
1308
- // Renders as: { "$template": "Hello \${user.name}!" }
1304
+ const greeting = $template\`Hello \${$state('/user/name')}!\`;
1305
+ // Renders as: { "$template": "Hello \${/user/name}!" }
1309
1306
  \`\`\`
1310
1307
 
1311
- Template interpolations may include state refs, item refs, indexes, \`null\`, or \`undefined\`.
1308
+ Template interpolations accept state refs, \`null\`, or \`undefined\`. Use item and index refs directly in compatible repeated-child props. For combined text on web, use \`$concat\` when the runtime registers standard directives; item and index refs cannot be interpolated in \`$template\`.
1312
1309
 
1313
1310
  ## Conditions
1314
1311
 
@@ -1317,8 +1314,8 @@ Conditions are used for \`visible\` and \`$cond()\`.
1317
1314
  \`\`\`ts
1318
1315
  import { equals, gt, truthy, and_, or_, not_ } from '@rippling/pebble-sdui-web';
1319
1316
 
1320
- const isAdmin = equals($state('user.role'), 'admin');
1321
- const hasTodos = gt($state('count'), 0);
1317
+ const isAdmin = equals($state('/user/role'), 'admin');
1318
+ const hasTodos = gt($state('/count'), 0);
1322
1319
  const show = and_(isAdmin, hasTodos);
1323
1320
  \`\`\`
1324
1321
 
@@ -1342,7 +1339,7 @@ Use \`$cond(condition, thenValue, elseValue)\` for runtime prop values.
1342
1339
 
1343
1340
  \`\`\`ts
1344
1341
  const statusColor = $cond(
1345
- equals($state('active'), true),
1342
+ equals($state('/active'), true),
1346
1343
  'green',
1347
1344
  'gray'
1348
1345
  );
@@ -1355,23 +1352,22 @@ Both branches should resolve to the same prop type.
1355
1352
  \`repeat(path, key?)\` creates a repeat binding and a typed item accessor.
1356
1353
 
1357
1354
  \`\`\`ts
1358
- const [todoRepeat, todo] = repeat('todos', 'id');
1355
+ const [todoRepeat, todo] = repeat('/todos', 'id');
1359
1356
 
1360
1357
  const textRef = todo.$('text'); // { "$item": "text" }
1361
1358
  const doneBind = todo.$bind('done'); // { "$bindItem": "done" }
1362
1359
  const indexRef = todo.$index(); // { "$index": true }
1363
1360
  \`\`\`
1364
1361
 
1365
- Attach the repeat binding to the component that should render once per item:
1362
+ Attach the repeat binding to a child-capable container. The container renders once; its children render once per item:
1366
1363
 
1367
1364
  \`\`\`ts
1368
- import { Text } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
1365
+ import { Text, VStack } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
1369
1366
 
1370
- const repeatedText = Text({
1367
+ const todoList = VStack({
1371
1368
  repeat: todoRepeat,
1372
- props: {
1373
- text: todo.$('text'),
1374
- },
1369
+ props: { gap: 'space300' },
1370
+ children: [Text({ props: { text: todo.$('text') } })],
1375
1371
  });
1376
1372
  \`\`\`
1377
1373