@wix/patterns 1.459.0 → 1.460.0

package/dist/docs/CustomFieldType/add-field-modal.tsx

@@ -0,0 +1,206 @@
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import { EditableTable, defineFieldType } from '@wix/patterns';
+import type { EditableColumn, Field } from '@wix/patterns';
+import {
+  useSchemaSource,
+  useEditableTableCollection,
+} from '@wix/patterns/schema';
+import type {
+  CollectionBackend,
+  FieldActions,
+  LoadedSchema,
+  Schema,
+} from '@wix/patterns/schema';
+
+type Task = { id: string; name: string; progress?: number };
+
+function CustomFieldTypeFieldModal() {
+  // Plain object store (the live-example scope shadows the global `Map`).
+  const [store] = React.useState<{ tasks: Task[]; nextId: number }>(() => ({
+    nextId: 4,
+    tasks: [
+      { id: '1', name: 'Design homepage', progress: 80 },
+      { id: '2', name: 'Set up payments', progress: 100 },
+      { id: '3', name: 'Write product descriptions', progress: 25 },
+    ],
+  }));
+
+  const clamp = (value: number) =>
+    Math.max(0, Math.min(100, Math.round(value) || 0));
+
+  const ProgressCellView = ({ value }: { value: number }) => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+      <div
+        style={{
+          width: '80px',
+          height: '6px',
+          borderRadius: '3px',
+          background: '#DFE5EB',
+          overflow: 'hidden',
+        }}
+      >
+        <div
+          style={{
+            width: `${clamp(value ?? 0)}%`,
+            height: '100%',
+            background: '#3899EC',
+          }}
+        />
+      </div>
+      <span>{clamp(value ?? 0)}%</span>
+    </div>
+  );
+
+  const progressFieldType = defineFieldType<number>({
+    type: 'docs.progress',
+    display: {
+      label: 'Progress',
+      icons: { Small: () => <span>%</span>, Medium: () => <span>%</span> },
+    },
+    filter: { filterable: false },
+    value: { defaultValue: 0, isEmpty: (v) => v == null },
+    capabilities: { sortable: true },
+    editableTable: {
+      ViewComponent: ProgressCellView,
+      serialize: (v) => String(clamp(v ?? 0)),
+      deserialize: (raw) => clamp(parseFloat(raw)),
+    },
+    // Opts the type into the add-field modal: it shows in the type picker with
+    // the definition's label and icons, and a created field arrives at the
+    // source's addField as { type: 'CUSTOM', customType: 'docs.progress' }.
+    fieldModal: {
+      creatable: true,
+      namePlaceholder: 'e.g. Progress',
+      subtitle: 'A 0–100% progress bar',
+      group: 'Custom types',
+    },
+  });
+
+  const [schema] = React.useState<Schema>(() => ({
+    id: 'docs-custom-field-type-modal',
+    fields: {},
+    displayField: 'name',
+    idField: 'id',
+    itemPermissions: { createItem: true, updateItem: true, deleteItem: true },
+    // Enables the add-field flow — the editable table shows the "+" header
+    // button, which opens the add-field modal.
+    schemaPermissions: {
+      createField: true,
+      updateField: true,
+      deleteField: true,
+    },
+  }));
+
+  // In-memory field CRUD: each mutation returns the updated fields map, which
+  // the source merges into the loaded schema so the columns update in place.
+  const fieldActions: FieldActions = {
+    addField: async (field) => {
+      schema.fields = { ...schema.fields, [field.id]: field };
+      return schema.fields;
+    },
+    editField: async (fieldId, updates) => {
+      const existing = schema.fields[fieldId];
+      if (existing) {
+        schema.fields = {
+          ...schema.fields,
+          [fieldId]: { ...existing, ...updates } as Field,
+        };
+      }
+      return schema.fields;
+    },
+    deleteField: async (fieldId) => {
+      const rest = { ...schema.fields };
+      delete rest[fieldId];
+      schema.fields = rest;
+      return schema.fields;
+    },
+  };
+
+  const backend: CollectionBackend<Task> = {
+    find: async ({ search = '', sort = [] }) => {
+      const found = store.tasks.filter((task) =>
+        task.name.toLowerCase().includes(search.toLowerCase()),
+      );
+      if (sort.length) {
+        const [{ fieldName, order }] = sort;
+        found.sort((a, b) => {
+          const left = a[fieldName as keyof Task] ?? 0;
+          const right = b[fieldName as keyof Task] ?? 0;
+          const diff = left < right ? -1 : left > right ? 1 : 0;
+          return order === 'asc' ? diff : -diff;
+        });
+      }
+      return { items: found, total: found.length };
+    },
+    create: async (entity) => {
+      const created = { id: `task-${store.nextId++}`, name: '', ...entity };
+      store.tasks = [...store.tasks, created];
+      return created;
+    },
+    update: async (entity) => {
+      store.tasks = store.tasks.map((task) =>
+        task.id === entity.id ? entity : task,
+      );
+      return entity;
+    },
+    bulkDelete: async (entityIds) => {
+      store.tasks = store.tasks.filter((task) => !entityIds.includes(task.id));
+    },
+  };
+
+  const loadSchema = async (): Promise<LoadedSchema<Task>> => ({
+    schema,
+    backend,
+    fieldActions,
+  });
+
+  const columns: EditableColumn<Task>[] = [
+    {
+      id: 'name',
+      title: 'Name',
+      cellType: 'text',
+      getValue: (task) => task.name,
+      setValue: (task, value) => ({ ...task, name: value }),
+      width: 220,
+    },
+  ];
+
+  const source = useSchemaSource<Task>({
+    collectionId: 'docs-custom-field-type-modal',
+    loadSchema,
+    fieldTypes: [progressFieldType],
+    // The modal renders only what the source declares: these standard picker
+    // options plus every creatable custom type (appended automatically).
+    fieldModal: {
+      text: {
+        addTitle: 'Add a field',
+        editTitle: 'Edit field',
+      },
+      types: [
+        {
+          patternsType: 'SHORT_TEXT',
+          label: 'Text',
+          subtitle: 'Titles, paragraph',
+          group: 'Essentials',
+        },
+        {
+          patternsType: 'NUMBER',
+          label: 'Number',
+          subtitle: 'ID, rating, order number',
+          group: 'Essentials',
+        },
+      ],
+    },
+  });
+  const state = useEditableTableCollection<Task>(source);
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Tasks' }} />
+      <CollectionPage.Content>
+        <EditableTable state={state} columns={columns} />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}

