@jxsuite/schema 1.4.0 → 1.8.0

package/defs/tag-expression.schema.ts

@@ -0,0 +1,98 @@
+/**
+ * A tag name chosen at element creation, from a set the schema can enumerate.
+ *
+ * The motivating case is one element that must be an `<a>` when a prop is set and a `<div>` when it
+ * is not, wrapping an identical subtree either way. Before this def there were two answers and both
+ * were bad: write `"${state.href ? 'a' : 'div'}"`, which nothing in the pipeline evaluates and each
+ * consumer then broke differently and silently (see {@link tagNameSchema}); or reach for a
+ * `$switch` CHILD, whose cases render in place of the container's content — so varying the wrapper
+ * means duplicating the whole subtree once per case, and still leaves the container `<div>` wrapped
+ * around the result.
+ *
+ * **The results are `TagName`s, not operands.** That is the property everything else here depends
+ * on. The discriminant in `target` may be any expression, but every branch's RESULT is a literal
+ * tag held to the same pattern a written-out tag is held to — so the candidate set is readable
+ * straight out of the JSON without evaluating anything. The compiler can emit one template per
+ * candidate, `jx validate` can refuse `"A LINK"` at authoring time, and the void-element,
+ * preformatted, `img` and slot analyses that read a tag structurally keep a finite set to reason
+ * about. A `${…}` template in this position would have surrendered all of that.
+ *
+ * **Vocabulary, not new keywords.** `$expression`, `?:` (test in `target`, consequent in `value`,
+ * alternate in `initial`) and `switch` (discriminant in `target`, results in `cases`/`default`) all
+ * already mean exactly this — see `expression-node.schema.ts` and spec §19.4b. The alternative
+ * considered was `$switch`/`cases` inside the tagName block, which would have been a THIRD switch
+ * syntax in a language that has two, and would have made `cases` a homograph inside one element
+ * object: tag strings in `tagName`, child subtrees three lines below.
+ *
+ * **`default`/`initial` are REQUIRED here.** The expression-level `switch` leaves `default`
+ * optional and yields `undefined` when nothing matches; an element with no tag is not a thing that
+ * can exist, so the fallback is mandatory rather than a shape the runtime has to invent a rule
+ * for.
+ *
+ * **Evaluated ONCE, when the element is created, and never re-read.** This is the one place a
+ * `$expression` is not live, and it is deliberate: a tag that changed after mount would mean
+ * replacing the node, which costs the subtree's listeners, its focus, its typed input values and
+ * its component instances — and the runtime has no dispose walk to pay that bill with. `jx
+ * validate` warns when a tag discriminant is also an assignment target anywhere in the document, so
+ * the one case where the rule bites is caught at authoring time rather than discovered as a `<div>`
+ * that never became an `<a>`.
+ */
+export const tagExpressionSchema = {
+  anyOf: [
+    {
+      additionalProperties: false,
+      description:
+        "Two-way: `target` is the test, `value` the tag when it is truthy, `initial` the tag when it is not.",
+      properties: {
+        initial: { $ref: "#/$defs/TagName" },
+        operator: { const: "?:", type: "string" },
+        target: { $ref: "#/$defs/ExpressionOperand" },
+        value: { $ref: "#/$defs/TagName" },
+      },
+      required: ["operator", "target", "value", "initial"],
+      title: "?: — the tag when the test holds, and the tag when it does not",
+    },
+    {
+      additionalProperties: false,
+      description:
+        "Multiway: `target` is the discriminant, matched against case keys by its string form. " +
+        "`default` is required — an element with no tag cannot exist.",
+      properties: {
+        cases: {
+          additionalProperties: { $ref: "#/$defs/TagName" },
+          type: "object",
+        },
+        default: { $ref: "#/$defs/TagName" },
+        operator: { const: "switch", type: "string" },
+        target: { $ref: "#/$defs/ExpressionOperand" },
+      },
+      required: ["operator", "target", "cases", "default"],
+      title: "switch — one tag per discriminant value, with a required fallback",
+    },
+  ],
+  description:
+    "A tag name chosen at element creation. Every branch resolves to a `TagName`, so the candidate " +
+    "set is enumerable without evaluating anything.",
+} as const;
+
+/**
+ * What an ELEMENT's `tagName` may be: a name, or a {@link tagExpressionSchema} choosing between
+ * names.
+ *
+ * Wired into `ElementDef.tagName` alone. The document ROOT and `SwitchNode`'s container keep the
+ * bare `TagName`, so `customElements.define`, the compiler's module emit and the output filenames
+ * derived from the root tag all keep receiving a string — a guarantee that lives in the type rather
+ * than in a positional branch someone can forget. `HeadEntry` declares its own `tagName` and never
+ * referenced the shared def, so a head tag is static for free.
+ */
+export const elementTagNameSchema = {
+  anyOf: [
+    { $ref: "#/$defs/TagName" },
+    {
+      additionalProperties: false,
+      properties: { $expression: { $ref: "#/$defs/TagExpression" } },
+      required: ["$expression"],
+      type: "object",
+    },
+  ],
+} as const;

