AutoFillField — Integration Guide

Overview

AutoFillField is a design system wrapper component that adds a collapsible badge indicator to any form field that was pre-filled from an external source (e.g. Amazon import, AI suggestion, CSV import). The badge shows a sparkle icon that expands on hover to reveal the source name.

Import: import { AutoFillField } from '@arda-cards/design-system/canary'

Step 1: Track auto-filled fields with useAutoFilledFields

Use the useAutoFilledFields hook from the frontend app for state management. It returns a Record<string, string> mapping field keys to source names, plus helpers for clearing.

import { useAutoFilledFields } from '@/hooks/useAutoFilledFields';

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

The hook provides:

• autoFilledFields — Record<string, string> mapping field keys to source names
• setAutoFilledFields — set the entire map (e.g. on import)
• clearAutoFill(key) — remove a single field’s auto-fill indicator
• clearAllAutoFill() — clear all indicators (e.g. when opening a blank form)

Step 2: Populate the map on pre-fill

When the form is populated from an external source, set the map entries for each pre-filled field:

const source = 'Amazon';
const fields: Record<string, string> = {};
if (prefillData.name) fields['name'] = source;
if (prefillData.supplier) fields['supplier'] = source;
if (prefillData.sku) fields['sku'] = source;
setAutoFilledFields(fields);

Important: Clear the map when opening a blank form (no pre-fill) to avoid stale indicators:

if (!initialFormData) {
  clearAllAutoFill();
}

Step 3: Wrap fields with AutoFillField

Wrap each auto-filled field’s label and input together in an AutoFillField. The badge positions itself absolutely at the top-right corner of the wrapper.

Text inputs (default — dismissOn=“input”)

Text inputs, textareas, and typeaheads auto-dismiss when the user types:

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

Custom components (dismissOn=“manual”)

Radix Select, image uploads, and other custom components that don’t fire native DOM events need manual dismiss. The consumer calls clearAutoFill in their own change handler:

<AutoFillField
  source={autoFilledFields['orderMethod']}
  iconColor='text-primary'
  dismissOn='manual'
>
  <label>Order method</label>
  <ArdaSelect
    value={orderMethod}
    onValueChange={(v) => {
      setOrderMethod(v);
      clearAutoFill('orderMethod'); // one extra line
    }}
    options={orderMethodOptions}
  />
</AutoFillField>

Native selects and checkboxes (dismissOn=“change”)

Native HTML form elements that fire onChange events:

<AutoFillField
  source={autoFilledFields['taxable']}
  iconColor='text-primary'
  dismissOn='change'
  onClear={() => clearAutoFill('taxable')}
>
  <label>Taxable</label>
  <input type="checkbox" checked={taxable} onChange={handleChange} />
</AutoFillField>

Step 4: Organisms with internal fields

For organisms like ItemCardEditor that manage their own internal inputs, the auto-fill state must be passed as a prop since you can’t wrap internal fields from outside.

Use the map-based autoFill prop:

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

The organism internally wraps each field with AutoFillField. Presence of a key in fields means that field is auto-filled; the value is the onClear callback.

Dismiss modes reference

Mode	DOM Event	Use for	Auto-dismiss?
input (default)	onInput	Text inputs, textareas, typeaheads	Yes — on every keystroke
change	onChange	Native selects, checkboxes, toggles	Yes — on value change
manual	None	Radix Select, image upload, custom components	No — consumer calls clearAutoFill

Props reference

Prop	Type	Default	Description
source	string | undefined	—	Optional. Source name shown in badge. When undefined, no badge is rendered — so a Record<string, string> lookup that misses (autoFilledFields['sku']) simply renders nothing.
iconColor	string	—	CSS color class for the sparkle icon (e.g. text-primary).
dismissOn	'input' | 'change' | 'manual'	'input'	Which DOM event triggers auto-dismiss.
onClear	() => void	—	Optional. Called when the badge is auto-dismissed. Required unless dismissOn='manual' — in manual mode the consumer dismisses via its own change handler, so onClear is not used.
children	ReactNode	—	The wrapped form field (label + input).
className	string	—	Additional CSS classes on the wrapper.

Badge behavior

• Collapsed: Small sparkle icon circle at the top-right of the wrapped content
• Hover: Expands to pill shape showing “Filled by {source}”
• Dismissed: Badge disappears when user edits the field
• No source: Wrapper renders transparently with zero overhead