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

package/docs/profiles/components/UiSkeleton.yml

@@ -0,0 +1,82 @@
+component: UiSkeleton
+summary: >
+  UiSkeleton displays a placeholder block for loading content. It supports text,
+  rectangle and circle appearances with pulse or shimmer animation.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiSkeleton
+
+examples:
+  - title: Example
+    code: |
+      <template>
+        <UiSkeleton />
+
+      </template>
+
+      <script lang="ts" setup>
+      import { UiSkeleton } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+use_when:
+  - You need a content placeholder before actual data is loaded.
+  - You need line, card or avatar-like loading placeholders.
+
+avoid_when:
+  - You need a spinner-like indicator instead of a content-shaped placeholder.
+
+api:
+  key_props:
+    - name: appearance
+    - name: size
+    - name: animation
+    - name: width
+    - name: height
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-skeleton
+    tag: div
+
+geometry:
+  layout: inline block or block placeholder
+  root_display: inline-block
+  width_behavior: preset width by appearance and size, overridable via width prop
+
+ai_notes:
+  do:
+    - Use text appearance for line placeholders.
+    - Use circle appearance for avatar placeholders.
+    - Override width or height only when the preset size is not enough.
+  avoid:
+    - Do not use for errors or empty states; skeletons mean content is still expected.
+
+behavior:
+  notes:
+    - appearance should approximate the eventual content shape.
+    - animation communicates loading; avoid excessive animated skeletons in dense screens.
+
+composition:
+  works_well_with:
+    - UiAvatar
+    - UiTable
+    - UiLoader
+  patterns:
+    - title: Loading rows
+      notes: Use text or rectangle skeletons where table or list rows will appear.
+    - title: Loading identity
+      notes: Use circle skeletons where avatars will appear.
+
+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-skeleton

package/docs/profiles/components/UiSlider.yml

@@ -0,0 +1,161 @@
+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
+
+examples:
+  - title: Basic slider
+    code: |
+      <template>
+        <UiSlider v-model:value="value" />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiSlider } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref(20)
+      </script>
+  - title: Range slider
+    code: |
+      <template>
+        <UiSlider
+          v-model:value="value"
+          type="range"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiSlider } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<number[]>([20, 80])
+      </script>
+  - title: Bounded range slider
+    code: |
+      <template>
+        <UiSlider
+          v-model:value="value"
+          type="range"
+          :min="10"
+          :max="60"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiSlider } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<number[]>([20, 80])
+      </script>
+  - title: Labelled range slider
+    code: |
+      <template>
+        <UiSlider
+          v-model:value="value"
+          type="range"
+          labelled
+        >
+          <template #label="{ boundary }">
+            {{ boundary }}%
+          </template>
+
+          <template #handle="{ boundary }">
+            {{ boundary }}%
+          </template>
+        </UiSlider>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiSlider } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<number[]>([20, 80])
+      </script>
+  - title: Controlled slider
+    code: |
+      <template>
+        <UiSlider
+          :value="value"
+          @update:value="value = $event"
+        />
+
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiSlider } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref(20)
+      </script>
+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
+
+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
+
+behavior:
+  notes:
+    - Use when approximate adjustment is acceptable.
+    - For exact numeric input, prefer UiTextbox with numeric inputmode or UiNumberStepper.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiNumberStepper
+  patterns:
+    - title: Bounded adjustment
+      notes: Wrap in UiField and show min, max, or current value nearby when precision matters.
+    - title: Slider plus exact value
+      notes: Pair with UiNumberStepper when users need both quick dragging and exact entry.
+
+ai_notes:
+  do:
+    - Use only for bounded numeric ranges.
+    - Make the current value visible when the slider affects important settings.
+  avoid:
+    - Do not use for open-ended numbers, money amounts, or identifiers.
+
+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-slider

package/docs/profiles/components/UiSwitch.yml

