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

package/docs/profiles/components/UiCollapseBox.yml

@@ -0,0 +1,143 @@
+component: UiCollapseBox
+summary: >
+  UiCollapseBox is a structured expandable container with built-in header, state handling,
+  and visual treatment. It is a higher-level companion to UiCollapse.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiCollapseBox
+
+related_components:
+  - UiCollapse
+  - UiCollapseGroup
+
+examples:
+  - title: Basic collapse box
+    code: |
+      <template>
+        <UiCollapseBox v-model:expanded="expanded">
+          <template #title>Section title</template>
+          <template #body-content>Section content</template>
+        </UiCollapseBox>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCollapseBox } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const expanded = ref(false)
+      </script>
+  - title: Grouped collapse boxes
+    code: |
+      <template>
+        <UiCollapseGroup v-model:activeBoxId="activeBoxId">
+          <UiCollapseBox id="one">
+            <template #title>One</template>
+            <template #body-content>...</template>
+          </UiCollapseBox>
+
+          <UiCollapseBox id="two">
+            <template #title>Two</template>
+            <template #body-content>...</template>
+          </UiCollapseBox>
+        </UiCollapseGroup>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCollapseBox, UiCollapseGroup } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const activeBoxId = ref('one')
+      </script>
+  - title: Disabled
+    code: |
+      <template>
+        <UiCollapseBox disabled>
+          <template #title>Disabled section</template>
+        </UiCollapseBox>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiCollapseBox } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Custom icon through a slot
+    code: |
+      <template>
+        <UiCollapseBox>
+          <template #icon>
+            <MyCustomIcon />
+          </template>
+        </UiCollapseBox>
+
+      </template>
+
+      <script lang="ts" setup>
+      import MyCustomIcon from '@retailcrm/embed-ui-v1-components/assets/sprites/actions/info.svg'
+      import { UiCollapseBox } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+use_when:
+  - You need a ready-to-use collapsible box.
+  - You need grouped expandable sections with consistent visuals.
+
+avoid_when:
+  - You need a bare collapse primitive without box chrome.
+
+api:
+  key_props:
+    - name: expanded
+    - name: expandable
+    - name: collapsible
+    - name: toggleable
+    - 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.
+
+ai_notes:
+  do:
+    - Use UiCollapseBox for structured disclosure UI.
+    - Put the summary in the header and details in the body; avoid hiding critical required fields.
+  avoid:
+    - Do not rebuild collapse header UI manually when this component already fits.
+
+composition:
+  works_well_with:
+    - UiCollapse
+    - UiCollapseGroup
+    - UiInfobox
+  patterns:
+    - title: Settings section
+      notes: Use for optional or advanced settings groups.
+    - title: Grouped disclosures
+      notes: Use inside UiCollapseGroup when multiple boxes should coordinate active state.
+
+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-collapse-box

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

@@ -37,3 +37,27 @@ geometry:
 ai_notes:
   do:
     - Use with UiCollapseBox when grouped expansion matters.
+  avoid:
+    - Do not introduce a group for a single collapsible section.
+
+behavior:
+  notes:
+    - activeBoxId tracks which child section is active.
+    - The component is mostly coordination logic rather than a visual container.
+
+composition:
+  works_well_with:
+    - UiCollapseBox
+  patterns:
+    - title: Accordion-like settings
+      notes: Use when users should move between several related expandable sections.
+
+accessibility:
+  notes:
+    - Keep visible labels and slot content meaningful.
+    - Prefer documented props and slots over custom DOM replacements so host-side accessibility behavior is preserved.
+
+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/UiCopyButton.yml

