react-panel-layout 0.5.2 → 0.6.0

package/src/demo/pages/StickyHeader/components/StickyHeaderBasics.tsx

@@ -0,0 +1,103 @@
+/**
+ * @file Basic StickyArea demo - native app-like overscroll experience
+ */
+import * as React from "react";
+import { StickyArea } from "../../../../sticky-header/index";
+import type { StickyAreaPosition, StickyAreaState } from "../../../../sticky-header/index";
+import styles from "./StickyHeader.module.css";
+
+const HeaderCover: React.FC = () => (
+  <div className={`${styles.coverPlaceholder} ${styles.coverGradient1}`}>Header Cover</div>
+);
+
+const FooterCover: React.FC = () => (
+  <div className={`${styles.coverPlaceholder} ${styles.coverGradient2}`}>Footer Cover</div>
+);
+
+export const StickyHeaderBasics: React.FC = () => {
+  const [headerState, setHeaderState] = React.useState<StickyAreaState>({
+    isStuck: false,
+    scrollOffset: 0,
+  });
+
+  const [footerState, setFooterState] = React.useState<StickyAreaState>({
+    isStuck: false,
+    scrollOffset: 0,
+  });
+
+  const [position, setPosition] = React.useState<StickyAreaPosition>("top");
+
+  const state = position === "top" ? headerState : footerState;
+
+  return (
+    <div className={styles.container}>
+      <div className={styles.stateIndicator}>
+        <div className={styles.stateRow}>
+          <span className={styles.stateLabel}>position:</span>
+          <select
+            value={position}
+            onChange={(e) => setPosition(e.target.value as StickyAreaPosition)}
+            className={styles.stateValue}
+          >
+            <option value="top">top (header)</option>
+            <option value="bottom">bottom (footer)</option>
+          </select>
+        </div>
+        <div className={styles.stateRow}>
+          <span className={styles.stateLabel}>isStuck:</span>
+          <span className={`${styles.stateValue} ${state.isStuck ? styles.stuck : ""}`}>
+            {state.isStuck ? "true" : "false"}
+          </span>
+        </div>
+        <div className={styles.stateRow}>
+          <span className={styles.stateLabel}>scrollOffset:</span>
+          <span className={styles.stateValue}>{state.scrollOffset.toFixed(0)}px</span>
+        </div>
+      </div>
+
+      <div className={styles.scrollArea}>
+        <StickyArea position="top" cover={<HeaderCover />} onStateChange={setHeaderState}>
+          <div className={styles.header}>
+            <h1>StickyArea Demo</h1>
+            <p>Pull down to see the overscroll effect (works best in PWA/WebApp mode)</p>
+          </div>
+        </StickyArea>
+
+        <div className={styles.content}>
+          <h2>About StickyArea</h2>
+          <p>
+            StickyArea provides a native app-like experience for SPAs and PWAs. It supports both header (top) and
+            footer (bottom) positions. When the user overscrolls, the cover content expands to fill the visible area.
+          </p>
+
+          <h2>Features</h2>
+          <ul>
+            <li>
+              <strong>Header &amp; Footer</strong> - Use position="top" or position="bottom"
+            </li>
+            <li>
+              <strong>Overscroll Effect</strong> - Cover expands during bounce
+            </li>
+            <li>
+              <strong>State Tracking</strong> - Know when area is "stuck" at edge
+            </li>
+          </ul>
+
+          <h2>Usage</h2>
+          <p>Use position prop to control header or footer behavior:</p>
+
+          <h2>Scroll to Bottom</h2>
+          <p>Keep scrolling to see the footer with its own cover that expands on pull-up overscroll...</p>
+          <p>The footer area works the same as the header, but anchored to the bottom.</p>
+          <p>Try changing the position selector above to see the state for header or footer.</p>
+        </div>
+
+        <StickyArea position="bottom" cover={<FooterCover />} onStateChange={setFooterState}>
+          <div className={styles.footer}>
+            <p>Footer Area - Pull up to see the overscroll effect</p>
+          </div>
+        </StickyArea>
+      </div>
+    </div>
+  );
+};

package/src/demo/routes.tsx

