React Collapse Pane

116 | 121 | 126 | {isCollapsed ? collapseOptions.afterToggleButton : collapseOptions.beforeToggleButton} 127 | 128 | 129 |

130 | 131 | ) : null; 132 | 133 | return ( 134 |

135 | 148 | {collapseButton} 149 | 150 | 151 | 152 | 153 | 154 | 158 | 159 |

160 | ); 161 | }; 162 | Resizer.displayName = 'Resizer'; 163 | -------------------------------------------------------------------------------- /src/components/SplitPane/hooks/useSplitPaneResize.ts: -------------------------------------------------------------------------------- 1 | import * as React from 'react'; 2 | import { useCallback, useEffect, useMemo, useRef, useState } from 'react'; 3 | import { SplitPaneProps, CollapseOptions } from '..'; 4 | import { useDragState, BeginDragCallback } from './effects/useDragState'; 5 | import { useMinSizes } from './memos/useMinSizes'; 6 | import { useGetMovedSizes } from './callbacks/useGetMovedSizes'; 7 | import { useIsCollapseReversed } from './memos/useIsCollapseReversed'; 8 | import { useHandleDragFinished } from './callbacks/useHandleDragFinished'; 9 | import { useHandleDragStart } from './callbacks/useHandleDragStart'; 10 | import { useChildPanes } from './memos/useChildPanes'; 11 | import { useGetCurrentPaneSizes } from './callbacks/useGetCurrentPaneSizes'; 12 | import { useCollapseSize } from './callbacks/useCollapseSize'; 13 | import { useUncollapseSize } from './callbacks/useUncollapseSize'; 14 | import { useUpdateCollapsedSizes } from './callbacks/useUpdateCollapsedSizes'; 15 | import { useCollapsedSize } from './memos/useCollapsedSize'; 16 | import { debounce } from '../helpers'; 17 | import { useRecalculateSizes } from './callbacks/useRecalculateSizes'; 18 | import { useEventListener } from '../../../hooks/useEventListener'; 19 | import { Nullable } from '../../../types/utilities'; 20 | 21 | export interface ChildPane { 22 | node: React.ReactChild; 23 | ref: React.RefObject; 24 | key: string; 25 | size: number; 26 | } 27 | interface SplitPaneResizeReturns { 28 | childPanes: ChildPane[]; 29 | resizingIndex: Nullable; 30 | handleDragStart: BeginDragCallback; 31 | } 32 | 33 | interface SplitPaneResizeOptions 34 | extends Pick { 35 | collapsedIndices: number[]; 36 | isLtr: boolean; 37 | collapseOptions?: CollapseOptions; 38 | children: React.ReactChild[]; 39 | isVertical: boolean; 40 | } 41 | 42 | /** 43 | * Manages the dragging, size calculation, collapse calculation, and general state management of the panes. It propogates the results of its complex calculations into the `childPanes` which are used by the rest of the "dumb" react components that just take all of them and render them 44 | */ 45 | export const useSplitPaneResize = (options: SplitPaneResizeOptions): SplitPaneResizeReturns => { 46 | const { 47 | children: originalChildren, 48 | split, 49 | initialSizes: originalDefaults, 50 | minSizes: originalMinSizes, 51 | hooks, 52 | collapsedIndices, 53 | collapsedSizes: originalCollapsedSizes, 54 | collapseOptions, 55 | isVertical, 56 | isLtr, 57 | } = options; 58 | 59 | const children = !Array.isArray(originalChildren) ? [originalChildren] : originalChildren; 60 | // VALUES: const values used throughout the different logic 61 | const paneRefs = useRef(new Map>()); 62 | 63 | const minSizes = useMinSizes({ 64 | minSizes: originalMinSizes, 65 | numSizes: children.length, 66 | collapseOptions, 67 | collapsedIndices, 68 | }); 69 | const collapsedSize = useCollapsedSize({ collapseOptions }); 70 | const childPanes = useChildPanes({ minSizes, children, paneRefs }); 71 | const isReversed = useIsCollapseReversed(collapseOptions); 72 | const initialSizes = useMemo(() => children.map((_c, idx) => originalDefaults?.[idx] ?? 1), [ 73 | children, 74 | originalDefaults, 75 | ]); 76 | 77 | // STATE: a map keeping track of all of the pane sizes 78 | const [sizes, setSizes] = useState(initialSizes); 79 | const [movedSizes, setMovedSizes] = useState(sizes); 80 | const [collapsedSizes, setCollapsedSizes] = useState[]>( 81 | originalCollapsedSizes ?? new Array(children.length).fill(null) 82 | ); 83 | // CALLBACKS callback functions used throughout. all functions are memoized by useCallback 84 | const getMovedSizes = useGetMovedSizes({ 85 | minSizes, 86 | sizes, 87 | isLtr, 88 | collapsedSize, 89 | collapsedIndices, 90 | isReversed, 91 | }); 92 | const getCurrentPaneSizes = useGetCurrentPaneSizes({ childPanes, split }); 93 | const handleDragFinished = useHandleDragFinished({ movedSizes, children, hooks, setSizes }); 94 | const recalculateSizes = useRecalculateSizes({ 95 | setMovedSizes, 96 | minSizes, 97 | collapsedIndices, 98 | collapsedSize, 99 | getCurrentPaneSizes, 100 | setSizes, 101 | originalMinSizes, 102 | }); 103 | 104 | // STATE: if dragging, contains which pane is dragging and what the offset is. If not dragging then null 105 | const { dragState, beginDrag } = useDragState(isVertical, handleDragFinished); 106 | 107 | const collapseSize = useCollapseSize({ 108 | setMovedSizes, 109 | setSizes, 110 | minSizes, 111 | movedSizes, 112 | isReversed, 113 | collapsedIndices, 114 | collapsedSize, 115 | }); 116 | const unCollapseSize = useUncollapseSize({ 117 | isReversed, 118 | movedSizes, 119 | minSizes, 120 | setMovedSizes, 121 | setSizes, 122 | collapsedSize, 123 | collapsedIndices, 124 | }); 125 | const updateCollapsedSizes = useUpdateCollapsedSizes({ 126 | sizes, 127 | collapsedSizes, 128 | setCollapsedSizes, 129 | movedSizes, 130 | collapseSize, 131 | unCollapseSize, 132 | hooks, 133 | }); 134 | 135 | // EFFECTS: manage updates and calculations based on dependency changes for states that are interacted with by multiple functions 136 | useEffect(() => { 137 | if (dragState !== null) setMovedSizes(getMovedSizes(dragState)); 138 | // eslint-disable-next-line react-hooks/exhaustive-deps 139 | }, [dragState]); 140 | useEffect(() => { 141 | if (dragState !== null) hooks?.onChange?.(movedSizes); 142 | }, [dragState, movedSizes, hooks]); 143 | useEffect(() => { 144 | hooks?.onCollapse?.(collapsedSizes); 145 | }, [collapsedSizes, hooks]); 146 | useEffect(() => { 147 | updateCollapsedSizes(collapsedIndices); 148 | // eslint-disable-next-line react-hooks/exhaustive-deps 149 | }, [collapsedIndices]); 150 | // recalculate initial sizes on window size change to maintain min sizes 151 | 152 | const resetSizes = useCallback( 153 | debounce(() => recalculateSizes(), 100), 154 | [recalculateSizes] 155 | ); 156 | useEventListener('resize', resetSizes); 157 | useEffect( 158 | () => recalculateSizes(initialSizes), 159 | // eslint-disable-next-line react-hooks/exhaustive-deps 160 | [] 161 | ); 162 | //populates the sizes of all the initially populated childPanes, adjust sizes based on collapsed state 163 | const childPanesWithSizes: ChildPane[] = useMemo( 164 | () => 165 | childPanes.map((child, index) => { 166 | return { ...child, size: movedSizes[index] }; 167 | }), 168 | [childPanes, movedSizes] 169 | ); 170 | 171 | const handleDragStart = useHandleDragStart({ isReversed, hooks, beginDrag }); 172 | return { 173 | childPanes: childPanesWithSizes, 174 | resizingIndex: dragState?.index ?? null, 175 | handleDragStart, 176 | }; 177 | }; 178 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # react-collapse-pane 2 | 3 | This is intended to be **the** simple, reliable, configurable, and elegant solution to having splittable, draggable and collapsible panes in your React application. 4 | 5 |

6 |

7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 |

37 | 38 | ## [[click for storybook demo]](https://storybook-collapse-pane.netlify.app/) 39 | ## [[click for documentation site]](https://b-zurg.github.io/react-collapse-pane/) 40 | 41 | # Getting Started :rocket: 42 | 43 | Install react-collapse-pane: 44 | ```bash 45 | npm i react-collapse-pane 46 | 47 | # or for yarn 48 | 49 | yarn add react-collapse-pane 50 | ``` 51 | 52 | Once installed you can import the `SplitPane` component in your code. 53 | 54 | ```ts 55 | import { SplitPane } from "react-collapse-pane"; 56 | ``` 57 | 58 | If you're using Typescript the `SplitPaneProps`, as well as a few other helper types type is also available. 59 | 60 | NOTE: Since the upgrade to MUI v5 you need to install a peer dependency style engine. Since there is a decision between styled components and emotion I did not make this an explicit dependency. 61 | 62 | If you want to simply use the default then follow the install guide here https://mui.com/material-ui/getting-started/installation/ 63 | If you want to use styled components then follow the configuration guide here https://mui.com/material-ui/guides/styled-engine/ 64 | 65 | In the future this dependency will be removed, apologies for the hassle while that gets sorted out. The next version will be much leaner. 66 | ```ts 67 | import { SplitPane, SplitPaneProps, ResizerOptions, CollapseOptions, SplitPaneHooks } from "react-collapse-pane"; 68 | ``` 69 | # Quick Start Usage :fire: 70 | 71 | The only component you must interact with is `SplitPane`. This serves as a wrapper for all of the children you wish to lay out. 72 | 73 | All you're required to give is a `split` prop which can be either `"horizontal"` or `"vertical"`. This identifies what the orientation of the split panel will be. 74 | 75 | ```tsx 76 | 77 |

This is the first div

78 |

This is the second div

79 |

This is the third div

80 | This is the fourth but not a div! 81 | 82 | ``` 83 | 84 | What you just did is make a split collapsible panel layout! 85 | 86 | ## Congrats! That was easy! :grin: 87 | 88 | This basically splits the children vertically (i.e. full-height split). The children can be any valid React child. If a child is `null` it will be excluded from being split or displayed. 89 | 90 | By default there is a 1px divider with a grabbable surface of 1rem width or height (depending on the split). If you hover over the divider a button will appear that you can use to collapse the panel. 91 | 92 | There is no limit to the number of elements you have as children. The `SplitPane` will split them all accordingly. 93 | 94 | ## But what about *styling* the resizer, the buttons, controlling the animations, or *RTL* support? :sob: 95 | 96 | This library supports all of these things and more! 97 | 98 | For more details check out [the documentation](https://b-zurg.github.io/react-collapse-pane/) 99 | 100 | # Documentation 101 | 102 | Documentation can be found at https://b-zurg.github.io/react-collapse-pane/ 103 | 104 | If you notice an issue then please make an issue or a PR! All docs are generated from the `docs` folder in the master branch. 105 | 106 | # Contributing and PRs :sparkling_heart: 107 | 108 | If you would like to contribute please check out the [contributor guide](/CONTRIBUTING.md) 109 | 110 | All contributions are welcome! All issues and feature requests are welcome! 111 | 112 | # Credit and Attribution :pray: 113 | 114 | This project did not start off from scratch. The foundation of the project was the excellently written [react-multi-split-pane](https://github.com/neoraider/react-multi-split-pane) library which is itself a typescript rewrite of the [react-split-pane](https://github.com/tomkp/react-split-pane) library. 115 | 116 | Much gratitude to their authors, [@NeoRaider](https://github.com/NeoRaider) and [@tomkp](https://github.com/tomkp) 117 | 118 | ## Contributors ✨ 119 | 120 | Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 |

_{Buzurg Arjmandi}
⚠️ 📖 💻 🎨 💡 📦

_hst44
🐛

131 | 132 | 133 | 134 | 135 | 136 | This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! 137 | -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | # react-collapse-pane 2 | 3 | This is intended to be **the** simple, reliable, configurable, and elegant solution to having splittable, draggable and collapsible panes in your React application. 4 | 5 | # Getting Started 🚀 6 | 7 | Install react-collapse-pane: 8 | ```sh 9 | npm i react-collapse-pane 10 | 11 | # or for yarn 12 | 13 | yarn add react-collapse-pane 14 | 15 | ``` 16 | 17 | Once installed you can import the `SplitPane` component. 18 | 19 | ```ts 20 | import { SplitPane } from "react-collapse-pane"; 21 | ``` 22 | 23 | If you're using Typescript the `SplitPaneProps`, and a few other helper types are also available. 24 | ```ts 25 | import { SplitPane, SplitPaneProps, ResizerOptions, CollapseOptions, SplitPaneHooks } from "react-collapse-pane"; 26 | ``` 27 | # Usage 👓 28 | 29 | ## The Basics - Laying Things Out 📘 30 | 31 | The only component you use is `SplitPane`. This is a wrapper for the children you wish to lay out in a panel form. 32 | 33 | There is only 1 required prop, `split`, which can be either `"horizontal"` or `"vertical"`. This identifies what the orientation of the split panel will be. 34 | 35 | Here's a basic example: 36 | ```tsx 37 | 38 |

This is the first div

39 |

This is the second div

40 |

This is the third div

41 | This is the fourth but not a div! 42 | 43 | ``` 44 | 45 | ?> **Note** There is no limit to the number of divs you have as children. The `SplitPane` will split them all accordingly. 46 | 47 | !> The children can be any valid React child, but if a child is `null` it will be excluded from being split or displayed. 48 | 49 | !> You must have **MORE** than one non-null child in the split-pane otherwise it will log an error and simply render the single child. 50 | 51 | ## Styling the Resizer 💅 52 | 53 | By default there is a 1px divider with some basic CSS. 54 | 55 | This is replaceable with the `css` and `hoverCss` options. No need to worry about pseudo selectors, transitions, animations or anything. You just have to indicate what the divider should look like **before** and **after**. This is accomplished by having two separate divs, one of which fades out and the other which fades in. 56 | 57 | !> **Note!** The css props must be valid `React.CSSProperties` objects. 58 | 59 | The sizer also has a grabbable surface that spans the height (or length) of the split and has a default grabbable surface of `1rem`. This is changeable by the `grabberSize` option which can be set to any valid CSS size value for `width` or `height`. 60 | 61 | ?> As per default React CSS, a number will be interpreted as a `px` value. 62 | 63 | 64 | Here's an example: 65 | 66 | ```tsx 67 | 81 |

This is the first div

82 |

This is the second div

83 | 84 | ``` 85 | 86 | 87 | ## Using a Collapse Button 🤹‍♀️ 88 | 89 | !> This is the killer feature of this library :eyes: 90 | 91 | It's a common need to want to collapse the left or initial panel to give more room for another part of a site or app. This is easily accomplished by including several `CollapseOptions` as a prop to the `SplitPane`. 92 | 93 | * `beforeToggleButton` - the element displayed as the collapse button **before** the panel is collapsed. This is an purely aesthetic component. 94 | * `afterToggleButton` - the element displayed as the collapse button **after** the panel is collapsed. This is an purely aesthetic component. 95 | * `buttonTransition` - the animation applied to the button appear/disappear. Possible options are `zoom`, `grow`, `fade`, or `none`. You can try them out in the storybook. `none` indicates to keep the button always visible. 96 | * `buttonTransitionTimeout` - the time (in millisecons) that the animation for the appear/disappear of the button will take place 97 | * `buttonPositionOffset` - a positive or negative number that will either add or subtract the flex-basis (starting at 100) of an invisible div before or after the button. e.g. 50 would make the "before" 150 and the "after" 50 98 | * `collapseDirection` - `'left' | 'right' | 'up' | 'down'` - this is used to indicate the direction that it should collapse. By default collapsing happens left and up for the vertical and horizontal splits respectively. Valid values for a vertical split are `left` or `right` and valid values for a horizontal split are `up` or `down` 99 | * `collapseSize` - the size of the collapsed panel after it has been collapsed 100 | * `collapseTransitionTimeout` - the duration within the collapse animation will take place 101 | * `overlayCss` - the css applied to a div positioned on top of the content. The overlay div has an initial opacity of zero which transitions to 1 over the course of the collapse. 102 | 103 | Here's an example using a `Button` element imported from elsewhere. 104 | 105 | ```tsx 106 | ⬅, 110 | afterToggleButton: , 111 | overlayCss: { backgroundColor: "black" }, 112 | buttonTransition: "zoom", 113 | buttonPositionOffset: -20, 114 | collapsedSize: 50, 115 | collapseTransitionTimeout: 350, 116 | }} 117 | > 118 |

