@retailcrm/embed-ui-v1-components 0.9.25 → 0.9.27

package/dist/remote.cjs

@@ -2466,6 +2466,12 @@ const slotNeedsBodyCellWrapper = (children) => {
   }
   return !nodes.every(isCellVNode);
 };
+const hasSlotContent = (children) => {
+  if (!children) {
+    return false;
+  }
+  return normalizeNodes(children).length > 0;
+};
 const renderGroupHead = (slot, props) => {
   return slot?.(props) ?? [String(props.group.key)];
 };
@@ -2692,17 +2698,25 @@ const _sfc_main$6 = vue.defineComponent({
         const pageSize = slots["footer-page-size"]?.(footerData);
         const exportControl = slots["footer-export"]?.(footerData);
         const pagination = slots["footer-pagination"]?.(footerData);
+        const hasSummary = hasSlotContent(summary);
+        const hasPageSize = hasSlotContent(pageSize);
+        const hasExportControl = hasSlotContent(exportControl);
+        const hasPagination = hasSlotContent(pagination);
+        const hasAnyStructuredFooterContent = hasSummary || hasPageSize || hasExportControl || hasPagination;
+        if (!hasAnyStructuredFooterContent) {
+          return null;
+        }
         return vue.h(UiTableSection, { kind: "foot", key: "footer" }, () => vue.h(UiTableRow, () => vue.h(UiTableBodyCell, {
           colspan: columnsCount,
           class: "ui-v1-table__footer-cell"
         }, () => vue.h("div", { class: "ui-v1-table__footer" }, [
-          summary ? vue.h("div", { class: "ui-v1-table__footer-meta" }, [summary]) : null,
-          pageSize || exportControl || pagination ? vue.h("div", { class: "ui-v1-table__footer-controls" }, [
-            pageSize || exportControl ? vue.h("div", { class: "ui-v1-table__footer-main" }, [
+          hasSummary ? vue.h("div", { class: "ui-v1-table__footer-meta" }, [summary]) : null,
+          hasPageSize || hasExportControl || hasPagination ? vue.h("div", { class: "ui-v1-table__footer-controls" }, [
+            hasPageSize || hasExportControl ? vue.h("div", { class: "ui-v1-table__footer-main" }, [
               pageSize,
               exportControl
             ]) : null,
-            pagination ? vue.h("div", { class: "ui-v1-table__footer-side" }, [pagination]) : null
+            hasPagination ? vue.h("div", { class: "ui-v1-table__footer-side" }, [pagination]) : null
           ]) : null
         ]))));
       }

package/dist/remote.js

@@ -2464,6 +2464,12 @@ const slotNeedsBodyCellWrapper = (children) => {
   }
   return !nodes.every(isCellVNode);
 };
+const hasSlotContent = (children) => {
+  if (!children) {
+    return false;
+  }
+  return normalizeNodes(children).length > 0;
+};
 const renderGroupHead = (slot, props) => {
   return slot?.(props) ?? [String(props.group.key)];
 };
@@ -2690,17 +2696,25 @@ const _sfc_main$6 = defineComponent({
         const pageSize = slots["footer-page-size"]?.(footerData);
         const exportControl = slots["footer-export"]?.(footerData);
         const pagination = slots["footer-pagination"]?.(footerData);
+        const hasSummary = hasSlotContent(summary);
+        const hasPageSize = hasSlotContent(pageSize);
+        const hasExportControl = hasSlotContent(exportControl);
+        const hasPagination = hasSlotContent(pagination);
+        const hasAnyStructuredFooterContent = hasSummary || hasPageSize || hasExportControl || hasPagination;
+        if (!hasAnyStructuredFooterContent) {
+          return null;
+        }
         return h(UiTableSection, { kind: "foot", key: "footer" }, () => h(UiTableRow, () => h(UiTableBodyCell, {
           colspan: columnsCount,
           class: "ui-v1-table__footer-cell"
         }, () => h("div", { class: "ui-v1-table__footer" }, [
-          summary ? h("div", { class: "ui-v1-table__footer-meta" }, [summary]) : null,
-          pageSize || exportControl || pagination ? h("div", { class: "ui-v1-table__footer-controls" }, [
-            pageSize || exportControl ? h("div", { class: "ui-v1-table__footer-main" }, [
+          hasSummary ? h("div", { class: "ui-v1-table__footer-meta" }, [summary]) : null,
+          hasPageSize || hasExportControl || hasPagination ? h("div", { class: "ui-v1-table__footer-controls" }, [
+            hasPageSize || hasExportControl ? h("div", { class: "ui-v1-table__footer-main" }, [
               pageSize,
               exportControl
             ]) : null,
-            pagination ? h("div", { class: "ui-v1-table__footer-side" }, [pagination]) : null
+            hasPagination ? h("div", { class: "ui-v1-table__footer-side" }, [pagination]) : null
           ]) : null
         ]))));
       }

package/docs/AI.md

@@ -63,10 +63,13 @@ When building a basic form or settings screen, start from patterns like:
 ```ts
 import {
   UiButton,
+  UiCheckbox,
   UiField,
+  UiNumberStepper,
   UiPageFooter,
   UiPageHeader,
   UiSelect,
+  UiSwitch,
   UiTextbox,
 } from '@retailcrm/embed-ui-v1-components/remote'
 ```
@@ -75,6 +78,9 @@ Typical compositions:
 
 - `UiField` + `UiTextbox`
 - `UiField` + `UiSelect`
+- `UiField` + `UiNumberStepper`
+- `UiSwitch` + visible label + hint row
+- `UiCheckbox` + visible label row or checkbox group
 - `UiPageHeader` + `UiButton`
 - `UiSelect` + `UiSelectOption`
 
@@ -91,15 +97,20 @@ Default screen rules:
 - use `UiPageFooter` for page-level save/cancel/delete actions instead of recreating a local footer;
 - use one `Success Primary` button for the strongest save/apply/create action that commits a result; use `Default Primary`
   only for another important action with a different meaning;
+- use `Secondary` buttons for real neighboring commands that should still look like buttons;
+- use `Tertiary` buttons for lower-emphasis edit, open, configure, cancel, close, and optional commands near headers,
+  cards, tables, and inline content;
 - apply the 24px top and 32px side/bottom padding rule to white content surfaces, not to the page root wrapper;
 - keep filters and controls near the content they affect;
-- use `UiField` around labeled form controls;
+- use `UiField` around labeled textbox, select, number, date, and time controls;
 - use `UiTable` for structured result lists;
 - use `UiLink` for navigation and inline links, `UiButton` for commands;
 - use `UiLoader` with `overlay: true` when loading should dim the covered page or module content;
 - keep public imports on `@retailcrm/embed-ui-v1-components/remote`;
 - when a component uses only the default slot, prefer `v-slot` on the component instead of `<template #default>`;
 - avoid custom markup that recreates textbox, select, button, link, or table chrome.
+- before passing enum-like prop values, check the component profile or public type; omit optional props instead of
+  inventing neutral values such as `"none"` when they are not listed.
 
 ## Default Recommendation For Table Screens
 
@@ -115,6 +126,10 @@ screen where users scan and refine datasets:
 - reset `page` to `1` when filters or sorting change;
 - debounce free-text search before writing query or fetching data;
 - use `UiTableSorter` for sortable headers;
+- for ordinary `UiTableColumn` cell customization, set header metadata through props such as `label`, `width`,
+  and `trim`, then use `v-slot` on `UiTableColumn` instead of `<template #cell>`;
+- use the `#cell` slot only when the column also needs another named slot such as `#label`, or when explicit
+  slot naming makes a complex column easier to read;
 - use `UiTable` footer slots for summary, page-size controls, export, and pagination;
 - compose table footer controls with `UiTableFooterSection` and `UiTableFooterButton`, not regular `UiButton`;
 - use chevron icon assets for table footer previous/next controls instead of text glyphs;
@@ -142,10 +157,16 @@ When building forms with remote controls:
 - use `UiField` for labeled text, select, date, and number controls;
 - forward `UiField` slot props into the actual child control when it accepts `id`, especially
   `UiTextbox`, `UiSelect`, and `UiNumberStepper`;
+- put validation errors inside the relevant field composition, not as unrelated sibling blocks;
 - when a component uses only the default slot, prefer `v-slot` on the component instead of
   `<template #default>`;
 - do not wrap `UiSwitch` in `UiField`; place the switch next to a visible label and optional hint,
   and connect `UiSwitch :id` with `label :for`.
+- do not wrap simple `UiCheckbox` rows in `UiField`; place the checkbox next to a visible label and optional hint.
+- use `UiSwitch` for compact immediate boolean settings, feature toggles, and enable/disable flags.
+- use `UiCheckbox` for checkbox groups, table row selection, "select all", acknowledgements, and checkbox-shaped choices.
+- use `UiNumberStepper` for bounded numeric settings, quantities, durations, limits, and values with meaningful increments.
+- use `UiTextbox` for numeric-looking text such as phone numbers, codes, identifiers, and free-form numeric strings.
 
 ## Default Recommendation For Widgets
 

package/docs/STYLING.md

@@ -157,6 +157,28 @@ For style-sensitive generation:
 4. avoid relying on internal descendant selectors unless the profile says that is safe;
 5. state which styling source is being followed when the change was requested by design feedback.
 
+## Remote Page Styles
+
+For Vue remote pages and page-like components, prefer local CSS Modules:
+
+```vue
+<style module lang="less">
+```
+
+Apply classes through `$style[...]` in the template. Use `@import (reference)` from
+`@retailcrm/embed-ui-v1-components/assets/stylesheets/*` for shared LESS tokens and typography
+mixins.
+
+Remote page styles should normally:
+
+- use package spacing, palette, geometry, and typography tokens instead of local hardcoded colors,
+  font sizes, weights, and spacing;
+- keep styles local to the page or component through CSS Modules;
+- avoid shared global files such as `admin.less` as the default strategy;
+- avoid duplicating CRM host layout padding on the page root;
+- put documented 24px top and 32px side/bottom padding on white content surfaces when such a
+  surface exists.
+
 ## Design Feedback Triage
 
 When design feedback does not match the current implementation, resolve the source before editing:

package/docs/profiles/components/UiAvatar.yml

@@ -16,7 +16,6 @@ examples:
           name="Anna Smith"
           src="https://example.com/avatar.jpg"
           size="sm"
-          status="none"
         />
       </template>
 
@@ -37,7 +36,17 @@ api:
     - name: src
     - name: name
     - name: status
+      values:
+        - busy
+        - break
+        - dinner
+        - free
+      notes: Omit status when no indicator should be shown; do not pass "none".
     - name: size
+      values:
+        - xs
+        - sm
+        - lg
     - name: href
 
 rendered_structure:
@@ -61,8 +70,10 @@ ai_notes:
   do:
     - Use UiAvatar for identity display, not for general media.
     - Provide name whenever possible so fallback identity stays meaningful.
+    - Omit optional enum-like props when no listed value applies.
   avoid:
     - Do not use it for generic content images or large media blocks.
+    - Do not pass unsupported neutral values such as status="none"; check listed values first.
 
 composition:
   works_well_with:

package/docs/profiles/components/UiButton.yml

@@ -211,6 +211,8 @@ behavior:
       notes: Enables the separate locked state.
   notes:
     - If href is present, the component becomes a link-shaped action.
+    - appearance="secondary" is for neighboring commands that should still read as real buttons.
+    - appearance="tertiary" is for lower-emphasis actions near headers, cards, tables, and inline content.
 
 accessibility:
   notes:
@@ -231,7 +233,9 @@ ai_notes:
     - Start with appearance=primary for the main CTA, then choose variant by meaning.
     - Use variant="success" for the strongest create/save/apply action when it commits a result, and keep only one Success Primary on a page.
     - Use the default variant for an important primary action that is not the strongest commit action.
-    - Use secondary or tertiary for neighboring actions near titles.
+    - Use secondary for a real neighboring command that should still look like a button.
+    - Use tertiary for lower-emphasis edit, open, configure, cancel, close, and optional commands that should not compete with the main flow.
   avoid:
     - Do not replace UiButton with UiLink when the action should read as a button.
     - Do not use UiButton for regular inline text navigation.
+    - Do not default every non-primary action to secondary; choose tertiary when the action is only supportive.

package/docs/profiles/components/UiCheckbox.yml

@@ -1,7 +1,7 @@
 component: UiCheckbox
 summary: >
-  UiCheckbox is a boolean or set-membership control. It supports single boolean-like usage
-  as well as model-plus-value patterns for checkbox groups.
+  UiCheckbox is a checkbox or set-membership control. It supports single acknowledgement-like
+  choices, table row selection, "select all" states, and model-plus-value patterns for checkbox groups.
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -37,12 +37,14 @@ examples:
       const channels = ref<string[]>([])
       </script>
 use_when:
-  - You need a yes or no control.
+  - You need a checkbox-shaped boolean choice such as an acknowledgement or confirmation.
   - You need one value inside a checkbox group model.
+  - You need row selection, mass selection, or an indeterminate "select all" control.
 
 avoid_when:
   - You need exclusive single choice, use UiRadio instead.
-  - You need a more compact toggle-like control, use UiSwitch instead.
+  - You need a compact immediate on or off setting, use UiSwitch instead.
+  - You need a settings toggle row where a switch better communicates enable or disable state.
 
 api:
   key_props:
@@ -73,26 +75,32 @@ behavior:
   notes:
     - model plus value supports group-style selection.
     - indeterminate is useful for partial selection states.
+    - For ordinary settings toggles, UiSwitch is usually the better control even when the value is boolean.
 
 ai_notes:
   do:
-    - Use for boolean choice or checkbox-group membership.
+    - Use for checkbox-group membership, acknowledgement-like boolean choices, and table row selection.
     - Use indeterminate for parent selection such as "select all visible rows".
   avoid:
     - Do not use for mutually exclusive options.
+    - Do not replace UiSwitch settings toggles with UiCheckbox just because the value is boolean.
 
 composition:
   works_well_with:
-    - UiField
+    - visible label
+    - hint text
     - UiTable
     - UiTableColumn
   patterns:
-    - title: Form boolean
-      notes: Wrap in UiField when the checkbox needs a persistent label, hint, or validation text.
+    - title: Checkbox row
+      notes: Place UiCheckbox on the left, label and optional hint on the right, similar to a UiSwitch settings row.
+    - title: Checkbox group
+      notes: Use several UiCheckbox controls with one array model and visible labels for multi-selection.
     - title: Table row selection
       notes: Use in the first narrow UiTableColumn for row selection; use indeterminate in the header checkbox for partial selection.
   avoid:
     - Do not use as a visual switch replacement when the action is an immediate on or off setting.
+    - Do not wrap simple checkbox rows in UiField; use an explicit row with visible label and optional hint.
 
 accessibility:
   notes:

package/docs/profiles/components/UiField.yml

@@ -12,7 +12,6 @@ public_import:
 related_components:
   - UiTextbox
   - UiSelect
-  - UiCheckbox
   - UiNumberStepper
   - UiDatePicker
 
@@ -162,6 +161,8 @@ api:
           - UiDatePicker
         avoid:
           - several unrelated controls
+          - UiSwitch setting rows
+          - UiCheckbox setting rows
           - decorative layout only
           - raw content without using slot props
       layout_effect: The control sits below the headline and inherits field-level semantics through slot props.
@@ -311,8 +312,10 @@ ai_notes:
     - Forward slot props into the actual control in most form scenarios.
     - Pass field.id to child controls that accept id, including UiTextbox, UiSelect, and UiNumberStepper.
     - Use v-slot on UiField when the field uses only the default slot.
-    - Use UiField as a semantic wrapper for a single control.
+    - Use UiField as a semantic wrapper for a single textbox, select, number, date, or time control.
+    - Place validation errors inside the relevant field composition instead of rendering them as unrelated sibling blocks.
   avoid:
     - Do not use UiField as a generic visual container without control semantics.
     - Do not use UiField for UiSwitch settings rows; pair UiSwitch with a visible label and hint text instead.
+    - Do not use UiField for simple UiCheckbox rows; pair UiCheckbox with a visible label and optional hint instead.
     - Do not ignore id and ariaLabelledby when accessibility matters.

package/docs/profiles/components/UiNumberStepper.yml

@@ -28,9 +28,11 @@ examples:
 use_when:
   - You need numeric input with explicit step controls.
   - You need range constraints and nullable numeric state.
+  - You need bounded numeric settings, quantities, durations, limits, delays, or values with meaningful increments.
 
 avoid_when:
   - You need plain text or decimal input without stepper controls.
+  - You need numeric-looking text such as phone numbers, codes, identifiers, or free-form strings.
 
 api:
   key_props:
@@ -82,6 +84,7 @@ ai_notes:
     - Prefer nullable when clearing the value is a valid state.
   avoid:
     - Do not use when the value is an identifier, phone, code, or other numeric-looking text.
+    - Do not replace with UiTextbox for bounded numeric settings unless a runtime limitation is documented.
 
 accessibility:
   notes:

package/docs/profiles/components/UiSwitch.yml

@@ -120,10 +120,12 @@ examples:
       </style>
 use_when:
   - You need a compact on or off toggle.
+  - You need an immediate boolean setting, feature flag, enable or disable control, or settings row.
 
 avoid_when:
   - You need checkbox-group semantics.
   - You need a UiField-style labeled wrapper; pair UiSwitch with a visible label and hint text instead.
+  - You need an acknowledgement, legal confirmation, table selection, or multi-select choice; use UiCheckbox instead.
 
 api:
   key_props:
@@ -170,6 +172,7 @@ ai_notes:
     - Put helper text below the label in the settings row, not in UiField hint.
   avoid:
     - Do not use for multi-select lists or legal acknowledgements; use UiCheckbox.
+    - Do not replace compact settings toggles with UiCheckbox just because the value is boolean.
     - Do not use UiField around UiSwitch.
 
 accessibility:

package/docs/profiles/components/UiTable.yml

@@ -32,24 +32,18 @@ examples:
           :rows="rows"
           row-key="id"
         >
-          <UiTableColumn label="Title">
-            <template #cell="{ row }">
-              <strong>{{ row.title }}</strong>
-            </template>
+          <UiTableColumn v-slot="{ row }" label="Title">
+            <strong>{{ row.title }}</strong>
           </UiTableColumn>
 
-          <UiTableColumn label="Customer" width="180">
-            <template #cell="{ row }">
-              {{ row.customer }}
-            </template>
+          <UiTableColumn v-slot="{ row }" label="Customer" width="180">
+            {{ row.customer }}
           </UiTableColumn>
 
-          <UiTableColumn label="Status" width="160">
-            <template #cell="{ row }">
-              <UiTag :background="statusBackgroundByName[row.status]" size="md" saturated :ticker="false">
-                {{ row.status }}
-              </UiTag>
-            </template>
+          <UiTableColumn v-slot="{ row }" label="Status" width="160">
+            <UiTag :background="statusBackgroundByName[row.status]" size="md" saturated :ticker="false">
+              {{ row.status }}
+            </UiTag>
           </UiTableColumn>
         </UiTable>
       </template>
@@ -78,29 +72,25 @@ examples:
           :rows="rows"
           row-key="id"
         >
-          <UiTableColumn label="Name">
-            <template #cell="{ row }">
-              {{ row.name }}
-            </template>
+          <UiTableColumn v-slot="{ row }" label="Name">
+            {{ row.name }}
           </UiTableColumn>
 
-          <UiTableColumn :width="48" label="" trim>
-            <template #cell="{ row }">
-              <UiPopperConnector>
-                <UiButton
-                  :aria-label="`Edit ${row.name}`"
-                  appearance="tertiary"
-                  size="sm"
-                  @click="edit(row)"
-                >
-                  <IconEdit aria-hidden="true" />
-                </UiButton>
-
-                <UiTooltip>
-                  Edit {{ row.name }}
-                </UiTooltip>
-              </UiPopperConnector>
-            </template>
+          <UiTableColumn v-slot="{ row }" :width="48" label="" trim>
+            <UiPopperConnector>
+              <UiButton
+                :aria-label="`Edit ${row.name}`"
+                appearance="tertiary"
+                size="sm"
+                @click="edit(row)"
+              >
+                <IconEdit aria-hidden="true" />
+              </UiButton>
+
+              <UiTooltip>
+                Edit {{ row.name }}
+              </UiTooltip>
+            </UiPopperConnector>
           </UiTableColumn>
         </UiTable>
       </template>
@@ -139,18 +129,14 @@ examples:
           :rows="rows"
           row-key="id"
         >
-          <UiTableColumn :width="44" label="" trim>
-            <template #cell="{ expanded, toggle }">
-              <button class="table-expand" type="button" @click="toggle">
-                {{ expanded ? '-' : '+' }}
-              </button>
-            </template>
+          <UiTableColumn v-slot="{ expanded, toggle }" :width="44" label="" trim>
+            <button class="table-expand" type="button" @click="toggle">
+              {{ expanded ? '-' : '+' }}
+            </button>
           </UiTableColumn>
 
-          <UiTableColumn label="Title">
-            <template #cell="{ row }">
-              {{ row.title }}
-            </template>
+          <UiTableColumn v-slot="{ row }" label="Title">
+            {{ row.title }}
           </UiTableColumn>
 
           <template #expand="{ row }">
@@ -186,16 +172,12 @@ examples:
           row-key="id"
           :group-by="groupByStatus"
         >
-          <UiTableColumn label="Title">
-            <template #cell="{ row }">
-              {{ row.title }}
-            </template>
+          <UiTableColumn v-slot="{ row }" label="Title">
+            {{ row.title }}
           </UiTableColumn>
 
-          <UiTableColumn label="Status" width="160">
-            <template #cell="{ row }">
-              {{ row.status }}
-            </template>
+          <UiTableColumn v-slot="{ row }" label="Status" width="160">
+            {{ row.status }}
           </UiTableColumn>
 
           <template #group-head="{ group }">
@@ -241,10 +223,8 @@ examples:
           :rows="rows"
           row-key="id"
         >
-          <UiTableColumn label="Title">
-            <template #cell="{ row }">
-              {{ row.title }}
-            </template>
+          <UiTableColumn v-slot="{ row }" label="Title">
+            {{ row.title }}
           </UiTableColumn>
 
           <template #footer-summary="{ rowsCount }">
@@ -440,16 +420,12 @@ examples:
           :rows="rows"
           row-key="id"
         >
-          <UiTableColumn label="Title">
-            <template #cell="{ row }">
-              {{ row.title }}
-            </template>
+          <UiTableColumn v-slot="{ row }" label="Title">
+            {{ row.title }}
           </UiTableColumn>
 
-          <UiTableColumn label="Status" width="160">
-            <template #cell="{ row }">
-              {{ row.status }}
-            </template>
+          <UiTableColumn v-slot="{ row }" label="Status" width="160">
+            {{ row.status }}
           </UiTableColumn>
         </UiTable>
       </template>
@@ -649,6 +625,11 @@ composition:
       - Use UiTableSorter inside a UiTableColumn label slot for sortable columns.
       - Reset pagination to the first page when sorting changes.
       - Persist sort key and direction in URL query parameters when routing is available.
+  columns:
+    notes:
+      - Configure header metadata with UiTableColumn props such as label, width, align, valign, and trim.
+      - Prefer `v-slot` on UiTableColumn for ordinary cell content when the header is configured through props.
+      - Use `#cell` only when the column also needs another named slot such as `#label`, or when explicit naming improves readability.
   pagination:
     notes:
       - Use footer-summary, footer-page-size, footer-export, and footer-pagination slots for structured footer controls.
@@ -676,6 +657,7 @@ ai_notes:
     - Compose footer controls with UiTableFooterSection and UiTableFooterButton.
     - Copy the Entity list table footer example when building a realistic entity-list footer.
     - Use UiTableSorter for sortable headers.
+    - Prefer UiTableColumn `v-slot` for ordinary custom cells when label and sizing are configured through props.
     - Use icon-only row action buttons with aria-label and UiTooltip in action columns.
   avoid:
     - Do not hide table filters in page header actions.
@@ -684,6 +666,7 @@ ai_notes:
     - Do not put visible text buttons in dense table action columns.
     - Do not put pagination only in local state when the screen has routable result sets.
     - Do not import table internals from host or src paths.
+    - Do not use `<template #cell>` for every column when the default slot would be simpler.
 
 behavior:
   notes:

package/docs/profiles/components/UiTableColumn.yml

@@ -11,6 +11,35 @@ public_import:
 related_components:
   - UiTable
 
+examples:
+  - title: Prop label with default cell slot
+    notes:
+      - Use this shape when header metadata is covered by props and only the cell body is custom.
+    code: |
+      <UiTableColumn v-slot="{ row }" label="Name" min-width="180">
+        <UiLink size="small">{{ row.name }}</UiLink>
+      </UiTableColumn>
+  - title: Custom label and explicit cell slot
+    notes:
+      - Use named slots when the column uses a custom label, for example a sorter.
+      - Keeping `#cell` explicit makes the two slot zones easier to scan.
+    code: |
+      <UiTableColumn min-width="180">
+        <template #label>
+          <UiTableSorter
+            :direction="sort.direction"
+            :active="sort.field === 'name'"
+            @click="setSort('name')"
+          >
+            Name
+          </UiTableSorter>
+        </template>
+
+        <template #cell="{ row }">
+          <UiLink size="small">{{ row.name }}</UiLink>
+        </template>
+      </UiTableColumn>
+
 use_when:
   - You define columns for UiTable.
 
@@ -30,12 +59,19 @@ api:
     - name: default
       zone: cell
       creates: Cell content.
+      notes: >
+        Prefer `v-slot` on UiTableColumn when the header label is already supplied by the `label`
+        prop and only the cell body is customized.
     - name: cell
       zone: cell
       creates: Explicit cell content.
+      notes: >
+        Use `#cell` when the column also needs another named slot such as `#label`, or when explicit
+        naming makes a complex column easier to read.
     - name: label
       zone: header-label
       creates: Header label content.
+      notes: Use only when the header label needs custom markup, for example UiTableSorter.
 
 rendered_structure:
   descriptive_only: true
@@ -60,6 +96,10 @@ composition:
       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: Prop label plus custom cell
+      notes: Use `<UiTableColumn v-slot="{ row }" label="Name">` instead of `<template #cell>` when `label` prop is enough for the header.
+    - title: Custom label plus custom cell
+      notes: Use separate `<template #label>` and `<template #cell>` blocks when the header is built with a slot.
     - title: Status column
       notes: Use UiTag for categorical statuses instead of raw colored text.
 
@@ -68,8 +108,12 @@ ai_notes:
     - 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.
+    - Prefer `v-slot` on UiTableColumn for ordinary custom cell content when the header is configured through props.
+    - Use the label slot only when the header itself needs custom markup.
+    - Use explicit `#cell` together with `#label` when both header and cell content are custom.
   avoid:
     - Do not place filters inside column labels; filters belong above the table.
+    - Do not wrap every cell body in `<template #cell>` when the default slot would express the same thing more simply.
 
 behavior:
   notes:

package/docs/profiles/components/UiTextbox.yml

@@ -37,12 +37,14 @@ use_when:
   - You need a standard text input.
   - You need search, email, phone, url, or password input.
   - You need decimal or numeric input without a separate stepper.
+  - You need numeric-looking text such as a phone, code, identifier, article, external id, or free-form numeric string.
   - You need a multiline control in the same visual language.
   - You need an input that composes well with UiField and inline editing.
 
 avoid_when:
   - You need value selection, not free-form input.
   - You need explicit increment and decrement UX.
+  - You need bounded numeric settings, quantities, durations, limits, or values with meaningful increments; use UiNumberStepper instead.
   - You need advanced formatting beyond the prefix or suffix model.
 
 api:

package/docs/profiles/pages/CardSettingsPage.yml

@@ -23,6 +23,8 @@ expected_structure:
   - The white content surface owns the 24px top and 32px side/bottom padding.
   - The page root wrapper should not repeat that padding.
   - Content can include text, buttons, fields, checkboxes, radio groups, switches, and other form controls.
+  - Textbox, select, number, date, and time controls usually live inside UiField.
+  - UiSwitch and simple UiCheckbox rows should use their own row layout with a visible label and optional hint, not UiField.
   - A bottom save panel is optional.
   - If a bottom save panel is used, its main save or apply action should be Success Primary.
 
@@ -55,9 +57,14 @@ recommended_components:
 ai_notes:
   do:
     - Keep form controls grouped by task or semantic section.
-    - Use UiField around labelled form controls.
+    - Use UiField around labeled textbox, select, number, date, and time controls.
+    - Use UiSwitch for compact enable or disable settings.
+    - Use UiCheckbox for checkbox groups, table selection, acknowledgements, and checkbox-shaped boolean choices.
     - Use tabs only when they reduce visible complexity without hiding required work.
     - Keep save/apply as the strongest footer action and move neighboring actions to secondary or tertiary appearances unless their variant has a distinct page-level meaning.
+    - Prefer tertiary for low-emphasis local actions that should not compete with the settings save flow.
   avoid:
     - Do not create a decorative landing page for operational settings.
     - Do not put content-surface padding on the root page wrapper.
+    - Do not use UiCheckbox as the default replacement for UiSwitch just because a setting is boolean.
+    - Do not wrap UiSwitch or simple UiCheckbox rows in UiField.

package/docs/profiles/pages/EntityListPage.yml

@@ -18,6 +18,7 @@ expected_structure:
   - One or more 48px page buttons on the right side of the header.
   - If there are multiple header buttons, one should be primary and the rest can be secondary or tertiary.
   - The main Default Primary button usually creates a new entity for the list when there is no stronger Success Primary action on the page.
+  - Supporting header actions that should not compete with the create action are usually tertiary rather than secondary.
   - Filters above the table, built from controls such as select, textbox, and combobox-like selection components.
   - Filter controls should run in rows of roughly 4-5 fields, then wrap to the next row.
   - Filters can be collapsible.
@@ -65,8 +66,10 @@ ai_notes:
     - Persist filters, sorting, page, and page size in query parameters when routing is available.
     - Reset page to 1 when filters or sorting change.
     - Use narrow icon-only row action columns with matching aria-label and UiTooltip text.
+    - Use tertiary for low-emphasis header or row-adjacent commands when a secondary button would be too visually heavy.
   avoid:
     - Do not hide filters in page header actions.
     - Do not put pagination only in local state when the result set is routable.
     - Do not place UiTable inside an additional white card or padded content surface.
     - Do not use visible text buttons for dense table row actions.
+    - Do not make every header action secondary when only one action should draw attention.

package/docs/profiles/pages/PageComposition.yml

@@ -22,6 +22,8 @@ shared_rules:
   - Use Default Primary for an important action that is secondary to the Success Primary or does not commit a result.
   - Use Danger Primary only for one critical destructive action when the page needs it.
   - If several actions compete for attention, choose the main one for Success Primary and move the rest to Default Primary, secondary, tertiary, or dropdown actions by meaning.
+  - Use secondary for a real neighboring command that should still read as a button.
+  - Use tertiary for lower-emphasis header, card, inline, configure, edit, open, cancel, and close actions that should not compete with the main flow.
   - UiPageHeader actions and UiPageFooter actions belong to the same page-level action scope.
   - Treat each UiCollapseBox footer as a separate local action scope with the same rules scoped to that section.
   - A page can have several Default Primary buttons when each one belongs to a different UiCollapseBox footer.
@@ -60,8 +62,10 @@ ai_notes:
     - Choose ModalWindow or a full page when content needs wide tables, several sections, or complex controls.
     - Keep operational CRM screens dense, scannable, and work-focused.
     - Prefer variant="success" for the main save/apply/create action and keep it visually dominant.
+    - Prefer appearance="tertiary" for supportive actions that sit near content but should stay visually quiet.
   avoid:
     - Do not turn internal CRM work screens into marketing-style layouts.
     - Do not hide filters or primary workflow controls away from the content they affect.
     - Do not place multiple Success Primary, Default Primary, or Danger Primary actions with the same variant in the page-level scope or inside one collapse-box scope.
+    - Do not default every non-primary action to appearance="secondary"; choose by local action importance.
     - Do not add page-surface padding to both the page root and the white content surface.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@retailcrm/embed-ui-v1-components",
   "bin": "bin/embed-ui-v1-components.mjs",
   "type": "module",
-  "version": "0.9.25",
+  "version": "0.9.27",
   "license": "MIT",
   "author": "RetailDriverLLC <integration@retailcrm.ru>",
   "repository": {
@@ -82,8 +82,8 @@
     "@storybook/vue3": "^10.3.5",
     "@storybook/vue3-vite": "^10.3.5",
     "@vitejs/plugin-vue": "^6.0.2",
-    "@vitest/browser": "4.1.3",
-    "@vitest/browser-playwright": "4.1.3",
+    "@vitest/browser": "4.1.8",
+    "@vitest/browser-playwright": "4.1.8",
     "@vue/compiler-sfc": "^3.5.25",
     "@vue/test-utils": "^2.4.6",
     "@yandex/ymaps3-types": "^1.0.19072130",
@@ -100,7 +100,7 @@
     "vite": "^7.3.2",
     "vite-plugin-dts": "^4.5.4",
     "vite-svg-loader": "^5.1.0",
-    "vitest": "^4.1.3",
+    "vitest": "4.1.8",
     "vue": "^3.5.32",
     "vue-i18n": "10.0.8"
   }

package/templates/skills/embed-ui-v1-components-ui/SKILL.md.txt

@@ -26,13 +26,21 @@ Use this skill before changing frontend UI built with `@retailcrm/embed-ui-v1-co
 5. Do not hand-roll buttons, inputs, selects, tables, or links when a documented Embed UI component exists.
 6. Do not set arbitrary `font-family`; inherit the host/component stack unless a project-specific design requirement says otherwise.
 7. Do not style internal `.ui-v1-*` selectors unless the profile or `STYLING.md` explicitly documents that override pattern.
+8. For Vue remote pages, prefer `<style module lang="less">` with `$style[...]` and package LESS tokens/mixins.
+9. Before passing enum-like prop values, check the profile or public type; omit optional props instead of inventing neutral values.
 
 ## High-signal checks
 
 - For entity lists, use `UiTable`, `UiTableColumn`, and table footer slots.
+- For ordinary table cells, configure `UiTableColumn` headers through props and use `v-slot` on the column; reserve `#cell` for columns that also need another named slot or extra clarity.
 - For table pagination, follow the reference example in `UiTable.yml`: button sizes, active state, dividers, arrow assets, and scoped selector pattern.
 - For form fields, use `UiField` with the matching control and forward slot props such as `id` when the control accepts them.
+- Put validation errors inside the relevant field composition, not as unrelated sibling blocks.
 - For `UiSwitch`, use the documented switch + visible label + hint row instead of wrapping it in `UiField`.
+- For simple `UiCheckbox` rows, use checkbox + visible label + optional hint instead of wrapping it in `UiField`.
+- Use `UiSwitch` for compact boolean settings and `UiCheckbox` for checkbox groups, table row selection, select-all, and acknowledgements.
+- Use `UiNumberStepper` for bounded numeric settings and `UiTextbox` for numeric-looking text such as phones, codes, and identifiers.
+- Use `Secondary` buttons for real neighboring commands and `Tertiary` buttons for lower-emphasis edit/open/configure/cancel/close actions.
 - For widgets mounted into CRM targets, keep inline UI compact; move complex UI into `UiModalSidebar` or `UiModalWindow`.
 - For sidebar footers, group related actions, use 12px or 16px gaps inside groups, and confirm destructive icon-only actions with `UiPopconfirm okVariant="danger"`.