admin-ui-starter-kit 0.1.4 → 0.4.2

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

@@ -0,0 +1,187 @@
+---
+id: features/mentions
+title: "Features · Mentions"
+description: "Inline resource references for editors, comments, and event logs. Consumers provide resource registries and search callbacks; the package provides chips, picker UI, inline suggestions, parsing helpers, and headless hooks."
+layer: features
+family: "Collaboration"
+sourcePath: src/components/features/mentions
+examples:
+  - InlineMentionSuggestions
+  - MentionPickerPopover
+imports:
+  - @/components/base/badge
+  - @/components/base/buttons
+  - @/components/base/popover
+  - @/components/features/mentions
+  - @/components/typography
+publicImport: admin-ui-starter-kit/features/mentions
+tags:
+  - features
+  - collaboration
+  - mentions
+  - inline
+  - resource
+  - references
+  - editors
+---
+
+# Features · Mentions
+
+Inline resource references for editors, comments, and event logs. Consumers provide resource registries and search callbacks; the package provides chips, picker UI, inline suggestions, parsing helpers, and headless hooks.
+
+**Layer:** `features`
+**Source:** `src/components/features/mentions`
+**Consumer import:** `admin-ui-starter-kit/features/mentions`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/features/mentions`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Examples
+
+```tsx
+import { useState } from 'react';
+import { CalendarDays, Hash, UserRound } from 'lucide-react';
+
+import { Badge } from '@/components/base/badge';
+import { Button } from '@/components/base/buttons';
+import { Popover, PopoverTrigger } from '@/components/base/popover';
+import {
+	MentionChip,
+	MentionInlineSuggestions,
+	MentionPicker,
+	type MentionSuggestion,
+} from '@/components/features/mentions';
+import { Text } from '@/components/typography';
+
+type Kind = 'user' | 'booking';
+
+const resources = {
+	user: {
+		label: 'People',
+		icon: UserRound,
+		trigger: '@',
+		tone: 'primary' as const,
+	},
+	booking: {
+		label: 'Bookings',
+		icon: CalendarDays,
+		trigger: '#',
+		tone: 'info' as const,
+	},
+};
+
+const suggestions: MentionSuggestion<Kind>[] = [
+	{
+		id: 'user-1',
+		kind: 'user',
+		label: 'Maya Chen',
+		description: 'Account owner',
+	},
+	{
+		id: 'booking-1048',
+		kind: 'booking',
+		label: 'Booking #1048',
+		description: 'Chef table, Jun 24',
+	},
+];
+
+export function InlineMentionSuggestions() {
+	const [activeKind, setActiveKind] = useState<Kind | null>('user');
+	const [selected, setSelected] = useState<MentionSuggestion<Kind> | null>(null);
+	const visibleSuggestions = suggestions.filter((item) => item.kind === activeKind);
+
+	return (
+		<div className="space-y-3">
+			<div className="relative min-h-44 rounded-md border border-border/60 bg-card p-3">
+				<Text size="sm">
+					Loop <span className="font-medium text-primary">@ma</span> into the booking note.
+				</Text>
+				<MentionInlineSuggestions
+					open
+					activeKind={activeKind}
+					setActiveKind={setActiveKind}
+					kinds={['user', 'booking']}
+					resources={resources}
+					query="ma"
+					suggestions={visibleSuggestions}
+					suggestionsByKind={{
+						user: suggestions.filter((item) => item.kind === 'user'),
+						booking: suggestions.filter((item) => item.kind === 'booking'),
+					}}
+					isLoading={false}
+					onSelect={setSelected}
+				/>
+			</div>
+			{selected ? (
+				<div className="flex items-center gap-2">
+					<Text size="xs" type="secondary">
+						Selected
+					</Text>
+					<Badge variant="secondary">{selected.label}</Badge>
+				</div>
+			) : null}
+		</div>
+	);
+}
+
+export function MentionPickerPopover() {
+	const [open, setOpen] = useState(false);
+	const [activeKind, setActiveKind] = useState<Kind | null>('user');
+	const [query, setQuery] = useState('');
+	const [selected, setSelected] = useState<MentionSuggestion<Kind> | null>(null);
+	const filtered = suggestions.filter((item) => {
+		const matchesKind = activeKind === null || item.kind === activeKind;
+		const matchesQuery = item.label.toLowerCase().includes(query.toLowerCase());
+		return matchesKind && matchesQuery;
+	});
+
+	return (
+		<div className="space-y-3">
+			<Popover open={open} onOpenChange={setOpen}>
+				<PopoverTrigger asChild>
+					<Button type="button" variant="secondary" icon={Hash}>
+						Add reference
+					</Button>
+				</PopoverTrigger>
+				<MentionPicker
+					open={open}
+					activeKind={activeKind}
+					setActiveKind={setActiveKind}
+					kinds={['user', 'booking']}
+					resources={resources}
+					query={query}
+					setQuery={setQuery}
+					suggestions={filtered}
+					isLoading={false}
+					onSelect={(item) => {
+						setSelected(item);
+						setOpen(false);
+					}}
+				/>
+			</Popover>
+			{selected ? (
+				<MentionChip
+					mention={{
+						id: selected.id,
+						kind: selected.kind ?? 'user',
+						label: selected.label,
+					}}
+					resource={resources[selected.kind ?? 'user']}
+				/>
+			) : (
+				<Text size="xs" type="secondary">
+					No reference selected.
+				</Text>
+			)}
+		</div>
+	);
+}
+```
+
+## Example exports
+
+- `InlineMentionSuggestions`
+- `MentionPickerPopover`
+

package/.agents/skills/component-library-rules/references/components/features__metrics-analytics-bar.md

@@ -11,6 +11,7 @@ examples:
   - MetricGridCompactCardsAlternative
 imports:
   - @/components/composed/analytics
+publicImport: admin-ui-starter-kit/composed/analytics
 tags:
   - features
   - metrics
@@ -25,8 +26,14 @@ tags:
 
 `MetricBar` — horizontal KPI strip with hairline-divided cells. Pair with `MetricGrid` for card-style layouts.
 
-**Layer:** `features`  
+**Layer:** `features`
 **Source:** `src/components/composed/analytics`
+**Consumer import:** `admin-ui-starter-kit/composed/analytics`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/composed/analytics`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
 ## Examples
 