This is a div

119 |

This is a second div

120 |

This is a third div

121 |

This is a fourth div

122 | 123 | ``` 124 | 125 | ?> **Note!** When collapsing a panel, the `minSize` value is used to freeze the width of the collapsed panel to its minimum size and hides the rest of the content. This allows for a smooth collapse animation and is something to keep in mind. Until the animation reaches the min size it will shrink the panel as normal. Try it out for yourself! 126 | 127 | 128 | ## Hooks and Saving State ⚡ 129 | 130 | The component manages its own state while resizing however also allows an initial state as well as callbacks to save state changes. 131 | 132 | These callbacks are in the `hooks` prop: 133 | ```ts 134 | onDragStarted?: () => void; 135 | onChange?: (sizes: number[]) => void; 136 | onSaveSizes?: (sizes: number[]) => void; 137 | onCollapse?: (collapsedSizes: Nullable[]) => void; 138 | ``` 139 | * `onDragStarted` fires as soon as you click down on a resizer and begin moving 140 | * `onSaveSizes` fires when the movement of a resizer is finished and the mouse lifts **OR** when a panel is collapsed - as both of these trigger size changes. 141 | * `onChange` fires on every size change, which can be **quite** often 142 | * `onCollapse` fires whenever a panel is collapsed, and keeps track of the previously collapsed panes 143 | 144 | The initial state is passed in with these three props: 145 | 146 | ```ts 147 | initialSizes?: number[]; 148 | minSizes?: number | number[]; 149 | collapsedSizes?: Nullable[]; 150 | ``` 151 | * `initialSizes` is the default flex-basis that's given to the panes. This can be a simple ratio if it's the first time the render will happen and there's no saved sizes. e.g. `[1, 2, 1]` would make the second panel twice as big as its siblings. If you're saving state this should be the saved size value on a second render. 152 | * `minSizes` is either (1) a minimum size that's given to **all** the panes, or (2) an array of minimum sizes that's given to each pane in order. Any missing sizes in the array will be assumed default. 153 | * `collapsedSizes` an array of nullable numbers. This keeps track of a pane's size before it was collapsed. If not collapsed it's null. This will determine which panels are collapsed and what to do when they're uncollapsed. 154 | 155 | Typically if this is a controlled component you would have state variables for `initialSizes` and `collapsedSizes` and have callbacks on `onSaveSizes` and `onCollapse` that would save the two data points and pass them back into the `SplitPane` on a remount. The `minSizes` would typically never change. 156 | 157 | 158 | ## RTL Support ( Arabic, Hebrew, Farsi ) 🕋 159 | 160 | This library easily supports RTL languages by providing a `direction` prop. This is only necessary if you're using RTL. 161 | 162 | **Note!** 🚨 the `direction` is _only_ applicable if the split is `vertical` 163 | 164 | ```tsx 165 |

166 | 170 |

اللوحة الأولى

171 |

اللوحة الثانية

172 |

اللوحة الثالثة

173 |

اللوحة الرابعة

174 | 175 |

176 | ``` 177 | 178 | # Note about Polyfills 179 | * If you require IE11 support then you will need to add a pollyfill for `AbortController` 180 | * If you are using the ionic framework then you will need a polyfill for `resize-observer-polyfill` otherwise the pane size calculation will not work. -------------------------------------------------------------------------------- /logo.svg: -------------------------------------------------------------------------------- 1 | 11 | --------------------------------------------------------------------------------