@copilotkit/shared 1.80.0 → 1.81.0

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.
Files changed (125) hide show
  1. package/dist/a2ui-envelope.cjs +154 -0
  2. package/dist/a2ui-envelope.cjs.map +1 -0
  3. package/dist/a2ui-envelope.d.cts +101 -0
  4. package/dist/a2ui-envelope.d.cts.map +1 -0
  5. package/dist/a2ui-envelope.d.mts +101 -0
  6. package/dist/a2ui-envelope.d.mts.map +1 -0
  7. package/dist/a2ui-envelope.mjs +151 -0
  8. package/dist/a2ui-envelope.mjs.map +1 -0
  9. package/dist/a2ui-prompts.cjs +139 -0
  10. package/dist/a2ui-prompts.cjs.map +1 -1
  11. package/dist/a2ui-prompts.d.cts +60 -1
  12. package/dist/a2ui-prompts.d.cts.map +1 -1
  13. package/dist/a2ui-prompts.d.mts +60 -1
  14. package/dist/a2ui-prompts.d.mts.map +1 -1
  15. package/dist/a2ui-prompts.mjs +134 -1
  16. package/dist/a2ui-prompts.mjs.map +1 -1
  17. package/dist/generative-ui/basic-functions.cjs +177 -0
  18. package/dist/generative-ui/basic-functions.cjs.map +1 -0
  19. package/dist/generative-ui/basic-functions.d.cts +108 -0
  20. package/dist/generative-ui/basic-functions.d.cts.map +1 -0
  21. package/dist/generative-ui/basic-functions.d.mts +108 -0
  22. package/dist/generative-ui/basic-functions.d.mts.map +1 -0
  23. package/dist/generative-ui/basic-functions.mjs +167 -0
  24. package/dist/generative-ui/basic-functions.mjs.map +1 -0
  25. package/dist/generative-ui/child-refs.cjs +161 -0
  26. package/dist/generative-ui/child-refs.cjs.map +1 -0
  27. package/dist/generative-ui/child-refs.d.cts +68 -0
  28. package/dist/generative-ui/child-refs.d.cts.map +1 -0
  29. package/dist/generative-ui/child-refs.d.mts +68 -0
  30. package/dist/generative-ui/child-refs.d.mts.map +1 -0
  31. package/dist/generative-ui/child-refs.mjs +152 -0
  32. package/dist/generative-ui/child-refs.mjs.map +1 -0
  33. package/dist/generative-ui/is-record.cjs +10 -0
  34. package/dist/generative-ui/is-record.cjs.map +1 -0
  35. package/dist/generative-ui/is-record.mjs +9 -0
  36. package/dist/generative-ui/is-record.mjs.map +1 -0
  37. package/dist/generative-ui/prompt.cjs +91 -0
  38. package/dist/generative-ui/prompt.cjs.map +1 -0
  39. package/dist/generative-ui/prompt.d.cts +13 -0
  40. package/dist/generative-ui/prompt.d.cts.map +1 -0
  41. package/dist/generative-ui/prompt.d.mts +13 -0
  42. package/dist/generative-ui/prompt.d.mts.map +1 -0
  43. package/dist/generative-ui/prompt.mjs +90 -0
  44. package/dist/generative-ui/prompt.mjs.map +1 -0
  45. package/dist/generative-ui/render-ui-args.cjs +160 -0
  46. package/dist/generative-ui/render-ui-args.cjs.map +1 -0
  47. package/dist/generative-ui/render-ui-args.d.cts +40 -0
  48. package/dist/generative-ui/render-ui-args.d.cts.map +1 -0
  49. package/dist/generative-ui/render-ui-args.d.mts +40 -0
  50. package/dist/generative-ui/render-ui-args.d.mts.map +1 -0
  51. package/dist/generative-ui/render-ui-args.mjs +159 -0
  52. package/dist/generative-ui/render-ui-args.mjs.map +1 -0
  53. package/dist/generative-ui/types.cjs +101 -0
  54. package/dist/generative-ui/types.cjs.map +1 -0
  55. package/dist/generative-ui/types.d.cts +270 -0
  56. package/dist/generative-ui/types.d.cts.map +1 -0
  57. package/dist/generative-ui/types.d.mts +270 -0
  58. package/dist/generative-ui/types.d.mts.map +1 -0
  59. package/dist/generative-ui/types.mjs +86 -0
  60. package/dist/generative-ui/types.mjs.map +1 -0
  61. package/dist/generative-ui/validate-operation.cjs +405 -0
  62. package/dist/generative-ui/validate-operation.cjs.map +1 -0
  63. package/dist/generative-ui/validate-operation.d.cts +86 -0
  64. package/dist/generative-ui/validate-operation.d.cts.map +1 -0
  65. package/dist/generative-ui/validate-operation.d.mts +86 -0
  66. package/dist/generative-ui/validate-operation.d.mts.map +1 -0
  67. package/dist/generative-ui/validate-operation.mjs +399 -0
  68. package/dist/generative-ui/validate-operation.mjs.map +1 -0
  69. package/dist/index.cjs +63 -0
  70. package/dist/index.cjs.map +1 -1
  71. package/dist/index.d.cts +9 -2
  72. package/dist/index.d.cts.map +1 -1
  73. package/dist/index.d.mts +9 -2
  74. package/dist/index.d.mts.map +1 -1
  75. package/dist/index.mjs +9 -2
  76. package/dist/index.mjs.map +1 -1
  77. package/dist/index.umd.js +1421 -20
  78. package/dist/index.umd.js.map +1 -1
  79. package/dist/package.cjs +1 -1
  80. package/dist/package.mjs +1 -1
  81. package/dist/utils/dashboard-url.cjs +19 -0
  82. package/dist/utils/dashboard-url.cjs.map +1 -0
  83. package/dist/utils/dashboard-url.mjs +18 -0
  84. package/dist/utils/dashboard-url.mjs.map +1 -0
  85. package/dist/utils/index.cjs +2 -1
  86. package/dist/utils/index.cjs.map +1 -1
  87. package/dist/utils/index.d.cts.map +1 -1
  88. package/dist/utils/index.d.mts.map +1 -1
  89. package/dist/utils/index.mjs +2 -1
  90. package/dist/utils/index.mjs.map +1 -1
  91. package/dist/utils/inspector-learning.cjs +10 -7
  92. package/dist/utils/inspector-learning.cjs.map +1 -1
  93. package/dist/utils/inspector-learning.d.cts.map +1 -1
  94. package/dist/utils/inspector-learning.d.mts.map +1 -1
  95. package/dist/utils/inspector-learning.mjs +11 -7
  96. package/dist/utils/inspector-learning.mjs.map +1 -1
  97. package/dist/utils/inspector-metadata.cjs +2 -3
  98. package/dist/utils/inspector-metadata.cjs.map +1 -1
  99. package/dist/utils/inspector-metadata.d.cts.map +1 -1
  100. package/dist/utils/inspector-metadata.d.mts.map +1 -1
  101. package/dist/utils/inspector-metadata.mjs +3 -3
  102. package/dist/utils/inspector-metadata.mjs.map +1 -1
  103. package/package.json +1 -1
  104. package/src/__tests__/a2ui-envelope.test.ts +434 -0
  105. package/src/__tests__/a2ui-prompts.test.ts +362 -0
  106. package/src/a2ui-envelope.ts +309 -0
  107. package/src/a2ui-prompts.ts +207 -0
  108. package/src/generative-ui/__tests__/render-ui-args.test.ts +175 -0
  109. package/src/generative-ui/__tests__/validate-operation.test.ts +977 -0
  110. package/src/generative-ui/basic-functions.ts +282 -0
  111. package/src/generative-ui/child-refs.ts +210 -0
  112. package/src/generative-ui/index.ts +6 -0
  113. package/src/generative-ui/is-record.ts +4 -0
  114. package/src/generative-ui/prompt.ts +174 -0
  115. package/src/generative-ui/render-ui-args.ts +199 -0
  116. package/src/generative-ui/types.ts +314 -0
  117. package/src/generative-ui/validate-operation.ts +723 -0
  118. package/src/index.ts +15 -0
  119. package/src/utils/dashboard-url.ts +17 -0
  120. package/src/utils/index.ts +7 -1
  121. package/src/utils/inspector-learning.test.ts +58 -0
  122. package/src/utils/inspector-learning.ts +26 -5
  123. package/src/utils/inspector-metadata.test.ts +2 -1
  124. package/src/utils/inspector-metadata.ts +3 -13
  125. package/src/utils.test.ts +71 -0
@@ -0,0 +1,167 @@
1
+ //#region src/generative-ui/basic-functions.ts
2
+ /**
3
+ * The callers of an app function that names none: the renderer only, as
4
+ * in A2UI 1.0. The agent calls a function with `callRendererFunction` only
5
+ * when its declaration allows it (`"rendererOrAgent"` or `"agentOnly"`).
6
+ * The manifests and the exported catalog write the value out.
7
+ */
8
+ const GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS = "rendererOnly";
9
+ /**
10
+ * Who may call a function, from its permissions. A function that needs a
11
+ * user gesture is for the renderer only, whatever `allowedCallers` says.
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * functionCallers({}); // { renderer: true, agent: true }
16
+ * functionCallers({ allowedCallers: "rendererOnly" }); // { renderer: true, agent: false }
17
+ * functionCallers({ requiresUserActivation: true }); // { renderer: true, agent: false }
18
+ * ```
19
+ */
20
+ function functionCallers(fn) {
21
+ if (fn.requiresUserActivation) return {
22
+ renderer: true,
23
+ agent: false
24
+ };
25
+ const callers = fn.allowedCallers ?? GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS;
26
+ return {
27
+ renderer: callers !== "agentOnly",
28
+ agent: callers !== "rendererOnly"
29
+ };
30
+ }
31
+ /** Marks a table of built-in functions as callable by the renderer only. */
32
+ function rendererOnly(functions) {
33
+ return Object.fromEntries(Object.entries(functions).map(([name, info]) => [name, {
34
+ ...info,
35
+ allowedCallers: "rendererOnly"
36
+ }]));
37
+ }
38
+ /**
39
+ * The basic functions by name. A `{"@call"}` in a prop, in an event
40
+ * binding, or in a `callRendererFunction` may name any of them without a
41
+ * declaration in `createGenerativeUI({ functions })`.
42
+ */
43
+ const A2UI_BASIC_FUNCTIONS = rendererOnly({
44
+ required: {
45
+ description: "Valid when the value is not empty",
46
+ parameters: "{ value: unknown }",
47
+ returnType: "validationResult"
48
+ },
49
+ regex: {
50
+ description: "Valid when the value matches the pattern",
51
+ parameters: "{ value: string; pattern: string }",
52
+ returnType: "validationResult"
53
+ },
54
+ length: {
55
+ description: "Valid when the length of the value is within min and max",
56
+ parameters: "{ value: string; min?: number; max?: number }",
57
+ returnType: "validationResult"
58
+ },
59
+ numeric: {
60
+ description: "Valid when the value is a number within min and max",
61
+ parameters: "{ value: number; min?: number; max?: number }",
62
+ returnType: "validationResult"
63
+ },
64
+ email: {
65
+ description: "Valid when the value is an email address",
66
+ parameters: "{ value: string }",
67
+ returnType: "validationResult"
68
+ },
69
+ formatString: {
70
+ description: "Interpolates ${/path}, ${relative/path} and ${fn(arg: value)} in the value; \\${ is a literal",
71
+ parameters: "{ value: string }",
72
+ returnType: "string"
73
+ },
74
+ formatNumber: {
75
+ description: "The number in the locale of the user",
76
+ parameters: "{ value: number; decimals?: number; grouping?: boolean }",
77
+ returnType: "string"
78
+ },
79
+ formatCurrency: {
80
+ description: "The amount as money, with an ISO 4217 currency code",
81
+ parameters: "{ value: number; currency: string; decimals?: number; grouping?: boolean }",
82
+ returnType: "string"
83
+ },
84
+ formatDate: {
85
+ description: "A date or ISO string in a TR35 pattern, for example \"MMM d, yyyy\" or \"HH:mm\"",
86
+ parameters: "{ value: string | number; format: string }",
87
+ returnType: "string"
88
+ },
89
+ pluralize: {
90
+ description: "The string of the plural category of the value",
91
+ parameters: "{ value: number; zero?: string; one?: string; two?: string; few?: string; many?: string; other: string }",
92
+ returnType: "string"
93
+ },
94
+ openUrl: {
95
+ description: "Opens an http(s) URL in a new tab. Only from an event",
96
+ parameters: "{ url: string }",
97
+ returnType: "void",
98
+ requiresUserActivation: true
99
+ },
100
+ and: {
101
+ description: "True when every value is true",
102
+ parameters: "{ values: boolean[] }",
103
+ returnType: "boolean"
104
+ },
105
+ or: {
106
+ description: "True when any value is true",
107
+ parameters: "{ values: boolean[] }",
108
+ returnType: "boolean"
109
+ },
110
+ not: {
111
+ description: "The negated value",
112
+ parameters: "{ value: boolean }",
113
+ returnType: "boolean"
114
+ }
115
+ });
116
+ /**
117
+ * The value functions that CopilotKit adds to the basic catalog, because
118
+ * A2UI 1.0 has no arithmetic: `calc` evaluates an expression over named
119
+ * args, and `series` builds a computed list. A catalog may declare its own
120
+ * functions in A2UI, so these are regular catalog functions to the model;
121
+ * a renderer without them rejects the call instead of misrendering.
122
+ */
123
+ const COPILOTKIT_FUNCTIONS = rendererOnly({
124
+ calc: {
125
+ description: "The value of an arithmetic expression over the other args, by name: + - * / % ( ), comparisons, && || !, cond ? a : b, min max round floor ceil abs, 'text' + name",
126
+ parameters: "{ expression: string; [name: string]: number | string | boolean }",
127
+ returnType: "any",
128
+ extension: true
129
+ },
130
+ series: {
131
+ description: "A list of count copies of item, for chart data and template lists. Put arithmetic in ${expression} strings in item, using the loop variable (default i, counting from start, default 1) and other named args. A whole-expression string retains the result type, so \"${i * monthlyCost}\" yields a number. Arguments, including nested calc or formatString calls in item, resolve before the series loop; those calls cannot use the loop variable. Example: {\"@call\":\"series\",\"args\":{\"count\":6,\"item\":{\"month\":\"${i}\",\"cost\":\"${i * monthlyCost}\"},\"monthlyCost\":{\"@path\":\"/monthlyCost\"}}}. Omit variable to use i.",
132
+ parameters: "{ count: number; item: unknown; variable?: string; start?: number; [name: string]: unknown }",
133
+ returnType: "array",
134
+ extension: true
135
+ }
136
+ });
137
+ /** Every function a `{"@call"}` may name without a declaration: basic and CopilotKit. */
138
+ const GENERATIVE_UI_FUNCTIONS = {
139
+ ...A2UI_BASIC_FUNCTIONS,
140
+ ...COPILOTKIT_FUNCTIONS
141
+ };
142
+ /** The name of the system function that gives the index of a template item. */
143
+ const A2UI_INDEX_FUNCTION = "@index";
144
+ /** True for a built-in function name: basic, CopilotKit, or `@index`. */
145
+ function isA2UIBasicFunction(name) {
146
+ return name === A2UI_INDEX_FUNCTION || Object.prototype.hasOwnProperty.call(GENERATIVE_UI_FUNCTIONS, name);
147
+ }
148
+ /**
149
+ * True for a built-in function that a prop or a check may call: every one
150
+ * except the functions that need a user gesture.
151
+ */
152
+ function isA2UIValueFunction(name) {
153
+ if (name === A2UI_INDEX_FUNCTION) return true;
154
+ const info = Object.prototype.hasOwnProperty.call(GENERATIVE_UI_FUNCTIONS, name) ? GENERATIVE_UI_FUNCTIONS[name] : void 0;
155
+ return info !== void 0 && !info.requiresUserActivation;
156
+ }
157
+ /** `{ "@call": "<name>", "args"?: {...} }`: a function call value. */
158
+ function isCallBinding(value) {
159
+ return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value["@call"] === "string";
160
+ }
161
+ function isValidationResult(value) {
162
+ return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.valid === "boolean";
163
+ }
164
+
165
+ //#endregion
166
+ export { A2UI_BASIC_FUNCTIONS, A2UI_INDEX_FUNCTION, COPILOTKIT_FUNCTIONS, GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS, GENERATIVE_UI_FUNCTIONS, functionCallers, isA2UIBasicFunction, isA2UIValueFunction, isCallBinding, isValidationResult };
167
+ //# sourceMappingURL=basic-functions.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"basic-functions.mjs","names":[],"sources":["../../src/generative-ui/basic-functions.ts"],"sourcesContent":["/**\n * The functions of the A2UI 1.0 basic catalog, as the model and the\n * validator see them. The renderer implements them (react-core\n * `generative-ui/functions.ts`); this file holds only what both sides share:\n * the names, the short signatures for the schema the model reads, and who\n * may call each one.\n */\n\n/** What a function gives back, as A2UI 1.0 names it. */\nexport type A2UIFunctionReturnType =\n | \"string\"\n | \"number\"\n | \"boolean\"\n | \"array\"\n | \"object\"\n | \"validationResult\"\n | \"any\"\n | \"void\";\n\n/**\n * Who may call a function. The renderer calls it from an event binding or\n * as a prop value; the agent calls it with `callRendererFunction`.\n */\nexport type A2UIAllowedCallers =\n | \"rendererOnly\"\n | \"agentOnly\"\n | \"rendererOrAgent\";\n\n/**\n * The callers of an app function that names none: the renderer only, as\n * in A2UI 1.0. The agent calls a function with `callRendererFunction` only\n * when its declaration allows it (`\"rendererOrAgent\"` or `\"agentOnly\"`).\n * The manifests and the exported catalog write the value out.\n */\nexport const GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS: A2UIAllowedCallers =\n \"rendererOnly\";\n\n/** The A2UI 1.0 interface fields of a function: who calls it, and how. */\nexport interface A2UIFunctionPermissions {\n allowedCallers?: A2UIAllowedCallers;\n /**\n * True for a function that only runs from a user gesture (a click, a key\n * press). It is `rendererOnly`: the agent cannot call it, and a prop\n * cannot be bound to it.\n */\n requiresUserActivation?: boolean;\n}\n\n/**\n * Who may call a function, from its permissions. A function that needs a\n * user gesture is for the renderer only, whatever `allowedCallers` says.\n *\n * @example\n * ```ts\n * functionCallers({}); // { renderer: true, agent: true }\n * functionCallers({ allowedCallers: \"rendererOnly\" }); // { renderer: true, agent: false }\n * functionCallers({ requiresUserActivation: true }); // { renderer: true, agent: false }\n * ```\n */\nexport function functionCallers(fn: A2UIFunctionPermissions) {\n if (fn.requiresUserActivation) return { renderer: true, agent: false };\n const callers = fn.allowedCallers ?? GENERATIVE_UI_DEFAULT_ALLOWED_CALLERS;\n return {\n renderer: callers !== \"agentOnly\",\n agent: callers !== \"rendererOnly\",\n };\n}\n\nexport interface A2UIBasicFunctionInfo extends A2UIFunctionPermissions {\n description: string;\n /** The args, as a short TypeScript-like type for the compact schema. */\n parameters: string;\n returnType: A2UIFunctionReturnType;\n /** Built-in functions are value functions of the renderer. */\n allowedCallers: \"rendererOnly\";\n requiresUserActivation?: true;\n /** True for a CopilotKit function that the A2UI basic catalog lacks. */\n extension?: true;\n}\n\n/** Marks a table of built-in functions as callable by the renderer only. */\nfunction rendererOnly<Name extends string>(\n functions: Record<Name, Omit<A2UIBasicFunctionInfo, \"allowedCallers\">>,\n): Readonly<Record<Name, A2UIBasicFunctionInfo>> {\n return Object.fromEntries(\n Object.entries<Omit<A2UIBasicFunctionInfo, \"allowedCallers\">>(\n functions,\n ).map(([name, info]) => [\n name,\n { ...info, allowedCallers: \"rendererOnly\" },\n ]),\n ) as Record<Name, A2UIBasicFunctionInfo>;\n}\n\n/**\n * The basic functions by name. A `{\"@call\"}` in a prop, in an event\n * binding, or in a `callRendererFunction` may name any of them without a\n * declaration in `createGenerativeUI({ functions })`.\n */\nexport const A2UI_BASIC_FUNCTIONS: Readonly<\n Record<string, A2UIBasicFunctionInfo>\n> = rendererOnly({\n required: {\n description: \"Valid when the value is not empty\",\n parameters: \"{ value: unknown }\",\n returnType: \"validationResult\",\n },\n regex: {\n description: \"Valid when the value matches the pattern\",\n parameters: \"{ value: string; pattern: string }\",\n returnType: \"validationResult\",\n },\n length: {\n description: \"Valid when the length of the value is within min and max\",\n parameters: \"{ value: string; min?: number; max?: number }\",\n returnType: \"validationResult\",\n },\n numeric: {\n description: \"Valid when the value is a number within min and max\",\n parameters: \"{ value: number; min?: number; max?: number }\",\n returnType: \"validationResult\",\n },\n email: {\n description: \"Valid when the value is an email address\",\n parameters: \"{ value: string }\",\n returnType: \"validationResult\",\n },\n formatString: {\n description:\n \"Interpolates ${/path}, ${relative/path} and ${fn(arg: value)} in the value; \\\\${ is a literal\",\n parameters: \"{ value: string }\",\n returnType: \"string\",\n },\n formatNumber: {\n description: \"The number in the locale of the user\",\n parameters: \"{ value: number; decimals?: number; grouping?: boolean }\",\n returnType: \"string\",\n },\n formatCurrency: {\n description: \"The amount as money, with an ISO 4217 currency code\",\n parameters:\n \"{ value: number; currency: string; decimals?: number; grouping?: boolean }\",\n returnType: \"string\",\n },\n formatDate: {\n description:\n 'A date or ISO string in a TR35 pattern, for example \"MMM d, yyyy\" or \"HH:mm\"',\n parameters: \"{ value: string | number; format: string }\",\n returnType: \"string\",\n },\n pluralize: {\n description: \"The string of the plural category of the value\",\n parameters:\n \"{ value: number; zero?: string; one?: string; two?: string; few?: string; many?: string; other: string }\",\n returnType: \"string\",\n },\n openUrl: {\n description: \"Opens an http(s) URL in a new tab. Only from an event\",\n parameters: \"{ url: string }\",\n returnType: \"void\",\n requiresUserActivation: true,\n },\n and: {\n description: \"True when every value is true\",\n parameters: \"{ values: boolean[] }\",\n returnType: \"boolean\",\n },\n or: {\n description: \"True when any value is true\",\n parameters: \"{ values: boolean[] }\",\n returnType: \"boolean\",\n },\n not: {\n description: \"The negated value\",\n parameters: \"{ value: boolean }\",\n returnType: \"boolean\",\n },\n});\n\n/**\n * The value functions that CopilotKit adds to the basic catalog, because\n * A2UI 1.0 has no arithmetic: `calc` evaluates an expression over named\n * args, and `series` builds a computed list. A catalog may declare its own\n * functions in A2UI, so these are regular catalog functions to the model;\n * a renderer without them rejects the call instead of misrendering.\n */\nexport const COPILOTKIT_FUNCTIONS: Readonly<\n Record<string, A2UIBasicFunctionInfo>\n> = rendererOnly({\n calc: {\n description:\n \"The value of an arithmetic expression over the other args, by name: + - * / % ( ), comparisons, && || !, cond ? a : b, min max round floor ceil abs, 'text' + name\",\n parameters:\n \"{ expression: string; [name: string]: number | string | boolean }\",\n returnType: \"any\",\n extension: true,\n },\n // WORKAROUND(a2ui-agent-sdk 0.9.0): examples omit `variable` and use default i\n // because the Express compiler mistakes a literal `variable` key for its AST.\n // Runtime support for custom variable names is unchanged.\n // https://github.com/a2ui-project/a2ui/issues/3410\n series: {\n description:\n 'A list of count copies of item, for chart data and template lists. Put arithmetic in ${expression} strings in item, using the loop variable (default i, counting from start, default 1) and other named args. A whole-expression string retains the result type, so \"${i * monthlyCost}\" yields a number. Arguments, including nested calc or formatString calls in item, resolve before the series loop; those calls cannot use the loop variable. Example: {\"@call\":\"series\",\"args\":{\"count\":6,\"item\":{\"month\":\"${i}\",\"cost\":\"${i * monthlyCost}\"},\"monthlyCost\":{\"@path\":\"/monthlyCost\"}}}. Omit variable to use i.',\n parameters:\n \"{ count: number; item: unknown; variable?: string; start?: number; [name: string]: unknown }\",\n returnType: \"array\",\n extension: true,\n },\n});\n\n/** Every function a `{\"@call\"}` may name without a declaration: basic and CopilotKit. */\nexport const GENERATIVE_UI_FUNCTIONS: Readonly<\n Record<string, A2UIBasicFunctionInfo>\n> = { ...A2UI_BASIC_FUNCTIONS, ...COPILOTKIT_FUNCTIONS };\n\n/** The name of the system function that gives the index of a template item. */\nexport const A2UI_INDEX_FUNCTION = \"@index\";\n\n/** True for a built-in function name: basic, CopilotKit, or `@index`. */\nexport function isA2UIBasicFunction(name: string) {\n return (\n name === A2UI_INDEX_FUNCTION ||\n Object.prototype.hasOwnProperty.call(GENERATIVE_UI_FUNCTIONS, name)\n );\n}\n\n/**\n * True for a built-in function that a prop or a check may call: every one\n * except the functions that need a user gesture.\n */\nexport function isA2UIValueFunction(name: string) {\n if (name === A2UI_INDEX_FUNCTION) return true;\n const info = Object.prototype.hasOwnProperty.call(\n GENERATIVE_UI_FUNCTIONS,\n name,\n )\n ? GENERATIVE_UI_FUNCTIONS[name]\n : undefined;\n return info !== undefined && !info.requiresUserActivation;\n}\n\n/** `{ \"@call\": \"<name>\", \"args\"?: {...} }`: a function call value. */\nexport function isCallBinding(\n value: unknown,\n): value is { \"@call\": string; args?: Record<string, unknown> } {\n return (\n typeof value === \"object\" &&\n value !== null &&\n !Array.isArray(value) &&\n typeof (value as Record<string, unknown>)[\"@call\"] === \"string\"\n );\n}\n\n/** How bad a failed check is. `error` is the default; only an error blocks. */\nexport type A2UIValidationSeverity = \"error\" | \"warning\" | \"info\";\n\n/**\n * A2UI's `ValidationResult`: what a check gives. A validator function gives\n * one; a check may also bind a boolean, which the renderer coerces to one.\n * `code` names the failure for programs; `severity` says how bad it is,\n * `\"error\"` when left out. Other keys are allowed, for app validators that\n * carry more (a suggested value, a field path).\n */\nexport interface A2UIValidationResult {\n valid: boolean;\n message?: string;\n code?: string;\n severity?: A2UIValidationSeverity;\n [extra: string]: unknown;\n}\n\nexport function isValidationResult(\n value: unknown,\n): value is A2UIValidationResult {\n return (\n typeof value === \"object\" &&\n value !== null &&\n !Array.isArray(value) &&\n typeof (value as Record<string, unknown>).valid === \"boolean\"\n );\n}\n"],"mappings":";;;;;;;AAkCA,MAAa,wCACX;;;;;;;;;;;;AAwBF,SAAgB,gBAAgB,IAA6B;AAC3D,KAAI,GAAG,uBAAwB,QAAO;EAAE,UAAU;EAAM,OAAO;EAAO;CACtE,MAAM,UAAU,GAAG,kBAAkB;AACrC,QAAO;EACL,UAAU,YAAY;EACtB,OAAO,YAAY;EACpB;;;AAgBH,SAAS,aACP,WAC+C;AAC/C,QAAO,OAAO,YACZ,OAAO,QACL,UACD,CAAC,KAAK,CAAC,MAAM,UAAU,CACtB,MACA;EAAE,GAAG;EAAM,gBAAgB;EAAgB,CAC5C,CAAC,CACH;;;;;;;AAQH,MAAa,uBAET,aAAa;CACf,UAAU;EACR,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,OAAO;EACL,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,QAAQ;EACN,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,SAAS;EACP,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,OAAO;EACL,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,cAAc;EACZ,aACE;EACF,YAAY;EACZ,YAAY;EACb;CACD,cAAc;EACZ,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,gBAAgB;EACd,aAAa;EACb,YACE;EACF,YAAY;EACb;CACD,YAAY;EACV,aACE;EACF,YAAY;EACZ,YAAY;EACb;CACD,WAAW;EACT,aAAa;EACb,YACE;EACF,YAAY;EACb;CACD,SAAS;EACP,aAAa;EACb,YAAY;EACZ,YAAY;EACZ,wBAAwB;EACzB;CACD,KAAK;EACH,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,IAAI;EACF,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACD,KAAK;EACH,aAAa;EACb,YAAY;EACZ,YAAY;EACb;CACF,CAAC;;;;;;;;AASF,MAAa,uBAET,aAAa;CACf,MAAM;EACJ,aACE;EACF,YACE;EACF,YAAY;EACZ,WAAW;EACZ;CAKD,QAAQ;EACN,aACE;EACF,YACE;EACF,YAAY;EACZ,WAAW;EACZ;CACF,CAAC;;AAGF,MAAa,0BAET;CAAE,GAAG;CAAsB,GAAG;CAAsB;;AAGxD,MAAa,sBAAsB;;AAGnC,SAAgB,oBAAoB,MAAc;AAChD,QACE,SAAS,uBACT,OAAO,UAAU,eAAe,KAAK,yBAAyB,KAAK;;;;;;AAQvE,SAAgB,oBAAoB,MAAc;AAChD,KAAI,SAAS,oBAAqB,QAAO;CACzC,MAAM,OAAO,OAAO,UAAU,eAAe,KAC3C,yBACA,KACD,GACG,wBAAwB,QACxB;AACJ,QAAO,SAAS,UAAa,CAAC,KAAK;;;AAIrC,SAAgB,cACd,OAC8D;AAC9D,QACE,OAAO,UAAU,YACjB,UAAU,QACV,CAAC,MAAM,QAAQ,MAAM,IACrB,OAAQ,MAAkC,aAAa;;AAsB3D,SAAgB,mBACd,OAC+B;AAC/B,QACE,OAAO,UAAU,YACjB,UAAU,QACV,CAAC,MAAM,QAAQ,MAAM,IACrB,OAAQ,MAAkC,UAAU"}
@@ -0,0 +1,161 @@
1
+ const require_is_record = require('./is-record.cjs');
2
+
3
+ //#region src/generative-ui/child-refs.ts
4
+ /**
5
+ * How A2UI 1.0 marks a prop that holds a component reference: the JSON
6
+ * Schema of the prop is a `$ref` to one of these two common types.
7
+ * Validators and renderers find the children of a component by these refs,
8
+ * at any depth of the props schema.
9
+ */
10
+ const A2UI_COMPONENT_ID_REF = "common_types.json#/$defs/ComponentId";
11
+ const A2UI_CHILD_LIST_REF = "common_types.json#/$defs/ChildList";
12
+ /**
13
+ * The start of the `description` that marks a schema as a component
14
+ * reference before it is turned into JSON Schema. `child()` and
15
+ * `childList()` set it; a schema from another library can set a description
16
+ * that starts with the same mark to get the same effect. What follows the
17
+ * mark (after a space) stays as the description of the reference.
18
+ */
19
+ const A2UI_COMPONENT_ID_MARK = "@a2ui/ComponentId";
20
+ const A2UI_CHILD_LIST_MARK = "@a2ui/ChildList";
21
+ /** The ref kind of a JSON Schema node, or `undefined` for a plain value. */
22
+ function childRefKind(schema) {
23
+ const ref = schema.$ref;
24
+ if (ref === A2UI_COMPONENT_ID_REF) return "single";
25
+ if (ref === A2UI_CHILD_LIST_REF) return "multiple";
26
+ }
27
+ /**
28
+ * Turns the reference marks of a JSON Schema into A2UI `$ref`s, in place of
29
+ * the marked node. The mark is the `description` set by `child()` and
30
+ * `childList()`; after this, the node is `{ "$ref": "common_types.json#/..." }`.
31
+ */
32
+ function applyChildRefMarks(schema) {
33
+ const marked = (description, mark, ref) => {
34
+ if (typeof description !== "string" || !description.startsWith(mark)) return;
35
+ const rest = description.slice(mark.length).trim();
36
+ return rest === "" ? { $ref: ref } : {
37
+ $ref: ref,
38
+ description: rest
39
+ };
40
+ };
41
+ const visit = (node) => {
42
+ if (Array.isArray(node)) return node.map(visit);
43
+ if (!require_is_record.isRecord(node)) return node;
44
+ const reference = marked(node.description, A2UI_COMPONENT_ID_MARK, A2UI_COMPONENT_ID_REF) ?? marked(node.description, A2UI_CHILD_LIST_MARK, A2UI_CHILD_LIST_REF);
45
+ if (reference) return reference;
46
+ return Object.fromEntries(Object.entries(node).map(([key, value]) => [key, visit(value)]));
47
+ };
48
+ return visit(schema);
49
+ }
50
+ /**
51
+ * Every component reference in a props schema, with its path. Walks
52
+ * `properties`, array `items`, and the variants of `anyOf` / `oneOf` /
53
+ * `allOf`. A union counts as a reference only when every alternative is
54
+ * one of the same kind: a prop that is text in one branch and a child in
55
+ * another cannot be told apart from its value, so it stays data.
56
+ */
57
+ function collectChildRefs(schema) {
58
+ const refs = [];
59
+ const seen = /* @__PURE__ */ new Set();
60
+ const add = (path, kind) => {
61
+ const key = path.join("\0");
62
+ if (seen.has(key)) return;
63
+ seen.add(key);
64
+ refs.push({
65
+ path,
66
+ kind
67
+ });
68
+ };
69
+ const visit = (node, path) => {
70
+ if (!require_is_record.isRecord(node)) return;
71
+ const kind = childRefKind(node);
72
+ if (kind) return add(path, kind);
73
+ for (const list of [node.anyOf, node.oneOf]) {
74
+ if (!Array.isArray(list) || list.length === 0) continue;
75
+ const kinds = list.map((variant) => require_is_record.isRecord(variant) ? childRefKind(variant) : void 0);
76
+ const [first] = kinds;
77
+ if (first && kinds.every((k) => k === first)) add(path, first);
78
+ else if (kinds.every((k) => k === void 0)) {
79
+ const perVariant = list.map((variant) => collectChildRefs(variant));
80
+ const key = (ref) => `${ref.kind}\u0000${ref.path.join("\0")}`;
81
+ perVariant[0].filter((ref) => perVariant.every((refs) => refs.some((r) => key(r) === key(ref)))).forEach((ref) => add([...path, ...ref.path], ref.kind));
82
+ }
83
+ }
84
+ if (Array.isArray(node.allOf)) node.allOf.forEach((variant) => visit(variant, path));
85
+ if (require_is_record.isRecord(node.properties)) for (const [key, value] of Object.entries(node.properties)) visit(value, [...path, key]);
86
+ if (require_is_record.isRecord(node.items)) visit(node.items, [...path, "*"]);
87
+ };
88
+ visit(schema, []);
89
+ return refs;
90
+ }
91
+ /**
92
+ * The component ids at the references of one component node: a string id,
93
+ * a list of ids, or the `componentId` of a template, at every ref path.
94
+ * Bound or computed values are not ids and are left out.
95
+ */
96
+ function childIdsAtRefs(component, refs) {
97
+ const ids = [];
98
+ const collect = (value) => {
99
+ if (typeof value === "string") ids.push(value);
100
+ else if (Array.isArray(value)) value.forEach((id) => typeof id === "string" && ids.push(id));
101
+ else if (require_is_record.isRecord(value) && typeof value.componentId === "string") ids.push(value.componentId);
102
+ };
103
+ const visit = (value, path) => {
104
+ if (path.length === 0) return collect(value);
105
+ const [head, ...rest] = path;
106
+ if (head === "*") {
107
+ if (Array.isArray(value)) value.forEach((item) => visit(item, rest));
108
+ return;
109
+ }
110
+ if (require_is_record.isRecord(value) && Object.prototype.hasOwnProperty.call(value, head)) visit(value[head], rest);
111
+ };
112
+ for (const ref of refs) visit(component, ref.path);
113
+ return ids;
114
+ }
115
+ /**
116
+ * True when a reference of the component is bound or computed (`{"@path"}`,
117
+ * `{"@call"}`) at the ref itself or above it, so its ids are known only
118
+ * at render time.
119
+ */
120
+ function hasBoundChildRef(component, refs) {
121
+ const isDynamic = (value) => require_is_record.isRecord(value) && ("@path" in value || "@call" in value);
122
+ const visit = (value, path) => {
123
+ if (isDynamic(value)) return true;
124
+ if (path.length === 0) return false;
125
+ const [head, ...rest] = path;
126
+ if (head === "*") return Array.isArray(value) && value.some((item) => visit(item, rest));
127
+ return require_is_record.isRecord(value) && Object.prototype.hasOwnProperty.call(value, head) && visit(value[head], rest);
128
+ };
129
+ return refs.some((ref) => visit(component, ref.path));
130
+ }
131
+ /**
132
+ * Walks `value` along a ref path and replaces what sits at the end with
133
+ * `replace(found)`. Objects and arrays on the way are copied; everything
134
+ * else keeps its identity. Missing keys are left alone.
135
+ */
136
+ function mapAtChildRef(value, path, replace) {
137
+ if (path.length === 0) return replace(value);
138
+ const [head, ...rest] = path;
139
+ if (head === "*") {
140
+ if (!Array.isArray(value)) return value;
141
+ return value.map((item) => mapAtChildRef(item, rest, replace));
142
+ }
143
+ if (!require_is_record.isRecord(value) || !Object.prototype.hasOwnProperty.call(value, head)) return value;
144
+ return {
145
+ ...value,
146
+ [head]: mapAtChildRef(value[head], rest, replace)
147
+ };
148
+ }
149
+
150
+ //#endregion
151
+ exports.A2UI_CHILD_LIST_MARK = A2UI_CHILD_LIST_MARK;
152
+ exports.A2UI_CHILD_LIST_REF = A2UI_CHILD_LIST_REF;
153
+ exports.A2UI_COMPONENT_ID_MARK = A2UI_COMPONENT_ID_MARK;
154
+ exports.A2UI_COMPONENT_ID_REF = A2UI_COMPONENT_ID_REF;
155
+ exports.applyChildRefMarks = applyChildRefMarks;
156
+ exports.childIdsAtRefs = childIdsAtRefs;
157
+ exports.childRefKind = childRefKind;
158
+ exports.collectChildRefs = collectChildRefs;
159
+ exports.hasBoundChildRef = hasBoundChildRef;
160
+ exports.mapAtChildRef = mapAtChildRef;
161
+ //# sourceMappingURL=child-refs.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"child-refs.cjs","names":["isRecord"],"sources":["../../src/generative-ui/child-refs.ts"],"sourcesContent":["import type { GenerativeUIJSONSchema } from \"./types\";\nimport { isRecord } from \"./is-record\";\n\n/**\n * How A2UI 1.0 marks a prop that holds a component reference: the JSON\n * Schema of the prop is a `$ref` to one of these two common types.\n * Validators and renderers find the children of a component by these refs,\n * at any depth of the props schema.\n */\nexport const A2UI_COMPONENT_ID_REF = \"common_types.json#/$defs/ComponentId\";\nexport const A2UI_CHILD_LIST_REF = \"common_types.json#/$defs/ChildList\";\n\n/**\n * The start of the `description` that marks a schema as a component\n * reference before it is turned into JSON Schema. `child()` and\n * `childList()` set it; a schema from another library can set a description\n * that starts with the same mark to get the same effect. What follows the\n * mark (after a space) stays as the description of the reference.\n */\nexport const A2UI_COMPONENT_ID_MARK = \"@a2ui/ComponentId\";\nexport const A2UI_CHILD_LIST_MARK = \"@a2ui/ChildList\";\n\nexport type ChildRefKind = \"single\" | \"multiple\";\n\n/** One component reference in a props schema. */\nexport interface ChildRef {\n /**\n * The keys from the props root to the reference. `\"*\"` stands for the\n * items of an array. `[\"tabs\", \"*\", \"child\"]` is the `child` of each\n * entry of `tabs`.\n */\n path: readonly string[];\n kind: ChildRefKind;\n}\n\n/** The ref kind of a JSON Schema node, or `undefined` for a plain value. */\nexport function childRefKind(\n schema: GenerativeUIJSONSchema,\n): ChildRefKind | undefined {\n const ref = schema.$ref;\n if (ref === A2UI_COMPONENT_ID_REF) return \"single\";\n if (ref === A2UI_CHILD_LIST_REF) return \"multiple\";\n return undefined;\n}\n\n/**\n * Turns the reference marks of a JSON Schema into A2UI `$ref`s, in place of\n * the marked node. The mark is the `description` set by `child()` and\n * `childList()`; after this, the node is `{ \"$ref\": \"common_types.json#/...\" }`.\n */\nexport function applyChildRefMarks(\n schema: GenerativeUIJSONSchema,\n): GenerativeUIJSONSchema {\n const marked = (description: unknown, mark: string, ref: string) => {\n if (typeof description !== \"string\" || !description.startsWith(mark)) {\n return undefined;\n }\n const rest = description.slice(mark.length).trim();\n return rest === \"\" ? { $ref: ref } : { $ref: ref, description: rest };\n };\n const visit = (node: unknown): unknown => {\n if (Array.isArray(node)) return node.map(visit);\n if (!isRecord(node)) return node;\n const reference =\n marked(node.description, A2UI_COMPONENT_ID_MARK, A2UI_COMPONENT_ID_REF) ??\n marked(node.description, A2UI_CHILD_LIST_MARK, A2UI_CHILD_LIST_REF);\n if (reference) return reference;\n return Object.fromEntries(\n Object.entries(node).map(([key, value]) => [key, visit(value)]),\n );\n };\n return visit(schema) as GenerativeUIJSONSchema;\n}\n\n/**\n * Every component reference in a props schema, with its path. Walks\n * `properties`, array `items`, and the variants of `anyOf` / `oneOf` /\n * `allOf`. A union counts as a reference only when every alternative is\n * one of the same kind: a prop that is text in one branch and a child in\n * another cannot be told apart from its value, so it stays data.\n */\nexport function collectChildRefs(schema: GenerativeUIJSONSchema): ChildRef[] {\n const refs: ChildRef[] = [];\n const seen = new Set<string>();\n const add = (path: string[], kind: ChildRefKind) => {\n const key = path.join(\"\\u0000\");\n if (seen.has(key)) return;\n seen.add(key);\n refs.push({ path, kind });\n };\n const visit = (node: unknown, path: string[]) => {\n if (!isRecord(node)) return;\n const kind = childRefKind(node);\n if (kind) return add(path, kind);\n for (const list of [node.anyOf, node.oneOf]) {\n if (!Array.isArray(list) || list.length === 0) continue;\n const kinds = list.map((variant) =>\n isRecord(variant) ? childRefKind(variant) : undefined,\n );\n const [first] = kinds;\n if (first && kinds.every((k) => k === first)) add(path, first);\n else if (kinds.every((k) => k === undefined)) {\n // Objects in a union: a nested reference counts only when every\n // alternative has it at the same path with the same kind.\n const perVariant = list.map((variant) =>\n collectChildRefs(variant as GenerativeUIJSONSchema),\n );\n const key = (ref: ChildRef) =>\n `${ref.kind}\\u0000${ref.path.join(\"\\u0000\")}`;\n const shared = perVariant[0].filter((ref) =>\n perVariant.every((refs) => refs.some((r) => key(r) === key(ref))),\n );\n shared.forEach((ref) => add([...path, ...ref.path], ref.kind));\n }\n }\n if (Array.isArray(node.allOf)) {\n node.allOf.forEach((variant) => visit(variant, path));\n }\n if (isRecord(node.properties)) {\n for (const [key, value] of Object.entries(node.properties)) {\n visit(value, [...path, key]);\n }\n }\n if (isRecord(node.items)) visit(node.items, [...path, \"*\"]);\n };\n visit(schema, []);\n return refs;\n}\n\n/**\n * The component ids at the references of one component node: a string id,\n * a list of ids, or the `componentId` of a template, at every ref path.\n * Bound or computed values are not ids and are left out.\n */\nexport function childIdsAtRefs(\n component: Record<string, unknown>,\n refs: readonly ChildRef[],\n): string[] {\n const ids: string[] = [];\n const collect = (value: unknown) => {\n if (typeof value === \"string\") ids.push(value);\n else if (Array.isArray(value)) {\n value.forEach((id) => typeof id === \"string\" && ids.push(id));\n } else if (isRecord(value) && typeof value.componentId === \"string\") {\n ids.push(value.componentId);\n }\n };\n const visit = (value: unknown, path: readonly string[]) => {\n if (path.length === 0) return collect(value);\n const [head, ...rest] = path;\n if (head === \"*\") {\n if (Array.isArray(value)) value.forEach((item) => visit(item, rest));\n return;\n }\n if (isRecord(value) && Object.prototype.hasOwnProperty.call(value, head)) {\n visit(value[head], rest);\n }\n };\n for (const ref of refs) visit(component, ref.path);\n return ids;\n}\n\n/**\n * True when a reference of the component is bound or computed (`{\"@path\"}`,\n * `{\"@call\"}`) at the ref itself or above it, so its ids are known only\n * at render time.\n */\nexport function hasBoundChildRef(\n component: Record<string, unknown>,\n refs: readonly ChildRef[],\n): boolean {\n const isDynamic = (value: unknown) =>\n isRecord(value) && (\"@path\" in value || \"@call\" in value);\n const visit = (value: unknown, path: readonly string[]): boolean => {\n if (isDynamic(value)) return true;\n if (path.length === 0) return false;\n const [head, ...rest] = path;\n if (head === \"*\") {\n return Array.isArray(value) && value.some((item) => visit(item, rest));\n }\n return (\n isRecord(value) &&\n Object.prototype.hasOwnProperty.call(value, head) &&\n visit(value[head], rest)\n );\n };\n return refs.some((ref) => visit(component, ref.path));\n}\n\n/**\n * Walks `value` along a ref path and replaces what sits at the end with\n * `replace(found)`. Objects and arrays on the way are copied; everything\n * else keeps its identity. Missing keys are left alone.\n */\nexport function mapAtChildRef(\n value: unknown,\n path: readonly string[],\n replace: (found: unknown) => unknown,\n): unknown {\n if (path.length === 0) return replace(value);\n const [head, ...rest] = path;\n if (head === \"*\") {\n if (!Array.isArray(value)) return value;\n return value.map((item) => mapAtChildRef(item, rest, replace));\n }\n if (!isRecord(value) || !Object.prototype.hasOwnProperty.call(value, head)) {\n return value;\n }\n return { ...value, [head]: mapAtChildRef(value[head], rest, replace) };\n}\n"],"mappings":"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"}
@@ -0,0 +1,68 @@
1
+ import { GenerativeUIJSONSchema } from "./types.cjs";
2
+
3
+ //#region src/generative-ui/child-refs.d.ts
4
+ /**
5
+ * How A2UI 1.0 marks a prop that holds a component reference: the JSON
6
+ * Schema of the prop is a `$ref` to one of these two common types.
7
+ * Validators and renderers find the children of a component by these refs,
8
+ * at any depth of the props schema.
9
+ */
10
+ declare const A2UI_COMPONENT_ID_REF = "common_types.json#/$defs/ComponentId";
11
+ declare const A2UI_CHILD_LIST_REF = "common_types.json#/$defs/ChildList";
12
+ /**
13
+ * The start of the `description` that marks a schema as a component
14
+ * reference before it is turned into JSON Schema. `child()` and
15
+ * `childList()` set it; a schema from another library can set a description
16
+ * that starts with the same mark to get the same effect. What follows the
17
+ * mark (after a space) stays as the description of the reference.
18
+ */
19
+ declare const A2UI_COMPONENT_ID_MARK = "@a2ui/ComponentId";
20
+ declare const A2UI_CHILD_LIST_MARK = "@a2ui/ChildList";
21
+ type ChildRefKind = "single" | "multiple";
22
+ /** One component reference in a props schema. */
23
+ interface ChildRef {
24
+ /**
25
+ * The keys from the props root to the reference. `"*"` stands for the
26
+ * items of an array. `["tabs", "*", "child"]` is the `child` of each
27
+ * entry of `tabs`.
28
+ */
29
+ path: readonly string[];
30
+ kind: ChildRefKind;
31
+ }
32
+ /** The ref kind of a JSON Schema node, or `undefined` for a plain value. */
33
+ declare function childRefKind(schema: GenerativeUIJSONSchema): ChildRefKind | undefined;
34
+ /**
35
+ * Turns the reference marks of a JSON Schema into A2UI `$ref`s, in place of
36
+ * the marked node. The mark is the `description` set by `child()` and
37
+ * `childList()`; after this, the node is `{ "$ref": "common_types.json#/..." }`.
38
+ */
39
+ declare function applyChildRefMarks(schema: GenerativeUIJSONSchema): GenerativeUIJSONSchema;
40
+ /**
41
+ * Every component reference in a props schema, with its path. Walks
42
+ * `properties`, array `items`, and the variants of `anyOf` / `oneOf` /
43
+ * `allOf`. A union counts as a reference only when every alternative is
44
+ * one of the same kind: a prop that is text in one branch and a child in
45
+ * another cannot be told apart from its value, so it stays data.
46
+ */
47
+ declare function collectChildRefs(schema: GenerativeUIJSONSchema): ChildRef[];
48
+ /**
49
+ * The component ids at the references of one component node: a string id,
50
+ * a list of ids, or the `componentId` of a template, at every ref path.
51
+ * Bound or computed values are not ids and are left out.
52
+ */
53
+ declare function childIdsAtRefs(component: Record<string, unknown>, refs: readonly ChildRef[]): string[];
54
+ /**
55
+ * True when a reference of the component is bound or computed (`{"@path"}`,
56
+ * `{"@call"}`) at the ref itself or above it, so its ids are known only
57
+ * at render time.
58
+ */
59
+ declare function hasBoundChildRef(component: Record<string, unknown>, refs: readonly ChildRef[]): boolean;
60
+ /**
61
+ * Walks `value` along a ref path and replaces what sits at the end with
62
+ * `replace(found)`. Objects and arrays on the way are copied; everything
63
+ * else keeps its identity. Missing keys are left alone.
64
+ */
65
+ declare function mapAtChildRef(value: unknown, path: readonly string[], replace: (found: unknown) => unknown): unknown;
66
+ //#endregion
67
+ export { A2UI_CHILD_LIST_MARK, A2UI_CHILD_LIST_REF, A2UI_COMPONENT_ID_MARK, A2UI_COMPONENT_ID_REF, ChildRef, ChildRefKind, applyChildRefMarks, childIdsAtRefs, childRefKind, collectChildRefs, hasBoundChildRef, mapAtChildRef };
68
+ //# sourceMappingURL=child-refs.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"child-refs.d.cts","names":[],"sources":["../../src/generative-ui/child-refs.ts"],"mappings":";;;;;AASA;;;;cAAa,qBAAA;AAAA,cACA,mBAAA;;;;;AASb;;;cAAa,sBAAA;AAAA,cACA,oBAAA;AAAA,KAED,YAAA;;UAGK,QAAA;EALgB;;AAEjC;;;EASE,IAAA;EACA,IAAA,EAAM,YAAA;AAAA;;iBAIQ,YAAA,CACd,MAAA,EAAQ,sBAAA,GACP,YAAA;;;;;;iBAYa,kBAAA,CACd,MAAA,EAAQ,sBAAA,GACP,sBAAA;AAhBH;;;;;;;AAAA,iBA6CgB,gBAAA,CAAiB,MAAA,EAAQ,sBAAA,GAAyB,QAAA;;AA/BlE;;;;iBAoFgB,cAAA,CACd,SAAA,EAAW,MAAA,mBACX,IAAA,WAAe,QAAA;;;;;AAvDjB;iBAsFgB,gBAAA,CACd,SAAA,EAAW,MAAA,mBACX,IAAA,WAAe,QAAA;;;;;;iBAyBD,aAAA,CACd,KAAA,WACA,IAAA,qBACA,OAAA,GAAU,KAAA"}
@@ -0,0 +1,68 @@
1
+ import { GenerativeUIJSONSchema } from "./types.mjs";
2
+
3
+ //#region src/generative-ui/child-refs.d.ts
4
+ /**
5
+ * How A2UI 1.0 marks a prop that holds a component reference: the JSON
6
+ * Schema of the prop is a `$ref` to one of these two common types.
7
+ * Validators and renderers find the children of a component by these refs,
8
+ * at any depth of the props schema.
9
+ */
10
+ declare const A2UI_COMPONENT_ID_REF = "common_types.json#/$defs/ComponentId";
11
+ declare const A2UI_CHILD_LIST_REF = "common_types.json#/$defs/ChildList";
12
+ /**
13
+ * The start of the `description` that marks a schema as a component
14
+ * reference before it is turned into JSON Schema. `child()` and
15
+ * `childList()` set it; a schema from another library can set a description
16
+ * that starts with the same mark to get the same effect. What follows the
17
+ * mark (after a space) stays as the description of the reference.
18
+ */
19
+ declare const A2UI_COMPONENT_ID_MARK = "@a2ui/ComponentId";
20
+ declare const A2UI_CHILD_LIST_MARK = "@a2ui/ChildList";
21
+ type ChildRefKind = "single" | "multiple";
22
+ /** One component reference in a props schema. */
23
+ interface ChildRef {
24
+ /**
25
+ * The keys from the props root to the reference. `"*"` stands for the
26
+ * items of an array. `["tabs", "*", "child"]` is the `child` of each
27
+ * entry of `tabs`.
28
+ */
29
+ path: readonly string[];
30
+ kind: ChildRefKind;
31
+ }
32
+ /** The ref kind of a JSON Schema node, or `undefined` for a plain value. */
33
+ declare function childRefKind(schema: GenerativeUIJSONSchema): ChildRefKind | undefined;
34
+ /**
35
+ * Turns the reference marks of a JSON Schema into A2UI `$ref`s, in place of
36
+ * the marked node. The mark is the `description` set by `child()` and
37
+ * `childList()`; after this, the node is `{ "$ref": "common_types.json#/..." }`.
38
+ */
39
+ declare function applyChildRefMarks(schema: GenerativeUIJSONSchema): GenerativeUIJSONSchema;
40
+ /**
41
+ * Every component reference in a props schema, with its path. Walks
42
+ * `properties`, array `items`, and the variants of `anyOf` / `oneOf` /
43
+ * `allOf`. A union counts as a reference only when every alternative is
44
+ * one of the same kind: a prop that is text in one branch and a child in
45
+ * another cannot be told apart from its value, so it stays data.
46
+ */
47
+ declare function collectChildRefs(schema: GenerativeUIJSONSchema): ChildRef[];
48
+ /**
49
+ * The component ids at the references of one component node: a string id,
50
+ * a list of ids, or the `componentId` of a template, at every ref path.
51
+ * Bound or computed values are not ids and are left out.
52
+ */
53
+ declare function childIdsAtRefs(component: Record<string, unknown>, refs: readonly ChildRef[]): string[];
54
+ /**
55
+ * True when a reference of the component is bound or computed (`{"@path"}`,
56
+ * `{"@call"}`) at the ref itself or above it, so its ids are known only
57
+ * at render time.
58
+ */
59
+ declare function hasBoundChildRef(component: Record<string, unknown>, refs: readonly ChildRef[]): boolean;
60
+ /**
61
+ * Walks `value` along a ref path and replaces what sits at the end with
62
+ * `replace(found)`. Objects and arrays on the way are copied; everything
63
+ * else keeps its identity. Missing keys are left alone.
64
+ */
65
+ declare function mapAtChildRef(value: unknown, path: readonly string[], replace: (found: unknown) => unknown): unknown;
66
+ //#endregion
67
+ export { A2UI_CHILD_LIST_MARK, A2UI_CHILD_LIST_REF, A2UI_COMPONENT_ID_MARK, A2UI_COMPONENT_ID_REF, ChildRef, ChildRefKind, applyChildRefMarks, childIdsAtRefs, childRefKind, collectChildRefs, hasBoundChildRef, mapAtChildRef };
68
+ //# sourceMappingURL=child-refs.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"child-refs.d.mts","names":[],"sources":["../../src/generative-ui/child-refs.ts"],"mappings":";;;;;AASA;;;;cAAa,qBAAA;AAAA,cACA,mBAAA;;;;;AASb;;;cAAa,sBAAA;AAAA,cACA,oBAAA;AAAA,KAED,YAAA;;UAGK,QAAA;EALgB;;AAEjC;;;EASE,IAAA;EACA,IAAA,EAAM,YAAA;AAAA;;iBAIQ,YAAA,CACd,MAAA,EAAQ,sBAAA,GACP,YAAA;;;;;;iBAYa,kBAAA,CACd,MAAA,EAAQ,sBAAA,GACP,sBAAA;AAhBH;;;;;;;AAAA,iBA6CgB,gBAAA,CAAiB,MAAA,EAAQ,sBAAA,GAAyB,QAAA;;AA/BlE;;;;iBAoFgB,cAAA,CACd,SAAA,EAAW,MAAA,mBACX,IAAA,WAAe,QAAA;;;;;AAvDjB;iBAsFgB,gBAAA,CACd,SAAA,EAAW,MAAA,mBACX,IAAA,WAAe,QAAA;;;;;;iBAyBD,aAAA,CACd,KAAA,WACA,IAAA,qBACA,OAAA,GAAU,KAAA"}