@stonedogcode/style 0.9.0

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@stonedogcode/style",
+  "version": "0.9.0",
+  "description": "A Panda CSS design system: a themeable Panda preset plus the React components built on it.",
+  "license": "Apache-2.0",
+  "author": "StoneDogCode L.L.C.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stonedog-code/stonedog-style.git"
+  },
+  "//publishConfig": "A SCOPED package defaults to access: restricted. Publishing one without this succeeds, prints nothing unusual, and then 404s for every consumer — which reads as a missing package rather than as a private one. It was not needed while the name was unscoped (those default to public), so it is new as of NEH-482 and it is the single thing most likely to be forgotten in a scope migration.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "//exports": "This package ships TypeScript SOURCE, not a bundled dist/. Panda CSS extracts styles by statically parsing source files, so a consumer's `panda codegen` must be able to read our .tsx. A pre-bundled dist would emit class names Panda never generated a stylesheet for. Consumers transpile us (Next.js: `transpilePackages: ['@stonedogcode/style']`) and add our src to their panda `include` globs. See CLAUDE.md.",
+  "exports": {
+    ".": "./src/index.ts",
+    "./preset": "./src/preset/index.ts",
+    "./package.json": "./package.json"
+  },
+  "//files": "The package ships SOURCE, so `src` has to go out whole — but only the part a consumer imports. Tests, Playwright component tests and their harnesses were 57 of 130 entries and never resolvable from any export, so every one of them was a file a consumer's Panda run had to be told to skip. `src/__tests__/published-package.test.ts` asserts this listing rather than this array: npm's own resolution of these negations is the only thing that decides what ships.",
+  "files": [
+    "src",
+    "!src/**/__tests__/**",
+    "!src/**/*.ct.tsx",
+    "!src/**/*.harness.tsx",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "scripts": {
+    "panda:prepare": "panda codegen",
+    "panda:build": "panda codegen && panda cssgen --outfile styled-system/styles.css",
+    "panda:watch": "panda --watch",
+    "prepare": "npm run panda:prepare",
+    "pretype-check": "npm run panda:prepare",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint . --ext ts,tsx",
+    "//pretest": "panda:build, not panda:prepare — the token-contract suite asserts against the generated stylesheet, which cssgen produces and codegen alone does not.",
+    "pretest": "npm run panda:build",
+    "test": "jest",
+    "pretest:ct": "npm run panda:build",
+    "test:ct": "playwright test --config playwright-ct.config.ts",
+    "test:ct:ui": "playwright test --config playwright-ct.config.ts --ui",
+    "test:coverage": "jest --coverage",
+    "gate": "npm run type-check && npm run lint && npm run test",
+    "//publish:stonedog-style": "Publish to npm, end to end. Run from a terminal, interactively — npm prompts for the 2FA one-time password and the login flow needs a browser. It refuses a checkout that is detached, dirty, or behind origin/main: a submodule sits detached at the consumer's gitlink by default, and publishing from one commit behind ships a tarball missing the very thing you are publishing for while looking like a success (it did, on 2026-08-04, without TitleLogo.tsx). Runs the gate, prints the tarball listing, then proves the result by installing from the registry into a temp directory.",
+    "publish:stonedog-style": "bash scripts/publish-package.sh",
+    "version:bump:patch": "npm version patch --no-git-tag-version",
+    "version:bump:minor": "npm version minor --no-git-tag-version",
+    "audit": "npm audit --audit-level=moderate"
+  },
+  "peerDependencies": {
+    "@pandacss/dev": ">=1.9.0",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "csstype": "^3.2.3"
+  },
+  "devDependencies": {
+    "@pandacss/dev": "^1.11.1",
+    "@playwright/experimental-ct-react": "^1.62.1",
+    "@playwright/test": "^1.62.1",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^8.57.1",
+    "eslint-plugin-react": "^7.37.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "react": "^19.0.4",
+    "react-dom": "^19.0.4",
+    "ts-jest": "^29.4.11",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "panda-css",
+    "design-system",
+    "react",
+    "components",
+    "theme"
+  ]
+}

