@keenmate/web-grid 1.0.0-rc15 → 1.0.1

package/ai/sorting-filtering-pagination.txt

@@ -0,0 +1,375 @@
+SORTING, FILTERING, AND PAGINATION
+===================================
+Reference for @keenmate/web-grid sorting, filtering, pagination, server-side
+data, and summary bar features. All properties are set via JavaScript on the
+<web-grid> element. See basic-setup.txt for installation and imports.
+
+
+SORTING
+-------
+Sorting is controlled by two grid-level properties and one per-column flag.
+
+Grid properties:
+  sortMode    String. Default: 'none'. Values: 'none', 'single', 'multi'.
+              'none' disables sorting entirely.
+              'single' allows one column sorted at a time.
+              'multi' allows multiple columns sorted simultaneously.
+
+  sort        Array of SortState objects. Default: [].
+              Each entry: { column: string, direction: 'asc' | 'desc' }
+              Set this to provide initial sort or reflect server-side sort.
+              Readable and writable at any time.
+
+Per-column flag:
+  isSortable  Boolean on column definition. When set, this column participates
+              in sorting when the grid's sortMode is 'single' or 'multi'.
+
+User interaction:
+  - Click a sortable column header: sets that column as the sole sort (asc).
+  - Click the same header again: toggles to desc.
+  - Click the same header a third time: clears sorting.
+  - Ctrl+Click (or Cmd+Click) in multi mode: adds the column to the existing
+    sort. If already sorted asc, toggles to desc. If already desc, removes it.
+
+When sorting changes, the grid resets currentPage to 1 and fires the
+ondatarequest callback with trigger='sort'.
+
+Client-side sorting (default): the grid sorts items automatically using
+localeCompare for strings, numeric comparison for numbers, and string
+coercion as fallback. Multi-column sort compares columns in priority order.
+
+Server-side sorting: set ondatarequest to fetch data from your server.
+The detail.sort array tells you the requested sort state.
+
+Example -- enable multi-column sort with initial state:
+
+  const grid = document.getElementById('grid')
+  grid.sortMode = 'multi'
+  grid.sort = [
+    { column: 'lastName', direction: 'asc' },
+    { column: 'firstName', direction: 'asc' }
+  ]
+  grid.columns = [
+    { field: 'lastName', title: 'Last Name', isSortable: true },
+    { field: 'firstName', title: 'First Name', isSortable: true },
+    { field: 'notes', title: 'Notes', isSortable: false }
+  ]
+
+Sort state type:
+
+  type SortState = {
+    column: string        // field name
+    direction: 'asc' | 'desc'
+  }
+
+
+FILTERING
+---------
+Filtering adds a text input below each column header. Typing into it filters
+rows by that column using case-insensitive substring matching.
+
+Grid property:
+  isFilterable  Boolean. Default: false. Set to true to show filter row.
+
+Per-column flag:
+  isFilterable  Boolean on column definition. Set to false to hide the filter
+                input for a specific column while the grid-level filter row is
+                visible.
+
+Client-side filtering (default): the grid filters items before sorting and
+pagination. For each active filter, the cell value is converted to a string
+and tested for case-insensitive inclusion of the filter text.
+
+Server-side filtering: use the ondatarequest callback. The filters are
+currently managed client-side in the grid's internal state. For server-side
+filtering, listen to ondatarequest and apply your own filter logic on the
+server.
+
+Example:
+
+  grid.isFilterable = true
+  grid.columns = [
+    { field: 'name', title: 'Name', isFilterable: true },
+    { field: 'email', title: 'Email', isFilterable: true },
+    { field: 'actions', title: '', isFilterable: false }
+  ]
+
+
+PAGINATION
+----------
+Pagination splits items across pages. Supports both client-side slicing and
+server-side data fetching.
+
+Grid properties:
+
+  isPageable          Boolean. Default: false. Enables pagination.
+
+  pageSize            Number. Default: 10. Rows displayed per page.
+
+  pageSizes           Number array. Available page sizes for the selector
+                      dropdown. Example: [10, 25, 50, 100]. If not set,
+                      the page size selector is not shown.
+
+  paginationMode      String. Default: 'client'.
+                      'client' -- the grid holds all items and slices them.
+                      'server' -- items property contains only the current
+                      page; the grid does not slice.
+
+  currentPage         Number. Default: 1. Current page, 1-based. Writable.
+                      Changing it triggers re-render. Automatically reset to
+                      1 when sort or pageSize changes.
+
+  totalItems          Number or null. Default: null. Required for server-side
+                      pagination so the grid can calculate total pages. For
+                      client-side mode, the grid uses items.length.
+
+  showPagination      Boolean or 'auto'. Default: 'auto'.
+                      true -- always show pagination bar.
+                      false -- never show.
+                      'auto' -- hide when total pages is 1 or less.
+
+  paginationPosition  String. Default: 'bottom-center'. Positions the
+                      pagination bar. Use pipe to show in multiple positions.
+                      Values: 'top-left', 'top-center', 'top-right',
+                      'bottom-left', 'bottom-center', 'bottom-right'.
+                      Example: 'top-right|bottom-right' shows pagination in
+                      both top-right and bottom-right corners.
+
+  paginationLayout    String. Controls element order inside the pagination bar.
+                      Default: 'pageSize|previous|pageInfo|next'.
+                      Elements: 'first', 'previous', 'pageInfo', 'next',
+                      'last', 'pageSize'.
+                      Example: 'first|previous|pageInfo|next|last' shows
+                      first/last buttons.
+                      Example: 'pageSize|previous|pageInfo|next' shows page
+                      size selector on the left.
+
+  paginationLabelsCallback
+                      Function. Receives context, returns partial label
+                      overrides for i18n/localization.
+
+                      Type: (context: PaginationLabelsContext) => Partial<PaginationLabels>
+
+                      PaginationLabelsContext:
+                        { currentPage, totalPages, totalItems, pageSize }
+
+                      PaginationLabels fields:
+                        first, previous, next, last, pageInfo, itemCount,
+                        perPage
+
+Example -- client-side pagination:
+
+  grid.isPageable = true
+  grid.pageSize = 25
+  grid.pageSizes = [10, 25, 50, 100]
+  grid.paginationPosition = 'bottom-center'
+  grid.paginationLayout = 'pageSize|previous|pageInfo|next'
+  grid.items = allData  // grid slices automatically
+
+Example -- custom pagination labels (i18n):
+
+  grid.paginationLabelsCallback = (ctx) => ({
+    first: 'Prvni',
+    previous: 'Predchozi',
+    next: 'Dalsi',
+    last: 'Posledni',
+    pageInfo: `Strana ${ctx.currentPage} z ${ctx.totalPages}`,
+    itemCount: `${ctx.totalItems} polozek`,
+    perPage: 'na stranku'
+  })
+
+Static labels can also be set via the labels property:
+
+  grid.labels = {
+    paginationFirst: 'First',
+    paginationPrevious: 'Previous',
+    paginationNext: 'Next',
+    paginationLast: 'Last',
+    paginationPageInfo: 'Page {current} of {total}',
+    paginationItemCount: '{count} items',
+    paginationPerPage: 'per page'
+  }
+
+
+SERVER-SIDE DATA (ondatarequest)
+--------------------------------
+The ondatarequest callback fires whenever the user changes sort, page, or
+page size. Use it to fetch data from a server.
+
+  grid.ondatarequest = (detail) => {
+    // detail is DataRequestDetail
+  }
+
+DataRequestDetail type:
+
+  {
+    sort: SortState[]           // Current sort state array
+    page: number                // Requested page (1-based)
+    pageSize: number            // Requested page size
+    trigger: DataRequestTrigger // What caused the request
+    mode: DataRequestMode       // How to handle the response
+    skip: number                // Items to skip (offset for server query)
+  }
+
+  DataRequestTrigger: 'sort' | 'page' | 'pageSize' | 'init' | 'loadMore'
+  DataRequestMode: 'replace' | 'append'
+
+The trigger field tells you what changed:
+  'sort'     -- user clicked a sortable header
+  'page'     -- user navigated to a different page
+  'pageSize' -- user changed the page size selector
+  'init'     -- initial data load (if triggered programmatically)
+  'loadMore' -- infinite scroll requested more items
+
+The mode field tells you how to apply the response:
+  'replace'  -- replace grid.items with the response (normal case)
+  'append'   -- append to grid.items (infinite scroll / loadMore)
+
+The skip field is a convenience for SQL OFFSET. For pagination it equals
+(page - 1) * pageSize. For loadMore it equals the current items.length.
+
+
+SERVER-SIDE PAGINATION SETUP
+-----------------------------
+To use server-side pagination:
+
+1. Set paginationMode to 'server'.
+2. Set totalItems to the total row count from the server.
+3. Set items to only the current page of data.
+4. Implement ondatarequest to fetch new pages from the server.
+
+Example:
+
+  const grid = document.getElementById('grid')
+
+  // Configure grid
+  grid.columns = [
+    { field: 'id', title: 'ID', width: '80px', isSortable: true },
+    { field: 'name', title: 'Name', isSortable: true },
+    { field: 'email', title: 'Email', isSortable: true }
+  ]
+  grid.isPageable = true
+  grid.pageSize = 25
+  grid.pageSizes = [10, 25, 50, 100]
+  grid.paginationMode = 'server'
+  grid.sortMode = 'single'
+  grid.paginationLayout = 'pageSize|first|previous|pageInfo|next|last'
+
+  // Fetch data from server
+  async function loadData(detail) {
+    const params = new URLSearchParams({
+      page: detail.page,
+      pageSize: detail.pageSize,
+      skip: detail.skip
+    })
+
+    // Add sort parameters
+    if (detail.sort.length > 0) {
+      params.set('sortField', detail.sort[0].column)
+      params.set('sortDir', detail.sort[0].direction)
+    }
+
+    const response = await fetch(`/api/users?${params}`)
+    const data = await response.json()
+
+    grid.items = data.rows        // Current page only
+    grid.totalItems = data.total  // Total count for pagination
+  }
+
+  // Handle user interactions (page change, sort, page size change)
+  grid.ondatarequest = (detail) => {
+    loadData(detail)
+  }
+
+  // Initial load
+  loadData({ page: 1, pageSize: 25, skip: 0, sort: [], trigger: 'init', mode: 'replace' })
+
+
+SUMMARY BAR
+-----------
+The summary bar displays custom content (totals, aggregates, metadata) in a
+configurable position, optionally sharing a row with the pagination bar.
+
+Grid properties:
+
+  summaryPosition     String. Position(s) for the summary bar.
+                      Values: 'top-left', 'top-center', 'top-right',
+                      'bottom-left', 'bottom-center', 'bottom-right'.
+                      Use pipe for multiple: 'top-right|bottom-right'.
+                      Not set by default (no summary shown).
+
+  summaryContentCallback
+                      Function returning an HTML string for the summary.
+                      Receives a SummaryContext object.
+
+                      Type: (context: SummaryContext) => string
+
+                      SummaryContext:
+                        {
+                          items: T[]          // Current page items
+                          allItems: T[]       // All items (before pagination)
+                          totalItems: number
+                          currentPage: number
+                          pageSize: number
+                          metadata: unknown   // From summaryMetadata property
+                        }
+
+  isSummaryInline     Boolean. Default: true. When true, the summary shares
+                      the same row as the pagination bar when they are in the
+                      same area (e.g., both at bottom). When false, the summary
+                      gets its own row.
+
+  summaryMetadata     Any value. Default: undefined. Server-provided metadata
+                      passed through to summaryContentCallback as
+                      context.metadata. Useful for server-calculated aggregates
+                      (sums, averages) that cannot be computed client-side.
+
+Example -- client-side summary:
+
+  grid.summaryPosition = 'bottom-left'
+  grid.summaryContentCallback = (ctx) => {
+    const total = ctx.allItems.reduce((sum, row) => sum + row.amount, 0)
+    return `<strong>Total:</strong> $${total.toFixed(2)} (${ctx.totalItems} rows)`
+  }
+
+Example -- server-side summary with metadata:
+
+  grid.summaryPosition = 'bottom-right'
+  grid.summaryContentCallback = (ctx) => {
+    const meta = ctx.metadata
+    if (!meta) return ''
+    return `Sum: $${meta.sum} | Avg: $${meta.average}`
+  }
+
+  // In your ondatarequest handler:
+  grid.ondatarequest = async (detail) => {
+    const response = await fetch(`/api/data?page=${detail.page}`)
+    const data = await response.json()
+    grid.items = data.rows
+    grid.totalItems = data.total
+    grid.summaryMetadata = data.aggregates  // { sum: 12345, average: 67.8 }
+  }
+
+Example -- summary with pagination in same row:
+
+  grid.isPageable = true
+  grid.paginationPosition = 'bottom-right'
+  grid.summaryPosition = 'bottom-left'
+  grid.isSummaryInline = true  // shares the bottom row with pagination
+
+
+DATA PIPELINE ORDER
+-------------------
+When using client-side mode, the grid processes items in this order:
+
+  items --> filteredItems --> sortedItems --> paginatedItems --> displayItems
+
+1. filteredItems: applies column filters (case-insensitive substring match)
+2. sortedItems: applies multi-column sort using localeCompare / numeric compare
+3. paginatedItems: slices by currentPage and pageSize (client mode only;
+   server mode skips slicing)
+4. displayItems: adds empty row if isNewRowEnabled
+
+For server-side mode, the grid trusts that items already represents the
+correct page with correct sort and filter applied. Set items, totalItems,
+and optionally summaryMetadata after each server fetch.

