@charcuterie/ui 0.1.1 → 0.2.0

package/src/Field/Field.mdx

@@ -0,0 +1,74 @@
+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. mux-magic's `FieldLabel` renders a `<label>` with **no `htmlFor`** —
+which looks correct, reads correctly to a sighted user, and gives a screen reader an
+unnamed textbox.
+
+<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} />
+
+## `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.

package/src/Field/Field.stories.tsx

@@ -0,0 +1,144 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import { Select } from "../Select/Select.tsx"
+import { Field } from "./Field.tsx"
+
+const TEXT_INPUT_CLASS =
+  "w-full rounded-md border border-border-default bg-surface-raised px-3 py-2 text-content-primary text-sm focus-visible:outline-solid focus-visible:outline-(length:--focus-ring-width) focus-visible:outline-offset-(--focus-ring-offset) focus-visible:outline-focus-ring"
+
+const meta = {
+  title: "Components/Field",
+  component: Field,
+  parameters: { layout: "padded" },
+  args: {
+    isRequired: false,
+    label: "Output directory",
+  },
+} satisfies Meta<typeof Field>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    children: (
+      <input className={TEXT_INPUT_CLASS} type="text" />
+    ),
+    description: "Where finished rips are moved.",
+    label: "Output directory",
+  },
+}
+
+/**
+ * The control is a slot, not a hardcoded `<input>` — `Select` goes
+ * in the same hole, and so does an app's own control. The `id`,
+ * `aria-describedby`, `aria-invalid`, and `required` are cloned onto
+ * whatever is passed.
+ */
+export const AllVariants: Story = {
+  args: {
+    children: (
+      <input className={TEXT_INPUT_CLASS} type="text" />
+    ),
+    label: "Output directory",
+  },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell label="text input">
+        <Field label="Output directory">
+          <input className={TEXT_INPUT_CLASS} type="text" />
+        </Field>
+      </StoryCell>
+
+      <StoryCell label="select">
+        <Field label="Rip profile">
+          <Select
+            options={[
+              { label: "Lossless", value: "lossless" },
+              { label: "Compressed", value: "compressed" },
+            ]}
+          />
+        </Field>
+      </StoryCell>
+
+      <StoryCell label="with description">
+        <Field
+          description="Where finished rips are moved."
+          label="Archive path"
+        >
+          <input className={TEXT_INPUT_CLASS} type="text" />
+        </Field>
+      </StoryCell>
+
+      <StoryCell label="required">
+        <Field isRequired label="Disc label">
+          <input className={TEXT_INPUT_CLASS} type="text" />
+        </Field>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * `error` is the only source of invalidity — there is no separate
+ * `isInvalid`, because two sources for one fact is how a control
+ * ends up `aria-invalid="true"` with nothing saying why.
+ *
+ * With both a description and an error, `aria-describedby` names
+ * them in that order. A screen reader reads the list in sequence,
+ * and the two sentences are not interchangeable.
+ */
+export const AllStates: Story = {
+  args: {
+    children: (
+      <input className={TEXT_INPUT_CLASS} type="text" />
+    ),
+    label: "Output directory",
+  },
+  render: () => (
+    <StoryGrid columns={3}>
+      <StoryCell label="valid">
+        <Field label="Bay name">
+          <input
+            className={TEXT_INPUT_CLASS}
+            defaultValue="Bay 3"
+            type="text"
+          />
+        </Field>
+      </StoryCell>
+
+      <StoryCell label="invalid">
+        <Field
+          error="That path is not writable."
+          label="Scratch path"
+        >
+          <input
+            className={TEXT_INPUT_CLASS}
+            defaultValue="/mnt/readonly"
+            type="text"
+          />
+        </Field>
+      </StoryCell>
+
+      <StoryCell label="described and invalid">
+        <Field
+          description="Absolute paths only."
+          error="That path is not writable."
+          isRequired
+          label="Archive path"
+        >
+          <input
+            className={TEXT_INPUT_CLASS}
+            defaultValue="mnt/archive"
+            type="text"
+          />
+        </Field>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}

package/src/Field/Field.test.tsx

@@ -0,0 +1,142 @@
+import { composeStories } from "@storybook/react"
+import { expect } 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 "./Field.stories.tsx"
+
+const { AllStates, AllVariants, Default } =
+  composeStories(stories)
+
+test("the label names the control it points at", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  // The whole point of the component in one query: the control is
+  // findable by the *label's* text, which is only true if `htmlFor`
+  // and the control's `id` agree. mux-magic's `FieldLabel` renders
+  // a `<label>` with no `htmlFor` at all — it looks right, reads
+  // right to a sighted user, and gives this query nothing.
+  const control = expectAgentDrivable(canvas, {
+    name: "Output directory",
+    role: "textbox",
+  })
+
+  await expect(control).toHaveAttribute("id")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("a description is announced with the control", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const control = expectAgentDrivable(canvas, {
+    name: "Output directory",
+    role: "textbox",
+  })
+
+  const describedBy = control.getAttribute(
+    "aria-describedby",
+  )
+
+  await expect(describedBy).not.toBeNull()
+
+  await expect(
+    document.getElementById(describedBy ?? ""),
+  ).toHaveTextContent("Where finished rips are moved.")
+})
+
+test("the slot takes a Select as readily as an input", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllVariants)
+
+  // A native `<select>` reports `role="combobox"`, and it is named
+  // by the same cloned `id`. The slot does not know what it is
+  // holding, which is the contract.
+  expectAgentDrivable(canvas, {
+    name: "Rip profile",
+    role: "combobox",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("`required` is spelled twice, on purpose", async () => {
+  const { canvas } = await mountStory(AllVariants)
+
+  const control = expectAgentDrivable(canvas, {
+    name: "Disc label",
+    role: "textbox",
+  })
+
+  // `required` is the constraint the browser validates;
+  // `aria-required` is the one it announces on a control the browser
+  // does not validate. They are not redundant, and a component that
+  // sets only the first is silent on a composite widget.
+  await expect(control).toBeRequired()
+
+  await expect(control).toHaveAttribute(
+    "aria-required",
+    "true",
+  )
+})
+
+test("an error is the only source of invalidity", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  // Valid: nothing claims otherwise.
+  await expect(
+    expectAgentDrivable(canvas, {
+      name: "Bay name",
+      role: "textbox",
+    }),
+  ).not.toHaveAttribute("aria-invalid")
+
+  const invalid = expectAgentDrivable(canvas, {
+    name: "Scratch path",
+    role: "textbox",
+  })
+
+  await expect(invalid).toHaveAttribute(
+    "aria-invalid",
+    "true",
+  )
+
+  await expect(
+    document.getElementById(
+      invalid.getAttribute("aria-describedby") ?? "",
+    ),
+  ).toHaveTextContent("That path is not writable.")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * Order inside `aria-describedby` is behaviour, not formatting. A
+ * screen reader reads the list in sequence, and "absolute paths only
+ * — that path is not writable" is a different sentence from its
+ * reverse. Nothing but the order of one array enforces it.
+ */
+test("description is described before error", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  const control = expectAgentDrivable(canvas, {
+    name: "Archive path",
+    role: "textbox",
+  })
+
+  const [descriptionId, errorId] = (
+    control.getAttribute("aria-describedby") ?? ""
+  ).split(" ")
+
+  await expect(
+    document.getElementById(descriptionId ?? ""),
+  ).toHaveTextContent("Absolute paths only.")
+
+  await expect(
+    document.getElementById(errorId ?? ""),
+  ).toHaveTextContent("That path is not writable.")
+})

package/src/Field/Field.tsx

@@ -0,0 +1,163 @@
+import {
+  useClonedChild,
+  useUniqueId,
+} from "@charcuterie/logic"
+import type { ReactElement, ReactNode } from "react"
+
+import { toClassName } from "../toClassName.ts"
+
+export type FieldProps = {
+  /**
+   * The control. **Cloned, not wrapped** — the same slot contract
+   * as `Popover`'s trigger, so a `Field` can go around an `<input>`,
+   * a `<textarea>`, a `Select`, or an app's own control without
+   * changing that control's layout.
+   */
+  children: ReactElement
+  className?: string
+  /**
+   * Standing help — units, a format, a warning about what the value
+   * does. Announced with the control, before any error.
+   */
+  description?: ReactNode
+  /**
+   * Present means invalid. There is no separate `isInvalid`, because
+   * two sources 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.
+   */
+  error?: ReactNode
+  isRequired?: boolean
+  label: ReactNode
+}
+
+/**
+ * Sixteen files in the fleet spell a label, a control, and a hint,
+ * and no two spell the wiring the same way. `FieldLabel` in
+ * mux-magic renders a `<label>` with no `htmlFor` at all — which
+ * looks correct, reads correctly to a sighted user, and gives a
+ * screen reader an unnamed textbox.
+ *
+ * ### The ids are static, and that is why `createLinkedIds` is not here
+ *
+ * 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 of them 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**, which is worth saying plainly
+ * rather than manufacturing a use for. It is the one state kind the
+ * component layer has never needed.
+ *
+ * ### Order matters inside `aria-describedby`
+ *
+ * Description first, error second. A screen reader reads the list in
+ * order, and "millisecondsonly — required" is a different sentence
+ * from "required — milliseconds only". Nothing enforces this but the
+ * order of the array below, which is why it is not built from an
+ * object.
+ *
+ * ### The error is described, not announced
+ *
+ * No `role="alert"` and no live region here, 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 elsewhere. A form that fails on submit should say so
+ * once, at the top, with the `Alert` this library already ships —
+ * and then the user tabs into the field and hears the specific
+ * reason.
+ */
+export const Field = ({
+  children,
+  className,
+  description,
+  error,
+  isRequired = false,
+  label,
+}: FieldProps): ReactNode => {
+  const baseId = useUniqueId()
+
+  const controlId = `${baseId}-control`
+
+  const descriptionId = `${baseId}-description`
+
+  const errorId = `${baseId}-error`
+
+  const describedBy = [
+    description === undefined ? null : descriptionId,
+    error === undefined ? null : errorId,
+  ]
+    .filter(Boolean)
+    .join(" ")
+
+  const clonedControl = useClonedChild(children, {
+    "aria-describedby":
+      describedBy === "" ? undefined : describedBy,
+    // `aria-invalid` is derived from the error's presence, never
+    // passed. A control marked invalid with no described reason is
+    // a screen reader saying "invalid" and stopping.
+    "aria-invalid": error === undefined ? undefined : true,
+    // Both, and they are not redundant: `required` is the
+    // constraint the browser validates and `aria-required` is the
+    // one it announces on a control the browser does not validate
+    // — a `role="combobox"`, or anything composite.
+    "aria-required": isRequired || undefined,
+    id: controlId,
+    required: isRequired || undefined,
+  })
+
+  return (
+    <div
+      className={toClassName(
+        "flex flex-col gap-1.5",
+        className,
+      )}
+    >
+      <label
+        className="font-medium text-content-primary text-sm"
+        htmlFor={controlId}
+      >
+        {label}
+
+        {isRequired ? (
+          <span
+            // Decoration beside a real `aria-required`. An asterisk
+            // announced as "asterisk" is noise; announced as
+            // nothing, with the control already saying "required",
+            // is correct.
+            aria-hidden="true"
+            className="ms-1 text-intent-danger-content"
+          >
+            *
+          </span>
+        ) : null}
+      </label>
+
+      {clonedControl}
+
+      {description === undefined ? null : (
+        <p
+          className="text-content-secondary text-xs"
+          id={descriptionId}
+        >
+          {description}
+        </p>
+      )}
+
+      {error === undefined ? null : (
+        <p
+          className="text-intent-danger-content text-xs"
+          id={errorId}
+        >
+          {error}
+        </p>
+      )}
+    </div>
+  )
+}

package/src/FileDropZone/FileDropZone.mdx

@@ -0,0 +1,78 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as FileDropZoneStories from "./FileDropZone.stories";
+
+<Meta of={FileDropZoneStories} />
+
+# FileDropZone
+
+The one drag target in the fleet is gallery-downloader's, and it **gets the hard part
+right** — credit where it is due, and the fix is reproduced here.
+
+<Canvas of={FileDropZoneStories.Default} />
+
+## Props
+
+<Controls />
+
+## 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
+- the drop handlers are an **enhancement** on a control that already works without them
+
+That ordering is the entire design. Building the drop zone first and bolting on an "or
+browse" link is how the fleet's version ended up with an `alert()` as its error channel and
+no keyboard path at all.
+
+`sr-only` rather than `display: none` — the clip-rect technique keeps the element focusable,
+which is the whole point of it being there.
+
+<Canvas of={FileDropZoneStories.AllVariants} />
+
+## The `dragDepth` counter, kept
+
+`dragenter` and `dragleave` fire once per **element** the pointer crosses, not once per
+zone. A plain boolean turns the highlight off halfway across the zone and it strobes:
+
+```js
+let dragDepth = 0
+
+function handlePageDragEnter() { dragDepth++;  if (dragDepth === 1) …on()  }
+function handlePageDragLeave() { dragDepth--;  if (dragDepth === 0) …off() }
+```
+
+That is gallery-downloader's, and it is correct. It lives in a ref here rather than in state,
+because 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 avoids.
+
+## `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 — and
+gallery-downloader's page is built entirely around `dataTransfer.getData("text")`, never
+looking at `.files` at all.
+
+`onDropText` is here rather than being someone's follow-up for exactly that reason: the one
+consumer this component has wants the text path, not the file path.
+
+<Canvas of={FileDropZoneStories.AllStates} />
+
+## The input is cleared after every pick
+
+A file input keeps its value, so choosing the *same* file twice is not a change and the
+handler never runs. It reads as "it ignored me", and it is the oldest bug in this control.
+
+<Canvas of={FileDropZoneStories.Interactive} />