admin-ui-starter-kit 0.1.4 → 0.4.2

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

@@ -0,0 +1,235 @@
+---
+id: base/frame
+title: "Frame"
+description: "Grouped panel primitive for related admin content, stacked records, and dense framed surfaces."
+layer: base
+family: "Foundations"
+sourcePath: src/components/base/frame
+examples:
+  - DefaultFrame
+  - StackedPanels
+  - InverseFrame
+  - DenseFitPanel
+  - FrameVariantMatrix
+imports:
+  - @/components/base/badge
+  - @/components/base/buttons
+  - @/components/base/frame
+  - @/components/base/item
+  - @/components/typography
+publicImport: admin-ui-starter-kit/base/frame
+tags:
+  - base
+  - foundations
+  - frame
+  - grouped
+  - panel
+  - primitive
+  - related
+---
+
+# Frame
+
+Grouped panel primitive for related admin content, stacked records, and dense framed surfaces.
+
+**Layer:** `base`
+**Source:** `src/components/base/frame`
+**Consumer import:** `admin-ui-starter-kit/base/frame`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/frame`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+`Frame` gives consumers a reusable grouping shell without reaching for ad hoc
+card divs. It owns the outer chrome and spacing tokens; `FramePanel` owns each
+inner surface. Use it when several related panels should read as one object.
+
+## Usage
+
+Import from the exact public entrypoint:
+
+```tsx
+import {
+	Frame,
+	FramePanel,
+	FrameHeader,
+	FrameTitle,
+	FrameDescription,
+	FrameFooter,
+} from 'admin-ui-starter-kit/base/frame';
+```
+
+Use `Frame` for related admin panels that need one shared boundary. Use
+`FramePanel` for each contained surface, `fit` when media or charts should
+touch the panel edge, `stacked` when panels should collapse into one segmented
+record, and `dense` for table-adjacent or settings-row layouts. The default
+`spacing` follows `useCardConfig().defaultPadding`; pass `spacing` only when a
+surface needs to override the provider default.
+
+## Examples
+
+```tsx
+import { Activity, BadgeCheck, CreditCard, Database, ShieldCheck } from 'lucide-react';
+
+import {
+	Frame,
+	FrameDescription,
+	FrameFooter,
+	FrameHeader,
+	FramePanel,
+	FrameTitle,
+} from '@/components/base/frame';
+import {
+	Item,
+	ItemActions,
+	ItemContent,
+	ItemDescription,
+	ItemMedia,
+	ItemTitle,
+} from '@/components/base/item';
+import { Badge } from '@/components/base/badge';
+import { Button } from '@/components/base/buttons';
+import { Text } from '@/components/typography';
+
+const systemRows = [
+	{ id: 'sync', title: 'Catalog sync', description: 'Last completed 8 minutes ago', icon: Database, badge: 'Healthy' },
+	{ id: 'payments', title: 'Payments', description: 'Stripe webhooks are processing normally', icon: CreditCard, badge: 'Live' },
+	{ id: 'security', title: 'Security review', description: '2 team members need SSO confirmation', icon: ShieldCheck, badge: 'Review' },
+];
+
+const frameMatrix = [
+	{ variant: 'default', spacing: 'xs', title: 'Default / xs' },
+	{ variant: 'inverse', spacing: 'sm', title: 'Inverse / sm' },
+	{ variant: 'ghost', spacing: 'base', title: 'Ghost / base' },
+	{ variant: 'default', spacing: 'lg', title: 'Default / lg' },
+] as const;
+
+export function DefaultFrame() {
+	return (
+		<Frame className="w-full max-w-xl">
+			<FrameHeader>
+				<FrameTitle>Workspace health</FrameTitle>
+				<FrameDescription>Grouped panels with one shared outer frame.</FrameDescription>
+			</FrameHeader>
+			<FramePanel>
+				<div className="grid gap-3 sm:grid-cols-3">
+					<div>
+						<Text size="xs" type="secondary">Uptime</Text>
+						<Text weight="semibold">99.98%</Text>
+					</div>
+					<div>
+						<Text size="xs" type="secondary">Open alerts</Text>
+						<Text weight="semibold">3</Text>
+					</div>
+					<div>
+						<Text size="xs" type="secondary">Queued jobs</Text>
+						<Text weight="semibold">18</Text>
+					</div>
+				</div>
+			</FramePanel>
+			<FrameFooter>
+				<Text size="xs" type="secondary">Updated just now</Text>
+			</FrameFooter>
+		</Frame>
+	);
+}
+
+export function StackedPanels() {
+	return (
+		<Frame stacked spacing="sm" className="w-full max-w-xl">
+			{systemRows.map((row) => {
+				const Icon = row.icon;
+				return (
+					<FramePanel key={row.id}>
+						<Item className="rounded-none p-0">
+							<ItemMedia variant="icon">
+								<Icon />
+							</ItemMedia>
+							<ItemContent>
+								<ItemTitle>{row.title}</ItemTitle>
+								<ItemDescription>{row.description}</ItemDescription>
+							</ItemContent>
+							<ItemActions>
+								<Badge variant={row.badge === 'Review' ? 'warning' : 'success'}>{row.badge}</Badge>
+							</ItemActions>
+						</Item>
+					</FramePanel>
+				);
+			})}
+		</Frame>
+	);
+}
+
+export function InverseFrame() {
+	return (
+		<Frame variant="inverse" spacing="base" className="w-full max-w-xl">
+			<FramePanel>
+				<div className="flex items-start justify-between gap-3">
+					<div className="space-y-1">
+						<Text size="xs" type="secondary">Monthly automation run</Text>
+						<Text weight="semibold">12,842 tasks completed</Text>
+						<Text size="xs" type="secondary">Average queue latency is down 18% from last week.</Text>
+					</div>
+					<Badge variant="info">
+						<Activity className="size-3" />
+						Live
+					</Badge>
+				</div>
+			</FramePanel>
+		</Frame>
+	);
+}
+
+export function DenseFitPanel() {
+	return (
+		<Frame dense className="w-full max-w-xl">
+			<FramePanel fit>
+				<div className="grid grid-cols-[1fr_auto] items-center gap-3 px-3 py-2">
+					<div className="flex items-center gap-2">
+						<BadgeCheck className="size-4 text-success" />
+						<Text weight="semibold">Payout batch approved</Text>
+					</div>
+					<Button variant="secondary" buttonStyle="ghost">View</Button>
+				</div>
+			</FramePanel>
+		</Frame>
+	);
+}
+
+export function FrameVariantMatrix() {
+	return (
+		<div className="grid w-full gap-3 md:grid-cols-2">
+			{frameMatrix.map((item) => (
+				<Frame
+					key={`${item.variant}-${item.spacing}`}
+					variant={item.variant}
+					spacing={item.spacing}
+				>
+					<FrameHeader>
+						<FrameTitle>{item.title}</FrameTitle>
+						<FrameDescription>Provider-aware spacing with stable frame hooks.</FrameDescription>
+					</FrameHeader>
+					<FramePanel>
+						<div className="flex items-center justify-between gap-3">
+							<Text size="xs" type="secondary">Review queue</Text>
+							<Badge variant={item.variant === 'ghost' ? 'secondary' : 'info'}>12 open</Badge>
+						</div>
+					</FramePanel>
+				</Frame>
+			))}
+		</div>
+	);
+}
+```
+
+## Example exports
+
+- `DefaultFrame`
+- `StackedPanels`
+- `InverseFrame`
+- `DenseFitPanel`
+- `FrameVariantMatrix`
+

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

@@ -14,6 +14,7 @@ imports:
   - @/components/base/buttons
   - @/components/base/forms/fields/switch
   - @/components/base/item
+publicImport: admin-ui-starter-kit/base/item
 tags:
   - base
   - foundations
@@ -28,8 +29,53 @@ tags:
 
 Canonical row primitive — icon/avatar/image media, title + description content, optional actions. Use ItemGroup to compose lists.
 
-**Layer:** `base`  
+**Layer:** `base`
 **Source:** `src/components/base/item`
+**Consumer import:** `admin-ui-starter-kit/base/item`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/item`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+`Item` is the row primitive used everywhere a "media + title-stack + actions"
+shape recurs — admin rows, contact details, search results, settings toggles,
+dropdown menus. Compose `ItemMedia`, `ItemContent` (with `ItemTitle` and
+`ItemDescription`), and `ItemActions` inside an `Item`. Wrap multiple rows in
+`ItemGroup` (with optional `ItemSeparator`s between them) for a list.
+
+The `render` prop turns any `Item` into a custom element (anchor, button, link
+wrapper) without breaking focus/hover styling.
+
+## Consumer usage
+
+Consumers import the row primitive from the exact package entrypoint:
+
+```tsx
+import {
+	Item,
+	ItemActions,
+	ItemContent,
+	ItemDescription,
+	ItemGroup,
+	ItemMedia,
+	ItemTitle,
+} from 'admin-ui-starter-kit/base/item';
+```
+
+Promote `Item` first whenever the row has its own identity: navigation rows,
+settings rows, search results, contact methods, activity rows, menu options, or
+any media + title + description + actions shape. `ItemTitle` and
+`ItemDescription` already route through the typography layer, so consumers do
+not need local text utility classes for the row stack.
+
+Use `MetadataList` instead when the rows are label/value facts describing one
+entity, such as invoice totals, SKU attributes, contact metadata, or account
+properties. Use `FormField` when the row contains a form control. If each row
+can be clicked, selected, toggled, or acted on independently, it is probably an
+`Item`.
 
 ## Examples
 

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

@@ -12,6 +12,7 @@ examples:
   - CompactSize
 imports:
   - @/components/base/map
+publicImport: admin-ui-starter-kit/base/map
 tags:
   - base
   - navigation
@@ -27,8 +28,43 @@ tags:
 
 Leaflet-backed map primitives — Map shell, MapTileLayer, MapMarker, MapPopup. Always wrap in a fixed-height container.
 
-**Layer:** `base`  
+**Layer:** `base`
 **Source:** `src/components/base/map`
+**Consumer import:** `admin-ui-starter-kit/base/map`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/map`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+The map components are thin React wrappers around Leaflet. Always wrap a
+`<Map>` in a parent with a fixed height (Leaflet renders absolute children).
+Compose `<MapTileLayer />` for the basemap, `<MapMarker>` for a pin, and
+`<MapPopup>` inside a marker for the click bubble.
+
+## Default
+
+<Example name="Default" source={examplesSource}>
+	<Examples.Default />
+</Example>
+
+## Multiple markers
+
+<Example name="MultipleMarkers" source={examplesSource}>
+	<Examples.MultipleMarkers />
+</Example>
+
+## Sizes & zoom
+
+<Example name="TighterZoom" source={examplesSource}>
+	<Examples.TighterZoom />
+</Example>
+
+<Example name="CompactSize" source={examplesSource}>
+	<Examples.CompactSize />
+</Example>
 
 ## Examples
 

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

@@ -3,7 +3,6 @@ id: base/metadata-list
 title: "Metadata list"
 description: "Flexible label/value list for entity metadata. Three layouts (vertical grid, horizontal pills, two-column rows), per-item icons, tooltips, descriptions, and custom renderers — with first-class empty-state handling."
 layer: base
-family: "Data display"
 sourcePath: src/components/base/display/metadata
 examples:
   - APISurface
@@ -20,14 +19,14 @@ examples:
   - EmptyStateFallbacksCustomRenderers
 imports:
   - @/components/base/badge
+  - @/components/base/buttons
   - @/components/base/cards
   - @/components/base/display/avatar
   - @/components/base/display/metadata
   - @/components/typography
+publicImport: admin-ui-starter-kit/base/display/metadata
 tags:
   - base
-  - data
-  - display
   - metadata
   - list
   - flexible
@@ -39,8 +38,97 @@ tags:
 
 Flexible label/value list for entity metadata. Three layouts (vertical grid, horizontal pills, two-column rows), per-item icons, tooltips, descriptions, and custom renderers — with first-class empty-state handling.
 
-**Layer:** `base`  
+**Layer:** `base`
 **Source:** `src/components/base/display/metadata`
+**Consumer import:** `admin-ui-starter-kit/base/display/metadata`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/display/metadata`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+`MetadataList` renders an array of `{ id, label, value, icon?, tooltip?,
+description?, render?, emptyLabel? }` items. List-level props pick the
+`layout` (`vertical` / `rows` / `horizontal`), the `columns` count (1–4),
+and density. Per-item `render` escapes the default formatting for status
+pills, copyable IDs, links, or inline edits.
+
+## Consumer usage
+
+Consumers import metadata primitives from the exact nested package entrypoint:
+
+```tsx
+import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
+```
+
+Use `MetadataList` for compact facts about a single entity: label/value
+attributes, receipt rows, account properties, audit details, or operational
+summaries. It is intentionally read-heavy and scan-first.
+
+Use `Item` instead when each row represents a separate object or action with a
+title stack, media, and trailing controls. Use `FormField` when the row contains
+an editable input. Metadata is for describing an entity; Item is for listing
+entities or actions.
+
+## API surface
+
+<Example name="APISurface" source={examplesSource}>
+	<Examples.APISurface />
+</Example>
+
+## Vertical grid
+
+<Example name="Vertical2ColumnNoIcons" source={examplesSource}>
+	<Examples.Vertical2ColumnNoIcons />
+</Example>
+
+<Example name="VerticalSingleColumnNoIcons" source={examplesSource}>
+	<Examples.VerticalSingleColumnNoIcons />
+</Example>
+
+<Example name="Example3ColumnWithIcons" source={examplesSource}>
+	<Examples.Example3ColumnWithIcons />
+</Example>
+
+<Example name="Dense4ColumnOverview" source={examplesSource}>
+	<Examples.Dense4ColumnOverview />
+</Example>
+
+## Two-column rows
+
+<Example name="RowsTwoColumnWithHairlines" source={examplesSource}>
+	<Examples.RowsTwoColumnWithHairlines />
+</Example>
+
+<Example name="RowsReceiptStyle" source={examplesSource}>
+	<Examples.RowsReceiptStyle />
+</Example>
+
+<Example name="RowsWithIconsTooltips" source={examplesSource}>
+	<Examples.RowsWithIconsTooltips />
+</Example>
+
+## Horizontal pills
+
+<Example name="HorizontalPillSummary" source={examplesSource}>
+	<Examples.HorizontalPillSummary />
+</Example>
+
+## Composition
+
+<Example name="SectionedMultiCard" source={examplesSource}>
+	<Examples.SectionedMultiCard />
+</Example>
+
+<Example name="WithTitleSeparator" source={examplesSource}>
+	<Examples.WithTitleSeparator />
+</Example>
+
+<Example name="EmptyStateFallbacksCustomRenderers" source={examplesSource}>
+	<Examples.EmptyStateFallbacksCustomRenderers />
+</Example>
 
 ## Examples
 
