@retailcrm/embed-ui-v1-components 0.9.21 → 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.21",
+  "version": "0.9.22-alpha.1",
   "license": "MIT",
   "author": "RetailDriverLLC <integration@retailcrm.ru>",
   "repository": "git@github.com:retailcrm/embed-ui.git",