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

package/docs/profiles/UiSelectOption.yml

@@ -0,0 +1,32 @@
+component: UiSelectOption
+summary: >
+  UiSelectOption is the base selectable child of UiSelect. It represents one option node
+  in the select option tree.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiSelectOption
+
+related_components:
+  - UiSelect
+  - UiSelectOptionGroup
+
+use_when:
+  - You need one option inside UiSelect.
+
+avoid_when:
+  - You need free layout content inside a select dropdown.
+
+api:
+  key_props:
+    - name: value
+    - name: label
+    - name: description
+    - name: disabled
+    - name: counter
+    - name: accent
+
+ai_notes:
+  do:
+    - Use as the default child node of UiSelect.

package/docs/profiles/UiSelectOptionGroup.yml

@@ -0,0 +1,26 @@
+component: UiSelectOptionGroup
+summary: >
+  UiSelectOptionGroup groups related UiSelectOption nodes under a shared label.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiSelectOptionGroup
+
+related_components:
+  - UiSelect
+  - UiSelectOption
+
+use_when:
+  - You need grouped select options.
+
+avoid_when:
+  - You only have a flat list of options.
+
+api:
+  key_props:
+    - name: label
+
+ai_notes:
+  do:
+    - Use to structure large option lists inside UiSelect.

package/docs/profiles/UiSlider.yml

@@ -0,0 +1,26 @@
+component: UiSlider
+summary: >
+  UiSlider is a range-selection control for single values or ranges on a numeric track.
+  It supports single-handle and range-handle modes.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiSlider
+
+use_when:
+  - You need compact ranged numeric selection.
+  - You need one or two draggable handles on a track.
+
+avoid_when:
+  - You need precise text entry.
+
+api:
+  key_props:
+    - name: type
+    - name: value
+    - name: min
+    - name: max
+    - name: labelled
+  emits:
+    - name: update:value

package/docs/profiles/UiSwitch.yml

@@ -0,0 +1,25 @@
+component: UiSwitch
+summary: >
+  UiSwitch is a compact boolean toggle control. It is the most concise choice for on or off state
+  when checkbox semantics would feel visually heavy.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiSwitch
+
+use_when:
+  - You need a compact on or off toggle.
+
+avoid_when:
+  - You need checkbox-group semantics.
+
+api:
+  key_props:
+    - name: value
+    - name: square
+    - name: disabled
+  methods:
+    - name: click
+    - name: focus
+    - name: blur

package/docs/profiles/UiTab.yml

