chati-dev 4.3.0 → 4.4.0

package/framework/scaffold/saas-dashboard/components/data/DataTable.types.ts.template

@@ -0,0 +1,104 @@
+/**
+ * components/data/DataTable.types.ts
+ * ============================================================
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * DataTable is a generic component (DataTable<T>) that needs its
+ * column definition type to be importable independently. Without a
+ * dedicated types file, any component that imports ColumnDef<T>
+ * would pull in the entire DataTable render tree. Separating types
+ * allows tree-shaking and prevents circular imports when
+ * DataTablePagination imports the type for its own props.
+ *
+ * DESIGN DECISIONS
+ * ----------------
+ * ColumnDef<T> mirrors the TanStack Table v8 surface but does NOT
+ * depend on it. This keeps the preset dependency-light while
+ * matching the industry-standard mental model, making migration
+ * to full TanStack Table trivial (swap ColumnDef import only).
+ *
+ * The `render` function receives the full row datum so columns can
+ * compose multiple fields (e.g., an avatar + name cell) without
+ * needing a separate row accessor. The return type is ReactNode
+ * rather than string so cells can render badges, links, and icons.
+ *
+ * `align` defaults to 'left' for content columns and should be
+ * 'right' for numeric columns so decimal points stack vertically
+ * (a core data-table accessibility and readability requirement).
+ *
+ * SortDirection is a discriminated union rather than boolean to
+ * support the three-state cycle: none -> asc -> desc -> none.
+ * This matches how most data grids behave and avoids ambiguity
+ * about what `false` means for sort direction.
+ * ============================================================
+ */
+
+import type { ReactNode } from 'react';
+import type React from 'react';
+
+/** Three-state sort cycle: unsorted, ascending, descending. */
+export type SortDirection = 'asc' | 'desc' | 'none';
+
+/**
+ * Column definition for DataTable<T>.
+ * T is the row datum type (e.g., User, Order, Invoice).
+ */
+export interface ColumnDef<T> {
+  /**
+   * Unique key used as the React key and as the sort field identifier.
+   * Must be stable across renders (not an array index).
+   */
+  key: string;
+
+  /** Column header label. Rendered in <th> scope="col". */
+  header: string;
+
+  /**
+   * Cell renderer. Receives the full row datum.
+   * Return a ReactNode so cells can include badges, links, avatars.
+   * When omitted, falls back to String(row[key as keyof T]).
+   */
+  render?: (row: T) => ReactNode;
+
+  /**
+   * Text alignment within the cell.
+   * Use 'right' for numeric/currency columns to align decimal points.
+   * Defaults to 'left'.
+   */
+  align?: 'left' | 'center' | 'right';
+
+  /**
+   * Whether this column is sortable.
+   * When true, the header renders a ChevronUp/ChevronDown toggle
+   * and calls the onSort callback.
+   * Defaults to false.
+   */
+  sortable?: boolean;
+
+  /**
+   * Fixed column width in pixels or a CSS width string (e.g., '20%').
+   * Set on the <col> element inside <colgroup>.
+   * When omitted, the browser distributes width naturally.
+   */
+  width?: number | string;
+
+  /**
+   * sr-only description appended to the header for screen readers.
+   * Use for icon-only headers (e.g., a "Status" column with only a
+   * colored dot). Supplements, does not replace, the `header` string.
+   */
+  srDescription?: string;
+}
+
+/** Sort state passed to the onSort callback. */
+export interface SortState {
+  key: string;
+  direction: SortDirection;
+}
+
+/** Pagination state for DataTablePagination. */
+export interface PaginationState {
+  page: number;
+  pageSize: number;
+  total: number;
+}

package/framework/scaffold/saas-dashboard/components/data/DataTablePagination.tsx.template

