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

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,293 @@
+// 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, ...data-message-params })`; otherwise
+// the item's own text; otherwise `t('fieldErrors.unknown')`. Localize once
+// via `setMessages()`. `data-message-params` is an optional JSON object of
+// server-provided interpolation values (constraint declarations, validation
+// row columns) for translations with placeholders beyond {field}/{code}.
+//
+// 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') ?? '',
+  };
+  // Optional server-provided interpolation params (a JSON object), so a
+  // catalog translation may use placeholders beyond {field}/{code} — e.g.
+  // data-message-params='{"stock": 5}' for "在庫 {stock} を超えています。".
+  // Item params win over the implicit field/code; malformed or non-object
+  // JSON degrades to the attribute being ignored.
+  const raw = item.getAttribute('data-message-params');
+  if (raw) {
+    try {
+      const extra = JSON.parse(raw);
+      if (extra && typeof extra === 'object' && !Array.isArray(extra)) {
+        Object.assign(params, extra);
+      }
+    } catch {
+      /* malformed JSON — keep the default params */
+    }
+  }
+  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-combobox.css

@@ -51,7 +51,7 @@
     min-inline-size: var(--hc-combobox-listbox-min-width);
     max-block-size: var(--hc-combobox-listbox-max-height);
     overflow-y: auto;
-    box-shadow: 0 8px 24px rgb(0, 0, 0, 0.12);
+    box-shadow: var(--hc-shadow-lg);
     list-style: none;
   }
 

package/dist/hc-command.css

@@ -36,7 +36,7 @@
     background: var(--hc-command-bg);
     color: var(--hc-command-fg);
     overflow: hidden;
-    box-shadow: 0 8px 24px rgb(0, 0, 0, 0.12);
+    box-shadow: var(--hc-shadow-lg);
   }
 
   .hc-command__input {

package/dist/hc-datagrid.css

@@ -38,7 +38,7 @@
     /* Contextual shadow cast by a frozen column's trailing edge — its
        direction flips per edge (see the frozen-edge rules below), so it
        stays a CSS-local var, not a theme token. */
-    --hc-datagrid-freeze-shadow: 2px 0 4px -2px rgb(0, 0, 0, 0.25);
+    --hc-datagrid-freeze-shadow: 2px 0 4px -2px var(--hc-shadow-edge);
 
     position: relative;
     border: 1px solid var(--hc-datagrid-border);
@@ -173,7 +173,7 @@
 
   /* RTL: the freeze line falls on the other (inline-end) side. */
   .hc-datagrid:dir(rtl) {
-    --hc-datagrid-freeze-shadow: -2px 0 4px -2px rgb(0, 0, 0, 0.25);
+    --hc-datagrid-freeze-shadow: -2px 0 4px -2px var(--hc-shadow-edge);
   }
 
   /* ---- States ----
@@ -355,7 +355,7 @@
     line-height: 1.4;
     white-space: normal;
     overflow-wrap: anywhere;
-    box-shadow: 0 4px 12px rgb(0, 0, 0, 0.25);
+    box-shadow: var(--hc-shadow-lg);
     pointer-events: none;
   }
 

package/dist/hc-dialog.css

@@ -14,7 +14,7 @@
     color: var(--hc-dialog-fg);
     max-inline-size: var(--hc-dialog-max-width);
     inline-size: calc(100% - 2 * var(--hc-space-4));
-    box-shadow: 0 10px 30px rgb(0, 0, 0, 0.15);
+    box-shadow: var(--hc-shadow-overlay);
   }
 
   .hc-dialog::backdrop {

package/dist/hc-drawer.css

@@ -30,7 +30,7 @@
     background: var(--hc-drawer-bg);
     color: var(--hc-drawer-fg);
     overflow: hidden;
-    box-shadow: 0 0 30px rgb(0, 0, 0, 0.2);
+    box-shadow: var(--hc-shadow-overlay);
 
     /* Default side = right. Specific sides override below. */
     inset-block: 0;

package/dist/hc-hovercard.css

@@ -40,7 +40,7 @@
     color: var(--hc-hovercard-fg);
     inline-size: max-content;
     max-inline-size: var(--hc-hovercard-max-width);
-    box-shadow: 0 8px 24px rgb(0, 0, 0, 0.14);
+    box-shadow: var(--hc-shadow-lg);
 
     /* Shared directional placement (hc-anchored.css). */
     --hc-anchored-offset: var(--hc-hovercard-offset);

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-menu.css

@@ -34,7 +34,7 @@
     color: var(--hc-menu-fg);
     min-inline-size: var(--hc-menu-min-width);
     max-inline-size: var(--hc-menu-max-width);
-    box-shadow: 0 8px 24px rgb(0, 0, 0, 0.12);
+    box-shadow: var(--hc-shadow-lg);
   }
 
   /* Anchor Positioning path. installMenu injects the matching

package/dist/hc-multicombobox.css

@@ -117,7 +117,7 @@
     min-inline-size: var(--hc-multicombobox-listbox-min-width);
     max-block-size: var(--hc-multicombobox-listbox-max-height);
     overflow-y: auto;
-    box-shadow: 0 8px 24px rgb(0, 0, 0, 0.12);
+    box-shadow: var(--hc-shadow-lg);
     list-style: none;
   }
 

package/dist/hc-navmenu.css

@@ -77,7 +77,7 @@
     background: var(--hc-navmenu-panel-bg);
     color: var(--hc-navmenu-panel-fg);
     min-inline-size: var(--hc-navmenu-panel-min-width);
-    box-shadow: 0 8px 24px rgb(0, 0, 0, 0.12);
+    box-shadow: var(--hc-shadow-lg);
   }
 
   /* Links inside a panel stack as a readable list. */

package/dist/hc-popover.css

@@ -14,7 +14,7 @@
     color: var(--hc-popover-fg);
     min-inline-size: var(--hc-popover-min-width);
     max-inline-size: var(--hc-popover-max-width);
-    box-shadow: 0 6px 20px rgb(0, 0, 0, 0.12);
+    box-shadow: var(--hc-shadow-lg);
 
     /* Shared directional placement (hc-anchored.css). Anchoring is opt-in via
      * data-side + installPopover; a bare popover stays browser-positioned. */

package/dist/hc-switch.css

@@ -46,7 +46,7 @@
     block-size: var(--hc-switch-thumb-size);
     background-color: var(--hc-switch-thumb-bg);
     border-radius: 50%;
-    box-shadow: 0 1px 2px rgb(0, 0, 0, 0.15);
+    box-shadow: var(--hc-shadow-sm);
     translate: 0 -50%;
     transition: translate 120ms ease;
   }

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