package/.agents/skills/component-library-rules/references/components/features__metrics-analytics-cards.md

@@ -9,6 +9,7 @@ examples:
   - FourThemes
 imports:
   - @/components/composed/analytics
+publicImport: admin-ui-starter-kit/composed/analytics
 tags:
   - features
   - metrics
@@ -23,8 +24,14 @@ tags:
 
 `MetricGradient` — vivid gradient hero card with embedded area chart. Pick a `theme` to drive the colour palette.
 
-**Layer:** `features`  
+**Layer:** `features`
 **Source:** `src/components/composed/analytics`
+**Consumer import:** `admin-ui-starter-kit/composed/analytics`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/composed/analytics`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
 ## Examples
 

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

@@ -12,6 +12,7 @@ examples:
   - FlatNoChange
 imports:
   - @/components/composed/analytics
+publicImport: admin-ui-starter-kit/composed/analytics
 tags:
   - features
   - metrics
@@ -26,8 +27,14 @@ tags:
 
 `MetricComparison` — side-by-side current vs previous with a tone-tinted delta box. Reuses the unified `MetricData` shape so currency/percent formatting carries through.
 
-**Layer:** `features`  
+**Layer:** `features`
 **Source:** `src/components/composed/analytics`
+**Consumer import:** `admin-ui-starter-kit/composed/analytics`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/composed/analytics`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
 ## Examples
 

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

@@ -9,6 +9,7 @@ examples:
   - OrderActivity
 imports:
   - @/components/composed/analytics
+publicImport: admin-ui-starter-kit/composed/analytics
 tags:
   - features
   - metrics
@@ -23,8 +24,14 @@ tags:
 
 `ActivityHeatmap` — GitHub-style daily-activity calendar with success-tinted intensity cells.
 
-**Layer:** `features`  
+**Layer:** `features`
 **Source:** `src/components/composed/analytics`
