Merge branch 'main' into programmatic-reset

README.md

@@ -60,7 +60,67 @@ export const App = () => (
 );
 ```
 
-### Styling
+If you want more control over the behaviour of the individual panes you can use the `Allotment.Pane` component. This includes setting the minimum and maximum size of a pane, as well as whether to enable snapping behaviour.
+
+```jsx
+<Allotment >
+  <Allotment.Pane minSize={200}>
+    <ComponentA>
+  </Allotment.Pane>
+  <Allotment.Pane snap>
+    <ComponentB>
+  </Allotment.Pane>
+</Allotment>
+```
+
+## Allotment props
+
+### defaultSizes
+
+An array of initial sizes of the panes. If the sum of the sizes differs from the size of the container then the panes' sizes will be scaled proportionally.
+
+```jsx
+<Allotment defaultSizes={[100, 200]}>
+  <div />
+  <div />
+</Allotment>
+```
+
+### maxSize (default: `Infinity`)
+
+Maximum size of any pane.
+
+### minSize (default: `30`)
+
+Minimum size of any pane.
+
+### snap
+
+Enable snap to zero for all panes.
+
+### vertical (default: `false`)
+
+Direction to split. If true then the panes will be stacked vertically, otherwise they will be stacked horizontally.
+
+### onChange
+
+Callback that is fired when the pane sizes change (usually on drag). Recommended to add a debounce function to rate limit the callback.
+
+## Allotment.Pane props
+
+### maxSize
+
+Maximum size of this pane. Overrides `maxSize` set on parent component.
+
+### minSize
+
+Minimum size of this pane. Overrides `minSize` set on parent component.
+
+### snap
+
+Enable snap to zero for this pane. Overrides `snap` set on parent component.
+
+## Styling
 
 Allotment uses [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) for styling.
 You can customize the following default variables.

src/allotment.tsx

@@ -46,7 +46,14 @@ export type AllotmentHandle = { reset: () => void };
 
 export type AllotmentProps = {
   children: React.ReactNode;
-  /** Initial size of each element */
+  /**
+   * Initial size of each element
+   */
+  defaultSizes?: number[];
+  /**
+   * Initial size of each element
+   * @deprecated Use {@link AllotmentProps.defaultSizes defaultSizes} instead
+   */
   sizes?: number[];
   /** Direction to split */
   vertical?: boolean;
@@ -61,6 +68,7 @@ const Allotment = forwardRef<AllotmentHandle, AllotmentProps>(
       maxSize = Infinity,
       minSize = 30,
       sizes,
+      defaultSizes = sizes,
       snap = false,
       vertical = false,
       onChange,
@@ -73,6 +81,12 @@ const Allotment = forwardRef<AllotmentHandle, AllotmentProps>(
     const splitViewRef = useRef<SplitView | null>(null);
     const splitViewViewRef = useRef(new Map<React.Key, HTMLElement>());
 
+    if (process.env.NODE_ENV !== "production" && sizes) {
+      console.warn(
+        `Prop sizes is deprecated. Please use defaultSizes instead.`
+      );
+    }
+
     const childrenArray = useMemo(
       () => React.Children.toArray(children).filter(React.isValidElement),
       [children]

stories/allotment.stories.tsx

@@ -90,7 +90,11 @@ export const PersistSizes: Story<{ numViews: number; vertical: boolean }> = ({
   return (
     <div className={styles.container}>
       {hasReadFromLocalStorage && (
-        <Allotment vertical={vertical} onChange={handleChange} sizes={sizes}>
+        <Allotment
+          vertical={vertical}
+          onChange={handleChange}
+          defaultSizes={sizes}
+        >
           {views.map((view) => (
             <div key={view.id} className={styles.content}>
               {view.id}