@stonedogcode/style 0.10.1 → 0.13.0

package/src/components/StyledForm.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+import React from "react";
+import { css, cx } from "styled-system/css";
+import StyledFieldErrors, { type FieldError } from "./StyledFieldErrors";
+
+export interface StyledFormProps
+  extends React.FormHTMLAttributes<HTMLFormElement> {
+  children: React.ReactNode;
+  /**
+   * Validation failures to summarise above the fields.
+   *
+   * `FieldError[]`, not `z.ZodIssue[]` — which is the whole reason this
+   * component can live here. A zod host passes `result.error.issues`
+   * unchanged; see `StyledFieldErrors`.
+   */
+  errors?: ReadonlyArray<FieldError>;
+  /** Heading for the error summary. */
+  errorsTitle?: React.ReactNode;
+}
+
+/**
+ * A form with a validation summary above its fields.
+ *
+ * ```tsx
+ * <StyledForm errors={issues} onSubmit={handleSubmit}>
+ *   <StyledInputText … />
+ * </StyledForm>
+ * ```
+ *
+ * ## It renders a real `<form>`, which the original did not
+ *
+ * The component this replaces rendered a `StyledBox` — a `<div>`. That is not
+ * a cosmetic difference:
+ *
+ * - **Enter does not submit a div.** Pressing Enter in a text input submits the
+ *   form it belongs to; in a div it does nothing, so every such form needed a
+ *   pointer.
+ * - **Assistive technology loses the form role**, and with it the ability to
+ *   navigate by form.
+ * - **`required`, `type="email"` and friends do nothing** without a form to
+ *   validate against, which is the native validation the seam strategy for this
+ *   component leans on.
+ *
+ * The summary is rendered *before* the fields deliberately: a summary below the
+ * inputs is one a keyboard user reaches only after passing everything it is
+ * telling them about.
+ */
+export const StyledForm = React.forwardRef<HTMLFormElement, StyledFormProps>(
+  function StyledForm(
+    { children, errors, errorsTitle, className, ...rest },
+    ref,
+  ) {
+    return (
+      <form
+        ref={ref}
+        className={cx(
+          css({ display: "flex", flexDirection: "column", gap: "3" }),
+          className,
+        )}
+        {...rest}
+      >
+        {errors !== undefined && errors.length > 0 && (
+          <StyledFieldErrors
+            errors={errors}
+            {...(errorsTitle !== undefined ? { title: errorsTitle } : {})}
+          />
+        )}
+        {children}
+      </form>
+    );
+  },
+);
+
+export default StyledForm;

package/src/components/StyledLink.tsx

