@qnc/qnc_data_tables 1.0.3 → 1.0.6-a

package/dist/state_machine.js

@@ -0,0 +1,316 @@
+import { SELECTION_CHANGE } from "./event_names.js";
+import { 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 {
+    constructor(options, 
+    /** This is used to "prepare" cell html from the backend for your UI library of choice */
+    prepare_cell, event_target, 
+    /** Will be called any time any of our state changes */
+    onchange) {
+        this.options = options;
+        this.prepare_cell = prepare_cell;
+        this.event_target = event_target;
+        this.result_count_xhr = new XMLHttpRequest();
+        this.id_list_xhr = new XMLHttpRequest();
+        this.table_data_xhr = new XMLHttpRequest();
+        this.result_count = null;
+        this.accessible_result_count = null;
+        this.id_list = [];
+        this.table_data = [];
+        this.fetched_columns = new Set();
+        this.after_render = null;
+        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() {
+        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) => 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() {
+        try {
+            return column_sorting.parse_sort_key(this.stored_values.sort_key.value);
+        }
+        catch (e) {
+            console.error(e);
+            return null;
+        }
+    }
+    get selected_ids() {
+        return this.stored_values.selected_pks.value;
+    }
+    setup_result_count_xhr(xhr) {
+        xhr.onload = (e) => {
+            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();
+        };
+    }
+    setup_id_list_xhr(xhr) {
+        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();
+        };
+    }
+    setup_page_xhr(xhr) {
+        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();
+                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();
+        };
+    }
+    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();
+    }
+    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();
+    }
+    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);
+    }
+    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) {
+        this.stored_values.page_size.value = Math.min(page_size, this.options.page_limit);
+        this.onchange();
+    }
+    set_page_number(page_number) {
+        this.stored_values.page_number.value = Math.min(page_number, this.num_pages);
+        this.fetch_page();
+        this.onchange();
+    }
+    set_column_enabled(column_key, enabled) {
+        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) {
+        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) {
+        this.set_sort_key(column_sorting.make_function_sort_key(function_key));
+    }
+    sort_by_column(column_key, direction) {
+        this.set_sort_key(column_sorting.make_column_sort_key(column_key, direction));
+    }
+    set_column_width(column_key, width) {
+        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) {
+        this.column_manager.set_order(keys);
+        this.onchange();
+    }
+    set_selected(pk, selected) {
+        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, selected) {
+        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();
+    }
+    dispatch_selection_change_event() {
+        this.event_target.dispatchEvent(new CustomEvent(SELECTION_CHANGE));
+    }
+}
+function is_loading(xhr) {
+    return xhr.readyState != 4;
+}
+function log_error(xhr) {
+    /*
+    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) {
+    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) {
+    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) {
+    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)),
+    };
+}