@stridge/noctis 1.0.0-beta.0

package/dist/components/textarea/textarea.slots.js

@@ -0,0 +1,33 @@
+//#region src/components/textarea/textarea.slots.ts
+/**
+* The slot vocabulary every `Textarea` part stamps as its `data-slot`. The in-field action and count are
+* the shared `field-*` parts (see {@link FieldDataAttributes}); the toolbar hosts them.
+*/
+const TEXTAREA_SLOTS = {
+	root: "noctis-textarea",
+	control: "noctis-textarea-control",
+	toolbar: "noctis-textarea-toolbar"
+};
+/**
+* The data attributes the {@link Textarea} (and the Base UI control it renders) expose for styling and
+* testing. The shell's look is keyed off the root `data-slot="noctis-textarea"` plus `data-size`. State
+* flows from the editable control: the shell reads the control's `:disabled`/`aria-invalid`/`readonly`
+* (and Base UI/Field `data-*`) through `:has()`, so validity and disabled have one source of truth, with
+* the root's own `[data-invalid]`/`[data-disabled]` as additive shell-only overrides. Focus is calm and
+* ring-less, shifting the border to the focus role, mirroring Input.
+*/
+let TextareaDataAttributes = /* @__PURE__ */ function(TextareaDataAttributes) {
+	/** The rendered element of a given part (root shell, control, or toolbar). */
+	TextareaDataAttributes["slot"] = "data-slot";
+	/** The size scale — `sm` | `md` | `lg`; the generated layer keys the per-size internals off it. */
+	TextareaDataAttributes["size"] = "data-size";
+	/** Present when the field is in an invalid state — set by Base UI/Field on the control, or by the root override. */
+	TextareaDataAttributes["invalid"] = "data-invalid";
+	/** Present when the field is disabled — set by Base UI on the control, or by the root override. */
+	TextareaDataAttributes["disabled"] = "data-disabled";
+	/** Present when the field is read-only — set by Base UI on the control; the shell holds the rest border. */
+	TextareaDataAttributes["readonly"] = "data-readonly";
+	return TextareaDataAttributes;
+}({});
+//#endregion
+export { TEXTAREA_SLOTS, TextareaDataAttributes };

package/dist/components/textarea/textarea.types.d.ts

@@ -0,0 +1,5 @@
+//#region src/components/textarea/textarea.types.d.ts
+/** Field height/padding/text scale — `md` or `lg`. */
+type TextareaSize = "md" | "lg";
+//#endregion
+export { TextareaSize };

package/dist/components/toast/index.d.ts

@@ -0,0 +1,4 @@
+import { ToastPlacement, ToastType } from "./toast.types.js";
+import { ToastManager, ToastObject, ToastOptions, ToastPromiseOptions, ToastStatusOptions, ToastUpdateOptions, useToast } from "./toast.manager.js";
+import { Toast } from "./toast.js";
+import { ToastDataAttributes } from "./toast.slots.js";

package/dist/components/toast/toast.d.ts

@@ -0,0 +1,241 @@
+import { Toast as Toast$1 } from "../../primitives/toast/toast.js";
+import { ToastPlacement, ToastType } from "./toast.types.js";
+import { ToastPartProps, ToastRootPropsArgs, ToastViewportPropsArgs, actionProps, closeProps, contentProps, descriptionProps, iconProps, rootProps, spinnerProps, titleProps, viewportProps } from "./toast.props.js";
+import { ToastManager, ToastObject, ToastOptions, ToastPromiseOptions, ToastStatusOptions, ToastUpdateOptions, useToast } from "./toast.manager.js";
+import { ReactElement } from "react";
+
+//#region src/components/toast/toast.d.ts
+/**
+ * Hosts the toast manager and the timers, and shares the resolved viewport label. Wrap the app (or the
+ * region that raises toasts) once. `timeout` (default `5000`ms; `0` disables auto-dismiss), `limit`
+ * (default `3` — older toasts collapse behind the stack), and the translated `labels` flow from here.
+ *
+ * @see {@link Toast.Provider.Props}
+ */
+declare function ToastProvider(props: Toast.Provider.Props): ReactElement;
+/**
+ * The fixed live region that holds the stack, docked to the screen corner via `placement` (default
+ * `bottom-end`) and labelled with the translated `notifications` string (an explicit `aria-label` wins).
+ * The stack collapses into a peek by default and fans out on hover/focus. `placement` is logical — the
+ * `*-start`/`*-end` corners flip under RTL, and top placements enter from above.
+ *
+ * Slot: `noctis-toast-viewport` (with `data-placement` and `data-expanded` when fanned out). Styling is
+ * precompiled in `toast.css`.
+ * @see {@link Toast.Viewport.Props}
+ */
+declare function ToastViewport({
+  placement,
+  ...props
+}: Toast.Viewport.Props): ReactElement;
+/**
+ * Groups the parts of one toast and renders them on an elevated `<Surface>`, so each toast carries the
+ * elevated scope and its base paint — controls inside (the action and close buttons) re-derive off that
+ * base and separate cleanly. Pass the `toast` object from `useToast().toasts`; its `type` drives the
+ * leading status accent. Swipe-to-dismiss is enabled toward the docked corner (down/end).
+ *
+ * Slot: `noctis-toast` (with `data-type`, `data-swiping`, `data-starting-style`/`data-ending-style`).
+ * @see {@link Toast.Root.Props}
+ */
+declare function ToastRoot({
+  toast,
+  className,
+  swipeDirection,
+  ...props
+}: Toast.Root.Props): ReactElement;
+/**
+ * The title/description/actions column, growing to fill beside the close button.
+ *
+ * Slot: `noctis-toast-content`.
+ * @see {@link Toast.Content.Props}
+ */
+declare function ToastContent(props: Toast.Content.Props): ReactElement;
+/**
+ * The toast's accessible name, linked to the root via `aria-labelledby`.
+ *
+ * Slot: `noctis-toast-title`.
+ * @see {@link Toast.Title.Props}
+ */
+declare function ToastTitle(props: Toast.Title.Props): ReactElement;
+/**
+ * Supporting copy under the title, linked to the root via `aria-describedby`.
+ *
+ * Slot: `noctis-toast-description`.
+ * @see {@link Toast.Description.Props}
+ */
+declare function ToastDescription(props: Toast.Description.Props): ReactElement;
+/**
+ * An optional leading status glyph (e.g. a check for `success`, a triangle for `warning`). Compose the
+ * glyph as its child — `<Toast.Icon><Icon icon={CircleCheck} /></Toast.Icon>` — and it inherits the
+ * toast's status colour centrally, so the icon is the single chromatic signal. Decorative by
+ * default (`aria-hidden`); the title carries the accessible message.
+ *
+ * Slot: `noctis-toast-icon`.
+ * @see {@link Toast.Icon.Props}
+ */
+declare function ToastIcon(props: Toast.Icon.Props): ReactElement;
+/**
+ * The loading spinner for the async-pending phase — render it when the toast's `type` is `loading` (or
+ * during a `promise()`'s loading phase). A neutral, CSS-drawn ring that spins, going static under
+ * reduced motion; labelled with the translated `loading` string (`role="status"`).
+ *
+ * Slot: `noctis-toast-spinner`.
+ * @see {@link Toast.Spinner.Props}
+ */
+declare function ToastSpinner(props: Toast.Spinner.Props): ReactElement;
+/**
+ * An inline action inside a toast (e.g. Undo). Carries the toast's status accent and a focus-visible
+ * ring; compose a `Button` through `render` for a full button look, or use the styled default.
+ *
+ * Slot: `noctis-toast-action`.
+ * @see {@link Toast.Action.Props}
+ */
+declare function ToastAction(props: Toast.Action.Props): ReactElement;
+/**
+ * The trailing dismiss button. Renders a bare button with a quiet default look; compose a `Button`
+ * through `render` to inherit its behaviour. Give it an `aria-label` for the accessible name.
+ *
+ * Slot: `noctis-toast-close`.
+ * @see {@link Toast.Close.Props}
+ */
+declare function ToastClose(props: Toast.Close.Props): ReactElement;
+/**
+ * Portals an anchored toast to the end of the document, out of the stacked viewport flow. Pair it with
+ * `Toast.Positioner` and the `positionerProps` option on a raised toast to pin a transient toast to a
+ * trigger (e.g. a "Copied" bubble). Stacked toasts do not need this — the viewport already portals.
+ *
+ * @see {@link Toast.Portal.Props}
+ */
+declare function ToastPortal(props: Toast.Portal.Props): ReactElement;
+/**
+ * Positions an anchored toast against its trigger, mirroring popup positioning (`side`, `align`,
+ * `sideOffset`, collision avoidance). Supply the anchor through the raised toast's `positionerProps`.
+ *
+ * Slot: `noctis-toast-positioner`.
+ * @see {@link Toast.Positioner.Props}
+ */
+declare function ToastPositioner(props: Toast.Positioner.Props): ReactElement;
+/**
+ * The pointer arrow of an anchored toast, aimed at its trigger. Stamps `data-side`/`data-align` for the
+ * CSS to rotate it to the resolved side.
+ *
+ * Slot: `noctis-toast-arrow`.
+ * @see {@link Toast.Arrow.Props}
+ */
+declare function ToastArrow(props: Toast.Arrow.Props): ReactElement;
+/**
+ * Transient notification messages — a stacked, auto-dismissing, swipe-to-dismiss queue raised
+ * imperatively. Built on Base UI's Toast for focus, live-region announcement, timers, and swipe;
+ * the Noctis layer renders each toast on an elevated `<Surface>` and exposes a typed `useToast()`
+ * manager. Wrap the tree in `Toast.Provider`, render a `Toast.Viewport` that maps `useToast().toasts`
+ * into `Toast.Root`s, and raise toasts from anywhere with `useToast().success(…)` / `.info(…)` / etc.
+ *
+ * Styling is precompiled in `toast.css`, keyed off each part's `data-slot` (plus `data-type` on the
+ * root); the root renders through `Surface` for its elevated scope and base paint. Each part's function
+ * value carries the D12 `props()` escape hatch via `Object.assign` — spread it onto a foreign element
+ * to style it as that part.
+ *
+ * The runtime compound is a plain object (kept tree-shakeable); per-part prop and state types are
+ * exposed through the matching `Toast` namespace below — e.g. `Toast.Root.Props`, `Toast.Close.State`.
+ */
+declare const Toast: {
+  Provider: typeof ToastProvider;
+  Viewport: typeof ToastViewport & {
+    props: typeof viewportProps;
+  };
+  Root: typeof ToastRoot & {
+    props: typeof rootProps;
+  };
+  Content: typeof ToastContent & {
+    props: typeof contentProps;
+  };
+  Title: typeof ToastTitle & {
+    props: typeof titleProps;
+  };
+  Description: typeof ToastDescription & {
+    props: typeof descriptionProps;
+  };
+  Icon: typeof ToastIcon & {
+    props: typeof iconProps;
+  };
+  Spinner: typeof ToastSpinner & {
+    props: typeof spinnerProps;
+  };
+  Action: typeof ToastAction & {
+    props: typeof actionProps;
+  };
+  Close: typeof ToastClose & {
+    props: typeof closeProps;
+  };
+  Portal: typeof ToastPortal;
+  Positioner: typeof ToastPositioner;
+  Arrow: typeof ToastArrow;
+};
+/**
+ * Per-part prop and state types, mirroring Base UI's `Component.Part.Props` convention. This namespace
+ * is types-only — it emits no runtime code and merges with the `Toast` object above, so `Toast.Root` is
+ * the component value while `Toast.Root.Props` is its prop type.
+ */
+declare namespace Toast {
+  /** The status type driving a toast's leading accent — re-points it to the matching status role. */
+  type Type = ToastType;
+  /** The logical placement the viewport docks at — the `*-start`/`*-end` corners flip under RTL. */
+  type Placement = ToastPlacement;
+  /** The spreadable data-attribute prop bag every `Toast.*.props()` returns (D12). */
+  type PartProps = ToastPartProps;
+  namespace Provider {
+    type Props = Toast$1.Provider.Props;
+  }
+  namespace Viewport {
+    type Props = Toast$1.Viewport.Props & {
+      /** Where the viewport docks on screen — logical, flips under RTL. Defaults to `bottom-end`. */placement?: ToastPlacement;
+    };
+    type State = Toast$1.Viewport.State;
+    /** Argument to the `Toast.Viewport.props(...)` escape-hatch helper. */
+    type PropsArgs = ToastViewportPropsArgs;
+  }
+  namespace Root {
+    type Props = Toast$1.Root.Props;
+    type State = Toast$1.Root.State;
+    /** Argument to the `Toast.Root.props(...)` escape-hatch helper. */
+    type PropsArgs = ToastRootPropsArgs;
+  }
+  namespace Content {
+    type Props = Toast$1.Content.Props;
+    type State = Toast$1.Content.State;
+  }
+  namespace Title {
+    type Props = Toast$1.Title.Props;
+    type State = Toast$1.Title.State;
+  }
+  namespace Description {
+    type Props = Toast$1.Description.Props;
+    type State = Toast$1.Description.State;
+  }
+  namespace Icon {
+    type Props = Toast$1.Icon.Props;
+  }
+  namespace Spinner {
+    type Props = Toast$1.Spinner.Props;
+  }
+  namespace Action {
+    type Props = Toast$1.Action.Props;
+    type State = Toast$1.Action.State;
+  }
+  namespace Close {
+    type Props = Toast$1.Close.Props;
+    type State = Toast$1.Close.State;
+  }
+  namespace Portal {
+    type Props = Toast$1.Portal.Props;
+  }
+  namespace Positioner {
+    type Props = Toast$1.Positioner.Props;
+    type State = Toast$1.Positioner.State;
+  }
+  namespace Arrow {
+    type Props = Toast$1.Arrow.Props;
+    type State = Toast$1.Arrow.State;
+  }
+}
+//#endregion
+export { Toast };

package/dist/components/toast/toast.js

@@ -0,0 +1,193 @@
+"use client";
+import { Surface } from "../surface/surface.js";
+import { direction_provider_exports } from "../../primitives/direction-provider.js";
+import { Toast as Toast$2 } from "../../primitives/toast/toast.js";
+import { TOAST_SLOTS } from "./toast.slots.js";
+import { actionProps, closeProps, contentProps, descriptionProps, iconProps, resolveSwipeDirection, rootProps, spinnerProps, titleProps, viewportProps } from "./toast.props.js";
+import "./toast.manager.js";
+import { jsx } from "react/jsx-runtime";
+import { Toast } from "@base-ui/react/toast";
+//#region src/components/toast/toast.tsx
+/**
+* Hosts the toast manager and the timers, and shares the resolved viewport label. Wrap the app (or the
+* region that raises toasts) once. `timeout` (default `5000`ms; `0` disables auto-dismiss), `limit`
+* (default `3` — older toasts collapse behind the stack), and the translated `labels` flow from here.
+*
+* @see {@link Toast.Provider.Props}
+*/
+function ToastProvider(props) {
+	return /* @__PURE__ */ jsx(Toast$2.Provider, { ...props });
+}
+/**
+* The fixed live region that holds the stack, docked to the screen corner via `placement` (default
+* `bottom-end`) and labelled with the translated `notifications` string (an explicit `aria-label` wins).
+* The stack collapses into a peek by default and fans out on hover/focus. `placement` is logical — the
+* `*-start`/`*-end` corners flip under RTL, and top placements enter from above.
+*
+* Slot: `noctis-toast-viewport` (with `data-placement` and `data-expanded` when fanned out). Styling is
+* precompiled in `toast.css`.
+* @see {@link Toast.Viewport.Props}
+*/
+function ToastViewport({ placement = "bottom-end", ...props }) {
+	return /* @__PURE__ */ jsx(Toast$2.Viewport, {
+		"data-placement": placement,
+		...props
+	});
+}
+/**
+* Groups the parts of one toast and renders them on an elevated `<Surface>`, so each toast carries the
+* elevated scope and its base paint — controls inside (the action and close buttons) re-derive off that
+* base and separate cleanly. Pass the `toast` object from `useToast().toasts`; its `type` drives the
+* leading status accent. Swipe-to-dismiss is enabled toward the docked corner (down/end).
+*
+* Slot: `noctis-toast` (with `data-type`, `data-swiping`, `data-starting-style`/`data-ending-style`).
+* @see {@link Toast.Root.Props}
+*/
+function ToastRoot({ toast, className, swipeDirection, ...props }) {
+	const direction = (0, direction_provider_exports.useDirection)();
+	const resolvedSwipeDirection = swipeDirection ?? resolveSwipeDirection(direction);
+	return /* @__PURE__ */ jsx(Surface, {
+		elevation: "elevated",
+		shadow: "popover",
+		"data-slot": TOAST_SLOTS.root,
+		"data-type": toast.type,
+		render: /* @__PURE__ */ jsx(Toast.Root, {
+			toast,
+			swipeDirection: resolvedSwipeDirection,
+			className,
+			...props
+		})
+	});
+}
+/**
+* The title/description/actions column, growing to fill beside the close button.
+*
+* Slot: `noctis-toast-content`.
+* @see {@link Toast.Content.Props}
+*/
+function ToastContent(props) {
+	return /* @__PURE__ */ jsx(Toast$2.Content, { ...props });
+}
+/**
+* The toast's accessible name, linked to the root via `aria-labelledby`.
+*
+* Slot: `noctis-toast-title`.
+* @see {@link Toast.Title.Props}
+*/
+function ToastTitle(props) {
+	return /* @__PURE__ */ jsx(Toast$2.Title, { ...props });
+}
+/**
+* Supporting copy under the title, linked to the root via `aria-describedby`.
+*
+* Slot: `noctis-toast-description`.
+* @see {@link Toast.Description.Props}
+*/
+function ToastDescription(props) {
+	return /* @__PURE__ */ jsx(Toast$2.Description, { ...props });
+}
+/**
+* An optional leading status glyph (e.g. a check for `success`, a triangle for `warning`). Compose the
+* glyph as its child — `<Toast.Icon><Icon icon={CircleCheck} /></Toast.Icon>` — and it inherits the
+* toast's status colour centrally, so the icon is the single chromatic signal. Decorative by
+* default (`aria-hidden`); the title carries the accessible message.
+*
+* Slot: `noctis-toast-icon`.
+* @see {@link Toast.Icon.Props}
+*/
+function ToastIcon(props) {
+	return /* @__PURE__ */ jsx(Toast$2.Icon, { ...props });
+}
+/**
+* The loading spinner for the async-pending phase — render it when the toast's `type` is `loading` (or
+* during a `promise()`'s loading phase). A neutral, CSS-drawn ring that spins, going static under
+* reduced motion; labelled with the translated `loading` string (`role="status"`).
+*
+* Slot: `noctis-toast-spinner`.
+* @see {@link Toast.Spinner.Props}
+*/
+function ToastSpinner(props) {
+	return /* @__PURE__ */ jsx(Toast$2.Spinner, { ...props });
+}
+/**
+* An inline action inside a toast (e.g. Undo). Carries the toast's status accent and a focus-visible
+* ring; compose a `Button` through `render` for a full button look, or use the styled default.
+*
+* Slot: `noctis-toast-action`.
+* @see {@link Toast.Action.Props}
+*/
+function ToastAction(props) {
+	return /* @__PURE__ */ jsx(Toast$2.Action, { ...props });
+}
+/**
+* The trailing dismiss button. Renders a bare button with a quiet default look; compose a `Button`
+* through `render` to inherit its behaviour. Give it an `aria-label` for the accessible name.
+*
+* Slot: `noctis-toast-close`.
+* @see {@link Toast.Close.Props}
+*/
+function ToastClose(props) {
+	return /* @__PURE__ */ jsx(Toast$2.Close, { ...props });
+}
+/**
+* Portals an anchored toast to the end of the document, out of the stacked viewport flow. Pair it with
+* `Toast.Positioner` and the `positionerProps` option on a raised toast to pin a transient toast to a
+* trigger (e.g. a "Copied" bubble). Stacked toasts do not need this — the viewport already portals.
+*
+* @see {@link Toast.Portal.Props}
+*/
+function ToastPortal(props) {
+	return /* @__PURE__ */ jsx(Toast$2.Portal, { ...props });
+}
+/**
+* Positions an anchored toast against its trigger, mirroring popup positioning (`side`, `align`,
+* `sideOffset`, collision avoidance). Supply the anchor through the raised toast's `positionerProps`.
+*
+* Slot: `noctis-toast-positioner`.
+* @see {@link Toast.Positioner.Props}
+*/
+function ToastPositioner(props) {
+	return /* @__PURE__ */ jsx(Toast$2.Positioner, { ...props });
+}
+/**
+* The pointer arrow of an anchored toast, aimed at its trigger. Stamps `data-side`/`data-align` for the
+* CSS to rotate it to the resolved side.
+*
+* Slot: `noctis-toast-arrow`.
+* @see {@link Toast.Arrow.Props}
+*/
+function ToastArrow(props) {
+	return /* @__PURE__ */ jsx(Toast$2.Arrow, { ...props });
+}
+/**
+* Transient notification messages — a stacked, auto-dismissing, swipe-to-dismiss queue raised
+* imperatively. Built on Base UI's Toast for focus, live-region announcement, timers, and swipe;
+* the Noctis layer renders each toast on an elevated `<Surface>` and exposes a typed `useToast()`
+* manager. Wrap the tree in `Toast.Provider`, render a `Toast.Viewport` that maps `useToast().toasts`
+* into `Toast.Root`s, and raise toasts from anywhere with `useToast().success(…)` / `.info(…)` / etc.
+*
+* Styling is precompiled in `toast.css`, keyed off each part's `data-slot` (plus `data-type` on the
+* root); the root renders through `Surface` for its elevated scope and base paint. Each part's function
+* value carries the D12 `props()` escape hatch via `Object.assign` — spread it onto a foreign element
+* to style it as that part.
+*
+* The runtime compound is a plain object (kept tree-shakeable); per-part prop and state types are
+* exposed through the matching `Toast` namespace below — e.g. `Toast.Root.Props`, `Toast.Close.State`.
+*/
+const Toast$1 = {
+	Provider: ToastProvider,
+	Viewport: Object.assign(ToastViewport, { props: viewportProps }),
+	Root: Object.assign(ToastRoot, { props: rootProps }),
+	Content: Object.assign(ToastContent, { props: contentProps }),
+	Title: Object.assign(ToastTitle, { props: titleProps }),
+	Description: Object.assign(ToastDescription, { props: descriptionProps }),
+	Icon: Object.assign(ToastIcon, { props: iconProps }),
+	Spinner: Object.assign(ToastSpinner, { props: spinnerProps }),
+	Action: Object.assign(ToastAction, { props: actionProps }),
+	Close: Object.assign(ToastClose, { props: closeProps }),
+	Portal: ToastPortal,
+	Positioner: ToastPositioner,
+	Arrow: ToastArrow
+};
+//#endregion
+export { Toast$1 as Toast };

package/dist/components/toast/toast.manager.d.ts

@@ -0,0 +1,76 @@
+import { Toast as Toast$1 } from "../../primitives/toast/toast.js";
+import { ToastManagerPromiseOptions } from "@base-ui/react/toast";
+
+//#region src/components/toast/toast.manager.d.ts
+/** Base UI's live manager — the source of truth for the toast list and its imperative methods. */
+type BaseManager = ReturnType<typeof Toast$1.useToastManager>;
+/** The options Base UI's `add`/`update` accept (title, description, timeout, priority, action, …). */
+type AddOptions = Parameters<BaseManager["add"]>[0];
+/** The mounted-toast object Base UI tracks — read it off `toasts` to render the list. */
+type ToastObject = BaseManager["toasts"][number];
+/** Options for `show` and the typed convenience helpers — Base UI's add options minus the `type` it sets. */
+type ToastOptions = Omit<AddOptions, "type">;
+/** Options for `update` — Base UI's update options, which keep `type` so a toast can change status in place. */
+type ToastUpdateOptions = Parameters<BaseManager["update"]>[1];
+/** Options for the typed status helpers — the title is passed positionally, so it is optional here. */
+type ToastStatusOptions = Omit<ToastOptions, "title">;
+/** Custom per-toast data Base UI carries (defaults to the empty object — toasts here carry no extra data). */
+type ToastData = ToastObject extends {
+  data?: infer D;
+} ? NonNullable<D> : object;
+/**
+ * The promise descriptor `useToast().promise` resolves a toast against — the loading message and the
+ * success/error mappers Base UI swaps in as the promise settles. Generic over the resolved value so the
+ * `success` mapper is typed against it.
+ */
+type ToastPromiseOptions<Value> = ToastManagerPromiseOptions<Value, ToastData>;
+/**
+ * The Noctis toast manager — a typed, ergonomic façade over Base UI's `useToastManager`. The live list
+ * and timers live in Base UI's `Toast.Provider`; this hook reads that manager and exposes the status
+ * helpers the design system documents, so a button anywhere under the provider can raise a toast
+ * without prop threading. Like Sheet's `useSheetStack`, the state is owned upstream and the manager is
+ * reached through context (here, Base UI's provider) — call `useToast()` in any descendant.
+ */
+interface ToastManager {
+  /** Every mounted toast, front to back — render these inside the viewport. */
+  toasts: readonly ToastObject[];
+  /** The number of mounted toasts (≈ `useSheetStack().depth`) — read it to badge or gate the stack. */
+  count: number;
+  /**
+   * Raise a toast with explicit options (`title`, `description`, `timeout`, `priority`, …). A caller
+   * `timeout` is floored to 5000ms (slow readers and screen-zoom users); pass `0` to keep it up until
+   * acted on. Returns its id.
+   */
+  show: (options: ToastOptions) => string;
+  /** Raise an `info`-typed toast (polite live region) — the title positional, the rest optional. Returns its id. */
+  info: (title: string, options?: ToastStatusOptions) => string;
+  /** Raise a `success`-typed toast (polite live region). Returns its id. */
+  success: (title: string, options?: ToastStatusOptions) => string;
+  /** Raise a `warning`-typed toast — announced assertively (urgent). Returns its id. */
+  warning: (title: string, options?: ToastStatusOptions) => string;
+  /** Raise a `danger`-typed toast — announced assertively (urgent). Returns its id. */
+  danger: (title: string, options?: ToastStatusOptions) => string;
+  /**
+   * Raise a persistent `loading`-typed toast (neutral, no auto-dismiss) — render `Toast.Spinner` for
+   * it, then `update(id, …)` or `close(id)` when the work settles. Returns its id.
+   */
+  loading: (title: string, options?: ToastStatusOptions) => string;
+  /**
+   * Dismiss a toast by id; **omit the id to clear every toast** (Base UI closes the whole stack). It
+   * animates out, then unmounts. Prefer {@link ToastManager.clear} for the explicit all-clear.
+   */
+  dismiss: (id?: string) => void;
+  /** Clear the whole stack at once (≈ `useSheetStack().reset()`); equivalent to `dismiss()` with no id. */
+  clear: () => void;
+  /** Update a live toast in place by id (its `type`, copy, timeout, …), refreshing its auto-dismiss timer. */
+  update: (id: string, options: ToastUpdateOptions) => void;
+  /**
+   * Drive a single toast through a promise's lifecycle: it shows the `loading` message (with the
+   * spinner), then swaps that same toast to the `success` or `error` result as the promise settles —
+   * one toast, never a stack. Resolves with the promise's value.
+   */
+  promise: <Value>(promise: Promise<Value>, options: ToastPromiseOptions<Value>) => Promise<Value>;
+}
+declare function useToast(): ToastManager;
+//#endregion
+export { ToastManager, ToastObject, ToastOptions, ToastPromiseOptions, ToastStatusOptions, ToastUpdateOptions, useToast };

package/dist/components/toast/toast.manager.js

@@ -0,0 +1,71 @@
+"use client";
+import { Toast } from "../../primitives/toast/toast.js";
+import { useMemo } from "react";
+//#region src/components/toast/toast.manager.ts
+/**
+* Read the toast manager. Use it inside any component under `Toast.Provider` to raise, update, or
+* dismiss toasts — the typed status helpers (`info` / `success` / `warning` / `danger`) set the
+* matching `type`, which drives the leading status icon's colour; `show` raises a neutral toast and takes the
+* full option set.
+*
+*     const toast = useToast();
+*     toast.success("Saved", { description: "Your changes are live." });
+*/
+/** Spectrum's floor: a toast never auto-dismisses faster than this, so slow readers can keep up. */
+const TIMEOUT_FLOOR_MS = 5e3;
+/** Status types announced assertively (APG `alert`): the urgent outcomes interrupt; the rest stay polite. */
+const ASSERTIVE = {
+	warning: true,
+	danger: true
+};
+/**
+* The live-region politeness for a status (APG): `warning`/`danger` are urgent → assertive (`high`);
+* `info`/`success`/`loading` advise → polite (Base UI's default, so `undefined`).
+*/
+function statusPriority(type) {
+	return ASSERTIVE[type] ? "high" : void 0;
+}
+/** Clamp a caller `timeout` to the floor; `0` (persistent) and an unset timeout pass through untouched. */
+function floorTimeout(options) {
+	const { timeout } = options;
+	if (timeout === void 0 || timeout === 0 || timeout >= 5e3) return options;
+	return {
+		...options,
+		timeout: TIMEOUT_FLOOR_MS
+	};
+}
+function useToast() {
+	const manager = Toast.useToastManager();
+	return useMemo(() => {
+		const status = (type) => (title, options = {}) => {
+			const priority = statusPriority(type) ?? options.priority;
+			return manager.add(floorTimeout({
+				...options,
+				title,
+				type,
+				priority
+			}));
+		};
+		return {
+			toasts: manager.toasts,
+			count: manager.toasts.length,
+			show: (options) => manager.add(floorTimeout(options)),
+			info: status("info"),
+			success: status("success"),
+			warning: status("warning"),
+			danger: status("danger"),
+			loading: (title, options = {}) => manager.add({
+				...options,
+				title,
+				type: "loading",
+				timeout: 0
+			}),
+			dismiss: (id) => manager.close(id),
+			clear: () => manager.close(),
+			update: (id, options) => manager.update(id, floorTimeout(options)),
+			promise: (promise, options) => manager.promise(promise, options)
+		};
+	}, [manager]);
+}
+//#endregion
+export { useToast };