@excom/data-table 0.1.0

package/src/data-table.css

@@ -0,0 +1,124 @@
+@import "@excom/valence/src/content/table.css";
+
+/**
+ * Styles for `<data-table>` and the plain structural tags that make up a
+ * table: `<data-thead>`, `<data-tbody>`, `<data-tr>`, `<data-th>`,
+ * `<data-td>`, `<data-tfoot>`, `<data-tf>`. Only `<data-table>` and
+ * `<data-th>` are registered Neutron elements — the rest are inert custom
+ * tags styled here so markup reads like a real `<table>`. Use the
+ * `.tag-data-*` classes to apply the same styling to other elements
+ * (e.g. a real `<table>` / `<tr>` / `<td>`).
+ * @element data-table
+ */
+
+/* Aliases */
+@custom-selector :--data-table data-table, .tag-data-table;
+@custom-selector :--data-thead data-thead, .tag-data-thead;
+@custom-selector :--data-tbody data-tbody, .tag-data-tbody;
+@custom-selector :--data-tfoot data-tfoot, .tag-data-tfoot;
+@custom-selector :--data-tr data-tr, .tag-data-tr;
+@custom-selector :--data-th data-th, .tag-data-th;
+@custom-selector :--data-td data-td, .tag-data-td;
+@custom-selector :--data-tf data-tf, .tag-data-tf;
+/* NOOP: we treat every `<data-th>` as sortable */
+@custom-selector :--data-th--sort :is(:--data-th);
+@custom-selector :--data-th--sort-asc [sort-direction="asc"], [aria-sort="ascending"];
+@custom-selector :--data-th--sort-desc [sort-direction="desc"], [aria-sort="descending"];
+
+@define-mixin data-table-detect-cols $n {
+  &:has(:--data-tr > :nth-child($(n))) {
+    --data-table-cols-detected: $(n);
+  }
+}
+
+@define-mixin module-data-table {
+  @mixin module-table :--data-table, :--data-thead, :--data-tbody,
+    :--data-tfoot, :--data-tr, :--data-th, :--data-td, :--data-th--sort,
+    :--data-th--sort-asc, :--data-th--sort-desc;
+  :--data-table {
+    display: grid;
+    /**
+     * Column count for shared subgrid tracks. Auto-detected from the
+     * widest row; set on the host to override.
+     * @cssproperty --data-table-cols
+     * @syntax <integer>
+     */
+    --data-table-cols-detected: 1;
+    /* Leading columns hug content; last takes leftover so the table
+       stays `width: 100%`. `1fr` on every track would equalize. */
+    grid-template-columns:
+      repeat(
+        calc(var(--data-table-cols, var(--data-table-cols-detected)) - 1),
+        auto
+      )
+      minmax(min-content, 1fr);
+
+    /* Widest row wins (later rules override). Author `--data-table-cols` wins. */
+    @mixin data-table-detect-cols 2;
+    @mixin data-table-detect-cols 3;
+    @mixin data-table-detect-cols 4;
+    @mixin data-table-detect-cols 5;
+    @mixin data-table-detect-cols 6;
+    @mixin data-table-detect-cols 7;
+    @mixin data-table-detect-cols 8;
+    @mixin data-table-detect-cols 9;
+    @mixin data-table-detect-cols 10;
+    @mixin data-table-detect-cols 11;
+    @mixin data-table-detect-cols 12;
+    @mixin data-table-detect-cols 13;
+    @mixin data-table-detect-cols 14;
+    @mixin data-table-detect-cols 15;
+    @mixin data-table-detect-cols 16;
+
+    :--data-thead > :--data-tr {
+      order: 0;
+    }
+    :--data-tbody > :--data-tr {
+      /**
+       * Visual row order (1-based). Set by `<data-table>` on sort —
+       * not meant to be set by hand.
+       * @cssproperty
+       * @syntax <integer>
+       */
+      order: var(--data-tr-order);
+    }
+    :--data-tfoot > :--data-tr {
+      order: 9999;
+    }
+
+    :--data-thead,
+    :--data-tbody,
+    :--data-tfoot {
+      display: contents;
+    }
+    :--data-tr {
+      /**
+       * Row display. `<data-table>` sets `none` to hide filtered-out
+       * rows — not meant to be set by hand.
+       * @cssproperty
+       * @syntax none | grid
+       * @default grid
+       */
+      display: var(--data-tr-display, grid);
+      grid-column: 1 / -1;
+      grid-template-columns: subgrid;
+      :--data-th,
+      :--data-td,
+      :--data-tf {
+        display: block;
+        /* Borders via `:nth-of-type`; `order` only changes visual layout */
+        border-bottom: var(--v-border-width) solid var(--v-table-border-color) !important;
+        border-radius: 0 !important;
+      }
+    }
+    &:not(:has(:--data-tbody :--data-tr + :--data-tr)) {
+      /* One row or none: don't look sortable */
+      :--data-th {
+        cursor: default;
+        &::after {
+          content: "";
+        }
+      }
+    }
+  }
+}

