@charcuterie/ui 3.34.0 → 4.1.0

package/src/Main/scrollMemory.ts

@@ -1,73 +1,131 @@
 /**
- * What the browser will not remember for you.
+ * What the browser will not remember for you, and the one thing it
+ * would never have got wrong.
  *
- * `Shell` gives `<main>` the page's only vertical scrollport, so
- * the header and the rails stay put while the content moves —
- * that is the whole reason `Shell.test.tsx` asserts "only main
- * scrolls vertically, keeping the rail available".
- *
- * It costs exactly one thing, and this module is it. A browser
- * remembers **the document scroller's** offset per history entry
- * and puts it back on Back. It does that for a cross-document
- * load, and `history.scrollRestoration` is the switch for it. It
- * does **not** do it for an arbitrary element with
- * `overflow-y: auto`, and it does not do it at all for a
- * same-document `pushState` navigation, which is every link press
- * in a single-page app. So a page that scrolls its own `<main>`
- * loses the reader's place on Back, and no browser setting brings
- * it back:
+ * `Shell` gives `<main>` the page's only vertical scrollport, so the
+ * header and the rails stay put while the content moves — that is
+ * what `Shell.test.tsx` asserts. It costs exactly one thing, and
+ * this module is it. A browser remembers **the document scroller's**
+ * offset per history entry and puts it back on Back. It does not do
+ * that for an arbitrary element with `overflow-y: auto`, and it does
+ * not do it at all for a same-document `pushState` navigation, which
+ * is every link press in a single-page app:
  *
  * > *"If I scroll, click on an item, then go back, it resets me to
  * > the top. […] It should remember where the scroll position was
  * > previously. Isn't this handled by Chrome already?"*
  *
- * The offsets are held **in memory**, not in `sessionStorage`. A
- * history key survives a reload, but the DOM it described does
- * not: the app re-fetches, re-measures and often re-orders, so a
- * pixel offset from before the reload points at a different row.
- * Restoring a stale number is worse than restoring nothing,
- * because it looks deliberate.
+ * ## An entry remembers its PATH as well as its offset
+ *
+ * Not decoration — the second field is what keeps this from being a
+ * worse bug than the one it fixes. A history entry is not a page. A
+ * filter chip, an expanded group, a selected tab: each writes a
+ * search param, and **`setSearchParams` navigates**, so each mints a
+ * history entry the memory has never seen. Treating an unseen entry
+ * as "start at the top" therefore threw the reader to the top of the
+ * list every time they opened a group — which is exactly what
+ * shipped, and what the path comparison exists to prevent.
+ *
+ * So the rule is about the PAGE, not the entry:
+ *
+ *  - **An entry we have seen** → its remembered offset. This is the
+ *    whole feature: Back and Forward land where you left them.
+ *  - **A new entry on the SAME path** → leave the scrollport alone.
+ *    A search param changed; the reader did not go anywhere. This is
+ *    also precisely what the app did before this memory existed, so
+ *    it can never be a regression.
+ *  - **A new entry on a DIFFERENT path** → the top. A page you have
+ *    not seen starts at its beginning, which is what a browser does
+ *    for a document.
+ *
+ * ## The offsets are in memory, never `sessionStorage`
+ *
+ * A history key survives a reload; the DOM it described does not.
+ * The app re-fetches, re-measures and often re-orders, so a pixel
+ * offset from before the reload points at a different row. Restoring
+ * a stale number is worse than restoring nothing, because it looks
+ * deliberate.
  */
 
 /**
  * How many history entries keep an offset. A reader goes back
  * through a handful of screens, never fifty, so this is a ceiling
  * against a long session rather than a working set — the map holds
- * one small number per entry and evicts the least recently
- * written.
+ * one small record per entry and evicts the least recently written.
  */
 const REMEMBERED_ENTRY_LIMIT = 50
 
