# Sheet

Present an authored native dialog from a viewport edge. (Custom element.)

Reference: https://timeless.build/docs/components/sheet/

> **Markup you author.** A `modal` sheet opens from markup: put `command="show-modal"` and `commandfor` on the trigger, naming the explicit `id` you gave the `<dialog>`. A non-modal sheet cannot, because the platform has no built-in command for `dialog.show()`, so leave `command` off that trigger and the click listener opens it. Close buttons take `command="close"` on either kind, and the platform copies the button `value` into `returnValue`. Timeless reads these attributes and never writes them, so a modal sheet still opens with JavaScript disabled.

## Markup

```html
<ui-sheet modal>
  <button class="ui-button" data-ui-part="trigger" type="button" command="show-modal" commandfor="settings-sheet">Open sheet</button>
  <dialog id="settings-sheet" aria-labelledby="settings-sheet-title" aria-describedby="settings-sheet-description">
  <div data-ui-part="drag-handle" aria-hidden="true"></div>
    <header>
      <h2 data-ui-part="title" id="settings-sheet-title">Settings</h2>
      <button class="ui-button" data-ui-variant="ghost" data-ui-size="sm" data-ui-part="close" type="button" aria-label="Close sheet" command="close" commandfor="settings-sheet">
        <svg aria-hidden="true" focusable="false" viewBox="0 0 16 16">
      <path d="m4.5 4.5 7 7m0-7-7 7" fill="none" stroke="currentColor" stroke-linecap="round" stroke-width="1"/>
    </svg>
      </button>
      <p data-ui-part="description" id="settings-sheet-description">Configure this preview.</p>
    </header>
    <section>
      <p>Changes apply immediately.</p>
    </section>
    <footer>
      <button class="ui-button" data-ui-variant="secondary" data-ui-part="close" type="button" command="close" commandfor="settings-sheet" value="cancel">Cancel</button>
      <button class="ui-button" data-ui-part="close" type="button" command="close" commandfor="settings-sheet" value="done">Done</button>
    </footer>
  </dialog>
</ui-sheet>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/sheet.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/core/dialog.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/sheet.css'
import '@timelessui/components/css/themes/atmosphere/dialog.css'
import '@timelessui/components/register/ui-sheet'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineSheetElement } from '@timelessui/components/define/ui-sheet'
defineSheetElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `trigger` | Yes | `[data-ui-part~='trigger']` | Native button that opens the sheet. On a `modal` sheet, add `command="show-modal"` and `commandfor` naming the panel id to open it from markup, before any script runs. A non-modal sheet has no declarative equivalent: the platform has no built-in command for `dialog.show()`, so its trigger stays on the click listener. |
| `panel` | Yes | `dialog` | The native `<dialog>` element. Give it an explicit `id` when a trigger or close button invokes it, since an invoker can only name an id the author wrote. |
| `close` | No | `[data-ui-part~='close']` | Optional explicit close button. Add `command="close"` and `commandfor` to close it from markup, on modal and non-modal sheets alike; the platform then also copies the button `value` into `returnValue`. |
| `drag-handle` | No | `[data-ui-part~='drag-handle']` | Optional grab area for the swipe gesture. A swipe works anywhere on the panel that is not a scrollable region, so this is an affordance rather than a requirement — but it is the one place a drag always starts, which is what a bottom sheet over a scrolling body needs. Decorative: hide it from assistive technology and keep a real close control. |
| `title` | No | `[data-ui-part~='title'], header > :where(h1, h2, h3)` | Names the sheet. Timeless points the panel's `aria-labelledby` at it, generating an id only if you left one off. A heading in the panel `<header>` counts without the token. An `aria-labelledby` you author always wins. |
| `description` | No | `[data-ui-part~='description'], header > p` | Supporting line under the title, wired with `aria-describedby` the same way. A `<p>` in the panel `<header>` counts without the token. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `modal` | presence | absent | Present to open the sheet as a modal, trapping focus and blocking the page behind it. Omit for a non-modal sheet the user can interact around. |
| `open` | presence | absent | Present to render the sheet open on load. |
| `position` | `top` · `right` · `bottom` · `left` | `right` | Which viewport edge the sheet slides in from. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-sheet>`

| Property | Type | Notes |
| --- | --- | --- |
| `modal` | `boolean` | Reflects the `modal` attribute |
| `open` | `boolean` | Reflects the `open` attribute |
| `position` | `'top' | 'right' | 'bottom' | 'left'` | Reflects the `position` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-open` | `CustomEvent<SheetEventDetail>` | Dispatched after the sheet opens. |
| `ui-close` | `CustomEvent<SheetEventDetail>` | Dispatched after the sheet closes. |
| `ui-dismiss` | `CustomEvent<SheetEventDetail>` | Dispatched when the sheet closes through Escape, a backdrop click, or a swipe past the dismiss threshold, rather than through an explicit control. The detail names which. A swipe reports `swipe` and behaves exactly like a backdrop click, because that is what it is: a pointer gesture on the overlay rather than a command. |

## Styling

Root identity: `ui-sheet`.
Required stylesheets: `tokens.css`, `core/sheet.css`, `core/button.css`, `core/dialog.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/sheet.css`, `themes/atmosphere/dialog.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-sheet-drag-offset` | How far the panel has been dragged along its own axis, written as a length while a swipe is in progress and cleared on release. The stylesheet turns it into a `translate`; setting it yourself only moves the panel. |

Design tokens this component reads (31), global and set at the theme level: `--ui-accent`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-bg-surface-subtle`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-radius-lg`, `--ui-radius-pill`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-floating`, `--ui-shadow-outline-control`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Modal Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Escape` | Close the sheet. Handled by the native `<dialog>` element. |

A `modal` sheet traps focus through `showModal()`; without `modal` the page stays interactive and focus is not trapped. Timeless restores focus to the trigger either way, including after a swipe. Naming comes from the `title` and `description` parts. Swipe-to-dismiss is an addition, never the only way out: Escape and a close control both stay, so the sheet is fully operable without a pointer.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.