useDocyrusAdaptiveCardItemList

Generate an array of Adaptive Card JSON payloads from a Docyrus field list + many records, and render them as a responsive grid, a stacked list, or a single Carousel card with the shared AdaptiveCard renderer.

Edit on GitHubEditllms.txt

Client Only

Installation

pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-adaptive-card-item-list

Required Packages(1 package)

pnpm add react

Overview

useDocyrusAdaptiveCardItemList is the list companion of useDocyrusAdaptiveCardItemDetail. You hand it a Docyrus field list + a list of records and it generates one Adaptive Card JSON payload per record (cards) — mapping Docyrus field types onto the Adaptive Cards element vocabulary — then renders them with the shared AdaptiveCard renderer.

Both hooks share the same backend-agnostic mapper, so a card looks identical whether it's shown alone (detail) or in a list. Four layouts are supported:

grid (default) — a responsive CSS grid of cards (auto-fill or fixed columns).
list — a single stacked column of cards.
carousel — one combined Adaptive Card whose Carousel pages are the per-record bodies.
table — one combined Adaptive Card whose Table has a field-label header row and one row per record (scalar fields become columns; images / rich-text / code are excluded). The table scrolls horizontally when it's wider than its container.

When a DocyrusTenantProvider is mounted, dates / numbers / currency are formatted with the tenant's preferences.

See useDocyrusAdaptiveCardItemDetail for the full field-type → element mapping and slot-detection rules.

Usage

Render a responsive grid of cards

'use client';

import { useDocyrusAdaptiveCardItemList } from '@docyrus/ui/hooks/use-docyrus-adaptive-card-item-list';

export function DealGallery({ fields, records }) {
  const { view } = useDocyrusAdaptiveCardItemList({
    fields,
    records,
    layout: 'grid',
    columns: 'flex',
    minCardWidth: 340
  });

  return view;
}

Per-card actions + scoped click handler

onItemAction receives the originating record and index, so one handler routes every card (not applied in carousel layout).

const { view } = useDocyrusAdaptiveCardItemList({
  fields,
  records,
  getItemActions: (record) => [
    { type: 'Action.OpenUrl', title: 'Open', url: `/deals/${record.id}` }
  ],
  onItemAction: (event, record) => {
    if (event.type === 'openUrl') router.push(event.url);
  }
});

Use the generated JSON array directly

const { cards, items } = useDocyrusAdaptiveCardItemList({ fields, records });

// `cards` is AdaptiveCardPayload[] — one per record
// `items` is [{ id, record, card }] if you need the record alongside its card
await syncToTeams(cards);

Carousel

const { view, carouselCard } = useDocyrusAdaptiveCardItemList({
  fields,
  records,
  layout: 'carousel'
});

// `carouselCard` is the single combined AdaptiveCardPayload (a Carousel).
return view;

Table

const { view, tableCard } = useDocyrusAdaptiveCardItemList({
  fields,
  records,
  layout: 'table'
});

// `tableCard` is the single combined AdaptiveCardPayload (a Table:
// header row = field labels, one row per record). Scrolls horizontally
// when wider than its container.
return view;

API Reference