@robosophy/ui-vue 1.1.10 → 1.1.12

package/components.md

@@ -1,442 +1,447 @@
-# @robosophy/ui-vue Components
-
-Reference for agents and developers using Robosophy Vue components in consuming projects.
-
-## Priority
-
-When building a module or complex UI, prefer these components before creating local equivalents:
-
-- `RsSidebar`: module navigation, side menu, mobile sidebar.
-- `RsAccountSelector`: user/account selector.
-- `RsIcon`: Material Symbols icon component and PrimeVue icon helper.
-- `RsAvatar`: user/account image or initials.
-- `RsCard`: reusable content container.
-
-Keep app behavior in the consuming project. Components emit events; the app handles routing, stores, fetches, permissions, logout, and redirects.
-
-## Setup
-
-```ts
-import {
-  RsAccountSelector,
-  RsAvatar,
-  RsCard,
-  RsIcon,
-  RsSidebar,
-  rsPrimeIcon,
-} from "@robosophy/ui-vue";
-```
-
-PrimeVue apps should register the Robosophy preset and import the theme CSS:
-
-```ts
-import PrimeVue from "primevue/config";
-import RobosophyPreset from "@robosophy/prime-theme";
-import "@robosophy/prime-theme/prime.css";
-
-app.use(PrimeVue, {
-  theme: {
-    preset: RobosophyPreset,
-  },
-});
-```
-
-`RsSidebar` and `RsAccountSelector` render their interactive controls with PrimeVue components, so PrimeVue apps should use the setup above to apply PrimeVue defaults plus Robosophy Button/Menu styling.
-
-Apps without PrimeVue should import:
-
-```ts
-import "@robosophy/tokens/tokens.css";
-```
-
-RsIcon uses SVG icons inline. Enable the Vite plugin to auto-detect icons and generate an SVG sprite:
-
-```ts
-import { robosophyMaterialSymbols } from "@robosophy/ui-vue/vite";
-
-export default defineConfig({
-  plugins: [vue(), robosophyMaterialSymbols()],
-});
-```
-
-El plugin escanea automaticamente `<RsIcon name="..." />`, `rsPrimeIcon("...")` y
-`icon: "..."` en el codigo fuente. Descarga los SVGs del repositorio oficial de Google
-durante el build, los cachea localmente y genera un sprite SVG inline. Sin fuentes
-tipograficas.
-
-## RsIcon
-
-Use for Material Symbols. The Vite plugin generates an SVG sprite with only the detected
-icons and inlines it in the HTML. No fonts are loaded.
-
-```vue
-<template>
-  <RsIcon name="home" />
-  <RsIcon name="settings" family="rounded" color="primary" />
-  <Button label="Inicio" :icon="rsPrimeIcon('home')" />
-</template>
-```
-
-For dynamic icon names that the scanner cannot see, add them to
-`robosophyMaterialSymbols({ include: [...] })`.
-
-### How the scanner works
-
-The plugin scans source files and detects icons using five patterns:
-
-| Pattern | Detects | Example |
-|---------|---------|---------|
-| 1 | `<RsIcon name="..." />` tags | `<RsIcon name="home" />` |
-| 2 | `rsPrimeIcon("...")` calls | `rsPrimeIcon('settings', { family: 'rounded' })` |
-| 3 | `icon: "..."` in objects | `{ icon: "inbox" }` |
-| 4 | Magic comments | `// @robosophy-icon: home` |
-| 5 | Arrays of strings (name has "icon") | `const iconNames = ["home", "search"]` |
-
-**Pattern 3** also extracts `weight` and `family` from the enclosing object:
-```ts
-{ icon: "home", weight: 200, family: "rounded" }
-// → weight 200, family "rounded"
-```
-
-**Pattern 4** (magic comments) is for cases where the scanner cannot detect an icon
-statically — typically when icon names are passed as props, stored in variables, or
-returned from functions:
-
-```ts
-// @robosophy-icon: manage_accounts
-// @robosophy-icon: settings family=rounded weight=200
-// @robosophy-icon: logout
-
-const action = { icon: "manage_accounts", label: "Perfil" };
-const getIcon = () => "settings";
-```
-
-**Pattern 5** detects arrays assigned to variables whose name contains "icon":
-```ts
-const icons = ["home", "search"];          // detected
-const sidebarIconNames = ["warning"];      // detected
-const names = ["home", "search"];          // NOT detected (no "icon" in name)
-```
-
-### When to use `include`
-
-Use the `include` option when an icon is used in many places or is controlled by
-remote configuration:
-
-```ts
-robosophyMaterialSymbols({
-  include: [
-    "home",
-    { family: "rounded", name: "settings", weight: 200 },
-  ],
-});
-```
-
-If `weight` is omitted, all valid weights (100–700) are included.
-
-### When to use magic comments
-
-Use `// @robosophy-icon:` when the icon is used in a single file and the variable
-name doesn't contain "icon":
-
-```ts
-// @robosophy-icon: manage_accounts
-// @robosophy-icon: logout
-const actions = [
-  { id: "profile", label: "Perfil", icon: "manage_accounts" },
-  { id: "logout", label: "Salir", icon: "logout" },
-];
-```
-
-### Special cases: props and iteration
-
-**Props to RsSidebar:** icons defined in the `items` array's `icon` property
-are detected by Pattern 3:
-```ts
-const items = [
-  { id: "home", label: "Home", icon: "home" },   // ✅ detected
-];
-```
-
-**Props to RsAccountSelector:** same — `icon` in action objects is detected.
-
-**v-for iteration with inline objects:** objects in the iterated array are detected:
-```vue
-<RsIcon v-for="item in items" :name="item.icon" />
-```
-
-**v-for with external variable:** not detectable — use magic comments:
-```vue
-<RsIcon v-for="name in iconNames" :name="name" />  <!-- add @robosophy-icon -->
-```
-
-### Full documentation
-
-For the complete technical reference (regex patterns, scanner architecture, plugin
-options, and known limitations), read `icon-scanner.md` in this package.
-
-For full control over icon props (fill, grade, etc.), use the slot approach:
-
-```vue
-<Button label="Favorito">
-  <template #icon>
-    <RsIcon name="favorite" fill color="danger" />
-  </template>
-</Button>
-```
-
-## RsSidebar
-
-Use for module navigation. It is controlled and presentational.
-
-Main props:
-
-```ts
-type RsSidebarItem = {
-  id: string;
-  label: string;
-  icon?: string;
-  active?: boolean;
-  disabled?: boolean;
-  visible?: boolean;
-  children?: RsSidebarItem[];
-};
-
-type RsSidebarProps = {
-  items: RsSidebarItem[];
-  footerItems?: RsSidebarItem[];
-  modules?: Array<{
-    text: string;
-    link: string;
-    active?: boolean;
-    disabled?: boolean;
-  }>;
-  navigateOnModuleSelect?: boolean;
-  title?: string;
-  icon?: string;
-  variant?: "pc" | "alta" | "cc" | "pog" | "cyo";
-  expanded?: boolean;
-  expandOnHover?: boolean;
-  mobileOpen?: boolean;
-  widthCollapsed?: string;
-  widthExpanded?: string;
-  ariaLabel?: string;
-};
-```
-
-Emits: `item-click`, `close-mobile`, `expanded-change`, `module-select`.
-
-Slots: `header`, `header-action`, `item`, `footer`.
-
-Example:
-
-```vue
-<script setup lang="ts">
-import { ref } from "vue";
-import { RsSidebar, type RsSidebarItem } from "@robosophy/ui-vue";
-
-const items: RsSidebarItem[] = [
-  { id: "liquidaciones", label: "Liquidacion", icon: "contract", active: true },
-  { id: "adquisiciones", label: "Adquisiciones", icon: "sell" },
-  {
-    id: "config",
-    label: "Config",
-    icon: "subtitles_gear",
-    children: [
-      { id: "excel", label: "Cargas Excel", icon: "upload" },
-      { id: "ayuda", label: "Ayuda", icon: "info" },
-    ],
-  },
-];
-
-const footerItems: RsSidebarItem[] = [{ id: "home", label: "Volver al home", icon: "home" }];
-const modules = [
-  { text: "Mi Alta", link: "/alta" },
-  { text: "Mi Cuenta y Orden", link: "/cyo", active: true },
-  { text: "Mi Cuenta Corriente", link: "/cc" },
-];
-const isMenuOpen = ref(false);
-
-function handleSidebarItem(item: RsSidebarItem) {
-  // Route, redirect, or store updates belong in the consuming app.
-}
-</script>
-
-<template>
-  <RsSidebar
-    title="CYO"
-    variant="cyo"
-    :items="items"
-    :modules="modules"
-    :footer-items="footerItems"
-    :mobile-open="isMenuOpen"
-    @item-click="handleSidebarItem"
-    @close-mobile="isMenuOpen = false"
-  />
-</template>
-```
-
-`modules` renders the default header dropdown. Each option has `text` and `link`. Selecting one emits `module-select`.
-
-If `navigateOnModuleSelect` is `true` the component also redirects with `window.location.href = module.link`. Set it to `false` in Storybook, tests, or apps that want to intercept navigation and route manually.
-
-Use the `header` slot only when the app needs to replace that default dropdown entirely.
-
-Project variants set sidebar icon and active colors:
-
-- `pc`: Plan Comercial, `#014A9F`.
-- `alta`: Alta, `#65AC1E`.
-- `cc`: Cuenta Corriente, `#49A0D4`.
-- `pog`: POG, `#007C2F`.
-- `cyo`: Cuenta y Orden, `#49A0D4`.
-
-## RsAccountSelector
-
-Use for user/account switching. It renders the clickable profile image trigger,
-opens the account panel, and closes it on outside click. It does not fetch,
-redirect, log out, or mutate stores.
-
-Main props:
-
-```ts
-type RsAccountSelectorUser = {
-  email: string;
-  name?: string;
-  avatarSrc?: string;
-  secondaryAvatarSrc?: string;
-  initials?: string;
-};
-
-type RsAccountSelectorAccount = {
-  id: string | number;
-  label: string;
-  avatarSrc?: string;
-  initials?: string;
-  active?: boolean;
-  disabled?: boolean;
-};
-
-type RsAccountSelectorAction = {
-  id: string;
-  label: string;
-  icon?: string;
-  visible?: boolean;
-  disabled?: boolean;
-  variant?: "ghost" | "danger";
-};
-```
-
-Use `v-model` when the open state needs to be controlled from the parent.
-
-Emits: `select-account`, `action`, `footer-action`, `update:modelValue`, `open`, `close`.
-
-Slots: `trigger-avatar`, `user-avatar`, `account-avatar`, `account-trailing`, `actions`, `footer`, `empty`.
-
-Example:
-
-```vue
-<script setup lang="ts">
-import { RsAccountSelector } from "@robosophy/ui-vue";
-
-const user = {
-  email: "usuario@robosophy.com",
-  initials: "UR",
-  name: "Usuario Robosophy",
-};
-
-const accounts = [
-  { id: "1", label: "Cuenta Activa SA", initials: "CA", active: true },
-  { id: "2", label: "Cuenta Inactiva SRL", initials: "CI" },
-];
-
-const actions = [{ id: "profile", label: "Ver mi perfil", icon: "manage_accounts" }];
-const footerActions = [{ id: "logout", label: "Cerrar sesion", icon: "logout", variant: "danger" }];
-</script>
-
-<template>
-  <RsAccountSelector
-    :user="user"
-    :accounts="accounts"
-    :actions="actions"
-    :footer-actions="footerActions"
-    @select-account="selectAccount"
-    @action="handleAccountAction"
-    @footer-action="handleFooterAction"
-  />
-</template>
-```
-
-## RsAvatar
-
-Use for user or account identity.
-
-Useful props: `src`, `alt`, `initials`, `size`, `interactive`.
-
-Example:
-
-```vue
-<template>
-  <RsAvatar src="/avatar.png" alt="Usuario Robosophy" size="lg" />
-  <RsAvatar initials="CA" size="sm" interactive />
-</template>
-```
-
-## RsCard
-
-Use as a reusable content container.
-
-Variants: `default`, `brand`, `success`, `warning`, `danger`.
-
-Padding: `none`, `sm`, `md`, `lg`.
-
-Useful props: `title`, `subtitle`, `variant`, `padding`, `interactive`, `as`, `ariaLabel`.
-
-Example:
-
-```vue
-<template>
-  <RsCard title="Resumen" subtitle="Estado del modulo">
-    Contenido del proyecto consumidor.
-  </RsCard>
-
-  <RsCard variant="success" title="Operacion completada">
-    Mensaje de estado.
-  </RsCard>
-</template>
-```
-
-## Module Composition Pattern
-
-For a new module, start with `RsSidebar` for navigation, `RsCard` for sections, PrimeVue `Button` for actions, and `RsAccountSelector` only when user/account switching is needed.
-
-```vue
-<script setup lang="ts">
-import Button from "primevue/button";
-import { RsCard, RsSidebar, type RsSidebarItem } from "@robosophy/ui-vue";
-
-const sidebarItems: RsSidebarItem[] = [
-  { id: "dashboard", label: "Dashboard", icon: "dashboard", active: true },
-  { id: "settings", label: "Configuracion", icon: "settings" },
-];
-
-function navigateToSection(item: RsSidebarItem) {
-  // Push a route or update local module state in the consuming app.
-}
-</script>
-
-<template>
-  <div class="module-layout">
-    <RsSidebar title="Modulo" :items="sidebarItems" @item-click="navigateToSection" />
-
-    <main>
-      <RsCard title="Dashboard" subtitle="Indicadores principales">
-        <Button>
-          <span class="action-content">
-            <span>Crear</span>
-          </span>
-        </Button>
-      </RsCard>
-    </main>
-  </div>
-</template>
-```
+# @robosophy/ui-vue Components
+
+Reference for agents and developers using Robosophy Vue components in consuming projects.
+
+## Priority
+
+When building a module or complex UI, prefer these components before creating local equivalents:
+
+- `RsSidebar`: module navigation, side menu, mobile sidebar.
+- `RsAccountSelector`: user/account selector.
+- `RsIcon`: Material Symbols icon component and PrimeVue icon helper.
+- `RsAvatar`: user/account image or initials.
+- `RsCard`: reusable content container.
+
+Keep app behavior in the consuming project. Components emit events; the app handles routing, stores, fetches, permissions, logout, and redirects.
+
+## Setup
+
+```ts
+import {
+  RsAccountSelector,
+  RsAvatar,
+  RsCard,
+  RsIcon,
+  RsSidebar,
+  rsPrimeIcon,
+} from "@robosophy/ui-vue";
+```
+
+PrimeVue apps should register the Robosophy preset and import the theme CSS:
+
+```ts
+import PrimeVue from "primevue/config";
+import RobosophyPreset from "@robosophy/prime-theme";
+import "@robosophy/prime-theme/prime.css";
+
+app.use(PrimeVue, {
+  theme: {
+    preset: RobosophyPreset,
+  },
+});
+```
+
+`RsSidebar` and `RsAccountSelector` render their interactive controls with PrimeVue components, so PrimeVue apps should use the setup above to apply PrimeVue defaults plus Robosophy Button/Menu styling.
+
+Apps without PrimeVue should import:
+
+```ts
+import "@robosophy/tokens/tokens.css";
+```
+
+RsIcon uses SVG icons inline. Enable the Vite plugin to auto-detect icons and generate an SVG sprite:
+
+```ts
+import { robosophyMaterialSymbols } from "@robosophy/ui-vue/vite";
+
+export default defineConfig({
+  plugins: [vue(), robosophyMaterialSymbols()],
+});
+```
+
+El plugin escanea automaticamente `<RsIcon name="..." />`, `rsPrimeIcon("...")` y
+`icon: "..."` en el codigo fuente. Descarga los SVGs del repositorio oficial de Google
+durante el build, los cachea localmente y genera un sprite SVG inline. Sin fuentes
+tipograficas.
+
+## RsIcon
+
+Use for Material Symbols. The Vite plugin generates an SVG sprite with only the detected
+icons and inlines it in the HTML. No fonts are loaded.
+
+```vue
+<template>
+  <RsIcon name="home" />
+  <RsIcon name="settings" family="rounded" color="primary" />
+  <RsIcon name="manage_accounts" notification />
+  <RsIcon name="manage_accounts" notification notification-color="#d80115" />
+  <Button label="Inicio" :icon="rsPrimeIcon('home')" />
+</template>
+```
+
+`notification` muestra un punto de aviso sobre el ícono (por defecto amarillo del design system,
+`--rs-color-yellow-500`). `notificationColor` permite sobreescribir el color del punto.
+
+For dynamic icon names that the scanner cannot see, add them to
+`robosophyMaterialSymbols({ include: [...] })`.
+
+### How the scanner works
+
+The plugin scans source files and detects icons using five patterns:
+
+| Pattern | Detects | Example |
+|---------|---------|---------|
+| 1 | `<RsIcon name="..." />` tags | `<RsIcon name="home" />` |
+| 2 | `rsPrimeIcon("...")` calls | `rsPrimeIcon('settings', { family: 'rounded' })` |
+| 3 | `icon: "..."` in objects | `{ icon: "inbox" }` |
+| 4 | Magic comments | `// @robosophy-icon: home` |
+| 5 | Arrays of strings (name has "icon") | `const iconNames = ["home", "search"]` |
+
+**Pattern 3** also extracts `weight` and `family` from the enclosing object:
+```ts
+{ icon: "home", weight: 200, family: "rounded" }
+// → weight 200, family "rounded"
+```
+
+**Pattern 4** (magic comments) is for cases where the scanner cannot detect an icon
+statically — typically when icon names are passed as props, stored in variables, or
+returned from functions:
+
+```ts
+// @robosophy-icon: manage_accounts
+// @robosophy-icon: settings family=rounded weight=200
+// @robosophy-icon: logout
+
+const action = { icon: "manage_accounts", label: "Perfil" };
+const getIcon = () => "settings";
+```
+
+**Pattern 5** detects arrays assigned to variables whose name contains "icon":
+```ts
+const icons = ["home", "search"];          // detected
+const sidebarIconNames = ["warning"];      // detected
+const names = ["home", "search"];          // NOT detected (no "icon" in name)
+```
+
+### When to use `include`
+
+Use the `include` option when an icon is used in many places or is controlled by
+remote configuration:
+
+```ts
+robosophyMaterialSymbols({
+  include: [
+    "home",
+    { family: "rounded", name: "settings", weight: 200 },
+  ],
+});
+```
+
+If `weight` is omitted, all valid weights (100–700) are included.
+
+### When to use magic comments
+
+Use `// @robosophy-icon:` when the icon is used in a single file and the variable
+name doesn't contain "icon":
+
+```ts
+// @robosophy-icon: manage_accounts
+// @robosophy-icon: logout
+const actions = [
+  { id: "profile", label: "Perfil", icon: "manage_accounts" },
+  { id: "logout", label: "Salir", icon: "logout" },
+];
+```
+
+### Special cases: props and iteration
+
+**Props to RsSidebar:** icons defined in the `items` array's `icon` property
+are detected by Pattern 3:
+```ts
+const items = [
+  { id: "home", label: "Home", icon: "home" },   // ✅ detected
+];
+```
+
+**Props to RsAccountSelector:** same — `icon` in action objects is detected.
+
+**v-for iteration with inline objects:** objects in the iterated array are detected:
+```vue
+<RsIcon v-for="item in items" :name="item.icon" />
+```
+
+**v-for with external variable:** not detectable — use magic comments:
+```vue
+<RsIcon v-for="name in iconNames" :name="name" />  <!-- add @robosophy-icon -->
+```
+
+### Full documentation
+
+For the complete technical reference (regex patterns, scanner architecture, plugin
+options, and known limitations), read `icon-scanner.md` in this package.
+
+For full control over icon props (fill, grade, etc.), use the slot approach:
+
+```vue
+<Button label="Favorito">
+  <template #icon>
+    <RsIcon name="favorite" fill color="danger" />
+  </template>
+</Button>
+```
+
+## RsSidebar
+
+Use for module navigation. It is controlled and presentational.
+
+Main props:
+
+```ts
+type RsSidebarItem = {
+  id: string;
+  label: string;
+  icon?: string;
+  active?: boolean;
+  disabled?: boolean;
+  visible?: boolean;
+  children?: RsSidebarItem[];
+};
+
+type RsSidebarProps = {
+  items: RsSidebarItem[];
+  footerItems?: RsSidebarItem[];
+  modules?: Array<{
+    text: string;
+    link: string;
+    active?: boolean;
+    disabled?: boolean;
+  }>;
+  navigateOnModuleSelect?: boolean;
+  title?: string;
+  icon?: string;
+  variant?: "pc" | "alta" | "cc" | "pog" | "cyo";
+  expanded?: boolean;
+  expandOnHover?: boolean;
+  mobileOpen?: boolean;
+  widthCollapsed?: string;
+  widthExpanded?: string;
+  ariaLabel?: string;
+};
+```
+
+Emits: `item-click`, `close-mobile`, `expanded-change`, `module-select`.
+
+Slots: `header`, `header-action`, `item`, `footer`.
+
+Example:
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { RsSidebar, type RsSidebarItem } from "@robosophy/ui-vue";
+
+const items: RsSidebarItem[] = [
+  { id: "liquidaciones", label: "Liquidacion", icon: "contract", active: true },
+  { id: "adquisiciones", label: "Adquisiciones", icon: "sell" },
+  {
+    id: "config",
+    label: "Config",
+    icon: "subtitles_gear",
+    children: [
+      { id: "excel", label: "Cargas Excel", icon: "upload" },
+      { id: "ayuda", label: "Ayuda", icon: "info" },
+    ],
+  },
+];
+
+const footerItems: RsSidebarItem[] = [{ id: "home", label: "Volver al home", icon: "home" }];
+const modules = [
+  { text: "Mi Alta", link: "/alta" },
+  { text: "Mi Cuenta y Orden", link: "/cyo", active: true },
+  { text: "Mi Cuenta Corriente", link: "/cc" },
+];
+const isMenuOpen = ref(false);
+
+function handleSidebarItem(item: RsSidebarItem) {
+  // Route, redirect, or store updates belong in the consuming app.
+}
+</script>
+
+<template>
+  <RsSidebar
+    title="CYO"
+    variant="cyo"
+    :items="items"
+    :modules="modules"
+    :footer-items="footerItems"
+    :mobile-open="isMenuOpen"
+    @item-click="handleSidebarItem"
+    @close-mobile="isMenuOpen = false"
+  />
+</template>
+```
+
+`modules` renders the default header dropdown. Each option has `text` and `link`. Selecting one emits `module-select`.
+
+If `navigateOnModuleSelect` is `true` the component also redirects with `window.location.href = module.link`. Set it to `false` in Storybook, tests, or apps that want to intercept navigation and route manually.
+
+Use the `header` slot only when the app needs to replace that default dropdown entirely.
+
+Project variants set sidebar icon and active colors:
+
+- `pc`: Plan Comercial, `#014A9F`.
+- `alta`: Alta, `#65AC1E`.
+- `cc`: Cuenta Corriente, `#49A0D4`.
+- `pog`: POG, `#007C2F`.
+- `cyo`: Cuenta y Orden, `#49A0D4`.
+
+## RsAccountSelector
+
+Use for user/account switching. It renders the clickable profile image trigger,
+opens the account panel, and closes it on outside click. It does not fetch,
+redirect, log out, or mutate stores.
+
+Main props:
+
+```ts
+type RsAccountSelectorUser = {
+  email: string;
+  name?: string;
+  avatarSrc?: string;
+  secondaryAvatarSrc?: string;
+  initials?: string;
+};
+
+type RsAccountSelectorAccount = {
+  id: string | number;
+  label: string;
+  avatarSrc?: string;
+  initials?: string;
+  active?: boolean;
+  disabled?: boolean;
+};
+
+type RsAccountSelectorAction = {
+  id: string;
+  label: string;
+  icon?: string;
+  visible?: boolean;
+  disabled?: boolean;
+  variant?: "ghost" | "danger";
+};
+```
+
+Use `v-model` when the open state needs to be controlled from the parent.
+
+Emits: `select-account`, `action`, `footer-action`, `update:modelValue`, `open`, `close`.
+
+Slots: `trigger-avatar`, `user-avatar`, `account-avatar`, `account-trailing`, `actions`, `footer`, `empty`.
+
+Example:
+
+```vue
+<script setup lang="ts">
+import { RsAccountSelector } from "@robosophy/ui-vue";
+
+const user = {
+  email: "usuario@robosophy.com",
+  initials: "UR",
+  name: "Usuario Robosophy",
+};
+
+const accounts = [
+  { id: "1", label: "Cuenta Activa SA", initials: "CA", active: true },
+  { id: "2", label: "Cuenta Inactiva SRL", initials: "CI" },
+];
+
+const actions = [{ id: "profile", label: "Ver mi perfil", icon: "manage_accounts" }];
+const footerActions = [{ id: "logout", label: "Cerrar sesion", icon: "logout", variant: "danger" }];
+</script>
+
+<template>
+  <RsAccountSelector
+    :user="user"
+    :accounts="accounts"
+    :actions="actions"
+    :footer-actions="footerActions"
+    @select-account="selectAccount"
+    @action="handleAccountAction"
+    @footer-action="handleFooterAction"
+  />
+</template>
+```
+
+## RsAvatar
+
+Use for user or account identity.
+
+Useful props: `src`, `alt`, `initials`, `size`, `interactive`.
+
+Example:
+
+```vue
+<template>
+  <RsAvatar src="/avatar.png" alt="Usuario Robosophy" size="lg" />
+  <RsAvatar initials="CA" size="sm" interactive />
+</template>
+```
+
+## RsCard
+
+Use as a reusable content container.
+
+Variants: `default`, `brand`, `success`, `warning`, `danger`.
+
+Padding: `none`, `sm`, `md`, `lg`.
+
+Useful props: `title`, `subtitle`, `variant`, `padding`, `interactive`, `as`, `ariaLabel`.
+
+Example:
+
+```vue
+<template>
+  <RsCard title="Resumen" subtitle="Estado del modulo">
+    Contenido del proyecto consumidor.
+  </RsCard>
+
+  <RsCard variant="success" title="Operacion completada">
+    Mensaje de estado.
+  </RsCard>
+</template>
+```
+
+## Module Composition Pattern
+
+For a new module, start with `RsSidebar` for navigation, `RsCard` for sections, PrimeVue `Button` for actions, and `RsAccountSelector` only when user/account switching is needed.
+
+```vue
+<script setup lang="ts">
+import Button from "primevue/button";
+import { RsCard, RsSidebar, type RsSidebarItem } from "@robosophy/ui-vue";
+
+const sidebarItems: RsSidebarItem[] = [
+  { id: "dashboard", label: "Dashboard", icon: "dashboard", active: true },
+  { id: "settings", label: "Configuracion", icon: "settings" },
+];
+
+function navigateToSection(item: RsSidebarItem) {
+  // Push a route or update local module state in the consuming app.
+}
+</script>
+
+<template>
+  <div class="module-layout">
+    <RsSidebar title="Modulo" :items="sidebarItems" @item-click="navigateToSection" />
+
+    <main>
+      <RsCard title="Dashboard" subtitle="Indicadores principales">
+        <Button>
+          <span class="action-content">
+            <span>Crear</span>
+          </span>
+        </Button>
+      </RsCard>
+    </main>
+  </div>
+</template>
+```