@jxsuite/schema 1.5.0 → 1.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/class-schema.json CHANGED
@@ -181,6 +181,7 @@
181
181
  "resolvePaths",
182
182
  "lower",
183
183
  "emit",
184
+ "head",
184
185
  "assets",
185
186
  "mount",
186
187
  "dialect",
@@ -23,8 +23,17 @@ export const childrenValueSchema = {
23
23
  oneOf: [
24
24
  {
25
25
  items: {
26
- oneOf: [
26
+ /* `anyOf`, not `oneOf`, and SwitchNode is the reason for both halves of that.
27
+ `$defs.SwitchNode` was defined and referenced from nowhere — a node the compiler fully
28
+ renders (`shared.ts` renderSwitch) that no position in the schema admitted, so every
29
+ document with a `$switch` child failed `jx validate`. Adding the ref under `oneOf` would
30
+ have traded one break for another: a switch child that also carries `tagName` (its
31
+ container element) matches ElementDef AND SwitchNode, and "exactly one" then rejects the
32
+ form that works today. `anyOf` accepts both, and still rejects a child object that is
33
+ neither. */
34
+ anyOf: [
27
35
  { $ref: "#/$defs/ElementDef" },
36
+ { $ref: "#/$defs/SwitchNode" },
28
37
  { $ref: "#/$defs/ArrayNamespace" },
29
38
  { type: "string" },
30
39
  { type: "number" },
@@ -15,6 +15,7 @@ export const CLASS_METHOD_ROLES = [
15
15
  "resolvePaths",
16
16
  "lower",
17
17
  "emit",
18
+ "head",
18
19
  "assets",
19
20
  "mount",
20
21
  "dialect",
@@ -100,7 +100,7 @@ export const elementDefSchema = {
100
100
  src: { $ref: "#/$defs/StringOrRef" },
101
101
  style: { $ref: "#/$defs/StyleObject" },
102
102
  tabIndex: { $ref: "#/$defs/NumberOrRef" },
103
- tagName: { $ref: "#/$defs/TagName" },
103
+ tagName: { $ref: "#/$defs/ElementTagName" },
104
104
  textContent: { $ref: "#/$defs/StringOrRef" },
105
105
  title: { $ref: "#/$defs/StringOrRef" },
106
106
  type: { $ref: "#/$defs/StringOrRef" },
@@ -1,3 +1,5 @@
1
+ import { intlHelpersClause } from "../src/intl.ts";
2
+
1
3
  export const expressionPointerSchema = {
2
4
  additionalProperties: false,
3
5
  description:
@@ -199,7 +201,8 @@ export const expressionNodeSchema = {
199
201
  },
200
202
  {
201
203
  description:
202
- "Invoke a callable, pure in formula position: target is the callee pointer — a named formula entry (#/state/…) or a blessed pure global via window#/ (Math.*, JSON.*, Object.keys/values/entries, and the Intl helpers Intl/formatNumber, Intl/formatDate, Intl/formatRelativeTime) — and value is the positional argument list (the splice args-in-value precedent). Argument order follows the callee's declared parameters.",
204
+ "Invoke a callable, pure in formula position: target is the callee pointer — a named formula entry (#/state/…) or a blessed pure global via window#/ (Math.*, JSON.*, Object.keys/values/entries, and " +
205
+ `${intlHelpersClause()}) — and value is the positional argument list (the splice args-in-value precedent). Argument order follows the callee's declared parameters.`,
203
206
  not: { required: ["initial"] },
204
207
  properties: {
205
208
  operator: { $ref: "#/$defs/CallOperator" },
@@ -57,8 +57,26 @@ export const externalClassDefSchema = {
57
57
  default: {},
58
58
  description: { type: "string" },
59
59
  domain: { type: "string" },
60
- expires: { type: "string" },
61
- filter: { $ref: "#/$defs/RefObject" },
60
+ /* Widened to mirror `sort` below, because this one grab-bag of properties is shared by EVERY
61
+ state `$prototype` with no discrimination on which prototype is in play. `filter` as a
62
+ reactive `$ref` is what the built-in `Array` prototype wants; `@jxsuite/parser`'s
63
+ ContentCollection and `@jxsuite/connector`'s TableQuery both declare their own `filter` as a
64
+ rule ARRAY, and the core shape silently overrode the class's own declaration — so a document
65
+ using a documented class parameter correctly failed `jx validate` with "must be object". */
66
+ filter: {
67
+ anyOf: [
68
+ { $ref: "#/$defs/RefObject" },
69
+ { description: "A single filter object, e.g. an equality shorthand.", type: "object" },
70
+ {
71
+ description: 'Ordered filter rules, e.g. [{ field: "Slug", op: "not empty" }].',
72
+ items: { type: "object" },
73
+ type: "array",
74
+ },
75
+ ],
76
+ description:
77
+ "Filter configuration: a reactive $ref binding, a single filter object, or an ordered " +
78
+ "array of rules.",
79
+ },
62
80
  headers: { additionalProperties: { type: "string" }, type: "object" },
63
81
  indexes: {
64
82
  items: {
@@ -10,7 +10,12 @@ export const headEntrySchema = {
10
10
  },
11
11
  children: { items: { $ref: "#/$defs/HeadEntry" }, type: "array" },
12
12
  tagName: { type: "string" },
13
- textContent: { type: "string" },
13
+ textContent: {
14
+ description:
15
+ "Element content. An object is serialized to JSON inside the tag — that is how a " +
16
+ 'JSON-LD block (`<script type="application/ld+json">`) is authored.',
17
+ oneOf: [{ type: "string" }, { type: "object" }],
18
+ },
14
19
  },
15
20
  required: ["tagName"],
16
21
  type: "object",
@@ -4,6 +4,13 @@ export const imageConfigSchema = {
4
4
  formats: { items: { type: "string" }, type: "array" },
5
5
  lazyLoad: { type: "boolean" },
6
6
  optimize: { type: "boolean" },
7
+ picture: {
8
+ description:
9
+ "Wrap a multi-format image in a <picture> with one <source> per format (default true). " +
10
+ "With it off the <img> carries a srcset in the preferred format alone, which browsers " +
11
+ "that cannot decode that format will still select from.",
12
+ type: "boolean",
13
+ },
7
14
  quality: {
8
15
  properties: {
9
16
  avif: { type: "number" },
package/defs/index.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  // Leaf schemas
2
+ export { elementTagNameSchema, tagExpressionSchema } from "./tag-expression.schema";
2
3
  export { tagNameSchema } from "./tag-name.schema";
3
4
  export { stringOrRefSchema, boolOrRefSchema, numberOrRefSchema } from "./string-or-ref.schema";
4
5
  export { headEntrySchema } from "./head-entry.schema";
@@ -83,7 +84,7 @@ export {
83
84
  } from "./class-def.schema";
84
85
 
85
86
  // Project
86
- export { projectConfigSchema } from "./project-config.schema";
87
+ export { projectConfigSchema, REDIRECT_STATUSES } from "./project-config.schema";
87
88
 
88
89
  // Extensions (specs/extensions.md)
89
90
  export { extensionManifestSchema } from "./extension-manifest.schema";
@@ -1,3 +1,14 @@
1
+ import { LANGUAGE_TAG_PATTERN } from "../src/locale.ts";
2
+
3
+ /**
4
+ * The RFC 9110 §15.4 redirection statuses a static host can express. 303 preserves the "see other,
5
+ * with GET" semantics; 307 and 308 preserve the request method, which 301 and 302 historically do
6
+ * not. **200 is not here**: a host's rewrite/proxy convention is not a redirection status, and
7
+ * modelling it as one is what let the compiler emit a meta-refresh page for a rewrite. Rewrites are
8
+ * `{ destination, rewrite: true }`.
9
+ */
10
+ export const REDIRECT_STATUSES = [301, 302, 303, 307, 308] as const;
11
+
1
12
  export const projectConfigSchema = {
2
13
  description:
3
14
  "Schema for Jx project.json files. " +
@@ -126,6 +137,116 @@ export const projectConfigSchema = {
126
137
  description: "Output directory for compiled site.",
127
138
  type: "string",
128
139
  },
140
+ headers: {
141
+ additionalProperties: false,
142
+ description:
143
+ "Emit dist/_headers — the response headers only the build can know. Honored by " +
144
+ "Cloudflare Pages/Workers assets and Netlify; on the node/bun adapters the file " +
145
+ "documents what a reverse proxy in front of them must send.",
146
+ properties: {
147
+ cache: {
148
+ default: "auto",
149
+ description:
150
+ '"auto" marks the content-addressed image variants immutable (RFC 8246) and ' +
151
+ 'revalidates everything else (RFC 9111). "off" emits no Cache-Control at all.',
152
+ enum: ["auto", "off"],
153
+ type: "string",
154
+ },
155
+ enabled: { default: true, type: "boolean" },
156
+ rules: {
157
+ additionalProperties: { additionalProperties: { type: "string" }, type: "object" },
158
+ description: "Verbatim rules, merged after the generated block.",
159
+ propertyNames: { pattern: "^/" },
160
+ type: "object",
161
+ },
162
+ security: {
163
+ additionalProperties: false,
164
+ properties: {
165
+ contentTypeOptions: { default: true, type: "boolean" },
166
+ csp: {
167
+ default: false,
168
+ description:
169
+ "CSP Level 3. Off by default: unlike the other security headers this one " +
170
+ "governs code the build cannot see — a third-party script that loads a " +
171
+ "second script, a widget that opens a frame — so turning it on is a change " +
172
+ "to verify in the browser console, not a safe default. `script-src` is " +
173
+ "derived from the inline scripts and external origins the build emitted; " +
174
+ "`style-src` keeps 'unsafe-inline', because per-page <style> blocks and " +
175
+ "per-element style attributes have no site-wide hash.",
176
+ oneOf: [
177
+ { type: "boolean" },
178
+ { const: "report-only" },
179
+ {
180
+ additionalProperties: false,
181
+ properties: {
182
+ directives: {
183
+ additionalProperties: {
184
+ oneOf: [{ type: "string" }, { const: false }],
185
+ },
186
+ description:
187
+ "Replace (string) or remove (false) a computed directive. A " +
188
+ "replacement is wholesale, so an addition restates the defaults.",
189
+ type: "object",
190
+ },
191
+ mode: { default: "enforce", enum: ["enforce", "report-only"] },
192
+ reportUri: { format: "uri-reference", type: "string" },
193
+ },
194
+ type: "object",
195
+ },
196
+ ],
197
+ },
198
+ frameOptions: {
199
+ default: "SAMEORIGIN",
200
+ oneOf: [{ enum: ["DENY", "SAMEORIGIN"], type: "string" }, { const: false }],
201
+ },
202
+ hsts: {
203
+ default: false,
204
+ description:
205
+ "RFC 6797. Off by default: a wrong max-age locks the apex domain to HTTPS " +
206
+ "for that long, and the mistake is invisible until a certificate lapses. " +
207
+ "`preload` requires `includeSubDomains` and is a build error without it.",
208
+ oneOf: [
209
+ { type: "boolean" },
210
+ {
211
+ additionalProperties: false,
212
+ properties: {
213
+ includeSubDomains: { default: true, type: "boolean" },
214
+ maxAge: { default: 31_536_000, minimum: 0, type: "integer" },
215
+ preload: { default: false, type: "boolean" },
216
+ },
217
+ type: "object",
218
+ },
219
+ ],
220
+ },
221
+ permissionsPolicy: {
222
+ default: "camera=(), microphone=(), geolocation=()",
223
+ oneOf: [{ type: "string" }, { const: false }],
224
+ },
225
+ referrerPolicy: {
226
+ default: "strict-origin-when-cross-origin",
227
+ oneOf: [
228
+ {
229
+ enum: [
230
+ "no-referrer",
231
+ "no-referrer-when-downgrade",
232
+ "origin",
233
+ "origin-when-cross-origin",
234
+ "same-origin",
235
+ "strict-origin",
236
+ "strict-origin-when-cross-origin",
237
+ "unsafe-url",
238
+ ],
239
+ type: "string",
240
+ },
241
+ { const: false },
242
+ ],
243
+ },
244
+ },
245
+ type: "object",
246
+ },
247
+ },
248
+ type: "object",
249
+ },
129
250
  sitemap: {
130
251
  default: true,
131
252
  description:
@@ -155,9 +276,17 @@ export const projectConfigSchema = {
155
276
  description: "Default charset for the page.",
156
277
  type: "string",
157
278
  },
279
+ dir: {
280
+ description:
281
+ "Base direction for the <html> element. Omitted when unset — a page's `$dir` " +
282
+ "overrides it. Right-to-left content renders left-to-right without this.",
283
+ enum: ["ltr", "rtl", "auto"],
284
+ type: "string",
285
+ },
158
286
  lang: {
159
287
  default: "en",
160
- description: "Default lang attribute for the <html> element.",
288
+ description:
289
+ "Default lang attribute for the <html> element. A page's `$lang` overrides it.",
161
290
  type: "string",
162
291
  },
163
292
  layout: {
@@ -168,6 +297,18 @@ export const projectConfigSchema = {
168
297
  examples: ["./layouts/base.json"],
169
298
  oneOf: [{ type: "string" }, { type: "null" }],
170
299
  },
300
+ shadow: {
301
+ default: false,
302
+ description:
303
+ "Default shadow-DOM mode for every component (spec.md §16.6). Off unless set: a " +
304
+ "shadow root isolates component styles from the page and replaces the <slot> " +
305
+ "emulation with real slot distribution. A component's own `$shadow` overrides this " +
306
+ "in both directions.",
307
+ oneOf: [
308
+ { enum: ["open", "closed"], type: "string" },
309
+ { const: false, type: "boolean" },
310
+ ],
311
+ },
171
312
  },
172
313
  type: "object",
173
314
  },
@@ -179,18 +320,127 @@ export const projectConfigSchema = {
179
320
  items: { type: "string" },
180
321
  type: "array",
181
322
  },
323
+ manifest: {
324
+ additionalProperties: false,
325
+ description:
326
+ 'W3C Web App Manifest, emitted as manifest.webmanifest with a <link rel="manifest"> ' +
327
+ "on every page. Absent means no manifest: it is a claim that a site is meant to be " +
328
+ "installed, and most are not.",
329
+ properties: {
330
+ backgroundColor: { type: "string" },
331
+ categories: { items: { type: "string" }, type: "array" },
332
+ description: { type: "string" },
333
+ dir: { enum: ["ltr", "rtl", "auto"], type: "string" },
334
+ display: {
335
+ default: "standalone",
336
+ enum: ["fullscreen", "standalone", "minimal-ui", "browser"],
337
+ type: "string",
338
+ },
339
+ enabled: { default: true, type: "boolean" },
340
+ icons: {
341
+ description:
342
+ "Icons at 192px and 512px are what browsers require before offering to install " +
343
+ "the site; the build warns when either is missing.",
344
+ items: {
345
+ additionalProperties: false,
346
+ properties: {
347
+ purpose: { type: "string" },
348
+ sizes: { examples: ["192x192"], type: "string" },
349
+ src: { type: "string" },
350
+ type: { type: "string" },
351
+ },
352
+ required: ["src"],
353
+ type: "object",
354
+ },
355
+ type: "array",
356
+ },
357
+ lang: { type: "string" },
358
+ name: { description: "Defaults to the project name.", type: "string" },
359
+ orientation: { type: "string" },
360
+ scope: { type: "string" },
361
+ shortName: { type: "string" },
362
+ startUrl: { default: "/", type: "string" },
363
+ themeColor: { type: "string" },
364
+ },
365
+ type: "object",
366
+ },
367
+ serviceWorker: {
368
+ default: false,
369
+ description:
370
+ "W3C Service Worker, emitted as sw.js. Off unless declared — a worker is sticky, so it " +
371
+ "is the one output that can keep breaking visitors after a deploy tries to fix them. " +
372
+ "**Turning it off means `false`, not deleting the key**: `false` emits a tombstone at " +
373
+ "the same URL that unregisters the old worker and clears its caches, and a 404 there is " +
374
+ "not an instruction to stop. HTML is always network-first; only the content-addressed " +
375
+ "/images/_optimized/* is served cache-first.",
376
+ oneOf: [
377
+ { type: "boolean" },
378
+ {
379
+ additionalProperties: false,
380
+ properties: {
381
+ enabled: { default: true, type: "boolean" },
382
+ offlineFallback: {
383
+ description:
384
+ "Page served for a failed navigation. Added to `precache` if not already there.",
385
+ type: "string",
386
+ },
387
+ precache: {
388
+ description:
389
+ "Site-absolute URLs fetched at install time. Each must be a file this build " +
390
+ "produces; one that is not fails the build, because a single unreachable entry " +
391
+ "stops the worker installing at all.",
392
+ items: { pattern: "^/", type: "string" },
393
+ type: "array",
394
+ },
395
+ scope: { default: "/", type: "string" },
396
+ },
397
+ type: "object",
398
+ },
399
+ ],
400
+ },
401
+ securityTxt: {
402
+ additionalProperties: false,
403
+ description:
404
+ "RFC 9116 security.txt, emitted at .well-known/security.txt. `expires` is required by " +
405
+ "§2.5.5 and an absent or past value is a build error — an expired file advertises a " +
406
+ "reporting channel while telling the reporter not to trust it. A hand-placed " +
407
+ "public/.well-known/security.txt shadows this, which is how a clearsigned file ships.",
408
+ properties: {
409
+ acknowledgments: { items: { type: "string" }, type: "array" },
410
+ canonical: { type: "string" },
411
+ contact: {
412
+ description: "At least one mailto:, https: or tel: URI (§2.5.3).",
413
+ items: { type: "string" },
414
+ type: "array",
415
+ },
416
+ enabled: { default: true, type: "boolean" },
417
+ encryption: { items: { type: "string" }, type: "array" },
418
+ expires: { format: "date-time", type: "string" },
419
+ hiring: { items: { type: "string" }, type: "array" },
420
+ policy: { items: { type: "string" }, type: "array" },
421
+ preferredLanguages: {
422
+ description: "BCP 47 tags, validated and canonicalized like i18n.locales.",
423
+ items: { pattern: LANGUAGE_TAG_PATTERN, type: "string" },
424
+ type: "array",
425
+ },
426
+ },
427
+ type: "object",
428
+ },
182
429
  i18n: {
183
430
  description: "Internationalization configuration.",
184
431
  properties: {
185
432
  defaultLocale: {
186
- description: "Default locale code.",
433
+ description:
434
+ "Default locale, as a BCP 47 language tag. The pattern catches shape errors " +
435
+ "(`en_US`, `en--US`); the build is the authority on well-formedness.",
187
436
  examples: ["en"],
437
+ pattern: LANGUAGE_TAG_PATTERN,
188
438
  type: "string",
189
439
  },
190
440
  locales: {
191
- description: "Available locale codes.",
441
+ description: "Available locales, as BCP 47 language tags.",
192
442
  examples: [["en", "fr", "de"]],
193
- items: { type: "string" },
443
+ items: { pattern: LANGUAGE_TAG_PATTERN, type: "string" },
194
444
  type: "array",
195
445
  },
196
446
  routing: {
@@ -222,9 +472,51 @@ export const projectConfigSchema = {
222
472
  type: "string",
223
473
  },
224
474
  redirects: {
225
- additionalProperties: { type: "string" },
226
- description: "Static redirect rules. Maps source paths to destination paths.",
227
- examples: [{ "/old-about": "/about" }],
475
+ additionalProperties: {
476
+ oneOf: [
477
+ { description: "Destination path or URL; implies a 301.", type: "string" },
478
+ {
479
+ additionalProperties: false,
480
+ description: "A redirect with an explicit RFC 9110 §15.4 status.",
481
+ properties: {
482
+ destination: { type: "string" },
483
+ status: {
484
+ default: 301,
485
+ description:
486
+ "RFC 9110 §15.4 redirection status. 307 and 308 preserve the request method; " +
487
+ "301 and 302 historically do not.",
488
+ enum: [...REDIRECT_STATUSES],
489
+ type: "integer",
490
+ },
491
+ },
492
+ required: ["destination"],
493
+ type: "object",
494
+ },
495
+ {
496
+ additionalProperties: false,
497
+ description:
498
+ "A rewrite (proxy): the destination's content is served AT the source URL, with no " +
499
+ "redirect. Emitted as status 200 in `_redirects`, which is the host convention — " +
500
+ "not an HTTP redirection status.",
501
+ properties: {
502
+ destination: { type: "string" },
503
+ rewrite: { const: true, type: "boolean" },
504
+ },
505
+ required: ["destination", "rewrite"],
506
+ type: "object",
507
+ },
508
+ ],
509
+ },
510
+ description:
511
+ "Static redirect and rewrite rules. Keys are source paths in URLPattern pathname syntax.",
512
+ examples: [
513
+ {
514
+ "/api/*": { destination: "https://api.example.com/*", rewrite: true },
515
+ "/legacy/*": { destination: "/archive/*", status: 308 },
516
+ "/old-about": "/about",
517
+ },
518
+ ],
519
+ propertyNames: { pattern: "^/" },
228
520
  type: "object",
229
521
  },
230
522
  state: {
@@ -0,0 +1,98 @@
1
+ /**
2
+ * A tag name chosen at element creation, from a set the schema can enumerate.
3
+ *
4
+ * The motivating case is one element that must be an `<a>` when a prop is set and a `<div>` when it
5
+ * is not, wrapping an identical subtree either way. Before this def there were two answers and both
6
+ * were bad: write `"${state.href ? 'a' : 'div'}"`, which nothing in the pipeline evaluates and each
7
+ * consumer then broke differently and silently (see {@link tagNameSchema}); or reach for a
8
+ * `$switch` CHILD, whose cases render in place of the container's content — so varying the wrapper
9
+ * means duplicating the whole subtree once per case, and still leaves the container `<div>` wrapped
10
+ * around the result.
11
+ *
12
+ * **The results are `TagName`s, not operands.** That is the property everything else here depends
13
+ * on. The discriminant in `target` may be any expression, but every branch's RESULT is a literal
14
+ * tag held to the same pattern a written-out tag is held to — so the candidate set is readable
15
+ * straight out of the JSON without evaluating anything. The compiler can emit one template per
16
+ * candidate, `jx validate` can refuse `"A LINK"` at authoring time, and the void-element,
17
+ * preformatted, `img` and slot analyses that read a tag structurally keep a finite set to reason
18
+ * about. A `${…}` template in this position would have surrendered all of that.
19
+ *
20
+ * **Vocabulary, not new keywords.** `$expression`, `?:` (test in `target`, consequent in `value`,
21
+ * alternate in `initial`) and `switch` (discriminant in `target`, results in `cases`/`default`) all
22
+ * already mean exactly this — see `expression-node.schema.ts` and spec §19.4b. The alternative
23
+ * considered was `$switch`/`cases` inside the tagName block, which would have been a THIRD switch
24
+ * syntax in a language that has two, and would have made `cases` a homograph inside one element
25
+ * object: tag strings in `tagName`, child subtrees three lines below.
26
+ *
27
+ * **`default`/`initial` are REQUIRED here.** The expression-level `switch` leaves `default`
28
+ * optional and yields `undefined` when nothing matches; an element with no tag is not a thing that
29
+ * can exist, so the fallback is mandatory rather than a shape the runtime has to invent a rule
30
+ * for.
31
+ *
32
+ * **Evaluated ONCE, when the element is created, and never re-read.** This is the one place a
33
+ * `$expression` is not live, and it is deliberate: a tag that changed after mount would mean
34
+ * replacing the node, which costs the subtree's listeners, its focus, its typed input values and
35
+ * its component instances — and the runtime has no dispose walk to pay that bill with. `jx
36
+ * validate` warns when a tag discriminant is also an assignment target anywhere in the document, so
37
+ * the one case where the rule bites is caught at authoring time rather than discovered as a `<div>`
38
+ * that never became an `<a>`.
39
+ */
40
+ export const tagExpressionSchema = {
41
+ anyOf: [
42
+ {
43
+ additionalProperties: false,
44
+ description:
45
+ "Two-way: `target` is the test, `value` the tag when it is truthy, `initial` the tag when it is not.",
46
+ properties: {
47
+ initial: { $ref: "#/$defs/TagName" },
48
+ operator: { const: "?:", type: "string" },
49
+ target: { $ref: "#/$defs/ExpressionOperand" },
50
+ value: { $ref: "#/$defs/TagName" },
51
+ },
52
+ required: ["operator", "target", "value", "initial"],
53
+ title: "?: — the tag when the test holds, and the tag when it does not",
54
+ },
55
+ {
56
+ additionalProperties: false,
57
+ description:
58
+ "Multiway: `target` is the discriminant, matched against case keys by its string form. " +
59
+ "`default` is required — an element with no tag cannot exist.",
60
+ properties: {
61
+ cases: {
62
+ additionalProperties: { $ref: "#/$defs/TagName" },
63
+ type: "object",
64
+ },
65
+ default: { $ref: "#/$defs/TagName" },
66
+ operator: { const: "switch", type: "string" },
67
+ target: { $ref: "#/$defs/ExpressionOperand" },
68
+ },
69
+ required: ["operator", "target", "cases", "default"],
70
+ title: "switch — one tag per discriminant value, with a required fallback",
71
+ },
72
+ ],
73
+ description:
74
+ "A tag name chosen at element creation. Every branch resolves to a `TagName`, so the candidate " +
75
+ "set is enumerable without evaluating anything.",
76
+ } as const;
77
+
78
+ /**
79
+ * What an ELEMENT's `tagName` may be: a name, or a {@link tagExpressionSchema} choosing between
80
+ * names.
81
+ *
82
+ * Wired into `ElementDef.tagName` alone. The document ROOT and `SwitchNode`'s container keep the
83
+ * bare `TagName`, so `customElements.define`, the compiler's module emit and the output filenames
84
+ * derived from the root tag all keep receiving a string — a guarantee that lives in the type rather
85
+ * than in a positional branch someone can forget. `HeadEntry` declares its own `tagName` and never
86
+ * referenced the shared def, so a head tag is static for free.
87
+ */
88
+ export const elementTagNameSchema = {
89
+ anyOf: [
90
+ { $ref: "#/$defs/TagName" },
91
+ {
92
+ additionalProperties: false,
93
+ properties: { $expression: { $ref: "#/$defs/TagExpression" } },
94
+ required: ["$expression"],
95
+ type: "object",
96
+ },
97
+ ],
98
+ } as const;
@@ -1,6 +1,18 @@
1
1
  export const tagNameSchema = {
2
2
  description:
3
- "HTML element tag name or custom element name (must contain a hyphen per Web Components spec).",
3
+ "HTML element tag name or custom element name (must contain a hyphen per Web Components spec). " +
4
+ "A NAME, never an expression: no `${…}` position in the pipeline evaluates a tagName. Use " +
5
+ "`$switch`/`cases` to vary the element.",
4
6
  minLength: 1,
7
+ /* THE PATTERN IS THE WHOLE POINT. Without it `"\${state.href ? 'a' : 'div'}"` validates, and every
8
+ consumer downstream then does something different and silent with it: the runtime hands it to
9
+ `document.createElement` and throws `InvalidCharacterError`; the compiler splices it into a lit
10
+ template as a binding in tag position, which lit cannot do; and the static renderer emits it into
11
+ the prerendered HTML and re-resolves that string against the PAGE scope, where the component's
12
+ own `state` is undefined — so a built site silently collapses to the fallback branch's tag with
13
+ the other branch's attributes. Found by driving Studio against a real site whose component did
14
+ exactly this. Every tagName in packages/, extensions/, sites/, examples/ and docs/ already
15
+ conforms, so the pattern only rejects what was already broken. */
16
+ pattern: "^[a-zA-Z][a-zA-Z0-9._-]*$",
5
17
  type: "string",
6
18
  } as const;
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "dependencies": {
3
- "@webref/css": "^8.7.1",
3
+ "@webref/css": "^8.7.2",
4
4
  "@webref/elements": "^2.7.1",
5
- "@webref/idl": "^3.82.1",
5
+ "@webref/idl": "^3.82.2",
6
6
  "ajv": "^8.20.0",
7
7
  "ajv-formats": "^3.0.1"
8
8
  },
@@ -10,12 +10,17 @@
10
10
  "exports": {
11
11
  ".": "./src/schema.ts",
12
12
  "./asset-paths": "./src/asset-paths.ts",
13
+ "./component-meta": "./src/component-meta.ts",
13
14
  "./extension-registry": "./src/extension-registry.ts",
14
15
  "./format-registry": "./src/format-registry.ts",
15
16
  "./project-schemas": "./src/project-schemas.ts",
16
17
  "./validate-project": "./src/validate-project.ts",
17
18
  "./types": "./types.ts",
18
19
  "./guards": "./src/guards.ts",
20
+ "./locale": "./src/locale.ts",
21
+ "./intl": "./src/intl.ts",
22
+ "./media-type": "./src/media-type.ts",
23
+ "./ijson": "./src/ijson.ts",
19
24
  "./parse": "./src/parse.ts",
20
25
  "./defs": "./defs/index.ts",
21
26
  "./schema.json": "./schema.json",
@@ -50,7 +55,7 @@
50
55
  "upgrade": "bunx npm-check-updates -u && bun install"
51
56
  },
52
57
  "type": "module",
53
- "version": "1.5.0",
58
+ "version": "1.8.1",
54
59
  "devDependencies": {
55
60
  "json-schema-to-ts": "^3.1.1"
56
61
  }