@luciodale/swipe-bar 1.0.0

package/README.md

@@ -0,0 +1,298 @@
+# SwipeBar
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/luciodale/swipe-bar/main/packages/docs/public/logo.svg" alt="SwipeBar Logo" width="200" height="200" />
+</div>
+
+<div align="center">
+  
+  [📖 Documentation](#) • [🎮 Live Demo](#) • [📦 NPM Package](https://www.npmjs.com/package/@luciodale/swipe-bar)
+  
+</div>
+
+## A native swipe bar experience
+
+SwipeBar provides an intuitive, native-app-like experience for mobile and desktop sidebars. Swipe from the edge to open, drag to close, and enjoy smooth animations with full customization control.
+
+## Features
+
+- 📦 **Lightweight** - zero dependencies
+- 📱 **Native Mobile Gestures** - Swipe from screen edges just like native apps
+- 🖱️ **Desktop Support** - Works seamlessly with mouse interactions
+- 🎨 **Fully Customizable** - Complete control over styling, animations, and behavior
+- 🎯 **Smart Positioning** - Automatically adapts between absolute and relative positioning
+- 🎭 **Custom Toggles** - Use built-in toggle icons or provide your own components
+- ⚡ **Performant** - Relies on transform and opacity properties
+- 🎚️ **Configurable Thresholds** - Fine-tune edge activation and drag sensitivity
+- 🌓 **Overlay Support** - Optional backdrop overlay with customizable colors
+- 📏 **Responsive** - Media query support for different screen sizes
+- 🔧 **Programmatic Control** - Open and close sidebars from anywhere in your app
+
+## Installation
+
+```bash
+npm install @luciodale/swipe-bar
+# or
+yarn add @luciodale/swipe-bar
+# or
+bun add @luciodale/swipe-bar
+```
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install @luciodale/swipe-bar
+```
+
+### 2. Add the Provider
+
+Wrap your app with `SwipeBarProvider`:
+
+```tsx
+import { SwipeBarProvider } from "@luciodale/swipe-bar";
+
+function App() {
+  return (
+    <SwipeBarProvider>
+      {/* Your app content */}
+    </SwipeBarProvider>
+  );
+}
+```
+
+### 3. Add Left Sidebar
+
+```tsx
+import { SwipeBarLeft } from "@luciodale/swipe-bar";
+
+<SwipeBarLeft className="bg-blue-500 ...">
+  <nav>Your sidebar content</nav>
+</SwipeBarLeft>
+```
+
+### 4. Add Right Sidebar
+
+```tsx
+import { SwipeBarRight } from "@luciodale/swipe-bar";
+
+<SwipeBarRight className="bg-blue-500 ...">
+  <div>Settings panel</div>
+</SwipeBarRight>
+```
+
+### 5. Programmatic Control
+
+Use the context hook to control sidebars from anywhere:
+
+```tsx
+import { useSwipeBarContext } from "@luciodale/swipe-bar";
+
+function MyComponent() {
+  const { openSidebar, closeSidebar, isLeftOpen, isRightOpen } = useSwipeBarContext();
+  
+  return (
+    <button onClick={() => openSidebar("left")}>
+      Open Left Sidebar
+    </button>
+  );
+}
+```
+
+## Props & Configuration
+
+### Provider Props
+
+Configure global defaults for all sidebars:
+
+```tsx
+<SwipeBarProvider
+  sidebarWidthPx={320}
+  transitionMs={200}
+  edgeActivationWidthPx={40}
+  dragActivationDeltaPx={20}
+  showOverlay={true}
+  closeSidebarOnOverlayClick={true}
+  isAbsolute={false}
+  overlayBackgroundColor="rgba(0, 0, 0, 0.5)"
+  toggleIconColor="white"
+  toggleIconSizePx={40}
+  toggleIconEdgeDistancePx={40}
+  showToggle={true}
+  mediaQueryWidth={640}
+>
+  {children}
+</SwipeBarProvider>
+```
+
+### Sidebar Props
+
+Both `SwipeBarLeft` and `SwipeBarRight` accept the same props, which override provider defaults:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | CSS classes for the sidebar container |
+| `ToggleComponent` | `ReactNode` | - | Custom toggle button component |
+| `sidebarWidthPx` | `number` | `320` | Width of the sidebar in pixels |
+| `transitionMs` | `number` | `200` | Animation duration in milliseconds |
+| `edgeActivationWidthPx` | `number` | `40` | Touch zone width from screen edge to activate swipe |
+| `dragActivationDeltaPx` | `number` | `20` | Minimum drag distance to activate sidebar |
+| `showOverlay` | `boolean` | `true` | Show backdrop overlay when sidebar is open |
+| `closeSidebarOnOverlayClick` | `boolean` | `true` | Close sidebar when clicking overlay |
+| `isAbsolute` | `boolean` | `false` | Use absolute positioning (overlay mode) |
+| `overlayBackgroundColor` | `string` | `"rgba(0, 0, 0, 0.5)"` | Overlay background color |
+| `toggleIconColor` | `string` | `"white"` | Color of the built-in toggle icon |
+| `toggleIconSizePx` | `number` | `40` | Size of the toggle icon |
+| `toggleIconEdgeDistancePx` | `number` | `40` | Distance of toggle from screen edge |
+| `showToggle` | `boolean` | `true` | Show the toggle button |
+| `mediaQueryWidth` | `number` | `640` | Max screen width for swipe gestures (in pixels) |
+
+### Context API
+
+```tsx
+const {
+  isLeftOpen,           // boolean - is left sidebar open
+  isRightOpen,          // boolean - is right sidebar open
+  openSidebar,          // (side: "left" | "right") => void
+  closeSidebar,         // (side: "left" | "right") => void
+  globalOptions,        // current global options
+  setGlobalOptions,     // update global options
+} = useSwipeBarContext();
+```
+
+## Key Concepts
+
+### isAbsolute Mode
+
+By default, sidebars push content to the side. Set `isAbsolute={true}` to make sidebars overlay on top of content instead:
+
+```tsx
+<SwipeBarLeft isAbsolute={true}>
+  {/* This sidebar will overlay content */}
+</SwipeBarLeft>
+```
+
+**Note:** On mobile (below `mediaQueryWidth`), sidebars automatically switch to absolute positioning for a better mobile experience.
+
+### Media Query Width
+
+Control when swipe gestures are enabled based on screen size:
+
+```tsx
+<SwipeBarProvider mediaQueryWidth={640}>
+  {/* Swipe gestures only work on screens ≤640px wide */}
+</SwipeBarProvider>
+```
+
+This is useful if you want swipe interactions only on mobile/tablet devices.
+
+### Toggle Button Behavior
+
+The built-in toggle button automatically hides when:
+- The sidebar is open AND `closeSidebarOnOverlayClick` is `true`
+- The overlay is visible to handle closing instead
+
+### Custom Toggles
+
+Replace the default toggle with your own component:
+
+```tsx
+<SwipeBarLeft 
+  ToggleComponent={
+    <button className="my-custom-toggle">
+      ☰
+    </button>
+  }
+>
+  {/* content */}
+</SwipeBarLeft>
+```
+
+## Examples
+
+### Basic Sidebar
+
+```tsx
+import { SwipeBarProvider, SwipeBarLeft } from "@luciodale/swipe-bar";
+
+function App() {
+  return (
+    <SwipeBarProvider>
+      <SwipeBarLeft className="bg-gray-800 text-white p-4">
+        <h2>Navigation</h2>
+        <nav>
+          <a href="/">Home</a>
+          <a href="/about">About</a>
+          <a href="/contact">Contact</a>
+        </nav>
+      </SwipeBarLeft>
+      
+      <main>
+        {/* Your main content */}
+      </main>
+    </SwipeBarProvider>
+  );
+}
+```
+
+### Glassmorphism Sidebar
+
+```tsx
+<SwipeBarLeft 
+  className="bg-white/10 backdrop-blur-2xl border-r border-white/20"
+  overlayBackgroundColor="rgba(0, 0, 0, 0.3)"
+>
+  {/* Glass effect sidebar content */}
+</SwipeBarLeft>
+```
+
+### Full-Width Mobile Sidebar
+
+```tsx
+<SwipeBarLeft 
+  sidebarWidthPx={window.innerWidth}
+  isAbsolute={true}
+>
+  {/* Full screen mobile menu */}
+</SwipeBarLeft>
+```
+
+### Programmatic Control
+
+```tsx
+function Header() {
+  const { openSidebar } = useSwipeBarContext();
+  
+  return (
+    <header>
+      <button onClick={() => openSidebar("left")}>Menu</button>
+      <h1>My App</h1>
+      <button onClick={() => openSidebar("right")}>Settings</button>
+    </header>
+  );
+}
+```
+
+## Browser Support
+
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Mobile Safari (iOS 12+)
+- Chrome Android (latest)
+
+Touch events and smooth animations are supported across all modern browsers.
+
+## Contributing
+
+Contributions are welcome! Feel free to:
+
+- Report bugs
+- Suggest new features
+- Submit pull requests
+- Improve documentation
+
+## License
+
+MIT

package/dist/SwipeBarProvider.d.ts

@@ -0,0 +1,29 @@
+import { ReactNode } from 'react';
+import { TSidebarSide, TSwipeBarOptions } from './swipeSidebarShared';
+
+type TLockedSidebar = TSidebarSide | null;
+type TSwipeSidebarContext = {
+    lockedSidebar: TLockedSidebar;
+    setLockedSidebar: (side: TLockedSidebar) => void;
+    leftSidebarRef: React.RefObject<HTMLDivElement | null>;
+    rightSidebarRef: React.RefObject<HTMLDivElement | null>;
+    isLeftOpen: boolean;
+    isRightOpen: boolean;
+    openSidebar: (side: TSidebarSide) => void;
+    closeSidebar: (side: TSidebarSide) => void;
+    dragSidebar: (side: TSidebarSide, translateX: number | null) => void;
+    globalOptions: Required<TSwipeBarOptions>;
+    setGlobalOptions: (options: Partial<Required<TSwipeBarOptions>>) => void;
+    leftSidebarOptions: TSwipeBarOptions;
+    rightSidebarOptions: TSwipeBarOptions;
+    setLeftSidebarOptions: (options: TSwipeBarOptions) => void;
+    setRightSidebarOptions: (options: TSwipeBarOptions) => void;
+    leftToggleRef: React.RefObject<HTMLDivElement | null>;
+    rightToggleRef: React.RefObject<HTMLDivElement | null>;
+};
+export declare const SwipeSidebarContext: import('react').Context<TSwipeSidebarContext | null>;
+export declare const SwipeBarProvider: ({ children, sidebarWidthPx, transitionMs, edgeActivationWidthPx, dragActivationDeltaPx, showOverlay, closeSidebarOnOverlayClick, isAbsolute, overlayBackgroundColor, toggleIconColor, toggleIconSizePx, toggleIconEdgeDistancePx, showToggle, mediaQueryWidth, }: {
+    children: ReactNode;
+} & TSwipeBarOptions) => import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=SwipeBarProvider.d.ts.map

package/dist/SwipeBarProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SwipeBarProvider.d.ts","sourceRoot":"","sources":["../src/SwipeBarProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EAKf,MAAM,OAAO,CAAC;AACf,OAAO,EAWL,KAAK,YAAY,EAGjB,KAAK,gBAAgB,EAKtB,MAAM,sBAAsB,CAAC;AAE9B,KAAK,cAAc,GAAG,YAAY,GAAG,IAAI,CAAC;AAE1C,KAAK,oBAAoB,GAAG;IAC1B,aAAa,EAAE,cAAc,CAAC;IAC9B,gBAAgB,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC;IACjD,cAAc,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACvD,eAAe,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACxD,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;IAC1C,YAAY,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;IAC3C,WAAW,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IACrE,aAAa,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAC1C,gBAAgB,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC,KAAK,IAAI,CAAC;IACzE,kBAAkB,EAAE,gBAAgB,CAAC;IACrC,mBAAmB,EAAE,gBAAgB,CAAC;IACtC,qBAAqB,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC3D,sBAAsB,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC5D,aAAa,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACtD,cAAc,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CACxD,CAAC;AAEF,eAAO,MAAM,mBAAmB,sDAE/B,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,kQAe9B;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,GAAG,gBAAgB,4CA6G5C,CAAC"}

package/dist/ToggleLeft.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+import { TSwipeBarOptions } from './swipeSidebarShared';
+
+type ToggleProps = {
+    showToggle?: boolean;
+    ToggleComponent?: ReactNode;
+    options: Required<TSwipeBarOptions>;
+};
+export declare function ToggleLeft({ options, showToggle, ToggleComponent, }: ToggleProps): import("react/jsx-runtime").JSX.Element | null;
+export {};
+//# sourceMappingURL=ToggleLeft.d.ts.map

package/dist/ToggleLeft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToggleLeft.d.ts","sourceRoot":"","sources":["../src/ToggleLeft.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,sBAAsB,CAAC;AAG9B,KAAK,WAAW,GAAG;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B,OAAO,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;CACrC,CAAC;AAEF,wBAAgB,UAAU,CAAC,EACzB,OAAO,EACP,UAAiB,EACjB,eAAe,GAChB,EAAE,WAAW,kDAsCb"}

package/dist/ToggleRight.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+import { TSwipeBarOptions } from './swipeSidebarShared';
+
+type ToggleProps = {
+    showToggle?: boolean;
+    ToggleComponent?: ReactNode;
+    options: Required<TSwipeBarOptions>;
+};
+export declare function ToggleRight({ options, showToggle, ToggleComponent, }: ToggleProps): import("react/jsx-runtime").JSX.Element | null;
+export {};
+//# sourceMappingURL=ToggleRight.d.ts.map

package/dist/ToggleRight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToggleRight.d.ts","sourceRoot":"","sources":["../src/ToggleRight.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,sBAAsB,CAAC;AAG9B,KAAK,WAAW,GAAG;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B,OAAO,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;CACrC,CAAC;AAEF,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,UAAiB,EACjB,eAAe,GAChB,EAAE,WAAW,kDAwCb"}

package/dist/components/Overlay.d.ts

@@ -0,0 +1,10 @@
+type TOverlay = {
+    isCollapsed: boolean;
+    setCollapsed: () => void;
+    closeSidebarOnClick?: boolean;
+    overlayBackgroundColor?: string;
+    transitionMs?: number;
+};
+export declare function Overlay({ isCollapsed, setCollapsed, closeSidebarOnClick, transitionMs, overlayBackgroundColor, }: TOverlay): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=Overlay.d.ts.map

package/dist/components/Overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Overlay.d.ts","sourceRoot":"","sources":["../../src/components/Overlay.tsx"],"names":[],"mappings":"AAEA,KAAK,QAAQ,GAAG;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,wBAAgB,OAAO,CAAC,EACtB,WAAW,EACX,YAAY,EACZ,mBAA0B,EAC1B,YAAY,EACZ,sBAAsB,GACvB,EAAE,QAAQ,2CAmBV"}

package/dist/components/SwipeBarLeft.d.ts

@@ -0,0 +1,4 @@
+import { TSwipeSidebar } from '../swipeSidebarShared';
+
+export declare function SwipeBarLeft({ className, children, ToggleComponent, ...currentOptions }: TSwipeSidebar): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=SwipeBarLeft.d.ts.map

package/dist/components/SwipeBarLeft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SwipeBarLeft.d.ts","sourceRoot":"","sources":["../../src/components/SwipeBarLeft.tsx"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,aAAa,EAInB,MAAM,uBAAuB,CAAC;AAM/B,wBAAgB,YAAY,CAAC,EAC3B,SAAS,EACT,QAAQ,EACR,eAAe,EACf,GAAG,cAAc,EAClB,EAAE,aAAa,2CA0Cf"}

package/dist/components/SwipeBarRight.d.ts

@@ -0,0 +1,4 @@
+import { TSwipeSidebar } from '../swipeSidebarShared';
+
+export declare function SwipeBarRight({ className, children, ToggleComponent, ...currentOptions }: TSwipeSidebar): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=SwipeBarRight.d.ts.map

package/dist/components/SwipeBarRight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SwipeBarRight.d.ts","sourceRoot":"","sources":["../../src/components/SwipeBarRight.tsx"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,aAAa,EAInB,MAAM,uBAAuB,CAAC;AAM/B,wBAAgB,aAAa,CAAC,EAC5B,SAAS,EACT,QAAQ,EACR,eAAe,EACf,GAAG,cAAc,EAClB,EAAE,aAAa,2CA0Cf"}

package/dist/components/ToggleIcon.d.ts

@@ -0,0 +1,5 @@
+export declare function ToggleIcon({ size, color }: {
+    size: number;
+    color: string;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ToggleIcon.d.ts.map

package/dist/components/ToggleIcon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToggleIcon.d.ts","sourceRoot":"","sources":["../../src/components/ToggleIcon.tsx"],"names":[],"mappings":"AAGA,wBAAgB,UAAU,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,2CAqD1E"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { Overlay } from './components/Overlay';
+export { SwipeBarLeft } from './components/SwipeBarLeft';
+export { SwipeBarRight } from './components/SwipeBarRight';
+export { SwipeBarProvider } from './SwipeBarProvider';
+export { ToggleLeft } from './ToggleLeft';
+export { ToggleRight } from './ToggleRight';
+export { useMediaQuery } from './useMediaQuery';
+export { useSwipeBarContext } from './useSwipeBarContext';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}