@qnc/qnc_data_tables 1.0.3 → 1.0.6-a

package/dist/optional_storage.d.ts

@@ -0,0 +1,6 @@
+/** Two purposes: automatic key-prefixing, and the ability to create a "dummy storage" */
+export declare function optional_storage_wrapper(storage: Storage | null, key_prefix: string): {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+};
+export type OptionalStorage = ReturnType<typeof optional_storage_wrapper>;

package/dist/optional_storage.js

@@ -0,0 +1,18 @@
+/** Two purposes: automatic key-prefixing, and the ability to create a "dummy storage" */
+export function optional_storage_wrapper(storage, key_prefix) {
+    if (!storage)
+        return {
+            get(key) {
+                return null;
+            },
+            set(key, value) { },
+        };
+    return {
+        get(key) {
+            return storage.getItem(`${key_prefix}${key}`);
+        },
+        set(key, value) {
+            storage.setItem(`${key_prefix}${key}`, value);
+        },
+    };
+}

package/dist/optional_storage.ts

@@ -0,0 +1,23 @@
+/** Two purposes: automatic key-prefixing, and the ability to create a "dummy storage" */
+export function optional_storage_wrapper(
+    storage: Storage | null,
+    key_prefix: string,
+) {
+    if (!storage)
+        return {
+            get(key: string) {
+                return null;
+            },
+            set(key: string, value: string) {},
+        };
+    return {
+        get(key: string) {
+            return storage.getItem(`${key_prefix}${key}`);
+        },
+        set(key: string, value: string) {
+            storage.setItem(`${key_prefix}${key}`, value);
+        },
+    };
+}
+
+export type OptionalStorage = ReturnType<typeof optional_storage_wrapper>;

package/dist/overflow_class_manager.d.ts

@@ -0,0 +1,20 @@
+/**
+    Responsible for toggling "[PREFIX][SIDE]" classes on a possibly-overflowing element.
+
+    Nothing project-specific here
+ */
+export declare class OverflowClassManager {
+    readonly root: Element;
+    readonly class_prefix: string;
+    constructor(root: Element, class_prefix: string);
+    /**
+        detector _may_ have zero size; that's okay (it _should_ have 0 size in at least one dimension)
+
+        detector _may_ be longer (in one dimension) than root; that's also okay
+
+        detector should be positioned [side]-most inside the root (this is tricky if root has padding).
+
+        If root element can scroll in both directions, you need to be careful about how you setup your detectors. Eg. right detector should either be full-height, or should use sticky positioning so that it never goes completely above or completely below root. The only way right detector should not intersect (at all) with root is if it is to-the-right-of root.
+     */
+    setup_overflow_detector(detector: Element, side: "left" | "right" | "top" | "bottom"): void;
+}

package/dist/overflow_class_manager.js

@@ -0,0 +1,30 @@
+/**
+    Responsible for toggling "[PREFIX][SIDE]" classes on a possibly-overflowing element.
+
+    Nothing project-specific here
+ */
+export class OverflowClassManager {
+    constructor(root, class_prefix) {
+        this.root = root;
+        this.class_prefix = class_prefix;
+    }
+    /**
+        detector _may_ have zero size; that's okay (it _should_ have 0 size in at least one dimension)
+
+        detector _may_ be longer (in one dimension) than root; that's also okay
+
+        detector should be positioned [side]-most inside the root (this is tricky if root has padding).
+
+        If root element can scroll in both directions, you need to be careful about how you setup your detectors. Eg. right detector should either be full-height, or should use sticky positioning so that it never goes completely above or completely below root. The only way right detector should not intersect (at all) with root is if it is to-the-right-of root.
+     */
+    setup_overflow_detector(detector, side) {
+        const class_name = `${this.class_prefix}${side}`;
+        new IntersectionObserver((entries, observer) => {
+            if (entries[0]) {
+                this.root.classList.toggle(class_name, !entries[0].isIntersecting);
+            }
+        }, {
+            root: this.root,
+        }).observe(detector);
+    }
+}

package/dist/overflow_class_manager.ts

