@hypermedia-components/core 0.0.1-alpha.0 → 0.1.0

package/dist/field-error-core.d.ts

@@ -0,0 +1,26 @@
+/** @param {Element} control */
+export function fieldOf(control: Element): Element;
+/**
+ * Append `id` to the control's `aria-describedby` token list (idempotent).
+ *
+ * @param {Element} control
+ * @param {string} id
+ */
+export function ensureDescribedBy(control: Element, id: string): void;
+/**
+ * Remove `id` from the control's `aria-describedby` token list, dropping
+ * the attribute entirely when no tokens remain.
+ *
+ * @param {Element} control
+ * @param {string} id
+ */
+export function pruneDescribedBy(control: Element, id: string): void;
+/**
+ * Find or create the field's `.hc-field__error` element, give it a stable
+ * id, and point the control's `aria-describedby` at it.
+ *
+ * @param {Element} field
+ * @param {Element} control
+ * @returns {Element}
+ */
+export function getOrCreateError(field: Element, control: Element): Element;

package/dist/field-error-core.js

@@ -0,0 +1,71 @@
+// Shared field-error plumbing for `installValidation()` (native constraint
+// validation) and `installFieldErrors()` (server-sent validation errors).
+//
+// Both behaviors surface a message inside a field's `.hc-field__error`
+// element with identical ARIA wiring (`aria-describedby` on the control,
+// `aria-live` on the message). Keeping the mechanics in one module
+// guarantees the two error sources stay byte-identical instead of
+// drifting copies. Internal module — not part of the public entry.
+
+let errorIdSeq = 0;
+
+/** @param {Element} control */
+export function fieldOf(control) {
+  return control?.closest?.('.hc-field') ?? null;
+}
+
+/**
+ * Append `id` to the control's `aria-describedby` token list (idempotent).
+ *
+ * @param {Element} control
+ * @param {string} id
+ */
+export function ensureDescribedBy(control, id) {
+  const existing = (control.getAttribute('aria-describedby') ?? '')
+    .split(/\s+/)
+    .filter(Boolean);
+  if (!existing.includes(id)) {
+    existing.push(id);
+    control.setAttribute('aria-describedby', existing.join(' '));
+  }
+}
+
+/**
+ * Remove `id` from the control's `aria-describedby` token list, dropping
+ * the attribute entirely when no tokens remain.
+ *
+ * @param {Element} control
+ * @param {string} id
+ */
+export function pruneDescribedBy(control, id) {
+  const existing = (control.getAttribute('aria-describedby') ?? '')
+    .split(/\s+/)
+    .filter(Boolean)
+    .filter((token) => token !== id);
+  if (existing.length) {
+    control.setAttribute('aria-describedby', existing.join(' '));
+  } else {
+    control.removeAttribute('aria-describedby');
+  }
+}
+
+/**
+ * Find or create the field's `.hc-field__error` element, give it a stable
+ * id, and point the control's `aria-describedby` at it.
+ *
+ * @param {Element} field
+ * @param {Element} control
+ * @returns {Element}
+ */
+export function getOrCreateError(field, control) {
+  let error = field.querySelector('.hc-field__error');
+  if (!error) {
+    error = field.ownerDocument.createElement('p');
+    error.className = 'hc-field__error';
+    error.setAttribute('aria-live', 'polite');
+    field.appendChild(error);
+  }
+  if (!error.id) error.id = `hc-field-error-${(errorIdSeq += 1)}`;
+  ensureDescribedBy(control, error.id);
+  return error;
+}

package/dist/field-errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Install the field-errors behavior: distribute server-sent
+ * `[data-hc-field-errors]` fragments (see the `field-errors` recipe) to
+ * the form fields they name, with the same ARIA wiring
+ * `installValidation()` uses.
+ *
+ * Fragments are picked up when swapped in by htmx (`htmx:afterSwap` /
+ * `htmx:oobAfterSwap`), when inserted by any other means
+ * (`MutationObserver`), and once at install time for a full-page render.
+ *
+ * @param {Document|Element} [root]
+ *   The root to watch. Defaults to the global document when available.
+ * @returns {() => void} an idempotent uninstaller.
+ */
+export function installFieldErrors(root?: Document | Element): () => void;

package/dist/field-errors.js

