@retailcrm/embed-ui-v1-components 0.9.14 → 0.9.16

package/docs/profiles/UiLoader.yml

@@ -0,0 +1,38 @@
+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 or fixed only when the loader should escape normal inline flow.

package/docs/profiles/UiMenuItem.yml

@@ -0,0 +1,57 @@
+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.

package/docs/profiles/UiMenuItemGroup.yml

@@ -0,0 +1,50 @@
+component: UiMenuItemGroup
+summary: >
+  UiMenuItemGroup groups related menu items and exposes dedicated zones for group label
+  and quantity metadata.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiMenuItemGroup
+
+related_components:
+  - UiMenuItem
+
+use_when:
+  - You need several menu items under one group heading.
+  - You need group label or quantity metadata.
+
+avoid_when:
+  - You have only one item and no group semantics.
+
+api:
+  slots:
+    - name: default
+      zone: group-body
+      creates: Main group content.
+    - name: option
+      zone: option-list
+      creates: Explicit option area for grouped items.
+    - name: label
+      zone: group-label
+      creates: Group heading area.
+    - name: quantity
+      zone: group-meta
+      creates: Group quantity or meta area.
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-menu-item-group
+    tag: div
+  notes: The root wraps the group head and the nested option content.
+
+geometry:
+  layout: block-like menu group wrapper
+  root_display: block
+  width_behavior: stretches to available menu width
+
+ai_notes:
+  do:
+    - Use for grouped menu structure instead of manual heading-plus-list markup.

package/docs/profiles/UiModalSidebar.yml

@@ -0,0 +1,46 @@
+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
+
+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.

package/docs/profiles/UiModalWindow.yml

@@ -0,0 +1,44 @@
+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
+
+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

package/docs/profiles/UiModalWindowSurface.yml

@@ -0,0 +1,41 @@
+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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiModalWindowSurface
+
+related_components:
+  - UiModalWindow
+
+use_when:
+  - You need explicit modal surface composition.
+  - You need modal surface behavior without the higher-level modal wrapper.
+
+avoid_when:
+  - You just need the regular centered modal API, use UiModalWindow instead.
+
+api:
+  key_props:
+    - name: opened
+    - name: closable
+    - name: appearance
+    - name: fullscreen
+    - name: responsive
+    - name: scrolling
+    - name: role
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-modal-window
+    tag: div
+  notes: The component is teleported and renders the modal overlay and surface container directly.
+
+geometry:
+  layout: teleported modal overlay
+  root_display: flex
+  width_behavior: viewport-covering overlay with content-sized or responsive surface

package/docs/profiles/UiNumberStepper.yml

@@ -0,0 +1,52 @@
+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
+
+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.

package/docs/profiles/UiPageHeader.yml

