shelving 1.96.0 → 1.96.2

package/package.json

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

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.js

@@ -1,20 +1,8 @@
 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 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();
-}
+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.
@@ -29,14 +17,16 @@ export function useFocus(active = true) {
     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 (!FOCUSED) {
-            FOCUSED = [];
+        if (!FOCUS_STACK) {
+            FOCUS_STACK = [];
             // Add a focus listener on the body that listens for changes in focus.
             document.body.addEventListener("focusin", () => {
-                const el = getLastItem(FOCUSED);
+                var _a;
+                const el = getLastItem(FOCUS_STACK);
                 if (el && !el.contains(document.activeElement))
-                    _applyFocus(el);
+                    (_a = getFirstFocusable(el)) === null || _a === void 0 ? void 0 : _a.focus();
             });
         }
         // Only run if the element is open and the ref is attached.
@@ -45,12 +35,12 @@ export function useFocus(active = true) {
             // 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);
+            (_a = getFirstFocusable(el)) === null || _a === void 0 ? void 0 : _a.focus();
             // Add this element to the stack of elements to keep focused.
-            addArrayItem(FOCUSED, el);
+            addArrayItem(FOCUS_STACK, el);
             return () => {
                 // Remove this element from the stack of elements to keep focused.
-                deleteArrayItems(FOCUSED, el);
+                deleteArrayItems(FOCUS_STACK, el);
                 // Attempt to restore the previous focus.
                 if (lastEl instanceof HTMLElement)
                     lastEl.focus();

package/react/useInstance.d.ts

@@ -4,4 +4,4 @@ import type { Arguments } from "../util/function.js";
  * - Creates a new instance of `Constructor` using `args`
  * - Returns same instance for as long as `args` is equal to previous `args`.
  */
-export declare function useInstance<T, A extends Arguments>(Constructor: new (...a: A) => T, ...args: A): T;
+export declare function useInstance<T, A extends Arguments = []>(Constructor: new (...a: A) => T, ...args: A): T;

package/react/useLazy.d.ts

@@ -5,6 +5,6 @@ import type { Lazy } from "../util/lazy.js";
  * - Returns `value` (if not a function) or the result of calling `value(...args)` (if a function).
  * - Returns same `value` for as long as `args` is equal to previous `args`.
  */
-export declare function useLazy<T, A extends Arguments>(value: (...args: A) => T, ...args: A): T;
+export declare function useLazy<T, A extends Arguments = []>(value: (...args: A) => T, ...args: A): T;
 export declare function useLazy<T>(value: T, ...args: Arguments): T;
-export declare function useLazy<T, A extends Arguments>(value: Lazy<T, A>, ...args: A): T;
+export declare function useLazy<T, A extends Arguments = []>(value: Lazy<T, A>, ...args: A): T;

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)