@docyrus/docyrus 0.0.31 → 0.0.32

package/resources/pi-agent/skills/docyrus-app-dev-react/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docyrus-app-dev-react
-description: Build Docyrus React TypeScript web applications end-to-end, combining authentication, API access, generated collections, TanStack Query/Form patterns, and production-grade UI implementation with preferred component libraries. Use when creating or modifying Docyrus-backed apps that use @docyrus/api-client, @docyrus/signin, Docyrus collections, queries, dashboards, forms, tables, layouts, or Docyrus UI components.
+description: Build Docyrus React TypeScript web applications end-to-end, combining authentication, API access, @docyrus/app-utils runtime helpers, generated collections, TanStack Query/Form patterns, and production-grade UI implementation with preferred component libraries. Use when creating or modifying Docyrus-backed apps that use @docyrus/api-client, @docyrus/signin, @docyrus/app-utils, Docyrus collections, queries, dashboards, forms, tables, layouts, or Docyrus UI components.
 ---
 
 # Docyrus App Dev React
@@ -12,7 +12,7 @@ Build Docyrus React TypeScript applications end-to-end. This skill combines app
 - React 19 + TypeScript + Vite
 - TanStack Router (code-based), TanStack Query (server state), TanStack Form
 - Tailwind CSS v4, shadcn/ui components
-- `@docyrus/api-client` + `@docyrus/signin`
+- `@docyrus/api-client` + `@docyrus/signin` + `@docyrus/app-utils`
 - Auto-generated collections from OpenAPI spec
 - Preferred UI libraries: shadcn, diceui, animate-ui, docyrus-ui, reui
 
@@ -22,7 +22,10 @@ Use this skill when you are:
 
 - Building or modifying a Docyrus-backed React app
 - Setting up authentication with `@docyrus/signin`
+- Bootstrapping tenant-aware runtime utilities with `@docyrus/app-utils`
 - Fetching or mutating data with generated collections or `@docyrus/api-client`
+- Persisting app-level config or saved grid views with `AppConfig` and `DataViews`
+- Building record sharing, role management, or ACL-driven UI flows
 - Designing feature UIs such as dashboards, forms, tables, layouts, dialogs, analytics, or detail pages
 - Selecting between shadcn, diceui, animate-ui, docyrus-ui, and reui components
 - Implementing complete feature flows that combine data access and polished UI
@@ -30,11 +33,13 @@ Use this skill when you are:
 ## End-to-End Feature Workflow
 
 1. Set up app auth, routing, and query providers.
-2. Use generated Docyrus collection hooks or the REST client for data access.
-3. Define `columns`, filters, formulas, child queries, and mutations correctly.
-4. Check preferred UI components before building anything custom.
-5. Use Docyrus form and detail patterns for create, edit, and item detail flows.
-6. Connect UI actions to TanStack Query mutations and invalidate relevant queries.
+2. Bootstrap `TenantPreferences`, date/number utilities, and shared app runtime helpers from `@docyrus/app-utils`.
+3. Use generated Docyrus collection hooks or the REST client for data access.
+4. Define `columns`, filters, formulas, child queries, and mutations correctly.
+5. Use `AppConfig` for per-app persisted settings and `DataViews` for saved grid views.
+6. Check preferred UI components before building anything custom.
+7. Use Docyrus form and detail patterns for create, edit, item detail, and editable grid flows.
+8. Connect UI actions to TanStack Query mutations and invalidate relevant queries.
 
 ## Quick Start: App Bootstrap
 