package/support/custom-elements.json

@@ -0,0 +1,366 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "data-table.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "DataTable",
+          "customElement": true,
+          "tagName": "data-table",
+          "summary": "Sortable / filterable data table — plain tags, one behavior owner.",
+          "description": "Options the `--export` invoker carries as `data-*` attributes (`data-file-type=\"json\"`, `data-file-name=\"people\"`, `data-full`).",
+          "attributes": [
+            {
+              "name": "filter-value",
+              "type": {
+                "text": "string"
+              },
+              "description": "Hides `data-tr` rows (via `--data-tr-display: none`) whose text content doesn't include this value. Case-insensitive unless `filter-casing` is set. Unset / empty clears the filter. Rows stay in the DOM so Quark bindings survive.",
+              "fieldName": "filterValue"
+            },
+            {
+              "name": "filter-casing",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Match `filter-value` case-sensitively instead of the default case-insensitive comparison.",
+              "fieldName": "filterCasing"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "filterValue",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Hides `data-tr` rows (via `--data-tr-display: none`) whose text content doesn't include this value. Case-insensitive unless `filter-casing` is set. Unset / empty clears the filter. Rows stay in the DOM so Quark bindings survive.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "filterCasing",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Match `filter-value` case-sensitively instead of the default case-insensitive comparison.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "provision",
+              "type": {
+                "text": "DataTableProvision",
+                "expanded": "{ totalRows: number; visibleRows: number; sortColumnIndex: number | null; sortDirection: \"asc\" | \"desc\" | null; filterValue: string | null; }"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "`{ totalRows, visibleRows, sortColumnIndex, sortDirection, filterValue }` — recomputed after connect, after the `data-table-sort` default action, and after every filter change. Not reflected as an attribute.",
+              "_neutron": {
+                "surface": "option"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "data-table-sort",
+              "description": "Cancelable. Dispatched when the active sort column / direction changes: on connect (if a `data-th` already has `sort-direction`) and after every `data-th-sort`. Call `preventDefault()` to take over sorting yourself.",
+              "type": {
+                "text": "DataTableSortEvent",
+                "expanded": "CustomEvent & { type: \"data-table-sort\"; detail: { sortDirection: \"asc\" | \"desc\"; columnType: \"string\" | \"number\" | \"date\"; columnIndex: number; sortFn: (a: string, b: string) => number; rows: HTMLElement[]; }; bubbles: true; cancelable: true; composed: true }"
+              }
+            }
+          ],
+          "_neutron": {
+            "provisions": [
+              {
+                "name": "provision",
+                "type": {
+                  "text": "DataTableProvision",
+                  "expanded": "{ totalRows: number; visibleRows: number; sortColumnIndex: number | null; sortDirection: \"asc\" | \"desc\" | null; filterValue: string | null; }"
+                },
+                "description": "`{ totalRows, visibleRows, sortColumnIndex, sortDirection, filterValue }` — recomputed after connect, after the `data-table-sort` default action, and after every filter change. Not reflected as an attribute.",
+                "fieldName": "provision"
+              }
+            ],
+            "listens": [
+              {
+                "name": "data-th-sort",
+                "description": "Bubbled up from a descendant `data-th` when its `sort-direction` changes. Sets that header as the active sort column (clearing `sort-direction` from the previously active one) and emits `data-table-sort`.",
+                "type": {
+                  "text": "DataThSortEvent",
+                  "expanded": "CustomEvent & { type: \"data-th-sort\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+                }
+              }
+            ],
+            "commands": [
+              {
+                "name": "--export",
+                "description": "Builds a file from the table's `data-tr` / `data-td` / `data-th` text content and downloads it. Options are `data-*` on the invoker: `data-file-type` (`csv`, the default, or `json`), `data-file-name` (default `export_table_<locale-date>`), and `data-full` to download every row in DOM order instead of only the visible rows in visual sort order. Filtering needs no command: write `filter-value` / `filter-casing`."
+              }
+            ],
+            "defaultActions": [
+              {
+                "name": "data-table-sort",
+                "description": "Sorts `event.detail.rows` by `columnIndex` with `sortFn` and sets `--data-tr-order` on each row (visual CSS `order` — DOM order is unchanged)."
+              }
+            ],
+            "expectedChildren": [
+              {
+                "relationship": "descendant",
+                "selector": "data-th",
+                "required": true,
+                "description": "Sortable column header. Clicking toggles its `sort-direction` and fires `data-th-sort`, which becomes the active column."
+              },
+              {
+                "relationship": "descendant",
+                "selector": "data-tbody",
+                "required": true,
+                "description": "Required row container. Sorting and filtering both operate on its `data-tr` children."
+              },
+              {
+                "relationship": "descendant",
+                "selector": "data-tr",
+                "required": true,
+                "description": "Row, direct child of `data-tbody`. Gets `--data-tr-order` on sort and `--data-tr-display` on filter. DOM order is unchanged."
+              },
+              {
+                "relationship": "descendant",
+                "selector": "data-td",
+                "required": true,
+                "description": "Cell within a `data-tr`, read as sortable / export cell content."
+              }
+            ],
+            "cssAliases": [
+              {
+                "name": ":--data-table",
+                "selectors": [
+                  "data-table",
+                  ".tag-data-table"
+                ],
+                "kind": "element"
+              },
+              {
+                "name": ":--data-thead",
+                "selectors": [
+                  "data-thead",
+                  ".tag-data-thead"
+                ],
+                "kind": "element"
+              },
+              {
+                "name": ":--data-tbody",
+                "selectors": [
+                  "data-tbody",
+                  ".tag-data-tbody"
+                ],
+                "kind": "element"
+              },
+              {
+                "name": ":--data-tfoot",
+                "selectors": [
+                  "data-tfoot",
+                  ".tag-data-tfoot"
+                ],
+                "kind": "element"
+              },
+              {
+                "name": ":--data-tr",
+                "selectors": [
+                  "data-tr",
+                  ".tag-data-tr"
+                ],
+                "kind": "element"
+              },
+              {
+                "name": ":--data-td",
+                "selectors": [
+                  "data-td",
+                  ".tag-data-td"
+                ],
+                "kind": "element"
+              },
+              {
+                "name": ":--data-tf",
+                "selectors": [
+                  "data-tf",
+                  ".tag-data-tf"
+                ],
+                "kind": "element"
+              }
+            ]
+          },
+          "cssProperties": [
+            {
+              "name": "--data-table-cols",
+              "description": "Column count for shared subgrid tracks. Auto-detected from the widest row; set on the host to override.",
+              "syntax": "<integer>",
+              "default": "1"
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "DataTable",
+          "declaration": {
+            "name": "DataTable",
+            "module": "data-table.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "data-table",
+          "declaration": {
+            "name": "DataTable",
+            "module": "data-table.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "data-th.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "DataTh",
+          "customElement": true,
+          "tagName": "data-th",
+          "summary": "Sortable column header — click toggles sort direction.",
+          "description": "Sortable column header. Clicking toggles `sort-direction` between `asc` / `desc`; the parent `<data-table>` listens for the resulting `data-th-sort` event to drive sorting and to track which header is active. Renders no chrome of its own — style via `.tag-data-th` or the sort-direction indicators in `data-table`'s stylesheet.",
+          "attributes": [
+            {
+              "name": "column-type",
+              "type": {
+                "text": "string"
+              },
+              "description": "Sort comparator to use for this column's cell values. `data-table` treats `null` as \"string\".",
+              "fieldName": "columnType",
+              "values": [
+                "string",
+                "number",
+                "date"
+              ]
+            },
+            {
+              "name": "sort-direction",
+              "type": {
+                "text": "string"
+              },
+              "description": "Current sort direction. A click toggles between `asc` / `desc`; setting it (by any means) fires `data-th-sort`. Only one `data-th` per table should carry this at a time — the parent `<data-table>` clears the previously active header when a new one is set.",
+              "fieldName": "sortDirection",
+              "values": [
+                "asc",
+                "desc"
+              ]
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "columnType",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Sort comparator to use for this column's cell values. `data-table` treats `null` as \"string\".",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "sortDirection",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Current sort direction. A click toggles between `asc` / `desc`; setting it (by any means) fires `data-th-sort`. Only one `data-th` per table should carry this at a time — the parent `<data-table>` clears the previously active header when a new one is set.",
+              "_neutron": {
+                "surface": "hybrid"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "data-th-sort",
+              "description": "Dispatched whenever `sort-direction` is set, whether by a click or programmatically. Bubbles to the parent `<data-table>`.",
+              "type": {
+                "text": "DataThSortEvent",
+                "expanded": "CustomEvent & { type: \"data-th-sort\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+              }
+            }
+          ],
+          "_neutron": {
+            "cssAliases": [
+              {
+                "name": ":--data-th",
+                "selectors": [
+                  "data-th",
+                  ".tag-data-th"
+                ],
+                "kind": "element"
+              },
+              {
+                "name": ":--data-th--sort",
+                "selectors": [
+                  ":is(:--data-th)"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--data-th--sort-asc",
+                "selectors": [
+                  "[sort-direction=\"asc\"]",
+                  "[aria-sort=\"ascending\"]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--data-th--sort-desc",
+                "selectors": [
+                  "[sort-direction=\"desc\"]",
+                  "[aria-sort=\"descending\"]"
+                ],
+                "kind": "state"
+              }
+            ]
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "DataTh",
+          "declaration": {
+            "name": "DataTh",
+            "module": "data-th.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "data-th",
+          "declaration": {
+            "name": "DataTh",
+            "module": "data-th.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/demos/filter.html

@@ -0,0 +1,67 @@
+<div>
+  <quark-sheet>
+    :scope {
+      @on input (target: "form[data-filter]") {
+        data-table { filter-value: target.elements.filterValue.value; }
+      }
+      @on change (target: "form[data-filter]") {
+        data-table { filter-casing: target.elements.filterCasing.checked; }
+      }
+      @on change (target: "form[data-export]") {
+        form[data-export] [command="--export"] {
+          data-file-type: target.elements.fileType.value;
+          data-file-name: target.elements.fileName.value;
+          data-full: target.elements.full.checked;
+        }
+      }
+    }
+  </quark-sheet>
+  <form data-filter>
+    <fieldset role="group">
+      <input name="filterValue" placeholder="Filter table…" />
+      <label>
+        Case-sensitive
+        <input name="filterCasing" role="switch" type="checkbox" />
+      </label>
+    </fieldset>
+  </form>
+  <data-table id="demo-data-table-filter">
+    <data-thead>
+      <data-tr>
+        <data-th column-type="string">Name</data-th>
+        <data-th column-type="number">Age</data-th>
+      </data-tr>
+    </data-thead>
+    <data-tbody>
+      <data-tr><data-td>Beatrice</data-td><data-td>44</data-td></data-tr>
+      <data-tr><data-td>Cynthia</data-td><data-td>41</data-td></data-tr>
+      <data-tr><data-td>Beau</data-td><data-td>29</data-td></data-tr>
+      <data-tr><data-td>Adam</data-td><data-td>36</data-td></data-tr>
+    </data-tbody>
+  </data-table>
+  <hr />
+  <button type="button" command="--export" commandfor="demo-data-table-filter">
+    Export as-is
+  </button>
+  <hr />
+  <form data-export class="tag-article">
+    <header>
+      <h4>Export with options</h4>
+    </header>
+    <label>
+      <select name="fileType">
+        <option value="csv" selected>CSV</option>
+        <option value="json">JSON</option>
+      </select>
+    </label>
+    <label>
+      File name
+      <input name="fileName" placeholder="File name" />
+    </label>
+    <label>
+      <input name="full" type="checkbox" role="switch" />
+      Full table (ignores active filter/sort)
+    </label>
+    <button type="button" command="--export" commandfor="demo-data-table-filter">Export</button>
+  </form>
+</div>

package/support/demos/simple.html

@@ -0,0 +1,14 @@
+<data-table>
+  <data-thead>
+    <data-tr>
+      <data-th column-type="string" sort-direction="asc">Name</data-th>
+      <data-th column-type="number">Age</data-th>
+    </data-tr>
+  </data-thead>
+  <data-tbody>
+    <data-tr><data-td>Beatrice</data-td><data-td>44</data-td></data-tr>
+    <data-tr><data-td>Cynthia</data-td><data-td>41</data-td></data-tr>
+    <data-tr><data-td>Beau</data-td><data-td>29</data-td></data-tr>
+    <data-tr><data-td>Adam</data-td><data-td>36</data-td></data-tr>
+  </data-tbody>
+</data-table>