@kronor/dtv 0.2.9

package/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*.{ts, tsx, json}]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false

package/.github/copilot-instructions.md

@@ -0,0 +1,64 @@
+# Copilot Instructions for dtv
+
+## Project Overview
+- This is a React + TypeScript monorepo using Vite for development/build, Playwright for E2E tests, and Jest for unit tests.
+- The core domain is a declarative, schema-driven table view system for filtering, displaying, and interacting with data collections.
+- Major code is in `src/`, with key subfolders:
+  - `src/framework/`: Table/view schema, filter logic, state, and data fetching.
+  - `src/components/`: UI components, including filter forms, AI assistant, and table rendering.
+  - `src/views/`: View definitions, each exporting a `View` object with schema, columns, and query config.
+
+## Key Patterns & Conventions
+- **Filter Schema**: Filters are defined in `FilterFieldSchema` objects, with each filter requiring an `aiGenerated: boolean` field. See `src/framework/filters.ts` for types and helpers.
+- **AI Integration**: The AI assistant (see `src/components/AIAssistantForm.tsx` and `src/components/aiAssistant.ts`) can generate filters, which must set `aiGenerated: true`.
+- **View Registration**: Views can be defined in two formats:
+  - **TSX Format** (legacy): Each view exports a `View` object with schema, columns, and query config
+  - **JSON Format** (new): Views are organized in folders with `view.json` (schema) and `runtime.tsx` (cell renderers)
+  - See `src/views/simple-test-view/` and `src/views/request-log/` for JSON format examples
+  - See `src/views/payment-requests/` for TSX format example
+- **Type Safety**: All filter and view schemas are strongly typed. When adding new filters, always specify all required fields.
+- **Cell Renderers**: All cell renderers receive `setFilterState` as a required prop, allowing them to programmatically update filter state when users interact with table cells.
+
+## Testing & Code Quality
+- **Unit Tests**: Run with `npm run test-unit` (Jest)
+- **E2E Tests**: Run with `npm test` or `npm run test` (Playwright)
+- **Linting**: Run with `npm run lint` (ESLint with TypeScript)
+- E2E test files are located in `e2e/` directory
+- Unit test files use `.test.ts` or `.test.tsx` extensions
+- The file `COPILOT_TEST_COMMAND.txt` in the repo root also specifies the canonical unit test command for AI tools.
+
+### Linting & Code Standards
+- ESLint is configured with TypeScript, React hooks, and React refresh rules
+- Pre-commit hooks automatically run linting and tests before commits
+- CI pipeline runs linting, unit tests, and E2E tests on push/PR
+- **EditorConfig**: Follow `.editorconfig` formatting rules for all files:
+  - Use 4 spaces for indentation (TypeScript, TSX, JSON)
+  - UTF-8 encoding with LF line endings
+  - Insert final newline and trim trailing whitespace
+  - When generating or editing JSON files, always use 4-space indentation to match project standards
+- Key rules:
+  - `@typescript-eslint/no-explicit-any` is disabled to allow `any` types when needed
+  - Use `@ts-expect-error` with descriptive comments instead of `@ts-ignore`
+  - React Hook dependency warnings can be suppressed with `// eslint-disable-next-line react-hooks/exhaustive-deps` when intentional
+  - Fast refresh warnings are acceptable (non-blocking) for files that export both components and utilities
+
+## Integration & Data Flow
+- Data is fetched via GraphQL using `graphql-request` (see `src/framework/data.ts`).
+- Views define their own GraphQL queries and filter schemas.
+- Filter expressions are serialized/deserialized using helpers in `src/framework/filters.ts`.
+
+## Project-Specific Advice
+- Always update all usages of schema types when changing filter/view schema fields.
+- When adding new filters, ensure `aiGenerated` is set appropriately.
+- Use the helpers in `src/framework/filters.ts` for building filter expressions and controls.
+- All cell renderers must accept `setFilterState` as a required prop for programmatic filter updates.
+- For new E2E tests, add Playwright specs in `e2e/`.
+- For new unit tests, add Jest specs with `.test.ts` or `.test.tsx` extensions.
+
+## Examples
+- See `src/views/paymentRequest.tsx` for a full-featured view definition.
+- See `src/components/AIAssistantForm.tsx` for AI-driven filter generation.
+- See `src/framework/filters.ts` for filter schema/type definitions and utilities.
+
+---
+If you are unsure about a workflow or convention, check for a helper or type in `src/framework/` or look for examples in `src/views/` and `src/components/`.