@@ -0,0 +1,234 @@
+/**
+ * components/data/DataTablePagination.tsx
+ * ============================================================
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * Pagination is extracted from DataTable into its own file for two
+ * reasons:
+ *
+ * 1. Composability: callers who render DataTable inside a drawer or
+ *    modal may want pagination above the table, or not at all. A
+ *    standalone component supports every layout without conditional
+ *    rendering inside DataTable.
+ *
+ * 2. Testability: pagination logic ("Showing X to Y of Z",
+ *    page-size options, boundary conditions on prev/next) is much
+ *    easier to unit-test when isolated.
+ *
+ * DESIGN DECISIONS
+ * ----------------
+ * Page-size select: uses a native <select> (not a custom dropdown)
+ *   because native <select> has built-in keyboard navigation,
+ *   mobile-native UX (bottom sheet picker on iOS), and zero
+ *   JavaScript overhead. A real <label> is provided (sr-only)
+ *   so the field is fully accessible.
+ *
+ * "Showing X to Y of Z" copy: computed client-side from props.
+ *   When total is 0, it shows "No results" instead of "Showing 0
+ *   to 0 of 0" which is confusing.
+ *
+ * Prev/Next buttons: disabled at boundaries. `aria-disabled` is set
+ *   in addition to the HTML `disabled` attribute so CSS can style
+ *   the disabled state without relying on the attribute selector
+ *   specificity.
+ *
+ * Page count: shown as "Page X of Y" in between prev/next for
+ *   context. Hidden on very small viewports (< 400px) to avoid
+ *   wrapping.
+ *
+ * MOTION: no transition on the pagination row itself. The table body
+ *   re-renders with new rows, and that transition (if any) is
+ *   handled by DataTable's row entry animation.
+ * ============================================================
+ */
+
+'use client';
+
+import React, { useId } from 'react';
+import { ChevronLeft, ChevronRight } from 'lucide-react';
+
+export interface DataTablePaginationProps {
+  /** Current page number (1-indexed). */
+  page: number;
+  /** Number of rows per page. */
+  pageSize: number;
+  /** Total number of rows across all pages. */
+  total: number;
+  /** Called when user navigates to a different page. */
+  onPageChange: (page: number) => void;
+  /** Called when user changes rows-per-page. */
+  onPageSizeChange: (size: number) => void;
+  /** Available page-size options. Defaults to [10, 25, 50, 100]. */
+  pageSizeOptions?: number[];
+}
+
+const DEFAULT_PAGE_SIZE_OPTIONS = [10, 25, 50, 100];
+
+export function DataTablePagination({
+  page,
+  pageSize,
+  total,
+  onPageChange,
+  onPageSizeChange,
+  pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
+}: DataTablePaginationProps) {
+  const selectId = useId();
+  const totalPages = Math.max(1, Math.ceil(total / pageSize));
+  const firstRow = total === 0 ? 0 : (page - 1) * pageSize + 1;
+  const lastRow = Math.min(page * pageSize, total);
+  const canPrev = page > 1;
+  const canNext = page < totalPages;
+
+  const rowSummary =
+    total === 0
+      ? 'No results'
+      : `Showing ${firstRow} to ${lastRow} of ${total}`;
+
+  return (
+    <div
+      role="navigation"
+      aria-label="Table pagination"
+      style={paginationWrapStyle}
+    >
+      {/* Left: rows summary */}
+      <span
+        aria-live="polite"
+        aria-atomic="true"
+        style={{
+          fontSize: 'var(--type-small)',
+          color: 'var(--color-text-secondary)',
+          flexShrink: 0,
+        }}
+      >
+        {rowSummary}
+      </span>
+
+      {/* Right: page-size selector + navigation */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--space-4)' }}>
+        {/* Rows per page */}
+        <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--space-2)' }}>
+          {/* Real label, sr-only */}
+          <label
+            htmlFor={selectId}
+            style={srOnlyStyle}
+          >
+            Rows per page
+          </label>
+          <select
+            id={selectId}
+            value={pageSize}
+            onChange={(e) => {
+              onPageSizeChange(Number(e.target.value));
+              onPageChange(1);
+            }}
+            style={selectStyle}
+            aria-label="Rows per page"
+          >
+            {pageSizeOptions.map((opt) => (
+              <option key={opt} value={opt}>
+                {opt} rows
+              </option>
+            ))}
+          </select>
+        </div>
+
+        {/* Page indicator */}
+        <span
+          style={{
+            fontSize: 'var(--type-small)',
+            color: 'var(--color-text-secondary)',
+            // Hide on very narrow containers to prevent wrap
+            display: 'inline',
+            whiteSpace: 'nowrap',
+          }}
+          aria-label={`Page ${page} of ${totalPages}`}
+        >
+          {page} / {totalPages}
+        </span>
+
+        {/* Previous */}
+        <button
+          type="button"
+          onClick={() => canPrev && onPageChange(page - 1)}
+          disabled={!canPrev}
+          aria-disabled={!canPrev}
+          aria-label="Previous page"
+          style={navButtonStyle(!canPrev)}
+        >
+          <ChevronLeft size={15} aria-hidden="true" />
+        </button>
+
+        {/* Next */}
+        <button
+          type="button"
+          onClick={() => canNext && onPageChange(page + 1)}
+          disabled={!canNext}
+          aria-disabled={!canNext}
+          aria-label="Next page"
+          style={navButtonStyle(!canNext)}
+        >
+          <ChevronRight size={15} aria-hidden="true" />
+        </button>
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Styles
+// ---------------------------------------------------------------------------
+
+const paginationWrapStyle: React.CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  flexWrap: 'wrap',
+  gap: 'var(--space-3)',
+  padding: 'var(--space-3) var(--space-4)',
+  borderTop: '1px solid var(--color-border-default)',
+  backgroundColor: 'var(--color-bg-raised)',
+};
+
+const selectStyle: React.CSSProperties = {
+  backgroundColor: 'var(--color-bg-sunken)',
+  color: 'var(--color-text-primary)',
+  border: '1px solid var(--color-border-default)',
+  borderRadius: 'var(--radius-sm)',
+  fontSize: 'var(--type-small)',
+  padding: 'var(--space-1) var(--space-2)',
+  cursor: 'pointer',
+  outline: 'none',
+  // Focus ring handled by global :focus-visible rule in globals.css
+};
+
+function navButtonStyle(disabled: boolean): React.CSSProperties {
+  return {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: 'var(--space-8)',
+    height: 'var(--space-8)',
+    borderRadius: 'var(--radius-default)',
+    border: '1px solid var(--color-border-default)',
+    backgroundColor: 'transparent',
+    color: disabled ? 'var(--color-text-muted)' : 'var(--color-text-primary)',
+    cursor: disabled ? 'not-allowed' : 'pointer',
+    opacity: disabled ? 0.4 : 1,
+    transition: `background-color var(--duration-fast) var(--ease-out),
+                 opacity var(--duration-fast) var(--ease-out)`,
+    outline: 'none',
+    pointerEvents: disabled ? 'none' : undefined,
+  };
+}
+
+const srOnlyStyle: React.CSSProperties = {
+  position: 'absolute',
+  width: '1px',
+  height: '1px',
+  padding: 0,
+  margin: '-1px',
+  overflow: 'hidden',
+  clip: 'rect(0,0,0,0)',
+  whiteSpace: 'nowrap',
+  border: 0,
+};

