@stonedogcode/style 0.13.0 → 0.15.0

package/README.md

@@ -12,7 +12,7 @@ the whole component set re-skins at runtime. No component here knows a colour.
 
 ## Status
 
-Early. The preset is complete (22 recipes, 43 colour tokens); the component set
+Early. The preset is complete (23 recipes, 43 colour tokens); the component set
 is being extracted incrementally and currently covers the layout and typography
 primitives. See [CLAUDE.md](./CLAUDE.md) for the architecture and the
 contribution rules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonedogcode/style",
-  "version": "0.13.0",
+  "version": "0.15.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.",

package/src/components/StyledLink.tsx

@@ -2,7 +2,7 @@
 
 import React from "react";
 import { buttonRecipe } from "styled-system/recipes";
-import { cx } from "styled-system/css";
+import { css, cx } from "styled-system/css";
 import { useLinkComponent, useResolvedVariant } from "../config/style-config";
 import { ALL_VARIANTS } from "../config/types";
 
@@ -17,6 +17,15 @@ import { ALL_VARIANTS } from "../config/types";
  */
 const LINK_VARIANTS = ALL_VARIANTS;
 
+/**
+ * How a link sits in its surroundings.
+ *
+ * `text` is the default and the safe one: a link in a sentence must not become
+ * a 48px control. `flow` is the layout participant. `control` is the tap
+ * target, and carries the house 48px floor.
+ */
+export type LinkPresentation = "text" | "flow" | "control";
+
 export interface StyledLinkProps
   extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
   /** Where the link goes. */
@@ -55,6 +64,61 @@ export interface StyledLinkProps
    */
   externalIndicator?: React.ReactNode;
   variant?: string;
+  /**
+   * Render as a standalone control with a 48x48 tap target, rather than as
+   * text inside a sentence.
+   *
+   * **The default is inline, and that is deliberate rather than a shortcut.**
+   * `buttonRecipe`'s base states `min-height: 48px`, `display: inline-flex`
+   * and padding — correct for a control, and wrong for a link in a paragraph,
+   * where it forces a 48px line box and breaks the text flow. Measured at
+   * 48.375px before this prop existed.
+   *
+   * Inline is also what the standard expects: WCAG 2.5.5 and 2.5.8 both carve
+   * out targets that are "in a sentence or block of text", so a text link at
+   * text height is conformant. The floor applies to the standalone case, and
+   * `standalone` is how a nav item, a card action or a button-shaped link asks
+   * for it.
+   *
+   * @deprecated Use `presentation` instead — `standalone` maps to
+   * `presentation="control"`. It is kept because it is public API and consumers
+   * pass it today; it will be removed once they have moved.
+   */
+  standalone?: boolean;
+  /**
+   * How the link sits in its surroundings. Three cases, because there are
+   * genuinely three (NEH-728).
+   *
+   * | | display | min-height | for |
+   * |---|---|---|---|
+   * | `text` (default) | `inline` | none | a link inside a sentence |
+   * | `flow` | `inline-flex` | none | a link that is a layout participant |
+   * | `control` | `inline-flex` | **48px** | a nav item, a card action |
+   *
+   * ## Why `flow` had to exist
+   *
+   * `text` and `control` look like they cover the space, and they do not. A
+   * link that is neither prose nor a tap target is extremely common — a row in
+   * a list, a cell in a grid, anything given a width by its parent — and
+   * HopperGuard had 67 of them (NEH-728).
+   *
+   * Neither of the other two can express it, and **both fail silently**:
+   *
+   * - `control` adds the 48px floor to links that are not tap targets, which
+   *   changes layout everywhere it is wrong.
+   * - `text` sets `display: inline`, and on a non-replaced inline box **`width`
+   *   does not apply** and **`margin-left: auto` does nothing** — so a `w` prop
+   *   becomes a no-op and a right-hand icon loses its push-to-end. No build
+   *   error, no type error, no warning; the link just renders wrong.
+   *
+   * `flow` is inline-flex without the floor: it takes a width, it lays its
+   * icons out, and it does not claim to be a 48px target when it is not.
+   *
+   * **Do not reach for `flow` to escape the tap-target floor on something that
+   * IS a control.** The floor is a house minimum, not a default to be routed
+   * around; `control` is the honest answer for anything a finger aims at.
+   */
+  presentation?: LinkPresentation;
 }
 
 /** The default external-destination glyph — "↗", north-east arrow. */
@@ -83,6 +147,8 @@ export const StyledLink = React.forwardRef<HTMLAnchorElement, StyledLinkProps>(
       rightIcon,
       externalIndicator,
       variant,
+      standalone = false,
+      presentation,
       className,
       ...rest
     },