package/src/components/DictationControls.tsx

@@ -0,0 +1,141 @@
+"use client";
+
+import React from "react";
+import { styled } from "styled-system/jsx";
+import { useIntentIcon } from "../config/intent-icons";
+import type { Dictation } from "./dictation";
+
+/**
+ * The mic (and optional redo) buttons that sit inside a dictatable field.
+ *
+ * Shared by `StyledInputText` and `StyledInputTextArea` so the two cannot
+ * drift — they had already drifted in the app this came from, where only one
+ * of them offered redo.
+ *
+ * ## Accessibility, which is most of what this component is
+ *
+ * - **`aria-pressed`, not a label that changes.** A toggle whose name flips
+ *   between "Dictate" and "Stop" reads as a different control each time and
+ *   breaks voice input ("click Dictate" stops matching once recording starts).
+ *   The name stays put; the state is what changes.
+ * - **Recording is not signalled by colour alone.** Colour drives the icon,
+ *   `aria-pressed` drives assistive tech, and the two together mean the state
+ *   survives both a screen reader and achromatopsia.
+ * - **44×44 minimum.** These sit inside a field and the temptation is to make
+ *   them small enough not to crowd the text. The floor wins; the field gets
+ *   padding instead.
+ */
+
+export interface DictationControlsProps {
+  dictation: Dictation;
+  /** Accessible name for the mic. */
+  micLabel: string;
+  /** Accessible name for redo. */
+  redoLabel: string;
+  /**
+   * Where the buttons sit vertically.
+   *
+   * `center` for a single-line field. `top` for a textarea, which grows — a
+   * centred button would drift down the field as the user typed and end up
+   * beside the middle of their text.
+   */
+  anchor?: "center" | "top";
+}
+
+/** Room the field must leave on its trailing edge so text clears the buttons. */
+export function dictationPadding(dictation: Dictation | undefined): string | undefined {
+  if (!dictation?.isSupported) return undefined;
+  return dictation.showRedo ? "5.5em" : "3.5em";
+}
+
+const ControlButton = styled("button", {
+  base: {
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    // WCAG 2.5.5. Non-negotiable even though these live inside a field —
+    // the field pads itself to make room rather than shrinking them.
+    minWidth: "48px",
+    minHeight: "48px",
+    background: "transparent",
+    border: "none",
+    padding: "0.25em",
+    cursor: "pointer",
+    lineHeight: "0",
+    borderRadius: "md",
+    color: "textPrimary",
+    _hover: { color: "textAccent" },
+  },
+  variants: {
+    recording: {
+      // A token, not `var(--colors-red-500, #e53e3e)` as the originating code
+      // had — that namespace is undefined under every prefix, so the literal
+      // always won and the recording state ignored the theme entirely.
+      true: { color: "textError" },
+    },
+  },
+});
+
+export default function DictationControls({
+  dictation,
+  micLabel,
+  redoLabel,
+  anchor = "center",
+}: DictationControlsProps) {
+  const micIcon = useIntentIcon("dictate");
+  const redoIcon = useIntentIcon("redo");
+
+  if (!dictation.isSupported) return null;
+
+  const vertical: React.CSSProperties =
+    anchor === "top"
+      ? { top: "0.25em" }
+      : { top: "50%", transform: "translateY(-50%)" };
+
+  // ONE absolutely-positioned row, not two independently-offset buttons.
+  //
+  // The first version gave each button its own `right` offset — `3em` and
+  // `0.25em` — and they overlapped by 7px at every viewport. `em` resolves
+  // against inherited font size, so the gap between two 44px buttons was
+  // expressed in a unit with no relationship to 44px, and any change to the
+  // surrounding type scale would have moved them again. Flex owns the gap now
+  // and the arithmetic is gone.
+  //
+  // Redo comes first in DOM order, so it sits inboard and the mic stays on the
+  // edge where the user learned it — and tab order matches reading order.
+  return (
+    <div
+      style={{
+        position: "absolute",
+        right: "0.25em",
+        display: "flex",
+        alignItems: "center",
+        gap: "0.25em",
+        ...vertical,
+      }}
+    >
+      {/* Suppressed while the continue prompt is up — see `Dictation`. */}
+      {dictation.showRedo && dictation.redo && !dictation.continuePrompt && (
+        <ControlButton
+          type="button"
+          aria-label={redoLabel}
+          data-testid="dictation-redo"
+          onClick={dictation.redo}
+        >
+          {redoIcon}
+        </ControlButton>
+      )}
+      <ControlButton
+        type="button"
+        aria-label={micLabel}
+        // The name is constant and the STATE changes — see the note above.
+        aria-pressed={dictation.isListening}
+        recording={dictation.isListening}
+        data-testid="dictation-mic"
+        onClick={dictation.onMicClick}
+      >
+        {micIcon}
+      </ControlButton>
+    </div>
+  );
+}

