@praxisui/core 9.0.65 → 9.0.67

package/README.md

@@ -4,8 +4,119 @@ Shared contracts, tokens, services, metadata models, widget runtime primitives,
 
 Use this package directly when a host application or library needs Praxis UI types, global actions, metadata registries, schema clients, resource discovery, i18n, theme bridge, dynamic widget contracts, or shared runtime services.
 
+## Governed color palettes
+
+`materializeGovernedPaletteEntries(palette, purposes)` returns `MaterializedGovernedColorToken[]`, pairing each original `entry` with its resolved `color`. It preserves distinct token IDs even when CSS references/colors match, applies purpose filtering, and resolves fallback dependencies against the complete palette. Use this projection for identified swatches; do not zip color arrays to entries or infer identity from color equality. `materializeGovernedPaletteColors` remains the string-only projection of the same resolver.
+
+`GovernedColorPaletteService` is the canonical Angular client for color-palette projections published by Praxis Config. Published palettes carry a stable `familyKey`, an explicit `variant` identity and token-level `displayName`/`aliases`; incomplete legacy projections are rejected before caching. The service supports list/read/capabilities/preview, exact `list(familyKey)` queries, tenant/environment-isolated caching, conditional ETag revalidation and deterministic `version`/`etag` pins. Consumers may use names and aliases for presentation and discovery only: `paletteKey` and `tokenId` remain the persisted identities, and local metadata must not become a second source of governance. `GovernedColorTokenSelection` carries the exact palette/version/ETag/token observation beside the existing CSS-string field value; applications persist it only through an explicit domain field or mapping.
+
 ## LLM Recommendation Guide
 
