@etus/ui 0.1.0

package/src/components/primitives/Thumbnail/Thumbnail.tsx

@@ -0,0 +1,141 @@
+"use client"
+
+import type { ThumbnailProps } from "./Thumbnail.types"
+
+import { cva } from "class-variance-authority"
+import * as React from "react"
+
+import { cn } from "../../../lib/utils"
+import { Image } from "../Image"
+
+const thumbnailVariants = cva(
+  "relative inline-block overflow-hidden bg-[color:var(--thumbnail-root-bg)]",
+  {
+    variants: {
+      size: {
+        xs: "w-[var(--thumbnail-size-xs-width)]",
+        sm: "w-[var(--thumbnail-size-sm-width)]",
+        default: "w-[var(--thumbnail-size-default-width)]",
+        lg: "w-[var(--thumbnail-size-lg-width)]",
+        xl: "w-[var(--thumbnail-size-xl-width)]",
+      },
+      aspectRatio: {
+        square: "aspect-square",
+        video: "aspect-video",
+        wide: "aspect-[4/3]",
+      },
+      rounded: {
+        none: "rounded-[var(--thumbnail-rounded-none)]",
+        sm: "rounded-[var(--thumbnail-rounded-sm)]",
+        default: "rounded-[var(--thumbnail-rounded-default)]",
+        lg: "rounded-[var(--thumbnail-rounded-lg)]",
+        full: "rounded-[var(--thumbnail-rounded-full)]",
+      },
+    },
+    defaultVariants: {
+      size: "default",
+      aspectRatio: "square",
+      rounded: "default",
+    },
+  }
+)
+
+/**
+ * Thumbnail - A small image preview component with size and aspect ratio variants.
+ *
+ * Features:
+ * - Multiple size variants (xs, sm, default, lg, xl)
+ * - Aspect ratio control (square, video, wide)
+ * - Fallback content on error
+ * - Placeholder during loading
+ * - Click/select behavior for galleries
+ * - Selected and disabled states
+ *
+ * @example
+ * // Basic usage
+ * <Thumbnail src="/photo.jpg" alt="Photo preview" />
+ *
+ * @example
+ * // With size and aspect ratio
+ * <Thumbnail src="/video.jpg" alt="Video preview" size="lg" aspectRatio="video" />
+ *
+ * @example
+ * // Interactive with selected state
+ * <Thumbnail
+ *   src="/photo.jpg"
+ *   alt="Photo"
+ *   onClick={() => handleSelect()}
+ *   selected={isSelected}
+ * />
+ */
+function Thumbnail({
+  src,
+  alt,
+  size = "default",
+  aspectRatio = "square",
+  rounded = "default",
+  fallback,
+  placeholder,
+  onClick,
+  selected = false,
+  disabled = false,
+  className,
+  ...props
+}: ThumbnailProps) {
+  const handleClick = React.useCallback(() => {
+    if (!disabled && onClick) {
+      onClick()
+    }
+  }, [disabled, onClick])
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent) => {
+      if (disabled || !onClick) return
+
+      if (event.key === "Enter" || event.key === " ") {
+        event.preventDefault()
+        onClick()
+      }
+    },
+    [disabled, onClick]
+  )
+
+  const isInteractive = !!onClick
+
+  return (
+    <div
+      className={cn(
+        thumbnailVariants({ size, aspectRatio, rounded }),
+        // Interactive styles
+        isInteractive && !disabled && "cursor-pointer",
+        // Focus styles for interactive
+        isInteractive && "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+        // Selected state
+        selected && "ring-2 ring-primary ring-offset-2",
+        // Disabled state
+        disabled && "opacity-50 cursor-not-allowed pointer-events-none",
+        className
+      )}
+      aria-disabled={isInteractive && disabled ? true : undefined}
+      aria-pressed={isInteractive ? selected : undefined}
+      data-slot="thumbnail"
+      role={isInteractive ? "button" : undefined}
+      tabIndex={isInteractive ? (disabled ? -1 : 0) : undefined}
+      onClick={isInteractive ? handleClick : undefined}
+      onKeyDown={isInteractive ? handleKeyDown : undefined}
+      {...props}
+    >
+      <Image
+        alt={alt}
+        className="size-full"
+        data-slot="thumbnail-image"
+        fallback={fallback}
+        objectFit="cover"
+        placeholder={placeholder}
+        src={src}
+      />
+    </div>
+  )
+}
+
+export { Thumbnail, thumbnailVariants }

