@adamosuiteservices/ui 1.4.5 → 1.5.6

package/docs/components/ui/scroll-area.md

@@ -0,0 +1,357 @@
+# ScrollArea
+
+Componente de área de scroll personalizada con scrollbars estilizados. Construido sobre Radix UI Scroll Area para proporcionar una experiencia de scroll consistente y accesible.
+
+## Características Principales
+
+- **Scrollbars personalizados**: Scrollbars estilizados que reemplazan los nativos del navegador
+- **Orientación flexible**: Soporte para scroll vertical y horizontal
+- **Radix UI**: Construido sobre `@radix-ui/react-scroll-area` para accesibilidad y funcionalidad robusta
+- **Focus management**: Manejo automático de focus con ring visual
+- **Data slots**: Atributos `data-slot` para targeting CSS específico
+- **Responsive**: Funciona en todos los dispositivos y navegadores
+
+## Importación
+
+```tsx
+import { ScrollArea, ScrollBar } from "@adamosuiteservices/ui/scroll-area";
+```
+
+## Uso Básico
+
+### Scroll Vertical
+
+Uso más común, scroll vertical automático.
+
+```tsx
+import { ScrollArea } from "@adamosuiteservices/ui/scroll-area";
+import { Separator } from "@adamosuiteservices/ui/separator";
+
+<ScrollArea className="h-72 w-48 rounded-md border">
+  <div className="p-4">
+    <h4 className="mb-4 text-sm font-medium leading-none">Tags</h4>
+    {Array.from({ length: 50 }).map((_, i) => (
+      <div key={i}>
+        <div className="text-sm">Tag {i + 1}</div>
+        {i !== 49 && <Separator className="my-2" />}
+      </div>
+    ))}
+  </div>
+</ScrollArea>;
+```
+
+### Scroll Horizontal
+
+Para contenido que se desplaza horizontalmente.
+
+```tsx
+import { ScrollArea, ScrollBar } from "@adamosuiteservices/ui/scroll-area";
+
+<ScrollArea className="w-96 whitespace-nowrap rounded-md border">
+  <div className="flex w-max space-x-4 p-4">
+    {Array.from({ length: 20 }).map((_, i) => (
+      <figure key={i} className="shrink-0">
+        <div className="overflow-hidden rounded-md">
+          <img
+            src={`/images/${i + 1}.jpg`}
+            alt={`Photo ${i + 1}`}
+            className="h-[200px] w-[300px] object-cover"
+          />
+        </div>
+        <figcaption className="pt-2 text-xs text-muted-foreground">
+          Photo by Artist {i + 1}
+        </figcaption>
+      </figure>
+    ))}
+  </div>
+  <ScrollBar orientation="horizontal" />
+</ScrollArea>;
+```
+
+**Nota**: Para scroll horizontal, debes agregar explícitamente `<ScrollBar orientation="horizontal" />`.
+
+### Ambos Scrollbars
+
+Contenido que desborda en ambas direcciones.
+
+```tsx
+<ScrollArea className="h-[400px] w-[600px] rounded-md border">
+  <div className="w-[800px] p-4">
+    <h4 className="mb-4 text-sm font-medium leading-none">
+      Wide Content with Vertical Scroll
+    </h4>
+    <div className="space-y-2">
+      {Array.from({ length: 30 }).map((_, i) => (
+        <div key={i} className="text-sm p-3 bg-muted rounded">
+          Item {i + 1} - This is wide content that needs horizontal scroll.
+        </div>
+      ))}
+    </div>
+  </div>
+  <ScrollBar orientation="horizontal" />
+</ScrollArea>
+```
+
+## Componentes
+
+### ScrollArea
+
+Componente principal del área de scroll.
+
+#### Props
+
+| Prop        | Tipo                             | Descripción                  |
+| ----------- | -------------------------------- | ---------------------------- |
+| `className` | `string`                         | Clases CSS adicionales       |
+| `children`  | `ReactNode`                      | Contenido del área de scroll |
+| `...props`  | `ScrollAreaPrimitive.Root` props | Props de Radix UI ScrollArea |
+
+**Estilos por defecto**: `relative`
+
+**Data slot**: `scroll-area`
+
+#### Características internas
+
+- **Viewport automático**: Incluye `ScrollAreaPrimitive.Viewport` con focus management
+- **ScrollBar vertical**: Incluye automáticamente un `ScrollBar` vertical por defecto
+- **Corner**: Incluye `ScrollAreaPrimitive.Corner` para el espacio entre scrollbars
+
+### ScrollBar
+
+Componente de scrollbar personalizado.
+
+#### Props
+
+| Prop          | Tipo                                            | Default      | Descripción                           |
+| ------------- | ----------------------------------------------- | ------------ | ------------------------------------- |
+| `orientation` | `"vertical" \| "horizontal"`                    | `"vertical"` | Orientación del scrollbar             |
+| `className`   | `string`                                        | -            | Clases CSS adicionales                |
+| `...props`    | `ScrollAreaPrimitive.ScrollAreaScrollbar` props | -            | Props de Radix UI ScrollAreaScrollbar |
+
+**Estilos por defecto**:
+
+- Base: `flex touch-none p-px transition-colors select-none`
+- Vertical: `h-full w-2.5 border-l border-l-transparent`
+- Horizontal: `h-2.5 flex-col border-t border-t-transparent`
+
+**Data slot**: `scroll-area-scrollbar`
+
+**Thumb**: Incluye internamente un `ScrollAreaThumb` con estilo `bg-border relative flex-1 rounded-full`
+
+## Ejemplos
+
+### Texto Largo (Terms & Conditions)
+
+```tsx
+<ScrollArea className="h-[400px] w-[500px] rounded-md border p-4">
+  <h3 className="mb-4 text-lg font-semibold">Terms and Conditions</h3>
+  <div className="space-y-4 text-sm">
+    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>
+    <p>Duis aute irure dolor in reprehenderit in voluptate...</p>
+    {/* More paragraphs */}
+  </div>
+</ScrollArea>
+```
+
+### Con Badges/Tags
+
+```tsx
+import { Badge } from "@adamosuiteservices/ui/badge";
+
+const tags = ["React", "TypeScript", "Next.js", "Tailwind"];
+
+<ScrollArea className="h-72 w-80 rounded-md border p-4">
+  <h4 className="mb-4 text-sm font-medium leading-none">Technologies</h4>
+  <div className="flex flex-wrap gap-2">
+    {tags.map((tag) => (
+      <Badge key={tag} variant="secondary">
+        {tag}
+      </Badge>
+    ))}
+  </div>
+</ScrollArea>;
+```
+
+### Alturas Personalizadas
+
+Controla la altura visible con clases de Tailwind.
+
+```tsx
+{
+  /* Small */
+}
+<ScrollArea className="h-32 w-64 rounded-md border p-4">
+  {/* Content */}
+</ScrollArea>;
+
+{
+  /* Medium */
+}
+<ScrollArea className="h-64 w-64 rounded-md border p-4">
+  {/* Content */}
+</ScrollArea>;
+
+{
+  /* Large */
+}
+<ScrollArea className="h-96 w-64 rounded-md border p-4">
+  {/* Content */}
+</ScrollArea>;
+
+{
+  /* Full viewport height */
+}
+<ScrollArea className="h-screen w-64 rounded-md border p-4">
+  {/* Content */}
+</ScrollArea>;
+```
+
+## Casos de Uso
+
+### Listas de Navegación
+
+```tsx
+<ScrollArea className="h-[600px] w-64 rounded-md border">
+  <nav className="p-4 space-y-1">
+    {menuItems.map((item) => (
+      <a
+        key={item.id}
+        href={item.href}
+        className="block px-3 py-2 rounded-md hover:bg-accent"
+      >
+        {item.label}
+      </a>
+    ))}
+  </nav>
+</ScrollArea>
+```
+
+### Chat/Messages
+
+```tsx
+<ScrollArea className="h-[500px] w-full rounded-md border p-4">
+  <div className="space-y-4">
+    {messages.map((message) => (
+      <div key={message.id} className="flex gap-3">
+        <Avatar />
+        <div>
+          <p className="text-sm font-medium">{message.author}</p>
+          <p className="text-sm text-muted-foreground">{message.content}</p>
+        </div>
+      </div>
+    ))}
+  </div>
+</ScrollArea>
+```
+
+### Galería de Imágenes (Horizontal)
+
+```tsx
+<ScrollArea className="w-full whitespace-nowrap rounded-md border">
+  <div className="flex gap-4 p-4">
+    {images.map((image) => (
+      <img
+        key={image.id}
+        src={image.url}
+        alt={image.alt}
+        className="h-48 w-64 object-cover rounded-md"
+      />
+    ))}
+  </div>
+  <ScrollBar orientation="horizontal" />
+</ScrollArea>
+```
+
+### Tabla con Scroll
+
+```tsx
+<ScrollArea className="h-[400px] w-full rounded-md border">
+  <table className="w-full">
+    <thead>
+      <tr>
+        <th>Column 1</th>
+        <th>Column 2</th>
+        <th>Column 3</th>
+      </tr>
+    </thead>
+    <tbody>
+      {data.map((row) => (
+        <tr key={row.id}>
+          <td>{row.col1}</td>
+          <td>{row.col2}</td>
+          <td>{row.col3}</td>
+        </tr>
+      ))}
+    </tbody>
+  </table>
+</ScrollArea>
+```
+
+## Personalización
+
+### Estilos del Scrollbar
+
+Puedes personalizar el scrollbar usando las clases de Tailwind:
+
+```tsx
+<ScrollArea className="h-72 w-48 rounded-md border">
+  <div className="p-4">{/* Content */}</div>
+</ScrollArea>;
+
+{
+  /* Custom scrollbar color */
+}
+<ScrollBar className="[&>div]:bg-primary" />;
+```
+
+### Ocultar Scrollbar en Móviles
+
+```tsx
+<ScrollArea className="h-72 w-full rounded-md border">
+  <div className="p-4">{/* Content */}</div>
+  <ScrollBar className="hidden md:flex" />
+</ScrollArea>
+```
+
+## Accesibilidad
+
+- ✅ **Focus visible**: Ring automático al hacer focus con teclado
+- ✅ **Keyboard navigation**: Soporte completo para navegación con teclado (flechas, Page Up/Down, Home/End)
+- ✅ **Touch support**: `touch-none` en scrollbar para prevenir conflictos con gestos
+- ✅ **ARIA**: Radix UI maneja automáticamente los atributos ARIA necesarios
+
+## Data Slots
+
+Los siguientes atributos `data-slot` están disponibles para targeting CSS:
+
+- `scroll-area` - Contenedor principal
+- `scroll-area-viewport` - Viewport del contenido
+- `scroll-area-scrollbar` - Scrollbar (vertical u horizontal)
+- `scroll-area-thumb` - Thumb del scrollbar
+
+### Ejemplo de uso con data-slot
+
+```css
+[data-slot="scroll-area-scrollbar"] {
+  width: 12px;
+}
+
+[data-slot="scroll-area-thumb"] {
+  background: hsl(var(--primary));
+}
+```
+
+## Notas de Implementación
+
+- El componente usa internamente las clases con prefijo `adm:` para evitar conflictos de estilos
+- `ScrollArea` incluye automáticamente un `ScrollBar` vertical por defecto
+- Para scroll horizontal, debes agregar explícitamente `<ScrollBar orientation="horizontal" />`
+- El viewport tiene `size-full` (width y height 100%) para ocupar todo el espacio disponible
+- El scrollbar tiene `transition-colors` para efectos suaves
+- El thumb del scrollbar usa `bg-border` por defecto, configurable con variables CSS de tema
+
+## Referencias
+
+- Basado en [Radix UI Scroll Area](https://www.radix-ui.com/docs/primitives/components/scroll-area)
+- Inspirado en [shadcn/ui ScrollArea](https://ui.shadcn.com/docs/components/scroll-area)
+- Compatible con todos los navegadores modernos

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adamosuiteservices/ui",
-  "version": "1.4.5",
+  "version": "1.5.6",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -11,6 +11,7 @@
     "./styles.css": "./dist/styles.css",
     "./custom-layered-styles.css": "./dist/custom-layered-styles.css",
     "./colors.css": "./dist/colors.css",
+    "./custom-scroll-bar.css": "./dist/custom-scroll-bar.css",
     "./fonts.css": "./dist/fonts.css",
     "./radius.css": "./dist/radius.css",
     "./space.css": "./dist/space.css",
@@ -239,6 +240,7 @@
     "@radix-ui/react-portal": "^1.1.9",
     "@radix-ui/react-progress": "^1.1.7",
     "@radix-ui/react-radio-group": "^1.3.8",
+    "@radix-ui/react-scroll-area": "^1.2.10",
     "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-separator": "^1.1.7",
     "@radix-ui/react-slider": "^1.3.6",
@@ -282,4 +284,4 @@
     "vite": "^7.1.7",
     "vite-plugin-dts": "^4.5.4"
   }
-}
+}