@sepale/components 0.0.0-stage → 0.1.0

package/dist/components/data-handler.svelte.d.ts

@@ -0,0 +1,362 @@
+/**
+ * The data handler: the live state of one remote resource — the rows of the
+ * current page, the total, the search, the sort, the filter values, the
+ * selection, the pending edits and their history — and the requests that read
+ * and change it.
+ *
+ * It draws nothing. `DataHandler.svelte` hands an instance to its children;
+ * the same class can be used directly, `new DataHandlerState(…)`. Tables,
+ * grids and lists know nothing of it: they are given its rows as if they
+ * were static.
+ *
+ * Where the data comes from, in order:
+ *   1. the functions passed as `get` / `update` / `delete` — plain async
+ *      functions, or SvelteKit remote functions, which are callable the same
+ *      way;
+ *   2. otherwise `path`, a REST resource:
+ *        GET    path?filters…&search=&sort=id-asc&page=&limit=  → { data, total }
+ *        PATCH  path/:id      body: the changed fields
+ *        DELETE path          body: [ids]
+ *   3. otherwise the action is not available (`canUpdate`, `canDelete`).
+ */
+export type EntityFilter<ID extends string = string> = {
+    id: ID;
+    title: string;
+    type: 'entity';
+    /** The suggestions for what is being typed. */
+    items: (query: string) => PromiseLike<EntitySuggestion[]> | EntitySuggestion[];
+    /** The text of one suggestion, and of the value. Default: its `name`, else its `id`. */
+    show?: (suggestion: EntitySuggestion) => string;
+    /** Milliseconds without typing before `items` is asked. */
+    wait?: number;
+    /** What it picks, for whoever draws the entity (DataControl's `entity`). */
+    kind?: string;
+};
+export type NumberFilter<ID extends string = string> = {
+    id: ID;
+    title: string;
+    type: 'number';
+    min?: number;
+    max?: number;
+    step?: number;
+};
+export type DateFilter<ID extends string = string> = {
+    id: ID;
+    title: string;
+    type: 'date';
+};
+export type SelectFilter<ID extends string = string, V extends string = string> = {
+    id: ID;
+    title: string;
+    type: 'select';
+    options: {
+        name: string;
+        value: V;
+    }[];
+    multiple?: boolean;
+    nullable?: boolean;
+    /** In a `fields` control, show a choice among few options as a switch rather than a select. */
+    switch?: boolean;
+};
+export type BooleanFilter<ID extends string = string> = {
+    id: ID;
+    title: string;
+    type: 'boolean';
+};
+export type TextFilter<ID extends string = string> = {
+    id: ID;
+    title: string;
+    type: 'text';
+};
+export type Filter<ID extends string = string> = Readonly<EntityFilter<ID> | NumberFilter<ID> | DateFilter<ID> | SelectFilter<ID, string> | BooleanFilter<ID> | TextFilter<ID>>;
+/** A picked entity: what the filter holds, and what the address bar writes. */
+export type EntityValue = {
+    id: string;
+    name?: string;
+};
+/** A suggestion for an entity filter. A numeric id is written as text once picked. */
+export type EntitySuggestion = {
+    id: string | number;
+    name?: string;
+};
+type FilterValueMap<V extends string = string> = {
+    text: string;
+    entity: EntityValue;
+    number: number;
+    date: Date;
+    select: V[];
+    boolean: boolean;
+};
+type ValueOf<F extends Filter> = F extends SelectFilter<string, infer V> ? FilterValueMap<V>[F['type']] : FilterValueMap[F['type']];
+/** The value of every filter, by id. A filter without a value is absent. */
+export type FilterValues<F extends readonly Filter[]> = {
+    [K in F[number]['id']]?: ValueOf<Extract<F[number], {
+        id: K;
+    }>>;
+};
+/** A filter as the handler holds it: shown or not, and maybe immutable. */
+export type HandledFilter<F extends Filter = Filter> = F & {
+    /** On the page, with or without a value. */
+    shown: boolean;
+    /** Set by the page and never offered to the visitor. */
+    immutable: boolean;
+};
+/** One way to order the rows. `id` is what the server is sent. */
+export type Sort = {
+    id: string;
+    name: string;
+    value: 'asc' | 'desc';
+};
+export type GetParams<FV> = {
+    filters: FV;
+    search?: string;
+    sort?: {
+        id: string;
+        value: 'asc' | 'desc';
+    };
+    /** The handler always sends it; a direct call may leave it out. */
+    limit?: number;
+    /** From 1. The handler always sends it; a direct call may leave it out. */
+    page?: number;
+};
+export type GetResult<Model> = {
+    data?: Model[];
+    total?: number;
+};
+export type GetQuery<FV, Model> = (params: GetParams<FV>) => PromiseLike<GetResult<Model>>;
+export type UpdateQuery<Model, Id> = (params: {
+    id: Id;
+    data: Partial<Model>;
+}) => PromiseLike<unknown>;
+export type DeleteQuery<Id> = (ids: Id[]) => PromiseLike<unknown>;
+/** How a row is told apart: one of its keys, or a pair of functions. */
+export type Identifier<Model, Id> = keyof Model | {
+    to: (row: Model, index: number) => string;
+    from: (id: string) => Id;
+};
+/** How the query is written to the address bar. Default: the History API. */
+export type Navigation = {
+    push: (url: string, state: Record<string, unknown>) => void;
+    replace: (url: string, state: Record<string, unknown>) => void;
+};
+/** What `confirmDiscard` may answer. */
+export type DiscardChoice = 'save' | 'discard' | 'stay';
+/** Every text the handler writes, for `onlog` and `onerror`. */
+export type DataHandlerMessages = {
+    loadFailed: string;
+    saveFailed: string;
+    deleteFailed: string;
+    discarded: (count: number) => string;
+    saved: (count: number) => string;
+    deleted: (count: number) => string;
+    exportEmpty: string;
+};
+export type DataHandlerOptions<F extends readonly Filter[], Model, Id> = {
+    /** How a row is told apart. A key of the model, or `{ to, from }`. */
+    identifier: Identifier<Model, Id>;
+    /** Fetch one page. A plain async function or a SvelteKit remote function. */
+    get?: GetQuery<FilterValues<F>, Model>;
+    /** Save the changed fields of one row. */
+    update?: UpdateQuery<Model, Id>;
+    /** Delete rows. */
+    delete?: DeleteQuery<Id>;
+    /** A REST resource standing in for whichever of the three is missing. */
+    path?: string;
+    /** The fetch `path` goes through. Default: the global one. */
+    fetch?: typeof fetch;
+    /** The filters the visitor may use. */
+    filters?: F;
+    /** The orders the visitor may pick. */
+    sorts?: readonly Sort[];
+    /** The starting order. Default: the first of `sorts`. */
+    sort?: Sort;
+    /** Filters set by the page and never shown. */
+    immutableFilters?: F[number]['id'][];
+    /** The starting search. */
+    search?: string;
+    /** The starting filter values. */
+    filterValues?: FilterValues<F>;
+    /** Rows already loaded (by a server load), so the first fetch is skipped. */
+    init?: GetResult<Model>;
+    /** Rows per page. Default 10. */
+    limit?: number;
+    /** The starting page, from 1. */
+    page?: number;
+    /** Write the query to the address bar after every fetch. Default false. */
+    history?: boolean;
+    /** How to write it. In SvelteKit, pass `{ push: pushState, replace: replaceState }`. */
+    navigation?: Navigation;
+    /** Asked before deleting. `false` cancels. Without it, the rows go at once. */
+    confirmDelete?: (ids: string[]) => Promise<boolean>;
+    /** Asked before a fetch would drop unsaved changes. Without it, they are dropped and logged. */
+    confirmDiscard?: (count: number) => Promise<DiscardChoice>;
+    /** Something happened worth telling the visitor. */
+    onlog?: (message: string) => void;
+    /** Something failed. Without it, the error goes to the console. */
+    onerror?: (message: string, error?: unknown) => void;
+    /** The texts written to `onlog` and `onerror`. */
+    messages?: Partial<DataHandlerMessages>;
+};
+/**
+ * One row as the handler hands it out: the data, and what can be done to it.
+ * `value` is what to draw; `init` is what the server last said; `updated`
+ * holds the fields that differ.
+ */
+export type DataRow<Model> = {
+    id: string;
+    init: Model;
+    value: Model;
+    updated: Partial<Model>;
+    selected: boolean;
+    /** Changed and not yet saved. */
+    readonly dirty: boolean;
+    select: () => void;
+    unselect: () => void;
+    toggle: () => void;
+    /** Change fields: an object of new values, or a function of the current value. */
+    update: (patch: Partial<Model> | ((value: Model) => Partial<Model>)) => void;
+    /** Take back this row's last change. */
+    undo: () => void;
+    /** Drop every change to this row. Undoable. */
+    reset: () => void;
+    save: () => Promise<void>;
+    delete: () => Promise<void>;
+};
+/** Filter values out of a query string — to start a handler where the URL left it. */
+export declare function parseFilterValues<const F extends readonly Filter[]>(params: URLSearchParams, filters: F): FilterValues<F>;
+/** Filter values into a query string. */
+export declare function filterValuesToParams<const F extends readonly Filter[]>(values: FilterValues<F>, filters: F): URLSearchParams;
+/** Everything a handler can start from that a URL can carry. */
+export declare function parseQuery<const F extends readonly Filter[]>(params: URLSearchParams, filters: F, sorts?: readonly Sort[]): {
+    filterValues: FilterValues<F>;
+    search?: string;
+    sort?: Sort;
+    page?: number;
+    limit?: number;
+};
+export declare class DataHandlerState<const F extends readonly Filter[] = Filter[], Model extends Record<string, any> = Record<string, any>, Id = string> {
+    #private;
+    /** A fetch is running. */
+    loading: boolean;
+    /** The rows of the current page. */
+    rows: DataRow<Model>[];
+    /** How many rows match, over every page. `undefined` until known. */
+    total: number | undefined;
+    /** Every filter the handler knows, shown or not. */
+    filters: HandledFilter<F[number]>[];
+    /** The value of each filter. */
+    filterValues: FilterValues<F>;
+    search: string;
+    sort: Sort | undefined;
+    /** From 1. */
+    page: number;
+    limit: number;
+    readonly sorts: readonly Sort[];
+    /** The keys of the selected rows. */
+    selection: string[];
+    /** The rows changed and not yet saved. */
+    changed: string[];
+    /** Something is changed and not yet saved. */
+    dirty: boolean;
+    /** The filters on the page. */
+    shownFilters: HandledFilter<F[number]>[];
+    /** The filters that could be added to the page. */
+    availableFilters: HandledFilter<F[number]>[];
+    /** How many pages there are, once the total is known. */
+    pages: number | undefined;
+    canUndo: boolean;
+    canRedo: boolean;
+    readonly identifier: {
+        to: (row: Model, index: number) => string;
+        from: (id: string) => Id;
+    };
+    readonly options: DataHandlerOptions<F, Model, Id>;
+    readonly messages: DataHandlerMessages;
+    constructor(options: DataHandlerOptions<F, Model, Id>);
+    get canUpdate(): boolean;
+    get canDelete(): boolean;
+    /**
+     * Fetch the current page. Unsaved changes are put to `confirmDiscard`
+     * first; "stay" puts the query back where the last fetch left it.
+     * `delay` debounces (a search being typed); `replace` rewrites the
+     * address bar entry instead of adding one; `typing` names the field being
+     * typed in, whose changes in a row make a single entry.
+     */
+    load(options?: {
+        delay?: number;
+        replace?: boolean;
+        typing?: string;
+    }): Promise<void>;
+    /** Fetch again, as is: after a change made elsewhere. */
+    reload(): Promise<void>;
+    /**
+     * Go back to a query the address bar holds, when the visitor walks the
+     * browser history: fetches it without adding an entry. Filters holding a
+     * value are shown, the others are not; immutable ones keep their value. On
+     * "stay", the address is written back to the rows still on screen.
+     */
+    restore(params: URLSearchParams): Promise<void>;
+    /** The query, as the address bar and the REST path write it. */
+    toSearchParams(): URLSearchParams;
+    changePage(page: number): Promise<void>;
+    changeLimit(limit: number): Promise<void>;
+    changeSort(sort: Sort | undefined): Promise<void>;
+    /** A new search, fetched once the typing pauses (`delay`, default 300 ms). */
+    changeSearch(search: string, delay?: number): Promise<void>;
+    changeFilter<K extends F[number]['id']>(id: K, value: FilterValues<F>[K] | undefined, delay?: number): Promise<void>;
+    /** Put a filter on the page, without a value yet. */
+    showFilter(id: F[number]['id']): void;
+    /** Take a filter off the page, and its value with it. */
+    removeFilter(id: F[number]['id']): Promise<void> | undefined;
+    /** Select one row, or every row of the page. */
+    select(id?: string): void;
+    /** Unselect one row, or every row. */
+    unselect(id?: string): void;
+    /** Every row of the page is selected. */
+    get allSelected(): boolean;
+    /** Change fields of one row. */
+    update(id: string, patch: Partial<Model> | ((value: Model) => Partial<Model>)): void;
+    /** Take back the last change, of the whole page or of one row. */
+    undo(id?: string): void;
+    /** Put back the last change undone. */
+    redo(): void;
+    /** Drop every unsaved change — of one row, or of the page. One undoable step. */
+    reset(id?: string): void;
+    /** Send the changes — of one row, or of every changed row. */
+    save(id?: string): Promise<void>;
+    /** Delete one row, or the selection. Asks `confirmDelete` first. */
+    delete(id?: string): Promise<void>;
+    /**
+     * Every row matching the current query, fetched by batches, as a CSV file
+     * the browser downloads. Returns the file's content, or `undefined` when
+     * there was nothing to export.
+     *
+     * The file is written for a spreadsheet: a UTF-8 BOM (without it Excel
+     * reads ANSI and mangles accents), CRLF line ends (RFC 4180), and text
+     * starting with `= + - @` prefixed with `'`, so that a cell coming from a
+     * user is never run as a formula.
+     */
+    export(options?: {
+        /** The file name. Default `export.csv`. */
+        name?: string;
+        /** At most this many rows. */
+        max?: number;
+        /** Rows per request. Default 100. */
+        batch?: number;
+        /** The columns, in order. Default: every key of the widest row. */
+        columns?: {
+            key: string;
+            label?: string;
+        }[];
+        /** A row as the CSV writes it. Default: the row itself. */
+        format?: (row: Model) => Record<string, unknown>;
+        /** The cell separator. Default `;`. */
+        separator?: string;
+        /** The decimal mark of numbers. Default `,` with a `;` separator (how
+         *  a spreadsheet in a comma-decimal locale reads it), `.` otherwise. */
+        decimal?: string;
+        /** Build the CSV without downloading it. */
+        download?: boolean;
+    }): Promise<string | undefined>;
+}
+export {};