@xoong/controls 0.0.39 → 0.0.42

package/src/split-button.js

@@ -0,0 +1,42 @@
+// @ts-check
+/**
+ * <xo-split-button> is a main action with a menu of related actions next to it.
+ *
+ *   <xo-split-button more="More publish options">
+ *     <button class="primary" xo-click="POST /articles/{id}/publish">Publish</button>
+ *     <button xo-click="POST /articles/{id}/schedule">Schedule</button>
+ *     <a href="/articles/{id}/preview">Preview</a>
+ *   </xo-split-button>
+ *
+ * - The first child is the main button. The others become the items of an <xo-menu> opened by the arrow button, which is named by `more`
+ *   (default "More options") and has `aria-haspopup="menu"`. The arrow keys open the menu from the arrow button (the menu's own keys).
+ * - Draws `.xo-split-button > main button + xo-menu > button.icon-only[xo-menu-trigger] + items`. A `primary` class on the main button is carried over to the arrow.
+ */
+import { XoElement, define, text } from '@xoong/core';
+
+class XoSplitButton extends XoElement {
+  static props = { more: String };
+
+  connected() { void this.ready().then(() => this.#build()); } // the buttons are the children
+
+  #build() {
+    if (this.querySelector(':scope > .xo-split-button')) return;
+    const [main, ...items] = [...this.children].filter((c) => c instanceof HTMLElement);
+    if (!main) return;
+    const wrap = document.createElement('div');
+    wrap.className = 'xo-split-button';
+    const arrow = document.createElement('button');
+    arrow.type = 'button';
+    arrow.className = `${main.classList.contains('primary') ? 'primary ' : ''}icon-only`;
+    arrow.setAttribute('xo-menu-trigger', '');
+    arrow.setAttribute('aria-haspopup', 'menu');
+    arrow.setAttribute('aria-label', this.more || text('xoong.controls.moreOptions', 'More options'));
+    arrow.innerHTML = '<span class="ic" data-ic="chevron-down" aria-hidden="true"></span>';
+    const menu = document.createElement('xo-menu');
+    menu.setAttribute('label', arrow.getAttribute('aria-label') ?? '');
+    menu.append(arrow, ...items);
+    wrap.append(main, menu);
+    this.replaceChildren(wrap);
+  }
+}
+define('xo-split-button', XoSplitButton);

package/src/stat.js

@@ -0,0 +1,58 @@
+// @ts-check
+/**
+ * <xo-stat> is a KPI tile: a label, a big value, a change against before, and a sparkline from a series.
+ *
+ *   <xo-stat label="Visits" value="48,210" delta="12.4" delta-label="vs last week" series="20,22,18,26,24,32,29"></xo-stat>
+ *
+ * - `delta` is a number: positive shows an up arrow, negative a down arrow (the sign and the arrow carry the meaning, not only the colour);
+ *   `trend="down-is-good"` swaps which direction counts as good (costs, errors). `delta-label` is the text after it.
+ * - `series` (comma-separated numbers, or `el.seriesData = [...]`) draws the sparkline; it is decoration (`aria-hidden`), the numbers are in the text.
+ * - Draws `.xo-kpi > .xo-kpi__label + .xo-kpi__value + .xo-kpi__delta + svg.xo-kpi__spark`.
+ */
+import { XoElement, define, text } from '@xoong/core';
+
+const NS = 'http://www.w3.org/2000/svg';
+
+class XoStat extends XoElement {
+  static props = { label: String, value: String, delta: Number, deltaLabel: String, series: String, trend: String };
+
+  #list = /** @type {number[] | null} */ (null);
+  #built = false;
+  get seriesData() { return this.#list ?? (this.series ?? '').split(',').map((s) => s.trim()).filter(Boolean).map(Number).filter((n) => !Number.isNaN(n)); }
+  set seriesData(v) { this.#list = Array.isArray(v) ? v.map(Number) : null; if (this.#built) this.#draw(); }
+
+  connected() { this.#built = true; this.#draw(); }
+  attributeChangedCallback(attr, old, value) { super.attributeChangedCallback(attr, old, value); if (this.#built) this.#draw(); }
+
+  #draw() {
+    this.classList.add('xo-kpi');
+    const parts = [];
+    const span = (/** @type {string} */ cls, /** @type {string} */ t) => { const s = document.createElement('span'); s.className = cls; s.textContent = t; return s; };
+    parts.push(span('xo-kpi__label', this.label ?? ''), span('xo-kpi__value', this.value ?? ''));
+    if (this.hasAttribute('delta') && !Number.isNaN(this.delta)) {
+      const d = this.delta;
+      const el = span('xo-kpi__delta', '');
+      const good = this.trend === 'down-is-good' ? d <= 0 : d >= 0;
+      el.dataset.good = String(good);
+      el.dataset.direction = d > 0 ? 'up' : d < 0 ? 'down' : 'flat';
+      const icon = document.createElement('span');
+      icon.className = 'ic'; icon.dataset.ic = d >= 0 ? 'arrow-up' : 'arrow-down'; icon.setAttribute('aria-hidden', 'true');
+      const sign = d > 0 ? '+' : d < 0 ? '−' : '';
+      el.append(icon, `${sign}${Math.abs(d)}%${this.deltaLabel ? ` ${this.deltaLabel}` : ''}`);
+      el.setAttribute('aria-label', (good ? text('xoong.stat.better', '{change} better', { change: `${sign}${Math.abs(d)}%` }) : text('xoong.stat.worse', '{change} worse', { change: `${sign}${Math.abs(d)}%` })) + (this.deltaLabel ? ` ${this.deltaLabel}` : ''));
+      parts.push(el);
+    }
+    const data = this.seriesData;
+    if (data.length > 1) {
+      const lo = Math.min(...data), hi = Math.max(...data), r = hi - lo || 1;
+      const svg = document.createElementNS(NS, 'svg');
+      svg.setAttribute('class', 'xo-kpi__spark'); svg.setAttribute('viewBox', '0 0 100 32'); svg.setAttribute('preserveAspectRatio', 'none'); svg.setAttribute('aria-hidden', 'true');
+      const path = document.createElementNS(NS, 'path');
+      path.setAttribute('d', data.map((v, i) => `${i ? 'L' : 'M'}${((i / (data.length - 1)) * 100).toFixed(1)} ${(30 - ((v - lo) / r) * 28).toFixed(1)}`).join(' '));
+      svg.append(path);
+      parts.push(svg);
+    }
+    this.replaceChildren(...parts);
+  }
+}
+define('xo-stat', XoStat);

package/src/stepper.js

@@ -18,7 +18,9 @@ class XoStepper extends XoControl {
 
   setValue(v) { const n = Number(v); super.setValue(v === '' || v == null || Number.isNaN(n) ? '' : this.#clamp(n)); this.#paint(); }
   get focusTarget() { return this.#input; }
-  #clamp(/** @type {number} */ n) { return Math.min(this.max ?? Infinity, Math.max(this.min ?? -Infinity, n)); }
+  get #min() { return this.hasAttribute('min') ? /** @type {number} */ (this.min) : -Infinity; } // an absent Number prop reads as 0, so the attribute decides
+  get #max() { return this.hasAttribute('max') ? /** @type {number} */ (this.max) : Infinity; }
+  #clamp(/** @type {number} */ n) { return Math.min(this.#max, Math.max(this.#min, n)); }
   get #step() { return this.step || 1; }
 
   connected() {
@@ -42,19 +44,20 @@ class XoStepper extends XoControl {
       if (k === 'Enter') { this.#commit(); return; }
       const by = { ArrowUp: 1, ArrowDown: -1, PageUp: 10, PageDown: -10 }[k];
       if (by) { e.preventDefault(); this.#move(by); }
-      else if ((k === 'Home' && this.min != null) || (k === 'End' && this.max != null)) { e.preventDefault(); this.#set(k === 'Home' ? /** @type {number} */ (this.min) : /** @type {number} */ (this.max)); }
+      else if ((k === 'Home' && this.hasAttribute('min')) || (k === 'End' && this.hasAttribute('max'))) { e.preventDefault(); this.#set(k === 'Home' ? /** @type {number} */ (this.min) : /** @type {number} */ (this.max)); }
     });
     this.#input = input;
     this.#buttons = [button(-1, text('xoong.controls.decrease', 'Decrease'), 'minus'), button(1, text('xoong.controls.increase', 'Increase'), 'plus')];
     wrap.append(this.#buttons[0], input, this.#buttons[1]);
     this.replaceChildren(wrap);
+    if (this.hasAttribute('value')) this.setValue(this.getAttribute('value')); // the base class would keep the attribute text: a number control holds a number
     queueMicrotask(() => this.#paint());
   }
   attributeChangedCallback(attr, old, value) { super.attributeChangedCallback(attr, old, value); this.#paint(); }
 
   #move(/** @type {number} */ steps) {
     if (this.isDisabled || this.readonly) return;
-    const now = super.value === '' ? (this.min ?? 0) - (steps > 0 ? this.#step : 0) : super.value;
+    const now = super.value === '' ? (this.hasAttribute('min') ? /** @type {number} */ (this.min) : 0) - (steps > 0 ? this.#step : 0) : super.value;
     this.#set(now + steps * this.#step);
   }
   #set(/** @type {number} */ n) {
@@ -75,11 +78,11 @@ class XoStepper extends XoControl {
     const v = super.value;
     i.value = v === '' ? '' : String(v);
     i.setAttribute('aria-label', this.label || this.name || 'Number');
-    for (const [a, val] of [['aria-valuemin', this.min], ['aria-valuemax', this.max], ['aria-valuenow', v === '' ? undefined : v]]) { if (val == null) i.removeAttribute(/** @type {string} */ (a)); else i.setAttribute(/** @type {string} */ (a), String(val)); }
+    for (const [a, val] of [['aria-valuemin', this.hasAttribute('min') ? this.min : undefined], ['aria-valuemax', this.hasAttribute('max') ? this.max : undefined], ['aria-valuenow', v === '' ? undefined : v]]) { if (val == null) i.removeAttribute(/** @type {string} */ (a)); else i.setAttribute(/** @type {string} */ (a), String(val)); }
     const off = this.isDisabled || this.readonly;
     i.disabled = off;
-    this.#buttons[0].disabled = off || (v !== '' && this.min != null && v <= this.min);
-    this.#buttons[1].disabled = off || (v !== '' && this.max != null && v >= this.max);
+    this.#buttons[0].disabled = off || (v !== '' && this.hasAttribute('min') && v <= /** @type {number} */ (this.min));
+    this.#buttons[1].disabled = off || (v !== '' && this.hasAttribute('max') && v >= /** @type {number} */ (this.max));
   }
 }
 define('xo-stepper', XoStepper);

package/src/steps.js

@@ -0,0 +1,73 @@
+// @ts-check
+/**
+ * <xo-steps> shows where the person is in a flow of a few steps.
+ *
+ *   <xo-steps current="1"><span>Account</span><span>Plan</span><span>Done</span></xo-steps>
+ *   <xo-steps current="0"><ol><li>Choose</li><li>Details</li><li>Insert</li></ol></xo-steps>
+ *
+ * - The children are the data: each `li`, `[data-step]` or (when there are none of those) each child element is one step and its text is the title.
+ *   The element replaces them with `.xo-steps > .xo-step(--done) + .xo-steps__line(--done) + ...`.
+ * - `current` is the zero-based index of the step being worked on (0 by default). Steps before it are done: a check mark in the circle (named
+ *   "Completed"), never colour alone, and the line before the current step is filled. The current step has `aria-current="step"`, its circle is
+ *   marked (`is-current`) and its title is bold. A `current` equal to the number of steps (or more) marks everything done; no step is current.
+ * - The container is a `role=list` of `role=listitem` steps. It is display only: nothing is clickable and there is no value.
+ */
+import { XoElement, define, text } from '@xoong/core';
+
+class XoSteps extends XoElement {
+  static props = { current: Number, label: String };
+
+  /** @type {string[] | null} */ #titles = null;
+  #built = false;
+
+  connected() { void this.ready().then(() => this.#read()); }
+
+  #read() {
+    if (this.#built || !this.isConnected) return;
+    this.#built = true;
+    let items = [...this.querySelectorAll('li,[data-step]')];
+    if (!items.length) items = [...this.children];
+    this.#titles = items.map((el) => (el.textContent ?? '').replace(/\s+/g, ' ').trim()).filter(Boolean);
+    this.#paint();
+  }
+
+  attributeChangedCallback(attr, old, value) { super.attributeChangedCallback(attr, old, value); this.#paint(); }
+
+  #paint() {
+    const titles = this.#titles;
+    if (!titles) return;
+    const current = Math.floor(this.current) || 0;
+    const root = document.createElement('div');
+    root.className = 'xo-steps';
+    root.setAttribute('role', 'list');
+    if (this.label) root.setAttribute('aria-label', this.label);
+    titles.forEach((title, i) => {
+      const done = i < current;
+      const here = i === current;
+      if (i > 0) {
+        const line = document.createElement('span');
+        line.className = 'xo-steps__line' + (i <= current ? ' xo-steps__line--done' : '');
+        line.setAttribute('aria-hidden', 'true');
+        root.append(line);
+      }
+      const step = document.createElement('span');
+      step.className = 'xo-step' + (done ? ' xo-step--done' : '');
+      step.setAttribute('role', 'listitem');
+      if (here) step.setAttribute('aria-current', 'step');
+      const n = document.createElement('span');
+      n.className = 'xo-step__n' + (here ? ' is-current' : '');
+      if (done) {
+        n.setAttribute('role', 'img');
+        n.setAttribute('aria-label', text('xoong.steps.done', 'Completed'));
+        n.innerHTML = '<span class="ic" data-ic="check" aria-hidden="true"></span>';
+      } else n.textContent = String(i + 1);
+      const name = document.createElement(here ? 'b' : 'span');
+      if (!done && !here) name.className = 'muted';
+      name.textContent = title;
+      step.append(n, name);
+      root.append(step);
+    });
+    this.replaceChildren(root);
+  }
+}
+define('xo-steps', XoSteps);

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/textarea.js

@@ -0,0 +1,57 @@
+// @ts-check
+/**
+ * <xo-textarea> is a textarea with a character counter and a thin progress bar toward `maxlength`.
+ *
+ *   <xo-textarea name="excerpt" label="Excerpt" maxlength="160" rows="4"></xo-textarea>
+ *
+ * - The counter ("142 / 160") sits in `.hint` under the field; it is announced politely only when the text gets near the limit (the last 10%) or goes over.
+ *   Over the limit the field is invalid with a message (the browser's `maxlength` is not set, so pasted text is kept and shown red, not cut silently).
+ * - The value is the string. `input` and `change` fire like a native textarea.
+ */
+import { XoControl, define, text } from '@xoong/core';
+
+class XoTextarea extends XoControl {
+  static props = { ...XoControl.props, label: String, maxlength: Number, rows: Number, placeholder: String };
+
+  /** @type {HTMLTextAreaElement | null} */ #area = null;
+  /** @type {HTMLElement | null} */ #count = null;
+  /** @type {HTMLElement | null} */ #bar = null;
+
+  setValue(v) { super.setValue(v == null ? '' : String(v)); if (this.#area && this.#area.value !== super.value) this.#area.value = super.value; this.#paint(); }
+  get focusTarget() { return this.#area; }
+  validate(v) { return this.maxlength && String(v).length > this.maxlength ? text('xoong.controls.tooLong', 'Use at most {max} characters.', { max: this.maxlength }) : ''; }
+
+  connected() {
+    const wrap = document.createElement('div');
+    wrap.className = 'xo-textarea-meter';
+    const area = document.createElement('textarea');
+    area.addEventListener('input', (e) => { e.stopPropagation(); this.userInput(area.value); this.#paint(); });
+    area.addEventListener('change', (e) => { e.stopPropagation(); this.userChange(); });
+    const bar = document.createElement('div');
+    bar.className = 'xo-progress xo-progress--thin';
+    bar.append(document.createElement('i'));
+    const count = document.createElement('span');
+    count.className = 'hint';
+    wrap.append(area, bar);
+    this.#area = area; this.#bar = bar; this.#count = count;
+    this.replaceChildren(wrap, count);
+    queueMicrotask(() => { area.value = super.value; this.#paint(); });
+  }
+  attributeChangedCallback(attr, old, value) { super.attributeChangedCallback(attr, old, value); this.#paint(); }
+
+  #paint() {
+    const a = this.#area, c = this.#count, bar = this.#bar;
+    if (!a || !c || !bar) return;
+    const n = String(super.value).length, max = this.maxlength || 0;
+    a.rows = this.rows || 3; a.placeholder = this.placeholder ?? ''; a.disabled = this.isDisabled; a.readOnly = this.readonly;
+    a.setAttribute('aria-label', this.label || this.name || text('xoong.controls.text', 'Text'));
+    a.setAttribute('aria-invalid', String(!!max && n > max));
+    bar.hidden = !max; c.hidden = !max;
+    if (!max) return;
+    c.textContent = `${n} / ${max}`;
+    c.setAttribute('aria-live', n >= max * 0.9 ? 'polite' : 'off');
+    c.classList.toggle('error', n > max);
+    /** @type {HTMLElement} */ (bar.firstElementChild).style.width = `${Math.min(100, (n / max) * 100)}%`;
+  }
+}
+define('xo-textarea', XoTextarea);

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);