@stonedogcode/style 0.17.0 → 0.20.0

package/src/components/useDisclosure.ts

@@ -0,0 +1,139 @@
+"use client";
+
+import { useCallback, useId, useState } from "react";
+
+/**
+ * The mechanics of a disclosure, with no markup attached.
+ *
+ * ## Why this exists as a hook and not only as a component
+ *
+ * `StyledCollapsible` renders its own `<button>` with the trigger inside it.
+ * That is the right default and it is the wrong shape for a host whose control
+ * is *already* a button — an icon button with a tooltip, say, sitting in a
+ * header row opposite a title. Handed such a control as `trigger`, the
+ * component would wrap one `<button>` in another: invalid HTML that React warns
+ * will break hydration, and one affordance split into two, with the accessible
+ * name on the inner element and `aria-expanded` on the outer one. A screen
+ * reader then announces a button that says nothing, containing a button that
+ * says nothing about its state.
+ *
+ * The alternative — the host hand-rolling `useState`, a `useId`, the two ARIA
+ * attributes and the `hidden` decision — is how one product ends up with two
+ * disclosures that disagree, which is exactly what NEH-1100 records happening.
+ *
+ * So the mechanics live here, and both the component below and any host
+ * composition are built on the same three lines. There is one implementation of
+ * *a disclosure*; there are as many arrangements of it as there are layouts.
+ *
+ * ```tsx
+ * const { open, triggerProps, contentProps } = useDisclosure();
+ *
+ * <header>
+ *   <h2>Vitals</h2>
+ *   <MyIconButton {...triggerProps} aria-label={open ? "Hide" : "Show"} />
+ * </header>
+ * <section {...contentProps}>…</section>
+ * ```
+ *
+ * ## `hidden`, never unmounted
+ *
+ * `contentProps.hidden` is the whole opinion this hook carries, and it is not
+ * negotiable by a prop. Unmounting collapsed content looks tidier and discards
+ * focus, scroll position and anything part-typed — so a mis-press destroys work
+ * rather than merely hiding it. `hidden` also keeps the region addressable by
+ * `aria-controls` at all times, which is what lets `aria-expanded` mean
+ * anything: a control that claims to expand something must point at something
+ * that exists while it is collapsed.
+ *
+ * A host that genuinely wants unmounting can render `{open && …}` itself. It
+ * should then know it is giving that up.
+ */
+
+export interface UseDisclosureOptions {
+  /** Controlled. Omit to let the hook own the state. */
+  open?: boolean | undefined;
+  /** Initial state when uncontrolled. Default `false`. */
+  defaultOpen?: boolean | undefined;
+  onOpenChange?: ((next: boolean) => void) | undefined;
+  /**
+   * The id linking trigger to content. Generated when omitted.
+   *
+   * Supply one only when something outside this pair must reference the region
+   * by id; two disclosures given the same id will produce two triggers pointing
+   * at one region.
+   */
+  id?: string | undefined;
+}
+
+/** Spread onto the ONE element that is the control. It must be a `<button>`. */
+export interface DisclosureTriggerProps {
+  type: "button";
+  "aria-expanded": boolean;
+  "aria-controls": string;
+  onClick: () => void;
+}
+
+/** Spread onto the region the control shows and hides. */
+export interface DisclosureContentProps {
+  id: string;
+  hidden: boolean;
+}
+
+export interface Disclosure {
+  open: boolean;
+  toggle: () => void;
+  setOpen: (next: boolean) => void;
+  triggerProps: DisclosureTriggerProps;
+  contentProps: DisclosureContentProps;
+}
+
+export function useDisclosure(options: UseDisclosureOptions = {}): Disclosure {
+  const { open: controlled, defaultOpen = false, onOpenChange, id } = options;
+
+  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 = controlled !== undefined;
+  const open = isControlled ? controlled : uncontrolled;
+
+  const generatedId = useId();
+  const contentId = id ?? generatedId;
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      // The internal state moves even when controlled. If the host ignores the
+      // callback the control would otherwise appear dead to the pointer, and a
+      // control that does nothing when pressed is indistinguishable from a
+      // broken one.
+      if (!isControlled) setUncontrolled(next);
+      onOpenChange?.(next);
+    },
+    [isControlled, onOpenChange],
+  );
+
+  const toggle = useCallback(() => setOpen(!open), [setOpen, open]);
+
+  return {
+    open,
+    toggle,
+    setOpen,
+    triggerProps: {
+      // `type="button"` because the commonest place a disclosure lives is
+      // inside a form, where an untyped button submits it. The symptom is a
+      // page reload on the first press of a "show more" control.
+      type: "button",
+      "aria-expanded": open,
+      "aria-controls": contentId,
+      onClick: toggle,
+    },
+    contentProps: {
+      id: contentId,
+      hidden: !open,
+    },
+  };
+}
+
+export default useDisclosure;

