@docyrus/docyrus 0.0.68 → 0.0.70

package/resources/pi-agent/skills/docyrus-cli-app/references/list-query-examples.md

@@ -0,0 +1,248 @@
+# List Query Examples
+
+Practical examples for `docyrus ds list` with columns, filters, sorting, and pagination.
+
+---
+
+## Table of Contents
+
+1. [Basic Listing](#basic-listing)
+2. [Column Selection](#column-selection)
+3. [Filtering](#filtering)
+4. [Sorting](#sorting)
+5. [Pagination](#pagination)
+6. [Combined Examples](#combined-examples)
+
+---
+
+## Basic Listing
+
+List all records with default columns:
+
+```bash
+docyrus ds list crm contacts
+```
+
+List with JSON output:
+
+```bash
+docyrus ds list crm contacts --format json
+```
+
+---
+
+## Column Selection
+
+Select specific fields:
+
+```bash
+docyrus ds list crm contacts --columns "name, email, phone"
+```
+
+Select with relation expansion (get related account's name):
+
+```bash
+docyrus ds list crm contacts --columns "name, email, related_account(account_name)"
+```
+
+Spread related fields into root object:
+
+```bash
+docyrus ds list crm contacts --columns "name, ...related_account(account_name, account_phone)"
+```
+
+Alias columns:
+
+```bash
+docyrus ds list crm contacts --columns "n:name, e:email, p:phone"
+```
+
+---
+
+## Filtering
+
+### Single field equals
+
+```bash
+docyrus ds list crm contacts --filters '{"rules":[{"field":"status","operator":"=","value":"active"}]}'
+```
+
+### Multiple conditions (AND)
+
+```bash
+docyrus ds list crm contacts --filters '{"combinator":"and","rules":[{"field":"status","operator":"=","value":"active"},{"field":"priority","operator":">=","value":3}]}'
+```
+
+### OR conditions
+
+```bash
+docyrus ds list crm contacts --filters '{"combinator":"or","rules":[{"field":"city","operator":"=","value":"Istanbul"},{"field":"city","operator":"=","value":"Ankara"}]}'
+```
+
+### IN operator (match any value in list)
+
+```bash
+docyrus ds list crm contacts --filters '{"rules":[{"field":"status","operator":"in","value":[1,2,3]}]}'
+```
+
+### Not equal
+
+```bash
+docyrus ds list crm contacts --filters '{"rules":[{"field":"status","operator":"!=","value":"archived"}]}'
+```
+
+### Text search with LIKE
+
+```bash
+docyrus ds list crm contacts --filters '{"rules":[{"field":"name","operator":"like","value":"John"}]}'
+```
+
+### Empty / not empty
+
+```bash
+docyrus ds list crm contacts --filters '{"rules":[{"field":"email","operator":"not empty"}]}'
+```
+
+```bash
+docyrus ds list crm contacts --filters '{"rules":[{"field":"phone","operator":"empty"}]}'
+```
+
+### Date shortcuts
+
+Records created this month:
+
+```bash
+docyrus ds list crm contacts --filters '{"rules":[{"field":"created_on","operator":"this_month"}]}'
+```
+
+Records created today:
+
+```bash
+docyrus ds list crm contacts --filters '{"rules":[{"field":"created_on","operator":"today"}]}'
+```
+
+Records from last 30 days:
+
+```bash
+docyrus ds list crm contacts --filters '{"rules":[{"field":"created_on","operator":"last_30_days"}]}'
+```
+
+### Date range with between
+
+```bash
+docyrus ds list crm contacts --filters '{"rules":[{"field":"created_on","operator":"between","value":["2025-01-01","2025-06-30"]}]}'
+```
+
+### Filter on related field
+
+Filter by related account's status:
+
+```bash
+docyrus ds list crm contacts --filters '{"rules":[{"field":"rel_related_account/account_status","operator":"=","value":1}]}'
+```
+
+### Current user filter
+
+Records owned by current user:
+
+```bash
+docyrus ds list crm contacts --filters '{"rules":[{"field":"record_owner","operator":"active_user"}]}'
+```
+
+### Nested AND + OR
+
+Active contacts created this month OR contacts with high priority:
+
+```bash
+docyrus ds list crm contacts --filters '{"combinator":"or","rules":[{"combinator":"and","rules":[{"field":"status","operator":"=","value":"active"},{"field":"created_on","operator":"this_month"}]},{"field":"priority","operator":">=","value":5}]}'
+```
+
+---
+
+## Sorting
+
+Sort by name ascending (default):
+
+```bash
+docyrus ds list crm contacts --orderBy "name"
+```
+
+Sort by created date descending:
+
+```bash
+docyrus ds list crm contacts --orderBy "created_on DESC"
+```
+
+---
+
+## Pagination
+
+First 10 records:
+
+```bash
+docyrus ds list crm contacts --limit 10
+```
+
+Next 10 records (page 2):
+
+```bash
+docyrus ds list crm contacts --limit 10 --offset 10
+```
+
+Get total count alongside results:
+
+```bash
+docyrus ds list crm contacts --limit 10 --fullCount true
+```
+
+---
+
+## Combined Examples
+
+### Active contacts with email, sorted by name, paginated
+
+```bash
+docyrus ds list crm contacts \
+  --columns "name, email, phone, created_on" \
+  --filters '{"rules":[{"field":"status","operator":"=","value":"active"},{"field":"email","operator":"not empty"}]}' \
+  --orderBy "name" \
+  --limit 25 \
+  --fullCount true
+```
+
+### Recent high-priority deals with account info
+
+```bash
+docyrus ds list crm deals \
+  --columns "name, amount, stage, ...related_account(account_name)" \
+  --filters '{"combinator":"and","rules":[{"field":"priority","operator":">=","value":4},{"field":"created_on","operator":"last_30_days"}]}' \
+  --orderBy "amount DESC" \
+  --limit 20
+```
+
+### Search for records by keyword
+
+```bash
+docyrus ds list crm contacts \
+  --columns "name, email, phone" \
+  --filters '{"rules":[{"field":"name","operator":"like","value":"Smith"}]}' \
+  --format json
+```
+
+### Export all records as JSON lines
+
+```bash
+docyrus ds list crm contacts \
+  --columns "id, name, email, phone, status, created_on" \
+  --format jsonl
+```
+
+### Records owned by current user, created this quarter
+
+```bash
+docyrus ds list crm tasks \
+  --columns "name, status, priority, due_date" \
+  --filters '{"combinator":"and","rules":[{"field":"record_owner","operator":"active_user"},{"field":"created_on","operator":"this_quarter"}]}' \
+  --orderBy "due_date" \
+  --limit 50
+```

package/resources/pi-agent/skills/docyrus-data-grid-page-design/SKILL.md

@@ -13,6 +13,9 @@ Build full Docyrus list pages around the web `DataGrid` stack.
    - Best when rows come from a Docyrus data source or generated collection.
    - Gives you metadata-driven columns, saved views, toolbar wiring, search, filters (with async option search for relation/user fields), grouping, sorting, row-height, display mode, paging, and reload.
    - Auto-wires reference field expansion, tenant-aware formatters, and a shared users list when supplied.
+   - Built-in inline change tracking + save banner (`trackChanges`, `onSaveChanges`).
+   - Built-in selection-bar bulk actions (`bulkActions`: `update`, `delete`, `export`) with `BulkUpdateDialog` + `RecordDeleteConfirmDialog`.
+   - Built-in server-side export menu (`enableServerExportMenu`, `exportColumns`, `exportFileName`, `serverExportLimit`).
    - Read `references/hook-pages.md`.
 
 2. **Custom layout or custom row-query lifecycle** → use `useDocyrusDataViewSelect` + `useDataGrid`.

package/resources/pi-agent/skills/docyrus-data-grid-page-design/references/hook-pages.md

@@ -88,15 +88,45 @@ Use `onReload` when you use `data` mode, because the hook cannot refetch rows on
 
 - `actionsColumn`: add per-row actions right after the select column.
 - `extraColumns`: prepend custom columns before metadata-generated Docyrus fields.
-- `mapColumn`: override or skip generated field columns.
+- `mapColumn`: override or skip generated field columns (`(field, defaultColumn) => ColumnDef | null`).
 - `defaultRowGroupingColumn`: seed a default grouping for views that do not define one.
 - `systemViews`: add static developer-defined views before saved backend views.
-- `enableViewSelect`, `enableSearchInput`, `enableFilterMenu`, `enableGroupMenu`, `enableSortMenu`, `enableRowHeightMenu`, `enableDisplayMenu`, `enableReloadButton`: trim the standard toolbar.
-- `showSelectColumn`, `enableRowMarkers`: control the left-most reserved column.
+- `enableViewSelect`, `enableSearchInput`, `enableFilterMenu`, `enableGroupMenu`, `enableSortMenu`, `enableRowHeightMenu`, `enableDisplayMenu`, `enableReloadButton`, `enableServerExportMenu`: trim the standard toolbar (all default `true`).
+- `showSelectColumn` (default `true`), `enableRowMarkers` (default `true`): control the left-most reserved column.
+- `selectColumn`: override `getDataGridSelectColumn` entirely.
+- `searchPlaceholder` (default `"Search…"`), `searchDebounceMs` (default `300`), `toolbarClassName`.
+- `enableSearch` (default `false`), `enableGrouping` (default `true`), `readOnly` (default `true`) — forwarded to `useDataGrid`.
 
 ### Query shape
 
 - `listParams`: append query params like `limit`, `fullCount`, `expand`, or custom backend flags. `listParams` overrides win against the hook's defaults, so use this to pin paging or add tenant-specific flags.
+- `defaultLimit` (default `100`): page size used when no `limit` is supplied via `listParams`.
+- `enableItemsQuery` (default `true` when no `data` prop is given): set `false` to wire the toolbar without fetching rows.
+
+### Inline change tracking
+
+- `trackChanges` (default `true`): enables the save/discard banner above the grid for inline cell edits.
+- `onSaveChanges?: (changes: Array<RowChange>, data: Array<TData>) => void | Promise<void>`: custom save handler. By default the hook batches changes into a single `PATCH /items/bulk` call (with `enableAutomation: false`, `enableChangeLogging: false`) using `collection.updateMany` when supplied, otherwise the direct items endpoint.
+
+### Bulk actions (selection bar)
+
+- `bulkActions` (default `['update', 'delete', 'export']`): array of built-in bulk actions to surface when rows are selected. Pass `false` or `[]` to hide the selection bar entirely.
+  - `update` → opens the `BulkUpdateDialog`. Calls `collection.updateMany` when present, otherwise the direct items endpoint.
+  - `delete` → opens `RecordDeleteConfirmDialog`. Calls `collection.deleteMany` when present, otherwise the direct items endpoint.
+  - `export` → opens the export menu for the selection (subset of the toolbar export).
+
+### Server export
+
+- `enableServerExportMenu` (default `true`): toolbar export dropdown that pulls all rows matching the active view's filters/keyword from `POST /v1/edge/run/query-export`.
+- `serverExportLimit` (default `10000`): row cap forwarded to the server export endpoint.
+- `serverExportExcludedFieldTypes`: field types to skip when picking export columns. Defaults to virtual / non-stored types like `field-action`.
+- `serverExportExcludedSlugs`: field slugs to skip when picking export columns. Defaults to internal metadata columns mirroring the legacy Vue exporter (`data`, `document`, `parent_data_source_id`, `parent_record_id`, `icon`, `color`, `mentions`, `followers`, `type`, `tenant_view_id`, `tenant_data_source_id`, `sort_order`, `editor_view_id`).
+- `exportColumns` (default `'visible'`): `'visible'` uses the table's currently-visible columns; `'all'` includes every data-source field; an explicit `Array<string>` of slugs picks specific fields in order.
+- `exportFileName`: file name (without extension) for exports. Defaults to `dataSourceSlug`.
+
+### Lifecycle hooks
+
+- `onReload?: () => void`: called after the reload button's internal `refetch` (data source + views + items) runs.
 
 ### Tenant-aware formatters
 
@@ -169,12 +199,26 @@ Out of the box (no `mapColumn` needed):
 
 Use `mapColumn` only when you need to override these defaults.
 
+## Hook result
+
+`useDocyrusDataGrid<TData>` returns:
+
+- `table` — TanStack Table instance. Pass to `<DataGrid>` and any toolbar building blocks.
+- `gridProps` — spread onto `<DataGrid table={table} {...gridProps} />`. Includes `actions: Array<DataGridAction<TData>>` so the floating selection bar lights up automatically when `bulkActions` are enabled.
+- `toolbar` — pre-wired toolbar `ReactNode` ready to render above the grid.
+- `items: Array<TData>` — resolved rows from `data`, `collection.list()`, or the direct items fetch.
+- `resolvedListParams: DocyrusDataGridListParams` — final params sent to the backend (after merging view state, search, and `listParams`). Use for export/analytics/copy-query.
+- `pagingMode: 'standard' | 'virtual-scroll' | undefined` — resolved paging mode for the active view. Pass to `<DataGrid pagingMode>` so the standard footer renders only when the view enables it.
+- `reload: () => void` — triggers `refetch()` (data source + views + items) and the optional `onReload` callback.
+- Plus everything from `useDocyrusDataViewSelect` except `gridViewSelectProps`: `views`, `fields`, `dataSource`, `activeViewId`, `setActiveViewId`, `isLoading`, `error`, `refetch`.
+
 ## Important behavior
 
 - `gridProps` already carries the active view's paging settings. Usually you should just spread it into `<DataGrid>`.
 - Backend-saved views store field slugs, not reserved columns like `select` or `actions`. The hook re-prepends and re-pins those reserved columns for you.
 - In `data` mode the search box becomes client-side global filtering. In backend modes it becomes `filterKeyword`.
 - The hook controls TanStack `columnFilters` state. If you build a manual page, replicate this so toolbar filter changes can drive your row query.
+- `collection.updateMany` / `collection.deleteMany` are required for bulk update/delete to use the collection layer; otherwise the hook falls back to the direct items endpoints.
 
 ## Default recommendation