package/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    timeout-minutes: 60
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [20.x]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build application
+        run: npm run build
+
+      - name: Run linting
+        run: npm run lint
+
+      - name: Run unit tests
+        run: npm run test-unit
+
+      # - name: Install Playwright browsers
+      #   run: npx playwright install --with-deps
+
+      # - name: Run Playwright tests
+      #   run: npx playwright test
+
+      - uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30

package/.husky/pre-commit

@@ -0,0 +1,8 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+# Run linting first
+npm run lint
+
+# Run tests if linting passes
+npm test && npm run test-unit

package/README.md

@@ -0,0 +1,63 @@
+# Declarative Table View System
+
+This project is a React + TypeScript monorepo for building schema-driven, declarative table views with advanced filtering, data fetching, and AI-assisted filter generation.
+
+## Project Overview
+- **Framework:** React, TypeScript, Vite
+- **Testing:** Jest (unit), Playwright (E2E)
+- **Core Domain:** Declarative, schema-driven table view system for filtering, displaying, and interacting with data collections.
+- **Key Directories:**
+  - `src/framework/`: Table/view schema, filter logic, state, and data fetching.
+  - `src/components/`: UI components, including filter forms, AI assistant, and table rendering.
+  - `src/views/`: View definitions, each exporting a `View` object with schema, columns, and query config.
+
+## Key Patterns & Conventions
+- **Filter Schema:** Filters are defined in `FilterFieldSchema` objects. Each filter requires an `aiGenerated: boolean` field. See `src/framework/filters.ts` for types and helpers.
+- **AI Integration:** The AI assistant (see `src/components/AIAssistantForm.tsx` and `src/components/aiAssistant.ts`) can generate filters, which must set `aiGenerated: true`.
+- **View Registration:** Each view (e.g., `paymentRequest.tsx`) exports a `View` object with a `filterSchema`, `columnDefinitions`, and a GraphQL query.
+- **Type Safety:** All filter and view schemas are strongly typed. When adding new filters, always specify all required fields.
+
+## Integration & Data Flow
+- Data is fetched via GraphQL using `graphql-request` (see `src/framework/data.ts`).
+- Views define their own GraphQL queries and filter schemas.
+- Filter expressions are serialized/deserialized using helpers in `src/framework/filters.ts`.
+ - Unified URL Filter Param: Both share links and persistence use a single base64 URL-safe encoded parameter `dtv-filter-state`. Enable syncing by passing `syncFilterStateToUrl: true` to `renderTableView` (or `?sync-filter-state-to-url=true` in dev). The param is updated only when filters are applied (not on every change). When disabled, a one-off link is consumed (param removed after load).
+
+## Development
+
+### Install dependencies
+```sh
+npm install
+```
+
+### Environment Variables
+Create a `.env.development` file in the project root to set environment variables for local development (e.g., API endpoints, feature flags, secrets).
+
+Example:
+```env
+VITE_GRAPHQL_HOST=https://your-graphql-host.example.com
+VITE_GRAPHQL_TOKEN=your-graphql-token-here
+VITE_GEMINI_API_KEY=your-gemini-api-key-here
+```
+
+### Start development server
+```sh
+npm run dev
+```
+
+### Run unit tests
+```sh
+npm run test-unit
+```
+
+### Run E2E tests (Playwright)
+```sh
+npm test
+# or
+npm run test
+```
+
+## Examples
+- See `src/views/paymentRequest.tsx` for a full-featured view definition.
+- See `src/components/AIAssistantForm.tsx` for AI-driven filter generation.
+- See `src/framework/filters.ts` for filter schema/type definitions and utilities.

package/docs/api/README.md