@@ -0,0 +1,157 @@
+"use client";
+
+import React from "react";
+import { buttonRecipe } from "styled-system/recipes";
+import { cx } from "styled-system/css";
+import { useLinkComponent, useResolvedVariant } from "../config/style-config";
+import { ALL_VARIANTS } from "../config/types";
+
+/**
+ * The variants a link may take.
+ *
+ * `link` is included and is the default, which is why this list is passed to
+ * `useResolvedVariant` explicitly rather than letting it fall back to
+ * `THEME_VARIANTS`. Without it, `variant="link"` — the value nearly every call
+ * site wants — narrows to `solid` and every link renders as a filled button.
+ * That is the exact silent narrowing documented on `useResolvedVariant`.
+ */
+const LINK_VARIANTS = ALL_VARIANTS;
+
+export interface StyledLinkProps
+  extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+  /** Where the link goes. */
+  href: string;
+  children: React.ReactNode;
+  /**
+   * Marks the destination as outside this application.
+   *
+   * Two things follow, and both matter: the link renders through a plain `<a>`
+   * rather than the host's router (a client-side router cannot navigate to
+   * another origin, and handing it one is how a "link that does nothing" bug
+   * starts), and it gains a visible external indicator.
+   */
+  isExternal?: boolean;
+  /** Open in a new browsing context. */
+  newWindow?: boolean;
+  /**
+   * Renders the link inert.
+   *
+   * There is no `disabled` attribute for an anchor, so this removes `href` —
+   * which is what actually stops activation and takes the element out of the
+   * tab order — and states `aria-disabled` for assistive technology. Setting
+   * only `aria-disabled` would leave a fully working link that merely claims
+   * not to be.
+   */
+  disabled?: boolean;
+  leftIcon?: React.ReactNode;
+  rightIcon?: React.ReactNode;
+  /**
+   * The external-destination indicator.
+   *
+   * Defaults to a text glyph, for the reason `StyledAlert` uses one: this
+   * package ships no artwork, and a character inherits `currentColor` and the
+   * font scale, so it cannot end up a different colour or size from the label
+   * beside it. Pass a node to substitute an icon, or `null` for none.
+   */
+  externalIndicator?: React.ReactNode;
+  variant?: string;
+}
+
+/** The default external-destination glyph — "↗", north-east arrow. */
+const EXTERNAL_GLYPH = "↗";
+
+/**
+ * A link.
+ *
+ * ```tsx
+ * <StyledLink href="/settings">Settings</StyledLink>
+ * <StyledLink href="https://example.com" isExternal newWindow>Docs</StyledLink>
+ * ```
+ *
+ * In-app destinations render through the host's `linkComponent` (a plain `<a>`
+ * unless configured); external ones always render a plain `<a>`.
+ */
+export const StyledLink = React.forwardRef<HTMLAnchorElement, StyledLinkProps>(
+  function StyledLink(
+    {
+      href,
+      children,
+      isExternal,
+      newWindow,
+      disabled,
+      leftIcon,
+      rightIcon,
+      externalIndicator,
+      variant,
+      className,
+      ...rest
+    },
+    ref,
+  ) {
+    const HostLink = useLinkComponent();
+    const resolved = useResolvedVariant(variant ?? "link", LINK_VARIANTS);
+    const classes = cx(buttonRecipe({ variant: resolved }), className);
+
+    const indicator =
+      externalIndicator === undefined ? EXTERNAL_GLYPH : externalIndicator;
+
+    const content = (
+      <>
+        {leftIcon !== undefined && leftIcon !== null && (
+          <span aria-hidden="true">{leftIcon}</span>
+        )}
+        <span>{children}</span>
+        {rightIcon !== undefined && rightIcon !== null && (
+          <span aria-hidden="true">{rightIcon}</span>
+        )}
+        {isExternal && indicator !== null && (
+          // `aria-hidden` because the accessible name already carries the
+          // destination, and because "opens in a new window" is conveyed by the
+          // visible glyph for sighted users and by nothing useful when read
+          // aloud as "north east arrow".
+          <span aria-hidden="true">{indicator}</span>
+        )}
+      </>
+    );
+
+    // Shared by both branches. `href` is omitted entirely when disabled rather
+    // than set to "#": "#" is a live link to the top of the page, so it stays
+    // focusable and activating it scrolls — a disabled control that does
+    // something is worse than one that looks enabled.
+    const common = {
+      ...(disabled ? {} : { href }),
+      "aria-disabled": disabled ? true : undefined,
+      className: classes,
+      ...(newWindow
+        ? {
+            target: "_blank",
+            // Both, and not only for security. `noopener` severs
+            // `window.opener` (tabnabbing); `noreferrer` also suppresses the
+            // Referer header. They are separate protections and older engines
+            // implement only one.
+            rel: "noopener noreferrer",
+          }
+        : {}),
+      ...rest,
+    };
+
+    // An external destination never goes through the host's router: a
+    // client-side router cannot navigate off-origin, and several will
+    // intercept the click and do nothing at all.
+    if (isExternal || disabled) {
+      return (
+        <a ref={ref} {...common}>
+          {content}
+        </a>
+      );
+    }
+
+    return (
+      <HostLink ref={ref} href={href} {...common}>
+        {content}
+      </HostLink>
+    );
+  },
+);
+
+export default StyledLink;