@@ -0,0 +1,114 @@
+component: UiTab
+summary: >
+  UiTab is a declarative child node for UiTabGroup. It does not render meaningful
+  standalone UI by itself; instead, UiTabGroup consumes its props and slots to build
+  tab buttons, overflow menu items, and optional tab panel content.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiTab
+    - UiTabGroup
+
+related_components:
+  - UiTabGroup
+
+use_when:
+  - You need custom icon, label, counter, or content inside UiTabGroup.
+  - You want each tab declaration to keep its header and panel content together.
+
+avoid_when:
+  - You need a standalone button or link.
+  - A plain items array on UiTabGroup is enough for the screen.
+  - You need non-string tab identity, because UiTabGroup uses string id.
+
+api:
+  key_props:
+    - name: id
+      notes: Required string identifier used by UiTabGroup as activeId.
+    - name: label
+      notes: Fallback plain-text header label.
+    - name: counter
+      notes: Optional badge-like counter.
+    - name: disabled
+      notes: Marks the tab as non-interactive.
+  props:
+    - name: id
+      notes: Must be unique within one UiTabGroup.
+    - name: label
+      notes: Optional when label slot is used.
+    - name: counter
+      notes: Optional when counter slot is used.
+    - name: disabled
+      notes: Excluded from selection and keyboard navigation.
+  slots:
+    - name: icon
+      zone: tab leading icon
+      notes: Used both in the visible tab button and in the overflow menu item.
+    - name: label
+      zone: tab label
+      notes: Overrides plain label prop for the header.
+    - name: counter
+      zone: tab counter
+      notes: Overrides plain counter prop for the header.
+    - name: content
+      zone: active tab panel
+      notes: Rendered only for the active tab by UiTabGroup.
+
+rendered_structure:
+  descriptive_only: true
+  notes: >
+    UiTab is a structural declaration rather than a standalone DOM component. The
+    parent UiTabGroup resolves UiTab children and renders the actual tab buttons,
+    menu items, and optional tabpanel.
+
+geometry:
+  layout: no standalone layout, interpreted by UiTabGroup
+  notes:
+    - UiTab itself should not be used outside UiTabGroup.
+    - Icon-only tabs are inferred when icon exists but label and counter do not.
+
+behavior:
+  states:
+    - name: disabled
+      notes: The parent group keeps it visible but non-interactive.
+  notes:
+    - content slot is mounted only for the active tab.
+    - icon, label, and counter are also used when the tab moves into overflow menu.
+
+accessibility:
+  notes:
+    - UiTab does not create tab semantics by itself.
+    - UiTabGroup applies role=tab, aria-selected, aria-controls, and tabpanel relationships.
+
+composition:
+  works_well_with:
+    - UiTabGroup
+  patterns:
+    - title: Rich tab declaration
+      notes: Keep icon, counter, and content close to the tab declaration inside UiTabGroup.
+
+examples:
+  - title: Rich tab child
+    goal: Declare one tab with custom icon and panel content.
+    code: |
+      <UiTab id="overview" label="Overview" counter="8">
+        <template #icon>
+          <IconStar />
+        </template>
+
+        <template #content>
+          <section>
+            <h4>Overview</h4>
+            <p>Panel content for the active tab.</p>
+          </section>
+        </template>
+      </UiTab>
+
+ai_notes:
+  do:
+    - Use UiTab only inside UiTabGroup.
+    - Prefer label and counter props for simple cases, and slots for richer markup.
+  avoid:
+    - Do not expect UiTab to render useful DOM outside a group.
+    - Do not rely on an undocumented default slot for header rendering.

package/docs/profiles/UiTabGroup.yml

