@tensor_1/react 2.27.0 → 2.29.0

package/README.md

@@ -308,3 +308,49 @@ const toRoute = (p: UixLinkProps) => <NextLink {...p} />;
 - **`CollapsibleSection`** stays a JS-free `<details>` unless you pass `lazy`, `persistKey` or `openRequest`. `lazy` unmounts a closed body; `lazy="keep"` keeps it after the first open.
 - **`ConfirmDialog`** focuses the type-to-confirm field, else Cancel when `destructive`. `Popconfirm` is for low-risk, easily undone actions; use `ConfirmDialog` for anything hard to undo.
 - **`KbdCombo`** renders the non-Apple glyphs on the server and switches to ⌘/⇧/⌥ after mount, so hydration matches. Pass `platform` to pin it.
+
+### Imperative toasts (2.28.0)
+
+`toast()` queues a toast from anywhere on the client (a mutation hook, a tRPC error handler); every mounted
+`<Toaster />` renders the queue (UIx HAR-1363; replaces `sonner` in TENSOR and MOTUS).
+
+```tsx
+<Toaster position="bottom-end" limit={3} />                       // once, in the app shell
+
+toast.success('Saved', { description: 'Change CHG-1042 updated.' });
+toast.error('Could not save', { action: { label: 'Copy details', onClick: copy } });   // stays until dismissed
+toast.warning('Export is taking longer than usual');
+const id = toast.loading('Exporting…'); toast.update(id, { kind: 'success', message: 'Exported' });
+toast.promise(save(), { loading: 'Saving…', success: 'Saved', error: (e) => `Failed: ${message(e)}` });
+toast.undoable('Ticket closed', { onUndo: reopen, onCommit: close });   // TENSOR C2 useUndoableAction
+toast.dismiss(id);   // or toast.dismiss() for all
+```
+
+- **Timing:** success, info and default toasts stay 5 s, warnings 8 s; errors and loading toasts stay until dismissed or updated. Pass `duration` (ms, or `null`) to override. Timers pause while the pointer or focus is inside the toaster and while the tab is hidden.
+- **Stacking:** at most `limit` toasts show (default 3). The rest wait their turn. Reusing an `id` replaces a toast in place.
+- **Accessibility:** errors are `role="alert"`. Everything else is announced through the toaster's polite live region, and a loading toast that settles is announced again. Esc closes the focused toast. Tone glyphs are decorative; the text carries the meaning.
+- **Stores:** `toast` writes to a default store that `<Toaster />` reads. `createToastApi(createToastStore())` gives a separate queue (tests, embedded apps); pass its `store` to `<Toaster store>`. The store has no React dependency.
+- `<Toaster>` still renders hand-managed `<Toast>` children first. `Toast` gains `tone="warning"` and an `action` slot.
+### Icons (`@tensor_1/react/icons`)
+
+The UIx icon set (HAR-996): 233 glyphs drawn in `currentColor` at the `--uix-icon-*` sizes. Icons come only from UIx
+(workspace ADR-0038); no product adds an icon library. The glyphs are Lucide's (ISC); the licence travels in
+`THIRD_PARTY_NOTICES.md`. Import the CSS once: `@tensor_1/tokens/components/icon` (also in the bundle).
+
+```tsx
+import { ShieldCheckIcon, TriangleAlertIcon, Icon } from '@tensor_1/react/icons';
+import type { UixIcon, IconName } from '@tensor_1/react/icons';
+
+<ShieldCheckIcon />                                   // decorative: aria-hidden, 20 px (md)
+<ShieldCheckIcon size="sm" tone="success" label="Verified" />   // role="img" with a name
+<Button icon aria-label="Delete"><Trash2Icon /></Button>         // the button carries the name
+<Icon name={entityIconName} />                          // chosen at run time (loads the whole set)
+const icons: Record<EntityType, UixIcon> = { incident: SirenIcon, change: GitBranchIcon };
+```
+
+- **Migrating from `lucide-react`:** import from `@tensor_1/react/icons` and add `Icon` to the name: `ShieldCheck` → `ShieldCheckIcon`. The older Lucide names the products use are kept as aliases (`AlertTriangleIcon`, `CheckCircle2Icon`, `Loader2Icon`, …). `etc/icon-names.json` maps every Lucide name to its UIx component and glyph, for a codemod. `LucideIcon` becomes `UixIcon`.
+- **Size:** `sm` 16 px, `md` 20 px (default), `lg` 24 px, or any CSS length or pixel number. A product sizing class (a Tailwind `size-4`) wins over the default.
+- **Tone:** `current` (default, inherits the text colour), `muted`, `accent`, `success`, `warning`, `danger`, `info`.
+- **Accessibility:** decorative unless `label` is set. Never let an icon carry meaning alone; pair it with text.
+- **Bundle size:** each `<Name>Icon` is tree-shaken; one icon adds well under 3 KB minified. `<Icon name>` and `ICON_GLYPHS` load all of them.
+- **A glyph is missing?** Add its Lucide name to `scripts/icon-names.txt`, run `node scripts/generate-icons.mjs <lucide-react dir>` and release. Do not paste an SVG into a product.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,54 @@
+# Third-party notices
+
+`@tensor_1/react` redistributes SVG path data from these projects. Their licences require this notice to travel with copies.
+
+## Lucide (lucide-react 1.39.0)
+
+Used by: the icon set (`@tensor_1/react/icons`, `dist/icons/**`) and the editor, emoji, reaction and table-control glyphs (`EditorIcons`). Source: https://lucide.dev
+
+```text
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+```

