@rippling/pebble-sdui-web 0.25.3 → 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
 
@@ -4105,24 +4105,48 @@ No additional properties.
4105
4105
 
4106
4106
  A structured list entry for displaying related entities vertically, with a title and optional caption. Use within grouped lists to present items for scanning, selection, or action.
4107
4107
 
4108
- Skipped: leftRenderer/rightRenderer (ReactNode — not serializable in JSON spec), dropdownActions (complex DropdownProps object with nested callbacks).
4108
+ Use slots.leftRenderer and slots.rightRenderer to place arbitrary SDUI content on either side of the title and caption, including Icon, Text, Button, or composed layout components. Ordinary children are not rendered.
4109
+
4110
+ dropdownActions.list adds an overflow menu. Each action requires a unique id; use { isSeparator: true } entries to separate action groups. Selecting an action writes its id to actionClickedId before emitting action, so bind actionClickedId to state when the handler needs to identify the selection. The row itself emits press when clicked.
4109
4111
 
4110
4112
  Catalog key: `ListItem`
4111
4113
  Builder: `ListItem`
4112
4114
  Props type: `ListItemProps`
4113
4115
  Accepts children: no
4114
- Events: `press`
4116
+ Events: `press`, `action`
4115
4117
 
4116
4118
  ### Props
4117
4119
 
4118
4120
  | Name | Required | Type | Description |
4119
4121
  |---|---:|---|---|
4122
+ | `actionClickedId` | no | string | ID of the last selected overflow action. Bind this prop when handling action |
4120
4123
  | `caption` | no | string | Secondary text below the title |
4124
+ | `dropdownActions` | no | [DropdownAction](./types.md#dropdownaction) | Overflow menu displayed at the end of the row |
4121
4125
  | `shouldTruncateCaption` | no | boolean | Truncate caption to single line. Default: true |
4122
4126
  | `title` | no | string | Primary text content of the list item |
4123
4127
 
4124
4128
  No additional properties.
4125
4129
 
4130
+ ## ListItemLayout
4131
+
4132
+ Group ListItem rows with dividers
4133
+
4134
+ Use ListItem children to create a grouped list with the React ListItem.Layout container styling, including row separation and removal of the final divider.
4135
+
4136
+ Catalog key: `ListItemLayout`
4137
+ Builder: `ListItemLayout`
4138
+ Props type: `ListItemLayoutProps`
4139
+ Accepts children: yes
4140
+ Events: _none_
4141
+
4142
+ ### Props
4143
+
4144
+ | Name | Required | Type | Description |
4145
+ |---|---:|---|---|
4146
+ | `title` | no | string | Optional title shown above the grouped list rows |
4147
+
4148
+ No additional properties.
4149
+
4126
4150
  ## LoaderCard
4127
4151
 
4128
4152
  A skeleton placeholder shaped like a card, shown while card content is loading. Use inside a Card.Group context to match card dimensions and reduce perceived loading time. Set isGridView for grid-based layouts.
@@ -4417,9 +4441,9 @@ No additional properties.
4417
4441
 
4418
4442
  ## ObjectListView
4419
4443
 
4420
- Full-featured object list page with list view management. Supports multiple list views, view switching, inline editing, bulk actions, and record management. Use objectApiName to specify the object.
4444
+ Full-featured object list page with list view management. Use objectApiName to specify the object. Optional rqlFilter intersects a page-owned RQL filter with native list filters while preserving native record actions.
4421
4445
 
4422
- Wraps ObjectListPage which provides list view selector, manage views, add/delete records, CSV export, and RQL filtering.
4446
+ Wraps ObjectListPage. When rqlFilter is set, the same scope applies to paginated rows and CSV export. Native write controls remain permission-driven. Render the list only after the required scope is known.
4423
4447
 
4424
4448
  Catalog key: `ObjectListView`
4425
4449
  Builder: `ObjectListView`
@@ -4432,6 +4456,7 @@ Events: _none_
4432
4456
  | Name | Required | Type | Description |
4433
4457
  |---|---:|---|---|
4434
4458
  | `objectApiName` | yes | string | |
4459
+ | `rqlFilter` | no | string | Page-owned RQL condition applied to every grid request and CSV export in addition to saved-view and native filters. Render only after required scope values are known. Escape user-selected values before building RQL. |
4435
4460
 
4436
4461
  No additional properties.
4437
4462