@qnc/qnc_data_tables 1.0.3 → 1.0.6-a

package/README.md

@@ -0,0 +1,36 @@
+# Basic usage
+
+```ts
+import * as qdt from "@qnc/qnc_data_tables.js";
+// You can also subclass Renderer and override any of the methods, then use that
+qdt.define_custom_element("qnc-data-table", new qdt.Renderer());
+// now any <qnc-data-table> elements will automatically be handled
+```
+
+## Setting up our styles
+
+```ts
+import * as qdt from "@qnc/qnc_data_tables.js";
+document.head.appendChild(qdt.create_style());
+```
+
+Note: in the future, we might provide a css file which you can host/inject as you see fit. For now, this is the only supported technique.
+
+## Filter Forms
+
+By connecting a data table to a form (via the `filter_form_id` configuration parameter), we'll submit that form's data every time we refresh the table. We'll also refresh the table every time the filter form dispatches a `submit` event. We do NOT, however:
+
+- call `preventDefault()` on the form's submit event (you definitely need to this)
+- automatically trigger the form to submit at any time (you might want to trigger the form to submit on every change, or even every input)
+
+## Selection actions
+
+qnc-data-table elements do not render any kind of "selection action buttons" (ie. things that can be _done_ with the selected items). These elements do expose a TableManager, however, which you can use to implement your selction actions.
+
+If you want to define your selection action buttons in your backend (ie. initial page html), we recommend using register_selection_fieldset_controller_custom_element.
+
+
+## TODO
+
+- Move column controls into top control bar, use qnc-dialog instead of details
+- clean up styling, document how to customize (use custom css properties on the root element?)

package/dist/bound_stored_value.d.ts

@@ -0,0 +1,39 @@
+/**
+    Creates simple objects that wrap a single value, and persist that value to some type of Storage every time the value is updated.
+
+    Different "Converters" can be written to store different value types. Stored types should ideally be immutable. Any attempt to _replace_ the wrapper's value will cause stored value to be updated, but _mutating_ the wrapper's value will not.
+ */
+export type Converter<T> = {
+    /** may also throw an error */
+    decode: (value: string) => T;
+    encode: (value: T) => string;
+};
+export declare const NUMBER_CONVERTER: Converter<number>;
+export declare const STRING_CONVERTER: Converter<string>;
+export declare const STRING_ARRAY_CONVERTER: Converter<string[]>;
+export declare const STRING_NUMBER_MAP_CONVERTER: Converter<ReadonlyMap<string, number>>;
+export declare const STRING_SET_CONVERTER: Converter<ReadonlySet<string>>;
+export declare class BoundStoredValue<T> {
+    #private;
+    private storage;
+    private key;
+    private converter;
+    private default_value;
+    constructor(storage: Storage | null, key: string, converter: Converter<T>, default_value: T);
+    get value(): T;
+    set value(value: T);
+}
+/**
+    Similar to a BoundStoredValue<ReadonlySet<string>>, but with some extra convenience methods for mutating the set.
+ */
+export declare class BoundStoredStringSet {
+    #private;
+    private storage;
+    private key;
+    constructor(storage: Storage | null, key: string);
+    get value(): ReadonlySet<string>;
+    set value(value: ReadonlySet<string>);
+    add(value: string): void;
+    delete(value: string): void;
+    clear(value: string): void;
+}

package/dist/bound_stored_value.js

