@teo-garcia/react-shared 0.1.9 → 1.2.0

package/README.md

@@ -2,12 +2,11 @@
 
 # @teo-garcia/react-shared
 
-**Shared React components, hooks, utilities, and adapters for fullstack web
-templates**
+**Shared React hooks, utilities, and components for fullstack web templates**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![npm](https://img.shields.io/npm/v/@teo-garcia/react-shared?color=blue)](https://www.npmjs.com/package/@teo-garcia/react-shared)
-[![React](https://img.shields.io/badge/React-18+-61DAFB?logo=react&logoColor=black)](https://react.dev)
+[![React](https://img.shields.io/badge/React-19+-61DAFB?logo=react&logoColor=black)](https://react.dev)
 
 Part of the [@teo-garcia/templates](https://github.com/teo-garcia/templates)
 ecosystem
@@ -16,141 +15,170 @@ ecosystem
 
 ---
 
-## Features
-
-| Area              | Includes                                                           |
-| ----------------- | ------------------------------------------------------------------ |
-| **Components**    | `ThemeSwitch`, `ViewportInfo`, `ErrorBoundary`                     |
-| **Hooks**         | `useHealthcheck` with React Query                                  |
-| **Utilities**     | Environment helpers and MSW setup helpers                          |
-| **Adapters**      | Theme and environment adapters for Next.js and Vite-based apps     |
-| **Compatibility** | Framework-agnostic usage across Next.js and React Router templates |
-| **Type Safety**   | TypeScript definitions for all exports                             |
-| **Packaging**     | Tree-shakeable module exports                                      |
-
 ## Requirements
 
-- React 18+
+- React 19+
 - TypeScript
-- Tailwind CSS for included component styles
+- Tailwind CSS in the consuming app (for `Skeleton` and `cn`)
 
-## Quick Start
+## Installation
 
 ```bash
-# Install the package
 pnpm add @teo-garcia/react-shared
 
-# Required peer dependencies
-pnpm add react react-dom lucide-react
-
-# Optional for hooks
+# Optional: hooks that use TanStack Query
 pnpm add @tanstack/react-query
 
-# Optional for MSW helpers
-pnpm add -D msw
+# Optional: test utilities
+pnpm add -D @testing-library/react
 ```
 
-### Components
+---
 
-```tsx
-import { ThemeSwitch } from '@teo-garcia/react-shared/components'
-import { useNextThemesAdapter } from '@teo-garcia/react-shared/adapters/theme'
+## Hooks
 
-export function App() {
-  const themeAdapter = useNextThemesAdapter()
-  return <ThemeSwitch themeAdapter={themeAdapter} />
-}
-```
+All hooks are framework-agnostic and SSR-safe.
 
-### Hooks
+| Hook                              | Description                                                                                    |
+| --------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `useDebounce(value, delay)`       | Returns a debounced copy of `value` that updates after `delay` ms of inactivity                |
+| `useLocalStorage(key, initial)`   | `localStorage`-backed state as a tuple `[value, set, remove]`. Returns `initial` on the server |
+| `useMediaQuery(query)`            | Tracks a CSS media query. Returns `false` on the server                                        |
+| `useOnClickOutside(ref, handler)` | Fires `handler` on `mousedown`/`touchstart` outside the given ref                              |
+| `usePrevious(value)`              | Returns the previous render's value of a state or prop                                         |
+| `useIsomorphicLayoutEffect`       | `useLayoutEffect` on the client, `useEffect` on the server — eliminates SSR warnings           |
 
-```tsx
-import { useHealthcheck } from '@teo-garcia/react-shared/hooks'
+Import paths: `@teo-garcia/react-shared/hooks/<hook-name>`
 
-export function HealthStatus() {
-  const { data, isLoading, error } = useHealthcheck({
-    url: 'http://localhost:3000/api/healthcheck',
-  })
+---
 
-  if (isLoading) return <div>Checking...</div>
-  if (error) return <div>Health check failed</div>
-  return <div>Status: {data?.status}</div>
-}
-```
+## Components
 
-### Utilities
+### `ErrorBoundary`
 
-```tsx
-import {
-  isClient,
-  isDevelopment,
-} from '@teo-garcia/react-shared/utils'
+Catches thrown errors in child trees and renders a fallback. Supports four
+fallback patterns, auto-reset on prop changes, and focus-restoring "Try again"
+in the default UI.
 
-if (isDevelopment()) {
-  console.log('Running in dev mode')
-}
+| Prop                | Type                                          | Description                                                            |
+| ------------------- | --------------------------------------------- | ---------------------------------------------------------------------- |
+| `FallbackComponent` | `ComponentType<{ error, resetError }>`        | Highest-priority fallback — receives the error and a reset callback    |
+| `fallbackRender`    | `(props: { error, resetError }) => ReactNode` | Render-prop fallback                                                   |
+| `fallback`          | `ReactNode \| (error) => ReactNode`           | Static element or function fallback                                    |
+| `resetKeys`         | `unknown[]`                                   | When any value in the array changes, the boundary resets automatically |
+| `onError`           | `(error, errorInfo) => void`                  | Called after every caught error — use for logging or tracking          |
+| `onReset`           | `() => void`                                  | Called whenever the boundary resets                                    |
 
-if (isClient()) {
-  localStorage.setItem('key', 'value')
-}
-```
+Import path: `@teo-garcia/react-shared/components/error-boundary`
+
+---
 
-### Adapters
+### `VisuallyHidden`
 
-```tsx
-import { ViewportInfo } from '@teo-garcia/react-shared/components'
-import { viteEnvironmentAdapter } from '@teo-garcia/react-shared/adapters/environment'
+Renders content that is invisible on screen but fully accessible to assistive
+technologies. Zero dependencies, RSC-safe, no Tailwind required.
 
-export function App() {
-  return <ViewportInfo environmentAdapter={viteEnvironmentAdapter} />
-}
-```
+Use for: icon-only button labels, skip-navigation links, form hints,
+screen-reader-only status messages.
+
+Import path: `@teo-garcia/react-shared/components/visually-hidden`
+
+---
+
+### `Skeleton`
+
+A single-line loading placeholder using Tailwind's `animate-pulse`. Accepts
+`className` for sizing so it adapts to any layout without wrapper divs.
+
+Use for: card skeletons, text line placeholders, avatar placeholders, table row
+stubs.
+
+Import path: `@teo-garcia/react-shared/components/skeleton`
 
-## Exports
+---
+
+### `Portal`
+
+Renders children into a target DOM node outside the React tree via
+`createPortal`. SSR-safe — returns `null` until mounted. Treats
+`container={null}` as "not ready" and defers rendering, which pairs cleanly with
+`useRef`.
+
+Use for: modals, drawers, tooltips, toasts — anything that must escape
+`overflow: hidden` or stacking context.
+
+Import path: `@teo-garcia/react-shared/components/portal`
+
+---
+
+### `FocusTrap`
+
+Traps keyboard focus within its container while `active`. Tab wraps from last to
+first element; Shift+Tab wraps from first to last. Restores focus to the
+previously focused element on deactivation or unmount.
 
-| Export | Description |
-| ------ | ----------- |
-| `@teo-garcia/react-shared/components` | Shared React UI components |
-| `@teo-garcia/react-shared/hooks` | Shared React hooks |
-| `@teo-garcia/react-shared/utils` | Framework-agnostic utilities |
-| `@teo-garcia/react-shared/adapters/theme` | Theme adapters |
-| `@teo-garcia/react-shared/adapters/environment` | Environment adapters |
+Use for: modals, dialogs, drawers, dropdowns — any overlay where focus must not
+escape.
 
-## Included APIs
+| Prop           | Type      | Default | Description                                     |
+| -------------- | --------- | ------- | ----------------------------------------------- |
+| `active`       | `boolean` | `true`  | Enables or disables the trap                    |
+| `initialFocus` | `boolean` | `true`  | Focuses the first focusable child on activation |
 
-### Components
+Import path: `@teo-garcia/react-shared/components/focus-trap`
 
-- `ThemeSwitch` - Theme switcher button
-- `ViewportInfo` - Viewport dimensions display for development
-- `ErrorBoundary` - Error boundary component
+---
+
+## Utilities
+
+### `cn`
 
-### Hooks
+Merges Tailwind class names with conflict resolution — later classes win. Built
+on `clsx` + `tailwind-merge`.
 
-- `useHealthcheck` - API health check hook
+Import path: `@teo-garcia/react-shared/utils/cn`
+
+---
 
-### Utilities
+## Test utilities
 
-- `isDevelopment()` - Check if running in development mode
-- `isProduction()` - Check if running in production mode
-- `isServer()` - Check if running on the server
-- `isClient()` - Check if running in the browser
-- `setupMSWBrowser()` - Setup MSW for browser usage
-- `setupMSWServer()` - Setup MSW for Node.js and test usage
+Helpers for wrapping components under test with a `QueryClient` provider.
 
-### Adapters
+| Export                              | Description                                                                                        |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `createWrapper(options?)`           | Returns a `QueryClientProvider` wrapper component. Create at module level, not inside render calls |
+| `renderWithProviders(ui, options?)` | Convenience wrapper around `@testing-library/react` `render` with `createWrapper` pre-applied      |
 
-- `useNextThemesAdapter()` - Adapter for `next-themes`
-- `createCustomThemeAdapter()` - Adapter for custom theme providers
-- `nextEnvironmentAdapter` - Environment adapter for Next.js
-- `viteEnvironmentAdapter` - Environment adapter for Vite-based apps
+Accepts an optional `queryClient` in options to inject a custom client (useful
+for testing query state).
 
-## Notes
+Import path: `@teo-garcia/react-shared/test-utils`
 
-- Components assume Tailwind CSS is available in the consuming app.
-- Hooks and adapters are designed to be framework-agnostic where possible.
-- Consumers should import only the module paths they need.
+---
+
+## All export paths
+
+| Path                                                          | Contents                               |
+| ------------------------------------------------------------- | -------------------------------------- |
+| `@teo-garcia/react-shared/components`                         | All components (barrel)                |
+| `@teo-garcia/react-shared/components/error-boundary`          | `ErrorBoundary`, `FallbackProps`       |
+| `@teo-garcia/react-shared/components/focus-trap`              | `FocusTrap`                            |
+| `@teo-garcia/react-shared/components/portal`                  | `Portal`                               |
+| `@teo-garcia/react-shared/components/skeleton`                | `Skeleton`                             |
+| `@teo-garcia/react-shared/components/visually-hidden`         | `VisuallyHidden`                       |
+| `@teo-garcia/react-shared/hooks`                              | All hooks (barrel)                     |
+| `@teo-garcia/react-shared/hooks/use-debounce`                 | `useDebounce`                          |
+| `@teo-garcia/react-shared/hooks/use-isomorphic-layout-effect` | `useIsomorphicLayoutEffect`            |
+| `@teo-garcia/react-shared/hooks/use-local-storage`            | `useLocalStorage`                      |
+| `@teo-garcia/react-shared/hooks/use-media-query`              | `useMediaQuery`                        |
+| `@teo-garcia/react-shared/hooks/use-on-click-outside`         | `useOnClickOutside`                    |
+| `@teo-garcia/react-shared/hooks/use-previous`                 | `usePrevious`                          |
+| `@teo-garcia/react-shared/utils/cn`                           | `cn`                                   |
+| `@teo-garcia/react-shared/test-utils`                         | `createWrapper`, `renderWithProviders` |
+
+---
 
-## Related Packages
+## Related packages
 
 | Package                                                                                    | Description         |
 | ------------------------------------------------------------------------------------------ | ------------------- |

package/dist/components/aspect-ratio/aspect-ratio.d.ts

@@ -0,0 +1,17 @@
+import { type HTMLAttributes } from 'react';
+interface AspectRatioProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Width-to-height ratio expressed as a number.
+     * Common values: `16/9`, `4/3`, `1` (square), `3/4` (portrait).
+     * Defaults to `16/9`.
+     */
+    ratio?: number;
+}
+/**
+ * Maintains a fixed aspect ratio for its content.
+ * RSC-safe. No Tailwind required.
+ * Use for responsive images, videos, iframes, and map embeds.
+ */
+export declare function AspectRatio({ ratio, style, children, ...props }: AspectRatioProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=aspect-ratio.d.ts.map

package/dist/components/aspect-ratio/aspect-ratio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aspect-ratio.d.ts","sourceRoot":"","sources":["../../../src/components/aspect-ratio/aspect-ratio.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,OAAO,CAAA;AAE3C,UAAU,gBAAiB,SAAQ,cAAc,CAAC,cAAc,CAAC;IAC/D;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAc,EACd,KAAK,EACL,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,gBAAgB,2CAclB"}

package/dist/components/aspect-ratio/aspect-ratio.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Maintains a fixed aspect ratio for its content.
+ * RSC-safe. No Tailwind required.
+ * Use for responsive images, videos, iframes, and map embeds.
+ */
+export function AspectRatio({ ratio = 16 / 9, style, children, ...props }) {
+    return (_jsx("div", { style: {
+            position: 'relative',
+            width: '100%',
+            paddingBottom: `${(1 / ratio) * 100}%`,
+            ...style,
+        }, ...props, children: _jsx("div", { style: { position: 'absolute', inset: 0 }, children: children }) }));
+}

package/dist/components/aspect-ratio/index.d.ts

@@ -0,0 +1,2 @@
+export { AspectRatio } from './aspect-ratio.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/aspect-ratio/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/aspect-ratio/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/components/aspect-ratio/index.js

@@ -0,0 +1 @@
+export { AspectRatio } from './aspect-ratio.js';

package/dist/components/debug-json/debug-json.d.ts

@@ -0,0 +1,14 @@
+interface DebugJSONProps {
+    value: unknown;
+    label?: string;
+    /** Expand the details element by default. Defaults to `false`. */
+    open?: boolean;
+}
+/**
+ * Renders any value as pretty-printed JSON inside a collapsible `<details>`.
+ * Dev-only: returns `null` in production.
+ * Better than `console.log` during development — stays on screen and updates reactively.
+ */
+export declare function DebugJSON({ value, label, open }: DebugJSONProps): import("react/jsx-runtime").JSX.Element | null;
+export {};
+//# sourceMappingURL=debug-json.d.ts.map

package/dist/components/debug-json/debug-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-json.d.ts","sourceRoot":"","sources":["../../../src/components/debug-json/debug-json.tsx"],"names":[],"mappings":"AAEA,UAAU,cAAc;IACtB,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kEAAkE;IAClE,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAY,EAAE,EAAE,cAAc,kDAwCvE"}

package/dist/components/debug-json/debug-json.js

@@ -0,0 +1,32 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Renders any value as pretty-printed JSON inside a collapsible `<details>`.
+ * Dev-only: returns `null` in production.
+ * Better than `console.log` during development — stays on screen and updates reactively.
+ */
+export function DebugJSON({ value, label, open = false }) {
+    if (process.env.NODE_ENV === 'production')
+        return null;
+    return (_jsxs("details", { open: open, style: {
+            fontFamily: 'ui-monospace, monospace',
+            fontSize: '0.75rem',
+            border: '1px solid rgba(0,0,0,0.1)',
+            borderRadius: '6px',
+            padding: '0.5rem 0.625rem',
+            margin: '0.5rem 0',
+            background: 'rgba(0,0,0,0.03)',
+            maxWidth: '100%',
+            overflow: 'auto',
+        }, children: [_jsx("summary", { style: {
+                    cursor: 'pointer',
+                    userSelect: 'none',
+                    color: '#64748b',
+                    fontWeight: 500,
+                }, children: label ?? 'debug' }), _jsx("pre", { style: {
+                    margin: '0.5rem 0 0',
+                    whiteSpace: 'pre-wrap',
+                    wordBreak: 'break-all',
+                    color: '#1e293b',
+                }, children: JSON.stringify(value, null, 2) })] }));
+}

package/dist/components/debug-json/index.d.ts

@@ -0,0 +1,2 @@
+export { DebugJSON } from './debug-json.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/debug-json/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/debug-json/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/components/debug-json/index.js

@@ -0,0 +1 @@
+export { DebugJSON } from './debug-json.js';

package/dist/components/dev-panel/dev-panel.d.ts

@@ -0,0 +1,30 @@
+import { type ReactNode } from 'react';
+export interface DevPanelProps {
+    /**
+     * Tailwind breakpoint map. Defaults to standard Tailwind v3/v4 breakpoints.
+     * Pass your own if you've customized the theme.
+     */
+    breakpoints?: Record<string, number>;
+    /** Additional debug content rendered inside the panel. */
+    children?: ReactNode;
+    /** Corner to anchor the panel to. Defaults to `'bottom-left'`. */
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    /**
+     * Keyboard shortcut to toggle the panel.
+     * Format: modifier keys joined by `+`, then the key. Defaults to `'shift+d'`.
+     * Examples: `'shift+d'`, `'ctrl+shift+d'`, `'alt+d'`.
+     */
+    shortcut?: string;
+}
+/**
+ * Fixed overlay showing the current Tailwind breakpoint, viewport dimensions,
+ * and color scheme. Dev-only — renders nothing in production.
+ *
+ * Much better than raw px — shows the named breakpoint (`lg`) so you immediately
+ * know which Tailwind classes are active, not just "1124px".
+ *
+ * Pass children to add custom debug rows (route, user, feature flags, etc.).
+ * Toggle visibility with the keyboard shortcut (default: Shift+D).
+ */
+export declare function DevPanel(props: DevPanelProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=dev-panel.d.ts.map

package/dist/components/dev-panel/dev-panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-panel.d.ts","sourceRoot":"","sources":["../../../src/components/dev-panel/dev-panel.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAuB,KAAK,SAAS,EAAsB,MAAM,OAAO,CAAA;AAwC/E,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACpC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,UAAU,GAAG,WAAW,GAAG,aAAa,GAAG,cAAc,CAAA;IACpE;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AA0LD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,kDAG5C"}

package/dist/components/dev-panel/dev-panel.js

@@ -0,0 +1,155 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+const DEFAULT_BREAKPOINTS = {
+    sm: 640,
+    md: 768,
+    lg: 1024,
+    xl: 1280,
+    '2xl': 1536,
+};
+const POSITION_STYLES = {
+    'top-left': { top: '0.75rem', left: '0.75rem' },
+    'top-right': { top: '0.75rem', right: '0.75rem' },
+    'bottom-left': { bottom: '0.75rem', left: '0.75rem' },
+    'bottom-right': { bottom: '0.75rem', right: '0.75rem' },
+};
+function resolveBreakpoint(width, breakpoints) {
+    const sorted = Object.entries(breakpoints).sort(([, a], [, b]) => b - a);
+    for (const [name, min] of sorted) {
+        if (width >= min)
+            return name;
+    }
+    return 'xs';
+}
+function matchShortcut(e, shortcut) {
+    const parts = shortcut.toLowerCase().split('+');
+    const key = parts.at(-1) ?? '';
+    return (e.key.toLowerCase() === key &&
+        e.shiftKey === parts.includes('shift') &&
+        e.metaKey === parts.includes('meta') &&
+        e.ctrlKey === parts.includes('ctrl') &&
+        e.altKey === parts.includes('alt'));
+}
+function DevPanelInner({ breakpoints = DEFAULT_BREAKPOINTS, children, position = 'bottom-left', shortcut = 'shift+d', }) {
+    const [open, setOpen] = useState(true);
+    const [viewport, setViewport] = useState({ w: 0, h: 0 });
+    const [dark, setDark] = useState(false);
+    useEffect(() => {
+        function update() {
+            setViewport({ w: window.innerWidth, h: window.innerHeight });
+            setDark(document.documentElement.classList.contains('dark') ||
+                window.matchMedia('(prefers-color-scheme: dark)').matches);
+        }
+        update();
+        window.addEventListener('resize', update);
+        // Watch for class changes on <html> (Tailwind dark mode toggle)
+        const observer = new MutationObserver(update);
+        observer.observe(document.documentElement, {
+            attributes: true,
+            attributeFilter: ['class'],
+        });
+        return () => {
+            window.removeEventListener('resize', update);
+            observer.disconnect();
+        };
+    }, []);
+    useEffect(() => {
+        function handleKey(e) {
+            if (matchShortcut(e, shortcut))
+                setOpen((v) => !v);
+        }
+        window.addEventListener('keydown', handleKey);
+        return () => window.removeEventListener('keydown', handleKey);
+    }, [shortcut]);
+    const allBreakpoints = [
+        ['xs', 0],
+        ...Object.entries(breakpoints).sort(([, a], [, b]) => a - b),
+    ];
+    const current = resolveBreakpoint(viewport.w, breakpoints);
+    const base = {
+        position: 'fixed',
+        ...POSITION_STYLES[position],
+        zIndex: 9999,
+        fontFamily: 'ui-monospace, monospace',
+        fontSize: '0.72rem',
+        backdropFilter: 'blur(10px)',
+        WebkitBackdropFilter: 'blur(10px)',
+    };
+    if (!open) {
+        return (_jsx("button", { onClick: () => setOpen(true), title: `Dev Panel (${shortcut})`, style: {
+                ...base,
+                background: 'rgba(15,15,15,0.88)',
+                color: '#06b6d4',
+                border: '1px solid rgba(255,255,255,0.08)',
+                borderRadius: '6px',
+                padding: '0.2rem 0.5rem',
+                cursor: 'pointer',
+                lineHeight: 1.5,
+            }, children: current }));
+    }
+    return (_jsxs("div", { style: {
+            ...base,
+            background: 'rgba(12,12,12,0.93)',
+            color: '#cbd5e1',
+            border: '1px solid rgba(255,255,255,0.07)',
+            borderRadius: '10px',
+            padding: '0.6rem 0.75rem',
+            lineHeight: 1.7,
+            minWidth: '13rem',
+            boxShadow: '0 8px 32px rgba(0,0,0,0.5)',
+            userSelect: 'none',
+        }, children: [_jsx("button", { onClick: () => setOpen(false), title: 'Close', style: {
+                    position: 'absolute',
+                    top: '0.3rem',
+                    right: '0.45rem',
+                    background: 'none',
+                    border: 'none',
+                    color: '#475569',
+                    cursor: 'pointer',
+                    fontSize: '0.65rem',
+                    lineHeight: 1,
+                    padding: 0,
+                }, children: "\u2715" }), _jsx("div", { style: {
+                    display: 'flex',
+                    gap: '0.4rem',
+                    alignItems: 'baseline',
+                    marginBottom: '0.1rem',
+                }, children: allBreakpoints.map(([name]) => (_jsx("span", { style: {
+                        color: name === current ? '#06b6d4' : '#334155',
+                        fontWeight: name === current ? 700 : 400,
+                        fontSize: name === current ? '0.78rem' : '0.68rem',
+                        letterSpacing: name === current ? '0.02em' : undefined,
+                    }, children: name }, name))) }), _jsxs("div", { style: {
+                    display: 'flex',
+                    gap: '0.75rem',
+                    color: '#475569',
+                    fontSize: '0.68rem',
+                }, children: [_jsxs("span", { children: [viewport.w, " \u00D7 ", viewport.h] }), _jsx("span", { children: dark ? '☾ dark' : '☀ light' })] }), children && (_jsx("div", { style: {
+                    marginTop: '0.4rem',
+                    paddingTop: '0.4rem',
+                    borderTop: '1px solid rgba(255,255,255,0.05)',
+                    color: '#64748b',
+                    fontSize: '0.68rem',
+                    lineHeight: 1.6,
+                }, children: children })), _jsxs("div", { style: {
+                    marginTop: '0.3rem',
+                    color: '#1e293b',
+                    fontSize: '0.6rem',
+                }, children: [shortcut, " to toggle"] })] }));
+}
+/**
+ * Fixed overlay showing the current Tailwind breakpoint, viewport dimensions,
+ * and color scheme. Dev-only — renders nothing in production.
+ *
+ * Much better than raw px — shows the named breakpoint (`lg`) so you immediately
+ * know which Tailwind classes are active, not just "1124px".
+ *
+ * Pass children to add custom debug rows (route, user, feature flags, etc.).
+ * Toggle visibility with the keyboard shortcut (default: Shift+D).
+ */
+export function DevPanel(props) {
+    if (process.env.NODE_ENV === 'production')
+        return null;
+    return _jsx(DevPanelInner, { ...props });
+}

package/dist/components/dev-panel/index.d.ts

@@ -0,0 +1,2 @@
+export { DevPanel, type DevPanelProps } from './dev-panel.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/dev-panel/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/dev-panel/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/components/dev-panel/index.js

@@ -0,0 +1 @@
+export { DevPanel } from './dev-panel.js';