@medalsocial/meda 1.3.0 → 1.5.0

package/README.md

@@ -1,16 +1,16 @@
 # @medalsocial/meda
 
-Shared UI shell and runtime primitives — the navigation chrome, panels, tab bars, command palette, and workbench layout that power Medal's apps. Published as Apache-2.0.
+Shared UI shell and runtime primitives — the navigation chrome, panels, auth controls, recipes, theme bridges, command palette, and workbench layout that power Medal's apps. Published as Apache-2.0.
 
 ![npm](https://img.shields.io/npm/v/@medalsocial/meda)
 
 ## Install
 
 ```bash
-pnpm add @medalsocial/meda
+pnpm add @medalsocial/meda lucide-react
 ```
 
-Peer deps: `react >= 19`, `react-dom >= 19`.
+Peer deps: `react >= 19`, `react-dom >= 19`, and `lucide-react`.
 
 ## Tailwind CSS v4 setup
 
@@ -22,36 +22,81 @@ Meda ships a `styles.css` with its design tokens. Import it once in your entry s
 
 ## Usage
 
-`ShellStateProvider` stores panel/selection state in URL search params and is router-agnostic. You provide a `ShellSearchParamsAdapter` so it can read and update them however your router prefers. A minimal, in-memory adapter:
+Use `AppShell` for the styled shell surface:
 
 ```tsx
-import { useState } from 'react';
-import { ShellStateProvider, ShellFrame } from '@medalsocial/meda';
+import { AppShell, MedaShellProvider } from '@medalsocial/meda/shell';
+import { Inbox } from 'lucide-react';
 
 export function App() {
-  const [searchParams, setSearchParams] = useState(() => new URLSearchParams());
+  const workspace = { id: 'workspace', name: 'Workspace' };
+  const apps = [{ id: 'inbox', label: 'Inbox', icon: Inbox }];
 
   return (
-    <ShellStateProvider
-      adapter={{
-        searchParams,
-        setSearchParams: (updater) => setSearchParams((current) => updater(current)),
-      }}
-    >
-      <ShellFrame>{/* your app */}</ShellFrame>
-    </ShellStateProvider>
+    <MedaShellProvider workspace={workspace} apps={apps}>
+      <AppShell
+        variant="workspace"
+        iconRail={{
+          mainItems: [{ id: 'inbox', label: 'Inbox', icon: Inbox, to: '/inbox' }],
+        }}
+      >
+        {/* your app */}
+      </AppShell>
+    </MedaShellProvider>
   );
 }
 ```
 
-For a real app, wire the adapter to your router (e.g. TanStack Router's `useSearch`/`useNavigate`, React Router's `useSearchParams`) so URL changes persist state.
+For framework routing, pass a render callback and forward Meda props:
+
+```tsx
+import Link from 'next/link';
+
+<AppShell
+  variant="workspace"
+  iconRail={{
+    mainItems,
+    renderLink: ({ item, linkProps }) => <Link {...linkProps} href={item.to} prefetch />,
+  }}
+>
+  {children}
+</AppShell>;
+```
+
+For app-scoped brand tokens:
+
+```ts
+import { createMedaThemeCss, defineMedaTheme } from '@medalsocial/meda/theme';
+
+const css = createMedaThemeCss(
+  defineMedaTheme({
+    appId: 'auto',
+    colors: {
+      primary: 'var(--hb-brand-500)',
+      background: 'var(--hb-base-50)',
+    },
+    dark: {
+      colors: {
+        background: 'var(--hb-base-900)',
+      },
+    },
+  })
+);
+```
+
+Lower-level `ShellStateProvider` and layout parts remain available from `@medalsocial/meda/shell/primitives` for apps that need to own more composition.
 
 See the [demo app](./demo) for a live playground.
 
 ## Exports
 
 - `@medalsocial/meda` — curated public API (components + helpers)
-- `@medalsocial/meda/shell` — shell-only subpath
+- `@medalsocial/meda/shell` — styled shell components and hooks
+- `@medalsocial/meda/shell/primitives` — lower-level shell state and layout primitives
+- `@medalsocial/meda/auth` — provider-neutral auth controls
+- `@medalsocial/meda/auth/better-auth` — optional better-auth adapter
+- `@medalsocial/meda/recipes/next` — copyable Next.js adoption recipe metadata
+- `@medalsocial/meda/theme` — app-scoped token bridge helpers
 - `@medalsocial/meda/marketing` — marketing sections and campaign blocks
 - `@medalsocial/meda/styles.css` — design tokens + base styles
 
@@ -64,6 +109,7 @@ Prefer to copy source into your project instead of installing? The shadcn-compat
 npx shadcn add https://meda.medalsocial.com/r/meda-shell.json
 npx shadcn add https://meda.medalsocial.com/r/meda-shell-state.json
 npx shadcn add https://meda.medalsocial.com/r/meda-workbench-layout.json
+npx shadcn add https://meda.medalsocial.com/r/meda-next-app-shell.json
 ```
 
 The registry index is at `https://meda.medalsocial.com/registry.json`. Source JSON files live under [`./registry`](./registry) in this repo and are deployed as static assets via Cloudflare Workers — see `wrangler.toml` and `.github/workflows/deploy-worker.yml`.

package/dist/auth/auth-message.d.ts

@@ -0,0 +1,10 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface AuthMessageProps extends HTMLAttributes<HTMLDivElement> {
+    children?: ReactNode;
+}
+export declare function AuthError({ children, className, ...props }: AuthMessageProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function AuthNotice({ children, className, ...props }: AuthMessageProps): import("react/jsx-runtime").JSX.Element | null;
+export interface AuthOneTapSlotProps extends HTMLAttributes<HTMLDivElement> {
+    children?: ReactNode;
+}
+export declare function AuthOneTapSlot({ children, className, ...props }: AuthOneTapSlotProps): import("react/jsx-runtime").JSX.Element;

package/dist/auth/auth-message.js

@@ -0,0 +1,18 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from '../lib/utils.js';
+export function AuthError({ children, className, ...props }) {
+    if (!children) {
+        return null;
+    }
+    return (_jsx("div", { role: "alert", className: cn('rounded-md border border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive', className), ...props, children: children }));
+}
+export function AuthNotice({ children, className, ...props }) {
+    if (!children) {
+        return null;
+    }
+    return (_jsx("div", { className: cn('rounded-md border border-border bg-muted/60 px-3 py-2 text-sm text-muted-foreground', className), ...props, children: children }));
+}
+export function AuthOneTapSlot({ children, className, ...props }) {
+    return (_jsx("div", { "data-meda-auth-one-tap-slot": "", className: cn('contents', className), ...props, children: children }));
+}

package/dist/auth/auth-provider-button.d.ts

@@ -0,0 +1,14 @@
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+import { type RenderElement } from '../lib/render-element.js';
+export type AuthProvider = 'google' | (string & {});
+export interface AuthProviderButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+    provider?: AuthProvider;
+    label: ReactNode;
+    icon?: ReactNode;
+    loading?: boolean;
+    loadingLabel?: ReactNode;
+    lastUsed?: boolean;
+    lastUsedLabel?: ReactNode;
+    render?: RenderElement<ButtonHTMLAttributes<HTMLButtonElement>>;
+}
+export declare function AuthProviderButton({ provider, label, icon, loading, loadingLabel, lastUsed, lastUsedLabel, render, disabled, className, type, ...props }: AuthProviderButtonProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;

package/dist/auth/auth-provider-button.js

@@ -0,0 +1,26 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { renderElement } from '../lib/render-element.js';
+import { cn } from '../lib/utils.js';
+export function AuthProviderButton({ provider, label, icon, loading = false, loadingLabel = 'Loading...', lastUsed = false, lastUsedLabel = 'Last used', render, disabled, className, type = 'button', ...props }) {
+    const resolvedIcon = icon ?? (provider === 'google' ? _jsx(GoogleIcon, {}) : null);
+    const isDisabled = disabled || loading;
+    const children = (_jsxs(_Fragment, { children: [resolvedIcon && (_jsx("span", { className: "flex size-5 shrink-0 items-center justify-center", "aria-hidden": "true", children: resolvedIcon })), _jsx("span", { className: "min-w-0 truncate", children: loading ? loadingLabel : label }), lastUsed && !loading && (_jsx("span", { "aria-hidden": "true", className: "ml-auto shrink-0 rounded-full bg-muted px-2 py-0.5 text-[11px] font-medium text-muted-foreground", children: lastUsedLabel }))] }));
+    const buttonProps = {
+        type,
+        disabled: isDisabled,
+        'aria-busy': loading || undefined,
+        'data-provider': provider,
+        'data-last-used': lastUsed || undefined,
+        className: cn('relative inline-flex min-h-11 w-full items-center justify-center gap-3 rounded-md border border-border bg-background px-4 py-2.5 text-sm font-medium text-foreground shadow-sm transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-60', className),
+        ...props,
+        children,
+    };
+    if (render) {
+        return renderElement(render, buttonProps);
+    }
+    return _jsx("button", { ...buttonProps });
+}
+function GoogleIcon() {
+    return (_jsxs("svg", { viewBox: "0 0 24 24", className: "size-5", "aria-hidden": "true", children: [_jsx("path", { fill: "#4285F4", d: "M21.6 12.23c0-.82-.07-1.42-.22-2.05H12v3.72h5.51c-.11.92-.71 2.31-2.04 3.24l-.02.12 2.96 2.29.2.02c1.86-1.72 2.99-4.25 2.99-7.34z" }), _jsx("path", { fill: "#34A853", d: "M12 22c2.66 0 4.89-.88 6.52-2.39l-3.11-2.42c-.83.58-1.95.99-3.41.99a5.93 5.93 0 0 1-5.6-4.1l-.12.01-3.08 2.39-.04.11A9.85 9.85 0 0 0 12 22z" }), _jsx("path", { fill: "#FBBC05", d: "M6.4 14.08A6.17 6.17 0 0 1 6.07 12c0-.72.12-1.42.32-2.08l-.01-.13-3.12-2.42-.1.05A9.93 9.93 0 0 0 2.1 12c0 1.64.39 3.19 1.07 4.57l3.23-2.49z" }), _jsx("path", { fill: "#EA4335", d: "M12 5.82c1.85 0 3.1.8 3.81 1.47l2.78-2.72C16.88 2.98 14.66 2 12 2a9.85 9.85 0 0 0-8.84 5.42l3.22 2.5A5.96 5.96 0 0 1 12 5.82z" })] }));
+}

package/dist/auth/auth-provider-list.d.ts

@@ -0,0 +1,6 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+export interface AuthProviderListProps extends HTMLAttributes<HTMLUListElement> {
+    children: ReactNode;
+    label?: string;
+}
+export declare function AuthProviderList({ children, className, label, ...props }: AuthProviderListProps): import("react/jsx-runtime").JSX.Element;

package/dist/auth/auth-provider-list.js

@@ -0,0 +1,7 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Children, isValidElement } from 'react';
+import { cn } from '../lib/utils.js';
+export function AuthProviderList({ children, className, label = 'Authentication providers', ...props }) {
+    return (_jsx("ul", { "aria-label": label, className: cn('flex w-full flex-col gap-3', className), ...props, children: Children.toArray(children).map((child, index) => (_jsx("li", { className: "contents", children: child }, isValidElement(child) && child.key != null ? child.key : index))) }));
+}

package/dist/auth/better-auth.d.ts

@@ -0,0 +1,40 @@
+import { type AuthProviderButtonProps } from './auth-provider-button.js';
+export interface BetterAuthSocialArgs {
+    provider: string;
+    callbackURL?: string;
+    errorCallbackURL?: string;
+}
+export interface BetterAuthOneTapArgs {
+    callbackURL?: string;
+}
+export interface BetterAuthClientLike {
+    signIn?: {
+        social?: (args: BetterAuthSocialArgs) => Promise<unknown> | unknown;
+    };
+    oneTap?: (args: BetterAuthOneTapArgs) => Promise<unknown> | unknown;
+    getLastUsedLoginMethod?: () => Promise<string | null | undefined> | string | null | undefined;
+}
+export interface BetterAuthProviderButtonProps extends Omit<AuthProviderButtonProps, 'onClick' | 'provider'> {
+    authClient: BetterAuthClientLike;
+    provider?: string;
+    callbackURL?: string;
+    errorCallbackURL?: string;
+    onPendingChange?: (pending: boolean) => void;
+    onError?: (error: unknown) => void;
+    onSuccess?: (result: unknown) => void;
+}
+export declare function BetterAuthProviderButton({ authClient, provider, callbackURL, errorCallbackURL, onPendingChange, onError, onSuccess, loading, ...props }: BetterAuthProviderButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare function useBetterAuthLastLoginMethod(authClient: BetterAuthClientLike): string | null;
+export interface BetterAuthOneTapProps {
+    authClient: BetterAuthClientLike;
+    enabled?: boolean;
+    callbackURL?: string;
+    onError?: (error: unknown) => void;
+    onSuccess?: (result: unknown) => void;
+}
+export declare function BetterAuthOneTap({ authClient, enabled, callbackURL, onError, onSuccess, }: BetterAuthOneTapProps): null;
+export declare function createBetterAuthAdapter(authClient: BetterAuthClientLike): {
+    BetterAuthProviderButton: (props: Omit<BetterAuthProviderButtonProps, "authClient">) => import("react/jsx-runtime").JSX.Element;
+    BetterAuthOneTap: (props: Omit<BetterAuthOneTapProps, "authClient">) => import("react/jsx-runtime").JSX.Element;
+    useBetterAuthLastLoginMethod: () => string | null;
+};

package/dist/auth/better-auth.js

@@ -0,0 +1,92 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { AuthProviderButton } from './auth-provider-button.js';
+export function BetterAuthProviderButton({ authClient, provider = 'google', callbackURL, errorCallbackURL, onPendingChange, onError, onSuccess, loading, ...props }) {
+    const [internalPending, setInternalPending] = useState(false);
+    const pending = Boolean(loading || internalPending);
+    return (_jsx(AuthProviderButton, { ...props, provider: provider, loading: pending, onClick: async () => {
+            const social = authClient.signIn?.social;
+            if (!social) {
+                onError?.(new Error('better-auth social sign-in is unavailable.'));
+                return;
+            }
+            setInternalPending(true);
+            onPendingChange?.(true);
+            try {
+                const result = await social({ provider, callbackURL, errorCallbackURL });
+                onSuccess?.(result);
+            }
+            catch (error) {
+                onError?.(error);
+            }
+            finally {
+                setInternalPending(false);
+                onPendingChange?.(false);
+            }
+        } }));
+}
+export function useBetterAuthLastLoginMethod(authClient) {
+    const [method, setMethod] = useState(null);
+    useEffect(() => {
+        let active = true;
+        async function loadLastMethod() {
+            try {
+                const getter = authClient.getLastUsedLoginMethod;
+                const nextMethod = getter ? await getter() : null;
+                if (active) {
+                    setMethod(nextMethod ?? null);
+                }
+            }
+            catch {
+                if (active) {
+                    setMethod(null);
+                }
+            }
+        }
+        void loadLastMethod();
+        return () => {
+            active = false;
+        };
+    }, [authClient]);
+    return method;
+}
+export function BetterAuthOneTap({ authClient, enabled = true, callbackURL, onError, onSuccess, }) {
+    const onErrorRef = useRef(onError);
+    const onSuccessRef = useRef(onSuccess);
+    useEffect(() => {
+        onErrorRef.current = onError;
+        onSuccessRef.current = onSuccess;
+    }, [onError, onSuccess]);
+    useEffect(() => {
+        if (!enabled || !authClient.oneTap) {
+            return;
+        }
+        let active = true;
+        async function mountOneTap() {
+            try {
+                const result = await authClient.oneTap?.({ callbackURL });
+                if (active) {
+                    onSuccessRef.current?.(result);
+                }
+            }
+            catch (error) {
+                if (active) {
+                    onErrorRef.current?.(error);
+                }
+            }
+        }
+        void mountOneTap();
+        return () => {
+            active = false;
+        };
+    }, [authClient, callbackURL, enabled]);
+    return null;
+}
+export function createBetterAuthAdapter(authClient) {
+    return {
+        BetterAuthProviderButton: (props) => (_jsx(BetterAuthProviderButton, { authClient: authClient, ...props })),
+        BetterAuthOneTap: (props) => (_jsx(BetterAuthOneTap, { authClient: authClient, ...props })),
+        useBetterAuthLastLoginMethod: () => useBetterAuthLastLoginMethod(authClient),
+    };
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,6 @@
+export type { AuthMessageProps, AuthOneTapSlotProps } from './auth-message.js';
+export { AuthError, AuthNotice, AuthOneTapSlot } from './auth-message.js';
+export type { AuthProvider, AuthProviderButtonProps } from './auth-provider-button.js';
+export { AuthProviderButton } from './auth-provider-button.js';
+export type { AuthProviderListProps } from './auth-provider-list.js';
+export { AuthProviderList } from './auth-provider-list.js';

package/dist/auth/index.js

@@ -0,0 +1,3 @@
+export { AuthError, AuthNotice, AuthOneTapSlot } from './auth-message.js';
+export { AuthProviderButton } from './auth-provider-button.js';
+export { AuthProviderList } from './auth-provider-list.js';

package/dist/auth/public.d.ts

@@ -0,0 +1,6 @@
+export type { AuthMessageProps, AuthOneTapSlotProps } from './auth-message.js';
+export { AuthError, AuthNotice, AuthOneTapSlot } from './auth-message.js';
+export type { AuthProvider, AuthProviderButtonProps } from './auth-provider-button.js';
+export { AuthProviderButton } from './auth-provider-button.js';
+export type { AuthProviderListProps } from './auth-provider-list.js';
+export { AuthProviderList } from './auth-provider-list.js';

package/dist/auth/public.js

@@ -0,0 +1,3 @@
+export { AuthError, AuthNotice, AuthOneTapSlot } from './auth-message.js';
+export { AuthProviderButton } from './auth-provider-button.js';
+export { AuthProviderList } from './auth-provider-list.js';

package/dist/index.d.ts

@@ -1,6 +1,8 @@
+export * from './auth/public.js';
 export * from './brand/public.js';
 export * from './chat/public.js';
 export * from './marketing/public.js';
 export * from './panel/public.js';
 export * from './shell/index.js';
+export * from './theme/index.js';
 export * from './timeline/public.js';

package/dist/index.js

@@ -1,6 +1,8 @@
+export * from './auth/public.js';
 export * from './brand/public.js';
 export * from './chat/public.js';
 export * from './marketing/public.js';
 export * from './panel/public.js';
 export * from './shell/index.js'; // v2 surface
+export * from './theme/index.js';
 export * from './timeline/public.js';

package/dist/lib/render-element.d.ts

@@ -0,0 +1,9 @@
+import { type ReactElement, type ReactNode } from 'react';
+export type RenderElement<TProps extends {
+    className?: string;
+    children?: ReactNode;
+}> = ReactElement<Partial<TProps>>;
+export declare function renderElement<TProps extends {
+    className?: string;
+    children?: ReactNode;
+}>(render: RenderElement<TProps>, props: TProps): ReactNode;

package/dist/lib/render-element.js

@@ -0,0 +1,27 @@
+import { cloneElement, isValidElement, } from 'react';
+import { cn } from './utils.js';
+function composeEventHandlers(consumerHandler, medaHandler) {
+    if (!consumerHandler)
+        return medaHandler;
+    if (!medaHandler)
+        return consumerHandler;
+    return (event) => {
+        consumerHandler(event);
+        if (!event.defaultPrevented) {
+            medaHandler(event);
+        }
+    };
+}
+export function renderElement(render, props) {
+    if (!isValidElement(render))
+        return null;
+    const renderProps = render.props;
+    const medaProps = props;
+    return cloneElement(render, {
+        ...renderProps,
+        ...medaProps,
+        className: cn(renderProps.className, medaProps.className),
+        onClick: composeEventHandlers(renderProps.onClick, medaProps.onClick),
+        onKeyDown: composeEventHandlers(renderProps.onKeyDown, medaProps.onKeyDown),
+    });
+}

package/dist/recipes/next.d.ts

@@ -0,0 +1,49 @@
+export interface MedaRecipeFile {
+    path: string;
+    target: string;
+    type: 'registry:block' | 'registry:component' | 'registry:hook' | 'registry:lib';
+    content: string;
+}
+export interface MedaRecipe {
+    name: string;
+    title: string;
+    description: string;
+    dependencies: string[];
+    peerDependencies: string[];
+    cssVars: string[];
+    files: MedaRecipeFile[];
+    accessibility: string[];
+    composition: string[];
+}
+export declare const nextAppShellRecipe: {
+    name: string;
+    title: string;
+    description: string;
+    dependencies: string[];
+    peerDependencies: string[];
+    cssVars: string[];
+    files: {
+        path: string;
+        target: string;
+        type: "registry:block";
+        content: string;
+    }[];
+    accessibility: string[];
+    composition: string[];
+};
+export declare const nextRecipes: {
+    name: string;
+    title: string;
+    description: string;
+    dependencies: string[];
+    peerDependencies: string[];
+    cssVars: string[];
+    files: {
+        path: string;
+        target: string;
+        type: "registry:block";
+        content: string;
+    }[];
+    accessibility: string[];
+    composition: string[];
+}[];

package/dist/recipes/next.js

@@ -0,0 +1,128 @@
+export const nextAppShellRecipe = {
+    name: 'meda-next-app-shell',
+    title: 'Meda Next AppShell',
+    description: 'Copyable Next.js App Router shell adapter with next/link routing, route-owned panel views, and auth controls.',
+    dependencies: ['@medalsocial/meda', 'lucide-react'],
+    peerDependencies: ['next', 'react', 'react-dom'],
+    cssVars: ['@medalsocial/meda/styles.css'],
+    files: [
+        {
+            path: 'registry/meda/meda-next-app-shell/meda-next-app-shell.tsx',
+            target: 'components/meda/meda-next-app-shell.tsx',
+            type: 'registry:block',
+            content: `\
+'use client'
+
+import Link from 'next/link'
+import type { ComponentProps, ReactNode } from 'react'
+import {
+  AppShell,
+  AuthError,
+  AuthNotice,
+  AuthOneTapSlot,
+  AuthProviderButton,
+  AuthProviderList,
+  MedaShellProvider,
+  PanelViewsProvider,
+  type AppDefinition,
+  type IconRailItem,
+  type PanelView,
+  type WorkspaceDefinition,
+} from '@medalsocial/meda/shell'
+
+export function MedaNextWorkspaceShell({
+  workspace,
+  apps,
+  iconItems,
+  activeIconId,
+  panelViews = [],
+  defaultPanelView,
+  children,
+}: {
+  workspace: WorkspaceDefinition
+  apps: AppDefinition[]
+  iconItems: IconRailItem[]
+  activeIconId?: string
+  panelViews?: PanelView[]
+  defaultPanelView?: string
+  children: ReactNode
+}) {
+  return (
+    <MedaShellProvider workspace={workspace} apps={apps}>
+      <AppShell
+        variant="workspace"
+        iconRail={{
+          mainItems: iconItems,
+          activeId: activeIconId,
+          renderLink: ({ item, linkProps }) => (
+            <Link {...linkProps} href={item.to} prefetch />
+          ),
+        }}
+        rightPanel={{ panelViews, defaultView: defaultPanelView }}
+      >
+        <PanelViewsProvider views={panelViews} defaultView={defaultPanelView}>
+          {children}
+        </PanelViewsProvider>
+      </AppShell>
+    </MedaShellProvider>
+  )
+}
+
+export function MedaNextAuthShell({
+  brandName,
+  brandMark,
+  appName,
+  tagline,
+  preview,
+  error,
+  notice,
+  onGoogleSignIn,
+}: {
+  brandName: ReactNode
+  brandMark?: ReactNode
+  appName?: ReactNode
+  tagline?: ReactNode
+  preview?: ReactNode
+  error?: ReactNode
+  notice?: ReactNode
+  onGoogleSignIn: ComponentProps<typeof AuthProviderButton>['onClick']
+}) {
+  return (
+    <MedaShellProvider workspace={{ id: 'auth', name: 'Auth', icon: brandMark }} apps={[]}>
+      <AppShell
+        variant="auth"
+        branding={{ brandName, brandMark, appName, tagline }}
+        preview={preview}
+      >
+        <AuthProviderList>
+          <AuthProviderButton
+            provider="google"
+            label="Continue with Google"
+            onClick={onGoogleSignIn}
+          />
+        </AuthProviderList>
+        <AuthNotice>{notice}</AuthNotice>
+        <AuthError>{error}</AuthError>
+        <AuthOneTapSlot />
+      </AppShell>
+    </MedaShellProvider>
+  )
+}
+`,
+        },
+    ],
+    accessibility: [
+        'Every drawer and panel keeps its accessible name from AppShell and RightPanel.',
+        'Custom link renderers must forward all linkProps to preserve aria-current, labels, handlers, and className.',
+        'Auth provider buttons keep the visible provider affordance separate from the accessible button name.',
+        'Route-owned panel views should expose headings inside their rendered panel content.',
+        'Reduced-motion behavior remains delegated to Meda shell motion tokens.',
+    ],
+    composition: [
+        'MedaShellProvider owns workspace and app context for the copied shell adapter.',
+        'AppShell receives route-owned rightPanel views on first render to avoid delayed panel UI.',
+        'PanelViewsProvider wraps children with the same panelViews and defaultPanelView for nested route registrations.',
+        'renderLink composes Next Link by forwarding Meda linkProps before setting framework-specific props.',
+    ],
+};
+export const nextRecipes = [nextAppShellRecipe];

package/dist/shell/app-shell-workspace.d.ts

@@ -1,10 +1,11 @@
 import type { ReactNode } from 'react';
-import type { AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig } from './types.js';
+import type { AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig, AppShellWorkspaceConfig } from './types.js';
 export interface AppShellWorkspaceProps {
     iconRail?: AppShellIconRailConfig;
     contextRail?: AppShellContextRailConfig;
     rightPanel?: AppShellRightPanelConfig;
+    workspace?: AppShellWorkspaceConfig;
     globalActions?: ReactNode;
     children: ReactNode;
 }
-export declare function AppShellWorkspace({ iconRail, contextRail, rightPanel, globalActions, children, }: AppShellWorkspaceProps): import("react/jsx-runtime").JSX.Element;
+export declare function AppShellWorkspace({ iconRail, contextRail, rightPanel, workspace, globalActions, children, }: AppShellWorkspaceProps): import("react/jsx-runtime").JSX.Element;

package/dist/shell/app-shell-workspace.js

@@ -12,7 +12,7 @@ import { ShellHeader } from './shell-header.js';
 import { ShellMain } from './shell-main.js';
 import { useShellViewport } from './use-shell-viewport.js';
 const EMPTY_PANEL_VIEWS = [];
-export function AppShellWorkspace({ iconRail, contextRail, rightPanel, globalActions, children, }) {
+export function AppShellWorkspace({ iconRail, contextRail, rightPanel, workspace, globalActions, children, }) {
     const viewport = useShellViewport();
     const isMobile = viewport === 'mobile';
     const staticPanelViews = rightPanel?.panelViews ?? EMPTY_PANEL_VIEWS;
@@ -37,7 +37,7 @@ export function AppShellWorkspace({ iconRail, contextRail, rightPanel, globalAct
     // rendered without an explicit-height ancestor (tests, direct imports). The
     // <AppShell> wrapper already enforces h-screen for the workspace variant, so
     // nested viewport-height divs collapse cleanly — no double-scroll.
-    return (_jsxs("div", { className: "flex h-screen flex-col", children: [isMobile ? (_jsx(MobileHeader, { globalActions: globalActions })) : (_jsx(ShellHeader, { globalActions: globalActions })), _jsxs("div", { className: "relative flex flex-1 overflow-hidden", children: [!isMobile && iconRail && (_jsx(IconRail, { mainItems: iconRail.mainItems, utilityItems: iconRail.utilityItems, footer: iconRail.footer, activeId: iconRail.activeId, renderLink: iconRail.renderLink })), !isMobile && contextRail && (_jsx(ContextRail, { appId: contextRail.appId, module: contextRail.module, activeItemId: contextRail.activeItemId })), _jsx(ShellMain, { layout: "workspace", children: children }), !isMobile && resolvedRightPanel.panelViews.length > 0 && (_jsx(RightPanel, { panelViews: staticPanelViews, defaultView: rightPanel?.defaultView }))] }), isMobile && hasDrawerContent && _jsx(MobileBottomNav, { items: navItems }), isMobile && hasDrawerContent && (_jsx(MobileDrawers, { menuItems: mobileMenuItems, menuActiveId: iconRail?.activeId, menuRenderLink: iconRail?.renderLink, module: contextRail?.module, moduleAppId: contextRail?.appId, panelViews: resolvedRightPanel.panelViews, defaultView: resolvedRightPanel.defaultView }))] }));
+    return (_jsxs("div", { className: "flex h-screen flex-col", children: [isMobile ? (_jsx(MobileHeader, { globalActions: globalActions })) : (_jsx(ShellHeader, { globalActions: globalActions, workspaceMenuItems: workspace?.menuItems, workspaceMenuFooter: workspace?.menuFooter })), _jsxs("div", { className: "relative flex flex-1 overflow-hidden", children: [!isMobile && iconRail && (_jsx(IconRail, { mainItems: iconRail.mainItems, utilityItems: iconRail.utilityItems, footer: iconRail.footer, activeId: iconRail.activeId, renderLink: iconRail.renderLink })), !isMobile && contextRail && (_jsx(ContextRail, { appId: contextRail.appId, module: contextRail.module, activeItemId: contextRail.activeItemId })), _jsx(ShellMain, { layout: "workspace", children: children }), !isMobile && resolvedRightPanel.panelViews.length > 0 && (_jsx(RightPanel, { panelViews: staticPanelViews, defaultView: rightPanel?.defaultView }))] }), isMobile && hasDrawerContent && _jsx(MobileBottomNav, { items: navItems }), isMobile && hasDrawerContent && (_jsx(MobileDrawers, { menuItems: mobileMenuItems, menuActiveId: iconRail?.activeId, menuRenderLink: iconRail?.renderLink, module: contextRail?.module, moduleAppId: contextRail?.appId, panelViews: resolvedRightPanel.panelViews, defaultView: resolvedRightPanel.defaultView }))] }));
 }
 function buildMobileNavItems(iconRail, contextRail, panelViews) {
     const items = [];