@woylie/doggo 0.16.1 → 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.1"}
+    {: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/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.1",
+  "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",