better-supabase 0.13.0 → 0.14.0

package/dist/client-BIMg9IiF.d.ts

@@ -0,0 +1,349 @@
+/// <reference lib="esnext.temporal" />
+import { D as ValidationIssue, T as ErrorMapper, b as DbError, f as Result, t as AsyncResult } from "./result-C6jDfedy.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { r as BlockTemporalOptions } from "./block-helpers-BaugZlJV.js";
+import { t as BlockTransport } from "./block-transport-d53POsem.js";
+import { n as BlockHooks } from "./block-hooks-CmjPKqQ_.js";
+import { d as FilterLimits, h as FilterQuery, i as FilterCombinator, r as FilterClock } from "./filter-query-o3b_GuyC.js";
+import { n as Controller, t as AuthPort } from "./controller-DAD4hbl4.js";
+import { n as RuleField, r as RuleFieldCatalog } from "./fields-CanaxA0U.js";
+import { n as FilterRecordField, t as FilterEvaluation } from "./filter-evaluate-C3i2bGfk.js";
+//#region src/blocks/rules/rules.d.ts
+/** What a rule runs when it matches: a kind the app handles and its settings. */
+interface RuleAction {
+  /** Such as `approvals.request` or `notifications.send`. */
+  readonly kind: string;
+  readonly config?: Readonly<Record<string, unknown>>;
+}
+interface Rule {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly subjectType: string;
+  /** The event type the rule is tested on, such as `expense.submitted`. */
+  readonly trigger: string;
+  readonly name: string;
+  readonly description: string | undefined;
+  readonly conditions: FilterQuery;
+  readonly actions: readonly RuleAction[];
+  readonly enabled: boolean;
+  /** A match ends the evaluation, so later rules for the trigger don't run. */
+  readonly stopProcessing: boolean;
+  /** The rank key rules are tested in. */
+  readonly rank: string;
+  readonly version: number;
+  readonly createdBy: string | undefined;
+  readonly updatedBy: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+/** `save`'s input: left-out keys keep their value on an existing rule. */
+interface RuleInput {
+  readonly id?: string;
+  /** The version the editor read; a newer stored one fails with `RULE_CONFLICT`. */
+  readonly version?: number;
+  /** Required for a new rule; it can't change later. */
+  readonly subjectType?: string;
+  readonly trigger?: string;
+  readonly name?: string;
+  readonly description?: string | null;
+  readonly conditions?: FilterQuery;
+  readonly actions?: readonly RuleAction[];
+  /** Turning a rule on takes `rules.publish`. */
+  readonly enabled?: boolean;
+  readonly stopProcessing?: boolean;
+}
+interface RuleVersion {
+  readonly ruleId: string;
+  readonly version: number;
+  readonly name: string;
+  readonly conditions: FilterQuery;
+  readonly actions: readonly RuleAction[];
+  readonly savedBy: string | undefined;
+  readonly savedAt: Temporal.Instant;
+}
+/** A rule that matched, with the truth of every condition and group by node id. */
+interface RuleMatch {
+  readonly rule: Rule;
+  readonly results: Readonly<Record<string, boolean | null>>;
+}
+/** One entry of a rule's evaluation log. */
+interface RuleEvaluationEntry {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly ruleId: string;
+  readonly version: number;
+  readonly subjectType: string;
+  readonly subjectId: string | undefined;
+  readonly trigger: string;
+  readonly matched: boolean;
+  readonly results: Readonly<Record<string, boolean | null>>;
+  readonly mode: "live" | "test";
+  readonly evaluatedBy: string | undefined;
+  readonly evaluatedAt: Temporal.Instant;
+}
+interface RuleListOptions {
+  readonly subjectType?: string;
+  readonly trigger?: string;
+  readonly enabled?: boolean;
+}
+/** What `matching` and `run` test: one subject, as the trigger event saw it. */
+interface RuleSubject {
+  readonly subjectType: string;
+  readonly trigger: string;
+  /**
+   * The record the field catalog's columns read, such as the expense row with
+   * its submitter.
+   */
+  readonly subject: Readonly<Record<string, unknown>>;
+  /** The IANA zone relative dates ("today") resolve in. Default `UTC`. */
+  readonly timeZone?: string;
+}
+interface RulesOptions extends BlockTemporalOptions {
+  /** The caller's transport (`rpcTransport(supabase)`). */
+  readonly transport: BlockTransport;
+  /** The module schema, or its API schema. Default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: BlockHooks<Rules>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+interface Rules {
+  /** The field catalog, for one subject type or all of them. */
+  fields(subjectType?: string): AsyncResult<readonly RuleField[]>;
+  /** The organization's rules in evaluation order (needs `rules.read`). */
+  list(organizationId: string, options?: RuleListOptions): AsyncResult<readonly Rule[]>;
+  /** `undefined` when the caller can't read a rule with this id. */
+  get(id: string): AsyncResult<Rule | undefined>;
+  /**
+   * Creates or changes a rule. `rules.edit` covers disabled rules; enabling a
+   * rule or changing an enabled one takes `rules.publish`.
+   */
+  save(organizationId: string, input: RuleInput): AsyncResult<Rule>;
+  /** Turns a rule on or off (needs `rules.publish`). */
+  setEnabled(id: string, enabled: boolean): AsyncResult<Rule>;
+  /** Moves a rule to a rank key from `rankBetween` over its neighbours. */
+  move(id: string, rank: string): AsyncResult<Rule>;
+  /**
+   * Removes a rule with its history (needs `rules.admin`); `false` when there
+   * is none to remove.
+   */
+  remove(id: string): AsyncResult<boolean>;
+  /** Saved versions, newest first. */
+  versions(id: string): AsyncResult<readonly RuleVersion[]>;
+  /** The evaluation log, newest first. */
+  evaluations(id: string, options?: {
+    readonly before?: Temporal.Instant;
+    readonly pageSize?: number;
+  }): AsyncResult<readonly RuleEvaluationEntry[]>;
+  /** The enabled rules for the trigger that match, evaluated in the database. */
+  matching(organizationId: string, input: RuleSubject): AsyncResult<readonly RuleMatch[]>;
+  /**
+   * Runs a rule's stored conditions on a sample record and logs it as a test
+   * (needs `rules.edit`). Nothing runs; the result says what would match.
+   */
+  test(rule: Rule, subject: Readonly<Record<string, unknown>>, options?: {
+    readonly fields?: readonly RuleField[];
+    readonly subjectId?: string;
+    readonly clock?: FilterClock;
+  }): AsyncResult<FilterEvaluation>;
+}
+/** A rule row from the module's functions. */
+declare function ruleOf(value: unknown): Rule;
+/** Catalog fields in the shape `evaluateFilterQuery` reads. */
+declare function ruleRecordFields(fields: readonly RuleField[]): readonly FilterRecordField[];
+/**
+ * Tests a rule's conditions on one record in memory, the same way the
+ * database's `rule_evaluate` does. `fields` is the subject type's catalog.
+ */
+declare function evaluateRule(rule: Pick<Rule, "conditions">, subject: unknown, fields: readonly RuleField[], clock?: FilterClock): FilterEvaluation;
+/** Tenant rules as the caller: the catalog, the rules, their history and tests. */
+declare function createRules(options: RulesOptions): Rules;
+interface RulesAdminOptions extends BlockTemporalOptions {
+  /**
+   * A service-role transport: `sync_rule_fields` and `run_rules` are granted to
+   * `service_role` only.
+   */
+  readonly transport: BlockTransport;
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+interface RulesAdmin {
+  /** Replaces the subject type's field catalog; returns how many fields it has. */
+  syncFields(catalog: RuleFieldCatalog): AsyncResult<number>;
+  /**
+   * Evaluates the enabled rules for the trigger, logs each one live and returns
+   * the matches.
+   */
+  run(organizationId: string, input: RuleSubject & {
+    readonly subjectId?: string;
+  }): AsyncResult<readonly RuleMatch[]>;
+}
+/** The field sync and live evaluation, with a service-role client. */
+declare function createRulesAdmin(options: RulesAdminOptions): RulesAdmin;
+/**
+ * What a handler receives: the action, the rule it belongs to and the dispatch
+ * context.
+ */
+interface RuleActionCall<C = unknown> {
+  readonly action: RuleAction;
+  readonly rule: Rule;
+  readonly results: Readonly<Record<string, boolean | null>>;
+  readonly context: C;
+}
+/**
+ * Runs one action kind. Return a `Result`; a throw becomes an `unexpected`
+ * error.
+ */
+type RuleActionHandler<C = unknown> = (call: RuleActionCall<C>) => Result<unknown> | PromiseLike<Result<unknown>>;
+/** The outcome of one action: its value, or the error its handler returned. */
+type RuleActionOutcome = {
+  readonly ruleId: string;
+  readonly kind: string;
+  readonly ok: true;
+  readonly value: unknown;
+} | {
+  readonly ruleId: string;
+  readonly kind: string;
+  readonly ok: false;
+  readonly error: DbError;
+};
+interface RuleDispatcherOptions<C> {
+  /** A handler per action kind, such as `approvals.request`. */
+  readonly handlers: Readonly<Record<string, RuleActionHandler<C>>>;
+}
+interface RuleDispatcher<C = unknown> {
+  /**
+   * Runs the actions of `matches` in order. A failed action doesn't stop the
+   * others; each one's outcome comes back. A kind without a handler is an
+   * `invalid_request` outcome with the hint `RULE_ACTION_UNKNOWN`.
+   */
+  dispatch(matches: readonly RuleMatch[], context: C): AsyncResult<readonly RuleActionOutcome[]>;
+}
+/** Runs matched rules' actions with the app's handlers. */
+declare function createRuleDispatcher<C = unknown>(options: RuleDispatcherOptions<C>): RuleDispatcher<C>;
+/** An outbox event as the rule sink reads it; an `OutboxEvent` fits. */
+interface RuleSinkEvent {
+  readonly id: string;
+  readonly type: string;
+  readonly payload?: unknown;
+  readonly tenant?: string | null;
+}
+/**
+ * What `load` returns for an event the rules should see: the subject and the
+ * dispatch context.
+ */
+interface RuleSinkTarget<C> {
+  readonly organizationId: string;
+  readonly subjectType: string;
+  readonly subjectId?: string;
+  /** The record the field catalog's columns read. */
+  readonly subject: Readonly<Record<string, unknown>>;
+  readonly timeZone?: string;
+  readonly context: C;
+}
+interface RuleSinkOptions<C> {
+  /** `rules.run` from `createRulesAdmin`, which logs each evaluation live. */
+  readonly rules: Pick<RulesAdmin, "run">;
+  readonly dispatcher: RuleDispatcher<C>;
+  /**
+   * Reads the subject an event is about, such as the app table row named by
+   * `payload.id`. `undefined` skips the event.
+   */
+  readonly load: (event: RuleSinkEvent) => RuleSinkTarget<C> | undefined | PromiseLike<RuleSinkTarget<C> | undefined>;
+  /** Receives each event's action outcomes, failed ones included. */
+  readonly onOutcomes?: (event: RuleSinkEvent, outcomes: readonly RuleActionOutcome[]) => void;
+}
+/**
+ * An outbox consumer handler that tests the rules whose trigger is the event's
+ * type and runs the actions of the ones that match, for
+ * `outbox.consume("rules", createRuleSink(...))`. It throws when the evaluation
+ * fails, so the outbox retries the event; a failed action goes to `onOutcomes`
+ * instead, since a retry would run the others again.
+ */
+declare function createRuleSink<C = unknown>(options: RuleSinkOptions<C>): (events: readonly RuleSinkEvent[]) => Promise<void>;
+//#endregion
+//#region src/blocks/rules/client.d.ts
+interface RuleBuilderControllerOptions {
+  readonly client: Pick<Rules, "fields" | "get" | "save">;
+  readonly auth: AuthPort;
+  readonly organizationId: string;
+  /** The rule to edit; `null` edits a new one. */
+  readonly rule: string | null;
+  /** The record type whose fields the rules test. */
+  readonly subjectType: string;
+  /** A new rule's trigger, such as `expense.submitted`. */
+  readonly trigger?: string;
+  /** The tree a new rule starts with, such as a fixed first condition. */
+  readonly initial?: FilterQuery;
+  /**
+   * Node ids the editor may not change, move or remove, such as the fixed first
+   * condition. Only the editor knows them; the stored rule doesn't.
+   */
+  readonly locked?: readonly string[];
+  /** Defaults to `RULE_LIMITS`. */
+  readonly limits?: FilterLimits;
+  /** Makes node ids. Defaults to `crypto.randomUUID()`. */
+  readonly newId?: () => string;
+}
+interface RuleBuilderSnapshot {
+  /** The stored rule; `undefined` for a new one or before the first load. */
+  readonly rule: Rule | undefined;
+  /** The subject type's field catalog; `undefined` until loaded. */
+  readonly fields: readonly RuleField[] | undefined;
+  readonly name: string;
+  readonly conditions: FilterQuery;
+  readonly actions: readonly RuleAction[];
+  readonly stopProcessing: boolean;
+  readonly locked: readonly string[];
+  /** Problems in the tree, checked against the fields once they load. */
+  readonly issues: readonly ValidationIssue[];
+  /**
+   * Whether the name, tree, actions or `stopProcessing` differ from the stored
+   * rule.
+   */
+  readonly dirty: boolean;
+  readonly loading: boolean;
+  readonly saving: boolean;
+  readonly error: DbError | undefined;
+}
+interface RuleBuilderActions {
+  /** Loads the fields and the rule again, dropping unsaved edits. */
+  readonly refresh: () => Promise<void>;
+  /** Adds a condition to `group` (the root by default) and returns its id. */
+  readonly addRule: (group?: string, field?: string) => string;
+  /** Adds an empty group to `group` (the root by default) and returns its id. */
+  readonly addGroup: (group?: string, combinator?: FilterCombinator) => string;
+  readonly remove: (id: string) => void;
+  /** Moves a node into `group`, where it ends up at `index`. */
+  readonly move: (id: string, group: string, index: number) => void;
+  readonly setField: (id: string, field: string) => void;
+  /** Keeps the value when the operator takes the same kind of value. */
+  readonly setOperator: (id: string, operator: string) => void;
+  readonly setValue: (id: string, value: unknown) => void;
+  readonly setNegated: (id: string, negated: boolean) => void;
+  readonly setCombinator: (group: string, combinator: FilterCombinator) => void;
+  readonly setName: (name: string) => void;
+  readonly setActions: (actions: readonly RuleAction[]) => void;
+  readonly setStopProcessing: (stop: boolean) => void;
+  readonly lock: (id: string) => void;
+  readonly unlock: (id: string) => void;
+  /** Drops unsaved edits. */
+  readonly reset: () => void;
+  /**
+   * Saves the rule, `enabled` turning it on or off with it. The saved rule, or
+   * `undefined` with `error` set.
+   */
+  readonly save: (options?: {
+    readonly enabled?: boolean;
+  }) => Promise<Rule | undefined>;
+}
+type RuleBuilderController = Controller<RuleBuilderSnapshot, RuleBuilderActions>;
+/**
+ * The editor state of one rule: the field catalog, the condition tree and the
+ * edits to it, with validation, dirty state and save.
+ */
+declare function createRuleBuilderController(options: RuleBuilderControllerOptions): RuleBuilderController;
+//#endregion
+export { evaluateRule as A, RulesAdmin as C, createRuleSink as D, createRuleDispatcher as E, ruleRecordFields as M, createRules as O, Rules as S, RulesOptions as T, RuleSinkEvent as _, createRuleBuilderController as a, RuleSubject as b, RuleActionCall as c, RuleDispatcher as d, RuleDispatcherOptions as f, RuleMatch as g, RuleListOptions as h, RuleBuilderSnapshot as i, ruleOf as j, createRulesAdmin as k, RuleActionHandler as l, RuleInput as m, RuleBuilderController as n, Rule as o, RuleEvaluationEntry as p, RuleBuilderControllerOptions as r, RuleAction as s, RuleBuilderActions as t, RuleActionOutcome as u, RuleSinkOptions as v, RulesAdminOptions as w, RuleVersion as x, RuleSinkTarget as y };

package/dist/client-BQseXods.d.ts

@@ -0,0 +1,309 @@
+import { D as ValidationIssue, T as ErrorMapper, t as AsyncResult } from "./result-C6jDfedy.js";
+import { t as StandardSchemaV1 } from "./standard-DbQsD2xZ.js";
+import { i as RowFields, r as FieldsOf } from "./block-fields-3w4MZr8U.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as BlockTransport } from "./block-transport-d53POsem.js";
+import { n as BlockHooks } from "./block-hooks-CmjPKqQ_.js";
+import { p as ListQueryInput } from "./list-query-BtluNnYk.js";
+import { n as Controller } from "./controller-DAD4hbl4.js";
+import { t as RankNeighbors } from "./rank-result-DwR0FawB.js";
+//#region src/blocks/saved-views/saved-views.d.ts
+declare const SAVED_VIEW_KINDS: readonly ["table", "board", "calendar", "timeline", "gantt"];
+type SavedViewKind = (typeof SAVED_VIEW_KINDS)[number];
+declare const SAVED_VIEW_SCOPES: readonly ["user", "team", "tenant"];
+type SavedViewScope = (typeof SAVED_VIEW_SCOPES)[number];
+declare const SAVED_VIEW_DENSITIES: readonly ["compact", "default", "comfortable"];
+type SavedViewDensity = (typeof SAVED_VIEW_DENSITIES)[number];
+/** Column layout, in the shape of TanStack Table's column state. */
+interface SavedViewColumns {
+  readonly visible?: readonly string[];
+  readonly order?: readonly string[];
+  readonly sizes?: Readonly<Record<string, number>>;
+  readonly pinned?: {
+    readonly left?: readonly string[];
+    readonly right?: readonly string[];
+  };
+}
+/** What a view stores. `query` is the list's typed input, without the page. */
+interface SavedViewState<Q extends ListQueryInput<string, string> = ListQueryInput<string, string>> {
+  readonly query?: Omit<Q, "page" | "after">;
+  readonly columns?: SavedViewColumns;
+  readonly grouping?: readonly string[];
+  readonly density?: SavedViewDensity;
+  /**
+   * Settings of the layout, such as a board's group column or a calendar's date
+   * field.
+   */
+  readonly layout?: Readonly<Record<string, unknown>>;
+  /**
+   * Keeps the view to the records of a collection
+   * (`better-supabase/blocks/collections`): pass `collections.where(id)` as the
+   * list's `where`.
+   */
+  readonly collectionId?: string;
+}
+/** The part of a view's state that lives outside the URL. */
+type SavedViewDisplayState = Omit<SavedViewState, "query">;
+/** The caller's own flags for a view, which need no right to change it. */
+interface SavedViewPreference {
+  /** Opens this view first, ahead of every slot default. */
+  readonly isDefault: boolean;
+  readonly hidden: boolean;
+  readonly pinned: boolean;
+}
+interface SavedViewPreferenceInput {
+  readonly isDefault?: boolean;
+  readonly hidden?: boolean;
+  readonly pinned?: boolean;
+}
+interface DuplicateViewInput {
+  readonly name?: string;
+  /** Default `user`. `team` and `tenant` need `views.share`. */
+  readonly scope?: SavedViewScope;
+  /** The team, for `scope: "team"`. */
+  readonly teamId?: string;
+}
+/**
+ * The part of a `defineListQuery` definition a saved view checks its query
+ * against. Any list definition fits.
+ */
+interface SavedViewList {
+  parse(input: object | undefined): {
+    readonly ok: boolean;
+    readonly issues?: readonly ValidationIssue[] | undefined;
+  };
+  readonly jsonSchema: Readonly<Record<string, unknown>>;
+}
+interface SavedView<Q extends ListQueryInput<string, string> = ListQueryInput<string, string>, F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly list: string;
+  readonly scope: SavedViewScope;
+  readonly ownerId: string | null;
+  readonly teamId: string | null;
+  readonly name: string;
+  readonly kind: SavedViewKind;
+  readonly state: SavedViewState<Q>;
+  readonly rank: string;
+  /** The default of its slot (the owner's, the team's or the tenant's). */
+  readonly isDefault: boolean;
+  /** The caller's own flags; all false without the preferences table. */
+  readonly preference: SavedViewPreference;
+  /** The app's extra columns (`options.extraColumns`), by column name. */
+  readonly fields: RowFields<F>;
+}
+/**
+ * What `save` and `duplicate` resolve to: the view's id, rank key and extra
+ * columns.
+ */
+interface SavedViewRef<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly rank: string;
+  /** The app's extra columns (`options.extraColumns`), by column name. */
+  readonly fields: RowFields<F>;
+}
+interface SaveViewInput<Q extends ListQueryInput<string, string> = ListQueryInput<string, string>, F extends object = Record<never, never>> {
+  readonly organizationId: string;
+  /** The list's key, such as `tasks`; also the key in `lists`. */
+  readonly list: string;
+  readonly name: string;
+  readonly state: SavedViewState<Q>;
+  /** Default `table`. */
+  readonly kind?: SavedViewKind;
+  /** Default `user`. `team` and `tenant` need `views.share`. */
+  readonly scope?: SavedViewScope;
+  /** The team, for `scope: "team"`. */
+  readonly teamId?: string;
+  /** Updates this view instead of adding one. */
+  readonly id?: string;
+  /**
+   * Values for the app's extra columns (`options.extraColumns`); left out keeps
+   * the stored ones.
+   */
+  readonly fields?: Partial<F> & Readonly<Record<string, unknown>>;
+}
+interface SavedViewsOptions<S extends StandardSchemaV1 | undefined = undefined> {
+  readonly transport: BlockTransport;
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /** List definitions by key; `save` checks a view's query against its list. */
+  readonly lists?: Readonly<Record<string, SavedViewList>>;
+  /**
+   * A Standard Schema for the extra columns of the saved views table
+   * (`blocks.saved-views.options.extraColumns`): writes are validated, reads
+   * parsed.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<SavedViews<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+interface SavedViews<F extends object = Record<never, never>> {
+  /** Adds a view, or updates `input.id`. Resolves to its id and rank key. */
+  save(input: SaveViewInput<ListQueryInput<string, string>, F>): AsyncResult<SavedViewRef<F>>;
+  /** The views the caller sees for a list, in rank order. */
+  list(organizationId: string, list: string): AsyncResult<SavedView<ListQueryInput<string, string>, F>[]>;
+  /** Moves a view between its neighbours' rank keys. Resolves to its new key. */
+  reorder(id: string, neighbors: RankNeighbors): AsyncResult<string>;
+  /**
+   * Makes a view the default of its slot (the user's, the team's or the
+   * tenant's).
+   */
+  setDefault(id: string, on?: boolean): AsyncResult<boolean>;
+  /**
+   * Sets the caller's own flags on a view they see. Omitted flags keep their
+   * value; one preferred default per user and list.
+   */
+  setPreference(id: string, preference: SavedViewPreferenceInput): AsyncResult<SavedViewPreference>;
+  /**
+   * Copies a view the caller sees as a new view. Resolves to its id and rank
+   * key.
+   */
+  duplicate(id: string, input?: DuplicateViewInput): AsyncResult<SavedViewRef<F>>;
+  delete(id: string): AsyncResult<boolean>;
+}
+/**
+ * Checks a view's state, and its `query` against `list` when given. An empty
+ * list means the state is valid.
+ */
+declare function savedViewIssues(state: unknown, list?: SavedViewList): readonly ValidationIssue[];
+/** The JSON Schema of a view's state, with `query` from the list's schema. */
+declare function savedViewStateSchema(list?: SavedViewList): Readonly<Record<string, unknown>>;
+declare function createSavedViews<S extends StandardSchemaV1 | undefined = undefined>(options: SavedViewsOptions<S>): SavedViews<FieldsOf<S>>;
+/** The fields of a view `defaultView` reads; `SavedView` fits. */
+interface DefaultViewCandidate {
+  readonly scope: SavedViewScope;
+  readonly isDefault: boolean;
+  readonly preference?: Partial<Pick<SavedViewPreference, "isDefault" | "hidden">>;
+}
+/**
+ * The view that opens first: the caller's preferred default, then the user's
+ * slot default, a team default, the tenant's, then the first view. Views the
+ * caller hid are skipped.
+ */
+declare function defaultView<V extends DefaultViewCandidate>(views: readonly V[]): V | undefined;
+//#endregion
+//#region src/blocks/saved-views/query-state.d.ts
+/**
+ * The URL state of a list as nuqs returns it from
+ * `useQueryStates(list.nuqs(createParser))`: one key per parser, `null` when
+ * the parameter is absent.
+ */
+type ListUrlState = Readonly<Record<string, unknown>>;
+/** A list's URL state as the typed query a view stores, without the page. */
+declare function queryFromUrlState(state: ListUrlState): ListQueryInput<string, string>;
+/**
+ * The URL state that opens a view's query: every key in `keys` (the current
+ * state's), `null` unless the query sets it, so applying a view clears what the
+ * previous one set. The page goes back to the first.
+ */
+declare function urlStateFromQuery(query: ListQueryInput<string, string> | undefined, keys: readonly string[]): Record<string, unknown>;
+/** A view's state without `query`: the part `onApplyState` shows. */
+declare function displayStateOf(state: SavedViewState): SavedViewDisplayState;
+/** Whether two states show the same columns, grouping, density and layout. */
+declare function sameDisplayState(a: SavedViewState | undefined, b: SavedViewState | undefined): boolean;
+/** Whether two stored queries select the same rows in the same order. */
+declare function sameQuery(a: ListQueryInput<string, string> | undefined, b: ListQueryInput<string, string> | undefined): boolean;
+//#endregion
+//#region src/blocks/saved-views/client.d.ts
+/** The fields of a saved view the controller reads; `SavedView` fits. */
+interface SavedViewLike extends DefaultViewCandidate {
+  readonly id: string;
+  readonly name: string;
+  readonly state: SavedViewState;
+}
+interface SavedViewsSyncOptions<V extends SavedViewLike> {
+  /**
+   * Loads the list's views, e.g. a server action that calls
+   * `savedViews.list()`.
+   */
+  readonly load: () => Promise<readonly V[]>;
+  /**
+   * The state the UI shows outside the URL: columns, grouping, density and
+   * layout. `saveCurrent` stores it with the query, and `active` and `isDirty`
+   * compare it. Without it only the query counts.
+   */
+  readonly getState?: () => SavedViewDisplayState;
+  /**
+   * Shows a view's state outside the URL; `apply` calls it with everything but
+   * `query`.
+   */
+  readonly onApplyState?: (state: SavedViewDisplayState, view: V) => void;
+  /**
+   * Saves the current state, e.g. a server action that calls
+   * `savedViews.save()`.
+   */
+  readonly save?: (input: {
+    readonly name: string;
+    readonly query: ListQueryInput<string, string>;
+    /** The query and `getState()` together, as `savedViews.save()` takes it. */
+    readonly state: SavedViewState;
+    readonly id?: string;
+  }) => Promise<unknown>;
+  readonly remove?: (id: string) => Promise<unknown>;
+  /** Copies a view, e.g. a server action that calls `savedViews.duplicate()`. */
+  readonly duplicate?: (input: {
+    readonly id: string;
+    readonly name: string;
+    readonly scope?: SavedViewScope;
+  }) => Promise<unknown>;
+  /**
+   * Sets the caller's flags, e.g. a server action that calls
+   * `savedViews.setPreference()`.
+   */
+  readonly setPreference?: (id: string, preference: SavedViewPreferenceInput) => Promise<unknown>;
+  /**
+   * Applies the default view after the first load when the URL holds no query.
+   * Default `true`.
+   */
+  readonly openDefault?: boolean;
+}
+interface SavedViewsControllerOptions<V extends SavedViewLike> extends SavedViewsSyncOptions<V> {
+  /**
+   * The list's URL state now, e.g. from nuqs
+   * `useQueryStates(list.nuqs(createParser))`.
+   */
+  readonly urlState: () => ListUrlState;
+  /** Its setter, which `apply` calls with every key so stale ones clear. */
+  readonly setUrlState: (next: Record<string, unknown>) => unknown;
+}
+interface SavedViewsSnapshot<V extends SavedViewLike> {
+  /** `undefined` until the first load. */
+  readonly views: readonly V[] | undefined;
+  /** The view `apply` opened last. */
+  readonly opened: V | undefined;
+  readonly error: unknown;
+}
+interface SavedViewsActions<V extends SavedViewLike> {
+  /** Puts a view's query in the URL and passes the rest to `onApplyState`. */
+  readonly apply: (view: V) => void;
+  /** Saves the current state as a new view, or over `id`, then loads again. */
+  readonly saveCurrent: (name: string, id?: string) => Promise<void>;
+  readonly remove: (id: string) => Promise<void>;
+  /** Copies a view under `name`, then loads again. */
+  readonly duplicate: (id: string, name: string, scope?: SavedViewScope) => Promise<void>;
+  /** Sets the caller's own default, hidden or pinned flag, then loads again. */
+  readonly setPreference: (id: string, preference: SavedViewPreferenceInput) => Promise<void>;
+  readonly refresh: () => Promise<void>;
+}
+type SavedViewsController<V extends SavedViewLike> = Controller<SavedViewsSnapshot<V>, SavedViewsActions<V>>;
+/** What the URL and the display state show, compared with the views. */
+interface SavedViewsMatch<V extends SavedViewLike> {
+  /** The view whose state the URL and `getState()` hold, if any. */
+  readonly active: V | undefined;
+  /** The URL's query, in the shape a view stores. */
+  readonly query: ListQueryInput<string, string>;
+  /** The URL's query and `getState()`, in the shape a view stores. */
+  readonly state: SavedViewState;
+  /** Whether the state changed since `apply` opened the last view. */
+  readonly isDirty: boolean;
+}
+/** Matches the URL state and the display state against the loaded views. */
+declare function matchSavedViews<V extends SavedViewLike>(snapshot: SavedViewsSnapshot<V>, urlState: ListUrlState, display: SavedViewDisplayState | undefined): SavedViewsMatch<V>;
+/**
+ * Saved views of one list, synced with its URL state and, through `getState`
+ * and `onApplyState`, with the table's columns, grouping, density and layout.
+ */
+declare function createSavedViewsController<V extends SavedViewLike>(options: SavedViewsControllerOptions<V>): SavedViewsController<V>;
+//#endregion
+export { SavedViewRef as A, SavedViewColumns as C, SavedViewList as D, SavedViewKind as E, createSavedViews as F, defaultView as I, savedViewIssues as L, SavedViewState as M, SavedViews as N, SavedViewPreference as O, SavedViewsOptions as P, savedViewStateSchema as R, SavedView as S, SavedViewDisplayState as T, DuplicateViewInput as _, SavedViewsMatch as a, SAVED_VIEW_SCOPES as b, createSavedViewsController as c, displayStateOf as d, queryFromUrlState as f, DefaultViewCandidate as g, urlStateFromQuery as h, SavedViewsControllerOptions as i, SavedViewScope as j, SavedViewPreferenceInput as k, matchSavedViews as l, sameQuery as m, SavedViewsActions as n, SavedViewsSnapshot as o, sameDisplayState as p, SavedViewsController as r, SavedViewsSyncOptions as s, SavedViewLike as t, ListUrlState as u, SAVED_VIEW_DENSITIES as v, SavedViewDensity as w, SaveViewInput as x, SAVED_VIEW_KINDS as y };