@praxisui/list 10.0.0-rc.4 → 10.0.0-rc.40

package/README.md

@@ -116,8 +116,9 @@ configured adapter; an in-memory adapter does not imply remote persistence.
 ## Configuration Highlights
 
 - Layout variants: `list`, `cards`, `tiles`.
-- Runtime-active layout fields include `lines`, `dividers`, `groupBy`, `pageSize`, `density` and `model`.
-- Templating slots include `leading`, `primary`, `secondary`, `meta`, `trailing`, `features`, `sectionHeader` and `emptyState`.
+- Runtime-active layout fields include `lines`, `dividers`, `groupBy`, `pageSize`, `density`, `model`, `cardColumns` (`'auto' | 1 | 2 | 3 | 4`), `cardMinWidth` and `cardMinHeight`.
+- Templating slots include `leading`, `primary`, `secondary`, `meta`, `trailing`, `features`, `sectionHeader` and `emptyState`, with `templating.statusPosition` (`'inline' | 'top-right'`) for card/tile status badges.
+- Item style rules (`rules.itemStyles[]`) support semantic `tone` (`'neutral' | 'primary' | 'success' | 'warning' | 'danger' | 'muted'`), materializing M3 token classes (`.pdx-list-item--<tone>`) without requiring raw CSS.
 - Leading images delegated to Rich Content stay within their reserved track and retain their aspect ratio. Skin overrides are rendered in an instance-scoped style element, using the supplied CSP nonce; updates replace that element's content and destruction removes it. Appearance presets wrap within narrow editors.
 - In `layout.rowLayout`, canonical semantic slots keep the configured desktop grid and reflow into ordered, non-overlapping rows at narrow viewports; extended operational slots stack without requiring host CSS.
 - Template expressions use `${item.field}`. Currency/date/number templates can use config i18n defaults.
@@ -148,10 +149,37 @@ Its validity is combined with raw JSON and document/query validation; visiting
 another tab preserves the text, and Reset discards it explicitly. See
 [Surface consumer validation](../praxis-core/docs/surface-draft-consumers-validation-2026-09-08.md).
 
+## Page Builder Integration & Insertion Presets
+
+`@praxisui/list` integrates directly with the visual palette of `@praxisui/page-builder`. Register its canonical metadata during app bootstrap:
+
+```ts
+import { providePraxisListMetadata } from '@praxisui/list';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    providePraxisListMetadata(),
+  ],
+};
+```
+
+When opened in the Page Builder, the component palette discovers `praxis-list` and exposes three structured canonical insertion presets (`PRAXIS_LIST_INSERTION_PRESETS`), enabling 1-click drag-and-drop authoring:
+
+1. **Feed operacional (`operational-feed`)**: Real-time event and alert stream featuring `pill-soft` skin, status icons, timestamp metadata, and contextual severity chips.
+2. **Catálogo com avatares (`avatar-catalog`)**: Executive personnel or asset card directory with `elevated` skin, single selection, avatar/photo icons, role/department secondary text, and status badges.
+3. **Lista financeira de saldos (`financial-metrics`)**: Corporate balance and liquidity overview with `glass` skin, category subtitles, and formatted currency metric blocks.
+
+Each preset preconfigures `configPersistenceStrategy: 'input-first'` and `enableCustomization: true`, and supplies representative starter data for immediate visual verification on the canvas.
+
+In the visual editor (`Data` tab), the data source summary displays the active resolution mode (**Local / sample data**, **Remote resource (API)**, or **No data source configured**). When a preset or authored list includes `dataSource.data`, those local rows take precedence over `dataSource.resourcePath`. Clicking **Use remote resource (remove local data)** clears `dataSource.data` so the configured `resourcePath` becomes active and loads its schema fields; during the same editing session, **Restore local data** can recover the stashed sample rows before saving, while **Reset** reverts the editor to its initial configuration snapshot.
+
 ## Public API Snapshot
 
 The root `@praxisui/list` entrypoint exports `PraxisList`, `PraxisListConfig`, list data services, templating/rich-content/selection adapters, metadata provider, list i18n helpers, AI capabilities, `PRAXIS_LIST_AUTHORING_MANIFEST` and `PraxisListDocPageComponent`. It also preserves the public editor classes `PraxisListConfigEditor` and `PraxisListWidgetConfigEditor`, and the types `PraxisListWidgetEditorInputs` and `PraxisListWidgetEditorValue`. Hosts can import these names directly from `@praxisui/list`; generic authoring hosts should resolve the configured editor through component metadata.
 
+Compact list, card and tile presenters delegated to `PraxisRichContent` use its existing `layout="inline"`: row slots, leading/primary/secondary content, metadata, trailing/status badges and features retain their intrinsic content width. Empty-state regions, section headers and rich-content expansion documents keep block rendering. Keep this distinction in the canonical List renderer; do not compensate with consumer CSS or remove Rich Content document containment. A rendered badge label needs a nonzero visible box: DOM text alone does not prove that a compact presenter is readable. Validate these compositions in their real desktop and narrow Dialog/list hosts.
+
+
 ## Official Links
 
 - Documentation: https://praxisui.dev/components/list