@vitavision/ui 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitavision/ui",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "The vitavision instrument design system: Tailwind v4 tokens, theme, and React primitives.",
   "license": "MIT OR Apache-2.0",
   "repository": {
@@ -28,6 +28,7 @@
       "import": "./dist/index.js"
     },
     "./styles.css": "./src/styles.css",
+    "./fonts.css": "./src/fonts/fonts.css",
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/src/components/ui/Input.tsx

@@ -5,7 +5,7 @@
  * can still pick up the shared palette and focus treatment.
  */
 
-import type { ComponentProps } from "react";
+import { useId, type ComponentProps } from "react";
 
 import { byDensity, useDensity } from "./Density";
 import { useFieldDescription } from "./Field";
@@ -54,22 +54,46 @@ export function Input({ className, "aria-describedby": describedBy, ...rest }: C
   );
 }
 
+/** Props of `NumberInput`: every `<input>` prop, `ref` included, with numeric bounds and a `unit`. */
+export type NumberInputProps = Omit<ComponentProps<"input">, "min" | "max"> & {
+  /** The smallest accepted value. */
+  min?: number | undefined;
+  /** The largest accepted value. */
+  max?: number | undefined;
+  /**
+   * 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.
+ * 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.
  */
-export function NumberInput({
+export function NumberInput({ unit, ...props }: NumberInputProps) {
+  return unit === undefined || unit === "" ? (
+    <PlainNumberInput {...props} />
+  ) : (
+    <UnitNumberInput unit={unit} {...props} />
+  );
+}
+
+function PlainNumberInput({
   className,
   "aria-describedby": describedBy,
   ...rest
-}: Omit<ComponentProps<"input">, "min" | "max"> & {
-  /** The smallest accepted value. */
-  min?: number | undefined;
-  /** The largest accepted value. */
-  max?: number | undefined;
-}) {
+}: Omit<NumberInputProps, "unit">) {
   return (
     <input
       {...useFieldDescription(describedBy)}
@@ -81,6 +105,39 @@ export function NumberInput({
   );
 }
 
+/*
+ * A component of its own so that only a field with a unit calls `useId`: a plain
+ * `NumberInput` stays byte-identical to the one before `unit` existed, down to the ids React
+ * hands the elements rendered after it.
+ */
+function UnitNumberInput({
+  unit,
+  style,
+  "aria-describedby": describedBy,
+  ...rest
+}: Omit<NumberInputProps, "unit"> & { unit: string }) {
+  const unitId = useId();
+  return (
+    <span data-unit={unit} className="relative flex w-full min-w-0 items-center">
+      <PlainNumberInput
+        {...rest}
+        aria-describedby={describedBy ? `${describedBy} ${unitId}` : unitId}
+        // Room for the unit: its width in the unit's own characters, plus the field's padding.
+        style={{ paddingInlineEnd: `calc(${unit.length}ch + 1rem)`, ...style }}
+      />
+      {/* `aria-hidden` keeps the unit out of the field's *name* when a `<label>` wraps it;
+          `aria-describedby` still reads it, as the description. */}
+      <span
+        id={unitId}
+        aria-hidden
+        className="pointer-events-none absolute inset-y-0 right-2.5 flex items-center font-mono text-xs text-fg-subtle select-none"
+      >
+        {unit}
+      </span>
+    </span>
+  );
+}
+
 /**
  * Multi-line text — set in mono, for JSON and lists. Takes every `<textarea>` prop, `ref`
  * included.

package/src/components/ui/PoseInput.tsx

@@ -0,0 +1,181 @@
+/*
+ * A rigid transform, edited the way people think about one.
+ *
+ * Poses travel as `{ rotation: [qx, qy, qz, qw], translation: [tx, ty, tz] }` — the SE(3) wire
+ * form — because a quaternion is the honest representation. Nobody edits one by hand,
+ * though: a rotation is read and typed as roll, pitch and yaw in degrees. This component
+ * shows that view and writes back the wire form.
+ *
+ * It owns no rotation mathematics. Which Euler convention "roll, pitch, yaw" means — the
+ * axis order, intrinsic or extrinsic — is a decision of the 3D package that defines the
+ * frames, so the conversion is passed in as a `RotationView`. This package stays pure UI.
+ */
+
+import { useState } from "react";
+
+import { byDensity, useDensity } from "./Density";
+import { ReadoutStrip } from "./Panel";
+import { cn } from "./cn";
+import { formatNumber } from "./numberText";
+import { VectorInput } from "./VectorInput";
+
+/** Three numbers: a translation `[tx, ty, tz]`, or Euler angles. */
+export type Vec3 = readonly [number, number, number];
+
+/** A unit quaternion in the wire order `[qx, qy, qz, qw]` (scalar last). */
+export 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]`.
+ */
+export 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.
+ */
+export 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`. */
+export 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;
+}
+
+const DEGREES = 180 / Math.PI;
+const DEFAULT_ANGLE_LABELS = ["roll", "pitch", "yaw"] as const;
+
+const sameQuaternion = (a: Quaternion, b: Quaternion) => 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`.
+ */
+export function PoseInput({
+  value,
+  onValueChange,
+  rotationView,
+  translationUnit = "m",
+  translationPrecision,
+  rotationPrecision = 2,
+  readOnly = false,
+  disabled = false,
+  "aria-label": ariaLabel = "Pose",
+  className,
+}: PoseInputProps) {
+  const density = useDensity();
+  // The angles last typed, and the quaternion they became.
+  const [typed, setTyped] = useState<{ rotation: Quaternion; angles: Vec3 } | null>(null);
+
+  const scale = translationUnit === "mm" ? 1000 : 1;
+  const tPrecision = translationPrecision ?? (translationUnit === "mm" ? 1 : 4);
+  const translation = value.translation.map((component) => component * scale);
+  const radians =
+    typed !== null && sameQuaternion(typed.rotation, value.rotation) ? typed.angles : rotationView.toEuler(value.rotation);
+  const degrees = radians.map((angle) => angle * DEGREES);
+  const angleLabels = rotationView.labels ?? DEFAULT_ANGLE_LABELS;
+
+  if (readOnly) {
+    const join = (values: readonly number[], precision: number) =>
+      values.map((component) => formatNumber(component, precision)).join(" ");
+    return (
+      <div role="group" aria-label={ariaLabel} data-readonly="" className={cn("min-w-0", className)}>
+        <ReadoutStrip
+          items={[
+            { label: "t", value: `${join(translation, tPrecision)} ${translationUnit}` },
+            { label: "rpy", value: `${join(degrees, rotationPrecision)} °` },
+          ]}
+        />
+      </div>
+    );
+  }
+
+  const onTranslation = (next: number[]) => {
+    const [x = 0, y = 0, z = 0] = next.map((component) => component / scale);
+    onValueChange?.({ rotation: value.rotation, translation: [x, y, z] });
+  };
+
+  const onRotation = (next: number[]) => {
+    const [a = 0, b = 0, c = 0] = next.map((angle) => angle / DEGREES);
+    const angles: Vec3 = [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 (
+    <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)}
+    >
+      <span aria-hidden className={rowLabel}>
+        Translation
+      </span>
+      <VectorInput
+        aria-label="Translation"
+        value={translation}
+        onValueChange={onTranslation}
+        unit={translationUnit}
+        precision={tPrecision}
+        step={translationUnit === "mm" ? 1 : 0.001}
+        disabled={disabled}
+      />
+      <span aria-hidden className={rowLabel}>
+        Rotation
+      </span>
+      <VectorInput
+        aria-label="Rotation"
+        value={degrees}
+        onValueChange={onRotation}
+        labels={angleLabels}
+        unit="°"
+        precision={rotationPrecision}
+        step={1}
+        disabled={disabled}
+      />
+    </div>
+  );
+}

package/src/components/ui/Select.tsx

@@ -16,6 +16,7 @@ import { Check, ChevronDown } from "lucide-react";
 import { useState } from "react";
 
 import { useFieldDescription } from "./Field";
+import { useControlHeight } from "./Input";
 import { cn, focusRingInset } from "./cn";
 
 const UNSET_SENTINEL = "__unset__";
@@ -72,6 +73,8 @@ export function Select({
 }) {
   const [open, setOpen] = useState(false);
   const described = useFieldDescription(ownDescribedBy);
+  // The trigger is a control like any input: 32 px comfortable, 28 px compact.
+  const height = useControlHeight();
 
   return (
     <RadixSelect.Root
@@ -91,7 +94,8 @@ export function Select({
         // order. Focus returns to it on close all the same.
         tabIndex={open ? -1 : undefined}
         className={cn(
-          "flex h-8 w-full items-center justify-between gap-2 rounded-control border border-line-strong bg-raised px-2.5 text-sm text-fg",
+          "flex w-full items-center justify-between gap-2 rounded-control border border-line-strong bg-raised px-2.5 text-sm text-fg",
+          height,
           "transition-colors hover:border-fg-subtle",
           "disabled:cursor-not-allowed disabled:opacity-50",
           "data-[placeholder]:text-fg-subtle",

package/src/components/ui/VectorInput.tsx

@@ -0,0 +1,183 @@
+/*
+ * A small vector — a position, a set of angles, a scale — edited as one row.
+ *
+ * Three separate `Field`s for x, y and z spend three labels and three rows on what a reader
+ * thinks of as one quantity. This is one row: a quiet axis letter before each number, the
+ * unit once at the end, and one name for the whole group.
+ *
+ * Each field keeps the text being typed while it has focus and shows the formatted value
+ * otherwise (see `numberText.ts`), so `precision` never fights the cursor. Every valid
+ * keystroke is reported, so whatever the vector drives follows the typing.
+ */
+
+import { useId, useState } from "react";
+import type { KeyboardEvent } from "react";
+
+import { NumberInput } from "./Input";
+import { ReadoutStrip } from "./Panel";
+import { cn } from "./cn";
+import { formatNumber, parseNumber } from "./numberText";
+
+const DEFAULT_LABELS = ["x", "y", "z", "w"];
+
+/** Props of `VectorInput`. */
+export 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 function VectorInput({
+  value,
+  onValueChange,
+  labels = DEFAULT_LABELS,
+  unit,
+  step,
+  precision = 3,
+  min,
+  max,
+  readOnly = false,
+  disabled = false,
+  "aria-label": ariaLabel,
+  className,
+}: VectorInputProps) {
+  const unitId = useId();
+  const labelOf = (index: number) => labels[index] ?? String(index);
+
+  if (readOnly) {
+    return (
+      <div role="group" aria-label={ariaLabel} data-readonly="" className={cn("min-w-0", className)}>
+        <ReadoutStrip
+          items={value.map((component, index) => ({
+            label: labelOf(index),
+            value: unit ? `${formatNumber(component, precision)} ${unit}` : formatNumber(component, precision),
+          }))}
+        />
+      </div>
+    );
+  }
+
+  const change = (index: number, component: number) => {
+    if (component === value[index]) return;
+    onValueChange?.(value.map((current, i) => (i === index ? component : current)));
+  };
+
+  return (
+    <div
+      role="group"
+      aria-label={ariaLabel}
+      data-disabled={disabled ? "" : undefined}
+      className={cn("flex min-w-0 items-center gap-1.5", className)}
+    >
+      {value.map((component, index) => (
+        // The components are positional: index is their identity.
+        // eslint-disable-next-line @eslint-react/no-array-index-key -- see above
+        <label key={index} className="flex min-w-0 flex-1 items-center gap-1">
+          <span className="shrink-0 font-mono text-[11px] text-fg-subtle">{labelOf(index)}</span>
+          <ComponentField
+            value={component}
+            precision={precision}
+            step={step}
+            min={min}
+            max={max}
+            disabled={disabled}
+            describedBy={unit ? unitId : undefined}
+            onCommit={(next) => change(index, next)}
+          />
+        </label>
+      ))}
+      {unit && (
+        <span id={unitId} className="shrink-0 font-mono text-xs text-fg-subtle">
+          {unit}
+        </span>
+      )}
+    </div>
+  );
+}
+
+/** One component: formatted at rest, the typed text while focused. */
+function ComponentField({
+  value,
+  precision,
+  step,
+  min,
+  max,
+  disabled,
+  describedBy,
+  onCommit,
+}: {
+  value: number;
+  precision: number;
+  step: number | undefined;
+  min: number | undefined;
+  max: number | undefined;
+  disabled: boolean;
+  describedBy: string | undefined;
+  onCommit: (value: number) => void;
+}) {
+  // Non-null while the field is being edited: the text as typed, and the value on focus.
+  const [draft, setDraft] = useState<{ text: string; initial: number } | null>(null);
+  const formatted = formatNumber(value, precision);
+
+  const onKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    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 (
+    <NumberInput
+      value={draft?.text ?? formatted}
+      step={step ?? "any"}
+      min={min}
+      max={max}
+      disabled={disabled}
+      aria-describedby={describedBy}
+      onFocus={() => setDraft({ text: formatted, initial: value })}
+      onBlur={() => setDraft(null)}
+      onKeyDown={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"
+    />
+  );
+}

package/src/components/ui/index.ts

@@ -29,6 +29,7 @@ export {
   controlClasses,
   inputClasses,
   useControlHeight,
+  type NumberInputProps,
 } from "./Input";
 export {
   PageHeader,
@@ -38,6 +39,14 @@ export {
   Section,
   type ReadoutItem,
 } from "./Panel";
+export {
+  PoseInput,
+  type PoseInputProps,
+  type PoseValue,
+  type Quaternion,
+  type RotationView,
+  type Vec3,
+} from "./PoseInput";
 export { SegmentedControl } from "./SegmentedControl";
 export { Select, type SelectOption } from "./Select";
 export { Slider } from "./Slider";
@@ -45,3 +54,4 @@ export { Table, type Column } from "./Table";
 export { Checkbox, Switch } from "./Toggle";
 export { ToggleChip } from "./ToggleChip";
 export { InfoHint, Tooltip, TooltipProvider } from "./Tooltip";
+export { VectorInput, type VectorInputProps } from "./VectorInput";

package/src/components/ui/numberText.ts

@@ -0,0 +1,36 @@
+/*
+ * Numbers as a field shows them and as a person types them. Internal to this package (used by
+ * `VectorInput` and `PoseInput`); not exported.
+ *
+ * A field bound straight to a number re-formats under the cursor: typing `0.` into a field
+ * showing `0.000` becomes `0` before the next digit arrives. So the multi-number fields keep
+ * the typed text while they have focus and show the formatted value otherwise; these are the
+ * two conversions between the two.
+ */
+
+/**
+ * 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.
+ */
+export function formatNumber(value: number, precision: number): string {
+  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.
+ */
+export function parseNumber(text: string): number | null {
+  const trimmed = text.trim();
+  if (trimmed === "") return null;
+  const value = Number(trimmed);
+  return Number.isFinite(value) ? value : null;
+}