@eifi1/ui-kit 0.9.0 → 0.11.0

package/dist/components/toast.d.ts

@@ -0,0 +1,167 @@
+import * as react from 'react';
+import { ReactNode, MouseEvent, CSSProperties, ReactElement } from 'react';
+
+/** The words the toast layer says. `close` and `notifications` are read by a screen
+ *  reader (the close button's name, the toast region's name); `undo` and `redo` are
+ *  the default action labels of {@link toast.undo} / {@link toast.redo}. */
+interface ToastLabels {
+    close: string;
+    notifications: string;
+    undo: string;
+    redo: string;
+}
+declare const DEFAULT_TOAST_LABELS: ToastLabels;
+type ToastId = string | number;
+/** A button on the toast. Clicking it dismisses the toast, unless `onClick` calls
+ *  `event.preventDefault()`. */
+interface ToastAction {
+    label: ReactNode;
+    onClick: (event: MouseEvent<HTMLButtonElement>) => void;
+}
+interface ToastOptions {
+    /** Re-using an id REPLACES the toast on screen with that id (in place — it does not
+     *  stack a second one), which is how a toast is updated. Default: a fresh id. */
+    id?: ToastId;
+    description?: ReactNode;
+    action?: ToastAction;
+    /** A second, quieter button (sonner's `cancel`). */
+    cancel?: ToastAction;
+    /** Milliseconds; `Infinity` keeps it until dismissed. Default 4s — or
+     *  {@link TOAST_ACTION_DURATION} when there is an `action`, so there is time to
+     *  read the message AND reach the button. */
+    duration?: number;
+    /** Called when the toast is closed by the user (close button, swipe, action). */
+    onDismiss?: (toast: {
+        id: ToastId;
+    }) => void;
+    /** Called when the toast times out. */
+    onAutoClose?: (toast: {
+        id: ToastId;
+    }) => void;
+    /** Wrap the message and the description in `data-private`, so an app's demo /
+     *  privacy mode blurs them like every other sensitive value. */
+    redact?: boolean;
+    /** Replaces the tone's icon. */
+    icon?: ReactNode;
+    /** `false`: no close button, no swipe. */
+    dismissible?: boolean;
+    /** Per toast, over the `<Toaster>`'s `closeButton`. */
+    closeButton?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/** The default duration of a toast that carries an action (8s rather than 4s). */
+declare const TOAST_ACTION_DURATION = 8000;
+type Kind = "default" | "success" | "error" | "warning" | "info" | "loading";
+interface ToastPromiseOptions<T> extends ToastOptions {
+    loading: ReactNode;
+    /** The success message, or a function of the resolved value. Omitted: the loading
+     *  toast is dismissed. */
+    success?: ReactNode | ((value: T) => ReactNode);
+    /** The error message, or a function of the rejection. Omitted: dismissed. */
+    error?: ReactNode | ((error: unknown) => ReactNode);
+    finally?: () => void;
+}
+interface ToastUndoOptions extends Omit<ToastOptions, "action"> {
+    /** Called when the button is pressed. */
+    onUndo: () => void;
+    /** Default: `toast.undo` from `<UiKitProvider>` ("Undo"). */
+    label?: ReactNode;
+    /** Default `success` — the step the toast reports worked. */
+    tone?: Exclude<Kind, "loading">;
+}
+interface ToastRedoOptions extends Omit<ToastUndoOptions, "onUndo"> {
+    onRedo: () => void;
+}
+/**
+ * Show a toast. The same shape as sonner's `toast`, so an app migrates by changing the
+ * import: `toast(msg, opts)`, `toast.success` / `error` / `warning` / `info` /
+ * `loading`, `toast.promise`, `toast.dismiss`, `toast.custom`. Each returns the toast's
+ * id; pass it back as `id` to replace that toast in place.
+ *
+ * Needs a mounted {@link Toaster}. Messages may be any ReactNode.
+ */
+declare const toast: ((message: ReactNode, opts?: ToastOptions) => ToastId) & {
+    message: (message: ReactNode, opts?: ToastOptions) => ToastId;
+    success: (message: ReactNode, opts?: ToastOptions) => ToastId;
+    error: (message: ReactNode, opts?: ToastOptions) => ToastId;
+    warning: (message: ReactNode, opts?: ToastOptions) => ToastId;
+    info: (message: ReactNode, opts?: ToastOptions) => ToastId;
+    /** A spinner that does not time out — replace it (same `id`) or dismiss it. */
+    loading: (message: ReactNode, opts?: ToastOptions) => ToastId;
+    /**
+     * A loading toast that becomes the success or the error toast, in place, when
+     * `promise` settles. Returns the toast's id; the promise itself is the caller's.
+     */
+    promise<T>(promise: Promise<T> | (() => Promise<T>), options: ToastPromiseOptions<T>): ToastId;
+    /** Close one toast, or every toast when `id` is omitted. */
+    dismiss(id?: ToastId): void;
+    /** Render your own node in a toast slot — `render` receives the id to dismiss it. */
+    custom(render: (id: ToastId) => ReactElement, opts?: Omit<ToastOptions, "redact">): ToastId;
+    /**
+     * "Deleted — Undo": a toast whose action takes the step back, labelled by the
+     * provider's `toast.undo`. The journal stays the app's; this is only its toast.
+     * Pair with {@link toast.redo} so the step back can itself be taken back.
+     */
+    undo(message: ReactNode, { onUndo, ...opts }: ToastUndoOptions): ToastId;
+    /** {@link toast.undo}'s mirror: the action is labelled `toast.redo`. */
+    redo(message: ReactNode, { onRedo, ...opts }: ToastRedoOptions): ToastId;
+};
+type ToastPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
+type ToastSwipeDirection = "top" | "right" | "bottom" | "left";
+/** sonner's offset: one value for every edge, or per edge. Numbers are px. */
+type ToasterOffset = string | number | {
+    top?: string | number;
+    right?: string | number;
+    bottom?: string | number;
+    left?: string | number;
+};
+interface ToasterProps {
+    /** Default: `bottom-center` on a phone (so the toast covers neither the header's
+     *  buttons nor the bottom nav's), `top-center` from `md` up. */
+    position?: ToastPosition;
+    /** The height to keep clear at the bottom — AppShell's bottom nav. Default: its
+     *  measured `--app-nav-h`, so nothing has to be passed under an AppShell. The safe
+     *  area is added either way. Numbers are px. */
+    navOffset?: string | number;
+    /** Default: follows the `.dark` class the kit's theme store (`useApplyTheme`) puts
+     *  on `<html>` — whichever store the app built, with nothing passed. */
+    theme?: "light" | "dark" | "system";
+    labels?: Partial<ToastLabels>;
+    /** Default 4s (8s for a toast with an action). */
+    duration?: number;
+    visibleToasts?: number;
+    expand?: boolean;
+    /** Default true. */
+    closeButton?: boolean;
+    /** Tone-coloured toasts (the AlertBanner tokens). Default true. */
+    richColors?: boolean;
+    /** Default: every direction. */
+    swipeDirections?: ToastSwipeDirection[];
+    /** Overrides the computed offset outright (above the nav on a phone, below a 48px
+     *  top bar on desktop). */
+    offset?: ToasterOffset;
+    /** Below 600px, where sonner switches to its full-width layout. Default: `offset`'s
+     *  phone value. */
+    mobileOffset?: ToasterOffset;
+    /** Keyboard shortcut that moves focus into the toasts. Default Alt+T. */
+    hotkey?: string[];
+    gap?: number;
+    dir?: "ltr" | "rtl" | "auto";
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Where the toasts appear, with the kit's defaults — mount ONE, near the root and
+ * inside `<UiKitProvider>` (it reads the `toast` labels) and inside the router if a
+ * toast's content navigates.
+ *
+ * Accessible as sonner makes it: the toasts sit in a polite live region, so a message
+ * is announced with its description and its action's label; every toast and every
+ * button in it is focusable, the timer pauses while focus or the pointer is inside,
+ * and Alt+T ({@link ToasterProps.hotkey}) moves focus to the newest toast. A toast
+ * with an action stays up 8s by default, so the button can be reached.
+ */
+declare function Toaster({ position, navOffset, theme, labels: labelsProp, closeButton, richColors, swipeDirections, offset, mobileOffset, className, style, ...rest }: ToasterProps): react.JSX.Element | null;
+
+export { DEFAULT_TOAST_LABELS, TOAST_ACTION_DURATION, type ToastAction, type ToastId, type ToastLabels, type ToastOptions, type ToastPosition, type ToastPromiseOptions, type ToastRedoOptions, type ToastSwipeDirection, type ToastUndoOptions, Toaster, type ToasterOffset, type ToasterProps, toast };

package/dist/components/toast.js

@@ -0,0 +1,226 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { useEffect, useState, useSyncExternalStore } from "react";
+import { useKitLabels } from "../i18n/kit-labels.js";
+import { useMediaQuery } from "../hooks/use-media-query.js";
+import { PHONE_QUERY } from "./ui.js";
+let sonner = null;
+let loading = null;
+const queue = [];
+function loadSonner() {
+  loading ??= import("sonner").then(
+    (mod) => {
+      sonner = mod;
+      for (const fn of queue.splice(0)) fn(mod);
+      return mod;
+    },
+    () => {
+      queue.length = 0;
+      console.warn(
+        "@eifi1/ui-kit: `toast` needs the optional peer `sonner` \u2014 install it (npm i sonner) to show toasts."
+      );
+      return null;
+    }
+  );
+  return loading;
+}
+function withSonner(fn) {
+  if (sonner) {
+    fn(sonner);
+    return;
+  }
+  queue.push(fn);
+  void loadSonner();
+}
+let counter = 0;
+const nextId = () => `kit-toast-${++counter}`;
+const DEFAULT_TOAST_LABELS = {
+  close: "Close notification",
+  notifications: "Notifications",
+  undo: "Undo",
+  redo: "Redo"
+};
+let activeLabels = DEFAULT_TOAST_LABELS;
+const TOAST_ACTION_DURATION = 8e3;
+const privately = (node) => /* @__PURE__ */ jsx("span", { "data-private": "", children: node });
+function toSonnerData(opts, id) {
+  const { redact, description, duration, action, ...rest } = opts ?? {};
+  const data = { ...rest, id };
+  if (description !== void 0) data.description = redact ? privately(description) : description;
+  if (action) data.action = action;
+  const resolved = duration ?? (action ? TOAST_ACTION_DURATION : void 0);
+  if (resolved !== void 0) data.duration = resolved;
+  return data;
+}
+function show(kind, message, opts) {
+  const id = opts?.id ?? nextId();
+  const title = opts?.redact ? privately(message) : message;
+  const data = toSonnerData(opts, id);
+  withSonner((s) => {
+    if (kind === "default") s.toast(title, data);
+    else s.toast[kind](title, data);
+  });
+  return id;
+}
+function undoable(message, { tone = "success", label, run, ...opts }, fallback) {
+  return show(tone, message, {
+    ...opts,
+    action: { label: label ?? fallback, onClick: () => run() }
+  });
+}
+const toast = Object.assign(
+  (message, opts) => show("default", message, opts),
+  {
+    message: (message, opts) => show("default", message, opts),
+    success: (message, opts) => show("success", message, opts),
+    error: (message, opts) => show("error", message, opts),
+    warning: (message, opts) => show("warning", message, opts),
+    info: (message, opts) => show("info", message, opts),
+    /** A spinner that does not time out — replace it (same `id`) or dismiss it. */
+    loading: (message, opts) => show("loading", message, opts),
+    /**
+     * A loading toast that becomes the success or the error toast, in place, when
+     * `promise` settles. Returns the toast's id; the promise itself is the caller's.
+     */
+    promise(promise, options) {
+      const { loading: pending, success, error, finally: onFinally, ...opts } = options;
+      const id = show("loading", pending, opts);
+      const same = { ...opts, id };
+      Promise.resolve().then(() => typeof promise === "function" ? promise() : promise).then(
+        (value) => {
+          if (success === void 0) toast.dismiss(id);
+          else show("success", typeof success === "function" ? success(value) : success, same);
+        },
+        (reason) => {
+          if (error === void 0) toast.dismiss(id);
+          else show("error", typeof error === "function" ? error(reason) : error, same);
+        }
+      ).finally(() => onFinally?.());
+      return id;
+    },
+    /** Close one toast, or every toast when `id` is omitted. */
+    dismiss(id) {
+      withSonner((s) => s.toast.dismiss(id));
+    },
+    /** Render your own node in a toast slot — `render` receives the id to dismiss it. */
+    custom(render, opts) {
+      const id = opts?.id ?? nextId();
+      const data = toSonnerData(opts, id);
+      withSonner((s) => s.toast.custom(render, data));
+      return id;
+    },
+    /**
+     * "Deleted — Undo": a toast whose action takes the step back, labelled by the
+     * provider's `toast.undo`. The journal stays the app's; this is only its toast.
+     * Pair with {@link toast.redo} so the step back can itself be taken back.
+     */
+    undo(message, { onUndo, ...opts }) {
+      return undoable(message, { ...opts, run: onUndo }, activeLabels.undo);
+    },
+    /** {@link toast.undo}'s mirror: the action is labelled `toast.redo`. */
+    redo(message, { onRedo, ...opts }) {
+      return undoable(message, { ...opts, run: onRedo }, activeLabels.redo);
+    }
+  }
+);
+const KIT_TOASTER_STYLE = {
+  zIndex: "var(--z-toast, 2147483647)",
+  fontFamily: "inherit",
+  "--normal-bg": "var(--bg-surface)",
+  "--normal-bg-hover": "var(--bg-hover)",
+  "--normal-border": "var(--border)",
+  "--normal-border-hover": "var(--border-strong)",
+  "--normal-text": "var(--text-primary)",
+  "--gray2": "var(--bg-hover)",
+  "--gray5": "var(--border-strong)",
+  "--gray11": "var(--text-muted)",
+  "--success-bg": "var(--toast-success-bg)",
+  "--success-border": "var(--toast-success-border)",
+  "--success-text": "var(--success)",
+  "--info-bg": "var(--toast-info-bg)",
+  "--info-border": "var(--toast-info-border)",
+  "--info-text": "var(--info)",
+  "--warning-bg": "var(--toast-warning-bg)",
+  "--warning-border": "var(--toast-warning-border)",
+  "--warning-text": "var(--warning)",
+  "--error-bg": "var(--toast-danger-bg)",
+  "--error-border": "var(--toast-danger-border)",
+  "--error-text": "var(--danger)"
+};
+const ALL_DIRECTIONS = ["top", "right", "bottom", "left"];
+function readDocumentTheme() {
+  return typeof document !== "undefined" && document.documentElement.classList.contains("dark") ? "dark" : "light";
+}
+function subscribeDocumentTheme(onChange) {
+  if (typeof MutationObserver === "undefined") return () => {
+  };
+  const mo = new MutationObserver(onChange);
+  mo.observe(document.documentElement, { attributes: true, attributeFilter: ["class"] });
+  return () => mo.disconnect();
+}
+const px = (v) => typeof v === "number" ? `${v}px` : v;
+function Toaster({
+  position,
+  navOffset,
+  theme,
+  labels: labelsProp,
+  closeButton = true,
+  richColors = true,
+  swipeDirections = ALL_DIRECTIONS,
+  offset,
+  mobileOffset,
+  className,
+  style,
+  ...rest
+}) {
+  const [mod, setMod] = useState(sonner);
+  useEffect(() => {
+    if (mod) return;
+    let live = true;
+    void loadSonner().then((m) => {
+      if (live && m) setMod(m);
+    });
+    return () => {
+      live = false;
+    };
+  }, [mod]);
+  const labels = useKitLabels("toast", DEFAULT_TOAST_LABELS, labelsProp);
+  useEffect(() => {
+    activeLabels = labels;
+    return () => {
+      if (activeLabels === labels) activeLabels = DEFAULT_TOAST_LABELS;
+    };
+  }, [labels]);
+  const documentTheme = useSyncExternalStore(subscribeDocumentTheme, readDocumentTheme, () => "light");
+  const phone = useMediaQuery(PHONE_QUERY, false);
+  const resolved = position ?? (phone ? "bottom-center" : "top-center");
+  const bottom = `calc(max(${navOffset === void 0 ? "var(--app-nav-h, 0px)" : px(navOffset)}, env(safe-area-inset-bottom, 0px)) + 0.75rem)`;
+  const top = "calc(env(safe-area-inset-top, 0px) + 4rem)";
+  const computed = resolved.startsWith("bottom") ? { bottom } : { top };
+  if (!mod) return null;
+  const Sonner = mod.Toaster;
+  return /* @__PURE__ */ jsx(
+    Sonner,
+    {
+      ...rest,
+      position: resolved,
+      theme: theme ?? documentTheme,
+      closeButton,
+      richColors,
+      swipeDirections,
+      offset: offset ?? computed,
+      mobileOffset: mobileOffset ?? offset ?? computed,
+      containerAriaLabel: labels.notifications,
+      toastOptions: { closeButtonAriaLabel: labels.close },
+      className: className ? `kit-toaster ${className}` : "kit-toaster",
+      style: { ...KIT_TOASTER_STYLE, ...style }
+    }
+  );
+}
+export {
+  DEFAULT_TOAST_LABELS,
+  TOAST_ACTION_DURATION,
+  Toaster,
+  toast
+};
+//# sourceMappingURL=toast.js.map

package/dist/components/toast.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/toast.tsx"],"sourcesContent":["import { useEffect, useState, useSyncExternalStore } from \"react\";\nimport type { CSSProperties, MouseEvent, ReactElement, ReactNode } from \"react\";\nimport { useKitLabels } from \"../i18n/kit-labels\";\nimport { useMediaQuery } from \"../hooks/use-media-query\";\nimport { PHONE_QUERY } from \"./ui\";\n\n/**\n * The kit's toast layer: a `toast` API and a `<Toaster>`, over sonner.\n *\n * WHY A WRAPPER AND NOT \"USE SONNER\". Both apps mounted sonner by hand and carried the\n * same policy in it — bottom-centre on a phone so the toast covers neither the header\n * nor the bottom nav, a lift above that nav, swipe in every direction, a z-index above\n * every overlay, the theme fed in from the store — and one of them wrote that policy\n * twice. `toast` mirrors sonner's call shape, so migrating is an import swap:\n *\n *     import { toast } from \"@eifi1/ui-kit\";   // was: from \"sonner\"\n *\n * WHY SONNER IS LOADED LAZILY. It is an OPTIONAL peer, and this module is re-exported by\n * the barrel: a static import here would make every app that imports a Button install\n * it (see optional-peer-imports.test.tsx). So nothing here imports it statically. The\n * `<Toaster>` loads it when it mounts — long before anyone clicks anything — and a call\n * made before that is queued and replayed in order the moment it has loaded. Every call\n * returns its id synchronously anyway: the id is chosen here, not by sonner.\n */\n\ntype Sonner = typeof import(\"sonner\");\ntype SonnerData = NonNullable<Parameters<Sonner[\"toast\"]>[1]>;\n\n/* ── Loading sonner ──────────────────────────────────────────────────────── */\n\nlet sonner: Sonner | null = null;\nlet loading: Promise<Sonner | null> | null = null;\nconst queue: Array<(s: Sonner) => void> = [];\n\nfunction loadSonner(): Promise<Sonner | null> {\n  loading ??= import(\"sonner\").then(\n    (mod) => {\n      sonner = mod;\n      // Flushed in the SAME callback that sets `sonner`, so a call arriving between\n      // the two cannot overtake one that was queued before it.\n      for (const fn of queue.splice(0)) fn(mod);\n      return mod;\n    },\n    () => {\n      queue.length = 0;\n      console.warn(\n        \"@eifi1/ui-kit: `toast` needs the optional peer `sonner` — install it (npm i sonner) to show toasts.\",\n      );\n      return null;\n    },\n  );\n  return loading;\n}\n\nfunction withSonner(fn: (s: Sonner) => void): void {\n  if (sonner) {\n    fn(sonner);\n    return;\n  }\n  queue.push(fn);\n  void loadSonner();\n}\n\nlet counter = 0;\nconst nextId = () => `kit-toast-${++counter}`;\n\n/* ── Labels ──────────────────────────────────────────────────────────────── */\n\n/** The words the toast layer says. `close` and `notifications` are read by a screen\n *  reader (the close button's name, the toast region's name); `undo` and `redo` are\n *  the default action labels of {@link toast.undo} / {@link toast.redo}. */\nexport interface ToastLabels {\n  close: string;\n  notifications: string;\n  undo: string;\n  redo: string;\n}\n\nexport const DEFAULT_TOAST_LABELS: ToastLabels = {\n  close: \"Close notification\",\n  notifications: \"Notifications\",\n  undo: \"Undo\",\n  redo: \"Redo\",\n};\n\n/** What the mounted `<Toaster>` resolved from `<UiKitProvider>` — so `toast.undo()`,\n *  which is called from mutation callbacks and not from a component, still says\n *  \"Rückgängig\" in a German app. */\nlet activeLabels: ToastLabels = DEFAULT_TOAST_LABELS;\n\n/* ── The API ─────────────────────────────────────────────────────────────── */\n\nexport type ToastId = string | number;\n\n/** A button on the toast. Clicking it dismisses the toast, unless `onClick` calls\n *  `event.preventDefault()`. */\nexport interface ToastAction {\n  label: ReactNode;\n  onClick: (event: MouseEvent<HTMLButtonElement>) => void;\n}\n\nexport interface ToastOptions {\n  /** Re-using an id REPLACES the toast on screen with that id (in place — it does not\n   *  stack a second one), which is how a toast is updated. Default: a fresh id. */\n  id?: ToastId;\n  description?: ReactNode;\n  action?: ToastAction;\n  /** A second, quieter button (sonner's `cancel`). */\n  cancel?: ToastAction;\n  /** Milliseconds; `Infinity` keeps it until dismissed. Default 4s — or\n   *  {@link TOAST_ACTION_DURATION} when there is an `action`, so there is time to\n   *  read the message AND reach the button. */\n  duration?: number;\n  /** Called when the toast is closed by the user (close button, swipe, action). */\n  onDismiss?: (toast: { id: ToastId }) => void;\n  /** Called when the toast times out. */\n  onAutoClose?: (toast: { id: ToastId }) => void;\n  /** Wrap the message and the description in `data-private`, so an app's demo /\n   *  privacy mode blurs them like every other sensitive value. */\n  redact?: boolean;\n  /** Replaces the tone's icon. */\n  icon?: ReactNode;\n  /** `false`: no close button, no swipe. */\n  dismissible?: boolean;\n  /** Per toast, over the `<Toaster>`'s `closeButton`. */\n  closeButton?: boolean;\n  className?: string;\n  style?: CSSProperties;\n}\n\n/** The default duration of a toast that carries an action (8s rather than 4s). */\nexport const TOAST_ACTION_DURATION = 8000;\n\ntype Kind = \"default\" | \"success\" | \"error\" | \"warning\" | \"info\" | \"loading\";\n\nconst privately = (node: ReactNode) => <span data-private=\"\">{node}</span>;\n\nfunction toSonnerData(opts: ToastOptions | undefined, id: ToastId): SonnerData {\n  const { redact, description, duration, action, ...rest } = opts ?? {};\n  const data: SonnerData = { ...rest, id };\n  if (description !== undefined) data.description = redact ? privately(description) : description;\n  if (action) data.action = action;\n  const resolved = duration ?? (action ? TOAST_ACTION_DURATION : undefined);\n  if (resolved !== undefined) data.duration = resolved;\n  return data;\n}\n\nfunction show(kind: Kind, message: ReactNode, opts?: ToastOptions): ToastId {\n  const id = opts?.id ?? nextId();\n  const title = opts?.redact ? privately(message) : message;\n  const data = toSonnerData(opts, id);\n  withSonner((s) => {\n    if (kind === \"default\") s.toast(title, data);\n    else s.toast[kind](title, data);\n  });\n  return id;\n}\n\nexport interface ToastPromiseOptions<T> extends ToastOptions {\n  loading: ReactNode;\n  /** The success message, or a function of the resolved value. Omitted: the loading\n   *  toast is dismissed. */\n  success?: ReactNode | ((value: T) => ReactNode);\n  /** The error message, or a function of the rejection. Omitted: dismissed. */\n  error?: ReactNode | ((error: unknown) => ReactNode);\n  finally?: () => void;\n}\n\nexport interface ToastUndoOptions extends Omit<ToastOptions, \"action\"> {\n  /** Called when the button is pressed. */\n  onUndo: () => void;\n  /** Default: `toast.undo` from `<UiKitProvider>` (\"Undo\"). */\n  label?: ReactNode;\n  /** Default `success` — the step the toast reports worked. */\n  tone?: Exclude<Kind, \"loading\">;\n}\n\nexport interface ToastRedoOptions extends Omit<ToastUndoOptions, \"onUndo\"> {\n  onRedo: () => void;\n}\n\nfunction undoable(\n  message: ReactNode,\n  { tone = \"success\", label, run, ...opts }: Omit<ToastUndoOptions, \"onUndo\"> & { run: () => void },\n  fallback: ReactNode,\n): ToastId {\n  return show(tone, message, {\n    ...opts,\n    action: { label: label ?? fallback, onClick: () => run() },\n  });\n}\n\n/**\n * Show a toast. The same shape as sonner's `toast`, so an app migrates by changing the\n * import: `toast(msg, opts)`, `toast.success` / `error` / `warning` / `info` /\n * `loading`, `toast.promise`, `toast.dismiss`, `toast.custom`. Each returns the toast's\n * id; pass it back as `id` to replace that toast in place.\n *\n * Needs a mounted {@link Toaster}. Messages may be any ReactNode.\n */\nexport const toast = Object.assign(\n  (message: ReactNode, opts?: ToastOptions): ToastId => show(\"default\", message, opts),\n  {\n    message: (message: ReactNode, opts?: ToastOptions) => show(\"default\", message, opts),\n    success: (message: ReactNode, opts?: ToastOptions) => show(\"success\", message, opts),\n    error: (message: ReactNode, opts?: ToastOptions) => show(\"error\", message, opts),\n    warning: (message: ReactNode, opts?: ToastOptions) => show(\"warning\", message, opts),\n    info: (message: ReactNode, opts?: ToastOptions) => show(\"info\", message, opts),\n    /** A spinner that does not time out — replace it (same `id`) or dismiss it. */\n    loading: (message: ReactNode, opts?: ToastOptions) => show(\"loading\", message, opts),\n\n    /**\n     * A loading toast that becomes the success or the error toast, in place, when\n     * `promise` settles. Returns the toast's id; the promise itself is the caller's.\n     */\n    promise<T>(promise: Promise<T> | (() => Promise<T>), options: ToastPromiseOptions<T>): ToastId {\n      const { loading: pending, success, error, finally: onFinally, ...opts } = options;\n      const id = show(\"loading\", pending, opts);\n      const same = { ...opts, id };\n      Promise.resolve()\n        .then(() => (typeof promise === \"function\" ? promise() : promise))\n        .then(\n          (value) => {\n            if (success === undefined) toast.dismiss(id);\n            else show(\"success\", typeof success === \"function\" ? success(value) : success, same);\n          },\n          (reason: unknown) => {\n            if (error === undefined) toast.dismiss(id);\n            else show(\"error\", typeof error === \"function\" ? error(reason) : error, same);\n          },\n        )\n        .finally(() => onFinally?.());\n      return id;\n    },\n\n    /** Close one toast, or every toast when `id` is omitted. */\n    dismiss(id?: ToastId): void {\n      withSonner((s) => s.toast.dismiss(id));\n    },\n\n    /** Render your own node in a toast slot — `render` receives the id to dismiss it. */\n    custom(render: (id: ToastId) => ReactElement, opts?: Omit<ToastOptions, \"redact\">): ToastId {\n      const id = opts?.id ?? nextId();\n      const data = toSonnerData(opts, id);\n      withSonner((s) => s.toast.custom(render, data));\n      return id;\n    },\n\n    /**\n     * \"Deleted — Undo\": a toast whose action takes the step back, labelled by the\n     * provider's `toast.undo`. The journal stays the app's; this is only its toast.\n     * Pair with {@link toast.redo} so the step back can itself be taken back.\n     */\n    undo(message: ReactNode, { onUndo, ...opts }: ToastUndoOptions): ToastId {\n      return undoable(message, { ...opts, run: onUndo }, activeLabels.undo);\n    },\n\n    /** {@link toast.undo}'s mirror: the action is labelled `toast.redo`. */\n    redo(message: ReactNode, { onRedo, ...opts }: ToastRedoOptions): ToastId {\n      return undoable(message, { ...opts, run: onRedo }, activeLabels.redo);\n    },\n  },\n);\n\n/* ── The Toaster ─────────────────────────────────────────────────────────── */\n\nexport type ToastPosition =\n  | \"top-left\"\n  | \"top-center\"\n  | \"top-right\"\n  | \"bottom-left\"\n  | \"bottom-center\"\n  | \"bottom-right\";\n\nexport type ToastSwipeDirection = \"top\" | \"right\" | \"bottom\" | \"left\";\n\n/** sonner's offset: one value for every edge, or per edge. Numbers are px. */\nexport type ToasterOffset =\n  | string\n  | number\n  | { top?: string | number; right?: string | number; bottom?: string | number; left?: string | number };\n\nexport interface ToasterProps {\n  /** Default: `bottom-center` on a phone (so the toast covers neither the header's\n   *  buttons nor the bottom nav's), `top-center` from `md` up. */\n  position?: ToastPosition;\n  /** The height to keep clear at the bottom — AppShell's bottom nav. Default: its\n   *  measured `--app-nav-h`, so nothing has to be passed under an AppShell. The safe\n   *  area is added either way. Numbers are px. */\n  navOffset?: string | number;\n  /** Default: follows the `.dark` class the kit's theme store (`useApplyTheme`) puts\n   *  on `<html>` — whichever store the app built, with nothing passed. */\n  theme?: \"light\" | \"dark\" | \"system\";\n  labels?: Partial<ToastLabels>;\n  /** Default 4s (8s for a toast with an action). */\n  duration?: number;\n  visibleToasts?: number;\n  expand?: boolean;\n  /** Default true. */\n  closeButton?: boolean;\n  /** Tone-coloured toasts (the AlertBanner tokens). Default true. */\n  richColors?: boolean;\n  /** Default: every direction. */\n  swipeDirections?: ToastSwipeDirection[];\n  /** Overrides the computed offset outright (above the nav on a phone, below a 48px\n   *  top bar on desktop). */\n  offset?: ToasterOffset;\n  /** Below 600px, where sonner switches to its full-width layout. Default: `offset`'s\n   *  phone value. */\n  mobileOffset?: ToasterOffset;\n  /** Keyboard shortcut that moves focus into the toasts. Default Alt+T. */\n  hotkey?: string[];\n  gap?: number;\n  dir?: \"ltr\" | \"rtl\" | \"auto\";\n  className?: string;\n  style?: CSSProperties;\n}\n\n/** The kit's palette, mapped onto sonner's variables. Inline on the toaster element,\n *  so it wins over sonner's injected sheet with no specificity contest. The tone\n *  backgrounds go through `--toast-*` aliases computed at `:root` in tokens.css:\n *  sonner redefines `--success-bg` on this same element, and a variable cannot read\n *  its own name — `--success-bg: var(--success-bg)` here would be a cycle. */\nconst KIT_TOASTER_STYLE = {\n  zIndex: \"var(--z-toast, 2147483647)\",\n  fontFamily: \"inherit\",\n  \"--normal-bg\": \"var(--bg-surface)\",\n  \"--normal-bg-hover\": \"var(--bg-hover)\",\n  \"--normal-border\": \"var(--border)\",\n  \"--normal-border-hover\": \"var(--border-strong)\",\n  \"--normal-text\": \"var(--text-primary)\",\n  \"--gray2\": \"var(--bg-hover)\",\n  \"--gray5\": \"var(--border-strong)\",\n  \"--gray11\": \"var(--text-muted)\",\n  \"--success-bg\": \"var(--toast-success-bg)\",\n  \"--success-border\": \"var(--toast-success-border)\",\n  \"--success-text\": \"var(--success)\",\n  \"--info-bg\": \"var(--toast-info-bg)\",\n  \"--info-border\": \"var(--toast-info-border)\",\n  \"--info-text\": \"var(--info)\",\n  \"--warning-bg\": \"var(--toast-warning-bg)\",\n  \"--warning-border\": \"var(--toast-warning-border)\",\n  \"--warning-text\": \"var(--warning)\",\n  \"--error-bg\": \"var(--toast-danger-bg)\",\n  \"--error-border\": \"var(--toast-danger-border)\",\n  \"--error-text\": \"var(--danger)\",\n} as CSSProperties;\n\nconst ALL_DIRECTIONS: ToastSwipeDirection[] = [\"top\", \"right\", \"bottom\", \"left\"];\n\n/** Light or dark, as the `.dark` class on `<html>` says right now. */\nfunction readDocumentTheme(): \"light\" | \"dark\" {\n  return typeof document !== \"undefined\" && document.documentElement.classList.contains(\"dark\")\n    ? \"dark\"\n    : \"light\";\n}\n\nfunction subscribeDocumentTheme(onChange: () => void): () => void {\n  if (typeof MutationObserver === \"undefined\") return () => {};\n  const mo = new MutationObserver(onChange);\n  mo.observe(document.documentElement, { attributes: true, attributeFilter: [\"class\"] });\n  return () => mo.disconnect();\n}\n\nconst px = (v: string | number) => (typeof v === \"number\" ? `${v}px` : v);\n\n/**\n * Where the toasts appear, with the kit's defaults — mount ONE, near the root and\n * inside `<UiKitProvider>` (it reads the `toast` labels) and inside the router if a\n * toast's content navigates.\n *\n * Accessible as sonner makes it: the toasts sit in a polite live region, so a message\n * is announced with its description and its action's label; every toast and every\n * button in it is focusable, the timer pauses while focus or the pointer is inside,\n * and Alt+T ({@link ToasterProps.hotkey}) moves focus to the newest toast. A toast\n * with an action stays up 8s by default, so the button can be reached.\n */\nexport function Toaster({\n  position,\n  navOffset,\n  theme,\n  labels: labelsProp,\n  closeButton = true,\n  richColors = true,\n  swipeDirections = ALL_DIRECTIONS,\n  offset,\n  mobileOffset,\n  className,\n  style,\n  ...rest\n}: ToasterProps) {\n  const [mod, setMod] = useState<Sonner | null>(sonner);\n  useEffect(() => {\n    if (mod) return;\n    let live = true;\n    void loadSonner().then((m) => {\n      if (live && m) setMod(m);\n    });\n    return () => {\n      live = false;\n    };\n  }, [mod]);\n\n  const labels = useKitLabels(\"toast\", DEFAULT_TOAST_LABELS, labelsProp);\n  useEffect(() => {\n    activeLabels = labels;\n    return () => {\n      if (activeLabels === labels) activeLabels = DEFAULT_TOAST_LABELS;\n    };\n  }, [labels]);\n\n  const documentTheme = useSyncExternalStore(subscribeDocumentTheme, readDocumentTheme, () => \"light\" as const);\n  const phone = useMediaQuery(PHONE_QUERY, false);\n  const resolved: ToastPosition = position ?? (phone ? \"bottom-center\" : \"top-center\");\n\n  // Above the bottom nav and the home indicator: whichever is taller, since the nav\n  // already pads itself by the safe area (the same sum BulkActionBar floats on).\n  const bottom = `calc(max(${navOffset === undefined ? \"var(--app-nav-h, 0px)\" : px(navOffset)}, env(safe-area-inset-bottom, 0px)) + 0.75rem)`;\n  // Below a 48px TopBar with the same 1rem clearance.\n  const top = \"calc(env(safe-area-inset-top, 0px) + 4rem)\";\n  const computed = resolved.startsWith(\"bottom\") ? { bottom } : { top };\n\n  if (!mod) return null;\n  const Sonner = mod.Toaster;\n  return (\n    <Sonner\n      {...rest}\n      position={resolved}\n      theme={theme ?? documentTheme}\n      closeButton={closeButton}\n      richColors={richColors}\n      swipeDirections={swipeDirections}\n      offset={offset ?? computed}\n      mobileOffset={mobileOffset ?? offset ?? computed}\n      containerAriaLabel={labels.notifications}\n      toastOptions={{ closeButtonAriaLabel: labels.close }}\n      className={className ? `kit-toaster ${className}` : \"kit-toaster\"}\n      style={{ ...KIT_TOASTER_STYLE, ...style }}\n    />\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/components/toggle-group.d.ts

@@ -1,4 +1,4 @@
-import { ComponentPropsWithoutRef, ReactElement } from 'react';
+import { ComponentPropsWithoutRef, ReactNode, ReactElement } from 'react';
 
 interface ToggleOption<T extends string> {
     value: T;
@@ -40,12 +40,53 @@ interface ToggleGroupBaseProps<T extends string> extends Omit<ComponentPropsWith
      * live and others are not is a menu with holes in it, and no caller here wants one.
      */
     disabled?: boolean;
+    /**
+     * `sm`: 12px options with `px-2 py-1` — the compact group keksdose's rule editor
+     * (rule-editor:204) writes as `optionClassName="px-2 py-1 text-xs"` beside a small
+     * caption. `md` (default) is the size every other group has.
+     */
+    size?: "sm" | "md";
+    /**
+     * Stand in a form row as a FIELD: with a label the group wears the field's chrome —
+     * border, surface, the top strip with a small static label in it, a labelled
+     * {@link Select}'s height — so beside an Input or a Select it reads as one of them
+     * rather than as a control with a caption over it. lenkbank builds exactly this by
+     * hand as `ToggleField` (features/gear/common.tsx:97, feedback #69), and its notes
+     * are why the chrome STRETCHES to its row as well as matching the select's padding:
+     * a native select's height is the browser's, so a toggle a few pixels short of it
+     * is levelled up by the row rather than by arithmetic.
+     *
+     * The label names the group (`aria-labelledby`), so `aria-label` is not needed. With
+     * a label, `className` styles the field's wrapper — as on {@link Select} — and the
+     * group's own box is dropped: two nested borders read as a control in a control.
+     */
+    label?: ReactNode;
+    /** A {@link FieldHint} on the label line, as on a labelled {@link Select}. Only with
+     *  `label`. */
+    hint?: ReactNode;
+    /** The message under the field when it is wrong: paints the field's border with
+     *  `--danger`, marks the group `aria-invalid` and describes it with the message, as
+     *  {@link Select}'s `error` does. Only with `label`. */
+    error?: ReactNode;
 }
+/**
+ * A line under the group saying what the CHOSEN option means — lenkbank's ToggleField
+ * `hint` (features/gear/common.tsx:97): not help behind a "?" but a caption, and one
+ * that changes as the choice does. Pass a function of the value for that; it is
+ * attached with `aria-describedby`, and a function caption is also a polite live
+ * region, because a description is read when the group is entered and not again when
+ * an arrow key changes the choice underneath it.
+ *
+ * In muted 11px text under the field (or the bare group), above an `error`.
+ */
+type ToggleGroupCaption<V> = ReactNode | ((value: V) => ReactNode);
 /** The group as it has always been: one option is always the answer. */
 interface ToggleGroupRequiredProps<T extends string> extends ToggleGroupBaseProps<T> {
     allowEmpty?: false;
     value: T;
     onChange: (value: T) => void;
+    /** See {@link ToggleGroupCaption}. */
+    caption?: ToggleGroupCaption<T>;
 }
 /**
  * A group that can be emptied: clicking the active option clears it, and `onChange`
@@ -61,6 +102,8 @@ interface ToggleGroupClearableProps<T extends string> extends ToggleGroupBasePro
     allowEmpty: true;
     value: T | null;
     onChange: (value: T | null) => void;
+    /** See {@link ToggleGroupCaption}. `null` while nothing is chosen. */
+    caption?: ToggleGroupCaption<T | null>;
 }
 /** `allowEmpty` picks the shape, so `onChange` is typed `(T) => void` unless the group
  *  can actually emit `null` — no existing caller has a `null` to handle. */

package/dist/components/toggle-group.js

@@ -1,7 +1,9 @@
 "use client";
-import { jsx } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useId } from "react";
 import { cn } from "../lib/cn.js";
 import { horizontalStep } from "../lib/direction.js";
+import { FIELD_INVALID, FloatingField } from "./ui.js";
 function ToggleGroup(props) {
   const {
     value,
@@ -10,10 +12,22 @@ function ToggleGroup(props) {
     optionClassName,
     ariaLabel,
     disabled = false,
+    size = "md",
+    label,
+    hint,
+    error,
     "aria-label": ariaLabelAttr,
     ...restWithMode
   } = props;
-  const { allowEmpty: _allowEmpty, onChange: _onChange, ...rest } = restWithMode;
+  const labelId = useId();
+  const errorId = useId();
+  const field = label !== void 0 && label !== null && label !== false && label !== "";
+  const hasError = field && error !== void 0 && error !== null && error !== false && error !== "";
+  const { allowEmpty: _allowEmpty, onChange: _onChange, caption, ...rest } = restWithMode;
+  const captionId = useId();
+  const captionIsLive = typeof caption === "function";
+  const captionNode = captionIsLive ? caption(value) : caption;
+  const hasCaption = captionNode !== void 0 && captionNode !== null && captionNode !== false && captionNode !== "";
   const choose = (next) => {
     if (props.allowEmpty) props.onChange(next === value ? null : next);
     else props.onChange(next);
@@ -36,12 +50,15 @@ function ToggleGroup(props) {
     buttons?.[next]?.focus();
     choose(options[next].value);
   };
-  return /* @__PURE__ */ jsx(
+  const group = /* @__PURE__ */ jsx(
     "div",
     {
       ...rest,
       role: clearable ? "group" : "radiogroup",
       "aria-label": ariaLabelAttr ?? ariaLabel,
+      "aria-labelledby": field && ariaLabelAttr === void 0 && ariaLabel === void 0 ? labelId : rest["aria-labelledby"],
+      "aria-invalid": hasError || rest["aria-invalid"] || void 0,
+      "aria-describedby": [rest["aria-describedby"], hasCaption && captionId, hasError && errorId].filter(Boolean).join(" ") || void 0,
       "aria-disabled": disabled || void 0,
       className: cn(
         // `gap-0.5` — the same 2px as the container's own padding, so EVERY segment
@@ -61,7 +78,10 @@ function ToggleGroup(props) {
         // package does; `cursor-not-allowed` is on the buttons, which is what a
         // pointer is actually over.
         disabled && "opacity-60",
-        className
+        // Inside the field's chrome the group is only a row of segments: no border, no
+        // surface, no padding of its own, and the field (not the group) is what dims.
+        field && "border-0 bg-transparent p-0 shadow-none opacity-100",
+        !field && className
       ),
       children: options.map((opt, index) => {
         const active = opt.value === value;
@@ -100,6 +120,11 @@ function ToggleGroup(props) {
               // inside the segment it belongs to; focus-visible keeps it for the
               // keyboard, which is the only input that needs it.
               "min-w-0 flex-1 basis-auto truncate rounded px-3 py-1.5 text-sm font-medium transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--border-strong)]",
+              size === "sm" && "px-2 py-1 text-xs",
+              // In a field: no vertical padding and a 20px line — a `text-sm` line, the
+              // same line a labelled Select holds under its label strip — so the field's
+              // own `pt-4 pb-1` decides the height, as it does for the select.
+              field && "py-0 leading-5",
               active ? "bg-[var(--bg-inverse)] text-[var(--text-inverse)]" : "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]",
               // No hover fill on a group that cannot be changed — a segment that
               // lights up under the pointer is an offer, and there is none here.
@@ -114,6 +139,50 @@ function ToggleGroup(props) {
       })
     }
   );
+  const captionEl = hasCaption || captionIsLive ? /* @__PURE__ */ jsx(
+    "p",
+    {
+      id: captionId,
+      "aria-live": captionIsLive ? "polite" : void 0,
+      className: cn("text-[11px] leading-snug text-[var(--text-muted)]", hasCaption && "mt-1"),
+      children: hasCaption ? captionNode : null
+    }
+  ) : null;
+  if (!field) {
+    if (!captionEl) return group;
+    return /* @__PURE__ */ jsxs("div", { className: "min-w-0", children: [
+      group,
+      captionEl
+    ] });
+  }
+  return (
+    // `h-full` + `flex-1`: the chrome fills a grid or stretched flex row, which is what
+    // levels it with a select beside it whatever the browser makes of the select.
+    /* @__PURE__ */ jsxs("div", { className: cn("flex h-full flex-col", className), children: [
+      /* @__PURE__ */ jsx(
+        FloatingField,
+        {
+          className: "flex flex-1 flex-col",
+          label: /* @__PURE__ */ jsx("span", { id: labelId, children: label }),
+          staticLabel: true,
+          hint,
+          children: /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: cn(
+                "flex flex-1 flex-col justify-center rounded-md border border-[var(--border)] bg-[var(--bg-surface)] px-1 pt-4 pb-1 shadow-sm",
+                disabled && "bg-[var(--bg-surface-2)] opacity-60",
+                hasError && FIELD_INVALID
+              ),
+              children: group
+            }
+          )
+        }
+      ),
+      captionEl,
+      hasError && /* @__PURE__ */ jsx("p", { id: errorId, className: "mt-1 text-[11px] leading-tight text-[var(--danger)]", children: error })
+    ] })
+  );
 }
 export {
   ToggleGroup