@revolist/ui 0.0.0-stage → 4.0.1-rc

package/OWNERSHIP.md

@@ -0,0 +1,123 @@
+# Shared UI ownership
+
+`@revolist/ui` is the implementation owner for reusable product controls. Pro's
+existing exports and leaf modules are compatibility adapters. Product code owns
+values, validation, commands, persistence and domain layout.
+
+AI prompt, suggestions, applied-request trail, action status, result and assistant compositions live in
+`src/ai/`; `src/ai/_style.scss` owns their token-based presentation. Pro's AI
+adapter owns interpretation, field policy, view commands, query execution and
+view snapshots. Framework adapters and native mounting reuse the same TSX.
+
+| Component family | Implementation owner under `src/` | Style owner under `src/` |
+| --- | --- | --- |
+| Native button, input, select, textarea, summary | `control-presentation.view.tsx`; Preact `native-control.tsx` | `styles/_primitives.scss`, `styles/_control.scss`, `_form.scss` |
+| Button variants, icon button, toggle, group | `controls.tsx`, `buttons/` | `styles/_primitives.scss` |
+| Icon | `icons/icon.tsx` | `styles/_primitives.scss` |
+| Checkbox | `checkbox/index.ts` | `checkbox/checkbox.scss` |
+| Switch | `switch/index.tsx` | `styles/_primitives.scss` |
+| Radio group | `controls.tsx` | `_form.scss`, `styles/_compositions.scss` |
+| Choice chips, segmented control, tabs | `choice-chips/`, `segmented-switch/`; semantic exports in `controls.tsx` | `styles/_primitives.scss` |
+| Search | `search-input/native.view.tsx`; Preact `search-input/index.tsx` | `styles/_primitives.scss` |
+| Number/date/time inputs, stepper | `controls.tsx`; grid scalar/counter adapters in `native-controls.view.tsx` | `_form.scss`, `styles/_editor-counter.scss` |
+| Listbox, panes, split layout | `editor-layout/index.tsx`; neutral aliases in `controls.tsx` | `editor-layout/style.scss` |
+| Form field, hint, error, section, disclosure | `form-controls/`, `controls.tsx` | `_form.scss`, `styles/_compositions.scss` |
+| Chips | `form-controls/presentation.tsx` | `styles/_primitives.scss` |
+| Scalar/range sliders | `filter/filters/slider/`, `native-controls.view.tsx` | `filter/filters/slider/_slider.scss`, `styles/_editor-slider.scss` |
+| Calendar and date pickers | `calendar/`, `pickers.tsx` | `calendar/_calendar.scss`, `styles/_compositions.scss` |
+| Dropdown, combobox, multi-select | `dropdown/`; compositions in `pickers.tsx` | `dropdown/editor-dropdown.style.scss`, `styles/_compositions.scss` |
+| Color palette/picker | `color-palette/` | `color-palette/*.scss` |
+| Resource picker, avatar | `resource-picker/`, `avatar/` | `resource-picker/resource-picker.scss`, `avatar/avatar.style.scss` |
+| Dialog, popover, tooltip, menu, resize | `surfaces.view.tsx`, `dialog/`, `core/`; Preact compositions in `controls.tsx` and `pickers.tsx` | `_dialog.scss`, `styles/_primitives.scss`, `styles/_compositions.scss` |
+| Toolbar, panel, empty state, alerts | `controls.tsx` | `styles/_compositions.scss` |
+| Status feedback and badges | `status-feedback/`, `controls.tsx` | `status-feedback/status-feedback.scss`, `styles/_primitives.scss` |
+| Loading | `native-controls.view.tsx`, `controls.tsx` | `styles/_loading.scss`, `styles/_compositions.scss` |
+| Pagination, progress, rating | `pagination.ts`, `progress/`, `native-controls.view.tsx`, `controls.tsx` | `progress/_bar.scss`, `progress/_circular.scss`, `styles/legacy-rating.css`, `styles/legacy-pagination.css`, `styles/_compositions.scss` |
+| BarChart, LineChart, AreaChart; distribution adapter and brush range | `distribution-chart/bar-chart.tsx`, `line-chart.tsx`, `area-chart.tsx`; shared `chart-frame.tsx` and `geometry.ts`; `brush-range/` | `distribution-chart/_distribution-chart.scss`, `brush-range/_brush-range.scss` |
+| Option rows, legend, inline fields | `filter-controls.tsx` | `styles/_filter-controls.scss` |
+| Weekly time grid and keyboard/paint gesture lifecycle | `time-grid.tsx` | `styles/_time-grid.scss` |
+| Highlighted text input and scroll synchronization | `filter-controls.tsx` | `styles/_filter-controls.scss` |
+| Theme tokens | `styles/_theme.scss` | `styles/_tokens.scss` installs light/dark scopes |
+
+## Renderer and stylesheet contracts
+
+- Preact products use `@revolist/ui/native-control` when they need transparent
+  native attributes, native input/change events, or DOM refs. Semantic
+  compositions come from `@revolist/ui/preact` or their leaf entry.
+- RevoGrid/Stencil templates use `renderControl(h, tag, attributes, ...children)`
+  or `controlAttributes` with their existing JSX factory. They retain Core VNodes.
+- Element-returning hosts use the Preact mount adapters `createControl` or `createSearchInput`. Set the input type at
+  creation. Preserve the shared class when adding product classes.
+- Charts keeps its native renderer. It normalizes controls through
+  `controlAttributes` and installs `native-styles.scss?inline` inside its control
+  hosts. These styles are scoped and include no Preact or Pro runtime.
+- Standalone product stylesheet entries include `@revolist/ui/styles.scss`.
+  Products customize `--rv-ui-*`, `--rv-control-*`, and `--rv-search-input-*`
+  variables. Legacy selector-based Pivot fields include the same `control.scss`
+  mixin. Feature styles own layout and documented variants, not a second base.
+
+## Intentional product adapters
+
+Working calendars, task/card/event forms, configurators, chart inspectors and
+menus keep domain policy and data operations in their product. Large title
+fields and toolbar layouts remain product compositions using shared primitives.
+Grid cells, timeline event/task hit targets, dependency handles, card drag
+surfaces, grid expansion and virtualization keep their product geometry.
+`src/ownership.test.ts` records the explicit scene exceptions and rejects new
+local primitive JSX/factories elsewhere. UI's native dependency boundary and
+Charts' rendering boundary have separate assertions.
+
+Changes to a shared owner need UI coverage and the affected product's existing
+integration tests. Canonical suite selection is documented in `TESTING.md`.
+
+History and export commands use UI's `SvgButton` (or `IconButton` convenience composition) for SVG, count badge and pointer/keyboard tooltip presentation. Element-returning adapters use `decorateIconAction`; Charts renders controls through Preact. Products supply localized labels, permissions, actions and history counts. `ToolbarGroup` groups commands with spacing; `ButtonGroup` remains the bordered choice composition. Both danger button variants use the same red outline presentation.
+
+Structured filter adapters retain aggregation, matching, amount/date validation, timezone policy, preset meaning and commit transactions. UI receives explicit data and formatted labels. Expression parsing, syntax tokens, diagnostics and debounce remain in Pro; UI owns the highlighted input's geometry and scroll synchronization. TimeGrid owns keyboard focus and paint gesture cleanup; Pro expands visual buckets into selected hourly filter values. Legacy filter CSS classes remain adapter hooks, with theme aliases at the Pro boundary.
+
+## Grid-backed filter compositions stay in Pro
+
+Selection lists and their search/select-all composition are owned by
+`packages/pro/plugins/filter/filters/selection/list/`. They render the existing
+RevoGrid `SelectionGrid`, including virtualization, grouping, option columns and
+selection transactions. They must not be replaced with a shared checkbox list.
+Faceted-list composition also stays in Pro; it already used native rows before
+this migration. Both consume UI primitives for checkbox, search and progress.
+
+The independent UI gallery contains no imitation selection filter.
+Statistical/date preset meaning, expression parsing and time-matrix bucket
+conversion remain Pro policy; generic option rows, highlighted input geometry,
+distribution rendering and time-grid gestures remain UI presentation.
+
+BarChart and LineChart are independent compact visual components, exported through the Preact entry and `@revolist/ui/bar-chart` / `@revolist/ui/line-chart`. Each owns its series rendering. The shared chart frame owns keyboard focus and tooltips; DistributionChart only dispatches to the selected standalone chart. BrushRange composes that adapter with the existing range slider; Pro retains bins, matching, date semantics and filter commits.
+
+### Field configurators
+
+`src/field-configurator.tsx` owns field libraries, headings, lists, drag-ready rows, neutral items and icon/caption slots. `src/styles/_field-configurator.scss` owns presentation and UI-token fallbacks. Pivot configurator exports remain aliases; its SCSS mixin delegates to UI. Query rules, native policy inspection, field metadata icons, tooltips and grid drag/drop stay in Pivot. The gallery demonstrates these primitives independently.
+
+Pivot configuration and chart query searchable fields both use `PivotDimensionsGrid` and Pro `TreeDataPlugin` in Pivot. The UI field library is a neutral disclosure/list shell, never a substitute for these grid-backed browsers.
+
+Active filter badges use `filter-badge.tsx` (`FilterBadge` and `FilterBadgeInfoButton`) and `styles/_filter-badge.scss`. Pro owns filter state, localization, custom render values, slots and tooltip lifecycle; its old stylesheet is a compatibility import.
+
+FilterBadge composes ChoiceChip; ChoiceChip owns optional info and close actions as siblings of the selection button. ChoiceChipInfoButton owns the common details action appearance.
+
+Active filter badges in Pro, Audit History, Order Explorer, planning and Pivot compose shared Choice chips. Consumers retain filter state and layout only; chip shape, surfaces, font weight and actions belong to UI.
+
+ChoiceChip, ChoiceChips options and FilterBadge accept optional `color`. UI owns colored selected text/border/tint; chip-badge filter descriptors only supply color values, labels and filter policy.
+
+Link-style action buttons use `Button variant="link"` or `SvgButton variant="link"`. UI owns the borderless blue text, icon spacing, hover/focus and disabled presentation; grouped-filter TextIconButton is a compatibility adapter without local appearance CSS.
+
+## Interactive timeline track
+
+`src/timeline-track/` owns controlled bar rendering, selection, pointer capture/movement/resizing, keyboard edits, numeric geometry helpers and track styles. Pro's Timeline editor adapter retains draft validation, localization and commits; its existing model helper exports forward to the shared model. The read-only cell timeline renderer remains in `cell-visuals/timeline.ts`.
+
+## Editable dialog composition
+
+`dialog/dialog.parts.tsx` owns editable-name headers (including optional dialog caption), close controls and the standard action footer with start/end slots. `_dialog.scss` owns header insets, message separation and footer layout. Scheduler, Kanban and Gantt retain validation, permissions, translations and persistence, without local footer-button appearance overrides.
+
+## Selection lists
+
+`selection-list.ts` exposes the general Listbox/option/group API backed by `editor-layout/index.tsx` and its existing stylesheet. Optional icon/label/description content lives in the shared option owner. Format Cells and generic gallery lists use the same markup, keyboard handling and styles; formatter-specific IDs and data policy stay in Pro.
+
+## Preact element construction
+
+All shared UI markup is Preact TSX. Element-returning compatibility APIs mount the same TSX through `preact-mount.tsx`; they do not build parallel DOM trees. Lifecycle controllers may attach, position, focus and dispose rendered roots. Grid/Stencil VNode adapters retain the Core rendering contract. Charts controls use Preact through the same mount boundary; chart scene/export geometry remains scene-owned.

package/README.md

@@ -1,3 +1,345 @@
-# Temporary Holding Version
+# RevoGrid shared UI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared controls for Grid Pro, Pivot, Charts, Gantt, Scheduler, Kanban and standalone examples. The workspace uses source exports; `pnpm pack:public` prepares an independently installable, ESM distribution with JavaScript, declarations, CSS and Angular partial-compilation metadata. Preparing the archive does not publish it to a registry. Public availability does not change the existing Commercial license.
+
+## Entry points
+
+```ts
+// No grid or global browser state required at import time.
+// Preact is the required shared rendering peer.
+import {
+  DialogController,
+  PopoverController,
+  attachMenuKeyboard,
+} from '@revolist/ui/native';
+
+// Optional Preact rendering adapters.
+import { Button, Switch, Calendar, DateRangePicker } from '@revolist/ui/preact';
+
+// Import once in a product's styles entry.
+import '@revolist/ui/styles.scss';
+```
+
+The root entry is the native entry. `tokens.scss` exposes tokens separately. The distribution preserves the existing exported subpaths. Import only declared package exports; unexported implementation files are not an API.
+
+## Inline badges
+
+Use `Badge` from `@revolist/ui/preact` or `VueBadge` from
+`@revolist/ui/vue-badge`. Both accept `variant="neutral"` for inactive counts,
+`variant="accent"` for blue selected states, and `shape="pill"` (default) or
+`shape="rounded"`. The default `solid` variant preserves existing badge tokens.
+Vue renders the default slot and forwards native attributes and classes.
+
+## Component catalog
+
+| Family            | Components                                                                                                              |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Actions           | Button, IconButton, ToggleButton, ButtonGroup, Icon                                                                     |
+| Binary and choice | Checkbox, Switch, RadioGroup, ChoiceChips                                                                               |
+| Navigation        | SegmentedControl, Tabs, TabPanel, Listbox, ListboxOption                                                                |
+| Fields            | TextInput, Textarea, SearchInput, NumberInput, NumberStepper, NativeSelect                                              |
+| Selection         | Dropdown, Combobox, MultiSelect, Chip, RemovableChip, ResourcePicker                                                    |
+| Numeric ranges    | TimelineTrack, Slider, RangeSlider; native scalar-slider/counter adapters                                                              |
+| Dates             | Calendar and its header/day/month/year parts, DateInput, TimeInput, DateTimeInput, DatePicker, DateRangePicker          |
+| Appearance        | ColorPalette, ColorPicker, Avatar                                                                                       |
+| Forms             | FormField, FieldHint, FieldError, FormSection, Disclosure, DisclosureSummary                                            |
+| Surfaces          | Dialog, DialogHeader, DialogBody, DialogFooter, ConfirmDialog, Popover, Tooltip, Menu, MenuItem, MenuSeparator, Submenu |
+| Composition       | Toolbar, ToolbarGroup, ToolbarSeparator, SplitLayout, Pane, Panel, ResizeHandle                                         |
+| Feedback          | Badge, CountBadge, StatusBadge, Alert, FeedbackPanel, Spinner, LoadingOverlay, EmptyState                               |
+| Indicators        | Pagination, ProgressBar, CircularProgress, Rating                                                                       |
+
+Native controllers own lifecycle, keyboard interaction, portal placement and cleanup. Preact adapters own rendered state, while product adapters own grid integration. Exported native rendering helpers accept the host's element factory so Charts can keep its existing DOM renderer.
+
+See [OWNERSHIP.md](./OWNERSHIP.md) for implementation/style owners, renderer contracts and intentional product adapters.
+
+## Ownership and compatibility
+
+- UI does not import Core, Pro, or another product. Dates and working-calendar calculations stay in `@revolist/dates`.
+- Existing Pro exports and leaf modules forward to the shared owner. Grid edit events, focus preservation, popup coordination, remote loading and cell/column types stay in Pro adapters.
+- Task/card/event editors, working-calendar editors, Pivot configurators and chart inspectors remain product compositions.
+- Controlled inputs receive values and callbacks. Date controls use civil date/native input strings; products retain timezone conversion, storage and validation policy.
+- Sliders distinguish live input and commit callbacks. Popup/dialog handles have explicit teardown, and returned cleanup functions release listeners.
+- `--rv-ui-*` variables define semantic surfaces, text, focus and control tokens. Existing classes and legacy feature variable overrides remain supported.
+- Use the separate native entry in Charts. Importing the Preact barrel in Charts would violate the dependency boundary.
+
+## Gallery and checks
+
+The standalone gallery app lives in [`apps/ui-gallery`](../../apps/ui-gallery). Run `pnpm dev:ui` from the repository root, or `pnpm dev` from that app directory.
+
+```sh
+pnpm --filter @revolist/ui-gallery dev
+pnpm --filter @revolist/ui-gallery build
+pnpm --filter @revolist/ui lint
+pnpm --filter @revolist/ui test
+pnpm --filter @revolist/ui-gallery test:browser
+```
+
+The gallery shows default, compact, disabled, selected, mixed, invalid, read-only, loading, light/dark and RTL examples. The Chromium suite uses the built gallery and covers keyboard controls, nested overlays, focus return, multiple picker instances and narrow layouts. CI runs UI unit tests in the remaining-package group and browser tests alongside the existing Chromium integration job.
+
+Colocated owner tests cover extracted implementations. Pro keeps consumer integration tests for its event adapters and compatibility exports. The build tooling bundles UI declarations into each product's `_shared/ui` directory so published types do not depend on this private workspace package.
+
+The gallery also demonstrates filter building blocks without a grid: distribution charts with range brushes, generic option rows, weekly time grids and legends, inline field groups and highlighted text inputs. Import these from the Preact entry; consuming products supply data, localized text and domain policy.
+
+Grid-backed selection and filter policy belong to Pro.
+
+Compact `BarChart`, `LineChart` and `AreaChart` render independently of brush controls or grid instances. Import them from `@revolist/ui/preact` or their leaf entries (`@revolist/ui/bar-chart`, `@revolist/ui/line-chart`, `@revolist/ui/area-chart`). They accept explicit `data`, `ariaLabel`, height, selection flags and tooltip content. `DistributionChart` preserves the existing type-switching contract; `BrushRange` remains the slider composition. The gallery includes separate bar and line cards.
+
+Field configurators use `FieldLibrary`, `FieldLibraryList`, `FieldGroup`, `FieldGroupHeading`, `FieldList`, `FieldRow`, `FieldItem`, and `FieldContent` from `@revolist/ui/field-configurator` (also in the Preact entry). They provide native disclosure, row structure and slots, not field metadata or query policy. Pivot compatibility exports delegate here; Pivot owns search policy, axis assignment, ordering and selection state.
+
+### Interactive timeline track
+
+`TimelineTrack` from `@revolist/ui/timeline-track` (also exported through `preact`) renders controlled `{ id, event: { start, end, label? } }` rows. Supply a finite increasing `range`, optional selected ID and label callbacks, `onSelect`, and `onEventChange`. Event changes preserve extra event metadata. The component owns pointer movement, edge resizing, ArrowLeft/ArrowRight edits, selection presentation and range labels; consumers own draft validation, storage and commits. Import the common styles entry once. The Sliders gallery includes an interactive example.
+
+### Editable dialogs and standard actions
+
+Compose `EditableDialogHeader`, `DialogBody`, and `DialogActionFooter` inside `DialogForm`. These parts are exported from `@revolist/ui/dialog/dialog.parts` and `@revolist/ui/preact`; they preserve the consumer's native dialog lifecycle and form callbacks. Scheduler, Kanban and Gantt use this composition.
+
+The header accepts `titleId`, controlled `title`/`inputProps`, an accessible `inputLabel`, optional dialog `name` and description, and a close callback/label. Use `inputProps={false}` for a static heading. Native disabled/readonly semantics pass through.
+
+The footer shows standard Cancel and submit Save actions by default. `cancel`, `save`, `deleteAction`, and `reset` accept labels and native button attributes/callbacks; set any action to `false` to hide it. Delete and Reset are opt-in and default to `type="button"`, so they never accidentally submit. `start` and `end` accept custom content on each side; `children` adds validation or other content above the action panel. Product translations and permissions remain explicit. See the Dialogs and floating surfaces gallery example for all actions, custom slots and hidden defaults.
+
+### Selection lists
+
+`Listbox`, `ListboxOption`, and `ListboxGroup` are available from `@revolist/ui/selection-list` and the Preact entry. Options support `icon`, `label`, and `description` directly, or arbitrary children for custom content. Groups add visible headings and accessible group labels. List selection and ArrowUp/ArrowDown/Home/End handling share one owner, including disabled-option skipping. Plain text, rich and grouped variants are demonstrated together in the Selection list gallery example. Format Cells consumes this same option API; it has no separate selection-list implementation. Existing EditorList and content-wrapper imports remain compatible.
+
+### Interface colors
+
+See [Colors and usage](COLORS.md) for semantic roles, theming, and compatibility overrides. The gallery header links to the independent Colors page (`?page=colors`).
+
+Built-in product defaults live in named `src/color-palette/*-palettes.ts` modules. The Colors page shows each palette's values, usage, and consumers. Products import purpose-specific constants or the generated `@revolist/ui/palettes.scss` lookup; run `pnpm --filter @revolist/ui generate:palettes` after changing definitions. `check:palettes` verifies the generated source is current.
+
+## Accessibility
+
+See [Accessibility review and integration requirements](ACCESSIBILITY.md) for tested coverage, remaining gaps, and consumer responsibilities. Automated gallery checks are part of the shared UI browser suite.
+
+## Motion
+
+See [Shared UI motion](MOTION.md) for the component review, timings, and disable policy. Add `data-rv-ui-motion="off"` to the document or a region to disable motion; OS reduced motion is always respected. The gallery includes a Motion selector.
+
+### Busy buttons
+
+`Button`, `IconButton`, `ToggleButton`, `SvgButton` and `ButtonControl` accept `busy?: boolean`. Set `busy` while an action is pending, then clear it when the action completes (including failure). A loading ring appears, the accessible name stays intact, and native disabling blocks clicks, keyboard activation and form submission. Busy buttons retain their normal variant colors; an explicit `disabled` prop still takes precedence visually and remains disabled after busy clears. The same option is supported by `createControl(document, 'button', { busy: true })`.
+
+```tsx
+<Button variant="primary" busy={saving} onClick={save}>Save changes</Button>
+```
+
+The ring inherits the button text color. Motion Off (`data-rv-ui-motion="off"`) and `prefers-reduced-motion` keep the loading ring visible without spinning. Busy state is controlled by the caller; it does not start or finish an asynchronous task itself.
+
+## Standalone framework controls
+
+Import `@revolist/ui/styles.css` once for compiled standard styles. The public build bundles private date/chart utilities; customers do not need private workspace packages or a TypeScript/Sass source compiler. Preact is required by the shared rendering layer; React, Vue, Angular and Svelte are optional peers used only by their adapter subpaths.
+
+```ts
+import { createControl, applyControlPresentation } from '@revolist/ui';
+import { ButtonControl, Input, Select, TextArea } from '@revolist/ui/react-control';
+import { vRvControl } from '@revolist/ui/vue-control'; // <button v-rv-control>
+import { UiControlDirective } from '@revolist/ui/angular-control'; // standalone imports; <button rvControl>
+import { rvControl } from '@revolist/ui/svelte-control'; // <button use:rvControl>
+import '@revolist/ui/styles.css';
+```
+
+Each adapter preserves native elements, events, values and form bindings. React controls forward native refs. Vue and Angular directives and the Svelte action retain native refs and bindings. `applyControlPresentation(root)` handles existing static toolbar HTML; call it after replacing that HTML or changing a control type.
+
+## Build and release preparation
+
+Run `pnpm --dir packages/ui pack:public` from the monorepo, then `pnpm --dir packages/ui test:public`. The generated public package is `dist/`, and the archive is `artifacts/revolist-ui-<version>.tgz`. The workspace manifest intentionally remains private; the generated distribution manifest declares public access and contains no workspace dependencies.
+
+Before publication, standalone repositories consume an identical archive in their own `vendor/` directory using relative `file:` dependencies and a lockfile generated against that real archive. These paths are portable with the cloned repository. Include its vendor archive when copying a starter out of that repository. After an authorized registry release, dependencies can switch to the published version and locks can be regenerated from the registry. Do not substitute unverified registry URLs or integrity values for the prepared archive.
+
+The Publish NPM workflow includes UI in `all` releases and supports a standalone `ui` selection. It applies the release tag version, runs the public build and archive consumer checks, then signs and publishes the compiled `dist/` package to npm with public access using the `NPM_TOKEN` repository secret. Local build and preparation scripts do not publish. Once the release is available, demos can install `@revolist/ui` from npm with their required framework peers.
+
+## Vue component wrappers
+
+`@revolist/ui/vue` exposes Vue wrappers for the Preact component catalog and the
+standalone number, mask, duration, temporal, assignee and Markdown editors.
+These wrappers retain the existing Preact implementation and require both Vue
+and Preact. Use `vue-control` for native HTML controls that only need presentation;
+its runtime presentation helpers do not import Preact.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Dropdown, DatePicker, Dialog } from '@revolist/ui/vue';
+import '@revolist/ui/styles.css';
+
+const status = ref('open');
+const source = [
+  { value: 'open', label: 'Open' },
+  { value: 'closed', label: 'Closed' },
+];
+</script>
+
+<template>
+  <Dropdown v-model="status" :source="source">
+    <template #option="{ option, selected }">
+      <strong>{{ option.label }}</strong>
+      <span v-if="selected"> Selected</span>
+    </template>
+  </Dropdown>
+</template>
+```
+
+- Values, callback props and configuration keep their existing contracts.
+  `v-model` additionally connects Dropdown/Combobox/MultiSelect, the scalar
+  inputs, Switch/Checkbox, choice controls, rating, color and date pickers.
+  ResourcePicker uses `selectedResourceIds`; CalendarPicker uses `selected`.
+  RangeSlider keeps `fromValue`, `toValue`, `onRangeChange` and `onRangeCommit`;
+  it does not flatten a two-handle range into a scalar model.
+- Default slots supply `children`; named content slots supply the matching
+  component prop (for example Dialog's `footer` and Switch's `label`). Dropdown
+  has scoped `option` (`option`, `selected`), `value` (`option`), `content`
+  (`content.id`, `content.close`) and `noResults` slots. ReorderList has `item`
+  and `handle` slots (`item`, `index`). Use Vue slots for Vue VNodes, rather than
+  returning them from a Preact render callback.
+- Vue owns slot content via Teleport, preserving injection and reactive updates.
+  Preact owns the surrounding control. Mount and slot boundaries add elements
+  styled with `display: contents`; DOM code depending on direct-child selectors
+  must account for these boundaries. Supply explicit accessible labels and input
+  associations instead of relying on Preact inspecting Vue slot VNodes.
+- The exposed `element` ref is the mount boundary, not the component's internal
+  input. Existing explicit `inputRef` callback props remain available.
+- Wrappers render empty boundaries on the server and mount interactive UI on the
+  client. They do not provide server-rendered component content.
+- Unmounting disposes the Preact root and its effects, portals and controllers.
+
+`createVueAdapter` is exported for application-owned Preact compositions using the
+same lifecycle. The catalog's wrapper factory calls are marked pure for consumer
+bundle tree shaking.
+
+The focused browser check runs against its own framework fixture, independently of the
+Preact gallery:
+
+```sh
+pnpm --filter @revolist/ui-gallery exec playwright test --config ../../tests/shared-ui/playwright.framework-adapters.config.ts
+```
+
+## React, Angular and Svelte component adapters
+
+All adapters reuse the existing Preact controls and their interaction lifecycle.
+Import `@revolist/ui/styles.css` once. Install Preact and your host framework;
+React component wrappers also require `react-dom`. The primitive `*-control`
+entries remain available for framework-owned native elements.
+
+### React
+
+`@revolist/ui/react` provides named components matching the shared catalog and
+standalone editors. Props and controlled callbacks keep their shared names.
+React owns children and custom content through portals, preserving React context
+and state. `renderPlaceholder` receives only placeholder text; `renderSelectedValue`
+receives only selected options. Built-in Preact child VNodes are not passed to React. Dropdown render callbacks omit the Preact element-factory argument:
+
+```tsx
+import { Dropdown, Dialog } from '@revolist/ui/react';
+
+<Dropdown
+  source={source}
+  value={selected}
+  onChange={setSelected}
+  renderOption={(option, selected) => (
+    <strong aria-current={selected}>{option.label}</strong>
+  )}
+/>
+
+<Dialog open={open} title="Edit" closeLabel="Close" onClose={close}
+  footer={<button onClick={save}>Save</button>}>
+  <Editor />
+</Dialog>
+```
+
+Wrappers expose `{ element }` through their React ref: this is the mount boundary,
+not an internal input. Shared control callbacks receive native DOM events; they
+do not synthesize React events. NativeSelect renders directly in React to retain
+native `<option>` children and also offers `onValueChange`.
+
+### Angular
+
+Import standalone `UiComponent` and `UiSlotDirective` from `@revolist/ui/angular`.
+The generic `<rv-ui>` host accepts any shared catalog name in `component` and its
+controlled values/configuration in `props`. `valueChange` forwards the component's
+primary model callback; `uiEvent` forwards `{ name, args }` for supplied `on*`
+callbacks, the primary model callback, and `onClose`. Supplied callbacks still run
+and retain their return values. Use immutable `props` updates so Angular can
+observe configuration changes.
+
+```html
+<rv-ui component="Dropdown" [props]="{ source: source, value: selected }"
+       (valueChange)="selected = $any($event)">
+  <ng-template rvUiSlot="option" let-option="option" let-selected="selected">
+    <strong>{{ option.label }}</strong>
+  </ng-template>
+</rv-ui>
+```
+
+Use `rvUiSlot="default"` for children, `rvUiSlot="footer"` for a dialog footer,
+and the same scoped option/value/content slots described for Vue. Angular keeps
+ownership and change detection of embedded views after they move into controls.
+Use `<select rvControl>` for Angular-owned native option templates; the generic
+host rejects NativeSelect template slots instead of nesting options in an invalid
+slot container. Public Angular entries ship partial-compilation metadata.
+
+### Svelte 5
+
+`@revolist/ui/svelte` exports `UiComponent`, a generic catalog host. Supply shared
+props and callbacks, or use `onValueChange` to observe the primary controlled
+callback. `onUiEvent` receives the same event envelope as Angular. Named snippets
+use the same scope names as Angular/Vue slots. Replace the `props` object when
+changing configuration.
+
+```svelte
+<script lang="ts">
+  import { UiComponent } from '@revolist/ui/svelte';
+  let selected = $state('open');
+  const source = [{ value: 'open', label: 'Open' }];
+</script>
+
+<UiComponent component="Dropdown" props={{ source, value: selected }}
+  onValueChange={value => selected = value as string} slots={{ option }} />
+
+{#snippet option(scope: Record<string, any>)}
+  <strong>{scope.option.label}</strong>
+{/snippet}
+```
+
+Default children and named snippets remain Svelte-owned, with their original
+context and reactive updates. NativeSelect renders options directly in Svelte.
+The public package supplies a Svelte source condition plus precompiled browser
+and server entry points, so server imports do not execute client mounting code.
+
+### Rendering boundaries and verification
+
+Complex wrappers mount on the client and render empty boundaries on the server;
+full server-rendered control markup is not provided. Native selects retain their
+framework's native rendering. Content uses additional elements styled with
+`display: contents`; direct-child DOM selectors must account for those elements.
+Provide explicit labels and associations when child-VNode inspection would
+otherwise determine them. Unmounting releases Preact effects and portals along
+with the host framework's content. Angular/Svelte's generic hosts include the
+catalog lookup; React's named factory calls are marked pure for tree shaking.
+
+`UiComponentName` and `UiComponentProps<Name>` are available from the Angular,
+Svelte and framework entries for explicitly typing application configurations.
+The dedicated browser fixture covers all four frameworks:
+
+```sh
+pnpm --filter @revolist/ui lint:svelte
+pnpm --filter @revolist/ui-gallery exec playwright test --config ../../tests/shared-ui/playwright.framework-adapters.config.ts
+```
+
+### PDF viewer
+
+`PdfViewer` adds PDF rendering, text selection/search, page navigation, zoom/fit,
+rotation, local files, download and printing. It is available through the Preact,
+React and Vue entries and the Angular/Svelte component catalog. Install the optional
+`pdfjs-dist` peer and provide its matching worker URL. See
+[`src/pdf-viewer/README.md`](src/pdf-viewer/README.md) for setup, API and lifecycle.
+
+
+Pagination supports `boundaryButtons` to show or hide the first/last page buttons.
+The native `PaginationPanel` (and Pro pagination) defaults to `true`; the framework
+`Pagination` component defaults to `false` to preserve its existing appearance.
+Set `boundaryButtons={false}` to keep only previous/next controls. With
+`navigation={false}`, all navigation buttons are hidden. Framework `Pagination`
+also accepts localized `firstLabel`/`lastLabel` and children for a page field or selector.
+
+`DateTimeField` and the native date/time popup adapter share a compact time selector: typed entry plus keyboard-accessible hour/minute columns, optional seconds (`precision: 'second'`) and localized AM/PM (`timeFormat: '12h'` or `'locale'`). `minTime`, `maxTime` and `timeStep` constrain each choice; intervals are anchored to `minTime` when supplied. Single datetime pickers place the same panel beside the calendar and stack it on narrow screens. Existing `autoApply`, `showActions`, `required` and action labels retain their behavior. Override `text.hours`, `minutes`, `seconds`, `dayPeriod` and `noTimes` alongside the existing time labels for translations. Vue, React and Angular fields use the same shared implementation.

package/_button.scss

@@ -0,0 +1,75 @@
+@use './styles/motion';
+/**
+* Buttons styling
+*/
+
+@use './variables' as *;
+
+.rv-button {
+  border: 1px solid var(--rv-ui-btn-outline-border);
+  border-radius: 5px;
+  background-color: var(--rv-ui-btn-outline-bg, transparent);
+  color: var(--rv-ui-btn-outline-fg, inherit);
+  transition:
+    background-color var(--rv-ui-motion-fast, 120ms) var(--rv-ui-motion-ease, ease),
+    color var(--rv-ui-motion-fast, 120ms) var(--rv-ui-motion-ease, ease),
+    border-color var(--rv-ui-motion-fast, 120ms) var(--rv-ui-motion-ease, ease),
+    opacity var(--rv-ui-motion-fast, 120ms) var(--rv-ui-motion-ease, ease);
+
+  &:not(.disabled) {
+    cursor: pointer;
+  }
+
+  &.disabled {
+    opacity: 0.5;
+  }
+
+  &.small {
+    padding: 3px 6px;
+    min-width: 30px;
+    font-size: 16px;
+  }
+
+  &:not(.small) {
+    padding: 5px 20px;
+    font-size: 14px;
+  }
+
+  &:not(.disabled):hover {
+    background-color: var(--rv-ui-btn-outline-bg-hover, $button-alt-bg-light-hover);
+    border-color: var(--rv-ui-btn-outline-border-hover);
+  }
+
+  &.dark {
+    border-color: var(--rv-ui-btn-outline-border, $button-alt-bg-light);
+    background-color: var(--rv-ui-btn-outline-bg, $background-color-dark);
+    color: var(--rv-ui-btn-outline-fg, $text-color-dark);
+  }
+
+  &.solid {
+    border-color: transparent;
+    background-color: var(--rv-ui-btn-bg);
+    color: var(--rv-ui-btn-fg);
+
+    &:not(.disabled):hover {
+      background-color: var(--rv-ui-btn-bg-hover, $button-alt-bg-light);
+      border-color: transparent;
+    }
+  }
+
+  &:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 2px var(--rv-ui-focus-ring);
+  }
+}
+
+revo-grid[theme^='dark'] .rv-button:not(.solid) {
+  border-color: var(--rv-ui-btn-outline-border, $button-alt-bg-light);
+  background-color: var(--rv-ui-btn-outline-bg, $background-color-dark);
+  color: var(--rv-ui-btn-outline-fg, $text-color-dark);
+
+  &:hover {
+    background-color: var(--rv-ui-btn-outline-bg-hover, $button-alt-bg-light);
+    border-color: var(--rv-ui-btn-outline-border-hover, $button-alt-bg-light);
+  }
+}