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

package/docs/profiles/components/UiPopconfirm.yml

@@ -0,0 +1,164 @@
+component: UiPopconfirm
+summary: >
+  UiPopconfirm is a non-modal floating confirmation dialog anchored to a trigger.
+  Use it for short action confirmations where a modal would be too heavy.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiPopconfirm
+
+related_components:
+  - UiButton
+  - UiPopper
+  - UiModalWindow
+
+examples:
+  - title: Basic confirmation
+    code: |
+      <template>
+        <UiPopconfirm title="Confirm action?">
+          <template #trigger="{ open }">
+            <UiButton :active="open">
+              Archive
+            </UiButton>
+          </template>
+
+          The item will be moved to the archive.
+        </UiPopconfirm>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiButton, UiPopconfirm } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Destructive action
+    code: |
+      <template>
+        <UiPopconfirm title="Delete item?" ok-variant="danger">
+          <template #trigger="{ open }">
+            <UiButton :active="open" variant="danger">
+              Delete
+            </UiButton>
+          </template>
+
+          This action cannot be undone.
+        </UiPopconfirm>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiButton, UiPopconfirm } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
+use_when:
+  - You need a short confirmation for a single nearby action.
+  - You need confirm and cancel events without blocking the whole page.
+  - You need a destructive confirmation through okVariant="danger".
+
+avoid_when:
+  - You need a form, long explanation, or multi-step confirmation.
+  - You need to block page interaction; use UiModalWindow instead.
+  - You only need helper text; use UiTooltip instead.
+
+api:
+  key_props:
+    - name: title
+      notes: Text title shown above the description.
+    - name: okVariant
+      notes: Confirmation button variant; use danger for destructive actions.
+    - name: placement
+      notes: Preferred floating position relative to the trigger.
+    - name: visible
+      notes: Controlled open state for v-model:visible.
+  props:
+    - name: okTitle
+      notes: Confirmation button text.
+    - name: cancelTitle
+      notes: Cancel button text.
+    - name: cancelAppearance
+      notes: Cancel button appearance.
+    - name: cancelVariant
+      notes: Cancel button variant.
+    - name: buttonSize
+      notes: Size of both action buttons.
+    - name: popperClass
+      notes: Extra class for the floating popper root.
+    - name: popperOptions
+      notes: Additional UiPopper options.
+  slots:
+    - name: trigger
+      zone: trigger
+      creates: Target element that opens the confirmation.
+      notes: Receives open for active trigger styling when supported.
+    - name: title
+      zone: header
+      creates: Custom title content.
+    - name: default
+      zone: body
+      creates: Confirmation description.
+    - name: cancel-text
+      zone: footer
+      creates: Cancel button content.
+    - name: ok-text
+      zone: footer
+      creates: Confirmation button content.
+  emits:
+    - name: ok
+      payload: undefined
+      notes: Fired when the confirmation button is clicked.
+    - name: cancel
+      payload: undefined
+      notes: Fired when the cancel button is clicked or the popup closes by outside click.
+    - name: toggle
+      payload: boolean
+      notes: Fired when open state changes.
+    - name: update:visible
+      payload: boolean
+      notes: v-model:visible update channel.
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-popper.ui-v1-popconfirm via UiPopper
+    tag: div
+  zones:
+    - .ui-v1-popconfirm__title
+    - .ui-v1-popconfirm__content
+    - .ui-v1-popconfirm__footer
+
+geometry:
+  layout: floating dialog outside normal document flow
+  root_display: block
+  width_behavior: content-sized with max width
+  notes:
+    - Defaults to bottom-start placement.
+    - The layer is anchored to the component trigger wrapper.
+
+ai_notes:
+  do:
+    - Use UiPopconfirm for short confirmations instead of building UiPopper and UiButton manually.
+    - Pass open from the trigger slot into UiButton active when possible.
+    - Use okVariant="danger" for destructive actions.
+  avoid:
+    - Do not put forms or complex flows into UiPopconfirm.
+    - Do not use it as a tooltip or notification.
+
+accessibility:
+  notes:
+    - Renders a non-modal dialog with aria-modal="false".
+    - Title content is connected through aria-labelledby when present.
+    - Use an accessible trigger component such as UiButton.
+
+styling:
+  notes:
+    - Use props and slots first; use popperClass only for local layout integrations.
+    - CSS variables can tune the floating surface width.
+  root_classes:
+    - .ui-v1-popconfirm
+  zones:
+    - .ui-v1-popconfirm__title
+    - .ui-v1-popconfirm__content
+    - .ui-v1-popconfirm__footer
+  css_variables:
+    public_theme_variables:
+      - name: --ui-v1-popconfirm-width-max
+        effect: Maximum width of the floating confirmation.

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

