mvc-kit 2.12.0 → 2.12.1

package/src/react/components/CardList.test.tsx

@@ -0,0 +1,142 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { render, screen } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+import { CardList } from './CardList';
+
+interface Item {
+  id: string;
+  name: string;
+}
+
+const items: Item[] = [
+  { id: '1', name: 'Alice' },
+  { id: '2', name: 'Bob' },
+  { id: '3', name: 'Charlie' },
+];
+
+describe('CardList', () => {
+  it('renders items', () => {
+    render(
+      <CardList
+        items={items}
+        renderItem={(item) => <span>{item.name}</span>}
+      />,
+    );
+    expect(screen.getByText('Alice')).toBeDefined();
+    expect(screen.getByText('Bob')).toBeDefined();
+    expect(screen.getByText('Charlie')).toBeDefined();
+  });
+
+  it('renders as list layout by default', () => {
+    const { container } = render(
+      <CardList
+        items={items}
+        renderItem={(item) => <span>{item.name}</span>}
+      />,
+    );
+    const ul = container.querySelector('[data-component="card-list"]')!;
+    expect(ul.getAttribute('data-layout')).toBe('list');
+    expect(ul.getAttribute('role')).toBe('list');
+  });
+
+  it('renders as grid layout with CSS custom properties', () => {
+    const { container } = render(
+      <CardList
+        items={items}
+        renderItem={(item) => <span>{item.name}</span>}
+        layout="grid"
+        columns={4}
+        gap="2rem"
+      />,
+    );
+    const ul = container.querySelector('[data-component="card-list"]')!;
+    expect(ul.getAttribute('data-layout')).toBe('grid');
+    expect((ul as HTMLElement).style.display).toBe('grid');
+    expect((ul as HTMLElement).style.gridTemplateColumns).toContain('4');
+    expect((ul as HTMLElement).style.gap).toContain('2rem');
+  });
+
+  it('uses custom keyOf', () => {
+    const { container } = render(
+      <CardList
+        items={[{ uid: 'x', label: 'X' }]}
+        keyOf={(item: any) => item.uid}
+        renderItem={(item: any) => <span>{item.label}</span>}
+      />,
+    );
+    expect(screen.getByText('X')).toBeDefined();
+  });
+
+  it('renders empty state', () => {
+    render(
+      <CardList
+        items={[]}
+        renderItem={() => <span>item</span>}
+        renderEmpty={() => <p>No items found</p>}
+      />,
+    );
+    expect(screen.getByText('No items found')).toBeDefined();
+  });
+
+  it('renders loading state', () => {
+    render(
+      <CardList
+        items={items}
+        loading={true}
+        renderItem={(item) => <span>{item.name}</span>}
+        renderLoading={() => <p>Loading data...</p>}
+      />,
+    );
+    expect(screen.getByText('Loading data...')).toBeDefined();
+    expect(screen.queryByText('Alice')).toBeNull();
+  });
+
+  it('renders error state', () => {
+    render(
+      <CardList
+        items={items}
+        error="Something went wrong"
+        renderItem={(item) => <span>{item.name}</span>}
+        renderError={(err) => <p>Error: {err}</p>}
+      />,
+    );
+    expect(screen.getByText('Error: Something went wrong')).toBeDefined();
+    expect(screen.queryByText('Alice')).toBeNull();
+  });
+
+  it('applies className', () => {
+    const { container } = render(
+      <CardList
+        items={items}
+        renderItem={(item) => <span>{item.name}</span>}
+        className="my-list"
+      />,
+    );
+    expect(container.querySelector('.my-list')).not.toBeNull();
+  });
+
+  it('applies aria-label', () => {
+    const { container } = render(
+      <CardList
+        items={items}
+        renderItem={(item) => <span>{item.name}</span>}
+        aria-label="User list"
+      />,
+    );
+    const ul = container.querySelector('[data-component="card-list"]')!;
+    expect(ul.getAttribute('aria-label')).toBe('User list');
+  });
+
+  it('passes index to renderItem', () => {
+    render(
+      <CardList
+        items={items}
+        renderItem={(item, index) => <span>{index}: {item.name}</span>}
+      />,
+    );
+    expect(screen.getByText('0: Alice')).toBeDefined();
+    expect(screen.getByText('2: Charlie')).toBeDefined();
+  });
+});

