Skip to content

Commit

Permalink
docs: big changes to documentation structure and initial story
Browse files Browse the repository at this point in the history
  • Loading branch information
@b-zurg
b-zurg committed Jun 22, 2020
1 parent dd1c4ff commit a59a2c0
Show file tree
Hide file tree
Showing 4 changed files with 96 additions and 182 deletions.
145 changes: 19 additions & 126 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This is intended to be **the** simple, reliable, configurable, and elegant solution to having splittable, draggable and collapsible panes in your React application.

<a href="https://react-collapse-pane.zurg.dev" target="_blank"><img src="logo.svg" alt="logo" style="width:100%"/></a>
<a href="https://collapse-pane.zurg.dev" target="_blank"><img src="logo.svg" alt="logo" style="width:100%"/></a>
<p align="center">
<a href="https://github.com/b-zurg/react-collapse-pane/pulls">
<img alt="prs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg">
Expand Down Expand Up @@ -35,7 +35,8 @@ This is intended to be **the** simple, reliable, configurable, and elegant solut

</p>

## [[click for storybook demo]](https://react-collapse-pane.zurg.dev/)
## [[click for storybook demo]](https://storybook.collapse-pane.zurg.dev/)
## [[click for documentation site]](https://collapse-pane.zurg.dev/)

# Getting Started :rocket:

Expand All @@ -57,13 +58,12 @@ If you're using Typescript the `SplitPaneProps`, as well as a few other helper t
```ts
import { SplitPane, SplitPaneProps, ResizerOptions, CollapseOptions, SplitPaneHooks } from "react-collapse-pane";
```
# Usage 🗻
# Quick Start Usage :fire:

## The Basics 📘
The only component you must interact with is `SplitPane`. This serves as a wrapper for all of the children you wish to lay out.

The only component you must interact with is `SplitPane`. This serves as a wrapper for the children you wish to layout in a panel form.
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.

Here's a basic example:
```tsx
<SplitPane split="vertical">
<div>This is the first div</div>
Expand All @@ -73,147 +73,40 @@ Here's a basic example:
</SplitPane>
```

This will split the children. The children can be any valid React child. If a child is `null` it will be excluded from being split or displayed.
What you just did is make a splittable panel layout!

**Note!** :eyes: There is no limit to the number of divs you have as children. The `SplitPane` will split them all accordingly.
## Congrats! That was easy! :grin:

## Styling the Resizer 💅
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.

By default there is a 1px divider that starts out `rgba(120, 120, 120, 0.3)` and transitions to `rgba(120, 120, 120, 0.6)` on hover. Having a grey color with an alpha value means that it will look nice on both light and dark backgrounds.
By default there is a 1px divider with a grabbable surface of 1rem width or height (depending on the split).

This is easily 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.

**Note** 🚨 The css props must be valid `React.CSSProperties` objects.
There is also no limit to the number of divs you have as children. The `SplitPane` will split them all accordingly.

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`.
## But what about collapsing the panels, styling the resizer, or RTL support? :sob:

**Note!** :eyes: As per default React CSS, a number will be interpreted as a `px` value.
This library supports all of these things and more!

For more details check out [the documentation](https://collapse-pane.zurg.dev/)

Here's an example:
# Documentation

```tsx
<SplitPane
split="vertical"
resizerOptions={{
css: {
width: '1px',
background: 'rgba(0, 0, 0, 0.1)',
},
hoverCss: {
width: '3px',
background: '1px solid rgba(102, 194, 255, 0.5)',
},
grabberSize: '1rem',
}}
>
<div>This is the first div</div>
<div>This is the second div</div>
</SplitPane>
```


## Using a Collapse Button 🤹‍♀️

This is the killer feature of this library :eyes:

It's a common UX 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`.

* `beforeToggleButton` - the element displayed as the collapse button **before** the panel is collapsed. This is an purely aesthetic component.
* `afterToggleButton` - the element displayed as the collapse button **after** the panel is collapsed. This is an purely aesthetic component.
* `buttonTransition` - the animation applied to the button appear/disappear. Possible options are `zoom`, `grow`, or `fade`
* `buttonTransitionTimeout` - the time (in millisecons) that the animation for the appear/disappear of the button will take place
* `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
* `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`
* `collapseSize` - the size of the collapsed panel after it has been collapsed
* `collapseTransitionTimeout` - the duration within the collapse animation will take place
* `overlayCss` - the css applied to a div positioned on top of the content.

Here's an example using a `Button` element imported from elsewhere.

```tsx
<SplitPane
split="vertical"
collapseOptions={{
beforeToggleButton: <Button>⬅</Button>,
afterToggleButton: <Button>➡</Button>,
overlayCss: { backgroundColor: "black" },
buttonTransition: "zoom",
buttonPositionOffset: -20,
collapsedSize: 50,
collapseTransitionTimeout: 350,
}}
>
<div>This is a div</div>
<div>This is a second div</div>
<div>This is a third div</div>
<div>This is a fourth div</div>
</SplitPane>
```

**Note!** :eyes: 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!
Documentation can be found at https://collapse-pane.zurg.dev

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.

## Hooks and Saving State ⚡

The component manages its own state while resizing however also allows an initial state as well as callbacks to save state changes.

These callbacks are in the `hooks` prop:
```ts
onDragStarted?: () => void;
onChange?: (sizes: number[]) => void;
onSaveSizes?: (sizes: number[]) => void;
onCollapse?: (collapsedSizes: Nullable<number>[]) => void;
```
* `onDragStarted` fires as soon as you click down on a resizer and begin moving
* `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.
* `onChange` fires on every size change, which can be **quite** often
* `onCollapse` fires whenever a panel is collapsed, and keeps track of the previously collapsed panes

