@tensor_1/react 2.35.0 → 2.37.0

package/dist/components/SearchSuggest.d.ts

@@ -50,6 +50,17 @@ interface SearchSuggestProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onCha
     empty?: ReactNode;
     /** Shown instead of the empty state when suggestions could not be loaded. */
     error?: ReactNode;
+    /**
+     * Shown in the open list when there is nothing else to show there: no options, nothing
+     * loading, no error and no empty state. For a search that has not started yet, e.g.
+     * "Type at least 2 characters." (HAR-1648).
+     */
+    idle?: ReactNode;
+    /**
+     * A line under the options that is not an option: arrow keys skip it and it cannot be
+     * chosen. For "More matches. Keep typing to narrow the search." when the results were cut off.
+     */
+    note?: ReactNode;
     /** A keyboard hint shown in the empty, unfocused field, e.g. "/". */
     shortcutHint?: string;
     /** Accessible name of the clear button (default "Clear search"). */
@@ -86,6 +97,6 @@ interface SearchSuggestProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onCha
  * (`aria-activedescendant`), Enter opens it (the first row when none is active), Escape closes the
  * list and a second Escape clears the text.
  */
-declare function SearchSuggest({ value, onValueChange, options, onSelect, label, placeholder, highlight, heading, headingAction, footer, loading, loadingLabel, empty, error, shortcutHint, clearLabel: clearLabelProp, status, size, open: openProp, strategy, onOpenChange, inputRef, autoFocus, name, inputId, inputDescribedBy, className, onBlur, ...props }: SearchSuggestProps): react.JSX.Element;
+declare function SearchSuggest({ value, onValueChange, options, onSelect, label, placeholder, highlight, heading, headingAction, footer, loading, loadingLabel, empty, idle, note, error, shortcutHint, clearLabel: clearLabelProp, status, size, open: openProp, strategy, onOpenChange, inputRef, autoFocus, name, inputId, inputDescribedBy, className, onBlur, ...props }: SearchSuggestProps): react.JSX.Element;
 
 export { SearchSuggest, type SearchSuggestAction, type SearchSuggestOption, type SearchSuggestProps };

package/dist/components/SearchSuggest.js

