# @zerolith/a11y

Import from `@zerolith/a11y`. Generated from the source; every signature below is what the published types declare.

## Functions

### focusOrigin

```ts
function focusOrigin(doc?: Document): FocusOriginMonitor
```

Watches how focus arrives, the way Angular CDK's focus monitor does: a key
pressed before focus moves means keyboard, a pointer pressed means pointer
or touch, anything else means program. The origin is a signal and a
`data-focus-origin` attribute on the root element, so a stylesheet can
show focus rings for keyboard users only: `[data-focus-origin="keyboard"] :focus { outline: ... }`.

Source: `packages/a11y/src/focus.ts:284`

### focusTrap

```ts
function focusTrap(options?: FocusTrapOptions): (element: Element) => void
```

A `ref` that keeps Tab and Shift+Tab inside the element, pulls focus back
when it lands outside, moves focus in once the element is in the document,
and returns it where it came from when the element's template is removed.
With traps on several elements, as when a dialog opens a confirmation,
only the newest acts until its template is removed.

Source: `packages/a11y/src/focus.ts:55`

### focusables

```ts
function focusables(root: Element): HTMLElement[]
```

The elements inside `root` that take Tab focus, in document order, skipping anything hidden.

Source: `packages/a11y/src/focus.ts:31`

### rovingTabindex

```ts
function rovingTabindex(options?: RovingOptions): (element: Element) => void
```

A `ref` for a composite widget: exactly one item is in the Tab order, the
arrow keys, Home, and End move between items, and the item that was
selected or checked starts as the current one. Disabled, hidden, and
inert items are skipped, as the children of a collapsed tree item are.

Source: `packages/a11y/src/focus.ts:170`

### createAnnouncer

```ts
function createAnnouncer(doc?: Document): Announcer
```

Creates a pair of live regions, one polite and one assertive, appended to
the document body at once, so assistive technology knows them before the
first message, and hidden visually by inline styles, which hold in any
document `doc` names. Each announcement clears the
region and writes the message on the next task, so repeating a message
is read again.

Source: `packages/a11y/src/announce.ts:31`

### forcedColors

```ts
function forcedColors(): ReadableSignal<boolean>
```

True while the user agent is in forced colors mode, such as Windows high contrast, where author colors are replaced by system ones.

Source: `packages/a11y/src/media.ts:31`

### mediaQuery

```ts
function mediaQuery(query: string): ReadableSignal<boolean>
```

A media query as a signal that follows the query's matches; false wherever `matchMedia` does not exist, such as on the server.

Source: `packages/a11y/src/media.ts:9`

### reducedMotion

```ts
function reducedMotion(): ReadableSignal<boolean>
```

True while the user has asked for reduced motion.

Source: `packages/a11y/src/media.ts:37`

## Interfaces

### FocusOriginMonitor

```ts
interface FocusOriginMonitor
```

What `focusOrigin` returns.

- `readonly origin: ReadableSignal<FocusOrigin | null>`: The origin of the current focus, or null while nothing in the document has focus.
- `dispose(): void`: Removes the listeners and the attribute.

Source: `packages/a11y/src/focus.ts:269`

### FocusTrapOptions

```ts
interface FocusTrapOptions
```

Options for `focusTrap`.

- `initial?: string | HTMLElement | false`: What receives focus on attach: a selector inside the element, an element, or false to leave focus alone. Defaults to the first focusable, or the element itself.
- `restore?: boolean`: Returns focus to the element that had it before the trap attached. Defaults to true.

Source: `packages/a11y/src/focus.ts:40`

### RovingOptions

```ts
interface RovingOptions
```

Options for `rovingTabindex`.

- `items?: string`: The selector of the items. Defaults to the ARIA roles of composite widgets plus `[data-roving]`.
- `orientation?: "horizontal" | "vertical" | "both"`: Which arrow keys move: `horizontal` (left and right), `vertical` (up and down), or `both`. Defaults to both.
- `loop?: boolean`: Wraps from the last item to the first and back. Defaults to true.

Source: `packages/a11y/src/focus.ts:152`

### Announcer

```ts
interface Announcer
```

What `createAnnouncer` returns.

- `announce(message: string, politeness?: Politeness): void`: Queues a message for the live region; `assertive` interrupts what is being read.
- `dispose(): void`: Removes the live regions.

Source: `packages/a11y/src/announce.ts:15`

## Types

### FocusOrigin

```ts
type FocusOrigin = "keyboard" | "pointer" | "touch" | "program"
```

How the element that has focus got it.

Source: `packages/a11y/src/focus.ts:266`

### Politeness

```ts
type Politeness = "polite" | "assertive"
```

How urgently a message is read.

Source: `packages/a11y/src/announce.ts:12`

## Constants

### visuallyHidden

```ts
const visuallyHidden: Styles
```

The clip pattern that hides an element visually while assistive technology still reads it.

Source: `packages/a11y/src/announce.ts:7`