@lar-works/design-system 0.0.0-stage → 0.1.0

package/src/collections/ScrollRow.tsx

@@ -0,0 +1,90 @@
+import { ChevronRightIcon } from 'lucide-react';
+import type { ReactNode, Ref } from 'react';
+
+import { IconButton } from '../actions/IconButton';
+import { SkeletonLoader } from '../feedback/SkeletonLoader';
+import { Inline } from '../layout/Flow';
+
+const row = '-mx-1 flex snap-x scroll-px-1 gap-4 overflow-x-auto px-1 pt-1 pb-3';
+
+/** One row of wide cards, such as video stills, that scrolls sideways instead of wrapping. */
+export function ScrollRow({
+    ref,
+    label,
+    loading = false,
+    loadingLabel = label,
+    children,
+}: {
+    ref: Ref<HTMLUListElement>;
+    label: string;
+    loading?: boolean;
+    loadingLabel?: string;
+    children?: ReactNode;
+}) {
+    if (loading)
+        return (
+            <SkeletonLoader label={loadingLabel}>
+                <div className={row}>
+                    {Array.from({ length: 4 }, (_, index) => (
+                        <div key={index} className="flex w-64 shrink-0 flex-col gap-2">
+                            <SkeletonLoader.Shape presentation="video" />
+                            <SkeletonLoader.Shape width="wide" />
+                        </div>
+                    ))}
+                </div>
+            </SkeletonLoader>
+        );
+
+    return (
+        <ul ref={ref} aria-label={label} className={row}>
+            {children}
+        </ul>
+    );
+}
+
+/** `value` identifies the item, so its row can scroll to it. */
+export function ScrollRowItem({ value, children }: { value?: string; children: ReactNode }) {
+    return (
+        <li data-value={value} className="w-64 shrink-0 snap-start">
+            {children}
+        </li>
+    );
+}
+
+/** Each arrow is disabled at its end of the row, so both are while the row fits. */
+export function ScrollRowArrows({
+    onScroll,
+    canScrollBack,
+    canScrollForward,
+    backLabel,
+    forwardLabel,
+}: {
+    onScroll: (direction: 1 | -1) => void;
+    canScrollBack: boolean;
+    canScrollForward: boolean;
+    backLabel: string;
+    forwardLabel: string;
+}) {
+    return (
+        <Inline space="tight">
+            <IconButton
+                aria-label={backLabel}
+                title={backLabel}
+                disabled={!canScrollBack}
+                icon={
+                    <span className="flex rotate-180">
+                        <ChevronRightIcon />
+                    </span>
+                }
+                onClick={() => onScroll(-1)}
+            />
+            <IconButton
+                aria-label={forwardLabel}
+                title={forwardLabel}
+                disabled={!canScrollForward}
+                icon={<ChevronRightIcon />}
+                onClick={() => onScroll(1)}
+            />
+        </Inline>
+    );
+}

package/src/collections/VirtualGrid.tsx

@@ -0,0 +1,92 @@
+import { useWindowVirtualizer } from '@tanstack/react-virtual';
+import { type ReactNode, useEffect, useRef } from 'react';
+
+import { useCollectionViewport } from './CollectionViewport';
+import { useCollectionMotion } from './useCollectionMotion';
+
+interface VirtualGridProps {
+    count: number;
+    label: string;
+    onRangeChange: (startIndex: number, endIndex: number) => void;
+    renderItem: (index: number) => ReactNode;
+    textRows?: 1 | 2 | 3;
+    aspect?: 'square' | 'poster';
+    itemKey: (index: number) => string;
+    loading?: boolean;
+}
+
+export function VirtualGrid({
+    count,
+    label,
+    onRangeChange,
+    renderItem,
+    itemKey,
+    loading,
+    textRows = 2,
+    aspect = 'square',
+}: VirtualGridProps) {
+    const { scrollMargin, setCollectionElement, width } = useCollectionViewport();
+    const root = useRef<HTMLDivElement>(null);
+
+    useCollectionMotion(root);
+
+    const gap = 16;
+    const maxItemWidth = 170;
+    // Reserve the tallest grid until measured so history restoration is not clipped.
+    const layoutWidth = width || maxItemWidth * 2 + gap;
+    const columns = Math.max(2, Math.round((layoutWidth + gap) / (maxItemWidth + gap)));
+    const itemWidth = Math.min(maxItemWidth, Math.max(0, (layoutWidth - gap * (columns - 1)) / columns));
+    const rowHeight = itemWidth * (aspect === 'poster' ? 1.5 : 1) + 64 + (textRows - 2) * 16;
+    const rowCount = Math.ceil(count / columns);
+    const virtualizer = useWindowVirtualizer({
+        count: rowCount,
+        estimateSize: () => rowHeight,
+        overscan: 2,
+        scrollMargin,
+    });
+    const rows = virtualizer.getVirtualItems();
+    const startIndex = (rows[0]?.index ?? 0) * columns;
+    const endIndex = Math.min(count - 1, ((rows.at(-1)?.index ?? 0) + 1) * columns - 1);
+
+    useEffect(() => {
+        virtualizer.measure();
+    }, [columns, rowHeight, virtualizer]);
+
+    useEffect(() => {
+        if (count > 0) onRangeChange(startIndex, endIndex);
+    }, [count, endIndex, onRangeChange, startIndex]);
+
+    return (
+        <div ref={setCollectionElement} role="region" aria-label={label}>
+            <div
+                ref={root}
+                className="relative w-full"
+                aria-busy={loading}
+                style={{ height: virtualizer.getTotalSize() }}
+            >
+                {rows.flatMap((row) =>
+                    Array.from({ length: columns }, (_, column) => {
+                        const index = row.index * columns + column;
+                        const key = itemKey(index);
+
+                        return index < count ? (
+                            <div
+                                key={key}
+                                data-collection-key={key}
+                                data-index={index}
+                                className="absolute"
+                                style={{
+                                    left: column * (itemWidth + (layoutWidth - columns * itemWidth) / (columns - 1)),
+                                    top: row.start - scrollMargin,
+                                    width: itemWidth,
+                                }}
+                            >
+                                {renderItem(index)}
+                            </div>
+                        ) : null;
+                    }),
+                )}
+            </div>
+        </div>
+    );
+}

package/src/collections/VirtualList.tsx

