@pilotiq/pilotiq 0.1.0

package/dist/Resource.d.ts

@@ -0,0 +1,290 @@
+import type { Element } from './schema/Element.js';
+import type { Form } from './elements/Form.js';
+import { Table } from './elements/Table.js';
+import type { Page } from './Page.js';
+import type { ModelLike, ModelQuery, QueryContext } from './orm/modelDefaults.js';
+import type { IconValue } from './icons/types.js';
+import type { RelationManager } from './RelationManager.js';
+import type { SchemaContext } from './schema/resolveSchema.js';
+import type { ClusterClass } from './Cluster.js';
+/** Map of resource page roles to Page subclasses. */
+export interface ResourcePages {
+    index?: typeof Page;
+    create?: typeof Page;
+    edit?: typeof Page;
+    view?: typeof Page;
+}
+/** Pill color tokens for `navigationBadgeColor`. Matches the shared color
+ * palette used by `ListTab.badgeColor` so the renderer can re-use the
+ * same Tailwind utility map. */
+export type NavigationBadgeColor = 'default' | 'primary' | 'success' | 'warning' | 'destructive' | 'info';
+/** Returned by `navigationBadge`: a string/number to render as a pill,
+ * or undefined to render no pill. May be async. Errors thrown from this
+ * handler are swallowed by `panelInfo()` so a flaky count never blanks
+ * the page. */
+export type NavigationBadgeHandler = () => string | number | undefined | Promise<string | number | undefined>;
+/**
+ * Abstract Resource base class. **All methods are static** — resources are
+ * registered by class, not by instance. Routes look up the class and call
+ * statics directly.
+ *
+ * Subclasses override `form()`, `table()`, `detail()`, and `pages()` to
+ * shape the resource. Defaults make the most-common case (CRUD with a
+ * form + a table) work with minimal boilerplate; 2.2 will fill in
+ * auto-generated default Page classes.
+ */
+export declare abstract class Resource {
+    /** Human-readable plural label, e.g. `'Articles'`. */
+    static label: string;
+    /** Singular label, e.g. `'Article'`. */
+    static labelSingular: string;
+    /** Breadcrumb label override. Falls through to `label`. Use this when
+     *  the breadcrumb chain reads better with a different word than the
+     *  sidebar / page-title plural — e.g. `label = 'Blog Posts'` paired
+     *  with `breadcrumb = 'Posts'` for a tighter chain. */
+    static breadcrumb: string | undefined;
+    /** URL slug. Derived from `label` when unset. */
+    static slug: string;
+    /** Sidebar / nav icon. Either a kebab-case registry name (e.g.,
+     * `'file'`) or a React component reference imported from any icon
+     * library (e.g., `import { Newspaper } from 'lucide-react'`).
+     * See `@pilotiq/pilotiq/icons` for the registry; component refs
+     * resolve via the Vite-plugin `_components.ts` manifest. */
+    static icon: IconValue;
+    /** Group label this resource renders under in the sidebar. Items
+     * without a group land in an unnamed top section. */
+    static navigationGroup: string | undefined;
+    /** Sort key within a group. Lower sorts first; ties fall back to
+     * registration order. Items without a sort go after sorted items. */
+    static navigationSort: number | undefined;
+    /** Sidebar label override. `Resource.label` still drives page titles. */
+    static navigationLabel: string | undefined;
+    /** Sidebar icon override. Same `IconValue` contract as `icon`. */
+    static navigationIcon: IconValue;
+    /** Server-eval'd badge handler; rendered as a small pill next to the
+     * label. Errors thrown here are swallowed so a broken count never
+     * breaks page render. */
+    static navigationBadge: NavigationBadgeHandler | undefined;
+    /** Pill color for the badge. */
+    static navigationBadgeColor: NavigationBadgeColor;
+    /** Class name (`Resource.name` / `Global.name` / `Page.name`) of a
+     * parent nav item. Renders nested under the parent when set; renders
+     * at top level when the name doesn't resolve. */
+    static navigationParentItem: string | undefined;
+    /**
+     * Cluster this resource belongs to. When set, the resource's URLs gain
+     * the cluster's slug as a prefix segment (e.g. `/admin/content/articles`
+     * instead of `/admin/articles`) and the resource nests under the
+     * cluster's nav entry instead of appearing at the panel top level.
+     *
+     * The referenced class must be registered via `Pilotiq.clusters([…])`;
+     * boot fails otherwise.
+     */
+    static cluster?: ClusterClass;
+    /** Column that names a record when referring to it in search results,
+     * breadcrumbs, or relation pickers. Resolution order at the call site
+     * is `recordTitleAttribute` → `'name'` → `'title'` → `'id'`. */
+    static recordTitleAttribute: string | undefined;
+    /**
+     * Optional ORM model. When set, `defaultPages` auto-fills `Form.save`,
+     * `Form.loadRecord`, `Table.records`, and `Resource.deleteRecord` so
+     * the common CRUD case needs no manual wiring. Anything explicitly
+     * configured on `form()` / `table()` still wins.
+     *
+     * Any object satisfying `ModelLike` works — `@rudderjs/orm` `Model`
+     * subclasses do so structurally via their static methods.
+     */
+    static model?: ModelLike;
+    /**
+     * Hook for scoping every query against this resource's table — list
+     * pages, global search, find-by-PK loads (record load for view / edit
+     * pages, policy lookups). Default returns `this.model.query()`.
+     *
+     * Override to install tenant scopes, default ordering, eager-load
+     * defaults, or any other always-on filter:
+     *
+     * @example
+     * static override query(ctx) {
+     *   return super.query(ctx).where('tenantId', (ctx?.user as any)?.tenantId)
+     * }
+     *
+     * @example
+     * static override query(ctx) {
+     *   return super.query(ctx).orderBy('createdAt', 'DESC')
+     * }
+     *
+     * Soft-delete restore / force-delete routes deliberately bypass this
+     * — they build their own `query().withTrashed()` chain so a scope that
+     * hides trashed rows doesn't hide records the operator is trying to
+     * recover. Everything else routes through here.
+     *
+     * Throws when `static model` isn't set; subclasses without a model
+     * must override `query()` directly to return whatever query builder
+     * they're driving.
+     */
+    static query(_ctx?: QueryContext): ModelQuery;
+    /** Enable soft-delete UX (TrashedFilter, Restore action,
+     * Force-delete action, soft-delete-aware row visibility). Default
+     * `false`. Requires `Resource.model` to be set, with
+     * `Model.softDeletes = true` on the rudder side. */
+    static softDeletes: boolean;
+    /** Column name carrying the soft-delete timestamp on each row.
+     * Per-row visibility predicates and the trashed-row branch in
+     * `Action.delete` consult `record[deletedAtColumn]`. Default
+     * matches rudder's `'deletedAt'`. */
+    static deletedAtColumn: string;
+    /** Persist the active list filter / search / sort slice on the
+     *  user's session so revisiting the resource lands on the same view.
+     *  No-ops silently when `@rudderjs/session` isn't mounted. */
+    static persistFiltersInSession: boolean;
+    /** Skip server-side row loading on list pages; the client paints a
+     *  skeleton and fetches rows from `GET {base}/{slug}/_table` after
+     *  mount. URL chrome (filters / search / page / group) still mirrors
+     *  on the SSR pass so the skeleton frame doesn't reset visible state. */
+    static deferLoading: boolean;
+    /** Include this resource in Cmd+K palette results. Default `false` —
+     * quiet resources don't pollute results until users opt in. */
+    static globalSearch: boolean;
+    /**
+     * Columns the default search query LIKE-matches against. The default
+     * dedupes `recordTitleAttribute` (Plan #9) with every searchable
+     * column on the resource's table. Override to constrain or extend.
+     * Returning an empty array effectively opts the resource out even
+     * when `globalSearch=true`.
+     */
+    static globallySearchableAttributes(): string[];
+    /**
+     * Title shown in the palette result row. Default resolution chain:
+     * `record[recordTitleAttribute]` → `record.name` → `record.title` →
+     * `record.id`. Override to customise (e.g. include the id).
+     */
+    static getGlobalSearchResultTitle(record: unknown): string;
+    /**
+     * Optional second-line text under the title. Returning `undefined`
+     * tells the renderer to skip the subtitle row. Useful for status,
+     * timestamps, or category pills.
+     */
+    static getGlobalSearchResultSubtitle(_record: unknown): string | undefined;
+    /**
+     * URL the palette navigates to on Enter. Default uses the View page
+     * when one exists, else the Edit page, else the resource list. Pass
+     * `base` (the panel base path) so overrides don't have to thread it
+     * through the panel config.
+     */
+    static getGlobalSearchResultUrl(record: unknown, base: string): string;
+    /**
+     * Override the default LIKE-on-attributes search query. Return a
+     * `ModelQuery` (still chainable through `paginate(1, limit)`) for
+     * advanced cases — joins, full-text, `pg_trgm`. Returning `undefined`
+     * (the default) falls through to the framework-built query.
+     */
+    static getGlobalSearchQuery(_needle: string): ModelQuery | undefined;
+    /** Coarse "should this resource exist for this user at all" gate.
+     * Failing `canAccess` drops the resource from the nav tree entirely
+     * and 403s every route under it. */
+    static canAccess(_user: unknown): Promise<boolean>;
+    /** Allowed to load the index/list page. Item still appears in nav
+     * when `canAccess` passes but `canViewAny` fails — the URL just 403s. */
+    static canViewAny(_user: unknown): Promise<boolean>;
+    /** Allowed to load the read-only view page for a given record. */
+    static canView(_user: unknown, _record: unknown): Promise<boolean>;
+    /** Allowed to access the create page + invoke the create form.
+     * Auto-hides `Action.create(R, …)` triggers that haven't set an
+     * explicit `.visible()` rule. */
+    static canCreate(_user: unknown): Promise<boolean>;
+    /** Allowed to edit a given record. Auto-hides `Action.edit(R, …)`
+     * triggers without an explicit `.visible()` rule. */
+    static canEdit(_user: unknown, _record: unknown): Promise<boolean>;
+    /** Allowed to delete a given record. Auto-hides `Action.delete(R, …)`
+     * triggers without an explicit `.visible()` rule. */
+    static canDelete(_user: unknown, _record: unknown): Promise<boolean>;
+    /** Plan #13 — allowed to restore a soft-deleted record. Defaults
+     * `true`; auto-hides `Action.restore(R, …)` when false. Only
+     * checked on resources with `softDeletes = true`. */
+    static canRestore(_user: unknown, _record: unknown): Promise<boolean>;
+    /** Plan #13 — allowed to permanently delete a soft-deleted record.
+     * Defaults to whatever `canDelete` returns when this method is *not*
+     * overridden — soft-delete restore is generally lower-privilege
+     * than force-delete, but force-delete inheriting from delete is the
+     * conservative starting point. Override this to tighten or loosen
+     * independently. Only checked on resources with `softDeletes = true`.
+     *
+     * The `safeForceDeletePolicy` helper (used by routes + `Action.forceDelete`
+     * visibility) detects the un-overridden case via reference equality
+     * against `Resource.canForceDelete` — same trick Plan #11 uses for
+     * `safeManagerPolicy`. Don't reassign `Resource.canForceDelete`
+     * outside of subclass overrides; it'd break the detection globally. */
+    static canForceDelete(this: ResourceClass, user: unknown, record: unknown): Promise<boolean>;
+    /**
+     * Configure the form used by `create` and `edit` pages by default.
+     * Receives a fresh `Form` instance; return the configured form.
+     */
+    static form(form: Form): Form;
+    /**
+     * Configure the table used by the `index` page by default.
+     * Receives a fresh `Table` instance; return the configured table.
+     */
+    static table(table: Table): Table;
+    /**
+     * Schema for the read-only `view` page. Receives the loaded record.
+     * Returns an array of Elements (typically Sections + display elements).
+     */
+    static detail(_record: unknown): Element[];
+    /**
+     * Plan #15 — schema rendered above the list-page table. Default `[]`.
+     * Typical use: dashboard widgets that contextualize the list (KPI cards,
+     * charts, status alerts). Anything Element-typed is allowed —
+     * `Group / Card / Section` for layout, `Stat / StatsOverview / Chart /
+     * TableWidget / View` for server-data widgets, `Heading / Alert` for
+     * static chrome. Resolves with the same `SchemaContext` passed to the
+     * list page's schema (carries `mode: 'table'`, `basePath`, `user`).
+     * Server-data widgets inside resolve in parallel via the shared
+     * `_widgetData` map and re-fetch through `POST {base}/{slug}/_widget/:id`.
+     * The hook only fires after `Resource.canAccess(user)` passes (route-level
+     * gate) — there's no extra per-hook authorization.
+     */
+    static headerSchema(_ctx?: SchemaContext): Element[] | Promise<Element[]>;
+    /**
+     * Plan #15 — schema rendered below the list-page table. Default `[]`.
+     * Same shape and posture as `headerSchema()`; useful for footnotes,
+     * legends, or "longest-running…" tables that contextualize the list
+     * from below.
+     */
+    static footerSchema(_ctx?: SchemaContext): Element[] | Promise<Element[]>;
+    /**
+     * Delete a record by id. Falls through to `model.delete(id)` when
+     * `static model` is set; otherwise throws so the user knows to wire
+     * something up. Override on the subclass for custom delete logic.
+     * Wired up by the `POST {base}/{slug}/{id}/delete` route.
+     */
+    static deleteRecord(id: string): Promise<void>;
+    /**
+     * User-overridable page map. Return any subset of `{ index, create, edit, view }`
+     * to override the auto-generated defaults; missing keys fall through to
+     * defaults via `resolvePages()`.
+     */
+    static pages(): ResourcePages;
+    /**
+     * Resolved page map: defaults from `defaultPages(this)` overlaid with whatever
+     * `pages()` returns. This is what routing consumes (wired in 2.3).
+     */
+    static resolvePages(): ResourcePages;
+    /**
+     * Plan #11 — relation managers mounted under this resource's edit /
+     * view pages. Each entry is a `RelationManager` subclass; routes are
+     * registered under `${base}/${slug}/:id/${manager.relationship}`.
+     * Default empty.
+     */
+    static relations(): Array<typeof RelationManager>;
+    /** URL slug, derived from `label` when not set explicitly. */
+    static getSlug(): string;
+    /** Sidebar label: `navigationLabel` override falls through to `label`. */
+    static getNavigationLabel(): string;
+    /** Breadcrumb label: `breadcrumb` override falls through to `label`. */
+    static getBreadcrumb(): string;
+    /** Sidebar icon: `navigationIcon` override falls through to `icon`. */
+    static getNavigationIcon(): IconValue;
+}
+/** Constructor type for `Resource` subclasses. Used in panel registration. */
+export type ResourceClass = typeof Resource;
+//# sourceMappingURL=Resource.d.ts.map

