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

package/docs/COMPONENTS.md

@@ -16,6 +16,8 @@ Detailed AI-friendly profiles are collected in [`PROFILES.md`](./PROFILES.md).
 - [`UiRadio`](./profiles/UiRadio.yml): single choice
 - [`UiRadioSwitch`](./profiles/UiRadioSwitch.yml): segmented single-choice switch with inline or section-card appearance
 - [`UiRadioSwitchOption`](./profiles/UiRadioSwitchOption.yml): rich option child for UiRadioSwitch
+- [`UiToggleGroup`](./profiles/UiToggleGroup.yml): segmented multi-select group built from toggle buttons
+- [`UiToggleGroupOption`](./profiles/UiToggleGroupOption.yml): rich option child for UiToggleGroup
 - [`UiSwitch`](./profiles/UiSwitch.yml): state toggle
 - [`UiSlider`](./profiles/UiSlider.yml): ranged value selection
 - [`UiSelect`](./profiles/UiSelect.yml): select container for single or multiple choice
@@ -29,6 +31,7 @@ Detailed AI-friendly profiles are collected in [`PROFILES.md`](./PROFILES.md).
 ## Actions And Navigation
 
 - [`UiButton`](./profiles/UiButton.yml): main action button that can render as a button or anchor
+- [`UiToggleButton`](./profiles/UiToggleButton.yml): stateful toggle button primitive for standalone or grouped use
 - [`UiAddButton`](./profiles/UiAddButton.yml): add action button
 - [`UiCopyButton`](./profiles/UiCopyButton.yml): copy value action
 - [`UiToolbarButton`](./profiles/UiToolbarButton.yml): toolbar button

package/docs/FORMAT.md

@@ -52,6 +52,17 @@ api:
     - name: update:value
       payload: unknown
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-component
+    tag: div
+
+geometry:
+  layout: block-like root
+  root_display: block
+  width_behavior: stretches to container width by default
+
 styling:
   root_classes:
     - .ui-v1-component
@@ -140,6 +151,7 @@ Inside `api`, it is useful to distinguish:
 Describe the actual rendered shape:
 
 - the root container;
+- the actual root tag or tags when they matter, for example `button`, `a`, `div`, or `span`;
 - the main internal zones;
 - where label, control, action area, icon area, popper content, and similar parts live;
 - current root classes and state classes, if they help reasoning.
@@ -155,10 +167,17 @@ Important:
 Capture:
 
 - whether the component is block-like or inline-like;
+- what the root behaves like in layout terms, for example `block`, `inline-block`, `inline-flex`, or `flex`;
 - what stretches to `width: 100%` and what stays content-sized;
 - how the component behaves in a row, grid, header, or popper;
 - which props affect dimensions: `size`, `multiline`, `autofit`, `popperFitTrigger`, and so on.
 
+Useful optional fields:
+
+- `root_display` for the root display mode or the common display modes when the root changes by props;
+- `width_behavior` for whether the component stretches, shrinks to content, or switches between those modes;
+- `notes` for short practical remarks about how the root behaves in layout and composition.
+
 ## 8. `styling`
 
 Capture only the styling data that helps an agent make safe decisions:

package/docs/PROFILES.md

@@ -36,6 +36,8 @@ Current high-signal core profiles:
 - [`UiField`](./profiles/UiField.yml)
 - [`UiTextbox`](./profiles/UiTextbox.yml)
 - [`UiButton`](./profiles/UiButton.yml)
+- [`UiToggleButton`](./profiles/UiToggleButton.yml)
+- [`UiToggleGroup`](./profiles/UiToggleGroup.yml)
 - [`UiPageHeader`](./profiles/UiPageHeader.yml)
 - [`UiSelect`](./profiles/UiSelect.yml)
 - [`UiRadioSwitch`](./profiles/UiRadioSwitch.yml)

package/docs/profiles/UiAddButton.yml

@@ -34,6 +34,18 @@ api:
       zone: secondary-copy
       creates: Optional secondary description near the main label.
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: button.ui-v1-add-button
+    tag: button
+  notes: Current root is a single action button with optional icon and description zones.
+
+geometry:
+  layout: button-like action root
+  root_display: flex
+  width_behavior: content-sized by default
+
 behavior:
   notes:
     - Behaves like a clickable add action with standard button focus and click semantics.

package/docs/profiles/UiAlert.yml

@@ -24,6 +24,18 @@ api:
     - name: closable
     - name: fluid
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-alert
+    tag: div
+  notes: Current alert body is wrapped in UiTransition and uses one flex row for icon, content, and optional closer.
+
+geometry:
+  layout: block-like feedback row
+  root_display: flex
+  width_behavior: stretches to container width by default
+
 behavior:
   notes:
     - shown controls visibility.

