@praxisui/list 1.0.0-beta.8 → 3.0.0-beta.0

package/README.md

@@ -1,7 +1,65 @@
+---
+title: "List"
+slug: "list-overview"
+description: "Visao geral do @praxisui/list com variantes de lista e cards, slots declarativos, acoes, agrupamento e selecao."
+doc_type: "reference"
+document_kind: "component-overview"
+component: "list"
+category: "components"
+audience:
+  - "frontend"
+  - "host"
+  - "architect"
+level: "intermediate"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "list"
+  - "cards"
+  - "slots"
+  - "selection"
+  - "actions"
+order: 40
+icon: "view_list"
+toc: true
+sidebar: true
+search_boost: 1.0
+reading_time: 10
+estimated_setup_time: 15
+version: "1.0"
+related_docs:
+  - "host-integration-guide"
+  - "consumer-integration-quickstart"
+keywords:
+  - "cards"
+  - "grouping"
+  - "selection"
+  - "templating"
+last_updated: "2026-03-07"
+---
+
 # @praxisui/list — Configurable List/Cards Component
 
+## Documentation
+
+- Official documentation: https://praxisui.dev
+- Quickstart reference app: https://github.com/codexrodrigues/praxis-ui-quickstart
+- Recommended for: list and card experiences with templating, actions, grouping and selection in enterprise apps
+
+## When to use
+
+- Exibir colecoes em formato de lista ou cards com a mesma base de configuracao
+- Habilitar agrupamento, acoes e selecao sem criar um componente bespoke por tela
+- Integrar dados locais ou remotos em experiencias de catalogo e backoffice
+
 Angular list/cards component for enterprise apps. Supports local or remote data, multiple layout variants, templating slots, actions, grouping and selection.
 
+## Customization Mode Contract
+
+- `enableCustomization` is the canonical public input for runtime customization mode.
+- Customization mode controls the in-app editor and AI assistant only. It does not change the list data mode.
+- New hosts and generated snippets should use `enableCustomization`.
+
 ## Install
 
 ```bash
@@ -13,6 +71,7 @@ Peers (install in your app):
 - `rxjs` (>=7 <9)
 - `@praxisui/core` (icons, config storage, CRUD service)
 - Optional: `@praxisui/settings-panel` (to open the in-app list configuration editor)
+- Optional: `@praxisui/dynamic-fields` (color picker used by the in-app editor)
 
 ## Quick Start
 
@@ -26,6 +85,7 @@ import { PraxisList } from '@praxisui/list';
   imports: [PraxisList],
   template: `
     <praxis-list
+      listId="products-list"
       [config]="config"
       (itemClick)="onItem($event)"
       (actionClick)="onAction($event)"