@@ -69,10 +74,60 @@ if (status === 'unauthenticated') return <SignInButton />
 // hasPermission('edit', dataSourceId) — check ACL permission on a data source
 ```
 
+### Tenant-aware app utilities
+
+Use `@docyrus/app-utils` as the default runtime layer for tenant-level formatting and persisted app/grid preferences.
+
+```tsx
+import {
+  createAppConfigClient,
+  createDataViewClient,
+  createDateUtils,
+  createNumberUtils,
+  getTenantPreferences,
+} from '@docyrus/app-utils'
+
+function useAppRuntime(appId: string) {
+  const client = useDocyrusClient()
+  const { getMyInfo } = useUsersCollection()
+
+  return useQuery({
+    queryKey: ['app-runtime', appId],
+    enabled: !!client && !!appId,
+    queryFn: async () => {
+      const [preferences, me] = await Promise.all([
+        getTenantPreferences(client!),
+        getMyInfo(),
+      ])
+
+      return {
+        preferences,
+        me,
+        dateUtils: createDateUtils({
+          preferences,
+          userTimezone: me.timeZone?.id,
+        }),
+        numberUtils: createNumberUtils({ preferences }),
+        appConfig: createAppConfigClient(client!, appId),
+        dataViews: createDataViewClient(client!, appId),
+      }
+    },
+  })
+}
+```
+
+Use this runtime to:
+
+- Format dates and datetimes with tenant format strings and the user's timezone.
+- Format numbers, currency-like values, and decimals using tenant separators and precision.
+- Read and upsert the app's single persisted `AppConfig` document.
+- Read and persist saved grid views through `DataViews`.
+
 ### Data fetching with generated collections
 
 ```tsx
 const { list } = useBaseProjectCollection()
+
 const { data: projects } = useQuery({
   queryKey: ['projects'],
   queryFn: () =>
@@ -85,12 +140,40 @@ const { data: projects } = useQuery({
 })
 ```
 
-## Common Docyrus Asset URL Templates
+### ACL, roles, and record sharing
 
-- `User avatar path template`: `https://api.docyrus.app/storage/v1/object/tenant-public/:tenantId/users/:userId/:user.photo`
-- `Tenant logo path template`: `https://api.docyrus.app/storage/v1/object/tenant-public/:tenantId/:tenant.logo`
+Use direct `useDocyrusClient()` calls for ACL features. These routes may be hidden from generated OpenAPI output, so they are typically not available through generated collection hooks.
 
-Use these templates when wiring user chips, assignee avatars, comments, activity feeds, app shell branding, workspace switchers, and any `DataGrid` user option payload that needs `avatarUrl`.
+```tsx
+const client = useDocyrusClient()
+
+const { data: roles } = useQuery({
+  queryKey: ['acl', 'roles'],
+  queryFn: () => client!.get('/v1/users/acl/roles'),
+})
+
+const replaceUserRoles = useMutation({
+  mutationFn: ({ userId, roleIds }: { userId: string; roleIds: string[] }) =>
+    client!.put(`/v1/users/acl/users/${userId}/roles`, { roleIds }),
+})
+
+const createRoleQuery = useMutation({
+  mutationFn: (payload: Record<string, unknown>) =>
+    client!.post('/v1/users/acl/role-queries', payload),
+})
+```
+
+Prefer role `uid` values returned by the API when sending `roleIds` for user-role updates or role-query payloads.
+
+### Saved data grid views
+
+Use `DataGridViewSelect` as the default saved-view UI for Docyrus grids, and persist those views with `createDataViewClient(client, appId)`.
+
+- `DataGridViewSelect` is the default component for showing and editing saved grid views.
+- Pass the TanStack table instance via `table` so the selector/editor can read column definitions.
+- Pass `fields` when you want the built-in filter builder enabled in the editor.
+- Back `views`, `onViewCreate`, `onViewSave`, `onViewDelete`, `onViewHide`, and `onViewUnhide` with `DataViews` CRUD.
+- Use `DataGridViewEditor` separately only when you need a standalone editor outside the selector.
 
 ## Critical App/Data Rules
 
@@ -101,7 +184,20 @@ Use these templates when wiring user chips, assignee avatars, comments, activity
 5. **Child query keys must appear in `columns`**.
 6. **Formula keys must appear in `columns`**.
 7. **Use `useUsersCollection().getMyInfo()`** for current user profile instead of making a direct profile call.
-8. **Regenerate collections after schema changes** by rebuilding the tenant OpenAPI spec, downloading the latest `openapi.json`, and re-running the collection generator.
+8. **Initialize `TenantPreferences` once per app runtime** and create shared `dateUtils` / `numberUtils` instances from `@docyrus/app-utils`.
+9. **Formatting functions from `@docyrus/app-utils` are regionalized** — do not hardcode locale, date format, decimal separator, thousand separator, or decimal precision when tenant preferences should drive them.
+10. **Use `createAppConfigClient(client, appId)`** for the app's single persisted config document; `upsert` is the default write path.
+11. **Use `createDataViewClient(client, appId)`** for saved grid-view CRUD.
+12. **Use `DataViews` with `DataGridViewSelect`** to show, create, edit, reorder, hide, unhide, soft-delete, and hard-delete saved data grid views.
+13. **`DataGridViewSelect` needs a TanStack table instance** and should receive `fields` when you want the built-in filter builder/editor experience.
+14. **Data view creation requires `name` and `tenant_data_source_id`**.
+15. **Use `dataViews.update(viewId, { archived: true })` for soft-delete** and `dataViews.remove(viewId)` only for irreversible hard-delete.
+16. **Regenerate collections after schema changes** by rebuilding the tenant OpenAPI spec, downloading the latest `openapi.json`, and re-running the collection generator.
+17. **ACL endpoints are usually raw-client integrations** — use `useDocyrusClient()` or `RestApiClient` for roles, user-role assignments, role queries, record sharing, and ownership transfer.
+18. **Prefer role `uid` values** for ACL role writes, user-role `roleIds`, and role-query `roleIds`.
+19. **Treat `PUT /v1/users/acl/users/:userId/roles` as full replacement** and `POST /v1/users/acl/users/:userId/roles` as additive.
+20. **Send role-query `query` as raw JSON** and omit `tenantAppId` when `dataSourceId` is present; backend derives it.
+21. **After deleting a role, invalidate dependent app queries** for role lists, user-role lists, role-query lists, and any UI that renders primary-role labels.
 
 ## Critical UI/UX Rules
 
@@ -119,10 +215,8 @@ Use these templates when wiring user chips, assignee avatars, comments, activity
 8. **All forms must use TanStack Form + the Docyrus form system**. Do not build feature forms with plain HTML forms or React Hook Form directly.
 9. **Use `EditableRecordDetail` for inline editing** in item detail views.
 10. **Always enable `trackChanges`** for editable detail and grid experiences.
-11. **When using Docyrus `DataGrid`, always set the correct `meta.cell` variant for the field type**. Do not reuse a generic text cell for typed Docyrus data.
-12. **When rendering data source records in tables, cards, or lists, prefer the matching Docyrus value renderer** instead of handwritten display JSX.
-13. **When editing inline, pass the real `IField` metadata into `EditableRecordDetailField` or `EditableValue`** so Docyrus can dispatch the correct editor and display pair from `field.type`.
-14. **If a field type has no dedicated `DataGrid` cell variant, keep the grid cell read-only and move editing to a sheet, dialog, or detail page**.
+11. **Use `DataGridViewSelect` for saved grid views** and back it with `DataViews` from `@docyrus/app-utils`.
+12. **Prefer `DataGridViewEditor` only when you need a standalone grid-view editor** outside the selector component.
 
 ## Default UI Choices
 
@@ -138,7 +232,7 @@ Use these templates when wiring user chips, assignee avatars, comments, activity
 | App navigation | `Sidebar` | animate-ui |
 | Data table | `DataTable` | diceui |
 | Editable grid | `Data Grid` | docyrus |
-| Grid saved views | `DataGridViewSelect` | docyrus |
+| Grid saved views | `DataGridViewSelect` + `DataViews` | docyrus + `@docyrus/app-utils` |
 | Forms | Docyrus form fields + TanStack Form | docyrus |
 | Charts | shadcn chart + Recharts | shadcn |
 | File upload | File Upload | diceui |
@@ -149,74 +243,6 @@ Use these templates when wiring user chips, assignee avatars, comments, activity
 | Pricing / quoting | `PricingEnginePanel` | docyrus |
 | Analytics / pivot | `PivotGrid` | docyrus |
 
-## Data Source Field Type UI Mapping
-
-If you already have Docyrus field metadata, prefer explicit Docyrus field-specific primitives over custom UI glue:
-
-- Forms: use the specific `*FormField` for the field type
-- Read-only display: matching value renderer / `DynamicValue`
-- Inline editing: `EditableRecordDetailField` or `EditableValue`
-- Editable grids: `DataGrid` with the matching `meta.cell` variant
-
-Use the table below as the default mapping guide.
-
-| Field type(s) | `DataGrid` cell variant | Form field | Inline edit | Value renderer | Notes |
-|---------------|-------------------------|------------|-------------|----------------|-------|
-| `field-text` | `short-text` | `TextFormField` | `EditableValue` with `field-text` | `TextValue` | Default single-line text |
-| `field-textarea` | `long-text` | `TextareaFormField` | `EditableValue` with `field-textarea` | `TextValue` | Multi-line content |
-| `field-email` | `email` | `EmailFormField` | `EditableValue` with `field-email` | `EmailValue` | Use for clickable email cells |
-| `field-url` | `url` | `UrlFormField` | `EditableValue` with `field-url` | `UrlValue` | Prefer typed URL rendering over plain text |
-| `field-phone` | `phone` | `PhoneFormField` | `EditableValue` with `field-phone` | `PhoneValue` | Supports phone-specific display and editing |
-| `field-number` | `number` | `NumberFormField` | `EditableValue` with `field-number` | `NumberValue` | Standard numeric input |
-| `field-money` | `currency` | `MoneyFormField` | `EditableValue` with `field-money` | `MoneyValue` | Use money-specific formatting |
-| `field-currency` | `currency-code` | `CurrencyCodeFormField` | `EditableValue` with `field-currency` | `CurrencyCodeValue` | ISO currency codes |
-| `field-duration` | `duration` | `DurationFormField` | `EditableValue` with `field-duration` | `DurationValue` | Duration editing/display |
-| `field-rating` | `rating` | `RatingFormField` | `EditableValue` with `field-rating` | `RatingValue` | Star rating |
-| `field-select` | `select` | `SelectFormField` | `EditableValue` with `field-select` | `SelectValue` | Single select with Docyrus enum options |
-| `field-radioGroup` | `select` | `RadioGroupFormField` | `EditableValue` with `field-radioGroup` | `SelectValue` | In grids, use a select-style cell |
-| `field-enum` | `enum` | `EnumFormField` | `EditableValue` with `field-enum` | `SelectValue` | Backend-driven enum values |
-| `field-status` | `status` | `StatusFormField` | `EditableValue` with `field-status` | `StatusValue` | Preserves status metadata such as description/follow-up |
-| `field-multiSelect` | `multi-select` | `MultiSelectFormField` | `EditableValue` with `field-multiSelect` | `MultiSelectValue` | Multi-badge selection |
-| `field-tagSelect` | `tag-select` | `TagSelectFormField` | `EditableValue` with `field-tagSelect` | `MultiSelectValue` | Colored tag chips |
-| `field-userSelect` | `user` | `UserSelectFormField` | `EditableValue` with `field-userSelect` | `UserValue` | Populate `CellUserOption.avatarUrl` using the user avatar template |
-| `field-userMultiSelect` | `user-multi-select` | `UserMultiSelectFormField` | `EditableValue` with `field-userMultiSelect` | `UserMultiValue` | Use the avatar template for each selected user |
-| `field-relation` | `relation` | `RelationFormField` | `EditableValue` with `field-relation` | `RelationValue` | Prefer Docyrus relation lookup behavior |
-| `field-date` | `date` | `DateFormField` | `EditableValue` with `field-date` | `DateValue` | Date-only |
-| `field-dateTime` | `datetime` | `DateTimeFormField` | `EditableValue` with `field-dateTime` | `DateTimeValue` | Date + time |
-| `field-time` | `time` | `TimeFormField` | `EditableValue` with `field-time` | `TimeValue` | Time-only |
-| `field-dateRange` | `date-range` | `DateRangeFormField` | `EditableValue` with `field-dateRange` | `DateRangeValue` | Start/end pairs |
-| `field-checkbox` | `checkbox` | `CheckboxFormField` | `EditableValue` with `field-checkbox` | `CheckboxValue` | Boolean checkbox |
-| `field-switch` | `switch` | `SwitchFormField` | `EditableValue` with `field-switch` | `SwitchValue` | Boolean toggle |
-| `field-color` | `color` | `ColorFormField` | `EditableValue` with `field-color` | `ColorValue` | Use the swatch-aware UI |
-| `field-icon` | `icon` | `IconFormField` | `EditableValue` with `field-icon` | `IconValue` | Keep icon selection/rendering typed |
-| `field-file` | `file` | `FileFormField` | `EditableValue` with `field-file` when inline file editing is acceptable | `FileValue` | Grid editing is fine only when upload UX fits the workflow |
-| `field-image` | `image` | `ImageFormField` | `EditableValue` with `field-image` when inline image editing is acceptable | `ImageValue` | Prefer preview-aware image handling |
-| `field-locationSelect` | `—` | `LocationSelectFormField` | `EditableValue` with `field-locationSelect` | `LocationValue` | No dedicated `DataGrid` cell variant in current docs; prefer detail editing |
-| `field-docEditor` | `—` | `DocEditorFormField` | `EditableValue` with `field-docEditor` | `DocEditorValue` | Avoid dense grid editing; use a detail view or sheet |
-| `field-htmlEditor` | `—` | `HtmlEditorFormField` | `EditableValue` with `field-htmlEditor` | `RichTextValue` | Prefer detail editing over grid editing |
-| `field-emailEditor` | `—` | `EmailEditorFormField` | `EditableValue` with `field-emailEditor` | `RichTextValue` | Better in a drawer/modal editor |
-| `field-codeEditor` | `long-text` or `—` | `CodeEditorFormField` | `EditableValue` with `field-codeEditor` | `CodeValue` | Prefer a detail editor if syntax-aware editing matters |
-| `field-taskList` | `—` | `TaskListFormField` | `EditableValue` with `field-taskList` | `TaskListValue` | Better in detail surfaces than grids |
-| `field-queryBuilder` | `—` | `QueryBuilderFormField` | `EditableValue` with `field-queryBuilder` | `—` | Use dedicated query-builder UI |
-| `field-dynamic` | `—` | `DynamicConfigFormField` | `EditableValue` with `field-dynamic` | `—` | Specialized config UX |
-| `field-schemaRepeater` | `—` | `SchemaRepeaterFormField` | `EditableValue` with `field-schemaRepeater` | `—` | Repeater editing belongs in a form/detail surface |
-| `field-approvalStatus` | `—` | `ApprovalStatusFormField` | `EditableValue` with `field-approvalStatus` | `ApprovalStatusValue` | No dedicated `DataGrid` cell variant in current docs |
-| `field-inlineData`, `field-inlineForm`, `field-todo` | `—` | `—` | Use `EditableValue` only if the field has a supported dedicated inline experience | `InlineDataValue`, `TodoValue` | Prefer specialized detail UI over grid editing |
-| `field-display`, `field-formula`, `field-relatedField`, `field-button`, `field-identity`, `field-autonumber`, `field-list` | `—` | `—` | Keep read-only by default | `TextValue`, `FormulaValue`, `RelatedFieldValue`, `ButtonValue`, `IdentityValue`, `ListValue` | These are commonly display/virtual/system-driven rather than user-editable |
-| `field-code` | `—` | `—` | Keep read-only or build a custom feature-specific editor intentionally | `TextValue` | Do not force this into a generic grid editor unless the simplification is intentional |
-
-### Field-Type Mapping Notes
-
-- `EditableValue` is the low-level inline editor. The important choice is the `field.type` you pass in; Docyrus uses that metadata to choose the correct inline form/display behavior.
-- If a field type does not have a documented `DataGrid` cell variant, do not approximate it with a text cell unless the simplification is intentional and acceptable for the feature.
-- For large rich-content or structured fields, prefer `AwesomeDialog`, dedicated detail pages, or `EditableRecordDetail` instead of dense grid editing.
-- The current shared `FIELD_TYPES` list in the platform is the authoritative source. If UI docs mention a field type not present in the tenant schema/runtime, do not assume it is available.
-- Reference docs:
-  - `https://ui.docy.app/docs/web/docyrus/value-renderers/llms.txt`
-  - `https://ui.docy.app/docs/web/docyrus/form-fields/llms.txt`
-  - `https://ui.docy.app/docs/web/docyrus/editable-value/llms.txt`
-  - `https://ui.docy.app/docs/web/docyrus/data-grid/llms.txt`
-
 ## Quick UI Patterns
 
 ### Item create form
@@ -326,6 +352,7 @@ For deep dives, read:
 - `references/README.md` — merged reference map for app development and UI design
 - `references/api-client-and-auth.md`
 - `references/collections-and-patterns.md`
+- `../docyrus-api-dev/references/acl-endpoints-frontend.md`
 - `../docyrus-api-dev/references/data-source-query-guide.md`
 - `../docyrus-api-dev/references/formula-design-guide-llm.md`
 - `../docyrus-api-dev/references/query-guide.md`

package/resources/pi-agent/skills/docyrus-app-dev-react/references/README.md

@@ -8,6 +8,7 @@ Read these files for data access, auth, query design, and collection patterns:
 
 - `api-client-and-auth.md`
 - `collections-and-patterns.md`
+- `../../docyrus-api-dev/references/acl-endpoints-frontend.md`
 - `../../docyrus-api-dev/references/data-source-query-guide.md`
 - `../../docyrus-api-dev/references/formula-design-guide-llm.md`
 - `../../docyrus-api-dev/references/query-guide.md`

package/resources/pi-agent/skills/docyrus-app-dev-react/references/collections-and-patterns.md

@@ -239,6 +239,7 @@ export function useDeleteProject() {
     },
   })
 }
