@stonedogcode/style 0.9.0

package/src/components/StyledCollapsible.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+import React, { useId, useState } from "react";
+import { styled } from "styled-system/jsx";
+
+/**
+ * A disclosure: a trigger that shows and hides a region.
+ *
+ * Built here rather than in an app because three products want the same thing
+ * and one of them currently reaches for Chakra to get it. It knows nothing
+ * about what it contains.
+ *
+ * ## Why the content stays mounted
+ *
+ * Collapsed content is hidden with `hidden`, not unmounted. Unmounting looks
+ * tidier and is wrong for the audience this package serves: it discards focus,
+ * scroll position and any input a reader had part-typed, so a mis-click on the
+ * trigger destroys work rather than merely hiding it. `hidden` also keeps the
+ * region addressable by `aria-controls` at all times, which is what lets the
+ * trigger's `aria-expanded` mean anything.
+ *
+ * `hidden` rather than `display: none` in CSS: it is the accessibility default,
+ * it removes the content from the accessibility tree *and* from tab order in
+ * one attribute, and it cannot be defeated by a host stylesheet the way a
+ * utility class can.
+ */
+
+export interface StyledCollapsibleProps {
+  /** The disclosure's own control. Rendered inside a `<button>`. */
+  trigger: React.ReactNode;
+  children: React.ReactNode;
+  /** Controlled. Omit to let the component own the state. */
+  open?: boolean | undefined;
+  /** Initial state when uncontrolled. Default `false`. */
+  defaultOpen?: boolean | undefined;
+  onOpenChange?: ((next: boolean) => void) | undefined;
+  /**
+   * Names the trigger.
+   *
+   * State belongs in `aria-expanded`, never in the name — a name that reads
+   * "Collapse tools" is announced as "Collapse tools, expanded", which says the
+   * same thing twice and in opposite tenses. Say what the control is *for*.
+   */
+  "aria-label"?: string | undefined;
+  /** Escape hatch for a host that must reach the trigger in a test. */
+  triggerTestId?: string | undefined;
+  contentTestId?: string | undefined;
+}
+
+/**
+ * 48px, matching every other interactive floor in this package: stated as a
+ * minimum rather than left to emerge from padding, so no density step or font
+ * profile can erode it below the WCAG target size.
+ */
+const CONTROL_MIN_TARGET = "48px";
+
+const CollapsibleTrigger = styled("button", {
+  base: {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: "2",
+    minHeight: CONTROL_MIN_TARGET,
+    minWidth: CONTROL_MIN_TARGET,
+    px: "2",
+    borderRadius: "md",
+    borderWidth: "1px",
+    borderStyle: "solid",
+    borderColor: "borderBgPrimary",
+    color: "textPrimary",
+    background: "transparent",
+    cursor: "pointer",
+  },
+});
+
+const StyledCollapsible: React.FC<StyledCollapsibleProps> = ({
+  trigger,
+  children,
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  "aria-label": ariaLabel,
+  triggerTestId,
+  contentTestId,
+}) => {
+  const [uncontrolled, setUncontrolled] = useState(defaultOpen);
+
+  // Controlled the moment `open` is supplied, and uncontrolled otherwise —
+  // decided per render rather than latched at mount, because a host that
+  // switches between the two mid-life has a bug we should not paper over by
+  // silently ignoring the prop.
+  const isControlled = open !== undefined;
+  const isOpen = isControlled ? open : uncontrolled;
+
+  const contentId = useId();
+
+  const toggle = () => {
+    const next = !isOpen;
+    // The internal state moves even when controlled. If the host ignores the
+    // callback the component would otherwise appear dead to the pointer, and a
+    // control that does nothing when pressed is indistinguishable from a broken
+    // one — for this audience, the reader concludes the app is broken, not that
+    // they misread the affordance.
+    if (!isControlled) setUncontrolled(next);
+    onOpenChange?.(next);
+  };
+
+  return (
+    <>
+      <CollapsibleTrigger
+        type="button"
+        onClick={toggle}
+        aria-expanded={isOpen}
+        aria-controls={contentId}
+        aria-label={ariaLabel}
+        data-testid={triggerTestId}
+      >
+        {trigger}
+      </CollapsibleTrigger>
+      <div id={contentId} hidden={!isOpen} data-testid={contentTestId}>
+        {children}
+      </div>
+    </>
+  );
+};
+
+export default StyledCollapsible;
+export { StyledCollapsible };

