@medalsocial/meda 1.3.0 → 1.5.0

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

@@ -1,17 +1,26 @@
 import type { ReactNode } from 'react';
-import type { AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig } from './types.js';
+import type { AppShellAuthBranding, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig, AppShellWorkspaceConfig } from './types.js';
 interface AppShellBaseProps {
     children: ReactNode;
     className?: string;
 }
 export type AppShellProps = AppShellBaseProps & ({
     variant: 'auth';
-    auth: AppShellAuthConfig;
+    auth?: AppShellAuthConfig;
+    branding?: AppShellAuthBranding;
+    preview?: ReactNode;
+    actions?: ReactNode;
 } | {
     variant: 'workspace';
     iconRail?: AppShellIconRailConfig;
     contextRail?: AppShellContextRailConfig;
     rightPanel?: AppShellRightPanelConfig;
+    /**
+     * Configurable workspace dropdown — replaces the package-default
+     * "Manage workspaces / Settings / Profile / Sign out" entries when
+     * `menuItems` is provided. The theme toggle is preserved automatically.
+     */
+    workspace?: AppShellWorkspaceConfig;
     globalActions?: ReactNode;
 } | {
     variant: 'chat';

package/dist/shell/app-shell.js

@@ -14,13 +14,25 @@ export function AppShell(props) {
     const wrapper = (content) => (_jsx("div", { "data-meda-app": activeAppId, "data-meda-workspace": workspace.id, "data-meda-variant": props.variant, className: cn(heightClass, 'bg-background text-foreground', props.className), children: content }));
     switch (props.variant) {
         case 'auth':
-            return wrapper(_jsx(AppShellAuth, { ...props.auth, children: props.children }));
+            return wrapper(_jsx(AppShellAuth, { ...resolveAuthConfig(props), children: props.children }));
         case 'workspace':
-            return wrapper(_jsx(AppShellWorkspace, { iconRail: props.iconRail, contextRail: props.contextRail, rightPanel: props.rightPanel, globalActions: props.globalActions, children: props.children }));
+            return wrapper(_jsx(AppShellWorkspace, { iconRail: props.iconRail, contextRail: props.contextRail, rightPanel: props.rightPanel, workspace: props.workspace, globalActions: props.globalActions, children: props.children }));
         case 'chat':
             return wrapper(_jsx(AppShellChat, { globalActions: props.globalActions, children: props.children }));
     }
 }
+function resolveAuthConfig(props) {
+    const { auth, branding } = props;
+    return {
+        title: auth?.title ?? branding?.appName ?? branding?.brandName ?? 'Sign in',
+        description: auth?.description ?? branding?.tagline,
+        brandName: auth?.brandName ?? branding?.brandName,
+        brandMark: auth?.brandMark ?? branding?.brandMark,
+        eyebrow: auth?.eyebrow,
+        preview: auth?.preview ?? props.preview,
+        actions: auth?.actions ?? props.actions,
+    };
+}
 export function AppShellBody({ children, className }) {
     return (_jsx("div", { className: cn('relative flex h-[calc(100vh-var(--shell-header-height))] overflow-hidden', className), children: children }));
 }

package/dist/shell/context-rail.js

@@ -15,7 +15,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * once <AppShellBody> ships as a ResizableShell Group.
  */
 import { PanelLeftClose, PanelLeftOpen } from 'lucide-react';
-import { useId, useRef, useState } from 'react';
+import { Fragment, useId, useRef, useState } from 'react';
 import { cn } from '../lib/utils.js';
 import { useMedaShell } from './shell-provider.js';
 import { useShellViewport } from './use-shell-viewport.js';
@@ -120,9 +120,15 @@ export function ContextRail({ appId, module, hidden = false, collapsible = true,
                                 : 'text-muted-foreground hover:bg-accent hover:text-foreground');
                             const IconComp = item.icon;
                             const inner = (_jsxs(_Fragment, { children: [_jsx(IconComp, { size: 16, "aria-hidden": "true", className: "shrink-0" }), _jsx("span", { className: "truncate", children: item.label }), item.shortcut && (_jsx("kbd", { className: "ml-auto font-mono text-[10px] text-muted-foreground", children: item.shortcut }))] }));
+                            const linkProps = {
+                                href: item.to,
+                                'aria-current': isActive ? 'page' : undefined,
+                                className: klass,
+                                children: inner,
+                            };
                             if (renderLink) {
-                                return renderLink({ item, isActive, className: klass, children: inner });
+                                return (_jsx(Fragment, { children: renderLink({ item, isActive, className: klass, children: inner, linkProps }) }, item.id));
                             }
-                            return (_jsx("a", { href: item.to, "aria-current": isActive ? 'page' : undefined, className: klass, children: inner }, item.id));
+                            return _jsx("a", { ...linkProps }, item.id);
                         }) })), module.render?.({ workspaceId: ctx.workspace.id, appId })] }), !collapsed && (_jsx(ResizeHandle, { currentWidth: width, onResize: handleResize, onCommit: handleCommit }))] }));
 }

