@praxisui/list

@praxisui/list — Configurable List/Cards Component

🔰 Exemplos / Quickstart

Para ver esta biblioteca em funcionamento em uma aplicação completa, utilize o projeto de exemplo (Quickstart):

• Repositório: https://github.com/codexrodrigues/praxis-ui-quickstart
• O Quickstart demonstra a integração das bibliotecas @praxisui/* em um app Angular, incluindo instalação, configuração e uso em telas reais.

Angular list/cards component for enterprise apps. Supports local or remote data, multiple layout variants, templating slots, actions, grouping and selection.

Install

npm i @praxisui/list

Peers (install in your app):

• @angular/core, @angular/common, @angular/material (Angular 16–20 compatible)
• rxjs (>=7 <9)
• @praxisui/core (icons, config storage, CRUD service)
• Optional: @praxisui/settings-panel (to open the in-app list configuration editor)

Quick Start

import { Component } from '@angular/core';
import { PraxisList } from '@praxisui/list';

@Component({
  selector: 'app-list-demo',
  standalone: true,
  imports: [PraxisList],
  template: `
    <praxis-list
      [config]="config"
      (itemClick)="onItem($event)"
      (actionClick)="onAction($event)"
      (selectionChange)="onSelection($event)"
    />
  `,
})
export class ListDemoComponent {
  config = {
    id: 'products-list',
    dataSource: { data: [
      { id: 1, name: 'Phone', price: 699, image: '/assets/phone.png', rating: 4.5 },
      { id: 2, name: 'Laptop', price: 1499, image: '/assets/laptop.png', rating: 4.8 },
    ] },
    layout: { variant: 'list', lines: 2, dividers: 'between' },
    selection: { mode: 'single', return: 'item', compareBy: 'id' },
    templating: {
      leading: { type: 'image', expr: '${item.image}', imageAlt: 'Product image' },
      primary: { type: 'text', expr: '${item.name}' },
      secondary: { type: 'currency', expr: '${item.price}|:USD' },
      meta: { type: 'rating', expr: '${item.rating}' },
      trailing: { type: 'chip', expr: 'In stock', color: 'primary' },
      features: [
        { icon: 'grade', expr: '${item.rating}' },
      ],
    },
    actions: [
      { id: 'favorite', icon: 'favorite', label: 'Like' },
      { id: 'buy', icon: 'shopping_cart', kind: 'button', buttonVariant: 'stroked', label: 'Buy' },
    ],
  } satisfies import('@praxisui/list').PraxisListConfig;

  onItem(e: any) { console.log('itemClick', e); }
  onAction(e: any) { console.log('actionClick', e); }
  onSelection(e: any) { console.log('selectionChange', e); }
}

Remote Data (resourcePath)

Provide dataSource.resourcePath to fetch data and (optionally) infer templating from backend schema.

<praxis-list [config]="{
  id: 'employees',
  dataSource: { resourcePath: 'employees', sort: ['name,asc'] },
  layout: { variant: 'list', lines: 2, groupBy: 'department' },
  templating: { primary: { type: 'text', expr: '${item.name}' } }
}"></praxis-list>

The component uses GenericCrudService from @praxisui/core when resourcePath is set. If no primary template is provided, it will try to infer templates using the backend schema once.

Layout Variants

• list (default): Material list with optional selection and dividers.
• cards: Card grid layout with the same templating slots.

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.

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'.
• 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.
• 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.

Actions

Configure contextual item actions via config.actions:

actions: [
  { id: 'edit', icon: 'edit', label: 'Edit' },
  { id: 'delete', icon: 'delete', color: 'warn', showIf: "${item.status} == 'active'" },
  { id: 'details', kind: 'button', buttonVariant: 'raised', label: 'Details' },
]

• 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').

Selection and Events

Selection (config.selection):

• mode: 'none' | 'single' | 'multiple'.
• compareBy: property used to track items.
• return: 'value' | 'item' | 'id' for selectionChange payload.
• Bind to an external FormControl via formControlName/formControlPath when using form.

Outputs:

• (itemClick): { item, index, section? }
• (actionClick): { actionId, item, index }
• (selectionChange): { mode, value, items, ids? }

License

Apache-2.0 — see LICENSE in this package or the repository root.