@stonedogcode/style 0.9.0

package/src/components/StyledHStack.tsx

@@ -0,0 +1,145 @@
+import React from "react";
+import { hstack } from "styled-system/patterns";
+import type { ConditionalValue } from "styled-system/types";
+import { Property } from "csstype";
+
+export interface StyledHStackProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, "color"> {
+  as?: React.ElementType | undefined;
+  gap?: ConditionalValue<string | number> | undefined;
+  align?: ConditionalValue<string> | undefined;
+  justify?: ConditionalValue<string> | undefined;
+  width?: ConditionalValue<string> | undefined;
+  w?: ConditionalValue<string> | undefined;
+  marginBottom?: ConditionalValue<string> | undefined;
+  mb?: ConditionalValue<string | number> | undefined;
+  marginTop?: ConditionalValue<string | number> | undefined;
+  mt?: ConditionalValue<string | number> | undefined;
+  flexWrap?: ConditionalValue<string> | undefined;
+  display?: ConditionalValue<string> | undefined;
+  alignItems?: ConditionalValue<string> | undefined;
+  justifyContent?: ConditionalValue<string> | undefined;
+  p?: ConditionalValue<string | number> | undefined;
+  py?: ConditionalValue<string | number> | undefined;
+  px?: ConditionalValue<string | number> | undefined;
+  pt?: ConditionalValue<string | number> | undefined;
+  minH?: ConditionalValue<string | number> | undefined;
+  flexShrink?: ConditionalValue<string | number> | undefined;
+  flexDirection?: ConditionalValue<Property.FlexDirection> | undefined;
+  bg?: ConditionalValue<string> | undefined;
+  backgroundColor?: ConditionalValue<string> | undefined;
+  height?: ConditionalValue<string | number> | undefined;
+  h?: ConditionalValue<string | number> | undefined;
+  borderRadius?: ConditionalValue<string | number> | undefined;
+  borderWidth?: ConditionalValue<string | number> | undefined;
+  borderColor?: ConditionalValue<string> | undefined;
+  border?: ConditionalValue<string> | undefined;
+  opacity?: ConditionalValue<number> | undefined;
+  color?: ConditionalValue<string> | undefined;
+  _dark?: Record<string, unknown> | undefined;
+  // Allow additional Panda CSS style props
+  [key: string]: unknown;
+}
+
+export const StyledHStack: React.FC<StyledHStackProps> = ({
+  as: Component = "div",
+  gap = "2",
+  align,
+  justify,
+  width,
+  w,
+  marginBottom,
+  mb,
+  flexWrap,
+  display,
+  alignItems,
+  justifyContent,
+  p,
+  py,
+  px,
+  minH,
+  pt,
+  bg,
+  backgroundColor,
+  children,
+  flexDirection,
+  flexShrink,
+  marginTop,
+  mt,
+  height,
+  h,
+  borderRadius,
+  borderWidth,
+  borderColor,
+  border,
+  opacity,
+  color,
+  _dark,
+  className: _className,
+  style: _style,
+  ...rest
+}) => {
+  // Separate HTML attributes from style props
+  const htmlAttrs: Record<string, unknown> = {};
+  const extraStyleProps: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(rest)) {
+    if (key.startsWith("on") || key.startsWith("data-") || key.startsWith("aria-") || ["id", "ref", "role", "tabIndex", "draggable", "title"].includes(key)) {
+      htmlAttrs[key] = value;
+    } else {
+      extraStyleProps[key] = value;
+    }
+  }
+
+  // Map React-style props to styled-system pattern props
+  const mappedProps: Record<string, unknown> = {
+    gap: typeof gap === "number" ? String(gap) : gap,
+    // `alignItems`, not `align`. The generated `hstack` pattern destructures
+    // only `justify` and `gap`, hard-codes `alignItems: "center"`, then spreads
+    // the rest — so only a key literally named `alignItems` overrides that
+    // centre. `align` is not a Panda utility either, so it used to survive into
+    // `css()` and emit a class name with no rule behind it (NEH-288).
+    alignItems: align || alignItems,
+    justify: justify || justifyContent,
+    width: width || w,
+    marginBottom: marginBottom || mb,
+    marginTop: marginTop || mt,
+    flexWrap,
+    display,
+    p,
+    py,
+    px,
+    minH,
+    pt,
+    background: bg || backgroundColor,
+    flexDirection,
+    flexShrink,
+    height: height || h,
+    borderRadius,
+    borderWidth,
+    borderColor,
+    border,
+    opacity,
+    color,
+    _dark,
+    ...extraStyleProps,
+  };
+
+  // Remove undefined values
+  Object.keys(mappedProps).forEach(
+    (key) => mappedProps[key] === undefined && delete mappedProps[key],
+  );
+
+  return (
+    <Component
+      className={hstack(mappedProps as Parameters<typeof hstack>[0])}
+      style={_style}
+      {...htmlAttrs}
+    >
+      {children}
+    </Component>
+  );
+};
+
+StyledHStack.displayName = "StyledHStack";
+
+export default StyledHStack;

package/src/components/StyledHeading.tsx

@@ -0,0 +1,79 @@
+import React from "react";
+import StyledSeparator from "./StyledSeparator";
+import StyledText from "./StyledText";
+import { useFontSizeProfile } from "../config/style-config";
+import { stepUpFontSize } from "../config/font-size";
+import type { FontSizeKey } from "../config/types";
+import type { HTMLStyledProps } from "styled-system/jsx";
+
+type SizeKey = FontSizeKey;
+
+type StyledHeadingProps = HTMLStyledProps<"h1"> & {
+  addSeparator?: boolean;
+  size?: SizeKey;
+  as?: React.ElementType;
+  fixedSize?: boolean;
+  color?: string;
+  ellipsis?: boolean;
+  wrap?: boolean;
+};
+
+const StyledHeading = React.forwardRef<HTMLElement, StyledHeadingProps>(
+  (
+    {
+      children,
+      addSeparator,
+      size,
+      as = "h1",
+      fixedSize,
+      color,
+      ellipsis = false,
+      wrap = true,
+      ...rest
+    },
+    ref,
+  ) => {
+    const fontSizeProfile = useFontSizeProfile();
+    let baseSize: SizeKey;
+    if (size) {
+      baseSize = size;
+    } else if (fixedSize) {
+      baseSize = "md";
+    } else {
+      baseSize = fontSizeProfile;
+    }
+
+    // A heading reads one tier above whatever body text is currently set to,
+    // so the hierarchy survives every font-size profile rather than only the
+    // default one. Clamped at the top of the scale by stepUpFontSize.
+    const headingSize = stepUpFontSize(baseSize);
+
+    return (
+      <>
+        <StyledText
+          as={as}
+          ref={ref}
+          size={headingSize}
+          // The theme's heading face, so a theme can pair a display face with
+          // its body face (NEH-289). Asked for here rather than in textRecipe
+          // because StyledHeading shares that recipe with body copy. Written as
+          // a literal so Panda's extractor, which only reads source text, sees
+          // it.
+          fontFamily="heading"
+          fontWeight="bold"
+          fixedSize={fixedSize}
+          color={color}
+          ellipsis={ellipsis}
+          wrap={wrap}
+          {...rest}
+        >
+          {children}
+        </StyledText>
+        {addSeparator && <StyledSeparator />}
+      </>
+    );
+  },
+);
+
+StyledHeading.displayName = "StyledHeading";
+export default StyledHeading;

package/src/components/StyledHrRule.tsx

@@ -0,0 +1,33 @@
+"use client";
+
+import { log } from "../config/logger";
+import React from "react";
+import { styled } from "styled-system/jsx";
+import type { HTMLStyledProps } from "styled-system/types";
+
+/**
+ * Modern styled `<hr>` — a thin horizontal rule with a subtle gradient
+ * fade to transparent at each end. Inherits Panda style props so callers
+ * can override `borderColor`, `my`, `opacity`, etc. as needed.
+ */
+const PandaHr = styled("hr", {
+  base: {
+    border: "0",
+    height: "1px",
+    width: "100%",
+    margin: "0",
+
+    opacity: 0.85,
+  },
+});
+
+export type StyledHrRuleProps = HTMLStyledProps<"hr">;
+
+export const StyledHrRule = React.forwardRef<HTMLHRElement, StyledHrRuleProps>(
+  function StyledHrRule(props, ref) {
+    log.trace("StyledHrRule rendered");
+    return <PandaHr bg="boxBgSecondary" ref={ref} role="separator" {...props} />;
+  },
+);
+
+export default StyledHrRule;

package/src/components/StyledIcon.tsx

@@ -0,0 +1,172 @@
+"use client";
+
+import React from "react";
+import { iconRecipe } from "styled-system/recipes";
+import { log } from "../config/logger";
+import { useIconSize } from "../config/style-config";
+import type { IconSize } from "../config/types";
+
+/**
+ * The icon seam.
+ *
+ * This package ships **no icons**, on purpose: the components it was extracted
+ * from used a per-seat commercial icon set whose artwork cannot be
+ * redistributed under this licence. Rather than pick a replacement and impose
+ * it on every consumer, `StyledIcon` is a sizing-and-colouring wrapper that
+ * renders whatever node you hand it. Bring Lucide, Heroicons, Font Awesome,
+ * Material Symbols, or your own SVGs — the system only cares that the result
+ * lands in a consistently sized, theme-coloured box.
+ *
+ * Two mechanisms do the colouring, because icon libraries disagree about how
+ * they take a colour:
+ *
+ * 1. **`color` is set on the wrapper**, so any icon drawn with
+ *    `fill="currentColor"` or `stroke="currentColor"` inherits it. That covers
+ *    Lucide, Heroicons, Feather, Material Symbols, and most hand-rolled SVGs —
+ *    for those, nothing further is needed.
+ * 2. **Custom properties are published** — `--icon-primary-color`,
+ *    `--icon-secondary-color`, `--icon-secondary-opacity` — for sets that paint
+ *    from variables instead, such as Font Awesome's duotone family. An adapter
+ *    maps them in one line of CSS; see the README.
+ *
+ * Publishing neutral property names rather than any library's own is what keeps
+ * this package free of a dependency it must not have.
+ */
+
+/**
+ * Size vocabulary. Defined in `config/types` because `StyleConfig` names it
+ * too — re-exported here so the long-standing import path keeps working.
+ */
+export type { IconSize };
+
+/** Rendered box size, in CSS px, for each size name. */
+const SIZE_TO_PX: Record<string, number> = {
+  "2xs": 10,
+  xs: 12,
+  sm: 16,
+  "1x": 20,
+  md: 20,
+  lg: 24,
+  "2x": 32,
+  xl: 32,
+  "2xl": 40,
+  "3x": 48,
+  "4x": 64,
+  "5x": 80,
+  "6x": 96,
+  "7x": 112,
+  "8x": 128,
+  "9x": 144,
+  "10x": 160,
+};
+
+/** The recipe defines four size variants; the rest fall back to the base. */
+const RECIPE_SIZES = new Set(["sm", "md", "lg", "xl"]);
+
+export interface StyledIconProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, "color"> {
+  /**
+   * The icon to render — any React node. Passing `children` instead is
+   * equivalent; `icon` reads better at a call site that renders nothing else.
+   */
+  icon?: React.ReactNode;
+  children?: React.ReactNode;
+  /**
+   * Box size. Omit it and the app-wide default from `StonedogStyleProvider`
+   * applies (`"2x"` if the host sets nothing).
+   *
+   * **Prefer omitting it.** Setting the app-wide default once is what keeps an
+   * application to a single icon scale; a size named at the call site opts that
+   * icon out of ever being retuned. Pass it only where this specific icon must
+   * differ from everything around it.
+   */
+  size?: IconSize;
+  /** Primary colour. Defaults to the theme's main text colour. */
+  color?: string;
+  /** Secondary colour, for two-tone icon sets. Ignored by single-tone ones. */
+  secondaryColor?: string;
+  /** Opacity of the secondary tone, for sets that support it. */
+  secondaryOpacity?: number;
+  /**
+   * Accessible label. **Omit it for a decorative icon** — one that sits beside
+   * text already saying the same thing. An icon-only control needs one; an icon
+   * next to its own label must not have one, or screen readers announce the
+   * name twice.
+   */
+  title?: string;
+}
+
+/**
+ * Defaults reference the token layer rather than literal colours, so an icon
+ * with no explicit colour still follows the host's theme and colour mode.
+ */
+const DEFAULT_PRIMARY = "var(--colors-text-main)";
+const DEFAULT_SECONDARY = "var(--colors-icon-bg-primary)";
+
+const StyledIcon: React.FC<StyledIconProps> = ({
+  icon,
+  children,
+  size: sizeProp,
+  color,
+  secondaryColor,
+  secondaryOpacity,
+  title,
+  className,
+  style,
+  ...rest
+}) => {
+  log.trace("StyledIcon rendered");
+
+  // Caller's size, else the app-wide default, else "2x". Same precedence rule
+  // as `useResolvedVariant`, and shared for the same reason: when each control
+  // picks its own default, the app quietly grows several scales at once.
+  const appIconSize = useIconSize();
+  const size = sizeProp ?? appIconSize;
+
+  const recipeClass = iconRecipe(
+    RECIPE_SIZES.has(size) ? { size: size as "sm" | "md" | "lg" | "xl" } : {},
+  );
+  const mergedClassName = [recipeClass, className].filter(Boolean).join(" ");
+
+  const boxSize = SIZE_TO_PX[size] ?? 20;
+  const primary = color ?? DEFAULT_PRIMARY;
+
+  const mergedStyle = {
+    // Published for icon sets that paint from variables. Neutral names, so no
+    // particular library is baked in — adapters map them (see the README).
+    "--icon-primary-color": primary,
+    "--icon-secondary-color": secondaryColor ?? DEFAULT_SECONDARY,
+    ...(secondaryOpacity != null
+      ? { "--icon-secondary-opacity": secondaryOpacity }
+      : {}),
+    // For everything drawn with currentColor, which is most of them.
+    color: primary,
+    ...(typeof style === "object" && style !== null ? style : {}),
+    // After the caller's style on purpose: `size` is the prop that exists to
+    // control the box, so it must not be silently defeated by a stray height in
+    // a spread style object.
+    height: `${boxSize}px`,
+    width: `${boxSize}px`,
+  } as React.CSSProperties;
+
+  return (
+    <span
+      {...rest}
+      className={mergedClassName}
+      style={mergedStyle}
+      // A titled icon is being used AS the label for something, so it needs a
+      // role to go with the name. An untitled one is decorative and is hidden,
+      // rather than read out as an anonymous graphic.
+      role={title ? "img" : undefined}
+      aria-label={title}
+      aria-hidden={title ? undefined : true}
+    >
+      {icon ?? children}
+    </span>
+  );
+};
+
+StyledIcon.displayName = "StyledIcon";
+
+export default StyledIcon;
+export { StyledIcon };

