@qnc/qnc_data_tables 1.3.1 → 1.3.2

package/dist/table_options.d.ts

@@ -0,0 +1,177 @@
+import * as ss from "superstruct";
+declare const ColumnStruct: ss.Struct<{
+    key: string;
+    fixed: boolean;
+    display: string;
+    help_text: string;
+    enabled: boolean;
+    width: number;
+    sortable: boolean;
+    horizontal_alignment: "left" | "center" | "right" | "flex-start" | "flex-end" | "end" | "start";
+    data_vertical_alignment: "center" | "end" | "start" | "stretch";
+}, {
+    /** used to persist settings in Storage; must be unique across a table */
+    key: ss.Struct<string, null>;
+    /** column title */
+    display: ss.Struct<string, null>;
+    help_text: ss.Struct<string, null>;
+    /** whether the column is _initially_ shown; user can enable/disable */
+    enabled: ss.Struct<boolean, null>;
+    /** if true, the column cannot be reordered or enabled/disabled by the user, and is "sticky" when scrolling horizontally */
+    fixed: ss.Struct<boolean, null>;
+    /** sets the _initial_ with, in px; it's user-resizable */
+    width: ss.Struct<number, null>;
+    /** whether or not the user can click the column header to sort by this column */
+    /** when the user is sorting by this column, we will automatically set sort key to column_asc-KEY or column-desc-KEY */
+    sortable: ss.Struct<boolean, null>;
+    /** effects BOTH headers and data cells; individual data cells can override */
+    horizontal_alignment: ss.Struct<"left" | "center" | "right" | "flex-start" | "flex-end" | "end" | "start", null>;
+    /** effects ONLY data cells (not header); individual data cells can override */
+    data_vertical_alignment: ss.Struct<"center" | "end" | "start" | "stretch", null>;
+}>;
+export type Column = ss.Infer<typeof ColumnStruct>;
+declare const OptionalStorageStruct: ss.Struct<"localStorage" | "sessionStorage" | null, null>;
+export type OptionalStorageChoice = ss.Infer<typeof OptionalStorageStruct>;
+export declare function get_storage(type: OptionalStorageChoice): Storage | null;
+/**
+    "ExtraSortFunctions" are NOT js functions.
+    They are DESCRIPTIONS of sort functions implemented by the backend.
+    The only thing the front-end does with them is display some kind of sort-picker.
+ */
+declare const ExtraSortFunctionStruct: ss.Struct<{
+    key: string;
+    display: string;
+    help_text: string;
+}, {
+    /** will be submitted to back-end */
+    key: ss.Struct<string, null>;
+    /** what to display in sort-picker */
+    display: ss.Struct<string, null>;
+    /** help text, in case `display` is not self-explanatory */
+    help_text: ss.Struct<string, null>;
+}>;
+export type ExtraSortFunction = ss.Infer<typeof ExtraSortFunctionStruct>;
+declare const TableOptionsStruct: ss.Struct<{
+    columns: {
+        key: string;
+        fixed: boolean;
+        display: string;
+        help_text: string;
+        enabled: boolean;
+        width: number;
+        sortable: boolean;
+        horizontal_alignment: "left" | "center" | "right" | "flex-start" | "flex-end" | "end" | "start";
+        data_vertical_alignment: "center" | "end" | "start" | "stretch";
+    }[];
+    allow_selection: boolean;
+    api_url: string;
+    filter_form_id: string;
+    key_prefix: string;
+    page_size: number;
+    page_limit: number;
+    table_limit: number;
+    fill_last_page: boolean;
+    layout_storage: "localStorage" | "sessionStorage" | null;
+    navigation_storage: "localStorage" | "sessionStorage" | null;
+    selection_storage: "localStorage" | "sessionStorage" | null;
+    sort_storage: "localStorage" | "sessionStorage" | null;
+    extra_sort_functions: {
+        key: string;
+        display: string;
+        help_text: string;
+    }[];
+    default_sort: {
+        type: "column";
+        column_key: string;
+        direction: "reverse" | "forward";
+    } | {
+        type: "function";
+        function_key: string;
+    } | null;
+}, {
+    columns: ss.Struct<{
+        key: string;
+        fixed: boolean;
+        display: string;
+        help_text: string;
+        enabled: boolean;
+        width: number;
+        sortable: boolean;
+        horizontal_alignment: "left" | "center" | "right" | "flex-start" | "flex-end" | "end" | "start";
+        data_vertical_alignment: "center" | "end" | "start" | "stretch";
+    }[], ss.Struct<{
+        key: string;
+        fixed: boolean;
+        display: string;
+        help_text: string;
+        enabled: boolean;
+        width: number;
+        sortable: boolean;
+        horizontal_alignment: "left" | "center" | "right" | "flex-start" | "flex-end" | "end" | "start";
+        data_vertical_alignment: "center" | "end" | "start" | "stretch";
+    }, {
+        /** used to persist settings in Storage; must be unique across a table */
+        key: ss.Struct<string, null>;
+        /** column title */
+        display: ss.Struct<string, null>;
+        help_text: ss.Struct<string, null>;
+        /** whether the column is _initially_ shown; user can enable/disable */
+        enabled: ss.Struct<boolean, null>;
+        /** if true, the column cannot be reordered or enabled/disabled by the user, and is "sticky" when scrolling horizontally */
+        fixed: ss.Struct<boolean, null>;
+        /** sets the _initial_ with, in px; it's user-resizable */
+        width: ss.Struct<number, null>;
+        /** whether or not the user can click the column header to sort by this column */
+        /** when the user is sorting by this column, we will automatically set sort key to column_asc-KEY or column-desc-KEY */
+        sortable: ss.Struct<boolean, null>;
+        /** effects BOTH headers and data cells; individual data cells can override */
+        horizontal_alignment: ss.Struct<"left" | "center" | "right" | "flex-start" | "flex-end" | "end" | "start", null>;
+        /** effects ONLY data cells (not header); individual data cells can override */
+        data_vertical_alignment: ss.Struct<"center" | "end" | "start" | "stretch", null>;
+    }>>;
+    allow_selection: ss.Struct<boolean, null>;
+    api_url: ss.Struct<string, null>;
+    filter_form_id: ss.Struct<string, null>;
+    key_prefix: ss.Struct<string, null>;
+    page_size: ss.Struct<number, null>;
+    page_limit: ss.Struct<number, null>;
+    table_limit: ss.Struct<number, null>;
+    fill_last_page: ss.Struct<boolean, null>;
+    /** Where table layout preferences (columns, column widths) are stored */
+    layout_storage: ss.Struct<"localStorage" | "sessionStorage" | null, null>;
+    /** where page number is stored */
+    navigation_storage: ss.Struct<"localStorage" | "sessionStorage" | null, null>;
+    /** where selection is stored */
+    selection_storage: ss.Struct<"localStorage" | "sessionStorage" | null, null>;
+    /** where sort order is stored */
+    sort_storage: ss.Struct<"localStorage" | "sessionStorage" | null, null>;
+    /** when non-empty, will cause a "sort widget" to be displayed in the paginator */
+    extra_sort_functions: ss.Struct<{
+        key: string;
+        display: string;
+        help_text: string;
+    }[], ss.Struct<{
+        key: string;
+        display: string;
+        help_text: string;
+    }, {
+        /** will be submitted to back-end */
+        key: ss.Struct<string, null>;
+        /** what to display in sort-picker */
+        display: ss.Struct<string, null>;
+        /** help text, in case `display` is not self-explanatory */
+        help_text: ss.Struct<string, null>;
+    }>>;
+    /** If null, front-end will arbitrarily choose one of the available sorting options */
+    default_sort: ss.Struct<{
+        type: "column";
+        column_key: string;
+        direction: "reverse" | "forward";
+    } | {
+        type: "function";
+        function_key: string;
+    } | null, null>;
+}>;
+export type TableOptions = ss.Infer<typeof TableOptionsStruct>;
+export declare function read_options_from_json_string(json: string): TableOptions;
+export {};