package/src/components/DictationPrompt.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+import React from "react";
+import { styled } from "styled-system/jsx";
+import StyledButton from "./StyledButton";
+import StyledText from "./StyledText";
+import type { Dictation } from "./dictation";
+
+/**
+ * "Add to what you already wrote?" — the choice a second recording forces.
+ *
+ * Renders **below** the field, not inside it, and that is the whole design.
+ * The mic and redo buttons are affordances: small, in the corner, ignorable.
+ * This is a question with two answers and a wrong one that destroys work, so it
+ * takes up room, sits in the reading path, and does not go away on its own.
+ *
+ * It exists because the alternative is guessing. A user who dictates a
+ * paragraph, stops, thinks, and presses the mic again has not told anyone
+ * whether they meant to add or replace — and silently replacing is a data-loss
+ * bug wearing the costume of a UX preference.
+ *
+ * Announced as a `group` with an accessible name rather than a live region: it
+ * appears in response to the user's own action, so they are already attending
+ * to it, and an alert would interrupt a screen reader mid-sentence for
+ * something they just asked for.
+ */
+
+export interface DictationPromptProps {
+  dictation: Dictation;
+  question: string;
+  continueLabel: string;
+  startOverLabel: string;
+}
+
+const PromptRow = styled("div", {
+  base: {
+    display: "flex",
+    flexWrap: "wrap",
+    alignItems: "center",
+    gap: "2",
+    marginTop: "2",
+  },
+});
+
+export default function DictationPrompt({
+  dictation,
+  question,
+  continueLabel,
+  startOverLabel,
+}: DictationPromptProps) {
+  if (!dictation.continuePrompt) return null;
+  if (!dictation.chooseContinue || !dictation.chooseStartOver) return null;
+
+  return (
+    <PromptRow role="group" aria-label={question} data-testid="dictation-continue-prompt">
+      <StyledText>{question}</StyledText>
+      {/* Real buttons, not bare styled elements — they inherit the 44px floor
+          and the theme like every other control. Continue comes first because
+          it is the non-destructive answer. */}
+      <StyledButton
+        type="button"
+        variant="outline"
+        data-testid="dictation-continue"
+        onClick={dictation.chooseContinue}
+      >
+        {continueLabel}
+      </StyledButton>
+      <StyledButton
+        type="button"
+        variant="ghost"
+        data-testid="dictation-start-over"
+        onClick={dictation.chooseStartOver}
+      >
+        {startOverLabel}
+      </StyledButton>
+    </PromptRow>
+  );
+}

package/src/components/StyledBox.tsx

