@stonedogcode/style 0.16.0 → 0.19.0

package/README.md

@@ -629,6 +629,55 @@ Scroll mode needs a height to scroll inside: `StyledScrollbar` is
 height (`display: flex; flex-direction: column; height: …`). Unconstrained, the
 rail simply grows — which is correct, and is not a bug.
 
+## Form help — `StyledFieldHelp`
+
+Permanent explanatory text for a field: below the label, above the control,
+always visible.
+
+```tsx
+<StyledFormLabel htmlFor="dose">Dose</StyledFormLabel>
+<StyledFieldHelp htmlFor="dose">
+  Milligrams per tablet, as printed on the bottle.
+</StyledFieldHelp>
+<StyledInputText id="dose" />
+```
+
+It is **text, and nothing else** — no trigger, no disclosure, no popover, no
+preference. That is the design rather than a simplification, and it is what the
+guarantees below rest on.
+
+### What it guarantees
+
+- **Zero tab stops.** Nothing here is focusable, so explaining a hundred fields
+  costs the keyboard nothing. The pattern this replaces put a help *button*
+  beside every explained control, which roughly doubled keyboard traversal on a
+  busy form and cannot be fixed while a per-control control remains: taking the
+  buttons out of the tab order loses the help for sighted keyboard users
+  instead.
+- **The control's `aria-describedby` points at it**, so a screen reader
+  announces the words as the field's description rather than reading them as
+  stray prose further down the page. The component sets the attribute itself,
+  merging with any description the control already had and removing only its own
+  id when it unmounts — so a call site that forgets still gets the association.
+  `fieldHelpId("dose")` is `"dose-help"`, exported so a host can put the
+  attribute in server-rendered markup instead; the component notices and stands
+  down.
+- **No pointer is involved**, which sidesteps WCAG 1.4.13 (Content on Hover or
+  Focus) rather than trying to satisfy it. Touch, mouse and keyboard all get the
+  same words with no gesture and no setting.
+- **One tier below the app-wide text size, and never below the smallest tier**
+  the host offers. A reader who has already turned their text down is the one
+  with the least room to spare.
+- **Contrast is measured, not assumed.** The colour is the emphasis token
+  `textMuted`, which is `currentColor`-relative, so it de-emphasises correctly
+  on a light theme and a dark one. The component tests composite the whole
+  ancestor chain — every translucent layer, not the page background — and assert
+  WCAG 1.4.3 AA against the surface the text really paints on. Measuring against
+  the page is how text on a tinted chip gets a confident, wrong pass.
+
+`children` is typed `ReactNode` for formatting — a unit, a `<strong>`, a line
+break. Putting a control in there defeats the only promise the component makes.
+
 ## Adopting a component as it is migrated
 
 Components move out of HopperGuard into this package one at a time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonedogcode/style",
-  "version": "0.16.0",
+  "version": "0.19.0",
   "description": "A Panda CSS design system: a themeable Panda preset plus the React components built on it.",
   "license": "Apache-2.0",
   "author": "StoneDogCode L.L.C.",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "git+https://github.com/stonedog-code/stonedog-style.git"
   },
-  "//publishConfig": "A SCOPED package defaults to access: restricted. Publishing one without this succeeds, prints nothing unusual, and then 404s for every consumer \u2014 which reads as a missing package rather than as a private one. It was not needed while the name was unscoped (those default to public), so it is new as of the scope migration and it is the single thing most likely to be forgotten in one.",
+  "//publishConfig": "A SCOPED package defaults to access: restricted. Publishing one without this succeeds, prints nothing unusual, and then 404s for every consumer — which reads as a missing package rather than as a private one. It was not needed while the name was unscoped (those default to public), so it is new as of the scope migration and it is the single thing most likely to be forgotten in one.",
   "publishConfig": {
     "access": "public"
   },
@@ -20,7 +20,7 @@
     "./preset": "./src/preset/index.ts",
     "./package.json": "./package.json"
   },
