admin-ui-starter-kit 0.1.4 → 0.4.3

package/.agents/skills/component-library-rules/references/components/layout__layout-app-shell.md

@@ -15,6 +15,7 @@ imports:
   - @/components/base/display/separator
   - @/components/base/item
   - @/components/base/sidebar
+  - @/components/composed/analytics
   - @/components/features/global-search
   - @/components/layout
   - @/components/layout/app-shell
@@ -23,6 +24,7 @@ imports:
   - @/components/layout/sidebar
   - @/components/typography
   - @/preview/_mocks
+publicImport: admin-ui-starter-kit/layout/app-shell
 tags:
   - layout
   - shells
@@ -37,8 +39,14 @@ tags:
 
 Standalone header-first shell with a 70px+ topbar and a sidebar/content body grid.
 
-**Layer:** `layout`  
+**Layer:** `layout`
 **Source:** `src/components/layout/app-shell`
+**Consumer import:** `admin-ui-starter-kit/layout/app-shell`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/layout/app-shell`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
 ## Examples
 
@@ -51,6 +59,7 @@ import { Button } from '@/components/base/buttons';
 import { SmartCard } from '@/components/base/cards';
 import { Separator } from '@/components/base/display/separator';
 import { SidebarTrigger } from '@/components/base/sidebar';
+import { MetricGrid, type MetricData } from '@/components/composed/analytics';
 import {
 	Item,
 	ItemActions,
@@ -161,8 +170,12 @@ const BADGE_VARIANT = {
 	team: 'warning',
 } as const;
 
-const HEADER_CONTROL_CLASS = 'size-[var(--app-shell-header-control-size)] rounded-lg border border-[var(--app-shell-header-border)] bg-[var(--app-shell-header-accent)] text-[var(--app-shell-header-foreground)] shadow-none hover:bg-[var(--app-shell-header-accent)] data-[state=open]:bg-[var(--app-shell-header-accent)] [&>svg]:size-4';
-const HEADER_USER_TRIGGER_CLASS = 'h-[var(--app-shell-header-control-size)] text-[var(--app-shell-header-foreground)] hover:bg-[var(--app-shell-header-accent)] data-[state=open]:bg-[var(--app-shell-header-accent)] max-md:size-[var(--app-shell-header-control-size)] max-md:justify-center max-md:p-0 max-md:[&_.header-user-menu--avatar]:size-7 max-md:[&_.header-user-menu--identity]:hidden max-md:[&_.header-user-menu--chevron]:hidden';
+const HEADER_CONTROL_CLASS = 'size-[var(--app-shell-header-control-size)] rounded-lg border border-border bg-accent text-foreground shadow-none hover:bg-accent data-[state=open]:bg-accent [&>svg]:size-4';
+const HEADER_USER_TRIGGER_CLASS = 'h-[var(--app-shell-header-control-size)] text-foreground hover:bg-accent data-[state=open]:bg-accent max-md:size-[var(--app-shell-header-control-size)] max-md:justify-center max-md:p-0 max-md:[&_.header-user-menu--avatar]:size-7 max-md:[&_.header-user-menu--identity]:hidden max-md:[&_.header-user-menu--chevron]:hidden';
+// Portalled menus from the light header render outside the header's `.light`
+// scope, so re-apply the light palette on the menu content with the scope class.
+const HEADER_LIGHT_MENU_CONTENT_CLASS = 'light !ring-border/70';
+const SHELL_PREVIEW_FRAME_CLASS = 'w-full min-w-0 max-w-[72rem] min-h-0 rounded-md border border-border shadow-sm';
 
 const queueItems = [
 	{ title: 'Stripe payout mismatch', meta: 'Payments / due 11:30' },
@@ -171,6 +184,66 @@ const queueItems = [
 	{ title: 'Supplier hold', meta: 'Inventory / split fulfillment' },
 ];
 
+const financeSignals = [
+	{
+		title: 'Payout batch',
+		meta: 'North America / 36 invoices',
+		status: 'Ready',
+		variant: 'success',
+		icon: CreditCard,
+	},
+	{
+		title: 'Tax export',
+		meta: 'EU marketplaces / Q2 review',
+		status: 'Review',
+		variant: 'warning',
+		icon: FileText,
+	},
+	{
+		title: 'Risk controls',
+		meta: 'Three orders above manual threshold',
+		status: 'Active',
+		variant: 'info',
+		icon: Shield,
+	},
+	{
+		title: 'Forecast delta',
+		meta: 'Revenue plan is 4.8% above baseline',
+		status: 'Live',
+		variant: 'secondary',
+		icon: BarChart3,
+	},
+] as const;
+
+const shellMetrics: MetricData[] = [
+	{
+		id: 'revenue',
+		label: 'Revenue',
+		value: 24820,
+		valueType: 'currency',
+		currency: 'USD',
+		change: { value: '12.4%', direction: 'up' },
+		icon: CreditCard,
+		subtitle: 'This month',
+	},
+	{
+		id: 'manual-review',
+		label: 'Manual review',
+		value: 8,
+		valueType: 'number',
+		icon: Shield,
+		subtitle: 'High-value orders',
+	},
+	{
+		id: 'ready-to-fulfill',
+		label: 'Ready to fulfill',
+		value: 36,
+		valueType: 'number',
+		icon: Package,
+		subtitle: 'Queued today',
+	},
+];
+
 function renderPreviewLink({ href, children, className, target, rel }: LayoutLinkRenderProps) {
 	return <a href={href ?? '#'} className={className} target={target} rel={rel}>{children}</a>;
 }
@@ -342,7 +415,7 @@ function HeaderLogo({
 
 	return (
 		<div className="flex min-w-0 items-center gap-3">
-			<div className="flex size-[var(--app-shell-header-control-size)] shrink-0 items-center justify-center rounded-lg bg-card text-card-foreground shadow-sm ring-1 ring-[var(--app-shell-header-border)]">
+			<div className="flex size-[var(--app-shell-header-control-size)] shrink-0 items-center justify-center rounded-lg bg-card text-card-foreground shadow-sm ring-1 ring-border">
 				<img src={logoSrc} alt="" className="size-5 object-contain" aria-hidden="true" />
 			</div>
 			<div className="hidden min-w-0 sm:block">
@@ -396,7 +469,15 @@ function SidebarColumn({
 	);
 }
 
-function HeaderEnd({ divider = false }: { divider?: boolean }) {
+function HeaderEnd({
+	divider = false,
+	menuSurface = 'dark',
+}: {
+	divider?: boolean;
+	menuSurface?: 'dark' | 'light';
+}) {
+	const menuContentClassName = menuSurface === 'light' ? HEADER_LIGHT_MENU_CONTENT_CLASS : undefined;
+
 	return (
 		<>
 			<HeaderNotifications
@@ -404,14 +485,16 @@ function HeaderEnd({ divider = false }: { divider?: boolean }) {
 				unreadCount={2}
 				renderLink={renderPreviewLink}
 				className={HEADER_CONTROL_CLASS}
+				contentClassName={menuContentClassName}
 			/>
 			{divider && (
-				<Separator orientation="vertical" className="hidden h-7 bg-[var(--app-shell-header-border)] md:block" />
+				<Separator orientation="vertical" className="hidden h-7 bg-border md:block" />
 			)}
 			<HeaderUserMenu
 				user={user}
 				showEmail={false}
 				triggerClassName={HEADER_USER_TRIGGER_CLASS}
+				contentClassName={menuContentClassName}
 				onProfile={() => {}}
 				onSettings={() => {}}
 				onLogout={() => {}}
@@ -422,19 +505,14 @@ function HeaderEnd({ divider = false }: { divider?: boolean }) {
 
 function MetricsGrid() {
 	return (
-		<div className="grid gap-3 md:grid-cols-3">
-			{[
-				['Manual review', '8', 'High-value orders'],
-				['Awaiting stock', '12', 'Split fulfillment'],
-				['Ready to fulfill', '36', 'Queued today'],
-			].map(([label, value, detail]) => (
-				<SmartCard key={label} padding="sm" className="shadow-sm">
-					<Text size="xs" type="secondary">{label}</Text>
-					<Text weight="semibold">{value}</Text>
-					<Text size="xs" type="secondary">{detail}</Text>
-				</SmartCard>
-			))}
-		</div>
+		<MetricGrid
+			metrics={shellMetrics}
+			variant="bordered"
+			size="sm"
+			columns={3}
+			gap="sm"
+			showSparklines={false}
+		/>
 	);
 }
 
@@ -465,6 +543,42 @@ function WorkQueue() {
 	);
 }
 
+function FinanceSignals() {
+	return (
+		<SmartCard padding="sm" className="shadow-sm">
+			<div className="flex items-start justify-between gap-3 border-b border-border pb-2.5">
+				<div className="min-w-0">
+					<Text weight="semibold">Settlement signals</Text>
+					<Text size="xs" type="secondary" className="mt-1">
+						Current finance checkpoints with owner-ready statuses.
+					</Text>
+				</div>
+				<Badge variant="info">4 live</Badge>
+			</div>
+			<div className="grid gap-2 pt-3 md:grid-cols-2">
+				{financeSignals.map((signal) => {
+					const Icon = signal.icon;
+
+					return (
+						<Item key={signal.title} size="sm" className="rounded-md border border-border bg-background/60 px-3 py-2.5">
+							<ItemMedia variant="icon" className="size-8 rounded-md bg-muted text-muted-foreground">
+								<Icon className="size-4" aria-hidden="true" />
+							</ItemMedia>
+							<ItemContent>
+								<ItemTitle>{signal.title}</ItemTitle>
+								<ItemDescription clamp={1}>{signal.meta}</ItemDescription>
+							</ItemContent>
+							<ItemActions>
+								<Badge variant={signal.variant}>{signal.status}</Badge>
+							</ItemActions>
+						</Item>
+					);
+				})}
+			</div>
+		</SmartCard>
+	);
+}
+
 export function DarkHeaderLeftSidebar() {
 	const search = useAppShellSearch();
 
@@ -472,7 +586,7 @@ export function DarkHeaderLeftSidebar() {
 		<SidebarProvider defaultOpen className="min-h-0">
 			<TopbarSidebarLayout
 				headerTheme="dark"
-				className="h-[44rem] min-h-0 rounded-md border border-border shadow-sm"
+				className={cn('h-[44rem]', SHELL_PREVIEW_FRAME_CLASS)}
 				sidebarTrigger={<AppShellSidebarTrigger />}
 				logo={<HeaderLogo />}
 				sidebar={<SidebarColumn currentUrl="#/orders/pending" />}
@@ -482,7 +596,7 @@ export function DarkHeaderLeftSidebar() {
 					headerEnd: <HeaderEnd divider />,
 				}}
 			>
-				<div className="space-y-5 p-5">
+				<div className="space-y-4 p-4">
 					{search.overlay}
 					<PageHeader
 						title="Pending orders"
@@ -514,16 +628,16 @@ export function LightHeaderRightSidebar() {
 				headerTheme="light"
 				sidebarSide="right"
 				sidebarWidth="18rem"
-				className="h-[38rem] min-h-0 rounded-md border border-border shadow-sm"
+				className={cn('h-[42rem]', SHELL_PREVIEW_FRAME_CLASS)}
 				sidebarTrigger={<AppShellSidebarTrigger />}
 				logo={<FullLogo />}
 				sidebar={<SidebarColumn currentUrl="#/reports" side="right" />}
 				slots={{
 					headerCenter: search.trigger,
-					headerEnd: <HeaderEnd />,
+					headerEnd: <HeaderEnd menuSurface="light" />,
 				}}
 			>
-				<div className="space-y-5 p-5">
+				<div className="space-y-4 p-4">
 					{search.overlay}
 					<PageHeader
 						title="Finance reports"
@@ -538,6 +652,7 @@ export function LightHeaderRightSidebar() {
 							Finance work stays in the content region while the right rail handles navigation.
 						</Text>
 					</SmartCard>
+					<FinanceSignals />
 				</div>
 			</TopbarSidebarLayout>
 		</SidebarProvider>