@charcuterie/ui 0.1.0

package/src/Modal/Modal.tsx

@@ -0,0 +1,228 @@
+import { useUniqueId } from "@charcuterie/logic"
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+import { useEffect, useRef } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import { toClassName } from "../toClassName.ts"
+import { lockScrollBehind } from "./lockScrollBehind.ts"
+
+export type ModalSize = "full" | "lg" | "md" | "sm" | "xl"
+
+export type ModalProps = Omit<
+  ComponentPropsWithRef<"dialog">,
+  "onClose" | "open"
+> & {
+  /** The footer row. Buttons, usually. */
+  footer?: ReactNode
+  heading: string
+  headingLevel?: 2 | 3 | 4
+  /**
+   * Escape and a backdrop press both close. Off for the one
+   * honest case — a destructive confirm the user has to answer —
+   * and off means Escape is *cancelled* rather than ignored, so
+   * the browser cannot close a dialog the app still owns.
+   */
+  isDismissable?: boolean
+  isVisible: boolean
+  /**
+   * Every route out lands here: the close button, Escape, a
+   * backdrop press. Wire it to a `useVisibility()`'s `hide`.
+   */
+  onClose: () => void
+  size?: ModalSize
+}
+
+/**
+ * `85dvh` rather than `85vh` — on a phone the two differ by the
+ * address bar, and a dialog whose footer is under it is a dialog
+ * with no buttons.
+ */
+const SIZE_CLASS: Record<ModalSize, string> = {
+  sm: "max-h-[85dvh] w-full max-w-sm",
+  md: "max-h-[85dvh] w-full max-w-md",
+  lg: "max-h-[85dvh] w-full max-w-2xl",
+  // M5 added this, because the scale jumped from 42rem straight to
+  // the whole viewport and rip-deck's capture tail lands in the
+  // gap: a MakeMKV robot log is fixed-width `MSG:5072,0,1,"…"`
+  // lines that wrap badly at 42rem, and a full-screen dialog over a
+  // nine-bay dashboard hides the thing being diagnosed. 56rem is
+  // what that app's hand-rolled `<dialog>` used before the swap.
+  xl: "max-h-[85dvh] w-full max-w-4xl",
+  full: "h-[100dvh] max-h-[100dvh] w-full max-w-full rounded-none",
+}
+
+/**
+ * Four repos, and **plex-channels and ripdeck independently
+ * converged on native `<dialog>`** — which is the design here
+ * rather than a shortcut. `showModal()` gives a focus trap,
+ * Escape, `::backdrop`, `inert` on everything behind it, and the
+ * **top layer**, from the platform, correctly, in every browser
+ * the fleet runs.
+ *
+ * What is not free — and the reason a component exists at all —
+ * is that a native `<dialog>` is a *self-owning* control: call
+ * `showModal()` and it decides it is open. That is the same
+ * conflict Radix has, and it gets the same answer as everywhere
+ * else in this library: **`isVisible` is the truth, and an effect
+ * makes the element agree with it.** Nothing here reads
+ * `dialogElement.open` as state; it is read only to avoid calling
+ * a method that would throw.
+ *
+ * ### Why it is not portalled
+ *
+ * The top layer is a *paint* concept: a `<dialog>` renders above
+ * everything while staying exactly where it is in the DOM. So it
+ * needs no portal — and that matters well past tidiness, because a
+ * portal moves the node to `document.body`, out of whatever
+ * element a test or an agent scoped its queries to.
+ * `canvas.getByRole("dialog")` finds this one. It would not find a
+ * portalled one, and the story would have to reach for `screen`
+ * and lose its scoping.
+ *
+ * ### `open:flex`, not `flex`
+ *
+ * A closed `<dialog>` is hidden by a UA rule that any
+ * `display: flex` of ours would beat — so the modal would render
+ * permanently, in the page flow, with no error. The layout is
+ * therefore behind Tailwind's `open:` variant, which is the
+ * `[open]` attribute the browser manages.
+ *
+ * ### The accessible name
+ *
+ * `heading` is required and is a string, not a `ReactNode`. A
+ * dialog with no name is announced as "dialog" and nothing else,
+ * which is what every hand-rolled modal in the inventory does.
+ */
+export const Modal = ({
+  children,
+  className,
+  footer,
+  heading,
+  headingLevel = 2,
+  isDismissable = true,
+  isVisible,
+  onClose,
+  size = "md",
+  ...dialogProps
+}: ModalProps): ReactNode => {
+  const dialogRef = useRef<HTMLDialogElement>(null)
+
+  const headingId = useUniqueId()
+
+  const Heading = `h${headingLevel}` as const
+
+  useEffect(() => {
+    const dialogElement = dialogRef.current
+
+    if (!dialogElement) {
+      return
+    }
+
+    // Guarded both ways. `showModal()` on an already-open dialog
+    // throws `InvalidStateError`, and `close()` on a closed one
+    // fires a spurious `close` event — either turns a re-render
+    // into a bug.
+    if (isVisible && !dialogElement.open) {
+      dialogElement.showModal()
+    }
+
+    if (!isVisible && dialogElement.open) {
+      dialogElement.close()
+    }
+  }, [isVisible])
+
+  useEffect(
+    () => (isVisible ? lockScrollBehind() : undefined),
+    [isVisible],
+  )
+
+  return (
+    /*
+     * The one suppression in this package, and the rule really is
+     * wrong here rather than inconvenient.
+     *
+     * `useKeyWithClickEvents` looks for a click handler on
+     * something a keyboard user cannot reach. This one is on the
+     * **backdrop** — which is not an element, has no keyboard
+     * equivalent to give it, and whose keyboard counterpart is the
+     * `onCancel` directly above: Escape, from the platform, which
+     * is the entire reason this is built on `<dialog>`. Biome
+     * cannot see `onCancel` as a keyboard route.
+     *
+     * Pairing the click with an `onKeyDown` to satisfy the rule
+     * would duplicate a close request the browser already routes
+     * correctly — including deciding which of two stacked dialogs
+     * it belongs to — which is a worse component in exchange for a
+     * green linter.
+     */
+    // biome-ignore lint/a11y/useKeyWithClickEvents: Escape is handled by `onCancel`, which this rule cannot see.
+    <dialog
+      {...dialogProps}
+      aria-labelledby={headingId}
+      className={toClassName(
+        // `m-auto` and `p-0` undo the UA stylesheet, which centres
+        // by margin and adds padding of its own.
+        "m-auto flex-col overflow-hidden rounded-lg border border-border-default bg-surface-overlay p-0 text-content-primary shadow-high backdrop:bg-scrim open:flex",
+        SIZE_CLASS[size],
+        className,
+      )}
+      onCancel={(cancelEvent) => {
+        // Escape. Cancelled rather than ignored when the dialog is
+        // not dismissable: letting the browser close it would
+        // leave `isVisible` true and the element shut, which is
+        // precisely the desync this component exists to prevent.
+        cancelEvent.preventDefault()
+
+        if (isDismissable) {
+          onClose()
+        }
+      }}
+      onClick={(clickEvent) => {
+        // The backdrop is not an element — a press on it targets
+        // the `<dialog>` itself, while a press on the content
+        // targets something inside. Comparing target to
+        // currentTarget is the whole test.
+        if (
+          isDismissable &&
+          clickEvent.target === clickEvent.currentTarget
+        ) {
+          onClose()
+        }
+      }}
+      ref={dialogRef}
+    >
+      <header className="flex shrink-0 items-start justify-between gap-3 border-b border-border-subtle p-4">
+        <Heading
+          className="font-semibold text-lg leading-tight"
+          id={headingId}
+        >
+          {heading}
+        </Heading>
+
+        {isDismissable ? (
+          <Button
+            appearance="ghost"
+            intent="neutral"
+            onClick={onClose}
+            size="sm"
+          >
+            Close
+          </Button>
+        ) : null}
+      </header>
+
+      <div className="min-h-0 flex-1 overflow-auto p-4">
+        {children}
+      </div>
+
+      {footer ? (
+        <footer className="flex shrink-0 flex-wrap justify-end gap-2 border-t border-border-subtle p-4">
+          {footer}
+        </footer>
+      ) : null}
+    </dialog>
+  )
+}

