npm - drab - Versions diffs - 6.0.0 → 6.1.0 - Mend

drab 6.0.0 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/dist/announcer/define.d.ts +1 -0
package/dist/announcer/define.js +3 -0
package/dist/announcer/index.d.ts +49 -0
package/dist/announcer/index.js +80 -0
package/dist/base/copy/index.js +1 -0
package/dist/base/define.js +2 -1
package/dist/base/index.d.ts +8 -8
package/dist/base/index.js +15 -9
package/dist/contextmenu/define.js +2 -1
package/dist/copy/define.js +2 -1
package/dist/define.js +3 -2
package/dist/dialog/define.js +2 -1
package/dist/editor/define.js +2 -1
package/dist/editor/index.d.ts +5 -0
package/dist/fullscreen/define.js +2 -1
package/dist/index.d.ts +13 -12
package/dist/index.js +13 -12
package/dist/intersect/define.js +2 -1
package/dist/prefetch/define.js +2 -1
package/dist/share/define.js +2 -1
package/dist/tablesort/define.js +2 -1
package/dist/tablesort/index.d.ts +4 -0
package/dist/tablesort/index.js +32 -20
package/dist/util/define.d.ts +8 -0
package/dist/util/define.js +11 -0
package/dist/wakelock/define.js +2 -1
package/dist/wakelock/index.js +2 -0
package/dist/youtube/define.js +2 -1
package/package.json +9 -1

package/dist/announcer/define.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export {};

package/dist/announcer/define.js ADDED Viewed

@@ -0,0 +1,3 @@
+import { define } from "../util/define.js";
+import { Announcer } from "./index.js";
+define("drab-announcer", Announcer);

package/dist/announcer/index.d.ts ADDED Viewed

@@ -0,0 +1,49 @@
+/**
+ * Use the `Announcer` element to create a visually hidden ARIA live region
+ * that announces content changes to screen readers. Use this element when you
+ * need to announce changes to screen readers that something has changed. If changed
+ * element is visible on the page, add the appropriate ARIA live attribute to the
+ * visible element instead of using this announcer.
+ *
+ * It's recommended to create this element with JavaScript using the `Announcer.init` method,
+ * then you can reuse the same announcer throughout the application to
+ * [avoid duplicate regions](https://www.sarasoueidan.com/blog/accessible-notifications-with-aria-live-regions-part-2/#limit-the-number-of-live-regions-on-the-page)
+ * (see below).
+ *
+ * `aria-live`
+ *
+ * By default, the announcer is created with the
+ * [`polite` ARIA live attribute](https://www.sarasoueidan.com/blog/accessible-notifications-with-aria-live-regions-part-1/#1.-using-the-aria-live-attribute).
+ *
+ * @example
+ *
+ * ```ts
+ * import { Announcer } from "drab/announcer";
+ *
+ * // creates and appends a new announcer to the body element
+ * const announcer = Announcer.init();
+ *
+ * // create announcement
+ * announcer.announce("message");
+ * ```
+ *
+ * > The `Base` element creates a single `Announcer` to share between all elements
+ * > that can be accessed through `this.announce`. If you are using one of drab's other
+ * > elements you can call `announce` directly on the element to announce changes.
+ */
+export declare class Announcer extends HTMLElement {
+    constructor();
+    connectedCallback(): void;
+    /**
+     * @param message message to announce to screen readers
+     */
+    announce(message: string): void;
+    /**
+     * Helper method to create a new `Announcer` element named `drab-announcer`
+     * and append the element to the `<body>` tag. If an announcer already exists
+     * on the page it will return the existing element.
+     *
+     * @returns the created or existing `Announcer` element
+     */
+    static init(): Announcer;
+}

package/dist/announcer/index.js ADDED Viewed

