@wix/patterns 1.476.0 → 1.478.0

package/dist/docs/useSchemaSource.md

@@ -6,88 +6,48 @@ Paths written as `dist/…` below are relative to the `@wix/patterns` package ro
 
 Examples below are illustrative: each one demonstrates this page's API, and everything around it — data source, layout, http client — is only scaffolding to make that runnable.
 
-Some of that scaffolding is environment-scoped and is **not** needed to use this component: `@wix/patterns-cms`. Those resolve only against a Wix build environment (a Yoshi flow's runtime, a generated service client, an internal sibling package) — substitute your own data source and http client rather than installing them.
-
 ## Design
 
 ### Description
 
-A **schema source** describes a collection once: its fields, how to read and write its items, and, optionally, how to add, edit and delete fields. The `@wix/patterns/schema` entry builds the page from it. Columns, filters, grid cards, entity-page forms and field management all come from the source, so you don't list them by hand.
+The `@wix/patterns/schema` entry builds a page from a **Wix Data (CMS) collection**. Its source, `useCmsSchemaSource` from `@wix/patterns-cms`, describes the collection once: its fields, how to read and write its items, and how to add, edit and delete fields. Columns, filters, grid cards, entity-page forms and field management all come from the source, so you don't list them by hand.
+
+**For any other data, don't use this entry or `@wix/patterns-cms`.** Use the `@wix/patterns` hooks (`useTableCollection` and the rest) with your own `fetchData` and `columns`.
 
-Every page follows the same three steps:
+Every CMS page follows the same three steps:
 
-1. **Create a source** for the collection.
+1. **Create the source** with `useCmsSchemaSource`.
 2. **Pass it to a collection hook** — `useTableCollection(source)`, `useGridCollection(source)`, `useEditableTableCollection(source)`, `useLayoutSwitchCollection(source, …)`, or `useEntityPage(source, …)` for a single item.
 3. **Render the state** with the component of the same name from `@wix/patterns/schema` — `Table`, `Grid`, `EditableTable`, `LayoutSwitch`, `EntityPage` (with `EntityPageFieldsCard` for the fields).
 
 ```ts
-import {
-  useSchemaSource,
-  useTableCollection,
-  Table,
-} from '@wix/patterns/schema';
-
-const source = useSchemaSource<Task>({
-  collectionId: 'tasks',
-  loadSchema: loadTasksSchema,
-});
-const state = useTableCollection<Task>(source);
+import { useTableCollection, Table } from '@wix/patterns/schema';
+import { useCmsSchemaSource } from '@wix/patterns-cms';
+
+const source = useCmsSchemaSource<Item>({ collectionId: 'Products' });
+const state = useTableCollection<Item>(source);
 
 <Table state={state} />;
 ```
 
 Take the component from `@wix/patterns/schema`, not from `@wix/patterns`. Fields such as dates, media and references render components that need the source in React context, and only the schema-entry components provide it.
 
-#### Choosing a source
-
-- **A Wix Data (CMS) collection — `useCmsSchemaSource`** from `@wix/patterns-cms`. Loads the collection's fields and items, and brings the CMS add/edit field modal. The field changes (the "+" header button, edit, delete) need the user's permissions: pass `includeUserPermissions: true` and the site's `metasiteId`. Without them, fields can't be changed.
-
-  ```ts
-  import { useCmsSchemaSource } from '@wix/patterns-cms';
-
-  const source = useCmsSchemaSource<Item>({ collectionId: 'Products' });
-  ```
-
-- **A platformized entity — `usePlatformizedSource`**. You keep your own item access (`backend.find`, plus optional writes). The source lets users add fields on top of your entity. Your entity's own fields are not part of it, so you still write their columns.
-
-  ```ts
-  import { usePlatformizedSource } from '@wix/patterns/schema';
+#### The source
 
-  const source = usePlatformizedSource<Product>({
-    fqdn: 'stores.catalog.product',
-    backend: { find: queryProducts },
-  });
-  ```
+`useCmsSchemaSource` loads the collection's fields, items and permissions, wires reference fields to the collections they point at, and brings the add/edit field modal with the types Wix Data can create. Don't write your own source for a CMS collection: you would lose all of that.
 
-- **Any other data — `useSchemaSource`**. You write `loadSchema`, which returns the fields (`schema`), the item access (`backend`), and optionally the field changes (`fieldActions`). This is also where you register custom field types (`fieldTypes`) and set up the add-field modal (`fieldModal`).
-
-  ```ts
-  import { useSchemaSource } from '@wix/patterns/schema';
-
-  const source = useSchemaSource<Task>({
-    collectionId: 'tasks',
-    loadSchema: async () => ({
-      schema: tasksSchema,
-      backend: tasksBackend,
-      fieldActions: tasksFieldActions,
-    }),
-  });
-  ```
+- **Field changes** (the "+" header button, edit, delete) need the user's permissions: pass `includeUserPermissions: true`. They are loaded for the site the patterns container runs in (`environment.msid`); pass `metasiteId` only to load them for another site. Without them, fields can't be changed.
+- **Custom field types** are registered with `fieldTypes` — see **Custom Field Types**.
+- **Install** `@wix/patterns-cms` at the version that depends on your exact `@wix/patterns` version. Any other version installs a second copy of `@wix/patterns`, and the page splits across two React contexts, which neither `tsc` nor a build reports.
 
 A source is created once per `collectionId`. Changing its other options on a later render has no effect. To switch collections, render the page again with a React `key` that includes the new id.
 
-#### What `loadSchema` returns
-
-- `schema` (`Schema`) — the fields keyed by id, plus `idField`, `displayField`, and `schemaPermissions` (which field changes the user may make). Without `schemaPermissions`, the fields can't be edited.
-- `backend` (`CollectionBackend`) — `find` is required. It receives the query's `search`, `filters`, `sort` and paging, and must apply all of them. A control that the backend ignores will show but do nothing. `get`, `create`, `update`, `delete`, `bulkDelete` and `bulkInsert` are optional. Each one you provide turns on the matching UI (for example, row edits in `EditableTable`).
-- `fieldActions` (`FieldActions`) — optional. `addField`, `editField`, `deleteField` and the other field changes. Each one except `renameField` returns the collection's updated fields, and the page applies them without loading the schema again. `renameField` returns nothing.
-
 #### Compared with the classic hooks
 
 |                                    | Classic (`@wix/patterns`)              | Schema (`@wix/patterns/schema`)                                                                                        |
 | ---------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| Data                               | `fetchData` on the hook options        | the source's `backend.find`                                                                                            |
-| `queryName`, `itemKey`, `itemName` | required on the hook                   | from the source (`collectionId`, `idField`, `displayField`)                                                            |
+| Data                               | `fetchData` on the hook options        | the collection, through `useCmsSchemaSource`                                                                           |
+| `queryName`, `itemKey`, `itemName` | required on the hook                   | from the source (the collection id, `_id`, the display field)                                                          |
 | Table columns                      | `columns` required                     | from the fields. `columns` is optional: its columns come first, and one with a field's id replaces that field's column |
 | Changing the fetch                 | replace `fetchData`                    | `wrapFetchData(next)` wraps the source's fetch                                                                         |
 | Field management                   | `fieldsSource` / `dataExtension` props | always on, from the source                                                                                             |
@@ -99,12 +59,13 @@ A source is created once per `collectionId`. Changing its other options on a lat
 
 
 ```tsx
-import { useSchemaSource, useTableCollection, Table } from '@wix/patterns/schema';
+import { useTableCollection, Table } from '@wix/patterns/schema';
+import { useCmsSchemaSource } from '@wix/patterns-cms';
 ```
 
 ### CMS collection
 
-What you get: a table over a Wix Data collection with no columns written by hand. `useCmsSchemaSource` loads the fields and the items. Every field becomes a column with its type icon, and the "+" header button adds a field once user permissions are loaded (`includeUserPermissions` and `metasiteId`). (In these docs `useCmsSchemaSource` uses in-memory data so it runs with no backend.)
+What you get: a table over a Wix Data collection with no columns written by hand. `useCmsSchemaSource` loads the fields and the items. Every field becomes a column with its type icon, and the "+" header button adds a field once user permissions are loaded (`includeUserPermissions: true`). (In these docs `useCmsSchemaSource` uses in-memory data so it runs with no backend.)
 
 Example code: read `dist/examples/useSchemaSource/cms-collection.tsx`
 
@@ -114,36 +75,13 @@ What you get: the columns from the fields, plus one you add. `columns` adds colu
 
 Example code: read `dist/examples/useSchemaSource/extra-columns-and-data.tsx`
 
-### Your own source
-
-What you get: a source over any data. `loadSchema` returns the fields (`schema`), the item access (`backend`), and optionally the field changes (`fieldActions`). `find` receives search, filters and sort and must apply them. Try it: search, sort by a column, or add a field with the "+" header button. The new field is stored in memory, so it resets on refresh.
-
-Example code: read `dist/examples/useSchemaSource/your-own-source.tsx`
-
 ## API
 
 ### Overview
 
-Options of `useSchemaSource` (`SchemaSourceInput<T>`). Only `collectionId` and `loadSchema` are required.
+Options of `useSchemaSource`, which `useCmsSchemaSource` builds on. A CMS page passes `useCmsSchemaSource` its own options (`collectionId`, `includeUserPermissions`, `metasiteId`, `fieldTypes`, …) instead — see `UseCmsSchemaSourceDeps` in the type index.
 
 ### Props
 
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `references` | `Record<string, SchemaSource<any>>` | No | - | Sources for collections this one references, keyed by the referenced collection id. A renderer resolves a reference field through the matching entry — its `loadSchema` gives the referenced schema and `sourceFetchData` queries the referenced items. Default: none. |
-| `getReferencedCollectionSource` | `((collectionId: string) => SchemaSource<any>)` | No | - | Lazy source lookup for a referenced collection that is not in `references`. Is used when a reference field is created in the add field modal. The returned source owns its own async schema/item loading. |
-| `itemKey` | `((item: T) => string)` | No | - | Stable row identity. Default: `row[idField]`. |
-| `itemName` | `((item: T) => string)` | No | - | Row display label. Default: `row[displayField]`. |
-| `searchableFieldIds` | `((schema: Schema) => string[])` | No | - | Fields free-text search runs against. Default: `[displayField]`. |
-| `fieldModal` | `FieldModalInput` | No | - | What the add/edit field modal shows. Default: no types, generic titles. |
-| `fieldTypes` | `FieldTypeDefinition<unknown>[]` | No | - | Consumer-defined field types: how a field of that type renders, filters and validates wherever it appears. A field with `type: 'CUSTOM'` resolves its definition here by `customType`. The add/edit field modal never reads this — see `fieldModal`. Default: none. |
-| `getFieldPresentation` | `((field: Field) => FieldPresentation)` | No | - | Overrides one existing field's type label, icons and collection-picker label. Does not change its type, values or add-field options. |
-| `canAddFields` | `((schema: Schema) => boolean)` | No | - | Default: `schemaPermissions.createField`. |
-| `canEditField` | `((field: Field, schema: Schema) => boolean)` | No | - | Default: `schemaPermissions.updateField`, except for system fields and the id field. |
-| `canDeleteField` | `((field: Field, schema: Schema) => boolean)` | No | - | Default: `schemaPermissions.deleteField`, except for system fields and the id field. |
-| `getDeleteFieldConfirmation` | `((field: Field, schema: Schema) => DeleteFieldConfirmation)` | No | - | Resolved when deletion is requested. Undefined keeps the default dialog. |
-| `fieldPermissions` | `FieldPermissions` | No | - | Permission defaults shown in the modal. Absent ⇒ no permissions section. |
-| `supportsPii` | `boolean` | No | - | Default: `false`. |
-| `getFieldValue` | `((item: T, field: Field) => unknown)` | No | - | The value of a field on an item. Default: `item[field.id]`. |
-| `setFieldValue` | `((item: T, field: Field, value: unknown) => T)` | No | - | Writes a field's value on an item, returning the updated item. Default: `{ ...item, [field.id]: value }`. |
+Read `dist/dts-bundle/hooks/useSchemaSource.d.ts` for `useSchemaSource`'s props. Shared shapes cut to a one-line stub there hold 16 of them: `dist/dts-bundle/types/SchemaSourceInput.d.ts` (16).