@sentientui/core 0.32.0 → 0.34.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 (52) hide show
  1. package/dist/chunk-3FKD44SF.mjs +2 -0
  2. package/dist/chunk-3FKD44SF.mjs.map +1 -0
  3. package/dist/chunk-DGRAS5VP.mjs +2 -0
  4. package/dist/chunk-DGRAS5VP.mjs.map +1 -0
  5. package/dist/{index-CgkImSaM.d.ts → index-C2EOL-_c.d.cts} +43 -4
  6. package/dist/{index-COl_pfNm.d.cts → index-DrMXbLKP.d.ts} +43 -4
  7. package/dist/index-engagement.js +1 -1
  8. package/dist/index-engagement.js.map +1 -1
  9. package/dist/index-engagement.mjs +1 -1
  10. package/dist/index-engagement.mjs.map +1 -1
  11. package/dist/index-graph.d.cts +6 -4
  12. package/dist/index-graph.d.ts +6 -4
  13. package/dist/index-graph.js +1 -1
  14. package/dist/index-graph.js.map +1 -1
  15. package/dist/index-graph.mjs +1 -1
  16. package/dist/index-graph.mjs.map +1 -1
  17. package/dist/index-local.d.cts +4 -2
  18. package/dist/index-local.d.ts +4 -2
  19. package/dist/index-region.d.cts +40 -0
  20. package/dist/index-region.d.ts +40 -0
  21. package/dist/index-region.js +2 -0
  22. package/dist/index-region.js.map +1 -0
  23. package/dist/index-region.mjs +2 -0
  24. package/dist/index-region.mjs.map +1 -0
  25. package/dist/index-server.d.cts +74 -3
  26. package/dist/index-server.d.ts +74 -3
  27. package/dist/index-server.js +1 -1
  28. package/dist/index-server.js.map +1 -1
  29. package/dist/index-server.mjs +1 -1
  30. package/dist/index-server.mjs.map +1 -1
  31. package/dist/index-style-sample.d.cts +12 -0
  32. package/dist/index-style-sample.d.ts +12 -0
  33. package/dist/index-style-sample.js +2 -0
  34. package/dist/index-style-sample.js.map +1 -0
  35. package/dist/index-style-sample.mjs +2 -0
  36. package/dist/index-style-sample.mjs.map +1 -0
  37. package/dist/index.d.cts +4 -2
  38. package/dist/index.d.ts +4 -2
  39. package/dist/index.js +1 -1
  40. package/dist/index.js.map +1 -1
  41. package/dist/index.mjs +1 -1
  42. package/dist/region-skeleton-CQ4yhVw1.d.cts +56 -0
  43. package/dist/region-skeleton-CQ4yhVw1.d.ts +56 -0
  44. package/dist/session-meta-CWGtzFOQ.d.ts +226 -0
  45. package/dist/session-meta-KwDqU9a8.d.cts +226 -0
  46. package/dist/style-vocabulary-BqviEw9O.d.cts +285 -0
  47. package/dist/style-vocabulary-BqviEw9O.d.ts +285 -0
  48. package/package.json +11 -1
  49. package/dist/chunk-EVYMV2C6.mjs +0 -2
  50. package/dist/chunk-EVYMV2C6.mjs.map +0 -1
  51. package/dist/session-meta-DydKfQiR.d.cts +0 -416
  52. package/dist/session-meta-DydKfQiR.d.ts +0 -416
@@ -0,0 +1,285 @@
1
+ /**
2
+ * Composition Blocks (spec: 2026-08-20-nocode-composition-variants-design.md §4).
3
+ *
4
+ * A bounded, TYPED component tree — never HTML — that a registry arm may carry
5
+ * (`published_config.arms[].blocks`). The vocabulary is the whitelist: every
6
+ * prop value is an enumerated token, validated server-side before publish
7
+ * (apps/api/src/domain/composition-blocks.ts) and rendered client-side through
8
+ * document.createElement + property assignment only. No innerHTML/outerHTML/
9
+ * insertAdjacentHTML exists anywhere on this path — the security property is
10
+ * preserved by never accepting HTML, not by sanitizing it, which is why there
11
+ * is no sanitizer to keep honest.
12
+ *
13
+ * Token lists live here (not in the API domain like SlotOps' mirrors) because
14
+ * three parties must agree byte-for-byte: the server validator, the snippet
15
+ * renderer, and eventually the React renderer (§11) — a drifted copy would let
16
+ * a published arm fail to render, which the fail-safe turns into an invisibly
17
+ * missing section, not an error.
18
+ */
19
+ declare const BLOCK_GAPS: readonly ["none", "sm", "md", "lg"];
20
+ declare const BLOCK_ALIGNS: readonly ["start", "center", "end", "stretch"];
21
+ declare const BLOCK_JUSTIFIES: readonly ["start", "center", "end", "between"];
22
+ declare const BLOCK_SIZES: readonly ["sm", "md", "lg"];
23
+ declare const BLOCK_WEIGHTS: readonly ["normal", "medium", "bold"];
24
+ declare const BLOCK_TONES: readonly ["default", "muted", "accent"];
25
+ declare const BLOCK_EMPHASES: readonly ["primary", "secondary", "ghost"];
26
+ declare const BLOCK_TEXT_ALIGNS: readonly ["left", "center", "right"];
27
+ declare const BLOCK_RATIOS: readonly ["auto", "square", "landscape", "wide"];
28
+ declare const BLOCK_FITS: readonly ["cover", "contain"];
29
+ declare const BLOCK_GRID_COLUMNS: readonly [2, 3, 4];
30
+ declare const BLOCK_HEADING_LEVELS: readonly [1, 2, 3, 4];
31
+ declare const BLOCK_SURFACES: readonly ["default", "raised"];
32
+ declare const BLOCK_PADS: readonly ["none", "sm", "md", "lg"];
33
+ declare const BLOCK_MAX_WIDTHS: readonly ["measure"];
34
+ type BlockGap = (typeof BLOCK_GAPS)[number];
35
+ type BlockAlign = (typeof BLOCK_ALIGNS)[number];
36
+ type BlockJustify = (typeof BLOCK_JUSTIFIES)[number];
37
+ type BlockSize = (typeof BLOCK_SIZES)[number];
38
+ type BlockWeight = (typeof BLOCK_WEIGHTS)[number];
39
+ type BlockTone = (typeof BLOCK_TONES)[number];
40
+ type BlockEmphasis = (typeof BLOCK_EMPHASES)[number];
41
+ type BlockTextAlign = (typeof BLOCK_TEXT_ALIGNS)[number];
42
+ type BlockRatio = (typeof BLOCK_RATIOS)[number];
43
+ type BlockFit = (typeof BLOCK_FITS)[number];
44
+ type BlockSurface = (typeof BLOCK_SURFACES)[number];
45
+ type BlockPad = (typeof BLOCK_PADS)[number];
46
+ type BlockMaxWidth = (typeof BLOCK_MAX_WIDTHS)[number];
47
+ /** Flex row/column container. `surface: 'raised'` renders it as a card
48
+ * (palette surface bg + border hairline + radius + readable text pairing);
49
+ * a raised stack with no `pad` defaults to `md` — a zero-padding card is a
50
+ * design bug both renderers refuse to reproduce. */
51
+ type StackBlock = {
52
+ type: 'stack';
53
+ direction: 'row' | 'column';
54
+ children: BlockNode[];
55
+ gap?: BlockGap;
56
+ align?: BlockAlign;
57
+ justify?: BlockJustify;
58
+ wrap?: boolean;
59
+ surface?: BlockSurface;
60
+ pad?: BlockPad;
61
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
62
+ * renders with exactly that class list and none of the palette styling
63
+ * below; when it doesn't (entry dropped), the palette styling stands. */
64
+ like?: string;
65
+ };
66
+ /** 2–4 equal-column grid container. */
67
+ type GridBlock = {
68
+ type: 'grid';
69
+ columns: (typeof BLOCK_GRID_COLUMNS)[number];
70
+ children: BlockNode[];
71
+ gap?: BlockGap;
72
+ align?: BlockAlign;
73
+ pad?: BlockPad;
74
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
75
+ * renders with exactly that class list and none of the palette styling
76
+ * below; when it doesn't (entry dropped), the palette styling stands. */
77
+ like?: string;
78
+ };
79
+ /** Paragraph / label. `maxWidth: 'measure'` caps long copy at a readable 65ch. */
80
+ type TextBlock = {
81
+ type: 'text';
82
+ value: string;
83
+ size?: BlockSize;
84
+ weight?: BlockWeight;
85
+ tone?: BlockTone;
86
+ align?: BlockTextAlign;
87
+ maxWidth?: BlockMaxWidth;
88
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
89
+ * renders with exactly that class list and none of the palette styling
90
+ * below; when it doesn't (entry dropped), the palette styling stands. */
91
+ like?: string;
92
+ };
93
+ /** h2–h4; h1 only in a compose arm replacing the region that holds the page's h1. */
94
+ type HeadingBlock = {
95
+ type: 'heading';
96
+ value: string;
97
+ level: (typeof BLOCK_HEADING_LEVELS)[number];
98
+ size?: BlockSize;
99
+ align?: BlockTextAlign;
100
+ maxWidth?: BlockMaxWidth;
101
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
102
+ * renders with exactly that class list and none of the palette styling
103
+ * below; when it doesn't (entry dropped), the palette styling stands. */
104
+ like?: string;
105
+ };
106
+ /** Link styled as a button. `tag` feeds agent legibility (agentDataByVariant). */
107
+ type ButtonBlock = {
108
+ type: 'button';
109
+ label: string;
110
+ href: string;
111
+ emphasis?: BlockEmphasis;
112
+ size?: BlockSize;
113
+ tag?: string;
114
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
115
+ * renders with exactly that class list and none of the palette styling
116
+ * below; when it doesn't (entry dropped), the palette styling stands. */
117
+ like?: string;
118
+ };
119
+ /** Inline text link. */
120
+ type LinkBlock = {
121
+ type: 'link';
122
+ label: string;
123
+ href: string;
124
+ tag?: string;
125
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
126
+ * renders with exactly that class list and none of the palette styling
127
+ * below; when it doesn't (entry dropped), the palette styling stands. */
128
+ like?: string;
129
+ };
130
+ /** Image. `alt` is required; empty only with an explicit `decorative: true`. */
131
+ type ImageBlock = {
132
+ type: 'image';
133
+ src: string;
134
+ alt: string;
135
+ decorative?: boolean;
136
+ ratio?: BlockRatio;
137
+ fit?: BlockFit;
138
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
139
+ * renders with exactly that class list and none of the palette styling
140
+ * below; when it doesn't (entry dropped), the palette styling stands. */
141
+ like?: string;
142
+ };
143
+ /** Eyebrow / pill. */
144
+ type BadgeBlock = {
145
+ type: 'badge';
146
+ value: string;
147
+ tone?: BlockTone;
148
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
149
+ * renders with exactly that class list and none of the palette styling
150
+ * below; when it doesn't (entry dropped), the palette styling stands. */
151
+ like?: string;
152
+ };
153
+ /** Vertical rhythm. */
154
+ type SpacerBlock = {
155
+ type: 'spacer';
156
+ size: BlockSize;
157
+ };
158
+ /** Section separation — a 1px hairline in the palette border color. No props:
159
+ * anything a divider could be configured with is a styling decision, and
160
+ * styling decisions live in tokens, not on nodes. */
161
+ type DividerBlock = {
162
+ type: 'divider';
163
+ };
164
+ declare const FORM_FIELD_KINDS: readonly ["input", "textarea", "select"];
165
+ declare const FORM_INPUT_TYPES: readonly ["text", "email", "number", "tel"];
166
+ declare const MAX_FORM_FIELDS = 5;
167
+ declare const MAX_FORM_SELECT_OPTIONS = 8;
168
+ /** One field of a form block. Fields are props, not child blocks, so an input
169
+ * can never appear outside a form — the constraint is structural, no
170
+ * validator has to chase it. */
171
+ type FormField = {
172
+ kind: (typeof FORM_FIELD_KINDS)[number];
173
+ /** Slug key for the values object handed to onFormSubmit. */
174
+ name: string;
175
+ /** Visible label — required, a11y is not optional. */
176
+ label: string;
177
+ /** input fields only. Never password/file/hidden — the closed list is the guarantee. */
178
+ inputType?: (typeof FORM_INPUT_TYPES)[number];
179
+ required?: boolean;
180
+ placeholder?: string;
181
+ /** select fields only: 2–MAX_FORM_SELECT_OPTIONS plain-text options. */
182
+ options?: string[];
183
+ };
184
+ /** Lead/contact form. Submit fires `submitGoal` (a project goal) and hands the
185
+ * values to the developer's onFormSubmit — field values never reach Sentient.
186
+ * At most one form per tree; a form is a leaf (no children). */
187
+ type FormBlock = {
188
+ type: 'form';
189
+ submitGoal: string;
190
+ submitLabel: string;
191
+ fields: FormField[];
192
+ emphasis?: BlockEmphasis;
193
+ };
194
+ type BlockNode = StackBlock | GridBlock | TextBlock | HeadingBlock | ButtonBlock | LinkBlock | ImageBlock | BadgeBlock | SpacerBlock | DividerBlock | FormBlock;
195
+ /** The derived site palette (spec §4 "Colour and type: derived, not chosen").
196
+ * Sampled by the on-site editor from the live page's own buttons — computed
197
+ * styles, so values are plain colors (rgb/hex), never var()/url() — validated
198
+ * server-side, stored per project, and served with the decision so injected
199
+ * blocks render in the merchant's own primary color and corner radius.
200
+ * Absent → the renderer's neutral inherit-first defaults. */
201
+ type SitePalette = {
202
+ primaryBg: string;
203
+ primaryText: string;
204
+ radius: string;
205
+ /** Brand accent — resolves `tone: 'accent'` and secondary/ghost button color.
206
+ * Optional: sites tokenized before brand-token extraction shipped carry
207
+ * only the three fields above, and every renderer keeps its neutral
208
+ * fallback for them. */
209
+ accent?: string;
210
+ /** Readable text color on the accent (contrast-derived when not declared). */
211
+ accentText?: string;
212
+ /** Card/section background. */
213
+ surface?: string;
214
+ /** Readable text color on the surface (contrast-derived when not declared).
215
+ * Resolves the text pairing of `surface: 'raised'` stacks. */
216
+ surfaceText?: string;
217
+ /** Hairline border color (form fields, dividers). */
218
+ border?: string;
219
+ /** Muted text color — resolves `tone: 'muted'` (fallback: opacity 0.7). */
220
+ muted?: string;
221
+ };
222
+ declare const MAX_BLOCK_NODES = 64;
223
+ declare const MAX_BLOCK_DEPTH = 5;
224
+ declare const MAX_BLOCK_CHILDREN = 12;
225
+ declare const MAX_BLOCK_ARMS = 4;
226
+ declare const MAX_BLOCK_TEXT_LEN = 500;
227
+ /** True when the tree contains a form node at any depth. Surfaces that cannot
228
+ * render forms (snippet today, React without an onFormSubmit handler) must
229
+ * refuse the WHOLE tree — skipping just the form node would render a section
230
+ * minus its call-to-action, which looks live while converting nothing. */
231
+ declare function containsFormBlock(node: unknown): boolean;
232
+
233
+ declare const STYLE_ROLES: readonly ["button-primary", "button-secondary", "button-ghost", "link", "heading-1", "heading-2", "heading-3", "eyebrow", "text-lead", "text-body", "text-muted", "text-small", "badge", "card", "section", "image", "list"];
234
+ type StyleRole = (typeof STYLE_ROLES)[number];
235
+ /** A resolved vocabulary id. `node:k` and `role:x` are authoring forms the
236
+ * server resolves BEFORE persist — a stored or served tree only ever carries
237
+ * ids that match this. */
238
+ declare const LIKE_ID_RE: RegExp;
239
+ declare const MAX_STYLE_ENTRIES = 60;
240
+ declare const MAX_SITE_IMAGES = 40;
241
+ type StyleEntry = {
242
+ id: string;
243
+ role: StyleRole;
244
+ /** Exactly as observed on one element; validated server-side (validateClassList). */
245
+ classes: string;
246
+ /** Computed styles at observation time. Colors are what make the contrast
247
+ * gate judgeable; an entry without them can't carry text in a Redesign. */
248
+ computed: {
249
+ color?: string;
250
+ bg?: string;
251
+ bgDark?: string;
252
+ fontSize?: string;
253
+ fontWeight?: string;
254
+ radius?: string;
255
+ };
256
+ seen: {
257
+ url: string;
258
+ count: number;
259
+ at: string;
260
+ };
261
+ source: 'editor' | 'crawl' | 'skeleton';
262
+ };
263
+ type SiteImage = {
264
+ id: string;
265
+ src: string;
266
+ alt: string;
267
+ w: number;
268
+ h: number;
269
+ seenOn: string;
270
+ };
271
+ type StyleVocabulary = {
272
+ rev: string;
273
+ entries: StyleEntry[];
274
+ images: SiteImage[];
275
+ };
276
+ /** A Redesign arm: a composition tree whose visual nodes borrow site styles,
277
+ * optionally painted on a site section/card surface. */
278
+ type ComposeArm = {
279
+ surface?: {
280
+ like: string;
281
+ };
282
+ tree: BlockNode;
283
+ };
284
+
285
+ export { type SitePalette as $, type BlockTextAlign as A, BLOCK_ALIGNS as B, type BlockTone as C, type BlockWeight as D, type ButtonBlock as E, type ComposeArm as F, type DividerBlock as G, FORM_FIELD_KINDS as H, FORM_INPUT_TYPES as I, type FormBlock as J, type FormField as K, type GridBlock as L, type HeadingBlock as M, type ImageBlock as N, LIKE_ID_RE as O, type LinkBlock as P, MAX_BLOCK_ARMS as Q, MAX_BLOCK_CHILDREN as R, MAX_BLOCK_DEPTH as S, MAX_BLOCK_NODES as T, MAX_BLOCK_TEXT_LEN as U, MAX_FORM_FIELDS as V, MAX_FORM_SELECT_OPTIONS as W, MAX_SITE_IMAGES as X, MAX_STYLE_ENTRIES as Y, STYLE_ROLES as Z, type SiteImage as _, BLOCK_EMPHASES as a, type SpacerBlock as a0, type StackBlock as a1, type StyleEntry as a2, type StyleRole as a3, type StyleVocabulary as a4, type TextBlock as a5, containsFormBlock as a6, BLOCK_FITS as b, BLOCK_GAPS as c, BLOCK_GRID_COLUMNS as d, BLOCK_HEADING_LEVELS as e, BLOCK_JUSTIFIES as f, BLOCK_MAX_WIDTHS as g, BLOCK_PADS as h, BLOCK_RATIOS as i, BLOCK_SIZES as j, BLOCK_SURFACES as k, BLOCK_TEXT_ALIGNS as l, BLOCK_TONES as m, BLOCK_WEIGHTS as n, type BadgeBlock as o, type BlockAlign as p, type BlockEmphasis as q, type BlockFit as r, type BlockGap as s, type BlockJustify as t, type BlockMaxWidth as u, type BlockNode as v, type BlockPad as w, type BlockRatio as x, type BlockSize as y, type BlockSurface as z };
@@ -0,0 +1,285 @@
1
+ /**
2
+ * Composition Blocks (spec: 2026-08-20-nocode-composition-variants-design.md §4).
3
+ *
4
+ * A bounded, TYPED component tree — never HTML — that a registry arm may carry
5
+ * (`published_config.arms[].blocks`). The vocabulary is the whitelist: every
6
+ * prop value is an enumerated token, validated server-side before publish
7
+ * (apps/api/src/domain/composition-blocks.ts) and rendered client-side through
8
+ * document.createElement + property assignment only. No innerHTML/outerHTML/
9
+ * insertAdjacentHTML exists anywhere on this path — the security property is
10
+ * preserved by never accepting HTML, not by sanitizing it, which is why there
11
+ * is no sanitizer to keep honest.
12
+ *
13
+ * Token lists live here (not in the API domain like SlotOps' mirrors) because
14
+ * three parties must agree byte-for-byte: the server validator, the snippet
15
+ * renderer, and eventually the React renderer (§11) — a drifted copy would let
16
+ * a published arm fail to render, which the fail-safe turns into an invisibly
17
+ * missing section, not an error.
18
+ */
19
+ declare const BLOCK_GAPS: readonly ["none", "sm", "md", "lg"];
20
+ declare const BLOCK_ALIGNS: readonly ["start", "center", "end", "stretch"];
21
+ declare const BLOCK_JUSTIFIES: readonly ["start", "center", "end", "between"];
22
+ declare const BLOCK_SIZES: readonly ["sm", "md", "lg"];
23
+ declare const BLOCK_WEIGHTS: readonly ["normal", "medium", "bold"];
24
+ declare const BLOCK_TONES: readonly ["default", "muted", "accent"];
25
+ declare const BLOCK_EMPHASES: readonly ["primary", "secondary", "ghost"];
26
+ declare const BLOCK_TEXT_ALIGNS: readonly ["left", "center", "right"];
27
+ declare const BLOCK_RATIOS: readonly ["auto", "square", "landscape", "wide"];
28
+ declare const BLOCK_FITS: readonly ["cover", "contain"];
29
+ declare const BLOCK_GRID_COLUMNS: readonly [2, 3, 4];
30
+ declare const BLOCK_HEADING_LEVELS: readonly [1, 2, 3, 4];
31
+ declare const BLOCK_SURFACES: readonly ["default", "raised"];
32
+ declare const BLOCK_PADS: readonly ["none", "sm", "md", "lg"];
33
+ declare const BLOCK_MAX_WIDTHS: readonly ["measure"];
34
+ type BlockGap = (typeof BLOCK_GAPS)[number];
35
+ type BlockAlign = (typeof BLOCK_ALIGNS)[number];
36
+ type BlockJustify = (typeof BLOCK_JUSTIFIES)[number];
37
+ type BlockSize = (typeof BLOCK_SIZES)[number];
38
+ type BlockWeight = (typeof BLOCK_WEIGHTS)[number];
39
+ type BlockTone = (typeof BLOCK_TONES)[number];
40
+ type BlockEmphasis = (typeof BLOCK_EMPHASES)[number];
41
+ type BlockTextAlign = (typeof BLOCK_TEXT_ALIGNS)[number];
42
+ type BlockRatio = (typeof BLOCK_RATIOS)[number];
43
+ type BlockFit = (typeof BLOCK_FITS)[number];
44
+ type BlockSurface = (typeof BLOCK_SURFACES)[number];
45
+ type BlockPad = (typeof BLOCK_PADS)[number];
46
+ type BlockMaxWidth = (typeof BLOCK_MAX_WIDTHS)[number];
47
+ /** Flex row/column container. `surface: 'raised'` renders it as a card
48
+ * (palette surface bg + border hairline + radius + readable text pairing);
49
+ * a raised stack with no `pad` defaults to `md` — a zero-padding card is a
50
+ * design bug both renderers refuse to reproduce. */
51
+ type StackBlock = {
52
+ type: 'stack';
53
+ direction: 'row' | 'column';
54
+ children: BlockNode[];
55
+ gap?: BlockGap;
56
+ align?: BlockAlign;
57
+ justify?: BlockJustify;
58
+ wrap?: boolean;
59
+ surface?: BlockSurface;
60
+ pad?: BlockPad;
61
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
62
+ * renders with exactly that class list and none of the palette styling
63
+ * below; when it doesn't (entry dropped), the palette styling stands. */
64
+ like?: string;
65
+ };
66
+ /** 2–4 equal-column grid container. */
67
+ type GridBlock = {
68
+ type: 'grid';
69
+ columns: (typeof BLOCK_GRID_COLUMNS)[number];
70
+ children: BlockNode[];
71
+ gap?: BlockGap;
72
+ align?: BlockAlign;
73
+ pad?: BlockPad;
74
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
75
+ * renders with exactly that class list and none of the palette styling
76
+ * below; when it doesn't (entry dropped), the palette styling stands. */
77
+ like?: string;
78
+ };
79
+ /** Paragraph / label. `maxWidth: 'measure'` caps long copy at a readable 65ch. */
80
+ type TextBlock = {
81
+ type: 'text';
82
+ value: string;
83
+ size?: BlockSize;
84
+ weight?: BlockWeight;
85
+ tone?: BlockTone;
86
+ align?: BlockTextAlign;
87
+ maxWidth?: BlockMaxWidth;
88
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
89
+ * renders with exactly that class list and none of the palette styling
90
+ * below; when it doesn't (entry dropped), the palette styling stands. */
91
+ like?: string;
92
+ };
93
+ /** h2–h4; h1 only in a compose arm replacing the region that holds the page's h1. */
94
+ type HeadingBlock = {
95
+ type: 'heading';
96
+ value: string;
97
+ level: (typeof BLOCK_HEADING_LEVELS)[number];
98
+ size?: BlockSize;
99
+ align?: BlockTextAlign;
100
+ maxWidth?: BlockMaxWidth;
101
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
102
+ * renders with exactly that class list and none of the palette styling
103
+ * below; when it doesn't (entry dropped), the palette styling stands. */
104
+ like?: string;
105
+ };
106
+ /** Link styled as a button. `tag` feeds agent legibility (agentDataByVariant). */
107
+ type ButtonBlock = {
108
+ type: 'button';
109
+ label: string;
110
+ href: string;
111
+ emphasis?: BlockEmphasis;
112
+ size?: BlockSize;
113
+ tag?: string;
114
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
115
+ * renders with exactly that class list and none of the palette styling
116
+ * below; when it doesn't (entry dropped), the palette styling stands. */
117
+ like?: string;
118
+ };
119
+ /** Inline text link. */
120
+ type LinkBlock = {
121
+ type: 'link';
122
+ label: string;
123
+ href: string;
124
+ tag?: string;
125
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
126
+ * renders with exactly that class list and none of the palette styling
127
+ * below; when it doesn't (entry dropped), the palette styling stands. */
128
+ like?: string;
129
+ };
130
+ /** Image. `alt` is required; empty only with an explicit `decorative: true`. */
131
+ type ImageBlock = {
132
+ type: 'image';
133
+ src: string;
134
+ alt: string;
135
+ decorative?: boolean;
136
+ ratio?: BlockRatio;
137
+ fit?: BlockFit;
138
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
139
+ * renders with exactly that class list and none of the palette styling
140
+ * below; when it doesn't (entry dropped), the palette styling stands. */
141
+ like?: string;
142
+ };
143
+ /** Eyebrow / pill. */
144
+ type BadgeBlock = {
145
+ type: 'badge';
146
+ value: string;
147
+ tone?: BlockTone;
148
+ /** Borrow a site style (style-vocabulary.ts): when it resolves, the node
149
+ * renders with exactly that class list and none of the palette styling
150
+ * below; when it doesn't (entry dropped), the palette styling stands. */
151
+ like?: string;
152
+ };
153
+ /** Vertical rhythm. */
154
+ type SpacerBlock = {
155
+ type: 'spacer';
156
+ size: BlockSize;
157
+ };
158
+ /** Section separation — a 1px hairline in the palette border color. No props:
159
+ * anything a divider could be configured with is a styling decision, and
160
+ * styling decisions live in tokens, not on nodes. */
161
+ type DividerBlock = {
162
+ type: 'divider';
163
+ };
164
+ declare const FORM_FIELD_KINDS: readonly ["input", "textarea", "select"];
165
+ declare const FORM_INPUT_TYPES: readonly ["text", "email", "number", "tel"];
166
+ declare const MAX_FORM_FIELDS = 5;
167
+ declare const MAX_FORM_SELECT_OPTIONS = 8;
168
+ /** One field of a form block. Fields are props, not child blocks, so an input
169
+ * can never appear outside a form — the constraint is structural, no
170
+ * validator has to chase it. */
171
+ type FormField = {
172
+ kind: (typeof FORM_FIELD_KINDS)[number];
173
+ /** Slug key for the values object handed to onFormSubmit. */
174
+ name: string;
175
+ /** Visible label — required, a11y is not optional. */
176
+ label: string;
177
+ /** input fields only. Never password/file/hidden — the closed list is the guarantee. */
178
+ inputType?: (typeof FORM_INPUT_TYPES)[number];
179
+ required?: boolean;
180
+ placeholder?: string;
181
+ /** select fields only: 2–MAX_FORM_SELECT_OPTIONS plain-text options. */
182
+ options?: string[];
183
+ };
184
+ /** Lead/contact form. Submit fires `submitGoal` (a project goal) and hands the
185
+ * values to the developer's onFormSubmit — field values never reach Sentient.
186
+ * At most one form per tree; a form is a leaf (no children). */
187
+ type FormBlock = {
188
+ type: 'form';
189
+ submitGoal: string;
190
+ submitLabel: string;
191
+ fields: FormField[];
192
+ emphasis?: BlockEmphasis;
193
+ };
194
+ type BlockNode = StackBlock | GridBlock | TextBlock | HeadingBlock | ButtonBlock | LinkBlock | ImageBlock | BadgeBlock | SpacerBlock | DividerBlock | FormBlock;
195
+ /** The derived site palette (spec §4 "Colour and type: derived, not chosen").
196
+ * Sampled by the on-site editor from the live page's own buttons — computed
197
+ * styles, so values are plain colors (rgb/hex), never var()/url() — validated
198
+ * server-side, stored per project, and served with the decision so injected
199
+ * blocks render in the merchant's own primary color and corner radius.
200
+ * Absent → the renderer's neutral inherit-first defaults. */
201
+ type SitePalette = {
202
+ primaryBg: string;
203
+ primaryText: string;
204
+ radius: string;
205
+ /** Brand accent — resolves `tone: 'accent'` and secondary/ghost button color.
206
+ * Optional: sites tokenized before brand-token extraction shipped carry
207
+ * only the three fields above, and every renderer keeps its neutral
208
+ * fallback for them. */
209
+ accent?: string;
210
+ /** Readable text color on the accent (contrast-derived when not declared). */
211
+ accentText?: string;
212
+ /** Card/section background. */
213
+ surface?: string;
214
+ /** Readable text color on the surface (contrast-derived when not declared).
215
+ * Resolves the text pairing of `surface: 'raised'` stacks. */
216
+ surfaceText?: string;
217
+ /** Hairline border color (form fields, dividers). */
218
+ border?: string;
219
+ /** Muted text color — resolves `tone: 'muted'` (fallback: opacity 0.7). */
220
+ muted?: string;
221
+ };
222
+ declare const MAX_BLOCK_NODES = 64;
223
+ declare const MAX_BLOCK_DEPTH = 5;
224
+ declare const MAX_BLOCK_CHILDREN = 12;
225
+ declare const MAX_BLOCK_ARMS = 4;
226
+ declare const MAX_BLOCK_TEXT_LEN = 500;
227
+ /** True when the tree contains a form node at any depth. Surfaces that cannot
228
+ * render forms (snippet today, React without an onFormSubmit handler) must
229
+ * refuse the WHOLE tree — skipping just the form node would render a section
230
+ * minus its call-to-action, which looks live while converting nothing. */
231
+ declare function containsFormBlock(node: unknown): boolean;
232
+
233
+ declare const STYLE_ROLES: readonly ["button-primary", "button-secondary", "button-ghost", "link", "heading-1", "heading-2", "heading-3", "eyebrow", "text-lead", "text-body", "text-muted", "text-small", "badge", "card", "section", "image", "list"];
234
+ type StyleRole = (typeof STYLE_ROLES)[number];
235
+ /** A resolved vocabulary id. `node:k` and `role:x` are authoring forms the
236
+ * server resolves BEFORE persist — a stored or served tree only ever carries
237
+ * ids that match this. */
238
+ declare const LIKE_ID_RE: RegExp;
239
+ declare const MAX_STYLE_ENTRIES = 60;
240
+ declare const MAX_SITE_IMAGES = 40;
241
+ type StyleEntry = {
242
+ id: string;
243
+ role: StyleRole;
244
+ /** Exactly as observed on one element; validated server-side (validateClassList). */
245
+ classes: string;
246
+ /** Computed styles at observation time. Colors are what make the contrast
247
+ * gate judgeable; an entry without them can't carry text in a Redesign. */
248
+ computed: {
249
+ color?: string;
250
+ bg?: string;
251
+ bgDark?: string;
252
+ fontSize?: string;
253
+ fontWeight?: string;
254
+ radius?: string;
255
+ };
256
+ seen: {
257
+ url: string;
258
+ count: number;
259
+ at: string;
260
+ };
261
+ source: 'editor' | 'crawl' | 'skeleton';
262
+ };
263
+ type SiteImage = {
264
+ id: string;
265
+ src: string;
266
+ alt: string;
267
+ w: number;
268
+ h: number;
269
+ seenOn: string;
270
+ };
271
+ type StyleVocabulary = {
272
+ rev: string;
273
+ entries: StyleEntry[];
274
+ images: SiteImage[];
275
+ };
276
+ /** A Redesign arm: a composition tree whose visual nodes borrow site styles,
277
+ * optionally painted on a site section/card surface. */
278
+ type ComposeArm = {
279
+ surface?: {
280
+ like: string;
281
+ };
282
+ tree: BlockNode;
283
+ };
284
+
285
+ export { type SitePalette as $, type BlockTextAlign as A, BLOCK_ALIGNS as B, type BlockTone as C, type BlockWeight as D, type ButtonBlock as E, type ComposeArm as F, type DividerBlock as G, FORM_FIELD_KINDS as H, FORM_INPUT_TYPES as I, type FormBlock as J, type FormField as K, type GridBlock as L, type HeadingBlock as M, type ImageBlock as N, LIKE_ID_RE as O, type LinkBlock as P, MAX_BLOCK_ARMS as Q, MAX_BLOCK_CHILDREN as R, MAX_BLOCK_DEPTH as S, MAX_BLOCK_NODES as T, MAX_BLOCK_TEXT_LEN as U, MAX_FORM_FIELDS as V, MAX_FORM_SELECT_OPTIONS as W, MAX_SITE_IMAGES as X, MAX_STYLE_ENTRIES as Y, STYLE_ROLES as Z, type SiteImage as _, BLOCK_EMPHASES as a, type SpacerBlock as a0, type StackBlock as a1, type StyleEntry as a2, type StyleRole as a3, type StyleVocabulary as a4, type TextBlock as a5, containsFormBlock as a6, BLOCK_FITS as b, BLOCK_GAPS as c, BLOCK_GRID_COLUMNS as d, BLOCK_HEADING_LEVELS as e, BLOCK_JUSTIFIES as f, BLOCK_MAX_WIDTHS as g, BLOCK_PADS as h, BLOCK_RATIOS as i, BLOCK_SIZES as j, BLOCK_SURFACES as k, BLOCK_TEXT_ALIGNS as l, BLOCK_TONES as m, BLOCK_WEIGHTS as n, type BadgeBlock as o, type BlockAlign as p, type BlockEmphasis as q, type BlockFit as r, type BlockGap as s, type BlockJustify as t, type BlockMaxWidth as u, type BlockNode as v, type BlockPad as w, type BlockRatio as x, type BlockSize as y, type BlockSurface as z };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sentientui/core",
3
- "version": "0.32.0",
3
+ "version": "0.34.0",
4
4
  "private": false,
5
5
  "license": "MIT",
6
6
  "sideEffects": false,
@@ -37,6 +37,16 @@
37
37
  "import": "./dist/index-graph.mjs",
38
38
  "require": "./dist/index-graph.js"
39
39
  },
40
+ "./style-sample": {
41
+ "types": "./dist/index-style-sample.d.ts",
42
+ "import": "./dist/index-style-sample.mjs",
43
+ "require": "./dist/index-style-sample.js"
44
+ },
45
+ "./region": {
46
+ "types": "./dist/index-region.d.ts",
47
+ "import": "./dist/index-region.mjs",
48
+ "require": "./dist/index-region.js"
49
+ },
40
50
  "./engagement": {
41
51
  "types": "./dist/index-engagement.d.ts",
42
52
  "import": "./dist/index-engagement.mjs",