mvc-kit 2.12.0 → 2.12.1

package/src/react/components/DataTable.tsx

@@ -0,0 +1,267 @@
+import type { ReactNode } from 'react';
+import type {
+  Column,
+  SortHeaderProps,
+  SelectionState,
+  SelectionHelper,
+  PaginationState,
+  PaginationHelper,
+  PaginationInfo,
+  SortingHelper,
+  AsyncStateProps,
+} from './types';
+import { isSelectionHelper, isPaginationHelper, isSortingHelper } from './types';
+import type { SortDescriptor } from '../../Sorting';
+
+// ── Prop resolution helpers ──
+
+interface ResolvedSelection {
+  selected: ReadonlySet<any>;
+  onToggle: (key: any) => void;
+  onToggleAll: (allKeys: any[]) => void;
+}
+
+function resolveSelectionProp(selection: SelectionState | SelectionHelper): ResolvedSelection {
+  if (isSelectionHelper(selection)) {
+    return {
+      selected: selection.selected,
+      onToggle: (key) => selection.toggle(key),
+      onToggleAll: (allKeys) => selection.toggleAll(allKeys),
+    };
+  }
+  return {
+    selected: selection.selected,
+    onToggle: selection.onToggle,
+    onToggleAll: (allKeys) => selection.onToggleAll(allKeys),
+  };
+}
+
+function resolveSortProp(
+  sort: readonly SortDescriptor[] | SortingHelper,
+  onSort?: (key: string) => void,
+): { sorts: readonly SortDescriptor[]; onSort: ((key: string) => void) | undefined } {
+  if (isSortingHelper(sort)) {
+    return { sorts: sort.sorts, onSort: (key) => sort.toggle(key) };
+  }
+  return { sorts: sort, onSort };
+}
+
+function resolvePaginationProp(
+  pagination: PaginationState | PaginationHelper,
+  pageSize?: number,
+  paginationTotal?: number,
+): PaginationInfo {
+  if (isPaginationHelper(pagination)) {
+    const total = paginationTotal ?? 0;
+    const ps = pagination.pageSize;
+    const pageCount = Math.max(1, Math.ceil(total / ps));
+    const page = pagination.page;
+    return {
+      page,
+      pageCount,
+      total,
+      pageSize: ps,
+      hasPrev: page > 1,
+      hasNext: page < pageCount,
+      goToPage: (p) => pagination.setPage(p),
+      goPrev: () => pagination.setPage(page - 1),
+      goNext: () => pagination.setPage(page + 1),
+    };
+  }
+  const total = pagination.total;
+  const ps = pageSize ?? 10;
+  const pageCount = Math.max(1, Math.ceil(total / ps));
+  const page = pagination.page;
+  return {
+    page,
+    pageCount,
+    total,
+    pageSize: ps,
+    hasPrev: page > 1,
+    hasNext: page < pageCount,
+    goToPage: pagination.onPageChange,
+    goPrev: () => pagination.onPageChange(page - 1),
+    goNext: () => pagination.onPageChange(page + 1),
+  };
+}
+
+/** Props for the DataTable headless component. */
+export interface DataTableProps<T> extends AsyncStateProps {
+  items: T[];
+  columns: Column<T>[];
+  keyOf?: (item: T) => string | number;
+  pageSize?: number;
+
+  // Controlled state — accepts object-literal OR helper instance
+  sort?: readonly SortDescriptor[] | SortingHelper;
+  onSort?: (key: string) => void;
+  selection?: SelectionState | SelectionHelper;
+  pagination?: PaginationState | PaginationHelper;
+  paginationTotal?: number;
+
+  // Render slots
+  renderEmpty?: () => ReactNode;
+  renderLoading?: () => ReactNode;
+  renderError?: (error: string) => ReactNode;
+  renderSortIndicator?: (props: SortHeaderProps) => ReactNode;
+  renderRow?: (item: T, index: number, defaultCells: ReactNode) => ReactNode;
+  renderPagination?: (info: PaginationInfo) => ReactNode;
+
+  className?: string;
+  'aria-label'?: string;
+}
+
+const defaultKeyOf = (item: any) => item.id;
+
+function getAriaSortValue(key: string, sorts: readonly SortDescriptor[] | undefined): 'ascending' | 'descending' | 'none' {
+  if (!sorts) return 'none';
+  const desc = sorts.find(s => s.key === key);
+  if (!desc) return 'none';
+  return desc.direction === 'asc' ? 'ascending' : 'descending';
+}
+
+/**
+ * Headless data table with sort headers, selection checkboxes, and pagination slots.
+ * Renders semantic HTML (`<table>`) with data attributes for styling.
+ * Accepts Sorting/Selection/Pagination helpers directly via duck-typing.
+ */
+export function DataTable<T>({
+  items,
+  columns,
+  keyOf = defaultKeyOf,
+  pageSize,
+  sort,
+  onSort,
+  selection,
+  loading,
+  error,
+  pagination,
+  paginationTotal,
+  renderEmpty,
+  renderLoading,
+  renderError,
+  renderSortIndicator,
+  renderRow,
+  renderPagination,
+  className,
+  'aria-label': ariaLabel,
+}: DataTableProps<T>) {
+  if (loading && renderLoading) return <>{renderLoading()}</>;
+  if (error && renderError) return <>{renderError(error)}</>;
+  if (items.length === 0 && renderEmpty) return <>{renderEmpty()}</>;
+
+  // ── Resolve props ──
+  const resolvedSelection = selection ? resolveSelectionProp(selection) : undefined;
+
+  let resolvedSorts: readonly SortDescriptor[] | undefined;
+  let resolvedOnSort: ((key: string) => void) | undefined;
+  if (sort) {
+    const resolved = resolveSortProp(sort, onSort);
+    resolvedSorts = resolved.sorts;
+    resolvedOnSort = resolved.onSort;
+  }
+
+  let displayItems = items;
+  let paginationInfo: PaginationInfo | undefined;
+  if (pagination) {
+    paginationInfo = resolvePaginationProp(pagination, pageSize, paginationTotal);
+  } else if (pageSize && !pagination) {
+    displayItems = items.slice(0, pageSize);
+  }
+
+  // Selection: check indeterminate state
+  const allKeys = resolvedSelection ? displayItems.map(item => keyOf(item)) : [];
+  const allSelected = resolvedSelection && allKeys.length > 0 && allKeys.every(k => resolvedSelection!.selected.has(k));
+  const someSelected = resolvedSelection && allKeys.some(k => resolvedSelection!.selected.has(k));
+
+  return (
+    <div data-component="data-table" className={className}>
+      <table role="grid" aria-label={ariaLabel}>
+        <thead>
+          <tr>
+            {resolvedSelection && (
+              <th data-column="select">
+                <input
+                  type="checkbox"
+                  checked={!!allSelected}
+                  ref={(el) => {
+                    if (el) el.indeterminate = !!someSelected && !allSelected;
+                  }}
+                  onChange={() => resolvedSelection!.onToggleAll(allKeys)}
+                  aria-label="Select all"
+                />
+              </th>
+            )}
+            {columns.map((col) => {
+              const isSortable = col.sortable && resolvedOnSort;
+              const sortDesc = resolvedSorts?.find(s => s.key === col.key);
+              const isActive = !!sortDesc;
+              const sortIndex = resolvedSorts ? resolvedSorts.findIndex(s => s.key === col.key) : -1;
+
+              return (
+                <th
+                  key={col.key}
+                  data-sortable={isSortable ? '' : undefined}
+                  data-sorted={isActive ? '' : undefined}
+                  data-align={col.align}
+                  style={col.width ? { width: col.width } : undefined}
+                  aria-sort={isSortable ? getAriaSortValue(col.key, resolvedSorts) : undefined}
+                >
+                  {isSortable ? (
+                    <button type="button" onClick={() => resolvedOnSort!(col.key)}>
+                      {col.header}
+                      {renderSortIndicator?.({
+                        active: isActive,
+                        direction: sortDesc?.direction ?? 'asc',
+                        index: sortIndex,
+                        onToggle: () => resolvedOnSort!(col.key),
+                      })}
+                    </button>
+                  ) : (
+                    col.header
+                  )}
+                </th>
+              );
+            })}
+          </tr>
+        </thead>
+        <tbody>
+          {displayItems.map((item, index) => {
+            const key = keyOf(item);
+            const isSelected = resolvedSelection?.selected.has(key);
+
+            const cells = (
+              <>
+                {resolvedSelection && (
+                  <td data-column="select">
+                    <input
+                      type="checkbox"
+                      checked={!!isSelected}
+                      onChange={() => resolvedSelection!.onToggle(key)}
+                      aria-label={`Select row ${key}`}
+                    />
+                  </td>
+                )}
+                {columns.map((col) => (
+                  <td
+                    key={col.key}
+                    data-align={col.align}
+                  >
+                    {col.render(item, index)}
+                  </td>
+                ))}
+              </>
+            );
+
+            return (
+              <tr key={key} data-selected={isSelected ? '' : undefined}>
+                {renderRow ? renderRow(item, index, cells) : cells}
+              </tr>
+            );
+          })}
+        </tbody>
+      </table>
+      {paginationInfo && renderPagination?.(paginationInfo)}
+    </div>
+  );
+}