package/dist/shell/icon-rail.d.ts

@@ -1,5 +1,5 @@
 import type { LucideIcon } from 'lucide-react';
-import type { ReactNode } from 'react';
+import type { AnchorHTMLAttributes, ReactNode } from 'react';
 export interface IconRailItem {
     id: string;
     label: string;
@@ -12,6 +12,7 @@ export interface IconRailRenderLinkArgs {
     isActive: boolean;
     className: string;
     children: ReactNode;
+    linkProps: AnchorHTMLAttributes<HTMLAnchorElement>;
 }
 export interface IconRailProps {
     mainItems: IconRailItem[];

package/dist/shell/icon-rail.js

@@ -29,9 +29,16 @@ export function IconRail({ mainItems, utilityItems = [], footer, activeId, rende
         const klass = itemClass(isActive);
         const IconComp = item.icon;
         const inner = (_jsxs(_Fragment, { children: [_jsx(IconComp, { size: 22, "aria-hidden": "true" }), item.badge ? _jsx("span", { className: "absolute right-1 top-1", children: item.badge }) : null] }));
+        const linkProps = {
+            href: item.to,
+            'aria-label': item.label,
+            'aria-current': isActive ? 'page' : undefined,
+            className: 'contents',
+            children: inner,
+        };
         const linkContent = renderLink ? (
         // renderLink consumers receive the className so they can apply it themselves
-        renderLink({ item, isActive, className: klass, children: inner })) : (_jsx("a", { href: item.to, "aria-label": item.label, "aria-current": isActive ? 'page' : undefined, className: "contents", children: inner }));
+        renderLink({ item, isActive, className: klass, children: inner, linkProps })) : (_jsx("a", { ...linkProps }));
         return (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { render: _jsx("span", { "data-testid": `icon-rail-trigger-${item.id}`, className: klass, children: linkContent }) }), _jsx(TooltipContent, { side: "right", children: item.label })] }, item.id));
     };
     return (_jsx(TooltipProvider, { children: _jsxs("nav", { "data-testid": "icon-rail", "aria-label": "Primary", className: cn('flex h-full w-[var(--shell-rail-width)] shrink-0 flex-col items-center bg-shell-rail py-3.5', className), children: [_jsx("div", { className: "flex flex-col items-center gap-1", children: mainItems.map(renderItem) }), utilityItems.length > 0 && (_jsxs(_Fragment, { children: [_jsx(RailDivider, { pinnedBottom: pinnedBottom, onToggle: () => setPinnedBottom((prev) => !prev) }), _jsx("div", { "data-testid": "utility-items-wrapper", className: cn('flex flex-col items-center gap-1', pinnedBottom && 'mt-auto'), children: utilityItems.map(renderItem) })] })), footer && (_jsx("div", { className: cn('pt-3', pinnedBottom || utilityItems.length === 0 ? 'mt-auto' : ''), children: footer }))] }) }));

package/dist/shell/index.d.ts

@@ -1,3 +1,5 @@
+export type { AuthMessageProps, AuthOneTapSlotProps, AuthProvider, AuthProviderButtonProps, AuthProviderListProps, } from '../auth/index.js';
+export { AuthError, AuthNotice, AuthOneTapSlot, AuthProviderButton, AuthProviderList, } from '../auth/index.js';
 export { AppShell, AppShellBody } from './app-shell.js';
 export type { CommandGroupDefinition } from './command-palette.js';
 export { CommandPalette, useCommandGroup, useCommands } from './command-palette.js';
@@ -5,6 +7,7 @@ export { ContextRail } from './context-rail.js';
 export type { DragModeBannerProps } from './drag-mode-banner.js';
 export { DragModeBanner } from './drag-mode-banner.js';
 export * as Extras from './extras/index.js';
+export type { IconRailItem, IconRailProps, IconRailRenderLinkArgs } from './icon-rail.js';
 export { IconRail, RailDivider } from './icon-rail.js';
 export type { ShellStorageAdapter } from './layout-state.js';
 export { createLocalStorageAdapter } from './layout-state.js';
@@ -23,5 +26,5 @@ export type { MedaShellProviderProps } from './shell-provider.js';
 export { MedaShellProvider, useMedaShell, useShellSelection } from './shell-provider.js';
 export { DefaultThemeProvider, ThemeToggle, useTheme } from './theme.js';
 export { NextThemesAdapter } from './theme-next-themes.js';
