@qnc/qnc_data_tables 1.0.3 → 1.0.6-a

package/dist/column_manager.ts

@@ -0,0 +1,158 @@
+import { Column } from "./table_options.js";
+import * as ss from "superstruct";
+import * as tu from "@qnc/type_utils";
+
+/**
+    Responsible for 
+    - reading TableOptions.columns and then interpreting and updating user's stored preferences
+ */
+export class ColumnManager {
+    #fixed_columns: ManagedColumn[];
+    #sortable_columns: ManagedColumn[];
+    #all_columns: Map<string, ManagedColumn>;
+
+    constructor(
+        private columns: Column[],
+        private storage: Storage | null,
+        private storage_key: string,
+        public on_any_change: () => void,
+    ) {
+        if (columns.length != new Set(columns.map((c) => c.key)).size)
+            throw new Error("columns do not all have unique keys");
+
+        this.#all_columns = new Map();
+        this.#fixed_columns = [];
+        this.#sortable_columns = [];
+
+        for (const c of columns) {
+            const mutable_column: ManagedColumn = {
+                key: c.key,
+                display: c.display,
+                help_text: c.help_text,
+                width: c.width,
+                enabled: c.enabled,
+                sortable: c.sortable,
+            };
+
+            this.#all_columns.set(c.key, c);
+            if (c.fixed) {
+                this.#fixed_columns.push(c);
+            } else {
+                this.#sortable_columns.push(c);
+            }
+        }
+
+        // update state based on user preferences
+        if (storage) {
+            const config = tu.parse_json(
+                storage.getItem(this.storage_key) ?? "",
+            );
+            if (ss.is(config, UserPreferencesStruct)) {
+                this.#read_order(config.map((column) => column.key));
+
+                for (const { key, enabled, width } of config) {
+                    const column = this.#all_columns.get(key);
+                    if (!column) continue; // previously saved column is no longer available; no problem, just ignore it
+                    column.enabled = enabled;
+                    column.width = width;
+                }
+            }
+        }
+    }
+
+    /** returns them in display order */
+    get all_enabled_columns(): ColumnList {
+        return this.#fixed_columns.concat(
+            this.#sortable_columns.filter((c) => c.enabled),
+        );
+    }
+    /** returns them in display order */
+    get fixed_enabled_columns(): ColumnList {
+        return this.#fixed_columns;
+    }
+    /** returns them in display order */
+    get sortable_enabled_columns(): ColumnList {
+        return this.#sortable_columns.filter((c) => c.enabled);
+    }
+    /** returns them in sorted order */
+    get all_sortable_columns(): ColumnList {
+        return this.#sortable_columns;
+    }
+
+    /** the only keys that matter are those that correspond to sortable columns; if you pass us keys of fixed columns, we simply ignore those */
+    #read_order(keys: Array<string>) {
+        this.#sortable_columns.sort(function (
+            a: ManagedColumn,
+            b: ManagedColumn,
+        ) {
+            return keys.indexOf(a.key) - keys.indexOf(b.key);
+        });
+    }
+
+    /** the only keys that matter are those that correspond to sortable columns; if you pass us keys of fixed columns, we simply ignore those */
+    set_order(keys: Array<string>) {
+        this.#read_order(keys);
+        this.#save();
+        this.on_any_change();
+    }
+
+    set_enabled(key: string, enabled: boolean) {
+        const column = this.#all_columns.get(key);
+        if (!column) throw new Error(`No column with key ${key}`);
+        column.enabled = enabled;
+        this.#save();
+        this.on_any_change();
+    }
+
+    set_width(key: string, width: number) {
+        const column = this.#all_columns.get(key);
+        if (!column) throw new Error(`No column with key ${key}`);
+        column.width = width;
+        this.#save();
+        this.on_any_change();
+    }
+
+    #save() {
+        if (!this.storage) return;
+        const columns = this.#fixed_columns.concat(this.#sortable_columns);
+        this.storage.setItem(
+            this.storage_key,
+            JSON.stringify(
+                columns.map((column) => ({
+                    key: column.key,
+                    enabled: column.enabled,
+                    width: column.width,
+                })),
+            ),
+        );
+    }
+}
+
+/** Readonly view of ColumnManager; can be passed to view layer */
+export type ConfiguredColumns = {
+    all_enabled_columns: ColumnList;
+    fixed_enabled_columns: ColumnList;
+    sortable_enabled_columns: ColumnList;
+    all_sortable_columns: ColumnList;
+};
+
+type ManagedColumn = {
+    key: string;
+    display: string;
+    help_text: string;
+    sortable: boolean;
+    enabled: boolean;
+    width: number;
+};
+
+type ColumnList = ReadonlyArray<Readonly<ManagedColumn>>;
+
+export type ConfiguredColumn = Readonly<ManagedColumn>;
+
+const UserPreferencesStruct = ss.array(
+    ss.object({
+        key: ss.string(),
+        width: ss.number(),
+        enabled: ss.boolean(),
+    }),
+);

