@excom/data-table 0.1.0

package/support/package-meta.json

@@ -0,0 +1,280 @@
+{
+  "shortName": "data-table",
+  "package": {
+    "name": "@excom/data-table",
+    "version": "0.1.0",
+    "description": "<data-table> custom element",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "filter": "<div>\n  <quark-sheet>\n    :scope {\n      @on input (target: \"form[data-filter]\") {\n        data-table { filter-value: target.elements.filterValue.value; }\n      }\n      @on change (target: \"form[data-filter]\") {\n        data-table { filter-casing: target.elements.filterCasing.checked; }\n      }\n      @on change (target: \"form[data-export]\") {\n        form[data-export] [command=\"--export\"] {\n          data-file-type: target.elements.fileType.value;\n          data-file-name: target.elements.fileName.value;\n          data-full: target.elements.full.checked;\n        }\n      }\n    }\n  </quark-sheet>\n  <form data-filter>\n    <fieldset role=\"group\">\n      <input name=\"filterValue\" placeholder=\"Filter table…\" />\n      <label>\n        Case-sensitive\n        <input name=\"filterCasing\" role=\"switch\" type=\"checkbox\" />\n      </label>\n    </fieldset>\n  </form>\n  <data-table id=\"demo-data-table-filter\">\n    <data-thead>\n      <data-tr>\n        <data-th column-type=\"string\">Name</data-th>\n        <data-th column-type=\"number\">Age</data-th>\n      </data-tr>\n    </data-thead>\n    <data-tbody>\n      <data-tr><data-td>Beatrice</data-td><data-td>44</data-td></data-tr>\n      <data-tr><data-td>Cynthia</data-td><data-td>41</data-td></data-tr>\n      <data-tr><data-td>Beau</data-td><data-td>29</data-td></data-tr>\n      <data-tr><data-td>Adam</data-td><data-td>36</data-td></data-tr>\n    </data-tbody>\n  </data-table>\n  <hr />\n  <button type=\"button\" command=\"--export\" commandfor=\"demo-data-table-filter\">\n    Export as-is\n  </button>\n  <hr />\n  <form data-export class=\"tag-article\">\n    <header>\n      <h4>Export with options</h4>\n    </header>\n    <label>\n      <select name=\"fileType\">\n        <option value=\"csv\" selected>CSV</option>\n        <option value=\"json\">JSON</option>\n      </select>\n    </label>\n    <label>\n      File name\n      <input name=\"fileName\" placeholder=\"File name\" />\n    </label>\n    <label>\n      <input name=\"full\" type=\"checkbox\" role=\"switch\" />\n      Full table (ignores active filter/sort)\n    </label>\n    <button type=\"button\" command=\"--export\" commandfor=\"demo-data-table-filter\">Export</button>\n  </form>\n</div>\n",
+    "simple": "<data-table>\n  <data-thead>\n    <data-tr>\n      <data-th column-type=\"string\" sort-direction=\"asc\">Name</data-th>\n      <data-th column-type=\"number\">Age</data-th>\n    </data-tr>\n  </data-thead>\n  <data-tbody>\n    <data-tr><data-td>Beatrice</data-td><data-td>44</data-td></data-tr>\n    <data-tr><data-td>Cynthia</data-td><data-td>41</data-td></data-tr>\n    <data-tr><data-td>Beau</data-td><data-td>29</data-td></data-tr>\n    <data-tr><data-td>Adam</data-td><data-td>36</data-td></data-tr>\n  </data-tbody>\n</data-table>\n"
+  },
+  "readme": "<h1 id=\"md-data-table\">data-table</h1>\n<p>Sortable, filterable tables from plain custom tags — one behavior owner\n(<code>&lt;data-table&gt;</code> + <code>&lt;data-th&gt;</code>), everything else is CSS.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Sort</strong> Click a <code>&lt;data-th&gt;</code> to visually sort by string, number, or date</li>\n<li><strong>Filter</strong> <code>filter-value</code> hides non-matching rows</li>\n<li><strong>Export</strong> The <code>--export</code> command downloads visible / all rows as CSV / JSON</li>\n<li><strong>DOM-stable</strong> Sort / filter via CSS only. Does not conflict with DOM owners, such as Quark.</li>\n<li><strong>Bindable counts</strong> <code>.provision</code> is <code>{ totalRows, visibleRows, sortColumnIndex, sortDirection, filterValue }</code> — a &quot;12 of 40 rows&quot; readout is one Quark rule</li>\n<li><strong>Plain structural tags</strong> <code>&lt;data-thead&gt;</code> / <code>&lt;data-tbody&gt;</code> / <code>&lt;data-tr&gt;</code> /\n<code>&lt;data-td&gt;</code> are CSS-only — no registration cost</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Only <code>&lt;data-table&gt;</code> and <code>&lt;data-th&gt;</code> are registered custom elements.\n<code>&lt;data-thead&gt;</code>, <code>&lt;data-tbody&gt;</code>, <code>&lt;data-tr&gt;</code>, <code>&lt;data-td&gt;</code>, <code>&lt;data-tfoot&gt;</code>, and <code>&lt;data-tf&gt;</code> are plain tags — this package&#39;s CSS styles them as a table (or apply the equivalent <code>.tag-data-*</code> classes).</p>\n<p>Sort and filter are visual only (CSS <code>order</code> / <code>display</code>).\nRow nodes never move or leave the DOM, so Quark bindings and <code>iterate()</code> tables keep working.</p>\n<include-content data-language=\"html\"><template>&lt;data-table&gt;\n  &lt;data-thead&gt;\n    &lt;data-tr&gt;\n      &lt;data-th column-type=\"string\" sort-direction=\"asc\"&gt;Name&lt;/data-th&gt;\n      &lt;data-th column-type=\"number\"&gt;Age&lt;/data-th&gt;\n    &lt;/data-tr&gt;\n  &lt;/data-thead&gt;\n  &lt;data-tbody&gt;\n    &lt;data-tr&gt;&lt;data-td&gt;Adam&lt;/data-td&gt;&lt;data-td&gt;36&lt;/data-td&gt;&lt;/data-tr&gt;\n    &lt;data-tr&gt;&lt;data-td&gt;Beau&lt;/data-td&gt;&lt;data-td&gt;29&lt;/data-td&gt;&lt;/data-tr&gt;\n  &lt;/data-tbody&gt;\n&lt;/data-table&gt;</template></include-content>\n<p><code>&lt;data-tbody&gt;</code> is required — sorting and filtering both operate on its\n<code>&lt;data-tr&gt;</code> children.</p>\n<p><code>.provision</code> reports the row counts and the active sort / filter, recomputed after connect, after a sort, and after every filter change.\nRead it from a rule matching the table:</p>\n<include-content data-language=\"quark\"><template>data-table {\n  $visible: prop(\"provision\").visibleRows;\n  $total: prop(\"provision\").totalRows;\n  [bind-count] { content: \"#{$visible} of #{$total} rows\"; }\n}</template></include-content>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-filter-rows-export-as-csv\">Filter rows + export as CSV</h4>\n<p>Filtering is State: write <code>filter-value</code> / <code>filter-casing</code> on the table — here a Quark <code>@on input</code> block copies the search field into them. Matching is case-insensitive unless <code>filter-casing</code> is set.</p>\n<p>Invoke <code>--export</code> on the table (<code>&lt;button command=&quot;--export&quot; commandfor=&quot;…&quot;&gt;</code>) to download its visible rows (visual sort order). The button&#39;s <code>data-file-type</code> is <code>csv</code> (default) or <code>json</code>; <code>data-file-name</code> sets the download name; <code>data-full</code> downloads every row in DOM order, regardless of filtering / sorting.</p>\n<p>The first export button is the happy path (the table as you see it, including active filter / sort). The form below it writes <code>data-file-type</code> / <code>data-file-name</code> / <code>data-full</code> onto its button.</p>\n<p><include-content data-demo=\"filter\"></include-content></p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-data-table\">data-table</h1>\n<p>Sortable, filterable tables from plain custom tags — one behavior owner\n(<code>&lt;data-table&gt;</code> + <code>&lt;data-th&gt;</code>), everything else is CSS.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Sort</strong> Click a <code>&lt;data-th&gt;</code> to visually sort by string, number, or date</li>\n<li><strong>Filter</strong> <code>filter-value</code> hides non-matching rows</li>\n<li><strong>Export</strong> The <code>--export</code> command downloads visible / all rows as CSV / JSON</li>\n<li><strong>DOM-stable</strong> Sort / filter via CSS only. Does not conflict with DOM owners, such as Quark.</li>\n<li><strong>Bindable counts</strong> <code>.provision</code> is <code>{ totalRows, visibleRows, sortColumnIndex, sortDirection, filterValue }</code> — a &quot;12 of 40 rows&quot; readout is one Quark rule</li>\n<li><strong>Plain structural tags</strong> <code>&lt;data-thead&gt;</code> / <code>&lt;data-tbody&gt;</code> / <code>&lt;data-tr&gt;</code> /\n<code>&lt;data-td&gt;</code> are CSS-only — no registration cost</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Only <code>&lt;data-table&gt;</code> and <code>&lt;data-th&gt;</code> are registered custom elements.\n<code>&lt;data-thead&gt;</code>, <code>&lt;data-tbody&gt;</code>, <code>&lt;data-tr&gt;</code>, <code>&lt;data-td&gt;</code>, <code>&lt;data-tfoot&gt;</code>, and <code>&lt;data-tf&gt;</code> are plain tags — this package&#39;s CSS styles them as a table (or apply the equivalent <code>.tag-data-*</code> classes).</p>\n<p>Sort and filter are visual only (CSS <code>order</code> / <code>display</code>).\nRow nodes never move or leave the DOM, so Quark bindings and <code>iterate()</code> tables keep working.</p>\n<include-content data-language=\"html\"><template>&lt;data-table&gt;\n  &lt;data-thead&gt;\n    &lt;data-tr&gt;\n      &lt;data-th column-type=\"string\" sort-direction=\"asc\"&gt;Name&lt;/data-th&gt;\n      &lt;data-th column-type=\"number\"&gt;Age&lt;/data-th&gt;\n    &lt;/data-tr&gt;\n  &lt;/data-thead&gt;\n  &lt;data-tbody&gt;\n    &lt;data-tr&gt;&lt;data-td&gt;Adam&lt;/data-td&gt;&lt;data-td&gt;36&lt;/data-td&gt;&lt;/data-tr&gt;\n    &lt;data-tr&gt;&lt;data-td&gt;Beau&lt;/data-td&gt;&lt;data-td&gt;29&lt;/data-td&gt;&lt;/data-tr&gt;\n  &lt;/data-tbody&gt;\n&lt;/data-table&gt;</template></include-content>\n<p><code>&lt;data-tbody&gt;</code> is required — sorting and filtering both operate on its\n<code>&lt;data-tr&gt;</code> children.</p>\n<p><code>.provision</code> reports the row counts and the active sort / filter, recomputed after connect, after a sort, and after every filter change.\nRead it from a rule matching the table:</p>\n<include-content data-language=\"quark\"><template>data-table {\n  $visible: prop(\"provision\").visibleRows;\n  $total: prop(\"provision\").totalRows;\n  [bind-count] { content: \"#{$visible} of #{$total} rows\"; }\n}</template></include-content>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-filter-rows-export-as-csv\">Filter rows + export as CSV</h4>\n<p>Filtering is State: write <code>filter-value</code> / <code>filter-casing</code> on the table — here a Quark <code>@on input</code> block copies the search field into them. Matching is case-insensitive unless <code>filter-casing</code> is set.</p>\n<p>Invoke <code>--export</code> on the table (<code>&lt;button command=&quot;--export&quot; commandfor=&quot;…&quot;&gt;</code>) to download its visible rows (visual sort order). The button&#39;s <code>data-file-type</code> is <code>csv</code> (default) or <code>json</code>; <code>data-file-name</code> sets the download name; <code>data-full</code> downloads every row in DOM order, regardless of filtering / sorting.</p>\n<p>The first export button is the happy path (the table as you see it, including active filter / sort). The form below it writes <code>data-file-type</code> / <code>data-file-name</code> / <code>data-full</code> onto its button.</p>\n<p><include-content data-demo=\"filter\"></include-content></p>\n"
+  },
+  "installation": {
+    "name": "@excom/data-table",
+    "shortName": "data-table",
+    "version": "0.1.0",
+    "description": "<data-table> custom element",
+    "packageType": "kit-element",
+    "cdn": "<script src=\"https://unpkg.com/@excom/kit-utils/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/neutron/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/data-table@0.1.0/dist/index.umd.min.js\"></script>\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@excom/data-table@0.1.0/dist/index.css\">",
+    "install": {
+      "npm": "npm install @excom/data-table"
+    },
+    "imports": {
+      "js": "import \"@excom/data-table\";",
+      "css": "@import \"@excom/data-table\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/data-table\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/data-table\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "data-table",
+      "summary": "Sortable / filterable data table — plain tags, one behavior owner.",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "filter-casing",
+          "type": "boolean",
+          "description": "Match <code>filter-value</code> case-sensitively instead of the default case-insensitive comparison.",
+          "fieldName": "filterCasing",
+          "surface": "option"
+        },
+        {
+          "name": "filter-value",
+          "type": "string",
+          "description": "Hides <code>data-tr</code> rows (via <code>--data-tr-display: none</code>) whose text content doesn&#39;t include this value. Case-insensitive unless <code>filter-casing</code> is set. Unset / empty clears the filter. Rows stay in the DOM so Quark bindings survive.",
+          "fieldName": "filterValue",
+          "surface": "option"
+        }
+      ],
+      "events": [
+        {
+          "name": "data-table-sort",
+          "description": "Cancelable. Dispatched when the active sort column / direction changes: on connect (if a <code>data-th</code> already has <code>sort-direction</code>) and after every <code>data-th-sort</code>. Call <code>preventDefault()</code> to take over sorting yourself.",
+          "type": "DataTableSortEvent",
+          "typeExpanded": "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 }",
+          "defaultAction": "Sorts <code>event.detail.rows</code> by <code>columnIndex</code> with <code>sortFn</code> and sets <code>--data-tr-order</code> on each row (visual CSS <code>order</code> — DOM order is unchanged)."
+        }
+      ],
+      "slots": [],
+      "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"
+        }
+      ],
+      "cssClasses": [],
+      "cssAliases": [
+        {
+          "name": ":--data-table",
+          "selectors": [
+            "data-table",
+            ".tag-data-table"
+          ],
+          "kind": "element",
+          "description": ""
+        },
+        {
+          "name": ":--data-tbody",
+          "selectors": [
+            "data-tbody",
+            ".tag-data-tbody"
+          ],
+          "kind": "element",
+          "description": ""
+        },
+        {
+          "name": ":--data-td",
+          "selectors": [
+            "data-td",
+            ".tag-data-td"
+          ],
+          "kind": "element",
+          "description": ""
+        },
+        {
+          "name": ":--data-tf",
+          "selectors": [
+            "data-tf",
+            ".tag-data-tf"
+          ],
+          "kind": "element",
+          "description": ""
+        },
+        {
+          "name": ":--data-tfoot",
+          "selectors": [
+            "data-tfoot",
+            ".tag-data-tfoot"
+          ],
+          "kind": "element",
+          "description": ""
+        },
+        {
+          "name": ":--data-thead",
+          "selectors": [
+            "data-thead",
+            ".tag-data-thead"
+          ],
+          "kind": "element",
+          "description": ""
+        },
+        {
+          "name": ":--data-tr",
+          "selectors": [
+            "data-tr",
+            ".tag-data-tr"
+          ],
+          "kind": "element",
+          "description": ""
+        }
+      ],
+      "listens": [
+        {
+          "name": "data-th-sort",
+          "description": "Bubbled up from a descendant <code>data-th</code> when its <code>sort-direction</code> changes. Sets that header as the active sort column (clearing <code>sort-direction</code> from the previously active one) and emits <code>data-table-sort</code>.",
+          "type": "DataThSortEvent",
+          "typeExpanded": "CustomEvent & { type: \"data-th-sort\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+        }
+      ],
+      "commands": [
+        {
+          "name": "--export",
+          "description": "Builds a file from the table&#39;s <code>data-tr</code> / <code>data-td</code> / <code>data-th</code> text content and downloads it. Options are <code>data-*</code> on the invoker: <code>data-file-type</code> (<code>csv</code>, the default, or <code>json</code>), <code>data-file-name</code> (default <code>export_table_&lt;locale-date&gt;</code>), and <code>data-full</code> to download every row in DOM order instead of only the visible rows in visual sort order. Filtering needs no command: write <code>filter-value</code> / <code>filter-casing</code>."
+        }
+      ],
+      "defaultActions": [
+        {
+          "name": "data-table-sort",
+          "description": "Sorts <code>event.detail.rows</code> by <code>columnIndex</code> with <code>sortFn</code> and sets <code>--data-tr-order</code> on each row (visual CSS <code>order</code> — DOM order is unchanged)."
+        }
+      ],
+      "expectedChildren": [
+        {
+          "name": "descendant:data-tbody",
+          "relationship": "descendant",
+          "selector": "data-tbody",
+          "required": true,
+          "description": "Required row container. Sorting and filtering both operate on its <code>data-tr</code> children."
+        },
+        {
+          "name": "descendant:data-td",
+          "relationship": "descendant",
+          "selector": "data-td",
+          "required": true,
+          "description": "Cell within a <code>data-tr</code>, read as sortable / export cell content."
+        },
+        {
+          "name": "descendant:data-th",
+          "relationship": "descendant",
+          "selector": "data-th",
+          "required": true,
+          "description": "Sortable column header. Clicking toggles its <code>sort-direction</code> and fires <code>data-th-sort</code>, which becomes the active column."
+        },
+        {
+          "name": "descendant:data-tr",
+          "relationship": "descendant",
+          "selector": "data-tr",
+          "required": true,
+          "description": "Row, direct child of <code>data-tbody</code>. Gets <code>--data-tr-order</code> on sort and <code>--data-tr-display</code> on filter. DOM order is unchanged."
+        }
+      ],
+      "provisions": [
+        {
+          "name": "provision",
+          "type": "DataTableProvision",
+          "typeExpanded": "{ totalRows: number; visibleRows: number; sortColumnIndex: number | null; sortDirection: \"asc\" | \"desc\" | null; filterValue: string | null; }",
+          "description": "<code>{ totalRows, visibleRows, sortColumnIndex, sortDirection, filterValue }</code> — recomputed after connect, after the <code>data-table-sort</code> default action, and after every filter change. Not reflected as an attribute.",
+          "fieldName": "provision"
+        }
+      ]
+    },
+    {
+      "tag": "data-th",
+      "summary": "Sortable column header — click toggles sort direction.",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "column-type",
+          "type": "string",
+          "description": "Sort comparator to use for this column&#39;s cell values. <code>data-table</code> treats <code>null</code> as &quot;string&quot;.",
+          "fieldName": "columnType",
+          "surface": "option",
+          "values": "\"string\" | \"number\" | \"date\""
+        },
+        {
+          "name": "sort-direction",
+          "type": "string",
+          "description": "Current sort direction. A click toggles between <code>asc</code> / <code>desc</code>; setting it (by any means) fires <code>data-th-sort</code>. Only one <code>data-th</code> per table should carry this at a time — the parent <code>&lt;data-table&gt;</code> clears the previously active header when a new one is set.",
+          "fieldName": "sortDirection",
+          "surface": "hybrid",
+          "values": "\"asc\" | \"desc\""
+        }
+      ],
+      "events": [
+        {
+          "name": "data-th-sort",
+          "description": "Dispatched whenever <code>sort-direction</code> is set, whether by a click or programmatically. Bubbles to the parent <code>&lt;data-table&gt;</code>.",
+          "type": "DataThSortEvent",
+          "typeExpanded": "CustomEvent & { type: \"data-th-sort\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+        }
+      ],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [
+        {
+          "name": ":--data-th",
+          "selectors": [
+            "data-th",
+            ".tag-data-th"
+          ],
+          "kind": "element",
+          "description": ""
+        },
+        {
+          "name": ":--data-th--sort",
+          "selectors": [
+            ":is(:--data-th)"
+          ],
+          "kind": "state",
+          "description": ""
+        },
+        {
+          "name": ":--data-th--sort-asc",
+          "selectors": [
+            "[sort-direction=\"asc\"]",
+            "[aria-sort=\"ascending\"]"
+          ],
+          "kind": "state",
+          "description": ""
+        },
+        {
+          "name": ":--data-th--sort-desc",
+          "selectors": [
+            "[sort-direction=\"desc\"]",
+            "[aria-sort=\"descending\"]"
+          ],
+          "kind": "state",
+          "description": ""
+        }
+      ],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": []
+    }
+  ],
+  "exportedFiles": {}
+}