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

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}

@@ -39,3 +39,33 @@ geometry:
   layout: teleported modal overlay
   root_display: flex
   width_behavior: viewport-covering overlay with content-sized or responsive surface
+
+behavior:
+  notes:
+    - Lower-level surface keeps modal mechanics while leaving more composition responsibility to the caller.
+    - Use role intentionally for dialog or alertdialog flows.
+
+composition:
+  works_well_with:
+    - UiModalWindow
+  patterns:
+    - title: Custom modal shell
+      notes: Use only when UiModalWindow does not expose enough structure for the required modal.
+
+ai_notes:
+  do:
+    - Prefer UiModalWindow for ordinary centered dialogs.
+  avoid:
+    - Do not choose the surface API just to change simple body content.
+
+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-modal-window

package/docs/profiles/components/UiNumberStepper.yml

@@ -0,0 +1,100 @@
+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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiNumberStepper
+
+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.
+
+avoid_when:
+  - You need plain text or decimal input without stepper controls.
+
+api:
+  key_props:
+    - name: value
+    - name: min
+    - name: max
+    - name: step
+    - name: decimals
+    - name: clamp
+    - name: nullable
+    - name: direction
+  methods:
+    - name: focus
+    - name: blur
+    - name: increase
+    - name: decrease
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-number-stepper
+    tag: div
+  notes: One inline control root wraps the text input and increment or decrement actions.
+
+geometry:
+  layout: inline numeric control
+  root_display: inline-flex
+  width_behavior: content-sized by default
+
+behavior:
+  notes:
+    - Can clamp values into range.
+    - Supports horizontal and vertical direction.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiTextbox
+    - UiSlider
+  patterns:
+    - title: Exact bounded number
+      notes: Use for quantities, limits, delays, and other settings where increment and decrement controls are useful.
+    - title: Numeric filter
+      notes: In table filters, keep the value in query parameters when routing exists.
+
+ai_notes:
+  do:
+    - Use for precise numeric settings with known min, max, or step.
+    - Prefer nullable when clearing the value is a valid state.
+  avoid:
+    - Do not use when the value is an identifier, phone, code, or other numeric-looking text.
+
+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-number-stepper

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

@@ -16,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.
@@ -209,29 +248,6 @@ composition:
     - title: Compact actions
       notes: Keep only one or two compact actions on the right.
 
-examples:
-  - title: Editable header with addon and actions
-    goal: Build a page header with inline validation and a link near the title.
-    code: |
-      <UiPageHeader
-        v-model:value="title"
-        :invalid="!title"
-        :error="title ? '' : 'Title is required'"
-        editable
-        placeholder="Enter a title"
-      >
-        <template #addon>
-          <UiLink>
-            Collapse filter
-          </UiLink>
-        </template>
-
-        <template #actions>
-          <UiButton appearance="tertiary">
-            Actions
-          </UiButton>
-        </template>
-      </UiPageHeader>
 
 ai_notes:
   do:

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}

@@ -12,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.
@@ -23,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:
@@ -178,19 +244,6 @@ composition:
     - title: Shared target context
       notes: The target ref usually comes through UiPopperConnector and UiPopperTarget.
 
-examples:
-  - title: Mental model
-    goal: Understand the basic target plus floating content pattern.
-    code: |
-      <UiPopperConnector>
-        <UiPopperTarget>
-          <button type="button">Open</button>
-        </UiPopperTarget>
-
-        <UiPopper :visible="open">
-          Popup content
-        </UiPopper>
-      </UiPopperConnector>
 
 ai_notes:
   do:

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

@@ -80,31 +80,6 @@ composition:
     - title: Explicit anchor
       notes: Add UiPopperTarget only when the anchor must be limited to a specific wrapper or sub-area.
 
-examples:
-  - title: Shared target context
-    goal: Connect target and popper through one shared wrapper.
-    code: |
-      <UiPopperConnector>
-        <UiPopperTarget>
-          <button type="button">Open</button>
-        </UiPopperTarget>
-
-        <UiPopper :visible="open">
-          Content
-        </UiPopper>
-      </UiPopperConnector>
-  - title: Connector without explicit target
-    goal: Use a button as the implicit anchor.
-    code: |
-      <UiPopperConnector>
-        <UiButton appearance="secondary">
-          Open
-        </UiButton>
-
-        <UiPopper :visible="open">
-          Content
-        </UiPopper>
-      </UiPopperConnector>
 
 ai_notes:
   do:
@@ -113,3 +88,8 @@ ai_notes:
   avoid:
     - Do not use it as a styling wrapper.
     - Do not add UiPopperTarget automatically around every trigger.
+
+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.