@@ -0,0 +1,80 @@
+import { define } from "../util/define.js";
+/**
+ * Use the `Announcer` element to create a visually hidden ARIA live region
+ * that announces content changes to screen readers. Use this element when you
+ * need to announce changes to screen readers that something has changed. If changed
+ * element is visible on the page, add the appropriate ARIA live attribute to the
+ * visible element instead of using this announcer.
+ *
+ * It's recommended to create this element with JavaScript using the `Announcer.init` method,
+ * then you can reuse the same announcer throughout the application to
+ * [avoid duplicate regions](https://www.sarasoueidan.com/blog/accessible-notifications-with-aria-live-regions-part-2/#limit-the-number-of-live-regions-on-the-page)
+ * (see below).
+ *
+ * `aria-live`
+ *
+ * By default, the announcer is created with the
+ * [`polite` ARIA live attribute](https://www.sarasoueidan.com/blog/accessible-notifications-with-aria-live-regions-part-1/#1.-using-the-aria-live-attribute).
+ *
+ * @example
+ *
+ * ```ts
+ * import { Announcer } from "drab/announcer";
+ *
+ * // creates and appends a new announcer to the body element
+ * const announcer = Announcer.init();
+ *
+ * // create announcement
+ * announcer.announce("message");
+ * ```
+ *
+ * > The `Base` element creates a single `Announcer` to share between all elements
+ * > that can be accessed through `this.announce`. If you are using one of drab's other
+ * > elements you can call `announce` directly on the element to announce changes.
+ */
+export class Announcer extends HTMLElement {
+    constructor() {
+        super();
+    }
+    connectedCallback() {
+        this.style.position = "absolute";
+        this.style.width = "1px";
+        this.style.height = "1px";
+        this.style.padding = "0";
+        this.style.margin = "-1px";
+        this.style.overflow = "hidden";
+        this.style.clipPath = "rect(0, 0, 0, 0)";
+        this.style.whiteSpace = "nowrap";
+        this.style.borderWidth = "0";
+        if (!this.ariaLive)
+            this.ariaLive = "polite";
+    }
+    /**
+     * @param message message to announce to screen readers
+     */
+    announce(message) {
+        // this ensures multiple messages will be read in succession
+        const span = document.createElement("span");
+        span.textContent = message;
+        this.append(span);
+        // https://www.sarasoueidan.com/blog/accessible-notifications-with-aria-live-regions-part-2/#empty-the-live-region-and-wait-a-bit-in-between-updates
+        setTimeout(() => span.remove(), 10000);
+    }
+    /**
+     * Helper method to create a new `Announcer` element named `drab-announcer`
+     * and append the element to the `<body>` tag. If an announcer already exists
+     * on the page it will return the existing element.
+     *
+     * @returns the created or existing `Announcer` element
+     */
+    static init() {
+        define("drab-announcer", this);
+        const name = "drab-announcer";
+        let announcer = document.querySelector(name);
+        if (!announcer) {
+            announcer = document.createElement(name);
+            document.body.append(announcer);
+        }
+        return announcer;
+    }
+}

package/dist/base/copy/index.js CHANGED Viewed