package/src/index.ts

@@ -210,6 +210,16 @@ export {
 } from "./components/StyledFieldHelp";
 export type { StyledFieldHelpProps } from "./components/StyledFieldHelp";
 
+/**
+ * A file dropzone with image previews. Ships no artwork: both glyph slots
+ * default to nothing and the host passes its own icon set if it wants one.
+ */
+export {
+  default as StyledImageUpload,
+  StyledImageUpload as ImageUpload,
+} from "./components/StyledImageUpload";
+export type { StyledImageUploadProps } from "./components/StyledImageUpload";
+
 // ---------------------------------------------------------------------------
 // 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
@@ -315,3 +325,39 @@ export { DL_VARIANTS } from "./components/StyledDefinitionList";
 
 export { default as StyledSparkLine } from "./components/StyledSparkLine";
 export type { StyledSparkLineProps } from "./components/StyledSparkLine";
+
+/**
+ * A data table that renders real `<table>` markup rather than a div grid — the
+ * table role is what carries row and column position to a screen reader.
+ */
+export { default as StyledTable, StyledTable as Table } from "./components/StyledTable";
+export type {
+  StyledTableProps,
+  StyledTableHeaderProps,
+  StyledTableBodyProps,
+  ColumnDefinition,
+} from "./components/StyledTable";
+
+// ---------------------------------------------------------------------------
+// Notifications
+// ---------------------------------------------------------------------------
+export { default as StyledToaster, StyledToaster as Toaster } from "./components/StyledToaster";
+export type { StyledToasterProps } from "./components/StyledToaster";
+
+export { createToaster, DEFAULT_DURATIONS } from "./components/toaster-store";
+export type {
+  Toast,
+  ToastAction,
+  ToastOptions,
+  ToastType,
+  ToasterStore,
+  ToasterStoreOptions,
+} from "./components/toaster-store";
+
+export { default as useDisclosure } from "./components/useDisclosure";
+export type {
+  Disclosure,
+  DisclosureContentProps,
+  DisclosureTriggerProps,
+  UseDisclosureOptions,
+} from "./components/useDisclosure";

package/src/preset/index.ts

@@ -27,6 +27,7 @@ import { stackRecipe } from "./recipes/stack";
 import { stripedRecipe } from "./recipes/striped";
 import { tagRecipe } from "./recipes/tag";
 import { textRecipe } from "./recipes/text";