package/src/Modal/lockScrollBehind.ts

@@ -0,0 +1,59 @@
+/**
+ * The one thing `showModal()` does not do.
+ *
+ * A native modal makes everything behind it `inert` — unclickable,
+ * untabbable, invisible to a screen reader — and then lets you
+ * scroll it anyway. On a phone that reads as the dialog sliding
+ * around; on a long page it loses the user's place entirely.
+ *
+ * Counted rather than boolean, because nested dialogs are legal
+ * (`showModal()` stacks in the top layer) and a naive
+ * lock/unlock pair has the inner one's cleanup unlock the page
+ * while the outer is still open. The original value is captured
+ * on the *first* lock, so restoring is a restore rather than a
+ * guess at what an app's own stylesheet wanted.
+ *
+ * Not a React hook: this is process-wide state, and two components
+ * sharing it through module scope is the honest expression of
+ * that. `Modal` calls it from an effect and returns the release as
+ * the cleanup.
+ */
+
+let lockCount = 0
+
+let previousOverflow = ""
+
+export const lockScrollBehind = (): (() => void) => {
+  if (typeof document === "undefined") {
+    return () => {}
+  }
+
+  const { documentElement } = document
+
+  if (lockCount === 0) {
+    previousOverflow = documentElement.style.overflow
+
+    documentElement.style.overflow = "hidden"
+  }
+
+  lockCount += 1
+
+  let isReleased = false
+
+  return () => {
+    // Idempotent, because React 19's StrictMode runs an effect's
+    // cleanup twice and a double decrement would unlock the page
+    // under a dialog that is still open.
+    if (isReleased) {
+      return
+    }
+
+    isReleased = true
+
+    lockCount -= 1
+
+    if (lockCount === 0) {
+      documentElement.style.overflow = previousOverflow
+    }
+  }
+}

