@judo/actions 0.1.0

package/LICENSE

@@ -0,0 +1,277 @@
+Eclipse Public License - v 2.0
+
+    THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE
+    PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION
+    OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.
+
+1. DEFINITIONS
+
+"Contribution" means:
+
+  a) in the case of the initial Contributor, the initial content
+     Distributed under this Agreement, and
+
+  b) in the case of each subsequent Contributor:
+     i) changes to the Program, and
+     ii) additions to the Program;
+  where such changes and/or additions to the Program originate from
+  and are Distributed by that particular Contributor. A Contribution
+  "originates" from a Contributor if it was added to the Program by
+  such Contributor itself or anyone acting on such Contributor's behalf.
+  Contributions do not include changes or additions to the Program that
+  are not Modified Works.
+
+"Contributor" means any person or entity that Distributes the Program.
+
+"Licensed Patents" mean patent claims licensable by a Contributor which
+are necessarily infringed by the use or sale of its Contribution alone
+or when combined with the Program.
+
+"Program" means the Contributions Distributed in accordance with this
+Agreement.
+
+"Recipient" means anyone who receives the Program under this Agreement
+or any Secondary License (as applicable), including Contributors.
+
+"Derivative Works" shall mean any work, whether in Source Code or other
+form, that is based on (or derived from) the Program and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship.
+
+"Modified Works" shall mean any work in Source Code or other form that
+results from an addition to, deletion from, or modification of the
+contents of the Program, including, for purposes of clarity any new file
+in Source Code form that contains any contents of the Program. Modified
+Works shall not include works that contain only declarations,
+interfaces, types, classes, structures, or files of the Program solely
+in each case in order to link to, bind by name, or subclass the Program
+or Modified Works thereof.
+
+"Distribute" means the acts of a) distributing or b) making available
+in any manner that enables the transfer of a copy.
+
+"Source Code" means the form of a Program preferred for making
+modifications, including but not limited to software source code,
+documentation source, and configuration files.
+
+"Secondary License" means either the GNU General Public License,
+Version 2.0, or any later versions of that license, including any
+exceptions or additional permissions as identified by the initial
+Contributor.
+
+2. GRANT OF RIGHTS
+
+  a) Subject to the terms of this Agreement, each Contributor hereby
+  grants Recipient a non-exclusive, worldwide, royalty-free copyright
+  license to reproduce, prepare Derivative Works of, publicly display,
+  publicly perform, Distribute and sublicense the Contribution of such
+  Contributor, if any, and such Derivative Works.
+
+  b) Subject to the terms of this Agreement, each Contributor hereby
+  grants Recipient a non-exclusive, worldwide, royalty-free patent
+  license under Licensed Patents to make, use, sell, offer to sell,
+  import and otherwise transfer the Contribution of such Contributor,
+  if any, in Source Code or other form. This patent license shall
+  apply to the combination of the Contribution and the Program if, at
+  the time the Contribution is added by the Contributor, such addition
+  of the Contribution causes such combination to be covered by the
+  Licensed Patents. The patent license shall not apply to any other
+  combinations which include the Contribution. No hardware per se is
+  licensed hereunder.
+
+  c) Recipient understands that although each Contributor grants the
+  licenses to its Contributions set forth herein, no assurances are
+  provided by any Contributor that the Program does not infringe the
+  patent or other intellectual property rights of any other entity.
+  Each Contributor disclaims any liability to Recipient for claims
+  brought by any other entity based on infringement of intellectual
+  property rights or otherwise. As a condition to exercising the
+  rights and licenses granted hereunder, each Recipient hereby
+  assumes sole responsibility to secure any other intellectual
+  property rights needed, if any. For example, if a third party
+  patent license is required to allow Recipient to Distribute the
+  Program, it is Recipient's responsibility to acquire that license
+  before distributing the Program.
+
+  d) Each Contributor represents that to its knowledge it has
+  sufficient copyright rights in its Contribution, if any, to grant
+  the copyright license set forth in this Agreement.
+
+  e) Notwithstanding the terms of any Secondary License, no
+  Contributor makes additional grants to any Recipient (other than
+  those set forth in this Agreement) as a result of such Recipient's
+  receipt of the Program under the terms of a Secondary License
+  (if permitted under the terms of Section 3).
+
+3. REQUIREMENTS
+
+3.1 If a Contributor Distributes the Program in any form, then:
+
+  a) the Program must also be made available as Source Code, in
+  accordance with section 3.2, and the Contributor must accompany
+  the Program with a statement that the Source Code for the Program
+  is available under this Agreement, and informs Recipients how to
+  obtain it in a reasonable manner on or through a medium customarily
+  used for software exchange; and
+
+  b) the Contributor may Distribute the Program under a license
+  different than this Agreement, provided that such license:
+     i) effectively disclaims on behalf of all other Contributors all
+     warranties and conditions, express and implied, including
+     warranties or conditions of title and non-infringement, and
+     implied warranties or conditions of merchantability and fitness
+     for a particular purpose;
+
+     ii) effectively excludes on behalf of all other Contributors all
+     liability for damages, including direct, indirect, special,
+     incidental and consequential damages, such as lost profits;
+
+     iii) does not attempt to limit or alter the recipients' rights
+     in the Source Code under section 3.2; and
+
+     iv) requires any subsequent distribution of the Program by any
+     party to be under a license that satisfies the requirements
+     of this section 3.
+
+3.2 When the Program is Distributed as Source Code:
+
+  a) it must be made available under this Agreement, or if the
+  Program (i) is combined with other material in a separate file or
+  files made available under a Secondary License, and (ii) the initial
+  Contributor attached to the Source Code the notice described in
+  Exhibit A of this Agreement, then the Program may be made available
+  under the terms of such Secondary Licenses, and
+
+  b) a copy of this Agreement must be included with each copy of
+  the Program.
+
+3.3 Contributors may not remove or alter any copyright, patent,
+trademark, attribution notices, disclaimers of warranty, or limitations
+of liability ("notices") contained within the Program from any copy of
+the Program which they Distribute, provided that Contributors may add
+their own appropriate notices.
+
+4. COMMERCIAL DISTRIBUTION
+
+Commercial distributors of software may accept certain responsibilities
+with respect to end users, business partners and the like. While this
+license is intended to facilitate the commercial use of the Program,
+the Contributor who includes the Program in a commercial product
+offering should do so in a manner which does not create potential
+liability for other Contributors. Therefore, if a Contributor includes
+the Program in a commercial product offering, such Contributor
+("Commercial Contributor") hereby agrees to defend and indemnify every
+other Contributor ("Indemnified Contributor") against any losses,
+damages and costs (collectively "Losses") arising from claims, lawsuits
+and other legal actions brought by a third party against the Indemnified
+Contributor to the extent caused by the acts or omissions of such
+Commercial Contributor in connection with its distribution of the Program
+in a commercial product offering. The obligations in this section do not
+apply to any claims or Losses relating to any actual or alleged
+intellectual property infringement. In order to qualify, an Indemnified
+Contributor must: a) promptly notify the Commercial Contributor in
+writing of such claim, and b) allow the Commercial Contributor to control,
+and cooperate with the Commercial Contributor in, the defense and any
+related settlement negotiations. The Indemnified Contributor may
+participate in any such claim at its own expense.
+
+For example, a Contributor might include the Program in a commercial
+product offering, Product X. That Contributor is then a Commercial
+Contributor. If that Commercial Contributor then makes performance
+claims, or offers warranties related to Product X, those performance
+claims and warranties are such Commercial Contributor's responsibility
+alone. Under this section, the Commercial Contributor would have to
+defend claims against the other Contributors related to those performance
+claims and warranties, and if a court requires any other Contributor to
+pay any damages as a result, the Commercial Contributor must pay
+those damages.
+
+5. NO WARRANTY
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT
+PERMITTED BY APPLICABLE LAW, THE PROGRAM IS PROVIDED ON AN "AS IS"
+BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR
+IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF
+TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
+PURPOSE. Each Recipient is solely responsible for determining the
+appropriateness of using and distributing the Program and assumes all
+risks associated with its exercise of rights under this Agreement,
+including but not limited to the risks and costs of program errors,
+compliance with applicable laws, damage to or loss of data, programs
+or equipment, and unavailability or interruption of operations.
+
+6. DISCLAIMER OF LIABILITY
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT
+PERMITTED BY APPLICABLE LAW, NEITHER RECIPIENT NOR ANY CONTRIBUTORS
+SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST
+PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE
+EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+7. GENERAL
+
+If any provision of this Agreement is invalid or unenforceable under
+applicable law, it shall not affect the validity or enforceability of
+the remainder of the terms of this Agreement, and without further
+action by the parties hereto, such provision shall be reformed to the
+minimum extent necessary to make such provision valid and enforceable.
+
+If Recipient institutes patent litigation against any entity
+(including a cross-claim or counterclaim in a lawsuit) alleging that the
+Program itself (excluding combinations of the Program with other software
+or hardware) infringes such Recipient's patent(s), then such Recipient's
+rights granted under Section 2(b) shall terminate as of the date such
+litigation is filed.
+
+All Recipient's rights under this Agreement shall terminate if it
+fails to comply with any of the material terms or conditions of this
+Agreement and does not cure such failure in a reasonable period of
+time after becoming aware of such noncompliance. If all Recipient's
+rights under this Agreement terminate, Recipient agrees to cease use
+and distribution of the Program as soon as reasonably practicable.
+However, Recipient's obligations under this Agreement and any licenses
+granted by Recipient relating to the Program shall continue and survive.
+
+Everyone is permitted to copy and distribute copies of this Agreement,
+but in order to avoid inconsistency the Agreement is copyrighted and
+may only be modified in the following manner. The Agreement Steward
+reserves the right to publish new versions (including revisions) of
+this Agreement from time to time. No one other than the Agreement
+Steward has the right to modify this Agreement. The Eclipse Foundation
+is the initial Agreement Steward. The Eclipse Foundation may assign the
+responsibility to serve as the Agreement Steward to a suitable separate
+entity. Each new version of the Agreement will be given a distinguishing
+version number. The Program (including Contributions) may always be
+Distributed subject to the version of the Agreement under which it was
+received. In addition, after a new version of the Agreement is published,
+Contributor may elect to Distribute the Program (including its
+Contributions) under the new version.
+
+Except as expressly stated in Sections 2(a) and 2(b) above, Recipient
+receives no rights or licenses to the intellectual property of any
+Contributor under this Agreement, whether expressly, by implication,
+estoppel or otherwise. All rights in the Program not expressly granted
+under this Agreement are reserved. Nothing in this Agreement is intended
+to be enforceable by any entity that is not a Contributor or Recipient.
+No third-party beneficiary rights are created under this Agreement.
+
+Exhibit A - Form of Secondary Licenses Notice
+
+"This Source Code may also be made available under the following 
+Secondary Licenses when the conditions for such availability set forth 
+in the Eclipse Public License, v. 2.0 are satisfied: {name license(s),
+version(s), and exceptions or additional permissions here}."
+
+  Simply including a copy of this Agreement, including this Exhibit A
+  is not sufficient to license the Source Code under Secondary Licenses.
+
+  If it is not possible or desirable to put the notice in a particular
+  file, then You may include the notice in a location (such as a LICENSE
+  file in a relevant directory) where a recipient would be likely to
+  look for such a notice.
+
+  You may add additional accurate notices of copyright ownership.

