@charcuterie/ui 4.24.0 → 4.26.0

package/src/CommandPalette/useCommandPaletteHotkeys.ts

@@ -0,0 +1,158 @@
+import { useLatestRef } from "@charcuterie/logic"
+import { useEffect } from "react"
+
+export type CommandPaletteHotkeysOptions = {
+  /** Off while the palette is open, or on a page that should not take the keys. Default `true`. */
+  isEnabled?: boolean
+  /**
+   * A printable key typed outside an editable field opens the palette
+   * with that character as the query. Default `true`.
+   */
+  isOpenedByTyping?: boolean
+  /** Receives the text the palette should open with: `""`, or the character typed. */
+  onOpen: (initialQuery: string) => void
+}
+
+/**
+ * Elements that keep their keys: anything you type into, and the
+ * widgets with their own type-to-find (a focused `Listbox` or `Menu`
+ * jumps to the option you type, and stealing that key breaks it).
+ */
+const TYPEAHEAD_OWNER_SELECTOR = [
+  "input",
+  "textarea",
+  "select",
+  "[contenteditable]:not([contenteditable='false'])",
+  "[role='combobox']",
+  "[role='grid']",
+  "[role='listbox']",
+  "[role='menu']",
+  "[role='menubar']",
+  "[role='searchbox']",
+  "[role='textbox']",
+  "[role='tree']",
+  "[role='treegrid']",
+].join(",")
+
+/** Input types that take no text, so a letter typed on one is free to open the palette. */
+const NON_TEXT_INPUT_TYPES = new Set([
+  "button",
+  "checkbox",
+  "color",
+  "file",
+  "image",
+  "radio",
+  "range",
+  "reset",
+  "submit",
+])
+
+export const getIsTypingTarget = (
+  target: EventTarget | null,
+): boolean => {
+  if (!(target instanceof Element)) {
+    return false
+  }
+
+  if (
+    target instanceof HTMLInputElement &&
+    NON_TEXT_INPUT_TYPES.has(target.type)
+  ) {
+    return false
+  }
+
+  return (
+    (target instanceof HTMLElement &&
+      target.isContentEditable) ||
+    target.closest(TYPEAHEAD_OWNER_SELECTOR) !== null
+  )
+}
+
+/**
+ * The global keys that open a command palette, as an opt-in hook.
+ *
+ * - **`Ctrl K`, `Ctrl Space`** (or `⌘` on a Mac) open it from
+ *   anywhere, a text field included — the chord types nothing.
+ * - **`/`** opens it when focus is not somewhere that types, and
+ *   the slash itself is not typed.
+ * - **Any printable key** does the same and becomes the query, so
+ *   the page is a search box without a click (`isOpenedByTyping`).
+ *
+ * It is a hook, not something `CommandPalette` does on mount,
+ * because a document-wide key listener is a page-level decision: an
+ * app with two palettes, or a page where letters already mean
+ * something (a board with its own shortcuts), must be able to say
+ * no. See
+ * `docs/decisions/2026-10-16-command-palette-hotkeys-are-an-opt-in-hook.md`.
+ *
+ * A key another handler already claimed (`defaultPrevented`), a key
+ * pressed during IME composition, and a key with `Alt` held are all
+ * left alone.
+ */
+export const useCommandPaletteHotkeys = ({
+  isEnabled = true,
+  isOpenedByTyping = true,
+  onOpen,
+}: CommandPaletteHotkeysOptions): void => {
+  const onOpenRef = useLatestRef(onOpen)
+
+  useEffect(() => {
+    if (!isEnabled) {
+      return
+    }
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (
+        event.defaultPrevented ||
+        event.isComposing ||
+        event.altKey
+      ) {
+        return
+      }
+
+      const isChord = event.ctrlKey || event.metaKey
+
+      if (isChord) {
+        if (
+          !event.shiftKey &&
+          (event.key.toLowerCase() === "k" ||
+            event.key === " ")
+        ) {
+          event.preventDefault()
+          onOpenRef.current("")
+        }
+
+        return
+      }
+
+      if (getIsTypingTarget(event.target)) {
+        return
+      }
+
+      if (event.key === "/") {
+        event.preventDefault()
+        onOpenRef.current("")
+
+        return
+      }
+
+      // `key` is the character for a printable key and a name
+      // ("Enter", "ArrowDown") for everything else; a space is
+      // printable but presses the focused button.
+      if (
+        isOpenedByTyping &&
+        [...event.key].length === 1 &&
+        /\S/u.test(event.key)
+      ) {
+        event.preventDefault()
+        onOpenRef.current(event.key)
+      }
+    }
+
+    document.addEventListener("keydown", handleKeyDown)
+
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown)
+    }
+  }, [isEnabled, isOpenedByTyping, onOpenRef])
+}

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
@@ -84,6 +86,45 @@ that sets them through a `style` object.
 
 <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,6 +1,6 @@
 import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
-import type { CSSProperties } from "react"
+import { type CSSProperties, useState } from "react"
 
 import { Badge } from "../Badge/Badge.tsx"
 import { Button } from "../Button/Button.tsx"
@@ -10,7 +10,11 @@ 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"
 
@@ -183,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:
@@ -524,6 +664,116 @@ export const StickyHeadings: Story = {
   ),
 }
 
+/**
+ * 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.