@@ -0,0 +1,274 @@
+// installFieldErrors — distribute a server-sent validation-error fragment
+// to the form fields it names (recipe `field-errors`).
+//
+// The canonical fragment (the server returns this on e.g. a 422; htmx
+// swaps it into a container inside — or pointed at — the form):
+//
+//   <div class="hc-alert" data-variant="error" role="alert" data-hc-field-errors>
+//     <p class="hc-alert__title">Unprocessable Entity</p>
+//     <ul class="hc-alert__errors">
+//       <li class="hc-alert__error" data-field="email" data-code="duplicate"
+//           data-message-key="members.email.duplicate">email: duplicate</li>
+//     </ul>
+//     <p class="hc-alert__body">optional hint line</p>
+//   </div>
+//
+// `data-hc-field-errors` is the opt-in: empty means "distribute into the
+// closest form"; a non-empty value is a CSS selector for the form (for
+// out-of-band swaps or an alert rendered outside the form).
+//
+// For each `.hc-alert__error[data-field]` whose name matches a control in
+// the form, the behavior writes the message into the field's
+// `.hc-field__error` (creating one after a bare control), sets
+// `aria-invalid` + `aria-describedby` on the control and `data-invalid`
+// on the field — the same wiring installValidation() uses — and marks the
+// item `data-distributed` so the summary doesn't read it twice. Items
+// naming no known control stay visible in the summary. The first invalid
+// control is focused (opt out with `data-focus="none"` on the alert).
+//
+// Message resolution per item: `data-message-key` found in the i18n
+// catalog → `t(key, { field, code })`; otherwise the item's own text;
+// otherwise `t('fieldErrors.unknown')`. Localize once via `setMessages()`.
+//
+// Server errors are stale the moment the user edits the field or
+// resubmits: cleared on first `input`/`change` per field, on `submit` /
+// `reset` of the form, and before re-distributing a newly swapped-in
+// fragment. Native constraint validation outranks a server error on the
+// same control (the native message reflects the current value).
+//
+// The behavior never makes a request — htmx owns the network. State lives
+// in HTML attributes; install is idempotent and returns an uninstaller.
+
+import {
+  ensureDescribedBy,
+  fieldOf,
+  getOrCreateError,
+  pruneDescribedBy,
+} from './field-error-core.js';
+import { hasMessage, t } from './i18n.js';
+
+const INSTALL_KEY = '__hcFieldErrorsUninstall';
+
+function escapeName(name) {
+  if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') return CSS.escape(name);
+  return name.replace(/["\\]/g, '\\$&');
+}
+
+// Resolve the scope (normally the <form>) an alert distributes into.
+function scopeOf(alert, root) {
+  const selector = alert.getAttribute('data-hc-field-errors');
+  if (selector) {
+    const doc = root.nodeType === 9 ? root : root.ownerDocument;
+    return doc.querySelector(selector);
+  }
+  return alert.closest('form');
+}
+
+// First control in the scope whose `name` matches. `form.elements`
+// handles radio/checkbox groups natively (RadioNodeList → first member).
+function controlFor(scope, name) {
+  let found;
+  if (scope.elements && typeof scope.elements.namedItem === 'function') {
+    found = scope.elements.namedItem(name);
+  } else {
+    found = scope.querySelector(`[name="${escapeName(name)}"]`);
+  }
+  if (found && found.tagName == null && typeof found.length === 'number') {
+    found = found[0] ?? null; // RadioNodeList
+  }
+  return found ?? null;
+}
+
+function resolveMessage(item) {
+  const key = item.getAttribute('data-message-key');
+  const params = {
+    field: item.getAttribute('data-field') ?? '',
+    code: item.getAttribute('data-code') ?? '',
+  };
+  if (key && hasMessage(key)) return t(key, params);
+  const text = item.textContent.trim();
+  if (text) return text;
+  return t('fieldErrors.unknown', params);
+}
+
+let ownedIdSeq = 0;
+
+// Write one or more messages (one per line) into the field's error slot —
+// or into a created slot right after a control that has no `.hc-field`.
+function applyErrors(control, messages) {
+  const doc = control.ownerDocument;
+  const field = fieldOf(control);
+  let error;
+  if (field) {
+    error = getOrCreateError(field, control);
+    field.setAttribute('data-invalid', 'true');
+  } else {
+    error = doc.createElement('p');
+    error.className = 'hc-field__error';
+    error.setAttribute('aria-live', 'polite');
+    // "owned" = created by this behavior next to a bare control; removed
+    // entirely on clear (a field's shared slot is only emptied).
+    error.setAttribute('data-hc-server-error-owned', '');
+    error.id = `hc-server-error-${(ownedIdSeq += 1)}`;
+    control.insertAdjacentElement('afterend', error);
+    ensureDescribedBy(control, error.id);
+  }
+  error.textContent = '';
+  messages.forEach((message, index) => {
+    if (index > 0) error.appendChild(doc.createElement('br'));
+    error.appendChild(doc.createTextNode(message));
+  });
+  error.setAttribute('data-hc-server-error', '');
+  control.setAttribute('aria-invalid', 'true');
+  control.dataset.hcServerInvalid = '';
+}
+
+// Clear every server error inside the scope (errors created by us are
+// removed; errors living in a field's shared slot are emptied).
+function clearServerErrors(scope) {
+  for (const control of scope.querySelectorAll('[data-hc-server-invalid]')) {
+    clearServerErrorFor(control);
+  }
+}
+
+function clearServerErrorFor(control) {
+  delete control.dataset.hcServerInvalid;
+  control.removeAttribute('aria-invalid');
+  const field = fieldOf(control);
+  if (field) field.removeAttribute('data-invalid');
+  // The error element(s) this control points at via aria-describedby.
+  const doc = control.ownerDocument;
+  const ids = (control.getAttribute('aria-describedby') ?? '').split(/\s+/).filter(Boolean);
+  for (const id of ids) {
+    const error = doc.getElementById(id);
+    if (!error || !error.hasAttribute('data-hc-server-error')) continue;
+    if (error.hasAttribute('data-hc-server-error-owned')) {
+      pruneDescribedBy(control, id);
+      error.remove();
+    } else {
+      error.textContent = '';
+      error.removeAttribute('data-hc-server-error');
+    }
+  }
+}
+
+function distribute(alert, root) {
+  if (alert.dataset.distributed != null) return;
+
+  const scope = scopeOf(alert, root);
+  if (!scope) {
+    // No form to distribute into — everything stays in the summary.
+    alert.dataset.distributed = 'none';
+    return;
+  }
+
+  clearServerErrors(scope);
+
+  const items = alert.querySelectorAll('.hc-alert__error[data-field]');
+  // Group by control so several errors for one field render one per line.
+  const perControl = new Map();
+  let distributed = 0;
+  let total = 0;
+  for (const item of items) {
+    total += 1;
+    const control = controlFor(scope, item.getAttribute('data-field'));
+    if (!control) continue; // unknown field — stays visible in the summary
+    if (!perControl.has(control)) perControl.set(control, []);
+    perControl.get(control).push(resolveMessage(item));
+    item.setAttribute('data-distributed', 'true');
+    distributed += 1;
+  }
+
+  for (const [control, messages] of perControl) {
+    applyErrors(control, messages);
+  }
+
+  alert.dataset.distributed =
+    distributed === 0 ? 'none' : distributed === total ? 'all' : 'partial';
+
+  if (alert.getAttribute('data-focus') !== 'none') {
+    const first = perControl.keys().next().value;
+    try {
+      first?.focus?.();
+    } catch {
+      /* unfocusable control — the wiring still stands */
+    }
+  }
+}
+
+function scan(node, root) {
+  if (!node || typeof node.querySelectorAll !== 'function') return;
+  if (typeof node.matches === 'function' && node.matches('[data-hc-field-errors]')) {
+    distribute(node, root);
+  }
+  for (const alert of node.querySelectorAll('[data-hc-field-errors]')) {
+    distribute(alert, root);
+  }
+}
+
+/**
+ * Install the field-errors behavior: distribute server-sent
+ * `[data-hc-field-errors]` fragments (see the `field-errors` recipe) to
+ * the form fields they name, with the same ARIA wiring
+ * `installValidation()` uses.
+ *
+ * Fragments are picked up when swapped in by htmx (`htmx:afterSwap` /
+ * `htmx:oobAfterSwap`), when inserted by any other means
+ * (`MutationObserver`), and once at install time for a full-page render.
+ *
+ * @param {Document|Element} [root]
+ *   The root to watch. Defaults to the global document when available.
+ * @returns {() => void} an idempotent uninstaller.
+ */
+export function installFieldErrors(root = (typeof document !== 'undefined' ? document : null)) {
+  if (!root) return () => {};
+  if (root[INSTALL_KEY]) return root[INSTALL_KEY];
+
+  function onSwap(event) {
+    scan(event.target, root);
+  }
+
+  function onInput(event) {
+    const el = event.target;
+    if (el?.dataset?.hcServerInvalid != null) clearServerErrorFor(el);
+  }
+
+  function onSubmitOrReset(event) {
+    const form = event.target;
+    if (form && typeof form.querySelectorAll === 'function') clearServerErrors(form);
+  }
+
+  root.addEventListener('htmx:afterSwap', onSwap);
+  root.addEventListener('htmx:oobAfterSwap', onSwap);
+  root.addEventListener('input', onInput);
+  root.addEventListener('change', onInput);
+  root.addEventListener('submit', onSubmitOrReset, true);
+  root.addEventListener('reset', onSubmitOrReset, true);
+
+  const observer = new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) {
+        if (node.nodeType === 1) scan(node, root);
+      }
+    }
+  });
+  const observeTarget = root.nodeType === 9 ? root.documentElement : root;
+  observer.observe(observeTarget, { childList: true, subtree: true });
+
+  // A full-page error render (no swap) is distributed immediately.
+  scan(observeTarget, root);
+
+  const uninstall = () => {
+    if (root[INSTALL_KEY] !== uninstall) return;
+    root.removeEventListener('htmx:afterSwap', onSwap);
+    root.removeEventListener('htmx:oobAfterSwap', onSwap);
+    root.removeEventListener('input', onInput);
+    root.removeEventListener('change', onInput);
+    root.removeEventListener('submit', onSubmitOrReset, true);
+    root.removeEventListener('reset', onSubmitOrReset, true);
+    observer.disconnect();
+    delete root[INSTALL_KEY];
+  };
+  root[INSTALL_KEY] = uninstall;
+  return uninstall;
+}

