@qnc/qnc_data_tables 1.0.4 → 1.0.6-a

package/dist/state_machine.ts

@@ -0,0 +1,434 @@
+import { SELECTION_CHANGE } from "./event_names.js";
+import { AppState, SortState } from "./state_types.js";
+import { TableOptions, get_storage } from "./table_options.js";
+import * as tu from "@qnc/type_utils";
+import { ColumnManager } from "./column_manager.js";
+import * as column_sorting from "./column_sorting.js";
+import {
+    BoundStoredValue,
+    BoundStoredStringSet,
+    NUMBER_CONVERTER,
+    STRING_CONVERTER,
+} from "./bound_stored_value.js";
+import { WatchedMutableValue } from "./watched_mutable_value.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 class StateMachine<cell_data_type> {
+    /** 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: ReturnType<typeof make_bound_stored_values>;
+    private onchange: () => void;
+    private result_count_xhr = new XMLHttpRequest();
+    private id_list_xhr = new XMLHttpRequest();
+    private table_data_xhr = new XMLHttpRequest();
+    private result_count: number | null = null;
+    private accessible_result_count: number | null = null;
+    private id_list: string[] = [];
+    private table_data: [string, Map<string, cell_data_type>][] = [];
+    private column_manager: ColumnManager;
+    private fetched_columns = new Set<string>();
+    private valid_sort_keys: Set<string>;
+    public after_render: (() => void) | null = null;
+    private table_overflows_left: WatchedMutableValue<boolean>;
+    private table_overflows_right: WatchedMutableValue<boolean>;
+    private row_width_style_string: WatchedMutableValue<string>;
+    constructor(
+        private options: TableOptions,
+        /** This is used to "prepare" cell html from the backend for your UI library of choice */
+        private prepare_cell: (
+            html: string,
+            column_key: string,
+        ) => cell_data_type,
+        private event_target: EventTarget,
+        /** Will be called any time any of our state changes */
+        onchange: (state: AppState<cell_data_type>) => void,
+    ) {
+        this.column_manager = new ColumnManager(
+            options.columns,
+            get_storage(options.layout_storage),
+            options.key_prefix + "_columns",
+            this.on_column_manager_change,
+        );
+        this.stored_values = make_bound_stored_values(options);
+        this.onchange = () => onchange(this.get_state());
+
+        this.table_overflows_left = new WatchedMutableValue(
+            false,
+            this.onchange,
+        );
+        this.table_overflows_right = new WatchedMutableValue(
+            false,
+            this.onchange,
+        );
+        this.row_width_style_string = new WatchedMutableValue(
+            "",
+            this.onchange,
+        );
+
+        this.setup_result_count_xhr(this.result_count_xhr);
+        this.setup_id_list_xhr(this.id_list_xhr);
+        this.setup_page_xhr(this.table_data_xhr);
+
+        this.valid_sort_keys = new Set();
+        for (const sort_function of options.extra_sort_functions) {
+            this.valid_sort_keys.add(
+                column_sorting.make_function_sort_key(sort_function.key),
+            );
+        }
+        for (const column of options.columns) {
+            if (!column.sortable) continue;
+            this.valid_sort_keys.add(
+                column_sorting.make_column_sort_key(column.key, "forward"),
+            );
+            this.valid_sort_keys.add(
+                column_sorting.make_column_sort_key(column.key, "reverse"),
+            );
+        }
+
+        this.fetch_data();
+    }
+
+    on_column_manager_change() {}
+
+    /** 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> {
+        return {
+            page_number: this.stored_values.page_number.value,
+            selected_pks: this.stored_values.selected_pks.value,
+            filtered_pks: this.id_list,
+            result_count: this.result_count,
+            page_limit: this.options.page_limit,
+            table_limit: this.options.table_limit,
+            fetching_page_data:
+                is_loading(this.id_list_xhr) || is_loading(this.table_data_xhr),
+            fetching_result_count: is_loading(this.result_count_xhr),
+            columns: this.column_manager,
+
+            // Note: now that we've added current_sort, this could be replaced
+            sort_state_interpreter: (column_key: string) =>
+                column_sorting.current_sort_direction(
+                    column_key,
+                    this.stored_values.sort_key.value,
+                ),
+
+            table_data: this.table_data,
+            fill_last_page: this.options.fill_last_page,
+            page_size: this.stored_values.page_size.value,
+            accessible_result_count: this.accessible_result_count,
+            fetching_accessible_result_count: is_loading(this.id_list_xhr),
+            table_key: this.options.key_prefix,
+            include_selection_column: this.options.allow_selection,
+            table_overflows_left: this.table_overflows_left,
+            table_overflows_right: this.table_overflows_right,
+            row_width_style_string: this.row_width_style_string,
+            current_sort: this.get_sort_state(),
+            extra_sort_functions: this.options.extra_sort_functions,
+        };
+    }
+    get_sort_state(): SortState | null {
+        try {
+            return column_sorting.parse_sort_key(
+                this.stored_values.sort_key.value,
+            );
+        } catch (e) {
+            console.error(e);
+            return null;
+        }
+    }
+
+    get selected_ids(): ReadonlySet<string> {
+        return this.stored_values.selected_pks.value;
+    }
+
+    private setup_result_count_xhr(xhr: XMLHttpRequest) {
+        xhr.onload = (e: ProgressEvent) => {
+            if (xhr.status != 200) {
+                log_error(xhr);
+                this.onchange();
+                return;
+            }
+
+            const data = tu.require_string_map(tu.parse_json(xhr.responseText));
+            this.result_count = tu.require_number(data.count);
+            this.onchange();
+        };
+        xhr.onerror = () => {
+            log_error(xhr);
+            this.onchange();
+        };
+    }
+    private setup_id_list_xhr(xhr: XMLHttpRequest) {
+        xhr.onload = () => {
+            if (xhr.status != 200) {
+                log_error(xhr);
+                this.onchange();
+                return;
+            }
+
+            const data = tu.require_string_map(tu.parse_json(xhr.responseText));
+            this.id_list = tu.require_array(data.ids).map(tu.require_string);
+            this.accessible_result_count = this.id_list.length;
+
+            this.onchange();
+            this.fetch_page();
+        };
+        xhr.onerror = () => {
+            log_error(xhr);
+            this.onchange();
+        };
+    }
+    private setup_page_xhr(xhr: XMLHttpRequest) {
+        xhr.onload = () => {
+            if (xhr.status != 200) {
+                log_error(xhr);
+                this.onchange();
+                return;
+            }
+
+            const data = tu.require_string_map(tu.parse_json(xhr.responseText));
+            this.table_data = tu.require_array(data.rows).map((row) => {
+                if (!tu.is_2_tuple(row))
+                    throw new Error("row data not an array");
+                const pk = tu.require_string(row[0]);
+                const cell_data = tu.require_array(row[1]);
+
+                const cells = new Map<string, cell_data_type>();
+
+                for (const column of cell_data) {
+                    // const array = tu.require_array(column)
+                    // column
+
+                    const [column_key, html] = tu.require_2_tuple(column);
+
+                    tu.assert_string(column_key);
+                    tu.assert_string(html);
+
+                    cells.set(column_key, this.prepare_cell(html, column_key));
+                }
+
+                return [pk, cells];
+            });
+
+            this.onchange();
+        };
+        xhr.onerror = () => {
+            log_error(xhr);
+            this.onchange();
+        };
+    }
+
+    private fetch_result_count() {
+        const data = get_filter_form_data(this.options.filter_form_id);
+        data.append(`${this.options.key_prefix}_action`, "get_result_count");
+
+        this.result_count_xhr.open("POST", this.options.api_url);
+        this.result_count_xhr.send(data);
+
+        this.onchange();
+    }
+    private fetch_id_list() {
+        const data = get_filter_form_data(this.options.filter_form_id);
+        data.append(`${this.options.key_prefix}_action`, "get_ids");
+        if (this.stored_values.sort_key.value) {
+            data.append(
+                `${this.options.key_prefix}_sort_key`,
+                this.stored_values.sort_key.value,
+            );
+        }
+
+        this.id_list_xhr.open("POST", this.options.api_url);
+        this.id_list_xhr.send(data);
+
+        this.onchange();
+    }
+    private fetch_page() {
+        // Note - most pages won't need data from filter_form to return results
+        // However, some pages MAY include controls in the filter_form which impact how the columns/data are generated
+        // It's part of our documented contract that we always submit filter_form data with each post request
+        const data = get_filter_form_data(this.options.filter_form_id);
+        data.append(`${this.options.key_prefix}_action`, "get_table_data");
+
+        const column_keys = this.column_manager.all_enabled_columns.map(
+            (c) => c.key,
+        );
+        this.fetched_columns = new Set(column_keys);
+
+        data.append(
+            `${this.options.key_prefix}_columns`,
+            JSON.stringify(column_keys),
+        );
+        const page_size = this.stored_values.page_size.value;
+        const start_index =
+            (this.stored_values.page_number.value - 1) * page_size;
+        data.append(
+            `${this.options.key_prefix}_ids`,
+            JSON.stringify(
+                this.id_list.slice(start_index, start_index + page_size),
+            ),
+        );
+
+        this.table_data_xhr.open("POST", this.options.api_url);
+        this.table_data_xhr.send(data);
+    }
+
+    private get num_pages() {
+        return Math.ceil(
+            this.id_list.length / this.stored_values.page_size.value,
+        );
+    }
+
+    fetch_data() {
+        this.fetch_result_count();
+        this.fetch_id_list();
+    }
+    set_page_size(page_size: number) {
+        this.stored_values.page_size.value = Math.min(
+            page_size,
+            this.options.page_limit,
+        );
+        this.onchange();
+    }
+    set_page_number(page_number: number) {
+        this.stored_values.page_number.value = Math.min(
+            page_number,
+            this.num_pages,
+        );
+        this.fetch_page();
+        this.onchange();
+    }
+    set_column_enabled(column_key: string, enabled: boolean) {
+        this.column_manager.set_enabled(column_key, enabled);
+        if (enabled && !this.fetched_columns.has(column_key)) this.fetch_page();
+        this.onchange();
+    }
+    set_sort_key(sort_key: string) {
+        console.assert(this.valid_sort_keys.has(sort_key));
+        this.stored_values.sort_key.value = sort_key;
+        this.fetch_data();
+        this.onchange();
+    }
+    sort_by_function(function_key: string) {
+        this.set_sort_key(column_sorting.make_function_sort_key(function_key));
+    }
+    sort_by_column(column_key: string, direction: "forward" | "reverse") {
+        this.set_sort_key(
+            column_sorting.make_column_sort_key(column_key, direction),
+        );
+    }
+    set_column_width(column_key: string, width: number) {
+        this.column_manager.set_width(column_key, width);
+        this.onchange();
+    }
+
+    /** keys may include all sortable columns, not just the enabled ones */
+    set_column_order(keys: string[]) {
+        this.column_manager.set_order(keys);
+        this.onchange();
+    }
+
+    set_selected(pk: string, selected: boolean) {
+        const set = this.stored_values.selected_pks;
+        if (selected) set.add(pk);
+        else set.delete(pk);
+        this.onchange();
+        this.dispatch_selection_change_event();
+    }
+
+    bulk_set_selected(pks: Iterable<string>, selected: boolean) {
+        const set = new Set(this.stored_values.selected_pks.value);
+        if (selected) {
+            for (const value of pks) {
+                set.add(value);
+            }
+        } else {
+            for (const value of pks) {
+                set.delete(value);
+            }
+        }
+        this.stored_values.selected_pks.value = set;
+        this.onchange();
+        this.dispatch_selection_change_event();
+    }
+
+    private dispatch_selection_change_event() {
+        this.event_target.dispatchEvent(new CustomEvent(SELECTION_CHANGE));
+    }
+}
+
+function is_loading(xhr: XMLHttpRequest) {
+    return xhr.readyState != 4;
+}
+function log_error(xhr: XMLHttpRequest) {
+    /* 
+    Always log the error but don't alert when status == 0, statusText == "" and responseText == "" because Safari
+    returns those conditions when a request is interrupted by the user making another request (navigating away) and we don't want to show
+    an empty alert. 
+    These conditions are also met when there is a network failure. Ideally, we _would_ alert the user to that case in some way, but I'm not sure how to differentiate between the two.
+    */
+    console.warn("qnc_data_tables xhr error: ", xhr);
+    if (xhr.status != 0 || xhr.statusText != "" || xhr.responseText != "") {
+        alert("Data table error: " + xhr.responseText || xhr.statusText);
+    }
+}
+function get_filter_form(id: string): HTMLFormElement | null {
+    if (!id) return null;
+    const form = document.getElementById(id);
+    if (!(form instanceof HTMLFormElement))
+        throw new Error(`ID "${id}" does not reference a <form> on this page`);
+    return form;
+}
+/** Return a new FormData associate with the filter form if one is specified, else a new empty FormData */
+function get_filter_form_data(id: string): FormData {
+    const form = get_filter_form(id);
+    if (form) return new FormData(form);
+    return new FormData();
+}
+
+/**
+    Read TableOptions and make various BoundStoredValues that always save to correct storage "area" when updated
+
+    Note that this 
+ */
+function make_bound_stored_values(options: TableOptions) {
+    const { key_prefix } = options;
+
+    const selection_storage = get_storage(options.selection_storage);
+    const navigation_storage = get_storage(options.navigation_storage);
+    const layout_storage = get_storage(options.layout_storage);
+    const sort_storage = get_storage(options.sort_storage);
+
+    return {
+        page_number: new BoundStoredValue(
+            navigation_storage,
+            key_prefix + "_page",
+            NUMBER_CONVERTER,
+            1,
+        ),
+        page_size: new BoundStoredValue(
+            layout_storage,
+            key_prefix + "_page_size",
+            NUMBER_CONVERTER,
+            options.page_size,
+        ),
+        selected_pks: new BoundStoredStringSet(
+            selection_storage,
+            key_prefix + "_selected",
+        ),
+        sort_key: new BoundStoredValue(
+            sort_storage,
+            key_prefix + "_sort",
+            STRING_CONVERTER,
+            column_sorting.encode_sort(options.default_sort),
+        ),
+    };
+}

package/dist/state_types.d.ts

@@ -0,0 +1,62 @@
+import { ExtraSortFunction } from "./table_options.js";
+import { ConfiguredColumns } from "./column_manager.js";
+import { WatchedMutableValue } from "./watched_mutable_value.js";
+/**
+    A SortStateInterpreter takes a column key and identifies whether we are currently:
+    - sorting by that column, in the forward direction ('forward')
+    - sorting by that column, in the reverse direction ('reverse')
+    - not sorting by that column (null)
+ */
+export type SortStateInterpreter = (column_key: string) => "forward" | "reverse" | null;
+export type SortState = {
+    type: "function";
+    function_key: string;
+} | {
+    type: "column";
+    column_key: string;
+    direction: "forward" | "reverse";
+};
+/**
+    This should contain EVERYTHING needed to render a non-interactive version of the UI, at a point in time. This includes:
+    - fixed values read from "configuration"
+    - user controlled settings
+    - data fetched from backend
+
+    AppState does NOT contain any callback functions (for updating state). Those are implemented by StateMachine.
+    Actually, AppState MAY store some simple callback/update functions, in the form of WatchedMutableValues.
+    That's really only intended for simple things that are computed from the rendered layout, and which only affect other aspects of the rendered layout (ie. no other logic will likely be needed in response to updating the value).
+*/
+export type AppState<cell_data_type> = Readonly<{
+    /**
+        Must be unique across all data tables on a given page (used in constructing CSS classes).
+    */
+    table_key: string;
+    page_number: number;
+    selected_pks: ReadonlySet<string>;
+    filtered_pks: string[];
+    /** null means we have not yet fetched any result count; should only occur before first result_count becomes available */
+    result_count: number | null;
+    /** Will generally be the same as result_count. MAY be less, if backend decides it's too expensive to return that many ids. */
+    accessible_result_count: number | null;
+    page_limit: number;
+    table_limit: number;
+    fill_last_page: boolean;
+    page_size: number;
+    /** indicates that we are fetching the total result count; any current result_count value is "stale" */
+    fetching_result_count: boolean;
+    /** indicates that we are fetching the list of matching ids; any current accessible_result_count is "stale"  */
+    fetching_accessible_result_count: boolean;
+    fetching_page_data: boolean;
+    columns: ConfiguredColumns;
+    sort_state_interpreter: (column_key: string) => "forward" | "reverse" | null;
+    current_sort: SortState | null;
+    extra_sort_functions: ExtraSortFunction[];
+    table_data: ReadonlyArray<Readonly<[
+        string,
+        ReadonlyMap<string, cell_data_type>
+    ]>>;
+    include_selection_column: boolean;
+    table_overflows_left: WatchedMutableValue<boolean>;
+    table_overflows_right: WatchedMutableValue<boolean>;
+    row_width_style_string: WatchedMutableValue<string>;
+}>;

package/dist/state_types.js

@@ -0,0 +1 @@
+export {};

package/dist/state_types.ts

@@ -0,0 +1,84 @@
+import { ExtraSortFunction } from "./table_options.js";
+import { ConfiguredColumns } from "./column_manager.js";
+import { WatchedMutableValue } from "./watched_mutable_value.js";
+
+/**
+    A SortStateInterpreter takes a column key and identifies whether we are currently:
+    - sorting by that column, in the forward direction ('forward')
+    - sorting by that column, in the reverse direction ('reverse')
+    - not sorting by that column (null)
+ */
+export type SortStateInterpreter = (
+    column_key: string,
+) => "forward" | "reverse" | null;
+
+export type SortState =
+    | {
+          type: "function";
+          function_key: string;
+      }
+    | {
+          type: "column";
+          column_key: string;
+          direction: "forward" | "reverse";
+      };
+
+/** 
+    This should contain EVERYTHING needed to render a non-interactive version of the UI, at a point in time. This includes:
+    - fixed values read from "configuration"
+    - user controlled settings
+    - data fetched from backend
+
+    AppState does NOT contain any callback functions (for updating state). Those are implemented by StateMachine.
+    Actually, AppState MAY store some simple callback/update functions, in the form of WatchedMutableValues.
+    That's really only intended for simple things that are computed from the rendered layout, and which only affect other aspects of the rendered layout (ie. no other logic will likely be needed in response to updating the value).
+*/
+
+export type AppState<cell_data_type> = Readonly<{
+    /** 
+        Must be unique across all data tables on a given page (used in constructing CSS classes).
+    */
+    table_key: string;
+    page_number: number;
+    selected_pks: ReadonlySet<string>;
+    filtered_pks: string[];
+    /** null means we have not yet fetched any result count; should only occur before first result_count becomes available */
+    result_count: number | null;
+    /** Will generally be the same as result_count. MAY be less, if backend decides it's too expensive to return that many ids. */
+    accessible_result_count: number | null;
+    page_limit: number;
+    table_limit: number;
+    fill_last_page: boolean;
+    page_size: number;
+    /** indicates that we are fetching the total result count; any current result_count value is "stale" */
+    fetching_result_count: boolean;
+    /** indicates that we are fetching the list of matching ids; any current accessible_result_count is "stale"  */
+    fetching_accessible_result_count: boolean;
+    fetching_page_data: boolean;
+    columns: ConfiguredColumns;
+
+    // note: now that we have current_sort, this is rather redundant
+    sort_state_interpreter: (
+        column_key: string,
+    ) => "forward" | "reverse" | null;
+
+    current_sort: SortState | null;
+    extra_sort_functions: ExtraSortFunction[];
+
+    table_data: ReadonlyArray<
+        // array of rows
+        Readonly<
+            [
+                string, // the pk of the row
+                ReadonlyMap<string, cell_data_type>, // column_key => cell data
+            ]
+        >
+    >;
+    include_selection_column: boolean;
+
+    // Note: this approach was implemented after mithril_view.HeaderComponent
+    // That component could have taken this approach (for "sticky_style_string") and it would not have needed to be stateful
+    table_overflows_left: WatchedMutableValue<boolean>;
+    table_overflows_right: WatchedMutableValue<boolean>;
+    row_width_style_string: WatchedMutableValue<string>;
+}>;

package/dist/table_manager.d.ts

@@ -0,0 +1,9 @@
+import { StateMachine } from "./state_machine.js";
+export declare class TableManager {
+    private readonly state_machine;
+    private event_target;
+    constructor(state_machine: StateMachine<any>, event_target: EventTarget);
+    add_selected_ids_changed_listener(callback: () => void): void;
+    remove_selected_ids_changed_listener(callback: () => void): void;
+    get selected_ids(): ReadonlySet<string>;
+}

package/dist/table_manager.js

@@ -0,0 +1,16 @@
+import { SELECTION_CHANGE } from "./event_names.js";
+export class TableManager {
+    constructor(state_machine, event_target) {
+        this.state_machine = state_machine;
+        this.event_target = event_target;
+    }
+    add_selected_ids_changed_listener(callback) {
+        this.event_target.addEventListener(SELECTION_CHANGE, callback);
+    }
+    remove_selected_ids_changed_listener(callback) {
+        this.event_target.removeEventListener(SELECTION_CHANGE, callback);
+    }
+    get selected_ids() {
+        return this.state_machine.selected_ids;
+    }
+}

package/dist/table_manager.ts

@@ -0,0 +1,28 @@
+import { StateMachine } from "./state_machine.js";
+import { SELECTION_CHANGE } from "./event_names.js";
+
+export class TableManager {
+    constructor(
+        private readonly state_machine: StateMachine<any>,
+        private event_target: EventTarget,
+    ) {}
+
+    add_selected_ids_changed_listener(callback: () => void) {
+        this.event_target.addEventListener(SELECTION_CHANGE, callback);
+    }
+    remove_selected_ids_changed_listener(callback: () => void) {
+        this.event_target.removeEventListener(SELECTION_CHANGE, callback);
+    }
+
+    get selected_ids(): ReadonlySet<string> {
+        return this.state_machine.selected_ids;
+    }
+    // Things we might want to implement:
+    // select(id: string, selected: boolean) {}
+    // set_selected(ids: ReadonlySet<string>) {}
+    // get table_id(): string {}
+    // reload() {}
+    // clear_selection() {}
+    // post_ids_to_new_window(url: string) {}
+    // post_ids_to_window_named(name: string, url: string) {}
+}