+**Consumer import:** `admin-ui-starter-kit/composed/analytics`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/composed/analytics`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
 ## Examples
 
@@ -33,11 +40,11 @@ import { ActivityHeatmap, type ActivityHeatmapDay } from '@/components/composed/
 
 function generate(): ActivityHeatmapDay[] {
 	const days: ActivityHeatmapDay[] = [];
-	const now = new Date();
+	const now = new Date('2026-06-19T00:00:00Z');
 	for (let i = 89; i >= 0; i--) {
 		const d = new Date(now);
 		d.setDate(d.getDate() - i);
-		const r = Math.random();
+		const r = ((i * 37 + 17) % 100) / 100;
 		const level: 0 | 1 | 2 | 3 | 4 = r < 0.15 ? 0 : r < 0.35 ? 1 : r < 0.6 ? 2 : r < 0.8 ? 3 : 4;
 		days.push({ date: d.toISOString().slice(0, 10), level });
 	}

package/.agents/skills/component-library-rules/references/components/features__metrics-inline-badge.md

@@ -9,6 +9,7 @@ examples:
   - MixedSizesDirections
 imports:
   - @/components/composed/data-display/inline-metric
+publicImport: admin-ui-starter-kit/composed/data-display
 tags:
   - features
   - metrics
@@ -23,8 +24,14 @@ tags:
 
 `InlineMetricBadge` — compact `label · value · change%` pill rows. Use as in-flow copy where a full Metric tile is too heavy.
 
-**Layer:** `features`  
+**Layer:** `features`
 **Source:** `src/components/composed/data-display/inline-metric`
+**Consumer import:** `admin-ui-starter-kit/composed/data-display`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/composed/data-display`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
 ## Examples
 

package/.agents/skills/component-library-rules/references/components/features__metrics-kpi-row.md

@@ -10,6 +10,7 @@ examples:
   - Example3KPIs
 imports:
   - @/components/composed/data-display/mini-kpi
+publicImport: admin-ui-starter-kit/composed/data-display
 tags:
   - features
   - metrics
@@ -24,8 +25,14 @@ tags:
 
 `MiniKpiRow` — compact horizontal divider-separated KPI strip for header / footer accents.
 
-**Layer:** `features`  
+**Layer:** `features`
 **Source:** `src/components/composed/data-display/mini-kpi`
+**Consumer import:** `admin-ui-starter-kit/composed/data-display`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/composed/data-display`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
 ## Examples
 

package/.agents/skills/component-library-rules/references/components/features__metrics-micro-grid.md

@@ -10,6 +10,7 @@ examples:
   - PinnedChartKinds
 imports:
   - @/components/composed/analytics
+publicImport: admin-ui-starter-kit/composed/analytics
 tags:
   - features
   - metrics
@@ -24,8 +25,14 @@ tags:
 
 `MetricMicroGrid` — six-cell dense overview pairing each KPI with a different lightweight visualization (bars / line / dots / progress / area / pie).
 
-**Layer:** `features`  
+**Layer:** `features`
 **Source:** `src/components/composed/analytics`
+**Consumer import:** `admin-ui-starter-kit/composed/analytics`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/composed/analytics`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
 ## Examples
 

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

@@ -20,6 +20,7 @@ examples:
 imports:
   - @/components/composed/analytics
   - @/components/typography
+publicImport: admin-ui-starter-kit/composed/analytics
 tags:
   - features
   - metrics
@@ -34,8 +35,14 @@ tags:
 
 The unified metrics module: a single Metric component with seven layout variants, plus MetricBar, MetricGrid, and supporting atoms (TrendChip, Sparkline, Skeleton). One MetricData shape powers every surface — see the dedicated pages for each layout.
 
-**Layer:** `features`  
+**Layer:** `features`
 **Source:** `src/components/composed/analytics`
+**Consumer import:** `admin-ui-starter-kit/composed/analytics`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/composed/analytics`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
 ## Examples
 

package/.agents/skills/component-library-rules/references/components/features__metrics-stat-cards.md

@@ -10,6 +10,7 @@ examples:
   - MetricColored
 imports:
   - @/components/composed/analytics
+publicImport: admin-ui-starter-kit/composed/analytics
 tags:
   - features
   - metrics
@@ -24,8 +25,14 @@ tags:
 
 Two stat tile flavors built from the unified `Metric` component — `accent` (dark surface + sparkline) and `colored` (segmented progress bar).
 
-**Layer:** `features`  
+**Layer:** `features`
 **Source:** `src/components/composed/analytics`
+**Consumer import:** `admin-ui-starter-kit/composed/analytics`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/composed/analytics`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
 ## Examples
 

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

@@ -1,6 +1,8 @@
 ---
 id: features/overlays
 title: "Features · Overlays"
+description: "Native dialog-backed Dialog, Drawer in four directions, and AlertDialog. Same emphasis/tone system, focus management, async-confirm flow, and confirm/cancel ergonomics across all three. Callback-driven so they slot into any framework."
+layer: features
 family: "Overlays"
 sourcePath: src/components/features/overlays
 examples:
