@charcuterie/ui 0.1.1 → 1.0.0

package/src/FileDropZone/FileDropZone.test.tsx

@@ -0,0 +1,230 @@
+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 * as stories from "./FileDropZone.stories.tsx"
+
+const { AllStates, AllVariants, Default, Interactive } =
+  composeStories(stories)
+
+/**
+ * There is **no keyboard gesture for drag-and-drop**, and WCAG 2.5.7
+ * (AA since 2.2) requires a single-pointer alternative for any
+ * dragging movement. The honest one has existed since 1995: a real
+ * `<input type="file">`.
+ *
+ * So the zone is a `<label>` around an input, and the drop handlers
+ * are an enhancement on a control that already works without them.
+ * The fleet's one drag target — gallery-downloader's page — has no
+ * keyboard path at all.
+ */
+/**
+ * **The one component in this library that cannot use
+ * `expectAgentDrivable`, and the reason is worth the space.**
+ *
+ * `<input type="file">` — the accessible, keyboard-operable answer,
+ * the whole point of the design above — has **no ARIA role**.
+ * HTML-AAM defines none, so testing-library's role computation
+ * matches it to nothing and `getByRole("button")` returns zero
+ * elements.
+ *
+ * Browsers disagree with the specification and with each other:
+ * Chrome exposes it as a button in its accessibility tree, and
+ * **Playwright's own role engine maps it to `button`** — so
+ * `page.getByRole("button", { name })` finds it in a real agent run
+ * while `canvas.getByRole` cannot find it here.
+ *
+ * That is a genuine hole in this library's central claim, and it is
+ * a hole in the platform rather than in the component: the *most*
+ * accessible file control is the one the role model has no name for.
+ * `getByLabelText` is the honest query — and it is also what
+ * `page.getByLabel(…).setInputFiles(…)` does, which is how an agent
+ * drives this in practice.
+ */
+test("the zone is a real file input, reachable and named", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  const input = canvas.getByLabelText(
+    "Drop a disc image here",
+  )
+
+  await expect(input.tagName).toBe("INPUT")
+
+  await expect(input).toHaveAttribute("type", "file")
+
+  // Reachable with Tab. `sr-only` is the clip-rect technique, which
+  // keeps an element focusable — `display: none` would not.
+  await expect(input.tabIndex).toBeGreaterThanOrEqual(0)
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("`accept` and `multiple` reach the input", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllVariants)
+
+  await expect(
+    canvas.getByLabelText("Drop subtitle files"),
+  ).toHaveAttribute("multiple")
+
+  await expect(
+    canvas.getByLabelText("Drop a subtitle track"),
+  ).toHaveAttribute("accept", ".srt,.ass")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("a disabled zone disables its input", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  await expect(
+    canvas.getByLabelText("Drop a disabled image"),
+  ).toBeDisabled()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("choosing a file through the picker reports it", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const input = canvas.getByLabelText(
+    "Drop files or a link",
+  ) as HTMLInputElement
+
+  await userEvent.upload(
+    input,
+    new File(["disc"], "blade-runner.iso", {
+      type: "application/octet-stream",
+    }),
+  )
+
+  await waitFor(() => {
+    expect(
+      canvas.getByText("blade-runner.iso"),
+    ).toBeInTheDocument()
+  })
+})
+
+/**
+ * A file input keeps its value, so picking the *same* file twice is
+ * not a change and the handler never runs — which reads as "it
+ * ignored me" and is the oldest bug in this control. The input is
+ * cleared after every pick.
+ */
+test("the same file can be chosen twice", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const input = canvas.getByLabelText(
+    "Drop files or a link",
+  ) as HTMLInputElement
+
+  const file = new File(["disc"], "alien.iso", {
+    type: "application/octet-stream",
+  })
+
+  await userEvent.upload(input, file)
+
+  await waitFor(() => {
+    expect(
+      canvas.getByText("alien.iso"),
+    ).toBeInTheDocument()
+  })
+
+  await expect(input.value).toBe("")
+
+  await userEvent.upload(input, file)
+
+  await waitFor(() => {
+    expect(
+      canvas.getByText("alien.iso"),
+    ).toBeInTheDocument()
+  })
+})
+
+/**
+ * Dragging a link gives `text/plain` and an **empty** `files` list.
+ * A zone that only reads `.files` silently ignores the single most
+ * common thing a user drags into a downloader.
+ */
+test("a dropped link reports as text", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const zone = canvas
+    .getByLabelText("Drop files or a link")
+    .closest("label")
+
+  const dataTransfer = new DataTransfer()
+
+  dataTransfer.setData(
+    "text",
+    "https://example.test/gallery/42",
+  )
+
+  // `dragover` first, and its default action is to **reject** the
+  // drop — without `preventDefault` the `drop` below never fires at
+  // all. Nothing errors; the zone just looks broken.
+  zone?.dispatchEvent(
+    new DragEvent("dragover", {
+      bubbles: true,
+      cancelable: true,
+      dataTransfer,
+    }),
+  )
+
+  zone?.dispatchEvent(
+    new DragEvent("drop", {
+      bubbles: true,
+      cancelable: true,
+      dataTransfer,
+    }),
+  )
+
+  await waitFor(() => {
+    expect(
+      canvas.getByText("https://example.test/gallery/42"),
+    ).toBeInTheDocument()
+  })
+})
+
+/**
+ * `dragenter` and `dragleave` fire once per **element** the pointer
+ * crosses, not once per zone — so a plain boolean turns the
+ * highlight off halfway across and it strobes.
+ * gallery-downloader's page keeps a `dragDepth` counter, which is
+ * the correct fix and is reproduced here.
+ */
+test("the highlight survives crossing a child element", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const zone = canvas
+    .getByLabelText("Drop a disc image here")
+    .closest("label") as HTMLLabelElement
+
+  const [child] = Array.from(zone.querySelectorAll("span"))
+
+  const dispatch = (type: string, target: Element) => {
+    target.dispatchEvent(
+      new DragEvent(type, {
+        bubbles: true,
+        cancelable: true,
+        dataTransfer: new DataTransfer(),
+      }),
+    )
+  }
+
+  dispatch("dragenter", zone)
+
+  const activeClass = zone.className
+
+  // Entering a child fires `dragenter` again *and* `dragleave` on
+  // the zone. Depth goes 1 → 2 → 1, so the highlight stays on.
+  dispatch("dragenter", child ?? zone)
+
+  dispatch("dragleave", zone)
+
+  await expect(zone.className).toBe(activeClass)
+})

