@stonedogcode/style 0.12.0 → 0.15.0

package/src/config/link-component.tsx

@@ -0,0 +1,69 @@
+"use client";
+
+import React from "react";
+
+/**
+ * The props any link implementation must accept.
+ *
+ * Deliberately the native anchor's own surface plus a required `href`. That is
+ * not a compromise to keep the type simple — it is the boundary. A router's
+ * link component accepts these and adds its own (prefetch, scroll, replace);
+ * this package neither knows nor passes those, so the extra props stay the
+ * host's business and no routing concept leaks in here.
+ *
+ * `href` is a `string`, not `string | UrlObject`. Next.js accepts the object
+ * form, but naming it here would put a Next.js type in a package whose whole
+ * premise is that it has none — and a host that wants the object form can wrap
+ * its own component and take it there, which is exactly what the seam is for.
+ */
+export interface LinkComponentProps
+  extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  href: string;
+  children?: React.ReactNode;
+}
+
+/**
+ * What `StyledLink` renders for an in-app destination.
+ *
+ * A host swaps in its router's link — `next/link`, `react-router`'s `Link`,
+ * whatever it has — and gets client-side navigation and prefetching. A host
+ * that says nothing gets `DefaultLinkComponent` below.
+ *
+ * Typed as a component rather than an `ElementType` union so the intrinsic
+ * `"a"` string is not a valid value. Allowing it would mean two ways to say the
+ * same thing, and the one that looks simpler is the one that cannot be given a
+ * `displayName` or wrapped.
+ *
+ * **It must forward its ref to the underlying anchor.** `RefAttributes` is in
+ * the props type rather than left implicit because this package's peer range
+ * starts at React 18, where a `ref` handed to a plain function component is not
+ * a prop — React 18 drops it and logs "Function components cannot be given
+ * refs". Stating it in the type is what makes that a compile error for the host
+ * instead of a console warning nobody reads. `next/link` and react-router's
+ * `Link` both forward already, so the common cases need nothing.
+ */
+export type LinkComponent = React.ComponentType<
+  LinkComponentProps & React.RefAttributes<HTMLAnchorElement>
+>;
+
+/**
+ * A plain anchor, and the reason this seam is safe to leave unconfigured.
+ *
+ * This is the point of the whole arrangement (NEH-430): the default is not a
+ * placeholder that throws, warns, or renders nothing until someone wires a
+ * router. It is a **real, correct, accessible link** — it navigates, it opens in
+ * a new tab when told to, middle-click and "open in new window" work, and a
+ * screen reader announces it as a link. What a host gains by overriding is
+ * client-side navigation and prefetching: real benefits, and neither of them
+ * load-bearing for the link *working*.
+ *
+ * A seam whose default is broken is a required configuration step wearing a
+ * disguise, and it recreates exactly the adoption deadlock this issue set out
+ * to remove.
+ */
+export const DefaultLinkComponent: LinkComponent = React.forwardRef<
+  HTMLAnchorElement,
+  LinkComponentProps
+>(function DefaultLinkComponent(props, ref) {
+  return <a ref={ref} {...props} />;
+}) as LinkComponent;

package/src/config/style-config.tsx

@@ -5,6 +5,7 @@ import type { DensityProfile, FontSizeProfile, IconSize, ThemeVariant } from "./
 import { resolveDensityStep, type DensityBase, type DensityStep } from "./density";
 import { THEME_VARIANTS } from "./types";
 import { IntentIconProvider, type IntentIcons } from "./intent-icons";
+import { DefaultLinkComponent, type LinkComponent } from "./link-component";
 
 /**
  * Everything this component library needs to know about the host application.
@@ -69,6 +70,26 @@ export interface StyleConfig {
    * (a business tool for a general audience) sets `"md"`.
    */
   iconSize: IconSize;
