@navette-js/panels 1.0.0-beta.3 → 1.0.0-beta.4

package/lib/index.d.ts

@@ -5,6 +5,10 @@ import { Action } from '@navette-js/actions';
 import { Step, Wizard } from '@navette-js/forms';
 import { Component as SchemaComponent, Schema, type SchemaHost } from '@navette-js/schemas';
 export { Notification, Notifications } from './notifications.ts';
+export { MemorySessionStore, type SessionStore } from './session-store.ts';
+export { csvCell, csvLine, DownloadStore, ExportAction, ExportBulkAction, ExportColumn, Exporter, ImportAction, ImportColumn, Importer, parseCsv, type ExportActionInstance, type ImportActionInstance } from './import-export.ts';
+import { DownloadStore } from './import-export.ts';
+import { type SessionStore } from './session-store.ts';
 import { type CalendarEvent, type CalendarLabels, type CalendarView } from './calendar.ts';
 export { addDays, addMonths, CALENDAR_LABELS, dayOf, daysBetween, eventsOn, renderCalendar, renderCalendarEvent, timeOf, visibleRange, type CalendarEvent, type CalendarLabels, type CalendarModel, type CalendarView } from './calendar.ts';
 import { type DatabaseNotificationStore, type GlobalSearchCategory, type GlobalSearchResult } from './topbar.ts';
@@ -71,6 +75,8 @@ export interface AuthProvider {
     markEmailAsVerified?(user: User): MaybePromise<void>;
     /** A value that changes with the stored password, so a used reset link becomes invalid. */
     getPasswordFingerprint?(user: User): MaybePromise<string>;
+    /** Can this user use this panel? Checked on every request and at login (`false`: 403, or "credentials do not match" at login). */
+    canAccessPanel?(user: User, panel: Panel): MaybePromise<boolean>;
 }
 /**
  * Panel tenants (teams, organizations…). Every panel page then lives under
@@ -97,7 +103,8 @@ export type PanelContext = {
     panel: Panel;
     user: User | null;
     mailbox: string;
-    tenant?: unknown;
+    tenant?: unknown; /** Signed in through the shared session, but not allowed into this panel. */
+    denied?: boolean;
 };
 /**
  * Predefined panel theme: a set of colors (palettes or plain colors), optionally a font and some CSS.
@@ -114,6 +121,19 @@ export type Theme = {
     /** CSS added to the page for this theme (written by the panel developer, inserted as-is). */
     css?: string;
 };