package/src/components/primitives/Thumbnail/Thumbnail.types.ts

@@ -0,0 +1,102 @@
+import type { thumbnailVariants } from "./Thumbnail"
+import type { VariantProps } from "class-variance-authority"
+import type { ComponentProps, ReactNode } from "react"
+
+/**
+ * Available thumbnail sizes (fixed widths)
+ * - xs: 40px
+ * - sm: 56px
+ * - default: 80px
+ * - lg: 120px
+ * - xl: 160px
+ */
+export type ThumbnailSize = "default" | "lg" | "sm" | "xl" | "xs"
+
+/**
+ * Available aspect ratios
+ * - square: 1/1
+ * - video: 16/9
+ * - wide: 4/3
+ */
+export type ThumbnailAspectRatio = "square" | "video" | "wide"
+
+/**
+ * Available border radius variants
+ */
+export type ThumbnailRounded = "default" | "full" | "lg" | "none" | "sm"
+
+/**
+ * Thumbnail component props
+ */
+export interface ThumbnailProps
+  extends Omit<ComponentProps<"div">, "placeholder">,
+    VariantProps<typeof thumbnailVariants> {
+  /**
+   * Alternative text for accessibility (required)
+   */
+  alt: string
+
+  /**
+   * Aspect ratio of the thumbnail
+   * @default "square"
+   */
+  aspectRatio?: ThumbnailAspectRatio
+
+  /**
+   * Whether the thumbnail is disabled
+   * @default false
+   */
+  disabled?: boolean
+
+  /**
+   * Content to display when image fails to load
+   */
+  fallback?: ReactNode
+
+  /**
+   * Click handler for interactive thumbnails
+   */
+  onClick?: () => void
+
+  /**
+   * Content to display while image is loading
+   */
+  placeholder?: ReactNode
+
+  /**
+   * Border radius variant
+   * @default "default"
+   */
+  rounded?: ThumbnailRounded
+
+  /**
+   * Whether the thumbnail is selected (for galleries)
+   * @default false
+   */
+  selected?: boolean
+
+  /**
+   * Size variant (fixed widths)
+   * @default "default"
+   */
+  size?: ThumbnailSize
+
+  /**
+   * Image source URL
+   */
+  src: string
+}
+
+/**
+ * Size type derived from thumbnailVariants
+ */
+export type ThumbnailSizeVariant = NonNullable<
+  VariantProps<typeof thumbnailVariants>["size"]
+>
+
+/**
+ * Rounded type derived from thumbnailVariants
+ */
+export type ThumbnailRoundedVariant = NonNullable<
+  VariantProps<typeof thumbnailVariants>["rounded"]
+>

package/src/components/primitives/Thumbnail/index.ts

@@ -0,0 +1,9 @@
+export { Thumbnail, thumbnailVariants } from "./Thumbnail"
+export type {
+  ThumbnailAspectRatio,
+  ThumbnailProps,
+  ThumbnailRounded,
+  ThumbnailRoundedVariant,
+  ThumbnailSize,
+  ThumbnailSizeVariant,
+} from "./Thumbnail.types"

package/src/components/primitives/Toggle/README.md