package/dist/docs/CustomFieldType/editable-cell.tsx

@@ -0,0 +1,206 @@
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import { EditableTable, defineFieldType } from '@wix/patterns';
+import type { CellEditProps, EditableColumn, Field } from '@wix/patterns';
+import {
+  useSchemaSource,
+  useEditableTableCollection,
+} from '@wix/patterns/schema';
+import type {
+  CollectionBackend,
+  LoadedSchema,
+  Schema,
+} from '@wix/patterns/schema';
+
+type Task = { id: string; name: string; progress?: number };
+
+function CustomFieldTypeSpreadsheet() {
+  // Plain object store (the live-example scope shadows the global `Map`).
+  const [store] = React.useState<{ tasks: Task[]; nextId: number }>(() => ({
+    nextId: 6,
+    tasks: [
+      { id: '1', name: 'Design homepage', progress: 80 },
+      { id: '2', name: 'Set up payments', progress: 100 },
+      { id: '3', name: 'Write product descriptions', progress: 25 },
+      { id: '4', name: 'Configure shipping', progress: 55 },
+      { id: '5', name: 'Launch campaign', progress: 0 },
+    ],
+  }));
+
+  const clamp = (value: number) =>
+    Math.max(0, Math.min(100, Math.round(value) || 0));
+
+  const ProgressCellView = ({ value }: { value: number }) => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+      <div
+        style={{
+          width: '80px',
+          height: '6px',
+          borderRadius: '3px',
+          background: '#DFE5EB',
+          overflow: 'hidden',
+        }}
+      >
+        <div
+          style={{
+            width: `${clamp(value ?? 0)}%`,
+            height: '100%',
+            background: '#3899EC',
+          }}
+        />
+      </div>
+      <span>{clamp(value ?? 0)}%</span>
+    </div>
+  );
+
+  const ProgressCellEdit = ({
+    value,
+    onChange,
+    onCommit,
+    onCancel,
+    inputRef,
+  }: CellEditProps<number>) => {
+    const input = React.useRef<HTMLInputElement>(null);
+    React.useImperativeHandle(inputRef, () => ({
+      focus: () => input.current?.focus(),
+    }));
+    return (
+      <input
+        ref={input}
+        type="number"
+        min={0}
+        max={100}
+        value={value ?? 0}
+        // parseFloat, not Number — the example scope shadows `Number`.
+        onChange={(event) => onChange(parseFloat(event.target.value))}
+        onKeyDown={(event) => {
+          if (event.key === 'Enter') {
+            onCommit();
+          }
+          if (event.key === 'Escape') {
+            onCancel();
+          }
+        }}
+        style={{
+          width: '100%',
+          height: '100%',
+          border: 'none',
+          outline: 'none',
+        }}
+      />
+    );
+  };
+
+  const progressFieldType = defineFieldType<number>({
+    type: 'docs.progress',
+    display: {
+      label: 'Progress',
+      icons: { Small: () => <span>%</span>, Medium: () => <span>%</span> },
+    },
+    // This example focuses on the editable cell; opt out of filtering explicitly.
+    filter: { filterable: false },
+    value: { defaultValue: 0, isEmpty: (v) => v == null },
+    capabilities: { sortable: true },
+    editableTable: {
+      ViewComponent: ProgressCellView,
+      EditComponent: ProgressCellEdit,
+      serialize: (v) => String(clamp(v ?? 0)),
+      deserialize: (raw) => clamp(parseFloat(raw)),
+      normalizeOnCommit: (v) => clamp(v ?? 0),
+      onTypeToEdit: ({ key }) =>
+        /^\d$/.test(key) ? { value: parseInt(key, 10) } : undefined,
+    },
+    // Items here appear on the field's actions menus (e.g. the editable
+    // table's column header menu) — only for fields of this type.
+    actions: {
+      items: [
+        {
+          key: 'progress-only-action',
+          label: 'This is action only for progress bar',
+          onClick: () => window.alert('This is action only for progress bar'),
+        },
+      ],
+    },
+  });
+
+  const progressField: Field = {
+    id: 'progress',
+    displayName: 'Progress',
+    type: 'CUSTOM',
+    customType: 'docs.progress',
+  };
+
+  const schema: Schema = {
+    id: 'docs-custom-field-type-editable',
+    fields: { progress: progressField },
+    displayField: 'name',
+    idField: 'id',
+    itemPermissions: { createItem: true, updateItem: true, deleteItem: true },
+  };
+
+  const backend: CollectionBackend<Task> = {
+    // Sorting is delegated to the backend: `find` receives `sort`
+    // ({ fieldName, order }[]) and owns applying it.
+    find: async ({ search = '', sort = [] }) => {
+      const found = store.tasks.filter((task) =>
+        task.name.toLowerCase().includes(search.toLowerCase()),
+      );
+      if (sort.length) {
+        const [{ fieldName, order }] = sort;
+        found.sort((a, b) => {
+          const left = a[fieldName as keyof Task] ?? 0;
+          const right = b[fieldName as keyof Task] ?? 0;
+          const diff = left < right ? -1 : left > right ? 1 : 0;
+          return order === 'asc' ? diff : -diff;
+        });
+      }
+      return { items: found, total: found.length };
+    },
+    create: async (entity) => {
+      const created = { id: `task-${store.nextId++}`, name: '', ...entity };
+      store.tasks = [...store.tasks, created];
+      return created;
+    },
+    update: async (entity) => {
+      store.tasks = store.tasks.map((task) =>
+        task.id === entity.id ? entity : task,
+      );
+      return entity;
+    },
+    bulkDelete: async (entityIds) => {
+      store.tasks = store.tasks.filter((task) => !entityIds.includes(task.id));
+    },
+  };
+
+  const loadSchema = async (): Promise<LoadedSchema<Task>> => ({
+    schema,
+    backend,
+  });
+
+  const columns: EditableColumn<Task>[] = [
+    {
+      id: 'name',
+      title: 'Name',
+      cellType: 'text',
+      getValue: (task) => task.name,
+      setValue: (task, value) => ({ ...task, name: value }),
+      width: 220,
+    },
+  ];
+
+  const source = useSchemaSource<Task>({
+    collectionId: 'docs-custom-field-type-editable',
+    loadSchema,
+    fieldTypes: [progressFieldType],
+  });
+  const state = useEditableTableCollection<Task>(source);
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Tasks' }} />
+      <CollectionPage.Content>
+        <EditableTable state={state} columns={columns} />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}