@@ -0,0 +1,224 @@
+import { useWindowVirtualizer } from '@tanstack/react-virtual';
+import { ChevronDownIcon } from 'lucide-react';
+import { type CSSProperties, type ReactNode, useCallback, useEffect, useRef } from 'react';
+
+import { SkeletonLoader } from '../feedback/SkeletonLoader';
+import { tabbable } from '../foundations/KeyboardFocus';
+import { LinkOverlay } from '../typography/Link';
+import { columnBreakpoints, columnWidths } from './CollectionTokens';
+import { useCollectionViewport } from './CollectionViewport';
+import { DataRow } from './DataRow';
+import { useCollectionMotion } from './useCollectionMotion';
+
+export interface ListColumn<TItem> {
+    id: string;
+    label: string;
+    hideLabel?: boolean;
+    render: (item: TItem, visibleColumns: readonly string[], index: number) => ReactNode;
+    size: keyof typeof columnWidths;
+    priority?: keyof typeof columnBreakpoints;
+    placeholder?: (visibleColumns: readonly string[]) => ReactNode;
+    align?: 'right';
+}
+
+export interface VirtualListProps<TItem> {
+    columns: readonly ListColumn<TItem>[];
+    count: number;
+    itemAt: (index: number) => TItem | undefined;
+    itemLabel: (item: TItem) => string;
+    label: string;
+    onRangeChange: (startIndex: number, endIndex: number) => void;
+    onSelect?: (item: TItem) => void;
+    itemHref?: (item: TItem) => string | undefined;
+    onNavigate?: (href: string) => void;
+    placeholderAt?: (index: number) => ReactNode;
+    itemKey: (index: number) => string;
+    loading?: boolean;
+    section?: {
+        isStart: (item: TItem, index: number, previous: TItem | undefined) => boolean;
+        render: (item: TItem) => ReactNode;
+    };
+    sort?: string;
+    direction?: 'asc' | 'desc';
+}
+
+export function VirtualList<TItem>({
+    columns,
+    count,
+    itemAt,
+    itemLabel,
+    label,
+    onRangeChange,
+    onSelect,
+    itemHref,
+    onNavigate,
+    placeholderAt,
+    itemKey,
+    loading,
+    section,
+    sort,
+    direction = 'asc',
+}: VirtualListProps<TItem>) {
+    const { scrollMargin, setCollectionElement, width } = useCollectionViewport();
+    const root = useRef<HTMLDivElement>(null);
+    const attachRoot = useCallback(
+        (element: HTMLDivElement | null) => {
+            root.current = element;
+            setCollectionElement(element);
+        },
+        [setCollectionElement],
+    );
+
+    useCollectionMotion(root);
+
+    const visibleColumns = columns.filter(
+        (column) => column.id === sort || width >= columnBreakpoints[column.priority ?? 'primary'],
+    );
+    const visibleColumnIds = visibleColumns.map((column) => column.id);
+    const virtualizer = useWindowVirtualizer({
+        count,
+        // Layout belongs to stable catalog slots. Domain keys still identify
+        // mounted rows below; changing page data must not remeasure every slot.
+        // Section headers are measured with their mounted row wrappers.
+        estimateSize: () => 64,
+        overscan: 8,
+        scrollMargin,
+    });
+    const virtualItems = virtualizer.getVirtualItems();
+    const startIndex = Math.max(0, virtualItems[0]?.index ?? 0);
+    const endIndex = Math.min(count - 1, virtualItems.at(-1)?.index ?? 0);
+
+    useEffect(() => {
+        if (endIndex >= startIndex) onRangeChange(startIndex, endIndex);
+    }, [endIndex, onRangeChange, startIndex]);
+
+    return (
+        <div
+            role="table"
+            aria-label={label}
+            aria-busy={loading}
+            aria-rowcount={count + 1}
+            aria-colcount={visibleColumns.length}
+            className="border-base-300 bg-base-100 @container min-w-0 rounded-b-xl border-x border-b"
+            style={
+                {
+                    '--lar-list-columns': visibleColumns.map((column) => columnWidths[column.size]).join(' '),
+                } as CSSProperties
+            }
+        >
+            <div
+                role="rowgroup"
+                className="bg-base-50 sticky top-(--lar-header-height,0px) z-20 -mx-px -mt-(--lar-page-gutter,0px) pt-(--lar-page-gutter,0px)"
+            >
+                <div
+                    role="row"
+                    aria-rowindex={1}
+                    className="border-base-300 bg-base-100 box-content grid h-10 grid-cols-(--lar-list-columns) items-center gap-4 rounded-t-xl border px-3"
+                >
+                    {visibleColumns.map((column) => (
+                        <div
+                            key={column.id}
+                            role="columnheader"
+                            aria-sort={
+                                column.id === sort ? (direction === 'asc' ? 'ascending' : 'descending') : undefined
+                            }
+                            className={`flex min-w-0 items-center gap-1 text-xs font-medium ${column.align === 'right' ? 'justify-end' : ''} ${column.id === sort ? 'text-base-content' : 'text-base-content/50'}`}
+                        >
+                            <span className={column.hideLabel ? 'sr-only' : 'truncate'}>{column.label}</span>
+                            {column.id === sort ? (
+                                <span className={`size-3 shrink-0 ${direction === 'asc' ? 'rotate-180' : ''}`}>
+                                    <ChevronDownIcon />
+                                </span>
+                            ) : null}
+                        </div>
+                    ))}
+                </div>
+            </div>
+            <div
+                ref={attachRoot}
+                role="rowgroup"
+                className="relative w-full"
+                style={{ height: virtualizer.getTotalSize() }}
+            >
+                {virtualItems.map((item) => {
+                    const index = item.index;
+                    const key = itemKey(index);
+                    const value = itemAt(index);
+                    const href = value ? itemHref?.(value) : undefined;
+                    const placeholder = placeholderAt?.(index);
+                    const sectionStart = value && section?.isStart(value, index, itemAt(index - 1));
+
+                    return (
+                        <div
+                            key={key}
+                            data-collection-key={key}
+                            role="presentation"
+                            ref={virtualizer.measureElement}
+                            data-index={item.index}
+                            className="absolute top-0 left-0 w-full"
+                            style={{ top: item.start - scrollMargin }}
+                        >
+                            {sectionStart ? section?.render(value) : null}
+                            <div className="h-16">
+                                <DataRow rowIndex={item.index + 2} interactive={Boolean(value && (href || onSelect))}>
+                                    {placeholder ? (
+                                        <div
+                                            role="cell"
+                                            aria-colspan={visibleColumns.length}
+                                            className="col-span-full min-w-0"
+                                        >
+                                            {placeholder}
+                                        </div>
+                                    ) : (
+                                        visibleColumns.map((column, columnIndex) => {
+                                            const content = value
+                                                ? column.render(value, visibleColumnIds, index)
+                                                : undefined;
+
+                                            return (
+                                                <div
+                                                    key={column.id}
+                                                    role="cell"
+                                                    title={typeof content === 'string' ? content : undefined}
+                                                    className={`min-w-0 truncate text-sm ${column.align === 'right' ? 'text-right tabular-nums' : ''} ${column.id === sort || columnIndex === 0 ? 'text-base-content' : 'text-base-content/55'}`}
+                                                >
+                                                    {!value ? (
+                                                        (column.placeholder?.(visibleColumnIds) ?? (
+                                                            <SkeletonLoader.Shape width="wide" />
+                                                        ))
+                                                    ) : columnIndex === 0 ? (
+                                                        <>
+                                                            {href ? (
+                                                                <LinkOverlay
+                                                                    href={href}
+                                                                    onNavigate={onNavigate}
+                                                                    aria-label={itemLabel(value)}
+                                                                />
+                                                            ) : onSelect ? (
+                                                                <button
+                                                                    {...tabbable}
+                                                                    type="button"
+                                                                    data-slot="action-overlay"
+                                                                    aria-label={itemLabel(value)}
+                                                                    onClick={() => onSelect(value)}
+                                                                    className="focus-visible:outline-primary absolute inset-0 z-1 block w-full cursor-pointer rounded-md focus-visible:outline-2 focus-visible:-outline-offset-2"
+                                                                />
+                                                            ) : null}
+                                                            <div className="py-2">{content}</div>
+                                                        </>
+                                                    ) : (
+                                                        content
+                                                    )}
+                                                </div>
+                                            );
+                                        })
+                                    )}
+                                </DataRow>
+                            </div>
+                        </div>
+                    );
+                })}
+            </div>
+        </div>
+    );
+}

