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

package/docs/profiles/pages/ModalSidebar.yml

@@ -0,0 +1,158 @@
+page_profile: ModalSidebar
+summary: >
+  Side-docked modal pattern for small contextual forms, local additional information,
+  or compact entity cards.
+
+use_when:
+  - You need a small contextual form.
+  - You need local additional information connected to the current page.
+  - You need a compact entity card with a limited number of fields and settings.
+
+examples_from_design:
+  - task card
+  - notifications
+  - new ticket
+  - scenario step editing
+
+examples:
+  - title: Footer actions
+    code: |
+      <template>
+          <div>
+              <UiButton @click="open = true">
+                  Open sidebar
+              </UiButton>
+
+              <UiModalSidebar v-model:opened="open">
+                  <template #title>
+                      Title
+                  </template>
+
+                  <div class="modal-sidebar-example__body">
+                      Sidebar content
+                  </div>
+
+                  <template #footer>
+                      <div class="modal-sidebar-footer">
+                          <div class="modal-sidebar-footer__main">
+                              <UiButton @click="save">
+                                  Save
+                              </UiButton>
+
+                              <UiButton appearance="secondary" @click="open = false">
+                                  Close
+                              </UiButton>
+                          </div>
+
+                          <UiButton
+                              aria-label="Delete"
+                              appearance="tertiary"
+                              class="modal-sidebar-footer__delete"
+                              variant="danger"
+                              @click="deleteItem"
+                          >
+                              <IconDelete
+                                  aria-hidden="true"
+                                  class="modal-sidebar-footer__delete-icon"
+                              />
+                          </UiButton>
+                      </div>
+                  </template>
+              </UiModalSidebar>
+          </div>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+
+      import IconDelete from '@retailcrm/embed-ui-v1-components/assets/sprites/ui/delete.svg'
+      import {
+        UiButton,
+        UiModalSidebar,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const open = ref(false)
+
+      const save = () => {
+        open.value = false
+      }
+
+      const deleteItem = () => {
+        open.value = false
+      }
+      </script>
+
+      <style scoped>
+      .modal-sidebar-example__body {
+        min-height: 360px;
+      }
+
+      .modal-sidebar-footer {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        width: 100%;
+      }
+
+      .modal-sidebar-footer__main {
+        display: flex;
+        align-items: center;
+        gap: 16px;
+      }
+
+      .modal-sidebar-footer__delete.ui-v1-button {
+        color: #8a96a6;
+      }
+
+      .modal-sidebar-footer__delete.ui-v1-button:hover,
+      .modal-sidebar-footer__delete.ui-v1-button:focus-visible {
+        color: #dd4040;
+      }
+
+      .modal-sidebar-footer__delete-icon {
+        display: block;
+        width: 24px;
+        height: 24px;
+      }
+      </style>
+
+size_rules:
+  - Sidebar can use 720px width.
+  - Sidebar can use 416px width.
+
+expected_structure:
+  - Fixed header at the top with title and close button.
+  - Header can also contain extra text, icon, button, or tag.
+  - If a sidebar opens from another sidebar, show a back arrow to return to the previous sidebar.
+  - Fixed footer at the bottom.
+  - Footer usually contains save, cancel or close, and delete actions.
+  - Footer can also contain a copy button or auxiliary text.
+  - Content can be flexible, but should stay compact.
+  - Small tables can be placed in sidebars.
+
+recommended_components:
+  - name: UiModalSidebar
+    profile: ../components/UiModalSidebar.yml
+  - name: UiButton
+    profile: ../components/UiButton.yml
+  - name: UiTag
+    profile: ../components/UiTag.yml
+  - name: UiField
+    profile: ../components/UiField.yml
+  - name: UiTextbox
+    profile: ../components/UiTextbox.yml
+  - name: UiSelect
+    profile: ../components/UiSelect.yml
+  - name: UiTable
+    profile: ../components/UiTable.yml
+    notes: Use only for small, simple tables.
+
+ai_notes:
+  do:
+    - Use for inspect, edit, or secondary workflows related to the current list or page.
+    - Keep the flow compact.
+  avoid:
+    - Do not use for bulky or complex interfaces.
+    - Do not use collapse blocks inside sidebars.
+    - Do not use two-column content on separate surfaces.
+    - Use a full page or modal window for bulky flows.

package/docs/profiles/pages/ModalWindow.yml

@@ -0,0 +1,55 @@
+page_profile: ModalWindow
+summary: >
+  Centered modal pattern for large contextual tables or additional local settings when a sidebar is not enough.
+
+use_when:
+  - You need a large local workflow.
+  - You need auxiliary table content.
+  - You need dense local settings that do not fit a sidebar.
+
+examples_from_design:
+  - adding products to an order
+  - marking products in an order
+  - viewing an email from the communication list
+  - merging duplicates in the database cleanliness section
+
+size_rules:
+  - Modal can use 960px width.
+  - Modal can use full screen with side margins.
+
+expected_structure:
+  - Fixed header at the top with title and close button.
+  - Header can include extra text, icon, button, or tag.
+  - Fixed footer at the bottom.
+  - Footer usually contains save, cancel or close, and delete actions.
+  - Footer can also contain a copy button or auxiliary text.
+  - Content can be flexible; tables are a common modal use case.
+  - If a modal contains a table, the table stretches across the modal width.
+  - If a modal is split into sections, use large tabs instead of a regular modal header.
+
+spacing_rules:
+  - Left, right, and bottom margins are 32px.
+  - Top margin is 24px.
+
+recommended_components:
+  - name: UiModalWindow
+    profile: ../components/UiModalWindow.yml
+  - name: UiButton
+    profile: ../components/UiButton.yml
+  - name: UiTabGroup
+    profile: ../components/UiTabGroup.yml
+  - name: UiTab
+    profile: ../components/UiTab.yml
+  - name: UiTable
+    profile: ../components/UiTable.yml
+  - name: UiTableColumn
+    profile: ../components/UiTableColumn.yml
+  - name: UiTableFooterSection
+    profile: ../components/UiTableFooterSection.yml
+
+ai_notes:
+  do:
+    - Use for workflows that need width, table content, or several sections.
+    - Use large tabs when modal content is split into sections.
+  avoid:
+    - Do not use a sidebar when content needs wide tables or complex controls.

package/docs/profiles/pages/MultiColumnPage.yml

@@ -0,0 +1,27 @@
+page_profile: MultiColumnPage
+summary: >
+  Detail-page pattern for entity cards with several semantic blocks that should be visible in parallel.
+
+use_when:
+  - You need an entity detail page with multiple related blocks.
+  - You need order, customer, or product information visible in parallel.
+
+examples_from_design:
+  - order page
+  - customer page
+  - product view page
+
+layout_rules:
+  - Content is placed on surfaces.
+  - The most common surface spans the full screen width.
+  - Semantic blocks can be arranged vertically and horizontally.
+  - Distance between blocks is 24px.
+  - Allowed width distributions are 100%, 50% / 50%, and 30% / 70%.
+
+ai_notes:
+  do:
+    - Keep hierarchy operational and dense.
+    - Use parallel blocks only when users need to compare or scan them together.
+  avoid:
+    - Do not use marketing-style layouts.
+    - Do not split content into columns when a single linear form is easier to complete.

package/docs/profiles/pages/PageComposition.yml

@@ -0,0 +1,56 @@
+page_profile: PageComposition
+summary: >
+  Shared page-composition rules for RetailCRM extension screens built with
+  @retailcrm/embed-ui-v1-components.
+
+use_after:
+  - ../../README.md
+  - ../../../AGENTS.md
+  - ../../AI.md
+  - ../components
+
+scope:
+  - Page-composition guidance for full pages, modals, sidebars, filters, tables, and settings layouts.
+  - Complements component API profiles instead of replacing them.
+
+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.
+  - 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.
+  - Content blocks commonly use 32px left, right, and bottom padding and 24px top padding.
+  - Prefer public components from @retailcrm/embed-ui-v1-components/remote.
+  - Do not invent custom chrome for pages, forms, tables, tabs, buttons, modals, or sidebars when a documented component fits.
+
+decision_guide:
+  - need: Searchable, filterable registry.
+    use: EntityListPage
+    profile: ./EntityListPage.yml
+  - need: Entity editing or settings form.
+    use: CardSettingsPage
+    profile: ./CardSettingsPage.yml
+  - need: Several semantic blocks visible together.
+    use: MultiColumnPage
+    profile: ./MultiColumnPage.yml
+  - need: Grouped settings with independent sections.
+    use: CollapseBlockPage
+    profile: ./CollapseBlockPage.yml
+  - need: Small contextual form or compact entity card.
+    use: ModalSidebar
+    profile: ./ModalSidebar.yml
+  - need: Large local workflow, auxiliary table, or dense settings flow.
+    use: ModalWindow
+    profile: ./ModalWindow.yml
+
+ai_notes:
+  do:
+    - 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.
+  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.

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.19",
+  "version": "0.9.22-alpha.1",
   "license": "MIT",
   "author": "RetailDriverLLC <integration@retailcrm.ru>",
   "repository": "git@github.com:retailcrm/embed-ui.git",
@@ -67,20 +67,20 @@
     "@retailcrm/image-preview": "^1.0.2",
     "date-fns": "^4.1.0",
     "lodash.isequal": "^4.5.0",
-    "vue3-perfect-scrollbar": "^1.6.0"
+    "vue3-perfect-scrollbar": "^2.0.0"
   },
   "devDependencies": {
-    "@storybook/addon-a11y": "^10.1.11",
-    "@storybook/addon-docs": "^10.1.11",
-    "@storybook/addon-links": "^10.1.11",
-    "@storybook/addon-themes": "^10.1.11",
-    "@storybook/builder-vite": "^10.1.11",
-    "@storybook/vue3": "^10.1.11",
-    "@storybook/vue3-vite": "^10.1.11",
+    "@storybook/addon-a11y": "^10.3.5",
+    "@storybook/addon-docs": "^10.3.5",
+    "@storybook/addon-links": "^10.3.5",
+    "@storybook/addon-themes": "^10.3.5",
+    "@storybook/builder-vite": "^10.3.5",
+    "@storybook/vue3": "^10.3.5",
+    "@storybook/vue3-vite": "^10.3.5",
     "@types/lodash.isequal": "^4.5.8",
     "@vitejs/plugin-vue": "^6.0.2",
-    "@vitest/browser": "4.0.15",
-    "@vitest/browser-playwright": "4.0.15",
+    "@vitest/browser": "4.1.3",
+    "@vitest/browser-playwright": "4.1.3",
     "@vue/compiler-sfc": "^3.5.25",
     "@vue/test-utils": "^2.4.6",
     "@yandex/ymaps3-types": "^1.0.19072130",
@@ -90,15 +90,15 @@
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "remark-gfm": "^4.0.0",
-    "storybook": "^10.1.11",
+    "storybook": "^10.3.5",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "uuid": "^13.0.0",
-    "vite": "^7.2.7",
+    "vite": "^7.3.2",
     "vite-plugin-dts": "^4.5.4",
     "vite-svg-loader": "^5.1.0",
-    "vitest": "^4.0.15",
-    "vue": "^3.5.25",
+    "vitest": "^4.1.3",
+    "vue": "^3.5.32",
     "vue-i18n": "10.0.8"
   }
 }

package/docs/profiles/UiAddButton.yml

@@ -1,57 +0,0 @@
-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
-
-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.
-  avoid:
-    - Do not replace a plain UiButton unless the add semantics are intentional.

package/docs/profiles/UiAlert.yml

@@ -1,48 +0,0 @@
-component: UiAlert
-summary: >
-  UiAlert is a compact contextual message block for status, warning, success, and danger feedback.
-  It can be shown inline in normal page flow and can be closable.
-
-public_import:
-  from: '@retailcrm/embed-ui-v1-components/remote'
-  named:
-    - UiAlert
-
-use_when:
-  - You need inline status feedback.
-  - You need dismissible page-level or section-level notice content.
-
-avoid_when:
-  - You need a blocking modal message.
-  - You need a tiny field-level validation hint.
-
-api:
-  key_props:
-    - name: variant
-    - name: text
-    - name: shown
-    - name: closable
-    - name: fluid
-
-rendered_structure:
-  descriptive_only: true
-  root:
-    shape: div.ui-v1-alert
-    tag: div
-  notes: Current alert body is wrapped in UiTransition and uses one flex row for icon, content, and optional closer.
-
-geometry:
-  layout: block-like feedback row
-  root_display: flex
-  width_behavior: stretches to container width by default
-
-behavior:
-  notes:
-    - shown controls visibility.
-    - closable enables user dismissal.
-
-ai_notes:
-  do:
-    - Use UiAlert for inline feedback that should stay in normal layout flow.
-  avoid:
-    - Do not use it as a replacement for modal confirmation.

package/docs/profiles/UiAvatar.yml

@@ -1,48 +0,0 @@
-component: UiAvatar
-summary: >
-  UiAvatar renders a user or entity avatar with optional name, status, and link semantics.
-  It is meant for compact identity display rather than generic image rendering.
-
-public_import:
-  from: '@retailcrm/embed-ui-v1-components/remote'
-  named:
-    - UiAvatar
-
-use_when:
-  - You need a compact identity marker for a user or contact.
-  - You need avatar display with optional status.
-
-avoid_when:
-  - You need a generic content image.
-  - You need a large media block.
-
-api:
-  key_props:
-    - name: src
-    - name: name
-    - name: status
-    - name: size
-    - name: href
-
-rendered_structure:
-  descriptive_only: true
-  root:
-    shape: div.ui-v1-avatar or a.ui-v1-avatar
-    tag: div or a
-  notes: The root switches to anchor when href is provided.
-
-geometry:
-  layout: avatar frame
-  root_display: inline-block
-  width_behavior: content-sized by size
-
-behavior:
-  notes:
-    - Can render linked avatar behavior when href is provided.
-    - Name is useful as fallback identity information.
-
-ai_notes:
-  do:
-    - Use UiAvatar for identity display, not for general media.
-  avoid:
-    - Do not use it where UiImage is the better semantic fit.