package/README.md

@@ -0,0 +1,257 @@
+# @judo/actions
+
+> Action handler system and REST API client for JUDO UI Runtime
+
+## Purpose
+
+Provides the complete action handler system — a registry of **40 built-in action handler hooks** (navigation, CRUD, relation, operation, form, selector, autocomplete, table, and other), a full REST API client (`JudoRestApi`), transfer serialization, path building, a React context provider for the API, lifecycle composition for action overrides, and dispatcher/handler hooks for wiring actions to UI components.
+
+## Architecture Layer
+
+**Layer 4 (Features)** — depends on `model-api`; consumed by `components` and `app-shell`.
+
+## Dependencies
+
+- `@judo/model-api` — model type definitions (`Action`, `ActionDefinition`, `ClassType`, `RelationType`, etc.)
+- `react ^19` — React (peer dependency)
+
+> **Note:** While handlers conceptually use services from `core` (navigation, data store), `feedback` (dialogs, notifications), and `i18n` (translations), these are **not package dependencies**. Handlers receive these services at runtime through the `TypedActionHandlerContext` object passed to each handler invocation.
+
+## File Structure
+
+```
+src/
+├── index.ts                          # Root barrel export
+├── types.ts                          # Core action types, interfaces, context shapes
+├── api/
+│   ├── types.ts                      # REST API types (HTTP, serialization, validation, query)
+│   ├── constants.ts                  # REST header names and URL suffixes
+│   ├── transfer-serializer.ts          # Default transfer serializer (strips internal props)
+│   ├── judo-rest-api.ts              # JudoRestApi class (~870 lines) - full REST client
+│   ├── model-converters.ts           # Convert model types → REST metadata (internal)
+│   └── path-builder.ts              # REST URL path construction
+├── hooks/
+│   ├── use-action-dispatcher.ts      # useActionDispatcher hook
+│   └── use-action-handler.ts         # useActionHandler hook + hasActionHandler
+├── provider/
+│   └── api-context.tsx               # ApiProvider + useApi context
+├── registry/
+│   └── action-handler-registry.ts    # Maps 40 action types → handler hooks
+├── lifecycle/
+│   └── execute-with-lifecycle.ts     # Lifecycle composition engine (before/execute/after/onError)
+└── handlers/
+    ├── navigation/                   # 4 handlers
+    ├── form/                         # 3 handlers
+    ├── selector/                     # 5 handlers
+    ├── crud/                         # 7 handlers
+    ├── relation/                     # 8 handlers
+    ├── table/                        # 3 handlers
+    ├── operation/                    # 5 handlers
+    ├── autocomplete/                 # 3 handlers
+    └── other/                        # 2 handlers
+```
+
+## Exports Summary
+
+### Core Action Types
+
+| Export                                  | Kind      | Description                                                                                                                                                                                                        |
+| --------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ActionType`                            | type      | Union of 40 string literals — all action definition type names.                                                                                                                                                    |
+| `DialogCloseResultType`                 | type      | `"cancelled" \| "created" \| "updated" \| "deleted" \| "selected" \| "submitted"`                                                                                                                                  |
+| `DialogCloseResult`                     | type      | Discriminated union for dialog/action outcomes.                                                                                                                                                                    |
+| `TypedActionHandlerContext`             | interface | Runtime context: `transfer`, `selectedRows`, `closeDialog`, `navigation`, `data`, `registry`, `validation`, `notifications`, `isEager`, `pageType`, `isEditMode`, `isPageAction`, `createDialog`, `onDialogClose`. |
+| `ActionHandlerHookWithMeta`             | interface | Typed handler hook with `.actionType` metadata property for registration.                                                                                                                                          |
+| `ActionHandlerFactoryProperties`        | interface | Custom handler registration properties (by `sourceId`).                                                                                                                                                            |
+| `BuiltInActionHandlerFactoryProperties` | interface | Built-in handler registration properties (by `actionType`).                                                                                                                                                        |
+| `ACTION_HANDLER_FACTORY`                | symbol    | Service symbol for DI registration (re-exported from `model-api`).                                                                                                                                                 |
+
+### Lifecycle
+
+| Export                                                                 | Kind     | Description                                                                           |
+| ---------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- |
+| `executeWithLifecycle(defaultHandler, overrides, baseContext, action)` | function | Composes lifecycle overrides (before/execute/after/onError) around a default handler. |
+
+### REST API Client
+
+| Export                      | Kind      | Description                                                                                    |
+| --------------------------- | --------- | ---------------------------------------------------------------------------------------------- |
+| `JudoRestApi` (class)       | class     | Full REST client (~870 lines) with 25+ methods covering all JUDO REST operations.              |
+| `createJudoRestApi(config)` | function  | Factory function for `JudoRestApi`.                                                            |
+| `JudoRestApiConfig`         | interface | Config: `baseUrl`, `application: Application`, optional interceptors, serializer/deserializer. |
+
+**Key REST methods:**
+
+| Method                                                  | REST Endpoint                          | Description                                   |
+| ------------------------------------------------------- | -------------------------------------- | --------------------------------------------- |
+| `getTemplate(classType)`                                | `GET /{classPath}/~template`           | Fetch template for new transfer               |
+| `refresh(classType, target, qc?)`                       | `POST /{classPath}/~get`               | Refresh stored transfer by signed ID          |
+| `update(classType, target, mask?)`                      | `POST /{classPath}/~update`            | Update existing transfer                      |
+| `validateUpdate(classType, target)`                     | `POST /{classPath}/~validate`          | Server-side update validation                 |
+| `delete(classType, target)`                             | `POST /{classPath}/~delete`            | Delete transfer                               |
+| `listRelation(relation, owner?, qc?, countRecords?)`    | `POST /…/{relation}/~list`             | List transfers in relation                    |
+| `getRelation(relation, owner, qc?)`                     | `POST /…/{relation}/~get`              | Get single-valued relation                    |
+| `refreshAccessRelation(relation, qc?)`                  | `POST /…/{relation}/~get`              | Get non-collection access relation (no owner) |
+| `getRelationRange(relation, owner?, qc?)`               | `POST /…/{relation}/~range`            | Fetch range for selectors                     |
+| `getRelationTemplate(relation)`                         | `GET /{targetClassPath}/~template`     | Get template for relation target              |
+| `createRelation(relation, owner, data, mask?)`          | `POST /…/~create`                      | Create transfer in relation                   |
+| `validateCreateRelation(relation, owner, data)`         | `POST /…/~validate`                    | Validate create before persisting             |
+| `setRelation(relation, owner, selected)`                | `POST /…/~update/{relation}/~set`      | Set single-valued relation                    |
+| `unsetRelation(relation, owner)`                        | `POST /…/~update/{relation}/~unset`    | Clear single-valued relation                  |
+| `addToRelation(relation, owner, selected)`              | `POST /…/~update/{relation}/~add`      | Add to collection relation                    |
+| `removeFromRelation(relation, owner, selected)`         | `POST /…/~update/{relation}/~remove`   | Remove from collection relation               |
+| `exportRelation(relation, owner?, qc?)`                 | `POST /…/{relation}/~export`           | Export relation data as blob                  |
+| `invokeOperation(classType, op, owner?, input?)`        | `POST /{classPath}/{opName}`           | Invoke operation                              |
+| `validateOperationInput(classType, op, owner?, input?)` | `POST /{classPath}/{opName}/~validate` | Validate operation input                      |
+| `getOperationInputTemplate(operation)`                  | `GET /{inputClassPath}/~template`      | Get template for operation input              |
+| `getOperationInputRange(classType, op, owner?, qc?)`    | `POST /{classPath}/{opName}/~range`    | Fetch range for operation selector            |
+| `getPrincipal()`                                        | `GET /{actorPath}/~principal`          | Get current principal                         |
+| `getMetadata()`                                         | `GET /{actorPath}/~meta`               | Get application metadata                      |
+| `uploadFile(attributePath, file)`                       | Two-step upload with token             | Upload binary data                            |
+| `downloadFile(downloadToken, disposition?)`             | `GET /download?disposition=…`          | Download binary data                          |
+| `findInstance(relation, identifier, mask?)`             | `POST /…/{relation}/~list`             | Find transfer by business identifier          |
+
+### Transfer Serialization (internal to `api/` module)
+
+These are exported from `api/index.ts` but **not** from the package's main entry point:
+
+| Export                          | Kind         | Description                                                                                    |
+| ------------------------------- | ------------ | ---------------------------------------------------------------------------------------------- |
+| `BACKEND_PROPERTIES`            | constant Set | `__identifier`, `__entityType`, `__deleteable`, `__updateable`, `__version` — never send back. |
+| `FRONTEND_PROPERTIES`           | constant Set | `__tempId`, `__isNew`, `__items` — client-only, never serialize.                               |
+| `INTERNAL_PROPERTIES`           | constant Set | Union of both sets.                                                                            |
+| `isInternalProperty(key)`       | function     | Returns true for any internal prop (keeps `__signedIdentifier`).                               |
+| `stripInternalProperties(data)` | function     | Creates a new object without internal props.                                                   |
+| `defaultTransferSerializer`     | constant     | Serializer that strips top-level internal properties (handles arrays by mapping).              |
+
+### Path Building
+
+| Function                                                            | Description                                          |
+| ------------------------------------------------------------------- | ---------------------------------------------------- |
+| `getPathForActor(application, path?)`                               | Builds `/{modelName}/{actorPath}{path}`              |
+| `getRelationPath(relation, application, suffix)`                    | REST path for relation read endpoints                |
+| `getClassPath(classType, application, suffix)`                      | REST path for class endpoints                        |
+| `getMutationRelationPath(relation, application, suffix, isAccess?)` | Mutation path with `/~update/` prefix for non-access |
+| `getOperationPath(classType, operationName, application, suffix?)`  | REST path for operation invocations                  |
+
+### API Validation
+
+| Export                    | Kind      | Description                                                                   |
+| ------------------------- | --------- | ----------------------------------------------------------------------------- |
+| `ValidationError` (class) | class     | Extends `Error` with `status`, `feedbackItems`, and `toFieldErrors()` method. |
+| `FeedbackItem`            | interface | `{ code, level, location, message }` from server responses.                   |
+
+### React Hooks
+
+| Hook                           | Description                                                                                                                                                    |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useActionDispatcher(options)` | Returns `{ dispatch, canHandle }`. Resolves handlers from registry, builds context, calls handlers. Supports lifecycle overrides via `actionOverrides` option. |
+| `useActionHandler(action)`     | Returns the handler function for a single action. Throws if no handler found.                                                                                  |
+| `hasActionHandler(action)`     | Checks whether a handler exists in the registry.                                                                                                               |
+
+### React Provider
+
+| Export        | Kind      | Description                                           |
+| ------------- | --------- | ----------------------------------------------------- |
+| `ApiProvider` | component | Provides `JudoRestApi` via React context.             |
+| `useApi()`    | hook      | Consumes the API context; throws if outside provider. |
+
+### Built-in Action Handler Hooks (40 total)
+
+#### Navigation (4)
+
+| Handler                       | Action Type                   | Description                                                           |
+| ----------------------------- | ----------------------------- | --------------------------------------------------------------------- |
+| `useBackActionHandler`        | `BackActionDefinition`        | Closes dialog if open, otherwise `goBack`                             |
+| `useOpenPageActionHandler`    | `OpenPageActionDefinition`    | Navigates to target page with transfer params; forwards eager context |
+| `useRowOpenPageActionHandler` | `RowOpenPageActionDefinition` | Same as above but for table row clicks                                |
+| `useCancelActionHandler`      | `CancelActionDefinition`      | Closes dialog → or resets transfer (VIEW edit mode) → or goBack       |
+
+#### Form (3)
+
+| Handler                                  | Action Type                              | Description                                                            |
+| ---------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------- |
+| `useOpenFormActionHandler`               | `OpenFormActionDefinition`               | Opens form dialog for editing                                          |
+| `useOpenCreateFormActionHandler`         | `OpenCreateFormActionDefinition`         | Opens create form dialog; supports eager/lazy modes with onDialogClose |
+| `useOpenOperationInputFormActionHandler` | `OpenOperationInputFormActionDefinition` | Opens form for operation input parameters                              |
+
+#### Selector (5)
+
+| Handler                                      | Action Type                                  | Description                                      |
+| -------------------------------------------- | -------------------------------------------- | ------------------------------------------------ |
+| `useOpenSelectorActionHandler`               | `OpenSelectorActionDefinition`               | Opens single-selection dialog                    |
+| `useOpenAddSelectorActionHandler`            | `OpenAddSelectorActionDefinition`            | Opens multi-selection dialog for add             |
+| `useOpenSetSelectorActionHandler`            | `OpenSetSelectorActionDefinition`            | Opens selection dialog for set                   |
+| `useOpenOperationInputSelectorActionHandler` | `OpenOperationInputSelectorActionDefinition` | Opens selector for operation input               |
+| `useSelectorRangeActionHandler`              | `SelectorRangeActionDefinition`              | Fetches range data via REST (or legacy callback) |
+
+#### CRUD (7)
+
+| Handler                       | Action Type                   | Description                                                                                                                            |
+| ----------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `useRefreshActionHandler`     | `RefreshActionDefinition`     | Four modes: access relation list, transfer relation list, selector range, single transfer refresh. Eager mode seeds from parent store. |
+| `useCreateActionHandler`      | `CreateActionDefinition`      | Eager (local with validation) or lazy (REST) create with validation flow                                                               |
+| `useUpdateActionHandler`      | `UpdateActionDefinition`      | Eager (parent update) or lazy (REST update + refresh). Reads transfer from data store via `pageTransferId`.                            |
+| `useDeleteActionHandler`      | `DeleteActionDefinition`      | REST delete, clears from store, navigates back                                                                                         |
+| `useBulkDeleteActionHandler`  | `BulkDeleteActionDefinition`  | Deletes all selected rows via parallel REST calls                                                                                      |
+| `useRowDeleteActionHandler`   | `RowDeleteActionDefinition`   | Eager (remove from parent) or lazy (REST delete) single row                                                                            |
+| `useGetTemplateActionHandler` | `GetTemplateActionDefinition` | Fetches default values via REST; stores at `pageTransferId`                                                                            |
+
+#### Relation (8)
+
+| Handler                           | Action Type                       | Description                                                  |
+| --------------------------------- | --------------------------------- | ------------------------------------------------------------ |
+| `useSetActionHandler`             | `SetActionDefinition`             | Sets single-valued relation; closes dialog with `"selected"` |
+| `useUnsetActionHandler`           | `UnsetActionDefinition`           | Clears single-valued relation                                |
+| `useAddActionHandler`             | `AddActionDefinition`             | Adds to collection relation; closes dialog with `"selected"` |
+| `useRemoveActionHandler`          | `RemoveActionDefinition`          | Eager (remove from parent array) or lazy (REST remove)       |
+| `useBulkRemoveActionHandler`      | `BulkRemoveActionDefinition`      | Eager or lazy removal of multiple selected transfers         |
+| `useClearActionHandler`           | `ClearActionDefinition`           | Clears all transfers from relation via `unsetRelation`       |
+| `useRefreshRelationActionHandler` | `RefreshRelationActionDefinition` | Refreshes relation data (list or get based on cardinality)   |
+| `useFilterRelationActionHandler`  | `FilterRelationActionDefinition`  | Signals filter intent via `onFilterRelation` callback        |
+
+#### Table (3)
+
+| Handler                           | Action Type                       | Description                                                  |
+| --------------------------------- | --------------------------------- | ------------------------------------------------------------ |
+| `useFilterActionHandler`          | `FilterActionDefinition`          | Signals filter intent via `onFilterRequest` callback         |
+| `useExportActionHandler`          | `ExportActionDefinition`          | Exports via REST, triggers browser download                  |
+| `useInlineCreateRowActionHandler` | `InlineCreateRowActionDefinition` | Signals inline row creation via `onInlineCreateRow` callback |
+
+#### Operation (5)
+
+| Handler                                      | Action Type                                  | Description                                                                  |
+| -------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------- |
+| `useCallOperationActionHandler`              | `CallOperationActionDefinition`              | Invokes bound operation via REST; opens output dialog if result + targetPage |
+| `useBulkCallOperationActionHandler`          | `BulkCallOperationActionDefinition`          | Invokes operation on each selected row in parallel                           |
+| `useInputFormCallOperationActionHandler`     | `InputFormCallOperationActionDefinition`     | Invokes operation with form input; closes dialog only on success             |
+| `useInputSelectorCallOperationActionHandler` | `InputSelectorCallOperationActionDefinition` | Invokes operation with selected transfer; closes dialog only on success      |
+| `useParameterlessCallOperationActionHandler` | `ParameterlessCallOperationActionDefinition` | Invokes operation with no input                                              |
+
+#### Autocomplete (3)
+
+| Handler                             | Action Type                         | Description                                     |
+| ----------------------------------- | ----------------------------------- | ----------------------------------------------- |
+| `useAutocompleteRangeActionHandler` | `AutocompleteRangeActionDefinition` | Fetches range for autocomplete with search text |
+| `useAutocompleteSetActionHandler`   | `AutocompleteSetActionDefinition`   | Sets single-valued relation via autocomplete    |
+| `useAutocompleteAddActionHandler`   | `AutocompleteAddActionDefinition`   | Adds to collection via autocomplete             |
+
+#### Other (2)
+
+| Handler                    | Action Type                | Description                                |
+| -------------------------- | -------------------------- | ------------------------------------------ |
+| `usePreFetchActionHandler` | `PreFetchActionDefinition` | Pre-fetches data via `onPreFetch` callback |
+| `useCustomActionHandler`   | `CustomActionDefinition`   | Delegates to `onCustomAction` callback     |
+
+## Key Patterns
+
+- **Hook factory pattern**: Every handler is `(action) => (context) => Promise<void>`. React hooks at the outer level; async handler at the inner level.
+- **Discriminated union dispatch**: Internal registry maps `@type` → handler hook. 40 entries cover all action types.
+- **Eager vs Lazy**: CRUD and relation handlers distinguish between eager (local aggregated, no REST) and lazy (REST-persisted) modes.
+- **Transfer serialization**: `defaultTransferSerializer` strips all `__*` properties except `__signedIdentifier`.
+- **Validation error flow**: `ValidationError` auto-parses 400 responses. Handlers set field errors on `ValidationContext`.
+- **Path construction**: `getRelationPath`/`getClassPath`/`getMutationRelationPath` compose REST URLs from model metadata.
+- **Context casting**: Handlers cast `TypedActionHandlerContext` to local interfaces for mode-specific properties (eager, selector, API, legacy callbacks).
+- **React context for API**: `ApiProvider`/`useApi` decouple handler instantiation from API configuration.
+- **Lifecycle composition**: `executeWithLifecycle` wraps built-in handlers with before/execute/after/onError hooks for customization.
+- **Legacy callback support**: All handlers support both legacy callbacks (on\*) and API mode, enabling incremental migration.

