@retailcrm/embed-ui-v1-components 0.9.13 → 0.9.15

package/docs/profiles/UiNumberStepper.yml

@@ -0,0 +1,40 @@
+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
+
+behavior:
+  notes:
+    - Can clamp values into range.
+    - Supports horizontal and vertical direction.

package/docs/profiles/UiPageHeader.yml

@@ -0,0 +1,240 @@
+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: .ui-v1-page-header
+  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
+  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.

package/docs/profiles/UiPopper.yml

@@ -0,0 +1,197 @@
+component: UiPopper
+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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiPopper
+
+related_components:
+  - UiPopperConnector
+  - UiPopperTarget
+  - UiSelect
+  - UiTooltip
+
+use_when:
+  - You need a floating layer anchored to a target element.
+  - You need separate show and hide triggers for target and popper.
+  - You need a dropdown, tooltip, or contextual popup with placement control.
+
+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.
+
+api:
+  key_props:
+    - name: visible
+      notes: Controls open state.
+    - name: target
+      notes: DOM target used for positioning.
+    - name: placement
+      notes: Controls side and alignment.
+    - name: targetTriggers
+      notes: Target-side trigger rules.
+    - name: popperTriggers
+      notes: Popper-side trigger rules.
+    - name: globalTriggers
+      notes: Global trigger rules such as outside click or escape.
+    - name: withArrow
+      notes: Adds an arrow element.
+  props:
+    - name: strategy
+      notes: Floating strategy such as absolute or fixed.
+    - name: container
+      notes: Teleport target, often body.
+    - name: disabled
+      notes: Disables floating behavior.
+    - name: delay
+      notes: Show or hide delay.
+    - name: detachTimeout
+      notes: Delay before detaching the layer.
+    - name: offset
+      notes: Floating layer offset.
+  slots:
+    - name: default
+      zone: floating content
+      creates: The floating content body rendered inside the popper layer.
+      accepts:
+        recommended:
+          - tooltip body
+          - menu or list content
+          - dropdown surface
+          - compact popup layout
+        avoid:
+          - full page layout
+          - content that relies on normal document flow
+          - unrelated anchor markup
+      layout_effect: Content is teleported into the floating layer and positioned relative to the active anchor.
+      notes: Content rendered inside the popper layer.
+  emits:
+    - name: update:visible
+      payload: boolean
+      notes: Main open-state update channel.
+    - name: show
+      payload: undefined
+      notes: Fired when the popper starts opening.
+    - name: shown
+      payload: undefined
+      notes: Fired when the popper is open.
+    - name: hide
+      payload: undefined
+      notes: Fired when the popper starts closing.
+    - name: hidden
+      payload: undefined
+      notes: Fired when the popper is closed.
+    - name: dispose
+      payload: undefined
+      notes: Fired when the layer is disposed.
+    - name: attached
+      payload: undefined
+      notes: Fired when the layer is attached to the DOM.
+
+rendered_structure:
+  descriptive_only: true
+  root: .ui-v1-popper
+  zones:
+    - .ui-v1-popper__arrow when withArrow=true
+    - .ui-v1-popper__content
+  notes: The popper is teleported into a container and lives outside the original layout tree.
+
+geometry:
+  layout: floating layer outside normal document flow
+  notes:
+    - Position is calculated relative to the target element.
+    - Container controls where the DOM node is teleported.
+    - Placement and floating options control side, alignment, and adaptation.
+
+styling:
+  notes:
+    - UiPopper is one of the main CSS-variable-driven primitives in the library.
+    - Prefer documented CSS variables over descendant selector overrides.
+    - Classes are mostly useful for debugging and understanding the floating surface structure.
+  root_classes:
+    - .ui-v1-popper
+  state_classes:
+    - .ui-v1-popper_hidden
+    - .ui-v1-popper_shown
+  zones:
+    - .ui-v1-popper__arrow
+    - .ui-v1-popper__content
+  css_variables:
+    public_theme_variables:
+      - name: --ui-v1-popper-background
+        effect: Surface and arrow background color.
+      - name: --ui-v1-popper-roundings
+        effect: Surface corner radius.
+      - name: --ui-v1-popper-arrow-roundings
+        effect: Arrow corner radius.
+      - name: --ui-v1-popper-arrow-size
+        effect: Arrow square size before rotation.
+      - name: --ui-v1-popper-width
+        effect: Content width.
+      - name: --ui-v1-popper-width-min
+        effect: Minimum content width.
+      - name: --ui-v1-popper-width-max
+        effect: Maximum content width.
+      - name: --ui-v1-popper-height
+        effect: Content height.
+      - name: --ui-v1-popper-height-min
+        effect: Minimum content height.
+      - name: --ui-v1-popper-height-max
+        effect: Maximum content height.
+      - name: --ui-v1-popper-padding
+        effect: Inner content padding.
+      - name: --ui-v1-popper-z-index
+        effect: Layer stacking level.
+  typography:
+    default:
+      mixin: text-small
+      size: 14px
+      line_height: 20px
+      weight: 400
+
+behavior:
+  notes:
+    - Target-side and popper-side triggers are configured separately.
+    - The layer may remain open across hover or focus when configured that way.
+    - Outside interactions are handled through global trigger rules.
+
+accessibility:
+  notes:
+    - UiPopper itself does not define semantic role for its content.
+    - ARIA semantics should come from the higher-level component using it.
+
+composition:
+  works_well_with:
+    - UiPopperConnector
+    - UiPopperTarget
+    - UiTooltip
+    - UiSelect
+  patterns:
+    - 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:
+    - Use UiPopper as low-level floating mechanics when higher-level components are not enough.
+    - Think in terms of target, triggers, and floating content as separate parts.
+  avoid:
+    - Do not treat UiPopper as a regular inline wrapper.
+    - Do not forget that it lives outside normal document flow.

package/docs/profiles/UiPopperConnector.yml

@@ -0,0 +1,109 @@
+component: UiPopperConnector
+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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiPopperConnector
+
+related_components:
+  - UiPopper
+  - UiPopperTarget
+  - UiSelect
+  - UiTooltip
+
+use_when:
+  - You need UiPopper and UiPopperTarget to share the same target context.
+  - You need the standard target-driven composition for a dropdown or tooltip.
+  - Your trigger already exposes its root element into connector context, for example UiButton.
+
+avoid_when:
+  - You need a generic visual wrapper without popper mechanics.
+  - Target is passed manually and the shared connector model is not used.
+
+api:
+  slots:
+    - name: default
+      zone: shared popper composition
+      creates: Shared target context for target-side and popper-side children.
+      accepts:
+        recommended:
+          - UiPopperTarget plus UiPopper
+          - implicit anchor trigger plus UiPopper
+          - tooltip-like target and floating content pairs
+        avoid:
+          - styling-only wrappers
+          - unrelated layout content
+          - children that do not participate in target or popper flow
+      layout_effect: Usually no direct layout effect; mainly establishes shared anchor context.
+      notes: Place target and popper-related children here so they share one context.
+
+rendered_structure:
+  descriptive_only: true
+  notes: >
+    The connector exists mainly to provide target context. It is not a styled layout primitive.
+
+geometry:
+  notes:
+    - It usually has no meaningful layout behavior on its own.
+    - Treat it as a context wrapper, not as a visual block.
+
+behavior:
+  notes:
+    - Stores or forwards the shared target element reference.
+    - Lets UiPopperTarget and UiPopper use the same anchor context.
+    - If a child component already exposes its root element into connector context, explicit UiPopperTarget may be unnecessary.
+    - UiButton is a practical example: inside UiPopperConnector it can act as the anchor without an extra UiPopperTarget wrapper.
+
+accessibility:
+  notes:
+    - Does not create ARIA semantics by itself.
+
+composition:
+  works_well_with:
+    - UiPopperTarget
+    - UiPopper
+    - UiTooltip
+    - UiSelect
+  patterns:
+    - title: Implicit anchor
+      notes: Connector alone is enough when the trigger already provides a stable root element.
+    - 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:
+    - Use UiPopperConnector when a higher-level component expects shared target context.
+    - Prefer connector-only composition when the trigger already exposes the correct root element.
+  avoid:
+    - Do not use it as a styling wrapper.
+    - Do not add UiPopperTarget automatically around every trigger.