+- `WidgetShellConfig.stickyHeader: true` retains the existing composition-derived
+  header within its widget during page scrolling. Omission/false keeps normal flow.
+  This differs from `bodyLayout: 'scroll'`, which governs body scrolling. No second
+  selection state, cloned header or page geometry is persisted.
+- Hosts with fixed chrome may set `--pdx-shell-sticky-header-offset` (CSS length,
+  default `0px`). Measure responsive chrome; do not assume a desktop-only height.
+  The lab uses a lifecycle-owned ResizeObserver for its functional heading.
+- Pinning releases at the widget boundary and is suspended during drag authoring,
+  collapse, hidden/disabled headers, expanded/fullscreen windows and scroll recovery.
+  This is not a global selected-record bar. Transparent/gradient header appearances
+  are painted over an opaque Material surface so data does not bleed through.
+  Keyboard focus is revealed below pinned chrome without changing its target.
+- Nested sticky shells add the measured height of sticky ancestor headers in the
+  same scrollport. This is transient geometry, not a saved offset or another
+  selection context. The stack stops at an independent scrolling container;
+  hidden/inactive headers cease contributing. Ancestor resize observation is
+  disconnected on destruction. Body scrolling/fill and window-layout rules apply
+  to the owning shell's direct body, not to every nested widget body.
+- An invisible shell (`kind: 'none'`) removes padding only from its own body.
+  Nested dashboard shells retain their authored body spacing. Hiding a header
+  with `showHeader: false` does not hide child headers or reset child spacing.
+- The Page Builder shell editor exposes the option. Existing saved layouts are
+  preserved; changing the source recipe does not silently migrate saved pages.
+
+- Coordinated manual resize: an unambiguous edge collision yields space from the
+  affected neighbors, preserving their opposite edges and respecting `minColSpan`,
+  `minRowSpan`, `lockSize` and `lockPosition`. It does not swap widgets or push a
+  chain of unrelated items. Diagonal/corner collisions with no unambiguous yielding
+  axis fail closed. Drag still uses the authored `block`/`swap` collision policy.
+  The actual widgets preview the valid distribution: green means available, amber
+  means minimum reached, red means the requested resize exceeds available space.
+  Icons, localized labels and live announcements accompany colors. Pointer release
+  applies the clamped distribution in one authoring event; Escape/cancel/capture loss
+  discards the entire preview. Feedback is transient, never serialized.
+  Author useful content-specific minimums and device overrides: the grid default of
+  one unit is a geometric limit, not a guarantee of readable enterprise content.
+  `autoRows: 'content'` measures content-driven tracks and uses independent pixel
+  `contentSize` for vertical resizing; `rowSpan` remains at least one. Resizing does not
+  imply automatic packing or moving unrelated widgets to a new row.
+
+- Widget Shell sizing: the shell includes its border inside the height reserved by its
+  host (`border-box`). Consumers do not need a global CSS reset to prevent a 2px overflow.
+  In a content-sized canvas, collapsing every tall widget in a shared row lets the next
+  row move upward; an expanded sibling still determines the shared row height. This is
+  CSS Grid reflow, not automatic compaction of authored fixed coordinates.
+
+- Dynamic Page resize presentation: selecting an unlocked widget in an editable grid
+  exposes eight edge/corner grips with 24px targets, themed focus and localized names.
+  The widget wrapper is keyboard focusable: focus selects it, Tab reaches its controls,
+  arrow keys resize, and Escape from a grip returns focus to the wrapper. Selection alone
+  does not change the document. Header drag remains the reorder entrypoint.
+
+  **More actions → Size…** offers width in grid columns and height in rows (fixed grid)
+  or pixels (content rows). An optional fixed-corner choice preserves the opposite edges.
+  Valid changes preview the same constrained distribution as the grips; Apply commits once,
+  Cancel/Escape discard the preview and restore widget focus. Out-of-range or blocked sizes
+  disable Apply rather than silently changing the requested numbers. The dialog identifies
+  whether the edit targets the base layout or a device override. Opening it preserves
+  automatic height; changing only width does not create a fixed height.
+
+  This menu is available with canvas authoring permission, including headerless widgets
+  and hosts that disable removal or shell configuration. Size-locked widgets disable it.
+  There is no dedicated Resize widget icon, global selector or detached directional panel.
+  The size action is transient and never persisted in page JSON. Shell actions can explicitly
+  use `placement: 'menu'` to stay in More actions even when header slots are free; the shell
+  editor and capability catalog share that value. Existing header/window placements retain
+  their behavior. All sizing reuses canonical canvas items, constraints and device targeting.
+  The editor offers exact grid-width presets (⅓, ½, ⅔, 100%) when the column count
+  can represent them without rounding. They change the width draft, preserve the fixed
+  corner and require Apply; an unavailable full width is rejected, never silently clamped.
+  After a committed resize, reopen Size… on that widget to undo the last resize in this
+  session, including yielded neighbors. Recovery restores prior device inheritance and
+  keeps unrelated content edits. It refuses changed affected geometry/limits, new collisions,
+  a different device scope or page identity. This is one-operation recovery, not a general
+  history or redo stack. Double-click shortcuts remain a usability-study hypothesis.
+
+- Dynamic Page gesture note: drag/resize previews belong to one primary pointer at a time.
+  Secondary buttons, non-primary touches and additional pointers do not replace an active
+  gesture. Cancellation or lost capture discards only transient canvas geometry, never a
+  snapshot of the whole page. External page/context/identity or authoring-mode changes cancel
+  the current gesture; a late pointerup cannot commit it. The same cleanup runs on destruction.
+  Cancellation is announced through `dynamicWidgetPage` in pt-BR/en-US, not as a collision.
+  This does not certify physical touch ergonomics or fixed-grid compaction.
+  No additional persisted layout or shell setting is required.
+
+- Widget Shell header note: identity and actions wrap according to the available card width,
+  including narrow cards inside wide canvases. Titles/subtitles retain up to two visible lines
+  and expose their complete localized content through Material tooltips. Icon action targets
+  remain 44px; resize affordances are a separate canvas concern. Existing `disabled` actions
+  stay disabled in overflow menus and cannot dispatch through the shell handler. This is UI
+  state enforcement, not backend authorization. No additional shell JSON field is required.
+
+- Widget Shell overlay note: expanded/fullscreen shells place the authored appearance over
+  an opaque backing from the existing Material surface token. Transparent inline shells
+  therefore remain transparent inline without exposing the obscured page through fullscreen.
+  The active overlay is programmatically focusable (`tabindex="-1"`), so blank-area clicks
+  retain a shell keyboard target without adding a sequential Tab stop. Escape received inside
+  the shell closes the overlay and restores its opening button when still connected.
+  Closing is deferred until event propagation completes: a child overlay that prevents the
+  default Escape action, including a Material select handled by the CDK body dispatcher,
+  keeps priority. The first Escape closes that select; the next closes the shell.
+  Deferred handling is ignored after shell destruction. These are presentation
+  changes only and do not rewrite saved shell appearance or canvas coordinates.
+  This is not a full modal accessibility or fixed-grid collapse/reflow certificate.
+
 - 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.
@@ -233,6 +344,62 @@ Hosts that maintain an authored source separately from runtime state should cons
 `pageChange` remains the compatibility stream for every canonical page update, including persistent
 runtime state; transient composition projections remain excluded from both outputs.
 