package/dist/table_options.js

@@ -0,0 +1,110 @@
+import * as ss from "superstruct";
+import { assert_never } from "@qnc/type_utils";
+function css_class_component() {
+    return ss.define("css_class_component", (value) => (typeof value == "string" && value.match(/^[\w-]*$/) !== null) ||
+        `Expected a string, but received: ${value}`);
+}
+const ColumnStruct = ss.object({
+    /** used to persist settings in Storage; must be unique across a table */
+    key: css_class_component(),
+    /** column title */
+    display: ss.string(),
+    help_text: ss.string(),
+    /** whether the column is _initially_ shown; user can enable/disable */
+    enabled: ss.boolean(),
+    /** if true, the column cannot be reordered or enabled/disabled by the user, and is "sticky" when scrolling horizontally */
+    fixed: ss.boolean(),
+    /** sets the _initial_ with, in px; it's user-resizable */
+    width: ss.number(),
+    /** whether or not the user can click the column header to sort by this column */
+    /** when the user is sorting by this column, we will automatically set sort key to column_asc-KEY or column-desc-KEY */
+    sortable: ss.boolean(),
+    /** effects BOTH headers and data cells; individual data cells can override */
+    horizontal_alignment: ss.defaulted(ss.union([
+        ss.literal("left"),
+        ss.literal("center"),
+        ss.literal("right"),
+        ss.literal("flex-start"),
+        ss.literal("flex-end"),
+        ss.literal("end"),
+        ss.literal("start"),
+    ]), "flex-start"),
+    /** effects ONLY data cells (not header); individual data cells can override */
+    data_vertical_alignment: ss.defaulted(ss.union([
+        ss.literal("stretch"),
+        ss.literal("center"),
+        ss.literal("start"),
+        ss.literal("end"),
+    ]), "center"),
+});
+const OptionalStorageStruct = ss.union([
+    ss.literal("localStorage"),
+    ss.literal("sessionStorage"),
+    ss.literal(null),
+]);
+export function get_storage(type) {
+    if (type == "localStorage")
+        return localStorage;
+    if (type == "sessionStorage")
+        return sessionStorage;
+    if (type == null)
+        return null;
+    assert_never(type);
+}
+const SortStateStruct = ss.union([
+    ss.object({
+        type: ss.literal("column"),
+        column_key: ss.string(),
+        direction: ss.union([ss.literal("forward"), ss.literal("reverse")]),
+    }),
+    ss.object({
+        type: ss.literal("function"),
+        function_key: ss.string(),
+    }),
+]);
+/**
+    "ExtraSortFunctions" are NOT js functions.
+    They are DESCRIPTIONS of sort functions implemented by the backend.
+    The only thing the front-end does with them is display some kind of sort-picker.
+ */
+const ExtraSortFunctionStruct = ss.object({
+    /** will be submitted to back-end */
+    key: ss.string(),
+    /** what to display in sort-picker */
+    display: ss.string(),
+    /** help text, in case `display` is not self-explanatory */
+    help_text: ss.defaulted(ss.string(), ""),
+});
+const TableOptionsStruct = ss.object({
+    columns: ss.array(ColumnStruct),
+    allow_selection: ss.defaulted(ss.boolean(), false),
+    api_url: ss.defaulted(ss.string(), "."),
+    // If non-empty, MUST reference a <form> element on the page
+    filter_form_id: ss.defaulted(ss.string(), ""),
+    // Must be unique across all data tables on a given page (used in constructing CSS classes and Storage keys)
+    // Must be unique across all tables submitting to same api_url (used in constructing keys for backend communication)
+    // Must contain only alphanumerics, underscores, and hyphens
+    key_prefix: ss.defaulted(css_class_component(), "table-manager"),
+    page_size: ss.integer(),
+    page_limit: ss.integer(),
+    table_limit: ss.integer(),
+    // If last page of data has fewer rows than page_size and this is set, we'll add empty rows
+    // keeps layout/height more consistent, regardless of data
+    fill_last_page: ss.defaulted(ss.boolean(), true),
+    /** Where table layout preferences (columns, column widths) are stored */
+    layout_storage: ss.defaulted(OptionalStorageStruct, "localStorage"),
+    /** where page number is stored */
+    navigation_storage: ss.defaulted(OptionalStorageStruct, "sessionStorage"),
+    /** where selection is stored */
+    selection_storage: ss.defaulted(OptionalStorageStruct, "sessionStorage"),
+    /** where sort order is stored */
+    sort_storage: ss.defaulted(OptionalStorageStruct, "localStorage"),
+    /** when non-empty, will cause a "sort widget" to be displayed in the paginator */
+    extra_sort_functions: ss.defaulted(ss.array(ExtraSortFunctionStruct), []),
+    /** If null, front-end will arbitrarily choose one of the available sorting options */
+    default_sort: ss.defaulted(ss.union([SortStateStruct, ss.literal(null)]), null),
+});
+export function read_options_from_json_string(json) {
+    return ss.create(JSON.parse(json), TableOptionsStruct);
+}
+//# sourceMappingURL=table_options.js.map

