@parallelworks/ui 0.51.0 → 0.53.0

package/dist/components/DescriptionList.js

@@ -1,28 +1,66 @@
 import { cx } from "../cx.js";
-import { CheckIcon, CopyIcon } from "../icons.js";
 import { useStrings } from "./Provider.js";
-import { useCopy } from "./useCopy.js";
-import { IconButton } from "./IconButton.js";
 import { InfoTip } from "./InfoTip.js";
+import { CopyButton } from "./CopyButton.js";
+import { withPathBreaks } from "./pathBreaks.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { useId, useRef } from "react";
+import { createContext, useContext, useId, useRef } from "react";
 //#region src/components/DescriptionList.tsx
 var variantClasses = {
 	plain: "*:py-1",
 	divided: "divide-y divide-(--theme-border) *:py-2",
 	card: "panel divide-y divide-(--theme-border) px-4 *:py-2"
 };
+var columns = (stacked) => cx("grid grid-cols-[minmax(0,1fr)]", !stacked && "@sm/dl:grid-cols-[fit-content(40%)_minmax(0,1fr)] @sm/dl:gap-x-6");
+var InGroup = createContext(false);
+var titleClassName = "col-span-full m-0 mb-1 text-sm font-semibold text-(--theme-app)";
 /** Names and their values, such as the details of a record in a drawer or a card. The
 *  label column is as wide as its longest label, up to two fifths of the list, so a
 *  long label wraps rather than squeezing the values; each label sits over its value
-*  when the list is narrow. */
-function DescriptionList({ variant = "plain", stacked = false, className, children, ...props }) {
+*  when the list is narrow. Lists side by side in one panel share their label column
+*  inside a `DescriptionListGroup`. */
+function DescriptionList({ variant = "plain", title, headingLevel = 3, stacked = false, className, children, ...props }) {
+	const grouped = useContext(InGroup);
+	const titleId = useId();
+	const Heading = `h${headingLevel}`;
+	const list = /* @__PURE__ */ jsx("dl", {
+		...props,
+		className: cx("m-0 text-sm", grouped ? "col-span-full grid grid-cols-subgrid" : columns(stacked), variantClasses[variant]),
+		children
+	});
+	const named = title !== void 0 ? {
+		role: "group",
+		"aria-labelledby": titleId
+	} : {};
+	const heading = title !== void 0 && /* @__PURE__ */ jsx(Heading, {
+		id: titleId,
+		className: titleClassName,
+		children: title
+	});
+	if (grouped) return /* @__PURE__ */ jsxs("div", {
+		...named,
+		className: cx("col-span-full grid grid-cols-subgrid", className),
+		children: [heading, list]
+	});
+	return /* @__PURE__ */ jsxs("div", {
+		...named,
+		className: cx("@container/dl min-w-0", className),
+		children: [heading, list]
+	});
+}
+/** Description lists in one panel, such as a record's Overview, Actor and Target, that
+*  share one label column: it fits the longest label across all of them, so their
+*  values start at one edge down the panel. Each list keeps its own title and variant;
+*  all of them stack together when the panel is narrow. */
+function DescriptionListGroup({ stacked = false, className, children }) {
 	return /* @__PURE__ */ jsx("div", {
 		className: cx("@container/dl min-w-0", className),
-		children: /* @__PURE__ */ jsx("dl", {
-			...props,
-			className: cx("m-0 grid grid-cols-[minmax(0,1fr)] text-sm", !stacked && "@sm/dl:grid-cols-[fit-content(40%)_minmax(0,1fr)] @sm/dl:gap-x-6", variantClasses[variant]),
-			children
+		children: /* @__PURE__ */ jsx("div", {
+			className: cx(columns(stacked), "gap-y-6"),
+			children: /* @__PURE__ */ jsx(InGroup, {
+				value: true,
+				children
+			})
 		})
 	});
 }
@@ -46,7 +84,7 @@ function DescriptionListItem({ label, children, tooltip, mono = false, copy = fa
 			children: isEmpty(children) ? /* @__PURE__ */ jsx(EmptyValue, {}) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("div", {
 				"data-value": true,
 				className: cx("min-w-0 leading-5 wrap-anywhere", mono && "font-mono text-[0.8125rem]"),
-				children
+				children: withPathBreaks(children)
 			}), copy !== false && /* @__PURE__ */ jsx(CopyValue, {
 				text: copy === true ? void 0 : copy,
 				label,
@@ -70,25 +108,21 @@ function EmptyValue() {
 	});
 }
 function CopyValue({ text, label, labelId }) {
-	const { common: t } = useStrings();
-	const { copy, copied } = useCopy();
 	const buttonId = useId();
 	const button = useRef(null);
-	const onClick = () => {
+	const shown = () => {
 		const value = button.current?.closest("dd")?.querySelector("[data-value]");
-		const shown = value?.innerText ?? value?.textContent;
-		copy(text ?? shown ?? "", typeof label === "string" ? { label } : void 0);
+		return value?.innerText ?? value?.textContent ?? "";
 	};
-	return /* @__PURE__ */ jsx(IconButton, {
+	return /* @__PURE__ */ jsx(CopyButton, {
 		ref: button,
 		id: buttonId,
 		size: "xs",
-		label: copied ? t.copied : t.copy,
-		"aria-labelledby": `${buttonId} ${labelId}`,
-		icon: copied ? /* @__PURE__ */ jsx(CheckIcon, {}) : /* @__PURE__ */ jsx(CopyIcon, {}),
-		onClick,
+		text: text ?? shown,
+		label: typeof label === "string" ? label : void 0,
+		"aria-labelledby": typeof label === "string" ? void 0 : `${buttonId} ${labelId}`,
 		className: "-my-0.5"
 	});
 }
 //#endregion
-export { DescriptionListItem, DescriptionList as default };
+export { DescriptionListGroup, DescriptionListItem, DescriptionList as default };

package/dist/components/Disclosure.js

@@ -17,7 +17,7 @@ function Disclosure({ summary, open, onOpenChange, defaultOpen = false, disabled
 		disabled,
 		className,
 		children: [/* @__PURE__ */ jsxs(Collapsible.Trigger, {
-			className: cx("group/disclosure flex min-w-0 items-start gap-2 text-left", disabled ? "cursor-default" : "cursor-pointer", summaryClassName),
+			className: cx("group/disclosure flex min-w-0 items-start gap-2 rounded-sm text-left focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-(--theme-focus)", disabled ? "cursor-default" : "cursor-pointer", summaryClassName),
 			children: [summary, !disabled && /* @__PURE__ */ jsx(ChevronRightIcon, {
 				"aria-hidden": "true",
 				className: "mt-1 h-3.5 w-3.5 shrink-0 opacity-70 transition-transform group-data-panel-open/disclosure:rotate-90 motion-reduce:transition-none"

package/dist/components/Drawer.js

@@ -1,7 +1,8 @@
 import { cx } from "../cx.js";
 import { CloseIcon } from "../icons.js";
-import { pressedToast } from "./Toast.js";
 import { useStrings } from "./Provider.js";
+import { IconButton } from "./IconButton.js";
+import { closeHandler } from "./dismiss.js";
 import { useSplitter } from "./splitter.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useLayoutEffect, useRef, useState } from "react";
@@ -30,14 +31,7 @@ function Drawer$1({ open, onClose, title, description, footer, side = "right", w
 	});
 	const header = title !== void 0 || description !== void 0 || closeButton;
 	const area = contained ? "absolute inset-0" : "fixed inset-x-0 bottom-0 top-(--app-inset-top,0px)";
-	const onOpenChange = (next, details) => {
-		if (next) return;
-		if (!dismissible && details.reason === "escape-key" || details.reason === "outside-press" && pressedToast(details.event)) {
-			details.cancel();
-			return;
-		}
-		onClose();
-	};
+	const onOpenChange = closeHandler(dismissible, onClose);
 	return /* @__PURE__ */ jsxs(Drawer.Root, {
 		open,
 		onOpenChange,
@@ -70,24 +64,24 @@ function Drawer$1({ open, onClose, title, description, footer, side = "right", w
 								children: [/* @__PURE__ */ jsxs("div", {
 									className: "min-w-0 flex-1",
 									children: [title !== void 0 && /* @__PURE__ */ jsx(Drawer.Title, {
-										className: "truncate text-sm font-semibold",
+										className: "m-0 text-sm font-semibold wrap-break-word",
 										children: title
 									}), description !== void 0 && /* @__PURE__ */ jsx(Drawer.Description, {
 										className: "mt-0.5 text-xs text-(--theme-muted-text-color)",
 										children: description
 									})]
-								}), closeButton && /* @__PURE__ */ jsx(Drawer.Close, {
-									"aria-label": common.close,
-									className: "-m-1 shrink-0 cursor-pointer rounded-md p-1 text-(--theme-muted-text-color) transition-colors hover:bg-(--theme-muted-panel-bg) hover:text-(--theme-app)",
-									children: /* @__PURE__ */ jsx(CloseIcon, { className: "h-4 w-4" })
-								})]
+								}), closeButton && /* @__PURE__ */ jsx(Drawer.Close, { render: /* @__PURE__ */ jsx(IconButton, {
+									icon: /* @__PURE__ */ jsx(CloseIcon, {}),
+									label: common.close,
+									className: "-my-1 -me-1.5"
+								}) })]
 							}),
 							/* @__PURE__ */ jsx("div", {
 								className: cx("relative flex min-h-0 flex-1 flex-col overflow-y-auto", padded && "p-4", className),
 								children
 							}),
 							footer && /* @__PURE__ */ jsx("div", {
-								className: "flex shrink-0 justify-end gap-2 border-t border-(--theme-border) px-4 py-3",
+								className: cx("flex shrink-0 items-center justify-end gap-2 border-t border-(--theme-border) px-5 py-3", "px-4"),
 								children: footer
 							})
 						]

package/dist/components/Field.d.ts

@@ -17,11 +17,21 @@ export declare const FieldRowContext: import("react").Context<boolean>;
 /** The surrounding Field's control props, for a control drawn further down than the Field's
  *  own children. Null outside a Field. */
 export declare function useFieldControl(): FieldControlProps | null;
+/** The label's id, for a control that isn't a Base UI one and so isn't named by the label's
+ *  `for`, such as a button that opens a picker. */
+export declare function useFieldLabelId(): string | undefined;
 export type FieldLayout = 'stacked' | 'inline';
 export interface FieldProps {
     label: ReactNode;
-    /** Beside the label and outside it, so it stays out of the control's name: an InfoTip, a count. */
+    /** Beside the label and outside it, so it stays out of the control's name, such as a count. For
+     *  help text, use `help`. */
     hint?: ReactNode;
+    /** More about the field, behind a ? beside the label. It is read with the control as part of
+     *  its description, so the ? is hidden from assistive technology and Tab passes over it. It
+     *  opens on hover or press of the ?, and while the control has keyboard focus, until Escape.
+     *  `[text](url)` links and line breaks show as such; a link keeps the ? in the Tab order, as
+     *  the keyboard's way to it. */
+    help?: string | undefined;
     /** Buttons at the far end of the label's row that act on the field, such as one that
      *  switches its control to a typed expression. */
     actions?: ReactNode;
@@ -47,9 +57,10 @@ export interface FieldProps {
     /** The control's id; one is made up when left out. */
     id?: string | undefined;
     className?: string | undefined;
-    /** The control, or a function that places the control props on it. A Base UI control, such
-     *  as Select, Combobox, NumberInput, Checkbox or Switch, needs only the `id`. A value shown
-     *  but not edited goes in a `FieldValue`. */
+    /** The control, or a function that places the control props on it. Any control of this
+     *  package, such as Input, Select, Combobox, NumberInput, Switch or DatePicker, takes its label,
+     *  description and invalid state from the Field on its own; a native element needs the
+     *  function. A value shown but not edited goes in a `FieldValue`. */
     children: ReactNode | ((control: FieldControlProps) => ReactNode);
 }
 /** An error in the look a Field gives its own, for a control outside a Field, or for a part of
@@ -61,7 +72,7 @@ export declare function ErrorText({ id, children }: {
 }): import("react").JSX.Element | null;
 /** A control with its label, help and error, tied to it for assistive technology. One frame
  *  for every field, in a form or standing alone. */
-export declare function Field({ label, hint, actions, description, error, invalid, required, disabled, layout, compact, size, group, id: ownId, className, children, }: FieldProps): import("react").JSX.Element;
+export declare function Field({ label, hint, help, actions, description, error, invalid, required, disabled, layout, compact, size, group, id: ownId, className, children, }: FieldProps): import("react").JSX.Element;
 /** One checkbox or radio and its label inside a Field, such as an option of a group. A bare
  *  `<label>` there would take the Field's label as its own, so every option read as the field. */
 export declare function FieldOption({ disabled, className, children, }: {

package/dist/components/Field.js

@@ -1,9 +1,11 @@
 import { cx } from "../cx.js";
 import { EyeIcon, EyeOffIcon, WarningIcon } from "../icons.js";
 import { useStrings } from "./Provider.js";
+import { focusCameFromKeyboard, trackFocusModality } from "./focus.js";
+import { InfoTip, formatInfoTipContent } from "./InfoTip.js";
 import { RequiredMark } from "./RequiredMark.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { createContext, use, useId } from "react";
+import { createContext, use, useEffect, useId, useState } from "react";
 import { Field } from "@base-ui/react/field";
 import { Fieldset } from "@base-ui/react/fieldset";
 //#region src/components/Field.tsx
@@ -15,7 +17,12 @@ var FieldRowContext = createContext(false);
 /** The surrounding Field's control props, for a control drawn further down than the Field's
 *  own children. Null outside a Field. */
 function useFieldControl() {
-	return use(ControlContext);
+	return use(ControlContext)?.control ?? null;
+}
+/** The label's id, for a control that isn't a Base UI one and so isn't named by the label's
+*  `for`, such as a button that opens a picker. */
+function useFieldLabelId() {
+	return use(ControlContext)?.labelId;
 }
 var labelSizes = {
 	sm: {
@@ -48,14 +55,19 @@ function ErrorText({ id, children }) {
 }
 /** A control with its label, help and error, tied to it for assistive technology. One frame
 *  for every field, in a form or standing alone. */
-function Field$1({ label, hint, actions, description, error, invalid, required = false, disabled = false, layout = "stacked", compact = false, size = "md", group = false, id: ownId, className, children }) {
+function Field$1({ label, hint, help, actions, description, error, invalid, required = false, disabled = false, layout = "stacked", compact = false, size = "md", group = false, id: ownId, className, children }) {
 	const uid = useId();
 	const id = ownId ?? `${uid}control`;
 	const labelId = `${uid}label`;
 	const descriptionId = description ? `${uid}description` : void 0;
+	const helpId = help ? `${uid}help` : void 0;
 	const errorId = error ? `${uid}error` : void 0;
 	const isInvalid = Boolean(error) || Boolean(invalid);
-	const describedBy = [descriptionId, errorId].filter(Boolean).join(" ");
+	const describedBy = [
+		descriptionId,
+		helpId,
+		errorId
+	].filter(Boolean).join(" ");
 	const control = {
 		id,
 		...group && { "aria-labelledby": labelId },
@@ -63,26 +75,61 @@ function Field$1({ label, hint, actions, description, error, invalid, required =
 		...isInvalid && { "aria-invalid": true },
 		...required && { "aria-required": true }
 	};
+	const controlContext = {
+		control,
+		labelId
+	};
 	const inline = layout === "inline";
 	const inRow = use(FieldRowContext) && !inline && !group;
 	const labelSize = labelSizes[size];
+	const [helpOpen, setHelpOpen] = useState(false);
+	useEffect(() => {
+		if (help) trackFocusModality();
+	}, [help]);
+	const helpTip = help && /* @__PURE__ */ jsx(InfoTip, {
+		text: help,
+		describesControl: true,
+		open: Boolean(helpOpen),
+		onOpenChange: (open) => setHelpOpen(open && "pointer"),
+		keepSide: helpOpen === "focus"
+	});
+	const helpFocus = help ? {
+		onFocus: () => {
+			if (focusCameFromKeyboard()) setHelpOpen("focus");
+		},
+		onBlur: (event) => {
+			if (!event.currentTarget.contains(event.relatedTarget)) setHelpOpen(false);
+		},
+		onKeyDown: (event) => {
+			if (event.key === "Escape" && helpOpen) {
+				event.stopPropagation();
+				setHelpOpen(false);
+			}
+		}
+	} : {};
 	const labelBox = cx(labelClassName, labelSize.text, inline && cx(labelSize.inlineHeight, "shrink-0", compact ? "mr-2 w-fit" : "w-52 pr-3"), inRow && "row-start-1 self-end");
 	const labelContent = /* @__PURE__ */ jsxs(Fragment, { children: [
 		/* @__PURE__ */ jsxs("span", { children: [label, required && /* @__PURE__ */ jsx(RequiredMark, {})] }),
+		helpTip,
 		hint,
 		actions && /* @__PURE__ */ jsx("span", {
 			className: actionsClassName,
 			children: actions
 		})
 	] });
+	const placed = typeof children === "function" ? children(control) : children;
 	const body = /* @__PURE__ */ jsxs("div", {
 		className: cx("flex w-full min-w-0 flex-col gap-1", inRow && "row-start-2"),
+		...helpFocus,
 		children: [
 			/* @__PURE__ */ jsx(FieldRowContext, {
 				value: false,
 				children: /* @__PURE__ */ jsx(ControlContext, {
-					value: control,
-					children: typeof children === "function" ? children(control) : children
+					value: controlContext,
+					children: inline ? /* @__PURE__ */ jsx("div", {
+						className: cx("grid items-center", labelSize.inlineHeight),
+						children: placed
+					}) : placed
 				})
 			}),
 			description && /* @__PURE__ */ jsx(Field.Description, {
@@ -90,6 +137,11 @@ function Field$1({ label, hint, actions, description, error, invalid, required =
 				className: "text-xs leading-relaxed text-(--theme-muted-text-color)",
 				children: description
 			}),
+			help && /* @__PURE__ */ jsx(Field.Description, {
+				id: helpId,
+				hidden: true,
+				children: formatInfoTipContent(help)
+			}),
 			error && /* @__PURE__ */ jsxs(Field.Error, {
 				id: errorId,
 				match: true,
@@ -128,11 +180,12 @@ function Field$1({ label, hint, actions, description, error, invalid, required =
 			className: labelBox,
 			children: [
 				/* @__PURE__ */ jsxs(Field.Label, {
-					htmlFor: id,
+					...typeof children === "function" || ownId !== void 0 ? { htmlFor: id } : {},
 					id: labelId,
 					"data-field-label": true,
 					children: [label, required && /* @__PURE__ */ jsx(RequiredMark, {})]
 				}),
+				helpTip,
 				hint,
 				actions && /* @__PURE__ */ jsx("span", {
 					className: actionsClassName,
@@ -177,8 +230,10 @@ function RevealToggle({ revealed, onRevealedChange, disabled }) {
 *  DescriptionList. */
 function FieldValue({ size = "md", className, children, ...props }) {
 	const control = useFieldControl();
+	const labelId = useFieldLabelId();
 	return /* @__PURE__ */ jsx("output", {
 		id: control?.id,
+		"aria-labelledby": labelId,
 		"aria-describedby": control?.["aria-describedby"],
 		...props,
 		className: cx("flex min-w-0 items-center break-words text-(--theme-app)", size === "sm" ? "min-h-7 text-xs" : "min-h-9 text-sm", className),
@@ -186,4 +241,4 @@ function FieldValue({ size = "md", className, children, ...props }) {
 	});
 }
 //#endregion
-export { ErrorText, Field$1 as Field, FieldOption, FieldRowContext, FieldValue, RevealToggle, useFieldControl };
+export { ErrorText, Field$1 as Field, FieldOption, FieldRowContext, FieldValue, RevealToggle, useFieldControl, useFieldLabelId };

package/dist/components/IconButton.d.ts

@@ -1,6 +1,7 @@
 import { type ComponentPropsWithRef, type ReactNode } from 'react';
+import { type AppLinkProps } from './AppLink.js';
 import { type ButtonSize, type ButtonVariant } from './buttonClasses.js';
-export interface IconButtonProps extends ComponentPropsWithRef<'button'> {
+interface IconButtonOwnProps {
     icon: ReactNode;
     /** The accessible name, also shown as the tooltip. */
     label: string;
@@ -8,13 +9,21 @@ export interface IconButtonProps extends ComponentPropsWithRef<'button'> {
     size?: ButtonSize;
     /** A toggle's state: set, it reads as pressed (`aria-pressed`). */
     pressed?: boolean | undefined;
-    /** A dot in the corner, such as for filters narrowing what the page shows. */
+    /** A dot in the corner, such as for filters narrowing what the page shows. It
+     *  is only seen, so say what it means in `label` too, such as "Filters (2 on)". */
     dot?: boolean;
     /** A single key, such as F, that presses the button from anywhere on the page
      *  outside a text field. Also shown in the tooltip. */
     shortcut?: string | undefined;
 }
-/** A button that shows only an icon, named by its tooltip. It can be a popup's
- *  trigger: it passes the trigger's props and ref on, and hides its tooltip while
- *  the popup is open. */
+/** With `href` it is a link that looks like the button, for navigation. */
+export type IconButtonProps = IconButtonOwnProps & ((ComponentPropsWithRef<'button'> & {
+    href?: undefined;
+}) | (Omit<AppLinkProps, 'href'> & {
+    href: string;
+}));
+/** A button that shows only an icon, named by its tooltip, or with `href` a
+ *  link that looks like one. It can be a popup's trigger: it passes the
+ *  trigger's props and ref on, and hides its tooltip while the popup is open. */
 export declare function IconButton({ icon, label, variant, size, pressed, dot, shortcut, className, ref, ...props }: IconButtonProps): import("react").JSX.Element;
+export {};

package/dist/components/IconButton.js

@@ -1,37 +1,48 @@
 import { cx } from "../cx.js";
 import { buttonClasses } from "./buttonClasses.js";
 import { Tooltip } from "./Tooltip.js";
+import { AppLink } from "./AppLink.js";
 import { useShortcutKey } from "./shortcutKey.js";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useCallback, useRef } from "react";
 //#region src/components/IconButton.tsx
-/** A button that shows only an icon, named by its tooltip. It can be a popup's
-*  trigger: it passes the trigger's props and ref on, and hides its tooltip while
-*  the popup is open. */
+/** A button that shows only an icon, named by its tooltip, or with `href` a
+*  link that looks like one. It can be a popup's trigger: it passes the
+*  trigger's props and ref on, and hides its tooltip while the popup is open. */
 function IconButton({ icon, label, variant = "ghost", size = "sm", pressed, dot = false, shortcut, className, ref, ...props }) {
 	const button = useRef(null);
 	const setButton = useCallback((node) => {
 		button.current = node;
-		if (typeof ref === "function") ref(node);
-		else if (ref) ref.current = node;
+		const forward = ref;
+		if (typeof forward === "function") forward(node);
+		else if (forward) forward.current = node;
 	}, [ref]);
+	const shared = {
+		"aria-label": label,
+		className: cx(buttonClasses({
+			variant,
+			size,
+			iconOnly: true
+		}), className)
+	};
+	const content = /* @__PURE__ */ jsxs(Fragment, { children: [icon, dot && /* @__PURE__ */ jsx("span", { className: "absolute right-0 top-0 h-1.5 w-1.5 rounded-full bg-(--theme-link)" })] });
 	useShortcutKey(shortcut, () => button.current?.click());
 	return /* @__PURE__ */ jsx(Tooltip, {
 		content: label,
 		shortcut: shortcut?.toUpperCase(),
 		disabled: props["aria-expanded"] === true && !!props["aria-haspopup"],
-		children: /* @__PURE__ */ jsxs("button", {
+		children: props.href !== void 0 ? /* @__PURE__ */ jsx(AppLink, {
+			...shared,
+			ref: setButton,
+			...props,
+			children: content
+		}) : /* @__PURE__ */ jsx("button", {
 			type: "button",
-			"aria-label": label,
 			"aria-pressed": pressed,
+			...shared,
 			ref: setButton,
-			className: cx(buttonClasses({
-				variant,
-				size,
-				iconOnly: true
-			}), className),
 			...props,
-			children: [icon, dot && /* @__PURE__ */ jsx("span", { className: "absolute right-0 top-0 h-1.5 w-1.5 rounded-full bg-(--theme-link)" })]
+			children: content
 		})
 	});
 }

package/dist/components/InfoTip.d.ts

@@ -8,8 +8,19 @@ interface InfoTipProps {
     className?: string | undefined;
     /** Replaces the info icon as the trigger, such as a status label the text explains. */
     children?: ReactNode;
+    /** The text is also a control's description, which assistive technology reads with the
+     *  control, so the ? is hidden from it and skipped by Tab rather than offering the text twice.
+     *  Text with a link keeps the ? reachable, as the only way to the link from the keyboard. */
+    describesControl?: boolean | undefined;
+    /** Opens it from outside as well as on hover and press, such as while the described control
+     *  has keyboard focus. Pair it with `onOpenChange`. */
+    open?: boolean | undefined;
+    onOpenChange?: ((open: boolean) => void) | undefined;
+    /** Stays on `side` rather than flipping where it doesn't fit, as while the control it
+     *  describes is typed in, which a flipped tip would cover. */
+    keepSide?: boolean | undefined;
 }
 /** Extra detail behind an info trigger. A popover that also opens on hover, so
  *  touch and screen reader users can reach it and its links. */
-export declare function InfoTip({ text, side, className, children }: InfoTipProps): import("react").JSX.Element | null;
+export declare function InfoTip({ text, side, className, children, describesControl, open, onOpenChange, keepSide, }: InfoTipProps): import("react").JSX.Element | null;
 export {};

package/dist/components/InfoTip.js

@@ -28,21 +28,32 @@ function formatInfoTipContent(content) {
 	if (!content) return null;
 	return keyedByContent(content.split(/<br\s*\/?>|\n/i), (l) => l).map(({ key, item: line }, idx) => /* @__PURE__ */ jsxs(Fragment$1, { children: [idx > 0 && /* @__PURE__ */ jsx("br", {}), formatLine(line)] }, key));
 }
+var hasLink = (content) => new RegExp(linkRegex.source).test(content);
 /** Extra detail behind an info trigger. A popover that also opens on hover, so
 *  touch and screen reader users can reach it and its links. */
-function InfoTip({ text, side = "top", className, children }) {
+function InfoTip({ text, side = "top", className, children, describesControl = false, open, onOpenChange, keepSide = false }) {
 	const t = useStrings().common;
 	if (!text) return children ? /* @__PURE__ */ jsx("span", {
 		className,
 		children
 	}) : null;
+	const hidden = describesControl && !hasLink(text);
 	return /* @__PURE__ */ jsx(Popover, {
 		variant: "tip",
 		openOnHover: true,
 		side,
+		keepSide,
+		...open === void 0 ? {} : { open },
+		...onOpenChange ? { onOpenChange } : {},
+		...describesControl && { initialFocus: "none" },
+		...hidden && { finalFocus: false },
 		trigger: /* @__PURE__ */ jsx("button", {
 			type: "button",
-			"aria-label": children ? void 0 : t.moreInfo,
+			...hidden && {
+				tabIndex: -1,
+				"aria-hidden": true
+			},
+			"aria-label": children || hidden ? void 0 : t.moreInfo,
 			className: cx("inline-flex items-center cursor-help", !children && "tooltip", className),
 			children: children ?? /* @__PURE__ */ jsx(HelpIcon, { "aria-hidden": "true" })
 		}),

package/dist/components/Input.d.ts

@@ -1,30 +1,36 @@
-import type { InputHTMLAttributes, ReactNode, TextareaHTMLAttributes } from 'react';
+import type { InputHTMLAttributes, ReactNode, Ref, TextareaHTMLAttributes } from 'react';
 import { type FieldControlProps } from './Field.js';
 import { type FieldBoxSize } from './fieldBox.js';
 interface FramedProps {
-    /** Without a label the box stands alone; name it with `aria-label`. */
+    /** Without a label the box stands alone: name it with `aria-label`, or place it in a Field. */
     label?: ReactNode;
     /** Beside the label and outside it, so it stays out of the field's name. */
     hint?: ReactNode;
+    /** More about the field, behind a ? beside the label; see Field's `help`. */
+    help?: string | undefined;
     /** Help under the field. */
     description?: ReactNode;
     error?: ReactNode;
     mono?: boolean;
-    /** `sm` for dense places such as toolbars and table cells. */
+    /** `sm` for dense places such as toolbars and table cells. With a label, the label matches. */
     size?: FieldBoxSize | undefined;
 }
 export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'>, FramedProps {
+    ref?: Ref<HTMLInputElement> | undefined;
 }
 export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement>, FramedProps {
+    ref?: Ref<HTMLTextAreaElement> | undefined;
 }
 /** The Field around a control when it has a label; the control alone when it doesn't. */
-export declare function framed({ label, hint, description, error }: Omit<FramedProps, 'mono' | 'size'>, { id, required, disabled, }: {
+export declare function framed({ label, hint, help, description, error, size }: Omit<FramedProps, 'mono'>, { id, required, disabled, }: {
     id?: string | undefined;
     required?: boolean | undefined;
     disabled?: boolean | undefined;
 }, control: (props: Partial<FieldControlProps>) => ReactNode): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;
-/** A single-line text field. `type="password"` adds a button that shows what was typed. */
-export declare const Input: import("react").ForwardRefExoticComponent<InputProps & import("react").RefAttributes<HTMLInputElement>>;
-/** A multi-line text field that grows by hand. */
-export declare const Textarea: import("react").ForwardRefExoticComponent<TextareaProps & import("react").RefAttributes<HTMLTextAreaElement>>;
+/** A single-line text field. `type="password"` adds a button that shows what was typed. Placed in
+ *  a Field, it takes the Field's label, description and invalid state. */
+export declare function Input({ label, hint, help, description, error, className, mono, size, type, ref, ...props }: InputProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;
+/** A multi-line text field that grows by hand. Placed in a Field, it takes the Field's label,
+ *  description and invalid state. */
+export declare function Textarea({ label, hint, help, description, error, className, mono, size, ref, ...props }: TextareaProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;
 export {};