package/framework/scaffold/saas-dashboard/components/data/SkeletonBlock.tsx.template

@@ -0,0 +1,111 @@
+/**
+ * components/data/SkeletonBlock.tsx
+ * ============================================================
+ * WHY THIS COMPONENT EXISTS
+ * -------------------------
+ * Loading states are a first-class quality concern in dashboard UIs.
+ * A generic skeleton block eliminates the temptation to use spinners
+ * (which do not communicate layout) or plain grey boxes (which shift
+ * layout when content loads). SkeletonBlock reserves exact space
+ * with the same dimensions as the content it stands in for.
+ *
+ * ANIMATION APPROACH
+ * ------------------
+ * The shimmer effect is implemented as a CSS gradient sweep on a
+ * ::after pseudo-element. Critically, only `transform: translateX`
+ * is animated -- never `background-position` or `left`. This keeps
+ * the animation on the compositor thread and prevents layout
+ * thrashing even when hundreds of skeleton blocks are visible
+ * simultaneously (e.g., a 50-row table in loading state).
+ *
+ * The gradient is 200% wide so the sweep covers the full element
+ * width with a centered highlight, creating the perception of light
+ * reflecting across a surface.
+ *
+ * REDUCED-MOTION
+ * --------------
+ * When prefers-reduced-motion: reduce is active, the shimmer
+ * animation is disabled via the global globals.css rule that sets
+ * animation-duration to 0.01ms. The element still renders as a
+ * static muted block (using --color-bg-highlight), which preserves
+ * the layout placeholder without causing motion discomfort.
+ *
+ * USAGE
+ * -----
+ * <SkeletonBlock width="60%" height={14} borderRadius="var(--radius-sharp)" />
+ * <SkeletonBlock width={32} height={32} borderRadius="var(--radius-circle)" />
+ * ============================================================
+ */
+
+import React from 'react';
+
+export interface SkeletonBlockProps {
+  /** Width as a CSS string ('60%', '120px') or raw pixel number. */
+  width?: number | string;
+  /** Height as a CSS string or raw pixel number. */
+  height?: number | string;
+  /** Border radius mapped to a token (e.g., 'var(--radius-default)'). */
+  borderRadius?: string;
+  /** Additional className for layout overrides. */
+  className?: string;
+}
+
+export function SkeletonBlock({
+  width = '100%',
+  height = 16,
+  borderRadius = 'var(--radius-sharp)',
+  className,
+}: SkeletonBlockProps) {
+  const widthVal = typeof width === 'number' ? `${width}px` : width;
+  const heightVal = typeof height === 'number' ? `${height}px` : height;
+
+  return (
+    <span
+      className={className}
+      aria-hidden="true"
+      style={{
+        display: 'block',
+        width: widthVal,
+        height: heightVal,
+        borderRadius,
+        // Base color: a step above the card surface so it's perceptible
+        // but not jarring. Uses the overlay bg to match card interiors.
+        backgroundColor: 'var(--color-bg-highlight)',
+        position: 'relative',
+        overflow: 'hidden',
+        // Shimmer is the ::after pseudo-element, but since inline styles
+        // cannot target pseudo-elements, the animation class is injected
+        // via a <style> tag rendered once at the module level.
+      }}
+    >
+      {/* Shimmer layer injected via inline <style> -- scoped keyframes */}
+      <style>{SHIMMER_KEYFRAMES}</style>
+      <span
+        aria-hidden="true"
+        style={{
+          position: 'absolute',
+          inset: 0,
+          background:
+            'linear-gradient(90deg, transparent 0%, rgba(255,255,255,0.07) 50%, transparent 100%)',
+          backgroundSize: '200% 100%',
+          // translateX sweeps from -100% to +100% of the element width
+          animation: `skeleton-shimmer 1.4s var(--ease-in-out, cubic-bezier(0.4, 0, 0.2, 1)) infinite`,
+          // Will-change hints to compositor for GPU promotion
+          willChange: 'transform',
+        }}
+      />
+    </span>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Keyframes injected once per page render (React deduplicates identical
+// <style> elements in the DOM, so this does not multiply).
+// Only transform is animated -- never left, width, or background-position.
+// ---------------------------------------------------------------------------
+const SHIMMER_KEYFRAMES = `
+  @keyframes skeleton-shimmer {
+    from { transform: translateX(-100%); }
+    to   { transform: translateX(100%); }
+  }
+`;