@soyfri/shared-library 1.5.0 → 2.0.0-beta.0

package/src/components/Avatar/Avatar.definitions.ts

@@ -0,0 +1,162 @@
+export const DefaultAvatarDefinition = `
+import { Avatar } from './Avatar';
+
+export const DefaultAvatarExample = () => (
+    <Avatar
+        items={[
+            { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=1' },
+            { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=2' },
+        ]}
+    />
+);
+`;
+
+export const WithTypeAndTextDefinition = `
+import { Avatar } from './Avatar';
+
+export const WithTypeAndTextExample = () => (
+    <Avatar
+        type="Owner"
+        items={[{ text: 'Maria', imageUrl: 'https://i.pravatar.cc/150?img=5' }]}
+        showText
+    />
+);
+`;
+
+export const WithBadgesAndTooltipDefinition = `
+import { Avatar } from './Avatar';
+
+export const WithBadgesAndTooltipExample = () => (
+    <Avatar
+        showTooltip
+        items={[
+            { text: 'John D.', badge: 'JD', backgroundColor: '#EF5350', color: '#fff' },
+            { text: 'Alice B.', badge: 'AB', backgroundColor: '#AB47BC', color: '#fff' },
+        ]}
+    />
+);
+`;
+
+export const SizeSmallDefinition = `
+import { Avatar } from './Avatar';
+
+export const SizeSmallExample = () => (
+    <Avatar
+        size="sm"
+        items={[
+            { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=11' },
+            { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=12' },
+            { text: 'User Three', imageUrl: 'https://i.pravatar.cc/150?img=13' },
+        ]}
+    />
+);
+`;
+
+export const SizeMediumDefinition = `
+import { Avatar } from './Avatar';
+
+export const SizeMediumExample = () => (
+    <Avatar
+        size="md"
+        items={[
+            { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=21' },
+            { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=22' },
+            { text: 'User Three', imageUrl: 'https://i.pravatar.cc/150?img=23' },
+        ]}
+    />
+);
+`;
+
+export const SizeLargeDefinition = `
+import { Avatar } from './Avatar';
+
+export const SizeLargeExample = () => (
+    <Avatar
+        size="lg"
+        items={[
+            { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=31' },
+            { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=32' },
+        ]}
+    />
+);
+`;
+
+export const SizeExtraLargeDefinition = `
+import { Avatar } from './Avatar';
+
+export const SizeExtraLargeExample = () => (
+    <Avatar
+        size="xl"
+        items={[{ text: 'Maria', imageUrl: 'https://i.pravatar.cc/150?img=5' }]}
+        showText={false}
+    />
+);
+`;
+
+export const NumericSizeDefinition = `
+import { Avatar } from './Avatar';
+
+export const NumericSizeExample = () => (
+    <Avatar
+        size={72}
+        items={[
+            { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=41' },
+            { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=42' },
+        ]}
+        showText={false}
+    />
+);
+`;
+
+export const FallbackIconDefinition = `
+import { Avatar } from './Avatar';
+
+export const FallbackIconExample = () => (
+    <Avatar
+        items={[
+            { text: 'Without image' },
+            { text: 'Broken image', imageUrl: 'https://example.invalid/broken.png' },
+        ]}
+        showTooltip
+    />
+);
+`;
+
+export const DisplayedAvatarsLimitDefinition = `
+import { Avatar } from './Avatar';
+
+export const DisplayedAvatarsLimitExample = () => (
+    <Avatar
+        displayedAvatars={3}
+        items={[
+            { text: 'User 1', imageUrl: 'https://i.pravatar.cc/150?img=51' },
+            { text: 'User 2', imageUrl: 'https://i.pravatar.cc/150?img=52' },
+            { text: 'User 3', imageUrl: 'https://i.pravatar.cc/150?img=53' },
+            { text: 'User 4', imageUrl: 'https://i.pravatar.cc/150?img=54' },
+            { text: 'User 5', imageUrl: 'https://i.pravatar.cc/150?img=55' },
+        ]}
+    />
+);
+`;
+
+export const CustomStylingDefinition = `
+import { Avatar } from './Avatar';
+
+export const CustomStylingExample = () => (
+    <Avatar
+        size="md"
+        items={[
+            { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=61' },
+            { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=62' },
+        ]}
+        sx={{
+            p: 1,
+            borderRadius: 2,
+            bgcolor: 'action.hover',
+        }}
+        avatarSx={{
+            border: (theme) => '3px solid ' + theme.palette.primary.main,
+        }}
+    />
+);
+`;

package/src/components/Avatar/Avatar.stories.tsx

@@ -1,14 +1,72 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Avatar, AvatarProps } from './Avatar';
 import { within, expect } from 'storybook/test';
+import { Avatar } from './Avatar';
+import {
+  DefaultAvatarDefinition,
+  WithTypeAndTextDefinition,
+  WithBadgesAndTooltipDefinition,
+  SizeSmallDefinition,
+  SizeMediumDefinition,
+  SizeLargeDefinition,
+  SizeExtraLargeDefinition,
+  NumericSizeDefinition,
+  FallbackIconDefinition,
+  DisplayedAvatarsLimitDefinition,
+  CustomStylingDefinition,
+} from './Avatar.definitions';
 
 const meta: Meta<typeof Avatar> = {
   title: 'Components/Avatar',
   component: Avatar,
   parameters: {
     layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Avatar basado en MUI Avatar con soporte para stacking, tooltips, fallback a icono/badge y passthrough de sx. Admite imagen, texto y badge por cada item.',
+      },
+    },
   },
   tags: ['autodocs'],
+  argTypes: {
+    items: {
+      control: 'object',
+      description: 'Array de `AvatarItem` (text/imageUrl/badge/color/backgroundColor).',
+    },
+    type: {
+      control: 'text',
+      description: 'Etiqueta que antecede al texto cuando hay un único item (ej. "Owner: Maria").',
+    },
+    displayedAvatars: {
+      control: 'number',
+      description: 'Número máximo de avatares visibles. El resto se contabiliza como `+N`.',
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg', 'xl'],
+      description: 'Tamaño del avatar. Acepta presets (`sm | md | lg | xl`) o un número libre en px.',
+    },
+    showText: {
+      control: 'boolean',
+      description: 'Muestra el texto al lado del avatar.',
+    },
+    showTooltip: {
+      control: 'boolean',
+      description: 'Muestra el tooltip con `item.text` al hover.',
+    },
+    overlap: {
+      control: 'number',
+      description: 'Overlap en px entre avatares cuando hay varios (override del default por tamaño).',
+    },
+    sx: {
+      control: false,
+      description: 'sx del contenedor raíz. Se mergea sobre los defaults.',
+    },
+    avatarSx: {
+      control: false,
+      description: 'sx aplicado a cada MuiAvatar individual (borde, colores, etc).',
+    },
+  },
 };
 
 export default meta;
@@ -21,6 +79,9 @@ export const Default: Story = {
       { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=2' },
     ],
   },
+  parameters: {
+    docs: { source: { code: DefaultAvatarDefinition.trim() } },
+  },
 };
 
 export const WithTypeAndText: Story = {
@@ -36,6 +97,9 @@ export const WithTypeAndText: Story = {
     expect(text).toBeInTheDocument();
     expect(type).toHaveTextContent('Owner:');
   },
+  parameters: {
+    docs: { source: { code: WithTypeAndTextDefinition.trim() } },
+  },
 };
 
 export const WithBadgesAndTooltip: Story = {
@@ -51,4 +115,144 @@ export const WithBadgesAndTooltip: Story = {
     const badges = await canvas.findAllByTestId('badge');
     expect(badges.length).toBe(2);
   },
+  parameters: {
+    docs: { source: { code: WithBadgesAndTooltipDefinition.trim() } },
+  },
+};
+
+export const SizeSmall: Story = {
+  args: {
+    size: 'sm',
+    items: [
+      { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=11' },
+      { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=12' },
+      { text: 'User Three', imageUrl: 'https://i.pravatar.cc/150?img=13' },
+    ],
+  },
+  parameters: {
+    docs: { source: { code: SizeSmallDefinition.trim() } },
+  },
+};
+
+export const SizeMedium: Story = {
+  args: {
+    size: 'md',
+    items: [
+      { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=21' },
+      { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=22' },
+      { text: 'User Three', imageUrl: 'https://i.pravatar.cc/150?img=23' },
+    ],
+  },
+  parameters: {
+    docs: { source: { code: SizeMediumDefinition.trim() } },
+  },
+};
+
+export const SizeLarge: Story = {
+  args: {
+    size: 'lg',
+    items: [
+      { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=31' },
+      { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=32' },
+    ],
+  },
+  parameters: {
+    docs: { source: { code: SizeLargeDefinition.trim() } },
+  },
+};
+
+export const SizeExtraLarge: Story = {
+  args: {
+    size: 'xl',
+    items: [{ text: 'Maria', imageUrl: 'https://i.pravatar.cc/150?img=5' }],
+    showText: false,
+  },
+  parameters: {
+    docs: { source: { code: SizeExtraLargeDefinition.trim() } },
+  },
+};
+
+export const NumericSize: Story = {
+  args: {
+    size: 72,
+    items: [
+      { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=41' },
+      { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=42' },
+    ],
+    showText: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Pasando un número en `size` se calcula automáticamente el borde, font-size y overlap proporcional.',
+      },
+      source: { code: NumericSizeDefinition.trim() },
+    },
+  },
+};
+
+export const FallbackIcon: Story = {
+  args: {
+    showTooltip: true,
+    items: [
+      { text: 'Without image' },
+      { text: 'Broken image', imageUrl: 'https://example.invalid/broken.png' },
+    ],
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Cuando no hay imagen (o falla la carga) y no hay badge, cae al icono `AccountCircle`.',
+      },
+      source: { code: FallbackIconDefinition.trim() },
+    },
+  },
+};
+
+export const DisplayedAvatarsLimit: Story = {
+  args: {
+    displayedAvatars: 3,
+    items: [
+      { text: 'User 1', imageUrl: 'https://i.pravatar.cc/150?img=51' },
+      { text: 'User 2', imageUrl: 'https://i.pravatar.cc/150?img=52' },
+      { text: 'User 3', imageUrl: 'https://i.pravatar.cc/150?img=53' },
+      { text: 'User 4', imageUrl: 'https://i.pravatar.cc/150?img=54' },
+      { text: 'User 5', imageUrl: 'https://i.pravatar.cc/150?img=55' },
+    ],
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Solo se renderizan `displayedAvatars` avatares; el resto se cuenta en el `+N` del texto.',
+      },
+      source: { code: DisplayedAvatarsLimitDefinition.trim() },
+    },
+  },
+};
+
+export const CustomStyling: Story = {
+  args: {
+    size: 'md',
+    items: [
+      { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=61' },
+      { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=62' },
+    ],
+    sx: {
+      p: 1,
+      borderRadius: 2,
+      bgcolor: 'action.hover',
+    },
+    avatarSx: {
+      border: (theme) => `3px solid ${theme.palette.primary.main}`,
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Demo del passthrough de `sx` (contenedor) y `avatarSx` (cada avatar). El consumidor puede overridear bordes, colores y el layout del wrapper sin tocar el componente.',
+      },
+      source: { code: CustomStylingDefinition.trim() },
+    },
+  },
 };