@@ -0,0 +1,32 @@
+# View DSL API Documentation
+
+This folder contains detailed API documentation for the runtime extension points of the View DSL:
+
+- Cell Renderers (`cellRenderers`)
+- Runtime Object (`Runtime`)
+- No Rows Components (`noRowsComponents` and per-view `noRowsComponent`)
+- Custom Filter Components (`customFilterComponents`)
+- Query Transforms (`queryTransforms`)
+- Initial Values (`initialValues`)
+ - Static Conditions (`staticConditions` on a View)
+
+Each extension point is referenced from JSON view definitions using a Runtime Reference object:
+
+```jsonc
+{
+    "section": "cellRenderers", // one of: cellRenderers, noRowsComponents, customFilterComponents, queryTransforms, initialValues
+    "key": "transaction"        // the key inside the runtime section
+}
+```
+
+Resolution precedence: External (per-app) runtime overrides Built-in runtime. If the key is missing in both, an error is thrown listing available keys.
+
+---
+
+## Files
+- `cell-renderers.md` — How to write cell renderer functions and available helper components.
+- `runtime.md` — Structure of the `Runtime` object and how runtime references are resolved.
+- `no-rows-component.md` — Authoring components shown when a view returns zero rows.
+ - `static-conditions.md` — Defining always-on GraphQL boolean expressions via `staticConditions`.
+
+Add additional docs here for transforms, custom filters, etc. as needed.

package/docs/api/cell-renderers.md

@@ -0,0 +1,121 @@
+# Cell Renderer API
+
+Cell renderers are React functions responsible for rendering the contents of each table cell.
+They are referenced from JSON view definitions via a runtime reference of the form:
+
+```jsonc
+{
+    "section": "cellRenderers",
+    "key": "transaction"
+}
+```
+
+The runtime must expose a matching function under `runtime.cellRenderers.transaction`.
+
+## Type Signature
+```
+import { CellRenderer } from "src/framework/column-definition";
+
+export type CellRenderer = (props: CellRendererProps) => React.ReactNode;
+
+export type CellRendererProps = {
+  data: Record<string, any>;
+  setFilterState: (updater: (current: FilterState) => FilterState) => void;
+  applyFilters: () => void;
+  updateFilterById: (filterId: string, updater: (currentValue: any) => any) => void;
+  createElement: typeof React.createElement;
+  components: { Badge; FlexRow; FlexColumn; Mapping; DateTime; CurrencyAmount; Link; };
+  currency: { majorToMinor: (major: number, code: string, locale?: string) => number; minorToMajor: (minor: number, code: string, locale?: string) => number };
+};
+```
+
+### Provided Props
+- `data`: Object containing the resolved data fields for this column. Its structure is derived from the column's `data` field array in the JSON definition. For nested/query configs additional keys may be present (e.g. `attempts.cardType`).
+- `setFilterState(updater)`: Low-level state setter for the full filter map. Prefer `updateFilterById` for targeted updates.
+- `applyFilters()`: Triggers a new data fetch after mutating filter state programmatically.
+- `updateFilterById(filterId, updater)`: Focused helper to update the internal form state of a single filter (tree structure) in-place.
+- `createElement`: Re-exported `React.createElement` for advanced dynamic element factories (rarely needed).
+- `components`: Convenience bundle of commonly used primitives:
+  - `Badge` (`Tag` from PrimeReact) — for status-like labels
+  - `FlexRow` / `FlexColumn` — layout helpers with gap/align/justify props
+  - `Mapping` — map raw values to labels (`<Mapping value={merchantId} map={{1: 'Boozt'}} />`)
+  - `DateTime` — localized date/time formatting
+  - `CurrencyAmount` — currency formatting with `Intl.NumberFormat`
+  - (prop) `currency` — helpers for unit conversion (major/minor units)
+  - `Link` — styled anchor element
+
+## Creating a Cell Renderer
+```tsx
+// runtime.tsx
+export const myRuntime: Runtime = {
+    cellRenderers: {
+        // Example where the GraphQL field "amountMinor" is stored in minor units (e.g. cents)
+        amount: ({
+            data: { currency, amountMinor },
+            components: { FlexRow, CurrencyAmount },
+            currency: { minorToMajor }
+        }) => {
+            // Convert minor (integer) units to major for display using provided helper
+            const majorAmount = minorToMajor(amountMinor, currency);
+            return (
+                <FlexRow justify="end">
+                    <CurrencyAmount amount={majorAmount} currency={currency} />
+                </FlexRow>
+            );
+        }
+    },
+    queryTransforms: {},
+    noRowsComponents: {},
+    customFilterComponents: {},
+    initialValues: {}
+};
+```
+
+If your amount field already arrives as a major unit (e.g. 123.45 for USD) you can skip the `minorToMajor` call and pass it directly to `CurrencyAmount`.
+
+## Referencing in JSON View
+```jsonc
+{
+  "data": [ { "type": "field", "path": "currency" }, { "type": "field", "path": "amount" } ],
+  "name": "Amount",
+  "cellRenderer": { "section": "cellRenderers", "key": "amount" }
+}
+```
+
+## Programmatic Filtering Example
+A cell renderer can trigger a filter update upon interaction:
+```tsx
+initiatedBy: ({ data, updateFilterById, applyFilters, components: { FlexRow, FlexColumn } }) => {
+  const handleEmailClick = () => {
+    updateFilterById('customer-email', current => ({
+      ...current,
+      value: { operator: '_eq', value: data['customer.email'] }
+    }));
+    applyFilters();
+  };
+  return (
+    <FlexRow align="center">
+      <FlexColumn>
+        <span className="tw:font-bold">{data['customer.name']}</span>
+        <button className="tw:text-blue-500 tw:underline" onClick={handleEmailClick}>
+          {data['customer.email']}
+        </button>
+      </FlexColumn>
+    </FlexRow>
+  );
+}
+```
+
+## Data Shape Notes
+- Each `data` entry in the column definition becomes a property on the `data` object using its `path`.
+- For `queryConfigs`, nested results may be flattened (e.g. `attempts.cardType`). The exact flattening logic mirrors the GraphQL query builder.
+
+## Best Practices
+- Keep renderers pure (avoid side effects except in event handlers).
+- Pull layout primitives from `components` to stay consistent.
+- Guard against missing fields (`data.someKey ?? '-'`).
+- Limit expensive computations; precompute in transforms/query if possible.
+- Use `updateFilterById` + `applyFilters` for instant filtering interactions.
+
+## Error Handling
+If a reference key is missing, parsing the JSON view will throw an error listing available keys, preventing runtime ambiguity.

