@alneas/appkit-react 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+Consumer-facing changes for `@alneas/appkit-react`, newest first. A versioned entry
+may be prepared before publication; confirm availability on the
+[npm package page](https://www.npmjs.com/package/@alneas/appkit-react). Publication
+dates are recorded only when confirmed.
+
+## [0.2.0]
+
+### Added
+
+- Discoverable agent instructions, package context and API catalog in
+  `consumer-ai/`, identified by the `appkit.agent` manifest field, and the public
+  `@alneas/appkit-react/api-index.json` export. Core's `appkit-api` CLI can inspect
+  the React catalog when this package is installed.
+- This cumulative changelog, included in the npm archive and linked from README.
+
+### Fixed
+
+- Make Ajv resolver field-error entries writable so React Hook Form can update
+  and clear them without property-assignment errors.
+- Improve accessible names, live error announcements, semantic table markup,
+  keyboard/drag interactions and theme behavior in the reviewed DataTable,
+  editable table, file preview, calendar, Gantt, Kanban, workflow and theme controls.
+  These changes do not certify every component or arbitrary host color palette.
+
+### Changed
+
+- Pin the runtime Core dependency to `0.2.0`, adopting its AI error codes,
+  documentation URLs and recovery metadata. Publishing Core independently does
+  not update older React installations' exact dependency.
+- Expand public component/hook JSDoc and canonical import/setup examples.
+
+### Upgrade from 0.1.0
+
+- After this version is published, install `@alneas/appkit-react@0.2.0`. Applications
+  importing Core directly should install `@alneas/appkit-core@0.2.0` as well so
+  their direct dependency agrees with React's exact Core dependency.
+- Keep Node.js 24 or newer and React/React DOM `^19.2.3`, the documented providers
+  and the explicit stylesheet import. Review peers for each optional feature.
+- Applications still own AI tool approval, server authorization and durable
+  idempotency. Core recovery metadata does not authorize retries or execution.
+- The public Storybook catalog and its automated state/accessibility tests are
+  repository development tools, not a new npm runtime dependency or proof of
+  hosted-provider behavior.
+
+## [0.1.0]
+
+- Initial public release of React UI, forms, tables, providers and AI bindings,
+  with ESM, CommonJS, TypeScript declarations and explicit styles.
+
+[0.2.0]: https://github.com/dataarthub/appkit/compare/v0.1.0...appkit-react-v0.2.0
+[0.1.0]: https://github.com/dataarthub/appkit/releases/tag/v0.1.0

package/README.md

@@ -1,35 +1,105 @@
 # 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](docs/ui.md).
-- `@alneas/appkit-react/tools`: [Build schema forms and record tables](docs/tools.md).
-- `@alneas/appkit-react/ai`: [Review AI proposals in React](docs/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](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
 
-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](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.
+
 ```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](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 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](docs/exports.md) · [Contributing](../../CONTRIBUTING.md) · [Releasing](../../RELEASING.md)
+### Contributing and license
 
-[Complete request form](docs/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/consumer-ai/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: appkit-react-consumer
+description: Integrate @alneas/appkit-react using published feature subpaths.
+---
+
+Read package-context.json for exact exports and peers. Install package names; import feature subpaths. Each feature guide must state its public import path. Preserve host providers and explicit CSS imports. Applications own authorization, migrations, final writes, atomic checks and durable idempotency. AI metadata consistency does not establish end-to-end coding-agent capability.
+
+Use api-index.json for actual exported names, signatures and public import paths. Read llms.txt and the linked feature guide before choosing optional peers, host providers or CSS. Package.json appkit.agent is Appkit-specific discovery metadata, not an automatically executed agent hook. The same skill, context and catalog are present at consumer-ai/ and dist/consumer-ai/ for compatibility.
+
+The Core package's appkit-api CLI searches locally available catalogs without running tools or contacting a provider. Check each result's package version and digest; registry 0.1.0 does not include this new CLI. Never replace a missing legacy catalog with a newer API surface. Always verify generated code with the consumer's type checker and relevant behavior tests.
+
+AI tool calls and outputs are untrusted. Schema validity is not approval. Bind host approval to immutable arguments/targets/session/registration, enforce server permissions and durable idempotency at execution, and project minimal outputs. Adapters do not run tools or authorize writes. Read the AI guide and Core error guide; never infer permission from a tool-output event or bypass duplicate-call protection.