@docyrus/docyrus 0.0.67 → 0.0.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/docyrus",
-  "version": "0.0.67",
+  "version": "0.0.68",
   "private": false,
   "description": "Docyrus API CLI",
   "main": "./main.js",
@@ -14,8 +14,8 @@
     "@clack/prompts": "^0.11.0",
     "@ff-labs/fff-node": "0.6.4",
     "@hono/node-server": "^1.19.13",
-    "@mariozechner/pi-ai": "0.70.2",
-    "@mariozechner/pi-coding-agent": "0.70.2",
+    "@mariozechner/pi-ai": "0.70.6",
+    "@mariozechner/pi-coding-agent": "0.70.6",
     "@modelcontextprotocol/ext-apps": "^1.2.2",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@mozilla/readability": "^0.6.0",

package/resources/pi-agent/extensions/pi-bash-live-view/widget.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from '@mariozechner/pi-coding-agent';
+import { truncateToWidth } from '@mariozechner/pi-tui';
 import { snapshotToAnsiContentLines } from './terminal-emulator.ts';
 import type { PtyTerminalSession } from './pty-session.ts';
 
@@ -37,23 +38,7 @@ export function buildTopBorder(title: string, innerWidth: number, elapsedMs: num
 }
 
 function fitAnsiLine(line: string, width: number): string {
-  let out = '';
-  let visible = 0;
-  let i = 0;
-  while (i < line.length && visible < width) {
-    if (line[i] === '\x1b' && line[i + 1] === '[') {
-      const match = line.slice(i).match(/^\x1b\[[0-9;]*m/);
-      if (match) {
-        out += match[0];
-        i += match[0].length;
-        continue;
-      }
-    }
-    out += line[i];
-    visible += 1;
-    i += 1;
-  }
-  return `${out}\x1b[0m${' '.repeat(Math.max(0, width - visible))}`;
+  return `${truncateToWidth(line, width, '', true)}\x1b[0m`;
 }
 
 export function buildWidgetAnsiLines({

package/resources/pi-agent/skills/docyrus-app-dev-react/references/component-selection-guide.md

@@ -30,6 +30,7 @@ Mobile-first form                  → container="drawer" side="bottom"
 ```
 
 **AwesomeDialog** props reference:
+
 - `container`: `'modal'` | `'sheet'` | `'drawer'` — determines the dialog presentation
 - `side`: `'left'` | `'right'` | `'top'` | `'bottom'` — positioning for sheet/drawer
 - `size`: `'sm'` | `'default'` | `'lg'` | `'xl'` | `'full'` — size preset
@@ -43,6 +44,7 @@ Mobile-first form                  → container="drawer" side="bottom"
 **Sub-components**: `AwesomeDialogHeader`, `AwesomeDialogBody`, `AwesomeDialogFooter`, `AwesomeDialogToolbar`
 
 **Example — Small create form (task):**
+
 ```tsx
 <AwesomeDialog open={open} onOpenChange={setOpen} container="sheet" side="right">
   <AwesomeDialogHeader title="Create Task" icon="far-plus" />
@@ -55,6 +57,7 @@ Mobile-first form                  → container="drawer" side="bottom"
 ```
 
 **Example — Large create form (project):**
+
 ```tsx
 <AwesomeDialog open={open} onOpenChange={setOpen} container="modal" size="lg" fullscreenable>
   <AwesomeDialogHeader title="Create Project" icon="far-folder-plus" />
@@ -78,6 +81,7 @@ Small items (tasks, contacts, comments)      → AwesomeDialog with container="s
 ```
 
 **Decision tree:**
+
 ```
 Does the item have:
   - Multiple tabs/sections?
@@ -92,6 +96,7 @@ Does the item have:
 ```
 
 **Example — Task detail in AwesomeDialog:**
+
 ```tsx
 <AwesomeDialog open={open} onOpenChange={setOpen} container="sheet" side="right" size="lg" fullscreenable>
   <AwesomeDialogHeader
@@ -117,11 +122,13 @@ Does the item have:
 **All forms must use** TanStack Form with the Docyrus form field system. Never use plain HTML forms or React Hook Form directly.
 
 **Key components:**
+
 - `DynamicFormField` — Auto-dispatches to the correct field type based on `IField.type`
 - 47+ field types: text, number, email, url, phone, date, dateTime, time, select, multiSelect, status, relation, file, image, code, docEditor, and more
 - Each field type has a dedicated `*FormField` component (e.g., `TextFormField`, `SelectFormField`, `DateFormField`)
 
 **Form field pattern:**
+
 ```tsx
 import { useForm } from '@tanstack/react-form'
 import { TextFormField, SelectFormField, DateFormField } from '@docyrus/ui/components/form-fields'
@@ -141,12 +148,14 @@ const form = useForm({ defaultValues: { title: '', status: '', dueDate: '' } })
 Use `EditableRecordDetail` for detail views where users can edit individual fields inline without opening a full form page. **Always enable `trackChanges`** to highlight changed fields and show a floating ActionBar. Always include an **"Edit All"** button in the header to switch to a full form editing experience.
 
 **Key components:**
+
 - `EditableRecordDetail` — Provider/wrapper that manages field state, change tracking, and save/cancel
 - `EditableRecordDetailField` — Individual field that reads config from context, renders label + inline-editable value
 - `EditableValue` — Lower-level single-field inline editor (used internally by EditableRecordDetailField)
 - `useEditableRecordDetail()` — Hook to access form, values, changes, and save/cancel from within the provider
 
 **How it works (with `trackChanges` enabled):**
+
 1. Fields render as read-only `DynamicValue` display
 2. Click a field → switches to `DynamicFormField` editor inline
 3. Changed fields get highlighted with amber background
@@ -156,6 +165,7 @@ Use `EditableRecordDetail` for detail views where users can edit individual fiel
 **Important:** Always pass `trackChanges` prop when using `EditableRecordDetail` or `DataGrid` with cell editing. Without it, users have no visual feedback about which fields they've modified and no centralized Save/Cancel flow.
 
 **Field change tracking types:**
+
 ```tsx
 interface RecordDetailField {
   field: IField           // Field configuration (name, slug, type)
@@ -174,6 +184,7 @@ interface FieldChange {
 ```
 
 **Example — Detail view with inline editing and "Edit All" button:**
+
 ```tsx
 <AwesomeDialogHeader
   title="Task Detail"
@@ -368,9 +379,11 @@ When using **Data Grid View Select**, back its `views`, `onViewCreate`, `onViewS
 ## Library-Specific Strengths
 
 ### shadcn (43 components)
+
 **Best for**: Core UI primitives, forms, basic layout
 
 **Strengths**:
+
 - Well-tested, accessible components
 - Great documentation
 - Broad browser support
@@ -379,9 +392,11 @@ When using **Data Grid View Select**, back its `views`, `onViewCreate`, `onViewS
 **Use when**: You need a standard, reliable component without special features
 
 ### diceui (42 components)
+
 **Best for**: Advanced interactions, specialized data components
 
 **Strengths**:
+
 - Rich feature sets (filtering, sorting, virtualization)
 - Advanced input types (phone, color, mask)
 - Drag-drop capabilities
@@ -390,9 +405,11 @@ When using **Data Grid View Select**, back its `views`, `onViewCreate`, `onViewS
 **Use when**: You need advanced functionality beyond basic components
 
 ### animate-ui (21 components)
+
 **Best for**: Animated transitions, polished UX
 
 **Strengths**:
+
 - Smooth, professional animations
 - Enhanced visual feedback
 - Composable animated patterns
@@ -400,9 +417,11 @@ When using **Data Grid View Select**, back its `views`, `onViewCreate`, `onViewS
 **Use when**: Animation/transitions are important to the UX
 
 ### docyrus (51 components)
+
 **Best for**: Docyrus-specific data handling, forms, dialogs, inline editing, scheduling, chat, AI agents, and business logic
 
 **Strengths**:
+
 - Deep Docyrus platform integration
 - AwesomeDialog system for item creation and detail views
 - EditableRecordDetail for inline field editing with change tracking
@@ -419,9 +438,11 @@ When using **Data Grid View Select**, back its `views`, `onViewCreate`, `onViewS
 **Use when**: Working with Docyrus data sources, building item create/detail flows, forms, scheduling, chat, AI features, or queries
 
 ### reui (2 components)
+
 **Best for**: Specific utility needs
 
 **Strengths**:
+
 - Focused implementations
 - Lightweight alternatives
 
@@ -466,25 +487,29 @@ These are the **recommended defaults** unless the user specifies otherwise:
 
 ## When to Use Each Library
 
-### Use shadcn when:
+### Use shadcn when
+
 - Building basic forms with standard inputs
 - Creating simple layouts with cards, buttons, badges
 - Need reliable, accessible primitives
 - No special animation or advanced features required
 
-### Use diceui when:
+### Use diceui when
+
 - Building complex data tables with sorting/filtering
 - Need advanced input types (phone, color, tags)
 - Implementing drag-drop (kanban, sortable lists)
 - Creating rich data visualizations (gauges, timelines)
 
-### Use animate-ui when:
+### Use animate-ui when
+
 - Animation/transitions are important to the design
 - Building navigation with smooth interactions
 - Creating polished dialog/overlay experiences
 - Need animated feedback for user actions
 
-### Use docyrus when:
+### Use docyrus when
+
 - Building item create forms (AwesomeDialog, Create Record Dialog)
 - Building item detail views (AwesomeDialog + EditableRecordDetail)
 - Working directly with Docyrus data sources
@@ -499,7 +524,8 @@ These are the **recommended defaults** unless the user specifies otherwise:
 - Need rich item selectors (Mega Select, Kanban)
 - Need Docyrus-specific components (query builder, activity panel, notifications)
 
-### Use reui when:
+### Use reui when
+
 - The specific component (file upload or sortable) matches your exact need
 - Want a lightweight alternative to diceui versions
 
@@ -524,6 +550,7 @@ These are the **recommended defaults** unless the user specifies otherwise:
    - Use for: Fallback when neither hugeicons nor fontawesome have the icon
 
 **Example**:
+
 ```tsx
 import { HugeIconDollarCircle } from '@/components/icons/hugeicons'
 import { FaLightChartLine } from '@/components/icons/fontawesome'
@@ -544,6 +571,7 @@ import { LucideActivity } from 'lucide-react'
 ## Quick Reference: Component Categories
 
 ### Dialogs & Item Flows
+
 - Item create forms: **docyrus AwesomeDialog** (sheet for small, modal for large)
 - Quick record create: **docyrus Create Record Dialog** (popover with subject/mentions)
 - Item detail (small): **docyrus AwesomeDialog** (sheet right)
@@ -553,6 +581,7 @@ import { LucideActivity } from 'lucide-react'
 - Responsive: diceui Responsive Dialog
 
 ### Data & Display
+
 - Tables: docyrus Data Grid, diceui Data Table, shadcn Table
 - Pivot table: docyrus PivotGrid (hierarchies, subtotals, drilldown, export)
 - Grid saved views: docyrus Data Grid View Select + `DataViews` from `@docyrus/app-utils`
@@ -564,6 +593,7 @@ import { LucideActivity } from 'lucide-react'
 - Tree: docyrus TreeView
 
 ### Forms & Input
+
 - Dynamic forms: **docyrus Form Fields + TanStack Form** (always use)
 - Inline editing: docyrus EditableRecordDetail, EditableValue
 - Text: shadcn Input, Textarea
@@ -576,17 +606,20 @@ import { LucideActivity } from 'lucide-react'
 - Special: diceui Phone Input, Color Picker, Tags Input
 
 ### Navigation
+
 - Sidebar: animate-ui Sidebar
 - Menus: animate-ui Dropdown Menu, shadcn Menubar
 - Breadcrumbs: shadcn Breadcrumb
 - Tabs: animate-ui Tabs
 
 ### Overlays
+
 - Item forms/details: **docyrus AwesomeDialog** (preferred)
 - Popovers: animate-ui Popover, Tooltip, Hover Card
 - Drawers: shadcn Drawer, animate-ui Sheet
 
 ### Communication
+
 - Team chat: docyrus Team Chat Channel (threads, reactions, mentions)
 - Email composing: docyrus Email Composer (To/Cc/Bcc, toolbar, attachments)
 - Comments: docyrus Comments Panel (threaded conversations)
@@ -594,21 +627,25 @@ import { LucideActivity } from 'lucide-react'
 - Activity logging: docyrus Log Activity Form (calls, emails, meetings, tasks, statuses)
 
 ### Scheduling
+
 - Project timelines: docyrus Gantt
 - Resource scheduling: docyrus Resource Scheduler Panel (horizontal timeline)
 - Appointment booking: docyrus Time Slot Scheduler (columns/month views)
 - Calendar events: docyrus Calendar (month/week/day views)
 
 ### AI & Agents
+
 - AI chat: docyrus Docyrus Agent (chat mode)
 - AI actions: docyrus Docyrus Agent (action-panel mode)
 - AI trigger: docyrus Docyrus Agent (floating trigger button)
 
 ### Business Logic
+
 - Pricing/quoting: docyrus Pricing Engine Panel (line items, VAT, discounts)
 - Record sharing: docyrus Record Sharing (permissions, users/teams/roles)
 
 ### Specialized
+
 - Kanban: docyrus Kanban (drag-drop columns)
 - Timeline: diceui Timeline
 - Stepper / wizard: docyrus Stepper (6 variants, horizontal/vertical, animated)

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

@@ -0,0 +1,58 @@
+---
+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.
+   - 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`.