@@ -0,0 +1,244 @@
+component: UiPageHeader
+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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiPageHeader
+
+related_components:
+  - UiButton
+  - UiLink
+  - UiTextbox
+  - UiPopperConnector
+  - UiPopperTarget
+
+use_when:
+  - You need the main title of an extension page.
+  - You need inline title editing.
+  - You need a small inline addon near the title, such as UiLink.
+  - You need compact right-aligned actions.
+
+avoid_when:
+  - You need a regular form label.
+  - You need a small section title without page-header semantics.
+  - You need a multi-line editor rather than inline title editing.
+
+api:
+  key_props:
+    - name: value
+      notes: Main title text.
+    - name: placeholder
+      notes: Placeholder for empty editable state.
+    - name: editable
+      notes: Enables the h1 -> UiTextbox -> h1 cycle.
+    - name: invalid
+      notes: Used for error styling and the empty-title tooltip scenario.
+    - name: error
+      notes: Required for the tooltip in remote mode when invalid and empty.
+  props:
+    - name: autofocus
+      notes: Focuses edit state after mount.
+    - name: autoselect
+      notes: Selects the current value inside the textbox on focus.
+    - name: readonly
+      notes: Blocks entering edit mode.
+    - name: disabled
+      notes: Blocks interaction completely.
+  slots:
+    - name: addon
+      zone: inline sibling near title
+      creates: An inline addon area next to the title.
+      accepts:
+        recommended:
+          - UiLink
+          - short text
+          - compact inline status
+        avoid:
+          - full form layout
+          - wide content blocks
+          - content that should belong to the tooltip target
+      layout_effect: Renders as a sibling next to the title inside the main area.
+      notes: >
+        Inline content near the title, for example UiLink. This slot lives as a sibling next to the
+        title and should not be placed inside the tooltip target.
+    - name: actions
+      zone: right-side actions
+      creates: A compact right-aligned actions area.
+      accepts:
+        recommended:
+          - UiButton
+          - UiToolbarButton
+          - UiToolbarLink
+          - one or two compact actions
+        avoid:
+          - full form groups
+          - wide content blocks
+          - large multi-row layouts
+      layout_effect: Stays in the right-side action zone and should remain compact.
+      notes: Compact actions on the right, usually UiButton or toolbar-like actions.
+  emits:
+    - name: update:value
+      payload: string
+      notes: Main title update channel.
+    - name: focus
+      payload: FocusEvent
+      notes: Forwarded from the inner textbox.
+    - name: blur
+      payload: FocusEvent
+      notes: Forwarded from the inner textbox.
+    - name: change
+      payload: Event
+      notes: Forwarded from the inner textbox.
+    - name: keydown
+      payload: KeyboardEvent
+      notes: Forwarded from the inner textbox.
+  methods:
+    - name: focus
+      notes: Enters edit state and focuses the textbox.
+    - name: blur
+      notes: Blurs the textbox.
+
+rendered_structure:
+  descriptive_only: true
+  notes: >
+    This structure is useful for reasoning and debugging, not as a public styling API.
+  root:
+    shape: div.ui-v1-page-header
+    tag: div
+  zones:
+    - .ui-v1-page-header__main
+    - .ui-v1-page-header__title
+    - .ui-v1-page-header__addon
+    - .ui-v1-page-header__actions
+    - h1.ui-v1-page-header__trigger in display state
+    - UiTextbox.ui-v1-page-header__textbox in edit state
+  remote_overlay_notes:
+    - The tooltip is anchored to the title area through UiPopperConnector and UiPopperTarget.
+    - The addon renders as a sibling next to the title, not inside the tooltip target.
+
+geometry:
+  layout: flex
+  root_display: flex
+  width_behavior: stretches to container width by default
+  notes:
+    - Root uses justify-content space-between and can wrap.
+    - The main area contains title and optional addon.
+    - The actions area stays compact on the right.
+    - The display-state title draws an underline aligned with the underline textbox style.
+    - In edit state, the textbox uses size=xl, autofit, and outlined=false.
+
+styling:
+  notes:
+    - UiPageHeader styling is split between the page-header root and the inner UiTextbox used during edit state.
+    - Prefer editable, invalid, disabled, and slot composition before custom CSS.
+    - Classes below are descriptive hooks, not a stable public selector API.
+  root_classes:
+    - .ui-v1-page-header
+  state_classes:
+    - .ui-v1-page-header_disabled
+    - .ui-v1-page-header_invalid
+    - .ui-v1-page-header__trigger_editable
+    - .ui-v1-page-header__trigger_empty
+  zones:
+    - .ui-v1-page-header__main
+    - .ui-v1-page-header__title
+    - .ui-v1-page-header__addon
+    - .ui-v1-page-header__actions
+    - .ui-v1-page-header__trigger
+    - .ui-v1-page-header__textbox
+  css_variables:
+    public_theme_variables:
+      - name: --ui-v1-page-header-danger-color
+        effect: Invalid title color and underline color.
+      - name: --ui-v1-page-header-danger-shadow-color
+        effect: Invalid shadow color for the editing textbox.
+    internal_layout_variables:
+      - name: --ui-v1-page-header-primary-color
+        effect: Derived active title color, often provided through invalid or focus flow.
+      - name: --ui-v1-page-header-primary-shadow-color
+        effect: Derived active shadow color for the editing textbox.
+      - name: --border-color
+        effect: Display-state underline color on the editable trigger.
+  typography:
+    title:
+      mixin: h2-accent
+      size: 24px
+      line_height: 32px
+      weight: 500
+    notes:
+      - The display h1 and the edit-state textbox share the same title typography.
+      - Addon and actions keep their own component typography and should not be forced into the title scale.
+
+behavior:
+  states:
+    - name: editable
+      notes: Enables the h1 -> UiTextbox -> h1 cycle.
+    - name: non-editable
+      notes: Leaves the title as a regular h1 and should not break native text selection.
+    - name: readonly
+      notes: Blocks entering edit state.
+    - name: disabled
+      notes: Blocks interaction completely.
+    - name: invalid
+      notes: Is visually meaningful only when the value is empty.
+  notes:
+    - Click, Enter, and Space enter edit state when editable is true.
+    - Enter finishes editing and returns to display state unless a blocking error state is active.
+    - Placeholder is shown when value is empty.
+    - If invalid=true, value is empty, and error is present, remote mode shows a tooltip.
+    - While invalid + empty + error is active, the component stays in edit state on blur and Enter.
+
+accessibility:
+  notes:
+    - In display state, an editable title gets role=button and tabindex=0.
+    - In display state, a non-editable title stays a plain h1.
+    - The inner textbox gets aria-label based on placeholder or current value.
+    - Keyboard completion for inline editing is centered on Enter.
+
+composition:
+  works_well_with:
+    - UiButton
+    - UiLink
+  patterns:
+    - title: Inline filter link
+      notes: Use addon for a neighboring link such as Collapse filter.
+    - 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:
+    - Use UiPageHeader as a page-level title, not as a replacement for UiField.
+    - Set placeholder explicitly for editable scenarios.
+    - Pass both invalid and a clear error message if empty-title validation matters.
+    - Use addon for inline neighbors next to the title.
+  avoid:
+    - Do not assume the tooltip is anchored to the entire main area.
+    - Do not overload the actions area with full form layout.