@stonedogcode/style 0.12.0 → 0.15.0

package/src/components/StyledLink.tsx

@@ -0,0 +1,254 @@
+"use client";
+
+import React from "react";
+import { buttonRecipe } from "styled-system/recipes";
+import { css, 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;
+
+/**
+ * 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. */
+  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;
+  /**
+   * 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. */
+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,
+      standalone = false,
+      presentation,
+      className,
+      ...rest
+    },
+    ref,
+  ) {
+    const HostLink = useLinkComponent();
+    const resolved = useResolvedVariant(variant ?? "link", LINK_VARIANTS);
+
+    /*
+     * `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;
+
+    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,155 @@
+"use client";
+
+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.
+   *
+   * 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,
+      tone = "neutral",
+      indicator,
+      onRemove,
+      removeLabel = "Remove",
+      className,
+      ...rest
+    },
+    ref,
+  ) {
+    return (
+      <span
+        ref={ref}
+        /*
+         * 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
+            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;