@charcuterie/ui 0.1.0 → 0.2.0

package/src/Accordion/Accordion.stories.tsx

@@ -0,0 +1,146 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { Badge } from "../Badge/Badge.tsx"
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import type { AccordionItem } from "./Accordion.tsx"
+import { Accordion } from "./Accordion.tsx"
+
+const JOB_SECTIONS: AccordionItem[] = [
+  {
+    content: (
+      <p>Blade Runner (1982) · 9 titles · MakeMKV 1.17.8</p>
+    ),
+    key: "disc",
+    label: "Disc",
+  },
+  {
+    content: (
+      <p className="font-mono text-xs">
+        14:02:11 AACS handshake complete, reading…
+      </p>
+    ),
+    key: "log",
+    label: "Log",
+  },
+  {
+    content: (
+      <div className="flex gap-2">
+        <Badge intent="warning" size="sm">
+          1 retry
+        </Badge>
+
+        <Badge intent="info" size="sm">
+          AACS
+        </Badge>
+      </div>
+    ),
+    key: "flags",
+    label: "Flags",
+  },
+]
+
+const STATE_SECTIONS: AccordionItem[] = [
+  ...JOB_SECTIONS,
+  {
+    content: <p>Unreachable — no verdict yet.</p>,
+    isDisabled: true,
+    key: "verdict",
+    label: "Verdict",
+  },
+]
+
+const meta = {
+  title: "Components/Accordion",
+  component: Accordion,
+  parameters: { layout: "padded" },
+  args: {
+    headingLevel: 3,
+    isMultiple: false,
+    items: JOB_SECTIONS,
+  },
+} satisfies Meta<typeof Accordion>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { expandedKeys: ["disc"], items: JOB_SECTIONS },
+}
+
+/**
+ * Exclusive is `VisibilityGroup`; `isMultiple` is
+ * `MultiplePicker`. Both hooks are created and one is consulted,
+ * because hooks cannot be conditional — two empty stores and no DOM,
+ * which is cheaper than reimplementing exclusivity on top of the
+ * multiple kind.
+ */
+export const AllVariants: Story = {
+  args: { items: JOB_SECTIONS },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell label="exclusive (default)">
+        <Accordion
+          expandedKeys={["disc"]}
+          items={JOB_SECTIONS}
+        />
+      </StoryCell>
+
+      <StoryCell label="multiple">
+        <Accordion
+          expandedKeys={["disc", "flags"]}
+          isMultiple
+          items={JOB_SECTIONS}
+        />
+      </StoryCell>
+
+      <StoryCell label="all collapsed">
+        <Accordion items={JOB_SECTIONS} />
+      </StoryCell>
+
+      {/*
+        Its own item set, with names that appear nowhere else on the
+        board. Four accordions sharing three labels means
+        `getByRole("heading", { name: "Log" })` matches four
+        elements, and `expectAgentDrivable` treats ambiguity as a
+        failure — correctly, since an agent would be picking one at
+        random.
+      */}
+      <StoryCell label="heading level 2">
+        <Accordion
+          expandedKeys={["steps"]}
+          headingLevel={2}
+          items={[
+            {
+              content: <p>4 of 9 titles complete.</p>,
+              key: "steps",
+              label: "Steps",
+            },
+            {
+              content: <p>No errors.</p>,
+              key: "errors",
+              label: "Errors",
+            },
+          ]}
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * A disabled section is **not a member of the group**. Registration
+ * is membership, so nothing can expand it — including a consumer
+ * passing its key in `expandedKeys`. That is the behaviour a
+ * `<summary>` cannot have at all, which is one of the two reasons
+ * this is not built on `<details>`.
+ */
+export const AllStates: Story = {
+  args: {
+    expandedKeys: ["verdict"],
+    items: STATE_SECTIONS,
+  },
+}

package/src/Accordion/Accordion.test.tsx

@@ -0,0 +1,163 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent, waitFor } from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./Accordion.stories.tsx"
+
+const { AllStates, AllVariants, Default } =
+  composeStories(stories)
+
+test("a trigger says what it controls and whether it is open", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  const disc = expectAgentDrivable(canvas, {
+    name: "Disc",
+    role: "button",
+  })
+
+  await expect(disc).toHaveAttribute(
+    "aria-expanded",
+    "true",
+  )
+
+  // The panel is queried by id rather than by role, because it is
+  // deliberately **not** a landmark — the APG's own caveat about
+  // "landmark region proliferation", which a board of four
+  // accordions turned into a failing `landmark-unique` immediately.
+  const panel = document.getElementById(
+    disc.getAttribute("aria-controls") ?? "",
+  )
+
+  await expect(panel).not.toBeNull()
+
+  // The link still reaches in both directions — the button's
+  // `aria-controls` at the panel, the panel's `aria-labelledby` back
+  // at the button. Both ids come from one `useUniqueId`, and this is
+  // the relationship a screen reader actually follows; the landmark
+  // only ever added a second route to the same node.
+  await expect(panel).toHaveAttribute(
+    "aria-labelledby",
+    disc.id,
+  )
+
+  await expect(panel).toHaveTextContent("Blade Runner")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * The first-paint hole `Tabs` found, in the other kind. Members
+ * register from an effect, so on the very first paint the intent
+ * still lives in `pendingKey` — an accordion reading only
+ * `visibleKey` renders every section collapsed and corrects itself a
+ * frame later.
+ */
+test("the initially expanded section is expanded on the first paint", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const expanded = canvas
+    .queryAllByRole("button")
+    .filter(
+      (one: HTMLElement) =>
+        one.getAttribute("aria-expanded") === "true",
+    )
+
+  await expect(expanded).toHaveLength(1)
+
+  await expect(expanded[0]).toHaveTextContent("Disc")
+})
+
+test("exclusive means opening one closes the other", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const log = expectAgentDrivable(canvas, {
+    name: "Log",
+    role: "button",
+  })
+
+  await userEvent.click(log)
+
+  await waitFor(() => {
+    expect(log).toHaveAttribute("aria-expanded", "true")
+  })
+
+  await expect(
+    expectAgentDrivable(canvas, {
+      name: "Disc",
+      role: "button",
+    }),
+  ).toHaveAttribute("aria-expanded", "false")
+})
+
+test("multiple keeps both open", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllVariants)
+
+  // Two sections start expanded in the `multiple` cell, which the
+  // exclusive kind cannot represent at all.
+  const expanded = canvas
+    .queryAllByRole("button")
+    .filter(
+      (one: HTMLElement) =>
+        one.getAttribute("aria-expanded") === "true",
+    )
+    .map((one: HTMLElement) => one.textContent)
+
+  await expect(expanded).toEqual([
+    "Disc",
+    "Disc",
+    "Flags",
+    "Steps",
+  ])
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("the heading level is the caller's, not the component's", async () => {
+  const { canvas } = await mountStory(AllVariants)
+
+  const level2 = expectAgentDrivable(canvas, {
+    name: "Steps",
+    role: "heading",
+  })
+
+  // An accordion inside a `Card` that already has an `<h2>` needs
+  // `3`, and getting it wrong is a document-outline break no gate
+  // here can see — it depends entirely on the page.
+  await expect(level2.tagName).toBe("H2")
+})
+
+/**
+ * Registration is membership. A disabled section never registers, so
+ * nothing can expand it — including this story, which passes its key
+ * in `expandedKeys` on purpose.
+ */
+test("a disabled section cannot be expanded, even by the caller", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  const verdict = expectAgentDrivable(canvas, {
+    name: "Verdict",
+    role: "button",
+  })
+
+  await expect(verdict).toBeDisabled()
+
+  await expect(verdict).toHaveAttribute(
+    "aria-expanded",
+    "false",
+  )
+
+  await userEvent.click(verdict, { pointerEventsCheck: 0 })
+
+  await expect(verdict).toHaveAttribute(
+    "aria-expanded",
+    "false",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/Accordion/Accordion.tsx

@@ -0,0 +1,182 @@
+import {
+  useMultiplePicker,
+  useUniqueId,
+  useVisibilityGroup,
+} from "@charcuterie/logic"
+import type { ReactNode } from "react"
+
+import { toClassName } from "../toClassName.ts"
+import { AccordionSection } from "./AccordionSection.tsx"
+
+export type AccordionHeadingLevel = 2 | 3 | 4 | 5 | 6
+
+export type AccordionItem = {
+  content: ReactNode
+  isDisabled?: boolean
+  key: string
+  label: ReactNode
+}
+
+export type AccordionProps = {
+  className?: string
+  /** **Initial** only. Charcuterie owns it from then on. */
+  expandedKeys?: string[]
+  /**
+   * The heading level the triggers sit at. An accordion inside a
+   * `Card` that already has an `<h2>` needs `3`, and getting this
+   * wrong is a document-outline break that no gate here can see —
+   * it depends entirely on the page.
+   */
+  headingLevel?: AccordionHeadingLevel
+  /**
+   * Several sections open at once. The default is **exclusive**,
+   * because that is what every one of the fleet's disclosure groups
+   * does today.
+   */
+  isMultiple?: boolean
+  items: AccordionItem[]
+  onChange?: (expandedKeys: string[]) => void
+}
+
+/**
+ * Eleven sites in the fleet, and the plan called it "nearly free
+ * once `Tabs` exists". It is — the exclusive mode is
+ * `VisibilityGroup` and nothing else — but the reason it is worth
+ * shipping is not the saving.
+ *
+ * ### The two-owners bug, live, in the app this milestone migrates
+ *
+ * mux-magic's `JobStepsDisclosure` is built on `<details>`, and
+ * `<details>` **owns `open`**. It also wants the state in a Jotai
+ * atom so a job can be expanded from elsewhere. Reconciling the two
+ * takes three separate mechanisms:
+ *
+ * ```tsx
+ * const detailsRef = useRef<HTMLDetailsElement>(null)
+ * const skipNextToggleRef = useRef(isOpen)
+ *
+ * useEffect(() => {
+ *   if (detailsRef.current) detailsRef.current.open = isOpen
+ * }, [isOpen])
+ *
+ * const handleToggle = (event) => {
+ *   if (skipNextToggleRef.current) {
+ *     skipNextToggleRef.current = false
+ *     return          // ← swallow the toggle our own write just fired
+ *   }
+ *   setStepsOpen(…)
+ * }
+ * ```
+ *
+ * That is the Radix argument from `Popover` pointed at the platform:
+ * a ref to reach past React, an effect to push state into the DOM,
+ * and a guard to stop the DOM's echo coming back. Every one of the
+ * three exists only because two things hold one fact.
+ *
+ * So this is a `<button aria-expanded>` and a `role="region"` — the
+ * ARIA Authoring Practices accordion — with `VisibilityGroup`
+ * holding the state alone. `<details name="…">` is the platform's
+ * own exclusive accordion and was rejected for the same reason, plus
+ * one it cannot fix: **a `<summary>` cannot be disabled**, and four
+ * of the fleet's eleven sites have a section that is unreachable
+ * until a job produces it.
+ *
+ * ### Two kinds, one component, and both hooks always run
+ *
+ * `isMultiple` picks between `VisibilityGroup` and `MultiplePicker`,
+ * and hooks cannot be conditional — so both are created and one is
+ * consulted. That is two empty stores and no DOM, which is cheaper
+ * than the alternative: reimplementing exclusivity on top of
+ * `MultiplePicker` by deselecting the others, which is precisely the
+ * logic `VisibilityGroup` exists to own once.
+ */
+export const Accordion = ({
+  className,
+  expandedKeys,
+  headingLevel = 3,
+  isMultiple = false,
+  items,
+  onChange,
+}: AccordionProps): ReactNode => {
+  const baseId = useUniqueId()
+
+  const [initialKey] = expandedKeys ?? []
+
+  const group = useVisibilityGroup<string>({
+    onChange: (visibleKey) => {
+      if (!isMultiple) {
+        onChange?.(visibleKey === null ? [] : [visibleKey])
+      }
+    },
+    visibleKey: initialKey ?? null,
+  })
+
+  const picker = useMultiplePicker<string>({
+    onChange: (selectedValues) => {
+      if (isMultiple) {
+        onChange?.([...selectedValues])
+      }
+    },
+    selectedValues: expandedKeys,
+  })
+
+  /**
+   * Visible **or** pending, the same load-bearing fallback `Tabs`
+   * needs and for the same reason: members register from an effect,
+   * so on the first paint the intent still lives in the pending
+   * field. Reading only the settled one renders every section
+   * collapsed and corrects itself a frame later — a flash on a
+   * desktop and a visible jump on the kiosk Pi.
+   *
+   * **And only until something registers**, which `Tabs` never had
+   * to say because it seeds itself from the first *enabled* tab. A
+   * key that can never register — a disabled section's — stays
+   * pending forever, so an unqualified fallback renders it expanded
+   * permanently and `isDisabled` quietly stops meaning anything.
+   * Found by the story that passes a disabled key on purpose.
+   *
+   * Every member registers in one commit, so this really is "before
+   * the first effects ran" rather than a race between them.
+   */
+  const hasRegistered = isMultiple
+    ? picker.registeredValues.length > 0
+    : group.registeredKeys.length > 0
+
+  const expanded = isMultiple
+    ? new Set([
+        ...picker.selectedValues,
+        ...(hasRegistered ? [] : picker.pendingValues),
+      ])
+    : new Set(
+        [
+          group.visibleKey ??
+            (hasRegistered ? null : group.pendingKey),
+        ].filter((key) => key !== null),
+      )
+
+  return (
+    <div
+      className={toClassName(
+        "flex flex-col divide-y divide-border-subtle overflow-hidden rounded-md border border-border-subtle",
+        className,
+      )}
+    >
+      {items.map((item, index) => (
+        <AccordionSection
+          headingLevel={headingLevel}
+          id={`${baseId}-trigger-${index}`}
+          isExpanded={expanded.has(item.key)}
+          item={item}
+          key={item.key}
+          onToggle={
+            isMultiple ? picker.toggle : group.toggle
+          }
+          panelId={`${baseId}-panel-${index}`}
+          register={
+            isMultiple ? picker.register : group.register
+          }
+        />
+      ))}
+    </div>
+  )
+}

package/src/Accordion/AccordionSection.tsx

@@ -0,0 +1,163 @@
+import type { ReactNode } from "react"
+import { useEffect } from "react"
+
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+import type {
+  AccordionHeadingLevel,
+  AccordionItem,
+} from "./Accordion.tsx"
+
+/**
+ * Written out rather than interpolated into a tag name. React
+ * accepts `` `h${level}` `` perfectly well; a reader and a grep do
+ * not, and "which heading levels does this component emit" should be
+ * answerable by looking.
+ */
+const HEADING_TAG: Record<
+  AccordionHeadingLevel,
+  "h2" | "h3" | "h4" | "h5" | "h6"
+> = {
+  2: "h2",
+  3: "h3",
+  4: "h4",
+  5: "h5",
+  6: "h6",
+}
+
+export type AccordionSectionProps = {
+  headingLevel: AccordionHeadingLevel
+  id: string
+  isExpanded: boolean
+  item: AccordionItem
+  onToggle: (key: string) => void
+  panelId: string
+  /**
+   * `VisibilityGroup.register` or `MultiplePicker.register`,
+   * whichever kind the accordion is running. Both have this shape,
+   * which is the point of the kinds being separate rather than one
+   * configurable one.
+   */
+  register: (key: string) => () => void
+}
+
+/**
+ * Its own file for the same reason `TabTrigger` is: **registration
+ * is an effect**, and an effect cannot run in a loop.
+ *
+ * A disabled section stays out of the group entirely — it is not a
+ * member, so nothing can expand it, including a consumer passing its
+ * key in `expandedKeys`. That is registration-as-membership again,
+ * and it is the behaviour a `<summary>` cannot have at all.
+ */
+export const AccordionSection = ({
+  headingLevel,
+  id,
+  isExpanded,
+  item,
+  onToggle,
+  panelId,
+  register,
+}: AccordionSectionProps): ReactNode => {
+  const { isDisabled = false, key, label } = item
+
+  const Heading = HEADING_TAG[headingLevel]
+
+  useEffect(() => {
+    if (isDisabled) {
+      return
+    }
+
+    return register(key)
+  }, [isDisabled, key, register])
+
+  return (
+    <div className="bg-surface-raised">
+      <Heading className="m-0 text-md">
+        <button
+          aria-controls={panelId}
+          aria-expanded={isExpanded}
+          className={toClassName(
+            "flex w-full cursor-pointer items-center justify-between gap-3 bg-transparent px-4 py-3 text-start font-medium text-content-primary text-sm transition-colors duration-(--duration-fast) ease-standard",
+            "hover:bg-intent-neutral-surface",
+            isDisabled &&
+              "cursor-not-allowed text-content-disabled hover:bg-transparent",
+            FOCUS_RING_CLASS,
+          )}
+          disabled={isDisabled}
+          id={id}
+          onClick={() => {
+            onToggle(key)
+          }}
+          type="button"
+        >
+          {label}
+
+          <svg
+            // Decoration. The button already announces
+            // `aria-expanded`, which is the same fact said properly.
+            aria-hidden="true"
+            className={toClassName(
+              "size-4 shrink-0 text-content-secondary transition-transform duration-(--duration-fast) ease-standard",
+              isExpanded && "rotate-180",
+            )}
+            fill="none"
+            focusable={false}
+            stroke="currentColor"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            strokeWidth={1.75}
+            viewBox="0 0 24 24"
+            xmlns="http://www.w3.org/2000/svg"
+          >
+            <path d="m6 9 6 6 6-6" />
+          </svg>
+        </button>
+      </Heading>
+
+      {/*
+        `group`, not `region`, and the difference is a landmark.
+
+        The APG's accordion pattern says a panel *may* take
+        `role="region"` and adds a caveat in the same breath: avoid
+        it "in circumstances that create landmark region
+        proliferation". A component library has to assume the worst
+        case, and the worst case arrived on the first board — four
+        accordions produced four landmarks named "Disc", and axe's
+        `landmark-unique` failed the story. A real page with a job
+        list does exactly that.
+
+        Dropping the role entirely was the first fix and it was
+        wrong: `aria-labelledby` on a roleless `<div>` is **inert**,
+        so the panel would have lost its name rather than just its
+        landmark — caught by `useAriaPropsSupportedByRole`, which is
+        the one linter rule in this file that was right.
+
+        `group` is the role the caveat is reaching for: "a set of UI
+        objects **not** intended to be included in a page summary".
+        It keeps `aria-labelledby` meaningful and stays out of the
+        landmark list.
+      */}
+      {/* biome-ignore lint/a11y/useSemanticElements: the semantic element for `group` is `<fieldset>`, which is a form-control grouping — it drags `<legend>` semantics and form-reset behaviour onto an accordion panel that contains prose. */}
+      <div
+        aria-labelledby={id}
+        className="px-4 pt-1 pb-4 text-content-secondary text-sm"
+        // `hidden` rather than unmounting, matching `Tabs`. A panel
+        // that unmounts loses a scroll position, a partially typed
+        // form, and any subscription its content opened — and the
+        // fleet's log panes are exactly that.
+        hidden={!isExpanded}
+        id={panelId}
+        // `group`, not `region`. A `group` is explicitly "a set of
+        // UI objects **not** intended to be included in a page
+        // summary", so it carries `aria-labelledby` and the
+        // trigger↔panel relationship without joining the landmark
+        // list — which is exactly the distinction the APG's caveat
+        // is reaching for and does not have a role for.
+        role="group"
+      >
+        {item.content}
+      </div>
+    </div>
+  )
+}