@btst/stack 2.12.2 → 3.0.0-rc.2

package/dist/next/index.d.cts

@@ -0,0 +1,97 @@
+import { S as StackRequestHandler, R as ResolveStackClient } from '../shared/stack.EOPVnJrF.cjs';
+export { G as GetStackClient } from '../shared/stack.EOPVnJrF.cjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { QueryClient, DehydrateOptions } from '@tanstack/react-query';
+import { Metadata } from 'next';
+import { ReactNode } from 'react';
+import { S as StackRouterConfig } from '../shared/stack.aqVZ6PEW.cjs';
+
+/**
+ * Wires a BTST API handler to the five HTTP method exports a Next.js route
+ * handler file needs.
+ *
+ * @example
+ * ```ts
+ * // app/api/data/[[...all]]/route.ts
+ * import { toNextRouteHandlers } from "@btst/stack/next";
+ * import { handler } from "@/lib/stack";
+ *
+ * export const { GET, POST, PUT, PATCH, DELETE } = toNextRouteHandlers(handler);
+ * ```
+ */
+declare function toNextRouteHandlers(handler: StackRequestHandler): {
+    GET: StackRequestHandler;
+    POST: StackRequestHandler;
+    PUT: StackRequestHandler;
+    PATCH: StackRequestHandler;
+    DELETE: StackRequestHandler;
+};
+
+interface NextPageProps {
+    params: Promise<{
+        all?: string[];
+    }>;
+}
+/** Resolves the stack client for a Next.js page or metadata request. */
+type GetNextStackClient = ResolveStackClient<NextPageProps>;
+interface CreateNextPageOptions {
+    /**
+     * Returns the stack client for the current request. May be async and receives
+     * the page props so request-aware clients can resolve request-local state.
+     */
+    getStackClient: GetNextStackClient;
+    /** Returns the QueryClient for the current context (`lib/query-client`). */
+    getQueryClient: () => QueryClient;
+    /**
+     * Called when no route matches the path. Defaults to `notFound()` from
+     * `next/navigation`.
+     */
+    notFound?: () => never;
+    /** Wraps the rendered page (inside the `HydrationBoundary`). */
+    wrapPage?: (page: ReactNode) => ReactNode;
+    /**
+     * Options passed to `dehydrate()`. Defaults to dehydrating failed queries
+     * in addition to the React Query defaults, so the client does not refetch
+     * queries that errored during SSR. Override e.g. to sanitize error
+     * payloads before they are serialized into the HTML.
+     */
+    dehydrateOptions?: DehydrateOptions;
+}
+/**
+ * Creates the Next.js catch-all page for BTST plugin routes: SSR prefetch via
+ * `route.loader()`, React Query dehydration (including failed queries),
+ * `generateMetadata` with loader-before-meta ordering, and 404 via
+ * `notFound()`.
+ *
+ * @example
+ * ```tsx
+ * // app/pages/[[...all]]/page.tsx
+ * import { createNextPage } from "@btst/stack/next";
+ * import { getOrCreateQueryClient } from "@/lib/query-client";
+ * import { getStackClient } from "@/lib/stack-client";
+ *
+ * export const dynamic = "force-dynamic";
+ * const page = createNextPage({ getStackClient, getQueryClient: getOrCreateQueryClient });
+ * export default page.Page;
+ * export const generateMetadata = page.generateMetadata;
+ * ```
+ */
+declare function createNextPage(options: CreateNextPageOptions): {
+    Page: (pageProps: NextPageProps) => Promise<react_jsx_runtime.JSX.Element>;
+    generateMetadata: (pageProps: NextPageProps) => Promise<Metadata>;
+};
+
+/**
+ * Router preset for Next.js (App Router).
+ *
+ * @example
+ * ```tsx
+ * import { nextRouter } from "@btst/stack/next";
+ *
+ * <StackProvider basePath="/pages" router={nextRouter()} api={{ baseURL, basePath: "/api/data" }}>
+ * ```
+ */
+declare function nextRouter(): StackRouterConfig;
+
+export { ResolveStackClient, StackRequestHandler, createNextPage, nextRouter, toNextRouteHandlers };
+export type { CreateNextPageOptions, GetNextStackClient, NextPageProps };

package/dist/next/index.d.mts

@@ -0,0 +1,97 @@
+import { S as StackRequestHandler, R as ResolveStackClient } from '../shared/stack.EOPVnJrF.mjs';
+export { G as GetStackClient } from '../shared/stack.EOPVnJrF.mjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { QueryClient, DehydrateOptions } from '@tanstack/react-query';
+import { Metadata } from 'next';
+import { ReactNode } from 'react';
+import { S as StackRouterConfig } from '../shared/stack.aqVZ6PEW.mjs';
+
+/**
+ * Wires a BTST API handler to the five HTTP method exports a Next.js route
+ * handler file needs.
+ *
+ * @example
+ * ```ts
+ * // app/api/data/[[...all]]/route.ts
+ * import { toNextRouteHandlers } from "@btst/stack/next";
+ * import { handler } from "@/lib/stack";
+ *
+ * export const { GET, POST, PUT, PATCH, DELETE } = toNextRouteHandlers(handler);
+ * ```
+ */
+declare function toNextRouteHandlers(handler: StackRequestHandler): {
+    GET: StackRequestHandler;
+    POST: StackRequestHandler;
+    PUT: StackRequestHandler;
+    PATCH: StackRequestHandler;
+    DELETE: StackRequestHandler;
+};
+
+interface NextPageProps {
+    params: Promise<{
+        all?: string[];
+    }>;
+}
+/** Resolves the stack client for a Next.js page or metadata request. */
+type GetNextStackClient = ResolveStackClient<NextPageProps>;
+interface CreateNextPageOptions {
+    /**
+     * Returns the stack client for the current request. May be async and receives
+     * the page props so request-aware clients can resolve request-local state.
+     */
+    getStackClient: GetNextStackClient;
+    /** Returns the QueryClient for the current context (`lib/query-client`). */
+    getQueryClient: () => QueryClient;
+    /**
+     * Called when no route matches the path. Defaults to `notFound()` from
+     * `next/navigation`.
+     */
+    notFound?: () => never;
+    /** Wraps the rendered page (inside the `HydrationBoundary`). */
+    wrapPage?: (page: ReactNode) => ReactNode;
+    /**
+     * Options passed to `dehydrate()`. Defaults to dehydrating failed queries
+     * in addition to the React Query defaults, so the client does not refetch
+     * queries that errored during SSR. Override e.g. to sanitize error
+     * payloads before they are serialized into the HTML.
+     */
+    dehydrateOptions?: DehydrateOptions;
+}
+/**
+ * Creates the Next.js catch-all page for BTST plugin routes: SSR prefetch via
+ * `route.loader()`, React Query dehydration (including failed queries),
+ * `generateMetadata` with loader-before-meta ordering, and 404 via
+ * `notFound()`.
+ *
+ * @example
+ * ```tsx
+ * // app/pages/[[...all]]/page.tsx
+ * import { createNextPage } from "@btst/stack/next";
+ * import { getOrCreateQueryClient } from "@/lib/query-client";
+ * import { getStackClient } from "@/lib/stack-client";
+ *
+ * export const dynamic = "force-dynamic";
+ * const page = createNextPage({ getStackClient, getQueryClient: getOrCreateQueryClient });
+ * export default page.Page;
+ * export const generateMetadata = page.generateMetadata;
+ * ```
+ */
+declare function createNextPage(options: CreateNextPageOptions): {
+    Page: (pageProps: NextPageProps) => Promise<react_jsx_runtime.JSX.Element>;
+    generateMetadata: (pageProps: NextPageProps) => Promise<Metadata>;
+};
+
+/**
+ * Router preset for Next.js (App Router).
+ *
+ * @example
+ * ```tsx
+ * import { nextRouter } from "@btst/stack/next";
+ *
+ * <StackProvider basePath="/pages" router={nextRouter()} api={{ baseURL, basePath: "/api/data" }}>
+ * ```
+ */
+declare function nextRouter(): StackRouterConfig;
+
+export { ResolveStackClient, StackRequestHandler, createNextPage, nextRouter, toNextRouteHandlers };
+export type { CreateNextPageOptions, GetNextStackClient, NextPageProps };

package/dist/next/index.d.ts

@@ -0,0 +1,97 @@
+import { S as StackRequestHandler, R as ResolveStackClient } from '../shared/stack.EOPVnJrF.js';
+export { G as GetStackClient } from '../shared/stack.EOPVnJrF.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { QueryClient, DehydrateOptions } from '@tanstack/react-query';
+import { Metadata } from 'next';
+import { ReactNode } from 'react';
+import { S as StackRouterConfig } from '../shared/stack.aqVZ6PEW.js';
+
+/**
+ * Wires a BTST API handler to the five HTTP method exports a Next.js route
+ * handler file needs.
+ *
+ * @example
+ * ```ts
+ * // app/api/data/[[...all]]/route.ts
+ * import { toNextRouteHandlers } from "@btst/stack/next";
+ * import { handler } from "@/lib/stack";
+ *
+ * export const { GET, POST, PUT, PATCH, DELETE } = toNextRouteHandlers(handler);
+ * ```
+ */
+declare function toNextRouteHandlers(handler: StackRequestHandler): {
+    GET: StackRequestHandler;
+    POST: StackRequestHandler;
+    PUT: StackRequestHandler;
+    PATCH: StackRequestHandler;
+    DELETE: StackRequestHandler;
+};
+
+interface NextPageProps {
+    params: Promise<{
+        all?: string[];
+    }>;
+}
+/** Resolves the stack client for a Next.js page or metadata request. */
+type GetNextStackClient = ResolveStackClient<NextPageProps>;
+interface CreateNextPageOptions {
+    /**
+     * Returns the stack client for the current request. May be async and receives
+     * the page props so request-aware clients can resolve request-local state.
+     */
+    getStackClient: GetNextStackClient;
+    /** Returns the QueryClient for the current context (`lib/query-client`). */
+    getQueryClient: () => QueryClient;
+    /**
+     * Called when no route matches the path. Defaults to `notFound()` from
+     * `next/navigation`.
+     */
+    notFound?: () => never;
+    /** Wraps the rendered page (inside the `HydrationBoundary`). */
+    wrapPage?: (page: ReactNode) => ReactNode;
+    /**
+     * Options passed to `dehydrate()`. Defaults to dehydrating failed queries
+     * in addition to the React Query defaults, so the client does not refetch
+     * queries that errored during SSR. Override e.g. to sanitize error
+     * payloads before they are serialized into the HTML.
+     */
+    dehydrateOptions?: DehydrateOptions;
+}
+/**
+ * Creates the Next.js catch-all page for BTST plugin routes: SSR prefetch via
+ * `route.loader()`, React Query dehydration (including failed queries),
+ * `generateMetadata` with loader-before-meta ordering, and 404 via
+ * `notFound()`.
+ *
+ * @example
+ * ```tsx
+ * // app/pages/[[...all]]/page.tsx
+ * import { createNextPage } from "@btst/stack/next";
+ * import { getOrCreateQueryClient } from "@/lib/query-client";
+ * import { getStackClient } from "@/lib/stack-client";
+ *
+ * export const dynamic = "force-dynamic";
+ * const page = createNextPage({ getStackClient, getQueryClient: getOrCreateQueryClient });
+ * export default page.Page;
+ * export const generateMetadata = page.generateMetadata;
+ * ```
+ */
+declare function createNextPage(options: CreateNextPageOptions): {
+    Page: (pageProps: NextPageProps) => Promise<react_jsx_runtime.JSX.Element>;
+    generateMetadata: (pageProps: NextPageProps) => Promise<Metadata>;
+};
+
+/**
+ * Router preset for Next.js (App Router).
+ *
+ * @example
+ * ```tsx
+ * import { nextRouter } from "@btst/stack/next";
+ *
+ * <StackProvider basePath="/pages" router={nextRouter()} api={{ baseURL, basePath: "/api/data" }}>
+ * ```
+ */
+declare function nextRouter(): StackRouterConfig;
+
+export { ResolveStackClient, StackRequestHandler, createNextPage, nextRouter, toNextRouteHandlers };
+export type { CreateNextPageOptions, GetNextStackClient, NextPageProps };

package/dist/next/index.mjs

@@ -0,0 +1,3 @@
+export { toNextRouteHandlers } from '../packages/stack/src/next/handlers.mjs';
+export { createNextPage } from '../packages/stack/src/next/page.mjs';
+export { nextRouter } from '../packages/stack/src/next/router.mjs';

package/dist/packages/stack/src/client/components/compose.cjs

@@ -3,8 +3,14 @@
 
 const jsxRuntime = require('react/jsx-runtime');
 const React = require('react');
+const auth = require('../../context/auth.cjs');
+const provider = require('../../context/provider.cjs');
 const errorBoundary = require('./error-boundary.cjs');
 
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e.default : e; }
+
+const React__default = /*#__PURE__*/_interopDefaultCompat(React);
+
 function RouteRenderer({
   router,
   path,
@@ -13,7 +19,7 @@ function RouteRenderer({
   onError,
   props
 }) {
-  const route = router.getRoute(path);
+  const route = React__default.useMemo(() => router.getRoute(path), [router, path]);
   return /* @__PURE__ */ jsxRuntime.jsx(
     ComposedRoute,
     {
@@ -28,6 +34,42 @@ function RouteRenderer({
     }
   );
 }
+function RouteGuard({
+  permission,
+  LoadingComponent,
+  children
+}) {
+  const auth$1 = auth.useAuthContext();
+  const stack = provider.useStackOrNull();
+  const { can, isPending } = auth.useCan(permission);
+  const identity = auth$1?.identity ?? null;
+  const loginPath = auth$1?.provider.loginPath;
+  const navigate = stack?.router?.navigate;
+  const shouldRedirect = !!auth$1 && !isPending && !can && !identity && !!loginPath;
+  React.useEffect(() => {
+    if (!shouldRedirect || !loginPath) return;
+    if (navigate) {
+      void navigate(loginPath);
+    } else if (typeof window !== "undefined") {
+      window.location.assign(loginPath);
+    }
+  }, [shouldRedirect, loginPath, navigate]);
+  if (!auth$1) {
+    return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children });
+  }
+  if (isPending || shouldRedirect) {
+    return LoadingComponent ? /* @__PURE__ */ jsxRuntime.jsx(LoadingComponent, {}) : null;
+  }
+  if (can) {
+    return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children });
+  }
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[btst/auth] RouteGuard denied: cannot ${permission.action} ${permission.resource}`
+    );
+  }
+  throw new Error("Unauthorized");
+}
 function ComposedRoute({
   path,
   PageComponent,
@@ -36,10 +78,11 @@ function ComposedRoute({
   onNotFound,
   NotFoundComponent,
   props,
-  onError
+  onError,
+  permission
 }) {
   if (PageComponent) {
-    const content = /* @__PURE__ */ jsxRuntime.jsx(PageComponent, { ...props });
+    const content = permission ? /* @__PURE__ */ jsxRuntime.jsx(RouteGuard, { permission, LoadingComponent, children: /* @__PURE__ */ jsxRuntime.jsx(PageComponent, { ...props }) }) : /* @__PURE__ */ jsxRuntime.jsx(PageComponent, { ...props });
     const suspenseFallback = LoadingComponent ? /* @__PURE__ */ jsxRuntime.jsx(LoadingComponent, {}) : null;
     if (ErrorComponent) {
       return /* @__PURE__ */ jsxRuntime.jsx(React.Suspense, { fallback: suspenseFallback, children: /* @__PURE__ */ jsxRuntime.jsx(

package/dist/packages/stack/src/client/components/compose.mjs

@@ -1,6 +1,8 @@
 "use client";
-import { jsx } from 'react/jsx-runtime';
-import { Suspense } from 'react';
+import { jsx, Fragment } from 'react/jsx-runtime';
+import React__default, { Suspense, useEffect } from 'react';
+import { useAuthContext, useCan } from '../../context/auth.mjs';
+import { useStackOrNull } from '../../context/provider.mjs';
 import { ErrorBoundary } from './error-boundary.mjs';
 
 function RouteRenderer({
@@ -11,7 +13,7 @@ function RouteRenderer({
   onError,
   props
 }) {
-  const route = router.getRoute(path);
+  const route = React__default.useMemo(() => router.getRoute(path), [router, path]);
   return /* @__PURE__ */ jsx(
     ComposedRoute,
     {
@@ -26,6 +28,42 @@ function RouteRenderer({
     }
   );
 }
+function RouteGuard({
+  permission,
+  LoadingComponent,
+  children
+}) {
+  const auth = useAuthContext();
+  const stack = useStackOrNull();
+  const { can, isPending } = useCan(permission);
+  const identity = auth?.identity ?? null;
+  const loginPath = auth?.provider.loginPath;
+  const navigate = stack?.router?.navigate;
+  const shouldRedirect = !!auth && !isPending && !can && !identity && !!loginPath;
+  useEffect(() => {
+    if (!shouldRedirect || !loginPath) return;
+    if (navigate) {
+      void navigate(loginPath);
+    } else if (typeof window !== "undefined") {
+      window.location.assign(loginPath);
+    }
+  }, [shouldRedirect, loginPath, navigate]);
+  if (!auth) {
+    return /* @__PURE__ */ jsx(Fragment, { children });
+  }
+  if (isPending || shouldRedirect) {
+    return LoadingComponent ? /* @__PURE__ */ jsx(LoadingComponent, {}) : null;
+  }
+  if (can) {
+    return /* @__PURE__ */ jsx(Fragment, { children });
+  }
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[btst/auth] RouteGuard denied: cannot ${permission.action} ${permission.resource}`
+    );
+  }
+  throw new Error("Unauthorized");
+}
 function ComposedRoute({
   path,
   PageComponent,
@@ -34,10 +72,11 @@ function ComposedRoute({
   onNotFound,
   NotFoundComponent,
   props,
-  onError
+  onError,
+  permission
 }) {
   if (PageComponent) {
-    const content = /* @__PURE__ */ jsx(PageComponent, { ...props });
+    const content = permission ? /* @__PURE__ */ jsx(RouteGuard, { permission, LoadingComponent, children: /* @__PURE__ */ jsx(PageComponent, { ...props }) }) : /* @__PURE__ */ jsx(PageComponent, { ...props });
     const suspenseFallback = LoadingComponent ? /* @__PURE__ */ jsx(LoadingComponent, {}) : null;
     if (ErrorComponent) {
       return /* @__PURE__ */ jsx(Suspense, { fallback: suspenseFallback, children: /* @__PURE__ */ jsx(

package/dist/packages/stack/src/client/hooks/use-list-state.cjs

@@ -0,0 +1,151 @@
+"use client";
+'use strict';
+
+const React = require('react');
+const provider = require('../../context/provider.cjs');
+const listState = require('../../shared/list-state.cjs');
+
+let urlVersion = 0;
+const urlListeners = /* @__PURE__ */ new Set();
+function notifyUrlChanged() {
+  urlVersion++;
+  for (const listener of urlListeners) listener();
+}
+function subscribeToUrl(listener) {
+  if (urlListeners.size === 0 && typeof window !== "undefined") {
+    window.addEventListener("popstate", notifyUrlChanged);
+  }
+  urlListeners.add(listener);
+  return () => {
+    urlListeners.delete(listener);
+    if (urlListeners.size === 0 && typeof window !== "undefined") {
+      window.removeEventListener("popstate", notifyUrlChanged);
+    }
+  };
+}
+function getUrlVersion() {
+  return urlVersion;
+}
+function getServerUrlVersion() {
+  return 0;
+}
+let pendingQueue = null;
+function searchParamsEqual(a, b) {
+  const sorted = (params) => {
+    const copy = new URLSearchParams(params.toString());
+    copy.sort();
+    return copy.toString();
+  };
+  return sorted(a) === sorted(b);
+}
+function enqueueListStateUpdate(update) {
+  if (pendingQueue) {
+    pendingQueue.push(update);
+    return;
+  }
+  pendingQueue = [update];
+  queueMicrotask(() => {
+    const queue = pendingQueue;
+    pendingQueue = null;
+    if (!queue || queue.length === 0) return;
+    const first = queue[0];
+    const currentParams = first.getSearchParams();
+    let params = currentParams;
+    let replace = true;
+    let changed = false;
+    for (const entry of queue) {
+      const prevState = listState.parseListStateFromSearchParams(
+        entry.namespace,
+        entry.schema,
+        params
+      );
+      const nextState = { ...prevState, ...entry.patch };
+      if (Object.keys(entry.schema).every(
+        (key) => Object.is(prevState[key], nextState[key])
+      )) {
+        continue;
+      }
+      changed = true;
+      params = listState.serializeListStateToSearchParams(
+        entry.namespace,
+        entry.schema,
+        nextState,
+        params
+      );
+      if (!listState.resolveListStateHistoryMode(
+        entry.schema,
+        entry.patch,
+        entry.explicitReplace
+      )) {
+        replace = false;
+      }
+    }
+    if (!changed || searchParamsEqual(params, currentParams)) return;
+    first.setSearchParams(params, { replace });
+    notifyUrlChanged();
+  });
+}
+function useListState(namespace, schema) {
+  const stack = provider.useStackOrNull();
+  const router = stack?.router;
+  const getSearchParams = router?.getSearchParams;
+  const setSearchParams = router?.setSearchParams;
+  const hasWriteBinding = !!getSearchParams && !!setSearchParams;
+  React.useSyncExternalStore(subscribeToUrl, getUrlVersion, getServerUrlVersion);
+  const urlState = listState.parseListStateFromSearchParams(
+    namespace,
+    schema,
+    getSearchParams?.() ?? new URLSearchParams()
+  );
+  const [localPatch, setLocalPatch] = React.useState({});
+  const setState = React.useCallback(
+    (updates, options) => {
+      if (!setSearchParams || !getSearchParams) {
+        setLocalPatch((prevPatch) => {
+          const urlBase = listState.parseListStateFromSearchParams(
+            namespace,
+            schema,
+            getSearchParams?.() ?? new URLSearchParams()
+          );
+          const prev = { ...urlBase, ...prevPatch };
+          const patch2 = typeof updates === "function" ? updates(prev) : updates;
+          if (!patch2 || Object.keys(patch2).length === 0) return prevPatch;
+          return { ...prevPatch, ...patch2 };
+        });
+        return;
+      }
+      let baseState = listState.parseListStateFromSearchParams(
+        namespace,
+        schema,
+        getSearchParams()
+      );
+      if (pendingQueue) {
+        for (const entry of pendingQueue) {
+          if (entry.namespace === namespace) {
+            baseState = { ...baseState, ...entry.patch };
+          }
+        }
+      }
+      const patch = typeof updates === "function" ? updates(baseState) : updates;
+      if (!patch || Object.keys(patch).length === 0) return;
+      enqueueListStateUpdate({
+        namespace,
+        schema,
+        patch: { ...patch },
+        explicitReplace: options?.replace,
+        getSearchParams,
+        setSearchParams
+      });
+    },
+    [namespace, schema, setSearchParams, getSearchParams]
+  );
+  return [
+    hasWriteBinding ? urlState : { ...urlState, ...localPatch },
+    setState
+  ];
+}
+
+exports.listStateParamKey = listState.listStateParamKey;
+exports.parseListStateFromSearchParams = listState.parseListStateFromSearchParams;
+exports.serializeListStateToSearchParams = listState.serializeListStateToSearchParams;
+exports.useListState = useListState;