package/src/components/StyledPage.tsx

@@ -0,0 +1,274 @@
+"use client";
+
+import React from "react";
+import { css, cx } from "styled-system/css";
+
+export interface StyledPageProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+  children?: React.ReactNode;
+  /** Heading for the page. Rendered as an `<h1>` unless `titleAs` says otherwise. */
+  title?: React.ReactNode;
+  /**
+   * Which heading level the title takes.
+   *
+   * `h1` by default, because a page's title is the page's heading. A host
+   * rendering `StyledPage` inside another heading structure passes `h2`/`h3` —
+   * skipped or duplicated levels are a real navigation problem for screen
+   * reader users, and the component cannot see its own surroundings.
+   */
+  titleAs?: "h1" | "h2" | "h3";
+  /** Show a Save action. */
+  includeSave?: boolean;
+  onSave?: (() => void) | undefined;
+  /**
+   * What Cancel does.
+   *
+   * Defaults to going back one entry in session history — see the note on
+   * `goBack` below for why that needs no router.
+   */
+  onCancel?: (() => void) | undefined;
+  saveDisabled?: boolean;
+  cancelDisabled?: boolean;
+  saveLabel?: string;
+  cancelLabel?: string;
+  /**
+   * Whether there are unsaved changes.
+   *
+   * Gates both actions: Cancel appears only when there is something to
+   * discard, and Save is disabled until there is something to save.
+   */
+  isDirty?: boolean;
+  /**
+   * Whether the page's own content area scrolls.
+   *
+   * Defaults to `true` — meaning the content box is `overflow: hidden` and an
+   * element INSIDE it is expected to own the scroll. This is the surprising
+   * default and it is inherited deliberately: it is what the originating app's
+   * pages are built against, and flipping it would give every one of them a
+   * second scrollbar. Pass `false` to let the page scroll as one unit.
+   */
+  hideScrollbar?: boolean;
+  /** Optional icon nodes for the actions. This package ships no artwork. */
+  saveIcon?: React.ReactNode;
+  cancelIcon?: React.ReactNode;
+}
+
+/**
+ * Go back one entry in session history.
+ *
+ * **This is why `StyledPage` needs no routing seam**, and it is worth stating
+ * plainly because the issue that scheduled this work (NEH-430) assumed
+ * otherwise — it proposed passing the current path in, or a `useRouter`-shaped
+ * seam defaulting to `window.location`.
+ *
+ * Reading the component it replaces, the only thing it ever asked the router
+ * for was `router.back()`, as the default `onCancel`. And a router's `back()`
+ * *is* session history — Next's app-router `back()` and react-router's
+ * `navigate(-1)` both end up here. So this is not a degraded fallback standing
+ * in for the real thing; it is the same operation, reached directly.
+ *
+ * The corollary matters more than the saving: `StyleConfig` gains no field.
+ * Every field there is one a new host must understand before it can render a
+ * button, and adding one for an operation the platform already provides would
+ * have been a seam that bought nothing.
+ */
+function goBack(): void {
+  // Guarded for SSR: this is only ever called from a click handler, so in
+  // practice `window` is there — but a host rendering an action on the server
+  // and hydrating should not crash on a missing global.
+  if (typeof window !== "undefined") window.history.back();
+}
+
+/**
+ * The shared look of the two actions.
+ *
+ * Deliberately not `StyledButton`: these need to be buttons at the 48px floor
+ * and nothing else, and routing them through the button recipe would make the
+ * page's toolbar change appearance with the app-wide variant, which is not a
+ * decision a page shell should be making for its host.
+ */
+const actionClass = css({
+  display: "inline-flex",
+  alignItems: "center",
+  justifyContent: "center",
+  gap: "2",
+  // The house floor, stated rather than left to emerge from padding.
+  minHeight: "48px",
+  minWidth: "48px",
+  paddingInline: "3",
+  borderRadius: "md",
+  backgroundColor: "buttonBgPrimary",
+  color: "buttonTextPrimary",
+  cursor: "pointer",
+  _disabled: {
+    cursor: "not-allowed",
+    opacity: 0.6,
+  },
+});
+
+/**
+ * The standard wrapper for a page rendered into an application's body region.
+ *
+ * ```tsx
+ * <StyledPage title="Settings" hideScrollbar={false}>
+ *   …
+ * </StyledPage>
+ * ```
+ *
+ * ## The layout contract, which is the load-bearing part
+ *
+ * The shell this is designed for is a fixed three-row grid — header, body,
+ * footer — where only the body row may scroll. `StyledPage` fills that row
+ * (`flex: 1; min-height: 0; overflow: hidden`) and renders a content box that
+ * fills what is left.
+ *
+ * `min-height: 0` is the non-obvious half and must not be "tidied" away: a flex
+ * child refuses to shrink below its content height without it, so the overflow
+ * escapes the row and pushes the footer off-screen instead of scrolling.
+ *
+ * ## Two things deliberately different from the component this replaces
+ *
+ * **The actions row no longer claims `flex: 1`.** The original set
+ * `flex="1" minH={0} height="100%"` on it, which asks a toolbar to fill the
+ * page — so it competed with the content box for the same space. A toolbar is
+ * `min-content` tall.
+ *
+ * **It paints through tokens.** The original set
+ * `backgroundColor: "var(--hopper-box-main-bg)"` inline, which hardcodes the
+ * default custom-property namespace and so ignores `cssVarPrefix` entirely —
+ * the exact defect class documented in CLAUDE.md. Under a host using another
+ * prefix it painted nothing at all.
+ */
+export const StyledPage = React.forwardRef<HTMLDivElement, StyledPageProps>(
+  function StyledPage(
+    {
+      children,
+      title,
+      titleAs: TitleTag = "h1",
+      includeSave,
+      onSave,
+      onCancel,
+      saveDisabled,
+      cancelDisabled,
+      saveLabel = "Save",
+      cancelLabel = "Cancel",
+      isDirty = false,
+      hideScrollbar = true,
+      saveIcon,
+      cancelIcon,
+      className,
+      ...rest
+    },
+    ref,
+  ) {
+    const showActions = includeSave === true;
+
+    return (
+      <div
+        ref={ref}
+        data-testid="styled-page-root"
+        className={cx(
+          css({
+            display: "flex",
+            flexDirection: "column",
+            flex: "1",
+            width: "100%",
+            // See the contract note above: without this the overflow escapes
+            // the row rather than scrolling inside it.
+            minHeight: "0",
+            overflow: "hidden",
+            backgroundColor: "boxBgMain",
+            // `textMain`, not `textPrimary`. These tokens are a SURFACE axis:
+            // `textPrimary` means "text on the PRIMARY surface" and pairing it
+            // with `boxBgMain` is the mistake TEXT_BACKGROUND_PAIRS exists to
+            // prevent — it would render a colour never contrast-checked against
+            // this background. The original's raw properties were
+            // `box-main-bg` / `box-main-text`, which is this pair.
+            color: "textMain",
+          }),
+          className,
+        )}
+        {...rest}
+      >
+        {title !== undefined && title !== null && (
+          <TitleTag
+            data-testid="styled-page-title"
+            className={css({
+              // min-content by construction: a heading is not a flex item that
+              // should grow. Stated as flexShrink/flexGrow rather than left
+              // implicit because the surrounding column makes `flex: 1` the
+              // thing a reader expects to see.
+              flexGrow: 0,
+              flexShrink: 0,
+              fontSize: "xl",
+              fontWeight: "bold",
+            })}
+          >
+            {title}
+          </TitleTag>
+        )}
+
+        {showActions && (
+          <div
+            data-testid="styled-page-actions"
+            className={css({
+              display: "flex",
+              flexDirection: "row",
+              justifyContent: "flex-end",
+              alignItems: "center",
+              gap: "2",
+              // A toolbar is min-content tall. The original asked for flex:1
+              // and height:100%, which made it compete with the content.
+              flexGrow: 0,
+              flexShrink: 0,
+            })}
+          >
+            {/*
+              Cancel appears only when there is something to discard. Rendering
+              a disabled Cancel on a pristine page is a control that can never
+              do anything, and "discard nothing" is not an action.
+            */}
+            {isDirty && (
+              <button
+                type="button"
+                onClick={onCancel ?? goBack}
+                disabled={cancelDisabled}
+                className={actionClass}
+              >
+                {cancelIcon}
+                {cancelLabel}
+              </button>
+            )}
+            <button
+              type="button"
+              onClick={onSave}
+              // Disabled until there is something to save. `saveDisabled` is
+              // the host's own veto and is independent of dirtiness.
+              disabled={saveDisabled === true || !isDirty}
+              className={actionClass}
+            >
+              {saveIcon}
+              {saveLabel}
+            </button>
+          </div>
+        )}
+
+        <div
+          data-testid="styled-page-content"
+          className={css({
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "stretch",
+            flex: "1",
+            minHeight: "0",
+          })}
+          style={{ overflow: hideScrollbar ? "hidden" : "auto" }}
+        >
+          {children}
+        </div>
+      </div>
+    );
+  },
+);
+
+export default StyledPage;

package/src/components/StyledTag.tsx

@@ -0,0 +1,118 @@
+"use client";
+
+import React from "react";
+import { css, cx } from "styled-system/css";
+
+export interface StyledTagProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, "onSelect"> {
+  children: React.ReactNode;
+  /**
+   * Show a remove control, and call this when it is activated.
+   *
+   * Omitting it renders a plain, non-interactive tag — which is what the great
+   * majority of call sites want. A tag that is merely a label should not be
+   * focusable, and should not offer a button that does nothing.
+   */
+  onRemove?: (() => void) | undefined;
+  /**
+   * The remove button's accessible name.
+   *
+   * Defaults to `Remove` — deliberately generic, because the component cannot
+   * see the label text as a string (children may be any node) and inventing
+   * "Remove {children}" from a React tree produces "Remove [object Object]" as
+   * often as it produces something useful. A call site with a plain text label
+   * should pass the specific form; a list of tags all announcing "Remove" is
+   * navigable but tedious.
+   */
+  removeLabel?: string;
+}
+
+/**
+ * A small label, optionally removable.
+ *
+ * ```tsx
+ * <StyledTag>Draft</StyledTag>
+ * <StyledTag onRemove={() => drop(id)} removeLabel="Remove tag Draft">Draft</StyledTag>
+ * ```
+ *
+ * ## Why this is a `<span>` and not a compound component
+ *
+ * The version this replaces was built on `@ark-ui/react`, which is what kept it
+ * out of this package — a dependency imposed on every consumer, one of them a
+ * proprietary SaaS and one AGPLv3.
+ *
+ * The judgement (NEH-430, and the same one the dropdown got) is that the
+ * library buys interactive/dismissible behaviour that a span with a close
+ * button also provides, and usually provides *more* accessibly, because there
+ * is no reimplemented focus management to get wrong. A host that genuinely
+ * needs the compound version composes it locally, at the one call site.
+ */
+export const StyledTag = React.forwardRef<HTMLSpanElement, StyledTagProps>(
+  function StyledTag(
+    { children, 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,
+        )}
+        {...rest}
+      >
+        <span>{children}</span>
+        {onRemove !== undefined && (
+          <button
+            type="button"
+            onClick={onRemove}
+            aria-label={removeLabel}
+            className={css({
+              display: "inline-flex",
+              alignItems: "center",
+              justifyContent: "center",
+              // The house floor, stated rather than left to emerge from
+              // padding — see CLAUDE.md. A remove control inside a small tag is
+              // exactly where a hit area silently shrinks below it.
+              minWidth: "48px",
+              minHeight: "48px",
+              // The visible glyph stays small while the hit area does not, so
+              // the tag does not become 48px tall to hold its own button.
+              marginBlock: "-3",
+              marginInlineEnd: "-2",
+              background: "transparent",
+              border: "none",
+              cursor: "pointer",
+              color: "inherit",
+            })}
+          >
+            {/*
+              `aria-hidden` so the button announces its `aria-label` alone. A
+              multiplication sign, not a letter x: it is the correct glyph and
+              a screen reader that ignores the hiding reads "times" rather
+              than "x", which at least is not a letter of the label.
+            */}
+            <span aria-hidden="true">×</span>
+          </button>
+        )}
+      </span>
+    );
+  },
+);
+
+export default StyledTag;

