@tensor_1/react 2.23.0 → 2.25.0

package/README.md

@@ -205,4 +205,41 @@ Radial mode still shortens long labels to fit its ring, but every node carries i
 <CopyButton value={email} label={t('copyEmail')} copiedLabel={t('copied')} failedLabel={t('copyFailed')} />
 ```
 
+### DiffViewer words and control size
+
+- **Every word is a label.** `labels` (a `Partial<DiffViewerLabels>`, English defaults in `DEFAULT_DIFF_VIEWER_LABELS`) covers the version names, group titles, the summary, the live progress text, and the action buttons.
+- **Each action is named for its entry.** The visible words come from `acceptIncoming` / `keepCurrent` / `markPending`. The accessible names come from `acceptIncomingFor` / `keepCurrentFor` / `markPendingFor`, e.g. "Accept incoming for $.limit". Each entry's three buttons sit in a group named by `resolve`. When you translate a name, keep the visible word inside it, so people using speech input can say what they see (WCAG 2.5.3).
+- **`controlSize`** sets the height of the action buttons and the entry rows. `sm` (the default) is the compact 28px kit size. `md` follows `--uix-control-h`, so a theme with 60px controls gets 60px actions. `lg` is 44px.
+
+```tsx
+<DiffViewer
+  base={published} current={draft} incoming={remote}
+  controlSize="md"
+  labels={{
+    acceptIncoming: t('acceptIncoming'), acceptIncomingFor: t('acceptIncomingFor'), // 'Prihvati dolazno za {path}'
+    keepCurrent: t('keepCurrent'), keepCurrentFor: t('keepCurrentFor'),
+    markPending: t('markPending'), markPendingFor: t('markPendingFor'),
+    resolve: t('resolve'), /* …the rest of DiffViewerLabels */
+  }}
+  onResolutionChange={record}
+/>
+```
+
 Ships **ESM + CJS + types**, with per-file `"use client"` so it's safe under React Server Components. Part of the **[UIx v2 styleguide](https://github.com/COx-ORG-H/UIx)**.
+
+### InfoTip and `help` slots
+
+A small ? next to a title or label opens a plain-text explanation. Use it for what a page, section or field *means*. Keep instructions the user needs while typing ("8+ characters", "ISO date") visible in `hint`.
+
+```tsx
+<PageHeader title={t('incidents')} help={t('incidents.help')} helpLabel={t('aboutIncidents')} />
+<Card title="Open work" titleAs="h2" help={help.openWork}>…</Card>
+<SectionHead title="Latest news" help={help.news} />
+<Field label="Impact" required help={help.impact}><Input /></Field>
+<InfoTip content={text} label="About: Impact" />
+```
+
+- **`help?: string | null`** on `PageHeader`, `Card`, `SectionHead` and `Field`. Empty, whitespace-only or `null` renders nothing, so pass the resolved string without a guard. Blank lines become paragraphs. The text is always plain, never HTML.
+- **`helpLabel`** is the ? button's accessible name. It defaults to `"About: <title>"` (English), so pass a translated one.
+- **Placement:** the ? is a fixed 9 px glyph, superscript at the top right of the title or label, whatever the text size. It sits beside the heading or `<label>`, never inside it, so the heading's name stays the title and clicking a field label still focuses the input.
+- **Behaviour:** hover opens it after about 300 ms, keyboard focus opens it at once, and a click or tap keeps it open. Esc closes it and keeps focus on the ?, and a press outside also closes it. The panel is the button's `aria-describedby`, so screen readers announce it on focus. It uses `popover="manual"`, so it never closes another open popover.

package/dist/components/Card.d.ts

@@ -6,11 +6,18 @@ interface CardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
     /** Element for the title — pick a real heading to slot the card into the page outline (UIX-A11Y-4). Default `div` keeps legacy rendering. */
     titleAs?: 'h2' | 'h3' | 'h4' | 'div';
     subtitle?: ReactNode;
+    /**
+     * Plain-text help behind a ? button after the title. Blank lines separate paragraphs;
+     * empty, whitespace-only or `null` renders no button.
+     */
+    help?: string | null;
+    /** Accessible name of the ? button. Default `"About: <title>"` when title is text; pass a localised one. */
+    helpLabel?: string;
     headerAction?: ReactNode;
     footer?: ReactNode;
     children?: ReactNode;
 }
-declare function Card({ title, titleAs: TitleTag, subtitle, headerAction, footer, children, className, ...props }: CardProps): react.JSX.Element;
+declare function Card({ title, titleAs: TitleTag, subtitle, help, helpLabel, headerAction, footer, children, className, ...props }: CardProps): react.JSX.Element;
 interface CardLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'title'> {
     title?: ReactNode;
     subtitle?: ReactNode;

package/dist/components/Card.js

@@ -1,11 +1,17 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { cx } from "../cx.js";
-function Card({ title, titleAs: TitleTag = "div", subtitle, headerAction, footer, children, className, ...props }) {
+import { InfoTip } from "./InfoTip.js";
+import { hasHelp, helpLabelFor } from "../info-tip-model.js";
+function Card({ title, titleAs: TitleTag = "div", subtitle, help, helpLabel, headerAction, footer, children, className, ...props }) {
   const hasHeader = title != null || subtitle != null || headerAction != null;
+  const heading = title ? /* @__PURE__ */ jsx(TitleTag, { className: "uix-card__title", children: title }) : null;
   return /* @__PURE__ */ jsxs("div", { className: cx("uix-card", className), ...props, children: [
     hasHeader && /* @__PURE__ */ jsxs("div", { className: "uix-card__header", children: [
       /* @__PURE__ */ jsxs("div", { style: { flex: 1 }, children: [
-        title && /* @__PURE__ */ jsx(TitleTag, { className: "uix-card__title", children: title }),
+        heading && hasHelp(help) ? /* @__PURE__ */ jsxs("div", { className: "uix-card__title-row", children: [
+          heading,
+          /* @__PURE__ */ jsx(InfoTip, { content: help, label: helpLabel ?? helpLabelFor(title) })
+        ] }) : heading,
         subtitle && /* @__PURE__ */ jsx("div", { className: "uix-card__subtitle", children: subtitle })
       ] }),
       headerAction

package/dist/components/DiffViewer.d.ts

@@ -6,6 +6,11 @@ import { DiffEntry, DiffResolution } from '../diff-model.js';
  * Every word the diff viewer renders (TENSOR RX-125, UIX-12). `base` / `current` /
  * `incoming` keep their meaning from before; `{path}`, `{version}`, `{resolved}` and
  * `{total}` are placeholders.
+ *
+ * `acceptIncomingFor` / `keepCurrentFor` / `markPendingFor` are the accessible names of
+ * the three action buttons, so a screen reader hears which entry each one resolves. Keep
+ * the visible word inside the translated name (WCAG 2.5.3 Label in Name): speech-input
+ * users say what they see.
  */
 interface DiffViewerLabels {
     base: string;
@@ -26,6 +31,9 @@ interface DiffViewerLabels {
     acceptIncoming: string;
     keepCurrent: string;
     markPending: string;
+    acceptIncomingFor: string;
+    keepCurrentFor: string;
+    markPendingFor: string;
     resolutionAccept: string;
     resolutionSkip: string;
     resolutionPending: string;
@@ -41,9 +49,15 @@ interface DiffViewerProps {
     resolutions?: Record<string, DiffResolution>;
     onResolutionChange?: (path: string, resolution: DiffResolution) => void;
     labels?: Partial<DiffViewerLabels>;
+    /**
+     * Height of the resolution buttons and the entry disclosure rows. `sm` (the default) is
+     * the compact 28px kit size; `md` follows `--uix-control-h`, so a theme that sets its
+     * own control height (for example 60px touch targets) gets it here too; `lg` is 44px.
+     */
+    controlSize?: 'sm' | 'md' | 'lg';
     className?: string;
 }
 /** Three-way configuration diff with per-entry keyboard-operable resolution. */
-declare function DiffViewer({ base, current, incoming, entries: providedEntries, resolutions: controlledResolutions, onResolutionChange, labels: labelOverrides, className, }: DiffViewerProps): react.JSX.Element;
+declare function DiffViewer({ base, current, incoming, entries: providedEntries, resolutions: controlledResolutions, onResolutionChange, labels: labelOverrides, controlSize, className, }: DiffViewerProps): react.JSX.Element;
 
 export { DEFAULT_DIFF_VIEWER_LABELS, DiffViewer, type DiffViewerLabels, type DiffViewerProps };

package/dist/components/DiffViewer.js

@@ -24,6 +24,9 @@ const DEFAULT_DIFF_VIEWER_LABELS = {
   acceptIncoming: "Accept incoming",
   keepCurrent: "Keep current",
   markPending: "Mark pending",
+  acceptIncomingFor: "Accept incoming for {path}",
+  keepCurrentFor: "Keep current for {path}",
+  markPendingFor: "Mark pending for {path}",
   resolutionAccept: "accepted",
   resolutionSkip: "kept",
   resolutionPending: "pending",
@@ -40,10 +43,12 @@ function DiffViewer({
   resolutions: controlledResolutions,
   onResolutionChange,
   labels: labelOverrides,
+  controlSize = "sm",
   className
 }) {
   const labels = { ...DEFAULT_DIFF_VIEWER_LABELS, ...labelOverrides };
   const resolutionLabel = { accept: labels.resolutionAccept, skip: labels.resolutionSkip, pending: labels.resolutionPending };
+  const buttonSize = controlSize === "md" ? void 0 : `uix-btn--${controlSize}`;
   const id = useId();
   const entries = useMemo(() => providedEntries ?? buildThreeWayDiff(base, current, incoming), [providedEntries, base, current, incoming]);
   const [internalResolutions, setInternalResolutions] = useState({});
@@ -57,8 +62,8 @@ function DiffViewer({
     /* @__PURE__ */ jsx("h3", { children: labels.noDifferences }),
     /* @__PURE__ */ jsx("p", { children: labels.noDifferencesDetail })
   ] });
-  return /* @__PURE__ */ jsxs("section", { className: cx("uix-diff-viewer", className), "aria-label": labels.region, children: [
-    /* @__PURE__ */ jsxs("div", { className: "uix-diff-viewer__summary", "aria-label": labels.summary, children: [
+  return /* @__PURE__ */ jsxs("section", { className: cx("uix-diff-viewer", className), "aria-label": labels.region, "data-control-size": controlSize, children: [
+    /* @__PURE__ */ jsxs("div", { className: "uix-diff-viewer__summary", role: "group", "aria-label": labels.summary, children: [
       GROUPS.map((kind) => /* @__PURE__ */ jsxs("span", { children: [
         /* @__PURE__ */ jsx("b", { children: summary[kind] }),
         " ",
@@ -95,10 +100,10 @@ function DiffViewer({
               /* @__PURE__ */ jsx("strong", { children: labels[version] }),
               /* @__PURE__ */ jsx("pre", { children: renderValue(entry[version], labels.notPresent) })
             ] }, version)) }),
-            /* @__PURE__ */ jsxs("div", { className: "uix-diff-viewer__actions", "aria-label": fillLabel(labels.resolve, { path: entry.path }), children: [
-              /* @__PURE__ */ jsx("button", { type: "button", className: "uix-btn uix-btn--primary uix-btn--sm", "aria-pressed": resolution === "accept", onClick: () => resolve(entry.path, "accept"), children: labels.acceptIncoming }),
-              /* @__PURE__ */ jsx("button", { type: "button", className: "uix-btn uix-btn--secondary uix-btn--sm", "aria-pressed": resolution === "skip", onClick: () => resolve(entry.path, "skip"), children: labels.keepCurrent }),
-              /* @__PURE__ */ jsx("button", { type: "button", className: "uix-btn uix-btn--ghost uix-btn--sm", "aria-pressed": resolution === "pending", onClick: () => resolve(entry.path, "pending"), children: labels.markPending })
+            /* @__PURE__ */ jsxs("div", { className: "uix-diff-viewer__actions", role: "group", "aria-label": fillLabel(labels.resolve, { path: entry.path }), children: [
+              /* @__PURE__ */ jsx("button", { type: "button", className: cx("uix-btn uix-btn--primary", buttonSize), "aria-label": fillLabel(labels.acceptIncomingFor, { path: entry.path }), "aria-pressed": resolution === "accept", onClick: () => resolve(entry.path, "accept"), children: labels.acceptIncoming }),
+              /* @__PURE__ */ jsx("button", { type: "button", className: cx("uix-btn uix-btn--secondary", buttonSize), "aria-label": fillLabel(labels.keepCurrentFor, { path: entry.path }), "aria-pressed": resolution === "skip", onClick: () => resolve(entry.path, "skip"), children: labels.keepCurrent }),
+              /* @__PURE__ */ jsx("button", { type: "button", className: cx("uix-btn uix-btn--ghost", buttonSize), "aria-label": fillLabel(labels.markPendingFor, { path: entry.path }), "aria-pressed": resolution === "pending", onClick: () => resolve(entry.path, "pending"), children: labels.markPending })
             ] })
           ] }, entry.path);
         })

package/dist/components/EditorIcons.d.ts

@@ -31,6 +31,7 @@ declare const PATHS: {
     readonly richMode: "M14 2v4a2 2 0 0 0 2 2h4M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7ZM8 13h8M8 17h5";
     readonly clock: "M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20ZM12 6v6l4 2";
     readonly grip: "M9 5h.01M9 12h.01M9 19h.01M15 5h.01M15 12h.01M15 19h.01";
+    readonly more: "M5 12h.01M12 12h.01M19 12h.01";
 };
 type EditorIconName = keyof typeof PATHS;
 declare function EditorIcon({ name, ...props }: {

package/dist/components/EditorIcons.js

@@ -28,7 +28,8 @@ const PATHS = {
   sourceMode: "M10 12.5 8 15l2 2.5M14 12.5l2 2.5-2 2.5M14 2v4a2 2 0 0 0 2 2h4M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z",
   richMode: "M14 2v4a2 2 0 0 0 2 2h4M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7ZM8 13h8M8 17h5",
   clock: "M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20ZM12 6v6l4 2",
-  grip: "M9 5h.01M9 12h.01M9 19h.01M15 5h.01M15 12h.01M15 19h.01"
+  grip: "M9 5h.01M9 12h.01M9 19h.01M15 5h.01M15 12h.01M15 19h.01",
+  more: "M5 12h.01M12 12h.01M19 12h.01"
 };
 function EditorIcon({ name, ...props }) {
   return /* @__PURE__ */ jsx(

package/dist/components/EditorialHome.d.ts

@@ -25,11 +25,18 @@ interface SectionHeadProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'>
     title: ReactNode;
     /** id for the `<h2>`, for `aria-labelledby` wiring on the enclosing section. */
     titleId?: string;
+    /**
+     * Plain-text help behind a ? button after the title. Blank lines separate paragraphs;
+     * empty, whitespace-only or `null` renders no button.
+     */
+    help?: string | null;
+    /** Accessible name of the ? button. Default `"About: <title>"` when title is text; pass a localised one. */
+    helpLabel?: string;
     /** Right-aligned slot — a `.uix-section-link` anchor, a button, a pill. */
     action?: ReactNode;
 }
-/** Section head — title row with an optional trailing action (`.uix-section-head`). */
-declare function SectionHead({ title, titleId, action, className, ...props }: SectionHeadProps): react.JSX.Element;
+/** Section head — title row (+ optional `help` ?) with an optional trailing action (`.uix-section-head`). */
+declare function SectionHead({ title, titleId, help, helpLabel, action, className, ...props }: SectionHeadProps): react.JSX.Element;
 interface NoticeQueueProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
     /** Leading icon slot. */
     icon?: ReactNode;

package/dist/components/EditorialHome.js

@@ -1,5 +1,7 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { cx } from "../cx.js";
+import { InfoTip } from "./InfoTip.js";
+import { hasHelp, helpLabelFor } from "../info-tip-model.js";
 function PageIntro({
   kicker,
   title,
@@ -26,9 +28,13 @@ function PageIntro({
     children
   ] });
 }
-function SectionHead({ title, titleId, action, className, ...props }) {
+function SectionHead({ title, titleId, help, helpLabel, action, className, ...props }) {
+  const heading = /* @__PURE__ */ jsx("h2", { className: "uix-section-title", id: titleId, children: title });
   return /* @__PURE__ */ jsxs("div", { className: cx("uix-section-head", className), ...props, children: [
-    /* @__PURE__ */ jsx("h2", { className: "uix-section-title", id: titleId, children: title }),
+    hasHelp(help) ? /* @__PURE__ */ jsxs("div", { className: "uix-section-head__title-row", children: [
+      heading,
+      /* @__PURE__ */ jsx(InfoTip, { content: help, label: helpLabel ?? helpLabelFor(title) })
+    ] }) : heading,
     action
   ] });
 }

package/dist/components/Field.d.ts

@@ -7,10 +7,18 @@ interface FieldProps {
     error?: string;
     success?: string;
     required?: boolean;
+    /**
+     * Plain-text help behind a ? button after the label (before the required marker). Blank
+     * lines separate paragraphs; empty, whitespace-only or `null` renders no button. Needs `label`.
+     * Keep format or validation instructions in `hint`, where they stay visible.
+     */
+    help?: string | null;
+    /** Accessible name of the ? button. Default `"About: <label>"`; pass a localised one. */
+    helpLabel?: string;
     children: ReactNode;
     className?: string;
     htmlFor?: string;
 }
-declare function Field({ label, hint, error, success, required, children, className, htmlFor }: FieldProps): react.JSX.Element;
+declare function Field({ label, hint, error, success, required, help, helpLabel, children, className, htmlFor }: FieldProps): react.JSX.Element;
 
 export { Field, type FieldProps };

package/dist/components/Field.js

@@ -1,7 +1,9 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { cloneElement, isValidElement, useId } from "react";
 import { cx } from "../cx.js";
-function Field({ label, hint, error, success, required, children, className, htmlFor }) {
+import { InfoTip } from "./InfoTip.js";
+import { hasHelp, helpLabelFor } from "../info-tip-model.js";
+function Field({ label, hint, error, success, required, help, helpLabel, children, className, htmlFor }) {
   const uid = useId();
   const msgId = `${uid}-msg`;
   const describedBy = error || success || hint ? msgId : void 0;
@@ -13,7 +15,11 @@ function Field({ label, hint, error, success, required, children, className, htm
     "aria-required": children.props["aria-required"] ?? (required || void 0)
   }) : children;
   return /* @__PURE__ */ jsxs("div", { className: cx("uix-field", className), children: [
-    label && /* @__PURE__ */ jsx("label", { className: "uix-field__label", htmlFor: htmlFor ?? controlId, "data-required": required || void 0, children: label }),
+    label && hasHelp(help) ? /* @__PURE__ */ jsxs("div", { className: "uix-field__label-row", children: [
+      /* @__PURE__ */ jsx("label", { className: "uix-field__label", htmlFor: htmlFor ?? controlId, children: label }),
+      /* @__PURE__ */ jsx(InfoTip, { content: help, label: helpLabel ?? helpLabelFor(label) }),
+      required && /* @__PURE__ */ jsx("span", { className: "uix-field__required", "aria-hidden": "true", children: "*" })
+    ] }) : label && /* @__PURE__ */ jsx("label", { className: "uix-field__label", htmlFor: htmlFor ?? controlId, "data-required": required || void 0, children: label }),
     control,
     /* @__PURE__ */ jsx("div", { className: "uix-field__msg", id: msgId, children: error ? /* @__PURE__ */ jsx("span", { className: "uix-field__error", role: "alert", children: error }) : success ? /* @__PURE__ */ jsx("span", { className: "uix-field__success", role: "status", children: success }) : hint ? /* @__PURE__ */ jsx("span", { className: "uix-field__hint", children: hint }) : null })
   ] });

package/dist/components/InfoTip.d.ts

@@ -0,0 +1,29 @@
+import * as react from 'react';
+import { HTMLAttributes } from 'react';
+import { Placement } from '../overlay-position.js';
+
+interface InfoTipProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'content' | 'children'> {
+    /**
+     * Help text, rendered as plain text (never HTML). A blank line starts a new paragraph.
+     * Empty or whitespace-only text renders nothing, so a missing help string needs no guard.
+     */
+    content: string;
+    /** Accessible name of the ? button, e.g. "About: Incidents". The consumer localises it. */
+    label: string;
+    /** Preferred panel placement. Default `'bottom-start'`. */
+    placement?: Placement;
+}
+/**
+ * A small ? that explains a page, section or field. It is a fixed 9 px glyph, superscript at
+ * the top right of the text it follows (25 px hit area). The panel opens on hover (after a short delay), on
+ * keyboard focus, and on click or tap; a click keeps it open until a second click, Esc or a
+ * click outside. Esc returns focus to the button. The panel is plain text in
+ * the top layer (kit `Popover`, `popover="manual"`, so opening it never closes another popover)
+ * and is the button's `aria-describedby`, so the text is announced on focus.
+ *
+ * Do not put it inside a `<label>`, a heading or a link: `Field`, `PageHeader`, `Card` and
+ * `SectionHead` place it beside those through their `help` prop.
+ */
+declare function InfoTip({ content, ...props }: InfoTipProps): react.JSX.Element | null;
+
+export { InfoTip, type InfoTipProps };

package/dist/components/InfoTip.js

@@ -0,0 +1,185 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from "react";
+import { cx } from "../cx.js";
+import { helpParagraphs } from "../info-tip-model.js";
+import { Popover } from "./Popover.js";
+const OPEN_DELAY = 300;
+const CLOSE_DELAY = 100;
+const QuestionMark = () => /* @__PURE__ */ jsx("svg", { viewBox: "262 -840 436 760", fill: "currentColor", "aria-hidden": "true", focusable: "false", children: /* @__PURE__ */ jsx("path", { d: "M424-320q0-81 14.5-116.5T500-514q41-36 62.5-62.5T584-637q0-41-27.5-68T480-732q-51 0-77.5 31T365-638l-103-44q21-64 77-111t141-47q105 0 161.5 58.5T698-641q0 50-21.5 85.5T609-475q-49 47-59.5 71.5T539-320H424Zm56 240q-33 0-56.5-23.5T400-160q0-33 23.5-56.5T480-240q33 0 56.5 23.5T560-160q0 33-23.5 56.5T480-80Z" }) });
+const isShown = (el) => {
+  try {
+    return !!el?.matches(":popover-open");
+  } catch {
+    return false;
+  }
+};
+function InfoTip({ content, ...props }) {
+  const paragraphs = helpParagraphs(content);
+  if (!paragraphs.length) return null;
+  return /* @__PURE__ */ jsx(InfoTipControl, { paragraphs, ...props });
+}
+function InfoTipControl({
+  paragraphs,
+  label,
+  placement = "bottom-start",
+  className,
+  ...props
+}) {
+  const wrapRef = useRef(null);
+  const buttonRef = useRef(null);
+  const timer = useRef(null);
+  const openRef = useRef(false);
+  const pinned = useRef(false);
+  const pressing = useRef(false);
+  const refocusing = useRef(false);
+  const [open, setOpen] = useState(false);
+  const panelId = `${useId()}-panel`;
+  const panel = () => document.getElementById(panelId);
+  const clearTimer = () => {
+    if (timer.current != null) {
+      clearTimeout(timer.current);
+      timer.current = null;
+    }
+  };
+  const show = () => {
+    clearTimer();
+    const p = panel();
+    if (p && !isShown(p)) {
+      try {
+        p.showPopover();
+      } catch {
+      }
+    }
+    openRef.current = true;
+    setOpen(true);
+  };
+  const hide = () => {
+    clearTimer();
+    pinned.current = false;
+    const p = panel();
+    if (p && isShown(p)) {
+      try {
+        p.hidePopover();
+      } catch {
+      }
+    }
+    openRef.current = false;
+    setOpen(false);
+  };
+  const later = (fn, ms) => {
+    clearTimer();
+    timer.current = window.setTimeout(fn, ms);
+  };
+  const pointerEnter = () => {
+    if (openRef.current) clearTimer();
+    else later(show, OPEN_DELAY);
+  };
+  const pointerLeave = () => {
+    if (!openRef.current) {
+      clearTimer();
+      return;
+    }
+    if (pinned.current || document.activeElement === buttonRef.current) return;
+    later(hide, CLOSE_DELAY);
+  };
+  const escape = () => {
+    const active = document.activeElement;
+    const focusInside = !active || active === document.body || !!wrapRef.current?.contains(active);
+    hide();
+    if (focusInside && active !== buttonRef.current) {
+      refocusing.current = true;
+      buttonRef.current?.focus();
+      refocusing.current = false;
+    }
+  };
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e) => {
+      if (e.key === "Escape") escape();
+    };
+    const onPointer = (e) => {
+      if (!wrapRef.current?.contains(e.target)) hide();
+    };
+    document.addEventListener("keydown", onKey);
+    document.addEventListener("pointerdown", onPointer, true);
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      document.removeEventListener("pointerdown", onPointer, true);
+    };
+  }, [open]);
+  useEffect(() => () => {
+    clearTimer();
+    const p = panel();
+    if (p && isShown(p)) {
+      try {
+        p.hidePopover();
+      } catch {
+      }
+    }
+  }, []);
+  return /* @__PURE__ */ jsxs("span", { ref: wrapRef, className: cx("uix-info-tip", className), "data-open": open || void 0, ...props, children: [
+    /* @__PURE__ */ jsx(
+      "button",
+      {
+        ref: buttonRef,
+        type: "button",
+        className: "uix-info-tip__button",
+        "aria-label": label,
+        "aria-describedby": panelId,
+        onPointerEnter: pointerEnter,
+        onPointerLeave: pointerLeave,
+        onPointerDown: () => {
+          pressing.current = true;
+        },
+        onFocus: () => {
+          if (!refocusing.current) show();
+        },
+        onBlur: (e) => {
+          const next = e.relatedTarget;
+          if (!pinned.current || next && !wrapRef.current?.contains(next)) hide();
+        },
+        onClick: () => {
+          const viaPointer = pressing.current;
+          pressing.current = false;
+          if (openRef.current && (pinned.current || !viaPointer)) hide();
+          else {
+            show();
+            pinned.current = true;
+          }
+        },
+        onKeyDown: (e) => {
+          pressing.current = false;
+          if (e.key === "Escape" && openRef.current) {
+            e.preventDefault();
+            e.stopPropagation();
+            hide();
+          }
+        },
+        children: /* @__PURE__ */ jsx(QuestionMark, {})
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      Popover,
+      {
+        id: panelId,
+        role: "tooltip",
+        popover: "manual",
+        anchor: buttonRef,
+        placement,
+        className: "uix-info-tip__panel",
+        onPointerEnter: () => {
+          if (openRef.current) clearTimer();
+        },
+        onPointerLeave: pointerLeave,
+        onPointerDown: () => {
+          pinned.current = true;
+        },
+        children: paragraphs.map((text, i) => /* @__PURE__ */ jsx("p", { children: text }, i))
+      }
+    )
+  ] });
+}
+export {
+  InfoTip
+};

package/dist/components/PageHeader.d.ts

@@ -8,13 +8,20 @@ interface PageHeaderProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
     as?: 'h1' | 'h2';
     /** Supporting copy under the title. */
     subtitle?: ReactNode;
+    /**
+     * Plain-text help behind a ? button right after the title. Blank lines separate paragraphs;
+     * empty, whitespace-only or `null` renders no button.
+     */
+    help?: string | null;
+    /** Accessible name of the ? button. Default `"About: <title>"` when title is text; pass a localised one. */
+    helpLabel?: string;
     /** Right-aligned action area (buttons, menus). */
     actions?: ReactNode;
 }
 /**
- * Page header — eyebrow / title / subtitle + actions row, over `.uix-page-header`.
+ * Page header — eyebrow / title (+ optional `help` ?) / subtitle + actions row, over `.uix-page-header`.
  * The hairline + breathing room below come from the component CSS.
  */
-declare function PageHeader({ eyebrow, title, subtitle, actions, as: TitleTag, className, ...props }: PageHeaderProps): react.JSX.Element;
+declare function PageHeader({ eyebrow, title, subtitle, help, helpLabel, actions, as: TitleTag, className, ...props }: PageHeaderProps): react.JSX.Element;
 
 export { PageHeader, type PageHeaderProps };

package/dist/components/PageHeader.js

@@ -1,10 +1,16 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { cx } from "../cx.js";
-function PageHeader({ eyebrow, title, subtitle, actions, as: TitleTag = "h1", className, ...props }) {
+import { InfoTip } from "./InfoTip.js";
+import { hasHelp, helpLabelFor } from "../info-tip-model.js";
+function PageHeader({ eyebrow, title, subtitle, help, helpLabel, actions, as: TitleTag = "h1", className, ...props }) {
+  const heading = /* @__PURE__ */ jsx(TitleTag, { className: "uix-page-header__title", children: title });
   return /* @__PURE__ */ jsxs("header", { className: cx("uix-page-header", className), ...props, children: [
     /* @__PURE__ */ jsxs("div", { className: "uix-page-header__titles", children: [
       eyebrow != null && /* @__PURE__ */ jsx("div", { className: "uix-page-header__eyebrow", children: eyebrow }),
-      /* @__PURE__ */ jsx(TitleTag, { className: "uix-page-header__title", children: title }),
+      hasHelp(help) ? /* @__PURE__ */ jsxs("div", { className: "uix-page-header__title-row", children: [
+        heading,
+        /* @__PURE__ */ jsx(InfoTip, { content: help, label: helpLabel ?? helpLabelFor(title) })
+      ] }) : heading,
       subtitle != null && /* @__PURE__ */ jsx("p", { className: "uix-page-header__subtitle", children: subtitle })
     ] }),
     actions != null && /* @__PURE__ */ jsx("div", { className: "uix-page-header__actions", children: actions })

package/dist/components/SearchSuggest.d.ts

@@ -0,0 +1,87 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode, Ref } from 'react';
+
+/** One result row. */
+interface SearchSuggestOption {
+    /** Stable id, returned by `onSelect`. */
+    id: string;
+    /** The result's name. Matched letters are emphasised. */
+    title: string;
+    /** Where the result lives, outermost first (a breadcrumb). Middle crumbs truncate first. */
+    meta?: readonly string[];
+    /** One or two lines of context, clamped at two lines. Matched letters are emphasised. */
+    description?: string;
+    /** Optional leading glyph (decorative). */
+    icon?: ReactNode;
+}
+/** A labelled action inside the list (the footer row, the heading action). */
+interface SearchSuggestAction {
+    /** Visible text of the action. */
+    label: string;
+    /** Runs when the action is chosen. */
+    onSelect: () => void;
+}
+/** Props of {@link SearchSuggest}. */
+interface SearchSuggestProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'onSelect' | 'title' | 'defaultValue'> {
+    /** The text in the field (controlled). */
+    value: string;
+    /** Called on every edit, and with an empty string when the field is cleared. */
+    onValueChange: (value: string) => void;
+    /** The suggestions to show, best first. The consumer filters; this component only renders. */
+    options: readonly SearchSuggestOption[];
+    /** Called when a row is chosen by click or Enter. The list closes afterwards. */
+    onSelect: (id: string, option: SearchSuggestOption) => void;
+    /** Accessible name of the field (there is no visible label; the placeholder is not a label). */
+    label: string;
+    placeholder?: string;
+    /** Text to emphasise in rows. Defaults to `value`. */
+    highlight?: string;
+    /** A title above the options, e.g. "Recently opened". */
+    heading?: string;
+    /** A small action next to the heading, e.g. "Clear". */
+    headingAction?: SearchSuggestAction;
+    /** A last row after the options, e.g. "Show all 23 results". Reachable by arrow keys. */
+    footer?: SearchSuggestAction;
+    /** The field is fetching suggestions: a spinner shows in the field and, with no options yet, in the list. */
+    loading?: boolean;
+    /** Announced while loading, and shown in the list when it has no rows yet. */
+    loadingLabel?: string;
+    /** Shown when the field has text, nothing is loading and there are no options. */
+    empty?: ReactNode;
+    /** Shown instead of the empty state when suggestions could not be loaded. */
+    error?: ReactNode;
+    /** A keyboard hint shown in the empty, unfocused field, e.g. "/". */
+    shortcutHint?: string;
+    /** Accessible name of the clear button (default "Clear search"). */
+    clearLabel?: string;
+    /** A polite announcement, e.g. "8 results". Rendered in a visually hidden live region. */
+    status?: string;
+    /** `lg` for a page-level search (hubs, start pages); `md` for a field in a toolbar or header. */
+    size?: 'md' | 'lg';
+    /** Controlled open state of the suggestion list (optional). */
+    open?: boolean;
+    /** Called when the list opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * `absolute` (default) places the list under the field inside its own box. `fixed` floats it on
+     * the viewport, so a clipping ancestor (`overflow: hidden` toolbars and headers) cannot cut it off;
+     * it follows the field on scroll and resize and flips above it when there is no room below.
+     */
+    strategy?: 'absolute' | 'fixed';
+    /** Focus the field from outside (e.g. a "/" shortcut). */
+    inputRef?: Ref<HTMLInputElement | null>;
+    /** Focus the field on mount. */
+    autoFocus?: boolean;
+    /** Form field name of the input. */
+    name?: string;
+}
+/**
+ * A search field with a suggestion list underneath: the "search and jump" pattern of Windows
+ * Settings, Android Settings and most docs sites. Each row shows a name, where it lives and a line
+ * of context. ARIA combobox pattern: focus stays in the field, arrow keys move the active row
+ * (`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, status, size, open: openProp, strategy, onOpenChange, inputRef, autoFocus, name, className, onBlur, ...props }: SearchSuggestProps): react.JSX.Element;
+
+export { SearchSuggest, type SearchSuggestAction, type SearchSuggestOption, type SearchSuggestProps };