@charcuterie/ui 0.1.1 → 1.0.0

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>
+  )
+}

package/src/Field/Field.mdx

@@ -0,0 +1,144 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as FieldStories from "./Field.stories";
+
+<Meta of={FieldStories} />
+
+# Field
+
+Sixteen files in the fleet spell a label, a control, and a hint, and no two spell the
+wiring the same way.
+
+An earlier version of this page said mux-magic's `FieldLabel` renders a `<label>` with
+**no `htmlFor`**. That is false, and worth correcting rather than quietly deleting: it
+renders ``htmlFor={`${stepId}-${field.name}`}``, and has since it was written. The defect
+is at the *other* end of the pair — **8 of its 16 call sites never render that id on
+anything**. Measured on `mux-magic@master`, the eight that do are `BooleanField`,
+`ChapterSplitsField`, `EnumField`, `NumberField`, `NumberWithLookupField`, `PathField`,
+`StringArrayField` and `StringField`. Of the rest, `RegexWithFlagsField` mints its own
+`patternId` / `flagsId` / `sampleId` and `SubtitleRulesField` spells
+``${step.command}-hasDefaultRules`` where the label says ``${step.id}-…``.
+
+The outcome is the same unnamed textbox by a worse route: a `<label>` pointing at an id
+that is nowhere in the document reads as correct in the label's own file, and is only
+wrong in the *other* file. Half of them are broken and nothing says which half. That is
+the argument for a component rather than a convention — here the id is minted and consumed
+in one place and cannot be spelled twice.
+
+<Canvas of={FieldStories.Default} />
+
+## Props
+
+<Controls />
+
+## The control is a slot
+
+Cloned, not wrapped — the same contract as `Popover`'s trigger. An `<input>`, a
+`<textarea>`, a `Select`, or an app's own control all go in the same hole, and the `id`,
+`aria-describedby`, `aria-invalid` and `required` are injected onto whatever arrives.
+
+<Canvas of={FieldStories.AllVariants} />
+
+## A slot is a pass-through
+
+Which is a rule this component needed and did not have. `Field` and `Tooltip` both clone
+onto their single child, so the obvious thing to write —
+
+```tsx
+<Field label="Rename pattern" isRequired>
+  <Tooltip label="A JavaScript regular expression.">
+    <input />
+  </Tooltip>
+</Field>
+```
+
+— handed `id`, `aria-describedby`, `aria-invalid` and `required` to the **`Tooltip`
+component**, which declares none of them. `cloneElement` does not care. React drops all
+four without a warning, TypeScript never sees it (`Children.only` returns a `ReactElement`
+whose props are `any`), every test still passed, and the render was pixel-identical. The
+only symptom was a `<label htmlFor>` pointing at an id nowhere in the document — the exact
+defect above, reproduced by the component built to prevent it, and this time by the
+library rather than by a consumer.
+
+**Silent prop-dropping is the worst version of this**, so anything a slot receives from
+above is forwarded to the child it clones onto, and a chain of slots behaves like the one
+control at the bottom of it. `aria-describedby` — the one prop that is a *list* — is
+merged rather than overwritten, outer first.
+
+It works in both orders, and the second is not symmetrical: a `Tooltip` around a `Field`
+hands down not one attribute but a working component — floating-ui's hover, focus and
+dismiss handlers and `refs.setReference`. Those reach the control too, or the tip is a
+floating node with no trigger and no anchor.
+
+<Canvas of={FieldStories.Nested} />
+
+## Several controls are a `FieldGroup`, not a `Field`
+
+`Field` mints one id and clones it onto one child. An `id` names one element and a
+`<label htmlFor>` points at one, so the moment there are two controls the label names one
+of them and leaves the rest anonymous. Six of mux-magic's sixteen field components are in
+that position — `RegexWithFlagsField` (pattern, flags, sample, and a checkbox),
+`NumberWithLookupField`, `LanguageCodeField`, `LanguageCodesField`, `SubtitleTypesField`
+and `RenameRegexField`.
+
+`FieldGroup` renders `<fieldset>` + `<legend>` and does **not** clone. This is the one
+place in the library where `<fieldset>` is right: `AccordionSection` rejected it for its
+panel precisely because that element means *form-control grouping*, and here the content
+really is one. `<legend>` names the group natively, so no `role="group"` and no
+`aria-labelledby`.
+
+What a group cannot carry is `aria-invalid`, which has no group form — it belongs on the
+control that is actually invalid, and a `FieldGroup` does not know which one that is. So
+`error` here is **described, not asserted**: it joins the `<fieldset>`'s
+`aria-describedby`. Cloning `aria-invalid` onto every child would mark the valid ones
+invalid. A control that is itself invalid says so in its own `Field`.
+
+<Canvas of={FieldStories.Group} />
+
+## `createLinkedIds` is *not* here, and that is the finding
+
+The plan expected `useLinkedIds` to do this wiring. It does not fit, for the same reason it
+did not fit `Tabs`: that kind exists for a **dynamic** pairing, where the registration
+multiset is what stops an `aria-describedby` naming a node React has already removed.
+
+A field renders its own description and its own error, so it knows *at render* which exist.
+The ids come from one `useUniqueId` and a conditional join, and they cannot get out of step
+at all.
+
+That leaves `createLinkedIds` with **no consumer in this package across twenty-five
+components**. It is the one state kind the component layer has never needed, and saying so
+is more useful than manufacturing a use for it.
+
+## One source of invalidity
+
+There is no `isInvalid` prop. `error` being present *is* the invalidity:
+
+| `error` | `aria-invalid` | `aria-describedby` |
+| --- | --- | --- |
+| absent | not set | description only, if any |
+| present | `"true"` | description then error |
+
+Two props for one fact is how a control ends up `aria-invalid="true"` with nothing saying
+why — which is what `RegexWithFlagsField` does in mux-magic today.
+
+<Canvas of={FieldStories.AllStates} />
+
+## The error is *described*, not announced
+
+No `role="alert"` and no live region, deliberately. An error bound through
+`aria-describedby` is read when the control takes focus — which is when the user can act on
+it. A live region on the same text announces it a second time, from nowhere, while the caret
+is somewhere else.
+
+A form that fails on submit should say so **once, at the top**, with the `Alert` this
+library already ships. Then the user tabs into the field and hears the specific reason.
+`ToastRegion` draws the same line for the same reason.
+
+## Order is behaviour
+
+`aria-describedby` is read in sequence, so description comes before error:
+
+> "Absolute paths only. That path is not writable."
+
+reads correctly; its reverse does not. Nothing enforces this but the order of one array in
+the component, which is why that array is not built from an object.