@@ -3,7 +3,6 @@ summary: >
   UiPopper is the low-level floating layer used for tooltips, dropdowns, and popups.
   It controls visibility, teleport container, positioning, and trigger logic, but is usually
   consumed as part of a higher-level component rather than as a standalone content wrapper.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uipopper--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -13,9 +12,74 @@ public_import:
 related_components:
   - UiPopperConnector
   - UiPopperTarget
+  - UiPopconfirm
   - UiSelect
   - UiTooltip
 
+examples:
+  - title: Usage
+    code: |
+      <template>
+          <UiPopperConnector>
+              <UiButton variant="danger">
+                  Delete
+              </UiButton>
+
+              <UiPopper role="dialog" class="popconfirm">
+                  <div class="popconfirm__content">
+                      This action cannot be cancelled. Continue?
+                  </div>
+
+                  <div class="popconfirm__footer">
+                      <UiButton variant="danger">
+                          Yes
+                      </UiButton>
+
+                      <UiButton appearance="secondary">
+                          No
+                      </UiButton>
+                  </div>
+              </UiPopper>
+          </UiPopperConnector>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiButton, UiPopper, UiPopperConnector } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Custom target components
+    code: |
+      <template>
+          <UiPopperConnector>
+              <UiPopperTarget tag="span" role="button" class="icon-button">
+                  <IconTrash aria-label="Delete" />
+              </UiPopperTarget>
+
+              <UiPopper role="tooltip" class="tooltip">
+                  Delete
+              </UiPopper>
+
+              <UiPopper role="dialog" class="popconfirm">
+                  <div class="popconfirm__content">
+                      This action cannot be cancelled. Continue?
+                  </div>
+
+                  <div class="popconfirm__footer">
+                      <UiButton variant="danger">
+                          Yes
+                      </UiButton>
+
+                      <UiButton appearance="secondary">
+                          No
+                      </UiButton>
+                  </div>
+              </UiPopper>
+          </UiPopperConnector>
+      </template>
+
+      <script lang="ts" setup>
+      import IconTrash from '@retailcrm/embed-ui-v1-components/assets/sprites/ui/delete.svg'
+      import { UiButton, UiPopper, UiPopperConnector, UiPopperTarget } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
 use_when:
   - You need a floating layer anchored to a target element.
   - You need separate show and hide triggers for target and popper.
@@ -24,6 +88,7 @@ use_when:
 avoid_when:
   - You need a regular block in normal document flow.
   - You need a high-level dropdown or tooltip and do not need low-level control.
+  - You need a short action confirmation; use UiPopconfirm instead.
 
 api:
   key_props:

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

@@ -3,7 +3,6 @@ summary: >
   UiPopperConnector is a lightweight wrapper that gives target-side and popper-side parts
   a shared target context. It has almost no UI meaning on its own, but is often required
   for correct target-driven floating behavior.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uipopper--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -94,4 +93,3 @@ 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.

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

@@ -2,7 +2,6 @@ component: UiPopperTarget
 summary: >
   UiPopperTarget is the target-side wrapper that registers a DOM element in popper context.
   A good mental model is "this node is the anchor", not "this is a visual layout wrapper".
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uipopper--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -97,4 +96,3 @@ 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.

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

@@ -2,13 +2,27 @@ component: UiRadio
 summary: >
   UiRadio is the single-choice selection control for exclusive option sets.
   It is the radio-style counterpart to UiCheckbox.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiradio--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
   named:
     - UiRadio
 
+examples:
+  - title: Example
+    code: |
+      <template>
+        <UiRadio id="delivery-courier" v-model:model="deliveryType" value="courier" name="delivery-type" />
+        <label for="delivery-courier">Courier</label>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiRadio } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const deliveryType = ref('courier')
+      </script>
+
 use_when:
   - You need one selected value from a fixed set.
 