@@ -0,0 +1,233 @@
+component: UiTabGroup
+summary: >
+  UiTabGroup is the navigation container for UiTab children or simple tab items.
+  It manages active tab selection by string id, keyboard navigation, optional overflow
+  into a dropdown menu, and optional tabpanel rendering from the active UiTab content slot.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiTabGroup
+    - UiTab
+
+related_components:
+  - UiTab
+  - UiButton
+  - UiMenuItem
+
+use_when:
+  - You need horizontal navigation between a small or medium number of sections.
+  - Active state can be represented by a string id.
+  - You need overflow handling that moves extra tabs into a dropdown.
+  - You want optional panel content rendered from the active UiTab.
+
+avoid_when:
+  - You need free-form router navigation that should not behave like a tablist.
+  - You need non-string identity with custom equality logic.
+  - You need many options better served by a menu or select.
+
+api:
+  key_props:
+    - name: activeId
+      notes: Main selected-tab model by string id.
+    - name: items
+      notes: Simple array-based alternative to slot-declared UiTab children.
+    - name: appearance
+      notes: Supports text and filled visual styles.
+    - name: size
+      notes: Supports sm, md, lg.
+    - name: overflowing
+      notes: Enables overflow resolution into a dropdown menu.
+    - name: menuExpanded
+      notes: Optional controlled state for the overflow menu.
+    - name: focusableId
+      notes: Optional controlled state for roving focus.
+  props:
+    - name: activeId
+      notes: Usually used through v-model:active-id.
+    - name: items
+      notes: Expects array items shaped as { id, label?, counter?, disabled?, iconOnly? }.
+    - name: focusableId
+      notes: Advanced control hook; usually let the component manage it.
+    - name: menuExpanded
+      notes: Advanced control hook; usually let the component manage it.
+    - name: size
+      notes: Changes typography, icon size, and spacing.
+    - name: appearance
+      notes: text is classic tabs, filled is segmented-tab styling.
+    - name: overflowing
+      notes: When false, all tabs stay in the header row without overflow menu.
+  child_components:
+    - name: UiTab
+      key_props:
+        - id
+        - label
+        - counter
+        - disabled
+      notes: Use it when a tab needs icon, custom label, custom counter, or content slot.
+  slots:
+    - name: default
+      zone: tab declarations
+      creates: Slot-based tab registry via UiTab children.
+      accepts:
+        recommended:
+          - UiTab
+        avoid:
+          - arbitrary buttons
+          - unrelated layout wrappers
+      notes: >
+        Use items for simple data-driven tabs, and default slot with UiTab for richer
+        headers or tabpanel content.
+  emits:
+    - name: change
+      payload: string
+      notes: Fired when the active tab changes.
+    - name: update:activeId
+      payload: string
+      notes: Main v-model channel.
+    - name: update:focusableId
+      payload: string | null
+      notes: Optional roving-focus control channel.
+    - name: update:menuExpanded
+      payload: boolean
+      notes: Optional overflow-menu visibility control channel.
+    - name: layout
+      payload: "{ headIds: string[]; menuIds: string[] }"
+      notes: Emits the current overflow split between visible tabs and menu tabs.
+
+rendered_structure:
+  descriptive_only: true
+  notes: >
+    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.
+  composition:
+    - .ui-v1-tab-group root
+    - .ui-v1-tab-group__head with role=tablist region
+    - .ui-v1-tab-group__content for visible tabs
+    - .ui-v1-tab-group__measure hidden sizing layer
+    - .ui-v1-tab-group__trigger for overflow button
+    - .ui-v1-tab-group__menu inside UiPopper
+    - .ui-v1-tab-group__panel for active tabpanel content
+  classes:
+    - .ui-v1-tab-group
+    - .ui-v1-tab-group_text
+    - .ui-v1-tab-group_filled
+    - .ui-v1-tab
+    - .ui-v1-tab_active
+    - .ui-v1-tab_disabled
+
+geometry:
+  layout: block-level group with full-width header and optional content panel
+  notes:
+    - The group itself stretches to width 100%.
+    - The visible header keeps tabs on one row.
+    - overflowing lets extra tabs move into a dropdown instead of wrapping.
+    - The active panel sits below the tab header.
+
+styling:
+  notes:
+    - Prefer appearance and size props over selector overrides.
+    - Current classes help explain state and overflow structure.
+  root_classes:
+    - .ui-v1-tab-group
+    - .ui-v1-tab
+  state_classes:
+    - .ui-v1-tab-group_text
+    - .ui-v1-tab-group_filled
+    - .ui-v1-tab_active
+    - .ui-v1-tab_disabled
+    - .ui-v1-tab_icon-without-text
+  zones:
+    - .ui-v1-tab-group__head
+    - .ui-v1-tab-group__content
+    - .ui-v1-tab-group__measure
+    - .ui-v1-tab-group__trigger
+    - .ui-v1-tab-group__menu
+    - .ui-v1-tab-group__panel
+    - .ui-v1-tab__icon
+    - .ui-v1-tab__label
+    - .ui-v1-tab__counter
+  typography:
+    default:
+      notes:
+        - text appearance uses tab-specific typography that depends on size.
+        - lg uses heading-scale typography and larger icon sizing.
+
+behavior:
+  states:
+    - name: overflowing
+      notes: Enables moving extra tabs into a dropdown menu.
+    - name: appearance=text
+      notes: Classic underline tabs.
+    - name: appearance=filled
+      notes: Filled segmented-tab look with zero gap between tabs.
+    - name: disabled tab
+      notes: Visible but not interactive and excluded from keyboard navigation.
+  selection_and_layout:
+    - activeId is resolved only against existing tab ids.
+    - When overflowing is enabled, the active tab tries to remain in the visible header.
+    - layout reports which ids stay in the header and which move into the menu.
+    - menuExpanded and focusableId can be controlled from outside but usually do not need to be.
+  keyboard:
+    - One tab stop is used for the whole visible tablist.
+    - Arrow keys move focus and selection across enabled visible tabs.
+    - Home and End jump to the first or last enabled visible tab.
+    - Space and Enter activate the focused tab.
+    - Overflow menu items use menuitemradio semantics and activate on click, Enter, or Space.
+
+accessibility:
+  notes:
+    - The visible header uses tablist and tab roles.
+    - The active tab can be linked to its content through aria-controls and aria-labelledby.
+    - The content container uses role=tabpanel when active UiTab provides content slot.
+    - Overflow menu items use role=menuitemradio and aria-checked.
+
+composition:
+  works_well_with:
+    - UiTab
+  patterns:
+    - title: Simple tabs from items
+      notes: Use items when tabs are data-only and do not need per-tab content slots.
+    - title: Rich tabs from UiTab
+      notes: Use UiTab children when tabs need icon, custom label, counter, or tabpanel content.
+
+examples:
+  - title: Data-driven tabs
+    goal: Render a compact tab header from plain items.
+    code: |
+      <UiTabGroup
+        v-model:active-id="activeId"
+        :items="[
+          { id: 'overview', label: 'Overview', counter: '8' },
+          { id: 'orders', label: 'Orders', counter: '12' },
+        ]"
+        overflowing
+      />
+  - title: Tabs with panel content
+    goal: Render active tabpanel content from UiTab child declarations.
+    code: |
+      <UiTabGroup
+        v-model:active-id="activeId"
+        overflowing
+      >
+        <UiTab id="overview" label="Overview">
+          <template #content>
+            <section>
+              <h4>Overview</h4>
+              <p>Visible only when this tab is active.</p>
+            </section>
+          </template>
+        </UiTab>
+
+        <UiTab id="orders" label="Orders" />
+      </UiTabGroup>
+
+ai_notes:
+  do:
+    - Use v-model:active-id with string ids.
+    - Prefer items for simple tabs and UiTab children for rich composition.
+    - Treat menuExpanded and focusableId as advanced controlled props, not default requirements.
+  avoid:
+    - Do not pass object values or expect equalsFn-like behavior.
+    - Do not rely on internal overflow DOM structure as a stable extension contract.

