@stonedogcode/style 0.10.1 → 0.13.0

package/README.md

@@ -82,7 +82,8 @@ token reads one, and **a token whose property is undefined renders as nothing**
 no fallback, no warning, no error. An app that skips this compiles, builds,
 serves, and shows you a blank page.
 
-There are **44** of them. Get the list at runtime rather than copying one:
+There are **45** of them. Get the list at runtime rather than copying one — a
+number in prose goes stale the day a token is added, and this one already had:
 
 ```ts
 import { requiredCssCustomProperties } from "@stonedogcode/style/preset";
@@ -91,7 +92,57 @@ requiredCssCustomProperties();           // --hopper-* (default)
 requiredCssCustomProperties("optima");   // --optima-*, if you set cssVarPrefix
 ```
 
-A complete starter theme — all 44, nothing elided. Dark, and every text/surface
+### 8 colour tokens you do NOT have to define
+
+`textMuted` and `textSubtle` are the **emphasis** axis — how important a piece
+of text is, on whatever surface it sits. They are the one exception to the
+no-fallback rule above, and they are not in `requiredCssCustomProperties()`.
+
+They can have a default because *"like the surrounding text, but quieter"* has a
+correct answer on every theme, which *"what colour is this surface?"* does not:
+
+```css
+color-mix(in srgb, currentColor 78%, transparent)   /* textMuted  */
+color-mix(in srgb, currentColor 64%, transparent)   /* textSubtle */
+```
+
+`currentColor` inside a `color` declaration resolves to the **inherited** value,
+so both follow whatever text they sit among — light theme, dark theme, or a
+palette this package has never seen. Both clear WCAG AA against the surfaces
+they pair with, measured in a browser rather than chosen by eye.
+
+Define `--<prefix>-text-muted-text` / `--<prefix>-text-subtle-text` only if you
+want a different step.
+
+### ...and six more, for status
+
+`boxSuccess` / `boxWarning` / `boxError` and their `borderSuccess` /
+`borderWarning` / `borderError` are the chips `StyledAlert` paints on. They are
+defaulted for the same reason and a slightly different one: **danger-red,
+caution-amber and success-green are near-universal**, so a default is knowable
+where "what colour is this surface?" is not.
+
+The hue is fixed and the *lightness* is not, which is the split that matters —
+red has to stay red to mean danger, but how light that red sits has to follow
+the page:
+
+```css
+color-mix(in srgb, #dc2626 14%, transparent)   /* boxError    — tints the page */
+#dc2626                                        /* borderError — a solid hue    */
+```
+
+The borders are solid because a translucent one cannot clear WCAG 1.4.11 (3:1
+for a non-text boundary): at 45% they measured 1.72–2.05:1 against a dark page.
+A saturated mid-tone clears 3:1 at both ends, which is what lets one value serve
+a light theme and a dark one.
+
+Define `--<prefix>-box-{success,warning,error}-{bg,border}` to use your own.
+
+**Do not reach for `textSecondary` when you mean "muted".** That is the *surface*
+axis — it means "text on the secondary surface" — and using it for emphasis
+collapses two levels onto one colour.
+
+A complete starter theme — all 45, nothing elided. Dark, and every text/surface
 pair clears WCAG AA (measured: worst 5.17:1, ten of thirteen pairs at AAA), so
 it is a legitimate starting point rather than a placeholder. Replace the values;
 keep every key.
@@ -115,6 +166,7 @@ keep every key.
   --hopper-text-pop-text: #38bdf8;
   --hopper-text-error-text: #f87171;
   --hopper-text-warning-text: #fbbf24;
+  --hopper-text-success-text: #4ade80;
 
   /* Borders */
   --hopper-box-primary-border: #475569;