@@ -0,0 +1,193 @@
+/**
+ * @file Demo route configuration for Sidebar and Router
+ */
+import * as React from "react";
+
+// Page components (static imports to satisfy lint rules)
+import FP_Basic from "./pages/FloatingPanelFrame/basic";
+import FP_WithMeta from "./pages/FloatingPanelFrame/with-meta";
+import FP_WithControls from "./pages/FloatingPanelFrame/with-controls";
+import FP_Complex from "./pages/FloatingPanelFrame/complex";
+import FP_Scrollable from "./pages/FloatingPanelFrame/scrollable";
+
+import HD_Simple from "./pages/HorizontalDivider/simple-resizable-panels";
+import HD_Rich from "./pages/HorizontalDivider/panels-with-rich-content";
+import HD_Three from "./pages/HorizontalDivider/three-panel-layout";
+
+import RH_Vertical from "./pages/ResizeHandle/vertical";
+import RH_Horizontal from "./pages/ResizeHandle/horizontal";
+import RH_Both from "./pages/ResizeHandle/both-directions";
+import RH_Nested from "./pages/ResizeHandle/nested-panels";
+
+import PL_SimpleGrid from "./pages/PanelLayout/simple-grid";
+import PL_IDE from "./pages/PanelLayout/ide-layout";
+import PL_Dashboard from "./pages/PanelLayout/dashboard";
+import PL_Overlays from "./pages/PanelLayout/draggable-overlays";
+
+import DR_Basics from "./pages/Drawer/basics";
+import DR_Menu from "./pages/Drawer/menu";
+import DR_Animations from "./pages/Drawer/animations";
+
+import PS_Preview from "./pages/PanelSystem/preview";
+import PS_Tabbar from "./pages/PanelSystem/tabbar";
+import { ResizableFloatingPanelsPreview } from "./pages/FloatingPanelFrame/ResizableFloatingPanelsPreview";
+import RL_AdaptiveWorkspace from "./pages/ResponsiveLayout/adaptive-workspace";
+
+import PV_Basics from "./pages/Pivot/basics";
+import PV_Tabs from "./pages/Pivot/tabs";
+import PV_Sidebar from "./pages/Pivot/sidebar";
+import PV_Transitions from "./pages/Pivot/transitions";
+import PV_Swipe from "./pages/Pivot/swipe";
+import PV_SwipeDebug from "./pages/Pivot/swipe-debug";
+import PV_SwipeTabs from "./pages/Pivot/swipe-tabs";
+
+import ST_Basics from "./pages/Stack/basics";
+import ST_Tablet from "./pages/Stack/tablet";
+
+import SH_Basics from "./pages/StickyHeader/basics";
+
+import { FiGrid, FiLayers, FiColumns, FiMaximize2, FiBox, FiCpu, FiSmartphone, FiSidebar, FiNavigation, FiImage } from "react-icons/fi";
+
+export type DemoPage = {
+  id: string;
+  label: string;
+  path: string; // path relative to the category base
+  element: React.ReactNode;
+};
+
+export type DemoCategory = {
+  id: string;
+  label: string;
+  icon: React.ReactNode;
+  base: string; // base route path
+  pages: DemoPage[];
+};
+
+export const demoCategories: DemoCategory[] = [
+  {
+    id: "panel-layout",
+    label: "PanelLayout",
+    icon: <FiGrid />,
+    base: "/components/panel-layout",
+    pages: [
+      { id: "simple-grid", label: "Simple Grid", path: "simple-grid", element: <PL_SimpleGrid /> },
+      { id: "ide-layout", label: "IDE Layout", path: "ide-layout", element: <PL_IDE /> },
+      { id: "dashboard", label: "Dashboard", path: "dashboard", element: <PL_Dashboard /> },
+      { id: "draggable-overlays", label: "Draggable Overlays", path: "draggable-overlays", element: <PL_Overlays /> },
+    ],
+  },
+  {
+    id: "drawer",
+    label: "Drawer",
+    icon: <FiSidebar />,
+    base: "/components/drawer",
+    pages: [
+      { id: "basics", label: "Basics", path: "basics", element: <DR_Basics /> },
+      { id: "menu", label: "Menu", path: "menu", element: <DR_Menu /> },
+      { id: "animations", label: "Animations", path: "animations", element: <DR_Animations /> },
+    ],
+  },
+  {
+    id: "responsive-layout",
+    label: "Responsive Layout",
+    icon: <FiSmartphone />,
+    base: "/components/responsive-layout",
+    pages: [
+      {
+        id: "adaptive-workspace",
+        label: "Adaptive Workspace",
+        path: "adaptive-workspace",
+        element: <RL_AdaptiveWorkspace />,
+      },
+    ],
+  },
+  {
+    id: "floating-panel-frame",
+    label: "FloatingPanelFrame",
+    icon: <FiLayers />,
+    base: "/components/floating-panel-frame",
+    pages: [
+      { id: "basic", label: "Basic", path: "basic", element: <FP_Basic /> },
+      { id: "with-meta", label: "With Meta", path: "with-meta", element: <FP_WithMeta /> },
+      { id: "with-controls", label: "With Controls", path: "with-controls", element: <FP_WithControls /> },
+      { id: "complex", label: "Complex", path: "complex", element: <FP_Complex /> },
+      { id: "scrollable", label: "Scrollable", path: "scrollable", element: <FP_Scrollable /> },
+    ],
+  },
+  {
+    id: "horizontal-divider",
+    label: "HorizontalDivider",
+    icon: <FiColumns />,
+    base: "/components/horizontal-divider",
+    pages: [
+      { id: "simple", label: "Simple", path: "simple-resizable-panels", element: <HD_Simple /> },
+      { id: "rich-content", label: "Rich Content", path: "panels-with-rich-content", element: <HD_Rich /> },
+      { id: "three-panel", label: "Three Panel", path: "three-panel-layout", element: <HD_Three /> },
+    ],
+  },
+  {
+    id: "resize-handle",
+    label: "ResizeHandle",
+    icon: <FiMaximize2 />,
+    base: "/components/resize-handle",
+    pages: [
+      { id: "vertical", label: "Vertical", path: "vertical", element: <RH_Vertical /> },
+      { id: "horizontal", label: "Horizontal", path: "horizontal", element: <RH_Horizontal /> },
+      { id: "both", label: "Both Directions", path: "both-directions", element: <RH_Both /> },
+      { id: "nested", label: "Nested Panels", path: "nested-panels", element: <RH_Nested /> },
+    ],
+  },
+  {
+    id: "resizable-floating-panels",
+    label: "Resizable Floating Panels",
+    icon: <FiBox />,
+    base: "/components/resizable-floating-panels",
+    pages: [
+      { id: "edge-resize", label: "Edge Resize", path: "edge-resize", element: <ResizableFloatingPanelsPreview /> },
+    ],
+  },
+  {
+    id: "panel-system",
+    label: "PanelSystem",
+    icon: <FiCpu />,
+    base: "/components/panel-system",
+    pages: [
+      { id: "preview", label: "Preview", path: "preview", element: <PS_Preview /> },
+      { id: "tabbar", label: "TabBar", path: "tabbar", element: <PS_Tabbar /> },
+    ],
+  },
+  {
+    id: "pivot",
+    label: "Pivot",
+    icon: <FiNavigation />,
+    base: "/components/pivot",
+    pages: [
+      { id: "basics", label: "Basics", path: "basics", element: <PV_Basics /> },
+      { id: "tabs", label: "Tab Navigation", path: "tabs", element: <PV_Tabs /> },
+      { id: "sidebar", label: "Sidebar Navigation", path: "sidebar", element: <PV_Sidebar /> },
+      { id: "transitions", label: "Transitions", path: "transitions", element: <PV_Transitions /> },
+      { id: "swipe", label: "Swipe Navigation", path: "swipe", element: <PV_Swipe /> },
+      { id: "swipe-tabs", label: "Swipe Tabs", path: "swipe-tabs", element: <PV_SwipeTabs /> },
+      { id: "swipe-debug", label: "Swipe Debug (iOS)", path: "swipe-debug", element: <PV_SwipeDebug /> },
+    ],
+  },
+  {
+    id: "stack",
+    label: "Stack",
+    icon: <FiLayers />,
+    base: "/components/stack",
+    pages: [
+      { id: "basics", label: "Basics", path: "basics", element: <ST_Basics /> },
+      { id: "tablet", label: "Tablet Layout", path: "tablet", element: <ST_Tablet /> },
+    ],
+  },
+  {
+    id: "sticky-header",
+    label: "StickyHeader",
+    icon: <FiImage />,
+    base: "/components/sticky-header",
+    pages: [
+      { id: "basics", label: "Basics", path: "basics", element: <SH_Basics /> },
+    ],
+  },
+];