package/dist/api/constants.d.ts

@@ -0,0 +1,27 @@
+/**
+ * JUDO REST API constants.
+ * Based on REST_REQUEST_MAPPING_SPECIFICATION.md
+ */
+export declare const HEADER_SIGNED_IDENTIFIER = "X-Judo-SignedIdentifier";
+export declare const HEADER_MASK = "X-Judo-Mask";
+export declare const HEADER_MARK_SELECTED_RANGE_ITEMS = "X-Judo-Mark-Selected-Range-Items";
+export declare const HEADER_COUNT_RECORDS = "X-Judo-CountRecords";
+export declare const HEADER_TOKEN = "X-Token";
+export declare const DEFAULT_COMMAND_MASK = "{}";
+export declare const SUFFIX_TEMPLATE = "/~template";
+export declare const SUFFIX_GET = "/~get";
+export declare const SUFFIX_UPDATE = "/~update";
+export declare const SUFFIX_VALIDATE = "/~validate";
+export declare const SUFFIX_DELETE = "/~delete";
+export declare const SUFFIX_LIST = "/~list";
+export declare const SUFFIX_RANGE = "/~range";
+export declare const SUFFIX_CREATE = "/~create";
+export declare const SUFFIX_SET = "/~set";
+export declare const SUFFIX_UNSET = "/~unset";
+export declare const SUFFIX_ADD = "/~add";
+export declare const SUFFIX_REMOVE = "/~remove";
+export declare const SUFFIX_EXPORT = "/~export";
+export declare const SUFFIX_UPLOAD_TOKEN = "/~upload-token";
+export declare const SUFFIX_PRINCIPAL = "/~principal";
+export declare const SUFFIX_META = "/~meta";
+//# sourceMappingURL=constants.d.ts.map

package/dist/api/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/api/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,eAAO,MAAM,wBAAwB,4BAA4B,CAAC;AAClE,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,gCAAgC,qCAAqC,CAAC;AACnF,eAAO,MAAM,oBAAoB,wBAAwB,CAAC;AAC1D,eAAO,MAAM,YAAY,YAAY,CAAC;AAGtC,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAGzC,eAAO,MAAM,eAAe,eAAe,CAAC;AAC5C,eAAO,MAAM,UAAU,UAAU,CAAC;AAClC,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,eAAO,MAAM,eAAe,eAAe,CAAC;AAC5C,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,eAAO,MAAM,WAAW,WAAW,CAAC;AACpC,eAAO,MAAM,YAAY,YAAY,CAAC;AACtC,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,eAAO,MAAM,UAAU,UAAU,CAAC;AAClC,eAAO,MAAM,YAAY,YAAY,CAAC;AACtC,eAAO,MAAM,UAAU,UAAU,CAAC;AAClC,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AACpD,eAAO,MAAM,gBAAgB,gBAAgB,CAAC;AAC9C,eAAO,MAAM,WAAW,WAAW,CAAC"}

package/dist/api/index.d.ts

@@ -0,0 +1,9 @@
+export { JudoRestApi, createJudoRestApi } from './judo-rest-api';
+export type { JudoRestApiConfig, OperationInfo } from './judo-rest-api';
+export type { JudoRestResponse, TransferData, StrictTransferData, TransferStored, StrictTransferStored, QueryCustomizer, RangeRequestBody, HttpMethod, ResponseType, DeserializationType, ServiceType, ResponseDeserializerConfig, TransferSerializer, TransferDeserializer, TemporalFieldType, TemporalFieldRegistry, FeedbackItem, DialogResult, OnDialogSubmit, OnDialogValidate, } from './types';
+export { ValidationError } from './types';
+export { getPathForActor, getRelationPath, getClassPath, getMutationRelationPath, getOperationPath, } from './path-builder';
+export { HEADER_SIGNED_IDENTIFIER, HEADER_MASK, HEADER_MARK_SELECTED_RANGE_ITEMS, HEADER_TOKEN, DEFAULT_COMMAND_MASK, SUFFIX_TEMPLATE, SUFFIX_GET, SUFFIX_UPDATE, SUFFIX_VALIDATE, SUFFIX_DELETE, SUFFIX_LIST, SUFFIX_RANGE, SUFFIX_CREATE, SUFFIX_SET, SUFFIX_UNSET, SUFFIX_ADD, SUFFIX_REMOVE, SUFFIX_EXPORT, } from './constants';
+export { defaultTransferSerializer, createModelAwareSerializer, serializeTemporalValue, stripInternalProperties, isInternalProperty, INTERNAL_PROPERTIES, BACKEND_PROPERTIES, FRONTEND_PROPERTIES, } from './transfer-serializer';
+export { createModelAwareDeserializer, deserializeTemporalValue, parseLocalDate } from './transfer-deserializer';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACjE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACxE,YAAY,EAEX,gBAAgB,EAEhB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAEhB,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,WAAW,EAEX,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EAEpB,iBAAiB,EACjB,qBAAqB,EAErB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,gBAAgB,GAChB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EACN,eAAe,EACf,eAAe,EACf,YAAY,EACZ,uBAAuB,EACvB,gBAAgB,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACN,wBAAwB,EACxB,WAAW,EACX,gCAAgC,EAChC,YAAY,EACZ,oBAAoB,EACpB,eAAe,EACf,UAAU,EACV,aAAa,EACb,eAAe,EACf,aAAa,EACb,WAAW,EACX,YAAY,EACZ,aAAa,EACb,UAAU,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACb,aAAa,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,yBAAyB,EACzB,0BAA0B,EAC1B,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,4BAA4B,EAAE,wBAAwB,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC"}