@btst/stack 2.12.2 → 3.0.0-rc.2

package/dist/plugins/client/hooks/index.cjs

@@ -0,0 +1,13 @@
+'use strict';
+
+const hooks = require('../../../packages/stack/src/plugins/client/resource/hooks.cjs');
+const useForm = require('../../../packages/stack/src/plugins/client/resource/use-form.cjs');
+const useSelect = require('../../../packages/stack/src/plugins/client/resource/use-select.cjs');
+const useDebounce = require('../../../packages/stack/src/plugins/client/resource/use-debounce.cjs');
+
+
+
+exports.createResource = hooks.createResource;
+exports.createUseForm = useForm.createUseForm;
+exports.createUseSelect = useSelect.createUseSelect;
+exports.useDebounce = useDebounce.useDebounce;

package/dist/plugins/client/hooks/index.d.cts

@@ -0,0 +1,204 @@
+import { UseInfiniteQueryResult, InfiniteData, UseSuspenseInfiniteQueryResult, UseQueryResult, UseSuspenseQueryResult, UseMutationResult } from '@tanstack/react-query';
+import { a as StackError, f as ResourceDef, p as ResourcesDeclaration, k as ResourceQueryArgs, l as ResourceQueryData, h as ResourceMutationResult, j as ResourceMutationVars } from '../../../shared/stack.CbZenbej.cjs';
+
+/** Configuration for the per-resource `useForm` hook. */
+interface ResourceFormConfig<TValues, TRecord = unknown, TResult = unknown> {
+    action: "create" | "edit";
+    /** Detail-query arg identifying the record to edit (e.g. a slug or id) */
+    id?: unknown;
+    /** Query used to fetch the record for edit (default `"detail"`) */
+    detailQuery?: string;
+    /** Mutation used on create submit (default `"create"`) */
+    createMutation?: string;
+    /** Mutation used on edit submit (default `"update"`) */
+    updateMutation?: string;
+    /**
+     * Externally supplied record — skips the internal detail fetch. Useful
+     * when the record comes from a suspense hook higher in the tree.
+     */
+    record?: TRecord | null;
+    /** Default form values, or a function deriving them from the record */
+    defaults?: TValues | ((record: TRecord | null) => TValues);
+    /** Maps form values to create-mutation variables (default: identity) */
+    toCreateVars?: (values: TValues) => unknown;
+    /** Maps form values to update-mutation variables (default: identity) */
+    toUpdateVars?: (values: TValues, record: TRecord | null) => unknown;
+    /** Success notification, sent through the `notify` provider */
+    successMessage?: string | ((result: TResult, action: "create" | "edit") => string);
+    /**
+     * Error notification for non-field errors. Field-level validation errors
+     * land on `fieldErrors` instead of producing a notification.
+     */
+    errorMessage?: string | ((error: StackError) => string);
+    /**
+     * Path to navigate to after success (via the router adapter's
+     * `navigate`). A function form derives it from the result; return a
+     * falsy value to skip navigation.
+     */
+    redirect?: string | ((result: TResult, action: "create" | "edit") => string | false | null | undefined);
+    /** Called after a successful submit (before redirect) */
+    onSuccess?: (result: TResult) => void | Promise<void>;
+}
+/** Result of the per-resource `useForm` hook. */
+interface ResourceFormResult<TValues, TRecord = unknown, TResult = unknown> {
+    action: "create" | "edit";
+    /** The record being edited (null while loading or when creating) */
+    record: TRecord | null;
+    isLoadingRecord: boolean;
+    recordError: Error | null;
+    /** Resolved default values (stable while `record` is unchanged) */
+    defaultValues: TValues | undefined;
+    /** Runs the right mutation; resolves the result, or undefined on error */
+    submit: (values: TValues) => Promise<TResult | undefined>;
+    isSubmitting: boolean;
+    /** Last submit error (normalized), or null */
+    error: StackError | null;
+    /** Field name → validation message(s) from the last submit error */
+    fieldErrors: Record<string, string | string[]>;
+    clearErrors: () => void;
+}
+/**
+ * Builds the per-resource `useForm` hook: bundles the create/edit lifecycle —
+ * fetch record for edit, defaults, submit the right mutation, invalidate,
+ * notify, redirect, and per-field error state from `StackError.errors`.
+ */
+declare function createUseForm(plugin: string, resourceName: string, resource: ResourceDef): <TValues, TRecord = unknown, TResult = unknown>(config: ResourceFormConfig<TValues, TRecord, TResult>) => ResourceFormResult<TValues, TRecord, TResult>;
+
+/** An option produced by the per-resource `useSelect` hook. */
+interface ResourceSelectOption<TItem> {
+    value: string;
+    label: string;
+    /** The underlying record; undefined for values that could not be resolved */
+    item?: TItem;
+}
+/** Configuration for the per-resource `useSelect` hook. */
+interface ResourceSelectConfig<TItem> {
+    /**
+     * Query used to fetch options (default `"list"`). Must be a non-infinite
+     * query whose data is an array of records.
+     */
+    query?: string;
+    /** Maps the (debounced) search text to the option-query args */
+    searchArgs: (search: string) => readonly unknown[];
+    getOptionValue: (item: TItem) => string;
+    getOptionLabel: (item: TItem) => string;
+    /** Currently selected value(s) — preloaded when missing from options */
+    value?: string | string[];
+    /**
+     * Query used to preload selected values missing from the options
+     * (default query `"detail"`). Preloading is skipped when omitted.
+     */
+    preload?: {
+        query?: string;
+        args: (value: string) => readonly unknown[];
+    };
+    /** Debounce for the search text in milliseconds (default 300) */
+    debounceMs?: number;
+    enabled?: boolean;
+}
+/** Result of the per-resource `useSelect` hook. */
+interface ResourceSelectResult<TItem> {
+    /** Search results plus preloaded selected records */
+    options: ResourceSelectOption<TItem>[];
+    /** Options for the current `value(s)`, resolved where possible */
+    selectedOptions: ResourceSelectOption<TItem>[];
+    search: string;
+    setSearch: (search: string) => void;
+    /** Initial load of options or preloaded values in flight */
+    isLoading: boolean;
+    /** Search debounce pending or a search fetch in flight */
+    isSearching: boolean;
+    error: Error | null;
+}
+/**
+ * Builds the per-resource `useSelect` hook: debounced server-side search,
+ * current-value preloading, and loading states for relation pickers.
+ */
+declare function createUseSelect(plugin: string, resourceName: string, resource: ResourceDef): <TItem>(config: ResourceSelectConfig<TItem>) => ResourceSelectResult<TItem>;
+
+/**
+ * `createResource` — generates the repetitive React Query plumbing for a
+ * plugin's resources from a single declaration: plain queries, suspense
+ * queries, infinite queries, mutations with invalidation, plus `useForm`
+ * and `useSelect` per resource.
+ *
+ * The same declaration feeds `createResourceQueryKeys` (see `./queries`),
+ * so SSR loaders and SSG `prefetchForRoute` keys stay in sync with hooks.
+ *
+ * @example
+ * ```ts
+ * const blog = createResource({ plugin: "blog", resources: blogResources });
+ *
+ * export const usePost = (slug?: string) =>
+ *   blog.posts.detail.use([slug ?? ""], { enabled: !!slug });
+ * export const useCreatePost = () => blog.posts.create.use();
+ * ```
+ */
+
+/** Per-call options for generated query hooks. */
+interface ResourceQueryOptions {
+    enabled?: boolean;
+}
+/** Hooks generated for a non-infinite query declaration. */
+interface ResourcePlainQueryHooks<TArgs extends readonly unknown[], TData> {
+    use(args?: TArgs, options?: ResourceQueryOptions): UseQueryResult<TData, Error>;
+    /** Suspense variant — re-throws refetch errors for Error Boundaries */
+    useSuspense(args?: TArgs): UseSuspenseQueryResult<TData, Error>;
+}
+/** Hooks generated for an infinite query declaration. */
+interface ResourceInfiniteQueryHooks<TArgs extends readonly unknown[], TData> {
+    useInfinite(args?: TArgs, options?: ResourceQueryOptions): UseInfiniteQueryResult<InfiniteData<TData, number>, Error>;
+    /** Suspense variant — re-throws refetch errors for Error Boundaries */
+    useSuspenseInfinite(args?: TArgs): UseSuspenseInfiniteQueryResult<InfiniteData<TData, number>, Error>;
+}
+/** Dispatches to the plain or infinite hook set based on the declaration. */
+type ResourceQueryHooks<TDef> = TDef extends {
+    infinite: true;
+} ? ResourceInfiniteQueryHooks<ResourceQueryArgs<TDef>, ResourceQueryData<TDef>> : ResourcePlainQueryHooks<ResourceQueryArgs<TDef>, ResourceQueryData<TDef>>;
+/** Hook generated for a mutation declaration. */
+interface ResourceMutationHooks<TDef> {
+    use(): UseMutationResult<ResourceMutationResult<TDef>, Error, ResourceMutationVars<TDef>>;
+}
+/** The detail-query record type of a resource (used by `useForm` defaults). */
+type ResourceDetailData<TResource extends ResourceDef> = TResource["queries"] extends {
+    detail: infer TDetail;
+} ? ResourceQueryData<TDetail> : unknown;
+/** The generated handle for a single resource. */
+type ResourceHandle<TResource extends ResourceDef> = {
+    [Q in keyof TResource["queries"]]: ResourceQueryHooks<TResource["queries"][Q]>;
+} & {
+    [M in keyof NonNullable<TResource["mutations"]>]: ResourceMutationHooks<NonNullable<TResource["mutations"]>[M]>;
+} & {
+    useForm<TValues, TResult = unknown, TRecord = ResourceDetailData<TResource>>(config: ResourceFormConfig<TValues, TRecord, TResult>): ResourceFormResult<TValues, TRecord, TResult>;
+    useSelect<TItem>(config: ResourceSelectConfig<TItem>): ResourceSelectResult<TItem>;
+};
+/** The generated resource handles, keyed by resource name. */
+type Resource<TResources extends ResourcesDeclaration> = {
+    [R in keyof TResources]: ResourceHandle<TResources[R]>;
+};
+interface CreateResourceConfig<TResources extends ResourcesDeclaration> {
+    /** Plugin name used to resolve plugin-specific request headers. */
+    plugin: string;
+    resources: TResources;
+}
+/**
+ * Generates the full hook surface for a plugin's resources.
+ *
+ * Hooks resolve API and router wiring from `StackProvider`, plus any
+ * plugin-specific request headers, at render time so the declaration can
+ * live at module scope.
+ */
+declare function createResource<const TResources extends ResourcesDeclaration>(config: CreateResourceConfig<TResources>): Resource<TResources>;
+
+/**
+ * Plugin-specific request options consumed by the resource layer.
+ */
+interface ResourceOverrides {
+    headers?: HeadersInit;
+}
+
+/** Returns `value` debounced by `delay` milliseconds (default 500). */
+declare function useDebounce<T>(value: T, delay?: number): T;
+
+export { createResource, createUseForm, createUseSelect, useDebounce };
+export type { CreateResourceConfig, Resource, ResourceDetailData, ResourceFormConfig, ResourceFormResult, ResourceHandle, ResourceInfiniteQueryHooks, ResourceMutationHooks, ResourceOverrides, ResourcePlainQueryHooks, ResourceQueryHooks, ResourceQueryOptions, ResourceSelectConfig, ResourceSelectOption, ResourceSelectResult };