@@ -0,0 +1,104 @@
+component: UiCopyButton
+summary: >
+  UiCopyButton is an action component for copying text values with tooltip feedback.
+  It wraps copy behavior and copied-state hinting into one compact UI.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiCopyButton
+
+related_components:
+  - UiTooltip
+  - UiButton
+
+examples:
+  - title: Example
+    code: |
+      <template>
+        <UiCopyButton text="Text to copy" size="sm">
+          <template #hint>
+            Copy
+          </template>
+
+          <template #hint-copied>
+            Copied
+          </template>
+        </UiCopyButton>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiCopyButton } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
+use_when:
+  - You need a copy-to-clipboard action for a value.
+  - You need built-in hint and copied-state tooltip text.
+
+avoid_when:
+  - You need a generic button with no copy semantics.
+
+api:
+  key_props:
+    - name: text
+    - name: size
+    - name: tooltipOptions
+  slots:
+    - name: trigger
+      zone: trigger
+      creates: Visible trigger content.
+    - name: hint
+      zone: tooltip
+      creates: Default tooltip content.
+    - name: hint-copied
+      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.
+    - Provide the exact text prop that should be copied.
+  avoid:
+    - Do not use for actions whose primary purpose is not copying.
+
+behavior:
+  notes:
+    - Shows normal hint content before copy and copied-state hint after successful copy.
+    - tooltipOptions customizes the hint surface.
+
+composition:
+  works_well_with:
+    - UiTooltip
+    - UiButton
+    - UiTable
+  patterns:
+    - title: Copy value in a table
+      notes: Use for IDs, tokens, phones, or links where copying is a repeated row action.
+
+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-copy-button

package/docs/profiles/components/UiDate.yml

@@ -0,0 +1,84 @@
+component: UiDate
+summary: >
+  UiDate is a display component for formatted date or date-time output. It is for presenting
+  date values, not for editing them.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiDate
+
+examples:
+  - title: Standard usage
+    code: |
+      <template>
+          <UiDate :date="new Date()" locale="en-GB" />
+      </template>
+
+      <script setup>
+      import { UiDate } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: With time display
+    code: |
+      <template>
+          <UiDate :date="new Date()" locale="en-GB" with-time />
+      </template>
+
+      <script setup>
+      import { UiDate } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
+use_when:
+  - You need to display a date value.
+  - You need optional time display with locale-aware formatting.
+
+avoid_when:
+  - You need editable date input.
+
+api:
+  key_props:
+    - name: date
+    - 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.
+    - Use withTime only when the time changes user interpretation.
+  avoid:
+    - Do not use for editable date fields or filter controls.
+
+behavior:
+  notes:
+    - Renders semantic time output for display.
+    - locale should be explicit when the surrounding screen uses a specific locale.
+
+composition:
+  works_well_with:
+    - UiTable
+    - UiDatePicker
+  patterns:
+    - title: Table date
+      notes: Use plain formatted output in tables; split date and time into separate lines only for compact scanning.
+
+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.

package/docs/profiles/components/UiDatePicker.yml

@@ -0,0 +1,138 @@
+component: UiDatePicker
+summary: >
+  UiDatePicker combines textbox-like date display, popper behavior, and calendar selection.
+  It supports single-date and range flows, constraints, and quick options.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiDatePicker
+
+related_components:
+  - UiCalendar
+  - UiTextbox
+  - UiPopper
+
+examples:
+  - title: Example
+    code: |
+      <template>
+        <UiDatePicker v-model:value="value" />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiDatePicker } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<Date | null>(new Date())
+      </script>
+  - title: Range selection
+    code: |
+      <template>
+        <UiDatePicker
+          v-model:value="value"
+          type="range"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiDatePicker } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<Date[]>([
+        new Date('2024-11-10'),
+        new Date('2024-11-19'),
+      ])
+      </script>
+  - title: Quick presets (`quickOptions`)
+    code: |
+      <template>
+        <UiDatePicker
+          v-model:value="value"
+          synchronization="confirmed"
+          :quick-options="[
+            { label: 'Today', value: new Date() },
+            { label: 'This week', value: [new Date('2024-11-18'), new Date('2024-11-24')] },
+          ]"
+        />
+
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiDatePicker } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<Date | null>(new Date())
+      </script>
+use_when:
+  - You need editable date input.
+  - You need date-range selection through a textbox-plus-popup flow.
+
+avoid_when:
+  - You need always-visible inline calendar selection only.
+
+api:
+  key_props:
+    - name: value
+    - name: type
+    - name: minDate
+    - name: maxDate
+    - name: nullable
+    - name: synchronization
+    - name: quickOptions
+    - name: textboxOptions
+  methods:
+    - name: open
+    - 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.
+    - synchronization controls instant versus confirmed behavior.
+
+ai_notes:
+  do:
+    - Prefer UiDatePicker for typed or popup date input.
+    - Use textboxOptions for trigger sizing and placeholder behavior instead of custom trigger markup.
+  avoid:
+    - Do not use UiCalendar directly if a textbox trigger is expected.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiTable
+    - UiCalendar
+  patterns:
+    - title: Date filter
+      notes: Use in the filter area above UiTable for date and date-range filters; persist selected values in URL query parameters when routing exists.
+    - title: Form date input
+      notes: Wrap in UiField so label, hint, and validation are preserved.
+
+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-date-picker

