admin-ui-starter-kit 0.5.0 → 0.6.1

package/.agents/skills/component-library-rules/references/components/base__display.md

@@ -1,627 +0,0 @@
----
-id: base/display
-title: "Display"
-description: "The display layer — Avatar, IconBadge, InlineStat, Tooltip, Separator, NotificationBanner, BooleanIndicator, ShowIf, ThrottleAlert, VisuallyHidden, PlaceholderPattern."
-layer: base
-family: "Display"
-sourcePath: src/components/base/display
-examples:
-  - NotificationBannerVariants
-  - AvatarSizes
-  - StackedAvatarsExample
-  - IconBadgeTones
-  - IconBadgeShapes
-  - IconBadgeSizes
-  - InlineStatLayouts
-  - SeparatorExample
-  - TooltipExample
-  - BooleanIndicatorExample
-  - ShowIfExample
-  - ThrottleAlertExample
-  - VisuallyHiddenExample
-  - PlaceholderPatternExample
-  - AlertExample
-  - ProgressExample
-  - SkeletonExample
-  - CollapsibleExample
-  - DialogExample
-  - DateBlockExample
-  - MoneyDisplayExample
-  - QRCodeExample
-  - RealisticUserCard
-imports:
-  - @/components/base/badge
-  - @/components/base/buttons
-  - @/components/base/display/alert
-  - @/components/base/display/avatar
-  - @/components/base/display/boolean-indicator
-  - @/components/base/display/collapsible
-  - @/components/base/display/date-block
-  - @/components/base/display/dialog
-  - @/components/base/display/icon-badge
-  - @/components/base/display/inline-stat
-  - @/components/base/display/money-display
-  - @/components/base/display/notification-banner
-  - @/components/base/display/placeholder-pattern
-  - @/components/base/display/progress
-  - @/components/base/display/qr-code
-  - @/components/base/display/separator
-  - @/components/base/display/show-if
-  - @/components/base/display/skeleton
-  - @/components/base/display/stacked-avatars
-  - @/components/base/display/throttle-alert
-  - @/components/base/display/tooltip
-  - @/components/base/display/visually-hidden
-  - @/components/base/item
-  - @/components/typography/text
-  - @/preview/_mocks
-publicImport: admin-ui-starter-kit/base/display
-tags:
-  - base
-  - display
-  - layer
-  - avatar
-  - iconbadge
-  - inlinestat
----
-
-# Display
-
-The display layer — Avatar, IconBadge, InlineStat, Tooltip, Separator, NotificationBanner, BooleanIndicator, ShowIf, ThrottleAlert, VisuallyHidden, PlaceholderPattern.
-
-**Layer:** `base`
-**Source:** `src/components/base/display`
-**Consumer import:** `admin-ui-starter-kit/base/display`
-
-## Consumer import
-
-Consumers import this surface from `admin-ui-starter-kit/base/display`.
-The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
-
-## Overview
-
-The `display/` folder collects every "show this small thing" primitive — from
-re-exports of shadcn (`Avatar`, `Separator`, `Tooltip`) to custom presentational
-helpers (`IconBadge`, `InlineStat`, `BooleanIndicator`, `NotificationBanner`,
-`StackedAvatars`, `PlaceholderPattern`). Each is intentionally narrow.
-
-## Realistic usage
-
-<Example name="RealisticUserCard" source={examplesSource}>
-	<Examples.RealisticUserCard />
-</Example>
-
-## Avatar & StackedAvatars
-
-<Example name="AvatarSizes" source={examplesSource}>
-	<Examples.AvatarSizes />
-</Example>
-
-<Example name="StackedAvatarsExample" source={examplesSource}>
-	<Examples.StackedAvatarsExample />
-</Example>
-
-## IconBadge
-
-<Example name="IconBadgeTones" source={examplesSource}>
-	<Examples.IconBadgeTones />
-</Example>
-
-<Example name="IconBadgeShapes" source={examplesSource}>
-	<Examples.IconBadgeShapes />
-</Example>
-
-<Example name="IconBadgeSizes" source={examplesSource}>
-	<Examples.IconBadgeSizes />
-</Example>
-
-## InlineStat
-
-<Example name="InlineStatLayouts" source={examplesSource}>
-	<Examples.InlineStatLayouts />
-</Example>
-
-## Separator & Tooltip
-
-<Example name="SeparatorExample" source={examplesSource}>
-	<Examples.SeparatorExample />
-</Example>
-
-<Example name="TooltipExample" source={examplesSource}>
-	<Examples.TooltipExample />
-</Example>
-
-## NotificationBanner
-
-<Example name="NotificationBannerVariants" source={examplesSource}>
-	<Examples.NotificationBannerVariants />
-</Example>
-
-## Boolean & conditionals
-
-<Example name="BooleanIndicatorExample" source={examplesSource}>
-	<Examples.BooleanIndicatorExample />
-</Example>
-
-<Example name="ShowIfExample" source={examplesSource}>
-	<Examples.ShowIfExample />
-</Example>
-
-## Misc
-
-<Example name="ThrottleAlertExample" source={examplesSource}>
-	<Examples.ThrottleAlertExample />
-</Example>
-
-<Example name="VisuallyHiddenExample" source={examplesSource}>
-	<Examples.VisuallyHiddenExample />
-</Example>
-
-<Example name="PlaceholderPatternExample" source={examplesSource}>
-	<Examples.PlaceholderPatternExample />
-</Example>
-
-## Alert
-
-<Example name="AlertExample" source={examplesSource}>
-	<Examples.AlertExample />
-</Example>
-
-## Progress & Skeleton
-
-<Example name="ProgressExample" source={examplesSource}>
-	<Examples.ProgressExample />
-</Example>
-
-<Example name="SkeletonExample" source={examplesSource}>
-	<Examples.SkeletonExample />
-</Example>
-
-## Collapsible & Dialog
-
-<Example name="CollapsibleExample" source={examplesSource}>
-	<Examples.CollapsibleExample />
-</Example>
-
-<Example name="DialogExample" source={examplesSource}>
-	<Examples.DialogExample />
-</Example>
-
-## DateBlock
-
-<Example name="DateBlockExample" source={examplesSource}>
-	<Examples.DateBlockExample />
-</Example>
-
-## MoneyDisplay
-
-<Example name="MoneyDisplayExample" source={examplesSource}>
-	<Examples.MoneyDisplayExample />
-</Example>
-
-## QRCode
-
-<Example name="QRCodeExample" source={examplesSource}>
-	<Examples.QRCodeExample />
-</Example>
-
-## Examples
-
-```tsx
-import { useState } from 'react';
-import { AlertTriangle, Bell, CheckCircle2, ChevronDown, Sparkles, Terminal, User } from 'lucide-react';
-import { Badge } from '@/components/base/badge';
-import { Avatar, AvatarFallback, AvatarImage } from '@/components/base/display/avatar';
-import { BooleanIndicator } from '@/components/base/display/boolean-indicator';
-import { IconBadge } from '@/components/base/display/icon-badge';
-import { InlineStat } from '@/components/base/display/inline-stat';
-import { NotificationBanner } from '@/components/base/display/notification-banner';
-import { PlaceholderPattern } from '@/components/base/display/placeholder-pattern';
-import { Separator } from '@/components/base/display/separator';
-import { ShowIf } from '@/components/base/display/show-if';
-import { StackedAvatars } from '@/components/base/display/stacked-avatars';
-import { ThrottleAlert } from '@/components/base/display/throttle-alert';
-import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/base/display/tooltip';
-import { VisuallyHidden } from '@/components/base/display/visually-hidden';
-import { Alert, AlertTitle, AlertDescription } from '@/components/base/display/alert';
-import { Progress } from '@/components/base/display/progress';
-import { Skeleton } from '@/components/base/display/skeleton';
-import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/base/display/collapsible';
-import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from '@/components/base/display/dialog';
-import { DateBlock } from '@/components/base/display/date-block';
-import { MoneyDisplay } from '@/components/base/display/money-display';
-import { QRCode } from '@/components/base/display/qr-code';
-import { Button } from '@/components/base/buttons';
-import { Item, ItemActions, ItemContent, ItemDescription, ItemMedia, ItemTitle } from '@/components/base/item';
-import { Text } from '@/components/typography/text';
-import { MOCK_CUSTOMERS } from '@/preview/_mocks';
-
-export function NotificationBannerVariants() {
-	return (
-		<div className="flex flex-col gap-3 w-full max-w-md">
-			<NotificationBanner type="info" title="Heads up" message="An informational notice." />
-			<NotificationBanner type="success" title="Saved" message="All changes have been saved." />
-			<NotificationBanner type="warning" title="Be careful" message="This will affect 24 records." />
-			<NotificationBanner
-				type="error"
-				title="Failed"
-				message="Something went wrong."
-				dismissible
-				onDismiss={() => {}}
-			/>
-		</div>
-	);
-}
-
-export function AvatarSizes() {
-	return (
-		<div className="flex items-end gap-3">
-			<Avatar className="size-6">
-				<AvatarImage src="https://api.dicebear.com/7.x/avataaars/svg?seed=sarah" />
-				<AvatarFallback>SS</AvatarFallback>
-			</Avatar>
-			<Avatar className="size-8">
-				<AvatarFallback>ML</AvatarFallback>
-			</Avatar>
-			<Avatar className="size-10">
-				<AvatarImage src="https://api.dicebear.com/7.x/avataaars/svg?seed=aiko" />
-				<AvatarFallback>AT</AvatarFallback>
-			</Avatar>
-			<Avatar className="size-14">
-				<AvatarFallback>DR</AvatarFallback>
-			</Avatar>
-		</div>
-	);
-}
-
-export function StackedAvatarsExample() {
-	return (
-		<StackedAvatars
-			users={MOCK_CUSTOMERS.slice(0, 5).map((c) => ({
-				id: c.id,
-				name: c.name,
-				imageUrl: `https://api.dicebear.com/7.x/avataaars/svg?seed=${c.avatarSeed}`,
-			}))}
-			max={3}
-		/>
-	);
-}
-
-export function IconBadgeTones() {
-	const tones = ['primary', 'secondary', 'success', 'warning', 'destructive', 'info', 'muted'] as const;
-	return (
-		<div className="flex flex-wrap items-center gap-2">
-			{tones.map((tone) => (
-				<IconBadge key={tone} icon={Sparkles} tone={tone} />
-			))}
-		</div>
-	);
-}
-
-export function IconBadgeShapes() {
-	return (
-		<div className="flex items-center gap-3">
-			<IconBadge icon={Sparkles} shape="circle" />
-			<IconBadge icon={Sparkles} shape="square" />
-			<IconBadge icon={Sparkles} shape="circle" solid tone="primary" />
-			<IconBadge icon={Sparkles} shape="square" solid tone="success" />
-			<IconBadge icon={Sparkles} bordered />
-		</div>
-	);
-}
-
-export function IconBadgeSizes() {
-	return (
-		<div className="flex items-center gap-3">
-			<IconBadge icon={Bell} size="xs" />
-			<IconBadge icon={Bell} size="sm" />
-			<IconBadge icon={Bell} size="md" />
-			<IconBadge icon={Bell} size="lg" />
-		</div>
-	);
-}
-
-export function InlineStatLayouts() {
-	return (
-		<div className="flex flex-col gap-3 w-full max-w-md">
-			<InlineStat label="Total spent" value="$12,450" mono />
-			<InlineStat layout="inline" label="Status:" value="Active" />
-			<InlineStat layout="stacked" label="Last seen" value="3 hours ago" />
-		</div>
-	);
-}
-
-export function SeparatorExample() {
-	return (
-		<div className="w-full max-w-md">
-			<Text>Section above</Text>
-			<Separator className="my-3" />
-			<Text>Section below</Text>
-			<div className="mt-4 flex h-6 items-center gap-2">
-				<Text tag="span">Inline</Text>
-				<Separator orientation="vertical" />
-				<Text tag="span">Items</Text>
-				<Separator orientation="vertical" />
-				<Text tag="span">Here</Text>
-			</div>
-		</div>
-	);
-}
-
-export function TooltipExample() {
-	return (
-		<TooltipProvider>
-			<div className="flex items-center gap-3">
-				<Tooltip>
-					<TooltipTrigger asChild>
-						<Button type="button" variant="secondary" buttonStyle="outline">Hover me</Button>
-					</TooltipTrigger>
-					<TooltipContent>
-						<p>I'm a tooltip</p>
-					</TooltipContent>
-				</Tooltip>
-				<Tooltip>
-					<TooltipTrigger asChild>
-						<IconBadge icon={User} tone="primary" />
-					</TooltipTrigger>
-					<TooltipContent>
-						<p>User profile</p>
-					</TooltipContent>
-				</Tooltip>
-			</div>
-		</TooltipProvider>
-	);
-}
-
-export function BooleanIndicatorExample() {
-	return (
-		<div className="flex flex-col gap-2 w-full max-w-sm">
-			<BooleanIndicator label="Verified" value trueVariant="success" />
-			<BooleanIndicator label="Active" value={false} />
-			<BooleanIndicator label="Subscribed" value trueLabel="Yes" falseLabel="No" trueVariant="primary" />
-		</div>
-	);
-}
-
-export function ShowIfExample() {
-	const [show, setShow] = useState(true);
-	return (
-		<div className="flex flex-col gap-2 w-full max-w-sm">
-			<Button
-				type="button"
-				variant="secondary"
-				buttonStyle="outline"
-				className="self-start"
-				onClick={() => setShow((v) => !v)}
-			>
-				{show ? 'Hide' : 'Show'} content
-			</Button>
-			<ShowIf when={show} fallback={<Text tag="span" type="secondary">Hidden — fallback shown.</Text>}>
-				<Text tag="span">Visible only when <code>when</code> is true.</Text>
-			</ShowIf>
-		</div>
-	);
-}
-
-export function ThrottleAlertExample() {
-	return (
-		<div className="w-full max-w-md">
-			<ThrottleAlert
-				message="Too many failed attempts. Please wait."
-				attempts={5}
-				remaining="2 minutes"
-			/>
-		</div>
-	);
-}
-
-export function VisuallyHiddenExample() {
-	return (
-		<div className="flex flex-col gap-2">
-			<Button type="button" variant="secondary" buttonStyle="outline" size="icon-sm" className="self-start">
-				<span aria-hidden>×</span>
-				<VisuallyHidden>Close</VisuallyHidden>
-			</Button>
-			<Text size="xs" type="secondary">
-				The button has accessible name &quot;Close&quot; — only the × is visible.
-			</Text>
-		</div>
-	);
-}
-
-export function PlaceholderPatternExample() {
-	return (
-		<div className="relative h-32 w-full max-w-md overflow-hidden rounded-lg border border-border">
-			<PlaceholderPattern className="absolute inset-0 size-full text-muted" />
-		</div>
-	);
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Alert (shadcn re-export)
-// ─────────────────────────────────────────────────────────────────────────────
-
-export function AlertExample() {
-	return (
-		<div className="flex w-full max-w-md flex-col gap-3">
-			<Alert>
-				<Terminal className="size-4" />
-				<AlertTitle>Heads up!</AlertTitle>
-				<AlertDescription>You can preview every example below.</AlertDescription>
-			</Alert>
-			<Alert variant="destructive">
-				<AlertTriangle className="size-4" />
-				<AlertTitle>Something went wrong</AlertTitle>
-				<AlertDescription>Please retry or contact support.</AlertDescription>
-			</Alert>
-		</div>
-	);
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Progress
-// ─────────────────────────────────────────────────────────────────────────────
-
-export function ProgressExample() {
-	return (
-		<div className="flex w-full max-w-md flex-col gap-3">
-			<Progress value={20} />
-			<Progress value={60} />
-			<Progress value={92} />
-		</div>
-	);
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Skeleton
-// ─────────────────────────────────────────────────────────────────────────────
-
-export function SkeletonExample() {
-	return (
-		<div className="flex w-full max-w-md items-center gap-4">
-			<Skeleton className="size-12 rounded-full" />
-			<div className="flex flex-1 flex-col gap-2">
-				<Skeleton className="h-4 w-3/4" />
-				<Skeleton className="h-3 w-1/2" />
-			</div>
-		</div>
-	);
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Collapsible
-// ─────────────────────────────────────────────────────────────────────────────
-
-export function CollapsibleExample() {
-	return (
-		<div className="w-full max-w-md">
-			<Collapsible>
-				<CollapsibleTrigger asChild>
-					<Button type="button" variant="secondary" buttonStyle="outline" icon={ChevronDown}>
-						Toggle details
-					</Button>
-				</CollapsibleTrigger>
-				<CollapsibleContent className="mt-2 rounded-md border border-border bg-card p-3">
-					<Text>Hidden content revealed on click. Use Collapsible for inline disclosures.</Text>
-				</CollapsibleContent>
-			</Collapsible>
-		</div>
-	);
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Dialog
-// ─────────────────────────────────────────────────────────────────────────────
-
-export function DialogExample() {
-	return (
-		<Dialog>
-			<DialogTrigger asChild>
-				<Button>Open dialog</Button>
-			</DialogTrigger>
-			<DialogContent>
-				<DialogHeader>
-					<DialogTitle>Are you sure?</DialogTitle>
-					<DialogDescription>This action cannot be undone.</DialogDescription>
-				</DialogHeader>
-				<DialogFooter>
-					<Button variant="secondary" buttonStyle="ghost">Cancel</Button>
-					<Button variant="error">Delete</Button>
-				</DialogFooter>
-			</DialogContent>
-		</Dialog>
-	);
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// DateBlock
-// ─────────────────────────────────────────────────────────────────────────────
-
-export function DateBlockExample() {
-	return (
-		<div className="flex flex-wrap items-start gap-4">
-			<DateBlock date="2026-04-12" />
-			<DateBlock date="2026-04-12" time="14:30" />
-			<DateBlock date="2026-04-12" layout="inline" />
-			<DateBlock date={new Date()} tone="primary" />
-		</div>
-	);
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// MoneyDisplay
-// ─────────────────────────────────────────────────────────────────────────────
-
-export function MoneyDisplayExample() {
-	return (
-		<div className="flex flex-col gap-3">
-			<MoneyDisplay money={{ amount: 2450, currency: 'USD' }} size="lg" weight="semibold" />
-			<MoneyDisplay money={{ amount: 49.99, currency: 'EUR' }} />
-			<MoneyDisplay money={null} />
-		</div>
-	);
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// QRCode
-// ─────────────────────────────────────────────────────────────────────────────
-
-export function QRCodeExample() {
-	return (
-		<div className="w-40">
-			<QRCode data="https://github.com/admin-ui-starter-kit" />
-		</div>
-	);
-}
-
-export function RealisticUserCard() {
-	const c = MOCK_CUSTOMERS[0];
-	return (
-		<Item variant="outline" className="w-full max-w-md">
-			<ItemMedia variant="avatar">
-				<Avatar className="size-10">
-					<AvatarImage src={`https://api.dicebear.com/7.x/avataaars/svg?seed=${c.avatarSeed}`} />
-					<AvatarFallback>{c.name.split(' ').map((p) => p[0]).join('')}</AvatarFallback>
-				</Avatar>
-			</ItemMedia>
-			<ItemContent>
-				<ItemTitle>{c.name}</ItemTitle>
-				<ItemDescription clamp={1}>{c.email}</ItemDescription>
-			</ItemContent>
-			<ItemActions>
-				<Badge variant="success" className="gap-1.5 whitespace-nowrap">
-					<CheckCircle2 className="size-3.5" />
-					Verified
-				</Badge>
-			</ItemActions>
-		</Item>
-	);
-}
-```
-
-## Example exports
-
-- `NotificationBannerVariants`
-- `AvatarSizes`
-- `StackedAvatarsExample`
-- `IconBadgeTones`
-- `IconBadgeShapes`
-- `IconBadgeSizes`
-- `InlineStatLayouts`
-- `SeparatorExample`
-- `TooltipExample`
-- `BooleanIndicatorExample`
-- `ShowIfExample`
-- `ThrottleAlertExample`
-- `VisuallyHiddenExample`
-- `PlaceholderPatternExample`
-- `AlertExample`
-- `ProgressExample`
-- `SkeletonExample`
-- `CollapsibleExample`
-- `DialogExample`
-- `DateBlockExample`
-- `MoneyDisplayExample`
-- `QRCodeExample`
-- `RealisticUserCard`
-