@@ -0,0 +1,123 @@
+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
+
+examples:
+  - title: Basic switch
+    code: |
+      <template>
+        <UiSwitch v-model:value="enabled" />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiSwitch } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const enabled = ref(false)
+      </script>
+  - title: Controlled switch
+    code: |
+      <template>
+        <UiSwitch
+          :value="enabled"
+          @update:value="enabled = $event"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiSwitch } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const enabled = ref(false)
+      </script>
+  - title: Disabled
+    code: |
+      <template>
+        <UiSwitch :value="true" disabled />
+      </template>
+
+      <script lang="ts" setup>
+      import { UiSwitch } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Square
+    code: |
+      <template>
+        <UiSwitch v-model:value="enabled" square />
+
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiSwitch } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const enabled = ref(false)
+      </script>
+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
+
+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
+
+behavior:
+  notes:
+    - Best for immediate boolean settings, not for long-form confirmation choices.
+    - Disabled blocks interaction while preserving the current state visually.
+
+composition:
+  works_well_with:
+    - UiField
+  patterns:
+    - title: Settings row
+      notes: Pair with a visible label and optional description so the on or off state is unambiguous.
+  avoid:
+    - Do not use without a nearby label; the switch alone does not explain what will change.
+
+ai_notes:
+  do:
+    - Use for compact feature toggles and enable or disable settings.
+  avoid:
+    - Do not use for multi-select lists or legal acknowledgements; use UiCheckbox.
+
+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-switch

package/docs/profiles/components/UiTab.yml

@@ -0,0 +1,234 @@
+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
+
+examples:
+  - title: Tabs through `items`
+    code: |
+      <template>
+        <UiTabGroup
+          v-model:active-id="activeId"
+          :items="items"
+          overflowing
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiTabGroup } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const activeId = ref('overview')
+
+      const items = [
+        { id: 'overview', label: 'Overview', counter: '8' },
+        { id: 'orders', label: 'Orders', counter: '12' },
+        { id: 'files', label: 'Files', counter: '3' },
+      ]
+      </script>
+  - title: Tabs through `UiTab`, slot icons, and panel content
+    code: |
+      <template>
+        <UiTabGroup
+          v-model:active-id="activeId"
+          overflowing
+        >
+          <UiTab
+            v-for="item in items"
+            :key="item.id"
+            :id="item.id"
+            :label="item.label"
+            :counter="item.counter"
+            :disabled="item.disabled"
+          >
+            <template #icon>
+              <IconStar />
+            </template>
+
+            <template #content>
+              <section>
+                <h4>{{ item.label }}</h4>
+                <p>Active panel content for the tab {{ item.label }}</p>
+              </section>
+            </template>
+          </UiTab>
+        </UiTabGroup>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import IconStar from '@retailcrm/embed-ui-v1-components/assets/sprites/actions/star.svg'
+      import {
+        UiTab,
+        UiTabGroup,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const activeId = ref('overview')
+
+      const items = [
+        { id: 'overview', label: 'Overview', counter: '8' },
+        { id: 'orders', label: 'Orders', counter: '12' },
+        { id: 'files', label: 'Files', counter: '3' },
+      ]
+      </script>
+  - title: Filled tabs
+    code: |
+      <template>
+        <UiTabGroup
+          v-model:active-id="activeId"
+          appearance="filled"
+        >
+          <UiTab
+            v-for="item in items"
+            :key="item.id"
+            :id="item.id"
+            :label="item.label"
+            :counter="item.counter"
+          >
+            <template #icon>
+              <IconStar />
+            </template>
+          </UiTab>
+        </UiTabGroup>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import IconStar from '@retailcrm/embed-ui-v1-components/assets/sprites/actions/star.svg'
+      import { UiTab, UiTabGroup } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const activeId = ref('overview')
+
+      const items = [
+        { id: 'overview', label: 'Overview', counter: '8' },
+        { id: 'orders', label: 'Orders', counter: '12' },
+        { id: 'files', label: 'Files', counter: '3' },
+      ]
+      </script>
+  - title: Overflow menu
+    code: |
+      <template>
+        <div style="width: 320px;">
+          <UiTabGroup
+            v-model:active-id="activeId"
+            :items="items"
+            overflowing
+          />
+        </div>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiTabGroup } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const activeId = ref('overview')
+
+      const items = [
+        { id: 'overview', label: 'Overview', counter: '8' },
+        { id: 'orders', label: 'Orders', counter: '12' },
+        { id: 'files', label: 'Files', counter: '3' },
+      ]
+      </script>
+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
+  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,
+    menu items, and optional tabpanel.
+
+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.
+
+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.
+
+
+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.
+
+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/{UiTabGroup.yml → components/UiTabGroup.yml}

@@ -197,36 +197,6 @@ composition:
     - 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: