admin-ui-starter-kit 0.1.4 → 0.4.3

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

@@ -25,8 +25,9 @@ imports:
   - @/components/base/badge
   - @/components/base/buttons
   - @/components/base/cards
+  - @/components/base/display/avatar
   - @/components/typography/text
-  - @/components/ui/avatar
+publicImport: admin-ui-starter-kit/base/cards
 tags:
   - base
   - foundations
@@ -41,8 +42,104 @@ tags:
 
 The composed card primitive — header (icon, title, suffix, slots), optional alert, expandable body, footer text or slot, and three surface chromes.
 
-**Layer:** `base`  
+**Layer:** `base`
 **Source:** `src/components/base/cards`
+**Consumer import:** `admin-ui-starter-kit/base/cards`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/cards`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+`SmartCard` is the canonical card surface — every dashboard tile, settings
+panel, or KPI block runs through it. Three `surface` chromes (`card`, `flat`,
+`framed`), three padding scales, optional `headerStart` / `headerEnd` /
+`headerAction` slots, action menus, alert bands, footer text or `footerSlot`,
+and an `expandable` body for long content.
+
+## Default
+
+<Example name="Default" source={examplesSource}>
+	<Examples.Default />
+</Example>
+
+## Surface variants
+
+<Example name="SurfaceVariants" source={examplesSource}>
+	<Examples.SurfaceVariants />
+</Example>
+
+## Padding sizes
+
+<Example name="PaddingSizes" source={examplesSource}>
+	<Examples.PaddingSizes />
+</Example>
+
+## Header composition
+
+<Example name="WithIconTooltipFooter" source={examplesSource}>
+	<Examples.WithIconTooltipFooter />
+</Example>
+
+<Example name="HeaderSlots" source={examplesSource}>
+	<Examples.HeaderSlots />
+</Example>
+
+<Example name="WithActions" source={examplesSource}>
+	<Examples.WithActions />
+</Example>
+
+<Example name="HeaderAndFooterDividers" source={examplesSource}>
+	<Examples.HeaderAndFooterDividers />
+</Example>
+
+## Alerts
+
+<Example name="AlertVariants" source={examplesSource}>
+	<Examples.AlertVariants />
+</Example>
+
+## Expandable
+
+<Example name="ExpandableUncontrolled" source={examplesSource}>
+	<Examples.ExpandableUncontrolled />
+</Example>
+
+<Example name="ExpandableCustomLabels" source={examplesSource}>
+	<Examples.ExpandableCustomLabels />
+</Example>
+
+## States
+
+<Example name="Skeleton" source={examplesSource}>
+	<Examples.Skeleton />
+</Example>
+
+## Primitive parts
+
+`CardShell`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`,
+and `CardFooter` are exported from `base/cards` for the rare case when
+`SmartCard`'s composition is too opinionated.
+
+<Example name="PrimitiveComposition" source={examplesSource}>
+	<Examples.PrimitiveComposition />
+</Example>
+
+## Realistic usage
+
+<Example name="MetricKPICard" source={examplesSource}>
+	<Examples.MetricKPICard />
+</Example>
+
+<Example name="NotificationCard" source={examplesSource}>
+	<Examples.NotificationCard />
+</Example>
+
+<Example name="StatRowClickable" source={examplesSource}>
+	<Examples.StatRowClickable />
+</Example>
 
 ## Examples
 
@@ -59,7 +156,7 @@ import {
 	CardContent,
 	CardFooter,
 } from '@/components/base/cards';
-import { Avatar, AvatarFallback } from '@/components/ui/avatar';
+import { Avatar, AvatarFallback } from '@/components/base/display/avatar';
 import { Text } from '@/components/typography/text';
 import { Badge } from '@/components/base/badge';
 
@@ -140,7 +237,7 @@ export function PaddingSizes() {
 
 export function SurfaceVariants() {
 	return (
-		<div className="grid w-full grid-cols-1 gap-4 md:grid-cols-3">
+		<div className="grid w-full grid-cols-[repeat(auto-fit,minmax(min(12rem,100%),1fr))] gap-3">
 			<SmartCard surface="card" title="Card (default)" description="Bordered + soft shadow.">
 				<Text type="secondary">Canonical card chrome.</Text>
 			</SmartCard>

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

@@ -0,0 +1,524 @@
+---
+id: base/carousel
+title: "Carousel"
+description: "Embla-backed carousel with keyboard navigation, orientation support, plugins, and base Button controls."
+layer: base
+family: "Navigation & data"
+sourcePath: src/components/base/carousel
+examples:
+  - ProductCarousel
+  - InsideControlsCarousel
+  - GalleryCarousel
+  - ProductGridGallery
+  - TopNavigationCarousel
+  - ResponsiveCarousel
+  - VerticalCarousel
+  - LocalizedControls
+imports:
+  - @/components/base/badge
+  - @/components/base/buttons
+  - @/components/base/cards
+  - @/components/base/carousel
+  - @/components/typography
+publicImport: admin-ui-starter-kit/base/carousel
+tags:
+  - base
+  - navigation
+  - data
+  - carousel
+  - embla
+  - backed
+  - keyboard
+  - orientation
+---
+
+# Carousel
+
+Embla-backed carousel with keyboard navigation, orientation support, plugins, and base Button controls.
+
+**Layer:** `base`
+**Source:** `src/components/base/carousel`
+**Consumer import:** `admin-ui-starter-kit/base/carousel`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/carousel`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+`Carousel` is the package-owned Embla wrapper. Importing it requires the
+optional `embla-carousel-react` peer; apps that never import `base/carousel`
+do not need that dependency. Pagination can use compact round dots or the
+pill treatment via `paginationStyle="pill"` on `CarouselDots` or
+`CarouselNavigation` `dotsProps`.
+
+## Usage
+
+Install `embla-carousel-react` in apps that import this exact entrypoint, then
+import the carousel family:
+
+```tsx
+import {
+	Carousel,
+	CarouselContent,
+	CarouselItem,
+	CarouselPrevious,
+	CarouselNext,
+	CarouselNavigation,
+	CarouselDots,
+} from 'admin-ui-starter-kit/base/carousel';
+```
+
+Use `opts` and `plugins` for Embla configuration, `orientation` for horizontal
+or vertical layouts, and `setApi` when a composed surface needs direct access to
+the Embla API. Choose root `controlPlacement` or per-control `placement` for
+outside, inside, overlay, or inline arrows. Use `CarouselNavigation` when arrows
+and pagination should live in the document flow, and pass `strings` to override
+all accessible labels.
+
+## Examples
+
+```tsx
+import {
+	Camera,
+	Footprints,
+	Headphones,
+	LampDesk,
+	Leaf,
+	Package,
+	PanelTop,
+	ShoppingBag,
+	TrendingUp,
+	Watch,
+	type LucideIcon,
+} from 'lucide-react';
+
+import {
+	Carousel,
+	CarouselContent,
+	CarouselDots,
+	CarouselItem,
+	CarouselNext,
+	CarouselNavigation,
+	CarouselPrevious,
+	useCarousel,
+} from '@/components/base/carousel';
+import { Badge } from '@/components/base/badge';
+import { Button } from '@/components/base/buttons';
+import { SmartCard } from '@/components/base/cards';
+import { Text } from '@/components/typography';
+
+const products = [
+	{
+		id: 'orbit',
+		name: 'Orbit field watch',
+		category: 'Accessories',
+		revenue: '$18.4k',
+		units: '1,284',
+		stock: 'In stock',
+		icon: Watch,
+		visualClass: 'border-info/20 bg-gradient-to-br from-info/5 via-card to-info/5',
+	},
+	{
+		id: 'signal',
+		name: 'Signal headphones',
+		category: 'Audio',
+		revenue: '$12.1k',
+		units: '842',
+		stock: 'Low stock',
+		icon: Headphones,
+		visualClass: 'border-primary/20 bg-gradient-to-br from-primary/5 via-card to-primary/5',
+	},
+	{
+		id: 'stride',
+		name: 'Stride runner',
+		category: 'Footwear',
+		revenue: '$8.9k',
+		units: '694',
+		stock: 'In stock',
+		icon: Footprints,
+		visualClass: 'border-success/20 bg-gradient-to-br from-success/5 via-card to-success/5',
+	},
+	{
+		id: 'focus',
+		name: 'Focus camera',
+		category: 'Photo',
+		revenue: '$7.3k',
+		units: '512',
+		stock: 'Restock',
+		icon: Camera,
+		visualClass: 'border-warning/20 bg-gradient-to-br from-warning/10 via-card to-warning/10',
+	},
+	{
+		id: 'arc',
+		name: 'Arc desk lamp',
+		category: 'Home office',
+		revenue: '$6.8k',
+		units: '438',
+		stock: 'In stock',
+		icon: LampDesk,
+		visualClass: 'border-info/20 bg-gradient-to-br from-muted via-card to-info/5',
+	},
+	{
+		id: 'terra',
+		name: 'Terra planter',
+		category: 'Garden',
+		revenue: '$5.6k',
+		units: '376',
+		stock: 'In stock',
+		icon: Leaf,
+		visualClass: 'border-success/20 bg-gradient-to-br from-muted via-card to-success/5',
+	},
+] satisfies Array<{
+	id: string;
+	name: string;
+	category: string;
+	revenue: string;
+	units: string;
+	stock: string;
+	icon: LucideIcon;
+	visualClass: string;
+}>;
+
+function stockVariant(stock: string) {
+	return stock === 'In stock' ? 'success' : 'warning';
+}
+
+function ProductVisual({
+	product,
+	className = 'aspect-video w-full',
+	compact = false,
+}: {
+	product: (typeof products)[number];
+	className?: string;
+	compact?: boolean;
+}) {
+	const Icon = product.icon;
+
+	return (
+		<div
+			role="img"
+			aria-label={product.name}
+			className={[
+				'relative flex items-center justify-center overflow-hidden rounded-md border',
+				product.visualClass,
+				className,
+			].join(' ')}
+		>
+			<div className="absolute inset-x-4 top-4 h-px bg-foreground/10" />
+			<div className="absolute inset-y-4 left-4 w-px bg-foreground/10" />
+			<div className="flex flex-col items-center gap-2 text-center">
+				<div className={compact ? 'rounded-md border border-border/70 bg-background/70 p-1.5' : 'rounded-lg border border-border/70 bg-background/70 p-3 shadow-xs'}>
+					<Icon className={compact ? 'size-5 text-foreground' : 'size-8 text-foreground'} aria-hidden="true" />
+				</div>
+				{!compact && (
+					<Text size="xs" weight="semibold" className="max-w-32 truncate">
+						{product.name}
+					</Text>
+				)}
+			</div>
+		</div>
+	);
+}
+
+export function ProductCarousel() {
+	return (
+		<Carousel className="w-full max-w-2xl px-11">
+			<CarouselContent>
+				{products.map((product) => (
+					<CarouselItem key={product.id}>
+						<SmartCard padding="sm" className="overflow-hidden">
+							<div className="grid gap-3 sm:grid-cols-[1.2fr_1fr] sm:items-center">
+								<ProductVisual product={product} />
+								<div className="space-y-2">
+									<Badge variant="info">{product.category}</Badge>
+									<div>
+										<Text weight="semibold">{product.name}</Text>
+										<Text size="xs" type="secondary">Featured product performance</Text>
+									</div>
+									<div className="flex items-center gap-2">
+										<TrendingUp className="size-4 text-success" />
+										<Text weight="semibold">{product.revenue}</Text>
+									</div>
+								</div>
+							</div>
+						</SmartCard>
+					</CarouselItem>
+				))}
+			</CarouselContent>
+			<CarouselPrevious className="left-0" />
+			<CarouselNext className="right-0" />
+			<CarouselDots paginationStyle="pill" className="mt-3" />
+		</Carousel>
+	);
+}
+
+export function InsideControlsCarousel() {
+	return (
+		<Carousel controlPlacement="inside" opts={{ align: 'start' }} className="w-full max-w-3xl">
+			<CarouselContent>
+				{products.slice(0, 4).map((product) => (
+					<CarouselItem key={product.id} className="md:basis-1/2">
+						<SmartCard
+							title={product.name}
+							description={product.category}
+							icon={<Package className="size-4" />}
+							padding="sm"
+							className="overflow-hidden"
+						>
+							<ProductVisual product={product} className="aspect-[16/10] w-full" />
+							<Text size="xs" type="secondary" className="mt-3">
+								Absolute controls sit inside the carousel bounds.
+							</Text>
+						</SmartCard>
+					</CarouselItem>
+				))}
+			</CarouselContent>
+			<CarouselPrevious />
+			<CarouselNext />
+			<CarouselDots className="mt-3" />
+		</Carousel>
+	);
+}
+
+function GalleryThumbnails() {
+	const { selectedIndex, scrollTo } = useCarousel();
+
+	return (
+		<div className="mt-3 grid grid-cols-4 gap-2">
+			{products.slice(0, 4).map((product, index) => (
+				<Button
+					key={product.id}
+					type="button"
+					variant="secondary"
+					buttonStyle="ghost"
+					size="sm"
+					aria-label={`Show ${product.name}`}
+					aria-current={selectedIndex === index ? 'true' : undefined}
+					className="h-auto min-w-0 justify-start rounded-lg p-1 data-[active=true]:ring-2 data-[active=true]:ring-ring/40"
+					data-active={selectedIndex === index ? 'true' : undefined}
+					onClick={() => scrollTo(index)}
+				>
+					<ProductVisual product={product} className="aspect-video w-full" compact />
+				</Button>
+			))}
+		</div>
+	);
+}
+
+export function GalleryCarousel() {
+	return (
+		<Carousel
+			opts={{ align: 'start', loop: true }}
+			controlPlacement="overlay"
+			className="w-full max-w-3xl"
+			strings={{ goToSlide: 'Show gallery image {index} of {total}' }}
+		>
+			<div className="relative">
+				<CarouselContent className="-ml-3">
+					{products.slice(0, 4).map((product) => (
+						<CarouselItem key={product.id} className="pl-3">
+							<SmartCard padding="sm" className="overflow-hidden">
+								<div className="grid gap-4 md:grid-cols-[1.4fr_1fr] md:items-center">
+									<ProductVisual product={product} className="aspect-[16/10] w-full" />
+									<div className="space-y-3">
+										<div className="flex items-center gap-2">
+											<Badge variant="info">{product.category}</Badge>
+											<Badge variant={stockVariant(product.stock)}>{product.stock}</Badge>
+										</div>
+										<div>
+											<Text weight="semibold">{product.name}</Text>
+											<Text size="xs" type="secondary">
+												Gallery navigation uses thumbnails plus Embla state.
+											</Text>
+										</div>
+										<div className="grid grid-cols-2 gap-2">
+											<div>
+												<Text size="xxs" type="secondary">Revenue</Text>
+												<Text weight="semibold">{product.revenue}</Text>
+											</div>
+											<div>
+												<Text size="xxs" type="secondary">Units</Text>
+												<Text weight="semibold">{product.units}</Text>
+											</div>
+										</div>
+									</div>
+								</div>
+							</SmartCard>
+						</CarouselItem>
+					))}
+				</CarouselContent>
+				<CarouselPrevious />
+				<CarouselNext />
+			</div>
+			<GalleryThumbnails />
+		</Carousel>
+	);
+}
+
+export function ProductGridGallery() {
+	const groups = [
+		products.slice(0, 3),
+		products.slice(3, 6),
+	];
+
+	return (
+		<Carousel
+			opts={{ align: 'start' }}
+			className="w-full max-w-5xl"
+			strings={{ goToSlide: 'Show product group {index} of {total}' }}
+		>
+			<CarouselContent>
+				{groups.map((group, index) => (
+					<CarouselItem key={index}>
+						<div className="grid gap-3 md:grid-cols-3">
+							{group.map((product) => (
+								<SmartCard
+									key={product.id}
+									title={product.name}
+									description={product.category}
+									icon={<ShoppingBag className="size-4" />}
+									headerEnd={<Badge variant={stockVariant(product.stock)}>{product.stock}</Badge>}
+									padding="sm"
+								>
+									<ProductVisual product={product} className="aspect-[4/3] w-full" />
+									<div className="mt-3 grid grid-cols-2 gap-2">
+										<div>
+											<Text size="xxs" type="secondary">Revenue</Text>
+											<Text weight="semibold">{product.revenue}</Text>
+										</div>
+										<div>
+											<Text size="xxs" type="secondary">Units</Text>
+											<Text weight="semibold">{product.units}</Text>
+										</div>
+									</div>
+								</SmartCard>
+							))}
+						</div>
+					</CarouselItem>
+				))}
+			</CarouselContent>
+			<div className="mt-3 flex flex-wrap items-center justify-between gap-3">
+				<div className="flex items-center gap-2">
+					<PanelTop className="size-4 text-muted-foreground" />
+					<Text size="xs" type="secondary">Grouped by merchandising priority</Text>
+				</div>
+				<CarouselNavigation align="end" dotsProps={{ paginationStyle: 'pill' }} />
+			</div>
+		</Carousel>
+	);
+}
+
+export function TopNavigationCarousel() {
+	return (
+		<Carousel controlPlacement="inline" opts={{ align: 'start' }} className="w-full max-w-3xl">
+			<div className="mb-3 flex flex-wrap items-center justify-between gap-3">
+				<div>
+					<Text weight="semibold">Relative top controls</Text>
+					<Text size="xs" type="secondary">Inline arrows and dots stay in document flow.</Text>
+				</div>
+				<CarouselNavigation align="end" dotsProps={{ paginationStyle: 'pill' }} />
+			</div>
+			<CarouselContent>
+				{products.slice(0, 4).map((product) => (
+					<CarouselItem key={product.id} className="sm:basis-1/2">
+						<SmartCard
+							title={product.name}
+							description={product.category}
+							icon={<ShoppingBag className="size-4" />}
+							headerEnd={<Badge variant={stockVariant(product.stock)}>{product.stock}</Badge>}
+						>
+							<Text size="xs" type="secondary">
+								{product.units} units sold this month.
+							</Text>
+						</SmartCard>
+					</CarouselItem>
+				))}
+			</CarouselContent>
+		</Carousel>
+	);
+}
+
+export function ResponsiveCarousel() {
+	return (
+		<Carousel opts={{ align: 'start' }} className="w-full max-w-4xl px-11">
+			<CarouselContent>
+				{products.map((product) => (
+					<CarouselItem key={product.id} className="sm:basis-1/2 lg:basis-1/3">
+						<SmartCard
+							title={product.name}
+							description={product.category}
+							icon={<Package className="size-4" />}
+						>
+							<ProductVisual product={product} className="aspect-[4/3] w-full" />
+							<Text size="xs" type="secondary" className="mt-3">
+								Revenue this month: {product.revenue}
+							</Text>
+						</SmartCard>
+					</CarouselItem>
+				))}
+			</CarouselContent>
+			<CarouselPrevious className="left-0" />
+			<CarouselNext className="right-0" />
+		</Carousel>
+	);
+}
+
+export function VerticalCarousel() {
+	return (
+		<Carousel orientation="vertical" className="h-80 w-full max-w-md py-11">
+			<CarouselContent className="h-64">
+				{products.map((product) => (
+					<CarouselItem key={product.id} className="basis-1/2">
+						<SmartCard title={product.name} description={product.category}>
+							<Text size="xs" type="secondary">Monthly revenue</Text>
+							<Text weight="semibold">{product.revenue}</Text>
+						</SmartCard>
+					</CarouselItem>
+				))}
+			</CarouselContent>
+			<CarouselPrevious className="top-0" />
+			<CarouselNext className="bottom-0" />
+		</Carousel>
+	);
+}
+
+export function LocalizedControls() {
+	return (
+		<Carousel
+			className="w-full max-w-md px-11"
+			strings={{
+				previousSlide: 'Previous product',
+				nextSlide: 'Next product',
+				goToSlide: 'Show product {index} of {total}',
+			}}
+		>
+			<CarouselContent>
+				{products.slice(0, 2).map((product) => (
+					<CarouselItem key={product.id}>
+						<SmartCard title={product.name} description={product.category}>
+							<Text size="xs" type="secondary">Accessible labels are supplied through `strings`.</Text>
+						</SmartCard>
+					</CarouselItem>
+				))}
+			</CarouselContent>
+			<CarouselPrevious className="left-0" />
+			<CarouselNext className="right-0" />
+			<CarouselDots className="mt-3" />
+		</Carousel>
+	);
+}
+```
+
+## Example exports
+
+- `ProductCarousel`
+- `InsideControlsCarousel`
+- `GalleryCarousel`
+- `ProductGridGallery`
+- `TopNavigationCarousel`
+- `ResponsiveCarousel`
+- `VerticalCarousel`
+- `LocalizedControls`
+