@@ -64,12 +124,85 @@ export class ListDemoComponent {
 }
 ```
 
+## Runtime Contract (Data Mode and Precedence)
+
+Effective data mode resolution follows `ListDataService.stream()`:
+
+1. if `dataSource.data` exists, local mode is used;
+2. else if `dataSource.resourcePath` exists and `GenericCrudService` is available, remote mode is used;
+3. otherwise, empty mode is used.
+
+Critical rule:
+- local data has precedence over remote when both `dataSource.data` and `dataSource.resourcePath` are present.
+
+Decision matrix (runtime today):
+
+| `dataSource.data` | `dataSource.resourcePath` | Resolved mode | Data pipeline | Main surface |
+| --- | --- | --- | --- | --- |
+| array | any value | local | local array only | list/cards/tiles |
+| missing/null | filled | remote | `/filter` with fallback `getAll()` on failure | list/cards/tiles + remote controls |
+| missing/null | missing/empty | empty | none | empty state |
+
+Important behavior:
+- pagination/search/sort controls from `ui.*` are rendered only when `dataSource.resourcePath` is defined.
+- remote mode uses `GenericCrudService.filter(query, pageable)` and falls back to `getAll()` when `/filter` fails.
+
+## Runtime Status Matrix (High-Impact Paths)
+
+| JSON path | Runtime status | Notes |
+| --- | --- | --- |
+| `dataSource.data` | Active | Local mode source. |
+| `dataSource.resourcePath` | Active | Remote mode source. |
+| `layout.virtualScroll` | Declared-only | Accepted in config/editor but no runtime binding yet. |
+| `layout.stickySectionHeader` | Declared-only | Accepted in config/editor but no runtime sticky behavior yet. |
+| `actions[].emitPayload` | Declared-only | Authoring field only; `actionClick` payload shape is fixed. |
+| `events.*` | Declared-only | Declarative mapping only; no dynamic event router in runtime. |
+| `a11y.highContrast` / `a11y.reduceMotion` | Declared-only | No visual/runtime enforcement yet. |
+
+## Pagina de documentacao viva (showcase completo)
+
+Para documentar o componente com exemplos live (layout, templating, selecao, acoes, skins e snippets),
+use o componente `praxis-list-doc-page`:
+
+```html
+<praxis-list-doc-page></praxis-list-doc-page>
+```
+
+```ts
+import { Component } from '@angular/core';
+import { PraxisListDocPageComponent } from '@praxisui/list';
+
+@Component({
+  selector: 'app-list-doc-host',
+  standalone: true,
+  imports: [PraxisListDocPageComponent],
+  template: `<praxis-list-doc-page />`,
+})
+export class ListDocHostComponent {}
+```
+
+Cobertura da pagina:
+- Variantes `list`, `cards`, `tiles`.
+- `density`, `lines`, `model`, `groupBy`, `dividers`.
+- Slots `leading`, `primary`, `secondary`, `meta`, `trailing`, `sectionHeader`, `emptyState`.
+- Tipos de template `text`, `icon`, `image`, `chip`, `rating`, `currency`, `date`, `html`.
+- Selecao (`none`, `single`, `multiple`) com `FormControl` externo.
+- Acoes com `showIf`, estilos `icon/button` e log de eventos.
+- Skins `elevated`, `pill-soft`, `glass`, `gradient-tile`, `custom`.
+- Snippets para host, config JSON e contrato remoto com `resourcePath`.
+
+## Persistência
+
+- `listId` é obrigatório para salvar/carregar configurações.
+- A chave usada no storage é `praxis-list-config-<component_id>` (via `ComponentKeyService`).
+- Use `componentInstanceId` quando houver múltiplas listas com o mesmo `listId` na mesma rota.
+
 ## Remote Data (resourcePath)
 
 Provide `dataSource.resourcePath` to fetch data and (optionally) infer templating from backend schema.
 
 ```html
-<praxis-list [config]="{
+<praxis-list listId="employees" [config]="{
   id: 'employees',
   dataSource: { resourcePath: 'employees', sort: ['name,asc'] },
   layout: { variant: 'list', lines: 2, groupBy: 'department' },
@@ -83,25 +216,51 @@ The component uses `GenericCrudService` from `@praxisui/core` when `resourcePath
 
 - `list` (default): Material list with optional selection and dividers.
 - `cards`: Card grid layout with the same templating slots.
+- `tiles`: Modern grid layout (image + title + meta), ideal for catalogs.
 
 Layout options (`config.layout`):
 - `lines`: 1 | 2 | 3 controls visible text lines.
 - `dividers`: 'none' | 'between' | 'all'.
 - `groupBy`: string key to group items; section headers can be templated via `templating.sectionHeader`.
-- `pageSize`, `virtualScroll`, `density`, `model` for advanced tuning.
+- `pageSize`, `density`, `model` are runtime-active.
+- `virtualScroll` and `stickySectionHeader` are currently declared-only (no runtime binding yet).
+
+## Config Merging Behavior
+Be aware that `applyConfigFromAdapter` replaces the entire `config` object. It does not perform a deep merge. Any local runtime overrides must be re-applied or managed carefully.
 
 ## Templating Slots
 
 Every slot accepts a `TemplateDef` with `type`, `expr`, optional `class` and `style`.
-- `leading`: 'icon' | 'image' with optional `badge`.
-- `primary`: 'text' | 'html' | 'date' | 'currency' | 'rating' | 'chip'.
+- `leading`: 'icon' | 'image' | 'text' | 'chip' | 'rating' | 'html' with optional `badge`.
+- `primary`: 'text' | 'html' | 'date' | 'currency'.
 - `secondary`: same as primary; shown when `lines > 1`.
-- `meta`: small text or chip/rating rendered inline or on the side (`metaPlacement`).
-- `trailing`: optional trailing text/chip.
+- `meta`: small text or chip/rating/icon/image rendered inline or on the side (`metaPlacement`).
+- `trailing`: optional trailing text/chip/icon/image.
 - `features`: array of `{ icon?, expr }` rendered below primary/secondary; control with `featuresVisible` and `featuresMode` ('icons+labels' | 'icons-only' | 'labels-only').
 
 Expressions use `${...}` to read from `item` (e.g., `${item.name}`). For `currency`, you may pass code/locale as `|:USD` or `|:USD:en-US`.
 
+### Rating props
+
+```json
+{
+  "templating": {
+    "meta": {
+      "type": "rating",
+      "expr": "${item.rating}",
+      "props": { "rating": { "max": 5, "size": 16, "color": "primary" } }
+    }
+  }
+}
+```
+
+### Colors
+
+`color` accepts:
+- theme colors (`primary`, `accent`, `warn`)
+- M3 tokens (`var(--md-sys-color-*)`)
+- custom colors (hex/rgb). The in-app editor offers a color picker.
+
 ## Actions
 
 Configure contextual item actions via `config.actions`:
@@ -115,8 +274,44 @@ actions: [
 ```
 
 - `kind`: 'icon' (default) or 'button'.