package/dist/plugins/client/hooks/index.d.mts

@@ -0,0 +1,204 @@
+import { UseInfiniteQueryResult, InfiniteData, UseSuspenseInfiniteQueryResult, UseQueryResult, UseSuspenseQueryResult, UseMutationResult } from '@tanstack/react-query';
+import { a as StackError, f as ResourceDef, p as ResourcesDeclaration, k as ResourceQueryArgs, l as ResourceQueryData, h as ResourceMutationResult, j as ResourceMutationVars } from '../../../shared/stack.CbZenbej.mjs';
+
+/** Configuration for the per-resource `useForm` hook. */
+interface ResourceFormConfig<TValues, TRecord = unknown, TResult = unknown> {
+    action: "create" | "edit";
+    /** Detail-query arg identifying the record to edit (e.g. a slug or id) */
+    id?: unknown;
+    /** Query used to fetch the record for edit (default `"detail"`) */
+    detailQuery?: string;
+    /** Mutation used on create submit (default `"create"`) */
+    createMutation?: string;
+    /** Mutation used on edit submit (default `"update"`) */
+    updateMutation?: string;
+    /**
+     * Externally supplied record — skips the internal detail fetch. Useful
+     * when the record comes from a suspense hook higher in the tree.
+     */
+    record?: TRecord | null;
+    /** Default form values, or a function deriving them from the record */
+    defaults?: TValues | ((record: TRecord | null) => TValues);
+    /** Maps form values to create-mutation variables (default: identity) */
+    toCreateVars?: (values: TValues) => unknown;
+    /** Maps form values to update-mutation variables (default: identity) */
+    toUpdateVars?: (values: TValues, record: TRecord | null) => unknown;
+    /** Success notification, sent through the `notify` provider */
+    successMessage?: string | ((result: TResult, action: "create" | "edit") => string);
+    /**
+     * Error notification for non-field errors. Field-level validation errors
+     * land on `fieldErrors` instead of producing a notification.
+     */
+    errorMessage?: string | ((error: StackError) => string);
+    /**
+     * Path to navigate to after success (via the router adapter's
+     * `navigate`). A function form derives it from the result; return a
+     * falsy value to skip navigation.
+     */
+    redirect?: string | ((result: TResult, action: "create" | "edit") => string | false | null | undefined);
+    /** Called after a successful submit (before redirect) */
+    onSuccess?: (result: TResult) => void | Promise<void>;
+}
+/** Result of the per-resource `useForm` hook. */
+interface ResourceFormResult<TValues, TRecord = unknown, TResult = unknown> {
+    action: "create" | "edit";
+    /** The record being edited (null while loading or when creating) */
+    record: TRecord | null;
+    isLoadingRecord: boolean;
+    recordError: Error | null;
+    /** Resolved default values (stable while `record` is unchanged) */
+    defaultValues: TValues | undefined;
+    /** Runs the right mutation; resolves the result, or undefined on error */
+    submit: (values: TValues) => Promise<TResult | undefined>;
+    isSubmitting: boolean;
+    /** Last submit error (normalized), or null */
+    error: StackError | null;
+    /** Field name → validation message(s) from the last submit error */
+    fieldErrors: Record<string, string | string[]>;
+    clearErrors: () => void;
+}
+/**
+ * Builds the per-resource `useForm` hook: bundles the create/edit lifecycle —
+ * fetch record for edit, defaults, submit the right mutation, invalidate,
+ * notify, redirect, and per-field error state from `StackError.errors`.
+ */
+declare function createUseForm(plugin: string, resourceName: string, resource: ResourceDef): <TValues, TRecord = unknown, TResult = unknown>(config: ResourceFormConfig<TValues, TRecord, TResult>) => ResourceFormResult<TValues, TRecord, TResult>;
+
+/** An option produced by the per-resource `useSelect` hook. */
+interface ResourceSelectOption<TItem> {
+    value: string;
+    label: string;
+    /** The underlying record; undefined for values that could not be resolved */
+    item?: TItem;
+}
+/** Configuration for the per-resource `useSelect` hook. */
+interface ResourceSelectConfig<TItem> {
+    /**
+     * Query used to fetch options (default `"list"`). Must be a non-infinite
+     * query whose data is an array of records.
+     */
+    query?: string;
+    /** Maps the (debounced) search text to the option-query args */
+    searchArgs: (search: string) => readonly unknown[];
+    getOptionValue: (item: TItem) => string;
+    getOptionLabel: (item: TItem) => string;
+    /** Currently selected value(s) — preloaded when missing from options */
+    value?: string | string[];
+    /**
+     * Query used to preload selected values missing from the options
+     * (default query `"detail"`). Preloading is skipped when omitted.
+     */
+    preload?: {
+        query?: string;
+        args: (value: string) => readonly unknown[];
+    };
+    /** Debounce for the search text in milliseconds (default 300) */
+    debounceMs?: number;
+    enabled?: boolean;
+}
+/** Result of the per-resource `useSelect` hook. */
+interface ResourceSelectResult<TItem> {
+    /** Search results plus preloaded selected records */
+    options: ResourceSelectOption<TItem>[];
+    /** Options for the current `value(s)`, resolved where possible */
+    selectedOptions: ResourceSelectOption<TItem>[];
+    search: string;
+    setSearch: (search: string) => void;
+    /** Initial load of options or preloaded values in flight */
+    isLoading: boolean;
+    /** Search debounce pending or a search fetch in flight */
+    isSearching: boolean;
+    error: Error | null;
+}
+/**
+ * Builds the per-resource `useSelect` hook: debounced server-side search,
+ * current-value preloading, and loading states for relation pickers.
+ */
+declare function createUseSelect(plugin: string, resourceName: string, resource: ResourceDef): <TItem>(config: ResourceSelectConfig<TItem>) => ResourceSelectResult<TItem>;
+
+/**
+ * `createResource` — generates the repetitive React Query plumbing for a
+ * plugin's resources from a single declaration: plain queries, suspense
+ * queries, infinite queries, mutations with invalidation, plus `useForm`
+ * and `useSelect` per resource.
+ *
+ * The same declaration feeds `createResourceQueryKeys` (see `./queries`),
+ * so SSR loaders and SSG `prefetchForRoute` keys stay in sync with hooks.
+ *
+ * @example
+ * ```ts
+ * const blog = createResource({ plugin: "blog", resources: blogResources });
+ *
+ * export const usePost = (slug?: string) =>
+ *   blog.posts.detail.use([slug ?? ""], { enabled: !!slug });
+ * export const useCreatePost = () => blog.posts.create.use();
+ * ```
+ */
+
+/** Per-call options for generated query hooks. */
+interface ResourceQueryOptions {
+    enabled?: boolean;
+}
+/** Hooks generated for a non-infinite query declaration. */
+interface ResourcePlainQueryHooks<TArgs extends readonly unknown[], TData> {
+    use(args?: TArgs, options?: ResourceQueryOptions): UseQueryResult<TData, Error>;
+    /** Suspense variant — re-throws refetch errors for Error Boundaries */
+    useSuspense(args?: TArgs): UseSuspenseQueryResult<TData, Error>;
+}
+/** Hooks generated for an infinite query declaration. */
+interface ResourceInfiniteQueryHooks<TArgs extends readonly unknown[], TData> {
+    useInfinite(args?: TArgs, options?: ResourceQueryOptions): UseInfiniteQueryResult<InfiniteData<TData, number>, Error>;
+    /** Suspense variant — re-throws refetch errors for Error Boundaries */
+    useSuspenseInfinite(args?: TArgs): UseSuspenseInfiniteQueryResult<InfiniteData<TData, number>, Error>;
+}
+/** Dispatches to the plain or infinite hook set based on the declaration. */
+type ResourceQueryHooks<TDef> = TDef extends {
+    infinite: true;
+} ? ResourceInfiniteQueryHooks<ResourceQueryArgs<TDef>, ResourceQueryData<TDef>> : ResourcePlainQueryHooks<ResourceQueryArgs<TDef>, ResourceQueryData<TDef>>;
+/** Hook generated for a mutation declaration. */
+interface ResourceMutationHooks<TDef> {
+    use(): UseMutationResult<ResourceMutationResult<TDef>, Error, ResourceMutationVars<TDef>>;
+}
+/** The detail-query record type of a resource (used by `useForm` defaults). */
+type ResourceDetailData<TResource extends ResourceDef> = TResource["queries"] extends {
+    detail: infer TDetail;
+} ? ResourceQueryData<TDetail> : unknown;
+/** The generated handle for a single resource. */
+type ResourceHandle<TResource extends ResourceDef> = {
+    [Q in keyof TResource["queries"]]: ResourceQueryHooks<TResource["queries"][Q]>;
+} & {
+    [M in keyof NonNullable<TResource["mutations"]>]: ResourceMutationHooks<NonNullable<TResource["mutations"]>[M]>;
+} & {
+    useForm<TValues, TResult = unknown, TRecord = ResourceDetailData<TResource>>(config: ResourceFormConfig<TValues, TRecord, TResult>): ResourceFormResult<TValues, TRecord, TResult>;
+    useSelect<TItem>(config: ResourceSelectConfig<TItem>): ResourceSelectResult<TItem>;
+};
+/** The generated resource handles, keyed by resource name. */
+type Resource<TResources extends ResourcesDeclaration> = {
+    [R in keyof TResources]: ResourceHandle<TResources[R]>;
+};
+interface CreateResourceConfig<TResources extends ResourcesDeclaration> {
+    /** Plugin name used to resolve plugin-specific request headers. */
+    plugin: string;
+    resources: TResources;
+}
+/**
+ * Generates the full hook surface for a plugin's resources.
+ *
+ * Hooks resolve API and router wiring from `StackProvider`, plus any
+ * plugin-specific request headers, at render time so the declaration can
+ * live at module scope.
+ */
+declare function createResource<const TResources extends ResourcesDeclaration>(config: CreateResourceConfig<TResources>): Resource<TResources>;
+
+/**
+ * Plugin-specific request options consumed by the resource layer.
+ */
+interface ResourceOverrides {
+    headers?: HeadersInit;
+}
+
+/** Returns `value` debounced by `delay` milliseconds (default 500). */
+declare function useDebounce<T>(value: T, delay?: number): T;
+
+export { createResource, createUseForm, createUseSelect, useDebounce };
+export type { CreateResourceConfig, Resource, ResourceDetailData, ResourceFormConfig, ResourceFormResult, ResourceHandle, ResourceInfiniteQueryHooks, ResourceMutationHooks, ResourceOverrides, ResourcePlainQueryHooks, ResourceQueryHooks, ResourceQueryOptions, ResourceSelectConfig, ResourceSelectOption, ResourceSelectResult };

package/dist/plugins/client/hooks/index.d.ts

@@ -0,0 +1,204 @@
+import { UseInfiniteQueryResult, InfiniteData, UseSuspenseInfiniteQueryResult, UseQueryResult, UseSuspenseQueryResult, UseMutationResult } from '@tanstack/react-query';
+import { a as StackError, f as ResourceDef, p as ResourcesDeclaration, k as ResourceQueryArgs, l as ResourceQueryData, h as ResourceMutationResult, j as ResourceMutationVars } from '../../../shared/stack.CbZenbej.js';
+
+/** Configuration for the per-resource `useForm` hook. */
+interface ResourceFormConfig<TValues, TRecord = unknown, TResult = unknown> {
+    action: "create" | "edit";
+    /** Detail-query arg identifying the record to edit (e.g. a slug or id) */
+    id?: unknown;
+    /** Query used to fetch the record for edit (default `"detail"`) */
+    detailQuery?: string;
+    /** Mutation used on create submit (default `"create"`) */
+    createMutation?: string;
+    /** Mutation used on edit submit (default `"update"`) */
+    updateMutation?: string;
+    /**
+     * Externally supplied record — skips the internal detail fetch. Useful
+     * when the record comes from a suspense hook higher in the tree.
+     */
+    record?: TRecord | null;
+    /** Default form values, or a function deriving them from the record */
+    defaults?: TValues | ((record: TRecord | null) => TValues);
+    /** Maps form values to create-mutation variables (default: identity) */
+    toCreateVars?: (values: TValues) => unknown;
+    /** Maps form values to update-mutation variables (default: identity) */
+    toUpdateVars?: (values: TValues, record: TRecord | null) => unknown;
+    /** Success notification, sent through the `notify` provider */
+    successMessage?: string | ((result: TResult, action: "create" | "edit") => string);
+    /**
+     * Error notification for non-field errors. Field-level validation errors
+     * land on `fieldErrors` instead of producing a notification.
+     */
+    errorMessage?: string | ((error: StackError) => string);
+    /**
+     * Path to navigate to after success (via the router adapter's
+     * `navigate`). A function form derives it from the result; return a
+     * falsy value to skip navigation.
+     */
+    redirect?: string | ((result: TResult, action: "create" | "edit") => string | false | null | undefined);
+    /** Called after a successful submit (before redirect) */
+    onSuccess?: (result: TResult) => void | Promise<void>;
+}
+/** Result of the per-resource `useForm` hook. */
+interface ResourceFormResult<TValues, TRecord = unknown, TResult = unknown> {
+    action: "create" | "edit";
+    /** The record being edited (null while loading or when creating) */
+    record: TRecord | null;
+    isLoadingRecord: boolean;
+    recordError: Error | null;
+    /** Resolved default values (stable while `record` is unchanged) */
+    defaultValues: TValues | undefined;
+    /** Runs the right mutation; resolves the result, or undefined on error */
+    submit: (values: TValues) => Promise<TResult | undefined>;
+    isSubmitting: boolean;
+    /** Last submit error (normalized), or null */
+    error: StackError | null;
+    /** Field name → validation message(s) from the last submit error */
+    fieldErrors: Record<string, string | string[]>;
+    clearErrors: () => void;
+}
+/**
+ * Builds the per-resource `useForm` hook: bundles the create/edit lifecycle —
+ * fetch record for edit, defaults, submit the right mutation, invalidate,
+ * notify, redirect, and per-field error state from `StackError.errors`.
+ */
+declare function createUseForm(plugin: string, resourceName: string, resource: ResourceDef): <TValues, TRecord = unknown, TResult = unknown>(config: ResourceFormConfig<TValues, TRecord, TResult>) => ResourceFormResult<TValues, TRecord, TResult>;
+
+/** An option produced by the per-resource `useSelect` hook. */
+interface ResourceSelectOption<TItem> {
+    value: string;
+    label: string;
+    /** The underlying record; undefined for values that could not be resolved */
+    item?: TItem;
+}
+/** Configuration for the per-resource `useSelect` hook. */
+interface ResourceSelectConfig<TItem> {
+    /**
+     * Query used to fetch options (default `"list"`). Must be a non-infinite
+     * query whose data is an array of records.
+     */
+    query?: string;
+    /** Maps the (debounced) search text to the option-query args */
+    searchArgs: (search: string) => readonly unknown[];
+    getOptionValue: (item: TItem) => string;
+    getOptionLabel: (item: TItem) => string;
+    /** Currently selected value(s) — preloaded when missing from options */
+    value?: string | string[];
+    /**
+     * Query used to preload selected values missing from the options
+     * (default query `"detail"`). Preloading is skipped when omitted.
+     */
+    preload?: {
+        query?: string;
+        args: (value: string) => readonly unknown[];
+    };
+    /** Debounce for the search text in milliseconds (default 300) */
+    debounceMs?: number;
+    enabled?: boolean;
+}
+/** Result of the per-resource `useSelect` hook. */
+interface ResourceSelectResult<TItem> {
+    /** Search results plus preloaded selected records */
+    options: ResourceSelectOption<TItem>[];
+    /** Options for the current `value(s)`, resolved where possible */
+    selectedOptions: ResourceSelectOption<TItem>[];
+    search: string;
+    setSearch: (search: string) => void;
+    /** Initial load of options or preloaded values in flight */
+    isLoading: boolean;
+    /** Search debounce pending or a search fetch in flight */
+    isSearching: boolean;
+    error: Error | null;
+}
+/**
+ * Builds the per-resource `useSelect` hook: debounced server-side search,
+ * current-value preloading, and loading states for relation pickers.
+ */
+declare function createUseSelect(plugin: string, resourceName: string, resource: ResourceDef): <TItem>(config: ResourceSelectConfig<TItem>) => ResourceSelectResult<TItem>;
+
+/**
+ * `createResource` — generates the repetitive React Query plumbing for a
+ * plugin's resources from a single declaration: plain queries, suspense
+ * queries, infinite queries, mutations with invalidation, plus `useForm`
+ * and `useSelect` per resource.
+ *
+ * The same declaration feeds `createResourceQueryKeys` (see `./queries`),
+ * so SSR loaders and SSG `prefetchForRoute` keys stay in sync with hooks.
+ *
+ * @example
+ * ```ts
+ * const blog = createResource({ plugin: "blog", resources: blogResources });
+ *
+ * export const usePost = (slug?: string) =>
+ *   blog.posts.detail.use([slug ?? ""], { enabled: !!slug });
+ * export const useCreatePost = () => blog.posts.create.use();
+ * ```
+ */
+
+/** Per-call options for generated query hooks. */
+interface ResourceQueryOptions {
+    enabled?: boolean;
+}
+/** Hooks generated for a non-infinite query declaration. */
+interface ResourcePlainQueryHooks<TArgs extends readonly unknown[], TData> {
+    use(args?: TArgs, options?: ResourceQueryOptions): UseQueryResult<TData, Error>;
+    /** Suspense variant — re-throws refetch errors for Error Boundaries */
+    useSuspense(args?: TArgs): UseSuspenseQueryResult<TData, Error>;
+}
+/** Hooks generated for an infinite query declaration. */
+interface ResourceInfiniteQueryHooks<TArgs extends readonly unknown[], TData> {
+    useInfinite(args?: TArgs, options?: ResourceQueryOptions): UseInfiniteQueryResult<InfiniteData<TData, number>, Error>;
+    /** Suspense variant — re-throws refetch errors for Error Boundaries */
+    useSuspenseInfinite(args?: TArgs): UseSuspenseInfiniteQueryResult<InfiniteData<TData, number>, Error>;
+}
+/** Dispatches to the plain or infinite hook set based on the declaration. */
+type ResourceQueryHooks<TDef> = TDef extends {
+    infinite: true;
+} ? ResourceInfiniteQueryHooks<ResourceQueryArgs<TDef>, ResourceQueryData<TDef>> : ResourcePlainQueryHooks<ResourceQueryArgs<TDef>, ResourceQueryData<TDef>>;
+/** Hook generated for a mutation declaration. */
+interface ResourceMutationHooks<TDef> {
+    use(): UseMutationResult<ResourceMutationResult<TDef>, Error, ResourceMutationVars<TDef>>;
+}
+/** The detail-query record type of a resource (used by `useForm` defaults). */
+type ResourceDetailData<TResource extends ResourceDef> = TResource["queries"] extends {
+    detail: infer TDetail;
+} ? ResourceQueryData<TDetail> : unknown;
+/** The generated handle for a single resource. */
+type ResourceHandle<TResource extends ResourceDef> = {
+    [Q in keyof TResource["queries"]]: ResourceQueryHooks<TResource["queries"][Q]>;
+} & {
+    [M in keyof NonNullable<TResource["mutations"]>]: ResourceMutationHooks<NonNullable<TResource["mutations"]>[M]>;
+} & {
+    useForm<TValues, TResult = unknown, TRecord = ResourceDetailData<TResource>>(config: ResourceFormConfig<TValues, TRecord, TResult>): ResourceFormResult<TValues, TRecord, TResult>;
+    useSelect<TItem>(config: ResourceSelectConfig<TItem>): ResourceSelectResult<TItem>;
+};
+/** The generated resource handles, keyed by resource name. */
+type Resource<TResources extends ResourcesDeclaration> = {
+    [R in keyof TResources]: ResourceHandle<TResources[R]>;
+};
+interface CreateResourceConfig<TResources extends ResourcesDeclaration> {
+    /** Plugin name used to resolve plugin-specific request headers. */
+    plugin: string;
+    resources: TResources;
+}
+/**
+ * Generates the full hook surface for a plugin's resources.
+ *
+ * Hooks resolve API and router wiring from `StackProvider`, plus any
+ * plugin-specific request headers, at render time so the declaration can
+ * live at module scope.
+ */
+declare function createResource<const TResources extends ResourcesDeclaration>(config: CreateResourceConfig<TResources>): Resource<TResources>;
+
+/**
+ * Plugin-specific request options consumed by the resource layer.
+ */
+interface ResourceOverrides {
+    headers?: HeadersInit;
+}
+
+/** Returns `value` debounced by `delay` milliseconds (default 500). */
+declare function useDebounce<T>(value: T, delay?: number): T;
+
+export { createResource, createUseForm, createUseSelect, useDebounce };
+export type { CreateResourceConfig, Resource, ResourceDetailData, ResourceFormConfig, ResourceFormResult, ResourceHandle, ResourceInfiniteQueryHooks, ResourceMutationHooks, ResourceOverrides, ResourcePlainQueryHooks, ResourceQueryHooks, ResourceQueryOptions, ResourceSelectConfig, ResourceSelectOption, ResourceSelectResult };