package/src/components/StyledDefinitionList.tsx

@@ -0,0 +1,134 @@
+"use client";
+
+import React from "react";
+import { styled } from "styled-system/jsx";
+import { dlRecipe } from "styled-system/recipes";
+import { useResolvedVariant } from "../config/style-config";
+import { ALL_VARIANTS, type AllowedVariant } from "../config/types";
+
+/**
+ * Term-and-definition pairs in two columns — the shape a details panel wants.
+ *
+ * `<dl>` rather than a table because these are *pairs*, not a grid: there is
+ * one value per label, no column headers, and nothing to sort. A screen reader
+ * announces "list, 6 items" and reads each term with its definition, which a
+ * two-column table of unheaded cells does not.
+ *
+ * ```tsx
+ * <StyledDefinitionList.Root>
+ *   <StyledDefinitionList.Term>Admitted</StyledDefinitionList.Term>
+ *   <StyledDefinitionList.Definition>4 March</StyledDefinitionList.Definition>
+ * </StyledDefinitionList.Root>
+ * ```
+ *
+ * ## Two defects fixed on the way across
+ *
+ * **It ignored the app-wide appearance.** The variant defaulted to a literal
+ * `"solid"` and never consulted the host's configuration, so a product set to
+ * `glass` or `matte` got one panel that stayed solid regardless. Every other
+ * component in this package resolves through `useResolvedVariant`; this one
+ * predated it. It does now, which means an unset variant follows the app
+ * rather than overriding it.
+ *
+ * **The row separators never rendered.** `dlRecipe` drew them with
+ * `& > li:not(:last-child)` — but a `<dl>` contains `<dt>` and `<dd>`, never
+ * `<li>`, so the selector matched nothing in the only element the recipe is
+ * ever applied to. The rule was present, valid, and dead. It is `& > dd` now,
+ * which puts a line after each pair rather than between a term and its own
+ * definition.
+ *
+ * That fix is in the recipe rather than here, so it reaches any consumer using
+ * `dlRecipe` directly. Nothing consumed it before this component, so no
+ * existing surface changes.
+ *
+ * ## The `link` / `selected` coercion is gone
+ *
+ * The originating version silently mapped `link`, `ghost` and `selected` onto
+ * `solid`. A coerced variant still renders, so a call site asking for `ghost`
+ * saw a solid panel and no warning — the same silent-coercion failure NEH-234
+ * documented. `useResolvedVariant`'s allow-list makes the supported set
+ * explicit instead: `DL_VARIANTS` is what the recipe actually defines.
+ */
+
+const PandaDefinitionList = styled("dl", {
+  base: {
+    display: "grid",
+    gridTemplateColumns: "max-content 1fr",
+    gap: "0.5rem 1.5rem",
+    padding: "1rem",
+  },
+});
+
+const PandaTerm = styled("dt", {
+  base: {
+    fontWeight: "bold",
+    gridColumn: 1,
+  },
+});
+
+const PandaDescription = styled("dd", {
+  base: {
+    margin: 0,
+    gridColumn: 2,
+  },
+});
+
+/** The appearances `dlRecipe` actually defines. */
+export const DL_VARIANTS = [
+  "solid",
+  "outline",
+  "aurora",
+  "glass",
+  "matte",
+  "none",
+  "unstyled",
+] as const;
+
+export type DlVariant = (typeof DL_VARIANTS)[number];
+
+export type StyledDefinitionListProps = React.PropsWithChildren<
+  React.HTMLAttributes<HTMLDListElement> & {
+    /**
+     * `undefined` is spelled out because the repo runs
+     * `exactOptionalPropertyTypes`: without it a caller holding a
+     * possibly-unset variant cannot forward it, even though "unset" is
+     * precisely the case this component handles by following the app.
+     */
+    variant?: AllowedVariant | DlVariant | undefined;
+  }
+>;
+
+const StyledDefinitionListRoot = React.forwardRef<
+  HTMLDListElement,
+  StyledDefinitionListProps
+>(({ children, variant, className, ...rest }, ref) => {
+  const resolved = useResolvedVariant(variant, DL_VARIANTS);
+
+  return (
+    <PandaDefinitionList
+      ref={ref}
+      className={[dlRecipe({ variant: resolved }), className]
+        .filter(Boolean)
+        .join(" ")}
+      {...rest}
+    >
+      {children}
+    </PandaDefinitionList>
+  );
+});
+
+StyledDefinitionListRoot.displayName = "StyledDefinitionList.Root";
+
+const StyledDefinitionList = {
+  Root: StyledDefinitionListRoot,
+  Term: PandaTerm,
+  Definition: PandaDescription,
+};
+
+/**
+ * Re-exported so a consumer can validate a variant before passing it — the
+ * same vocabulary `useResolvedVariant` gates on.
+ */
+export { ALL_VARIANTS };
+
+export default StyledDefinitionList;

