@vitavision/ui 0.7.0 → 0.8.0

package/README.md

@@ -124,11 +124,26 @@ keep independent preferences.
 
 **Primitives** — `Badge`, `CountRun`, `StatusDot` · `Button`, `ButtonLink` (a navigation styled as a button — never nest a `Button` in a link), `buttonClasses` · `Dialog`, `ConfirmDialog`,
 `DialogClose` · `Disclosure` · `Callout`, `Empty`, `ErrorBox`, `ProgressBar`, `Skeleton`,
-`SkeletonRows` · `Field` · `Input`, `NumberInput`, `Textarea` · `PageHeader`, `Panel`,
+`SkeletonRows` · `Field` · `Input`, `NumberInput` (with an optional `unit` written in the
+field), `Textarea` · `VectorInput`, `PoseInput` · `PageHeader`, `Panel`,
 `ReadoutStrip`, `Section` · `SegmentedControl` · `Select` · `Slider` · `Table` ·
 `Checkbox`, `Switch` · `ToggleChip` · `InfoHint`, `Tooltip`, `TooltipProvider` ·
 `ThemeToggle` · plus `cn`, `focusRing`, `focusRingInset`.
 
+`PoseInput` edits an SE(3) pose in the wire form `{ rotation: [qx, qy, qz, qw], translation:
+[tx, ty, tz] }` as a translation and roll/pitch/yaw in degrees, but does no rotation
+mathematics: the quaternion ↔ angles conversion — and so what "roll, pitch, yaw" means — is
+passed in as a `RotationView` by the package that owns the frame conventions:
+
+```tsx
+<PoseInput
+  value={camera.world_se3_self}
+  onValueChange={setPose}
+  rotationView={{ toEuler: quatToRpy, fromEuler: rpyToQuat }}
+  translationUnit="mm"
+/>
+```
+
 ### Density
 
 Every primitive with two spacings reads `useDensity()`. The default, `comfortable`, is what

package/dist/index.d.ts

@@ -460,18 +460,33 @@ export declare function useControlHeight(): string;
  * is described by the field's description and error.
  */
 export declare function Input({ className, "aria-describedby": describedBy, ...rest }: ComponentProps<"input">): import("react").JSX.Element;
