@apliteni/apliteni-ui 0.25.3 → 0.27.0

package/src/components/pagination.js

@@ -0,0 +1,344 @@
+// Pagination — the strip under a table or a list, as an HTML string.
+//
+// It renders a page the CALLER computed. Rows never come in here: `page`,
+// `pageSize` and `total` are numbers, so a page counted by a server and a page
+// sliced out of an array in memory produce the same markup.
+//
+// `total: null` is the honest shape for an API that cannot count what it has not
+// fetched. The component then knows no last page, so it draws Prev and Next and
+// nothing else — see `ui-pager--open` below.
+import { esc } from './index.js';
+
+// The sizes a table offers, and the one it starts on. Named here so no call site
+// writes either number: both moved once already and would have moved in thirteen
+// files. MUI's DataGrid ships exactly this pair (default 100, options 25/50/100),
+// AG Grid defaults to 100, and the finance portal's two data-heavy surfaces
+// already page at 100. A 250 step was in the first draft of this component and
+// no surveyed kit offers one, so it went rather than being invented.
+export const PAGE_SIZES = [25, 50, 100];
+export const DEFAULT_PAGE_SIZE = 100;
+
+// The classes button({ variant: 'ghost', size: 'sm' }) emits, written out because
+// button() takes no extra class and every control here needs one of its own for
+// the React component to key on. src/components/pagination.test.js asserts the
+// two agree, so a change to button()'s class list fails there instead of drifting.
+const GHOST_SM = 'ui-btn ui-btn--ghost ui-btn--sm';
+
+const VARIANTS = ['steps', 'numbered', 'jump'];
+
+// The id seeds a <label for> and the control it names, so two pagers that share
+// one are two labels pointing at one control: the second table's "Rows" label
+// focuses the FIRST table's select, and the second select has no accessible name
+// at all. `tabs()` states the same requirement in words and leaves it there; a
+// pager is dropped under a table by a caller who is not thinking about ids, and
+// two tables on a page is the ordinary case rather than the exotic one. So an
+// omitted id is unique by construction instead. A caller who needs a stable id —
+// a server rendering the same page twice, a test — passes one.
+let seq = 0;
+const cx = (...a) => a.filter(Boolean).join(' ');
+
+// Every number here arrives from a URL in real use — `?page=-2`, `?page=abc`,
+// `?page=` — so each is coerced before it is clamped, and nothing that is not a
+// finite integer reaches the markup.
+//
+// `Number()` alone is not that check, and the first draft of this used it. It
+// reads '', '  ', null, [] and false as 0, all of which are finite: `?total=` then
+// meant "this result holds zero rows" and erased the whole component, and
+// `?pageSize=` meant one row per page. Only a number, or a string with something
+// in it, is a number here. A Symbol is refused rather than thrown on — a string
+// factory that raises a TypeError is a worse answer than a pager.
+//
+// The cap is Number.MAX_SAFE_INTEGER because above it arithmetic stops moving:
+// `at - 1 === at === at + 1`, so Prev and Next would carry the same target while
+// both rendered live, and a page past 1e21 prints as `1e+21`, which parseInt reads
+// back as 1.
+const CAP = Number.MAX_SAFE_INTEGER;
+const int = (v, fallback) => {
+  const raw = typeof v === 'number' ? v
+    : (typeof v === 'string' && v.trim() !== '') ? Number(v)
+      : NaN;
+  if (!Number.isFinite(raw)) return fallback;
+  return Math.min(Math.max(Math.trunc(raw), -CAP), CAP);
+};
+const fmt = (n) => n.toLocaleString('en-US');
+
+// A control at an end is DISABLED, never removed. Polaris states the rule as
+// "Hint when merchants are at the first or the last page by disabling the
+// corresponding button": removing it slides the next control sideways under a
+// pointer already travelling toward it, and takes away the only evidence a
+// screen-reader user has that they are at the start.
+//
+// An <a> has no disabled state, so an end that is off renders as
+// <button disabled> even when `href` was given — a link that goes nowhere reads
+// as available right up until it is followed.
+function control({ cls, page, label, href, disabled = false, current = false }) {
+  const attrs = `class="${cls}" data-page="${page}"${current ? ' aria-current="page"' : ''}`;
+  return href && !disabled
+    ? `<a href="${esc(href(page))}" ${attrs}>${esc(label)}</a>`
+    : `<button type="button" ${attrs}${disabled ? ' disabled aria-disabled="true"' : ''}>${esc(label)}</button>`;
+}
+
+/**
+ * The page numbers a `numbered` pager shows, with `null` where a run was cut.
+ *
+ * Seven slots at most: page 1, the last page, the current page with one
+ * neighbour each side, and a gap for each run removed between them. Two rules
+ * keep the strip honest — no two gaps side by side, and no gap standing in for a
+ * single page, because an ellipsis hiding one number is wider than the number
+ * and costs a click to find out what it was.
+ */
+function slotsFor(page, pageCount) {
+  const wanted = [1, pageCount, page - 1, page, page + 1]
+    .filter((n) => n >= 1 && n <= pageCount);
+  const shown = [...new Set(wanted)].sort((a, b) => a - b);
+  const out = [];
+  for (const n of shown) {
+    const prev = out.length ? out[out.length - 1] : null;
+    if (prev != null) {
+      if (n - prev === 2) out.push(prev + 1); // one page hidden — draw it, not a gap
+      else if (n - prev > 2) out.push(null);
+    }
+    out.push(n);
+  }
+  return out;
+}
+
+/**
+ * pagination({ … }) → the <nav> a caller drops under a table.
+ *
+ * A pager for a single page draws no steps: GOV.UK's guidance is "Do not show
+ * pagination if there's only one page of content", and the kit was rendering
+ * two permanently dead buttons under every short table. With no size control to
+ * offer, such a pager has no job at all and returns the empty string; with one,
+ * the <nav> stays for the size control alone — somebody looking at 25 of 25 rows
+ * may still want 100 per page — and carries `ui-pager--single`.
+ */
+export function pagination({
+  page = 1,
+  pageSize = DEFAULT_PAGE_SIZE,
+  total = null,
+  hasMore = false,
+  pageSizes = null,
+  variant = 'steps',
+  label = 'Pagination',
+  loading = false,
+  href = null,
+  id,
+} = {}) {
+  const uid = esc(String(id ?? `pager-${++seq}`));
+  const kind = VARIANTS.includes(variant) ? variant : 'steps';
+  // A size of zero or less is not a size, so it is read as absent rather than
+  // clamped to 1 — clamping turns `?pageSize=0` into 4,812 pages of one row.
+  const asked = int(pageSize, DEFAULT_PAGE_SIZE);
+  const size = asked > 0 ? asked : DEFAULT_PAGE_SIZE;
+  // A total that is not a number is a total nobody knows — the open shape is the
+  // truthful answer to it, and it is the same answer `total: null` asks for.
+  const asRows = int(total, null);
+  const counted = total != null && asRows !== null;
+  const rows = counted ? Math.max(0, asRows) : null;
+  const last = counted ? Math.max(1, Math.ceil(rows / size)) : null;
+  // One below the cap when nothing is counted, because the open shape emits
+  // `at + 1` as Next's target and MAX_SAFE_INTEGER + 1 is not representable — it
+  // rounds back onto its neighbour, so Prev and Next would carry one page again.
+  const at = counted
+    ? Math.min(Math.max(1, int(page, 1)), last)
+    : Math.min(Math.max(1, int(page, 1)), CAP - 1);
+
+  // The current size is offered even when the caller's list forgot it: a select
+  // whose value is not among its options renders as the first one, which reports
+  // a page size the table is not using.
+  // Capped: this is a string factory, and a caller who hands it a hundred thousand
+  // sizes gets a hundred thousand <option>s and megabytes of HTML rather than an
+  // error. Twelve is past any real size menu — MUI ships four.
+  const offered = (Array.isArray(pageSizes) ? pageSizes : [])
+    .slice(0, 12)
+    .map((s) => int(s, 0))
+    .filter((s) => s > 0);
+  const sizes = offered.length
+    ? [...new Set([...offered, size])].sort((a, b) => a - b)
+    : [];
+
+  const single = counted && last === 1;
+  if (single && !sizes.length) return '';
+
+  const from = (at - 1) * size + 1;
+  const to = counted ? Math.min(at * size, rows) : null;
+  // Not "1–0 of 0" for an empty result, and not "7–7 of 7" for a single row:
+  // both are arithmetic a reader has to undo.
+  const status = !counted ? `Page ${fmt(at)}`
+    : rows === 0 ? '0 of 0'
+      : from === to ? `${fmt(from)} of ${fmt(rows)}`
+        : `${fmt(from)}–${fmt(to)} of ${fmt(rows)}`;
+
+  const sizeBlock = sizes.length
+    ? `<div class="ui-pager__size">`
+      + `<label class="ui-pager__size-label" for="${uid}-size">Rows</label>`
+      + `<select class="ui-select ui-pager__size-select" id="${uid}-size"${loading ? ' disabled' : ''}>`
+      + sizes.map((s) => `<option value="${s}"${s === size ? ' selected' : ''}>${fmt(s)}</option>`).join('')
+      + `</select></div>`
+    : '';
+
+  const step = (spec) => control({ cls: `${GHOST_SM} ui-pager__step`, href, ...spec, disabled: loading || spec.disabled });
+  const atStart = at === 1;
+  const atEnd = counted && at === last;
+
+  let steps = '';
+  if (single) {
+    steps = ''; // GOV.UK: no pagination for one page of content.
+  } else if (!counted) {
+    // The open shape: no last page exists, so no control may claim to reach one.
+    // Next is off when the caller says there is nothing after this page.
+    steps = `<div class="ui-pager__steps">`
+      + step({ page: Math.max(1, at - 1), label: 'Prev', disabled: atStart })
+      + step({ page: at + 1, label: 'Next', disabled: !hasMore })
+      + `</div>`;
+  } else {
+    let middle = '';
+    if (kind === 'numbered') {
+      middle = slotsFor(at, last).map((n) => (n == null
+        ? '<span class="ui-pager__gap" aria-hidden="true">…</span>'
+        : control({
+          cls: cx(`${GHOST_SM} ui-pager__page`, n === at && 'is-current'),
+          href,
+          page: n,
+          label: fmt(n),
+          current: n === at,
+          disabled: loading,
+        }))).join('');
+    } else if (kind === 'jump') {
+      middle = `<span class="ui-pager__jump"><label for="${uid}-jump">Page</label>`
+        + `<input class="ui-input ui-pager__jump-input" id="${uid}-jump" type="number"`
+        + ` min="1" max="${last}" value="${at}"${loading ? ' disabled' : ''}>`
+        + `<span class="ui-pager__jump-of">of ${fmt(last)}</span></span>`;
+    }
+    // First and Last are the numbered variant's own job — its first and last
+    // slots are always those two pages, so a second pair of controls for them
+    // would be the same jump written twice.
+    const ends = kind !== 'numbered';
+    steps = `<div class="ui-pager__steps">`
+      + (ends ? step({ page: 1, label: 'First', disabled: atStart }) : '')
+      + step({ page: Math.max(1, at - 1), label: 'Prev', disabled: atStart })
+      + middle
+      + step({ page: Math.min(last, at + 1), label: 'Next', disabled: atEnd })
+      + (ends ? step({ page: last, label: 'Last', disabled: atEnd }) : '')
+      + `</div>`;
+  }
+
+  // The status line is the only live region in the component: a strip where the
+  // numbers, the size control and four buttons all announced would read the same
+  // change out four times.
+  return `<nav class="${cx('ui-pager', `ui-pager--${kind}`, !counted && 'ui-pager--open', single && 'ui-pager--single')}"`
+    + ` aria-label="${esc(label)}"${loading ? ' aria-busy="true"' : ''}>`
+    + `<p class="ui-pager__status" aria-live="polite" aria-atomic="true">${esc(status)}</p>`
+    + sizeBlock
+    + steps
+    + `</nav>`;
+}
+
+/**
+ * Make a rendered pager work.
+ *
+ * Every control the factory draws is inert markup until this runs: the steps
+ * carry `data-page` and nothing reads it, the size control is a `<select>` with
+ * no handler, and the jump input is an `<input>` with no handler. Shipping the
+ * `jump` variant without this meant shipping the one control that reaches an
+ * arbitrary page and having it do nothing.
+ *
+ * It reads the class contract rather than hooks of its own — `.ui-pager__step`,
+ * `.ui-pager__page`, `.ui-pager__size-select`, `.ui-pager__jump-input` — so the
+ * markup is exactly what `pagination()` already returns and the React component
+ * is still class-for-class identical to it.
+ *
+ *   const pager = wirePagination(root, {
+ *     onPage: (page) => load({ page }),
+ *     onPageSize: (size) => load({ page: 1, size }),
+ *   });
+ *
+ * Listeners are delegated from `root`, so a pager re-rendered underneath stays
+ * wired. Returns a function that removes them.
+ *
+ * A step rendered as an `<a href>` is left alone: it is a link, the browser owns
+ * it, and calling it back as well would navigate twice.
+ */
+export function wirePagination(root = document, { onPage, onPageSize } = {}) {
+  const scope = typeof root === 'string' ? document.querySelector(root) : root;
+  if (!scope || typeof scope.addEventListener !== 'function') return () => {};
+
+  const pageOf = (el) => int(el.getAttribute('data-page'), null);
+  const inPager = (el) => el && el.closest && el.closest('.ui-pager');
+
+  const onClick = (e) => {
+    const step = e.target.closest?.('.ui-pager__step, .ui-pager__page');
+    if (!step || !inPager(step) || step.tagName === 'A' || step.disabled) return;
+    const page = pageOf(step);
+    if (page !== null) onPage?.(page);
+  };
+
+  const onChange = (e) => {
+    const select = e.target.closest?.('.ui-pager__size-select');
+    if (!select || !inPager(select)) return;
+    const size = int(select.value, null);
+    if (size !== null && size > 0) onPageSize?.(size);
+  };
+
+  // Enter commits; so does leaving the box. A value the input cannot parse — it
+  // is type="number", so a rejected keystroke leaves it empty — is not a page,
+  // and the box goes back to the one it was showing rather than to page 1.
+  const commit = (box) => {
+    const asked = int(box.value, null);
+    const max = int(box.getAttribute('max'), null);
+    if (asked === null || asked < 1) {
+      box.value = box.defaultValue;
+      return;
+    }
+    const page = max === null ? asked : Math.min(asked, max);
+    box.value = String(page);
+    if (String(page) !== box.defaultValue) onPage?.(page);
+  };
+  const onKeydown = (e) => {
+    const box = e.target.closest?.('.ui-pager__jump-input');
+    if (!box || !inPager(box) || e.key !== 'Enter') return;
+    // A lone number input inside a <form> submits it on Enter, which reloads the
+    // page the reader was trying to move within.
+    e.preventDefault();
+    commit(box);
+  };
+  const onBlur = (e) => {
+    const box = e.target.closest?.('.ui-pager__jump-input');
+    if (box && inPager(box)) commit(box);
+  };
+
+  scope.addEventListener('click', onClick);
+  scope.addEventListener('change', onChange);
+  scope.addEventListener('keydown', onKeydown);
+  scope.addEventListener('focusout', onBlur);
+  return () => {
+    scope.removeEventListener('click', onClick);
+    scope.removeEventListener('change', onChange);
+    scope.removeEventListener('keydown', onKeydown);
+    scope.removeEventListener('focusout', onBlur);
+  };
+}
+
+/**
+ * Rewrite a pager's row range, in place. THIS is the announcement.
+ *
+ * The factory returns a whole `<nav>`, so the obvious way to show a new page is
+ * to replace it — which inserts a brand-new live region that already contains its
+ * text, and several screen readers say nothing at all about a region that arrived
+ * with its content. The kit has met this before and answered it the same way:
+ * `setBusy()` rewrites the line its region already holds rather than inserting a
+ * new one. why: docs/specification.md#pending-and-denied-states
+ *
+ * So a consumer re-rendering a pager should hand the new range here instead of
+ * relying on the replacement to speak. Returns the status element, or null when
+ * there is nothing to update — safe against a torn-down view.
+ */
+export function setPagerStatus(root, text) {
+  const el = typeof root === 'string' ? document.querySelector(root) : root;
+  if (!el || typeof el.querySelector !== 'function') return null;
+  const status = el.matches?.('.ui-pager__status') ? el : el.querySelector('.ui-pager__status');
+  if (!status) return null;
+  if (status.textContent !== String(text)) status.textContent = String(text);
+  return status;
+}