@@ -16,17 +18,33 @@ imports:
   - @/components/base/badge
   - @/components/base/buttons
   - @/components/base/display/avatar
+  - @/components/base/forms
   - @/components/base/forms/fields
+  - @/components/base/item
   - @/components/features/overlays
   - @/components/typography
+publicImport: admin-ui-starter-kit/features/overlays
 tags:
-  - overlays
   - features
+  - overlays
+  - native
+  - dialog
+  - backed
+  - drawer
 ---
 
 # Features · Overlays
 
+Native dialog-backed Dialog, Drawer in four directions, and AlertDialog. Same emphasis/tone system, focus management, async-confirm flow, and confirm/cancel ergonomics across all three. Callback-driven so they slot into any framework.
+
+**Layer:** `features`
 **Source:** `src/components/features/overlays`
+**Consumer import:** `admin-ui-starter-kit/features/overlays`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/features/overlays`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
 ## Examples
 
@@ -50,7 +68,14 @@ import {
 import { Avatar, AvatarFallback } from '@/components/base/display/avatar';
 import { Badge } from '@/components/base/badge';
 import { Button } from '@/components/base/buttons';
+import { FormField } from '@/components/base/forms';
 import { Input } from '@/components/base/forms/fields';
+import {
+	Item,
+	ItemContent,
+	ItemMedia,
+	ItemTitle,
+} from '@/components/base/item';
 import { Text } from '@/components/typography';
 import { AlertDialog, Dialog, Drawer } from '@/components/features/overlays';
 
@@ -198,31 +223,28 @@ export function DialogFormPattern() {
 									}}
 									className="space-y-3"
 								>
-									<label className="block">
-										<Text tag="span" size="xs" weight="medium" className="block mb-1">Card number</Text>
+									<FormField label="Card number">
 										<Input
 											type="text"
 											placeholder="4242 4242 4242 4242"
 											className="font-mono tabular-nums"
 										/>
-									</label>
+									</FormField>
 									<div className="grid grid-cols-2 gap-3">
-										<label className="block">
-											<Text tag="span" size="xs" weight="medium" className="block mb-1">Expiry</Text>
+										<FormField label="Expiry">
 											<Input
 												type="text"
 												placeholder="MM / YY"
 												className="font-mono tabular-nums"
 											/>
-										</label>
-										<label className="block">
-											<Text tag="span" size="xs" weight="medium" className="block mb-1">CVC</Text>
+										</FormField>
+										<FormField label="CVC">
 											<Input
 												type="text"
 												placeholder="123"
 												className="font-mono tabular-nums"
 											/>
-										</label>
+										</FormField>
 									</div>
 								</form>
 							</Dialog>
@@ -293,10 +315,14 @@ export function Drawer4Directions() {
 										{ icon: CreditCard, label: 'Invoices' },
 										{ icon: Settings, label: 'Settings' },
 									].map((item) => (
-										<button key={item.label} className="flex w-full items-center gap-3 rounded-md px-3 py-2 text-left transition-colors hover:bg-muted/50">
-											<item.icon className="size-4 text-muted-foreground" />
-											<Text>{item.label}</Text>
-										</button>
+										<Item key={item.label} render={<button type="button" />} className="hover:bg-muted/50">
+											<ItemMedia variant="icon" className="text-muted-foreground">
+												<item.icon />
+											</ItemMedia>
+											<ItemContent>
+												<ItemTitle bold={false}>{item.label}</ItemTitle>
+											</ItemContent>
+										</Item>
 									))}
 								</nav>
 							</Drawer>
@@ -315,12 +341,18 @@ export function Drawer4Directions() {
 										{ icon: CreditCard, label: 'Record payment' },
 										{ icon: FileText, label: 'New booking' },
 									].map((a) => (
-										<button key={a.label} className="flex flex-col items-center gap-2 rounded-lg border border-border bg-card px-3 py-4 transition-colors hover:bg-muted/40">
+										<Button
+											key={a.label}
+											type="button"
+											variant="secondary"
+											buttonStyle="ghost"
+											className="h-auto flex-col gap-2 rounded-lg border border-border bg-card px-3 py-4 transition-colors hover:bg-muted/40"
+										>
 											<span className="inline-flex size-9 items-center justify-center rounded-lg bg-primary/10 text-primary">
 												<a.icon className="size-4" />
 											</span>
 											<Text size="xs" weight="medium" align="center">{a.label}</Text>
-										</button>
+										</Button>
 									))}
 								</div>
 							</Drawer>