@soyfri/shared-library 2.0.0-beta.3 → 2.0.0-beta.4

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,
+}) => {
+  const [errorIndex, setErrorIndex] = useState<Set<number>>(new Set());
+
+  const handleImageError = (index: number) => {
+    setErrorIndex((prev) => {
+      const next = new Set(prev);
+      next.add(index);
+      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 && !errorIndex.has(i);
+    const showBadgeFallback = !!item.badge;
+
+    // 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
+        data-testid="avatar"
+        alt={item.text || 'User avatar'}
+        src={hasImage ? item.imageUrl : undefined}
+        imgProps={{
+          'data-testid': 'image',
+          onError: () => handleImageError(i),
+        } as React.ImgHTMLAttributes<HTMLImageElement>}
+        sx={finalSx}
+      >
+        {!hasImage && showBadgeFallback ? (
+          <span data-testid="badge" aria-label={item.text}>
+            {item.badge}
+          </span>
+        ) : !hasImage ? (
+          <AccountCircleIcon
+            data-testid="icon"
+            aria-label={item.text}
+            sx={{ width: '100%', height: '100%' }}
+          />
+        ) : null}
+      </MuiAvatar>
+    );
+
+    if (showTooltip && item.text) {
+      return (
+        <Tooltip key={i} title={item.text}>
+          {avatarEl}
+        </Tooltip>
+      );
+    }
+    return <React.Fragment key={i}>{avatarEl}</React.Fragment>;
+  };
+
+  return (
+    <Box
+      data-testid="avatar-container"
+      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
+          data-testid="text"
+          variant="caption"
+          sx={{
+            ml: 1,
+            fontSize: '0.75rem',
+            fontWeight: 400,
+            color: 'text.primary',
+          }}
+        >
+          {type && items.length === 1 && (
+            <Box component="span" data-testid="type" 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 @@
+export { default as Avatar} from './Avatar'

package/src/components/Button/Button.definition.ts

@@ -0,0 +1,97 @@
+export const DefaultButtonDefinition = `
+<Button variant="text">
+  Button
+</Button>
+`
+
+export const OutlinedButtonDefinition = `
+<Button variant="outlined">
+  Button
+</Button>
+`
+
+export const ContainedButtonDefinition = `
+<Button variant="contained">
+  Button
+</Button>
+`
+
+export const WithStartIconButtonDefinition = `
+<Button
+  data-testid="button"
+  startIcon={<NotificationsIcon/>}
+  variant="contained"
+>
+  Button
+</Button>
+`
+
+export const WithEndIconButtonDefinition = `
+<Button
+  data-testid="button"
+  endIcon={<NotificationsIcon/>}
+  variant="contained"
+>
+  Button
+</Button>
+`
+
+export const WithSmallSizeButtonDefinition = `
+<Button
+  data-testid="button"
+  size="small"
+  variant="contained"
+>
+  Button
+</Button>
+`
+
+export const WithLargeSizeButtonDefinition = `
+<Button
+  data-testid="button"
+  size="large"
+  variant="contained"
+>
+  Button
+</Button>
+`
+
+export const DisabledStateButtonDefinition = `
+<Button
+  data-testid="button"
+  disabled
+  variant="contained"
+>
+  Button
+</Button>`
+
+export const LoadingButtonDefinition = `
+<Button
+  data-testid="button"
+  loading
+  variant="contained"
+>
+  Button
+</Button>
+`
+
+export const LoadingIndicatorStartButtonDefinition = `
+<Button
+  data-testid="button"
+  loading
+  loadingPosition="start"
+  variant="contained"
+>
+  Button
+</Button>
+`
+
+export const LoadingIndicatorEndButtonDefinition = `
+<Button
+  data-testid="button"
+  loading
+  loadingPosition="end"
+  variant="contained"
+>
+  Button
+</Button>`