shelving 1.95.0 → 1.96.1

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.95.0",
+	"version": "1.96.1",
 	"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/useData.d.ts

@@ -1,14 +1,15 @@
 /// <reference types="react" />
 import type { AsyncQueryReference } from "../db/QueryReference.js";
 import type { ImmutableArray } from "../util/array.js";
+import type { Nullish } from "../util/null.js";
 import { AsyncItemReference } from "../db/ItemReference.js";
 import { ItemState } from "../db/ItemState.js";
 import { QueryState } from "../db/QueryState.js";
-type RefToState<T> = T extends undefined ? undefined : T extends AsyncItemReference<infer X> ? ItemState<X> : T extends AsyncQueryReference<infer X> ? QueryState<X> : never;
+type NullishReferenceState<T> = T extends undefined | null ? undefined : T extends AsyncItemReference<infer X> ? ItemState<X> : T extends AsyncQueryReference<infer X> ? QueryState<X> : never;
 /** Use one or more data items or queries. */
-export declare function useData<T extends AsyncItemReference | AsyncQueryReference | undefined>(ref: T): RefToState<T>;
-export declare function useData<T extends ImmutableArray<AsyncItemReference | AsyncQueryReference | undefined>>(...refs: T): {
-    [K in keyof T]: RefToState<T[K]>;
+export declare function useData<T extends Nullish<AsyncItemReference | AsyncQueryReference>>(ref: T): NullishReferenceState<T>;
+export declare function useData<T extends ImmutableArray<Nullish<AsyncItemReference | AsyncQueryReference>>>(...refs: T): {
+    [K in keyof T]: NullishReferenceState<T[K]>;
 };
 /** Wrap components with `<DataCache>` to allow the use of `useData()`. */
 export declare const DataCache: ({ children }: {

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,51 @@
+import { useEffect, useRef } from "react";
+import { addArrayItem, deleteArrayItems, getLastItem } from "../util/array.js";
+import { getFirstFocusable } from "../util/focus.js";
+/** Stack of elements that should be keeping focus. */
+let FOCUS_STACK;
+/**
+ * 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(() => {
+        var _a;
+        // Set up a global listener the first time `useFocus()` is actually used.
+        if (!FOCUS_STACK) {
+            FOCUS_STACK = [];
+            // Add a focus listener on the body that listens for changes in focus.
+            document.body.addEventListener("focusin", () => {
+                var _a;
+                const el = getLastItem(FOCUS_STACK);
+                if (el && !el.contains(document.activeElement))
+                    (_a = getFirstFocusable(el)) === null || _a === void 0 ? void 0 : _a.focus();
+            });
+        }
+        // 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).
+            (_a = getFirstFocusable(el)) === null || _a === void 0 ? void 0 : _a.focus();
+            // Add this element to the stack of elements to keep focused.
+            addArrayItem(FOCUS_STACK, el);
+            return () => {
+                // Remove this element from the stack of elements to keep focused.
+                deleteArrayItems(FOCUS_STACK, el);
+                // Attempt to restore the previous focus.
+                if (lastEl instanceof HTMLElement)
+                    lastEl.focus();
+            };
+        }
+    }, [ref.current, active]);
+    return ref;
+}

package/react/useState.d.ts

@@ -1,5 +1,6 @@
 import type { AnyState } from "../state/State.js";
 import type { ImmutableArray } from "../util/array.js";
+import type { Nullish } from "../util/null.js";
 /**
  * Subscribe to one or more `State` instances.
  *
@@ -9,5 +10,5 @@ import type { ImmutableArray } from "../util/array.js";
  * - If the value is a `State` instance
  */
 export declare function useState<T extends AnyState>(state: T): T;
-export declare function useState<T extends AnyState>(state?: T | undefined): T | undefined;
-export declare function useState<T extends ImmutableArray<AnyState | undefined>>(...states: T): T;
+export declare function useState<T extends AnyState>(state?: Nullish<T>): Nullish<T>;
+export declare function useState<T extends ImmutableArray<Nullish<AnyState>>>(...states: T): T;

package/util/focus.d.ts

@@ -0,0 +1,2 @@
+/** Find the first focusable element inside HTML element (including the element itself). */
+export declare function getFirstFocusable(el: HTMLElement): HTMLElement | null;

package/util/focus.js

@@ -0,0 +1,6 @@
+/** Selector for elements that can take focus */
+const FOCUSABLE = `a:link, button:enabled, input:enabled, select:enabled, textarea:enabled, [tabindex]:not([tabindex="-1"]):not(:disabled)`;
+/** Find the first focusable element inside HTML element (including the element itself). */
+export function getFirstFocusable(el) {
+    return el.matches(FOCUSABLE) ? el : el.querySelector(FOCUSABLE);
+}

package/util/index.d.ts

@@ -15,6 +15,7 @@ export * from "./duration.js";
 export * from "./entry.js";
 export * from "./equal.js";
 export * from "./error.js";
+export * from "./focus.js";
 export * from "./function.js";
 export * from "./hydrate.js";
 export * from "./iterate.js";

package/util/index.js

@@ -15,6 +15,7 @@ export * from "./duration.js";
 export * from "./entry.js";
 export * from "./equal.js";
 export * from "./error.js";
+export * from "./focus.js";
 export * from "./function.js";
 export * from "./hydrate.js";
 export * from "./iterate.js";

package/util/null.d.ts

@@ -1,17 +1,23 @@
 /** Function that always returns null. */
 export declare const getNull: () => null;
+/** Nullable is the value or `null` */
+export type Nullable<T> = T | null;
 /** Is a value null? */
 export declare const isNull: (value: unknown) => value is null;
+/** Assert that a value is not null. */
+export declare function assertNull<T>(value: Nullable<T>): asserts value is T;
 /** Is a value not null? */
-export declare const notNull: <T>(value: T | null) => value is T;
+export declare const notNull: <T>(value: Nullable<T>) => value is T;
 /** Assert that a value is not null. */
-export declare function assertNotNull<T>(value: T | null): asserts value is T;
+export declare function assertNotNull<T>(value: Nullable<T>): asserts value is T;
 /** Get the not-nullish version of value. */
-export declare function getNotNull<T>(value: T | null): T;
-/** Nullish is `null` or `undefined` */
+export declare function getNotNull<T>(value: Nullable<T>): T;
+/** Nullish is the value or `null` or `undefined` */
 export type Nullish<T> = T | null | undefined;
 /** Is a value nullish? */
 export declare const isNullish: <T>(value: Nullish<T>) => value is null | undefined;
+/** Assert that a value is not nullish. */
+export declare function assertNullish<T>(value: Nullish<T>): asserts value is T;
 /** Is a value not nullish? */
 export declare const notNullish: <T>(value: Nullish<T>) => value is T;
 /** Assert that a value is not nullish. */

package/util/null.js

@@ -4,6 +4,11 @@ import { RequiredError } from "../error/RequiredError.js";
 export const getNull = () => null;
 /** Is a value null? */
 export const isNull = (value) => value === null;
+/** Assert that a value is not null. */
+export function assertNull(value) {
+    if (value !== null)
+        throw new AssertionError("Must be null", value);
+}
 /** Is a value not null? */
 export const notNull = (value) => value !== null;
 /** Assert that a value is not null. */
@@ -18,6 +23,11 @@ export function getNotNull(value) {
 }
 /** Is a value nullish? */
 export const isNullish = (value) => value === null || value === undefined;
+/** Assert that a value is not nullish. */
+export function assertNullish(value) {
+    if (value !== null && value !== undefined)
+        throw new AssertionError("Must be null or undefined", value);
+}
 /** Is a value not nullish? */
 export const notNullish = (value) => value !== null && value !== undefined;
 /** Assert that a value is not nullish. */

package/util/undefined.d.ts

@@ -4,6 +4,8 @@ export declare const getUndefined: () => undefined;
 export declare const isUndefined: (value: unknown) => value is undefined;
 /** Is a value defined? */
 export declare const isDefined: <T>(value: T | undefined) => value is T;
+/** Is a value defined? */
+export declare const notUndefined: <T>(value: T | undefined) => value is T;
 /** Assert that a value is not `undefined` */
 export declare function assertDefined<T>(value: T | undefined): asserts value is T;
 /** Get a defined value. */

package/util/undefined.js

@@ -5,6 +5,8 @@ export const getUndefined = () => undefined;
 export const isUndefined = (value) => value === undefined;
 /** Is a value defined? */
 export const isDefined = (value) => value !== undefined;
+/** Is a value defined? */
+export const notUndefined = isDefined;
 /** Assert that a value is not `undefined` */
 export function assertDefined(value) {
     if (value === undefined)