@wix/patterns 1.467.0 → 1.469.0

package/dist/docs/NestedTable.md

@@ -4,6 +4,10 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+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/ambassador-contacts-v4-contact/http`, `@wix/ambassador-contacts-v4-contact/types`, `@wix/yoshi-flow-bm`. 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
 
 ```tsx
@@ -227,25 +231,25 @@ useNestedTable({
 
 All levels are of the same entity type / query endpoint
 
-Example code: read `dist/docs/NestedTable/single-entity.tsx`
+Example code: read `dist/examples/NestedTable/single-entity.tsx`
 
 ### Various Entities
 
 Each level is of a different entity type / query endpoint
 
-Example code: read `dist/docs/NestedTable/various-entities.tsx`
+Example code: read `dist/examples/NestedTable/various-entities.tsx`
 
 ### Flat Mode (Search)
 
 Table is in flat mode when search is active. Items are not grouped by level. Items shown with breadcrumbs when provided in the level config. `fetchData` will be called with `query.fields` that contains the value `breadcrumbs` to signal that the breadcrumbs should be fetched.
 
-Example code: read `dist/docs/NestedTable/flat-mode-search.tsx`
+Example code: read `dist/examples/NestedTable/flat-mode-search.tsx`
 
 ### Filters
 
 A client-side example of using filters on nested table (ignore the fetchData implementation that should be use a real API on a real project)
 
-Example code: read `dist/docs/NestedTable/filters.tsx`
+Example code: read `dist/examples/NestedTable/filters.tsx`
 
 ---
 
@@ -255,11 +259,11 @@ Example code: read `dist/docs/NestedTable/filters.tsx`
 
 Accessing node by id and all its descendants
 
-Example code: read `dist/docs/NestedTable/node-api-usage.tsx`
+Example code: read `dist/examples/NestedTable/node-api-usage.tsx`
 
 ### Drag and Drop
 
-Example code: read `dist/docs/NestedTable/drag-and-drop.tsx`
+Example code: read `dist/examples/NestedTable/drag-and-drop.tsx`
 
 ## API
 

package/dist/docs/NumberRangeFilter.md

@@ -4,6 +4,8 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+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.
+
 ## Design
 
 ### Overview

package/dist/docs/OperatorFilterPicker.md

@@ -4,6 +4,8 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+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.
+
 ## Design
 
 ### Overview

package/dist/docs/PageWrapper.md

@@ -2,6 +2,8 @@
 
 **Category:** Base Components/Pages/Custom/PageWrapper
 
+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.
+
 ## Design
 
 ### Description

package/dist/docs/PatternsReactRoute.md

@@ -4,6 +4,8 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+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.
+
 ## Design
 
 ### Description
@@ -13,7 +15,13 @@ The `PatternsReactRoute` component defines a route for a Patterns element.
 This component extends [`Route`](https://reactrouter.com/en/main/route/route)  from `react-router-dom`.
 
 ### Usage
-Wrap `PatternsReactRoute` components with [`PatternsReactRouter`](/?path=/story/base-components-pages-routing--patternsreactrouter).
+Wrap `PatternsReactRoute` components with [`PatternsReactRouter`](/?path=/story/base-components-pages-router--patternsreactrouter),
+as **direct** children of it. A route nested any deeper — inside a page
+component, a wrapper component, or a fragment — is never converted to a
+`Route`, and React Router throws "[MyPage] is not a `<Route>` component. All
+component children of `<Routes>` must be a `<Route>` or `<React.Fragment>`" at
+render time. See [Patterns Router Overview → Every `PatternsReactRoute` must be
+a direct child](/?path=/story/base-components-pages-router--overview).
 
 ```tsx
 import { PatternsReactRoute } from '@wix/patterns/router';

package/dist/docs/PatternsReactRouter.md

@@ -4,6 +4,8 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+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.
+
 ## Design
 
 ### Description
@@ -15,14 +17,24 @@ This component extends [`BrowserRouter`](https://reactrouter.com/en/main/router-
 ### Usage
 
 1. Import `PatternsReactRouter` and `PatternsReactRoute`.
-1. For each page you want to route to, add a [`PatternsReactRoute`](./?path=%2Fstory%2Fbase-components-pages-routing--patternsreactroute) component inside the `PatternsReactRouter` component.
+1. For each page you want to route to, add a [`PatternsReactRoute`](./?path=%2Fstory%2Fbase-components-pages-router--patternsreactroute) component inside the `PatternsReactRouter` component.
+
+> **Every `PatternsReactRoute` must be a *direct* child of this component.** The
+> conversion from `PatternsReactRoute` to React Router's `Route` runs one level
+> deep over this component's children, so a route nested inside a page component,
+> a wrapper, or a fragment never gets converted, and React Router throws
+> "[MyPage] is not a `<Route>` component. All component children of `<Routes>`
+> must be a `<Route>` or `<React.Fragment>`" while rendering. Declaring the entity
+> routes inside the collection page component is the common way into this. See
+> [Patterns Router Overview → Every `PatternsReactRoute` must be a direct
+> child](./?path=/story/base-components-pages-router--overview).
 
 > **Route `path`s are relative to this router's own mount point**, not to
 > whatever host page, panel, or outer route you reached it through. Never
 > re-prefix a route's `path` with that outer name (e.g. a router mounted on a
 > page named "shifts" still roots its own routes at `path="/"`, not
 > `path="/shifts"`). See [Patterns Router Overview → Paths are relative to
-> where the router is mounted](./?path=/story/base-components-pages-routing--routingoverview).
+> where the router is mounted](./?path=/story/base-components-pages-router--overview).
 > The same rule applies to `parentPath` on `useEntityPage()` and to the `path`
 > passed to `navigateToEntityPage()` / `navigateToCollectionPage()`.
 

package/dist/docs/PickerContent.md

@@ -2,6 +2,8 @@
 
 **Category:** Base Components/Collections/Picker
 
+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.
+
 ## API
 
 ### Overview

package/dist/docs/PickerModal.md

@@ -4,6 +4,10 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+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/ambassador-contacts-v4-contact/http`, `@wix/ambassador-contacts-v4-contact/types`, `@wix/fe-essentials/react`. 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
@@ -21,7 +25,7 @@ import { PickerModal } from '@wix/patterns';
 
 ### Multi Select
 
-Example code: read `dist/docs/PickerModal/multi-select.tsx`
+Example code: read `dist/examples/PickerModal/multi-select.tsx`
 
 ---
 
@@ -29,7 +33,7 @@ Example code: read `dist/docs/PickerModal/multi-select.tsx`
 
  Radio button selection, the user can select one item only
 
-Example code: read `dist/docs/PickerModal/single-selection.tsx`
+Example code: read `dist/examples/PickerModal/single-selection.tsx`
 
 ---
 
@@ -37,7 +41,7 @@ Example code: read `dist/docs/PickerModal/single-selection.tsx`
 
  When the user opens the modal some of the items are already selected
 
-Example code: read `dist/docs/PickerModal/pre-selected-item.tsx`
+Example code: read `dist/examples/PickerModal/pre-selected-item.tsx`
 
 ---
 
@@ -45,7 +49,7 @@ Example code: read `dist/docs/PickerModal/pre-selected-item.tsx`
 
 You can add a `SingleSelectFilter` to your Picker Modal to filter its contents. To have it you need to pass `SingleSelectFilter` to the `filterComponent` prop in `PickerContent` and define the filter behavior when creating a state (check out `usePickerContent` and `usePickerModal`) in the example.
 
-Example code: read `dist/docs/PickerModal/with-filter-dropdown.tsx`
+Example code: read `dist/examples/PickerModal/with-filter-dropdown.tsx`
 
 ---
 
@@ -53,7 +57,7 @@ Example code: read `dist/docs/PickerModal/with-filter-dropdown.tsx`
 
 You can override the search behavior using the `search` prop. Pass `false` to hide search, or a custom `<CollectionSearch />`
 
-Example code: read `dist/docs/PickerModal/search-override.tsx`
+Example code: read `dist/examples/PickerModal/search-override.tsx`
 
 ## API
 

package/dist/docs/PickerStandalone.md

@@ -4,6 +4,10 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+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/ambassador-contacts-v4-contact/http`, `@wix/ambassador-contacts-v4-contact/types`, `@wix/fe-essentials/react`. 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.
+
 ## Import
 
 ```tsx
@@ -33,25 +37,25 @@ import { PickerStandalone } from '@wix/patterns';
 
 ### Basic
 
-Example code: read `dist/docs/PickerStandalone/basic.tsx`
+Example code: read `dist/examples/PickerStandalone/basic.tsx`
 
 ---
 
 ### Custom Empty State
 
-Example code: read `dist/docs/PickerStandalone/custom-empty-state.tsx`
+Example code: read `dist/examples/PickerStandalone/custom-empty-state.tsx`
 
 ---
 
 ### Custom Items
 
-Example code: read `dist/docs/PickerStandalone/custom-items.tsx`
+Example code: read `dist/examples/PickerStandalone/custom-items.tsx`
 
 ---
 
 ### CreateNew
 
-Example code: read `dist/docs/PickerStandalone/createnew.tsx`
+Example code: read `dist/examples/PickerStandalone/createnew.tsx`
 
 ## API
 

package/dist/docs/PrimaryActionButton.md

@@ -4,6 +4,8 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+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.
+
 ## Design
 
 ### Description

package/dist/docs/PrimaryActions.md

@@ -4,6 +4,8 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+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.
+
 ## Design
 
 ### Description

package/dist/docs/PrimaryPageButton.md

@@ -6,6 +6,8 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+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.
+
 ## Design
 
 ### Description

package/dist/docs/RadioGroupFilter.md

@@ -4,6 +4,8 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+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.
+
 ## Design
 
 ### Overview

package/dist/docs/Reading the Doc Indices.md

@@ -0,0 +1,186 @@
+# Reading the Doc Indices
+
+**Category:** Guides
+
+Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
+
+## Overview
+
+`@wix/patterns` ships two machine-readable indices under `dist/`, and they answer different
+questions. This is what their conventions mean, so a consumer reading them does not mistake
+a deliberate stub for a truncated file.
+
+| Index | Covers | Use it for |
+| --- | --- | --- |
+| `dist/docs/index.json` | every documented name — components, hooks, factories, state types, guides | finding a name's doc, its examples, and the guides |
+| `dist/dts-bundle/index.json` | a curated set of names | reading a real, fully-resolved declaration |
+
+The docs index is the larger of the two: everything documented has an entry, while the
+bundle index is deliberately curated. A name absent from the bundle index is not
+undocumented — look it up in the docs index.
+
+## What an entry can carry
+
+| Field | Meaning |
+| --- | --- |
+| `file` | the doc, relative to `dist/docs/` |
+| `category` | the Storybook path the doc was authored under |
+| `importPath` | the subpath to import this name from — take it from here rather than opening the page |
+| `bundle` | the declaration file that holds this name's props, relative to `dist/dts-bundle/` |
+| `symbols` | export names that resolve to this entry, where the doc's title is not the export |
+| `examples` | worked examples for this name, relative to `dist/examples/` |
+| `relatedComponents` | on a guide: the components it recommends |
+| `status`, `statusMessage` | see *Lifecycle*, below |
+
+**The three fields above answer three different questions, and one entry rarely needs all
+three.** `importPath` answers "where does this come from" without a read at all. `examples`
+answers "how is this called" — a worked example states the whole call, where the same answer
+assembled from a type chain can cost several files, since a `…Params` type is often a `Pick<>`
+of a declaration elsewhere and no file states the resolved shape. `bundle` answers "what are
+the props, and which are optional". Pick the one you need; reading a page for a fact the entry
+already carries is the common way a lookup gets expensive.
+
+`importPath` is parsed from the page's own import fence, so it agrees with what the doc shows.
+It is absent where a doc shows no `@wix/patterns` import of its own — a guide, or a type that is
+documented but not exported (see *Lifecycle* on `unreachable`). The bundle index derives the
+same fact independently, from `package.json`'s exports map, and the build warns when the two
+disagree.
+
+**The index is keyed by Storybook title, which is not always the export.** `ExportTo.md`
+documents `ExportButton`; `ToolbarFilters` is the entry for `CollectionToolbarFilters`. That
+is what `symbols` is for — resolve a name against the keys *and* the aliases.
+
+**Where a name's props live is stated, not guessed.** An entry with a `bundle` field has no
+props table in its doc: its `### Props` section points at that bundle on purpose, and the
+bundle is the better source because it keeps the `extends` clause with its exclusions. An
+entry without the field carries its own table.
+
+## A bundle stops where you stop writing code
+
+A bundle holds its own name's declaration plus every shape **you** would write by hand. It
+deliberately does not expand what the library hands back, so two kinds of one-line stub are
+answers rather than truncation.
+
+An empty body with a **"Produced by"** note means: call that hook to get one.
+
+```ts
+/**
+ * `TableState` — you receive this, you don't construct it.
+ * Produced by `useTableCollection()` (also `useAmbassadorTable()`, `useTableContext()`).
+ * Look `TableState` up in the bundle index for its own API.
+ */
+declare class TableState<T, F> {
+}
+```
+
+`<Table state={…}>` needs `useTableCollection()`, not `TableState`'s internals — but if you
+do need its members, it has its own entry, where the body is complete.
+
+A stub saying **"cut here because it has its own bundle"** means the same for a shape you do
+write: it was not copied in twice.
+
+Every bundle fits in a single read, and the index's `bytes` field says how large before you
+open one. So a bundle is never partially shown — anything that looks missing was cut
+deliberately, and both stubs name where it went.
+
+**And the index says where, before you open anything.** A stub names its destination, but
+only once you are already inside the file — so following the chain by hand costs one round
+trip per hop, and the hops are only visible one at a time. `readWith` is that same
+information in the index: the bundles this one stubs, with `readWithBytes` for what the set
+costs, the way `bytes` does for a single file.
+
+```json
+"Table": {
+  "file": "components/Table.d.ts",
+  "bytes": 5277,
+  "readWith": [
+    "types/CollectionTableBaseProps.d.ts",
+    "types/Filter.d.ts",
+    "types/TableState.d.ts"
+  ],
+  "readWithBytes": 31731
+}
+```
+
+Direct edges only — but every name in a `readWith` has its own entry here, carrying its own
+`readWith`, so **the full chain closes from this index alone, reading nothing.** Walk it to
+the depth your question needs and open that set in one parallel read. `Table`'s props, for
+instance: the chain through `CollectionTableBaseProps` reaches `ToolbarCollectionBaseProps`
+and `ToolbarBaseProps` (and is circular — `ToolbarBaseProps` re-stubs the first), which is
+four files and 68KB of the eighteen-file, 145KB closure. Resolving that here is why the
+field is not the closure itself: "batch all eighteen" trades a waterfall for a context
+flood.
+
+An entry with no `readWith` is self-contained; `file` is the whole answer.
+
+## Types the docs do not cover
+
+The bundles also hold the types those props are built from — `Filter<T>`, `RangeItem<T>`,
+`OffsetQuery`, a `…Props` interface. Several are declared in `@wix/bex-core`; the bundle
+resolves and inlines the real declaration, so the full shape is there with no deep
+`@wix/bex-core/dist/types/…` path to chase. Import them from `@wix/patterns` regardless of
+where the bundle shows them declared.
+
+## A bare import is the one shape that does not say where to look
+
+A plain `import { X } from '<module>'` with no note attached means the bundle recorded where
+a type is *declared* rather than where it is exported. What follows depends on the path:
+
+- **A normal entry point** — `react`, `react-hook-form`, `history`,
+  `@wix/design-system` — resolves the ordinary way.
+- **A deep internal path** — `@wix/design-system/dist/types/DropdownLayout` — is an upstream
+  defect. It is not a public entry point, and the name is often not re-exported from the
+  package root either, so there is no shorter import to substitute. Where the type is a prop
+  you fill in, use the shape the owning library documents; where it is a pass-through you
+  never construct, pass what the patterns doc shows or omit it, since these are optional.
+
+## Lifecycle
+
+`status` carries `"deprecated"`, and `statusMessage` names the replacement —
+`PrimaryPageButton` says *"Use `PrimaryActions` component instead."* Worth checking before
+committing to a name: a deprecated component still compiles and still renders, so nothing
+else in the lookup path will stop you. The doc itself also carries the notice, above the
+import example.
+
+A few names carry `"status": "unreachable"`, plus `"unexported": true` from **1.465.0** —
+the `…BaseProps` interfaces a component's props `extends`. Read them for the props they
+contribute; do not write an import for them.
+
+## Entry points
+
+`@wix/patterns` is 31 entry points, not one namespace, and `/form` re-exports
+`@wix/bex-core/form`. The `exports/` directory under `dist/dts-bundle/` holds one file per
+entry point, named after the subpath: the package root is
+`dist/dts-bundle/exports/index.d.ts`, `@wix/patterns/form` is
+`dist/dts-bundle/exports/form.d.ts`, and a nested one such as `@wix/patterns/testkit/backend`
+is `dist/dts-bundle/exports/testkit/backend.d.ts`.
+
+**Those files list only the curated names**, so they are not an inventory of the entry point:
+a subpath's real export surface can be larger, and a file holding nothing but a comment means
+no curated name lives there yet — not that the subpath does not exist. For the authoritative
+import line, read the doc of the name you want.
+
+**`/form` is where that gap is widest, so it is worth stating outright.** It is
+`export * from '@wix/bex-core/form'`, which is itself `export * from 'react-hook-form'`, so
+its real surface is react-hook-form's entire public API. The names the guides and examples
+write are curated and carry an `importPath` like anything else — `useForm`, `useController`,
+`Controller`, `ControllerProps`, `FieldValues`, `UseFormReturn`. The rest, `useWatch` and
+`useFieldArray` among them, import from `@wix/patterns/form` just the same while appearing in
+neither index, and react-hook-form's own docs are their reference. So a react-hook-form name
+is never unexported merely because the docs index has no page for it; none of them does.
+
+## Cross-references and examples
+
+Docs link to related names as Storybook URLs — `[TableState](./?path=/story/…--tablestate)`.
+Resolve the link text back to a file through `dist/docs/index.json`, the same way you found
+the first doc. There is no automatic multi-level expansion. Links to
+`https://www.docs.wixdesignsystem.com/` are the design system's, not this library's.
+
+Compound components have a doc per sub-part — `CollectionPage.md`,
+`CollectionPage.Header.md`, `CollectionPage.Content.md`.
+
+Heavy examples are written beside the doc rather than inlined. The doc keeps the heading and
+the description and names the path: `Example code: read \`dist/docs/ToolbarFilters/apply-changes.tsx\``.
+The same files are listed in the entry's `examples` field.
+
+

package/dist/docs/RequestId.md

@@ -2,6 +2,8 @@
 
 **Category:** Features/Display/Errors/RequestId
 
+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.
+
 ## Design
 
 ### Description

package/dist/docs/SecondaryActions.md

@@ -4,6 +4,8 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+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.
+
 ## Design
 
 ### Description

package/dist/docs/SettingsPage.AdditionalContent.md

@@ -2,6 +2,8 @@
 
 **Category:** Base Components/Pages/Settings Page
 
+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.
+
 ## API
 
 ### Overview

package/dist/docs/SettingsPage.Card.md

@@ -2,6 +2,8 @@
 
 **Category:** Base Components/Pages/Settings Page
 
+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.
+
 ## Examples
 
 ### Basic

package/dist/docs/SettingsPage.Content.md

@@ -2,6 +2,8 @@
 
 **Category:** Base Components/Pages/Settings Page
 
+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.
+
 ## API
 
 ### Overview

package/dist/docs/SettingsPage.Header.md

@@ -2,6 +2,10 @@
 
 **Category:** Base Components/Pages/Settings Page
 
+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/ambassador-cairo-dummyservice-v1-dummy-entity/types`. 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.
+
 ## Examples
 
 ### Basic

package/dist/docs/SettingsPage.MainContent.md

@@ -2,6 +2,8 @@
 
 **Category:** Base Components/Pages/Settings Page
 
+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.
+
 ## API
 
 ### Overview

package/dist/docs/SettingsPage.md

@@ -4,6 +4,8 @@
 
 Paths written as `dist/…` below are relative to the `@wix/patterns` package root — the directory holding its `package.json`.
 
+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.
+
 ## Overview
 
 ### Introduction
@@ -31,7 +33,7 @@ In summary, the ``SettingsPage`` component and the associated [`useSettingsPage`
 
 This example demonstrates a basic usage of the `SettingsPage`.
 
-Example code: read `dist/docs/SettingsPage/basic.tsx`
+Example code: read `dist/examples/SettingsPage/basic.tsx`
 
 ---
 
@@ -39,7 +41,7 @@ Example code: read `dist/docs/SettingsPage/basic.tsx`
 
 This example illustrates the use of both main and additional content.
 
-Example code: read `dist/docs/SettingsPage/2-columns.tsx`
+Example code: read `dist/examples/SettingsPage/2-columns.tsx`
 
 ---
 
@@ -47,7 +49,7 @@ Example code: read `dist/docs/SettingsPage/2-columns.tsx`
 
 This sample illustrates the skeleton state of an settings page based on the provided structure.
 
-Example code: read `dist/docs/SettingsPage/loading.tsx`
+Example code: read `dist/examples/SettingsPage/loading.tsx`
 
 ---
 
@@ -55,7 +57,7 @@ Example code: read `dist/docs/SettingsPage/loading.tsx`
 
 This example demonstrates the error state when fetching an settings fails.
 
-Example code: read `dist/docs/SettingsPage/error-on-fetch.tsx`
+Example code: read `dist/examples/SettingsPage/error-on-fetch.tsx`
 
 ---
 
@@ -63,7 +65,7 @@ Example code: read `dist/docs/SettingsPage/error-on-fetch.tsx`
 
 This example demonstrates the error toast when saving an settings fails.
 
-Example code: read `dist/docs/SettingsPage/error-on-save.tsx`
+Example code: read `dist/examples/SettingsPage/error-on-save.tsx`
 
 ---
 
@@ -73,7 +75,7 @@ Example code: read `dist/docs/SettingsPage/error-on-save.tsx`
 
 This demonstrates how to use [useController](https://react-hook-form.com/docs/usecontroller) with the default value set at the `Card.Content` level. Note that the `state.settings` value is initialized following the Card skeleton loader. To obtain the initial value, it must be accessed within the Card.Content child, as illustrated in the following example. Accessing it before or at a higher level will result in an `undefined` value.
 
-Example code: read `dist/docs/SettingsPage/input-initialization-with-usecontroller.tsx`
+Example code: read `dist/examples/SettingsPage/input-initialization-with-usecontroller.tsx`
 
 ---
 
@@ -81,7 +83,7 @@ Example code: read `dist/docs/SettingsPage/input-initialization-with-usecontroll
 
 This demonstrates how to use [Controller](https://react-hook-form.com/docs/usecontroller/controller) where you can easily access the settings by using `useSettings`. This method allows for accessing the settings much earlier in the process. As a result, the default value will be dynamically updated as soon as the settings itself is updated, as shown in the example below.
 
-Example code: read `dist/docs/SettingsPage/input-initialization-with-controller.tsx`
+Example code: read `dist/examples/SettingsPage/input-initialization-with-controller.tsx`
 
 ## API
 

package/dist/docs/SettingsPageState.md

@@ -2,6 +2,8 @@
 
 **Category:** Base Components/Pages/Settings Page/State
 
+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.
+
 ## API
 
 ### Overview