@praxisui/core 9.0.0-beta.9 → 9.0.0-rc.1

package/README.md

@@ -58,6 +58,95 @@ export class IconsComponent {}
 
 Hosts should load the icon fonts they use. Without the classic Material Icons font, ligature names such as `clear` can render as visible text.
 
+Use `PraxisIconButtonComponent` for icon-only actions. It keeps the native
+`button` contract, centers the glyph, and preserves a 44px pointer target even
+when the visible surface is compact. It accepts the same `mi:`, `mso:`, `msr:`
+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';
+
+@Component({
+  imports: [PraxisIconButtonComponent],
+  template: `
+    <button
+      type="button"
+      [praxisIconButton]="'mic'"
+      size="compact"
+      [pressed]="isListening()"
+      aria-label="Ditar pedido"
+    ></button>
+  `,
+})
+export class ComposerActionsComponent {
+  readonly isListening = signal(false);
+}
+```
+
+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` |
+
+The component defaults the native host to `type="button"`; an explicit host
+attribute still documents intent and prevents accidental form submission in
+templates that are later refactored. Every icon-only action must have an
+accessible name, normally `aria-label`, supplied by the host or its i18n layer.
+The consumer remains responsible for `[disabled]` while busy when repeated
+activation must be blocked.
+Use `presentation="projected"` when an icon-only action is presented by a
+governed component such as `PraxisRichContent`; the canonical button continues
+to own interaction geometry while the projected renderer owns content semantics.
+
+The component owns target, surface and glyph alignment. Consumers may set
+`--praxis-icon-button-filled-background` and
+`--praxis-icon-button-filled-foreground` to materialize a governed semantic
+tone, but should not override the target, surface or icon size variables.
+Hosts must load the font family selected by the icon prefix and provide the
+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 |
+
+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
+isolated destructive action, pagination, or a control that must remain easy to
+acquire under operational pressure. Density changes presentation only; it must
+not encode authorization, importance or business state.
+
+Migration from `mat-icon-button` should remove local MDC/Material internal
+variables and local width, height, padding or icon-margin fixes. Keep
+domain-specific state, labels and action authorization in the owning component;
+the Core primitive owns presentation and native interaction only.
+
+### Semantic theme surfaces
+
+`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';
+
+const themeCss = buildPraxisThemeSurfaceCss({
+  surfaceOverlay: 'var(--app-overlay-surface)',
+  focusOutline: 'var(--app-focus-ring)',
+});
+```
+
+Apply the generated variables in the host stylesheet or define the `--praxis-theme-*` variables directly. Runtime libraries consume these roles with Material-token fallbacks while their existing component-specific tokens remain supported.
+
 ## Component Metadata
 
 `ComponentMetadataRegistry` is the shared registry used by builders and runtime loaders to resolve component metadata.
@@ -121,6 +210,13 @@ Use `page.composition.links` for persisted wiring. `page.connections` is legacy/
 
 If the problem is URL or HTTP execution, start with `resourcePath`. If the problem is semantic discovery, surface/action context, or stable runtime identity, start with `resourceKey`.
 
+`ResourceCapabilitySnapshot.canonicalOperations` preserves structural support only.
+`operations` carries the current operation contract and availability for CRUD, query,
+options, stats, and export. The core keeps unknown operation IDs for forward compatibility;
+it must not infer authorization from a `canonicalOperations` boolean or discard denial metadata.
+
+`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.
+
 ## Schema And Metadata
 
 Core exports schema and metadata infrastructure used by form, table, list, chart, CRUD, and page-builder packages:
@@ -132,10 +228,16 @@ Core exports schema and metadata infrastructure used by form, table, list, chart
 - `x-ui.optionSource` models and serializers
 - `x-ui.analytics` models and `AnalyticsSchemaContractService`
 - `valuePresentation` models and resolver
+- `FieldPresentationConfig` for semantic read-only/list/table-cell presentation
 - form layout item models
 - JSON Logic models and runtime service
 
+For governed analytics cross-filtering, `bindings.primaryDimension.keyFilterField` is the public request field that receives the raw `bucket.key`. Consumers must preserve its type, verify the target request schema, and must not infer this field from the dimension name, display label, or backend property paths.
+
 `valuePresentation` is the shared display contract for scalar read-only values such as currency, number, date, datetime, time, percentage, and boolean.
+`presentation` is the shared semantic wrapper contract for presentation-capable consumers. It can request chip, badge, status or iconValue rendering while preserving the raw value used for filtering, sorting and export.
+
+`FieldPresentationConfig` is the shared semantic presentation contract for read-only surfaces that need a visual primitive around the value, such as `chip`, `badge`, `status`, `iconValue`, or `microVisualization`. It keeps business data in the original field and lets consumers map `tone`, `appearance`, `icon`, `tooltip`, and optional fixed `label` values to their own renderer and theme tokens.
 
 ## Global Actions
 
@@ -177,6 +279,12 @@ Without an HTTP provider, local CSV/JSON export uses loaded items. With the HTTP
 
 Core also exports shared AI authoring types, capability types, dynamic-page context packs, and domain catalog context packs used by component packages.
 
+## Component Config Authoring
+
+`DynamicWidgetPageComponent` treats the editor declared by `ComponentDocMeta.configEditor` as the canonical authoring surface for the **Configurar conteúdo** action. When the Settings Panel bridge is available, the host resolves any transient `contextResolver` evidence and opens that metadata-owned editor even if the live widget also exposes an internal settings shortcut. This keeps the action deterministic across widget loading states.
+
+Widget-local settings dispatch remains only a fallback when the canonical Settings Panel/editor is unavailable. Transient context and diagnostics are passed separately to the editor and must not be copied into persisted `definition.inputs`; the editor result owns the persisted `{ inputs }` round-trip.
+
 ## Domain Governance
 
 `DomainKnowledgeService` and `DomainRuleService` are shared clients for governed semantic decision flows exposed by `praxis-config-starter`. Runtime surfaces should treat materializations as derived projections of backend-governed decisions, not as frontend-owned business rules.
@@ -186,11 +294,12 @@ Core also exports shared AI authoring types, capability types, dynamic-page cont
 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
 - 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
-- UI helpers such as icon picker, empty state card, resource quick connect, schema viewer, and `PraxisIconDirective`
+- UI helpers such as icon picker, empty state card, resource quick connect, schema viewer, `PraxisIconDirective`, and `PraxisIconButtonComponent`
 
 See the package `public-api.ts` for the full export list.