@aglyn/aglyn 1.0.0-beta.221 → 1.0.0-beta.222

package/src/lib/data-transfer/field-catalog.js

@@ -0,0 +1,278 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /*==========================================
+ * FIELD CATALOG — every field a resource has, in the order a person picks them.
+ *
+ * Export offers ALL of a resource's fields: the standard ones it declares,
+ * the custom ones the organization defined, and the derived and system ones
+ * (the Aglyn id, created and updated times) that are read but never written.
+ * The catalog is that list, grouped and ordered once, so the export picker,
+ * the import mapping and the plan all name the same fields the same way.
+ *
+ * ## Presets
+ *
+ *  - `everything` — every field, in catalog order.
+ *  - `reimportable` — the default for export: the Aglyn id, the resource's
+ *    match keys and every writable field, so the file comes back in and
+ *    finds the records it came from.
+ *  - `minimal` — the id, the match keys, the required fields and whatever
+ *    short list the resource names as its minimum.
+ *
+ * A saved preset is a list of field ids; resolving it drops the ids the
+ * catalog no longer has (a deleted custom field) and says which.
+ *
+ * A resource may bring presets of its own (`TransferResourcePreset`): a
+ * named list of its fields, and the column names another product's import
+ * expects for them, so a file laid out for that product comes out of the
+ * export dialog ready to upload there.
+ *=========================================*/ import { customImportTarget } from "../app-utils/csv-import.js";
+import { PLATFORM_BRAND_NAME } from "../app-utils/platform-brand.js";
+import { TRANSFER_ID_FIELD, isTransferFieldWritable } from "./resource.js";
+/** The group a field with no group, or an unknown one, is listed under. */ export const TRANSFER_OTHER_GROUP = {
+    id: 'other',
+    label: 'Other'
+};
+/** The group custom fields are listed under unless they name their own. */ export const TRANSFER_CUSTOM_GROUP = {
+    id: 'custom',
+    label: 'Custom fields'
+};
+/** The group system fields are listed under unless they name their own. */ export const TRANSFER_SYSTEM_GROUP = {
+    id: 'system',
+    label: 'System'
+};
+/** A custom field definition as a catalog field, with id `custom:<key>`. */ export function customTransferField(definition) {
+    var _definition_group, _definition_type;
+    return _extends({
+        id: customImportTarget(definition.key),
+        label: definition.label || definition.key,
+        group: (_definition_group = definition.group) != null ? _definition_group : TRANSFER_CUSTOM_GROUP.id,
+        type: (_definition_type = definition.type) != null ? _definition_type : 'text',
+        custom: true,
+        aliases: definition.label && definition.label !== definition.key ? [
+            definition.key
+        ] : []
+    }, definition.picklistId ? {
+        picklistId: definition.picklistId
+    } : {}, definition.required ? {
+        required: true
+    } : {});
+}
+/** The Aglyn id field every catalog carries, labeled with the configured brand. */ export function transferIdField(label = `${PLATFORM_BRAND_NAME} ID`) {
+    return {
+        id: TRANSFER_ID_FIELD,
+        label,
+        group: TRANSFER_SYSTEM_GROUP.id,
+        type: 'text',
+        system: true,
+        readOnly: true,
+        matchKey: true,
+        aliases: [
+            ...new Set([
+                `${PLATFORM_BRAND_NAME.toLowerCase()} id`,
+                'aglyn id',
+                'record id',
+                'id'
+            ])
+        ]
+    };
+}
+/**
+ * The catalog for a resource.
+ *
+ * Standard fields come first in their groups, then derived ones, then custom
+ * ones, then system ones; within a group the declaration order holds. A
+ * field id declared twice keeps its first declaration — a custom field can
+ * never shadow a standard one because its id carries the `custom:` prefix.
+ */ export function buildTransferFieldCatalog(input) {
+    var _input_derived, _input_custom, _input_system, _input_groups;
+    const declared = [
+        ...input.standard,
+        ...((_input_derived = input.derived) != null ? _input_derived : []).map((field)=>_extends({}, field, {
+                derived: true
+            })),
+        ...((_input_custom = input.custom) != null ? _input_custom : []).map(customTransferField),
+        ...((_input_system = input.system) != null ? _input_system : []).map((field)=>{
+            var _field_group;
+            return _extends({}, field, {
+                system: true,
+                group: (_field_group = field.group) != null ? _field_group : TRANSFER_SYSTEM_GROUP.id
+            });
+        })
+    ];
+    if (!declared.some((field)=>field.id === TRANSFER_ID_FIELD)) declared.push(transferIdField());
+    const byId = new Map();
+    for (const field of declared)if (!byId.has(field.id)) byId.set(field.id, field);
+    const unique = [
+        ...byId.values()
+    ];
+    // The declared groups in their order, then any group a field names that
+    // was not declared, then the built-in tail (custom, system, other) unless
+    // the resource placed one of those itself.
+    const ordered = [];
+    const known = new Set();
+    const addGroup = (group)=>{
+        if (known.has(group.id)) return;
+        known.add(group.id);
+        ordered.push(group);
+    };
+    const builtIn = [
+        TRANSFER_CUSTOM_GROUP,
+        TRANSFER_SYSTEM_GROUP,
+        TRANSFER_OTHER_GROUP
+    ];
+    for (const group of (_input_groups = input.groups) != null ? _input_groups : [])addGroup(group);
+    for (const field of unique){
+        const id = field.group;
+        if (id && !builtIn.some((group)=>group.id === id)) addGroup({
+            id,
+            label: id
+        });
+    }
+    for (const group of builtIn)addGroup(group);
+    const groupOf = (field)=>field.group && known.has(field.group) ? field.group : TRANSFER_OTHER_GROUP.id;
+    const fields = ordered.flatMap((group)=>unique.filter((field)=>groupOf(field) === group.id));
+    return {
+        fields,
+        byId: new Map(fields.map((field)=>[
+                field.id,
+                field
+            ])),
+        groups: ordered.filter((group)=>fields.some((field)=>groupOf(field) === group.id))
+    };
+}
+/** The fields under each group, in catalog order; `fieldIds` narrows and keeps catalog order. */ export function groupTransferFields(catalog, fieldIds) {
+    const wanted = fieldIds ? new Set(fieldIds) : null;
+    const groupOf = (field)=>field.group && catalog.groups.some((group)=>group.id === field.group) ? field.group : TRANSFER_OTHER_GROUP.id;
+    return catalog.groups.map((group)=>({
+            group,
+            fields: catalog.fields.filter((field)=>groupOf(field) === group.id && (!wanted || wanted.has(field.id)))
+        })).filter((entry)=>entry.fields.length > 0);
+}
+/** The fields whose label, id or an alias contains every word of `query`. */ export function searchTransferFields(catalog, query) {
+    const words = String(query != null ? query : '').toLowerCase().split(/\s+/).filter(Boolean);
+    if (!words.length) return [
+        ...catalog.fields
+    ];
+    return catalog.fields.filter((field)=>{
+        var _field_aliases;
+        const haystack = [
+            field.label,
+            field.id,
+            ...(_field_aliases = field.aliases) != null ? _field_aliases : []
+        ].join(' ').toLowerCase();
+        return words.every((word)=>haystack.includes(word));
+    });
+}
+export const TRANSFER_PRESET_IDS = [
+    'everything',
+    'reimportable',
+    'minimal'
+];
+/** The longest column name a preset or an export request may give a field. */ export const TRANSFER_HEADER_MAX = 120;
+/**
+ * The column names an export may write, from what a request or a preset
+ * carries: only for the chosen fields, trimmed, non-empty, at most
+ * {@link TRANSFER_HEADER_MAX} characters, and never two fields under one
+ * name — a file whose columns repeat cannot be read back.
+ */ export function transferExportHeaders(fieldIds, headers) {
+    const out = {};
+    if (!headers || typeof headers !== 'object' || Array.isArray(headers)) return out;
+    const taken = new Set();
+    for (const fieldId of fieldIds){
+        const raw = headers[fieldId];
+        if (typeof raw !== 'string') continue;
+        const name = raw.trim().slice(0, TRANSFER_HEADER_MAX);
+        const key = name.toLowerCase();
+        if (!name || taken.has(key)) continue;
+        taken.add(key);
+        out[fieldId] = name;
+    }
+    return out;
+}
+/**
+ * A list of field ids against the catalog: unknown ids dropped (and
+ * reported), duplicates dropped, the given order kept, and every id in
+ * `ensure` present — added in catalog order at the front when missing.
+ */ export function resolveTransferFieldSelection(catalog, selected, ensure = []) {
+    const seen = new Set();
+    const fieldIds = [];
+    const unknown = [];
+    for (const id of selected){
+        if (seen.has(id)) continue;
+        seen.add(id);
+        if (catalog.byId.has(id)) fieldIds.push(id);
+        else unknown.push(id);
+    }
+    const missing = catalog.fields.filter((field)=>ensure.includes(field.id) && !fieldIds.includes(field.id)).map((field)=>field.id);
+    return {
+        fieldIds: [
+            ...missing,
+            ...fieldIds
+        ],
+        unknown
+    };
+}
+/**
+ * The fields a preset exports, in order. A built-in preset is computed from
+ * the catalog; a saved one is resolved against it. The re-importable and
+ * minimal presets lead with the id and the match keys.
+ */ export function resolveTransferPreset(catalog, preset, hints = {}) {
+    var _hints_matchKeyFieldIds, _hints_minimalFieldIds, _hints_minimalFieldIds1;
+    // The id leads once, whether or not the match keys name it too.
+    const keys = [
+        ...new Set([
+            TRANSFER_ID_FIELD,
+            ...(_hints_matchKeyFieldIds = hints.matchKeyFieldIds) != null ? _hints_matchKeyFieldIds : []
+        ])
+    ].filter((id)=>catalog.byId.has(id));
+    const lead = (ids)=>{
+        const rest = new Set(ids);
+        for (const key of keys)rest.delete(key);
+        return [
+            ...keys,
+            ...catalog.fields.filter((field)=>rest.has(field.id)).map((field)=>field.id)
+        ];
+    };
+    if (typeof preset !== 'string') return resolveTransferFieldSelection(catalog, preset.fieldIds);
+    if (preset === 'everything') return {
+        fieldIds: catalog.fields.map((field)=>field.id),
+        unknown: []
+    };
+    if (preset === 'reimportable') {
+        return {
+            fieldIds: lead(catalog.fields.filter(isTransferFieldWritable).map((field)=>field.id)),
+            unknown: []
+        };
+    }
+    const minimal = new Set((_hints_minimalFieldIds = hints.minimalFieldIds) != null ? _hints_minimalFieldIds : []);
+    return {
+        fieldIds: lead(catalog.fields.filter((field)=>field.required || minimal.has(field.id)).map((field)=>field.id)),
+        unknown: ((_hints_minimalFieldIds1 = hints.minimalFieldIds) != null ? _hints_minimalFieldIds1 : []).filter((id)=>!catalog.byId.has(id))
+    };
+}
+/** `ids` with the entry at `from` moved to `to` — the picker's drag to reorder. */ export function moveTransferField(ids, from, to) {
+    const next = [
+        ...ids
+    ];
+    if (from < 0 || from >= next.length) return next;
+    const [moved] = next.splice(from, 1);
+    const at = Math.max(0, Math.min(next.length, to));
+    next.splice(at, 0, moved);
+    return next;
+}
+
+//# sourceMappingURL=field-catalog.js.map