+import { toastRecipe } from "./recipes/toast";
 import { tooltipRecipe } from "./recipes/tooltip";
 
 import {
@@ -56,8 +57,9 @@ export interface StonedogStylePresetOptions {
 /**
  * Every recipe, keyed by the name it is exported under in `styled-system/recipes`.
  *
- * Five of these (`alertRecipe`, `listRecipe`, `menuRecipe`, `inputBoolRecipe`,
- * `inputRadioRootRecipe`) are slot recipes declared with `defineSlotRecipe`.
+ * Six of these (`alertRecipe`, `listRecipe`, `menuRecipe`, `inputBoolRecipe`,
+ * `inputRadioRootRecipe`, `toastRecipe`) are slot recipes declared with
+ * `defineSlotRecipe`.
  * Panda accepts them here rather than under `slotRecipes` and generates them
  * correctly — verified against HopperGuard's own generated output. Moving them
  * to `slotRecipes` would be more "correct" by the docs and would change the
@@ -87,6 +89,7 @@ const recipes = {
   stripedRecipe,
   tagRecipe,
   textRecipe,
+  toastRecipe,
   tooltipRecipe,
 };
 

package/src/preset/recipes/toast.ts

@@ -0,0 +1,161 @@
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * A transient message: the region it lives in, and the card itself.
+ *
+ * Extracted from HopperGuard, where the card was a `cva` in the component file
+ * and the region was a nine-cell CSS grid of which one cell was ever used. Both
+ * are here now, for the reason every recipe is: a `cva` inside a component is
+ * invisible to a consumer's Panda run unless that consumer globs this package's
+ * source, whereas a recipe is emitted from config with no parsing at all.
+ *
+ * ## The accent is a border, not a background
+ *
+ * Status is carried by a 4px bar down the leading edge rather than by tinting
+ * the whole card. Two reasons, and the second is the load-bearing one:
+ *
+ * - A toast sits over arbitrary page content, so it needs an opaque surface of
+ *   its own to stay readable. A tint would fight that.
+ * - **Colour is never the only cue.** The accent says the same thing as the
+ *   glyph the component renders beside the message, so a reader who cannot
+ *   distinguish the hues loses nothing — WCAG 1.4.1, Level A. Deleting the
+ *   glyph "because the colour already says it" is the regression this note
+ *   exists to stop.
+ *
+ * `borderInlineStart` rather than `borderLeft`: in a right-to-left document the
+ * accent belongs on the right, and the logical property is what moves it there.
+ */
+export const toastRecipe = defineSlotRecipe({
+  className: "toast",
+  description: "A transient message and the region that stacks them",
+  slots: [
+    "region",
+    "root",
+    "indicator",
+    "content",
+    "title",
+    "description",
+    "action",
+    "close",
+  ],
+  base: {
+    region: {
+      position: "fixed",
+      // Anchored to one corner rather than laid out in a grid of nine cells:
+      // the extracted version declared all nine and rendered into exactly one,
+      // so eight of them were markup nothing could ever reach.
+      insetBlockEnd: "4",
+      insetInlineEnd: "4",
+      display: "flex",
+      flexDirection: "column",
+      alignItems: "flex-end",
+      gap: "3",
+      // The region spans far enough to stack wide toasts but must not swallow
+      // clicks meant for the page beneath it — `none` here, `auto` on each
+      // card. Without this pairing a dismissed-but-still-animating toast
+      // leaves an invisible plate over the corner of the app.
+      pointerEvents: "none",
+      maxWidth: "calc(100vw - {spacing.8})",
+      zIndex: "toast",
+    },
+    root: {
+      pointerEvents: "auto",
+      display: "flex",
+      alignItems: "center",
+      gap: "4",
+      borderRadius: "md",
+      boxShadow: "lg",
+      paddingInline: "4",
+      paddingBlock: "3",
+      minWidth: { base: "320px", lg: "600px" },
+      maxWidth: { base: "400px", lg: "700px" },
+      fontSize: "md",
+      // Stated, not inherited: a themed typeface otherwise reaches the page and
+      // stops at the edge of the component (NEH-289).
+      fontFamily: "body",
+      borderWidth: "1px",
+      borderStyle: "solid",
+      // `borderBgPrimary`, not the `borderSubtle` this was first written with:
+      // that token belongs to HopperGuard's vocabulary, not this package's, and
+      // Panda passes an unknown token through as a literal — the card would
+      // have rendered with `border-color: borderSubtle`, which the browser
+      // discards, so the toast would have had no border at all and nothing
+      // would have said so. The package's own token-contract test caught it.
+      borderColor: "borderBgPrimary",
+      backgroundColor: "boxBgPrimary",
+      color: "textPrimary",
+      transition: "opacity 200ms ease, transform 200ms ease",
+      // `data-state` rather than a class: the renderer flips one attribute and
+      // the same rule drives both directions, so there is no window in which a
+      // toast has neither state.
+      "&[data-state='closed']": {
+        opacity: "0",
+        transform: "translateY(0.5rem)",
+      },
+      "&[data-state='open']": {
+        opacity: "1",
+        transform: "translateY(0)",
+      },
+    },
+    indicator: {
+      flexShrink: 0,
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "center",
+      lineHeight: "1",
+      fontSize: "lg",
+    },
+    content: {
+      flex: "1",
+      minWidth: "0",
+      display: "flex",
+      flexDirection: "column",
+      gap: "1",
+    },
+    title: {
+      fontWeight: "bold",
+    },
+    description: {
+      display: "block",
+    },
+    action: {
+      flexShrink: 0,
+    },
+    close: {
+      flexShrink: 0,
+      display: "inline-flex",
+      alignItems: "center",
+      justifyContent: "center",
+      // 48px, matching every other interactive floor in this package. A close
+      // control is the one thing on a toast a person is *aiming* at, often
+      // while it is animating, so it is the last place to shave a target down
+      // to the size of its glyph.
+      minWidth: "48px",
+      minHeight: "48px",
+      borderRadius: "md",
+      borderWidth: "1px",
+      borderStyle: "solid",
+      borderColor: "transparent",
+      background: "transparent",
+      color: "inherit",
+      cursor: "pointer",
+    },
+  },
+  variants: {
+    /**
+     * The status accent. `default` deliberately has none — a toast that means
+     * nothing in particular should not borrow a colour that means something.
+     */
+    type: {
+      success: { root: { borderInlineStartWidth: "4px", borderInlineStartColor: "borderSuccess" } },
+      error: { root: { borderInlineStartWidth: "4px", borderInlineStartColor: "borderError" } },
+      warning: { root: { borderInlineStartWidth: "4px", borderInlineStartColor: "borderWarning" } },
+      info: { root: { borderInlineStartWidth: "4px", borderInlineStartColor: "borderBgAccent" } },
+      loading: { root: { borderInlineStartWidth: "4px", borderInlineStartColor: "borderBgAccent" } },
+      default: {},
+    },
+  },
+  defaultVariants: {
+    type: "default",
+  },
+});