-export type { AppDefinition, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig, AppShellVariant, CommandDefinition, ContextItem, ContextModule, MobileBottomNavItem, PanelMode, PanelView, ShellLinkRenderArgs, ShellMainLayout, ShellRenderContext, ShellViewport, ThemeAdapter, WorkspaceDefinition, } from './types.js';
+export type { AppDefinition, AppShellAuthBranding, AppShellAuthConfig, AppShellContextRailConfig, AppShellIconRailConfig, AppShellRightPanelConfig, AppShellVariant, AppShellWorkspaceConfig, CommandDefinition, ContextItem, ContextModule, MobileBottomNavItem, PanelMode, PanelView, ShellLinkRenderArgs, ShellMainLayout, ShellRenderContext, ShellViewport, ThemeAdapter, WorkspaceDefinition, WorkspaceMenuItem, } from './types.js';
 export { useShellViewport } from './use-shell-viewport.js';

package/dist/shell/index.js

@@ -3,6 +3,7 @@
 // the directive (see test/nextjs-consumer.test.ts). Each underlying component
 // file carries its own 'use client' — Next traces through the barrel and
 // applies them per-component. The barrel itself is just a re-exporter.
+export { AuthError, AuthNotice, AuthOneTapSlot, AuthProviderButton, AuthProviderList, } from '../auth/index.js';
 // Layout
 export { AppShell, AppShellBody } from './app-shell.js';
 // Command palette
@@ -12,7 +13,6 @@ export { ContextRail } from './context-rail.js';
 export { DragModeBanner } from './drag-mode-banner.js';
 // Extras (legacy components ported during Phase 15 — opt-in for apps that need them)
 export * as Extras from './extras/index.js';
-// Rails + main + panel
 export { IconRail, RailDivider } from './icon-rail.js';
 // Storage adapter (consumers may want to provide their own)
 export { createLocalStorageAdapter } from './layout-state.js';

package/dist/shell/internal/mobile-drawers.js