@@ -67,6 +155,7 @@ import {
 } from 'lucide-react';
 import { Avatar, AvatarFallback } from '@/components/base/display/avatar';
 import { Badge } from '@/components/base/badge';
+import { Button } from '@/components/base/buttons';
 import { SmartCard } from '@/components/base/cards';
 import { MetadataList, type MetadataListItem } from '@/components/base/display/metadata';
 import { Text } from '@/components/typography';
@@ -76,14 +165,17 @@ import { Text } from '@/components/typography';
 function CopyableValue({ value, mono = true }: { value: string; mono?: boolean }) {
 	const [copied, setCopied] = useState(false);
 	return (
-		<button
+		<Button
 			type="button"
+			variant="secondary"
+			buttonStyle="ghost"
+			size="xs"
 			onClick={() => {
 				try { navigator.clipboard.writeText(value); } catch { /* ignore */ }
 				setCopied(true);
 				setTimeout(() => setCopied(false), 1200);
 			}}
-			className="group inline-flex items-center gap-1.5 rounded-md px-1 py-0.5 -ml-1 transition-colors hover:bg-muted/60"
+			className="group -ml-1 h-auto gap-1.5 rounded-md px-1 py-0.5 shadow-none transition-colors hover:bg-muted/60"
 			title="Copy to clipboard"
 		>
 			<Text tag="span" weight="medium" className={mono ? 'font-mono tabular-nums' : 'tabular-nums'}>{value}</Text>
@@ -92,7 +184,7 @@ function CopyableValue({ value, mono = true }: { value: string; mono?: boolean }
 			) : (
 				<Copy className="size-3 text-muted-foreground/50 opacity-0 transition-opacity group-hover:opacity-100" aria-hidden="true" />
 			)}
-		</button>
+		</Button>
 	);
 }
 

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

@@ -29,6 +29,7 @@ imports:
   - @/components/base/navigation/section-nav
   - @/components/base/navigation/side-nav
   - @/components/base/navigation/tab-navigation-menu
+publicImport: admin-ui-starter-kit/base/navigation
 tags:
   - base
   - navigation
@@ -43,8 +44,77 @@ tags:
 
 The navigation primitives — PageHeader, Breadcrumbs, ActionMenu, LanguageSwitcher, SectionNav, SideNav, AsideNavigationMenu, TabNavigationMenu, NavigationTabs, OverflowTabBar.
 
-**Layer:** `base`  
+**Layer:** `base`
 **Source:** `src/components/base/navigation`
+**Consumer import:** `admin-ui-starter-kit/base/navigation`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/navigation`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+The `navigation/` folder bundles every cross-cutting nav surface — page
+headers, breadcrumb trails, side rails, tab bars, action menus, and the
+language switcher. All components are framework-agnostic — pass `href`s and
+let the consumer wire routing.
+
+## Page header
+
+<Example name="PageHeaderExample" source={examplesSource}>
+	<Examples.PageHeaderExample />
+</Example>
+
+## Breadcrumbs
+
+<Example name="BreadcrumbsSizes" source={examplesSource}>
+	<Examples.BreadcrumbsSizes />
+</Example>
+
+## Tabs
+
+<Example name="TabNavigationMenuExample" source={examplesSource}>
+	<Examples.TabNavigationMenuExample />
+</Example>
+
+<Example name="NavigationTabsRound" source={examplesSource}>
+	<Examples.NavigationTabsRound />
+</Example>
+
+<Example name="OverflowTabBarResponsiveWithMoreMenu" source={examplesSource}>
+	<Examples.OverflowTabBarResponsiveWithMoreMenu />
+</Example>
+
+## Side nav & section nav
+
+<Example name="AsideNavigationMenuExample" source={examplesSource}>
+	<Examples.AsideNavigationMenuExample />
+</Example>
+
+<Example name="SideNavCollapsibleGroups" source={examplesSource}>
+	<Examples.SideNavCollapsibleGroups />
+</Example>
+
+<Example name="SectionNavSticky" source={examplesSource}>
+	<Examples.SectionNavSticky />
+</Example>
+
+## Action menu
+
+<Example name="ActionMenuExample" source={examplesSource}>
+	<Examples.ActionMenuExample />
+</Example>
+
+## Language switcher
+
+<Example name="LanguageSwitcherButtons" source={examplesSource}>
+	<Examples.LanguageSwitcherButtons />
+</Example>
+
+<Example name="LanguageSwitcherInline" source={examplesSource}>
+	<Examples.LanguageSwitcherInline />
+</Example>
 
 ## Examples
 

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

@@ -3,7 +3,6 @@ id: base/spinner
 title: "Spinner"
 description: "Loading indicator with three visual variants. Pairs with content placeholders, route transitions, and Suspense fallbacks."
 layer: base
-family: "Feedback"
 sourcePath: src/components/base/spinner
 examples:
   - Default
@@ -13,9 +12,9 @@ examples:
   - SectionPlaceholder
 imports:
   - @/components/base/spinner
+publicImport: admin-ui-starter-kit/base/spinner
 tags:
   - base
-  - feedback
   - spinner
   - loading
   - indicator
@@ -27,8 +26,50 @@ tags:
 
 Loading indicator with three visual variants. Pairs with content placeholders, route transitions, and Suspense fallbacks.
 
-**Layer:** `base`  
+**Layer:** `base`
 **Source:** `src/components/base/spinner`
+**Consumer import:** `admin-ui-starter-kit/base/spinner`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/spinner`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+`Spinner` ships three variants — `default` (rotating SVG), `shimmer` (round
+shimmer dot), `progress` (slim animated bar). The variant resolves through
+`useSpinnerConfig().defaultVariant`, so a consumer can pin the look at the
+`UIProvider` root and override per call. Pass an optional `label` for screen
+readers and a visible status message.
+
+## Default
+
+<Example name="Default" source={examplesSource}>
+	<Examples.Default />
+</Example>
+
+## Variants
+
+<Example name="Variants" source={examplesSource}>
+	<Examples.Variants />
+</Example>
+
+## Composition
+
+<Example name="WithLabel" source={examplesSource}>
+	<Examples.WithLabel />
+</Example>
+
+<Example name="CustomColour" source={examplesSource}>
+	<Examples.CustomColour />
+</Example>
+
+## Realistic usage
+
+<Example name="SectionPlaceholder" source={examplesSource}>
+	<Examples.SectionPlaceholder />
+</Example>
 
 ## Examples