@charcuterie/ui 0.2.0 → 1.0.0

package/src/Field/Field.tsx

@@ -4,9 +4,11 @@ import {
 } 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 = {
+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>`,
@@ -33,10 +35,32 @@ export type FieldProps = {
 
 /**
  * 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.
+ * 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
  *
@@ -72,6 +96,18 @@ export type FieldProps = {
  * 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,
@@ -80,10 +116,19 @@ export const Field = ({
   error,
   isRequired = false,
   label,
+  ...receivedSlotProps
 }: FieldProps): ReactNode => {
   const baseId = useUniqueId()
 
-  const controlId = `${baseId}-control`
+  /**
+   * 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`
 
@@ -96,21 +141,25 @@ export const Field = ({
     .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,
-  })
+  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

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/LogViewer/LogViewer.mdx

@@ -8,7 +8,8 @@ import * as LogViewerStories from "./LogViewer.stories";
 
 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.
+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} />
 
@@ -63,6 +64,40 @@ 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

package/src/LogViewer/LogViewer.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react"
 
+import { Accordion } from "../Accordion/Accordion.tsx"
 import {
   StoryCell,
   StoryGrid,
@@ -133,3 +134,36 @@ export const AllStates: Story = {
 export const Interactive: Story = {
   args: { label: "Bay 8 rip log", lines: LONG_LINES },
 }
+
+/**
+ * The pane mounted inside a **collapsed** `Accordion` section, which
+ * is how the fleet actually renders a log and is the one arrangement
+ * where following used to fail.
+ *
+ * `AccordionSection` renders its panel with `hidden`, deliberately,
+ * so the pane keeps its scroll position and its subscriptions across
+ * a collapse. A `hidden` subtree has no layout, so a pane that
+ * measures itself on mount measures `scrollHeight 0` — and neither
+ * `isFollowing` nor `lines` changes when the section is opened.
+ *
+ * Expand it: the log opens on its **last** line, not its first.
+ */
+export const InsideDisclosure: Story = {
+  args: { label: "Bay 9 rip log", lines: LONG_LINES },
+  render: () => (
+    <Accordion
+      items={[
+        {
+          content: (
+            <LogViewer
+              label="Bay 9 rip log"
+              lines={LONG_LINES}
+            />
+          ),
+          key: "logs",
+          label: "Bay 9 output",
+        },
+      ]}
+    />
+  ),
+}

package/src/LogViewer/LogViewer.test.tsx

@@ -7,8 +7,13 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./LogViewer.stories.tsx"
 
-const { AllStates, AllVariants, Default, Interactive } =
-  composeStories(stories)
+const {
+  AllStates,
+  AllVariants,
+  Default,
+  InsideDisclosure,
+  Interactive,
+} = composeStories(stories)
 
 test("the pane is named, and is a log", async () => {
   const { canvas, canvasElement } =
@@ -62,6 +67,64 @@ test("a full pane is scrolled to the bottom", async () => {
   })
 })
 
+/**
+ * The same defect, rebuilt out of two components that are each
+ * individually right — and the reason `LogViewer` watches its own box
+ * rather than trusting one mount measurement.
+ *
+ * `AccordionSection` renders `hidden` rather than unmounting, because
+ * the fleet's panels hold log panes and an unmounted panel loses its
+ * scroll position and its subscription. A `hidden` subtree has no
+ * layout box, so the mount effect reads `scrollHeight 0` and writes
+ * `scrollTop = 0` — and the effect's dependencies, `isFollowing` and
+ * the lines, are both unchanged by the reveal. 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
+ * ```
+ *
+ * mux-magic worked around it downstream, in `DisclosedLogViewer`, by
+ * not mounting the pane until the section had been opened once. This
+ * test is that workaround becoming deletable.
+ */
+test("a pane revealed by a disclosure follows the tail", async () => {
+  const { canvas } = await mountStory(InsideDisclosure)
+
+  // `hidden: true` because that is the whole precondition: the pane
+  // is in the accessibility tree's shadow, and in the layout tree not
+  // at all.
+  const pane = canvas.getByRole("log", {
+    hidden: true,
+    name: "Bay 9 rip log",
+  })
+
+  // Not a rhetorical assertion. If a future `AccordionSection`
+  // unmounts its panel instead, or stops using `hidden`, this test
+  // silently stops testing anything — so it fails here instead.
+  await expect(pane.scrollHeight).toBe(0)
+
+  expectAgentDrivable(canvas, {
+    name: "Bay 9 output",
+    role: "button",
+  }).click()
+
+  await waitFor(() => {
+    expect(pane.scrollHeight).toBeGreaterThan(
+      pane.clientHeight,
+    )
+  })
+
+  await waitFor(() => {
+    expect(
+      pane.scrollHeight -
+        pane.scrollTop -
+        pane.clientHeight,
+    ).toBeLessThan(4)
+  })
+})
+
 /**
  * Following is pinned to the user's own position. Scrolling back to
  * read the line that mentioned an error must not be undone twice a

package/src/LogViewer/LogViewer.tsx

@@ -35,7 +35,9 @@ export type LogViewerProps = {
  * Three repos render a scrolling log pane —
  * mux-magic's `JobLogsDisclosure` and `StepLogs`, rip-deck's
  * `LogModal` — and between them they have four defects that this
- * component exists to not have.
+ * component exists to not have. A fifth, below the effects, is not
+ * theirs: it is defect 1 coming back through the front door, in this
+ * component, found by the first app to consume it.
  *
  * ### 1. The one that follows nothing
  *
@@ -121,6 +123,70 @@ export const LogViewer = ({
     // for defect 1, and the dependency *is* the fix.
   }, [isFollowing, shownLines])
 
+  /**
+   * Defect 1 again, and the effect above cannot see it: **a pane can
+   * be measured before it has a box.**
+   *
+   * `AccordionSection` renders its panel with `hidden` rather than
+   * unmounting it, deliberately — "a panel that unmounts 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 effect above runs on mount
+   * with `scrollHeight 0` and writes `scrollTop = 0`, and then never
+   * runs again: neither `isFollowing` nor `shownLines` changes when
+   * the section is opened. 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
+   * ```
+   *
+   * 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 in its first week as a consumer and
+   * worked around it downstream, in a `DisclosedLogViewer` that
+   * withheld the pane until the section had been opened once. This is
+   * that workaround coming into the library so it can be deleted.
+   *
+   * ### Why the box and not the viewport
+   *
+   * An `IntersectionObserver` 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
+   * above 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, and that is the reveal.
+   *
+   * It pays for itself twice: a window resize re-wraps the lines and
+   * changes what is at the bottom, and a following pane should be at
+   * the new bottom rather than a few lines above it.
+   *
+   * Only while following. A user who scrolled up to read an error is
+   * not dragged back by resizing their window.
+   */
+  useEffect(() => {
+    const pane = paneRef.current
+
+    if (!pane || !isFollowing) {
+      return
+    }
+
+    const observer = new ResizeObserver(() => {
+      pane.scrollTop = pane.scrollHeight
+    })
+
+    observer.observe(pane)
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [isFollowing])
+
   return (
     <div
       className={toClassName(

package/src/Tooltip/Tooltip.tsx

@@ -17,9 +17,11 @@ import {
 } 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 = {
+export type TooltipProps = SlotProps & {
   /**
    * The control the tip describes. **Cloned, not wrapped** — the
    * same slot contract as `Popover`'s trigger.
@@ -83,6 +85,19 @@ export type TooltipProps = {
  * 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,
@@ -90,6 +105,7 @@ export const Tooltip = ({
   delay = 200,
   label,
   placement = "top",
+  ...receivedSlotProps
 }: TooltipProps): ReactNode => {
   const { isVisible, setIsVisible } = useVisibility()
 
@@ -121,10 +137,18 @@ export const Tooltip = ({
       useRole(context, { role: "tooltip" }),
     ])
 
-  const clonedTrigger = useClonedChild(children, {
-    ...getReferenceProps(),
-    ref: refs.setReference,
-  })
+  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 (
     <>

package/src/index.ts

@@ -68,6 +68,8 @@ export type {
 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"
@@ -145,6 +147,8 @@ export type {
 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,