package/src/components/StyledIconButton.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+import React from "react";
+import type { HTMLStyledProps } from "styled-system/types";
+import { buttonIconRecipe } from "styled-system/recipes";
+import type { AllowedVariant } from "../config/types";
+import { useStyleConfig } from "../config/style-config";
+import StyledTooltip from "./StyledTooltip";
+
+/**
+ * A button whose whole label is an icon.
+ *
+ * ## The variant coercion is necessary, not arbitrary
+ *
+ * `buttonIconRecipe` defines **seven** variants — `solid`, `outline`, `aurora`,
+ * `glass`, `matte`, `ghost`, `none` — and the vocabulary has ten. The missing
+ * three have to go somewhere, or a caller passing one gets a button with a class
+ * name and no rules behind it:
+ *
+ * | Asked for | Rendered as | Why |
+ * |---|---|---|
+ * | `unstyled` | `ghost` | closest thing the recipe has to "no chrome" |
+ * | `link` | `outline` | a link-styled icon button has no affordance at all |
+ * | `selected` | `outline` | same — the recipe has no selected treatment |
+ *
+ * This is why the component does not use `useResolvedVariant`, which would send
+ * all three to `solid` and give a "no chrome" request a filled background.
+ * `StyledButton` does something different again, because *its* recipe defines
+ * all ten. Three components, three variant sets — check the recipe before you
+ * assume.
+ *
+ * ## An icon button MUST be named
+ *
+ * There is no visible text, so `aria-label` (or `tooltip`, which supplies one)
+ * is the only thing standing between a screen-reader user and a control
+ * announced as "button". Nothing here can enforce that, so it is asserted in the
+ * tests and stated here.
+ */
+
+export type IconButtonSize = "1x" | "sm" | "md" | "lg";
+
+/** Variants the icon recipe actually defines. */
+type IconButtonVariant = "solid" | "outline" | "aurora" | "glass" | "matte" | "ghost" | "none";
+
+export interface StyledIconButtonProps extends HTMLStyledProps<"button"> {
+  variant?: AllowedVariant;
+  size?: IconButtonSize;
+  children?: React.ReactNode;
+  disabled?: boolean;
+  /** Also supplies the accessible name when no `aria-label` is given. */
+  tooltip?: string;
+  placement?: "top" | "bottom" | "left" | "right";
+  /** Render as something else — an anchor, for instance. */
+  as?: React.ElementType;
+  href?: string;
+  target?: string;
+  rel?: string;
+}
+
+/** Map the full vocabulary onto what the recipe can actually paint. */
+function toIconVariant(variant: AllowedVariant): IconButtonVariant {
+  if (variant === "unstyled") return "ghost";
+  if (variant === "link" || variant === "selected") return "outline";
+  return variant as IconButtonVariant;
+}
+
+const StyledIconButton = React.forwardRef<HTMLButtonElement, StyledIconButtonProps>(
+  function StyledIconButton(
+    {
+      children,
+      variant,
+      size = "md",
+      disabled,
+      tooltip,
+      placement,
+      as = "button",
+      onClick,
+      "aria-label": ariaLabel,
+      ...rest
+    },
+    ref,
+  ) {
+    const { variant: appVariant } = useStyleConfig();
+    const requested = variant ?? appVariant;
+    const painted = toIconVariant(requested);
+
+    const Element = as as React.ElementType;
+
+    // zIndex is pulled out of the Panda prop bag and applied inline. Panda would
+    // emit it as an atomic class, which loses to the recipe's own class in the
+    // cascade — so a caller stacking a button above a sibling would find it
+    // ignored.
+    const { zIndex, style, className: incoming, ...restWithoutZIndex } = rest;
+
+    return (
+      <StyledTooltip tooltip={tooltip} placement={placement}>
+        <Element
+          ref={ref}
+          className={[buttonIconRecipe({ variant: painted, size }), incoming]
+            .filter(Boolean)
+            .join(" ")}
+          // `data-panda-variant` reports what was ASKED for, not what was
+          // painted, so a caller inspecting the DOM can see their `link` was
+          // honoured as a request even though the recipe drew an outline.
+          data-panda-variant={requested}
+          // Fall back to the tooltip for the accessible name. An icon button has
+          // no visible text, so without one it announces as just "button" —
+          // WCAG 4.1.2. The tooltip is already the human-readable description of
+          // what the control does, so it is the right string, and an explicit
+          // aria-label still wins.
+          //
+          // This is a fix, not a port: upstream, a tooltip named the trigger
+          // ONLY when the child was not focusable. A button always is, so it got
+          // aria-describedby and no name. In the originating app that left 9 of
+          // 43 icon buttons unnamed (a further 10 have neither, which only the
+          // call sites can fix).
+          aria-label={ariaLabel ?? tooltip}
+          style={zIndex !== undefined ? { ...(style || {}), zIndex } : style}
+          onClick={onClick}
+          // Only a real <button> understands `disabled`; on an <a> it is
+          // meaningless and React would emit an invalid attribute.
+          disabled={as === "button" ? disabled : undefined}
+          {...restWithoutZIndex}
+        >
+          {children}
+        </Element>
+      </StyledTooltip>
+    );
+  },
+);
+
+StyledIconButton.displayName = "StyledIconButton";
+
+export default StyledIconButton;
+export { StyledIconButton };

