@charcuterie/ui 4.23.0 → 4.25.0

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/GroupedList/groupedListStickyHeading.ts

@@ -0,0 +1,24 @@
+/**
+ * The custom property a stuck heading reads its background from.
+ * Set it on any ancestor; it falls back to `--color-surface-base`.
+ */
+export const GROUPED_LIST_HEADING_SURFACE_PROPERTY =
+  "--charcuterie-grouped-list-heading-surface"
+
+/**
+ * The custom property a stuck heading reads its distance from the
+ * scroll container's top edge from. It falls back to `0px`.
+ */
+export const GROUPED_LIST_HEADING_OFFSET_PROPERTY =
+  "--charcuterie-grouped-list-heading-offset"
+
+/**
+ * Written out in full because Tailwind scans source text for whole
+ * class strings: an interpolated property name generates nothing.
+ *
+ * The heading row carries the space under it as padding rather than
+ * the group's `gap`, because a gap is transparent and the rows would
+ * show through it while the heading is stuck.
+ */
+export const STICKY_HEADING_CLASS =
+  "sticky top-[var(--charcuterie-grouped-list-heading-offset,0px)] z-[var(--layer-sticky)] bg-[color:var(--charcuterie-grouped-list-heading-surface,var(--color-surface-base))] pb-2"

package/src/index.ts

@@ -243,6 +243,10 @@ export type {
   GroupedListSize,
 } from "./GroupedList/GroupedList.tsx"
 export { GroupedList } from "./GroupedList/GroupedList.tsx"
+export {
+  GROUPED_LIST_HEADING_OFFSET_PROPERTY,
+  GROUPED_LIST_HEADING_SURFACE_PROPERTY,
+} from "./GroupedList/groupedListStickyHeading.ts"
 export type { HeaderProps } from "./Header/Header.tsx"
 export { Header } from "./Header/Header.tsx"
 export type { IconButtonProps } from "./IconButton/IconButton.tsx"

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;
   }