package/src/FileDropZone/FileDropZone.tsx

@@ -0,0 +1,234 @@
+import { useUniqueId } from "@charcuterie/logic"
+import type { DragEvent, ReactNode } from "react"
+import { useRef, useState } from "react"
+
+import { toClassName } from "../toClassName.ts"
+
+export type FileDropZoneProps = {
+  /** An `accept` list, passed straight to the input. */
+  accept?: string
+  className?: string
+  /** Secondary line — the formats taken, a size cap. */
+  description?: ReactNode
+  isDisabled?: boolean
+  isMultiple?: boolean
+  /** The control's accessible name, and its visible prompt. */
+  label: string
+  onDropFiles: (files: File[]) => void
+  /**
+   * Dropped text, when there is any. A browser hands over a dragged
+   * link as `text/plain` and no files at all, which is what
+   * gallery-downloader's page is built entirely around — it takes
+   * `dataTransfer.getData("text")` and never looks at `.files`.
+   */
+  onDropText?: (text: string) => void
+}
+
+/**
+ * The one drag target in the fleet is gallery-downloader's, and it
+ * gets the hard part right: `dragenter`/`dragleave` fire once per
+ * *element* the pointer crosses, not once per zone, so a naive
+ * implementation flickers over every child — and that page keeps a
+ * `dragDepth` counter, which is the correct fix. It is reproduced
+ * below with credit.
+ *
+ * What it has no answer for is the part that cannot be fixed by
+ * counting:
+ *
+ * ### Dragging is pointer-only, so the zone is a label around an input
+ *
+ * There is **no keyboard gesture for drag-and-drop**. WCAG 2.5.7
+ * (AA since 2.2) requires a single-pointer alternative for any
+ * dragging movement, and the honest one has existed since 1995: a
+ * real `<input type="file">`. So this component is a `<label>`
+ * wrapping a visually-hidden input — the whole zone is the label's
+ * click target, Tab reaches the input, Space and Enter open the
+ * picker, and the drop handlers are an *enhancement* on top of a
+ * control that already works without them.
+ *
+ * That ordering is the entire design. Building the drop zone first
+ * and bolting on a "or browse" link is how the fleet's version ended
+ * up with an `alert()` as its error channel and no keyboard path at
+ * all.
+ *
+ * ### `dragover` must be prevented, and the reason is a footgun
+ *
+ * A browser's default for `dragover` is *reject the drop*. Not
+ * preventing it means `drop` never fires — nothing errors, the
+ * cursor shows a "no entry" sign, and the zone looks like it has a
+ * broken handler when it in fact has no handler running at all.
+ *
+ * ### It reports text as well as files
+ *
+ * Dragging a link gives you `text/plain` and an empty `files` list.
+ * A zone that only reads `.files` silently ignores the single most
+ * common thing a user drags into a downloader, which is why
+ * `onDropText` is here rather than being someone's follow-up.
+ */
+export const FileDropZone = ({
+  accept,
+  className,
+  description,
+  isDisabled = false,
+  isMultiple = false,
+  label,
+  onDropFiles,
+  onDropText,
+}: FileDropZoneProps): ReactNode => {
+  const baseId = useUniqueId()
+
+  const inputId = `${baseId}-input`
+
+  const labelId = `${baseId}-label`
+
+  const descriptionId = `${baseId}-description`
+
+  const [isDragActive, setIsDragActive] = useState(false)
+
+  /**
+   * The counter gallery-downloader's page already keeps, and the
+   * reason it has to exist: `dragenter` fires again for every child
+   * element the pointer crosses, and `dragleave` fires for the one
+   * it left — so a plain boolean turns off halfway across the zone
+   * and the highlight strobes.
+   *
+   * A ref rather than state: nothing renders from the depth itself,
+   * only from whether it is above zero, and a re-render per crossed
+   * child during a drag is exactly the jank this is avoiding.
+   */
+  const dragDepth = useRef(0)
+
+  const endDrag = () => {
+    dragDepth.current = 0
+
+    setIsDragActive(false)
+  }
+
+  const handleDrop = (
+    dropEvent: DragEvent<HTMLElement>,
+  ) => {
+    dropEvent.preventDefault()
+
+    endDrag()
+
+    if (isDisabled) {
+      return
+    }
+
+    const files = Array.from(dropEvent.dataTransfer.files)
+
+    if (files.length > 0) {
+      onDropFiles(isMultiple ? files : files.slice(0, 1))
+
+      return
+    }
+
+    const text = dropEvent.dataTransfer.getData("text")
+
+    if (text !== "") {
+      onDropText?.(text)
+    }
+  }
+
+  return (
+    <label
+      className={toClassName(
+        "flex cursor-pointer flex-col items-center gap-1 rounded-md border-2 border-border-default border-dashed p-6 text-center transition-colors duration-(--duration-fast) ease-standard",
+        isDragActive
+          ? "border-intent-accent-border bg-intent-accent-surface"
+          : "bg-surface-sunken hover:border-border-strong",
+        isDisabled &&
+          "cursor-not-allowed border-border-subtle text-content-disabled hover:border-border-subtle",
+        // The ring is on the label, driven by the input inside it —
+        // the input is what actually takes focus, and it is
+        // visually hidden, so a ring on the input paints nothing.
+        "focus-within:outline-solid focus-within:outline-(length:--focus-ring-width) focus-within:outline-offset-(--focus-ring-offset) focus-within:outline-focus-ring",
+        className,
+      )}
+      htmlFor={inputId}
+      onDragEnter={(dragEvent) => {
+        dragEvent.preventDefault()
+
+        dragDepth.current += 1
+
+        if (dragDepth.current === 1) {
+          setIsDragActive(true)
+        }
+      }}
+      onDragLeave={(dragEvent) => {
+        dragEvent.preventDefault()
+
+        dragDepth.current -= 1
+
+        if (dragDepth.current === 0) {
+          setIsDragActive(false)
+        }
+      }}
+      onDragOver={(dragEvent) => {
+        // Not optional. The default action for `dragover` is to
+        // reject the drop, so without this `onDrop` below never runs
+        // and the zone looks broken rather than unhandled.
+        dragEvent.preventDefault()
+      }}
+      onDrop={handleDrop}
+    >
+      <input
+        accept={accept}
+        // Named by the prompt **only**, and described by the rest.
+        //
+        // The whole zone is the `<label>` — that is what makes the
+        // six-rem target clickable — so its text content is the
+        // prompt *and* the description, and a `<label for>` names
+        // its control with all of it. The input's accessible name
+        // came out as "Drop a disc image hereISO or MKV, up to 50
+        // GB.", which is not a name, and which `getByLabelText` and
+        // an agent both fail to match.
+        //
+        // `aria-labelledby` overrides the implicit `<label>` naming
+        // without giving up the click target.
+        aria-describedby={
+          description === undefined
+            ? undefined
+            : descriptionId
+        }
+        aria-labelledby={labelId}
+        className="sr-only"
+        disabled={isDisabled}
+        id={inputId}
+        multiple={isMultiple}
+        onChange={(changeEvent) => {
+          const files = Array.from(
+            changeEvent.currentTarget.files ?? [],
+          )
+
+          if (files.length > 0) {
+            onDropFiles(files)
+          }
+
+          // Cleared so choosing the *same* file twice fires again.
+          // A file input keeps its value, so the second pick is not
+          // a change and the handler never runs — which reads as
+          // "it ignored me" and is the oldest bug in this control.
+          changeEvent.currentTarget.value = ""
+        }}
+        type="file"
+      />
+
+      <span
+        className="font-medium text-content-primary text-sm"
+        id={labelId}
+      >
+        {label}
+      </span>
+
+      {description === undefined ? null : (
+        <span
+          className="text-content-secondary text-xs"
+          id={descriptionId}
+        >
+          {description}
+        </span>
+      )}
+    </label>
+  )
+}

