@voyant-travel/admin 0.111.0

package/dist/app/extension-routes.js

@@ -0,0 +1,134 @@
+import { createRoute, lazyRouteComponent, redirect, useNavigate, useParams, useSearch, } from "@tanstack/react-router";
+import * as React from "react";
+import { findAdminRouteContribution, requireImplementedAdminRoute, } from "../extensions.js";
+function resolveRuntime(runtime) {
+    return typeof runtime === "function" ? runtime() : runtime;
+}
+/**
+ * Wrap a lazy `page` contribution into a route component that injects route
+ * state ({@link AdminRoutePageProps}) read from the matched route. The page
+ * chunk stays code-split (the router's lazy-component machinery), and the
+ * wrapper forwards `preload` so hover/intent preloading fetches the chunk
+ * ahead of navigation.
+ */
+function createAdminRoutePageComponent(route) {
+    const page = route.page;
+    if (!page) {
+        throw new Error(`[voyant-admin] Route contribution "${route.id}" has no \`page\` loader to bind.`);
+    }
+    const LazyPage = lazyRouteComponent(page);
+    function AdminExtensionRoutePage() {
+        const params = useParams({ strict: false });
+        const search = useSearch({ strict: false });
+        const navigate = useNavigate();
+        const updateSearch = React.useCallback((updater, options) => {
+            void navigate({
+                // Same-route navigation: patch search state in place.
+                to: ".",
+                search: (prev) => updater(prev),
+                replace: options?.replace ?? true,
+            });
+        }, [navigate]);
+        return React.createElement(LazyPage, {
+            params,
+            search,
+            updateSearch,
+            title: route.title,
+        });
+    }
+    AdminExtensionRoutePage.displayName = `AdminExtensionRoutePage(${route.id})`;
+    AdminExtensionRoutePage.preload = LazyPage.preload;
+    return AdminExtensionRoutePage;
+}
+/**
+ * Resolve an extension route contribution by id and return the route
+ * options the host's generated admin route module spreads into a
+ * code-based `createRoute({...})`.
+ *
+ * Path and typed search contract stay literal in the generated module (they
+ * are what gives the host typed links); everything else — page, loader,
+ * SSR mode, boundaries — comes from the contribution.
+ */
+export function adminExtensionRouteOptions(extension, routeId, runtime) {
+    const route = requireImplementedAdminRoute(extension, routeId);
+    return adminRouteOptionsFromContribution(route, runtime);
+}
+function adminRouteOptionsFromContribution(route, runtime) {
+    const redirectTo = route.redirectTo;
+    const component = route.page
+        ? createAdminRoutePageComponent(route)
+        : route.component;
+    return {
+        component,
+        beforeLoad: redirectTo
+            ? () => {
+                throw redirect({ to: redirectTo, replace: true });
+            }
+            : undefined,
+        loader: ({ context, params }) => route.loader?.({
+            queryClient: context.queryClient,
+            runtime: resolveRuntime(runtime),
+            params,
+        }),
+        ssr: route.ssr,
+        wrapInSuspense: route.page ? true : undefined,
+        pendingComponent: route.pendingComponent,
+        errorComponent: route.errorComponent,
+    };
+}
+/**
+ * Build code-based child routes for a layout contribution's
+ * `children` that are NOT statically emitted by the host's generated
+ * module (packaged-admin RFC §4.8 + core-extension nesting).
+ *
+ * Static children keep literal paths in the generated module for typed
+ * links; dynamic children (app-supplied at factory time) bind here and are
+ * reachable via plain string navigation only.
+ */
+export function adminExtensionChildRoutes(extension, parentRouteId, getParentRoute, runtime, options = {}) {
+    const parent = findAdminRouteContribution(extension.routes, parentRouteId);
+    if (!parent) {
+        throw new Error(`[voyant-admin] Extension "${extension.id}" has no route contribution "${parentRouteId}".`);
+    }
+    const exclude = new Set(options.exclude ?? []);
+    return (parent.children ?? [])
+        .filter((child) => !exclude.has(child.path))
+        .map((child) => {
+        const options = {
+            getParentRoute,
+            path: child.path,
+            validateSearch: child.validateSearch,
+            ...adminRouteOptionsFromContribution(requireChildImplementation(extension, child), runtime),
+        };
+        // Runtime-built routes carry no typed-link contract (they are invisible
+        // to the host's generated typed-link maps), so the loose cast is sound.
+        return createRoute(options);
+    });
+}
+function requireChildImplementation(extension, child) {
+    if (!child.page && !child.component && !child.redirectTo) {
+        throw new Error(`[voyant-admin] Child route contribution "${child.id}" of extension ` +
+            `"${extension.id}" carries no implementation (neither \`page\`, \`component\`, ` +
+            `nor \`redirectTo\`).`);
+    }
+    return child;
+}
+/**
+ * Graft code-built extension routes under a file-based parent route
+ * (typically the workspace layout) and return the tree for `_addFileTypes`
+ * re-typing. Idempotent: an extension route replaces any previously grafted
+ * route with the same path, so dev-server re-evaluation of the generated
+ * module never duplicates children.
+ */
+export function attachAdminExtensionRoutes(routeTree, parentRoute, extensionRoutes) {
+    const existing = Array.isArray(parentRoute.children)
+        ? parentRoute.children
+        : [];
+    const extensionPaths = new Set(extensionRoutes.map((route) => route.options.path));
+    const children = [
+        ...existing.filter((route) => !extensionPaths.has(route.options.path)),
+        ...extensionRoutes,
+    ];
+    parentRoute.addChildren(children);
+    return routeTree;
+}

package/dist/app/index.d.ts

@@ -0,0 +1,9 @@
+export type { AdminExtensionChildRoutesOptions, AdminExtensionRouteLoaderArgs, AdminExtensionRouteOptions, AdminExtensionRouteRuntime, } from "./extension-routes.js";
+export { adminExtensionChildRoutes, adminExtensionRouteOptions, attachAdminExtensionRoutes, } from "./extension-routes.js";
+export type { AdminRootErrorBoundaryProps, AdminRootHeadOptions } from "./root.js";
+export { AdminRootErrorBoundary, AdminRootShell, adminRootHead } from "./root.js";
+export type { AdminRouterContext, CreateAdminRouterOptions } from "./router.js";
+export { AdminNotFound, createAdminQueryClient, createAdminRouter } from "./router.js";
+export type { AdminWorkspaceShellProps, AdminWorkspaceShellUser, CreateAdminWorkspaceBeforeLoadOptions, } from "./workspace.js";
+export { AdminRouterLink, AdminWorkspacePendingFallback, AdminWorkspaceShell, createAdminWorkspaceBeforeLoad, defaultAdminWorkspaceUser, } from "./workspace.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/app/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/app/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,gCAAgC,EAChC,6BAA6B,EAC7B,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EAAE,2BAA2B,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAClF,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACjF,YAAY,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAC/E,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACtF,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,qCAAqC,GACtC,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,eAAe,EACf,6BAA6B,EAC7B,mBAAmB,EACnB,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,gBAAgB,CAAA"}

package/dist/app/index.js

@@ -0,0 +1,4 @@
+export { adminExtensionChildRoutes, adminExtensionRouteOptions, attachAdminExtensionRoutes, } from "./extension-routes.js";
+export { AdminRootErrorBoundary, AdminRootShell, adminRootHead } from "./root.js";
+export { AdminNotFound, createAdminQueryClient, createAdminRouter } from "./router.js";
+export { AdminRouterLink, AdminWorkspacePendingFallback, AdminWorkspaceShell, createAdminWorkspaceBeforeLoad, defaultAdminWorkspaceUser, } from "./workspace.js";

package/dist/app/root.d.ts

@@ -0,0 +1,47 @@
+import type { ReactNode } from "react";
+export interface AdminRootHeadOptions {
+    /** Document/OG title. */
+    title: string;
+    description?: string;
+    faviconHref?: string;
+    themeColor?: string;
+    /** Extra meta tags appended after the defaults. */
+    meta?: Array<Record<string, string>>;
+    /** Extra link tags appended after the favicon. */
+    links?: Array<Record<string, string>>;
+}
+/**
+ * The root route `head()` payload for a Voyant admin app: charset/viewport,
+ * robots noindex, OG basics, favicon, and the pre-hydration theme/locale
+ * bootstrap script.
+ */
+export declare function adminRootHead(options: AdminRootHeadOptions): {
+    meta: Record<string, string>[];
+    links: Record<string, string>[];
+    scripts: {
+        children: string;
+    }[];
+};
+/**
+ * The SSR'd document shell (`shellComponent` on the root route): bare
+ * html/head/body with head content and router scripts. `suppressHydrationWarning`
+ * because the bootstrap script mutates `documentElement` before hydration.
+ */
+export declare function AdminRootShell({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export interface AdminRootErrorBoundaryProps {
+    error: unknown;
+    reset: () => void;
+    /** Fallback copy when the error has no usable message. */
+    fallbackMessage?: string;
+    homeHref?: string;
+}
+/**
+ * Root error boundary. TanStack Router's `errorComponent` replaces the root
+ * component entirely, so the app's provider tree (ThemeProvider etc.) isn't
+ * above us — mount a local ThemeProvider so <Toaster />'s useTheme() call
+ * doesn't crash the boundary.
+ */
+export declare function AdminRootErrorBoundary({ error, reset, fallbackMessage, homeHref, }: AdminRootErrorBoundaryProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=root.d.ts.map

package/dist/app/root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root.d.ts","sourceRoot":"","sources":["../../src/app/root.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,MAAM,WAAW,oBAAoB;IACnC,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mDAAmD;IACnD,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACpC,kDAAkD;IAClD,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACtC;AAUD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB;;;;;;EAkB1D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,2CAYnE;AAED,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,0DAA0D;IAC1D,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,KAAK,EACL,KAAK,EACL,eAAiE,EACjE,QAAc,GACf,EAAE,2BAA2B,2CA8B7B"}

package/dist/app/root.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { HeadContent, Scripts } from "@tanstack/react-router";
+import { Button, Toaster } from "@voyant-travel/ui/components";
+import { Alert, AlertDescription, AlertTitle } from "@voyant-travel/ui/components/alert";
+import { Empty, EmptyContent, EmptyHeader, EmptyMedia, EmptyTitle, } from "@voyant-travel/ui/components/empty";
+import { RefreshCcw } from "lucide-react";
+import { ThemeProvider } from "../providers/theme.js";
+/**
+ * Inline theme + language detection, run before hydration so the first paint
+ * doesn't flash the wrong theme or language. Load-bearing: keep in sync with
+ * the ThemeProvider storage key (`theme`) and locale storage key
+ * (`admin-locale`).
+ */
+const ADMIN_BOOTSTRAP_SCRIPT = `(function(){var t=localStorage.getItem("theme");if(t==="dark"||(!t||t==="system")&&matchMedia("(prefers-color-scheme:dark)").matches){document.documentElement.classList.add("dark")}var l=localStorage.getItem("admin-locale")||(navigator.language||"en");l=l.toLowerCase().split("-")[0];document.documentElement.lang=l==="ro"?"ro":"en"})()`;
+/**
+ * The root route `head()` payload for a Voyant admin app: charset/viewport,
+ * robots noindex, OG basics, favicon, and the pre-hydration theme/locale
+ * bootstrap script.
+ */
+export function adminRootHead(options) {
+    const { title, description, faviconHref = "/fav128.png", themeColor = "#ffffff" } = options;
+    return {
+        meta: [
+            { charSet: "utf-8" },
+            { name: "viewport", content: "width=device-width, initial-scale=1" },
+            { name: "robots", content: "noindex,nofollow" },
+            ...(description ? [{ name: "description", content: description }] : []),
+            { name: "theme-color", content: themeColor },
+            { property: "og:title", content: title },
+            { property: "og:type", content: "website" },
+            { title },
+            ...(options.meta ?? []),
+        ],
+        links: [{ rel: "icon", type: "image/png", href: faviconHref }, ...(options.links ?? [])],
+        scripts: [{ children: ADMIN_BOOTSTRAP_SCRIPT }],
+    };
+}
+/**
+ * The SSR'd document shell (`shellComponent` on the root route): bare
+ * html/head/body with head content and router scripts. `suppressHydrationWarning`
+ * because the bootstrap script mutates `documentElement` before hydration.
+ */
+export function AdminRootShell({ children }) {
+    return (_jsxs("html", { lang: "en", suppressHydrationWarning: true, children: [_jsx("head", { children: _jsx(HeadContent, {}) }), _jsxs("body", { className: "min-h-screen bg-background font-sans antialiased", suppressHydrationWarning: true, children: [children, _jsx(Scripts, {})] })] }));
+}
+/**
+ * Root error boundary. TanStack Router's `errorComponent` replaces the root
+ * component entirely, so the app's provider tree (ThemeProvider etc.) isn't
+ * above us — mount a local ThemeProvider so <Toaster />'s useTheme() call
+ * doesn't crash the boundary.
+ */
+export function AdminRootErrorBoundary({ error, reset, fallbackMessage = "Something went wrong while loading this page.", homeHref = "/", }) {
+    const message = error instanceof Error && error.message ? error.message : fallbackMessage;
+    return (_jsx(ThemeProvider, { defaultTheme: "system", storageKey: "theme", children: _jsxs("div", { className: "flex min-h-screen items-center justify-center p-6", children: [_jsxs(Empty, { className: "max-w-xl border border-border bg-card p-8", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyMedia, { variant: "icon", children: _jsx(RefreshCcw, { className: "size-5" }) }), _jsx(EmptyTitle, { children: "Something went wrong" })] }), _jsxs(EmptyContent, { children: [_jsxs(Alert, { variant: "destructive", className: "text-left", children: [_jsx(AlertTitle, { children: "Request failed" }), _jsx(AlertDescription, { children: message })] }), _jsxs("div", { className: "flex items-center gap-3", children: [_jsx(Button, { onClick: () => reset(), children: "Try again" }), _jsx(Button, { variant: "outline", onClick: () => window.location.assign(homeHref), children: "Go to dashboard" })] })] })] }), _jsx(Toaster, {})] }) }));
+}

package/dist/app/router.d.ts

@@ -0,0 +1,30 @@
+import { QueryClient } from "@tanstack/react-query";
+import { type AnyRoute } from "@tanstack/react-router";
+import type { ReactNode } from "react";
+export interface AdminRouterContext {
+    queryClient: QueryClient;
+}
+/**
+ * QueryClient with the admin defaults: no focus refetch, one retry, and a
+ * 30s staleTime that keeps hover-preloaded data fresh long enough for the
+ * hover→click navigation to reuse it. Override per-query for hotter data.
+ */
+export declare function createAdminQueryClient(): QueryClient;
+export interface CreateAdminRouterOptions<TRouteTree extends AnyRoute> {
+    routeTree: TRouteTree;
+    queryClient?: QueryClient;
+    notFoundComponent?: () => ReactNode;
+}
+/**
+ * The admin router factory: TanStack Router wired with the Voyant defaults —
+ * intent preloading with a preload staleTime matching the QueryClient (without
+ * it, hover-prefetch considers data immediately stale and re-fires the loader
+ * on click), scroll restoration, a default not-found page, and QueryClient
+ * SSR dehydrate/hydrate so loader-prefetched queries survive the
+ * server→client boundary on routes that opt into SSR.
+ */
+export declare function createAdminRouter<TRouteTree extends AnyRoute>({ routeTree, queryClient, notFoundComponent, }: CreateAdminRouterOptions<TRouteTree>): import("@tanstack/router-core").RouterCore<TRouteTree, "never", false, import("@tanstack/history").RouterHistory, {
+    queryClient: object;
+}>;
+export declare function AdminNotFound(): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=router.d.ts.map

package/dist/app/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/app/router.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA4C,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAC7F,OAAO,EAAE,KAAK,QAAQ,EAA8C,MAAM,wBAAwB,CAAA;AAWlG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,WAAW,CAAA;CACzB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,WAAW,CAUpD;AAED,MAAM,WAAW,wBAAwB,CAAC,UAAU,SAAS,QAAQ;IACnE,SAAS,EAAE,UAAU,CAAA;IACrB,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,iBAAiB,CAAC,EAAE,MAAM,SAAS,CAAA;CACpC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,SAAS,QAAQ,EAAE,EAC7D,SAAS,EACT,WAAsC,EACtC,iBAAiC,GAClC,EAAE,wBAAwB,CAAC,UAAU,CAAC;iBAYwB,MAAM;GAKpE;AAED,wBAAgB,aAAa,4CAqB5B"}

package/dist/app/router.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { dehydrate, hydrate, QueryClient } from "@tanstack/react-query";
+import { createRouter as createTanStackRouter, Link } from "@tanstack/react-router";
+import { buttonVariants } from "@voyant-travel/ui/components/button";
+import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, } from "@voyant-travel/ui/components/empty";
+import { SearchX } from "lucide-react";
+/**
+ * QueryClient with the admin defaults: no focus refetch, one retry, and a
+ * 30s staleTime that keeps hover-preloaded data fresh long enough for the
+ * hover→click navigation to reuse it. Override per-query for hotter data.
+ */
+export function createAdminQueryClient() {
+    return new QueryClient({
+        defaultOptions: {
+            queries: {
+                refetchOnWindowFocus: false,
+                retry: 1,
+                staleTime: 30_000,
+            },
+        },
+    });
+}
+/**
+ * The admin router factory: TanStack Router wired with the Voyant defaults —
+ * intent preloading with a preload staleTime matching the QueryClient (without
+ * it, hover-prefetch considers data immediately stale and re-fires the loader
+ * on click), scroll restoration, a default not-found page, and QueryClient
+ * SSR dehydrate/hydrate so loader-prefetched queries survive the
+ * server→client boundary on routes that opt into SSR.
+ */
+export function createAdminRouter({ routeTree, queryClient = createAdminQueryClient(), notFoundComponent = AdminNotFound, }) {
+    return createTanStackRouter({
+        routeTree,
+        context: { queryClient },
+        scrollRestoration: true,
+        defaultPreload: "intent",
+        defaultPreloadStaleTime: 30_000,
+        defaultNotFoundComponent: notFoundComponent,
+        // Cast around Router's ValidateSerializableInput, which is stricter than
+        // DehydratedState's recursive `unknown` slots. Runtime payload is
+        // JSON-safe; the official @tanstack/react-router-with-query helper does
+        // the same erasure.
+        dehydrate: () => ({ queryClient: dehydrate(queryClient) }),
+        hydrate: (state) => {
+            hydrate(queryClient, state.queryClient);
+        },
+    });
+}
+export function AdminNotFound() {
+    return (_jsx("div", { className: "flex min-h-screen items-center justify-center bg-background p-6", children: _jsxs(Empty, { className: "max-w-xl border border-border bg-card", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyMedia, { variant: "icon", children: _jsx(SearchX, {}) }), _jsx(EmptyTitle, { children: "Page not found" }), _jsx(EmptyDescription, { children: "The page you requested does not exist or is no longer available." })] }), _jsx(EmptyContent, { children: _jsx(Link, { to: "/", className: buttonVariants({ variant: "default" }), children: "Go to dashboard" }) })] }) }));
+}

package/dist/app/workspace.d.ts

@@ -0,0 +1,84 @@
+import { type ReactNode } from "react";
+import type { AdminNavLinkComponent, AdminNavLinkProps } from "../components/admin-nav-link.js";
+import type { AdminExtension } from "../extensions.js";
+import { type AdminDestinationResolvers } from "../navigation/destinations.js";
+import type { OperatorAdminNavigationIcons } from "../navigation/operator-navigation.js";
+import { type OperatorAdminMessages } from "../providers/operator-admin-messages.js";
+import type { AdminUser } from "../types.js";
+/**
+ * Router-aware sidebar link. SidebarMenuButton with `asChild` wraps this in a
+ * Slot, which clones the element with merged className, data attributes, and
+ * event props — extras not declared on AdminNavLinkProps but arriving at runtime, so
+ * spread the rest. Without this, Slot's className is silently dropped and
+ * sidebar items render unstyled. External URLs fall back to a plain anchor.
+ */
+export declare const AdminRouterLink: import("react").ForwardRefExoticComponent<AdminNavLinkProps & import("react").RefAttributes<HTMLAnchorElement>>;
+export interface CreateAdminWorkspaceBeforeLoadOptions<TUser> {
+    /** Resolve the current user (server fn / cookie-forwarding fetch). */
+    getCurrentUser: () => Promise<TUser | null | undefined>;
+    /** Where unauthenticated visitors are sent. Default `/sign-in`. */
+    signInPath?: string;
+}
+/**
+ * The workspace auth guard. MUST run in `beforeLoad`, not `loader`:
+ * beforeLoad executes top-down for the whole matched chain BEFORE any loader
+ * fires, so an unauthenticated redirect short-circuits the subtree. In a
+ * loader it would race child loaders whose 401s surface the root error
+ * boundary and beat the redirect, dead-ending logged-out users. Returns
+ * `{ user }`, which TanStack merges into route context.
+ */
+export declare function createAdminWorkspaceBeforeLoad<TUser>({ getCurrentUser, signInPath, }: CreateAdminWorkspaceBeforeLoadOptions<TUser>): ({ location }: {
+    location: {
+        href: string;
+    };
+}) => Promise<{
+    user: TUser;
+}>;
+export declare function AdminWorkspacePendingFallback({ label }: {
+    label?: string;
+}): import("react/jsx-runtime").JSX.Element;
+/** Structural slice of the loaded user the shell itself needs. */
+export interface AdminWorkspaceShellUser {
+    firstName?: string | null;
+    lastName?: string | null;
+    email?: string | null;
+    profilePictureUrl?: string | null;
+    locale?: string | null;
+    timeZone?: string | null;
+    timezone?: string | null;
+    uiPrefs?: unknown;
+}
+/** Default mapping from the loaded user to the layout's AdminUser shape. */
+export declare function defaultAdminWorkspaceUser(user: AdminWorkspaceShellUser): AdminUser;
+export interface AdminWorkspaceShellProps<TUser extends AdminWorkspaceShellUser> {
+    user: TUser | null | undefined;
+    isUserLoading?: boolean;
+    /**
+     * Admin extensions for the navigation/widget seam. Pass a function to
+     * derive nav labels from the resolved admin messages.
+     */
+    extensions?: ReadonlyArray<AdminExtension> | ((messages: OperatorAdminMessages) => ReadonlyArray<AdminExtension>);
+    icons?: OperatorAdminNavigationIcons;
+    /** Defaults to the router-aware {@link AdminRouterLink}. */
+    linkComponent?: AdminNavLinkComponent;
+    /**
+     * Host resolver map for the semantic-destination contract (packaged-admin
+     * RFC §4.7): one `params → href` resolver per `AdminDestinations` key the
+     * mounted packages declare. When provided, the shell mounts an
+     * `AdminNavigationProvider` wired to the app router, so packaged pages can
+     * navigate to routes they don't own via `useAdminHref`/`useAdminNavigate`.
+     */
+    destinations?: AdminDestinationResolvers;
+    onSignOut?: () => void | Promise<void>;
+    /** Maps the loaded user for the layout; default covers the common fields. */
+    mapUser?: (user: TUser) => AdminUser;
+    children: ReactNode;
+}
+/**
+ * The authenticated workspace shell: bootstrap gate (current-user readiness
+ * is the only shell dependency), per-user message overrides, locale
+ * preference sync, and the workspace layout with router-aware links — the
+ * composition every Voyant admin previously copied from the starter.
+ */
+export declare function AdminWorkspaceShell<TUser extends AdminWorkspaceShellUser>({ user, isUserLoading, extensions, icons, linkComponent, destinations, onSignOut, mapUser, children, }: AdminWorkspaceShellProps<TUser>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/app/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/app/workspace.tsx"],"names":[],"mappings":"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"}

package/dist/app/workspace.js

@@ -0,0 +1,87 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Link, redirect, useRouter, useRouterState } from "@tanstack/react-router";
+import { Loader2 } from "lucide-react";
+import { forwardRef, useCallback, useMemo } from "react";
+import { OperatorAdminBootstrapGate } from "../components/operator-admin-bootstrap-gate.js";
+import { OperatorAdminWorkspaceLayout } from "../components/operator-admin-sidebar.js";
+import { AdminNavigationProvider, } from "../navigation/destinations.js";
+import { AdminLocalePreferenceSync } from "../providers/locale-preferences.js";
+import { getOperatorAdminMessageOverridesFromUiPrefs, OperatorAdminMessagesProvider, useOperatorAdminMessages, } from "../providers/operator-admin-messages.js";
+/**
+ * Router-aware sidebar link. SidebarMenuButton with `asChild` wraps this in a
+ * Slot, which clones the element with merged className, data attributes, and
+ * event props — extras not declared on AdminNavLinkProps but arriving at runtime, so
+ * spread the rest. Without this, Slot's className is silently dropped and
+ * sidebar items render unstyled. External URLs fall back to a plain anchor.
+ */
+export const AdminRouterLink = forwardRef(function AdminRouterLink({ children, href, onClick, target, ...rest }, ref) {
+    const external = href.startsWith("http://") || href.startsWith("https://");
+    if (external) {
+        return (_jsx("a", { ref: ref, href: href, target: target, rel: target === "_blank" ? "noopener noreferrer" : undefined, onClick: onClick, ...rest, children: children }));
+    }
+    return (_jsx(Link, { ref: ref, to: href, target: target, onClick: onClick, ...rest, children: children }));
+});
+/**
+ * The workspace auth guard. MUST run in `beforeLoad`, not `loader`:
+ * beforeLoad executes top-down for the whole matched chain BEFORE any loader
+ * fires, so an unauthenticated redirect short-circuits the subtree. In a
+ * loader it would race child loaders whose 401s surface the root error
+ * boundary and beat the redirect, dead-ending logged-out users. Returns
+ * `{ user }`, which TanStack merges into route context.
+ */
+export function createAdminWorkspaceBeforeLoad({ getCurrentUser, signInPath = "/sign-in", }) {
+    return async ({ location }) => {
+        const user = await getCurrentUser();
+        if (!user) {
+            throw redirect({
+                to: signInPath,
+                search: { next: location.href },
+            });
+        }
+        return { user };
+    };
+}
+export function AdminWorkspacePendingFallback({ label }) {
+    return (_jsx("div", { className: "flex min-h-screen items-center justify-center bg-background", children: _jsxs("div", { className: "flex flex-col items-center gap-4", children: [_jsx(Loader2, { className: "size-8 animate-spin text-muted-foreground" }), label ? _jsx("p", { className: "text-sm text-muted-foreground", children: label }) : null] }) }));
+}
+/** Default mapping from the loaded user to the layout's AdminUser shape. */
+export function defaultAdminWorkspaceUser(user) {
+    return {
+        name: [user.firstName, user.lastName].filter(Boolean).join(" "),
+        firstName: user.firstName,
+        lastName: user.lastName,
+        email: user.email ?? "",
+        avatar: user.profilePictureUrl,
+        locale: user.locale,
+        timeZone: user.timeZone ?? user.timezone,
+    };
+}
+/**
+ * The authenticated workspace shell: bootstrap gate (current-user readiness
+ * is the only shell dependency), per-user message overrides, locale
+ * preference sync, and the workspace layout with router-aware links — the
+ * composition every Voyant admin previously copied from the starter.
+ */
+export function AdminWorkspaceShell({ user, isUserLoading, extensions, icons, linkComponent = AdminRouterLink, destinations, onSignOut, mapUser = defaultAdminWorkspaceUser, children, }) {
+    const messages = useOperatorAdminMessages();
+    return (_jsx(OperatorAdminBootstrapGate, { user: user, isUserLoading: isUserLoading, loadingFallback: _jsx(AdminWorkspacePendingFallback, { label: messages.loading }), children: ({ user: loadedUser }) => (_jsxs(OperatorAdminMessagesProvider, { overrides: getOperatorAdminMessageOverridesFromUiPrefs(loadedUser.uiPrefs), children: [_jsx(AdminLocalePreferenceSync, { source: loadedUser }), _jsx(AdminWorkspaceShellInner, { user: loadedUser, extensions: extensions, icons: icons, linkComponent: linkComponent, destinations: destinations, onSignOut: onSignOut, mapUser: mapUser, children: children })] })) }));
+}
+function AdminWorkspaceShellInner({ user, extensions, icons, linkComponent, destinations, onSignOut, mapUser, children, }) {
+    const router = useRouter();
+    const currentPath = useRouterState({ select: (s) => s.location.pathname });
+    const messages = useOperatorAdminMessages();
+    const resolvedExtensions = useMemo(() => (typeof extensions === "function" ? extensions(messages) : extensions), [extensions, messages]);
+    // Resolver-built hrefs may carry a query string, so navigate by `href`
+    // (which parses it back into search params) rather than `to` (which would
+    // treat the whole string as a literal pathname). `replace` forwards so
+    // packaged redirect pages (alias routes, deep-link forwards) keep
+    // route-redirect history semantics.
+    const navigateToHref = useCallback((href, options) => {
+        void router.navigate({ href, replace: options?.replace });
+    }, [router]);
+    const layout = (_jsx(OperatorAdminWorkspaceLayout, { currentPath: currentPath, extensions: resolvedExtensions, icons: icons, linkComponent: linkComponent, onSignOut: onSignOut, user: mapUser(user), children: children }));
+    if (!destinations) {
+        return layout;
+    }
+    return (_jsx(AdminNavigationProvider, { resolvers: destinations, navigate: navigateToHref, children: layout }));
+}

package/dist/components/admin-breadcrumbs.d.ts

@@ -0,0 +1,18 @@
+import type * as React from "react";
+import { type AdminNavLinkComponent } from "./admin-nav-link.js";
+export interface AdminBreadcrumbSegment {
+    label: string;
+    href?: string;
+}
+export interface AdminBreadcrumbsProviderProps {
+    children: React.ReactNode;
+}
+export declare function AdminBreadcrumbsProvider({ children }: AdminBreadcrumbsProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useAdminBreadcrumbs(segments: ReadonlyArray<AdminBreadcrumbSegment>): void;
+export declare function useAdminBreadcrumbsValue(): ReadonlyArray<AdminBreadcrumbSegment>;
+export interface AdminBreadcrumbsTrailProps {
+    linkComponent?: AdminNavLinkComponent;
+    segments: ReadonlyArray<AdminBreadcrumbSegment>;
+}
+export declare function AdminBreadcrumbsTrail({ linkComponent: LinkComponent, segments, }: AdminBreadcrumbsTrailProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=admin-breadcrumbs.d.ts.map

package/dist/components/admin-breadcrumbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-breadcrumbs.d.ts","sourceRoot":"","sources":["../../src/components/admin-breadcrumbs.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAA;AAanC,OAAO,EAAE,KAAK,qBAAqB,EAAuB,MAAM,qBAAqB,CAAA;AAErF,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AASD,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAED,wBAAgB,wBAAwB,CAAC,EAAE,QAAQ,EAAE,EAAE,6BAA6B,2CAyCnF;AAUD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,CAAC,sBAAsB,CAAC,QAwBlF;AAED,wBAAgB,wBAAwB,IAAI,aAAa,CAAC,sBAAsB,CAAC,CAEhF;AAED,MAAM,WAAW,0BAA0B;IACzC,aAAa,CAAC,EAAE,qBAAqB,CAAA;IACrC,QAAQ,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAA;CAChD;AAED,wBAAgB,qBAAqB,CAAC,EACpC,aAAa,EAAE,aAAmC,EAClD,QAAQ,GACT,EAAE,0BAA0B,kDA+B5B"}

package/dist/components/admin-breadcrumbs.js

@@ -0,0 +1,84 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, } from "@voyant-travel/ui/components";
+import { createContext, Fragment, useCallback, useContext, useEffect, useId, useMemo, useRef, useState, } from "react";
+import { DefaultAdminNavLink } from "./admin-nav-link.js";
+const AdminBreadcrumbsContext = createContext(null);
+export function AdminBreadcrumbsProvider({ children }) {
+    const [overrides, setOverrides] = useState(() => new Map());
+    const segments = useMemo(() => Array.from(overrides.values()).at(-1) ?? [], [overrides]);
+    // Stable `setSegments` reference — the function reads / writes through
+    // the state setter only, so it never needs to capture `segments`. With
+    // a stable setter and content-hash short-circuit, consumer effects
+    // that depend on `context.setSegments` don't fire in a loop just
+    // because some other consumer pushed segments.
+    const setSegments = useCallback((id, next) => {
+        setOverrides((current) => {
+            const existing = current.get(id);
+            const desired = next && next.length > 0 ? next : undefined;
+            // Short-circuit: if the entry is already structurally identical
+            // (same content hash) — or already absent — leave the map
+            // untouched so React skips the re-render that would otherwise
+            // re-trigger every consumer's effect.
+            if (!desired && !existing)
+                return current;
+            if (desired &&
+                existing &&
+                existing.length === desired.length &&
+                serializeSegments(existing) === serializeSegments(desired)) {
+                return current;
+            }
+            const merged = new Map(current);
+            if (desired)
+                merged.set(id, desired);
+            else
+                merged.delete(id);
+            return merged;
+        });
+    }, []);
+    const context = useMemo(() => ({ segments, setSegments }), [segments, setSegments]);
+    return (_jsx(AdminBreadcrumbsContext.Provider, { value: context, children: children }));
+}
+function serializeSegments(segments) {
+    let out = "";
+    for (const s of segments) {
+        out += `${s.label}|${s.href ?? ""}\n`;
+    }
+    return out;
+}
+export function useAdminBreadcrumbs(segments) {
+    const context = useContext(AdminBreadcrumbsContext);
+    const id = useId();
+    // Hold the latest segments in a ref so the effect can read them without
+    // depending on array identity — callers can pass a fresh array each render.
+    const segmentsRef = useRef(segments);
+    segmentsRef.current = segments;
+    const key = serializeSegments(segments);
+    // Hold the context in a ref too so we don't have to put it in the
+    // effect's deps. The provider's `setSegments` is stable, but `context`
+    // itself re-allocates when `segments` (a different field on the same
+    // context) changes — which would otherwise re-fire this effect on
+    // every push from any consumer and cascade into an infinite loop.
+    const contextRef = useRef(context);
+    contextRef.current = context;
+    // biome-ignore lint/correctness/useExhaustiveDependencies: intentional content gate via `key`; context read via ref so it doesn't re-fire the effect
+    useEffect(() => {
+        const ctx = contextRef.current;
+        if (!ctx)
+            return;
+        const snapshot = segmentsRef.current.map((s) => ({ label: s.label, href: s.href }));
+        ctx.setSegments(id, snapshot);
+        return () => ctx.setSegments(id, null);
+    }, [id, key]);
+}
+export function useAdminBreadcrumbsValue() {
+    return useContext(AdminBreadcrumbsContext)?.segments ?? [];
+}
+export function AdminBreadcrumbsTrail({ linkComponent: LinkComponent = DefaultAdminNavLink, segments, }) {
+    if (segments.length === 0)
+        return null;
+    return (_jsx(Breadcrumb, { children: _jsx(BreadcrumbList, { children: segments.map((segment, index) => {
+                const isLast = index === segments.length - 1;
+                return (_jsxs(Fragment, { children: [_jsx(BreadcrumbItem, { children: isLast || !segment.href ? (_jsx(BreadcrumbPage, { children: segment.label })) : (_jsx(BreadcrumbLink, { render: _jsx(LinkComponent, { href: segment.href, target: "_self", children: segment.label }) })) }), !isLast && _jsx(BreadcrumbSeparator, {})] }, `${index}-${segment.label}`));
+            }) }) }));
+}