package/docs/profiles/UiCalendar.yml

@@ -1,48 +0,0 @@
-component: UiCalendar
-summary: >
-  UiCalendar is the date selection primitive behind date and date-range flows. It supports
-  single and range selection, multiple visual appearances, and locale-sensitive behavior.
-
-public_import:
-  from: '@retailcrm/embed-ui-v1-components/remote'
-  named:
-    - UiCalendar
-
-use_when:
-  - You need inline date selection.
-  - You need single-date or date-range picking without a textbox wrapper.
-
-avoid_when:
-  - You need the full textbox-plus-popper date picker flow.
-
-api:
-  key_props:
-    - name: value
-    - name: type
-    - name: appearance
-    - name: minDate
-    - name: maxDate
-    - name: locale
-
-rendered_structure:
-  descriptive_only: true
-  root:
-    shape: div.ui-v1-calendar
-    tag: div
-  notes: The root contains header controls, weekday labels, and the date grid.
-
-geometry:
-  layout: block-like calendar panel
-  root_display: flex
-  width_behavior: stretches to container width by default
-
-behavior:
-  notes:
-    - Supports single and range selection.
-    - minDate and maxDate constrain selection.
-
-ai_notes:
-  do:
-    - Use UiCalendar when inline calendar selection is the actual UI.
-  avoid:
-    - Use UiDatePicker instead if users expect textbox plus popup behavior.

package/docs/profiles/UiCheckbox.yml

@@ -1,53 +0,0 @@
-component: UiCheckbox
-summary: >
-  UiCheckbox is a boolean or set-membership control. It supports single boolean-like usage
-  as well as model-plus-value patterns for checkbox groups.
-
-public_import:
-  from: '@retailcrm/embed-ui-v1-components/remote'
-  named:
-    - UiCheckbox
-
-use_when:
-  - You need a yes or no control.
-  - You need one value inside a checkbox group model.
-
-avoid_when:
-  - You need exclusive single choice, use UiRadio instead.
-  - You need a more compact toggle-like control, use UiSwitch instead.
-
-api:
-  key_props:
-    - name: model
-    - name: value
-    - name: indeterminate
-    - name: valueOfTruthy
-    - name: valueOfFalsy
-    - name: disabled
-  methods:
-    - name: click
-    - name: focus
-    - name: blur
-
-rendered_structure:
-  descriptive_only: true
-  root:
-    shape: span.ui-v1-checkbox
-    tag: span
-  notes: One inline wrapper around the visual checkbox control and label content.
-
-geometry:
-  layout: inline checkbox control
-  root_display: inline-flex
-  width_behavior: content-sized by default
-
-behavior:
-  notes:
-    - model plus value supports group-style selection.
-    - indeterminate is useful for partial selection states.
-
-ai_notes:
-  do:
-    - Use for boolean choice or checkbox-group membership.
-  avoid:
-    - Do not use for mutually exclusive options.

package/docs/profiles/UiCollapse.yml

@@ -1,40 +0,0 @@
-component: UiCollapse
-summary: >
-  UiCollapse is a low-level show and hide container for expandable content. It controls
-  whether content is hidden or disposed and how the transition behaves.
-
-public_import:
-  from: '@retailcrm/embed-ui-v1-components/remote'
-  named:
-    - UiCollapse
-
-use_when:
-  - You need conditional expandable content.
-  - You need to choose between hidden and disposed collapsed states.
-
-avoid_when:
-  - You need a ready-to-use disclosure box with header UI, use UiCollapseBox instead.
-
-api:
-  key_props:
-    - name: expanded
-    - name: collapseBehaviour
-    - name: duration
-
-rendered_structure:
-  descriptive_only: true
-  root:
-    shape: div.ui-v1-collapse
-    tag: div
-  notes: The animated container is wrapped in a native transition and exists only while shown or expanded.
-
-geometry:
-  layout: block-like animated container
-  root_display: block
-  width_behavior: stretches to container width by default
-
-ai_notes:
-  do:
-    - Use UiCollapse as a primitive for expandable content regions.
-  avoid:
-    - Do not use it when a full disclosure component is the actual need.