package/src/collections/index.ts

@@ -0,0 +1,10 @@
+export { CollectionSectionHeader } from './CollectionSectionHeader';
+export { CollectionState } from './CollectionState';
+export { DataRow } from './DataRow';
+export { ResultEmpty, ResultList, ResultRow, type ResultRowProps } from './ResultList';
+export { ScrollRow, ScrollRowArrows, ScrollRowItem } from './ScrollRow';
+export { useCollectionMotion } from './useCollectionMotion';
+export { revealInRow, useScrollRow } from './useScrollRow';
+export { VirtualGrid } from './VirtualGrid';
+export type { VirtualListProps } from './VirtualList';
+export { type ListColumn, VirtualList } from './VirtualList';

package/src/collections/useCollectionMotion.ts

@@ -0,0 +1,42 @@
+import { type RefObject, useLayoutEffect, useRef } from 'react';
+
+// Children identify their domain key and collection index, even across virtual
+// rows. Only mounted items are measured, keeping large catalogs bounded.
+export function useCollectionMotion(root: RefObject<HTMLDivElement | null>) {
+    const positions = useRef(new Map<string, { index: string | undefined; x: number; y: number }>());
+
+    useLayoutEffect(() => {
+        const next = new Map<string, { index: string | undefined; x: number; y: number }>();
+        const reducedMotion = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+
+        for (const element of root.current?.querySelectorAll<HTMLElement>('[data-collection-key]') ?? []) {
+            const key = element.dataset.collectionKey!;
+            const position = { index: element.dataset.index, x: element.offsetLeft, y: element.offsetTop };
+            const previous = positions.current.get(key);
+
+            next.set(key, position);
+
+            if (reducedMotion || !element.animate) continue;
+
+            // Initial measurement and resizing can change coordinates without
+            // changing order. Translate only to make room or reorder items.
+            if (
+                previous &&
+                previous.index !== position.index &&
+                (previous.x !== position.x || previous.y !== position.y)
+            ) {
+                element.getAnimations().forEach((animation) => animation.cancel());
+                element.animate(
+                    [
+                        { transform: `translate(${previous.x - position.x}px, ${previous.y - position.y}px)` },
+                        { transform: 'translate(0, 0)' },
+                    ],
+                    { duration: 280, easing: 'cubic-bezier(0.2, 0.8, 0.2, 1)' },
+                );
+            } else if (!previous) {
+                element.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 220, easing: 'ease-out' });
+            }
+        }
+        positions.current = next;
+    });
+}

package/src/collections/useScrollRow.ts

