@charcuterie/ui 0.1.1 → 1.0.0

package/src/Field/Field.tsx

@@ -0,0 +1,212 @@
+import {
+  useClonedChild,
+  useUniqueId,
+} from "@charcuterie/logic"
+import type { ReactElement, ReactNode } from "react"
+
+import type { SlotProps } from "../slotProps.ts"
+import { mergeSlotProps } from "../slotProps.ts"
+import { toClassName } from "../toClassName.ts"
+
+export type FieldProps = SlotProps & {
+  /**
+   * 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.
+ *
+ * ### What mux-magic's `FieldLabel` actually gets wrong
+ *
+ * An earlier version of this docstring said it "renders a `<label>`
+ * with no `htmlFor` at all". **That is false** — 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`; the other eight either render no id at all or render
+ * a different one — `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>` that points at an id 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.
+ *
+ * ### 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.
+ *
+ * ### A slot is a pass-through
+ *
+ * A `Tooltip` between the field and its control is the obvious thing
+ * to write, and it is what mux-magic's `FieldLabel` does. Both
+ * components clone onto their one child, so everything below used to
+ * land on the `Tooltip` **component** and be dropped in silence —
+ * leaving the `<label htmlFor>` above pointing at nothing, which is
+ * precisely the defect this component was built to make impossible.
+ * `SlotProps` arriving from an outer slot is forwarded down, and
+ * `aria-describedby` is merged rather than replaced.
+ * `slotProps.ts` has the reasoning.
+ */
+export const Field = ({
+  children,
+  className,
+  description,
+  error,
+  isRequired = false,
+  label,
+  ...receivedSlotProps
+}: FieldProps): ReactNode => {
+  const baseId = useUniqueId()
+
+  /**
+   * A caller's own `id` wins, which is what makes a `Field` usable
+   * where the id has to be predictable — an autofill hint, a deep
+   * link, a server-rendered error summary linking to the control.
+   * `useUniqueId` is still called: hooks are unconditional, and it
+   * costs one counter read.
+   */
+  const controlId =
+    receivedSlotProps.id ?? `${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,
+    mergeSlotProps(receivedSlotProps, {
+      "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/Field/FieldGroup.tsx

@@ -0,0 +1,138 @@
+import { useUniqueId } from "@charcuterie/logic"
+import type { ReactNode } from "react"
+
+import { toClassName } from "../toClassName.ts"
+
+export type FieldGroupProps = {
+  /**
+   * The controls. **Rendered as-is, not cloned** — that is the whole
+   * difference from `Field`, and it is why this is a separate
+   * component rather than a boolean on that one.
+   */
+  children: ReactNode
+  className?: string
+  /** Standing help for the group as a whole. */
+  description?: ReactNode
+  /** Present means the group is invalid. */
+  error?: ReactNode
+  isRequired?: boolean
+  label: ReactNode
+}
+
+/**
+ * A label over **several** controls.
+ *
+ * `Field` mints one id and clones it onto one child, which is the
+ * right shape for a text input and the wrong shape the moment there
+ * are two of them: an `id` can only name one element, and a
+ * `<label htmlFor>` can only point at one. Six of mux-magic's sixteen
+ * field components are in that position — `RegexWithFlagsField`
+ * (pattern, flags, sample, and a checkbox), `NumberWithLookupField`
+ * (three inputs), `LanguageCodeField`, `LanguageCodesField`,
+ * `SubtitleTypesField` (a tag input beside a dropdown) and
+ * `RenameRegexField` (a row per rule) — and every one of them renders
+ * a `FieldLabel` whose `htmlFor` names, at best, one of them.
+ *
+ * ### `<fieldset>` and `<legend>`, not a `<label>`
+ *
+ * This is the one place in the library where `<fieldset>` is right.
+ * `AccordionSection` rejected it for its panel and said why — it is a
+ * *form-control grouping*, and dragging `<legend>` semantics onto
+ * prose is wrong. Here the content **is** a form-control grouping,
+ * so the element means what it says, `<legend>` names the group
+ * natively, and no `role="group"` and no `aria-labelledby` are
+ * needed.
+ *
+ * A `<label>` here would be the mux-magic defect deliberately: a
+ * label pointing at one control, or at none.
+ *
+ * ### What a group cannot carry
+ *
+ * `aria-invalid` has no group form — it belongs on the control that
+ * is actually invalid, and this component does not know which one
+ * that is. So `error` here is *described*, not *asserted*: it joins
+ * `aria-describedby` on the `<fieldset>`, which screen readers read
+ * as focus enters the group. A control inside that is itself invalid
+ * should say so itself, in its own `Field`.
+ *
+ * That is a real limitation and it is stated rather than papered
+ * over — the alternative was to clone `aria-invalid` onto every
+ * child, which marks the valid ones invalid.
+ */
+export const FieldGroup = ({
+  children,
+  className,
+  description,
+  error,
+  isRequired = false,
+  label,
+}: FieldGroupProps): ReactNode => {
+  const baseId = useUniqueId()
+
+  const descriptionId = `${baseId}-description`
+
+  const errorId = `${baseId}-error`
+
+  // Description first, error second, for the reason `Field` gives:
+  // a screen reader reads the list in order and the two sentences
+  // are not interchangeable.
+  const describedBy = [
+    description === undefined ? null : descriptionId,
+    error === undefined ? null : errorId,
+  ]
+    .filter(Boolean)
+    .join(" ")
+
+  return (
+    <fieldset
+      aria-describedby={
+        describedBy === "" ? undefined : describedBy
+      }
+      className={toClassName(
+        // A `<fieldset>` arrives with a border, an inline margin, a
+        // block padding, and `min-inline-size: min-content` — the
+        // last of which makes it refuse to shrink inside a flex or
+        // grid parent, which is the reason design systems avoid the
+        // element. All four are cleared here, once.
+        "m-0 flex min-w-0 flex-col gap-1.5 border-0 p-0",
+        className,
+      )}
+    >
+      <legend className="mb-1.5 p-0 font-medium text-content-primary text-sm">
+        {label}
+
+        {isRequired ? (
+          <span
+            // Decoration, as in `Field`. An asterisk announced as
+            // "asterisk" is noise; the controls inside carry their
+            // own `required`.
+            aria-hidden="true"
+            className="ms-1 text-intent-danger-content"
+          >
+            *
+          </span>
+        ) : null}
+      </legend>
+
+      {children}
+
+      {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>
+      )}
+    </fieldset>
+  )
+}

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} />

package/src/FileDropZone/FileDropZone.stories.tsx

@@ -0,0 +1,136 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import { FileDropZone } from "./FileDropZone.tsx"
+
+const noop = () => undefined
+
+const meta = {
+  title: "Components/FileDropZone",
+  component: FileDropZone,
+  parameters: { layout: "padded" },
+  args: {
+    isDisabled: false,
+    isMultiple: false,
+    label: "Drop a disc image here",
+    onDropFiles: noop,
+  },
+} satisfies Meta<typeof FileDropZone>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    description: "ISO or MKV, up to 50 GB.",
+    label: "Drop a disc image here",
+  },
+}
+
+export const AllVariants: Story = {
+  args: { label: "Drop a disc image here" },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell align="stretch" label="single file">
+        <FileDropZone
+          description="ISO or MKV, up to 50 GB."
+          label="Drop a disc image"
+          onDropFiles={noop}
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="multiple">
+        <FileDropZone
+          description="Several at once."
+          isMultiple
+          label="Drop subtitle files"
+          onDropFiles={noop}
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="accepting a type">
+        <FileDropZone
+          accept=".srt,.ass"
+          description="Subtitles only."
+          label="Drop a subtitle track"
+          onDropFiles={noop}
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="no description">
+        <FileDropZone
+          label="Drop anything"
+          onDropFiles={noop}
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+export const AllStates: Story = {
+  args: { label: "Drop a disc image here" },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell align="stretch" label="idle">
+        <FileDropZone
+          label="Drop an idle image"
+          onDropFiles={noop}
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="disabled">
+        <FileDropZone
+          description="A rip is already running."
+          isDisabled
+          label="Drop a disabled image"
+          onDropFiles={noop}
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Tab to it and press Enter — the file picker opens, which is the
+ * whole point: **there is no keyboard gesture for drag-and-drop**,
+ * so the zone is a `<label>` around a real `<input type="file">` and
+ * the drop handlers are an enhancement on top of a control that
+ * already works without them.
+ *
+ * Dragging a *link* reports through `onDropText`, because a browser
+ * hands over a dragged URL as `text/plain` with no files at all —
+ * which is what gallery-downloader's page is built entirely around.
+ */
+export const Interactive: Story = {
+  args: { label: "Drop a disc image here" },
+  render: function DropTarget() {
+    const [dropped, setDropped] = useState<string[]>([])
+
+    return (
+      <div className="flex flex-col gap-3">
+        <FileDropZone
+          description="Files, or a dragged link."
+          isMultiple
+          label="Drop files or a link"
+          onDropFiles={(files) => {
+            setDropped(files.map((file) => file.name))
+          }}
+          onDropText={(text) => {
+            setDropped([text])
+          }}
+        />
+
+        <ul className="list-none p-0 text-content-secondary text-sm">
+          {dropped.map((one) => (
+            <li key={one}>{one}</li>
+          ))}
+        </ul>
+      </div>
+    )
+  },
+}