package/docs/profiles/UiPopperTarget.yml

@@ -0,0 +1,112 @@
+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".
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiPopperTarget
+
+related_components:
+  - UiPopper
+  - UiPopperConnector
+  - UiSelect
+  - UiTooltip
+
+use_when:
+  - You need to explicitly mark the anchor element for UiPopper or a tooltip.
+  - You need to wrap a trigger and register it as the anchor in shared popper context.
+  - You need the floating layer to anchor to only part of a larger layout.
+
+avoid_when:
+  - You need a styling-only wrapper.
+  - Target ref is already passed manually and the connector model is not used.
+  - The trigger already exposes a suitable root element through UiPopperConnector, for example UiButton.
+
+api:
+  props:
+    - name: tag
+      notes: Wrapper tag name. Default is div.
+  slots:
+    - name: default
+      zone: target content
+      creates: The explicit anchor wrapper for the floating layer.
+      accepts:
+        recommended:
+          - one trigger node
+          - one title wrapper
+          - one compact anchor area
+        avoid:
+          - large unrelated layout trees
+          - content that should not define the anchor bounds
+          - multiple disconnected anchor areas
+      layout_effect: The wrapper becomes the anchor bounds used by popper positioning.
+      notes: Put the trigger or anchor node inside this slot.
+
+rendered_structure:
+  descriptive_only: true
+  notes: >
+    The component renders a configurable wrapper tag and stores its element ref in popper context.
+    It does not add complex UI logic on its own.
+
+geometry:
+  notes:
+    - Layout depends on the chosen tag and its children.
+    - Its main purpose is to provide the correct anchor ref for the popper.
+
+behavior:
+  notes:
+    - On mount and update, it forwards the current element ref into popper context.
+    - It is the target-side part of the UiPopperConnector + UiPopperTarget + UiPopper pattern.
+    - It is optional, not mandatory.
+    - Use it when you need an explicit wrapper as the anchor; skip it when connector already receives the right element.
+
+accessibility:
+  notes:
+    - It does not create ARIA semantics. Those should come from the inner trigger.
+
+composition:
+  works_well_with:
+    - UiPopperConnector
+    - UiPopper
+    - UiTooltip
+  patterns:
+    - title: Dedicated anchor wrapper
+      notes: Use a separate target wrapper when the floating layer should anchor to only part of a layout.
+    - title: Not always needed
+      notes: Connector-only composition is enough when the trigger already exposes its root element.
+
+examples:
+  - title: Tooltip anchor
+    goal: Anchor a floating layer to a specific title or button wrapper.
+    code: |
+      <UiPopperConnector>
+        <UiPopperTarget tag="span">
+          <span>Title</span>
+        </UiPopperTarget>
+
+        <UiPopper :visible="open">
+          Tooltip
+        </UiPopper>
+      </UiPopperConnector>
+  - title: Explicit title-only anchor
+    goal: Bind the floating layer to a title wrapper instead of the whole row.
+    code: |
+      <UiPopperConnector>
+        <UiPopperTarget tag="span">
+          <span class="header-title">Title</span>
+        </UiPopperTarget>
+
+        <UiPopper :visible="open">
+          Tooltip
+        </UiPopper>
+      </UiPopperConnector>
+
+ai_notes:
+  do:
+    - Use UiPopperTarget when the anchor should be limited to a specific part of the layout.
+    - Use it intentionally, not by default.
+  avoid:
+    - Do not treat the wrapper as decorative only; it affects what the floating layer anchors to.
+    - Do not wrap every UiButton or similar trigger with UiPopperTarget if connector already gives the correct anchor.