@wix/patterns 1.419.0 → 1.420.0

package/src/components/ImportButton/CAIRO-4118-tasks.md

@@ -26,7 +26,7 @@ This tracker turns the ticket's task spec into individually-trackable items. All
 |---|---|---|---|---|
 | 2.1 | Duplicate field mapping | Once a collection field is selected in one dropdown, **disable** it (visible but unselectable) in all other dropdowns | done | Shipped in PR #5130 (`feat(Import): disable already selected fields`). `ImportState.selectedFieldIds` (computed `Set` of mapped field ids) drives the per-dropdown `disabled` flag in `ImportStepConfiguration.tsx`: an option is disabled when `selectedFieldIds.has(option.id)` **and** it isn't the current header's own selection (so the field stays selectable in its own dropdown). Tests: *"disables already-selected fields in other dropdowns"*, *"does not disable a field in its own dropdown"* in `Table.importButton.spec.tsx` (both passing). |
 | 2.2 | Zero data rows | Show an **inline warning notice** inside step 2 (non-blocking) — user can still proceed or go back. [Design](https://www.figma.com/design/RpB9iQ6a43xcvKiovmJaA1/Import?node-id=72-39072) | done | Inline `SectionHelper` (skin `warning`, hook `import-no-rows-warning`) in `ImportStepConfiguration.tsx` with keys `cairo.import.noRowsWarningTitle` / `noRowsWarningDescription`. Trigger broadened from `csvRows.length === 0` to the new `ImportState.hasNoMappedData` computed — true when there are mappings but **no mapped column holds data in any row** (matching the design copy "no data was found inside the mapped columns"); it reacts to mapping changes and stays false when nothing is mapped yet (that case is covered by the disabled Import button + `noMappingsTooltip`). Non-blocking: Import stays enabled whenever `hasMappings` is true. Tests in `Table.importButton.spec.tsx`: *"...shows warning for CSV with headers but no rows"*, *"shows the warning when rows exist but the mapped columns are empty"*, *"does not show the warning when a mapped column has data"*. Keys already registered in the Translation Center. |
-| 2.3 | Mismatch between CSV data and chosen field | Dropdown enters **error state** with a status message | open | — |
+| 2.3 | Mismatch between CSV data and chosen field | Dropdown enters **error state** with a status message | open | Tracked in [CAIRO-4392](https://wix.atlassian.net/browse/CAIRO-4392) (relates to CAIRO-4118). Needs design: reuse existing field validators to validate every CSV row client-side, with open questions on coverage/perf, blocking vs non-blocking, and how it reconciles with the planned client→server async-import migration. |
 
 ## Step 3 — Progress: Full Import Failures
 

package/src/components/ImportButton/CAIRO-4230-create-new-field.md

@@ -0,0 +1,188 @@
+# CAIRO-4230 — Import CSV: map a column to a *new* field (create-on-import)
+
+> High-level implementation summary. Not a line-by-line plan — see the tickets for
+> the full spec/design.
+>
+> - **CAIRO-4230** — Import CSV: Support "Add New Field" flow (this task)
+> - **CAIRO-4131** — Suggest field type from column data (the design/visual source;
+>   we only borrow the "create new field" mechanic from it, not the type detection)
+> - Design: https://www.figma.com/design/RpB9iQ6a43xcvKiovmJaA1/Import?node-id=81-110873
+
+## Goal
+
+Today, an unmapped CSV column defaults to **"Don't import"** (`mappingByHeader[header] = null`).
+We want to optionally let the user map a column to a **brand-new collection field that
+is created as part of the import flow itself** — shown in the mapping dropdown as
+`<Column Title> (New)` with the helper text *"This will be a new text field. Edit Field"*
+(see image in CAIRO-4131).
+
+## Scope (what we are building now vs. not)
+
+**In scope**
+- Ability to create a new field from an unmapped column during the mapping step.
+- Field type is **always `text` for now** (no data-driven type detection).
+- A way to **choose the default behavior** for unmapped columns (create new field vs.
+  don't import). Likely the **presence of the create-field callback prop itself is the
+  opt-in** (see below) — no separate flag.
+
+**Out of scope (deferred — CAIRO-4131)**
+- CSV column **type detection** (Number/Date/Boolean/URL/Text "best fit"). The
+  `(New)` suggestion will always be a text field for now.
+- The "Edit Field" entry point that opens a type selector pre-populated with the
+  detected type. (We may still surface a static "This will be a new text field"
+  label, but no editing flow.)
+
+> Note: the **default-behavior prop is the deliverable the tickets call out explicitly**
+> ("some entry points want this as default, some want 'don't import' as a default").
+
+## Key design point — configurability via the callback prop
+
+Field creation is exposed as a new **callback prop, a sibling to `bulkUploadItems`**:
+`updateSchema`. The **presence of that callback is itself the opt-in**:
+
+- `updateSchema` provided → unmapped columns default to **create new (text) field**.
+- `updateSchema` absent → current behavior, unmapped columns default to **don't import**.
+
+This avoids a separate `unmappedColumnDefault` flag: a consumer can only create fields
+if it gives us the means to (the callback), so wanting the behavior and providing the
+capability are the same decision. This is what `getDefaultMapping` keys off when
+assigning the default for a column that didn't auto-match an existing field.
+
+> If a consumer later needs "provide `updateSchema` but still default to don't import",
+> we can add an explicit override flag then — but start with the implicit form.
+
+## Data model changes (`packages/core/src/state/ImportState/ImportState.ts`)
+
+Today a mapping value is `string | null` (existing field id, or skip). To represent
+"create a new text field for this column" we need a third state. Options (pick during
+implementation):
+
+- Extend the mapping value to a discriminated shape, e.g.
+  `{ kind: 'existing'; fieldId } | { kind: 'new'; fieldKey; fieldType: 'text' } | null`, or
+- Keep `mappingByHeader` for existing-field mappings and add a parallel
+  `newFieldByHeader` set/record for columns flagged as "create new".
+
+Whichever is chosen, the following must be updated accordingly:
+- `getDefaultMapping` — honor the new default-behavior prop for unmatched columns.
+- `hasMappings` / `hasNoMappedData` / `selectedFieldIds` — a "create new" column
+  counts as a real mapping.
+- `mappedRows` / `toMappedRows` — rows must write column data under the new field's
+  key/id so the values get uploaded.
+- `setMapping` — needs a way to set a column to "create new field".
+
+## New-field creation on import — single `updateSchema` call
+
+New fields must exist in the collection before the rows upload, otherwise the
+uploaded values have nowhere to land. Following the cm-import `beforeImport` flow
+(`wix-data-client/cm-import/.../progress/actions.js`), **all new fields are added
+in a single call** — not one call per field. The callback is modeled after
+`bulkUploadItems` (consumer supplies the actual mutation; Cairo orchestrates):
+
+```ts
+interface NewFieldDefinition { key: string; type: 'text'; displayName: string }
+type UpdateSchemaFn = (fields: NewFieldDefinition[]) => Promise<void>;
+```
+
+The consumer maps these to one schema mutation, e.g.
+`updateSchema(collectionId, ...fields.map(f => addField(f.key, f)))`.
+
+**Keys are decided by Cairo, not returned by the consumer.** `_resolveFieldMapping`
+derives each new field's `key` from the column header (`uniqueFieldKey`, camelCase +
+numeric suffix, deduped against existing field ids and other new keys), passes the
+list to `updateSchema`, and uses that same key as the upload payload key. So no id
+round-trip is needed and there's no per-field parallelism/collision concern.
+
+In `startImport`, after backup and before `_uploadBatches`:
+1. Collect all "create new" columns and derive their keys.
+2. Call `updateSchema(newFields)` once.
+3. Build the upload payload keyed by those keys (+ existing field ids).
+4. Proceed with the existing batch upload.
+
+If `updateSchema` throws, the import enters the **error state** with a "Try again"
+CTA (no rows uploaded). Open questions: whether created fields should be rolled
+back on a later failure/cancel (currently not — restore covers row data only).
+
+## UI changes (`packages/cairo/src/components/ImportButton/ImportStepConfiguration.tsx`)
+
+- Add a `<Column Title> (New)` option (or per-column toggle) to the mapping `Dropdown`.
+- When a column is set to "create new", render the helper text
+  *"This will be a new text field."* under the dropdown (the "Edit Field" link is
+  out of scope for now — omit or render disabled).
+- Match the design's warning/`(New)` visual treatment from CAIRO-4131 (yellow accent).
+
+## Wiring (props path)
+
+The new prop (`updateSchema`) follows the existing chain, exactly like `bulkUploadItems`:
+
+`ImportButtonProps` / `ImportModalProps` (`ImportProps.tsx`)
+→ `ImportButtonModalLayout.tsx`
+→ `useCreateImport({ ... })`
+→ `ImportStateProps` → `ImportState` constructor.
+
+All new props should be **optional** and additive to keep the change backward-compatible
+(core is widely consumed — see `packages/core/AGENTS.md`).
+
+## Translations
+
+New keys (route through the Wix Translation Center — core `en.json` and the generated
+`translations.ts` are gitignored and rebuilt from TC, so the local additions made
+during implementation are **not** committed and must be registered in TC):
+- `cairo.import.newFieldSuffix` (core) → `"(New)"` — appended in code to the CSV
+  column header to form the option label (e.g. `Title (New)`). The header is built
+  in code (not via an interpolated key) so the column name always shows.
+- `cairo.import.newFieldHelper` (core) → `"This will be a new {typeName} field."` —
+  the `{typeName}` param is the field-type name, injected lowercased (matching the
+  patterns-fields `type_mismatch_*` convention).
+- `auto-patterns.fields.field_type_text_title` (**patterns-fields**) → `"Text"` —
+  the shared field-type name reused for the type label. Future types reuse the
+  existing `auto-patterns.fields.field_type_<type>_title` keys.
+
+(`cairo.import.newFieldOption` = `"{column} (New)"` and `cairo.import.fieldType.text`
+were earlier forms; superseded.)
+
+### Field type is static (`text`) but the code is dynamic-ready
+- `NewFieldType` (core) is the single source of truth for the type union — today
+  just `'text'`.
+- The mapping carries `fieldType` end-to-end: `setNewFieldMapping` /
+  `getDefaultMapping` set it, and `_resolveFieldMapping` passes it to
+  `updateSchema`. To go dynamic, set the detected type there instead of `'text'`.
+- The helper text resolves the type name from the **shared patterns-fields**
+  field-type translations via `NEW_FIELD_TYPE_TITLE_KEY`, a
+  `Record<NewFieldType, …>` in `ImportStepConfiguration`. Widening `NewFieldType`
+  makes the missing entries a **compile error** — the one place to extend.
+- Those translations live in the patterns-fields artifact (fields'
+  `useTranslations()`), so the import modal is wrapped in `PatternsFieldsProvider`
+  **only when field creation is enabled** (`ImportButtonModalLayout`). The provider/
+  fields container is not initialized for plain imports.
+
+## Testing
+
+- Core/cairo: `Table.importButton.spec` — default mapping under updateSchema
+  present/absent, the single `updateSchema` call with all new fields, upload payload
+  keyed by derived keys, helper text, and schema-update failure → error state.
+- Follow existing Import test patterns (`InMemoryBackend`, `flush()`).
+
+## Decisions made during implementation
+- **Mapping model:** `mappingByHeader` value is now a discriminated `ColumnMapping`
+  = `{kind:'existing', fieldId} | {kind:'new', fieldType:'text'} | null`.
+- **Field creation:** runs in `startImport` **after** backup and **before** the batch
+  upload, via `_resolveFieldMapping()`. All "new" columns are added in **one**
+  `updateSchema(fields)` call; their keys are Cairo-derived (`uniqueFieldKey`) and
+  reused as the upload payload keys — no id round-trip.
+- **Failure handling:** if `updateSchema` throws, the import enters the **error state**
+  with a "Try again" CTA (same path as a first-batch upload failure); no rows upload.
+- **UI:** a synthetic `(New)` option is appended to each column dropdown when
+  `canCreateNewField`; selecting it shows the helper text. Clearing still means
+  "don't import" (`null`).
+
+## Still open (consumer/CMS side)
+- Whether created fields should be rolled back on cancel/restore (currently they are
+  not — restore only covers row data).
+- **Consumer wiring:** `auto-patterns` `useImport` must implement `updateSchema`
+  (one batched schema mutation, e.g. `updateSchema(collectionId, ...addField(...))`),
+  replacing the earlier per-field `createField`/`addField` path — pending a new
+  `@wix/patterns` publish.
+
+## AGENTS.md impact
+
+- Status: not needed (feature work inside an existing component/state pattern).

package/src/components/ImportButton/ImportButton.tsx

@@ -16,6 +16,7 @@ function _ImportButton<T, F extends FiltersMap>(props: ImportButtonProps) {
     fields,
     bulkUploadItems,
     backup,
+    updateSchema,
     batchSize,
   } = props;
 
@@ -38,6 +39,7 @@ function _ImportButton<T, F extends FiltersMap>(props: ImportButtonProps) {
               fields={fields}
               bulkUploadItems={bulkUploadItems}
               backup={backup}
+              updateSchema={updateSchema}
               batchSize={batchSize}
             />
           );

package/src/components/ImportButton/ImportButtonModalLayout.tsx

@@ -17,12 +17,14 @@ import { CustomDrawerLayout } from '../CustomDrawerLayout';
 import { ImportStepper } from './ImportStepper';
 import { MessageActionModal } from '../ActionModal';
 import { ModalWrapper } from '../CollectionModal';
+import { PatternsFieldsProvider } from '../../providers';
 
 function _ImportButtonModalLayout(props: ImportButtonModalLayoutProps) {
   const {
     fields,
     bulkUploadItems,
     backup,
+    updateSchema,
     batchSize,
     importModalState,
     ...rest
@@ -34,6 +36,7 @@ function _ImportButtonModalLayout(props: ImportButtonModalLayoutProps) {
     fields,
     bulkUploadItems,
     backup,
+    updateSchema,
     batchSize,
     importModalState,
   });
@@ -63,6 +66,16 @@ function _ImportButtonModalLayout(props: ImportButtonModalLayoutProps) {
       children
     );
 
+  // The configuration step's "new field" helper reads field-type names from the
+  // patterns-fields translations, which require this provider. Only mounted when
+  // field creation is enabled (the only case a "new" mapping can exist), so the
+  // fields container isn't initialized for plain imports.
+  const content = state.canCreateNewField ? (
+    <PatternsFieldsProvider>{wrappedChildren}</PatternsFieldsProvider>
+  ) : (
+    wrappedChildren
+  );
+
   useEffect(() => {
     if (onRequestClose) {
       return addEventListener(
@@ -89,7 +102,7 @@ function _ImportButtonModalLayout(props: ImportButtonModalLayoutProps) {
           removeContentPadding={removeContentPadding}
           {...rest}
           {...customModalLayoutProps}
-          children={wrappedChildren}
+          children={content}
         />
         <ModalWrapper
           state={discardModal}
@@ -142,7 +155,7 @@ function _ImportButtonModalLayout(props: ImportButtonModalLayoutProps) {
         removeContentPadding={removeContentPadding}
         {...rest}
         {...customModalLayoutProps}
-        children={wrappedChildren}
+        children={content}
       />
       <MessageActionModal
         dataHook="import-discard-changes-modal"

package/src/components/ImportButton/ImportModal.uni.driver.ts

@@ -90,6 +90,16 @@ export function ImportModalUniDriver(base: UniDriver, body: UniDriver) {
         body,
       ),
 
+    /** Text of the "new field" helper line under a column's mapping dropdown */
+    getNewFieldHelperText: (header: string) =>
+      modalLayoutBase()
+        .$(`[data-hook="import-new-field-helper-${header}"]`)
+        .text(),
+    newFieldHelperExists: (header: string) =>
+      modalLayoutBase()
+        .$(`[data-hook="import-new-field-helper-${header}"]`)
+        .exists(),
+
     /** Get the Dropdown driver for a specific CSV header mapping */
     getMappingDropdown: (header: string) =>
       DropdownUniDriver(

package/src/components/ImportButton/ImportProps.tsx

@@ -1,4 +1,9 @@
-import { BackupFn, BulkUploadItemsFn, ModalState } from '@wix/bex-core';
+import {
+  BackupFn,
+  BulkUploadItemsFn,
+  UpdateSchemaFn,
+  ModalState,
+} from '@wix/bex-core';
 import { CreateExportAsyncJobRequest } from '@wix/bex-utils/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/types';
 
 type ImportButtonToolbarType = 'default' | 'bulkActionToolbar';
@@ -7,6 +12,13 @@ export interface ImportButtonParams
   extends Pick<CreateExportAsyncJobRequest, 'fields'> {
   bulkUploadItems: BulkUploadItemsFn;
   backup?: BackupFn;
+  /**
+   * Adds new collection fields during import, in a single call, before the rows
+   * upload. When provided, unmapped CSV columns default to creating a new (text)
+   * field instead of "don't import". When omitted, behavior is unchanged
+   * (unmapped columns default to skip).
+   */
+  updateSchema?: UpdateSchemaFn;
   batchSize?: number;
 }
 

package/src/components/ImportButton/ImportStepConfiguration.tsx

@@ -7,7 +7,8 @@ import {
   SectionHelper,
 } from '@wix/design-system';
 import { ArrowRight } from '@wix/wix-ui-icons-common';
-import { ImportState } from '@wix/bex-core';
+import { ImportState, NewFieldType } from '@wix/bex-core';
+import { useTranslations } from '@wix/patterns-fields';
 import React from 'react';
 import { observer } from 'mobx-react-lite';
 
@@ -22,6 +23,134 @@ const COLUMN_WIDTHS = {
 };
 const SCROLLBAR_GUTTER: React.CSSProperties = { scrollbarGutter: 'stable' };
 
+// Synthetic dropdown option id representing "create a new field from this
+// column". Distinct from any real field id (which never starts with `$`).
+const CREATE_NEW_FIELD_OPTION_ID = '$createNewField';
+
+// Translation key for each new-field type's name, injected (lowercased) into the
+// helper text ("This will be a new {typeName} field."). Reuses the shared
+// patterns-fields field-type names. Keyed by `NewFieldType` so that when
+// CAIRO-4131 adds data-driven types (number/date/boolean/url/...), the missing
+// entries become a compile error here — the single place to extend.
+type FieldTypeTitleKey = 'auto-patterns.fields.field_type_text_title';
+
+const NEW_FIELD_TYPE_TITLE_KEY: Record<NewFieldType, FieldTypeTitleKey> = {
+  text: 'auto-patterns.fields.field_type_text_title',
+};
+
+type DropdownOption = ReturnType<typeof listItemSelectBuilder>;
+
+interface NewFieldHelperTextProps {
+  state: ImportState;
+  header: string;
+  fieldType: NewFieldType;
+}
+
+/**
+ * Helper line under a "create new field" mapping (e.g. "This will be a new text
+ * field."). The type name comes from the shared patterns-fields translations via
+ * `useTranslations`, so this is only rendered when the import modal is wrapped in
+ * `PatternsFieldsProvider` — which `ImportButtonModalLayout` does whenever field
+ * creation is enabled (the only case a `new` mapping exists).
+ */
+const NewFieldHelperText = observer(function _NewFieldHelperText({
+  state,
+  header,
+  fieldType,
+}: NewFieldHelperTextProps) {
+  const { t: ft } = useTranslations();
+  const typeName = ft(NEW_FIELD_TYPE_TITLE_KEY[fieldType]).toLocaleLowerCase();
+
+  return (
+    <Text size="tiny" secondary dataHook={`import-new-field-helper-${header}`}>
+      {state.translate('cairo.import.newFieldHelper', { typeName })}
+    </Text>
+  );
+});
+
+interface FieldMappingCellProps {
+  state: ImportState;
+  header: string;
+  fieldOptions: DropdownOption[];
+}
+
+const FieldMappingCell = observer(function _FieldMappingCell({
+  state,
+  header,
+  fieldOptions,
+}: FieldMappingCellProps) {
+  const { translate: t, selectedFieldIds, canCreateNewField } = state;
+  const mapping = state.mappingByHeader[header];
+
+  const selectedId =
+    mapping?.kind === 'existing'
+      ? mapping.fieldId
+      : mapping?.kind === 'new'
+      ? CREATE_NEW_FIELD_OPTION_ID
+      : undefined;
+
+  const options: DropdownOption[] = [
+    ...fieldOptions.map((option) => ({
+      ...option,
+      disabled:
+        selectedFieldIds.has(String(option.id)) &&
+        !(mapping?.kind === 'existing' && mapping.fieldId === String(option.id)),
+    })),
+    ...(canCreateNewField
+      ? [
+          // The option is the CSV column header itself (the new field is named
+          // after it) followed by a translated "(New)" marker. The header is
+          // built in code rather than via an interpolated key so it always
+          // shows, regardless of which translation bundle the consumer loads.
+          (() => {
+            const label = `${header} ${t('cairo.import.newFieldSuffix')}`;
+            return listItemSelectBuilder({
+              id: CREATE_NEW_FIELD_OPTION_ID,
+              label,
+              title: label,
+            });
+          })(),
+        ]
+      : []),
+  ];
+
+  return (
+    <Box direction="vertical" gap="SP1">
+      <Dropdown
+        dataHook={`import-mapping-${header}`}
+        clearButton
+        onClear={() => {
+          state.setMapping(header, null);
+        }}
+        placeholder={t('cairo.import.skipColumn')}
+        selectedId={selectedId}
+        onSelect={({ id }) => {
+          if (id === CREATE_NEW_FIELD_OPTION_ID) {
+            state.setNewFieldMapping(header);
+          } else {
+            state.setMapping(header, id as string);
+          }
+        }}
+        popoverProps={{
+          appendTo: 'window',
+          zIndex: 5001,
+          flip: true,
+          fixed: false,
+        }}
+        options={options}
+        size="small"
+      />
+      {mapping?.kind === 'new' && (
+        <NewFieldHelperText
+          state={state}
+          header={header}
+          fieldType={mapping.fieldType}
+        />
+      )}
+    </Box>
+  );
+});
+
 function _ImportStepConfiguration({ state }: ImportStepConfigurationProps) {
   const { csvHeaders, fields, translate: t } = state;
 
@@ -35,8 +164,6 @@ function _ImportStepConfiguration({ state }: ImportStepConfigurationProps) {
       }),
     );
 
-  const { selectedFieldIds } = state;
-
   const hasNoRows = state.hasNoMappedData;
 
   return (
@@ -109,30 +236,10 @@ function _ImportStepConfiguration({ state }: ImportStepConfigurationProps) {
                 },
                 {
                   value: (
-                    <Dropdown
-                      dataHook={`import-mapping-${header}`}
-                      clearButton
-                      onClear={() => {
-                        state.setMapping(header, null);
-                      }}
-                      placeholder={t('cairo.import.skipColumn')}
-                      selectedId={state.mappingByHeader[header] ?? undefined}
-                      onSelect={({ id }) => {
-                        state.setMapping(header, id as string);
-                      }}
-                      popoverProps={{
-                        appendTo: 'window',
-                        zIndex: 5001,
-                        flip: true,
-                        fixed: false,
-                      }}
-                      options={baseDropdownOptions.map((option) => ({
-                        ...option,
-                        disabled:
-                          selectedFieldIds.has(String(option.id)) &&
-                          state.mappingByHeader[header] !== String(option.id),
-                      }))}
-                      size="small"
+                    <FieldMappingCell
+                      state={state}
+                      header={header}
+                      fieldOptions={baseDropdownOptions}
                     />
                   ),
                   width: COLUMN_WIDTHS.field,

package/src/components/ImportButton/ImportStepUpload.st.css.ts

@@ -5,7 +5,7 @@ import { classesRuntime, statesRuntime } from "../../stylable-esm-runtime.js";
 
 
 
-var _namespace_ = "ImportStepUpload72349518";
+var _namespace_ = "ImportStepUpload2837626154";
 var _style_ = classesRuntime.bind(null, _namespace_);
 
 export var cssStates = statesRuntime.bind(null, _namespace_);
@@ -13,7 +13,7 @@ export var style = _style_;
 export var st: import("@stylable/runtime").STFunction = _style_;
 
 export var namespace = _namespace_;
-export var classes = {"root":"ImportStepUpload72349518__root","fileUpload":"ImportStepUpload72349518__fileUpload"};
+export var classes = {"root":"ImportStepUpload2837626154__root","fileUpload":"ImportStepUpload2837626154__fileUpload"};
 export var keyframes = {}; 
 export var layers = {};
 export var containers = {};