@@ -0,0 +1,64 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Scrolls `row` sideways, never its page, just far enough to show all of `item`. A snapping row settles on an item's
+ * start, so it scrolls to the first start that still shows all of `item`.
+ */
+export function revealInRow(row: HTMLElement, item: Element | null | undefined) {
+    if (!item) return;
+
+    const bounds = row.getBoundingClientRect();
+    const { left, right } = item.getBoundingClientRect();
+    const fit = right - bounds.right;
+    const style = getComputedStyle(row);
+    const padding = parseFloat(style.scrollPaddingLeft) || 0;
+    const starts =
+        style.scrollSnapType && style.scrollSnapType !== 'none'
+            ? Array.from(row.children, (child) => child.getBoundingClientRect().left - bounds.left - padding).filter(
+                  (start) => start >= fit,
+              )
+            : [];
+    const offset = left < bounds.left ? left - bounds.left : fit > 0 ? (starts.length ? Math.min(...starts) : fit) : 0;
+
+    if (offset) row.scrollTo({ left: row.scrollLeft + offset, behavior: 'smooth' });
+}
+
+/**
+ * Pairs a `ScrollRow` with `ScrollRowArrows` placed elsewhere, such as in its section header. `content` is a stable
+ * key for what the row shows, such as its item count, so the arrows re-measure when it changes.
+ */
+export function useScrollRow(content?: unknown) {
+    const [row, setRow] = useState<HTMLUListElement | null>(null);
+    const [ends, setEnds] = useState({ back: false, forward: false });
+
+    useEffect(() => {
+        const measure = () => {
+            const back = Boolean(row && row.scrollLeft > 1);
+            const forward = Boolean(row && row.scrollLeft + row.clientWidth < row.scrollWidth - 1);
+
+            setEnds((current) => (current.back === back && current.forward === forward ? current : { back, forward }));
+        };
+
+        measure();
+
+        if (!row) return;
+
+        const observer = new ResizeObserver(measure);
+
+        observer.observe(row);
+        row.addEventListener('scroll', measure, { passive: true });
+
+        return () => {
+            observer.disconnect();
+            row.removeEventListener('scroll', measure);
+        };
+    }, [row, content]);
+
+    return {
+        row,
+        setRow,
+        canScrollBack: ends.back,
+        canScrollForward: ends.forward,
+        scroll: (direction: 1 | -1) => row?.scrollBy({ left: direction * row.clientWidth * 0.8, behavior: 'smooth' }),
+    };
+}

package/src/display/ActivityCard.tsx

@@ -0,0 +1,76 @@
+import type { ReactNode } from 'react';
+
+import { SkeletonLoader } from '../feedback/SkeletonLoader';
+import { Inline, Stack } from '../layout/Flow';
+import { Text } from '../typography/Typography';
+
+interface ActivityCardProps {
+    loading?: boolean;
+    /** Cover, poster, or icon; the card gives it a fixed square to fill. */
+    artwork: ReactNode;
+    badges?: ReactNode;
+    /** A dense row of artwork and title with one subtitle, without the card chrome, detail, or badges. */
+    compact?: boolean;
+    detail?: string;
+    subtitle?: string;
+    title: string;
+}
+
+/** One thing happening on the server, whatever the media type: what it is, who has it, and how. */
+export function ActivityCard({
+    artwork,
+    badges,
+    compact = false,
+    detail,
+    subtitle,
+    title,
+    loading = false,
+}: ActivityCardProps) {
+    return (
+        <article
+            className={`flex min-w-0 items-center ${compact ? 'gap-3 rounded-lg p-2' : 'border-base-300 bg-base-100 gap-4 rounded-xl border p-3 shadow-xs'}`}
+        >
+            <div className={`shrink-0 ${compact ? 'size-10' : 'size-20'}`}>{artwork}</div>
+            <Stack space="tight" className="min-w-0 flex-1">
+                <Stack space="none" className="min-w-0">
+                    <Text as="span" variant="label" truncate title={title} loading={loading}>
+                        {title}
+                    </Text>
+                    {Object.entries(compact ? { subtitle } : { subtitle, detail }).map(([key, line]) =>
+                        line ? (
+                            <Text
+                                key={key}
+                                as="span"
+                                variant="caption"
+                                tone="muted"
+                                truncate
+                                title={line}
+                                loading={loading}
+                            >
+                                {line}
+                            </Text>
+                        ) : null,
+                    )}
+                </Stack>
+                {!compact && badges ? (
+                    <Inline wrap space="tight">
+                        {badges}
+                    </Inline>
+                ) : null}
+            </Stack>
+        </article>
+    );
+}
+
+export function ActivityCardSkeleton() {
+    return (
+        <ActivityCard
+            loading
+            artwork={<SkeletonLoader.Shape presentation="artwork" />}
+            title=""
+            subtitle=" "
+            detail=" "
+            badges={<SkeletonLoader.Shape width="wide" />}
+        />
+    );
+}