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

package/docs/profiles/UiRadioSwitch.yml

@@ -96,6 +96,9 @@ rendered_structure:
     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
@@ -112,6 +115,10 @@ rendered_structure:
 
 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.

package/docs/profiles/UiRadioSwitchOption.yml

@@ -62,10 +62,18 @@ api:
 
 rendered_structure:
   descriptive_only: true
+  root:
+    shape: div.ui-v1-radio-switch-option
+    tag: div
   notes: >
     UiRadioSwitchOption does not own the whole selection model. It is rendered inside
     UiRadioSwitch and becomes one radio node within the parent radiogroup.
 
+geometry:
+  layout: segmented option shell or card-like option
+  root_display: flex
+  width_behavior: flexible within the parent group layout
+
 behavior:
   states:
     - name: disabled

package/docs/profiles/UiScrollBox.yml

@@ -17,3 +17,15 @@ avoid_when:
 
 api:
   key_props: []
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: configurable wrapper tag or PerfectScrollbar root
+    tag: configurable, div by default
+  notes: The root depends on native mode and tag prop, but behaves as a scroll container rather than a visual primitive.
+
+geometry:
+  layout: scroll container
+  root_display: block
+  width_behavior: stretches to the size of its layout context

package/docs/profiles/UiSelect.yml

@@ -143,6 +143,11 @@ rendered_structure:
   descriptive_only: true
   notes: >
     Select is not a single DOM node in practice. Trigger and dropdown live in separate layers.
+  root:
+    trigger_shape: div.ui-v1-select
+    trigger_tag: div
+    dropdown_shape: div.ui-v1-select__popper via UiPopper
+    dropdown_tag: div
   composition:
     - UiPopperConnector as shared context
     - UiSelectTrigger as textbox-like trigger
@@ -158,6 +163,10 @@ rendered_structure:
 geometry:
   trigger_layout: textbox-like, fit-content, max-width 100%
   dropdown_layout: popper layer outside normal document flow
+  root_display:
+    trigger: block
+    dropdown: block in a floating layer
+  width_behavior: trigger is content-sized with max-width 100%, dropdown follows content and popperFitTrigger rules
   notes:
     - The trigger behaves visually like a textbox.
     - The dropdown is rendered in a popper layer outside normal flow.

package/docs/profiles/UiSelectOption.yml

@@ -27,6 +27,18 @@ api:
     - name: counter
     - name: accent
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-select-option
+    tag: div
+  notes: Renders one option wrapper that usually contains a UiMenuItem row.
+
+geometry:
+  layout: listbox option row
+  root_display: block
+  width_behavior: stretches to available dropdown width
+
 ai_notes:
   do:
     - Use as the default child node of UiSelect.

package/docs/profiles/UiSelectOptionGroup.yml

@@ -21,6 +21,18 @@ api:
   key_props:
     - name: label
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-select-option-group
+    tag: div
+  notes: Renders one structural group wrapper around a heading area and nested option content.
+
+geometry:
+  layout: block-like option group wrapper
+  root_display: block
+  width_behavior: stretches to available dropdown width
+
 ai_notes:
   do:
     - Use to structure large option lists inside UiSelect.

package/docs/profiles/UiSlider.yml

@@ -24,3 +24,15 @@ api:
     - name: labelled
   emits:
     - name: update:value
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-slider
+    tag: div
+  notes: The root contains labels, track, filler, and draggable handle nodes.
+
+geometry:
+  layout: horizontal slider track
+  root_display: flex
+  width_behavior: stretches to container width by default

package/docs/profiles/UiSwitch.yml

@@ -23,3 +23,15 @@ api:
     - name: click
     - name: focus
     - name: blur
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: span.ui-v1-switch
+    tag: span
+  notes: The root is one compact inline switch control.
+
+geometry:
+  layout: inline switch control
+  root_display: inline-block
+  width_behavior: content-sized by default

package/docs/profiles/UiTab.yml

@@ -57,6 +57,9 @@ api:
 
 rendered_structure:
   descriptive_only: true
+  root:
+    shape: no standalone DOM root
+    tag: none
   notes: >
     UiTab is a structural declaration rather than a standalone DOM component. The
     parent UiTabGroup resolves UiTab children and renders the actual tab buttons,
@@ -64,6 +67,8 @@ rendered_structure:
 
 geometry:
   layout: no standalone layout, interpreted by UiTabGroup
