@vitavision/ui 0.9.0 → 0.10.0

package/README.md

@@ -123,13 +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` ·
+`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`.
+`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];
@@ -1043,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`.
@@ -1090,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, ToastOptions, ToastRecord, ToastStore, ToastTone, ToasterProps, 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