Auto-Fill Field Indicators

Author: Seb Date: 2026-05-11 Status: Implemented — the auto-fill indicators feature described here is delivered and shipped; this document stays under roadmap/in-progress/ because the parent “Add Items from Amazon” project is still active (e.g. free-text search and mobile follow-ups). It moves to roadmap/completed/ when the parent project closes. Related Issue: Add Items from Amazon project

Summary

Visual indicators for form fields that have been auto-filled from an external source (e.g. Amazon product import, AI-assisted fill, CSV import). Fields show a collapsible sparkle badge that expands on hover to reveal the source name. The indicator auto-dismisses when the user edits the field, providing confidence about what was auto-filled versus manually entered.

Context

• The “Add from Amazon” feature pre-fills item form fields from Amazon product data. Users need to know which fields came from Amazon and which they entered themselves.
• This pattern is reusable for any auto-fill source: AI assistants, CSV imports, clipboard paste, etc.
• The solution uses a wrapper component (AutoFillField) that works with any child field without modifying its API.

What Was Built

Design system components (ux-prototype)

AutoFillField molecule — a wrapper component that adds a collapsible badge indicator to any form field:

<AutoFillField source="Amazon" iconColor="text-primary" onClear={() => clearAutoFill('sku')}>
  <label>SKU</label>
  <InputGroup>
    <InputGroupInput value={sku} onChange={handleChange} />
  </InputGroup>
</AutoFillField>

Key design decisions:

• Wrapper, not props — works with any component (InputGroup, TypeaheadInput, ArdaSelect, custom organisms) without modifying their API
• Zero extra height — badge sits absolutely positioned at the top-right of the wrapper, inline with the field label
• Collapsible badge — collapsed: small sparkle icon circle; hover: expands to pill showing “Filled by {source}”
• Three dismiss modes — input (default, text inputs), change (native selects/checkboxes), manual (Radix Select, image uploads, custom components)

Badge atom enhancements:

• Added size variant (sm = h-4, default = h-5)
• Added icon prop for leading icon
• Added iconColor prop for icon color class
• Added collapsible mode (circle that expands to pill on hover)
• Single-character badges render as circles automatically

Other design system additions:

• ArdaSelect atom — Radix Select wrapper with standard form field styling
• Select primitive — Shadcn-style Radix Select components
• InputGroup muted addon variant — for currency select addons with proper rounded corners
• SplitButton controlled menu — menuOpen/onMenuOpenChange props
• --accent-light design token — oklch(0.98 0.015 28) for secondary badge background

Frontend app (arda-frontend-app)

useAutoFilledFields hook — generic reusable hook for tracking auto-fill state:

const { autoFilledFields, setAutoFilledFields, clearAutoFill, clearAllAutoFill } = useAutoFilledFields();

Returns a Record<string, string> mapping field keys to source names, plus helpers for clearing individual fields or all at once.

ItemFormPanel integration:

• Wraps each auto-fillable field with AutoFillField
• Populates auto-fill state from Amazon import data via initialFormData prop
• Clears all auto-fill state when opening a blank form
• Each field clears independently on user edit

ItemCardEditor organism integration:

• Map-based autoFill prop for organism-internal fields (name, image):

<ItemCardEditor
  autoFill={{
    source: 'Amazon',
    iconColor: 'text-primary',
    fields: {
      title: () => clearAutoFill('name'),
      imageUrl: () => clearAutoFill('imageUrl'),
    },
  }}
/>

Amazon import field mapping

Amazon response field	Form field	Component	Dismiss mode
name	Item name	ItemCardEditor (internal)	input
image.url	Image	ItemCardEditor (internal)	manual
price.amount / price.currency	Unit cost	InputGroup + currency Select	input
asin	Supplier SKU	InputGroup + InputGroupInput	input
productUrl	Supplier URL	InputGroup + InputGroupInput	input
(hardcoded “Amazon”)	Supplier	TypeaheadInput	input

Implementation Details

Phase 1: Design system (completed)

1. Created AutoFillField wrapper molecule with collapsible badge
2. Enhanced Badge atom with size, icon, iconColor, collapsible props
3. Created ArdaSelect atom and Select primitives
4. Added muted addon variant to InputGroup
5. Added --accent-light token to tokens.css
6. Added menuOpen/onMenuOpenChange to SplitButton
7. Added Storybook stories for all new components
8. Exported all new types and components from canary entry point

Phase 2: Frontend app (completed)

1. Created useAutoFilledFields hook for state management
2. Wrapped all auto-fillable fields with AutoFillField
3. Added map-based autoFill prop to ItemCardEditor
4. Created lookupAdapters.ts for TypeaheadOption conversion
5. Migrated supplier to canary TypeaheadInput
6. Migrated order method to ArdaSelect
7. Migrated unit price to InputGroup with currency Select addon
8. Connected Amazon import flow to auto-fill state

Tests

Unit tests (ardaClient.amazonImport.test.ts)

• Returns success DTO on 200 and 206 responses
• Returns typed error codes on failure (UNRECOGNIZED_AMAZON_URL, UNSUPPORTED_SHORT_LINK, UNSUPPORTED_AMAZON_LOCALE)
• Calls handleAuthError on 401
• Sends correct headers (Content-Type, Authorization, X-ID-Token)
• Passes input as-is (caller trims)

E2E tests (amazon-import.spec.ts)

• Sub-menu opens and contains URL input field
• Submitting a URL pre-fills form fields
• Auto-fill badges appear on pre-filled fields
• Badges dismiss on user edit
• Error messages display for invalid URLs
• Cancel button works during import
• Normal “Add item” flow has no auto-fill indicators (regression guard)

Future Enhancements

• AutoFillProvider context — form-level provider that manages the field-to-source map, eliminating prop-drilling:

<AutoFillProvider fields={autoFilledFields} onClear={clearAutoFill}>
  <AutoFillField name="primarySupply.sku">
    <InputGroup>...</InputGroup>
  </AutoFillField>
</AutoFillProvider>

• Approval workflow — optional onApprove callback + approve button on badge for AI-assisted fills
• AI-assisted fill — apply the same indicator pattern for Claude-generated field suggestions
• CSV import — bulk auto-fill indicators for imported spreadsheet data