@pathscale/ui 2.11.13 → 3.0.0

package/dist/components/data-grid/DataGrid.interactions.d.ts

@@ -1,3 +1,4 @@
+import type { JSX } from "@solidjs/web";
 import type { DataGridColumn, DataGridRow } from "./createDataGrid";
 export declare const formatCell: (value: unknown) => string;
 export declare const columnSpan: (visible: number, hasSelection: boolean) => number;
@@ -5,7 +6,7 @@ export declare const columnSpan: (visible: number, hasSelection: boolean) => num
 export declare const pageLabel: (page: number, pageCount: number) => string;
 export declare const rangeLabel: (page: number, pageSize: number, total: number) => string;
 export declare const searchPlaceholder: (label: string) => string;
-export declare const cellContent: <Row extends DataGridRow>(column: DataGridColumn<Row>, row: Row, index: number) => string | number | boolean | import("solid-js/types/types.js").RenderedElement | Node | import("@solidjs/web").JSX.ArrayElement | null | undefined;
+export declare const cellContent: <Row extends DataGridRow>(column: DataGridColumn<Row>, row: Row, index: number) => JSX.Element;
 export declare const readInputValue: (event: {
     currentTarget: HTMLInputElement;
 }) => string;

package/dist/hooks/data/createMutation.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A write, without a query library. The companion to `createQuery`.
+ *
+ * Replaces `useMutation`. The same rule applies as there: reading this never
+ * suspends and never throws. `mutate` reports failure through `error`;
+ * `mutateAsync` rejects, for a caller that wants to await and handle it.
+ */
+export interface CreateMutationOptions<TArgs extends unknown[], TResult> {
+    mutationFn: (...args: TArgs) => Promise<TResult>;
+    onSuccess?: (result: TResult, ...args: TArgs) => void | Promise<void>;
+    onError?: (error: unknown, ...args: TArgs) => void;
+    /** Runs after success or failure, like TanStack's `onSettled`. */
+    onSettled?: () => void | Promise<void>;
+}
+/** Read as properties, for the same reason as `QueryResult`. */
+export interface MutationResult<TArgs extends unknown[], TResult> {
+    /** Fire and forget. Failure lands on `error` rather than as a rejection. */
+    mutate: (...args: TArgs) => void;
+    /** Fire and await. Rejects on failure. */
+    mutateAsync: (...args: TArgs) => Promise<TResult>;
+    readonly isPending: boolean;
+    readonly error: unknown;
+    readonly isError: boolean;
+    /** The last successful result. */
+    readonly data: TResult | undefined;
+    /** Clear `error` and `data`. */
+    reset: () => void;
+}
+export declare const createMutation: <TArgs extends unknown[], TResult>(options: () => CreateMutationOptions<TArgs, TResult>) => MutationResult<TArgs, TResult>;

package/dist/hooks/data/createMutation.js

@@ -0,0 +1,50 @@
+import { createSignal } from "solid-js";
+const createMutation = (options)=>{
+    const [isPending, setIsPending] = createSignal(false);
+    const [error, setError] = createSignal(void 0);
+    const [data, setData] = createSignal(void 0);
+    let inFlight = 0;
+    const mutateAsync = async (...args)=>{
+        const { mutationFn, onSuccess, onError, onSettled } = options();
+        inFlight++;
+        setIsPending(true);
+        setError(void 0);
+        try {
+            const result = await mutationFn(...args);
+            setData(()=>result);
+            await onSuccess?.(result, ...args);
+            return result;
+        } catch (caught) {
+            setError(()=>caught);
+            onError?.(caught, ...args);
+            throw caught;
+        } finally{
+            inFlight--;
+            if (0 === inFlight) setIsPending(false);
+            await onSettled?.();
+        }
+    };
+    return {
+        mutate: (...args)=>{
+            mutateAsync(...args).catch(()=>{});
+        },
+        mutateAsync,
+        get isPending () {
+            return isPending();
+        },
+        get error () {
+            return error();
+        },
+        get isError () {
+            return void 0 !== error();
+        },
+        get data () {
+            return data();
+        },
+        reset: ()=>{
+            setError(void 0);
+            setData(()=>void 0);
+        }
+    };
+};
+export { createMutation };

