@praxisui/core 9.0.4-rc.12 → 9.0.4-rc.14

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:
@@ -244,16 +242,10 @@ 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()],
 };
 ```
 
@@ -266,7 +258,7 @@ Resource action discovery also carries an optional `execution` contract. Consume
 `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()],