@@ -0,0 +1,174 @@
+import React from "react";
+import { styled } from "styled-system/jsx";
+import { boxRecipe, type BoxRecipeVariantProps } from "styled-system/recipes";
+import type { HTMLStyledProps, ConditionalValue } from "styled-system/types";
+import { Property } from "csstype";
+import { css, cx } from "styled-system/css";
+import StyledGrid from "./StyledGrid";
+import StyledVStack from "./StyledVStack";
+
+interface StyledGridPanelProps {
+  leftPanel?: React.ReactNode;
+  rightPanel?: React.ReactNode;
+  children: React.ReactNode;
+}
+
+const StyledGridPanel: React.FC<StyledGridPanelProps> = ({
+  leftPanel,
+  rightPanel,
+  children,
+}) => {
+  const hasPanels = leftPanel || rightPanel;
+
+  if (!hasPanels) {
+    return <div style={{ width: "100%", height: "100%" }}>{children}</div>;
+  }
+
+  return (
+    <StyledGrid
+      width="100%"
+      height="100%"
+      gap={0}
+      templateColumns="min-content 1fr min-content"
+      alignItems="stretch"
+      data-testid="styled-grid-panel"
+    >
+      <StyledBox itemID="left-panel" mr="3" style={{ gridColumn: 1 }}>{leftPanel}</StyledBox>
+      <StyledBox style={{ width: "100%", height: "100%", gridColumn: 2 }}>
+        {children}
+      </StyledBox>
+      <StyledBox itemID="right-panel" ml="3" style={{ overflowY: "auto", height: "100%", gridColumn: 3 }}>
+        {rightPanel}
+      </StyledBox>
+    </StyledGrid>
+  );
+};
+
+export interface StyledBoxProps
+  extends HTMLStyledProps<"div">,
+  BoxRecipeVariantProps {
+  as?: React.ElementType;
+  leftPanel?: React.ReactNode;
+  rightPanel?: React.ReactNode;
+  topPanel?: React.ReactNode;
+  bottomPanel?: React.ReactNode;
+  header?: React.ReactNode;
+  footer?: React.ReactNode;
+  mt?: ConditionalValue<Property.MarginTop | number>;
+  mb?: ConditionalValue<Property.MarginBottom | number>;
+  ml?: ConditionalValue<Property.MarginLeft | number>;
+  mr?: ConditionalValue<Property.MarginRight | number>;
+  p?: ConditionalValue<Property.Padding | number>;
+  pt?: ConditionalValue<Property.PaddingTop | number>;
+  pb?: ConditionalValue<Property.PaddingBottom | number>;
+  pl?: ConditionalValue<Property.PaddingLeft | number>;
+  pr?: ConditionalValue<Property.PaddingRight | number>;
+  px?: ConditionalValue<Property.Padding | number>;
+  py?: ConditionalValue<Property.Padding | number>;
+  m?: ConditionalValue<Property.Margin | number>;
+  mx?: ConditionalValue<Property.Margin | number>;
+  my?: ConditionalValue<Property.Margin | number>;
+  width?: ConditionalValue<Property.Width | number>;
+  w?: ConditionalValue<Property.Width | number>;
+  height?: ConditionalValue<Property.Height | number>;
+  h?: ConditionalValue<Property.Height | number>;
+  minH?: ConditionalValue<Property.MinHeight | number>;
+  maxW?: ConditionalValue<Property.MaxWidth | number>;
+  display?: ConditionalValue<Property.Display>;
+  flexDirection?: ConditionalValue<Property.FlexDirection>;
+  alignItems?: ConditionalValue<Property.AlignItems>;
+  justifyContent?: ConditionalValue<Property.JustifyContent>;
+  bg?: ConditionalValue<Property.Background>;
+  background?: ConditionalValue<Property.Background>;
+  color?: ConditionalValue<Property.Color>;
+  borderRadius?: ConditionalValue<Property.BorderRadius | number>;
+  border?: ConditionalValue<Property.Border | number>;
+  borderWidth?: ConditionalValue<Property.BorderWidth | number>;
+  borderColor?: ConditionalValue<Property.BorderColor>;
+  boxShadow?: ConditionalValue<Property.BoxShadow>;
+  position?: ConditionalValue<Property.Position>;
+  top?: ConditionalValue<Property.Top | number>;
+  right?: ConditionalValue<Property.Right | number>;
+  bottom?: ConditionalValue<Property.Bottom | number>;
+  left?: ConditionalValue<Property.Left | number>;
+  zIndex?: ConditionalValue<Property.ZIndex | number>;
+  overflow?: ConditionalValue<Property.Overflow>;
+  overflowX?: ConditionalValue<Property.OverflowX>;
+  overflowY?: ConditionalValue<Property.OverflowY>;
+  textAlign?: ConditionalValue<Property.TextAlign>;
+  gap?: ConditionalValue<Property.Gap | number>;
+  noWrap?: boolean;
+  scrollbar?: "auto" | "on" | "off";
+}
+
+const StyledBoxRoot = styled("div", boxRecipe);
+
+const StyledBox = React.forwardRef<HTMLDivElement, StyledBoxProps>(
+  ({
+    as,
+    children,
+    leftPanel,
+    rightPanel,
+    topPanel,
+    bottomPanel,
+    header,
+    footer,
+    noWrap,
+    scrollbar,
+    textAlign,
+    zIndex,
+    className,
+    ...rest
+  },
+    ref,
+  ) => {
+
+    // Create class for filtered properties
+    const filteredPropsClass = css({
+      // Only include if defined to avoid overriding with undefined
+      ...(textAlign && { textAlign }),
+      ...(zIndex !== undefined && { zIndex })
+    });
+    const combinedClassName = cx(className, filteredPropsClass);
+
+    const resolvedHeader = topPanel || header;
+    const resolvedFooter = bottomPanel || footer;
+
+    // scrollbar prop controls inner content overflow
+    const innerOverflow: Property.Overflow = scrollbar === "auto" ? "auto" : scrollbar === "on" ? "scroll" : "hidden";
+
+    if (noWrap) {
+      if (resolvedHeader || resolvedFooter) {
+        return (
+          <StyledBoxRoot ref={ref} {...(as ? { as } : {})} className={combinedClassName} display="flex" flexDirection="column" {...rest}>
+            {resolvedHeader}
+            <div style={{ flex: 1, minHeight: 0 }}>{children}</div>
+            {resolvedFooter}
+          </StyledBoxRoot>
+        );
+      }
+      return (
+        <StyledBoxRoot ref={ref} {...(as ? { as } : {})} className={combinedClassName} {...rest}>
+          {children}
+        </StyledBoxRoot>
+      );
+    }
+    return (
+      <StyledBoxRoot ref={ref} {...(as ? { as } : {})} className={combinedClassName} {...rest}>
+        <StyledVStack gap="0" width="100%" height="100%" style={{ overflow: innerOverflow }}>
+          {resolvedHeader}
+          <div style={{ flex: 1, minHeight: 0, width: "100%", overflow: innerOverflow }}>
+            <StyledGridPanel leftPanel={leftPanel} rightPanel={rightPanel}>
+              {children}
+            </StyledGridPanel>
+          </div>
+          {resolvedFooter}
+        </StyledVStack>
+      </StyledBoxRoot>
+    );
+  },
+);
+
+StyledBox.displayName = "StyledBox";
+export default StyledBox;
+export { StyledBox };

