@btst/stack 2.12.2 → 3.0.0-rc.2

package/dist/client/index.d.ts

@@ -1,8 +1,9 @@
-import { c as Sitemap, C as ClientPlugin, d as PluginRoutes, e as ClientLibConfig, f as ClientLib } from '../shared/stack.CQnwAN7x.js';
-export { b as ClientStackContext } from '../shared/stack.CQnwAN7x.js';
+import { c as Sitemap, C as ClientPlugin, d as PluginRoutes, e as ClientLibConfig, f as ClientLib } from '../shared/stack.BqTR6qi2.js';
+export { b as ClientStackContext } from '../shared/stack.BqTR6qi2.js';
 import '@btst/yar';
 import '@btst/db';
 import 'better-call';
+import '../shared/stack.C4_gEENS.js';
 
 /**
  * Converts an array of sitemap entries into an XML string following the sitemap.org protocol.
@@ -96,6 +97,65 @@ declare function metaElementsToObject(metaElements: Array<React.JSX.IntrinsicEle
  */
 declare function normalizePath(path?: string | Array<string> | undefined): string;
 
+type ListStateFieldType = "string" | "number" | "boolean";
+interface ListStateField<T extends ListStateFieldType = ListStateFieldType> {
+    type: T;
+    default: T extends "string" ? string : T extends "number" ? number : boolean;
+    /**
+     * How URL history is updated when this field changes.
+     * - `"push"` (default): discrete changes (tab switch, page change) — back button undoes.
+     * - `"replace"`: rapid changes (typing in a filter) — no extra history entries.
+     */
+    history?: "push" | "replace";
+}
+type ListStateSchema = Record<string, ListStateField>;
+type InferListStateValue<F extends ListStateField> = F["type"] extends "string" ? string : F["type"] extends "number" ? number : boolean;
+type InferListState<S extends ListStateSchema> = {
+    [K in keyof S]: InferListStateValue<S[K]>;
+};
+/**
+ * URL query param key for a list-state field.
+ * The `namespace` argument identifies the hook instance for SSR helpers but
+ * does not prefix URL keys — field names are used directly (e.g. `?tab=spam`).
+ */
+declare function listStateParamKey(_namespace: string, fieldKey: string): string;
+/**
+ * Parse list state from URL search params (SSR-safe — pass the request URL's
+ * search string or a `URLSearchParams` instance).
+ */
+declare function parseListStateFromSearchParams<S extends ListStateSchema>(namespace: string, schema: S, searchParams: URLSearchParams | string): InferListState<S>;
+/**
+ * Serialize list state into URL search params. Default values are omitted for
+ * clean URLs.
+ */
+declare function serializeListStateToSearchParams<S extends ListStateSchema>(namespace: string, schema: S, state: InferListState<S>, baseParams?: URLSearchParams): URLSearchParams;
+
+type SetListStateOptions = {
+    /** Force `replace` vs `push` history semantics for this update */
+    replace?: boolean;
+};
+type SetListState<S extends ListStateSchema> = (updates: Partial<InferListState<S>> | ((prev: InferListState<S>) => Partial<InferListState<S>>), options?: SetListStateOptions) => void;
+/**
+ * Sync list UI state (filters, tabs, pagination) with URL search params.
+ *
+ * Defaults are omitted from the URL. Field-level `history: "replace"` is used
+ * for rapid changes; discrete changes (tab/page) default to `push` so the back
+ * button undoes them.
+ *
+ * The `namespace` identifies this list state for SSR helpers; URL keys use
+ * the schema field names directly.
+ *
+ * @example
+ * ```tsx
+ * const [state, setState] = useListState("comments-moderation", {
+ *   tab: { type: "string", default: "pending" },
+ *   page: { type: "number", default: 1 },
+ * });
+ * // URL: ?tab=spam&page=3
+ * ```
+ */
+declare function useListState<S extends ListStateSchema>(namespace: string, schema: S): [InferListState<S>, SetListState<S>];
+
 /**
  * Creates the client library with plugin support
  *
@@ -145,4 +205,5 @@ declare function normalizePath(path?: string | Array<string> | undefined): strin
  */
 declare function createStackClient<TPlugins extends Record<string, ClientPlugin<any, any>>, TRoutes extends PluginRoutes<TPlugins> = PluginRoutes<TPlugins>>(config: ClientLibConfig<TPlugins>): ClientLib<TRoutes>;
 
-export { ClientLib, ClientLibConfig, ClientPlugin, createStackClient, metaElementsToObject, normalizePath, sitemapEntryToXmlString };
+export { ClientLib, ClientLibConfig, ClientPlugin, createStackClient, listStateParamKey, metaElementsToObject, normalizePath, parseListStateFromSearchParams, serializeListStateToSearchParams, sitemapEntryToXmlString, useListState };
+export type { InferListState, ListStateField, ListStateSchema, SetListState, SetListStateOptions };

