@praxisui/core 9.0.4-rc.9 → 9.0.4

package/README.md

@@ -8,7 +8,7 @@ Use this package directly when a host application or library needs Praxis UI typ
 
 - Recommend when: use it as the first dependency for shared Praxis UI contracts, metadata models, resource discovery, global actions, i18n, theme bridge, and dynamic widget runtime primitives.
 - Avoid when: a consuming app wants to redefine contracts owned by core, metadata starter, config starter, or component packages.
-- Pair with: Every runtime package in the @praxisui/* family.
+- Pair with: Every runtime package in the @praxisui/\* family.
 
 ## Official Links
 
@@ -40,13 +40,13 @@ Import the theme bridge after Angular Material and CDK overlay styles.
 Use `PraxisIconDirective` to normalize Material Icons and Material Symbols names.
 
 ```ts
-import { Component } from '@angular/core';
-import { MatIconModule } from '@angular/material/icon';
-import { PraxisIconDirective } from '@praxisui/core';
+import { Component } from "@angular/core";
+import { MatIconModule } from "@angular/material/icon";
+import { PraxisIconDirective } from "@praxisui/core";
 
 @Component({
   standalone: true,
-  selector: 'app-icons',
+  selector: "app-icons",
   imports: [MatIconModule, PraxisIconDirective],
   template: `
     <mat-icon [praxisIcon]="'mi:pending'"></mat-icon>
@@ -65,20 +65,12 @@ and `mss:` icon-family prefixes as `PraxisIconDirective`; unprefixed names keep
 the legacy Material Icons behavior.
 
 ```ts
-import { Component, signal } from '@angular/core';
-import { PraxisIconButtonComponent } from '@praxisui/core';
+import { Component, signal } from "@angular/core";
+import { PraxisIconButtonComponent } from "@praxisui/core";
 
 @Component({
   imports: [PraxisIconButtonComponent],
-  template: `
-    <button
-      type="button"
-      [praxisIconButton]="'mic'"
-      size="compact"
-      [pressed]="isListening()"
-      aria-label="Ditar pedido"
-    ></button>
-  `,
+  template: ` <button type="button" [praxisIconButton]="'mic'" size="compact" [pressed]="isListening()" aria-label="Ditar pedido"></button> `,
 })
 export class ComposerActionsComponent {
   readonly isListening = signal(false);
@@ -87,14 +79,14 @@ export class ComposerActionsComponent {
 
 Public inputs:
 
-| Input | Values | Default | Purpose |
-| --- | --- | --- | --- |
-| `praxisIconButton` | icon name or canonical family-prefixed icon | required | Glyph materialized inside the button |
-| `size` | `dense`, `compact`, `standard` | `standard` | Governed target, visible surface and glyph density |
-| `appearance` | `plain`, `filled` | `plain` | Transparent or emphasized action surface |
-| `presentation` | `icon`, `projected` | `icon` | Uses the named glyph or host-projected governed presentation |
-| `pressed` | `true`, `false`, `null` | `null` | Persistent toggle/listening state and native `aria-pressed`; `null` omits the attribute |
-| `busy` | boolean | `false` | Replaces the glyph with the canonical progress indicator and publishes `aria-busy` |
+| Input              | Values                                      | Default    | Purpose                                                                                 |
+| ------------------ | ------------------------------------------- | ---------- | --------------------------------------------------------------------------------------- |
+| `praxisIconButton` | icon name or canonical family-prefixed icon | required   | Glyph materialized inside the button                                                    |
+| `size`             | `dense`, `compact`, `standard`              | `standard` | Governed target, visible surface and glyph density                                      |
+| `appearance`       | `plain`, `filled`                           | `plain`    | Transparent or emphasized action surface                                                |
+| `presentation`     | `icon`, `projected`                         | `icon`     | Uses the named glyph or host-projected governed presentation                            |
+| `pressed`          | `true`, `false`, `null`                     | `null`     | Persistent toggle/listening state and native `aria-pressed`; `null` omits the attribute |
+| `busy`             | boolean                                     | `false`    | Replaces the glyph with the canonical progress indicator and publishes `aria-busy`      |
 
 The component defaults the native host to `type="button"`; an explicit host
 attribute still documents intent and prevents accidental form submission in
@@ -115,11 +107,11 @@ Praxis Material 3 semantic color tokens.
 
 Governed density matrix:
 
-| Size | Pointer target | Visible surface | Glyph | Intended use |
-| --- | ---: | ---: | ---: | --- |
-| `standard` | 44px | 40px | 22px | Primary and standalone icon actions |
-| `compact` | 44px | 36px | 20px | Composers, headers and frequent application actions |
-| `dense` | 36px | 32px | 18px | Secondary actions inside constrained editorial toolbars |
+| Size       | Pointer target | Visible surface | Glyph | Intended use                                            |
+| ---------- | -------------: | --------------: | ----: | ------------------------------------------------------- |
+| `standard` |           44px |            40px |  22px | Primary and standalone icon actions                     |
+| `compact`  |           44px |            36px |  20px | Composers, headers and frequent application actions     |
+| `dense`    |           36px |            32px |  18px | Secondary actions inside constrained editorial toolbars |
 
 On coarse pointers, `dense` automatically restores a 44px pointer target while
 keeping its 32px visible surface. Do not use `dense` for a primary action, an
@@ -137,11 +129,11 @@ the Core primitive owns presentation and native interaction only.
 `PraxisThemeSurfaceTokens` is the public semantic bridge for runtime surfaces. It deliberately avoids Material or MDC selectors, so a host can theme Praxis overlays, borders and focus states without patching component internals.
 
 ```ts
-import { buildPraxisThemeSurfaceCss } from '@praxisui/core';
+import { buildPraxisThemeSurfaceCss } from "@praxisui/core";
 
 const themeCss = buildPraxisThemeSurfaceCss({
-  surfaceOverlay: 'var(--app-overlay-surface)',
-  focusOutline: 'var(--app-focus-ring)',
+  surfaceOverlay: "var(--app-overlay-surface)",
+  focusOutline: "var(--app-focus-ring)",
 });
 ```
 
@@ -152,16 +144,16 @@ Apply the generated variables in the host stylesheet or define the `--praxis-the
 `ComponentMetadataRegistry` is the shared registry used by builders and runtime loaders to resolve component metadata.
 
 ```ts
-import { ComponentDocMeta, ComponentMetadataRegistry } from '@praxisui/core';
+import { ComponentDocMeta, ComponentMetadataRegistry } from "@praxisui/core";
 
 const metadata: ComponentDocMeta = {
-  id: 'app-widget',
-  selector: 'app-widget',
+  id: "app-widget",
+  selector: "app-widget",
   component: AppWidgetComponent,
-  friendlyName: 'App widget',
-  description: 'Host-owned widget.',
-  icon: 'widgets',
-  lib: 'app-host',
+  friendlyName: "App widget",
+  description: "Host-owned widget.",
+  icon: "widgets",
+  lib: "app-host",
 };
 
 registry.register(metadata);
@@ -174,12 +166,12 @@ Component-owned config editors and AI authoring manifests are declared on `Compo
 `DynamicWidgetPageComponent` renders `WidgetPageDefinition` documents.
 
 ```ts
-import { Component } from '@angular/core';
-import { DynamicWidgetPageComponent, WidgetPageDefinition } from '@praxisui/core';
+import { Component } from "@angular/core";
+import { DynamicWidgetPageComponent, WidgetPageDefinition } from "@praxisui/core";
 
 @Component({
   standalone: true,
-  selector: 'app-page',
+  selector: "app-page",
   imports: [DynamicWidgetPageComponent],
   template: `<praxis-dynamic-page [page]="page"></praxis-dynamic-page>`,
 })
@@ -187,10 +179,10 @@ export class PageComponent {
   page: WidgetPageDefinition = {
     widgets: [
       {
-        key: 'summary',
+        key: "summary",
         definition: {
-          id: 'app-widget',
-          inputs: { title: 'Summary' },
+          id: "app-widget",
+          inputs: { title: "Summary" },
         },
       },
     ],
@@ -201,6 +193,12 @@ export class PageComponent {
 
 Use `page.composition.links` for persisted wiring. `page.connections` is legacy/residual and should not be used for new pages or examples. Nested component ports should use `component-port` endpoints with `ref.nestedPath`.
 
+Page-owned business copy can use `page.i18n` plus explicit `PraxisTextValue`
+descriptors inside widget shells or nested widget inputs. The runtime resolves
+those descriptors only in its render projection, so the authored and persisted
+document keeps stable semantic keys. Plain strings remain untouched, and
+framework chrome continues to come from each library's i18n catalog.
+
 ## Resource Discovery
 
 `resourcePath` and `resourceKey` serve different purposes:
@@ -217,6 +215,8 @@ it must not infer authorization from a `canonicalOperations` boolean or discard
 
 `ResourceRecordOpenService` materializes the minimal `ResourceRecordOpenRef` published by governed analytics. It resolves the target resource catalog, loads the real item, follows its HATEOAS `surfaces` relation, requires the exact item surface to be available for the current context, and only then delegates to `ResourceSurfaceOpenAdapterService`. Consumers must not replace this flow with `${item.id}`, a copied surface path, a label match, or a prebuilt `surface.open` payload.
 
+When a discovered item surface publishes `relatedResource`, `ResourceSurfaceOpenAdapterService` delegates to `RelatedResourceSurfaceResolverService`. The resulting table targets the canonical child resource and receives the parent identity through `queryContext.filters`; it does not prefetch the item projection and rebuild a host-local table before opening. When the child surface publishes `childParentField`, related create actions seed that field through `actions[].form.initialValue`, and both create/update command policies project it into `groupedCommand.contextFields`. The field therefore remains in the schema-backed form and submit payload without rendering a redundant lookup for context the dossier already established. The materializer declares `openMode: "drawer"` but does not redefine drawer geometry: positioning, viewport height, focus, and close behavior remain owned by `@praxisui/crud`. This keeps the drawer responsive and preserves child operations, empty states, endpoint routing, and resource identity from the backend contract.
+
 ## Schema And Metadata
 
 Core exports schema and metadata infrastructure used by form, table, list, chart, CRUD, and page-builder packages:
@@ -244,29 +244,23 @@ For governed analytics cross-filtering, `bindings.primaryDimension.keyFilterFiel
 Global actions let widgets and shells request host-mediated work such as navigation, dialog, toast, analytics, API calls, or surface opening.
 
 ```ts
-import {
-  providePraxisGlobalActions,
-  providePraxisToastGlobalActions,
-} from '@praxisui/core';
+import { providePraxisGlobalActions, providePraxisToastGlobalActions } from "@praxisui/core";
 
 export const appConfig = {
-  providers: [
-    providePraxisGlobalActions(),
-    providePraxisToastGlobalActions(),
-  ],
+  providers: [providePraxisGlobalActions(), providePraxisToastGlobalActions()],
 };
 ```
 
 Use `GlobalActionRef` and the catalog helpers when declaring or validating action payloads. The host remains responsible for registered executors and policy.
 
-Resource action discovery also carries an optional `execution` contract. Consumers must materialize its interaction, idempotency, correlation, resource-version, selection, outcome and refresh policies instead of inferring command behavior from labels or HTTP methods. `ResourceActionOpenAdapterService` projects form-based actions into Dynamic Form inputs and fails closed when a required `If-Match` version cannot be supplied or bound at runtime.
+Resource action discovery also carries an optional `execution` contract. Consumers must materialize its interaction, idempotency, correlation, resource-version, selection, outcome and refresh policies instead of inferring command behavior from labels or HTTP methods. `ResourceActionOpenAdapterService` projects form-based actions into Dynamic Form inputs, uses transient schema-owned command layout, keeps the materialized host inputs authoritative over saved preferences, and fails closed when a required `If-Match` version cannot be supplied or bound at runtime.
 
 ## Collection Export
 
 `PraxisCollectionExportService` is the shared export contract used by table, list, and future collection components.
 
 ```ts
-import { providePraxisHttpCollectionExportProvider } from '@praxisui/core';
+import { providePraxisHttpCollectionExportProvider } from "@praxisui/core";
 
 export const appConfig = {
   providers: [providePraxisHttpCollectionExportProvider()],
@@ -297,7 +291,7 @@ Core exports:
 
 - shared services such as `GenericCrudService`, `GlobalConfigService`, `GlobalActionService`, `ResourceDiscoveryService`, `ComponentMetadataRegistry`, `PraxisJsonLogicService`, `LoadingOrchestratorService`
 - governed submit-error normalization through `ErrorMessageService`, preserving public `code`, `target`, `category`, and safe messages while keeping transport details out of UI fallbacks
-- tokens and providers for API URLs, global config, global actions, loading, i18n, settings panel bridge, surface drawer bridge, collection export, field selector registry, and overlay/layer scale
+- tokens and providers for API URLs, global config, global actions, loading, i18n, settings panel bridge, surface drawer bridge, collection export, field selector registry, overlay/layer scale, and the shared collection-search visual contract (`PRAXIS_COLLECTION_SEARCH_DEFAULTS`, `PRAXIS_COLLECTION_SEARCH_VARS`, `buildPraxisCollectionSearchCss`)
 - models for table config, fields, forms, rich content, editorial content, widget pages, global actions, resource discovery, domain knowledge/rules, analytics, query context, loading, and collection export
 - helpers for schema ids, ETag fetch, field mapping, config merge, validation, IDs, inline filter controls, global action refs, and form hooks
 - dynamic widget/page runtime components and metadata
@@ -305,6 +299,8 @@ Core exports:
 
 See the package `public-api.ts` for the full export list.
 
+Collection-search consumers must theme the semantic `--praxis-collection-search-*` variables instead of targeting Table or Dynamic Fields internals. The public radius token accepts square (`0`), intermediate (for example `8px`) and pill (`999px`) geometries; surface, text, outline, focus, density, typography and motion remain in the same shared contract.
+
 ## Notes
 
 - `@praxisui/core` centralizes shared Angular/runtime contracts, but backend metadata semantics are still defined by the appropriate backend starter.