# Toggle

A two-state button that can be either on or off.

Use Toggle for persistent formatting, bookmarking, pinning, or filter state where a pressed button is the right semantic pattern.

## Import

```ts
import { ToggleComponent } from '@edsis/component/toggle';
```

## Composition

The Angular surface keeps the same single-host shape as shadcn and Radix while mapping it to a native button selector.

```text
button[Toggle]
```

## Basic usage

Bind `[(pressed)]` when the parent should observe or control the state. The host always renders as a native button with `aria-pressed`.

```ts
readonly bookmarked = signal(false);
```

```html
<button Toggle aria-label="Toggle bookmark" [(pressed)]="bookmarked" variant="outline" size="sm">
  <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
    <path d="M6 4.75c0-.41.34-.75.75-.75h10.5c.41 0 .75.34.75.75V20l-6-3.5L6 20V4.75Z" />
  </svg>
  Bookmark
</button>
```

## Common patterns

### Outline variant

Use `variant="outline"` when the toggle should read like a bordered tool button.

```html
<button Toggle aria-label="Toggle italic" variant="outline">Italic</button>
```

### With text

Project an icon and visible text when the label should stay on screen.

```html
<button Toggle aria-label="Toggle italic">
  <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
    <path d="M10 4h8" />
    <path d="M6 20h8" />
    <path d="M14 4 10 20" />
  </svg>
  Italic
</button>
```

### Sizes

The toggle supports the shadcn size names `sm`, `default`, and `lg`.

```html
<button Toggle size="sm" variant="outline" aria-label="Toggle small">Small</button>
<button Toggle size="default" variant="outline" aria-label="Toggle default">Default</button>
<button Toggle size="lg" variant="outline" aria-label="Toggle large">Large</button>
```

### Disabled state

Set `[disabled]="true"` when the control should remain visible but unavailable.

```html
<button Toggle aria-label="Toggle bookmark" [disabled]="true">Bookmark</button>
```

### RTL

Direction comes from the surrounding layout. The API stays the same.

```html
<div dir="rtl" lang="ar" class="text-right">
  <button Toggle aria-label="تبديل الإشارة المرجعية" variant="outline" size="sm">
    إشارة مرجعية
  </button>
</div>
```

## API reference

| Input or model | Type                        | Default     |
| -------------- | --------------------------- | ----------- |
| `pressed`      | `boolean`                   | `false`     |
| `disabled`     | `boolean`                   | `false`     |
| `variant`      | `'default' \| 'outline'`    | `'default'` |
| `size`         | `'sm' \| 'default' \| 'lg'` | `'default'` |
| `class`        | `string`                    | `''`        |

Host: `button[Toggle]`.

The host exposes `aria-pressed`, `data-state="on|off"`, `data-variant`, `data-size`, and `data-disabled` for styling and testing hooks.

## Styling and theming

The primitive uses the shared library color tokens for `foreground`, `accent`, `muted`, `input`, and `ring`.

Use `class` to add width, shape, or layout utilities such as `rounded-full`, `w-full`, or responsive flex helpers.

## Accessibility

- `button[Toggle]` keeps the native button semantics and adds `aria-pressed` for the two-state pattern.
- Provide an `aria-label` for icon-only toggles.
- Use Toggle for persistent on/off state. If the control changes application state like a checkbox field, prefer the dedicated switch or checkbox primitive.
- Disabled toggles remain visible but non-interactive.

## Keyboard interactions

- Native button behavior covers Tab focus plus Enter and Space activation.
- Pressing Enter or Space toggles the `pressed` model through the native click event.

## Angular notes

- Import `ToggleComponent` into the standalone component that renders the host.
- `[(pressed)]` is the Angular replacement for React's `pressed` and `onPressedChange` pairing.
- The host always defaults to `type="button"` so it does not submit ancestor forms accidentally.

## Source parity

This Angular implementation follows the shadcn Toggle information architecture, variants, sizes, and RTL guidance while translating the runtime API to a native button host with signal-friendly two-way binding.