-  "//files": "The package ships SOURCE, so `src` has to go out whole \u2014 but only the part a consumer imports. Tests, Playwright component tests and their harnesses were 57 of 130 entries and never resolvable from any export, so every one of them was a file a consumer's Panda run had to be told to skip. `src/__tests__/published-package.test.ts` asserts this listing rather than this array: npm's own resolution of these negations is the only thing that decides what ships.",
+  "//files": "The package ships SOURCE, so `src` has to go out whole — but only the part a consumer imports. Tests, Playwright component tests and their harnesses were 57 of 130 entries and never resolvable from any export, so every one of them was a file a consumer's Panda run had to be told to skip. `src/__tests__/published-package.test.ts` asserts this listing rather than this array: npm's own resolution of these negations is the only thing that decides what ships.",
   "files": [
     "src",
     "!src/**/__tests__/**",
@@ -38,7 +38,7 @@
     "pretype-check": "npm run panda:prepare",
     "type-check": "tsc --noEmit",
     "lint": "eslint . --ext ts,tsx",
-    "//pretest": "panda:build, not panda:prepare \u2014 the token-contract suite asserts against the generated stylesheet, which cssgen produces and codegen alone does not.",
+    "//pretest": "panda:build, not panda:prepare — the token-contract suite asserts against the generated stylesheet, which cssgen produces and codegen alone does not.",
     "pretest": "npm run panda:build",
     "test": "jest",
     "pretest:ct": "npm run panda:build",
@@ -46,7 +46,7 @@
     "test:ct:ui": "playwright test --config playwright-ct.config.ts --ui",
     "test:coverage": "jest --coverage",
     "gate": "npm run type-check && npm run lint && npm run test",
-    "//publish:stonedog-style": "Publish to npm, end to end. Run from a terminal, interactively \u2014 npm prompts for the 2FA one-time password and the login flow needs a browser. It refuses a checkout that is detached, dirty, or behind origin/main: a submodule sits detached at the consumer's gitlink by default, and publishing from one commit behind ships a tarball missing the very thing you are publishing for while looking like a success (it did, on 2026-08-04, without TitleLogo.tsx). Runs the gate, prints the tarball listing, then proves the result by installing from the registry into a temp directory.",
+    "//publish:stonedog-style": "Publish to npm, end to end. Run from a terminal, interactively — npm prompts for the 2FA one-time password and the login flow needs a browser. It refuses a checkout that is detached, dirty, or behind origin/main: a submodule sits detached at the consumer's gitlink by default, and publishing from one commit behind ships a tarball missing the very thing you are publishing for while looking like a success (it did, on 2026-08-04, without TitleLogo.tsx). Runs the gate, prints the tarball listing, then proves the result by installing from the registry into a temp directory.",
     "publish:stonedog-style": "bash scripts/publish-package.sh",
     "version:bump:patch": "npm version patch --no-git-tag-version",
     "version:bump:minor": "npm version minor --no-git-tag-version",

package/src/components/StyledCollapsible.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import React, { useId, useState } from "react";
+import React from "react";
 import { styled } from "styled-system/jsx";
+import { useDisclosure } from "./useDisclosure";
 
 /**
  * A disclosure: a trigger that shows and hides a region.
@@ -82,41 +83,27 @@ const StyledCollapsible: React.FC<StyledCollapsibleProps> = ({
   triggerTestId,
   contentTestId,
 }) => {
-  const [uncontrolled, setUncontrolled] = useState(defaultOpen);
-
-  // Controlled the moment `open` is supplied, and uncontrolled otherwise —
-  // decided per render rather than latched at mount, because a host that
-  // switches between the two mid-life has a bug we should not paper over by
-  // silently ignoring the prop.
-  const isControlled = open !== undefined;
-  const isOpen = isControlled ? open : uncontrolled;
-
-  const contentId = useId();
-
-  const toggle = () => {
-    const next = !isOpen;
-    // The internal state moves even when controlled. If the host ignores the
-    // callback the component would otherwise appear dead to the pointer, and a
-    // control that does nothing when pressed is indistinguishable from a broken
-    // one — for this audience, the reader concludes the app is broken, not that
-    // they misread the affordance.
-    if (!isControlled) setUncontrolled(next);
-    onOpenChange?.(next);
-  };
+  // The mechanics live in `useDisclosure`, not here. This component is one
+  // ARRANGEMENT of a disclosure — a button with the trigger inside it, above
+  // the region — and a host whose control is already a button composes the
+  // same hook into its own layout instead of nesting one button in another
+  // (NEH-1100). Two arrangements, one implementation.
+  const { triggerProps, contentProps } = useDisclosure({
+    open,
+    defaultOpen,
+    onOpenChange,
+  });
 
   return (
     <>
       <CollapsibleTrigger
-        type="button"
-        onClick={toggle}
-        aria-expanded={isOpen}
-        aria-controls={contentId}
+        {...triggerProps}
         aria-label={ariaLabel}
         data-testid={triggerTestId}
       >
         {trigger}
       </CollapsibleTrigger>
-      <div id={contentId} hidden={!isOpen} data-testid={contentTestId}>
+      <div {...contentProps} data-testid={contentTestId}>
         {children}
       </div>
     </>

package/src/components/StyledFieldHelp.tsx

@@ -0,0 +1,248 @@
+"use client";
+
+import React, { useEffect, useRef } from "react";
+import { styled } from "styled-system/jsx";
+import type { HTMLStyledProps } from "styled-system/types";
+import { log } from "../config/logger";
+import { useFontSizeProfile } from "../config/style-config";
+import { fontSizeMap, stepDownFontSize } from "../config/font-size";
+
+/**
+ * Permanent help text for a form control: below the label, above the control,
+ * always visible, never interactive.
+ *
+ * ```tsx
+ * <StyledFormLabel htmlFor="dose">Dose</StyledFormLabel>
+ * <StyledFieldHelp htmlFor="dose">
+ *   Milligrams per tablet, as printed on the bottle.
+ * </StyledFieldHelp>
+ * <StyledInputText id="dose" />
+ * ```
+ *
+ * ## Why this exists rather than another tooltip (PRD-0037, NEH-972)
+ *
+ * The pattern this replaces is `StyledTooltip` plus its `HelpTrigger`, and the
+ * problem with it is not placement — NEH-769 fixed the placement and the
+ * pattern was still wrong. Four things fail at once:
+ *
+ * - **Hover-only help excludes touch entirely**, and is actively hostile to a
+ *   reader with a tremor: they open tooltips by accident and cannot reliably
+ *   move a pointer *into* one before it closes.
+ * - **`HelpTrigger` is a `<button>`, so every instance is a tab stop.** A
+ *   screenshot of one production screen showed roughly twenty of them; ~160
+ *   across the app. That roughly doubles keyboard traversal, and it cannot be
+ *   fixed by taking them out of the tab order — a sighted keyboard user not
+ *   running a screen reader would lose the help altogether. There is no fix
+ *   for the tab-stop tax that keeps a per-control control.
+ * - **Twenty identical glyphs are not twenty helps, they are noise.** Older
+ *   readers have measurably low tolerance for hidden information behind an
+ *   abstract icon, so the pattern penalised exactly the audience it was for.
+ * - It needed a **preference** (`accessibility.clickForTooltips`) to be usable
+ *   on a touch device, and a preference is a thing to get wrong.
+ *
+ * So this component has **no trigger, no state, no preference and no
+ * interaction**. It is text. That is the entire design, and every constraint
+ * below follows from it:
+ *
+ * - it adds **zero tab stops** — no `tabindex`, no focusable element, nothing
+ *   Tab can land on;
+ * - it needs **no pointer**, so it sidesteps WCAG 1.4.13 (Content on Hover or
+ *   Focus) rather than trying to satisfy dismissible/hoverable/persistent;
+ * - it is in the DOM from first paint, so a touch reader, a keyboard reader and
+ *   a screen-reader user all get the same words with no gesture at all.
+ *
+ * ## It wires `aria-describedby` itself, and that is deliberate
+ *
+ * Text sitting near a control is not a description of it. Without
+ * `aria-describedby` a screen reader announces "Dose, edit text" and the help
+ * is stray prose somewhere else in the reading order — which is how a field
+ * ends up *looking* explained and being unexplained.
+ *
+ * Two things make the association hard to get wrong, because this pattern is
+ * about to be applied at well over a hundred call sites and the one that gets
+ * skipped is the one nobody notices:
+ *
+ * 1. **The id is derived, not generated.** `fieldHelpId("dose")` is
+ *    `"dose-help"` — deterministic from the control's own id, so both sides can
+ *    name it without passing a generated value around, and it is stable across
+ *    server and client render.
+ * 2. **The component sets the attribute on the control** in an effect, merging
+ *    with anything already there. A call site that forgets still gets the
+ *    association.
+ *
+ * Set imperatively rather than by cloning the child, for the reason
+ * `StyledTooltip` records: `cloneElement` depends on every child component
+ * forwarding the prop, and a child that quietly drops it fails invisibly. It is
+ * not a wrapper for the same reason — a wrapper would have to own the control's
+ * markup, and this has to drop into a form whose markup already exists.
+ *
+ * `useEffect` rather than `useLayoutEffect`: nothing here affects layout, and
+ * the accessibility tree is read after hydration. A host may still write
+ * `aria-describedby={fieldHelpId("dose")}` on the control itself if it wants
+ * the association present in server-rendered HTML; the effect sees it is
+ * already there and leaves it alone.
+ *
+ * ## Size and colour
+ *
+ * **One tier below the app-wide text size, never below `xs`.** The size is an
+ * inline style rather than a Panda prop because Panda extracts styles by
+ * parsing source at BUILD time: a prop whose value is only known at runtime
+ * yields a class name with no rule behind it, and nothing errors.
+ * `StyledFormLabel` and `StyledText` reach for an inline style for exactly this
+ * reason. Reading the profile also matters — plain inheritance would pin the
+ * help to whatever the browser default is, which in a product whose body text
+ * is 1.375rem makes the help less than two-thirds the size of the text it
+ * explains.
+ *
+ * **Colour is `textMuted`**, the emphasis axis, which resolves relative to
+ * `currentColor` — so it de-emphasises against the surface it is actually on,
+ * light theme or dark, rather than picking a grey that is right on one of them.
+ * `StyledFieldHelp.contrast.ct.tsx` measures the rendered result against the
+ * **composited** background — every ancestor layer, not the page — and asserts
+ * WCAG 1.4.3 AA. Measuring against the page background is how a confidently
+ * wrong pass gets produced for text that sits on a tinted chip.
+ *
+ * The size step and the colour step are two signals, not one, so the help still
+ * reads as secondary for anyone who cannot see the colour difference.
+ */
+
+const PandaFieldHelp = styled("p", {
+  base: {
+    display: "block",
+    // Longhands, never the `margin` shorthand. Panda emits atomic rules, and a
+    // shorthand competing with a longhand for the same box is decided by
+    // stylesheet order rather than by what was written.
+    marginTop: "0",
+    marginInline: "0",
+    // The gap before the control. `StyledFormLabel` supplies the gap above.
+    marginBottom: "0.5rem",
+    color: "textMuted",
+    // Prose, and prose that is being read carefully — a little more leading
+    // than the label above it.
+    lineHeight: "1.4",
+    fontWeight: "normal",
+    // No `fontSize`: it is resolved at runtime from the profile. See above.
+  },
+});
+
+/**
+ * The `id` this component gives its help text, derived from the control's id.
+ *
+ * Exported so a call site can put the association in server-rendered HTML —
+ * `aria-describedby={fieldHelpId("dose")}` — and so a test can name the element
+ * without reaching into the DOM for it. Deterministic on purpose: a generated
+ * id (`useId`) cannot be named by the other half of the pair without threading
+ * a value between two siblings, and threading is what gets skipped.
+ */
+export function fieldHelpId(controlId: string): string {
+  return `${controlId}-help`;
+}
+
+/** Split an `aria-describedby` attribute into its id tokens. */
+function idTokens(value: string | null): string[] {
+  return value ? value.split(/\s+/).filter(Boolean) : [];
+}
+
+export interface StyledFieldHelpProps
+  extends Omit<HTMLStyledProps<"p">, "children"> {
+  /**
+   * The `id` of the control this describes.
+   *
+   * Required, and it is the whole point: without it this is prose near a
+   * control rather than the control's description. Named `htmlFor` to match
+   * `StyledFormLabel`, so the pair reads the same at a call site.
+   */
+  htmlFor: string;
+  /**
+   * The help itself. **Text.** Anything focusable put in here defeats the one
+   * guarantee this component makes, so it is typed as `ReactNode` for
+   * formatting (`<strong>`, a unit, a line break) rather than for controls.
+   */
+  children: React.ReactNode;
+  /** Override the derived id. Rarely wanted — see `fieldHelpId`. */
+  id?: string;
+}
+
+const StyledFieldHelp: React.FC<StyledFieldHelpProps> = ({
+  htmlFor,
+  children,
+  id,
+  style,
+  fontSize,
+  ...props
+}) => {
+  // Unconditional and at the top: folding this into the expression below reads
+  // fine and is a hooks-order violation the moment `fontSize` is passed.
+  const profile = useFontSizeProfile();
+  const ref = useRef<HTMLParagraphElement | null>(null);
+
+  const helpId = id ?? fieldHelpId(htmlFor);
+
+  useEffect(() => {
+    const node = ref.current;
+    if (!node) return;
+
+    // The element's own document, not the global one: a component test mounts
+    // inside an iframe, and a host may portal into another window.
+    const control = node.ownerDocument.getElementById(htmlFor);
+    if (!control) {
+      // Not thrown. A missing control is a call-site bug, but the help text is
+      // still readable on screen and throwing would take the whole form down
+      // over an attribute. The host hears about it through its own logger.
+      log.warn(
+        "StyledFieldHelp: no element has this id, so the help is not announced as the field's description",
+        { htmlFor, helpId },
+      );
+      return;
+    }
+
+    const tokens = idTokens(control.getAttribute("aria-describedby"));
+    // Already named — the call site wired it statically. Leave it be, or the
+    // id lands twice and a screen reader reads the description twice.
+    if (tokens.includes(helpId)) return;
+
+    control.setAttribute("aria-describedby", [...tokens, helpId].join(" "));
+
+    return () => {
+      // Read the attribute again rather than restoring the value captured
+      // above. Something else may have added its own id in the meantime — an
+      // error summary is the obvious one — and restoring a stale string would
+      // silently drop it.
+      const remaining = idTokens(
+        control.getAttribute("aria-describedby"),
+      ).filter((token) => token !== helpId);
+      if (remaining.length > 0) {
+        control.setAttribute("aria-describedby", remaining.join(" "));
+      } else {
+        control.removeAttribute("aria-describedby");
+      }
+    };
+  }, [htmlFor, helpId]);
+
+  // Applied only when the caller named no size, so their Panda `fontSize` class
+  // is not beaten by an inline declaration.
+  const sized = fontSize
+    ? undefined
+    : fontSizeMap[stepDownFontSize(profile)] ?? fontSizeMap.sm;
+
+  return (
+    <PandaFieldHelp
+      ref={ref}
+      id={helpId}
+      fontSize={fontSize}
+      // A stable hook for the app's own end-to-end assertion that help is in
+      // the DOM with no pointer interaction (PRD-0037's success criteria), and
+      // for finding the call sites during the migration.
+      data-field-help="true"
+      style={{ ...(sized ? { fontSize: sized } : {}), ...style }}
+      {...props}
+    >
+      {children}
+    </PandaFieldHelp>
+  );
+};
+
+StyledFieldHelp.displayName = "StyledFieldHelp";
+
+export default StyledFieldHelp;
+export { StyledFieldHelp };