package/src/react/components/InfiniteScroll.md

@@ -0,0 +1,116 @@
+# InfiniteScroll
+
+IntersectionObserver wrapper for infinite loading patterns. Renders a sentinel element that triggers `onLoadMore` when it enters the viewport.
+
+---
+
+## When to Use
+
+Use InfiniteScroll to wrap a list (typically `CardList`) and automatically trigger page loads as the user scrolls. Pairs with the `Feed` helper for cursor tracking.
+
+---
+
+## Basic Usage
+
+```tsx
+import { InfiniteScroll, CardList } from 'mvc-kit/react';
+
+function PostFeed() {
+  const [, vm] = useLocal(FeedVM, {});
+  return (
+    <InfiniteScroll
+      hasMore={vm.hasMore}
+      loading={vm.async.loadMore?.loading}
+      onLoadMore={() => vm.loadMore()}
+      renderEnd={() => <p>No more posts</p>}
+    >
+      <CardList items={vm.items} renderItem={post => <PostCard post={post} />} />
+    </InfiniteScroll>
+  );
+}
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `hasMore` | `boolean` | *required* | Whether more data is available |
+| `onLoadMore` | `() => void` | *required* | Called when sentinel enters viewport |
+| `loading` | `boolean` | `false` | Suppresses sentinel while loading |
+| `threshold` | `number` | `0.1` | IntersectionObserver threshold |
+| `rootMargin` | `string` | `'0px'` | IntersectionObserver root margin |
+| `direction` | `'down' \| 'up'` | `'down'` | Scroll direction; `'up'` applies `column-reverse` for chat UIs |
+| `children` | `ReactNode` | *required* | Content to wrap |
+| `className` | `string` | — | Container class |
+
+### Render Slots
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `renderLoading` | `() => ReactNode` | Shown while loading |
+| `renderEnd` | `() => ReactNode` | Shown when no more data |
+
+---
+
+## How It Works
+
+1. When `hasMore` is `true` and `loading` is `false`, a hidden sentinel `<div>` is appended after `children`
+2. An IntersectionObserver watches the sentinel
+3. When the sentinel enters the viewport, `onLoadMore` is called
+4. While loading, the sentinel is removed to prevent duplicate calls
+5. When `hasMore` becomes `false`, the sentinel is removed and `renderEnd` is shown
+
+---
+
+## SSR Safety
+
+The component guards against missing `IntersectionObserver` (server-side rendering). No observer is created if `typeof IntersectionObserver === 'undefined'`.
+
+---
+
+## Data Attributes
+
+| Attribute | Element | Description |
+|-----------|---------|-------------|
+| `data-component="infinite-scroll"` | Container `<div>` | Component identifier |
+| `data-sentinel` | Sentinel `<div>` | The observed element (hidden, `aria-hidden="true"`) |
+
+---
+
+## Customizing the Trigger Point
+
+Use `rootMargin` to trigger loading before the user reaches the bottom:
+
+```tsx
+<InfiniteScroll
+  hasMore={vm.hasMore}
+  onLoadMore={() => vm.loadMore()}
+  rootMargin="0px 0px 200px 0px"  // Trigger 200px before visible
+>
+  {/* ... */}
+</InfiniteScroll>
+```
+
+---
+
+## Reverse Scroll (Chat UI)
+
+Use `direction="up"` for chat-style interfaces where new content loads at the top:
+
+```tsx
+<InfiniteScroll
+  hasMore={vm.feed.hasMore}
+  loading={vm.async.loadOlder.loading}
+  onLoadMore={() => vm.loadOlder()}
+  direction="up"
+  renderEnd={() => <p>Beginning of conversation</p>}
+>
+  {vm.messages.map(msg => <MessageBubble key={msg.id} message={msg} />)}
+</InfiniteScroll>
+```
+
+When `direction="up"`, the component applies `display: flex; flex-direction: column-reverse` so the sentinel appears at the visual top, triggering loads as the user scrolls up.
+
+**Note:** `column-reverse` inverts scrollbar direction and may cause layout quirks in some browsers. For production chat UIs with complex scroll behavior, consider wrapping the container with scroll-anchoring or manual scroll position management.

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

@@ -0,0 +1,218 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { render, screen, act } from '@testing-library/react';
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { InfiniteScroll } from './InfiniteScroll';
+
+// Mock IntersectionObserver
+let observerCallback: IntersectionObserverCallback;
+let mockObserve: ReturnType<typeof vi.fn>;
+let mockDisconnect: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  mockObserve = vi.fn();
+  mockDisconnect = vi.fn();
+
+  global.IntersectionObserver = class MockIntersectionObserver {
+    constructor(callback: IntersectionObserverCallback) {
+      observerCallback = callback;
+    }
+    observe = mockObserve;
+    unobserve = vi.fn();
+    disconnect = mockDisconnect;
+    root = null;
+    rootMargin = '';
+    thresholds = [] as number[];
+    takeRecords = () => [] as IntersectionObserverEntry[];
+  } as any;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('InfiniteScroll', () => {
+  it('renders children', () => {
+    render(
+      <InfiniteScroll hasMore={true} onLoadMore={() => {}}>
+        <p>Content</p>
+      </InfiniteScroll>,
+    );
+    expect(screen.getByText('Content')).toBeDefined();
+  });
+
+  it('renders sentinel when hasMore and not loading', () => {
+    const { container } = render(
+      <InfiniteScroll hasMore={true} onLoadMore={() => {}}>
+        <p>Content</p>
+      </InfiniteScroll>,
+    );
+    const sentinel = container.querySelector('[data-sentinel]');
+    expect(sentinel).not.toBeNull();
+    expect(sentinel!.getAttribute('aria-hidden')).toBe('true');
+  });
+
+  it('does not render sentinel when loading', () => {
+    const { container } = render(
+      <InfiniteScroll hasMore={true} loading={true} onLoadMore={() => {}}>
+        <p>Content</p>
+      </InfiniteScroll>,
+    );
+    expect(container.querySelector('[data-sentinel]')).toBeNull();
+  });
+
+  it('does not render sentinel when hasMore is false', () => {
+    const { container } = render(
+      <InfiniteScroll hasMore={false} onLoadMore={() => {}}>
+        <p>Content</p>
+      </InfiniteScroll>,
+    );
+    expect(container.querySelector('[data-sentinel]')).toBeNull();
+  });
+
+  it('calls onLoadMore when sentinel intersects', () => {
+    const onLoadMore = vi.fn();
+    render(
+      <InfiniteScroll hasMore={true} onLoadMore={onLoadMore}>
+        <p>Content</p>
+      </InfiniteScroll>,
+    );
+
+    expect(mockObserve).toHaveBeenCalled();
+
+    // Simulate intersection
+    act(() => {
+      observerCallback(
+        [{ isIntersecting: true } as IntersectionObserverEntry],
+        {} as IntersectionObserver,
+      );
+    });
+
+    expect(onLoadMore).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not call onLoadMore when not intersecting', () => {
+    const onLoadMore = vi.fn();
+    render(
+      <InfiniteScroll hasMore={true} onLoadMore={onLoadMore}>
+        <p>Content</p>
+      </InfiniteScroll>,
+    );
+
+    act(() => {
+      observerCallback(
+        [{ isIntersecting: false } as IntersectionObserverEntry],
+        {} as IntersectionObserver,
+      );
+    });
+
+    expect(onLoadMore).not.toHaveBeenCalled();
+  });
+
+  it('renders loading slot when loading', () => {
+    render(
+      <InfiniteScroll
+        hasMore={true}
+        loading={true}
+        onLoadMore={() => {}}
+        renderLoading={() => <p>Loading...</p>}
+      >
+        <p>Content</p>
+      </InfiniteScroll>,
+    );
+    expect(screen.getByText('Loading...')).toBeDefined();
+  });
+
+  it('renders end slot when hasMore is false', () => {
+    render(
+      <InfiniteScroll
+        hasMore={false}
+        onLoadMore={() => {}}
+        renderEnd={() => <p>No more items</p>}
+      >
+        <p>Content</p>
+      </InfiniteScroll>,
+    );
+    expect(screen.getByText('No more items')).toBeDefined();
+  });
+
+  it('applies className', () => {
+    const { container } = render(
+      <InfiniteScroll hasMore={false} onLoadMore={() => {}} className="my-scroll">
+        <p>Content</p>
+      </InfiniteScroll>,
+    );
+    expect(container.querySelector('.my-scroll')).not.toBeNull();
+  });
+
+  it('disconnects observer on unmount', () => {
+    const { unmount } = render(
+      <InfiniteScroll hasMore={true} onLoadMore={() => {}}>
+        <p>Content</p>
+      </InfiniteScroll>,
+    );
+    unmount();
+    expect(mockDisconnect).toHaveBeenCalled();
+  });
+
+  it('handles missing IntersectionObserver (SSR guard)', () => {
+    const saved = global.IntersectionObserver;
+    delete (global as any).IntersectionObserver;
+
+    // Should not throw
+    const { container } = render(
+      <InfiniteScroll hasMore={true} onLoadMore={() => {}}>
+        <p>Content</p>
+      </InfiniteScroll>,
+    );
+    expect(screen.getByText('Content')).toBeDefined();
+
+    global.IntersectionObserver = saved;
+  });
+
+  describe('direction prop', () => {
+    it('direction="up" applies column-reverse style', () => {
+      const { container } = render(
+        <InfiniteScroll hasMore={true} onLoadMore={() => {}} direction="up">
+          <p>Content</p>
+        </InfiniteScroll>,
+      );
+      const wrapper = container.querySelector('[data-component="infinite-scroll"]') as HTMLElement;
+      expect(wrapper.style.display).toBe('flex');
+      expect(wrapper.style.flexDirection).toBe('column-reverse');
+    });
+
+    it('default direction has no inline style', () => {
+      const { container } = render(
+        <InfiniteScroll hasMore={true} onLoadMore={() => {}}>
+          <p>Content</p>
+        </InfiniteScroll>,
+      );
+      const wrapper = container.querySelector('[data-component="infinite-scroll"]') as HTMLElement;
+      expect(wrapper.style.display).toBe('');
+      expect(wrapper.style.flexDirection).toBe('');
+    });
+
+    it('sentinel still observed and fires onLoadMore in direction="up"', () => {
+      const onLoadMore = vi.fn();
+      const { container } = render(
+        <InfiniteScroll hasMore={true} onLoadMore={onLoadMore} direction="up">
+          <p>Content</p>
+        </InfiniteScroll>,
+      );
+
+      expect(container.querySelector('[data-sentinel]')).not.toBeNull();
+      expect(mockObserve).toHaveBeenCalled();
+
+      act(() => {
+        observerCallback(
+          [{ isIntersecting: true } as IntersectionObserverEntry],
+          {} as IntersectionObserver,
+        );
+      });
+
+      expect(onLoadMore).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/react/components/InfiniteScroll.tsx

@@ -0,0 +1,70 @@
+import { useRef, useEffect, type ReactNode } from 'react';
+
+/** Props for the InfiniteScroll headless component. */
+export interface InfiniteScrollProps {
+  hasMore: boolean;
+  loading?: boolean;
+  onLoadMore: () => void;
+  threshold?: number;
+  rootMargin?: string;
+  direction?: 'down' | 'up';
+  children: ReactNode;
+  renderLoading?: () => ReactNode;
+  renderEnd?: () => ReactNode;
+  className?: string;
+}
+
+/**
+ * Headless infinite scroll wrapper using IntersectionObserver.
+ * Renders a sentinel element that triggers `onLoadMore` when visible.
+ * Use `direction="up"` for reverse-scroll chat UIs.
+ */
+export function InfiniteScroll({
+  hasMore,
+  loading = false,
+  onLoadMore,
+  threshold = 0.1,
+  rootMargin = '0px',
+  direction = 'down',
+  children,
+  renderLoading,
+  renderEnd,
+  className,
+}: InfiniteScrollProps) {
+  const sentinelRef = useRef<HTMLDivElement>(null);
+  const onLoadMoreRef = useRef(onLoadMore);
+  onLoadMoreRef.current = onLoadMore;
+
+  useEffect(() => {
+    if (typeof IntersectionObserver === 'undefined') return;
+    const sentinel = sentinelRef.current;
+    if (!sentinel) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries[0]?.isIntersecting) {
+          onLoadMoreRef.current();
+        }
+      },
+      { threshold, rootMargin },
+    );
+
+    observer.observe(sentinel);
+    return () => observer.disconnect();
+  }, [threshold, rootMargin, hasMore, loading]);
+
+  const style = direction === 'up'
+    ? { display: 'flex', flexDirection: 'column-reverse' as const }
+    : undefined;
+
+  return (
+    <div data-component="infinite-scroll" className={className} style={style}>
+      {children}
+      {hasMore && !loading && (
+        <div ref={sentinelRef} aria-hidden="true" data-sentinel />
+      )}
+      {loading && renderLoading?.()}
+      {!hasMore && renderEnd?.()}
+    </div>
+  );
+}