@@ -73,6 +87,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-radio

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

@@ -4,7 +4,6 @@ summary: >
   a compact inline switch and a richer section-card layout. It is useful when the
   choice set is small and always visible. For richer per-option content, compose it
   with UiRadioSwitchOption instead of relying only on the options array.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiradioswitch--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -17,6 +16,61 @@ related_components:
   - UiField
   - UiRadioSwitchOption
 
+examples:
+  - title: Basic switcher
+    code: |
+      <template>
+        <UiRadioSwitch
+          v-model:value="mode"
+          :options="options"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiRadioSwitch } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const mode = ref({ key: 'auto' })
+
+      const options = [
+        { label: 'Auto', value: { key: 'auto' } },
+        { label: 'Manual', value: { key: 'manual' } },
+      ]
+      </script>
+  - title: Cards with descriptions
+    code: |
+      <template>
+        <UiRadioSwitch
+          v-model:value="mode"
+          appearance="section"
+          rubber
+          :equal-fn="equalFn"
+        >
+          <UiRadioSwitchOption
+            label="Auto"
+            :value="{ key: 'auto' }"
+            description="Automatic mode"
+          />
+
+          <UiRadioSwitchOption
+            label="Manual"
+            :value="{ key: 'manual' }"
+            description="Manual setup"
+          />
+        </UiRadioSwitch>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import {
+        UiRadioSwitch,
+        UiRadioSwitchOption,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const mode = ref({ key: 'auto' })
+      const equalFn = (a?: { key: string }, b?: { key: string }) => a?.key === b?.key
+      </script>
+
 use_when:
   - You need one selected value from a small fixed set.
   - You want a segmented control instead of classic radio circles.

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

@@ -3,7 +3,6 @@ summary: >
   UiRadioSwitchOption is the declarative option child of UiRadioSwitch. It is the
   richer alternative to the plain options array and is used when one option needs
   custom icon, label, description, or selected-state checkmark content.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiradioswitch--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -112,6 +111,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-radio-switch-option

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

@@ -2,13 +2,57 @@ component: UiScrollBox
 summary: >
   UiScrollBox is a scrollable container for constrained content areas. Use it when content
   should remain inside a dedicated scrolling region instead of growing the whole page.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiscrollbox--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
   named:
     - UiScrollBox
 
+examples:
+  - title: Example
+    code: |
+      <template>
+          <div :class="$style['wrapper']">
+              <UiScrollBox v-bind="$attrs" :class="$style['block']">
+                  <div :class="[$style['content'], $style['content_tall']]" />
+              </UiScrollBox>
+
+              <UiScrollBox v-bind="$attrs" :class="$style['block']">
+                  <div :class="[$style['content'], $style['content_wide']]" />
+              </UiScrollBox>
+          </div>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiScrollBox } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
+      <style lang="less" module>
+
+      .wrapper {
+        display: flex;
+      }
+
+      .block {
+        width: 120px;
+        height: 147px;
+        border: 1px solid rgba(30, 34, 72, 0.16);
+        border-radius: 8px;
+
+        &:not(:last-child) {
+          margin-right: 8px;
+        }
+      }
+
+      .content {
+        width: 100%;
+        height: 100%;
+
+        &_wide { width: 300px; }
+        &_tall { height: 300px; }
+      }
+      </style>
+
 use_when:
   - You need a bounded scroll area.
   - You need long content inside a fixed-height or fixed-width region.
@@ -62,4 +106,3 @@ 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.

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

@@ -3,7 +3,6 @@ summary: >
   UiSelect is a dropdown component for single-select and multi-select flows. It combines
   a textbox-like trigger with a popper-based option layer. For a correct mental model,
   read it together with UiPopper, UiPopperConnector, and UiPopperTarget.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiselect--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -19,6 +18,139 @@ related_components:
   - UiPopperConnector
   - UiPopperTarget
 
