admin-ui-starter-kit 0.1.4 → 0.4.2

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

@@ -22,6 +22,7 @@ imports:
   - @/components/base/cards
   - @/components/base/display/empty-state
   - @/components/typography/text-link
+publicImport: admin-ui-starter-kit/base/display
 tags:
   - base
   - display
@@ -36,8 +37,73 @@ tags:
 
 Adaptive zero-data surface. Wrap with the right illustration per resource — products, users, search results, inbox. Slots for media / actions / footer; consumer overrides every string.
 
-**Layer:** `base`  
+**Layer:** `base`
 **Source:** `src/components/base/display/empty-state`
+**Consumer import:** `admin-ui-starter-kit/base/display`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/display`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+`EmptyState` is the canonical zero-data surface. Pass an illustration (or any
+node) via `media`, optional `actions` and `footer` slots, and tune the surface
+with `padding` (`compact` / `base` / `loose`) and `border` (dashed drop-zone
+affordance). Five built-in illustrations cover the common cases.
+
+## Default
+
+<Example name="Default" source={examplesSource}>
+	<Examples.Default />
+</Example>
+
+## Common scenarios
+
+<Example name="NoProductsWithActions" source={examplesSource}>
+	<Examples.NoProductsWithActions />
+</Example>
+
+<Example name="NoTeamMembers" source={examplesSource}>
+	<Examples.NoTeamMembers />
+</Example>
+
+<Example name="NoSearchResults" source={examplesSource}>
+	<Examples.NoSearchResults />
+</Example>
+
+<Example name="InboxZero" source={examplesSource}>
+	<Examples.InboxZero />
+</Example>
+
+## Padding
+
+<Example name="PaddingCompact" source={examplesSource}>
+	<Examples.PaddingCompact />
+</Example>
+
+<Example name="PaddingBase" source={examplesSource}>
+	<Examples.PaddingBase />
+</Example>
+
+<Example name="PaddingLoose" source={examplesSource}>
+	<Examples.PaddingLoose />
+</Example>
+
+## Composition
+
+<Example name="DashedBorderDropZone" source={examplesSource}>
+	<Examples.DashedBorderDropZone />
+</Example>
+
+<Example name="StringsPropLocalisation" source={examplesSource}>
+	<Examples.StringsPropLocalisation />
+</Example>
+
+<Example name="RenderPropCustomMedia" source={examplesSource}>
+	<Examples.RenderPropCustomMedia />
+</Example>
 
 ## Examples
 

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

@@ -17,6 +17,7 @@ examples:
 imports:
   - @/components/base/event-calendar/event-calendar
   - @/components/base/event-calendar/event-calendar.types
+publicImport: admin-ui-starter-kit/base/event-calendar
 tags:
   - base
   - navigation
@@ -32,8 +33,62 @@ tags:
 
 Month view with categories, filtering, navigation rules, custom event rendering, and three day-heading variants.
 
-**Layer:** `base`  
+**Layer:** `base`
 **Source:** `src/components/base/event-calendar`
+**Consumer import:** `admin-ui-starter-kit/base/event-calendar`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/base/event-calendar`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Overview
+
+`EventCalendar` is the canonical month view — pass `events` and optional
+`categories`, drive filtering with `enableCategoryFilter` / `visibleCategories`
+or imperatively with `filterEvent`, and slot a custom renderer with
+`renderEvent`. Navigation can be capped via `minDate` / `maxDate` and
+`disabledDates`, and every string + locale is overridable.
+
+## Default
+
+<Example name="Default" source={examplesSource}>
+	<Examples.Default />
+</Example>
+
+## Navigation modes
+
+<Example name="RangeModeMonthYearCompactMonthYearJump" source={examplesSource}>
+	<Examples.RangeModeMonthYearCompactMonthYearJump />
+</Example>
+
+<Example name="NavigationLimitsDisabledDates" source={examplesSource}>
+	<Examples.NavigationLimitsDisabledDates />
+</Example>
+
+## Day-heading variants
+
+<Example name="DayHeadingVariantTinted" source={examplesSource}>
+	<Examples.DayHeadingVariantTinted />
+</Example>
+
+<Example name="DayHeadingVariantBordered" source={examplesSource}>
+	<Examples.DayHeadingVariantBordered />
+</Example>
+
+<Example name="DayHeadingVariantAccent" source={examplesSource}>
+	<Examples.DayHeadingVariantAccent />
+</Example>
+
+## Customisation
+
+<Example name="FilterEventRenderEventCustomEventRendering" source={examplesSource}>
+	<Examples.FilterEventRenderEventCustomEventRendering />
+</Example>
+
+<Example name="WithCustomStringsBG" source={examplesSource}>
+	<Examples.WithCustomStringsBG />
+</Example>
 
 ## Examples
 

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

@@ -11,6 +11,8 @@ examples:
   - WithHelperText
   - InputBasic
   - InputWithIcons
+  - PasswordInputExample
+  - SlugFieldExample
   - InputWithAddons
   - InputClearableLoading
   - InputCharacterCount
@@ -52,6 +54,7 @@ imports:
   - @/components/base/buttons
   - @/components/base/forms
   - @/components/base/forms/fields
+publicImport: admin-ui-starter-kit/base/forms
 tags:
   - base
   - forms
@@ -66,8 +69,298 @@ tags:
 
 The full form scope — FormField wrapper plus every field component exported from base/forms/fields: text inputs, numeric, selects, toggles, choice groups, date/time, repeaters, localized fields, and uploads.
 
-**Layer:** `base`  
+**Layer:** `base`
 **Source:** `src/components/base/forms`
+**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
+
+The `forms/` folder ships the canonical form-row wrapper (`FormField` /
+`ControlledFormField`) plus every input primitive — `Input`, `Textarea`,
+`Select`, numeric/money/dimension/weight inputs, choice groups, date & time
+pickers, sliders, tag/phone/coordinates inputs, three repeater families, and
+the localized field set. Most fields are framework-free and accept
+value/onChange directly. The repeater and localized-* families opt into
+`react-hook-form` — that coupling is intentional and contained to those files.
+
+Pair any field with `FormField` (or `ControlledFormField` for RHF) to inherit
+the standard label / required asterisk / error / hint rhythm. Pass `invalid`
+to the inner field to flip the destructive border + ring.
+
+## FormField wrapper
+
+<Example name="BasicField" source={examplesSource}>
+	<Examples.BasicField />
+</Example>
+
+<Example name="WithError" source={examplesSource}>
+	<Examples.WithError />
+</Example>
+
+<Example name="WithHelperText" source={examplesSource}>
+	<Examples.WithHelperText />
+</Example>
+
+## Consumer usage
+
+Consumers import the form row wrappers and field primitives from the exact
+package entrypoint:
+
+```tsx
+import {
+	ControlledFormField,
+	FormField,
+	Input,
+	MoneyInput,
+	Select,
+	Textarea,
+	ToggleField,
+} from 'admin-ui-starter-kit/base/forms';
+```
+
+Use `FormField` for presentational rows and custom controlled widgets. Use
+`ControlledFormField` when a field is bound to `react-hook-form`; its children
+render-prop receives `(field, error, invalid, fieldState)`. The wrapper already
+renders the merged backend / validation error message, so pass
+`invalid={invalid}` to the inner field and avoid duplicating error text inside
+the control.
+
+Searchable selects live in `admin-ui-starter-kit/base/combobox`, but they still
+belong inside `ControlledFormField` when used in forms.
+
+## Choosing field primitives
+
+- Use `Input` and `Textarea` for ordinary text entry.
+- Use `PasswordInput` for password fields that need a show/hide visibility
+  control; it keeps the icon button, aria labels, and input sizing consistent.
+- Use `SlugField` for generated read-only slugs derived from another form
+  value. It renders the package `Input` as read-only and submits the slug value
+  when a `name` is provided.
+- Use `DecimalInput`, `PercentageInput`, `MoneyInput`, `CurrencyInput`,
+  `WeightInput`, and `DimensionsInput` when the value has numeric semantics.
+- Use `Select` or `RichSelect` for finite option sets; use
+  `EnhancedCombobox` when options are searchable, async, grouped, or creatable.
+- Use `Switch`, `Checkbox`, `ToggleField`, and `SwitchCard` for boolean state.
+- Use `PillRadioGroup`, `ListRadioGroup`, `CardRadioGroup`, and
+  `CardCheckboxGroup` when options need richer scanning affordances.
+- Use `DateTimeInput`, `TimePicker`, `TagsInput`, `PhoneInput`, and
+  `CoordinatesInput` for domain-specific values instead of reassembling those
+  behaviours from generic inputs.
+- Use the repeater and localized-field families only when the form already uses
+  `react-hook-form`; they intentionally bind to RHF because they manage nested
+  arrays and locale-keyed objects.
+
+Do not use `Item` for form controls. `Item` is for display/action rows;
+`FormField` is the canonical label + control + hint/error row.
+
+## Text inputs
+
+<Example name="InputBasic" source={examplesSource}>
+	<Examples.InputBasic />
+</Example>
+
+<Example name="InputWithIcons" source={examplesSource}>
+	<Examples.InputWithIcons />
+</Example>
+
+<Example name="PasswordInputExample" source={examplesSource}>
+	<Examples.PasswordInputExample />
+</Example>
+
+<Example name="SlugFieldExample" source={examplesSource}>
+	<Examples.SlugFieldExample />
+</Example>
+
+<Example name="InputWithAddons" source={examplesSource}>
+	<Examples.InputWithAddons />
+</Example>
+
+<Example name="InputClearableLoading" source={examplesSource}>
+	<Examples.InputClearableLoading />
+</Example>
+
+<Example name="InputCharacterCount" source={examplesSource}>
+	<Examples.InputCharacterCount />
+</Example>
+
+<Example name="TextareaExample" source={examplesSource}>
+	<Examples.TextareaExample />
+</Example>
+
+## Numeric inputs
+
+<Example name="DecimalInputExample" source={examplesSource}>
+	<Examples.DecimalInputExample />
+</Example>
+
+<Example name="PercentageInputExample" source={examplesSource}>
+	<Examples.PercentageInputExample />
+</Example>
+
+<Example name="CurrencyInputExample" source={examplesSource}>
+	<Examples.CurrencyInputExample />
+</Example>
+
+<Example name="MoneyInputExample" source={examplesSource}>
+	<Examples.MoneyInputExample />
+</Example>
+
+<Example name="WeightInputExample" source={examplesSource}>
+	<Examples.WeightInputExample />
+</Example>
+
+<Example name="DimensionsInputExample" source={examplesSource}>
+	<Examples.DimensionsInputExample />
+</Example>
+
+## Selects
+
+<Example name="SelectExample" source={examplesSource}>
+	<Examples.SelectExample />
+</Example>
+
+<Example name="RichSelectExample" source={examplesSource}>
+	<Examples.RichSelectExample />
+</Example>
+
+<Example name="RoundingModeSelectExample" source={examplesSource}>
+	<Examples.RoundingModeSelectExample />
+</Example>
+
+## Toggles & checkboxes
+
+<Example name="SwitchExample" source={examplesSource}>
+	<Examples.SwitchExample />
+</Example>
+
+<Example name="CheckboxExample" source={examplesSource}>
+	<Examples.CheckboxExample />
+</Example>
+
+<Example name="ToggleFieldExample" source={examplesSource}>
+	<Examples.ToggleFieldExample />
+</Example>
+
+<Example name="SwitchCardExample" source={examplesSource}>
+	<Examples.SwitchCardExample />
+</Example>
+
+## Choice groups
+
+<Example name="PillRadioGroupExample" source={examplesSource}>
+	<Examples.PillRadioGroupExample />
+</Example>
+
+<Example name="ListRadioGroupExample" source={examplesSource}>
+	<Examples.ListRadioGroupExample />
+</Example>
+
+<Example name="CardRadioGroupExample" source={examplesSource}>
+	<Examples.CardRadioGroupExample />
+</Example>
+
+<Example name="CardCheckboxGroupExample" source={examplesSource}>
+	<Examples.CardCheckboxGroupExample />
+</Example>
+
+## Date & time
+
+<Example name="DateTimeInputExample" source={examplesSource}>
+	<Examples.DateTimeInputExample />
+</Example>
+
+<Example name="TimePickerExample" source={examplesSource}>
+	<Examples.TimePickerExample />
+</Example>
+
+## Other inputs
+
+<Example name="SliderExample" source={examplesSource}>
+	<Examples.SliderExample />
+</Example>
+
+<Example name="TagsInputExample" source={examplesSource}>
+	<Examples.TagsInputExample />
+</Example>
+
+<Example name="PhoneInputExample" source={examplesSource}>
+	<Examples.PhoneInputExample />
+</Example>
+
+<Example name="CoordinatesInputExample" source={examplesSource}>
+	<Examples.CoordinatesInputExample />
+</Example>
+
+## Repeaters
+
+These four primitives — `StringRepeater`, `ObjectRepeater`, `KeyValueEditor`,
+and `List` — share the underlying `<Repeater>` primitive (drag-to-reorder,
+add/remove, empty state). They are the only fields here that hard-couple to
+react-hook-form.
+
+<Example name="StringRepeaterExample" source={examplesSource}>
+	<Examples.StringRepeaterExample />
+</Example>
+
+<Example name="ObjectRepeaterExample" source={examplesSource}>
+	<Examples.ObjectRepeaterExample />
+</Example>
+
+<Example name="KeyValueEditorExample" source={examplesSource}>
+	<Examples.KeyValueEditorExample />
+</Example>
+
+<Example name="ListExample" source={examplesSource}>
+	<Examples.ListExample />
+</Example>
+
+## Localized fields
+
+The localized field family edits per-locale objects (e.g. `{ en: '…', bg: '…' }`)
+with a single field surface. Pass `primaryLocale` / `secondaryLocale` and the
+currently `activeLocale`. RHF-coupled.
+
+<Example name="LocalizedStringFieldExample" source={examplesSource}>
+	<Examples.LocalizedStringFieldExample />
+</Example>
+
+<Example name="LocalizedObjectFieldExample" source={examplesSource}>
+	<Examples.LocalizedObjectFieldExample />
+</Example>
+
+<Example name="LocalizedStringRepeaterExample" source={examplesSource}>
+	<Examples.LocalizedStringRepeaterExample />
+</Example>
+
+## Uploads
+
+The full upload subsystem (`UploadTray`, `MediaGallery`, `FileUpload`,
+`ImageUpload`, `UploadProgressList`) lives on the dedicated
+[`base/upload-tray`](/base/upload-tray) page. The two field-shaped
+upload primitives appear here for completeness.
+
+<Example name="AvatarUploadExample" source={examplesSource}>
+	<Examples.AvatarUploadExample />
+</Example>
+
+<Example name="DropzoneExample" source={examplesSource}>
+	<Examples.DropzoneExample />
+</Example>
+
+## Whole form
+
+A realistic product form combining `Input`, `MoneyInput`, `Select`,
+`Textarea`, and `ToggleField` behind `ControlledFormField` and
+`react-hook-form`.
+
+<Example name="WholeForm" source={examplesSource}>
+	<Examples.WholeForm />
+</Example>
 
 ## Examples
 
