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

package/docs/profiles/UiPopper.yml

@@ -0,0 +1,201 @@
+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:
+    shape: div.ui-v1-popper
+    tag: div
+  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
+  root_display: block
+  width_behavior: content-sized by floating content
+  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,115 @@
+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
+  root:
+    shape: no persistent DOM root
+    tag: none
+  notes: >
+    The connector exists mainly to provide target context. It is not a styled layout primitive.
+
+geometry:
+  layout: no standalone layout of its own
+  root_display: none
+  width_behavior: defined by slotted children
+  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,118 @@
+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
+  root:
+    shape: configurable wrapper tag
+    tag: configurable, div by default
+  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:
+  layout: wrapper defined by the chosen tag
+  root_display: depends on the chosen tag
+  width_behavior: follows the chosen tag and its children
+  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.

package/docs/profiles/UiRadio.yml

@@ -0,0 +1,38 @@
+component: UiRadio
+summary: >
+  UiRadio is the single-choice selection control for exclusive option sets.
+  It is the radio-style counterpart to UiCheckbox.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiRadio
+
+use_when:
+  - You need one selected value from a fixed set.
+
+avoid_when:
+  - You need multiple independent selections, use UiCheckbox instead.
+
+api:
+  key_props:
+    - name: model
+    - name: value
+    - name: required
+    - name: disabled
+  methods:
+    - name: click
+    - name: focus
+    - name: blur
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: span.ui-v1-radio
+    tag: span
+  notes: One inline wrapper around the visual radio control and label content.
+
+geometry:
+  layout: inline radio control
+  root_display: inline-flex
+  width_behavior: content-sized by default

package/docs/profiles/UiRadioSwitch.yml