-- `showIf`: simple equality check is supported (left side must be an `${...}` expression).
-- `emitPayload`: choose what the action emits ('item' | 'id' | 'value').
+- `showIf`: simple equality check is supported. Syntax: `"${item.field} == 'value'"`. Left side must be an interpolation expression.
+- `emitPayload`: authoring field in the config/editor; current runtime `actionClick` emission does not change shape based on this field.
+
+### Global actions (command)
+
+```ts
+actions: [
+  {
+    id: 'favorite',
+    icon: 'favorite',
+    label: 'Favorite',
+    command: 'global:api.post',
+    globalPayload: { url: '/api/favorite', body: { id: '${item.id}' } }
+  }
+]
+```
+
+When `command` is set, `actionClick` is **not emitted** by default. Use `emitLocal: true` to emit both.
+
+### Confirmation and loading
+
+```ts
+actions: [
+  {
+    id: 'delete',
+    icon: 'delete',
+    label: 'Delete',
+    command: 'global:api.patch',
+    showLoading: true,
+    confirmation: {
+      title: 'Confirm deletion',
+      message: 'Are you sure you want to delete this item?',
+      type: 'danger',
+    },
+    globalPayload: { url: '/api/items/${item.id}', body: { active: false } },
+  }
+]
+```
 
 ## Selection and Events
 
@@ -131,6 +326,25 @@ Outputs:
 - `(actionClick)`: `{ actionId, item, index }`
 - `(selectionChange)`: `{ mode, value, items, ids? }`
 
+## Known limitations and mismatches
+
+1. `layout.virtualScroll` and `layout.stickySectionHeader` exist in the contract/editor, but have no runtime implementation.
+2. `actions[].emitPayload` is accepted in config/editor, but does not change current `actionClick` payload format.
+3. `events.*` is declarative-only (no runtime dynamic routing).
+4. `a11y.highContrast` and `a11y.reduceMotion` are declarative-only at this stage.
+5. In remote mode, `/filter -> getAll()` fallback can increase network cost on large datasets.
+
+## Source of truth
+
+- Canonical contract: `projects/praxis-list/src/lib/praxis-list.json-api.md`
+- Runtime implementation:
+  - `projects/praxis-list/src/lib/components/praxis-list.component.ts`
+  - `projects/praxis-list/src/lib/components/praxis-list.component.html`
+  - `projects/praxis-list/src/lib/services/list-data.service.ts`
+- Runtime specs:
+  - `projects/praxis-list/src/lib/components/praxis-list.component.spec.ts`
+  - `projects/praxis-list/src/lib/services/list-data.service.spec.ts`
+
 ## License
 
 Apache-2.0 — see `LICENSE` in this package or the repository root.