@vitavision/ui 0.7.0 → 0.9.0

package/README.md

@@ -124,11 +124,27 @@ 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` ·
+`Checkbox`, `Switch` · `ToggleChip` · `Toaster`, `toast()` (notifications from anywhere; mount one `<Toaster />` near the root) ·
+`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
@@ -800,6 +880,97 @@ export declare function ToggleChip({ checked, onCheckedChange, children, swatch,
   className?: string | undefined;
 }): import("react").JSX.Element;
 //#endregion
+//#region src/components/ui/toastStore.d.ts
+/** A toast's kind: a fact (`info`), a completed action (`success`), a caveat (`warn`), a failure (`error`). */
+type ToastTone = "info" | "success" | "warn" | "error";
+/** What `toast()` takes. */
+interface ToastOptions {
+  /** One line: what happened. */
+  title: string;
+  /** More detail, and what to do about it. */
+  description?: string | undefined;
+  /** Defaults to `info`. */
+  tone?: ToastTone | undefined;
+  /**
+   * How long it stays, in milliseconds, while not hovered or focused. Defaults to 5000
+   * (8000 for `error`); `Infinity` keeps it until dismissed.
+   */
+  duration?: number | undefined;
+  /** Replace the toast with this id instead of adding one — for progress that updates in place. */
+  id?: string | undefined;
+}
+/** A toast in the store. */
+interface ToastRecord {
+  /** Identifies the toast to `dismiss` and to `id` replacement. */
+  id: string;
+  /** One line: what happened. */
+  title: string;
+  /** More detail, if any. */
+  description: string | undefined;
+  /** Its kind. */
+  tone: ToastTone;
+  /** Milliseconds before it dismisses itself (`Infinity`: never). */
+  duration: number;
+}
+/**
+ * A toast store: what `toast()` writes to and `<Toaster />` reads. Every member may be called
+ * detached.
+ */
+interface ToastStore {
+  /** Add a toast (or replace the one with `options.id`), returning its id. */
+  readonly toast: (options: ToastOptions) => string;
+  /** Remove one toast, or every toast when `id` is omitted. */
+  readonly dismiss: (id?: string) => void;
+  /** The toasts, oldest first. The same array until the store changes. */
+  readonly getSnapshot: () => readonly ToastRecord[];
+  /** Be told when the toasts change; returns the unsubscribe function. */
+  readonly subscribe: (listener: () => void) => () => void;
+}
+/**
+ * A new, empty toast store. The package keeps one (behind `toast()` and the default
+ * `<Toaster />`); create another only to isolate a region or a test.
+ *
+ * @returns The store.
+ */
+export declare function createToastStore(): ToastStore;
+/** The store behind `toast()` and a `<Toaster />` given no `store`. */
+export declare const defaultToastStore: ToastStore;
+/**
+ * Raise a notification, from anywhere — shown by the mounted `<Toaster />`.
+ *
+ * `toast({ title: "Scenario loaded", tone: "success" })`. Pass `id` to update a toast in
+ * place (a progress message that becomes a result). `toast.dismiss(id)` removes one early,
+ * `toast.dismiss()` all of them.
+ *
+ * @param options - The message, its tone and its duration.
+ * @returns The toast's id.
+ */
+export declare const toast: ((options: ToastOptions) => string) & {
+  /** Remove one toast, or every toast when `id` is omitted. */
+  dismiss: (id?: string) => void;
+};
+//#endregion
+//#region src/components/ui/Toaster.d.ts
+/** Props of `Toaster`. */
+interface ToasterProps {
+  /** The store to show. Defaults to the one behind `toast()`. */
+  store?: ToastStore | undefined;
+  /** How many toasts are shown at once; older ones wait. Defaults to 5. */
+  limit?: number | undefined;
+  /** Merged with the stack's own classes through `cn` (it is fixed to the bottom-right corner). */
+  className?: string | undefined;
+}
+/**
+ * The stack of notifications raised with `toast()`. Mount it once, near the root.
+ *
+ * Fixed to the bottom-right corner, newest at the bottom. Each toast dismisses itself after
+ * its `duration`; the countdown pauses while the pointer is over the stack or focus is inside
+ * it. A `section` landmark ("Notifications") holding a polite live region, so new toasts are
+ * announced; an `error` toast is a `role="alert"`, announced at once. Each toast carries
+ * `data-tone` and a "Dismiss" button.
+ */
+export declare function Toaster({ store, limit, className }: ToasterProps): import("react").JSX.Element;
+//#endregion
 //#region src/components/ui/Tooltip.d.ts
 /**
  * Shares one open delay (200 ms) across the tooltips below it. Mount it once near the root:
@@ -840,6 +1011,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 +1090,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, ToastOptions, ToastRecord, ToastStore, ToastTone, ToasterProps, Tone, Vec3, VectorInputProps };
 //# sourceMappingURL=index.d.ts.map