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

package/docs/profiles/components/UiInfobox.yml

@@ -0,0 +1,130 @@
+component: UiInfobox
+summary: >
+  UiInfobox is a richer explanatory block for inline product, warning, or helper content.
+  It can be closable and expandable.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiInfobox
+
+examples:
+  - title: Example
+    code: |
+      <template>
+        <UiInfobox title="Important information">
+          Content
+        </UiInfobox>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiInfobox } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Warning
+    code: |
+      <template>
+        <UiInfobox warning title="Warning">
+          Content
+        </UiInfobox>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiInfobox } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Expandable
+    code: |
+      <template>
+        <UiInfobox
+          v-model:expanded="expanded"
+          expandable
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiInfobox } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const expanded = ref(false)
+      </script>
+  - title: Closable
+    code: |
+      <template>
+        <UiInfobox
+          v-model:shown="shown"
+          closable
+        />
+
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiInfobox } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const shown = ref(true)
+      </script>
+use_when:
+  - You need a highlighted explanatory block.
+  - You need closable or expandable helper content.
+
+avoid_when:
+  - You need a one-line alert only.
+
+api:
+  key_props:
+    - name: title
+    - name: shown
+    - name: expanded
+    - name: expandable
+    - name: closable
+    - name: warning
+  methods:
+    - name: show
+    - name: hide
+    - name: toggle
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-infobox
+    tag: div
+  notes: The visible infobox body is wrapped in UiTransition and uses one flex row for media, content, and optional closer.
+
+geometry:
+  layout: block-like message panel
+  root_display: flex
+  width_behavior: stretches to container width by default
+
+ai_notes:
+  do:
+    - Use UiInfobox for richer guidance blocks, not tiny alerts.
+    - Use expandable when secondary explanation would otherwise make the screen noisy.
+  avoid:
+    - Do not use for transient success or error states; use UiAlert.
+
+behavior:
+  notes:
+    - shown controls visibility.
+    - expandable and expanded control progressive disclosure.
+    - warning changes the visual tone for cautionary guidance.
+
+composition:
+  works_well_with:
+    - UiAlert
+    - UiCollapse
+  patterns:
+    - title: Product guidance
+      notes: Use near the related form or table, not as a decorative card.
+    - title: Long explanation
+      notes: Prefer expandable content when the text is useful but not always needed.
+
+accessibility:
+  notes:
+    - Keep rendered text concise and meaningful for screen-reader users.
+    - Do not use this component as the only carrier of critical state if the state also needs form-level validation or focus management.
+
+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-infobox

package/docs/profiles/components/UiLink.yml

@@ -0,0 +1,111 @@
+component: UiLink
+summary: >
+  UiLink is the main text-link component for inline navigation and inline actions that should
+  still read as links rather than buttons.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiLink
+
+examples:
+  - title: Example
+    code: |
+      <template>
+          <UiLink v-bind="$attrs">
+              <template v-if="text.length">
+                  {{ text }}
+              </template>
+          </UiLink>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiLink } from '@retailcrm/embed-ui-v1-components/remote'
+
+      defineProps({
+        text: {
+          type: String,
+          default: '',
+        },
+      })
+      </script>
+
+use_when:
+  - You need inline navigation or linked text.
+  - You need a compact action that should still read as a link.
+
+avoid_when:
+  - You need button semantics, use UiButton instead.
+
+api:
+  key_props:
+    - name: href
+    - name: external
+    - name: appearance
+    - name: size
+      notes: Defaults to body text. Use size="small" inside UiTable cells to match table body typography.
+    - name: accent
+    - name: ellipsis
+  slots:
+    - name: icon
+      zone: inline-icon
+      creates: Optional icon zone inside the link.
+  emits:
+    - name: click
+    - name: focus
+    - name: blur
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: a.ui-v1-link
+    tag: a
+  notes: The root is one anchor element with inline icon and text zones.
+
+geometry:
+  layout: inline link root
+  root_display: inline-flex
+  width_behavior: content-sized by default
+
+composition:
+  works_well_with:
+    - UiTable
+    - UiToolbarLink
+    - UiButton
+  patterns:
+    - title: Table primary link
+      notes: Use size="small", accent, and ellipsis for the primary object link in a table cell.
+    - title: External link
+      notes: Use external when the link opens outside the current extension context.
+    - title: Button-shaped navigation
+      notes: Use UiButton with href when the navigation should visually read as a command button.
+
+ai_notes:
+  do:
+    - Use UiLink for real link semantics and inline navigation.
+    - Use size="small" for links inside UiTable body cells.
+    - Use ellipsis when a table-cell link can contain long names.
+  avoid:
+    - Do not use UiLink where the action should read as a button.
+    - Do not leave table-cell links at the default body size unless the link is intentionally emphasized.
+
+behavior:
+  notes:
+    - Read key_props first to identify supported states and variants.
+    - Prefer controlled props and documented emits when synchronizing component state with screen logic.
+
+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-link