@@ -193,7 +245,7 @@ the three ways this goes wrong silently:
 ```bash
 npx panda cssgen --outfile styled-system/styles.css
 
-# 1. Did the preset load? Expect ~44 matches, not 0.
+# 1. Did the preset load? Expect ~45 matches, not 0.
 grep -c 'var(--hopper-' styled-system/styles.css
 
 # 2. Did Panda parse the package's source? Expect ~240 classes, not ~0.
@@ -278,7 +330,7 @@ stonedogStylePreset({ cssVarPrefix: "acme" }); // → var(--acme-box-primary-bg)
 
 The rename is total — every token re-points, and no `--hopper-*` reference
 survives anywhere in the generated CSS. Choose it **before** you write a theme,
-because it changes all 44 property names you have to define.
+because it changes all 45 property names you have to define.
 
 ## Adopting it in a new app — a worked example
 
@@ -361,7 +413,7 @@ export default defineConfig({
 
 ```tsx
 // 4. Your root — theme first, then the provider
-import "./theme.css";                 // the 44 properties, from step 3 above
+import "./theme.css";                 // the 45 properties, from step 3 above
 import { StonedogStyleProvider } from "@stonedogcode/style";
 
 export function Root({ children }) {
@@ -579,7 +631,7 @@ rail simply grows — which is correct, and is not a bug.
 
 ## Adopting a component as it is migrated
 
-Components move out of HopperGuard into this package one at a time (NEH-167).
+Components move out of HopperGuard into this package one at a time.
 Each lands as its own release, so consumers adopt on their own schedule rather
 than waiting for a big-bang switch.
 
@@ -640,7 +692,7 @@ import { StyledSpinner } from "@stonedogcode/style";
 `optima-filings` is public and AGPLv3 and ships a public Docker image, so it
 uses a **permissive icon set** (Lucide) through the icon seam rather than the
 private Font Awesome package. Everything else is shared. Both Optima repos run
-their own `--optima-*` namespace via `cssVarPrefix` (NEH-170).
+their own `--optima-*` namespace via `cssVarPrefix`.
 
 ### Verify — the three checks that actually catch things
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonedogcode/style",
-  "version": "0.10.1",
+  "version": "0.13.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 — 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 NEH-482 and it is the single thing most likely to be forgotten in a scope migration.",
+  "//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"
   },

