admin-ui-starter-kit 0.1.3 → 0.4.2

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
 

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

@@ -27,6 +27,7 @@ imports:
   - @/components/base/table/pagination
   - @/components/typography
   - @/preview/_mocks
+publicImport: admin-ui-starter-kit/base/table
 tags:
   - base
   - navigation
@@ -42,15 +43,115 @@ tags:
 
 DataTable + Pagination — TanStack-React-Table-backed, with sorting, row actions, sticky header, three sizes, and three surface chromes.
 
-**Layer:** `base`  
+**Layer:** `base`
 **Source:** `src/components/base/table`
+**Consumer import:** `admin-ui-starter-kit/base/table`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/table`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+`DataTable<T>` wraps `@tanstack/react-table` with our typography, density,
+and surface tokens. Pass `columns` (typed against your row shape) and `data`,
+optionally enable `sorting`, supply `rowActions`, and tune `size` (xs / sm /
+base) and `surface` (card / glass / flat). Pair with `Pagination` for the
+canonical Laravel-paginator shape.
+
+## Default
+
+<Example name="BasicDefaultSizeXsCompact" source={examplesSource}>
+	<Examples.BasicDefaultSizeXsCompact />
+</Example>
+
+## Sizes
+
+<Example name="SizeSm" source={examplesSource}>
+	<Examples.SizeSm />
+</Example>
+
+<Example name="SizeBase" source={examplesSource}>
+	<Examples.SizeBase />
+</Example>
+
+## Surfaces
+
+<Example name="SurfaceGlassHeaderTransparentCleanOutlineNoMutedHeader" source={examplesSource}>
+	<Examples.SurfaceGlassHeaderTransparentCleanOutlineNoMutedHeader />
+</Example>
+
+<Example name="SurfaceFlatInsideSmartCardTableRendersNoChrome" source={examplesSource}>
+	<Examples.SurfaceFlatInsideSmartCardTableRendersNoChrome />
+</Example>
+
+<Example name="SizeSmGlassExplicitCellTextScaling" source={examplesSource}>
+	<Examples.SizeSmGlassExplicitCellTextScaling />
+</Example>
+
+## Features
+
+<Example name="WithSortingRowActions" source={examplesSource}>
+	<Examples.WithSortingRowActions />
+</Example>
+
+## Cell renderers
+
+`StatusCell`, `DateCell`, `CurrencyCell`, and `AvatarCell` are reusable
+column-cell renderers exported from `base/table`. Compose them inside your
+column `cell` function to keep the table look consistent.
+
+<Example name="CellRenderers" source={examplesSource}>
+	<Examples.CellRenderers />
+</Example>
+
+## Selection
+
+<Example name="WithRowSelection" source={examplesSource}>
+	<Examples.WithRowSelection />
+</Example>
+
+## Toolbar
+
+<Example name="WithColumnVisibility" source={examplesSource}>
+	<Examples.WithColumnVisibility />
+</Example>
+
+<Example name="WithCustomToolbar" source={examplesSource}>
+	<Examples.WithCustomToolbar />
+</Example>
+
+## Sticky
+
+<Example name="StickyHeaderAndFirstColumn" source={examplesSource}>
+	<Examples.StickyHeaderAndFirstColumn />
+</Example>
+
+## States
+
+<Example name="EmptyState" source={examplesSource}>
+	<Examples.EmptyState />
+</Example>
+
+## Pagination
+
+<Example name="PaginationExample" source={examplesSource}>
+	<Examples.PaginationExample />
+</Example>
+
+## Realistic usage
+
+<Example name="RealisticOrdersTable" source={examplesSource}>
+	<Examples.RealisticOrdersTable />
+</Example>
 
 ## Examples
 
 ```tsx
 import { useState } from 'react';
 import { type ColumnDef, type RowSelectionState } from '@tanstack/react-table';