@@ -32,6 +32,8 @@ function SearchSuggest({
   loading = false,
   loadingLabel,
   empty,
+  idle,
+  note,
   error,
   shortcutHint,
   clearLabel: clearLabelProp,
@@ -72,7 +74,8 @@ function SearchSuggest({
   const hasText = value.trim().length > 0;
   const showEmpty = hasText && !loading && !error && options.length === 0 && empty != null;
   const showLoading = loading && options.length === 0;
-  const visible = open && (itemCount > 0 || showLoading || showEmpty || error != null);
+  const showIdle = idle != null && itemCount === 0 && !loading && error == null && !showEmpty;
+  const visible = open && (itemCount > 0 || showLoading || showEmpty || showIdle || error != null);
   const optionId = (index) => `${id}-option-${index}`;
   useEffect(() => {
     if (!visible || active < 0) return;
@@ -294,7 +297,9 @@ function SearchSuggest({
             loadingLabel && /* @__PURE__ */ jsx("span", { children: loadingLabel })
           ] }),
           error != null && options.length === 0 && !loading && /* @__PURE__ */ jsx("div", { className: "uix-search-suggest__state", children: error }),
-          showEmpty && /* @__PURE__ */ jsx("div", { className: "uix-search-suggest__state", children: empty })
+          showEmpty && /* @__PURE__ */ jsx("div", { className: "uix-search-suggest__state", children: empty }),
+          showIdle && /* @__PURE__ */ jsx("div", { className: "uix-search-suggest__state", children: idle }),
+          note != null && options.length > 0 && /* @__PURE__ */ jsx("div", { className: "uix-search-suggest__note", children: note })
         ] }),
         /* @__PURE__ */ jsx("span", { className: "uix-visually-hidden", role: "status", "aria-live": "polite", children: status ?? "" })
       ]

package/dist/components/Tree.d.ts

@@ -8,7 +8,23 @@ interface TreeNodeData {
     typeaheadLabel?: string;
     icon?: ReactNode;
     children?: TreeNodeData[];
+    /**
+     * The node can be expanded although its `children` are not known yet (HAR-1382). With
+     * `Tree loadChildren`, expanding it loads them; until then it shows a loading row, and an
+     * error row with Retry when the load failed.
+     */
+    hasChildren?: boolean;
+}
+/** The words of a tree that loads children on expand (HAR-1382). */
+interface TreeLabels {
+    /** The row under a node whose children are loading. */
+    loading: string;
+    /** The row under a node whose children could not be loaded. */
+    error: string;
+    /** The action in that row. Enter, Space or a click on the row runs it. */
+    retry: string;
 }
+declare const DEFAULT_TREE_LABELS: TreeLabels;
 interface TreeNodeProps {
     node: TreeNodeData;
     expanded: Set<string>;
@@ -21,6 +37,8 @@ interface TreeNodeProps {
     level?: number;
     /** Whether a click on the row itself toggles a branch (see {@link TreeProps.toggleOnRowClick}). */
     rowToggles?: boolean;
+    /** Ids of nodes whose children are loading (`aria-busy`). */
+    busy?: ReadonlySet<string>;
 }
 interface TreeProps extends Omit<HTMLAttributes<HTMLUListElement>, 'onSelect' | 'onChange'> {
     nodes: TreeNodeData[];
@@ -46,7 +64,17 @@ interface TreeProps extends Omit<HTMLAttributes<HTMLUListElement>, 'onSelect' |
      * where a row click only selects and the chevron toggles. Enter/Space still does both.
      */
     toggleOnRowClick?: boolean;
+    /**
+     * Loads the children of a node that has `hasChildren` and no `children` yet, the first time
+     * it is expanded (HAR-1382; an org chart, a CMDB hierarchy). While it runs the node is
+     * `aria-busy` and shows a loading row; a rejection shows an error row whose Enter, Space or
+     * click retries. The result is kept for the life of the tree; a node that later arrives with
+     * its own `children` uses those.
+     */
+    loadChildren?: (node: TreeNodeData) => Promise<TreeNodeData[]>;
+    /** Words of the loading and error rows. Default: `UixLabelsProvider` `tree`, then English. */
+    labels?: Partial<TreeLabels>;
 }
-declare function Tree({ nodes, expanded: controlledExpanded, defaultExpanded, selected, onToggle, onSelect, virtualize, rowHeight, maxHeight, toggleOnRowClick, className, ...props }: TreeProps): react.JSX.Element;
+declare function Tree({ nodes: nodesProp, expanded: controlledExpanded, defaultExpanded, selected, onToggle, onSelect: onSelectProp, virtualize, rowHeight, maxHeight, toggleOnRowClick, loadChildren, labels: labelOverrides, className, ...props }: TreeProps): react.JSX.Element;
 
-export { Tree, type TreeNodeData, type TreeNodeProps, type TreeProps };
+export { DEFAULT_TREE_LABELS, Tree, type TreeLabels, type TreeNodeData, type TreeNodeProps, type TreeProps };

package/dist/components/Tree.js

@@ -1,11 +1,21 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
 import { cx } from "../cx.js";
+import { useUixLabels } from "../labels-context.js";
 import { flattenTree, treeNav } from "../tree-model.js";
 import { virtualWindow, shouldVirtualize } from "../table-engine.js";
 const ChevronIcon = () => /* @__PURE__ */ jsx("svg", { viewBox: "0 0 12 12", fill: "none", stroke: "currentColor", strokeWidth: 1.5, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: /* @__PURE__ */ jsx("path", { d: "M2 4l4 4 4-4" }) });
-function TreeNode({ node, expanded, selected, selectable, tabbableId, onToggle, onSelect, onFocusNode, level = 1, rowToggles = true }) {
+const DEFAULT_TREE_LABELS = {
+  loading: "Loading\u2026",
+  error: "Could not load.",
+  retry: "Retry"
+};
+const LOADING = "::uix-loading";
+const FAILED = "::uix-error";
+const syntheticOf = (id) => id.endsWith(LOADING) ? { parent: id.slice(0, -LOADING.length), kind: "loading" } : id.endsWith(FAILED) ? { parent: id.slice(0, -FAILED.length), kind: "error" } : null;
+const Ring = () => /* @__PURE__ */ jsx("span", { className: "uix-spinner uix-spinner--sm", "aria-hidden": "true" });
+function TreeNode({ node, expanded, selected, selectable, tabbableId, onToggle, onSelect, onFocusNode, level = 1, rowToggles = true, busy }) {
   const hasChildren = Array.isArray(node.children) && node.children.length > 0;
   const isExpanded = expanded.has(node.id);
   return /* @__PURE__ */ jsxs(
@@ -14,7 +24,8 @@ function TreeNode({ node, expanded, selected, selectable, tabbableId, onToggle,
       role: "treeitem",
       "aria-level": level,
       "aria-expanded": hasChildren ? isExpanded : void 0,
-      "aria-selected": selectable ? selected === node.id : void 0,
+      "aria-selected": selectable && !syntheticOf(node.id) ? selected === node.id : void 0,
+      "aria-busy": busy?.has(node.id) || void 0,
       "data-id": node.id,
       tabIndex: tabbableId === node.id ? 0 : -1,
       className: "uix-tree__item",
@@ -64,7 +75,8 @@ function TreeNode({ node, expanded, selected, selectable, tabbableId, onToggle,
             onSelect,
             onFocusNode,
             level: level + 1,
-            rowToggles
+            rowToggles,
+            busy
           },
           child.id
         )) })
@@ -73,16 +85,18 @@ function TreeNode({ node, expanded, selected, selectable, tabbableId, onToggle,
   );
 }
 function Tree({
-  nodes,
+  nodes: nodesProp,
   expanded: controlledExpanded,
   defaultExpanded,
   selected,
   onToggle,
-  onSelect,
+  onSelect: onSelectProp,
   virtualize,
   rowHeight = 32,
   maxHeight = 384,
   toggleOnRowClick,
+  loadChildren,
+  labels: labelOverrides,
   className,
   ...props
 }) {
@@ -90,8 +104,111 @@ function Tree({
   const expanded = controlledExpanded ?? internalExpanded;
   const rootRef = useRef(null);
   const [focusedId, setFocusedId] = useState(void 0);
-  const selectable = selected !== void 0 || onSelect != null;
+  const selectable = selected !== void 0 || onSelectProp != null;
   const rowToggles = toggleOnRowClick ?? !selectable;
+  const labels = { ...DEFAULT_TREE_LABELS, ...useUixLabels().tree, ...labelOverrides };
+  const treeId = useId();
+  const [loaded, setLoaded] = useState(() => /* @__PURE__ */ new Map());
+  const [failed, setFailed] = useState(() => /* @__PURE__ */ new Set());
+  const [loading, setLoading] = useState(() => /* @__PURE__ */ new Set());
+  const inFlight = useRef(/* @__PURE__ */ new Set());
+  const loadRef = useRef(loadChildren);
+  loadRef.current = loadChildren;
+  const refocus = useRef(null);
+  const nodes = useMemo(() => {
+    const row = (parent, kind) => ({
+      id: parent.id + (kind === "error" ? FAILED : LOADING),
+      typeaheadLabel: "",
+      label: kind === "error" ? /* @__PURE__ */ jsxs("span", { className: "uix-tree__status uix-tree__status--error", children: [
+        labels.error,
+        " ",
+        /* @__PURE__ */ jsx("span", { className: "uix-tree__retry", children: labels.retry })
+      ] }) : /* @__PURE__ */ jsxs("span", { className: "uix-tree__status", children: [
+        /* @__PURE__ */ jsx(Ring, {}),
+        labels.loading
+      ] })
+    });
+    const decorate = (list) => list.map((node) => {
+      const known = node.children ?? loaded.get(node.id);
+      if (known) return { ...node, children: decorate(known) };
+      if (!node.hasChildren) return node;
+      return { ...node, children: [row(node, failed.has(node.id) ? "error" : "loading")] };
+    });
+    return loadChildren || nodesProp.some(function lazy(n) {
+      return !!n.hasChildren || !!n.children?.some(lazy);
+    }) ? decorate(nodesProp) : nodesProp;
+  }, [nodesProp, loaded, failed, loadChildren, labels.error, labels.retry, labels.loading]);
+  const load = useCallback((node) => {
+    const run = loadRef.current;
+    if (!run || inFlight.current.has(node.id)) return;
+    inFlight.current.add(node.id);
+    setFailed((prev) => {
+      if (!prev.has(node.id)) return prev;
+      const next = new Set(prev);
+      next.delete(node.id);
+      return next;
+    });
+    setLoading((prev) => new Set(prev).add(node.id));
+    const settle = (apply, focusNext) => {
+      inFlight.current.delete(node.id);
+      const active = typeof document !== "undefined" ? document.activeElement : null;
+      if (active?.dataset?.id === node.id + LOADING || active?.dataset?.id === node.id + FAILED) refocus.current = focusNext;
+      setLoading((prev) => {
+        const next = new Set(prev);
+        next.delete(node.id);
+        return next;
+      });
+      apply();
+    };
+    run(node).then(
+      (children) => settle(() => setLoaded((prev) => new Map(prev).set(node.id, children)), node.id),
+      () => settle(() => setFailed((prev) => new Set(prev).add(node.id)), node.id + FAILED)
+    );
+  }, []);
+  useEffect(() => {
+    if (!loadChildren) return;
+    const visit = (list) => {
+      for (const node of list) {
+        const known = node.children ?? loaded.get(node.id);
+        if (known) visit(known);
+        else if (node.hasChildren && expanded.has(node.id) && !failed.has(node.id)) load(node);
+      }
+    };
+    visit(nodesProp);
+  }, [nodesProp, expanded, loaded, failed, loadChildren, load]);
+  useEffect(() => {
+    const id = refocus.current;
+    if (id == null) return;
+    refocus.current = null;
+    setFocusedId(id);
+    document.querySelector(`[data-uix-tree="${CSS.escape(treeId)}"] [role="treeitem"][data-id="${CSS.escape(id)}"]`)?.focus();
+  }, [loaded, failed, loading, treeId]);
+  const findNode = (id, list = nodesProp) => {
+    for (const node of list) {
+      if (node.id === id) return node;
+      const inside = findNode(id, node.children ?? loaded.get(node.id) ?? []);
+      if (inside) return inside;
+    }
+    return void 0;
+  };
+  const handleSelect = (id) => {
+    const synthetic = syntheticOf(id);
+    if (!synthetic) {
+      onSelectProp?.(id);
+      return;
+    }
+    if (synthetic.kind !== "error") return;
+    const parent = findNode(synthetic.parent);
+    if (!parent) return;
+    refocus.current = parent.id + LOADING;
+    setFailed((prev) => {
+      const next = new Set(prev);
+      next.delete(parent.id);
+      return next;
+    });
+    load(parent);
+  };
+  const onSelect = selectable || loadChildren ? handleSelect : void 0;
   const handleToggle = useCallback((id) => {
     if (!controlledExpanded) {
       setInternalExpanded((prev) => {
@@ -121,6 +238,8 @@ function Tree({
         focusedId,
         setFocusedId,
         rowToggles,
+        busy: loading,
+        treeId,
         className,
         ...props
       }
@@ -185,7 +304,7 @@ function Tree({
         break;
     }
   };
-  return /* @__PURE__ */ jsx("ul", { ref: rootRef, className: cx("uix-tree", className), role: "tree", onKeyDown, ...props, children: nodes.map((node) => /* @__PURE__ */ jsx(
+  return /* @__PURE__ */ jsx("ul", { ref: rootRef, className: cx("uix-tree", className), role: "tree", "data-uix-tree": treeId, onKeyDown, ...props, children: nodes.map((node) => /* @__PURE__ */ jsx(
     TreeNode,
     {
       node,
@@ -197,7 +316,8 @@ function Tree({
       onSelect,
       onFocusNode: setFocusedId,
       level: 1,
-      rowToggles
+      rowToggles,
+      busy: loading
     },
     node.id
   )) });
@@ -214,6 +334,8 @@ function VirtualTreeView({
   focusedId,
   setFocusedId,
   rowToggles,
+  busy,
+  treeId,
   className,
   ...props
 }) {
@@ -273,6 +395,7 @@ function VirtualTreeView({
       ref: scrollRef,
       className: cx("uix-tree", "uix-tree--virtual", className),
       role: "tree",
+      "data-uix-tree": treeId,
       tabIndex: -1,
       style: { maxHeight, overflow: "auto" },
       onScroll: (e) => setScrollTop(e.currentTarget.scrollTop),
@@ -299,7 +422,8 @@ function VirtualTreeView({
               "aria-setsize": f.setsize,
               "aria-posinset": f.posinset,
               "aria-expanded": f.hasChildren ? f.isExpanded : void 0,
-              "aria-selected": selectable ? selected === f.node.id : void 0,
+              "aria-selected": selectable && !syntheticOf(f.node.id) ? selected === f.node.id : void 0,
+              "aria-busy": busy.has(f.node.id) || void 0,
               "data-id": f.node.id,
               tabIndex: tabbableId === f.node.id || !windowHasTabbable && i === 0 ? 0 : -1,
               className: "uix-tree__item",
@@ -346,5 +470,6 @@ function VirtualTreeView({
   );
 }
 export {
+  DEFAULT_TREE_LABELS,
   Tree
 };

package/dist/date-field-model.d.ts

@@ -0,0 +1,40 @@
+/**
+ * uix date-field model — pure helpers behind `DatePicker`, `DateTimePicker` and the field mode
+ * of `DateRangePicker` (HAR-1383): how a locale orders day / month / year, how a typed date is
+ * read, and how a date-time value is split and joined. No DOM, no React, no runtime import, so
+ * the unit test loads this file directly (date-field-model.test.mjs).
+ *
+ * A date is an ISO calendar date, `YYYY-MM-DD`. A date-time is a wall-clock value,
+ * `YYYY-MM-DDTHH:mm`, as `<input type="datetime-local">` holds it: no zone, no offset. Which
+ * zone that wall clock is in is the product's to know and to show.
+ */
+type DatePart = 'day' | 'month' | 'year';
+/** Whether `YYYY-MM-DD` names a real calendar day (2026-02-30 does not). */
+declare function isValidDateKey(value: string): boolean;
+/**
+ * The order in which `locale` writes a numeric date: `['day', 'month', 'year']` for de or
+ * en-GB, `['month', 'day', 'year']` for en-US, `['year', 'month', 'day']` for sv or ja.
+ */
+declare function dateOrder(locale?: string | readonly string[]): DatePart[];
+/** A hint for the field, e.g. `DD.MM.YYYY`, `MM/DD/YYYY`, `YYYY-MM-DD`, in the locale's own shape. */
+declare function datePattern(locale?: string | readonly string[]): string;
+/** A numeric date in the locale's shape: 22.11.2026, 11/22/2026, 2026-11-22. */
+declare function formatDateKey(value: string, locale?: string | readonly string[]): string;
+/**
+ * Read a typed date. ISO `YYYY-MM-DD` is always accepted; otherwise three numbers separated by
+ * `.`, `/`, `-` or spaces are read in the locale's order (so `3.4.2026` is 3 April in German and
+ * `3/4/2026` is 4 March in en-US). A two-digit year means 2000–2099. Returns the ISO date, or
+ * `null` when the text is not a real date.
+ */
+declare function parseDateInput(text: string, locale?: string | readonly string[]): string | null;
+/** Split `YYYY-MM-DDTHH:mm` (seconds are dropped) into its date and time. */
+declare function splitDateTime(value: string | null | undefined): {
+    date: string | null;
+    time: string;
+};
+/** Join a date and a time into `YYYY-MM-DDTHH:mm`; without a date there is no value. */
+declare function joinDateTime(date: string | null, time: string, fallbackTime?: string): string | null;
+/** The short name of `timeZone` on that day ("CEST", "GMT+2"), for the label beside a time. */
+declare function timeZoneName(timeZone: string, date: string | null, locale?: string | readonly string[]): string;
+
+export { type DatePart, dateOrder, datePattern, formatDateKey, isValidDateKey, joinDateTime, parseDateInput, splitDateTime, timeZoneName };

package/dist/date-field-model.js

@@ -0,0 +1,79 @@
+const pad = (n, width = 2) => String(n).padStart(width, "0");
+function isValidDateKey(value) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) return false;
+  const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  if (month < 1 || month > 12 || day < 1) return false;
+  return day <= new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+function dateOrder(locale) {
+  try {
+    const parts = new Intl.DateTimeFormat(locale, { year: "numeric", month: "2-digit", day: "2-digit", timeZone: "UTC" }).formatToParts(new Date(Date.UTC(2026, 10, 22)));
+    const order = parts.map((part) => part.type).filter((type) => type === "day" || type === "month" || type === "year");
+    if (order.length === 3 && new Set(order).size === 3) return order;
+  } catch {
+  }
+  return ["year", "month", "day"];
+}
+function datePattern(locale) {
+  const letters = { day: "DD", month: "MM", year: "YYYY" };
+  try {
+    return new Intl.DateTimeFormat(locale, { year: "numeric", month: "2-digit", day: "2-digit", timeZone: "UTC" }).formatToParts(new Date(Date.UTC(2026, 10, 22))).map((part) => part.type === "day" || part.type === "month" || part.type === "year" ? letters[part.type] : part.value).join("");
+  } catch {
+    return "YYYY-MM-DD";
+  }
+}
+function formatDateKey(value, locale) {
+  if (!isValidDateKey(value)) return value;
+  return new Intl.DateTimeFormat(locale, { year: "numeric", month: "2-digit", day: "2-digit", timeZone: "UTC" }).format(/* @__PURE__ */ new Date(`${value}T00:00:00Z`));
+}
+function parseDateInput(text, locale) {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  if (/^\d{4}-\d{1,2}-\d{1,2}$/.test(trimmed)) {
+    const [year2, month, day] = trimmed.split("-").map(Number);
+    const iso2 = `${pad(year2, 4)}-${pad(month)}-${pad(day)}`;
+    return isValidDateKey(iso2) ? iso2 : null;
+  }
+  const numbers = trimmed.split(/[.\/\-\s]+/).filter(Boolean);
+  if (numbers.length !== 3 || numbers.some((n) => !/^\d{1,4}$/.test(n))) return null;
+  const order = dateOrder(locale);
+  const read = {};
+  order.forEach((part, index) => {
+    read[part] = Number(numbers[index]);
+  });
+  let year = read.year;
+  const yearText = numbers[order.indexOf("year")];
+  if (yearText.length <= 2) year += 2e3;
+  else if (yearText.length !== 4) return null;
+  const iso = `${pad(year, 4)}-${pad(read.month)}-${pad(read.day)}`;
+  return isValidDateKey(iso) ? iso : null;
+}
+function splitDateTime(value) {
+  const match = value ? /^(\d{4}-\d{2}-\d{2})(?:T(\d{2}:\d{2}))?/.exec(value) : null;
+  if (!match || !isValidDateKey(match[1])) return { date: null, time: "" };
+  return { date: match[1], time: match[2] ?? "" };
+}
+function joinDateTime(date, time, fallbackTime = "00:00") {
+  if (!date) return null;
+  return `${date}T${/^\d{2}:\d{2}/.test(time) ? time.slice(0, 5) : fallbackTime}`;
+}
+function timeZoneName(timeZone, date, locale) {
+  try {
+    const at = date && isValidDateKey(date) ? /* @__PURE__ */ new Date(`${date}T12:00:00Z`) : /* @__PURE__ */ new Date();
+    const part = new Intl.DateTimeFormat(locale, { timeZone, timeZoneName: "short" }).formatToParts(at).find((p) => p.type === "timeZoneName");
+    return part?.value ?? timeZone;
+  } catch {
+    return timeZone;
+  }
+}
+export {
+  dateOrder,
+  datePattern,
+  formatDateKey,
+  isValidDateKey,
+  joinDateTime,
+  parseDateInput,
+  splitDateTime,
+  timeZoneName
+};

package/dist/hooks/usePrinting.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `true` while the page is printed, or shown with print media.
+ *
+ * A view that mounts only the rows near its viewport uses this to mount all of them for the
+ * paper. The browser lays the page out for print as soon as the `beforeprint` handlers return,
+ * so the state is committed inside the event (`flushSync`), not in a later task.
+ *
+ * It cannot answer in time when `window.print()` is called from inside a React effect or
+ * lifecycle method, on mount or later: React commits the change after the effect, which is
+ * after the page was laid out. A page that prints itself that way turns windowing off through
+ * the component's own prop instead, or calls `print()` from an event handler or a timer.
+ */
+declare function usePrinting(enabled?: boolean): boolean;
+
+export { usePrinting };

package/dist/hooks/usePrinting.js

@@ -0,0 +1,29 @@
+"use client";
+import { useEffect, useState } from "react";
+import { flushSync } from "react-dom";
+function usePrinting(enabled = true) {
+  const [printing, setPrinting] = useState(false);
+  useEffect(() => {
+    if (!enabled || typeof window === "undefined") return void 0;
+    const set = (next) => {
+      flushSync(() => setPrinting(next));
+    };
+    const before = () => set(true);
+    const after = () => set(false);
+    const query = typeof window.matchMedia === "function" ? window.matchMedia("print") : null;
+    const changed = (event) => set(event.matches);
+    window.addEventListener("beforeprint", before);
+    window.addEventListener("afterprint", after);
+    query?.addEventListener?.("change", changed);
+    setPrinting(Boolean(query?.matches));
+    return () => {
+      window.removeEventListener("beforeprint", before);
+      window.removeEventListener("afterprint", after);
+      query?.removeEventListener?.("change", changed);
+    };
+  }, [enabled]);
+  return enabled && printing;
+}
+export {
+  usePrinting
+};