@@ -34,15 +34,22 @@ const menuItemClassName = 'flex items-center gap-2 rounded-md px-3 py-2 text-sm
 function MenuDrawerItem({ item, isActive, onClose, renderLink, }) {
     const Icon = item.icon;
     const children = (_jsxs(_Fragment, { children: [_jsx(Icon, { size: 18, "aria-hidden": "true" }), _jsx("span", { children: item.label })] }));
+    const className = cn(menuItemClassName, isActive && 'bg-accent text-foreground');
+    const linkProps = {
+        href: item.to,
+        className,
+        children,
+    };
     if (renderLink) {
         return closeAfterLinkClick(renderLink({
             item,
             isActive,
-            className: cn(menuItemClassName, isActive && 'bg-accent text-foreground'),
+            className,
             children,
+            linkProps,
         }), onClose);
     }
-    return (_jsx("a", { href: item.to, onClick: onClose, className: menuItemClassName, children: children }));
+    return closeAfterLinkClick(_jsx("a", { ...linkProps }), onClose);
 }
 function closeAfterLinkClick(link, onClose) {
     if (!isValidElement(link)) {

package/dist/shell/primitives.d.ts

@@ -0,0 +1,9 @@
+export type { ShellStorageAdapter } from './layout-state.js';
+export { createLocalStorageAdapter } from './layout-state.js';
+export type { PanelViewsProviderProps } from './panel-views-provider.js';
+export { PanelViewsProvider } from './panel-views-provider.js';
+export { ResizableHandle, ResizableShell, ResizableShellPanel } from './resizable-shell.js';
+export type { MedaShellProviderProps } from './shell-provider.js';
+export { MedaShellProvider, useMedaShell, useShellSelection } from './shell-provider.js';
+export type { AppDefinition, CommandDefinition, ContextItem, ContextModule, MobileBottomNavItem, PanelMode, PanelView, ShellLinkRenderArgs, ShellRenderContext, ShellViewport, ThemeAdapter, WorkspaceDefinition, } from './types.js';
+export { useShellViewport } from './use-shell-viewport.js';

package/dist/shell/primitives.js

@@ -0,0 +1,7 @@
+// State and layout primitives for consumers that want Meda shell behavior
+// without importing the full styled shell barrel.
+export { createLocalStorageAdapter } from './layout-state.js';
+export { PanelViewsProvider } from './panel-views-provider.js';
+export { ResizableHandle, ResizableShell, ResizableShellPanel } from './resizable-shell.js';
+export { MedaShellProvider, useMedaShell, useShellSelection } from './shell-provider.js';
+export { useShellViewport } from './use-shell-viewport.js';

package/dist/shell/right-panel.d.ts

@@ -1,3 +1,4 @@
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
 import type { PanelMode, PanelView } from './types.js';
 export interface RightPanelProps {
     /** Views to render as tabs in the panel header. */
@@ -10,6 +11,16 @@ export interface RightPanelProps {
      * If only ['panel'], the cycle button is hidden.
      */
     modes?: PanelMode[];
+    renderTab?: (args: RightPanelTabRenderArgs) => ReactNode;
     className?: string;
 }
-export declare function RightPanel({ panelViews, defaultView, modes, className, }: RightPanelProps): import("react/jsx-runtime").JSX.Element | null;
+export interface RightPanelTabRenderArgs {
+    view: PanelView;
+    isActive: boolean;
+    buttonProps: RightPanelTabButtonProps;
+    children: ReactNode;
+}
+export type RightPanelTabButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+    'data-active'?: boolean;
+};
+export declare function RightPanel({ panelViews, defaultView, modes, renderTab, className, }: RightPanelProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/shell/right-panel.js

@@ -1,5 +1,5 @@
 'use client';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * RightPanel — spec §12
  *
@@ -16,7 +16,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * TODO(phase-15-refactor): swap to ResizableShell once AppShellBody is a PanelGroup
  */
 import { Maximize2, Minimize2, X } from 'lucide-react';
-import { useEffect, useRef, useState } from 'react';
+import { Fragment, useEffect, useRef, useState } from 'react';
 import { cn } from '../lib/utils.js';
 import { useResolvedPanelViews } from './panel-views-provider.js';
 import { useMedaShell } from './shell-provider.js';
@@ -63,7 +63,7 @@ function ResizeHandle({ currentWidth, onResize, onCommit }) {
 // ---------------------------------------------------------------------------
 // RightPanel
 // ---------------------------------------------------------------------------
-export function RightPanel({ panelViews = EMPTY_PANEL_VIEWS, defaultView, modes = ['panel', 'expanded', 'fullscreen'], className, }) {
+export function RightPanel({ panelViews = EMPTY_PANEL_VIEWS, defaultView, modes = ['panel', 'expanded', 'fullscreen'], renderTab, className, }) {
     const band = useShellViewport();
     const ctx = useMedaShell();
     const { mode, activeView, width, setMode, setActiveView, setWidth } = ctx.panel;
@@ -132,8 +132,20 @@ export function RightPanel({ panelViews = EMPTY_PANEL_VIEWS, defaultView, modes
     return (_jsx("aside", { "data-meda-panel-mode": mode, "aria-hidden": mode === 'closed' ? 'true' : undefined, className: cn('relative h-full shrink-0 overflow-hidden border-l border-shell-border bg-shell-panel', 'transition-[width] ease-[var(--motion-ease)] duration-[var(--motion-panel)]', mode === 'fullscreen' && 'fixed inset-0 h-screen w-screen border-none', zIndexClass, className), style: widthStyle, children: mode !== 'closed' && (_jsxs("div", { className: "flex h-full flex-col", children: [_jsxs("div", { className: "flex items-center justify-between border-b border-shell-border px-3 py-2", children: [_jsx("div", { className: "flex items-center gap-1", children: resolvedPanelViews.map((view) => {
                                 const isActive = view.id === activeView;
                                 const Icon = view.icon;
-                                return (_jsxs("button", { type: "button", "aria-current": isActive ? 'true' : undefined, onClick: () => setActiveView(view.id), className: cn('inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium transition-colors', isActive
+                                const children = (_jsxs(_Fragment, { children: [_jsx(Icon, { size: 14, "aria-hidden": "true" }), _jsx("span", { children: view.label })] }));
+                                const buttonProps = {
+                                    type: 'button',
+                                    'aria-current': isActive ? 'true' : undefined,
+                                    'data-active': isActive || undefined,
+                                    onClick: () => setActiveView(view.id),
+                                    className: cn('inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium transition-colors', isActive
                                         ? 'bg-accent text-accent-foreground'
-                                        : 'text-muted-foreground hover:bg-accent hover:text-foreground'), children: [_jsx(Icon, { size: 14, "aria-hidden": "true" }), _jsx("span", { children: view.label })] }, view.id));
+                                        : 'text-muted-foreground hover:bg-accent hover:text-foreground'),
+                                    children,
+                                };
+                                if (renderTab) {
+                                    return (_jsx(Fragment, { children: renderTab({ view, isActive, buttonProps, children }) }, view.id));
+                                }
+                                return _jsx("button", { ...buttonProps }, view.id);
                             }) }), _jsxs("div", { className: "flex items-center gap-1", children: [modes.length > 1 && (_jsx("button", { type: "button", "aria-label": cycleAriaLabel, onClick: cycleOpenMode, className: "inline-flex h-7 w-7 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground", children: mode === 'fullscreen' ? (_jsx(Minimize2, { size: 14, "aria-hidden": "true" })) : (_jsx(Maximize2, { size: 14, "aria-hidden": "true" })) })), _jsx("button", { type: "button", "aria-label": "Close panel", onClick: () => setMode('closed'), className: "inline-flex h-7 w-7 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground", children: _jsx(X, { size: 14, "aria-hidden": "true" }) })] })] }), _jsx("div", { className: "flex-1 overflow-y-auto", children: activePanelView != null ? (activePanelView.render(renderCtx)) : (_jsx("div", { className: "p-4 text-muted-foreground text-sm", children: "No panel view selected" })) }), mode === 'panel' && (_jsx(ResizeHandle, { currentWidth: resolvedWidth, onResize: handleResize, onCommit: handleCommit }))] })) }));
 }

package/dist/shell/shell-header.d.ts

@@ -1,12 +1,34 @@
-import type { ReactNode } from 'react';
+import { type ReactNode } from 'react';
+import type { WorkspaceMenuItem } from './types.js';
 export interface WorkspaceSwitcherProps {
+    /**
+     * Configurable dropdown items. When provided, REPLACES the default
+     * "Manage workspaces / Settings / Profile / Sign out" entries. The theme
+     * toggle is still inserted automatically by meda — between the items and
+     * the footer — so consumers don't have to reimplement theme cycling.
+     *
+     * When omitted, the package-default items render (1.x behavior).
+     */
+    menuItems?: WorkspaceMenuItem[];
+    /**
+     * Extra content rendered after all items and the theme toggle. Backwards-
+     * compatible alias for the legacy `workspaceMenuFooter` prop.
+     */
+    menuFooter?: ReactNode;
+    /** @deprecated Use `menuFooter` instead. */
     workspaceMenuFooter?: ReactNode;
 }
-export declare function WorkspaceSwitcher({ workspaceMenuFooter }?: WorkspaceSwitcherProps): import("react/jsx-runtime").JSX.Element;
+export declare function WorkspaceSwitcher({ menuItems, menuFooter, workspaceMenuFooter, }?: WorkspaceSwitcherProps): import("react/jsx-runtime").JSX.Element;
 export declare function AppTabs(): import("react/jsx-runtime").JSX.Element;
 export declare function PanelToggle(): import("react/jsx-runtime").JSX.Element;
 export interface ShellHeaderProps {
     globalActions?: ReactNode;
     className?: string;
+    /**
+     * Forwarded to the internal `<WorkspaceSwitcher>`. See
+     * `WorkspaceSwitcherProps` for the full shape.
+     */
+    workspaceMenuItems?: WorkspaceMenuItem[];
+    workspaceMenuFooter?: ReactNode;
 }
-export declare function ShellHeader({ globalActions, className }?: ShellHeaderProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ShellHeader({ globalActions, className, workspaceMenuItems, workspaceMenuFooter, }?: ShellHeaderProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/shell/shell-header.js

@@ -1,6 +1,7 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { ChevronDown, Monitor, Moon, PanelRightClose, PanelRightOpen, Sun } from 'lucide-react';
+import { createElement, Fragment, isValidElement } from 'react';
 import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, } from '../components/ui/dropdown-menu.js';
 import { cn } from '../lib/utils.js';
 import { useMedaShell } from './shell-provider.js';
@@ -18,9 +19,43 @@ function ThemeToggleMenuItem() {
     const Icon = THEME_ICON[theme];
     return (_jsxs(DropdownMenuItem, { onClick: () => setTheme(NEXT_THEME[theme]), children: [_jsx(Icon, { size: 16, "aria-hidden": "true" }), THEME_LABEL[theme]] }));
 }
-export function WorkspaceSwitcher({ workspaceMenuFooter } = {}) {
+function renderConfiguredIcon(icon) {
+    if (icon == null)
+        return null;
+    if (isValidElement(icon))
+        return icon;
+    if (typeof icon === 'function') {
+        return createElement(icon, { size: 16, 'aria-hidden': true });
+    }
+    // forwardRef/memo components are objects carrying a `$$typeof` symbol —
+    // treat them like Lucide components. Plain ReactNode objects (arrays,
+    // iterables, promises) have no `$$typeof` and are rendered as-is so they
+    // don't crash createElement with "Element type is invalid".
+    if (typeof icon === 'object' && icon !== null) {
+        const candidate = icon;
+        if (candidate.$$typeof != null) {
+            return createElement(icon, {
+                size: 16,
+                'aria-hidden': true,
+            });
+        }
+    }
+    return icon;
+}
+function renderConfiguredItem(item) {
+    const handleSelect = () => item.onClick?.();
+    // Childless anchor — Base UI merges the DropdownMenuItem's children into the
+    // cloned render element. Passing children here would override the icon +
+    // label children below and configured icons would silently disappear.
+    // biome-ignore lint/a11y/useAnchorContent: children are injected at render time by Base UI's `render` prop
+    const renderLink = item.href != null ? _jsx("a", { href: item.href }) : undefined;
+    return (_jsxs(DropdownMenuItem, { render: renderLink, "data-variant": item.variant ?? 'default', className: item.variant === 'destructive' ? 'text-destructive' : undefined, onClick: handleSelect, children: [renderConfiguredIcon(item.icon), item.label] }));
+}
+export function WorkspaceSwitcher({ menuItems, menuFooter, workspaceMenuFooter, } = {}) {
     const { workspace, workspaces } = useMedaShell();
-    return (_jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger, { render: _jsx("button", { type: "button", className: "flex items-center gap-1.5 rounded-md px-2 py-1.5 text-sm font-medium hover:bg-accent" }), children: [workspace.icon != null && (_jsx("span", { className: "shrink-0", "aria-hidden": "true", children: workspace.icon })), _jsx("span", { children: workspace.name }), _jsx(ChevronDown, { size: 14, "aria-hidden": "true" })] }), _jsxs(DropdownMenuContent, { className: "min-w-[200px]", children: [workspaces.length > 0 && (_jsxs(_Fragment, { children: [workspaces.map((ws) => (_jsxs(DropdownMenuItem, { children: [ws.icon != null && _jsx("span", { "aria-hidden": "true", children: ws.icon }), ws.name] }, ws.id))), _jsx(DropdownMenuSeparator, {})] })), _jsx(DropdownMenuItem, { children: "Manage workspaces" }), _jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { children: "Settings" }), _jsx(DropdownMenuItem, { children: "Profile" }), _jsx(DropdownMenuSeparator, {}), _jsx(ThemeToggleMenuItem, {}), _jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { children: "Sign out" }), workspaceMenuFooter] })] }));
+    const resolvedFooter = menuFooter ?? workspaceMenuFooter;
+    const useConfiguredItems = Array.isArray(menuItems);
+    return (_jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger, { render: _jsx("button", { type: "button", className: "flex items-center gap-1.5 rounded-md px-2 py-1.5 text-sm font-medium hover:bg-accent" }), children: [workspace.icon != null && (_jsx("span", { className: "shrink-0", "aria-hidden": "true", children: workspace.icon })), _jsx("span", { children: workspace.name }), _jsx(ChevronDown, { size: 14, "aria-hidden": "true" })] }), _jsxs(DropdownMenuContent, { className: "min-w-[200px]", children: [workspaces.length > 0 && (_jsxs(_Fragment, { children: [workspaces.map((ws) => (_jsxs(DropdownMenuItem, { children: [ws.icon != null && _jsx("span", { "aria-hidden": "true", children: ws.icon }), ws.name] }, ws.id))), _jsx(DropdownMenuSeparator, {})] })), useConfiguredItems ? (menuItems.map((item) => (_jsxs(Fragment, { children: [renderConfiguredItem(item), item.separatorAfter && _jsx(DropdownMenuSeparator, {})] }, item.id)))) : (_jsxs(_Fragment, { children: [_jsx(DropdownMenuItem, { children: "Manage workspaces" }), _jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { children: "Settings" }), _jsx(DropdownMenuItem, { children: "Profile" })] })), _jsx(DropdownMenuSeparator, {}), _jsx(ThemeToggleMenuItem, {}), !useConfiguredItems && (_jsxs(_Fragment, { children: [_jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { children: "Sign out" })] })), resolvedFooter] })] }));
 }
 // ---------------------------------------------------------------------------
 // AppTabs