package/dist/docs/CustomFieldType/entity-page-form.tsx

@@ -0,0 +1,133 @@
+import React from 'react';
+import { defineFieldType } from '@wix/patterns';
+import type { Field, FormFieldComponentProps } from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+import {
+  EntityPage,
+  EntityPageFieldsCard,
+  useEntityPage,
+  useSchemaSource,
+} from '@wix/patterns/schema';
+import type {
+  CollectionBackend,
+  LoadedSchema,
+  Schema,
+} from '@wix/patterns/schema';
+import { Input } from '@wix/design-system';
+
+type Task = { id: string; name: string; progress?: number };
+
+function CustomFieldTypeEntityPage() {
+  // Plain object store (the live-example scope shadows the global `Map`).
+  const [store] = React.useState<{ task: Task }>(() => ({
+    task: { id: '1', name: 'Design homepage', progress: 80 },
+  }));
+
+  const clamp = (value: number) =>
+    Math.max(0, Math.min(100, Math.round(value) || 0));
+
+  // The entity-page form input. The entity page owns the form wiring and the
+  // field UI (label, error message from the definition's value.validate) —
+  // this renders only the input.
+  const ProgressFormField = ({
+    value,
+    onChange,
+    onBlur,
+  }: FormFieldComponentProps<number>) => (
+    <Input
+      type="number"
+      min={0}
+      max={100}
+      suffix={<Input.Affix>%</Input.Affix>}
+      value={String(value ?? 0)}
+      // parseFloat, not Number — the example scope shadows `Number`.
+      onChange={(event) => onChange(clamp(parseFloat(event.target.value)))}
+      onBlur={onBlur}
+    />
+  );
+
+  const progressFieldType = defineFieldType<number>({
+    type: 'docs.progress',
+    display: {
+      label: 'Progress',
+      icons: { Small: () => <span>%</span>, Medium: () => <span>%</span> },
+    },
+    filter: { filterable: false },
+    value: {
+      defaultValue: 0,
+      isEmpty: (v) => v == null,
+      // Runs on every surface that validates the field — the entity-page
+      // form wires it into its own validation.
+      validate: (v) =>
+        v != null && (v < 0 || v > 100)
+          ? 'Progress must be between 0 and 100'
+          : null,
+    },
+    // Required once the field renders on an entity page — development throws
+    // without it; production skips the field.
+    form: { Component: ProgressFormField },
+  });
+
+  const progressField: Field = {
+    id: 'progress',
+    displayName: 'Progress',
+    type: 'CUSTOM',
+    customType: 'docs.progress',
+  };
+
+  const schema: Schema = {
+    id: 'docs-custom-field-type-entity-page',
+    fields: {
+      name: { id: 'name', displayName: 'Name', type: 'SHORT_TEXT' } as Field,
+      progress: progressField,
+    },
+    displayField: 'name',
+    idField: 'id',
+  };
+
+  // The entity page reads and writes the entity through the source's backend:
+  // `fetch` derives from `get`, saving from `update`.
+  const backend: CollectionBackend<Task> = {
+    find: async () => ({ items: [store.task], total: 1 }),
+    get: async () => store.task,
+    update: async (entity) => {
+      store.task = entity;
+      return entity;
+    },
+  };
+
+  const loadSchema = async (): Promise<LoadedSchema<Task>> => ({
+    schema,
+    backend,
+  });
+
+  const source = useSchemaSource<Task>({
+    collectionId: 'docs-custom-field-type-entity-page',
+    loadSchema,
+    fieldTypes: [progressFieldType],
+  });
+
+  const form = useForm();
+  const state = useEntityPage<Task>(source, {
+    parentPageId: '',
+    form,
+    entityId: '1',
+    saveSuccessToast: 'Saved',
+    saveErrorToast: () => 'Failed to save',
+  });
+
+  return (
+    <EntityPage state={state} dataHook="docs-custom-field-type-entity-page">
+      <EntityPage.Header title={{ text: store.task.name }} />
+      <EntityPage.Content>
+        <EntityPage.MainContent>
+          <EntityPageFieldsCard
+            title="Fields"
+            subtitle="The Progress field renders through its `form` slot"
+            minHeight="204px"
+          />
+        </EntityPage.MainContent>
+      </EntityPage.Content>
+    </EntityPage>
+  );
+}