package/docs/api/no-rows-component.md

@@ -0,0 +1,71 @@
+# No Rows Component API
+
+A No Rows Component renders contextual UI when a view's data query returns zero rows.
+It can guide the user to broaden filters, change date ranges, or provide helpful links.
+
+## Type Signature
+Defined in `src/framework/view.ts`:
+```
+export type NoRowsComponentProps = {
+  setFilterState: (updater: (current: FilterState) => FilterState) => void;
+  filterState: FilterState;
+  applyFilters: () => void;
+  updateFilterById: (filterId: string, updater: (current: FilterFormState) => FilterFormState) => void;
+};
+export type NoRowsComponent = (props: NoRowsComponentProps) => React.ReactNode;
+```
+
+In a runtime, entries live under `runtime.noRowsComponents`:
+```ts
+noRowsComponents: {
+  noRowsExtendDateRange: NoRowsExtendDateRange
+}
+```
+
+## Referencing in View JSON
+```jsonc
+"noRowsComponent": { "section": "noRowsComponents", "key": "noRowsExtendDateRange" }
+```
+
+## Example Component
+`src/views/payment-requests/components/NoRowsExtendDateRange.tsx`:
+```tsx
+const NoRowsExtendDateRange = ({ updateFilterById, applyFilters }) => {
+  const handleExtend = () => {
+    updateFilterById('date-range', currentFilter => {
+      if (currentFilter.type === 'and' && currentFilter.children.length > 0) {
+        const firstChild = currentFilter.children[0];
+        if (firstChild.type === 'leaf') {
+          const d = new Date(firstChild.value); d.setMonth(d.getMonth() - 1);
+          return { ...currentFilter, children: [{ ...firstChild, value: d }, ...currentFilter.children.slice(1)] };
+        }
+      }
+      return currentFilter;
+    });
+    applyFilters();
+  };
+  return (
+    <FlexColumn align="center" justify="center" className="py-8 text-gray-400">
+      <span>No data rows match the current filter.</span>
+      <Button label="Extend the date range back by 1 month" onClick={handleExtend} size="small" />
+    </FlexColumn>
+  );
+};
+```
+
+## When to Use
+- Suggesting filter adjustments (expand date range, clear a value).
+- Offering quick actions (e.g. buttons to reset filters).
+- Providing guidance (links to documentation or onboarding steps).
+
+## Best Practices
+- Keep height modest; avoid pushing layout drastically.
+- Provide at most 1–2 primary actions.
+- Don't auto-modify filters without explicit user interaction.
+- Use neutral/secondary styling to differentiate from loaded data states.
+
+## Advanced Interactions
+You have full access to the current filter tree via `filterState` if deeper introspection is required (e.g. determining which specific filter is most restrictive). Modify only what is necessary for clarity.
+
+## Error Handling
+If the referenced key is missing in the runtime, parsing the view JSON will throw with available keys to aid discovery.

