shelving 1.94.0 → 1.96.0

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.94.0",
+	"version": "1.96.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

package/react/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./useFocus.js";
 export * from "./useLazy.js";
 export * from "./useReduce.js";
 export * from "./useInstance.js";

package/react/index.js

@@ -1,4 +1,5 @@
 // Utilities.
+export * from "./useFocus.js";
 export * from "./useLazy.js";
 export * from "./useReduce.js";
 export * from "./useInstance.js";

package/react/useFocus.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="react" />
+/**
+ * Hook that puts the user's focus on an element (or the first focusable element inside that element) when it is attached to the DOM.
+ * - When the element using `useFocus()` is attached to the DOM, finds the first focusable element and calls `element.focus()` on it.
+ * - If the user tabs outside the element focus will 'wrap' and refocus inside the container until the targeted element is detached from the DOM.
+ *
+ * @param active Whether this `useFocus()` is active or not (so we can skip setting focus for modals that appear in the DOM but are minimised etc).
+ *
+ * @returns React ref that should be set on the target element you want the focus to be placed on or within.
+ */
+export declare function useFocus<T extends HTMLElement>(active?: boolean): React.RefObject<T>;

package/react/useFocus.js

@@ -0,0 +1,61 @@
+import { useEffect, useRef } from "react";
+import { addArrayItem, deleteArrayItems, getLastItem } from "../util/array.js";
+/** Stack of elements that should be keeping focus. */
+let FOCUSED;
+/** Selector for elements that can take focus */
+const FOCUSABLE = `[href], button, input, select, textarea, [tabindex]:not([tabindex="-1"])`;
+/**
+ * Focus on the first focusable element inside a container.
+ * - Checks items with an `autofocus` attribute first, then other elements.
+ */
+function _applyFocus(container, selector = FOCUSABLE) {
+    if (container.matches(selector))
+        return container.focus();
+    const child = container.querySelector(selector);
+    if (child instanceof HTMLElement)
+        return child.focus();
+}
+/**
+ * Hook that puts the user's focus on an element (or the first focusable element inside that element) when it is attached to the DOM.
+ * - When the element using `useFocus()` is attached to the DOM, finds the first focusable element and calls `element.focus()` on it.
+ * - If the user tabs outside the element focus will 'wrap' and refocus inside the container until the targeted element is detached from the DOM.
+ *
+ * @param active Whether this `useFocus()` is active or not (so we can skip setting focus for modals that appear in the DOM but are minimised etc).
+ *
+ * @returns React ref that should be set on the target element you want the focus to be placed on or within.
+ */
+export function useFocus(active = true) {
+    // Store the element in a ref.
+    const ref = useRef(null);
+    // Effect that runs when element is first attached to the DOM.
+    useEffect(() => {
+        // Set up a global listener the first time `useFocus()` is actually used.
+        if (!FOCUSED) {
+            FOCUSED = [];
+            // Add a focus listener on the body that listens for changes in focus.
+            document.body.addEventListener("focusin", () => {
+                const el = getLastItem(FOCUSED);
+                if (el && !el.contains(document.activeElement))
+                    _applyFocus(el);
+            });
+        }
+        // Only run if the element is open and the ref is attached.
+        const el = ref.current;
+        if (active && el) {
+            // Keep reference to the element that was focused before this element took the focus.
+            const lastEl = document.activeElement;
+            // Focus immediately on the first auto-focusable element now (e.g. this might just be the close button).
+            _applyFocus(el, FOCUSABLE);
+            // Add this element to the stack of elements to keep focused.
+            addArrayItem(FOCUSED, el);
+            return () => {
+                // Remove this element from the stack of elements to keep focused.
+                deleteArrayItems(FOCUSED, el);
+                // Attempt to restore the previous focus.
+                if (lastEl instanceof HTMLElement)
+                    lastEl.focus();
+            };
+        }
+    }, [ref.current, active]);
+    return ref;
+}

package/schema/OptionalSchema.d.ts

@@ -1,12 +1,14 @@
-import type { Schema } from "./Schema.js";
+import type { Schema, SchemaOptions } from "./Schema.js";
 import { ThroughSchema } from "./ThroughSchema.js";
+/** Allowed options for `OptionalSchema` */
+export type OptionalSchemaOptions<T> = SchemaOptions & {
+    readonly source: Schema<T>;
+    readonly value?: T | null;
+};
 /** Validate a value of a specific type or `null`. */
 export declare class OptionalSchema<T> extends ThroughSchema<T | null> {
     readonly value: T | null;
-    constructor(options: ConstructorParameters<typeof Schema>[0] & {
-        source: Schema<T>;
-        value?: T | null;
-    });
+    constructor(options: OptionalSchemaOptions<T>);
     validate(unsafeValue?: unknown): T | null;
 }
 /** Create a new optional schema from a source schema. */

package/schema/RequiredSchema.d.ts

@@ -1,6 +1,6 @@
 import type { Schema } from "./Schema.js";
 import { ThroughSchema } from "./ThroughSchema.js";
-/** Validate a value of a specifed type, but return `Feedback` if the validated value is falsy. */
+/** Validate a value of a specifed type, but throw `Feedback` if the validated value is falsy. */
 export declare class RequiredSchema<T> extends ThroughSchema<T> {
     validate(unsafeValue: unknown): T;
 }

package/schema/RequiredSchema.js

@@ -1,6 +1,6 @@
 import { Feedback } from "../feedback/Feedback.js";
 import { ThroughSchema } from "./ThroughSchema.js";
-/** Validate a value of a specifed type, but return `Feedback` if the validated value is falsy. */
+/** Validate a value of a specifed type, but throw `Feedback` if the validated value is falsy. */
 export class RequiredSchema extends ThroughSchema {
     validate(unsafeValue) {
         const safeValue = super.validate(unsafeValue);

package/schema/ThroughSchema.js

@@ -2,8 +2,9 @@ import { Schema } from "./Schema.js";
 /** Schema that passes through to a source schema. */
 export class ThroughSchema extends Schema {
     constructor(options) {
-        super(options);
-        this.source = options.source;
+        const source = options.source;
+        super({ ...source, ...options });
+        this.source = source;
     }
     validate(unsafeValue) {
         return this.source.validate(unsafeValue);