@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.
- package/dist/core/expressions.d.ts +2 -2
- package/dist/core/spec.cjs +1 -1
- package/dist/core/spec.cjs.map +1 -1
- package/dist/core/spec.js +62 -54
- package/dist/core/spec.js.map +1 -1
- package/dist/docs/concepts.md +13 -14
- package/dist/docs/typescript/api-reference.md +6 -7
- package/dist/docs/typescript/recipes.md +14 -10
- package/dist/sdk-docs.cjs +17 -21
- package/dist/sdk-docs.cjs.map +1 -1
- package/dist/sdk-docs.js +17 -21
- package/dist/sdk-docs.js.map +1 -1
- package/package.json +1 -1
|
@@ -32,9 +32,9 @@ export interface TemplateRef {
|
|
|
32
32
|
}
|
|
33
33
|
/**
|
|
34
34
|
* Valid interpolation value inside a $template tagged template.
|
|
35
|
-
*
|
|
35
|
+
* Runtime templates resolve state paths, not repeat item or index refs.
|
|
36
36
|
*/
|
|
37
|
-
export type TemplateInterpolation = StateRef<unknown> |
|
|
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;
|
package/dist/core/spec.cjs
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function
|
|
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
|
package/dist/core/spec.cjs.map
CHANGED
|
@@ -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
|
|
2
|
-
const
|
|
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
|
|
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
|
|
11
|
-
if (
|
|
12
|
-
const
|
|
13
|
-
if (
|
|
14
|
-
throw new Error(`Duplicate element id: ${
|
|
15
|
-
|
|
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 =
|
|
18
|
-
(
|
|
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 (
|
|
26
|
-
return
|
|
25
|
+
while (u.has(n));
|
|
26
|
+
return u.add(n), n;
|
|
27
27
|
}
|
|
28
28
|
function c(n) {
|
|
29
|
-
const s = n, o =
|
|
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
|
|
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
|
|
41
|
-
type:
|
|
42
|
-
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
|
|
46
|
-
Object.entries(
|
|
47
|
-
|
|
48
|
-
|
|
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
|
-
)),
|
|
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
|
-
|
|
53
|
-
const
|
|
52
|
+
e(p);
|
|
53
|
+
const r = d(p);
|
|
54
54
|
return JSON.parse(
|
|
55
55
|
JSON.stringify({
|
|
56
|
-
root:
|
|
57
|
-
elements:
|
|
58
|
-
state:
|
|
56
|
+
root: r,
|
|
57
|
+
elements: $,
|
|
58
|
+
state: I
|
|
59
59
|
})
|
|
60
60
|
);
|
|
61
61
|
}
|
|
62
|
-
function
|
|
63
|
-
const
|
|
64
|
-
function
|
|
65
|
-
return { $state:
|
|
62
|
+
function x(p) {
|
|
63
|
+
const I = p.state;
|
|
64
|
+
function $(e) {
|
|
65
|
+
return { $state: e };
|
|
66
66
|
}
|
|
67
|
-
function
|
|
68
|
-
return { $bindState:
|
|
67
|
+
function h(e) {
|
|
68
|
+
return { $bindState: e };
|
|
69
69
|
}
|
|
70
|
-
function
|
|
71
|
-
let c =
|
|
70
|
+
function m(e, ...a) {
|
|
71
|
+
let c = e[0];
|
|
72
72
|
for (let d = 0; d < a.length; d += 1) {
|
|
73
|
-
const
|
|
74
|
-
|
|
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(
|
|
79
|
-
return { $cond:
|
|
86
|
+
function b(e, a, c) {
|
|
87
|
+
return { $cond: e, $then: a, $else: c };
|
|
80
88
|
}
|
|
81
|
-
function
|
|
82
|
-
return [{ statePath:
|
|
89
|
+
function u(e, a) {
|
|
90
|
+
return [{ statePath: e, key: a }, {
|
|
83
91
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
84
|
-
$(
|
|
85
|
-
return { $item:
|
|
92
|
+
$(r) {
|
|
93
|
+
return { $item: r };
|
|
86
94
|
},
|
|
87
95
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
88
|
-
$bind(
|
|
89
|
-
return { $bindItem:
|
|
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(
|
|
98
|
-
return
|
|
105
|
+
function w(e) {
|
|
106
|
+
return g(e, I);
|
|
99
107
|
}
|
|
100
108
|
return {
|
|
101
|
-
$state:
|
|
102
|
-
$bindState:
|
|
103
|
-
$template:
|
|
109
|
+
$state: $,
|
|
110
|
+
$bindState: h,
|
|
111
|
+
$template: m,
|
|
104
112
|
$cond: b,
|
|
105
|
-
repeat:
|
|
113
|
+
repeat: u,
|
|
106
114
|
render: w
|
|
107
115
|
};
|
|
108
116
|
}
|
|
109
117
|
export {
|
|
110
|
-
|
|
111
|
-
|
|
118
|
+
x as createSpec,
|
|
119
|
+
g as renderElementTree
|
|
112
120
|
};
|
|
113
121
|
//# sourceMappingURL=spec.js.map
|
package/dist/core/spec.js.map
CHANGED
|
@@ -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":"AAkEO,SAASA,EAAkBC,GAAmBC,GAA0B;AAC7E,QAAMC,IAA0C,CAAA,GAC1CC,wBAAkB,IAAA,GAClBC,wBAAiB,QAAA,GACjBC,wBAAc,QAAA,GACdC,wBAAc,IAAA;AACpB,MAAIC,IAAkB;AAEtB,WAASC,EACPC,GACAC,IAAO,oBAAI,WACL;AAXH,QAAAC;AAYH,UAAMC,IAAaH;AACnB,QAAIC,EAAK,IAAIE,CAAU;AACrB;AAEF,IAAAF,EAAK,IAAIE,CAAU;AAEnB,UAAMC,IAAIJ;AACV,QAAII,EAAE,OAAO,QAAW;AACtB,YAAMC,IAAWX,EAAY,IAAIU,EAAE,EAAE;AACrC,UAAIC,KAAYA,MAAaF;AAC3B,cAAM,IAAI,MAAM,yBAAyBC,EAAE,EAAE,EAAE;AAEjD,MAAAV,EAAY,IAAIU,EAAE,IAAID,CAAU,GAChCN,EAAQ,IAAIO,EAAE,EAAE;AAAA,IAClB;AAEA,KAAAF,IAAAE,EAAE,aAAF,QAAAF,EAAY,QAAQ,CAAAI,MAASP,EAAmBO,GAAOL,CAAI,IAC3D,OAAO,OAAOG,EAAE,SAAS,CAAA,CAAE,EAAE;AAAA,MAAQ,OACnCG,EAAa,QAAQ,OAASR,EAAmBO,GAAOL,CAAI,CAAC;AAAA,IAAA;AAAA,EAEjE;AAEA,WAASO,IAA8B;AACrC,QAAIC;AACJ;AACE,MAAAA,IAAK,WAAWX,CAAe,IAC/BA,KAAmB;AAAA,WACZD,EAAQ,IAAIY,CAAE;AAEvB,WAAAZ,EAAQ,IAAIY,CAAE,GACPA;AAAA,EACT;AAEA,WAASC,EAAUV,GAA2B;AAC5C,UAAMG,IAAaH,GACbK,IAAWV,EAAW,IAAIQ,CAAU;AAC1C,QAAIE;AACF,aAAOA;AAIT,UAAMI,IADIT,EACG,MAAMQ,EAAA;AACnB,WAAAb,EAAW,IAAIQ,GAAYM,CAAE,GACtBA;AAAA,EACT;AAEA,WAASE,EAAQX,GAA2B;AAC1C,UAAMG,IAAaH,GACbS,IAAKC,EAAUV,CAAI;AACzB,QAAIJ,EAAQ,IAAIO,CAAU;AACxB,aAAOM;AAET,IAAAb,EAAQ,IAAIO,CAAU;AAEtB,UAAMC,IAAIJ,GACJY,IAAqBR,EAAE,WACzBA,EAAE,SAAS,IAAI,CAAAE,MAASK,EAAQL,CAAK,CAAC,IACtC,CAAA,GAEEO,IAA6B;AAAA,MACjC,MAAMT,EAAE;AAAA,MACR,OAAOA,EAAE;AAAA,MACT,UAAUQ;AAAA,IAAA;AAEZ,WAAIR,EAAE,UACJS,EAAY,QAAQ,OAAO;AAAA,MACzB,OAAO,QAAQT,EAAE,KAAK,EAAE,IAAI,CAAC,CAACU,GAAMP,CAAY,MAAM;AAAA,QACpDO;AAAA,QACAP,EAAa,IAAI,CAAAD,MAASK,EAAQL,CAAK,CAAC;AAAA,MAAA,CACzC;AAAA,IAAA,IAIDF,EAAE,YAAY,WAChBS,EAAY,UAAUT,EAAE,UAEtBA,EAAE,OACJS,EAAY,KAAKT,EAAE,KAEjBA,EAAE,UACJS,EAAY,QAAQT,EAAE,QAEpBA,EAAE,WACJS,EAAY,SAAST,EAAE,SAGzBX,EAASgB,CAAE,IAAII,GACRJ;AAAA,EACT;AAEA,EAAAV,EAAmBR,CAAI;AACvB,QAAMwB,IAASJ,EAAQpB,CAAI;AAE3B,SAAO,KAAK;AAAA,IACV,KAAK,UAAU;AAAA,MACb,MAAMwB;AAAA,MACN,UAAAtB;AAAA,MACA,OAAAD;AAAA,IAAA,CACD;AAAA,EAAA;AAEL;AAqCO,SAASwB,EAAkCC,GAE1B;AACtB,QAAMC,IAAeD,EAAO;AAE5B,WAASE,EAAOC,GAAuB;AACrC,WAAO,EAAE,QAAQA,EAAA;AAAA,EACnB;AAEA,WAASC,EAAWD,GAAuB;AACzC,WAAO,EAAE,YAAYA,EAAA;AAAA,EACvB;AAMA,WAASE,EACPC,MACGC,GACM;AACT,QAAIC,IAASF,EAAQ,CAAC;AACtB,aAASG,IAAI,GAAGA,IAAIF,EAAO,QAAQE,KAAK,GAAG;AACzC,YAAMC,IAAMH,EAAOE,CAAC;AACpB,UAAIC,KAAQ;AACV,QAAAF,KAAU;AAAA,eAEV,OAAOE,KAAQ,YACf,YAAYA,KACZ,OAAOA,EAAI,UAAW;AAEtB,QAAAF,KAAU,MAAME,EAAI,MAAM;AAAA;AAE1B,cAAM,IAAI;AAAA,UACR;AAAA,QAAA;AAGJ,MAAAF,KAAUF,EAAQG,IAAI,CAAC;AAAA,IACzB;AACA,WAAO,EAAE,WAAWD,EAAA;AAAA,EACtB;AAEA,WAASG,EAAMC,GAAoBC,GAAeC,GAAyB;AACzE,WAAO,EAAE,OAAOF,GAAW,OAAOC,GAAM,OAAOC,EAAA;AAAA,EACjD;AASA,WAASC,EACPC,GACAC,GACkC;AAkBlC,WAAO,CAjBe,EAAE,WAAAD,GAAW,KAAAC,EAAA,GAES;AAAA;AAAA,MAE1C,EAAEd,GAAmB;AACnB,eAAO,EAAE,OAAOA,EAAA;AAAA,MAClB;AAAA;AAAA,MAEA,MAAMA,GAAmB;AACvB,eAAO,EAAE,WAAWA,EAAA;AAAA,MACtB;AAAA;AAAA,MAEA,SAAc;AACZ,eAAO,EAAE,QAAQ,GAAA;AAAA,MACnB;AAAA,IAAA,CAGiC;AAAA,EACrC;AAEA,WAASe,EAAO5C,GAA6B;AAC3C,WAAOD,EAAkBC,GAAM2B,CAAY;AAAA,EAC7C;AAEA,SAAO;AAAA,IACL,QAAAC;AAAA,IACA,YAAAE;AAAA,IACA,WAAAC;AAAA,IACA,OAAAM;AAAA,IACA,QAAAI;AAAA,IACA,QAAAG;AAAA,EAAA;AAEJ;"}
|
package/dist/docs/concepts.md
CHANGED
|
@@ -308,28 +308,27 @@ Example:
|
|
|
308
308
|
}
|
|
309
309
|
```
|
|
310
310
|
|
|
311
|
-
Use templates when a string prop needs runtime interpolation from state
|
|
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
|
|
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
|
-
"
|
|
328
|
-
|
|
329
|
-
"
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
189
|
+
VStack({
|
|
190
190
|
repeat: todoRepeat,
|
|
191
|
-
props: {
|
|
192
|
-
|
|
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.
|
|
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?)`
|
|
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
|
-
|
|
256
|
+
VStack({
|
|
257
257
|
repeat: todoRepeat,
|
|
258
|
-
props: {
|
|
259
|
-
|
|
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
|
-
"
|
|
273
|
-
"text": { "$item": "title" }
|
|
274
|
-
}
|
|
278
|
+
"children": ["todo-card"]
|
|
275
279
|
}
|
|
276
280
|
```
|
|
277
281
|
|
|
278
|
-
Use `todo.$bind('field')` only when
|
|
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
|
|
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
|
|
1286
|
-
// Renders as: { "$state": "user
|
|
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
|
|
1297
|
-
// Renders as: { "$bindState": "user
|
|
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
|
|
1308
|
-
// Renders as: { "$template": "Hello \${user
|
|
1304
|
+
const greeting = $template\`Hello \${$state('/user/name')}!\`;
|
|
1305
|
+
// Renders as: { "$template": "Hello \${/user/name}!" }
|
|
1309
1306
|
\`\`\`
|
|
1310
1307
|
|
|
1311
|
-
Template interpolations
|
|
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
|
|
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
|
|
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
|
|
1367
|
+
const todoList = VStack({
|
|
1371
1368
|
repeat: todoRepeat,
|
|
1372
|
-
props: {
|
|
1373
|
-
|
|
1374
|
-
},
|
|
1369
|
+
props: { gap: 'space300' },
|
|
1370
|
+
children: [Text({ props: { text: todo.$('text') } })],
|
|
1375
1371
|
});
|
|
1376
1372
|
\`\`\`
|
|
1377
1373
|
|