package/docs/profiles/components/UiLoader.yml

@@ -0,0 +1,71 @@
+component: UiLoader
+summary: >
+  UiLoader displays loading progress or waiting state. It can be used inline or as an overlay.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiLoader
+
+use_when:
+  - You need a visible loading indicator.
+  - You need inline or overlay loading state.
+
+avoid_when:
+  - You need skeleton content rather than a spinner-like loader.
+
+api:
+  key_props:
+    - name: diameter
+    - name: thickness
+    - name: fixed
+    - name: overlay
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-loader
+    tag: div
+  notes: The loader body may be wrapped in UiTransition, but the visible loader itself is one div root.
+
+geometry:
+  layout: loader surface or overlay
+  root_display: block
+  width_behavior: content-sized by default, viewport-covering in fixed or overlay modes
+
+ai_notes:
+  do:
+    - Use overlay=true when the loader should dim the covered page or module content.
+    - Use overlay or fixed only when the loader should escape normal inline flow.
+    - Preserve surrounding filters and headers when only the content area is loading.
+  avoid:
+    - Do not create custom dimming markup around UiLoader; use the overlay prop.
+    - Do not replace content-shaped loading with a page-wide loader when UiSkeleton would communicate layout better.
+
+behavior:
+  notes:
+    - overlay=true adds the dimmed backdrop for covered content.
+    - fixed and overlay change the loader from inline feedback into a surface-covering state.
+    - diameter and thickness tune the visual weight of the indicator.
+
+composition:
+  works_well_with:
+    - UiSkeleton
+    - UiAlert
+  patterns:
+    - title: Table loading
+      notes: Keep filters visible and show loading in the table area.
+    - title: Blocking operation
+      notes: Use overlay only when interaction with the covered content must be blocked.
+
+accessibility:
+  notes:
+    - Keep rendered text concise and meaningful for screen-reader users.
+    - Do not use this component as the only carrier of critical state if the state also needs form-level validation or focus management.
+
+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-loader

package/docs/profiles/components/UiMenuItem.yml

@@ -0,0 +1,93 @@
+component: UiMenuItem
+summary: >
+  UiMenuItem is a structured menu row component with support for icons, avatar, description,
+  counters, and active or danger styling.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiMenuItem
+
+use_when:
+  - You need a menu row with structured content zones.
+  - You need icon, avatar, description, or counter inside one menu item.
+
+avoid_when:
+  - You need a plain inline link.
+
+api:
+  key_props:
+    - name: description
+    - name: counter
+    - name: active
+    - name: danger
+    - name: disabled
+    - name: size
+  slots:
+    - name: default
+      zone: main-label
+      creates: Main visible label area.
+    - name: avatar
+      zone: leading-avatar
+      creates: Leading avatar zone.
+    - name: leading-icon
+      zone: leading-icon
+      creates: Leading icon zone.
+    - name: description
+      zone: secondary-copy
+      creates: Secondary description area.
+    - name: trailing-icon
+      zone: trailing-icon
+      creates: Trailing icon zone.
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-menu-item
+    tag: div
+  notes: The root is one menu row container with leading, main, and trailing content zones.
+
+geometry:
+  layout: menu row
+  root_display: flex
+  width_behavior: stretches to available menu width
+
+ai_notes:
+  do:
+    - Use structured slots instead of custom wrappers inside menu rows.
+    - Use danger only for destructive menu actions.
+  avoid:
+    - Do not use as a generic card or list row outside menu-like surfaces.
+
+behavior:
+  notes:
+    - active marks the current or selected item.
+    - disabled prevents interaction.
+    - danger changes semantic tone for destructive actions.
+
+composition:
+  works_well_with:
+    - UiMenuItemGroup
+    - UiAvatar
+    - UiTag
+  patterns:
+    - title: Command menu row
+      notes: Use leading-icon for action identity and trailing-icon for disclosure or shortcut-like hints.
+    - title: Entity menu row
+      notes: Use avatar and description slots for users, customers, or entities.
+
+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-menu-item

package/docs/profiles/{UiMenuItemGroup.yml → components/UiMenuItemGroup.yml}

@@ -48,3 +48,28 @@ geometry:
 ai_notes:
   do:
     - Use for grouped menu structure instead of manual heading-plus-list markup.
+  avoid:
+    - Do not group unrelated actions only for visual spacing.
+
+behavior:
+  notes:
+    - The group organizes nested menu rows but does not manage selection by itself.
+
+composition:
+  works_well_with:
+    - UiMenuItem
+  patterns:
+    - title: Grouped options
+      notes: Use label and quantity slots to clarify large option groups.
+
+accessibility:
+  notes:
+    - Keep visible labels and slot content meaningful.
+    - Prefer documented props and slots over custom DOM replacements so host-side accessibility behavior is preserved.
+
+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-menu-item-group

package/docs/profiles/components/UiModalSidebar.yml

@@ -0,0 +1,156 @@
+component: UiModalSidebar
+summary: >
+  UiModalSidebar is a side-docked modal surface with open state, direction, size, and
+  scrolling control. Use it when the UI should slide from an edge instead of opening as a centered dialog.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiModalSidebar
+
+examples:
+  - title: Example
+    code: |
+      <template>
+          <div>
+              <UiButton @click="open = true">
+                  {{ buttonTitle }}
+              </UiButton>
+
+              <UiModalSidebar v-model:opened="open" v-bind="$attrs">
+                  <template #title>
+                      Title
+                  </template>
+
+                  <div style="height: 1500px;">
+                      <div>Content with a height of 1500px</div>
+
+                      <div v-if="hasNesting" style="margin-top: 16px">
+                          <UiButton @click="modalSidebarInner = true">
+                              Nested sidebar
+                          </UiButton>
+
+                          <UiModalSidebar
+                              v-model:opened="modalSidebarInner"
+                              @close-sidebar="modalSidebarInner = false"
+                          >
+                              <template #title>
+                                  Header
+                              </template>
+
+                              <div style="height: 1500px;">
+                                  <div>Some content</div>
+                                  <div>Nested sidebar</div>
+                              </div>
+
+                              <template #footer>
+                                  <UiButton @click="modalSidebarInner = false">
+                                      Close
+                                  </UiButton>
+                              </template>
+                          </UiModalSidebar>
+                      </div>
+                  </div>
+
+                  <template v-if="footer" #footer>
+                      <UiButton @click="open = false">
+                          Close
+                      </UiButton>
+                  </template>
+              </UiModalSidebar>
+          </div>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+
+      import { UiButton } from '@retailcrm/embed-ui-v1-components/remote'
+      import { UiModalSidebar } from '@retailcrm/embed-ui-v1-components/remote'
+
+      defineProps({
+        buttonTitle: {
+          type: String,
+          default: '',
+        },
+
+        hasNesting: {
+          type: Boolean,
+          default: false,
+        },
+
+        footer: {
+          type: Boolean,
+          default: false,
+        },
+      })
+
+      const open = ref(false)
+      const modalSidebarInner = ref(false)
+      </script>
+
+use_when:
+  - You need side-panel modal UI.
+  - You need left or right docked modal content.
+
+avoid_when:
+  - You need a centered dialog.
+
+api:
+  key_props:
+    - name: opened
+    - name: closable
+    - name: direction
+    - name: size
+    - name: scrolling
+    - name: fixed
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-modal-sidebar-overlay
+    tag: div
+  notes: The component is teleported; the overlay div contains the actual aside.ui-v1-modal-sidebar panel.
+
+geometry:
+  layout: teleported overlay with side panel
+  root_display: flex
+  width_behavior: viewport-covering overlay with fixed-width sidebar surface
+
+behavior:
+  notes:
+    - opened controls visibility.
+    - direction controls which side the sidebar comes from.
+
+ai_notes:
+  do:
+    - Use UiModalSidebar when page context should stay visually connected to the modal content.
+    - Use for inspect, edit, or secondary workflows that relate to the current list or page.
+  avoid:
+    - Do not use for short confirmations; use UiModalWindow.
+
+composition:
+  works_well_with:
+    - UiTable
+    - UiField
+    - UiButton
+  patterns:
+    - title: Row detail side panel
+      notes: Open from a table row when the user should keep list context visible.
+    - title: Side edit form
+      notes: Put primary actions in the sidebar footer when the form edits the selected object.
+
+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-modal-sidebar-overlay