+examples:
+  - title: Basic selection
+    code: |
+      <template>
+          <UiSelect placeholder="Assignee">
+              <UiSelectOption value="kyle" label="Kyle Simmons" />
+              <UiSelectOption value="eduardo" label="Eduardo Henry" />
+              <UiSelectOption value="philip" label="Philip Williamson" />
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import {
+        UiSelect,
+        UiSelectOption,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Multiple selection with clearing
+    code: |
+      <template>
+          <UiSelect
+              v-model:value="value"
+              multiple
+              clearable
+              placeholder="Assignees"
+          >
+              <UiSelectOption value="kyle" label="Kyle Simmons" />
+              <UiSelectOption value="eduardo" label="Eduardo Henry" />
+              <UiSelectOption value="philip" label="Philip Williamson" />
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiSelect, UiSelectOption } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<string[]>([])
+      </script>
+  - title: Option search
+    code: |
+      <template>
+          <UiSelect filterable placeholder="Find a user">
+              <UiSelectOption value="kyle" label="Kyle Simmons" />
+              <UiSelectOption value="eduardo" label="Eduardo Henry" />
+              <UiSelectOption value="philip" label="Philip Williamson" />
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiSelect, UiSelectOption } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Error state (`invalid`)
+    code: |
+      <template>
+          <UiSelect
+              v-model:value="value"
+              invalid
+              placeholder="User"
+          >
+              <UiSelectOption value="kyle" label="Kyle Simmons" />
+              <UiSelectOption value="eduardo" label="Eduardo Henry" />
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiSelect, UiSelectOption } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref('eduardo')
+      </script>
+  - title: "`readonly` mode"
+    code: |
+      <template>
+          <UiSelect readonly placeholder="User">
+              <UiSelectOption value="kyle" label="Kyle Simmons" />
+              <UiSelectOption value="eduardo" label="Eduardo Henry" />
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiSelect, UiSelectOption } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: "`disabled` mode"
+    code: |
+      <template>
+          <UiSelect disabled placeholder="User">
+              <UiSelectOption value="kyle" label="Kyle Simmons" />
+              <UiSelectOption value="eduardo" label="Eduardo Henry" />
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiSelect, UiSelectOption } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Object options
+    code: |
+      <template>
+          <UiSelect
+              :value="{ id: 2, name: 'Eduardo Henry' }"
+              :equals-fn="(a, b) => a?.id === b?.id"
+              placeholder="User"
+          >
+              <UiSelectOption :value="{ id: 1, name: 'Kyle Simmons' }" label="Kyle Simmons" />
+              <UiSelectOption :value="{ id: 2, name: 'Eduardo Henry' }" label="Eduardo Henry" />
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiSelect, UiSelectOption } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Grouped options
+    code: |
+      <template>
+          <UiSelect placeholder="Employee">
+              <UiSelectOptionGroup label="Sales department">
+                  <UiSelectOption value="kyle" label="Kyle Simmons" />
+                  <UiSelectOption value="eduardo" label="Eduardo Henry" />
+              </UiSelectOptionGroup>
+
+              <UiSelectOptionGroup label="Support">
+                  <UiSelectOption value="philip" label="Philip Williamson" />
+              </UiSelectOptionGroup>
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import {
+        UiSelect,
+        UiSelectOption,
+        UiSelectOptionGroup,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
 use_when:
   - You need to choose one value from a list.
   - You need multi-select behavior.

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

@@ -2,7 +2,6 @@ component: UiSelectOption
 summary: >
   UiSelectOption is the base selectable child of UiSelect. It represents one option node
   in the select option tree.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiselect--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -71,6 +70,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-select-option

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

@@ -1,7 +1,6 @@
 component: UiSelectOptionGroup
 summary: >
   UiSelectOptionGroup groups related UiSelectOption nodes under a shared label.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiselect--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -63,6 +62,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-select-option-group

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

@@ -2,13 +2,23 @@ component: UiSkeleton
 summary: >
   UiSkeleton displays a placeholder block for loading content. It supports text,
   rectangle and circle appearances with pulse or shimmer animation.
-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'
   named:
     - UiSkeleton
 
+examples:
+  - title: Example
+    code: |
+      <template>
+        <UiSkeleton />
+
+      </template>
+
+      <script lang="ts" setup>
+      import { UiSkeleton } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
 use_when:
   - You need a content placeholder before actual data is loaded.
   - You need line, card or avatar-like loading placeholders.
@@ -68,6 +78,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-skeleton