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

package/docs/profiles/components/UiError.yml

@@ -92,8 +92,10 @@ ai_notes:
   do:
     - Use for compact error presentation.
     - Keep the message short and specific.
+    - Put field-level errors inside the matching UiField instead of below the field wrapper.
   avoid:
     - Do not use for multi-paragraph explanations or page-level failures.
+    - Do not leave field-level errors disconnected from the control they describe.
 
 composition:
   works_well_with:
@@ -101,7 +103,9 @@ composition:
     - UiAlert
   patterns:
     - title: Field or section error
-      notes: Use where the user needs to see a concise local error message.
+      notes: >
+        Use where the user needs to see a concise local error message. For field-level validation,
+        render UiError inside the corresponding UiField default slot, directly after the control.
     - title: Page-level failure
       notes: Use UiAlert or UiInfobox instead when the error needs explanation and actions.
 

package/docs/profiles/components/UiField.yml

@@ -109,6 +109,56 @@ examples:
 
       const duration = ref(30)
       </script>
+  - title: Field validation with local error
+    notes:
+      - Keep the field-level error inside the UiField default slot, directly after the control it describes.
+      - Forward id and ARIA slot props into the real control; invalid styling alone is not enough for validation wiring.
+      - Add local margin to UiError when the design needs a visual gap below the control.
+    code: |
+      <template>
+          <UiField
+              id="specialist-name"
+              v-slot="field"
+              :invalid="Boolean(error)"
+              label="Name"
+              required
+          >
+              <UiTextbox
+                  :id="field.id"
+                  v-model:value="name"
+                  :invalid="field.invalid"
+                  :input-attributes="{
+                      'aria-labelledby': field.ariaLabelledby,
+                      'aria-invalid': field.ariaInvalid,
+                  }"
+              />
+
+              <UiError
+                  v-if="error"
+                  :class="$style['form-field-error']"
+                  :message="error"
+              />
+          </UiField>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+
+      import {
+        UiError,
+        UiField,
+        UiTextbox,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const name = ref('')
+      const error = ref('Name is required')
+      </script>
+
+      <style lang="less" module>
+      .form-field-error {
+        margin-top: 4px;
+      }
+      </style>
 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.
@@ -305,6 +355,10 @@ composition:
   patterns:
     - title: Safe field wiring
       notes: Use slot props for semantics, not just for visual wrapping.
+    - title: Field-level validation
+      notes: >
+        Place UiError inside the default slot immediately after the control, and complete id,
+        aria-labelledby, and aria-invalid wiring on the real control.
 
 
 ai_notes:
@@ -314,8 +368,11 @@ ai_notes:
     - Use v-slot on UiField when the field uses only the default slot.
     - 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.
+    - Add local spacing to UiError itself when the error needs a visible gap from the control.
   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.
+    - Do not render field-level UiError as a sibling immediately after the closing UiField.
+    - Do not rely only on the invalid prop when the control can receive field ARIA slot props.

package/docs/profiles/components/UiSelect.yml

@@ -213,7 +213,9 @@ api:
         - disabled
         - counter
         - accent
-      notes: Base selectable option node.
+      notes: >
+        Base selectable option node. Nullable values are allowed when they are meaningful to the model,
+        but Vue keys for repeated option nodes must be stable and non-null.
     - name: UiSelectOptionGroup
       key_props:
         - label

package/docs/profiles/components/UiSelectOption.yml

@@ -44,14 +44,19 @@ ai_notes:
     - Use as the default child node of UiSelect.
     - Provide stable value and human-readable label.
     - Use description for secondary explanation, not for long help text.
+    - Keep Vue `v-for` keys stable and non-null even when the option value itself can be null.
+    - Normalize persisted option DTOs to non-null ids, or use another stable domain key such as code, slug, or a temporary client id.
   avoid:
     - Do not put arbitrary controls inside options.
+    - Do not use nullable DTO ids directly as Vue keys.
+    - Do not use array index as the fallback key for dynamic options that can be sorted, filtered, inserted, or removed.
 
 behavior:
   notes:
     - disabled prevents selection while keeping the option visible.
     - counter and accent help scan dense option lists.
     - In filterable selects, label and description participate in matching.
+    - A nullable option value is valid for selection semantics, but the Vue key for a repeated option node must still be stable and non-null.
 
 composition:
   works_well_with:

package/docs/profiles/components/UiTable.yml

@@ -119,6 +119,98 @@ examples:
         console.log(row)
       }
       </script>
