@charcuterie/ui 4.23.0 → 4.25.0

package/src/GroupedList/GroupedList.mdx

@@ -7,7 +7,9 @@ import * as GroupedListStories from "./GroupedList.stories";
 # GroupedList
 
 An always-open list whose rows sit under group headings. Each row is a label, an optional
-muted description, optional badges, optional richer content, and optional trailing actions.
+muted description, optional badges, optional richer content, an optional figure beside the
+text, and optional trailing actions. A row can also be the target itself, muted, or
+highlighted.
 
 Three apps drew this shape by hand: castkit's page picker (pages under the screen that shows
 them), tally-marks' cards (cards under the team that earns them) and whereabouts' nested
@@ -56,6 +58,73 @@ There is no container query and no media query: the content decides.
 
 <Canvas of={GroupedListStories.Responsive} />
 
+## Sticky headings
+
+`isHeadingSticky` pins each group's heading to the top of the nearest scrolling ancestor while
+that group's rows scroll under it, and the next group's heading pushes it away. Use it for a
+list inside a scrolling pane, where the heading is the only thing that says which screen or
+team a row belongs to once the row scrolls out of sight. It is off by default.
+
+A stuck heading needs an opaque background, or the rows show through it. The component cannot
+know which surface it sits on — a page is `surface-base`, a settings pane is
+`surface-raised` — so the host says so with a custom property:
+
+| Property | Default | Set it to |
+| --- | --- | --- |
+| `--charcuterie-grouped-list-heading-surface` | `var(--color-surface-base)` | The background of the pane the list sits on. |
+| `--charcuterie-grouped-list-heading-offset` | `0px` | The height of anything already stuck to the top of the same scroll container, such as a sticky `Header`. |
+
+Set either one on any ancestor of the list. The names are exported as
+`GROUPED_LIST_HEADING_SURFACE_PROPERTY` and `GROUPED_LIST_HEADING_OFFSET_PROPERTY` for a host
+that sets them through a `style` object.
+
+```css
+.settings-panel {
+  --charcuterie-grouped-list-heading-surface: var(--color-surface-raised);
+}
+```
+
+<Canvas of={GroupedListStories.StickyHeadings} />
+
+## A row can be the target
+
+Give an item `onSelect` and the whole row becomes one native `<button>` — "open this card"
+for a list whose primary action is the row itself. `selectLabel` names it (it defaults to
+`label`); name the verb, as with any repeated action: `selectLabel="Edit Water the ferns"`.
+
+- **Every state is drawn.** Hover tints the row and rings its edge (only on devices that
+  hover, so a tap does not leave a row lit). A press sinks the row slightly, with motion only
+  when the user has not asked the OS for less. Keyboard focus draws the focus ring inside the
+  row's edge, where the list's rounded corners cannot clip it, and one ring-width in from it,
+  so a highlighted row that has focus shows both rings.
+- **The actions stay their own targets.** The button is drawn under the row's text and the
+  text lets the pointer through to it; `actions` sit above it. Pressing "Delete" never opens
+  the row, and Tab reaches the row, then its actions, then the next row.
+- **Nothing is nested in the button.** It is empty and named by `aria-label`, so `badges`,
+  `content` and `aside` must not hold controls — a control belongs in `actions`.
+
+`aside` is a figure that belongs **beside** the text — a payout, a total. It asks for at
+least 11rem next to the text column's 12rem, so it sits between the text and the actions in a
+wide list and drops under the text in a narrow one.
+
+<Canvas of={GroupedListStories.SelectableRows} />
+
+## Muted and highlighted rows
+
+- `isMuted` recedes a row that exists but is switched off: a sunken surface and a quieter
+  label. It stays fully operable, and it is a surface and a text role rather than an opacity,
+  because a faded row would drop below the AA contrast floor and only a disabled control may.
+  Say why in a badge as well ("off").
+- `isHighlighted` rings the row and pulses the ring twice — "this one just changed", after a
+  scan or a save. `highlightIntent` picks the colour (`accent` by default). The ring stays
+  while the flag does, so the app decides how long it lasts, usually with a timer. **To pulse
+  an already-highlighted row again, change its `key`**: a new key is a new row, and a new row
+  starts the pulse from the beginning. Under `prefers-reduced-motion` and on ePaper the ring
+  does not pulse; it is simply there. The pulse lives in `@charcuterie/ui/styles.css`, which
+  every app already imports.
+
+<Canvas of={GroupedListStories.RowStates} />
+
 ## Name a repeated action after its row
 
 Ten rows of "Open" are ten buttons an agent cannot tell apart. Give each one a name that

package/src/GroupedList/GroupedList.stories.tsx

@@ -1,5 +1,6 @@
 import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
+import { type CSSProperties, useState } from "react"
 
 import { Badge } from "../Badge/Badge.tsx"
 import { Button } from "../Button/Button.tsx"
@@ -9,8 +10,13 @@ import {
   StoryGrid,
 } from "../board.storyHelpers.tsx"
 import { EmptyState } from "../EmptyState/EmptyState.tsx"
