@stonedogcode/style 0.20.0 → 0.20.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonedogcode/style",
-  "version": "0.20.0",
+  "version": "0.20.2",
   "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.",
@@ -48,6 +48,7 @@
     "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 — 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",
+    "publishnpm": "npm run publish:stonedog-style",
     "version:bump:patch": "npm version patch --no-git-tag-version",
     "version:bump:minor": "npm version minor --no-git-tag-version",
     "audit": "npm audit --audit-level=moderate"

package/src/components/StyledImageUpload.tsx

@@ -68,25 +68,80 @@ const PandaItemGroup = styled("div", {
 });
 const PandaItem = styled("div", { base: { position: "relative" } });
 
-/** Chakra's `Float` — the delete control at the item's top-end corner. */
+/**
+ * Chakra's `Float` — the delete control at the item's top-end corner.
+ *
+ * The `translate(40%, -40%)` this used to carry is gone (NEH-1117). It centred
+ * the control ON the corner, so roughly half of it hung outside the preview it
+ * belonged to — measured in Chromium at every viewport, the control's top edge
+ * sat at **y = -7.2**, above the top of the page. That is tolerable while the
+ * control is 16px and merely untidy; at the 48px hit area below it would put
+ * two neighbouring previews' targets into the same few pixels, which is the
+ * sharper half of what the issue reports.
+ *
+ * So the hit area is anchored inside the tile instead, and the visible chip
+ * sits in its top-end corner — which lands the chip in very nearly the place
+ * it occupied before, without anything overhanging.
+ */
 const PandaFloat = styled("div", {
   base: {
     position: "absolute",
     top: "0",
     right: "0",
-    transform: "translate(40%, -40%)",
   },
 });
 
 /**
+ * The hit area — and only the hit area.
+ *
  * `boxSize="4"` and `layerStyle="fill.solid"` were Chakra props with no Panda
- * equivalent — they do not exist on a `styled("button")` and the type-check
- * rejects both. Their effect is reproduced as real styles.
+ * equivalent; their effect is reproduced as real styles. What was NOT
+ * reproduced was a tap target: `boxSize="4"` is **16x16 CSS px**, a third of
+ * this package's stated 48x48 floor, and it came across the extraction
+ * unchanged (NEH-1116) because changing it changes HopperGuard's rendering.
+ * This is that change.
+ *
+ * The split is `StyledTag`'s, which solves the same tension: the BUTTON is the
+ * target and carries no appearance at all, and the chip inside it is what a
+ * reader sees. Sizing the visible circle to 48px instead would put a control
+ * half the width of the 96px preview on top of it.
+ *
+ * `StyledTag` needs negative block margin to stop the target growing its own
+ * tag; here the control is absolutely positioned, so it is already out of
+ * flow and cannot drag the preview's layout with it whatever size it is. The
+ * component test asserts the preview stays 96x96 rather than trusting that.
+ */
+const PandaDeleteTrigger = styled("button", {
+  base: {
+    display: "inline-flex",
+    // Top-end, not centred: the chip keeps the corner position it has always
+    // had, and the extra target grows inwards over the preview — which is
+    // decorative, and the only direction with room.
+    alignItems: "flex-start",
+    justifyContent: "flex-end",
+    // The house floor, stated rather than left to emerge from whatever glyph
+    // a consumer passes — see CLAUDE.md. 48 rather than WCAG 2.5.5 AAA's 44,
+    // because the standard is calibrated for the general population and this
+    // library's largest consumer serves an often-elderly, sometimes
+    // motor-impaired audience.
+    minWidth: "48px",
+    minHeight: "48px",
+    padding: "0",
+    background: "transparent",
+    border: "none",
+    cursor: "pointer",
+  },
+});
+
+/**
+ * What a reader actually sees: the small round chip that used to BE the
+ * button. Same size, same tokens, same appearance — it is now a passenger
+ * inside a target big enough to hit.
  *
  * The colours are tokens, never literals, so the control follows the host's
  * theme and colour mode.
  */