package/src/demo/styles/animations.css

@@ -0,0 +1,68 @@
+/**
+ * Demo animation definitions (global CSS, not scoped by CSS modules)
+ *
+ * Users should define their own keyframes and CSS variables in their global CSS.
+ * This file demonstrates the pattern.
+ */
+
+/* ===============================
+ * Pivot Animations
+ * =============================== */
+
+@keyframes pivotEnter {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes pivotLeave {
+  from {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateY(-8px);
+  }
+}
+
+/* ===============================
+ * Stack Animations
+ * =============================== */
+
+@keyframes stackPush {
+  from {
+    transform: translateX(100%);
+  }
+  to {
+    transform: translateX(0);
+  }
+}
+
+@keyframes stackPop {
+  from {
+    transform: translateX(0);
+  }
+  to {
+    transform: translateX(100%);
+  }
+}
+
+/* ===============================
+ * CSS Variable Registration
+ * =============================== */
+
+:root {
+  /* Pivot animations */
+  --rpl-pivot-animation-enter: pivotEnter 200ms ease-out forwards;
+  --rpl-pivot-animation-leave: pivotLeave 150ms ease-in forwards;
+
+  /* Stack animations */
+  --rpl-stack-animation-push: stackPush 350ms cubic-bezier(0.32, 0.72, 0, 1) forwards;
+  --rpl-stack-animation-pop: stackPop 350ms cubic-bezier(0.32, 0.72, 0, 1) forwards;
+}

package/src/demo/styles/stack-themes.css

@@ -0,0 +1,35 @@
+/**
+ * Stack navigation theme presets
+ * Apply to a container element to customize stack animations
+ *
+ * CSS custom properties:
+ * - --stack-duration: Animation duration
+ * - --stack-easing: Animation timing function
+ */
+
+/* iOS Theme (Default) - Accurate iOS 17 navigation timing */
+.stack-theme-ios {
+  /* iOS uses ~350ms with a custom spring-like curve */
+  --stack-duration: 350ms;
+  --stack-easing: cubic-bezier(0.32, 0.72, 0, 1);
+}
+
+/* Android Material 3 Theme */
+.stack-theme-android {
+  /* Material 3 uses emphasized easing for spatial transitions */
+  --stack-duration: 400ms;
+  --stack-easing: cubic-bezier(0.05, 0.7, 0.1, 1);
+}
+
+/* Windows/Fluent Theme */
+.stack-theme-fluent {
+  /* Fluent uses faster, snappier animations */
+  --stack-duration: 250ms;
+  --stack-easing: cubic-bezier(0.1, 0.9, 0.2, 1);
+}
+
+/* Instant (No animation) */
+.stack-theme-instant {
+  --stack-duration: 0ms;
+  --stack-easing: linear;
+}

package/src/demo/utils/createPanelView.tsx

@@ -0,0 +1,58 @@
+/**
+ * @file Demo-only connected PanelView factory that wires contexts to a presentational group view.
+ */
+import * as React from "react";
+import type { GroupId, PanelGroupRenderProps, TabBarRenderProps } from "../../modules/panels/state/types";
+import { usePanelRenderContext } from "../../modules/panels/rendering/RenderContext";
+import { useDomRegistry } from "../../modules/panels/dom/DomRegistry";
+import { PanelGroupView } from "../../components/panels/PanelGroupView";
+import { TabBar as DefaultTabBar } from "../../components/tabs/TabBar";
+
+export type PanelViewComponent = React.FC<{ groupId: GroupId }>;
+
+export const createPanelView = (
+  TabBarImpl?: React.ComponentType<TabBarRenderProps>,
+  PanelGroupImpl?: React.ComponentType<PanelGroupRenderProps>,
+): PanelViewComponent => {
+  const TabBarComp = TabBarImpl ?? DefaultTabBar;
+  const PanelGroupComp: React.ComponentType<PanelGroupRenderProps> = PanelGroupImpl ?? ((p) => <PanelGroupView {...p} />);
+  const View: PanelViewComponent = ({ groupId }) => {
+    const { getGroup, getGroupContent, onClickTab, onAddTab, onCloseTab, onStartTabDrag, doubleClickToAdd, registerContentContainer } = usePanelRenderContext();
+    const { setGroupEl, setTabbarEl, setContentEl } = useDomRegistry();
+
+    const group = getGroup(groupId);
+    if (!group) {
+      return null;
+    }
+    const content = getGroupContent(groupId);
+    const groupRef = React.useCallback((el: HTMLDivElement | null) => setGroupEl(groupId, el), [groupId, setGroupEl]);
+    const contentRef = React.useCallback((el: HTMLDivElement | null) => {
+      setContentEl(groupId, el);
+      registerContentContainer(groupId, el);
+    }, [groupId, setContentEl, registerContentContainer]);
+    const tabbarRef = React.useCallback((el: HTMLDivElement | null) => setTabbarEl(groupId, el), [groupId, setTabbarEl]);
+
+    return (
+      <PanelGroupComp
+        group={group}
+        tabbar={
+          <TabBarComp
+            rootRef={tabbarRef}
+            group={group}
+            onClickTab={(tabId) => onClickTab(groupId, tabId)}
+            onAddTab={onAddTab}
+            onCloseTab={onCloseTab}
+            onStartDrag={(tabId, gid, e) => onStartTabDrag(tabId, gid, e)}
+            doubleClickToAdd={doubleClickToAdd}
+          />
+        }
+        content={content}
+        groupRef={groupRef}
+        contentRef={contentRef}
+      />
+    );
+  };
+  View.displayName = "DemoConnectedPanelView";
+  return View;
+};
+

package/src/floating/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @file Entry point for floating panel frame components.
+ *
+ * Consumers should import from 'react-panel-layout/floating' to keep these
+ * decorative helpers separate from the core layout system.
+ */
+
+export {
+  FloatingPanelFrame,
+  FloatingPanelHeader,
+  FloatingPanelTitle,
+  FloatingPanelMeta,
+  FloatingPanelControls,
+  FloatingPanelContent,
+} from "../components/paneling/FloatingPanelFrame";
+
+export type {
+  FloatingPanelFrameProps,
+  FloatingPanelHeaderProps,
+  FloatingPanelTitleProps,
+  FloatingPanelMetaProps,
+  FloatingPanelControlsProps,
+  FloatingPanelContentProps,
+} from "../components/paneling/FloatingPanelFrame";

package/src/grid/index.ts

@@ -0,0 +1,75 @@
+/**
+ * @file Grid entry point - Grid layout components and hooks
+ * @packageDocumentation
+ *
+ * This is a subpath export entry point for `react-panel-layout/grid`.
+ *
+ * ## Overview
+ * Grid provides CSS Grid-based layout components for arranging panels in rows
+ * and columns. Supports resizable tracks, draggable layers, and floating windows.
+ *
+ * ## Installation
+ * ```ts
+ * import { GridLayout } from "react-panel-layout/grid";
+ * ```
+ *
+ * ## Basic Usage
+ * ```tsx
+ * const config = {
+ *   areas: [
+ *     ['sidebar', 'main', 'main'],
+ *     ['sidebar', 'main', 'main'],
+ *   ],
+ *   columns: [{ size: '200px' }, { size: '1fr' }, { size: '1fr' }],
+ *   rows: [{ size: '1fr' }, { size: '1fr' }],
+ *   gap: '8px',
+ * };
+ *
+ * const layers = [
+ *   { id: 'sidebar', component: <Sidebar /> },
+ *   { id: 'main', component: <MainContent /> },
+ * ];
+ *
+ * function App() {
+ *   return <GridLayout config={config} layers={layers} />;
+ * }
+ * ```
+ *
+ * ## Resizable Tracks
+ * ```tsx
+ * const config = {
+ *   columns: [
+ *     { size: '200px', resizable: true, minSize: 100, maxSize: 400 },
+ *     { size: '1fr' },
+ *   ],
+ *   // ...
+ * };
+ * ```
+ */
+
+// Components
+export { GridLayout } from "../components/grid/GridLayout.js";
+export { GridLayerList } from "../components/grid/GridLayerList.js";
+export { GridLayerResizeHandles } from "../components/grid/GridLayerResizeHandles.js";
+export { GridTrackResizeHandle } from "../components/grid/GridTrackResizeHandle.js";
+
+// Context
+export {
+  GridLayoutProvider,
+  useGridLayoutContext,
+} from "../modules/grid/GridLayoutContext.js";
+
+// Hooks
+export { useGridPlacements } from "../modules/grid/useGridPlacements.js";
+export { useGridTracks } from "../modules/grid/useGridTracks.js";
+
+// Types
+export type {
+  GridLayerHandleProps,
+  ResizeHandleConfig,
+  GridLayerRenderState,
+  GridLayoutContextValue,
+} from "../modules/grid/GridLayoutContext.js";
+
+export type { GridLayoutProps } from "../components/grid/GridLayout.js";
+export type { TrackHandleConfig, TrackDirection } from "../modules/grid/useGridTracks.js";

package/src/hooks/ContentCacheContext.tsx

@@ -0,0 +1,87 @@
+/**
+ * @file Context + Provider pattern for shared content caching.
+ *
+ * Use this when you need to share content caching across a component tree,
+ * such as when multiple child components need access to cached content.
+ *
+ * For local caching within a single component, use useContentCache directly.
+ */
+import * as React from "react";
+import { useContentCache, type ContentResolver, type UseContentCacheResult } from "./useContentCache";
+
+/**
+ * Context value type for content cache.
+ */
+export type ContentCacheContextValue<TId extends string = string> = UseContentCacheResult<TId>;
+
+/**
+ * Creates a content cache context and associated hooks/providers.
+ *
+ * @example
+ * ```tsx
+ * // Create context for a specific use case
+ * const { Provider, useCache } = createContentCacheContext<LayerId>('LayerContent');
+ *
+ * // In provider component
+ * <Provider resolveContent={getLayerContent} validIds={layerIds}>
+ *   {children}
+ * </Provider>
+ *
+ * // In consumer component
+ * const { getCachedContent } = useCache();
+ * return <div>{getCachedContent(layerId)}</div>;
+ * ```
+ */
+export function createContentCacheContext<TId extends string = string>(displayName: string): {
+  /**
+   * Provider component that manages content caching for its children.
+   */
+  Provider: React.FC<ContentCacheProviderProps<TId>>;
+  /**
+   * Hook to access the content cache from a child component.
+   */
+  useCache: () => ContentCacheContextValue<TId>;
+  /**
+   * The raw React context (for advanced use cases).
+   */
+  Context: React.Context<ContentCacheContextValue<TId> | null>;
+} {
+  const Context = React.createContext<ContentCacheContextValue<TId> | null>(null);
+  Context.displayName = `${displayName}CacheContext`;
+
+  const useCache = (): ContentCacheContextValue<TId> => {
+    const ctx = React.useContext(Context);
+    if (!ctx) {
+      throw new Error(`use${displayName}Cache must be used within ${displayName}CacheProvider`);
+    }
+    return ctx;
+  };
+
+  const Provider: React.FC<ContentCacheProviderProps<TId>> = ({ resolveContent, validIds, children }) => {
+    const cacheResult = useContentCache({ resolveContent, validIds });
+
+    const value = React.useMemo<ContentCacheContextValue<TId>>(
+      () => cacheResult,
+      [cacheResult],
+    );
+
+    return <Context.Provider value={value}>{children}</Context.Provider>;
+  };
+  Provider.displayName = `${displayName}CacheProvider`;
+
+  return { Provider, useCache, Context };
+}
+
+/**
+ * Props for content cache provider components.
+ */
+export type ContentCacheProviderProps<TId extends string = string> = React.PropsWithChildren<{
+  /**
+   * Function to resolve content by ID.
+   */
+  resolveContent: ContentResolver<TId>;
+  /**
+   * Current valid IDs for cache cleanup.
+   */
+  validIds: readonly TId[];
+}>;