@xoong/controls 0.0.0-stage → 0.0.34

package/src/switch.js

@@ -0,0 +1,71 @@
+// @ts-check
+/**
+ * <xo-switch> is one setting on or off (the WAI-ARIA switch pattern), a form control with a boolean value.
+ *
+ *   <xo-switch name="notify" label="Email me about replies" checked></xo-switch>
+ *   <xo-switch name="menu" size="sm" label="Show in menu"></xo-switch>
+ *
+ * - It draws `button.xo-switch[role=switch][aria-checked]`; Space and Enter toggle it (a native button does this), `disabled` and `readonly` stop it.
+ * - `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.
+ */
+import { XoControl, define } from '@xoong/core';
+
+const truthy = (v) => v === true || v === 'true' || v === 'on' || v === '1' || v === 1;
+
+class XoSwitch extends XoControl {
+  static props = { ...XoControl.props, label: String, checked: Boolean, busy: Boolean, size: String };
+
+  /** @type {HTMLButtonElement | null} */ #button = null;
+
+  get value() { return truthy(super.value); }
+  set value(v) { super.value = truthy(v); }
+  setValue(v) { super.setValue(truthy(v)); this.#paint(); }
+
+  get checked() { return this.value; }
+  set checked(v) { this.setValue(!!v); }
+
+  serialize(v) { return truthy(v) ? 'on' : null; }
+  isEmpty(v) { return !truthy(v); }
+  get focusTarget() { return this.#button; }
+
+  connected() {
+    if (this.hasAttribute('checked') && !this.value) this.setValue(true);
+    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 (this.size === 'sm') button.classList.add('xo-switch--sm');
+    this.#paint();
+  }
+
+  attributeChangedCallback(attr, old, value) {
+    super.attributeChangedCallback(attr, old, value);
+    if (attr === 'checked') this.setValue(value !== null);
+    this.#paint();
+  }
+
+  #toggle() {
+    if (this.isDisabled || this.readonly || this.busy) return;
+    this.userInput(!this.value);
+    this.userChange();
+    this.#paint();
+  }
+
+  #paint() {
+    const b = this.#button;
+    if (!b) return;
+    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.busy) b.setAttribute('aria-busy', 'true'); else b.removeAttribute('aria-busy');
+    if (this.readonly) b.setAttribute('aria-readonly', 'true'); else b.removeAttribute('aria-readonly');
+  }
+}
+define('xo-switch', XoSwitch);

package/src/tabs.js