package/dist/hooks/data/createQuery.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Asynchronous reads, without a query library.
+ *
+ * This exists to replace `@tanstack/solid-query`, and the replacement is not a
+ * like-for-like port. One behaviour is deliberately different, and it is the
+ * reason this file exists rather than a wrapper around the old one:
+ *
+ * **A query that has not run is not pending, and reading it never suspends.**
+ *
+ * TanStack keeps a query that has never fetched -- including one held back by
+ * `enabled: false` -- at `status: "pending"` forever. Under Solid 2, reading a
+ * pending query throws `NotReadyError` to suspend. A widget whose query was
+ * disabled therefore suspended for the lifetime of the page, and because
+ * `NotReadyError` extends `Error` with no message, a boundary that caught it
+ * had nothing to print. That is how a support-chat button that had not
+ * connected replaced an entire application with a blank error page.
+ *
+ * Here, `data` is `undefined` until there is data, `isLoading` is true only
+ * while a fetch is actually in flight, and neither ever throws. A caller that
+ * wants to suspend can do so explicitly; a caller that forgets cannot take the
+ * page down.
+ */
+export interface CreateQueryOptions<T> {
+    /**
+     * Identity, for invalidation. Compared by value, and matched by prefix, so
+     * `["users"]` invalidates `["users", 1]` as well.
+     */
+    key: readonly unknown[];
+    /** The read itself. Only called when `enabled` is not false. */
+    fetcher: () => Promise<T>;
+    /** Held back while false. Default true. */
+    enabled?: boolean;
+}
+/**
+ * Read as properties, not as accessors.
+ *
+ * `solid-query` returned a store, so every consumer of it is written
+ * `query.data`, `query.isLoading`, `query.isError` -- roughly three thousand
+ * such reads across these applications. Exposing accessors here would mean
+ * editing all of them to add `()`, turning a migration of the ~300 files that
+ * *define* queries into one that touches every file that reads one.
+ *
+ * These are getters over signals, so a read inside a tracked scope still
+ * subscribes exactly as an accessor call would.
+ */
+export interface QueryResult<T> {
+    /** The last value read, or `undefined` before the first one arrives. */
+    readonly data: T | undefined;
+    /** The last failure, cleared by the next successful read. */
+    readonly error: unknown;
+    /** True only while a fetch is in flight. Never true for a disabled query. */
+    readonly isLoading: boolean;
+    /**
+     * Alias of `isLoading`, for call sites carried over from `solid-query`.
+     *
+     * Note the deliberate difference in meaning. There, `isPending` was "has no
+     * data", which stayed true forever for a query held back by `enabled: false`
+     * -- so `if (isPending) return <Spinner/>` spun for the life of the page.
+     * Here it means "a fetch is in flight", so a disabled query reads as not
+     * pending and its consumer renders instead of hanging.
+     */
+    readonly isPending: boolean;
+    /** True when the last read failed. */
+    readonly isError: boolean;
+    /** True when a value has arrived and the last read did not fail. */
+    readonly isSuccess: boolean;
+    /** True once a value has arrived at least once. */
+    readonly isReady: boolean;
+    /** Read again now, regardless of `enabled`. */
+    refetch: () => Promise<void>;
+}
+/**
+ * Re-read every live query whose key starts with `prefix`.
+ *
+ * The replacement for `useQueryClient().invalidateQueries({ queryKey })`. It is
+ * a plain function rather than something read from context: invalidation is
+ * usually wanted from a mutation handler or a store, which are not components
+ * and have no context to read.
+ */
+export declare const invalidateQueries: (prefix: readonly unknown[]) => void;
+export declare const createQuery: <T>(options: () => CreateQueryOptions<T>) => QueryResult<T>;

package/dist/hooks/data/createQuery.js

@@ -0,0 +1,72 @@
+import { createRenderEffect, createSignal, onCleanup, untrack } from "solid-js";
+const registry = new Set();
+const isPrefix = (prefix, key)=>prefix.length <= key.length && prefix.every((part, index)=>Object.is(part, key[index]));
+const invalidateQueries = (prefix)=>{
+    for (const entry of registry)if (isPrefix(prefix, entry.key)) entry.refetch();
+};
+const createQuery = (options)=>{
+    const [data, setData] = createSignal(void 0);
+    const [error, setError] = createSignal(void 0);
+    const [isLoading, setIsLoading] = createSignal(false);
+    const [isReady, setIsReady] = createSignal(false);
+    let generation = 0;
+    const run = async ()=>{
+        const mine = ++generation;
+        const { fetcher } = untrack(options);
+        setIsLoading(true);
+        try {
+            const value = await fetcher();
+            if (mine !== generation) return;
+            setData(()=>value);
+            setError(void 0);
+            setIsReady(true);
+        } catch (caught) {
+            if (mine !== generation) return;
+            setError(()=>caught);
+        } finally{
+            if (mine === generation) setIsLoading(false);
+        }
+    };
+    createRenderEffect(()=>options(), ({ key, enabled = true })=>{
+        if (!enabled) {
+            generation++;
+            setIsLoading(false);
+            return;
+        }
+        const entry = {
+            key,
+            refetch: ()=>void run()
+        };
+        registry.add(entry);
+        onCleanup(()=>registry.delete(entry));
+        run();
+    });
+    onCleanup(()=>{
+        generation++;
+    });
+    return {
+        get data () {
+            return data();
+        },
+        get error () {
+            return error();
+        },
+        get isLoading () {
+            return isLoading();
+        },
+        get isPending () {
+            return isLoading();
+        },
+        get isError () {
+            return void 0 !== error();
+        },
+        get isSuccess () {
+            return isReady() && void 0 === error();
+        },
+        get isReady () {
+            return isReady();
+        },
+        refetch: run
+    };
+};
+export { createQuery, invalidateQueries };

package/dist/hooks/data/createQuery.test.d.ts

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

package/dist/hooks/data/createQuery.test.js

@@ -0,0 +1,207 @@
+import { describe, expect, test } from "bun:test";
+import { createRenderEffect, createRoot, flush } from "solid-js";
+import { createMutation } from "./createMutation.js";
+import { createQuery, invalidateQueries } from "./createQuery.js";
+const tick = ()=>new Promise((resolve)=>setTimeout(resolve, 0));
+describe("createQuery", ()=>{
+    test("a disabled query is not loading, and never throws", async ()=>{
+        let calls = 0;
+        const dispose = createRoot((d)=>{
+            const q = createQuery(()=>({
+                    key: [
+                        "never"
+                    ],
+                    enabled: false,
+                    fetcher: async ()=>{
+                        calls++;
+                        return "value";
+                    }
+                }));
+            expect(q.isLoading).toBe(false);
+            expect(q.data).toBeUndefined();
+            expect(q.isReady).toBe(false);
+            return d;
+        });
+        await tick();
+        expect(calls).toBe(0);
+        dispose();
+    });
+    test("reads, and reports readiness", async ()=>{
+        let resolveFetch;
+        const result = await createRoot(async (dispose)=>{
+            const q = createQuery(()=>({
+                    key: [
+                        "thing"
+                    ],
+                    fetcher: ()=>new Promise((r)=>resolveFetch = r)
+                }));
+            flush();
+            const whileLoading = {
+                loading: q.isLoading,
+                ready: q.isReady
+            };
+            resolveFetch?.("hello");
+            await tick();
+            return {
+                whileLoading,
+                data: q.data,
+                ready: q.isReady,
+                dispose
+            };
+        });
+        expect(result.whileLoading).toEqual({
+            loading: true,
+            ready: false
+        });
+        expect(result.data).toBe("hello");
+        expect(result.ready).toBe(true);
+        result.dispose();
+    });
+    test("a failure lands on error rather than being thrown", async ()=>{
+        const result = await createRoot(async (dispose)=>{
+            const q = createQuery(()=>({
+                    key: [
+                        "bad"
+                    ],
+                    fetcher: async ()=>{
+                        throw new Error("nope");
+                    }
+                }));
+            flush();
+            await tick();
+            return {
+                error: q.error,
+                loading: q.isLoading,
+                dispose
+            };
+        });
+        expect(result.error.message).toBe("nope");
+        expect(result.loading).toBe(false);
+        result.dispose();
+    });
+    test("invalidateQueries matches by key prefix", async ()=>{
+        let calls = 0;
+        const dispose = createRoot((d)=>{
+            createQuery(()=>({
+                    key: [
+                        "users",
+                        1
+                    ],
+                    fetcher: async ()=>{
+                        calls++;
+                        return calls;
+                    }
+                }));
+            flush();
+            return d;
+        });
+        await tick();
+        expect(calls).toBe(1);
+        invalidateQueries([
+            "users"
+        ]);
+        await tick();
+        expect(calls).toBe(2);
+        invalidateQueries([
+            "apps"
+        ]);
+        await tick();
+        expect(calls).toBe(2);
+        dispose();
+    });
+    test("a disposed query deregisters, so invalidation cannot reach it", async ()=>{
+        let calls = 0;
+        const dispose = createRoot((d)=>{
+            createQuery(()=>({
+                    key: [
+                        "gone"
+                    ],
+                    fetcher: async ()=>{
+                        calls++;
+                        return calls;
+                    }
+                }));
+            flush();
+            return d;
+        });
+        await tick();
+        expect(calls).toBe(1);
+        dispose();
+        invalidateQueries([
+            "gone"
+        ]);
+        await tick();
+        expect(calls).toBe(1);
+    });
+});
+describe("property reads stay reactive", ()=>{
+    test("a tracked scope re-runs when data lands", async ()=>{
+        let resolveFetch;
+        const seen = [];
+        const result = await createRoot(async (dispose)=>{
+            const q = createQuery(()=>({
+                    key: [
+                        "reactive"
+                    ],
+                    fetcher: ()=>new Promise((r)=>resolveFetch = r)
+                }));
+            createRenderEffect(()=>q.data, (value)=>{
+                seen.push(value);
+            });
+            flush();
+            resolveFetch?.("arrived");
+            await tick();
+            flush();
+            return {
+                dispose
+            };
+        });
+        expect(seen[0]).toBeUndefined();
+        expect(seen.at(-1)).toBe("arrived");
+        result.dispose();
+    });
+});
+describe("createMutation", ()=>{
+    test("mutate reports failure without an unhandled rejection", async ()=>{
+        const result = await createRoot(async (dispose)=>{
+            const m = createMutation(()=>({
+                    mutationFn: async ()=>{
+                        throw new Error("write failed");
+                    }
+                }));
+            m.mutate();
+            await tick();
+            return {
+                error: m.error,
+                pending: m.isPending,
+                dispose
+            };
+        });
+        expect(result.error.message).toBe("write failed");
+        expect(result.pending).toBe(false);
+        result.dispose();
+    });
+    test("mutateAsync rejects, and onSuccess sees the result", async ()=>{
+        const seen = [];
+        const result = await createRoot(async (dispose)=>{
+            const m = createMutation(()=>({
+                    mutationFn: async (name)=>`made ${name}`,
+                    onSuccess: (r)=>{
+                        seen.push(r);
+                    }
+                }));
+            const value = await m.mutateAsync("app");
+            return {
+                value,
+                data: m.data,
+                dispose
+            };
+        });
+        expect(result.value).toBe("made app");
+        expect(result.data).toBe("made app");
+        expect(seen).toEqual([
+            "made app"
+        ]);
+        result.dispose();
+    });
+});

