@povio/ui 5.0.0-rc.8 → 6.0.0-rc.1

package/README.md

@@ -2,6 +2,8 @@
 
 UI Components that match Povio's Atlas Design System.
 
+Upgrading an existing project? See the [migration guide](MIGRATION.md) for the web form, selection, upload, date/time, table, and page-builder changes.
+
 ## Installation
 
 `bun add @povio/ui`
@@ -14,17 +16,52 @@ Use component and feature subpaths in application code. Each subpath resolves to
 import { Button } from "@povio/ui/button";
 import { BadgeButton } from "@povio/ui/badge-button";
 import { Dialog } from "@povio/ui/dialog";
-import { Select } from "@povio/ui/tanstack/select";
+import { Select } from "@povio/ui/select";
 import { useForm } from "@povio/ui/tanstack/form";
 import { Table } from "@povio/ui/tanstack/table";
 import { RichTextEditor } from "@povio/ui/rich-text-editor";
 ```
 
-Form inputs are available from matching integration paths, such as `@povio/ui/rhf/input` and `@povio/ui/tanstack/input`. Dynamic input builders are exposed from `@povio/ui/rhf/inputs` and `@povio/ui/tanstack/inputs`.
+TanStack Form is the supported form integration. Import form inputs from `@povio/ui/tanstack/input` and other component subpaths, hooks from `@povio/ui/tanstack/form`.
+
+Ordinary component subpaths expose standalone controls: `@povio/ui/input` accepts `value`/`onChange` or an uncontrolled `defaultValue`, and rejects `field`. The corresponding `@povio/ui/tanstack/input` requires `field={{ form, name }}` and rejects top-level values, change/blur handlers, and defaults; initialize values through `useForm({ defaultValues })`. Boolean controls use `isSelected`/`onChange` and `defaultSelected` when standalone. Date/time controls use string values and defaults; number controls use numbers or null. The broad root and TanStack barrels expose the bound versions.
+
+Optional side effects belong inside the binding: `field={{ form, name: "name", onValueChange: value => ..., onBlur: () => ... }}`. Change callbacks receive the native control value after the raw form update; blur callbacks run after actual focus loss marks the field touched. Selection commits can validate/flush autosave without firing the blur callback. Form resets and programmatic setters do not call either callback.
+
+`FileInput` binds native `File`/`File[]` values. `FileUpload` also binds files while managing upload progress, cancellation, and server IDs internally. Its standalone `value` accepts upload state records for existing uploads, while `onChange` emits selected native files; changes to supplied upload state are reflected in its display.
+
+The broad `@povio/ui` and `@povio/ui/tanstack` entries remain for compatibility. They are not recommended for new application imports because they reconnect otherwise independent feature graphs.
+
+Feature dependencies are optional peers. Install the matching packages when using date/calendar entries, `@povio/ui/tanstack/table`, TanStack Form inputs, or the rich text editor. Basic components such as Button, Typography, and Dialog do not require table, drag-and-drop, calendar, or TipTap packages.
+
+```tsx
+import { useForm } from "@povio/ui/tanstack/form";
+import { Input } from "@povio/ui/tanstack/input";
+import { z } from "zod";
+
+const schema = z.object({ name: z.string().min(1) });
+
+function NameForm({ onSubmit }: { onSubmit: (values: z.output<typeof schema>) => void }) {
+  const form = useForm({ defaultValues: { name: "" }, zodSchema: schema });
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)}>
+      <Input
+        label="Name"
+        field={{ form, name: "name" }}
+      />
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
 
-The broad `@povio/ui`, `@povio/ui/rhf`, and `@povio/ui/tanstack` entries remain for compatibility. They are not recommended for new application imports because they reconnect otherwise independent feature graphs.
+### Migrating existing forms
 
-Feature dependencies are optional peers. Install the matching packages when using date/calendar entries, `@povio/ui/tanstack/table`, RHF/TanStack Form inputs, or the rich text editor. Basic components such as Button, Typography, and Dialog do not require table, drag-and-drop, calendar, or TipTap packages.
+The web UI package no longer maintains React Hook Form (RHF) integration. The root entry now exports the TanStack barrel. Replace imports from `@povio/ui/rhf` and its subpaths with the TanStack paths above, and replace `formControl={{ control: form.control, name }}` with `field={{ form, name }}`. Keep component names such as `Input`. Compose fields explicitly in JSX and declare TanStack table columns directly.
+
+Use `zodSchema` for validation and `form.handleSubmit(onSubmit, onInvalid)` for submission; the valid callback receives transformed schema values. Replace `form.watch(...)` with `useFormValue(form, values => values.name)` and form-state subscriptions with `useFormState(form, state => state.isSubmitting)`, both from `@povio/ui/tanstack/form`. Replace values through `form.reset(values)`, which clears dirty and touched state. Autosave hooks remain available from the TanStack barrel.
+
+Standalone controls keep their existing `value` / `onChange` or `isSelected` / `onChange` props. Consumers can build an external RHF adapter using those props. Mobile and `@povio/rn-ui` retain their own RHF integrations.
 
 React Aria is an internal `@povio/ui` dependency and does not need to be installed separately. The build keeps `react-aria` and all its subpaths external so providers and Povio components share the installed module contexts. Component-scoped escape-hatch entries expose only the corresponding React Aria primitive and its types for custom implementations:
 
@@ -43,28 +80,112 @@ Each emitted entry is independently bundled and tree-shaken; it does not forward
 
 Use `Badge` for display content, `BadgeButton` for a compact, badge-styled action, and `ToggleButton` or `ToggleGroup` for selection. `BadgeButton` uses the theme's `badge-*` spacing and radius tokens; customize its recipe through `UIOverrides.badgeButton`.
 
+## Selection and text suggestions
+
+Use `Select` to store an item ID, or an array of IDs with `selectionMode="multiple"`. Set `isSearchable` to filter the choices. Typing a search query does not change the selected ID.
+
+Use `Autocomplete` to store free text. Its `value` and `onChange` use strings, selecting a suggestion emits its label, and clearing emits `""`. Text need not match a suggestion. Suggestion IDs identify rows; they are never the submitted value.
+
+```tsx
+import { Select } from "@povio/ui/select";
+import { Autocomplete } from "@povio/ui/autocomplete";
+
+const cities = [{ id: "city-1", label: "Ljubljana" }];
+// Choosing Ljubljana stores "city-1".
+<Select
+  label="City"
+  items={cities}
+  value={cityId}
+  onChange={setCityId}
+  isSearchable
+/>;
+// Choosing Ljubljana stores "Ljubljana"; arbitrary city names are also allowed.
+<Autocomplete
+  label="City name"
+  items={cities}
+  value={cityName}
+  onChange={setCityName}
+/>;
+```
+
+Migrate ID-valued autocomplete controls to `Select isSearchable`, including controls with multiple selections. Form bindings follow the same distinction: bind `Select` to an ID field and `Autocomplete` to a text field.
+
+### Async choices
+
+Supply an explicit loader through `useAsyncList` and pass its result to `Select` as `list`. The loader controls the request, response mapping, cancellation, and pagination; it returns `{ items, cursor }`, with an omitted cursor for the last page. Each control should have its own list so searches remain independent.
+
+```tsx
+import { Select } from "@povio/ui/select";
+import { useAsyncList } from "@povio/ui/use-async-list";
+
+const list = useAsyncList({
+  initialSelectedKeys: cityId ? [cityId] : [],
+  load: async ({ signal, filterText, cursor, selectedKeys }) => {
+    const page = await loadCities({ signal, search: filterText, cursor, selectedKeys });
+    return { items: page.items, cursor: page.nextCursor ?? undefined };
+  },
+});
+
+<Select
+  label="City"
+  value={cityId}
+  onChange={setCityId}
+  list={list}
+  isSearchable
+/>;
+{
+  list.error && (
+    <div role="alert">
+      {list.error.message}
+      <button onClick={() => list.reload()}>Retry</button>
+    </div>
+  );
+}
+```
+
+The hook starts loading when mounted. The control forwards search changes and scroll pagination to the list and leaves server-ranked items unfiltered. Display `list.error` and a retry action beside the control; `list.reload()` retries the current filter. If a saved ID is outside the first page, supply its label through `initialSelection`, or resolve `selectedKeys` in your loader and merge the selected items with the page. Selecting still emits IDs, and selected labels remain visible when subsequent searches exclude those IDs. Use `field={{ form, name }}` with the bound `@povio/ui/tanstack/select` entry instead of value callbacks for a form field.
+
+`QuerySelect`, `QueryAutocomplete`, and their query-hook adapters have been removed. Call regular API functions inside loaders; query hooks belong at component scope. Applications can retain their existing query cache, authorization checks, and response validation around those API calls, as the admin application's `useAsyncLabelList` does.
+
 ## Theme configurator
 
-The live theme editor ships separately as `@povio/ui/ui-configurator`, with its stylesheet at `@povio/ui/ui-configurator/styles`. It is independent of Storybook and is excluded from ordinary component imports. For only the `parseThemeCss` / `exportCss` helpers and token types, use the lightweight `@povio/ui/ui-configurator/theme` entry.
+Install it as a development dependency with `bun add -d @povio/ui-configurator`. The live theme editor ships separately as `@povio/ui-configurator`, with its stylesheet at `@povio/ui-configurator/styles`. It is independent of Storybook and is excluded from ordinary component imports. For only the `parseThemeCss` / `exportCss` helpers and token types, use the lightweight `@povio/ui-configurator/theme` entry.
 
 To save its Tailwind CSS export directly to your app's theme during development, add the bundled Vite plugin:
 
 ```ts
-import { uiConfigurator } from "@povio/ui/ui-configurator/vite";
+import { uiConfigurator } from "@povio/ui-configurator/vite";
 
 // In your Vite plugins array:
 uiConfigurator({ themeFile: "src/styles/theme.css" });
 ```
 
-The path defaults to `src/styles/theme.css` relative to this app's Vite root. **Advanced → Export → Tailwind CSS → Save theme** updates that file's token declarations and lets Vite reload the CSS. Each app writes only its own configured theme. Apply remains session-only; Cancel does not undo a file save. The plugin and save action are absent from builds and preview servers. See [the configurator guide](./src/configurator/README.md) for provider setup, preview behavior, and supported theme blocks.
+The path defaults to `src/styles/theme.css` relative to this app's Vite root. **Advanced → Export → Tailwind CSS → Save theme** updates that file's token declarations and lets Vite reload the CSS. Each app writes only its own configured theme. Apply remains session-only; Cancel does not undo a file save. The plugin and save action are absent from builds and preview servers. See [the configurator guide](../ui-configurator/README.md) for provider setup, preview behavior, and supported theme blocks.
+
+## Choosing buttons
+
+Choose a button by its interaction:
+
+| Interaction                                        | Component                                                                                  |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Action with a visible label, optionally with icons | `Button` from `@povio/ui/button`                                                           |
+| Action displayed as an icon                        | `IconButton` from `@povio/ui/icon-button`, with an accessible name such as `label="Close"` |
+| Persistent selected/unselected state               | `ToggleButton` from `@povio/ui/toggle-button`                                              |
+| Primary action with a separate menu trigger        | `SplitButton` from `@povio/ui/split-button`                                                |
+
+`BadgeButton` remains available for interactive badges, including its existing selection behavior. Use ordinary badge/status components for information without an action. An icon-only selected action uses `ToggleButton iconOnly` with an accessible name; `Button` itself does not accept `iconOnly`, `toggle`, or selection props.
+
+Text appearance is `Button variant="text"`. For the former TextButton defaults, also specify `width="hug"`. The former InlineIconButton appearance is `IconButton variant="text" size="sm" width="hug" disableTooltip`; preserve any explicitly supplied size. `IconButton` provides a tooltip by default, so disable it when an enclosing tooltip already supplies one or when preserving the old inline appearance.
+
+See the [button migration steps](./MIGRATION.md#13-choose-buttons-by-behavior) for removed exports and exact replacements.
 
 ## Button sizes
 
-`Button` supports `sm` (with `s` as an equivalent alias), `default`, and `none` (zero padding). Omitting `size` uses `default`. The same sizes apply to `IconButton`, `InlineIconButton`, `TextButton`, `ToggleButton`, and `SplitButton`.
+`Button` supports `sm` (with `s` as an equivalent alias), `default`, and `none` (zero padding). Omitting `size` uses `default`. The same sizes apply to `IconButton`, `ToggleButton`, and `SplitButton`.
 
 When migrating, replace `xs` and `small` with `sm`; remove explicit `default`, `m`, `md`, `l`, and `lg` size props to use the default. `sm` uses the existing small spacing tokens, and `default` uses the medium spacing tokens.
 
-Use `<TextButton size="none">Read more</TextButton>` for a text action without button padding.
+Use `<Button variant="text" width="hug" size="none">Read more</Button>` for a text action without button padding. The focused button cleanup preserves these sizes, spacing tokens, variants, and colors.
 
 ## Input sizes
 
@@ -72,27 +193,62 @@ Inputs support `size="small"` and `default`. Omit `size` for the default. This a
 
 Replace `size="extra-small"` with `size="small"`, and remove `size="large"` or `size="default"` to use the default. Small and default retain their existing spacing.
 
-## Built-package tests
+## Date and time values
 
-From `packages/ui`, run `bun run test:package` to build the publishable package and run its Chromium regressions. The tests resolve public imports through `dist/package.json`, covering both date pickers with empty and populated values in static and editable modes, including locale switches without remounting.
+The standalone date/time subpaths accept `value`/`onChange` or an initial `defaultValue`. Passing `null` clears a control; omitting `value` leaves it uncontrolled. TanStack versions take their values/defaults from the bound field, and `field.onValueChange` receives the same output after the form updates.
 
-## Versioning
+| Control           | Input and output format                                                                                                                                     | Empty output                                                |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `DatePicker`      | `fullIso=true` (default): UTC-calendar date, emitted as `YYYY-MM-DDT00:00:00.000Z`. `fullIso=false`: `YYYY-MM-DD`.                                          | `null`                                                      |
+| `DateRangePicker` | `{ start, end }`; `fullIso=true` (default) emits start at UTC `00:00:00.000Z` and end at UTC `23:59:59.999Z`. `fullIso=false` emits `YYYY-MM-DD` endpoints. | `null`; a null endpoint is allowed with `allowPartialRange` |
+| `DateTimePicker`  | Input ISO timestamp with `Z` or an explicit offset; output UTC instant as `YYYY-MM-DDTHH:mm:ss.sssZ`.                                                       | `null`                                                      |
+| `TimePicker`      | Input ISO timestamp with `Z` or an explicit offset; output edited clock time on the date anchor as `YYYY-MM-DDTHH:mm:ss.sssZ`.                              | `null`                                                      |
 
-`^2.1` still corresponds to Atlas 2.1. All versions after that currently target Atlas 2.2 and follow semantic versioning — breaking changes bump the major version.
+`fullIso` is supported by `DatePicker` and `DateRangePicker`. Remove it from `DateTimePicker` and `TimePicker`: it previously had no effect, and their output always contains a full UTC timestamp.
 
-## AI component rules
+Date-only controls use UTC calendar fields for parsing and output. In full ISO mode, the UTC date of an input timestamp determines the selected day. Month granularity normalizes to the first of the month, and year granularity to January 1. Range outputs represent inclusive whole UTC days. Partial ranges emit `null` unless `allowPartialRange` is enabled (default: false). With relative mode enabled, `onRelativeChange` emits the preset key and `onChange` emits its resolved range in the selected `fullIso` format; clearing or switching modes resets both to `null`.
 
-The package ships RuleSync source rules in `.rulesync/` and `rulesync.jsonc`. They document the public component API, standard aliases, form contracts, accessibility expectations, and styling conventions for AI coding tools. Generated tool files are deliberately excluded from the published npm package.
+`DateTimePicker` and `TimePicker` display and edit in `timeZone`, falling back to `UIConfig.dateInput.timeZone` (default: `"clientLocal"`, the browser's zone). Changing the zone changes displayed clock fields, while emitted timestamps remain UTC. For example, `2025-07-04T08:30:00.000Z` displays as 10:30 in `Europe/Ljubljana`; editing it to 11:30 emits `2025-07-04T09:30:00.000Z`. Display locale and `format` do not change the value format.
 
-To generate the UI rules into a consuming project's repository root, install [`rulesync`](https://github.com/dyoshikawa/rulesync) (`^8.15.0`) in that project, then run the executable bundled with `@povio/ui`:
+`TimePicker` uses `date` as its calendar anchor: it parses that string as a JavaScript `Date` instant, converts it into the effective zone, then replaces the clock fields. Use an explicit offset or `Z` to avoid ambiguous local timestamps. For example, `date="2025-03-04T00:00:00.000Z"` falls on March 3 in `America/Los_Angeles`; entering 10:30 emits `2025-03-03T18:30:00.000Z`. Without `date` (or with `null`), edits use today's date in the effective zone, even if the supplied `value` has another date. Once the editable input is mounted, changing `date` re-emits the current clock time on the new anchor. `isTimeOptional` on `DateTimePicker` completes a date with midnight in the effective zone when time is omitted.
 
-```bash
-bunx --package @povio/ui povio-ui-rules
+```tsx
+import { DatePicker } from "@povio/ui/date-picker";
+import { DateTimePicker } from "@povio/ui/date-time-picker";
+import { TimePicker } from "@povio/ui/time-picker";
+
+<DatePicker
+  label="Birthday"
+  fullIso={false}
+  defaultValue="2025-03-04"
+/>;
+<DateTimePicker
+  label="Meeting"
+  timeZone="Europe/Ljubljana"
+  defaultValue="2025-07-04T08:30:00.000Z"
+/>;
+<TimePicker
+  label="Departure"
+  timeZone="America/Los_Angeles"
+  date="2025-03-04T12:00:00.000Z"
+/>;
 ```
 
-This generates the relevant Cursor, Claude Code, and Codex CLI files in the consuming repository. Add generated files to that repository's `.gitignore` unless they are intentionally versioned. Re-run the command after upgrading `@povio/ui`; verify without writing files by adding `--check` (for example, `bunx --package @povio/ui povio-ui-rules --check`).
+## Table selection
+
+Table selection is internally managed by default. Supply `defaultSelectedRows` alone for an initial selection, or `onRowSelectionChange` alone to observe changes. Defaults are read only when mounted. When both props are supplied, selection is controlled: pass the current state through the legacy `defaultSelectedRows` prop and its React state setter through `onRowSelectionChange`. That callback receives TanStack selection values or updater functions. Use stable `getRowId` values for selection keys.
+
+## Pagination
 
-Within this monorepo, the equivalent package-local commands are `bun run --filter @povio/ui rules:gen` and `bun run --filter @povio/ui rules:check`.
+`usePagination` from `@povio/ui/tanstack/table` returns zero-based table state, defaulting to `{ pageIndex: 0, pageSize: 20 }`. URL page numbers remain one-based: `?page=2` becomes `pageIndex: 1`, and the first page omits the `page` parameter. Explicit default state overrides URL initialization; URL values are otherwise read when mounted. PaginatedTable accepts that state directly. Standalone Pagination uses one-based `page`, so convert with `pageIndex + 1` and `page - 1` at its boundary. See the [pagination migration steps](MIGRATION.md#11-check-pagination-boundaries) for row slicing, URL behavior, and page-size resets.
+
+## Built-package tests
+
+From `packages/ui`, run `bun run test:package` to build the publishable package and run its Chromium regressions. The tests resolve public imports through `dist/package.json`, covering both date pickers with empty and populated values in static and editable modes, including locale switches without remounting.
+
+## Versioning
+
+`^2.1` still corresponds to Atlas 2.1. All versions after that currently target Atlas 2.2 and follow semantic versioning — breaking changes bump the major version.
 
 ## Publishing
 
@@ -146,6 +302,14 @@ We also use a custom tailwind plugin to shorten some selectors inside the @povio
 @plugin "@povio/ui/tw-ui-plugin";
 ```
 
+### Palette roles
+
+Use the template's semantic palette for custom layouts. `surface-default-background` is the page surface, `surface-default-card` is the card/panel/popover surface, and `surface-default-sunken` is for recessed areas and filled inputs. Pair them with `text-content-primary`, `text-content-secondary`, or `text-content-muted` according to emphasis. The `content-inverted-*` roles are for inverted surfaces, while `fixed-black` and `fixed-white` retain the same literal color in both modes.
+
+Use the theme's radius tokens for custom cards and layouts, such as `rounded-global-rounding-xs` (0.25rem), `rounded-global-rounding-s` (0.375rem), or `rounded-global-rounding-m` (0.5rem). The template resets Tailwind's default radii; bare `rounded`, `rounded-md`, and `rounded-lg` are not defined. Existing theme tokens such as `rounded-m` and component-specific rounding roles remain available.
+
+Status treatments have explicit pairs: `bg-status-success-background text-status-success-foreground` for a contained treatment, or `bg-status-success-subtle-background text-status-success-subtle-foreground` for a subtle treatment. Equivalent roles exist for `warning` and `destructive`. Use `text-status-success-accent` or `border-status-success-accent` for standalone status content or boundaries. Destructive subtle colors preserve their existing distinct values; they are not a reversal of the contained pair. Action components continue using `interactive-*` colors. See the [palette migration mapping](MIGRATION.md#14-migrate-palette-roles) for exact replacements.
+
 ### State color utilities
 
 Import the color utilities in your application's Tailwind stylesheet. This import is required because `@povio/ui` components use these utilities:
@@ -184,7 +348,7 @@ import { IconSlot } from "@povio/ui/icon-slot";
 />;
 ```
 
-`IconSlot` is also exported from `@povio/ui`, `@povio/ui/rhf`, `@povio/ui/tanstack`, and `@povio/ui/icons`. `className` styles the outer slot; `iconClassName` styles the SVG. The slot controls SVG dimensions, including supplied SVGs with their own size classes. Use the inherited CSS variable `--icons-scale` to change the default ratio throughout a theme, or `scale` to override one slot. A 20px token at `0.8` produces a 16px SVG; a 24px token produces a 19.2px SVG. Stroke width continues to follow the icon's own configuration.
+`IconSlot` is also exported from `@povio/ui`, `@povio/ui/tanstack`, and `@povio/ui/icons`. `className` styles the outer slot; `iconClassName` styles the SVG. The slot controls SVG dimensions, including supplied SVGs with their own size classes. Use the inherited CSS variable `--icons-scale` to change the default ratio throughout a theme, or `scale` to override one slot. A 20px token at `0.8` produces a 16px SVG; a 24px token produces a 19.2px SVG. Stroke width continues to follow the icon's own configuration.
 
 Override the shared recipe through `UIOverrides` at `iconSlot.cva`. Component-specific icon recipes, such as `button.iconSize`, now style the outer slot. An explicitly configured slot passed to a button or input keeps its configuration without nesting another slot.
 
@@ -268,3 +432,65 @@ We're using a helper class for flex, so make sure to add this into your base css
   flex: 1 0 0;
 }
 ```
+
+## App canvas page (`/_canvas`)
+
+The separate `@povio/ui-configurator` package includes a ready-made page for inspecting all your TanStack Router pages. Install it as a development dependency alongside a compatible `@povio/ui` release, and retain your application's existing `@tanstack/react-router` dependency (an optional peer for this integration).
+
+For file-based routing, create `src/routes/[_]canvas.tsx` (or use your configured routes directory). The brackets escape TanStack's pathless-layout underscore convention:
+
+```tsx
+import "@povio/ui-configurator/app-canvas/styles";
+import { appCanvasRouteOptions } from "@povio/ui-configurator/app-canvas/tanstack";
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/_canvas")(appCanvasRouteOptions({ enabled: import.meta.env.DEV }));
+```
+
+Mount `AppCanvasBridge` once beneath the existing router and `UIConfigurationProvider`, alongside the root `Outlet`. The provider must be shared by the canvas route and the normal application pages; keep its existing theme defaults and persistence. If the app does not yet have this provider, add one using `parseThemeCss` on its theme source.
+
+```tsx
+import { isAppCanvasFrame } from "@povio/ui-configurator/app-canvas";
+import { AppCanvasBridge, useIsAppCanvasPage } from "@povio/ui-configurator/app-canvas/tanstack";
+
+// Inside the app's root component, under its UIConfigurationProvider:
+const canvasPage = useIsAppCanvasPage();
+return (
+  <>
+    <AppCanvasBridge />
+    <Outlet />
+    {!canvasPage && !isAppCanvasFrame() && <ExistingConfigurationLauncher />}
+  </>
+);
+```
+
+`ExistingConfigurationLauncher` represents your existing launcher/editor, if any. Do not render a second `UIConfigurationModal` on `/_canvas`: the supplied page includes its own draggable editor. Keep app-specific debug overlays out of canvas frames too.
+
+For code-based routing, add the package route to the existing root's children **before** creating the router:
+
+```tsx
+import "@povio/ui-configurator/app-canvas/styles";
+import { createAppCanvasRoute } from "@povio/ui-configurator/app-canvas/tanstack";
+const canvasRoute = createAppCanvasRoute({
+  getParentRoute: () => rootRoute,
+  enabled: import.meta.env.DEV,
+  canvas: { examples: { "/projects/$projectId": { params: { projectId: "example-id" } } } },
+});
+const routeTree = rootRoute.addChildren([homeRoute, projectsRoute, canvasRoute]);
+```
+
+Then open `/_canvas` directly. `enabled` accepts a boolean or a synchronous predicate; false produces a not-found route. Apply your existing access policy if enabling it outside development. Normal page authentication and loaders still run inside the frames. The canvas excludes its own pathname, and dynamic pages without example parameters remain explicitly unresolved. The lower-level `AppCanvasPage` and `AppCanvas` components remain available from `@povio/ui-configurator/app-canvas` for custom integrations.
+
+### Canvas workspaces
+
+The canvas supports named workspaces, enabled pages per workspace, and independent positions per breakpoint. The selected page's HTML layers expand directly beneath its row in the sidebar.
+
+The existing `uiConfigurator` Vite plugin also saves canvas settings to `povio.canvas.json` in the app root. Configure an alternate file with `uiConfigurator({ canvasFile: "povio.canvas.json" })`, or disable this with `canvasFile: false`. No Git commands run: review and commit this file through the normal repository workflow. Conflicting writes from different sessions are rejected instead of silently overwriting settings. Without this development-server connection, settings stay in browser storage; export/import remains available.
+
+### Fontsource font families
+
+In Configure UI, open Typography → Font families → Browse Fontsource. Search or filter the catalog, select a family to preview it, then choose Heading, Body, or Add to available fonts and click **Add font to app**. In development, this installs the verified Fontsource package with the application's existing package manager, updates its package.json and lockfile, and adds CSS imports. Variable families with a weight axis are preferred; static families load their supported weights and styles. Existing compatible packages and imports are reused.
+
+The selected role changes the live preview. **Save changes** writes it to the app's theme CSS. Adding a font makes its assets available; role assignments are saved explicitly with the theme. Package installation scripts are disabled, and no Git commit or push is performed. Catalog browsing and temporary CDN previews also work without the development installer.
+
+The Vite plugin uses `src/styles/globals.css` by default. For another CSS entrypoint, configure `uiConfigurator({ fontCssFile: "src/app.css" })`; it must exist inside the application's Vite root. Set `fontCssFile: false` to disable font installation. Restart Vite after adding or changing the plugin configuration.

package/dist/{Accordion-BzwO4_ml.js → Accordion-DQRdeDs1.js}

@@ -2,11 +2,11 @@ import { t as ChevronDown } from "./chevron-down-B4Pr8bD3.js";
 import { t as clsx } from "./clsx-CnD0nOiA.js";
 import { t as UIOverrides } from "./uiOverrides.context-BTCH9y5a.js";
 import { t as IconSlot } from "./IconSlot-DSK7qNxc.js";
-import { n as $7230ffa83bc0c2cf$export$29f1550f4b0d4415, o as $7230ffa83bc0c2cf$export$c62b8e45d58ddad9, r as $7230ffa83bc0c2cf$export$4d86445c2cf5e3, s as $7230ffa83bc0c2cf$export$df3a06d6289f983e, t as $7230ffa83bc0c2cf$export$2881499e37b75b9a } from "./utils-Czcqspm7.js";
-import { n as $7705c033048f6da7$export$353f5b6fc5456de1, t as $7705c033048f6da7$export$24d547caef80ccd1 } from "./Button-D6KlWSFL.js";
-import { t as $2ec61d1d4f780267$export$a8a3e93435678ff9 } from "./Heading-nI1_VOaE.js";
+import { n as $7230ffa83bc0c2cf$export$29f1550f4b0d4415, o as $7230ffa83bc0c2cf$export$c62b8e45d58ddad9, r as $7230ffa83bc0c2cf$export$4d86445c2cf5e3, s as $7230ffa83bc0c2cf$export$df3a06d6289f983e, t as $7230ffa83bc0c2cf$export$2881499e37b75b9a } from "./utils-BkLF-JA3.js";
+import { n as $7705c033048f6da7$export$353f5b6fc5456de1, t as $7705c033048f6da7$export$24d547caef80ccd1 } from "./Button-C1YB5dOw.js";
+import { t as $2ec61d1d4f780267$export$a8a3e93435678ff9 } from "./Heading-D4XFYv__.js";
 import { t as Typography } from "./Typography-LU4z2pR1.js";
-import { a as accordionHeadingTitleDefinition, c as accordionPanelContentDefinition, i as accordionHeadingSubtitleDefinition, l as accordionPanelDefinition, n as accordionDefinition, o as accordionIconDefinition, r as accordionHeadingDefinition, s as accordionItemDefinition, t as accordionChevronDefinition, u as accordionTriggerDefinition } from "./accordion.cva-CL1bVscW.js";
+import { a as accordionHeadingTitleDefinition, c as accordionPanelContentDefinition, i as accordionHeadingSubtitleDefinition, l as accordionPanelDefinition, n as accordionDefinition, o as accordionIconDefinition, r as accordionHeadingDefinition, s as accordionItemDefinition, t as accordionChevronDefinition, u as accordionTriggerDefinition } from "./accordion.cva-CeBWV9EO.js";
 import $ahdqC$react, { createContext, forwardRef, useContext } from "react";
 import { c } from "react/compiler-runtime";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
@@ -18,7 +18,7 @@ import { useId as useId$1 } from "react-aria/useId";
 import { useDisclosure } from "react-aria/useDisclosure";
 import { useDisclosureGroupState } from "react-stately/useDisclosureGroupState";
 import { useDisclosureState } from "react-stately/useDisclosureState";
-//#region ../../node_modules/.bun/react-aria-components@1.21.1+67f6792bdf102c28/node_modules/react-aria-components/dist/private/Disclosure.mjs
+//#region ../../node_modules/.bun/react-aria-components@1.22.1+67f6792bdf102c28/node_modules/react-aria-components/dist/private/Disclosure.mjs
 const $a3e16eab0ea4036c$export$1d40e3e0cc4d5de = /*#__PURE__*/ createContext(null);
 const $a3e16eab0ea4036c$export$944aceb4f8c89f10 = /*#__PURE__*/ forwardRef(function DisclosureGroup(props, ref) {
 	let state = useDisclosureGroupState(props);

package/dist/{Alert-DfiJbKH0.d.ts → Alert-Cee_nKWj.d.ts}

@@ -1,12 +1,12 @@
-import { t as StyleMergeUtils } from "./style-merge.util-zLimKwt6.js";
-import { t as UIOverrides } from "./uiOverrides.context-DEp139He.js";
+import { n as StyleMergeUtils, t as UIOverrides } from "./uiOverrides.context-Dmev7iRS.js";
+import "./style-definitions-_RXJdSk-.js";
 import { FC, ReactNode, SVGProps } from "react";
 //#region src/components/status/Alert/alert.cva.d.ts
 declare const alertDefinition: {
   base: string[];
   config: StyleMergeUtils.Config<{
     readonly variant: {
-      readonly outlined: "border bg-surface-default-card text-surface-default-card-foreground";
+      readonly outlined: "border bg-surface-default-card text-content-primary";
       readonly contained: "";
     };
     readonly color: {

package/dist/{AlertDialog-OWTbR4km.d.ts → AlertDialog-uNDUIyng.d.ts}

@@ -1,6 +1,6 @@
-import { n as ButtonVariantProps } from "./button.cva-C7kEhgoA.js";
-import { n as DialogProps } from "./Dialog-CW93T9X1.js";
-import { r as TypographyPropsCva } from "./Typography-XljT9s02.js";
+import { n as ButtonVariantProps } from "./button.cva-CBckM91c.js";
+import { n as DialogProps } from "./Dialog-V-2cgGk1.js";
+import { r as TypographyPropsCva } from "./Typography-D2FfZr7a.js";
 //#region src/components/overlays/AlertDialog/AlertDialog.d.ts
 interface AlertDialogAction {
   label: string;

package/dist/Autocomplete-CWU9Ev3J.js

@@ -0,0 +1,142 @@
+import { t as UIConfig } from "./uiConfig.context-CT9EVqC5.js";
+import { t as clsx } from "./clsx-CnD0nOiA.js";
+import { t as UIOverrides } from "./uiOverrides.context-BTCH9y5a.js";
+import { l as $542a13ca2fa5b484$export$5b6b19405a83ff9d } from "./Dialog-lFYX-7Ax.js";
+import { t as $dbdc5e6e7ce01b4b$export$72b9695b8216309a } from "./ComboBox-DFlz6HJ8.js";
+import { n as $41fb335299a4a39e$export$f5b8910cec6cf069 } from "./Input-BG0Xjw5X.js";
+import { i as $928221da08ecbc62$export$a11e76429ed99b4, t as $928221da08ecbc62$export$41f133550aa26f48 } from "./ListBox-CoUk0kkt.js";
+import { r as $a8ea2faf2ebe4d2f$re_export$mergeRefs } from "./import-D_3dPATF.js";
+import { t as useFieldAccessibility } from "./useFieldAccessibility-eZIMECmG.js";
+import { t as FormField } from "./FormField-D7KKJ6kG.js";
+import { t as inputBaseDefinition } from "./input.cva-w7ZEVQAM.js";
+import { t as TooltipWrapper } from "./TooltipWrapper-D7HUZLsP.js";
+import { t as popoverDefinition } from "./popover.cva-Bhud1wnp.js";
+import { t as selectListBoxItemDefinition } from "./selectItem.cva-BWfEkNs_.js";
+import { t as InputContent } from "./InputContent-KhD4_YvO.js";
+import { memo, useId, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/components/inputs/Selection/Autocomplete/Autocomplete.tsx
+function AutocompleteInner({ items, ref, value, defaultValue = "", onChange, onBlur, isClientSearchDisabled, inputClassName, label, error: errorProp, errorMessage, helperText, className, tooltipText, isRequired: isRequiredProp, required, rightContent, headerClassName, errorClassName, isHeaderHidden, isDisabled: isDisabledProp, disabled, isReadOnly, isInvalid, validationBehavior, validate, isDirty, as: asProp, layout: layoutProp, hideLabel: hideLabelProp, variant: variantProp, size: sizeProp, isClearable: isClearableProp, isClearableIfDisabled, unit, isLoading, action, leadingIcon, trailingIcon, placeholder, ...rest }) {
+	const ui = UIConfig.useConfig();
+	const isDisabled = isDisabledProp ?? disabled;
+	const isRequired = isRequiredProp ?? required;
+	const error = errorMessage ?? errorProp;
+	const generatedId = useId();
+	const inputId = rest.id ?? generatedId;
+	const inputBaseCva = UIOverrides.useCva("input.baseCva", inputBaseDefinition);
+	const popoverCva = UIOverrides.useCva("popover.cva", popoverDefinition);
+	const itemCva = UIOverrides.useCva("select.listBoxItemCva", selectListBoxItemDefinition);
+	const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
+	const inputValue = value ?? uncontrolledValue;
+	const inputRef = useRef(null);
+	const as = layoutProp ?? asProp ?? ui.input.as;
+	const hideLabel = hideLabelProp ?? ui.input.hideLabel;
+	const variant = variantProp ?? ui.input.variant;
+	const size = sizeProp ?? ui.input.size;
+	const isClearable = isClearableProp ?? ui.input.isClearable;
+	const { describedBy, errorMessageId, helperTextId } = useFieldAccessibility({
+		describedBy: rest["aria-describedby"],
+		error,
+		helperText
+	});
+	const changeText = (text) => {
+		if (isReadOnly || isDisabled) return;
+		if (value === void 0) setUncontrolledValue(text);
+		onChange?.(text);
+	};
+	const fieldProps = {
+		label,
+		error,
+		helperText,
+		tooltipText,
+		isRequired,
+		rightContent,
+		headerClassName,
+		errorClassName,
+		isDisabled,
+		hideLabel,
+		errorMessageId,
+		helperTextId,
+		labelProps: { htmlFor: inputId },
+		isHeaderHidden: isHeaderHidden || as === "inline" || as === "filter" || as === "floating"
+	};
+	return /* @__PURE__ */ jsxs($dbdc5e6e7ce01b4b$export$72b9695b8216309a, {
+		allowsCustomValue: true,
+		defaultItems: items,
+		...isClientSearchDisabled ? { items } : {},
+		inputValue,
+		onInputChange: changeText,
+		isDisabled,
+		isReadOnly,
+		isRequired,
+		isInvalid: !!error || isInvalid,
+		validationBehavior,
+		validate: validate ? ({ inputValue }) => validate(inputValue) : void 0,
+		"aria-label": rest["aria-label"] ?? label,
+		className: clsx("group w-full", className),
+		children: [/* @__PURE__ */ jsx(TooltipWrapper, {
+			as,
+			error,
+			children: /* @__PURE__ */ jsx(FormField, {
+				...fieldProps,
+				as,
+				children: /* @__PURE__ */ jsx("div", {
+					className: clsx("relative flex cursor-text has-disabled:cursor-default", inputBaseCva({
+						variant,
+						as
+					}), inputClassName),
+					"data-is-empty": !inputValue || void 0,
+					"data-is-disabled": isDisabled || void 0,
+					"data-is-required": isRequired || void 0,
+					children: /* @__PURE__ */ jsx(InputContent, {
+						unit,
+						isLoading,
+						isDisabled,
+						action,
+						leadingIcon,
+						trailingIcon,
+						isClearable: isClearable && !isReadOnly,
+						isClearableIfDisabled,
+						value: inputValue,
+						onChange: changeText,
+						headerProps: {
+							...fieldProps,
+							isHeaderHidden: hideLabel || isHeaderHidden
+						},
+						as,
+						size,
+						children: /* @__PURE__ */ jsx($41fb335299a4a39e$export$f5b8910cec6cf069, {
+							...rest,
+							id: inputId,
+							ref: $a8ea2faf2ebe4d2f$re_export$mergeRefs(ref, inputRef),
+							onBlur,
+							"aria-describedby": describedBy,
+							"aria-errormessage": errorMessageId,
+							placeholder: as === "floating" ? "\xA0" : placeholder,
+							"data-is-filled": !!inputValue || void 0,
+							"data-is-dirty": isDirty || void 0,
+							className: "min-w-0 w-full bg-transparent outline-none"
+						})
+					})
+				})
+			})
+		}), /* @__PURE__ */ jsx($542a13ca2fa5b484$export$5b6b19405a83ff9d, {
+			className: popoverCva({}),
+			style: { width: "var(--trigger-width)" },
+			children: /* @__PURE__ */ jsx($928221da08ecbc62$export$41f133550aa26f48, {
+				className: "max-h-72 overflow-auto outline-none",
+				children: (item) => /* @__PURE__ */ jsx($928221da08ecbc62$export$a11e76429ed99b4, {
+					id: item.id,
+					textValue: item.label,
+					isDisabled: item.isDisabled,
+					className: itemCva({ isSingle: true }),
+					children: item.label
+				})
+			})
+		})]
+	});
+}
+const AutocompleteComponent = (props) => /* @__PURE__ */ jsx(AutocompleteInner, { ...props });
+const Autocomplete = memo(AutocompleteComponent);
+//#endregion
+export { AutocompleteInner as n, Autocomplete as t };

package/dist/Autocomplete-D_4gEL7D.d.ts

@@ -0,0 +1,23 @@
+import { i as InputProps$1 } from "./Input-BX3sZBEp.js";
+import { InputProps, Key } from "react-aria-components";
+//#region src/components/inputs/Selection/Autocomplete/Autocomplete.d.ts
+interface AutocompleteItem {
+  id: Key;
+  label: string;
+  isDisabled?: boolean;
+}
+/** Text entry with optional suggestions. Values are text, never suggestion IDs. */
+interface AutocompleteProps extends Omit<InputProps$1, "type" | "renderStaticInput" | "autoFocusOnMount" | "spellCheck" | "validationState"> {
+  field?: never;
+  items: AutocompleteItem[];
+  spellCheck?: InputProps["spellCheck"];
+  /** Disable local filtering when suggestions are already filtered by a server. */
+  isClientSearchDisabled?: boolean;
+}
+declare function AutocompleteInner({ items, ref, value, defaultValue, onChange, onBlur, isClientSearchDisabled, inputClassName, label, error: errorProp, errorMessage, helperText, className, tooltipText, isRequired: isRequiredProp, required, rightContent, headerClassName, errorClassName, isHeaderHidden, isDisabled: isDisabledProp, disabled, isReadOnly, isInvalid, validationBehavior, validate, isDirty, as: asProp, layout: layoutProp, hideLabel: hideLabelProp, variant: variantProp, size: sizeProp, isClearable: isClearableProp, isClearableIfDisabled, unit, isLoading, action, leadingIcon, trailingIcon, placeholder, ...rest }: AutocompleteProps): import("react").JSX.Element;
+declare const AutocompleteComponent: (props: AutocompleteProps & {
+  field?: never;
+}) => import("react").JSX.Element;
+declare const Autocomplete: import("react").MemoExoticComponent<typeof AutocompleteComponent>;
+//#endregion
+export { AutocompleteProps as a, AutocompleteItem as i, AutocompleteComponent as n, AutocompleteInner as r, Autocomplete as t };

package/dist/Autocomplete.bound-CqhZtdd8.d.ts

@@ -0,0 +1,9 @@
+import { a as AutocompleteProps$1 } from "./Autocomplete-D_4gEL7D.js";
+import { n as FieldValues, t as FormControlProps } from "./form.types-C8P4sznq.js";
+//#region src/components/inputs/Selection/Autocomplete/Autocomplete.bound.d.ts
+type ControlledAutocompleteProps<TFieldValues extends FieldValues> = FormControlProps<AutocompleteProps$1, TFieldValues>;
+type AutocompleteProps<TFieldValues extends FieldValues = FieldValues> = ControlledAutocompleteProps<TFieldValues>;
+declare function AutocompleteComponent<TFieldValues extends FieldValues>(props: ControlledAutocompleteProps<TFieldValues>): import("react").JSX.Element;
+declare const Autocomplete: typeof AutocompleteComponent;
+//#endregion
+export { AutocompleteProps as n, ControlledAutocompleteProps as r, Autocomplete as t };

package/dist/Autocomplete.bound-D0pgmsHB.js

@@ -0,0 +1,28 @@
+import { r as $a8ea2faf2ebe4d2f$re_export$mergeRefs } from "./import-D_3dPATF.js";
+import { t as FieldController } from "./form.binding-B-2id68q.js";
+import { n as AutocompleteInner } from "./Autocomplete-CWU9Ev3J.js";
+import { memo } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/components/inputs/Selection/Autocomplete/Autocomplete.bound.tsx
+function AutocompleteComponent(props) {
+	const { field, ref, ...innerProps } = props;
+	return /* @__PURE__ */ jsx(FieldController, {
+		control: field.form,
+		name: field.name,
+		onValueChange: field.onValueChange,
+		onBlur: field.onBlur,
+		render: ({ field, fieldState: { error, isDirty } }) => /* @__PURE__ */ jsx(AutocompleteInner, {
+			...innerProps,
+			ref: $a8ea2faf2ebe4d2f$re_export$mergeRefs(ref, field.ref),
+			value: field.value ?? "",
+			onChange: field.onChange,
+			onBlur: field.onBlur,
+			isDirty,
+			isDisabled: field.disabled || props.isDisabled,
+			error: props.error ?? error?.message
+		})
+	});
+}
+const Autocomplete = memo(AutocompleteComponent);
+//#endregion
+export { Autocomplete as t };