package/dist/docs/CustomFieldType/table-cell-and-filter.tsx

@@ -0,0 +1,165 @@
+import React from 'react';
+import { CollectionPage } from '@wix/patterns/page';
+import {
+  Table,
+  defineFieldType,
+  idNameArrayFilter,
+  MultiInlineCheckboxFilter,
+} from '@wix/patterns';
+import type { Field, FilterProps } from '@wix/patterns';
+import { useSchemaSource, useTableCollection } from '@wix/patterns/schema';
+import type {
+  CollectionBackend,
+  LoadedSchema,
+  Schema,
+} from '@wix/patterns/schema';
+
+type Task = { id: string; name: string; progress?: number };
+type Bucket = { id: string; name: string };
+
+function CustomFieldTypeTable() {
+  const tasks: Task[] = [
+    { id: '1', name: 'Design homepage', progress: 80 },
+    { id: '2', name: 'Set up payments', progress: 100 },
+    { id: '3', name: 'Write product descriptions', progress: 25 },
+    { id: '4', name: 'Configure shipping', progress: 55 },
+    { id: '5', name: 'Launch campaign', progress: 0 },
+  ];
+
+  const ProgressCell = ({ value }: { value: number }) => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+      <div
+        style={{
+          width: '80px',
+          height: '6px',
+          borderRadius: '3px',
+          background: '#DFE5EB',
+          overflow: 'hidden',
+        }}
+      >
+        <div
+          style={{
+            width: `${value ?? 0}%`,
+            height: '100%',
+            background: '#3899EC',
+          }}
+        />
+      </div>
+      <span>{value ?? 0}%</span>
+    </div>
+  );
+
+  // The option id encodes the range; the backend parses it back.
+  const BUCKETS: Bucket[] = [
+    { id: '0-33', name: 'Low (0-33%)' },
+    { id: '34-66', name: 'Medium (34-66%)' },
+    { id: '67-100', name: 'High (67-100%)' },
+  ];
+
+  const progressFieldType = defineFieldType<number>({
+    type: 'docs.progress',
+    display: {
+      label: 'Progress',
+      icons: { Small: () => <span>%</span>, Medium: () => <span>%</span> },
+    },
+    filter: {
+      createFilter: () => idNameArrayFilter<Bucket>(),
+      Component: (props: FilterProps<Bucket[]>) => (
+        <MultiInlineCheckboxFilter {...props} data={BUCKETS} />
+      ),
+    },
+    value: { defaultValue: 0, isEmpty: (v) => v == null },
+    capabilities: { sortable: true },
+    table: {
+      CellComponent: ({ value }) => <ProgressCell value={value} />,
+      width: '160px',
+    },
+    actions: {
+      items: [
+        {
+          key: 'about-progress',
+          label: 'About this field type',
+          onClick: (field) =>
+            window.alert(`"${field.displayName}" is a custom field type.`),
+        },
+      ],
+    },
+  });
+
+  // The field is typed CUSTOM and points at the definition through `customType`.
+  const progressField: Field = {
+    id: 'progress',
+    displayName: 'Progress',
+    type: 'CUSTOM',
+    customType: 'docs.progress',
+  };
+
+  const schema: Schema = {
+    id: 'docs-custom-field-type-table',
+    fields: { progress: progressField },
+    displayField: 'name',
+    idField: 'id',
+  };
+
+  // Like filtering, sorting is delegated to the backend: `find` receives
+  // `sort` ({ fieldName, order }[]) and owns applying it.
+  const backend: CollectionBackend<Task> = {
+    find: async ({ search = '', filters = {}, sort = [] }) => {
+      const buckets = (filters as { progress?: Bucket[] }).progress;
+      const found = tasks.filter(
+        (task) =>
+          task.name.toLowerCase().includes(search.toLowerCase()) &&
+          (!buckets?.length ||
+            buckets.some(({ id }) => {
+              // parseInt, not Number — the example scope shadows `Number`.
+              const [min, max] = id
+                .split('-')
+                .map((part) => parseInt(part, 10));
+              const progress = task.progress ?? 0;
+              return progress >= min && progress <= max;
+            })),
+      );
+      if (sort.length) {
+        const [{ fieldName, order }] = sort;
+        found.sort((a, b) => {
+          const left = a[fieldName as keyof Task] ?? 0;
+          const right = b[fieldName as keyof Task] ?? 0;
+          const diff = left < right ? -1 : left > right ? 1 : 0;
+          return order === 'asc' ? diff : -diff;
+        });
+      }
+      return { items: found, total: found.length };
+    },
+  };
+
+  const loadSchema = async (): Promise<LoadedSchema<Task>> => ({
+    schema,
+    backend,
+  });
+
+  const source = useSchemaSource<Task>({
+    collectionId: 'docs-custom-field-type-table',
+    loadSchema,
+    fieldTypes: [progressFieldType],
+  });
+  const state = useTableCollection<Task>(source);
+
+  return (
+    <CollectionPage height="400px">
+      <CollectionPage.Header title={{ text: 'Tasks' }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          columns={[
+            {
+              id: 'name',
+              title: 'Name',
+              render: (task) => task.name,
+              width: '220px',
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+}