package/dist/column_resizing.d.ts

@@ -0,0 +1,3 @@
+type ResizeCallback = (width: number) => void;
+export declare function begin_header_drag(event: MouseEvent, on_resize: ResizeCallback, initial_width: number, on_complete: () => void): void;
+export {};

package/dist/column_resizing.js

@@ -0,0 +1,30 @@
+let resizing = null;
+export function begin_header_drag(event, on_resize, initial_width, on_complete) {
+    complete_any_active_resizing();
+    const style = document.createElement("style");
+    style.innerHTML = "* {cursor: col-resize !important}";
+    document.body.appendChild(style);
+    resizing = {
+        style,
+        on_resize,
+        initial_width,
+        initial_x: event.clientX,
+        on_complete,
+    };
+}
+window.addEventListener("mousemove", function (event) {
+    if (!resizing)
+        return;
+    event.preventDefault(); // prevent text selection
+    const new_width = Math.max(0, resizing.initial_width + event.clientX - resizing.initial_x);
+    resizing.on_resize(new_width);
+});
+function complete_any_active_resizing() {
+    if (!resizing)
+        return;
+    resizing.style.remove();
+    const on_complete = resizing.on_complete;
+    resizing = null;
+    on_complete();
+}
+window.addEventListener("mouseup", complete_any_active_resizing);

package/dist/column_resizing.ts

@@ -0,0 +1,52 @@
+type ResizeCallback = (width: number) => void;
+
+type ColumnResizing = {
+    style: HTMLStyleElement;
+    on_resize: ResizeCallback;
+    initial_x: number;
+    initial_width: number;
+    on_complete: () => void;
+};
+
+let resizing: ColumnResizing | null = null;
+
+export function begin_header_drag(
+    event: MouseEvent,
+    on_resize: ResizeCallback,
+    initial_width: number,
+    on_complete: () => void,
+) {
+    complete_any_active_resizing();
+    const style = document.createElement("style");
+    style.innerHTML = "* {cursor: col-resize !important}";
+    document.body.appendChild(style);
+    resizing = {
+        style,
+        on_resize,
+        initial_width,
+        initial_x: event.clientX,
+        on_complete,
+    };
+}
+window.addEventListener("mousemove", function (event) {
+    if (!resizing) return;
+    event.preventDefault(); // prevent text selection
+
+    const new_width = Math.max(
+        0,
+        resizing.initial_width + event.clientX - resizing.initial_x,
+    );
+    resizing.on_resize(new_width);
+});
+function complete_any_active_resizing() {
+    if (!resizing) return;
+    resizing.style.remove();
+
+    const on_complete = resizing.on_complete;
+
+    resizing = null;
+
+    on_complete();
+}
+
+window.addEventListener("mouseup", complete_any_active_resizing);

package/dist/column_sorting.d.ts