-const PandaDeleteTrigger = styled("button", {
+const PandaDeleteChip = styled("span", {
   base: {
     display: "inline-flex",
     alignItems: "center",
@@ -94,7 +149,6 @@ const PandaDeleteTrigger = styled("button", {
     width: "4",
     height: "4",
     borderRadius: "full",
-    cursor: "pointer",
     lineHeight: "1",
     bg: "boxBgPrimary",
     color: "textPrimary",
@@ -207,9 +261,7 @@ const FileUploadPreviewOnly = ({
               aria-label={`Remove ${file.name}`}
               onClick={() => removeFile(file)}
             >
-              {removeIcon ? (
-                <span aria-hidden="true">{removeIcon}</span>
-              ) : null}
+              <PandaDeleteChip aria-hidden="true">{removeIcon}</PandaDeleteChip>
             </PandaDeleteTrigger>
           </PandaFloat>
         </PandaItem>

package/src/components/StyledTooltip.tsx

@@ -226,6 +226,59 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
    */
   const [focusableAncestor, setFocusableAncestor] = useState<HTMLElement | null>(null);
 
+  /**
+   * Whether the layout effect below has yet decided WHERE the click-mode help
+   * control belongs (NEH-965).
+   *
+   * The control is a real `<button>`, and until the trigger has been measured
+   * the component cannot know whether it is standing inside one. Rendering it
+   * optimistically and moving it afterwards is not an option: React validates
+   * DOM nesting at *render* time, against the React tree, so a single pass
+   * with `<button>` inside `<button>` warns and — on a server-rendered host
+   * like hopper-web — produces a hydration error, whatever the DOM ends up
+   * looking like a moment later.
+   *
+   * So the first pass renders no control at all and the second one puts it
+   * where it belongs. Both effects here are layout effects, so that settles
+   * before paint and before hydration compares anything: there is no frame in
+   * which a reader could see the control missing, and no server/client
+   * mismatch, because the server also renders nothing.
+   */
+  const [helpPlacementSettled, setHelpPlacementSettled] = useState(false);
+
+  /**
+   * The element the click-mode help control is rendered into when the trigger
+   * sits inside something focusable (NEH-965).
+   *
+   * `HelpTrigger` renders beside the child, inside the trigger wrapper. When
+   * the tooltipped thing is an icon inside an icon button that lands the
+   * control *inside* that button:
+   *
+   *     <button aria-label="Expand">   <- the consumer's control
+   *       <div>                        <- TooltipTrigger
+   *         <svg aria-hidden />
+   *         <button aria-label="More information">?</button>   <- invalid
+   *
+   * `<button>` cannot be a descendant of `<button>`, and this is not a
+   * preference anybody opted into: `isClick` is `trigger === "click" ||
+   * !canHover`, so it is the DEFAULT rendering on every phone and tablet.
+   *
+   * Simply not rendering the control would trade invalid HTML for an
+   * unreachable explanation — on a device that cannot hover there is no hover,
+   * and tapping the button activates it rather than explaining it. So the
+   * control moves *out* instead: a span inserted immediately after the
+   * focusable ancestor, portalled into. Valid HTML, still visible, still
+   * tappable, still in the tab sequence, and it scrolls with the page because
+   * it sits in normal flow rather than being positioned over anything.
+   *
+   * `inline-flex` on the host rather than `display: contents`: contents would
+   * let the control participate in the ancestor's parent layout directly, but
+   * it was removed from the accessibility tree by browsers this package's
+   * audience is still using, and an invisible help control is the bug we are
+   * fixing.
+   */
+  const [helpHost, setHelpHost] = useState<HTMLElement | null>(null);
+
   /**
    * True when something else — a descendant or an ancestor — already puts this
    * trigger's content in the tab sequence. When it does, the trigger must add
@@ -287,6 +340,10 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
       ? null
       : node?.parentElement?.closest<HTMLElement>(FOCUSABLE_SELECTOR) ?? null;
     setFocusableAncestor((prev) => (prev === ancestor ? prev : ancestor));
+    // Measured — the next render may place the help control (NEH-965). Set
+    // before the `!node` bail so a trigger that never mounted a node does not
+    // leave click mode permanently without its control.
+    setHelpPlacementSettled(true);
 
     if (!node) return;
 
@@ -299,9 +356,21 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
       .join(" ")
       .replace(/\s+/g, " ")
       .trim();
+    // With a focusable ancestor the help control is rendered OUTSIDE it
+    // (NEH-965), so the ancestor no longer supplies context by containment and
+    // the control has to carry the subject in its own name. "More information"
+    // sitting on its own next to a button called "Expand" names nothing —
+    // which is the twenty-identical-controls problem NEH-769 fixed for the
+    // inline case, reappearing one level up.
+    const ancestorText = ancestor
+      ? (ancestor.getAttribute("aria-label") ?? ancestor.textContent ?? "")
+          .replace(/\s+/g, " ")
+          .trim()
+      : "";
+    const subject = ownText || ancestorText;
     // Long enough to distinguish twenty controls, short enough that a screen
     // reader does not read a paragraph before the reader can act on it.
-    setSubjectLabel(ownText.length > 80 ? `${ownText.slice(0, 80).trimEnd()}…` : ownText);
+    setSubjectLabel(subject.length > 80 ? `${subject.slice(0, 80).trimEnd()}…` : subject);
 
     // parentElement, not the node itself: closest() would match our own
     // aria-label once we set one, and the answer would flip every render.
@@ -361,6 +430,67 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
     };
   }, [focusableAncestor, isClick, show, hide]);
 
+  /**
+   * Insert the host for the portalled help control, immediately after the
+   * focusable ancestor (NEH-965). A layout effect, so the control is in place
+   * before paint.
+   */
+  useLayoutEffect(() => {
+    if (!isClick || !focusableAncestor || typeof document === "undefined") {
+      setHelpHost(null);
+      return;
+    }
+    const host = document.createElement("span");
+    // Named so a consumer reading the DOM can see whose node this is, and so a
+    // test can assert the control landed outside the ancestor rather than
+    // merely that it exists somewhere.
+    host.setAttribute("data-stonedog-tooltip-help-host", "");
+    host.style.display = "inline-flex";
+    host.style.verticalAlign = "middle";
+    focusableAncestor.after(host);
+    setHelpHost(host);
+    return () => {
+      host.remove();
+      setHelpHost(null);
+    };
+  }, [isClick, focusableAncestor]);
+
+  /**
+   * Keep the host beside its ancestor when React MOVES the ancestor.
+   *
+   * The host is a node this component inserts, not one React renders, so React
+   * does not move it with the ancestor: reordering a row of icon buttons
+   * leaves every help control behind at its old index. Measured before fixing,
+   * two buttons swapped:
+   *
+   *     before  BTN(Expand) HOST(Help: Expand) BTN(Collapse) HOST(Help: Collapse)
+   *     after   HOST(Help: Expand) BTN(Collapse) HOST(Help: Collapse) BTN(Expand)
+   *
+   * — every control now beside the wrong button, which for an accessibility
+   * affordance is worse than the nesting it replaced.
+   *
+   * Re-running the effect above cannot catch this. Its dependency is the
+   * ancestor NODE, and a moved node is the same node, so nothing changes and
+   * nothing re-runs. Hence a deliberately dependency-free layout effect: it
+   * re-asserts the placement on every commit, before paint, and costs two DOM
+   * property reads on a path that only exists in click mode inside a focusable
+   * ancestor.
+   *
+   * Scope worth stating rather than implying: this follows a move that
+   * RE-RENDERS this component, which is what a list reorder does. A subtree
+   * memoised so hard that React moves it without rendering it would not be
+   * followed. A `MutationObserver` on the parent would cover that too, and is
+   * deliberately not here — its callback is a microtask, so it could not be
+   * asserted in the tier that can see this at all, and an untested guard is
+   * the thing this package's rules are most emphatic about.
+   */
+  useLayoutEffect(() => {
+    if (!helpHost || !focusableAncestor) return;
+    if (!focusableAncestor.isConnected) return;
+    if (helpHost.previousSibling === focusableAncestor) return;
+    focusableAncestor.after(helpHost);
+  });
+
   useLayoutEffect(() => {
     if (visible && triggerRef.current && tooltipRef.current) {
       const triggerRect = triggerRef.current.getBoundingClientRect();
@@ -566,19 +696,40 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
   const resolvedHelpLabel =
     helpLabel ?? (subjectLabel ? `Help: ${subjectLabel}` : "More information");
 
-  const helpControl = isClick ? (
-    <HelpTrigger
-      ref={helpRef}
-      type="button"
-      side={helpGoesFirst ? "before" : "after"}
-      aria-label={resolvedHelpLabel}
-      aria-expanded={visible}
-      aria-controls={visible ? tooltipId : undefined}
-      onClick={() => setVisible((open) => !open)}
-    >
-      ?
-    </HelpTrigger>
-  ) : null;
+  /**
+   * The click-mode control — rendered only once its home is known, see
+   * `helpPlacementSettled`.
+   *
+   * `stopPropagation` is load-bearing rather than defensive. A React portal
+   * bubbles its events through the REACT tree, not the DOM tree, so once this
+   * control is portalled out of the icon button it is still, as far as React
+   * is concerned, inside it — and a press on "?" would fire the button's own
+   * `onClick`. That is precisely the collision this fix exists to remove, so
+   * it is stopped for the inline case too: pressing "?" asks for an
+   * explanation, and must never also do the thing being explained.
+   */
+  const helpControl =
+    isClick && helpPlacementSettled ? (
+      <HelpTrigger
+        ref={helpRef}
+        type="button"
+        side={helpGoesFirst ? "before" : "after"}
+        aria-label={resolvedHelpLabel}
+        aria-expanded={visible}
+        aria-controls={visible ? tooltipId : undefined}
+        onMouseDown={(event: React.MouseEvent) => event.stopPropagation()}
+        onClick={(event: React.MouseEvent) => {
+          event.stopPropagation();
+          setVisible((open) => !open);
+        }}
+      >
+        ?
+      </HelpTrigger>
+    ) : null;
+
+  // Inside a focusable ancestor the control is portalled out to `helpHost`;
+  // everywhere else it stays where it has always been, beside the child.
+  const inlineHelpControl = focusableAncestor ? null : helpControl;
 
   return (
     <>
@@ -628,10 +779,11 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
         aria-describedby={!insideFocusable && visible ? tooltipId : undefined}
         {...rest}
       >
-        {helpGoesFirst && helpControl}
+        {helpGoesFirst && inlineHelpControl}
         {children}
-        {!helpGoesFirst && helpControl}
+        {!helpGoesFirst && inlineHelpControl}
       </TooltipTrigger>
+      {helpControl && helpHost && createPortal(helpControl, helpHost)}
       {visible && typeof document !== "undefined" &&
         createPortal(
           <TooltipContent

package/src/preset/recipes/button.ts

@@ -133,13 +133,24 @@ export const buttonRecipe = defineRecipe({
           pointerEvents: "none",
         },
       },
+      /**
+       * The same correction `iconButton`'s `matte` takes, for the same reason
+       * (NEH-881) — see the long note there.
+       *
+       * NEH-881 named only `iconButton`. These two recipes are the same control
+       * in two shapes and their `matte` blocks were byte-identical, including
+       * the inert `bgGradient` that kept the pairing guard from inspecting
+       * either of them. Fixing one and leaving the other would ship the defect
+       * under a different class name, so both move together: the same 8-of-18
+       * measurement applies unchanged, because it is a property of the surface
+       * and the text token, not of the shape of the control.
+       */
       matte: {
-        bgGradient: "linear(to-b, gray.800, gray.900)",
         borderColor: "gray.700",
         borderWidth: "1px",
         boxShadow: "md",
         bg: "buttonBgAccent",
-        color: "textPrimary",
+        color: "buttonTextAccent",
         borderRadius: "lg",
         fontWeight: "bold",
       },

package/src/preset/recipes/icon-button.ts

@@ -155,13 +155,50 @@ export const buttonIconRecipe = defineRecipe({
           pointerEvents: "none",
         },
       },
+      /**
+       * The accent pairing again, and the gradient that was hiding it
+       * (NEH-881).
+       *
+       * This variant was filed as a different defect class: a FIXED dark
+       * `gray.800`→`gray.900` gradient painting over the accent fill in every
+       * theme, with a themed `textPrimary` glyph left dark-on-dark on top of
+       * it. The proposed fix was a deliberate literal `color: "white"`, as
+       * `box` and `input-bool` had already taken for their own `matte`.
+       *
+       * **There is no gradient.** `bgGradient` is Chakra v2 syntax; Panda has
+       * no such utility and no `linear()` shorthand, so it emitted
+       * `background-image: linear(to-b, gray.800, gray.900)` — not valid CSS,
+       * discarded at parse time by every engine. Chromium reads the element
+       * back as `background-image: none`, and the `background` shorthand
+       * emitted just above it had already reset `background-image` in any case.
+       *
+       * So the surface here has always been plain `buttonBgAccent`, and this is
+       * the ordinary NEH-796 / NEH-877 mispairing after all — `textPrimary` is
+       * the contract's partner for `boxBgPrimary`, not for an accent fill.
+       * Measured over nine host themes in both modes, 18 pairs: `textPrimary`
+       * is below WCAG AA on 8 of them, every one in dark mode, the worst at
+       * 2.15:1 (white on `#F59E0B`). `buttonTextAccent` is below AA on 0 of the
+       * 18, and reaches 9.78:1 on that same worst pair.
+       *
+       * Had `color: "white"` been taken as filed, it would have pinned the
+       * failing half of that measurement in place under a comment calling it
+       * deliberate — the shape where a test makes a bug unfixable by review.
+       *
+       * The dead declaration goes too, and that is not tidying. The pairing
+       * sweep in `variant-contrast-pairing.test.ts` reads `background-image`
+       * before `background`, so while the invalid gradient was emitted the
+       * guard took it as this variant's surface, found the token contract said
+       * nothing about it, and skipped the variant entirely. Removing it is what
+       * puts `matte` back under the guard that already covers its five
+       * siblings — verified by planting the old colour back and watching that
+       * guard name both selectors.
+       */
       matte: {
-        bgGradient: "linear(to-b, gray.800, gray.900)",
         borderColor: "gray.700",
         borderWidth: "1px",
         boxShadow: "md",
         bg: "buttonBgAccent",
-        color: "textPrimary",
+        color: "buttonTextAccent",
         borderRadius: "lg",
         fontWeight: "bold",
       },