@arun-dev/headless 4.12.0 → 4.13.0

package/dist/toast/index.cjs

@@ -0,0 +1,376 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/toast/index.ts
+var toast_exports = {};
+__export(toast_exports, {
+  Toast: () => index_parts_exports,
+  useToastManager: () => useToastManager
+});
+module.exports = __toCommonJS(toast_exports);
+
+// src/toast/index.parts.ts
+var index_parts_exports = {};
+__export(index_parts_exports, {
+  Action: () => ToastAction,
+  Close: () => ToastClose,
+  Description: () => ToastDescription,
+  Provider: () => ToastProvider,
+  Root: () => ToastRoot,
+  Title: () => ToastTitle,
+  Viewport: () => ToastViewport
+});
+
+// src/toast/ToastProvider.tsx
+var import_react2 = require("react");
+
+// src/toast/ToastContext.ts
+var import_react = require("react");
+var ToastContext = (0, import_react.createContext)(null);
+function useToastContext(part) {
+  const context = (0, import_react.useContext)(ToastContext);
+  if (context === null) {
+    throw new Error(`${part} must be used inside <Toast.Provider>.`);
+  }
+  return context;
+}
+function useToastManager() {
+  const { toasts, add, update, close } = useToastContext("useToastManager()");
+  return { toasts, add, update, close };
+}
+var ToastRootContext = (0, import_react.createContext)(null);
+function useToastRootContext(part) {
+  const toast = (0, import_react.useContext)(ToastRootContext);
+  if (toast === null) {
+    throw new Error(`<Toast.${part}> must be rendered inside <Toast.Root>.`);
+  }
+  return toast;
+}
+
+// src/toast/ToastProvider.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function ToastProvider({ limit = 3, timeout = 5e3, children }) {
+  const [all, setAll] = (0, import_react2.useState)([]);
+  const prefix = (0, import_react2.useId)();
+  const counter = (0, import_react2.useRef)(0);
+  const closedRef = (0, import_react2.useRef)(/* @__PURE__ */ new Set());
+  const add = (0, import_react2.useCallback)(
+    (options) => {
+      const id = options.id ?? `${prefix}-${++counter.current}`;
+      const toast = {
+        ...options,
+        id,
+        timeout: options.timeout ?? timeout,
+        priority: options.priority ?? "low"
+      };
+      closedRef.current.delete(id);
+      setAll((current) => [...current.filter((t) => t.id !== id), toast]);
+      return id;
+    },
+    [prefix, timeout]
+  );
+  const update = (0, import_react2.useCallback)((id, patch) => {
+    setAll(
+      (current) => current.map((t) => t.id === id ? { ...t, ...patch, id } : t)
+    );
+  }, []);
+  const close = (0, import_react2.useCallback)((id) => {
+    setAll((current) => {
+      const toast = current.find((t) => t.id === id);
+      if (toast && !closedRef.current.has(id)) {
+        closedRef.current.add(id);
+        queueMicrotask(() => toast.onClose?.());
+      }
+      return current.filter((t) => t.id !== id);
+    });
+  }, []);
+  const [pointerInside, setPointerInside] = (0, import_react2.useState)(false);
+  const [focusInside, setFocusInside] = (0, import_react2.useState)(false);
+  const [pageHidden, setPageHidden] = (0, import_react2.useState)(false);
+  (0, import_react2.useEffect)(() => {
+    const onVisibility = () => setPageHidden(document.visibilityState === "hidden");
+    onVisibility();
+    document.addEventListener("visibilitychange", onVisibility);
+    return () => document.removeEventListener("visibilitychange", onVisibility);
+  }, []);
+  const viewportRef = (0, import_react2.useRef)(null);
+  const toasts = (0, import_react2.useMemo)(() => all.slice(-limit), [all, limit]);
+  const context = (0, import_react2.useMemo)(
+    () => ({
+      toasts,
+      add,
+      update,
+      close,
+      paused: pointerInside || focusInside || pageHidden,
+      setPointerInside,
+      setFocusInside,
+      viewportRef
+    }),
+    [toasts, add, update, close, pointerInside, focusInside, pageHidden]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ToastContext.Provider, { value: context, children });
+}
+
+// src/toast/ToastViewport.tsx
+var import_react4 = require("react");
+
+// src/core/useRender.ts
+var import_react3 = require("react");
+
+// src/core/mergeProps.ts
+function isEventHandler(key) {
+  return key.length > 2 && key.startsWith("on") && key[2] === key[2]?.toUpperCase();
+}
+function mergeRefs(...refs) {
+  return (node) => {
+    const cleanups = refs.map((ref) => {
+      if (typeof ref === "function") {
+        const result = ref(node);
+        return typeof result === "function" ? result : () => ref(null);
+      }
+      if (ref && typeof ref === "object") {
+        ref.current = node;
+        return () => {
+          ref.current = null;
+        };
+      }
+      return void 0;
+    });
+    return () => {
+      cleanups.forEach((cleanup) => {
+        if (typeof cleanup === "function") cleanup();
+      });
+    };
+  };
+}
+function isSyntheticEvent(event) {
+  return typeof event === "object" && event !== null && "nativeEvent" in event;
+}
+function makeEventPreventable(event) {
+  if (Object.prototype.hasOwnProperty.call(event, "preventComponentHandler")) return;
+  const target = event;
+  target.preventComponentHandler = () => {
+    target.componentHandlerPrevented = true;
+  };
+}
+function isComponentHandlerPrevented(event) {
+  return typeof event === "object" && event !== null && event.componentHandlerPrevented === true;
+}
+function chainHandlers(earlier, value) {
+  return (...args) => {
+    const event = args[0];
+    if (isSyntheticEvent(event)) makeEventPreventable(event);
+    value(...args);
+    if (isComponentHandlerPrevented(event)) return;
+    earlier(...args);
+  };
+}
+function mergeProps(...objects) {
+  const merged = {};
+  for (const props of objects) {
+    if (!props) continue;
+    for (const key of Object.keys(props)) {
+      const value = props[key];
+      if (value === void 0) continue;
+      if (isEventHandler(key) && typeof value === "function") {
+        const earlier = merged[key];
+        merged[key] = typeof earlier === "function" ? chainHandlers(earlier, value) : value;
+      } else if (key === "className") {
+        merged.className = merged.className ? `${String(merged.className)} ${String(value)}` : value;
+      } else if (key === "style") {
+        merged.style = { ...merged.style, ...value };
+      } else if (key === "ref") {
+        merged.ref = merged.ref ? mergeRefs(merged.ref, value) : value;
+      } else {
+        merged[key] = value;
+      }
+    }
+  }
+  return merged;
+}
+
+// src/core/useRender.ts
+function useRender({
+  render,
+  defaultTagName,
+  props,
+  consumerProps
+}) {
+  const merged = mergeProps(props, consumerProps);
+  if ((0, import_react3.isValidElement)(render)) {
+    return (0, import_react3.cloneElement)(render, mergeProps(merged, render.props));
+  }
+  return (0, import_react3.createElement)(defaultTagName, merged);
+}
+
+// src/toast/ToastViewport.tsx
+function ToastViewport({ className, children, render, ...rest }) {
+  const { toasts, viewportRef, setPointerInside, setFocusInside } = useToastContext("<Toast.Viewport>");
+  const elementRef = (0, import_react4.useRef)(null);
+  const newest = toasts.at(-1)?.id;
+  (0, import_react4.useLayoutEffect)(() => {
+    const element = elementRef.current;
+    viewportRef.current = element;
+    if (!element || typeof element.showPopover !== "function") return;
+    if (element.matches(":popover-open")) element.hidePopover();
+    element.showPopover();
+  }, [newest, viewportRef]);
+  return useRender({
+    render,
+    defaultTagName: "section",
+    props: {
+      popover: "manual",
+      "aria-label": "Notifications",
+      "aria-live": "polite",
+      tabIndex: -1,
+      className,
+      ref: elementRef,
+      children: typeof children === "function" ? children(toasts) : children,
+      onPointerEnter() {
+        setPointerInside(true);
+      },
+      onPointerLeave() {
+        setPointerInside(false);
+      },
+      onFocus() {
+        setFocusInside(true);
+      },
+      onBlur(event) {
+        const next = event.relatedTarget;
+        if (!next || !event.currentTarget.contains(next)) setFocusInside(false);
+      }
+    },
+    consumerProps: rest
+  });
+}
+
+// src/toast/ToastRoot.tsx
+var import_react5 = require("react");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function ToastRoot({ toast, className, children, render, ...rest }) {
+  const { close, paused, viewportRef } = useToastContext("<Toast.Root>");
+  const elementRef = (0, import_react5.useRef)(null);
+  const { id, timeout } = toast;
+  const remaining = (0, import_react5.useRef)(timeout);
+  const lastTimeout = (0, import_react5.useRef)(timeout);
+  if (lastTimeout.current !== timeout) {
+    lastTimeout.current = timeout;
+    remaining.current = timeout;
+  }
+  (0, import_react5.useEffect)(() => {
+    if (paused || timeout <= 0) return;
+    const started = Date.now();
+    const timer = setTimeout(() => close(id), remaining.current);
+    return () => {
+      clearTimeout(timer);
+      remaining.current = Math.max(0, remaining.current - (Date.now() - started));
+    };
+  }, [paused, timeout, id, close]);
+  const focusInside = (0, import_react5.useRef)(false);
+  (0, import_react5.useEffect)(
+    () => () => {
+      if (focusInside.current) viewportRef.current?.focus();
+    },
+    [viewportRef]
+  );
+  const element = useRender({
+    render,
+    defaultTagName: "div",
+    props: {
+      role: toast.priority === "high" ? "alert" : void 0,
+      "aria-atomic": true,
+      "data-type": toast.type,
+      className,
+      children,
+      ref: elementRef,
+      onFocus() {
+        focusInside.current = true;
+      },
+      onBlur(event) {
+        const next = event.relatedTarget;
+        if (!next || !event.currentTarget.contains(next)) focusInside.current = false;
+      },
+      onKeyDown(event) {
+        if (event.key === "Escape") {
+          event.preventDefault();
+          close(id);
+        }
+      }
+    },
+    consumerProps: rest
+  });
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(ToastRootContext.Provider, { value: toast, children: element });
+}
+
+// src/toast/ToastTitle.tsx
+function ToastTitle({ className, children, render, ...rest }) {
+  const toast = useToastRootContext("Title");
+  return useRender({
+    render,
+    defaultTagName: "p",
+    props: { className, children: children ?? toast.title },
+    consumerProps: rest
+  });
+}
+
+// src/toast/ToastDescription.tsx
+function ToastDescription({ className, children, render, ...rest }) {
+  const toast = useToastRootContext("Description");
+  return useRender({
+    render,
+    defaultTagName: "div",
+    props: { className, children: children ?? toast.description },
+    consumerProps: rest
+  });
+}
+
+// src/toast/ToastAction.tsx
+function ToastAction({ className, children, render, ...rest }) {
+  useToastRootContext("Action");
+  return useRender({
+    render,
+    defaultTagName: "button",
+    props: { type: "button", className, children },
+    consumerProps: rest
+  });
+}
+
+// src/toast/ToastClose.tsx
+function ToastClose({ className, children, render, ...rest }) {
+  const { close } = useToastContext("<Toast.Close>");
+  const { id } = useToastRootContext("Close");
+  return useRender({
+    render,
+    defaultTagName: "button",
+    props: {
+      type: "button",
+      className,
+      children,
+      onClick() {
+        close(id);
+      }
+    },
+    consumerProps: rest
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Toast,
+  useToastManager
+});

package/dist/toast/index.d.cts

@@ -0,0 +1,141 @@
+import * as react from 'react';
+import { ReactNode, ReactElement, Ref, ComponentPropsWithRef } from 'react';
+
+type ToastProviderProps = {
+    /** How many show at once. The rest wait, their timers stopped, and show as others close. */
+    limit?: number;
+    /** Milliseconds a toast stays, unless it sets its own. `0` keeps toasts until closed. */
+    timeout?: number;
+    children?: ReactNode;
+};
+/**
+ * Holds the toasts (decision 16). Put it near the root, with one `Toast.Viewport` inside, and
+ * call `useToastManager()` anywhere below to show one.
+ */
+declare function ToastProvider({ limit, timeout, children }: ToastProviderProps): react.JSX.Element;
+
+/** `'high'` is announced at once (`role="alert"`); `'low'`, the default, when the reader is idle. */
+type ToastPriority = 'low' | 'high';
+/** What `add` takes. Everything is optional but something to show. */
+type ToastOptions<Data = unknown> = {
+    /** Reuse an id to replace a toast of the same id. Generated otherwise. */
+    id?: string;
+    title?: ReactNode;
+    description?: ReactNode;
+    /** Your kind of toast — `"success"`, `"error"` — emitted as `data-type` for styling. */
+    type?: string;
+    /** Milliseconds before it closes on its own. `0` keeps it until closed. Defaults to the Provider's. */
+    timeout?: number;
+    priority?: ToastPriority;
+    /** A button on the toast, for the ui's default rendering. The headless `Action` part is yours to place. */
+    action?: {
+        label: ReactNode;
+        onClick: () => void;
+    };
+    /** Called once it closes, however it closed. */
+    onClose?: () => void;
+    /** Anything else your rendering needs. */
+    data?: Data;
+};
+type ToastObject<Data = unknown> = ToastOptions<Data> & {
+    id: string;
+    timeout: number;
+    priority: ToastPriority;
+};
+type ToastManager = {
+    /** The toasts to render: the newest `limit`, oldest first. */
+    toasts: readonly ToastObject[];
+    /** Shows a toast and returns its id. */
+    add: <Data = unknown>(options: ToastOptions<Data>) => string;
+    /** Changes a shown toast — its text after a save finishes, say. A new `timeout` restarts it. */
+    update: <Data = unknown>(id: string, patch: Partial<ToastOptions<Data>>) => void;
+    /** Closes a toast. */
+    close: (id: string) => void;
+};
+/** Shows and closes toasts from anywhere under the Provider. */
+declare function useToastManager(): ToastManager;
+
+type ToastViewportOwnProps = {
+    /** The toasts, rendered: usually `toasts.map((toast) => <Toast.Root key={toast.id} toast={toast}>…)`. */
+    children?: ReactNode | ((toasts: readonly ToastObject[]) => ReactNode);
+    /** Element to render instead of the default `<section>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ToastViewportProps = ToastViewportOwnProps & Omit<ComponentPropsWithRef<'section'>, keyof ToastViewportOwnProps>;
+/**
+ * Where toasts show: a `<section aria-label="Notifications">`, `aria-live="polite"`, and a
+ * `popover="manual"` kept open in the top layer — above a modal Dialog — with no portal
+ * (decisions 12 and 16). It stays open while empty, so the live region already exists when the
+ * first toast arrives, and moves back to the top of the top layer as each arrives.
+ *
+ * Timers pause while the pointer is over it or focus is in it.
+ */
+declare function ToastViewport({ className, children, render, ...rest }: ToastViewportProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ToastRootOwnProps = {
+    /** The toast this renders — one of `useToastManager().toasts`. */
+    toast: ToastObject;
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ToastRootProps = ToastRootOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ToastRootOwnProps>;
+/**
+ * One toast. Closes itself after its `timeout`, counting only while not paused, and on Esc while
+ * focus is in it. A `priority: 'high'` toast is `role="alert"`; the rest are announced politely
+ * by the Viewport. `data-type` carries its `type`, for styling.
+ */
+declare function ToastRoot({ toast, className, children, render, ...rest }: ToastRootProps): react.JSX.Element;
+
+type ToastTitleOwnProps = {
+    /** Element to render instead of the default `<p>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ToastTitleProps = ToastTitleOwnProps & Omit<ComponentPropsWithRef<'p'>, keyof ToastTitleOwnProps>;
+/** The toast's title. Its children default to the toast's `title`. */
+declare function ToastTitle({ className, children, render, ...rest }: ToastTitleProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ToastDescriptionOwnProps = {
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ToastDescriptionProps = ToastDescriptionOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ToastDescriptionOwnProps>;
+/** The toast's description. Its children default to the toast's `description`. */
+declare function ToastDescription({ className, children, render, ...rest }: ToastDescriptionProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ToastActionOwnProps = {
+    /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ToastActionProps = ToastActionOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ToastActionOwnProps>;
+/**
+ * A button that does something about the toast — "Undo". It does not close the toast; call
+ * `close` in your handler if it should. Keep it optional: a toast can vanish before anyone
+ * reaches it, so the same action must be possible elsewhere.
+ */
+declare function ToastAction({ className, children, render, ...rest }: ToastActionProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ToastCloseOwnProps = {
+    /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ToastCloseProps = ToastCloseOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ToastCloseOwnProps>;
+/** Closes its toast. Give it an `aria-label` — "Dismiss" — if it shows only an icon. */
+declare function ToastClose({ className, children, render, ...rest }: ToastCloseProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+declare namespace index_parts {
+  export { ToastAction as Action, ToastClose as Close, ToastDescription as Description, ToastProvider as Provider, ToastRoot as Root, ToastTitle as Title, ToastViewport as Viewport };
+}
+
+export { index_parts as Toast, type ToastActionProps, type ToastCloseProps, type ToastDescriptionProps, type ToastManager, type ToastObject, type ToastOptions, type ToastPriority, type ToastProviderProps, type ToastRootProps, type ToastTitleProps, type ToastViewportProps, useToastManager };

package/dist/toast/index.d.ts

@@ -0,0 +1,141 @@
+import * as react from 'react';
+import { ReactNode, ReactElement, Ref, ComponentPropsWithRef } from 'react';
+
+type ToastProviderProps = {
+    /** How many show at once. The rest wait, their timers stopped, and show as others close. */
+    limit?: number;
+    /** Milliseconds a toast stays, unless it sets its own. `0` keeps toasts until closed. */
+    timeout?: number;
+    children?: ReactNode;
+};
+/**
+ * Holds the toasts (decision 16). Put it near the root, with one `Toast.Viewport` inside, and
+ * call `useToastManager()` anywhere below to show one.
+ */
+declare function ToastProvider({ limit, timeout, children }: ToastProviderProps): react.JSX.Element;
+
+/** `'high'` is announced at once (`role="alert"`); `'low'`, the default, when the reader is idle. */
+type ToastPriority = 'low' | 'high';
+/** What `add` takes. Everything is optional but something to show. */
+type ToastOptions<Data = unknown> = {
+    /** Reuse an id to replace a toast of the same id. Generated otherwise. */
+    id?: string;
+    title?: ReactNode;
+    description?: ReactNode;
+    /** Your kind of toast — `"success"`, `"error"` — emitted as `data-type` for styling. */
+    type?: string;
+    /** Milliseconds before it closes on its own. `0` keeps it until closed. Defaults to the Provider's. */
+    timeout?: number;
+    priority?: ToastPriority;
+    /** A button on the toast, for the ui's default rendering. The headless `Action` part is yours to place. */
+    action?: {
+        label: ReactNode;
+        onClick: () => void;
+    };
+    /** Called once it closes, however it closed. */
+    onClose?: () => void;
+    /** Anything else your rendering needs. */
+    data?: Data;
+};
+type ToastObject<Data = unknown> = ToastOptions<Data> & {
+    id: string;
+    timeout: number;
+    priority: ToastPriority;
+};
+type ToastManager = {
+    /** The toasts to render: the newest `limit`, oldest first. */
+    toasts: readonly ToastObject[];
+    /** Shows a toast and returns its id. */
+    add: <Data = unknown>(options: ToastOptions<Data>) => string;
+    /** Changes a shown toast — its text after a save finishes, say. A new `timeout` restarts it. */
+    update: <Data = unknown>(id: string, patch: Partial<ToastOptions<Data>>) => void;
+    /** Closes a toast. */
+    close: (id: string) => void;
+};
+/** Shows and closes toasts from anywhere under the Provider. */
+declare function useToastManager(): ToastManager;
+
+type ToastViewportOwnProps = {
+    /** The toasts, rendered: usually `toasts.map((toast) => <Toast.Root key={toast.id} toast={toast}>…)`. */
+    children?: ReactNode | ((toasts: readonly ToastObject[]) => ReactNode);
+    /** Element to render instead of the default `<section>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ToastViewportProps = ToastViewportOwnProps & Omit<ComponentPropsWithRef<'section'>, keyof ToastViewportOwnProps>;
+/**
+ * Where toasts show: a `<section aria-label="Notifications">`, `aria-live="polite"`, and a
+ * `popover="manual"` kept open in the top layer — above a modal Dialog — with no portal
+ * (decisions 12 and 16). It stays open while empty, so the live region already exists when the
+ * first toast arrives, and moves back to the top of the top layer as each arrives.
+ *
+ * Timers pause while the pointer is over it or focus is in it.
+ */
+declare function ToastViewport({ className, children, render, ...rest }: ToastViewportProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ToastRootOwnProps = {
+    /** The toast this renders — one of `useToastManager().toasts`. */
+    toast: ToastObject;
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ToastRootProps = ToastRootOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ToastRootOwnProps>;
+/**
+ * One toast. Closes itself after its `timeout`, counting only while not paused, and on Esc while
+ * focus is in it. A `priority: 'high'` toast is `role="alert"`; the rest are announced politely
+ * by the Viewport. `data-type` carries its `type`, for styling.
+ */
+declare function ToastRoot({ toast, className, children, render, ...rest }: ToastRootProps): react.JSX.Element;
+
+type ToastTitleOwnProps = {
+    /** Element to render instead of the default `<p>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ToastTitleProps = ToastTitleOwnProps & Omit<ComponentPropsWithRef<'p'>, keyof ToastTitleOwnProps>;
+/** The toast's title. Its children default to the toast's `title`. */
+declare function ToastTitle({ className, children, render, ...rest }: ToastTitleProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ToastDescriptionOwnProps = {
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ToastDescriptionProps = ToastDescriptionOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ToastDescriptionOwnProps>;
+/** The toast's description. Its children default to the toast's `description`. */
+declare function ToastDescription({ className, children, render, ...rest }: ToastDescriptionProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ToastActionOwnProps = {
+    /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ToastActionProps = ToastActionOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ToastActionOwnProps>;
+/**
+ * A button that does something about the toast — "Undo". It does not close the toast; call
+ * `close` in your handler if it should. Keep it optional: a toast can vanish before anyone
+ * reaches it, so the same action must be possible elsewhere.
+ */
+declare function ToastAction({ className, children, render, ...rest }: ToastActionProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ToastCloseOwnProps = {
+    /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ToastCloseProps = ToastCloseOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ToastCloseOwnProps>;
+/** Closes its toast. Give it an `aria-label` — "Dismiss" — if it shows only an icon. */
+declare function ToastClose({ className, children, render, ...rest }: ToastCloseProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+declare namespace index_parts {
+  export { ToastAction as Action, ToastClose as Close, ToastDescription as Description, ToastProvider as Provider, ToastRoot as Root, ToastTitle as Title, ToastViewport as Viewport };
+}
+
+export { index_parts as Toast, type ToastActionProps, type ToastCloseProps, type ToastDescriptionProps, type ToastManager, type ToastObject, type ToastOptions, type ToastPriority, type ToastProviderProps, type ToastRootProps, type ToastTitleProps, type ToastViewportProps, useToastManager };

package/dist/toast/index.js

@@ -0,0 +1,262 @@
+import {
+  __export,
+  useRender
+} from "../chunk-OQTWWZ4B.js";
+
+// src/toast/index.parts.ts
+var index_parts_exports = {};
+__export(index_parts_exports, {
+  Action: () => ToastAction,
+  Close: () => ToastClose,
+  Description: () => ToastDescription,
+  Provider: () => ToastProvider,
+  Root: () => ToastRoot,
+  Title: () => ToastTitle,
+  Viewport: () => ToastViewport
+});
+
+// src/toast/ToastProvider.tsx
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+
+// src/toast/ToastContext.ts
+import { createContext, useContext } from "react";
+var ToastContext = createContext(null);
+function useToastContext(part) {
+  const context = useContext(ToastContext);
+  if (context === null) {
+    throw new Error(`${part} must be used inside <Toast.Provider>.`);
+  }
+  return context;
+}
+function useToastManager() {
+  const { toasts, add, update, close } = useToastContext("useToastManager()");
+  return { toasts, add, update, close };
+}
+var ToastRootContext = createContext(null);
+function useToastRootContext(part) {
+  const toast = useContext(ToastRootContext);
+  if (toast === null) {
+    throw new Error(`<Toast.${part}> must be rendered inside <Toast.Root>.`);
+  }
+  return toast;
+}
+
+// src/toast/ToastProvider.tsx
+import { jsx } from "react/jsx-runtime";
+function ToastProvider({ limit = 3, timeout = 5e3, children }) {
+  const [all, setAll] = useState([]);
+  const prefix = useId();
+  const counter = useRef(0);
+  const closedRef = useRef(/* @__PURE__ */ new Set());
+  const add = useCallback(
+    (options) => {
+      const id = options.id ?? `${prefix}-${++counter.current}`;
+      const toast = {
+        ...options,
+        id,
+        timeout: options.timeout ?? timeout,
+        priority: options.priority ?? "low"
+      };
+      closedRef.current.delete(id);
+      setAll((current) => [...current.filter((t) => t.id !== id), toast]);
+      return id;
+    },
+    [prefix, timeout]
+  );
+  const update = useCallback((id, patch) => {
+    setAll(
+      (current) => current.map((t) => t.id === id ? { ...t, ...patch, id } : t)
+    );
+  }, []);
+  const close = useCallback((id) => {
+    setAll((current) => {
+      const toast = current.find((t) => t.id === id);
+      if (toast && !closedRef.current.has(id)) {
+        closedRef.current.add(id);
+        queueMicrotask(() => toast.onClose?.());
+      }
+      return current.filter((t) => t.id !== id);
+    });
+  }, []);
+  const [pointerInside, setPointerInside] = useState(false);
+  const [focusInside, setFocusInside] = useState(false);
+  const [pageHidden, setPageHidden] = useState(false);
+  useEffect(() => {
+    const onVisibility = () => setPageHidden(document.visibilityState === "hidden");
+    onVisibility();
+    document.addEventListener("visibilitychange", onVisibility);
+    return () => document.removeEventListener("visibilitychange", onVisibility);
+  }, []);
+  const viewportRef = useRef(null);
+  const toasts = useMemo(() => all.slice(-limit), [all, limit]);
+  const context = useMemo(
+    () => ({
+      toasts,
+      add,
+      update,
+      close,
+      paused: pointerInside || focusInside || pageHidden,
+      setPointerInside,
+      setFocusInside,
+      viewportRef
+    }),
+    [toasts, add, update, close, pointerInside, focusInside, pageHidden]
+  );
+  return /* @__PURE__ */ jsx(ToastContext.Provider, { value: context, children });
+}
+
+// src/toast/ToastViewport.tsx
+import { useLayoutEffect, useRef as useRef2 } from "react";
+function ToastViewport({ className, children, render, ...rest }) {
+  const { toasts, viewportRef, setPointerInside, setFocusInside } = useToastContext("<Toast.Viewport>");
+  const elementRef = useRef2(null);
+  const newest = toasts.at(-1)?.id;
+  useLayoutEffect(() => {
+    const element = elementRef.current;
+    viewportRef.current = element;
+    if (!element || typeof element.showPopover !== "function") return;
+    if (element.matches(":popover-open")) element.hidePopover();
+    element.showPopover();
+  }, [newest, viewportRef]);
+  return useRender({
+    render,
+    defaultTagName: "section",
+    props: {
+      popover: "manual",
+      "aria-label": "Notifications",
+      "aria-live": "polite",
+      tabIndex: -1,
+      className,
+      ref: elementRef,
+      children: typeof children === "function" ? children(toasts) : children,
+      onPointerEnter() {
+        setPointerInside(true);
+      },
+      onPointerLeave() {
+        setPointerInside(false);
+      },
+      onFocus() {
+        setFocusInside(true);
+      },
+      onBlur(event) {
+        const next = event.relatedTarget;
+        if (!next || !event.currentTarget.contains(next)) setFocusInside(false);
+      }
+    },
+    consumerProps: rest
+  });
+}
+
+// src/toast/ToastRoot.tsx
+import { useEffect as useEffect2, useRef as useRef3 } from "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+function ToastRoot({ toast, className, children, render, ...rest }) {
+  const { close, paused, viewportRef } = useToastContext("<Toast.Root>");
+  const elementRef = useRef3(null);
+  const { id, timeout } = toast;
+  const remaining = useRef3(timeout);
+  const lastTimeout = useRef3(timeout);
+  if (lastTimeout.current !== timeout) {
+    lastTimeout.current = timeout;
+    remaining.current = timeout;
+  }
+  useEffect2(() => {
+    if (paused || timeout <= 0) return;
+    const started = Date.now();
+    const timer = setTimeout(() => close(id), remaining.current);
+    return () => {
+      clearTimeout(timer);
+      remaining.current = Math.max(0, remaining.current - (Date.now() - started));
+    };
+  }, [paused, timeout, id, close]);
+  const focusInside = useRef3(false);
+  useEffect2(
+    () => () => {
+      if (focusInside.current) viewportRef.current?.focus();
+    },
+    [viewportRef]
+  );
+  const element = useRender({
+    render,
+    defaultTagName: "div",
+    props: {
+      role: toast.priority === "high" ? "alert" : void 0,
+      "aria-atomic": true,
+      "data-type": toast.type,
+      className,
+      children,
+      ref: elementRef,
+      onFocus() {
+        focusInside.current = true;
+      },
+      onBlur(event) {
+        const next = event.relatedTarget;
+        if (!next || !event.currentTarget.contains(next)) focusInside.current = false;
+      },
+      onKeyDown(event) {
+        if (event.key === "Escape") {
+          event.preventDefault();
+          close(id);
+        }
+      }
+    },
+    consumerProps: rest
+  });
+  return /* @__PURE__ */ jsx2(ToastRootContext.Provider, { value: toast, children: element });
+}
+
+// src/toast/ToastTitle.tsx
+function ToastTitle({ className, children, render, ...rest }) {
+  const toast = useToastRootContext("Title");
+  return useRender({
+    render,
+    defaultTagName: "p",
+    props: { className, children: children ?? toast.title },
+    consumerProps: rest
+  });
+}
+
+// src/toast/ToastDescription.tsx
+function ToastDescription({ className, children, render, ...rest }) {
+  const toast = useToastRootContext("Description");
+  return useRender({
+    render,
+    defaultTagName: "div",
+    props: { className, children: children ?? toast.description },
+    consumerProps: rest
+  });
+}
+
+// src/toast/ToastAction.tsx
+function ToastAction({ className, children, render, ...rest }) {
+  useToastRootContext("Action");
+  return useRender({
+    render,
+    defaultTagName: "button",
+    props: { type: "button", className, children },
+    consumerProps: rest
+  });
+}
+
+// src/toast/ToastClose.tsx
+function ToastClose({ className, children, render, ...rest }) {
+  const { close } = useToastContext("<Toast.Close>");
+  const { id } = useToastRootContext("Close");
+  return useRender({
+    render,
+    defaultTagName: "button",
+    props: {
+      type: "button",
+      className,
+      children,
+      onClick() {
+        close(id);
+      }
+    },
+    consumerProps: rest
+  });
+}
+export {
+  index_parts_exports as Toast,
+  useToastManager
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arun-dev/headless",
-  "version": "4.12.0",
+  "version": "4.13.0",
   "description": "Unstyled React behaviour primitives — render engine, controlled/uncontrolled state, and data-* state projection. Ships no CSS and no class names.",
   "license": "MIT",
   "type": "module",
@@ -114,6 +114,16 @@
         "default": "./dist/field/index.cjs"
       }
     },
+    "./toast": {
+      "import": {
+        "types": "./dist/toast/index.d.ts",
+        "default": "./dist/toast/index.js"
+      },
+      "require": {
+        "types": "./dist/toast/index.d.cts",
+        "default": "./dist/toast/index.cjs"
+      }
+    },
     "./switch": {
       "import": {
         "types": "./dist/switch/index.d.ts",