@retailcrm/embed-ui-v1-components 0.9.19 → 0.9.22-alpha.1

package/docs/profiles/components/UiTableColumn.yml

@@ -0,0 +1,87 @@
+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.
+
+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
+
+composition:
+  works_well_with:
+    - UiTable
+    - UiTableSorter
+    - UiLink
+    - UiTag
+  patterns:
+    - title: Primary link column
+      notes: Put the row's main UiLink in the first meaningful text column and set link size to small.
+    - title: Sortable header
+      notes: Use the label slot with UiTableSorter when the column supports sorting.
+    - title: Status column
+      notes: Use UiTag for categorical statuses instead of raw colored text.
+
+ai_notes:
+  do:
+    - Set minWidth for important text columns so generated tables remain scannable.
+    - Use align="right" for numbers, money, and percentages.
+    - Use trim only for narrow checkbox, icon, or action columns.
+  avoid:
+    - Do not place filters inside column labels; filters belong above the table.
+
+behavior:
+  notes:
+    - Behavior is mostly coordinated by the parent component.
+    - Use this child only in the documented parent composition.
+
+accessibility:
+  notes:
+    - This component is normally used inside its parent composition; accessibility behavior is completed by the parent component.
+    - Keep labels and visible text meaningful because parent keyboard and screen-reader behavior depends on child content.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.

package/docs/profiles/components/UiTableFooterButton.yml

@@ -0,0 +1,85 @@
+component: UiTableFooterButton
+summary: >
+  UiTableFooterButton is a footer-scoped action control for custom table footer layouts.
+  It behaves like a table-specific button primitive rather than a full replacement for UiButton.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiTableFooterButton
+
+related_components:
+  - UiTable
+  - UiTableFooterSection
+
+use_when:
+  - You need an action inside a custom table footer area.
+
+avoid_when:
+  - UiButton is enough outside table footer composition.
+  - You are not building custom footer structure.
+
+api:
+  key_props:
+    - name: type
+  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.
+    - Use for page-size, pagination, export, and compact table-scoped footer actions.
+  avoid:
+    - Do not substitute it for general page-level actions.
+
+composition:
+  works_well_with:
+    - UiTableFooterSection
+    - UiTable
+  patterns:
+    - title: Pagination control
+      notes: Use inside footer-pagination slot for previous, next, and page controls.
+      states:
+        - name: ordinary-page
+          notes: Render the page number as UiTableFooterButton text.
+        - name: current-page
+          notes: Mark the active page with a local custom class and style it inside the table example scope.
+        - name: arrow
+          notes: Render the previous/next chevron icon inside UiTableFooterButton and provide an aria-label.
+        - name: passive-or-disabled
+          notes: Use disabled when the control is unavailable; use a local custom class only for visual passive states such as selected page size.
+    - title: Page-size control
+      notes: Use inside footer-page-size slot for compact page-size choices.
+
+behavior:
+  notes:
+    - Behavior is mostly coordinated by the parent component.
+    - Use this child only in the documented parent composition.
+
+accessibility:
+  notes:
+    - This component is normally used inside its parent composition; accessibility behavior is completed by the parent component.
+    - Keep labels and visible text meaningful because parent keyboard and screen-reader behavior depends on child content.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - For footer pagination, style local custom classes on UiTableFooterButton instead of replacing it with UiButton.
+    - For page buttons, use a 36px square target with 4px radius, 14px text, black ordinary page color, and blue active background.
+    - For arrow buttons, use a 36px square target with a 24px chevron icon and grey color.
+    - Combine selectors like `.entity-list-table .ui-v1-table__footer-button.entity-list-table__pagination-button_current` when overriding active states, because base footer button styles set link-like colors.
+  root_classes:
+    - .ui-v1-table

package/docs/profiles/components/UiTableFooterSection.yml

@@ -0,0 +1,73 @@
+component: UiTableFooterSection
+summary: >
+  UiTableFooterSection is the low-level footer container for custom table footer layouts.
+  It is mainly useful when UiTable footer slots are not enough on their own.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiTableFooterSection
+
+related_components:
+  - UiTable
+  - UiTableFooterButton
+
+use_when:
+  - You compose custom footer content from public table primitives.
+
+avoid_when:
+  - UiTable footer slots already solve the layout.
+  - You do not need explicit footer structure.
+
+api:
+  slots:
+    - name: default
+      zone: footer-section-content
+      creates: Compact footer controls or metadata.
+
+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.
+    - Keep content compact and table-scoped.
+    - Add local CSS on the table root for footer row height, background, typography, and pagination spacing when recreating the reference footer.
+  avoid:
+    - Do not treat it as a standalone layout section.
+
+composition:
+  works_well_with:
+    - UiTable
+    - UiTableFooterButton
+  patterns:
+    - title: Structured table footer
+      notes: Use in footer-page-size, footer-export, and footer-pagination slots to match table footer spacing.
+
+behavior:
+  notes:
+    - Behavior is mostly coordinated by the parent component.
+    - Use this child only in the documented parent composition.
+
+accessibility:
+  notes:
+    - This component is normally used inside its parent composition; accessibility behavior is completed by the parent component.
+    - Keep labels and visible text meaningful because parent keyboard and screen-reader behavior depends on child content.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - For reference-style footer controls, apply a local class to each UiTableFooterSection and style it through the UiTable root class.
+    - The pagination section usually needs padding-block 8px and an inner flex group with 8px gaps.
+  root_classes:
+    - .ui-v1-table

