FieldMapper UI

FieldMapper is a React component for editing a mapping: one row per model property, each with the source chosen for it, a transform (copy, extract, file, lookup) and a preview of the value. It's controlled and has no Seed dependencies: you pass the sources, targets and edges, and it calls onChange with the new edges. useFieldMapper is the same logic without the markup, for building your own UI.

import { FieldMapper, useFieldMapper } from '@seedprotocol/mapping/react'

/react needs react and react-dom 18 or 19. The types it works with (SourceNode, TargetProperty, FieldMapping) are described in the Overview.

FieldMapper

function FieldMapper(props: FieldMapperProps): JSX.Element

Props

Required:

Optional:

The deprecated props are listed at the end.

Example

A feed mapper with an author picker on lookup rows:

import { useEffect, useState, type ReactNode } from 'react'
import {
  rssXmlToSources,
  autoMap,
  lookupKey,
  type FieldMapping,
  type SourceNode,
  type TargetProperty,
} from '@seedprotocol/mapping'
import { FieldMapper } from '@seedprotocol/mapping/react'

const targets: TargetProperty[] = [
  { name: 'title', dataType: 'Text', required: true },
  { name: 'body', dataType: 'Html' },
  { name: 'author', dataType: 'Relation', ref: 'Author', required: true },
]

export function MapFeed({ xml, onSave }: { xml: string; onSave: (m: FieldMapping[]) => void }) {
  const [sample, setSample] = useState<SourceNode[]>([])
  const [mappings, setMappings] = useState<FieldMapping[]>([])

  useEffect(() => {
    rssXmlToSources(xml).then(({ items }) => {
      const first = items[0] ?? []
      setSample(first)
      setMappings(autoMap(first, targets))
    })
  }, [xml])

  return (
    <>
      <FieldMapper
        sources={sample}
        targets={targets}
        mappings={mappings}
        onChange={setMappings}
        theme="structural"
        slots={{ preview: 'row', inspector: false }}
        renderLookup={(row) => (
          <AuthorPicker
            name={row.sampleValue}
            onPick={(seedLocalId) => {
              const key = lookupKey(row.sampleValue)
              const others = (row.mapping?.lookup?.entries ?? []).filter((e) => lookupKey(e.value) !== key)
              row.onLookupChange([...others, { value: row.sampleValue, refs: [seedLocalId] }])
            }}
          />
        )}
      />
      <button type="button" onClick={() => onSave(mappings)}>
        Save mapping
      </button>
    </>
  )
}

// Your own component: lists Author items and calls onPick with one's seedLocalId
declare function AuthorPicker(props: { name: string; onPick: (seedLocalId: string) => void }): ReactNode

The example calls rssXmlToSources, so in a Vite app it needs the plugin's includeNodePolyfills, as In a browser shows.

Row layouts

rowKey="property" (the default) shows one row per property. Each row has the property name (with * when required) and type, a source select listing every source with a sample of its value, a transform select once a source is chosen, your accessory, a remove button, and a preview line. Above the rows are an Auto-map button, a coverage count ("3 of 8 properties mapped · 1 required missing") and two filter buttons, Mapped + required and All N properties. Below them are an Add mapping button, which opens a select of the properties without an edge, and a collapsible Source fields list: each of the entry's sources with its sample, the properties it feeds (or "unused"), and a Map this button that opens the same select.

Rows shown at first depend on defaultRows: 'requiredAndMapped' shows mapped and required properties, 'mapped' only mapped ones (and neither filter button starts pressed), 'all' every property. Properties added with Add mapping stay visible.

rowKey="source" shows one row per edge, in order: source select, transform select, "into", property select. The coverage count also names the missing required properties, and a banner repeats them. Rows naming a property that another row also names are all flagged, the first one included, with a banner counting them ("2 rows claim the same property"). Add mapping adds an empty row, which becomes an edge once it has both a source and a property. Use this mode when you want users to see the edge list as it is. Source mode has no filter buttons or Source fields list, and ignores defaultRows.

In both modes, choosing a source also sets the transform the row needs, if any: lookup for a relation property, extract for a URL going into an Html property, file for a URL going into an Image or File property.

Row states

Every row element carries data-state, which is also row.state in render props:

Rows also carry data-property-name, data-required="true", data-resolve (the edge's transform) and data-source-kind.

FieldMapperRow

The row object passed to renderRowAccessory, renderRowExpansion and transformOptions.

Previews use the same rules as applyMapping, so a Date property previews as a millisecond timestamp.

Lookup pickers

The package doesn't know what an Author is, so renderLookup is where you supply a picker that does. It's called for rows whose edge has resolve: 'lookup', with a FieldMapperLookupRow: everything in FieldMapperRow plus

onLookupChange: (entries: LookupEntry[]) => void
onSplitChange: (separators: LookupSeparator[] | null) => void

onLookupChange replaces the edge's whole lookup.entries list (an empty list removes it) and calls onChange. Keep the entries for other names, as the example above does. Entries match by lookup key (case-insensitive, see LookupEntry), so compare with lookupKey when you drop the old entry: with e.value !== row.sampleValue, a re-pick for "mira chen" would leave a "Mira Chen" entry ahead of the new one, and the first match wins. The picker's job is to turn row.sampleValue (the sample entry's author name) into item IDs; the other entries' names show up as users map more entries, or you can offer every name in the feed with collectLookupValues.

onSplitChange sets the edge's split separators, or removes split with null or []; FieldMapper has no control of its own for it, so render one in your picker if you want joint bylines split. Code that builds a FieldMapperLookupRow itself, such as a test, has to supply both functions.

Lookup rows stay in the needsLookup state until the table has an entry for the sample's text, or with split, for every part of it.

Built-in editor

Without renderLookup, each lookup edge gets a text editor: one line per name, with an input where the user types IDs separated by commas or spaces. It lists the edge's entries and the sample entry's text, one line per lookup key. Each keystroke writes the edge's lookup.entries through onChange, and emptying an input removes that entry. It has no control for split.

slots.lookups and layout decide what shows:

Transforms

The transform select appears once a row has a source. By default it offers copy, extract, file and lookup, plus assemble on Html properties, plus the edge's current transform if it's something else. transformOptions receives the row and that default list and returns the list to show:

type FieldMapperTransformOption = { value: '' | ResolveJob; label: string; disabled?: boolean }

value: '' means copy. To offer a slug that's derived from the title:

import { FieldMapper } from '@seedprotocol/mapping/react'
import type { FieldMapping, SourceNode, TargetProperty } from '@seedprotocol/mapping'

declare const sources: SourceNode[]
declare const targets: TargetProperty[]
declare const mappings: FieldMapping[]
declare const setMappings: (m: FieldMapping[]) => void

export const SlugAwareMapper = () => (
  <FieldMapper
    sources={sources}
    targets={targets}
    mappings={mappings}
    onChange={setMappings}
    transformOptions={(row, defaults) =>
      row.target?.name === 'slug' ? [...defaults, { value: 'derive', label: 'from title' }] : defaults
    }
  />
)

Offering derive also shows the transform select on rows without a source; once such a row has a source-less derive edge, its select is disabled until the user picks a source. The package saves resolve: 'derive' on the edge but doesn't compute anything; set derive.from with useFieldMapper's setDerive or withDeriveSpec, and apply it yourself after applyMapping.

Slots

slots switches parts of the component on and off.

Styling

theme decides how much CSS the component brings:

The CSS goes into one <style id="seed-field-mapper-theme"> element in document.head, added the first time a FieldMapper mounts (never during server rendering). It sits in the cascade layer @layer seed-field-mapper, so any unlayered rule of yours wins without specificity tricks. The element is shared: with two FieldMappers on one page, the last theme other than 'none' to mount or change is the one in effect, and switching to 'none' doesn't remove CSS that's already there.

Classes and CSS variables

Every part has a fixed class, and classNames adds yours next to it:

The root also gets seed-field-mapper--rows (--wires in the wires layout), seed-field-mapper--unstyled with theme="none", and data-theme, data-layout and (rows layout only) data-row-key attributes. SLOT_BASE_CLASS exports the table above.

The injected themes read CSS variables you can override on .seed-field-mapper: colors (--sfm-color-ground, --sfm-color-ink, --sfm-color-well, --sfm-color-line, --sfm-color-muted, --sfm-color-faint, --sfm-color-selection, --sfm-color-warning, --sfm-color-danger, --sfm-color-highlight, --sfm-map-1 … --sfm-map-8) and layout (--sfm-space-1 … --sfm-space-4, --sfm-radius-sm|md|lg, --sfm-font-family, --sfm-font-mono, --sfm-font-size-sm|md, --sfm-control-height, --sfm-row-gap). 'structural' defines only the layout ones.

Your own controls

components swaps in your design system's controls. Each gets these props:

The Select receives native <option> children, so a custom select has to read them or render a native <select> underneath. The prop types are exported as FieldMapperSelectProps, FieldMapperButtonProps and FieldMapperPillProps.

useFieldMapper

The state logic behind FieldMapper, for a UI of your own.

function useFieldMapper(args: UseFieldMapperArgs): UseFieldMapperResult

type UseFieldMapperArgs = {
  sources: SourceNode[]
  targets: TargetProperty[]
  mappings: FieldMapping[]
  onChange: (mappings: FieldMapping[]) => void
  rowKey?: 'property' | 'source'
  onAutoMap?: () => FieldMapping[]
}

rowKey defaults to 'property'.

It returns the rows to render and functions that edit the edges and call onChange. A rowId is a row's id: the property name in property mode.

connect and removeBySource also exist; they serve the deprecated wires layout. filterPropertyNames(targets, mappings, mode, extra) returns the property names to show for a defaultRows mode, plus the names in the extra set, or null for 'all'.

Other exports

The pure functions the component is built from are exported too, for previews or tests outside React: computeCoverage, findConflicts, computeRequiredResolve, previewForEdge, buildSyncPreviewBag (the JSON preview's content), buildSourceOptions, buildPropertyModeRows, connectSourceToProperty, defaultTransformOptions, resolveTransformOptions, showTransformSelect, isTransformSelectDisabled, resolveSlots, showRowPreview, showJsonPreview and slotClass, plus the theme pieces resolveTheme, ensureThemeInjected, buildThemeCss, wrapInThemeLayer, DEFAULT_THEME_CSS, STRUCTURAL_THEME_CSS, PAINT_THEME_CSS and THEME_STYLE_ID. resetThemeInjectionForTests is for tests only. FIELD_MAPPER_PAIR_SLOTS (8) and connectionStrokeForIndex serve the deprecated wires layout's connector colors. connectSourceToProperty(mappings, sources, targets, sourceId, propertyName) returns the next FieldMapping[].

Deprecated props

These /react APIs still work. Avoid them in new code.

Related

• Overview: the types and the data flow
• Helpers: parsers, autoMap and the apply functions
• Import an RSS feed into your models: FieldMapper in a full import