@@ -0,0 +1,40 @@
+/**
+    Responsible for toggling "[PREFIX][SIDE]" classes on a possibly-overflowing element.
+
+    Nothing project-specific here
+ */
+export class OverflowClassManager {
+    constructor(
+        readonly root: Element,
+        readonly class_prefix: string,
+    ) {}
+
+    /**
+        detector _may_ have zero size; that's okay (it _should_ have 0 size in at least one dimension)
+
+        detector _may_ be longer (in one dimension) than root; that's also okay
+
+        detector should be positioned [side]-most inside the root (this is tricky if root has padding).
+
+        If root element can scroll in both directions, you need to be careful about how you setup your detectors. Eg. right detector should either be full-height, or should use sticky positioning so that it never goes completely above or completely below root. The only way right detector should not intersect (at all) with root is if it is to-the-right-of root.
+     */
+    setup_overflow_detector(
+        detector: Element,
+        side: "left" | "right" | "top" | "bottom",
+    ) {
+        const class_name = `${this.class_prefix}${side}`;
+        new IntersectionObserver(
+            (entries, observer) => {
+                if (entries[0]) {
+                    this.root.classList.toggle(
+                        class_name,
+                        !entries[0].isIntersecting,
+                    );
+                }
+            },
+            {
+                root: this.root,
+            },
+        ).observe(detector);
+    }
+}

package/dist/renderer.d.ts

@@ -0,0 +1,16 @@
+import m from "mithril";
+export declare class Renderer {
+    /**
+        Given some phrasing content and some help text, return an "augmented" version of that phrasing content with some means of accessing the help text.
+        The help text might be long; it should not take up space on the page.
+        The final rendered result should not be much wider than the initial phrasing content (this may be used inside space-constrained locations, like <th> elements).
+    */
+    render_with_help_text(phrasing_content: m.Children, help: string): m.Vnode<any, any>;
+    render_with_optional_help_text(phrasing_content: m.Children, help: string): m.Children;
+    render_header(args: {
+        label: m.Children;
+        sortable: boolean;
+        sorted: "no" | "forward" | "reverse";
+        set_sort: (direction: "forward" | "reverse") => void;
+    }): m.Vnode<any, any>;
+}

package/dist/renderer.js

@@ -0,0 +1,51 @@
+/*
+    Here we implement a class for performing various low-level rendering operations, which users might want to override (ie. so that the generated markup works better with their stylesheet or to use custom components that are used elsewhere on their site). You should NOT implement a custom Renderer in order to change or add functionality (and we'll do our best with the method signatures/documentation to prevent that).
+*/
+import m from "mithril";
+export class Renderer {
+    /**
+        Given some phrasing content and some help text, return an "augmented" version of that phrasing content with some means of accessing the help text.
+        The help text might be long; it should not take up space on the page.
+        The final rendered result should not be much wider than the initial phrasing content (this may be used inside space-constrained locations, like <th> elements).
+    */
+    render_with_help_text(phrasing_content, help) {
+        return m("span", { title: help }, phrasing_content, m("span", {
+            tabindex: 0,
+            onclick: function (e) {
+                alert(help);
+                // This allows you to render help text inside other interactive elements
+                e.preventDefault();
+                e.stopPropagation();
+            },
+            onkeydown: function (e) {
+                if (e.key == "Enter" || e.key == " ") {
+                    this.click();
+                    // in case you pressed space, don't scroll page
+                    e.preventDefault();
+                }
+            },
+            className: "qnc-data-table-help-text",
+        }));
+    }
+    render_with_optional_help_text(phrasing_content, help) {
+        if (help)
+            return this.render_with_help_text(phrasing_content, help);
+        return phrasing_content;
+    }
+    render_header(args) {
+        // entire header text is a (clickable) button (similar to many file browser and other UIs) :
+        if (args.sortable)
+            return m("button", {
+                onclick: () => args.set_sort(args.sorted == "forward" ? "reverse" : "forward"),
+                className: "qnc-data-table-header-button",
+                type: "button",
+            }, 
+            // The wrapping span is so that you can see (in your browser's dev tools) exactly how wide the button content is, in case you want to fix column width at that width
+            // (note - button _might_ also suffice for this, but users might style button as full-width, for increased click target size)
+            m("span", m("span", { className: "qnc-data-table-header-button-text" }, args.label), args.sorted == "forward" &&
+                m("span", { className: "qnc-data-table-sort-indicator" }, " ▲"), args.sorted == "reverse" &&
+                m("span", { className: "qnc-data-table-sort-indicator" }, " ▼")));
+        // The wrapping span is so that you can see (in your browser's dev tools) exactly how wide the text content is, in case you want to fix column width at that width
+        return m("span", args.label);
+    }
+}

package/dist/renderer.ts

@@ -0,0 +1,86 @@
+/*
+    Here we implement a class for performing various low-level rendering operations, which users might want to override (ie. so that the generated markup works better with their stylesheet or to use custom components that are used elsewhere on their site). You should NOT implement a custom Renderer in order to change or add functionality (and we'll do our best with the method signatures/documentation to prevent that).
+*/
+import m from "mithril";
+
+export class Renderer {
+    /** 
+        Given some phrasing content and some help text, return an "augmented" version of that phrasing content with some means of accessing the help text. 
+        The help text might be long; it should not take up space on the page.
+        The final rendered result should not be much wider than the initial phrasing content (this may be used inside space-constrained locations, like <th> elements).
+    */
+    render_with_help_text(phrasing_content: m.Children, help: string) {
+        return m(
+            "span",
+            { title: help },
+            phrasing_content,
+            m("span", {
+                tabindex: 0,
+                onclick: function (e: MouseEvent) {
+                    alert(help);
+                    // This allows you to render help text inside other interactive elements
+                    e.preventDefault();
+                    e.stopPropagation();
+                },
+                onkeydown: function (e: KeyboardEvent) {
+                    if (e.key == "Enter" || e.key == " ") {
+                        this.click();
+                        // in case you pressed space, don't scroll page
+                        e.preventDefault();
+                    }
+                },
+                className: "qnc-data-table-help-text",
+            }),
+        );
+    }
+    render_with_optional_help_text(phrasing_content: m.Children, help: string) {
+        if (help) return this.render_with_help_text(phrasing_content, help);
+        return phrasing_content;
+    }
+    render_header(args: {
+        label: m.Children;
+        sortable: boolean;
+        sorted: "no" | "forward" | "reverse";
+        set_sort: (direction: "forward" | "reverse") => void;
+    }) {
+        // entire header text is a (clickable) button (similar to many file browser and other UIs) :
+        if (args.sortable)
+            return m(
+                "button",
+                {
+                    onclick: () =>
+                        args.set_sort(
+                            args.sorted == "forward" ? "reverse" : "forward",
+                        ),
+                    className: "qnc-data-table-header-button",
+                    type: "button",
+                },
+
+                // The wrapping span is so that you can see (in your browser's dev tools) exactly how wide the button content is, in case you want to fix column width at that width
+                // (note - button _might_ also suffice for this, but users might style button as full-width, for increased click target size)
+                m(
+                    "span",
+                    m(
+                        "span",
+                        { className: "qnc-data-table-header-button-text" },
+                        args.label,
+                    ),
+                    args.sorted == "forward" &&
+                        m(
+                            "span",
+                            { className: "qnc-data-table-sort-indicator" },
+                            " ▲",
+                        ),
+                    args.sorted == "reverse" &&
+                        m(
+                            "span",
+                            { className: "qnc-data-table-sort-indicator" },
+                            " ▼",
+                        ),
+                ),
+            );
+
+        // The wrapping span is so that you can see (in your browser's dev tools) exactly how wide the text content is, in case you want to fix column width at that width
+        return m("span", args.label);
+    }
+}

package/dist/selection_fieldset_controller.d.ts

@@ -0,0 +1,9 @@
+/**
+    Registers a custom element (<qdt-selection-fieldset-controller>) for wrapping a <fieldset> element.
+    The custom element:
+    - requires a "table-id" attribute to be set, which must be the id of a data table element
+    - dynamically updates the fieldset's "disabled" attribute
+    - dynamically updates the fieldset's legend (to include # of selected items)
+    - provides access to the TableManager of the connected data table
+ */
+export declare function register_selection_fieldset_controller_custom_element(): void;

package/dist/selection_fieldset_controller.js

