@docyrus/docyrus 0.0.30 → 0.0.32

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

@@ -0,0 +1,361 @@
+---
+name: docyrus-app-dev-react
+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
+
+Build Docyrus React TypeScript applications end-to-end. This skill combines app architecture, authentication, data access, query patterns, and production-grade UI guidance in one place.
+
+## Tech Stack
+
+- 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/app-utils`
+- Auto-generated collections from OpenAPI spec
+- Preferred UI libraries: shadcn, diceui, animate-ui, docyrus-ui, reui
+
+## When to Use This Skill
+
+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
+
+## End-to-End Feature Workflow
+
+1. Set up app auth, routing, and query providers.
+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
+
+### Root provider setup
+
+```tsx
+import { DocyrusAuthProvider } from '@docyrus/signin'
+
+<DocyrusAuthProvider
+  apiUrl={import.meta.env.VITE_API_BASE_URL}
+  clientId={import.meta.env.VITE_OAUTH2_CLIENT_ID}
+  redirectUri={import.meta.env.VITE_OAUTH2_REDIRECT_URI}
+  scopes={['offline_access', 'Read.All', 'DS.ReadWrite.All', 'Users.Read']}
+  callbackPath="/auth/callback"
+>
+  <QueryClientProvider client={queryClient}>
+    <RouterProvider router={router} />
+  </QueryClientProvider>
+</DocyrusAuthProvider>
+```
+
+### Auth gate and current-user access
+
+```tsx
+const { status, user, hasRole, hasPermission } = useDocyrusAuth()
+
+if (status === 'loading') return <Spinner />
+if (status === 'unauthenticated') return <SignInButton />
+
+// user is auto-fetched from /v1/users/me after authentication
+// hasRole('super_admin') — check role by slug or uid
+// 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: () =>
+    list({
+      columns: ['name', 'status', 'record_owner(firstname,lastname)'],
+      filters: { rules: [{ field: 'status', operator: '!=', value: 'archived' }] },
+      orderBy: 'created_on DESC',
+      limit: 50,
+    }),
+})
+```
+
+### ACL, roles, and record sharing
+
+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.
+
+```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
+
+1. **Always send `columns`** in `.list()` and `.get()` calls. Without it, only `id` is returned.
+2. **Collections are React hooks** — call `useBaseProjectCollection()`, `useUsersCollection()`, and similar hooks inside React components.
+3. **Data source endpoints are dynamic** — they only exist if the data source is defined in the tenant OpenAPI spec.
+4. **Use `id` for `count` calculations**. Use actual field slugs for `sum`, `avg`, `min`, and `max`.
+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. **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
+
+1. **Always check preferred components first** before creating anything custom.
+2. **Use `AwesomeCard` for dashboards** unless the user explicitly wants a different card style.
+3. **Use animate-ui `Sidebar` for app layouts** unless another layout is requested.
+4. **Prefer Recharts for charts**. shadcn chart primitives are the default wrapper.
+5. **Use icons in this order**: hugeicons, then fontawesome light, then lucide.
+6. **Use `AwesomeDialog` for item create forms**.
+   - Small/simple forms: `container="sheet"` with `side="right"`
+   - Long/complex forms: `container="modal"` or `container="drawer"`
+7. **Choose detail containers based on item complexity**.
+   - Large items: dedicated page
+   - Small items: `AwesomeDialog` right sheet
+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. **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
+
+| Use Case | Default Component | Library |
+|----------|-------------------|---------|
+| Item create form | `AwesomeDialog` | docyrus |
+| Quick record create | `CreateRecordDialog` | docyrus |
+| Item detail (small) | `AwesomeDialog` sheet right | docyrus |
+| Item detail (large) | Dedicated page | — |
+| Inline editing | `EditableRecordDetail` | docyrus |
+| Dashboard card | `AwesomeCard` | docyrus |
+| Stat dashboards | `AwesomeStats` | docyrus |
+| App navigation | `Sidebar` | animate-ui |
+| Data table | `DataTable` | diceui |
+| Editable grid | `Data Grid` | 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 |
+| Gantt/project scheduling | `Gantt` | docyrus |
+| Resource scheduling | `ResourceSchedulerPanel` | docyrus |
+| Team chat | `TeamChatChannel` | docyrus |
+| AI interface | `DocyrusAgent` | docyrus |
+| Pricing / quoting | `PricingEnginePanel` | docyrus |
+| Analytics / pivot | `PivotGrid` | docyrus |
+
+## Quick UI Patterns
+
+### Item create form
+
+```tsx
+<AwesomeDialog open={open} onOpenChange={setOpen} container="sheet" side="right" size="default">
+  <AwesomeDialogHeader title="Create Task" icon="far-plus" />
+  <AwesomeDialogBody>
+    <form.Field name="title">{(field) => <TextFormField field={field} label="Title" />}</form.Field>
+    <form.Field name="status">{(field) => <SelectFormField field={field} label="Status" />}</form.Field>
+  </AwesomeDialogBody>
+  <AwesomeDialogFooter>
+    <Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
+    <Button onClick={handleSubmit}>Create</Button>
+  </AwesomeDialogFooter>
+</AwesomeDialog>
+```
+
+### Item detail with inline editing
+
+```tsx
+<AwesomeDialog open={open} onOpenChange={setOpen} container="sheet" side="right" size="lg" fullscreenable>
+  <AwesomeDialogHeader
+    title="Task Detail"
+    description="Review and edit task fields inline"
+    headerButtons={<Button variant="outline" size="sm" onClick={switchToFullForm}>Edit All</Button>}
+  />
+  <AwesomeDialogBody>
+    <EditableRecordDetail fields={fields} record={record} onSave={handleSave} trackChanges>
+      <EditableRecordDetailField slug="title" />
+      <EditableRecordDetailField slug="status" />
+      <EditableRecordDetailField slug="assignee" />
+      <EditableRecordDetailField slug="due_date" />
+    </EditableRecordDetail>
+  </AwesomeDialogBody>
+</AwesomeDialog>
+```
+
+## TanStack Query Pattern
+
+```typescript
+function useProjects(params?: ICollectionListParams) {
+  const { list } = useBaseProjectCollection()
+  return useQuery({
+    queryKey: ['projects', 'list', params],
+    queryFn: () => list({ columns: PROJECT_COLUMNS, ...params }),
+  })
+}
+
+function useCreateProject() {
+  const { create } = useBaseProjectCollection()
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (data: Record<string, unknown>) => create(data),
+    onSuccess: () => {
+      void qc.invalidateQueries({ queryKey: ['projects'] })
+    },
+  })
+}
+```
+
+## Collection CRUD Methods
+
+```typescript
+const { list, get, create, update, delete: deleteOne, deleteMany } = useBaseProjectCollection()
+
+list(params?: ICollectionListParams)
+get(id, { columns })
+create(data)
+update(id, data)
+deleteOne(id)
+deleteMany({ recordIds })
+```
+
+API endpoint pattern: `/v1/apps/{appSlug}/data-sources/{slug}/items`
+
+## Query Capabilities Summary
+
+The `.list()` method supports:
+
+- `columns`
+- `filters`
+- `filterKeyword`
+- `orderBy`
+- `limit` and `offset`
+- `fullCount`
+- `calculations`
+- `formulas`
+- `childQueries`
+- `pivot`
+- `expand`
+
+## Component Installation Pattern
+
+```bash
+pnpm dlx shadcn@latest add button
+pnpm dlx shadcn@latest add @diceui/data-table
+pnpm dlx shadcn@latest add @animate-ui/sidebar
+pnpm dlx @docyrus/cli add @docyrus/ui-awesome-card
+pnpm dlx shadcn@latest add @reui/file-upload-default
+```
+
+## References
+
+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`
+- `references/preferred-components-catalog.md`
+- `references/component-selection-guide.md`
+- `references/icon-usage-guide.md`

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

@@ -0,0 +1,29 @@
+# Docyrus App Dev React Reference Map
+
+This directory contains the full reference set for `docyrus-app-dev-react`.
+
+## App Development References
+
+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`
+
+## UI Design References
+
+Read these files for component selection, design patterns, and UI library guidance:
+
+- `preferred-components-catalog.md`
+- `component-selection-guide.md`
+- `icon-usage-guide.md`
+
+## How to Use This Skill
+
+1. Start with `../SKILL.md` for the merged operating guidance.
+2. Use the app-development references when working on auth, queries, collections, routing, and mutations.
+3. Use the UI-design references when selecting components, designing layouts, or implementing polished feature flows.
+4. Combine both when building end-to-end Docyrus React features.