@stonedogcode/style 0.9.0

package/src/components/StyledInputToggle.tsx

@@ -0,0 +1,224 @@
+"use client";
+
+import React from "react";
+import { styled } from "styled-system/jsx";
+import StyledTooltip from "./StyledTooltip";
+
+/**
+ * An on/off switch.
+ *
+ * ## No animation library
+ *
+ * The originating component used framer-motion for two things: sliding the
+ * handle, and growing a strike-through when disabled. Both are a CSS
+ * transition, and a whole animation library is a heavy thing to make three
+ * products carry for a 26px circle that moves 30px. This package has one
+ * runtime dependency and that is worth defending.
+ *
+ * The spring is gone with it. A spring on a binary control is decoration —
+ * there is no in-between state to communicate — and it delayed the settled
+ * position by longer than the ease does.
+ *
+ * **It honours `prefers-reduced-motion`.** Motion is a vestibular trigger, not
+ * only a preference; under that query the handle moves instantly.
+ *
+ * ## It is a real button
+ *
+ * The original was a `<div role="switch">` with hand-written `Space`/`Enter`
+ * handling and a manual `tabIndex`. A `<button>` gets all of that from the
+ * platform — focus, activation, the disabled semantics — and gets them right in
+ * the cases hand-rolled versions miss, like activation on key-up rather than
+ * key-down.
+ *
+ * ## Three defects fixed on the way in
+ *
+ * **It was under the tap-target floor.** The switch was 60×30 CSS px against a
+ * 44×44 minimum (WCAG 2.5.5). The track still *looks* 60×30 — the button pads
+ * out to 44 around it, so the appearance is unchanged and the target is legal.
+ * Shrinking the visible track would have been the wrong fix; a switch reads as
+ * a switch at that size.
+ *
+ * **It painted itself from the raw palette** — `gray.300`, `green.400`,
+ * `white` — so it ignored the theme and dark mode entirely. Now tokens, chosen
+ * from `TEXT_BACKGROUND_PAIRS` rather than by eye: the handle is the *text*
+ * token belonging to whichever track surface is under it, which is the
+ * package's own contract for "these two are readable together".
+ *
+ * **It could end up with no accessible name.** The old fallback used `tooltip`
+ * only when it happened to be a string, so a node tooltip left the switch
+ * announced as "switch" with no name at all. `label` is now explicit, with the
+ * string tooltip still serving as a fallback.
+ */
+
+export interface StyledInputToggleProps {
+  id?: string;
+  value: boolean;
+  onChange: (value: boolean) => void;
+  /** Shown above the switch when on. */
+  iconOn?: React.ReactNode;
+  /** Shown above the switch when off. */
+  iconOff?: React.ReactNode;
+  disabled?: boolean;
+  tooltip?: React.ReactNode;
+  placement?: "top" | "bottom" | "left" | "right";
+  /** Accessible name. Pass it — see above. */
+  label?: string;
+  ["data-testid"]?: string;
+}
+
+const ToggleContainer = styled("div", {
+  base: {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    gap: "2",
+  },
+});
+
+const IconContainer = styled("div", {
+  base: { position: "relative" },
+});
+
+const StrikeThrough = styled("div", {
+  base: {
+    position: "absolute",
+    top: "50%",
+    left: 0,
+    width: "100%",
+    height: "2px",
+    backgroundColor: "currentColor",
+    transformOrigin: "center",
+    transform: "scaleX(1)",
+    animation: "stonedogStrikeIn 200ms ease-out",
+    "@media (prefers-reduced-motion: reduce)": {
+      animation: "none",
+    },
+  },
+});
+
+/**
+ * The button. Its padding is what carries the 44px floor: the visible track
+ * inside stays 60×30, so nothing looks different and the target is legal.
+ */
+const SwitchButton = styled("button", {
+  base: {
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    minWidth: "48px",
+    minHeight: "48px",
+    padding: "0",
+    border: "none",
+    background: "transparent",
+    cursor: "pointer",
+    borderRadius: "md",
+    _disabled: {
+      cursor: "not-allowed",
+      opacity: 0.5,
+    },
+  },
+});
+
+const Track = styled("span", {
+  base: {
+    display: "flex",
+    alignItems: "center",
+    width: "60px",
+    height: "30px",
+    borderRadius: "15px",
+    padding: "2px",
+    transition: "background-color 200ms ease",
+    "@media (prefers-reduced-motion: reduce)": {
+      transition: "none",
+    },
+  },
+  variants: {
+    on: {
+      // Token pairs from TEXT_BACKGROUND_PAIRS — the handle below reads against
+      // whichever of these is under it.
+      true: { backgroundColor: "buttonBgAccent" },
+      false: { backgroundColor: "boxBgSecondary" },
+    },
+  },
+});
+
+const Handle = styled("span", {
+  base: {
+    width: "26px",
+    height: "26px",
+    borderRadius: "50%",
+    // translateX, not `margin-left: auto` — a margin change is not animatable,
+    // which is why the original needed a layout animation to move at all.
+    transform: "translateX(0)",
+    transition: "transform 200ms ease, background-color 200ms ease",
+    "@media (prefers-reduced-motion: reduce)": {
+      transition: "none",
+    },
+  },
+  variants: {
+    on: {
+      true: {
+        transform: "translateX(30px)",
+        backgroundColor: "buttonTextAccent",
+      },
+      false: { backgroundColor: "textSecondary" },
+    },
+  },
+});
+
+export default function StyledInputToggle({
+  id,
+  value,
+  onChange,
+  iconOn,
+  iconOff,
+  disabled,
+  tooltip,
+  placement,
+  label,
+  ...props
+}: StyledInputToggleProps) {
+  const hasIcons = iconOn || iconOff;
+  const name = label ?? (typeof tooltip === "string" ? tooltip : undefined);
+
+  const content = (
+    <ToggleContainer id={id}>
+      {hasIcons && (
+        <IconContainer>
+          {value ? iconOn : iconOff}
+          {/* Decorative: the switch's own state is already announced by
+              aria-checked and aria-disabled. */}
+          {disabled && <StrikeThrough aria-hidden="true" data-testid="toggle-strike" />}
+        </IconContainer>
+      )}
+      <SwitchButton
+        type="button"
+        role="switch"
+        aria-checked={value}
+        aria-label={name}
+        disabled={disabled}
+        data-state={value ? "on" : "off"}
+        // The caller's id lands on the BUTTON, not the container. A test that
+        // does `click(getByTestId(...))` has to hit the interactive element —
+        // clicking a wrapper does nothing, and the failure looks like a broken
+        // component rather than a mis-aimed selector.
+        data-testid={props["data-testid"] ?? "toggle-switch"}
+        onClick={() => onChange(!value)}
+      >
+        <Track on={value}>
+          <Handle on={value} />
+        </Track>
+      </SwitchButton>
+    </ToggleContainer>
+  );
+
+  if (tooltip) {
+    return (
+      <StyledTooltip tooltip={tooltip} placement={placement}>
+        {content}
+      </StyledTooltip>
+    );
+  }
+
+  return content;
+}

package/src/components/StyledList.tsx

@@ -0,0 +1,188 @@
+"use client";
+
+import React from "react";
+import { styled } from "styled-system/jsx";
+import { listRecipe } from "styled-system/recipes";
+import { useResolvedVariant } from "../config/style-config";
+import { log } from "../config/logger";
+
+/**
+ * A vertical list of rows — the surface, borders and row separators that turn
+ * a `<ul>` into a panel.
+ *
+ * Compose it: `StyledList.Root` draws the container, `StyledList.Item` draws a
+ * row. Both are required; an `Item` outside a `Root` is a bare `<li>`, which is
+ * the correct behaviour and also the reason the previous version had a bug —
+ * see below.
+ *
+ * ## The variants a call site can ask for
+ *
+ * The five app-wide appearances plus `ghost`, `none` and `unstyled`. Anything
+ * else falls back to `solid` through `useResolvedVariant`, rather than being
+ * passed to the recipe and rendering as nothing.
+ *
+ * ## Three defects fixed on the way across
+ *
+ * **The default variant was a variant that does not exist.** The originating
+ * version read `variant ?? globalVariant ?? "list"` — and `"list"` is the
+ * recipe's *className*, not one of its variants. Any consumer rendering a list
+ * before a `StonedogStyleProvider` had supplied a global variant therefore
+ * asked the recipe for `variant: "list"`, matched nothing, and got an unstyled
+ * list: no surface, no border, no row separators. It looked like a list that
+ * had simply not been styled yet, which is exactly why it survived.
+ *
+ * Resolution goes through `useResolvedVariant` now, with the allow-list, which
+ * is the mechanism NEH-234 added for precisely this class of miss.
+ *
+ * **The row styling was injected by the parent, not owned by the row.** `Root`
+ * walked its children with `React.Children.map` and `cloneElement`d the item
+ * class onto each one. That breaks in the three ways cloning children always
+ * breaks: a `<>fragment</>` of rows received the class on the *fragment*, a
+ * row rendered by a child component never saw it, and any row that was not a
+ * direct child was skipped. It also meant `StyledList.Item` had no styling of
+ * its own — so the component only worked in the one arrangement its author
+ * happened to test.
+ *
+ * `Item` now carries its own slot class. Rows render correctly wherever they
+ * are, including inside a `.map()`, a fragment, or a wrapper component.
+ *
+ * **`gap` was hand-implemented as a margin on every child but the last.** The
+ * recipe root is already `display: flex; flex-direction: column`, so this was
+ * reimplementing the `gap` property — badly, because writing `marginBottom`
+ * into each child's inline `style` silently overwrote any margin the caller had
+ * set there. It is a real `gap` now.
+ *
+ * ## `role="list"` is not redundant here
+ *
+ * Safari removes list semantics from any `<ul>` whose `list-style` is `none` —
+ * a deliberate WebKit decision, and this component sets exactly that whenever
+ * bullets are off (the default). Without the explicit role, VoiceOver stops
+ * announcing "list, 6 items", which is the one piece of information a
+ * non-visual reader needs before deciding whether to read on.
+ */
+
+const PandaUl = styled("ul");
+const PandaOl = styled("ol");
+const PandaListItem = styled("li");
+
+/** What a call site may ask for, beyond the five app-wide appearances. */
+export const LIST_VARIANTS = [
+  "solid",
+  "outline",
+  "lines",
+  "aurora",
+  "glass",
+  "matte",
+  "ghost",
+  "none",
+  "unstyled",
+] as const;
+
+export type ListVariant = (typeof LIST_VARIANTS)[number];
+
+/**
+ * Props derive from the Panda component, not from `React.HTMLAttributes`, so
+ * style props (`w`, `h`, `mt`, …) are typed rather than merely tolerated.
+ *
+ * The originating version reached this by declaring `[key: string]: unknown`
+ * — which accepted the style props *and* every typo alongside them, and
+ * defeated type checking on the whole component. Narrowing it to
+ * `HTMLAttributes` was the opposite mistake: 9 HopperGuard call sites pass
+ * `w`, `h` or `mt`, and they are legitimate. `ComponentProps<typeof PandaUl>`
+ * is the type that admits exactly the real ones.
+ */
+export type StyledListRootProps = React.PropsWithChildren<
+  React.ComponentProps<typeof PandaUl> & {
+    /**
+     * `| undefined` is spelled out throughout this file because the repo runs
+     * `exactOptionalPropertyTypes`: without it a caller holding a
+     * possibly-unset variant cannot forward it, even though "unset" is exactly
+     * the case this component handles by following the app.
+     */
+    variant?: ListVariant | undefined;
+    /** Space between rows. A real CSS `gap` — see the note above. */
+    gap?: string | number | undefined;
+    /** Render as `<ol>` with numbers. */
+    showNumbers?: boolean;
+    /** Render bullets. Off by default; see the `role="list"` note. */
+    showBullets?: boolean;
+  }
+>;
+
+const StyledListRoot = React.forwardRef<
+  HTMLUListElement | HTMLOListElement,
+  StyledListRootProps
+>(
+  (
+    { children, variant, gap, showNumbers, showBullets, className, style, ...rest },
+    ref,
+  ) => {
+    log.trace("StyledListRoot rendered");
+
+    const resolved = useResolvedVariant(variant, LIST_VARIANTS);
+    const recipeClasses = listRecipe({ variant: resolved });
+
+    const listStyle = showNumbers ? "decimal" : showBullets ? "disc" : "none";
+
+    const ListTag = showNumbers ? PandaOl : PandaUl;
+
+    return (
+      <ListTag
+        ref={ref as React.Ref<HTMLUListElement & HTMLOListElement>}
+        className={[recipeClasses.root, className].filter(Boolean).join(" ")}
+        // `role` only when the marker is gone — with real markers the native
+        // semantics are intact and an explicit role would be noise.
+        role={listStyle === "none" ? "list" : undefined}
+        style={{
+          listStyleType: listStyle,
+          paddingLeft: listStyle !== "none" ? "1.5em" : undefined,
+          // Inline rather than a Panda `gap` prop: the value arrives at
+          // runtime, and Panda extracts at build time, so a prop here would
+          // emit a class with no rule behind it. Same trap as NEH-233.
+          ...(gap !== undefined ? { gap } : {}),
+          ...style,
+        }}
+        {...rest}
+      >
+        {children}
+      </ListTag>
+    );
+  },
+);
+
+StyledListRoot.displayName = "StyledList.Root";
+
+export type StyledListItemProps = React.ComponentProps<typeof PandaListItem> & {
+  /**
+   * Match the `Root`'s variant. Only needed when a row is rendered outside the
+   * `Root`'s own subtree — otherwise leave it; rows inherit their surface from
+   * the container's recipe.
+   */
+  variant?: ListVariant | undefined;
+};
+
+const StyledListItem = React.forwardRef<HTMLLIElement, StyledListItemProps>(
+  ({ children, className, variant, ...props }, ref) => {
+    const resolved = useResolvedVariant(variant, LIST_VARIANTS);
+    const recipeClasses = listRecipe({ variant: resolved });
+
+    return (
+      <PandaListItem
+        ref={ref}
+        className={[recipeClasses.item, className].filter(Boolean).join(" ")}
+        {...props}
+      >
+        {children}
+      </PandaListItem>
+    );
+  },
+);
+
+StyledListItem.displayName = "StyledList.Item";
+
+const StyledList = {
+  Root: StyledListRoot,
+  Item: StyledListItem,
+};
+
+export default StyledList;

package/src/components/StyledScrollbar.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+import { log } from "../config/logger";
+import React from "react";
+import { styled } from "styled-system/jsx";
+import type { HTMLStyledProps } from "styled-system/types";
+
+const PandaScrollBox = styled("div", {
+  base: {
+    overflow: "auto",
+    minHeight: 0,
+    flex: "1",
+    display: "flex",
+    paddingRight: "0.5rem",
+    flexDirection: "column",
+    scrollbarWidth: "thick",
+    // Via the token, not a literal `var(--hopper-…)`: the custom-property
+    // prefix is configurable per consumer (see the preset), so a hardcoded
+    // namespace paints nothing for any host that picked a different one.
+    scrollbarColor: "{colors.boxBgSecondary} transparent",
+  },
+});
+
+export interface StyledScrollbarProps extends HTMLStyledProps<"div"> {
+  border?: string | number;
+}
+
+const StyledScrollbar: React.FC<StyledScrollbarProps> = ({
+  children,
+  border,
+  ...rest
+}) => {
+  log.trace("StyledScrollbar rendered");
+  const extraStyles: React.CSSProperties = {};
+  if (border !== undefined) {
+    if (border === "none" || border === "0") {
+      extraStyles.borderWidth = "5px";
+      extraStyles.borderStyle = "none";
+      extraStyles.borderRadius = "0";
+    }
+  }
+  return (
+    <PandaScrollBox
+      data-testid="styled-scrollbar"
+      style={extraStyles}
+      {...rest}
+    >
+      {children}
+    </PandaScrollBox>
+  );
+};
+
+export default StyledScrollbar;

package/src/components/StyledSearch.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+import React from "react";
+import StyledBox from "./StyledBox";
+import StyledInputText from "./StyledInputText";
+import type { Dictation } from "./dictation";
+
+/**
+ * A search box.
+ *
+ * Thin on purpose: a `StyledInputText` of `type="search"` at a width that steps
+ * up with the viewport. The width is the only thing here worth sharing — a
+ * search field that spans a wide screen is harder to use, not easier, because
+ * the eye has to travel from the field to results that start back at the left.
+ *
+ * `type="search"` is not cosmetic. It gives the browser's own clear button, the
+ * right on-screen keyboard with a "search" action key, and the correct role for
+ * assistive tech.
+ *
+ * **It does not filter anything.** It owns a string and reports changes; what
+ * that string means belongs to the screen. The originating component took a
+ * `data` prop it never read, marked "for future filtering" — that is the shape
+ * this deliberately does not have.
+ */
+
+export interface StyledSearchProps {
+  /** Current query. Controlled. */
+  search: string;
+  onSearchChange: (value: string) => void;
+  placeholder?: string;
+  onKeyDown?: (e: React.KeyboardEvent<HTMLInputElement>) => void;
+  /**
+   * Accessible name. Defaults to the placeholder — but a field whose only name
+   * is placeholder text has no name once the user types, so pass one.
+   */
+  label?: string;
+  /** Host-supplied dictation. Omit for no microphone. */
+  dictation?: Dictation;
+  ["data-testid"]?: string;
+}
+
+const StyledSearch = React.forwardRef<HTMLInputElement, StyledSearchProps>(
+  function StyledSearch(
+    {
+      search,
+      onSearchChange,
+      placeholder = "Search...",
+      onKeyDown,
+      label,
+      dictation,
+      ...props
+    },
+    ref,
+  ) {
+    return (
+      <StyledBox
+        w={{ base: "300px", md: "400px", lg: "500px" }}
+        data-testid="search-container"
+      >
+        <StyledInputText
+          ref={ref}
+          type="search"
+          data-testid={props["data-testid"] ?? "search-input"}
+          aria-label={label ?? placeholder}
+          placeholder={placeholder}
+          value={search}
+          onChange={(e) => onSearchChange(e.target.value)}
+          onKeyDown={onKeyDown}
+          {...(dictation ? { dictation } : {})}
+        />
+      </StyledBox>
+    );
+  },
+);
+
+StyledSearch.displayName = "StyledSearch";
+
+export default StyledSearch;