@@ -0,0 +1,85 @@
+import { BaseQncDataTable } from "./custom_element.js";
+/**
+    Intended to wrap a <fieldset> element of "selection action buttons".
+    Responsible for:
+    - dynamically updating fieldset's "disabled" attribute
+    - dynamically updating fieldset's legend (to include # of selected items)
+    - providing access to the TableManager of the connected data table
+
+    Intended for use when you're generating selection action buttons on your backend (in initial page HTML).
+
+    If you're building selection action buttons on the front-end, this is probably not the best approach.
+ */
+class QdtSelectionFieldsetController extends HTMLElement {
+    constructor() {
+        super();
+        this.fieldset = null;
+        this.legend = null;
+        this.table = null;
+        this.on_selection_change = () => this.render();
+    }
+    connectedCallback() {
+        this.connect_table();
+        this.connect_fieldset();
+        this.render();
+    }
+    static get selected_attributes() {
+        return ["table-id"];
+    }
+    attributeChangedCallback(name, old_value, new_value) {
+        this.connect_table();
+        this.render();
+    }
+    connect_table() {
+        this.table = null;
+        const id = this.getAttribute("table-id");
+        if (!id) {
+            console.error(`${this.tagName} requires "table-id" attribute`);
+            return;
+        }
+        const table = document.getElementById(id);
+        if (!table) {
+            console.error(`"${id}" does not reference any element by id`);
+            return;
+        }
+        if (!(table instanceof BaseQncDataTable)) {
+            console.error(`"${id}" references an HTML element, but it is not a BaseQncDataTable`);
+            return;
+        }
+        this.table = table;
+        this.table
+            .required_table_manager()
+            .add_selected_ids_changed_listener(this.on_selection_change);
+    }
+    connect_fieldset() {
+        this.fieldset = this.querySelector("fieldset");
+        if (!this.fieldset)
+            console.warn("Could not find a fieldset descendant. Our presence is meaningless.");
+        this.legend = this.querySelector("legend");
+    }
+    render() {
+        const selected_count = this.table
+            ? this.table.required_table_manager().selected_ids.size
+            : 0;
+        if (this.fieldset)
+            this.fieldset.disabled = selected_count == 0;
+        if (this.legend)
+            this.legend.innerText = `With ${selected_count} selected item(s):`;
+    }
+    required_table_manager() {
+        if (!this.table)
+            throw new Error("We are not connected to a table");
+        return this.table.required_table_manager();
+    }
+}
+/**
+    Registers a custom element (<qdt-selection-fieldset-controller>) for wrapping a <fieldset> element.
+    The custom element:
+    - requires a "table-id" attribute to be set, which must be the id of a data table element
+    - dynamically updates the fieldset's "disabled" attribute
+    - dynamically updates the fieldset's legend (to include # of selected items)
+    - provides access to the TableManager of the connected data table
+ */
+export function register_selection_fieldset_controller_custom_element() {
+    customElements.define("qdt-selection-fieldset-controller", QdtSelectionFieldsetController);
+}

package/dist/selection_fieldset_controller.ts

@@ -0,0 +1,104 @@
+import { TableManager } from "./table_manager.js";
+import { BaseQncDataTable } from "./custom_element.js";
+
+/**
+    Intended to wrap a <fieldset> element of "selection action buttons".
+    Responsible for:
+    - dynamically updating fieldset's "disabled" attribute
+    - dynamically updating fieldset's legend (to include # of selected items)
+    - providing access to the TableManager of the connected data table
+
+    Intended for use when you're generating selection action buttons on your backend (in initial page HTML).
+
+    If you're building selection action buttons on the front-end, this is probably not the best approach.
+ */
+class QdtSelectionFieldsetController extends HTMLElement {
+    private fieldset: HTMLFieldSetElement | null = null;
+    private legend: HTMLLegendElement | null = null;
+    private table: BaseQncDataTable | null = null;
+
+    private on_selection_change: () => void;
+
+    constructor() {
+        super();
+        this.on_selection_change = () => this.render();
+    }
+
+    connectedCallback() {
+        this.connect_table();
+        this.connect_fieldset();
+        this.render();
+    }
+
+    private static get selected_attributes() {
+        return ["table-id"];
+    }
+
+    attributeChangedCallback(
+        name: string,
+        old_value: string,
+        new_value: string,
+    ) {
+        this.connect_table();
+        this.render();
+    }
+    private connect_table() {
+        this.table = null;
+
+        const id = this.getAttribute("table-id");
+        if (!id) {
+            console.error(`${this.tagName} requires "table-id" attribute`);
+            return;
+        }
+        const table = document.getElementById(id);
+        if (!table) {
+            console.error(`"${id}" does not reference any element by id`);
+            return;
+        }
+        if (!(table instanceof BaseQncDataTable)) {
+            console.error(
+                `"${id}" references an HTML element, but it is not a BaseQncDataTable`,
+            );
+            return;
+        }
+        this.table = table;
+        this.table
+            .required_table_manager()
+            .add_selected_ids_changed_listener(this.on_selection_change);
+    }
+    private connect_fieldset() {
+        this.fieldset = this.querySelector("fieldset");
+        if (!this.fieldset)
+            console.warn(
+                "Could not find a fieldset descendant. Our presence is meaningless.",
+            );
+        this.legend = this.querySelector("legend");
+    }
+    private render() {
+        const selected_count = this.table
+            ? this.table.required_table_manager().selected_ids.size
+            : 0;
+
+        if (this.fieldset) this.fieldset.disabled = selected_count == 0;
+        if (this.legend)
+            this.legend.innerText = `With ${selected_count} selected item(s):`;
+    }
+    required_table_manager(): TableManager {
+        if (!this.table) throw new Error("We are not connected to a table");
+        return this.table.required_table_manager();
+    }
+}
+/**
+    Registers a custom element (<qdt-selection-fieldset-controller>) for wrapping a <fieldset> element.
+    The custom element:
+    - requires a "table-id" attribute to be set, which must be the id of a data table element
+    - dynamically updates the fieldset's "disabled" attribute
+    - dynamically updates the fieldset's legend (to include # of selected items)
+    - provides access to the TableManager of the connected data table
+ */
+export function register_selection_fieldset_controller_custom_element() {
+    customElements.define(
+        "qdt-selection-fieldset-controller",
+        QdtSelectionFieldsetController,
+    );
+}

