@xoong/controls 0.0.39 → 0.0.42

package/package.json

@@ -1,27 +1,135 @@
 {
   "name": "@xoong/controls",
-  "version": "0.0.39",
+  "version": "0.0.42",
   "description": "xoong form and page controls: tabs, popover, tooltip, menu, combobox, chips, tag input, carousel. Light DOM, accessible, zero dependencies besides @xoong/core.",
   "type": "module",
   "main": "src/index.js",
   "exports": {
     ".": {
+      "types": "./src/index.d.ts",
       "default": "./src/index.js"
     },
-    "./carousel": "./src/carousel.js",
-    "./combobox": "./src/combobox.js",
-    "./copy": "./src/copy.js",
-    "./date": "./src/date.js",
-    "./image": "./src/image.js",
-    "./password": "./src/password.js",
-    "./slider": "./src/slider.js",
-    "./stepper": "./src/stepper.js",
+    "./accordion": {
+      "types": "./src/index.d.ts",
+      "default": "./src/accordion.js"
+    },
+    "./avatar": {
+      "types": "./src/index.d.ts",
+      "default": "./src/avatar.js"
+    },
+    "./carousel": {
+      "types": "./src/index.d.ts",
+      "default": "./src/carousel.js"
+    },
+    "./chart": {
+      "types": "./src/index.d.ts",
+      "default": "./src/chart.js"
+    },
+    "./combobox": {
+      "types": "./src/index.d.ts",
+      "default": "./src/combobox.js"
+    },
+    "./command": {
+      "types": "./src/index.d.ts",
+      "default": "./src/command.js"
+    },
+    "./consent": {
+      "types": "./src/index.d.ts",
+      "default": "./src/consent.js"
+    },
     "./controls.css": "./src/controls.css",
-    "./menu": "./src/menu.js",
-    "./switch": "./src/switch.js",
-    "./tabs": "./src/tabs.js",
-    "./time": "./src/time.js",
-    "./tooltip": "./src/tooltip.js"
+    "./copy": {
+      "types": "./src/index.d.ts",
+      "default": "./src/copy.js"
+    },
+    "./date": {
+      "types": "./src/index.d.ts",
+      "default": "./src/date.js"
+    },
+    "./file": {
+      "types": "./src/index.d.ts",
+      "default": "./src/file.js"
+    },
+    "./image": {
+      "types": "./src/index.d.ts",
+      "default": "./src/image.js"
+    },
+    "./inline-edit": {
+      "types": "./src/index.d.ts",
+      "default": "./src/inline-edit.js"
+    },
+    "./menu": {
+      "types": "./src/index.d.ts",
+      "default": "./src/menu.js"
+    },
+    "./otp": {
+      "types": "./src/index.d.ts",
+      "default": "./src/otp.js"
+    },
+    "./password": {
+      "types": "./src/index.d.ts",
+      "default": "./src/password.js"
+    },
+    "./popover": {
+      "types": "./src/index.d.ts",
+      "default": "./src/popover.js"
+    },
+    "./progress": {
+      "types": "./src/index.d.ts",
+      "default": "./src/progress.js"
+    },
+    "./range-slider": {
+      "types": "./src/index.d.ts",
+      "default": "./src/range-slider.js"
+    },
+    "./segmented": {
+      "types": "./src/index.d.ts",
+      "default": "./src/segmented.js"
+    },
+    "./slider": {
+      "types": "./src/index.d.ts",
+      "default": "./src/slider.js"
+    },
+    "./split-button": {
+      "types": "./src/index.d.ts",
+      "default": "./src/split-button.js"
+    },
+    "./stat": {
+      "types": "./src/index.d.ts",
+      "default": "./src/stat.js"
+    },
+    "./stepper": {
+      "types": "./src/index.d.ts",
+      "default": "./src/stepper.js"
+    },
+    "./steps": {
+      "types": "./src/index.d.ts",
+      "default": "./src/steps.js"
+    },
+    "./switch": {
+      "types": "./src/index.d.ts",
+      "default": "./src/switch.js"
+    },
+    "./tabs": {
+      "types": "./src/index.d.ts",
+      "default": "./src/tabs.js"
+    },
+    "./textarea": {
+      "types": "./src/index.d.ts",
+      "default": "./src/textarea.js"
+    },
+    "./theme-toggle": {
+      "types": "./src/index.d.ts",
+      "default": "./src/theme-toggle.js"
+    },
+    "./time": {
+      "types": "./src/index.d.ts",
+      "default": "./src/time.js"
+    },
+    "./tooltip": {
+      "types": "./src/index.d.ts",
+      "default": "./src/tooltip.js"
+    }
   },
   "sideEffects": true,
   "files": [
@@ -46,9 +154,9 @@
   "bugs": {
     "url": "https://github.com/fpt-duongtx/xoong/issues"
   },
-  "homepage": "https://github.com/fpt-duongtx/xoong#readme",
+  "homepage": "https://fpt-duongtx.github.io/xoong/",
   "dependencies": {
-    "@xoong/core": "0.0.39"
+    "@xoong/core": "0.0.42"
   },
   "publishConfig": {
     "access": "public"

package/src/accordion.js

@@ -0,0 +1,51 @@
+// @ts-check
+/**
+ * <xo-accordion> turns a stack of native <details> into an accordion.
+ *
+ *   <xo-accordion single>
+ *     <details><summary>What is xoong?</summary><div class="xo-accordion__body">A small framework.</div></details>
+ *     <details open><summary>Does it need a build?</summary><div class="xo-accordion__body">No.</div></details>
+ *   </xo-accordion>
+ *
+ * - The children stay native <details>: Enter and Space on the summary work as the browser does. `single` allows one open at a time
+ *   (the native `name` attribute of <details>). ArrowUp, ArrowDown, Home and End move between the summaries.
+ * - Each <details> gets the class `xo-accordion` and a body class if you leave it out is up to you; `xo-accordion-change` fires with `{ index, open }`.
+ */
+import { XoElement, define } from '@xoong/core';
+
+let counter = 0;
+
+class XoAccordion extends XoElement {
+  static props = { single: Boolean };
+  #name = `xo-accordion-${++counter}`;
+
+  connected() {
+    this.addEventListener('toggle', (e) => {
+      const d = e.target;
+      if (d instanceof HTMLDetailsElement && d.parentElement === this) this.dispatchEvent(new CustomEvent('xo-accordion-change', { bubbles: true, detail: { index: this.#items.indexOf(d), open: d.open } }));
+    }, true);
+    this.addEventListener('keydown', (e) => this.#key(e));
+    this.#setup();
+    new MutationObserver(() => this.#setup()).observe(this, { childList: true });
+  }
+  attributeChangedCallback(attr, old, value) { super.attributeChangedCallback(attr, old, value); this.#setup(); }
+
+  get #items() { return /** @type {HTMLDetailsElement[]} */ ([...this.children].filter((c) => c instanceof HTMLDetailsElement)); }
+  #setup() {
+    for (const d of this.#items) {
+      d.classList.add('xo-accordion');
+      if (this.single) d.setAttribute('name', this.#name); else if (d.getAttribute('name') === this.#name) d.removeAttribute('name');
+    }
+  }
+  #key(/** @type {KeyboardEvent} */ e) {
+    const t = e.target;
+    if (!(t instanceof HTMLElement) || t.localName !== 'summary') return;
+    const sums = this.#items.map((d) => /** @type {HTMLElement} */ (d.querySelector(':scope > summary')));
+    const i = sums.indexOf(t);
+    const to = { ArrowDown: i + 1, ArrowUp: i - 1, Home: 0, End: sums.length - 1 }[e.key];
+    if (to === undefined || i < 0) return;
+    e.preventDefault();
+    sums[(to + sums.length) % sums.length]?.focus();
+  }
+}
+define('xo-accordion', XoAccordion);

package/src/avatar.js

@@ -0,0 +1,142 @@
+// @ts-check
+/**
+ * <xo-avatar> is a person (or a team) as a round badge: their picture when there is one, their initials when there is not.
+ * <xo-avatars> stacks several of them.
+ *
+ *   <xo-avatar name="Nguyễn Văn An" src="/img/an.jpg" size="lg" status="ok"></xo-avatar>
+ *   <xo-avatars max="3"><xo-avatar name="An Dao"></xo-avatar> <xo-avatar name="Linh Tran"></xo-avatar> ... </xo-avatars>
+ *
+ * - The element itself is the `.xo-avatar` badge (it gets the classes `xo-avatar`, `xo-avatar--sm|lg` from `size`, and `xo-avatar--ok|warn|muted` from
+ *   `status`). Colour is never the only signal: the status is added to the accessible name ("An Dao, online").
+ * - Initials: the first letter of the first and of the last word ("Nguyễn Văn An" is "NA"); a single word gives its first two letters. Without a
+ *   name the user icon is drawn.
+ * - `src` is tried first: the image replaces the initials once it loads and the initials stay when it fails (`data-state` is `loaded` or `error`).
+ * - The accessible name is the full name: `role=img` with `aria-label`; inside <xo-avatars> it is a `role=listitem` with the same label.
+ * - <xo-avatars max="3"> is a `role=list` of its avatars. Only `max` are shown; a last badge "+N" (labelled "N more") stands for the rest.
+ *   Without `max` all are shown.
+ */
+import { XoElement, define, text } from '@xoong/core';
+
+/** Initials for a name: first letter of the first and the last word, or the first two letters of a single word. */
+export function initialsOf(/** @type {string} */ name) {
+  const words = String(name ?? '').trim().split(/\s+/).map((w) => Array.from(w.replace(/^[^\p{L}\p{N}]+/u, ''))).filter((w) => w.length);
+  if (!words.length) return '';
+  const letters = words.length === 1 ? words[0].slice(0, 2) : [words[0][0], words[words.length - 1][0]];
+  return letters.join('').toLocaleUpperCase();
+}
+
+const STATUS = ['ok', 'warn', 'muted'];
+const SIZE = ['sm', 'lg'];
+
+class XoAvatar extends XoElement {
+  static props = { name: String, src: String, size: String, status: String };
+
+  /** @type {HTMLImageElement | null} */ #img = null;
+  /** @type {HTMLElement | null} */ #initials = null;
+
+  connected() {
+    const initials = document.createElement('span');
+    initials.setAttribute('aria-hidden', 'true');
+    this.#initials = initials;
+    this.replaceChildren(initials);
+    this.#img = null;
+    this.#loadImage();
+    this.#paint();
+  }
+
+  attributeChangedCallback(attr, old, value) {
+    super.attributeChangedCallback(attr, old, value);
+    if (attr === 'src' && this.#initials) this.#loadImage();
+    this.#paint();
+  }
+
+  /** The stack (or the page) calls this when the avatar is moved into or out of an <xo-avatars>. */
+  refresh() { this.#paint(); }
+
+  #loadImage() {
+    this.#img?.remove();
+    this.#img = null;
+    delete this.dataset.state;
+    this.#initials?.removeAttribute('hidden');
+    if (!this.src) return;
+    const img = document.createElement('img');
+    img.alt = '';
+    img.setAttribute('aria-hidden', 'true');
+    img.decoding = 'async';
+    // The picture fills the badge: set through the CSS object model (no style attribute, strict CSP) so it works with or without a stylesheet rule.
+    for (const [k, v] of [['width', '100%'], ['height', '100%'], ['objectFit', 'cover'], ['borderRadius', '50%'], ['display', 'none']]) /** @type {any} */ (img.style)[k] = v;
+    img.addEventListener('load', () => { if (this.#img !== img) return; img.style.display = 'block'; this.#initials?.setAttribute('hidden', ''); this.dataset.state = 'loaded'; });
+    img.addEventListener('error', () => { if (this.#img !== img) return; img.remove(); this.#img = null; this.#initials?.removeAttribute('hidden'); this.dataset.state = 'error'; });
+    this.#img = img;
+    this.append(img);
+    img.src = this.src;
+  }
+
+  #paint() {
+    const el = this.#initials;
+    if (!el) return;
+    const name = (this.name ?? '').trim();
+    const initials = initialsOf(name);
+    if (initials) el.textContent = initials;
+    else el.innerHTML = '<span class="ic" data-ic="user" aria-hidden="true"></span>';
+    const cls = this.classList;
+    cls.add('xo-avatar');
+    for (const s of SIZE) cls.toggle(`xo-avatar--${s}`, this.size === s);
+    for (const s of STATUS) cls.toggle(`xo-avatar--${s}`, this.status === s);
+    const status = this.status === 'ok' ? text('xoong.avatar.ok', 'online') : this.status === 'warn' ? text('xoong.avatar.warn', 'needs attention') : this.status === 'muted' ? text('xoong.avatar.muted', 'inactive') : '';
+    const label = name ? (status ? `${name}, ${status}` : name) : text('xoong.avatar.unknown', 'Unknown user');
+    this.setAttribute('aria-label', label);
+    this.setAttribute('role', this.closest('xo-avatars') ? 'listitem' : 'img');
+  }
+}
+define('xo-avatar', XoAvatar);
+
+class XoAvatars extends XoElement {
+  static props = { max: Number, label: String };
+
+  /** @type {HTMLElement | null} */ #more = null;
+  /** @type {MutationObserver | null} */ #watch = null;
+
+  connected() {
+    this.classList.add('xo-avatars');
+    this.setAttribute('role', 'list');
+    void this.ready().then(() => {
+      this.#layout();
+      this.#watch = new MutationObserver(() => this.#layout());
+      this.#watch.observe(this, { childList: true });
+    });
+  }
+  disconnected() { this.#watch?.disconnect(); this.#watch = null; }
+
+  attributeChangedCallback(attr, old, value) {
+    super.attributeChangedCallback(attr, old, value);
+    if (this.isConnected && this.#watch) this.#layout();
+  }
+
+  #layout() {
+    this.#watch?.disconnect();
+    const items = /** @type {HTMLElement[]} */ ([...this.children].filter((c) => c !== this.#more));
+    const max = this.max > 0 ? Math.floor(this.max) : items.length;
+    const rest = Math.max(0, items.length - max);
+    items.forEach((el, i) => {
+      if (!el.hasAttribute('role') || el.getAttribute('role') === 'img') el.setAttribute('role', 'listitem');
+      if (/** @type {any} */ (el).refresh) /** @type {any} */ (el).refresh();
+      const hide = i >= max;
+      el.toggleAttribute('hidden', hide);
+      if (hide) el.style.display = 'none'; else el.style.removeProperty('display');
+    });
+    if (rest > 0) {
+      if (!this.#more) {
+        const more = document.createElement('span');
+        more.className = 'xo-avatar xo-avatar--muted';
+        more.setAttribute('role', 'listitem');
+        this.#more = more;
+      }
+      this.#more.textContent = `+${rest}`;
+      this.#more.setAttribute('aria-label', text('xoong.avatar.more', '{count} more', { count: rest }));
+      if (this.lastElementChild !== this.#more) this.append(this.#more);
+    } else if (this.#more) { this.#more.remove(); this.#more = null; }
+    this.#watch?.observe(this, { childList: true });
+  }
+}
+define('xo-avatars', XoAvatars);

package/src/carousel.js

@@ -153,7 +153,8 @@ class XoCarousel extends XoElement {
     const index = this.#index;
     slides.forEach((slide, i) => {
       if (!slide.hasAttribute('aria-label') || slide.hasAttribute('data-xo-label')) { slide.setAttribute('aria-label', text('xoong.carousel.slide', '{n} of {count}', { n: i + 1, count: n })); slide.setAttribute('data-xo-label', ''); }
-      slide.setAttribute('role', 'group');
+      if (slide.localName === 'article') slide.removeAttribute('role'); // an <article> already has a role, and group is not allowed on it (axe aria-allowed-role); the roledescription and label stay
+      else slide.setAttribute('role', 'group');
       slide.setAttribute('aria-roledescription', 'slide');
       if (laidOut) { // a slide completely out of view is not reachable by Tab or by a reader's browse mode; a peeking one is
         const a = slide.getBoundingClientRect(), b = track.getBoundingClientRect();

package/src/chart.js

@@ -0,0 +1,85 @@
+// @ts-check
+/**
+ * <xo-chart> draws a small bar or line chart from data, with the same numbers as a table for everyone who prefers or needs it.
+ *
+ *   <xo-chart type="bar" label="Visits per period" unit="k" data='[{"label":"Mon","value":12},{"label":"Tue","value":18}]'></xo-chart>
+ *   el.rows = [{ label: 'Mon', value: 12 }, ...]      // or numbers: [12, 18], labelled 1, 2, ...
+ *
+ * - `type` is `bar` (default) or `line`. The SVG has role=img and the label; in a bar chart each bar is focusable and named ("Mon: 12k").
+ * - "View as table" (a native <details>) lists the same data. `unit` is appended to the values; `heading` and `value-heading` name the columns.
+ * - Colours come from the theme (classes `grid`, `axis`, `bar`, `line`, `area`, `dot` inside `.xo-chart`); `rows` can be set again at any time.
+ */
+import { XoElement, define, text } from '@xoong/core';
+
+const NS = 'http://www.w3.org/2000/svg';
+const W = 640, H = 220, L = 36, B = 24, T = 8;
+/** A round number at or above `v`, for the top of the axis. */
+const nice = (/** @type {number} */ v) => { if (v <= 0) return 1; const p = 10 ** Math.floor(Math.log10(v)); const f = v / p; return (f <= 1 ? 1 : f <= 2 ? 2 : f <= 5 ? 5 : 10) * p; };
+
+class XoChart extends XoElement {
+  static props = { type: String, label: String, unit: String, heading: String, valueHeading: String, data: String };
+
+  /** @type {{ label: string, value: number }[]} */ #rows = [];
+  #built = false;
+
+  get rows() { return this.#rows; }
+  set rows(v) { this.#rows = (Array.isArray(v) ? v : []).map((r, i) => (typeof r === 'number' ? { label: String(i + 1), value: r } : { label: String(r.label), value: Number(r.value) })); if (this.#built) this.#draw(); }
+
+  connected() {
+    if (!this.#rows.length && this.data) { try { this.rows = JSON.parse(this.data); } catch { /* not JSON: no data */ } }
+    this.#built = true;
+    this.#draw();
+  }
+  attributeChangedCallback(attr, old, value) {
+    super.attributeChangedCallback(attr, old, value);
+    if (attr === 'data' && this.#built) { try { this.rows = JSON.parse(value ?? '[]'); } catch { this.rows = []; } } else if (this.#built) this.#draw();
+  }
+
+  #draw() {
+    const rows = this.#rows;
+    const unit = this.unit ?? '';
+    const el = (/** @type {string} */ tag, /** @type {Record<string, string | number>} */ attrs = {}) => { const e = document.createElementNS(NS, tag); for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, String(v)); return e; };
+    const svg = /** @type {SVGSVGElement} */ (el('svg', { viewBox: `0 0 ${W} ${H}`, role: 'img', 'aria-label': this.label ?? '' }));
+    const top = nice(Math.max(0, ...rows.map((r) => r.value)));
+    const y = (/** @type {number} */ v) => T + (H - B - T) * (1 - v / top);
+    for (let i = 0; i <= 4; i++) {
+      const v = (top / 4) * i;
+      svg.append(el('line', { class: 'grid', x1: L, x2: W, y1: y(v), y2: y(v) }));
+      const t = el('text', { class: 'axis', x: L - 6, y: y(v) + 4, 'text-anchor': 'end' }); t.textContent = `${+v.toFixed(2)}${unit}`; svg.append(t);
+    }
+    const step = (W - L) / Math.max(1, rows.length);
+    const cx = (/** @type {number} */ i) => L + step * (i + 0.5);
+    const every = Math.ceil(rows.length / 12); // at most about twelve labels on the axis
+    rows.forEach((r, i) => { if (i % every) return; const t = el('text', { class: 'axis', x: cx(i), y: H - 6, 'text-anchor': 'middle' }); t.textContent = r.label; svg.append(t); });
+    if (this.type === 'line' && rows.length) {
+      const pts = rows.map((r, i) => `${cx(i)},${y(r.value)}`);
+      svg.append(el('polygon', { class: 'area', points: `${cx(0)},${y(0)} ${pts.join(' ')} ${cx(rows.length - 1)},${y(0)}` }), el('polyline', { class: 'line', points: pts.join(' ') }));
+      rows.forEach((r, i) => svg.append(el('circle', { class: 'dot', cx: cx(i), cy: y(r.value), r: 3.5 })));
+    } else {
+      const w = Math.min(48, step * 0.6);
+      rows.forEach((r, i) => {
+        const bar = el('rect', { class: 'bar', x: cx(i) - w / 2, y: y(r.value), width: w, height: Math.max(0, y(0) - y(r.value)), rx: 3, tabindex: 0, role: 'img', 'aria-label': `${r.label}: ${r.value}${unit}` });
+        const title = el('title'); title.textContent = `${r.label}: ${r.value}${unit}`; bar.append(title);
+        svg.append(bar);
+      });
+    }
+    const fig = document.createElement('figure');
+    fig.className = 'xo-chart';
+    fig.append(svg);
+    const d = document.createElement('details');
+    const s = document.createElement('summary');
+    s.className = 'button ghost sm'; s.textContent = text('xoong.chart.table', 'View as table');
+    const table = document.createElement('table');
+    table.className = 'std';
+    const cell = (/** @type {string} */ tag, /** @type {string} */ t) => { const c = document.createElement(tag); c.textContent = t; return c; };
+    const head = document.createElement('tr'); head.append(cell('th', this.heading || text('xoong.chart.label', 'Label')), cell('th', this.valueHeading || text('xoong.chart.value', 'Value')));
+    const thead = document.createElement('thead'); thead.append(head);
+    const tbody = document.createElement('tbody');
+    for (const r of rows) { const tr = document.createElement('tr'); tr.append(cell('td', r.label), cell('td', `${r.value}${unit}`)); tbody.append(tr); }
+    table.append(thead, tbody);
+    d.append(s, table);
+    fig.append(d);
+    this.replaceChildren(fig);
+  }
+}
+define('xo-chart', XoChart);

package/src/command.js

@@ -0,0 +1,99 @@
+// @ts-check
+/**
+ * <xo-command> is a command palette: press Ctrl/Cmd+K, type, pick with the arrows, press Enter.
+ *
+ *   <xo-command shortcut="k" label="Search commands">
+ *     <a href="/articles" data-group="Go to">Articles</a>
+ *     <button data-group="Actions" data-value="new-article">New article</button>
+ *   </xo-command>
+ *
+ * - The children are the commands (links or buttons; `data-group` names the group; an icon inside is kept). They are listed in a dialog;
+ *   typing filters them by their text. ArrowUp/ArrowDown (wrapping) move the highlight (`aria-activedescendant`), Home/End jump, Enter runs it, Escape closes.
+ * - Running a command clicks its original element (a link navigates, a button runs its own handler or `xo-click`) and fires
+ *   `xo-command-run` with `{ value, label }` (`value` is `data-value`, or the href).
+ * - `open()` and `close()`; the shortcut is Ctrl/Cmd plus the key of `shortcut` (default `k`).
+ */
+import { XoElement, define, text } from '@xoong/core';
+
+let counter = 0;
+
+class XoCommand extends XoElement {
+  static props = { shortcut: String, label: String };
+
+  #id = `xo-command-${++counter}`;
+  /** @type {HTMLDialogElement | null} */ #dialog = null;
+  /** @type {HTMLInputElement | null} */ #input = null;
+  /** @type {HTMLElement | null} */ #list = null;
+  /** @type {HTMLElement[]} */ #items = [];
+  /** @type {{ el: HTMLElement, label: string, group: string, html: string }[]} */ #commands = [];
+  #active = 0;
+  #onKey = (/** @type {KeyboardEvent} */ e) => { if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === (this.shortcut || 'k').toLowerCase()) { e.preventDefault(); this.open(); } };
+
+  connected() { void this.ready().then(() => this.#init()); document.addEventListener('keydown', this.#onKey); } // the commands are the children: wait until the parser has them
+
+  #init() {
+    if (this.#dialog) return;
+    this.#commands = [...this.children].filter((c) => c instanceof HTMLElement).map((el) => ({ el: /** @type {HTMLElement} */ (el), label: (el.textContent ?? '').trim(), group: el.dataset.group ?? '', html: el.innerHTML }));
+    for (const c of this.#commands) c.el.hidden = true;
+    const dialog = document.createElement('dialog');
+    dialog.className = 'xo-command-dialog';
+    dialog.setAttribute('aria-label', this.label || text('xoong.command.label', 'Search commands'));
+    dialog.innerHTML = `<div class="xo-float xo-command"><div class="xo-command__input"><span class="ic" data-ic="search" aria-hidden="true"></span><input role="combobox" aria-expanded="true" aria-autocomplete="list" autocomplete="off"><span class="xo-kbd" aria-hidden="true">Esc</span></div><div class="xo-listbox" role="listbox"></div></div>`;
+    const input = /** @type {HTMLInputElement} */ (dialog.querySelector('input'));
+    const list = /** @type {HTMLElement} */ (dialog.querySelector('.xo-listbox'));
+    list.id = `${this.#id}-list`; list.setAttribute('aria-label', text('xoong.command.results', 'Results'));
+    input.setAttribute('aria-controls', list.id);
+    input.setAttribute('aria-label', this.label || text('xoong.command.label', 'Search commands'));
+    input.placeholder = text('xoong.command.placeholder', 'Type a command or page');
+    input.addEventListener('input', () => { this.#active = 0; this.#render(); });
+    input.addEventListener('keydown', (e) => this.#key(e));
+    dialog.addEventListener('click', (e) => { if (e.target === dialog) this.close(); }); // the backdrop
+    dialog.addEventListener('close', () => { input.value = ''; });
+    this.#dialog = dialog; this.#input = input; this.#list = list;
+    this.append(dialog);
+  }
+  disconnected() { document.removeEventListener('keydown', this.#onKey); }
+
+  open() { if (!this.#dialog || this.#dialog.open) return; this.#active = 0; this.#render(); this.#dialog.showModal(); this.#input?.focus(); }
+  close() { this.#dialog?.close(); }
+
+  #render() {
+    const q = (this.#input?.value ?? '').trim().toLowerCase();
+    const shown = this.#commands.filter((c) => !q || c.label.toLowerCase().includes(q));
+    const list = /** @type {HTMLElement} */ (this.#list);
+    list.replaceChildren();
+    this.#items = [];
+    if (!shown.length) { const p = document.createElement('p'); p.className = 'xo-option__group'; p.textContent = text('xoong.controls.noResults', 'No results'); list.append(p); }
+    let group = null;
+    shown.forEach((c, i) => {
+      if (c.group && c.group !== group) { group = c.group; const g = document.createElement('div'); g.className = 'xo-option__group'; g.setAttribute('role', 'presentation'); g.textContent = c.group; list.append(g); }
+      const o = document.createElement('button');
+      o.type = 'button'; o.className = 'xo-option'; o.setAttribute('role', 'option'); o.tabIndex = -1; o.id = `${this.#id}-o${i}`; o.innerHTML = c.html;
+      o.addEventListener('click', () => this.#run(c));
+      o.addEventListener('pointermove', () => { this.#active = i; this.#mark(); });
+      list.append(o);
+      this.#items.push(o);
+    });
+    this.#shown = shown;
+    this.#mark();
+  }
+  /** @type {typeof this.#commands} */ #shown = [];
+  #mark() {
+    this.#items.forEach((o, i) => { const on = i === this.#active; o.classList.toggle('xo-option--active', on); o.setAttribute('aria-selected', String(on)); if (on) o.scrollIntoView?.({ block: 'nearest' }); });
+    const on = this.#items[this.#active];
+    if (on) this.#input?.setAttribute('aria-activedescendant', on.id); else this.#input?.removeAttribute('aria-activedescendant');
+  }
+  #key(/** @type {KeyboardEvent} */ e) {
+    const n = this.#items.length;
+    if (e.key === 'ArrowDown' || e.key === 'ArrowUp') { e.preventDefault(); if (n) { this.#active = (this.#active + (e.key === 'ArrowDown' ? 1 : -1) + n) % n; this.#mark(); } }
+    else if (e.key === 'Home' || e.key === 'End') { e.preventDefault(); this.#active = e.key === 'Home' ? 0 : Math.max(0, n - 1); this.#mark(); }
+    else if (e.key === 'Enter') { e.preventDefault(); const c = this.#shown[this.#active]; if (c) this.#run(c); }
+  }
+  #run(/** @type {{ el: HTMLElement, label: string }} */ c) {
+    this.close();
+    const value = c.el.dataset.value ?? c.el.getAttribute('href') ?? c.label;
+    this.dispatchEvent(new CustomEvent('xo-command-run', { bubbles: true, detail: { value, label: c.label } }));
+    c.el.hidden = false; c.el.click(); c.el.hidden = true;
+  }
+}
+define('xo-command', XoCommand);

package/src/consent.js

@@ -0,0 +1,64 @@
+// @ts-check
+/**
+ * <xo-consent> is a cookie (or tracking) consent bar that remembers the choice.
+ *
+ *   <xo-consent categories="analytics,marketing" label="Cookie consent">
+ *     <b>We use two cookies.</b> One keeps you signed in, one measures anonymous visits. You choose.
+ *   </xo-consent>
+ *   <button xo-consent-open>Cookie settings</button>
+ *
+ * - The text inside is the message. Two buttons: "Essential only" (every category false) and "Accept all" (every category true).
+ * - The choice is saved in localStorage (`xoong-consent`, or `storage`) as `{ analytics: true, ... }`; the bar stays hidden until
+ *   `open()` or a click on any element with `xo-consent-open`. `xo-consent` fires with the choices when the person chooses.
+ * - Read it anywhere with `el.choices` (null until chosen). Nothing is loaded or blocked by this element: your code decides what a choice allows.
+ */
+import { XoElement, define, text } from '@xoong/core';
+
+class XoConsent extends XoElement {
+  static props = { categories: String, storage: String, label: String };
+
+  /** @type {HTMLElement | null} */ #bar = null;
+  #onOpen = (/** @type {Event} */ e) => { if (/** @type {Element} */ (e.target).closest?.('[xo-consent-open]')) this.open(); };
+  get #key() { return this.storage || 'xoong-consent'; }
+  get #names() { return (this.categories ?? '').split(',').map((s) => s.trim()).filter(Boolean); }
+
+  /** The saved choices, or null when the visitor has not chosen. */
+  get choices() { try { return JSON.parse(localStorage.getItem(this.#key) ?? 'null'); } catch { return null; } }
+
+  connected() { document.addEventListener('click', this.#onOpen); void this.ready().then(() => this.#init()); } // the message is the children: wait until the parser has them
+
+  #init() {
+    if (this.#bar) return;
+    const message = document.createElement('p');
+    message.append(...this.childNodes);
+    const row = document.createElement('div');
+    row.className = 'row-inline';
+    const make = (/** @type {string} */ label, /** @type {boolean} */ all, /** @type {boolean} */ primary) => {
+      const b = document.createElement('button');
+      b.type = 'button'; b.className = `button${primary ? ' primary' : ''}`; b.textContent = label;
+      b.addEventListener('click', () => this.#choose(all));
+      return b;
+    };
+    row.append(make(text('xoong.consent.essential', 'Essential only'), false, false), make(text('xoong.consent.all', 'Accept all'), true, true));
+    const bar = document.createElement('div');
+    bar.className = 'xo-consent';
+    bar.setAttribute('role', 'region');
+    bar.setAttribute('aria-label', this.label || text('xoong.consent.label', 'Cookie consent'));
+    bar.append(message, row);
+    this.#bar = bar;
+    this.replaceChildren(bar);
+    bar.hidden = this.choices !== null;
+  }
+  disconnected() { document.removeEventListener('click', this.#onOpen); }
+
+  /** Show the bar again (cookie settings). */
+  open() { if (this.#bar) { this.#bar.hidden = false; /** @type {HTMLElement | null} */ (this.#bar.querySelector('button.primary'))?.focus(); } }
+
+  #choose(/** @type {boolean} */ all) {
+    const choices = Object.fromEntries(this.#names.map((n) => [n, all]));
+    try { localStorage.setItem(this.#key, JSON.stringify(choices)); } catch { /* not saved */ }
+    if (this.#bar) this.#bar.hidden = true;
+    this.dispatchEvent(new CustomEvent('xo-consent', { bubbles: true, detail: choices }));
+  }
+}
+define('xo-consent', XoConsent);

package/src/controls.css

@@ -8,6 +8,13 @@
   xo-tabs > [role="tabpanel"] { padding-top: var(--xo-space-3, .75rem); }
 }
 
+@layer xoong-controls {
+  /* the hosts of the field and feedback elements: a custom element is inline until told otherwise */
+  :is(xo-date, xo-slider, xo-range-slider, xo-password, xo-copy, xo-file, xo-textarea, xo-otp, xo-progress, xo-steps, xo-stat, xo-chart, xo-accordion, xo-consent) { display: block; }
+  :is(xo-switch, xo-stepper, xo-time, xo-segmented, xo-split-button, xo-spinner, xo-avatar, xo-avatars, xo-inline-edit, xo-theme-toggle, xo-popover-anchor) { display: inline-block; }
+  xo-popover[hidden] { display: none; }
+}
+
 @layer xoong-controls {
   xo-image { display: block; position: relative; overflow: hidden; max-width: 100%; }
   xo-image > img { display: block; width: 100%; height: 100%; object-fit: var(--xo-image-fit, cover); object-position: var(--xo-image-position, center); }