@vipengele/react-ui 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Gomes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,466 @@
 # @vipengele/react-ui
 
-`0.0.0` is a placeholder. It carries no code, and exists only so that a trusted publisher can
-be enrolled on this name — npm can enrol one only on a name the registry already holds.
+Vipengele's themeable React component library. Components read theme exclusively through
+`--vpg-*` CSS custom properties set by `@vipengele/react-tokens`' `ThemeProvider` — there is no
+`useTheme()` hook (see `docs/adr/0001-theming-via-css-custom-properties-no-context-hook.md`).
 
-Install a real release instead: <https://github.com/vipengele/react>
+```tsx
+import { Spinner } from "@vipengele/react-ui";
+
+<Spinner size="md" />;
+```
+
+## Tree-shaking
+
+Components are plain named exports — never a namespace barrel — so a consumer importing one
+component pulls in only that component and its stylesheet.
+
+## Styling
+
+Each component ships its styles as a string injected through React 19's
+`<style href precedence>`, not as a `.css` import: a stylesheet import is the module side effect
+that `"sideEffects": false` would have to carve an exception for. React hoists and de-duplicates
+by `href`, so N instances inject one stylesheet.
+
+Theme properties are only ever *read* through `var()` in those stylesheets, never assigned as an
+inline style. An inline declaration beats any stylesheet rule for the same property on the same
+element, so an inline `--vpg-*` value would permanently shadow `ThemeProvider`'s dark-mode
+reassignment and that instance would stop adapting to colour mode.
+
+## Components
+
+### `Spinner`
+
+An indeterminate loading indicator. Sizes `sm | md | lg` (steps of the icon scale — a spinner is
+glyph-sized), stroked in `var(--vpg-accent)`, rotated by a CSS
+`@keyframes` rule that slows under `prefers-reduced-motion: reduce`. Exposes `role="status"` with
+a `label` (default `"Loading"`) as its accessible name.
+
+`color` sets an inline stroke override. It is an opt-in escape hatch for a spinner sitting on a
+ground the theme doesn't know about: that instance no longer adapts to light/dark.
+
+### `Button`
+
+The library's action atom. `variant` is `primary | secondary | ghost | danger`, `size` is
+`sm | md | lg` — the same scale as `Spinner`, so a `loading` button holds its height when its
+content is swapped for an inline `<Spinner size={size} color="currentColor" />`. `disabled` and
+`loading` both disable interaction; `loading` additionally sets `aria-busy`.
+
+`leadingIcon` and `trailingIcon` take the icon component itself — `<Button leadingIcon={Plus} />`
+— never a name, so a bundler only ever sees icons actually referenced. Passing `iconOnly` renders
+the button with no visible label, in which case `aria-label` is required rather than optional: it
+is the button's only accessible name.
+
+### `Typography`
+
+The library's text atom. `variant` is `display | h1 | h2 | h3 | h4 | body-lg | body-md |
+body-sm | caption`, `weight` is `regular | medium | bold`, and `color` is a curated set of
+`--vpg-*` ink tokens — `primary | secondary | subtle | accent` — not an arbitrary CSS colour,
+so text always tracks light/dark mode.
+
+`variant` also chooses the rendered HTML element (`display`/`h1`–`h4` render their matching
+heading tag, `body-*` renders `<p>`, `caption` renders `<span>`). `as` overrides only the tag,
+never the visual style, so a heading-styled label can render as a `<div>` where an `<h1>` would
+break the document outline.
+
+### `ButtonGroup`
+
+Groups plain `<Button>` children into a single attached control. `orientation` is
+`horizontal | vertical`. Children render unmodified — no `cloneElement`, no context — the
+segmented look comes entirely from `ButtonGroup`'s own stylesheet targeting `.vpg-button` as
+a descendant.
+
+### `Avatar`
+
+The library's person atom: an image, the person's initials, or a generic person glyph, in that
+order of preference, framed as a `circle` or `square` (`shape`) at size `sm | md | lg | xl`.
+
+`src` is the image to render; a failed load falls through to initials, then to the icon, so a
+dead URL degrades instead of leaving a blank frame. `name` is the source of the initials — the
+first character of the first word plus the first character of the last word, upper-cased — and
+the accessible name unless `alt` overrides it.
+
+### `Skeleton`
+
+A shimmering placeholder shaped to match the content it stands in for: `variant` is
+`rect | circle | text`. `width`/`height` accept a number (treated as pixels) or a string
+carrying its own unit; left unset, the variant's own stylesheet rule sizes it. Decorative by
+construction — it renders with `aria-hidden="true"` and never reaches the accessibility tree.
+
+### `Card`
+
+A structured content surface: `Card`, `Card.Header`, `Card.Content` (required), and
+`Card.Footer`. At most one of each subcomponent is allowed among `Card`'s children — anything
+else, including an arbitrary child or a second `Card.Header`, throws at render. Layout is
+CSS-driven (`order` in a flex column), so the three subcomponents render header-above-content-
+above-footer regardless of the order they're written in JSX.
+
+Passing `onClick` makes the whole card interactive: it renders as `<div role="button"
+tabIndex={0}>` with `Enter`/`Space` activating it, not as a native `<button>` — a `<button>`'s
+content model forbids interactive content, and `Card.Footer`'s canonical content is a `<Button>`.
+
+### `FormField`
+
+Labels exactly one focusable control — `label`/`hint`/`error`/`children`, flat props rather than
+a compound component. `children` is a native input, `Toggle`, `RadioButton`, or `Dropdown`'s
+trigger — a single element whose component forwards unknown props to its focusable root. Not a
+group-shaped component like `RadioGroup`, which gets its accessible name from its own
+`aria-label` instead.
+
+`FormField` generates ids via `useId` and clones onto the child: `id` (the child's own `id` wins
+if it already has one), `aria-describedby` (built from whichever of `hint`/`error` render, merged
+with any `aria-describedby` the child already carries rather than overwritten), `aria-invalid`
+(set when `error` is non-empty), and `aria-labelledby` — applied unconditionally, regardless of
+what element the child renders as. `<label htmlFor>` only associates with labelable elements
+(`input`/`select`/`textarea`/`button`/`meter`/`output`/`progress`), so a non-labelable trigger
+(`Dropdown`'s `<div role="combobox">`) would otherwise get no accessible name at all;
+`aria-labelledby` works on both, so every control gets it uniformly.
+
+`children` that isn't a single valid element — text, an array, a `Fragment`, `null` — throws:
+there's no single node to attach the label and description to.
+
+```tsx
+<FormField label="Email" hint="We never share this" error={errors.email}>
+  <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
+</FormField>
+```
+
+### `FieldSet`
+
+A native `<fieldset>` + `<legend>` pair with spacing between `children`, for grouping related
+controls — typically one or more `FormField`s, though it isn't restricted to them. It carries no
+form-state logic of its own, purely layout: `legend` renders in the native `<legend>`, which
+names the `<fieldset>` automatically with no id/aria wiring needed. `disabled` forwards straight
+to the native `<fieldset>`, which disables every descendant form control for free.
+
+A `<legend>` naming its `<fieldset>` doesn't extend to a `role="radiogroup"` element nested
+inside it, which is why `RadioGroup` carries its own `aria-label` rather than relying on an
+ancestor `FieldSet`'s legend.
+
+```tsx
+<FieldSet legend="Shipping address">
+  <FormField label="Street">
+    <input />
+  </FormField>
+  <FormField label="City">
+    <input />
+  </FormField>
+</FieldSet>
+```
+
+### `Progress`
+
+A linear progress bar. `size` is `sm | md | lg`. Given a `value` (against `max`, default `100`),
+it renders determinate — the fill's width tracks the percentage, and `role="progressbar"` carries
+`aria-valuenow`/`-valuemin`/`-valuemax`; a `value` outside `[0, max]` is clamped rather than
+over- or under-filling the track. Omitting `value` renders indeterminate instead: a looping
+sweep with no `aria-value*` attributes, since a progress bar with no known value has nothing to
+report as a percentage. The sweep slows rather than stops under `prefers-reduced-motion: reduce`.
+
+### `Tabs`
+
+A tabbed interface: `Tabs`, `Tabs.List`, `Tabs.Tab`, and `Tabs.Panel`. Each `Tabs.Tab` is paired
+with the `Tabs.Panel` carrying the same `value`; the `id`/`aria-controls`/`aria-labelledby` wiring
+between them is generated with `useId`, so no DOM ids need supplying. Selection is controlled
+through `value`/`onChange`, or left to `Tabs` itself — seeded by `defaultValue`, falling back to
+the first `Tabs.Tab` in `children`.
+
+The list follows the WAI-ARIA tabs pattern: a roving tabindex (the selected tab is the list's only
+tab stop), automatic activation — an arrow key moves focus and selects in one step — wrap-around
+at both ends, and `Home`/`End` jumping to the first/last tab. `orientation` is `horizontal` (the
+default, Left/Right) or `vertical` (Up/Down); the off-axis arrow pair is left unhandled. A tab
+with `disabled` is skipped by keyboard traversal entirely and cannot be clicked.
+
+Only the selected panel is mounted — the others render nothing rather than staying in the DOM
+hidden, so a panel's internal state does not survive a switch away from it.
+
+### `TextField`
+
+A styled native `<input>` for free-text entry (`type` defaults to `"text"`; pass `"email"`,
+`"password"`, etc. for any other native input type). Forwards every other `<input>` prop as-is.
+Reads the same border/radius/surface tokens `Dropdown`'s trigger reads, and the same
+`aria-invalid` styling hook, so a text field and a dropdown trigger read as the same kind of
+control side by side in a form.
+
+### `Toggle`
+
+A native `<input type="checkbox" role="switch">` styled as a switch. It forwards every
+`<input>` prop except `type`/`role`, so `checked`/`onChange` (controlled) or `defaultChecked`
+(uncontrolled), `disabled`, and `aria-label`/`aria-labelledby` all work exactly as they do on a
+plain checkbox. No custom keyboard handling and no hand-set `aria-checked`: the native element
+already exposes its checked state through the DOM, handles focus and keyboard interaction, and
+participates in forms for free.
+
+### `RadioButton` / `RadioGroup`
+
+`RadioButton` is a single styled native `<input type="radio">`. It forwards every `<input>` prop
+except `type`, and is usable entirely on its own outside any `RadioGroup` — pass `name`,
+`checked`/`onChange` (controlled) or `defaultChecked` (uncontrolled), and `value` manually, the
+same as a plain radio input. No custom keyboard or roving-tabindex code: native radios sharing a
+`name` get browser-native grouping and arrow-key behavior for free.
+
+### `Slider`
+
+A native `<input type="range">` styled as a single-thumb slider. It forwards every `<input>`
+prop except `type`, so `min`/`max`/`step`, `value`/`onChange` (controlled) or `defaultValue`
+(uncontrolled), and `disabled` all work exactly as they do on a plain range input. No custom
+keyboard or pointer handling: the native element already handles arrow-key stepping, dragging,
+touch, and form participation for free. Two-thumb range selection is out of scope.
+
+`RadioGroup` is a context provider grouping `RadioButton`s: `role="radiogroup"` on its own
+wrapper, with an `aria-label` for its accessible name — independent of any ancestor `FieldSet`,
+since a `<legend>` doesn't automatically name a nested `role="radiogroup"` element the way it
+names the `<fieldset>` itself. Selection is controlled through `value`/`onChange`, or left to
+`RadioGroup` itself, seeded by `defaultValue` — the same duality as `Tabs`. A shared `name` is
+auto-generated with `useId` when not given explicitly, and every child `RadioButton` reads its
+`name`, checked state, and change handler from context; an explicit `checked`/`onChange` on a
+`RadioButton` still overrides what the group would otherwise provide.
+
+```tsx
+<RadioGroup aria-label="Size" defaultValue="medium">
+  <RadioButton aria-label="Small" value="small" />
+  <RadioButton aria-label="Medium" value="medium" />
+  <RadioButton aria-label="Large" value="large" />
+</RadioGroup>
+```
+
+### `Tooltip`
+
+A small floating label describing its trigger. `content` is what the bubble shows, `children` is
+the trigger, and `placement` (`top | bottom | left | right`, default `top`) is the preferred side —
+the bubble flips to the opposite side when it wouldn't fit there and shifts to stay on-screen.
+
+The trigger is wrapped in an inline `<span>` carrying the ref and the hover/focus handlers, never
+cloned, so it can be any node — including a component that forwards neither a ref nor unknown
+props. The bubble appears on hover and on keyboard focus, and is dismissed by moving away, by
+blurring the trigger, or by `Escape`. It carries `role="tooltip"` and is wired to the trigger with
+`aria-describedby` while open.
+
+`disabled` suppresses the tooltip outright: no handler is registered and the bubble never renders.
+It lives on `Tooltip` rather than being read off the trigger, because the trigger's props are
+never inspected.
+
+The bubble portals into the nearest ancestor `.vpg-root` — the subtree `ThemeProvider`
+establishes — rather than `document.body`, so it keeps every `--vpg-*` value. On a page with no
+`.vpg-root` ancestor it renders inline beside the trigger instead, positioned identically but
+inheriting whatever theme surrounds it.
+
+### `Popover`
+
+A floating panel of interactive content. `content` is what the panel holds, `children` is the
+trigger, and `placement` (`top | bottom | left | right`, default `bottom`) is the preferred side —
+the panel flips to the opposite side when it wouldn't fit there and shifts to stay on-screen.
+
+The trigger is wrapped in an inline `<span>` carrying the ref and the click handler, never cloned,
+so it can be any node. Clicking it opens the panel; clicking it again, pressing outside, or
+pressing `Escape` closes it. The wrapper carries `aria-haspopup="dialog"` and an `aria-expanded`
+that tracks the panel, which itself is a `role="dialog"`.
+
+Open state is either controlled through `open`/`onOpenChange` or left to `Popover` itself, seeded
+by `defaultOpen`. `onOpenChange` fires for every open/close request in both forms. `content` is a
+plain node rather than a render prop taking a `close` callback: content that has to close the
+popover itself belongs in the controlled form, where the consumer already owns the state.
+
+While the panel is open, focus is trapped inside it and the rest of the page is hidden from
+assistive technology; closing it returns focus to the trigger. The panel holds real interactive
+content, so keyboard users must be able to reach it and must not fall out the back of it.
+
+The panel portals into the nearest ancestor `.vpg-root` — the subtree `ThemeProvider`
+establishes — rather than `document.body`, so it keeps every `--vpg-*` value. On a page with no
+`.vpg-root` ancestor it renders inline beside the trigger instead, positioned identically but
+inheriting whatever theme surrounds it.
+
+### `Dropdown`
+
+A select-only combobox: `Dropdown` and `Dropdown.Option` children directly beneath it, with no
+list layer — the floating listbox's positioning is `Dropdown`'s own business. The field fills its
+container's width, the way `TextField` does, rather than shrinking to fit its selection — it never
+widens as options are selected. Each
+`Dropdown.Option` takes a `value`, a `label` (the string shown in the trigger, in its chip, matched
+by the search query, and — with `searchable={false}` — by type-ahead on the trigger), an optional
+leading `icon`, and `disabled`. A child that is neither a
+`Dropdown.Option`, a `Dropdown.Group` nor falsy throws at render; falsy children — what `condition
+&& <Dropdown.Option />` produces — are skipped.
+
+A selection is a `DropdownValue` — `{ value, label, icon? }`, or `null` for none — controlled
+through `value`/`onChange` or left to `Dropdown` itself, seeded by `defaultValue`. `multiple`
+switches all three to arrays: each option gains a checkbox, each selected value a removable chip
+beside the trigger, and selecting toggles the option without closing the listbox. `onChange` hands
+back the whole object of the option that was picked — `(value: DropdownValue | null) => void` in
+single-select, where `null` is the emptied selection, and `(value: DropdownValue[]) => void` in
+`multiple`, where the empty array is.
+
+The `value` string is the identity, so a consumer that re-creates its value object on every render
+keeps its selection. A `Dropdown.Option` carrying that `value` supplies the label and icon that
+render; the value object's own are the fallback for a selection no option matches.
+
+```tsx
+<Dropdown defaultValue={{ value: "medium", label: "Medium" }} onChange={(size) => setSize(size)}>
+  <Dropdown.Option value="small" label="Small" icon={Minus} />
+  <Dropdown.Option value="medium" label="Medium" />
+  <Dropdown.Option value="large" label="Large" disabled />
+</Dropdown>
+```
+
+`searchable` (default `true`) opens the listbox under a search row: a magnifier, an input hinted
+by `searchPlaceholder` (default `"Search"`), then a divider. Typing filters the options to a
+case-insensitive substring of their labels, wherever it falls in them, and a query matching none
+of them says "No results" rather than leaving the panel blank. A selection the query filters out
+of the list keeps its place in the trigger and its chip. `searchable={false}` renders the listbox
+alone, with type-ahead on the trigger.
+
+```tsx
+<Dropdown aria-label="Assignee" searchPlaceholder="Search people">
+  <Dropdown.Option value="ada" label="Ada Lovelace" icon={User} />
+  <Dropdown.Option value="grace" label="Grace Hopper" icon={User} />
+</Dropdown>
+```
+
+Every keystroke belongs to that search once the row exists. A printable character typed on the
+closed trigger opens the popover and seeds the query with it. A pick in `multiple` mode keeps the
+popover open and clears the query, so the next character searches every option again rather than
+narrowing what is left of the picked option's own match. `Backspace` with no character left to
+delete removes the last selection — `multiple`'s alone, since a single selection has no last
+selection distinct from its only one, and `clearable` below is what empties that. The query clears as the
+popover closes, so the next open starts on the full list.
+
+#### Groups
+
+`Dropdown.Group label` heads a run of `Dropdown.Option` children. A heading is not an option: it
+takes no place in the flat list the arrow keys, `Home`/`End` and the wrap at either end travel, so
+every option is reached exactly as it is with no group declared. Each group renders as a
+`role="group"` named by its heading, with a separator drawn between one group and the next —
+never before the first or after the last, and never declared by the consumer. A group the search
+query leaves no option in renders nothing at all. A `Dropdown.Group` inside a `Dropdown.Group`
+throws, as does any group child that is neither a `Dropdown.Option` nor falsy.
+
+```tsx
+<Dropdown aria-label="Fruit">
+  <Dropdown.Option value="all" label="All fruit" />
+  <Dropdown.Group label="Citrus">
+    <Dropdown.Option value="lemon" label="Lemon" />
+    <Dropdown.Option value="lime" label="Lime" />
+  </Dropdown.Group>
+  <Dropdown.Group label="Stone">
+    <Dropdown.Option value="peach" label="Peach" />
+  </Dropdown.Group>
+</Dropdown>
+```
+
+An async result groups itself with a `group` string instead — see below.
+
+The search input is a second `role="combobox"`, with `aria-autocomplete="list"`, its own
+`aria-controls` on the listbox and the `aria-activedescendant` tracking the highlight; it is named
+by `searchPlaceholder`, while the trigger keeps the accessible name and description. A non-modal
+`FloatingFocusManager` puts real DOM focus in that input as the panel opens, and Escape, a
+selection and a press outside each hand focus back to the trigger. `Enter` selects the highlighted
+option; `Space` is a character in the query, not a selection key.
+
+The trigger is a `<div role="combobox" tabIndex={0}>`, not a `<button>`: only `combobox` and a
+handful of other roles may legally carry `aria-activedescendant`, and the highlighted option is
+tracked virtually through exactly that attribute rather than by moving focus into the listbox.
+The trigger also carries `aria-haspopup="listbox"`, `aria-expanded` and `aria-controls`, and
+forwards `id`/`aria-label`/`aria-labelledby`/`aria-describedby`/`aria-invalid` — so a `Dropdown`
+wrapped in a `FormField` gets its accessible name and description on the element that actually
+takes focus.
+
+Keyboard: `Enter`/`Space` opens the listbox and then selects the highlighted option (toggling it,
+in `multiple`), the arrow keys move the highlight and wrap at both ends, `Home`/`End` jump to the
+first/last option, `Escape` closes, and — with no search row to type into — typing a character
+jumps the highlight to the next option whose label starts with it. Disabled options are skipped by
+every one of those and cannot be clicked.
+
+In `multiple` mode the chips render as siblings *before* the trigger inside a plain wrapper, never
+inside it: floating-ui merges its own click and keyboard handlers into the trigger's, so a remove
+button nested in there could not be reliably intercepted before those ran. The chips carry the
+whole selection: the trigger beside them renders nothing once anything is selected, and is the
+click target holding the chevron. The placeholder shows there while the selection is empty.
+
+Those chips keep to one row, so a field with a selection stands at the same height as an empty
+one. Which of them fit is measured against the width the field has — not capped at a number, which
+would already overflow a narrow field and leave room unused in a wide one — and re-measured before
+the next paint whenever that width changes. The rest give way to an indicator counting them, and a
+chip too wide for the field shows with its label cut short rather than pushing the field past its
+container.
+
+The indicator standing for the rest reads "and N more" and takes no tab stop — a hidden selection
+is removed by unchecking it in the listbox, since the chip carrying it is not on screen to remove
+it from, so a stop there would be a stop with nothing to do. Hovering it shows the labels it
+stands for in a `Tooltip`. That tooltip is the pointer's route to them; a screen reader's is the
+trigger, which is described by every selection, hidden or not — and that description is *merged*
+with whatever `aria-describedby` the trigger is given, so a `Dropdown` inside a `FormField` keeps
+its hint and its error message alongside it rather than losing them to the selection.
+
+`wrapChips` switches the measurement off and wraps the chips onto further rows instead, growing
+the field downwards:
+
+```tsx
+<Dropdown multiple wrapChips aria-label="Fruit" defaultValue={picked} onChange={setPicked}>
+  {fruit.map((name) => (
+    <Dropdown.Option key={name} value={name} label={name} />
+  ))}
+</Dropdown>
+```
+
+`clearable` (default `false`) puts a "Clear selection" `<button>` in the field's trailing slot
+while anything is selected, and takes it away again once nothing is. Pressing it empties the whole
+selection at once — `onChange` reports `null` in single-select and `[]` in `multiple` — without
+opening the listbox, and leaves focus on the trigger. It is an adornment rather than a control the
+field reads: the focus ring it takes is its own, and the field around it stays at rest.
+
+```tsx
+<Dropdown clearable aria-label="Size" value={size} onChange={setSize}>
+  <Dropdown.Option value="small" label="Small" />
+  <Dropdown.Option value="large" label="Large" />
+</Dropdown>
+```
+
+The listbox — the whole panel, search row included — portals into the nearest ancestor
+`.vpg-root` — the subtree `ThemeProvider` establishes — rather than `document.body`, so it
+keeps every `--vpg-*` value. On a page with no `.vpg-root` ancestor it renders inline
+beside the trigger instead.
+
+#### Async data source
+
+Pass `loadOptions` instead of `children` to back `Dropdown` with an API rather than a declared
+list:
+
+```tsx
+<Dropdown
+  aria-label="Country"
+  placeholder="Pick a country"
+  defaultValue={{ value: "jp", label: "Japan" }}
+  loadOptions={(query) => fetchCountries(query)}
+/>
+```
+
+`loadOptions: (query: string) => Promise<DropdownAsyncOption[]>` — each result a `{value, label,
+icon?, disabled?, group?}` — is called with the search query after it settles for `debounceMs` (default
+`300`), and `Dropdown` renders whatever it resolves to. Filtering the query is the API's job in
+this mode: results are shown as returned, never matched again client-side. `loadingMessage`
+(default `"Loading…"`) shows while a search is pending, `errorMessage` (default `"Something went
+wrong."`) shows if the promise rejects, and a search that returns nothing says "No results". A
+response the query has moved past is discarded rather than applied — a slow earlier search
+resolving after a faster later one, and equally one resolving while the next query is still
+settling. The search is keyed off the query alone, so an inline arrow like the one above, fresh on
+every render, is as correct as a memoised `loadOptions`. `children` goes unread when `loadOptions`
+is set.
+
+A result's `group` is the heading it stands under. Results carrying the same string are one group
+however far apart they arrive in the array, the groups stand in the order their first result
+arrives, and every result carrying no group at all comes before them.
+
+A selection carries its own `label`, so the trigger and a `multiple` chip render it with nothing
+fetched, no search run and no option child to match against — including for a `value` or
+`defaultValue` handed straight to `Dropdown`.
+
+## Runtime dependencies
+
+`@floating-ui/react` positions `Tooltip`'s bubble, `Popover`'s panel and `Dropdown`'s listbox —
+and drives its virtual-focus list navigation and type-ahead. It travels only with the components
+that need it — a bundle importing anything else does not pull it in, which `bundle-check/`
+asserts.
+
+## Peer dependencies
+
+React 19 and React DOM 19 — components render React and rely on `<style href precedence>`.

package/dist/Avatar/Avatar.d.ts

@@ -0,0 +1,21 @@
+import { type HTMLAttributes } from "react";
+export type AvatarSize = "sm" | "md" | "lg" | "xl";
+export type AvatarShape = "circle" | "square";
+export interface AvatarProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children"> {
+    /** The image to render. An image that fails to load falls through to the initials, and then
+     * to the generic person icon, so a dead URL degrades instead of leaving a blank frame. */
+    src?: string;
+    /** The person the avatar stands for: the source of the initials, and the accessible name
+     * when no `alt` is given. */
+    name?: string;
+    /** Overrides `name` as the accessible name. */
+    alt?: string;
+    size?: AvatarSize;
+    shape?: AvatarShape;
+}
+/**
+ * The library's person atom: an image, the person's initials, or a generic person glyph, in
+ * that order of preference, framed as a circle or a rounded square.
+ */
+export declare function Avatar({ src, name, alt, size, shape, className, ...rest }: AvatarProps): import("react").JSX.Element;
+//# sourceMappingURL=Avatar.d.ts.map

package/dist/Avatar/Avatar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../../src/Avatar/Avatar.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,cAAc,EAAY,MAAM,OAAO,CAAC;AAGtD,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEnD,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9C,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,CAAC,eAAe,CAAC,EAAE,UAAU,CAAC;IACpF;8FAC0F;IAC1F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;iCAC6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAiBD;;;GAGG;AACH,wBAAgB,MAAM,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAW,EAAE,KAAgB,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,WAAW,+BAuCxG"}

