@stonedogcode/style 0.12.0 → 0.13.0

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/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 } from "./components/StyledLink";
+
+export { default as StyledTag, StyledTag as Tag } from "./components/StyledTag";
+export type { StyledTagProps } 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

@@ -195,6 +195,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,
       },