@papernote/ui 1.3.1 → 1.5.0

package/dist/context/MobileContext.d.ts

@@ -0,0 +1,168 @@
+import React, { ReactNode } from 'react';
+import { Breakpoint, Orientation, ViewportSize } from '../hooks/useResponsive';
+/**
+ * Mobile context value interface
+ *
+ * Provides comprehensive responsive state for the entire application.
+ */
+export interface MobileContextValue {
+    /** True when viewport width < 768px */
+    isMobile: boolean;
+    /** True when viewport width is 768px - 1023px */
+    isTablet: boolean;
+    /** True when viewport width >= 1024px */
+    isDesktop: boolean;
+    /** True when device supports touch input */
+    isTouchDevice: boolean;
+    /** Current Tailwind breakpoint: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' */
+    breakpoint: Breakpoint;
+    /** Current orientation: 'portrait' | 'landscape' */
+    orientation: Orientation;
+    /** Current viewport dimensions */
+    viewport: ViewportSize;
+    /** Safe area insets for notched devices */
+    safeAreaInsets: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    /** True when mobile OR touch device (useful for UI decisions) */
+    useMobileUI: boolean;
+}
+/**
+ * Mobile context
+ */
+declare const MobileContext: React.Context<MobileContextValue>;
+/**
+ * MobileProvider props
+ */
+export interface MobileProviderProps {
+    /** Child components that will have access to mobile context */
+    children: ReactNode;
+    /**
+     * Force mobile UI mode regardless of device detection.
+     * Useful for testing or forcing mobile layout on tablets.
+     */
+    forceMobileUI?: boolean;
+    /**
+     * Force desktop UI mode regardless of device detection.
+     * Useful for testing or forcing desktop layout on mobile.
+     */
+    forceDesktopUI?: boolean;
+}
+/**
+ * MobileProvider - Provides responsive state to the entire application
+ *
+ * Wrap your application with MobileProvider to enable auto-responsive
+ * behavior in notebook-ui components.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { MobileProvider } from 'notebook-ui';
+ *
+ * function App() {
+ *   return (
+ *     <MobileProvider>
+ *       <YourApplication />
+ *     </MobileProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Force mobile UI for testing
+ * ```tsx
+ * <MobileProvider forceMobileUI>
+ *   <YourApplication />
+ * </MobileProvider>
+ * ```
+ */
+export declare function MobileProvider({ children, forceMobileUI, forceDesktopUI, }: MobileProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * useMobileContext - Hook to access mobile responsive state
+ *
+ * Must be used within a MobileProvider. Returns comprehensive
+ * responsive state for making UI decisions.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { isMobile, useMobileUI, breakpoint } = useMobileContext();
+ *
+ *   return useMobileUI ? <MobileView /> : <DesktopView />;
+ * }
+ * ```
+ */
+export declare function useMobileContext(): MobileContextValue;
+/**
+ * withMobileContext - HOC to inject mobile context as props
+ *
+ * For class components or when you prefer props over hooks.
+ *
+ * @example
+ * ```tsx
+ * interface Props {
+ *   mobile: MobileContextValue;
+ * }
+ *
+ * class MyComponent extends React.Component<Props> {
+ *   render() {
+ *     const { isMobile } = this.props.mobile;
+ *     return isMobile ? <Mobile /> : <Desktop />;
+ *   }
+ * }
+ *
+ * export default withMobileContext(MyComponent);
+ * ```
+ */
+export declare function withMobileContext<P extends {
+    mobile: MobileContextValue;
+}>(Component: React.ComponentType<P>): {
+    (props: Omit<P, "mobile">): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/**
+ * MobileOnly - Renders children only on mobile devices
+ *
+ * @example
+ * ```tsx
+ * <MobileOnly>
+ *   <BottomNavigation items={navItems} />
+ * </MobileOnly>
+ * ```
+ */
+export declare function MobileOnly({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * DesktopOnly - Renders children only on desktop devices
+ *
+ * @example
+ * ```tsx
+ * <DesktopOnly>
+ *   <Sidebar items={navItems} />
+ * </DesktopOnly>
+ * ```
+ */
+export declare function DesktopOnly({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * Responsive - Renders different content based on device type
+ *
+ * @example
+ * ```tsx
+ * <Responsive
+ *   mobile={<MobileNavigation />}
+ *   tablet={<TabletNavigation />}
+ *   desktop={<DesktopNavigation />}
+ * />
+ * ```
+ */
+export declare function Responsive({ mobile, tablet, desktop, }: {
+    mobile?: ReactNode;
+    tablet?: ReactNode;
+    desktop?: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export default MobileContext;
+//# sourceMappingURL=MobileContext.d.ts.map

package/dist/context/MobileContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MobileContext.d.ts","sourceRoot":"","sources":["../../src/context/MobileContext.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAsC,SAAS,EAAE,MAAM,OAAO,CAAC;AAC7E,OAAO,EASL,UAAU,EACV,WAAW,EACX,YAAY,EACb,MAAM,wBAAwB,CAAC;AAEhC;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAC;IAClB,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAC;IACnB,4CAA4C;IAC5C,aAAa,EAAE,OAAO,CAAC;IACvB,4EAA4E;IAC5E,UAAU,EAAE,UAAU,CAAC;IACvB,oDAAoD;IACpD,WAAW,EAAE,WAAW,CAAC;IACzB,kCAAkC;IAClC,QAAQ,EAAE,YAAY,CAAC;IACvB,2CAA2C;IAC3C,cAAc,EAAE;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,iEAAiE;IACjE,WAAW,EAAE,OAAO,CAAC;CACtB;AAiBD;;GAEG;AACH,QAAA,MAAM,aAAa,mCAAyD,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAAC,EAC7B,QAAQ,EACR,aAAqB,EACrB,cAAsB,GACvB,EAAE,mBAAmB,2CAkDrB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,kBAAkB,CAarD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS;IAAE,MAAM,EAAE,kBAAkB,CAAA;CAAE,EACxE,SAAS,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;YAIA,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC;;EAQnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,kDAG/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,kDAGhE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,EACzB,MAAM,EACN,MAAM,EACN,OAAO,GACR,EAAE;IACD,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB,2CAWA;AAED,eAAe,aAAa,CAAC"}

package/dist/hooks/useResponsive.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Tailwind breakpoint values in pixels
+ */
+export declare const BREAKPOINTS: {
+    readonly xs: 0;
+    readonly sm: 640;
+    readonly md: 768;
+    readonly lg: 1024;
+    readonly xl: 1280;
+    readonly '2xl': 1536;
+};
+export type Breakpoint = keyof typeof BREAKPOINTS;
+/**
+ * Viewport size state
+ */
+export interface ViewportSize {
+    width: number;
+    height: number;
+}
+/**
+ * Orientation type
+ */
+export type Orientation = 'portrait' | 'landscape';
+/**
+ * useViewportSize - Returns current viewport dimensions
+ *
+ * Updates on window resize with debouncing for performance.
+ * SSR-safe with sensible defaults.
+ *
+ * @example
+ * const { width, height } = useViewportSize();
+ * console.log(`Viewport: ${width}x${height}`);
+ */
+export declare function useViewportSize(): ViewportSize;
+/**
+ * useBreakpoint - Returns the current Tailwind breakpoint
+ *
+ * Automatically updates when viewport crosses breakpoint thresholds.
+ *
+ * @example
+ * const breakpoint = useBreakpoint();
+ * // Returns: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+ */
+export declare function useBreakpoint(): Breakpoint;
+/**
+ * useMediaQuery - React hook for CSS media queries
+ *
+ * SSR-safe implementation that returns false during SSR and
+ * updates reactively when media query match state changes.
+ *
+ * @param query - CSS media query string (e.g., '(max-width: 768px)')
+ * @returns boolean indicating if the media query matches
+ *
+ * @example
+ * const isDarkMode = useMediaQuery('(prefers-color-scheme: dark)');
+ * const isReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
+ * const isPortrait = useMediaQuery('(orientation: portrait)');
+ */
+export declare function useMediaQuery(query: string): boolean;
+/**
+ * useIsMobile - Returns true when viewport is mobile-sized (< 768px)
+ *
+ * @example
+ * const isMobile = useIsMobile();
+ * return isMobile ? <MobileNav /> : <DesktopNav />;
+ */
+export declare function useIsMobile(): boolean;
+/**
+ * useIsTablet - Returns true when viewport is tablet-sized (768px - 1023px)
+ *
+ * @example
+ * const isTablet = useIsTablet();
+ */
+export declare function useIsTablet(): boolean;
+/**
+ * useIsDesktop - Returns true when viewport is desktop-sized (>= 1024px)
+ *
+ * @example
+ * const isDesktop = useIsDesktop();
+ */
+export declare function useIsDesktop(): boolean;
+/**
+ * useIsTouchDevice - Detects if the device supports touch input
+ *
+ * Uses multiple detection methods for reliability:
+ * - Touch event support
+ * - Pointer coarse media query
+ * - Max touch points
+ *
+ * @example
+ * const isTouchDevice = useIsTouchDevice();
+ * // Show swipe hints on touch devices
+ */
+export declare function useIsTouchDevice(): boolean;
+/**
+ * useOrientation - Returns current screen orientation
+ *
+ * @returns 'portrait' | 'landscape'
+ *
+ * @example
+ * const orientation = useOrientation();
+ * // Adjust layout based on orientation
+ */
+export declare function useOrientation(): Orientation;
+/**
+ * useBreakpointValue - Returns different values based on breakpoint
+ *
+ * Mobile-first: Returns the value for the current breakpoint or the
+ * closest smaller breakpoint that has a value defined.
+ *
+ * @param values - Object mapping breakpoints to values
+ * @param defaultValue - Fallback value if no breakpoint matches
+ *
+ * @example
+ * const columns = useBreakpointValue({ xs: 1, sm: 2, lg: 4 }, 1);
+ * // Returns 1 on xs, 2 on sm/md, 4 on lg/xl/2xl
+ *
+ * const padding = useBreakpointValue({ xs: 'p-2', md: 'p-4', xl: 'p-8' });
+ */
+export declare function useBreakpointValue<T>(values: Partial<Record<Breakpoint, T>>, defaultValue?: T): T | undefined;
+/**
+ * useResponsiveCallback - Returns a memoized callback that receives responsive info
+ *
+ * Useful for callbacks that need to behave differently based on viewport.
+ *
+ * @example
+ * const handleClick = useResponsiveCallback((isMobile) => {
+ *   if (isMobile) {
+ *     openBottomSheet();
+ *   } else {
+ *     openModal();
+ *   }
+ * });
+ */
+export declare function useResponsiveCallback<T extends (...args: any[]) => any>(callback: (isMobile: boolean, isTablet: boolean, isDesktop: boolean) => T): T;
+/**
+ * useSafeAreaInsets - Returns safe area insets for notched devices
+ *
+ * Uses CSS environment variables (env(safe-area-inset-*)) to get
+ * safe area dimensions for devices with notches or home indicators.
+ *
+ * @example
+ * const { top, bottom } = useSafeAreaInsets();
+ * // Add padding-bottom for home indicator
+ */
+export declare function useSafeAreaInsets(): {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+/**
+ * usePrefersMobile - Checks if user prefers reduced data/animations (mobile-friendly)
+ *
+ * Combines multiple preferences that might indicate mobile/low-power usage.
+ */
+export declare function usePrefersMobile(): boolean;
+//# sourceMappingURL=useResponsive.d.ts.map

package/dist/hooks/useResponsive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useResponsive.d.ts","sourceRoot":"","sources":["../../src/hooks/useResponsive.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;CAOd,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,WAAW,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,WAAW,CAAC;AAoBnD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,IAAI,YAAY,CA8B9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAS1C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAwBpD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAuB1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAG5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EACtC,YAAY,CAAC,EAAE,CAAC,GACf,CAAC,GAAG,SAAS,CAkBf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACrE,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,KAAK,CAAC,GACxE,CAAC,CASH;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd,CAkCA;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAO1C"}