@@ -0,0 +1,119 @@
+// @ts-check
+/**
+ * <xo-tabs> turns sections into an accessible tab set (the WAI-ARIA tabs pattern, automatic activation).
+ *
+ *   <xo-tabs label="Article" value="seo">
+ *     <section xo-tab="General">...</section>
+ *     <section xo-tab="SEO" id="seo">...</section>
+ *   </xo-tabs>
+ *
+ * - The `xo-tab` attribute is the tab's label; the section's `id` is its key (the position when there is none).
+ * - `value` is the key of the selected tab (the first one by default); `tabs.select(key)` changes it. `xo-tab-change` fires with `{ value }`.
+ * - Keys: Left and Right (wrapping), Home and End move and select; only the selected tab is in the tab order.
+ * - Panels are hidden, not removed: their form controls stay in the form, so a required field on another tab still blocks submit.
+ *   On `xo-reveal` (a form found an invalid field) the tab that holds that field is selected, and the event is answered.
+ * - A tab whose panel has a control with `aria-invalid="true"` gets `data-invalid`, for a marker in CSS.
+ */
+import { XoElement, define } from '@xoong/core';
+
+let counter = 0;
+
+class XoTabs extends XoElement {
+  static props = { value: String, label: String };
+
+  /** @type {{ key: string, panel: HTMLElement, tab: HTMLButtonElement }[]} */ #items = [];
+  /** @type {HTMLElement | null} */ #list = null;
+  /** @type {MutationObserver | null} */ #watch = null;
+  #onReveal = (/** @type {Event} */ event) => {
+    const path = /** @type {CustomEvent} */ (event).detail?.path;
+    if (!path || event.defaultPrevented) return;
+    const item = this.#items.find(({ panel }) => panel.querySelector(`[name="${String(path).replace(/["\\]/g, '\\$&')}"]`));
+    if (item && !this.#isSelected(item)) { this.select(item.key); event.preventDefault(); }
+  };
+
+  connected() {
+    // The children may not exist yet when the parser connects the element: build once the tree is complete.
+    if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', () => this.#build(), { once: true });
+    else queueMicrotask(() => this.#build());
+    document.addEventListener('xo-reveal', this.#onReveal);
+  }
+
+  disconnected() {
+    document.removeEventListener('xo-reveal', this.#onReveal);
+    this.#watch?.disconnect();
+  }
+
+  /** Select a tab by key (or by position); unknown keys are ignored. */
+  select(key, { focus = false } = {}) {
+    const item = this.#items.find((i) => i.key === String(key));
+    if (!item) return;
+    const changed = this.getAttribute('value') !== item.key;
+    for (const other of this.#items) {
+      const on = other === item;
+      other.panel.hidden = !on;
+      other.tab.setAttribute('aria-selected', String(on));
+      other.tab.tabIndex = on ? 0 : -1;
+    }
+    this.setAttribute('value', item.key);
+    if (focus) item.tab.focus();
+    if (changed) this.dispatchEvent(new CustomEvent('xo-tab-change', { bubbles: true, detail: { value: item.key } }));
+  }
+
+  #isSelected(/** @type {{ tab: HTMLElement }} */ item) { return item.tab.getAttribute('aria-selected') === 'true'; }
+
+  #build() {
+    if (this.#list || !this.isConnected) return;
+    const id = `xo-tabs-${++counter}`;
+    this.querySelector(':scope > [role="tablist"]')?.remove(); // a copy of a tabs element that was already built (a view clones its content): start over
+    const panels = /** @type {HTMLElement[]} */ ([...this.children].filter((c) => c.hasAttribute('xo-tab')));
+    const list = document.createElement('div');
+    list.setAttribute('role', 'tablist');
+    if (this.label) list.setAttribute('aria-label', this.label);
+    this.#items = panels.map((panel, i) => {
+      if ('xoGenId' in panel.dataset) { panel.removeAttribute('id'); delete panel.dataset.xoGenId; } // an id made by an earlier build is not a key
+      const key = panel.id || String(i); // the section's id when it has one, else its position
+      const tab = document.createElement('button');
+      tab.type = 'button';
+      tab.id = `${id}-tab-${i}`;
+      tab.setAttribute('role', 'tab');
+      tab.dataset.tab = key;
+      tab.textContent = panel.getAttribute('xo-tab') ?? key;
+      if (!panel.id) { panel.id = `${id}-panel-${i}`; panel.dataset.xoGenId = ''; } // for aria-controls only: the key stays the position
+      tab.setAttribute('aria-controls', panel.id);
+      panel.setAttribute('role', 'tabpanel');
+      panel.setAttribute('aria-labelledby', tab.id);
+      tab.addEventListener('click', () => this.select(key));
+      list.append(tab);
+      return { key, panel, tab };
+    });
+    list.addEventListener('keydown', (event) => this.#onKey(/** @type {KeyboardEvent} */ (event)));
+    this.prepend(list);
+    this.#list = list;
+    this.select(this.#items.some((i) => i.key === this.value) ? this.value : (this.#items[0]?.key ?? ''));
+    this.#watch = new MutationObserver(() => this.#markInvalid());
+    this.#watch.observe(this, { subtree: true, attributes: true, attributeFilter: ['aria-invalid'] });
+    this.#markInvalid();
+  }
+
+  #markInvalid() {
+    for (const { panel, tab } of this.#items) tab.toggleAttribute('data-invalid', !!panel.querySelector('[aria-invalid="true"]'));
+  }
+
+  #onKey(/** @type {KeyboardEvent} */ event) {
+    const at = this.#items.findIndex((i) => i.tab === event.target);
+    if (at < 0) return;
+    const last = this.#items.length - 1;
+    const next = event.key === 'ArrowRight' ? (at === last ? 0 : at + 1)
+      : event.key === 'ArrowLeft' ? (at === 0 ? last : at - 1)
+      : event.key === 'Home' ? 0 : event.key === 'End' ? last : -1;
+    if (next < 0) return;
+    event.preventDefault();
+    this.select(this.#items[next].key, { focus: true });
+  }
+
+  attributeChangedCallback(attr, old, value) {
+    super.attributeChangedCallback(attr, old, value);
+    if (attr === 'value' && this.#list && value !== null && !this.#items.some((i) => i.key === value && this.#isSelected(i))) this.select(value);
+  }
+}
+define('xo-tabs', XoTabs);

package/src/time.js

@@ -0,0 +1,68 @@
+// @ts-check
+/**
+ * <xo-time> is a time of day as two selects, hour and minute.
+ *
+ *   <xo-time name="at" label="Time" step="15" value="09:30"></xo-time>
+ *
+ * - The value is `HH:mm` (24 hours) or '' when empty. `step` is the minutes between choices (default 5, 1 to 30); a value off the step is kept as a choice.
+ * - Choosing an hour on an empty field sets the minutes to 00. Both selects are native (keyboard and screen readers as they are), named Hour and Minute.
+ * - `change` and `input` fire when the person chooses; `min` and `max` (`HH:mm`) make a value outside invalid.
+ */
+import { XoControl, define, text } from '@xoong/core';
+
+const pad = (n) => String(n).padStart(2, '0');
+const parse = (v) => { const m = /^([01]\d|2[0-3]):([0-5]\d)$/.exec(v ?? ''); return m ? [m[1], m[2]] : null; };
+
+class XoTime extends XoControl {
+  static props = { ...XoControl.props, label: String, step: Number, min: String, max: String };
+
+  /** @type {HTMLSelectElement | null} */ #h = null;
+  /** @type {HTMLSelectElement | null} */ #m = null;
+
+  setValue(v) { super.setValue(parse(v) ? v : ''); this.#paint(); }
+  isEmpty(v) { return !v; }
+  get focusTarget() { return this.#h; }
+  validate(v) { return v && ((this.min && v < this.min) || (this.max && v > this.max)) ? text('xoong.controls.timeRange', 'Choose a time within the allowed range.') : ''; }
+
+  connected() {
+    const group = document.createElement('div');
+    group.className = 'row-inline xo-time';
+    group.setAttribute('role', 'group');
+    if (this.label) group.setAttribute('aria-label', this.label);
+    // the native `change` stops here: the control fires its own, once
+    const make = (name) => { const s = document.createElement('select'); s.setAttribute('aria-label', name); s.addEventListener('change', (e) => { e.stopPropagation(); this.#choose(); }); return s; };
+    this.#h = make(text('xoong.controls.hour', 'Hour'));
+    this.#m = make(text('xoong.controls.minute', 'Minute'));
+    const colon = document.createElement('span');
+    colon.textContent = ':'; colon.setAttribute('aria-hidden', 'true');
+    group.append(this.#h, colon, this.#m);
+    this.replaceChildren(group);
+    queueMicrotask(() => this.#paint()); // the base class applies a `value` attribute after connected()
+  }
+  attributeChangedCallback(attr, old, value) { super.attributeChangedCallback(attr, old, value); this.#paint(); }
+
+  #paint() {
+    const h = this.#h, m = this.#m;
+    if (!h || !m) return;
+    const [vh, vm] = parse(super.value) ?? ['', ''];
+    const step = Math.min(30, Math.max(1, this.step || 5));
+    const fill = (/** @type {HTMLSelectElement} */ s, /** @type {string[]} */ list, /** @type {string} */ now) => {
+      const all = list.includes(now) || !now ? list : [...list, now].sort();
+      s.replaceChildren(...['', ...all].map((t) => { const o = document.createElement('option'); o.value = t; o.textContent = t || '--'; return o; }));
+      s.value = now;
+    };
+    fill(h, Array.from({ length: 24 }, (_, i) => pad(i)), vh);
+    fill(m, Array.from({ length: Math.ceil(60 / step) }, (_, i) => pad(i * step)), vm);
+    h.disabled = m.disabled = this.isDisabled || this.readonly;
+  }
+
+  #choose() {
+    const h = /** @type {HTMLSelectElement} */ (this.#h).value;
+    let m = /** @type {HTMLSelectElement} */ (this.#m).value;
+    if (h && !m) m = '00';
+    this.setValue(h ? `${h}:${m}` : '');
+    this.userInput(super.value);
+    this.userChange();
+  }
+}
+define('xo-time', XoTime);

package/src/tooltip.js

@@ -0,0 +1,79 @@
+// @ts-check
+/**
+ * xo-tooltip="Save the draft" on any element shows a short text next to it (the WAI-ARIA tooltip pattern).
+ *
+ *   <button xo-tooltip="Save the draft">Save</button>
+ *   <button xo-tooltip="Delete" aria-label="Delete">🗑</button>
+ *
+ * - Shown after a short delay on hover, at once on keyboard focus; hidden on leave, blur, Escape or a click. The pointer may move onto the
+ *   tooltip without it closing (WCAG 1.4.13: dismissible, hoverable, persistent).
+ * - The element gets `aria-describedby` while it is shown. The text is a description, not the accessible name: an icon-only button
+ *   still needs `aria-label`.
+ * - One shared `<div role="tooltip" class="xo-tooltip">` for the page, placed above the element (below when there is no room).
+ */
+const DELAY = 400;
+
+/** @type {HTMLElement | null} */ let tip = null;
+/** @type {Element | null} */ let current = null;
+/** @type {ReturnType<typeof setTimeout> | undefined} */ let timer;
+
+function element() {
+  if (!tip) {
+    tip = document.createElement('div');
+    tip.id = 'xo-tooltip';
+    tip.className = 'xo-tooltip';
+    tip.setAttribute('role', 'tooltip');
+    tip.hidden = true;
+    if ('showPopover' in tip) tip.setAttribute('popover', 'manual');
+    tip.addEventListener('pointerleave', () => hide());
+  }
+  if (!tip.isConnected) document.body.append(tip); // a page that replaced the body gets it back
+  return tip;
+}
+
+function show(/** @type {Element} */ target) {
+  clearTimeout(timer);
+  const text = target.getAttribute('xo-tooltip');
+  if (!text) return;
+  const t = element();
+  if (current && current !== target) current.removeAttribute('aria-describedby');
+  current = target;
+  t.textContent = text;
+  t.hidden = false;
+  if (t.hasAttribute('popover') && !t.matches(':popover-open')) t.showPopover();
+  target.setAttribute('aria-describedby', t.id);
+  const r = target.getBoundingClientRect();
+  const tr = t.getBoundingClientRect();
+  const above = r.top - tr.height - 6 >= 0;
+  const left = Math.max(4, Math.min(r.left + r.width / 2 - tr.width / 2, (globalThis.innerWidth || 1024) - tr.width - 4));
+  Object.assign(t.style, { position: 'fixed', inset: 'auto', margin: '0', left: `${left}px`, top: `${above ? r.top - tr.height - 6 : r.bottom + 6}px` });
+}
+
+function hide() {
+  clearTimeout(timer);
+  if (!tip || tip.hidden) return;
+  current?.removeAttribute('aria-describedby');
+  current = null;
+  if (tip.hasAttribute('popover') && tip.matches(':popover-open')) tip.hidePopover();
+  tip.hidden = true;
+}
+
+const owner = (/** @type {EventTarget | null} */ n) => /** @type {Element | null} */ (n instanceof Element ? n.closest('[xo-tooltip]') : null);
+
+document.addEventListener('mouseover', (event) => {
+  const target = owner(event.target);
+  if (!target || target === current) return;
+  clearTimeout(timer);
+  timer = setTimeout(() => show(target), DELAY);
+});
+document.addEventListener('mouseout', (event) => {
+  const from = owner(event.target);
+  if (!from) return;
+  const to = /** @type {Node | null} */ (event.relatedTarget);
+  if (to && (from.contains(to) || tip?.contains(to))) return; // still on the element, or moving onto the tooltip
+  hide();
+});
+document.addEventListener('focusin', (event) => { const target = owner(event.target); if (target) show(target); });
+document.addEventListener('focusout', (event) => { if (owner(event.target)) hide(); });
+document.addEventListener('keydown', (event) => { if (event.key === 'Escape' && tip && !tip.hidden) hide(); });
+document.addEventListener('pointerdown', () => hide());