+  root_display: none
+  width_behavior: no standalone width behavior of its own
   notes:
     - UiTab itself should not be used outside UiTabGroup.
     - Icon-only tabs are inferred when icon exists but label and counter do not.

package/docs/profiles/UiTabGroup.yml

@@ -101,6 +101,9 @@ rendered_structure:
     UiTabGroup renders a header row, a visible tablist region, an optional overflow
     trigger with popper menu, and an optional tabpanel for the active UiTab content.
     Class names are useful for debugging, not as a guaranteed public styling API.
+  root:
+    shape: div.ui-v1-tab-group
+    tag: div
   composition:
     - .ui-v1-tab-group root
     - .ui-v1-tab-group__head with role=tablist region
@@ -119,6 +122,8 @@ rendered_structure:
 
 geometry:
   layout: block-level group with full-width header and optional content panel
+  root_display: block
+  width_behavior: stretches to container width by default
   notes:
     - The group itself stretches to width 100%.
     - The visible header keeps tabs on one row.

package/docs/profiles/UiTable.yml

@@ -52,7 +52,9 @@ api:
 
 rendered_structure:
   descriptive_only: true
-  root: .ui-v1-table
+  root:
+    shape: table.ui-v1-table
+    tag: table
   zones:
     - .ui-v1-table__section_head
     - .ui-v1-table__section_body
@@ -66,7 +68,9 @@ rendered_structure:
 
 geometry:
   layout: block-width table
+  root_display: table
   width: 100%
+  width_behavior: stretches to container width by default
   notes:
     - Root fills available width.
     - fixed=true switches table-layout from auto to fixed.

package/docs/profiles/UiTableBodyCell.yml

@@ -28,6 +28,18 @@ api:
     - name: trim
     - name: theme
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: td.ui-v1-table__body-cell
+    tag: td
+  notes: The component renders one table body cell.
+
+geometry:
+  layout: table cell
+  root_display: table-cell
+  width_behavior: controlled by table layout and column sizing
+
 ai_notes:
   do:
     - Keep it inside UiTable row composition.

package/docs/profiles/UiTableColumn.yml

@@ -36,3 +36,15 @@ api:
     - name: label
       zone: header-label
       creates: Header label content.
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: col
+    tag: col
+  notes: The component renders one structural table column node.
+
+geometry:
+  layout: structural table column
+  root_display: table-column
+  width_behavior: controlled by table layout and width props on the parent table

package/docs/profiles/UiTableFooterButton.yml

@@ -25,6 +25,18 @@ api:
   emits:
     - name: click
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: button.ui-v1-table__footer-button
+    tag: button
+  notes: The visible label is wrapped in an inner inline-flex content span.
+
+geometry:
+  layout: inline footer action
+  root_display: inline-block
+  width_behavior: content-sized by label content
+
 ai_notes:
   do:
     - Keep it in table footer usage.

package/docs/profiles/UiTableFooterSection.yml

@@ -19,6 +19,18 @@ avoid_when:
   - UiTable footer slots already solve the layout.
   - You do not need explicit footer structure.
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-table__footer-section
+    tag: div
+  notes: Renders one footer section wrapper inside the table footer controls area.
+
+geometry:
+  layout: footer meta or control section
+  root_display: block
+  width_behavior: content-sized within the footer flex row
+
 ai_notes:
   do:
     - Use it only as part of custom table footer composition.

package/docs/profiles/UiTableHeadCell.yml

@@ -25,6 +25,18 @@ api:
     - name: align
     - name: trim
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: th.ui-v1-table__head-cell
+    tag: th
+  notes: The component renders one table head cell.
+
+geometry:
+  layout: table header cell
+  root_display: table-cell
+  width_behavior: controlled by table layout and column sizing
+
 ai_notes:
   do:
     - Prefer UiTableColumn first for regular table headers.

package/docs/profiles/UiTableSorter.yml

@@ -26,6 +26,18 @@ api:
   emits:
     - name: click
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: button.ui-v1-table__sorter
+    tag: button
+  notes: The root contains the label and sort icon as one inline control.
+
+geometry:
+  layout: inline sorting control
+  root_display: inline-flex
+  width_behavior: content-sized by label and icon
+
 ai_notes:
   do:
     - Pair it with explicit sort state in screen logic.

package/docs/profiles/UiTag.yml