@@ -0,0 +1,231 @@
+component: UiRadioSwitch
+summary: >
+  UiRadioSwitch is a single-choice segmented control with two practical modes:
+  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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiRadioSwitch
+    - UiRadioSwitchOption
+
+related_components:
+  - UiRadio
+  - UiField
+  - UiRadioSwitchOption
+
+use_when:
+  - You need one selected value from a small fixed set.
+  - You want a segmented control instead of classic radio circles.
+  - You need a card-like section switch with descriptions.
+  - You need object values and must compare them through equalFn.
+
+avoid_when:
+  - You need multiple independent selections.
+  - You need dozens of options or searchable choice, use UiSelect instead.
+  - You need free-form content unrelated to a single-choice switch.
+
+api:
+  key_props:
+    - name: value
+      notes: Current selected value.
+    - name: options
+      notes: Quick array-based way to declare simple options.
+    - name: equalFn
+      notes: Important when option values are objects or other non-primitives.
+    - name: appearance
+      notes: Switches between default inline mode and section card mode.
+    - name: size
+      notes: Controls option height and icon sizing in default mode.
+    - name: rubber
+      notes: Makes the root behave like inline-flex instead of stretching full width.
+  props:
+    - name: value
+      notes: Works as the single selected model value.
+    - name: options
+      notes: Expects array items shaped as { label, value, disabled }.
+    - name: equalFn
+      notes: Defaults to strict equality.
+    - name: appearance
+      notes: Supports default and section.
+    - name: size
+      notes: Supports sm, md, lg.
+    - name: rubber
+      notes: Useful when the switch should size to content.
+  child_components:
+    - name: UiRadioSwitchOption
+      key_props:
+        - value
+        - label
+        - description
+        - disabled
+      notes: >
+        Use it when an option needs description, custom icon, custom label, or
+        custom checkmark content.
+  slots:
+    - name: default
+      zone: option tree
+      creates: Replaces array-based options with manually declared UiRadioSwitchOption nodes.
+      accepts:
+        recommended:
+          - UiRadioSwitchOption
+        avoid:
+          - arbitrary interactive controls
+          - unrelated wrappers
+      notes: >
+        The simplest path is options for plain labels, and default slot for richer
+        option markup.
+    - name: icon
+      zone: shared option icon in options mode
+      notes: >
+        Used only when options array mode renders generated options. For per-option
+        rich composition, use UiRadioSwitchOption slots instead.
+  emits:
+    - name: change
+      payload: unknown
+      notes: Fired when the selected value changes.
+    - name: update:value
+      payload: unknown
+      notes: Main v-model channel.
+
+rendered_structure:
+  descriptive_only: true
+  notes: >
+    The component renders as one radiogroup root and a list of option shells with
+    radio semantics. This section is for mental modeling and debugging, not as a
+    stable styling contract.
+  root:
+    shape: div.ui-v1-radio-switch
+    tag: div
+  composition:
+    - UiRadioSwitch root with role=radiogroup
+    - UiRadioSwitchOption shells with role=radio
+    - section mode can add description and selected-state checkmark
+  classes:
+    - .ui-v1-radio-switch
+    - .ui-v1-radio-switch_borderless
+    - .ui-v1-radio-switch_rubber
+    - .ui-v1-radio-switch-option
+    - .ui-v1-radio-switch-option_default
+    - .ui-v1-radio-switch-option_standalone
+    - .ui-v1-radio-switch-option_active
+    - .ui-v1-radio-switch-option_disabled
+
+geometry:
+  layout: flex row for default mode, wrapping card row for section mode
+  root_display:
+    default: flex
+    rubber: inline-flex
+  width_behavior: stretches by default, content-sized with rubber
+  notes:
+    - Default appearance behaves like a segmented control with adjacent options.
+    - Section appearance removes the outer border and lets cards wrap to a new line.
+    - rubber makes the root inline-sized instead of full-width.
+    - In section mode each option has a large minimum width and card-like padding.
+
+styling:
+  notes:
+    - Current classes describe host DOM structure and states.
+    - Prefer appearance, size, and rubber over selector-level customization.
+  root_classes:
+    - .ui-v1-radio-switch
+    - .ui-v1-radio-switch-option
+  state_classes:
+    - .ui-v1-radio-switch_borderless
+    - .ui-v1-radio-switch_rubber
+    - .ui-v1-radio-switch-option_default
+    - .ui-v1-radio-switch-option_standalone
+    - .ui-v1-radio-switch-option_active
+    - .ui-v1-radio-switch-option_disabled
+  zones:
+    - .ui-v1-radio-switch-option__head
+    - .ui-v1-radio-switch-option__icon
+    - .ui-v1-radio-switch-option__label
+    - .ui-v1-radio-switch-option__description
+    - .ui-v1-radio-switch-option__done
+  typography:
+    default:
+      notes:
+        - Default mode uses regular text sizing.
+        - Section mode uses accent heading-like styling for the main label.
+
+behavior:
+  states:
+    - name: appearance=default
+      notes: Renders a compact segmented control.
+    - name: appearance=section
+      notes: Renders standalone cards with optional description and selected checkmark.
+    - name: disabled
+      notes: Disabled options cannot be selected or focused by keyboard navigation.
+    - name: rubber
+      notes: Keeps the root content-sized.
+  selection_and_matching:
+    - The component is always single-select.
+    - update:value and change are emitted together on selection change.
+    - equalFn should usually be provided when values are objects.
+    - In options mode the component generates UiRadioSwitchOption nodes internally.
+  keyboard:
+    - One tab stop is used for the whole group.
+    - ArrowLeft, ArrowRight, ArrowUp, and ArrowDown move focus and selection across enabled options.
+    - Home and End jump to the first or last enabled option.
+    - Space and Enter select the currently focused option.
+
+accessibility:
+  notes:
+    - The root acts as radiogroup.
+    - Each option acts as radio and exposes aria-checked and aria-disabled.
+    - The current implementation uses roving tabindex so only one option is tabbable.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiRadioSwitchOption
+  patterns:
+    - title: Simple mode switch
+      notes: Use options for a small plain-text set such as view or status mode.
+    - title: Section cards
+      notes: Use UiRadioSwitchOption when each choice needs icon, description, or custom checkmark.
+
+examples:
+  - title: Simple options array
+    goal: Build a compact single-choice segmented control.
+    code: |
+      <UiRadioSwitch
+        v-model:value="mode"
+        :options="[
+          { label: 'Auto', value: 'auto' },
+          { label: 'Manual', value: 'manual' },
+        ]"
+      />
+  - title: Rich card options
+    goal: Render section cards with object values and descriptions.
+    code: |
+      <UiRadioSwitch
+        v-model:value="mode"
+        appearance="section"
+        rubber
+        :equal-fn="(a, b) => a?.key === b?.key"
+      >
+        <UiRadioSwitchOption
+          label="Auto"
+          :value="{ key: 'auto' }"
+          description="Automatic mode"
+        />
+
+        <UiRadioSwitchOption
+          label="Manual"
+          :value="{ key: 'manual' }"
+          description="Manual setup"
+        />
+      </UiRadioSwitch>
+
+ai_notes:
+  do:
+    - Use options for simple text-only cases.
+    - Switch to UiRadioSwitchOption when a choice needs richer content.
+    - Provide equalFn for object values instead of relying on reference equality.
+  avoid:
+    - Do not use it for multi-select flows.
+    - Do not treat internal .ui-v1-* classes as a stable extension styling API.