@net-advantage/jo-ui-card-list

Publishable generic card list. Bind a collection, supply a card template, and the list renders one card per item plus an optional dashed "new item" card (inset slightly from a full card). Cards flow left-to-right, then wrap (Z order), fill the container width, and sit on a transparent background. The list never scrolls itself; the host page or container owns scrolling.

A single click calls onSelect(item, index); pair it with selectedKey to highlight the selection.

Double-clicking a card (or pressing Enter/Space on it) opens a Dialog from @net-advantage/jo-ui-dialog in edit mode. The new item card opens it in create mode. The host supplies the dialog content.

<CardList
  items={journeyTypes}
  getItemKey={(item) => item.id}
  getItemLabel={(item) => item.title}
  renderItem={(item) => <JourneyTypeCard item={item} />}
  renderDialogContent={(context) =>
    context.mode === 'edit' ? <JourneyTypeForm value={context.item} /> : <JourneyTypeForm />
  }
  onDialogSubmit={(context) => save(context)}
  newItemLabel="New Type"
  showNewItem=true
/>

Return false from onDialogSubmit to keep the dialog open, for example after a validation failure.

Loading

Loading is off by default, so lists with local data never show it.

• loading replaces the cards with a jo-ui-shadow card skeleton that matches the grid and minCardWidth. Use loadingCount to set how many placeholders, or renderLoading to supply your own.
• dialogLoading shows a form skeleton inside the dialog and disables Save. Set it from onItemOpen / onNewItemOpen while the item's details are fetched.

MVVM

flowchart LR
  Props["CardListProps<TItem>"] --> ViewModel["useCardListViewModel"]
  Model["jo-ui-card-list.model.ts"] --> ViewModel
  ViewModel --> View["CardList.tsx"]
  View --> Dialog["jo-ui-dialog"]
  View -->|"loading"| Shadow["jo-ui-shadow"]
  View -->|"double click / Enter"| ViewModel
  ViewModel -->|"onSelect, onItemOpen, onNewItemOpen, onDialogSubmit, onDialogClose"| Host["Host application"]

| Layer | File | Responsibility | | --- | --- | --- | | Contract | jo-ui-card-list.types.ts | Generic props, dialog context, card and dialog view-models | | Model | jo-ui-card-list.model.ts | Class names, grid style, open keys, item entries, dialog title | | View-model | jo-ui-card-list.view-model.ts | Dialog state, open/close/submit handlers, card render state | | View | CardList.tsx | Render the grid, card frames, new item card, and dialog |

Models

flowchart TD
  Props["CardListProps<TItem>"] --> Entries["CardListEntry<TItem>[]"]
  Props --> Context["CardListDialogContext<TItem>"]
  Entries --> Cards["CardListCardViewModel[]"]
  Context --> DialogVm["CardListDialogViewModel"]
  Cards --> ViewModel["CardListViewModel"]
  DialogVm --> ViewModel

• CardListDialogContext is { mode: 'edit', item, index } or { mode: 'create' }.
• selectedKey marks one card with a selected border and aria-current.
• getItemClassName adds per-item classes to the card frame.
• minCardWidth (default 16rem) sets the minimum column width; columns grow to fill the row.
• getItemLabel names cards for assistive technology and titles the edit dialog. Without it, the card content is the accessible name and the title is Edit item.
• getDialogTitle overrides both dialog titles.

Structure

• src: runtime component, model, view-model, types, and companion tests.
• stories: Storybook stories for documentation and visual testing.

Publish footprint

This package publishes only:

• dist
• README.md

Stories and tests are excluded from the published artifact by design.