package/docs/profiles/components/UiError.yml

@@ -0,0 +1,123 @@
+component: UiError
+summary: >
+  UiError is a compact error-state component for short error messages or fallback states.
+  It is intended for concise inline error display rather than large alert copy.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiError
+
+examples:
+  - title: Example
+    code: |
+      <template>
+          <UiError v-bind="$attrs" :class="$style['container']">
+              <template v-if="useSlot">
+                  <div :class="$style['content']">
+                      <IconError :class="$style['icon']" />
+                      Error message with icon
+                  </div>
+              </template>
+          </UiError>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiError } from '@retailcrm/embed-ui-v1-components/remote'
+
+      import IconError from '@retailcrm/embed-ui-v1-components/assets/sprites/alerts/error.svg'
+
+      defineProps({
+        useSlot: {
+          type: Boolean,
+          default: false,
+        },
+      })
+      </script>
+
+      <style lang="less" module>
+
+      .container {
+        padding: 8px;
+        background: #FFF;
+        border: 1px solid #dee2e6;
+        border-radius: 8px;
+      }
+
+      .content {
+        display: flex;
+        align-items: center;
+        gap: 4px;
+      }
+
+      .icon {
+        width: 16px;
+        height: 16px;
+      }
+      </style>
+
+use_when:
+  - You need a compact error block.
+  - You need inline error text with standard styling.
+
+avoid_when:
+  - You need a richer feedback block, use UiAlert or UiInfobox instead.
+
+api:
+  key_props:
+    - name: message
+      notes: Fallback error text when default slot is not provided.
+    - name: align
+      notes: left or right text alignment.
+    - name: ellipsis
+      notes: Truncates long error text instead of wrapping.
+  slots:
+    - name: default
+      zone: error-content
+      creates: Error text or compact fallback content.
+
+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.
+    - Keep the message short and specific.
+  avoid:
+    - Do not use for multi-paragraph explanations or page-level failures.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiAlert
+  patterns:
+    - title: Field or section error
+      notes: Use where the user needs to see a concise local error message.
+    - title: Page-level failure
+      notes: Use UiAlert or UiInfobox instead when the error needs explanation and actions.
+
+behavior:
+  notes:
+    - Read key_props first to identify supported states and variants.
+    - Prefer controlled props and documented emits when synchronizing component state with screen logic.
+
+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-error

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

@@ -15,6 +15,52 @@ related_components:
   - UiCheckbox
   - UiDatePicker
 
+examples:
+  - title: Basic usage
+    code: |
+      <template>
+          <UiField id="name-field" label="Name" hint="At least 3 characters">
+              <template #default="field">
+                  <UiTextbox
+                      :id="field.id"
+                      :input-attributes="{
+                          'aria-labelledby': field.ariaLabelledby,
+                          'aria-invalid': field.ariaInvalid,
+                      }"
+                  />
+              </template>
+          </UiField>
+      </template>
+
+      <script lang="ts" setup>
+      import {
+        UiField,
+        UiTextbox,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Addon next to label
+    code: |
+      <template>
+          <UiField id="name-field" label="Name">
+              <template #addon>
+                  Up to 32 characters
+              </template>
+
+              <template #default="field">
+                  <UiTextbox
+                      :id="field.id"
+                      :input-attributes="{
+                          'aria-labelledby': field.ariaLabelledby,
+                          'aria-invalid': field.ariaInvalid,
+                      }"
+                  />
+              </template>
+          </UiField>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiField, UiTextbox } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
 use_when:
   - You need a labeled form control with consistent field semantics.
   - You need to pass id, aria-labelledby, and aria-invalid into an inner control.
@@ -208,21 +254,6 @@ composition:
     - title: Safe field wiring
       notes: Use slot props for semantics, not just for visual wrapping.
 
-examples:
-  - title: Text field with propagated semantics
-    goal: Build a text field with correct ARIA wiring.
-    code: |
-      <UiField id="comment" label="Comment" hint="Visible to managers">
-        <template #default="field">
-          <UiTextbox
-            :id="field.id"
-            :input-attributes="{
-              'aria-labelledby': field.ariaLabelledby,
-              'aria-invalid': field.ariaInvalid,
-            }"
-          />
-        </template>
-      </UiField>
 
 ai_notes:
   do: