@voyantjs/admin-app 0.0.0

package/README.md

@@ -0,0 +1,72 @@
+# @voyantjs/admin-app
+
+The Voyant admin application factory: the root document, router defaults,
+auth-guarded workspace shell, and router-aware navigation — the composition
+glue every Voyant admin previously copied from the template, delivered as a
+versioned package.
+
+Part of the Packaged Admin direction (`docs/architecture/packaged-admin-rfc.md`,
+Phase 1). `@voyantjs/admin` stays the primitives package (providers, layout,
+extension seam); this package owns the application-level composition on top.
+
+## What it provides
+
+- **`createAdminRouter({ routeTree })`** / **`createAdminQueryClient()`** —
+  TanStack Router + QueryClient with the Voyant defaults: intent preloading
+  with matched staleTime, scroll restoration, default not-found page, and
+  QueryClient SSR dehydrate/hydrate.
+- **`adminRootHead({ title, ... })`** / **`AdminRootShell`** /
+  **`AdminRootErrorBoundary`** — the root route internals, including the
+  pre-hydration theme/locale bootstrap script (no theme flash) and an error
+  boundary that survives outside the provider tree.
+- **`createAdminWorkspaceBeforeLoad({ getCurrentUser })`** — the auth guard,
+  in `beforeLoad` so the redirect short-circuits child loaders instead of
+  racing them.
+- **`AdminWorkspaceShell`** — bootstrap gate → per-user message overrides →
+  locale sync → workspace layout, with `AdminRouterLink` (Slot-compatible,
+  external-URL-aware) as the default nav link. Pass `destinations` (a
+  `satisfies AdminDestinationResolvers` map) to mount the semantic-destination
+  contract: packaged pages resolve `AdminDestinations` keys to hrefs via
+  `useAdminHref`/`useAdminNavigate`, and the shell routes them through the app
+  router.
+
+## Usage
+
+```tsx
+// src/router.tsx
+export const getRouter = () => createAdminRouter({ routeTree })
+
+// src/routes/__root.tsx
+export const Route = createRootRouteWithContext<AdminRouterContext>()({
+  head: () => adminRootHead({ title: "Acme Admin" }),
+  shellComponent: AdminRootShell,
+  component: RootComponent, // app-owned: mounts the app's provider stack
+  errorComponent: AdminRootErrorBoundary,
+})
+
+// src/routes/_workspace/route.tsx
+export const Route = createFileRoute("/_workspace")({
+  ssr: "data-only",
+  beforeLoad: createAdminWorkspaceBeforeLoad({ getCurrentUser }),
+  loader: ({ context }) => ({ user: context.user }),
+  pendingComponent: AdminWorkspacePendingFallback,
+  component: () => (
+    <AdminWorkspaceShell
+      user={user}
+      icons={navigationIcons}
+      extensions={(messages) => createMyAdminExtensions(messages)}
+      destinations={myAdminDestinations} // key → href resolvers, satisfies AdminDestinationResolvers
+      onSignOut={() => signOut({ redirectTo: "/sign-in" })}
+    >
+      <Outlet />
+    </AdminWorkspaceShell>
+  ),
+})
+```
+
+What stays app-owned: the provider list (which domain modules are mounted),
+extension definitions, navigation icons, branding, and the auth client.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+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/index.d.ts.map

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

@@ -0,0 +1,3 @@
+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/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/root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root.d.ts","sourceRoot":"","sources":["../src/root.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,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/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 { ThemeProvider } from "@voyantjs/admin";
+import { Button, Toaster } from "@voyantjs/ui/components";
+import { Alert, AlertDescription, AlertTitle } from "@voyantjs/ui/components/alert";
+import { Empty, EmptyContent, EmptyHeader, EmptyMedia, EmptyTitle, } from "@voyantjs/ui/components/empty";
+import { RefreshCcw } from "lucide-react";
+/**
+ * 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/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/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/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;iBAYmC,MAAM;GAK/E;AAED,wBAAgB,aAAa,4CAqB5B"}

package/dist/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 "@voyantjs/ui/components/button";
+import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, } from "@voyantjs/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/workspace.d.ts

@@ -0,0 +1,79 @@
+import { type AdminDestinationResolvers, type AdminExtension, type AdminNavLinkComponent, type AdminNavLinkProps, type AdminUser, type OperatorAdminMessages, type OperatorAdminNavigationIcons } from "@voyantjs/admin";
+import { type ReactNode } from "react";
+/**
+ * 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 template.
+ */
+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/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.tsx"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,cAAc,EAGnB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,SAAS,EAGd,KAAK,qBAAqB,EAE1B,KAAK,4BAA4B,EAGlC,MAAM,iBAAiB,CAAA;AAExB,OAAO,EAAc,KAAK,SAAS,EAAwB,MAAM,OAAO,CAAA;AAExE;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,iHAyB3B,CAAA;AAED,MAAM,WAAW,qCAAqC,CAAC,KAAK;IAC1D,sEAAsE;IACtE,cAAc,EAAE,MAAM,OAAO,CAAC,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;IACvD,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,EACpD,cAAc,EACd,UAAuB,GACxB,EAAE,qCAAqC,CAAC,KAAK,CAAC,IAC/B,cAAc;IAAE,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,KAAG,OAAO,CAAC;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,CAYtF;AAED,wBAAgB,6BAA6B,CAAC,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,2CAS1E;AAED,kEAAkE;AAClE,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,4EAA4E;AAC5E,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,uBAAuB,GAAG,SAAS,CAUlF;AAED,MAAM,WAAW,wBAAwB,CAAC,KAAK,SAAS,uBAAuB;IAC7E,IAAI,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,CAAA;IAC9B,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;OAGG;IACH,UAAU,CAAC,EACP,aAAa,CAAC,cAAc,CAAC,GAC7B,CAAC,CAAC,QAAQ,EAAE,qBAAqB,KAAK,aAAa,CAAC,cAAc,CAAC,CAAC,CAAA;IACxE,KAAK,CAAC,EAAE,4BAA4B,CAAA;IACpC,4DAA4D;IAC5D,aAAa,CAAC,EAAE,qBAAqB,CAAA;IACrC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,yBAAyB,CAAA;IACxC,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtC,6EAA6E;IAC7E,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,SAAS,CAAA;IACpC,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,uBAAuB,EAAE,EACzE,IAAI,EACJ,aAAa,EACb,UAAU,EACV,KAAK,EACL,aAA+B,EAC/B,YAAY,EACZ,SAAS,EACT,OAAmC,EACnC,QAAQ,GACT,EAAE,wBAAwB,CAAC,KAAK,CAAC,2CA6BjC"}

package/dist/workspace.js

@@ -0,0 +1,81 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Link, redirect, useRouter, useRouterState } from "@tanstack/react-router";
+import { AdminLocalePreferenceSync, AdminNavigationProvider, getOperatorAdminMessageOverridesFromUiPrefs, OperatorAdminBootstrapGate, OperatorAdminMessagesProvider, OperatorAdminWorkspaceLayout, useOperatorAdminMessages, } from "@voyantjs/admin";
+import { Loader2 } from "lucide-react";
+import { forwardRef, useCallback, useMemo } from "react";
+/**
+ * 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 template.
+ */
+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).
+    const navigateToHref = useCallback((href) => {
+        void router.navigate({ href });
+    }, [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/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@voyantjs/admin-app",
+  "version": "0.0.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./root": "./src/root.tsx",
+    "./router": "./src/router.tsx",
+    "./workspace": "./src/workspace.tsx"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "prepack": "pnpm run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/ tests/",
+    "test": "vitest run --passWithNoTests"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "@tanstack/react-router": "^1.0.0",
+    "@voyantjs/admin": "workspace:^",
+    "@voyantjs/ui": "workspace:^",
+    "lucide-react": "^0.475.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.100.11",
+    "@tanstack/react-router": "^1.170.4",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@voyantjs/admin": "workspace:^",
+    "@voyantjs/ui": "workspace:^",
+    "@voyantjs/voyant-typescript-config": "workspace:^",
+    "lucide-react": "^1.7.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      },
+      "./root": {
+        "types": "./dist/root.d.ts",
+        "import": "./dist/root.js",
+        "default": "./dist/root.js"
+      },
+      "./router": {
+        "types": "./dist/router.d.ts",
+        "import": "./dist/router.js",
+        "default": "./dist/router.js"
+      },
+      "./workspace": {
+        "types": "./dist/workspace.d.ts",
+        "import": "./dist/workspace.js",
+        "default": "./dist/workspace.js"
+      }
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voyantjs/voyant.git",
+    "directory": "packages/admin-app"
+  }
+}