@loadbare/widgets 0.10.1 → 0.11.1

package/README.md

@@ -41,3 +41,20 @@ Apart from the line in `src/imports.ts`, no other import statements
 are required.  The loadbare builder automatically bundles the HTML and
 JS for any widget in the library that is actually used in the app.
 
+## Agent skills
+
+The package ships an agent skill, `loadbare-widgets`, written for a coding agent working
+in a project that depends on `@loadbare/widgets`.  Install it with:
+
+```bash
+npx loadbare-widgets skills install
+```
+
+It links the skill into `.agents/skills/` and `.claude/skills/`, where agents
+look for skills.  `--copy` writes copies instead of links, and `--dir <path>`
+installs into one directory of your choosing.  The command prints the paths to
+add to `.gitignore` and writes nothing there itself.
+
+`npx loadbare-app skills install`, `npx loadbare-widgets skills install` and
+`npx loadbare-db skills install` install the three loadbare skills, one per
+package.

package/dist-cli/package-root.js

@@ -0,0 +1,24 @@
+/**
+ * Walk up from `dir` to the nearest ancestor holding a package.json.
+ *
+ * Needed because a caller may run from source (cli/*.ts) or compiled
+ * (dist-cli/*.js) — both are the same distance from the package root, but
+ * nothing here should assume that stays true.
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+export async function findPackageRoot(dir) {
+    for (;;) {
+        try {
+            await readFile(path.join(dir, "package.json"), "utf-8");
+            return dir;
+        }
+        catch {
+            const parent = path.dirname(dir);
+            if (parent === dir) {
+                throw new Error(`could not find a package.json above '${dir}'`);
+            }
+            dir = parent;
+        }
+    }
+}

package/dist-cli/skills-cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * loadbare-widgets — the package's one command.
+ *
+ *   loadbare-widgets skills install [--copy] [--dir <path>]
+ *
+ * Installs the agent skills that ship in this package into `.agents/skills`
+ * and `.claude/skills`, or into `--dir` alone — see cli/skills.ts.  Nothing
+ * goes to stdout but the usage `--help` asks for; every other line is
+ * progress, on stderr.
+ */
+import { parseArgs } from "node:util";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findPackageRoot } from "./package-root.js";
+import { installSkills, SKILL_DESTINATIONS } from "./skills.js";
+const USAGE = "usage: loadbare-widgets skills install [--copy] [--dir <path>]";
+async function main() {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            allowPositionals: true,
+            options: {
+                copy: { type: "boolean", default: false },
+                dir: { type: "string" },
+                help: { type: "boolean", short: "h", default: false },
+            },
+        });
+    }
+    catch (err) {
+        console.error(`loadbare-widgets: ${err.message}`);
+        console.error(USAGE);
+        return 1;
+    }
+    const { values, positionals } = parsed;
+    // Asked for, the usage is the product, so it alone goes to stdout.
+    if (values.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    if (positionals.join(" ") !== "skills install") {
+        console.error(USAGE);
+        return 1;
+    }
+    // Source and compiled output sit at different depths, so the package is
+    // found by walking up rather than by counting.
+    const packageRoot = await findPackageRoot(path.dirname(fileURLToPath(import.meta.url)));
+    const source = path.join(packageRoot, "skills");
+    const destinations = values.dir ? [values.dir] : SKILL_DESTINATIONS;
+    const result = installSkills({
+        source,
+        destinations,
+        copy: values.copy,
+        cwd: process.cwd(),
+        log: (line) => console.error(line),
+    });
+    // An install with no skills in it is a packaging fault, not a user error,
+    // and saying where it looked is what makes that diagnosable.
+    if (result.names.length === 0) {
+        console.error(`loadbare-widgets: this install of @loadbare/widgets carries no skills (looked in ${source})`);
+        return 1;
+    }
+    console.error("");
+    if (result.copiedInstead) {
+        console.error("Some links could not be created and those skills were copied instead.");
+        console.error("A copy does not follow the package when it is upgraded — rerun this");
+        console.error("command after an upgrade, or use --copy everywhere and commit the result.");
+        console.error("");
+    }
+    if (values.copy) {
+        console.error("These are copies.  Commit them, and rerun this command after upgrading");
+        console.error("@loadbare/widgets so the skill matches the widgets.");
+    }
+    else {
+        console.error("These are links into node_modules.  To keep them out of git:");
+        console.error("");
+        for (const destination of destinations) {
+            for (const name of result.names) {
+                console.error(`    ${path.join(destination, name)}`);
+            }
+        }
+    }
+    console.error("");
+    console.error("Start your agent from this directory and it will find them.");
+    return result.refused > 0 ? 1 : 0;
+}
+process.exitCode = await main();

