@versini/ui-panel

An accessible React slide-out panel component built with TypeScript and TailwindCSS.

The Panel component provides slide-out panels and drawers with focus management, keyboard navigation, document title management, optional animations, and customizable positioning / sizing.

Table of Contents

• Table of Contents
• Features
• Installation
• Usage
• Examples
  • Message Box Variant
  • Animated Panel (Fade)
• API
  • Panel Props

Features

• 🪟 Versatile Layouts: Standard panel and message box variants (kind prop)
• 🎯 Focus Management: Uses underlying modal primitives for proper focus trapping & return
• ♿ Accessible: ARIA compliant structure with heading, description, close control
• 🎬 Optional Animations: Slide or fade entrance animations (animation / animationType)
• 📐 Responsive Sizing: Predefined max widths (small, medium, large) above md breakpoint
• 🧩 Composable: Footer slot for actions / extra content
• 🧪 Type Safe: Fully typed props with inline documentation

Installation

npm install @versini/ui-panel

Note: This component requires TailwindCSS and the @versini/ui-styles plugin for proper styling. See the installation documentation for complete setup instructions.

Usage

import { Panel } from "@versini/ui-panel";
import { useState } from "react";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Panel</button>
      <Panel title="Panel Title" open={open} onOpenChange={setOpen}>
        Panel content goes here.
      </Panel>
    </>
  );
}

Examples

Message Box Variant

import { Panel } from "@versini/ui-panel";
import { useState } from "react";

function MessageBoxExample() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <button onClick={() => setOpen(true)}>Show Message</button>
      <Panel
        kind="messagebox"
        title="Session Expired"
        open={open}
        onOpenChange={setOpen}
        footer={
          <div className="flex justify-end gap-2">
            <button
              className="px-3 py-1 rounded bg-surface-lighter"
              onClick={() => setOpen(false)}
            >
              Dismiss
            </button>
            <button className="px-3 py-1 rounded bg-blue-600 text-white">
              Re‑authenticate
            </button>
          </div>
        }
      >
        Your session has expired. Please sign in again to continue.
      </Panel>
    </>
  );
}

Animated Panel (Fade)

<Panel
  title="Animated Panel"
  open={open}
  onOpenChange={setOpen}
  animation
  animationType="fade"
>
  Content with fade animation.
</Panel>

API

Panel Props

| Prop | Type | Default | Description | | --------------- | ------------------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | open | boolean | - | Whether the panel is open. | | onOpenChange | (open: boolean) => void | - | Callback fired when open state changes. | | title | string | - | Title displayed in the header (also used to augment document.title). | | children | React.ReactNode | - | Main content of the panel. | | footer | React.ReactNode | - | Optional footer content (actions, etc.). | | className | string | - | Extra classes applied to width wrapper (overrides default width). | | borderMode | "dark" \| "light" | "light" | Visual style of border / surface. | | kind | "panel" \| "messagebox" | "panel" | Layout variant. | | animation | boolean | false | Enable entrance animation. | | animationType | "slide" \| "fade" | "slide" | Animation style (only when animation is true). | | maxWidth | "small" \| "medium" \| "large" | "medium" | Max width applied (≥ md breakpoint) for kind="panel". | | initialFocus | number \| React.RefObject<HTMLElement \| null> | 0 | Which element to initially focus when the Panel opens. Can be a tabbable index (0 = close button), a ref to an element, or -1 to disable. |

Also inherits any valid props for the underlying modal primitives where relevant.