-const rememberedOffsets = new Map<string, number>()
+export type ScrollEntry = {
+  /** The history entry — react-router's `useLocation().key`. */
+  key: string
+  /** The page it belongs to — `useLocation().pathname`. */
+  path: string
+}
+
+type RememberedEntry = {
+  offset: number
+  path: string
+}
+
+const rememberedEntries = new Map<string, RememberedEntry>()
+
+/**
+ * The entry the scrollport is showing. Module state rather than a
+ * ref, because the question it answers — *did the reader change page
+ * or only a search param?* — is asked by the incoming entry's effect
+ * about the OUTGOING one, and by then the outgoing effect has
+ * already been cleaned up.
+ */
+let currentEntry: ScrollEntry | null = null
 
 export const rememberScrollOffset = (
-  key: string,
+  entry: ScrollEntry,
   offset: number,
 ) => {
-  // Delete before set, so insertion order is least-recent-first
-  // and the eviction below takes the right one. A plain `set` on
-  // an existing key keeps its original position.
-  rememberedOffsets.delete(key)
-  rememberedOffsets.set(key, offset)
+  // Delete before set, so insertion order is least-recent-first and
+  // the eviction below takes the right one. A plain `set` on an
+  // existing key keeps its original position.
+  rememberedEntries.delete(entry.key)
+  rememberedEntries.set(entry.key, {
+    offset,
+    path: entry.path,
+  })
 
-  for (const oldestKey of rememberedOffsets.keys()) {
-    if (rememberedOffsets.size <= REMEMBERED_ENTRY_LIMIT) {
+  for (const oldestKey of rememberedEntries.keys()) {
+    if (rememberedEntries.size <= REMEMBERED_ENTRY_LIMIT) {
       break
     }
 
-    rememberedOffsets.delete(oldestKey)
+    rememberedEntries.delete(oldestKey)
   }
 }
 
 /**
- * `0` for an entry nobody has scrolled, which is also the right
- * answer for an entry nobody has *seen* — a link press lands at
- * the top of the new page.
+ * Where the scrollport should go for this entry, or `null` for
+ * **leave it alone** — which is a third answer rather than a missing
+ * one, and the difference between a search param and a page.
  */
-export const recallScrollOffset = (key: string) =>
-  rememberedOffsets.get(key) ?? 0
+export const resolveScrollOffset = (entry: ScrollEntry) => {
+  const remembered = rememberedEntries.get(entry.key)
+
+  if (remembered) {
+    return remembered.offset
+  }
+
+  const isSamePage =
+    currentEntry !== null &&
+    currentEntry.path === entry.path
+
+  return isSamePage ? null : 0
+}
+
+/** Called by the hook once it owns the scrollport for this entry. */
+export const enterScrollEntry = (entry: ScrollEntry) => {
+  currentEntry = entry
+}
 
 /** Test-only. Module state outlives a mount; a test must not. */
 export const forgetScrollOffsets = () => {
-  rememberedOffsets.clear()
+  rememberedEntries.clear()
+  currentEntry = null
 }

package/src/Main/scrollMemoryContext.ts

@@ -0,0 +1,21 @@
+import { createContext } from "react"
+
+import type { ScrollEntry } from "./scrollMemory.ts"
+
+/**
+ * How the history entry reaches `Main` without `Main` knowing a
+ * router exists.
+ *
+ * `@charcuterie/ui`'s main entry is router-free and stays that way —
+ * `sourceRules.test.ts` asserts it, and the fleet runs five
+ * different routers. So the entry arrives as a plain
+ * `{ key, path }`, and the one component that knows how to read it
+ * from react-router lives in the `./react-router` subpath.
+ *
+ * A context rather than a prop, because the alternative is a prop
+ * every app has to remember on every `Main` it renders. It was a
+ * prop first, exactly once, and three of the four apps that needed
+ * it did not have it.
+ */
+export const ScrollMemoryContext =
+  createContext<ScrollEntry | null>(null)

package/src/Main/useScrollMemory.ts

@@ -1,8 +1,10 @@
 import { useCallback, useLayoutEffect, useRef } from "react"
 
 import {
-  recallScrollOffset,
+  enterScrollEntry,
   rememberScrollOffset,
+  resolveScrollOffset,
+  type ScrollEntry,
 } from "./scrollMemory.ts"
 
 /**
@@ -11,11 +13,11 @@ import {
  *
  * The offset cannot be applied until the scrollport is tall enough
  * to hold it, and on a client-rendered page it is not: the commit
- * that changes the route draws a skeleton, and the rows land a
- * fetch later. So the restore re-applies as the content grows, and
- * gives up after this. A page that takes longer than three seconds
- * to fill has already been read from the top, and moving it then
- * is a worse answer than leaving it where the reader put it.
+ * that changes the route draws a skeleton, and the rows land a fetch
+ * later. So the restore re-applies as the content grows, and gives
+ * up after this. A page that takes longer than three seconds to fill
+ * has already been read from the top, and moving it then is a worse
+ * answer than leaving it where the reader put it.
  */
 const RESTORE_WINDOW_MS = 3000
 
@@ -28,41 +30,42 @@ const READER_INTENT_EVENTS = [
 ] as const
 
 /**
- * Remember where this history entry was scrolled to, and put it
- * back when the reader returns to it.
+ * Remember where this history entry was scrolled to, and put it back
+ * when the reader returns to it.
  *
- * `scrollMemory.ts` says why the browser will not. This is the
- * part that has to survive the two things a real page does:
+ * `scrollMemory.ts` says why the browser will not, and what an entry
+ * that has never been seen should do. This is the part that has to
+ * survive the two things a real page does:
  *
  *  1. **The content arrives late.** An offset applied against a
- *     600px skeleton clamps to `0` and looks like it did nothing.
- *     A `ResizeObserver` on the scrollport and on its content
- *     column re-applies the offset every time either grows, until
- *     the offset lands or the window closes.
- *  2. **The reader scrolls during all that.** Any wheel, touch,
- *     key or pointer press ends the restore immediately. The
- *     alternative is a page that jumps out from under somebody who
- *     has already started reading.
+ *     600px skeleton clamps to `0` and looks like it did nothing. A
+ *     `ResizeObserver` on the scrollport and on its content column
+ *     re-applies the offset every time either grows, until the
+ *     offset lands or the window closes.
+ *  2. **The reader scrolls during all that.** Any wheel, touch, key
+ *     or pointer press ends the restore immediately. The alternative
+ *     is a page that jumps out from under somebody who has already
+ *     started reading.
  *
  * The save is a passive `scroll` listener, suppressed while a
  * restore is in flight. Without that suppression the feature eats
  * itself: writing `scrollTop` on a still-short page clamps to `0`
- * and fires a `scroll` event reading `0`, which would be saved
- * over the very offset being restored.
+ * and fires a `scroll` event reading `0`, which would be saved over
+ * the very offset being restored.
  *
- * @param scrollKey Identifies the history entry — react-router's
- *   `useLocation().key`. `undefined` turns the memory off, which is
- *   what an app with no router gets.
+ * @param entry The history entry and the page it belongs to.
+ *   `null` turns the memory off, which is what an app that renders
+ *   no `ScrollMemoryProvider` gets.
  */
 export const useScrollMemory = (
-  scrollKey: string | undefined,
+  entry: ScrollEntry | null | undefined,
 ) => {
   const elementRef = useRef<HTMLElement | null>(null)
   const isRestoringRef = useRef(false)
 
-  // A ref rather than a query for the `<main>` id: the effect
-  // below runs in the same commit that mounts the node, and only a
-  // ref can say which node that was.
+  // A ref rather than a query for the `<main>` id: the effect below
+  // runs in the same commit that mounts the node, and only a ref can
+  // say which node that was.
   //
   // `unknown` in, narrowed here, so the returned function is both a
   // `RefCallback<HTMLElement>` and something `mergeRefs` accepts —
@@ -73,18 +76,43 @@ export const useScrollMemory = (
       node instanceof HTMLElement ? node : null
   }, [])
 
+  const key = entry?.key
+  const path = entry?.path
+
   useLayoutEffect(() => {
     const element = elementRef.current
 
-    if (!element || scrollKey === undefined) {
+    if (
+      !element ||
+      key === undefined ||
+      path === undefined
+    ) {
       return undefined
     }
 
-    const offset = recallScrollOffset(scrollKey)
-
-    // The arrow defers the read of `applyOffset`, so the three
-    // pieces can be declared in the order they depend on each
-    // other rather than in the order they are used.
+    const currentEntry = { key, path }
+
+    // `null` means leave the scrollport alone: a search param
+    // changed and the reader did not go anywhere. It is read BEFORE
+    // this entry becomes the current one, because the answer depends
+    // on the page the reader is arriving from.
+    const offset = resolveScrollOffset(currentEntry)
+
+    enterScrollEntry(currentEntry)
+
+    // Seed the entry now rather than waiting for a `scroll` event.
+    // A reader who opens a group and then follows a link never
+    // scrolls in between, so without this the entry they came from
+    // is one the memory has never seen — and Back would send them to
+    // the top of a list they were half-way down.
+    rememberScrollOffset(
+      currentEntry,
+      offset ?? element.scrollTop,
+    )
+
+    // The arrow defers the read of `applyOffset`, so the pieces can
+    // be declared in the order they depend on each other rather than
+    // in the order they are used.
     const observer = new ResizeObserver(() => {
       applyOffset()
     })
@@ -93,12 +121,9 @@ export const useScrollMemory = (
       stopRestoring()
     }, RESTORE_WINDOW_MS)
 
-    const stopRestoring = () => {
-      if (!isRestoringRef.current) {
-        return
-      }
+    let isRestoring = offset !== null
 
-      isRestoringRef.current = false
+    const teardown = () => {
       observer.disconnect()
       globalThis.clearTimeout(deadline)
 
@@ -110,8 +135,18 @@ export const useScrollMemory = (
       }
     }
 
+    const stopRestoring = () => {
+      if (!isRestoring) {
+        return
+      }
+
+      isRestoring = false
+      isRestoringRef.current = false
+      teardown()
+    }
+
     const applyOffset = () => {
-      if (!isRestoringRef.current) {
+      if (!isRestoring || offset === null) {
         return
       }
 
@@ -128,10 +163,10 @@ export const useScrollMemory = (
         return
       }
 
-      rememberScrollOffset(scrollKey, element.scrollTop)
+      rememberScrollOffset(currentEntry, element.scrollTop)
     }
 
-    isRestoringRef.current = true
+    isRestoringRef.current = isRestoring
 
     for (const eventName of READER_INTENT_EVENTS) {
       element.addEventListener(eventName, stopRestoring, {
@@ -155,10 +190,15 @@ export const useScrollMemory = (
     applyOffset()
 
     return () => {
-      stopRestoring()
+      // Unconditional, unlike `stopRestoring` — a restore that
+      // already landed still has an observer and four listeners on
+      // an element the next entry is about to use, and a stale
+      // observer that survives its effect applies a stale offset.
+      isRestoring = false
+      teardown()
       element.removeEventListener("scroll", onScroll)
     }
-  }, [scrollKey])
+  }, [key, path])
 
   return setElement
 }

package/src/PortraitTiles/PortraitAvatar.tsx

@@ -0,0 +1,49 @@
+import type { ReactNode } from "react"
+import { useState } from "react"
+
+/**
+ * The face, and the one piece of this component that holds state.
+ *
+ * A portrait grid is the shape that cannot absorb a broken image:
+ * a missing `<img>` is a torn hole where a person's face was, next
+ * to nine that rendered. `onError` is the only signal a browser
+ * gives for a 404, a wrong content type, or a file the user's
+ * network stripped — so the fallback the caller already supplied for
+ * "no picture" covers "no picture *today*" as well.
+ *
+ * Its own component because the state is per portrait. Hoisting it
+ * to a `Record<string, boolean>` in the set would re-render every
+ * tile whenever any one image failed.
+ */
+export const PortraitAvatar = ({
+  className,
+  imageSrc,
+  initials,
+}: {
+  className: string
+  imageSrc: string | undefined
+  initials: ReactNode
+}): ReactNode => {
+  const [isImageBroken, setIsImageBroken] = useState(false)
+
+  if (imageSrc === undefined || isImageBroken) {
+    return (
+      <span aria-hidden className={className}>
+        {initials}
+      </span>
+    )
+  }
+
+  return (
+    <img
+      // The name is beside it, inside the same tile, so an alt here
+      // is the name announced twice.
+      alt=""
+      className={className}
+      onError={() => {
+        setIsImageBroken(true)
+      }}
+      src={imageSrc}
+    />
+  )
+}

package/src/PortraitTiles/PortraitTiles.mdx

@@ -0,0 +1,153 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as PortraitTilesStories from "./PortraitTiles.stories";
+
+<Meta of={PortraitTilesStories} />
+
+# PortraitTiles
+
+A set of **people** — or of anything else picked by its face — drawn as round pictures with a
+name and one big number.
+
+points-market's "Who's shopping?" is the shape this is taken from. It had been hand-rolled
+there since the app was built, and it is the third tile shape the fleet grew on its own,
+after mux-magic's and Gallery Downloader's "Pick a tool" cards.
+
+<Canvas of={PortraitTilesStories.Default} />
+
+## Props
+
+<Controls />
+
+## Why this is not an `ActionTiles` variant
+
+The two answer different questions.
+
+- [`ActionTiles`](/docs/components-actions-actiontiles--docs) asks **what do you want to
+  do** — a name, a line of help, an icon that illustrates a verb.
+- This asks **who is this** — a face, and one number that decides it. There is no
+  description, because a person is not explained.
+
+Collapsing them would mean one component whose `icon` is sometimes a 20px glyph beside the
+title and sometimes a 144px circle above it, with `hint` meaning "what this does" in one mode
+and "points" in the other. That is two components wearing one name.
+
+What they **do** share is the box: `tileStyles.ts` holds the border, the radius, the surface
+and the `auto-fill` grid, and both read it. A page carrying both does not show two different
+cards.
+
+## It scales, and the scaling is the point
+
+Two axes carry it, and neither is a pixel count in an app.
+
+**The container.** `layout="auto"` is a row while the set is narrow and a column once it has
+room, off a `cq-sm` (24rem) query on the set itself. Nothing reads the viewport, so a picker
+in a 320px sidebar on a 2560px monitor gets the row form — which is right, and which a media
+query would have got wrong.
+
+**The density.** Every length is a token, so `data-density="kiosk"` grows the type ramp
+underneath it: `text-2xl` is 30px at `comfortable` and 38px at `kiosk`. points-market runs
+`kiosk` today, and that is where its big numbers come from.
+
+<Canvas of={PortraitTilesStories.Responsive} />
+
+The container and the element querying it **cannot be the same box** — a container query
+matches descendants only. The set renders a wrapper for that reason, the same arrangement
+`EmptyState` uses, and `className` stays on the outer element where a consumer expects it.
+
+<Canvas of={PortraitTilesStories.AllVariants} />
+
+## The colour is the person's, not the position's
+
+A portrait takes the next hue from the ten-wide
+[categorical palette](/docs/foundations-colour--docs) when it names none, which costs a call
+site nothing and is the right default for a list assembled on the fly.
+
+It is the **wrong** default for a household. Add a fifth member and the first four change
+colour — and their colour was the thing the picker was being read by, faster than the names
+were. Any set whose subjects persist should store a `categorical` per subject and pass it,
+the same call Docket makes for a project.
+
+`categorical` and not `intent`: an intent is a claim the design system makes — `danger` says
+what happens if you press the thing — and a person is not a warning.
+
+<Canvas of={PortraitTilesStories.NamedHues} />
+
+### When the colour is not ours to choose
+
+Some colours are not a design decision at all. points-market colours each child to match the
+**NFC card they physically tap**, by a settled household decision, so the picker on the wall
+and the card in their hand have to agree. Ten audited hues cannot promise that, and
+re-theming the colour would be re-theming the card.
+
+That is what `color` is for, and it is the same line
+[`Swatch`](/docs/components-data-swatch--docs) draws: a colour that arrived from the world is
+data, not a token. It reaches the paint through custom properties on the tile, because
+Tailwind generates its CSS at build time from source text and a colour out of a database is
+not in the source.
+
+Three things happen to that one colour, and only the first uses it raw.
+
+- The **fill** is the colour, exactly.
+- The **initials** are black or white, whichever the fill can carry — which is why the third
+  portrait below has white letters and the other two have black. Pass six-digit hex:
+  `getReadableTextColour` measures hex and nothing else, and falls back to white on anything
+  it cannot parse rather than throwing inside your render.
+- The **number** is the colour mixed toward the scheme's own text colour, so a pale card
+  colour is still readable on a pale surface — and, in the dark scheme, is pulled the other
+  way instead.
+
+Reach for this arm only when the colour is a **fact about the subject**. A colour that is
+merely a choice is `categorical`, and it gets re-theming and a contrast guarantee for free.
+
+<Canvas of={PortraitTilesStories.DataColours} />
+
+## A picture, and what happens when it 404s
+
+`imageSrc` draws a photo; `initials` draws a letter on the hue's solid fill. A portrait grid
+is the shape that cannot absorb a broken image — a missing `<img>` is a torn hole where a
+face was, next to three that loaded — so a load error falls back to the initials the caller
+already supplied.
+
+The `<img>` is `alt=""` on purpose. The name is beside it inside the same tile, so an alt
+here is the name announced twice.
+
+<Canvas of={PortraitTilesStories.WithPictures} />
+
+## The keyboard is the platform's
+
+`href` makes a portrait a real `<a href>`, routed through the injected `RouterLink` for a
+same-origin destination — so middle-click, ctrl-click, "open in a new tab" and "copy link
+address" come from the element rather than from the paint. Without one it is a `<button>`
+that calls `onChoose`. A set may mix the two.
+
+Tab reaches **each** portrait. There is no roving tabindex, for the same reason `ActionTiles`
+has none: a radio group borrows one tab stop because exactly one of its options is true at a
+time, and nothing here is true.
+
+The group takes a required `label` naming the set — "Who's shopping?" — and `stat` is drawn
+inside the tile with its `hint` so both are part of the accessible name. "1,240" on its own
+tells a screen-reader user nothing.
+
+<Canvas of={PortraitTilesStories.AllStates} />
+
+## The lift, and who does not get it
+
+Hovering raises the portrait and casts a shadow. It is the one piece of motion in this
+library, kept because it is the thing the owner pointed at in points-market when this moved
+in here.
+
+`motion-reduce:hover:translate-y-0` turns the movement off for anyone who has asked the OS
+for less. The shadow and the coloured border stay, so the hover is still legible without it.
+
+<Canvas of={PortraitTilesStories.Interactive} />
+
+## What this deliberately does not do
+
+- **Hold a selection.** Nothing here is checked; the page moved on. A picker that keeps a
+  value is `RadioGroup itemShape="tile"`.
+- **Guarantee contrast on a `color` you supply.** The palette arm is audited in both schemes;
+  the data arm cannot be, because the colour is not ours. The initials are picked to suit the
+  fill and the number is pulled toward readable, and that is the whole of what it can promise.
+- **Crop or focus a face.** `object-fit: cover` centres, and that is all. An app that needs a
+  focal point owns the crop.