package/defs/tag-name.schema.ts

@@ -1,6 +1,18 @@
 export const tagNameSchema = {
   description:
-    "HTML element tag name or custom element name (must contain a hyphen per Web Components spec).",
+    "HTML element tag name or custom element name (must contain a hyphen per Web Components spec). " +
+    "A NAME, never an expression: no `${…}` position in the pipeline evaluates a tagName. Use " +
+    "`$switch`/`cases` to vary the element.",
   minLength: 1,
+  /* THE PATTERN IS THE WHOLE POINT. Without it `"\${state.href ? 'a' : 'div'}"` validates, and every
+     consumer downstream then does something different and silent with it: the runtime hands it to
+     `document.createElement` and throws `InvalidCharacterError`; the compiler splices it into a lit
+     template as a binding in tag position, which lit cannot do; and the static renderer emits it into
+     the prerendered HTML and re-resolves that string against the PAGE scope, where the component's
+     own `state` is undefined — so a built site silently collapses to the fallback branch's tag with
+     the other branch's attributes. Found by driving Studio against a real site whose component did
+     exactly this. Every tagName in packages/, extensions/, sites/, examples/ and docs/ already
+     conforms, so the pattern only rejects what was already broken. */
+  pattern: "^[a-zA-Z][a-zA-Z0-9._-]*$",
   type: "string",
 } as const;

package/package.json