The initial state is passed in with these three props:

```ts
initialSizes?: number[];
minSizes?: number | number[];
collapsedSizes?: Nullable<number>[];
```
* `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.
* `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.
* `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.

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.


## RTL Support ( Arabic, Hebrew, Farsi ) 🕋

This library easily supports RTL languages by providing a `direction` prop. This is only necessary if you're using RTL and can be left out.

**Note!** 🚨 the `direction` is _only_ applicable if the split is `vertical`

e.g.
```tsx
<div style={{ direction: 'rtl' }}>
<SplitPane
split="vertical"
direction="rtl"
>
<div>اللوحة الأولى</div>
<div>اللوحة الثانية</div>
<div>اللوحة الثالثة</div>
<div>اللوحة الرابعة</div>
</SplitPane>
</div>
```

# Contributing and PRs 💖
# Contributing and PRs :sparkling_heart:

If you would like to contribute please check out the [contributor guide](/CONTRIBUTING.md)

All contributions are welcome! All issues and feature requests are welcome!



# Credit and Attribution 🙏
# Credit and Attribution :pray:

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.

Expand Down
23 changes: 11 additions & 12 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@
This is intended to be **the** simple, reliable, configurable, and elegant solution to having splittable, draggable and collapsible panes in your React application.


## [[click for storybook demo]](https://react-collapse-pane.zurg.dev/)
## [[click for storybook demo]](https://storybook.collapse-pane.zurg.dev/)

# Getting Started :rocket:
# Getting Started 🚀

Install react-collapse-pane:
```bash
```sh
npm i --save-dev react-collapse-pane
```
```bash
```sh
yarn add --dev react-collapse-pane
```

Expand All @@ -25,7 +25,7 @@ If you're using Typescript the `SplitPaneProps`, as well as a few other helper t
```ts
import { SplitPane, SplitPaneProps, ResizerOptions, CollapseOptions, SplitPaneHooks } from "react-collapse-pane";
```
# Usage 🗻
# Usage 👓

## The Basics 📘

Expand All @@ -45,19 +45,19 @@ Here's a basic example:

This will split the children. The children can be any valid React child. If a child is `null` it will be excluded from being split or displayed.

**Note!** :eyes: There is no limit to the number of divs you have as children. The `SplitPane` will split them all accordingly.
?> **Note** there is no limit to the number of divs you have as children. The `SplitPane` will split them all accordingly.

## Styling the Resizer 💅

By default there is a 1px divider that starts out `rgba(120, 120, 120, 0.3)` and transitions to `rgba(120, 120, 120, 0.6)` on hover. Having a grey color with an alpha value means that it will look nice on both light and dark backgrounds.

This is easily 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.

**Note** 🚨 The css props must be valid `React.CSSProperties` objects.
!> **Note!** The css props must be valid `React.CSSProperties` objects.

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`.

**Note!** :eyes: As per default React CSS, a number will be interpreted as a `px` value.
?> As per default React CSS, a number will be interpreted as a `px` value.


Here's an example:
Expand Down Expand Up @@ -85,7 +85,7 @@ Here's an example:

## Using a Collapse Button 🤹‍♀️

This is the killer feature of this library :eyes:
!> This is the killer feature of this library :eyes:

It's a common UX 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`.

Expand Down Expand Up @@ -121,7 +121,7 @@ Here's an example using a `Button` element imported from elsewhere.
</SplitPane>
```

**Note!** :eyes: 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!
?> **Note!** :eyes: 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!


## Hooks and Saving State ⚡
Expand Down Expand Up @@ -156,11 +156,10 @@ Typically if this is a controlled component you would have state variables for `

## RTL Support ( Arabic, Hebrew, Farsi ) 🕋

This library easily supports RTL languages by providing a `direction` prop. This is only necessary if you're using RTL and can be left out.
This library easily supports RTL languages by providing a `direction` prop. This is only necessary if you're using RTL.

**Note!** 🚨 the `direction` is _only_ applicable if the split is `vertical`

e.g.
```tsx
<div style={{ direction: 'rtl' }}>
<SplitPane
Expand Down
10 changes: 7 additions & 3 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,12 @@
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Document</title>
<title>react-collapse-pane</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="Description">
<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/dark.css">
<link rel='shortcut icon' type='image/x-icon' href='/icon.svg' />
</head>
<body>
<div id="app"></div>
Expand All @@ -17,9 +18,12 @@
coverpage: true,
autoHeader: true,
themeColor: '#ff96d8',

search: 'auto',
search: [ '/' ]
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>
</body>
</html>
Loading

0 comments on commit a59a2c0

Please sign in to comment.