-import { Edit, Trash2, ShoppingBag, Calendar, Mail, CheckCircle2, Clock, XCircle, Truck } from 'lucide-react';
+import { Edit, Trash2, ShoppingBag, CheckCircle2, Clock, XCircle, Truck } from 'lucide-react';
 import {
 	DataTable,
 	StatusCell,
@@ -98,16 +199,12 @@ const columns: ColumnDef<Order>[] = [
 	{
 		accessorKey: 'customer',
 		header: 'Customer',
-		cell: ({ row }) => (
-			<div className="flex items-center gap-1.5">
-				<Mail className="size-3 text-muted-foreground" />
-				<Text tag="span" size="inherit">{row.original.customer}</Text>
-			</div>
-		),
+		cell: ({ row }) => <AvatarCell name={row.original.customer} />,
 	},
 	{
 		accessorKey: 'amount',
 		header: 'Amount',
+		meta: { align: 'end' },
 		cell: ({ getValue }) => (
 			<Text tag="span" size="inherit" weight="semibold" className="tabular-nums">
 				{String(getValue())}
@@ -127,12 +224,9 @@ const columns: ColumnDef<Order>[] = [
 		accessorKey: 'date',
 		header: 'Date',
 		cell: ({ getValue }) => (
-			<div className="flex items-center gap-1 text-muted-foreground">
-				<Calendar className="size-3" />
-				<Text tag="span" size="inherit" type="secondary" className="tabular-nums">
-					{String(getValue())}
-				</Text>
-			</div>
+			<Text tag="span" size="inherit" type="secondary" className="tabular-nums">
+				{String(getValue())}
+			</Text>
 		),
 	},
 ];
@@ -177,7 +271,7 @@ export function SurfaceGlassHeaderTransparentCleanOutlineNoMutedHeader() {
 export function SurfaceFlatInsideSmartCardTableRendersNoChrome() {
 	return (
 		<>
-			<div className="rounded-lg border border-border bg-card p-1">
+			<div className="w-full min-w-0 max-w-full overflow-hidden rounded-lg border border-border bg-card p-1">
 								<DataTable<Order>
 									columns={columns}
 									data={data}
@@ -346,7 +440,7 @@ export function CellRenderers() {
 export function WithRowSelection() {
 	const [selection, setSelection] = useState<RowSelectionState>({});
 	return (
-		<div className="flex flex-col gap-2">
+		<div className="flex w-full min-w-0 max-w-full flex-col gap-2 overflow-hidden">
 			<DataTable<Order>
 				columns={columns}
 				data={data}

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

@@ -23,11 +23,13 @@ examples:
   - DangerousHTMLExample
   - RealisticArticle
 imports:
+  - @/components/base/forms/fields
   - @/components/typography/heading
   - @/components/typography/label
   - @/components/typography/text
   - @/components/typography/text-link
   - @/components/typography/typography
+publicImport: admin-ui-starter-kit/typography
 tags:
   - base
   - foundations
@@ -42,8 +44,128 @@ tags:
 
 Heading, Text, Label, and TextLink — the four typography primitives every higher layer composes from.
 
-**Layer:** `base`  
+**Layer:** `base`
 **Source:** `src/components/typography`
+**Consumer import:** `admin-ui-starter-kit/typography`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/typography`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+The typography layer is intentionally tiny. `Heading` (h1–h6, optional
+`subHeading`), `Text` (six sizes, seven types, four weights, optional `asHTML`),
+`Label` (form captions), and `TextLink` (anchor sibling of `Text`) cover every
+typographic decision in the library. Anything outside the `typography/` folder
+that reaches for a font-size class is doing it wrong.
+
+## Consumer usage
+
+Consumers import typography from the top-level exact package entrypoint:
+
+```tsx
+import { Heading, Label, Text, TextLink } from 'admin-ui-starter-kit/typography';
+```
+
+Use `Text` for ordinary body, labels, metadata, helper copy, and inline
+messages. Omit `size` for normal body text so the `UIProvider` typography
+default can flow through; reach for `size="xs" type="secondary"` for secondary
+details and `size="xxs" type="secondary"` for dense micro labels. Use
+`weight="semibold"` instead of local font-weight classes.
+
+Use `Heading` for page or section headings, `Label` for form captions, and
+`TextLink` for inline links that need the same sizing and tone controls as
+`Text`. Do not hand-roll typography with raw `text-sm`, `text-xs`,
+`font-semibold`, or muted color utilities in consumer surfaces.
+
+## Heading
+
+<Example name="HeadingTags" source={examplesSource}>
+	<Examples.HeadingTags />
+</Example>
+
+<Example name="HeadingWithSubHeading" source={examplesSource}>
+	<Examples.HeadingWithSubHeading />
+</Example>
+
+## Text — sizes
+
+<Example name="TextSizes" source={examplesSource}>
+	<Examples.TextSizes />
+</Example>
+
+## Text — types & weights
+
+<Example name="TextTypes" source={examplesSource}>
+	<Examples.TextTypes />
+</Example>
+
+<Example name="TextWeights" source={examplesSource}>
+	<Examples.TextWeights />
+</Example>
+
+## Text — layout
+
+<Example name="TextLineHeights" source={examplesSource}>
+	<Examples.TextLineHeights />
+</Example>
+
+<Example name="TextAlignment" source={examplesSource}>
+	<Examples.TextAlignment />
+</Example>
+
+<Example name="TextTags" source={examplesSource}>
+	<Examples.TextTags />
+</Example>
+
+## Text — content prop & HTML
+
+<Example name="TextContentAndHTML" source={examplesSource}>
+	<Examples.TextContentAndHTML />
+</Example>
+
+## Label
+
+<Example name="LabelExample" source={examplesSource}>
+	<Examples.LabelExample />
+</Example>
+
+## TextLink
+
+<Example name="TextLinkVariants" source={examplesSource}>
+	<Examples.TextLinkVariants />
+</Example>
+
+<Example name="TextLinkSizes" source={examplesSource}>
+	<Examples.TextLinkSizes />
+</Example>
+
+## Inline helpers — HighLight & Underline
+
+The `HighLight` and `Underline` helpers (from `@/components/typography/typography`)
+render small inline accents in four variants — `primary`, `success`,
+`warning`, `error`. `DangerousHTML` is the sanitised escape-hatch when you
+must render server-trusted HTML.
+
+<Example name="HighLightExample" source={examplesSource}>
+	<Examples.HighLightExample />
+</Example>
+
+<Example name="UnderlineExample" source={examplesSource}>
+	<Examples.UnderlineExample />
+</Example>
+
+<Example name="DangerousHTMLExample" source={examplesSource}>
+	<Examples.DangerousHTMLExample />
+</Example>
+
+## Realistic usage
+
+<Example name="RealisticArticle" source={examplesSource}>
+	<Examples.RealisticArticle />
+</Example>
 
 ## Examples
 
@@ -53,6 +175,7 @@ import { Text } from '@/components/typography/text';
 import Label from '@/components/typography/label';
 import TextLink from '@/components/typography/text-link';
 import { HighLight, Underline, DangerousHTML } from '@/components/typography/typography';
+import { Input } from '@/components/base/forms/fields';
 
 const SIZES = ['xxs', 'xs', 'sm', 'base', 'lg', 'xl'] as const;
 const TYPES = ['main', 'inverse', 'secondary', 'discrete', 'error', 'success', 'primary'] as const;
@@ -170,12 +293,12 @@ export function LabelExample() {
 	return (
 		<div className="flex flex-col gap-3 w-full max-w-sm">
 			<div className="space-y-1">
-				<Label>Email address</Label>
-				<input className="w-full rounded border border-border bg-background px-2 py-1.5 text-sm" placeholder="you@example.com" />
+				<Label htmlFor="typography-email">Email address</Label>
+				<Input id="typography-email" placeholder="you@example.com" />
 			</div>
 			<div className="space-y-1">
-				<Label className="text-primary">Custom-coloured label</Label>
-				<input className="w-full rounded border border-border bg-background px-2 py-1.5 text-sm" />
+				<Label htmlFor="typography-custom-label" className="text-primary">Custom-coloured label</Label>
+				<Input id="typography-custom-label" />
 			</div>
 		</div>
 	);

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

@@ -13,6 +13,7 @@ examples:
   - LocalisedFrench
 imports:
   - @/components/base/forms/fields
+publicImport: admin-ui-starter-kit/base/forms
 tags:
   - base
   - forms
@@ -28,8 +29,49 @@ tags:
 
 Drag-drop area + per-file progress rows + summary toolbar. Composes Dropzone and UploadProgressList. Framework-agnostic — the consumer drives the actual transfer.
 
-**Layer:** `base`  
+**Layer:** `base`
 **Source:** `src/components/base/forms/fields`
+**Consumer import:** `admin-ui-starter-kit/base/forms`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/forms`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+`UploadTray` is the canonical drop-and-progress surface. The consumer owns
+the items array (status + progress) and wires `onAddFiles`, `onRetry`,
+`onRemove`, and `onClearAll` to their transfer mechanism. Every string is
+overridable via `strings`, `listStrings`, and `dropzone.strings`.
+
+## Default
+
+<Example name="Default" source={examplesSource}>
+	<Examples.Default />
+</Example>
+
+## States
+
+<Example name="EmptyDropzoneOnly" source={examplesSource}>
+	<Examples.EmptyDropzoneOnly />
+</Example>
+
+<Example name="MixedItemStates" source={examplesSource}>
+	<Examples.MixedItemStates />
+</Example>
+
+## Realistic usage
+
+<Example name="LiveSimulatedUpload" source={examplesSource}>
+	<Examples.LiveSimulatedUpload />
+</Example>
+
+## Localisation
+
+<Example name="LocalisedFrench" source={examplesSource}>
+	<Examples.LocalisedFrench />
+</Example>
 
 ## Examples
 

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

@@ -1,7 +1,7 @@
 ---
 id: common/brand
 title: "Common · Brand"
-description: "Logo + AppLogo (sized variants). Source images expected at /assets/media/gct-logo[-light].png."
+description: "Inline Logo + AppLogo variants used by the preview shell."
 layer: common
 family: "Branding"
 sourcePath: src/preview/_brand
@@ -17,16 +17,16 @@ tags:
   - branding
   - _brand
   - brand
+  - inline
   - logo
   - applogo
-  - sized
 ---
 
 # Common · Brand
 
-Logo + AppLogo (sized variants). Source images expected at /assets/media/gct-logo[-light].png.
+Inline Logo + AppLogo variants used by the preview shell.
 
-**Layer:** `common`  
+**Layer:** `common`
 **Source:** `src/preview/_brand`
 
 ## Examples
@@ -38,37 +38,33 @@ import { Row, Col } from '../../PreviewLayout';
 
 export function LogoExample() {
 	return (
-		<>
-			<Col>
-								<Logo className="w-40 h-auto" />
-								<Logo className="w-40 h-auto" inverted />
-							</Col>
-		</>
+		<Col>
+			<Logo className="w-40" />
+			<div className="w-fit rounded-md bg-foreground p-3">
+				<Logo className="w-40" inverted />
+			</div>
+		</Col>
 	);
 }
 
 export function AppLogoSizes() {
 	return (
-		<>
-			<Row>
-								<AppLogo size="small" />
-								<AppLogo size="medium" />
-								<AppLogo size="large" />
-							</Row>
-		</>
+		<Row>
+			<AppLogo size="small" />
+			<AppLogo size="medium" />
+			<AppLogo size="large" />
+		</Row>
 	);
 }
 
 export function AppLogoVariants() {
 	return (
-		<>
-			<Row>
-								<AppLogo variant="dark" />
-								<div className="rounded-md bg-foreground p-3">
-									<AppLogo variant="light" />
-								</div>
-							</Row>
-		</>
+		<Row>
+			<AppLogo variant="dark" />
+			<div className="w-fit rounded-md bg-foreground p-3">
+				<AppLogo variant="light" />
+			</div>
+		</Row>
 	);
 }
 ```

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

@@ -18,6 +18,7 @@ imports:
   - @/components/composed/admin/role-permission
   - @/components/composed/admin/settings-toggle
   - @/components/composed/admin/team-member
+publicImport: admin-ui-starter-kit/composed/admin
 tags:
   - composed
   - admin
@@ -31,8 +32,14 @@ tags:
 
 Team list, permissions, conversations, settings, inventory.
 
-**Layer:** `composed`  
+**Layer:** `composed`
 **Source:** `src/components/composed/admin`
+**Consumer import:** `admin-ui-starter-kit/composed/admin`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/composed/admin`.
+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/composed__ai-elements.md

@@ -23,6 +23,7 @@ examples:
 imports:
   - @/components/composed/ai
   - @/components/typography
+publicImport: admin-ui-starter-kit/composed/ai
 tags:
   - composed
   - ai
@@ -36,8 +37,14 @@ tags:
 
 Standalone surfaces ported from elements.ai-sdk.dev: shimmer, code-block, agent, package-info, reasoning, chain-of-thought, sources, inline-citation, task, artifact, file-tree, confirmation, attachment.
 
-**Layer:** `composed`  
+**Layer:** `composed`
 **Source:** `src/components/composed/ai`
+**Consumer import:** `admin-ui-starter-kit/composed/ai`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/composed/ai`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
 ## Examples
 
@@ -74,10 +81,18 @@ export function Counter() {
 const SHELL_SAMPLE = `pnpm install admin-ui-starter-kit
 pnpm add -D tailwindcss@^4 @tailwindcss/vite`;
 
+const VITE_FAVICON = `data:image/svg+xml,${encodeURIComponent(`
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 40">
+	<rect width="40" height="40" rx="10" fill="#646cff"/>
+	<path d="M10 9h20l-10 22L10 9Z" fill="#fff"/>
+	<path d="M20 9h10L20 31V9Z" fill="#ffd62e" opacity=".9"/>
+</svg>
+`)}`;
+
 export function AiShimmerExample() {
 	return (
 		<>
-			<div className="flex flex-col gap-3">
+			<div className="flex w-full min-w-0 max-w-full flex-col gap-3">
 								<AiShimmer>Generating insights…</AiShimmer>
 								<AiShimmer paused>Paused</AiShimmer>
 							</div>
@@ -88,7 +103,7 @@ export function AiShimmerExample() {
 export function AiAgentExample() {
 	return (
 		<>
-			<div className="flex flex-col gap-3">
+			<div className="flex w-full min-w-0 max-w-full flex-col gap-3">
 								<AiAgent name="Atlas" subtitle="claude-4.7-1m" status="thinking" icon={Bot} />
 								<AiAgent
 									name="Helios"
@@ -107,7 +122,7 @@ export function AiAgentExample() {
 export function AiCodeBlockExample() {
 	return (
 		<>
-			<div className="flex flex-col gap-3">
+			<div className="flex w-full min-w-0 max-w-full flex-col gap-3">
 								<AiCodeBlock code={REACT_SAMPLE} language="tsx" filename="Counter.tsx" showLineNumbers />
 								<AiCodeBlock code={SHELL_SAMPLE} language="shell" />
 							</div>
@@ -177,7 +192,7 @@ export function AiSourcesExample() {
 											title: 'Vite — Next-gen tooling',
 											publisher: 'vitejs.dev',
 											url: 'https://vitejs.dev',
-											faviconUrl: 'https://vitejs.dev/logo.svg',
+											faviconUrl: VITE_FAVICON,
 										},
 										{
 											id: 'b',
@@ -213,7 +228,7 @@ export function AiSourcesExample() {
 export function AiReasoningExample() {
 	return (
 		<>
-			<div className="flex flex-col gap-3">
+			<div className="flex w-full min-w-0 max-w-full flex-col gap-3">
 								<AiReasoning streaming defaultExpanded>
 									{`Looking at the schema, I need to:\n1. Group rows by booking date\n2. Sum totals per group\n3. Pull refund deltas from the parallel table…`}
 								</AiReasoning>

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

@@ -15,6 +15,7 @@ examples:
   - AiFeedbackExample
 imports:
   - @/components/composed/ai
+publicImport: admin-ui-starter-kit/composed/ai
 tags:
   - composed
   - ai
@@ -28,8 +29,14 @@ tags:
 
 Confidence dial, prompt suggestions, token usage card, message bubble, tool call, citation, feedback.
 
-**Layer:** `composed`  
+**Layer:** `composed`
 **Source:** `src/components/composed/ai`
+**Consumer import:** `admin-ui-starter-kit/composed/ai`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/composed/ai`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
 
 ## Examples