@sixthshift/design-system 0.5.0 → 0.6.0

package/src/components/Toast/Toast.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { FloatingPortal, type FloatingPortalProps } from "@floating-ui/react";
 import { Button } from "@sixthshift/design-system/button";
 import { usePresence } from "@sixthshift/design-system/hooks";
@@ -19,6 +21,13 @@ export type ToastProps = Omit<MessageProps, "size"> & {
   onAction?: () => void;
   /** Portal root element (default: document.body) */
   root?: FloatingPortalProps["root"];
+  /**
+   * Set to `false` to play the exit animation and then call `onClose`. This is
+   * how a stack dismisses a toast on a timer: the toast stays mounted through
+   * its fade-out, and the stack drops it when `onClose` fires.
+   * @default true
+   */
+  open?: boolean;
   /**
    * Whether Toast should render in a portal and position itself.
    * Set to false when Toast is rendered by a parent that handles positioning (e.g., OverlayContext).
@@ -50,8 +59,8 @@ export type ToastProps = Omit<MessageProps, "size"> & {
  * portals itself (`FloatingPortal`, optionally to a custom `root`) and
  * applies the fixed bottom-center classes itself. Set it to `false` when a
  * parent already handles portalling and position — this is how
- * `OverlayContext`'s toast stack renders it. Toast has no built-in
- * auto-dismiss timer; that's `useToast`'s job, one layer up.
+ * `ToastStack` renders it. Toast has no built-in auto-dismiss timer; that's
+ * `ToastStack`'s job, one layer up, driven through `open`.
  *
  * Exit animation (`usePresence`) keeps Toast mounted through its fade-out,
  * so `onClose` fires only after the animation completes. Toast has no focus
@@ -59,13 +68,20 @@ export type ToastProps = Omit<MessageProps, "size"> & {
  * a dialog.
  */
 export const Toast = React.forwardRef<HTMLDivElement, ToastProps>(
-  ({ className, intent = "neutral", title, icon, action, onAction, onClose, root, standalone = true, children, ...props }, ref) => {
+  ({ className, intent = "neutral", title, icon, action, onAction, onClose, root, open = true, standalone = true, children, ...props }, ref) => {
     const { ref: presenceRef, state, isMounted, show, hide } = usePresence();
 
-    // Start enter animation on mount
+    // `open` drives presence: enter on mount, exit when it flips false. The
+    // close handler is read through a ref so a new identity does not replay
+    // the exit.
+    const onCloseRef = React.useRef(onClose);
+    React.useEffect(() => {
+      onCloseRef.current = onClose;
+    });
     React.useEffect(() => {
-      show();
-    }, [show]);
+      if (open) show();
+      else hide(() => onCloseRef.current?.());
+    }, [open, show, hide]);
 
     // Handle close with exit animation
     const handleClose = React.useCallback(() => {

package/src/components/Toggle/Toggle.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
 import type { VariantProps } from "class-variance-authority";
@@ -32,7 +34,7 @@ export type ToggleProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "o
  * Built directly on Button: it calls `buttonRecipe(...)` and takes the same
  * `variant`/`intent`/`size` axes Button does, plus `iconOnly` for a toolbar
  * toggle whose whole content is an icon. The
- * pressed-state colour mapping lives in `src/theme/recipes/toggle.css`,
+ * pressed-state colour mapping lives in `src/components/Toggle/toggle.recipe.css`,
  * keyed off the `data-state="on" | "off"` attribute this component renders
  * alongside `aria-pressed`.
  *

package/src/components/ToggleGroup/ToggleGroupMultiple.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import * as React from "react";
 import { ToggleGroupContainer } from "./ToggleGroupContainer";
@@ -19,6 +21,8 @@ const ToggleGroupMultiple = React.forwardRef<HTMLDivElement, ToggleGroupMultiple
       iconOnly = false,
       disabled,
       className,
+      name,
+      form,
       ...props
     },
     ref
@@ -54,6 +58,8 @@ const ToggleGroupMultiple = React.forwardRef<HTMLDivElement, ToggleGroupMultiple
             onClick={() => handleToggle(option.value)}
           />
         ))}
+        {/* Mirrors the selection for native form submission, same contract as Checkbox/DatePicker. */}
+        {name && value.map((v) => <input key={v} type="hidden" name={`${name}[]`} value={v} {...(form ? { form } : {})} />)}
       </ToggleGroupContainer>
     );
   }

package/src/components/ToggleGroup/ToggleGroupSingle.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import * as React from "react";
 import { getRovingTargetIndex } from "../../internal/rovingFocus";
@@ -21,6 +23,8 @@ const ToggleGroupSingle = React.forwardRef<HTMLDivElement, ToggleGroupSingleProp
       iconOnly = false,
       disabled,
       className,
+      name,
+      form,
       ...props
     },
     ref
@@ -98,6 +102,8 @@ const ToggleGroupSingle = React.forwardRef<HTMLDivElement, ToggleGroupSingleProp
             onClick={() => handleSelect(option.value)}
           />
         ))}
+        {/* Mirrors the selection for native form submission, same contract as Checkbox/DatePicker. */}
+        {name && value && <input type="hidden" name={name} value={value} {...(form ? { form } : {})} />}
       </ToggleGroupContainer>
     );
   }

package/src/components/ToggleGroup/toggleGroup.types.ts

@@ -39,6 +39,13 @@ export type ToggleGroupBaseProps = Omit<React.HTMLAttributes<HTMLDivElement>, "o
   iconOnly?: boolean;
   /** Disable all options */
   disabled?: boolean;
+  /**
+   * Input name for native form submission. The selection is mirrored into
+   * hidden `<input>`s — `name` in single mode, `${name}[]` in multiple mode.
+   */
+  name?: string;
+  /** The `form` attribute for the hidden input(s), for a group rendered outside its `<form>`. */
+  form?: string;
 };
 
 export type ToggleGroupSingleProps = ToggleGroupBaseProps & {

package/src/components/Tooltip/Tooltip.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { autoUpdate, flip, offset, type Placement, shift, useDismiss, useFloating, useFocus, useHover, useInteractions, useRole } from "@floating-ui/react";
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import { TooltipBody } from "./components/TooltipBody";

package/src/components/Tooltip/components/TooltipBody.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { FloatingPortal } from "@floating-ui/react";
 import { cn } from "@sixthshift/design-system/utils";
 import * as React from "react";

package/src/components/Tooltip/components/TooltipContext.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { createContext, useContext } from "react";
 
 export type TooltipContextValue = {

package/src/components/Tooltip/components/TooltipTrigger.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import * as React from "react";
 import { Slot } from "../../../internal/Slot";
 import { useTooltipContext } from "./TooltipContext";

package/src/hooks/useCollapsible.ts

@@ -1,3 +1,5 @@
+"use client";
+
 import { useCallback, useState } from "react";
 
 export function useCollapsible(defaultExpanded = true) {

package/src/hooks/useControllableState.ts

@@ -1,3 +1,5 @@
+"use client";
+
 import { useCallback, useRef, useState } from "react";
 
 declare const process: undefined | { env?: { NODE_ENV?: string } };

package/src/hooks/useDebouncedCallback.ts

@@ -1,3 +1,5 @@
+"use client";
+
 import { useCallback, useRef } from "react";
 
 /**

package/src/hooks/useDebouncedState.ts

@@ -1,3 +1,5 @@
+"use client";
+
 import { useEffect, useState } from "react";
 
 /**

package/src/hooks/useDeviceFormFactor.ts

@@ -1,3 +1,5 @@
+"use client";
+
 import { useSyncExternalStore } from "react";
 
 /**

package/src/hooks/useLocalStorage.ts

@@ -1,3 +1,5 @@
+"use client";
+
 import { useCallback, useSyncExternalStore } from "react";
 
 type SetValue<T> = T | ((prev: T) => T);

package/src/hooks/useMergedFloatingRef.ts

@@ -1,3 +1,5 @@
+"use client";
+
 import { useCallback } from "react";
 import type { WritableRefObject } from "../internal/types";
 

package/src/hooks/usePresence.ts

@@ -1,3 +1,5 @@
+"use client";
+
 import { type RefCallback, useCallback, useEffect, useRef, useState } from "react";
 
 // =============================================================================

package/src/hooks/useStack.ts

@@ -1,4 +1,6 @@
-import { type Dispatch, type Reducer, startTransition, useCallback, useEffect, useReducer } from "react";
+"use client";
+
+import { type Dispatch, type Reducer, startTransition, useCallback, useEffect, useReducer, useRef } from "react";
 
 type Id = string | number;
 type Transition = {
@@ -70,23 +72,44 @@ export function useStack<T extends StackItem>(initialStack: T[] = []): [T[], Sta
 
   const [state, dispatch] = useReducer(reducer, initialStack);
 
+  // One removal timer per transitioning item. The effect re-runs on every
+  // state change, so timers are tracked in a ref keyed by item id: an item
+  // already scheduled is never scheduled again (re-running the effect must not
+  // reset or duplicate its countdown), and a timer whose item has left the
+  // stack by other means is cancelled rather than left to fire at a reused id.
+  const removalTimersRef = useRef(new Map<Id, ReturnType<typeof setTimeout>>());
+
   useEffect(() => {
-    const itemsToRemove = state.filter((item) => item.transition);
+    const timers = removalTimersRef.current;
+    const transitioning = new Set(state.filter((item) => item.transition).map((item) => item.id));
 
-    if (itemsToRemove.length === 0) {
-      return;
+    for (const [id, timer] of timers) {
+      if (!transitioning.has(id)) {
+        clearTimeout(timer);
+        timers.delete(id);
+      }
     }
 
-    itemsToRemove.reverse().forEach((itemToRemove) => {
-      setTimeout(
-        () => {
-          dispatch({ type: "remove", id: itemToRemove.id });
-        }, // We found the item by the `transition` property, so we can be sure it exists.
-        (itemToRemove.transition as Transition).duration
-      );
-    });
+    for (const item of state) {
+      if (!item.transition || timers.has(item.id)) continue;
+      const timer = setTimeout(() => {
+        timers.delete(item.id);
+        dispatch({ type: "remove", id: item.id });
+      }, item.transition.duration);
+      timers.set(item.id, timer);
+    }
   }, [state]);
 
+  // Unmount only: without this, a stack unmounted mid-transition dispatches
+  // into an unmounted reducer.
+  useEffect(() => {
+    const timers = removalTimersRef.current;
+    return () => {
+      for (const timer of timers.values()) clearTimeout(timer);
+      timers.clear();
+    };
+  }, []);
+
   // Memoize the dispatch wrapper to prevent unnecessary re-renders
   // dispatch from useReducer is stable, so this only creates once
   const wrappedDispatch = useCallback((params: Action<T>) => {

package/src/hooks/useTheme.ts

@@ -1,3 +1,5 @@
+"use client";
+
 import { useCallback, useSyncExternalStore } from "react";
 
 export type Theme = "light" | "dark" | "system";

package/src/internal/PickerField.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { cn } from "@sixthshift/design-system/utils";
 import { X } from "lucide-react";
 import * as React from "react";

package/src/internal/SegmentedField.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { cn } from "@sixthshift/design-system/utils";
 import * as React from "react";
 import { useRef, useState } from "react";

package/src/internal/escapeLayers.ts

@@ -0,0 +1,53 @@
+"use client";
+
+import { useEffect } from "react";
+
+/**
+ * Registry of open "escape layers" — transient floating overlays (popovers,
+ * select dropdowns, picker calendars) that should consume an Escape press
+ * before any dialog beneath them reacts to it.
+ *
+ * The dialogs and these overlays each listen for Escape on `document`
+ * independently (floating-ui's `useDismiss` has no tree here), and document
+ * listeners fire in registration order — usually the dialog's first, since it
+ * opened first. So a dialog cannot rely on `defaultPrevented`; instead it asks
+ * this registry whether a layer is open and, if so, leaves the Escape to it.
+ * The registry is read synchronously during the event, before React commits
+ * the layer's close, so the layer that is handling this Escape still counts.
+ *
+ * Module-level on purpose: Popover, Select and Modal live in separate subpath
+ * entries with no shared context, and a context would also miss overlays
+ * rendered outside an `OverlayProvider`.
+ */
+const transientLayers = new Set<symbol>();
+const dialogLayers = new Set<symbol>();
+
+/** True while any transient escape-consuming overlay (popover-like) is open. */
+export const hasOpenEscapeLayer = () => transientLayers.size > 0;
+
+/** True while any modal dialog is open. A non-modal Sheet under a Modal defers Escape to it. */
+export const hasOpenEscapeDialog = () => dialogLayers.size > 0;
+
+function useRegistration(registry: Set<symbol>, active: boolean) {
+  useEffect(() => {
+    if (!active) return;
+    const token = Symbol("escape-layer");
+    registry.add(token);
+    return () => {
+      registry.delete(token);
+    };
+  }, [registry, active]);
+}
+
+/**
+ * Marks this component as an open transient escape layer while `active` is
+ * true. Call with the overlay's `open` state.
+ */
+export function useEscapeLayer(active: boolean) {
+  useRegistration(transientLayers, active);
+}
+
+/** Marks this component as an open modal dialog while `active` is true. */
+export function useEscapeDialog(active: boolean) {
+  useRegistration(dialogLayers, active);
+}

package/src/lib/ErrorBoundary.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { Component, type ErrorInfo, type ReactNode } from "react";
 
 export type ErrorFallbackProps = {

package/src/lib/contexts/ComponentsContext/ComponentsContext.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { createContext, type PropsWithChildren, type ReactNode, useContext } from "react";
 
 type LinkProps = {

package/src/lib/contexts/OverlayContext/OverlayContext.tsx

@@ -1,10 +1,19 @@
+"use client";
+
 import { FloatingPortal, type FloatingPortalProps } from "@floating-ui/react";
 import { type StackItem, useStack } from "@sixthshift/design-system/hooks";
 import { createContext, type FunctionComponent, type PropsWithChildren, useContext, useEffect, useMemo } from "react";
+import { hasOpenEscapeLayer } from "../../../internal/escapeLayers";
+import { ToastStack } from "./ToastStack";
+import { toastStore as defaultToastStore, type ToastStore } from "./toastStore";
 
 type OverlayContextProps = {
   modal?: FloatingPortalProps["root"];
   toast?: FloatingPortalProps["root"];
+  /** The toast stack to render. Default: the app's one, which `toast()` opens onto. Hand in your own for a second bundle or a test. */
+  toasts?: ToastStore;
+  /** Merged over the toast stack's container classes, so an app can move it (above a bottom bar, into a corner). */
+  toastClassName?: string;
 };
 
 /** Stack item for overlays - component is a self-contained wrapper */
@@ -18,10 +27,13 @@ type OverlayStackItem = StackItem & {
 };
 
 type OverlayContextType = {
-  modalRoot?: FloatingPortalProps["root"];
+  // `undefined` spelled out rather than an optional `?:` — the context value
+  // below always sets the key, and `exactOptionalPropertyTypes` treats "absent"
+  // and "present but undefined" as different types.
+  modalRoot: FloatingPortalProps["root"] | undefined;
   modalStack: ReturnType<typeof useStack<OverlayStackItem>>;
-  toastRoot?: FloatingPortalProps["root"];
-  toastStack: ReturnType<typeof useStack<OverlayStackItem>>;
+  toastRoot: FloatingPortalProps["root"] | undefined;
+  toastStore: ToastStore;
 };
 
 /**
@@ -35,18 +47,28 @@ const rootProp = (root: FloatingPortalProps["root"] | undefined) => (root === un
 const OverlayContext = createContext<OverlayContextType>(undefined as unknown as OverlayContextType);
 export const useOverlayContext = () => useContext(OverlayContext);
 
-export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }: PropsWithChildren<OverlayContextProps>) => {
-  // The roots pass through unresolved, deliberately. Defaulting them to
-  // `document.body` here read the DOM during render, which threw the whole
-  // tree under SSR — and it bought nothing: `FloatingPortal` already falls
-  // back to `document.body` when no `root` is given, on the client, where a
-  // body exists. Both portals below are behind a non-empty stack, and both
-  // stacks start empty, so nothing portals on the server either way.
+export const OverlayProvider = ({
+  modal: modalRoot,
+  toast: toastRoot,
+  toasts: toastStore = defaultToastStore,
+  toastClassName,
+  children,
+}: PropsWithChildren<OverlayContextProps>) => {
+  // The roots pass through unresolved, deliberately. `"use client"` makes this a
+  // Client Component, but a Client Component is still rendered once on the
+  // server — defaulting to `document.body` here read the DOM at render scope and
+  // threw "document is not defined" on the first App Router request, which
+  // src/testing/stories.ssr.test.tsx and src/exports.ssr.test.tsx now catch. It
+  // bought nothing either: `FloatingPortal` already falls back to
+  // `document.body` when no `root` is given, and does it in an effect, on the
+  // client, where a body exists. Both portals below are behind a non-empty
+  // stack, and both stacks start empty, so nothing portals on the server anyway.
+  //
+  // Modals are a `useStack` here; toasts are a store outside React, so that
+  // `toast()` works from code that is not a component.
   const modalStack = useStack<OverlayStackItem>([]);
-  const toastStack = useStack<OverlayStackItem>([]);
 
   const [modals] = modalStack;
-  const [toasts] = toastStack;
 
   // Global escape key handler - closes topmost modal
   useEffect(() => {
@@ -54,6 +76,10 @@ export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }
 
     const handleEscape = (event: KeyboardEvent) => {
       if (event.key === "Escape") {
+        // A transient overlay open above the modal (a Select dropdown, a
+        // Popover, a picker calendar) consumes this Escape via its own
+        // dismiss handling — closing the modal too would double-fire.
+        if (hasOpenEscapeLayer()) return;
         const topModal = modals.at(-1);
         topModal?.onClose?.();
       }
@@ -69,9 +95,9 @@ export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }
       modalRoot,
       modalStack,
       toastRoot,
-      toastStack,
+      toastStore,
     }),
-    [modalRoot, modalStack, toastRoot, toastStack]
+    [modalRoot, modalStack, toastRoot, toastStore]
   );
 
   return (
@@ -87,18 +113,8 @@ export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }
         </FloatingPortal>
       )}
 
-      {/* Toast stack - rendered in portal */}
-      {toasts.length > 0 && (
-        <FloatingPortal {...rootProp(toastRoot)}>
-          <div className="pointer-events-none fixed bottom-6 left-1/2 z-toast flex -translate-x-1/2 flex-col-reverse items-center gap-3">
-            {toasts.map(({ id, component: Component, onClose, ...props }) => (
-              <div key={id} className="pointer-events-auto">
-                <Component onClose={onClose} {...props} />
-              </div>
-            ))}
-          </div>
-        </FloatingPortal>
-      )}
+      {/* Toast stack - portals itself, and only while it holds something */}
+      <ToastStack store={toastStore} className={toastClassName} {...rootProp(toastRoot)} />
     </OverlayContext.Provider>
   );
 };

package/src/lib/contexts/OverlayContext/ToastStack.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+import { FloatingPortal, type FloatingPortalProps } from "@floating-ui/react";
+import { Toast } from "@sixthshift/design-system/toast";
+import { cn } from "@sixthshift/design-system/utils";
+import { useCallback, useEffect, useSyncExternalStore } from "react";
+import { toastStore as defaultStore, type ToastRecord, type ToastStore } from "./toastStore";
+
+const EMPTY: readonly ToastRecord[] = [];
+
+/** The store's stack, re-rendering the caller as it changes. Empty during server rendering. */
+export function useToasts(store: ToastStore = defaultStore): readonly ToastRecord[] {
+  return useSyncExternalStore(store.subscribe, store.snapshot, () => EMPTY);
+}
+
+/**
+ * One toast in the stack: the dismissal timer lives here, not in the store,
+ * so the store stays free of the DOM. Expiry and the X button take the same
+ * path — `open` flips false, `Toast` plays its exit, and `onClose` drops the
+ * record once the animation ends.
+ */
+function ToastItem({ record, store }: { record: ToastRecord; store: ToastStore }) {
+  const { id, duration, closing } = record;
+  // `duration` is the stack's to act on, not the toast's to render.
+  const { component: Component = Toast, duration: _duration, ...props } = record.options;
+
+  useEffect(() => {
+    if (duration <= 0 || closing) return;
+    const timer = setTimeout(() => store.close(id), duration);
+    return () => clearTimeout(timer);
+  }, [id, duration, closing, store]);
+
+  const onClose = useCallback(() => store.remove(id), [store, id]);
+
+  return (
+    <div className="pointer-events-auto" data-toast-id={id} data-toast-intent={props.intent ?? "neutral"}>
+      <Component {...props} standalone={false} open={!closing} onClose={onClose} />
+    </div>
+  );
+}
+
+export type ToastStackProps = {
+  /** The stack to render. Default: the app's one, which `toast()` opens onto. */
+  store?: ToastStore | undefined;
+  /** Portal root (default: `document.body`). */
+  root?: FloatingPortalProps["root"] | undefined;
+  /** Merged over the container's classes, so an app can move the stack (above a bottom bar, to a corner). */
+  className?: string | undefined;
+};
+
+/** The container's own classes: bottom centre, newest at the bottom, click-through between toasts. */
+export const TOAST_STACK_CLASS = "pointer-events-none fixed bottom-6 left-1/2 z-toast flex -translate-x-1/2 flex-col-reverse items-center gap-3";
+
+/**
+ * The open toasts, portalled and positioned. `OverlayProvider` renders one;
+ * render it yourself only when there is no provider to host it.
+ */
+export function ToastStack({ store = defaultStore, root, className }: ToastStackProps) {
+  const toasts = useToasts(store);
+  if (toasts.length === 0) return null;
+  // `root` omitted rather than passed as `undefined`: see OverlayContext's `rootProp`.
+  return (
+    <FloatingPortal {...(root === undefined ? {} : { root })}>
+      <div className={cn(TOAST_STACK_CLASS, className)} data-toast-stack="" data-count={toasts.length}>
+        {toasts.map((record) => (
+          <ToastItem key={record.id} record={record} store={store} />
+        ))}
+      </div>
+    </FloatingPortal>
+  );
+}

package/src/lib/contexts/OverlayContext/hooks/useModal.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { ModalContextProvider, type ModalProps, type OnClose } from "@sixthshift/design-system/modal";
 import { type ComponentType, type ReactNode, Suspense, useCallback, useId, useRef } from "react";
 import { useOverlayContext } from "../OverlayContext";