package/src/components/StyledFieldset.tsx

@@ -0,0 +1,157 @@
+"use client";
+
+import React from "react";
+import { styled } from "styled-system/jsx";
+import { formRecipe } from "styled-system/recipes";
+import { useResolvedVariant } from "../config/style-config";
+import { log } from "../config/logger";
+import StyledFormLabel from "./StyledFormLabel";
+
+/**
+ * A group of related form controls, with a visible name.
+ *
+ * The `<fieldset>`/`<legend>` pair is the only markup that gives a *group* an
+ * accessible name. Assistive tech announces the legend when focus enters the
+ * group and, for radios in particular, that legend is the question the options
+ * are answering — without it a screen reader meets "Yes / No" with no idea what
+ * is being asked. That is the reason to reach for this rather than a heading
+ * above a `<div>`, which looks identical and carries none of it.
+ *
+ * ```tsx
+ * <StyledFieldset>
+ *   <StyledFieldset.Legend>Contact preferences</StyledFieldset.Legend>
+ *   <StyledFieldset.Content>
+ *     <StyledFieldset.Field>
+ *       <StyledFieldset.Label htmlFor="email">Email</StyledFieldset.Label>
+ *       <StyledFieldset.Value><input id="email" /></StyledFieldset.Value>
+ *     </StyledFieldset.Field>
+ *   </StyledFieldset.Content>
+ * </StyledFieldset>
+ * ```
+ *
+ * ## Two defects fixed on the way across
+ *
+ * **No variant meant no styling at all.** The root read
+ * `variant ? formRecipe({ variant }) : ""` — so a fieldset rendered without an
+ * explicit `variant` prop got an empty class string: no surface, no border, no
+ * padding, and no response to the app-wide appearance. Every other component in
+ * this package treats an absent variant as "follow the app", and 18 HopperGuard
+ * call sites were relying on a default that silently did nothing.
+ *
+ * It resolves through `useResolvedVariant` now, so an unset variant follows the
+ * host's configuration and an unrecognised one falls back to `solid` rather
+ * than to nothing. **This visibly changes existing fieldsets** — they gain the
+ * surface they were always supposed to have, which is why it is called out here
+ * rather than buried in the move.
+ *
+ * **`Label` was a second, divergent form label.** It was a bare `<label>` with
+ * `display: block` and a margin — no colour token, no font-size profile, and no
+ * `required`/`optional` markers. `StyledFormLabel` in this same package handles
+ * all four, and having two labels in one design system is precisely how a
+ * product ends up with form rows that do not match each other. `Label` now
+ * delegates to it, so a field inside a fieldset and a field outside one are the
+ * same control.
+ *
+ * The DOM shape is unchanged — both render a `<label>` — but the label now
+ * follows the user's text-size setting, which it did not before.
+ */
+
+const PandaFieldsetLegend = styled("legend", {
+  base: { fontWeight: "bold", paddingX: "0.5rem" },
+});
+const PandaFieldsetContent = styled("div", { base: { marginTop: "1rem" } });
+const PandaFieldsetField = styled("div", {
+  base: { width: "100%", marginBottom: "1rem" },
+});
+const PandaFieldsetValue = styled("div");
+
+/** The appearances `formRecipe` defines. */
+export const FIELDSET_VARIANTS = [
+  "solid",
+  "outline",
+  "lines",
+  "aurora",
+  "glass",
+  "matte",
+  "none",
+  "unstyled",
+] as const;
+
+export type FieldsetVariant = (typeof FIELDSET_VARIANTS)[number];
+
+export type StyledFieldsetProps = React.ComponentProps<"fieldset"> & {
+  /**
+   * `| undefined` is spelled out 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?: FieldsetVariant | undefined;
+};
+
+const StyledFieldsetRoot = React.forwardRef<
+  HTMLFieldSetElement,
+  StyledFieldsetProps
+>(({ children, variant, className, ...props }, ref) => {
+  log.trace("StyledFieldset.Root rendered");
+
+  const resolved = useResolvedVariant(variant, FIELDSET_VARIANTS);
+
+  return (
+    <fieldset
+      ref={ref}
+      className={[formRecipe({ variant: resolved }), className]
+        .filter(Boolean)
+        .join(" ")}
+      {...props}
+    >
+      {children}
+    </fieldset>
+  );
+});
+StyledFieldsetRoot.displayName = "StyledFieldset.Root";
+
+const StyledFieldsetLegend = React.forwardRef<
+  HTMLLegendElement,
+  React.ComponentProps<typeof PandaFieldsetLegend>
+>((props, ref) => <PandaFieldsetLegend ref={ref} {...props} />);
+StyledFieldsetLegend.displayName = "StyledFieldset.Legend";
+
+const StyledFieldsetContent = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentProps<typeof PandaFieldsetContent>
+>((props, ref) => <PandaFieldsetContent ref={ref} {...props} />);
+StyledFieldsetContent.displayName = "StyledFieldset.Content";
+
+const StyledFieldsetField = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentProps<typeof PandaFieldsetField>
+>((props, ref) => <PandaFieldsetField ref={ref} {...props} />);
+StyledFieldsetField.displayName = "StyledFieldset.Field";
+
+const StyledFieldsetValue = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentProps<typeof PandaFieldsetValue>
+>((props, ref) => <PandaFieldsetValue ref={ref} {...props} />);
+StyledFieldsetValue.displayName = "StyledFieldset.Value";
+
+interface StyledFieldsetComponentType
+  extends React.ForwardRefExoticComponent<
+    StyledFieldsetProps & React.RefAttributes<HTMLFieldSetElement>
+  > {
+  Legend: typeof StyledFieldsetLegend;
+  Content: typeof StyledFieldsetContent;
+  Field: typeof StyledFieldsetField;
+  /** `StyledFormLabel` — the same label used outside a fieldset. */
+  Label: typeof StyledFormLabel;
+  Value: typeof StyledFieldsetValue;
+}
+
+const StyledFieldset = StyledFieldsetRoot as StyledFieldsetComponentType;
+StyledFieldset.Legend = StyledFieldsetLegend;
+StyledFieldset.Content = StyledFieldsetContent;
+StyledFieldset.Field = StyledFieldsetField;
+StyledFieldset.Label = StyledFormLabel;
+StyledFieldset.Value = StyledFieldsetValue;
+
+export default StyledFieldset;

package/src/components/StyledFlex.tsx

@@ -0,0 +1,13 @@
+import { styled, type HTMLStyledProps } from "styled-system/jsx";
+
+export const StyledFlex = styled("div", {
+  base: {
+    display: "flex",
+  },
+});
+
+export type StyledFlexProps = HTMLStyledProps<typeof StyledFlex>;
+
+StyledFlex.displayName = "StyledFlex";
+
+export default StyledFlex;