Configure

Register the element once, then configure each instance with attributes (strings) and properties (objects/functions).

import { defineImportSuiteElement, mountImportFlow } from '@capitality-io/mildport-widget';
await defineImportSuiteElement('mildport-import');

One configuration surface: `targets`

Declare what record types can be created and which fields each carries. Mildport derives matching, validation, and capture-first UX from this catalog internally.

Scenario	Example
Capture-first (PDF, photo, notes)	Multiple targets — Contact, Lead, Task…
Multi-entity spreadsheet	`{ id: 'person', fields: [...] }`, `{ id: 'organization', fields: [...] }`
Single flat CSV	One target — `{ id: 'contact', fields: [...] }`

Recommended: use mountImportFlow() to bundle targets, upload flags, apply mode, and mapping memory. See Capture-first imports.

Attributes

Attribute	Description
`api-base-url`	Origin of your self-hosted (or pilot) engine, e.g. `https://imports.your-infra.example`.
`license-key`	The signed tenant license key the engine verifies offline.
`catalog-key`	Pin one published server catalog for this embed. Optional: without it the widget auto-adopts a single listed catalog or offers a picker in the context bar. Which catalogs the picker offers — and which one adopts by default — are server-side per-catalog settings (star / unlist), not embed config.
`catalog-project`	Sub-project key — the catalog fetch applies that project’s stored override.
`targets-mode`	`replace` (default) or `patch` — treat `targets` as a per-launch patch over the server catalog.
`offline`	No server at all: files parse in-browser, matching runs the bundled matcher, apply stays in-page. Schema comes from `targets` or the in-widget Define-fields step.
`grid-impl`	Review-grid implementation (e.g. `slickgrid`).

<mildport-import
  api-base-url="https://imports.your-infra.example"
  license-key="SIGNED_TENANT_KEY"
  grid-impl="slickgrid"
></mildport-import>

Properties

Property	Type	Description
`targets`	`TargetCatalog`	Record types + field metadata (types, validators, matcher aliases). Required unless `catalog-key` is set.
`applyMode`	`'webhook' \| 'browser'`	Deliver via a signed apply webhook, or hand rows back in-page.
`mappingIdentifier`	`string \| null`	Stable id so confirmed mappings are remembered across imports.
`hostConfig`	`ImportSuiteHostConfig`	Accepted formats, multi-file joins, cleaning hooks, sample data, AI cleaning level (`aiTransforms: 'off' \| 'suggest' \| 'full'`) and audit `actor`.
`profile`	`ImportProfile`	A committed import profile (`{mapping?, recipe?}`): the mapping auto-applies on Match, the recipe shows as a one-click cleanup suggestion on Review.
`onResults`	`(rows, mapping) => void`	Browser-mode callback with the delivered rows + mapping.

Example — `mountImportFlow` (recommended)

const el = document.querySelector('mildport-import')!;

mountImportFlow(el, {
  id: 'tenant-contacts',
  version: 'v1',
  targets: [
    {
      id: 'person',
      label: 'Person',
      fields: [
        {
          key: 'person.firstName',
          label: 'First name',
          alternativeMatches: ['given name', 'vorname'],
        },
        {
          key: 'person.email',
          label: 'Email',
          columnType: 'email',
          required: true,
        },
      ],
    },
    {
      id: 'organization',
      label: 'Organization',
      fields: [{ key: 'organization.name', label: 'Company name' }],
    },
  ],
  input: { acceptedFormats: ['spreadsheet', 'text', 'pdf', 'image'] },
  delivery: { mode: 'browser' },
});

el.onResults = (rows, mapping) => sync(rows, mapping);

Example — set `targets` directly

el.targets = [
  {
    id: 'contact',
    label: 'Contact',
    fields: [
      { key: 'contact.email', label: 'Email', columnType: 'email', required: true },
      { key: 'contact.name', label: 'Name' },
    ],
  },
];
el.applyMode = 'browser';
el.hostConfig = { acceptedFormats: ['pdf', 'image', 'text', 'spreadsheet'] };

Next: Events & apply.