@@ -27,3 +27,15 @@ api:
     - name: focus
     - name: blur
     - name: remove
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-tag-wrapper
+    tag: div
+  notes: The public root is a wrapper div; the visible pill itself is the nested .ui-v1-tag node.
+
+geometry:
+  layout: wrapper around a content-sized tag pill
+  root_display: block
+  width_behavior: root follows normal block flow, inner tag stays content-sized

package/docs/profiles/UiTextbox.yml

@@ -193,7 +193,9 @@ rendered_structure:
     This is a descriptive model of the current implementation for reasoning and debugging,
     not a guaranteed DOM API. The root is span-based, so UiTextbox should be treated as
     an inline control rather than a block wrapper.
-  root: span.ui-v1-textbox
+  root:
+    shape: span.ui-v1-textbox
+    tag: span
   zones:
     - span.ui-v1-textbox__prefix
     - span.ui-v1-textbox__icon.ui-v1-textbox__icon_leading
@@ -205,7 +207,9 @@ rendered_structure:
 
 geometry:
   layout: inline-flex
+  root_display: inline-flex
   width: fit-content
+  width_behavior: content-sized with max-width 100%
   max_width: 100%
   notes:
     - Root behaves as a span-based inline-flex group around the actual control.

package/docs/profiles/UiTimePicker.yml

@@ -32,3 +32,15 @@ api:
     - name: open
     - name: close
     - name: focus
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-time-picker
+    tag: div
+  notes: The root is a combobox wrapper around the textbox-like trigger and the popper-based listbox.
+
+geometry:
+  layout: combobox wrapper with floating menu
+  root_display: block
+  width_behavior: follows normal block flow for the wrapper, with a floating dropdown layer

package/docs/profiles/UiToggleButton.yml

