@warkypublic/svelix 0.1.44 → 0.1.46

package/llm/plans/card_grid.plan.md

@@ -0,0 +1,305 @@
+# CardGrid Component — Implementation Plan
+
+## Context
+
+The project has `GridlerFull` for tabular data but no card-based equivalent. We need a `CardGrid` component that mirrors most GridlerFull features (sorting, filtering, search, context menus, data fetching) but renders records as responsive cards with **selection + animation** and **keyboard navigation**.
+
+---
+
+## Files
+
+All under `src/lib/components/CardGrid/`:
+
+| File | Lines (est.) | Role |
+|------|-------------|------|
+| `cardGrid.ts` | ~80 | Types + pure helpers (selection, grid math) |
+| `DefaultCard.svelte` | ~40 | Fallback card renderer |
+| `CardGridFilterPanel.svelte` | ~120 | Filter UI (reuses GridlerFull operator set) |
+| `CardGrid.svelte` | ~450 | Main component |
+| `index.ts` | ~10 | Barrel exports |
+
+Also update: `src/lib/components/index.ts` (add `export * from './CardGrid/index'`)
+
+---
+
+## Reuse From Existing Code
+
+| What | Source | How |
+|------|--------|-----|
+| `GridlerResolveSpecAdapter` | `src/lib/components/Gridler/adapters/GridlerResolveSpecAdapter.ts` | Import & instantiate directly |
+| `GridlerRestHeaderSpecAdapter` | `src/lib/components/Gridler/adapters/GridlerRestHeaderSpecAdapter.ts` | Same |
+| `GridlerAdapterConfig`, `GridlerPageResult` | `src/lib/components/Gridler/types.ts` | Re-export from cardGrid.ts |
+| `gridColumnFiltersToFilterOptions()` | `src/lib/components/Gridler/utils/filters.ts` | Import for server-side filters |
+| `buildSearchFilters()` | `src/lib/components/Gridler/utils/filters.ts` | Import — always pass `searchColumns` explicitly to avoid GridlerColumn type mismatch |
+| `sortOrderToSortOptions()` | `src/lib/components/Gridler/utils/sort.ts` | Import for server-side sort |
+| `GridColumnSortOrder`, `GridColumnFilters`, `FilterOperator` | `src/lib/components/Types/generic_grid.ts` | Re-export |
+| `BetterMenu` | `src/lib/components/BetterMenu/` | Context menu + filter panel popup |
+| Data fetch pattern | `GridlerFull.svelte` lines 550-700 | Port adapter creation, fetchPage, loadNextPage, cancellation |
+
+---
+
+## 1. `cardGrid.ts` — Types & Helpers
+
+### Types
+
+```ts
+export interface CardGridColumn {
+  id: string;
+  title: string;
+  dataKey?: string;        // field path; defaults to id
+  format?: GridColumnFormat;
+  disableSort?: boolean;
+  disableFilter?: boolean;
+  disableSearch?: boolean;
+}
+
+export interface CardSortOption {
+  columnId: string;
+  label: string;
+}
+
+export interface CardGridContextMenuItem {
+  id: string;
+  label: string;
+  disabled?: boolean;
+  icon?: string;
+  kind?: 'item' | 'separator';
+  onselect?: (rowData?: Record<string, unknown>) => void;
+}
+```
+
+### Pure Helpers
+
+- `toggleItemInSelection(items, item, uniqueID)` — add/remove by uniqueID match
+- `rangeSelect(allItems, anchorIndex, targetIndex)` — slice between anchor and target
+- `isItemSelected(selectedItems, item, uniqueID)` — boolean check
+- `computeColumnsInRow(containerWidth, cardMinWidth, gap)` — `Math.max(1, Math.floor((w + gap) / (minW + gap)))`
+
+---
+
+## 2. `CardGrid.svelte` — Props
+
+```ts
+interface Props {
+  // Column/display
+  columns: CardGridColumn[];
+  displayColumns?: string[];
+  cardMinWidth?: number;       // default 280
+  cardGap?: number;            // default 16
+
+  // Custom rendering — note: card snippet gets selected+focused state
+  card?: Snippet<[Record<string, unknown>, number, boolean, boolean]>;
+  empty?: Snippet;
+  skeleton?: Snippet;
+
+  // Data source (mirrors GridlerFull pattern)
+  dataSource?: 'resolvespec' | 'headerspec' | 'local';
+  dataSourceOptions?: { url, authToken, schema, entity, uniqueID, hotfields, extraOptions };
+  data?: Record<string, unknown>[] | (() => Promise<Record<string, unknown>[]>);
+  pageSize?: number;           // default 20
+  uniqueID?: string;           // default 'id'
+
+  // Search
+  searchValue?: string;
+  onSearchValueChange?: (v: string) => void;
+  serverSideSearch?: boolean;  // default true
+  searchColumns?: string[];
+  searchPlaceholder?: string;
+
+  // Sort
+  sortOrder?: GridColumnSortOrder;
+  onSortOrderChange?: (order: GridColumnSortOrder) => void;
+  sortOptions?: CardSortOption[];
+
+  // Filters
+  filters?: GridColumnFilters;
+  onFilterChange?: (filters: GridColumnFilters) => void;
+
+  // Selection
+  selectedItems?: Record<string, unknown>[];
+  onSelectedItemsChange?: (items: Record<string, unknown>[]) => void;
+  multiSelect?: boolean;       // default true
+
+  // Card events
+  onCardClick?: (record, index) => void;
+  onCardDblClick?: (record, index) => void;
+  onCardContextMenu?: (record, index, x, y) => void;
+
+  // Context menu
+  menuItems?: CardGridContextMenuItem[];
+
+  // Status
+  total?: number;              // bindable
+  loading?: boolean;           // bindable
+  onLoadError?: (error: string) => void;
+
+  // Layout
+  class?: string;
+  toolbarEnd?: Snippet;
+}
+```
+
+---
+
+## 3. State Management
+
+**Controlled/uncontrolled pairs** (same pattern as GridlerFull):
+- `searchValue` / `internalSearchValue` → `resolvedSearchValue`
+- `filters` / `internalFilters` → `resolvedFilters`
+- `sortOrder` / `internalSortOrder` → `resolvedSortOrder`
+- `selectedItems` / `internalSelectedItems` → `resolvedSelectedItems`
+
+**Server state** (port of GridlerFull lines 537-546):
+- `serverData`, `serverTotal`, `serverCursor`, `serverFetchVersion`, `serverLoading`, `serverAllLoaded`
+
+**CardGrid-specific state**:
+- `focusedIndex: $state(-1)` — keyboard-focused card
+- `anchorIndex: $state(-1)` — shift+click range anchor
+- `columnsInRow: $state(1)` — via ResizeObserver
+- `containerEl`, `sentinelEl`, `searchInputEl` — element refs
+
+---
+
+## 4. Data Fetching (Port of GridlerFull)
+
+- **Adapter instantiation**: `$derived.by` — create `GridlerResolveSpecAdapter` or `GridlerRestHeaderSpecAdapter` from `dataSourceOptions`
+- **Initial fetch `$effect`**: triggers on adapter/sort/search/filters/refreshTrigger changes → reset state → `fetchPage()`
+- **`fetchPage()`**: calls `adapter.readPage(pageSize, cursor, sort, allFilters, fields)` with cancellation via `serverFetchVersion`
+- **`loadNextPage()`**: appends results, updates cursor
+- **Infinite scroll**: IntersectionObserver on sentinel div with `rootMargin: '200px'`
+- **`refresh()` export**: increment `refreshTrigger`
+
+Filter construction reuses `gridColumnFiltersToFilterOptions()` + `buildSearchFilters()`.
+
+---
+
+## 5. Selection
+
+**Click logic**:
+- **Plain click**: select single card, set anchor
+- **Ctrl/Cmd+click**: toggle card in/out of selection
+- **Shift+click**: range select from anchor to target
+- **Background click** (`e.target === e.currentTarget`): clear selection
+- **Escape**: clear selection
+
+**Bindable output**: `selectedItems` array + `onSelectedItemsChange` callback
+
+---
+
+## 6. Selection Animation (CSS Transitions)
+
+```css
+.cg-card {
+  transition: transform 150ms ease, box-shadow 150ms ease, border-color 150ms ease;
+  border: 2px solid transparent;
+}
+
+.cg-card-selected {
+  border-color: var(--color-primary-500);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--color-primary-500) 25%, transparent);
+  transform: scale(1.02);
+}
+
+.cg-card-focused {
+  outline: 2px solid var(--color-primary-400);
+  outline-offset: 2px;
+}
+```
+
+Selected = animated ring + subtle scale lift. Focused = outline ring (distinct from selection).
+
+---
+
+## 7. Keyboard Navigation
+
+Container gets `tabindex="0"` + `onkeydown`. `columnsInRow` computed via ResizeObserver.
+
+| Key | Action |
+|-----|--------|
+| ←/→ | Move focus left/right |
+| ↑/↓ | Move focus up/down by `columnsInRow` |
+| Enter | Trigger `onCardClick` on focused card |
+| Space | Toggle selection on focused card |
+| Escape | Clear selection, blur focus |
+| Tab/Shift+Tab | Move focus forward/backward |
+| Ctrl+A | Select all loaded cards |
+| Ctrl+F | Focus search input |
+
+After focus change: `scrollIntoView({ block: 'nearest', behavior: 'smooth' })`.
+
+Search input stops keydown propagation for its own keys to avoid grid nav conflicts.
+
+---
+
+## 8. Filter Panel (`CardGridFilterPanel.svelte`)
+
+- Opened via toolbar "Filters" button → BetterMenu popup (snippet-renderer pattern from GridlerFull line 406)
+- Shows filterable columns with operator dropdown (same 14 operators as GridlerFull)
+- Add/remove/edit filter rows
+- Apply/Cancel/Clear buttons
+- Emits updated `GridColumnFilters` object
+
+---
+
+## 9. Context Menu
+
+- Right-click on card → `BetterMenu.show()` with card data
+- Built-in items: Refresh, Clear Search (if active), Clear Filters (if active), Clear Sort (if active)
+- Custom items from `menuItems` prop prepended with separator
+
+---
+
+## 10. Template Structure
+
+```
+┌─ Toolbar ────────────────────────────────────────────────┐
+│ [Search input]  [Sort pills...]  [Filters (n)]  [↻] N items │
+└──────────────────────────────────────────────────────────┘
+┌─ Card Grid (role="listbox", tabindex="0") ──────────────┐
+│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐                    │
+│ │ Card │ │ Card │ │ Card │ │ Card │  ← auto-fill grid   │
+│ └──────┘ └──────┘ └──────┘ └──────┘                    │
+│ ┌──────┐ ┌──────┐ ┌──────┐                             │
+│ │ Card │ │ Card │ │ Card │                              │
+│ └──────┘ └──────┘ └──────┘                             │
+│ [sentinel]                                              │
+└──────────────────────────────────────────────────────────┘
+┌─ Page loading indicator ─────────────────────────────────┐
+│ Loading more...                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+States: skeleton (first load), empty, cards, loading-more (subsequent pages).
+
+---
+
+## Implementation Order
+
+1. `cardGrid.ts` — types + helpers (no Svelte deps)
+2. `DefaultCard.svelte` — simple presentational
+3. `CardGridFilterPanel.svelte` — self-contained filter UI
+4. `CardGrid.svelte` — main component (depends on all above + Gridler adapters/utils)
+5. `index.ts` — barrel exports
+6. Update `src/lib/components/index.ts`
+
+---
+
+## Verification
+
+```bash
+cd packages/svelix && pnpm run check   # TypeScript + Svelte type check
+cd packages/svelix && pnpm run test    # Vitest
+```
+
+Manual: drop `<CardGrid>` into a page with a known schema/entity. Verify:
+- Cards render with data
+- Search filters results server-side
+- Sort pills toggle direction, re-fetch
+- Filter panel applies/clears filters
+- Click selects card with animation
+- Ctrl+click multi-selects
+- Shift+click range selects
+- Arrow keys navigate, Space toggles, Enter activates
+- Scroll to bottom loads next page
+- Right-click shows context menu
+- Refresh button reloads data

package/package.json

@@ -1,8 +1,26 @@
 {
   "name": "@warkypublic/svelix",
-  "version": "0.1.44",
+  "version": "0.1.46",
   "description": "Svelte 5 component library with Skeleton UI and Tailwind CSS",
   "license": "Apache-2.0",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build && pnpm run package",
+    "preview": "vite preview",
+    "package": "svelte-kit sync && svelte-package && mkdir -p dist/css && cp src/lib/css/tailwind-source.css dist/css/tailwind-source.css && publint",
+    "prepublishOnly": "npm run package",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run --project unit",
+    "test:unit": "vitest run --project unit",
+    "test:watch": "vitest --project unit",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -84,22 +102,5 @@
     "isomorphic-dompurify": "^3.13.0",
     "katex": "^0.16.47",
     "monaco-editor": "^0.55.1"
-  },
-  "scripts": {
-    "dev": "vite dev",
-    "build": "vite build && pnpm run package",
-    "preview": "vite preview",
-    "package": "svelte-kit sync && svelte-package && mkdir -p dist/css && cp src/lib/css/tailwind-source.css dist/css/tailwind-source.css && publint",
-    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
-    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
-    "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "test": "vitest run --project unit",
-    "test:unit": "vitest run --project unit",
-    "test:watch": "vitest --project unit",
-    "test:e2e": "playwright test",
-    "test:e2e:ui": "playwright test --ui"
   }
 }