Reference

TypeScript reference

Public Drawer types, controller and snapshot shapes, renderable content, close-button options and exported numeric constants.

@samline/drawer is written in strict TypeScript (strict: true, noUncheckedIndexedAccess: true, exactOptionalPropertyTypes: true, verbatimModuleSyntax: true). The root entrypoint exports the controller, options, snapshot, id, direction, snap-point, and renderable types listed below. Some useful shapes are intentionally available only through an exported type’s properties, and DrawerApi is exported from the browser subpath rather than the root.


Top-level types

import type {
  CommonDrawerDirection,
  CommonDrawerSnapPoint,
  CommonDrawerId,
  CommonDrawerOptions,
  CommonDrawerSnapshot,
  CommonDrawerController,
  VanillaDrawerController,
  VanillaDrawerOptions,
  VanillaRenderable,
} from '@samline/drawer'

CommonDrawerDirection

type CommonDrawerDirection = 'top' | 'bottom' | 'left' | 'right'

The four directions a drawer can slide from / to. See Options → direction and Recipes → Build a sidebar panel with the right direction for the matching CSS.

CommonDrawerSnapPoint

type CommonDrawerSnapPoint = number | string

A snap point value. Numbers are interpreted as fractions of the viewport or supplied custom container. Every string is parsed with parseInt and treated as an absolute pixel count: '120px' resolves to 120 px, '50%' resolves to 50 px, and decimal strings are truncated.

const drawer = createDrawer({
  id: 'filters',
  snapPoints: ['180px', '420px', 1],
  activeSnapPoint: '180px',
})

CommonDrawerId

type CommonDrawerId = string

The runtime instance id. Omitted ids are generated independently; explicit ids must be unique and cannot be changed by update().

const a = createDrawer({ id: 'account', content: 'A' })
a.update({ content: 'B' })
const b = getDrawer('account') // the identical controller

CommonDrawerOptions

The full options surface — see Options for the field-by-field reference with examples for every field.

interface CommonDrawerOptions {
  id?: CommonDrawerId
  parentId?: CommonDrawerId
  open?: boolean
  defaultOpen?: boolean
  onOpenChange?: (open: boolean) => void
  onClose?: () => void
  onAnimationEnd?: (open: boolean) => void
  onActiveSnapPointChange?: (snapPoint: CommonDrawerSnapPoint | null) => void
  onDragChange?: (percentageDragged: number) => void
  onReleaseChange?: (open: boolean) => void
  dismissible?: boolean
  modal?: boolean
  overlay?: boolean
  nested?: boolean
  direction?: CommonDrawerDirection
  snapPoints?: CommonDrawerSnapPoint[]
  fadeFromIndex?: number
  activeSnapPoint?: CommonDrawerSnapPoint | null
  closeThreshold?: number
  scrollLockTimeout?: number
  shouldScaleBackground?: boolean
  setBackgroundColorOnScale?: boolean
  handleOnly?: boolean
  fixed?: boolean
  disablePreventScroll?: boolean
  repositionInputs?: boolean
  snapToSequentialPoint?: boolean
  preventScrollRestoration?: boolean
  noBodyStyles?: boolean
  autoFocus?: boolean
  preventCycle?: boolean
}

Snapshot state shape

The runtime state is available as CommonDrawerSnapshot['state']. CommonDrawerState is the source-level interface name, but it is not a named root export.

import type { CommonDrawerSnapshot } from '@samline/drawer'

type CommonDrawerState = CommonDrawerSnapshot['state']

// Equivalent shape:
interface DrawerStateShape {
  isOpen: boolean
  activeSnapPoint: CommonDrawerSnapPoint | null
  direction: CommonDrawerDirection
  snapPoints: CommonDrawerSnapPoint[]
  dismissible: boolean
  modal: boolean
}

CommonDrawerSnapshot

The full controller snapshot.

interface CommonDrawerSnapshot {
  options: CommonDrawerOptions
  state: DrawerStateShape
}

CommonDrawerController

The headless controller interface. The VanillaDrawerController returned by createDrawer extends this with the DOM-aware helpers (element, update, destroy).

interface CommonDrawerController {
  getSnapshot: () => CommonDrawerSnapshot
  setOpen: (open: boolean) => CommonDrawerSnapshot
  setActiveSnapPoint: (snapPoint: CommonDrawerSnapPoint | null) => CommonDrawerSnapshot
  update: (options: Partial<Omit<CommonDrawerOptions, 'id'>>) => CommonDrawerSnapshot
  destroy: () => void
  subscribe: (listener: (snapshot: CommonDrawerSnapshot) => void) => () => void
}

setOpen and setActiveSnapPoint return the new snapshot. update shallow-merges options. destroy disposes listeners and makes the controller terminal. subscribe registers a listener; the returned function unsubscribes it.

import { createDrawerController } from '@samline/drawer'

const controller = createDrawerController({
  id: 'filters',
  direction: 'bottom',
  defaultOpen: true,
})

controller.getSnapshot().state.isOpen // true
controller.setOpen(false)
const unsubscribe = controller.subscribe(snapshot => {
  console.log(snapshot.state.isOpen)
})
unsubscribe()

VanillaDrawerController

interface VanillaDrawerController extends CommonDrawerController {
  id: CommonDrawerId
  element: HTMLElement | null
  options: VanillaDrawerOptions
  update: (options?: Omit<VanillaDrawerOptions, 'id'>) => CommonDrawerSnapshot
  destroy: () => void
}
  • id — the runtime instance id.
  • element — the current host element (<div data-drawer-vanilla-root>) when mounted, or null after destroy().
  • options — the latest merged options passed to the root entrypoint.
  • update(options?) — merge new options into the same id and re-render. Returns the resulting snapshot. Registry queries always return the identical controller.
  • destroy() — disposes this instance and all its listeners; destroyed handles cannot be reused.
import { createDrawer } from '@samline/drawer'

const drawer = createDrawer({ id: 'filters', title: 'Filters' })
drawer.element // <div data-drawer-vanilla-root="filters">
drawer.id // 'filters'
drawer.options // { id: 'filters', title: 'Filters', ... }

drawer.update({ activeSnapPoint: '420px' })
drawer.destroy()
drawer.element // null

VanillaDrawerOptions

CommonDrawerOptions extended with the vanilla-only host / trigger / handle / content / className options. See Options → Vanilla-only options for the full list with examples.

interface VanillaDrawerOptions extends CommonDrawerOptions {
  container?: HTMLElement | null
  triggerElement?: HTMLElement | null
  triggerText?: string
  showHandle?: boolean
  handleClassName?: string
  handleAriaLabel?: string
  ariaLabel?: string
  ariaLabelledBy?: string
  ariaDescribedBy?: string
  title?: VanillaRenderable
  titleVisuallyHidden?: boolean
  description?: VanillaRenderable
  descriptionVisuallyHidden?: boolean
  content?: VanillaRenderable
  overlayClassName?: string
  contentClassName?: string
  closeButton?:
    | boolean
    | {
        className?: string
        icon?: string | Element
        ariaLabel?: string
      }
}

container is the mount target; the default is document.body. Every drawer gets its own host inside the target, so multiple drawers can share a container without sharing mount state.

VanillaRenderable

type VanillaRenderable = string | number | HTMLElement | (() => HTMLElement) | null | undefined

The value shape accepted by title, description, and content. Strings and numbers are mounted as text nodes. Pre-built HTMLElement instances are moved into the slot (not cloned). Thunks are invoked once per dialog DOM build and must return an HTMLElement. null / undefined render nothing for that slot.

import { createDrawer } from '@samline/drawer'

// 1. String
createDrawer({ id: 'a', content: 'Hello' })

// 2. Number
createDrawer({ id: 'b', title: 3 })

// 3. Pre-built element
const form = document.createElement('form')
createDrawer({ id: 'c', content: form })

// 4. Lazy thunk
createDrawer({
  id: 'd',
  content: () => {
    const node = document.createElement('div')
    node.textContent = new Date().toLocaleTimeString()
    return node
  },
})

// 5. Empty
createDrawer({ id: 'e' })

See Options → Renderable content and Recipes → Custom HTML content for the full contract and end-to-end patterns.

Close-button option shape

The source names this object VanillaCloseButtonOptions, but that name is not exported from the package root. Derive it from the exported options type when a standalone alias is useful:

import type { VanillaDrawerOptions } from '@samline/drawer'

type CloseButtonOptions = Exclude<NonNullable<VanillaDrawerOptions['closeButton']>, boolean>

const closeButton: CloseButtonOptions = {
  className: 'absolute top-5 right-5',
  icon: '✕',
  ariaLabel: 'Close filters',
}

Its equivalent shape is { className?: string; icon?: string | Element; ariaLabel?: string }.

  • className — class applied to the button. The consumer can use it to position the button (e.g. absolute top-5 right-5).
  • icon — icon content. A string is rendered as text inside a <span aria-hidden="true">. An element, HTML or SVG, is appended as-is. Defaults to an inline SVG X drawn with currentColor.
  • ariaLabel — accessible label for the button. Defaults to 'Close'.

The full mount lifecycle of the button is in Options → closeButton and the recipe in Recipes → Built-in close button.


Factory

The vanilla createDrawer(options?) factory returns a VanillaDrawerController. The headless createDrawerController(options?) factory returns a CommonDrawerController with no DOM awareness.

import { createDrawer, createDrawerController } from '@samline/drawer'

function createDrawer(options?: VanillaDrawerOptions): VanillaDrawerController
function createDrawerController(options?: CommonDrawerOptions): CommonDrawerController

createDrawer registers and renders a per-id host. createDrawerController is headless: it publishes snapshots but does not mount DOM, run registry lifecycle callbacks, or honor DOM-only options such as content, container, triggerElement, closeButton, or any *ClassName.

import { createDrawerController } from '@samline/drawer'

// Headless: useful for tests, workers, or building a different renderer.
const headless = createDrawerController({ id: 'x', defaultOpen: true })
headless.getSnapshot().state.isOpen // true

Numeric constants

The numeric defaults used by the runtime live in src/constants.ts and are re-exported as plain numbers from the root entrypoint. Use them when you want to reason about timing without re-deriving values.

Constant Default Meaning
TRANSITIONS.DURATION 0.5 CSS transition duration in seconds.
TRANSITIONS.EASE [0.32, 0.72, 0, 1] CSS cubic-bezier() ease curve.
VELOCITY_THRESHOLD 0.4 Minimum velocity (px / ms) for a release to dismiss the drawer.
CLOSE_THRESHOLD 0.25 Minimum fraction of the drawer dimension the user must drag past for release to dismiss.
SCROLL_LOCK_TIMEOUT 100 Drag-permission cooldown in milliseconds after a gesture is blocked by scroll state.
BORDER_RADIUS 8 Pixel value the scale-background pipeline uses for the page-shell border-radius at percentageDragged = 0.
NESTED_DISPLACEMENT 16 Pixel displacement used when an open child scales and shifts its parent drawer.
WINDOW_TOP_OFFSET 26 Pixel offset used by scale-background math and the mobile Firefox viewport layout.
DRAG_CLASS 'drawer-dragging' Class added after axis intent is accepted and removed on release or cancellation.
import { TRANSITIONS, VELOCITY_THRESHOLD, CLOSE_THRESHOLD } from '@samline/drawer'

console.log(TRANSITIONS.DURATION) // 0.5
console.log(TRANSITIONS.EASE) // [0.32, 0.72, 0, 1]
console.log(VELOCITY_THRESHOLD) // 0.4
console.log(CLOSE_THRESHOLD) // 0.25

Override the shared easing/duration in your own stylesheet by targeting [data-drawer] (see CSS styling) — the constants are not wired through options.


Browser module additions

The optional browser subpath exports the DrawerApi type, the named/default Drawer namespace and the same seven named functions as the root. There is no second registry or browser-only factory.

import { Drawer, type DrawerApi } from '@samline/drawer/browser'
const drawer = Drawer.createDrawer({ title: 'Filters' })

Browser global

The standalone IIFE installs window.Drawer with that same API; a module import does not install it.

import type { DrawerApi } from '@samline/drawer/browser'
declare global {
  interface Window {
    Drawer?: DrawerApi
  }
}
window.Drawer?.createDrawer({ title: 'Filters', content: 'Body' })

The removed browser/newDrawer/available aliases are listed in the v5 changelog. Use getDrawers() for inspection and native template factories for HTML.


Subscribing to state changes

The controller is observable. subscribe fires the listener immediately with the current snapshot, then on every subsequent state change.

import { createDrawer } from '@samline/drawer'

const drawer = createDrawer({ id: 'filters', title: 'Filters' })

const unsubscribe = drawer.subscribe(snapshot => {
  console.log('isOpen:', snapshot.state.isOpen)
  console.log('snap:', snapshot.state.activeSnapPoint)
  console.log('direction:', snapshot.state.direction)
})

// Later, when the subscriber is no longer needed:
unsubscribe()

getSnapshot() returns the current snapshot without subscribing — useful for read-only consumers.

import { createDrawer } from '@samline/drawer'

const drawer = createDrawer({ id: 'filters' })
const snap = drawer.getSnapshot()
if (snap.state.isOpen) {
  // safe to read state synchronously
}

setOpen(), setActiveSnapPoint(), and update() all return the new snapshot, so you can inspect the result without an extra getSnapshot() call.

import { createDrawer } from '@samline/drawer'

const drawer = createDrawer({ id: 'filters' })
drawer.update({ title: 'Filters', activeSnapPoint: '420px' })
const next = drawer.setOpen(true)
console.log(next.state.isOpen) // true

See also

  • Options — every field with defaults and examples.
  • Recipes — end-to-end patterns.
  • CSS styling — data-attribute and class contract for theming.
  • Browser global — using window.Drawer from a plain <script> tag.