docs(base): draft spec for page property type

2026-05-07 06:23:06 +08:00 · 2026-04-20 20:01:44 +01:00
parent eb0f37bfe5
commit 30988c1959
1 changed files with 309 additions and 0 deletions
@@ -0,0 +1,309 @@
 # Base `page` Property Type — Design Spec
 **Date:** 2026-04-20
 **Status:** Draft
 **Feature area:** `apps/server/src/core/base`, `apps/client/src/features/base`, `apps/server/src/core/page`
 ## Goal
 Add a new base property type `page` that lets a user search for and link **one existing page** per cell. Modeled on how the editor's `@` page-mention works — the picker searches existing pages workspace-wide (with current-space prioritized) and the cell renders a live pill with the page's icon and title. No page is auto-created from the picker; users can only link pages that already exist.
 Why: today users who want a page-reference column would have to paste a URL into a `url` cell, which loses the icon + title and doesn't validate. We also want to avoid the Focalboard-style pattern of auto-creating a page-row per table row, which would bloat the pages tree.
 ## Non-goals (v1)
 - **Multiple pages per cell.** Single page only. Forward-compatible: the schema widens trivially to `z.union([z.uuid(), z.array(z.uuid())])` + an `allowMultiple` type option later, with zero data migration (see "Future extension" below).
 - **Sorting by page title.** Would require a JOIN against `pages` in the row-list query; skip in v1. Filter suffices.
 - **Creating pages from within the picker.**
 - **Cross-workspace page linking.**
 - **Rich previews / hover cards** showing page excerpts — pill-only.
 - **Confluence-style section grouping** in the property type picker (e.g. the "Page and live doc" section in the screenshot). Flat list for v1; grouping is a separate polish task.
 ## UX overview
 ### Picker (edit mode)
 - Popover modeled on [cell-person.tsx](../../../apps/client/src/features/base/components/cells/cell-person.tsx) but stripped for single-select. `width=300`, `position="bottom-start"`, `trapFocus`.
 - Top: search input, auto-focused. If a page is currently linked, a removable "tag" for it sits above the search (same shape as `personTag`).
 - Body: results list (max 25), fed by `searchSuggestions({ query, includePages: true, spaceId: base.spaceId, limit: 25 })` — reuses the existing suggestion endpoint, which prioritizes `spaceId` results.
 - Each row: `{icon or IconFileDescription} {title}` + muted space name on the right (so cross-space picks are visually distinct).
 - Empty-query state: if pulling recent-pages is easy to plug in, show recent pages; otherwise "Type to search…" hint.
 - Click or Enter on a highlighted row → `onCommit(pageId)`, popover closes.
 - Esc / click-outside → `onCancel`.
 - Clicking the "Remove" affordance on the current tag → `onCommit(null)`.
 - Keyboard: reuse `useListKeyboardNav`.
 ### View mode
 - Empty cell → empty placeholder (same class as `cellClasses.emptyValue`).
 - Resolved page → pill `{icon or IconFileDescription} {title}`, anchor that navigates to `buildPageUrl(space.slug, slugId, title)` using the helper that [mention-view.tsx](../../../apps/client/src/features/editor/components/mention/mention-view.tsx) already uses.
 - Unresolved (deleted or viewer has no access) → greyed pill "Page not found", no link, `aria-disabled`.
 - Single click on the pill = navigate. Double-click on the cell = open picker (same rule grid-cell applies to other types).
 ### Sort / filter UI
 - [view-sort-config.tsx](../../../apps/client/src/features/base/components/views/view-sort-config.tsx): exclude `page` properties from the sortable set.
 - [view-filter-config.tsx](../../../apps/client/src/features/base/components/views/view-filter-config.tsx): filter editor branch for `page` with operators `isEmpty`, `isNotEmpty`, `any`, `none`. The value picker reuses the same search dropdown from the cell picker.
 ## Data model
 ### Cell value
 - **Stored shape:** `string` (page UUID) or `null`. Parallels `person` in single mode.
 - **Example:** `{ "01998b7e-...": "01998b80-..." }` — property UUID → page UUID.
 ### Property type options
 - **v1:** empty `{}` (reuse `emptyTypeOptionsSchema`).
 - **Future:** `{ allowMultiple?: boolean }`.
 ### Schema additions
 **Server — [base.schemas.ts](../../../apps/server/src/core/base/base.schemas.ts):**
 ```ts
 export const BasePropertyType = {
  // ...existing entries...
  PAGE: 'page',
 } as const;
 // typeOptionsSchemaMap
 [BasePropertyType.PAGE]: emptyTypeOptionsSchema,
 // cellValueSchemaMap
 [BasePropertyType.PAGE]: z.uuid(),
 ```
 **Client — [base.types.ts](../../../apps/client/src/features/base/types/base.types.ts):**
 ```ts
 export type BasePropertyType = ... | 'page';
 export type PageTypeOptions = Record<string, never>;
 ```
 ### Property kind & engine
 **[engine/kinds.ts](../../../apps/server/src/core/base/engine/kinds.ts):**
 ```ts
 export const PropertyKind = {
  // ...existing...
  PAGE: 'page',
 } as const;
 // propertyKind()
 case BasePropertyType.PAGE:
  return PropertyKind.PAGE;
 ```
 **[engine/predicate.ts](../../../apps/server/src/core/base/engine/predicate.ts):** new `pageCondition()` handler — shape follows `selectCondition()` (single UUID stored as text):
 - `isEmpty` / `isNotEmpty` → `textCell` is null or empty
 - `eq` / `neq` → text equality / inequality (null-safe for `neq`)
 - `any` → `textCell IN (...)`
 - `none` → `textCell NOT IN (...)` or null
 Wired into the `switch (kind)` in `buildCondition`:
 ```ts
 case PropertyKind.PAGE:
  return pageCondition(eb, cond);
 ```
 **[engine/sort.ts](../../../apps/server/src/core/base/engine/sort.ts):** no new branch. `page` falls into the default text-sentinel path (sorts by raw UUID string, which is unhelpful but harmless — the sort UI won't expose this type in v1).
 ### Type conversion
 **[base.schemas.ts `CellConversionContext`](../../../apps/server/src/core/base/base.schemas.ts:191):** add a new field:
 ```ts
 export type CellConversionContext = {
  fromTypeOptions?: unknown;
  userNames?: Map<string, string>;
  attachmentNames?: Map<string, string>;
  pageTitles?: Map<string, string>; // NEW
 };
 ```
 **[base-type-conversion.task.ts](../../../apps/server/src/core/base/tasks/base-type-conversion.task.ts):** when `fromType === 'page'`, batch-load titles via the same page repo path used by the new resolver endpoint (see below) and populate `ctx.pageTitles`.
 **`attemptCellConversion` branches:**
 - `page → text`: resolve `ctx.pageTitles.get(uuid)` → title (or `""` if missing).
 - `page → *` (anything else): return `{converted: true, value: null}`.
 - `* → page`: return `{converted: true, value: null}` (free text or other IDs can't be coerced to a valid page UUID).
 ## Server: page resolver endpoint
 New endpoint for cell hydration on the client. Reusing `/pages/info` is inappropriate — it returns full page content and is one-at-a-time.
 ### `POST /bases/pages/resolve`
 **Request:**
 ```ts
 { pageIds: string[] }  // 1 <= length <= 100, enforced server-side; 400 on violation
 ```
 **Response:**
 ```ts
 {
  items: Array<{
    id: string;
    slugId: string;
    title: string | null;
    icon: string | null;
    spaceId: string;
    space: { id: string; slug: string; name: string };
  }>;
 }
 ```
 ### Behavior
 1. Deduplicate input IDs.
 2. Select from `pages` where `id IN (...)` AND `deletedAt IS NULL` AND `workspaceId = current`.
 3. Filter the result set through `pagePermissionRepo.filterAccessiblePageIds({ pageIds, userId })` — same mechanism used by [search.service.ts:131-139](../../../apps/server/src/core/search/search.service.ts).
 4. Join `spaces` to include `space.slug` and `space.name` for navigation.
 5. Silently omit any ID the user can't see (deleted, restricted, cross-workspace). The client treats any requested ID missing from `items` as "Page not found".
 ### Code layout
 - **Controller:** add method to [base.controller.ts](../../../apps/server/src/core/base/controllers/base.controller.ts) at path `@Post('pages/resolve')`. Guarded by the same `JwtAuthGuard` + workspace check the rest of `/bases/*` uses.
 - **Service:** new file `apps/server/src/core/base/services/base-page-resolver.service.ts` with `resolvePagesForBase(pageIds, workspaceId, userId)`. Keeps the coupling to `PageRepo` + `PagePermissionRepo` isolated to this one file.
 - **Module:** wire the new service into [base.module.ts](../../../apps/server/src/core/base/base.module.ts). `PageRepo` + `PagePermissionRepo` are already shared modules.
 ## Client: cell component & resolver
 ### Batch resolver hook
 New file `apps/client/src/features/base/queries/base-page-resolver-query.ts`:
 ```ts
 export function useResolvedPages(pageIds: string[]): Map<string, ResolvedPage | null>
 ```
 - Deduplicate + sort IDs to form a stable React Query key.
 - Fetch `POST /bases/pages/resolve` with `{ pageIds }`.
 - Return a `Map` keyed by every requested ID — `null` for any ID absent from the server response.
 - `staleTime: 30_000`, `gcTime: 5 * 60_000`.
 - Realtime invalidation: listen for existing page-level websocket events (rename, delete) and invalidate the query when a touched ID intersects our key. Exact event names to be surveyed during plan writing.
 ### Cell component
 New file `apps/client/src/features/base/components/cells/cell-page.tsx`:
 ```ts
 type CellPageProps = {
  value: unknown;
  property: IBaseProperty;
  rowId: string;
  isEditing: boolean;
  onCommit: (value: unknown) => void;
  onCancel: () => void;
 };
 ```
 **Behavior:**
 - Parse value: accept `string` only (ignore arrays — they'd be from a future multi mode that we drop until upgraded).
 - `useResolvedPages([value])` — yes even for single lookups; the hook dedupes internally so multiple cells sharing the same page ID hit one request.
 - View mode: resolved → pill with icon+title, anchor to `buildPageUrl`. Unresolved → greyed "Page not found".
 - Edit mode: popover picker (see UX overview). Search via existing `searchSuggestions`.
 Wire into [grid-cell.tsx](../../../apps/client/src/features/base/components/grid/grid-cell.tsx):
 ```ts
 const cellComponents = {
  // ...existing...
  page: CellPage,
 };
 ```
 ### Property type picker
 [property-type-picker.tsx](../../../apps/client/src/features/base/components/property/property-type-picker.tsx): append one entry (after `file`):
 ```ts
 { type: "page", icon: IconFileDescription, labelKey: "Page" },
 ```
 ### Filter editor
 [view-filter-config.tsx](../../../apps/client/src/features/base/components/views/view-filter-config.tsx): new branch for `page`:
 - Operators: `isEmpty`, `isNotEmpty`, `any`, `none`.
 - Value picker for `any`/`none`: reuses the same `searchSuggestions`-backed search dropdown from the cell picker — user picks one or more pages as filter operands.
 ### Sort editor
 [view-sort-config.tsx](../../../apps/client/src/features/base/components/views/view-sort-config.tsx): exclude `page` from the list of sortable property types.
 ## Testing
 ### Server — unit
 - **Schema:** `validateCellValue('page', uuid)` passes; with garbage string / number → fails; with `null` → passes (null = empty).
 - **Conversion:**
  - `attemptCellConversion('page', 'text', uuid, { pageTitles: Map<uuid,title> })` → resolved title.
  - Same call with empty `pageTitles` → `""`.
  - `page → number/date/select/…` → `{converted: true, value: null}`.
  - `text → page` with any string input → `{converted: true, value: null}`.
 - **Predicate:** for each operator (`isEmpty`, `isNotEmpty`, `eq`, `neq`, `any`, `none`), `pageCondition()` returns the expected Kysely expression shape.
 ### Server — integration
 - **Resolver endpoint `POST /bases/pages/resolve`:**
  - valid IDs in an accessible space → present in `items`
  - deleted pages (trash) → absent
  - pages in a space the user isn't a member of → absent
  - pages in another workspace → absent
  - empty array → 400
  - array length > 100 → 400
 - **Row CRUD:** create a property of type `page`, write a cell with a UUID, read back → round-trip shape is `string`.
 - **View filter:** create a view config with `{ op: 'any', propertyId, value: [uuidA, uuidB] }`, hit row-list, verify only matching rows returned.
 ### Client — unit (Vitest + React Testing Library)
 - `cell-page.test.tsx`:
  - view mode with resolved page → renders pill with icon + title and an `<a>` to the computed URL
  - view mode with unresolved page (null in resolver map) → renders greyed "Page not found", no `<a>`
  - double-click opens picker
  - Enter on highlighted result commits `pageId`
  - Esc cancels
  - Remove tag button commits `null`
 - `base-page-resolver-query.test.ts`:
  - dedupes IDs
  - stable query key across re-renders with same set
  - missing IDs render as `null` in the returned map
 ### Manual QA checklist
 - Link a page in the same space.
 - Link a page in another space → pill shows, picker shows muted space-name hint.
 - Remove link → cell empties.
 - Delete linked page (via trash) → cell flips to "Page not found" on next resolver refetch.
 - Viewer loses space access → same "Page not found" fallback.
 - Rename linked page → within ≤30s (staleTime) the pill reflects the new title; realtime event should also trigger refetch.
 - Filter: `isEmpty`, `isNotEmpty`, `any` (multi-select), `none`.
 - Conversion `page → text` populates cells with page titles.
 - Conversion `text → page` wipes cells.
 ## Rollout
 - **No DB migration.** All changes are code-only: new enum value, new cell-value validator entry, new engine kind branch, new endpoint.
 - **No feature flag.** The type appears in the picker as soon as the build ships. Backwards-compatible since `'page'` is a new type identifier.
 - Existing bases continue to work unchanged.
 ## Risks & open questions
 - **30s staleTime.** Renames take up to 30s to propagate without realtime invalidation. The realtime hook should shrink this to near-zero in practice; verify in QA. If it feels slow, drop `staleTime` to `0` and rely solely on realtime + refetch-on-window-focus.
 - **"Page not found" label.** i18n-friendly; run through the translation pipeline. Consider whether to differentiate deleted vs. restricted — current answer: no, one label covers both and matches Confluence's behavior.
 - **Cross-space name exposure.** The picker surfaces the space name of pages the user can access cross-space. This is already exposed via the existing page-mention flow, so no new exposure, but flag in review.
 ## Future extension (multiple pages per cell)
 When `allowMultiple` lands:
 1. Widen cell-value schema: `z.uuid()` → `z.union([z.uuid(), z.array(z.uuid())])`. Existing single-UUID cells continue to validate.
 2. Add `allowMultiple` boolean to `pageTypeOptionsSchema` (default `false` for existing properties).
 3. In [predicate.ts](../../../apps/server/src/core/base/engine/predicate.ts), branch `pageCondition` on `allowMultiple`: `true` → reuse `arrayOfIdsCondition`; `false` → keep the current text-based path.
 4. Client cell normalizes on read (`Array.isArray(value) ? value : typeof value === 'string' ? [value] : []`), mirrors [cell-person.tsx:33](../../../apps/client/src/features/base/components/cells/cell-person.tsx).
 5. No data writes required for existing cells.
 This spec leaves room for that change without locking the storage shape.