@docyrus/docyrus 0.0.67 → 0.0.69

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

@@ -0,0 +1,61 @@
+---
+name: docyrus-data-grid-page-design
+description: Build Docyrus React data-grid and record-list pages with `DataGrid`, `DataGridViewSelect`, `useDataGrid`, `useDocyrusDataViewSelect`, and `useDocyrusDataGrid`. Use when asked to build or refactor a list page, records table, CRM or ERP grid, saved-view tabs, row actions, manual DataGrid toolbar composition, or Docyrus data-source grid queries with filtering, sorting, grouping, search, display modes, paging, and reload behavior.
+---
+
+# Docyrus Data Grid Page Design
+
+Build full Docyrus list pages around the web `DataGrid` stack.
+
+## Choose the build mode
+
+1. **Standard Docyrus page** → use `useDocyrusDataGrid`.
+   - 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`.
+   - Best when you need a custom toolbar arrangement, local/demo data, or a non-standard fetch cycle.
+   - Read `references/manual-pages.md`.
+
+3. **No backend saved views** → use `useDataGrid` with local `SavedDataGridView[]` or `DataGridViewMenu`.
+   - Also covered in `references/manual-pages.md`.
+
+4. **Complex Docyrus query payloads** → also load the `docyrus-api-dev` skill.
+5. **Advanced saved-view persistence or manual view-driven queries** → read `references/advanced-saved-view-query-patterns.md`.
+6. **Tenant-aware formatters and shared users list** → read `references/tenant-and-users-providers.md`.
+
+## Default page workflow
+
+1. Confirm the `appSlug`, `dataSourceSlug`, and whether a generated collection already exists.
+2. Pick hook mode or manual mode.
+3. App-level: ensure a `TenantProvider` (preferences → date/number utils) and `UsersProvider` (`/v1/users` cache) wrap the route, and pull `formatDate` / `formatDateTime` / `formatNumber` / `users` into the grid hook from those contexts.
+4. Add reserved columns in this order: select first, actions second. They are pinned left automatically by `useDocyrusDataGrid`.
+5. Keep the page in a flex column layout with the grid body wrapped in `min-h-0 flex-1`.
+6. Add create/edit/view/delete dialogs around row actions.
+7. Verify initial saved view, search, filters, grouping, sorting, paging, and reload behavior.
+
+## Non-negotiables
+
+- Render page-sized grids with the toolbar in a shrink-0 row and the grid inside `min-h-0 flex-1`.
+- Prefer `<DataGrid table={table} {...gridProps} height="auto" />` for full-page layouts.
+- Pass the TanStack `table` instance to every grid menu and to `DataGridViewSelect`.
+- `useDocyrusDataViewSelect` manages view metadata only. It does **not** fetch rows and does **not** accept `table`.
+- Manual Docyrus item queries must always send `columns`. Reference fields (`field-userSelect`, `field-userMultiSelect`, `field-relation`, `field-relatedField`, `field-select`, `field-radioGroup`, `field-enum`, `field-systemEnum`, `field-multiSelect`, `field-tagSelect`, `field-status`, `field-approvalStatus`) must also be added to the `expand` array so the API returns `{ id, name, ... }` payloads instead of bare IDs.
+- Backend saved-view filters need enum options; `useDocyrusDataViewSelect` already fetches the data source with `expand=enums`.
+- Manual pages must apply the initial active view with `applyViewToTable(table, activeView)` after views and columns are ready. User-triggered view switches through `DataGridViewSelect` are applied automatically.
+- Prefer `useDocyrusDataGrid` unless you truly need custom row fetching or custom toolbar composition. The hook handles auto-expand, async filter options, formatters, and reserved-column pinning for you.
+- When you wire manual view CRUD into `DataGridViewSelect`, pass `isSaving` and `isLoading` so the editor UX stays correct during saves and background fetches.
+- For tenant-aware date/datetime/number formatting, fetch `getTenantPreferences(client)` once at app boot and pass the resulting `formatDate` / `formatDateTime` / `formatNumber` callbacks into `useDocyrusDataGrid`.
+- For instant avatar + label rendering on user-typed cells, fetch `/v1/users` once at app boot and pass the resulting `CellUserOption[]` into `useDocyrusDataGrid` via the `users` option.
+
+## References
+
+- `references/hook-pages.md` — one-call Docyrus grid pages with direct API mode, collection mode, extension points, formatters, and shared-users wiring.
+- `references/manual-pages.md` — local/manual grid composition, local views, backend view-select wiring, and initial-view handling.
+- `references/advanced-saved-view-query-patterns.md` — saved-view persistence, system views, hidden views, paging ownership, and translating active views into manual server queries.
+- `references/tenant-and-users-providers.md` — app-level providers for tenant preferences and the shared users list, plus how to plug them into `useDocyrusDataGrid`.

package/resources/pi-agent/skills/docyrus-data-grid-page-design/references/advanced-saved-view-query-patterns.md

@@ -0,0 +1,158 @@
+# Advanced Saved-View and Query Patterns
+
+## Read this when
+
+- You need backend-saved views but do not want `useDocyrusDataGrid` to own row fetching.
+- You want system views plus user-saved views in one selector.
+- You need to debug why a saved view, grouping rule, or paging setting is not reflected in the grid.
+- You need to translate `SavedDataGridView` into a custom Docyrus items query.
+
+## Saved-view ownership model
+
+- `DataGridViewSelect` applies the selected view to the TanStack table when the user clicks a tab or dropdown item.
+- `useDocyrusDataGrid` also reapplies the active view on mount and whenever the active view changes, so the initial view works without extra code.
+- Manual pages using `useDocyrusDataViewSelect` plus `useDataGrid` must still apply the initial active view with `applyViewToTable(table, activeView)`.
+
+## System views, hidden views, and persistence
+
+`useDocyrusDataViewSelect` supports three useful layers of view state:
+
+1. `systemViews`
+   - Developer-defined static views.
+   - Automatically marked `isSystem: true`.
+   - Render before saved backend views.
+   - Cannot be edited or deleted through `DataGridViewSelect`, but can still be hidden.
+
+2. active-view persistence
+   - Controlled by `persistActiveView` and `persistKey`.
+   - Default storage namespace: `docyrus:data-grid-view:appSlug:dataSourceSlug[:appId]`.
+   - Initial resolution order: current in-memory value, stored value, backend `is_default`, then first available view.
+
+3. hidden-view persistence
+   - Managed through `hiddenViewIds`, `onViewHide`, and `onViewUnhide` in `gridViewSelectProps`.
+   - Stored separately from the active-view key.
+   - Useful when system views should exist but not always stay visible in the tab strip.
+
+## Manual server-query translation from a saved view
+
+If you keep custom row fetching, derive request params from the active view yourself. Don't forget the toolbar filter merge — `DataGridFilterMenu` writes to TanStack `columnFilters`, and a manual page must AND-merge those into the saved-view filter payload.
+
+```ts
+const activeView = views.find(view => view.id === activeViewId);
+
+const columns = buildColumnsFromView(fields, activeView);
+const orderBy = (activeView?.sorting ?? []).map(sort => ({
+  field: sort.id,
+  direction: sort.desc ? 'desc' : 'asc'
+}));
+
+// Auto-expand reference-type fields so the API returns `{ id, name, ... }` payloads.
+const EXPANDABLE_FIELD_TYPES = new Set([
+  'field-userSelect', 'field-userMultiSelect',
+  'field-relation', 'field-relatedField',
+  'field-select', 'field-radioGroup',
+  'field-enum', 'field-systemEnum',
+  'field-multiSelect', 'field-tagSelect',
+  'field-status', 'field-approvalStatus'
+]);
+const expand = fields
+  .filter(field => columns.includes(field.slug) && EXPANDABLE_FIELD_TYPES.has(field.type))
+  .map(field => field.slug);
+
+// Merge saved-view filters with toolbar filter state.
+const viewFilter = activeView?.filterQuery?.rules?.length ? activeView.filterQuery : undefined;
+const toolbarRules = (table.getState().columnFilters ?? [])
+  .map(filter => toServerRule(filter)) // import from @docyrus/ui/components/data-grid/lib/data-grid-server
+  .filter(Boolean);
+
+let filters;
+
+if (viewFilter && toolbarRules.length > 0) {
+  filters = { combinator: 'and', rules: [viewFilter, ...toolbarRules] };
+} else if (viewFilter) {
+  filters = viewFilter;
+} else if (toolbarRules.length > 0) {
+  filters = { combinator: 'and', rules: toolbarRules };
+}
+
+const params = {
+  columns,
+  orderBy: orderBy.length > 0 ? orderBy : undefined,
+  filters,
+  filterKeyword: keyword || undefined,
+  expand: expand.length > 0 ? expand : undefined,
+  limit: 50,
+  offset: 0
+};
+```
+
+Rules to preserve from the built-in hook behavior:
+
+- Always include `id` in `columns`.
+- When `columnOrder` is present, treat it as the ordered whitelist of visible field slugs.
+- Otherwise use `columnVisibility` entries with `true` values.
+- With no explicit saved-view visibility config, fetch all field slugs.
+- If the active view groups by a field, make sure that field stays in `columns` even if the saved view hides it.
+- Add reference-type field slugs to `expand` so user / relation / status / select / multi-select cells render with full data.
+- AND-merge `view.filterQuery` with the toolbar filter rules; reset `pageIndex` to 0 when the merged filter changes.
+- If you merge app-specific overrides, apply them last so they win.
+
+## Reserved columns versus backend field slugs
+
+There are two different conventions:
+
+- Local/manual views can include reserved table columns like `select` and `actions` inside `columnOrder`.
+- Backend Docyrus-saved views only know real data-source field slugs.
+
+That difference matters when you build a hybrid page. If you manually persist local views, reserved columns are safe. If you round-trip views through Docyrus backend APIs, assume only real field slugs are persisted and prepend reserved UI columns in the page code.
+
+## Paging ownership
+
+Saved views can carry:
+
+- `pagingEnabled`
+- `pagingMode`
+- `pageSize`
+
+`useDocyrusDataGrid` reads those values and forwards them into `useDataGrid`, and `gridProps` then carries the resolved paging mode.
+
+If you build the page manually and want the active view to own paging:
+
+- read the values from `activeView`
+- pass `pagingMode` and `pageSize` into `useDataGrid`
+- ensure your own row query or pagination model stays compatible with that page size
+
+If you ignore these properties in manual mode, the view editor can save paging settings that never affect the rendered grid.
+
+## Good advanced combinations
+
+### System starter views + backend user views
+
+Use `systemViews` for non-editable defaults like:
+
+- All records
+- My records
+- Needs attention
+- Recently updated
+
+Then let users create their own backend-saved views beside them.
+
+### Hook-owned metadata + app-owned data fetching
+
+Use `useDocyrusDataViewSelect` when you want:
+
+- backend view CRUD
+- field metadata for the filter editor
+- active-view persistence
+- hidden-view persistence
+
+but you still want the page's existing query hook, export pipeline, or analytics request builder to own row fetching.
+
+## Debug checklist
+
+- **Wrong initial view?** Check `persistActiveView`, `persistKey`, and whether a stale value is still in local storage.
+- **Grouping not working?** Make sure the grouping field is included in fetched `columns` and remains visible enough for the row model.
+- **Filter builder missing?** Pass `fields` into `DataGridViewSelect`.
+- **View tabs empty during loading?** Pass `isLoading` so the selector can render its loading state.
+- **Editor closes too early on save?** Pass `isSaving` when the host owns async create or update.
+- **Backend returns incomplete rows?** You probably forgot `columns`.