@wireweave/core 3.1.0-beta.4 → 3.1.0-beta.6

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.
@@ -0,0 +1,371 @@
1
+ /**
2
+ * GENERATED FILE — DO NOT EDIT.
3
+ *
4
+ * Derived from `src/grammar/wireframe.peggy` by `scripts/extract-grammar-elements.mjs`
5
+ * (`pnpm build:spec`). The grammar is the single source of truth for the DSL
6
+ * element set; edit the grammar and regenerate, never this file.
7
+ */
8
+ /** Every DSL element keyword, mapped to the AST node type its rule emits. */
9
+ declare const GRAMMAR_ELEMENTS: {
10
+ readonly page: "Page";
11
+ readonly layout: "Layout";
12
+ readonly component: "Component";
13
+ readonly use: "ComponentUse";
14
+ readonly slot: "Slot";
15
+ readonly header: "Header";
16
+ readonly main: "Main";
17
+ readonly footer: "Footer";
18
+ readonly sidebar: "Sidebar";
19
+ readonly row: "Row";
20
+ readonly col: "Col";
21
+ readonly stack: "Stack";
22
+ readonly relative: "Relative";
23
+ readonly card: "Card";
24
+ readonly modal: "Modal";
25
+ readonly drawer: "Drawer";
26
+ readonly accordion: "Accordion";
27
+ readonly section: "Section";
28
+ readonly text: "Text";
29
+ readonly title: "Title";
30
+ readonly link: "Link";
31
+ readonly button: "Button";
32
+ readonly input: "Input";
33
+ readonly textarea: "Textarea";
34
+ readonly select: "Select";
35
+ readonly checkbox: "Checkbox";
36
+ readonly radio: "Radio";
37
+ readonly switch: "Switch";
38
+ readonly slider: "Slider";
39
+ readonly image: "Image";
40
+ readonly placeholder: "Placeholder";
41
+ readonly avatar: "Avatar";
42
+ readonly badge: "Badge";
43
+ readonly icon: "Icon";
44
+ readonly table: "Table";
45
+ readonly list: "List";
46
+ readonly alert: "Alert";
47
+ readonly toast: "Toast";
48
+ readonly progress: "Progress";
49
+ readonly spinner: "Spinner";
50
+ readonly tooltip: "Tooltip";
51
+ readonly popover: "Popover";
52
+ readonly dropdown: "Dropdown";
53
+ readonly nav: "Nav";
54
+ readonly tabs: "Tabs";
55
+ readonly breadcrumb: "Breadcrumb";
56
+ readonly divider: "Divider";
57
+ readonly marker: "Marker";
58
+ readonly annotations: "Annotations";
59
+ readonly item: "AnnotationItem";
60
+ };
61
+ /** Union of every DSL element keyword. */
62
+ type GrammarElementName = keyof typeof GRAMMAR_ELEMENTS;
63
+ /** Union of every AST node type an element rule emits. */
64
+ type GrammarNodeType = (typeof GRAMMAR_ELEMENTS)[GrammarElementName];
65
+ /**
66
+ * Node types that exist only inside another element's block.
67
+ *
68
+ * `nav { item … }` and `nav { group { … } }` produce real nodes — they carry
69
+ * attributes, hold interaction intents and need a source location — but their
70
+ * keywords are not elements: `item` means something different in `nav`,
71
+ * `list`, `dropdown` and `annotations`, so it cannot map to one node type the
72
+ * way {@link GRAMMAR_ELEMENTS} entries do. They are addressed by node type
73
+ * instead, and the spec registry gives them their metadata that way.
74
+ */
75
+ declare const GRAMMAR_BLOCK_NODE_TYPES: readonly ["ListItem", "DropdownItem", "NavGroup", "NavItem"];
76
+ /** Union of every block-scoped node type. */
77
+ type GrammarBlockNodeType = (typeof GRAMMAR_BLOCK_NODE_TYPES)[number];
78
+ /**
79
+ * The grammar's `ChildKeyword` set: keywords that start a child element and so
80
+ * cannot be parsed back as attribute names (`AttributeName = !ChildKeyword Identifier`).
81
+ * It also covers block-scoped keywords (`columns`, `tab`, `group`) that are not
82
+ * elements of their own, and omits element keywords that are deliberately
83
+ * context-sensitive (`title`, `placeholder`, `icon` double as attribute names).
84
+ */
85
+ declare const GRAMMAR_CHILD_KEYWORDS: readonly ["page", "header", "main", "footer", "sidebar", "row", "col", "stack", "relative", "card", "modal", "drawer", "accordion", "section", "text", "link", "button", "input", "textarea", "select", "checkbox", "radio", "switch", "slider", "image", "avatar", "badge", "table", "columns", "list", "item", "alert", "toast", "progress", "spinner", "tooltip", "popover", "dropdown", "divider", "nav", "tabs", "tab", "breadcrumb", "group", "marker", "annotations", "layout", "component", "use", "fill", "slot"];
86
+
87
+ /**
88
+ * GENERATED FILE — DO NOT EDIT.
89
+ *
90
+ * Derived from `src/icons/lucide-icons.generated.ts` by `scripts/extract-icon-names.mjs`
91
+ * (`pnpm build:icon-names`). The dataset is the single source of truth for
92
+ * which glyphs exist; regenerate from it, never edit this file.
93
+ */
94
+ /**
95
+ * Every icon name the renderer can draw.
96
+ *
97
+ * Read this through `attributeFor(element, attribute)`, which is the only
98
+ * consumer that knows an icon-valued attribute from any other string-valued
99
+ * one. The flat attribute registry deliberately does not carry these values —
100
+ * see `attribute-overrides.ts`.
101
+ */
102
+ declare const LUCIDE_ICON_NAMES: readonly string[];
103
+
104
+ /**
105
+ * Types for Wireweave DSL Specification
106
+ */
107
+ /**
108
+ * Attribute value type
109
+ */
110
+ type AttributeValueType = 'boolean' | 'number' | 'string' | 'string[]' | 'object' | 'object[]' | 'enum';
111
+ /**
112
+ * Attribute definition
113
+ */
114
+ interface AttributeSpec {
115
+ /** Attribute name */
116
+ name: string;
117
+ /** Value type */
118
+ type: AttributeValueType;
119
+ /**
120
+ * Value keywords this attribute accepts, machine-readable.
121
+ *
122
+ * For `type: 'enum'` these are the whole domain. For the attributes whose
123
+ * value is *either* a keyword or something open-ended — `w="full"` or
124
+ * `w=240`, bare `wrap` or `wrap=nowrap` — they are the keyword half, and
125
+ * {@link AttributeSpec.type} names the other half. Listing them here rather
126
+ * than inside the description sentence is what lets an editor complete them.
127
+ */
128
+ values?: readonly string[];
129
+ /** Description for documentation */
130
+ description?: string;
131
+ }
132
+ /**
133
+ * A narrowing of one registry attribute, scoped to one element.
134
+ *
135
+ * {@link AttributeSpec} is a flat namespace keyed by attribute name alone, so it
136
+ * can only state what an attribute means everywhere at once. Some facts are not
137
+ * of that shape: `name` on `icon` is a glyph out of a closed 1.6k-name set,
138
+ * while `name` on `radio` is whatever string groups the radios. An override
139
+ * carries the narrower fact for the one element it holds on, and the wider one
140
+ * stays in the registry for everybody else.
141
+ *
142
+ * Narrowing only, in both directions:
143
+ * - `name` is absent from this type, so an override cannot rename an attribute
144
+ * and therefore cannot bring a name into existence that the registry has not
145
+ * already declared.
146
+ * - `values` may only shrink an existing domain, and `type` may only move to
147
+ * `enum` from an open one. `spec-override-containment.test.ts` in
148
+ * `packages/language-data` holds both, because an override that widened would
149
+ * be a second registry hiding behind a lookup function.
150
+ */
151
+ type AttributeOverride = Omit<Partial<AttributeSpec>, 'name'>;
152
+ /**
153
+ * Component category
154
+ *
155
+ * `structure` is the odd one out: its elements (`layout`, `component`, `slot`)
156
+ * declare reusable structure rather than draw anything, so editors and docs
157
+ * must not offer them as ordinary content the way they offer a `card`.
158
+ */
159
+ type ComponentCategory = 'structure' | 'layout' | 'grid' | 'container' | 'text' | 'input' | 'display' | 'data' | 'feedback' | 'overlay' | 'navigation' | 'annotation';
160
+ /**
161
+ * Component definition
162
+ */
163
+ interface ComponentSpec {
164
+ /** Component name (lowercase, as used in DSL) */
165
+ name: string;
166
+ /** AST node type (PascalCase) */
167
+ nodeType: string;
168
+ /** Component category */
169
+ category: ComponentCategory;
170
+ /** Valid attributes for this component (names only, definitions in ATTRIBUTES) */
171
+ attributes: readonly string[];
172
+ /** Whether this component can have children */
173
+ hasChildren: boolean;
174
+ /** Description for documentation */
175
+ description: string;
176
+ }
177
+
178
+ /**
179
+ * Wireweave DSL Component Definitions
180
+ *
181
+ * Metadata for every element the grammar defines.
182
+ *
183
+ * The element set itself is not declared here — it is extracted from
184
+ * `src/grammar/wireframe.peggy` into `grammar-elements.generated.ts`. This file
185
+ * only attaches metadata (category, attributes, description) to those elements,
186
+ * and the `Record<GrammarElementName, …>` key type makes that attachment total:
187
+ * a new grammar element fails to typecheck until its metadata is filled in, and
188
+ * an entry for a non-element is rejected as an excess property.
189
+ */
190
+
191
+ /**
192
+ * Every element keyword, in presentation order.
193
+ *
194
+ * `Object.keys` widens to `string[]`; the keys are exactly `GrammarElementName`
195
+ * because {@link COMPONENT_METADATA} is typed as a total record over it.
196
+ */
197
+ declare const COMPONENT_NAMES: readonly GrammarElementName[];
198
+ /**
199
+ * All valid components in Wireweave DSL
200
+ */
201
+ declare const COMPONENT_SPECS: readonly ComponentSpec[];
202
+ /**
203
+ * Set of all valid component names for quick lookup
204
+ */
205
+ declare const VALID_COMPONENT_NAMES: ReadonlySet<string>;
206
+ /**
207
+ * Map of component name to spec for quick lookup
208
+ */
209
+ declare const COMPONENT_MAP: ReadonlyMap<string, ComponentSpec>;
210
+ /**
211
+ * Specs for block-scoped nodes. Deliberately absent from {@link COMPONENT_SPECS}
212
+ * and {@link COMPONENT_MAP}: those answer "what elements can I write here", and
213
+ * `item` is not writable on its own.
214
+ */
215
+ declare const BLOCK_NODE_SPECS: readonly ComponentSpec[];
216
+ /**
217
+ * Map of AST node type to spec for quick lookup.
218
+ *
219
+ * Covers every node type the parser can emit — elements and block-scoped nodes
220
+ * alike — because a consumer that dispatches on `node.type` has no way to know
221
+ * which category a node came from. `__tests__/grammar-spec-ssot.test.ts` holds
222
+ * that coverage total against the grammar.
223
+ */
224
+ declare const NODE_TYPE_MAP: ReadonlyMap<string, ComponentSpec>;
225
+ /**
226
+ * Map of AST node type to spec, restricted to elements.
227
+ *
228
+ * The distinction from {@link NODE_TYPE_MAP} is the two different questions a
229
+ * consumer can be asking. "Can this node be resolved at all" — validation,
230
+ * attribute checking — wants every emitted type. "Is this a component the
231
+ * author placed on the screen" — element counts, category tallies, inventories
232
+ * — must exclude block-scoped nodes, or a nav's entries each get counted as
233
+ * screen elements alongside the nav itself.
234
+ */
235
+ declare const ELEMENT_NODE_TYPE_MAP: ReadonlyMap<string, ComponentSpec>;
236
+ /**
237
+ * Spec by element name — the typed lookup consumers derive their own
238
+ * per-element data from (editor tooling, docs generators).
239
+ */
240
+ declare const COMPONENT_SPEC_BY_NAME: Readonly<Record<GrammarElementName, ComponentSpec>>;
241
+ /**
242
+ * Get valid attributes for a component (by name or node type)
243
+ */
244
+ declare function getValidAttributes(componentNameOrType: string): readonly string[] | undefined;
245
+ /**
246
+ * Check if an attribute is valid for a component
247
+ */
248
+ declare function isValidAttribute(componentNameOrType: string, attributeName: string): boolean;
249
+
250
+ /**
251
+ * Wireweave DSL Attribute Definitions
252
+ *
253
+ * Complete list of all valid attributes in Wireweave DSL.
254
+ */
255
+
256
+ /**
257
+ * All valid attributes in Wireweave DSL
258
+ */
259
+ declare const ATTRIBUTE_SPECS: readonly AttributeSpec[];
260
+ /**
261
+ * Set of all valid attribute names for quick lookup
262
+ */
263
+ declare const VALID_ATTRIBUTE_NAMES: ReadonlySet<string>;
264
+ /**
265
+ * Map of attribute name to spec for quick lookup
266
+ */
267
+ declare const ATTRIBUTE_MAP: ReadonlyMap<string, AttributeSpec>;
268
+ /**
269
+ * Attributes every element accepts, because every renderer turns them into that
270
+ * element's own box: padding, margin, gap, size bounds, absolute offsets.
271
+ *
272
+ * The membership of this list is measured, not asserted.
273
+ * `@wireweave/language-data`'s `__tests__/spec-render-closure.test.ts` renders
274
+ * each element with and without each attribute it declares and fails on any pair
275
+ * that leaves the output identical — bar a short list of recorded render debt,
276
+ * which may only shrink. So an attribute only some elements honour cannot sit
277
+ * here: it belongs in {@link CONTAINER_ATTRIBUTES} or on the individual elements
278
+ * that read it. Changes to the list itself are caught by
279
+ * `__tests__/spec-surface-baseline.ts` in the same package, in both directions:
280
+ * a name leaving this list withdraws syntax from documents already using it, and
281
+ * that is as much a failure as a name arriving unreviewed.
282
+ *
283
+ * Both gates live outside this package deliberately. A check shipped alongside
284
+ * the list it checks is the producer grading its own output, and this list is
285
+ * the thing under test.
286
+ */
287
+ declare const BOX_ATTRIBUTES: readonly string[];
288
+ /**
289
+ * Attributes only the elements that render a flex container honour — the flex
290
+ * properties themselves plus the decoration `getCommonClasses` puts on that
291
+ * container.
292
+ *
293
+ * Leaf controls (`checkbox`, `radio`, `divider`, `marker`, `annotations`) build
294
+ * their own markup and read none of these, so they declare {@link BOX_ATTRIBUTES}
295
+ * alone. Spread both lists on an element that renders a container.
296
+ */
297
+ declare const CONTAINER_ATTRIBUTES: readonly string[];
298
+ /**
299
+ * Attributes every element that can be interacted with accepts.
300
+ *
301
+ * The mirror of `InteractiveProps` in `src/ast/types.ts`: an element whose node
302
+ * extends that interface belongs in this list, and one whose node does not, does
303
+ * not. Spread it the way {@link BOX_ATTRIBUTES} is spread, so that adding an
304
+ * interaction attribute reaches every interactive element at once rather than
305
+ * six out of seven.
306
+ */
307
+ declare const INTERACTIVE_ATTRIBUTES: readonly string[];
308
+
309
+ /**
310
+ * Element-scoped attribute facts.
311
+ *
312
+ * `ATTRIBUTE_SPECS` is keyed by attribute name with no owning element, which is
313
+ * what lets an editor answer "is `gap` a real attribute" without knowing where
314
+ * the cursor is. The price is that it can hold only one answer per name, so a
315
+ * fact that is true on one element and false on the next has nowhere to live —
316
+ * the registry either states it everywhere (wrong) or nowhere (silent).
317
+ *
318
+ * This module is that missing place. It is keyed by node type first and
319
+ * attribute second, and {@link attributeFor} is the only way to read it: a
320
+ * consumer that has an element in hand gets the narrow answer, and one that has
321
+ * only a name still gets the registry's wide one.
322
+ *
323
+ * **The icon vocabulary is here on purpose, not for want of a better home.**
324
+ * `icon` is glyph-valued on all seven elements that declare it, so it looks like
325
+ * it belongs in the registry — but "in the registry" means "visible to
326
+ * element-blind consumers", and those are exactly the consumers that must not
327
+ * see it. `packages/language-data` mirrors registry `values` into the editor's
328
+ * value-keyword vocabulary, which is a single alternation matched against any
329
+ * value position; absorbing 1,667 glyph names there would colour `home` and
330
+ * `map` as language constants wherever a value can appear, in a document that
331
+ * has no icon in it. Icon names are a dataset the renderer looks names up in,
332
+ * not words of the language. Keeping them behind {@link attributeFor} is what
333
+ * keeps that distinction enforceable rather than merely stated.
334
+ *
335
+ * Keys are node types, never keywords. `item` names three different shapes
336
+ * (`NavItem`, `DropdownItem`, `ListItem`) — see the note on `BLOCK_NODE_METADATA`
337
+ * in `components.ts` — so a keyword-keyed table would silently apply one
338
+ * element's narrowing to two others. {@link attributeFor} still accepts either
339
+ * spelling and resolves it to the node type before looking here, so the two
340
+ * spellings cannot disagree.
341
+ */
342
+
343
+ /**
344
+ * Every element-scoped narrowing, keyed by node type then attribute name.
345
+ *
346
+ * Exported for the gates and for tooling that wants to enumerate the narrowings
347
+ * rather than ask about one pair. Read a single pair through
348
+ * {@link attributeFor}, which composes the narrowing onto the registry entry.
349
+ */
350
+ declare const ATTRIBUTE_OVERRIDES: Readonly<Record<string, Readonly<Record<string, AttributeOverride>>>>;
351
+ /**
352
+ * The spec of one attribute *on one element*.
353
+ *
354
+ * The element-aware counterpart to `isValidAttribute`, resolving the same way:
355
+ * either an element keyword or an AST node type identifies the element, so a
356
+ * consumer walking a parsed tree and one completing source text ask the same
357
+ * question and get the same answer.
358
+ *
359
+ * `undefined` means there is no spec to return — the element is unknown, or it
360
+ * does not accept the attribute, or the registry has never heard of the
361
+ * attribute. A caller that needs to tell those apart is asking a diagnostic
362
+ * question and should reach for the registries directly; this function answers
363
+ * "what does this attribute mean here", and all three cases answer it the same.
364
+ *
365
+ * @param componentNameOrType - element keyword (`icon`) or node type (`Icon`)
366
+ * @param attributeName - attribute as written in the source
367
+ * @returns the registry entry, narrowed by any override for this element
368
+ */
369
+ declare function attributeFor(componentNameOrType: string, attributeName: string): AttributeSpec | undefined;
370
+
371
+ export { ATTRIBUTE_MAP, ATTRIBUTE_OVERRIDES, ATTRIBUTE_SPECS, type AttributeOverride, type AttributeSpec, type AttributeValueType, BLOCK_NODE_SPECS, BOX_ATTRIBUTES, COMPONENT_MAP, COMPONENT_NAMES, COMPONENT_SPECS, COMPONENT_SPEC_BY_NAME, CONTAINER_ATTRIBUTES, type ComponentCategory, type ComponentSpec, ELEMENT_NODE_TYPE_MAP, GRAMMAR_BLOCK_NODE_TYPES, GRAMMAR_CHILD_KEYWORDS, GRAMMAR_ELEMENTS, type GrammarBlockNodeType, type GrammarElementName, type GrammarNodeType, INTERACTIVE_ATTRIBUTES, LUCIDE_ICON_NAMES, NODE_TYPE_MAP, VALID_ATTRIBUTE_NAMES, VALID_COMPONENT_NAMES, attributeFor, getValidAttributes, isValidAttribute };