package/dist/table_options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table_options.js","sourceRoot":"","sources":["../src/table_options.ts"],"names":[],"mappings":"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"}

package/dist/table_options.ts

@@ -0,0 +1,150 @@
+import * as ss from "superstruct";
+import { assert_never } from "@qnc/type_utils";
+
+function css_class_component(): ss.Struct<string, null> {
+    return ss.define(
+        "css_class_component",
+        (value) =>
+            (typeof value == "string" && value.match(/^[\w-]*$/) !== null) ||
+            `Expected a string, but received: ${value}`,
+    );
+}
+
+const ColumnStruct = ss.object({
+    /** used to persist settings in Storage; must be unique across a table */
+    key: css_class_component(),
+
+    /** column title */
+    display: ss.string(),
+
+    help_text: ss.string(),
+
+    /** whether the column is _initially_ shown; user can enable/disable */
+    enabled: ss.boolean(),
+
+    /** if true, the column cannot be reordered or enabled/disabled by the user, and is "sticky" when scrolling horizontally */
+    fixed: ss.boolean(),
+
+    /** sets the _initial_ with, in px; it's user-resizable */
+    width: ss.number(),
+
+    /** whether or not the user can click the column header to sort by this column */
+    /** when the user is sorting by this column, we will automatically set sort key to column_asc-KEY or column-desc-KEY */
+    sortable: ss.boolean(),
+
+    /** effects BOTH headers and data cells; individual data cells can override */
+    horizontal_alignment: ss.defaulted(
+        ss.union([
+            ss.literal("left"),
+            ss.literal("center"),
+            ss.literal("right"),
+            ss.literal("flex-start"),
+            ss.literal("flex-end"),
+            ss.literal("end"),
+            ss.literal("start"),
+        ]),
+        "flex-start",
+    ),
+
+    /** effects ONLY data cells (not header); individual data cells can override */
+    data_vertical_alignment: ss.defaulted(
+        ss.union([
+            ss.literal("stretch"),
+            ss.literal("center"),
+            ss.literal("start"),
+            ss.literal("end"),
+        ]),
+        "center",
+    ),
+});
+export type Column = ss.Infer<typeof ColumnStruct>;
+
+const OptionalStorageStruct = ss.union([
+    ss.literal("localStorage"),
+    ss.literal("sessionStorage"),
+    ss.literal(null),
+]);
+export type OptionalStorageChoice = ss.Infer<typeof OptionalStorageStruct>;
+
+export function get_storage(type: OptionalStorageChoice): Storage | null {
+    if (type == "localStorage") return localStorage;
+    if (type == "sessionStorage") return sessionStorage;
+    if (type == null) return null;
+    assert_never(type);
+}
+
+const SortStateStruct = ss.union([
+    ss.object({
+        type: ss.literal("column"),
+        column_key: ss.string(),
+        direction: ss.union([ss.literal("forward"), ss.literal("reverse")]),
+    }),
+    ss.object({
+        type: ss.literal("function"),
+        function_key: ss.string(),
+    }),
+]);
+
+/** 
+    "ExtraSortFunctions" are NOT js functions.
+    They are DESCRIPTIONS of sort functions implemented by the backend.
+    The only thing the front-end does with them is display some kind of sort-picker.
+ */
+const ExtraSortFunctionStruct = ss.object({
+    /** will be submitted to back-end */
+    key: ss.string(),
+    /** what to display in sort-picker */
+    display: ss.string(),
+    /** help text, in case `display` is not self-explanatory */
+    help_text: ss.defaulted(ss.string(), ""),
+});
+export type ExtraSortFunction = ss.Infer<typeof ExtraSortFunctionStruct>;
+
+const TableOptionsStruct = ss.object({
+    columns: ss.array(ColumnStruct),
+    allow_selection: ss.defaulted(ss.boolean(), false),
+    api_url: ss.defaulted(ss.string(), "."),
+
+    // If non-empty, MUST reference a <form> element on the page
+    filter_form_id: ss.defaulted(ss.string(), ""),
+
+    // Must be unique across all data tables on a given page (used in constructing CSS classes and Storage keys)
+    // Must be unique across all tables submitting to same api_url (used in constructing keys for backend communication)
+    // Must contain only alphanumerics, underscores, and hyphens
+    key_prefix: ss.defaulted(css_class_component(), "table-manager"),
+
+    page_size: ss.integer(),
+    page_limit: ss.integer(),
+    table_limit: ss.integer(),
+
+    // If last page of data has fewer rows than page_size and this is set, we'll add empty rows
+    // keeps layout/height more consistent, regardless of data
+    fill_last_page: ss.defaulted(ss.boolean(), true),
+
+    /** Where table layout preferences (columns, column widths) are stored */
+    layout_storage: ss.defaulted(OptionalStorageStruct, "localStorage"),
+
+    /** where page number is stored */
+    navigation_storage: ss.defaulted(OptionalStorageStruct, "sessionStorage"),
+
+    /** where selection is stored */
+    selection_storage: ss.defaulted(OptionalStorageStruct, "sessionStorage"),
+
+    /** where sort order is stored */
+    sort_storage: ss.defaulted(OptionalStorageStruct, "localStorage"),
+
+    /** when non-empty, will cause a "sort widget" to be displayed in the paginator */
+    extra_sort_functions: ss.defaulted(ss.array(ExtraSortFunctionStruct), []),
+
+    /** If null, front-end will arbitrarily choose one of the available sorting options */
+    default_sort: ss.defaulted(
+        ss.union([SortStateStruct, ss.literal(null)]),
+        null,
+    ),
+});
+
+export type TableOptions = ss.Infer<typeof TableOptionsStruct>;
+
+export function read_options_from_json_string(json: string): TableOptions {
+    return ss.create(JSON.parse(json), TableOptionsStruct);
+}

