@xoong/controls 0.0.36 → 0.0.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xoong/controls",
-  "version": "0.0.36",
+  "version": "0.0.41",
   "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",
@@ -8,10 +8,17 @@
     ".": {
       "default": "./src/index.js"
     },
+    "./accordion": "./src/accordion.js",
     "./carousel": "./src/carousel.js",
+    "./chart": "./src/chart.js",
+    "./command": "./src/command.js",
+    "./consent": "./src/consent.js",
+    "./file": "./src/file.js",
+    "./popover": "./src/popover.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",
@@ -19,6 +26,7 @@
     "./menu": "./src/menu.js",
     "./switch": "./src/switch.js",
     "./tabs": "./src/tabs.js",
+    "./theme-toggle": "./src/theme-toggle.js",
     "./time": "./src/time.js",
     "./tooltip": "./src/tooltip.js"
   },
@@ -47,7 +55,7 @@
   },
   "homepage": "https://github.com/fpt-duongtx/xoong#readme",
   "dependencies": {
-    "@xoong/core": "0.0.36"
+    "@xoong/core": "0.0.41"
   },
   "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/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,18 @@
   xo-tabs > [role="tabpanel"] { padding-top: var(--xo-space-3, .75rem); }
 }
 
+@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); }
+  xo-image[data-state="loading"] { background: var(--xo-color-subtle, #eef0f3); }
+  xo-image[data-state="loading"] > img { opacity: 0; }
+  xo-image > img { transition: opacity .2s; }
+  @media (prefers-reduced-motion: reduce) { xo-image > img { transition: none; } }
+  xo-image[data-state="empty"] > img, xo-image[data-state="error"] > img { display: none; }
+  xo-image[data-state="empty"], xo-image[data-state="error"] { background: var(--xo-color-subtle, #eef0f3); min-height: 3rem; }
+  xo-image .xo-image-note { position: absolute; inset: 0; display: grid; place-items: center; padding: .5rem; text-align: center; font-size: .85rem; color: var(--xo-color-muted, #5b6470); }
+}
+
 @layer xoong-controls {
   xo-menu { display: inline-block; }
   xo-menu [role="menu"] { min-width: 10rem; padding: var(--xo-space-1, .25rem); background: var(--xo-color-surface, #fff); color: inherit; border: 1px solid var(--xo-color-border, #d8dee4); border-radius: var(--xo-radius, 6px); box-shadow: 0 6px 18px rgb(0 0 0 / .15); }

package/src/file.js

@@ -0,0 +1,115 @@
+// @ts-check
+/**
+ * <xo-file> is a file field with a drop zone: drag a file onto it, or click to browse.
+ *
+ *   <xo-file name="logo" label="Logo" accept="image/*" max-size="2MB" hint="PNG or SVG, up to 2 MB"></xo-file>
+ *   <xo-file name="attachments" multiple></xo-file>
+ *
+ * - The value is a `File` (with `multiple`: an array of files); a form sends it as multipart. `accept` takes the native syntax (`image/*`, `.pdf`);
+ *   `max-size` is bytes or `2MB`, `500KB`. A refused file shows a message and fires `xo-file-reject` with `{ file, reason }` (`type` or `size`).
+ * - Images get a thumbnail. Each file has a Remove button. `el.progress = 0.4` shows an upload progress bar (`null` hides it).
+ * - The real <input type=file> stays in the zone, visually hidden but focusable: Enter and Space open the file dialog.
+ */
+import { XoControl, define, text } from '@xoong/core';
+
+const UNITS = { b: 1, kb: 1024, mb: 1024 ** 2, gb: 1024 ** 3 };
+const bytes = (/** @type {string | undefined} */ v) => { const m = /^\s*([\d.]+)\s*([kmg]?b)?\s*$/i.exec(v ?? ''); return m ? Math.round(Number(m[1]) * UNITS[/** @type {keyof typeof UNITS} */ ((m[2] ?? 'b').toLowerCase())]) : 0; };
+const matches = (/** @type {File} */ f, /** @type {string | undefined} */ accept) => !accept || accept.split(',').map((s) => s.trim().toLowerCase()).some((a) => a.startsWith('.') ? f.name.toLowerCase().endsWith(a) : a.endsWith('/*') ? f.type.startsWith(a.slice(0, -1)) : f.type === a);
+
+class XoFile extends XoControl {
+  static props = { ...XoControl.props, label: String, accept: String, maxSize: String, multiple: Boolean, hint: String };
+
+  /** @type {HTMLInputElement | null} */ #input = null;
+  /** @type {HTMLElement | null} */ #zone = null;
+  /** @type {HTMLElement | null} */ #list = null;
+  /** @type {HTMLElement | null} */ #error = null;
+  /** @type {HTMLProgressElement | null} */ #bar = null;
+  /** @type {string[]} */ #urls = [];
+
+  get #files() { const v = super.value; return /** @type {File[]} */ (Array.isArray(v) ? v : v ? [v] : []); }
+  setValue(v) { super.setValue(this.multiple ? (Array.isArray(v) ? v : v ? [v] : []) : Array.isArray(v) ? v[0] ?? '' : v ?? ''); this.#paintList(); }
+  serialize(v) {
+    if (!Array.isArray(v)) return super.serialize(v);
+    const data = new FormData();
+    for (const f of v) data.append(this.name, f);
+    return v.length ? data : null;
+  }
+  isEmpty(v) { return !v || (Array.isArray(v) && !v.length); }
+  get focusTarget() { return this.#input; }
+
+  /** Upload progress from 0 to 1, or null to hide the bar. */
+  get progress() { return this.#bar && !this.#bar.hidden ? this.#bar.value : null; }
+  set progress(p) { if (!this.#bar) return; this.#bar.hidden = p == null; if (p != null) this.#bar.value = Math.min(1, Math.max(0, p)); }
+
+  connected() {
+    const zone = document.createElement('label');
+    zone.className = 'xo-dropzone';
+    const input = document.createElement('input');
+    input.type = 'file';
+    input.accept = this.accept ?? '';
+    input.multiple = this.multiple;
+    input.setAttribute('aria-label', this.label || this.name || text('xoong.controls.file', 'File'));
+    zone.innerHTML = `<span class="ic" data-ic="upload" aria-hidden="true"></span><span><b>${this.multiple ? text('xoong.file.dropMany', 'Drop files') : text('xoong.file.drop', 'Drop a file')}</b> ${text('xoong.file.browse', 'or click to browse')}</span>`;
+    if (this.hint) { const h = document.createElement('span'); h.textContent = this.hint; zone.append(h); }
+    zone.append(input);
+    input.addEventListener('change', () => { this.#take([...(input.files ?? [])]); input.value = ''; });
+    for (const type of ['dragenter', 'dragover']) zone.addEventListener(type, (e) => { e.preventDefault(); zone.toggleAttribute('data-over', true); });
+    for (const type of ['dragleave', 'drop']) zone.addEventListener(type, () => zone.removeAttribute('data-over'));
+    zone.addEventListener('drop', (e) => { e.preventDefault(); this.#take([...(/** @type {DragEvent} */ (e).dataTransfer?.files ?? [])]); });
+    const error = document.createElement('p');
+    error.className = 'error'; error.setAttribute('role', 'alert'); error.hidden = true;
+    const bar = document.createElement('progress');
+    bar.max = 1; bar.hidden = true; bar.setAttribute('aria-label', text('xoong.file.progress', 'Upload progress'));
+    const list = document.createElement('ul');
+    list.className = 'xo-file-list';
+    this.#input = input; this.#zone = zone; this.#error = error; this.#list = list; this.#bar = bar;
+    this.replaceChildren(zone, error, bar, list);
+    queueMicrotask(() => this.#paintList());
+  }
+  disconnected() { this.#revoke(); }
+  attributeChangedCallback(attr, old, value) {
+    super.attributeChangedCallback(attr, old, value);
+    if (this.#input) { this.#input.accept = this.accept ?? ''; this.#input.multiple = this.multiple; this.#input.disabled = this.isDisabled || this.readonly; }
+  }
+
+  #take(/** @type {File[]} */ files) {
+    const limit = bytes(this.maxSize);
+    const ok = [];
+    const refuse = (/** @type {File} */ file, /** @type {'type' | 'size'} */ reason, /** @type {string} */ message) => {
+      this.#say(message);
+      this.dispatchEvent(new CustomEvent('xo-file-reject', { bubbles: true, detail: { file, reason } }));
+    };
+    this.#say('');
+    for (const f of this.multiple ? files : files.slice(0, 1)) {
+      if (!matches(f, this.accept)) refuse(f, 'type', text('xoong.file.type', '{name} is not an allowed file type.', { name: f.name }));
+      else if (limit && f.size > limit) refuse(f, 'size', text('xoong.file.size', '{name} is too large (at most {max}).', { name: f.name, max: this.maxSize }));
+      else ok.push(f);
+    }
+    if (!ok.length) return;
+    this.userInput(this.multiple ? [...this.#files, ...ok] : ok[0]);
+    this.userChange();
+  }
+  #say(/** @type {string} */ m) { if (this.#error) { this.#error.textContent = m; this.#error.hidden = !m; } }
+  #revoke() { for (const u of this.#urls.splice(0)) URL.revokeObjectURL?.(u); }
+
+  #paintList() {
+    const list = this.#list;
+    if (!list) return;
+    this.#revoke();
+    list.replaceChildren(...this.#files.map((f) => {
+      const li = document.createElement('li');
+      if (f.type.startsWith('image/') && typeof URL.createObjectURL === 'function') {
+        const url = URL.createObjectURL(f); this.#urls.push(url);
+        const img = document.createElement('img'); img.src = url; img.alt = ''; img.width = 40; img.height = 40;
+        li.append(img);
+      }
+      const name = document.createElement('span'); name.textContent = f.name;
+      const rm = document.createElement('button');
+      rm.type = 'button'; rm.className = 'ghost sm'; rm.textContent = text('xoong.file.remove', 'Remove'); rm.setAttribute('aria-label', text('xoong.controls.remove', 'Remove {label}', { label: f.name }));
+      rm.addEventListener('click', () => { this.userInput(this.multiple ? this.#files.filter((x) => x !== f) : ''); this.userChange(); this.#input?.focus(); });
+      li.append(name, rm);
+      return li;
+    }));
+  }
+}
+define('xo-file', XoFile);

package/src/image.js

@@ -0,0 +1,84 @@
+// @ts-check
+/**
+ * <xo-image> is an image that behaves well on a page: it loads lazily, keeps its space (no layout jump), shows a placeholder while it
+ * loads and something useful when it fails.
+ *
+ *   <xo-image src="/img/cover.jpg" alt="The harbour at dusk" width="1200" height="800"></xo-image>
+ *   <xo-image src="{cover.url}" alt="{cover.alt}" ratio="16/9" fit="cover" srcset="/s.jpg 480w, /l.jpg 1200w" sizes="(min-width: 60rem) 50vw, 100vw"></xo-image>
+ *   <xo-image src="/hero.jpg" alt="" priority></xo-image>
+ *
+ * - `alt` is required: text for the image, or `alt=""` for a decorative one. `xoong check` warns when it is missing.
+ * - Lazy by default (`loading="lazy"`, `decoding="async"`). `priority` is for the one image above the fold: eager, high fetch priority.
+ * - The space is reserved from `width` and `height`, or from `ratio` (`16/9`, `1.5`). `fit` (cover by default, or contain) and `position` set how
+ *   the picture fills it (the custom properties --xo-image-fit and --xo-image-position, set through the CSS object model: no style attribute).
+ * - `srcset` and `sizes` go to the <img> as they are. A `src` that changes (in an <xo-view>, with `src="{path}"`) loads again.
+ * - `data-state` on the element: `empty` (no src), `loading` (skeleton), `loaded`, `error`. On an error the `fallback` src is tried once;
+ *   without one the alt text is shown in the box. `load` and `error` events are re-fired on the element (they do not bubble).
+ */
+import { XoElement, define } from '@xoong/core';
+
+class XoImage extends XoElement {
+  static props = { src: String, srcset: String, sizes: String, alt: String, width: Number, height: Number, ratio: String, fit: String, position: String, priority: Boolean, loading: String, fallback: String };
+
+  /** @type {HTMLImageElement | null} */ #img = null;
+  /** @type {HTMLElement | null} */ #note = null;
+  #fellBack = false;
+  #warned = false;
+
+  connected() {
+    const img = document.createElement('img');
+    img.decoding = 'async';
+    img.addEventListener('load', () => { this.#state('loaded'); this.dispatchEvent(new Event('load')); });
+    img.addEventListener('error', () => this.#failed());
+    this.#img = img;
+    this.replaceChildren(img);
+    this.#paint();
+  }
+  attributeChangedCallback(attr, old, value) {
+    super.attributeChangedCallback(attr, old, value);
+    if (attr === 'src' || attr === 'srcset') this.#fellBack = false;
+    this.#paint();
+  }
+
+  #state(/** @type {string} */ s) {
+    this.dataset.state = s;
+    if (s !== 'error') { this.#note?.remove(); this.#note = null; }
+  }
+
+  #paint() {
+    const img = this.#img;
+    if (!img) return;
+    if (!this.hasAttribute('alt') && !this.#warned) { this.#warned = true; console.warn('xoong: <xo-image> needs an alt attribute (alt="" for a decorative image)', this.getAttribute('src')); }
+    img.alt = this.alt ?? '';
+    img.loading = this.priority ? 'eager' : this.loading === 'eager' ? 'eager' : 'lazy';
+    img.fetchPriority = this.priority ? 'high' : 'auto';
+    for (const k of /** @type {const} */ (['width', 'height'])) { if (this[k]) img.setAttribute(k, String(this[k])); else img.removeAttribute(k); }
+    if (this.sizes) img.sizes = this.sizes; else img.removeAttribute('sizes');
+    const ratio = this.ratio ? this.ratio.replace(/\s/g, '') : this.width && this.height ? `${this.width}/${this.height}` : '';
+    const set = (/** @type {string} */ k, /** @type {string | null | undefined} */ v) => (v ? this.style.setProperty(k, v) : this.style.removeProperty(k));
+    set('aspect-ratio', ratio);
+    set('--xo-image-fit', this.fit);
+    set('--xo-image-position', this.position);
+    const src = this.#fellBack ? this.fallback : this.src;
+    const srcset = this.#fellBack ? '' : this.srcset;
+    if (!src && !srcset) { img.removeAttribute('src'); img.removeAttribute('srcset'); this.#state('empty'); return; }
+    if (srcset) img.srcset = srcset; else img.removeAttribute('srcset');
+    if (src && img.getAttribute('src') !== src) { this.#state('loading'); img.src = src; }
+    else if (!src) this.#state('loading');
+    if (img.complete && img.naturalWidth > 0) this.#state('loaded'); // from the cache: there may be no load event
+    else if (!this.dataset.state || this.dataset.state === 'empty') this.#state('loading');
+  }
+
+  #failed() {
+    if (this.fallback && !this.#fellBack) { this.#fellBack = true; this.#paint(); return; }
+    this.#state('error');
+    if (!this.#note) {
+      this.#note = document.createElement('span');
+      this.#note.className = 'xo-image-note';
+      this.append(this.#note);
+    }
+    this.#note.textContent = this.alt ?? '';
+    this.dispatchEvent(new Event('error'));
+  }
+}
+define('xo-image', XoImage);

package/src/index.js

@@ -11,3 +11,11 @@ import './slider.js';
 import './stepper.js';
 import './password.js';
 import './copy.js';
+import './image.js';
+import './theme-toggle.js';
+import './accordion.js';
+import './popover.js';
+import './consent.js';
+import './file.js';
+import './command.js';
+import './chart.js';

package/src/layer.js

@@ -21,17 +21,23 @@ export function showLayer(panel, anchor, { matchWidth = false } = {}) {
   panel.hidden = false;
   const top = panel.hasAttribute('popover');
   if (top && !panel.matches(':popover-open')) panel.showPopover();
+  const MARGIN = 8;
   const place = () => {
     if (!top) return;
     const r = anchor.getBoundingClientRect();
-    const room = (globalThis.innerHeight || 768) - r.bottom;
-    const height = panel.getBoundingClientRect().height;
-    const flip = room < height + 8 && r.top > room; // not enough room below and more above: open upwards
-    Object.assign(panel.style, {
-      position: 'fixed', inset: 'auto', margin: '0', left: `${r.left}px`,
-      top: flip ? `${Math.max(4, r.top - height)}px` : `${r.bottom}px`,
-      ...(matchWidth ? { width: `${r.width}px`, boxSizing: 'border-box' } : {}),
-    });
+    const vw = globalThis.innerWidth || 1024;
+    const vh = globalThis.innerHeight || 768;
+    // measure at the natural size, then fit: first the side with room, then a height limit when neither side has enough
+    Object.assign(panel.style, { position: 'fixed', inset: 'auto', margin: '0', maxHeight: '', ...(matchWidth ? { width: `${r.width}px`, boxSizing: 'border-box' } : {}) });
+    const size = panel.getBoundingClientRect();
+    const below = vh - r.bottom - MARGIN;
+    const above = r.top - MARGIN;
+    const up = below < size.height && above > below; // not enough room below and more above: open upwards
+    const room = Math.max(up ? above : below, 80);
+    const height = Math.min(size.height, room);
+    if (size.height > room) panel.style.maxHeight = `${room}px`; // the panel scrolls (the lists already have overflow)
+    const left = Math.min(Math.max(r.left, MARGIN), Math.max(MARGIN, vw - size.width - MARGIN)); // keep it inside the viewport sideways
+    Object.assign(panel.style, { left: `${left}px`, top: up ? `${Math.max(MARGIN, r.top - height)}px` : `${r.bottom}px` });
   };
   place();
   if (!top) return () => {};

package/src/popover.js

@@ -0,0 +1,72 @@
+// @ts-check
+/**
+ * <xo-popover> is a small panel that opens from a button (notifications, a menu of settings, a mini form).
+ *
+ *   <div class="xo-notify">
+ *     <button aria-label="Notifications">...</button>
+ *     <xo-popover label="Notifications">...</xo-popover>
+ *   </div>
+ *
+ * - The trigger is the element named by `anchor` (a selector), or the element just before the popover. It gets `aria-expanded` and `aria-controls`.
+ * - A click on the trigger toggles it. Escape closes it and gives the focus back to the trigger; a click outside, or Tab out of the panel, closes it.
+ * - `open()`, `close()` and `toggle()`; the property/attribute `open`; `xo-popover-open` and `xo-popover-close` fire on the element.
+ * - The panel has the class `xo-popover` (the theme draws it) and `role="region"` named by `label`. With the Popover API it is drawn in the top layer under the
+ *   trigger and kept inside the viewport (flips up when there is more room above, scrolls when neither side has enough).
+ */
+import { XoElement, define } from '@xoong/core';
+import { prepareLayer, showLayer, hideLayer } from './layer.js';
+
+let counter = 0;
+
+class XoPopover extends XoElement {
+  static props = { anchor: String, label: String, open: Boolean };
+
+  #id = `xo-popover-${++counter}`;
+  /** @type {HTMLElement | null} */ #trigger = null;
+  #onClick = () => this.toggle();
+  #onDocument = (/** @type {Event} */ e) => { const t = /** @type {Node} */ (e.target); if (!this.contains(t) && !this.#trigger?.contains(t)) this.close(); };
+
+  connected() {
+    this.classList.add('xo-popover');
+    prepareLayer(this);
+    this.setAttribute('role', 'region');
+    if (!this.id) this.id = this.#id;
+    this.#trigger = this.anchor ? document.querySelector(this.anchor) : /** @type {HTMLElement | null} */ (this.previousElementSibling);
+    const t = this.#trigger;
+    if (t) { t.setAttribute('aria-controls', this.id); t.setAttribute('aria-haspopup', 'true'); t.addEventListener('click', this.#onClick); }
+    this.addEventListener('keydown', (e) => { if (e.key === 'Escape') { e.stopPropagation(); this.close(true); } });
+    this.addEventListener('focusout', (e) => { if (this.open && e.relatedTarget && !this.contains(/** @type {Node} */ (e.relatedTarget)) && e.relatedTarget !== this.#trigger) this.close(); });
+    this.#paint();
+  }
+  disconnected() { this.#trigger?.removeEventListener('click', this.#onClick); document.removeEventListener('pointerdown', this.#onDocument); this.#stop(); }
+  #stop = () => {};
+  attributeChangedCallback(attr, old, value) { super.attributeChangedCallback(attr, old, value); this.#paint(); }
+
+  /** Open it; the focus moves to the first focusable element of the panel. */
+  show() { this.setAttribute('open', ''); }
+  toggle() { this.open ? this.close() : this.show(); }
+  /** @param {boolean} [refocus] give the focus back to the trigger */
+  close(refocus = false) { if (!this.open) return; this.removeAttribute('open'); if (refocus) this.#trigger?.focus(); }
+
+  #paint() {
+    if (!this.isConnected) return;
+    if (this.label) this.setAttribute('aria-label', this.label); else this.removeAttribute('aria-label');
+    this.#trigger?.setAttribute('aria-expanded', String(this.open));
+    if (this.open === this.#wasOpen) return;
+    if (this.open) {
+      this.#stop();
+      this.#stop = showLayer(this, this.#trigger ?? this);
+      document.addEventListener('pointerdown', this.#onDocument);
+      this.dispatchEvent(new Event('xo-popover-open', { bubbles: true }));
+      /** @type {HTMLElement | null} */ (this.querySelector('button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"])'))?.focus();
+    } else {
+      this.#stop();
+      hideLayer(this);
+      document.removeEventListener('pointerdown', this.#onDocument);
+      this.dispatchEvent(new Event('xo-popover-close', { bubbles: true }));
+    }
+    this.#wasOpen = this.open;
+  }
+  #wasOpen = false;
+}
+define('xo-popover', XoPopover);

package/src/switch.js

@@ -9,7 +9,8 @@
  * - `value` is a boolean (`checked` is the same thing as an attribute/property). The form model gets true or false; a plain <form> submits "on" when
  *   it is on and nothing when it is off, like a checkbox.
  * - `change` and `input` fire when the person toggles it. `busy` sets aria-busy and ignores clicks while a save is running.
- * - `label` is the accessible name; a <label for> pointing at the element name also works through aria-labelledby on click-through.
+ * - Text inside the element is the visible label: `<xo-switch name="n">Email me about replies</xo-switch>` draws `label.xo-switch-row > button + span.xo-switch-text`; a click on the text toggles the switch and the text is its accessible name.
+ * - `label` is the accessible name when there is no visible text (an icon-only row, a switch in a table).
  */
 import { XoControl, define } from '@xoong/core';
 
@@ -19,6 +20,7 @@ class XoSwitch extends XoControl {
   static props = { ...XoControl.props, label: String, checked: Boolean, busy: Boolean, size: String };
 
   /** @type {HTMLButtonElement | null} */ #button = null;
+  #words = false;
 
   get value() { return truthy(super.value); }
   set value(v) { super.value = truthy(v); }
@@ -31,15 +33,28 @@ class XoSwitch extends XoControl {
   isEmpty(v) { return !truthy(v); }
   get focusTarget() { return this.#button; }
 
-  connected() {
+  connected() { void this.ready().then(() => this.#build()); } // the visible text is the children: wait until the parser has them
+
+  #build() {
+    if (this.#button) return;
     if (this.hasAttribute('checked') && !this.value) this.setValue(true);
+    const words = (this.textContent ?? '').trim();
     const button = document.createElement('button');
     button.type = 'button';
     button.className = 'xo-switch';
     button.setAttribute('role', 'switch');
     button.addEventListener('click', () => this.#toggle());
     this.#button = button;
-    this.replaceChildren(button);
+    if (words) {
+      const row = document.createElement('label');
+      row.className = 'xo-switch-row';
+      const span = document.createElement('span');
+      span.className = 'xo-switch-text';
+      span.textContent = words;
+      row.append(button, span);
+      this.replaceChildren(row);
+    } else this.replaceChildren(button);
+    this.#words = !!words;
     if (this.size === 'sm') button.classList.add('xo-switch--sm');
     this.#paint();
   }
@@ -63,7 +78,7 @@ class XoSwitch extends XoControl {
     b.setAttribute('aria-checked', String(this.value));
     b.disabled = this.isDisabled;
     b.classList.toggle('xo-switch--sm', this.size === 'sm');
-    if (this.label) b.setAttribute('aria-label', this.label); else b.removeAttribute('aria-label');
+    if (this.label && !this.#words) b.setAttribute('aria-label', this.label); else b.removeAttribute('aria-label'); // visible text names it through its <label>
     if (this.busy) b.setAttribute('aria-busy', 'true'); else b.removeAttribute('aria-busy');
     if (this.readonly) b.setAttribute('aria-readonly', 'true'); else b.removeAttribute('aria-readonly');
   }

package/src/theme-toggle.js

@@ -0,0 +1,68 @@
+// @ts-check
+/**
+ * <xo-theme-toggle> lets the visitor choose the light or the dark theme.
+ *
+ *   <xo-theme-toggle></xo-theme-toggle>
+ *
+ * - A toggle button (`aria-pressed` = dark is on) that sets `data-theme="light" | "dark"` on <html>, which the themes read; the choice is saved
+ *   in localStorage (`xoong-theme`, or the `storage` attribute). Until the visitor chooses, nothing is set and the system setting
+ *   (prefers-color-scheme) decides, and the button follows it when it changes.
+ * - To avoid a flash of the wrong theme, apply the saved value in a script in the <head> before the first paint:
+ *   `try { const t = localStorage.getItem('xoong-theme'); if (t === 'light' || t === 'dark') document.documentElement.dataset.theme = t; } catch {}`
+ * - `xo-theme-change` fires with `{ theme }` ('light' | 'dark'); `reset()` forgets the choice and follows the system again.
+ */
+import { XoElement, define, text } from '@xoong/core';
+
+class XoThemeToggle extends XoElement {
+  static props = { storage: String };
+
+  /** @type {HTMLButtonElement | null} */ #button = null;
+  #query = typeof matchMedia === 'function' ? matchMedia('(prefers-color-scheme: dark)') : null;
+  #onSystem = () => this.#paint();
+  get #key() { return this.storage || 'xoong-theme'; }
+
+  /** The theme in effect: the chosen one, else the system's. */
+  get theme() {
+    const set = document.documentElement.dataset.theme;
+    return set === 'dark' || set === 'light' ? set : this.#query?.matches ? 'dark' : 'light';
+  }
+
+  connected() {
+    try { const saved = localStorage.getItem(this.#key); if (saved === 'light' || saved === 'dark') document.documentElement.dataset.theme = saved; } catch { /* not saved */ }
+    const b = document.createElement('button');
+    b.type = 'button';
+    b.className = 'icon-only ghost';
+    b.innerHTML = '<span class="ic" aria-hidden="true"></span>';
+    b.addEventListener('click', () => this.#set(this.theme === 'dark' ? 'light' : 'dark'));
+    this.#button = b;
+    this.replaceChildren(b);
+    this.#query?.addEventListener?.('change', this.#onSystem);
+    this.#paint();
+  }
+  disconnected() { this.#query?.removeEventListener?.('change', this.#onSystem); }
+
+  #set(/** @type {'light' | 'dark'} */ theme) {
+    document.documentElement.dataset.theme = theme;
+    try { localStorage.setItem(this.#key, theme); } catch { /* not saved */ }
+    this.#paint();
+    this.dispatchEvent(new CustomEvent('xo-theme-change', { bubbles: true, detail: { theme } }));
+  }
+
+  /** Forget the choice: the system setting decides again. */
+  reset() {
+    delete document.documentElement.dataset.theme;
+    try { localStorage.removeItem(this.#key); } catch { /* not saved */ }
+    this.#paint();
+    this.dispatchEvent(new CustomEvent('xo-theme-change', { bubbles: true, detail: { theme: this.theme } }));
+  }
+
+  #paint() {
+    const b = this.#button;
+    if (!b) return;
+    const dark = this.theme === 'dark';
+    b.setAttribute('aria-pressed', String(dark));
+    b.setAttribute('aria-label', text('xoong.controls.darkTheme', 'Dark theme'));
+    /** @type {HTMLElement} */ (b.firstElementChild).dataset.ic = dark ? 'sun' : 'moon';
+  }
+}
+define('xo-theme-toggle', XoThemeToggle);