@pilotiq/pilotiq 0.7.1 → 0.8.0

package/dist/pageData/navigation.d.ts

@@ -0,0 +1,292 @@
+import type { Pilotiq, PilotiqConfig } from '../Pilotiq.js';
+import type { Page } from '../Page.js';
+import type { ResourceClass, NavigationBadgeColor } from '../Resource.js';
+import type { GlobalClass } from '../Global.js';
+import type { ElementMeta } from '../schema/Element.js';
+import type { ThemeMeta } from '../theme/types.js';
+import { type SerializedIcon } from '../icons/types.js';
+import type { UserMenuItemMeta } from '../UserMenuItem.js';
+import { type RenderHookMap, type RenderHookName } from '../RenderHook.js';
+import { type PageRole } from '../applyPageHooks.js';
+/**
+ * Top-right user dropdown shipped to the renderer in `viewProps.panel`.
+ * `null` when no `Pilotiq.user(req => …)` resolver is configured or the
+ * resolver returns `null` (no logged-in user) — the renderer suppresses
+ * the dropdown entirely in that case.
+ *
+ * `user.name / user.email / user.avatar` are duck-typed off the
+ * resolver's return value; whichever fields are present round-trip into
+ * the dropdown trigger (initials fall back to the first two letters of
+ * `name` when no avatar URL is set).
+ */
+export interface UserMenuMeta {
+    user: {
+        name?: string;
+        email?: string;
+        avatar?: string;
+    };
+    items: UserMenuItemMeta[];
+    signOut?: {
+        url: string;
+        label: string;
+        method: 'POST' | 'GET';
+    };
+}
+/**
+ * Bell-icon dropdown configuration shipped under `viewProps.panel`. Sparse —
+ * absent when `Pilotiq.databaseNotifications()` wasn't called OR when no
+ * user resolves (anonymous request → no inbox to surface). Renderer mounts
+ * the bell only when this is set.
+ *
+ * Routes are absolute URLs (panel `basePath` already applied). Client
+ * substitutes `:id` per row when calling read / unread; `_widget`-style
+ * params aren't used here because the bell only ever issues these four
+ * fetch shapes.
+ *
+ * `polling` mirrors `DatabaseNotificationsConfig.polling` — `null` ships
+ * over the wire to disable client-side polling. The bell still fetches on
+ * mount + after every mark-read mutation.
+ */
+export interface DatabaseNotificationsMeta {
+    position: 'topbar' | 'sidebar';
+    polling: number | null;
+    pageSize: number;
+    badgeColor: NavigationBadgeColor;
+    trigger?: {
+        icon?: string;
+        label?: string;
+    };
+    listUrl: string;
+    readAllUrl: string;
+    /** Template URL with literal `:id` placeholder. Client replaces. */
+    readUrl: string;
+    /** Template URL with literal `:id` placeholder. Client replaces. */
+    unreadUrl: string;
+    /**
+     * Template URL for the notification-action dispatch endpoint with
+     * literal `:id` and `:actionName` placeholders. Bell client builds
+     * per-action URLs by substituting both at render time. Used only by
+     * `handler`-mode actions; `url` / `post` actions ride their own URL
+     * verbatim.
+     */
+    actionUrl: string;
+    /**
+     * Phase 2 — broadcast hint. Sparse — absent when
+     * `databaseNotifications({ broadcast: true })` wasn't set OR when no
+     * resolved user has an `id` to scope the channel to.
+     *
+     * Client connects to `wsUrl` via `@rudderjs/broadcast`'s
+     * `RudderSocket`, subscribes to the `channel` (already includes the
+     * `private-` prefix), and listens for `event` to trigger refetches.
+     */
+    broadcast?: {
+        wsUrl: string;
+        channel: string;
+        event: string;
+    };
+}
+/**
+ * Right-sidebar shipped under `viewProps.panel.rightSidebar`. Sparse —
+ * absent from `panelInfo()` when no contributions are registered, every
+ * registered contribution failed `canAccess(user)`, or every visible
+ * contribution is `hidden: true`. Renderer mounts the chrome only when
+ * this is set.
+ *
+ * The React component reference for each contribution does NOT travel
+ * here — only its tab-strip metadata. The actual body component is
+ * resolved client-side from the Vite plugin's `_components.ts` manifest
+ * keyed by contribution `id`, mirroring the icon-class round-trip.
+ *
+ * `defaultWidth` rolls up: contribution-level value when one
+ * contribution was registered with one, otherwise the panel-level
+ * baseline (`RIGHT_PANEL_DEFAULT_WIDTH`). Client also clamps
+ * localStorage values to `[minWidth, maxWidth]`.
+ */
+export interface RightPanelMeta {
+    id: string;
+    label: string;
+    icon?: SerializedIcon;
+    defaultWidth: number;
+}
+export interface RightSidebarMeta {
+    panels: RightPanelMeta[];
+    defaultWidth: number;
+    minWidth: number;
+    maxWidth: number;
+}
+/**
+ * Single nav-tree entry. `name` is the JS class name (`R.name` /
+ * `G.name` / `P.name`) — also the lookup key into the build-time
+ * `_components.ts` manifest the Vite plugin emits, so component-typed
+ * icons resolve from the same identifier.
+ */
+export interface NavItem {
+    name: string;
+    label: string;
+    url: string;
+    icon?: SerializedIcon;
+    group?: string;
+    sort?: number;
+    badge?: string;
+    badgeColor?: NavigationBadgeColor;
+    children?: NavItem[];
+}
+/**
+ * Build the panel header summary + the unified navigation tree.
+ *
+ * Pipeline:
+ *   1. flatten resources + globals + pages into raw NavItem records
+ *   2. drop items whose `canAccess(user)` (Plan #10) returns false
+ *   3. resolve `navigationParentItem` references → nest under parents
+ *      (cycles broken with a console warn; dangling parents render at top level)
+ *   4. sort within each grouping (top-level *and* every parent's children)
+ *      by `navigationSort` ascending → registration order
+ *   5. resolve every `navigationBadge()` in parallel via `Promise.all`;
+ *      handler errors are swallowed (badge omitted) so a flaky count
+ *      never blanks the page
+ *
+ * `req` is the active request; pilotiq calls `pilotiq.resolveUser(req)`
+ * once and threads the user into every Resource/Global/Page `canAccess`
+ * check. When `Pilotiq.user(fn)` isn't configured, user is `null` and the
+ * default `canAccess` returns true → no items dropped.
+ */
+/**
+ * Optional route-context for `panelInfo()`. When set, render-hook
+ * `scope: { resource | page | global }` filters fire correctly for the
+ * active route. Missing keys mean the slot has no scope-able identifier
+ * (chrome-only routes); scope-less hooks still fire either way.
+ *
+ * `url` defaults to `cfg.path` when unset. `recordId` rides through to
+ * `RenderHookContext.recordId` for hooks that need it.
+ */
+export interface PanelInfoRoute {
+    resource?: ResourceClass;
+    page?: typeof Page;
+    global?: GlobalClass;
+    recordId?: string;
+    url?: string;
+}
+export declare function panelInfo(pilotiq: Pilotiq, req?: unknown, route?: PanelInfoRoute): Promise<{
+    aiSuggestionsMode?: "review";
+    renderHooks?: Partial<Record<RenderHookName, ElementMeta[]>>;
+    rightSidebar?: RightSidebarMeta;
+    databaseNotifications?: DatabaseNotificationsMeta;
+    userMenu?: UserMenuMeta;
+    name: string;
+    branding: {
+        title?: string;
+        logo?: string;
+    };
+    navigation: NavItem[];
+    theme: ThemeMeta | undefined;
+    themeEditor: boolean;
+}>;
+/**
+ * Build the bell-icon meta. Returns `null` when:
+ *   - `Pilotiq.databaseNotifications()` was never called, OR
+ *   - no user resolves (no inbox to surface).
+ *
+ * Defaults follow Filament: 30s polling, 25 rows per page, primary
+ * badge color, topbar position.
+ */
+export declare function buildDatabaseNotificationsMeta(cfg: Readonly<PilotiqConfig>, user: unknown): DatabaseNotificationsMeta | null;
+/**
+ * Build the right-sidebar meta from registered contributions. Returns
+ * `null` when:
+ *
+ *   - no contributions were registered, OR
+ *   - every contribution failed `canAccess(user)` (or its predicate
+ *     threw — fail-closed), OR
+ *   - every passing contribution is `hidden: true` (no tab-strip
+ *     surface to mount; programmatic-open consumers should ship at
+ *     least one visible tab).
+ *
+ * Visible contributions are sorted by `sort` ascending (default 100),
+ * with registration order as a stable tiebreaker. Each entry's icon is
+ * serialized through `serializeIcon` keyed on the contribution `id`
+ * (Phase B's Vite plugin extends `_components.ts` to round-trip
+ * component-typed icons under that key). `defaultWidth` rolls up:
+ * panel-level baseline is `RIGHT_PANEL_DEFAULT_WIDTH`; per-contribution
+ * overrides ride on `RightPanelMeta.defaultWidth`.
+ *
+ * Errors thrown by `canAccess` are swallowed (the contribution is
+ * dropped + a single console warn is emitted) so a flaky predicate on
+ * one pane never blanks the whole sidebar.
+ */
+export declare function buildRightSidebarMeta(cfg: Readonly<PilotiqConfig>, user: unknown): Promise<RightSidebarMeta | null>;
+/**
+ * Resolve every chrome render hook (body / topbar / sidebar / user-menu
+ * / footer / head). Returns a sparse map — slots with no matching
+ * registered entries are omitted so the wire payload stays minimal on
+ * panels that don't use render hooks at all.
+ */
+export declare function resolveChromeHooks(pilotiq: Pilotiq, user: unknown, route: PanelInfoRoute): Promise<RenderHookMap>;
+/**
+ * Resolve a subset of page-role render hooks (e.g. `panels::page.start`
+ * + the list-records / create-record / view-record / edit-record /
+ * global-search slot families). Per-page-role data builders call this
+ * after schema resolution and stamp the result on `viewProps.renderHooks`.
+ *
+ * `names` lets each builder declare exactly which slots it serves so a
+ * list-page builder doesn't ship slots that only fire on the edit page.
+ */
+/**
+ * Per-builder one-shot — resolve the role's slot set + splice the
+ * results into the resolved schema. Wraps the two steps a per-builder
+ * data fn always does in lockstep:
+ *
+ *   1. `resolvePageHooks(pilotiq, user, pageHooksFor(role), route)`
+ *   2. `applyPageHooks(schemaData, hooks, role)`
+ *
+ * Returns the wrapped `ElementMeta[]`. No-op when the panel has no
+ * registered hooks. Pass through what you'd pass to `panelInfo()`'s
+ * route arg — same shape.
+ */
+export declare function applyRoleHooks(pilotiq: Pilotiq, user: unknown, role: PageRole, schemaData: ElementMeta[], route?: PanelInfoRoute): Promise<ElementMeta[]>;
+export declare function resolvePageHooks(pilotiq: Pilotiq, user: unknown, names: readonly RenderHookName[], route: PanelInfoRoute): Promise<RenderHookMap>;
+/**
+ * Build the top-right user-menu meta. Returns `null` when:
+ *   - `Pilotiq.user()` isn't configured, or
+ *   - the resolver returned `null` (anonymous request), or
+ *   - the user object has no extractable identity AND the panel
+ *     configured no items / no sign-out (nothing to render).
+ *
+ * Items resolve in parallel with their visibility predicates
+ * (`UserMenuItem.visible`). Throwing predicates fail closed (item
+ * dropped). Sort by `.sort(n)` ascending → registration order.
+ */
+export declare function buildUserMenu(pilotiq: Pilotiq, user: unknown): Promise<UserMenuMeta | null>;
+/** Build the auto-injected profile entry from `cfg.profilePage`. The
+ *  Page's `static label` / `static icon` win; defaults `'Edit profile'`
+ *  + `'user-circle'` (registry-resolved). Returns `null` when no
+ *  profile page is configured or `Page.canAccess(user)` denies. */
+export declare function buildProfileMenuItem(cfg: Readonly<PilotiqConfig>, user: unknown): Promise<UserMenuItemMeta | null>;
+/** Duck-type the user object for display fields. We never throw — a
+ *  user resolver might return literally anything (a primitive, a class
+ *  instance with getters, a plain object) and the dropdown should
+ *  degrade gracefully (initials fallback to '?' when no name found). */
+export declare function extractUserIdentity(user: unknown): {
+    name?: string;
+    email?: string;
+    avatar?: string;
+};
+/** @internal Internal node before nesting; carries the registration index
+ *  so we can stable-sort by it as the tie-breaker. */
+interface RawNavItem extends NavItem {
+    parent?: string;
+    /** Registration index across resources → globals → pages (in that order),
+     *  so resources beat globals on a sort tie within the same group. */
+    _idx: number;
+}
+/** Plan #10 — stamp the resolved user onto a SchemaContext so action
+ *  visibility predicates can see it during `resolveSchema`. The `user`
+ *  field is opaque (whatever `Pilotiq.user(req => …)` returns); skipped
+ *  when null/undefined to keep ctx tidy. */
+export declare function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<NavItem[]>;
+/**
+ * Resolve `parent` references → nest, drop cycles, sort within each
+ * grouping, then strip internal scaffolding (`parent`, `_idx`).
+ */
+export declare function nestAndSort(raw: RawNavItem[]): NavItem[];
+export {};
+//# sourceMappingURL=navigation.d.ts.map

package/dist/pageData/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/pageData/navigation.ts"],"names":[],"mappings":"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"}