@lad-sapienza/scms-core 0.1.0-alpha.0

package/components/DataTb/DataTb.tsx

@@ -0,0 +1,340 @@
+/**
+ * DataTb Component
+ * 
+ * Main data table component using TanStack Table
+ * Supports sorting, filtering, and pagination
+ */
+
+import { useState, useEffect, useMemo, useRef } from 'react';
+import {
+  useReactTable,
+  getCoreRowModel,
+  getSortedRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  flexRender,
+  type SortingState,
+  type ColumnFiltersState,
+} from '@tanstack/react-table';
+import { fetchData } from '../../utils/data-fetcher';
+import type { DataRow, DataTbProps } from './types';
+import {
+  autoDetectColumns,
+  mergeColumns,
+  columnConfigToColumnDef,
+  globalFilterFn,
+} from './utils';
+
+export function DataTb({
+  columns: userColumns,
+  searchable = false,
+  pagination = true,
+  sortable = true,
+  initialSort,
+  className = '',
+  source,
+  loadingMessage = 'Loading data...',
+  emptyMessage = 'No data available',
+  errorMessage = 'Error loading data',
+  truncateContent = true,
+  truncateMaxWidth = '20rem',
+  contentSize = 'sm',
+}: DataTbProps) {
+  const [data, setData] = useState<DataRow[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const [sorting, setSorting] = useState<SortingState>(
+    initialSort ? [{ id: initialSort.columnKey, desc: initialSort.direction === 'desc' }] : []
+  );
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
+  const [globalFilter, setGlobalFilter] = useState('');
+
+  // Use a ref to track source changes more reliably
+  const sourceRef = useRef<string>('');
+  const currentSourceKey = JSON.stringify(source);
+
+  // Pagination config
+  const paginationConfig = typeof pagination === 'object' ? pagination : {};
+  const pageSize = paginationConfig.pageSize || 10;
+  const pageSizeOptions = paginationConfig.pageSizeOptions || [10, 20, 50, 100];
+  const contentSizeClass = contentSize === 'sm' ? 'small' : '';
+
+  // Fetch data based on source configuration
+  useEffect(() => {
+    // Check if source has actually changed
+    if (currentSourceKey === sourceRef.current) {
+      return;
+    }
+
+    sourceRef.current = currentSourceKey;
+
+    if (!source) {
+      setError(new Error('No data source provided'));
+      setLoading(false);
+      return;
+    }
+
+    // Guards against a stale response overwriting newer state if the source
+    // changes again before this fetch resolves.
+    let cancelled = false;
+
+    const loadData = async () => {
+      try {
+        setLoading(true);
+        setError(null);
+
+        const fetchedData = await fetchData(source);
+        if (cancelled) return;
+
+        setData(fetchedData);
+        setLoading(false);
+      } catch (err) {
+        if (cancelled) return;
+        setError(err instanceof Error ? err : new Error('Failed to load data'));
+        setLoading(false);
+      }
+    };
+
+    loadData();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [currentSourceKey]); // Use stringified source as dependency
+
+  // Auto-detect or merge columns
+  const finalColumns = useMemo(() => {
+    if (data.length === 0) {
+      return [];
+    }
+
+    const autoColumns = autoDetectColumns(data);
+    const merged = mergeColumns(autoColumns, userColumns);
+    return merged;
+  }, [data, userColumns]);
+
+  // Convert to TanStack column definitions
+  const columnDefs = useMemo(
+    () => finalColumns.map(columnConfigToColumnDef),
+    [finalColumns]
+  );
+
+  // Initialize table
+  const table = useReactTable({
+    data,
+    columns: columnDefs,
+    getCoreRowModel: getCoreRowModel(),
+    getSortedRowModel: sortable ? getSortedRowModel() : undefined,
+    getFilteredRowModel: searchable ? getFilteredRowModel() : undefined,
+    getPaginationRowModel: pagination ? getPaginationRowModel() : undefined,
+    onSortingChange: setSorting,
+    onColumnFiltersChange: setColumnFilters,
+    onGlobalFilterChange: setGlobalFilter,
+    globalFilterFn: globalFilterFn,
+    state: {
+      sorting,
+      columnFilters,
+      globalFilter,
+    },
+    initialState: {
+      pagination: {
+        pageSize,
+      },
+    },
+  });
+
+  // Render loading state
+  if (loading) {
+    return (
+      <div className="datatb-container">
+        <div className="datatb-loading p-4 text-center text-secondary">
+          {loadingMessage}
+        </div>
+      </div>
+    );
+  }
+
+  // Render error state
+  if (error) {
+    return (
+      <div className="datatb-container">
+        <div className="datatb-error p-4 text-center text-danger">
+          {errorMessage}: {error.message}
+        </div>
+      </div>
+    );
+  }
+
+  // Render empty state
+  if (data.length === 0) {
+    return (
+      <div className="datatb-container">
+        <div className="datatb-empty p-4 text-center text-secondary">
+          {emptyMessage}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className={`datatb-container ${className}`}>
+
+      {/* Search input */}
+      {searchable && (
+        <div className="datatb-search mb-3">
+          <input
+            type="text"
+            value={globalFilter ?? ''}
+            onChange={(e) => setGlobalFilter(e.target.value)}
+            placeholder="Search..."
+            className="form-control form-control-sm"
+            style={{ maxWidth: '24rem' }}
+          />
+        </div>
+      )}
+
+      {/* Table */}
+      <div className="datatb-table-wrapper table-responsive border rounded shadow-sm">
+        <table className="datatb-table table table-sm table-hover mb-0">
+          <thead className="table-light">
+            {table.getHeaderGroups().map((headerGroup) => (
+              <tr key={headerGroup.id}>
+                {headerGroup.headers.map((header, index) => (
+                  <th
+                    key={header.id}
+                    className={`py-2 text-start small fw-semibold text-uppercase ${
+                      index === 0 ? 'ps-3 pe-3' : 'px-3'
+                    }`}
+                    style={{ width: header.column.columnDef.meta?.width }}
+                  >
+                    {header.isPlaceholder ? null : (
+                      <div
+                        className={
+                          header.column.getCanSort()
+                            ? 'd-flex align-items-center gap-2 user-select-none'
+                            : 'd-flex align-items-center gap-2'
+                        }
+                        onClick={header.column.getToggleSortingHandler()}
+                        style={header.column.getCanSort() ? { cursor: 'pointer' } : undefined}
+                      >
+                        {flexRender(
+                          header.column.columnDef.header,
+                          header.getContext()
+                        )}
+                        {header.column.getCanSort() && (
+                          <span className="text-secondary">
+                            {{
+                              asc: '↑',
+                              desc: '↓',
+                            }[header.column.getIsSorted() as string] ?? '↕'}
+                          </span>
+                        )}
+                      </div>
+                    )}
+                  </th>
+                ))}
+              </tr>
+            ))}
+          </thead>
+          <tbody>
+            {table.getRowModel().rows.map((row) => (
+              <tr key={row.id}>
+                {row.getVisibleCells().map((cell, index) => (
+                  <td
+                    key={cell.id}
+                    className={`py-2 ${contentSizeClass} ${
+                      index === 0 ? 'ps-3 pe-3' : 'px-3'
+                    }`}
+                  >
+                    {(() => {
+                      const cellContent = flexRender(cell.column.columnDef.cell, cell.getContext());
+                      const isSimpleText =
+                        typeof cellContent === 'string' || typeof cellContent === 'number';
+
+                      if (!truncateContent) {
+                        return cellContent;
+                      }
+
+                      return (
+                        <div
+                          className="text-truncate"
+                          style={{ maxWidth: truncateMaxWidth }}
+                          title={isSimpleText ? String(cellContent) : undefined}
+                        >
+                          {cellContent}
+                        </div>
+                      );
+                    })()}
+                  </td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+
+      {/* Pagination */}
+      {pagination && (
+        <div className="datatb-pagination mt-3 d-flex flex-row align-items-center justify-content-between gap-2">
+          <div className="btn-group" role="group">
+            <button
+              onClick={() => table.setPageIndex(0)}
+              disabled={!table.getCanPreviousPage()}
+              className="btn btn-outline-secondary btn-sm"
+            >
+              {'<<'}
+            </button>
+            <button
+              onClick={() => table.previousPage()}
+              disabled={!table.getCanPreviousPage()}
+              className="btn btn-outline-secondary btn-sm"
+            >
+              {'<'}
+            </button>
+            <button
+              onClick={() => table.nextPage()}
+              disabled={!table.getCanNextPage()}
+              className="btn btn-outline-secondary btn-sm"
+            >
+              {'>'}
+            </button>
+            <button
+              onClick={() => table.setPageIndex(table.getPageCount() - 1)}
+              disabled={!table.getCanNextPage()}
+              className="btn btn-outline-secondary btn-sm"
+            >
+              {'>>'}
+            </button>
+          </div>
+
+          <div className="d-flex align-items-center gap-2 flex-nowrap">
+            <span className="small text-secondary text-nowrap">
+              Page {table.getState().pagination.pageIndex + 1} of {table.getPageCount()}
+            </span>
+
+            {paginationConfig.showPageSize !== false && (
+              <select
+                value={table.getState().pagination.pageSize}
+                onChange={(e) => {
+                  table.setPageSize(Number(e.target.value));
+                }}
+                className="form-select form-select-sm"
+                style={{ width: 'auto' }}
+              >
+                {pageSizeOptions.map((size) => (
+                  <option key={size} value={size}>
+                    {size}
+                  </option>
+                ))}
+              </select>
+            )}
+
+            <span className="small text-secondary text-nowrap">
+              ({data.length} total)
+            </span>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

package/components/DataTb/DataTbMdx.tsx

@@ -0,0 +1,75 @@
+/**
+ * MDX-safe wrapper for DataTb component
+ * 
+ * This wrapper ensures that object props are properly memoized
+ * to prevent infinite re-renders in MDX context
+ */
+
+import { useMemo } from 'react';
+import { DataTb as DataTbCore } from './DataTb';
+import type { DataTbProps, SourceConfig } from './types';
+import { directusShorthandToConfig } from '../../utils/directus-config';
+
+export function DataTb(props: DataTbProps) {
+  // Resolve source from simplified props or original source prop
+  const resolvedSource = useMemo<SourceConfig | undefined>(() => {
+    // If explicit source object is provided, use it (memoized later)
+    if (props.source) return props.source;
+
+    // Handle simplified CSV prop
+    if (props.csv) {
+      return { type: 'csv', url: props.csv } as const;
+    }
+
+    // Handle simplified JSON prop
+    if (props.json) {
+      if (Array.isArray(props.json)) {
+        return { type: 'json', data: props.json } as const;
+      }
+      return { type: 'json', url: props.json as string } as const;
+    }
+
+    // Handle simplified API prop
+    if (props.api) {
+      return { type: 'api', url: props.api } as const;
+    }
+
+    // Handle simplified Directus prop (same interface as Map component)
+    if (props.directus) {
+      const directusSource = directusShorthandToConfig(props.directus);
+      return directusSource ?? undefined;
+    }
+
+    return undefined;
+  }, [props.source, props.csv, props.json, props.api, JSON.stringify(props.directus)]);
+
+  // Memoize the source object to prevent re-creation on every render
+  // This is critical for MDX which might recreate objects on every pass
+  const stableSource = useMemo(() => resolvedSource, [JSON.stringify(resolvedSource)]);
+
+  // Memoize columns if provided
+  const stableColumns = useMemo(() => props.columns, [JSON.stringify(props.columns)]);
+
+  // Memoize pagination config if it's an object
+  const stablePagination = useMemo(() => {
+    if (typeof props.pagination === 'object') {
+      return props.pagination;
+    }
+    return props.pagination;
+  }, [JSON.stringify(props.pagination)]);
+
+  // Memoize initialSort if provided
+  const stableInitialSort = useMemo(() => props.initialSort, [JSON.stringify(props.initialSort)]);
+
+  return (
+    <DataTbCore
+      {...props}
+      source={stableSource}
+      columns={stableColumns}
+      pagination={stablePagination}
+      initialSort={stableInitialSort}
+    />
+  );
+}
+
+export default DataTb;

package/components/DataTb/README.md

@@ -0,0 +1,275 @@
+# DataTb Component
+
+A powerful, flexible data table component for Astro with support for multiple data sources, built on TanStack Table.
+
+## Features
+
+- 📊 **Multiple Data Sources**: CSV, JSON, Directus, and generic APIs
+- 🔍 **Global Search**: Filter data across all columns
+- ↕️ **Column Sorting**: Click headers to sort data
+- 📄 **Pagination**: Built-in pagination with customizable page sizes
+- 🎨 **Auto-detection**: Automatically detects columns from data
+- ⚙️ **Customizable**: Override columns, formatting, and rendering
+- 🎯 **TypeScript**: Full type safety
+- 💅 **Bootstrap Styled**: Uses the same Bootstrap 5 classes as the rest of s:CMS, themeable via `usr/styles/global.css`
+
+## Basic Usage
+
+### CSV Source
+
+```jsx
+import { DataTb } from '@lad-sapienza/scms-core/components/DataTb';
+
+<DataTb 
+  source={{ type: 'csv', url: '/data/products.csv' }}
+  searchable 
+  pagination 
+  client:idle 
+/>
+```
+
+### JSON Source
+
+```jsx
+<DataTb 
+  source={{
+    type: 'json',
+    data: [
+      { name: 'Item 1', price: 10 },
+      { name: 'Item 2', price: 20 }
+    ]
+  }}
+  searchable
+  client:idle
+/>
+```
+
+### Directus Source
+
+Reads `PUBLIC_DIRECTUS_URL` / `PUBLIC_DIRECTUS_TOKEN` from `.env` automatically — see [Directus Setup](#directus-setup) below.
+
+```jsx
+<DataTb 
+  directus={{
+    table: 'articles',
+    queryString: 'filter[status][_eq]=published&sort=-date_published',
+  }}
+  searchable 
+  pagination 
+  client:idle 
+/>
+```
+
+### API Source
+
+```jsx
+<DataTb 
+  source={{
+    type: 'api',
+    url: 'https://api.example.com/data',
+    transformer: (data) => data.results
+  }}
+  searchable 
+  pagination 
+  client:idle 
+/>
+```
+
+## Custom Columns
+
+Override column display, formatting, and rendering:
+
+```jsx
+<DataTb 
+  source={{ type: 'csv', url: '/data/products.csv' }}
+  columns={[
+    { key: 'id', header: 'ID', width: '80px' },
+    { key: 'name', header: 'Product Name', sortable: true },
+    { key: 'price', header: 'Price', format: 'currency' },
+    { key: 'date', header: 'Date', format: 'date' },
+    { 
+      key: 'status', 
+      header: 'Status',
+      render: (val) => val === 'active' ? '✅' : '❌'
+    }
+  ]}
+  searchable
+  pagination={{ pageSize: 20 }}
+  initialSort={{ columnKey: 'name', direction: 'asc' }}
+  client:idle
+/>
+```
+
+## Props
+
+### DataTb Component
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `ColumnConfig[]` | auto-detected | Column definitions |
+| `searchable` | `boolean` | `false` | Enable global search |
+| `pagination` | `boolean \| PaginationConfig` | `true` | Enable/configure pagination |
+| `sortable` | `boolean` | `true` | Enable column sorting |
+| `initialSort` | `{ columnKey, direction }` | - | Initial sort state |
+| `className` | `string` | `''` | Custom CSS classes |
+| `loadingMessage` | `string` | `'Loading data...'` | Loading message |
+| `emptyMessage` | `string` | `'No data available'` | Empty state message |
+| `errorMessage` | `string` | `'Error loading data'` | Error message |
+| `truncateContent` | `boolean` | `true` | Truncate large cell content with ellipsis |
+| `truncateMaxWidth` | `string` | `'20rem'` | Max width for truncated cell content |
+| `contentSize` | `'sm' \| 'md'` | `'sm'` | Table body text size |
+
+### Column Config
+
+```typescript
+{
+  key: string;              // Data property key
+  header: string;           // Display header text
+  sortable?: boolean;       // Enable sorting (default: true)
+  format?: 'date' | 'number' | 'currency' | 'percent';
+  render?: (value, row) => ReactNode;  // Custom cell renderer
+  width?: string;           // Column width (CSS value)
+}
+```
+
+### Source Components
+
+#### CsvSource
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `url` | `string` | CSV file URL (local or remote) |
+| `delimiter` | `string` | Delimiter character (default: `','`) |
+| `skipRows` | `number` | Skip first N rows |
+
+#### JsonSource
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `data` | `DataRow[]` | Inline JSON data |
+| `url` | `string` | URL to fetch JSON from |
+
+#### DirectusSource
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `collection` | `string` | Collection name |
+| `config` | `{ url, token }` | Directus configuration |
+| `filter` | `object` | Directus filter query |
+| `fields` | `string[]` | Fields to select |
+| `sort` | `string[]` | Sort order (e.g., `['-date']`) |
+| `limit` | `number` | Limit results |
+
+#### ApiSource
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `url` | `string` | API endpoint URL |
+| `method` | `'GET' \| 'POST'` | HTTP method (default: `'GET'`) |
+| `headers` | `Record<string, string>` | Request headers |
+| `body` | `any` | Request body (for POST) |
+| `transformer` | `(data) => DataRow[]` | Transform response data |
+
+## Formatting
+
+Built-in formatters for common data types:
+
+- `format: 'date'` - Formats dates (e.g., "Jan 10, 2026")
+- `format: 'number'` - Formats numbers with thousands separators
+- `format: 'currency'` - Formats as USD currency
+- `format: 'percent'` - Formats as percentage
+
+## Custom Rendering
+
+Use the `render` function for complete control:
+
+```jsx
+columns={[
+  {
+    key: 'avatar',
+    header: 'Avatar',
+    render: (url) => <img src={url} alt="" className="w-10 h-10 rounded-full" />
+  },
+  {
+    key: 'status',
+    header: 'Status',
+    render: (status, row) => (
+      <span className={status === 'active' ? 'text-green-600' : 'text-red-600'}>
+        {status}
+      </span>
+    )
+  }
+]}
+```
+
+## Directus Setup
+
+1. Generate a token in the Directus admin panel:
+   - Settings → Access Tokens → Create Token
+   - Set appropriate permissions
+   - Copy the token
+
+2. Add it to `.env` in the project root:
+
+```env
+PUBLIC_DIRECTUS_URL=https://your-directus-instance.com
+PUBLIC_DIRECTUS_TOKEN=your-access-token
+```
+
+3. Use the simplified `directus` prop — `DataTb` reads the URL/token from those env vars automatically, no config object needed:
+
+```jsx
+<DataTb 
+  directus={{
+    table: 'your_collection',
+    queryString: 'filter[status][_eq]=published',
+  }}
+  client:idle
+/>
+```
+
+The `source={{ type: 'directus', config: { url, token }, collection }}` form shown above is still supported for cases where you need to pass an explicit URL/token instead of the env vars (e.g. multiple Directus instances on one site).
+
+## Client Hydration
+
+For optimal performance, use appropriate hydration strategies:
+
+- `client:load` - For interactive tables (Directus, API, searchable)
+- `client:idle` - For static data (CSV, JSON) - loads after initial page render
+- `client:visible` - Load when table scrolls into view
+
+```jsx
+{/* Dynamic data - load immediately */}
+<DataTb 
+  source={{
+    type: 'directus',
+    collection: 'articles',
+    config: directusConfig
+  }}
+  searchable 
+  pagination 
+  client:load 
+/>
+
+{/* Static data - load when idle */}
+<DataTb 
+  source={{ type: 'csv', url: '/data.csv' }}
+  client:idle 
+/>
+```
+
+## Architecture
+
+The DataTb component follows a simple, self-contained architecture:
+
+- **DataTb.tsx** - Main React component using TanStack Table with built-in data fetching
+- **DataTbMdx.tsx** - MDX-safe wrapper (memoizes props, resolves `csv`/`json`/`api`/`directus` shorthands) — this is what `@lad-sapienza/scms-core/components/DataTb`'s `DataTb` export actually is
+- **types.ts** - TypeScript definitions for all source types
+- **utils.ts** - Helper functions for column detection, formatting
+- **sources/** - Standalone headless data-loaders (`CsvSource`, `JsonSource`, `DirectusSource`, `ApiSource`) for building a custom UI outside `DataTb` itself
+
+Data fetching is handled internally based on the `source`/`csv`/`json`/`api`/`directus` prop, supporting CSV, JSON, Directus, and generic APIs.
+
+## Examples
+
+See the [DataTb docs page](../../../usr/content/docs/components/datatb.mdx) (rendered at `/docs/components/datatb` on a running site) for live, interactive examples of every prop and source type.