@wix/patterns 1.430.0 → 1.431.0

package/src/schema/EntityPage.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import type { FieldValues } from 'react-hook-form';
+import { SchemaFieldsProvider } from '../providers/SchemaFieldsProvider';
+import {
+  EntityPage as OpenEntityPage,
+  type EntityPageProps,
+} from '../components/EntityPage';
+
+/** EntityPage props for a source-driven page — the same as the open component's.
+ *  The fields container the page's fields need is wired here, not by the
+ *  consumer. */
+export type SchemaEntityPageProps<
+  T,
+  V extends FieldValues = FieldValues,
+> = EntityPageProps<T, V>;
+
+function _EntityPage<T, V extends FieldValues = FieldValues>({
+  state,
+  ...rest
+}: SchemaEntityPageProps<T, V>) {
+  // The container belongs to the schema and the state initializes it in init(),
+  // so there is nothing to create or register here.
+  return (
+    <SchemaFieldsProvider schema={state.schemaSource}>
+      <OpenEntityPage state={state} {...rest} />
+    </SchemaFieldsProvider>
+  );
+}
+
+_EntityPage.Header = OpenEntityPage.Header;
+_EntityPage.Content = OpenEntityPage.Content;
+_EntityPage.MainContent = OpenEntityPage.MainContent;
+_EntityPage.AdditionalContent = OpenEntityPage.AdditionalContent;
+_EntityPage.Card = OpenEntityPage.Card;
+_EntityPage.Slots = OpenEntityPage.Slots;
+_EntityPage.Extensions = OpenEntityPage.Extensions;
+
+_EntityPage.displayName = 'EntityPage';
+
+export const EntityPage = _EntityPage;

package/src/schema/EntityPageFieldsCard.tsx

@@ -0,0 +1,105 @@
+import React, { useEffect, useState } from 'react';
+import { Button, Card } from '@wix/design-system';
+import { observer } from 'mobx-react-lite';
+import { useWixPatternsContainer, usePageContext } from '@wix/bex-core/react';
+import {
+  EntityPageCard,
+  type EntityPageCardProps,
+} from '../components/EntityPageCard';
+import { EntityPageFields } from '../components/EntityPageFields';
+import { CustomColumnsEntityPagePanelMount } from '../components/CustomColumnsPanel/CustomColumnsEntityPagePanelMount';
+import { CustomColumnsDragAndDrop } from '../components/CustomColumns/CustomColumnsDragAndDrop';
+import { useEntityPageContext } from '../providers';
+import { EntityPageFieldsCardState } from '../state/EntityPageFieldsCardState';
+
+export interface EntityPageFieldsCardProps
+  extends Omit<EntityPageCardProps, 'children'> {
+  title: string;
+  subtitle?: string;
+  /**
+   * Field ids to offer, in order. Omitted ⇒ every editable schema field.
+   * Read once, on the first render — a later change is ignored, since the saved
+   * show/hide and order are keyed to the list the card started with.
+   */
+  fieldIds?: string[];
+  /**
+   * Namespace the per-user show/hide and order are stored under. Default: the
+   * source's collection id. Set it when a page has more than one fields card,
+   * so they don't share one saved layout.
+   */
+  persistencyKey?: string;
+  /** Whether to show the "Manage fields" button and panel. Default: `true`. */
+  showManageFields?: boolean;
+  dataHook?: string;
+}
+
+/** The page's schema fields in a card, with a "Manage fields" panel that shows,
+ *  hides and reorders them. The choice is saved per user and survives reloads.
+ *  Render inside the `EntityPage` from this entry. */
+export function _EntityPageFieldsCard({
+  title,
+  subtitle,
+  fieldIds,
+  persistencyKey,
+  showManageFields = true,
+  dataHook = 'entity-page-fields-card',
+  ...rest
+}: EntityPageFieldsCardProps) {
+  const container = useWixPatternsContainer();
+  const { translate: t } = container;
+  const { modalsContainerRef } = usePageContext();
+  const pageState = useEntityPageContext();
+
+  const [state] = useState(
+    () =>
+      new EntityPageFieldsCardState({
+        pageState,
+        container,
+        // The collection id is the schema id, and unlike the schema it is here
+        // on the first render. A page with no source has no schema and so no
+        // fields to lay out — the fallback just names an empty layout.
+        persistencyKey:
+          persistencyKey ??
+          pageState.schemaSource?.collectionId ??
+          'entity-page-fields',
+        fieldIds,
+        showManageFields,
+        dragAndDrop: CustomColumnsDragAndDrop,
+        modalsContainerRef,
+      }),
+  );
+
+  useEffect(() => state.init(), []);
+
+  return (
+    <EntityPageCard dataHook={dataHook} {...rest}>
+      <Card.Header
+        title={title}
+        subtitle={subtitle}
+        suffix={
+          state.canManageFields ? (
+            <Button
+              size="small"
+              priority="secondary"
+              dataHook="entity-page-fields-card-manage-fields"
+              onClick={() => state.openManageFields()}
+            >
+              {t('cairo.table.manage-fields.button.cta')}
+            </Button>
+          ) : undefined
+        }
+      />
+      <Card.Divider />
+      <Card.Content>
+        <EntityPageFields fieldIds={state.visibleFieldIds} />
+      </Card.Content>
+      {state.panelState && (
+        <CustomColumnsEntityPagePanelMount state={state.panelState} />
+      )}
+    </EntityPageCard>
+  );
+}
+
+_EntityPageFieldsCard.displayName = 'EntityPageFieldsCard';
+
+export const EntityPageFieldsCard = observer(_EntityPageFieldsCard);

