# Scroll Area

Native scroll viewport with token-styled scrollbars for constrained lists,
horizontal galleries, and RTL content. It maps the shadcn Scroll Area pattern to
Angular while keeping scrolling browser-native.

## Import

```ts
import { ScrollAreaComponent } from '@edsis/component/scroll-area';
```

Import composed primitives separately when the content needs them:

```ts
import { ScrollAreaComponent } from '@edsis/component/scroll-area';
import { SeparatorComponent } from '@edsis/component/separator';
```

## Usage

Give the host a stable height or width, then place padding on inner content when
the scrollbar should stay flush with the border.

```html
<ScrollArea class="h-72 w-48 rounded-md border border-border" viewportAriaLabel="Release tags">
  <div class="p-4">
    <h4 class="mb-4 text-sm font-medium leading-none">Tags</h4>
    @for (tag of tags; track tag) {
    <div class="text-sm">{{ tag }}</div>
    <Separator class="my-2" />
    }
  </div>
</ScrollArea>
```

## Common Patterns

### Basic List

```html
<ScrollArea class="h-64 w-56 rounded-md border border-border" viewportAriaLabel="Activity log">
  <ol class="space-y-3 p-4 text-sm">
    @for (event of events; track event.id) {
    <li>{{ event.label }}</li>
    }
  </ol>
</ScrollArea>
```

### Horizontal Content

```html
<ScrollArea
  class="w-full max-w-md rounded-md border border-border"
  viewportAriaLabel="Artwork gallery"
>
  <div class="flex w-max gap-4 p-4">
    @for (artwork of artworks; track artwork.id; let index = $index) {
    <figure class="shrink-0">
      <img
        [ngSrc]="artwork.image"
        [alt]="artwork.alt"
        [priority]="index === 0"
        width="300"
        height="400"
        class="aspect-3/4 h-64 w-48 rounded-md object-cover"
      />
      <figcaption class="pt-2 text-xs text-muted-foreground">{{ artwork.caption }}</figcaption>
    </figure>
    }
  </div>
</ScrollArea>
```

### RTL Content

```html
<ScrollArea
  dir="rtl"
  lang="ar"
  class="h-72 w-48 rounded-md border border-border text-right"
  viewportAriaLabel="قائمة العلامات"
>
  <div class="p-4">...</div>
</ScrollArea>
```

## API Reference

| Input               | Type             | Default | Description                                                                                   |
| ------------------- | ---------------- | ------- | --------------------------------------------------------------------------------------------- |
| `class`             | `string`         | `''`    | Classes applied to the custom-element host. Use this for size, border, radius, and placement. |
| `viewportClass`     | `string`         | `''`    | Classes merged onto the native scroll viewport for axis control, whitespace, or overflow.     |
| `viewportAriaLabel` | `string \| null` | `null`  | Adds an accessible label and exposes the viewport as a named region.                          |
| `viewportTabIndex`  | `number`         | `0`     | Keeps the scroll viewport keyboard-focusable. Use `-1` only when focusable children suffice.  |

## Styling and Theming

The host is block-level, relatively positioned, and overflow-hidden. The inner
viewport uses native `overflow: auto`, `scrollbar-width: thin` for Firefox, and
WebKit scrollbar pseudo-elements for Chromium/Safari.

Tokens consumed:

- `--border` for the default scrollbar thumb.
- `--muted-foreground` for the hover thumb fallback.
- `--ring` for keyboard focus indication.

Pass `class` for host sizing and borders, and `viewportClass` when the viewport
itself needs adjustments such as `whitespace-nowrap`, custom padding, or axis
constraints.

## Accessibility

The component keeps native wheel, touch, momentum, and keyboard scrolling. The
viewport is focusable by default with `tabindex="0"`, so keyboard users can
scroll overflowing content even when there are no focusable descendants.

Use `viewportAriaLabel` when the scrollable region needs a spoken name. When a
label is present, the viewport is exposed as `role="region"`. Keep long lists in
logical DOM order and avoid hiding important content behind custom-only pointer
controls.

## Keyboard Interactions

When the viewport has focus, the browser handles scrolling keys:

- Arrow keys move in the matching direction.
- Page Up and Page Down scroll by a larger step.
- Home and End jump to the start or end where supported.
- Space follows the browser's scroll behavior for the focused region.

## Angular Notes

`ScrollAreaComponent` is standalone and has no provider setup. Use Angular
`@for` with stable track expressions for long content. For static artwork inside
horizontal scroll examples, import `NgOptimizedImage` and use `ngSrc`.

The component intentionally does not add a child `ScrollBar` directive. Native
scrollbars are styled by CSS and remain visible only when the content overflows.

## Source Parity

The shadcn Scroll Area docs show `ScrollArea` plus a `ScrollBar` part. This
Angular implementation preserves the same usage goals, examples, RTL guidance,
and themed scrollbar appearance while mapping `ScrollBar` to browser-native
scrollbars instead of a separate decorative child component.