package/dist/plugins/client/hooks/index.mjs

@@ -0,0 +1,4 @@
+export { createResource } from '../../../packages/stack/src/plugins/client/resource/hooks.mjs';
+export { createUseForm } from '../../../packages/stack/src/plugins/client/resource/use-form.mjs';
+export { createUseSelect } from '../../../packages/stack/src/plugins/client/resource/use-select.mjs';
+export { useDebounce } from '../../../packages/stack/src/plugins/client/resource/use-debounce.mjs';

package/dist/plugins/client/index.cjs

@@ -1,6 +1,8 @@
 'use strict';
 
 const utils = require('../../packages/stack/src/plugins/utils.cjs');
+const errors = require('../../packages/stack/src/plugins/client/resource/errors.cjs');
+const queries = require('../../packages/stack/src/plugins/client/resource/queries.cjs');
 const yar = require('@btst/yar');
 const client = require('better-call/client');
 
@@ -12,8 +14,17 @@ exports.SSR_LOADER_ERROR_MESSAGE = utils.SSR_LOADER_ERROR_MESSAGE;
 exports.createApiClient = utils.createApiClient;
 exports.createSanitizedSSRLoaderError = utils.createSanitizedSSRLoaderError;
 exports.isConnectionError = utils.isConnectionError;
-exports.runClientHookWithShim = utils.runClientHookWithShim;
+exports.SHARED_QUERY_CONFIG = errors.SHARED_QUERY_CONFIG;
+exports.isErrorResponse = errors.isErrorResponse;
+exports.toError = errors.toError;
+exports.buildQueryKey = queries.buildQueryKey;
+exports.createResourceQueryKeys = queries.createResourceQueryKeys;
+exports.resolvePageSize = queries.resolvePageSize;
+exports.runResourceMutation = queries.runResourceMutation;
+exports.runResourceQuery = queries.runResourceQuery;
 exports.createRoute = yar.createRoute;
 exports.createRouter = yar.createRouter;
+exports.defineRoute = yar.defineRoute;
+exports.defineRoutes = yar.defineRoutes;
 exports.createClient = client.createClient;
 exports.defineClientPlugin = defineClientPlugin;