package/src/schema/Grid.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import { observer } from 'mobx-react-lite';
+import type { FiltersMap } from '@wix/bex-core';
+import { SchemaFieldsProvider } from '../providers/SchemaFieldsProvider';
+import { Grid as OpenGrid, type GridProps } from '../components/Grid/Grid';
+import type { SupportedCardGalleryItemProps } from '../components/Grid/SupportedCardGalleryItemProps';
+
+/** A grid driven by a source: the card title comes from the source's display
+ *  value, so `renderItem` sets only the rest of the card (subtitle, image,
+ *  badge, …). Field-type icons are always on, and not configurable. */
+export type SchemaGridProps<T, F extends FiltersMap> = Omit<
+  GridProps<T, F>,
+  'showFieldTypeIcons' | 'renderItem'
+> & {
+  renderItem?: (
+    item: T,
+    index: number,
+  ) => Omit<Partial<SupportedCardGalleryItemProps>, 'title'>;
+};
+
+function _Grid<T, F extends FiltersMap>(props: SchemaGridProps<T, F>) {
+  // Field-typed cells render patterns-fields components, which read the
+  // container from context (see Table).
+  const schema = props.state.toolbar.collectionFieldsSource?.schemaSource;
+  const grid = <OpenGrid {...props} showFieldTypeIcons />;
+  return <SchemaFieldsProvider schema={schema}>{grid}</SchemaFieldsProvider>;
+}
+
+export const Grid = observer(_Grid) as typeof _Grid;

package/src/schema/LayoutSwitch.tsx