+```
 
 ---
 

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

@@ -243,26 +243,43 @@ Follow this process when selecting a component:
 
 | Need | Component | Library | Rationale |
 |------|-----------|---------|-----------|
-| App sidebar | **Sidebar** | animate-ui | Default choice - smooth animations, composable |
-| Alternative sidebar | Navigation Menu | shadcn | For mega menus and dropdowns |
-| Breadcrumbs | Breadcrumb | shadcn | Path navigation |
-| Menu bar | Menubar | shadcn | Desktop-style persistent menu |
-| Dropdown menu | Dropdown Menu | animate-ui | Animated transitions |
-| Context menu | Context Menu | shadcn | Right-click menus |
-| Tabs | Tabs | animate-ui | Animated tab transitions |
+| Dynamic forms (default) | **Form Fields + TanStack Form** | docyrus | 47 field types with auto-dispatch — **always use this** |
+| Inline record editing | **EditableRecordDetail** | docyrus | Click-to-edit fields with change tracking + ActionBar |
+| Single field inline edit | EditableValue | docyrus | Lower-level click-to-edit for individual values |
+| Text input | Input | shadcn | Basic text input (use via TextFormField in forms) |
+| Text area | Textarea | shadcn | Multi-line text (use via TextareaFormField in forms) |
+| Select dropdown | Select | shadcn | Basic select (use via SelectFormField in forms) |
+| Combobox/autocomplete | Combobox | diceui | Search + select |
+| Date picker | Date Time Picker | docyrus | Date + time combined |
+| Date range picker | **Date Time Range Picker** | docyrus | Start/end date+time pair with size variants |
+| Date only | Calendar | shadcn | Date selection only |
+| Time only | Time Picker | diceui | Time selection only |
+| Phone number | Phone Input | diceui | International formatting |
+| Color selection | Color Picker | diceui | Full spectrum + palette |
+| File upload | File Upload | diceui | Drag-drop, preview, progress |
+| Tags input | Tags Input | diceui | Multiple tag entry |
+| Rating | Rating | diceui | Star/heart rating |
+| Checkbox group | Checkbox Group | diceui | Multiple selections |
+| Radio group (animated) | Radio Group | animate-ui | Single selection with animation |
+| Radio group (card/grid) | **Radio Group** | docyrus | Card variant with icons, descriptions, grid columns |
+| Switch | Switch | animate-ui | Toggle with animation |
+| Slider | Slider | shadcn | Range selection |
+| OTP input | Input OTP | shadcn | One-time password codes |
 
 ### Data Display & Tables
 
 | Need | Component | Library | Rationale |
 |------|-----------|---------|-----------|
 | Editable grid | Data Grid | docyrus | Virtualized, keyboard nav, cell editing — enable `trackChanges` for edit tracking |
-| Grid saved views | **Data Grid View Select** | docyrus | Saved view management with sort/filter/columns |
+| Grid saved views | **Data Grid View Select** | docyrus | Saved view management with sort/filter/columns — persist with `DataViews` from `@docyrus/app-utils` |
 | Read-only table | Table | shadcn | Simple, responsive tables |
 | Advanced data table | Data Table | diceui | Filtering, sorting, pagination built-in |
 | Table filters | Data Table Filter | docyrus | Multi-column filter bar |
 | Value display | Value Renderers | docyrus | 44 renderer types for read-only display |
 | Empty state | Empty | shadcn | No data placeholder |
 
+When using **Data Grid View Select**, back its `views`, `onViewCreate`, `onViewSave`, `onViewDelete`, `onViewHide`, and `onViewUnhide` flows with `createDataViewClient(client, appId)` from `@docyrus/app-utils`. Always pass the TanStack `table` instance, and pass `fields` when you want the editor's built-in filter builder enabled.
+
 ### Forms & Inputs
 
 **Always use TanStack Form + Docyrus form fields.** The `DynamicFormField` component auto-dispatches to the correct field type.
@@ -426,7 +443,7 @@ These are the **recommended defaults** unless the user specifies otherwise:
 | App navigation | Sidebar | animate-ui |
 | Charts | Chart + Recharts | shadcn |
 | Data table | Data Table | diceui |
-| Data grid saved views | **Data Grid View Select** | docyrus |
+| Data grid saved views | **Data Grid View Select** + `DataViews` | docyrus + `@docyrus/app-utils` |
 | Forms | **Form Fields + TanStack Form** | docyrus |
 | File upload | File Upload | diceui |
 | Confirmation dialogs | Alert Dialog | animate-ui |
@@ -538,7 +555,7 @@ import { LucideActivity } from 'lucide-react'
 ### 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
+- Grid saved views: docyrus Data Grid View Select + `DataViews` from `@docyrus/app-utils`
 - Cards: docyrus AwesomeCard, shadcn Card
 - Stat dashboards: docyrus AwesomeStats (grid/flex/tabs, mini-charts, comparisons)
 - Charts: shadcn Chart + Recharts