package/dist/Avatar/Avatar.stylesheet.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `<Avatar>`'s own styles, injected as an inline `<style>` rather than a `.css` import so the
+ * package can stay `"sideEffects": false` (same approach as `@vipengele/react-tokens`'s base stylesheet
+ * and `Button`'s stylesheet).
+ *
+ * Every `--vpg-*` property is *read* here through `var()` and never assigned inline by the
+ * component: an inline style declaration always wins over a stylesheet rule for the same
+ * property on the same element, so an inline `--vpg-surface-raised` would permanently
+ * shadow the dark-mode reassignment in `@vipengele/react-tokens`'s base stylesheet and this avatar
+ * would stop adapting to colour mode.
+ *
+ * The circle takes steps of the size scale and the initials steps of the type scale. The `xl`
+ * circle takes the size scale's display step, past the range a pointer targets, and the `sm`
+ * initials sit on the type scale's floor rather than under it.
+ */
+export declare const avatarStylesheet = "\n.vpg-avatar {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  flex: none;\n  box-sizing: border-box;\n  overflow: hidden;\n  background-color: var(--vpg-surface-raised);\n  color: var(--vpg-ink-muted);\n  font-family: inherit;\n  font-weight: 500;\n  line-height: 1;\n  /* The fallback content is centred text or a glyph; without this, a long initials string\n     would be selectable and could wrap out of the frame. */\n  user-select: none;\n}\n\n.vpg-avatar-circle {\n  border-radius: 50%;\n}\n\n.vpg-avatar-square {\n  border-radius: var(--vpg-radius);\n}\n\n.vpg-avatar-sm {\n  width: var(--vpg-size-xs);\n  height: var(--vpg-size-xs);\n  font-size: var(--vpg-font-size-xs);\n}\n\n.vpg-avatar-md {\n  width: var(--vpg-size-md);\n  height: var(--vpg-size-md);\n  font-size: var(--vpg-font-size-xs);\n}\n\n.vpg-avatar-lg {\n  width: var(--vpg-size-xl);\n  height: var(--vpg-size-xl);\n  font-size: var(--vpg-font-size-sm);\n}\n\n.vpg-avatar-xl {\n  width: var(--vpg-size-2xl);\n  height: var(--vpg-size-2xl);\n  font-size: var(--vpg-font-size-lg);\n}\n\n.vpg-avatar-image {\n  width: 100%;\n  height: 100%;\n  /* `cover` rather than `contain`: a non-square photo is cropped to the frame instead of\n     letterboxed against the surface colour. */\n  object-fit: cover;\n  display: block;\n}\n\n.vpg-avatar-icon {\n  /* Proportional to the frame, so one rule sizes the glyph across the whole size scale. */\n  width: 60%;\n  height: 60%;\n}\n";
+//# sourceMappingURL=Avatar.stylesheet.d.ts.map

package/dist/Avatar/Avatar.stylesheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Avatar.stylesheet.d.ts","sourceRoot":"","sources":["../../src/Avatar/Avatar.stylesheet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,28CAgE5B,CAAC"}

package/dist/Button/Button.d.ts

@@ -0,0 +1,39 @@
+import type { IconComponent } from "@vipengele/react-icons";
+import type { ButtonHTMLAttributes, ReactNode } from "react";
+export type ButtonVariant = "primary" | "secondary" | "ghost" | "danger";
+/** Shared with `Spinner`'s size scale, so a loading button holds its height. */
+export type ButtonSize = "sm" | "md" | "lg";
+interface ButtonOwnProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    /** Disables interaction and replaces the button's content with an inline `<Spinner>`. The
+     * button keeps its own text colour, so the spinner reads on every variant. */
+    loading?: boolean;
+    /** Rendered before the label. Pass the component itself — `<Button leadingIcon={Plus} />` —
+     * so a bundler only ever sees the icons actually referenced. */
+    leadingIcon?: IconComponent;
+    /** Rendered after the label, under the same rules as `leadingIcon`. */
+    trailingIcon?: IconComponent;
+}
+/**
+ * A square button carrying an icon and no text. `aria-label` is required rather than optional:
+ * without visible text, it is the button's only accessible name, and a runtime warning would
+ * land too late to stop the button shipping nameless.
+ */
+interface IconOnlyButtonProps extends ButtonOwnProps {
+    iconOnly: true;
+    "aria-label": string;
+    children?: never;
+}
+interface LabelledButtonProps extends ButtonOwnProps {
+    iconOnly?: false;
+    children?: ReactNode;
+}
+export type ButtonProps = IconOnlyButtonProps | LabelledButtonProps;
+/**
+ * The library's action atom, styled entirely from `--vpg-*` custom properties read through
+ * `var()` in its own stylesheet, so a themed instance follows colour mode without re-rendering.
+ */
+export declare function Button({ variant, size, loading, iconOnly, leadingIcon: LeadingIcon, trailingIcon: TrailingIcon, className, disabled, children, ...rest }: ButtonProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=Button.d.ts.map

package/dist/Button/Button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Button.d.ts","sourceRoot":"","sources":["../../src/Button/Button.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAI7D,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEzE,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C,UAAU,cAAe,SAAQ,IAAI,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAAE,UAAU,CAAC;IACxF,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;kFAC8E;IAC9E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;oEACgE;IAChE,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,uEAAuE;IACvE,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED;;;;GAIG;AACH,UAAU,mBAAoB,SAAQ,cAAc;IAClD,QAAQ,EAAE,IAAI,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB;AAED,UAAU,mBAAoB,SAAQ,cAAc;IAClD,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,MAAM,MAAM,WAAW,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AAEpE;;;GAGG;AACH,wBAAgB,MAAM,CAAC,EACrB,OAAmB,EACnB,IAAW,EACX,OAAe,EACf,QAAgB,EAChB,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,YAAY,EAC1B,SAAS,EACT,QAAgB,EAChB,QAAQ,EACR,GAAG,IAAI,EACR,EAAE,WAAW,+BAwCb"}

package/dist/Button/Button.stylesheet.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `<Button>`'s own styles, injected as an inline `<style>` rather than a `.css` import so the
+ * package can stay `"sideEffects": false` (same approach as `@vipengele/react-tokens`'s base stylesheet
+ * and `@vipengele/react-icons`'s icon stylesheet).
+ *
+ * Every `--vpg-*` property is *read* here through `var()` and never assigned inline by the
+ * component: an inline style declaration always wins over a stylesheet rule for the same
+ * property on the same element, so an inline `--vpg-accent` would permanently shadow the
+ * dark-mode reassignment in `@vipengele/react-tokens`'s base stylesheet and this button would stop
+ * adapting to colour mode.
+ *
+ * Heights come from the size scale, paddings from the spacing scale and label sizes from the
+ * type scale. The danger variant reads the `--vpg-danger` ramp, which is derived exactly as the
+ * accent ramp is, so both variants shift by the same amount on hover and press.
+ */
+export declare const buttonStylesheet = "\n.vpg-button {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  gap: var(--vpg-space-2);\n  box-sizing: border-box;\n  border: 1px solid transparent;\n  border-radius: var(--vpg-radius);\n  font-family: inherit;\n  font-weight: 500;\n  line-height: 1;\n  white-space: nowrap;\n  text-decoration: none;\n  cursor: pointer;\n  /* Colour and background come from the variant rules below; every variant animates the same\n     two properties, so the transition belongs here rather than four times over. */\n  transition: background-color 120ms ease, border-color 120ms ease, color 120ms ease;\n}\n\n.vpg-button:focus-visible {\n  /* Offset rather than inset so the ring stays legible against a same-coloured surface. */\n  outline: var(--vpg-focus-ring-width) solid var(--vpg-accent-ring);\n  outline-offset: var(--vpg-focus-ring-offset);\n}\n\n.vpg-button:disabled {\n  /* Pointer events stay on: a disabled button that swallows them gives no cursor feedback and\n     no tooltip target. `cursor` is what communicates the state. */\n  cursor: not-allowed;\n  opacity: 0.55;\n}\n\n.vpg-button-primary {\n  background-color: var(--vpg-accent);\n  color: var(--vpg-accent-contrast);\n}\n\n.vpg-button-primary:hover:not(:disabled) {\n  background-color: var(--vpg-accent-hover);\n}\n\n.vpg-button-primary:active:not(:disabled) {\n  background-color: var(--vpg-accent-press);\n}\n\n.vpg-button-secondary {\n  background-color: var(--vpg-surface-raised);\n  border-color: var(--vpg-border);\n  color: var(--vpg-ink);\n}\n\n.vpg-button-secondary:hover:not(:disabled) {\n  background-color: var(--vpg-surface-hover);\n  border-color: var(--vpg-border-strong);\n}\n\n.vpg-button-secondary:active:not(:disabled) {\n  background-color: var(--vpg-surface-press);\n}\n\n.vpg-button-ghost {\n  background-color: transparent;\n  color: var(--vpg-ink);\n}\n\n.vpg-button-ghost:hover:not(:disabled) {\n  background-color: var(--vpg-accent-wash);\n}\n\n.vpg-button-ghost:active:not(:disabled) {\n  background-color: var(--vpg-surface-press);\n}\n\n.vpg-button-danger {\n  background-color: var(--vpg-danger);\n  color: var(--vpg-danger-contrast);\n}\n\n.vpg-button-danger:hover:not(:disabled) {\n  background-color: var(--vpg-danger-hover);\n}\n\n.vpg-button-danger:active:not(:disabled) {\n  background-color: var(--vpg-danger-press);\n}\n\n.vpg-button-sm {\n  min-height: var(--vpg-size-sm);\n  padding: 0 var(--vpg-space-3);\n  font-size: var(--vpg-font-size-xs);\n}\n\n.vpg-button-md {\n  min-height: var(--vpg-size-md);\n  padding: 0 var(--vpg-space-4);\n  font-size: var(--vpg-font-size-sm);\n}\n\n.vpg-button-lg {\n  min-height: var(--vpg-size-xl);\n  padding: 0 var(--vpg-space-5);\n  font-size: var(--vpg-font-size-md);\n}\n\n/* Square: the horizontal padding is dropped and the min-height doubles as a width floor, so the\n   button stays square at every size without a second per-size scale. */\n.vpg-button-icon-only {\n  padding: 0;\n  aspect-ratio: 1;\n}\n\n.vpg-button-icon-only.vpg-button-sm {\n  min-width: var(--vpg-size-sm);\n}\n\n.vpg-button-icon-only.vpg-button-md {\n  min-width: var(--vpg-size-md);\n}\n\n.vpg-button-icon-only.vpg-button-lg {\n  min-width: var(--vpg-size-xl);\n}\n\n.vpg-button-icon {\n  flex: none;\n  width: 1em;\n  height: 1em;\n}\n\n/* Keeps the button's accessible name intact while `loading` swaps its visible content for a\n   spinner: the label stays in the accessibility tree, but takes up no visual space. */\n.vpg-button-visually-hidden {\n  position: absolute;\n  width: 1px;\n  height: 1px;\n  padding: 0;\n  margin: -1px;\n  overflow: hidden;\n  clip: rect(0, 0, 0, 0);\n  white-space: nowrap;\n  border: 0;\n}\n";
+//# sourceMappingURL=Button.stylesheet.d.ts.map

package/dist/Button/Button.stylesheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Button.stylesheet.d.ts","sourceRoot":"","sources":["../../src/Button/Button.stylesheet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,kmHA+I5B,CAAC"}

package/dist/ButtonGroup/ButtonGroup.d.ts

@@ -0,0 +1,16 @@
+import type { HTMLAttributes, ReactNode } from "react";
+export type ButtonGroupOrientation = "horizontal" | "vertical";
+interface ButtonGroupOwnProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    orientation?: ButtonGroupOrientation;
+    children?: ReactNode;
+}
+export type ButtonGroupProps = ButtonGroupOwnProps;
+/**
+ * Groups plain `<Button>` children into a single attached control. Children are rendered
+ * unmodified — no `cloneElement`, no context — the segmented look comes entirely from
+ * `ButtonGroup`'s own stylesheet targeting `.vpg-button` as a descendant, which makes
+ * `Button`'s rendered class name a contract this component depends on.
+ */
+export declare function ButtonGroup({ orientation, className, children, ...rest }: ButtonGroupProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=ButtonGroup.d.ts.map

package/dist/ButtonGroup/ButtonGroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ButtonGroup.d.ts","sourceRoot":"","sources":["../../src/ButtonGroup/ButtonGroup.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvD,MAAM,MAAM,sBAAsB,GAAG,YAAY,GAAG,UAAU,CAAC;AAE/D,UAAU,mBAAoB,SAAQ,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC;IACpF,WAAW,CAAC,EAAE,sBAAsB,CAAC;IACrC,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAEnD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,WAA0B,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,gBAAgB,+BAmBzG"}