+
+  /**
+   * What `StyledLink` renders for an in-app destination (NEH-430).
+   *
+   * This is a seam, not a dependency. `StyledLink` used to import `next/link`
+   * directly, which is why it could not live in this package at all — CLAUDE.md
+   * names `next/*` as forbidden, and three products with three framework
+   * choices cannot be made to share one.
+   *
+   * The default is a plain `<a>`: a real, working, accessible link, not a
+   * placeholder. A host passes its router's component to gain client-side
+   * navigation and prefetching, and gains nothing else — so an unconfigured
+   * host is not broken, merely un-optimised.
+   *
+   * Note this is the only field here whose value is a *component*. It sits on
+   * `StyleConfig` rather than being a `StyledLink` prop because the choice is
+   * app-wide by nature: passing it per call site is how ~40 links end up with
+   * two navigation behaviours and no way to retune either.
+   */
+  linkComponent: LinkComponent;
 }
 
 /**
@@ -91,6 +112,10 @@ export const DEFAULT_STYLE_CONFIG: StyleConfig = {
   // what the originating application already renders. Changing it would be an
   // invisible, app-wide visual change to every existing consumer.
   iconSize: "2x",
+  // A plain anchor. Unlike `iconSize` above this is genuinely the safe middle:
+  // it navigates correctly everywhere, and a host overriding it is opting into
+  // an improvement rather than repairing a default.
+  linkComponent: DefaultLinkComponent,
 };
 
 const StyleConfigContext = createContext<StyleConfig>(DEFAULT_STYLE_CONFIG);
@@ -143,6 +168,7 @@ export function StonedogStyleProvider({
   iconSize,
   density,
   densityBase,
+  linkComponent,
   icons,
 }: StonedogStyleProviderProps) {
   const value = useMemo<StyleConfig>(
@@ -153,8 +179,9 @@ export function StonedogStyleProvider({
       iconSize: iconSize ?? DEFAULT_STYLE_CONFIG.iconSize,
       density: density ?? DEFAULT_STYLE_CONFIG.density,
       densityBase: densityBase ?? DEFAULT_STYLE_CONFIG.densityBase,
+      linkComponent: linkComponent ?? DEFAULT_STYLE_CONFIG.linkComponent,
     }),
-    [fontSizeProfile, variant, iconSize, density, densityBase],
+    [fontSizeProfile, variant, iconSize, density, densityBase, linkComponent],
   );
 
   return (
@@ -196,6 +223,17 @@ export function useIconSize(): IconSize {
   return useStyleConfig().iconSize;
 }
 
+/**
+ * The host's link implementation, or a plain `<a>` if it supplied none.
+ *
+ * Exported so an application component outside this package can render a link
+ * the same way `StyledLink` does, without reaching for the router directly and
+ * re-creating the coupling the seam removed.
+ */
+export function useLinkComponent(): LinkComponent {
+  return useStyleConfig().linkComponent;
+}
+
 /**
  * Resolve a control's appearance: **the caller's, else the user's app-wide
  * setting, else `solid`.**

package/src/index.ts

@@ -20,6 +20,7 @@ export {
   useStyleConfig,
   useFontSizeProfile,
   useIconSize,
+  useLinkComponent,
   useResolvedVariant,
   DEFAULT_STYLE_CONFIG,
 } from "./config/style-config";
@@ -28,6 +29,10 @@ export type {
   StonedogStyleProviderProps,
 } from "./config/style-config";
 
+/** The link seam — see `config/link-component.tsx` and NEH-430. */
+export { DefaultLinkComponent } from "./config/link-component";
+export type { LinkComponent, LinkComponentProps } from "./config/link-component";
+
 /**
  * Deprecated `Hopper*` aliases — NEH-251. See `config/style-config.tsx`.
  * Removed once every consumer has landed its rename PR.
@@ -192,6 +197,43 @@ export type { StyledTooltipProps } from "./components/StyledTooltip";
 export { default as StyledFormLabel } from "./components/StyledFormLabel";
 export type { StyledFormLabelProps } from "./components/StyledFormLabel";
 
+// ---------------------------------------------------------------------------
+// Components that were blocked on a runtime dependency until NEH-430 gave each
+// a seam with a working default. None of them adds a dependency; the host
+// supplies the framework-specific half, or takes the default and loses nothing
+// that stops it working.
+// ---------------------------------------------------------------------------
+export { default as StyledLink, StyledLink as Link } from "./components/StyledLink";
+export type { StyledLinkProps, LinkPresentation } from "./components/StyledLink";
+
+export { default as StyledTag, StyledTag as Tag } from "./components/StyledTag";
+export type { StyledTagProps, TagTone } from "./components/StyledTag";
+
+export {
+  default as StyledFieldErrors,
+  StyledFieldErrors as FieldErrors,
+} from "./components/StyledFieldErrors";
+export type {
+  StyledFieldErrorsProps,
+  FieldError,
+} from "./components/StyledFieldErrors";
+
+export { default as StyledPage, StyledPage as Page } from "./components/StyledPage";
+export type { StyledPageProps } from "./components/StyledPage";
+
+export { default as StyledForm, StyledForm as Form } from "./components/StyledForm";
+export type { StyledFormProps } from "./components/StyledForm";
+
+export {
+  default as StyledConfetti,
+  StyledConfetti as Confetti,
+} from "./components/StyledConfetti";
+export type {
+  StyledConfettiProps,
+  CelebrateFn,
+  CelebrateOptions,
+} from "./components/StyledConfetti";
+
 export { default as StyledInputBool } from "./components/StyledInputBool";
 export type { StyledInputBoolProps, InputBoolVariant } from "./components/StyledInputBool";
 export { INPUT_BOOL_VARIANTS } from "./components/StyledInputBool";

package/src/preset/index.ts

@@ -25,6 +25,7 @@ import {
 } from "./recipes/separator";
 import { stackRecipe } from "./recipes/stack";
 import { stripedRecipe } from "./recipes/striped";
+import { tagRecipe } from "./recipes/tag";
 import { textRecipe } from "./recipes/text";
 import { tooltipRecipe } from "./recipes/tooltip";
 
@@ -83,6 +84,7 @@ const recipes = {
   separatorVerticalRecipe,
   stackRecipe,
   stripedRecipe,
+  tagRecipe,
   textRecipe,
   tooltipRecipe,
 };
@@ -135,7 +137,7 @@ const staticCssAlignment = [
 
 /**
  * The @stonedogcode/style Panda preset: colour tokens, breakpoints, keyframes, and
- * the 22 recipes the component library is built on.
+ * the 23 recipes the component library is built on.
  *
  * Deliberately does NOT set `globalCss`, `preflight`, `include`, or `outdir` —
  * those are application decisions, and a preset that quietly restyles `body` is
@@ -195,6 +197,34 @@ export function stonedogStylePreset(options: StonedogStylePresetOptions = {}) {
             "0%": { transform: "scaleX(0)" },
             "100%": { transform: "scaleX(1)" },
           },
+          /**
+           * One confetti particle's flight — `StyledConfetti`'s zero-dependency
+           * default (NEH-430).
+           *
+           * The three `--sd-confetti-*` properties are set inline, per
+           * particle, so one keyframe serves a whole burst travelling in every
+           * direction. A keyframe cannot randomise, and a hundred generated
+           * keyframes would be a hundred rules in every consumer's stylesheet.
+           *
+           * **These are NOT the theme namespace and must not be confused with
+           * it.** CLAUDE.md's rule — never write `var(--…)` for anything the
+           * HOST supplies — is about `--<prefix>-*` properties that a theme
+           * defines and `cssVarPrefix` re-points. These are component-internal,
+           * written and read in the same breath by the same component, and
+           * named `--sd-confetti-*` precisely so they cannot collide with a
+           * host's namespace. The particle's COLOUR still comes from a token.
+           */
+          stonedogConfettiBurst: {
+            "0%": {
+              transform: "translate3d(0, 0, 0) rotate(0deg)",
+              opacity: "1",
+            },
+            "100%": {
+              transform:
+                "translate3d(var(--sd-confetti-dx, 0), var(--sd-confetti-dy, 0), 0) rotate(var(--sd-confetti-rot, 0deg))",
+              opacity: "0",
+            },
+          },
         },
         recipes,
       },