@@ -0,0 +1,211 @@
+component: UiToggleButton
+summary: >
+  UiToggleButton is a stateful button primitive for toggle-like interactions. It keeps
+  native button shape and methods, but the pressed state is controlled externally and
+  can be used either for a standalone toggle or as the visual basis of segmented groups
+  such as UiToggleGroup.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiToggleButton
+
+related_components:
+  - UiToggleGroup
+  - UiCheckbox
+  - UiSwitch
+
+use_when:
+  - You need a button-looking control with externally managed pressed state.
+  - You need a primitive for segmented controls or compact filter chips.
+  - You need button methods like focus, blur, and click together with toggle styling.
+
+avoid_when:
+  - You need checkbox or radio semantics without custom composition.
+  - You need a plain action button without persistent state, use UiButton instead.
+  - You need a ready multi-select segmented group, use UiToggleGroup instead.
+
+api:
+  key_props:
+    - name: pressed
+      notes: Enables the selected visual state.
+    - name: size
+      values:
+        - lg
+        - md
+        - sm
+        - xs
+      notes: Controls height, horizontal padding, icon size, and radius.
+    - name: disabled
+      notes: Disables native interaction and applies disabled styling.
+    - name: grouped
+      notes: Enables segmented-group geometry for adjacent toggle buttons.
+  props:
+    - name: id
+      notes: Optional id passed to the native button root.
+    - name: type
+      notes: Native button type, defaults to button.
+    - name: focused
+      notes: Forces the focus-ring styling; used internally by keyboard-managed groups.
+  slots:
+    - name: default
+      zone: button content
+      creates: Inner content layout for label and optional icons.
+      accepts:
+        recommended:
+          - text
+          - text plus icon
+          - icon component
+          - svg
+        avoid:
+          - nested interactive elements
+          - large block layout wrappers
+      layout_effect: Text and icon nodes are normalized into separate inner spans.
+      notes: Main content slot for standalone or grouped toggles.
+  methods:
+    - name: click
+      notes: Triggers a click programmatically.
+    - name: focus
+      notes: Focuses the native button root.
+    - name: blur
+      notes: Removes focus from the native button root.
+
+rendered_structure:
+  descriptive_only: true
+  notes: >
+    UiToggleButton currently renders one native button root with normalized inner content.
+    This structure is useful for reasoning and debugging, not as a stable styling API.
+  root:
+    shape: button.ui-v1-toggle-button
+    tag: button
+  zones:
+    - .ui-v1-toggle-button__content
+    - .ui-v1-toggle-button__icon
+    - .ui-v1-toggle-button__text
+  state_classes:
+    - .ui-v1-toggle-button_pressed
+    - .ui-v1-toggle-button_disabled
+    - .ui-v1-toggle-button_focused
+    - .ui-v1-toggle-button_grouped
+
+geometry:
+  layout: inline-flex button root
+  root_display: inline-flex
+  width_behavior: content-sized by default
+  notes:
+    - Fits into inline rows and compact filter bars without forcing a new line.
+    - grouped keeps each button inline-sized while allowing adjacent segments to merge visually.
+    - Size controls height, min-width, horizontal padding, content gap, and radius.
+    - grouped removes standalone radii and lets adjacent buttons visually merge into a segmented row.
+    - The component stays content-sized by default and fits naturally into inline rows and compact filter areas.
+
+styling:
+  notes:
+    - Props like pressed, disabled, grouped, and size are the main styling API.
+    - Internal classes and CSS variables describe the current implementation and are most useful for debugging.
+  root_classes:
+    - .ui-v1-toggle-button
+  state_classes:
+    - .ui-v1-toggle-button_pressed
+    - .ui-v1-toggle-button_disabled
+    - .ui-v1-toggle-button_focused
+    - .ui-v1-toggle-button_grouped
+    - .ui-v1-toggle-button_lg
+    - .ui-v1-toggle-button_md
+    - .ui-v1-toggle-button_sm
+    - .ui-v1-toggle-button_xs
+  zones:
+    - .ui-v1-toggle-button__content
+    - .ui-v1-toggle-button__icon
+    - .ui-v1-toggle-button__text
+  css_variables:
+    internal_layout_variables:
+      - name: --ui-v1-toggle-button-height
+        effect: Current control height for the selected size.
+      - name: --ui-v1-toggle-button-min-width
+        effect: Minimum width for the current size.
+      - name: --ui-v1-toggle-button-padding-x
+        effect: Horizontal padding of the button content.
+      - name: --ui-v1-toggle-button-radius
+        effect: Border radius for standalone and grouped edge segments.
+      - name: --ui-v1-toggle-button-icon-size
+        effect: Size of normalized icon nodes.
+      - name: --ui-v1-toggle-button-content-gap
+        effect: Gap between icon and text.
+      - name: --ui-v1-toggle-button-focus-color
+        effect: Color of the box-shadow based focus ring.
+  typography:
+    size_variants:
+      - name: lg
+        mixin: h4-accent
+        size: 18px
+        line_height: 28px
+        weight: 500
+      - name: md
+        mixin: text-regular-accent
+        size: 16px
+        line_height: 24px
+        weight: 500
+      - name: sm
+        mixin: text-small-accent
+        size: 14px
+        line_height: 20px
+        weight: 500
+      - name: xs
+        mixin: text-tiny-accent
+        size: 12px
+        line_height: 14px
+        weight: 500
+
+behavior:
+  states:
+    - name: pressed
+      notes: Changes only the visual selected state; external code owns the actual model.
+    - name: disabled
+      notes: Disables interaction and applies disabled styling.
+    - name: grouped
+      notes: Enables segmented adjacency behavior for use in button rows and groups.
+    - name: focused
+      notes: Forces focus-ring styling for keyboard-managed composition scenarios.
+  notes:
+    - The component does not manage its own on or off state.
+    - Click handling and value updates are owned by the parent screen or group component.
+
+accessibility:
+  notes:
+    - The root is a native button.
+    - The component does not add toggle ARIA semantics automatically.
+    - For standalone toggle usage, the caller should provide the appropriate state attribute such as aria-pressed.
+    - In grouped multi-select composition, the caller may apply group-specific role and checked semantics.
+
+composition:
+  works_well_with:
+    - UiToggleGroup
+    - UiField
+    - compact filter bars
+  patterns:
+    - title: Standalone filter toggle
+      notes: Use one button with external pressed state for compact show or hide controls.
+    - title: Segmented multi-select primitive
+      notes: Use grouped buttons when composing a custom segmented row or when extending UiToggleGroup behavior.
+
+examples:
+  - title: Standalone pressed state
+    goal: Build a toggleable filter button.
+    code: |
+      <UiToggleButton
+        :pressed="filtersOpened"
+        :aria-pressed="filtersOpened"
+        @click="filtersOpened = !filtersOpened"
+      >
+        Filters
+      </UiToggleButton>
+
+ai_notes:
+  do:
+    - Treat pressed as a controlled visual state.
+    - Prefer UiToggleGroup when the task is multi-select segmented choice rather than a single primitive.
+    - Add explicit ARIA state when the button represents a semantic toggle.
+  avoid:
+    - Do not assume pressed updates automatically on click.
+    - Do not use UiToggleButton instead of UiButton for ordinary stateless actions.