@charcuterie/ui 4.24.0 → 4.25.0

package/src/GroupedList/GroupedList.tsx

@@ -1,4 +1,5 @@
 import { useUniqueId } from "@charcuterie/logic"
+import type { IntentName } from "@charcuterie/tokens"
 import type { ReactNode } from "react"
 
 import { toClassName } from "../toClassName.ts"
@@ -18,24 +19,86 @@ export type GroupedListItem = {
    * **Name a repeated action after its row.** Ten rows of "Open" are
    * ten buttons an agent cannot tell apart; `aria-label="Open Lobby"`
    * on each is one `getByRole` away.
+   *
+   * In a row with `onSelect` these stay their own targets: they sit
+   * above the whole-row button, so pressing one never selects the
+   * row.
    */
   actions?: ReactNode
+  /**
+   * A figure that belongs beside the text rather than under it — a
+   * payout, a total, a schedule. It sits between the text and the
+   * actions in a wide list and drops under the text in a narrow one,
+   * the same content-decided wrap the actions use: it asks for at
+   * least 11rem beside the text column's 12rem. Never interactive:
+   * in a row with `onSelect` the whole-row button sits over it.
+   */
+  aside?: ReactNode
   /** `Badge`s, drawn after the label and wrapping onto their own line when they run out of room. */
   badges?: ReactNode
   /**
    * Anything richer than one line of help — a payout, a rule list.
    * Drawn under the description, inside the text column, and never
-   * truncated.
+   * truncated. Never interactive in a row with `onSelect`; a control
+   * belongs in `actions`.
    */
   content?: ReactNode
   /** One muted line under the label: a path, a key, a count. Truncated like the label. */
   description?: string
+  /**
+   * The intent `isHighlighted` rings the row in. `accent` by default;
+   * an app whose highlight means "this just paid out" passes
+   * `success`.
+   */
+  highlightIntent?: IntentName
+  /**
+   * `true` rings the row and pulses the ring twice — "this one just
+   * changed", for a row a scan, a save or an arrival has touched.
+   * The ring stays while the flag does, so the app decides how long
+   * it lasts, usually by clearing it on a timer.
+   *
+   * **To pulse a row that is already highlighted again, change its
+   * `key`.** A new key is a new row, and a new row starts the pulse
+   * from the beginning; `` `${id}-${sequence}` `` is the usual shape.
+   *
+   * Under `prefers-reduced-motion` and on ePaper the ring does not
+   * pulse; it is simply there.
+   */
+  isHighlighted?: boolean
+  /**
+   * `true` draws the row receded — a sunken surface and a quieter
+   * label — for an entry that exists but is switched off. It stays
+   * fully operable and every colour on it still clears AA, which is
+   * why it is a surface and a text role rather than an opacity: a
+   * faded row is not a disabled one, and only a disabled control may
+   * drop below the contrast floor. Say WHY in a badge too ("off").
+   */
+  isMuted?: boolean
   key: string
   /**
    * Plain text, because it is what the row is called — the thing a
    * search matched and the text a clipped row's tooltip repeats.
    */
   label: string
+  /**
+   * Makes the whole row one native `<button>` — "open this one" for a
+   * row whose primary action is the row itself. Hover tints the row
+   * and rings its edge, a press sinks it (with motion only when the
+   * user has not asked for less), and keyboard focus draws the focus
+   * ring inside the row's edge. `actions` stay separate targets
+   * above it.
+   *
+   * The button is drawn UNDER the row's text and the text lets the
+   * pointer through, so nothing interactive is ever nested inside a
+   * button: keep `badges`, `content` and `aside` free of controls.
+   */
+  onSelect?: () => void
+  /**
+   * The whole-row button's accessible name. Defaults to `label`.
+   * Name the verb when there is one — `"Edit Water the ferns"` —
+   * the same rule as a repeated action.
+   */
+  selectLabel?: string
 }
 
 export type GroupedListGroup = {
@@ -148,6 +211,20 @@ const HEADING_TAG: Record<
  * know that surface, so `isHeadingSticky` reads it from a custom
  * property the host can set, falling back to `surface-base`.
  *
+ * ### A row can be the target
+ *
+ * tally-marks' card list opens a card's editor from anywhere on the
+ * card, and the owner asked for that to feel like an app: hover,
+ * press, focus, touch. `onSelect` is that, as one real `<button>`
+ * stretched under the row's text — not a click handler on an
+ * `<li>`, which no keyboard reaches and no screen reader announces.
+ * The text lets the pointer through to it; the actions sit above it
+ * and keep their own targets, so "Delete" never opens the editor.
+ *
+ * A row can also be muted (switched off but still there) and
+ * highlighted (just touched by a scan or a save) — the two other
+ * per-row states the same list drew by hand.
+ *
  * ### Not collapsible
  *
  * A group you can close is `Accordion`. This is for a list that is

package/src/GroupedList/GroupedListRow.tsx

@@ -1,3 +1,4 @@
+import type { IntentName } from "@charcuterie/tokens"
 import type { ReactNode } from "react"
 
 import { useIsTextClipped } from "../Badge/useIsTextClipped.ts"
@@ -18,6 +19,50 @@ const ROW_SIZE_CLASS: Record<GroupedListSize, string> = {
   sm: "px-3 py-2",
 }
 
+/**
+ * Written out per intent, because Tailwind scans source text for
+ * whole class strings: `inset-ring-intent-${intent}-content`
+ * generates nothing. `-content` rather than `-border`, because a
+ * ring that announces "this just changed" has to clear the 3:1
+ * non-text contrast floor against the row, and a border role is
+ * tuned to sit quietly under it.
+ */
+const HIGHLIGHT_RING_CLASS: Record<IntentName, string> = {
+  accent: "inset-ring-intent-accent-content",
+  danger: "inset-ring-intent-danger-content",
+  info: "inset-ring-intent-info-content",
+  neutral: "inset-ring-intent-neutral-content",
+  success: "inset-ring-intent-success-content",
+  warning: "inset-ring-intent-warning-content",
+}
+
+/**
+ * The whole-row button. It is the bottom layer of the row: the text
+ * columns above it are `pointer-events-none`, so a click on the label
+ * lands here, and the actions above it keep their own targets.
+ *
+ * Every state is a SURFACE plus an edge, never colour alone. Hover is
+ * scoped by Tailwind's own `hover:` to devices that hover, so a tap on
+ * a phone does not leave a row lit. The focus ring is drawn INSIDE the
+ * row's edge (a negative offset) because the group's list clips its
+ * rounded corners, and an outside ring would be cut off on the first
+ * and last row. It sits one ring-width in from the edge, so it never
+ * shares pixels with the hover edge or the highlight ring, which both
+ * hug the edge — a highlighted row that has focus shows both.
+ */
+const SELECT_BUTTON_CLASS =
+  "absolute inset-0 cursor-pointer appearance-none border-0 bg-transparent p-0 transition-[background-color,box-shadow] duration-(--duration-fast) ease-standard hover:bg-intent-neutral-surface-hover hover:inset-ring hover:inset-ring-intent-accent-border active:bg-intent-neutral-surface-hover focus-visible:outline-solid focus-visible:outline-(length:--focus-ring-width) focus-visible:outline-offset-[calc(var(--focus-ring-width)*-2)] focus-visible:outline-focus-ring"
+
+/**
+ * The press. The row sinks a little while its button is held — the
+ * motion the owner asked for on tally-marks' cards — and only when the
+ * user has not asked the OS for less; the surface change on the button
+ * carries the press without it. Keyed on the row's OWN button, so
+ * holding an action does not press the row.
+ */
+const SELECTABLE_ROW_CLASS =
+  "relative transition-transform duration-(--duration-fast) ease-standard motion-safe:has-[>button:active]:scale-[0.99]"
+
 /**
  * Its own file because each row measures its own text, and a hook
  * cannot run in a loop.
@@ -27,16 +72,27 @@ const ROW_SIZE_CLASS: Record<GroupedListSize, string> = {
  * `useIsTextClipped` is `Badge`'s: an ellipsis leaves no trace in the
  * DOM, so the only way to know a label is cut off is to measure it.
  * A `title` on every row would put a tooltip on forty short names to
- * help the one long one.
+ * help the one long one. In a selectable row the text lets the
+ * pointer through, so the clipped label's tooltip moves to the button
+ * the pointer is actually over.
  *
  * ### The actions wrap; they never squeeze the text
  *
  * The row is a wrapping flex line. The text column asks for 12rem
- * and grows into the rest, so in a wide list the actions sit at the
- * inline end of the same line, and in a list narrower than the text
- * plus the actions they drop under the text instead of crushing the
- * label to an ellipsis and nothing. No container query: the wrap is
- * decided by the content itself.
+ * and grows into the rest, and the aside asks for at least 11rem, so
+ * in a wide list the aside and the actions sit at the inline end of
+ * the same line, and in a list narrower than all of them they drop
+ * under the text instead of crushing the label to an ellipsis and
+ * nothing. No container query: the wrap is decided by the content
+ * itself.
+ *
+ * ### The layers of a selectable row
+ *
+ * In tree order, and every one of them positioned, so they paint in
+ * that order with no `z-index` to keep in step: the button (bottom),
+ * the text and the aside (pointer passes through), the actions
+ * (their own targets), and the highlight ring (top, pointer passes
+ * through) — the ring is last so a hovered row cannot paint over it.
  */
 export const GroupedListRow = ({
   isTextTruncated,
@@ -52,24 +108,62 @@ export const GroupedListRow = ({
     ? "truncate"
     : "wrap-anywhere"
 
+  const {
+    highlightIntent = "accent",
+    isHighlighted = false,
+    isMuted = false,
+    onSelect,
+  } = item
+
+  const isSelectable = onSelect !== undefined
+
+  // A layer that sits above the button and must let the pointer
+  // through to it. Without a button it is an ordinary column.
+  const passThroughClass = isSelectable
+    ? "pointer-events-none relative"
+    : null
+
   return (
     <li
       className={toClassName(
         "flex flex-wrap items-center gap-x-3 gap-y-2",
         ROW_SIZE_CLASS[size],
+        isSelectable && SELECTABLE_ROW_CLASS,
+        isHighlighted && "relative",
+        isMuted && "bg-surface-sunken",
       )}
     >
-      <div className="flex min-w-0 flex-[1_1_12rem] flex-col gap-0.5">
+      {isSelectable ? (
+        <button
+          aria-label={item.selectLabel ?? item.label}
+          className={SELECT_BUTTON_CLASS}
+          onClick={onSelect}
+          title={isTextTruncated ? clippedLabel : undefined}
+          type="button"
+        />
+      ) : null}
+
+      <div
+        className={toClassName(
+          "flex min-w-0 flex-[1_1_12rem] flex-col gap-0.5",
+          passThroughClass,
+        )}
+      >
         <div className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1">
           <span
             className={toClassName(
-              "min-w-0 max-w-full font-medium text-content-primary",
+              "min-w-0 max-w-full font-medium",
+              isMuted
+                ? "text-content-secondary"
+                : "text-content-primary",
               size === "sm" ? "text-sm" : "text-md",
               overflowClass,
             )}
             ref={labelRef}
             title={
-              isTextTruncated ? clippedLabel : undefined
+              isTextTruncated && !isSelectable
+                ? clippedLabel
+                : undefined
             }
           >
             {item.label}
@@ -107,11 +201,42 @@ export const GroupedListRow = ({
         ) : null}
       </div>
 
+      {item.aside ? (
+        <div
+          className={toClassName(
+            // An 11rem floor, so a short figure does not squeeze in
+            // beside a phone-width label: it sits beside the text only
+            // when there is room for a real column, and drops under
+            // it otherwise. `min(…, 100%)` keeps the floor from
+            // overflowing a list narrower than the floor itself.
+            "flex min-w-[min(11rem,100%)] max-w-full flex-[0_1_auto] wrap-anywhere",
+            passThroughClass,
+          )}
+        >
+          {item.aside}
+        </div>
+      ) : null}
+
       {item.actions ? (
-        <div className="flex shrink-0 items-center gap-2">
+        <div
+          className={toClassName(
+            "flex shrink-0 items-center gap-2",
+            isSelectable && "relative",
+          )}
+        >
           {item.actions}
         </div>
       ) : null}
+
+      {isHighlighted ? (
+        <span
+          aria-hidden
+          className={toClassName(
+            "charcuterie-highlight pointer-events-none absolute inset-0 inset-ring-2",
+            HIGHLIGHT_RING_CLASS[highlightIntent],
+          )}
+        />
+      ) : null}
     </li>
   )
 }

package/src/styles.css

@@ -1,6 +1,7 @@
-/* `@charcuterie/ui/styles.css` — the four looping affordances and
- * the token-tinted scrollbar: the visuals a Tailwind utility cannot
- * express against our tokens, and nothing else.
+/* `@charcuterie/ui/styles.css` — the four looping affordances, the
+ * one-shot highlight pulse and the token-tinted scrollbar: the
+ * visuals a Tailwind utility cannot express against our tokens, and
+ * nothing else.
  *
  * Every other visual in this package is a Tailwind utility reading
  * a token, which is what makes a scheme/density/variant flip a
@@ -74,6 +75,36 @@
   }
 }
 
+/* The highlight pulse: "this row just changed". Two blinks, then
+ * steady. Only OPACITY moves, and the last keyframe is fully shown,
+ * so the element's own resting style IS the static fallback — under
+ * reduced motion the animation is switched off below and the ring is
+ * simply there, and on ePaper a 0ms run ends on the same frame. That
+ * is the "every moving affordance owes a static fallback" rule met
+ * by construction rather than by a second rule. */
+@keyframes charcuterie-highlight {
+  0% {
+    opacity: 0;
+  }
+
+  25% {
+    opacity: 1;
+  }
+
+  55% {
+    opacity: 0.3;
+  }
+
+  100% {
+    opacity: 1;
+  }
+}
+
+.charcuterie-highlight {
+  animation: charcuterie-highlight var(--duration-loop-slow)
+    var(--easing-standard) 2;
+}
+
 .charcuterie-spin {
   animation: charcuterie-spin var(--duration-loop-fast)
     linear infinite;
@@ -105,7 +136,8 @@
   .charcuterie-spin,
   .charcuterie-shimmer,
   .charcuterie-sweep,
-  .charcuterie-pulse {
+  .charcuterie-pulse,
+  .charcuterie-highlight {
     animation: none;
   }