SolidJS Dismissible Layers Utility

Common errors

• TypeError: Cannot read properties of null (reading 'ownerDocument')

  cause The `element` prop passed to `Dismissible` was null or undefined when the component attempted to register global event listeners.
  fix Ensure the DOM element for `Dismissible` is rendered and its ref (`element` prop) is available before `Dismissible` attempts to initialize. Use SolidJS's `createSignal` for the ref and conditionally render the dismissible content with `Show` or `onMount` to guarantee the element exists.

• Dismissible layer not closing when expected (e.g., clicking outside or pressing Escape)

  cause The `enabled` prop is `false`, or the `onDismiss` callback does not correctly update the state controlling the `enabled` prop.
  fix Verify that `enabled={true}` when the dismissible layer should be active. Confirm that the `onDismiss` callback correctly updates the state variable (e.g., `setOpen(false)`) that controls the `enabled` prop, causing the component to react and dismiss.

• Nested dismissible layers close prematurely or in the wrong order.

  cause While `solid-dismissible` supports nesting, the parent layers might not be correctly 'disabled' or 'paused' when a child layer is active, causing parent dismissal events to propagate.
  fix Ensure that when a child dismissible layer is `enabled`, any parent dismissible layers have their `enabled` prop dynamically set to `false` or leverage the `activeDismissibles` signal to prevent parent dismissal logic from firing until the child is dismissed. The library handles the core nesting logic, but your state management must reflect the active layer hierarchy.

Warnings

• breaking As a package in early development (version 0.1.1), `solid-dismissible` may introduce breaking changes in future minor versions (e.g., 0.2.0, 0.3.0) without adhering strictly to semantic versioning until version 1.0.0 is reached.
  Fix: Review the package's changelog or GitHub releases for specific breaking changes when upgrading to new minor versions. Update your component implementations accordingly.
• gotcha Incorrectly configuring the `element` prop or allowing it to be `null` or `undefined` can lead to the dismissible component not functioning, as it relies on a valid DOM element to track outside interactions.
  Fix: Ensure the `element` prop is always set to a `Signal<HTMLElement | null>` that will eventually resolve to a valid DOM element ref, usually via `ref={setElementRef}`.
• gotcha When nesting `Dismissible` components, improper management of the `enabled` prop or `onDismiss` callbacks can lead to unintended dismissal of parent layers or prevent deeper layers from dismissing correctly. The library is designed to support nesting, but careful state management is required.
  Fix: Always ensure the `enabled` prop accurately reflects the current visibility/interactability of a dismissible layer. Use the `onDismiss` callback to update the state that controls `enabled`, and consider how nested components' `onDismiss` might affect their parents.

Install

• npm install solid-dismissible npm
• yarn add solid-dismissible yarn
• pnpm add solid-dismissible pnpm

Imports

• Dismissible
  wrong:

  import { Dismissible } from 'solid-dismissible'

  correct:

  import Dismissible from 'solid-dismissible'

  Dismissible is the default export of the package, providing the core component for managing dismissible layers.
• activeDismissibles
  wrong:

  import activeDismissibles from 'solid-dismissible'

  correct:

  import { activeDismissibles } from 'solid-dismissible'

  This is a named export, a SolidJS signal that tracks the IDs of currently active dismissible layers for advanced management.
• DismissibleProps

  import type { DismissibleProps } from 'solid-dismissible'

  Import the TypeScript type for the Dismissible component's props for type-safe usage.

Quickstart

This example demonstrates how to create a basic dismissible dialog component using `solid-dismissible`, managing its open state and dismissal logic.

import { createSignal, Show, type Component } from 'solid-js';
import Dismissible from 'solid-dismissible';

const DialogContent: Component<{ open: boolean; setOpen: (open: boolean) => void }> = (props) => {
  const [contentRef, setContentRef] = createSignal<HTMLElement | null>(null);

  return (
    <Dismissible
      element={contentRef}
      enabled={props.open()}
      onDismiss={() => props.setOpen(false)}
      // Optional: Prevent dismissal on outside focus
      // dismissOnOutsideFocus={false}
      // Optional: Prevent dismissal on escape key
      // dismissOnEscape={false}
    >
      <Show when={props.open()}>
        <div
          ref={setContentRef}
          tabIndex={-1} // Make div focusable for testing focus dismissal
          style={{
            border: '1px solid gray',
            padding: '20px',
            background: 'white',
            position: 'fixed',
            top: '50%',
            left: '50%',
            transform: 'translate(-50%, -50%)',
            zIndex: 1000
          }}
        >
          <h2>Dismissible Dialog</h2>
          <p>Click outside or press Escape to dismiss.</p>
          <button onClick={() => props.setOpen(false)}>Close</button>
        </div>
      </Show>
    </Dismissible>
  );
};

const App: Component = () => {
  const [dialogOpen, setDialogOpen] = createSignal(false);

  return (
    <div>
      <button onClick={() => setDialogOpen(true)}>Open Dialog</button>
      <DialogContent open={dialogOpen} setOpen={setDialogOpen} />
      <p>This is content behind the dialog.</p>
      <p>Try opening the dialog and clicking outside or pressing Escape.</p>
    </div>
  );
};

export default App;