package/docs/profiles/UiAvatar.yml

@@ -24,6 +24,18 @@ api:
     - name: size
     - name: href
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-avatar or a.ui-v1-avatar
+    tag: div or a
+  notes: The root switches to anchor when href is provided.
+
+geometry:
+  layout: avatar frame
+  root_display: inline-block
+  width_behavior: content-sized by size
+
 behavior:
   notes:
     - Can render linked avatar behavior when href is provided.

package/docs/profiles/UiAvatarList.yml

@@ -23,6 +23,18 @@ api:
     - name: avatars
     - name: size
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-avatar-list
+    tag: div
+  notes: Renders one wrapper around a compact row of avatars.
+
+geometry:
+  layout: inline avatar row
+  root_display: flex
+  width_behavior: content-sized by default
+
 ai_notes:
   do:
     - Use for compact grouped identity display.

package/docs/profiles/UiButton.yml

@@ -83,7 +83,9 @@ rendered_structure:
     This internal DOM description is useful for reasoning, not for styling against implementation details.
   root:
     button_shape: button.ui-v1-button
+    button_tag: button
     link_shape: a.ui-v1-button
+    link_tag: a
   zones:
     - .ui-v1-button__content
     - text span
@@ -95,7 +97,13 @@ rendered_structure:
 
 geometry:
   layout: inline-block
+  root_display:
+    default_button: inline-block
+    default_link: inline-block
+  width_behavior: content-sized by default
   notes:
+    - Fits naturally into inline rows and action strips.
+    - Does not behave like a full-width block unless constrained by the parent layout.
     - Size controls dimensions and internal paddings.
     - Icon-only content leads to a square-like layout through state classes.
     - The component fits naturally into inline rows, header actions, and compact action zones.

package/docs/profiles/UiCalendar.yml

@@ -24,6 +24,18 @@ api:
     - name: maxDate
     - name: locale
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-calendar
+    tag: div
+  notes: The root contains header controls, weekday labels, and the date grid.
+
+geometry:
+  layout: block-like calendar panel
+  root_display: flex
+  width_behavior: stretches to container width by default
+
 behavior:
   notes:
     - Supports single and range selection.

package/docs/profiles/UiCheckbox.yml

@@ -29,6 +29,18 @@ api:
     - name: focus
     - name: blur
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: span.ui-v1-checkbox
+    tag: span
+  notes: One inline wrapper around the visual checkbox control and label content.
+
+geometry:
+  layout: inline checkbox control
+  root_display: inline-flex
+  width_behavior: content-sized by default
+
 behavior:
   notes:
     - model plus value supports group-style selection.

package/docs/profiles/UiCollapse.yml

@@ -21,6 +21,18 @@ api:
     - name: collapseBehaviour
     - name: duration
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-collapse
+    tag: div
+  notes: The animated container is wrapped in a native transition and exists only while shown or expanded.
+
+geometry:
+  layout: block-like animated container
+  root_display: block
+  width_behavior: stretches to container width by default
+
 ai_notes:
   do:
     - Use UiCollapse as a primitive for expandable content regions.

package/docs/profiles/UiCollapseBox.yml

@@ -28,6 +28,18 @@ api:
     - name: disabled
     - name: color
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: section.ui-v1-collapse-box
+    tag: section
+  notes: Renders one section root with a header button and a collapsible body region.
+
+geometry:
+  layout: block-like collapsible section
+  root_display: flex
+  width_behavior: stretches to container width by default
+
 behavior:
   notes:
     - Supports controlled expanded state and grouped interaction.

package/docs/profiles/UiCollapseGroup.yml

@@ -22,6 +22,18 @@ api:
   key_props:
     - name: activeBoxId
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div
+    tag: div
+  notes: Current implementation is an unstyled wrapper that coordinates child UiCollapseBox nodes.
+
+geometry:
+  layout: block wrapper for stacked collapse boxes
+  root_display: block
+  width_behavior: stretches to container width by default
+
 ai_notes:
   do:
     - Use with UiCollapseBox when grouped expansion matters.

package/docs/profiles/UiCopyButton.yml

@@ -35,6 +35,18 @@ api:
       zone: tooltip
       creates: Tooltip content after copy succeeds.
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-copy-button
+    tag: div
+  notes: The root wraps the trigger, tooltip, and fallback input for clipboard support.
+
+geometry:
+  layout: inline trigger wrapper
+  root_display: inline-block
+  width_behavior: content-sized by default
+
 ai_notes:
   do:
     - Use for copy-specific flows instead of recreating copy state manually.

package/docs/profiles/UiDate.yml

@@ -21,6 +21,18 @@ api:
     - name: withTime
     - name: locale
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: time
+    tag: time
+  notes: Renders one semantic time element with formatted date text.
+
+geometry:
+  layout: inline date text
+  root_display: inline
+  width_behavior: content-sized by content
+
 ai_notes:
   do:
     - Use UiDate for formatted output and UiDatePicker for input.

package/docs/profiles/UiDatePicker.yml

@@ -35,6 +35,18 @@ api:
     - name: close
     - name: toggle
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: span.ui-v1-date-picker
+    tag: span
+  notes: The visible trigger behaves like an inline date control that opens a floating calendar.
+
+geometry:
+  layout: inline date input trigger
+  root_display: inline-block
+  width_behavior: content-sized by default
+
 behavior:
   notes:
     - Supports single-date and range flows.

package/docs/profiles/UiError.yml

@@ -15,6 +15,18 @@ use_when:
 avoid_when:
   - You need a richer feedback block, use UiAlert or UiInfobox instead.
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-error
+    tag: div
+  notes: Renders one text container for error content.
+
+geometry:
+  layout: block-like error text container
+  root_display: block
+  width_behavior: stretches to container width by default
+
 ai_notes:
   do:
     - Use for compact error presentation.

package/docs/profiles/UiField.yml

@@ -116,7 +116,9 @@ rendered_structure:
   descriptive_only: true
   notes: >
     This is a debugging and reasoning model, not a public styling contract.
-  root: .ui-v1-field
+  root:
+    shape: div.ui-v1-field
+    tag: div
   zones:
     - .ui-v1-field__headline
     - .ui-v1-field__label
@@ -126,8 +128,10 @@ rendered_structure:
 
 geometry:
   layout: grid
+  root_display: grid
   width: 100%
   min_width: 0
+  width_behavior: stretches to container width by default
   notes:
     - Root uses grid with a 4px gap.
     - The headline is a flex row.

package/docs/profiles/UiImage.yml

@@ -22,6 +22,18 @@ api:
     - name: resize
     - name: crop
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: img
+    tag: img
+  notes: The component renders a single image element.
+
+geometry:
+  layout: replaced media element
+  root_display: inline-block
+  width_behavior: intrinsic by image source or explicit dimensions
+
 ai_notes:
   do:
     - Use UiImage for general media and UiAvatar for people or identity.

package/docs/profiles/UiInfobox.yml

@@ -28,6 +28,18 @@ api:
     - name: hide
     - name: toggle
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-infobox
+    tag: div
+  notes: The visible infobox body is wrapped in UiTransition and uses one flex row for media, content, and optional closer.
+
+geometry:
+  layout: block-like message panel
+  root_display: flex
+  width_behavior: stretches to container width by default
+
 ai_notes:
   do:
     - Use UiInfobox for richer guidance blocks, not tiny alerts.

package/docs/profiles/UiLink.yml

@@ -32,6 +32,18 @@ api:
     - name: focus
     - name: blur
 
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: a.ui-v1-link
+    tag: a
+  notes: The root is one anchor element with inline icon and text zones.
+
+geometry:
+  layout: inline link root
+  root_display: inline-flex
+  width_behavior: content-sized by default
+
 ai_notes:
   do:
     - Use UiLink for real link semantics and inline navigation.

package/docs/profiles/UiLoader.yml

@@ -21,6 +21,18 @@ api:
     - 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

@@ -40,6 +40,18 @@ api:
       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

@@ -33,6 +33,18 @@ api:
       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

@@ -24,6 +24,18 @@ api:
     - 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.

package/docs/profiles/UiModalWindow.yml

@@ -30,3 +30,15 @@ api:
   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

@@ -27,3 +27,15 @@ api:
     - 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

@@ -34,6 +34,18 @@ api:
     - 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.

package/docs/profiles/UiPageHeader.yml

@@ -106,7 +106,9 @@ 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
+  root:
+    shape: div.ui-v1-page-header
+    tag: div
   zones:
     - .ui-v1-page-header__main
     - .ui-v1-page-header__title
@@ -120,6 +122,8 @@ rendered_structure:
 
 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.

package/docs/profiles/UiPopper.yml

@@ -94,7 +94,9 @@ api:
 
 rendered_structure:
   descriptive_only: true
-  root: .ui-v1-popper
+  root:
+    shape: div.ui-v1-popper
+    tag: div
   zones:
     - .ui-v1-popper__arrow when withArrow=true
     - .ui-v1-popper__content
@@ -102,6 +104,8 @@ rendered_structure:
 
 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.

package/docs/profiles/UiPopperConnector.yml

@@ -43,10 +43,16 @@ api:
 
 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.

package/docs/profiles/UiPopperTarget.yml

@@ -46,11 +46,17 @@ api:
 
 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.

package/docs/profiles/UiRadio.yml

@@ -24,3 +24,15 @@ api:
     - 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