package/src/components/StyledButton.tsx

@@ -0,0 +1,144 @@
+"use client";
+
+import React from "react";
+import { styled } from "styled-system/jsx";
+import type { HTMLStyledProps } from "styled-system/types";
+import { buttonRecipe } from "styled-system/recipes";
+import type { AllowedVariant } from "../config/types";
+import { useStyleConfig } from "../config/style-config";
+import StyledText from "./StyledText";
+import StyledSpinner from "./StyledSpinner";
+import StyledTooltip from "./StyledTooltip";
+
+/**
+ * The button every other button is built from.
+ *
+ * ## Why this does NOT use `useResolvedVariant`
+ *
+ * Everywhere else, `useResolvedVariant` narrows to the five *theme* variants
+ * and coerces anything else to `solid`, because most recipes define only those
+ * five and passing an unknown one renders an unstyled control.
+ *
+ * `buttonRecipe` is the exception: it defines **all ten** — the five theme
+ * variants plus `ghost`, `none`, `link`, `unstyled` and `selected`. Running the
+ * usual narrowing here would silently turn every ghost and link button solid,
+ * which is a visible regression at a lot of call sites. So this resolves against
+ * the wider `AllowedVariant` set on purpose.
+ *
+ * If you add a component whose recipe covers all ten, do the same and say why.
+ * If it covers only five, use `useResolvedVariant`.
+ */
+
+const PandaButton = styled("button", {
+  base: {
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+  },
+});
+
+export interface StyledButtonProps extends HTMLStyledProps<"button"> {
+  leftIcon?: React.ReactNode;
+  rightIcon?: React.ReactNode;
+  /** Any of the ten the button recipe defines, not just the five theme ones. */
+  variant?: AllowedVariant;
+  children?: React.ReactNode;
+  /** Disables the button and swaps the label for a spinner. */
+  loading?: boolean;
+  disabled?: boolean;
+  tooltip?: React.ReactNode;
+  /** What the spinner says while `loading`. Prefer naming the action. */
+  loadText?: React.ReactNode;
+  /** Keep the label on one line even when the button is narrow. */
+  noWrap?: boolean;
+}
+
+const StyledButton = React.forwardRef<HTMLButtonElement, StyledButtonProps>(
+  function StyledButton(
+    {
+      leftIcon,
+      rightIcon,
+      children,
+      variant,
+      loading,
+      disabled,
+      tooltip,
+      noWrap,
+      loadText = "Loading",
+      ...rest
+    },
+    ref,
+  ) {
+    const { variant: appVariant } = useStyleConfig();
+    const effectiveVariant = variant ?? appVariant;
+
+    // Positioning props are pulled out of the Panda prop bag and applied as
+    // inline style. Panda would otherwise emit them as atomic classes, which
+    // lose to the recipe's own class in the cascade — so a caller positioning a
+    // button absolutely would find it ignored.
+    const { top, right, position, zIndex, ...restWithoutPosition } = rest;
+    const style = {
+      top,
+      right,
+      position,
+      zIndex,
+      ...(noWrap ? { whiteSpace: "nowrap" as const } : {}),
+      ...(rest.style || {}),
+    };
+
+    return (
+      <StyledTooltip tooltip={tooltip}>
+        <PandaButton
+          ref={ref}
+          className={buttonRecipe({ variant: effectiveVariant })}
+          // A loading button must not be clickable — a second submit is the
+          // classic double-charge bug — and `aria-busy` is what tells a screen
+          // reader why it went inert.
+          disabled={loading || disabled}
+          aria-busy={loading}
+          data-panda-variant={effectiveVariant}
+          style={style as React.CSSProperties}
+          {...restWithoutPosition}
+        >
+          {leftIcon && <IconSlot side="left">{leftIcon}</IconSlot>}
+          {loading ? (
+            <StyledSpinner loadText={loadText} />
+          ) : (
+            <StyledText>{children}</StyledText>
+          )}
+          {rightIcon && <IconSlot side="right">{rightIcon}</IconSlot>}
+        </PandaButton>
+      </StyledTooltip>
+    );
+  },
+);
+
+/**
+ * Spacing for an icon beside the label.
+ *
+ * `em`, not `px`, so the gap tracks the button's own font size — which this
+ * system changes app-wide via the font-size profile. A fixed gap looks correct
+ * at `md` and wrong at both ends of the scale.
+ */
+const IconSlot = ({
+  side,
+  children,
+}: {
+  side: "left" | "right";
+  children: React.ReactNode;
+}) => (
+  <span
+    style={{
+      [side === "left" ? "marginRight" : "marginLeft"]: "0.5em",
+      display: "inline-flex",
+      alignItems: "center",
+    }}
+  >
+    {children}
+  </span>
+);
+
+StyledButton.displayName = "StyledButton";
+
+export default StyledButton;
+export { StyledButton };