@seedprotocol/mapping 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.7.0
+
+- Relation lookup is an edge-local stored intent: `FieldMapping.lookup.entries` as `{ value, ref }[]`. `ref` is opaque (`seedLocalId` or `seedUid`). Empty entries are a valid unassigned map.
+- `applyMapping` (sync) applies lookup entries and emits refs. Unmatched values are omitted. `applyMappingAsync` reports unmatched on `errors[]` and no longer calls the host `resolve` callback for lookup.
+- `autoMap` pairs alias matches such as `author` → List-of-Relation `authors` with `resolve: 'lookup'` and no invented refs.
+- `FieldMapper` `renderLookup?: (row: FieldMapperLookupRow) => ReactNode` — host picker on lookup rows (same split as `renderRowAccessory`). Package uid editor is a fallback only.
+- `useFieldMapper.setLookupEntries`. Row `sampleValue` and `data-state="needsLookup"` when the current sample has no matching entry.
+- `TargetProperty` stays Seed-accurate (`List` + `refValueType: 'Relation'` + `ref`). No `multiple` flag.
+- `MappingDocument.lookups` / `lookups` + `onLookupsChange` are deprecated read/write fallbacks for 0.6.0 documents.
+- `_pendingResolve` is extract/file only; lookup hits appear in the preview bag.
+
 ## 0.6.1
 
 - `FieldMapper` `renderRowAccessory?: (row: FieldMapperRow) => ReactNode` — host chrome slot on each rows-layout row (`.fm-row-accessory` / `classNames.rowAccessory`), after the transform control and before remove. Package does not fetch or preview; hosts return `null` when idle (e.g. show **Preview** only for `resolve: 'extract' | 'file'`).

package/README.md

@@ -7,12 +7,12 @@ Use this package to:
 1. Parse markdown or RSS/Atom into `SourceNode[]`
 2. Optionally expand URL sources with `buildResolvedSourceNodes` (extract / file candidates)
 3. Author `FieldMapping` edges (manually, via `autoMap`, or via `FieldMapper`)
-4. `applyMapping` (sync copy) or `applyMappingAsync` (host resolve callback) → property bag
+4. `applyMapping` (sync copy + stored lookup) or `applyMappingAsync` (host extract/file callback) → property bag
 
 Mappings are an edge list: one source may fan out to multiple properties (e.g. RSS
 `link` → `importUrl` and `canonicalUrl`). Each property is exclusive — at most one
-source may map to it. Optional `resolve: 'extract' | 'file' | 'lookup'` marks
-transforms the **host** (or a persisted value map) performs; the package never
+source may map to it. `resolve: 'extract' | 'file'` is applied by the host callback.
+`resolve: 'lookup'` is a stored string → ref table on the edge — the package never
 fetches, runs Readability, or loads Seed Identity items.
 
 ## Install
@@ -74,7 +74,7 @@ const mappings = autoMap(itemSources, postTargets)
 // link → importUrl/canonicalUrl (copy); missing body → link extract→html;
 // image URLs → featureImage with resolve:'file'
 
-// Sync preview skips resolve edges:
+// Sync preview applies lookup entries; extract/file stay pending:
 const preview = applyMapping(itemSources, mappings, postTargets)
 
 // Publish path — host owns HTTP / extract / store:
@@ -95,7 +95,8 @@ const { properties, errors } = await applyMappingAsync(
 ### Relation lookup (`resolve: 'lookup'`)
 
 Map a string source (e.g. RSS `author`) onto a Relation or List-of-Relation
-target (e.g. `authors` → Identity) via a persisted dictionary and/or host callback:
+target (e.g. `authors` → Identity) via **stored entries on the edge**. Use Seed
+model vocabulary — not a `multiple` flag:
 
 ```ts
 const postTargets: TargetProperty[] = [
@@ -108,36 +109,40 @@ const postTargets: TargetProperty[] = [
 ]
 
 const mappings = [
-  { sourceId: 'rss-author', propertyName: 'authors', resolve: 'lookup' as const },
+  {
+    sourceId: 'rss-author',
+    propertyName: 'authors',
+    resolve: 'lookup' as const,
+    lookup: {
+      entries: [{ value: 'Jane Doe', ref: 'identity-seed-uid' }],
+    },
+  },
 ]
 
 const doc: MappingDocument = {
   version: 1,
   sourceKind: 'rss',
   mappings,
-  lookups: {
-    authors: { 'Jane Doe': 'identity-seed-uid' },
-  },
 }
 
+// Sync apply emits refs from stored entries (extract/file still skipped):
+const bag = applyMapping(itemSources, mappings, postTargets)
+// bag.authors === ['identity-seed-uid']
+
 const { properties, errors } = await applyMappingAsync(
   itemSources,
   mappings,
   postTargets,
-  {
-    lookups: doc.lookups,
-    // Optional: called only when the table has no entry for the trimmed source value
-    resolve: async ({ job, rawValue }) => {
-      if (job === 'lookup') return await findOrCreateIdentity(rawValue!)
-      throw new Error(`unexpected job ${job}`)
-    },
-  },
 )
-// properties.authors === ['identity-seed-uid']
+// Unmatched values are omitted from the bag and listed in errors[].
+// Do not fetch identities inside apply — persist the assignment, then apply.
 ```
 
-`autoMap` never wires a plain string onto Relation / List-of-Relation targets —
-author those edges in FieldMapper or programmatically.
+`autoMap` pairs alias matches such as `author` → `authors` with
+`resolve: 'lookup'` and **empty** entries. It never invents refs.
+
+`MappingDocument.lookups` / `applyMappingAsync({ lookups })` remain a read-only
+fallback for 0.6.0 documents. Prefer `FieldMapping.lookup.entries`.
 
 `classifyUrl({ url, contentType? })` is a pure MIME/extension classifier
 (`html` | `image` | `audio` | `video` | `unknown`). Enclosure nodes expose
@@ -171,7 +176,6 @@ import {
   rssItemToSources,
   applyMappingAsync,
   type FieldMapping,
-  type MappingLookups,
 } from '@seedprotocol/mapping'
 import { FieldMapper, useFieldMapper } from '@seedprotocol/mapping/react'
 
@@ -182,13 +186,19 @@ import { FieldMapper, useFieldMapper } from '@seedprotocol/mapping/react'
   targets={postTargets} // e.g. { name: 'html', dataType: 'Html', required: true }
   mappings={mappings}
   onChange={setMappings}
-  lookups={lookups}
-  onLookupsChange={setLookups}
+  slots={{ lookups: 'row', preview: 'row' }}
   renderRowAccessory={(row) =>
     row.mapping?.resolve === 'extract' || row.mapping?.resolve === 'file'
       ? <button type="button">Preview</button>
       : null
   }
+  renderLookup={(row) => (
+    <IdentityLookup
+      sampleValue={row.sampleValue}
+      entries={row.mapping?.lookup?.entries ?? []}
+      onChange={row.onLookupChange}
+    />
+  )}
 />
 
 // Rows — source-keyed
@@ -218,13 +228,13 @@ const mapper = useFieldMapper({
 // mapper.rows, mapper.coverage, mapper.setSource, mapper.setTransform, …
 ```
 
-Connecting a source to a Relation / List-of-Relation target sets `resolve: 'lookup'`
-and (when `onLookupsChange` is provided) shows a string → seed uid editor — per-row
-when `layout="rows"` (default `slots.lookups: 'row'`), or as a section when
-`layout="wires"` / `slots.lookups: 'section'`.
+Connecting a source to a Relation / List-of-Relation target sets `resolve: 'lookup'`.
+Pass `renderLookup` to paint the host picker (Identity, etc.) on that row. Without
+`renderLookup`, `onLookupsChange` still enables the package uid-text fallback.
+`lookups` / `onLookupsChange` are deprecated — persist `lookup.entries` on the edge.
 
-Row and JSON previews match sync `applyMapping` output (pending resolve edges listed
-under `_pendingResolve`; JSON sits behind a disclosure).
+Row and JSON previews match sync `applyMapping` output. Lookup hits appear in the
+bag; only extract/file stay under `_pendingResolve`. JSON sits behind a disclosure.
 
 **Theming**
 
@@ -238,6 +248,7 @@ under `_pendingResolve`; JSON sits behind a disclosure).
 | `components` | Optional host `Select` / `Button` / `Pill` (defaults are native controls) |
 | `slots` | Toggle chrome: `autoMap`, `filter`, `inspector`, `preview` (`'row' \| 'json' \| 'both' \| false`), `lookups` (`'row' \| 'section' \| false`; rows layout defaults to `'row'`, wires to `'section'`) |
 | `renderRowAccessory` | Optional `(row: FieldMapperRow) => ReactNode` for host chrome (e.g. extract/file **Preview**) in `.fm-row-accessory`. Unrelated to `slots.preview`. Package does not fetch. |
+| `renderLookup` | Optional `(row: FieldMapperLookupRow) => ReactNode` for host lookup chrome on `resolve: 'lookup'` rows. Package does not fetch or list identities. |
 | `showPreview` | **Deprecated** — prefer `slots.preview` |
 | `connectionColors` | **Deprecated** optional stroke palette for wires; prefer `--sfm-map-*` / `--fm-map-*` / `--map-*` |
 | `layout="wires"` | **Deprecated** — prefer `layout="rows"` (now the default) |
@@ -247,9 +258,9 @@ under `_pendingResolve`; JSON sits behind a disclosure).
 **DOM hooks for host CSS**
 
 - Wires: mapped wells expose `data-mapping-index` / `data-pair={index % 8}` (kept for host CSS); pending `.active` only on the selected source.
-- Rows: `data-state="empty|mapped|needsResolve|conflict"`, `data-property-name`, `data-resolve`, `data-required`, `data-source-kind`.
+- Rows: `data-state="empty|mapped|needsResolve|needsLookup|conflict"`, `data-property-name`, `data-resolve`, `data-required`, `data-source-kind`.
 
-Sync `applyMapping` preview lists pending resolve edges under `_pendingResolve`.
+Sync `applyMapping` preview lists pending **extract/file** edges under `_pendingResolve`. Lookup refs from stored entries appear in the bag.
 
 See [FIELD_MAPPER_REDESIGN.md](../../docs/FIELD_MAPPER_REDESIGN.md) for the row-layout design study (Phases 1–5 shipped). PermaPress: [FIELD_MAPPER_PERMAPRESS_HANDOFF.md](../../docs/FIELD_MAPPER_PERMAPRESS_HANDOFF.md).
 
@@ -257,7 +268,7 @@ See [FIELD_MAPPER_REDESIGN.md](../../docs/FIELD_MAPPER_REDESIGN.md) for the row-
 
 | Type | Package | Meaning |
 |------|---------|---------|
-| `FieldMapping` / `MappingDocument` | `@seedprotocol/mapping` | Source id → **model property name** (1→N edges; optional `resolve`; optional `lookups`) |
+| `FieldMapping` / `MappingDocument` | `@seedprotocol/mapping` | Source id → **model property name** (1→N edges; optional `resolve`; optional `lookup.entries`) |
 | `FeedFieldManifest` | `@seedprotocol/sdk` | Property/key → **role** (`image` / `audio` / `video` / `file` / `html` / `text`) for display |
 
 Compose them: map + resolve into a plain item, then optionally normalize roles for media/HTML display. Storage stays `Image` / `File` schema types — no separate Audio/Video dataTypes.

package/dist/applyMapping.d.ts

@@ -6,19 +6,25 @@ export declare function coerceValue(rawValue: string, dataType: string): unknown
 /**
  * Apply field mappings to produce a property bag for createItem / publish.
  * Missing sources or unknown target properties are skipped (no throw).
- * Mappings with `resolve` are skipped — use `applyMappingAsync` with a host callback.
+ * `resolve: 'extract' | 'file'` edges are skipped — use `applyMappingAsync`.
+ * `resolve: 'lookup'` is applied from stored entries (or deprecated document lookups).
  */
-export declare function applyMapping(sources: SourceNode[], mappings: FieldMapping[], targets: TargetProperty[]): PropertyBag;
+export declare function applyMapping(sources: SourceNode[], mappings: FieldMapping[], targets: TargetProperty[], options?: {
+    lookups?: MappingLookups;
+}): PropertyBag;
 export type ApplyMappingAsyncOptions = {
-    /** Required for extract/file edges and lookup misses. */
+    /** Required for extract/file edges. Not called for lookup. */
     resolve?: ResolveCallback;
-    /** String → seed uid dictionaries keyed by property name. */
+    /**
+     * String → seed uid dictionaries keyed by property name.
+     * @deprecated Prefer `FieldMapping.lookup.entries`. Read as a fallback only.
+     */
     lookups?: MappingLookups;
 };
 /**
- * Async apply: copy+coerce plain edges; for `resolve` edges call the host
- * callback (or apply lookups for `lookup`) then coerce. Partial success —
- * failed resolve edges are listed in `errors` and omitted from `properties`.
+ * Async apply: copy+coerce plain edges; apply lookup entries; for extract/file
+ * call the host callback then coerce. Partial success — failed resolve edges
+ * are listed in `errors` and omitted from `properties`.
  */
 export declare function applyMappingAsync(sources: SourceNode[], mappings: FieldMapping[], targets: TargetProperty[], options?: ApplyMappingAsyncOptions): Promise<ApplyMappingAsyncResult>;
 //# sourceMappingURL=applyMapping.d.ts.map

package/dist/applyMapping.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"applyMapping.d.ts","sourceRoot":"","sources":["../src/applyMapping.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,uBAAuB,EACvB,YAAY,EACZ,cAAc,EACd,WAAW,EACX,eAAe,EAEf,UAAU,EACV,cAAc,EAEf,MAAM,SAAS,CAAA;AAEhB;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAuBvE;AA8DD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,UAAU,EAAE,EACrB,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,cAAc,EAAE,GACxB,WAAW,CAmBb;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,yDAAyD;IACzD,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB,CAAA;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,UAAU,EAAE,EACrB,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,cAAc,EAAE,EACzB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CAwIlC"}
+{"version":3,"file":"applyMapping.d.ts","sourceRoot":"","sources":["../src/applyMapping.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,uBAAuB,EACvB,YAAY,EACZ,cAAc,EACd,WAAW,EACX,eAAe,EAEf,UAAU,EACV,cAAc,EAEf,MAAM,SAAS,CAAA;AAEhB;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAuBvE;AA8DD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,UAAU,EAAE,EACrB,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,cAAc,EAAE,EACzB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,cAAc,CAAA;CAAE,GACrC,WAAW,CA4Bb;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,8DAA8D;IAC9D,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB,CAAA;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,UAAU,EAAE,EACrB,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,cAAc,EAAE,EACzB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CAwFlC"}