package/dist/Resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Resource.d.ts","sourceRoot":"","sources":["../src/Resource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAC3C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACrC,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAGhD,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAG,OAAO,IAAI,CAAA;IACpB,MAAM,CAAC,EAAE,OAAO,IAAI,CAAA;IACpB,IAAI,CAAC,EAAI,OAAO,IAAI,CAAA;IACpB,IAAI,CAAC,EAAI,OAAO,IAAI,CAAA;CACrB;AAED;;gCAEgC;AAChC,MAAM,MAAM,oBAAoB,GAC5B,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,MAAM,CAAA;AAE1E;;;eAGe;AACf,MAAM,MAAM,sBAAsB,GAChC,MAAM,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAA;AAE1E;;;;;;;;;GASG;AACH,8BAAsB,QAAQ;IAC5B,sDAAsD;IACtD,MAAM,CAAC,KAAK,EAAE,MAAM,CAAc;IAElC,wCAAwC;IACxC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAa;IAEzC;;;2DAGuD;IACvD,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAY;IAEjD,iDAAiD;IACjD,MAAM,CAAC,IAAI,EAAE,MAAM,CAAK;IAExB;;;;gEAI4D;IAC5D,MAAM,CAAC,IAAI,EAAE,SAAS,CAAS;IAM/B;yDACqD;IACrD,MAAM,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAY;IAEtD;yEACqE;IACrE,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAY;IAErD,yEAAyE;IACzE,MAAM,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAY;IAEtD,kEAAkE;IAClE,MAAM,CAAC,cAAc,EAAE,SAAS,CAAY;IAE5C;;6BAEyB;IACzB,MAAM,CAAC,eAAe,EAAE,sBAAsB,GAAG,SAAS,CAAY;IAEtE,gCAAgC;IAChC,MAAM,CAAC,oBAAoB,EAAE,oBAAoB,CAAY;IAE7D;;qDAEiD;IACjD,MAAM,CAAC,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAY;IAE3D;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,YAAY,CAAA;IAE7B;;oEAEgE;IAChE,MAAM,CAAC,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAY;IAE3D;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,CAAC,EAAE,SAAS,CAAA;IAExB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU;IAqB7C;;;wDAGoD;IACpD,MAAM,CAAC,WAAW,EAAE,OAAO,CAAQ;IAEnC;;;yCAGqC;IACrC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAc;IAE5C;;kEAE8D;IAC9D,MAAM,CAAC,uBAAuB,EAAE,OAAO,CAAQ;IAE/C;;;6EAGyE;IACzE,MAAM,CAAC,YAAY,EAAE,OAAO,CAAQ;IAQpC;mEAC+D;IAC/D,MAAM,CAAC,YAAY,EAAE,OAAO,CAAQ;IAEpC;;;;;;OAMG;IACH,MAAM,CAAC,4BAA4B,IAAI,MAAM,EAAE;IAiB/C;;;;OAIG;IACH,MAAM,CAAC,0BAA0B,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM;IAY1D;;;;OAIG;IACH,MAAM,CAAC,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAI1E;;;;;OAKG;IACH,MAAM,CAAC,wBAAwB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAStE;;;;;OAKG;IACH,MAAM,CAAC,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAYpE;;wCAEoC;WACvB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAExD;6EACyE;WAC5D,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAEzD,kEAAkE;WACrD,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAExE;;qCAEiC;WACpB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAExD;yDACqD;WACxC,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAExE;yDACqD;WACxC,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAE1E;;yDAEqD;WACxC,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAE3E;;;;;;;;;;;2EAWuE;WAC1D,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlG;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAE7B;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK;IAEjC;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE;IAE1C;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAEzE;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAEzE;;;;;OAKG;WACU,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUpD;;;;OAIG;IACH,MAAM,CAAC,KAAK,IAAI,aAAa;IAE7B;;;OAGG;IACH,MAAM,CAAC,YAAY,IAAI,aAAa;IAMpC;;;;;OAKG;IACH,MAAM,CAAC,SAAS,IAAI,KAAK,CAAC,OAAO,eAAe,CAAC;IAEjD,8DAA8D;IAC9D,MAAM,CAAC,OAAO,IAAI,MAAM;IAIxB,0EAA0E;IAC1E,MAAM,CAAC,kBAAkB,IAAI,MAAM;IAInC,wEAAwE;IACxE,MAAM,CAAC,aAAa,IAAI,MAAM;IAI9B,uEAAuE;IACvE,MAAM,CAAC,iBAAiB,IAAI,SAAS;CAGtC;AAED,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,OAAO,QAAQ,CAAA"}

