@retailcrm/embed-ui-v1-components 0.9.14 → 0.9.16

package/docs/AI.md

@@ -0,0 +1,106 @@
+# AI Context For `@retailcrm/embed-ui-v1-components`
+
+This file is intended for AI assistants and automations that use the installed
+`@retailcrm/embed-ui-v1-components` package inside another project.
+
+Only the public package contract is described below, without depending on the repository's internal structure.
+
+## Package Identity
+
+- Package name: `@retailcrm/embed-ui-v1-components`
+- Purpose: UI components and UI helpers for RetailCRM JS extensions
+- Framework: Vue 3
+- Published Storybook: `https://retailcrm.github.io/embed-ui/v1-components/0.9.14/`
+- Primary public entrypoints:
+  - `@retailcrm/embed-ui-v1-components/remote`
+  - `@retailcrm/embed-ui-v1-components/host`
+  - `@retailcrm/embed-ui-v1-components/assets/...`
+
+## Safe Usage Rules
+
+- Import only from documented public entrypoints.
+- Do not import from package-internal files such as `dist/*` or repository-only paths.
+- Treat `remote` as the default public surface for extension authors.
+- Treat `host` as a specialized public surface for runtime-side integrations.
+- If a requested capability is not present in public exports, say that directly instead of suggesting internal imports.
+
+## Reading Strategy For AI
+
+When generating UI code, use this order:
+
+1. read [`COMPONENTS.md`](./COMPONENTS.md) to identify candidate components;
+2. open a detailed profile from [`PROFILES.md`](./PROFILES.md) if one exists;
+3. use [`FORMAT.md`](./FORMAT.md) as the schema for what information is considered reliable;
+4. read [`STYLING.md`](./STYLING.md) when the task is about classes, variables, typography, or visual zones;
+5. if no profile exists yet, fall back to [Storybook](https://retailcrm.github.io/embed-ui/v1-components/0.9.14/) docs and public type declarations, and state any inference explicitly.
+
+## Default Recommendation For Common Forms
+
+When building a basic form or settings screen, start from patterns like:
+
+```ts
+import {
+  UiButton,
+  UiField,
+  UiPageHeader,
+  UiSelect,
+  UiTextbox,
+} from '@retailcrm/embed-ui-v1-components/remote'
+```
+
+Typical compositions:
+
+- `UiField` + `UiTextbox`
+- `UiField` + `UiSelect`
+- `UiPageHeader` + `UiButton`
+- `UiSelect` + `UiSelectOption`
+
+## What AI Needs In A Good Component Profile
+
+The most useful format for AI is a component profile that explicitly answers:
+
+- when to use the component and when not to use it;
+- which imports are public and safe;
+- which props, emits, slots, and `v-model` pairs actually matter in practice;
+- what the rendered shape looks like conceptually;
+- how the component behaves in disabled, readonly, invalid, empty, opened, and focused states;
+- how it composes with neighboring components;
+- which assumptions are safe, and which are merely current implementation details.
+
+That schema is documented in [`FORMAT.md`](./FORMAT.md).
+
+## Important Boundary About DOM And CSS
+
+Profiles may describe current host DOM shape and root classes so that AI can reason about geometry,
+states, and composition more accurately.
+
+However, extension code should not rely on `.ui-v1-*` classes as a stable public styling contract unless
+the package explicitly documents that contract.
+
+The preferred styling signal is:
+
+1. props such as `size`, `appearance`, `outlined`, or `variant`;
+2. documented CSS variables from profile `styling.css_variables`;
+3. descriptive classes only for debugging or narrow local integrations.
+
+## Current High-Signal Profiles
+
+- [`UiField`](./profiles/UiField.yml)
+- [`UiTextbox`](./profiles/UiTextbox.yml)
+- [`UiButton`](./profiles/UiButton.yml)
+- [`UiPageHeader`](./profiles/UiPageHeader.yml)
+- [`UiSelect`](./profiles/UiSelect.yml)
+- [`UiRadioSwitch`](./profiles/UiRadioSwitch.yml)
+- [`UiTabGroup`](./profiles/UiTabGroup.yml)
+- [`UiTab`](./profiles/UiTab.yml)
+- [`UiPopper`](./profiles/UiPopper.yml)
+- [`UiPopperConnector`](./profiles/UiPopperConnector.yml)
+- [`UiPopperTarget`](./profiles/UiPopperTarget.yml)
+
+## Related Public Docs
+
+- [`README.md`](./README.md)
+- [`COMPONENTS.md`](./COMPONENTS.md)
+- [`FORMAT.md`](./FORMAT.md)
+- [`STYLING.md`](./STYLING.md)
+- [`../AGENTS.md`](../AGENTS.md)

package/docs/COMPONENTS.md

@@ -0,0 +1,99 @@
+# Public Components Catalog
+
+This catalog describes the public components and helpers available to consumers of
+`@retailcrm/embed-ui-v1-components`.
+
+Unless stated otherwise, extension UI code should import these entities from
+`@retailcrm/embed-ui-v1-components/remote`.
+
+Detailed AI-friendly profiles are collected in [`PROFILES.md`](./PROFILES.md).
+
+## Form And Input
+
+- [`UiField`](./profiles/UiField.yml): field wrapper with label, hint, validation state, and slot props for ARIA wiring
+- [`UiTextbox`](./profiles/UiTextbox.yml): text or numeric input with prefix, suffix, clear action, and multiline mode
+- [`UiCheckbox`](./profiles/UiCheckbox.yml): boolean choice
+- [`UiRadio`](./profiles/UiRadio.yml): single choice
+- [`UiRadioSwitch`](./profiles/UiRadioSwitch.yml): segmented single-choice switch with inline or section-card appearance
+- [`UiRadioSwitchOption`](./profiles/UiRadioSwitchOption.yml): rich option child for UiRadioSwitch
+- [`UiToggleGroup`](./profiles/UiToggleGroup.yml): segmented multi-select group built from toggle buttons
+- [`UiToggleGroupOption`](./profiles/UiToggleGroupOption.yml): rich option child for UiToggleGroup
+- [`UiSwitch`](./profiles/UiSwitch.yml): state toggle
+- [`UiSlider`](./profiles/UiSlider.yml): ranged value selection
+- [`UiSelect`](./profiles/UiSelect.yml): select container for single or multiple choice
+- [`UiSelectOption`](./profiles/UiSelectOption.yml): select option
+- [`UiSelectOptionGroup`](./profiles/UiSelectOptionGroup.yml): grouped options
+- [`UiDatePicker`](./profiles/UiDatePicker.yml): date or date-range selection
+- [`UiTimePicker`](./profiles/UiTimePicker.yml): time selection
+- [`UiCalendar`](./profiles/UiCalendar.yml): calendar primitive
+- [`UiNumberStepper`](./profiles/UiNumberStepper.yml): numeric input with increment and decrement controls
+
+## Actions And Navigation
+
+- [`UiButton`](./profiles/UiButton.yml): main action button that can render as a button or anchor
+- [`UiToggleButton`](./profiles/UiToggleButton.yml): stateful toggle button primitive for standalone or grouped use
+- [`UiAddButton`](./profiles/UiAddButton.yml): add action button
+- [`UiCopyButton`](./profiles/UiCopyButton.yml): copy value action
+- [`UiToolbarButton`](./profiles/UiToolbarButton.yml): toolbar button
+- [`UiToolbarLink`](./profiles/UiToolbarLink.yml): toolbar link
+- [`UiLink`](./profiles/UiLink.yml): text link
+- [`UiMenuItem`](./profiles/UiMenuItem.yml): menu item
+- [`UiMenuItemGroup`](./profiles/UiMenuItemGroup.yml): menu item group
+- [`UiTabGroup`](./profiles/UiTabGroup.yml): tab navigation group with overflow handling and optional active panel
+- [`UiTab`](./profiles/UiTab.yml): declarative tab child for UiTabGroup
+
+## Layout And Structure
+
+- [`UiPageHeader`](./profiles/UiPageHeader.yml): page or section header with an editable title and action zone
+- [`UiCollapse`](./profiles/UiCollapse.yml): collapsible section
+- [`UiCollapseBox`](./profiles/UiCollapseBox.yml): collapsible container
+- [`UiCollapseGroup`](./profiles/UiCollapseGroup.yml): multiple collapse coordination
+- [`UiScrollBox`](./profiles/UiScrollBox.yml): scrollable container
+- [`UiTransition`](./profiles/UiTransition.yml): transition wrapper
+
+## Feedback And Status
+
+- [`UiAlert`](./profiles/UiAlert.yml): contextual alert or notification
+- [`UiInfobox`](./profiles/UiInfobox.yml): highlighted explanatory block
+- [`UiError`](./profiles/UiError.yml): compact error state
+- [`UiLoader`](./profiles/UiLoader.yml): loading indicator
+- [`UiTag`](./profiles/UiTag.yml): labels and statuses
+
+## Overlays And Modal Patterns
+
+- [`UiModalWindow`](./profiles/UiModalWindow.yml): modal window
+- [`UiModalWindowSurface`](./profiles/UiModalWindowSurface.yml): modal surface
+- [`UiModalSidebar`](./profiles/UiModalSidebar.yml): sidebar modal
+- [`UiTooltip`](./profiles/UiTooltip.yml): tooltip
+- [`UiPopper`](./profiles/UiPopper.yml): floating layer
+- [`UiPopperTarget`](./profiles/UiPopperTarget.yml): popper target
+- [`UiPopperConnector`](./profiles/UiPopperConnector.yml): target-to-floating connector
+
+## Content And Data Display
+
+- [`UiAvatar`](./profiles/UiAvatar.yml): avatar
+- [`UiAvatarList`](./profiles/UiAvatarList.yml): avatar list
+- [`UiDate`](./profiles/UiDate.yml): formatted date display
+- [`UiImage`](./profiles/UiImage.yml): image display
+- [`UiTable`](./profiles/UiTable.yml): table root
+- [`UiTableColumn`](./profiles/UiTableColumn.yml): table column declaration
+- [`UiTableHeadCell`](./profiles/UiTableHeadCell.yml): table head cell primitive
+- [`UiTableBodyCell`](./profiles/UiTableBodyCell.yml): table body cell primitive
+- [`UiTableFooterSection`](./profiles/UiTableFooterSection.yml): table footer section container
+- [`UiTableFooterButton`](./profiles/UiTableFooterButton.yml): table footer action button
+- [`UiTableSorter`](./profiles/UiTableSorter.yml): table sort control primitive
+- [`UiYandexMap`](./profiles/UiYandexMap.yml): Yandex map component
+
+## Helpers
+
+- `usePreview`: image preview helper
+- `ImageWorkersKey`: injection key for image workers
+- `formatDate`: date formatter
+- `formatDateTime`: date-time formatter
+- `formatTime`: time formatter
+
+## Public Entrypoint Rule
+
+- For extension UI code, use `@retailcrm/embed-ui-v1-components/remote`.
+- For assets, use `@retailcrm/embed-ui-v1-components/assets/...`.
+- Use `@retailcrm/embed-ui-v1-components/host` only if your application is the runtime-side integration.

package/docs/FORMAT.md

@@ -0,0 +1,267 @@
+# AI-Friendly Component Profile Format
+
+This document defines the YAML component profile format that AI assistants can use
+to work with `v1-components` confidently.
+
+The format is optimized for code generation, code review, and safe API selection rather than for marketing copy.
+
+## Design Goals
+
+A good profile should let an agent answer these questions without opening the source code:
+
+- which component to choose for a task;
+- how to import it and which neighbors it works with;
+- which props, emits, slots, and `v-model` pairs actually affect behavior;
+- how the component behaves in important states;
+- where the public contract ends and implementation details begin.
+
+## YAML Shape
+
+Recommended filename: `<ComponentName>.yml`
+
+Minimal shape:
+
+```yml
+component: UiComponent
+summary: >
+  A short description of the component.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiComponent
+
+use_when:
+  - scenario
+
+avoid_when:
+  - scenario
+
+api:
+  key_props:
+    - name: value
+      notes: high-signal behavior
+  props:
+    - name: value
+      notes: practical usage note
+  slots:
+    - name: default
+      zone: content
+      notes: role of the slot
+  emits:
+    - name: update:value
+      payload: unknown
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-component
+    tag: div
+
+geometry:
+  layout: block-like root
+  root_display: block
+  width_behavior: stretches to container width by default
+
+styling:
+  root_classes:
+    - .ui-v1-component
+  css_variables:
+    public_theme_variables:
+      - name: --ui-v1-component-color
+        effect: theme or state color
+  typography:
+    default:
+      mixin: text-regular
+      size: 16px
+      line_height: 24px
+      weight: 400
+
+examples:
+  - title: Basic example
+    goal: What the user or the agent is trying to build.
+    code: |
+      <UiComponent />
+
+ai_notes:
+  do:
+    - rule
+  avoid:
+    - anti-pattern
+```
+
+## Required Sections
+
+Each YAML profile should include the following conceptual sections.
+
+## 1. `summary`
+
+A short paragraph, usually 2 to 4 sentences:
+
+- what the component is;
+- which role it usually plays in the UI;
+- which neighboring components it is commonly used with.
+
+## 2. `use_when`
+
+A list of concrete scenarios:
+
+- when the component is a good default choice;
+- which cases it covers better than neighboring components.
+
+Keep the wording practical: "amount input", "page header", "filterable select".
+
+## 3. `avoid_when`
+
+A list of cases where the component should not be chosen:
+
+- wrong semantics;
+- composition limits;
+- cases where a neighboring component is a better fit.
+
+## 4. `public_import`
+
+Include:
+
+- the public entrypoint;
+- the primary import;
+- related public components, if they are needed for a complete scenario.
+
+## 5. `api`
+
+List only high-signal API:
+
+- key props;
+- key emits;
+- important slots;
+- exposed methods, if they affect usage patterns.
+
+Do not copy the entire `.d.ts` verbatim if parts of the API do not affect component choice.
+
+Inside `api`, it is useful to distinguish:
+
+- `key_props`
+- `props`
+- `slots`
+- `emits`
+- `methods`
+
+## 6. `rendered_structure`
+
+Describe the actual rendered shape:
+
+- the root container;
+- the actual root tag or tags when they matter, for example `button`, `a`, `div`, or `span`;
+- the main internal zones;
+- where label, control, action area, icon area, popper content, and similar parts live;
+- current root classes and state classes, if they help reasoning.
+
+Important:
+
+- this section is descriptive, not normative;
+- state explicitly that it exists for mental modeling and debugging;
+- do not present internal classes as a stable public styling API unless that contract is documented separately.
+
+## 7. `geometry`
+
+Capture:
+
+- whether the component is block-like or inline-like;
+- what the root behaves like in layout terms, for example `block`, `inline-block`, `inline-flex`, or `flex`;
+- what stretches to `width: 100%` and what stays content-sized;
+- how the component behaves in a row, grid, header, or popper;
+- which props affect dimensions: `size`, `multiline`, `autofit`, `popperFitTrigger`, and so on.
+
+Useful optional fields:
+
+- `root_display` for the root display mode or the common display modes when the root changes by props;
+- `width_behavior` for whether the component stretches, shrinks to content, or switches between those modes;
+- `notes` for short practical remarks about how the root behaves in layout and composition.
+
+## 8. `styling`
+
+Capture only the styling data that helps an agent make safe decisions:
+
+- root classes, zone classes, and state classes for reasoning and debugging;
+- CSS custom properties that change theme, spacing, size, or popper behavior;
+- typography mixins or resulting size, line-height, and weight values;
+- whether classes and variables are descriptive implementation details or safe override points.
+
+Inside `styling`, it is useful to distinguish:
+
+- `root_classes`
+- `state_classes`
+- `zones`
+- `css_variables`
+- `typography`
+
+Important:
+
+- prefer CSS variables and documented props over selector-based overrides;
+- do not present internal `.ui-v1-*` selectors as a stable public contract unless that is documented explicitly;
+- say when a variable is a documented theme hook versus an internal implementation token.
+
+## 9. `behavior`
+
+This is one of the most important sections for AI.
+
+Describe:
+
+- `disabled`, `readonly`, `invalid`, `active`, `expanded`, `multiple`, and other state props;
+- when and how errors, placeholders, clear buttons, and tooltips appear;
+- keyboard behavior when it matters for UX;
+- interaction transitions such as click-to-edit or open-close flows.
+
+## 10. `accessibility`
+
+Capture:
+
+- which ARIA relationships the component expects or creates;
+- what happens to `aria-invalid`, `aria-labelledby`, `role`, `aria-expanded`, and similar attributes;
+- which keys affect behavior, if that behavior is documented.
+
+## 11. `examples` and `composition`
+
+List:
+
+- common combinations;
+- required neighboring components;
+- safe defaults for typical screens;
+- goal-oriented examples such as "build a table", "build an editable header", or "build a field with a select";
+- examples of correct and incorrect composition.
+
+## 12. `ai_notes`
+
+A short list of rules specifically for code generation:
+
+- what to do almost every time;
+- what not to do;
+- where it is better to admit the docs are missing than to guess.
+
+## Writing Rules
+
+- Use short, concrete statements instead of vague praise.
+- Use the exact names of props, emits, and slots.
+- For slots, describe not only the name, but also what the slot does and which content restrictions exist.
+- For styling, distinguish between safe CSS variables and descriptive class names.
+- Do not mix "how the component looks right now" with "what is publicly guaranteed".
+- If behavior is inferred from implementation rather than public API, say that explicitly.
+- If information is missing, state the limitation rather than inventing details.
+
+## What Can Be Automated
+
+The following data can usually be obtained automatically or semi-automatically:
+
+- the list of public exports;
+- prop, emit, method, and enum names;
+- whether Storybook stories and examples exist;
+- the current root classes and layout zones from templates.
+
+These sections almost always need manual writing:
+
+- when to use the component;
+- which neighbors it composes with best;
+- which anti-patterns are most dangerous for AI;
+- which part of the DOM or CSS shape is only a descriptive model.
+
+That split should stay documented in maintainer-only repository notes, not in the published package docs.

package/docs/PROFILES.md

@@ -0,0 +1,66 @@
+# Component Profiles
+
+`PROFILES.md` is the entry point for machine-readable AI-friendly component profiles.
+
+The current profile layer is structured like this:
+
+- the index stays in markdown so both humans and agents can navigate it easily;
+- the actual profiles live in `docs/profiles/*.yml`;
+- YAML is the source of truth for structure, props, slots, emits, examples, and AI rules.
+
+## Table Of Contents
+
+- [Reading Order](#reading-order)
+- [Current Coverage](#current-coverage)
+- [What To Read First](#what-to-read-first)
+- [Styling Reads](#styling-reads)
+- [Notes](#notes)
+
+## Reading Order
+
+1. [`AI.md`](./AI.md)
+2. this index
+3. the relevant `.yml` profile
+
+## Current Coverage
+
+Coverage is now expanding across the public component catalog.
+
+Use these entrypoints:
+
+- [`COMPONENTS.md`](./COMPONENTS.md) for the full linked component index
+- `docs/profiles/*.yml` for per-component machine-readable profiles
+
+Current high-signal core profiles:
+
+- [`UiField`](./profiles/UiField.yml)
+- [`UiTextbox`](./profiles/UiTextbox.yml)
+- [`UiButton`](./profiles/UiButton.yml)
+- [`UiToggleButton`](./profiles/UiToggleButton.yml)
+- [`UiToggleGroup`](./profiles/UiToggleGroup.yml)
+- [`UiPageHeader`](./profiles/UiPageHeader.yml)
+- [`UiSelect`](./profiles/UiSelect.yml)
+- [`UiRadioSwitch`](./profiles/UiRadioSwitch.yml)
+- [`UiTabGroup`](./profiles/UiTabGroup.yml)
+- [`UiTab`](./profiles/UiTab.yml)
+- [`UiPopper`](./profiles/UiPopper.yml)
+- [`UiPopperConnector`](./profiles/UiPopperConnector.yml)
+- [`UiPopperTarget`](./profiles/UiPopperTarget.yml)
+
+## What To Read First
+
+- `key_props` if you need to choose a component quickly.
+- `props` if you need a broader practical API view.
+- `slots` if the task is about markup, zones, and allowed content.
+- `emits` if the component must be wired into screen logic.
+- `examples` if you need a working usage pattern quickly.
+- `ai_notes` if the agent needs safe defaults and anti-patterns.
+
+## Styling Reads
+
+- Read `styling` for root classes, state classes, CSS variables, and typography.
+- Read [`STYLING.md`](./STYLING.md) when the task is specifically about classes, visual zones, theming, or type scale.
+
+## Notes
+
+- All new updates should be made in YAML profiles.

package/docs/README.md

@@ -0,0 +1,65 @@
+# Public API Docs For `@retailcrm/embed-ui-v1-components`
+
+This directory contains consumer-facing and AI-friendly documentation for the public API of
+`@retailcrm/embed-ui-v1-components`.
+
+These docs are optimized for two main scenarios:
+
+- a developer or AI assistant is writing extension UI code and wants to use public components safely;
+- a library maintainer is extending the docs and wants to know which description format is the most useful for agents.
+
+## Documentation Map
+
+- [`AI.md`](./AI.md)
+  a compact quickstart for AI agents: which entrypoint to prefer, which reading order to use,
+  and which boundaries are safe by default.
+- [`COMPONENTS.md`](./COMPONENTS.md)
+  a catalog of public components and helpers with links to detailed component profiles.
+- [`FORMAT.md`](./FORMAT.md)
+  the target component profile format for AI assistants.
+- [`STYLING.md`](./STYLING.md)
+  shared guidance for reading classes, CSS variables, and typography in profiles.
+- [`PROFILES.md`](./PROFILES.md)
+  the index of YAML component profiles.
+
+## Public Entrypoints
+
+- `@retailcrm/embed-ui-v1-components/remote`
+  the primary entrypoint for extension UI code
+- `@retailcrm/embed-ui-v1-components/host`
+  the entrypoint for runtime-side integrations
+- `@retailcrm/embed-ui-v1-components/assets/...`
+  icons and other static package assets
+
+If you are writing regular extension code, you almost always want `remote`.
+
+## What These Docs Optimize For
+
+- help choose the right component for a task, not just list exports;
+- describe actual behavior, states, and composition patterns;
+- separate the public contract from descriptive implementation notes;
+- give AI agents enough context to avoid relying on internal package paths.
+
+## Important Boundary
+
+Component profiles may describe the current DOM shape, root classes, and host-side layout,
+but that information is meant as a mental model and a debugging aid.
+
+It should not be treated as a public styling API for extension code unless that contract is documented explicitly.
+
+The same rule applies to `.ui-v1-*` selectors in profile `styling` sections.
+
+## Suggested Reading Order
+
+If you need to generate UI quickly:
+
+1. [`AI.md`](./AI.md)
+2. [`COMPONENTS.md`](./COMPONENTS.md)
+3. the relevant profile from [`PROFILES.md`](./PROFILES.md)
+4. [`STYLING.md`](./STYLING.md) if the task is about classes, variables, typography, or layout tuning
+
+If you are extending the docs:
+
+1. [`FORMAT.md`](./FORMAT.md)
+2. [`STYLING.md`](./STYLING.md)
+3. the existing profiles in [`PROFILES.md`](./PROFILES.md)