+Pointer drag/resize in the canvas snapshots rendered CSS Grid track sizes and gutters at gesture
+start. Content-sized rows are not treated as uniformly sized `rowUnit` rows. Horizontal resize
+snaps to columns; vertical resize in `autoRows: 'content'` authors the item's independent
+`contentSize: { heightPx, offsetTopPx? }`, while fixed rows still resize by row spans.
+Captured DOM measurements remain private; only the resulting authored size is persisted. A gesture that leaves
+the canonical placement unchanged does not emit an authoring update or persist the page.
+It announces that no adjustment was applied instead of claiming a successful resize.
+
+Content-row widgets with `contentSize` use the existing shell `bodyLayout: 'scroll'`
+as a render projection (child inputs and authored shell are unchanged). North handles
+preserve the bottom by changing height and top inset, and stop at the track origin.
+South handles release occupied space. Shared rows only shrink when no other occupant
+still needs that height. Collapsing temporarily clears size/inset; expanding restores them.
+`constraints.minHeightPx` (floor/default 160) and `maxHeightPx` govern this mode;
+grid `minRowSpan/maxRowSpan` remain row-occupancy constraints, not pixel limits.
+Content-height gestures additionally protect the measured header, shell padding/borders
+and up to 160px of scrollable body. Naturally shorter content may use less. This is
+a structural viewport reserve, not business-component UX certification. Measurements
+remain transient and do not overwrite authored constraints. An incompatible authored
+maximum blocks the gesture. The page-owned settings flow also supplies a transient
+validator through the existing Settings Panel input envelope. Apply/Save and reopen
+check the effective active-device height against the currently rendered shell; these
+observations never enter the page JSON. Changed columns, gap, width or shell styling
+require Automatic height first, then applying the geometry and reopening to measure.
+Unrendered device variants and editors opened without that runtime validator retain
+numeric validation only. Scroll-layout shells now observe late header/content and
+width changes. If the measured reserve no longer fits, the header temporarily joins
+the body's outer scroll flow, keeping content reachable inside the authored box.
+When space is sufficient again, normal body-only scrolling returns and the outer
+scroll resets to the header. This recovery neither increases height beyond an
+authored maximum nor writes constraints/configuration. It is suspended for collapse,
+expanded/fullscreen overlays and non-scroll layouts. Shared private measurement
+keeps gesture/editor checks and recovery consistent. This is an access safeguard,
+not a guarantee that a small viewport is ergonomically adequate; virtualized/custom
+child scroll containers still need their own proof.
+Keyboard resize moves vertically by 16px (Shift: 32px). Omit `contentSize` to inherit
+the base item; set `'auto'` to explicitly restore natural height in a device override.
+Fixed-row mode retains this preference but does not materialize it. Page Builder exposes
+these settings under **Page settings → Widget limits**. See the canvas RFC for the
+manual-validation boundary and remaining AI-manifest publication work.
+Own minimum/maximum and outer-grid clamping retain gesture evidence until feedback
+is resolved, so an over-limit request is not shown as green merely because its
+candidate was already clamped. That evidence remains transient, not page JSON.
+During pointer resize, the selected widget's message follows the pointer in a
+viewport-constrained CDK overlay rather than its potentially off-screen footer.
+The pane passes through pointer hits, does not take focus, and disappears on
+commit/cancel or authoring revocation. Neighbor badges remain attached to their
+widgets; the existing live announcement describes the affected distribution.
+This does not add multi-widget push/reflow or compact fixed-grid rows when a shell is collapsed.
+
+Canvas resize exposes 24px direct grips on the selected widget, plus 44px controls in
+the collapsed alternative group or on-demand contextual panel. All presentations reuse
+the canonical gesture runtime and `canvas.items`. Keyboard controls and themed feedback remain available.
+Physical-touch ergonomics and save/reopen persistence still
+require separate proof; successful local interaction is not an enterprise certification.
+
 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
@@ -397,3 +564,9 @@ Action-bearing components must use the semantic `--praxis-action-control-*` vari
 - Do not use consuming apps to redefine contracts owned by core, metadata starter, config starter, or a component package.
 - Prefer `composition.links` for page wiring and `valuePresentation` for scalar display semantics.
 - Use the official documentation for full recipes on schema flow, option sources, analytics, global actions, dynamic pages, and governed AI flows.
+
+### Catálogo no quick connect e isolamento do editor de página
+
+`ResourceQuickConnectComponent` apresenta recursos publicados em `/schemas/catalog` usando o seletor `pdx-material-select` registrado em `ComponentMetadataRegistry`. O host deve registrar os descritores oficiais de DynamicFields. O controle é inicializado pelo protocolo `setInputMetadata` e ControlValueAccessor; Core não importa a biblioteca de campos. A conexão avançada por rota continua disponível.
+
+O editor de configurações da página recebe uma cópia da definição autoral. Dados carregados e entradas transitórias dos widgets não devem virar configuração ao alterar o layout.