@charcuterie/ui 0.1.1 → 1.0.0

package/src/Tooltip/Tooltip.stories.tsx

@@ -0,0 +1,104 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { placementArgType } from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import { IconButton } from "../IconButton/IconButton.tsx"
+import { SettingsIcon } from "../icons.storyHelpers.tsx"
+import { Tooltip } from "./Tooltip.tsx"
+
+const meta = {
+  title: "Components/Tooltip",
+  component: Tooltip,
+  parameters: { layout: "centered" },
+  argTypes: { placement: placementArgType },
+  args: {
+    delay: 200,
+    label: "Re-reads the disc from title 1.",
+    placement: "top",
+  },
+} satisfies Meta<typeof Tooltip>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    children: <Button appearance="outline">Retry</Button>,
+    label: "Re-reads the disc from title 1.",
+  },
+}
+
+/**
+ * A tooltip **adds**; it never *is* the name. The icon button below
+ * still carries its own `aria-label` — the tip is the sentence you
+ * would otherwise have had no room for.
+ */
+export const AllVariants: Story = {
+  args: {
+    children: <Button appearance="outline">Retry</Button>,
+    label: "Re-reads the disc from title 1.",
+  },
+  render: () => (
+    <StoryGrid columns={3}>
+      <StoryCell label="on a button">
+        <Tooltip label="Re-reads the disc from title 1.">
+          <Button appearance="outline">Retry</Button>
+        </Tooltip>
+      </StoryCell>
+
+      <StoryCell label="on an IconButton">
+        <Tooltip label="Opens the bay's rip settings.">
+          <IconButton label="Bay settings">
+            <SettingsIcon />
+          </IconButton>
+        </Tooltip>
+      </StoryCell>
+
+      <StoryCell label="placed below">
+        <Tooltip
+          label="Skips this title and carries on."
+          placement="bottom"
+        >
+          <Button appearance="outline">Skip</Button>
+        </Tooltip>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Closed until something asks for it. There is no "open" prop: a
+ * tooltip's visibility is entirely a consequence of hover or focus,
+ * which is the one piece of state in this library a consumer has no
+ * business holding.
+ */
+export const AllStates: Story = {
+  args: {
+    children: (
+      <Button appearance="outline">
+        Hover or Tab to me
+      </Button>
+    ),
+    label: "Re-reads the disc from title 1.",
+  },
+}
+
+/**
+ * Tab to the button. The tip opens **on focus** — the line
+ * mux-magic's `FieldTooltip` is missing, which makes its version
+ * pointer-only and a WCAG 2.1.1 failure on the control whose
+ * explanation lives there. Escape closes it, per WCAG 1.4.13.
+ */
+export const Interactive: Story = {
+  args: {
+    children: (
+      <Button appearance="outline">Keyboard tip</Button>
+    ),
+    label: "Opened by focus, closed by Escape.",
+  },
+}

package/src/Tooltip/Tooltip.test.tsx

@@ -0,0 +1,138 @@
+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 "./Tooltip.stories.tsx"
+
+const { AllVariants, Default, Interactive } =
+  composeStories(stories)
+
+test("nothing is shown until something asks", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  expectAgentDrivable(canvas, {
+    name: "Retry",
+    role: "button",
+  })
+
+  await expect(
+    canvas.queryAllByRole("tooltip"),
+  ).toHaveLength(0)
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * The defect that matters most in mux-magic's `FieldTooltip`: it
+ * renders `role="tooltip"` and **no `aria-describedby` anywhere**,
+ * so the control it belongs to never mentions it. `role="tooltip"`
+ * is not a live region and does nothing on its own — the tip is a
+ * floating node nobody is pointed at.
+ */
+test("the trigger is described by the tip that opened", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Interactive)
+
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Keyboard tip",
+    role: "button",
+  })
+
+  await expect(trigger).not.toHaveAttribute(
+    "aria-describedby",
+  )
+
+  await userEvent.tab()
+
+  await waitFor(() => {
+    expect(trigger).toHaveFocus()
+  })
+
+  const tip = await waitFor(() =>
+    expectAgentDrivable(canvas, { role: "tooltip" }),
+  )
+
+  await expect(trigger).toHaveAttribute(
+    "aria-describedby",
+    tip.id,
+  )
+
+  await expect(tip).toHaveTextContent(
+    "Opened by focus, closed by Escape.",
+  )
+
+  // Audited in the *driven* state, not at mount. The a11y addon
+  // runs axe once, when `run()` resolves — before anything has been
+  // focused — so an open tip would never be seen by it.
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * Focus, not just hover. `useFocus` is the line mux-magic is
+ * missing, and without it the tip is pointer-only — a WCAG 2.1.1
+ * failure on the one control whose explanation lives there.
+ */
+test("focus opens it and blur closes it", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  await userEvent.tab()
+
+  await waitFor(() => {
+    expectAgentDrivable(canvas, { role: "tooltip" })
+  })
+
+  await userEvent.tab()
+
+  await waitFor(() => {
+    expect(canvas.queryAllByRole("tooltip")).toHaveLength(0)
+  })
+})
+
+test("Escape dismisses it", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  await userEvent.tab()
+
+  await waitFor(() => {
+    expectAgentDrivable(canvas, { role: "tooltip" })
+  })
+
+  // WCAG 1.4.13 requires content shown on hover or focus to be
+  // dismissable without moving the pointer or the caret.
+  await userEvent.keyboard("{Escape}")
+
+  await waitFor(() => {
+    expect(canvas.queryAllByRole("tooltip")).toHaveLength(0)
+  })
+})
+
+/**
+ * A tooltip **adds**; it is never the name. An `IconButton` still
+ * carries its own `aria-label`, and the tip is the sentence there
+ * was no room for — so the button stays findable by the same query
+ * whether or not the tip is open.
+ */
+test("the tip does not become the control's name", async () => {
+  const { canvas } = await mountStory(AllVariants)
+
+  const iconButton = expectAgentDrivable(canvas, {
+    name: "Bay settings",
+    role: "button",
+  })
+
+  await userEvent.hover(iconButton)
+
+  await waitFor(() => {
+    expectAgentDrivable(canvas, { role: "tooltip" })
+  })
+
+  // Still "Bay settings", not "Opens the bay's rip settings."
+  expectAgentDrivable(canvas, {
+    name: "Bay settings",
+    role: "button",
+  })
+})

