"use client"; import type React from "react"; import { useEffect, useMemo, useState } from "react"; import { FacetList } from "@/components/registry/blocks/facet-list"; import { PaginationControls } from "@/components/registry/blocks/pagination-controls"; import { QuickSearchList } from "@/components/registry/blocks/quick-search-list"; import { ResultControls, type ResultControlsProps, } from "@/components/registry/blocks/result-controls"; import { SectionHeading, type SectionHeadingProps, } from "@/components/registry/blocks/section-heading"; import type { CollectionControllerState, CollectionResultControlsOptions, } from "@/hooks/registry/use-collection-controller"; import { cn } from "@/lib/registry/cn"; /** * Opinionated listing layouts for consistent "stacked" configurations. * Use these when the content should not be displayed as a grid. */ export const itemListingLayouts = { stacked_md: "flex flex-col gap-4", stacked_sm: "flex flex-col gap-2", divided_md: "flex flex-col divide-y divide-border", } as const; export interface ItemListingProps { items: TItem[]; renderItem: (item: TItem, index: number) => React.ReactNode; /** * Stable key for each item. Required to avoid index keys since this is a * generic building block used across many lists. */ getKey: (item: TItem, index: number) => string; displayOptions?: { /** * Wrapper element for the list itself. * Use `as="ul"` and `itemAs="li"` for semantic lists. */ as?: React.ElementType; /** Wrapper element for each item. */ itemAs?: React.ElementType; /** Rendered when items is empty. */ empty?: React.ReactNode; }; behaviorOptions?: { /** Optional standardized heading (SectionWrapper heading mode). */ heading?: SectionHeadingProps; /** Optional collection-level controls (search/sort/filter/count). */ resultControls?: ResultControlsProps; collectionController?: { state: CollectionControllerState; resultControlsOptions?: CollectionResultControlsOptions; }; /** * Optional collapsible mode. When provided, each row renders as a disclosure * with explicit React state, summary from `renderItem`, and expanded body * from `renderDetails`. */ collapsible?: { renderDetails: (item: TItem, index: number) => React.ReactNode; summaryClassName?: string; detailsClassName?: string; defaultOpen?: boolean; }; pagination?: { enabled?: boolean; pageSize?: number; initialPage?: number; summaryClassName?: string; controlsClassName?: string; previousLabel?: string; nextLabel?: string; styleVariant?: "default" | "compact"; alignment?: "start" | "center" | "end"; showPageNumbers?: boolean; visiblePageLinkCount?: number; }; }; styleOptions?: { /** Optional wrapper class (around heading + list). */ wrapperClassName?: string; /** ClassName applied to the list wrapper. */ className?: string; /** ClassName applied to each item wrapper. */ itemClassName?: string; }; } type CollapsibleOptions = NonNullable< NonNullable["behaviorOptions"]>["collapsible"] >; /** * One disclosure row in collapsible mode: a summary button that toggles the * expanded details body. Extracted so the `ItemListing` map callback stays flat. */ function CollapsibleRow({ itemKey, isOpen, summaryNode, collapsible, item, originalIndex, onToggle, }: { itemKey: string; isOpen: boolean; summaryNode: React.ReactNode; collapsible: CollapsibleOptions; item: TItem; originalIndex: number; onToggle: () => void; }) { return (

{collapsible.renderDetails(item, originalIndex)}

); } type PaginationOptions = NonNullable< NonNullable["behaviorOptions"]>["pagination"] >; /** * Pagination footer. Routes page changes through the collection controller * when present, otherwise drives the component's local `currentPage` state. */ function ListPagination({ pagination, usesController, controllerPage, currentPage, totalPages, setPage, setCurrentPage, }: { pagination: PaginationOptions | undefined; usesController: boolean; controllerPage: number; currentPage: number; totalPages: number; setPage: (page: number) => void; setCurrentPage: React.Dispatch>; }) { return ( usesController ? setPage(Math.max(1, controllerPage - 1)) : setCurrentPage((prev) => Math.max(1, prev - 1)) } onNext={() => usesController ? setPage(Math.min(totalPages, controllerPage + 1)) : setCurrentPage((prev) => Math.min(totalPages, prev + 1)) } /> ); } /** * Wraps the rendered list in a filter sidebar (quick-search + facets) when the * result controls request sidebar placement; otherwise renders the list alone. */ function ListWithSidebar({ resultControls, children, }: { resultControls: ResultControlsProps | undefined; children: React.ReactNode; }) { const filters = resultControls?.filters; const showSidebar = (filters?.enabled ?? false) && filters?.placement === "sidebar" && ((filters?.facets?.length ?? 0) > 0 || (filters?.quickSearch?.enabled ?? false)); if (!showSidebar) return children; const showQuickSearch = (filters?.quickSearch?.enabled ?? false) && (filters?.quickSearch?.items?.length ?? 0) > 0; const showFacetList = (filters?.facets?.length ?? 0) > 0; return (

{children}

); } /** * Outer wrapper applied when a heading, wrapper class, or result controls are * present. A split-layout heading renders heading + (controls + list) in a * two-column grid; otherwise heading + controls + list stack vertically. */ function WrappedListing({ heading, resultControls, wrapperClassName, children, }: { heading: SectionHeadingProps | undefined; resultControls: ResultControlsProps | undefined; wrapperClassName: string | undefined; children: React.ReactNode; }) { const headingLayout = heading?.layout; const isSplitLayout = headingLayout === "split-start" || headingLayout === "split-end"; const controls = resultControls ? ( ) : null; if (heading && isSplitLayout) { const isRight = headingLayout === "split-end"; return (

{controls} {children}

); } return (

{heading ? : null} {controls} {children}

); } /** Resolve the slice of items to render for the current page, routing * through the collection controller when one is present. */ function resolveVisibleItems(args: { usesController: boolean; shouldPaginate: boolean; controller: CollectionControllerState | undefined; items: TItem[]; currentPage: number; pageSize: number; }): TItem[] { const { usesController, shouldPaginate, controller, items } = args; if (usesController) { if (!shouldPaginate) return controller?.filteredItems ?? []; return controller?.pagedItems ?? []; } if (!shouldPaginate) return items; const start = (args.currentPage - 1) * args.pageSize; return items.slice(start, start + args.pageSize); } /** Reconcile the open/closed disclosure map against the currently * visible items, preserving prior open state and defaulting new rows. */ function reconcileOpenMap( prev: Record, args: { visibleItems: TItem[]; shouldPaginate: boolean; currentPage: number; pageSize: number; getKey: (item: TItem, index: number) => string; defaultOpen: boolean; }, ): Record { const next: Record = {}; args.visibleItems.forEach((item, index) => { const originalIndex = args.shouldPaginate ? (args.currentPage - 1) * args.pageSize + index : index; const key = args.getKey(item, originalIndex); next[key] = prev[key] ?? args.defaultOpen; }); return next; } type PaginationModel = { currentPage: number; setCurrentPage: React.Dispatch>; controllerPage: number; usesController: boolean; shouldPaginate: boolean; pageSize: number; totalPages: number; setPage: (page: number) => void; }; /** Owns the page-state machine: local `currentPage` plus derived * pagination geometry, routed through the collection controller when * present. Clamps the local page into range when the page count shrinks. */ function usePaginationModel( items: TItem[], controller: CollectionControllerState | undefined, pagination: PaginationOptions | undefined, ): PaginationModel { const usesController = Boolean(controller); const controllerPage = controller?.currentPage ?? 1; const shouldPaginate = usesController ? (pagination?.enabled ?? true) : (pagination?.enabled ?? false); const pageSize = Math.max(1, pagination?.pageSize ?? 8); const totalPages = usesController ? (controller?.totalPages ?? 1) : shouldPaginate ? Math.ceil(items.length / pageSize) : 1; const [currentPage, setCurrentPage] = useState( Math.max(1, pagination?.initialPage ?? 1), ); const setPage = (page: number) => { if (controller) { controller.setCurrentPage(page); return; } setCurrentPage(page); }; useEffect(() => { if (usesController) return; if (!shouldPaginate) return; setCurrentPage((prev) => { if (prev < 1) return 1; if (prev > totalPages) return totalPages; return prev; }); }, [shouldPaginate, totalPages, usesController]); return { currentPage, setCurrentPage, controllerPage, usesController, shouldPaginate, pageSize, totalPages, setPage, }; } /** Render one row of the list, wrapping in a `CollapsibleRow` when * collapsible mode is on and applying the optional item wrapper. */ function ListRow({ item, originalIndex, itemKey, isOpen, renderItem, collapsible, ItemWrapper, itemClassName, onToggle, }: { item: TItem; originalIndex: number; itemKey: string; isOpen: boolean; renderItem: (item: TItem, index: number) => React.ReactNode; collapsible: CollapsibleOptions | undefined; ItemWrapper: React.ElementType; itemClassName: string | undefined; onToggle: () => void; }) { const summaryNode = renderItem(item, originalIndex); const node = collapsible ? ( ) : ( summaryNode ); if (itemClassName) { return {node}; } return <>{node}; } export function ItemListing({ items, renderItem, getKey, displayOptions, behaviorOptions, styleOptions, }: ItemListingProps) { const resolvedHeading = behaviorOptions?.heading; const resolvedWrapperClassName = styleOptions?.wrapperClassName; const resolvedAs = displayOptions?.as; const resolvedItemAs = displayOptions?.itemAs; const resolvedClassName = styleOptions?.className; const resolvedItemClassName = styleOptions?.itemClassName; const resolvedEmpty = displayOptions?.empty; const resolvedCollapsible = behaviorOptions?.collapsible; const resolvedCollectionController = behaviorOptions?.collectionController; const controller = resolvedCollectionController?.state; const resolvedResultControls = behaviorOptions?.resultControls ?? (controller ? controller.createResultControlsProps( resolvedCollectionController?.resultControlsOptions, ) : undefined); const resolvedPagination = behaviorOptions?.pagination; const { currentPage, setCurrentPage, controllerPage, usesController, shouldPaginate, pageSize, totalPages, setPage, } = usePaginationModel(items, controller, resolvedPagination); const visibleItems = useMemo( () => resolveVisibleItems({ usesController, shouldPaginate, controller, items, currentPage, pageSize, }), [controller, currentPage, items, pageSize, shouldPaginate, usesController], ); const hasItems = items.length > 0; const shouldWrap = Boolean( resolvedHeading || resolvedWrapperClassName || resolvedResultControls, ); const Wrapper = (resolvedAs ?? "div") as React.ElementType; const ItemWrapper = (resolvedItemAs ?? "div") as React.ElementType; const [openMap, setOpenMap] = useState>({}); useEffect(() => { if (!resolvedCollapsible) return; setOpenMap((prev) => reconcileOpenMap(prev, { visibleItems, shouldPaginate, currentPage, pageSize, getKey, defaultOpen: Boolean(resolvedCollapsible.defaultOpen), }), ); }, [ resolvedCollapsible, visibleItems, getKey, shouldPaginate, currentPage, pageSize, ]); if (!hasItems && !shouldWrap) return resolvedEmpty ?? null; const renderListRow = (item: TItem, index: number) => { const originalIndex = shouldPaginate ? (currentPage - 1) * pageSize + index : index; const key = getKey(item, originalIndex); const isOpen = openMap[key] ?? Boolean(resolvedCollapsible?.defaultOpen); const toggleRow = () => setOpenMap((prev) => ({ ...prev, [key]: !(prev[key] ?? Boolean(resolvedCollapsible?.defaultOpen)), })); return ( ); }; const list = hasItems ? (

{visibleItems.map(renderListRow)} {shouldPaginate ? ( ) : null}

) : ( (resolvedEmpty ?? null) ); const listWithSidebar = ( {list} ); if (!shouldWrap) return listWithSidebar; return ( {listWithSidebar} ); }

Item Listing

Showcase

Item Listing