package/src/components/StyledAlert.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+import React from "react";
+import { alertRecipe } from "styled-system/recipes";
+import { cx } from "styled-system/css";
+
+/** The four things an alert can be. */
+export type AlertStatus = "info" | "success" | "warning" | "error";
+
+/**
+ * Which ARIA role each status takes, and why they are not all the same.
+ *
+ * The difference is whether the announcement **interrupts**. `alert` is an
+ * assertive live region: a screen reader abandons what it was saying to read it.
+ * That is right for a failure the user must deal with and wrong for a
+ * confirmation — being interrupted mid-sentence to be told something worked is
+ * hostile, and doing it for every status trains people to ignore the important
+ * ones.
+ *
+ * The original component had **no role at all**, so none of the four was
+ * announced. An alert that is not announced is not an alert (NEH-421).
+ */
+const ROLE_FOR_STATUS: Record<AlertStatus, "alert" | "status"> = {
+  error: "alert",
+  warning: "alert",
+  info: "status",
+  success: "status",
+};
+
+/**
+ * The non-colour signal for each status — WCAG 1.4.1 (Use of Colour), Level A.
+ *
+ * The original conveyed status by background colour alone. The `Indicator` slot
+ * existed and every call site left it empty, so the whole distinction was
+ * invisible to anyone who cannot separate four pale washes — which includes
+ * roughly one man in twelve, and anyone on a bad screen in daylight.
+ *
+ * These are text characters rather than icons on purpose. This package ships no
+ * artwork by policy, and a glyph inherits `currentColor` and the font scale for
+ * free, so the signal survives a font-size change and cannot end up a different
+ * colour from the message beside it.
+ *
+ * They are `aria-hidden`: the role above already tells a screen reader what kind
+ * of message this is, and reading "warning sign" before the text would be the
+ * same information twice.
+ */
+const GLYPH_FOR_STATUS: Record<AlertStatus, string> = {
+  info: "i",
+  success: "✓",
+  warning: "!",
+  error: "✕",
+};
+
+export interface StyledAlertProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+  /** Which kind of message this is. Decides colour, glyph AND announcement. */
+  status?: AlertStatus;
+  /** Optional heading, shown above the message in bold. */
+  title?: React.ReactNode;
+  /**
+   * Replace the built-in glyph.
+   *
+   * Pass a node to substitute your own icon, or `null` to render no indicator.
+   * `null` is deliberately possible and deliberately awkward to reach for: it
+   * puts the component back in breach of WCAG 1.4.1 unless the surrounding UI
+   * carries the signal some other way.
+   */
+  indicator?: React.ReactNode;
+  children?: React.ReactNode;
+}
+
+/**
+ * A status banner.
+ *
+ * ```tsx
+ * <StyledAlert status="error" title="Something went wrong">
+ *   We could not save your changes.
+ * </StyledAlert>
+ * ```
+ */
+export const StyledAlert = React.forwardRef<HTMLDivElement, StyledAlertProps>(
+  function StyledAlert(
+    { status = "info", title, indicator, children, className, ...rest },
+    ref,
+  ) {
+    const classes = alertRecipe({ status });
+    const glyph = indicator === undefined ? GLYPH_FOR_STATUS[status] : indicator;
+
+    return (
+      <div
+        ref={ref}
+        // `role` and `aria-live` together: the role carries the semantics, and
+        // the explicit `aria-live` is what makes an alert rendered into an
+        // already-present region announce when its CONTENT changes rather than
+        // only when it mounts. A banner that swaps "saving" for "failed" in
+        // place is the common case and the one that otherwise goes silent.
+        role={ROLE_FOR_STATUS[status]}
+        aria-live={ROLE_FOR_STATUS[status] === "alert" ? "assertive" : "polite"}
+        className={cx(classes.root, className)}
+        {...rest}
+      >
+        {glyph !== null && (
+          <span aria-hidden="true" className={classes.indicator}>
+            {glyph}
+          </span>
+        )}
+        <div className={classes.content}>
+          {title !== undefined && title !== null && (
+            <div className={classes.title}>{title}</div>
+          )}
+          {children !== undefined && children !== null && (
+            <div className={classes.description}>{children}</div>
+          )}
+        </div>
+      </div>
+    );
+  },
+);
+
+export default StyledAlert;

package/src/components/StyledConfetti.tsx

