@wtfalch/design 0.6.0 → 0.8.0

package/dist/tf.css

@@ -363,7 +363,28 @@ body::before {
    where the flat grey reads as recessed rather than as something to use. It is
    derived rather than declared -- a new token would have to be added to every
    theme in `themes.ts`, and a theme that missed it would lose its controls. */
+/* An anchor drawn as a button. Three things the element brings that a
+   `<button>` does not, and all three have to go: the underline, the link
+   colour, and the text alignment a block anchor inherits. `cursor: pointer`
+   it already has. Disabled is `aria-disabled` here -- an anchor ignores the
+   native attribute -- so every `:disabled` rule above has an
+   `[aria-disabled='true']` twin rather than a rewrite, which leaves each
+   `button` selector at the specificity it had and every committed baseline
+   untouched. */
+a.btn {
+  text-decoration: none;
+  color: var(--text);
+  text-align: center;
+}
+
+a.btn[aria-disabled='true'] {
+  /* A disabled anchor still takes the pointer, so say so. The click itself is
+     blocked in the capture phase by the component. */
+  cursor: not-allowed;
+}
+
 button,
+a.btn,
 input,
 textarea,
 select {
@@ -387,7 +408,8 @@ select {
    the icon; the button simply had no opinion about how to arrange two things.
    `inline-flex` and a gap gives it one, and the gap replaces the space
    character people were putting between an icon and its label. */
-button {
+button,
+a.btn {
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -413,7 +435,8 @@ button[aria-pressed='true']:hover:not(:disabled) { border-color: var(--accent);
 
 /* The glyph never shrinks: in a narrow row flexbox would take it from the icon
    before the text, and half an icon is not a smaller icon. */
-button > svg { flex: none; }
+button > svg,
+a.btn > svg { flex: none; }
 
 .size-sm { font-size: var(--text-xs); padding: var(--space-1) var(--space-2); }
 
@@ -439,6 +462,7 @@ input, textarea, select { width: 100%; }
 textarea { resize: none; }
 
 button:hover:not(:disabled),
+a.btn:hover:not([aria-disabled='true']),
 input:hover:not(:disabled),
 textarea:hover:not(:disabled),
 select:hover:not(:disabled) { border-color: var(--accent); }
@@ -447,6 +471,7 @@ select:hover:not(:disabled) { border-color: var(--accent); }
    `:focus` on the fields because a focused field is a place you are typing and
    should say so however you got there. */
 button:focus-visible,
+a.btn:focus-visible,
 input:focus,
 textarea:focus,
 select:focus { outline: none; border-color: var(--accent); }
@@ -540,11 +565,13 @@ input[type='checkbox']:disabled,
 input[type='radio']:disabled { cursor: not-allowed; background: var(--panel-2); }
 
 button:disabled,
+a.btn[aria-disabled='true'],
 input:disabled,
 textarea:disabled,
 select:disabled { opacity: 0.45; cursor: not-allowed; }
 
-button.primary { background: var(--accent); border-color: var(--accent); color: var(--on-accent); }
+button.primary,
+a.btn.primary { background: var(--accent); border-color: var(--accent); color: var(--on-accent); }
 
 /* A disabled primary is not a faded primary.
    `opacity: .45` was the whole of it, and a coloured fill at 45% is still a
@@ -552,7 +579,8 @@ button.primary { background: var(--accent); border-color: var(--accent); color:
    thing on the panel. That got worse when onboarding started holding people at
    a disabled Next. So it gives up the fill entirely and becomes the shape of a
    disabled control -- the opacity then has nothing left to do. */
-button.primary:disabled {
+button.primary:disabled,
+a.btn.primary[aria-disabled='true'] {
   background: var(--panel-2);
   border-color: var(--border);
   color: var(--muted);
@@ -622,13 +650,15 @@ button[aria-busy='true']::after {
 
 /* Quiet: no border, no fill. For the action beside the action -- Cancel next to
    Save -- where a bordered box competes with the thing it is next to. */
-button.ghost {
+button.ghost,
+a.btn.ghost {
   background: transparent;
   border-color: transparent;
   color: var(--muted);
 }
 
-button.ghost:hover:not(:disabled) {
+button.ghost:hover:not(:disabled),
+a.btn.ghost:hover:not([aria-disabled='true']) {
   background: var(--panel-2);
   border-color: transparent;
   color: var(--text);
@@ -835,19 +865,22 @@ button.ghost:hover:not(:disabled) {
 /* `:where(button)` so this carries no specificity of its own: a component's
    press rule below -- a card, a tab, a rail item, all of them buttons --
    wins by coming later, instead of every one having to restate `button`. */
-:where(button):active:not(:disabled) {
+:where(button):active:not(:disabled),
+:where(a.btn):active:not([aria-disabled='true']) {
   background: color-mix(in srgb, var(--text) var(--press-ink), var(--control));
   border-color: var(--accent);
   transform: scale(var(--press-scale));
   transition: none;
 }
 
-button.primary:active:not(:disabled) {
+button.primary:active:not(:disabled),
+a.btn.primary:active:not([aria-disabled='true']) {
   background: color-mix(in srgb, var(--text) var(--press-ink), var(--accent));
   border-color: color-mix(in srgb, var(--text) var(--press-ink), var(--accent));
 }
 
-button.ghost:active:not(:disabled) {
+button.ghost:active:not(:disabled),
+a.btn.ghost:active:not([aria-disabled='true']) {
   background: color-mix(in srgb, var(--text) var(--press-ink), var(--panel-2));
   border-color: transparent;
 }
@@ -1070,7 +1103,8 @@ input:active, textarea:active, select:active { transform: none; }
 /* Full width, for the one action a card or a step is about. Not a size: a
    `block` button is the same height as any other, it just stops being a thing
    you have to aim at. */
-button.block { display: flex; width: 100%; }
+button.block,
+a.btn.block { display: flex; width: 100%; }
 
 /* The default is `size-md`, spelled once for every control.
    The paragraph above promised one scale for buttons, inputs and selects, and
@@ -1079,6 +1113,7 @@ button.block { display: flex; width: 100%; }
    could line up. The download modal's search box against its Search button was
    the version you could see from across the room. */
 button,
+a.btn,
 input,
 textarea,
 select,
@@ -1229,18 +1264,21 @@ select,
 
 /* ---- ./dangerzone.css ---- */
 /* Destructive, and legible as such standing still. */
-button.danger {
+button.danger,
+a.btn.danger {
   color: var(--bad);
   border-color: color-mix(in srgb, var(--bad) 45%, var(--border-strong));
 }
 
-button.danger:hover:not(:disabled) {
+button.danger:hover:not(:disabled),
+a.btn.danger:hover:not([aria-disabled='true']) {
   background: color-mix(in srgb, var(--bad) 12%, var(--panel));
   border-color: var(--bad);
   color: var(--bad);
 }
 
-button.danger:active:not(:disabled) {
+button.danger:active:not(:disabled),
+a.btn.danger:active:not([aria-disabled='true']) {
   background: color-mix(in srgb, var(--bad) 20%, var(--panel));
   border-color: var(--bad);
 }
@@ -3350,6 +3388,70 @@ input[type='range'].slider:disabled::-moz-range-thumb { opacity: 0; }
 
 .secret-lg > .secret-eye { padding: var(--space-2); }
 
+/* An input with something inside its edges: a glyph on the left, a hint or a
+   clear button on the right. Same arrangement as `.secret` above, and for the
+   same reason -- one grid cell with everything stacked in it, and the room
+   reserved in the input's own padding, so nothing is positioned against a
+   height that changes with `size`. */
+.adorned { display: grid; align-items: center; }
+
+.adorned > input,
+.adorned > .adorned-mark,
+.adorned > .adorned-end { grid-area: 1 / 1; }
+
+.adorned.block { width: 100%; }
+
+.adorned > .adorned-mark {
+  justify-self: start;
+  margin-left: var(--space-2);
+  color: var(--muted);
+  /* The glyph is decoration over the box; clicks belong to the input under
+     it, which is otherwise unreachable in its own left edge. */
+  pointer-events: none;
+  /* Over the input, not under it. Both share one grid cell, the input has an
+     opaque `--control` background, and it comes later in the DOM -- so
+     without this the glyph is painted and then covered, which looks exactly
+     like an icon that failed to render. `.secret` never hit this because its
+     button is written after the input. */
+  z-index: 1;
+}
+
+/* Room for the glyph, on the scale, so a density change moves the text with
+   the mark rather than leaving one behind. `--space-8` is what `.secret`
+   reserves on the right for the same reason; the scale has no 7, and an
+   undefined custom property does not fall back -- the declaration computes
+   to 0 and the text sits under the glyph. */
+.adorned-icon > input { padding-left: var(--space-8); }
+
+/* No `--space-12` on the scale; two steps that are, added. Same arithmetic
+   as `.secret-lg`. */
+.adorned-icon.adorned-lg > input { padding-left: calc(var(--space-10) + var(--space-1)); }
+
+.adorned > .adorned-end {
+  justify-self: end;
+  display: flex;
+  align-items: center;
+  gap: var(--space-1);
+  margin-right: var(--space-1);
+}
+
+/* `:has`, not a sibling combinator: the input comes *before* the end cap in
+   the DOM, so `~` reads the wrong way and matches nothing. */
+.adorned:has(> .adorned-end) > input { padding-right: var(--space-8); }
+.adorned-lg:has(> .adorned-end) > input {
+  padding-right: calc(var(--space-10) + var(--space-1));
+}
+
+/* Sized from its glyph, not `.icon-btn`'s 34px tile, which would be taller
+   than a small input -- the note above `.secret-eye` in full. */
+.adorned-clear {
+  width: auto; height: auto;
+  padding: var(--space-1);
+  opacity: 1;
+}
+
+.adorned-lg .adorned-clear { padding: var(--space-2); }
+
 /* ---- ./tour.css ---- */
 /* tour ----------------------------------------------------------------- */
 
@@ -3417,6 +3519,150 @@ input[type='range'].slider:disabled::-moz-range-thumb { opacity: 0; }
    anchored surfaces (`.pop`, `.menu-sheet`, `.cmd`) sit over everything and a
    rule of equal specificity that came earlier would lose to whatever the
    sheets they cover happen to set. */
+/* ---- ./kbd.css ---- */
+/* One rule where there were two identical ones, in `menu.css` and
+   `command.css`. Both keep their class as well, so `Menu` and `Command` are
+   `.kbd .menu-key` and `.kbd .cmd-key` now: the declarations are the same, so
+   nothing moves, and the context classes stay available for a rule that ever
+   needs to tell the two apart. */
+.kbd {
+  flex: none;
+  font-family: var(--font-mono);
+  font-size: var(--text-2xs);
+  color: var(--muted);
+  letter-spacing: var(--tracking);
+}
+
+/* ---- ./stat.css ---- */
+/* A figure with furniture. `--space-1` between the three lines because they
+   are one object read top to bottom, not three paragraphs. */
+.stat {
+  display: grid;
+  gap: var(--space-1);
+  padding: var(--space-4);
+  border: var(--border-width) solid var(--border);
+  border-radius: var(--radius-md);
+  background: var(--panel);
+}
+
+/* Inside something already bordered. A bordered tile in a bordered row is two
+   boxes saying one thing. */
+.stat-bare {
+  padding: 0;
+  border: 0;
+  border-radius: 0;
+  background: none;
+  gap: 0;
+  line-height: 1.25;
+}
+
+.stat > p { margin: 0; }
+
+.stat-label {
+  color: var(--muted);
+  font-size: var(--text-xs);
+}
+
+/* Tabular figures are the point: a column of numbers is compared by its
+   digits' positions, and proportional ones move them per row. */
+.stat-value {
+  font-size: var(--text-lg);
+  font-weight: var(--weight-strong);
+  font-variant-numeric: tabular-nums;
+}
+
+.stat-bare .stat-value { font-size: var(--text-sm); }
+
+.stat-note {
+  color: var(--muted);
+  font-size: var(--text-xs);
+}
+
+/* Only the figure takes the colour. Colouring the label too makes the tile a
+   status box, and a tone here is a remark about the number. */
+.stat[data-tone='info'] .stat-value { color: var(--info); }
+.stat[data-tone='good'] .stat-value { color: var(--good); }
+.stat[data-tone='warn'] .stat-value { color: var(--warn); }
+.stat[data-tone='bad'] .stat-value { color: var(--bad); }
+
+/* ---- ./shell.css ---- */
+/* The frame. Layout only: every colour and every step is a token, and the
+   page inside it owns its own spacing. */
+.shell {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+  background: var(--bg);
+  color: var(--text);
+}
+
+.shell-head {
+  border-bottom: var(--border-width) solid var(--border);
+  background: var(--panel);
+  /* `flex: none` so a long page does not squeeze the header. */
+  flex: none;
+}
+
+/* The measure, said once. `--shell-measure` rather than a literal so an app
+   with a different one sets a variable instead of overriding three rules and
+   missing the fourth -- which is how manage ended up with `head-inner-wide`
+   and `main-wide` as separate classes. */
+.shell {
+  --shell-measure: 64rem;
+  --shell-measure-wide: 90rem;
+}
+
+.shell-head-inner,
+.shell-nav,
+.shell-main {
+  width: 100%;
+  max-width: var(--shell-measure);
+  margin-inline: auto;
+  padding-inline: var(--space-4);
+}
+
+.shell-wide { max-width: var(--shell-measure-wide); }
+
+.shell-head-inner {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-4);
+  padding-block: var(--space-3);
+  min-width: 0;
+}
+
+.shell-who {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  min-width: 0;
+}
+
+.shell-nav { padding-bottom: var(--space-2); }
+
+.shell-main {
+  flex: 1;
+  padding-block: var(--space-6);
+  /* `min-width: 0` because a flex child will not shrink below its content,
+     and one wide table inside then pushes the whole page sideways. */
+  min-width: 0;
+}
+
+/* The label beside the theme control, when it is drawn. */
+.theme-switch {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-width: 0;
+}
+
+.theme-switch-label {
+  color: var(--muted);
+  font-size: var(--text-sm);
+  white-space: nowrap;
+}
+
 /* ---- ./scrollarea.css ---- */
 /* A box that scrolls, with its edges drawn.
    

package/dist/themes/choice.d.ts

@@ -0,0 +1,71 @@
+/**
+ * A person's theme, remembered, and applied before the page is drawn.
+ *
+ * **Three apps wrote this and two of them wrote it identically.**
+ * `src/theme/first-paint.ts` is byte-for-byte the same file in
+ * wtfalch-manage and app-template; valet's is the same script with the
+ * comment rewritten. Each also keeps a `themes.ts` listing ids and labels the
+ * package already knows -- a `Theme` carries the `name` a picker shows, and a
+ * `Product` carries its themes and which one it wears by default -- so the
+ * app-side list was a second copy of a fact, kept in step by hand.
+ *
+ * **The script is a string, and it has to be.** It runs before the bundle, in
+ * a blocking `<script>` in `<head>`, because a theme applied after hydration
+ * means a person who chose Paper sees Night for a frame. That is the whole
+ * reason this is not simply a `useEffect`.
+ *
+ * **It sets `data-theme` and nothing else.** The palettes ship as CSS from
+ * `productCss`, generated from the same objects the contrast test measures,
+ * so the attribute is the entire mechanism. `applyTheme` writes custom
+ * properties instead and is for the case with no stylesheet to lean on --
+ * theming a subtree, or a product whose CSS is not the one loaded.
+ *
+ * A copy of this shipped with a bug worth keeping: a stored id the app no
+ * longer offers has to fall back, or a browser that remembers `sepia` from a
+ * palette you dropped renders unthemed. The list is inlined into the script
+ * for that check.
+ */
+import type { BrandName } from '../components/brandMarks.js';
+import { type Product } from '../products/index.js';
+/** Where the choice lives. One key across the estate, so a person who picked
+ *  Night on one app is not asked again on the next one under the same
+ *  origin. The README has used this name since 0.1.0. */
+export declare const THEME_STORAGE_KEY = "theme";
+export interface ThemeChoice {
+    id: string;
+    /** What the picker calls it -- the theme's own `name`. */
+    label: string;
+    /** The line under it, where a picker has room. */
+    note: string;
+}
+/**
+ * What this product offers, in the order it declared them.
+ *
+ * `only` narrows to a subset, for an app that ships a product's palette
+ * without all of its themes. An id the product does not have is dropped
+ * rather than thrown on: the list is presentation, and a picker missing a row
+ * is better than a page that will not render.
+ */
+export declare function themeChoices(product: BrandName | Product, only?: readonly string[]): ThemeChoice[];
+/**
+ * The blocking script, as a string to put in a `<script>` in `<head>`.
+ *
+ * `dangerouslySetInnerHTML={{ __html: themeChoiceScript('tf') }}` in a Next
+ * root layout, above everything. It reads the stored id, checks it against
+ * what this app offers, and writes `data-theme` on `<html>`.
+ *
+ * Wrapped in try/catch because `localStorage` throws outright in a browser
+ * set to block site data, and an exception here happens before anything is
+ * drawn -- so the page that fails to read a preference would otherwise fail
+ * to render at all.
+ */
+export declare function themeChoiceScript(product: BrandName | Product, options?: {
+    only?: readonly string[];
+    storageKey?: string;
+}): string;
+/** What the script would have written, for code that needs the same answer
+ *  after hydration. Reads the same key and applies the same fallback. */
+export declare function storedTheme(product: BrandName | Product, options?: {
+    only?: readonly string[];
+    storageKey?: string;
+}): string;

package/dist/themes/choice.js

@@ -0,0 +1,81 @@
+/**
+ * A person's theme, remembered, and applied before the page is drawn.
+ *
+ * **Three apps wrote this and two of them wrote it identically.**
+ * `src/theme/first-paint.ts` is byte-for-byte the same file in
+ * wtfalch-manage and app-template; valet's is the same script with the
+ * comment rewritten. Each also keeps a `themes.ts` listing ids and labels the
+ * package already knows -- a `Theme` carries the `name` a picker shows, and a
+ * `Product` carries its themes and which one it wears by default -- so the
+ * app-side list was a second copy of a fact, kept in step by hand.
+ *
+ * **The script is a string, and it has to be.** It runs before the bundle, in
+ * a blocking `<script>` in `<head>`, because a theme applied after hydration
+ * means a person who chose Paper sees Night for a frame. That is the whole
+ * reason this is not simply a `useEffect`.
+ *
+ * **It sets `data-theme` and nothing else.** The palettes ship as CSS from
+ * `productCss`, generated from the same objects the contrast test measures,
+ * so the attribute is the entire mechanism. `applyTheme` writes custom
+ * properties instead and is for the case with no stylesheet to lean on --
+ * theming a subtree, or a product whose CSS is not the one loaded.
+ *
+ * A copy of this shipped with a bug worth keeping: a stored id the app no
+ * longer offers has to fall back, or a browser that remembers `sepia` from a
+ * palette you dropped renders unthemed. The list is inlined into the script
+ * for that check.
+ */
+import { PRODUCTS } from '../products/index.js';
+/** Where the choice lives. One key across the estate, so a person who picked
+ *  Night on one app is not asked again on the next one under the same
+ *  origin. The README has used this name since 0.1.0. */
+export const THEME_STORAGE_KEY = 'theme';
+function resolve(product) {
+    return typeof product === 'string' ? PRODUCTS[product] : product;
+}
+/**
+ * What this product offers, in the order it declared them.
+ *
+ * `only` narrows to a subset, for an app that ships a product's palette
+ * without all of its themes. An id the product does not have is dropped
+ * rather than thrown on: the list is presentation, and a picker missing a row
+ * is better than a page that will not render.
+ */
+export function themeChoices(product, only) {
+    const p = resolve(product);
+    const ids = only ? only.filter((id) => id in p.themes) : Object.keys(p.themes);
+    return ids.map((id) => ({ id, label: p.themes[id].name, note: p.themes[id].note }));
+}
+/**
+ * The blocking script, as a string to put in a `<script>` in `<head>`.
+ *
+ * `dangerouslySetInnerHTML={{ __html: themeChoiceScript('tf') }}` in a Next
+ * root layout, above everything. It reads the stored id, checks it against
+ * what this app offers, and writes `data-theme` on `<html>`.
+ *
+ * Wrapped in try/catch because `localStorage` throws outright in a browser
+ * set to block site data, and an exception here happens before anything is
+ * drawn -- so the page that fails to read a preference would otherwise fail
+ * to render at all.
+ */
+export function themeChoiceScript(product, options = {}) {
+    const p = resolve(product);
+    const ids = themeChoices(product, options.only).map((c) => c.id);
+    const key = JSON.stringify(options.storageKey ?? THEME_STORAGE_KEY);
+    const fallback = JSON.stringify(ids.includes(p.defaultTheme) ? p.defaultTheme : (ids[0] ?? p.defaultTheme));
+    return `(function(){try{var t=localStorage.getItem(${key});document.documentElement.dataset.theme=${JSON.stringify(ids)}.indexOf(t)>=0?t:${fallback}}catch(e){}})()`;
+}
+/** What the script would have written, for code that needs the same answer
+ *  after hydration. Reads the same key and applies the same fallback. */
+export function storedTheme(product, options = {}) {
+    const p = resolve(product);
+    const ids = themeChoices(product, options.only).map((c) => c.id);
+    const fallback = ids.includes(p.defaultTheme) ? p.defaultTheme : (ids[0] ?? p.defaultTheme);
+    try {
+        const stored = localStorage.getItem(options.storageKey ?? THEME_STORAGE_KEY);
+        return stored && ids.includes(stored) ? stored : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}