admin-ui-starter-kit 0.1.4 → 0.4.3

package/.agents/skills/component-quality-pass/scripts/scan-quality-smells.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const roots = ['src/components', 'src/preview/pages'];
+const exts = new Set(['.ts', '.tsx', '.mdx']);
+const maxReportsPerRule = 80;
+
+function isCommentLine(line) {
+	const trimmed = line.trim();
+	return (
+		trimmed.startsWith('//') ||
+		trimmed.startsWith('*') ||
+		trimmed.startsWith('{/*') ||
+		trimmed.startsWith('/*')
+	);
+}
+
+function countUnescapedBackticks(line) {
+	let count = 0;
+	for (let index = 0; index < line.length; index += 1) {
+		if (line[index] !== '`') continue;
+		let slashCount = 0;
+		for (let cursor = index - 1; cursor >= 0 && line[cursor] === '\\'; cursor -= 1) {
+			slashCount += 1;
+		}
+		if (slashCount % 2 === 0) count += 1;
+	}
+	return count;
+}
+
+function getTemplateLiteralLines(lines) {
+	const templateLines = new Set();
+	let inTemplate = false;
+
+	for (let index = 0; index < lines.length; index += 1) {
+		const backtickCount = countUnescapedBackticks(lines[index]);
+		if (inTemplate || backtickCount > 0) {
+			templateLines.add(index);
+		}
+		if (backtickCount % 2 === 1) {
+			inTemplate = !inTemplate;
+		}
+	}
+
+	return templateLines;
+}
+
+function hasNearbyDevGuard(lines, index) {
+	const start = Math.max(0, index - 10);
+	for (let cursor = start; cursor <= index; cursor += 1) {
+		if (/import\.meta\.env(?:\?\.DEV|\.DEV)/.test(lines[cursor])) return true;
+	}
+	return false;
+}
+
+function hasNearbyPrimarySurface(lines, index) {
+	const start = Math.max(0, index - 2);
+	const end = Math.min(lines.length - 1, index + 4);
+	for (let cursor = start; cursor <= end; cursor += 1) {
+		if (
+			/\bbg-primary\b|selection:bg-primary|data-\[[^\]]+\]:bg-primary|\bfill-primary\b|\bstroke-primary-foreground\b/.test(
+				lines[cursor],
+			)
+		) {
+			return true;
+		}
+	}
+	return false;
+}
+
+function hasNearbyNativeHiddenInputReason(lines, index) {
+	const end = Math.min(lines.length - 1, index + 8);
+	for (let cursor = index; cursor <= end; cursor += 1) {
+		if (/\btype=["'](?:hidden|file)["']|\bhidden\b/.test(lines[cursor])) return true;
+	}
+	return false;
+}
+
+function hasNearbyHiddenTriggerReason(lines, index) {
+	const end = Math.min(lines.length - 1, index + 8);
+	for (let cursor = index; cursor <= end; cursor += 1) {
+		if (/className=["']sr-only["']|tabIndex=\{-1\}/.test(lines[cursor])) return true;
+	}
+	return false;
+}
+
+const rules = [
+	{
+		id: 'arbitrary-text-px',
+		pattern: /text-\[(?:10|11|13)px\]|text-\[[0-9.]+px\]/,
+		message: 'Arbitrary pixel text size; use typography tokens/components.',
+	},
+	{
+		id: 'raw-hue-color',
+		pattern: /\b(?:text|bg|border|ring|fill|stroke)-(?:red|orange|yellow|green|blue|purple|pink|indigo|cyan|teal|emerald|amber|lime|rose|sky|violet)-\d{2,3}\b/,
+		message: 'Raw hue utility; prefer semantic tokens.',
+	},
+	{
+		id: 'primary-foreground-text',
+		pattern: /\btext-primary-foreground\b/,
+		message: 'primary-foreground text outside primary backgrounds is usually wrong.',
+		ignoreLine: (line, context) =>
+			/\bbg-primary\b|selection:bg-primary|data-\[[^\]]+\]:bg-primary/.test(line) ||
+			hasNearbyPrimarySurface(context.lines, context.index),
+	},
+	{
+		id: 'chart-token-outside-chart',
+		pattern: /\b(?:text|bg|border|fill|stroke)-chart-[1-5]\b/,
+		message: 'Chart token outside real chart usage; use semantic tokens.',
+		skipPath: /chart|Chart/,
+	},
+	{
+		id: 'focus-not-focus-visible',
+		pattern: /\bfocus:(?!visible)(?!\s*\()/,
+		message: 'Use focus-visible for interactive focus rings.',
+		skipPath: /src\/components\/ui\//,
+	},
+	{
+		id: 'raw-button',
+		pattern: /<button\b/,
+		message: 'Raw button; use base Button unless this is primitive/internal code.',
+		skipPath: /\.test\.|src\/components\/ui\/|src\/components\/base\//,
+		ignoreLine: (line, context) =>
+			/render=\{\s*<button\b/.test(line) ||
+			hasNearbyHiddenTriggerReason(context.lines, context.index),
+	},
+	{
+		id: 'raw-input',
+		pattern: /<input\b/,
+		message: 'Raw input; use base form fields unless hidden/native input is required.',
+		skipPath: /\.test\.|src\/components\/ui\/|src\/components\/base\/forms\//,
+		ignoreLine: (_line, context) =>
+			hasNearbyNativeHiddenInputReason(context.lines, context.index),
+	},
+	{
+		id: 'direct-ui-import',
+		pattern: /from ['"]@\/components\/ui\//,
+		message: 'Direct ui primitive import outside base wrapper.',
+		skipPath: /src\/components\/base\/|src\/components\/ui\/|src\/preview\/pages\/ui\//,
+	},
+	{
+		id: 'framework-import',
+		pattern: /from ['"](?:@inertiajs|next\/|react-router|@tanstack\/react-router|@tanstack\/react-query|ziggy-js|vite-bundled-i18n)/,
+		message: 'Framework/query/i18n import in component library surface.',
+	},
+	{
+		id: 'locale-detection',
+		pattern: /navigator\.language|navigator\.languages/,
+		message: 'Library should accept locale; do not detect browser locale.',
+	},
+	{
+		id: 'console-unguarded',
+		pattern: /console\.(?:warn|error)\(/,
+		message: 'Console calls must be DEV-guarded and paired with callbacks for real errors.',
+		ignoreLine: (_line, context) =>
+			hasNearbyDevGuard(context.lines, context.index),
+	},
+];
+
+function walk(dir, files = []) {
+	for (const name of readdirSync(dir)) {
+		if (name === 'node_modules' || name === 'dist') continue;
+		const path = join(dir, name);
+		const stat = statSync(path);
+		if (stat.isDirectory()) walk(path, files);
+		else if (exts.has(path.slice(path.lastIndexOf('.')))) files.push(path);
+	}
+	return files;
+}
+
+const reports = new Map(rules.map((rule) => [rule.id, []]));
+
+for (const root of roots) {
+	for (const file of walk(root)) {
+		const rel = relative(process.cwd(), file);
+		const lines = readFileSync(file, 'utf8').split(/\r?\n/);
+		const templateLiteralLines = getTemplateLiteralLines(lines);
+		for (const rule of rules) {
+			if (rule.skipPath?.test(rel)) continue;
+			for (let index = 0; index < lines.length; index += 1) {
+				if (isCommentLine(lines[index]) || templateLiteralLines.has(index)) continue;
+				if (!rule.pattern.test(lines[index])) continue;
+				if (rule.ignoreLine?.(lines[index], { lines, index, rel })) continue;
+				const bucket = reports.get(rule.id);
+				if (bucket.length < maxReportsPerRule) {
+					bucket.push({ file: rel, line: index + 1, text: lines[index].trim() });
+				}
+			}
+		}
+	}
+}
+
+let total = 0;
+for (const rule of rules) {
+	const bucket = reports.get(rule.id);
+	if (bucket.length === 0) continue;
+	total += bucket.length;
+	console.log(`\n${rule.id}: ${rule.message}`);
+	for (const report of bucket) {
+		console.log(`  ${report.file}:${report.line}  ${report.text}`);
+	}
+	if (bucket.length === maxReportsPerRule) {
+		console.log(`  ... capped at ${maxReportsPerRule} reports`);
+	}
+}
+
+if (total === 0) {
+	console.log('No quality smells found by static scan.');
+} else {
+	console.log(`\n${total} potential smells found. Triage manually; static output is not proof of a bug.`);
+	process.exitCode = 1;
+}

package/AGENTS.md

@@ -13,9 +13,9 @@ good or bad. Fixes propagate everywhere; mistakes do too.
 
 The architectural goals — and the reason every rule below exists — are:
 
-1. **Centralized**: shadcn primitives, typography, base wrappers,
-   composed surfaces, and feature shells all ship from one place.
-   Consumers upgrade once.
+1. **Centralized**: shadcn primitives live internally, while typography,
+   base wrappers, composed surfaces, and feature shells ship as the
+   public package surface. Consumers upgrade once.
 2. **Framework-agnostic**: Inertia, Tanstack Router, RR7, Next.js, plain
    Vite, anywhere. Routing, i18n, and data fetching arrive via callbacks
    and props at each call site. **The library never imports any framework
@@ -106,7 +106,10 @@ Hard rules (full detail in the skill):
   data / i18n at the call site via direct props
   (`onSubmit`, `onSelect`, `fetcher`, `strings`, …).
 - Direct imports from `@/components/ui/*` are allowed **only** inside
-  the matching `base/` wrapper. Anywhere else, use the wrapper.
+  the matching `base/` wrapper. Anywhere else, use the wrapper. Raw
+  `src/components/ui/*` files are not public package entrypoints;
+  consumers use `admin-ui-starter-kit/base/<family>`,
+  `admin-ui-starter-kit/features/<feature>`, etc.
 - Published package imports are exact subpaths. The root entrypoint
   exports only optional-peer-free utilities/provider; `base`,
   `composed`, and `features` aggregate entrypoints are intentionally

package/COMPONENT_SELECTION.md

@@ -13,26 +13,32 @@ or documented here, treat it as private.
 | Button or icon button | `Button`, `TextButton`, button variants | `admin-ui-starter-kit/base/buttons` |
 | Status pill or count badge | `Badge` | `admin-ui-starter-kit/base/badge` |
 | Card shell | `SmartCard` | `admin-ui-starter-kit/base/cards` |
+| Section frame or grouped panels | `Frame` family | `admin-ui-starter-kit/base/frame` |
 | Row with icon/avatar/title/meta/actions | `Item` family | `admin-ui-starter-kit/base/item` |
 | Label/value metadata | `MetadataList` | `admin-ui-starter-kit/base/display/metadata` |
-| Tooltip, avatar, separator, inline stat | display family | `admin-ui-starter-kit/base/display` |
+| Alert, tooltip, avatar, separator, inline stat | display family | `admin-ui-starter-kit/base/display` |
+| Recharts primitives with themed tooltip/legend | chart display family | `admin-ui-starter-kit/base/display/chart` |
 | Form label/control/error row | `FormField`, `ControlledFormField` | `admin-ui-starter-kit/base/forms` |
-| Inputs, selects, textareas, QR fields | form field exports | `admin-ui-starter-kit/base/forms` |
-| Searchable select | `Combobox` | `admin-ui-starter-kit/base/combobox` |
+| Inputs, password reveal, selects, textareas, QR fields | form field exports | `admin-ui-starter-kit/base/forms` |
+| Backend/schema-driven settings forms | `SchemaForm`, `useSchemaForm` | `admin-ui-starter-kit/features/schema-form` |
+| Searchable select | `EnhancedCombobox`, `EnhancedComboboxMultiple` | `admin-ui-starter-kit/base/combobox` |
 | Popover menu or command menu | `PopoverMenu`, `Command` | `admin-ui-starter-kit/base/popover-menu`, `admin-ui-starter-kit/base/command` |
+| Embla-backed carousel controls | `Carousel` family | `admin-ui-starter-kit/base/carousel` |
 | Dropdown navigation menus | navigation family | `admin-ui-starter-kit/base/navigation` |
 | Data table | `DataTable` | `admin-ui-starter-kit/base/table` |
 | Date picker or date range picker | date picker family | `admin-ui-starter-kit/base/date-pickers` |
 | Map or place autocomplete | map family | `admin-ui-starter-kit/base/map` |
-| KPI cards and charts | analytics surfaces | `admin-ui-starter-kit/composed/analytics` |
+| KPI cards and chart cards | analytics surfaces | `admin-ui-starter-kit/composed/analytics` |
 | Commerce/order/product surfaces | commerce surfaces | `admin-ui-starter-kit/composed/commerce` |
 | Timeline | timeline surfaces | `admin-ui-starter-kit/composed/timelines` |
 | Comments panel | `Comments` | `admin-ui-starter-kit/features/comments` |
 | Filter bar/facets | filters feature | `admin-ui-starter-kit/features/filters` |
 | Dialog, drawer, alert dialog | overlays feature | `admin-ui-starter-kit/features/overlays` |
 | Global search shell | global search feature | `admin-ui-starter-kit/features/global-search` |
+| Media picker, asset library, product gallery field | `MediaLibrary`, `MediaLibraryDialog`, `useMediaLibrary` | `admin-ui-starter-kit/features/media-library` |
 | Mentions/typeahead | mentions or suggestions feature | `admin-ui-starter-kit/features/mentions`, `admin-ui-starter-kit/features/suggestions` |
 | Rich text editor | TipTap-backed editor | `admin-ui-starter-kit/features/rich-text-editor` |
+| Auth card or split-page chrome | `AuthShell`, `AuthCard`, `AuthSplitPanel`, social/policy/language slots | `admin-ui-starter-kit/layout/auth` |
 | Page title/actions/breadcrumb chrome | page layout | `admin-ui-starter-kit/layout/page` |
 | Header shell/search/action slots | header layout | `admin-ui-starter-kit/layout/header` |
 | Sidebar shell | sidebar layout | `admin-ui-starter-kit/layout/sidebar` |
@@ -55,13 +61,52 @@ or documented here, treat it as private.
    rich text editor live there.
 
 5. Is it page chrome?
-   Use `layout`. Keep routing and active-link state in the app.
+   Use `layout`. Keep routing, active-link state, auth requests, and app
+   translations in the app.
 
 6. Does it hardcode backend, auth, routing, app translations, or product
    branding?
    Keep it in the app. Wrap package components only where the wrapper binds
    app-specific behaviour.
 
+## High-frequency primitives
+
+Promote `Item` first for row-shaped UI. If a row has its own identity, media,
+title/description stack, click target, trailing badge, action button, switch, or
+chevron, use `admin-ui-starter-kit/base/item`.
+
+Use `MetadataList` for label/value facts that describe one entity. Metadata rows
+are read-heavy summaries: invoice totals, account attributes, SKU details,
+audit facts, or receipt lines. If the row is acted on independently, it is no
+longer metadata.
+
+Use `FormField` or `ControlledFormField` for every editable label + control +
+hint/error row. `ControlledFormField` owns the error text for
+`react-hook-form`; pass its `invalid` render-prop value down to the inner field
+or combobox.
+
+Use `PasswordInput` for password fields that need a show/hide icon. Do not
+rebuild the reveal button around `Input type="password"`.
+
+Use `SchemaForm` when the consuming app already has backend-provided field
+definitions, tenant settings, integration configuration, or another admin
+schema that should render as one cohesive form or as section cards. Keep
+validation libraries, server errors, route changes, translations, async option
+fetching, and submission in the app through `validate`, `errors`, `onSubmit`,
+`onError`, `strings`, `renderField`, and `renderSection`.
+
+Use `MediaLibrary` for app-level media picking flows: product galleries, CMS
+assets, campaign files, and upload staging. Use `MediaLibraryDialog` only when
+the picker needs modal behavior; it reuses `features/overlays/Dialog` for
+backdrop, escape handling, trigger support, and overlay chrome. Wire fetching,
+uploading, metadata updates, routing, and storage through props such as
+`fetcher`, `onUpload`, `onItemUpdate`, `onItemDelete`, `value`, and
+`onValueChange`.
+
+Typography is not optional glue. Use `Text`, `Heading`, `Label`, and `TextLink`
+from `admin-ui-starter-kit/typography` instead of raw font-size, weight, or
+muted-color utility classes.
+
 ## Adapter examples
 
 Use an app adapter when you bind framework behaviour:
@@ -92,6 +137,7 @@ Use:
 ```tsx
 import { Button } from 'admin-ui-starter-kit/base/buttons';
 import { Text } from 'admin-ui-starter-kit/typography';
+import { ChartContainer } from 'admin-ui-starter-kit/base/display/chart';
 import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
 ```
 

package/INTEGRATION.md

@@ -20,6 +20,9 @@ Install optional peers only for the entrypoints you import. For example,
 `admin-ui-starter-kit/features/rich-text-editor` needs TipTap,
 `admin-ui-starter-kit/base/table` needs TanStack Table, and
 `admin-ui-starter-kit/base/map` needs the Leaflet peer set.
+`admin-ui-starter-kit/base/carousel` needs `embla-carousel-react`.
+`admin-ui-starter-kit/base/display/chart` and chart-backed analytics surfaces
+need `recharts`.
 `admin-ui-starter-kit/base/date-pickers` needs `react-day-picker@^10`;
 pass-through `calendarProps` follow DayPicker v10, so deprecated v9 props
 such as `fromYear` / `toYear` must be replaced with `startMonth` / `endMonth`.
@@ -33,9 +36,18 @@ Import the family you use. This is the core package contract.
 import { UIProvider } from 'admin-ui-starter-kit/ui-provider';
 import { Text } from 'admin-ui-starter-kit/typography';
 import { Button } from 'admin-ui-starter-kit/base/buttons';
+import { Carousel } from 'admin-ui-starter-kit/base/carousel';
+import { EnhancedCombobox } from 'admin-ui-starter-kit/base/combobox';
+import { ControlledFormField, Input, PasswordInput } from 'admin-ui-starter-kit/base/forms';
+import { Frame } from 'admin-ui-starter-kit/base/frame';
 import { Item, ItemContent, ItemMedia, ItemTitle } from 'admin-ui-starter-kit/base/item';
+import { ChartContainer } from 'admin-ui-starter-kit/base/display/chart';
 import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
+import { ChartCard } from 'admin-ui-starter-kit/composed/analytics';
 import { Comments } from 'admin-ui-starter-kit/features/comments';
+import { MediaLibraryDialog } from 'admin-ui-starter-kit/features/media-library';
+import { SchemaForm } from 'admin-ui-starter-kit/features/schema-form';
+import { AuthShell } from 'admin-ui-starter-kit/layout/auth';
 import { PageHeader } from 'admin-ui-starter-kit/layout/page';
 ```
 
@@ -46,8 +58,9 @@ they would force optional peers into apps that do not use them.
 
 Only documented nested subfamily entrypoints are public. For example,
 `MetadataList` is intentionally exported from
-`admin-ui-starter-kit/base/display/metadata` so consumers do not need the
-broader `base/display` barrel or its optional peers.
+`admin-ui-starter-kit/base/display/metadata`, and chart primitives are exported
+from `admin-ui-starter-kit/base/display/chart`, so consumers can avoid optional
+peers they do not use.
 
 The package publishes exact export keys, not wildcard package exports. If an
 import path is not documented or listed in `package.json` `exports`, treat it as
@@ -59,6 +72,39 @@ The root entrypoint is intentionally small:
 import { UIProvider, useStrings, cn } from 'admin-ui-starter-kit';
 ```
 
+Common primitive choices:
+
+- Use `Item` for rows with their own identity, media, title stack, click target,
+  or trailing actions.
+- Use `MetadataList` for label/value facts that describe one entity.
+- Use `FormField` / `ControlledFormField` for every editable label + control +
+  hint/error row.
+- Use `PasswordInput` instead of plain `Input type="password"` when the field
+  needs a show/hide icon with accessible labels.
+- Use `EnhancedCombobox` / `EnhancedComboboxMultiple` for searchable selects;
+  wrap them in `ControlledFormField` inside forms and pass `invalid={invalid}`
+  from the render-prop.
+- Use `SchemaForm` from `admin-ui-starter-kit/features/schema-form` when the
+  app already has backend-provided field definitions, tenant settings, or
+  integration configuration that should render as a cohesive form or section
+  cards. Keep validation libraries, server errors, submit handlers, route
+  changes, translations, async option fetching, and app-specific controls in
+  the consuming app via `validate`, `errors`, `onSubmit`, `onError`, `strings`,
+  `renderField`, and `renderSection`.
+- Use `AuthShell` from `admin-ui-starter-kit/layout/auth` for login, register,
+  invite, reset, magic-link, verification, and two-factor page chrome. It covers
+  logo/brand, social providers, policy links, language links or switchers, and
+  full-bleed top media strips; keep the form action, auth routes, translations,
+  locale state, and router links in the app.
+- Use `MediaLibrary` / `MediaLibraryDialog` from
+  `admin-ui-starter-kit/features/media-library` for media picking, product
+  gallery fields, asset search, upload staging, and metadata editing. Keep
+  storage, fetching, URL resolution, and framework routing in the app through
+  `fetcher`, `accessors`, `onUpload`, `onItemUpdate`, `onItemDelete`, `value`,
+  and `onValueChange`.
+- Use `Text`, `Heading`, `Label`, and `TextLink` instead of local typography
+  utility spans.
+
 ## 3. Mount styles and provider
 
 ```tsx

package/MIGRATION.md

@@ -59,7 +59,9 @@ import { Item, ItemContent, ItemMedia, ItemTitle } from 'admin-ui-starter-kit/ba
 ```
 
 Use `MetadataList` for label/value data, compact summaries, and entity details.
-Use `Item` for rows with media, title, description, metadata, or actions.
+Use `Item` for rows with their own identity, media, title, description,
+click target, or actions. If each row can be acted on independently, prefer
+`Item`; if the rows are facts about one entity, prefer `MetadataList`.
 
 ## 4. Replace form rows
 
@@ -67,11 +69,22 @@ Use the package form shell before moving larger forms:
 
 ```tsx
 import { ControlledFormField, Input, Select } from 'admin-ui-starter-kit/base/forms';
+import { EnhancedCombobox } from 'admin-ui-starter-kit/base/combobox';
+import { SchemaForm } from 'admin-ui-starter-kit/features/schema-form';
 ```
 
 Keep form submission, validation schemas, and API mutation wiring in the app.
 The package should own the field row and control presentation, not the backend
-contract.
+contract. `ControlledFormField` renders the merged backend / validation error;
+pass its render-prop `invalid` value to the inner field or combobox instead of
+duplicating error text inside the control.
+
+Use `SchemaForm` when local code is rendering backend-provided settings,
+tenant configuration, integration setup, or other schema-driven admin forms.
+Map app records into `SchemaFormSchema`, then keep route changes, submit
+handlers, server errors, validation libraries, translations, and app-specific
+controls wired through props such as `value`, `errors`, `validate`, `onSubmit`,
+`onError`, `strings`, `renderField`, and `renderSection`.
 
 ## 5. Replace tables, filters, metrics, and overlays
 
@@ -86,7 +99,8 @@ import { Dialog, Drawer } from 'admin-ui-starter-kit/features/overlays';
 
 Install optional peers only for the entrypoints you import. For example,
 `base/table` needs `@tanstack/react-table`, `composed/analytics` needs
-`recharts`, `features/rich-text-editor` needs TipTap, and
+`recharts`, `base/display/chart` needs `recharts`, `base/carousel` needs
+`embla-carousel-react`, `features/rich-text-editor` needs TipTap, and
 `base/date-pickers` needs `react-day-picker@^10`. When migrating local date
 picker wrappers, update pass-through DayPicker props to v10 names
 (`startMonth` / `endMonth`) instead of deprecated v9 names

package/PUBLISHING.md

@@ -15,6 +15,7 @@ npm run verify                   # arch + exports + types + lint + tests
 npm run build:lib                # produces dist/
 npm run test:dist-assets         # confirms style.css font/map assets exist
 npm run build:showcase           # produces dist/showcase for the shipped docs app
+npm run verify:release           # maintainer-grade release gate: verify + package/browser/a11y/visual checks
 ```
 
 Every command must succeed locally before publish — if you ship a broken
@@ -48,7 +49,9 @@ top.
 npm publish --dry-run
 ```
 
-Read the file list. **Confirm:**
+`npm run test:package-smoke` automates this tarball check and builds a
+temporary Vite consumer against the exact public package subpaths. If you run
+`npm publish --dry-run` manually, read the file list. **Confirm:**
 - `dist/` is included with both `.js` and `.cjs` for every entrypoint.
 - `dist/style.css` is included.
 - `dist/files/` and `dist/images/` are included for font and map CSS assets.

package/README.md

@@ -56,7 +56,7 @@ exactly your tool.**
 
 ## Seven non-negotiable principles
 
-1. **Layered architecture.** `ui/` (shadcn primitives, never edited) →
+1. **Layered architecture.** `ui/` (internal shadcn primitives, never edited) →
    `typography/` → `base/` (typography-aware wrappers) → `layout/`
    (app shells) and `composed/` (domain rows + cards) → `features/`
    (callback-driven feature surfaces). Enforced by `npm run lint:architecture`.
@@ -84,9 +84,9 @@ exactly your tool.**
 
 ## What this is not
 
-- **A drop-in replacement for `shadcn/ui`** — it builds on top of shadcn,
-  doesn't replace it. You still install + customise shadcn primitives the
-  way shadcn intends.
+- **A public `shadcn/ui` mirror** — it builds on top of shadcn, but raw
+  `src/components/ui/*` files are an internal maintainer layer. Consumers use
+  the exact package entrypoints documented below.
 - **A marketing-site UI kit** — no hero sections, no landing-page blocks. Use
   it for app interiors.
 - **Coupled to any backend** — everything is callback-driven, you bring the
@@ -128,6 +128,8 @@ plan that icon-package upgrade as part of adoption.
 | `features/rich-text-editor` | `@tiptap/pm @tiptap/react @tiptap/starter-kit` |
 | `base/map` | `leaflet leaflet-draw leaflet.fullscreen leaflet.markercluster react-leaflet react-leaflet-markercluster` |
 | `base/table` | `@tanstack/react-table` |
+| `base/carousel` | `embla-carousel-react` |
+| `base/display/chart` | `recharts` |
 | `composed/analytics` (charts) | `recharts` |
 | `composed/cards` with sortable lists | `@dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities` |
 | `base/date-pickers` | `react-day-picker@^10` |
@@ -216,6 +218,36 @@ npx admin-ui-starter-kit-showcase
 
 Opens `http://127.0.0.1:7654` with sidebar navigation across UI / Base / Composed / Features / Layout, search, and per-component examples + APIs.
 
+Auth layouts live under the exact layout subpath:
+
+```tsx
+import { AuthShell } from 'admin-ui-starter-kit/layout/auth';
+```
+
+Use them for login, register, invite, reset, magic-link, verification, and
+two-factor page chrome. The shell covers logo/brand, social provider buttons,
+policy links, language links or switchers, and full-bleed top media strips.
+Forms, submit handlers, translations, locale state, and framework links stay in
+the consuming app.
+
+Media picking and product gallery flows live under the exact feature subpath:
+
+```tsx
+import { MediaLibrary, MediaLibraryDialog } from 'admin-ui-starter-kit/features/media-library';
+import { SchemaForm } from 'admin-ui-starter-kit/features/schema-form';
+```
+
+Use `MediaLibrary` for embedded asset management and `MediaLibraryDialog` when
+the picker should open in the shared overlay `Dialog`. Fetching, uploads,
+metadata edits, storage URLs, and framework routing stay in the consuming app
+through direct props.
+
+Use `SchemaForm` for backend-provided settings, tenant configuration,
+integration setup, or other admin schemas that should render as one cohesive
+form or as section cards. Keep validation libraries, server errors, route
+changes, translations, async option fetching, and app-specific controls in the
+consuming app through direct props.
+
 Flags:
 - `--port <n>` — pick a port (default 7654)
 - `--host <h>` — bind to a different host (default 127.0.0.1)
@@ -258,9 +290,10 @@ const currency = props.currency ?? defaultCurrency;
 <ContactCard strings={{ contact: t('actions.contact') }} />
 ```
 
-**`<Item>` and `<FormField>` — canonical row primitives.** Any "media + title
-+ description + actions" row goes through `Item`; any "label + control +
-error" row goes through `FormField`/`ControlledFormField`.
+**`<Item>`, `<MetadataList>`, and `<FormField>` — canonical row decisions.**
+Any "media + title + description + actions" row goes through `Item`.
+Any label/value fact summary goes through `MetadataList`. Any editable
+"label + control + error" row goes through `FormField`/`ControlledFormField`.
 
 ```tsx
 <Item>
@@ -290,20 +323,30 @@ Import per component family. This keeps optional peers isolated: importing
 ```tsx
 import { Text } from 'admin-ui-starter-kit/typography';
 import { Button } from 'admin-ui-starter-kit/base/buttons';
+import { Frame, FramePanel } from 'admin-ui-starter-kit/base/frame';
 import { Item, ItemGroup, ItemMedia, ItemContent, ItemTitle } from 'admin-ui-starter-kit/base/item';
+import { ControlledFormField, Input, PasswordInput } from 'admin-ui-starter-kit/base/forms';
+import { EnhancedCombobox } from 'admin-ui-starter-kit/base/combobox';
 import { Badge } from 'admin-ui-starter-kit/base/badge';
+import { Alert } from 'admin-ui-starter-kit/base/display';
+import { Carousel, CarouselContent, CarouselItem } from 'admin-ui-starter-kit/base/carousel';
+import { ChartContainer } from 'admin-ui-starter-kit/base/display/chart';
 import { ContactCard } from 'admin-ui-starter-kit/composed/cards';
+import { ChartCard } from 'admin-ui-starter-kit/composed/analytics';
 import { Comments } from 'admin-ui-starter-kit/features/comments';
 import { Dialog, Drawer } from 'admin-ui-starter-kit/features/overlays';
+import { SchemaForm } from 'admin-ui-starter-kit/features/schema-form';
 import { useStrings } from 'admin-ui-starter-kit/lib/strings';
 ```
 
 Use documented exact entrypoints only. `MetadataList` has its own public
-subfamily entrypoint because the broader `base/display` barrel includes display
-utilities with optional peers:
+subfamily entrypoint because it is often used on its own. Chart primitives also
+have an isolated entrypoint so consumers do not pull Recharts through unrelated
+display helpers:
 
 ```tsx
 import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
+import { ChartContainer } from 'admin-ui-starter-kit/base/display/chart';
 ```
 
 Safe public entrypoint shapes:
@@ -312,12 +355,18 @@ Safe public entrypoint shapes:
 - `admin-ui-starter-kit/typography`
 - `admin-ui-starter-kit/base/buttons`, `admin-ui-starter-kit/base/item`, etc.
 - `admin-ui-starter-kit/base/display/metadata`
+- `admin-ui-starter-kit/base/display/chart`
 - `admin-ui-starter-kit/composed/cards`, `admin-ui-starter-kit/composed/analytics`, etc.
-- `admin-ui-starter-kit/features/comments`, `admin-ui-starter-kit/features/filters`, etc.
+- `admin-ui-starter-kit/features/comments`, `admin-ui-starter-kit/features/filters`, `admin-ui-starter-kit/features/schema-form`, etc.
 - `admin-ui-starter-kit/layout` and exact layout families such as `admin-ui-starter-kit/layout/page`
 - `admin-ui-starter-kit/lib/strings`
 - `admin-ui-starter-kit/lib/utils`
 
+Raw shadcn primitives under `src/components/ui/*` are intentionally not public
+package exports. If a consumer needs Tabs, import the library wrapper surface
+that owns that pattern, such as `admin-ui-starter-kit/base/navigation`, rather
+than `admin-ui-starter-kit/ui/tabs`.
+
 Avoid broad component imports such as `admin-ui-starter-kit/base`,
 `admin-ui-starter-kit/composed`, or `admin-ui-starter-kit/features`; they are
 intentionally not exported. Use the exact family subpath so missing optional
@@ -326,6 +375,25 @@ peers fail only when you import the feature that needs them. The package
 null wildcard blockers are intentionally avoided because bundlers handle them
 inconsistently.
 
+### Internal shadcn primitive inventory
+
+Maintainers can add shadcn primitives with
+`npx shadcn@latest add <primitive>`, which writes to `src/components/ui/`.
+Those files are reproducible shadcn output and should be wrapped in `base/`,
+`layout/`, or `features/` before becoming a public package API.
+
+Installed internal primitives include:
+`accordion`, `alert-dialog`, `alert`, `aspect-ratio`, `avatar`, `badge`,
+`breadcrumb`, `button`, `button-group`, `calendar`, `card`, `carousel`,
+`chart`, `checkbox`, `collapsible`, `combobox`, `command`, `context-menu`,
+`dialog`, `direction`, `drawer`, `dropdown-menu`, `empty`, `field`,
+`hover-card`, `input`, `input-group`, `input-otp`, `item`, `kbd`, `label`,
+`menubar`, `native-select`, `navigation-menu`, `pagination`, `popover`,
+`progress`, `radio-group`, `resizable`, `scroll-area`, `select`,
+`separator`, `sheet`, `sidebar`, `skeleton`, `slider`, `slot`, `sonner`,
+`spinner`, `switch`, `table`, `tabs`, `textarea`, `toggle`, `toggle-group`,
+and `tooltip`.
+
 Dropdown menus use Base UI's `render` prop for custom triggers, not Radix's
 `asChild` prop:
 
@@ -398,8 +466,13 @@ npm run lint             # eslint
 npm run lint:architecture # check layer-import boundaries
 npm run test:exports     # check the exports map matches the file tree
 npm run test:dist-assets # check style.css referenced assets exist after build:lib
+npm run test:package-smoke # pack + temporary consumer build for exact subpaths
+npm run test:browser:features # Playwright feature route/workflow sweep
+npm run test:a11y:features # axe pass over feature showcase routes
+npm run test:visual:features # committed feature screenshot baselines
 npm run test             # vitest run
 npm run verify           # lint:architecture + test:exports + typecheck + lint + test
+npm run verify:release   # full maintainer release gate
 npm run publish:skill    # copy the rules skill into ~/.claude and ~/.agents
 ```
 
@@ -419,7 +492,7 @@ src/
 │   ├── strings.ts    useStrings + StringsProp + DeepPartial helpers
 │   └── utils.ts      cn() etc.
 ├── hooks/          cross-cutting hooks (useDebounce, useMobile, …)
-└── preview/        in-repo showcase app (excluded from publish)
+└── preview/        in-repo showcase app source (excluded from publish; dist/showcase ships prebuilt)
 ```
 
 ---