package/src/index.css

@@ -28,6 +28,7 @@
 @import "./styles/drawer.css";
 @import "./styles/confirm.css";
 @import "./styles/table.css";
+@import "./styles/pagination.css";
 @import "./styles/empty.css";
 @import "./styles/callout.css";
 @import "./styles/code.css";

package/src/index.js

@@ -13,6 +13,7 @@ export * from './components/feedback.js';
 export * from './components/toasts.js';
 export * from './components/success.js';
 export * from './components/loading.js';
+export * from './components/pagination.js';
 export * from './assets/icons.js';
 export * from './assets/brand.js';
 export * from './motion.js';

package/src/inline.js

@@ -41,6 +41,7 @@ export const styles = {
   drawer: read('styles/drawer.css'),
   confirm: read('styles/confirm.css'),
   table: read('styles/table.css'),
+  pagination: read('styles/pagination.css'),
   empty: read('styles/empty.css'),
   callout: read('styles/callout.css'),
   code: read('styles/code.css'),
@@ -69,6 +70,7 @@ export const cssText = [
   styles.drawer,
   styles.confirm,
   styles.table,
+  styles.pagination,
   styles.empty,
   styles.callout,
   styles.code,

package/src/styles/button.css

@@ -100,7 +100,21 @@
 .ui-btn--ghost[aria-disabled="true"] {
   background: transparent;
   border-color: transparent;
+  color: var(--disabled-ink-bare);
 }
+/* With no box, the ink is read on whatever is behind it. --disabled-ink read
+   5.18:1 on a card and 4.66:1 on --surface-3 in dark, under #220's 5.56, so the
+   ghost takes an ink set for the dullest ground: in dark 7.00 / 6.24 / 6.69 /
+   5.62 on --bg / --surface / --surface-2 / --surface-3, in light 6.50 / 6.50 /
+   6.01 / 5.60. The enabled ghost's --dim reads 1.5 times that in dark, 1.6 in light.
+
+   #273 got here the long way. It first gave the ghost the flat disabled box
+   instead, on the claim that nothing would get less readable. That was false:
+   --bg and --surface lost up to 0.46. Then the box was rendered in a pager at
+   page 1, and the boxed First and Prev read heavier than the boxless Next and
+   Last beside them: the controls that were off looked like the live ones. No
+   contrast table shows that. The box was reverted and this ink shipped.
+   Held by src/styles/button-disabled.test.js. */
 
 /* Busy: keep the label, run an indeterminate accent shimmer along the base, and
    the button is disabled (not clickable). Pass busy + the .ui-btn__bars markup.

package/src/styles/input.css

@@ -49,7 +49,13 @@
 
 /* The value a reader typed is still the value; it goes quiet, it does not fade
    into the field under it the way an opacity would take both down together. #220 */
+/* `.ui-select` joins these two in #273. It had no disabled rule at all, and it
+   sets `background: var(--surface-2)` as an author declaration — which outranks
+   the UA's own grey-out — so a disabled select rendered pixel-identical to a live
+   one. A pager marked busy showed every button and the jump input visibly off
+   beside a size control that still looked available. */
 .ui-input:disabled,
+.ui-select:disabled,
 .ui-textarea:disabled {
   background: var(--disabled-surface);
   border-color: var(--disabled-border);

package/src/styles/pagination.css

@@ -0,0 +1,124 @@
+/* ============================================================================
+ * Pagination — .ui-pager  (variants: --steps / --numbered / --jump)
+ *   --open    total unknown: Prev and Next only, no last page to reach
+ *   --single  one page of content: the size control alone, no steps
+ * The controls are .ui-btn ghost/sm and the size control is a .ui-select, so
+ * everything here is layout and the two states those sheets do not own.
+ * ========================================================================== */
+
+.ui-pager {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-3) var(--space-4);
+  font-size: var(--text-sm);
+}
+
+/* The status is the only thing anchored to the start of the strip: it is read,
+   not aimed at, and pushing the controls to the far end keeps the pointer's
+   target group in one place as the row count changes width. */
+.ui-pager__status {
+  margin: 0 auto 0 0;
+  color: var(--muted);
+  font-variant-numeric: tabular-nums;
+}
+
+.ui-pager__size {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+}
+.ui-pager__size-label { color: var(--muted); }
+
+/* .ui-select is a form field sized for a form — full width, 12px/15px padding.
+   In a pager it sits in a row of sm buttons, so it takes their scale. Two things
+   travel with that: the chevron .ui-select paints is positioned from the right
+   edge, so the padding on that side has to stay clear of it, and the height is
+   declared so this control and the jump input beside it agree on one box. */
+.ui-pager__size-select {
+  width: auto;
+  min-height: var(--space-8);
+  padding: var(--space-1) var(--space-6) var(--space-1) var(--space-2);
+  font-size: var(--text-sm);
+  border-radius: var(--radius-sm);
+  background-position: right var(--space-2) center;
+}
+
+.ui-pager__steps {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-1);
+}
+
+/* Page numbers are read as a row of equal cells, and .ui-btn--sm's padding makes
+   "1" narrower than "49" — so a strip re-flows under the pointer as the reader
+   walks into three-digit pages. The number is WCAG 2.5.8's 24px: an equalised
+   cell should not be narrower than a target is allowed to be. */
+.ui-pager__page {
+  min-width: var(--space-6);
+  font-variant-numeric: tabular-nums;
+}
+
+/* The page you are on. Guarded, because this weighs the same as `.ui-btn:disabled`
+   and is imported after it: written plainly it would repaint the current page of
+   a `loading` pager as though it were live, which is the one thing the busy state
+   must not leave behind. Spelled `[disabled]` rather than `:disabled` — the same
+   selector for the markup this component emits, and the spelling that keeps a
+   rule about an ENABLED control out of the disabled-rule sweep in
+   stories/guidelines/accessibility-floor.test.js, which reads selector text. */
+.ui-pager__page.is-current:not([disabled]) {
+  background: var(--surface-3);
+  border-color: var(--border);
+  color: var(--strong);
+  font-weight: var(--weight-semibold);
+}
+
+.ui-pager__gap {
+  padding: 0 var(--space-1);
+  color: var(--muted);
+}
+
+.ui-pager__jump {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  color: var(--muted);
+  padding: 0 var(--space-1);
+}
+/* Wide enough for four digits and the spinner a number input draws beside them;
+   in ch so it follows the type rather than a measured pixel. The height is
+   declared rather than left to the line box, because an <input> holds its value
+   in a property: it is the one control in the strip with no text of its own, and
+   nothing else gives it the 24px WCAG 2.5.8 asks of a pointer target. */
+.ui-pager__jump-input {
+  width: 8ch;
+  min-height: var(--space-8);
+  padding: var(--space-1) var(--space-2);
+  font-size: var(--text-sm);
+  border-radius: var(--radius-sm);
+  text-align: center;
+}
+
+/* A pager directly after a table stands off it. The strip owns no margin of its
+   own — it is dropped under lists and cards too, and a component that carries
+   spacing everywhere is one every caller has to cancel somewhere — so the gap is
+   declared on the one adjacency the kit can see. `.rx-pager` carried a bare
+   `margin-top: 16px` for this, which is --space-4; the number moves to the scale
+   with it rather than travelling as a literal.
+   why: docs/specification.md#spacing-and-rhythm */
+.ui-table + .ui-pager { margin-top: var(--space-4); }
+
+/* A step given an `href` is an anchor, and a host stylesheet's `a:link` is
+   (0,1,1) — which outranks `.ui-btn--ghost` at (0,1,0) and paints the enabled
+   steps in the host's link colour while the disabled ends keep --disabled-ink-bare.
+   One strip, reading as two different controls. The kit has paid for this twice
+   already and both fixes are the same shape: see the (0,2,0) note on
+   `.ui-nav .ui-nav__item` in nav.css. Storybook ships no `a:link`, so the "Pages
+   as links" story cannot show it — which is why the rule is stated rather than
+   discovered.
+   why: docs/specification.md#pagination */
+a.ui-pager__step,
+a.ui-pager__page { color: var(--dim); }
+a.ui-pager__step:hover,
+a.ui-pager__page:hover { color: var(--strong); }

package/src/tokens/tokens.css

@@ -158,6 +158,11 @@
   --disabled-ink: var(--muted);
   --disabled-surface: var(--surface-2);
   --disabled-border: var(--border);
+  /* The ink of a disabled control that paints no box of its own — a ghost button. With
+     no surface beside it, it is read on whatever is behind it, so it is set to clear the
+     floor on the dullest ground there is (--surface-3). #273
+     why: docs/specification.md#colour-and-contrast */
+  --disabled-ink-bare: #a39eb7;
 
   /* Lifted from #9b5dff, which cleared the flat surfaces and failed on its own wash over
      a card; the value was already in the ramp. --ring is var(--accent) and follows by
@@ -271,6 +276,7 @@
   --disabled-ink: var(--muted);
   --disabled-surface: var(--surface-2);
   --disabled-border: var(--border);
+  --disabled-ink-bare: #585e6c;
 
   --accent: #6a2dcc;
   --accent-strong: #6a2dcc; /* already dark enough for white text */