package/dist/Resource.js

@@ -0,0 +1,362 @@
+import { Table } from './elements/Table.js';
+import { defaultPages } from './defaultPages.js';
+import { resourceBasePath } from './clusterPaths.js';
+/**
+ * Abstract Resource base class. **All methods are static** — resources are
+ * registered by class, not by instance. Routes look up the class and call
+ * statics directly.
+ *
+ * Subclasses override `form()`, `table()`, `detail()`, and `pages()` to
+ * shape the resource. Defaults make the most-common case (CRUD with a
+ * form + a table) work with minimal boilerplate; 2.2 will fill in
+ * auto-generated default Page classes.
+ */
+export class Resource {
+    /** Human-readable plural label, e.g. `'Articles'`. */
+    static label = 'Resources';
+    /** Singular label, e.g. `'Article'`. */
+    static labelSingular = 'Resource';
+    /** Breadcrumb label override. Falls through to `label`. Use this when
+     *  the breadcrumb chain reads better with a different word than the
+     *  sidebar / page-title plural — e.g. `label = 'Blog Posts'` paired
+     *  with `breadcrumb = 'Posts'` for a tighter chain. */
+    static breadcrumb = undefined;
+    /** URL slug. Derived from `label` when unset. */
+    static slug = '';
+    /** Sidebar / nav icon. Either a kebab-case registry name (e.g.,
+     * `'file'`) or a React component reference imported from any icon
+     * library (e.g., `import { Newspaper } from 'lucide-react'`).
+     * See `@pilotiq/pilotiq/icons` for the registry; component refs
+     * resolve via the Vite-plugin `_components.ts` manifest. */
+    static icon = 'file';
+    // ─── Plan #9: navigation metadata ──────────────────────────
+    // Static fields evaluated once at panel-config time; only
+    // `navigationBadge` runs per request. See docs/plans/resource-navigation.md.
+    /** Group label this resource renders under in the sidebar. Items
+     * without a group land in an unnamed top section. */
+    static navigationGroup = undefined;
+    /** Sort key within a group. Lower sorts first; ties fall back to
+     * registration order. Items without a sort go after sorted items. */
+    static navigationSort = undefined;
+    /** Sidebar label override. `Resource.label` still drives page titles. */
+    static navigationLabel = undefined;
+    /** Sidebar icon override. Same `IconValue` contract as `icon`. */
+    static navigationIcon = undefined;
+    /** Server-eval'd badge handler; rendered as a small pill next to the
+     * label. Errors thrown here are swallowed so a broken count never
+     * breaks page render. */
+    static navigationBadge = undefined;
+    /** Pill color for the badge. */
+    static navigationBadgeColor = 'default';
+    /** Class name (`Resource.name` / `Global.name` / `Page.name`) of a
+     * parent nav item. Renders nested under the parent when set; renders
+     * at top level when the name doesn't resolve. */
+    static navigationParentItem = undefined;
+    /**
+     * Cluster this resource belongs to. When set, the resource's URLs gain
+     * the cluster's slug as a prefix segment (e.g. `/admin/content/articles`
+     * instead of `/admin/articles`) and the resource nests under the
+     * cluster's nav entry instead of appearing at the panel top level.
+     *
+     * The referenced class must be registered via `Pilotiq.clusters([…])`;
+     * boot fails otherwise.
+     */
+    static cluster;
+    /** Column that names a record when referring to it in search results,
+     * breadcrumbs, or relation pickers. Resolution order at the call site
+     * is `recordTitleAttribute` → `'name'` → `'title'` → `'id'`. */
+    static recordTitleAttribute = undefined;
+    /**
+     * Optional ORM model. When set, `defaultPages` auto-fills `Form.save`,
+     * `Form.loadRecord`, `Table.records`, and `Resource.deleteRecord` so
+     * the common CRUD case needs no manual wiring. Anything explicitly
+     * configured on `form()` / `table()` still wins.
+     *
+     * Any object satisfying `ModelLike` works — `@rudderjs/orm` `Model`
+     * subclasses do so structurally via their static methods.
+     */
+    static model;
+    /**
+     * Hook for scoping every query against this resource's table — list
+     * pages, global search, find-by-PK loads (record load for view / edit
+     * pages, policy lookups). Default returns `this.model.query()`.
+     *
+     * Override to install tenant scopes, default ordering, eager-load
+     * defaults, or any other always-on filter:
+     *
+     * @example
+     * static override query(ctx) {
+     *   return super.query(ctx).where('tenantId', (ctx?.user as any)?.tenantId)
+     * }
+     *
+     * @example
+     * static override query(ctx) {
+     *   return super.query(ctx).orderBy('createdAt', 'DESC')
+     * }
+     *
+     * Soft-delete restore / force-delete routes deliberately bypass this
+     * — they build their own `query().withTrashed()` chain so a scope that
+     * hides trashed rows doesn't hide records the operator is trying to
+     * recover. Everything else routes through here.
+     *
+     * Throws when `static model` isn't set; subclasses without a model
+     * must override `query()` directly to return whatever query builder
+     * they're driving.
+     */
+    static query(_ctx) {
+        if (!this.model) {
+            throw new Error(`[Pilotiq] ${this.name}.query() requires \`static model = …\` to be set, ` +
+                `or override \`static query(ctx)\` directly to return a custom ModelQuery.`);
+        }
+        return this.model.query();
+    }
+    // ─── Plan #13: soft deletes ────────────────────────────────
+    // Opt-in: when true, pilotiq routes the standard delete action
+    // through `model.delete()` (which writes `deletedAt`), surfaces a
+    // TrashedFilter on the list page, swaps the row-action set on
+    // trashed rows (Restore + Force-delete instead of Edit + Delete),
+    // and exposes two new POST routes: `/:id/restore` and
+    // `/:id/force-delete`. The rudder ORM side must also opt in
+    // (`Model.softDeletes = true`) for the underlying behavior to
+    // engage — pilotiq throws a clear boot error when the flag is
+    // set here but the model lacks `restore` / `forceDelete`.
+    /** Enable soft-delete UX (TrashedFilter, Restore action,
+     * Force-delete action, soft-delete-aware row visibility). Default
+     * `false`. Requires `Resource.model` to be set, with
+     * `Model.softDeletes = true` on the rudder side. */
+    static softDeletes = false;
+    /** Column name carrying the soft-delete timestamp on each row.
+     * Per-row visibility predicates and the trashed-row branch in
+     * `Action.delete` consult `record[deletedAtColumn]`. Default
+     * matches rudder's `'deletedAt'`. */
+    static deletedAtColumn = 'deletedAt';
+    /** Persist the active list filter / search / sort slice on the
+     *  user's session so revisiting the resource lands on the same view.
+     *  No-ops silently when `@rudderjs/session` isn't mounted. */
+    static persistFiltersInSession = false;
+    /** Skip server-side row loading on list pages; the client paints a
+     *  skeleton and fetches rows from `GET {base}/{slug}/_table` after
+     *  mount. URL chrome (filters / search / page / group) still mirrors
+     *  on the SSR pass so the skeleton frame doesn't reset visible state. */
+    static deferLoading = false;
+    // ─── Plan #12: global search ───────────────────────────────
+    // Opt-in: resources with `globalSearch = false` are skipped by the
+    // panel-level Cmd+K palette. Defaults below derive everything from
+    // already-shipped surfaces (`recordTitleAttribute`, `Column.searchable()`,
+    // the standard view URL) so the common case needs zero overrides.
+    /** Include this resource in Cmd+K palette results. Default `false` —
+     * quiet resources don't pollute results until users opt in. */
+    static globalSearch = false;
+    /**
+     * Columns the default search query LIKE-matches against. The default
+     * dedupes `recordTitleAttribute` (Plan #9) with every searchable
+     * column on the resource's table. Override to constrain or extend.
+     * Returning an empty array effectively opts the resource out even
+     * when `globalSearch=true`.
+     */
+    static globallySearchableAttributes() {
+        const attrs = new Set();
+        if (this.recordTitleAttribute)
+            attrs.add(this.recordTitleAttribute);
+        // Materialise the resource's configured table once and read every
+        // `searchable()` column off it. The Table builder is a pure
+        // configuration call (no DB hits, no I/O), so doing this per
+        // search request is fine; resources that don't want this can
+        // override `globallySearchableAttributes()` directly.
+        try {
+            const table = this.table(Table.make());
+            for (const col of table.getColumns()) {
+                if (col.isSearchable())
+                    attrs.add(col.name);
+            }
+        }
+        catch { /* defensive — bad user table()? skip */ }
+        return [...attrs];
+    }
+    /**
+     * Title shown in the palette result row. Default resolution chain:
+     * `record[recordTitleAttribute]` → `record.name` → `record.title` →
+     * `record.id`. Override to customise (e.g. include the id).
+     */
+    static getGlobalSearchResultTitle(record) {
+        const r = record;
+        if (!r)
+            return '';
+        if (this.recordTitleAttribute && r[this.recordTitleAttribute] !== undefined) {
+            return String(r[this.recordTitleAttribute]);
+        }
+        if (r['name'] !== undefined)
+            return String(r['name']);
+        if (r['title'] !== undefined)
+            return String(r['title']);
+        if (r['id'] !== undefined)
+            return String(r['id']);
+        return '';
+    }
+    /**
+     * Optional second-line text under the title. Returning `undefined`
+     * tells the renderer to skip the subtitle row. Useful for status,
+     * timestamps, or category pills.
+     */
+    static getGlobalSearchResultSubtitle(_record) {
+        return undefined;
+    }
+    /**
+     * URL the palette navigates to on Enter. Default uses the View page
+     * when one exists, else the Edit page, else the resource list. Pass
+     * `base` (the panel base path) so overrides don't have to thread it
+     * through the panel config.
+     */
+    static getGlobalSearchResultUrl(record, base) {
+        const r = record;
+        const prefix = resourceBasePath(base, this);
+        if (!r)
+            return prefix;
+        const id = r['id'];
+        if (id === undefined || id === null)
+            return prefix;
+        return `${prefix}/${String(id)}`;
+    }
+    /**
+     * Override the default LIKE-on-attributes search query. Return a
+     * `ModelQuery` (still chainable through `paginate(1, limit)`) for
+     * advanced cases — joins, full-text, `pg_trgm`. Returning `undefined`
+     * (the default) falls through to the framework-built query.
+     */
+    static getGlobalSearchQuery(_needle) {
+        return undefined;
+    }
+    // ─── Plan #10: authorization predicates ────────────────────
+    // All async, all default `true`. Routes call them with the resolved
+    // user (from `Pilotiq.user(fn)`); the renderer threads the same user
+    // into nav-tree filtering and `Action.create/edit/view/delete`
+    // factories. Override per-resource with role/policy logic. The user
+    // argument is whatever `Pilotiq.user(req => …)` returns — opaque to
+    // pilotiq, your shape.
+    /** Coarse "should this resource exist for this user at all" gate.
+     * Failing `canAccess` drops the resource from the nav tree entirely
+     * and 403s every route under it. */
+    static async canAccess(_user) { return true; }
+    /** Allowed to load the index/list page. Item still appears in nav
+     * when `canAccess` passes but `canViewAny` fails — the URL just 403s. */
+    static async canViewAny(_user) { return true; }
+    /** Allowed to load the read-only view page for a given record. */
+    static async canView(_user, _record) { return true; }
+    /** Allowed to access the create page + invoke the create form.
+     * Auto-hides `Action.create(R, …)` triggers that haven't set an
+     * explicit `.visible()` rule. */
+    static async canCreate(_user) { return true; }
+    /** Allowed to edit a given record. Auto-hides `Action.edit(R, …)`
+     * triggers without an explicit `.visible()` rule. */
+    static async canEdit(_user, _record) { return true; }
+    /** Allowed to delete a given record. Auto-hides `Action.delete(R, …)`
+     * triggers without an explicit `.visible()` rule. */
+    static async canDelete(_user, _record) { return true; }
+    /** Plan #13 — allowed to restore a soft-deleted record. Defaults
+     * `true`; auto-hides `Action.restore(R, …)` when false. Only
+     * checked on resources with `softDeletes = true`. */
+    static async canRestore(_user, _record) { return true; }
+    /** Plan #13 — allowed to permanently delete a soft-deleted record.
+     * Defaults to whatever `canDelete` returns when this method is *not*
+     * overridden — soft-delete restore is generally lower-privilege
+     * than force-delete, but force-delete inheriting from delete is the
+     * conservative starting point. Override this to tighten or loosen
+     * independently. Only checked on resources with `softDeletes = true`.
+     *
+     * The `safeForceDeletePolicy` helper (used by routes + `Action.forceDelete`
+     * visibility) detects the un-overridden case via reference equality
+     * against `Resource.canForceDelete` — same trick Plan #11 uses for
+     * `safeManagerPolicy`. Don't reassign `Resource.canForceDelete`
+     * outside of subclass overrides; it'd break the detection globally. */
+    static async canForceDelete(user, record) {
+        return this.canDelete(user, record);
+    }
+    /**
+     * Configure the form used by `create` and `edit` pages by default.
+     * Receives a fresh `Form` instance; return the configured form.
+     */
+    static form(form) { return form; }
+    /**
+     * Configure the table used by the `index` page by default.
+     * Receives a fresh `Table` instance; return the configured table.
+     */
+    static table(table) { return table; }
+    /**
+     * Schema for the read-only `view` page. Receives the loaded record.
+     * Returns an array of Elements (typically Sections + display elements).
+     */
+    static detail(_record) { return []; }
+    /**
+     * Plan #15 — schema rendered above the list-page table. Default `[]`.
+     * Typical use: dashboard widgets that contextualize the list (KPI cards,
+     * charts, status alerts). Anything Element-typed is allowed —
+     * `Group / Card / Section` for layout, `Stat / StatsOverview / Chart /
+     * TableWidget / View` for server-data widgets, `Heading / Alert` for
+     * static chrome. Resolves with the same `SchemaContext` passed to the
+     * list page's schema (carries `mode: 'table'`, `basePath`, `user`).
+     * Server-data widgets inside resolve in parallel via the shared
+     * `_widgetData` map and re-fetch through `POST {base}/{slug}/_widget/:id`.
+     * The hook only fires after `Resource.canAccess(user)` passes (route-level
+     * gate) — there's no extra per-hook authorization.
+     */
+    static headerSchema(_ctx) { return []; }
+    /**
+     * Plan #15 — schema rendered below the list-page table. Default `[]`.
+     * Same shape and posture as `headerSchema()`; useful for footnotes,
+     * legends, or "longest-running…" tables that contextualize the list
+     * from below.
+     */
+    static footerSchema(_ctx) { return []; }
+    /**
+     * Delete a record by id. Falls through to `model.delete(id)` when
+     * `static model` is set; otherwise throws so the user knows to wire
+     * something up. Override on the subclass for custom delete logic.
+     * Wired up by the `POST {base}/{slug}/{id}/delete` route.
+     */
+    static async deleteRecord(id) {
+        if (this.model) {
+            await this.model.delete(id);
+            return;
+        }
+        throw new Error(`[Pilotiq] ${this.name}: no deleteRecord(id) implementation. Set Resource.model = … or override Resource.deleteRecord to wire up deletion.`);
+    }
+    /**
+     * User-overridable page map. Return any subset of `{ index, create, edit, view }`
+     * to override the auto-generated defaults; missing keys fall through to
+     * defaults via `resolvePages()`.
+     */
+    static pages() { return {}; }
+    /**
+     * Resolved page map: defaults from `defaultPages(this)` overlaid with whatever
+     * `pages()` returns. This is what routing consumes (wired in 2.3).
+     */
+    static resolvePages() {
+        const defaults = defaultPages(this);
+        const overrides = this.pages();
+        return { ...defaults, ...overrides };
+    }
+    /**
+     * Plan #11 — relation managers mounted under this resource's edit /
+     * view pages. Each entry is a `RelationManager` subclass; routes are
+     * registered under `${base}/${slug}/:id/${manager.relationship}`.
+     * Default empty.
+     */
+    static relations() { return []; }
+    /** URL slug, derived from `label` when not set explicitly. */
+    static getSlug() {
+        return this.slug || this.label.toLowerCase().replace(/\s+/g, '-');
+    }
+    /** Sidebar label: `navigationLabel` override falls through to `label`. */
+    static getNavigationLabel() {
+        return this.navigationLabel ?? this.label;
+    }
+    /** Breadcrumb label: `breadcrumb` override falls through to `label`. */
+    static getBreadcrumb() {
+        return this.breadcrumb ?? this.label;
+    }
+    /** Sidebar icon: `navigationIcon` override falls through to `icon`. */
+    static getNavigationIcon() {
+        return this.navigationIcon ?? this.icon;
+    }
+}
+//# sourceMappingURL=Resource.js.map