@alneas/appkit-react 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,111 @@
+# 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.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
+
+- 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.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,35 +1,32 @@
 # Appkit React
 
-React 19 forms, validation and record views connected to application-owned adapters.
+React 19 components, schema-driven forms, record tables and AI interfaces for
+business applications. Your application supplies data adapters and server rules.
 
-## Why
+## Usage
 
-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.
-
-## Highlights
-
-- `@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).
-
-## Quickstart
-
-Use an existing React 19 application with React DOM 19.
-
-```bash
-bun add @alneas/appkit-react
-```
+Requires Node.js 24 or later and React / React DOM `^19.2.3`. Import styles once
+at your application's entry point.
 
 ```tsx
-import {Button} from '@alneas/appkit-react/ui';
+import { Button } from '@alneas/appkit-react/ui';
 import '@alneas/appkit-react/styles';
-export function SaveButton() {return <Button>Save</Button>;}
+
+export function SaveButton({ save }: { save: () => void }) {
+  return <Button onClick={save}>Save</Button>;
+}
 ```
 
-## Next steps
+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).
 
-[Public exports and optional peers](docs/exports.md) · [Contributing](../../CONTRIBUTING.md) · [Releasing](../../RELEASING.md)
+## Documentation
 
-[Complete request form](docs/request-form.md). FormView requires collection, QueryClientProvider and DataAccessProvider.
+[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)
 
-Compiled CSS license texts are retained in `THIRD_PARTY_NOTICES.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.

package/consumer-ai/SKILL.md

@@ -0,0 +1,20 @@
+---
+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.
+
+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.