package/dist/hooks/data/index.d.ts

@@ -0,0 +1,4 @@
+export type { CreateQueryOptions, QueryResult, } from "./createQuery";
+export { createQuery, invalidateQueries } from "./createQuery";
+export type { CreateMutationOptions, MutationResult, } from "./createMutation";
+export { createMutation } from "./createMutation";

package/dist/hooks/data/index.js

@@ -0,0 +1,2 @@
+export { createQuery, invalidateQueries } from "./createQuery.js";
+export { createMutation } from "./createMutation.js";

package/dist/index.d.ts

@@ -121,6 +121,8 @@ export type { Align, CapabilityProps, ChangeReason, Constraint, Controlled, Dire
 export { FLAVORS, isInvalid, resolveState, SIZES, SPACES, STATES, VARIANTS, } from "./components/vocabulary";
 export type { AnyFormApi, CreateFormOptions, FormApi, UseFieldResult, } from "./hooks/form";
 export { createForm, FormContext, getFirstFieldError, useField, useFormContext, } from "./hooks/form";
+export type { CreateMutationOptions, CreateQueryOptions, MutationResult, QueryResult, } from "./hooks/data";
+export { createMutation, createQuery, invalidateQueries, } from "./hooks/data";
 export { useDesktop } from "./hooks/layout";
 export type { UseAnchoredOverlayPositionOptions } from "./hooks/table";
 export { useAnchoredOverlayPosition } from "./hooks/table";

package/dist/index.js

@@ -72,6 +72,7 @@ export { DEFAULT_GAP as DEFAULT_TOAST_GAP, DEFAULT_MAX_VISIBLE_TOAST, DEFAULT_SC
 export { TooltipArrow, TooltipContent, TooltipTrigger, default as Tooltip } from "./components/tooltip/index.js";
 export { FLAVORS, SIZES, SPACES, STATES, VARIANTS, isInvalid, resolveState } from "./components/vocabulary.js";
 export { FormContext, createForm, getFirstFieldError, useField, useFormContext } from "./hooks/form/index.js";
+export { createMutation, createQuery, invalidateQueries } from "./hooks/data/index.js";
 export { useDesktop } from "./hooks/layout/index.js";
 export { useAnchoredOverlayPosition } from "./hooks/table/index.js";
 export { evaluatePasswordRules, matchPasswordConfirmation } from "./passwordRules.js";

package/dist/layouts.manifest.json

@@ -1,7 +1,7 @@
 {
   "format": "solid-layouts-library-v2",
   "package": "@pathscale/ui",
-  "version": "2.11.13",
+  "version": "3.0.0",
   "components": {
     "Accordion": {
       "kind": "embedded"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pathscale/ui",
-  "version": "2.11.13",
+  "version": "3.0.0",
   "author": "pathscale",
   "repository": {
     "type": "git",