admin-ui-starter-kit 0.1.4 → 0.4.3

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

@@ -0,0 +1,391 @@
+---
+id: base/chart
+title: "Chart"
+description: "Token-aware Recharts helpers plus a composed ChartCard for admin analytics surfaces."
+layer: base
+family: "Display"
+sourcePath: src/components/base/display/chart
+examples:
+  - BarChartCard
+  - AreaChartCard
+  - LineChartCard
+  - DonutChartCard
+  - RadialChartCard
+  - MixedSeriesChartCard
+imports:
+  - @/components/base/badge
+  - @/components/base/display/chart
+  - @/components/composed/analytics
+  - @/components/typography
+publicImport: admin-ui-starter-kit/base/display/chart
+tags:
+  - base
+  - display
+  - chart
+  - token
+  - aware
+  - recharts
+  - helpers
+---
+
+# Chart
+
+Token-aware Recharts helpers plus a composed ChartCard for admin analytics surfaces.
+
+**Layer:** `base`
+**Source:** `src/components/base/display/chart`
+**Consumer import:** `admin-ui-starter-kit/base/display/chart`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/display/chart`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+The base chart helpers provide configuration, color variables, tooltip content,
+and legend content for Recharts. Use `ChartCard` from `composed/analytics`
+when the chart needs standard card chrome.
+
+## Usage
+
+Apps that import chart primitives install `recharts`, then use the exact chart
+entrypoint:
+
+```tsx
+import {
+	ChartContainer,
+	ChartTooltip,
+	ChartTooltipContent,
+	ChartLegend,
+	ChartLegendContent,
+	type ChartConfig,
+} from 'admin-ui-starter-kit/base/display/chart';
+import { ChartCard } from 'admin-ui-starter-kit/composed/analytics';
+```
+
+Keep data, axes, series, and Recharts chart children caller-owned. Pass
+`ChartConfig` labels and colors into `ChartContainer`; the helper exposes those
+colors as `--color-*` variables scoped to the chart. Use `ChartTooltipContent`
+and `ChartLegendContent` for tokenized admin-density chrome. Use `ChartCard`
+when a chart needs SmartCard header, footer, and slot structure without adding a
+schema layer.
+
+## Examples
+
+```tsx
+import {
+	Area,
+	AreaChart,
+	Bar,
+	BarChart,
+	ComposedChart,
+	CartesianGrid,
+	Cell,
+	Line,
+	LineChart,
+	Pie,
+	PieChart,
+	PolarAngleAxis,
+	RadialBar,
+	RadialBarChart,
+	ReferenceArea,
+	XAxis,
+	YAxis,
+} from 'recharts';
+
+import { Badge } from '@/components/base/badge';
+import {
+	ChartLegend,
+	ChartLegendContent,
+	ChartTooltip,
+	ChartTooltipContent,
+	type ChartConfig,
+} from '@/components/base/display/chart';
+import { ChartCard } from '@/components/composed/analytics';
+import { Text } from '@/components/typography';
+
+const monthlyData = [
+	{ month: 'Jan', revenue: 30000, target: 36000, orders: 240 },
+	{ month: 'Feb', revenue: 42000, target: 39000, orders: 310 },
+	{ month: 'Mar', revenue: 38000, target: 43000, orders: 290 },
+	{ month: 'Apr', revenue: 54000, target: 47000, orders: 420 },
+	{ month: 'May', revenue: 46000, target: 52000, orders: 370 },
+	{ month: 'Jun', revenue: 68000, target: 56000, orders: 520 },
+];
+
+const channelData = [
+	{ channel: 'Direct', desktop: 186, mobile: 80 },
+	{ channel: 'Search', desktop: 305, mobile: 200 },
+	{ channel: 'Social', desktop: 237, mobile: 120 },
+	{ channel: 'Email', desktop: 73, mobile: 190 },
+	{ channel: 'Partner', desktop: 209, mobile: 130 },
+];
+
+const segmentData = [
+	{ segment: 'New', value: 420, fill: 'var(--color-new)' },
+	{ segment: 'Returning', value: 680, fill: 'var(--color-returning)' },
+	{ segment: 'Enterprise', value: 260, fill: 'var(--color-enterprise)' },
+];
+
+const capacityData = [{ name: 'Used', value: 76, fill: 'var(--color-used)' }];
+
+const monthlyBands = [
+	{ id: 'jan-feb', x1: 'Jan', x2: 'Feb' },
+	{ id: 'mar-apr', x1: 'Mar', x2: 'Apr' },
+	{ id: 'may-jun', x1: 'May', x2: 'Jun' },
+];
+
+const channelBands = [
+	{ id: 'direct-search', x1: 'Direct', x2: 'Search' },
+	{ id: 'social-email', x1: 'Social', x2: 'Email' },
+];
+
+const chartConfig = {
+	revenue: { label: 'Revenue', color: 'var(--chart-1)' },
+	target: { label: 'Target', color: 'var(--chart-2)' },
+	orders: { label: 'Orders', color: 'var(--chart-2)' },
+	desktop: { label: 'Desktop', color: 'var(--chart-1)' },
+	mobile: { label: 'Mobile', color: 'var(--chart-2)' },
+	new: { label: 'New', color: 'var(--chart-1)' },
+	returning: { label: 'Returning', color: 'var(--chart-2)' },
+	enterprise: { label: 'Enterprise', color: 'var(--chart-3)' },
+	used: { label: 'Used capacity', color: 'var(--chart-1)' },
+} satisfies ChartConfig;
+
+function currencyTick(value: number | string) {
+	const parsed = Number(value);
+	return Number.isFinite(parsed) ? `$${Math.round(parsed / 1000)}k` : String(value);
+}
+
+function ChartInsight({
+	label,
+	value,
+	tone = 'secondary',
+}: {
+	label: string;
+	value: string;
+	tone?: 'secondary' | 'success' | 'warning';
+}) {
+	return (
+		<div className="flex flex-wrap items-center justify-between gap-2">
+			<Text size="xs" type="secondary">{label}</Text>
+			<Badge variant={tone}>{value}</Badge>
+		</div>
+	);
+}
+
+function MonthlyBands() {
+	return (
+		<>
+			{monthlyBands.map((band) => (
+				<ReferenceArea
+					key={band.id}
+					x1={band.x1}
+					x2={band.x2}
+					fill="var(--muted)"
+					fillOpacity={0.34}
+					strokeOpacity={0}
+				/>
+			))}
+		</>
+	);
+}
+
+function ChannelBands() {
+	return (
+		<>
+			{channelBands.map((band) => (
+				<ReferenceArea
+					key={band.id}
+					x1={band.x1}
+					x2={band.x2}
+					fill="var(--muted)"
+					fillOpacity={0.28}
+					strokeOpacity={0}
+				/>
+			))}
+		</>
+	);
+}
+
+export function BarChartCard() {
+	return (
+		<ChartCard
+			title="Revenue growth"
+			description="Monthly revenue by completed order date"
+			headerEnd={<Badge variant="success">+12.4%</Badge>}
+			footer={<ChartInsight label="Best month" value="June" tone="success" />}
+			config={chartConfig}
+		>
+			<BarChart accessibilityLayer data={monthlyData} margin={{ left: 4, right: 8, top: 12 }}>
+				<MonthlyBands />
+				<CartesianGrid vertical={false} strokeDasharray="3 3" strokeOpacity={0.7} />
+				<XAxis dataKey="month" tickLine={false} axisLine={false} tickMargin={8} />
+				<YAxis width={36} tickLine={false} axisLine={false} tickFormatter={currencyTick} />
+				<ChartTooltip cursor={false} content={<ChartTooltipContent indicator="dot" />} />
+				<Bar dataKey="revenue" fill="var(--color-revenue)" radius={[4, 4, 2, 2]} maxBarSize={48} />
+			</BarChart>
+		</ChartCard>
+	);
+}
+
+export function AreaChartCard() {
+	return (
+		<ChartCard
+			title="Order volume"
+			description="Orders accepted over the last six months"
+			headerEnd={<Badge variant="info">+31%</Badge>}
+			footer={<ChartInsight label="Queued fulfillment" value="18 orders" />}
+			config={chartConfig}
+		>
+			<AreaChart accessibilityLayer data={monthlyData} margin={{ left: 4, right: 8, top: 12 }}>
+				<defs>
+					<linearGradient id="orders-fill" x1="0" y1="0" x2="0" y2="1">
+						<stop offset="5%" stopColor="var(--color-orders)" stopOpacity={0.35} />
+						<stop offset="95%" stopColor="var(--color-orders)" stopOpacity={0.02} />
+					</linearGradient>
+				</defs>
+				<MonthlyBands />
+				<CartesianGrid vertical={false} strokeDasharray="3 3" strokeOpacity={0.7} />
+				<XAxis dataKey="month" tickLine={false} axisLine={false} tickMargin={8} />
+				<YAxis width={28} tickLine={false} axisLine={false} />
+				<ChartTooltip cursor={false} content={<ChartTooltipContent indicator="line" />} />
+				<Area
+					dataKey="orders"
+					type="natural"
+					fill="url(#orders-fill)"
+					stroke="var(--color-orders)"
+					strokeWidth={2}
+				/>
+			</AreaChart>
+		</ChartCard>
+	);
+}
+
+export function LineChartCard() {
+	return (
+		<ChartCard
+			title="Revenue vs target"
+			description="Actual revenue compared with monthly target"
+			headerEnd={<Badge variant="success">On pace</Badge>}
+			footer={<ChartInsight label="Target gap closed" value="18%" tone="success" />}
+			config={chartConfig}
+		>
+			<LineChart accessibilityLayer data={monthlyData} margin={{ left: 4, right: 8, top: 12 }}>
+				<MonthlyBands />
+				<CartesianGrid vertical={false} strokeDasharray="3 3" strokeOpacity={0.7} />
+				<XAxis dataKey="month" tickLine={false} axisLine={false} tickMargin={8} />
+				<YAxis width={36} tickLine={false} axisLine={false} tickFormatter={currencyTick} />
+				<ChartTooltip cursor={false} content={<ChartTooltipContent indicator="dot" />} />
+				<ChartLegend content={<ChartLegendContent />} />
+				<Line dataKey="revenue" type="monotone" stroke="var(--color-revenue)" strokeWidth={2} dot={false} />
+				<Line
+					dataKey="target"
+					type="monotone"
+					stroke="var(--color-target)"
+					strokeWidth={2}
+					strokeDasharray="5 4"
+					dot={false}
+				/>
+			</LineChart>
+		</ChartCard>
+	);
+}
+
+export function DonutChartCard() {
+	return (
+		<ChartCard
+			title="Customer mix"
+			description="Active customer segments this month"
+			headerEnd={<Badge variant="info">1,360</Badge>}
+			footer={<ChartInsight label="Returning share" value="50%" tone="success" />}
+			config={chartConfig}
+			chartClassName="mx-auto max-w-sm"
+		>
+			<PieChart accessibilityLayer>
+				<ChartTooltip cursor={false} content={<ChartTooltipContent hideLabel nameKey="segment" />} />
+				<Pie
+					data={segmentData}
+					dataKey="value"
+					nameKey="segment"
+					innerRadius={58}
+					outerRadius={86}
+					paddingAngle={2}
+				>
+					{segmentData.map((entry) => (
+						<Cell key={entry.segment} fill={entry.fill} />
+					))}
+				</Pie>
+				<ChartLegend content={<ChartLegendContent nameKey="segment" />} />
+			</PieChart>
+		</ChartCard>
+	);
+}
+
+export function RadialChartCard() {
+	return (
+		<ChartCard
+			title="Automation capacity"
+			description="Current worker pool utilization"
+			headerEnd={<Badge variant="warning">76%</Badge>}
+			footer={<ChartInsight label="Autoscale threshold" value="85%" tone="warning" />}
+			config={chartConfig}
+			chartClassName="mx-auto max-w-sm"
+		>
+			<RadialBarChart
+				accessibilityLayer
+				data={capacityData}
+				startAngle={90}
+				endAngle={-270}
+				innerRadius={72}
+				outerRadius={104}
+			>
+				<PolarAngleAxis type="number" domain={[0, 100]} tick={false} />
+				<RadialBar dataKey="value" background cornerRadius={8} />
+				<ChartTooltip cursor={false} content={<ChartTooltipContent hideLabel />} />
+			</RadialBarChart>
+		</ChartCard>
+	);
+}
+
+export function MixedSeriesChartCard() {
+	return (
+		<ChartCard
+			title="Traffic by channel"
+			description="Desktop bars with mobile trend overlay"
+			headerEnd={<Badge variant="info">5 channels</Badge>}
+			footer={<ChartInsight label="Mobile lift" value="+8.6%" tone="success" />}
+			config={chartConfig}
+		>
+			<ComposedChart accessibilityLayer data={channelData} margin={{ left: 4, right: 8, top: 12 }}>
+				<ChannelBands />
+				<CartesianGrid vertical={false} strokeDasharray="3 3" strokeOpacity={0.7} />
+				<XAxis dataKey="channel" tickLine={false} axisLine={false} tickMargin={8} />
+				<YAxis width={28} tickLine={false} axisLine={false} />
+				<ChartTooltip cursor={false} content={<ChartTooltipContent indicator="dashed" />} />
+				<ChartLegend content={<ChartLegendContent />} />
+				<Bar dataKey="desktop" fill="var(--color-desktop)" radius={[4, 4, 2, 2]} maxBarSize={44} />
+				<Line
+					dataKey="mobile"
+					type="monotone"
+					stroke="var(--color-mobile)"
+					strokeWidth={2}
+					strokeDasharray="5 4"
+					dot={false}
+				/>
+			</ComposedChart>
+		</ChartCard>
+	);
+}
+```
+
+## Example exports
+
+- `BarChartCard`
+- `AreaChartCard`
+- `LineChartCard`
+- `DonutChartCard`
+- `RadialChartCard`
+- `MixedSeriesChartCard`
+

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

@@ -27,12 +27,15 @@ examples:
   - Invalid
   - MinSearchLength
   - RealisticCustomerPicker
+  - FormFieldIntegration
 imports:
   - @/components/base/badge
   - @/components/base/combobox
+  - @/components/base/display/avatar
+  - @/components/base/forms
   - @/components/typography
-  - @/components/ui/avatar
   - @/preview/_mocks
+publicImport: admin-ui-starter-kit/base/combobox
 tags:
   - base
   - forms
@@ -48,15 +51,158 @@ tags:
 
 EnhancedCombobox and EnhancedComboboxMultiple — searchable, optionally grouped, with apply / close-on-select behaviours, async fetchers, custom rendering, and form integration.
 
-**Layer:** `base`  
+**Layer:** `base`
 **Source:** `src/components/base/combobox`
+**Consumer import:** `admin-ui-starter-kit/base/combobox`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/combobox`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+The combobox primitives are intentionally generic — pass an `items` array
+(any shape), a `getItemLabel` and `getItemKey`, and own the `searchValue` and
+`selectedValue(s)` state. Optional `getItemGroup` collapses items into
+sections; `applyButton` defers commit until the user clicks Apply;
+`closeOnSelect` closes the popover after each pick. `creatable` + `onCreate`
+turn it into a free-form input. Every callback (`onSearch`, `onLoadMore`,
+`onCreate`) is an opt-in seam — no hardcoded fetcher, no opinionated wiring.
+
+## Consumer usage
+
+Consumers import the searchable select primitives from the exact package
+entrypoint:
+
+```tsx
+import { EnhancedCombobox, EnhancedComboboxMultiple } from 'admin-ui-starter-kit/base/combobox';
+import { ControlledFormField } from 'admin-ui-starter-kit/base/forms';
+```
+
+Use `EnhancedCombobox` for one value and `EnhancedComboboxMultiple` for arrays.
+The consuming app owns both the search text and selected value state. Always
+provide `getItemLabel` and `getItemKey` so the component can render labels,
+restore selected values, and keep list keys stable across async refreshes.
+
+Inside forms, wrap the combobox in `ControlledFormField`, pass `field.name`,
+`field.onBlur`, `field.value`, and `field.onChange`, then forward the third
+render-prop argument as `invalid={invalid}`. Use the combobox `error` prop only
+when the combobox renders outside `FormField` and needs to display its own error
+message.
+
+## Single
+
+<Example name="Default" source={examplesSource}>
+	<Examples.Default />
+</Example>
+
+<Example name="SingleSelect" source={examplesSource}>
+	<Examples.SingleSelect />
+</Example>
+
+<Example name="SingleHighlightMatch" source={examplesSource}>
+	<Examples.SingleHighlightMatch />
+</Example>
+
+<Example name="SingleCreatable" source={examplesSource}>
+	<Examples.SingleCreatable />
+</Example>
+
+## Multiple
+
+<Example name="MultipleSelect" source={examplesSource}>
+	<Examples.MultipleSelect />
+</Example>
+
+<Example name="MultipleApplyButton" source={examplesSource}>
+	<Examples.MultipleApplyButton />
+</Example>
+
+<Example name="MultipleCloseOnSelect" source={examplesSource}>
+	<Examples.MultipleCloseOnSelect />
+</Example>
+
+## Grouped options
+
+<Example name="MultipleGrouped" source={examplesSource}>
+	<Examples.MultipleGrouped />
+</Example>
+
+<Example name="GroupedTeamByRole" source={examplesSource}>
+	<Examples.GroupedTeamByRole />
+</Example>
+
+## Async / fetcher
+
+<Example name="AsyncCustomers" source={examplesSource}>
+	<Examples.AsyncCustomers />
+</Example>
+
+<Example name="AsyncDebouncedSearch" source={examplesSource}>
+	<Examples.AsyncDebouncedSearch />
+</Example>
+
+<Example name="AsyncWithLoadMore" source={examplesSource}>
+	<Examples.AsyncWithLoadMore />
+</Example>
+
+## Custom rendering
+
+<Example name="CustomItemRendering" source={examplesSource}>
+	<Examples.CustomItemRendering />
+</Example>
+
+<Example name="CustomGroupLabels" source={examplesSource}>
+	<Examples.CustomGroupLabels />
+</Example>
+
+## Sizes
+
+<Example name="SizeSm" source={examplesSource}>
+	<Examples.SizeSm />
+</Example>
+
+<Example name="SizeMd" source={examplesSource}>
+	<Examples.SizeMd />
+</Example>
+
+<Example name="SizeLg" source={examplesSource}>
+	<Examples.SizeLg />
+</Example>
+
+## States
+
+<Example name="Disabled" source={examplesSource}>
+	<Examples.Disabled />
+</Example>
+
+<Example name="Invalid" source={examplesSource}>
+	<Examples.Invalid />
+</Example>
+
+<Example name="MinSearchLength" source={examplesSource}>
+	<Examples.MinSearchLength />
+</Example>
+
+## Realistic usage
+
+<Example name="RealisticCustomerPicker" source={examplesSource}>
+	<Examples.RealisticCustomerPicker />
+</Example>
+
+<Example name="FormFieldIntegration" source={examplesSource}>
+	<Examples.FormFieldIntegration />
+</Example>
 
 ## Examples
 
 ```tsx
 import { useEffect, useMemo, useState } from 'react';
+import { useForm } from 'react-hook-form';
 import { EnhancedCombobox, EnhancedComboboxMultiple } from '@/components/base/combobox';
-import { Avatar, AvatarFallback } from '@/components/ui/avatar';
+import { ControlledFormField } from '@/components/base/forms';
+import { Avatar, AvatarFallback } from '@/components/base/display/avatar';
 import { Badge } from '@/components/base/badge';
 import { Text } from '@/components/typography';
 import {
@@ -68,6 +214,7 @@ import {
 } from '@/preview/_mocks';
 
 type Fruit = { id: string; name: string; group?: string };
+type AssigneeFormValues = { assignee: typeof MOCK_TEAM[number] | null };
 
 const ALL: Fruit[] = [
 	{ id: 'apple', name: 'Apple', group: 'Pomes' },
@@ -669,6 +816,67 @@ export function RealisticCustomerPicker() {
 		</div>
 	);
 }
+
+export function FormFieldIntegration() {
+	const { control, watch } = useForm<AssigneeFormValues>({
+		defaultValues: { assignee: null },
+		mode: 'onBlur',
+	});
+	const [search, setSearch] = useState('');
+	const assignee = watch('assignee');
+	const filtered = useMemo(() => {
+		const q = search.toLowerCase().trim();
+		if (!q) return MOCK_TEAM;
+		return MOCK_TEAM.filter((member) =>
+			member.name.toLowerCase().includes(q) || member.role.toLowerCase().includes(q)
+		);
+	}, [search]);
+
+	return (
+		<div className="grid w-full max-w-sm gap-2">
+			<ControlledFormField
+				name="assignee"
+				control={control}
+				label="Assignee"
+				required
+				hint="Search by teammate or role."
+				rules={{ required: 'Choose an assignee' }}
+			>
+				{(field, _error, invalid) => (
+					<EnhancedCombobox
+						name={field.name}
+						items={filtered}
+						searchValue={search}
+						onSearchValueChange={setSearch}
+						selectedValue={field.value}
+						onSelectedValueChange={field.onChange}
+						onBlur={field.onBlur}
+						invalid={invalid}
+						getItemLabel={(member) => member.name}
+						getItemKey={(member) => member.id}
+						minSearchLength={0}
+						strings={{ placeholder: 'Assign owner…' }}
+						renderItem={(member) => (
+							<div className="flex w-full items-center gap-2.5">
+								<Avatar className="h-7 w-7">
+									<AvatarFallback>{member.name.split(' ').map((part) => part[0]).join('')}</AvatarFallback>
+								</Avatar>
+								<div className="min-w-0 flex-1">
+									<Text weight="semibold">{member.name}</Text>
+									<Text size="xs" type="secondary">{member.role}</Text>
+								</div>
+								<Badge variant="secondary">{member.role}</Badge>
+							</div>
+						)}
+					/>
+				)}
+			</ControlledFormField>
+			<Text size="xs" type="secondary">
+				Selected owner: {assignee?.name ?? 'none'}
+			</Text>
+		</div>
+	);
+}
 ```
 
 ## Example exports
@@ -694,4 +902,5 @@ export function RealisticCustomerPicker() {
 - `Invalid`
 - `MinSearchLength`
 - `RealisticCustomerPicker`
+- `FormFieldIntegration`