+  - title: Multiple row actions in one final column
+    notes:
+      - Use one stable final action column for several row commands unless the product task explicitly asks for separate semantic columns.
+      - Keep the action cell width fixed and prevent it from wrapping primary row content.
+      - Each icon-only action needs aria-label and UiTooltip text.
+    code: |
+      <template>
+        <UiTable
+          bordered
+          :rows="rows"
+          row-key="id"
+        >
+          <UiTableColumn v-slot="{ row }" label="Name">
+            {{ row.name }}
+          </UiTableColumn>
+
+          <UiTableColumn v-slot="{ row }" :width="104" label="" trim>
+            <div :class="$style['specialist-table__actions']">
+              <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>
+
+              <UiPopperConnector>
+                <UiButton
+                  :aria-label="`Delete ${row.name}`"
+                  appearance="tertiary"
+                  size="sm"
+                  variant="danger"
+                  @click="remove(row)"
+                >
+                  <IconDelete aria-hidden="true" />
+                </UiButton>
+
+                <UiTooltip>
+                  Delete {{ row.name }}
+                </UiTooltip>
+              </UiPopperConnector>
+            </div>
+          </UiTableColumn>
+        </UiTable>
+      </template>
+
+      <script lang="ts" setup>
+      import IconDelete from '@retailcrm/embed-ui-v1-components/assets/sprites/ui/delete.svg'
+      import IconEdit from '@retailcrm/embed-ui-v1-components/assets/sprites/ui/edit.svg'
+      import {
+        UiButton,
+        UiPopperConnector,
+        UiTable,
+        UiTableColumn,
+        UiTooltip,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+
+      type Row = {
+        id: number
+        name: string
+      }
+
+      const rows: Row[] = [
+        { id: 101, name: 'Anna Smith' },
+        { id: 102, name: 'Ilya Johnson' },
+      ]
+
+      const edit = (row: Row) => {
+        console.log(row)
+      }
+
+      const remove = (row: Row) => {
+        console.log(row)
+      }
+      </script>
+
+      <style lang="less" module>
+      .specialist-table__actions {
+        display: flex;
+        align-items: center;
+        justify-content: flex-end;
+        gap: 8px;
+        white-space: nowrap;
+      }
+      </style>
   - title: Expandable rows table
     notes:
       - Use the expand slot and cell toggle helper for expandable row details.
@@ -644,6 +736,9 @@ composition:
   actions:
     notes:
       - Prefer narrow action columns with icon-only UiButton controls for row commands.
+      - If a row has multiple actions, keep them together in one final action column by default.
+      - Split row actions into separate columns only when each column has a distinct user-facing meaning or the task explicitly requires it.
+      - Give the action column a stable width and an inner flex container so actions do not resize or wrap primary row content.
       - Keep visible button text out of dense table rows; provide aria-label and matching UiTooltip text.
       - Use package sprite icons and set aria-hidden on the icon itself.
       - Wrap action buttons and UiTooltip in UiPopperConnector. Add UiPopperTarget only for custom non-component targets.
@@ -659,11 +754,13 @@ ai_notes:
     - 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.
+    - Put several row actions into one final action cell unless separate columns are explicitly required.
   avoid:
     - Do not hide table filters in page header actions.
     - Do not wrap UiTable in an additional white card, panel, or content-surface container.
     - Do not use UiButton inside table footer pagination.
     - Do not put visible text buttons in dense table action columns.
+    - Do not create several neighboring empty action columns for edit, delete, and similar compact row commands.
     - 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.

package/docs/profiles/pages/CardSettingsPage.yml

@@ -24,9 +24,15 @@ expected_structure:
   - 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.
+  - Field-level validation errors should be rendered as UiError inside the corresponding UiField, directly after the control.
+  - Bounded numeric settings, quantities, durations, limits, and ordering values should use UiNumberStepper instead of UiTextbox.
+  - UiTextbox with numeric input attributes is acceptable only when stepper controls do not fit the product interaction.
   - 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.
+  - Show page-level API failures with UiAlert variant="danger".
+  - Show successful saves with a closable UiAlert variant="success" or another documented project success pattern.
+  - Use UiLoader when loading blocks the settings form; keep already loaded form chrome stable during save requests when possible.
 
 recommended_components:
   - name: UiPageHeader
@@ -37,8 +43,16 @@ recommended_components:
     profile: ../components/UiField.yml
   - name: UiTextbox
     profile: ../components/UiTextbox.yml
+  - name: UiNumberStepper
+    profile: ../components/UiNumberStepper.yml
   - name: UiSelect
     profile: ../components/UiSelect.yml
+  - name: UiError
+    profile: ../components/UiError.yml
+  - name: UiAlert
+    profile: ../components/UiAlert.yml
+  - name: UiLoader
+    profile: ../components/UiLoader.yml
   - name: UiCheckbox
     profile: ../components/UiCheckbox.yml
   - name: UiRadio
@@ -58,6 +72,8 @@ ai_notes:
   do:
     - Keep form controls grouped by task or semantic section.
     - Use UiField around labeled textbox, select, number, date, and time controls.
+    - Put UiError inside the UiField that owns the invalid control.
+    - Use UiNumberStepper for bounded numeric settings and values with meaningful increments.
     - 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.
@@ -68,3 +84,5 @@ ai_notes:
     - 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.
+    - Do not implement bounded numeric settings as plain UiTextbox controls unless the exception is documented.
+    - Do not render field errors as unrelated sibling blocks outside UiField.

package/docs/profiles/pages/EntityListPage.yml

@@ -28,6 +28,12 @@ expected_structure:
   - UiTable should not be wrapped in an extra white content surface.
   - A wrapper around UiTable should only handle layout, width, or scrolling, without card chrome or content-surface padding.
   - Row action columns should use icon-only buttons with aria-label and UiTooltip instead of visible text buttons.
+  - Multiple row actions should live in one final action column with a stable width unless the task explicitly asks for separate columns.
+  - Settings-dependent columns should be conditional at the UiTableColumn level, not permanent columns that render empty values.
+  - If a setting disables a dependent column, avoid loading expensive data used only by that column.
+  - Show initial or blocking loading with UiLoader in the table/content area while keeping filters and page actions understandable.
+  - Show page-level API failures with UiAlert variant="danger".
+  - Use UiTable '#empty' for table-owned empty states; use UiInfobox when the empty state needs richer guidance or an action outside the table body.
   - The table may scroll and may support export.
 
 recommended_components:
@@ -51,6 +57,12 @@ recommended_components:
     profile: ../components/UiTableFooterSection.yml
   - name: UiTableFooterButton
     profile: ../components/UiTableFooterButton.yml
+  - name: UiLoader
+    profile: ../components/UiLoader.yml
+  - name: UiAlert
+    profile: ../components/UiAlert.yml
+  - name: UiInfobox
+    profile: ../components/UiInfobox.yml
 
 table_footer_rules:
   - Use UiTableFooterSection and UiTableFooterButton for table footer pagination.
@@ -66,10 +78,15 @@ 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.
+    - Put edit, delete, and similar compact row actions into one final action cell by default.
+    - Conditionally render settings-dependent columns at the column declaration, for example with `v-if` on UiTableColumn.
+    - Skip dependent API loads when the current settings make the dependent table data invisible.
     - 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 split compact row commands into several neighboring empty columns unless each column has a separate product meaning.
+    - Do not keep a settings-dependent column visible with blank cells when the setting is disabled.
     - Do not make every header action secondary when only one action should draw attention.

package/docs/profiles/pages/ModalSidebar.yml

@@ -151,6 +151,12 @@ expected_structure:
   - Destructive footer actions are often icon-only buttons aligned to the right edge.
   - Destructive icon-only actions should usually open UiPopconfirm with okVariant="danger"; its confirmation button is primary by default.
   - Content can be flexible, but should stay compact.
+  - Default sidebar forms use one form or grid container with a consistent gap.
+  - Each labeled textbox, select, number, date, or time control in a sidebar form should live in UiField.
+  - Field-level errors should use UiError inside the corresponding UiField, directly after the control.
+  - Bounded numeric sidebar fields should use UiNumberStepper unless stepper controls do not fit the product interaction.
+  - Footer actions should be placed through the UiModalSidebar footer slot, usually primary save and secondary or tertiary cancel.
+  - Sidebar titles should stay short enough for the available width.
   - Small tables can be placed in sidebars.
 
 recommended_components:
@@ -166,8 +172,14 @@ recommended_components:
     profile: ../components/UiField.yml
   - name: UiTextbox
     profile: ../components/UiTextbox.yml
+  - name: UiNumberStepper
+    profile: ../components/UiNumberStepper.yml
   - name: UiSelect
     profile: ../components/UiSelect.yml
+  - name: UiError
+    profile: ../components/UiError.yml
+  - name: UiAlert
+    profile: ../components/UiAlert.yml
   - name: UiTable
     profile: ../components/UiTable.yml
     notes: Use only for small, simple tables.
@@ -176,6 +188,9 @@ ai_notes:
   do:
     - Use for inspect, edit, or secondary workflows related to the current list or page.
     - Keep the flow compact.
+    - Use a single local form/grid container for sidebar forms.
+    - Put every labeled scalar form control in UiField and keep UiError inside that field.
+    - Use the footer slot for save/cancel actions rather than a page footer component.
     - Split footer actions into meaningful left and right groups when secondary or destructive actions need separation.
     - Use 12px or 16px gaps inside each footer action group.
     - Put destructive icon-only actions on the right and confirm them with UiPopconfirm okVariant="danger"; the confirmation button is primary by default.
@@ -183,4 +198,7 @@ ai_notes:
     - Do not use for bulky or complex interfaces.
     - Do not use collapse blocks inside sidebars.
     - Do not use two-column content on separate surfaces.
+    - Do not use a two-column form inside a sidebar unless the product task explicitly requires it and the content still fits.
+    - Do not place UiPageFooter inside UiModalSidebar.
+    - Do not mix unrelated spacing strategies inside one sidebar form; keep gaps owned by the form container and local error margins.
     - Use a full page or modal window for bulky flows.

package/docs/profiles/pages/PageComposition.yml

@@ -35,6 +35,12 @@ shared_rules:
   - Do not duplicate content-surface padding on the page root; outer page spacing is controlled by the CRM host layout.
   - Prefer public components from @retailcrm/embed-ui-v1-components/remote.
   - Do not invent custom chrome for pages, forms, tables, tabs, buttons, modals, or sidebars when a documented component fits.
+  - For Vue remote pages and page-like components, prefer local CSS Modules with `<style module lang="less">`; use shared global styles only as an intentional feature-level abstraction.
+  - Page-specific CSS Module class names should still describe the block they style, for example `entity-list__actions`, `settings-form__field-error`, or `modal-sidebar-form__footer`.
+  - Use UiLoader for loading states, UiAlert variant="danger" for page-level API failures, and UiAlert variant="success" or an approved local success pattern for successful saves.
+  - Use UiInfobox for richer explanatory empty states; use UiTable #empty when the empty state belongs directly to a table body.
+  - If a column or dependent UI exists only for an enabled setting, render the column conditionally instead of showing empty cells.
+  - Avoid loading expensive dependent API data when the setting that needs it is disabled.
 
 decision_guide:
   - need: Searchable, filterable registry.
@@ -63,9 +69,13 @@ ai_notes:
     - 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.
+    - Keep page-specific layout styles in CSS Modules unless the task records a shared styling abstraction.
+    - Choose one documented loading, error, success, and empty-state pattern for the page before finishing.
   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.
+    - Do not use a shared `admin.less` or other global page stylesheet only to avoid local composition styles.
+    - Do not show settings-dependent table columns as permanent empty placeholder columns.

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.27",
+  "version": "0.9.28",
   "license": "MIT",
   "author": "RetailDriverLLC <integration@retailcrm.ru>",
   "repository": {