-/**
- * A number, with the schema's own bounds attached.
- *
- * `font-mono` because these are read as quantities and compared down a column. Takes every
- * `<input>` prop, `ref` included (`type` is always `number`).
- */
-export declare function NumberInput({ className, "aria-describedby": describedBy, ...rest }: Omit<ComponentProps<"input">, "min" | "max"> & {
+/** Props of `NumberInput`: every `<input>` prop, `ref` included, with numeric bounds and a `unit`. */
+type NumberInputProps = Omit<ComponentProps<"input">, "min" | "max"> & {
   /** The smallest accepted value. */
   min?: number | undefined;
   /** The largest accepted value. */
   max?: number | undefined;
-}): import("react").JSX.Element;
+  /**
+   * The quantity's unit (`mm`, `m`, `°`, `px`), written inside the field after the number, in
+   * mono and muted. It is not part of the value. It is announced as the field's description
+   * (`aria-describedby`): after the caller's own `aria-describedby`, before a surrounding
+   * `Field`'s description and error.
+   */
+  unit?: string | undefined;
+};
+/**
+ * A number, with the schema's own bounds attached and, optionally, its unit written in the
+ * field.
+ *
+ * `font-mono` because these are read as quantities and compared down a column. Takes every
+ * `<input>` prop, `ref` included (`type` is always `number`); `className`, `style` and `ref`
+ * always go to the `<input>`.
+ *
+ * With a `unit`, the input sits in a `relative` full-width wrapper carrying `data-unit`, keeps
+ * room on its right for the unit, and is described by it; size such a field through its
+ * container. Without one — or with `""` — the markup is exactly the plain input.
+ */
+export declare function NumberInput({ unit, ...props }: NumberInputProps): import("react").JSX.Element;
 /**
  * Multi-line text — set in mono, for JSON and lists. Takes every `<textarea>` prop, `ref`
  * included.
@@ -572,6 +587,71 @@ export declare function ReadoutStrip({ items, className }: {
   className?: string | undefined;
 }): import("react").JSX.Element | null;
 //#endregion
+//#region src/components/ui/PoseInput.d.ts
+/** Three numbers: a translation `[tx, ty, tz]`, or Euler angles. */
+type Vec3 = readonly [number, number, number];
+/** A unit quaternion in the wire order `[qx, qy, qz, qw]` (scalar last). */
+type Quaternion = readonly [number, number, number, number];
+/**
+ * An SE(3) pose in the wire form (`a_se3_b` as nalgebra's `Isometry3` serialises it):
+ * translation in metres, rotation as a unit quaternion `[qx, qy, qz, qw]`.
+ */
+interface PoseValue {
+  /** The rotation, `[qx, qy, qz, qw]`. */
+  rotation: Quaternion;
+  /** The translation `[tx, ty, tz]`, in metres. */
+  translation: Vec3;
+}
+/**
+ * How a rotation is shown as three angles: the conversion both ways, and the angles' names.
+ * Supplied by the package that owns the frame conventions; `PoseInput` only calls it.
+ */
+interface RotationView {
+  /** The quaternion as three angles, in radians, in the order of `labels`. */
+  toEuler: (rotation: Quaternion) => Vec3;
+  /** Three angles in radians, in the order of `labels`, as a unit quaternion `[qx, qy, qz, qw]`. */
+  fromEuler: (angles: Vec3) => Quaternion;
+  /** The angles' names, shown before each field. Defaults to roll, pitch, yaw. */
+  labels?: readonly [string, string, string] | undefined;
+}
+/** Props of `PoseInput`. */
+interface PoseInputProps {
+  /** The pose, in the wire form. */
+  value: PoseValue;
+  /** Called with a new pose (new arrays) whenever a component changes. */
+  onValueChange?: ((value: PoseValue) => void) | undefined;
+  /** The quaternion ↔ angles conversion and the angles' names. Required: see `RotationView`. */
+  rotationView: RotationView;
+  /** Show and edit the translation in metres (the default) or millimetres. The value is always metres. */
+  translationUnit?: "m" | "mm" | undefined;
+  /** Decimals of the translation. Defaults to 4 for m, 1 for mm. */
+  translationPrecision?: number | undefined;
+  /** Decimals of the angles, in degrees. Defaults to 2. */
+  rotationPrecision?: number | undefined;
+  /** Show a compact mono readout instead of fields. */
+  readOnly?: boolean | undefined;
+  /** Blocks every field. */
+  disabled?: boolean | undefined;
+  /** Names the pose (`role="group"`). Defaults to "Pose". */
+  "aria-label"?: string | undefined;
+  /** Merged with the component's own classes through `cn`. */
+  className?: string | undefined;
+}
+/**
+ * An SE(3) pose shown and edited as a translation (m or mm) and three angles in degrees,
+ * reading and writing the wire form `{ rotation: [qx, qy, qz, qw], translation: [tx, ty, tz] }`.
+ *
+ * The angles come from `rotationView.toEuler` and go back through `rotationView.fromEuler`.
+ * The angles as typed are kept while the pose they produced is the one shown, so a yaw of
+ * 190° is not redisplayed as −170° and a gimbal-locked pitch does not scramble the other two
+ * angles mid-edit.
+ *
+ * A `role="group"` named by `aria-label`, holding two `VectorInput` groups ("Translation",
+ * "Rotation"). With `readOnly` it renders a `ReadoutStrip` instead
+ * (`t 0.1000 0.2000 0.3000 m · rpy 0.00 90.00 0.00 °`). The root carries `data-readonly`.
+ */
+export declare function PoseInput({ value, onValueChange, rotationView, translationUnit, translationPrecision, rotationPrecision, readOnly, disabled, "aria-label": ariaLabel, className }: PoseInputProps): import("react").JSX.Element;
+//#endregion
 //#region src/components/ui/SegmentedControl.d.ts
 /**
  * A choice among two or three, shown as a strip of segments (native radios in one group, so
@@ -840,6 +920,46 @@ export declare function InfoHint({ children, label, icon: Icon }: {
   icon?: LucideIcon | undefined;
 }): import("react").JSX.Element;
 //#endregion
+//#region src/components/ui/VectorInput.d.ts
+/** Props of `VectorInput`. */
+interface VectorInputProps {
+  /** The components. Its length is the number of fields. */
+  value: readonly number[];
+  /** Called with the whole vector (a new array) whenever one component changes to a valid number. */
+  onValueChange?: ((value: number[]) => void) | undefined;
+  /** Each component's label, shown before its field and naming it. Defaults to x, y, z, w. */
+  labels?: readonly string[] | undefined;
+  /** The unit of every component, shown once after the row (`m`, `mm`, `°`). */
+  unit?: string | undefined;
+  /** The arrow-key step. Defaults to `any` (the browser then steps by 1). */
+  step?: number | undefined;
+  /** Decimals shown when a field is not being edited. Defaults to 3. */
+  precision?: number | undefined;
+  /** The smallest accepted component. */
+  min?: number | undefined;
+  /** The largest accepted component. */
+  max?: number | undefined;
+  /** Show the values as a compact mono readout instead of fields. */
+  readOnly?: boolean | undefined;
+  /** Blocks every field. */
+  disabled?: boolean | undefined;
+  /** Names the group (`role="group"`). */
+  "aria-label": string;
+  /** Merged with the row's own classes through `cn`. */
+  className?: string | undefined;
+}
+/**
+ * A row of number fields editing one small vector, with the axis labels before the fields
+ * and the unit once after them.
+ *
+ * Controlled. A `role="group"` named by `aria-label`, each field named by its label and
+ * described by the unit. While a field has focus it shows what is typed; on blur or Enter it
+ * shows the value at `precision`; Escape restores the value it had on focus. With `readOnly`
+ * it renders a `ReadoutStrip` (`x 0.100 m · y …`) instead. The row carries `data-readonly`
+ * and `data-disabled`.
+ */
+export declare function VectorInput({ value, onValueChange, labels, unit, step, precision, min, max, readOnly, disabled, "aria-label": ariaLabel, className }: VectorInputProps): import("react").JSX.Element;
+//#endregion
 //#region src/components/Tabs.d.ts
 /** One tab of a `Tabs` strip. */
 interface TabItem<Id extends string> {
@@ -879,5 +999,5 @@ export declare function Tabs<Id extends string>({ items, active, onSelect, label
   className?: string | undefined;
 }): import("react").JSX.Element;
 //#endregion
-export type { BackLink, ButtonSize, ButtonVariant, CalloutTone, Column, Density, MeasureTone, ReadoutItem, SelectOption, TabItem, ThemeChoice, Tone };
+export type { BackLink, ButtonSize, ButtonVariant, CalloutTone, Column, Density, MeasureTone, NumberInputProps, PoseInputProps, PoseValue, Quaternion, ReadoutItem, RotationView, SelectOption, TabItem, ThemeChoice, Tone, Vec3, VectorInputProps };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -813,12 +813,24 @@ function Input({ className, "aria-describedby": describedBy, ...rest }) {
 	});
 }
 /**
-* A number, with the schema's own bounds attached.
+* A number, with the schema's own bounds attached and, optionally, its unit written in the
+* field.
 *
 * `font-mono` because these are read as quantities and compared down a column. Takes every
-* `<input>` prop, `ref` included (`type` is always `number`).
+* `<input>` prop, `ref` included (`type` is always `number`); `className`, `style` and `ref`
+* always go to the `<input>`.
+*
+* With a `unit`, the input sits in a `relative` full-width wrapper carrying `data-unit`, keeps
+* room on its right for the unit, and is described by it; size such a field through its
+* container. Without one — or with `""` — the markup is exactly the plain input.
 */
-function NumberInput({ className, "aria-describedby": describedBy, ...rest }) {
+function NumberInput({ unit, ...props }) {
+	return unit === void 0 || unit === "" ? /* @__PURE__ */ jsx(PlainNumberInput, { ...props }) : /* @__PURE__ */ jsx(UnitNumberInput, {
+		unit,
+		...props
+	});
+}
+function PlainNumberInput({ className, "aria-describedby": describedBy, ...rest }) {
 	return /* @__PURE__ */ jsx("input", {
 		...useFieldDescription(describedBy),
 		...rest,
@@ -827,6 +839,26 @@ function NumberInput({ className, "aria-describedby": describedBy, ...rest }) {
 		className: cn(controlClasses, useControlHeight(), "font-mono tabular-nums", className)
 	});
 }
+function UnitNumberInput({ unit, style, "aria-describedby": describedBy, ...rest }) {
+	const unitId = useId();
+	return /* @__PURE__ */ jsxs("span", {
+		"data-unit": unit,
+		className: "relative flex w-full min-w-0 items-center",
+		children: [/* @__PURE__ */ jsx(PlainNumberInput, {
+			...rest,
+			"aria-describedby": describedBy ? `${describedBy} ${unitId}` : unitId,
+			style: {
+				paddingInlineEnd: `calc(${unit.length}ch + 1rem)`,
+				...style
+			}
+		}), /* @__PURE__ */ jsx("span", {
+			id: unitId,
+			"aria-hidden": true,
+			className: "pointer-events-none absolute inset-y-0 right-2.5 flex items-center font-mono text-xs text-fg-subtle select-none",
+			children: unit
+		})]
+	});
+}
 /**
 * Multi-line text — set in mono, for JSON and lists. Takes every `<textarea>` prop, `ref`
 * included.
@@ -974,6 +1006,250 @@ function ReadoutStrip({ items, className }) {
 	});
 }
 //#endregion
+//#region src/components/ui/numberText.ts
+/**
+* A number at a fixed number of decimals, without a negative zero (`-0.000` reads as a sign
+* error in a coordinate readout).
+*
+* @param value - The number. Non-finite values print as `NaN`, `Infinity`, `-Infinity`.
+* @param precision - Decimals, 0–20.
+* @returns The text.
+*/
+function formatNumber(value, precision) {
+	if (!Number.isFinite(value)) return String(value);
+	const text = value.toFixed(precision);
+	return /^-0(?:\.0*)?$/.test(text) ? text.slice(1) : text;
+}
+/**
+* The number a field's text means, if it means one.
+*
+* @param text - What is in the field.
+* @returns The number, or `null` for empty, partial (`-`, `1e`) or non-numeric text.
+*/
+function parseNumber(text) {
+	const trimmed = text.trim();
+	if (trimmed === "") return null;
+	const value = Number(trimmed);
+	return Number.isFinite(value) ? value : null;
+}
+//#endregion
+//#region src/components/ui/VectorInput.tsx
+const DEFAULT_LABELS = [
+	"x",
+	"y",
+	"z",
+	"w"
+];
+/**
+* A row of number fields editing one small vector, with the axis labels before the fields
+* and the unit once after them.
+*
+* Controlled. A `role="group"` named by `aria-label`, each field named by its label and
+* described by the unit. While a field has focus it shows what is typed; on blur or Enter it
+* shows the value at `precision`; Escape restores the value it had on focus. With `readOnly`
+* it renders a `ReadoutStrip` (`x 0.100 m · y …`) instead. The row carries `data-readonly`
+* and `data-disabled`.
+*/
+function VectorInput({ value, onValueChange, labels = DEFAULT_LABELS, unit, step, precision = 3, min, max, readOnly = false, disabled = false, "aria-label": ariaLabel, className }) {
+	const unitId = useId();
+	const labelOf = (index) => labels[index] ?? String(index);
+	if (readOnly) return /* @__PURE__ */ jsx("div", {
+		role: "group",
+		"aria-label": ariaLabel,
+		"data-readonly": "",
+		className: cn("min-w-0", className),
+		children: /* @__PURE__ */ jsx(ReadoutStrip, { items: value.map((component, index) => ({
+			label: labelOf(index),
+			value: unit ? `${formatNumber(component, precision)} ${unit}` : formatNumber(component, precision)
+		})) })
+	});
+	const change = (index, component) => {
+		if (component === value[index]) return;
+		onValueChange?.(value.map((current, i) => i === index ? component : current));
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		role: "group",
+		"aria-label": ariaLabel,
+		"data-disabled": disabled ? "" : void 0,
+		className: cn("flex min-w-0 items-center gap-1.5", className),
+		children: [value.map((component, index) => /* @__PURE__ */ jsxs("label", {
+			className: "flex min-w-0 flex-1 items-center gap-1",
+			children: [/* @__PURE__ */ jsx("span", {
+				className: "shrink-0 font-mono text-[11px] text-fg-subtle",
+				children: labelOf(index)
+			}), /* @__PURE__ */ jsx(ComponentField, {
+				value: component,
+				precision,
+				step,
+				min,
+				max,
+				disabled,
+				describedBy: unit ? unitId : void 0,
+				onCommit: (next) => change(index, next)
+			})]
+		}, index)), unit && /* @__PURE__ */ jsx("span", {
+			id: unitId,
+			className: "shrink-0 font-mono text-xs text-fg-subtle",
+			children: unit
+		})]
+	});
+}
+/** One component: formatted at rest, the typed text while focused. */
+function ComponentField({ value, precision, step, min, max, disabled, describedBy, onCommit }) {
+	const [draft, setDraft] = useState(null);
+	const formatted = formatNumber(value, precision);
+	const onKeyDown = (event) => {
+		if (event.key === "Enter") setDraft((current) => current && {
+			...current,
+			text: formatted
+		});
+		else if (event.key === "Escape" && draft) {
+			event.preventDefault();
+			onCommit(draft.initial);
+			setDraft({
+				...draft,
+				text: formatNumber(draft.initial, precision)
+			});
+		}
+	};
+	return /* @__PURE__ */ jsx(NumberInput, {
+		value: draft?.text ?? formatted,
+		step: step ?? "any",
+		min,
+		max,
+		disabled,
+		"aria-describedby": describedBy,
+		onFocus: () => setDraft({
+			text: formatted,
+			initial: value
+		}),
+		onBlur: () => setDraft(null),
+		onKeyDown,
+		onChange: (event) => {
+			const text = event.currentTarget.value;
+			setDraft((current) => ({
+				text,
+				initial: current?.initial ?? value
+			}));
+			const parsed = parseNumber(text);
+			if (parsed !== null) onCommit(parsed);
+		},
+		className: "min-w-0 px-1.5"
+	});
+}
+//#endregion
+//#region src/components/ui/PoseInput.tsx
+const DEGREES = 180 / Math.PI;
+const DEFAULT_ANGLE_LABELS = [
+	"roll",
+	"pitch",
+	"yaw"
+];
+const sameQuaternion = (a, b) => a.every((component, index) => component === b[index]);
+/**
+* An SE(3) pose shown and edited as a translation (m or mm) and three angles in degrees,
+* reading and writing the wire form `{ rotation: [qx, qy, qz, qw], translation: [tx, ty, tz] }`.
+*
+* The angles come from `rotationView.toEuler` and go back through `rotationView.fromEuler`.
+* The angles as typed are kept while the pose they produced is the one shown, so a yaw of
+* 190° is not redisplayed as −170° and a gimbal-locked pitch does not scramble the other two
+* angles mid-edit.
+*
+* A `role="group"` named by `aria-label`, holding two `VectorInput` groups ("Translation",
+* "Rotation"). With `readOnly` it renders a `ReadoutStrip` instead
+* (`t 0.1000 0.2000 0.3000 m · rpy 0.00 90.00 0.00 °`). The root carries `data-readonly`.
+*/
+function PoseInput({ value, onValueChange, rotationView, translationUnit = "m", translationPrecision, rotationPrecision = 2, readOnly = false, disabled = false, "aria-label": ariaLabel = "Pose", className }) {
+	const density = useDensity();
+	const [typed, setTyped] = useState(null);
+	const scale = translationUnit === "mm" ? 1e3 : 1;
+	const tPrecision = translationPrecision ?? (translationUnit === "mm" ? 1 : 4);
+	const translation = value.translation.map((component) => component * scale);
+	const degrees = (typed !== null && sameQuaternion(typed.rotation, value.rotation) ? typed.angles : rotationView.toEuler(value.rotation)).map((angle) => angle * DEGREES);
+	const angleLabels = rotationView.labels ?? DEFAULT_ANGLE_LABELS;
+	if (readOnly) {
+		const join = (values, precision) => values.map((component) => formatNumber(component, precision)).join(" ");
+		return /* @__PURE__ */ jsx("div", {
+			role: "group",
+			"aria-label": ariaLabel,
+			"data-readonly": "",
+			className: cn("min-w-0", className),
+			children: /* @__PURE__ */ jsx(ReadoutStrip, { items: [{
+				label: "t",
+				value: `${join(translation, tPrecision)} ${translationUnit}`
+			}, {
+				label: "rpy",
+				value: `${join(degrees, rotationPrecision)} °`
+			}] })
+		});
+	}
+	const onTranslation = (next) => {
+		const [x = 0, y = 0, z = 0] = next.map((component) => component / scale);
+		onValueChange?.({
+			rotation: value.rotation,
+			translation: [
+				x,
+				y,
+				z
+			]
+		});
+	};
+	const onRotation = (next) => {
+		const [a = 0, b = 0, c = 0] = next.map((angle) => angle / DEGREES);
+		const angles = [
+			a,
+			b,
+			c
+		];
+		const rotation = rotationView.fromEuler(angles);
+		setTyped({
+			rotation,
+			angles
+		});
+		onValueChange?.({
+			rotation,
+			translation: value.translation
+		});
+	};
+	const rowLabel = cn("text-fg-muted", byDensity(density, "text-xs", "text-[11px]"));
+	return /* @__PURE__ */ jsxs("div", {
+		role: "group",
+		"aria-label": ariaLabel,
+		className: cn("grid min-w-0 grid-cols-[auto_minmax(0,1fr)] items-center gap-x-2", byDensity(density, "gap-y-2", "gap-y-1"), className),
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				"aria-hidden": true,
+				className: rowLabel,
+				children: "Translation"
+			}),
+			/* @__PURE__ */ jsx(VectorInput, {
+				"aria-label": "Translation",
+				value: translation,
+				onValueChange: onTranslation,
+				unit: translationUnit,
+				precision: tPrecision,
+				step: translationUnit === "mm" ? 1 : .001,
+				disabled
+			}),
+			/* @__PURE__ */ jsx("span", {
+				"aria-hidden": true,
+				className: rowLabel,
+				children: "Rotation"
+			}),
+			/* @__PURE__ */ jsx(VectorInput, {
+				"aria-label": "Rotation",
+				value: degrees,
+				onValueChange: onRotation,
+				labels: angleLabels,
+				unit: "°",
+				precision: rotationPrecision,
+				step: 1,
+				disabled
+			})
+		]
+	});
+}
+//#endregion
 //#region src/components/ui/SegmentedControl.tsx
 /**
 * A choice among two or three, shown as a strip of segments (native radios in one group, so
@@ -1344,6 +1620,6 @@ function Tabs({ items, active, onSelect, label, idPrefix, className }) {
 	});
 }
 //#endregion
-export { Badge, Button, ButtonLink, Callout, Checkbox, ConfirmDialog, CountRun, DEFAULT_THEME_STORAGE_KEY, DensityProvider, Dialog, DialogClose, Disclosure, Empty, ErrorBox, Field, InfoHint, Input, NumberInput, PageHeader, Panel, ProgressBar, ReadoutStrip, Section, SegmentedControl, Select, Skeleton, SkeletonRows, Slider, StatusDot, Switch, Table, Tabs, Textarea, ThemeToggle, ToggleChip, Tooltip, TooltipProvider, buttonClasses, byDensity, cn, controlClasses, focusRing, focusRingInset, initTheme, inputClasses, readThemeChoice, resolveTheme, setThemeChoice, toneColor, useControlHeight, useDensity };
+export { Badge, Button, ButtonLink, Callout, Checkbox, ConfirmDialog, CountRun, DEFAULT_THEME_STORAGE_KEY, DensityProvider, Dialog, DialogClose, Disclosure, Empty, ErrorBox, Field, InfoHint, Input, NumberInput, PageHeader, Panel, PoseInput, ProgressBar, ReadoutStrip, Section, SegmentedControl, Select, Skeleton, SkeletonRows, Slider, StatusDot, Switch, Table, Tabs, Textarea, ThemeToggle, ToggleChip, Tooltip, TooltipProvider, VectorInput, buttonClasses, byDensity, cn, controlClasses, focusRing, focusRingInset, initTheme, inputClasses, readThemeChoice, resolveTheme, setThemeChoice, toneColor, useControlHeight, useDensity };
 
 //# sourceMappingURL=index.js.map