package/src/react/components/CardList.tsx

@@ -0,0 +1,68 @@
+import type { ReactNode } from 'react';
+import type { AsyncStateProps } from './types';
+
+/** Props for the CardList headless component. */
+export interface CardListProps<T> extends AsyncStateProps {
+  items: T[];
+  renderItem: (item: T, index: number) => ReactNode;
+  keyOf?: (item: T) => string | number;
+  layout?: 'list' | 'grid';
+  columns?: number;
+  gap?: string;
+  renderEmpty?: () => ReactNode;
+  renderLoading?: () => ReactNode;
+  renderError?: (error: string) => ReactNode;
+  className?: string;
+  'aria-label'?: string;
+}
+
+const defaultKeyOf = (item: any) => item.id;
+
+/**
+ * Headless list/grid component with render-prop items.
+ * Renders a semantic `<ul>` with optional CSS grid layout.
+ */
+export function CardList<T>({
+  items,
+  renderItem,
+  keyOf = defaultKeyOf,
+  layout = 'list',
+  columns = 3,
+  gap = '1rem',
+  loading,
+  error,
+  renderEmpty,
+  renderLoading,
+  renderError,
+  className,
+  'aria-label': ariaLabel,
+}: CardListProps<T>) {
+  if (loading && renderLoading) return <>{renderLoading()}</>;
+  if (error && renderError) return <>{renderError(error)}</>;
+  if (items.length === 0 && renderEmpty) return <>{renderEmpty()}</>;
+
+  const style = layout === 'grid'
+    ? {
+        display: 'grid',
+        gridTemplateColumns: `repeat(var(--card-list-columns, ${columns}), 1fr)`,
+        gap: `var(--card-list-gap, ${gap})`,
+      } as const
+    : undefined;
+
+  return (
+    <ul
+      role="list"
+      data-component="card-list"
+      data-layout={layout}
+      className={className}
+      aria-label={ariaLabel}
+      style={style}
+    >
+      {items.map((item, index) => (
+        <li key={keyOf(item)} data-index={index}>
+          {renderItem(item, index)}
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/react/components/DataTable.md

@@ -0,0 +1,179 @@
+# DataTable
+
+Headless, unstyled table component with sort headers, row selection, and pagination support.
+
+---
+
+## When to Use
+
+Use DataTable for tabular data displays. It renders semantic HTML (`<table role="grid">`) with data attributes for styling hooks. No CSS included — bring your own styles.
+
+---
+
+## Basic Usage
+
+Pass helpers directly — DataTable detects them via duck-typing:
+
+```tsx
+import { DataTable } from 'mvc-kit/react';
+import type { Column } from 'mvc-kit/react';
+
+const columns: Column<User>[] = [
+  { key: 'name', header: 'Name', render: u => u.name, sortable: true },
+  { key: 'email', header: 'Email', render: u => u.email },
+  { key: 'role', header: 'Role', render: u => u.role, align: 'center' },
+];
+
+function UsersTable() {
+  const [state, vm] = useLocal(UsersVM, { search: '' });
+  return (
+    <DataTable
+      items={vm.items}
+      columns={columns}
+      sort={vm.sorting}
+      selection={vm.selection}
+      pagination={vm.pagination}
+      paginationTotal={vm.filteredCount}
+    />
+  );
+}
+```
+
+---
+
+## Props
+
+### Required
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `items` | `T[]` | Array of data items to render |
+| `columns` | `Column<T>[]` | Column definitions |
+
+### Column Definition
+
+```typescript
+interface Column<T> {
+  key: string;                                    // Unique identifier
+  header: ReactNode;                              // Header content
+  render: (item: T, index: number) => ReactNode;  // Cell renderer
+  sortable?: boolean;                             // Enable sort header
+  width?: string;                                 // Column width CSS
+  align?: 'left' | 'center' | 'right';           // Alignment
+}
+```
+
+### Optional
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `keyOf` | `(item: T) => string \| number` | `item => item.id` | Key extractor |
+| `pageSize` | `number` | — | Enables client-side pagination |
+| `sort` | `SortDescriptor[] \| SortingHelper` | — | Sort descriptors or Sorting helper |
+| `onSort` | `(key: string) => void` | — | Sort header click handler (not needed with SortingHelper) |
+| `selection` | `SelectionState \| SelectionHelper` | — | Selection state or Selection helper |
+| `pagination` | `PaginationState \| PaginationHelper` | — | Pagination state or Pagination helper |
+| `paginationTotal` | `number` | — | Total item count (required with PaginationHelper) |
+| `loading` | `boolean` | — | Loading state |
+| `error` | `string \| null` | — | Error message |
+| `className` | `string` | — | Container class |
+| `aria-label` | `string` | — | Table accessibility label |
+
+### Render Slots
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `renderEmpty` | `() => ReactNode` | Empty state |
+| `renderLoading` | `() => ReactNode` | Loading state |
+| `renderError` | `(error: string) => ReactNode` | Error state |
+| `renderSortIndicator` | `(props: SortHeaderProps) => ReactNode` | Custom sort indicator |
+| `renderRow` | `(item, index, cells) => ReactNode` | Custom row wrapper |
+| `renderPagination` | `(info: PaginationInfo) => ReactNode` | Pagination controls |
+
+---
+
+## Sort Headers
+
+Pass a `Sorting` helper directly, or use the object-literal form with `sort` + `onSort`:
+
+```tsx
+// Helper (recommended)
+sort={vm.sorting}
+
+// Object-literal (custom usage)
+sort={vm.sorting.sorts}
+onSort={key => vm.sorting.toggle(key)}
+```
+
+When sort is provided, sortable columns render `<button>` elements with `aria-sort` attributes:
+
+```tsx
+renderSortIndicator={({ active, direction }) => (
+  <span>{active ? (direction === 'asc' ? ' ↑' : ' ↓') : ''}</span>
+)}
+```
+
+---
+
+## Selection
+
+Pass a `Selection` helper directly, or use the object-literal form:
+
+```tsx
+// Helper (recommended) — DataTable passes allKeys to toggleAll automatically
+selection={vm.selection}
+
+// Object-literal (custom usage)
+selection={{
+  selected: vm.selection.selected,
+  onToggle: id => vm.selection.toggle(id),
+  onToggleAll: allKeys => vm.selection.toggleAll(allKeys),
+}}
+```
+
+DataTable computes `allKeys` from the visible items and passes them to `onToggleAll()` in both paths — you never need to reconstruct the key set yourself.
+
+---
+
+## Pagination
+
+Pass a `Pagination` helper directly (with `paginationTotal`), or use the object-literal form:
+
+```tsx
+// Helper (recommended)
+pagination={vm.pagination}
+paginationTotal={vm.filteredCount}
+
+// Object-literal (custom usage)
+pagination={{
+  page: vm.pagination.page,
+  total: vm.filteredCount,
+  onPageChange: p => vm.pagination.setPage(p),
+}}
+pageSize={vm.pagination.pageSize}
+```
+
+**Uncontrolled** (with `pageSize` only): Shows first page of items.
+
+```tsx
+renderPagination={info => (
+  <nav>
+    <button disabled={!info.hasPrev} onClick={info.goPrev}>Prev</button>
+    <span>Page {info.page} of {info.pageCount}</span>
+    <button disabled={!info.hasNext} onClick={info.goNext}>Next</button>
+  </nav>
+)}
+```
+
+---
+
+## Data Attributes
+
+| Attribute | Element | Description |
+|-----------|---------|-------------|
+| `data-component="data-table"` | Container `<div>` | Component identifier |
+| `data-sortable` | `<th>` | Present on sortable columns |
+| `data-sorted` | `<th>` | Present on actively sorted columns |
+| `data-selected` | `<tr>` | Present on selected rows |
+| `data-align` | `<th>`, `<td>` | Column alignment value |
+| `data-column="select"` | `<th>`, `<td>` | Selection checkbox column |