@judo/components 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,200 @@
+# @judo/components
+
+> Visual-model-driven MUI components for JUDO UI Runtime
+
+## Purpose
+
+The UI layer (Layer 5) of the JUDO runtime React framework. Interprets ECore XML models at runtime to produce React UI with **no code generation**. All components receive model objects (`PageContainer`, `Flex`, `Table`, `Input`, etc.) and render MUI-based UI from their properties.
+
+## Architecture Layer
+
+**Layer 5 (UI)** — the primary visual rendering package, consumed by `app-shell` and `standalone`.
+
+## Dependencies
+
+| Workspace         | External (Peer)                             |
+| ----------------- | ------------------------------------------- |
+| `@judo/model-api` | `@mui/material ^7`                          |
+| `@judo/core`      | `@mui/x-data-grid ^8`                       |
+| `@judo/i18n`      | `@mui/x-data-grid-pro ^8` (optional)        |
+| `@judo/actions`   | `@mui/x-date-pickers ^8`                    |
+| `@judo/feedback`  | `@mui/icons-material ^7`                    |
+| `@judo/test-ids`  | `@emotion/react ^11`, `@emotion/styled ^11` |
+|                   | `@mdi/font ^7`, `date-fns ^4`, `react ^19`  |
+
+## File Structure
+
+```
+src/
+├── index.ts                              # Barrel export
+├── styles.css                            # Force-full-width CSS for Stack layouts
+├── containers/
+│   ├── PageRenderer.tsx                  # Top-level page → container dispatcher
+│   ├── TableContainerRenderer.tsx        # TABLE container renderer
+│   ├── FormContainerRenderer.tsx         # FORM container renderer (create dialogs)
+│   └── ViewContainerRenderer.tsx         # VIEW container renderer
+├── dialogs/
+│   └── LinkSelectorDialog.tsx            # Relation selector dialog (DataGrid + filtering)
+├── errors/
+│   ├── ContainerErrorBoundary.tsx        # Error boundaries per container type
+│   └── index.ts                          # Barrel export
+├── hooks/
+│   ├── use-file-handling.tsx             # File download/upload/export hook
+│   ├── use-page-title.ts                # Page title resolution hook
+│   └── use-table-data.ts                # Table data management hook
+├── inputs/
+│   ├── InputRenderer.tsx                 # Input type dispatcher
+│   ├── TextInputComponent.tsx
+│   ├── NumericInputComponent.tsx
+│   ├── DateInputComponent.tsx
+│   ├── DateTimeInputComponent.tsx
+│   ├── TimeInputComponent.tsx
+│   ├── TextAreaComponent.tsx
+│   ├── CheckboxComponent.tsx
+│   ├── SwitchComponent.tsx
+│   ├── EnumerationComboComponent.tsx
+│   ├── EnumerationRadioComponent.tsx
+│   ├── EnumerationToggleButtonbarComponent.tsx
+│   ├── BinaryInputComponent.tsx
+│   └── PasswordInputComponent.tsx
+├── renderers/
+│   ├── VisualElementRenderer.tsx         # Central type dispatcher
+│   ├── FlexRenderer.tsx                  # Flex layout (Grid + Stack)
+│   ├── TableRenderer.tsx                 # MUI DataGrid wrapper
+│   ├── LinkRenderer.tsx                  # Autocomplete/relation field
+│   ├── TabControllerRenderer.tsx         # Tab layout
+│   ├── ButtonGroupRenderer.tsx           # Page-level button groups
+│   ├── InlineButtonGroupRenderer.tsx     # Inline dropdown button groups
+│   ├── StandaloneButtonRenderer.tsx      # Standalone navigation buttons
+│   ├── RowActionCell.tsx                 # Per-row action dropdown (internal)
+│   ├── SubThemeWrapper.tsx               # Theme override wrapper
+│   ├── FrameRenderer.tsx                 # Card/panel frame
+│   ├── IconRenderer.tsx                  # MDI icon renderer
+│   ├── PageHeader.tsx                    # Page title + actions
+│   └── TableToolbar.tsx                  # Custom DataGrid toolbar (internal)
+└── utils/
+    ├── alignment-mappers.ts             # Enum → CSS alignment mapping
+    ├── build-mask-string.ts             # Attribute/relation → _mask string builder
+    ├── build-query-customizer.ts        # DataGrid state → REST query (internal)
+    ├── destructive-action-utils.ts      # Destructive action detection + confirm options (internal)
+    ├── find-action-by-definition.ts     # Action ↔ definition matching (internal)
+    ├── find-on-init-action.ts           # OnInit action lookup
+    ├── find-visual-element.ts           # Tree search utilities
+    ├── flex-layout.ts                   # 12-column responsive grid math
+    ├── get-visible-buttons.ts           # Button visibility filtering (internal)
+    ├── mdi-alias-map.ts                 # MDI icon alias resolution (internal)
+    ├── mdi-alias-map.generated.ts       # Auto-generated (6,476 aliases)
+    ├── resolve-container-type.ts        # Container type resolution
+    ├── singleton-access.ts              # Singleton access page detection
+    ├── table-column-utils.ts            # Column type mapping (internal)
+    ├── table-filter-utils.ts            # DataGrid → REST filter conversion (internal)
+    └── table-sort-utils.ts             # Sort model conversion
+```
+
+## Exports Summary
+
+### Container Renderers
+
+| Component                         | Description                                                                                                                                                                                                                                                                                                                                  |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PageRenderer`                    | Top-level dispatcher. Lazy-loads container renderers by `ContainerType` (TABLE/FORM/VIEW) wrapped in error boundaries. Keys on `transferId` to force remount on navigation.                                                                                                                                                                  |
+| `TableContainerRenderer`          | TABLE container. Finds `Table` element, resolves Refresh action, dispatches onInit on mount (ref-guarded), renders `PageHeader` + `VisualElementRenderer`.                                                                                                                                                                                   |
+| `FormContainerRenderer`           | FORM container (create dialogs). Dispatches GetTemplate on mount for default values. Extracts create-dialog context. Sets `pageType: "FORM"` in dispatcher context.                                                                                                                                                                          |
+| `ViewContainerRenderer`           | VIEW container. Derives edit mode from transfer dirty state. Dispatches Refresh on mount when transfer available. Does NOT force readOnly based on edit mode. **Singleton access pages** (isAccess=true, isCollection=false): pre-fetches transfer via `refreshAccessRelation`, wraps children in `PageProvider` with resolved `transferId`. |
+| `resolveContainerType(container)` | Returns the container's explicit type or defaults to `TABLE`.                                                                                                                                                                                                                                                                                |
+
+### Error Boundaries
+
+| Component                                                        | Description                                                                                                                  |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `ContainerErrorBoundary`                                         | React class error boundary. Displays expandable MUI Alert with error message, element path, model JSON, and component stack. |
+| `TableErrorBoundary` / `FormErrorBoundary` / `ViewErrorBoundary` | Typed wrappers with specific labels.                                                                                         |
+
+### Visual Element Renderers
+
+| Component                   | Description                                                                                                                                                                                                                                                                                                                            |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `VisualElementRenderer`     | Central `@type` dispatcher → delegates to appropriate renderer. Checks component overrides and interceptors first. Unknown types log warning and return null.                                                                                                                                                                          |
+| `FlexRenderer`              | Flex layout: **Horizontal** = MUI Grid (12-column responsive), **Vertical** = MUI Stack (full-width). Supports size constraints and alignment.                                                                                                                                                                                         |
+| `TableRenderer`             | Full-featured MUI DataGrid wrapper. Manages row selection, filter panel, column building, column customizers (`useColumnCustomizers`), eager/non-eager modes, row actions, `forceShowTotalCount`. Supports CARD/TAG `representationComponent` via `useItemContainerConfig` — renders MUI Card grids or Chip lists instead of DataGrid. |
+| `LinkRenderer`              | MUI Autocomplete for relation/link elements with joined ButtonGroup. Supports typeahead, selector dialog, eager/lazy modes, and action buttons (View, Set, Unset, Create, Delete).                                                                                                                                                     |
+| `LinkSelectorDialog`        | Relation selector dialog with DataGrid table, filtering, and single-row selection for Link Set action.                                                                                                                                                                                                                                 |
+| `TabControllerRenderer`     | MUI Tabs with lazy tab panel rendering. Supports vertical/horizontal orientation.                                                                                                                                                                                                                                                      |
+| `ButtonGroupRenderer`       | Page/dialog-level button groups as horizontal MUI ButtonGroup. Filters visible buttons by edit mode. Supports group-level `hiddenBy` (via `useElementVisibility`) and per-button `enabledBy`/`hiddenBy` (via `useElementDisabled`/`useElementVisibility`).                                                                             |
+| `InlineButtonGroupRenderer` | Inline dropdown menu with IconButton + Menu + MenuItems. Supports `featuredActions` for inline buttons. Group-level `hiddenBy` and per-button `enabledBy`/`hiddenBy` dynamic behavior.                                                                                                                                                 |
+| `StandaloneButtonRenderer`  | Standalone Button elements (e.g., relation navigation buttons). Supports `hiddenBy`/`enabledBy` dynamic behavior, button style variants, confirmation dialogs for destructive actions.                                                                                                                                                 |
+| `SubThemeWrapper`           | Wraps children in a theme override based on model `subTheme` configuration and transfer data.                                                                                                                                                                                                                                          |
+| `FrameRenderer`             | MUI Card with optional header (icon + label).                                                                                                                                                                                                                                                                                          |
+| `IconRenderer`              | MDI webfont icon renderer with alias resolution and size support.                                                                                                                                                                                                                                                                      |
+| `PageHeader`                | Page title + page-level ButtonGroup.                                                                                                                                                                                                                                                                                                   |
+
+_Internal only (not exported): `RowActionCell` (per-row action dropdown used by `TableRenderer`), `TableToolbar` (custom DataGrid toolbar slot)._
+
+### Input Components (14)
+
+| Component                             | Model Type                   | MUI Component                                                       |
+| ------------------------------------- | ---------------------------- | ------------------------------------------------------------------- |
+| `InputRenderer`                       | —                            | Central dispatcher (uses `useVisualBinding`, `useEnumOptionFilter`) |
+| `TextInputComponent`                  | `TextInput`                  | `TextField`                                                         |
+| `NumericInputComponent`               | `NumericInput`               | `TextField` (type="number")                                         |
+| `DateInputComponent`                  | `DateInput`                  | `DatePicker`                                                        |
+| `DateTimeInputComponent`              | `DateTimeInput`              | `TextField` (type="datetime-local")                                 |
+| `TimeInputComponent`                  | `TimeInput`                  | `TimePicker`                                                        |
+| `TextAreaComponent`                   | `TextArea`                   | `TextField` (multiline)                                             |
+| `CheckboxComponent`                   | `Checkbox`                   | `MUI Checkbox` + `FormControlLabel`                                 |
+| `SwitchComponent`                     | `Switch`                     | `MUI Switch` + `FormControlLabel`                                   |
+| `EnumerationComboComponent`           | `EnumerationCombo`           | `Select` + `MenuItem`s                                              |
+| `EnumerationRadioComponent`           | `EnumerationRadio`           | `RadioGroup` + `FormControlLabel`s                                  |
+| `EnumerationToggleButtonbarComponent` | `EnumerationToggleButtonbar` | `ToggleButtonGroup` + `ToggleButton`s                               |
+| `BinaryInputComponent`                | `BinaryInput`                | File upload button + filename display                               |
+| `PasswordInputComponent`              | `PasswordInput`              | `TextField` with visibility toggle                                  |
+
+### Hooks
+
+| Hook                    | Description                                                                                                                                                                 |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useFileHandling()`     | File operations: download (attachment/inline preview), upload (two-step flow), JWT filename extraction, and export-to-file from API responses. Uses `useApi` + `useDialog`. |
+| `usePageTitle(options)` | Resolves page titles from `titleFrom` config: static label or dynamic attribute value with label fallback.                                                                  |
+| `useTableData(options)` | Manages table data for **eager** (client-side) and **non-eager** (server-side) modes. Sets DataGrid sort/filter/pagination modes accordingly.                               |
+
+### Exported Utility Functions
+
+| Function                                        | Description                                                                                            |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `mapMainAxisAlignment(alignment)`               | Enum → CSS `justifyContent` value.                                                                     |
+| `mapCrossAxisAlignment(alignment)`              | Enum → CSS `alignItems` value.                                                                         |
+| `mapAlignment(alignment)`                       | 2D Alignment enum → both CSS properties.                                                               |
+| `findOnInitAction(page, container)`             | Finds the onInit action for a container.                                                               |
+| `buildMaskString(params)`                       | Builds `_mask` string from attribute/relation arrays for REST queries.                                 |
+| `isSingletonAccessPage(page)`                   | Checks if page is a singleton access page (`RelationType` with `isAccess=true`, `isCollection=false`). |
+| `getSingletonAccessRelation(page)`              | Returns the `RelationType` for a singleton access page, or `undefined`.                                |
+| `resolveContainerType(container)`               | Returns the container's explicit type or defaults to `TABLE`.                                          |
+| `findVisualElementByType(root, type)`           | DFS search by `@type`.                                                                                 |
+| `findVisualElementById(root, id)`               | DFS search by `xmi:id`.                                                                                |
+| `findVisualElementBySourceId(root, sourceId)`   | DFS search by `sourceId`.                                                                              |
+| `flattenVisualElements(root)`                   | Pre-order tree flattening.                                                                             |
+| `calculateChildGridSize(element)`               | 12-column proportional sizing for child elements.                                                      |
+| `calculateHorizontalGridSize(element)`          | Responsive breakpoint configuration for horizontal flex.                                               |
+| `calculateVerticalGridSize()`                   | Always full-width (12 columns) for vertical flex.                                                      |
+| `calculateScaledSize(element)`                  | Scales element `col` relative to parent's column span.                                                 |
+| `isVerticalLayout(element)`                     | Checks if a Flex element has `VERTICAL` direction.                                                     |
+| `buildInitialSortModel(columns)`                | Builds initial DataGrid sort model from column definitions.                                            |
+| `buildInitialOrderBy(columns)`                  | Builds REST `_orderBy` from columns with sort configuration.                                           |
+| `convertSortModelToOrderBy(sortModel, columns)` | MUI sort model → REST format.                                                                          |
+| `extractFileNameFromToken(token, fallback)`     | Standalone JWT filename extraction (also available from `useFileHandling`).                            |
+
+_Internal utilities (not exported): `findActionByDefinition`, `buildQueryCustomizer`, `getVisibleButtons`, `resolveIconName`, `getColumnType`, `convertFilterModelToQueryCustomizer`, `isDestructiveAction`, `getDestructiveConfirmationOptions`._
+
+## Key Patterns
+
+- **Model-driven rendering**: All components receive model objects and render from their properties — no hardcoded layouts
+- **`@type` discriminator dispatch**: `VisualElementRenderer` and `InputRenderer` switch on `@type` to delegate to the correct renderer
+- **Action resolution via `findActionByDefinition`**: Buttons/containers match their inline `actionDefinition` against page `actions` by `xmi:id`
+- **Eager vs non-eager data**: Tables support client-side (DataGrid handles everything) and server-side (dispatch on sort/filter/pagination) modes
+- **Ref-guarded onInit dispatch**: All container renderers use `useRef` to prevent duplicate dispatches in StrictMode
+- **Context fallback pattern**: Components accept page/dispatch via props but fall back to context
+- **Lazy code splitting**: `PageRenderer` uses `React.lazy` for each container type with `Suspense`
+- **12-column responsive grid**: Flex layouts scale children proportionally with responsive breakpoints
+- **MDI icon alias resolution**: Build-time generated alias map (6,476 entries) enables runtime icon name resolution
+- **Singleton access page support**: ViewContainerRenderer detects singleton pages (isAccess=true, isCollection=false), pre-fetches transfer via `refreshAccessRelation`, and overrides `transferId` via nested `PageProvider` so `useVisualBinding` can find data in the store
+- **Runtime dynamic behavior**: Button renderers support `hiddenBy`/`enabledBy` model references via `useElementVisibility()` and `useElementDisabled()` hooks from `@judo/core`. Group-level visibility hides entire button groups; per-button visibility/disabled state is evaluated independently.