@@ -0,0 +1,11 @@
+import { SortState } from "./state_types.js";
+export declare function make_column_sort_key(column_key: string, direction: "forward" | "reverse"): string;
+export declare function make_function_sort_key(function_key: string): string;
+export declare function parse_sort_key(sort_key: string): SortState | null;
+export declare function encode_sort(sort: SortState | null): string;
+/**
+    sort_key identifies the current "sorting function" of the table
+    column_key can represent any column
+    return value indicates whether the current sorting function is sorting by this column, and if so, which direction
+ */
+export declare function current_sort_direction(column_key: string, sort_key: string): "forward" | "reverse" | null;

package/dist/column_sorting.js

@@ -0,0 +1,53 @@
+import * as tu from "@qnc/type_utils";
+// Note: this logic is duplicated in (and coupled to) the back-end
+const column_key_regex = /^_column_((?:forward)|(?:reverse))_(.*)$/;
+export function make_column_sort_key(column_key, direction) {
+    return `_column_${direction}_${column_key}`;
+}
+const function_key_regex = /^function_(.*)$/;
+export function make_function_sort_key(function_key) {
+    return `function_${function_key}`;
+}
+export function parse_sort_key(sort_key) {
+    if (sort_key == "")
+        return null;
+    let match = sort_key.match(column_key_regex);
+    if (match) {
+        return {
+            type: "column",
+            column_key: match[2],
+            direction: match[1],
+        };
+    }
+    match = sort_key.match(function_key_regex);
+    if (match) {
+        return {
+            type: "function",
+            function_key: match[1],
+        };
+    }
+    throw new Error(`Invalid sort key: ${sort_key}`);
+}
+export function encode_sort(sort) {
+    if (!sort)
+        return "";
+    if (sort.type == "column") {
+        return make_column_sort_key(sort.column_key, sort.direction);
+    }
+    if (sort.type == "function") {
+        return make_function_sort_key(sort.function_key);
+    }
+    tu.assert_never(sort);
+}
+/**
+    sort_key identifies the current "sorting function" of the table
+    column_key can represent any column
+    return value indicates whether the current sorting function is sorting by this column, and if so, which direction
+ */
+export function current_sort_direction(column_key, sort_key) {
+    if (sort_key == make_column_sort_key(column_key, "forward"))
+        return "forward";
+    if (sort_key == make_column_sort_key(column_key, "reverse"))
+        return "reverse";
+    return null;
+}

package/dist/column_sorting.ts

@@ -0,0 +1,63 @@
+import { SortState } from "./state_types.js";
+import * as tu from "@qnc/type_utils";
+
+// Note: this logic is duplicated in (and coupled to) the back-end
+const column_key_regex = /^_column_((?:forward)|(?:reverse))_(.*)$/;
+export function make_column_sort_key(
+    column_key: string,
+    direction: "forward" | "reverse",
+) {
+    return `_column_${direction}_${column_key}`;
+}
+
+const function_key_regex = /^function_(.*)$/;
+export function make_function_sort_key(function_key: string) {
+    return `function_${function_key}`;
+}
+
+export function parse_sort_key(sort_key: string): SortState | null {
+    if (sort_key == "") return null;
+    let match = sort_key.match(column_key_regex);
+    if (match) {
+        return {
+            type: "column",
+            column_key: match[2] as string,
+            direction: match[1] as "forward" | "reverse",
+        };
+    }
+    match = sort_key.match(function_key_regex);
+    if (match) {
+        return {
+            type: "function",
+            function_key: match[1] as string,
+        };
+    }
+    throw new Error(`Invalid sort key: ${sort_key}`);
+}
+
+export function encode_sort(sort: SortState | null) {
+    if (!sort) return "";
+    if (sort.type == "column") {
+        return make_column_sort_key(sort.column_key, sort.direction);
+    }
+    if (sort.type == "function") {
+        return make_function_sort_key(sort.function_key);
+    }
+    tu.assert_never(sort);
+}
+
+/**
+    sort_key identifies the current "sorting function" of the table
+    column_key can represent any column
+    return value indicates whether the current sorting function is sorting by this column, and if so, which direction
+ */
+export function current_sort_direction(
+    column_key: string,
+    sort_key: string,
+): "forward" | "reverse" | null {
+    if (sort_key == make_column_sort_key(column_key, "forward"))
+        return "forward";
+    if (sort_key == make_column_sort_key(column_key, "reverse"))
+        return "reverse";
+    return null;
+}

