@alneas/appkit-react 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,90 @@ 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.3.1]
+
+### Fixed
+
+- Preserve the KanbanColumnFrame registration/ref requirements in one JSDoc remarks
+  block so strict API documentation consumers retain the full guidance without
+  duplicate-tag warnings. Runtime behavior and callable types are unchanged.
+
+- Correct GenerativeUIRenderer declaration documentation to retain all rendering
+  requirements and fallback notes in one remarks block. Strict TypeDoc consumers
+  can generate API documentation without duplicate-tag warnings; runtime behavior,
+  exports and callable types are unchanged.
+- Require the published Core **^0.2.2** documentation patch. The compatible range
+  admits Core 0.2.x updates while excluding older declaration documentation;
+  applications retain exact resolved versions and integrity in their lockfile.
+  Verify that React and any host Core dependency resolve one shared installation.
+- This patch aligns the delivered Core documentation and dependency resolution;
+  it adds no public API changes. The breaking migration from React 0.2.x remains
+  documented under 0.3.0 and in the bundled migration guide.
+- This entry describes release preparation. Confirm npm availability before
+  adopting React 0.3.1; published React 0.3.0 continues to require Core 0.2.0.
+
+- Remove deprecated `aria-grabbed` from DataTable, shared Draggable/FileBrowser activators and enabled Kanban cards while
+  retaining `aria-pressed`, keyboard/pointer dragging, screen-reader instructions
+  and live announcements. This correction requires a new React package release;
+  published 0.3.0 archives do not contain it.
+
+## [0.3.0]
+
+### Breaking changes
+
+- Move all Appkit drag surfaces to native dnd-kit React 0.5.1. Generic provider
+  events use nullable `operation.source` / `target`, direct entity `data`, and
+  `event.canceled` in `onDragEnd`; the separate `onDragCancel` prop is removed.
+- Draggable render props use `ref` / `handleRef` instead of `attributes`,
+  `listeners` and `setNodeRef`; droppable props use `ref` / `isDropTarget`.
+  Native feedback owns movement; render-prop `style` is presentation only.
+- Exported Kanban sensors, controller context props and custom surfaces use the
+  native engine. High-level component props, business callbacks and FileProvider
+  operations remain; `resolveKanbanMove` retains its structural legacy input.
+- DOM-ref wrappers expose ordinary React 19 function component types. Normal JSX
+  props, DOM targets, Base UI composition and callback cleanup remain supported;
+  `ForwardRefExoticComponent` internals such as `.render` / `$$typeof` are removed.
+  Use `ComponentProps<typeof Component>` and `ComponentRef<typeof Component>`.
+- Hosts sharing Query must align `@tanstack/react-query` and
+  `@tanstack/query-core` at **5.104.5**. Mixed 5.104.4 / 5.104.5 installations can
+  produce nominal QueryClient/Query type conflicts.
+
+### Changed
+
+- Keep filter and keyboard callbacks current through committed Effect Events;
+  unchanged filters remain deduplicated and listener ownership stays stable.
+- Update Query to 5.104.5, Zustand to 5.0.16, panels to 4.14.8, Lucide to 1.61.0,
+  form resolvers to 6.0.0, and the reviewed localization dependencies. Host
+  integrations should verify their own cache/provider, forms and locale behavior.
+- Use a 250ms touch hold with 5px tolerance in the generic provider, retaining its
+  5px mouse/pen threshold. Native file icon handles retain selection/open behavior
+  and permit early touch scrolling.
+- Consolidate upgrade instructions in the packaged migration guide. Keep the npm
+  README concise and English-only, with documentation, history and migration links.
+
+### Fixed
+
+- Preserve hidden/grouped/persisted table order and reject stale drag positions.
+  File moves validate the current listing; successful overlapping moves refresh
+  the relevant current view without refreshing a departed view.
+
+### Removed
+
+- Remove production legacy core/sortable/utilities dependencies and the global
+  React-19 JSX compatibility shim. Applications must migrate their own old-engine
+  usage before removing direct dependencies they still need.
+
+### Upgrade from 0.2.0
+
+- This pre-1.0 minor contains breaking low-level drag and component-type changes.
+  Read the [0.3.0 migration guide](docs/migration.md) before upgrading and confirm
+  npm availability before installing exact React 0.3.0 / Core 0.2.0 pins.
+- React's Core dependency stays exactly **0.2.0**; no Core 0.3.0 is required.
+  Node >=24.0.0 and React/React DOM ^19.2.3 remain the public requirements.
+- Align Query, migrate low-level callbacks/registrations, update relevant native
+  input tests and regenerate host-owned API/notices records. A source version or
+  prepared changelog does not change an already published archive.
+
 ## [0.2.0]
 
 ### Added
@@ -49,5 +133,7 @@ dates are recorded only when confirmed.
 - Initial public release of React UI, forms, tables, providers and AI bindings,
   with ESM, CommonJS, TypeScript declarations and explicit styles.
 
+[0.3.1]: https://github.com/dataarthub/appkit/compare/appkit-react-v0.3.0...appkit-react-v0.3.1
+[0.3.0]: https://github.com/dataarthub/appkit/compare/appkit-react-v0.2.0...appkit-react-v0.3.0
 [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,105 +1,32 @@
 # 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 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.
+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).
 
-### Contributing and license
+## Documentation
 
-[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)
+[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)
 
-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.

package/consumer-ai/SKILL.md

@@ -10,3 +10,11 @@ Use api-index.json for actual exported names, signatures and public import paths
 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.
+
+React 0.3.0 drag surfaces use native dnd-kit React. Read docs/migration.md from
+this installed package before adapting a 0.2.0 consumer. It covers nullable native
+events, cancellation guards, registration refs, React 19 function component types
+and Query 5.104.5 alignment. High-level features own their native providers;
+standalone registrations must share a native provider. Resolve exact types from
+the matching installed API catalog. A prepared source version does not prove
+registry availability, and a newer catalog must not replace an older installation.