admin-ui-starter-kit 0.6.9 → 0.7.1

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

@@ -0,0 +1,37 @@
+---
+id: features/products/actions
+title: "Features · Products · Actions"
+description: "Product option and variant action menus that can be mounted inside tables, cards, rows, or fully custom consumer layouts."
+layer: features
+sourcePath: src/components/features/products
+examples:
+imports:
+publicImport: admin-ui-starter-kit/features/products
+tags:
+  - features
+  - products
+  - actions
+  - product
+  - option
+  - variant
+---
+
+# Features · Products · Actions
+
+Product option and variant action menus that can be mounted inside tables, cards, rows, or fully custom consumer layouts.
+
+**Layer:** `features`
+**Source:** `src/components/features/products`
+**Consumer import:** `admin-ui-starter-kit/features/products`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/features/products`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Standalone menus
+
+<Example name="StandaloneActionMenus" source={examplesSource}>
+	<Examples.StandaloneActionMenus />
+</Example>
+

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

@@ -0,0 +1,73 @@
+---
+id: features/products/support-rail
+title: "Features · Products · Support Rail"
+description: "Secondary product cards for readiness, structure, operations, quote preview, and policies."
+layer: features
+sourcePath: src/components/features/products
+examples:
+  - ProductSupportRail
+imports:
+  - @/components/features/products
+publicImport: admin-ui-starter-kit/features/products
+tags:
+  - features
+  - products
+  - support
+  - rail
+  - secondary
+  - product
+---
+
+# Features · Products · Support Rail
+
+Secondary product cards for readiness, structure, operations, quote preview, and policies.
+
+**Layer:** `features`
+**Source:** `src/components/features/products`
+**Consumer import:** `admin-ui-starter-kit/features/products`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/features/products`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Rail cards
+
+<Example name="ProductSupportRail" source={examplesSource}>
+	<Examples.ProductSupportRail />
+</Example>
+
+## Examples
+
+```tsx
+import {
+	ProductOperationsCard,
+	ProductPoliciesCard,
+	ProductQuotePreviewCard,
+	ProductReadinessCard,
+	ProductStructureCard,
+} from '@/components/features/products';
+
+import { ProductPreviewViewport, railProps } from './fixtures';
+
+export function ProductSupportRail() {
+	const rail = railProps();
+
+	return (
+		<ProductPreviewViewport>
+			<div className="grid w-full gap-4 lg:grid-cols-2">
+				<ProductReadinessCard {...rail.readiness} />
+				<ProductStructureCard {...rail.structure} />
+				<ProductOperationsCard {...rail.operations} />
+				<ProductQuotePreviewCard {...rail.quote} />
+				<ProductPoliciesCard {...rail.policies} />
+			</div>
+		</ProductPreviewViewport>
+	);
+}
+```
+
+## Example exports
+
+- `ProductSupportRail`
+

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