@@ -19,6 +19,7 @@ export class BaseCopy extends Base {
      * @param text The `text` to share
      */
     async copy(text = this.value) {
+        this.announce(`copied ${text} to clipboard`);
         await navigator.clipboard.writeText(text);
         this.swapContent();
     }

package/dist/base/define.js CHANGED Viewed

@@ -1,2 +1,3 @@
+import { define } from "../util/define.js";
 import { Base } from "./index.js";
-customElements.define("drab-base", Base);
+define("drab-base", Base);

package/dist/base/index.d.ts CHANGED Viewed

@@ -27,14 +27,18 @@ export declare class Base extends HTMLElement {
      */
     get event(): keyof HTMLElementEventMap;
     set event(value: keyof HTMLElementEventMap);
+    /**
+     * @param message message to announce to screen readers
+     */
+    announce(message: string): void;
     /**
      * @returns All of the elements that match the `trigger` selector.
      * @default this.querySelectorAll("[data-trigger]")
      */
     getTrigger<T extends HTMLElement = HTMLElement>(): NodeListOf<T>;
     /**
-     * @param instance The instance of the desired element, ex: `HTMLDialogElement`.
-     * Defaults to `HTMLElement`.
+     * @param instance The instance of the desired element to validate against,
+     * ex: `HTMLDialogElement`. Defaults to `HTMLElement`.
      * @returns The element that matches the `content` selector.
      * @default this.querySelector("[data-content]")
      */
@@ -67,16 +71,12 @@ export declare class Base extends HTMLElement {
      * The reason for this is to make these elements work better with frameworks like Svelte. For SSR this isn't necessary, but when client side rendering, the HTML within the custom element isn't available before `connectedCallback` is called. By waiting until the next microtask, the HTML content is available---then for example, listeners can be attached to elements inside.
      */
     mount(): void;
-    /**
-     * Called when custom element is added to the page.
-     */
+    /** Called when custom element is added to the page. */
     connectedCallback(): void;
     /**
      * Passed into `disconnectedCallback`, since `Base` needs to run `disconnectedCallback` as well. It is overridden in each element that needs to run `disconnectedCallback`.
      */
     destroy(): void;
-    /**
-     * Called when custom element is removed from the page.
-     */
+    /** Called when custom element is removed from the page. */
     disconnectedCallback(): void;
 }

package/dist/base/index.js CHANGED Viewed

@@ -1,3 +1,4 @@
+import { Announcer } from "../announcer/index.js";
 /**
  * Each element in the library extends the `Base` class. It provides methods
  * for selecting elements via HTML attributes along with other helpers.
@@ -12,8 +13,11 @@
  */
 export class Base extends HTMLElement {
     /**
-     * To clean up event listeners added to `document` when the element is removed.
+     * A single `Announcer` element to share between all drab elements to announce
+     * interactive changes.
      */
+    static #announcer = Announcer.init();
+    /** To clean up event listeners added to `document` when the element is removed. */
     #listenerController = new AbortController();
     constructor() {
         super();
@@ -31,6 +35,12 @@ export class Base extends HTMLElement {
     set event(value) {
         this.setAttribute("event", value);
     }
+    /**
+     * @param message message to announce to screen readers
+     */
+    announce(message) {
+        Base.#announcer.announce(message);
+    }
     /**
      * @returns All of the elements that match the `trigger` selector.
      * @default this.querySelectorAll("[data-trigger]")
@@ -40,8 +50,8 @@ export class Base extends HTMLElement {
         return triggers;
     }
     /**
-     * @param instance The instance of the desired element, ex: `HTMLDialogElement`.
-     * Defaults to `HTMLElement`.
+     * @param instance The instance of the desired element to validate against,
+     * ex: `HTMLDialogElement`. Defaults to `HTMLElement`.
      * @returns The element that matches the `content` selector.
      * @default this.querySelector("[data-content]")
      */
@@ -115,9 +125,7 @@ export class Base extends HTMLElement {
      * The reason for this is to make these elements work better with frameworks like Svelte. For SSR this isn't necessary, but when client side rendering, the HTML within the custom element isn't available before `connectedCallback` is called. By waiting until the next microtask, the HTML content is available---then for example, listeners can be attached to elements inside.
      */
     mount() { }
-    /**
-     * Called when custom element is added to the page.
-     */
+    /** Called when custom element is added to the page. */
     connectedCallback() {
         queueMicrotask(() => this.mount());
     }
@@ -125,9 +133,7 @@ export class Base extends HTMLElement {
      * Passed into `disconnectedCallback`, since `Base` needs to run `disconnectedCallback` as well. It is overridden in each element that needs to run `disconnectedCallback`.
      */
     destroy() { }
-    /**
-     * Called when custom element is removed from the page.
-     */
+    /** Called when custom element is removed from the page. */
     disconnectedCallback() {
         this.destroy();
         this.#listenerController.abort();

package/dist/contextmenu/define.js CHANGED Viewed

@@ -1,2 +1,3 @@
+import { define } from "../util/define.js";
 import { ContextMenu } from "./index.js";
-customElements.define("drab-contextmenu", ContextMenu);
+define("drab-contextmenu", ContextMenu);

package/dist/copy/define.js CHANGED Viewed

@@ -1,2 +1,3 @@
+import { define } from "../util/define.js";
 import { Copy } from "./index.js";
-customElements.define("drab-copy", Copy);
+define("drab-copy", Copy);

package/dist/define.js CHANGED Viewed

@@ -1,4 +1,5 @@
 import * as elements from "./index.js";
-for (const [key, value] of Object.entries(elements)) {
-    customElements.define(`drab-${key.toLowerCase()}`, value);
+import { define } from "./util/define.js";
+for (const [name, Constructor] of Object.entries(elements)) {
+    define(`drab-${name.toLowerCase()}`, Constructor);
 }

package/dist/dialog/define.js CHANGED Viewed

@@ -1,2 +1,3 @@
+import { define } from "../util/define.js";
 import { Dialog } from "./index.js";
-customElements.define("drab-dialog", Dialog);
+define("drab-dialog", Dialog);

package/dist/editor/define.js CHANGED Viewed

@@ -1,2 +1,3 @@
+import { define } from "../util/define.js";
 import { Editor } from "./index.js";
-customElements.define("drab-editor", Editor);
+define("drab-editor", Editor);

package/dist/editor/index.d.ts CHANGED Viewed

@@ -1,5 +1,10 @@
 import { Base, type BaseAttributes } from "../base/index.js";
 export type EditorAttributes = BaseAttributes;
+export type EditorTriggerAttributes = {
+    "data-value": string;
+    "data-key": string;
+    "data-type": "block" | "wrap" | "inline";
+};
 /**
  * A piece of content to insert into the `textarea`.
  */

package/dist/fullscreen/define.js CHANGED Viewed

@@ -1,2 +1,3 @@
+import { define } from "../util/define.js";
 import { Fullscreen } from "./index.js";
-customElements.define("drab-fullscreen", Fullscreen);
+define("drab-fullscreen", Fullscreen);

package/dist/index.d.ts CHANGED Viewed

@@ -1,12 +1,13 @@
-export { Base, type BaseAttributes } from "./base/index.js";
-export { ContextMenu, type ContextMenuAttributes, } from "./contextmenu/index.js";
-export { Copy, type CopyAttributes } from "./copy/index.js";
-export { Dialog, type DialogAttributes } from "./dialog/index.js";
-export { Editor, type EditorAttributes } from "./editor/index.js";
-export { Fullscreen, type FullscreenAttributes } from "./fullscreen/index.js";
-export { Intersect, type IntersectAttributes } from "./intersect/index.js";
-export { Prefetch, type PrefetchAttributes } from "./prefetch/index.js";
-export { Share, type ShareAttributes } from "./share/index.js";
-export { TableSort, type TableSortAttributes } from "./tablesort/index.js";
-export { WakeLock, type WakeLockAttributes } from "./wakelock/index.js";
-export { YouTube, type YouTubeAttributes } from "./youtube/index.js";
+export * from "./announcer/index.js";
+export * from "./base/index.js";
+export * from "./contextmenu/index.js";
+export * from "./copy/index.js";
+export * from "./dialog/index.js";
+export * from "./editor/index.js";
+export * from "./fullscreen/index.js";
+export * from "./intersect/index.js";
+export * from "./prefetch/index.js";
+export * from "./share/index.js";
+export * from "./tablesort/index.js";
+export * from "./wakelock/index.js";
+export * from "./youtube/index.js";

package/dist/index.js CHANGED Viewed

@@ -1,12 +1,13 @@
-export { Base } from "./base/index.js";
-export { ContextMenu, } from "./contextmenu/index.js";
-export { Copy } from "./copy/index.js";
-export { Dialog } from "./dialog/index.js";
-export { Editor } from "./editor/index.js";
-export { Fullscreen } from "./fullscreen/index.js";
-export { Intersect } from "./intersect/index.js";
-export { Prefetch } from "./prefetch/index.js";
-export { Share } from "./share/index.js";
-export { TableSort } from "./tablesort/index.js";
-export { WakeLock } from "./wakelock/index.js";
-export { YouTube } from "./youtube/index.js";
+export * from "./announcer/index.js";
+export * from "./base/index.js";
+export * from "./contextmenu/index.js";
+export * from "./copy/index.js";
+export * from "./dialog/index.js";
+export * from "./editor/index.js";
+export * from "./fullscreen/index.js";
+export * from "./intersect/index.js";
+export * from "./prefetch/index.js";
+export * from "./share/index.js";
+export * from "./tablesort/index.js";
+export * from "./wakelock/index.js";
+export * from "./youtube/index.js";

package/dist/intersect/define.js CHANGED Viewed

@@ -1,2 +1,3 @@
+import { define } from "../util/define.js";
 import { Intersect } from "./index.js";
-customElements.define("drab-intersect", Intersect);
+define("drab-intersect", Intersect);

package/dist/prefetch/define.js CHANGED Viewed

@@ -1,2 +1,3 @@
+import { define } from "../util/define.js";
 import { Prefetch } from "./index.js";
-customElements.define("drab-prefetch", Prefetch);
+define("drab-prefetch", Prefetch);

package/dist/share/define.js CHANGED Viewed

@@ -1,2 +1,3 @@
+import { define } from "../util/define.js";
 import { Share } from "./index.js";
-customElements.define("drab-share", Share);
+define("drab-share", Share);

package/dist/tablesort/define.js CHANGED Viewed

@@ -1,2 +1,3 @@
+import { define } from "../util/define.js";
 import { TableSort } from "./index.js";
-customElements.define("drab-tablesort", TableSort);
+define("drab-tablesort", TableSort);

package/dist/tablesort/index.d.ts CHANGED Viewed

@@ -1,5 +1,9 @@
 import { Base, type BaseAttributes } from "../base/index.js";
 export type TableSortAttributes = BaseAttributes;
+export type TableSortTriggerAttributes = {
+    "data-type": "string" | "boolean" | "number";
+    "data-value": string;
+};
 /**
  * Wrap a `HTMLTableElement` in the `TableSort` element to have sortable column
  * headers. Set each `th` that you want to sort to the `trigger`. Set the `tbody`

package/dist/tablesort/index.js CHANGED Viewed

@@ -20,7 +20,7 @@ export class TableSort extends Base {
      * Removes `data-asc` or `data-desc` from other triggers then sets the correct attribute on the selected trigger.
      *
      * @param trigger
-     * @returns true if ascending, false if descending
+     * @returns `true` if ascending, `false` if descending
      */
     #setAttributes(trigger) {
         const asc = "data-asc";
@@ -43,11 +43,24 @@ export class TableSort extends Base {
     mount() {
         const tbody = this.getContent(HTMLTableSectionElement);
         for (const trigger of this.getTrigger()) {
-            trigger.addEventListener(this.event, () => {
+            trigger.tabIndex = 0;
+            trigger.role = "button";
+            const listener = () => {
+                const asc = this.#setAttributes(trigger);
                 Array.from(tbody.querySelectorAll("tr"))
-                    .sort(comparer(trigger, this.#setAttributes(trigger)))
+                    .sort(comparer(trigger, asc))
                     .forEach((tr) => tbody.appendChild(tr));
-            });
+                this.announce(`sorted table by ${trigger.textContent} in ${asc ? "ascending" : "descending"} order`);
+            };
+            trigger.addEventListener(this.event, listener);
+            if (this.event === "click") {
+                trigger.addEventListener("keydown", (e) => {
+                    if (e.key === "Enter" || e.key === " ") {
+                        e.preventDefault();
+                        listener();
+                    }
+                });
+            }
         }
     }
 }
@@ -65,23 +78,9 @@ const comparer = (th, ascending) => {
                 return collator.compare(aVal, bVal);
             }
             else if (dataType === "boolean") {
-                /**
-                 * if value is one of these and type is boolean
-                 * it should be considered falsy
-                 * since actually `Boolean("false") === true`
-                 * @param val string pulled from the textContent or attr
-                 * @returns a boolean of the provided string
-                 */
-                const convertToBoolean = (val) => {
-                    const falsy = ["0", "false", "null", "undefined"];
-                    if (falsy.includes(val)) {
-                        return false;
-                    }
-                    return Boolean(val);
-                };
-                return convertToBoolean(aVal) === convertToBoolean(bVal)
+                return falsyBoolean(aVal) === falsyBoolean(bVal)
                     ? 0
-                    : convertToBoolean(aVal)
+                    : falsyBoolean(aVal)
                         ? -1
                         : 1;
             }
@@ -107,3 +106,16 @@ const getValue = (tr, i) => {
     }
     return "";
 };
+/**
+ * if value is one of these and type is boolean
+ * it should be considered falsy
+ * since actually `Boolean("false") === true`
+ * @param val string pulled from the textContent or attr
+ * @returns a boolean of the provided string
+ */
+const falsyBoolean = (val) => {
+    if (["0", "false", "null", "undefined"].includes(val)) {
+        return false;
+    }
+    return Boolean(val);
+};

package/dist/util/define.d.ts ADDED Viewed

@@ -0,0 +1,8 @@
+/**
+ * Define a custom element to the registry. Checks if the element is
+ * defined and then names the element.
+ *
+ * @param name name of the custom element
+ * @param Constructor custom element constructor
+ */
+export declare const define: (name: string, Constructor: CustomElementConstructor) => void;

package/dist/util/define.js ADDED Viewed

@@ -0,0 +1,11 @@
+/**
+ * Define a custom element to the registry. Checks if the element is
+ * defined and then names the element.
+ *
+ * @param name name of the custom element
+ * @param Constructor custom element constructor
+ */
+export const define = (name, Constructor) => {
+    if (!customElements.get(name))
+        customElements.define(name, Constructor);
+};

package/dist/wakelock/define.js CHANGED Viewed

@@ -1,2 +1,3 @@
+import { define } from "../util/define.js";
 import { WakeLock } from "./index.js";
-customElements.define("drab-wakelock", WakeLock);
+define("drab-wakelock", WakeLock);

package/dist/wakelock/index.js CHANGED Viewed

@@ -34,9 +34,11 @@ export class WakeLock extends Base {
         if (this.#wakeLockSupported() && document.visibilityState === "visible") {
             this.wakeLock = await navigator.wakeLock.request("screen");
             this.setAttribute("locked", "");
+            this.announce("screen wake lock activated");
             this.swapContent(false);
             this.wakeLock.addEventListener("release", () => {
                 this.removeAttribute("locked");
+                this.announce("screen wake lock deactivated");
                 this.swapContent(false);
                 if (!this.#autoLock) {
                     // set to null is required, used to determine if screen should be

package/dist/youtube/define.js CHANGED Viewed

@@ -1,2 +1,3 @@
+import { define } from "../util/define.js";
 import { YouTube } from "./index.js";
-customElements.define("drab-youtube", YouTube);
+define("drab-youtube", YouTube);

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
 	"name": "drab",
 	"description": "Interactivity for You",
-	"version": "6.0.0",
+	"version": "6.1.0",
 	"homepage": "https://drab.robino.dev",
 	"license": "MIT",
 	"author": {
@@ -42,6 +42,14 @@
 			"types": "./dist/define.d.ts",
 			"default": "./dist/define.js"
 		},
+		"./announcer": {
+			"types": "./dist/announcer/index.d.ts",
+			"default": "./dist/announcer/index.js"
+		},
+		"./announcer/define": {
+			"types": "./dist/announcer/define.d.ts",
+			"default": "./dist/announcer/define.js"
+		},
 		"./base": {
 			"types": "./dist/base/index.d.ts",
 			"default": "./dist/base/index.js"