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

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

@@ -3,7 +3,6 @@ summary: >
   UiField is a remote-only form field wrapper. It connects a label and an inner control through
   id and ARIA data, supports a hint tooltip near the label, and exposes an addon zone on the
   right side of the headline.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uifield--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -16,6 +15,52 @@ related_components:
   - UiCheckbox
   - UiDatePicker
 
+examples:
+  - title: Basic usage
+    code: |
+      <template>
+          <UiField id="name-field" label="Name" hint="At least 3 characters">
+              <template #default="field">
+                  <UiTextbox
+                      :id="field.id"
+                      :input-attributes="{
+                          'aria-labelledby': field.ariaLabelledby,
+                          'aria-invalid': field.ariaInvalid,
+                      }"
+                  />
+              </template>
+          </UiField>
+      </template>
+
+      <script lang="ts" setup>
+      import {
+        UiField,
+        UiTextbox,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Addon next to label
+    code: |
+      <template>
+          <UiField id="name-field" label="Name">
+              <template #addon>
+                  Up to 32 characters
+              </template>
+
+              <template #default="field">
+                  <UiTextbox
+                      :id="field.id"
+                      :input-attributes="{
+                          'aria-labelledby': field.ariaLabelledby,
+                          'aria-invalid': field.ariaInvalid,
+                      }"
+                  />
+              </template>
+          </UiField>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiField, UiTextbox } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
 use_when:
   - You need a labeled form control with consistent field semantics.
   - You need to pass id, aria-labelledby, and aria-invalid into an inner control.

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

@@ -2,13 +2,66 @@ component: UiInfobox
 summary: >
   UiInfobox is a richer explanatory block for inline product, warning, or helper content.
   It can be closable and expandable.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiinfobox--docs
 
 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.
@@ -73,6 +126,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-infobox

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

@@ -2,13 +2,34 @@ 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.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uilink--docs
 
 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.
@@ -86,6 +107,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-link

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

@@ -1,7 +1,6 @@
 component: UiLoader
 summary: >
   UiLoader displays loading progress or waiting state. It can be used inline or as an overlay.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiskeleton--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -68,6 +67,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-loader

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

@@ -2,7 +2,6 @@ component: UiMenuItem
 summary: >
   UiMenuItem is a structured menu row component with support for icons, avatar, description,
   counters, and active or danger styling.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/uimenuitem--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -90,6 +89,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-menu-item

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

@@ -2,7 +2,6 @@ component: UiMenuItemGroup
 summary: >
   UiMenuItemGroup groups related menu items and exposes dedicated zones for group label
   and quantity metadata.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/uimenuitem--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -72,6 +71,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-menu-item-group

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

@@ -2,13 +2,92 @@ 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.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uimodalsidebar--docs
 
 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.
@@ -73,6 +152,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-modal-sidebar-overlay

package/docs/profiles/components/UiModalWindow.yml

@@ -0,0 +1,181 @@
+component: UiModalWindow
+summary: >
+  UiModalWindow is the main centered modal container. It supports open state, closability,
+  appearance variants, fullscreen and responsive behavior, and dialog roles.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiModalWindow
+
+related_components:
+  - UiModalWindowSurface
+
+examples:
+  - title: Example
+    code: |
+      <template>
+          <div>
+              <UiButton appearance="secondary" @click="open = true">
+                  {{ buttonTitle }}
+              </UiButton>
+
+              <UiModalWindow v-model:opened="open" v-bind="$attrs">
+                  <template #title>
+                      Title
+                  </template>
+
+                  <div :style="$attrs.appearance == 'popup' ? { height: '1500px' } : {}">
+                      <div>Some content</div>
+
+                      <div v-if="hasNesting" style="margin-top: 16px">
+                          <UiButton appearance="secondary" @click="openNesting = true">
+                              Open nested window
+                          </UiButton>
+
+                          <UiModalWindow
+                              v-if="!nestedOnSameLevel"
+                              v-model:opened="openNesting"
+                              responsive
+                          >
+                              <template #title>
+                                  Nested window
+                              </template>
+
+                              <p>Some content</p>
+
+                              <template #footer>
+                                  <UiButton appearance="secondary" @click="openNesting = false">
+                                      Close
+                                  </UiButton>
+                              </template>
+                          </UiModalWindow>
+                      </div>
+                  </div>
+
+                  <template #footer>
+                      <UiButton appearance="secondary" @click="open = false">
+                          Close
+                      </UiButton>
+                  </template>
+              </UiModalWindow>
+
+              <UiModalWindow
+                  v-if="nestedOnSameLevel"
+                  v-model:opened="openNesting"
+                  v-bind="$attrs"
+                  responsive
+              >
+                  <template #title>
+                      Nested same-level window
+                  </template>
+
+                  <p>Some content</p>
+
+                  <template #footer>
+                      <UiButton appearance="secondary" @click="openNesting = false">
+                          Close
+                      </UiButton>
+                  </template>
+              </UiModalWindow>
+          </div>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+
+      import { UiButton } from '@retailcrm/embed-ui-v1-components/remote'
+      import { UiModalWindow } from '@retailcrm/embed-ui-v1-components/remote'
+
+      defineProps({
+        buttonTitle: {
+          type: String,
+          default: '',
+        },
+
+        hasNesting: {
+          type: Boolean,
+          default: false,
+        },
+
+        nestedOnSameLevel: {
+          type: Boolean,
+          default: false,
+        },
+      })
+
+      const open = ref(false)
+      const openNesting = ref(false)
+      </script>
+
+use_when:
+  - You need a centered dialog.
+  - You need modal interaction with standard dialog semantics.
+
+avoid_when:
+  - You need a side-docked modal, use UiModalSidebar instead.
+
+api:
+  key_props:
+    - name: opened
+    - name: closable
+    - name: appearance
+    - name: fullscreen
+    - name: responsive
+    - name: scrolling
+    - name: role
+  methods:
+    - name: open
+    - name: close
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-modal-window via UiModalWindowSurface
+    tag: div
+  notes: The component delegates the actual teleported modal root to UiModalWindowSurface and renders header, content, and footer inside it.
+
+geometry:
+  layout: teleported modal layer with centered surface
+  root_display: flex
+  width_behavior: viewport-covering overlay with content-sized or responsive surface
+
+behavior:
+  notes:
+    - opened controls modal visibility.
+    - closable should be false only when the user must complete or acknowledge a blocking flow.
+    - fullscreen and responsive affect surface sizing rather than modal semantics.
+
+composition:
+  works_well_with:
+    - UiButton
+    - UiField
+    - UiModalWindowSurface
+  patterns:
+    - title: Confirmation dialog
+      notes: Keep copy concise and put primary and secondary actions in the footer.
+    - title: Focused form
+      notes: Use for short forms that should not navigate away from the current page.
+
+ai_notes:
+  do:
+    - Use for focused blocking tasks and confirmations.
+    - Provide clear title, body, and footer actions when the modal asks the user to decide.
+  avoid:
+    - Do not use as a general page layout or for long workflows that deserve a full page or sidebar.
+
+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-window

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

@@ -2,7 +2,6 @@ component: UiModalWindowSurface
 summary: >
   UiModalWindowSurface is the lower-level modal surface API behind modal window flows.
   Use it when you need modal surface behavior with more explicit composition control.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uimodalwindow--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -68,6 +67,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-modal-window

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

@@ -2,7 +2,6 @@ component: UiNumberStepper
 summary: >
   UiNumberStepper is a numeric input with increase and decrease controls. It is built for
   constrained numeric entry where arrowing and step-based changes matter.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uinumberstepper--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -12,6 +11,20 @@ public_import:
 related_components:
   - UiTextbox
 
+examples:
+  - title: Example
+    code: |
+      <template>
+        <UiNumberStepper v-model:value="value" :min="0" :max="100" />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiNumberStepper } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<number | null>(10)
+      </script>
+
 use_when:
   - You need numeric input with explicit step controls.
   - You need range constraints and nullable numeric state.
@@ -83,6 +96,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-number-stepper

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

@@ -3,7 +3,6 @@ summary: >
   UiPageHeader is a page or major section header with an optional inline addon next to the title
   and an optional actions area on the right. In display state it renders the title as a semantic h1;
   in edit state it switches to UiTextbox.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uipageheader--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -17,6 +16,45 @@ related_components:
   - UiPopperConnector
   - UiPopperTarget
 
+examples:
+  - title: Example
+    code: |
+      <template>
+          <UiPageHeader
+              v-model:value="title"
+              :error="title ? '' : 'Title is required'"
+              :invalid="!title"
+              editable
+              placeholder="Enter a title"
+          >
+              <template #addon>
+                  <UiLink>
+                      Collapse filter
+                  </UiLink>
+              </template>
+
+              <template #actions>
+                  <UiButton appearance="tertiary">
+                      Actions
+                      <IconCaretDown aria-hidden="true" />
+                  </UiButton>
+              </template>
+          </UiPageHeader>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+
+      import IconCaretDown from '@retailcrm/embed-ui-v1-components/assets/sprites/arrows/caret-down.svg'
+      import {
+        UiButton,
+        UiLink,
+        UiPageHeader,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const title = ref('Returns')
+      </script>
+
 use_when:
   - You need the main title of an extension page.
   - You need inline title editing.