-import type { GroupedListGroup } from "./GroupedList.tsx"
+import { ValuePairs } from "../ValuePairs/ValuePairs.tsx"
+import type {
+  GroupedListGroup,
+  GroupedListItem,
+} from "./GroupedList.tsx"
 import { GroupedList } from "./GroupedList.tsx"
+import { GROUPED_LIST_HEADING_SURFACE_PROPERTY } from "./groupedListStickyHeading.ts"
 
 /**
  * Fixture data only. A signage app's pages, grouped by the screen
@@ -181,6 +187,142 @@ const CHORE_GROUPS: GroupedListGroup[] = [
   },
 ]
 
+/**
+ * Fixture data only. A chore card whose whole row opens its editor:
+ * the shape tally-marks' Rows view draws, with the payout beside the
+ * text and the daily cap under it.
+ */
+type ChoreCard = {
+  isActive: boolean
+  isHighlighted?: boolean
+  key: string
+  label: string
+  maxPerDay: number
+  points: number
+}
+
+const CHORE_CARDS: ChoreCard[] = [
+  {
+    isActive: true,
+    key: "water-ferns",
+    label: "Water the ferns",
+    maxPerDay: 5,
+    points: 5,
+  },
+  {
+    isActive: true,
+    isHighlighted: true,
+    key: "sort-recycling",
+    label: "Sort the recycling",
+    maxPerDay: 6,
+    points: 2,
+  },
+  {
+    isActive: false,
+    key: "feed-goldfish",
+    label: "Feed the goldfish",
+    maxPerDay: 2,
+    points: 2,
+  },
+]
+
+/**
+ * One chore card as a row. `onSelect` opens it; the action beside it
+ * is a separate target. A switched-off card is muted and says so in
+ * a badge.
+ */
+const toChoreRow = (
+  card: ChoreCard,
+  {
+    onDelete,
+    onSelect,
+  }: {
+    onDelete?: (label: string) => void
+    onSelect?: (label: string) => void
+  } = {},
+): GroupedListItem => ({
+  actions: (
+    <Button
+      appearance="ghost"
+      aria-label={`Delete ${card.label}`}
+      intent="danger"
+      onClick={() => {
+        onDelete?.(card.label)
+      }}
+      size="sm"
+    >
+      Delete
+    </Button>
+  ),
+  aside: (
+    <ValuePairs
+      items={[
+        {
+          id: "scan",
+          label: "Per scan",
+          value: `${card.points} pts`,
+        },
+      ]}
+      label="Payout"
+    />
+  ),
+  badges: card.isActive ? undefined : (
+    <Badge appearance="soft" size="sm">
+      off
+    </Badge>
+  ),
+  content: `Up to ${card.maxPerDay} pts a day`,
+  description: card.key,
+  highlightIntent: "success",
+  isHighlighted: card.isHighlighted,
+  isMuted: !card.isActive,
+  key: card.key,
+  label: card.label,
+  onSelect: () => {
+    onSelect?.(card.label)
+  },
+  selectLabel: `Edit ${card.label}`,
+})
+
+const toChoreGroups = (
+  handlers?: Parameters<typeof toChoreRow>[1],
+): GroupedListGroup[] => [
+  {
+    heading: "Team Orion",
+    items: CHORE_CARDS.map((card) =>
+      toChoreRow(card, handlers),
+    ),
+    key: "orion",
+    summary: "3 cards · up to 11 pts a day",
+  },
+]
+
+/**
+ * Fixture data only. The same plain row in each highlight intent.
+ */
+const HIGHLIGHT_INTENT_GROUPS: GroupedListGroup[] = [
+  {
+    heading: "Highlight intents",
+    items: (
+      [
+        "accent",
+        "success",
+        "info",
+        "warning",
+        "danger",
+        "neutral",
+      ] as const
+    ).map((intent) => ({
+      description: `highlightIntent="${intent}"`,
+      highlightIntent: intent,
+      isHighlighted: true,
+      key: intent,
+      label: `Highlighted ${intent}`,
+    })),
+    key: "intents",
+  },
+]
+
 const LONG_GROUPS: GroupedListGroup[] = [
   {
     heading:
@@ -220,6 +362,45 @@ const LONG_GROUPS: GroupedListGroup[] = [
   },
 ]
 
+/**
+ * Fixture data only. Enough screens that the pane has to scroll, so
+ * a stuck heading has rows to sit over.
+ */
+const MANY_SCREEN_GROUPS: GroupedListGroup[] = [
+  "Lobby",
+  "Break Room",
+  "Loading Dock",
+].map((screen) => ({
+  heading: `On the ${screen} screen`,
+  items: ["Welcome", "Weather", "Schedule", "Menu"].map(
+    (view) => ({
+      actions: openButton(`${view} on ${screen}`),
+      description: `/views/${view.toLowerCase()}`,
+      key: view,
+      label: view,
+    }),
+  ),
+  key: screen,
+}))
+
+/**
+ * A fixed block size is what makes the pane scroll; the heading
+ * sticks to the pane, the nearest scrolling ancestor.
+ */
+const SCROLL_PANE_STYLE: CSSProperties = {
+  blockSize: "16rem",
+}
+
+/**
+ * The host says which surface the list sits on. The pane is raised,
+ * so the stuck heading is raised too.
+ */
+const RAISED_PANE_STYLE = {
+  ...SCROLL_PANE_STYLE,
+  [GROUPED_LIST_HEADING_SURFACE_PROPERTY]:
+    "var(--color-surface-raised)",
+} as CSSProperties
+
 /**
  * A cap rather than a width, so the long label clips in every window
  * — an ultrawide grid cell would otherwise hold it whole and the
@@ -436,6 +617,163 @@ export const NarrowView: Story = {
   globals: { viewport: { value: "mobile1" } },
 }
 
+/**
+ * `isHeadingSticky` pins each heading to the top of the scrolling
+ * pane while its rows scroll under it. On the left the pane is the
+ * page surface, which is the default heading background. On the
+ * right the pane is raised, and it sets
+ * `--charcuterie-grouped-list-heading-surface` to match.
+ */
+export const StickyHeadings: Story = {
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell
+        align="stretch"
+        label="default: surface-base"
+      >
+        <section
+          aria-label="Pages on a base surface"
+          className="overflow-y-auto rounded-lg border border-border-subtle bg-surface-base px-3"
+          style={SCROLL_PANE_STYLE}
+        >
+          <GroupedList
+            groups={MANY_SCREEN_GROUPS}
+            isHeadingSticky
+            size="sm"
+          />
+        </section>
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="host sets the surface: surface-raised"
+      >
+        <section
+          aria-label="Pages on a raised surface"
+          className="overflow-y-auto rounded-lg border border-border-subtle bg-surface-raised px-3"
+          style={RAISED_PANE_STYLE}
+        >
+          <GroupedList
+            groups={MANY_SCREEN_GROUPS}
+            isHeadingSticky
+            size="sm"
+          />
+        </section>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * A row whose whole surface is its primary action. `onSelect` draws
+ * one native button under the row's text, named by `selectLabel`;
+ * the Delete action sits above it as its own target. The status
+ * line under the list says which one a click reached.
+ *
+ * The second card is highlighted (a scan just paid it), and the
+ * third is switched off, so it is muted.
+ */
+export const SelectableRows: Story = {
+  render: function SelectableRowsStory() {
+    const [lastEvent, setLastEvent] = useState(
+      "Nothing chosen yet",
+    )
+
+    return (
+      <div className="flex flex-col gap-3">
+        <GroupedList
+          groups={toChoreGroups({
+            onDelete: (label) => {
+              setLastEvent(`Deleted ${label}`)
+            },
+            onSelect: (label) => {
+              setLastEvent(`Opened ${label}`)
+            },
+          })}
+        />
+
+        <p
+          className="m-0 text-content-secondary text-sm"
+          role="status"
+        >
+          {lastEvent}
+        </p>
+      </div>
+    )
+  },
+}
+
+/**
+ * Every per-row state at once: hover, press and keyboard focus on
+ * the whole-row button (forced by the pseudo-states addon, the only
+ * way to review them in a static board), a muted row, and a
+ * highlight in each intent. The highlight's pulse is frozen here, so
+ * this is also its static, reduced-motion look.
+ */
+export const RowStates: Story = {
+  parameters: {
+    pseudo: {
+      active: ["#active-row li:first-child > button"],
+      focusVisible: ["#focus-row li:first-child > button"],
+      hover: ["#hover-row li:first-child > button"],
+    },
+  },
+  render: () => (
+    <StoryGrid columns={2}>
+      {(
+        [
+          ["resting", "resting-row"],
+          ["hover (forced)", "hover-row"],
+          ["active (forced)", "active-row"],
+          ["focus-visible (forced)", "focus-row"],
+        ] as const
+      ).map(([label, id]) => (
+        <StoryCell align="stretch" key={id} label={label}>
+          <div id={id}>
+            <GroupedList
+              groups={[
+                {
+                  heading: `Team Orion, ${label}`,
+                  items: CHORE_CARDS.slice(0, 1).map(
+                    (card) => toChoreRow(card),
+                  ),
+                  key: id,
+                },
+              ]}
+              size="sm"
+            />
+          </div>
+        </StoryCell>
+      ))}
+
+      <StoryCell align="stretch" label="isMuted">
+        <GroupedList
+          groups={[
+            {
+              heading: "Switched off",
+              items: [
+                toChoreRow(CHORE_CARDS[2] as ChoreCard),
+              ],
+              key: "muted",
+            },
+          ]}
+          size="sm"
+        />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="isHighlighted, each highlightIntent"
+      >
+        <GroupedList
+          groups={HIGHLIGHT_INTENT_GROUPS}
+          size="sm"
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
 /**
  * Light and dark side by side, each panel scoped with its own
  * `data-scheme`, so both read at once whatever the toolbar says.