@retailcrm/embed-ui-v1-components 0.9.23-alpha.3 → 0.9.24

package/AGENTS.md

@@ -70,6 +70,8 @@ Commonly used exports from `remote` include:
 - Prefer package public exports over reimplementing CRM-styled controls manually.
 - Match component choice to semantics:
   use `UiField` for labeled form controls, `UiAlert` for state messages, `UiPageHeader` for page-level headings.
+- For widget targets, keep inline UI compact: prefer `UiToolbarButton`, `UiToolbarLink`, short text, and icons.
+- Move complex widget UI into `UiModalSidebar` or `UiModalWindow` instead of expanding the target slot.
 - Keep imports on the public package boundary.
 - If you are unsure whether something is public, assume only exports from `remote` and `assets/*` are safe for consumer code.
 - If a needed capability is missing from the public API, say that clearly instead of suggesting internal imports.
@@ -96,7 +98,7 @@ Commonly used exports from `remote` include:
 
   <UiPageFooter>
     <template #actions>
-      <UiButton @click="save">
+      <UiButton variant="success" @click="save">
         Сохранить
       </UiButton>
     </template>
@@ -120,6 +122,14 @@ const save = () => {}
 </script>
 ```
 
+For page actions, use `Success Primary` for the strongest save/apply/create action, usually in
+`UiPageFooter`. Use `Default Primary` for another important action with a different meaning, and
+move neighboring actions to secondary or tertiary appearances.
+`UiPageHeader` and `UiPageFooter` share the same page-level action scope. When a page is split into
+`UiCollapseBox` sections, each collapse footer starts a local action scope: it can have its own
+single `Default Primary` action, while neighboring local actions should still use secondary or
+tertiary appearances.
+
 ## If You Need More Context
 
 - Package README:

package/docs/AI.md

@@ -32,27 +32,29 @@ When generating UI code, use this order:
 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.
+5. read [`WidgetComposition.yml`](./profiles/widgets/WidgetComposition.yml) when the task is about UI
+   mounted through `defineWidgetRunner`;
+6. use [`FORMAT.md`](./FORMAT.md) as the schema for what information is considered reliable;
+7. read [`STYLING.md`](./STYLING.md) when the task is about classes, variables, typography, or visual zones;
+8. 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
+- In `@retailcrm/embed-ui-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
+- In `@retailcrm/embed-ui-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
+- In `@retailcrm/embed-ui-v1-endpoint`, `docs/page-routes.md` explains how page `code`, CRM route
+  names, and `definePageRunner` are connected.
+- In `@retailcrm/embed-ui-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
+- In `@retailcrm/embed-ui-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.
+- In `@retailcrm/embed-ui-v1-contexts`, `docs/ru/CONCEPT.md` explains predefined CRM contexts such
+  as `order/card`, `customer/card`, `user/current`, and `settings`.
+- In `@retailcrm/embed-ui-v1-contexts`, `docs/ru/CUSTOM.md` explains custom-field contexts.
 
 ## Default Recommendation For Common Forms
 
@@ -87,6 +89,8 @@ Default screen rules:
   card/settings page, multi-column page, collapse-block page, modal sidebar, or modal window;
 - use `UiPageHeader` for page identity and top-level actions;
 - use `UiPageFooter` for page-level save/cancel/delete actions instead of recreating a local footer;
+- use one `Success Primary` button for the strongest save/apply/create action that commits a result; use `Default Primary`
+  only for another important action with a different meaning;
 - keep filters and controls near the content they affect;
 - use `UiField` around labeled form controls;
 - use `UiTable` for structured result lists;
@@ -121,6 +125,16 @@ Suggested query names:
 - `sort` and `direction` for sorting;
 - `page` and `pageSize` for pagination.
 
+## Default Recommendation For Widgets
+
+When building a widget mounted into a CRM target, keep the inline target UI compact and predictable:
+
+- read [`WidgetComposition.yml`](./profiles/widgets/WidgetComposition.yml) before composing widget UI;
+- render only simple inline UI in the target: `UiToolbarButton`, `UiToolbarLink`, short text, and icons;
+- move forms, tables, maps, filters, summaries, and multi-step flows into `UiModalSidebar` or `UiModalWindow`;
+- avoid custom panels, page headers, page footers, wide fixed layouts, or standalone screens inside the target slot;
+- read the endpoint target profile before choosing labels, modal type, or data access.
+
 ## External Documentation Patterns
 
 These references are useful when extending the profiles and examples in this package:

package/docs/PROFILES.md

@@ -7,6 +7,7 @@ The current profile layer is structured like this:
 - the index stays in markdown so both humans and agents can navigate it easily;
 - component profiles live in `docs/profiles/components/*.yml`;
 - page-composition profiles live in `docs/profiles/pages/*.yml`;
+- widget-composition profiles live in `docs/profiles/widgets/*.yml`;
 - YAML is the source of truth for structure, props, slots, emits, composition, page patterns, and AI rules.
 
 ## Table Of Contents
@@ -34,6 +35,7 @@ Use these entrypoints:
 - [`COMPONENTS.md`](./COMPONENTS.md) for the full linked component index
 - `docs/profiles/components/*.yml` for per-component machine-readable profiles
 - `docs/profiles/pages/*.yml` for page, modal, sidebar, filter, table, and settings-layout profiles
+- `docs/profiles/widgets/*.yml` for embedded widget composition profiles
 
 Current high-signal core profiles:
 
@@ -62,6 +64,10 @@ Current page profiles:
 - [`ModalSidebar`](./profiles/pages/ModalSidebar.yml)
 - [`ModalWindow`](./profiles/pages/ModalWindow.yml)
 
+Current widget profiles:
+
+- [`WidgetComposition`](./profiles/widgets/WidgetComposition.yml)
+
 ## What To Read First
 
 - `key_props` if you need to choose a component quickly.
@@ -71,6 +77,7 @@ Current page profiles:
 - `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.
+- `profiles/widgets/*.yml` if the task is about UI mounted through `defineWidgetRunner`.
 
 ## Styling Reads
 
@@ -82,3 +89,4 @@ Current page profiles:
 - All new updates should be made in YAML profiles.
 - Keep component-level details in `profiles/components`.
 - Keep page-composition details in `profiles/pages`.
+- Keep widget-composition details in `profiles/widgets`.

package/docs/README.md

@@ -62,7 +62,9 @@ If you need to generate UI quickly:
 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
+7. the widget composition profile from [`PROFILES.md`](./PROFILES.md) if the task is about UI mounted
+   through `defineWidgetRunner`
+8. [`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/UiButton.yml

@@ -228,7 +228,9 @@ composition:
 
 ai_notes:
   do:
-    - Start with appearance=primary for the main CTA.
+    - Start with appearance=primary for the main CTA, then choose variant by meaning.
+    - Use variant="success" for the strongest create/save/apply action when it commits a result, and keep only one Success Primary on a page.
+    - Use the default variant for an important primary action that is not the strongest commit action.
     - Use secondary or tertiary for neighboring actions near titles.
   avoid:
     - Do not replace UiButton with UiLink when the action should read as a button.

package/docs/profiles/components/UiCollapseBox.yml

@@ -76,6 +76,26 @@ examples:
       import MyCustomIcon from '@retailcrm/embed-ui-v1-components/assets/sprites/actions/info.svg'
       import { UiCollapseBox } from '@retailcrm/embed-ui-v1-components/remote'
       </script>
+  - title: Section with local action
+    code: |
+      <template>
+        <UiCollapseBox>
+          <template #title>Connection settings</template>
+          <template #body-content>Section form content</template>
+          <template #footer-content>
+            <UiButton @click="saveSection">Save section</UiButton>
+          </template>
+        </UiCollapseBox>
+      </template>
+
+      <script lang="ts" setup>
+      import {
+        UiButton,
+        UiCollapseBox,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const saveSection = () => {}
+      </script>
 use_when:
   - You need a ready-to-use collapsible box.
   - You need grouped expandable sections with consistent visuals.
@@ -112,8 +132,12 @@ ai_notes:
   do:
     - Use UiCollapseBox for structured disclosure UI.
     - Put the summary in the header and details in the body; avoid hiding critical required fields.
+    - Treat the footer and footer-content slots as a local action area for the section.
+    - Use one Default Primary button in a collapse footer for the main local action when the page has several independent sections.
+    - Use Success Primary in a collapse footer only when that section's local action is the strongest create/save/apply action.
   avoid:
     - Do not rebuild collapse header UI manually when this component already fits.
+    - Do not put several primary buttons of the same variant in one collapse footer.
 
 composition:
   works_well_with:

package/docs/profiles/components/UiPageFooter.yml

@@ -84,7 +84,7 @@ api:
           - wide content blocks
           - nested page sections
       layout_effect: Renders as the flexible left area and can contain multiple actions.
-      notes: Use this slot for save, apply, cancel, or save-and-exit actions.
+      notes: Use this slot for save, apply, cancel, or save-and-exit actions. The main save/apply action is usually a Success Primary UiButton.
     - name: aside
       zone: right-side aside action group
       creates: Separate aside action area.
@@ -156,6 +156,8 @@ ai_notes:
   do:
     - Import UiPageFooter from @retailcrm/embed-ui-v1-components/remote.
     - Use the actions slot for primary and secondary page actions.
+    - Use UiButton variant="success" for the strongest save/apply/create action in the footer.
+    - Keep neighboring footer actions less dominant unless they are the page's single Default Primary or Danger Primary by meaning.
     - Use the aside slot for a separated destructive or secondary action.
     - Put UiButton or another public action component inside slots.
     - Add page-level positioning only in the host/page layout when the footer must stick to a specific shell area.
@@ -164,3 +166,4 @@ ai_notes:
     - Do not import UiPageFooter from internal package paths.
     - Do not expect UiPageFooter to create buttons from props.
     - Do not expect UiPageFooter to be fixed to the bottom of the window automatically.
+    - Do not put multiple Success Primary, Default Primary, or Danger Primary actions with the same variant in the footer.

package/docs/profiles/pages/CardSettingsPage.yml

@@ -22,6 +22,7 @@ expected_structure:
   - Main content sits on a white content surface.
   - Content can include text, buttons, fields, checkboxes, radio groups, switches, and other form controls.
   - A bottom save panel is optional.
+  - If a bottom save panel is used, its main save or apply action should be Success Primary.
 
 recommended_components:
   - name: UiPageHeader
@@ -54,5 +55,6 @@ ai_notes:
     - Keep form controls grouped by task or semantic section.
     - Use UiField around labelled form controls.
     - Use tabs only when they reduce visible complexity without hiding required work.
+    - Keep save/apply as the strongest footer action and move neighboring actions to secondary or tertiary appearances unless their variant has a distinct page-level meaning.
   avoid:
     - Do not create a decorative landing page for operational settings.

package/docs/profiles/pages/CollapseBlockPage.yml

@@ -15,6 +15,9 @@ expected_structure:
   - Multiple collapsible blocks with their own content and local actions.
   - If the page contains only collapse blocks, the white page surface is not needed.
   - If every collapse block has its own save action, the bottom save panel is not needed.
+  - Treat each collapse block as a local mini-page with its own action priority.
+  - Each collapse block footer can have one Default Primary action for the main local action.
+  - If a block has a stronger create/save/apply action, make that local action Success Primary and move other actions to Default Primary, secondary, or tertiary by meaning.
   - Collapse blocks can contain text, buttons, fields, controls, and small tables.
 
 avoid_inside_blocks:
@@ -41,6 +44,9 @@ ai_notes:
   do:
     - Use collapses for optional or separable sections.
     - Keep required critical actions visible enough for the workflow.
+    - Put local section actions in the UiCollapseBox footer or footer-content slot.
+    - Apply primary-button limits inside each collapse block independently from the page-level footer.
   avoid:
     - Do not nest collapses inside collapses.
     - Do not hide complex tables inside collapse blocks.
+    - Do not add a global bottom save panel when each collapse block already has its own local save action.

package/docs/profiles/pages/EntityListPage.yml

@@ -17,7 +17,7 @@ expected_structure:
   - UiPageHeader with a page title.
   - One or more 48px page buttons on the right side of the header.
   - If there are multiple header buttons, one should be primary and the rest can be secondary or tertiary.
-  - The main primary button usually creates a new entity for the list.
+  - The main Default Primary button usually creates a new entity for the list when there is no stronger Success Primary action on the page.
   - Filters above the table, built from controls such as select, textbox, and combobox-like selection components.
   - Filter controls should run in rows of roughly 4-5 fields, then wrap to the next row.
   - Filters can be collapsible.

package/docs/profiles/pages/PageComposition.yml

@@ -16,9 +16,15 @@ scope:
 shared_rules:
   - Page title uses the large accent text style, Text large Accent 24.
   - Page-level actions sit to the right of the title.
-  - A page can have only one Default Primary button and one Success Primary button.
-  - Additional page actions can use secondary or tertiary variants when the task needs them.
-  - When a group has multiple buttons, the primary action should represent the main flow.
+  - A full page should have at most one page-level primary button of each variant, Success Primary, Default Primary, and Danger Primary.
+  - Use Success Primary for the page's strongest call to action when it creates or commits a result, such as Save, Apply, or Create.
+  - Place the page-level Success Primary action in UiPageFooter for save or apply workflows.
+  - Use Default Primary for an important action that is secondary to the Success Primary or does not commit a result.
+  - Use Danger Primary only for one critical destructive action when the page needs it.
+  - If several actions compete for attention, choose the main one for Success Primary and move the rest to Default Primary, secondary, tertiary, or dropdown actions by meaning.
+  - UiPageHeader actions and UiPageFooter actions belong to the same page-level action scope.
+  - Treat each UiCollapseBox footer as a separate local action scope with the same rules scoped to that section.
+  - A page can have several Default Primary buttons when each one belongs to a different UiCollapseBox footer.
   - Secondary actions should support or cancel the primary flow.
   - Components inside pages and blocks should be spaced by values divisible by 4px.
   - Common spacing values are 4, 8, 12, 16, 20, 24, 28, and 32px.
@@ -51,6 +57,8 @@ ai_notes:
     - Choose ModalSidebar only when the flow is compact.
     - Choose ModalWindow or a full page when content needs wide tables, several sections, or complex controls.
     - Keep operational CRM screens dense, scannable, and work-focused.
+    - Prefer variant="success" for the main save/apply/create action and keep it visually dominant.
   avoid:
     - Do not turn internal CRM work screens into marketing-style layouts.
     - Do not hide filters or primary workflow controls away from the content they affect.
+    - Do not place multiple Success Primary, Default Primary, or Danger Primary actions with the same variant in the page-level scope or inside one collapse-box scope.

package/docs/profiles/widgets/WidgetComposition.yml

@@ -0,0 +1,113 @@
+widget_profile: WidgetComposition
+summary: >
+  Composition rules for RetailCRM embedded widgets mounted into CRM target slots.
+  A widget should add a small predictable inline control to the host page and move
+  complex workflows into UiModalSidebar or UiModalWindow.
+
+use_when:
+  - You are building a component for defineWidgetRunner.
+  - You are rendering UI directly inside a widget target.
+  - You need to decide whether widget content belongs inline, in a modal sidebar, or in a modal window.
+
+inline_target_rules:
+  - Keep the UI rendered directly in the widget target simple and predictable.
+  - Prefer UiToolbarButton for compact widget actions.
+  - Prefer UiToolbarLink for compact navigation or link-shaped actions.
+  - Simple text is allowed when the widget only needs to show a short status, value, or hint.
+  - Icons are allowed when they clarify the toolbar action or compact status.
+  - Keep inline controls close to the target's existing density and spacing.
+  - Use one or a few compact controls; avoid turning the target slot into a standalone screen.
+
+complex_ui_rules:
+  - Put forms, tables, filters, maps, summaries, and multi-step workflows inside UiModalSidebar or UiModalWindow.
+  - Use UiModalSidebar for contextual editing, narrow forms, short lists, and side-panel workflows.
+  - Use UiModalWindow for wider workflows, maps, previews, or content that needs more horizontal room.
+  - The inline widget control should usually open the modal/sidebar and pass the relevant target/context data into that workflow.
+  - The modal/sidebar can use regular page-like components such as UiField, UiButton, UiTable, UiYandexMap, UiAlert, and UiLoader.
+
+avoid_inline:
+  - large cards
+  - full forms
+  - full tables
+  - filter panels
+  - nested page layouts
+  - custom panels that visually compete with the CRM page
+  - page-level headers or footers
+  - heavy custom spacing or wrappers that can break the host page layout
+
+recommended_components:
+  inline:
+    - name: UiToolbarButton
+      profile: ../components/UiToolbarButton.yml
+    - name: UiToolbarLink
+      profile: ../components/UiToolbarLink.yml
+  overlay:
+    - name: UiModalSidebar
+      profile: ../components/UiModalSidebar.yml
+    - name: UiModalWindow
+      profile: ../components/UiModalWindow.yml
+    - name: UiButton
+      profile: ../components/UiButton.yml
+    - name: UiField
+      profile: ../components/UiField.yml
+    - name: UiTable
+      profile: ../components/UiTable.yml
+
+examples:
+  - title: Compact widget action that opens a sidebar
+    code: |
+      <template>
+        <UiToolbarButton @click="opened = true">
+          Show details
+        </UiToolbarButton>
+
+        <UiModalSidebar v-model:opened="opened">
+          <template #title>Widget details</template>
+
+          <UiField id="note" label="Note">
+            <UiTextbox v-model:value="note" />
+          </UiField>
+
+          <template #footer>
+            <UiButton @click="save">Save</UiButton>
+            <UiButton appearance="secondary" @click="opened = false">Cancel</UiButton>
+          </template>
+        </UiModalSidebar>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+
+      import {
+        UiButton,
+        UiField,
+        UiModalSidebar,
+        UiTextbox,
+        UiToolbarButton,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const opened = ref(false)
+      const note = ref('')
+
+      const save = () => {
+        opened.value = false
+      }
+      </script>
+
+target_awareness:
+  - Read the endpoint target profile before choosing inline text, button labels, or modal type.
+  - Match the inline affordance to the target placement; field-level targets need especially compact UI.
+  - Do not infer data availability from the target name; read the linked context profiles.
+  - Avoid adding repeated or noisy controls to targets that can appear many times on one CRM page.
+
+ai_notes:
+  do:
+    - Render only compact, predictable UI directly in the widget target.
+    - Start inline widget UI with UiToolbarButton, UiToolbarLink, simple text, or an icon-enhanced compact action.
+    - Move complex UI into UiModalSidebar or UiModalWindow.
+    - Keep the host CRM page layout stable; the widget should enhance the target, not reshape the page.
+  avoid:
+    - Do not build a full page, dashboard, large card, form, or table directly inside a widget target.
+    - Do not use UiPageHeader or UiPageFooter for inline widget content.
+    - Do not add custom layout chrome around the widget unless the target profile explicitly calls for it.
+    - Do not make the target slot depend on wide fixed dimensions.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@retailcrm/embed-ui-v1-components",
   "bin": "bin/embed-ui-v1-components.mjs",
   "type": "module",
-  "version": "0.9.23-alpha.3",
+  "version": "0.9.24",
   "license": "MIT",
   "author": "RetailDriverLLC <integration@retailcrm.ru>",
   "repository": {