@woylie/doggo 0.15.0

package/assets/js/hooks/tree.js

@@ -0,0 +1,197 @@
+import { clamp, searchIndex, targetIndex } from "../navigation.js";
+
+const SEARCH_MS = 500;
+
+const isBranch = (item) => item.hasAttribute("aria-expanded");
+const isExpanded = (item) => item.getAttribute("aria-expanded") === "true";
+const groupOf = (item) => item.querySelector(':scope > [role="group"]');
+const labelOf = (item) =>
+  item.querySelector(':scope > :not(button):not([role="group"])');
+const parentOf = (item) =>
+  item.parentElement.closest('[role="treeitem"]') || null;
+
+export function initTree(tree) {
+  // Visible items only. A collapsed branch takes its descendants out of the
+  // sequence.
+  const getItems = () =>
+    Array.from(tree.querySelectorAll('[role="treeitem"]')).filter(
+      (item) => !item.closest('[role="group"][hidden]'),
+    );
+
+  // The hook owns the expanded state. A patch re-renders the server's
+  // version, so it is remembered by position and applied again.
+  const pathOf = (item) => {
+    const path = [];
+
+    for (let node = item; node; node = parentOf(node)) {
+      const siblings = Array.from(
+        node.parentElement.querySelectorAll(':scope > [role="treeitem"]'),
+      );
+      path.unshift(siblings.indexOf(node));
+    }
+
+    return path.join("-");
+  };
+
+  const expandedPaths = new Set();
+  let activeIdx = 0;
+  let search = "";
+  let searchTimeout;
+
+  // Every item, not just the visible ones: a hidden item would keep the tab
+  // index it had before the collapse.
+  const setActive = (idx) => {
+    activeIdx = idx;
+
+    const active = getItems()[idx];
+
+    for (const item of tree.querySelectorAll('[role="treeitem"]')) {
+      item.setAttribute("tabindex", item === active ? "0" : "-1");
+    }
+  };
+
+  const moveTo = (idx) => {
+    setActive(idx);
+    getItems()[idx].focus();
+  };
+
+  const setExpanded = (item, expanded) => {
+    item.setAttribute("aria-expanded", expanded ? "true" : "false");
+
+    const group = groupOf(item);
+
+    if (group) {
+      if (expanded) {
+        group.removeAttribute("hidden");
+      } else {
+        group.setAttribute("hidden", "");
+      }
+    }
+
+    const path = pathOf(item);
+
+    if (expanded) {
+      expandedPaths.add(path);
+    } else {
+      expandedPaths.delete(path);
+    }
+  };
+
+  // Only the caret toggles. A click on the label is the caller's, for
+  // selection. The caret is `aria-hidden`: the arrow keys already do this.
+  tree.addEventListener("click", (e) => {
+    const item = e.target.closest('[role="treeitem"]');
+
+    if (!item || !isBranch(item)) return;
+
+    // The item's own caret, not one a caller put in the label.
+    const caret = item.querySelector(":scope > button");
+
+    if (!caret || !caret.contains(e.target)) return;
+
+    setExpanded(item, !isExpanded(item));
+    item.focus();
+  });
+
+  tree.addEventListener("focusin", (e) => {
+    const idx = getItems().indexOf(e.target.closest('[role="treeitem"]'));
+
+    if (idx >= 0 && idx !== activeIdx) setActive(idx);
+  });
+
+  const typeAhead = (key) => {
+    clearTimeout(searchTimeout);
+    search += key;
+    searchTimeout = setTimeout(() => (search = ""), SEARCH_MS);
+
+    const repeated = [...search].every((char) => char === search[0]);
+    const items = getItems();
+    // The item's own label, but not nested items.
+    const labels = items.map((item) => labelOf(item)?.textContent ?? "");
+    const idx = searchIndex(
+      labels,
+      repeated ? search[0] : search,
+      repeated ? activeIdx : activeIdx - 1,
+    );
+
+    if (idx !== null) moveTo(idx);
+  };
+
+  tree.addEventListener("keydown", (e) => {
+    const items = getItems();
+    const item = e.target.closest('[role="treeitem"]');
+    const currentIdx = items.indexOf(item);
+
+    if (currentIdx < 0) return;
+
+    // Right opens a branch, then walks into it. Left closes it, then walks out.
+    if (e.key === "ArrowRight") {
+      e.preventDefault();
+
+      if (isBranch(item) && !isExpanded(item)) {
+        setExpanded(item, true);
+      } else if (isBranch(item)) {
+        const child = groupOf(item).querySelector('[role="treeitem"]');
+
+        if (child) moveTo(getItems().indexOf(child));
+      }
+
+      return;
+    }
+
+    if (e.key === "ArrowLeft") {
+      e.preventDefault();
+
+      if (isBranch(item) && isExpanded(item)) {
+        setExpanded(item, false);
+      } else {
+        const parent = parentOf(item);
+
+        if (parent) moveTo(getItems().indexOf(parent));
+      }
+
+      return;
+    }
+
+    const nextIdx = targetIndex(e.key, currentIdx, items.length, {
+      orientation: "vertical",
+    });
+
+    if (nextIdx !== null) {
+      e.preventDefault();
+      moveTo(nextIdx);
+      return;
+    }
+
+    if (e.key.length === 1 && !e.metaKey && !e.ctrlKey && !e.altKey) {
+      e.preventDefault();
+      typeAhead(e.key);
+    }
+  });
+
+  const restore = () => {
+    for (const item of tree.querySelectorAll('[role="treeitem"]')) {
+      if (isBranch(item) && expandedPaths.has(pathOf(item))) {
+        setExpanded(item, true);
+      }
+    }
+
+    const items = getItems();
+
+    if (items.length > 0) setActive(clamp(activeIdx, items.length));
+  };
+
+  restore();
+
+  return { update: restore };
+}
+
+export default {
+  mounted() {
+    this.instance = initTree(this.el);
+  },
+
+  updated() {
+    this.instance.update();
+  },
+};

