pageship 0.1.1 → 0.3.0

package/dist/skills/pageship-table/references/sort-and-filter.md

@@ -0,0 +1,235 @@
+# Sort and filter
+
+Use this markup, stylesheet and script as written. Change only the ids, the labels, the filter values and the column numbers. The script works on every `<figure class="table-figure" data-table>` in the file, so one copy serves all tables.
+
+## Markup
+
+The controls sit in the figure, between the caption and the table box. Leave out the parts the table doesn't need: a filter, the search box or the sort buttons.
+
+```html
+<figure class="table-figure" data-table>
+  <figcaption id="queues">Tickets by queue, Q3 2026, from the help desk export.</figcaption>
+  <div class="table-controls">
+    <span id="queues-region">Region</span>
+    <div role="group" aria-labelledby="queues-region" data-filter-by="group">
+      <button type="button" data-filter="" aria-pressed="true">All</button>
+      <button type="button" data-filter="EMEA" aria-pressed="false">EMEA</button>
+      <button type="button" data-filter="APAC" aria-pressed="false">APAC</button>
+    </div>
+    <input type="search" data-search aria-label="Find a queue" placeholder="Find a queue" />
+    <button type="button" data-reset>Reset</button>
+    <p data-count aria-live="polite"></p>
+  </div>
+  <div class="table-scroll" role="region" tabindex="0" aria-labelledby="queues">
+    <table aria-labelledby="queues">
+      <thead>
+        <tr>
+          <th scope="col"><button type="button" data-sort="text">Queue</button></th>
+          <th scope="col" class="num"><button type="button" data-sort="number">Tickets</button></th>
+          <th scope="col" class="num">
+            <button type="button" data-sort="number">Median first response</button>
+          </th>
+        </tr>
+      </thead>
+      <tbody data-group="EMEA">
+        <tr>
+          <th scope="rowgroup" colspan="3">EMEA</th>
+        </tr>
+        <tr>
+          <th scope="row">Billing</th>
+          <td class="num" data-value="1140">1,140</td>
+          <td class="num" data-value="220">3 h 40 min</td>
+        </tr>
+      </tbody>
+      <tbody data-group="APAC">
+        <tr>
+          <th scope="rowgroup" colspan="3">APAC</th>
+        </tr>
+        <tr>
+          <th scope="row">Billing</th>
+          <td class="num" data-value="265">265</td>
+          <td class="num">Not given</td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+  <p class="table-empty" hidden>No rows match. Reset to show every row.</p>
+</figure>
+```
+
+- **Sort buttons** go inside the header cells of the columns a reader ranks by. `data-sort="number"` sorts largest first and `data-sort="text"` from A; a second press reverses. Rows sort within their group.
+- **`data-value`** holds a plain number on every cell of a number column whose text is not one, such as `1,140`, `18%` or `3 h 40 min` (in one unit down the column, here minutes). Leave it off a "Not given" cell; those rows sort last.
+- **A filter** is a `role="group"` of buttons. With `data-filter-by="group"`, each button's `data-filter` names a `<tbody>` by its `data-group`. With `data-filter-by` set to a column number, counted from 0 with the row label as column 0, each button keeps the rows whose cell in that column reads exactly its `data-filter`. The `All` button's `data-filter` is empty.
+- **The search box** keeps the rows whose text contains what the reader types. Keep its `aria-label`, and keep it outside any `form`.
+- Every body row is a plain row of cells, apart from the one group heading row that opens each `<tbody>`.
+
+## Stylesheet
+
+Add this after the table stylesheet from the skill.
+
+```css
+.table-controls {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem 1rem;
+  align-items: center;
+  margin: 0.75rem 0;
+}
+.table-controls [role="group"] {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem;
+}
+.table-controls button,
+.table-controls input {
+  font: inherit;
+  font-size: 0.875rem;
+  color: var(--fg);
+  background: var(--bg);
+  border: 1px solid var(--muted);
+  border-radius: 4px;
+  padding: 0.25rem 0.625rem;
+}
+.table-controls button[aria-pressed="true"] {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: var(--bg);
+  font-weight: 600;
+}
+.table-scroll th button[data-sort] {
+  font: inherit;
+  color: inherit;
+  background: none;
+  border: 0;
+  padding: 0;
+  cursor: pointer;
+  text-align: inherit;
+}
+.table-scroll th button[data-sort]::after {
+  content: " \2195";
+  color: var(--muted);
+}
+.table-scroll th[aria-sort="ascending"] button::after {
+  content: " \2191";
+  color: inherit;
+}
+.table-scroll th[aria-sort="descending"] button::after {
+  content: " \2193";
+  color: inherit;
+}
+@media print {
+  .table-scroll th button[data-sort] {
+    display: inline !important;
+  }
+  .table-scroll th button[data-sort]::after {
+    content: none;
+  }
+}
+```
+
+## Script
+
+Put it in one `<script>` element at the end of `<body>`.
+
+```js
+for (const figure of document.querySelectorAll("figure[data-table]")) {
+  const groups = [...figure.querySelectorAll("tbody")].map((body) => {
+    const heading = body.rows[0]?.querySelector('th[scope="rowgroup"]') ? body.rows[0] : null;
+    return { body, heading, rows: [...body.rows].filter((row) => row !== heading) };
+  });
+  const total = groups.reduce((sum, group) => sum + group.rows.length, 0);
+  const sortButtons = [...figure.querySelectorAll("th button[data-sort]")];
+  const filters = [...figure.querySelectorAll("[data-filter-by]")];
+  const search = figure.querySelector("input[data-search]");
+  const count = figure.querySelector("[data-count]");
+  const empty = figure.querySelector(".table-empty");
+  let sort = null;
+
+  const cellText = (row, column) => row.cells[column]?.textContent.trim() ?? "";
+  const sortKey = (row, column, type) => {
+    const raw = row.cells[column]?.dataset.value ?? cellText(row, column);
+    if (type !== "number") return raw === "" ? null : raw;
+    return raw === "" || Number.isNaN(Number(raw)) ? null : Number(raw);
+  };
+  const keeps = (filter, group, row) => {
+    const value = filter.querySelector('[aria-pressed="true"]')?.dataset.filter ?? "";
+    if (value === "") return true;
+    const by = filter.dataset.filterBy;
+    return by === "group"
+      ? group.body.dataset.group === value
+      : cellText(row, Number(by)) === value;
+  };
+
+  function update() {
+    const query = search?.value.trim().toLowerCase() ?? "";
+    let shown = 0;
+    for (const group of groups) {
+      const rows = [...group.rows];
+      if (sort) {
+        const { column, type, direction } = sort;
+        rows.sort((a, b) => {
+          const x = sortKey(a, column, type);
+          const y = sortKey(b, column, type);
+          if (x === null || y === null) return (x === null) - (y === null);
+          const order =
+            type === "number" ? x - y : x.localeCompare(y, undefined, { numeric: true });
+          return direction === "ascending" ? order : -order;
+        });
+      }
+      group.body.append(...rows);
+      let groupShown = 0;
+      for (const row of rows) {
+        const match =
+          filters.every((filter) => keeps(filter, group, row)) &&
+          (query === "" || row.textContent.toLowerCase().includes(query));
+        row.hidden = !match;
+        if (match) groupShown += 1;
+      }
+      if (group.heading) group.heading.hidden = groupShown === 0;
+      shown += groupShown;
+    }
+    for (const button of sortButtons) {
+      const th = button.closest("th");
+      if (sort?.column === th.cellIndex) th.setAttribute("aria-sort", sort.direction);
+      else th.removeAttribute("aria-sort");
+    }
+    if (count) count.textContent = `Showing ${shown} of ${total} rows`;
+    if (empty) empty.hidden = shown > 0;
+  }
+
+  for (const button of sortButtons) {
+    button.addEventListener("click", () => {
+      const column = button.closest("th").cellIndex;
+      const type = button.dataset.sort;
+      // Numbers start largest first and text starts at A; a second press reverses.
+      const first = type === "number" ? "descending" : "ascending";
+      const other = first === "ascending" ? "descending" : "ascending";
+      const direction = sort?.column === column && sort.direction === first ? other : first;
+      sort = { column, type, direction };
+      update();
+    });
+  }
+  for (const filter of filters) {
+    for (const button of filter.querySelectorAll("button[data-filter]")) {
+      button.addEventListener("click", () => {
+        for (const other of filter.querySelectorAll("button[data-filter]")) {
+          other.setAttribute("aria-pressed", String(other === button));
+        }
+        update();
+      });
+    }
+  }
+  search?.addEventListener("input", update);
+  figure.querySelector("button[data-reset]")?.addEventListener("click", () => {
+    sort = null;
+    for (const filter of filters) {
+      for (const button of filter.querySelectorAll("button[data-filter]")) {
+        button.setAttribute("aria-pressed", String(button.dataset.filter === ""));
+      }
+    }
+    if (search) search.value = "";
+    update();
+  });
+  update();
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pageship",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Pageship CLI for checking server API compatibility.",
   "license": "UNLICENSED",
   "repository": {