@@ -1,8 +1,8 @@
 {
   "dependencies": {
-    "@webref/css": "^8.7.0",
+    "@webref/css": "^8.7.2",
     "@webref/elements": "^2.7.1",
-    "@webref/idl": "^3.82.0",
+    "@webref/idl": "^3.82.2",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1"
   },
@@ -16,6 +16,10 @@
     "./validate-project": "./src/validate-project.ts",
     "./types": "./types.ts",
     "./guards": "./src/guards.ts",
+    "./locale": "./src/locale.ts",
+    "./intl": "./src/intl.ts",
+    "./media-type": "./src/media-type.ts",
+    "./ijson": "./src/ijson.ts",
     "./parse": "./src/parse.ts",
     "./defs": "./defs/index.ts",
     "./schema.json": "./schema.json",
@@ -50,7 +54,7 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "type": "module",
-  "version": "1.4.0",
+  "version": "1.8.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/project-schema.json

@@ -15,6 +15,10 @@
         "optimize": {
           "type": "boolean"
         },
+        "picture": {
+          "description": "Wrap a multi-format image in a <picture> with one <source> per format (default true). With it off the <img> carries a srcset in the preferred format alone, which browsers that cannot decode that format will still select from.",
+          "type": "boolean"
+        },
         "quality": {
           "properties": {
             "avif": {
@@ -224,6 +228,167 @@
           "description": "Output directory for compiled site.",
           "type": "string"
         },
+        "headers": {
+          "additionalProperties": false,
+          "description": "Emit dist/_headers — the response headers only the build can know. Honored by Cloudflare Pages/Workers assets and Netlify; on the node/bun adapters the file documents what a reverse proxy in front of them must send.",
+          "properties": {
+            "cache": {
+              "default": "auto",
+              "description": "\"auto\" marks the content-addressed image variants immutable (RFC 8246) and revalidates everything else (RFC 9111). \"off\" emits no Cache-Control at all.",
+              "enum": [
+                "auto",
+                "off"
+              ],
+              "type": "string"
+            },
+            "enabled": {
+              "default": true,
+              "type": "boolean"
+            },
+            "rules": {
+              "additionalProperties": {
+                "additionalProperties": {
+                  "type": "string"
+                },
+                "type": "object"
+              },
+              "description": "Verbatim rules, merged after the generated block.",
+              "propertyNames": {
+                "pattern": "^/"
+              },
+              "type": "object"
+            },
+            "security": {
+              "additionalProperties": false,
+              "properties": {
+                "contentTypeOptions": {
+                  "default": true,
+                  "type": "boolean"
+                },
+                "csp": {
+                  "default": false,
+                  "description": "CSP Level 3. Off by default: unlike the other security headers this one governs code the build cannot see — a third-party script that loads a second script, a widget that opens a frame — so turning it on is a change to verify in the browser console, not a safe default. `script-src` is derived from the inline scripts and external origins the build emitted; `style-src` keeps 'unsafe-inline', because per-page <style> blocks and per-element style attributes have no site-wide hash.",
+                  "oneOf": [
+                    {
+                      "type": "boolean"
+                    },
+                    {
+                      "const": "report-only"
+                    },
+                    {
+                      "additionalProperties": false,
+                      "properties": {
+                        "directives": {
+                          "additionalProperties": {
+                            "oneOf": [
+                              {
+                                "type": "string"
+                              },
+                              {
+                                "const": false
+                              }
+                            ]
+                          },
+                          "description": "Replace (string) or remove (false) a computed directive. A replacement is wholesale, so an addition restates the defaults.",
+                          "type": "object"
+                        },
+                        "mode": {
+                          "default": "enforce",
+                          "enum": [
+                            "enforce",
+                            "report-only"
+                          ]
+                        },
+                        "reportUri": {
+                          "format": "uri-reference",
+                          "type": "string"
+                        }
+                      },
+                      "type": "object"
+                    }
+                  ]
+                },
+                "frameOptions": {
+                  "default": "SAMEORIGIN",
+                  "oneOf": [
+                    {
+                      "enum": [
+                        "DENY",
+                        "SAMEORIGIN"
+                      ],
+                      "type": "string"
+                    },
+                    {
+                      "const": false
+                    }
+                  ]
+                },
+                "hsts": {
+                  "default": false,
+                  "description": "RFC 6797. Off by default: a wrong max-age locks the apex domain to HTTPS for that long, and the mistake is invisible until a certificate lapses. `preload` requires `includeSubDomains` and is a build error without it.",
+                  "oneOf": [
+                    {
+                      "type": "boolean"
+                    },
+                    {
+                      "additionalProperties": false,
+                      "properties": {
+                        "includeSubDomains": {
+                          "default": true,
+                          "type": "boolean"
+                        },
+                        "maxAge": {
+                          "default": 31536000,
+                          "minimum": 0,
+                          "type": "integer"
+                        },
+                        "preload": {
+                          "default": false,
+                          "type": "boolean"
+                        }
+                      },
+                      "type": "object"
+                    }
+                  ]
+                },
+                "permissionsPolicy": {
+                  "default": "camera=(), microphone=(), geolocation=()",
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "const": false
+                    }
+                  ]
+                },
+                "referrerPolicy": {
+                  "default": "strict-origin-when-cross-origin",
+                  "oneOf": [
+                    {
+                      "enum": [
+                        "no-referrer",
+                        "no-referrer-when-downgrade",
+                        "origin",
+                        "origin-when-cross-origin",
+                        "same-origin",
+                        "strict-origin",
+                        "strict-origin-when-cross-origin",
+                        "unsafe-url"
+                      ],
+                      "type": "string"
+                    },
+                    {
+                      "const": false
+                    }
+                  ]
+                }
+              },
+              "type": "object"
+            }
+          },
+          "type": "object"
+        },
         "sitemap": {
           "default": true,
           "description": "Generate sitemap.xml from the route table (requires `url`). Set false to disable.",
@@ -257,9 +422,18 @@
           "description": "Default charset for the page.",
           "type": "string"
         },
+        "dir": {
+          "description": "Base direction for the <html> element. Omitted when unset — a page's `$dir` overrides it. Right-to-left content renders left-to-right without this.",
+          "enum": [
+            "ltr",
+            "rtl",
+            "auto"
+          ],
+          "type": "string"
+        },
         "lang": {
           "default": "en",
-          "description": "Default lang attribute for the <html> element.",
+          "description": "Default lang attribute for the <html> element. A page's `$lang` overrides it.",
           "type": "string"
         },
         "layout": {
@@ -276,6 +450,23 @@
               "type": "null"
             }
           ]
+        },
+        "shadow": {
+          "default": false,
+          "description": "Default shadow-DOM mode for every component (spec.md §16.6). Off unless set: a shadow root isolates component styles from the page and replaces the <slot> emulation with real slot distribution. A component's own `$shadow` overrides this in both directions.",
+          "oneOf": [
+            {
+              "enum": [
+                "open",
+                "closed"
+              ],
+              "type": "string"
+            },
+            {
+              "const": false,
+              "type": "boolean"
+            }
+          ]
         }
       },
       "type": "object"
@@ -292,18 +483,203 @@
       },
       "type": "array"
     },
+    "manifest": {
+      "additionalProperties": false,
+      "description": "W3C Web App Manifest, emitted as manifest.webmanifest with a <link rel=\"manifest\"> on every page. Absent means no manifest: it is a claim that a site is meant to be installed, and most are not.",
+      "properties": {
+        "backgroundColor": {
+          "type": "string"
+        },
+        "categories": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "description": {
+          "type": "string"
+        },
+        "dir": {
+          "enum": [
+            "ltr",
+            "rtl",
+            "auto"
+          ],
+          "type": "string"
+        },
+        "display": {
+          "default": "standalone",
+          "enum": [
+            "fullscreen",
+            "standalone",
+            "minimal-ui",
+            "browser"
+          ],
+          "type": "string"
+        },
+        "enabled": {
+          "default": true,
+          "type": "boolean"
+        },
+        "icons": {
+          "description": "Icons at 192px and 512px are what browsers require before offering to install the site; the build warns when either is missing.",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "purpose": {
+                "type": "string"
+              },
+              "sizes": {
+                "examples": [
+                  "192x192"
+                ],
+                "type": "string"
+              },
+              "src": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "src"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "lang": {
+          "type": "string"
+        },
+        "name": {
+          "description": "Defaults to the project name.",
+          "type": "string"
+        },
+        "orientation": {
+          "type": "string"
+        },
+        "scope": {
+          "type": "string"
+        },
+        "shortName": {
+          "type": "string"
+        },
+        "startUrl": {
+          "default": "/",
+          "type": "string"
+        },
+        "themeColor": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "serviceWorker": {
+      "default": false,
+      "description": "W3C Service Worker, emitted as sw.js. Off unless declared — a worker is sticky, so it is the one output that can keep breaking visitors after a deploy tries to fix them. **Turning it off means `false`, not deleting the key**: `false` emits a tombstone at the same URL that unregisters the old worker and clears its caches, and a 404 there is not an instruction to stop. HTML is always network-first; only the content-addressed /images/_optimized/* is served cache-first.",
+      "oneOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "default": true,
+              "type": "boolean"
+            },
+            "offlineFallback": {
+              "description": "Page served for a failed navigation. Added to `precache` if not already there.",
+              "type": "string"
+            },
+            "precache": {
+              "description": "Site-absolute URLs fetched at install time. Each must be a file this build produces; one that is not fails the build, because a single unreachable entry stops the worker installing at all.",
+              "items": {
+                "pattern": "^/",
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "scope": {
+              "default": "/",
+              "type": "string"
+            }
+          },
+          "type": "object"
+        }
+      ]
+    },
+    "securityTxt": {
+      "additionalProperties": false,
+      "description": "RFC 9116 security.txt, emitted at .well-known/security.txt. `expires` is required by §2.5.5 and an absent or past value is a build error — an expired file advertises a reporting channel while telling the reporter not to trust it. A hand-placed public/.well-known/security.txt shadows this, which is how a clearsigned file ships.",
+      "properties": {
+        "acknowledgments": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "canonical": {
+          "type": "string"
+        },
+        "contact": {
+          "description": "At least one mailto:, https: or tel: URI (§2.5.3).",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "enabled": {
+          "default": true,
+          "type": "boolean"
+        },
+        "encryption": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "expires": {
+          "format": "date-time",
+          "type": "string"
+        },
+        "hiring": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "policy": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "preferredLanguages": {
+          "description": "BCP 47 tags, validated and canonicalized like i18n.locales.",
+          "items": {
+            "pattern": "^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$",
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "type": "object"
+    },
     "i18n": {
       "description": "Internationalization configuration.",
       "properties": {
         "defaultLocale": {
-          "description": "Default locale code.",
+          "description": "Default locale, as a BCP 47 language tag. The pattern catches shape errors (`en_US`, `en--US`); the build is the authority on well-formedness.",
           "examples": [
             "en"
           ],
+          "pattern": "^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$",
           "type": "string"
         },
         "locales": {
-          "description": "Available locale codes.",
+          "description": "Available locales, as BCP 47 language tags.",
           "examples": [
             [
               "en",
@@ -312,6 +688,7 @@
             ]
           ],
           "items": {
+            "pattern": "^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$",
             "type": "string"
           },
           "type": "array"
@@ -354,14 +731,73 @@
     },
     "redirects": {
       "additionalProperties": {
-        "type": "string"
+        "oneOf": [
+          {
+            "description": "Destination path or URL; implies a 301.",
+            "type": "string"
+          },
+          {
+            "additionalProperties": false,
+            "description": "A redirect with an explicit RFC 9110 §15.4 status.",
+            "properties": {
+              "destination": {
+                "type": "string"
+              },
+              "status": {
+                "default": 301,
+                "description": "RFC 9110 §15.4 redirection status. 307 and 308 preserve the request method; 301 and 302 historically do not.",
+                "enum": [
+                  301,
+                  302,
+                  303,
+                  307,
+                  308
+                ],
+                "type": "integer"
+              }
+            },
+            "required": [
+              "destination"
+            ],
+            "type": "object"
+          },
+          {
+            "additionalProperties": false,
+            "description": "A rewrite (proxy): the destination's content is served AT the source URL, with no redirect. Emitted as status 200 in `_redirects`, which is the host convention — not an HTTP redirection status.",
+            "properties": {
+              "destination": {
+                "type": "string"
+              },
+              "rewrite": {
+                "const": true,
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "destination",
+              "rewrite"
+            ],
+            "type": "object"
+          }
+        ]
       },
-      "description": "Static redirect rules. Maps source paths to destination paths.",
+      "description": "Static redirect and rewrite rules. Keys are source paths in URLPattern pathname syntax.",
       "examples": [
         {
+          "/api/*": {
+            "destination": "https://api.example.com/*",
+            "rewrite": true
+          },
+          "/legacy/*": {
+            "destination": "/archive/*",
+            "status": 308
+          },
           "/old-about": "/about"
         }
       ],
+      "propertyNames": {
+        "pattern": "^/"
+      },
       "type": "object"
     },
     "state": {