package/docs/profiles/UiTable.yml

@@ -0,0 +1,148 @@
+component: UiTable
+summary: >
+  UiTable is the main data table component. It supports row rendering, grouping, expandable rows,
+  footer areas, and row-level interactions.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiTable
+
+related_components:
+  - UiTableColumn
+
+use_when:
+  - You need structured tabular data.
+  - You need group headers, expandable rows, or footer sections.
+
+avoid_when:
+  - You need a simple list or card layout.
+
+api:
+  key_props:
+    - name: rows
+    - name: rowKey
+    - name: headless
+    - name: bordered
+    - name: fixed
+    - name: groupBy
+  slots:
+    - name: default
+      zone: columns
+      creates: Column declarations.
+    - name: expand
+      zone: expanded-row
+      creates: Expanded row content.
+    - name: footer
+      zone: footer
+      creates: Full footer area.
+    - name: group-head
+      zone: group-head
+      creates: Group heading content.
+    - name: empty
+      zone: empty-state
+      creates: Empty-state content.
+  emits:
+    - name: row:click
+  methods:
+    - name: resetExpanded
+    - name: expand
+    - name: collapse
+    - name: toggle
+
+rendered_structure:
+  descriptive_only: true
+  root: .ui-v1-table
+  zones:
+    - .ui-v1-table__section_head
+    - .ui-v1-table__section_body
+    - .ui-v1-table__section_foot
+    - .ui-v1-table__row
+    - .ui-v1-table__head-cell
+    - .ui-v1-table__body-cell
+  notes: >
+    Table layout is distributed across head, body, foot, and cell-level classes. Treat this as a
+    reasoning model for geometry and spacing, not as a stable selector contract.
+
+geometry:
+  layout: block-width table
+  width: 100%
+  notes:
+    - Root fills available width.
+    - fixed=true switches table-layout from auto to fixed.
+    - bordered=true adds border and corner rounding through CSS variables.
+
+styling:
+  notes:
+    - UiTable exposes a relatively rich CSS-variable surface for spacing and table chrome.
+    - Prefer table props and slot composition first, then CSS variables for spacing or background tuning.
+    - Internal classes are descriptive and mainly useful for debugging or narrow local integration.
+  root_classes:
+    - .ui-v1-table
+  state_classes:
+    - .ui-v1-table_fixed
+    - .ui-v1-table_bordered
+    - .ui-v1-table__head-cell_align-center
+    - .ui-v1-table__head-cell_align-right
+    - .ui-v1-table__body-cell_align-center
+    - .ui-v1-table__body-cell_align-right
+    - .ui-v1-table__body-cell_valign-top
+    - .ui-v1-table__body-cell_valign-bottom
+    - .ui-v1-table__body-cell_theme-group
+    - .ui-v1-table__body-cell_trim
+    - .ui-v1-table__head-cell_trim
+  zones:
+    - .ui-v1-table__head-cell
+    - .ui-v1-table__body-cell
+    - .ui-v1-table__footer-cell
+  css_variables:
+    public_theme_variables:
+      - name: --ui-v1-table-border-width
+        effect: Outer border width in bordered mode.
+      - name: --ui-v1-table-rounding
+        effect: Shared corner rounding.
+      - name: --ui-v1-table-cell-padding-x
+        effect: Base inline cell padding.
+      - name: --ui-v1-table-cell-padding-y
+        effect: Base block cell padding.
+      - name: --ui-v1-table-head-background
+        effect: Header row background.
+      - name: --ui-v1-table-group-head-background
+        effect: Group heading row background.
+      - name: --ui-v1-table-padding-start
+        effect: Effective first-column start padding.
+      - name: --ui-v1-table-padding-end
+        effect: Effective last-column end padding.
+    internal_layout_variables:
+      - name: --ui-v1-table-effective-padding-start
+        effect: Start padding after bordered adjustments.
+      - name: --ui-v1-table-effective-padding-end
+        effect: End padding after bordered adjustments.
+      - name: --ui-v1-table-head-cell-padding-block-start
+        effect: Header top padding.
+      - name: --ui-v1-table-head-cell-padding-block-end
+        effect: Header bottom padding.
+      - name: --ui-v1-table-body-cell-padding-block-start
+        effect: Body top padding.
+      - name: --ui-v1-table-body-cell-padding-block-end
+        effect: Body bottom padding.
+      - name: --ui-v1-table-group-head-padding-block-start
+        effect: Group row top padding.
+      - name: --ui-v1-table-group-head-padding-block-end
+        effect: Group row bottom padding.
+  typography:
+    default:
+      mixin: text-small
+      size: 14px
+      line_height: 20px
+      weight: 400
+    head_cells:
+      mixin: text-tiny-accent
+      size: 12px
+      line_height: 14px
+      weight: 500
+    group_rows:
+      mixin: text-tiny
+      size: 12px
+      line_height: 14px
+      weight: 400

