@retailcrm/embed-ui-v1-components 0.9.19 → 0.9.22-alpha.1

package/docs/AI.md

@@ -10,7 +10,6 @@ Only the public package contract is described below, without depending on the re
 - Package name: `@retailcrm/embed-ui-v1-components`
 - Purpose: UI components and UI helpers for RetailCRM JS extensions
 - Framework: Vue 3
-- Published Storybook: `https://retailcrm.github.io/embed-ui/v1-components/0.9.14/`
 - Primary public entrypoints:
   - `@retailcrm/embed-ui-v1-components/remote`
   - `@retailcrm/embed-ui-v1-components/host`
@@ -28,11 +27,32 @@ Only the public package contract is described below, without depending on the re
 
 When generating UI code, use this order:
 
-1. read [`COMPONENTS.md`](./COMPONENTS.md) to identify candidate components;
-2. open a detailed profile from [`PROFILES.md`](./PROFILES.md) if one exists;
-3. use [`FORMAT.md`](./FORMAT.md) as the schema for what information is considered reliable;
-4. read [`STYLING.md`](./STYLING.md) when the task is about classes, variables, typography, or visual zones;
-5. if no profile exists yet, fall back to [Storybook](https://retailcrm.github.io/embed-ui/v1-components/0.9.14/) docs and public type declarations, and state any inference explicitly.
+1. read [`../README.md`](../README.md) and [`../AGENTS.md`](../AGENTS.md) for package-level usage rules;
+2. read [`COMPONENTS.md`](./COMPONENTS.md) to identify candidate components;
+3. open a detailed profile from [`PROFILES.md`](./PROFILES.md) if one exists;
+4. read the relevant page profile from [`PROFILES.md`](./PROFILES.md) when the task is about complete
+   pages, modals, sidebars, filters, tables, or settings layouts;
+5. use [`FORMAT.md`](./FORMAT.md) as the schema for what information is considered reliable;
+6. read [`STYLING.md`](./STYLING.md) when the task is about classes, variables, typography, or visual zones;
+7. if no profile exists yet, fall back to public type declarations and state any inference explicitly.
+
+## Runtime Embedding References
+
+When generating code for a CRM extension, separate UI component choice from runtime placement:
+
+- [`targets` and contexts](../../v1-endpoint/docs/targets.md): explains that `target` is the CRM
+  embedding point, while `context` is the reactive CRM data available at that point.
+- [`menu placements`](../../v1-endpoint/docs/menu-placements.md): explains how host/manifest menu
+  items map to remote page codes.
+- [`page routes`](../../v1-endpoint/docs/page-routes.md): explains how page `code`, CRM route names,
+  and `definePageRunner` are connected.
+- [`defineWidgetRunner`](../../v1-endpoint/docs/define-widget-runner.md): shows how a widget receives
+  the current `target` prop.
+- [`definePageRunner`](../../v1-endpoint/docs/define-page-runner.md): shows how a page receives the
+  current `code` prop.
+- [`context concept`](../../v1-contexts/docs/ru/CONCEPT.md): explains predefined CRM contexts such as
+  `order/card`, `customer/card`, `user/current`, and `settings`.
+- [`custom context`](../../v1-contexts/docs/ru/CUSTOM.md): explains custom-field contexts.
 
 ## Default Recommendation For Common Forms
 
@@ -55,6 +75,65 @@ Typical compositions:
 - `UiPageHeader` + `UiButton`
 - `UiSelect` + `UiSelectOption`
 
+## Default Recommendation For Full Screens
+
+When building a complete extension screen, prioritize a working operational interface over a
+decorative landing page.
+
+Default screen rules:
+
+- use [`PageComposition.yml`](./profiles/pages/PageComposition.yml) to choose between an entity list,
+  card/settings page, multi-column page, collapse-block page, modal sidebar, or modal window;
+- use `UiPageHeader` for page identity and top-level actions;
+- keep filters and controls near the content they affect;
+- use `UiField` around labeled form controls;
+- use `UiTable` for structured result lists;
+- use `UiLink` for navigation and inline links, `UiButton` for commands;
+- use `UiLoader` with `overlay: true` when loading should dim the covered page or module content;
+- keep public imports on `@retailcrm/embed-ui-v1-components/remote`;
+- avoid custom markup that recreates textbox, select, button, link, or table chrome.
+
+## Default Recommendation For Table Screens
+
+When building a registry, catalog, journal, search result, order list, customer list, or any
+screen where users scan and refine datasets:
+
+- put search and filters directly above `UiTable`;
+- use `UiTextbox` for free-text search and `UiSelect` or compact toggle controls for finite filters;
+- keep filters, sorting, page, and page size in GET query parameters when the host app has routing;
+- hydrate initial filter and pagination state from the current query;
+- reset `page` to `1` when filters or sorting change;
+- debounce free-text search before writing query or fetching data;
+- use `UiTableSorter` for sortable headers;
+- use `UiTable` footer slots for summary, page-size controls, export, and pagination;
+- compose table footer controls with `UiTableFooterSection` and `UiTableFooterButton`, not regular `UiButton`;
+- use chevron icon assets for table footer previous/next controls instead of text glyphs;
+- add local CSS for table footer layout and states; use [`UiTable.yml`](./profiles/components/UiTable.yml)
+  for the reference table footer example;
+- set `size="small"` on `UiLink` inside table cells so links match table body typography.
+
+Suggested query names:
+
+- `q` for text search;
+- `status`, `managerId`, `dateFrom`, `dateTo` for filters;
+- `sort` and `direction` for sorting;
+- `page` and `pageSize` for pagination.
+
+## External Documentation Patterns
+
+These references are useful when extending the profiles and examples in this package:
+
+- [shadcn/ui Data Table source](https://github.com/shadcn-ui/ui/blob/main/apps/v4/content/docs/components/radix/data-table.mdx)
+  documents a scenario-first table build: base table, row actions, pagination, sorting,
+  filtering, visibility, row selection, and reusable table pieces.
+- [Nuxt UI v4 Table source](https://github.com/nuxt/ui/blob/v4/docs/content/docs/2.components/table.md)
+  documents table state, sorting, pagination, loading, empty state, slots, and advanced flows.
+- [Nuxt UI v2 Table source](https://github.com/nuxt/ui/blob/v2/docs/content/2.components/table.md)
+  is useful for explicit searchable, paginable, manual sorting, and reactive query examples.
+- [PrimeVue DataTable docs](https://primevue.org/datatable/)
+  are useful for Vue table patterns around filtering, pagination, selection, lazy loading, empty,
+  loading, and accessibility.
+
 ## What AI Needs In A Good Component Profile
 
 The most useful format for AI is a component profile that explicitly answers:
@@ -85,22 +164,25 @@ The preferred styling signal is:
 
 ## Current High-Signal Profiles
 
-- [`UiField`](./profiles/UiField.yml)
-- [`UiTextbox`](./profiles/UiTextbox.yml)
-- [`UiButton`](./profiles/UiButton.yml)
-- [`UiPageHeader`](./profiles/UiPageHeader.yml)
-- [`UiSelect`](./profiles/UiSelect.yml)
-- [`UiRadioSwitch`](./profiles/UiRadioSwitch.yml)
-- [`UiTabGroup`](./profiles/UiTabGroup.yml)
-- [`UiTab`](./profiles/UiTab.yml)
-- [`UiPopper`](./profiles/UiPopper.yml)
-- [`UiPopperConnector`](./profiles/UiPopperConnector.yml)
-- [`UiPopperTarget`](./profiles/UiPopperTarget.yml)
+- [`UiField`](./profiles/components/UiField.yml)
+- [`UiTextbox`](./profiles/components/UiTextbox.yml)
+- [`UiButton`](./profiles/components/UiButton.yml)
+- [`UiPageHeader`](./profiles/components/UiPageHeader.yml)
+- [`UiSelect`](./profiles/components/UiSelect.yml)
+- [`UiRadioSwitch`](./profiles/components/UiRadioSwitch.yml)
+- [`UiTabGroup`](./profiles/components/UiTabGroup.yml)
+- [`UiTab`](./profiles/components/UiTab.yml)
+- [`UiPopper`](./profiles/components/UiPopper.yml)
+- [`UiPopperConnector`](./profiles/components/UiPopperConnector.yml)
+- [`UiPopperTarget`](./profiles/components/UiPopperTarget.yml)
 
 ## Related Public Docs
 
 - [`README.md`](./README.md)
+- [`../README.md`](../README.md)
+- [`../AGENTS.md`](../AGENTS.md)
 - [`COMPONENTS.md`](./COMPONENTS.md)
 - [`FORMAT.md`](./FORMAT.md)
 - [`STYLING.md`](./STYLING.md)
+- [`PROFILES.md`](./PROFILES.md)
 - [`../AGENTS.md`](../AGENTS.md)

package/docs/COMPONENTS.md

@@ -10,80 +10,79 @@ Detailed AI-friendly profiles are collected in [`PROFILES.md`](./PROFILES.md).
 
 ## Form And Input
 
-- [`UiField`](./profiles/UiField.yml): field wrapper with label, hint, validation state, and slot props for ARIA wiring
-- [`UiTextbox`](./profiles/UiTextbox.yml): text or numeric input with prefix, suffix, clear action, and multiline mode
-- [`UiCheckbox`](./profiles/UiCheckbox.yml): boolean choice
-- [`UiRadio`](./profiles/UiRadio.yml): single choice
-- [`UiRadioSwitch`](./profiles/UiRadioSwitch.yml): segmented single-choice switch with inline or section-card appearance
-- [`UiRadioSwitchOption`](./profiles/UiRadioSwitchOption.yml): rich option child for UiRadioSwitch
-- [`UiToggleGroup`](./profiles/UiToggleGroup.yml): segmented multi-select group built from toggle buttons
-- [`UiToggleGroupOption`](./profiles/UiToggleGroupOption.yml): rich option child for UiToggleGroup
-- [`UiSwitch`](./profiles/UiSwitch.yml): state toggle
-- [`UiSlider`](./profiles/UiSlider.yml): ranged value selection
-- [`UiSelect`](./profiles/UiSelect.yml): select container for single or multiple choice
-- [`UiSelectOption`](./profiles/UiSelectOption.yml): select option
-- [`UiSelectOptionGroup`](./profiles/UiSelectOptionGroup.yml): grouped options
-- [`UiDatePicker`](./profiles/UiDatePicker.yml): date or date-range selection
-- [`UiTimePicker`](./profiles/UiTimePicker.yml): time selection
-- [`UiCalendar`](./profiles/UiCalendar.yml): calendar primitive
-- [`UiNumberStepper`](./profiles/UiNumberStepper.yml): numeric input with increment and decrement controls
+- [`UiField`](./profiles/components/UiField.yml): field wrapper with label, hint, validation state, and slot props for ARIA wiring
+- [`UiTextbox`](./profiles/components/UiTextbox.yml): text or numeric input with prefix, suffix, clear action, and multiline mode
+- [`UiCheckbox`](./profiles/components/UiCheckbox.yml): boolean choice
+- [`UiRadio`](./profiles/components/UiRadio.yml): single choice
+- [`UiRadioSwitch`](./profiles/components/UiRadioSwitch.yml): segmented single-choice switch with inline or section-card appearance
+- [`UiRadioSwitchOption`](./profiles/components/UiRadioSwitchOption.yml): rich option child for UiRadioSwitch
+- [`UiToggleGroup`](./profiles/components/UiToggleGroup.yml): segmented multi-select group built from toggle buttons
+- [`UiToggleGroupOption`](./profiles/components/UiToggleGroupOption.yml): rich option child for UiToggleGroup
+- [`UiSwitch`](./profiles/components/UiSwitch.yml): state toggle
+- [`UiSlider`](./profiles/components/UiSlider.yml): ranged value selection
+- [`UiSelect`](./profiles/components/UiSelect.yml): select container for single or multiple choice
+- [`UiSelectOption`](./profiles/components/UiSelectOption.yml): select option
+- [`UiSelectOptionGroup`](./profiles/components/UiSelectOptionGroup.yml): grouped options
+- [`UiDatePicker`](./profiles/components/UiDatePicker.yml): date or date-range selection
+- [`UiTimePicker`](./profiles/components/UiTimePicker.yml): time selection
+- [`UiCalendar`](./profiles/components/UiCalendar.yml): calendar primitive
+- [`UiNumberStepper`](./profiles/components/UiNumberStepper.yml): numeric input with increment and decrement controls
 
 ## Actions And Navigation
 
-- [`UiButton`](./profiles/UiButton.yml): main action button that can render as a button or anchor
-- [`UiToggleButton`](./profiles/UiToggleButton.yml): stateful toggle button primitive for standalone or grouped use
-- [`UiAddButton`](./profiles/UiAddButton.yml): add action button
-- [`UiCopyButton`](./profiles/UiCopyButton.yml): copy value action
-- [`UiToolbarButton`](./profiles/UiToolbarButton.yml): toolbar button
-- [`UiToolbarLink`](./profiles/UiToolbarLink.yml): toolbar link
-- [`UiLink`](./profiles/UiLink.yml): text link
-- [`UiMenuItem`](./profiles/UiMenuItem.yml): menu item
-- [`UiMenuItemGroup`](./profiles/UiMenuItemGroup.yml): menu item group
-- [`UiTabGroup`](./profiles/UiTabGroup.yml): tab navigation group with overflow handling and optional active panel
-- [`UiTab`](./profiles/UiTab.yml): declarative tab child for UiTabGroup
+- [`UiButton`](./profiles/components/UiButton.yml): main action button that can render as a button or anchor
+- [`UiToggleButton`](./profiles/components/UiToggleButton.yml): stateful toggle button primitive for standalone or grouped use
+- [`UiAddButton`](./profiles/components/UiAddButton.yml): add action button
+- [`UiCopyButton`](./profiles/components/UiCopyButton.yml): copy value action
+- [`UiToolbarButton`](./profiles/components/UiToolbarButton.yml): toolbar button
+- [`UiToolbarLink`](./profiles/components/UiToolbarLink.yml): toolbar link
+- [`UiLink`](./profiles/components/UiLink.yml): text link
+- [`UiMenuItem`](./profiles/components/UiMenuItem.yml): menu item
+- [`UiMenuItemGroup`](./profiles/components/UiMenuItemGroup.yml): menu item group
+- [`UiTabGroup`](./profiles/components/UiTabGroup.yml): tab navigation group with overflow handling and optional active panel
+- [`UiTab`](./profiles/components/UiTab.yml): declarative tab child for UiTabGroup
 
 ## Layout And Structure
 
-- [`UiPageHeader`](./profiles/UiPageHeader.yml): page or section header with an editable title and action zone
-- [`UiCollapse`](./profiles/UiCollapse.yml): collapsible section
-- [`UiCollapseBox`](./profiles/UiCollapseBox.yml): collapsible container
-- [`UiCollapseGroup`](./profiles/UiCollapseGroup.yml): multiple collapse coordination
-- [`UiScrollBox`](./profiles/UiScrollBox.yml): scrollable container
-- [`UiTransition`](./profiles/UiTransition.yml): transition wrapper
+- [`UiPageHeader`](./profiles/components/UiPageHeader.yml): page or section header with an editable title and action zone
+- [`UiCollapse`](./profiles/components/UiCollapse.yml): collapsible section
+- [`UiCollapseBox`](./profiles/components/UiCollapseBox.yml): collapsible container
+- [`UiCollapseGroup`](./profiles/components/UiCollapseGroup.yml): multiple collapse coordination
+- [`UiScrollBox`](./profiles/components/UiScrollBox.yml): scrollable container
+- [`UiTransition`](./profiles/components/UiTransition.yml): transition wrapper
 
 ## Feedback And Status
 
-- [`UiAlert`](./profiles/UiAlert.yml): contextual alert or notification
-- [`UiInfobox`](./profiles/UiInfobox.yml): highlighted explanatory block
-- [`UiError`](./profiles/UiError.yml): compact error state
-- [`UiLoader`](./profiles/UiLoader.yml): loading indicator
-- [`UiSkeleton`](./profiles/UiSkeleton.yml): content placeholder for loading state
-- [`UiTag`](./profiles/UiTag.yml): labels and statuses
+- [`UiAlert`](./profiles/components/UiAlert.yml): contextual alert or notification
+- [`UiInfobox`](./profiles/components/UiInfobox.yml): highlighted explanatory block
+- [`UiError`](./profiles/components/UiError.yml): compact error state
+- [`UiLoader`](./profiles/components/UiLoader.yml): loading indicator
+- [`UiSkeleton`](./profiles/components/UiSkeleton.yml): content placeholder for loading state
+- [`UiTag`](./profiles/components/UiTag.yml): labels and statuses
 
 ## Overlays And Modal Patterns
 
-- [`UiModalWindow`](./profiles/UiModalWindow.yml): modal window
-- [`UiModalWindowSurface`](./profiles/UiModalWindowSurface.yml): modal surface
-- [`UiModalSidebar`](./profiles/UiModalSidebar.yml): sidebar modal
-- [`UiTooltip`](./profiles/UiTooltip.yml): tooltip
-- [`UiPopper`](./profiles/UiPopper.yml): floating layer
-- [`UiPopperTarget`](./profiles/UiPopperTarget.yml): popper target
-- [`UiPopperConnector`](./profiles/UiPopperConnector.yml): target-to-floating connector
+- [`UiModalWindow`](./profiles/components/UiModalWindow.yml): modal window
+- [`UiModalWindowSurface`](./profiles/components/UiModalWindowSurface.yml): modal surface
+- [`UiModalSidebar`](./profiles/components/UiModalSidebar.yml): sidebar modal
+- [`UiTooltip`](./profiles/components/UiTooltip.yml): tooltip
+- [`UiPopper`](./profiles/components/UiPopper.yml): floating layer
+- [`UiPopperTarget`](./profiles/components/UiPopperTarget.yml): popper target
+- [`UiPopperConnector`](./profiles/components/UiPopperConnector.yml): target-to-floating connector
 
 ## Content And Data Display
 
-- [`UiAvatar`](./profiles/UiAvatar.yml): avatar
-- [`UiAvatarList`](./profiles/UiAvatarList.yml): avatar list
-- [`UiDate`](./profiles/UiDate.yml): formatted date display
-- [`UiImage`](./profiles/UiImage.yml): image display
-- [`UiTable`](./profiles/UiTable.yml): table root
-- [`UiTableColumn`](./profiles/UiTableColumn.yml): table column declaration
-- [`UiTableHeadCell`](./profiles/UiTableHeadCell.yml): table head cell primitive
-- [`UiTableBodyCell`](./profiles/UiTableBodyCell.yml): table body cell primitive
-- [`UiTableFooterSection`](./profiles/UiTableFooterSection.yml): table footer section container
-- [`UiTableFooterButton`](./profiles/UiTableFooterButton.yml): table footer action button
-- [`UiTableSorter`](./profiles/UiTableSorter.yml): table sort control primitive
-- [`UiYandexMap`](./profiles/UiYandexMap.yml): Yandex map component
+- [`UiAvatar`](./profiles/components/UiAvatar.yml): avatar
+- [`UiAvatarList`](./profiles/components/UiAvatarList.yml): avatar list
+- [`UiDate`](./profiles/components/UiDate.yml): formatted date display
+- [`UiTable`](./profiles/components/UiTable.yml): table root
+- [`UiTableColumn`](./profiles/components/UiTableColumn.yml): table column declaration
+- [`UiTableHeadCell`](./profiles/components/UiTableHeadCell.yml): table head cell primitive
+- [`UiTableBodyCell`](./profiles/components/UiTableBodyCell.yml): table body cell primitive
+- [`UiTableFooterSection`](./profiles/components/UiTableFooterSection.yml): table footer section container
+- [`UiTableFooterButton`](./profiles/components/UiTableFooterButton.yml): table footer action button
+- [`UiTableSorter`](./profiles/components/UiTableSorter.yml): table sort control primitive
+- [`UiYandexMap`](./profiles/components/UiYandexMap.yml): Yandex map component
 
 ## Helpers
 

package/docs/FORMAT.md

@@ -19,6 +19,10 @@ A good profile should let an agent answer these questions without opening the so
 
 Recommended filename: `<ComponentName>.yml`
 
+Component profiles should live in `docs/profiles/components`.
+Page-composition profiles should live in `docs/profiles/pages`.
+Use `examples` for copyable snippets and cross-link related profiles with relative `profile` paths.
+
 Minimal shape:
 
 ```yml
@@ -77,12 +81,6 @@ styling:
       line_height: 24px
       weight: 400
 
-examples:
-  - title: Basic example
-    goal: What the user or the agent is trying to build.
-    code: |
-      <UiComponent />
-
 ai_notes:
   do:
     - rule
@@ -220,15 +218,16 @@ Capture:
 - what happens to `aria-invalid`, `aria-labelledby`, `role`, `aria-expanded`, and similar attributes;
 - which keys affect behavior, if that behavior is documented.
 
-## 11. `examples` and `composition`
+## 11. `composition`
 
 List:
 
 - common combinations;
 - required neighboring components;
 - safe defaults for typical screens;
-- goal-oriented examples such as "build a table", "build an editable header", or "build a field with a select";
-- examples of correct and incorrect composition.
+- correct and incorrect composition patterns.
+
+Keep examples in YAML profiles focused, copyable, and aligned with the public package entrypoints.
 
 ## 12. `ai_notes`
 
@@ -244,6 +243,7 @@ A short list of rules specifically for code generation:
 - Use the exact names of props, emits, and slots.
 - For slots, describe not only the name, but also what the slot does and which content restrictions exist.
 - For styling, distinguish between safe CSS variables and descriptive class names.
+- Keep runnable examples in YAML profiles when they clarify safe public usage.
 - Do not mix "how the component looks right now" with "what is publicly guaranteed".
 - If behavior is inferred from implementation rather than public API, say that explicitly.
 - If information is missing, state the limitation rather than inventing details.
@@ -254,7 +254,7 @@ The following data can usually be obtained automatically or semi-automatically:
 
 - the list of public exports;
 - prop, emit, method, and enum names;
-- whether Storybook stories and examples exist;
+- whether profile examples exist;
 - the current root classes and layout zones from templates.
 
 These sections almost always need manual writing:

package/docs/PROFILES.md

@@ -1,12 +1,13 @@
-# Component Profiles
+# AI Profiles
 
-`PROFILES.md` is the entry point for machine-readable AI-friendly component profiles.
+`PROFILES.md` is the entry point for machine-readable AI-friendly profiles.
 
 The current profile layer is structured like this:
 
 - the index stays in markdown so both humans and agents can navigate it easily;
-- the actual profiles live in `docs/profiles/*.yml`;
-- YAML is the source of truth for structure, props, slots, emits, examples, and AI rules.
+- component profiles live in `docs/profiles/components/*.yml`;
+- page-composition profiles live in `docs/profiles/pages/*.yml`;
+- YAML is the source of truth for structure, props, slots, emits, composition, page patterns, and AI rules.
 
 ## Table Of Contents
 
@@ -18,9 +19,11 @@ The current profile layer is structured like this:
 
 ## Reading Order
 
-1. [`AI.md`](./AI.md)
-2. this index
-3. the relevant `.yml` profile
+1. [`../README.md`](../README.md)
+2. [`../AGENTS.md`](../AGENTS.md)
+3. [`AI.md`](./AI.md)
+4. this index
+5. the relevant `.yml` profile
 
 ## Current Coverage
 
@@ -29,23 +32,34 @@ Coverage is now expanding across the public component catalog.
 Use these entrypoints:
 
 - [`COMPONENTS.md`](./COMPONENTS.md) for the full linked component index
-- `docs/profiles/*.yml` for per-component machine-readable profiles
+- `docs/profiles/components/*.yml` for per-component machine-readable profiles
+- `docs/profiles/pages/*.yml` for page, modal, sidebar, filter, table, and settings-layout profiles
 
 Current high-signal core profiles:
 
-- [`UiField`](./profiles/UiField.yml)
-- [`UiTextbox`](./profiles/UiTextbox.yml)
-- [`UiButton`](./profiles/UiButton.yml)
-- [`UiToggleButton`](./profiles/UiToggleButton.yml)
-- [`UiToggleGroup`](./profiles/UiToggleGroup.yml)
-- [`UiPageHeader`](./profiles/UiPageHeader.yml)
-- [`UiSelect`](./profiles/UiSelect.yml)
-- [`UiRadioSwitch`](./profiles/UiRadioSwitch.yml)
-- [`UiTabGroup`](./profiles/UiTabGroup.yml)
-- [`UiTab`](./profiles/UiTab.yml)
-- [`UiPopper`](./profiles/UiPopper.yml)
-- [`UiPopperConnector`](./profiles/UiPopperConnector.yml)
-- [`UiPopperTarget`](./profiles/UiPopperTarget.yml)
+- [`UiField`](./profiles/components/UiField.yml)
+- [`UiTextbox`](./profiles/components/UiTextbox.yml)
+- [`UiButton`](./profiles/components/UiButton.yml)
+- [`UiToggleButton`](./profiles/components/UiToggleButton.yml)
+- [`UiToggleGroup`](./profiles/components/UiToggleGroup.yml)
+- [`UiPageHeader`](./profiles/components/UiPageHeader.yml)
+- [`UiSelect`](./profiles/components/UiSelect.yml)
+- [`UiRadioSwitch`](./profiles/components/UiRadioSwitch.yml)
+- [`UiTabGroup`](./profiles/components/UiTabGroup.yml)
+- [`UiTab`](./profiles/components/UiTab.yml)
+- [`UiPopper`](./profiles/components/UiPopper.yml)
+- [`UiPopperConnector`](./profiles/components/UiPopperConnector.yml)
+- [`UiPopperTarget`](./profiles/components/UiPopperTarget.yml)
+
+Current page profiles:
+
+- [`PageComposition`](./profiles/pages/PageComposition.yml)
+- [`EntityListPage`](./profiles/pages/EntityListPage.yml)
+- [`CardSettingsPage`](./profiles/pages/CardSettingsPage.yml)
+- [`MultiColumnPage`](./profiles/pages/MultiColumnPage.yml)
+- [`CollapseBlockPage`](./profiles/pages/CollapseBlockPage.yml)
+- [`ModalSidebar`](./profiles/pages/ModalSidebar.yml)
+- [`ModalWindow`](./profiles/pages/ModalWindow.yml)
 
 ## What To Read First
 
@@ -53,8 +67,9 @@ Current high-signal core profiles:
 - `props` if you need a broader practical API view.
 - `slots` if the task is about markup, zones, and allowed content.
 - `emits` if the component must be wired into screen logic.
-- `examples` if you need a working usage pattern quickly.
+- `examples` if you need copyable usage snippets.
 - `ai_notes` if the agent needs safe defaults and anti-patterns.
+- `profiles/pages/*.yml` if the task is about a full page, modal, sidebar, filter, table, or settings layout.
 
 ## Styling Reads
 
@@ -64,3 +79,5 @@ Current high-signal core profiles:
 ## Notes
 
 - All new updates should be made in YAML profiles.
+- Keep component-level details in `profiles/components`.
+- Keep page-composition details in `profiles/pages`.

package/docs/README.md

@@ -10,6 +10,8 @@ These docs are optimized for two main scenarios:
 
 ## Documentation Map
 
+- [`../AGENTS.md`](../AGENTS.md)
+  package-level instructions for AI assistants using the installed package.
 - [`AI.md`](./AI.md)
   a compact quickstart for AI agents: which entrypoint to prefer, which reading order to use,
   and which boundaries are safe by default.
@@ -20,7 +22,7 @@ These docs are optimized for two main scenarios:
 - [`STYLING.md`](./STYLING.md)
   shared guidance for reading classes, CSS variables, and typography in profiles.
 - [`PROFILES.md`](./PROFILES.md)
-  the index of YAML component profiles.
+  the index of YAML component and page profiles.
 
 ## Public Entrypoints
 
@@ -53,10 +55,14 @@ The same rule applies to `.ui-v1-*` selectors in profile `styling` sections.
 
 If you need to generate UI quickly:
 
-1. [`AI.md`](./AI.md)
-2. [`COMPONENTS.md`](./COMPONENTS.md)
-3. the relevant profile from [`PROFILES.md`](./PROFILES.md)
-4. [`STYLING.md`](./STYLING.md) if the task is about classes, variables, typography, or layout tuning
+1. [`../README.md`](../README.md)
+2. [`../AGENTS.md`](../AGENTS.md)
+3. [`AI.md`](./AI.md)
+4. [`COMPONENTS.md`](./COMPONENTS.md)
+5. the relevant profile from [`PROFILES.md`](./PROFILES.md)
+6. the relevant page profile from [`PROFILES.md`](./PROFILES.md) if the task is about complete pages,
+   modals, sidebars, filters, tables, or settings layouts
+7. [`STYLING.md`](./STYLING.md) if the task is about classes, variables, typography, or layout tuning
 
 If you are extending the docs:
 

package/docs/profiles/components/UiAddButton.yml

@@ -0,0 +1,134 @@
+component: UiAddButton
+summary: >
+  UiAddButton is an action-first button for add or create flows. It is close to UiButton,
+  but tuned for "create another item" scenarios and supports small descriptive additions.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiAddButton
+
+related_components:
+  - UiButton
+  - UiToolbarButton
+
+examples:
+  - title: Basic add button
+    code: |
+      <template>
+        <UiAddButton>
+          Add Button
+        </UiAddButton>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAddButton } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Small add button (`small`)
+    code: |
+      <template>
+        <UiAddButton small>
+          Add Button
+        </UiAddButton>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAddButton } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Description slot
+    code: |
+      <template>
+        <UiAddButton color="blue">
+          Add Button
+
+          <template #description>
+            Description
+          </template>
+        </UiAddButton>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAddButton } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Custom height
+    code: |
+      <template>
+        <UiAddButton :height="120">Add Button</UiAddButton>
+        <UiAddButton height="50%">Add Button</UiAddButton>
+
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAddButton } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+use_when:
+  - You need a dedicated create or add action.
+  - You need a compact add CTA with optional extra description.
+
+avoid_when:
+  - You need a regular text link.
+  - You need a generic button without add semantics.
+
+api:
+  key_props:
+    - name: color
+    - name: small
+    - name: disabled
+    - name: height
+  slots:
+    - name: icon
+      zone: leading-icon
+      creates: Leading icon area for the add action.
+    - name: description
+      zone: secondary-copy
+      creates: Optional secondary description near the main label.
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: button.ui-v1-add-button
+    tag: button
+  notes: Current root is a single action button with optional icon and description zones.
+
+geometry:
+  layout: button-like action root
+  root_display: flex
+  width_behavior: content-sized by default
+
+behavior:
+  notes:
+    - Behaves like a clickable add action with standard button focus and click semantics.
+
+ai_notes:
+  do:
+    - Use for create and add flows rather than generic submit actions.
+    - Use description only when it clarifies what will be added.
+  avoid:
+    - Do not replace a plain UiButton unless the add semantics are intentional.
+
+composition:
+  works_well_with:
+    - UiButton
+    - UiPageHeader
+    - UiToolbarButton
+  patterns:
+    - title: Add item action
+      notes: Use near a list, empty state, or repeatable form section where the action creates another item.
+    - title: Page primary create
+      notes: UiButton in UiPageHeader is often better for a main create action; use UiAddButton for local add-another flows.
+
+accessibility:
+  notes:
+    - Prefer visible text labels for interactive controls.
+    - For icon-only or custom visual content, provide an accessible name through the supported label, title, or ARIA attributes exposed by the component.
+    - Preserve native keyboard semantics by using the component root instead of recreating the control with arbitrary markup.
+  keyboard:
+    - Tab moves focus to the control when it is focusable.
+    - Enter or Space activates native button-like controls when the host implementation renders a button.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+  root_classes:
+    - .ui-v1-add-button