package/src/components/StyledInputBool.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import React from "react";
+import StyledText from "./StyledText";
+import StyledHStack from "./StyledHStack";
+import { styled } from "styled-system/jsx";
+import { inputBoolRecipe } from "styled-system/recipes";
+import { useResolvedVariant } from "../config/style-config";
+
+
+/**
+ * A checkbox with its label.
+ *
+ * The whole thing is a `<label>`, so the text is part of the target rather than
+ * something next to it. A bare checkbox is roughly 14×14 CSS px — far under the
+ * 44×44 floor — and wrapping is what makes it hittable without demanding fine
+ * motor control. It is also why the label is not optional in practice: pass
+ * one, or the control has no accessible name and no usable target.
+ *
+ * Styling comes from `inputBoolRecipe`, which paints the box, the tick and the
+ * label as three slots. The variant resolves through `useResolvedVariant`, so a
+ * call site that says nothing inherits the app-wide choice.
+ */
+
+/**
+ * What `inputBoolRecipe` actually defines — wider than the five a user can pick
+ * app-wide, because `ghost` and `none` are reachable per call site.
+ *
+ * Passed to `useResolvedVariant` explicitly. Without it the default gate is the
+ * theme five and `variant="ghost"` silently becomes `solid`.
+ *
+ * `button` is omitted deliberately: the recipe defines it, but it restyles the
+ * checkbox as a push button, which is a different control rather than a
+ * different appearance of this one.
+ */
+export const INPUT_BOOL_VARIANTS = [
+  "solid",
+  "outline",
+  "aurora",
+  "glass",
+  "matte",
+  "ghost",
+  "none",
+] as const;
+
+export type InputBoolVariant = (typeof INPUT_BOOL_VARIANTS)[number];
+
+export interface StyledInputBoolProps
+  extends React.InputHTMLAttributes<HTMLInputElement> {
+  label?: string | React.ReactNode;
+  ["data-testid"]?: string;
+  isReadOnly?: boolean;
+  variant?: InputBoolVariant;
+}
+
+const StyledInputBool = React.forwardRef<
+  HTMLInputElement,
+  StyledInputBoolProps
+>(function StyledInputBool({ label, isReadOnly, variant, ...props }, ref) {
+  const slots = inputBoolRecipe({
+    variant: useResolvedVariant(variant, INPUT_BOOL_VARIANTS),
+  });
+
+  return (
+    <StyledHStack as="label" className={slots.root}>
+      <styled.input
+        type="checkbox"
+        ref={ref}
+        data-testid={props["data-testid"]}
+        readOnly={isReadOnly}
+        {...props}
+        className={slots.control}
+      />
+      {label && <StyledText className={slots.label}>{label}</StyledText>}
+    </StyledHStack>
+  );
+});
+
+StyledInputBool.displayName = "StyledInputBool";
+
+export default StyledInputBool;