package/ai/styling-theming.txt

@@ -0,0 +1,291 @@
+CSS VARIABLE ARCHITECTURE
+-------------------------
+WebGrid uses a two-level CSS variable system for theming:
+
+  Level 1: --base-* variables (cross-component theme)
+  Level 2: --wg-* variables (grid-specific)
+
+Each --wg-* variable falls back to a --base-* variable, then to a hardcoded default:
+
+  :host {
+    --wg-accent-color: var(--base-accent-color, #0078d4);
+    --wg-surface-1: var(--base-main-bg, #ffffff);
+    --wg-font-size-base: calc(var(--base-font-size-sm, 1.4) * var(--wg-rem));
+  }
+
+Priority chain:
+  1. Setting --wg-accent-color on <web-grid> overrides ONLY the grid
+  2. Setting --base-accent-color on :root themes ALL KeenMate components
+     (web-grid, web-multiselect, web-daterangepicker, etc.)
+  3. If neither is set, the hardcoded default (#0078d4) is used
+
+Example -- theme all KeenMate components at once:
+
+  :root {
+    --base-accent-color: #10b981;
+    --base-layer-1: #ffffff;
+    --base-font-family: 'Inter', sans-serif;
+  }
+
+Example -- override just the grid:
+
+  web-grid {
+    --wg-accent-color: #e11d48;
+    --wg-header-bg: #fafafa;
+  }
+
+Example -- override a specific grid instance:
+
+  web-grid#sales-grid {
+    --wg-accent-color: #7c3aed;
+  }
+
+The --wg-rem variable controls the base sizing unit. Default is 10px. All spacing,
+font sizes, and component dimensions scale proportionally from this value. Set to
+1rem for frameworks like Pure Admin where html { font-size: 10px }.
+
+
+KEY VARIABLES
+-------------
+Colors:
+  --wg-accent-color          Primary accent (focus outlines, active states, selection)
+                             Falls back to: --base-accent-color, default: #0078d4
+  --wg-text-color-1          Primary text (cells, headers)
+                             Falls back to: --base-text-color-1, default: #242424
+  --wg-text-color-2          Secondary text (row numbers, labels)
+  --wg-text-color-3          Muted text (placeholders, empty states)
+  --wg-surface-1             Main background (table body, cells)
+                             Falls back to: --base-main-bg, default: #ffffff
+  --wg-surface-2             Elevated background (headers, striped rows)
+                             Falls back to: --base-elevated-bg, default: #f5f5f5
+  --wg-surface-3             Hover background (row hover, button hover)
+  --wg-border-color          All borders (table, cells, header separators)
+                             Falls back to: --base-border-color, default: #e0e0e0
+
+Header:
+  --wg-header-bg             Header row background (defaults to --wg-surface-2)
+  --wg-header-bg-hover       Sortable header on hover
+  --wg-header-color          Header text color
+  --wg-header-border         Bottom border below header (2px solid)
+  --wg-header-padding        Header cell padding
+  --wg-header-font-weight    Header text weight (semibold)
+
+Rows:
+  --wg-row-bg-hover          Row hover when isHoverable=true (defaults to --wg-surface-3)
+  --wg-row-bg-even           Striped even rows when isStriped=true (defaults to --wg-surface-2)
+  --wg-row-border            Border between rows
+
+Typography:
+  --wg-font-family           Font for all grid text
+                             Falls back to: --base-font-family, default: inherit
+  --wg-font-size-base        Cell and editor text (14px at default scale)
+  --wg-font-size-sm          Filter inputs, pagination (12px)
+  --wg-font-size-xs          Error messages, small labels (11px)
+
+Layout:
+  --wg-cell-padding          Cell content padding (shorthand)
+  --wg-cell-padding-block    Cell vertical padding
+  --wg-cell-padding-inline   Cell horizontal padding
+  --wg-border-radius-sm      Buttons, inputs (4px)
+  --wg-border-radius-md      Dialogs, cards (6px)
+  --wg-border-radius-lg      Large elements (8px)
+
+The full list is 120+ variables. See _variables.css or the manifest for the complete set.
+
+
+DARK MODE
+---------
+Dark mode activates automatically. No configuration needed. Detection methods:
+
+  1. OS preference:      @media (prefers-color-scheme: dark)
+  2. Data attribute:     <html data-theme="dark">
+  3. Bootstrap 5.3+:     <html data-bs-theme="dark">
+  4. Tailwind CSS:       <html class="dark">
+
+All four methods apply the same dark palette overrides:
+
+  --wg-surface-1: #1f1f1f
+  --wg-surface-2: #2b2b2b
+  --wg-surface-3: #333333
+  --wg-text-color-1: #e0e0e0
+  --wg-text-color-2: #c0c0c0
+  --wg-text-color-3: #a0a0a0
+  --wg-border-color: #3d3d3d
+  --wg-input-bg: #1f1f1f
+  --wg-hover-bg: #3a3a3a
+  --wg-danger-color: #f87c86
+  --wg-danger-bg-light: #442726
+
+The attribute can be on the <web-grid> element itself or any ancestor:
+
+  <web-grid data-theme="dark">       (on the element)
+  <div data-bs-theme="dark">         (on an ancestor)
+    <web-grid></web-grid>
+  </div>
+
+If --base-* variables are set by a theme-designer dark theme, those take priority
+over the built-in dark mode overrides since --wg-* variables reference --base-*
+variables.
+
+
+DYNAMIC CELL AND ROW STYLING
+-----------------------------
+Three mechanisms for applying CSS classes to cells and rows:
+
+1. cellClass (static, per column):
+
+  grid.columns = [{
+    field: 'status',
+    cellClass: 'status-cell'
+  }]
+
+2. cellClassCallback (dynamic, per column):
+
+  grid.columns = [{
+    field: 'salary',
+    cellClassCallback: (value, row) => value > 90000 ? 'high-value' : null
+  }]
+
+3. rowClassCallback (dynamic, per row):
+
+  grid.rowClassCallback = (row, index) => {
+    if (row.status === 'inactive') return 'row-inactive'
+    if (row.isNew) return 'row-new'
+    return null
+  }
+
+IMPORTANT: These classes are applied INSIDE the Shadow DOM. External stylesheets
+cannot reach them. You MUST use customStylesCallback to define the CSS rules for
+these classes. Without it, the classes are added to elements but have no effect.
+
+
+CUSTOM STYLES INJECTION
+------------------------
+The customStylesCallback property returns a CSS string that gets injected into the
+Shadow DOM. This is the ONLY way to style custom classes from cellClassCallback or
+rowClassCallback.
+
+  grid.customStylesCallback = () => `
+    .high-value {
+      background: #d1fae5 !important;
+      font-weight: 600;
+    }
+    .row-inactive {
+      opacity: 0.5;
+    }
+    .row-new {
+      background: #fef3c7 !important;
+    }
+    .status-cell {
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+    }
+  `
+
+Notes:
+  - The callback is called during rendering and should return a CSS string
+  - Use !important on background to override hover/striped/selection styles
+  - The injected styles have access to all internal CSS classes (.wg__cell, etc.)
+  - This can also be used for general style overrides beyond custom classes
+
+Full example combining all three:
+
+  grid.columns = [
+    {
+      field: 'salary',
+      cellClass: 'numeric',
+      cellClassCallback: (value, row) => {
+        if (value > 100000) return 'salary-high'
+        if (value < 30000) return 'salary-low'
+        return null
+      }
+    },
+    {
+      field: 'status',
+      cellClassCallback: (value) => 'status-' + value
+    }
+  ]
+
+  grid.rowClassCallback = (row, index) =>
+    row.deleted ? 'row-deleted' : null
+
+  grid.customStylesCallback = () => `
+    .numeric { text-align: right; font-variant-numeric: tabular-nums; }
+    .salary-high { background: #d1fae5 !important; }
+    .salary-low { background: #fee2e2 !important; }
+    .status-active { color: #059669; }
+    .status-inactive { color: #dc2626; }
+    .row-deleted { text-decoration: line-through; opacity: 0.5; }
+  `
+
+
+COMPONENT VARIABLES MANIFEST
+-----------------------------
+A machine-readable JSON manifest documents all CSS variables consumed and exposed
+by the component. It is included in the npm package.
+
+Import path:
+
+  import manifest from '@keenmate/web-grid/manifest'
+
+Manifest structure:
+
+  manifest.component          "@keenmate/web-grid"
+  manifest.prefix             "wg"
+  manifest.baseVariables      Array of --base-* variables the component consumes
+  manifest.componentVariables Array of --wg-* variables the component exposes
+
+baseVariables entry format:
+
+  {
+    "name": "base-accent-color",
+    "required": true,
+    "usage": "Editor focus outline, active sort indicator, selected pagination button"
+  }
+
+componentVariables entry format:
+
+  {
+    "name": "wg-accent-color",
+    "category": "accent",
+    "usage": "Editor focus outline, active pagination, sorted column indicator"
+  }
+
+Counts (current):
+  - 37 baseVariables (--base-* consumed)
+  - 120+ componentVariables (--wg-* exposed)
+
+Categories in componentVariables:
+  sizing, accent, text, surface, border, input, danger, state, typography,
+  radius, spacing, table, header, cell, row, filter, sort, pagination, empty,
+  error, editor, dropdown, toolbar, inline-actions, overlay, tooltip,
+  context-menu, focus, selection, row-focus, cell-selection, row-locking,
+  freeze, resize, fill-handle, transition, z-index
+
+The manifest follows the component-variables schema:
+  https://raw.githubusercontent.com/keenmate/schemas/main/component-variables.schema.json
+
+This manifest is consumed by @keenmate/theme-designer for visual theming.
+
+
+THEME DESIGNER
+--------------
+Visual theming tool for all KeenMate components:
+
+  https://theme-designer.keenmate.dev
+
+The Theme Designer:
+  - Reads the component-variables manifest to know which variables exist
+  - Provides a visual UI for adjusting --base-* variables
+  - Generates CSS that sets --base-* on :root
+  - Changes propagate to all KeenMate components using the fallback chain
+
+Workflow:
+  1. Open theme-designer.keenmate.dev
+  2. Adjust colors, typography, spacing visually
+  3. Export generated CSS
+  4. Include the CSS in your application
+  5. All KeenMate components (web-grid, web-multiselect, etc.) pick up the theme
+
+Since --wg-* falls back to --base-*, the theme applies automatically without
+any grid-specific configuration.