package/src/Popover/Popover.mdx

@@ -0,0 +1,102 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as PopoverStories from "./Popover.stories";
+
+<Meta of={PopoverStories} />
+
+# Popover
+
+Replaces mux-magic's `@radix-ui/react-popover` re-export — a rewrite rather than a swap,
+for one reason: **Radix owns `open`.** Wrapping it leaves `useVisibility` and Radix both
+believing they hold the state, which is the conflict the whole state layer exists to
+avoid.
+
+<Canvas of={PopoverStories.Default} />
+
+## Props
+
+<Controls />
+
+## floating-ui, and only for what it is good at
+
+`@floating-ui/react` is the layer Radix, Base UI, and Ark UI are all *built on*, and it is
+**controlled by construction**: you pass state in and it never stores any.
+
+```tsx
+useFloating({
+  open: isVisible,          // ← read-only. Charcuterie stays the owner.
+  onOpenChange: (isNext) => { if (!isNext) hide() },
+  middleware: [offset(8), flip(), shift({ padding: 8 })],
+  strategy: "fixed",
+})
+```
+
+It is used for the three things only it can do — collision handling, a real dismiss layer,
+and focus management. The top layer, the positioning strategy, and the ARIA wiring come
+from the platform and from `useRole`.
+
+Passing `open:` *into* floating-ui does not violate the `is`/`has` rule; the adapter
+boundary is exactly the carve-out that rule already has
+([decision](../../../docs/decisions/2026-07-29-is-has-rule-has-no-external-api-carve-out.md)).
+
+## `popover="manual"`, not a portal and not `auto`
+
+`popover="manual"` puts the panel in the **top layer** — no `z-index` contest, and no
+`overflow: hidden` ancestor clipping it. That is what a portal is normally reached for,
+and unlike a portal the element **stays where it is in the DOM**:
+
+> `canvas.getByRole("dialog")` finds this panel. It would not find a portalled one, and
+> every story here would have to reach for `screen` and lose its scoping. Same argument as
+> `Modal`, one layer down.
+
+`manual` rather than `auto` is the state-ownership decision again. `auto` brings the UA's
+own light-dismiss, which closes the element by itself and leaves `isVisible` true.
+`useDismiss` does the same job through our callback, so Charcuterie stays the only thing
+that decides.
+
+### Two UA defaults that must be undone
+
+`[popover]` ships `position: fixed; inset: 0; margin: auto`. Left in place it centres the
+panel in the viewport and fights every coordinate floating-ui computes — and it looks
+deliberate, which is the worst kind of bug. `inset-auto m-0` puts it back, and
+`strategy: "fixed"` keeps the numbers viewport-relative like the top layer itself.
+`AllVariants` asserts the panel is positioned at all, for exactly this reason.
+
+<Canvas of={PopoverStories.AllVariants} />
+
+## The name is required
+
+`role="dialog"` takes **no accessible name from its content**, so `heading` is required and
+becomes `aria-label`. An unnamed panel is announced as "dialog" and is unfindable by
+`getByRole("dialog", { name })` — the same trap `Spinner` walked into in M3 with
+`role="status"`
+([decision](../../../docs/decisions/2026-07-29-status-regions-carry-an-aria-label.md)).
+
+`aria-expanded`, `aria-haspopup`, and `aria-controls` on the trigger, and `id` and `role`
+on the panel, all come from `useRole` — one source for both ends of the link, because a
+hand-written `aria-controls` pointing at an id that moved renders identically and
+announces nothing.
+
+<Canvas of={PopoverStories.AllStates} />
+
+## The trigger is cloned, not wrapped
+
+`useClonedChild` injects the reference props and the ref into whatever button you already
+have. An extra `<div>` around it is how a toolbar's layout quietly changes, and it is why
+this is the pattern v1 chose and M2 ported.
+
+## Escape *is* pressable here
+
+Unlike `Modal`'s. `useDismiss` listens for a keydown rather than relying on a UA default
+action, and a synthetic keydown is a real keydown as far as a listener is concerned — so
+the `Interactive` story presses it for real, and also dismisses by pressing the page
+behind the panel.
+
+<Canvas of={PopoverStories.Responsive} />
+
+A popover is positioned against the **viewport**, so `Responsive` is three triggers pinned
+to three edges rather than a `ContainerBoard`. The assertion is that the panel stays
+inside the viewport — which is all `flip` and `shift` actually promise; asserting a
+specific side would be asserting the collision did not happen.
+
+<Canvas of={PopoverStories.Interactive} />

package/src/Popover/Popover.stories.tsx

@@ -0,0 +1,247 @@
+import { useVisibility } from "@charcuterie/logic"
+import type { Placement } from "@floating-ui/react"
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+
+import { placementArgType } from "../argTypes.storyHelpers.ts"
+import { Badge } from "../Badge/Badge.tsx"
+import { Button } from "../Button/Button.tsx"
+import {
+  StoryCell,
+  StoryGrid,
+  StoryRow,
+} from "../board.storyHelpers.tsx"
+import { Popover } from "./Popover.tsx"
+
+const meta = {
+  title: "Components/Popover",
+  component: Popover,
+  parameters: { layout: "padded" },
+  argTypes: { placement: placementArgType },
+  args: { placement: "bottom-start" },
+} satisfies Meta<typeof Popover>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * One `useVisibility` per popover, and the trigger is a real
+ * `Button` that the component clones rather than wraps.
+ */
+const PopoverDemo = ({
+  children,
+  heading,
+  placement,
+  triggerLabel,
+}: {
+  children?: ReactNode
+  heading: string
+  placement?: Placement
+  triggerLabel: string
+}): ReactNode => {
+  const { hide, isVisible, toggle } = useVisibility()
+
+  return (
+    <Popover
+      heading={heading}
+      isVisible={isVisible}
+      onDismiss={hide}
+      placement={placement}
+      trigger={
+        <Button
+          appearance="soft"
+          onClick={toggle}
+          size="sm"
+        >
+          {triggerLabel}
+        </Button>
+      }
+    >
+      {children ?? (
+        <div className="flex flex-col gap-2">
+          <p className="text-content-secondary">
+            Filters apply to this bay only.
+          </p>
+
+          <Button appearance="outline" size="sm">
+            Clear filters
+          </Button>
+        </div>
+      )}
+    </Popover>
+  )
+}
+
+export const Default: Story = {
+  args: {
+    children: null,
+    heading: "Filters",
+    isVisible: false,
+    onDismiss: () => {},
+    trigger: <Button>Filters</Button>,
+  },
+  render: () => (
+    <PopoverDemo heading="Filters" triggerLabel="Filters" />
+  ),
+}
+
+const PLACEMENTS: Placement[] = [
+  "top",
+  "bottom-start",
+  "right",
+  "left-end",
+]
+
+export const AllVariants: Story = {
+  args: {
+    children: null,
+    heading: "Filters",
+    isVisible: false,
+    onDismiss: () => {},
+    trigger: <Button>Filters</Button>,
+  },
+  render: () => (
+    <StoryGrid columns={4}>
+      {PLACEMENTS.map((placement) => (
+        <StoryCell key={placement} label={placement}>
+          <PopoverDemo
+            heading={`Filters — ${placement}`}
+            placement={placement}
+            triggerLabel={`Open ${placement}`}
+          >
+            <p className="text-content-secondary">
+              Requested {placement}. `flip` and `shift` will
+              overrule it rather than let the panel leave
+              the viewport.
+            </p>
+          </PopoverDemo>
+        </StoryCell>
+      ))}
+    </StoryGrid>
+  ),
+}
+
+export const AllStates: Story = {
+  args: {
+    children: null,
+    heading: "Filters",
+    isVisible: false,
+    onDismiss: () => {},
+    trigger: <Button>Filters</Button>,
+  },
+  render: () => (
+    <StoryRow>
+      <PopoverDemo
+        heading="Bay 3 filters"
+        triggerLabel="Interactive content"
+      />
+
+      <PopoverDemo
+        heading="Read error detail"
+        triggerLabel="Text only"
+      >
+        <p className="text-content-secondary">
+          MakeMKV reported a read error on title 4 at
+          00:41:12. Eight of nine titles completed.
+        </p>
+      </PopoverDemo>
+
+      <PopoverDemo
+        heading="Bay 3 status"
+        triggerLabel="With a badge"
+      >
+        <div className="flex flex-col gap-2">
+          <Badge intent="warning" size="sm">
+            degraded
+          </Badge>
+
+          <p className="text-content-secondary">
+            One read retry in the last hour.
+          </p>
+        </div>
+      </PopoverDemo>
+    </StoryRow>
+  ),
+}
+
+/**
+ * The board a container query cannot help with, and for the
+ * opposite reason to `Modal`'s. A popover is positioned against the
+ * **viewport** — `flip` and `shift` measure collisions with it — so
+ * what varies is where the trigger sits on screen, not how wide its
+ * container is. Three triggers pinned to three edges is the honest
+ * instrument.
+ */
+export const Responsive: Story = {
+  args: {
+    children: null,
+    heading: "Filters",
+    isVisible: false,
+    onDismiss: () => {},
+    trigger: <Button>Filters</Button>,
+  },
+  render: () => (
+    <div className="flex min-h-64 flex-col justify-between gap-4">
+      <div className="flex justify-between">
+        <PopoverDemo
+          heading="Filters — top start"
+          placement="top"
+          triggerLabel="Top edge, asks for top"
+        >
+          <p className="text-content-secondary">
+            Asked for `top`, has no room, so `flip` sends it
+            down.
+          </p>
+        </PopoverDemo>
+
+        <PopoverDemo
+          heading="Filters — top end"
+          placement="right"
+          triggerLabel="Right edge, asks for right"
+        >
+          <p className="text-content-secondary">
+            Asked for `right`, has no room, so `shift` and
+            `flip` bring it back inside.
+          </p>
+        </PopoverDemo>
+      </div>
+
+      <PopoverDemo
+        heading="Filters — bottom"
+        placement="bottom"
+        triggerLabel="Bottom, asks for bottom"
+      >
+        <p className="text-content-secondary">
+          Room below, so it gets what it asked for.
+        </p>
+      </PopoverDemo>
+    </div>
+  ),
+}
+
+/**
+ * The dismiss layer, driven. Outside press and Escape both route
+ * through `useDismiss` → `onDismiss` → `hide()`, so the panel is
+ * never closed by anything except the state saying so.
+ *
+ * Escape *is* pressable here, unlike `Modal`'s: `useDismiss`
+ * listens for a keydown rather than relying on a UA default
+ * action, and a synthetic keydown is a real keydown as far as a
+ * listener is concerned.
+ */
+export const Interactive: Story = {
+  args: {
+    children: null,
+    heading: "Filters",
+    isVisible: false,
+    onDismiss: () => {},
+    trigger: <Button>Filters</Button>,
+  },
+  render: () => (
+    <PopoverDemo
+      heading="Bay 3 filters"
+      triggerLabel="Filters"
+    />
+  ),
+}