@@ -82,6 +375,8 @@ import {
 	Textarea,
 	Select,
 	Checkbox,
+	PasswordInput,
+	SlugField,
 	Switch,
 	SwitchCard,
 	ToggleField,
@@ -167,7 +462,37 @@ export function InputWithIcons() {
 		<div className="flex w-full max-w-sm flex-col gap-3">
 			<Input startIcon={Search} placeholder="Search orders…" />
 			<Input endIcon={Mail} placeholder="you@example.com" />
-			<Input aria-label="Password" startIcon={Lock} type="password" defaultValue="hunter2" />
+			<PasswordInput aria-label="Password" startIcon={Lock} defaultValue="hunter2" />
+		</div>
+	);
+}
+
+export function PasswordInputExample() {
+	return (
+		<div className="w-full max-w-sm">
+			<FormField label="Password" hint="The reveal button is keyboard and screen-reader accessible.">
+				<PasswordInput placeholder="Enter password" autoComplete="current-password" />
+			</FormField>
+		</div>
+	);
+}
+
+export function SlugFieldExample() {
+	const [title, setTitle] = useState('Summer Collection: Salt & Pepper Set');
+
+	return (
+		<div className="grid w-full max-w-sm gap-3">
+			<FormField label="Title" hint="The slug below updates from this value.">
+				<Input value={title} onChange={(event) => setTitle(event.target.value)} />
+			</FormField>
+			<FormField label="Slug" hint="Read-only value submitted with the form.">
+				<SlugField
+					name="slug"
+					value={title}
+					startAddon="/"
+					aria-label="Generated slug"
+				/>
+			</FormField>
 		</div>
 	);
 }
@@ -855,6 +1180,8 @@ export function WholeForm() {
 - `WithHelperText`
 - `InputBasic`
 - `InputWithIcons`
+- `PasswordInputExample`
+- `SlugFieldExample`
 - `InputWithAddons`
 - `InputClearableLoading`
 - `InputCharacterCount`