@@ -0,0 +1,78 @@
+import React from 'react';
+import { observer } from 'mobx-react-lite';
+import { SchemaFieldsProvider } from '../providers/SchemaFieldsProvider';
+import type { ReactElement } from 'react';
+import type { FiltersMap } from '@wix/bex-core';
+import {
+  LayoutSwitch as OpenLayoutSwitch,
+  type LayoutSwitchProps,
+} from '../components/LayoutSwitch/LayoutSwitch';
+import type { LayoutSwitchState } from '../state/LayoutSwitchState';
+import type { SchemaTableProps } from './Table';
+import type { SchemaEditableTableProps } from './EditableTable';
+import type { SchemaGridProps } from './Grid';
+
+type LayoutBag<P> = Omit<P, 'state' | 'tableGridSwitchButton'>;
+
+/** LayoutSwitch props for a source-driven page: the per-layout state is derived
+ *  from the single `state`, and each layout's props are the source-adjusted
+ *  versions (columns optional, no fieldsSource, field-type icons on). */
+export interface SchemaLayoutSwitchProps<T, F extends FiltersMap> {
+  state: LayoutSwitchState<T, F>;
+  importButton?: ReactElement;
+  tableProps?: LayoutBag<SchemaTableProps<T, F>>;
+  gridProps?: LayoutBag<SchemaGridProps<T, F>>;
+  spreadsheetProps?: LayoutBag<SchemaEditableTableProps<T, F>>;
+}
+
+function _LayoutSwitch<T, F extends FiltersMap>({
+  state,
+  importButton,
+  tableProps,
+  gridProps,
+  spreadsheetProps,
+}: SchemaLayoutSwitchProps<T, F>) {
+  const props: LayoutSwitchProps<T, F> = {
+    state,
+    importButton,
+    // Each layout is enabled only when both its props and its state exist —
+    // passing `tableProps` while the hook wasn't configured with `table` would
+    // otherwise render a layout with an undefined state and crash.
+    tableProps:
+      tableProps && state.tableState
+        ? {
+            ...tableProps,
+            state: state.tableState,
+            columns: tableProps.columns ?? [],
+            showFieldTypeIcons: true,
+            showAddFieldButton: true,
+          }
+        : undefined,
+    gridProps:
+      gridProps && state.gridState
+        ? {
+            ...gridProps,
+            state: state.gridState,
+            showFieldTypeIcons: true,
+          }
+        : undefined,
+    spreadsheetProps:
+      spreadsheetProps && state.spreadsheetState
+        ? {
+            ...spreadsheetProps,
+            state: state.spreadsheetState,
+            columns: spreadsheetProps.columns ?? [],
+            showFieldTypeIcons: true,
+          }
+        : undefined,
+  };
+
+  // Every layout needs the container, not just the spreadsheet (EditableTable) —
+  // a source's field-typed cells (e.g. DateTime) render in the table and grid
+  // layouts too.
+  const schema = state.toolbar.collectionFieldsSource?.schemaSource;
+  const layouts = <OpenLayoutSwitch {...props} />;
+  return <SchemaFieldsProvider schema={schema}>{layouts}</SchemaFieldsProvider>;
+}
+
+export const LayoutSwitch = observer(_LayoutSwitch) as typeof _LayoutSwitch;

package/src/schema/Table.tsx

@@ -0,0 +1,43 @@
+import React from 'react';
+import { observer } from 'mobx-react-lite';
+import type { FiltersMap } from '@wix/bex-core';
+import { SchemaFieldsProvider } from '../providers/SchemaFieldsProvider';
+import { Table as OpenTable, type TableProps } from '../components/Table/Table';
+import type { TableColumn } from '../model';
+import type { TableState } from '../state';
+
+/** Table props for a source-driven table: the source supplies the field
+ *  columns and attaches its own fields management. `columns` is optional
+ *  (extras only); the fields-management props are always on and not
+ *  configurable, and there is no `fieldsSource`/`dataExtension`. */
+export type SchemaTableProps<T, F extends FiltersMap> = Omit<
+  TableProps<T, F>,
+  | 'state'
+  | 'columns'
+  | 'fieldsSource'
+  | 'dataExtension'
+  | 'showFieldTypeIcons'
+  | 'showAddFieldButton'
+> & {
+  state: TableState<T, F>;
+  /** Columns beyond the source's fields (e.g. an action column). Default: none. */
+  columns?: TableColumn<T>[];
+};
+
+function _Table<T, F extends FiltersMap>(props: SchemaTableProps<T, F>) {
+  const { columns, ...rest } = props;
+  // A source's field-typed cells (dates, media, references) render
+  // patterns-fields components, which read the container from context.
+  const schema = props.state.toolbar.collectionFieldsSource?.schemaSource;
+  const table = (
+    <OpenTable
+      {...rest}
+      columns={columns ?? []}
+      showFieldTypeIcons
+      showAddFieldButton
+    />
+  );
+  return <SchemaFieldsProvider schema={schema}>{table}</SchemaFieldsProvider>;
+}
+
+export const Table = observer(_Table) as typeof _Table;

package/src/schema/index.ts

@@ -3,9 +3,19 @@ export * from './useTableCollection';
 export * from './useGridCollection';
 export * from './useEditableTableCollection';
 export * from './useLayoutSwitchCollection';
+export * from './useEntityPage';
 export {
   usePlatformizedSource,
   type PlatformizedSourceInput,
 } from './usePlatformizedSource';
 export type { SchemaCollectionOptions } from './schemaCollectionOptions';
 export { sourceMutations } from './sourceMutations';
+export { Table, type SchemaTableProps } from './Table';
+export { EditableTable, type SchemaEditableTableProps } from './EditableTable';
+export { Grid, type SchemaGridProps } from './Grid';
+export { LayoutSwitch, type SchemaLayoutSwitchProps } from './LayoutSwitch';
+export { EntityPage, type SchemaEntityPageProps } from './EntityPage';
+export {
+  EntityPageFieldsCard,
+  type EntityPageFieldsCardProps,
+} from './EntityPageFieldsCard';

package/src/schema/schemaCollectionOptions.ts

@@ -9,11 +9,6 @@ import type { CollectionConfigWithConditionals } from '@wix/bex-core/react';
 
 type FetchData<T> = (query: OffsetQuery) => Promise<OffsetQueryResult<T>>;
 
-/**
- * The collection options a schema-entry hook accepts — everything the source
- * doesn't supply. Source-owned keys (`queryName`, `paginationMode`,
- * `fetchData`, `fetchTotal`, `itemKey`, `itemName`) don't exist here.
- */
 export type SchemaCollectionOptions<T, F extends FiltersMap> = Omit<
   CollectionConfigWithConditionals<T, F>,
   | 'queryName'
@@ -22,17 +17,12 @@ export type SchemaCollectionOptions<T, F extends FiltersMap> = Omit<
   | 'fetchTotal'
   | 'itemKey'
   | 'itemName'
+  | 'fqdn'
 > & {
   /** Wraps the source's fetch (filter/enrich results) without replacing it. */
   wrapFetchData?: (next: FetchData<T>) => FetchData<T>;
 };
 