package/docs/profiles/UiTableBodyCell.yml

@@ -0,0 +1,35 @@
+component: UiTableBodyCell
+summary: >
+  UiTableBodyCell is the low-level body cell primitive used inside UiTable rows.
+  Use it only for custom table layouts built from public table parts.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiTableBodyCell
+
+related_components:
+  - UiTable
+
+use_when:
+  - You compose custom body rows with public table primitives.
+  - You need explicit align, valign, colspan, rowspan, or grouped-cell theme control.
+
+avoid_when:
+  - UiTableColumn already covers the body-cell rendering you need.
+  - You are not inside table row structure.
+
+api:
+  key_props:
+    - name: align
+    - name: valign
+    - name: colspan
+    - name: rowspan
+    - name: trim
+    - name: theme
+
+ai_notes:
+  do:
+    - Keep it inside UiTable row composition.
+  avoid:
+    - Do not use it as a generic box or layout wrapper.

package/docs/profiles/UiTableColumn.yml

@@ -0,0 +1,38 @@
+component: UiTableColumn
+summary: >
+  UiTableColumn declares one logical column inside UiTable. It carries label and sizing metadata
+  and defines how header labels and cells render.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiTableColumn
+
+related_components:
+  - UiTable
+
+use_when:
+  - You define columns for UiTable.
+
+avoid_when:
+  - You need standalone layout markup outside UiTable.
+
+api:
+  key_props:
+    - name: label
+    - name: width
+    - name: minWidth
+    - name: maxWidth
+    - name: align
+    - name: valign
+    - name: trim
+  slots:
+    - name: default
+      zone: cell
+      creates: Cell content.
+    - name: cell
+      zone: cell
+      creates: Explicit cell content.
+    - name: label
+      zone: header-label
+      creates: Header label content.