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

package/MIGRATION.md

@@ -0,0 +1,645 @@
+# Povio UI migration guide
+
+This guide covers the web UI cleanup, including the focused button cleanup: removal of React Hook Form integration, schema-driven rendering, query selectors, and the admin page builder; stricter input contracts; the form, accessibility, upload, date/time, table, and pagination fixes; and consolidation of redundant button wrappers.
+
+Migrate one form or page at a time. Preserve its API payloads, permissions, translations, URL state, and design. Choose controls from the meaning of each field, then verify their value types against the public declarations. A TypeScript error should be resolved by fixing the binding or data shape, rather than adding a cast or suppression.
+
+`Input` retains its name. Button component choices and palette role names are clarified below; existing designs, sizes, and color values are preserved. This migration does not require a design overhaul. React Native form integration is outside this web migration; the palette section also identifies the shared color names used by native apps.
+
+## 1. Find the affected code
+
+Start with application code, shared wrappers, examples, and code generators. Search for these usages:
+
+```sh
+rg -n '@povio/ui/rhf|formControl|QuerySelect|QueryAutocomplete|useQueryAutocomplete|dynamicInputs|dynamicColumns|ZodUtils|usePageBuilder|PageBuilder|builderConfigs' apps packages
+rg -n '@povio/ui/(tanstack/)?(inputs|query-select|query-autocomplete)|ui\.(querySelect|queryAutocomplete)' apps packages
+rg -n '\bfullIso\b|\bselectionMode\b|\bdefaultState\b' apps packages
+rg -n 'TextButton|InlineIconButton|@povio/ui/(text-button|inline-icon-button)|\biconOnly\b|\btoggle\b' apps packages
+rg -n 'text-text-|bg-elevation-fill-|interactive-contained-' apps packages
+```
+
+Also inspect imports of `Form`, `Inputs`, and `InputItem` from Povio UI, broad barrel imports used for standalone inputs, table cell callbacks that destructure `original`, and callbacks or defaults passed directly to bound inputs. The searches include valid usages: inspect the component before changing a prop. In particular, ToggleButton, BadgeButton, Breadcrumbs, and ToggleGroup retain their own selection or icon props; do not apply a global `iconOnly` or `toggle` removal. Keep React Native components unchanged.
+
+| Previous usage                                                   | Replacement                                                       |
+| ---------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `@povio/ui/rhf` and its component subpaths                       | `@povio/ui/tanstack/form` and `@povio/ui/tanstack/<component>`    |
+| `formControl={{ control, name }}`                                | `field={{ form, name }}`                                          |
+| Povio `Form`, `Inputs`, `InputItem`, `dynamicInputs`, `ZodUtils` | Explicit JSX fields and ordinary Zod validation                   |
+| `dynamicColumns`                                                 | Explicit typed column definitions                                 |
+| ID-valued or multi-selection `Autocomplete`                      | `Select`, with `isSearchable` when needed                         |
+| `QuerySelect`, `QueryAutocomplete`, `useQueryAutocomplete`       | `Select` plus `useAsyncList`, or explicit text suggestion loading |
+| Admin page-builder configuration and generated `builderConfigs`  | Domain pages, filters, fields, tables, and dialogs                |
+| `fullIso` on `DateTimePicker` or `TimePicker`                    | Remove the prop; keep full UTC timestamp values                   |
+| Web `TextButton` / `@povio/ui/text-button`                       | `Button variant="text" width="hug"`                               |
+| Web `InlineIconButton` / `@povio/ui/inline-icon-button`          | `IconButton variant="text" size="sm" width="hug" disableTooltip`  |
+| `Button iconOnly` / `Button toggle`                              | `IconButton` / `ToggleButton` with equivalent appearance          |
+| Table cell `({ original }) => original.name`                     | `({ row }) => row.original.name`                                  |
+
+Removed symbols and subpaths have no compatibility adapter. Update shared abstractions first so their consumers inherit the corrected contract.
+
+## 2. Replace RHF integration and choose the correct imports
+
+TanStack Form is the supported web form integration. Ordinary component subpaths are standalone; corresponding `tanstack` subpaths are bound to a form. The broad `@povio/ui` and `@povio/ui/tanstack` barrels expose bound input versions. Use explicit subpaths so the ownership of a value is visible at the import.
+
+| Purpose                                     | Import example                                                | Value ownership                                 |
+| ------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------- |
+| Controlled or uncontrolled standalone input | `@povio/ui/input`                                             | `value`/`onChange`, or a supported default prop |
+| Form-bound input                            | `@povio/ui/tanstack/input`                                    | Required `field={{ form, name }}`               |
+| Form hooks and types                        | `@povio/ui/tanstack/form`                                     | Raw form state and parsed submissions           |
+| ID selection                                | `@povio/ui/select` or `@povio/ui/tanstack/select`             | Single ID or array of IDs                       |
+| Free text with suggestions                  | `@povio/ui/autocomplete` or `@povio/ui/tanstack/autocomplete` | String                                          |
+| Tables                                      | `@povio/ui/tanstack/table`                                    | Explicit rows, columns, and table state         |
+
+Replace the RHF resolver with `zodSchema`. Replace the old control object with the entire Povio form object. A complete form now looks like this:
+
+```tsx
+import { z } from "zod";
+import { Button } from "@povio/ui/button";
+import { useForm } from "@povio/ui/tanstack/form";
+import { Input } from "@povio/ui/tanstack/input";
+import { Select } from "@povio/ui/tanstack/select";
+
+const profileSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+  roleId: z.string().nullable(),
+});
+
+export function ProfileForm({ onSave }: { onSave: (values: z.output<typeof profileSchema>) => Promise<void> }) {
+  const form = useForm({
+    zodSchema: profileSchema,
+    defaultValues: { name: "", roleId: null },
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit(onSave)}>
+      <Input
+        label="Name"
+        field={{ form, name: "name" }}
+      />
+      <Select
+        label="Role"
+        field={{ form, name: "roleId" }}
+        items={[{ id: "editor", label: "Editor" }]}
+      />
+      <Button type="submit">Save</Button>
+    </form>
+  );
+}
+```
+
+Use `form.handleSubmit(onValid, onInvalid)` as the submit handler. `onValid` receives parsed output; `onInvalid` receives errors and raw values. `onSubmitAsync` in the hook options is an asynchronous validator receiving `{ value }` in raw form shape, rather than the successful-submit callback.
+
+| RHF operation                                  | Povio TanStack operation                                         |
+| ---------------------------------------------- | ---------------------------------------------------------------- |
+| `watch("name")` or reactive value subscription | `useFormValue(form, values => values.name)`                      |
+| Reactive `formState` access                    | `useFormState(form, state => state.isDirty)` or another selector |
+| `setValue("name", value)`                      | `form.setFieldValue("name", value)`                              |
+| Replace values and establish defaults          | `form.reset(rawValues)`                                          |
+| Read current values outside rendering          | `form.state.values`                                              |
+
+RHF options and error APIs do not map by a simple rename. Reimplement their behavior with the supported form and field APIs. Keep RHF dependencies if other parts of the application still use them; remove them when no remaining consumer needs them. An application that retains RHF can adapt standalone controls itself.
+
+## 3. Give each value one owner
+
+Standalone controls reject `field`. Bound controls require it and reject top-level `value`, `onChange`, `onBlur`, `defaultValue`, `defaultSelected`, `defaultChecked`, `defaultState`, and `onValueCommit`. Boolean controls also reject competing `isSelected` values when bound. Initialize bound values through form defaults or reset them through the form.
+
+For example, replace a bound input with a top-level change side effect:
+
+```text
+Before: <Input field={{ form, name: "name" }} onChange={trackName} />
+After:  <Input field={{ form, name: "name", onValueChange: trackName }} />
+```
+
+`field.onValueChange` receives the control's native value after raw state updates. `field.onBlur` takes no arguments and runs after actual focus loss marks the field touched. Selection commits can validate or flush autosave without invoking that blur side effect. Programmatic setters and resets invoke neither callback. Move business effects that must run on programmatic changes into application logic explicitly.
+
+Use these value shapes when choosing a field schema and default:
+
+| Control                                              | Interaction value                                   | Empty value                |
+| ---------------------------------------------------- | --------------------------------------------------- | -------------------------- |
+| `Input`, `TextArea`, `PasswordInput`, `Autocomplete` | String                                              | `""`                       |
+| `NumberField`                                        | Number                                              | `null`                     |
+| `NumberRangeInput`                                   | `{ min: number \| null; max: number \| null }`      | `{ min: null, max: null }` |
+| `Checkbox`, `Switch`                                 | Boolean, controlled through standalone `isSelected` | `false`                    |
+| Single `Select`                                      | String or number ID                                 | `null`                     |
+| Multiple `Select`                                    | Array of IDs; `selectionMode="multiple"`            | `[]`                       |
+| Date/time controls                                   | String; see the format table below                  | `null`                     |
+| Single `FileInput` or bound `FileUpload`             | Native `File`                                       | `null`                     |
+| Multiple `FileInput` or bound `FileUpload`           | `File[]`                                            | `[]`                       |
+
+For other controls, use their public component types. Defaults are component-specific; do not add `defaultValue` to every standalone control. Checkbox and Switch use `defaultSelected` where an uncontrolled default is needed.
+
+NumberRangeInput uses `null` for each cleared endpoint, whether cleared with the keyboard or its clear button. Use nullable numbers in the range schema; keyboard clearing no longer propagates `NaN` into the form or standalone change callback.
+
+## 4. Replace schema-driven fields and columns
+
+Remove Povio `Form`, `Inputs`, `InputItem`, `dynamicInputs`, `dynamicColumns`, and `ZodUtils` usages. The `@povio/ui/tanstack/inputs` entry is gone. Keep Zod schemas for validation and transformation, and render each field explicitly as in the profile example.
+
+Choose widgets from domain meaning. A string may represent a name, password, selected ID, calendar date, or timestamp; its Zod primitive alone cannot determine the correct control. Preserve labels, options, permissions, conditional visibility, helper text, and custom layouts previously supplied by renderer configuration. Arrays of IDs should become multiple Select fields; arrays of domain objects need explicit editing UI.
+
+Define table columns directly using public types. For example:
+
+```tsx
+import { Table, type TableProps } from "@povio/ui/tanstack/table";
+
+type Rocket = { id: string; name: string };
+
+const columns: TableProps<Rocket>["columns"] = [
+  {
+    id: "name",
+    accessorKey: "name",
+    header: "Name",
+    cell: ({ row }) => row.original.name,
+  },
+];
+
+export function RocketsTable({ items }: { items: Rocket[] }) {
+  return (
+    <Table
+      items={items}
+      columns={columns}
+      getRowId={(rocket) => rocket.id}
+    />
+  );
+}
+```
+
+Use `row.original` for the domain row and `getValue()` for a cell's accessor value. Runtime aliases such as `original`, `data`, and `value` remain for compatibility, but do not rely on them in consumer code: they are not the portable public cell contract. Workspace type augmentations can hide this problem, so check examples against published declarations too.
+
+For row-selection cells, standalone Checkbox emits a boolean: use `isSelected={row.getIsSelected()}` with `onChange={(isSelected) => row.toggleSelected(isSelected)}`. Do not pass `row.getToggleSelectedHandler()` directly; that TanStack adapter expects a DOM event with `target.checked`. The select-all checkbox can use `onChange={table.toggleAllRowsSelected}` because that method accepts a boolean.
+
+Table selection defaults and change callbacks now work independently. `defaultSelectedRows` alone initializes internally managed selection once; later default changes do not reset it. `onRowSelectionChange` alone observes internal changes. Supplying both retains the existing controlled behavior: pass the current selection through the legacy `defaultSelectedRows` prop and update it through the callback, for example with a React state value and setter. The callback receives TanStack selection values or updater functions, not always a resolved object. Keep stable `getRowId` values so the selected keys identify the intended records.
+
+`useFilters(defaults, prefix, schema)` remains available with its existing positional API. Removing visual schema renderers does not require removing schemas used to parse filter data.
+
+## 5. Separate selected IDs from entered text
+
+Use `Select` when the submitted value identifies an option. Add `isSearchable` when users need to search those options. Typing a search does not replace the selected ID with the search text. Single selection emits an ID or `null`; multiple selection emits an ID array.
+
+Use `Autocomplete` when the submitted value is text. Suggestions help enter that text: choosing `{ id: "city-1", label: "Ljubljana" }` stores `"Ljubljana"`. Suggestion IDs identify list rows. Arbitrary text is allowed, and clearing emits `""`.
+
+```tsx
+import { Select } from "@povio/ui/select";
+import { Autocomplete } from "@povio/ui/autocomplete";
+
+const cities = [{ id: "city-1", label: "Ljubljana" }];
+
+export function CityFields({
+  cityId,
+  setCityId,
+  cityText,
+  setCityText,
+}: {
+  cityId: string | null;
+  setCityId: (value: string | null) => void;
+  cityText: string;
+  setCityText: (value: string) => void;
+}) {
+  return (
+    <>
+      <Select<string>
+        label="City record"
+        items={cities}
+        isSearchable
+        value={cityId}
+        onChange={setCityId}
+      />
+      <Autocomplete
+        label="City text"
+        items={cities}
+        value={cityText}
+        onChange={setCityText}
+      />
+    </>
+  );
+}
+```
+
+Move old ID-valued and multiple Autocomplete usages to Select. Preserve numeric IDs as numbers when the domain uses them. Do not convert IDs to labels in the request DTO merely to satisfy the Autocomplete type.
+
+## 6. Replace query selectors with explicit loaders
+
+`QuerySelect`, `QueryAutocomplete`, `useQueryAutocomplete`, their query-specific helper types, and the native and TanStack query-selector entries are removed. Remove obsolete `UIConfig.querySelect` and `UIConfig.queryAutocomplete` configuration. `AsyncSelect` is an example name, rather than a replacement public component.
+
+Create an independent `useAsyncList` in the component for each independently searchable Select. The application owns API calls, authentication, request mapping, response mapping, and errors. The loader receives `signal`, `filterText`, and `cursor`, and returns `{ items, cursor }`. Return `undefined` or `null` for the final cursor. Forward the abort signal to the request.
+
+This example accepts a typed application loader, so it can use the project's existing API client and response validation:
+
+```tsx
+import { Select, type SelectItem } from "@povio/ui/select";
+import { useAsyncList } from "@povio/ui/use-async-list";
+
+type UserPage = { items: SelectItem<string>[]; cursor?: string };
+type LoadUsers = (request: { search: string; cursor?: string; signal: AbortSignal }) => Promise<UserPage>;
+
+export function UserSelect({
+  value,
+  onChange,
+  initialSelection,
+  loadUsers,
+}: {
+  value: string | null;
+  onChange: (value: string | null) => void;
+  initialSelection?: SelectItem<string> | null;
+  loadUsers: LoadUsers;
+}) {
+  const list = useAsyncList<SelectItem<string>>({
+    getKey: (item) => item.id,
+    load: ({ signal, filterText, cursor }) => loadUsers({ signal, search: filterText ?? "", cursor }),
+  });
+
+  return (
+    <>
+      <Select<string>
+        label="User"
+        list={list}
+        isSearchable
+        value={value}
+        onChange={onChange}
+        initialSelection={initialSelection}
+      />
+      {list.error && (
+        <div role="alert">
+          Could not load users.{" "}
+          <button
+            type="button"
+            onClick={() => list.reload()}
+          >
+            Retry
+          </button>
+        </div>
+      )}
+    </>
+  );
+}
+```
+
+The hook loads on mount. `Select list={list}` forwards search and load-more interactions, owns loading flags, and disables local filtering of server results. Supply either `list` or `items`. With `list`, omit `isLoading`, `hasLoadMore`, `onLoadMore`, `isClientSearchDisabled`, and `ignoreInputValueFiltering`; these would compete with list state. A bound Select uses the same loader with `field` in place of `value` and `onChange`.
+
+React query hooks belong at component or custom-hook scope. Do not invoke them inside the asynchronous `load` callback. Call ordinary API functions or an explicitly obtained query client there.
+
+An existing selected ID may be absent from the first page. Supply `initialSelection` with its label, or explicitly resolve and merge selected records into the loaded options. Re-resolve when asynchronous form defaults or a reset change the selected IDs. Preserve those IDs if label loading fails and provide retry; a failed lookup must not silently clear a stored relationship. Carry forward cache and ACL behavior from the removed wrapper.
+
+For remotely loaded free-text suggestions, keep `Autocomplete items={list.items}`, forward text changes to both the text owner and `list.setFilterText(text)`, pass `isLoading={list.isLoading}`, and set `isClientSearchDisabled`. Autocomplete has no `list` prop. Render loading errors and retry separately.
+
+## 7. Preserve raw form types and parsed output
+
+`UIForm<Raw, Output>` and `useForm<Raw, Output>` distinguish editable values from submitted values. Remove the obsolete third generic argument. A schema is required when parsed output differs from input, and passing `zodSchema` can infer both types.
+
+```tsx
+import { z } from "zod";
+import { useForm } from "@povio/ui/tanstack/form";
+import { Input } from "@povio/ui/tanstack/input";
+
+const quantitySchema = z.object({
+  quantity: z.string().regex(/^\d+$/, "Enter a whole number").transform(Number),
+});
+
+export function QuantityForm({ onSave }: { onSave: (values: z.output<typeof quantitySchema>) => Promise<void> }) {
+  const form = useForm({ zodSchema: quantitySchema, defaultValues: { quantity: "1" } });
+  // Raw setters and resets receive strings; successful submission receives a number.
+  return (
+    <form onSubmit={form.handleSubmit(onSave)}>
+      <Input
+        label="Quantity"
+        field={{ form, name: "quantity" }}
+      />
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+Keep field names and bound values in the raw input shape. Use parsed output for API submission. Do not change the input component to a number-valued control just because a transform produces a number; either keep the raw string binding or intentionally change the schema's input contract.
+
+### Reset and autosave
+
+`defaultValues` establishes initial values. Changing that prop after mount does not replace current form values. Use `form.reset(rawValues)` for an intentional reset; it establishes the new baseline and clears dirty/touched state under the default reset behavior. Initial asynchronous defaults preserve edits made while loading and are ignored after a newer reset supersedes them.
+
+For forms that save and refresh server data, use `useFormAutosave` with `getResetValues`, `resetDeps`, and `onAutosave`. Include the server record or revision that changes after saving in `resetDeps`. Convert server output back to raw editable values in `getResetValues`.
+
+```tsx
+import { useFormAutosave, type AutosavePatch } from "@povio/ui/tanstack/form";
+import { Input } from "@povio/ui/tanstack/input";
+
+type Settings = { name: string };
+
+export function SettingsForm({
+  record,
+  onSave,
+}: {
+  record: Settings;
+  onSave: (patch: AutosavePatch<Settings>) => Promise<void>;
+}) {
+  const form = useFormAutosave<Settings>({
+    getResetValues: () => record,
+    resetDeps: [record],
+    onAutosave: onSave,
+    autosaveOn: "change",
+  });
+  return (
+    <Input
+      label="Name"
+      field={{ form, name: "name" }}
+    />
+  );
+}
+```
+
+The save callback must update or invalidate the source of `record` so refreshed server data reaches the hook. Use `useAutosave({ form, onSave, ... })` when you manage refresh/reset separately. Public `AutosavePatch`, `AutosaveHandler`, and hook prop types are exported from the form entry.
+
+Autosave schemas must preserve all raw field paths, including optional fields. Transforms can change a value's type at the same path; renaming or removing a path prevents reliable patch projection. Use an explicit submission/mapping strategy for those transformations instead.
+
+Clears and removals now remain in patches, including `null` and `undefined`. Arrays and dates are treated as whole values. Ensure the API serializer represents the intended deletion: JSON omits `undefined`, so a wire contract may require `null` or a separate deletion operation. Do not strip clears with truthiness checks or a generic “remove empty values” helper.
+
+An explicit reset cancels pending saves and rebases autosave. Disable/unmount cancels queued work. Refreshes after a save preserve edits made during the request; do not add a separate unconditional reset effect that overwrites them. A refresh timeout logs a warning rather than throwing; fix missing refresh dependencies or invalidation instead of treating the warning as a successful refresh.
+
+## 8. Migrate upload values without losing attachment IDs
+
+`multiple` is now a supported alias for `allowsMultiple` on FileInput and FileUpload. Either `multiple={true}` or `allowsMultiple={true}` enables multiple files; both true is also valid. Opposing flags are rejected. Single mode accepts nullable values; multiple mode uses `[]` for empty values.
+
+FileUpload applies single mode to drag-and-drop as well as browsing: after filtering accepted file types, only the first accepted dropped file is selected and uploaded. Extra accepted files are ignored before callbacks or transfers. Enable multiple mode explicitly when every accepted file should be processed.
+
+| Usage                   | Value/default contract                                                                    | Change callback                                                  |
+| ----------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Standalone `FileInput`  | `File \| null`, or `File[]` in multiple mode                                              | Native file(s)                                                   |
+| Bound `FileInput`       | Raw form field containing native file(s)                                                  | Optional `field.onValueChange` receives file(s)                  |
+| Bound `FileUpload`      | Raw form field containing `File \| null` or `File[]`                                      | Optional `field.onValueChange` receives file(s)                  |
+| Standalone `FileUpload` | `value`: `FileUploadState[] \| null` in single mode, `FileUploadState[]` in multiple mode | Native `File \| null` or `File[]`, rather than lifecycle records |
+
+Standalone FileUpload is not a symmetric `value`/`onChange` metadata editor. Its `value` describes displayed upload lifecycle state. `defaultValue` initializes native files; `defaultState` initializes metadata for existing uploads. A supplied `value`, including `null`, takes precedence over defaults. Bound uploads get defaults from their form and reject `defaultState`.
+
+Keep server attachment DTOs separate from browser files. `fileUpload(request, file, options)` returns a promise resolving to `{ id }`; `fileRemove({ id })` removes a server upload. Forward `options.abortController?.signal` and report progress through `options.onUploadProgress` in the application adapter. Capture returned IDs when constructing attachment payloads.
+
+The upload callback must complete the actual file transfer before returning `{ id }`. Requesting upload instructions only reserves the upload; it does not send the file bytes. Follow the returned method, URL, and form fields, and reject failed HTTP responses so the control displays an error instead of marking the file uploaded. Pass only the generated mutation's supported request arguments; send the native `File` to the storage endpoint, not as an extra argument to the instructions mutation.
+
+When migrating application adapters such as RocketMediaForm, send POST uploads as FormData with signed fields before the file, and PUT uploads as the raw file body. A resolved `fetch` does not imply HTTP success. Check transfer status and cancellation before publishing an attachment ID or preview, and forward upload progress when the transport supports it. The generated instructions mutation cannot cancel negotiation; check the supplied abort signal again after it resolves and before starting the transfer. The template's frontend adapter and current Storybook S3 guide demonstrate this flow.
+
+FileUpload catches thrown or rejected upload callbacks and displays their message through its accessible field error, with a localized fallback when no message is available. A supplied `error` prop takes precedence. Failed files are removed from the selection while successful uploads in the same batch remain. Cancellation and stale completions stay quiet; a new attempt or external reset/replacement clears the internal upload error. Applications can still supply their own validation or upload feedback through `error`.
+
+If a form field stores `{ id: string }`, use a standalone FileUpload with explicit application callbacks that update that attachment field. Do not bind it directly as if `{ id }` were a native File. Preserve existing attachment display metadata independently, and clear the attachment DTO when the user removes it.
+
+Reset/cancel/replacement now protects the component from stale upload completion and progress. Application callbacks that write attachment IDs should also respect cancellation and the currently edited record; component safeguards cannot undo an unrelated application mutation.
+
+## 9. Make date and time formats explicit
+
+Remove `fullIso` from both standalone and bound DateTimePicker and TimePicker. It was unsupported and had no effect. Keep it on DatePicker and DateRangePicker when choosing their output format.
+
+| Component                                 | Output format                                                               | Empty value |
+| ----------------------------------------- | --------------------------------------------------------------------------- | ----------- |
+| `DatePicker`, default `fullIso=true`      | UTC calendar date at `YYYY-MM-DDT00:00:00.000Z`                             | `null`      |
+| `DatePicker`, `fullIso=false`             | `YYYY-MM-DD`                                                                | `null`      |
+| `DateRangePicker`, default `fullIso=true` | `{ start, end }`: UTC midnight start and UTC `23:59:59.999Z` end, inclusive | `null`      |
+| `DateRangePicker`, `fullIso=false`        | `{ start, end }` containing `YYYY-MM-DD` endpoints                          | `null`      |
+| `DateTimePicker`                          | Full UTC ISO timestamp with milliseconds and `Z`                            | `null`      |
+| `TimePicker`                              | Full UTC ISO timestamp with milliseconds and `Z`, including its anchor date | `null`      |
+
+Date-only controls use UTC calendar fields to interpret timestamp inputs. Month granularity normalizes to the first of the month, and year granularity to January 1. Partial date ranges emit `null` unless `allowPartialRange` is enabled; with that option, a missing endpoint is `null`. Relative range mode emits a preset key through `onRelativeChange` and a resolved range through `onChange`. Clearing or switching modes resets both values.
+
+DateTimePicker and TimePicker display/edit in `timeZone`, falling back to `UIConfig.dateInput.timeZone`, whose default is `"clientLocal"`. Output remains UTC. Display `format` and locale do not change the wire value. DateTimePicker's `isTimeOptional` completes a date with midnight in the effective zone when time is omitted.
+
+TimePicker is not an `HH:mm` control. Its `date` anchor is parsed as a JavaScript Date instant and converted into the effective zone before replacing clock fields. Use a timestamp with an explicit offset or `Z`. Without an anchor, edits use today in that zone, even when the supplied value contains another date. Changing `date` after the editable input mounts re-emits the current clock time on the new anchor.
+
+For example, `date="2025-03-04T00:00:00.000Z"` is March 3 in `America/Los_Angeles`. Entering 10:30 emits `2025-03-03T18:30:00.000Z`. Choose the anchor to represent the intended local day, and check daylight-saving transitions in the application's supported zones.
+
+The removal of unsupported props does not require converting stored timestamps. If an API expects only clock text, map the full timestamp explicitly using the intended zone. If an API expects a calendar date, use DatePicker's date-only mode or an explicit domain conversion. Match request validation to the actual returned format. See [Date and time values](README.md#date-and-time-values) for examples.
+
+## 10. Replace the admin page builder with domain components
+
+Remove the shared page builder, `usePageBuilder`, dynamic page definitions, domain `*PageConfig(s)` wrappers, and generated `builderConfigs` outputs. Remove only the corresponding code-generation step; keep generated API clients, request/response schemas, and query hooks.
+
+For each page, carry the old configuration's behavior into explicit components:
+
+1. Render domain filters with standalone inputs, Select, and date controls.
+2. Define typed columns, action cells, and stable row IDs.
+3. Call existing domain query/mutation APIs from the page or its hooks.
+4. Render domain create/edit forms and view dialogs explicitly.
+5. Retain permission checks, translations, tabs, selected-record state, and query invalidation.
+
+Keep small shared presentation components such as `QueryFeedback`, `EmptyResults`, and the `normalizeFilter` helper. Preserve the distinction between an empty dataset and a filtered search with no matches. When a refresh fails, keep cached rows visible and show the error with retry.
+
+Keep filters, sorting, page size, and pagination in the established URL state. Use the existing routing serialization helpers; avoid adding another JSON encoding layer around arrays, objects, or quoted strings. Routing serialization was corrected to avoid double encoding.
+
+The explicit examples in this repository include `apps/admin/src/components/rockets/RocketsPage.tsx`, its `filters/` and `tables/` siblings, and frontend `apps/fe/src/components/rockets/RocketFilters.tsx` and `RocketsTable.tsx`. Existing application code can contain workspace-only table aliases; use the public `row.original` pattern above when creating portable examples.
+
+## 11. Check pagination boundaries
+
+TanStack table state and every `usePagination` input/output use zero-based `pageIndex`: the first page is `0`. The hook now defaults to `{ pageIndex: 0, pageSize: 20 }`. The standalone Pagination component's `page` is one-based. PaginatedTable converts between them and resets the index to zero when page size changes.
+
+Page sizes must be positive safe integers. The built-in page-size editor constrains numeric edits and only calls `onPageSizeChange` with a valid size; clearing it no longer emits `0` or resets pagination. Keep the same validation on application-owned page-size inputs, programmatic state, and API parameters.
+
+The URL remains one-based: `?page=2` initializes `pageIndex: 1`. The hook writes index `1` back as `page=2`, omits `page` for the first page, and omits `size` for the default size of `20`. Other query parameters are preserved. Invalid page or size values fall back to the default for that field; URL values must be positive safe whole integers.
+
+Change explicit first-page defaults from `usePagination({ pageIndex: 1, ... })` to `pageIndex: 0`. An explicitly supplied default state still takes precedence over URL initialization. Without it, the hook reads the URL when mounted; it does not rehydrate its state on later URL changes.
+
+Remove compensating offsets that were added around the old behavior. Apply a conversion exactly once at each boundary:
+
+```text
+Table state pageIndex 0 → visible page 1
+Table state pageIndex 1 → visible page 2
+One-based server API page = pageIndex + 1
+One-based pager selection → table pageIndex = page - 1
+URL page 2 ↔ table pageIndex 1
+```
+
+For local data, replace `(pageIndex - 1) * pageSize` with `pageIndex * pageSize`. Pass that slice to PaginatedTable; the component displays the rows you supply:
+
+```tsx
+import { PaginatedTable, type TableProps, usePagination } from "@povio/ui/tanstack/table";
+
+type Result = { id: string; name: string };
+const columns: TableProps<Result>["columns"] = [
+  { accessorKey: "name", header: "Name", cell: ({ row }) => row.original.name },
+];
+
+export function LocalResults({ rows }: { rows: Result[] }) {
+  const { pagination, setPagination } = usePagination();
+  const start = pagination.pageIndex * pagination.pageSize;
+  return (
+    <PaginatedTable
+      items={rows.slice(start, start + pagination.pageSize)}
+      columns={columns}
+      totalItems={rows.length}
+      pagination={pagination}
+      setPagination={setPagination}
+    />
+  );
+}
+```
+
+When connecting `usePagination` directly to a standalone Pagination, pass `page={pageIndex + 1}` and convert `onPageChange` back with `pageIndex: page - 1`. A jump-to-page input also shows one-based page numbers. For nonempty results, row ranges start at `pageIndex * pageSize + 1` and end at `Math.min((pageIndex + 1) * pageSize, totalItems)`. Set `pageIndex: 0` when changing page size manually; PaginatedTable already does this for its own pager.
+
+Check the server API's actual convention before converting its page number. PaginatedTable includes its pager; avoid adding a second one. InfiniteTable remains available for incremental loading; an application-owned API page/cursor is separate from `usePagination` state and retains the API's convention. Check first-page loading, navigation, page-size resets, and reloading a `?page=2` URL so offsets are applied exactly once.
+
+## 12. Preserve accessibility while replacing layouts
+
+Every field needs an accessible name. Keep visible `label` props or an appropriate supported `aria-label`/`aria-labelledby`. A placeholder does not replace a label. Hiding a visual label must retain the accessible name.
+
+Preserve helper text and visible validation errors, including filter and inline layouts. Use the component's error props so helper/error associations reach the input. Avoid recreating only a tooltip or a red border. Keep caller-provided `aria-describedby` associations when adding extra context.
+
+Give Dialog an explicit accessible name, preferably `aria-labelledby` pointing to a visible heading, or `aria-label`. AlertDialog associates its heading automatically and honors explicit names. Supply Popover's `sheetLabel` to name its overlay. Keep date/time labels and unique input IDs when rendering repeated fields.
+
+Check keyboard focus through static-to-editable input handoff, selection, clear actions, and overlay close. Disabled controls must remain unfocusable. An actual blur side effect must run once on focus loss, rather than on every selection commit. Avoid application focus effects that fight the component's focus restoration.
+
+## 13. Choose buttons by behavior
+
+The web `TextButton` and `InlineIconButton` components and their prop types (`TextButtonProps`, `InlineIconButtonProps`) are removed. Their `@povio/ui/text-button` and `@povio/ui/inline-icon-button` package entries and barrel exports are removed too. Replace their imports and usages, including shared wrappers, stories, and generated code. React Native buttons are unaffected.
+
+| Meaning                              | Component and import                          | Contract                                                                                     |
+| ------------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Action with visible text             | `Button` from `@povio/ui/button`              | `children` is the visible label; icons are optional                                          |
+| Action displayed only as an icon     | `IconButton` from `@povio/ui/icon-button`     | Required `icon` and accessible name, normally `label`                                        |
+| Persistent selected/unselected state | `ToggleButton` from `@povio/ui/toggle-button` | `isSelected`/`defaultSelected` and `onChange`; supports `iconOnly` for selected icon actions |
+| Primary action and separate menu     | `SplitButton` from `@povio/ui/split-button`   | Keep the existing action and menu props                                                      |
+
+`BadgeButton` remains available for interactive badge presentations and retains its existing `toggle`/selection contract. Do not migrate a status badge to an action button merely because the two share a shape. Noninteractive statuses should retain their existing status component.
+
+The cleanup changes component selection, while preserving design, colors, spacing, variants, and sizes. `Button`, `IconButton`, `ToggleButton`, and `SplitButton` keep `sm` (including alias `s`), `default`, and `none`. The default remains `default`; the removed InlineIconButton wrapper used `sm`, which must be explicit in its replacement. Keep custom icon dimensions, classes, inverted colors, link targets, event handlers, and refs.
+
+Use these replacements, preserving explicit sizes and widths:
+
+```text
+Before: <TextButton>Cancel</TextButton>
+After:  <Button variant="text" width="hug">Cancel</Button>
+
+Before: <TextButton width="fill" size="none">Read more</TextButton>
+After:  <Button variant="text" width="fill" size="none">Read more</Button>
+
+Before: <InlineIconButton icon={CloseIcon} label="Close" />
+After:  <IconButton variant="text" size="sm" width="hug" disableTooltip icon={CloseIcon} label="Close" />
+
+Before: <InlineIconButton size="none" icon={CloseIcon} label="Close" />
+After:  <IconButton variant="text" size="none" width="hug" disableTooltip icon={CloseIcon} label="Close" />
+
+Before: <Button iconOnly icon={CloseIcon}>Close</Button>
+After:  <IconButton icon={CloseIcon} label="Close" disableTooltip />
+
+Before: <Button toggle variant="contained" isSelected={enabled} onChange={setEnabled}>Enabled</Button>
+After:  <ToggleButton variant="contained" isSelected={enabled} onChange={setEnabled}>Enabled</ToggleButton>
+```
+
+`TextButton iconOnly` was a text-styled icon action with default button sizing. Replace it with `IconButton variant="text" width="hug" disableTooltip` and turn its children into `label`; retain its original size rather than adding the InlineIconButton `sm` default.
+
+`Button` rejects `iconOnly`, `toggle`, and selection props, including when their values are false. Remove `iconOnly={false}`/`toggle={false}` from ordinary actions. `Button` and `ButtonProps` no longer take an `IconOnly` generic argument. For a selected icon action, use `ToggleButton iconOnly` with an icon and preserve its accessible label and original appearance. Retain any original `variant`, `size`, or `width` when moving an existing Button to another behavior component. When the original `Button toggle` omitted its variant, preserve the effective configured Button variant explicitly: ToggleButton has historically defaulted to `outlined`, whereas the default Button configuration is `contained`.
+
+An IconButton needs an accessible name through `label`, `ariaLabel`, `aria-label`, or `aria-labelledby`. `label` is the usual choice and supplies the tooltip text. Put an old Button's hidden children into that name; do not discard them. For complex label markup, provide equivalent name text or use `aria-labelledby` to reference a label element. IconButton shows a tooltip by default; `disableTooltip` preserves the former InlineIconButton and `Button iconOnly` behavior, including existing outer tooltips and their placements/delays. An external `aria-labelledby` names the button but does not supply tooltip text, so supply `label` too when a tooltip is desired.
+
+If a shared wrapper spreads caller props, apply overridable defaults such as `size="sm"` before the spread. Apply the former InlineIconButton forced appearance (`variant="text"`, `width="hug"`, and `disableTooltip`) after the spread. Its old `disableTooltip={false}` never enabled a tooltip, so keep tooltip behavior explicit. The date-input configuration value `todayIconButtonComponent="inlineIconButton"` remains supported as an appearance preset; it does not refer to a package import and does not need renaming.
+
+Loading and icon props were not renamed. Keep the supported `loading`/`isLoading`, `icon`/`iconPosition`, `startIcon`/`endIcon`, and width aliases on components that expose them. Do not perform an unrelated prop rename, introduce a new shape API, or change theme tokens as part of this migration.
+
+## 14. Migrate palette roles
+
+Palette names now describe content emphasis, recessed surfaces, status treatments, and fixed colors. Rename definitions and usages together: CSS custom properties, Tailwind `--color-*` aliases, component classes, state utilities, inline variable references, presets, and saved CSS/override exports. The template's web and native consumers use the new names. Old public token names are not retained as aliases.
+
+Replace older example classes such as `text-text-default-1`, `text-text-default-2`, and `text-text-error-1` with `text-content-primary`, `text-content-secondary`, and `text-status-destructive-accent`. The old `bg-elevation-fill-*` and `interactive-contained-*` roles have no current aliases and generate no CSS. Choose card or sunken surfaces by purpose, and let custom option content inherit its parent's hover, focus, and selected text colors instead of hardcoding a foreground for every selection mode. The template resets Tailwind's default color palette; use the semantic theme roles rather than assuming classes such as `bg-gray-100` are available.
+
+These are naming changes. Keep the existing RGB/hex values, alpha values, light/dark mappings, state mixes, and contrast relationships. Do not replace a palette role with a fixed color merely because they look similar in one mode.
+
+### Content emphasis and recessed surfaces
+
+| Previous token                        | Canonical token              | Use                                       |
+| ------------------------------------- | ---------------------------- | ----------------------------------------- |
+| `surface-default-card-foreground`     | `content-primary`            | Main text and prominent icons             |
+| `surface-default-foreground`          | `content-secondary`          | Descriptions and supporting text          |
+| `surface-default-popover-foreground`  | `content-muted`              | Low-emphasis content and placeholders     |
+| `surface-inverted-card-foreground`    | `content-inverted-primary`   | Main content on an inverted surface       |
+| `surface-inverted-foreground`         | `content-inverted-secondary` | Supporting content on an inverted surface |
+| `surface-inverted-popover-foreground` | `content-inverted-muted`     | Muted content on an inverted surface      |
+| `surface-default-popover`             | `surface-default-sunken`     | Filled inputs and recessed content areas  |
+| `surface-inverted-popover`            | `surface-inverted-sunken`    | Recessed areas in an inverted treatment   |
+| `support-default`                     | `fixed-black`                | Invariant black in both modes             |
+| `support-inverted`                    | `fixed-white`                | Invariant white in both modes             |
+
+For example, `text-surface-default-card-foreground` becomes `text-content-primary`, and `bg-surface-default-popover` becomes `bg-surface-default-sunken`. A popover still uses the card surface: `bg-surface-default-card`. The former popover name described a recessed treatment rather than the Popover component's background.
+
+Raw web variables retain their value representation: `--surface-default-card-foreground-base` becomes `--content-primary-base`, and `--color-surface-default-card-foreground` becomes `--color-content-primary`. Native themes use the same canonical roles without the web `-base` suffix. The native generator accepts legacy Atlas export names and normalizes both declarations and `var()` references to the canonical names.
+
+### Status pairs and accents
+
+For each of `success`, `warning`, and `destructive`, choose a complete treatment:
+
+| Role                                      | Color token                  | Existing value                         |
+| ----------------------------------------- | ---------------------------- | -------------------------------------- |
+| Contained background                      | `status-*-background`        | Former `surface-*-base`                |
+| Content on contained background           | `status-*-foreground`        | Former `surface-*-inverted-base`       |
+| Subtle background                         | `status-*-subtle-background` | Existing subtle status treatment       |
+| Content on subtle background              | `status-*-subtle-foreground` | Existing subtle status treatment       |
+| Standalone status text, icons, or borders | `status-*-accent`            | Same value as the contained background |
+
+Before/after examples preserve the existing colors:
+
+```text
+Contained success:
+Before: bg-surface-success-base text-surface-success-inverted-base
+After:  bg-status-success-background text-status-success-foreground
+
+Subtle success:
+Before: bg-surface-success-inverted-base text-surface-success-base
+After:  bg-status-success-subtle-background text-status-success-subtle-foreground
+
+Standalone error text:
+Before: text-surface-destructive-base
+After:  text-status-destructive-accent
+
+Status border:
+Before: border-surface-warning-base
+After:  border-status-warning-accent
+```
+
+Success and warning subtle treatments reverse their existing contained pair. Destructive subtle treatments keep the existing `interactive-subtle-destructive-background` and `interactive-subtle-destructive-foreground` values. They do not reverse the contained destructive pair. In particular, old standalone error text maps to `status-destructive-accent`, not `status-destructive-subtle-foreground`; those colors differ in the light theme. Destructive action buttons retain their `interactive-*` roles.
+
+Use the element's purpose when replacing status tokens. A tooltip pointer matching a contained status surface uses `status-*-background`; an independent status icon uses `status-*-accent`. A text replacement cannot be inferred solely from a shared old variable name. Raw web variables also lose the old doubled suffix: `--surface-success-base-base` becomes `--status-success-background-base`, while `--surface-success-inverted-base-base` becomes `--status-success-foreground-base`.
+
+### Custom layouts and states
+
+The template resets Tailwind's radius namespace as well as its color palette. Use defined theme utilities for custom layouts: replace bare `rounded` with `rounded-global-rounding-xs` (0.25rem), `rounded-md` with `rounded-global-rounding-s` (0.375rem), and `rounded-lg` with `rounded-global-rounding-m` (0.5rem). These replacements retain the conventional intended dimensions without restoring Tailwind defaults or changing theme values. Keep existing supported radius tokens and arbitrary values. A Table `variant="rounded"` is a component variant, not a CSS utility, and does not need this replacement.
+
+```tsx
+export function AccountPanel() {
+  return (
+    <section className="rounded-m border border-border-default-subtle bg-surface-default-card p-4 text-content-primary">
+      <h2>Account</h2>
+      <p className="text-content-secondary">Manage your details.</p>
+      <div className="bg-surface-default-sunken p-2">
+        <span className="text-content-muted">Optional settings</span>
+      </div>
+      <p className="text-status-success-accent">Changes saved.</p>
+    </section>
+  );
+}
+```
+
+Keep the existing `surface-default-background`, `surface-default-card`, border, interactive action, focus ring, and overlay families. Semantic roles continue adapting to dark mode automatically. Use `fixed-white` or `fixed-black` only for content that must remain that literal color; do not change existing mode-aware content to a fixed color during the rename.
+
+State utilities keep their syntax and mix values. For example, `hover:bg-state-surface-default-popover/hover` becomes `hover:bg-state-surface-default-sunken/hover`. The state remains `/hover`; selected action recipes retain `/toggled`, `/toggled-hovered`, and `/toggled-disabled`. These mixes do not guarantee a visible change against every base surface, so this migration does not introduce a new hover treatment for white cards.
+
+Migrate app-owned exported themes and saved override strings before loading them. Search for old names after migration, allowing references in this guide, historical changelogs, and legacy generator input fixtures. Verify the rendered colors in both modes, including status accents versus subtle foregrounds. If a web Figma export still uses the old vocabulary, apply this mapping before replacing the template theme; the native generator already performs that normalization.
+
+## 15. Validate each migrated feature
+
+Use the application's normal typecheck, lint, and build commands. For table examples, also compile against the built package declarations so workspace augmentations cannot hide incompatible cell props. In this repository, `bun run test:table-examples` in `packages/ui` runs that focused check after `lib:build`.
+
+Add or retain focused regression coverage for changed behavior:
+
+- Forms: invalid input shows a visible associated error; successful submission receives parsed values; raw setters/reset values remain correctly typed.
+- Bound controls: only the form owns values; interaction callbacks get native values; setters and resets do not fire them.
+- Autosave: clearing a field sends the intended deletion; resetting cancels queued work; an edit made during save/refetch survives; refresh does not trigger an unintended save.
+- Selection: searchable Select saves IDs, multiple Select clears to `[]`, and Autocomplete saves free text and clears to `""`.
+- Loading: searching and loading the next cursor work; the final page stops loading; aborts do not restore old results; failed selected-label lookup preserves IDs and offers retry.
+- Uploads: both multiple aliases work; single clearing produces `null`; multiple clearing produces `[]`; stale completion cannot replace a newer selection or attachment.
+- Dates: outputs match the table above; range end is inclusive when using full ISO; time anchors and zone changes preserve the intended domain date/time.
+- Tables/pages: the first and second pages request the expected rows; page size resets pagination; cached data survives refresh errors; filters and sort survive URL reload.
+- Buttons: ordinary actions remain actions; selected actions retain their state and callbacks; icon actions have accessible names; loading prevents activation; links keep their targets; wrapper replacements retain sizes and existing tooltip behavior.
+- Accessibility: labels, helper/error associations, keyboard operation, overlay names, and focus restoration work in the layouts the application uses.
+
+Search again for removed entries and competing bound props before finishing. Review generated output as well as its generator so obsolete imports do not return on the next code-generation run.
+
+## Removed AI instruction files
+
+The old Povio UI rules, their generation command, rulesync configuration, and package distribution tooling for those instructions were removed. Remove obsolete references or copied UI instruction files from downstream projects. Keep unrelated project rules. Do not copy the old UI rules back or add a new automatic rule installation step as part of this migration.
+
+Use public component types, this guide, the [README](README.md), and explicit examples to determine the current API. New AI instructions can be introduced separately after the API contracts are settled.
+
+## Move development tools to @povio/ui-configurator
+
+Install `@povio/ui-configurator` as a development dependency. Replace imports from `@povio/ui/ui-configurator` with `@povio/ui-configurator` (including `/vite`, `/theme`, and `/styles`), and `@povio/ui/app-canvas` with `@povio/ui-configurator/app-canvas` (including `/tanstack` and `/styles`). Add the new package to Tailwind's `@source` paths. These entries are no longer published by `@povio/ui`.