package/src/components/StyledSeparator.tsx

@@ -0,0 +1,38 @@
+"use client";
+
+import { log } from "../config/logger";
+import { styled } from "styled-system/jsx";
+import {
+  separatorHorizontalRecipe,
+  separatorVerticalRecipe,
+} from "styled-system/recipes";
+import type { HTMLStyledProps } from "styled-system/types";
+
+const HorizontalSeparator = styled("div", separatorHorizontalRecipe);
+const VerticalSeparator = styled("div", separatorVerticalRecipe);
+
+type Orientation = "horizontal" | "vertical";
+type HorizontalVariant = "solid";
+type VerticalVariant = "solid";
+
+export interface StyledSeparatorProps extends HTMLStyledProps<"div"> {
+  orientation?: Orientation;
+  variant?: HorizontalVariant | VerticalVariant;
+}
+
+export const StyledSeparator = (props: StyledSeparatorProps) => {
+  log.trace("StyledSeparator rendered");
+  const { orientation = "horizontal", variant = "solid", ...rest } = props;
+
+  if (orientation === "horizontal") {
+    return (
+      <HorizontalSeparator variant={variant as HorizontalVariant} {...rest} />
+    );
+  }
+
+  return <VerticalSeparator variant={variant as VerticalVariant} {...rest} />;
+};
+
+StyledSeparator.displayName = "StyledSeparator";
+
+export default StyledSeparator;