package/src/lib/data-transfer/field-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/data-transfer/field-catalog.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/*==========================================\n * FIELD CATALOG — every field a resource has, in the order a person picks them.\n *\n * Export offers ALL of a resource's fields: the standard ones it declares,\n * the custom ones the organization defined, and the derived and system ones\n * (the Aglyn id, created and updated times) that are read but never written.\n * The catalog is that list, grouped and ordered once, so the export picker,\n * the import mapping and the plan all name the same fields the same way.\n *\n * ## Presets\n *\n *  - `everything` — every field, in catalog order.\n *  - `reimportable` — the default for export: the Aglyn id, the resource's\n *    match keys and every writable field, so the file comes back in and\n *    finds the records it came from.\n *  - `minimal` — the id, the match keys, the required fields and whatever\n *    short list the resource names as its minimum.\n *\n * A saved preset is a list of field ids; resolving it drops the ids the\n * catalog no longer has (a deleted custom field) and says which.\n *\n * A resource may bring presets of its own (`TransferResourcePreset`): a\n * named list of its fields, and the column names another product's import\n * expects for them, so a file laid out for that product comes out of the\n * export dialog ready to upload there.\n *=========================================*/\n\nimport { customImportTarget } from '../app-utils/csv-import'\nimport { PLATFORM_BRAND_NAME } from '../app-utils/platform-brand'\nimport { TRANSFER_ID_FIELD, isTransferFieldWritable } from './resource'\nimport type { TransferField, TransferFieldType } from './resource'\n\n/** A heading fields are listed under. */\nexport interface TransferFieldGroup {\n  id: string\n  label: string\n}\n\n/** The group a field with no group, or an unknown one, is listed under. */\nexport const TRANSFER_OTHER_GROUP: TransferFieldGroup = { id: 'other', label: 'Other' }\n\n/** The group custom fields are listed under unless they name their own. */\nexport const TRANSFER_CUSTOM_GROUP: TransferFieldGroup = { id: 'custom', label: 'Custom fields' }\n\n/** The group system fields are listed under unless they name their own. */\nexport const TRANSFER_SYSTEM_GROUP: TransferFieldGroup = { id: 'system', label: 'System' }\n\n/** A resource's fields, grouped and ordered. */\nexport interface TransferFieldCatalog {\n  /** Every field, in picker order: group by group, declaration order within. */\n  fields: TransferField[]\n  byId: ReadonlyMap<string, TransferField>\n  /** The groups that hold at least one field, in order. */\n  groups: TransferFieldGroup[]\n}\n\n/** A custom field as the organization defined it. */\nexport interface TransferCustomFieldDefinition {\n  key: string\n  label: string\n  type?: TransferFieldType\n  picklistId?: string\n  required?: boolean\n  group?: string\n}\n\n/** A custom field definition as a catalog field, with id `custom:<key>`. */\nexport function customTransferField(definition: TransferCustomFieldDefinition): TransferField {\n  return {\n    id: customImportTarget(definition.key),\n    label: definition.label || definition.key,\n    group: definition.group ?? TRANSFER_CUSTOM_GROUP.id,\n    type: definition.type ?? 'text',\n    custom: true,\n    aliases: definition.label && definition.label !== definition.key ? [definition.key] : [],\n    ...(definition.picklistId ? { picklistId: definition.picklistId } : {}),\n    ...(definition.required ? { required: true } : {}),\n  }\n}\n\n/** What a catalog is built from. */\nexport interface TransferCatalogInput {\n  /** The resource's own fields. */\n  standard: readonly TransferField[]\n  /** The organization's custom fields. */\n  custom?: readonly TransferCustomFieldDefinition[]\n  /** Computed fields, exported and never written. */\n  derived?: readonly TransferField[]\n  /** Platform-written fields; the Aglyn id is added when absent. */\n  system?: readonly TransferField[]\n  /** The groups, in order. Groups a field names but this list lacks are listed after these. */\n  groups?: readonly TransferFieldGroup[]\n}\n\n/** The Aglyn id field every catalog carries, labeled with the configured brand. */\nexport function transferIdField(label = `${PLATFORM_BRAND_NAME} ID`): TransferField {\n  return {\n    id: TRANSFER_ID_FIELD,\n    label,\n    group: TRANSFER_SYSTEM_GROUP.id,\n    type: 'text',\n    system: true,\n    readOnly: true,\n    matchKey: true,\n    aliases: [...new Set([`${PLATFORM_BRAND_NAME.toLowerCase()} id`, 'aglyn id', 'record id', 'id'])],\n  }\n}\n\n/**\n * The catalog for a resource.\n *\n * Standard fields come first in their groups, then derived ones, then custom\n * ones, then system ones; within a group the declaration order holds. A\n * field id declared twice keeps its first declaration — a custom field can\n * never shadow a standard one because its id carries the `custom:` prefix.\n */\nexport function buildTransferFieldCatalog(input: TransferCatalogInput): TransferFieldCatalog {\n  const declared: TransferField[] = [\n    ...input.standard,\n    ...(input.derived ?? []).map((field) => ({ ...field, derived: true })),\n    ...(input.custom ?? []).map(customTransferField),\n    ...(input.system ?? []).map((field) => ({\n      ...field,\n      system: true,\n      group: field.group ?? TRANSFER_SYSTEM_GROUP.id,\n    })),\n  ]\n  if (!declared.some((field) => field.id === TRANSFER_ID_FIELD)) declared.push(transferIdField())\n\n  const byId = new Map<string, TransferField>()\n  for (const field of declared) if (!byId.has(field.id)) byId.set(field.id, field)\n  const unique = [...byId.values()]\n\n  // The declared groups in their order, then any group a field names that\n  // was not declared, then the built-in tail (custom, system, other) unless\n  // the resource placed one of those itself.\n  const ordered: TransferFieldGroup[] = []\n  const known = new Set<string>()\n  const addGroup = (group: TransferFieldGroup): void => {\n    if (known.has(group.id)) return\n    known.add(group.id)\n    ordered.push(group)\n  }\n  const builtIn = [TRANSFER_CUSTOM_GROUP, TRANSFER_SYSTEM_GROUP, TRANSFER_OTHER_GROUP]\n  for (const group of input.groups ?? []) addGroup(group)\n  for (const field of unique) {\n    const id = field.group\n    if (id && !builtIn.some((group) => group.id === id)) addGroup({ id, label: id })\n  }\n  for (const group of builtIn) addGroup(group)\n\n  const groupOf = (field: TransferField): string =>\n    field.group && known.has(field.group) ? field.group : TRANSFER_OTHER_GROUP.id\n  const fields = ordered.flatMap((group) => unique.filter((field) => groupOf(field) === group.id))\n  return {\n    fields,\n    byId: new Map(fields.map((field) => [field.id, field])),\n    groups: ordered.filter((group) => fields.some((field) => groupOf(field) === group.id)),\n  }\n}\n\n/** The fields under each group, in catalog order; `fieldIds` narrows and keeps catalog order. */\nexport function groupTransferFields(\n  catalog: TransferFieldCatalog,\n  fieldIds?: readonly string[],\n): { group: TransferFieldGroup; fields: TransferField[] }[] {\n  const wanted = fieldIds ? new Set(fieldIds) : null\n  const groupOf = (field: TransferField): string =>\n    field.group && catalog.groups.some((group) => group.id === field.group) ? field.group : TRANSFER_OTHER_GROUP.id\n  return catalog.groups\n    .map((group) => ({\n      group,\n      fields: catalog.fields.filter(\n        (field) => groupOf(field) === group.id && (!wanted || wanted.has(field.id)),\n      ),\n    }))\n    .filter((entry) => entry.fields.length > 0)\n}\n\n/** The fields whose label, id or an alias contains every word of `query`. */\nexport function searchTransferFields(catalog: TransferFieldCatalog, query: string): TransferField[] {\n  const words = String(query ?? '')\n    .toLowerCase()\n    .split(/\\s+/)\n    .filter(Boolean)\n  if (!words.length) return [...catalog.fields]\n  return catalog.fields.filter((field) => {\n    const haystack = [field.label, field.id, ...(field.aliases ?? [])].join(' ').toLowerCase()\n    return words.every((word) => haystack.includes(word))\n  })\n}\n\n/** The built-in presets. */\nexport type TransferPresetId = 'everything' | 'reimportable' | 'minimal'\n\nexport const TRANSFER_PRESET_IDS: readonly TransferPresetId[] = ['everything', 'reimportable', 'minimal']\n\n/** A preset a person saved: a name and the fields in their chosen order. */\nexport interface TransferSavedPreset {\n  id: string\n  label: string\n  fieldIds: readonly string[]\n}\n\n/**\n * A preset the resource itself offers, listed after the built-in ones: its\n * fields in order and, for a layout another product imports, that\n * product's column name for each field. Its id must not be a built-in\n * preset's.\n */\nexport interface TransferResourcePreset extends TransferSavedPreset {\n  /** One sentence beside the preset in the picker. */\n  description?: string\n  /** Field id → the CSV column name written instead of the field's label. */\n  headers?: Readonly<Record<string, string>>\n}\n\n/** The longest column name a preset or an export request may give a field. */\nexport const TRANSFER_HEADER_MAX = 120\n\n/**\n * The column names an export may write, from what a request or a preset\n * carries: only for the chosen fields, trimmed, non-empty, at most\n * {@link TRANSFER_HEADER_MAX} characters, and never two fields under one\n * name — a file whose columns repeat cannot be read back.\n */\nexport function transferExportHeaders(\n  fieldIds: readonly string[],\n  headers: unknown,\n): Record<string, string> {\n  const out: Record<string, string> = {}\n  if (!headers || typeof headers !== 'object' || Array.isArray(headers)) return out\n  const taken = new Set<string>()\n  for (const fieldId of fieldIds) {\n    const raw = (headers as Record<string, unknown>)[fieldId]\n    if (typeof raw !== 'string') continue\n    const name = raw.trim().slice(0, TRANSFER_HEADER_MAX)\n    const key = name.toLowerCase()\n    if (!name || taken.has(key)) continue\n    taken.add(key)\n    out[fieldId] = name\n  }\n  return out\n}\n\n/** What a resource says about its own presets. */\nexport interface TransferPresetHints {\n  /** The fields a re-import matches on (the id is always included). */\n  matchKeyFieldIds?: readonly string[]\n  /** Fields the minimal preset adds beyond the id, match keys and required ones. */\n  minimalFieldIds?: readonly string[]\n}\n\n/** A resolved selection: the ids to export, in order, and the ids that no longer exist. */\nexport interface TransferFieldSelection {\n  fieldIds: string[]\n  unknown: string[]\n}\n\n/**\n * A list of field ids against the catalog: unknown ids dropped (and\n * reported), duplicates dropped, the given order kept, and every id in\n * `ensure` present — added in catalog order at the front when missing.\n */\nexport function resolveTransferFieldSelection(\n  catalog: TransferFieldCatalog,\n  selected: readonly string[],\n  ensure: readonly string[] = [],\n): TransferFieldSelection {\n  const seen = new Set<string>()\n  const fieldIds: string[] = []\n  const unknown: string[] = []\n  for (const id of selected) {\n    if (seen.has(id)) continue\n    seen.add(id)\n    if (catalog.byId.has(id)) fieldIds.push(id)\n    else unknown.push(id)\n  }\n  const missing = catalog.fields\n    .filter((field) => ensure.includes(field.id) && !fieldIds.includes(field.id))\n    .map((field) => field.id)\n  return { fieldIds: [...missing, ...fieldIds], unknown }\n}\n\n/**\n * The fields a preset exports, in order. A built-in preset is computed from\n * the catalog; a saved one is resolved against it. The re-importable and\n * minimal presets lead with the id and the match keys.\n */\nexport function resolveTransferPreset(\n  catalog: TransferFieldCatalog,\n  preset: TransferPresetId | TransferSavedPreset,\n  hints: TransferPresetHints = {},\n): TransferFieldSelection {\n  // The id leads once, whether or not the match keys name it too.\n  const keys = [...new Set([TRANSFER_ID_FIELD, ...(hints.matchKeyFieldIds ?? [])])].filter((id) => catalog.byId.has(id))\n  const lead = (ids: Iterable<string>): string[] => {\n    const rest = new Set(ids)\n    for (const key of keys) rest.delete(key)\n    return [...keys, ...catalog.fields.filter((field) => rest.has(field.id)).map((field) => field.id)]\n  }\n  if (typeof preset !== 'string') return resolveTransferFieldSelection(catalog, preset.fieldIds)\n  if (preset === 'everything') return { fieldIds: catalog.fields.map((field) => field.id), unknown: [] }\n  if (preset === 'reimportable') {\n    return {\n      fieldIds: lead(catalog.fields.filter(isTransferFieldWritable).map((field) => field.id)),\n      unknown: [],\n    }\n  }\n  const minimal = new Set(hints.minimalFieldIds ?? [])\n  return {\n    fieldIds: lead(\n      catalog.fields.filter((field) => field.required || minimal.has(field.id)).map((field) => field.id),\n    ),\n    unknown: (hints.minimalFieldIds ?? []).filter((id) => !catalog.byId.has(id)),\n  }\n}\n\n/** `ids` with the entry at `from` moved to `to` — the picker's drag to reorder. */\nexport function moveTransferField(ids: readonly string[], from: number, to: number): string[] {\n  const next = [...ids]\n  if (from < 0 || from >= next.length) return next\n  const [moved] = next.splice(from, 1)\n  const at = Math.max(0, Math.min(next.length, to))\n  next.splice(at, 0, moved as string)\n  return next\n}\n"],"names":["customImportTarget","PLATFORM_BRAND_NAME","TRANSFER_ID_FIELD","isTransferFieldWritable","TRANSFER_OTHER_GROUP","id","label","TRANSFER_CUSTOM_GROUP","TRANSFER_SYSTEM_GROUP","customTransferField","definition","key","group","type","custom","aliases","picklistId","required","transferIdField","system","readOnly","matchKey","Set","toLowerCase","buildTransferFieldCatalog","input","declared","standard","derived","map","field","some","push","byId","Map","has","set","unique","values","ordered","known","addGroup","add","builtIn","groups","groupOf","fields","flatMap","filter","groupTransferFields","catalog","fieldIds","wanted","entry","length","searchTransferFields","query","words","String","split","Boolean","haystack","join","every","word","includes","TRANSFER_PRESET_IDS","TRANSFER_HEADER_MAX","transferExportHeaders","headers","out","Array","isArray","taken","fieldId","raw","name","trim","slice","resolveTransferFieldSelection","selected","ensure","seen","unknown","missing","resolveTransferPreset","preset","hints","keys","matchKeyFieldIds","lead","ids","rest","delete","minimal","minimalFieldIds","moveTransferField","from","to","next","moved","splice","at","Math","max","min"],"mappings":"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"}

package/src/lib/data-transfer/header-match.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { TransferField, TransferFieldType } from './resource';
+/** Why a column was proposed for a field. */
+export type HeaderMatchReason = 'exactAlias' | 'normalizedAlias' | 'fuzzy' | 'typeInference';
+/** Extra header spellings for a resource's fields, from one source. */
+export interface TransferAliasDictionary {
+    /** Who the spellings come from, shown beside the match ("Spreadsheet export"). */
+    source: string;
+    /** Field id → header spellings. */
+    aliases: Readonly<Record<string, readonly string[]>>;
+}
+/** What a column's sample cells look like. */
+export type InferredCellType = 'email' | 'phone' | 'url' | 'date' | 'number' | 'currency' | 'boolean' | 'text';
+/** One candidate field for a column. */
+export interface HeaderCandidate {
+    fieldId: string;
+    confidence: number;
+    reason: HeaderMatchReason;
+    /** The alias that matched, as written. */
+    alias?: string;
+    /** The dictionary the alias came from, when a plugin supplied it. */
+    source?: string;
+}
+/** The proposal for one column. */
+export interface HeaderMatchProposal {
+    column: number;
+    header: string;
+    /** The proposed field, or `null` to leave the column unmapped. */
+    fieldId: string | null;
+    confidence: number;
+    reason: HeaderMatchReason | null;
+    alias?: string;
+    source?: string;
+    /** The next-best candidates, strongest first. */
+    alternatives: HeaderCandidate[];
+    /** What the sample cells look like, when samples were given. */
+    inferredType: InferredCellType | null;
+    /** The column wanted a field another column took. */
+    lostField?: string;
+}
+/** Two or more columns that want one field. */
+export interface HeaderMatchConflict {
+    fieldId: string;
+    /** Every column whose best candidate was the field, the winner first. */
+    columns: number[];
+}
+export interface HeaderMatchResult {
+    proposals: HeaderMatchProposal[];
+    /** Column → field id, for every column with a proposal. */
+    mapping: Record<number, string>;
+    conflicts: HeaderMatchConflict[];
+    /** Required fields no column was proposed for. */
+    unmappedRequired: string[];
+}
+export interface HeaderMatchOptions {
+    /** Plugin-supplied spellings, tried after the fields' own. */
+    dictionaries?: readonly TransferAliasDictionary[];
+    /** Sample rows (cells in column order) for type inference. */
+    samples?: readonly (readonly unknown[])[];
+    /** The least confidence a fuzzy match is proposed at; default 0.72. */
+    threshold?: number;
+}
+/** The default least confidence a fuzzy proposal is made at. */
+export declare const HEADER_MATCH_THRESHOLD = 0.72;
+/**
+ * A header folded for comparison: accents dropped, `camelCase` split,
+ * punctuation and underscores to spaces, lowercased, single-spaced.
+ * `First_Name`, `firstName` and `first name` fold together.
+ */
+export declare function normalizeHeader(value: unknown): string;
+/** A header with every separator removed: `e-mail` and `email` compare equal. */
+export declare function compactHeader(value: unknown): string;
+/**
+ * What a column's cells look like: the type at least 80% of its non-blank
+ * samples read as, or `text`. `null` when there is no non-blank sample.
+ */
+export declare function inferCellType(cells: readonly unknown[]): InferredCellType | null;
+/** Whether a field of `type` would take cells that look like `inferred`. */
+export declare function inferredTypeFits(type: TransferFieldType, inferred: InferredCellType): boolean;
+/** Every candidate field for one header, strongest first. */
+export declare function headerCandidates(header: string, fields: readonly TransferField[], options?: Pick<HeaderMatchOptions, 'dictionaries' | 'threshold'>): HeaderCandidate[];
+/**
+ * A proposal for every column of a file.
+ *
+ * Candidates are scored per column, nudged by type inference where samples
+ * were given (a fitting type breaks a near tie; a clearly misfitting one is
+ * demoted), then assigned greedily strongest first so each field goes to
+ * one column. A column with no header candidate but distinctive cells (all
+ * emails, all phones, all web addresses) is offered the one importable
+ * field of that type nobody took.
+ */
+export declare function matchHeaders(headers: readonly string[], fields: readonly TransferField[], options?: HeaderMatchOptions): HeaderMatchResult;
+/** Required fields a mapping leaves without a column. */
+export declare function mappingUnmappedRequired(mapping: Readonly<Record<number, string | null | undefined>>, fields: readonly TransferField[]): string[];
+/** What is wrong with a mapping as the person left it. */
+export interface MappingProblems {
+    /** Fields two or more columns are mapped to. */
+    duplicates: HeaderMatchConflict[];
+    /** Required fields with no column. */
+    unmappedRequired: string[];
+    /** Columns mapped to a field that does not exist or cannot be imported. */
+    invalid: {
+        column: number;
+        fieldId: string;
+    }[];
+}
+/**
+ * The problems that must be resolved before a mapping can be used: a field
+ * two columns write, a required field nobody writes, a target that cannot
+ * be imported.
+ */
+export declare function mappingProblems(mapping: Readonly<Record<number, string | null | undefined>>, fields: readonly TransferField[]): MappingProblems;
+/** Whether a mapping has nothing that blocks it. */
+export declare function mappingIsUsable(problems: MappingProblems): boolean;