package/src/Tooltip/Tooltip.tsx

@@ -0,0 +1,193 @@
+import {
+  useClonedChild,
+  useVisibility,
+} from "@charcuterie/logic"
+import type { Placement } from "@floating-ui/react"
+import {
+  autoUpdate,
+  flip,
+  offset,
+  shift,
+  useDismiss,
+  useFloating,
+  useFocus,
+  useHover,
+  useInteractions,
+  useRole,
+} from "@floating-ui/react"
+import type { ReactElement, ReactNode } from "react"
+
+import type { SlotProps } from "../slotProps.ts"
+import { mergeSlotProps } from "../slotProps.ts"
+import { toClassName } from "../toClassName.ts"
+
+export type TooltipProps = SlotProps & {
+  /**
+   * The control the tip describes. **Cloned, not wrapped** — the
+   * same slot contract as `Popover`'s trigger.
+   *
+   * It has to be something focusable. A tooltip on a `<span>` is
+   * pointer-only, which is the state mux-magic's is in today.
+   */
+  children: ReactElement
+  className?: string
+  /** Milliseconds of hover before it opens. */
+  delay?: number
+  /**
+   * Text, and text only. `role="tooltip"` has no way to move focus
+   * into itself, so a link or a button inside one is unreachable by
+   * keyboard and unreadable by touch — if it needs a control, it is
+   * a `Popover`.
+   */
+  label: string
+  placement?: Placement
+}
+
+/**
+ * Replaces mux-magic's `FieldTooltip`, which is 130 lines of
+ * hand-rolled positioning — a `computePosition` that reimplements
+ * `flip` and `shift` against `window.innerHeight` — and has three
+ * defects that all render perfectly:
+ *
+ *  1. **Nothing references the tip.** It sets `role="tooltip"` and
+ *     no `aria-describedby` anywhere, so the control it belongs to
+ *     never mentions it. A screen reader reads the button, says
+ *     nothing about the tip, and the tip itself is a floating node
+ *     nobody is pointed at. `role="tooltip"` is not a live region;
+ *     it does nothing on its own.
+ *  2. **Pointer only.** `onPointerEnter`/`onPointerLeave` with no
+ *     `onFocus`/`onBlur`, so a keyboard user cannot open it at all.
+ *  3. **No dismiss.** Escape does nothing, which WCAG 1.4.13
+ *     requires of any content shown on hover.
+ *
+ * All three come from the same place: the ARIA is written by hand
+ * beside the behaviour instead of falling out of it. Here `useRole`
+ * writes `aria-describedby` on the trigger and `role` + `id` on the
+ * tip from one source, `useFocus` is what makes it keyboard-openable,
+ * and `useDismiss` is Escape.
+ *
+ * ### Not a `title`, and not a substitute for a name
+ *
+ * A `title` attribute is unstyleable, has a ~1s delay nobody can
+ * change, and does not exist on touch. `Badge` still uses one — for
+ * a *truncation* readout, where the full text is already in
+ * `textContent` and the tip is a convenience
+ * ([decision](../../../docs/decisions/2026-07-30-a-badge-truncates-with-text-overflow.md)).
+ * That is the line: a `title` may repeat something already
+ * available, and a `Tooltip` may add something, but **neither may be
+ * the only place a control's name exists**. An icon button still
+ * needs its `aria-label`; the tip is extra.
+ *
+ * ### Touch has no hover, and this component does not pretend
+ *
+ * There is no long-press fallback here. A tooltip is supplementary
+ * by construction, so on the kiosk it simply never appears, and
+ * anything a touch user *must* read belongs in a `Field`'s
+ * `description` instead. Building a long-press would make the tip
+ * load-bearing on exactly the surface where it is least reliable.
+ *
+ * ### A slot is a pass-through
+ *
+ * A `Tooltip` is the natural thing to put between a `Field` and its
+ * control — mux-magic's `FieldLabel` renders a `FieldTooltip` for
+ * exactly that reason. Both components clone onto their one child, so
+ * an outer `Field` used to hand *this component* the `id`,
+ * `aria-describedby`, `aria-invalid` and `required` meant for the
+ * `<input>`, and this component dropped all four without a word.
+ *
+ * Anything in `SlotProps` that arrives from above is forwarded to the
+ * trigger, and `aria-describedby` is **merged** with the tip's own id
+ * rather than overwriting it. `slotProps.ts` has the reasoning.
+ */
+export const Tooltip = ({
+  children,
+  className,
+  delay = 200,
+  label,
+  placement = "top",
+  ...receivedSlotProps
+}: TooltipProps): ReactNode => {
+  const { isVisible, setIsVisible } = useVisibility()
+
+  const { context, floatingStyles, refs } = useFloating({
+    // Read-only, as everywhere: floating-ui is told what is true and
+    // never decides it.
+    open: isVisible,
+    onOpenChange: setIsVisible,
+    placement,
+    middleware: [offset(6), flip(), shift({ padding: 8 })],
+    strategy: "fixed",
+    whileElementsMounted: autoUpdate,
+  })
+
+  const { getFloatingProps, getReferenceProps } =
+    useInteractions([
+      useHover(context, {
+        // `move: false` — a tooltip that re-opens because the
+        // pointer twitched inside the trigger is the flicker every
+        // hand-rolled one has.
+        move: false,
+        restMs: delay,
+      }),
+      // The line mux-magic is missing. Without it the tip is
+      // pointer-only, which is a WCAG 2.1.1 failure on a control
+      // whose explanation lives there.
+      useFocus(context),
+      useDismiss(context, { referencePress: false }),
+      useRole(context, { role: "tooltip" }),
+    ])
+
+  const clonedTrigger = useClonedChild(
+    children,
+    // `mergeSlotProps` rather than a spread, because
+    // `getReferenceProps()` writes an `aria-describedby` of its own —
+    // `useRole` pointing the trigger at the tip — and an outer
+    // `Field` writes one naming its description and its error. A
+    // spread keeps whichever went last.
+    mergeSlotProps(receivedSlotProps, {
+      ...getReferenceProps(),
+      ref: refs.setReference,
+    }),
+  )
+
+  return (
+    <>
+      {clonedTrigger}
+
+      {isVisible ? (
+        <div
+          {...getFloatingProps()}
+          className={toClassName(
+            // `intent-neutral-solid` + its own `on-solid`, rather
+            // than `surface-inverse` + `content-on-accent`. The
+            // second pair looks like the obvious one and is not a
+            // *pair* at all — nothing in the token set promises those
+            // two contrast, and in `daylight` dark they land at
+            // 2.9:1. The `solid`/`on-solid` roles exist precisely to
+            // be a guaranteed couple, and the contrast gate checks
+            // them as one.
+            "inset-auto m-0 max-w-xs rounded-md bg-intent-neutral-solid px-2 py-1 text-intent-neutral-on-solid text-xs shadow-medium",
+            className,
+          )}
+          // No `popover="manual"` and no `FloatingFocusManager`,
+          // unlike `Popover`. Both exist to manage focus, and focus
+          // never enters a tooltip — moving it here is what makes
+          // one unescapable. The trade is that a tooltip is not in
+          // the top layer, so it can be clipped by an
+          // `overflow: hidden` ancestor; `strategy: "fixed"` keeps
+          // that to ancestors that actually clip fixed descendants.
+          ref={refs.setFloating}
+          // Duplicated from `getFloatingProps()` deliberately, and
+          // the two cannot differ — `useRole(context, { role:
+          // "tooltip" })` above is where it comes from. Stated here
+          // because a linter cannot see a role through a spread, and
+          // neither can the next reader.
+          role="tooltip"
+          style={floatingStyles}
+        >
+          {label}
+        </div>
+      ) : null}
+    </>
+  )
+}

package/src/index.ts

@@ -31,6 +31,12 @@
  * this package's README has always told it to do.
  */
 
+export type {
+  AccordionHeadingLevel,
+  AccordionItem,
+  AccordionProps,
+} from "./Accordion/Accordion.tsx"
+export { Accordion } from "./Accordion/Accordion.tsx"
 export type {
   AlertProps,
   AlertSize,
@@ -60,6 +66,12 @@ export type {
   EmptyStateSize,
 } from "./EmptyState/EmptyState.tsx"
 export { EmptyState } from "./EmptyState/EmptyState.tsx"
+export type { FieldProps } from "./Field/Field.tsx"
+export { Field } from "./Field/Field.tsx"
+export type { FieldGroupProps } from "./Field/FieldGroup.tsx"
+export { FieldGroup } from "./Field/FieldGroup.tsx"
+export type { FileDropZoneProps } from "./FileDropZone/FileDropZone.tsx"
+export { FileDropZone } from "./FileDropZone/FileDropZone.tsx"
 export type { IconButtonProps } from "./IconButton/IconButton.tsx"
 export { IconButton } from "./IconButton/IconButton.tsx"
 export type { IntentAppearance } from "./intentStyles.ts"
@@ -76,6 +88,11 @@ export type {
   LiveStatusIndicatorSize,
 } from "./LiveStatusIndicator/LiveStatusIndicator.tsx"
 export { LiveStatusIndicator } from "./LiveStatusIndicator/LiveStatusIndicator.tsx"
+export type {
+  LogLine,
+  LogViewerProps,
+} from "./LogViewer/LogViewer.tsx"
+export { LogViewer } from "./LogViewer/LogViewer.tsx"
 export type {
   MediaTileProps,
   MediaTileRatio,
@@ -83,6 +100,11 @@ export type {
 export { MediaTile } from "./MediaTile/MediaTile.tsx"
 export type { MediaStatus } from "./MediaTile/mediaStatus.ts"
 export { mediaTransitions } from "./MediaTile/mediaStatus.ts"
+export type {
+  MenuItem,
+  MenuProps,
+} from "./Menu/Menu.tsx"
+export { Menu } from "./Menu/Menu.tsx"
 export type {
   ModalProps,
   ModalSize,
@@ -106,13 +128,27 @@ export type {
   SegmentedItem,
 } from "./SegmentedControl/SegmentedControl.tsx"
 export { SegmentedControl } from "./SegmentedControl/SegmentedControl.tsx"
+export type {
+  SelectItem,
+  SelectOption,
+  SelectOptionGroup,
+  SelectProps,
+} from "./Select/Select.tsx"
+export { Select } from "./Select/Select.tsx"
 export type {
   SkeletonProps,
   SkeletonShape,
 } from "./Skeleton/Skeleton.tsx"
 export { Skeleton } from "./Skeleton/Skeleton.tsx"
+export type {
+  SortableTableHeaderProps,
+  SortDirection,
+} from "./SortableTableHeader/SortableTableHeader.tsx"
+export { SortableTableHeader } from "./SortableTableHeader/SortableTableHeader.tsx"
 export type { SpinnerProps } from "./Spinner/Spinner.tsx"
 export { Spinner } from "./Spinner/Spinner.tsx"
+export type { SlotProps } from "./slotProps.ts"
+export { mergeSlotProps } from "./slotProps.ts"
 export {
   getAsyncIntent,
   getAsyncLabel,
@@ -127,6 +163,17 @@ export type {
   TabsProps,
 } from "./Tabs/Tabs.tsx"
 export { Tabs } from "./Tabs/Tabs.tsx"
+export type { ToastProps } from "./Toast/Toast.tsx"
+export { Toast } from "./Toast/Toast.tsx"
+export type {
+  ToastRecord,
+  ToastRegionProps,
+} from "./Toast/ToastRegion.tsx"
+export { ToastRegion } from "./Toast/ToastRegion.tsx"
+export type { ToastStatus } from "./Toast/toastLifecycle.ts"
+export { toastTransitions } from "./Toast/toastLifecycle.ts"
+export type { TooltipProps } from "./Tooltip/Tooltip.tsx"
+export { Tooltip } from "./Tooltip/Tooltip.tsx"
 export { toClassName } from "./toClassName.ts"
 export type { VisuallyHiddenProps } from "./VisuallyHidden/VisuallyHidden.tsx"
 export { VisuallyHidden } from "./VisuallyHidden/VisuallyHidden.tsx"

package/src/mountStory.testHelpers.ts

@@ -25,16 +25,46 @@ type MountableStory = {
  * drift from it. It is also what triggers the a11y addon's
  * `afterEach`, so every mount here is an axe run.
  */
+/**
+ * Every canvas this helper has created, so the next mount can take
+ * the previous ones out of the document.
+ *
+ * They used to accumulate — one detached-but-attached `<div>` per
+ * test, for the whole file — and nothing noticed for three
+ * milestones, because every component up to M6 lays out **in
+ * flow**: a stale copy sits harmlessly below the live one and every
+ * query is scoped to its own canvas anyway.
+ *
+ * `ToastRegion` is the first `position: fixed` component in the
+ * library, and it broke that immediately. A previous test's toast
+ * stack is pinned to the same corner of the viewport as the live
+ * one, so `userEvent.click` — which clicks by **coordinates** —
+ * drove the wrong element while every query still returned the
+ * right one. The test failed with "the toast did not go away", one
+ * test after the toast it was actually clicking.
+ *
+ * The stale tree is removed rather than unmounted because portable
+ * stories expose no unmount. Detaching is enough: it takes the node
+ * out of the layout, which is the entire problem.
+ */
+const mountedCanvases: HTMLElement[] = []
+
 export const mountStory = async (
   story: MountableStory,
 ): Promise<{
   canvas: Canvas
   canvasElement: HTMLElement
 }> => {
+  for (const previous of mountedCanvases.splice(0)) {
+    previous.remove()
+  }
+
   const canvasElement = document.createElement("div")
 
   document.body.append(canvasElement)
 
+  mountedCanvases.push(canvasElement)
+
   await story.run({ canvasElement })
 
   return { canvas: within(canvasElement), canvasElement }