package/dist/state_machine.d.ts

@@ -0,0 +1,67 @@
+import { AppState, SortState } from "./state_types.js";
+import { TableOptions } from "./table_options.js";
+/**
+    The StateMachine is responsible for aggregating state from 3 sources of information:
+    - table configuration (eg. coming from JS or HTML attributes)
+    - saved user preferences
+    - data fetched from the backend
+
+    It is also responsible for:
+    - providing methods to adjust state
+    - fetching data from the back end
+    - automatically saving any changes of user-configurable "settings" for the table.
+    - dispatching custom events
+ */
+export declare class StateMachine<cell_data_type> {
+    private options;
+    /** This is used to "prepare" cell html from the backend for your UI library of choice */
+    private prepare_cell;
+    private event_target;
+    /** This represents all of the "user settings", EXCEPT those dealing with columns. We delegate the management of those settings to column_manager. */
+    private stored_values;
+    private onchange;
+    private result_count_xhr;
+    private id_list_xhr;
+    private table_data_xhr;
+    private result_count;
+    private accessible_result_count;
+    private id_list;
+    private table_data;
+    private column_manager;
+    private fetched_columns;
+    private valid_sort_keys;
+    after_render: (() => void) | null;
+    private table_overflows_left;
+    private table_overflows_right;
+    private row_width_style_string;
+    constructor(options: TableOptions, 
+    /** This is used to "prepare" cell html from the backend for your UI library of choice */
+    prepare_cell: (html: string, column_key: string) => cell_data_type, event_target: EventTarget, 
+    /** Will be called any time any of our state changes */
+    onchange: (state: AppState<cell_data_type>) => void);
+    on_column_manager_change(): void;
+    /** Get current app state. This will not be needed often, but you might want it for your initial rendering. */
+    get_state(): AppState<cell_data_type>;
+    get_sort_state(): SortState | null;
+    get selected_ids(): ReadonlySet<string>;
+    private setup_result_count_xhr;
+    private setup_id_list_xhr;
+    private setup_page_xhr;
+    private fetch_result_count;
+    private fetch_id_list;
+    private fetch_page;
+    private get num_pages();
+    fetch_data(): void;
+    set_page_size(page_size: number): void;
+    set_page_number(page_number: number): void;
+    set_column_enabled(column_key: string, enabled: boolean): void;
+    set_sort_key(sort_key: string): void;
+    sort_by_function(function_key: string): void;
+    sort_by_column(column_key: string, direction: "forward" | "reverse"): void;
+    set_column_width(column_key: string, width: number): void;
+    /** keys may include all sortable columns, not just the enabled ones */
+    set_column_order(keys: string[]): void;
+    set_selected(pk: string, selected: boolean): void;
+    bulk_set_selected(pks: Iterable<string>, selected: boolean): void;
+    private dispatch_selection_change_event;
+}