package/dist/components/Toast.d.ts

@@ -1,7 +1,8 @@
 import * as react from 'react';
 import { HTMLAttributes, ReactNode } from 'react';
+import { ToastStore } from '../toast-store.js';
 
-type ToastTone = 'success' | 'danger' | 'info';
+type ToastTone = 'success' | 'danger' | 'info' | 'warning';
 interface ToastProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
     /** TENSOR RX-125 (UIX-04): translatable; English default. */
     dismissLabel?: string;
@@ -9,15 +10,26 @@ interface ToastProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
     message?: ReactNode;
     tone?: ToastTone;
     icon?: ReactNode;
+    /** A button (or link) after the text, e.g. "Undo" or "Copy details" (HAR-1363). */
+    action?: ReactNode;
     onClose?: () => void;
     leaving?: boolean;
 }
-declare function Toast({ title, message, tone, icon, onClose, leaving, dismissLabel: dismissLabelProp, className, ...props }: ToastProps): react.JSX.Element;
+declare function Toast({ title, message, tone, icon, action, onClose, leaving, dismissLabel: dismissLabelProp, className, ...props }: ToastProps): react.JSX.Element;
 interface ToasterProps extends HTMLAttributes<HTMLDivElement> {
     /** TENSOR RX-125 (UIX-04): translatable; English default. */
     regionLabel?: string;
+    /**
+     * The queue to render (HAR-1363). Default: the store behind the exported `toast()`.
+     * Children still render first, so a hand-managed `<Toast>` keeps working.
+     */
+    store?: ToastStore;
+    /** At most this many store toasts on screen; later ones wait their turn. Default 3. */
+    limit?: number;
+    /** Corner of the viewport. Default `bottom-end`. */
+    position?: 'bottom-end' | 'bottom-start' | 'bottom-center' | 'top-end' | 'top-start' | 'top-center';
     children?: ReactNode;
 }
-declare function Toaster({ children, regionLabel: regionLabelProp, className, ...props }: ToasterProps): react.JSX.Element;
+declare function Toaster({ children, regionLabel: regionLabelProp, store, limit, position, className, onMouseEnter, onMouseLeave, onFocus, onBlur, onKeyDown, ...props }: ToasterProps): react.JSX.Element;
 
 export { Toast, type ToastProps, type ToastTone, Toaster, type ToasterProps };

package/dist/components/Toast.js

@@ -1,10 +1,11 @@
 "use client";
-import { jsx, jsxs } from "react/jsx-runtime";
-import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { cx } from "../cx.js";
 import { useUixLabels } from "../labels-context.js";
+import { toast as defaultToast } from "../toast-store.js";
 const ToasterContext = createContext(null);
-function Toast({ title, message, tone, icon, onClose, leaving, dismissLabel: dismissLabelProp, className, ...props }) {
+function Toast({ title, message, tone, icon, action, onClose, leaving, dismissLabel: dismissLabelProp, className, ...props }) {
   const uixLabels = useUixLabels();
   const dismissLabel = dismissLabelProp ?? uixLabels.toast?.dismiss ?? "Dismiss";
   const assertive = tone === "danger";
@@ -42,12 +43,106 @@ function Toast({ title, message, tone, icon, onClose, leaving, dismissLabel: dis
           title && /* @__PURE__ */ jsx("div", { className: "uix-toast__title", children: title }),
           message && /* @__PURE__ */ jsx("div", { className: "uix-toast__msg", children: message })
         ] }),
-        onClose && /* @__PURE__ */ jsx("button", { className: "uix-toast__close", onClick: handleClose, "aria-label": dismissLabel, children: "\xD7" })
+        action != null && /* @__PURE__ */ jsx("div", { className: "uix-toast__action-slot", children: action }),
+        onClose && /* @__PURE__ */ jsx("button", { type: "button", className: "uix-toast__close", onClick: handleClose, "aria-label": dismissLabel, children: "\xD7" })
       ]
     }
   );
 }
-function Toaster({ children, regionLabel: regionLabelProp, className, ...props }) {
+const KIND_TONE = {
+  success: "success",
+  error: "danger",
+  warning: "warning",
+  info: "info",
+  loading: "info",
+  default: void 0
+};
+const svg = (path) => /* @__PURE__ */ jsx("svg", { viewBox: "0 0 20 20", fill: "none", stroke: "currentColor", strokeWidth: 1.8, strokeLinecap: "round", strokeLinejoin: "round", children: path });
+const KIND_GLYPH = {
+  success: svg(/* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("circle", { cx: "10", cy: "10", r: "7.25" }),
+    /* @__PURE__ */ jsx("path", { d: "M6.75 10.25l2.25 2.25 4.25-4.75" })
+  ] })),
+  error: svg(/* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("circle", { cx: "10", cy: "10", r: "7.25" }),
+    /* @__PURE__ */ jsx("path", { d: "M10 6.25v4.5M10 13.5v.25" })
+  ] })),
+  warning: svg(/* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("path", { d: "M10 3.25l7.25 13H2.75z" }),
+    /* @__PURE__ */ jsx("path", { d: "M10 8.25v3.5M10 14v.25" })
+  ] })),
+  info: svg(/* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("circle", { cx: "10", cy: "10", r: "7.25" }),
+    /* @__PURE__ */ jsx("path", { d: "M10 9.25v4.5M10 6.5v.25" })
+  ] })),
+  loading: /* @__PURE__ */ jsx("span", { className: "uix-spinner uix-toast__spinner" })
+};
+function StoreToast({ record, store }) {
+  const action = record.action && /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      className: "uix-toast__action",
+      onClick: () => {
+        record.action.onClick();
+        store.dismiss(record.id, "action");
+      },
+      children: record.action.label
+    }
+  );
+  return /* @__PURE__ */ jsx(
+    Toast,
+    {
+      "data-toast-id": record.id,
+      tone: KIND_TONE[record.kind],
+      icon: record.icon ?? KIND_GLYPH[record.kind],
+      title: record.message,
+      message: record.description,
+      action,
+      leaving: record.leaving,
+      "aria-busy": record.kind === "loading" || void 0,
+      onClose: () => store.dismiss(record.id, "close")
+    }
+  );
+}
+function useToastTimers(store, visible, paused) {
+  const timers = useRef(/* @__PURE__ */ new Map());
+  useEffect(() => {
+    const now = Date.now();
+    const map = timers.current;
+    const live = new Map(visible.filter((r) => !r.leaving && r.duration != null).map((r) => [r.id, r]));
+    for (const [id, timer] of map) {
+      const record = live.get(id);
+      if (!record || record.version !== timer.version) {
+        if (timer.handle != null) clearTimeout(timer.handle);
+        map.delete(id);
+      }
+    }
+    for (const record of live.values()) {
+      let timer = map.get(record.id);
+      if (!timer) {
+        timer = { version: record.version, remaining: record.duration, start: now };
+        map.set(record.id, timer);
+      }
+      if (paused) {
+        if (timer.handle != null) {
+          clearTimeout(timer.handle);
+          timer.handle = void 0;
+          timer.remaining -= now - timer.start;
+        }
+      } else if (timer.handle == null) {
+        timer.start = now;
+        const id = record.id;
+        timer.handle = window.setTimeout(() => store.dismiss(id, "timeout"), Math.max(0, timer.remaining));
+      }
+    }
+  });
+  useEffect(() => () => {
+    for (const timer of timers.current.values()) if (timer.handle != null) clearTimeout(timer.handle);
+    timers.current.clear();
+  }, []);
+}
+function Toaster({ children, regionLabel: regionLabelProp, store = defaultToast.store, limit = 3, position = "bottom-end", className, onMouseEnter, onMouseLeave, onFocus, onBlur, onKeyDown, ...props }) {
   const uixLabels = useUixLabels();
   const regionLabel = regionLabelProp ?? uixLabels.toaster?.region ?? "Notifications";
   const [announced, setAnnounced] = useState("");
@@ -61,10 +156,59 @@ function Toaster({ children, regionLabel: regionLabelProp, className, ...props }
     if (clearTimer.current != null) clearTimeout(clearTimer.current);
   }, []);
   const ctx = useMemo(() => ({ announce }), [announce]);
-  return /* @__PURE__ */ jsx(ToasterContext.Provider, { value: ctx, children: /* @__PURE__ */ jsxs("div", { className: cx("uix-toaster", className), role: "region", "aria-label": regionLabel, ...props, children: [
-    /* @__PURE__ */ jsx("span", { className: "uix-visually-hidden", role: "status", "aria-live": "polite", children: announced }),
-    children
-  ] }) });
+  const records = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+  const visible = useMemo(() => records.slice(-Math.max(1, limit)), [records, limit]);
+  const [hovered, setHovered] = useState(false);
+  const [focused, setFocused] = useState(false);
+  const [hidden, setHidden] = useState(false);
+  useEffect(() => {
+    const sync = () => setHidden(document.visibilityState === "hidden");
+    sync();
+    document.addEventListener("visibilitychange", sync);
+    return () => document.removeEventListener("visibilitychange", sync);
+  }, []);
+  useToastTimers(store, visible, hovered || focused || hidden);
+  const handleKeyDown = (event) => {
+    onKeyDown?.(event);
+    if (event.defaultPrevented || event.key !== "Escape") return;
+    const id = event.target.closest("[data-toast-id]")?.dataset.toastId;
+    if (!id) return;
+    event.preventDefault();
+    event.stopPropagation();
+    store.dismiss(id, "close");
+  };
+  return /* @__PURE__ */ jsx(ToasterContext.Provider, { value: ctx, children: /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cx("uix-toaster", className),
+      role: "region",
+      "aria-label": regionLabel,
+      "data-position": position === "bottom-end" ? void 0 : position,
+      onMouseEnter: (e) => {
+        setHovered(true);
+        onMouseEnter?.(e);
+      },
+      onMouseLeave: (e) => {
+        setHovered(false);
+        onMouseLeave?.(e);
+      },
+      onFocus: (e) => {
+        setFocused(true);
+        onFocus?.(e);
+      },
+      onBlur: (e) => {
+        if (!e.currentTarget.contains(e.relatedTarget)) setFocused(false);
+        onBlur?.(e);
+      },
+      onKeyDown: handleKeyDown,
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx("span", { className: "uix-visually-hidden", role: "status", "aria-live": "polite", children: announced }),
+        children,
+        visible.map((record) => /* @__PURE__ */ jsx(StoreToast, { record, store }, `${record.id}:${record.kind}`))
+      ]
+    }
+  ) });
 }
 export {
   Toast,