@@ -0,0 +1,274 @@
+"use client";
+
+import React from "react";
+import { css, cx } from "styled-system/css";
+
+/** What a celebration is asked for. */
+export interface CelebrateOptions {
+  /** How many pieces to throw. */
+  particleCount: number;
+  /** Render these characters instead of coloured pieces. */
+  emojis?: ReadonlyArray<string> | undefined;
+}
+
+/**
+ * A host's own celebration.
+ *
+ * This is the seam that replaced a `js-confetti` import (NEH-430). A host that
+ * wants that library — or canvas-confetti, or a Lottie animation — passes a
+ * function; everyone else gets the CSS burst below.
+ *
+ * It may return a promise, in which case `onComplete` fires when it settles.
+ * A rejection is deliberately NOT propagated: a celebration that fails is not
+ * an error the user needs, and the surrounding flow (a save, a signup) has
+ * already succeeded by the time anything fires confetti.
+ */
+export type CelebrateFn = (
+  options: CelebrateOptions,
+) => void | Promise<unknown>;
+
+/** How long the default burst runs, in ms. Also the `onComplete` delay. */
+const BURST_MS = 1200;
+
+/**
+ * Tokens the default burst cycles through.
+ *
+ * Theme tokens rather than literal colours, so a celebration is on-brand and
+ * follows dark mode — and so this component does not become the one place in
+ * the package that knows a hex value.
+ */
+const PARTICLE_TOKENS = [
+  "boxBgAccent",
+  "boxBgPrimary",
+  "boxBgSecondary",
+  "textAccent",
+] as const;
+
+/**
+ * One pre-built class per particle colour.
+ *
+ * These are written out as four literal `css()` calls rather than generated in
+ * the render loop, and that is a requirement rather than a style preference:
+ * **Panda extracts styles by parsing source statically**, so
+ * `css({ backgroundColor: token })` — with `token` a variable — resolves to
+ * nothing and emits no rule, while the class name still lands in the DOM. The
+ * particles would be invisible, with no build error and nothing in the console.
+ * It is the same trap the CLAUDE.md note about `width={metrics.mark}` records.
+ */
+const PARTICLE_CLASS: Record<(typeof PARTICLE_TOKENS)[number], string> = {
+  boxBgAccent: css({ backgroundColor: "boxBgAccent" }),
+  boxBgPrimary: css({ backgroundColor: "boxBgPrimary" }),
+  boxBgSecondary: css({ backgroundColor: "boxBgSecondary" }),
+  textAccent: css({ backgroundColor: "textAccent" }),
+};
+
+interface Particle {
+  id: number;
+  dx: string;
+  dy: string;
+  rot: string;
+  delay: string;
+  token: (typeof PARTICLE_TOKENS)[number];
+  emoji: string | undefined;
+}
+
+function buildParticles(
+  count: number,
+  emojis: ReadonlyArray<string> | undefined,
+): Particle[] {
+  const particles: Particle[] = [];
+  for (let i = 0; i < count; i += 1) {
+    // Upward-biased spread: real confetti is thrown up and falls, so a
+    // symmetric circle reads as an explosion rather than a celebration.
+    const angle = Math.PI + Math.random() * Math.PI;
+    const distance = 80 + Math.random() * 160;
+    particles.push({
+      id: i,
+      dx: `${Math.cos(angle) * distance}px`,
+      dy: `${Math.sin(angle) * distance}px`,
+      rot: `${Math.random() * 720 - 360}deg`,
+      delay: `${Math.random() * 150}ms`,
+      token: PARTICLE_TOKENS[i % PARTICLE_TOKENS.length]!,
+      emoji: emojis && emojis.length > 0 ? emojis[i % emojis.length] : undefined,
+    });
+  }
+  return particles;
+}
+
+/** Whether the user has asked for less motion. */
+function prefersReducedMotion(): boolean {
+  if (typeof window === "undefined" || !window.matchMedia) return false;
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+export interface StyledConfettiProps {
+  /** Rising edge fires the celebration. Falling edge re-arms it. */
+  trigger?: boolean;
+  particleCount?: number;
+  emojis?: ReadonlyArray<string> | undefined;
+  /** Swap in a host implementation — see `CelebrateFn`. */
+  celebrate?: CelebrateFn | undefined;
+  /** Fires when the celebration has finished, however it was rendered. */
+  onComplete?: (() => void) | undefined;
+}
+
+/**
+ * A celebration, fired by a rising edge on `trigger`.
+ *
+ * ```tsx
+ * <StyledConfetti trigger={saved} onComplete={() => setSaved(false)} />
+ * ```
+ *
+ * ## The default is a real burst, not a no-op
+ *
+ * The component this replaces imported `js-confetti` — a dependency on every
+ * consumer for a decoration three call sites use. The seam is `celebrate`; the
+ * default is a CSS-only burst of themed particles, which needs no canvas, no
+ * library, and no host wiring.
+ *
+ * A no-op default was the other option the issue offered and would have been
+ * the weaker one: "nothing happens" is indistinguishable from "the seam is
+ * broken", and it is the reading someone reaches for first.
+ *
+ * ## It honours `prefers-reduced-motion`, and by skipping rather than shortening
+ *
+ * Confetti is purely decorative — it carries no information — which is exactly
+ * the category a reduced-motion preference is about. So when the preference is
+ * set the burst does not play at all, and **`onComplete` still fires**. That
+ * second half matters more than it looks: hosts commonly use `onComplete` to
+ * reset the trigger, so swallowing it would leave the flag stuck true and the
+ * celebration permanently armed.
+ *
+ * The check is deliberately made at fire time rather than subscribed to. A
+ * user changing the preference mid-burst is not worth a listener, and reading
+ * it during render would make the component's output differ between server and
+ * first client paint.
+ */
+export const StyledConfetti: React.FC<StyledConfettiProps> = ({
+  trigger = false,
+  particleCount = 60,
+  emojis,
+  celebrate,
+  onComplete,
+}) => {
+  const [particles, setParticles] = React.useState<Particle[] | null>(null);
+  const hasFired = React.useRef(false);
+
+  // The callback is held in a ref so it is not a dependency of the effect
+  // below. A host writing `onComplete={() => setSaved(false)}` inline passes a
+  // new function every render, which as a dependency would re-run the effect
+  // and re-fire the burst on every parent render.
+  const onCompleteRef = React.useRef(onComplete);
+  React.useEffect(() => {
+    onCompleteRef.current = onComplete;
+  }, [onComplete]);
+
+  React.useEffect(() => {
+    if (!trigger) {
+      // Falling edge re-arms, so the same component can celebrate twice.
+      hasFired.current = false;
+      return;
+    }
+    if (hasFired.current) return;
+    hasFired.current = true;
+
+    if (celebrate !== undefined) {
+      const result = celebrate({ particleCount, emojis });
+      if (result && typeof (result as Promise<unknown>).then === "function") {
+        // The SAME handler on both arms, rather than `.finally()`.
+        //
+        // Two things have to be true at once. A host implementation that
+        // rejects must still release the trigger — `onComplete` is what a host
+        // resets its flag in, so skipping it leaves the celebration armed for
+        // ever and nothing can fire again. And the rejection must be
+        // *consumed*: `.finally()` returns a promise that rejects onward, so it
+        // would satisfy the first requirement while emitting an unhandled
+        // rejection into the host's console for a decoration that failed. A
+        // two-armed `.then` does both.
+        void (result as Promise<unknown>).then(
+          () => onCompleteRef.current?.(),
+          () => onCompleteRef.current?.(),
+        );
+      } else {
+        onCompleteRef.current?.();
+      }
+      return;
+    }
+
+    if (prefersReducedMotion()) {
+      onCompleteRef.current?.();
+      return;
+    }
+
+    setParticles(buildParticles(particleCount, emojis));
+    const timer = setTimeout(() => {
+      setParticles(null);
+      onCompleteRef.current?.();
+    }, BURST_MS);
+
+    return () => clearTimeout(timer);
+  }, [trigger, particleCount, emojis, celebrate]);
+
+  if (particles === null) return null;
+
+  return (
+    <div
+      data-testid="styled-confetti"
+      // Decoration, and nothing else. `aria-hidden` because there is nothing
+      // here to announce, and `pointer-events: none` because a celebration
+      // that swallows the click on the button underneath it is a real bug.
+      aria-hidden="true"
+      className={css({
+        position: "fixed",
+        inset: "0",
+        pointerEvents: "none",
+        overflow: "hidden",
+        display: "grid",
+        placeItems: "center",
+        zIndex: "50",
+      })}
+    >
+      {particles.map((p) => (
+        <span
+          key={p.id}
+          data-testid="styled-confetti-particle"
+          className={cx(
+            css({
+              gridArea: "1 / 1",
+              width: "8px",
+              height: "8px",
+              borderRadius: "sm",
+              animation: "stonedogConfettiBurst 1.2s ease-out forwards",
+            }),
+            // Omitted for an emoji particle: the glyph is the decoration, and a
+            // coloured square behind it is not.
+            p.emoji === undefined ? PARTICLE_CLASS[p.token] : undefined,
+          )}
+          style={
+            {
+              // Per-particle values feeding the shared keyframe. See the
+              // keyframe's own comment for why these are custom properties and
+              // why they are not the theme namespace.
+              "--sd-confetti-dx": p.dx,
+              "--sd-confetti-dy": p.dy,
+              "--sd-confetti-rot": p.rot,
+              animationDelay: p.delay,
+              // An emoji particle is a glyph, so it must not also be a coloured
+              // square behind that glyph.
+              ...(p.emoji !== undefined
+                ? { fontSize: "1.5rem", width: "auto", height: "auto" }
+                : {}),
+            } as React.CSSProperties
+          }
+          {...(p.emoji === undefined
+            ? { "data-particle-token": p.token }
+            : {})}
+        >
+          {p.emoji}
+        </span>
+      ))}
+    </div>
+  );
+};
+
+export default StyledConfetti;

package/src/components/StyledFieldErrors.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import React from "react";
+import { css } from "styled-system/css";
+import StyledAlert from "./StyledAlert";
+
+/**
+ * One validation failure.
+ *
+ * `path` is the field it belongs to, as segments — `["address", "postcode"]`.
+ * An array rather than a dotted string because that is the shape every
+ * validator already produces, and joining is lossy in the one case that
+ * matters: a key containing a dot becomes indistinguishable from nesting.
+ */
+export interface FieldError {
+  path: ReadonlyArray<string | number>;
+  message: string;
+}
+
+export interface StyledFieldErrorsProps {
+  errors: ReadonlyArray<FieldError>;
+  /** Heading above the list. */
+  title?: React.ReactNode;
+  className?: string;
+}
+
+/**
+ * A summary of validation failures.
+ *
+ * ```tsx
+ * <StyledFieldErrors errors={result.error.issues} />
+ * ```
+ *
+ * ## Renamed from `StyledZodErrorDisplay`, and that is the whole point
+ *
+ * The component it replaces took `z.ZodIssue[]`, which put **zod in the
+ * dependency list of a design system** — imposed on every consumer, including
+ * ones that validate with something else or not at all (NEH-430).
+ *
+ * Nothing about rendering a list of field errors is zod-specific. `FieldError`
+ * is structurally what `ZodIssue` already is for these purposes, so a zod host
+ * passes `result.error.issues` **unchanged** — `ZodIssue` has both `path` and
+ * `message` — and a yup/valibot/hand-rolled host maps two fields. The rename is
+ * not cosmetic: `StyledZodErrorDisplay` is a name that tells every reader the
+ * package knows about zod, which is the thing being removed.
+ *
+ * ## Two behaviours that deliberately differ from the original
+ *
+ * **It is not dismissible.** The original carried a `dismissed` state and an
+ * effect resetting it whenever `errors` changed. A summary the user can dismiss
+ * while the errors are still there — and while the submit button still refuses
+ * — is a way to hide the explanation for a form that will not submit. If a host
+ * wants that, it can conditionally render this component, which is clearer at
+ * the call site than a hidden state inside it.
+ *
+ * **It paints from tokens, not from `red.*`.** The original used `red.50` /
+ * `red.200` / `red.900/30` and a `_dark` block, which is a literal palette
+ * colour: right in one theme, wrong in every other, and invisible to the
+ * contrast floor. This delegates to `StyledAlert status="error"`, so it inherits
+ * the error tokens, the `role="alert"` announcement, and the non-colour glyph.
+ */
+export const StyledFieldErrors = React.forwardRef<
+  HTMLDivElement,
+  StyledFieldErrorsProps
+>(function StyledFieldErrors(
+  { errors, title = "Please fix the following:", className },
+  ref,
+) {
+  // Nothing to say, so say nothing. Rendering an empty alert would announce
+  // itself to a screen reader — `role="alert"` is an assertive live region —
+  // and interrupt the user to tell them about no problems.
+  if (errors.length === 0) return null;
+
+  return (
+    <StyledAlert
+      ref={ref}
+      status="error"
+      title={title}
+      {...(className !== undefined ? { className } : {})}
+    >
+      <ul className={css({ listStyle: "disc", paddingInlineStart: "5" })}>
+        {errors.map((error, index) => (
+          // The path is part of the key because two fields commonly fail the
+          // same rule with the same message ("Required"), and a message-only
+          // key would collide. The index is the tail-breaker for the case where
+          // one field carries two failures.
+          <li key={`${error.path.join(".")}-${index}`}>{error.message}</li>
+        ))}
+      </ul>
+    </StyledAlert>
+  );
+});
+
+export default StyledFieldErrors;