Updated docs for positioned space / custom handles and cleaned up props

Author: aeagle

README.md

@@ -2,13 +2,13 @@
 
 ![NPM](https://img.shields.io/npm/v/react-spaces.svg) ![Azure Pipelines](https://allan-eagle.visualstudio.com/All%20projects/_apis/build/status/aeagle.react-spaces?branchName=master)
 
-An easy to understand and nestable layout system, React Spaces allow you to divide a page or container into anchored, scrollable and resizable spaces enabling you to build desktop/mobile type user interfaces in the browser. 
+An easy to understand and nestable layout system, React Spaces allow you to divide a page or container into anchored, scrollable and resizable spaces enabling you to build desktop/mobile type user interfaces in the browser.
 
 Rather than a library of visual UI components, Spaces are intended to be the reusable foundational blocks for laying out a UI which responds neatly to view port resizes leaving you to fill them with whatever components you want.
 
-- No styling to achieve simple or complex layouts.
-- Spaces know how to behave in relation to each other and resize accordingly.
-- Spaces don't have any visual element to them (even padding or margins). You can fill them with whatever you want.
+-   No styling to achieve simple or complex layouts.
+-   Spaces know how to behave in relation to each other and resize accordingly.
+-   Spaces don't have any visual element to them (even padding or margins). You can fill them with whatever you want.
 
 **Version 0.2.0 release - read [release notes here](https://www.allaneagle.com/react-spaces/release-0.2.0).**
 
@@ -48,18 +48,20 @@ There are resizable versions of these components called **\<LeftResizable /\>**,
 
 A space which consumes any available area left in the parent container/space taking into account any anchored spaces on every side.
 
+**\<Positioned /\>**
+
+A space which can be absolutely placed within a parent space either by top, left, width and height or by top, left, right and bottom.
+
 **\<Layer /\>**
 
 Layers allow you to create layers within a parent space, for example:
 
 ```html
 <ViewPort>
-  <Layer zIndex="{0}">
-    <LeftResizable size="20%" /> // floating sidebar
-  </Layer>
-  <Layer zIndex="{1}">
-    <Fill />
-  </Layer>
+	<Layer zIndex="{0}"> <LeftResizable size="20%" /> // floating sidebar </Layer>
+	<Layer zIndex="{1}">
+		<Fill />
+	</Layer>
 </ViewPort>
 ```
 

src/components/Anchored.tsx

@@ -2,50 +2,47 @@ import { SizeUnit, Type, AnchorType, ResizeHandlePlacement } from "../core-types
 import * as React from "react";
 import { Space } from "./Space";
 import * as PropTypes from "prop-types";
-import { commonProps, IReactSpaceProps } from "../core-react";
+import { commonProps, IReactSpaceCommonProps, IResizeHandleProps } from "../core-react";
 
-interface IAnchorProps extends IReactSpaceProps {
+export interface IResizableProps extends IReactSpaceCommonProps {
 	size: SizeUnit;
 	order?: number;
-	resizable?: boolean;
 	handleSize?: number;
 	handlePlacement?: ResizeHandlePlacement;
+	handleRender?: (handleProps: IResizeHandleProps) => React.ReactNode;
 	minimumSize?: number;
 	maximumSize?: number;
 	onResizeStart?: () => void | boolean;
 	onResizeEnd?: (newSize: SizeUnit) => void;
 }
 
-export const anchoredProps = {
+export const resizableProps = {
 	...commonProps,
 	...{
 		size: PropTypes.oneOfType([PropTypes.string, PropTypes.number]).isRequired,
 		order: PropTypes.number,
-		resizable: PropTypes.bool,
 		handleSize: PropTypes.number,
 		handlePlacement: PropTypes.oneOf([ResizeHandlePlacement.Inside, ResizeHandlePlacement.OverlayBoundary, ResizeHandlePlacement.OverlayInside]),
+		handleRender: PropTypes.func,
 		minimumSize: PropTypes.number,
 		maximumSize: PropTypes.number,
 		onResizeStart: PropTypes.func,
 		onResizeEnd: PropTypes.func,
 	},
 };
 
-export const resizableProps = {
-	...commonProps,
+export interface IAnchorProps extends IResizableProps {
+	resizable?: boolean;
+}
+
+export const anchoredProps = {
+	...resizableProps,
 	...{
-		size: PropTypes.oneOfType([PropTypes.string, PropTypes.number]).isRequired,
-		order: PropTypes.number,
-		handleSize: PropTypes.number,
-		handlePlacement: PropTypes.oneOf([ResizeHandlePlacement.Inside, ResizeHandlePlacement.OverlayBoundary, ResizeHandlePlacement.OverlayInside]),
-		minimumSize: PropTypes.number,
-		maximumSize: PropTypes.number,
-		onResizeStart: PropTypes.func,
-		onResizeEnd: PropTypes.func,
+		resizable: PropTypes.bool,
 	},
 };
 
-export const LeftResizable: React.FC<Omit<IAnchorProps, "resizable">> = ({ children, size, ...props }) => (
+export const LeftResizable: React.FC<IResizableProps> = ({ children, size, ...props }) => (
 	<Space {...props} type={Type.Anchored} anchor={AnchorType.Left} position={{ left: 0, top: 0, bottom: 0, rightResizable: true, width: size }}>
 		{children}
 	</Space>
@@ -65,7 +62,7 @@ export const Left: React.FC<IAnchorProps> = ({ size, children, resizable, ...com
 
 Left.propTypes = anchoredProps;
 
-export const TopResizable: React.FC<Omit<IAnchorProps, "resizable">> = ({ children, size, ...props }) => (
+export const TopResizable: React.FC<IResizableProps> = ({ children, size, ...props }) => (
 	<Space {...props} type={Type.Anchored} anchor={AnchorType.Top} position={{ left: 0, top: 0, right: 0, bottomResizable: true, height: size }}>
 		{children}
 	</Space>
@@ -85,7 +82,7 @@ export const Top: React.FC<IAnchorProps> = ({ size, children, resizable, ...comm
 
 Top.propTypes = anchoredProps;
 
-export const RightResizable: React.FC<Omit<IAnchorProps, "resizable">> = ({ children, size, ...props }) => (
+export const RightResizable: React.FC<IResizableProps> = ({ children, size, ...props }) => (
 	<Space {...props} type={Type.Anchored} anchor={AnchorType.Right} position={{ bottom: 0, top: 0, right: 0, leftResizable: true, width: size }}>
 		{children}
 	</Space>
@@ -105,7 +102,7 @@ export const Right: React.FC<IAnchorProps> = ({ size, children, resizable, ...co
 
 Right.propTypes = anchoredProps;
 
-export const BottomResizable: React.FC<Omit<IAnchorProps, "resizable">> = ({ children, size, ...props }) => (
+export const BottomResizable: React.FC<IResizableProps> = ({ children, size, ...props }) => (
 	<Space {...props} type={Type.Anchored} anchor={AnchorType.Bottom} position={{ bottom: 0, left: 0, right: 0, topResizable: true, height: size }}>
 		{children}
 	</Space>

src/components/Custom.tsx

@@ -1,29 +1,42 @@
-import { Type, SizeUnit, IPositionalProps, AnchorType, ResizeType, ResizeHandlePlacement } from "../core-types";
+import { Type, SizeUnit, IPositionalProps, AnchorType, ResizeType } from "../core-types";
 import * as React from "react";
 import { Space } from "./Space";
 import * as PropTypes from "prop-types";
-import { commonProps, IReactSpaceProps } from "../core-react";
+import { IReactSpaceCommonProps } from "../core-react";
+import { anchoredProps, IAnchorProps } from "./Anchored";
 
-interface ICustomProps extends IReactSpaceProps {
+type ICustomProps = Omit<IReactSpaceCommonProps & IAnchorProps, "size"> & {
+	// Anchored
+	anchor?: AnchorType;
+	anchorSize?: SizeUnit;
+
+	// Positioned
 	left?: SizeUnit | undefined;
 	top?: SizeUnit | undefined;
 	right?: SizeUnit | undefined;
 	bottom?: SizeUnit | undefined;
 	width?: SizeUnit | undefined;
 	height?: SizeUnit | undefined;
 	isPositioned?: boolean;
-	anchor?: AnchorType;
-	anchorSize?: SizeUnit;
-	resizable?: boolean;
 	resizeTypes?: ResizeType[];
-	handleSize?: number;
-	handlePlacement?: ResizeHandlePlacement;
-	overlayHandle?: boolean;
-	minimumSize?: number;
-	maximumSize?: number;
-	onResizeStart?: () => void | boolean;
-	onResizeEnd?: (newSize: SizeUnit) => void;
-}
+};
+
+const customProps = {
+	...anchoredProps,
+	...{
+		anchor: PropTypes.oneOf([AnchorType.Left, AnchorType.Top, AnchorType.Right, AnchorType.Bottom]),
+		anchorSize: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+
+		left: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+		top: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+		right: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+		bottom: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+		width: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+		height: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+		isPositioned: PropTypes.bool,
+		resizeTypes: PropTypes.any,
+	},
+};
 
 export const Custom: React.FC<ICustomProps> = ({
 	children,
@@ -87,23 +100,4 @@ export const Custom: React.FC<ICustomProps> = ({
 	);
 };
 
-Custom.propTypes = {
-	...commonProps,
-	...{
-		left: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
-		top: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
-		right: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
-		bottom: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
-		width: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
-		height: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
-		isPositioned: PropTypes.bool,
-		anchor: PropTypes.oneOf([AnchorType.Left, AnchorType.Top, AnchorType.Right, AnchorType.Bottom]),
-		anchorSize: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
-		resizable: PropTypes.bool,
-		handleSize: PropTypes.number,
-		minimumSize: PropTypes.number,
-		maximumSize: PropTypes.number,
-		onResizeStart: PropTypes.func,
-		onResizeEnd: PropTypes.func,
-	},
-};
+Custom.propTypes = customProps;

src/components/Fill.tsx

@@ -1,9 +1,9 @@
 import { Type } from "../core-types";
 import * as React from "react";
 import { Space } from "./Space";
-import { commonProps, IReactSpaceProps } from "../core-react";
+import { commonProps, IReactSpaceCommonProps } from "../core-react";
 
-export const Fill: React.FC<IReactSpaceProps> = (props) => (
+export const Fill: React.FC<IReactSpaceCommonProps> = (props) => (
 	<Space {...props} type={Type.Fill} position={{ left: 0, top: 0, right: 0, bottom: 0 }}>
 		{props.children}
 	</Space>

src/components/Fixed.tsx

@@ -2,9 +2,9 @@ import { SizeUnit, Type } from "../core-types";
 import * as React from "react";
 import { Space } from "./Space";
 import * as PropTypes from "prop-types";
-import { commonProps, IReactSpaceProps } from "../core-react";
+import { commonProps, IReactSpaceCommonProps } from "../core-react";
 
-interface IFixedProps extends IReactSpaceProps {
+interface IFixedProps extends IReactSpaceCommonProps {
 	width?: SizeUnit;
 	height: SizeUnit;
 }

src/components/Positioned.tsx

@@ -2,9 +2,9 @@ import { Type, SizeUnit, ResizeType } from "../core-types";
 import * as React from "react";
 import { Space } from "./Space";
 import * as PropTypes from "prop-types";
-import { commonProps, IReactSpaceProps } from "../core-react";
+import { commonProps, IReactSpaceCommonProps } from "../core-react";
 
-interface IPositionedProps extends IReactSpaceProps {
+interface IPositionedProps extends IReactSpaceCommonProps {
 	left?: SizeUnit;
 	top?: SizeUnit;
 	right?: SizeUnit;

src/components/Space.tsx

@@ -39,7 +39,7 @@ const SpaceInner: React.FC<IReactSpaceInnerProps & { wrapperInstance: Space }> =
 		onTouchMove,
 		onTouchEnd,
 		children,
-        handleRender
+		handleRender,
 	} = props;
 
 	const events = {
@@ -91,9 +91,7 @@ const SpaceInner: React.FC<IReactSpaceInnerProps & { wrapperInstance: Space }> =
 
 	return (
 		<>
-			{resizeHandles.mouseHandles.map((handleProps) => (
-				handleRender?.(handleProps) || <div {...handleProps} />
-			))}
+			{resizeHandles.mouseHandles.map((handleProps) => handleRender?.(handleProps) || <div {...handleProps} />)}
 			{React.createElement(
 				props.as || "div",
 				{

src/components/SpaceInfo.tsx

@@ -5,6 +5,9 @@ interface ISpaceInfoProps {
 	children: (info: DOMRect) => JSX.Element;
 }
 
+/**
+ * @deprecated use useCurrentSpace() hook instead
+ */
 export const Info: React.FC<ISpaceInfoProps> = (props) => {
 	const domRect = React.useContext(DOMRectContext);
 

src/components/ViewPort.tsx

@@ -2,9 +2,9 @@ import { Type, SizeUnit } from "../core-types";
 import * as React from "react";
 import { Space } from "./Space";
 import * as PropTypes from "prop-types";
-import { commonProps, IReactSpaceProps } from "../core-react";
+import { commonProps, IReactSpaceCommonProps } from "../core-react";
 
-interface IViewPortProps extends IReactSpaceProps {
+interface IViewPortProps extends IReactSpaceCommonProps {
 	left?: SizeUnit;
 	right?: SizeUnit;
 	top?: SizeUnit;

src/components/stories/00-docs/02-UsefulProperties.stories.mdx renamed to src/components/stories/00-docs/02-CommonProperties.stories.mdx

@@ -1,14 +1,14 @@
-import { Meta, Story, Canvas, Props } from "@storybook/addon-docs/blocks";
-import { CommonHeader, PropsTable, StandardProps } from "../Utils";
-
-<CommonHeader />
-
-<Meta title="React Spaces/Useful properties" />
-
-## Useful properties
-
-Applies to `<Fill />` `<Left />` `<Top />` `<Right />` `<Bottom />` `<LeftResizable />` `<TopResizable />` `<RightResizable />` `<BottomResizable />` `<Positioned />` `<Custom />`
-
-<PropsTable>
-	<StandardProps />
+import { Meta, Story, Canvas, Props } from "@storybook/addon-docs/blocks";
+import { CommonHeader, PropsTable, StandardProps } from "../Utils";
+
+<CommonHeader />
+
+<Meta title="React Spaces/Common properties" />
+
+## Useful properties
+
+Applies to `<Fill />` `<Left />` `<Top />` `<Right />` `<Bottom />` `<LeftResizable />` `<TopResizable />` `<RightResizable />` `<BottomResizable />` `<Positioned />` `<Custom />`
+
+<PropsTable>
+	<StandardProps />
 </PropsTable>