package/dist/hc-alert.css

@@ -1,7 +1,10 @@
 /* hc-alert — block-level notice / status message.
  *
  * Variants via data-variant: info (default) | success | warning | error
- * Optional parts: .hc-alert__title, .hc-alert__body
+ * Optional parts: .hc-alert__title, .hc-alert__body,
+ * .hc-alert__errors > .hc-alert__error (field-error list — see the
+ * `field-errors` recipe; `installFieldErrors()` distributes the items
+ * to their fields and marks them `data-distributed`).
  *
  * Accessibility: set role="status" (or aria-live="polite") on the
  * element for transient updates; role="alert" for urgent ones. The
@@ -34,6 +37,31 @@
     margin: 0;
   }
 
+  /* Field-error list (server validation fragment — `field-errors` recipe). */
+  .hc-alert__errors {
+    margin: 0;
+    padding-inline-start: 1.25em;
+  }
+
+  /* An item that installFieldErrors() has distributed to its field is
+   * hidden in the summary so the message isn't read twice. Items naming
+   * no known control keep rendering here. */
+  .hc-alert[data-hc-field-errors] .hc-alert__error[data-distributed="true"] {
+    display: none;
+  }
+
+  /* …and when every item was distributed, the now-empty list collapses. */
+  .hc-alert[data-hc-field-errors]
+    .hc-alert__errors:not(:has(.hc-alert__error:not([data-distributed="true"]))) {
+    display: none;
+  }
+
+  /* Opt-in: a fragment that carries only field errors (no standalone
+   * summary worth keeping) hides itself entirely once fully distributed. */
+  .hc-alert[data-hc-field-errors][data-summary="auto"][data-distributed="all"] {
+    display: none;
+  }
+
   .hc-alert[data-variant="success"] {
     background: var(--hc-alert-success-bg);
     color: var(--hc-alert-success-fg);

package/dist/hc-chip.css

@@ -0,0 +1,39 @@
+/* hc-chip — a quiet, pill-shaped token for facts and attributes
+ * (capabilities, tags, applied filters). Neutral surface + border by
+ * design: for *status* coloring use hc-badge (variant pills) or the
+ * .hc-status utility instead.
+ *
+ *   <ul class="hc-chips">
+ *     <li class="hc-chip">read:members</li>
+ *     <li class="hc-chip">write:members</li>
+ *   </ul>
+ *
+ * Pure CSS, no behavior. A chip with a trailing remove control is the
+ * multicombobox tag's job — chips here are presentational.
+ */
+@layer hc.components {
+  .hc-chip {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--hc-space-1);
+    padding-inline: var(--hc-chip-padding-x);
+    padding-block: var(--hc-chip-padding-y);
+    border: 1px solid var(--hc-chip-border);
+    border-radius: var(--hc-chip-radius);
+    background: var(--hc-chip-bg);
+    color: var(--hc-chip-fg);
+    font-size: var(--hc-chip-font-size);
+    line-height: 1.4;
+  }
+
+  /* List wrapper — strips the list chrome and wraps chips on a gap. The
+   * <ul>/<li> form keeps the set announceable as a list ("3 items"). */
+  .hc-chips {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--hc-chip-gap);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+}

