# Aspect Ratio

Displays content within a fixed width-to-height ratio.

Use Aspect Ratio for image frames, media placeholders, thumbnail cards, and any layout where the container height should derive from the available width.

## Import

```ts
import { AspectRatioComponent } from '@edsis/component/aspect-ratio';
```

## Usage

Bind a numeric ratio with `[ratio]`. The host renders as a block-level container with `position: relative`, so projected children can fill the box with `h-full w-full` or positioned overlays.

```html
<div class="w-full max-w-sm">
  <AspectRatio [ratio]="16 / 9" class="overflow-hidden rounded-lg border border-border bg-muted/30">
    <img
      src="https://avatar.vercel.sh/shadcn1"
      alt="Demo media"
      class="h-full w-full object-cover"
    />
  </AspectRatio>
</div>
```

## Common patterns

### Landscape media

Use `16 / 9` for hero images, video posters, and card thumbnails.

```html
<div class="max-w-sm">
  <AspectRatio [ratio]="16 / 9" class="overflow-hidden rounded-lg bg-muted">
    <img src="..." alt="Landscape" class="h-full w-full object-cover" />
  </AspectRatio>
</div>
```

### Square avatars or gallery tiles

Use `1` for square media slots.

```html
<div class="max-w-48">
  <AspectRatio [ratio]="1" class="overflow-hidden rounded-xl bg-muted">
    <img src="..." alt="Square tile" class="h-full w-full object-cover" />
  </AspectRatio>
</div>
```

### Portrait cards

Use `9 / 16` when the design calls for tall image treatments.

```html
<div class="max-w-40">
  <AspectRatio [ratio]="9 / 16" class="overflow-hidden rounded-xl bg-muted">
    <img src="..." alt="Portrait tile" class="h-full w-full object-cover" />
  </AspectRatio>
</div>
```

### Figure with caption

Keep captions outside the ratio box so the media height stays stable while text can grow naturally.

```html
<figure class="max-w-sm">
  <AspectRatio [ratio]="16 / 9" class="overflow-hidden rounded-lg border border-border bg-muted/30">
    <img src="..." alt="Beautiful landscape" class="h-full w-full object-cover" />
  </AspectRatio>
  <figcaption class="mt-2 text-sm text-muted-foreground">Beautiful landscape</figcaption>
</figure>
```

## API reference

### `AspectRatioComponent`

| Input   | Type     | Default  | Description                                                                                 |
| ------- | -------- | -------- | ------------------------------------------------------------------------------------------- |
| `ratio` | `number` | required | The desired width-to-height ratio. Use Angular expressions like `16 / 9`, `1`, or `9 / 16`. |
| `class` | `string` | `''`     | Additional utility classes for the host container.                                          |

## Styling and theming

Base host classes: `relative block w-full`.

Pass utility classes for rounded corners, borders, backgrounds, shadows, and max width. Add `overflow-hidden` when the projected media should be clipped to the container radius. The projected child should usually use `h-full w-full object-cover` for image-like content.

## Accessibility

Aspect Ratio has no built-in semantics beyond its host element. Accessibility comes from the projected content.

- Provide meaningful `alt` text for images.
- Prefer `<figure>` and `<figcaption>` when media needs visible labeling.
- Do not place essential text only inside a background image.

## Keyboard interactions

Aspect Ratio has no keyboard interaction. It should not receive focus unless the projected content contains an interactive control.

## Angular notes

- Import `AspectRatioComponent` directly into the standalone component that owns the media layout.
- Use `[ratio]` with a numeric Angular expression instead of a React prop like `ratio={16 / 9}`.
- The component uses a block-level custom element so width utilities such as `w-full` and `max-w-sm` behave predictably.
- The projected content is wrapped in an absolute fill container so overlays and full-height media stay aligned with the ratio box.

## Source parity

This Angular implementation follows the shadcn Aspect Ratio examples for landscape, square, portrait, and RTL-friendly media layouts while translating React props and fill behavior to Angular bindings and projected content.