@@ -0,0 +1,97 @@
+---
+id: features/products/variant-details
+title: "Features · Products · Variant Details"
+description: "Variant detail and editor surfaces for product-specific edit flows. Persistence, validation, and routing stay callback-owned by the consumer."
+layer: features
+sourcePath: src/components/features/products
+examples:
+  - VariantDetailsAndEditor
+imports:
+  - @/components/features/products
+publicImport: admin-ui-starter-kit/features/products
+tags:
+  - features
+  - products
+  - variant
+  - details
+  - detail
+  - editor
+---
+
+# Features · Products · Variant Details
+
+Variant detail and editor surfaces for product-specific edit flows. Persistence, validation, and routing stay callback-owned by the consumer.
+
+**Layer:** `features`
+**Source:** `src/components/features/products`
+**Consumer import:** `admin-ui-starter-kit/features/products`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/features/products`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Details and editor
+
+<Example name="VariantDetailsAndEditor" source={examplesSource}>
+	<Examples.VariantDetailsAndEditor />
+</Example>
+
+## Examples
+
+```tsx
+import { useState } from 'react';
+
+import {
+	ProductVariantDetails,
+	ProductVariantEditor,
+	type ProductVariantEditorValues,
+} from '@/components/features/products';
+
+import {
+	ProductMediaPreview,
+	ProductPreviewViewport,
+	noop,
+	options,
+	variantEditorValue,
+	variantOptionFields,
+	variantStatusOptions,
+	variants,
+} from './fixtures';
+
+export function VariantDetailsAndEditor() {
+	const [value, setValue] = useState<ProductVariantEditorValues>(variantEditorValue);
+
+	return (
+		<ProductPreviewViewport>
+			<div className="grid w-full gap-4 xl:grid-cols-[minmax(0,0.9fr)_minmax(0,1.1fr)]">
+				<ProductVariantDetails
+					variant={variants[0]}
+					optionItems={options.slice(0, 2)}
+					media={<ProductMediaPreview frame="wide" />}
+					onBack={noop}
+					onSelectVariant={noop}
+					onEditVariant={noop}
+					onDuplicateVariant={noop}
+					onDeleteVariant={noop}
+					onSelectOption={noop}
+				/>
+				<ProductVariantEditor
+					value={value}
+					optionFields={variantOptionFields}
+					statusOptions={variantStatusOptions}
+					onValueChange={setValue}
+					onSubmit={noop}
+					onCancel={noop}
+					onDelete={noop}
+				/>
+			</div>
+		</ProductPreviewViewport>
+	);
+}
+```
+
+## Example exports
+
+- `VariantDetailsAndEditor`
+

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

@@ -0,0 +1,269 @@
+---
+id: features/products/variant-management
+title: "Features · Products · Variant Management"
+description: "Option matrix and generated variants table with controlled collapse, selection, editable cells, render-props, and bulk callbacks."
+layer: features
+sourcePath: src/components/features/products
+examples:
+  - VariantManagement
+  - VariantTableControls
+imports:
+  - @/components/base/badge
+  - @/components/features/products
+publicImport: admin-ui-starter-kit/features/products
+tags:
+  - features
+  - products
+  - variant
+  - management
+  - option
+  - matrix
+---
+
+# Features · Products · Variant Management
+
+Option matrix and generated variants table with controlled collapse, selection, editable cells, render-props, and bulk callbacks.
+
+**Layer:** `features`
+**Source:** `src/components/features/products`
+**Consumer import:** `admin-ui-starter-kit/features/products`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/features/products`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Manager
+
+The manager example shows the production layout: options stay editable above
+the grouped variants table, while the variant table uses an inset frame,
+selection toolbar, and horizontal overflow instead of squeezing editable fields.
+
+<Example name="VariantManagement" source={examplesSource}>
+	<Examples.VariantManagement />
+</Example>
+
+## Table controls
+
+Use the table directly when consumers need to own the surrounding card or
+toolbar, while still keeping variant cells configurable as text, tags, fields,
+or custom render-props.
+
+<Example name="VariantTableControls" source={examplesSource}>
+	<Examples.VariantTableControls />
+</Example>
+
+## Examples
+
+```tsx
+import { useState } from 'react';
+
+import { Badge } from '@/components/base/badge';
+import {
+	ProductVariantsBulkTable,
+	ProductVariantsManager,
+	type ProductOptionEditDraft,
+	type ProductOptionGroup,
+	type ProductVariantEditableField,
+	type ProductVariantRow,
+} from '@/components/features/products';
+
+import {
+	optionGroups,
+	variantRows,
+} from './fixtures';
+
+function updateVariantField(
+	rows: ProductVariantRow[],
+	variantId: string,
+	field: ProductVariantEditableField,
+	value: string,
+) {
+	return rows.map((row) => (
+		row.id === variantId ? { ...row, [field]: value } : row
+	));
+}
+
+export function VariantManagement() {
+	const [selectedIds, setSelectedIds] = useState<string[]>([]);
+	const [optionState, setOptionState] = useState<ProductOptionGroup[]>(optionGroups);
+	const [variantState, setVariantState] = useState<ProductVariantRow[]>(variantRows);
+	const [collapsedOptionIds, setCollapsedOptionIds] = useState<string[]>([]);
+	const [configuredOptionId, setConfiguredOptionId] = useState<string | null>(null);
+
+	return (
+		<ProductVariantsManager
+			optionGroups={optionState}
+			variants={variantState}
+			optionCombinationDisplay="tags"
+			cellDisplay={{ sku: 'field', price: 'field', inventory: 'field' }}
+			visibleColumns={['variant', 'price', 'inventory', 'status']}
+			collapsedOptionIds={collapsedOptionIds}
+			onCollapsedOptionIdsChange={(ids) => setCollapsedOptionIds(ids)}
+			editingOptionId={configuredOptionId}
+			onEditingOptionIdChange={(id) => setConfiguredOptionId(id)}
+			selectedVariantIds={selectedIds}
+			onSelectedVariantIdsChange={(ids) => setSelectedIds(ids)}
+			onCreateOption={() => {
+				const nextIndex = optionState.length + 1;
+				const nextId = `custom-option-${nextIndex}`;
+				setOptionState((current) => [
+					...current,
+					{
+						id: nextId,
+						name: `Custom option ${nextIndex}`,
+						description: 'Consumer-owned option added from the preview.',
+						usedForVariants: false,
+						values: [{ id: `${nextId}-value-1`, label: 'New value' }],
+					},
+				]);
+				setConfiguredOptionId(nextId);
+			}}
+			onEditOption={(option) => setConfiguredOptionId(option.id)}
+			onDeleteOption={(option) => {
+				setOptionState((current) => current.filter((item) => item.id !== option.id));
+				if (configuredOptionId === option.id) {
+					setConfiguredOptionId(null);
+				}
+			}}
+			onSaveEditingOption={(option, draft: ProductOptionEditDraft) => {
+				setOptionState((current) => current.map((item) => (
+					item.id === option.id
+						? {
+							...item,
+							name: draft.name.trim() || item.name,
+							values: draft.values.map((value, index) => ({
+								...value,
+								id: value.id || `${item.id}-value-${index + 1}`,
+								label: String(value.label).trim() || `Value ${index + 1}`,
+							})),
+						}
+						: item
+				)));
+				setConfiguredOptionId(null);
+			}}
+			onCancelEditingOption={() => setConfiguredOptionId(null)}
+			onToggleUsedForVariants={(option, used) => {
+				setOptionState((current) => current.map((item) => (
+					item.id === option.id ? { ...item, usedForVariants: used } : item
+				)));
+			}}
+			onVariantFieldChange={(variant, field, value) => {
+				setVariantState((current) => updateVariantField(current, variant.id, field, value));
+			}}
+			onVariantFieldBlur={(variant, field, value) => {
+				setVariantState((current) => updateVariantField(current, variant.id, field, value.trim()));
+			}}
+			onSelectVariant={(variant) => setSelectedIds([variant.id])}
+			onEditVariant={(variant) => setSelectedIds([variant.id])}
+			onCreateVariant={() => {
+				const nextIndex = variantState.length + 1;
+				setVariantState((current) => [
+					...current,
+					{
+						id: `custom-variant-${nextIndex}`,
+						name: `Custom variant ${nextIndex}`,
+						sku: `CUSTOM-${nextIndex}`,
+						price: '0.00',
+						inventory: '0',
+						status: 'Draft',
+						statusVariant: 'secondary',
+						optionValueIds: {
+							'guest-count': 'one',
+							format: 'online',
+							'voucher-type': 'online',
+						},
+					},
+				]);
+			}}
+			onDuplicateVariant={(variant) => {
+				const nextIndex = variantState.length + 1;
+				setVariantState((current) => [
+					...current,
+					{
+						...variant,
+						id: `${variant.id}-copy-${nextIndex}`,
+						sku: `${variant.sku ?? 'SKU'}-COPY`,
+						status: 'Draft',
+						statusVariant: 'secondary',
+					},
+				]);
+			}}
+			onDeleteVariant={(variant) => {
+				setVariantState((current) => current.filter((item) => item.id !== variant.id));
+				setSelectedIds((current) => current.filter((id) => id !== variant.id));
+			}}
+			onBulkEdit={(selected) => {
+				const selectedSet = new Set(selected.map((variant) => variant.id));
+				setVariantState((current) => current.map((variant) => (
+					selectedSet.has(variant.id)
+						? { ...variant, status: 'Review', statusVariant: 'warning' }
+						: variant
+				)));
+			}}
+			onBulkApply={(selected) => {
+				const selectedSet = new Set(selected.map((variant) => variant.id));
+				setVariantState((current) => current.map((variant) => (
+					selectedSet.has(variant.id)
+						? { ...variant, status: 'Active', statusVariant: 'success' }
+						: variant
+				)));
+			}}
+			onBulkDelete={(selected) => {
+				const selectedSet = new Set(selected.map((variant) => variant.id));
+				setVariantState((current) => current.filter((variant) => !selectedSet.has(variant.id)));
+				setSelectedIds([]);
+			}}
+			strings={{
+				title: 'Variants',
+				description: '',
+			}}
+			variantsStrings={{
+				bulkApplyLabel: 'Mark active',
+			}}
+		/>
+	);
+}
+
+export function VariantTableControls() {
+	const [rows, setRows] = useState<ProductVariantRow[]>(variantRows.slice(0, 5));
+
+	return (
+		<ProductVariantsBulkTable
+			variants={rows}
+			optionGroups={optionGroups}
+			optionCombinationDisplay="tags"
+			selectionMode="none"
+			cellDisplay={{ sku: 'field', price: 'field' }}
+			visibleColumns={['variant', 'sku', 'price', 'inventory', 'status', 'updated']}
+			onVariantFieldChange={(variant, field, value) => {
+				setRows((current) => updateVariantField(current, variant.id, field, value));
+			}}
+			onVariantFieldBlur={(variant, field, value) => {
+				setRows((current) => updateVariantField(current, variant.id, field, value.trim()));
+			}}
+			renderCell={(variant, context) => {
+				if (context.column === 'status') {
+					return (
+						<Badge variant={variant.statusVariant ?? 'secondary'}>
+							{variant.status ?? 'Draft'}
+						</Badge>
+					);
+				}
+
+				return undefined;
+			}}
+			strings={{
+				title: 'Variant table controls',
+				description: 'Use table-level props for read-only, editable, tag-based, or custom-rendered variant cells.',
+			}}
+		/>
+	);
+}
+```
+
+## Example exports
+
+- `VariantManagement`
+- `VariantTableControls`
+

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