@@ -50,9 +85,9 @@ export function PanelToggle() {
     };
     return (_jsx("button", { type: "button", "aria-label": isOpen ? 'Close right panel' : 'Open right panel', onClick: handleClick, className: cn('inline-flex h-8 w-8 items-center justify-center rounded-md transition-colors', isOpen ? 'bg-accent text-accent-foreground' : 'text-muted-foreground hover:bg-accent'), children: isOpen ? (_jsx(PanelRightClose, { size: 18, "aria-hidden": "true" })) : (_jsx(PanelRightOpen, { size: 18, "aria-hidden": "true" })) }));
 }
-export function ShellHeader({ globalActions, className } = {}) {
+export function ShellHeader({ globalActions, className, workspaceMenuItems, workspaceMenuFooter, } = {}) {
     const band = useShellViewport();
     if (band === 'mobile')
         return null;
-    return (_jsxs("header", { className: cn('flex h-[var(--shell-header-height)] w-full items-center justify-between', 'border-b border-border bg-background px-3', className), children: [_jsxs("div", { className: "flex items-center", children: [_jsx(WorkspaceSwitcher, {}), _jsx(AppTabs, {})] }), _jsxs("div", { className: "flex items-center gap-2", children: [globalActions, _jsx(PanelToggle, {})] })] }));
+    return (_jsxs("header", { className: cn('flex h-[var(--shell-header-height)] w-full items-center justify-between', 'border-b border-border bg-background px-3', className), children: [_jsxs("div", { className: "flex items-center", children: [_jsx(WorkspaceSwitcher, { menuItems: workspaceMenuItems, menuFooter: workspaceMenuFooter }), _jsx(AppTabs, {})] }), _jsxs("div", { className: "flex items-center gap-2", children: [globalActions, _jsx(PanelToggle, {})] })] }));
 }

package/dist/shell/types.d.ts

@@ -1,5 +1,5 @@
 import type { LucideIcon } from 'lucide-react';
-import type { ReactNode } from 'react';
+import type { AnchorHTMLAttributes, ReactNode } from 'react';
 export interface AppDefinition {
     id: string;
     label: string;
@@ -49,6 +49,7 @@ export interface ShellLinkRenderArgs {
     isActive: boolean;
     className: string;
     children: ReactNode;
+    linkProps: AnchorHTMLAttributes<HTMLAnchorElement>;
 }
 export interface CommandDefinition {
     id: string;
@@ -92,6 +93,44 @@ export interface AppShellRightPanelConfig {
     panelViews: PanelView[];
     defaultView?: string;
 }
+/**
+ * A single configurable item in the WorkspaceSwitcher dropdown.
+ * Either `href` (renders as a link) or `onClick` (renders as a button) MUST
+ * be provided; supplying both makes the item a button that fires `onClick`
+ * AND navigates to `href` afterwards.
+ */
+interface WorkspaceMenuItemBase {
+    id: string;
+    label: ReactNode;
+    icon?: LucideIcon | ReactNode;
+    /** Insert a `<DropdownMenuSeparator />` immediately after this item. */
+    separatorAfter?: boolean;
+    /** Visual intent — `destructive` paints with the destructive token. */
+    variant?: 'default' | 'destructive';
+}
+export type WorkspaceMenuItem = WorkspaceMenuItemBase & ({
+    href: string;
+    onClick?: () => void;
+} | {
+    onClick: () => void;
+    href?: string;
+});
+/**
+ * Workspace dropdown configuration for `<AppShell variant="workspace">`.
+ *
+ * When `menuItems` is provided, it REPLACES the package-default menu
+ * ("Manage workspaces", "Settings", "Profile", "Sign out"). The theme toggle
+ * is still inserted automatically by meda — between the items and the footer
+ * — so consumers don't have to reimplement theme cycling.
+ *
+ * When `menuItems` is omitted, the package defaults render unchanged (the
+ * existing 1.x behavior). This is fully additive and non-breaking.
+ */
+export interface AppShellWorkspaceConfig {
+    menuItems?: WorkspaceMenuItem[];
+    /** Extra slot rendered after all items and the theme toggle. */
+    menuFooter?: ReactNode;
+}
 export interface AppShellAuthConfig {
     title: ReactNode;
     description?: ReactNode;
@@ -101,3 +140,10 @@ export interface AppShellAuthConfig {
     preview?: ReactNode;
     actions?: ReactNode;
 }
+export interface AppShellAuthBranding {
+    brandName?: ReactNode;
+    brandMark?: ReactNode;
+    appName?: ReactNode;
+    tagline?: ReactNode;
+}
+export {};

package/dist/styles/theme.css

@@ -1,7 +1,27 @@
 @import "./tokens.css";
 
+/* Tell Tailwind v4 to scan meda's compiled component output so utilities
+   like `h-full`, `mt-auto`, `py-3.5`, and `bg-shell-rail` (used by IconRail,
+   AppShellWorkspace, etc.) are generated even when the consumer app doesn't
+   reference them itself. Without this, consumers see broken layout where
+   meda components rely on classes the app doesn't otherwise use. Path is
+   resolved relative to this CSS file at build time, so it points to the
+   sibling component output regardless of where the package is installed. */
+@source "../**/*.js";
+
 @custom-variant dark (&:is(.dark *, [data-theme="dark"] *));
 
+@layer base {
+  :root {
+    color-scheme: light;
+  }
+
+  .dark,
+  [data-theme="dark"] {
+    color-scheme: dark;
+  }
+}
+
 @theme inline {
   /* Color primitives — exposed as Tailwind color scales */
 

package/dist/styles/theme.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+
+// Read theme.css via Node's runtime APIs without pulling in @types/node.
+// Declared locally so the package-level tsconfig (which doesn't include
+// node typings) still typechecks cleanly under jsdom Vitest runs.
+declare const require: (id: string) => unknown;
+declare const __dirname: string;
+
+const fs = require('node:fs') as { readFileSync(p: string, enc: string): string };
+const path = require('node:path') as { join(...parts: string[]): string };
+const themeCss = fs.readFileSync(path.join(__dirname, 'theme.css'), 'utf8');
+
+describe('theme.css', () => {
+  // Tailwind v4 only generates utility classes for class names it sees in
+  // scanned files. Consumer apps don't reference every utility used by meda
+  // components (e.g. `h-full`, `mt-auto`, `py-3.5`, `bg-shell-rail` on
+  // IconRail), so without an @source directive pointing at meda's compiled
+  // dist files, those classes silently disappear and component layouts
+  // collapse — most visibly, the IconRail's utility items fail to pin to
+  // the bottom of the viewport because `mt-auto` never gets generated.
+  //
+  // The directive is resolved relative to this CSS file at build time. Since
+  // src/styles/theme.css is copied verbatim to dist/styles/theme.css by the
+  // build script, `../**/*.js` from the dist location scans every emitted
+  // component module — exactly the surface consumers import from.
+  it('declares an @source directive that scans meda component output', () => {
+    expect(themeCss).toMatch(/@source\s+["']\.\.\/\*\*\/\*\.js["']/);
+  });
+});

package/dist/theme/index.d.ts

@@ -0,0 +1 @@
+export { createMedaThemeCss, defineMedaTheme, type MedaThemeConfig, type MedaThemeDefinition, type MedaThemeMode, type MedaThemeModeConfig, type MedaThemeTokenMap, } from './theme-bridge.js';

package/dist/theme/index.js

@@ -0,0 +1 @@
+export { createMedaThemeCss, defineMedaTheme, } from './theme-bridge.js';

package/dist/theme/theme-bridge.d.ts

@@ -0,0 +1,21 @@
+export type MedaThemeMode = 'light' | 'dark';
+export type MedaThemeTokenMap = Record<string, string | undefined>;
+export interface MedaThemeModeConfig {
+    colors?: MedaThemeTokenMap;
+    fonts?: MedaThemeTokenMap;
+    tokens?: MedaThemeTokenMap;
+}
+export interface MedaThemeConfig extends MedaThemeModeConfig {
+    appId: string;
+    selector?: string;
+    light?: MedaThemeModeConfig;
+    dark?: MedaThemeModeConfig;
+}
+export interface MedaThemeDefinition {
+    appId: string;
+    selector: string;
+    light: Required<MedaThemeModeConfig>;
+    dark: Required<MedaThemeModeConfig>;
+}
+export declare function defineMedaTheme(config: MedaThemeConfig): MedaThemeDefinition;
+export declare function createMedaThemeCss(theme: MedaThemeDefinition): string;

package/dist/theme/theme-bridge.js

@@ -0,0 +1,52 @@
+const MODE_KEYS = ['colors', 'fonts', 'tokens'];
+function assertAppId(appId) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(appId)) {
+        throw new Error('Meda theme appId must contain only letters, numbers, underscores, or dashes.');
+    }
+}
+function toCssVariableName(group, key) {
+    const normalized = key.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
+    if (normalized.startsWith('--')) {
+        return normalized;
+    }
+    if (group === 'fonts') {
+        return `--font-${normalized}`;
+    }
+    return `--${normalized}`;
+}
+function mergeModeConfig(base, mode = {}) {
+    return {
+        colors: { ...base.colors, ...mode.colors },
+        fonts: { ...base.fonts, ...mode.fonts },
+        tokens: { ...base.tokens, ...mode.tokens },
+    };
+}
+export function defineMedaTheme(config) {
+    assertAppId(config.appId);
+    const base = {
+        colors: config.colors ?? {},
+        fonts: config.fonts ?? {},
+        tokens: config.tokens ?? {},
+    };
+    return {
+        appId: config.appId,
+        selector: config.selector ?? `[data-meda-app="${config.appId}"]`,
+        light: mergeModeConfig(base, config.light),
+        dark: mergeModeConfig(base, config.dark),
+    };
+}
+function entriesForMode(mode) {
+    return MODE_KEYS.flatMap((group) => Object.entries(mode[group])
+        .filter((entry) => typeof entry[1] === 'string')
+        .map(([key, value]) => [toCssVariableName(group, key), value])).sort(([left], [right]) => left.localeCompare(right));
+}
+function renderBlock(selector, entries) {
+    const declarations = entries.map(([key, value]) => `  ${key}: ${value};`).join('\n');
+    return `${selector} {\n${declarations}\n}`;
+}
+export function createMedaThemeCss(theme) {
+    const lightEntries = entriesForMode(theme.light);
+    const darkEntries = entriesForMode(theme.dark);
+    const darkSelector = `${theme.selector}.dark, ${theme.selector}[data-theme="dark"]`;
+    return [renderBlock(theme.selector, lightEntries), renderBlock(darkSelector, darkEntries)].join('\n\n');
+}