package/dist/conditionally_wrapped_element.d.ts

@@ -0,0 +1,5 @@
+/**
+    If html represents exactly one node, and that node is an HTMLElement, return that element.
+    Otherwise, wrap in a div.
+ */
+export declare function conditionally_wrapped_element(html: string): HTMLElement;

package/dist/conditionally_wrapped_element.js

@@ -0,0 +1,14 @@
+/**
+    If html represents exactly one node, and that node is an HTMLElement, return that element.
+    Otherwise, wrap in a div.
+ */
+export function conditionally_wrapped_element(html) {
+    const t = document.createElement("template");
+    t.innerHTML = html;
+    if (t.content.childNodes.length == 1 &&
+        t.content.children[0] instanceof HTMLElement)
+        return t.content.children[0];
+    const d = document.createElement("div");
+    d.innerHTML = html;
+    return d;
+}

package/dist/conditionally_wrapped_element.ts

@@ -0,0 +1,17 @@
+/**
+    If html represents exactly one node, and that node is an HTMLElement, return that element.
+    Otherwise, wrap in a div.
+ */
+export function conditionally_wrapped_element(html: string): HTMLElement {
+    const t = document.createElement("template");
+    t.innerHTML = html;
+    if (
+        t.content.childNodes.length == 1 &&
+        t.content.children[0] instanceof HTMLElement
+    )
+        return t.content.children[0];
+
+    const d = document.createElement("div");
+    d.innerHTML = html;
+    return d;
+}

package/dist/create_mithril_app.d.ts

@@ -0,0 +1,3 @@
+import { StateMachine } from "./state_machine.js";
+import { Renderer } from "./renderer.js";
+export declare function create_mithril_app(container: HTMLElement, state_machine: StateMachine<string>, renderer: Renderer): void;

package/dist/create_mithril_app.js

@@ -0,0 +1,25 @@
+import m from "mithril";
+import { app_view } from "./mithril_view.js";
+export function create_mithril_app(container, state_machine, renderer) {
+    const updaters = {
+        sort_by_function: state_machine.sort_by_function.bind(state_machine),
+        sort_by_column: state_machine.sort_by_column.bind(state_machine),
+        set_page_size: state_machine.set_page_size.bind(state_machine),
+        set_page_number: state_machine.set_page_number.bind(state_machine),
+        set_column_enabled: state_machine.set_column_enabled.bind(state_machine),
+        set_column_width: state_machine.set_column_width.bind(state_machine),
+        set_column_order: state_machine.set_column_order.bind(state_machine),
+        set_selected(pk, selected) {
+            state_machine.set_selected(pk, selected);
+        },
+        bulk_set_selected(pks, selected) {
+            state_machine.bulk_set_selected(pks, selected);
+        },
+    };
+    const component = {
+        view() {
+            return app_view(state_machine.get_state(), renderer, updaters);
+        },
+    };
+    m.mount(container, component);
+}

package/dist/create_mithril_app.ts

@@ -0,0 +1,35 @@
+import { StateMachine } from "./state_machine.js";
+import m from "mithril";
+import { app_view } from "./mithril_view.js";
+import { Renderer } from "./renderer.js";
+
+export function create_mithril_app(
+    container: HTMLElement,
+    state_machine: StateMachine<string>,
+    renderer: Renderer,
+) {
+    const updaters = {
+        sort_by_function: state_machine.sort_by_function.bind(state_machine),
+        sort_by_column: state_machine.sort_by_column.bind(state_machine),
+        set_page_size: state_machine.set_page_size.bind(state_machine),
+        set_page_number: state_machine.set_page_number.bind(state_machine),
+        set_column_enabled:
+            state_machine.set_column_enabled.bind(state_machine),
+        set_column_width: state_machine.set_column_width.bind(state_machine),
+        set_column_order: state_machine.set_column_order.bind(state_machine),
+        set_selected(pk: string, selected: boolean) {
+            state_machine.set_selected(pk, selected);
+        },
+        bulk_set_selected(pks: Iterable<string>, selected: boolean) {
+            state_machine.bulk_set_selected(pks, selected);
+        },
+    };
+
+    const component = {
+        view() {
+            return app_view(state_machine.get_state(), renderer, updaters);
+        },
+    };
+
+    m.mount(container, component);
+}

package/dist/create_style.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Create a <style> element that users should inject into their document somewhere.
+ */
+export declare function create_style(): HTMLStyleElement;

package/dist/create_style.js

@@ -0,0 +1,9 @@
+import css from "../intermediate/qnc_data_tables_inline_css.js";
+/**
+ * Create a <style> element that users should inject into their document somewhere.
+ */
+export function create_style() {
+    const style = document.createElement("style");
+    style.innerText = css;
+    return style;
+}

package/dist/create_style.ts

@@ -0,0 +1,10 @@
+import css from "../intermediate/qnc_data_tables_inline_css.js";
+
+/**
+ * Create a <style> element that users should inject into their document somewhere.
+ */
+export function create_style() {
+    const style = document.createElement("style");
+    style.innerText = css;
+    return style;
+}

package/dist/custom_element.d.ts

@@ -0,0 +1,23 @@
+import { Renderer } from "./renderer.js";
+import { TableManager } from "./table_manager.js";
+/**
+    Register the given tag name with customElements as data-table container which always uses the given Renderer.
+    Most sites will only need to call this once.
+    You _may_ call this multiple times, if you want to have multiple "table styles", using different Renderers.
+
+    Note that any element defined via this function must also have a `table-config` attribute set. This attribute must be a JSON encoded TableOptions object (ie. from table_options.ts).
+ */
+export declare function define_custom_element(tag_name: string, renderer: Renderer): void;
+export declare class BaseQncDataTable extends HTMLElement {
+    #private;
+    get renderer(): Renderer;
+    private _table_manager;
+    static get observed_attributes(): string[];
+    connectedCallback(): void;
+    attributeChangedCallback(): void;
+    /**
+        To be called whenever you need access to our TableManager.
+        You should not store a reference to the result. The result may become invalid if our configuration changes.
+    */
+    required_table_manager(): TableManager;
+}

package/dist/custom_element.js

@@ -0,0 +1,63 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _BaseQncDataTable_instances, _BaseQncDataTable_setup;
+import { read_options_from_json_string } from "./table_options.js";
+import { create_mithril_app } from "./create_mithril_app.js";
+import { TableManager } from "./table_manager.js";
+import { StateMachine } from "./state_machine.js";
+import { conditionally_wrapped_element } from "./conditionally_wrapped_element.js";
+import { redraw } from "mithril";
+/**
+    Register the given tag name with customElements as data-table container which always uses the given Renderer.
+    Most sites will only need to call this once.
+    You _may_ call this multiple times, if you want to have multiple "table styles", using different Renderers.
+
+    Note that any element defined via this function must also have a `table-config` attribute set. This attribute must be a JSON encoded TableOptions object (ie. from table_options.ts).
+ */
+export function define_custom_element(tag_name, renderer) {
+    class QncDataTable extends BaseQncDataTable {
+        get renderer() {
+            return renderer;
+        }
+    }
+    customElements.define(tag_name, QncDataTable);
+}
+export class BaseQncDataTable extends HTMLElement {
+    constructor() {
+        super(...arguments);
+        _BaseQncDataTable_instances.add(this);
+        this._table_manager = null;
+    }
+    get renderer() {
+        throw new Error("`get renderer()` must be implemented in derived class");
+    }
+    static get observed_attributes() {
+        return ["table-config"];
+    }
+    connectedCallback() {
+        __classPrivateFieldGet(this, _BaseQncDataTable_instances, "m", _BaseQncDataTable_setup).call(this);
+    }
+    attributeChangedCallback() {
+        __classPrivateFieldGet(this, _BaseQncDataTable_instances, "m", _BaseQncDataTable_setup).call(this);
+    }
+    /**
+        To be called whenever you need access to our TableManager.
+        You should not store a reference to the result. The result may become invalid if our configuration changes.
+    */
+    required_table_manager() {
+        if (!this._table_manager)
+            throw new Error("Element has not been set up yet. It has no StateMachine attached");
+        return this._table_manager;
+    }
+}
+_BaseQncDataTable_instances = new WeakSet(), _BaseQncDataTable_setup = function _BaseQncDataTable_setup() {
+    const config = this.getAttribute("table-config");
+    if (!config)
+        throw new Error("[table-config] attribute is required");
+    const state_machine = new StateMachine(read_options_from_json_string(config), (html) => conditionally_wrapped_element(html).outerHTML, this, (state) => redraw());
+    create_mithril_app(this, state_machine, this.renderer);
+    this._table_manager = new TableManager(state_machine, this);
+};

package/dist/custom_element.ts

@@ -0,0 +1,71 @@
+import { Renderer } from "./renderer.js";
+import { read_options_from_json_string } from "./table_options.js";
+import { create_mithril_app } from "./create_mithril_app.js";
+import { TableManager } from "./table_manager.js";
+import { StateMachine } from "./state_machine.js";
+import { conditionally_wrapped_element } from "./conditionally_wrapped_element.js";
+import { redraw, Vnode } from "mithril";
+import { AppState } from "./state_types.js";
+
+/**
+    Register the given tag name with customElements as data-table container which always uses the given Renderer.
+    Most sites will only need to call this once.
+    You _may_ call this multiple times, if you want to have multiple "table styles", using different Renderers.
+
+    Note that any element defined via this function must also have a `table-config` attribute set. This attribute must be a JSON encoded TableOptions object (ie. from table_options.ts).
+ */
+export function define_custom_element(tag_name: string, renderer: Renderer) {
+    class QncDataTable extends BaseQncDataTable {
+        get renderer(): Renderer {
+            return renderer;
+        }
+    }
+    customElements.define(tag_name, QncDataTable);
+}
+
+export class BaseQncDataTable extends HTMLElement {
+    get renderer(): Renderer {
+        throw new Error(
+            "`get renderer()` must be implemented in derived class",
+        );
+    }
+
+    private _table_manager: TableManager | null = null;
+
+    static get observed_attributes() {
+        return ["table-config"];
+    }
+    connectedCallback() {
+        this.#setup();
+    }
+    attributeChangedCallback() {
+        this.#setup();
+    }
+    #setup() {
+        const config = this.getAttribute("table-config");
+        if (!config) throw new Error("[table-config] attribute is required");
+
+        const state_machine = new StateMachine(
+            read_options_from_json_string(config),
+            (html) => conditionally_wrapped_element(html).outerHTML,
+            this,
+            (state: AppState<string>) => redraw(),
+        );
+
+        create_mithril_app(this, state_machine, this.renderer);
+
+        this._table_manager = new TableManager(state_machine, this);
+    }
+
+    /**
+        To be called whenever you need access to our TableManager.
+        You should not store a reference to the result. The result may become invalid if our configuration changes.
+    */
+    required_table_manager(): TableManager {
+        if (!this._table_manager)
+            throw new Error(
+                "Element has not been set up yet. It has no StateMachine attached",
+            );
+        return this._table_manager;
+    }
+}

package/dist/event_names.d.ts

@@ -0,0 +1 @@
+export declare const SELECTION_CHANGE = "qnc-data-tables-selection-change";

package/dist/event_names.js

@@ -0,0 +1 @@
+export const SELECTION_CHANGE = "qnc-data-tables-selection-change";