package/src/LogViewer/LogViewer.mdx

@@ -0,0 +1,123 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as LogViewerStories from "./LogViewer.stories";
+
+<Meta of={LogViewerStories} />
+
+# LogViewer
+
+Three repos render a scrolling log pane — mux-magic's `JobLogsDisclosure` and `StepLogs`,
+rip-deck's `LogModal` — and between them they have four defects this component exists not to
+have. The fifth below is not theirs: it is defect 1 coming back through the front door, in
+this component, found by the first app to consume it.
+
+<Canvas of={LogViewerStories.Default} />
+
+## Props
+
+<Controls />
+
+## 1. The auto-scroll that follows nothing
+
+```tsx
+useEffect(() => {
+  const pane = paneRef.current
+  if (pane) pane.scrollTop = pane.scrollHeight
+}, [])          // ← empty deps
+```
+
+That is mux-magic's, and it runs **once**, on mount, when the pane is empty and
+`scrollHeight` *is* `clientHeight`. Every line after it arrives below the fold.
+
+It reads as correct, it is the shape everyone writes, and the log simply never follows.
+
+## 2. Following that cannot be escaped
+
+The naive fix — scroll to the bottom on every render — is worse: a user scrolling back to
+read the line that mentioned an error is yanked to the end twice a second.
+
+Following has to be **pinned to the user's own position**. It turns off the moment they
+scroll away and back on when they return to the bottom, and there is a **Jump to latest**
+button for when they do not want to scroll all that way.
+
+The pin test allows a few pixels of slack, because a fractional device pixel ratio means
+`scrollTop + clientHeight` never lands exactly on `scrollHeight`. An equality test here
+un-pins the pane on a 125% display and on nothing else.
+
+<Canvas of={LogViewerStories.Interactive} />
+
+## 3. `data-log-id`
+
+mux-magic's pane carries one. It is a `data-testid` under a different name — a handle only
+the test suite can see — and `sourceRules.test.ts` bans the **practice**, not the spelling.
+The pane here is found by its `label`, which is the query Playwright makes.
+
+## 4. Announcing an hour of build output
+
+`role="log"` is the correct role and `aria-live` is **off** unless asked for. A live log
+emitting a line every 300 ms is a screen reader that cannot be interrupted and a user who
+cannot read anything else on the page.
+
+The accessible answer for a long-running job is a `LiveStatusIndicator` announcing *state*
+and a log that is there to be read when wanted. `isAnnounced` exists for the short case: a
+five-line result panel where the lines **are** the outcome.
+
+<Canvas of={LogViewerStories.AllVariants} />
+
+## 5. A pane measured before it has a box
+
+Defect 1 again, and the fix for it cannot see this one. `AccordionSection` renders its panel
+with `hidden` rather than unmounting it, deliberately — an unmounted panel loses a scroll
+position, a partially typed form, and any subscription its content opened, and the fleet's
+log panes are exactly that. A `hidden` subtree has **no layout**, so the mount effect reads
+`scrollHeight 0` and writes `scrollTop = 0`. Measured in mux-magic on a 60-line pane:
+
+```
+while collapsed : scrollTop 0   scrollHeight 0     clientHeight 0
+after expanding : scrollTop 0   scrollHeight 976   clientHeight 254
+```
+
+Neither `isFollowing` nor `lines` changes when the section is opened, so the effect never
+runs again and the log opens on its **first** line. That is this component's own `}, [])`
+bug, rebuilt out of two components whose individual decisions are both right, and invisible
+to both of their test suites — `LogViewer`'s mounted visible, `Accordion`'s holding content
+that never measures itself. mux-magic hit it as a consumer and worked around it downstream,
+in a `DisclosedLogViewer` that withheld the pane until the section had been opened once.
+That workaround is now deletable.
+
+A `ResizeObserver` on the pane, live only while following, is the fix. Not an
+`IntersectionObserver`: that answers "is it on screen", which is a different question with
+two wrong answers here — a pane below the fold on a long page is not intersecting and has
+perfectly good layout, and scrolling the page later would re-fire for no reason.
+`ResizeObserver` answers "does it have a box, and is that box still the same size", which is
+the precondition the measurement actually needs; per spec it does not fire at `observe()`
+time for an element that is not being rendered, so **gaining a box is the first callback**.
+
+It pays for itself twice: a window resize re-wraps the lines and changes what is at the
+bottom, and a following pane belongs at the new bottom.
+
+<Canvas of={LogViewerStories.InsideDisclosure} />
+
+## Not every boolean is a state kind
+
+`isFollowing` is `useState`, not `useVisibility`, and this is the first component in the
+library to say so out loud.
+
+The kinds in `@charcuterie/logic` earn their keep when state is **registered** (members join
+a group), **composed** (focus and selection disagreeing), or **shared** (a trigger and a
+panel at opposite ends of a tree). None of that is true here: one component reads one
+boolean it wrote itself.
+
+Reaching for `useVisibility` because it is also a boolean would make `isVisible` mean "is
+following", which is how a state layer stops meaning anything.
+
+## `maxLines`, not virtualization
+
+The plan floated an optional `@tanstack/react-virtual` peer. Dropping the oldest lines is
+what actually bounds the DOM, costs no dependency, and is what every one of these panes
+wanted anyway — nobody scrolls back through an hour of sector reads.
+
+Virtualization stays unbuilt until a consumer produces a log where 500 lines is not enough,
+which is the same rule that kept a bare `Listbox` out of `Select`.
+
+<Canvas of={LogViewerStories.AllStates} />