package/src/preset/recipes/input-bool.ts

@@ -24,9 +24,16 @@ export const inputBoolRecipe = defineSlotRecipe({
        * Verified in the component-test harness rather than assumed: a raw
        * checkbox given a red 2px border and a slate background paints as the
        * default white box. The UA draws the widget and discards
-       * `background-color`, `border-*` and `border-radius` — while
-       * `getComputedStyle` cheerfully reports all of them, which is what made
-       * this recipe look styled for so long.
+       * `background-color` and `border-*` — while `getComputedStyle`
+       * cheerfully reports both, which is what made this recipe look styled
+       * for so long.
+       *
+       * `border-radius` is worse still and worth separating out (NEH-310): it
+       * does not even COMPUTE. A control set to `9999px` reports `0px`, so it
+       * cannot be asserted on, cannot be differed by, and is not merely
+       * invisible. The `borderRadius: "md"` below is therefore inert too; it is
+       * kept only because it belongs to the same `appearance: none` fallback
+       * set as `border` and `background-color`.
        *
        * The three it DOES honour, and therefore the only levers here:
        * `accent-color` (the checked fill and tick), `box-shadow` (painted
@@ -77,9 +84,21 @@ export const inputBoolRecipe = defineSlotRecipe({
        *
        * `buttonRecipe` expresses outline as a 2px edge with squared corners.
        * A native checkbox discards `border`, so the same reading is carried by
-       * a `box-shadow` ring, which it does paint — squared to match, and
-       * themed. `solid` states `none` explicitly rather than by omission, so
-       * switching between them cannot leave a ring behind.
+       * a `box-shadow` ring, which it does paint — themed. `solid` states
+       * `none` explicitly rather than by omission, so switching between them
+       * cannot leave a ring behind.
+       *
+       * **The squared corners were dropped in NEH-310, because they never
+       * existed.** This comment used to say the ring was "squared to match",
+       * and the variant carried `borderRadius: "0"` to do it. Probed in the
+       * harness: Chromium computes `border-radius: 0px` on a checkbox at
+       * `appearance: auto` **whatever the stylesheet says** — a control set to
+       * `9999px` reports `0px`, while a plain `<span>` beside it reports its
+       * `12px` correctly. So the property is not merely discarded at paint
+       * time like `background-color`; it does not even compute, and no variant
+       * here can differ by corner. The declaration is removed rather than left
+       * as decoration, since a recipe full of inert declarations is the exact
+       * condition that made this defect take three issues to find.
        */
       solid: {
         control: {
@@ -100,18 +119,60 @@ export const inputBoolRecipe = defineSlotRecipe({
            * different — and made a ticked outline checkbox a dark box on a dark
            * surface, which is the checked state, the one thing the control
            * exists to communicate. Distinguishing an appearance must not cost
-           * state legibility, so the difference is carried entirely by the ring
-           * and the corners.
+           * state legibility, so the difference is carried entirely by the
+           * ring.
            */
           accentColor: "buttonBgPrimary",
           boxShadow: "0 0 0 2px {colors.borderBgPrimary}",
-          borderRadius: "0",
         },
       },
+      /**
+       * The remaining variants, given a painted difference (NEH-310).
+       *
+       * NEH-234 fixed `solid` vs `outline` and stopped there, so these still
+       * differed only in `background`, `background-image`, `color` and a
+       * pseudo-element — every one of which this control discards. A user
+       * picking `aurora` app-wide watched every other control change and every
+       * checkbox stay put: the same complaint NEH-234 was filed for, one layer
+       * down.
+       *
+       * ## The rule they all follow
+       *
+       * **Appearance is carried by the ring; the checked colour never varies.**
+       *
+       * Not a stylistic choice — it is the lesson recorded on `outline` above.
+       * Giving a variant a recessive `accentColor` did make it more distinct,
+       * and made a ticked box dark-on-dark: illegible in the one state the
+       * control exists to communicate. So every variant keeps
+       * `accentColor: buttonBgPrimary` and differs by `box-shadow` alone.
+       *
+       * `outline` (the CSS property) is not available as a lever either: it is
+       * the focus ring, and a variant using it would look permanently focused.
+       * `border-radius` is not available because it does not even COMPUTE here
+       * — see the note on the `outline` variant.
+       *
+       * ## What this deliberately does NOT attempt
+       *
+       * `aurora` is a gradient and `glass` is a blur; a box-shadow ring is
+       * neither. These are **approximations** — a two-tone ring, a soft halo —
+       * not renderings of the intent. The real thing needs `appearance: none`
+       * plus a hand-drawn tick, which means owning forced-colors mode and every
+       * engine's default widget, and this repo's CT tier is Chromium-only so it
+       * cannot answer that. NEH-310 names it as option 2 and says it needs
+       * someone to look at the result in more than one engine.
+       *
+       * The unpainted `bg` / `color` / gradient declarations are left exactly
+       * as they were, per the note in `base`.
+       */
       aurora: {
         control: {
           backgroundImage: "linear-gradient(to right, #ff7e5f, #feb47b)",
           color: "buttonTextPrimary",
+          accentColor: "buttonBgPrimary",
+          // Two stops, two rings — the nearest a box-shadow gets to the
+          // gradient this variant means. Layers paint inner-first.
+          boxShadow:
+            "0 0 0 2px {colors.borderBgAccent}, 0 0 0 4px {colors.borderBgPrimary}",
         },
       },
       glass: {
@@ -120,7 +181,6 @@ export const inputBoolRecipe = defineSlotRecipe({
           overflow: "hidden",
           bg: "buttonBgPrimary/20",
           color: "textPrimary/10",
-          boxShadow: "xl",
           backdropFilter: "blur(8px)",
           fontWeight: "bold",
           lineHeight: "shorter",
@@ -135,6 +195,19 @@ export const inputBoolRecipe = defineSlotRecipe({
               "linear(to-br, rgba(255,255,255,0.1), rgba(255,255,255,0.05))",
             zIndex: -1,
           },
+          accentColor: "buttonBgPrimary",
+          // A soft halo rather than a hard edge — the nearest painted reading
+          // of "frosted".
+          //
+          // This REPLACES the `boxShadow: "xl"` this variant used to carry
+          // (removed above, not shadowed — a second `boxShadow` key here was a
+          // TS1117 duplicate-property error that the CSS build silently
+          // resolved in favour of the last one). `xl` was the only thing glass
+          // ever painted, and it is Panda's own neutral shadow: the same grey
+          // in every theme this package can wear, which is the one thing a
+          // themeable package must not ship.
+          boxShadow:
+            "0 0 0 1px {colors.borderBgSecondary}, 0 0 12px 2px {colors.boxshadowBgAccent}",
         },
       },
       matte: {
@@ -145,18 +218,46 @@ export const inputBoolRecipe = defineSlotRecipe({
           // is a FIXED dark gradient, so themed text on it risks dark-on-dark.
           color: "white",
           fontWeight: "bold",
+          accentColor: "buttonBgPrimary",
+          // Wide, blurred and low-contrast: a matte surface absorbs light
+          // rather than edging it. The only soft-edged ring in the set, so it
+          // cannot be mistaken for `outline` at a glance.
+          boxShadow: "0 2px 8px 0 {colors.boxshadowBgSecondary}",
         },
       },
       ghost: {
         control: {
           color: "textSecondary",
           bg: "buttonBgSecondary",
+          accentColor: "buttonBgPrimary",
+          // The thinnest ring in the set, in the secondary border colour.
+          // `ghost` means "present but not asserting itself", which every other
+          // recipe expresses by having no fill — exactly the property this
+          // control discards.
+          boxShadow: "0 0 0 1px {colors.borderBgSecondary}",
         },
       },
+      /**
+       * `none` is the one variant that CANNOT be distinguished, and saying so
+       * is more useful than inventing a difference (NEH-310).
+       *
+       * Every lever this control has is additive — a ring, a halo, a checked
+       * colour. `none` means "do not style this", so the only honest rendering
+       * of it is the bare widget, which is what `solid` already is. Giving it a
+       * ring to make a test pass would mean the variant named `none` was the
+       * only one wearing decoration.
+       *
+       * So `none` and `solid` render identically, deliberately, and the
+       * component test asserts that pair is equal rather than skipping it —
+       * so if a future `appearance: none` redesign (option 2 on NEH-310) makes
+       * them separable, the test says so instead of quietly passing.
+       */
       none: {
         control: {
           color: "buttonTextPrimary",
           bg: "gray.300",
+          accentColor: "buttonBgPrimary",
+          boxShadow: "none",
         },
       },
       button: {

package/src/preset/recipes/tag.ts

@@ -0,0 +1,96 @@
+import { defineRecipe } from "@pandacss/dev";
+
+/**
+ * A small label, in one of six tones.
+ *
+ * ## Why this is a recipe and not `css()` in the component
+ *
+ * `StyledTag` painted itself with an inline `css()` call, which was right while
+ * it had exactly one appearance. A tone chosen at runtime is a different
+ * problem: Panda's extractor reads source text, so `tone={STATUS_COLOR[status]}`
+ * resolves to nothing and emits no rule — while the class name still lands in
+ * the DOM. The result is an unstyled tag, with no build error and no console
+ * warning.
+ *
+ * Recipes are the escape from that, because `staticCssRecipes` in
+ * `preset/index.ts` forces **every variant of every recipe** into the
+ * stylesheet. So a tone computed from a status map is covered for free, which is
+ * how the consuming apps actually use this (NEH-721: HopperGuard drives 109 of
+ * its 155 tags from `STATUS_COLOR[item.status]` and friends).
+ *
+ * ## The tones reuse StyledAlert's vocabulary exactly
+ *
+ * `info` / `success` / `warning` / `error` are `AlertStatus`, and each pairs the
+ * **same tokens** the alert recipe pairs. Two status vocabularies in one package
+ * — one for banners and a different one for tags — is how a product ends up with
+ * a green that means "success" in one place and "active" in another.
+ *
+ * Two tones are additional rather than borrowed:
+ *
+ * - **`neutral`** is the historical default and stays the default, so every
+ *   existing call site renders exactly as it did before this variant existed.
+ * - **`accent`** has no alert equivalent, because an alert is always *about*
+ *   something being fine or not. A tag is often just a category — a label, a
+ *   type, a group — and forcing those into `info` would make "informational"
+ *   mean nothing.
+ *
+ * ## No border, unlike the alert
+ *
+ * The alert recipe pairs each background with a `border*` token. A tag is small
+ * and usually appears in groups; a 1px edge on each turns a row of five into
+ * visual noise, and the tinted background already separates it from the page.
+ * The border tokens stay available if a consumer disagrees.
+ */
+export const tagRecipe = defineRecipe({
+  className: "tag",
+  base: {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: "1",
+    paddingInline: "2",
+    /*
+     * Vertical padding is deliberately absent: the height comes from the line
+     * box and the horizontal padding, so a tag tracks the font scale instead of
+     * needing a re-tune whenever it moves.
+     */
+    borderRadius: "md",
+    /*
+     * Not a tap target. A plain tag is not interactive, so the 48px floor does
+     * not apply to it — the remove BUTTON inside `StyledTag` is, and states its
+     * own.
+     */
+    fontSize: "sm",
+    whiteSpace: "nowrap",
+  },
+  variants: {
+    tone: {
+      neutral: {
+        backgroundColor: "boxBgSecondary",
+        color: "textSecondary",
+      },
+      info: {
+        backgroundColor: "boxInfo",
+        color: "textMain",
+      },
+      success: {
+        backgroundColor: "boxSuccess",
+        color: "textSuccess",
+      },
+      warning: {
+        backgroundColor: "boxWarning",
+        color: "textWarning",
+      },
+      error: {
+        backgroundColor: "boxError",
+        color: "textError",
+      },
+      accent: {
+        backgroundColor: "boxBgAccent",
+        color: "textMain",
+      },
+    },
+  },
+  defaultVariants: {
+    tone: "neutral",
+  },
+});