@@ -211,7 +211,7 @@ function LogoMark() {
 function Wordmark() {
 	return (
 		<div className="flex flex-col items-center gap-1 text-center">
-			<Text tag="div" className="font-serif text-2xl leading-none tracking-normal text-foreground">
+			<Text tag="div" className="font-serif text-base leading-none tracking-normal text-foreground">
 				Gift come true
 			</Text>
 			<div className="h-px w-16 bg-foreground/40" />

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

@@ -9,6 +9,7 @@ examples:
   - NarrowContainer
   - WideContainer
   - BareContainer
+  - TwoColumnDetailLayout
   - SectionRhythm
 imports:
   - @/components/base/badge
@@ -44,7 +45,14 @@ The examples below use repository source aliases because they run inside the pre
 
 ```tsx
 import type { ReactNode } from 'react';
-import { Container, Section } from '@/components/layout/containers';
+import {
+	Container,
+	InnerLayoutBlock,
+	OuterLayoutBlock,
+	Section,
+	TopLayoutBlock,
+	TwoColumnLayout,
+} from '@/components/layout/containers';
 import { SmartCard } from '@/components/base/cards';
 import { Text } from '@/components/typography';
 import { Badge } from '@/components/base/badge';
@@ -130,6 +138,39 @@ export function BareContainer() {
 	);
 }
 
+export function TwoColumnDetailLayout() {
+	return (
+		<DemoViewport height={520}>
+			<Container as="section" width="narrow" padding="default">
+				<TwoColumnLayout stickyRight>
+					<TopLayoutBlock>
+						<div className="flex min-w-0 flex-col gap-space-xs">
+							<Text weight="semibold">Two column detail layout</Text>
+							<Text type="secondary">Use this for main form/detail content with a right-hand summary or support rail.</Text>
+						</div>
+					</TopLayoutBlock>
+					<InnerLayoutBlock>
+						<div className="grid gap-space-lg">
+							<SampleCard title="Primary details" detail="The first inner block owns the wider content column by default." />
+							<SampleCard title="Configuration" detail="Form sections, tables, and detail cards stay together in the main column." />
+							<SampleCard title="Publishing" detail="The layout does not own data or routing; it only standardizes structure." />
+						</div>
+					</InnerLayoutBlock>
+					<InnerLayoutBlock>
+						<div className="grid gap-space-lg">
+							<SampleCard title="Summary" detail="The second inner block becomes the aside column." />
+							<SampleCard title="Checklist" detail="Set `stickyRight` when the aside should remain visible on desktop." />
+						</div>
+					</InnerLayoutBlock>
+					<OuterLayoutBlock>
+						<SampleCard title="Full-width follow-up" detail="Outer blocks render below both columns for logs, related records, or footers." />
+					</OuterLayoutBlock>
+				</TwoColumnLayout>
+			</Container>
+		</DemoViewport>
+	);
+}
+
 export function SectionRhythm() {
 	return (
 		<div className="grid grid-cols-[repeat(auto-fit,minmax(min(12rem,100%),1fr))] gap-3">
@@ -150,5 +191,6 @@ export function SectionRhythm() {
 - `NarrowContainer`
 - `WideContainer`
 - `BareContainer`
+- `TwoColumnDetailLayout`
 - `SectionRhythm`
 

package/.agents/skills/component-library-rules/references/testing.md

@@ -24,7 +24,7 @@ forwards props to a primitive. You **do** need tests when:
 - The component owns business logic (a parser, formatter, async
   options hook).
 - A class name change would silently break a downstream consumer
-  (e.g. badge size class moved from `text-[10px]` to `text-xxs` —
+  (e.g. badge size class moved from `text-[10px]` to `text-xs` —
   consumers depending on the old class need a clear failure).
 
 ## Pattern: `<UIProvider>` config in tests

package/.agents/skills/token-system/SKILL.md

@@ -71,7 +71,10 @@ npx admin-ui-starter-kit-publish-theme
 
 That command publishes editable `theme.css` and a flattened `defaults.css`
 containing package-owned token layers into the consumer app. See
-`references/consumer-overrides.md` for the decision tree.
+`references/consumer-overrides.md` for the decision tree. For downstream
+consumer migrations that also need additional themes, dark-scope wiring, or
+`<UIProvider>` defaults, use
+`../admin-ui-consumer-migration/references/theme-overrides.md`.
 
 ## Checks
 

package/AGENTS.md

@@ -34,7 +34,7 @@ The architectural goals — and the reason every rule below exists — are:
    (default currency, week-start, default badge size, …) live in a
    single zustand store wrapped by `<UIProvider>` (see
    `@/lib/ui-provider`). One provider, no nesting.
-5. **Admin-density**: workhorses are `text-sm` and `text-xs`. `text-base`
+5. **Admin-density**: workhorses are `text-sm` and `text-pxs`. `text-base`
    is rare. Rows breathe at `py-2` minimum.
 6. **Visual-quality first**: every shipped surface is evaluated as a
    designer would — spacing, hierarchy, focus states, voice consistency.
@@ -373,7 +373,8 @@ When in doubt, model new work on these reference implementations:
 ## Common mistakes — don't repeat these
 
 - **`text-[10px]` / `text-[11px]` etc.** Forbidden as semantic sizes.
-  10px → `text-xxs`, 11px/13px → `text-xs`, 0.8rem → `text-xs`. The
+  10px/11px are below the admin scale; use 12px → `text-xs`, 13px → `text-pxs`,
+  14px → `text-sm`. The
   exception is density-toggled overrides in tables/calendars where the
   bespoke size is intentional and load-bearing — those are explicitly
   scoped (see the `SKIP` list in any token sweep).
@@ -448,7 +449,7 @@ When in doubt, model new work on these reference implementations:
   `--control-height`. Consumers can override them at `:root` or on a scoped
   wrapper to densify a surface.
 - **Token-driven typography** — Tailwind text utilities resolve through
-  `--text-scale` and the `--text-xxs/xs/sm/base/lg/xl/2xl` scale. Consumers
+  `--text-scale` and the `--text-xxs/xs/pxs/sm/base/lg/xl/2xl` scale. Consumers
   override `--text-scale` first, then individual text tokens only when needed.
 
 ## Commit / PR conventions

package/COMPONENT_SELECTION.md

@@ -35,6 +35,8 @@ or documented here, treat it as private.
 | Selected resource card | `ResourceSelectorCard` | `admin-ui-starter-kit/composed/data-display` |
 | Settings/security action rows and token manager | `ActionList`, `ActionRow`, `SensitiveActionCard`, `CopyableSecretAlert`, `ApiTokenManager` | `admin-ui-starter-kit/composed/admin` |
 | Commerce/order/product surfaces | commerce surfaces | `admin-ui-starter-kit/composed/commerce` |
+| Product editor, options, variants, support rail | product feature surfaces | `admin-ui-starter-kit/features/products` |
+| Search engine listing / SEO score | `SeoListingCard`, `calculateSeoListingScore` | `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/query helpers | filters feature, `parseFiltersFromQuery`, `serializeFiltersToQuery`, `mergeFilterQuery` | `admin-ui-starter-kit/features/filters` |
@@ -128,6 +130,17 @@ Use `ResourceSelectorCard` for a selected resource inside forms, dialogs, or
 show pages. The app owns the picker overlay and routing; the card only renders
 the selected resource through accessors and calls `onSelect` / `onRemove`.
 
+Use `ProductVariantsManager` when a product editor needs option groups and a
+generated variants table with shared callbacks, selection, editable cells,
+grouping, and action menus. Use `ProductOptionsMatrix` or
+`ProductVariantsBulkTable` directly only when the app owns the surrounding card
+or needs a custom editor composition.
+
+Use `SeoListingCard` for search-engine listing previews and SEO scoring inside
+commerce/product editors. The package owns title, description, permalink, and
+keyword checks through `calculateSeoListingScore`; the app owns persistence,
+field editing, routing, and translations.
+
 Use `DataTable` selection toolbar props plus `ResourceCell`,
 `StatusClusterCell`, and `DateMetaCell` for dense index pages. Keep URL state,
 sorting persistence, row navigation, and data fetching in the app.
@@ -185,6 +198,8 @@ 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/composed/data-display';
+import { SeoListingCard } from 'admin-ui-starter-kit/composed/commerce';
+import { ProductVariantsManager } from 'admin-ui-starter-kit/features/products';
 ```
 
 Do not use: