@soyfri/shared-library 2.0.0-beta.17 → 2.0.0-beta.19

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

@@ -0,0 +1,258 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+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;
+type Story = StoryObj<typeof Avatar>;
+
+export const Default: Story = {
+  args: {
+    items: [
+      { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=1' },
+      { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=2' },
+    ],
+  },
+  parameters: {
+    docs: { source: { code: DefaultAvatarDefinition.trim() } },
+  },
+};
+
+export const WithTypeAndText: Story = {
+  args: {
+    type: 'Owner',
+    items: [{ text: 'Maria', imageUrl: 'https://i.pravatar.cc/150?img=5' }],
+    showText: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const text = await canvas.findByTestId('text');
+    const type = await canvas.findByTestId('type');
+    expect(text).toBeInTheDocument();
+    expect(type).toHaveTextContent('Owner:');
+  },
+  parameters: {
+    docs: { source: { code: WithTypeAndTextDefinition.trim() } },
+  },
+};
+
+export const WithBadgesAndTooltip: Story = {
+  args: {
+    showTooltip: true,
+    items: [
+      { text: 'John D.', badge: 'JD', backgroundColor: '#EF5350', color: '#fff' },
+      { text: 'Alice B.', badge: 'AB', backgroundColor: '#AB47BC', color: '#fff' },
+    ],
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    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() },
+    },
+  },
+};

package/src/components/Avatar/Avatar.tsx

