@valancex/common 0.13.0 → 0.14.0

package/dist/primitives.js

@@ -1,66 +1,802 @@
-// The tags a layout or component may use, and the element each becomes. This is the vocabulary of the application model: a template says `<nav>`, `<link>`, `<para>`, and this table says
-// what they are on the web. It is also what the MESH manifest is derived from, so a tag that is not here is a compile error that names it.
+// GENERATED by @valancex/primitives from its specifications (specs/) and the web's realizations (realizations/web.json): do not edit; `pnpm --filter @valancex/primitives generate` writes it.
 //
-// Styling hooks are attributes: `class` for a part with a role of its own, `theme` (the `data-theme` attribute) for a variant, `label` (`aria-label`) and `current` (`aria-current`) where
-// the state is an accessibility fact too. A stylesheet is written against those and the elements.
+// The tags a layout or component may use, and the element each becomes. This is the vocabulary of the application model: a template says `<nav>`, `<link>`, `<paragraph>`, and this table says what they
+// are on the web. It is also what the MESH manifest is derived from (and `declared` below says what the specification adds to the derivation: a prop's type and whether a use must write it), so a tag
+// that is not here is a compile error that names it.
 import * as Web from "@valancex/valance/web";
-const klass = Web.attribute("class");
-const id = Web.attribute("id");
-const label = Web.attribute("aria-label");
-// A prop a tag declares is a prop every use of it must write (docs/application-model/HANDOFF.md, finding D1: MESH derives "required" from the realization and has no optional prop). So the
-// table is many narrow tags rather than a few wide ones: a tag carries only what its uses always have.
 export const primitives = {
-    // The portable core (the same names, props, events and payloads as the Desktop PORT's vocabulary: a component written with only these runs on both targets). `column` and `row` are custom
-    // elements, because this table cannot give a `div` a fixed attribute to tell them apart; `vlx` ships their layout (`core.css`). `heading` is an `h2` with its level as `aria-level`.
-    column: { element: "vlx-column" },
-    row: { element: "vlx-row" },
-    heading: { element: "h2", props: { level: Web.attribute("aria-level") } },
-    text: { element: "span" },
-    shell: { element: "div", props: { class: klass, theme: Web.attribute("data-theme") } },
-    div: { element: "div", props: { class: klass } },
-    header: { element: "header", props: { class: klass } },
-    footer: { element: "footer", props: { class: klass } },
-    main: { element: "main", props: { id, tabindex: Web.attribute("tabindex") } },
-    nav: { element: "nav", props: { class: klass, label } },
-    aside: { element: "aside", props: { class: klass } },
+    column: { element: "vlx-column", attributes: { "data-vlx": "column" } },
+    row: { element: "vlx-row", attributes: { "data-vlx": "row" } },
+    heading: { element: "h2", attributes: { "data-vlx": "heading" }, props: { level: Web.attribute("aria-level") } },
+    text: { element: "span", attributes: { "data-vlx": "text" }, props: { id: Web.attribute("id") } },
+    shell: { element: "div", props: { class: Web.attribute("class"), theme: Web.attribute("data-theme") } },
+    div: { element: "div", props: { class: Web.attribute("class") } },
+    header: { element: "header", props: { class: Web.attribute("class") } },
+    footer: { element: "footer", props: { class: Web.attribute("class") } },
+    main: { element: "main", props: { id: Web.attribute("id"), tabindex: Web.attribute("tabindex") } },
+    nav: { element: "nav", props: { class: Web.attribute("class"), label: Web.attribute("aria-label") } },
+    aside: { element: "aside", props: { class: Web.attribute("class") } },
     section: { element: "section" },
     article: { element: "article" },
-    h1: { element: "h1", props: { id } },
-    h2: { element: "h2", props: { id } },
-    h3: { element: "h3", props: { id } },
-    para: { element: "p", props: { class: klass } },
-    quote: { element: "blockquote", props: { class: klass } },
-    list: { element: "ul", props: { class: klass } },
-    olist: { element: "ol", props: { class: klass } },
-    item: { element: "li" },
-    pre: { element: "pre", props: { class: klass, tabindex: Web.attribute("tabindex") } },
+    h1: { element: "h1", props: { id: Web.attribute("id") } },
+    h2: { element: "h2", props: { id: Web.attribute("id") } },
+    h3: { element: "h3", props: { id: Web.attribute("id") } },
+    paragraph: { element: "p", props: { class: Web.attribute("class"), id: Web.attribute("id") } },
+    blockquote: { element: "blockquote", props: { class: Web.attribute("class") } },
+    list: { element: "ul", props: { ...(Web.elementWhen === undefined ? {} : { ordered: Web.elementWhen("ol") }), class: Web.attribute("class") } },
+    olist: { element: "ol", props: { class: Web.attribute("class") } },
+    listitem: { element: "li" },
+    pre: { element: "pre", props: { class: Web.attribute("class"), tabindex: Web.attribute("tabindex") } },
     code: { element: "code" },
     strong: { element: "strong" },
     em: { element: "em" },
-    span: { element: "span", props: { class: klass } },
-    image: { element: "img", props: { class: klass, src: Web.attribute("src"), alt: Web.attribute("alt"), loading: Web.attribute("loading") } },
-    /** A link inside text. */
+    span: { element: "span", props: { class: Web.attribute("class") } },
+    image: { element: "img", props: { class: Web.attribute("class"), src: Web.attribute("src"), alt: Web.attribute("alt"), loading: Web.attribute("loading") } },
     a: { element: "a", props: { href: Web.attribute("href") } },
-    /** A link that is part of the page's furniture (navigation, a brand): it has a class, and says whether it is where you are (`aria-current`: "page" or "false"). */
-    link: { element: "a", props: { href: Web.attribute("href"), class: klass, current: Web.attribute("aria-current") } },
-    /** A box to tick, reporting `change` with the new value (a boolean). It is an `<input type="checkbox">` (a constant attribute of the primitive), and `checked` is live and server-rendered (`controlledBoolean`). */
-    checkbox: {
-        element: "input",
-        attributes: { type: "checkbox" },
-        props: { checked: Web.controlledBoolean("checked"), label },
-        events: { change: Web.event("change", { kind: "boolean", of: (_event, element) => element.checked }) },
-    },
-    /** A text field, reporting `change` with the new text (a string); the field shows what the state says. */
-    textfield: {
-        element: "input",
-        props: { value: Web.controlled("value"), placeholder: Web.attribute("placeholder"), label },
-        events: {
-            change: Web.event("input", { kind: "string", of: (_event, element) => element.value }),
-            // Enter: the person is done with what they typed
-            submit: Web.event("keydown", undefined, { key: "Enter" }),
-            // Escape: the person backs out of what they typed
-            cancel: Web.event("keydown", undefined, { key: "Escape" }),
-        },
-    },
-    button: { element: "button", props: { class: klass, pressed: Web.attribute("aria-pressed"), disabled: Web.booleanAttribute("disabled") }, events: { click: { type: "click" } } },
+    link: { element: "a", props: { href: Web.attribute("href"), class: Web.attribute("class"), current: Web.attribute("aria-current") } },
+    checkbox: { element: "input", attributes: { "type": "checkbox", "data-vlx": "checkbox" }, props: { checked: Web.controlledBoolean("checked"), label: Web.attribute("aria-label"), invalid: Web.attribute("aria-invalid"), describedby: Web.attribute("aria-describedby"), earlyInput: Web.attribute("data-early-input") }, events: { change: Web.event("change", { kind: "boolean", of: (_event, element) => element.checked }) } },
+    textfield: { element: "input", attributes: { "data-vlx": "textfield" }, props: { value: Web.controlled("value"), placeholder: Web.attribute("placeholder"), label: Web.attribute("aria-label"), kind: Web.attribute("type"), invalid: Web.attribute("aria-invalid"), describedby: Web.attribute("aria-describedby") }, events: { change: Web.event("input", { kind: "string", of: (_event, element) => element.value }), submit: Web.event("keydown", undefined, { key: "Enter" }), cancel: Web.event("keydown", undefined, { key: "Escape" }), focus: Web.event("focus"), blur: Web.event("blur") } },
+    button: { element: "button", attributes: { "data-vlx": "button" }, props: { id: Web.attribute("id"), class: Web.attribute("class"), pressed: Web.attribute("aria-pressed"), label: Web.attribute("aria-label"), disabled: Web.booleanAttribute("disabled"), intent: Web.attribute("data-intent"), size: Web.attribute("data-size"), earlyInput: Web.attribute("data-early-input") }, events: { click: Web.event("click") } },
+    toggle: { element: "button", props: { pressed: Web.attribute("aria-pressed"), label: Web.attribute("aria-label"), disabled: Web.booleanAttribute("disabled"), class: Web.attribute("class"), earlyInput: Web.attribute("data-early-input") }, events: { change: Web.event("click", { kind: "boolean", of: (_event, element) => element.getAttribute("aria-pressed") !== "true" }) } },
+    radiogroup: { element: "div", attributes: { "role": "radiogroup" }, props: { label: Web.attribute("aria-label"), invalid: Web.attribute("aria-invalid"), describedby: Web.attribute("aria-describedby") } },
+    radio: { element: "input", attributes: { "type": "radio" }, props: { checked: Web.controlledBoolean("checked"), value: Web.attribute("value"), label: Web.attribute("aria-label"), disabled: Web.booleanAttribute("disabled"), earlyInput: Web.attribute("data-early-input") }, events: { select: Web.event("change", { kind: "string", of: (_event, element) => element.value }) }, ...{ group: { "within": "radiogroup", "attribute": "name" } } },
+    status: { element: "div", attributes: { "role": "status" } },
+    alert: { element: "div", attributes: { "role": "alert" } },
+    label: { element: "label" },
+    ...(Web.layerProp === undefined ? {} : { dialog: { element: "dialog", props: { open: Web.layerProp("open"), label: Web.attribute("aria-label") }, events: { dismiss: Web.layerDismiss }, ...{ layer: "modal" } } }),
+    ...(Web.layerProp === undefined ? {} : { popover: { element: "div", attributes: { "role": "group" }, props: { open: Web.layerProp("open"), anchor: Web.layerProp("anchor"), placement: Web.layerProp("placement"), mode: Web.attribute("popover"), label: Web.attribute("aria-label") }, events: { dismiss: Web.layerDismiss }, ...{ layer: "popover" } } }),
+};
+/** What each tag's props and events are, as the specification states them (the derivation from the table alone cannot say whether a prop is required, nor type one realized as text). */
+export const declared = {
+    "column": {
+        "props": {},
+        "events": {}
+    },
+    "row": {
+        "props": {},
+        "events": {}
+    },
+    "heading": {
+        "props": {
+            "level": {
+                "type": {
+                    "kind": "number"
+                },
+                "required": false
+            }
+        },
+        "events": {}
+    },
+    "text": {
+        "props": {
+            "id": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            }
+        },
+        "events": {}
+    },
+    "shell": {
+        "props": {
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            },
+            "theme": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "div": {
+        "props": {
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "header": {
+        "props": {
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "footer": {
+        "props": {
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "main": {
+        "props": {
+            "id": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            },
+            "tabindex": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "nav": {
+        "props": {
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            },
+            "label": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "aside": {
+        "props": {
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "section": {
+        "props": {},
+        "events": {}
+    },
+    "article": {
+        "props": {},
+        "events": {}
+    },
+    "h1": {
+        "props": {
+            "id": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "h2": {
+        "props": {
+            "id": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "h3": {
+        "props": {
+            "id": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "paragraph": {
+        "props": {
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            },
+            "id": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            }
+        },
+        "events": {}
+    },
+    "blockquote": {
+        "props": {
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "list": {
+        "props": {
+            "ordered": {
+                "type": {
+                    "kind": "boolean"
+                },
+                "required": false
+            },
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "olist": {
+        "props": {
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "listitem": {
+        "props": {},
+        "events": {}
+    },
+    "pre": {
+        "props": {
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            },
+            "tabindex": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "code": {
+        "props": {},
+        "events": {}
+    },
+    "strong": {
+        "props": {},
+        "events": {}
+    },
+    "em": {
+        "props": {},
+        "events": {}
+    },
+    "span": {
+        "props": {
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "image": {
+        "props": {
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            },
+            "src": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            },
+            "alt": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            },
+            "loading": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "a": {
+        "props": {
+            "href": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "link": {
+        "props": {
+            "href": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            },
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            },
+            "current": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {}
+    },
+    "checkbox": {
+        "props": {
+            "checked": {
+                "type": {
+                    "kind": "boolean"
+                },
+                "required": true
+            },
+            "label": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            },
+            "invalid": {
+                "type": {
+                    "kind": "boolean"
+                },
+                "required": false
+            },
+            "describedby": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            },
+            "earlyInput": {
+                "type": {
+                    "kind": "enum",
+                    "values": [
+                        "keep",
+                        "drop"
+                    ]
+                },
+                "required": false
+            }
+        },
+        "events": {
+            "change": {
+                "payload": {
+                    "kind": "boolean"
+                }
+            }
+        }
+    },
+    "textfield": {
+        "props": {
+            "value": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            },
+            "placeholder": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            },
+            "label": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            },
+            "kind": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            },
+            "invalid": {
+                "type": {
+                    "kind": "boolean"
+                },
+                "required": false
+            },
+            "describedby": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            }
+        },
+        "events": {
+            "change": {
+                "payload": {
+                    "kind": "string"
+                }
+            },
+            "submit": {},
+            "cancel": {},
+            "focus": {},
+            "blur": {}
+        }
+    },
+    "button": {
+        "props": {
+            "id": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            },
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            },
+            "pressed": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            },
+            "label": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            },
+            "disabled": {
+                "type": {
+                    "kind": "boolean"
+                },
+                "required": false
+            },
+            "intent": {
+                "type": {
+                    "kind": "enum",
+                    "values": [
+                        "neutral",
+                        "primary",
+                        "danger"
+                    ]
+                },
+                "required": false
+            },
+            "size": {
+                "type": {
+                    "kind": "enum",
+                    "values": [
+                        "sm",
+                        "md",
+                        "lg"
+                    ]
+                },
+                "required": false
+            },
+            "earlyInput": {
+                "type": {
+                    "kind": "enum",
+                    "values": [
+                        "keep",
+                        "drop"
+                    ]
+                },
+                "required": false
+            }
+        },
+        "events": {
+            "click": {}
+        }
+    },
+    "toggle": {
+        "props": {
+            "pressed": {
+                "type": {
+                    "kind": "boolean"
+                },
+                "required": true
+            },
+            "label": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            },
+            "disabled": {
+                "type": {
+                    "kind": "boolean"
+                },
+                "required": false
+            },
+            "class": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            },
+            "earlyInput": {
+                "type": {
+                    "kind": "enum",
+                    "values": [
+                        "keep",
+                        "drop"
+                    ]
+                },
+                "required": false
+            }
+        },
+        "events": {
+            "change": {
+                "payload": {
+                    "kind": "boolean"
+                }
+            }
+        }
+    },
+    "radiogroup": {
+        "props": {
+            "label": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            },
+            "invalid": {
+                "type": {
+                    "kind": "boolean"
+                },
+                "required": false
+            },
+            "describedby": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            }
+        },
+        "events": {}
+    },
+    "radio": {
+        "props": {
+            "checked": {
+                "type": {
+                    "kind": "boolean"
+                },
+                "required": true
+            },
+            "value": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            },
+            "label": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            },
+            "disabled": {
+                "type": {
+                    "kind": "boolean"
+                },
+                "required": false
+            },
+            "earlyInput": {
+                "type": {
+                    "kind": "enum",
+                    "values": [
+                        "keep",
+                        "drop"
+                    ]
+                },
+                "required": false
+            }
+        },
+        "events": {
+            "select": {
+                "payload": {
+                    "kind": "string"
+                }
+            }
+        }
+    },
+    "status": {
+        "props": {},
+        "events": {}
+    },
+    "alert": {
+        "props": {},
+        "events": {}
+    },
+    "label": {
+        "props": {},
+        "events": {}
+    },
+    "dialog": {
+        "props": {
+            "open": {
+                "type": {
+                    "kind": "boolean"
+                },
+                "required": true
+            },
+            "label": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": true
+            }
+        },
+        "events": {
+            "dismiss": {
+                "payload": {
+                    "kind": "string"
+                }
+            }
+        }
+    },
+    "popover": {
+        "props": {
+            "open": {
+                "type": {
+                    "kind": "boolean"
+                },
+                "required": true
+            },
+            "anchor": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            },
+            "placement": {
+                "type": {
+                    "kind": "enum",
+                    "values": [
+                        "top",
+                        "bottom",
+                        "start",
+                        "end"
+                    ]
+                },
+                "required": false
+            },
+            "mode": {
+                "type": {
+                    "kind": "enum",
+                    "values": [
+                        "auto",
+                        "manual"
+                    ]
+                },
+                "required": false
+            },
+            "label": {
+                "type": {
+                    "kind": "string"
+                },
+                "required": false
+            }
+        },
+        "events": {
+            "dismiss": {
+                "payload": {
+                    "kind": "string"
+                }
+            }
+        }
+    }
+};
+/** The tags that were renamed (decision P7), old to new: a template that writes the old one is told the new. */
+export const renamed = {
+    "para": "paragraph",
+    "item": "listitem",
+    "quote": "blockquote"
+};
+/** The props that were renamed (decision I29), by tag, old to new: a template that writes the old one is told the new. */
+export const renamedProps = {
+    "popover": {
+        "kind": "mode"
+    },
+    "button": {
+        "replay": "earlyInput"
+    },
+    "toggle": {
+        "replay": "earlyInput"
+    },
+    "checkbox": {
+        "replay": "earlyInput"
+    },
+    "radio": {
+        "replay": "earlyInput"
+    }
+};
+/** What a use of a tag must satisfy besides its props (`vlx` checks it): the tags that need a name (a `label` prop, or a `label` around them), the tags a tag may contain only, and the tags a tag must be inside. */
+export const rules = {
+    "named": [
+        "checkbox",
+        "textfield",
+        "radiogroup",
+        "radio",
+        "dialog"
+    ],
+    "modal": [
+        "dialog"
+    ],
+    "only": {
+        "list": [
+            "listitem"
+        ],
+        "olist": [
+            "listitem"
+        ],
+        "radiogroup": [
+            "radio",
+            "label"
+        ]
+    },
+    "within": {
+        "listitem": [
+            "list",
+            "olist"
+        ],
+        "radio": [
+            "radiogroup"
+        ]
+    }
 };