@woylie/doggo 0.16.0 → 0.17.0

package/README.md

@@ -21,11 +21,21 @@ The package can be installed by adding `doggo` to your list of dependencies in
 ```elixir
 def deps do
   [
-    {:doggo, "~> 0.16.0"}
+    {:doggo, "~> 0.17.0"}
   ]
 end
 ```
 
+Enable diagnostic checks at render time in `config/dev.exs` and
+`config/test.exs` :
+
+```elixir
+config :doggo, :diagnostics, true
+```
+
+These checks raise errors if components are not wired up correctly, for example
+if an accessible name is not set. If disabled, the checks are not compiled.
+
 ### Compatibility
 
 This package is tested against the Elixir and OTP versions that are still
@@ -172,6 +182,7 @@ import {
   MenuButton,
   SplitPane,
   Tabs,
+  Toggletip,
   Toolbar,
   Tooltip,
   Tree,
@@ -186,6 +197,7 @@ const hooks = {
   "Doggo.MenuButton": MenuButton,
   "Doggo.SplitPane": SplitPane,
   "Doggo.Tabs": Tabs,
+  "Doggo.Toggletip": Toggletip,
   "Doggo.Toolbar": Toolbar,
   "Doggo.Tooltip": Tooltip,
   "Doggo.Tree": Tree,
@@ -215,6 +227,7 @@ import {
   MenuButton,
   SplitPane,
   Tabs,
+  Toggletip,
   Toolbar,
   Tooltip,
   Tree,
@@ -231,6 +244,7 @@ import {
       "Doggo.MenuButton": MenuButton,
       "Doggo.SplitPane": SplitPane,
       "Doggo.Tabs": Tabs,
+      "Doggo.Toggletip": Toggletip,
       "Doggo.Toolbar": Toolbar,
       "Doggo.Tooltip": Tooltip,
       "Doggo.Tree": Tree,
@@ -328,6 +342,35 @@ The `data-invalid` attribute is set on the field wrapper whenever the field has
 errors. The `:empty` selector does not work here, because the rendered list
 contains whitespace.
 
+### Text direction
+
+Some components render text you pass in an attribute next to text of their
+own, such as a switch label beside its state text. These elements have
+`dir="auto"`. The browser takes their direction from the text itself, and
+right-to-left text in a left-to-right page does not reorder the text around
+it.
+
+Text you pass in a slot is not automatically isolated. If it can hold text in
+another direction, wrap it in `<bdi>`.
+
+```heex
+<.steps current_step={1}>
+  <:step><bdi>{@first_step_name}</bdi></:step>
+  <:step><bdi>{@second_step_name}</bdi></:step>
+</.steps>
+```
+
+The `field` label holds your label text next to the required or optional
+mark, without an element of its own. If your labels can be in a different
+direction than the page, set `unicode-bidi: plaintext` on the label. The
+browser then takes the label's direction from its content.
+
+```css
+.field label {
+  unicode-bidi: plaintext;
+}
+```
+
 ## Design decisions
 
 - Favor semantic HTML elements over CSS classes for structure and clarity.
@@ -338,6 +381,8 @@ contains whitespace.
   attributes.
 - The library is designed without default styles and does not prefer any
   particular CSS framework.
+- Don't render a container if it doesn't have any children, for example a
+  navigation without links.
 
 ## Demo app
 
@@ -400,6 +445,7 @@ component at any level:
 
 - Adding an attribute.
 - Adding a class.
+- Changing the whitespace between elements.
 - Removing an attribute that normally no CSS styles are attached to.
 
 These changes **are** breaking:
@@ -413,6 +459,8 @@ These changes **are** breaking:
 - Reordering elements.
 - Renaming a JavaScript hook.
 
+The output format of `mix dog.safelist` only changes in a major release.
+
 ## Feedback
 
 If you encounter any issues with a component, have suggestions for improvements,

package/assets/js/hooks/dialog.js

@@ -9,7 +9,7 @@ const hasClosedBy = () => "closedBy" in HTMLDialogElement.prototype;
 export function initDialog(dialog, { execJS = () => {} } = {}) {
   let invoke;
 
-  const dismissable = () => dialog.getAttribute("closedby") === "any";
+  const closedBy = () => dialog.getAttribute("closedby");
 
   // Dispatched by `Doggo.show_modal/2`.
   dialog.addEventListener("doggo:open", () => {
@@ -47,13 +47,13 @@ export function initDialog(dialog, { execJS = () => {} } = {}) {
     // `closedby="none"` has to hold Escape as well, which is the one part of
     // the attribute that native `<dialog>` does not give us anyway.
     dialog.addEventListener("cancel", (e) => {
-      if (!dismissable()) e.preventDefault();
+      if (closedBy() === "none") e.preventDefault();
     });
 
     // A click on the backdrop reaches the dialog itself, never a child, so
     // the target is the test for being outside.
     dialog.addEventListener("click", (e) => {
-      if (dismissable() && e.target === dialog) dialog.close();
+      if (closedBy() === "any" && e.target === dialog) dialog.close();
     });
   }
 

package/assets/js/hooks/toggletip.js

@@ -0,0 +1,82 @@
+// A long announcement cannot be interrupted, so the text is cut. The region is
+// emptied afterwards, since the open panel holds the same text.
+const maxLength = 250;
+const clearAfter = 1000;
+
+const announcement = (panel) => {
+  const text = panel.textContent.replace(/\s+/g, " ").trim();
+  return text.length > maxLength ? `${text.slice(0, maxLength)}…` : text;
+};
+
+// Remove the positioning once CSS anchor positioning is widely baseline
+// available; the example CSS places the panel where it is supported.
+const anchored = () => window.CSS?.supports?.("position-area: block-end");
+
+export function initToggletip(toggletip) {
+  const button = toggletip.querySelector(":scope > button");
+  const panel = toggletip.querySelector(":scope > [popover]");
+  const status = toggletip.querySelector(':scope > [role="status"]');
+  let timer;
+
+  const place = () => {
+    const rect = button.getBoundingClientRect();
+    const rtl = getComputedStyle(toggletip).direction === "rtl";
+    const start = rtl ? window.innerWidth - rect.right : rect.left;
+
+    const style = {
+      inset: "auto",
+      margin: "0",
+      "margin-block-start": "var(--toggletip-offset)",
+      "inset-block-start": `${rect.bottom}px`,
+      "inset-inline-start": `${start}px`,
+    };
+
+    for (const [name, value] of Object.entries(style)) {
+      panel.style.setProperty(name, value);
+    }
+  };
+
+  const position = () => {
+    if (!anchored() && panel.matches(":popover-open")) place();
+  };
+
+  const beforeToggle = (e) => {
+    if (!anchored() && e.newState === "open") place();
+  };
+
+  const announce = (e) => {
+    clearTimeout(timer);
+    status.textContent = e.newState === "open" ? announcement(panel) : "";
+    timer = setTimeout(() => (status.textContent = ""), clearAfter);
+  };
+
+  panel.addEventListener("beforetoggle", beforeToggle);
+  panel.addEventListener("toggle", announce);
+  window.addEventListener("scroll", position, true);
+  window.addEventListener("resize", position);
+
+  return {
+    update: position,
+    destroy() {
+      clearTimeout(timer);
+      panel.removeEventListener("beforetoggle", beforeToggle);
+      panel.removeEventListener("toggle", announce);
+      window.removeEventListener("scroll", position, true);
+      window.removeEventListener("resize", position);
+    },
+  };
+}
+
+export default {
+  mounted() {
+    this.instance = initToggletip(this.el);
+  },
+
+  updated() {
+    this.instance.update();
+  },
+
+  destroyed() {
+    this.instance.destroy();
+  },
+};

package/assets/js/hooks/tree.js

@@ -10,7 +10,26 @@ const labelOf = (item) =>
 const parentOf = (item) =>
   item.parentElement.closest('[role="treeitem"]') || null;
 
-export function initTree(tree) {
+const labelText = (item) => {
+  const label = labelOf(item);
+
+  if (!label) return "";
+
+  const copy = label.cloneNode(true);
+
+  for (const node of copy.querySelectorAll('[aria-hidden="true"], svg')) {
+    node.remove();
+  }
+
+  return copy.textContent;
+};
+
+const domWriter = {
+  setAttribute: (el, attr, value) => el.setAttribute(attr, value),
+  removeAttribute: (el, attr) => el.removeAttribute(attr),
+};
+
+export function initTree(tree, writer = domWriter) {
   // Visible items only. A collapsed branch takes its descendants out of the
   // sequence.
   const getItems = () =>
@@ -18,22 +37,6 @@ export function initTree(tree) {
       (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;
@@ -46,7 +49,7 @@ export function initTree(tree) {
     const active = getItems()[idx];
 
     for (const item of tree.querySelectorAll('[role="treeitem"]')) {
-      item.setAttribute("tabindex", item === active ? "0" : "-1");
+      writer.setAttribute(item, "tabindex", item === active ? "0" : "-1");
     }
   };
 
@@ -56,25 +59,17 @@ export function initTree(tree) {
   };
 
   const setExpanded = (item, expanded) => {
-    item.setAttribute("aria-expanded", expanded ? "true" : "false");
+    writer.setAttribute(item, "aria-expanded", expanded ? "true" : "false");
 
     const group = groupOf(item);
 
     if (group) {
       if (expanded) {
-        group.removeAttribute("hidden");
+        writer.removeAttribute(group, "hidden");
       } else {
-        group.setAttribute("hidden", "");
+        writer.setAttribute(group, "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
@@ -106,8 +101,7 @@ export function initTree(tree) {
 
     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 labels = items.map(labelText);
     const idx = searchIndex(
       labels,
       repeated ? search[0] : search,
@@ -131,7 +125,7 @@ export function initTree(tree) {
       if (isBranch(item) && !isExpanded(item)) {
         setExpanded(item, true);
       } else if (isBranch(item)) {
-        const child = groupOf(item).querySelector('[role="treeitem"]');
+        const child = groupOf(item)?.querySelector('[role="treeitem"]');
 
         if (child) moveTo(getItems().indexOf(child));
       }
@@ -155,6 +149,7 @@ export function initTree(tree) {
 
     const nextIdx = targetIndex(e.key, currentIdx, items.length, {
       orientation: "vertical",
+      wrap: false,
     });
 
     if (nextIdx !== null) {
@@ -170,12 +165,6 @@ export function initTree(tree) {
   });
 
   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));
@@ -188,7 +177,12 @@ export function initTree(tree) {
 
 export default {
   mounted() {
-    this.instance = initTree(this.el);
+    const js = this.js();
+
+    this.instance = initTree(this.el, {
+      setAttribute: (el, attr, value) => js.setAttribute(el, attr, value),
+      removeAttribute: (el, attr) => js.removeAttribute(el, attr),
+    });
   },
 
   updated() {

package/assets/js/index.js

@@ -8,4 +8,5 @@ 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 Toggletip, initToggletip } from "./hooks/toggletip.js";
 export { default as Tooltip, initTooltip } from "./hooks/tooltip.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@woylie/doggo",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "JavaScript hooks for the Doggo component library",
   "keywords": [
     "phoenix",
@@ -29,6 +29,7 @@
     "./combobox": "./assets/js/hooks/combobox.js",
     "./tabs": "./assets/js/hooks/tabs.js",
     "./toolbar": "./assets/js/hooks/toolbar.js",
+    "./toggletip": "./assets/js/hooks/toggletip.js",
     "./tooltip": "./assets/js/hooks/tooltip.js",
     "./menu": "./assets/js/hooks/menu.js",
     "./menu_button": "./assets/js/hooks/menu_button.js",