package/docs/api/runtime.md

@@ -0,0 +1,78 @@
+# Runtime Object
+
+The `Runtime` aggregates all pluggable functions and components that a JSON view can reference.
+It is defined in `src/framework/runtime.ts`:
+
+```ts
+export type Runtime = {
+  cellRenderers: Record<string, CellRenderer | React.ComponentType<any>>;
+  queryTransforms: Record<string, { toQuery: (input: any) => TransformResult }>;
+  noRowsComponents: Record<string, NoRowsComponent | React.ComponentType<any>>;
+  customFilterComponents: Record<string, React.ComponentType<any>>;
+  initialValues: Record<string, any>;
+};
+```
+
+## Sections
+| Section | Purpose | Reference Usage | Value Type |
+|---------|---------|-----------------|------------|
+| `cellRenderers` | Render table cells | Column `cellRenderer` | `(props) => ReactNode` |
+| `queryTransforms` | Preprocess raw filter form values into GraphQL-ready values | Filter expression `transform` | `{ toQuery(input) => { value, operator?, ... } }` |
+| `noRowsComponents` | UI when a data query yields zero rows | View `noRowsComponent` | `(props) => ReactNode` |
+| `customFilterComponents` | Custom input widgets inside filter forms | Filter control `{ type: 'custom' }` | React component |
+| `initialValues` | Dynamic initial values resolved at parse time | Any `initialValue` field | any |
+
+## Resolution Precedence
+When parsing a view JSON, runtime references are resolved via:
+1. External runtime passed to the <ViewRenderer /> (if any)
+2. Built-in (view-specific) runtime exported alongside the JSON
+
+If a key does not exist in either location an error is thrown with a list of known keys for that section.
+
+## Example Runtime
+```tsx
+export const paymentRequestsRuntime: Runtime = {
+  cellRenderers: { /* ... */ },
+  queryTransforms: {
+    reference: { toQuery: input => input.operator === '_like' ? { value: { value: `${input.value}%` } } : { value: input } },
+    amount: { toQuery: input => input ? { value: input * 100 } : { value: input } }
+  },
+  noRowsComponents: { noRowsExtendDateRange: NoRowsExtendDateRange },
+  customFilterComponents: { phoneNumberFilter: PhoneNumberFilter },
+  initialValues: {
+    dateRangeStart: (() => { const d = new Date(); d.setMonth(d.getMonth()-1); return d; })(),
+    dateRangeEnd: new Date()
+  }
+};
+```
+
+## Adding a New Section Entry
+```ts
+// Add a transform
+runtime.queryTransforms.orderId = {
+  toQuery: (input) => input ? { value: input.trim().toUpperCase() } : { value: input }
+};
+```
+
+## Transform Contract
+A transform receives the raw leaf value (or structured operator object for custom operator controls) and returns an object merged into the GraphQL boolean expression builder. Common pattern:
+```ts
+{ toQuery: (input) => ({ value: input }) }
+```
+You can wrap/reshape the value as needed (e.g. apply wildcards, multiply for minor units, split strings, etc.).
+
+## Initial Values via Runtime Reference
+Any `initialValue` field inside filter controls can be replaced with a runtime reference:
+```jsonc
+"initialValue": { "section": "initialValues", "key": "dateRangeStart" }
+```
+This allows dynamic (computed at parse time) defaults.
+
+## Debugging Missing References
+If parsing fails with: `Reference "foo" not found in cellRenderers. Available keys: a,b,c` verify:
+- The key exists in either runtime instance.
+- The JSON `section` name matches the correct section.
+- There are no typos (keys are case-sensitive).
+
+## Testing
+See `runtime-reference.test.ts` for validation tests around resolution and error messages.