package/src/components/StyledText.tsx

@@ -6,7 +6,7 @@ import { styled } from "styled-system/jsx";
 import { css, cx } from "styled-system/css";
 import StyledTooltip from "./StyledTooltip";
 import { useFontSizeProfile } from "../config/style-config";
-import { fontSizeMap } from "../config/font-size";
+import { fontSizeMap, resolveFontSizeKey } from "../config/font-size";
 import type { AllowedTextVariant } from "../config/types";
 import { textRecipe } from "styled-system/recipes";
 
@@ -114,15 +114,7 @@ const StyledText = React.forwardRef<HTMLSpanElement, StyledTextProps>((props, re
   } = props;
   const fontSizeProfile = useFontSizeProfile();
 
-  let finalSize;
-  if (size) {
-    finalSize = size;
-  } else if (fixedSize) {
-    finalSize = "md";
-  } else {
-    finalSize = fontSizeProfile;
-  }
-
+  const finalSize = resolveFontSizeKey({ size, fixedSize, profile: fontSizeProfile });
   const fontSize = fontSizeMap[finalSize] || fontSizeMap.md;
 
   const extraStyles: React.CSSProperties = {};

package/src/config/font-size.ts

@@ -62,6 +62,42 @@ export function getFontSizeLabel(size: string): string {
   return fontSizeLabelMap[size] ?? size;
 }
 
+/**
+ * Which scale step a piece of text ends up at: caller → `fixedSize` → profile.
+ *
+ * The same precedence shape as `useResolvedVariant`, and here for the same
+ * reason — but it is a *pure function* rather than a branch inside `StyledText`
+ * specifically so the unit tier can assert it (NEH-406).
+ *
+ * That mattered more than it looks. The rule was only ever checked through a
+ * rendered `font-size`, and **jsdom cannot see one of these values at all**:
+ * every `fontSizeMap` entry is a `var(--font-sizes-*, …)` reference, jsdom's
+ * CSS parser rejects it against the `font-size` grammar, and the declaration is
+ * dropped — the element ends up with no `style` attribute whatsoever. So
+ * `toHaveStyle({ fontSize: <anything> })` compared "" with "" and passed for
+ * every possible expectation, including one asserting a size that had not been
+ * true since the scale moved.
+ *
+ * Splitting the rule out gives each tier a question it can actually answer:
+ * *which step wins* here, and *what does it measure* in the browser tier.
+ *
+ * `fixedSize` pins to `md` — used where a label must not grow with the profile,
+ * e.g. inside a fixed-height control it would otherwise clip.
+ */
+export function resolveFontSizeKey({
+  size,
+  fixedSize,
+  profile,
+}: {
+  size?: string | undefined;
+  fixedSize?: boolean | undefined;
+  profile?: string | undefined;
+}): string {
+  if (size) return size;
+  if (fixedSize) return "md";
+  return profile ?? "md";
+}
+
 /**
  * The literal fallback inside a `fontSizeMap` entry, e.g. `"1rem"`.
  *