@alneas/appkit-react 0.2.0 → 0.3.1

package/llms-full.txt

@@ -2,109 +2,36 @@
 
 # Appkit React
 
-React 19 components, schema-driven forms and record views for business applications.
+React 19 components, schema-driven forms, record tables and AI interfaces for
+business applications. Your application supplies data adapters and server rules.
 
-[npm](https://www.npmjs.com/package/@alneas/appkit-react) · [Documentation](https://tech-docs.alneas.com/appkit/appkit-react/) · [GitHub](https://github.com/dataarthub/appkit) · [Change history](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/CHANGELOG.md)
+## Usage
 
-## Elevator Pitch
-
-Turn a JSON Schema into a form with validation and connect saves to your own backend. Combine forms with record tables, shared UI primitives and AI proposal review interfaces.
-
-## Why & Value
-
-Use React when your application needs the presentation layer for Appkit's schema and record contracts. You provide the authenticated data adapter and server rules; the form uses that adapter and reports the save result to your UI.
-
-React depends on [Appkit Core](https://www.npmjs.com/package/@alneas/appkit-core). Install Core directly as well when your own code imports its types or functions, as the example below does. For backend-only validation, storage or graph calculations, use Core alone.
-
-## Key Highlights
-
-- **Schema forms and record tables:** build input, filtering and CRUD views around shared record contracts. [Tools guide](docs/tools.md)
-- **React UI primitives:** compose buttons, dialogs, shared providers and hooks. [UI guide](docs/ui.md)
-- **AI interfaces:** connect chat and proposal review to explicit application approval and execution boundaries. [AI guide](docs/ai.md)
-- **Explicit integration:** import styles and supply host providers and data adapters. [Complete form recipe](docs/request-form.md)
-
-## Quickstart
-
-### Requirements and installation
-
-Use an existing React application. The package declares Node.js **24 or later** and requires React and React DOM **`^19.2.3`**. It provides ESM, CommonJS and TypeScript declarations.
-
-```bash
-npm install @alneas/appkit-react @alneas/appkit-core react@^19.2.3 react-dom@^19.2.3 @tanstack/react-query@5.104.4
-# Or use bun add with the same package names and versions.
-```
-
-The example directly imports TanStack Query, so it is listed explicitly. Import Appkit CSS once at your application's stylesheet entry point. `FormView` also requires `QueryClientProvider` and `DataAccessProvider`; a standalone `Button` does not require those data providers. Install optional chart, barcode, QR or AI peers only for their corresponding features; see [the export reference](docs/exports.md).
-
-### Render and save a request form
-
-This component accepts your application's `DataAccessAdapter`. Implement that adapter for your backend and pass it as the `adapter` prop; no demo backend or credentials are included.
+Requires Node.js 24 or later and React / React DOM `^19.2.3`. Import styles once
+at your application's entry point.
 
 ```tsx
-import { useState, type ComponentProps } from 'react';
-import type { DataAccessAdapter } from '@alneas/appkit-core/data';
-import { QueryClientProvider } from '@tanstack/react-query';
-import {
-  createQueryClient,
-  DataAccessProvider,
-} from '@alneas/appkit-react/tools/data-access/react';
-import { FormView } from '@alneas/appkit-react/tools/form';
+import { Button } from '@alneas/appkit-react/ui';
 import '@alneas/appkit-react/styles';
 
-const schema: ComponentProps<typeof FormView>['schema'] = {
-  type: 'object',
-  properties: {
-    name: { type: 'string', title: 'Name', minLength: 2 },
-    reason: { type: 'string', title: 'Reason', 'x-ui': { widget: 'textarea' } },
-  },
-  required: ['name'],
-};
-
-export function RequestForm({ adapter }: { adapter: DataAccessAdapter }) {
-  const [client] = useState(createQueryClient);
-  const [saved, setSaved] = useState('');
-
-  return (
-    <QueryClientProvider client={client}>
-      <DataAccessProvider adapter={adapter}>
-        <FormView
-          testId="persistence"
-          collection="records"
-          mode="create"
-          schema={schema}
-          validation={{
-            emptyStrings: 'preserve',
-            locale: 'en',
-            cast: { numericMode: 'strict' },
-          }}
-          onSuccess={record => setSaved(JSON.stringify(record))}
-        />
-        <output aria-label="Persisted">{saved}</output>
-      </DataAccessProvider>
-    </QueryClientProvider>
-  );
+export function SaveButton({ save }: { save: () => void }) {
+  return <Button onClick={save}>Save</Button>;
 }
 ```
 
-The form renders Name and Reason fields. A name shorter than two characters should fail validation. A successful save displays the record returned by your adapter. Your backend must enforce authorization, business rules and concurrency; browser validation is only the UI boundary. If your application already has a shared Query client, reuse its provider instead of adding another one. See the [complete recipe](docs/request-form.md) for failure and retry checks.
-
-## Next Steps
-
-- [Schema forms and record tables](docs/tools.md): the business UI entry points.
-- [UI primitives and providers](docs/ui.md): components and shared host setup.
-- [Public exports and optional peers](docs/exports.md): exact feature paths and additional dependencies.
-- [AI integration and security](docs/ai.md): proposal review and execution boundaries.
-- [Migration guide](docs/migration.md): moving from the earlier separate packages.
+For schema forms and record views, follow the [complete form recipe](docs/request-form.md)
+for the data adapter, Query provider and peer setup. Optional integrations have
+[additional peer requirements](docs/exports.md).
 
-### For coding agents
+## Documentation
 
-Start with the [agent instructions](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/consumer-ai/SKILL.md), then use the [API catalog](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/consumer-ai/api-index.json) and [full documentation](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/llms-full.txt). Installed packages include these files under `consumer-ai/` and `llms-full.txt`; their locations are also listed in the `appkit.agent` manifest field.
+[Guides and API](https://tech-docs.alneas.com/appkit/appkit-react/) ·
+[Change history](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/CHANGELOG.md) ·
+[GitHub Issues](https://github.com/dataarthub/appkit/issues)
 
-### Contributing and license
-
-[Contributing](https://github.com/dataarthub/appkit/blob/main/CONTRIBUTING.md) · [Releasing](https://github.com/dataarthub/appkit/blob/main/RELEASING.md) · [MIT license](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/LICENSE)
-
-Third-party license texts retained from the compiled CSS are included in [THIRD_PARTY_NOTICES.md](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/THIRD_PARTY_NOTICES.md), also shipped in the package root.
+Upgrading to 0.3.0 introduces breaking drag-event and component-type changes.
+Read the [migration guide](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/docs/migration.md)
+before upgrading. A prepared source version does not establish npm availability.
 
 
 ---
@@ -284,139 +211,383 @@ tags: ["appkit", "overview"]
 
 # Appkit React
 
-React 19 components, schema-driven forms and record views for business applications.
+React 19 components, schema-driven forms, record tables and AI interfaces for
+business applications. Your application supplies data adapters and server rules.
 
-[npm](https://www.npmjs.com/package/@alneas/appkit-react) · [Documentation](https://tech-docs.alneas.com/appkit/appkit-react/) · [GitHub](https://github.com/dataarthub/appkit) · [Change history](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/CHANGELOG.md)
+## Usage
 
-## Elevator Pitch
+Requires Node.js 24 or later and React / React DOM `^19.2.3`. Import styles once
+at your application's entry point.
 
-Turn a JSON Schema into a form with validation and connect saves to your own backend. Combine forms with record tables, shared UI primitives and AI proposal review interfaces.
+```tsx
+import { Button } from '@alneas/appkit-react/ui';
+import '@alneas/appkit-react/styles';
 
-## Why & Value
+export function SaveButton({ save }: { save: () => void }) {
+  return <Button onClick={save}>Save</Button>;
+}
+```
 
-Use React when your application needs the presentation layer for Appkit's schema and record contracts. You provide the authenticated data adapter and server rules; the form uses that adapter and reports the save result to your UI.
+For schema forms and record views, follow the [complete form recipe](request-form.md)
+for the data adapter, Query provider and peer setup. Optional integrations have
+[additional peer requirements](exports.md).
 
-React depends on [Appkit Core](https://www.npmjs.com/package/@alneas/appkit-core). Install Core directly as well when your own code imports its types or functions, as the example below does. For backend-only validation, storage or graph calculations, use Core alone.
+## Documentation
 
-## Key Highlights
+[Guides and API](https://tech-docs.alneas.com/appkit/appkit-react/) ·
+[Change history](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/CHANGELOG.md) ·
+[GitHub Issues](https://github.com/dataarthub/appkit/issues)
 
-- **Schema forms and record tables:** build input, filtering and CRUD views around shared record contracts. [Tools guide](tools.md)
-- **React UI primitives:** compose buttons, dialogs, shared providers and hooks. [UI guide](ui.md)
-- **AI interfaces:** connect chat and proposal review to explicit application approval and execution boundaries. [AI guide](ai.md)
-- **Explicit integration:** import styles and supply host providers and data adapters. [Complete form recipe](request-form.md)
+Upgrading to 0.3.0 introduces breaking drag-event and component-type changes.
+Read the [migration guide](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/docs/migration.md)
+before upgrading. A prepared source version does not establish npm availability.
 
-## Quickstart
 
-### Requirements and installation
+---
 
-Use an existing React application. The package declares Node.js **24 or later** and requires React and React DOM **`^19.2.3`**. It provides ESM, CommonJS and TypeScript declarations.
+<!-- docs/migration.md -->
+
+---
+title: "Upgrade Appkit React to 0.3.0"
+description: "Migrate native drag registrations, React 19 component types and shared Query dependencies, preserving the older package-split route."
+sidebar:
+  order: 20
+archetype: how-to
+project: appkit
+tags: ["migration", "core", "react"]
+---
+
+# Upgrade Appkit React to 0.3.0
+
+This guide targets **React 0.3.0 with Core 0.2.0**, upgrading from React 0.2.0.
+It may be prepared before npm publication. Confirm availability on npm before
+installing; source versions and a merged PR do not prove delivery. The default
+portal must retain the last delivered revision until publication is confirmed;
+then ingest the reviewed 0.3.0 source and API catalog together.
+
+## React 0.3.1 dependency alignment (release preparation)
+
+React 0.3.1 requires Core `^0.2.2`, starting at the confirmed published
+0.2.2 release. Applications keep an exact selected version in their lockfile. It adds no API migration beyond 0.3.0. Published React 0.3.0 retains its
+exact Core 0.2.0 dependency; the 0.3.0 commands below remain its historical route.
+
+After confirming React 0.3.1 is available, hosts with a direct Core dependency
+should install matching exact versions and refresh their lockfile:
 
 ```bash
-npm install @alneas/appkit-react @alneas/appkit-core react@^19.2.3 react-dom@^19.2.3 @tanstack/react-query@5.104.4
-# Or use bun add with the same package names and versions.
+npm view @alneas/appkit-react@0.3.1 version
+npm install --save-exact @alneas/appkit-react@0.3.1 @alneas/appkit-core@0.2.2 @tanstack/react-query@5.104.5 @tanstack/query-core@5.104.5
+npm ls @alneas/appkit-core
 ```
 
-The example directly imports TanStack Query, so it is listed explicitly. Import Appkit CSS once at your application's stylesheet entry point. `FormView` also requires `QueryClientProvider` and `DataAccessProvider`; a standalone `Button` does not require those data providers. Install optional chart, barcode, QR or AI peers only for their corresponding features; see [the export reference](exports.md).
+Confirm React and the host resolve the same Core 0.2.2 installation. Before npm
+publication, use verified candidate archives only for isolated checks; keep the
+portal and production consumers on their confirmed delivered versions. The
+remaining API migration sections apply to the 0.3 series.
 
-### Render and save a request form
+## Prerequisites
 
-This component accepts your application's `DataAccessAdapter`. Implement that adapter for your backend and pass it as the `adapter` prop; no demo backend or credentials are included.
+Use Node.js 24 or newer and React/React DOM matching `^19.2.3`. Confirm that
+React 0.3.0 is published before installing it; a source manifest version or merged
+PR does not establish npm availability.
+Keep the host lockfile and a working revision before upgrading. No new feature
+peer is required for high-level components. Import Appkit CSS once at the host
+boundary; provider contexts remain owned by each feature.
+
+## Public import
+
+| Surface | Supported import |
+| --- | --- |
+| Generic provider and registrations | `@alneas/appkit-react/tools/ui` (also root, `/tools` and `/tools/core`) |
+| Kanban board, Compound API and low-level helpers | `@alneas/appkit-react/tools/kanban` |
+| DataTable | `@alneas/appkit-react/tools/data-table` |
+| FileBrowser, standalone views and FileProvider types | `@alneas/appkit-react/tools/file-browser` |
+| Stylesheet | `@alneas/appkit-react/styles` |
+
+## Step-by-Step Implementation
+
+### 1. Select a containing release and inventory old-engine usage
+
+Confirm availability first, then install exact package versions. Before publication,
+use only the maintainer-verified candidate archives for isolated testing.
+
+```bash
+npm view @alneas/appkit-react@0.3.0 version
+npm install --save-exact @alneas/appkit-react@0.3.0 @alneas/appkit-core@0.2.0 @tanstack/react-query@5.104.5 @tanstack/query-core@5.104.5
+```
+
+For the original React 0.3.0 release, Core remains exactly 0.2.0. Core 0.2.1 and 0.2.2
+contain documentation improvements with no runtime/API migration. React 0.3.1
+adopts the published Core `^0.2.2` patch as described above; confirm each version's npm
+delivery independently.
+Core does not advance to 0.3.0 in this release. Align both direct Query packages
+at **5.104.5**. Mixed 5.104.4 / 5.104.5 installations can make QueryClient and Query
+nominal types incompatible. Refresh the host lockfile and inspect `npm ls
+@tanstack/react-query @tanstack/query-core`; do not hide conflicts with type casts
+or skipLibCheck. The library's Node >=24.0.0 and React/React DOM ^19.2.3 requirements
+remain; repository development tools have a separate Node requirement.
+
+Align any direct Core dependency with the selected React package's exact Core
+pin. If the host imports native dnd-kit hooks or sensor classes directly, declare
+those packages as direct host dependencies too. High-level Appkit usage does not
+require installing their import subpaths as packages.
+
+Inventory `onDragCancel`, `active`/`over.data.current`, `setNodeRef`, `attributes`,
+`listeners`, `isOver`, custom Kanban controllers/sensors and external old-engine
+hooks. Remove old application dependencies only when its own remaining usages
+have also migrated. Do not compose old and native registrations under one
+provider.
+
+### 2. Keep high-level business props and migrate low-level composition
+
+#### Kanban and DataTable
+
+React 0.3.0 uses dnd-kit React 0.5.1 for all Appkit drag surfaces.
+Previously published 0.2.0 archive bytes remain unchanged. These components
+create their own drag provider; hosts still import Appkit CSS once.
 
 ```tsx
-import { useState, type ComponentProps } from 'react';
-import type { DataAccessAdapter } from '@alneas/appkit-core/data';
-import { QueryClientProvider } from '@tanstack/react-query';
-import {
-  createQueryClient,
-  DataAccessProvider,
-} from '@alneas/appkit-react/tools/data-access/react';
-import { FormView } from '@alneas/appkit-react/tools/form';
+import {KanbanBoard, type KanbanTask} from '@alneas/appkit-react/tools/kanban';
 import '@alneas/appkit-react/styles';
+const tasks: KanbanTask[] = [{id: 'one', title: 'Review', status: 'todo'}];
+export function ReviewTasks() {
+  return <KanbanBoard tasks={tasks} columns={[{id: 'todo', title: 'Todo'}, {id: 'done', title: 'Done'}]}
+    onStatusChange={(taskId, status) => { console.log(taskId, status); }} />;
+}
+```
 
-const schema: ComponentProps<typeof FormView>['schema'] = {
-  type: 'object',
-  properties: {
-    name: { type: 'string', title: 'Name', minLength: 2 },
-    reason: { type: 'string', title: 'Reason', 'x-ui': { widget: 'textarea' } },
-  },
-  required: ['name'],
-};
+Kanban drag changes status, including movement into empty columns. It does not
+persist order within a column or invoke `onOrderChange`. WIP limits remain visual
+warnings. Space/Enter starts or confirms movement, Left/Right selects a column,
+and Escape cancels. Read-only cards do not activate dragging. Preset optimistic
+updates and controlled compound state retain their existing ownership.
 
-export function RequestForm({ adapter }: { adapter: DataAccessAdapter }) {
-  const [client] = useState(createQueryClient);
-  const [saved, setSaved] = useState('');
+DataTable keeps `DataTableProps`, `DataTableViewProps` and the existing settings
+format. Use the separate reorder button to move leaf columns; sorting remains a
+separate action. Hidden column slots remain in persisted order. Group headers
+and placeholders do not activate dragging. A column/visibility change during a
+drag invalidates its saved positions rather than applying stale indices.
+
+#### Low-level Kanban compatibility
+
+The following exported helpers from `@alneas/appkit-react/tools/kanban` expose
+an intentional source/runtime compatibility change in React 0.3.0:
+
+| API | React 0.3.0 contract |
+| --- | --- |
+| `useKanbanSensors(statusField)` | Native `@dnd-kit/dom` sensor descriptors, not legacy core descriptors. |
+| `useKanbanDrag(options).contextProps` | Native `DragDropProvider` props. Events expose `operation.source`/`operation.target`; cancellation is `event.canceled` on end. There is no legacy `onDragCancel` property. |
+| `KanbanDragSurface.controller` | A `KanbanDragController` returned by the migrated hook. Manually constructed legacy controllers must migrate. |
 
-  return (
-    <QueryClientProvider client={client}>
-      <DataAccessProvider adapter={adapter}>
-        <FormView
-          testId="persistence"
-          collection="records"
-          mode="create"
-          schema={schema}
-          validation={{
-            emptyStrings: 'preserve',
-            locale: 'en',
-            cast: { numericMode: 'strict' },
-          }}
-          onSuccess={record => setSaved(JSON.stringify(record))}
-        />
-        <output aria-label="Persisted">{saved}</output>
-      </DataAccessProvider>
-    </QueryClientProvider>
-  );
+The high-level props/callbacks and helper names remain. `resolveKanbanMove` retains
+its structural `{active, over}` input with `over.data.current`, so existing callers
+passing that shape still work. `KanbanDraggableCard` and `KanbanColumnFrame` now
+register with the native provider: pair them with the migrated surface, not a
+legacy `DndContext` or legacy hooks. To compose a low-level board:
+
+```tsx
+import {KanbanDragSurface, KanbanColumn, useKanbanDrag, type KanbanTask}
+  from '@alneas/appkit-react/tools/kanban';
+const customTasks: KanbanTask[] = [{id: 'one', title: 'Review', status: 'todo'}];
+export function CustomTaskSurface() {
+  const controller = useKanbanDrag({tasks: customTasks});
+  return <KanbanDragSurface controller={controller}>
+    <KanbanColumn column={{id: 'todo', title: 'Todo'}} tasks={customTasks} />
+    <KanbanColumn column={{id: 'done', title: 'Done'}} tasks={[]} />
+  </KanbanDragSurface>;
 }
 ```
 
-The form renders Name and Reason fields. A name shorter than two characters should fail validation. A successful save displays the record returned by your adapter. Your backend must enforce authorization, business rules and concurrency; browser validation is only the UI boundary. If your application already has a shared Query client, reuse its provider instead of adding another one. See the [complete recipe](request-form.md) for failure and retry checks.
+#### Generic wrappers and FileBrowser
 
-## Next Steps
+`DnDProvider`, `Draggable`, `Droppable` and their prop types remain exported from
+`@alneas/appkit-react`, `/tools`, `/tools/core` and `/tools/ui`. Their low-level
+contracts now use the native engine and are a breaking change:
 
-- [Schema forms and record tables](tools.md): the business UI entry points.
-- [UI primitives and providers](ui.md): components and shared host setup.
-- [Public exports and optional peers](exports.md): exact feature paths and additional dependencies.
-- [AI integration and security](ai.md): proposal review and execution boundaries.
-- [Migration guide](migration.md): moving from the earlier separate packages.
+| Legacy contract | Native contract |
+| --- | --- |
+| `event.active`, `event.over.data.current` | `event.operation.source`, `event.operation.target`, with `.data` directly on each entity; either entity can be null. |
+| Separate `onDragCancel` callback | `onDragEnd` also runs on cancel; check `event.canceled` before persisting. |
+| `attributes`, `listeners`, `setNodeRef` | `ref` on the draggable element; optional `handleRef` on a separate activator. Accessibility and input listeners are managed natively. |
+| Droppable `setNodeRef`, `isOver` | `ref`, `isDropTarget`. |
+| CSS transform in render-prop `style` | Native feedback controls movement; `style` remains presentational opacity/cursor styling. |
+| External legacy core hooks/context | Native `@dnd-kit/react` hooks with the native provider. |
+
+The default provider uses a 5px mouse/pen threshold and a 250ms touch hold
+with 5px tolerance so early swipes can scroll, plus native keyboard movement
+(10px per arrow, Shift for larger movement), native accessibility and clone
+feedback with immediate drop completion. Hosts can pass native provider props
+including sensors/plugins to customize this policy. Droppables use pointer
+intersection; an outside drop does not choose the nearest folder. Registration
+IDs are unique within each provider. A separate handle preserves nested controls:
 
-### For coding agents
+```tsx
+import {DnDProvider, Draggable, Droppable} from '@alneas/appkit-react/tools/ui';
+import '@alneas/appkit-react/styles';
+export function NativeDragExample() {
+  return <DnDProvider onDragEnd={event => {
+    const {source, target} = event.operation;
+    if (event.canceled || !source || !target) return;
+    console.log(source.data, target.data);
+  }}>
+    <Draggable id="file" data={{name: 'Report'}}>
+      {({ref, handleRef, style}) => <div ref={ref} style={style}>
+        <button ref={handleRef}>Move report</button>
+      </div>}
+    </Draggable>
+    <Droppable id="folder">{({ref, isDropTarget}) =>
+      <div ref={ref} data-over={isDropTarget}>Archive</div>}
+    </Droppable>
+  </DnDProvider>;
+}
+```
 
-Start with the [agent instructions](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/consumer-ai/SKILL.md), then use the [API catalog](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/consumer-ai/api-index.json) and [full documentation](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/llms-full.txt). Installed packages include these files under `consumer-ai/` and `llms-full.txt`; their locations are also listed in the `appkit.agent` manifest field.
+`FileBrowser`, `FileListView`, `FileGridView` and `FileProvider` retain their
+high-level props and storage contract. Standalone list/grid views must be inside
+`DnDProvider`; their list icon buttons and grid icon buttons are the native drag
+handles. Click/Meta-or-Ctrl selection, double-click open and context menus remain.
+Dropping moves only the dragged file into a listed folder, even when several
+files are selected. The folder path gains one trailing slash when needed.
+Cancellation, outside drops, missing/removed entities and listing/navigation
+changes do not write. A successful `moveNode` resolves before refresh; a rejected
+move reports its error without a success refresh. Navigation during an in-flight
+move prevents its completion from refreshing the old view.
+
+The package no longer depends on legacy `@dnd-kit/core`, `@dnd-kit/sortable` or
+`@dnd-kit/utilities` and no longer installs a global JSX compatibility shim.
+Remove those application dependencies only after migrating any application-owned
+old-engine usages. Dependency/type checks alone do not establish interaction or
+accessibility parity in a host application.
+
+A host-owned FileProvider stays an explicit input. Appkit does not configure a
+live storage service or authorize access to it:
 
-### Contributing and license
+```tsx
+import {FileBrowser, type FileProvider} from '@alneas/appkit-react/tools/file-browser';
+import '@alneas/appkit-react/styles';
+export function HostFiles({provider}: {provider: FileProvider}) {
+  return <div style={{height: 500}}><FileBrowser provider={provider} initialViewMode="list" /></div>;
+}
+```
 
-[Contributing](https://github.com/dataarthub/appkit/blob/main/CONTRIBUTING.md) · [Releasing](https://github.com/dataarthub/appkit/blob/main/RELEASING.md) · [MIT license](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/LICENSE)
+### 3. Roll out downstream consumers after publication
 
-Third-party license texts retained from the compiled CSS are included in [THIRD_PARTY_NOTICES.md](https://github.com/dataarthub/appkit/blob/main/packages/appkit-react/THIRD_PARTY_NOTICES.md), also shipped in the package root.
+After React 0.3.0 is confirmed published, update the application's exact public
+package pin, migrate low-level call sites, remove obsolete old-engine direct
+dependencies, and regenerate its declarations, API reports and notices through
+its own tooling. Update browser dependency optimization settings and installation
+guides that still name the old engine. Replace artificial legacy MouseSensor or
+TouchSensor test injections with trusted pointer/touch input. Keep restricted
+implementation details and raw verification receipts in their owning repository.
 
+### React 19 refs, component types and callbacks
 
----
+DOM-ref wrappers receive `ref` as a regular React 19 prop. Existing calls such as
+`<Input ref={inputRef} />` retain their public props and ref targets, including
+callback-ref cleanup and supported Base UI `render` composition. Custom wrappers
+can pass `ref` along with the other props:
 
-<!-- docs/migration.md -->
+```tsx
+import type {ComponentProps} from 'react';
+import {Input} from '@alneas/appkit-react/ui';
 
----
-title: "Migrate from app-core and react-tools"
-description: "Choose between the restricted package rename and the public Appkit 0.1.0 subset, then update dependencies, imports, providers and behavior checks."
-sidebar:
-  order: 20
-archetype: how-to
-project: appkit
-tags: ["migration", "core", "react"]
----
+export function NameInput(props: ComponentProps<typeof Input>) {
+  return <Input {...props} />;
+}
+```
 
-# Migrate from app-core and react-tools
+Use `ComponentProps<typeof Input>` and `ComponentRef<typeof Input>` for consumer
+types. Regular function components do not retain the `ForwardRefExoticComponent`
+wrapper type or its internal `.render`/`$$typeof` properties.
+
+Register window keyboard shortcuts with `@alneas/appkit-react/ui/hooks`:
+
+```tsx
+import {useKeyboardShortcuts} from '@alneas/appkit-react/ui/hooks';
+
+export function SaveShortcut({save}: {save: () => void}) {
+  useKeyboardShortcuts([{key: 's', ctrlKey: true, handler: save}]);
+  return null;
+}
+```
+
+Definitions and handlers use the latest committed values without re-registering
+the listener. Pass `false` as the second argument to disable shortcuts. Matching
+is case-insensitive, `ctrlKey: true` accepts Ctrl or Meta, and only the first
+match runs. Matches prevent the default action unless `preventDefault: false`.
+Input, composition and repeat events are not filtered. This hook needs no
+provider or stylesheet.
+
+For a headless filter, import `useFilter` from
+`@alneas/appkit-react/tools/filter`. It needs no provider or stylesheet:
+
+```tsx
+import {useFilter} from '@alneas/appkit-react/tools/filter';
+
+export function StatusFilter({onChange}: {onChange: (filter: Record<string, unknown>) => void}) {
+  const {values, setField} = useFilter({
+    fields: [{field: 'status', operator: 'eq'}],
+    onChange,
+  });
+  return <input value={String(values.status ?? '')}
+    onChange={event => setField('status', event.target.value)} />;
+}
+```
+
+Changed queries call the latest committed `onChange`. Replacing only the callback
+does not replay the existing filter, and equal query contents do not notify again.
 
-## Prerequisites
+
+## Verification
+
+Compile against the packed package with NodeNext and `skipLibCheck: false` in
+both ESM and CommonJS consumers. Old callback/render-prop examples should fail
+for the documented boundary change, not for missing hidden dependencies. Check
+that neither the installed graph nor emitted declarations need legacy dnd-kit or
+a global JSX augmentation.
+
+Exercise real components: empty-column Kanban movement, status-only callbacks,
+read-only/cancel/focus behavior; hidden/grouped/persisted table ordering and
+sorting; grid/list file moves, selection, double-click and context menus. Include
+held touch movement and pre-activation scrolling. Assert one intended move,
+refresh only after success, and no writes for cancel/outside/removed or stale
+entities. A viewport named mobile does not establish touch support.
+
+Run the consuming application's type and interaction checks before rollout. The
+[maintainer contribution guide](https://github.com/dataarthub/appkit/blob/main/CONTRIBUTING.md)
+describes Appkit's own verification commands. Passing isolated component tests
+does not establish hosted-provider authorization or complete downstream acceptance.
+
+## Troubleshooting / Common Pitfalls
+
+| Symptom | Action |
+| --- | --- |
+| `onDragCancel` or `event.active` no longer type-checks | Use native `onDragEnd`, inspect `event.canceled`, then nullable `operation.source`/`target`. |
+| Render props have no `attributes`, `listeners` or `setNodeRef` | Attach native `ref` and optional `handleRef`; use `isDropTarget` on targets. |
+| External hooks do not see the board/provider | Use the native engine consistently; update custom surface/controller composition. |
+| Existing synthetic mouse/touch tests never start | Use trusted pointer input; test touch hold and scroll separately. |
+| A file move finishes after navigation | The provider write may already have completed; Appkit suppresses refreshing the departed view, not the remote write itself. |
+| Expected low-level API is absent from the installed package | Confirm the exact containing release and installed lockfile; this guide targets React 0.3.0; verify registry availability. |
+
+
+## Earlier separate-package migration
+
+If you are still using the older separate packages, identify the supported public
+exports using this route, then apply the 0.3.0 compatibility steps above. Confirm
+the destination versions are published before running the commands.
+
+### Prerequisites
 
 This guide starts with applications using `@dataarthub/app-core` and
-`@dataarthub/react-tools`. The public destination is `@alneas/appkit-core@0.1.0`
-and `@alneas/appkit-react@0.1.0`. A public version number is independent of the
-legacy private package versions; `0.1.0` is not an in-place downgrade.
+`@dataarthub/react-tools`. The public destination is `@alneas/appkit-core@0.2.0`
+and `@alneas/appkit-react@0.3.0`. A public version number is independent of the
+legacy private package versions; public and restricted version numbers must not be compared as an in-place upgrade or downgrade.
 
 Use Node.js 24.0.0 or later. Public React requires React and React DOM matching
 `^19.2.3`. Keep the application's existing lockfile and a working revision before
 changing dependencies. Inventory feature imports and runtime behavior first.
 
-## Public import
+### Public import
 
 Install the two package names. Import framework-free APIs from
 `@alneas/appkit-core/data`, `/storage`, `/japan`, `/graph` or `/ai`, and React
@@ -424,9 +595,9 @@ features from `@alneas/appkit-react/ui`, `/tools` or `/ai`. Full import targets
 appear in the tables below and the [Core export reference](../../appkit-core/docs/exports.md)
 and [React export reference](exports.md).
 
-## Step-by-Step Implementation
+### Step-by-Step Implementation
 
-### 1. Choose the migration route
+#### 1. Choose the migration route
 
 | Route | Destination | What to change |
 | --- | --- | --- |
@@ -451,15 +622,15 @@ account; a version in a source manifest does not establish that it is published.
 The public install commands and compatibility claims below apply to the public
 route only. This guide does not certify a private release or its consumers.
 
-### 2. Install the public packages and keep registry scopes separate
+#### 2. Install the public packages and keep registry scopes separate
 
 For a React application using the form recipe:
 
 ```bash
-bun add --exact @alneas/appkit-core@0.1.0 @alneas/appkit-react@0.1.0 react@19.2.3 react-dom@19.2.3 @tanstack/react-query@5.104.4
+bun add --exact @alneas/appkit-core@0.2.0 @alneas/appkit-react@0.3.0 react@19.2.3 react-dom@19.2.3 @tanstack/react-query@5.104.5 @tanstack/query-core@5.104.5
 ```
 
-A server-only application needs only `@alneas/appkit-core@0.1.0` plus its selected
+A server-only application needs only `@alneas/appkit-core@0.2.0` plus its selected
 adapter's dependencies. Install feature-specific peers from the export references;
 root installation does not configure a database, storage endpoint or AI provider.
 
@@ -475,7 +646,7 @@ configuration. An entirely public consumer does not need GitHub Packages credent
 Do not change the default registry to GitHub Packages for the public packages.
 Do not replace registry dependencies with sibling source aliases or tarball overrides.
 
-### 3. Move React imports to feature subpaths
+#### 3. Move React imports to feature subpaths
 
 The following are destination entry points to inspect, not a claim that every
 symbol in an old barrel is available at the new entry.
@@ -521,7 +692,7 @@ Import the public stylesheet once at the application boundary. There is no publi
 export. Review your own CSS overrides against the resulting UI; an import change
 does not prove visual equivalence.
 
-### 4. Separate framework-free Core imports from React bindings
+#### 4. Separate framework-free Core imports from React bindings
 
 | Legacy Core import | Public destination / decision |
 | --- | --- |
@@ -574,7 +745,7 @@ export function loadRecords(adapter: DataAccessAdapter) {
 }
 ```
 
-### 5. Reconnect providers and review behavior
+#### 5. Reconnect providers and review behavior
 
 Use the [complete request-form recipe](request-form.md) for a working form with
 `QueryClientProvider`, `DataAccessProvider`, a stable query client, `collection`,
@@ -606,7 +777,7 @@ Review these contracts before switching traffic:
   Structured API checks and this migration example do not establish that an AI
   coding agent can migrate an arbitrary application correctly.
 
-### 6. Remove legacy dependencies after the cutover
+#### 6. Remove legacy dependencies after the cutover
 
 For an application that has migrated every legacy import to the public subset:
 
@@ -626,7 +797,7 @@ The private `compliance/prepare.mjs` is also not shipped by the public packages.
 Review the public packages' `LICENSE` files and React's `THIRD_PARTY_NOTICES.md`;
 keep notices for any retained private or application dependencies in scope.
 
-## Verification
+### Verification
 
 In the consuming application:
 
@@ -649,7 +820,7 @@ consumers, declarations and the request-form recipe; they do not certify your
 application, private extensions or every hosted provider. This guide's import
 example is checked separately; no complete legacy application migration is claimed.
 
-## Troubleshooting / Common Pitfalls
+### Troubleshooting / Common Pitfalls
 
 | Symptom | What to check |
 | --- | --- |
@@ -767,6 +938,14 @@ import '@alneas/appkit-react/styles';
 export const components = {FormView, DataTable};
 ```
 
+DataTable is also available from `@alneas/appkit-react/tools/data-table`. Its
+column reorder button supports Space to pick up/drop, arrow keys to move, and
+Escape to cancel. It exposes `aria-pressed` for drag state and retains the native
+screen-reader instructions and live announcements. The deprecated `aria-grabbed`
+attribute is removed from column reorder buttons, shared Draggable activators
+(including FileBrowser grid/list handles), and enabled Kanban cards. Read-only
+Kanban cards retain explicitly supplied caller accessibility attributes.
+
 ## Verification
 
 Type-check this example in your application. See [the export reference](exports.md) for narrower entry points and exact optional peers. Package import/type checks do not certify hosted providers.