package/dist/watched_mutable_value.d.ts

@@ -0,0 +1,15 @@
+/**
+    Intended to hold values which must be determined by the view layer (ie. which depend on rendered layout)
+    and which affect other aspects of the UI.
+
+    Example: the UI renders an element, then checks if that element has overflow, then wants to toggle a class on that element in response to the check.
+
+    Your state machine / "data store" should own/create the WatchedMutableValue. It can pass it directly to the view layer, which is free to update it.
+*/
+export declare class WatchedMutableValue<T> {
+    private value;
+    private onchange;
+    constructor(value: T, onchange: () => void);
+    get(): T;
+    set(value: T): void;
+}

package/dist/watched_mutable_value.js

@@ -0,0 +1,24 @@
+/**
+    Intended to hold values which must be determined by the view layer (ie. which depend on rendered layout)
+    and which affect other aspects of the UI.
+
+    Example: the UI renders an element, then checks if that element has overflow, then wants to toggle a class on that element in response to the check.
+
+    Your state machine / "data store" should own/create the WatchedMutableValue. It can pass it directly to the view layer, which is free to update it.
+*/
+export class WatchedMutableValue {
+    constructor(value, onchange) {
+        this.value = value;
+        this.onchange = onchange;
+    }
+    get() {
+        return this.value;
+    }
+    set(value) {
+        const changed = this.value != value;
+        this.value = value;
+        if (changed)
+            this.onchange();
+    }
+}
+//# sourceMappingURL=watched_mutable_value.js.map