package/assets/js/index.js

@@ -0,0 +1,11 @@
+export { default as Accordion, initAccordion } from "./hooks/accordion.js";
+export { default as Carousel, initCarousel } from "./hooks/carousel.js";
+export { default as Combobox, initCombobox } from "./hooks/combobox.js";
+export { default as Dialog, initDialog } from "./hooks/dialog.js";
+export { default as Menu, initMenu } from "./hooks/menu.js";
+export { default as MenuButton, initMenuButton } from "./hooks/menu_button.js";
+export { default as SplitPane, initSplitPane } from "./hooks/split_pane.js";
+export { default as Tabs, initTabs } from "./hooks/tabs.js";
+export { default as Tree, initTree } from "./hooks/tree.js";
+export { default as Toolbar, initToolbar } from "./hooks/toolbar.js";
+export { default as Tooltip, initTooltip } from "./hooks/tooltip.js";

package/assets/js/navigation.js

@@ -0,0 +1,69 @@
+// Keeps an index within a list of `total` elements.
+export function clamp(idx, total) {
+  return Math.min(Math.max(idx, 0), total - 1);
+}
+
+// Adds `offset` to `idx` while staying within the total range. Wraps around at
+// the ends if `wrap` is true.
+export function stepIndex(idx, offset, total, { wrap = true } = {}) {
+  if (wrap) return (idx + offset + total) % total;
+
+  return clamp(idx + offset, total);
+}
+
+// Returns the index the key moves to, or `null` if the key is not an arrow,
+// Home or End. The caller passes the current index, because each hook gets it
+// from somewhere else: the carousel from the slide in view, tabs and toolbars
+// from the focused element.
+export function targetIndex(
+  key,
+  currentIdx,
+  total,
+  { orientation = "horizontal", wrap = true } = {},
+) {
+  const [previous, next] =
+    orientation === "vertical"
+      ? ["ArrowUp", "ArrowDown"]
+      : ["ArrowLeft", "ArrowRight"];
+
+  if (key === next) return stepIndex(currentIdx, 1, total, { wrap });
+  if (key === previous) return stepIndex(currentIdx, -1, total, { wrap });
+  if (key === "Home") return 0;
+  if (key === "End") return total - 1;
+
+  return null;
+}
+
+// Sets `tabindex` to 0 on the element at `activeIdx` and to -1 on the rest, so
+// that the list is one tab stop.
+export function setRovingTabindex(elements, activeIdx) {
+  elements.forEach((el, idx) => {
+    el.setAttribute("tabindex", idx === activeIdx ? "0" : "-1");
+  });
+}
+
+// Sets `aria-selected` to true on the tab at `activeIdx` and to false on the
+// rest, and sets `tabindex` the same way as above. Used by `tabs` and by the
+// carousel pagination, which is also a tab list.
+export function selectTab(tabs, activeIdx) {
+  tabs.forEach((tab, idx) => {
+    tab.setAttribute("aria-selected", idx === activeIdx ? "true" : "false");
+  });
+
+  setRovingTabindex(tabs, activeIdx);
+}
+
+// Returns the index of the next label starting with `search`, after `fromIdx`,
+// wrapping around, or `null` if none matches. Used for type-ahead in menus.
+export function searchIndex(labels, search, fromIdx) {
+  const needle = search.toLowerCase();
+  const total = labels.length;
+
+  for (let offset = 1; offset <= total; offset++) {
+    const idx = (fromIdx + offset) % total;
+
+    if (labels[idx].trim().toLowerCase().startsWith(needle)) return idx;
+  }
+
+  return null;
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@woylie/doggo",
+  "version": "0.15.0",
+  "description": "JavaScript hooks for the Doggo component library",
+  "keywords": [
+    "phoenix",
+    "liveview",
+    "hooks",
+    "components",
+    "accessibility"
+  ],
+  "homepage": "https://hexdocs.pm/doggo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/woylie/doggo.git"
+  },
+  "bugs": "https://github.com/woylie/doggo/issues",
+  "author": "Mathias Polligkeit",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "assets/js/index.js",
+  "exports": {
+    ".": "./assets/js/index.js",
+    "./accordion": "./assets/js/hooks/accordion.js",
+    "./carousel": "./assets/js/hooks/carousel.js",
+    "./combobox": "./assets/js/hooks/combobox.js",
+    "./tabs": "./assets/js/hooks/tabs.js",
+    "./toolbar": "./assets/js/hooks/toolbar.js",
+    "./tooltip": "./assets/js/hooks/tooltip.js",
+    "./menu": "./assets/js/hooks/menu.js",
+    "./menu_button": "./assets/js/hooks/menu_button.js",
+    "./tree": "./assets/js/hooks/tree.js",
+    "./dialog": "./assets/js/hooks/dialog.js",
+    "./split_pane": "./assets/js/hooks/split_pane.js"
+  },
+  "files": [
+    "assets/js"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.9.1",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.11.0",
+    "happy-dom": "^20.11.15",
+    "prettier": "^3.9.6",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "lint": "pnpm run lint:prettier && pnpm run lint:eslint",
+    "lint:eslint": "eslint assets",
+    "lint:eslint:fix": "eslint assets --fix",
+    "lint:fix": "pnpm run lint:prettier:fix && pnpm run lint:eslint:fix",
+    "lint:prettier": "prettier assets --check",
+    "lint:prettier:fix": "prettier assets --write",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}