package/dist/client/index.mjs

@@ -2,6 +2,8 @@ import { createRouter } from '@btst/yar';
 export { sitemapEntryToXmlString } from '../packages/stack/src/client/sitemap-utils.mjs';
 export { metaElementsToObject } from '../packages/stack/src/client/meta-utils.mjs';
 export { normalizePath } from '../packages/stack/src/client/path-utils.mjs';
+export { useListState } from '../packages/stack/src/client/hooks/use-list-state.mjs';
+export { listStateParamKey, parseListStateFromSearchParams, serializeListStateToSearchParams } from '../packages/stack/src/shared/list-state.mjs';
 
 function createStackClient(config) {
   const { plugins, basePath } = config;

package/dist/context/index.cjs

@@ -1,6 +1,9 @@
 'use strict';
 
 const provider = require('../packages/stack/src/context/provider.cjs');
+const auth = require('../packages/stack/src/context/auth.cjs');
+const notify = require('../packages/stack/src/context/notify.cjs');
+const i18n = require('../packages/stack/src/context/i18n.cjs');
 
 
 
@@ -8,3 +11,10 @@ exports.StackProvider = provider.StackProvider;
 exports.useBasePath = provider.useBasePath;
 exports.usePluginOverrides = provider.usePluginOverrides;
 exports.useStack = provider.useStack;
+exports.useStackOrNull = provider.useStackOrNull;
+exports.CanAccess = auth.CanAccess;
+exports.useCan = auth.useCan;
+exports.useIdentity = auth.useIdentity;
+exports.defaultNotifyProvider = notify.defaultNotifyProvider;
+exports.useNotify = notify.useNotify;
+exports.useTranslate = i18n.useTranslate;

package/dist/context/index.d.cts

@@ -1,5 +1,65 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
+import { a as StackAuthProvider, C as CanParams, b as StackIdentity } from '../shared/stack.C4_gEENS.cjs';
+export { S as StackServerAuthProvider } from '../shared/stack.C4_gEENS.cjs';
+import { S as StackRouterConfig, a as StackApiConfig, b as StackRouter } from '../shared/stack.aqVZ6PEW.cjs';
+
+/**
+ * Optional i18n provider, passed to `StackProvider` via the `i18n` prop.
+ *
+ * Without a provider, `useTranslate()` returns the default English string with
+ * `{{param}}` interpolation — zero setup cost for English-only apps.
+ *
+ * @example
+ * ```tsx
+ * const i18n: StackI18nProvider = {
+ *   translate: (key, defaultValue, params) =>
+ *     t(key, { defaultValue, ...params }),
+ * };
+ *
+ * <StackProvider i18n={i18n} ...>
+ * ```
+ */
+interface StackI18nProvider {
+    /**
+     * Translate a namespaced key. Receives the English default and optional
+     * interpolation params when no translation exists for the key.
+     */
+    translate: (key: string, defaultValue: string, params?: Record<string, unknown>) => string;
+    /** Return the active locale (optional) */
+    getLocale?: () => string;
+    /** Switch locale (optional) */
+    changeLocale?: (locale: string) => void;
+}
+
+/**
+ * Options passed to notification methods.
+ */
+interface NotifyOptions {
+    /** Optional longer description shown below the message */
+    description?: string;
+}
+/**
+ * Pluggable notification provider, passed to `StackProvider` via the `notify` prop.
+ *
+ * When omitted, sonner toasts are used as the default implementation.
+ *
+ * @example
+ * ```tsx
+ * const notify: StackNotifyProvider = {
+ *   success: (msg) => myToast.success(msg),
+ *   error: (msg) => myToast.error(msg),
+ * };
+ *
+ * <StackProvider notify={notify} ...>
+ * ```
+ */
+interface StackNotifyProvider {
+    success?: (message: string, options?: NotifyOptions) => void;
+    error?: (message: string, options?: NotifyOptions) => void;
+    info?: (message: string, options?: NotifyOptions) => void;
+    warning?: (message: string, options?: NotifyOptions) => void;
+}
 
 /**
  * Context value that provides plugin-specific overrides
@@ -14,7 +74,24 @@ interface StackContextValue<TPluginOverrides extends Record<string, any>> {
      * The base path where the client router is mounted.
      */
     basePath: string;
+    /**
+     * Resolved top-level router (static preset fields merged with the
+     * preset's `useRouter` hook result).
+     */
+    router?: StackRouter;
+    /**
+     * Top-level API config applied to all plugins.
+     */
+    api?: StackApiConfig;
+    /** Top-level auth provider used by identity-aware components. */
+    auth?: StackAuthProvider;
 }
+/**
+ * The `overrides` prop shape for `StackProvider`.
+ * Plugin blocks are optional; fields inside each block retain the plugin's
+ * declared requirements.
+ */
+type StackProviderOverrides<TPluginOverrides extends Record<string, any>> = Partial<TPluginOverrides>;
 /**
  * Provider component for BTST context
  * Provides type-safe access to plugin-specific overrides
@@ -25,16 +102,13 @@ interface StackContextValue<TPluginOverrides extends Record<string, any>> {
  * ```tsx
  * // Define the type shape (no import of plugin values needed!)
  * type MyPluginOverrides = {
- *   todos: TodosPluginOverrides;
  *   messages: MessagesPluginOverrides;
  * };
  *
  * <StackProvider<MyPluginOverrides>
+ *   router={frameworkRouter}
+ *   api={{ baseURL, basePath: "/api/data" }}
  *   overrides={{
- *     todos: {
- *       Link: (props) => <NextLink {...props} />,
- *       navigate: (path) => router.push(path),
- *     },
  *     messages: {
  *       MarkdownRenderer: (props) => <ReactMarkdown {...props} />,
  *     }
@@ -43,11 +117,49 @@ interface StackContextValue<TPluginOverrides extends Record<string, any>> {
  *   {children}
  * </StackProvider>
  * ```
+ *
+ * Framework router and API wiring live at the top level. Per-plugin overrides
+ * carry only genuinely plugin-specific values:
+ *
+ * @example
+ * ```tsx
+ * import { nextRouter } from "@btst/stack/next";
+ *
+ * <StackProvider<MyPluginOverrides>
+ *   basePath="/pages"
+ *   router={nextRouter()}
+ *   api={{ baseURL, basePath: "/api/data" }}
+ *   overrides={{
+ *     blog: { uploadImage },
+ *   }}
+ * >
+ *   {children}
+ * </StackProvider>
+ * ```
  */
-declare function StackProvider<TPluginOverrides extends Record<string, any> = Record<string, any>>({ children, overrides, basePath, }: {
+declare function StackProvider<TPluginOverrides extends Record<string, any> = Record<string, any>>({ children, overrides, basePath, router, api, auth, notify, i18n, }: {
     children?: ReactNode;
-    overrides: TPluginOverrides;
+    overrides?: StackProviderOverrides<TPluginOverrides>;
     basePath: string;
+    router?: StackRouterConfig;
+    api?: StackApiConfig;
+    /**
+     * Optional auth provider. When set, `useIdentity()` / `useCan()` and
+     * `<CanAccess>` resolve identity and permissions through it. When omitted,
+     * behavior is identical to before: identity is `null` and all permission
+     * checks pass.
+     */
+    auth?: StackAuthProvider;
+    /**
+     * Optional notification provider. When omitted, sonner toasts are used via
+     * `useNotify()`.
+     */
+    notify?: StackNotifyProvider;
+    /**
+     * Optional i18n provider. When omitted, `useTranslate()` returns English
+     * defaults with `{{param}}` interpolation.
+     */
+    i18n?: StackI18nProvider;
 }): react_jsx_runtime.JSX.Element;
 /**
  * Hook to access the entire BTST context
@@ -62,6 +174,14 @@ declare function StackProvider<TPluginOverrides extends Record<string, any> = Re
  * ```
  */
 declare function useStack<TPluginOverrides extends Record<string, any> = Record<string, any>>(): StackContextValue<TPluginOverrides>;
+/**
+ * Like `useStack`, but returns `null` instead of throwing when rendered
+ * outside a `StackProvider`.
+ *
+ * @internal Used by core components (e.g. route gating) that must not change
+ * behavior for consumers rendering outside the provider.
+ */
+declare function useStackOrNull<TPluginOverrides extends Record<string, any> = Record<string, any>>(): StackContextValue<TPluginOverrides> | null;
 type OverridesResult<TOverrides, TDefaults> = undefined extends TDefaults ? TOverrides : TOverrides & Required<Pick<TDefaults & {}, keyof TDefaults>>;
 /**
  * Hook to access overrides for a specific plugin
@@ -72,15 +192,14 @@ type OverridesResult<TOverrides, TDefaults> = undefined extends TDefaults ? TOve
  * @example
  * ```tsx
  * // Without defaults - trusts plugin is configured
- * function TodosList() {
- *   const { navigate } = usePluginOverrides<TodosPluginOverrides>("todos");
- *   // navigate is (path: string) => void (required fields are non-nullable)
- *   navigate("/todos/add");
+ * function MessagesList() {
+ *   const { MarkdownRenderer } = usePluginOverrides<MessagesPluginOverrides>("messages");
+ *   return <MarkdownRenderer>{message.body}</MarkdownRenderer>;
  * }
  *
  * // With defaults - optional fields with defaults become required
- * function TodosList() {
- *   const { localization } = usePluginOverrides<TodosPluginOverrides, Partial<TodosPluginOverrides>>("todos", {
+ * function MessagesList() {
+ *   const { localization } = usePluginOverrides<MessagesPluginOverrides, Partial<MessagesPluginOverrides>>("messages", {
  *     localization: DEFAULT_LOCALIZATION
  *   });
  *   // localization is Localization (guaranteed to exist because we provided a default)
@@ -103,4 +222,99 @@ declare function usePluginOverrides<TOverrides = any, TDefaults extends Partial<
  */
 declare function useBasePath(): string;
 
-export { StackProvider, useBasePath, usePluginOverrides, useStack };
+/**
+ * Returns the current user's identity as resolved by the auth provider
+ * configured on `StackProvider`.
+ *
+ * Without an auth provider, returns `{ identity: null, isPending: false }`.
+ *
+ * @example
+ * ```tsx
+ * const { identity, isPending } = useIdentity();
+ * if (identity) return <span>Hello {identity.name}</span>;
+ * ```
+ */
+declare function useIdentity(): {
+    identity: StackIdentity | null;
+    isPending: boolean;
+    refetch: () => Promise<void>;
+};
+type CanState = {
+    can: boolean;
+    isPending: boolean;
+};
+/**
+ * Checks whether the current user can perform `action` on `resource` using
+ * the auth provider's `can()` function.
+ *
+ * Resolves to `{ can: true, isPending: false }` immediately when no auth
+ * provider is configured or the provider has no `can()` function — permission
+ * checks are opt-in and non-breaking.
+ *
+ * While the identity or the `can()` result is still resolving, returns
+ * `{ can: false, isPending: true }` so callers can avoid flashing
+ * permission-gated UI.
+ *
+ * @example
+ * ```tsx
+ * const { can, isPending } = useCan({ resource: "blog:post", action: "delete" });
+ * if (!isPending && can) return <DeletePostButton />;
+ * ```
+ */
+declare function useCan(params: CanParams): CanState;
+/**
+ * Element-level permission gate (Refine's `<CanAccess>` pattern).
+ *
+ * - Without an auth provider configured, always renders `children`.
+ * - While the check is pending, renders `loading` (default `null`) to avoid
+ *   flashing gated UI.
+ * - Renders `children` when `can()` allows, `fallback` (default `null`)
+ *   otherwise.
+ *
+ * @example
+ * ```tsx
+ * <CanAccess resource="blog:post" action="delete" fallback={null}>
+ *   <DeletePostButton />
+ * </CanAccess>
+ * ```
+ */
+declare function CanAccess({ resource, action, params, fallback, loading, children, }: CanParams & {
+    /** Rendered when access is denied (default `null`) */
+    fallback?: ReactNode;
+    /** Rendered while the permission check is pending (default `null`) */
+    loading?: ReactNode;
+    children?: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+/** Sonner-backed defaults used when no custom `notify` prop is configured. */
+declare const defaultNotifyProvider: Required<StackNotifyProvider>;
+/**
+ * Returns notification methods routed through the `notify` provider on
+ * `StackProvider`, falling back to sonner toasts when no override is set.
+ *
+ * @example
+ * ```tsx
+ * const notify = useNotify();
+ * notify.success("Post saved");
+ * notify.error("Failed to delete", { description: "Try again later" });
+ * ```
+ */
+declare function useNotify(): Required<StackNotifyProvider>;
+
+type TranslateFn = (key: string, defaultValue: string, params?: Record<string, unknown>) => string;
+/**
+ * Returns a `t(key, defaultValue, params?)` function for translatable UI strings.
+ *
+ * Without an `i18n` provider on `StackProvider`, returns the default English
+ * string with `{{param}}` interpolation — identical to hardcoded strings today.
+ *
+ * @example
+ * ```tsx
+ * const t = useTranslate();
+ * return <button>{t("blog.posts.create", "Create Post")}</button>;
+ * ```
+ */
+declare function useTranslate(): TranslateFn;
+
+export { CanAccess, CanParams, StackApiConfig, StackAuthProvider, StackIdentity, StackProvider, StackRouter, StackRouterConfig, defaultNotifyProvider, useBasePath, useCan, useIdentity, useNotify, usePluginOverrides, useStack, useStackOrNull, useTranslate };
+export type { NotifyOptions, StackI18nProvider, StackNotifyProvider, StackProviderOverrides, TranslateFn };