package/dist/watched_mutable_value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watched_mutable_value.js","sourceRoot":"","sources":["../src/watched_mutable_value.ts"],"names":[],"mappings":"AAAA;;;;;;;EAOE;AACF,MAAM,OAAO,mBAAmB;IAC5B,YACY,KAAQ,EACR,QAAoB;QADpB,UAAK,GAAL,KAAK,CAAG;QACR,aAAQ,GAAR,QAAQ,CAAY;IAC7B,CAAC;IAEJ,GAAG;QACC,OAAO,IAAI,CAAC,KAAK,CAAC;IACtB,CAAC;IACD,GAAG,CAAC,KAAQ;QACR,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC;QACpC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,OAAO;YAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC;CACJ"}

package/dist/watched_mutable_value.ts

@@ -0,0 +1,23 @@
+/**
+    Intended to hold values which must be determined by the view layer (ie. which depend on rendered layout)
+    and which affect other aspects of the UI.
+
+    Example: the UI renders an element, then checks if that element has overflow, then wants to toggle a class on that element in response to the check.
+
+    Your state machine / "data store" should own/create the WatchedMutableValue. It can pass it directly to the view layer, which is free to update it.
+*/
+export class WatchedMutableValue<T> {
+    constructor(
+        private value: T,
+        private onchange: () => void,
+    ) {}
+
+    get() {
+        return this.value;
+    }
+    set(value: T) {
+        const changed = this.value != value;
+        this.value = value;
+        if (changed) this.onchange();
+    }
+}

package/package.json

@@ -7,7 +7,7 @@
     "intermediate/*.ts",
     "README.md"
   ],
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Work-in-progress",
   "main": "dist/index.js",
   "scripts": {