@@ -0,0 +1,206 @@
+import React, { useState } from 'react';
+import {
+  Avatar as MuiAvatar,
+  Box,
+  Tooltip,
+  Typography,
+  type SxProps,
+  type Theme,
+} from '@mui/material';
+import AccountCircleIcon from '@mui/icons-material/AccountCircle';
+
+export interface AvatarItem {
+  text?: string;
+  imageUrl?: string;
+  badge?: string;
+  color?: string;
+  backgroundColor?: string;
+}
+
+export type AvatarSize = 'sm' | 'md' | 'lg' | 'xl' | number;
+
+export interface AvatarProps {
+  type?: string;
+  items: AvatarItem[];
+  displayedAvatars?: number;
+  size?: AvatarSize;
+  showText?: boolean;
+  showTooltip?: boolean;
+  /**
+   * sx aplicado al contenedor raíz.
+   */
+  sx?: SxProps<Theme>;
+  /**
+   * sx aplicado a cada MuiAvatar individual (se mergea sobre los defaults).
+   */
+  avatarSx?: SxProps<Theme>;
+  className?: string;
+  /**
+   * Overlap (px) entre avatares cuando hay varios. Default depende del tamaño.
+   */
+  overlap?: number;
+}
+
+// Escala alineada con la escala de MUI (sm=32, md=40, lg=56, xl=96) con borde
+// proporcional para el efecto stacked.
+const sizeMap: Record<
+  Exclude<AvatarSize, number>,
+  { px: number; border: number; font: number; overlap: number }
+> = {
+  sm: { px: 32, border: 2, font: 14, overlap: 8 },
+  md: { px: 40, border: 2, font: 16, overlap: 10 },
+  lg: { px: 56, border: 3, font: 22, overlap: 14 },
+  xl: { px: 96, border: 4, font: 36, overlap: 20 },
+};
+
+const resolveSize = (size: AvatarSize) => {
+  if (typeof size === 'number') {
+    return {
+      px: size,
+      border: Math.max(2, Math.round(size * 0.05)),
+      font: Math.round(size * 0.4),
+      overlap: Math.round(size * 0.25),
+    };
+  }
+  return sizeMap[size];
+};
+
+const mergeSx = (base: SxProps<Theme>, extra?: SxProps<Theme>): SxProps<Theme> => {
+  if (!extra) return base;
+  const baseArr = Array.isArray(base) ? base : [base];
+  const extraArr = Array.isArray(extra) ? extra : [extra];
+  return [...baseArr, ...extraArr] as SxProps<Theme>;
+};
+
+export const Avatar: React.FC<AvatarProps> = ({
+  items,
+  type,
+  displayedAvatars = 4,
+  size = 'sm',
+  showText = true,
+  showTooltip = false,
+  sx,
+  avatarSx,
+  className,
+  overlap,
+}) => {
+  // Indexamos por URL (no por posición) para que cambios en `items` — reorder,
+  // filtrado, paginación — no hagan que un avatar válido "herede" el estado de
+  // imagen rota de un item anterior que estaba en la misma posición.
+  const [failedUrls, setFailedUrls] = useState<Set<string>>(new Set());
+
+  const handleImageError = (url: string) => {
+    setFailedUrls((prev) => {
+      if (prev.has(url)) return prev;
+      const next = new Set(prev);
+      next.add(url);
+      return next;
+    });
+  };
+
+  if (!items || items.length === 0) {
+    return null;
+  }
+
+  const s = resolveSize(size);
+  const effectiveOverlap = overlap ?? s.overlap;
+  const visibleItems = items.slice(0, displayedAvatars);
+
+  const baseAvatarSx: SxProps<Theme> = {
+    width: s.px,
+    height: s.px,
+    fontSize: s.font,
+    fontWeight: 700,
+    border: (theme) => `${s.border}px solid ${theme.palette.background.paper}`,
+    boxSizing: 'content-box',
+  };
+
+  const renderSingleAvatar = (item: AvatarItem, i: number) => {
+    const hasImage = !!item.imageUrl && !failedUrls.has(item.imageUrl);
+    const showBadgeFallback = !!item.badge;
+    const itemKey = item.imageUrl ?? `${item.text ?? ''}-${item.badge ?? ''}-${i}`;
+
+    // Defaults tirando al theme; item.color / item.backgroundColor tienen prioridad.
+    const itemSx: SxProps<Theme> = {
+      bgcolor: item.backgroundColor ?? 'action.selected',
+      color: item.color ?? 'text.secondary',
+      // Stacking manual: margen negativo al segundo avatar en adelante.
+      ...(i > 0 && { marginLeft: `-${effectiveOverlap}px` }),
+      zIndex: visibleItems.length - i,
+    };
+
+    const finalSx = mergeSx(mergeSx(baseAvatarSx, itemSx), avatarSx);
+
+    const avatarEl = (
+      <MuiAvatar
+        alt={item.text || 'User avatar'}
+        src={hasImage ? item.imageUrl : undefined}
+        imgProps={{
+          onError: () => {
+            if (item.imageUrl) handleImageError(item.imageUrl);
+          },
+        }}
+        sx={finalSx}
+      >
+        {!hasImage && showBadgeFallback ? (
+          <span aria-label={item.text}>{item.badge}</span>
+        ) : !hasImage ? (
+          <AccountCircleIcon
+            aria-label={item.text}
+            sx={{ width: '100%', height: '100%' }}
+          />
+        ) : null}
+      </MuiAvatar>
+    );
+
+    if (showTooltip && item.text) {
+      return (
+        <Tooltip key={itemKey} title={item.text}>
+          {avatarEl}
+        </Tooltip>
+      );
+    }
+    return <React.Fragment key={itemKey}>{avatarEl}</React.Fragment>;
+  };
+
+  return (
+    <Box
+      className={className}
+      sx={mergeSx(
+        {
+          display: 'flex',
+          alignItems: 'center',
+          lineHeight: 1,
+          width: 'fit-content',
+        },
+        sx,
+      )}
+    >
+      <Box sx={{ display: 'flex', alignItems: 'center' }}>
+        {visibleItems.map((item, i) => renderSingleAvatar(item, i))}
+      </Box>
+
+      {showText && items[0]?.text && (
+        <Typography
+          variant="caption"
+          sx={{
+            ml: 1,
+            fontSize: '0.75rem',
+            fontWeight: 400,
+            color: 'text.primary',
+          }}
+        >
+          {type && items.length === 1 && (
+            <Box component="span" sx={{ mr: 0.5 }}>
+              {type}:
+            </Box>
+          )}
+          {items[0].text}
+          {items.length > 1 && ` +${items.length - 1}`}
+        </Typography>
+      )}
+    </Box>
+  );
+};
+
+export default Avatar;

package/src/components/Avatar/index.ts

@@ -0,0 +1,2 @@
+export { default as Avatar } from './Avatar';
+export type { AvatarItem, AvatarProps, AvatarSize } from './Avatar';