@@ -0,0 +1,134 @@
+/**
+    Creates simple objects that wrap a single value, and persist that value to some type of Storage every time the value is updated.
+
+    Different "Converters" can be written to store different value types. Stored types should ideally be immutable. Any attempt to _replace_ the wrapper's value will cause stored value to be updated, but _mutating_ the wrapper's value will not.
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+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 _BoundStoredValue_value, _BoundStoredStringSet_instances, _BoundStoredStringSet_set, _BoundStoredStringSet_save;
+import * as tu from "@qnc/type_utils";
+export const NUMBER_CONVERTER = {
+    // encode(value) {return value.toString()}
+    encode: JSON.stringify,
+    decode(value) {
+        return tu.require_number(tu.parse_json(value));
+    },
+};
+export const STRING_CONVERTER = {
+    encode: JSON.stringify,
+    decode(value) {
+        return tu.require_string(tu.parse_json(value));
+    },
+};
+export const STRING_ARRAY_CONVERTER = {
+    encode: JSON.stringify,
+    decode(value) {
+        return tu.require_array(tu.parse_json(value)).map(tu.require_string);
+    },
+};
+export const STRING_NUMBER_MAP_CONVERTER = {
+    encode(value) {
+        return JSON.stringify(Array.from(value.entries()));
+    },
+    decode(value) {
+        const map = new Map();
+        for (const row of tu.require_array(tu.parse_json(value))) {
+            const [key, value] = tu.require_2_tuple(row);
+            map.set(tu.require_string(key), tu.require_number(value));
+        }
+        return map;
+    },
+};
+export const STRING_SET_CONVERTER = {
+    encode(value) {
+        return JSON.stringify(Array.from(value));
+    },
+    decode(value) {
+        return new Set(tu.require_array(tu.parse_json(value)).map(tu.require_string));
+    },
+};
+export class BoundStoredValue {
+    constructor(storage, key, converter, default_value) {
+        this.storage = storage;
+        this.key = key;
+        this.converter = converter;
+        this.default_value = default_value;
+        _BoundStoredValue_value.set(this, void 0);
+        __classPrivateFieldSet(this, _BoundStoredValue_value, read(storage, key, this.converter.decode, default_value), "f");
+    }
+    get value() {
+        return __classPrivateFieldGet(this, _BoundStoredValue_value, "f");
+    }
+    set value(value) {
+        __classPrivateFieldSet(this, _BoundStoredValue_value, value, "f");
+        if (this.storage) {
+            this.storage.setItem(this.key, this.converter.encode(value));
+        }
+    }
+}
+_BoundStoredValue_value = new WeakMap();
+/**
+    Similar to a BoundStoredValue<ReadonlySet<string>>, but with some extra convenience methods for mutating the set.
+ */
+export class BoundStoredStringSet {
+    constructor(storage, key) {
+        _BoundStoredStringSet_instances.add(this);
+        this.storage = storage;
+        this.key = key;
+        _BoundStoredStringSet_set.set(this, void 0);
+        __classPrivateFieldSet(this, _BoundStoredStringSet_set, read(this.storage, this.key, function (value) {
+            return new Set(tu
+                .require_array(tu.parse_json(value))
+                .map(tu.require_string));
+        }, new Set([])), "f");
+    }
+    // Important: we return a ReadonlySet!
+    get value() {
+        return __classPrivateFieldGet(this, _BoundStoredStringSet_set, "f");
+    }
+    set value(value) {
+        __classPrivateFieldSet(this, _BoundStoredStringSet_set, new Set(value), "f");
+        __classPrivateFieldGet(this, _BoundStoredStringSet_instances, "m", _BoundStoredStringSet_save).call(this);
+    }
+    // Convenience methods, so you don't have to pass in an entirely new set
+    add(value) {
+        __classPrivateFieldGet(this, _BoundStoredStringSet_set, "f").add(value);
+        __classPrivateFieldGet(this, _BoundStoredStringSet_instances, "m", _BoundStoredStringSet_save).call(this);
+    }
+    delete(value) {
+        __classPrivateFieldGet(this, _BoundStoredStringSet_set, "f").delete(value);
+        __classPrivateFieldGet(this, _BoundStoredStringSet_instances, "m", _BoundStoredStringSet_save).call(this);
+    }
+    clear(value) {
+        __classPrivateFieldGet(this, _BoundStoredStringSet_set, "f").clear();
+        __classPrivateFieldGet(this, _BoundStoredStringSet_instances, "m", _BoundStoredStringSet_save);
+    }
+}
+_BoundStoredStringSet_set = new WeakMap(), _BoundStoredStringSet_instances = new WeakSet(), _BoundStoredStringSet_save = function _BoundStoredStringSet_save() {
+    if (this.storage) {
+        this.storage.setItem(this.key, STRING_SET_CONVERTER.encode(__classPrivateFieldGet(this, _BoundStoredStringSet_set, "f")));
+    }
+};
+function read(storage, key, from_string, default_value) {
+    if (!storage)
+        return default_value;
+    const value = storage.getItem(key);
+    if (value === null)
+        return default_value;
+    try {
+        return from_string(value);
+    }
+    catch (e) {
+        console.error(`Received value "${value}" for key "${key}" but not convert to correct type. Using default value instead.`);
+        return default_value;
+    }
+}

