@wix/patterns 1.426.0 → 1.427.0

package/dist/docs/ImportButton.md

@@ -0,0 +1,527 @@
+# ImportButton
+
+**Category:** Features/Import
+
+## Design
+
+### Description
+
+The `ImportButton` is the platformized solution for importing a CSV file into a collection.
+
+It renders an import action in the collection toolbar. On the default toolbar it shows a `ResponsiveButton`; on a bulk-action toolbar (`toolbarType="bulkActionToolbar"`) it shows a small secondary `Button`. Clicking it opens a multi-step modal (a `Drawer` on mobile) that walks the user through:
+
+1. **Upload** — pick a `.csv` file.
+2. **Map columns** — match each CSV column to an existing collection field, create a new field for it, or skip it.
+3. **Import** — the rows are sent to the server and progress is shown.
+4. **Summary** — created / updated / failed counts, with a "Download CSV" of the failed rows when some rows were rejected.
+
+Like `ExportTo`, the feature has two parts:
+
+- **Client** — the button and modal, shipped in `@wix/patterns`. You configure it with a single `config` object plus a `renderFieldEditor`, both produced by a **source hook** (below), and place it with the `` `importButton` prop.
+- **Server** — the actual write is done by a Wix Hub **Data Movement** job (see the [data-hub infrastructure](#data-hub-infrastructure) section). The client uploads the file, submits the job, and polls it to completion.
+
+#### Choosing a source hook
+
+`ImportButton` never takes hand-built inputs. You pick the hook that matches where the data is written, and spread its result onto ``:
+
+- **CMS (Wix Data)** — [`useSchemaImport`](./?path=/story/features-import--use-schema-import). Reads the import inputs live from the same schema source that backs the table, and supplies the CMS create/edit-field modal.
+
+  ```jsx
+  import { ImportButton, useSchemaImport } from '@wix/patterns';
+
+  const importProps = useSchemaImport(schemaSource);
+
+  } />;
+  ```
+
+- **Platformized (non–Wix-Data destination)** — [`usePlatformizedImport`](./?path=/story/features-import--use-platformized-import). For a target such as the stores catalog. Reads the table's toolbar so a DataExtension source's live fields are wired in.
+
+  ```jsx
+  import { ImportButton, usePlatformizedImport } from '@wix/patterns';
+
+  const importProps = usePlatformizedImport({
+    state,
+    destination: { storesCatalogProducts: {} },
+    fields: [{ id: 'name', header: 'Name', required: true }],
+  });
+
+  } />;
+  ```
+
+See each hook's page for its full props.
+
+#### data-hub infrastructure
+
+The import runs **entirely server-side** in [Wix Data Hub](https://github.com/wix-private/wix-data-hub) — a generic data-movement job executor. The client drives it through the `@wix/ambassador-hub-v1-job` API ([job submission & monitoring](https://github.com/wix-private/cloud/blob/master/hub/wix-data-hub-fs2)); the actual reading/writing is done by the [Data Hub executor](https://github.com/wix-private/wix-data-hub/blob/master/packages/wix-data-hub-executor-c/README.md), whose model is: a **source** reads batches, **transformations** alter them, and a **destination** writes them. The client only:
+
+1. Reserves an upload URL and PUTs the (rewritten) CSV, receiving a `fileId`.
+2. Submits a job (`source: { file }`, `destination`) and receives a `jobId`.
+3. Polls the job every 2 seconds until it reaches `COMPLETED`, `PARTIALLY_SUCCESSFUL`, or `FAILED`.
+4. Lists the job's per-row movement logs to build the failed-rows CSV, and terminates the job if the user cancels. Terminating does **not** roll back rows already written — that is what an optional `backup` (on either hook) is for.
+
+The **`destination`** you pass identifies which executor [destination](https://github.com/wix-private/wix-data-hub/blob/master/packages/wix-data-hub-executor-c/src/api/destination.ts) writes the rows — e.g. `{ wixDataCollection: … }` ([wix-data-collection](https://github.com/wix-private/wix-data-hub/tree/master/packages/wix-data-hub-executor-c/src/plugins/wix-data-collection) plugin) or `{ storesCatalogProducts: {} }` ([online-stores](https://github.com/wix-private/wix-data-hub/tree/master/packages/wix-data-hub-executor-c/src/plugins/online-stores) plugin). The CMS hook (`useSchemaImport`) builds the `wixDataCollection` destination for you; a platformized hook passes its `destination` through verbatim.
+
+Because a failed import comes back on a `200` (the failure is in the job status, not an HTTP error), the optional `jobApplicationErrorMap` (on either hook) lets you map the job's application-error codes to messages. You supply only the code → message map; the import resolves it through the error handler internally.
+
+
+```tsx
+import { ImportButton, useSchemaImport, usePlatformizedImport } from '@wix/patterns';
+```
+
+---
+
+### Examples
+
+### CMS import
+
+A Wix Data (CMS) collection. `useSchemaImport` reads the import inputs live from the table’s schema source and supplies the CMS create/edit-field modal; spread its result onto ``.
+
+```tsx
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  CustomColumns,
+  ImportButton,
+  Table,
+  tableSchemaSource,
+  useSchemaImport,
+  useTableCollection,
+} from '@wix/patterns';
+import { createInMemorySchemaSource } from '@wix/patterns/testkit';
+
+type CmsItem = {
+  _id: string;
+  name: string;
+  price: string;
+};
+
+function CmsImport() {
+  // In a real app, build the source with `createCmsSchemaSource` from
+  // `@wix/patterns-cms`. This docs example uses an in-memory source so it runs
+  // with no backend — the wiring below is identical either way.
+  const [schemaSource] = React.useState(() => {
+    const { source } = createInMemorySchemaSource<CmsItem>({
+      collectionId: 'Products',
+      fields: [
+        { id: 'name', displayName: 'Name', type: 'SHORT_TEXT' },
+        { id: 'price', displayName: 'Price', type: 'NUMBER' },
+      ],
+      items: [
+        { _id: '1', name: 'Coffee Mug', price: '12' },
+        { _id: '2', name: 'T-Shirt', price: '25' },
+      ],
+    });
+    return tableSchemaSource(source);
+  });
+
+  const state = useTableCollection<CmsItem>(schemaSource.collectionConfig);
+
+  // `useSchemaImport` reads the import inputs (fields, collection, create-new-
+  // field, backup) live from the schema source and returns the `ImportButton`
+  // props — `config` + the CMS create/edit-field modal — so just spread them.
+  const importProps = useSchemaImport(schemaSource);
+
+  return (
+    <CollectionPage>
+      <CollectionPage.Header title={{ text: 'Products' }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          horizontalScroll
+          fieldsSource={schemaSource}
+          customColumns={<CustomColumns />}
+          columns={[]}
+          importButton={<ImportButton {...importProps} />}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+
+export default CmsImport;
+```
+
+---
+
+### Platformized import
+
+A non–Wix-Data destination (here the stores catalog). `usePlatformizedImport` builds the config from the table’s toolbar + your `fields`/`destination`; spread its result onto ``.
+
+```tsx
+import { Page } from '@wix/design-system';
+import React from 'react';
+import {
+  ImportButton,
+  PageWrapper,
+  Table,
+  ToolbarTitle,
+  usePlatformizedImport,
+  useTableCollection,
+} from '@wix/patterns';
+import { queryStoreVariants } from '@wix/ambassador-stores-catalog-v1-product/http';
+import { StoreVariant } from '@wix/ambassador-stores-catalog-v1-product/types';
+import { useHttpClient } from '@wix/yoshi-flow-bm';
+
+function PlatformizedImport() {
+  const httpClient = useHttpClient();
+
+  const state = useTableCollection<StoreVariant>({
+    queryName: 'ImportButton-platformized',
+    fetchData: (query) => {
+      const { limit } = query;
+      return httpClient
+        .request(queryStoreVariants({ query: { cursorPaging: { limit } } }))
+        .then(({ data }) => ({
+          items: data.variants ?? [],
+          total: data.metadata?.total,
+        }));
+    },
+    itemKey: (variant) => variant.id ?? '',
+    itemName: (variant) => variant.productName ?? '',
+    fetchErrorMessage: () => 'Error fetching products',
+  });
+
+  // `usePlatformizedImport` reads the table's toolbar and returns the
+  // `ImportButton` props for a platformized (non–Wix-Data) destination — here
+  // the stores catalog. Spread the result.
+  const importProps = usePlatformizedImport({
+    state,
+    destination: { storesCatalogProducts: {} },
+    fields: [
+      { id: 'name', header: 'Name' },
+      { id: 'sku', header: 'SKU' },
+    ],
+  });
+
+  return (
+    <PageWrapper>
+      <Page height="400px">
+        <Page.Header title="Products" />
+        <Page.Content>
+          <Table
+            state={state}
+            horizontalScroll
+            title={<ToolbarTitle title="Products" showTotal />}
+            columns={[
+              { title: 'Name', render: (variant) => variant.productName },
+            ]}
+            importButton={<ImportButton {...importProps} />}
+          />
+        </Page.Content>
+      </Page>
+    </PageWrapper>
+  );
+}
+
+export default PlatformizedImport;
+```
+
+---
+
+### Required fields
+
+Mark fields with `required: true`. The import is blocked while any required field is still unmapped, with a footnote listing the missing ones. (Shown with `usePlatformizedImport`.)
+
+```tsx
+import { Page } from '@wix/design-system';
+import React from 'react';
+import {
+  ImportButton,
+  PageWrapper,
+  Table,
+  ToolbarTitle,
+  usePlatformizedImport,
+  useTableCollection,
+} from '@wix/patterns';
+import { queryStoreVariants } from '@wix/ambassador-stores-catalog-v1-product/http';
+import { StoreVariant } from '@wix/ambassador-stores-catalog-v1-product/types';
+import { useHttpClient } from '@wix/yoshi-flow-bm';
+
+function RequiredFields() {
+  const httpClient = useHttpClient();
+
+  const state = useTableCollection<StoreVariant>({
+    queryName: 'ImportButton-required',
+    fetchData: (query) => {
+      const { limit } = query;
+      return httpClient
+        .request(queryStoreVariants({ query: { cursorPaging: { limit } } }))
+        .then(({ data }) => ({
+          items: data.variants ?? [],
+          total: data.metadata?.total,
+        }));
+    },
+    itemKey: (variant) => variant.id ?? '',
+    itemName: (variant) => variant.productName ?? '',
+    fetchErrorMessage: () => 'Error fetching products',
+  });
+
+  // Mark fields `required: true`. The import is blocked while any required field
+  // is still unmapped, with a footnote listing the missing ones.
+  const importProps = usePlatformizedImport({
+    state,
+    destination: { storesCatalogProducts: {} },
+    fields: [
+      { id: 'name', header: 'Name', required: true },
+      { id: 'price', header: 'Price', required: true },
+      { id: 'sku', header: 'SKU' },
+    ],
+  });
+
+  return (
+    <PageWrapper>
+      <Page height="400px">
+        <Page.Header title="Products" />
+        <Page.Content>
+          <Table
+            state={state}
+            horizontalScroll
+            title={<ToolbarTitle title="Products" showTotal />}
+            columns={[
+              { title: 'Name', render: (variant) => variant.productName },
+            ]}
+            importButton={<ImportButton {...importProps} />}
+          />
+        </Page.Content>
+      </Page>
+    </PageWrapper>
+  );
+}
+
+export default RequiredFields;
+```
+
+---
+
+### Create new field
+
+A CMS capability: when the collection’s schema permits adding fields, unmapped CSV columns default to creating a new field (with an "Edit field" affordance) instead of being skipped. `useSchemaImport` wires it from the schema automatically.
+
+```tsx
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  CustomColumns,
+  ImportButton,
+  Table,
+  tableSchemaSource,
+  useSchemaImport,
+  useTableCollection,
+} from '@wix/patterns';
+import { createInMemorySchemaSource } from '@wix/patterns/testkit';
+
+type CmsItem = {
+  _id: string;
+  name: string;
+};
+
+// "Create new field" is a CMS (Wix Data) capability. `useSchemaImport` wires it
+// automatically: when the collection's schema permits adding fields
+// (`schemaPermissions.createField`), CSV columns that don't match an existing
+// field default to creating a new field (with an "Edit field" affordance)
+// instead of being skipped. Here only `name` exists, so other CSV columns become
+// new fields. (In a real app the source is `createCmsSchemaSource`.)
+function CreateNewField() {
+  const [schemaSource] = React.useState(() => {
+    const { source } = createInMemorySchemaSource<CmsItem>({
+      collectionId: 'Products',
+      fields: [{ id: 'name', displayName: 'Name', type: 'SHORT_TEXT' }],
+      items: [{ _id: '1', name: 'Coffee Mug' }],
+      schemaPermissions: {
+        createField: true,
+        updateField: true,
+        deleteField: true,
+      },
+    });
+    return tableSchemaSource(source);
+  });
+
+  const state = useTableCollection<CmsItem>(schemaSource.collectionConfig);
+  const importProps = useSchemaImport(schemaSource);
+
+  return (
+    <CollectionPage>
+      <CollectionPage.Header title={{ text: 'Products' }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          horizontalScroll
+          fieldsSource={schemaSource}
+          customColumns={<CustomColumns />}
+          columns={[]}
+          importButton={<ImportButton {...importProps} />}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+
+export default CreateNewField;
+```
+
+---
+
+### Update or skip by ID
+
+A CMS behavior: when a CSV column maps to the collection’s id field (`_id`), that row floats to the top and the modal offers an "update or skip" write policy for rows that collide on ID.
+
+```tsx
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  CustomColumns,
+  ImportButton,
+  Table,
+  tableSchemaSource,
+  useSchemaImport,
+  useTableCollection,
+} from '@wix/patterns';
+import { createInMemorySchemaSource } from '@wix/patterns/testkit';
+
+type CmsItem = {
+  _id: string;
+  name: string;
+};
+
+// Update-or-skip-by-ID is a CMS (Wix Data) behavior. When a CSV column maps to
+// the collection's id field (`_id`), that row floats to the top and the modal
+// offers an "update or skip" write policy for rows that collide on ID. Include
+// the id field in the schema so it's mappable; `useSchemaImport` derives the id
+// field from the schema. (In a real app the source is `createCmsSchemaSource`.)
+function IdCollisionWritePolicy() {
+  const [schemaSource] = React.useState(() => {
+    const { source } = createInMemorySchemaSource<CmsItem>({
+      collectionId: 'Products',
+      idField: '_id',
+      fields: [
+        { id: '_id', displayName: 'ID', type: 'SHORT_TEXT' },
+        { id: 'name', displayName: 'Name', type: 'SHORT_TEXT' },
+      ],
+      items: [{ _id: '1', name: 'Coffee Mug' }],
+    });
+    return tableSchemaSource(source);
+  });
+
+  const state = useTableCollection<CmsItem>(schemaSource.collectionConfig);
+  const importProps = useSchemaImport(schemaSource);
+
+  return (
+    <CollectionPage>
+      <CollectionPage.Header title={{ text: 'Products' }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          horizontalScroll
+          fieldsSource={schemaSource}
+          customColumns={<CustomColumns />}
+          columns={[]}
+          importButton={<ImportButton {...importProps} />}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}
+
+export default IdCollisionWritePolicy;
+```
+
+---
+
+### Backup & error handling
+
+Pass a `backup` to snapshot the collection before importing (undone on cancel) and a `jobApplicationErrorMap` to map a failed job’s application-error codes to messages. (Shown with `usePlatformizedImport`.)
+
+```tsx
+import { Page } from '@wix/design-system';
+import React from 'react';
+import {
+  ImportButton,
+  PageWrapper,
+  Table,
+  ToolbarTitle,
+  usePlatformizedImport,
+  useTableCollection,
+} from '@wix/patterns';
+import { queryStoreVariants } from '@wix/ambassador-stores-catalog-v1-product/http';
+import { StoreVariant } from '@wix/ambassador-stores-catalog-v1-product/types';
+import { useHttpClient } from '@wix/yoshi-flow-bm';
+
+function BackupAndErrorHandling() {
+  const httpClient = useHttpClient();
+
+  const state = useTableCollection<StoreVariant>({
+    queryName: 'ImportButton-backup',
+    fetchData: (query) => {
+      const { limit } = query;
+      return httpClient
+        .request(queryStoreVariants({ query: { cursorPaging: { limit } } }))
+        .then(({ data }) => ({
+          items: data.variants ?? [],
+          total: data.metadata?.total,
+        }));
+    },
+    itemKey: (variant) => variant.id ?? '',
+    itemName: (variant) => variant.productName ?? '',
+    fetchErrorMessage: () => 'Error fetching products',
+  });
+
+  const importProps = usePlatformizedImport({
+    state,
+    destination: { storesCatalogProducts: {} },
+    fields: [{ id: 'name', header: 'Name', required: true }],
+
+    // Optional: snapshot the collection before importing. The returned `restore`
+    // runs only if the user cancels mid-import (a job failure leaves partial
+    // rows and offers "Try again" instead).
+    backup: async () => {
+      // ...take a snapshot...
+      return {
+        restore: async () => {
+          // ...restore the snapshot...
+        },
+      };
+    },
+
+    // Optional: map the failed job's application-error codes to messages. You
+    // supply only the code → message map; the import resolves it through the
+    // error handler internally.
+    jobApplicationErrorMap: {
+      MISSING_REQUIRED_FIELDS: ({ data }) => ({
+        message: `Missing required fields: ${data?.missingFields?.join(', ')}`,
+      }),
+    },
+  });
+
+  return (
+    <PageWrapper>
+      <Page height="400px">
+        <Page.Header title="Products" />
+        <Page.Content>
+          <Table
+            state={state}
+            horizontalScroll
+            title={<ToolbarTitle title="Products" showTotal />}
+            columns={[
+              { title: 'Name', render: (variant) => variant.productName },
+            ]}
+            importButton={<ImportButton {...importProps} />}
+          />
+        </Page.Content>
+      </Page>
+    </PageWrapper>
+  );
+}
+
+export default BackupAndErrorHandling;
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `config` | `ImportButtonConfig` | Yes | - | The import inputs. Build it with a source hook — `useSchemaImport` for a CMS (Wix Data) collection, or `usePlatformizedImport` for a platformized destination — and pass the returned `config`. |
+| `renderFieldEditor` | `RenderImportFieldEditor` | No | - | Renders the source's create/edit-field modal (see {@link RenderImportFieldEditor}). Supplied by consumer-driven sources (e.g. `useSchemaImport` for CMS). A DataExtension destination provides its own internally, so it need not be passed for that case. |
+| `toolbarType` | `"bulkActionToolbar" \| "default"` | No | - | Which button variant to render. `'default'` (the default) shows a `ResponsiveButton`; `'bulkActionToolbar'` shows a compact secondary `Button`. |
+

package/dist/docs/MultiAutoInlineCheckboxFilter.md

@@ -599,7 +599,7 @@ import { MultiAutoInlineCheckboxFilter } from '@wix/patterns';
 | `MozUserModify` | `"-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "read-only" \| "read-write" \| "write-only"` | No | - | The **`user-modify`** property has no effect in Firefox. It was originally planned to determine whether or not the content of an element can be edited by a user. **Syntax**: `read-only \| read-write \| write-only` **Initial value**: `read-only` |
 | `MozUserSelect` | `"auto" \| "none" \| "-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "text" \| "all" \| "-moz-none"` | No | - | This feature is not Baseline because it does not work in some of the most widely-used browsers. **Syntax**: `auto \| text \| none \| all` **Initial value**: `auto` |
 | `MozWindowDragging` | `"-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "drag" \| "no-drag"` | No | - | **Syntax**: `drag \| no-drag` **Initial value**: `drag` |
-| `MozWindowShadow` | `"none" \| "-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "menu" \| "tooltip" \| "default" \| "sheet"` | No | - | **Syntax**: `default \| menu \| tooltip \| sheet \| none` **Initial value**: `default` |
+| `MozWindowShadow` | `"none" \| "-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "default" \| "menu" \| "tooltip" \| "sheet"` | No | - | **Syntax**: `default \| menu \| tooltip \| sheet \| none` **Initial value**: `default` |
 | `msAccelerator` | `"-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "false" \| "true"` | No | - | **Syntax**: `false \| true` **Initial value**: `false` |
 | `msBlockProgression` | `"-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "bt" \| "lr" \| "rl" \| "tb"` | No | - | **Syntax**: `tb \| rl \| bt \| lr` **Initial value**: `tb` |
 | `msContentZoomChaining` | `"none" \| "-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "chained"` | No | - | **Syntax**: `none \| chained` **Initial value**: `none` |

package/dist/docs/MultiInlineCheckboxFilter.md

@@ -620,7 +620,7 @@ function BasicMultiInlineCheckboxFilter() {
 | `MozUserModify` | `"-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "read-only" \| "read-write" \| "write-only"` | No | - | The **`user-modify`** property has no effect in Firefox. It was originally planned to determine whether or not the content of an element can be edited by a user. **Syntax**: `read-only \| read-write \| write-only` **Initial value**: `read-only` |
 | `MozUserSelect` | `"auto" \| "none" \| "-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "text" \| "all" \| "-moz-none"` | No | - | This feature is not Baseline because it does not work in some of the most widely-used browsers. **Syntax**: `auto \| text \| none \| all` **Initial value**: `auto` |
 | `MozWindowDragging` | `"-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "drag" \| "no-drag"` | No | - | **Syntax**: `drag \| no-drag` **Initial value**: `drag` |
-| `MozWindowShadow` | `"none" \| "-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "menu" \| "tooltip" \| "default" \| "sheet"` | No | - | **Syntax**: `default \| menu \| tooltip \| sheet \| none` **Initial value**: `default` |
+| `MozWindowShadow` | `"none" \| "-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "default" \| "menu" \| "tooltip" \| "sheet"` | No | - | **Syntax**: `default \| menu \| tooltip \| sheet \| none` **Initial value**: `default` |
 | `msAccelerator` | `"-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "false" \| "true"` | No | - | **Syntax**: `false \| true` **Initial value**: `false` |
 | `msBlockProgression` | `"-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "bt" \| "lr" \| "rl" \| "tb"` | No | - | **Syntax**: `tb \| rl \| bt \| lr` **Initial value**: `tb` |
 | `msContentZoomChaining` | `"none" \| "-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "chained"` | No | - | **Syntax**: `none \| chained` **Initial value**: `none` |

package/dist/docs/Table.md

@@ -1001,10 +1001,11 @@ function UseExternalDataSource() {
 | `exportButton` | `ReactElement<any, string \| JSXElementConstructor<any>>` | No | - | A [`<ExportButton />`](./?path=/story/features-export--exportto) react element to be added to the toolbar. |
 | `dragAndDrop` | `TableDragAndDropType` | No | - | Adds functionality to allow visitors to reorder items manually. For more information, see the [Drag and Drop Overview](./?path=/story/features-sort-drag-and-drop--overview). |
 | `dataExtension` | `(FC<DataExtensionOverrides> & DataExtensionObjectType) \| DataExtensionElement` | No | - | Data extension implementation: `import { DataExtension } from '@wix/patterns';` |
-| `fieldsSource` | `FieldsSourceProvider` | No | - | Attaches a field source to the table — the way to add a source's fields, filters, and field management. Build it with `tableSchemaSource(...)` for a schema source (also spread its `collectionConfig` into the collection hook), or `dataExtensionTableSource(...)` for DataExtension, which extends the consumer's own collection. |
+| `fieldsSource` | `FieldsSourceProvider` | No | - | A fields source (e.g. `dataExtensionTableSource(...)`) whose fields become columns and whose field management wires into the table. Schema sources attach via the `@wix/patterns/schema` collection hooks instead. |
 | `tags` | `TagsElement<T, F>` | No | - | Enables tags feature. In this element you can pass the configuration |
 | `checkboxTooltipContent` | `((rowData: KeyedItem<T>) => string)` | No | - | A function that receives the item of the row and returns a string for tooltip content. |
 | `bulkActionToolbar` | `BulkActionToolbarRenderProp<T, F>` | No | - | Render a custom toolbar when more than 1 item is selected.<br> The function accepts the following parameters * `selectedValues`: The items that were checked via the selection column * `uncheckedValues`: The items that were unchecked via the selection column * `allSelected`: Indicates whether the "Select All" checkbox is checked * `openModal`: Opens the modal that contains the component from `bulkActionModal` render prop * `clearSelection`: Clears all existing selection, call this after the action on the selected items was done * `total`: Total items in the server (taken from [`fetchData`](./?path=/story/common-hooks--usecollection) return value). * `openConfirmModal`: Opens a `<MessageModalLayout/>` to confirm an action about to be applied on the selected items. * `query`: ComputedQuery<F> - Representation of the current paging, sorting & filtering applied. Usually for using together with bulk action such as `updateAll` and `deleteAll` > When passed, enables `showSelection` by default. |
+| `showAddFieldButton` | `boolean` | No | - | When true, wraps every column header with the AddField hover popover. The "+" button is revealed when the consumer hovers a column header and triggers either the schema's `addField` or the data-extension's custom fields modal. Off by default. |
 | `bulkActionModal` | `BulkActionModalRenderProp<T, F>` | No | - | Opens a modal from the [`MultiBulkActionToolbar`](./?path=/story/features-actions-bulk-actions--multibulkactiontoolbar). Supported parameters: + `selectedValues`: Selected item values. + `uncheckedValues`: Unselected item values. + `isSelectAll`: [bool] Whether the **Select All** option is selected. + `closeModal`: Closes the modal. + `query`: [object] Instance of [ComputedQuery](./?path=/story/common-types--computedquery) that represents the query that resulted in an empty state. Representation of the current paging, sorting and filtering applied. Usually for using together with bulk action such as `updateAll` and `deleteAll`. |
 | `dataHook` | `string` | No | - | Applies a data-hook HTML attribute to be used in the tests |
 | `search` | `boolean \| FilterElement<any> \| CollectionSearchElement` | No | `true` | Displays a search input on the right side of the table toolbar.<br> <br> Accepts a boolean or a custom React element as a parameter. When passing `false`, no search input is displayed. |

package/dist/docs/TableGridSwitch.md

@@ -282,8 +282,9 @@ function TableGridSwitchAdvanceSorting() {
 | `rowStatus` | `((row: KeyedItem<T>, rowNum: number) => TableRowStatusValue \| null)` | No | - | When provided, renders a fixed-width status slot per row to the right of the selection/row-number column. The callback returns a `{ status, messages }` config for rows that need a status indicator, or `null`/`undefined` for an empty but width-reserved slot — the slot never collapses. Only `error` and `warning` statuses are supported; the slot is exclusively for those two indicator kinds, rendered via the WDS `<StatusIndicator/>`. |
 | `stickySelectionColumn` | `boolean` | No | - | Whether to add a sticky column. <br> Sticky columns allow you to display specific columns at all times while the visitor scrolls the table horizontally. |
 | `dataExtension` | `(FC<DataExtensionOverrides> & DataExtensionObjectType) \| DataExtensionElement` | No | - | Data extension implementation: `import { DataExtension } from '@wix/patterns';` |
-| `fieldsSource` | `FieldsSourceProvider` | No | - | Attaches a field source to the table — the way to add a source's fields, filters, and field management. Build it with `tableSchemaSource(...)` for a schema source (also spread its `collectionConfig` into the collection hook), or `dataExtensionTableSource(...)` for DataExtension, which extends the consumer's own collection. |
+| `fieldsSource` | `FieldsSourceProvider` | No | - | A fields source (e.g. `dataExtensionTableSource(...)`) whose fields become columns and whose field management wires into the table. Schema sources attach via the `@wix/patterns/schema` collection hooks instead. |
 | `checkboxTooltipContent` | `((rowData: KeyedItem<T>) => string)` | No | - | A function that receives the item of the row and returns a string for tooltip content. |
+| `showAddFieldButton` | `boolean` | No | - | When true, wraps every column header with the AddField hover popover. The "+" button is revealed when the consumer hovers a column header and triggers either the schema's `addField` or the data-extension's custom fields modal. Off by default. |
 | `bulkActionModal` | `BulkActionModalRenderProp<T, F>` | No | - | Opens a modal from the [`MultiBulkActionToolbar`](./?path=/story/features-actions-bulk-actions--multibulkactiontoolbar). Supported parameters: + `selectedValues`: Selected item values. + `uncheckedValues`: Unselected item values. + `isSelectAll`: [bool] Whether the **Select All** option is selected. + `closeModal`: Closes the modal. + `query`: [object] Instance of [ComputedQuery](./?path=/story/common-types--computedquery) that represents the query that resulted in an empty state. Representation of the current paging, sorting and filtering applied. Usually for using together with bulk action such as `updateAll` and `deleteAll`. |
 | `actionCellWidth` | `string \| number` | No | - | Width of the column containing the `actionCell` component. |
 | `actionCellProps` | `ActionCellPropsType<T>` | No | - | Extra columns props for the actions cell. |