@@ -90,7 +156,38 @@ export const StyledLink = React.forwardRef<HTMLAnchorElement, StyledLinkProps>(
   ) {
     const HostLink = useLinkComponent();
     const resolved = useResolvedVariant(variant ?? "link", LINK_VARIANTS);
-    const classes = cx(buttonRecipe({ variant: resolved }), className);
+
+    /*
+     * `presentation` wins; `standalone` is the deprecated spelling of
+     * `control`. Resolved in one place so there is no call site where the two
+     * disagree and the answer depends on which branch is read first.
+     */
+    const mode: LinkPresentation =
+      presentation ?? (standalone ? "control" : "text");
+
+    // The variant still comes from `buttonRecipe`, so colour, underline and
+    // hover stay one definition shared with every other control. Only the BOX
+    // is overridden — the properties that make a control a control are exactly
+    // the ones that break a sentence.
+    const classes = cx(
+      buttonRecipe({ variant: resolved }),
+      mode === "control"
+        ? undefined
+        : css({
+            /*
+             * `text` goes fully inline so it sits in a line box like any other
+             * word. `flow` stays a flex container: it is a layout participant,
+             * and on a non-replaced inline box `width` does not apply and
+             * `margin-left: auto` does nothing — so an inline `flow` would
+             * silently drop both (NEH-728).
+             */
+            display: mode === "flow" ? "inline-flex" : "inline",
+            minHeight: "0",
+            minWidth: "0",
+            padding: "0",
+          }),
+      className,
+    );
 
     const indicator =
       externalIndicator === undefined ? EXTERNAL_GLYPH : externalIndicator;

package/src/components/StyledTag.tsx

@@ -2,10 +2,51 @@
 
 import React from "react";
 import { css, cx } from "styled-system/css";
+import { tagRecipe } from "styled-system/recipes";
+import type { AlertStatus } from "./StyledAlert";
+
+/**
+ * A tag's tone.
+ *
+ * The four status names ARE `AlertStatus`, referenced rather than retyped, so
+ * the package cannot drift into two status vocabularies — a green that means
+ * "success" on a banner and "active" on a tag is the kind of divergence nobody
+ * notices until a product has both.
+ *
+ * `neutral` and `accent` extend it. `neutral` is the historical appearance and
+ * stays the default; `accent` exists because a tag is frequently just a
+ * *category* — a type, a group, a label — and forcing those into `info` would
+ * make "informational" mean nothing.
+ */
+export type TagTone = "neutral" | AlertStatus | "accent";
 
 export interface StyledTagProps
   extends Omit<React.HTMLAttributes<HTMLSpanElement>, "onSelect"> {
   children: React.ReactNode;
+  /**
+   * The tag's colour, carrying meaning.
+   *
+   * ## Colour must not be the only signal (WCAG 1.4.1, Level A)
+   *
+   * Usually it is not, and that is why there is no forced glyph here: a tag
+   * generally *is* its label, so `<StyledTag tone="success">Enabled</StyledTag>`
+   * says "enabled" in words and the colour merely reinforces it. `StyledAlert`
+   * needs a glyph because a banner's status is genuinely carried by its
+   * colouring; a tag's is carried by its text.
+   *
+   * **The exception is a tag whose label does not name its own state** — a
+   * feature name tinted green for on and grey for off, say. There the colour is
+   * the only signal and the criterion is unmet, so pass `indicator`.
+   */
+  tone?: TagTone;
+  /**
+   * A non-colour signal rendered before the label.
+   *
+   * Deliberately not defaulted per tone. See `tone` above: defaulting one would
+   * put a glyph on every tag in every consumer to fix the minority of cases
+   * where the label does not already say what the colour says.
+   */
+  indicator?: React.ReactNode;
   /**
    * Show a remove control, and call this when it is activated.
    *
@@ -49,33 +90,29 @@ export interface StyledTagProps
  */
 export const StyledTag = React.forwardRef<HTMLSpanElement, StyledTagProps>(
   function StyledTag(
-    { children, onRemove, removeLabel = "Remove", className, ...rest },
+    {
+      children,
+      tone = "neutral",
+      indicator,
+      onRemove,
+      removeLabel = "Remove",
+      className,
+      ...rest
+    },
     ref,
   ) {
     return (
       <span
         ref={ref}
-        className={cx(
-          css({
-            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",
-            backgroundColor: "boxBgSecondary",
-            color: "textSecondary",
-            // Not a tap target: a plain tag is not interactive, so the 48px
-            // floor does not apply to it. The remove BUTTON below is, and does.
-            fontSize: "sm",
-            whiteSpace: "nowrap",
-          }),
-          className,
-        )}
+        /*
+         * The recipe, not an inline `css()` — see `preset/recipes/tag.ts`. A
+         * tone computed at runtime (`tone={STATUS_COLOR[status]}`) is invisible
+         * to Panda's extractor, and `staticCssRecipes` is what covers it.
+         */
+        className={cx(tagRecipe({ tone }), className)}
         {...rest}
       >
+        {indicator !== undefined && <span aria-hidden="true">{indicator}</span>}
         <span>{children}</span>
         {onRemove !== undefined && (
           <button

package/src/index.ts

@@ -204,10 +204,10 @@ export type { StyledFormLabelProps } from "./components/StyledFormLabel";
 // that stops it working.
 // ---------------------------------------------------------------------------
 export { default as StyledLink, StyledLink as Link } from "./components/StyledLink";
-export type { StyledLinkProps } from "./components/StyledLink";
+export type { StyledLinkProps, LinkPresentation } from "./components/StyledLink";
 
 export { default as StyledTag, StyledTag as Tag } from "./components/StyledTag";
-export type { StyledTagProps } from "./components/StyledTag";
+export type { StyledTagProps, TagTone } from "./components/StyledTag";
 
 export {
   default as StyledFieldErrors,

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

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",
+  },
+});