package/dist/bound_stored_value.ts

@@ -0,0 +1,158 @@
+/**
+    Creates simple objects that wrap a single value, and persist that value to some type of Storage every time the value is updated.
+
+    Different "Converters" can be written to store different value types. Stored types should ideally be immutable. Any attempt to _replace_ the wrapper's value will cause stored value to be updated, but _mutating_ the wrapper's value will not.
+ */
+
+import * as tu from "@qnc/type_utils";
+
+export type Converter<T> = {
+    /** may also throw an error */
+    decode: (value: string) => T;
+    encode: (value: T) => string;
+};
+export const NUMBER_CONVERTER: Converter<number> = {
+    // encode(value) {return value.toString()}
+    encode: JSON.stringify,
+    decode(value) {
+        return tu.require_number(tu.parse_json(value));
+    },
+};
+export const STRING_CONVERTER: Converter<string> = {
+    encode: JSON.stringify,
+    decode(value) {
+        return tu.require_string(tu.parse_json(value));
+    },
+};
+export const STRING_ARRAY_CONVERTER: Converter<string[]> = {
+    encode: JSON.stringify,
+    decode(value) {
+        return tu.require_array(tu.parse_json(value)).map(tu.require_string);
+    },
+};
+export const STRING_NUMBER_MAP_CONVERTER: Converter<
+    ReadonlyMap<string, number>
+> = {
+    encode(value) {
+        return JSON.stringify(Array.from(value.entries()));
+    },
+    decode(value) {
+        const map = new Map<string, number>();
+        for (const row of tu.require_array(tu.parse_json(value))) {
+            const [key, value] = tu.require_2_tuple(row);
+            map.set(tu.require_string(key), tu.require_number(value));
+        }
+        return map;
+    },
+};
+export const STRING_SET_CONVERTER: Converter<ReadonlySet<string>> = {
+    encode(value: ReadonlySet<string>) {
+        return JSON.stringify(Array.from(value));
+    },
+    decode(value: string) {
+        return new Set(
+            tu.require_array(tu.parse_json(value)).map(tu.require_string),
+        );
+    },
+};
+
+export class BoundStoredValue<T> {
+    #value: T;
+
+    constructor(
+        private storage: Storage | null,
+        private key: string,
+        private converter: Converter<T>,
+        private default_value: T,
+    ) {
+        this.#value = read(storage, key, this.converter.decode, default_value);
+    }
+
+    get value() {
+        return this.#value;
+    }
+
+    set value(value: T) {
+        this.#value = value;
+        if (this.storage) {
+            this.storage.setItem(this.key, this.converter.encode(value));
+        }
+    }
+}
+
+/**
+    Similar to a BoundStoredValue<ReadonlySet<string>>, but with some extra convenience methods for mutating the set.
+ */
+export class BoundStoredStringSet {
+    #set: Set<string>;
+
+    constructor(
+        private storage: Storage | null,
+        private key: string,
+    ) {
+        this.#set = read(
+            this.storage,
+            this.key,
+            function (value: string) {
+                return new Set(
+                    tu
+                        .require_array(tu.parse_json(value))
+                        .map(tu.require_string),
+                );
+            },
+            new Set([]),
+        );
+    }
+
+    // Important: we return a ReadonlySet!
+    get value(): ReadonlySet<string> {
+        return this.#set;
+    }
+
+    set value(value: ReadonlySet<string>) {
+        this.#set = new Set(value);
+        this.#save();
+    }
+
+    // Convenience methods, so you don't have to pass in an entirely new set
+    add(value: string) {
+        this.#set.add(value);
+        this.#save();
+    }
+    delete(value: string) {
+        this.#set.delete(value);
+        this.#save();
+    }
+    clear(value: string) {
+        this.#set.clear();
+        this.#save;
+    }
+
+    #save() {
+        if (this.storage) {
+            this.storage.setItem(
+                this.key,
+                STRING_SET_CONVERTER.encode(this.#set),
+            );
+        }
+    }
+}
+
+function read<T>(
+    storage: Storage | null,
+    key: string,
+    from_string: (value: string) => T,
+    default_value: T,
+): T {
+    if (!storage) return default_value;
+    const value = storage.getItem(key);
+    if (value === null) return default_value;
+    try {
+        return from_string(value);
+    } catch (e) {
+        console.error(
+            `Received value "${value}" for key "${key}" but not convert to correct type. Using default value instead.`,
+        );
+        return default_value;
+    }
+}

package/dist/column_manager.d.ts

@@ -0,0 +1,43 @@
+import { Column } from "./table_options.js";
+/**
+    Responsible for
+    - reading TableOptions.columns and then interpreting and updating user's stored preferences
+ */
+export declare class ColumnManager {
+    #private;
+    private columns;
+    private storage;
+    private storage_key;
+    on_any_change: () => void;
+    constructor(columns: Column[], storage: Storage | null, storage_key: string, on_any_change: () => void);
+    /** returns them in display order */
+    get all_enabled_columns(): ColumnList;
+    /** returns them in display order */
+    get fixed_enabled_columns(): ColumnList;
+    /** returns them in display order */
+    get sortable_enabled_columns(): ColumnList;
+    /** returns them in sorted order */
+    get all_sortable_columns(): ColumnList;
+    /** 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>): void;
+    set_enabled(key: string, enabled: boolean): void;
+    set_width(key: string, width: number): void;
+}
+/** 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>;
+export {};

package/dist/column_manager.js

@@ -0,0 +1,124 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+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 _ColumnManager_instances, _ColumnManager_fixed_columns, _ColumnManager_sortable_columns, _ColumnManager_all_columns, _ColumnManager_read_order, _ColumnManager_save;
+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 {
+    constructor(columns, storage, storage_key, on_any_change) {
+        var _a;
+        _ColumnManager_instances.add(this);
+        this.columns = columns;
+        this.storage = storage;
+        this.storage_key = storage_key;
+        this.on_any_change = on_any_change;
+        _ColumnManager_fixed_columns.set(this, void 0);
+        _ColumnManager_sortable_columns.set(this, void 0);
+        _ColumnManager_all_columns.set(this, void 0);
+        if (columns.length != new Set(columns.map((c) => c.key)).size)
+            throw new Error("columns do not all have unique keys");
+        __classPrivateFieldSet(this, _ColumnManager_all_columns, new Map(), "f");
+        __classPrivateFieldSet(this, _ColumnManager_fixed_columns, [], "f");
+        __classPrivateFieldSet(this, _ColumnManager_sortable_columns, [], "f");
+        for (const c of columns) {
+            const mutable_column = {
+                key: c.key,
+                display: c.display,
+                help_text: c.help_text,
+                width: c.width,
+                enabled: c.enabled,
+                sortable: c.sortable,
+            };
+            __classPrivateFieldGet(this, _ColumnManager_all_columns, "f").set(c.key, c);
+            if (c.fixed) {
+                __classPrivateFieldGet(this, _ColumnManager_fixed_columns, "f").push(c);
+            }
+            else {
+                __classPrivateFieldGet(this, _ColumnManager_sortable_columns, "f").push(c);
+            }
+        }
+        // update state based on user preferences
+        if (storage) {
+            const config = tu.parse_json((_a = storage.getItem(this.storage_key)) !== null && _a !== void 0 ? _a : "");
+            if (ss.is(config, UserPreferencesStruct)) {
+                __classPrivateFieldGet(this, _ColumnManager_instances, "m", _ColumnManager_read_order).call(this, config.map((column) => column.key));
+                for (const { key, enabled, width } of config) {
+                    const column = __classPrivateFieldGet(this, _ColumnManager_all_columns, "f").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() {
+        return __classPrivateFieldGet(this, _ColumnManager_fixed_columns, "f").concat(__classPrivateFieldGet(this, _ColumnManager_sortable_columns, "f").filter((c) => c.enabled));
+    }
+    /** returns them in display order */
+    get fixed_enabled_columns() {
+        return __classPrivateFieldGet(this, _ColumnManager_fixed_columns, "f");
+    }
+    /** returns them in display order */
+    get sortable_enabled_columns() {
+        return __classPrivateFieldGet(this, _ColumnManager_sortable_columns, "f").filter((c) => c.enabled);
+    }
+    /** returns them in sorted order */
+    get all_sortable_columns() {
+        return __classPrivateFieldGet(this, _ColumnManager_sortable_columns, "f");
+    }
+    /** 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) {
+        __classPrivateFieldGet(this, _ColumnManager_instances, "m", _ColumnManager_read_order).call(this, keys);
+        __classPrivateFieldGet(this, _ColumnManager_instances, "m", _ColumnManager_save).call(this);
+        this.on_any_change();
+    }
+    set_enabled(key, enabled) {
+        const column = __classPrivateFieldGet(this, _ColumnManager_all_columns, "f").get(key);
+        if (!column)
+            throw new Error(`No column with key ${key}`);
+        column.enabled = enabled;
+        __classPrivateFieldGet(this, _ColumnManager_instances, "m", _ColumnManager_save).call(this);
+        this.on_any_change();
+    }
+    set_width(key, width) {
+        const column = __classPrivateFieldGet(this, _ColumnManager_all_columns, "f").get(key);
+        if (!column)
+            throw new Error(`No column with key ${key}`);
+        column.width = width;
+        __classPrivateFieldGet(this, _ColumnManager_instances, "m", _ColumnManager_save).call(this);
+        this.on_any_change();
+    }
+}
+_ColumnManager_fixed_columns = new WeakMap(), _ColumnManager_sortable_columns = new WeakMap(), _ColumnManager_all_columns = new WeakMap(), _ColumnManager_instances = new WeakSet(), _ColumnManager_read_order = function _ColumnManager_read_order(keys) {
+    __classPrivateFieldGet(this, _ColumnManager_sortable_columns, "f").sort(function (a, b) {
+        return keys.indexOf(a.key) - keys.indexOf(b.key);
+    });
+}, _ColumnManager_save = function _ColumnManager_save() {
+    if (!this.storage)
+        return;
+    const columns = __classPrivateFieldGet(this, _ColumnManager_fixed_columns, "f").concat(__classPrivateFieldGet(this, _ColumnManager_sortable_columns, "f"));
+    this.storage.setItem(this.storage_key, JSON.stringify(columns.map((column) => ({
+        key: column.key,
+        enabled: column.enabled,
+        width: column.width,
+    }))));
+};
+const UserPreferencesStruct = ss.array(ss.object({
+    key: ss.string(),
+    width: ss.number(),
+    enabled: ss.boolean(),
+}));