-/** Builds the collection config from the source: the query fetches through the
- *  source's backend, identity and labels come from the source, and the
- *  consumer's options fill the rest.
- *  `options` is typed loosely — the hooks' option types already enforce the
- *  consumer surface, and TS can't infer `F` back through the conditional
- *  config type; callers pass the generics explicitly. */
 export function schemaCollectionConfig<T, F extends FiltersMap>(
   source: SchemaSource<T>,
   options?: object,
@@ -45,6 +35,7 @@ export function schemaCollectionConfig<T, F extends FiltersMap>(
   return {
     ...rest,
     queryName: source.collectionId,
+    fqdn: source.collectionId,
     paginationMode: source.paginationMode,
     fetchData: wrapFetchData ? wrapFetchData(fetchData) : fetchData,
     itemKey: source.itemKey,

package/src/schema/sourceMutations.ts

@@ -1,8 +1,12 @@
 import type { SourceState } from '@wix/bex-core';
 import type { EditableTableMutationHandlers } from '../state/EditableTable';
 
+const LOCAL_ID_PREFIX = 'new-';
+
 const newLocalId = () =>
-  `new-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  `${LOCAL_ID_PREFIX}${Date.now().toString(36)}-${Math.random()
+    .toString(36)
+    .slice(2, 6)}`;
 
 /**
  * Row write handlers read from the source's state — the schema-entry default,
@@ -26,12 +30,28 @@ export function sourceMutations<T>(
     return fn;
   };
 
+  const idField = () => sourceState.schema?.idField ?? '_id';
+
+  // A new row needs an id up front to key its optimistic patch, but that id is
+  // ours, not the backend's — creating with it would persist "new-…" as the
+  // item's id. Dropped from the payload, so a create carries no id at all.
+  const withoutLocalId = (item: T): Partial<T> => {
+    const key = idField();
+    const record = item as Record<string, unknown>;
+    if (!String(record[key] ?? '').startsWith(LOCAL_ID_PREFIX)) {
+      return item;
+    }
+    const { [key]: _localId, ...rest } = record;
+    return rest as Partial<T>;
+  };
+
   return {
-    createItem: () =>
-      ({ [sourceState.schema?.idField ?? '_id']: newLocalId() } as T),
+    createItem: () => ({ [idField()]: newLocalId() } as T),
     submitCreate: (items) =>
       Promise.all(
-        items.map((item) => required(backend().create, 'creating')(item)),
+        items.map((item) =>
+          required(backend().create, 'creating')(withoutLocalId(item)),
+        ),
       ),
     submitUpdate: (items) =>
       Promise.all(

package/src/schema/syncSourcePermissions.ts

@@ -0,0 +1,27 @@
+import { autorun, runInAction } from 'mobx';
+import type { FiltersMap, SourceState } from '@wix/bex-core';
+import type { EditableTableState } from '../state/EditableTable';
+
+/**
+ * Keeps an editable table's row-action flags in sync with its source: an action
+ * is disabled when the source denies the permission (`schema.itemPermissions`)
+ * OR the backend can't perform it (the write method is absent, e.g. a read-only
+ * source). Reactive because the schema loads asynchronously. Returns a disposer.
+ */
+export function syncSourcePermissions<T, F extends FiltersMap>(
+  state: EditableTableState<T, F>,
+  sourceState: SourceState<T>,
+): () => void {
+  return autorun(() => {
+    const loaded = sourceState.loadedSchema;
+    const perms = loaded?.schema.itemPermissions;
+    const backend = loaded?.backend;
+    runInAction(() => {
+      state.addItemDisabled = !(perms?.createItem ?? true) || !backend?.create;
+      state.updateItemDisabled =
+        !(perms?.updateItem ?? true) || !backend?.update;
+      state.removeItemDisabled =
+        !(perms?.deleteItem ?? true) || !backend?.bulkDelete;
+    });
+  });
+}

package/src/schema/useEditableTableCollection.ts

@@ -1,4 +1,4 @@
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { SourceState } from '@wix/bex-core';
 import type {
   CollectionOptimisticActionsBaseParams,
@@ -7,33 +7,23 @@ import type {
   SchemaSource,
 } from '@wix/bex-core';
 import { useWixPatternsContainer } from '@wix/bex-core/react';
-import type {
-  EditableTableState,
-  EditableTablePermissions,
-  EditableTableMutationHandlers,
-} from '../state/EditableTable';
+import type { EditableTableState } from '../state/EditableTable';
 import type { CellType } from '../state/EditableTable/types';
 import type { FieldsSourceProvider } from '../components/fieldsSourceProvider';
-import {
-  useEditableTableCollection as useOpenEditableTableCollection,
-  type EditableTableCollectionConfig,
-} from '../hooks/useEditableTableCollection';
+import { useEditableTableCollection as useOpenEditableTableCollection } from '../hooks/useEditableTableCollection';
 import { SchemaState } from '../components/SchemaSource/SchemaState';
 import {
   schemaCollectionConfig,
   type SchemaCollectionOptions,
 } from './schemaCollectionOptions';
 import { sourceMutations } from './sourceMutations';
+import { syncSourcePermissions } from './syncSourcePermissions';
 import { attachesItself } from './usePlatformizedSource';
 
 export type SchemaEditableTableCollectionOptions<
   T,
   F extends FiltersMap = OptionalFiltersMap,
 > = SchemaCollectionOptions<T, F> & {
-  permissions?: EditableTablePermissions;
-  /** Row write handlers. Default: derived from the source's backend
-   *  (`create`/`update`/`bulkDelete`). */
-  mutations?: EditableTableMutationHandlers<T>;
   optimisticActionParams?: Partial<CollectionOptimisticActionsBaseParams<T, F>>;
   /** Additional cell types to register alongside the built-in ones. */
   extraCellTypes?: CellType[];
@@ -66,22 +56,22 @@ export function useEditableTableCollection<
     };
   });
 
-  const {
-    permissions,
-    mutations,
-    optimisticActionParams,
-    extraCellTypes,
-    ...rest
-  } = options ?? ({} as SchemaEditableTableCollectionOptions<T, F>);
+  const { optimisticActionParams, extraCellTypes, ...rest } =
+    options ?? ({} as SchemaEditableTableCollectionOptions<T, F>);
 
-  const state = useOpenEditableTableCollection<T, F>({
-    ...schemaCollectionConfig<T, F>(source, rest),
-    permissions,
-    mutations: mutations ?? sourceMutations(sourceState),
-    optimisticActionParams,
-    extraCellTypes,
-  } as unknown as EditableTableCollectionConfig<T, F>);
+  const state = useOpenEditableTableCollection<T, F>(
+    Object.assign(schemaCollectionConfig<T, F>(source, rest), {
+      mutations: sourceMutations(sourceState),
+      optimisticActionParams,
+      extraCellTypes,
+    }),
+  );
 
   useState(() => fieldsProvider.setOnTable(state.toolbar));
+  useEffect(
+    () => syncSourcePermissions(state, sourceState),
+    [state, sourceState],
+  );
+
   return state;
 }

package/src/schema/useEntityPage.ts

@@ -0,0 +1,105 @@
+import { useState } from 'react';
+import type { FieldValues } from 'react-hook-form';
+import type { SchemaSource } from '@wix/bex-core';
+import type { EntityPageState } from '../state';
+import {
+  useEntityPage as useOpenEntityPage,
+  type UseEntityPageParams,
+} from '../hooks/useEntityPage';
+
+/** Entity page options for a source-driven page: the source loads the schema and
+ *  its backend reads and writes the entity, so `fetch` and `onSave` derive from
+ *  it — pass one only to replace the derived default. */
+export type SchemaEntityPageOptions<
+  T,
+  V extends FieldValues = FieldValues,
+> = Omit<UseEntityPageParams<T, V>, 'fetch' | 'onSave' | 'schemaSource'> & {
+  /** The entity to load. Omitted ⇒ the create route: the page starts empty and
+   *  saving creates an entity. */
+  entityId?: string;
+  /** Replaces the read through the source's backend. */
+  fetch?: UseEntityPageParams<T, V>['fetch'];
+  /** Replaces the write through the source's backend. */
+  onSave?: UseEntityPageParams<T, V>['onSave'];
+};
+
+/** An entity page driven by a source: the source supplies the schema its fields
+ *  render from, and its backend reads and writes the entity. Render the state
+ *  with the `EntityPage` from this entry — it wires the fields provider. */
+export function useEntityPage<T, V extends FieldValues = FieldValues>(
+  source: SchemaSource<T>,
+  options: SchemaEntityPageOptions<T, V>,
+): EntityPageState<T, V> {
+  const { entityId, fetch, onSave, ...rest } = options;
+
+  // The derived read and write need values that change or don't exist yet when
+  // the state is created: the state itself (the save merges into the loaded
+  // entity) and the latest entityId (a re-fetch should read the current one).
+  const [page] = useState<PageRef<T, V>>(() => ({}));
+  page.entityId = entityId;
+
+  const state = useOpenEntityPage<T, V>({
+    ...rest,
+    schemaSource: source,
+    fetch: fetch ?? (() => fetchFromSource(source, page.entityId)),
+    onSave: onSave ?? (() => saveToSource(source, page)),
+  } as UseEntityPageParams<T, V>);
+
+  page.state = state;
+
+  return state;
+}
+
+interface PageRef<T, V extends FieldValues> {
+  entityId?: string;
+  state?: EntityPageState<T, V>;
+}
+
+async function fetchFromSource<T>(
+  source: SchemaSource<T>,
+  entityId?: string,
+): Promise<{ entity: T | undefined }> {
+  if (!entityId) {
+    return { entity: undefined };
+  }
+
+  const { backend } = await source.loadSchema();
+  return { entity: await required(backend.get, 'reading')(entityId) };
+}
+
+async function saveToSource<T, V extends FieldValues>(
+  source: SchemaSource<T>,
+  page: PageRef<T, V>,
+): Promise<{ updatedEntity: T }> {
+  const { entityId, state } = page;
+  const { backend } = await source.loadSchema();
+  const values = state!.form.getValues() as Partial<T>;
+
+  // Which write to run follows the route, not whether an entity happens to be
+  // loaded: an id whose entity is missing (deleted, or filtered out by
+  // permissions) must fail rather than quietly create a second record.
+  if (!entityId) {
+    return {
+      updatedEntity: await required(backend.create, 'creating')(values),
+    };
+  }
+
+  const { entity } = state!;
+  if (!entity) {
+    throw new Error(`The source has no entity "${entityId}" to update`);
+  }
+
+  return {
+    updatedEntity: await required(
+      backend.update,
+      'updating',
+    )({ ...entity, ...values } as T),
+  };
+}
+
+function required<F>(fn: F | undefined, action: string): F {
+  if (!fn) {
+    throw new Error(`The source doesn't support ${action} items`);
+  }
+  return fn;
+}