@@ -0,0 +1,232 @@
+# Toggle
+
+## Visão Geral
+
+O **Toggle** é um componente de controle binário do Design System ETUS que permite ao usuário alternar entre dois estados: ativado (`on`) e desativado (`off`). Construído sobre os primitivos `@radix-ui/react-toggle` e `@radix-ui/react-toggle-group`, oferece acessibilidade completa, gerenciamento de estado integrado e suporte a agrupamento (single/multiple selection).
+
+### Casos de Uso
+
+- Ativar/desativar funcionalidades (modo escuro, notificações)
+- Botões de formatação de texto (negrito, itálico, sublinhado)
+- Filtros e opções binárias em toolbars
+- Seleção de opções mutuamente exclusivas (rádio) ou múltiplas (checkbox) via `Toggle.Group`
+- Favoritar/desfavoritar itens
+
+### Classificação
+
+**Categoria:** Atom (Primitivo)
+**Dependências:** `@radix-ui/react-toggle`, `@radix-ui/react-toggle-group`, `class-variance-authority`
+
+---
+
+## Design Specs
+
+### Variantes (`variant`)
+
+| Variante | Uso | Tokens |
+|----------|-----|--------|
+| `default` | Uso geral, mínima ênfase | `bg-transparent`, hover `bg-muted` |
+| `outline` | Com borda, maior destaque | `border`, `bg-transparent`, shadow |
+
+### Tamanhos (`size`)
+
+| Tamanho | Altura | Padding | Min-Width | Uso |
+|---------|--------|---------|-----------|-----|
+| `sm` | `h-8` (32px) | `px-1.5` | `min-w-8` | Toolbars compactas, espaços restritos |
+| `default` | `h-9` (36px) | `px-2` | `min-w-9` | Uso geral |
+| `lg` | `h-10` (40px) | `px-2.5` | `min-w-10` | Maior destaque, touch-friendly |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default (off) | `bg-transparent` | Aparência base |
+| Pressed (on) | `data-[state=on]:bg-accent` | Fundo acentuado |
+| Hover | `hover:bg-muted` | Leve feedback visual |
+| Focus | `focus-visible:ring-[3px]` | Ring de 3px com `ring-ring/50` |
+| Disabled | `disabled:opacity-50` | 50% opacidade, sem interação |
+| Invalid | `aria-invalid:ring-destructive/20` | Ring vermelho para validação |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--muted             /* Hover background */
+--muted-foreground  /* Hover text */
+--accent            /* Estado ativo (on) */
+--accent-foreground /* Texto estado ativo */
+--ring              /* Focus ring */
+--input             /* Borda (outline) */
+--destructive       /* Validação inválida */
+
+/* Espaçamento */
+gap-2              /* Entre ícone e texto */
+
+/* Tipografia */
+text-sm            /* 14px */
+font-medium        /* 500 */
+
+/* Bordas */
+rounded-md         /* var(--radius) */
+
+/* Transições */
+transition-[color,box-shadow]  /* Suave em cores e sombras */
+```
+
+### data-slot
+
+```html
+<!-- Toggle Solitário -->
+<button data-slot="toggle" data-state="off">...</button>
+
+<!-- Toggle Group -->
+<div data-slot="toggle-group">
+  <button data-slot="toggle-item" data-state="on">...</button>
+  <button data-slot="toggle-item" data-state="off">...</button>
+</div>
+```
+
+---
+
+## API
+
+### Props (Toggle)
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `variant` | `"default" \| "outline"` | `"default"` | Estilo visual do toggle |
+| `size` | `"default" \| "sm" \| "lg"` | `"default"` | Tamanho do toggle |
+| `pressed` | `boolean` | - | Estado controlado (on/off) |
+| `defaultPressed` | `boolean` | `false` | Estado inicial não-controlado |
+| `onPressedChange` | `(pressed: boolean) => void` | - | Callback quando estado muda |
+| `disabled` | `boolean` | `false` | Desabilita o toggle |
+| `icon` | `ReactNode` | - | Ícone opcional exibido antes do children |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Conteúdo do toggle (ícone/texto) |
+
+> Herda todas as props de `@radix-ui/react-toggle` (Root)
+
+### Props (Toggle.Group)
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `type` | `"single" \| "multiple"` | **Obrigatório** | Tipo de seleção |
+| `value` | `string \| string[]` | - | Valor controlado |
+| `defaultValue` | `string \| string[]` | - | Valor inicial não-controlado |
+| `onValueChange` | `(value) => void` | - | Callback de mudança |
+| `variant` | `"default" \| "outline"` | - | Variante aplicada a todos os itens (herança) |
+| `size` | `"default" \| "sm" \| "lg"` | - | Tamanho aplicado a todos os itens (herança) |
+| `disabled` | `boolean` | `false` | Desabilita todos os itens do grupo |
+
+> Herda props de `@radix-ui/react-toggle-group` (Root)
+
+### Props (Toggle.Item)
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `value` | `string` | **Obrigatório** | Valor único do item no grupo |
+| `disabled` | `boolean` | `false` | Desabilita o item |
+| `icon` | `ReactNode` | - | Ícone opcional |
+| `aria-label` | `string` | - | Obrigatório se icon-only |
+
+> Herda props de `@radix-ui/react-toggle-group` (Item)
+
+### TypeScript
+
+```typescript
+import { Toggle, ToggleGroup, ToggleItem } from "@etus/ui"
+import type { ToggleProps, ToggleGroupProps, ToggleItemProps } from "@etus/ui"
+```
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { Toggle } from "@etus/ui"
+
+function Example() {
+  return <Toggle aria-label="Toggle bold">B</Toggle>
+}
+```
+
+### Com Ícones
+
+```tsx
+import { Bold, Italic } from "lucide-react"
+
+// Toggle com ícone via prop (recomendado para consistência)
+<Toggle aria-label="Bold" icon={<Bold />} />
+
+// Toggle com ícone via children
+<Toggle aria-label="Italic">
+  <Italic className="size-4" />
+</Toggle>
+```
+
+### Toggle Group (Single Selection)
+
+```tsx
+import { Toggle } from "@etus/ui"
+import { AlignLeft, AlignCenter, AlignRight } from "lucide-react"
+
+function AlignmentSelector() {
+  return (
+    <Toggle.Group type="single" defaultValue="left" aria-label="Text alignment">
+      <Toggle.Item value="left" aria-label="Align left">
+        <AlignLeft className="size-4" />
+      </Toggle.Item>
+      <Toggle.Item value="center" aria-label="Align center">
+        <AlignCenter className="size-4" />
+      </Toggle.Item>
+      <Toggle.Item value="right" aria-label="Align right">
+        <AlignRight className="size-4" />
+      </Toggle.Item>
+    </Toggle.Group>
+  )
+}
+```
+
+### Toggle Group (Multiple Selection)
+
+```tsx
+import { Toggle } from "@etus/ui"
+import { Bold, Italic, Underline } from "lucide-react"
+
+function FormatSelector() {
+  return (
+    <Toggle.Group type="multiple" aria-label="Text formatting">
+      <Toggle.Item value="bold" aria-label="Bold">
+        <Bold className="size-4" />
+      </Toggle.Item>
+      <Toggle.Item value="italic" aria-label="Italic">
+        <Italic className="size-4" />
+      </Toggle.Item>
+      <Toggle.Item value="underline" aria-label="Underline">
+        <Underline className="size-4" />
+      </Toggle.Item>
+    </Toggle.Group>
+  )
+}
+```
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso | Gerenciado por |
+|----------|-----|----------------|
+| `aria-pressed` | Estado do toggle (true/false) | Radix automaticamente |
+| `role="group"` | Identifica o container do ToggleGroup | Radix automaticamente |
+| `aria-label` | Descrição para screen readers | Manual (obrigatório para icon-only) |
+
+### Suporte a Teclado
+
+- **Toggle:** `Space` ou `Enter` ativa/desativa.
+- **ToggleGroup:** Setas direcionais navegam entre itens (roving tabindex) se `rovingFocus` ativado (default), ou `Tab` navega.
+
+---