@alneas/appkit-react 0.1.0 → 0.2.0

package/docs/index.md

@@ -1,42 +1,115 @@
 ---
 title: "Appkit React"
 description: "Unified React 19 business UI toolkit: accessible primitives, schema-driven forms, data tables, and AI chat interfaces"
+sidebar:
+  order: 1
 archetype: explanation
-project: tools
+project: appkit
+tags: ["appkit", "overview"]
 ---
 
 # Appkit React
 
-React 19 forms, validation and record views connected to application-owned adapters.
+React 19 components, schema-driven forms and record views for business applications.
 
-## Why
+[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)
 
-Feature subpaths keep provider decisions visible while installation uses just two npm packages. Align schemas with validation and record operations; retain application control over data writes.
+## Elevator Pitch
 
-## Highlights
+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.
 
-- `@alneas/appkit-react/ui`: [Compose React UI and shared providers](ui.md).
-- `@alneas/appkit-react/tools`: [Build schema forms and record tables](tools.md).
-- `@alneas/appkit-react/ai`: [Review AI proposals in React](ai.md).
+## 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](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)
 
 ## Quickstart
 
-Use an existing React 19 application with React DOM 19.
+### 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
-bun add @alneas/appkit-react
+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](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.
+
 ```tsx
-import {Button} from '@alneas/appkit-react/ui';
+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 '@alneas/appkit-react/styles';
-export function SaveButton() {return <Button>Save</Button>;}
+
+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>
+  );
+}
 ```
 
-## Next steps
+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.
+
+## Next Steps
+
+- [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.
+
+### For coding agents
+
+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.
 
-[Public exports and optional peers](exports.md) · [Contributing](../../../CONTRIBUTING.md) · [Releasing](../../../RELEASING.md)
+### Contributing and license
 
-[Complete request form](request-form.md). FormView requires collection, QueryClientProvider and DataAccessProvider.
+[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)
 
-Compiled CSS license texts are retained in `THIRD_PARTY_NOTICES.md`.
+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.

package/docs/migration.md

@@ -0,0 +1,268 @@
+---
+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"]
+---
+
+# Migrate from app-core and react-tools
+
+## 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.
+
+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
+
+Install the two package names. Import framework-free APIs from
+`@alneas/appkit-core/data`, `/storage`, `/japan`, `/graph` or `/ai`, and React
+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
+
+### 1. Choose the migration route
+
+| Route | Destination | What to change |
+| --- | --- | --- |
+| Keep the restricted product and its extensions | `@dataarthub/appkit-core` and `@dataarthub/appkit-react` on GitHub Packages | Rename the package prefix; check each used subpath and named export against that private release. |
+| Adopt the independently usable public subset | `@alneas/appkit-core` and `@alneas/appkit-react` on npm | Move each API to its feature subpath, review behavior differences and replace any feature outside the public exports. |
+
+These are different distributions. Replacing `@dataarthub` with `@alneas` does
+not preserve the full legacy product. If an API is absent from the public export
+references, retain its restricted implementation or choose an application-owned
+replacement before removing the old dependency.
+
+For the restricted rename, the intended prefix changes are:
+
+| Old | New restricted package |
+| --- | --- |
+| `@dataarthub/app-core` | `@dataarthub/appkit-core` |
+| `@dataarthub/react-tools` | `@dataarthub/appkit-react` |
+
+For example, `/schema/core` remains a Core subpath and `/form` remains a React
+subpath on that route. Select versions actually available to your GitHub Packages
+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
+
+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
+```
+
+A server-only application needs only `@alneas/appkit-core@0.1.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.
+
+If both distributions remain in the application, retain scoped registry routing:
+
+```ini
+@alneas:registry=https://registry.npmjs.org
+@dataarthub:registry=https://npm.pkg.github.com
+```
+
+Keep GitHub Packages authentication in the application's existing secret-managed
+configuration. An entirely public consumer does not need GitHub Packages credentials.
+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
+
+The following are destination entry points to inspect, not a claim that every
+symbol in an old barrel is available at the new entry.
+
+| Legacy import | Public destination |
+| --- | --- |
+| `@dataarthub/react-tools/ui` | `@alneas/appkit-react/ui` |
+| `@dataarthub/react-tools/core` | `@alneas/appkit-react/tools/core` |
+| `@dataarthub/react-tools/form` | `@alneas/appkit-react/tools/form` |
+| `@dataarthub/react-tools/data-table` | `@alneas/appkit-react/tools/data-table` |
+| `@dataarthub/react-tools/data-access/react` | `@alneas/appkit-react/tools/data-access/react` |
+| `@dataarthub/react-tools/filter` | `@alneas/appkit-react/tools/filter` |
+| `@dataarthub/react-tools/pane` | `@alneas/appkit-react/tools/pane` |
+| `@dataarthub/react-tools/workflow` | `@alneas/appkit-react/tools/workflow` |
+| `@dataarthub/react-tools/calendar` | `@alneas/appkit-react/tools/calendar` |
+| `@dataarthub/react-tools/kanban` | `@alneas/appkit-react/tools/kanban` |
+| `@dataarthub/react-tools/gantt` | `@alneas/appkit-react/tools/gantt` |
+| `@dataarthub/react-tools/chart` | `@alneas/appkit-react/tools/chart` |
+| `@dataarthub/react-tools/barcode` | `@alneas/appkit-react/tools/barcode` |
+| `@dataarthub/react-tools/file-browser` | `@alneas/appkit-react/tools/file-browser` |
+| `@dataarthub/react-tools/error` | `@alneas/appkit-react/tools/error` |
+| `@dataarthub/react-tools/i18n` | `@alneas/appkit-react/tools/i18n` |
+| `@dataarthub/react-tools/proposal` | `@alneas/appkit-react/ai/proposal` |
+| `@dataarthub/react-tools/action` | `@alneas/appkit-react/ai/action` |
+| `@dataarthub/react-tools/generative-ui` | `@alneas/appkit-react/ai/generative-ui` |
+| `@dataarthub/react-tools/styles` | `@alneas/appkit-react/styles` |
+
+Apply the same `/tools/` destination pattern for the public `sidebar`, `header`,
+`splash`, `priority-queue` and `editable-table` entries. Private authentication
+composition is not replaced by the public `/tools/auth` helper entry.
+
+Before:
+
+```diff
+-import { FormView } from '@dataarthub/react-tools/form';
+-import '@dataarthub/react-tools/styles';
++import { FormView } from '@alneas/appkit-react/tools/form';
++import '@alneas/appkit-react/styles';
+```
+
+Import the public stylesheet once at the application boundary. There is no public
+`/dist/react-tools.css`, `/theme.css`, `/base.css` or `/globals.css` compatibility
+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
+
+| Legacy Core import | Public destination / decision |
+| --- | --- |
+| `@dataarthub/app-core/schema` | `@alneas/appkit-core/data/schema` |
+| `@dataarthub/app-core/schema/core` | `@alneas/appkit-core/data/schema/core` |
+| `@dataarthub/app-core/schema/compiler` | `@alneas/appkit-core/data/schema/compiler` |
+| `@dataarthub/app-core/schema/server` | `@alneas/appkit-core/data/schema/server` (server only) |
+| `@dataarthub/app-core/data-access` | `@alneas/appkit-core/data` (common contracts/services) |
+| `@dataarthub/app-core/data-access/types` | `@alneas/appkit-core/data/types` |
+| `@dataarthub/app-core/data-access/sqlite` | `@alneas/appkit-core/data/sqlite` |
+| `@dataarthub/app-core/data-access/d1` | `@alneas/appkit-core/data/d1` |
+| `@dataarthub/app-core/storage` | `@alneas/appkit-core/storage`; review adapter configuration |
+| `@dataarthub/app-core/storage/local-adapter` | `@alneas/appkit-core/storage/server`; review constructor options |
+| `@dataarthub/app-core/storage/types` | Type imports from `@alneas/appkit-core/storage` |
+| `@dataarthub/app-core/proposal` | `@alneas/appkit-core/ai/proposal` |
+| `@dataarthub/app-core/action` | `@alneas/appkit-core/ai/action` |
+| `@dataarthub/app-core/generative-ui` | `@alneas/appkit-core/ai/generative-ui` |
+| `@dataarthub/app-core/ai` | `@alneas/appkit-core/ai/ai-chat` for conversation/chat APIs; check each symbol |
+| `@dataarthub/app-core/agent-output` | `@alneas/appkit-core/ai/agent-output` |
+| `@dataarthub/app-core/encoding` | `@alneas/appkit-core/data/encoding` |
+| `@dataarthub/app-core/content` | `@alneas/appkit-core/data/content`; Git Markdown uses `@alneas/appkit-core/data/content/git-markdown` |
+| `@dataarthub/app-core/editor` | `@alneas/appkit-core/data/editor` (JSON/upload helpers, not editor UI) |
+| `@dataarthub/app-core/excel` | Generic adapters: `@alneas/appkit-core/data/excel`; Japanese templates: `@alneas/appkit-core/japan/excel` |
+| `@dataarthub/app-core/csv` | Choose generic `@alneas/appkit-core/data/csv` or Japanese defaults in `@alneas/appkit-core/japan/csv` |
+| `@dataarthub/app-core/finance` | Generic calculations: `@alneas/appkit-core/data/finance`; Japanese invoice rules: `@alneas/appkit-core/japan/finance` |
+| `@dataarthub/app-core/edi` | Generic contracts: `@alneas/appkit-core/data/edi`; Japanese document conversion: `@alneas/appkit-core/japan/edi` |
+| `@dataarthub/app-core/pdf` | Generic data: `@alneas/appkit-core/data/pdf`; Japanese presets: `@alneas/appkit-core/japan/pdf`; neither replaces React PDF rendering |
+| `@dataarthub/app-core/legal-document` | `@alneas/appkit-core/japan/legal-document` |
+| `@dataarthub/app-core/notifications` | Choose `@alneas/appkit-core/data/notifications` or `@alneas/appkit-core/japan/notifications` |
+| `@dataarthub/app-core/google-calendar` | `@alneas/appkit-core/data/google-calendar` |
+
+Framework-free imports formerly reached through `@dataarthub/react-tools` should
+also move to Core, not to an assumed matching React export. Provider-specific
+record adapters have explicit entries such as `@alneas/appkit-core/data/supabase`
+and `@alneas/appkit-core/data/neon`; install their peers separately. Keep backend
+SDKs, filesystem access and credentials out of browser entry modules.
+
+The public Core root exports namespaces (`data`, `storage`, `japan`, `graph`, `ai`,
+`us`). It does not reproduce the old flat Core barrel. Prefer named feature imports:
+
+```typescript
+import { createAjvValidator } from '@alneas/appkit-core/data/schema/core';
+import { CSVGenerator } from '@alneas/appkit-core/japan/csv';
+import type { DataAccessAdapter } from '@alneas/appkit-core/data/types';
+
+export const validate = createAjvValidator({ locale: 'ja' });
+export const csv = new CSVGenerator();
+export function loadRecords(adapter: DataAccessAdapter) {
+  return adapter.find('records', {});
+}
+```
+
+### 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`,
+`schema`, `mode` and the explicit validation policy. `onSave` does not remove these
+provider requirements. A private `AppProvider` is not exported by public Appkit;
+compose the needed public providers in the host application instead.
+
+Import related hooks and providers from the same distribution, keep one compatible
+React runtime and query context, and declare dependencies you import directly.
+An application can pass its own compatible adapter to public UI without moving
+its database or replacing its backend implementation.
+
+Review these contracts before switching traffic:
+
+- **Validation:** explicitly choose locale, empty-string handling, numeric casting
+  and JSON Schema draft. Verify invalid input and omitted/default values, rather
+  than assuming legacy localized defaults survive a generic import.
+- **Regional formatting:** generic helpers and Japanese presets have different
+  responsibilities. Preserve CSV date formatting, invoice rounding, tax and
+  document output with representative fixtures when changing the chosen entry.
+- **Storage:** check constructor options, object keys, URL generation and failure
+  behavior against your configured adapter. The public storage layer uses
+  Web-standard signing/runtime APIs; do not assume an old SDK client constructor
+  or compliance wrapper is interchangeable.
+- **Persistence:** changing imports does not move records, run migrations or change
+  authorization. Keep connection configuration and existing data in place; verify
+  read/create/update/delete and failure handling against your application's adapter.
+- **AI:** use Core for proposal validation/contracts and React for review UI.
+  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
+
+For an application that has migrated every legacy import to the public subset:
+
+```bash
+bun remove @dataarthub/react-tools @dataarthub/app-core
+```
+
+Keep restricted dependencies still used by private features. Update TypeScript,
+bundler and test aliases, mocks, CSS imports and AI instruction references along
+with application imports. Remove obsolete source/tarball overrides and regenerate
+the application's own lockfile with its package manager.
+
+Public AI entry points are `@alneas/appkit-core/ai-instructions` and
+`@alneas/appkit-react/ai-instructions`, with machine context at each package's
+`/package-context.json`. The legacy `dist/ai/setup.mjs` is not a public setup CLI.
+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
+
+In the consuming application:
+
+1. Search source, tests and configuration for `@dataarthub/app-core` and
+   `@dataarthub/react-tools`. Each remaining use must be intentional.
+2. Run the application's TypeScript check with its normal module resolution.
+   Confirm each moved symbol exists, not just the destination subpath.
+3. Run the production build and open the migrated screens. Verify providers,
+   styles, validation, locale and optional integration loading.
+4. Exercise only the changed feature boundaries: real form persistence, adapter
+   failures and relevant document/CSV output. Reuse unchanged integration evidence
+   where its inputs still match; avoid production-data writes as a migration probe.
+5. Review the dependency tree for legacy leftovers or duplicate React/query
+   contexts, then keep the migration diff and application checks together.
+
+Expected result: the application resolves the selected published packages without
+source aliases, type-checks, and retains its tested behavior through explicit
+adapters/providers. Appkit's `0.1.0` release checks covered isolated public package
+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
+
+| Symptom | What to check |
+| --- | --- |
+| Package installation returns 401/404 | Public packages use npm; retained restricted packages need the correct GitHub scope and credentials. |
+| `Package subpath is not defined by exports` | Use the complete new feature path; there is no blanket compatibility alias for old subpaths or `dist/*`. |
+| A named export disappeared | Root barrels differ. Locate the actual symbol in the export reference; some features remain restricted. |
+| Missing query/data-access context | Use the paired public providers in the complete form recipe and check for duplicate dependency instances. |
+| UI renders without styling | Import `@alneas/appkit-react/styles` at the application boundary. |
+| Dates, validation or documents changed | Choose explicit locale/validation settings and the appropriate generic or Japanese preset entry. |
+| A browser build pulls in backend code | Move filesystem/SDK/credential imports to server modules and use explicit feature entries. |
+| A legacy provider/editor/PDF component has no public equivalent | Retain the restricted distribution or replace that feature explicitly; a namespace rename is insufficient. |

package/docs/request-form.md

@@ -1,8 +1,11 @@
 ---
 title: "Save a schema-driven request form"
 description: "Wire a schema to an application-owned adapter with retained input on failure."
+sidebar:
+  order: 3
 archetype: how-to
-project: tools
+project: appkit
+tags: ["appkit", "request-form"]
 ---
 
 # Save a schema-driven request form

package/docs/tools.md

@@ -1,8 +1,11 @@
 ---
 title: "Build schema forms and record tables"
 description: "Schema-driven forms, tables, filters and CRUD views"
+sidebar:
+  order: 4
 archetype: how-to
-project: tools
+project: appkit
+tags: ["appkit", "tools"]
 ---
 
 # Build schema forms and record tables

package/docs/ui.md

@@ -1,8 +1,11 @@
 ---
 title: "Compose React UI and shared providers"
 description: "React 19 primitives, theme providers and hooks"
+sidebar:
+  order: 5
 archetype: how-to
-project: tools
+project: appkit
+tags: ["appkit", "ui"]
 ---
 
 # Compose React UI and shared providers