+/** Navigation group: label, icon (then its items have none, as in Filament) and whether it can be collapsed. */
+export declare class NavigationGroup {
+    private _label;
+    private _icon;
+    private _collapsible;
+    constructor(label: string);
+    static make(label: string): NavigationGroup;
+    icon(name: string | null): this;
+    collapsible(condition?: boolean): this;
+    getLabel(): string;
+    getIcon(): string | null;
+    isCollapsible(): boolean;
+}
 export declare class NavigationItem {
     label: string;
     _url: string;
@@ -149,10 +169,20 @@ export declare class Panel {
     private _login;
     private _auth;
     private _key;
+    private _sessionStore;
+    /** Where per-browser data is kept (persisted table filters, search and sort): in memory by default. */
+    sessionStore(store: SessionStore): this;
+    getSessionStore(): SessionStore;
+    private _downloads;
+    /** Where files offered for download (exports, failed import rows) are kept: in memory by default. */
+    downloads(store: DownloadStore): this;
+    getDownloads(): DownloadStore;
+    getDownloadUrl(token: string): string;
     private _pages;
     private _resources;
     private _navigationItems;
     private _navigationGroups;
+    private _navigationGroupOptions;
     private _maxContentWidth;
     readonly colors: ColorManager;
     static make(): Panel;
@@ -191,12 +221,38 @@ export declare class Panel {
     login(page?: typeof Login): this;
     auth(provider: AuthProvider): this;
     key(key: string): this;
+    private _authGuard;
+    private _canAccess;
+    /**
+     * Session shared with the other panels that use the same guard (`'web'` by default): signing into one signs into all of
+     * them, and `canAccess()` decides who may enter each one. `null` gives this panel a session of its own.
+     * Panels sharing a guard must use the same key and the same auth provider.
+     */
+    authGuard(guard: string | null): this;
+    getAuthGuard(): string | null;
+    /** Who may use this panel, e.g. `panel.canAccess((user) => user.role === 'admin')`. Checked on every request and at login. */
+    canAccess(rule: ((user: User, panel: Panel) => MaybePromise<boolean>) | null): this;
+    /** True if this user may use this panel: the panel's rule and the provider's `canAccessPanel()`, when set, must both allow it. */
+    userCanAccess(user: User): Promise<boolean>;
+    /** Name of the session cookie: per guard (shared), or per panel. */
+    getSessionCookieName(): string;
     pages(pages: (typeof Page)[]): this;
     /** Registers resources: their pages and navigation items. */
     resources(resources: (typeof Resource)[]): this;
     navigationItems(items: NavigationItem[]): this;
     /** Order of navigation groups. */
-    navigationGroups(groups: string[]): this;
+    /** Order of the navigation groups: labels, or `NavigationGroup.make('Shop').icon('o-shopping-cart').collapsible(false)`. */
+    private _darkMode;
+    private _darkModeForced;
+    private _defaultThemeMode;
+    /** `false`: light mode only (no switcher); `darkMode(true, true)`: dark mode only. */
+    darkMode(condition?: boolean, isForced?: boolean): this;
+    /** Mode used until the user picks one in the switcher: `'system'` (default), `'light'` or `'dark'`. */
+    defaultThemeMode(mode: 'light' | 'dark' | 'system'): this;
+    hasDarkMode(): boolean;
+    hasDarkModeForced(): boolean;
+    getDefaultThemeMode(): 'light' | 'dark' | 'system';
+    navigationGroups(groups: (string | NavigationGroup)[]): this;
     private _plugins;
     /** Applies a plugin: an object that configures the panel (resources, pages, render hooks, themes…). */
     plugin(plugin: Plugin): this;
@@ -324,6 +380,25 @@ export declare class Panel {
     mailer(mailer: Mailer): this;
     sendMail(message: MailMessage): Promise<void>;
     getAuthKey(): string;
+    private _authSlugs;
+    private authSlug;
+    /** URL segment of the login page (`login` by default). */
+    loginRouteSlug(slug: string): this;
+    /** URL segment of the registration page (`register` by default). */
+    registrationRouteSlug(slug: string): this;
+    /** URL segments of the password reset pages: `<prefix>/<request>` and `<prefix>/<reset>` (`password-reset/request` and `password-reset/reset` by default). */
+    passwordResetRoutePrefix(prefix: string): this;
+    passwordResetRequestRouteSlug(slug: string): this;
+    passwordResetRouteSlug(slug: string): this;
+    /** Paths of the authentication pages, relative to the panel. */
+    getAuthPaths(): {
+        login: string;
+        registration: string;
+        passwordResetRequest: string;
+        passwordReset: string;
+    };
+    /** First URL segments used by the panel itself (never page slugs or tenant keys). */
+    getReservedSegments(): Set<string>;
     getRegistrationUrl(): string;
     getRequestPasswordResetUrl(): string;
     getResetPasswordUrl(user: User, fingerprint: string): string;
@@ -584,6 +659,8 @@ export declare class Page extends BasePage {
         context: Record<string, unknown>;
         data?: Record<string, unknown>;
     }[];
+    /** Files uploaded by rich editors (`componentFileAttachments.<state path>.<id>`), stored by the editor when it asks for their URL. */
+    componentFileAttachments: Record<string, unknown>;
     getActionMountContext(): Record<string, unknown>;
     protected getActionRecord(): unknown;
     /** Record targeted by an action mounted in a given context (table row…). */
@@ -594,6 +671,8 @@ export declare class Page extends BasePage {
      * Actions owned by a schema component (Repeater: add, delete, move; Section: header actions).
      * The key comes from the browser: it must match a real component of the schema, or the schema itself.
      */
+    /** Visible component of a schema of this page (or of a mounted action's form) with this key. */
+    protected findSchemaComponent(key: string): Promise<any | null>;
     protected getSchemaComponentActions(key: string): Promise<Action[]>;
     /** Context kept for a mounted action: the server's, never the browser's as-is. */
     protected resolveMountContext(clientContext: unknown): Record<string, unknown>;
@@ -632,6 +711,7 @@ export declare class Dashboard extends Page {
     /** Filters form state. Stays `null` while the page has no filters. */
     filters: Record<string, unknown> | null;
     /** Dashboard widgets. Defaults to the panel's (`panel.widgets([...])`). */
+    /** The panel's widgets, ordered by their `sort` (stable). */
     getWidgets(): (typeof Widget)[];
     /** Grid columns: a number (at the `lg` breakpoint), or one number per breakpoint. */
     getColumns(): number | Record<string, number>;
@@ -837,6 +917,10 @@ export declare abstract class Resource {
     /** Columns searched by global search; defaults to the title attribute. Empty array: the resource is not searchable. */
     static globallySearchableAttributes: string[] | null;
     static getGloballySearchableAttributes(): string[];
+    /** `false`: the resource is left out of global search. */
+    static isGloballySearchable: boolean;
+    /** `false`: the search term is matched as a whole instead of word by word. */
+    static shouldSplitGlobalSearchTerms: boolean;
     static canGloballySearch(): boolean;
     /** Position of this resource's group in the results; without one, after the others in registration order. */
     static globalSearchSort: number | null;
@@ -863,19 +947,21 @@ export type SubNavigationItem = {
     url: string;
     active: boolean;
 };
-type ColumnSpan = number | 'full';
+type ColumnSpan = number | 'full' | Record<string, number | 'full'>;
 /** Widget: a component displayed in a page's widget grid. */
 export declare abstract class Widget extends Component {
     static componentName: string;
-    /** Width in the widget grid: a number of columns, or `'full'`. */
+    /** Width in the widget grid: a number of columns or `'full'` (from `lg`), or a span per breakpoint (`{ md: 2, xl: 3 }`). */
     static columnSpan: ColumnSpan;
+    /** Position on the dashboard (lower first); widgets without a sort keep their order, after the sorted ones. */
+    static sort: number | null;
     /** Loaded when it becomes visible. */
     static isLazy: boolean;
     get panel(): Panel;
     /** Restricts the widget to some users: returning `false` removes it from the page and refuses to load it. */
     static canView(_user: User): boolean | Promise<boolean>;
     boot(): Promise<void>;
-    /** Grid column classes and style, at the `lg` breakpoint. */
+    /** Grid column classes and style: at the `lg` breakpoint, or per breakpoint. */
     protected gridColumn(): {
         classes: string[];
         style: string;
@@ -1086,6 +1172,10 @@ export declare abstract class StatsOverviewWidget extends Widget {
     /** Polling interval, or `null` to disable polling. */
     static pollingInterval: string | null;
     abstract getStats(): Stat[] | Promise<Stat[]>;
+    /** Heading shown above the stats. */
+    protected getHeading(): string | null;
+    /** Description under the heading. */
+    protected getDescription(): string | null;
     /** Row columns: three, or four when the number of stats fits better. */
     protected getColumns(count: number): number;
     render(): Promise<string>;
@@ -1102,6 +1192,10 @@ export type ChartData = {
  * has changed (checksum).
  */
 export declare abstract class ChartWidget extends Widget {
+    /** Empty state shown when `getData()` returns nothing. */
+    protected getEmptyStateHeading(): string;
+    protected getEmptyStateDescription(): string | null;
+    protected getEmptyStateIcon(): string | null;
     static callable: string[];
     static locked: string[];
     /** Polling interval, or `null` to disable polling. */
@@ -1222,6 +1316,13 @@ export declare class Tab {
     badge(resolver: () => number | string | null | Promise<number | string | null>): this;
     badgeColor(color: string): this;
     query(modifier: (query: any) => void): this;
+    private _icon;
+    private _iconPosition;
+    /** Icon of the tab, before its label (or after, with `iconPosition('after')`). */
+    icon(name: string | null): this;
+    iconPosition(position: 'before' | 'after'): this;
+    getIcon(): string | null;
+    getIconPosition(): 'before' | 'after';
     getLabel(key: string): string;
     hasBadge(): boolean;
     getBadge(): Promise<number | string | null>;
@@ -1253,16 +1354,29 @@ export declare class ListRecords extends Page implements TableHost {
     toggleTableReordering(): Promise<void>;
     /** Saves the new order: only keys belonging to the table are kept, each gets its position. */
     reorderTable(order: unknown, _draggedRecordKey?: unknown): Promise<void>;
+    /** Key of this table's persisted state: per page class (and resource or relationship). */
+    protected tableSessionKey(part: string): string;
+    /** Session of the persisted table state: the browser (its CSRF token) and the signed-in user. */
+    private tableSession;
+    dehydrate(): Promise<void>;
+    /** Restores the persisted table state; every value is sanitized like browser input. */
+    private restoreTableSession;
     mount(_params?: Record<string, unknown>): Promise<void>;
     /** Filters form: one group per filter, bound to `tableDeferredFilters.<filter>`. */
     tableFiltersFormSchema(schema: Schema): Schema;
+    /** Applied state of every declared filter, sanitized from the given (browser) state. */
+    protected sanitizeTableFilters(source: Record<string, unknown> | undefined): Record<string, FilterState>;
+    /** Live filters (`deferFilters(false)`): a changed field applies at once. */
+    updatedTableFilters(value: unknown, key: string | null): Promise<void>;
     applyTableFilters(): void;
     /** Removes an active filter indicator: the field is cleared from both the applied state and the form. */
-    removeTableFilter(filterName: unknown, field?: unknown): void;
+    removeTableFilter(filterName: unknown, field?: unknown): Promise<void>;
     /** Live field in the filters form (e.g. a rule's operator changed): runs its `afterStateUpdated`. */
     updatedTableDeferredFilters(_value: unknown, key: string | null): Promise<void>;
+    private runFilterFieldHook;
     resetTableFiltersForm(): void;
-    removeTableFilters(): void;
+    /** "Remove all": resets every removable filter (to its empty state, not its default), the search and the column searches. */
+    removeTableFilters(): Promise<void>;
     applyTableColumnManager(state?: unknown, _wasReordered?: unknown): void;
     resetTableColumnManager(): void;
     activeTab: string | null;
@@ -1292,10 +1406,23 @@ export declare class ListRecords extends Page implements TableHost {
     updateTableColumnState(columnName: unknown, recordKey: unknown, input: unknown): Promise<unknown>;
     /** Selected keys: the sent list, or, in "select all" mode, every record of the current query except deselected ones. */
     getSelectedRecordKeys(): Promise<string[]>;
+    /**
+     * Runs `process` for each selected record, loaded in chunks of `chunkSelectedRecords()`. Records failing the action's
+     * `authorizeIndividualRecords()` are skipped; `process` reports a failure by returning `false` or throwing. Then sends the
+     * action's success notification, or its failure notification with the number of records skipped and failed.
+     */
+    processSelectedRecords(action: Action, process: (record: any) => unknown | Promise<unknown>): Promise<{
+        total: number;
+        success: number;
+        unauthorized: number;
+        failed: number;
+    }>;
     deselectAllTableRecords(): void;
     getTable(): Table;
     renderTable(): Promise<string>;
+    protected renderTableEmptyStateActions(ctx: any): Promise<string[]>;
     /** Table header actions (none on a list page: they go in the page header). */
+    protected renderTableToolbarActions(ctx: any): Promise<string[]>;
     protected renderTableHeaderActions(ctx: any): Promise<string[]>;
     sortTable(column?: string | null, direction?: string | null): void;
     gotoPage(page: number, _pageName?: string): void;
@@ -1347,6 +1474,14 @@ export declare class RelationManager extends ListRecords {
     static searchAttachable(_ownerKey: string, _search: string): Promise<[string, string][]>;
     /** Label of an attachable record, or `null` if it is not attachable (also used as validation). */
     static attachableLabel(_ownerKey: string, _recordKey: string): Promise<string | null>;
+    /** Sets the owner of an existing record (its foreign key). */
+    static associate(_ownerKey: string, _recordKey: string): Promise<void>;
+    /** Clears the owner of records (their foreign key), without deleting them. */
+    static dissociate(_ownerKey: string, _recordKeys: string[]): Promise<void>;
+    /** Associable records matching the search: [key, label]. */
+    static searchAssociable(_ownerKey: string, _search: string): Promise<[string, string][]>;
+    /** Label of an associable record, or `null` if it is not associable (also used as validation). */
+    static associableLabel(_ownerKey: string, _recordKey: string): Promise<string | null>;
     getHeaderActions(): Action[];
     placeholder(): string;
     /** A relation manager has its own render hook locations, not the list page's. */
@@ -1425,13 +1560,21 @@ declare abstract class ResourceFormPage extends Page {
     /** Where "Cancel" goes when the browser has no history: the list page, unless the page decides otherwise. */
     protected getCancelUrl(): string;
     protected cancelAction(): Action;
+    /** Before the form is filled (with defaults, or with the record on the edit page). */
+    protected beforeFill(): void | Promise<void>;
+    /** After the form is filled. */
+    protected afterFill(): void | Promise<void>;
+    /** Before the form is validated, when it is submitted. */
+    protected beforeValidate(): void | Promise<void>;
+    /** After the form is validated successfully, before the data is transformed and saved. */
+    protected afterValidate(): void | Promise<void>;
     /** Validates the form; on error, sets the errors on the component and notifies the browser. */
     protected validateForm(): Promise<boolean>;
 }
 /** Record creation page. */
 export declare class CreateRecord extends ResourceFormPage {
     static callable: string[];
-    mount(): void;
+    mount(): Promise<void>;
     getOperation(): 'create';
     getSubmitMethod(): string;
     getTitle(): string;
@@ -1461,9 +1604,21 @@ export declare class DeleteAction {
     /** On an edit page, deletes the page's record and returns to the list. On a table row, deletes the row. */
     static make(): Action;
 }
-/** Replicate action: an `Action` with a list of attributes not to copy. */
+/** Replicate action: an `Action` with a list of attributes not to copy, and hooks around the saving of the copy. */
 export type ReplicateActionInstance = Action & {
     excludeAttributes(attributes: string[]): ReplicateActionInstance;
+    /** Runs before the copy is saved, with its attributes (`replica`, changeable) and the modal form's data. */
+    beforeReplicaSaved(callback: (ctx: {
+        replica: Record<string, unknown>;
+        data: Record<string, unknown>;
+        record: unknown;
+    }) => unknown): ReplicateActionInstance;
+    /** Runs after the copy is saved, with the saved record. */
+    afterReplicaSaved(callback: (ctx: {
+        replica: unknown;
+        data: Record<string, unknown>;
+        record: unknown;
+    }) => unknown): ReplicateActionInstance;
 };
 /** Duplicates a table row: the copy takes the record's attributes, except its key, timestamps and excluded ones. */
 export declare class ReplicateAction {
@@ -1495,6 +1650,18 @@ export declare class DetachAction {
 export declare class DetachBulkAction {
     static make(): Action;
 }
+/** Gives an existing record to the owner of a one-to-many relation manager (its foreign key). */
+export declare class AssociateAction {
+    static make(): Action;
+}
+/** Removes a row from the owner (clears its foreign key) without deleting it. */
+export declare class DissociateAction {
+    static make(): Action;
+}
+/** Dissociates the selected rows. */
+export declare class DissociateBulkAction {
+    static make(): Action;
+}
 /** Restores a soft-deleted record. Only visible when the record is deleted. */
 export declare class RestoreAction {
     static make(): Action;
@@ -1503,10 +1670,21 @@ export declare class RestoreAction {
 export declare class ForceDeleteAction {
     static make(): Action;
 }
-/** Deletes the records selected in a table. */
+/**
+ * Deletes the records selected in a table. Without `authorizeIndividualRecords()`, the selection is deleted in one query;
+ * with it, record by record, and the notification reports the records that could not be deleted.
+ */
 export declare class DeleteBulkAction {
     static make(): Action;
 }
+/** Restores the soft-deleted records selected in a table, each one checked with the `restore` ability. */
+export declare class RestoreBulkAction {
+    static make(): Action;
+}
+/** Permanently deletes the soft-deleted records selected in a table, each one checked with the `forceDelete` ability. */
+export declare class ForceDeleteBulkAction {
+    static make(): Action;
+}
 /** Record edit page. */
 export declare class EditRecord extends ResourceFormPage {
     static callable: string[];
@@ -1620,5 +1798,4 @@ export declare const discoverPages: (directory: string | URL) => Promise<(typeof
 export declare const discoverWidgets: (directory: string | URL) => Promise<(typeof Widget)[]>;
 /** Panels default-exported (`export default Panel.make()…`) by a folder's modules. */
 export declare function discoverPanels(directory: string | URL): Promise<Panel[]>;
-/** Express router for a panel: assets, runtime endpoint, authentication, tenants, protected pages. */
 export declare function panelRouter(panel: Panel, runtime: WireRuntime): Router;