@vitavision/ui 0.8.0 → 0.10.0

package/README.md

@@ -123,12 +123,25 @@ keep independent preferences.
 ### Components
 
 **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` (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`.
+`DialogClose` · `Disclosure` · `DropdownMenu`, `MenuItem`, `MenuCheckboxItem`, `MenuLabel`,
+`MenuSeparator` (a non-modal command and toggle menu) · `Callout`, `Empty`, `ErrorBox`,
+`ProgressBar`, `Skeleton`, `SkeletonRows` · `Field` · `Input`, `NumberInput` (with an optional
+`unit` written in the field; number-valued with `onValueChange`), `Textarea` · `VectorInput`,
+`PoseInput` · `Kbd` · `Listbox` (single choice among options that render their own content) ·
+`PageHeader`, `Panel`, `ReadoutStrip`, `Section` · `Popover`, `PopoverClose` ·
+`SegmentedControl` · `Select` · `Slider` · `Table` ·
+`Checkbox`, `Switch` · `ToggleChip` · `Toaster`, `toast()` (notifications from anywhere; mount one `<Toaster />` near the root) ·
+`InfoHint`, `Tooltip`, `TooltipProvider` ·
+`ThemeToggle` · plus `cn`, `focusRing`, `focusRingInset`, and `formatNumber` / `parseNumber`
+(the text ↔ number helpers behind the number fields).
+
+A number-valued `NumberInput` keeps what is being typed and reports only finite numbers inside
+`[min, max]`, so clearing a field to retype it never passes through 0. `onClear` is for a
+quantity that may be unset:
+
+```tsx
+<NumberInput unit="px" precision={1} min={4} value={roi.width} onValueChange={setWidth} />
+```
 
 `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

package/dist/index.d.ts

@@ -335,6 +335,77 @@ export declare function Disclosure({ summary, count, defaultOpen, className, chi
   children: ReactNode;
 }): import("react").JSX.Element;
 //#endregion
+//#region src/components/ui/DropdownMenu.d.ts
+/** Props of `DropdownMenu`. */
+interface DropdownMenuProps {
+  /** The element that opens it: one focusable element that accepts a ref (Radix `asChild`). */
+  trigger: ReactNode;
+  /** `MenuItem`, `MenuCheckboxItem`, `MenuLabel` and `MenuSeparator` elements. */
+  children: ReactNode;
+  /** Controlled open state. */
+  open?: boolean | undefined;
+  /** Called when it opens or closes. */
+  onOpenChange?: ((open: boolean) => void) | undefined;
+  /** Its alignment along the trigger. Defaults to `start`. */
+  align?: "start" | "center" | "end" | undefined;
+  /** The trigger's side it opens on. Defaults to `bottom`. */
+  side?: "top" | "right" | "bottom" | "left" | undefined;
+  /** Merged with the menu's own classes through `cn`. */
+  className?: string | undefined;
+}
+/**
+ * A menu (`role="menu"`) that opens from `trigger`, with arrow-key navigation, typeahead,
+ * Escape or a press outside to close, and focus returned to the trigger. It is non-modal: the
+ * page behind stays readable and operable. Toggling a `MenuCheckboxItem` keeps the menu open,
+ * so several layers can be switched in one visit.
+ */
+export declare function DropdownMenu({ trigger, children, open, onOpenChange, align, side, className }: DropdownMenuProps): import("react").JSX.Element;
+/** Props of `MenuItem`. */
+interface MenuItemProps {
+  /** The item's text. */
+  children: ReactNode;
+  /** Runs the command. */
+  onSelect?: (() => void) | undefined;
+  /** An icon before the text, in the indicator column. */
+  icon?: ReactNode;
+  /** `defect` for a destructive command. */
+  tone?: "defect" | undefined;
+  /** A shortcut shown at the end of the row, as a `Kbd`. Display only: binding it is the app's. */
+  shortcut?: string | undefined;
+  /** Blocks the item. */
+  disabled?: boolean | undefined;
+}
+/**
+ * A command. `onSelect` runs when it is clicked or chosen with Enter, and the menu then
+ * closes. `tone="defect"` marks a destructive command.
+ */
+export declare function MenuItem({ children, onSelect, shortcut, disabled, icon, tone }: MenuItemProps): import("react").JSX.Element;
+/** Props of `MenuCheckboxItem`. */
+interface MenuCheckboxItemProps {
+  /** The item's text. */
+  children: ReactNode;
+  /** Whether it is on. */
+  checked: boolean;
+  /** Called with the new state. */
+  onCheckedChange: (checked: boolean) => void;
+  /** A shortcut shown at the end of the row, as a `Kbd`. Display only: binding it is the app's. */
+  shortcut?: string | undefined;
+  /** Blocks the item. */
+  disabled?: boolean | undefined;
+}
+/**
+ * A toggle (`role="menuitemcheckbox"`): a layer on or off. A check marks it on. Choosing it
+ * leaves the menu open.
+ */
+export declare function MenuCheckboxItem({ children, checked, onCheckedChange, shortcut, disabled }: MenuCheckboxItemProps): import("react").JSX.Element;
+/** A heading over a group of items, in the eyebrow role. Not focusable. */
+export declare function MenuLabel({ children }: {
+  /** The heading. */
+  children: ReactNode;
+}): import("react").JSX.Element;
+/** A divider between groups of items. */
+export declare function MenuSeparator(): import("react").JSX.Element;
+//#endregion
 //#region src/components/ui/Feedback.d.ts
 /** A callout's kind: a fact (`info`), a caveat (`warning`), a failure (`error`) or `success`. */
 type CalloutTone = "info" | "warning" | "error" | "success";
@@ -460,8 +531,40 @@ 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;
-/** Props of `NumberInput`: every `<input>` prop, `ref` included, with numeric bounds and a `unit`. */
-type NumberInputProps = Omit<ComponentProps<"input">, "min" | "max"> & {
+/**
+ * Props of `NumberInput`: every `<input>` prop, `ref` included, with numeric bounds, a `unit`,
+ * and an optional number-valued API (`onValueChange`, `precision`).
+ */
+type NumberInputProps = Omit<ComponentProps<"input">, "min" | "max" | "value"> & {
+  /**
+   * The value. As text, it is the native input's `value`. With `onValueChange` it is a
+   * number, and `null` shows an empty field.
+   */
+  value?: string | number | readonly string[] | null | undefined;
+  /**
+   * Makes the field number-valued.
+   *
+   * - **While focused** it keeps the text as typed. A keystroke is reported only when the
+   *   text is a finite number inside `[min, max]` and differs from `value`. Empty, partial
+   *   (`-`, `1e`) and out-of-range text is never reported, so clearing a field to retype it
+   *   does not pass through 0, and typing `5` on the way to `50` does not report a value under
+   *   `min`.
+   * - **Enter** shows the value at `precision`. **Escape** restores the value the field had
+   *   on focus.
+   * - **On leaving**, the field shows `value` again.
+   */
+  onValueChange?: ((value: number) => void) | undefined;
+  /**
+   * Called when a number-valued field is committed empty (left, or Enter pressed, with no
+   * text), for a quantity that may be unset. Without it, emptying the field and leaving it
+   * restores `value`.
+   */
+  onClear?: (() => void) | undefined;
+  /**
+   * Decimals shown when a number-valued field is not being edited. Without it the number is
+   * shown as JavaScript prints it.
+   */
+  precision?: number | undefined;
   /** The smallest accepted value. */
   min?: number | undefined;
   /** The largest accepted value. */
@@ -485,14 +588,97 @@ type NumberInputProps = Omit<ComponentProps<"input">, "min" | "max"> & {
  * 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.
+ *
+ * With `onValueChange` the field is number-valued: `value` is a number (`null` shows empty), the
+ * typed text survives while the field has focus, and only finite numbers inside `[min, max]`
+ * are reported (see `onValueChange`; `onClear` reports an emptied field). Without it the field
+ * is the native text-valued input.
  */
-export declare function NumberInput({ unit, ...props }: NumberInputProps): import("react").JSX.Element;
+export declare function NumberInput({ onValueChange, onClear, precision, ...props }: NumberInputProps): import("react").JSX.Element;
 /**
  * Multi-line text — set in mono, for JSON and lists. Takes every `<textarea>` prop, `ref`
  * included.
  */
 export declare function Textarea({ className, "aria-describedby": describedBy, ...rest }: ComponentProps<"textarea">): import("react").JSX.Element;
 //#endregion
+//#region src/components/ui/Kbd.d.ts
+/**
+ * A keyboard key or chord (`F`, `⌘K`, `[`), set in mono on a raised key cap.
+ *
+ * Renders `<kbd>`, which screen readers announce as text. Write the key as the user's keyboard
+ * labels it; for a chord, one `Kbd` with the whole chord reads better than several. Takes
+ * every `<kbd>` prop, `ref` included.
+ */
+export declare function Kbd({ className, ...rest }: ComponentProps<"kbd">): import("react").JSX.Element;
+//#endregion
+//#region src/components/ui/Listbox.d.ts
+/** One option of a `Listbox`. */
+interface ListboxOption {
+  /** Its value, unique in the list. */
+  value: string;
+  /** Its name: the default rendering, and what a screen reader announces. */
+  label: string;
+  /** A second line under the label, in the default rendering. */
+  description?: string | undefined;
+  /** Shown but not choosable. */
+  disabled?: boolean | undefined;
+}
+/** What `renderOption` is told about an option. */
+interface ListboxOptionState {
+  /** It is the value. */
+  selected: boolean;
+  /** It has the keyboard cursor or the pointer. */
+  active: boolean;
+}
+/** Props of `Listbox`. */
+interface ListboxProps {
+  /** The options, in order. */
+  options: readonly ListboxOption[];
+  /** The selected value, or `null` for none. */
+  value: string | null;
+  /** Called with the value of the option chosen by click, Enter or Space. */
+  onValueChange?: ((value: string) => void) | undefined;
+  /**
+   * Renders an option's content (the row keeps its own padding, states and accessibility).
+   * Defaults to the label, with the description under it.
+   */
+  renderOption?: ((option: ListboxOption, state: ListboxOptionState) => ReactNode) | undefined;
+  /** Names the list. */
+  "aria-label": string;
+  /** Focus the list when it mounts, e.g. when it opens in a `Popover`. */
+  autoFocus?: boolean | undefined;
+  /** Merged with the list's own classes through `cn`. */
+  className?: string | undefined;
+}
+/**
+ * A single-select list (`role="listbox"`) of options that each render their own content.
+ *
+ * The list is one tab stop. The arrow keys, Home, End and Page keys move the active option
+ * (`aria-activedescendant`), skipping disabled ones, and Enter or Space choose it. A click
+ * chooses the option under the pointer. Controlled: the caller keeps `value`. Each option
+ * carries `aria-selected`, `data-selected` and `data-active`; the list scrolls the active
+ * option into view.
+ */
+export declare function Listbox({ options, value, onValueChange, renderOption, "aria-label": ariaLabel, autoFocus, className }: ListboxProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/ui/numberText.d.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.
+ */
+export declare function formatNumber(value: number, precision: number): string;
+/**
+ * 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 declare function parseNumber(text: string): number | null;
+//#endregion
 //#region src/components/ui/Panel.d.ts
 /**
  * A bordered surface with an optional header (a title and actions) above a padded body.
@@ -587,6 +773,49 @@ export declare function ReadoutStrip({ items, className }: {
   className?: string | undefined;
 }): import("react").JSX.Element | null;
 //#endregion
+//#region src/components/ui/Popover.d.ts
+/** Props of `Popover`. */
+interface PopoverProps {
+  /**
+   * The element that opens it: one focusable element that accepts a ref (Radix `asChild`).
+   * It carries `aria-expanded` and `data-state` (`open` / `closed`).
+   */
+  trigger: ReactNode;
+  /** The content. */
+  children: ReactNode;
+  /** Controlled open state. */
+  open?: boolean | undefined;
+  /** Initial open state when uncontrolled. */
+  defaultOpen?: boolean | undefined;
+  /** Called when it opens or closes. */
+  onOpenChange?: ((open: boolean) => void) | undefined;
+  /** The trigger's side it opens on. Defaults to `bottom`. */
+  side?: "top" | "right" | "bottom" | "left" | undefined;
+  /** Its alignment along that side. Defaults to `start`. */
+  align?: "start" | "center" | "end" | undefined;
+  /** Names the content (`aria-label`), when nothing inside it does. */
+  "aria-label"?: string | undefined;
+  /** Merged with the content's own classes through `cn`. */
+  className?: string | undefined;
+}
+/**
+ * Floating content anchored to `trigger`, on the `overlay` surface with a shadow (floating
+ * layers are the only ones that cast one).
+ *
+ * Controlled (`open` / `onOpenChange`) or not (`defaultOpen`). Focus moves into the content
+ * when it opens and back to the trigger when it closes. Escape and a press outside close it.
+ * The content carries `data-state` and `data-side`.
+ */
+export declare function Popover({ trigger, children, open, defaultOpen, onOpenChange, side, align, "aria-label": ariaLabel, className }: PopoverProps): import("react").JSX.Element;
+/**
+ * Closes the surrounding `Popover` when its child is activated. Wraps one element (Radix
+ * `asChild`).
+ */
+export declare function PopoverClose({ children }: {
+  /** The one element that closes the popover. */
+  children: ReactNode;
+}): import("react").JSX.Element;
+//#endregion
 //#region src/components/ui/PoseInput.d.ts
 /** Three numbers: a translation `[tx, ty, tz]`, or Euler angles. */
 type Vec3 = readonly [number, number, number];
@@ -880,6 +1109,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:
@@ -952,8 +1272,8 @@ interface VectorInputProps {
  * 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
+ * Controlled. A `role="group"` named by `aria-label`. Each field is named by the group and its
+ * label ("Translation x"), so two vectors on one screen stay apart, and is 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`.
@@ -999,5 +1319,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, NumberInputProps, PoseInputProps, PoseValue, Quaternion, ReadoutItem, RotationView, SelectOption, TabItem, ThemeChoice, Tone, Vec3, VectorInputProps };
+export type { BackLink, ButtonSize, ButtonVariant, CalloutTone, Column, Density, DropdownMenuProps, ListboxOption, ListboxOptionState, ListboxProps, MeasureTone, MenuCheckboxItemProps, MenuItemProps, NumberInputProps, PopoverProps, PoseInputProps, PoseValue, Quaternion, ReadoutItem, RotationView, SelectOption, TabItem, ThemeChoice, ToastOptions, ToastRecord, ToastStore, ToastTone, ToasterProps, Tone, Vec3, VectorInputProps };
 //# sourceMappingURL=index.d.ts.map