package/dist/hc-item.css

@@ -52,9 +52,11 @@
     outline-offset: -2px;
   }
 
-  /* Selected — option / list selection. */
+  /* Selected — option / list selection — and the current page in a nav
+   * list (aria-current="page" on the active sidebar link). */
   .hc-item[aria-selected="true"],
-  .hc-item[data-selected] {
+  .hc-item[data-selected],
+  .hc-item[aria-current]:not([aria-current="false"]) {
     background: var(--hc-item-selected-bg);
     color: var(--hc-item-selected-fg);
   }

package/dist/hc-table.css

@@ -38,6 +38,27 @@
     padding-block: var(--hc-space-1);
   }
 
+  /* Key-value variant — a two-column definition table for detail views:
+   *
+   *   <table class="hc-table" data-variant="kv">
+   *     <tbody>
+   *       <tr><th scope="row">Realm id</th><td>local</td></tr>
+   *       <tr><th scope="row">Created</th><td>2026-06-01</td></tr>
+   *     </tbody>
+   *   </table>
+   *
+   * Keys are row headers (<th scope="row">) on a fixed inline size with
+   * muted text; values keep the body styling. No <thead> needed. */
+  .hc-table[data-variant="kv"] tbody th {
+    inline-size: var(--hc-table-kv-key-width);
+    color: var(--hc-table-kv-key-fg);
+    font-weight: var(--hc-table-header-weight);
+  }
+
+  .hc-table[data-variant="kv"] tbody tr:hover {
+    background: none;
+  }
+
   /* Horizontal-scroll wrapper for wide tables on narrow viewports. A
    * data table has no intrinsic way to shrink below its columns' content
    * width, so wrap it in this element to confine the overflow to a

package/dist/hc.behaviors.d.ts

@@ -27,5 +27,7 @@ import { installSplitter } from './splitter.js';
 import { installShell } from './shell.js';
 import { installDatagrid } from './datagrid.js';
 import { installValidation } from './validation.js';
-export { installConfirm, installToast, installCloseDialog, installClosePopover, installRemoteDialog, installTabs, installMenu, installMenubar, installNavmenu, installTooltip, installPopover, installSlider, installCombobox, installMulticombobox, installDrawer, installHovercard, installToggleGroup, installCarousel, installToolbar, installAvatar, installPasswordToggle, installContextMenu, installCommand, installCalendar, installInputOtp, installSplitter, installShell, installDatagrid, installValidation };
-export { setMessages, resetMessages, getMessages, DEFAULT_MESSAGES } from "./i18n.js";
+import { installThemeToggle } from './theme-toggle.js';
+import { installFieldErrors } from './field-errors.js';
+export { installConfirm, installToast, installCloseDialog, installClosePopover, installRemoteDialog, installTabs, installMenu, installMenubar, installNavmenu, installTooltip, installPopover, installSlider, installCombobox, installMulticombobox, installDrawer, installHovercard, installToggleGroup, installCarousel, installToolbar, installAvatar, installPasswordToggle, installContextMenu, installCommand, installCalendar, installInputOtp, installSplitter, installShell, installDatagrid, installValidation, installThemeToggle, installFieldErrors };
+export { setMessages, resetMessages, getMessages, hasMessage, DEFAULT_MESSAGES } from "./i18n.js";

package/dist/hc.behaviors.js

@@ -36,6 +36,8 @@ import { installSplitter } from './splitter.js';
 import { installShell } from './shell.js';
 import { installDatagrid } from './datagrid.js';
 import { installValidation } from './validation.js';
+import { installThemeToggle } from './theme-toggle.js';
+import { installFieldErrors } from './field-errors.js';
 
 function init() {
   installConfirm();
@@ -67,6 +69,8 @@ function init() {
   installShell();
   installDatagrid();
   installValidation();
+  installThemeToggle();
+  installFieldErrors();
 }
 
 if (typeof document !== 'undefined') {
@@ -107,9 +111,11 @@ export {
   installShell,
   installDatagrid,
   installValidation,
+  installThemeToggle,
+  installFieldErrors,
 };
 
 // i18n — set the locale before this module's auto-init runs (e.g. inline
 // before the script that imports it), or import the named installers from
 // the main entry for full control over ordering.
-export { setMessages, resetMessages, getMessages, DEFAULT_MESSAGES } from './i18n.js';
+export { setMessages, resetMessages, getMessages, hasMessage, DEFAULT_MESSAGES } from './i18n.js';