package/e2e/app.spec.ts

@@ -0,0 +1,6 @@
+import { test, expect } from '@playwright/test';
+
+test('basic test', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.locator('body')).toBeVisible(); // Replace with a more specific selector for your app
+});

package/e2e/cell-renderer-setfilterstate.spec.ts

@@ -0,0 +1,63 @@
+import { test, expect } from '@playwright/test';
+import { mockPaginationGraphQL } from './graphqlMock';
+
+test.describe('Cell Renderer setFilterState', () => {
+    test('should allow cell renderers to programmatically set filter state', async ({ page }) => {
+        // Intercept the GraphQL request and mock the response
+        await page.route('**/v1/graphql', mockPaginationGraphQL);
+
+        // Navigate to the page
+        await page.goto('/?test-view=simple-test-view');
+
+        // Wait for the table to be present and visible
+        const table = page.getByRole('table');
+        await expect(table).toBeVisible();
+
+        // Verify initial state - all rows should be visible
+        await expect(table.getByText('Test 30', { exact: true })).toBeVisible();
+        await expect(table.getByText('Test 29', { exact: true })).toBeVisible();
+        await expect(table.getByText('Test 28', { exact: true })).toBeVisible();
+
+        // Note: This test verifies that the table renders correctly with the new required prop
+        // In a real implementation, you would:
+        // 1. Create a cell renderer that has a clickable element
+        // 2. Click that element to trigger setFilterState
+        // 3. Verify that the filter state changes accordingly
+
+        // Test that filters work normally (ensuring our changes don't break existing functionality)
+        // Show filters first
+        await page.getByText('Filters', { exact: true }).click();
+
+        // Find the Amount input and apply a filter (simple-test-view shows filters by default)
+        const amountLabel = page.getByText('Amount', { exact: true });
+        const amountInput = amountLabel.locator('..').locator('~ div input');
+        await amountInput.fill('260');
+        await amountInput.press('Enter');
+
+        // Assert that only the filtered rows are visible
+        await expect(table.getByText('Test 30', { exact: true })).toBeVisible();
+        await expect(table.getByText('Test 27', { exact: true })).toBeVisible();
+        await expect(table.getByText('Test 25', { exact: true })).not.toBeVisible();
+    });
+
+    test('should maintain table functionality with required setFilterState prop', async ({ page }) => {
+        // Intercept the GraphQL request and mock the response
+        await page.route('**/v1/graphql', mockPaginationGraphQL);
+
+        // Navigate to the payment request view which has more complex cell renderers
+        await page.goto('/?test-view=payment-requests');
+
+        // Wait for the table to be present and visible
+        const table = page.getByRole('table');
+        await expect(table).toBeVisible();
+
+        // Verify that the table headers are rendered correctly
+        await expect(table.getByText('Transaction')).toBeVisible();
+        await expect(table.getByText('Status')).toBeVisible();
+        await expect(table.getByText('Amount')).toBeVisible();
+
+        // Verify that cell renderers are working (they now receive setFilterState as required prop)
+        // The fact that the page loads without errors indicates our changes are working
+        await expect(table).toBeVisible();
+    });
+});