package/dist-cli/skills.js

@@ -0,0 +1,125 @@
+/**
+ * Put the agent skills that ship in this package where a coding agent will
+ * find them.
+ *
+ * The same command as `loadbare-db skills install` and `loadbare-app skills
+ * install`, and deliberately a copy of them rather than a shared module:
+ * this package reaches `@loadbare/app` only through `constants` and `types`,
+ * and a skill installer is neither.  The copies are kept identical, so a
+ * change to one belongs in all three.
+ *
+ * A symlink by default, because the point is that the skill tracks the
+ * dependency: `npm install @loadbare/widgets@next` and the skill moves with it.
+ * `copy` is for a team that would rather commit the text than have every
+ * clone depend on `node_modules` being populated.
+ *
+ * Nothing is done to `.gitignore`.  Whether these paths are committed is a
+ * decision about the project, and the command that installs a file is not the
+ * one to make it.
+ */
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, symlinkSync, } from "node:fs";
+import path from "node:path";
+/**
+ * Where a coding agent looks for skills.
+ *
+ * `.agents/skills` is the vendor-neutral location, read by Codex, Cursor and
+ * Copilot; `.claude/skills` is Claude Code's, and Cursor reads it too.  Both
+ * are written rather than guessing from what happens to be configured.
+ */
+export const SKILL_DESTINATIONS = [".agents/skills", ".claude/skills"];
+/** `absent` covers a dangling symlink, which `existsSync` reports as missing. */
+function entryKind(p) {
+    let stat;
+    try {
+        stat = lstatSync(p);
+    }
+    catch {
+        return "absent";
+    }
+    if (stat.isSymbolicLink())
+        return "symlink";
+    if (stat.isDirectory())
+        return "directory";
+    return "other";
+}
+/** The `name:` a skill directory declares, or null if there is no skill there. */
+function declaredSkillName(dir) {
+    try {
+        const match = /^name:\s*(\S+)\s*$/m.exec(readFileSync(path.join(dir, "SKILL.md"), "utf-8"));
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A link into `node_modules` is relative, so the project stays movable and the
+ * link means the same thing to everyone who checks it out.  A globally
+ * installed package gets an absolute path, since a relative one breaks the
+ * moment the project moves.
+ */
+function linkTarget(from, to, cwd) {
+    const inside = path.resolve(from).startsWith(path.resolve(cwd) + path.sep);
+    return inside
+        ? path.relative(path.dirname(path.resolve(cwd, to)), path.resolve(from))
+        : path.resolve(from);
+}
+/** The skills under `source`: each directory holding a `SKILL.md`. */
+export function shippedSkills(source) {
+    if (!existsSync(source))
+        return [];
+    return readdirSync(source, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() &&
+        existsSync(path.join(source, entry.name, "SKILL.md")))
+        .map((entry) => entry.name)
+        .sort();
+}
+export function installSkills(options) {
+    const { source, destinations, copy, cwd, log } = options;
+    const names = shippedSkills(source);
+    let refused = 0;
+    let copiedInstead = false;
+    for (const destination of destinations) {
+        for (const name of names) {
+            const from = path.join(source, name);
+            const to = path.join(destination, name);
+            const at = path.resolve(cwd, to);
+            const kind = entryKind(at);
+            // A directory this command wrote says so on its own front matter, and
+            // is replaced.  Anything else at that path belongs to someone, and a
+            // skill install is not permitted to be the thing that lost it.
+            if (kind === "directory" && declaredSkillName(at) !== name) {
+                log(`  refused ${to} — a directory is already there and is not the ${name} skill`);
+                refused++;
+                continue;
+            }
+            if (kind === "other") {
+                log(`  refused ${to} — a file is already there`);
+                refused++;
+                continue;
+            }
+            mkdirSync(path.resolve(cwd, destination), { recursive: true });
+            rmSync(at, { recursive: true, force: true });
+            if (copy) {
+                cpSync(from, at, { recursive: true });
+                log(`  copied  ${to}`);
+                continue;
+            }
+            try {
+                symlinkSync(linkTarget(from, to, cwd), at, "dir");
+                log(`  linked  ${to}`);
+            }
+            catch (error) {
+                // Windows refuses a symlink to an unprivileged process unless
+                // developer mode is on.  A copy is the same skill, so the install
+                // succeeds and the difference is reported rather than raised.
+                if (error.code !== "EPERM")
+                    throw error;
+                cpSync(from, at, { recursive: true });
+                copiedInstead = true;
+                log(`  copied  ${to}`);
+            }
+        }
+    }
+    return { names, refused, copiedInstead };
+}

package/docs/lb-checkbox.md

@@ -33,21 +33,17 @@ so they are expansion attributes here rather than `lb-column` and
 ## Why it is not like `lb-input`
 
 `lb-input` has a script that makes the tag itself the control, so the page
-writes `lb-column` on the tag.  `lb-checkbox` cannot do the same.  A value
-that lands before a widget's script has loaded reaches it only as the
-`lb-column-value` stamp, a string, and a checkbox's state is a boolean.  A
-script `lb-checkbox` would read the stamp `"false"` as checked, since no
-string is read.  The native checkbox has no such gap: the hub sets `checked`
-on it directly.
+writes `lb-column` on the tag.  `lb-checkbox` is markup alone, and the hub
+sets `checked` on the native checkbox inside it directly.
 
 `lb-input` could equally be markup alone; its script is a convention, kept
 for now.
 
 ## The control
 
-The checkbox is checked when its column is anything but `false` or null, and
-sends `"true"` or `"false"`.  See
-[checkboxes](../../app/docs/reference/data-binding.md#checkboxes).
+The checkbox is checked when its column is anything but `false`, null,
+`"false"` or `""`, and sends `"true"` or `"false"`.  See "Checkboxes" in the data-binding reference
+of the loadbare-app skill.
 
 ## Styling
 

package/docs/lb-form.md

@@ -26,8 +26,8 @@ Requires `exp-id`.
 A row with a key is on record, and each control saves its own column on
 `change` with `lb-request="lb-row-update"`.  A row whose key is empty is a new
 one not yet entered: the hub sends no update for it, so the controls only
-hold what a submit will gather.  See
-[a row not yet entered](../../app/docs/reference/data-binding.md#a-row-not-yet-entered).
+hold what a submit will gather.  See "A row not yet entered" in the
+data-binding reference of the loadbare-app skill.
 
 A definition only, with no script of its own.
 

package/docs/lb-input.md

@@ -43,13 +43,15 @@ off drops the attribute.
 `lb-input` is a form-associated custom element.  Its `value` property gets and
 sets the value of the `<input>` inside it, and it fires `change` on itself when
 that `<input>` fires `change`.  A form reset returns the `<input>` to its
-default.
+default.  A refusal's message for its column goes to the `<input>`, as HTML's
+own validity.
 
 ## Inside a form
 
 An `lb-input` inside an `lb-row-insert` or `lb-row-update` form carries no
 `lb-request`.  The hub gathers every `lb-column` whose form owner is the form
-on submit and sends one request for all of them.
+on submit and sends one request for all of them, so a widget that also sent
+its own would write the same edit twice.
 
 ```html
 <form lb-query="people" lb-request="lb-row-insert">

package/docs/lb-master.md

@@ -46,8 +46,8 @@ Requires `exp-row`.
 | Cancel   | A new row         | Resets the form                               |
 
 Each carries `data-mode`, `on-record` or `new`, and the stylesheet shows each
-only in its mode.  A new row is one whose key is empty, a
-[row not yet entered](../../app/docs/reference/data-binding.md#a-row-not-yet-entered).
+only in its mode.  A new row is one whose key is empty, a row not yet entered
+(see that section in the data-binding reference of the loadbare-app skill).
 
 Which row shows is a query parm, and only the page knows its name, so New is
 a request the page declares.  Its handler empties the parm, and the row

package/docs/lb-options.md

@@ -80,6 +80,8 @@ and `disabled` so it is never a choice.
 `lb-options` is a form-associated custom element.  Its `value` property gets
 and sets the value of the `<select>` inside it, and it fires `change` on itself
 when that `<select>` fires `change`.  A form reset selects the first option.
+A refusal's message for its column goes to the `<select>`, as HTML's own
+validity.
 
 The hub reads the element's own `lb-column` from the row around it, and lands
 the rows of its `lb-query` inside it.  A value set before the option it names

package/docs/lb-select.md

@@ -37,7 +37,8 @@ improvements through iterative use.
 `lb-select` is a form-associated custom element.  Its `value` property gets
 and sets the value of the `<select>` inside it, and it fires `change` on itself
 when that `<select>` fires `change`.  A form reset selects the option marked
-`selected`, or the first option.
+`selected`, or the first option.  A refusal's message for its column goes to
+the `<select>`, as HTML's own validity.
 
 ## Choosing
 

package/docs/lb-table.md

@@ -72,8 +72,9 @@ filter does not pass is hidden.
 ## The order on the heading
 
 The heading of the column the rows are sorted by carries a triangle, up for
-ascending and down for descending, and `aria-sort`.  Only the order's
-leading term is shown.  A heading's column is the `lb-column` in the cell
+ascending and down for descending, and `aria-sort`, read from the
+`lb-query-order` the hub stamps on the table.  Only the order's leading term
+is shown.  A heading's column is the `lb-column` in the cell
 at the same position in the row template, on the cell or inside it.  A cell
 naming no column, or several, gives its heading none.
 
@@ -160,7 +161,7 @@ created, or moved by changing a column the order reads.
 
 The footer is an ordinary part of the page, not a row from the table's query.
 An aggregate there covers every row showing.  A figure that is not a sum of the rows,
-such as a budget, is an element with its own `lb-query`, a query of kind
+such as a budget, is a `<tr>` with its own `lb-query`, a query of kind
 `row` declared on the server like any other.
 
 ## Styling an empty table

package/docs/lb-unknown-page.md

@@ -39,5 +39,5 @@ there is no page label to show.
 ## Inside the hub
 
 The hub finds the dialog inside its own subtree and nowhere else, so the tag
-goes inside `<lb-hub>`.  See [`chrome.html`](../../app/docs/reference/chrome.md)
-for the same dialog written by hand.
+goes inside `<lb-hub>`.  The chrome reference of the loadbare-app skill shows
+the same dialog written by hand in `chrome.html`.

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@loadbare/widgets",
   "description": "The basic widget set for @loadbare/app: input, select, options, picker, table, unknown-page, confirm, form, insert-dialog, master, checkbox, number, date, tel, mailto",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "type": "module",
   "files": [
     "dist",
+    "dist-cli",
     "docs",
+    "skills/loadbare-widgets/SKILL.md",
+    "skills/loadbare-widgets/references",
     "README.md"
   ],
   "publishConfig": {
@@ -17,12 +20,17 @@
       "default": "./dist/index.js"
     }
   },
+  "bin": {
+    "loadbare-widgets": "dist-cli/skills-cli.js"
+  },
   "loadbare": {
     "widgets": "./dist"
   },
   "scripts": {
-    "build": "node scripts/build.mjs",
-    "postbuild": "node ../../scripts/check-dist-imports.mjs",
+    "build": "node scripts/build.mjs && npm run build:cli && npm run build:skills",
+    "build:cli": "rm -rf dist-cli && tsc --project tsconfig.cli.json",
+    "build:skills": "node scripts/build-skills.mjs",
+    "postbuild": "node --eval \"fs.chmodSync('dist-cli/skills-cli.js', 0o755)\" --input-type=module && node ../../scripts/check-dist-imports.mjs",
     "test": "tsx --test \"tests/**/*.test.ts\"",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write .",

package/skills/loadbare-widgets/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: loadbare-widgets
+description: The basic widget set for Loadbare/app, shipped as `@loadbare/widgets`. Covers each widget's parameters, the attributes it reads, and what a change sends; `lb-input`, `lb-select`, `lb-options`, `lb-picker`, `lb-table`, `lb-unknown-page`, `lb-confirm`, `lb-form`, `lb-insert-dialog`, `lb-master`, `lb-checkbox`, `lb-number`, `lb-date`, `lb-tel` and `lb-mailto`. Use whenever a task writes or changes markup using one of these tags, or decides whether a page needs a custom element of its own. The pages, queries and requests the widgets sit in are the loadbare-app skill's.
+license: Apache-2.0
+metadata:
+  package: "@loadbare/widgets"
+  homepage: https://gitlab.com/kendowns/loadbare
+---
+
+# Working with @loadbare/widgets
+
+Every widget is an ordinary custom element for `@loadbare/app`: markup with
+`lb-*` attributes and `exp-*` parameters, landed and gathered by the hub like
+any other element.  How pages, queries, requests and custom elements work is
+in the loadbare-app skill.  This skill covers only what each widget takes and
+does.
+
+Install the package and list it in the application's `src/imports.ts`:
+
+```ts
+export default ["@loadbare/widgets"];
+```
+
+The builder then bundles the definition and script of each widget a page
+uses, and nothing else.  The application's own definition of a tag
+overrides the package's.
+
+`lb-input`, `lb-select`, `lb-options` and `lb-picker` are controls:
+form-associated custom elements with a `value` property that fire `change`.
+Each carries `lb-column` and `lb-request` itself, the way an `<input>` does.
+Inside a form that sends one request for all its controls, leave
+`lb-request` off.
+
+## Reference material
+
+One page per widget.  They ship with the package, so no network is needed.
+
+| Widget | Is |
+| --- | --- |
+| [`lb-input`](references/lb-input.md) | a control wrapping an `<input>` |
+| [`lb-select`](references/lb-select.md) | a control wrapping a `<select>` whose options the page writes |
+| [`lb-options`](references/lb-options.md) | a control wrapping a `<select>` whose options come from a query |
+| [`lb-picker`](references/lb-picker.md) | `lb-options` with the row template built in |
+| [`lb-table`](references/lb-table.md) | a `<table>` supplying its own scaffolding and a ghost row |
+| [`lb-unknown-page`](references/lb-unknown-page.md) | the chrome's dialog for a URL that names no page |
+| [`lb-confirm`](references/lb-confirm.md) | a button that asks before it sends |
+| [`lb-form`](references/lb-form.md) | a form over one row, which saves per control once the row is on record |
+| [`lb-insert-dialog`](references/lb-insert-dialog.md) | a row entered in a modal dialog, chosen in the picker that opened it |
+| [`lb-master`](references/lb-master.md) | a set, one of its rows, and the buttons that act on the set |
+| [`lb-checkbox`](references/lb-checkbox.md) | a checkbox and its label, as markup to style |
+| [`lb-number`](references/lb-number.md) | a number shown by `Intl.NumberFormat` |
+| [`lb-date`](references/lb-date.md) | a date or time shown by `Intl.DateTimeFormat` |
+| [`lb-tel`](references/lb-tel.md) | a phone number shown as a `tel:` link |
+| [`lb-mailto`](references/lb-mailto.md) | an email address shown as a `mailto:` link |
+
+## The other loadbare skills
+
+`npx loadbare-widgets skills install` puts this skill where a coding agent
+finds it.  `npx loadbare-app skills install` and
+`npx loadbare-db skills install` do the same for the loadbare-app and
+loadbare-db skills.

package/skills/loadbare-widgets/references/lb-checkbox.md

@@ -0,0 +1,59 @@
+# `lb-checkbox`
+
+> Status: a barebones starter.  Iterative use will drive improvements.
+
+A checkbox and its label as one element, for an application to style.  A
+definition only, with no script: the hub treats a native checkbox as a
+control, so the widget adds nothing but the markup.
+
+Requires `exp-column` and `exp-label`.
+
+```html
+<div lb-query="people">
+  <template>
+    <div>
+      <lb-checkbox exp-column="active" exp-label="Active" exp-request="lb-row-update"></lb-checkbox>
+    </div>
+  </template>
+</div>
+```
+
+## Expansion Attributes
+
+| Parameter     | Fills                                           |
+| ------------- | ----------------------------------------------- |
+| `exp-column`  | the checkbox's `lb-column`                      |
+| `exp-label`   | the label's text                                |
+| `exp-request` | the checkbox's `lb-request`, none when absent   |
+
+The column and request go on the checkbox inside, since it is the control,
+so they are expansion attributes here rather than `lb-column` and
+`lb-request` on the tag.
+
+## Why it is not like `lb-input`
+
+`lb-input` has a script that makes the tag itself the control, so the page
+writes `lb-column` on the tag.  `lb-checkbox` is markup alone, and the hub
+sets `checked` on the native checkbox inside it directly.
+
+`lb-input` could equally be markup alone; its script is a convention, kept
+for now.
+
+## The control
+
+The checkbox is checked when its column is anything but `false`, null,
+`"false"` or `""`, and sends `"true"` or `"false"`.  See "Checkboxes" in the data-binding reference
+of the loadbare-app skill.
+
+## Styling
+
+The definition is a `<label>` holding the `<input type="checkbox">` and a
+`<span>` with the text:
+
+```css
+lb-checkbox label {
+  display: inline-flex;
+  gap: 0.5em;
+  align-items: center;
+}
+```

package/skills/loadbare-widgets/references/lb-confirm.md

@@ -0,0 +1,44 @@
+# `lb-confirm`
+
+> Status: a barebones starter.  Iterative use will drive improvements.
+
+A button that asks before it sends.  The button opens a dialog holding the
+message the page writes inside the tag, a Cancel button, and a confirm button
+carrying the request.
+
+Requires `exp-label` and `exp-request`.
+
+```html
+<template>
+  <tr>
+    <td lb-column="name"></td>
+    <td>
+      <lb-confirm exp-label="Delete" exp-request="lb-row-delete">
+        Delete <b lb-column="name"></b>?
+      </lb-confirm>
+    </td>
+  </tr>
+</template>
+```
+
+## Expansion Attributes
+
+| Parameter     | Fills                                         |
+| ------------- | --------------------------------------------- |
+| `exp-label`   | the text of the button that opens the dialog  |
+| `exp-request` | the confirm button's `lb-request`             |
+| `exp-confirm` | the confirm button's text, `Confirm` when absent |
+
+## The request
+
+The request is on the dialog's confirm button, never on the tag, so nothing
+reaches the hub until the user says yes.  The dialog sits in the row the tag
+sits in, so the request carries that row's query and key, and the message
+can show the row's columns with `lb-column`.
+
+Cancel comes first and takes focus, so Enter on a dialog opened by accident
+sends nothing.  The widget closes the dialog when the request succeeds.  A refused request leaves it open, with the hub's
+`lb-request-error` on the confirm button.
+
+The dialog is found by its place in the tag, not by id, so the tag works in a
+row template, where the hub clones it once per row.

package/skills/loadbare-widgets/references/lb-date.md

@@ -0,0 +1,48 @@
+# `lb-date`
+
+> Status: a barebones starter.  Iterative use will drive improvements.
+
+A date or a time shown by the browser's `Intl.DateTimeFormat`.  Not a
+control: write `lb-column` on the tag, and the hub lands the column on it
+and never gathers it.
+
+```html
+<lb-date lb-column="due" exp-date-style="medium"></lb-date>
+```
+
+## Expansion Attributes
+
+Each parameter is one of `Intl.DateTimeFormat`'s options, in kebab-case.  A
+parameter not given leaves Intl's default.
+
+| Parameter            | `Intl.DateTimeFormat` option          |
+| -------------------- | ------------------------------------- |
+| `exp-locale`         | the locale, the browser's when absent |
+| `exp-date-style`     | `dateStyle`                           |
+| `exp-time-style`     | `timeStyle`                           |
+| `exp-time-zone`      | `timeZone`                            |
+| `exp-time-zone-name` | `timeZoneName`                        |
+| `exp-hour-cycle`     | `hourCycle`                           |
+| `exp-weekday`        | `weekday`                             |
+| `exp-era`            | `era`                                 |
+| `exp-year`           | `year`                                |
+| `exp-month`          | `month`                               |
+| `exp-day`            | `day`                                 |
+| `exp-hour`           | `hour`                                |
+| `exp-minute`         | `minute`                              |
+| `exp-second`         | `second`                              |
+
+Intl refuses `exp-date-style` or `exp-time-style` beside any of
+`exp-weekday` through `exp-second`.
+
+## The value
+
+The widget reads the value as JavaScript's `Date` does.  A date alone, as
+`YYYY-MM-DD`, shows as that day in every time zone.  A value that is no
+date shows as it arrived.  Null shows nothing.
+
+## Styling
+
+The definition is a `<time>` whose text is the formatted date and whose
+`datetime` is the value as it arrived.  The hub stamps the tag with
+`lb-column-value`, the value as it arrived.