package/docs/profiles/{UiTableHeadCell.yml → components/UiTableHeadCell.yml}

@@ -40,5 +40,31 @@ geometry:
 ai_notes:
   do:
     - Prefer UiTableColumn first for regular table headers.
+    - Use with UiTableSorter when building fully custom table structure.
   avoid:
     - Do not use it as a generic container outside table head rows.
+
+composition:
+  works_well_with:
+    - UiTableSorter
+    - UiTableColumn
+  patterns:
+    - title: Low-level sortable head
+      notes: Use only when UiTableColumn label slot cannot express the needed header.
+
+behavior:
+  notes:
+    - Behavior is mostly coordinated by the parent component.
+    - Use this child only in the documented parent composition.
+
+accessibility:
+  notes:
+    - This component is normally used inside its parent composition; accessibility behavior is completed by the parent component.
+    - Keep labels and visible text meaningful because parent keyboard and screen-reader behavior depends on child content.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+  root_classes:
+    - .ui-v1-table

package/docs/profiles/{UiTableSorter.yml → components/UiTableSorter.yml}

@@ -41,5 +41,32 @@ geometry:
 ai_notes:
   do:
     - Pair it with explicit sort state in screen logic.
+    - Persist sort key and direction in URL query parameters when the table is routable.
+    - Reset the current page to 1 when sorting changes.
   avoid:
     - Do not use it as a generic icon-only control outside table headers.
+
+composition:
+  works_well_with:
+    - UiTableColumn
+    - UiTableHeadCell
+  patterns:
+    - title: Column label slot
+      notes: Place in UiTableColumn label slot for normal sortable columns.
+
+behavior:
+  notes:
+    - Behavior is mostly coordinated by the parent component.
+    - Use this child only in the documented parent composition.
+
+accessibility:
+  notes:
+    - This component is normally used inside its parent composition; accessibility behavior is completed by the parent component.
+    - Keep labels and visible text meaningful because parent keyboard and screen-reader behavior depends on child content.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+  root_classes:
+    - .ui-v1-table

package/docs/profiles/components/UiTag.yml

@@ -0,0 +1,90 @@
+component: UiTag
+summary: >
+  UiTag is a compact label or status pill. It can be interactive, removable, pinned, or visually saturated.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiTag
+
+examples:
+  - title: Slots
+    code: |
+      <template>
+          <UiTag background="#FEA530" saturated>
+              VIP
+          </UiTag>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiTag } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
+use_when:
+  - You need a short status or label pill.
+  - You need removable or interactive tags.
+
+avoid_when:
+  - You need a full button or link.
+
+api:
+  key_props:
+    - name: size
+    - name: pinned
+    - name: removable
+    - name: interactive
+    - name: saturated
+    - name: background
+  emits:
+    - name: click
+    - 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
+
+behavior:
+  notes:
+    - interactive makes the tag feel actionable; use it only when click handling exists.
+    - removable should emit remove and needs a clear removal consequence.
+    - background is useful for semantic status palettes, but keep contrast readable.
+
+composition:
+  works_well_with:
+    - UiTable
+    - UiSelectOption
+    - UiMenuItem
+  patterns:
+    - title: Table status
+      notes: Use in UiTable cells for categorical states instead of raw colored text.
+    - title: Removable filter chip
+      notes: Use removable tags to show active filters when space allows.
+
+ai_notes:
+  do:
+    - Use for short statuses, categories, and active filter chips.
+    - Keep labels concise; tags should scan quickly.
+  avoid:
+    - Do not use as a full command button or as long explanatory text.
+
+accessibility:
+  notes:
+    - Keep rendered text concise and meaningful for screen-reader users.
+    - Do not use this component as the only carrier of critical state if the state also needs form-level validation or focus management.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+  root_classes:
+    - .ui-v1-tag-wrapper

package/docs/profiles/{UiTextbox.yml → components/UiTextbox.yml}

@@ -13,6 +13,26 @@ related_components:
   - UiPageHeader
   - UiSelect
 
+examples:
+  - title: Slots
+    code: |
+      <template>
+          <UiTextbox v-model:value="term">
+              <template #leading-icon>
+                  <IconSearch aria-hidden="true" />
+              </template>
+          </UiTextbox>
+      </template>
+
+      <script lang="ts" setup>
+      import IconSearch from '@retailcrm/embed-ui-v1-components/assets/sprites/actions/search.svg'
+      import { UiTextbox } from '@retailcrm/embed-ui-v1-components/remote'
+
+      import { ref } from 'vue'
+
+      const term = ref('')
+      </script>
+
 use_when:
   - You need a standard text input.
   - You need search, email, phone, url, or password input.
@@ -346,38 +366,6 @@ composition:
     - title: Inline control
       notes: Use UiTextbox as a self-contained control, not as a wrapper for arbitrary content.
 
-examples:
-  - title: Field wiring
-    goal: Build a standard text field with correct ARIA wiring.
-    code: |
-      <UiField id="name" label="Name">
-        <template #default="field">
-          <UiTextbox
-            :id="field.id"
-            :input-attributes="{
-              'aria-labelledby': field.ariaLabelledby,
-              'aria-invalid': field.ariaInvalid,
-            }"
-            v-model:value="name"
-          />
-        </template>
-      </UiField>
-  - title: Search pattern
-    goal: Build a textbox with a leading icon and clear action.
-    code: |
-      <UiTextbox v-model:value="term" clearable>
-        <template #leading-icon>
-          <IconSearch aria-hidden="true" />
-        </template>
-      </UiTextbox>
-  - title: Prefix and suffix zones
-    goal: Show safe markup for prefix and suffix content.
-    code: |
-      <UiTextbox v-model:value="amount" inputmode="decimal" suffix="₽">
-        <template #prefix>
-          <span>Amount</span>
-        </template>
-      </UiTextbox>
 
 ai_notes:
   do:

package/docs/profiles/components/UiTimePicker.yml

@@ -0,0 +1,144 @@
+component: UiTimePicker
+summary: >
+  UiTimePicker is a time input component that combines textbox-like entry with a list of
+  normalized time variants and bounds.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiTimePicker
+
+related_components:
+  - UiTextbox
+  - UiPopper
+
+examples:
+  - title: Example
+    code: |
+      <template>
+        <UiTimePicker v-model:value="value" />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiTimePicker } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref('10:30')
+      </script>
+  - title: Option interval (`interval`)
+    code: |
+      <template>
+        <UiTimePicker
+          v-model:value="value"
+          :interval="15"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiTimePicker } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref('10:30')
+      </script>
+  - title: Range limit (`minTime` / `maxTime`)
+    code: |
+      <template>
+        <UiTimePicker
+          v-model:value="value"
+          :min-time="[9, 30]"
+          :max-time="[18, 0]"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiTimePicker } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref('10:30')
+      </script>
+  - title: Custom options (`timeVariants`)
+    code: |
+      <template>
+        <UiTimePicker
+          v-model:value="value"
+          :time-variants="['09:00', '09:30', '12:25', '16:00']"
+        />
+
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiTimePicker } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref('10:30')
+      </script>
+use_when:
+  - You need editable time input.
+  - You need bounded time variants or interval-based time selection.
+
+avoid_when:
+  - You need raw text input without time semantics.
+
+api:
+  key_props:
+    - name: value
+    - name: placeholder
+    - name: interval
+    - name: timeVariants
+    - name: minTime
+    - name: maxTime
+    - name: textboxOptions
+  methods:
+    - 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
+
+behavior:
+  notes:
+    - interval and timeVariants shape the selectable list.
+    - minTime and maxTime constrain valid selection.
+    - textboxOptions should be used for trigger sizing and placeholder behavior.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiTextbox
+  patterns:
+    - title: Time field
+      notes: Wrap in UiField for forms and settings screens.
+    - title: Bounded scheduler input
+      notes: Use minTime, maxTime, and interval for schedules instead of allowing arbitrary text.
+
+ai_notes:
+  do:
+    - Use for semantic time values and schedule inputs.
+  avoid:
+    - Do not use UiTextbox alone when the value must be a valid bounded time.
+
+accessibility:
+  notes:
+    - Prefer visible text labels for interactive controls.
+    - For icon-only or custom visual content, provide an accessible name through the supported label, title, or ARIA attributes exposed by the component.
+    - Preserve native keyboard semantics by using the component root instead of recreating the control with arbitrary markup.
+  keyboard:
+    - Tab moves focus to the control when it is focusable.
+    - Enter or Space activates native button-like controls when the host implementation renders a button.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+  root_classes:
+    - .ui-v1-time-picker

package/docs/profiles/{UiToggleButton.yml → components/UiToggleButton.yml}

@@ -15,6 +15,22 @@ related_components:
   - UiCheckbox
   - UiSwitch
 
+examples:
+  - title: Single toggle
+    code: |
+      <template>
+        <UiToggleButton :pressed="opened" @click="opened = !opened">
+          Filters
+        </UiToggleButton>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiToggleButton } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const opened = ref(false)
+      </script>
+
 use_when:
   - You need a button-looking control with externally managed pressed state.
   - You need a primitive for segmented controls or compact filter chips.
@@ -189,17 +205,6 @@ composition:
     - 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: