@slithy/modal-core

The modal store. No React components, no animation, no UI.

modal-core owns the state machine and is the source of truth for which modals are open. All other modal packages depend on it. Consuming apps interact with it directly to open and close modals.

Installation

pnpm add @slithy/modal-core

Opening and Closing

All store methods are available via useModalStore.getState() for use outside React, or via the hook for reactive access.

import { useModalStore } from '@slithy/modal-core'

// Open a modal — pass any ReactNode
const id = useModalStore.getState().openModal(<MyModal />, {
  triggerEvent: event,   // event.target becomes the element focus returns to on close
})

// Close
useModalStore.getState().closeModal()        // topmost modal
useModalStore.getState().closeModal(id)      // specific modal
useModalStore.getState().closeAllModals()    // all modals

openModal options

| Option | Type | Description | |---|---|---| | id | string | Requested ID; if already in use, a unique ID is generated | | triggerEvent | ModalTriggerEvent | Enables focus return to the triggering element | | triggerElement | HTMLElement \| null | Explicit element to focus on close | | closeModals | string[] | Close specific modals before opening this one |

Reactive Access

import { useModalStore } from '@slithy/modal-core'

// Re-renders when modals change
const modals = useModalStore(s => s.modals)
const isAnyOpen = useModalStore(s => s.modals.length > 0)

// One-time read or in event handlers
const isOpen = useModalStore.getState().modalIsOpen()
const isOpen = useModalStore.getState().modalIsOpen(id)

Types

type ModalState = 'opening' | 'open' | 'closing' | 'closed'

type ModalElement = {
  id: string
  modal: React.ReactNode
  state: ModalState
  triggerElement?: HTMLElement | null
}

Accessibility

modal-core is a headless store — it renders no DOM and has no ARIA surface of its own. The actual WAI-ARIA Dialog (Modal) pattern compliance (role, aria-modal, focus trap, Escape handling, focus return, background inertness) lives in the rendering layers: see @slithy/modal-kit or @slithy/modal-spring for the full audit.

The one thing modal-core does own: capturing triggerElement on openModal (from triggerEvent.target or an explicit triggerElement override) is what makes focus-return-on-close possible in the layers above — always pass triggerEvent or triggerElement when opening a modal if you want that.

Exports

| Export | Description | |---|---| | useModalStore | Zustand-style store hook | | ModalStore | Store type | | ModalState | 'opening' \| 'open' \| 'closing' \| 'closed' | | ModalElement | Shape of a registered modal | | ModalTriggerEvent | Union of synthetic and native event types |