@judo/core 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,213 @@
+# @judo/core
+
+> Core React contexts and hooks for JUDO UI Runtime
+
+## Purpose
+
+Central state management layer providing application context, navigation, data binding, validation, dispatch, runtime configuration, customizations, and refresh signaling. This is the **heart of the React runtime** — it bridges model definitions to live React component trees.
+
+## Architecture Layer
+
+**Layer 3 (Infrastructure)** — consumed by components, app-shell, and actions packages.
+
+## Dependencies
+
+- `@judo/model-api` — model type definitions
+- `@judo/model-loader` — model registry
+- `@judo/actions` — action types (used by `DispatchContext`)
+- `react ^19` — React (peer)
+
+## File Structure
+
+```
+src/
+├── index.ts                          # Barrel re-export
+├── contexts/
+│   ├── application-context.tsx       # Application/actor context
+│   ├── navigation-context.tsx        # Page stack + dialog navigation
+│   ├── data-context.tsx              # DataStore provider
+│   ├── dispatch-context.tsx          # Action dispatch provider
+│   ├── page-context.tsx              # Current page metadata
+│   ├── refresh-signal-context.tsx    # Post-operation refresh signal
+│   ├── runtime-config-context.tsx    # Feature flags / runtime config
+│   ├── validation-context.tsx        # Form-level validation state
+│   ├── customizations-context.tsx    # Component overrides, interceptors, page customizations
+│   ├── mui-pro-context.tsx           # MUI X Pro component access
+│   ├── selector-selection-context.tsx # Selector dialog selection sharing
+│   └── index.ts                      # Barrel re-export for contexts
+├── hooks/
+│   ├── use-visual-binding.ts         # Visual element ↔ data store binding (incl. hiddenBy/enabledBy/requiredBy)
+│   ├── use-element-visibility.ts     # hiddenBy runtime evaluation for any VisualElement
+│   ├── use-element-disabled.ts       # enabledBy runtime evaluation for any VisualElement
+│   ├── use-validation.ts             # Per-element validation + useFormValidation
+│   ├── use-data-selector.ts          # Selector-based data subscriptions
+│   ├── use-edit-mode.ts              # Edit/dirty mode detection
+│   ├── use-visual-element.ts         # Visual element lookup utility
+│   ├── use-debounced-callback.ts     # Debounced callback for typeahead/autocomplete
+│   └── index.ts                      # Barrel re-export for hooks
+├── store/
+│   ├── data-store.ts                 # DataStore class (external store)
+│   ├── selectors.ts                  # Selector factory functions
+│   └── index.ts                      # Barrel re-export for store
+└── utils/
+    ├── deep-equal.ts                 # Deep equality comparison
+    └── index.ts                      # Barrel re-export for utils
+```
+
+## Exports Summary
+
+### Context Providers (11)
+
+| Provider                    | Key Props                                               | Purpose                                                                                                                                           |
+| --------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ApplicationProvider`       | `registry`                                              | Subscribes to `ModelRegistry` via `useSyncExternalStore`. Exposes active application + actor switching.                                           |
+| `NavigationProvider`        | `initialPage?`, `navigate?`, `getRouteForPage?`         | Page stack navigation, dialog open/close with callbacks, React Router integration.                                                                |
+| `DataProvider`              | `store?`                                                | Creates/wraps a `DataStore` instance in React context.                                                                                            |
+| `ValidationProvider`        | —                                                       | Manages field errors (`Map`) and touched state (`Set`).                                                                                           |
+| `PageProvider`              | `pageDefinition`, `transferId?`, `params?`, `isDialog?` | Current page metadata.                                                                                                                            |
+| `RuntimeConfigProvider`     | `config?`                                               | Feature flags (guards, forceShowTotalCount, headerFilters) and MUI Pro license key.                                                               |
+| `DispatchProvider`          | `dispatch`                                              | Action dispatch function for the component tree.                                                                                                  |
+| `RefreshSignalProvider`     | `signal`                                                | Page-level refresh signal. ViewContainerRenderer increments after successful operations; embedded components watch and re-dispatch refresh logic. |
+| `CustomizationsProvider`    | `customizations?`                                       | Component overrides, interceptors, page-scoped customization bundles. HMR support via ref + version counter.                                      |
+| `MuiProProvider`            | `isProEnabled`, `components?`                           | Provides Pro variants of MUI X components (e.g., `DataGridPro`). Activated when MUI Pro license is set.                                           |
+| `SelectorSelectionProvider` | `ownerTransfer?`                                        | Shares selection state (via mutable ref) between table and dialog footer in selector dialogs.                                                     |
+
+Each provider exports a **mandatory hook** (`useX()` — throws if outside provider) and an **optional hook** (`useXOptional()` — returns null), except `RefreshSignalProvider` which provides only `useRefreshSignal()` (returns 0 when outside provider).
+
+### DataStore
+
+| Export                       | Kind      | Description                                                                                                |
+| ---------------------------- | --------- | ---------------------------------------------------------------------------------------------------------- |
+| `TransferData`               | interface | Shape of transfer data objects with JUDO internal properties (`__signedIdentifier`, `__identifier`, etc.). |
+| `TransferState`              | interface | Per-transfer tracked state: `data`, `originalData`, `isDirty`, `isLoading`, `error`.                       |
+| `DataStoreState`             | interface | Full store state: `transfers` map + `version` counter.                                                     |
+| `DataSelector<T>`            | type      | Selector function: `(state: DataStoreState) => T`.                                                         |
+| `createEmptyTransferState()` | function  | Factory returning a new empty `TransferState`.                                                             |
+| `DataStore` (class)          | class     | External store (not React state) with selector-based subscriptions.                                        |
+
+**DataStore methods:**
+
+| Method                                          | Description                                                                             |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `subscribe(selector, callback)`                 | Subscribe to a data slice. Only fires when selected value changes. Returns unsubscribe. |
+| `getSnapshot(selector)`                         | Returns current value for a selector.                                                   |
+| `getState()`                                    | Returns full state (debug/test).                                                        |
+| `getTransfer(transferId)`                       | Get transfer state by ID.                                                               |
+| `setTransferData(transferId, data)`             | Sets transfer data & originalData, resets dirty/loading/error.                          |
+| `updateTransferField(transferId, field, value)` | Updates one field, recalculates `isDirty`. Creates transfer if absent.                  |
+| `updateTransferFields(transferId, updates)`     | Batch field updates, recalculates `isDirty`.                                            |
+| `setTransferLoading(transferId, loading)`       | Toggle loading state.                                                                   |
+| `setTransferError(transferId, error)`           | Set error, clears loading.                                                              |
+| `resetTransfer(transferId)`                     | Reverts data to originalData, clears dirty.                                             |
+| `clearTransfer(transferId)`                     | Removes transfer from store.                                                            |
+| `clearAll()`                                    | Clears all transfers.                                                                   |
+
+### Selector Factories
+
+| Function                                 | Description                                     |
+| ---------------------------------------- | ----------------------------------------------- |
+| `selectTransfer(transferId)`             | Selector for entire transfer state.             |
+| `selectTransferField(transferId, field)` | Selector for a single field value.              |
+| `selectTransferLoading(transferId)`      | Selector for loading state.                     |
+| `selectTransferError(transferId)`        | Selector for error state.                       |
+| `selectTransferDirty(transferId)`        | Selector for dirty state.                       |
+| `selectTransferIds`                      | Direct selector returning all transfer IDs.     |
+| `selectVersion`                          | Direct selector returning store version number. |
+
+### React Hooks
+
+| Hook                                                        | Description                                                                                                                                                                                                             |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useApplication()` / `useApplicationOptional()`             | Access application context (`ApplicationContextType`).                                                                                                                                                                  |
+| `useNavigation()` / `useNavigationOptional()`               | Access navigation context (page stack, dialogs).                                                                                                                                                                        |
+| `useDataStore()` / `useDataStoreOptional()`                 | Access `DataStore` instance.                                                                                                                                                                                            |
+| `useValidationContext()` / `useValidationContextOptional()` | Access validation context (field errors, touched state).                                                                                                                                                                |
+| `usePageContext()` / `usePageContextOptional()`             | Access current page metadata.                                                                                                                                                                                           |
+| `useRuntimeConfig()` / `useRuntimeConfigOptional()`         | Access runtime configuration (returns `RuntimeConfigContextType`).                                                                                                                                                      |
+| `useDispatch()` / `useDispatchOptional()`                   | Access action dispatch function.                                                                                                                                                                                        |
+| `useCustomizations()` / `useCustomizationsOptional()`       | Access customizations context (component overrides, interceptors, page customizations).                                                                                                                                 |
+| `useMuiPro()` / `useMuiProOptional()`                       | Access MUI Pro component context.                                                                                                                                                                                       |
+| `useSelectorSelection()` / `useSelectorSelectionOptional()` | Access selector dialog selection state.                                                                                                                                                                                 |
+| `useVisualBinding(element, attributeType?)`                 | **Core binding hook.** Subscribes to `DataStore` for attribute data. Resolves label, hidden, disabled, required, readOnly. Integrates `hiddenBy`, `enabledBy`, `requiredBy` dynamic behavior and validation for errors. |
+| `useElementVisibility(element)`                             | Evaluates runtime hidden state of any `VisualElement` via `hiddenBy` dynamic data, static `hidden`, and customization overrides. Safe outside `DataProvider`.                                                           |
+| `useElementDisabled(element)`                               | Evaluates runtime disabled state of any `VisualElement` via `enabledBy` dynamic data, static `disabled`, and customization overrides. `enabledBy` fully controls disabled when present. Safe outside `DataProvider`.    |
+| `useValidation(element)`                                    | Per-element validation. Returns `ValidationResult` with error (only for touched fields), touch/setError/clearError methods.                                                                                             |
+| `useFormValidation()`                                       | Alias for `useValidationContext()` — throws if outside `ValidationProvider`.                                                                                                                                            |
+| `useDataSelector(selector)`                                 | Generic selector subscription via `useSyncExternalStore`.                                                                                                                                                               |
+| `useTransferState(transferId)`                              | Convenience hook for full transfer state.                                                                                                                                                                               |
+| `useTransferField(transferId, field)`                       | Convenience hook for single field value.                                                                                                                                                                                |
+| `useTransferLoading(transferId)`                            | Convenience hook for transfer loading state.                                                                                                                                                                            |
+| `useTransferDirty(transferId)`                              | Convenience hook for transfer dirty state.                                                                                                                                                                              |
+| `useEditMode()`                                             | Derives edit mode from `PageContext` transfer ID + `DataStore` dirty state. No parameters — reads context directly.                                                                                                     |
+| `useRefreshSignal()`                                        | Returns current page-level refresh signal (0 when outside provider).                                                                                                                                                    |
+| `useComponentOverride(element)`                             | Returns custom component for element by sourceId, or null.                                                                                                                                                              |
+| `useComponentInterceptor(element)`                          | Returns intercepted component for element by `@type`, or null.                                                                                                                                                          |
+| `useSubThemeProvider(element)`                              | Returns the `SubThemeHook` for an element's `subTheme` property, or null.                                                                                                                                               |
+| `usePageActionOverrides(page, action)`                      | Returns action lifecycle overrides for an action on a page.                                                                                                                                                             |
+| `useVisualPropertyOverrides(element)`                       | Returns visual property overrides for an element.                                                                                                                                                                       |
+| `useResolvedPageActionOverrides()`                          | Returns all resolved action overrides for current page.                                                                                                                                                                 |
+| `useActionLifecycleOverrides(actionSourceId)`               | Returns lifecycle overrides for a specific action by sourceId.                                                                                                                                                          |
+| `useTypeaheadProvider(elementSourceId)`                     | Returns the typeahead provider for a text input, resolved from page-scoped `PageCustomization`.                                                                                                                         |
+| `useTableRowHighlighting(elementSourceId)`                  | Returns the `TableRowHighlightConfig[]` for a table element, resolved from page-scoped `PageCustomization`.                                                                                                             |
+| `useEnumOptionFilter(elementSourceId)`                      | Returns a wrapped filter function for enum input options. Subscribes to transfer data changes for reactive re-evaluation.                                                                                               |
+| `useDateValidationProps(elementSourceId)`                   | Returns `DateValidationProps` for a date/datetime input. Subscribes to transfer data changes for reactive re-evaluation.                                                                                                |
+| `useColumnCustomizers()`                                    | Returns all column customizer functions for the current page from `PageCustomization.columnCustomizers`.                                                                                                                |
+| `useItemContainerConfig(elementSourceId)`                   | Returns `ItemContainerConfig` for a table element from `PageCustomization.itemContainerConfigs`.                                                                                                                        |
+| `useDebouncedCallback(callback, delay?)`                    | Returns a debounced version of the callback (default 300ms). Used by autocomplete/typeahead.                                                                                                                            |
+| `getVisualElement(registry, sourceId)`                      | Utility function (not a hook) — looks up a `VisualElement` by sourceId from model registry.                                                                                                                             |
+
+### Additional Exported Components
+
+| Export                        | Kind      | Description                                                                                              |
+| ----------------------------- | --------- | -------------------------------------------------------------------------------------------------------- |
+| `PageActionOverridesProvider` | component | Calls registered page action hook and provides resolved overrides to descendants. Inside `PageProvider`. |
+| `VisualPropertiesProvider`    | component | Calls registered visual properties hook and provides overrides to descendants. Inside `PageProvider`.    |
+
+### Context Types
+
+| Type                           | Description                                                                                                                                                                                                                                    |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ApplicationContextType`       | `application`, `applications`, `actorName`, `switchActor`, `switchActorWithNavigation`                                                                                                                                                         |
+| `NavigationContextType`        | Extends `NavigationState`. Methods: `navigateTo`, `goBack`, `openDialog`, `closeDialog`, `replacePage`, `clearStack`, `dialog`, `canGoBack`                                                                                                    |
+| `PageStackEntry`               | `pageDefinition`, `params?`, `scrollPosition?`                                                                                                                                                                                                 |
+| `NavigationState`              | `pageStack`, `currentPage`, `dialogStack`                                                                                                                                                                                                      |
+| `DialogState`                  | `pageDefinition`, `size`, `params?`                                                                                                                                                                                                            |
+| `DialogCloseResultType`        | `"cancelled" \| "created" \| "updated" \| "deleted" \| "selected" \| "submitted"`                                                                                                                                                              |
+| `DialogCloseResult`            | Discriminated union for each result type (e.g., `{ type: "created"; isEager: boolean; data?: unknown }`)                                                                                                                                       |
+| `DialogCloseCallback`          | `(result?: DialogCloseResult) => void`                                                                                                                                                                                                         |
+| `PageContextType`              | `pageDefinition`, `transferId`, `params`, `isDialog`                                                                                                                                                                                           |
+| `ValidationContextType`        | Methods: `getError`, `setError`, `setErrors`, `touch`, `isTouched`, `clearErrors`, `clearError`, `validateAll`, `getAllErrors`, `isValid`                                                                                                      |
+| `ValidationState`              | `errors: Map<string, string>`, `touched: Set<string>`                                                                                                                                                                                          |
+| `RuntimeConfig`                | `features?: FeaturesConfig`, `muiProLicenseKey?`                                                                                                                                                                                               |
+| `FeaturesConfig`               | `guards?`, `forceShowTotalCountForLazyTables?`, `headerFilters?`                                                                                                                                                                               |
+| `RuntimeConfigContextType`     | `{ config: RuntimeConfig }`                                                                                                                                                                                                                    |
+| `DispatchFn`                   | `(action: Action) => Promise<unknown>` (uses `Action` from `@judo/actions`)                                                                                                                                                                    |
+| `DispatchContextType`          | `{ dispatch: DispatchFn }`                                                                                                                                                                                                                     |
+| `CustomizationsContextType`    | `version`, `getPageCustomization`, `getComponent`, `getComponentInterceptor`, `getSubThemeProvider`, `getRedirectHandler`, `getCustomRoutes`, `getMenuCustomizer`, `getFooterText`, `getHeroComponent`, `getSettingsPage`, `getGuestComponent` |
+| `MuiProContextType`            | `isProEnabled`, `getComponent(name)`                                                                                                                                                                                                           |
+| `SelectorSelectionContextType` | `selectedTransfersRef` (mutable ref), `ownerTransfer?`                                                                                                                                                                                         |
+| `VisualBindingResult`          | `value`, `onChange`, `error`, `hidden`, `disabled`, `required`, `label`, `readOnly`, `isLoading`, `isDirty`                                                                                                                                    |
+| `ValidationResult`             | `error`, `isTouched`, `touch()`, `setError()`, `clearError()`                                                                                                                                                                                  |
+| `EditModeResult`               | `isEditMode`, `transferId`                                                                                                                                                                                                                     |
+
+### Utilities
+
+| Export                | Kind     | Description                                                                                                                                                                                |
+| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `deepEqual(a, b)`     | function | Recursive deep equality comparison. Handles references, null/undefined, primitives, Arrays, Dates, and plain Objects. Used by `DataStore` for dirty tracking and selector cache stability. |
+| `DEFAULT_DEBOUNCE_MS` | constant | Default debounce delay (300ms) used by `useDebouncedCallback`.                                                                                                                             |
+
+## Key Patterns
+
+- **Mandatory + Optional hook pairs**: Every context exports both `useX()` (throws) and `useXOptional()` (returns null)
+- **External store with selector-based subscriptions**: `DataStore` is a plain class; hooks subscribe via `useSyncExternalStore` + selector functions for fine-grained re-renders
+- **Referential stability via deep-equal cache**: `useVisualBinding` and dynamic behavior hooks use ref-based caches with `deepEqual` to ensure referential stability for `useSyncExternalStore`
+- **Model-driven binding**: `useVisualBinding` bridges `VisualElement` to `DataStore` by resolving `attributeType.name` as the data field key
+- **Dynamic behavior via `*By` references**: `hiddenBy`/`enabledBy`/`requiredBy` properties on `VisualElement` reference `AttributeType` instances — hooks subscribe to the DataStore for those boolean fields and evaluate runtime visibility/disabled/required state
+- **`enabledBy` vs `hiddenBy` asymmetry**: `enabledBy` fully replaces the static `disabled` value when present; `hiddenBy` only overrides _to hidden_ (never clears static `hidden=true`)
+- **Dialog lifecycle with callbacks**: `openDialog` accepts an `onClose?: DialogCloseCallback` callback; dialog close callbacks stored in a ref-based stack (`dialogCloseCallbackStackRef`)
+- **React Router integration**: `NavigationProvider` optionally accepts `navigate` and `getRouteForPage` props
+- **`useSyncExternalStore` throughout**: `ApplicationProvider`, all data hooks, dynamic behavior hooks, and customization data-reactive hooks use React 18+ tear-free external store pattern
+- **RefreshSignalProvider**: Post-operation refresh signaling — ViewContainerRenderer increments a counter after operations; embedded components watch and re-dispatch their refresh logic
+- **Customizations with HMR support**: `CustomizationsProvider` stores config in a ref and uses a version counter; when customizations identity changes, version bumps and consumers re-render
+- **Selector selection via mutable ref**: `SelectorSelectionProvider` uses a `useRef` for selection state to avoid re-renders; value only read at dispatch time

package/dist/contexts/application-context.d.ts

@@ -0,0 +1,46 @@
+import { Application } from '@judo/model-api';
+import { ModelRegistry } from '@judo/model-loader';
+import { ReactNode } from 'react';
+/**
+ * Application context type.
+ */
+export interface ApplicationContextType {
+    /** Current active application (model required) */
+    application: Application;
+    /** All available applications (multi-actor) */
+    applications: Application[];
+    /** Switch to different actor */
+    switchActor: (actorName: string) => void;
+    /** Switch to different actor with navigation callback */
+    switchActorWithNavigation: (actorName: string, onSwitch?: (app: Application) => void) => void;
+    /** Current actor name */
+    actorName: string;
+}
+/**
+ * Hook to access application context.
+ * Throws if used outside provider or without model.
+ *
+ * @returns ApplicationContextType
+ * @throws Error if used outside ApplicationProvider
+ */
+export declare function useApplication(): ApplicationContextType;
+/**
+ * Hook to access application context (optional).
+ * Returns null if not within provider instead of throwing.
+ *
+ * @returns ApplicationContextType | null
+ */
+export declare function useApplicationOptional(): ApplicationContextType | null;
+/**
+ * Props for ApplicationProvider.
+ */
+export interface ApplicationProviderProps {
+    children: ReactNode;
+    registry: ModelRegistry;
+}
+/**
+ * Provider requiring loaded model.
+ * Uses useSyncExternalStore for proper subscription to registry changes.
+ */
+export declare function ApplicationProvider({ children, registry }: ApplicationProviderProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=application-context.d.ts.map

package/dist/contexts/application-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-context.d.ts","sourceRoot":"","sources":["../../src/contexts/application-context.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAoB,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,KAAK,SAAS,EAAgE,MAAM,OAAO,CAAC;AAErG;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,kDAAkD;IAClD,WAAW,EAAE,WAAW,CAAC;IACzB,+CAA+C;IAC/C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,gCAAgC;IAChC,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,yDAAyD;IACzD,yBAAyB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,IAAI,KAAK,IAAI,CAAC;IAC9F,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;CAClB;AAID;;;;;;GAMG;AACH,wBAAgB,cAAc,IAAI,sBAAsB,CASvD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,sBAAsB,GAAG,IAAI,CAEtE;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACxC,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,aAAa,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,wBAAwB,2CA4BnF"}