@spark-web/stack 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# @spark-web/stack
+
+## 1.0.0
+
+### Major Changes
+
+- [#27](https://github.com/brighte-labs/spark-web/pull/27)
+  [`4c8e398`](https://github.com/brighte-labs/spark-web/commit/4c8e3988f8a59d3dab60a6b67b1128b6ff2a5f2c)
+  Thanks [@JedWatson](https://github.com/JedWatson)! - Initial Version
+
+### Patch Changes
+
+- Updated dependencies
+  [[`4c8e398`](https://github.com/brighte-labs/spark-web/commit/4c8e3988f8a59d3dab60a6b67b1128b6ff2a5f2c)]:
+  - @spark-web/box@1.0.0
+  - @spark-web/divider@1.0.0
+  - @spark-web/theme@1.0.0
+  - @spark-web/utils@1.0.0

package/README.md

@@ -0,0 +1,118 @@
+---
+title: Stack
+storybookPath: page-layout-stack--default
+---
+
+Used to distribute children vertically, with even spacing between each child.
+
+```jsx live
+<Stack gap="large">
+  <Placeholder />
+  <Placeholder />
+  <Placeholder />
+</Stack>
+```
+
+## Examples
+
+### Gap
+
+The spacing between children can be adjusted using the `gap` prop.
+
+```jsx live
+<Columns gap="xxlarge">
+  <Stack gap="small">
+    <Placeholder />
+    <Placeholder />
+    <Placeholder />
+  </Stack>
+  <Stack gap="medium">
+    <Placeholder />
+    <Placeholder />
+    <Placeholder />
+  </Stack>
+  <Stack gap="large">
+    <Placeholder />
+    <Placeholder />
+    <Placeholder />
+  </Stack>
+  <Stack gap="xlarge">
+    <Placeholder />
+    <Placeholder />
+    <Placeholder />
+  </Stack>
+</Columns>
+```
+
+### Horizontal alignment
+
+Items can be aligned horizontally using the `align` prop.
+
+```jsx live
+<Stack gap="medium" dividers>
+  <Stack gap="small" align="left">
+    <Placeholder />
+    <Placeholder label="left" width={128} />
+    <Placeholder />
+  </Stack>
+  <Stack gap="small" align="center">
+    <Placeholder />
+    <Placeholder label="center" width={128} />
+    <Placeholder />
+  </Stack>
+  <Stack gap="small" align="right">
+    <Placeholder />
+    <Placeholder label="right" width={128} />
+    <Placeholder />
+  </Stack>
+</Stack>
+```
+
+### Dividers
+
+Use the `dividers` property to render a [Divider](/package/divider) between each
+element in the Stack.
+
+```jsx live
+<Stack gap="medium" dividers>
+  <Text>First item</Text>
+  <Text>Second item</Text>
+  <Text>Third item</Text>
+</Stack>
+```
+
+### Nesting
+
+Nest Stack components to create more complex white space rules.
+
+```jsx live
+<Stack gap="xlarge">
+  <Heading level="4">Heading</Heading>
+  <Stack gap="small">
+    <Text>Line 1</Text>
+    <Text>Line 2</Text>
+    <Text>Line 3</Text>
+  </Stack>
+  <Stack gap="small">
+    <Text>Line 1</Text>
+    <Text>Line 2</Text>
+    <Text>Line 3</Text>
+  </Stack>
+</Stack>
+```
+
+## Props
+
+| Prop      | Type                            | Default   | Description                                           |
+| --------- | ------------------------------- | --------- | ----------------------------------------------------- |
+| align?    | [ResponsiveProp<Align\>][align] | 'stretch' | Horizontally align items within the container.        |
+| dividers? | boolean                         |           | Sets whether to place a divider between each element. |
+
+`Stack` props also include [`Box`](/package/box) props and are not listed here
+(excludes `display`, `className`, `alignItems`, `flexDirection`,
+`justifyContent` and `flexWrap`).
+
+Extra props are also passed into the underlying [`Box`](/package/box) component.
+
+[align]:
+  https://bitbucket.org/brighte-energy/energy/src/537c678a81090af545969504776c6b3d2e67743e/spark-web/packages/stack/src/Stack.tsx#spark-web/packages/stack/src/Stack.tsx-21

package/dist/declarations/src/Stack.d.ts

@@ -0,0 +1,21 @@
+import type { BoxProps } from '@spark-web/box';
+import type { ResponsiveProp } from '@spark-web/theme';
+import type { ReactElement } from 'react';
+import type { Align } from './alignment';
+declare type ValidBoxProps = Omit<BoxProps, 'display' | 'className' | 'alignItems' | 'flexDirection' | 'justifyContent' | 'flexWrap'>;
+export declare type StackProps = {
+    /** Horizontally align items within the stack. */
+    align?: ResponsiveProp<Align>;
+    /** Place a divider between each element. */
+    dividers?: boolean;
+} & ValidBoxProps;
+export declare const Stack: <Comp extends import("react").ElementType<any> = "div">(props: {
+    as?: Comp | undefined;
+    ref?: import("react").Ref<Comp extends "symbol" | "clipPath" | "filter" | "mask" | "marker" | "text" | "circle" | "svg" | "animate" | "animateMotion" | "animateTransform" | "defs" | "desc" | "ellipse" | "feBlend" | "feColorMatrix" | "feComponentTransfer" | "feComposite" | "feConvolveMatrix" | "feDiffuseLighting" | "feDisplacementMap" | "feDistantLight" | "feDropShadow" | "feFlood" | "feFuncA" | "feFuncB" | "feFuncG" | "feFuncR" | "feGaussianBlur" | "feImage" | "feMerge" | "feMergeNode" | "feMorphology" | "feOffset" | "fePointLight" | "feSpecularLighting" | "feSpotLight" | "feTile" | "feTurbulence" | "foreignObject" | "g" | "image" | "line" | "linearGradient" | "metadata" | "mpath" | "path" | "pattern" | "polygon" | "polyline" | "radialGradient" | "rect" | "stop" | "switch" | "textPath" | "tspan" | "use" | "view" | keyof HTMLElementTagNameMap | "set" ? (HTMLElementTagNameMap & Pick<SVGElementTagNameMap, "symbol" | "clipPath" | "filter" | "mask" | "marker" | "text" | "circle" | "svg" | "animate" | "animateMotion" | "animateTransform" | "defs" | "desc" | "ellipse" | "feBlend" | "feColorMatrix" | "feComponentTransfer" | "feComposite" | "feConvolveMatrix" | "feDiffuseLighting" | "feDisplacementMap" | "feDistantLight" | "feDropShadow" | "feFlood" | "feFuncA" | "feFuncB" | "feFuncG" | "feFuncR" | "feGaussianBlur" | "feImage" | "feMerge" | "feMergeNode" | "feMorphology" | "feOffset" | "fePointLight" | "feSpecularLighting" | "feSpotLight" | "feTile" | "feTurbulence" | "foreignObject" | "g" | "image" | "line" | "linearGradient" | "metadata" | "mpath" | "path" | "pattern" | "polygon" | "polyline" | "radialGradient" | "rect" | "stop" | "switch" | "textPath" | "tspan" | "use" | "view" | "set">)[Comp] : Comp extends new (...args: any) => any ? InstanceType<Comp> : undefined> | undefined;
+} & Omit<import("react").PropsWithoutRef<import("react").ComponentProps<Comp>>, "as"> & {
+    /** Horizontally align items within the stack. */
+    align?: ResponsiveProp<"left" | "right" | "stretch" | "center"> | undefined;
+    /** Place a divider between each element. */
+    dividers?: boolean | undefined;
+} & ValidBoxProps) => ReactElement<any, string | import("react").JSXElementConstructor<any>>;
+export {};

package/dist/declarations/src/alignment.d.ts

@@ -0,0 +1,14 @@
+declare const alignLookup: {
+    readonly left: "start";
+    readonly center: "center";
+    readonly right: "end";
+    readonly stretch: "stretch";
+};
+export declare type Align = keyof typeof alignLookup;
+export declare const alignToAlignItems: (prop?: import("@spark-web/theme").ResponsiveProp<"left" | "right" | "stretch" | "center"> | undefined) => "stretch" | "center" | "end" | "start" | {
+    mobile: "stretch" | "center" | "end" | "start" | undefined;
+    tablet: "stretch" | "center" | "end" | "start" | undefined;
+    desktop: "stretch" | "center" | "end" | "start" | undefined;
+    wide: "stretch" | "center" | "end" | "start" | undefined;
+} | undefined;
+export {};

package/dist/declarations/src/index.d.ts

@@ -0,0 +1,2 @@
+export { Stack } from './Stack';
+export type { StackProps } from './Stack';

package/dist/spark-web-stack.cjs.d.ts

@@ -0,0 +1 @@
+export * from "./declarations/src/index";

package/dist/spark-web-stack.cjs.dev.js

@@ -0,0 +1,62 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _defineProperty = require('@babel/runtime/helpers/esm/defineProperty');
+var _objectWithoutProperties = require('@babel/runtime/helpers/esm/objectWithoutProperties');
+var React = require('react');
+var box = require('@spark-web/box');
+var divider = require('@spark-web/divider');
+var ts = require('@spark-web/utils/ts');
+var theme = require('@spark-web/theme');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
+
+var React__default = /*#__PURE__*/_interopDefault(React);
+
+var alignLookup = {
+  left: 'start',
+  center: 'center',
+  right: 'end',
+  stretch: 'stretch'
+};
+var alignToAlignItems = theme.createResponsiveMapFn(alignLookup);
+
+var _excluded = ["align", "children", "dividers"];
+var __jsx = React__default["default"].createElement;
+
+function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); enumerableOnly && (symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; })), keys.push.apply(keys, symbols); } return keys; }
+
+function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = null != arguments[i] ? arguments[i] : {}; i % 2 ? ownKeys(Object(source), !0).forEach(function (key) { _defineProperty(target, key, source[key]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)) : ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } return target; }
+var Stack = ts.forwardRefWithAs(function (_ref, forwardedRef) {
+  var _ref$align = _ref.align,
+      align = _ref$align === void 0 ? 'stretch' : _ref$align,
+      children = _ref.children,
+      dividers = _ref.dividers,
+      props = _objectWithoutProperties(_ref, _excluded);
+
+  var alignItems = alignToAlignItems(align);
+
+  var rootProps = _objectSpread({
+    ref: forwardedRef,
+    alignItems: alignItems,
+    display: 'flex',
+    flexDirection: 'column'
+  }, props); // bail early w/o dividers to avoid unnecessary map
+
+
+  if (!dividers) {
+    return __jsx(box.Box, rootProps, children);
+  } // map over children to insert dividers
+  // remove falsy values before mapping, keeps the index in sync
+
+
+  var childArray = React.Children.toArray(children);
+  return __jsx(box.Box, rootProps, childArray.map(function (child, idx) {
+    return __jsx(React.Fragment, {
+      key: child.key || idx
+    }, dividers && idx ? __jsx(divider.Divider, null) : null, child);
+  }));
+});
+
+exports.Stack = Stack;

package/dist/spark-web-stack.cjs.js

@@ -0,0 +1,7 @@
+'use strict';
+
+if (process.env.NODE_ENV === "production") {
+  module.exports = require("./spark-web-stack.cjs.prod.js");
+} else {
+  module.exports = require("./spark-web-stack.cjs.dev.js");
+}

package/dist/spark-web-stack.cjs.prod.js

@@ -0,0 +1,62 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _defineProperty = require('@babel/runtime/helpers/esm/defineProperty');
+var _objectWithoutProperties = require('@babel/runtime/helpers/esm/objectWithoutProperties');
+var React = require('react');
+var box = require('@spark-web/box');
+var divider = require('@spark-web/divider');
+var ts = require('@spark-web/utils/ts');
+var theme = require('@spark-web/theme');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
+
+var React__default = /*#__PURE__*/_interopDefault(React);
+
+var alignLookup = {
+  left: 'start',
+  center: 'center',
+  right: 'end',
+  stretch: 'stretch'
+};
+var alignToAlignItems = theme.createResponsiveMapFn(alignLookup);
+
+var _excluded = ["align", "children", "dividers"];
+var __jsx = React__default["default"].createElement;
+
+function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); enumerableOnly && (symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; })), keys.push.apply(keys, symbols); } return keys; }
+
+function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = null != arguments[i] ? arguments[i] : {}; i % 2 ? ownKeys(Object(source), !0).forEach(function (key) { _defineProperty(target, key, source[key]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)) : ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } return target; }
+var Stack = ts.forwardRefWithAs(function (_ref, forwardedRef) {
+  var _ref$align = _ref.align,
+      align = _ref$align === void 0 ? 'stretch' : _ref$align,
+      children = _ref.children,
+      dividers = _ref.dividers,
+      props = _objectWithoutProperties(_ref, _excluded);
+
+  var alignItems = alignToAlignItems(align);
+
+  var rootProps = _objectSpread({
+    ref: forwardedRef,
+    alignItems: alignItems,
+    display: 'flex',
+    flexDirection: 'column'
+  }, props); // bail early w/o dividers to avoid unnecessary map
+
+
+  if (!dividers) {
+    return __jsx(box.Box, rootProps, children);
+  } // map over children to insert dividers
+  // remove falsy values before mapping, keeps the index in sync
+
+
+  var childArray = React.Children.toArray(children);
+  return __jsx(box.Box, rootProps, childArray.map(function (child, idx) {
+    return __jsx(React.Fragment, {
+      key: child.key || idx
+    }, dividers && idx ? __jsx(divider.Divider, null) : null, child);
+  }));
+});
+
+exports.Stack = Stack;

package/dist/spark-web-stack.esm.js

@@ -0,0 +1,54 @@
+import _defineProperty from '@babel/runtime/helpers/esm/defineProperty';
+import _objectWithoutProperties from '@babel/runtime/helpers/esm/objectWithoutProperties';
+import React, { Children, Fragment } from 'react';
+import { Box } from '@spark-web/box';
+import { Divider } from '@spark-web/divider';
+import { forwardRefWithAs } from '@spark-web/utils/ts';
+import { createResponsiveMapFn } from '@spark-web/theme';
+
+var alignLookup = {
+  left: 'start',
+  center: 'center',
+  right: 'end',
+  stretch: 'stretch'
+};
+var alignToAlignItems = createResponsiveMapFn(alignLookup);
+
+var _excluded = ["align", "children", "dividers"];
+var __jsx = React.createElement;
+
+function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); enumerableOnly && (symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; })), keys.push.apply(keys, symbols); } return keys; }
+
+function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = null != arguments[i] ? arguments[i] : {}; i % 2 ? ownKeys(Object(source), !0).forEach(function (key) { _defineProperty(target, key, source[key]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)) : ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } return target; }
+var Stack = forwardRefWithAs(function (_ref, forwardedRef) {
+  var _ref$align = _ref.align,
+      align = _ref$align === void 0 ? 'stretch' : _ref$align,
+      children = _ref.children,
+      dividers = _ref.dividers,
+      props = _objectWithoutProperties(_ref, _excluded);
+
+  var alignItems = alignToAlignItems(align);
+
+  var rootProps = _objectSpread({
+    ref: forwardedRef,
+    alignItems: alignItems,
+    display: 'flex',
+    flexDirection: 'column'
+  }, props); // bail early w/o dividers to avoid unnecessary map
+
+
+  if (!dividers) {
+    return __jsx(Box, rootProps, children);
+  } // map over children to insert dividers
+  // remove falsy values before mapping, keeps the index in sync
+
+
+  var childArray = Children.toArray(children);
+  return __jsx(Box, rootProps, childArray.map(function (child, idx) {
+    return __jsx(Fragment, {
+      key: child.key || idx
+    }, dividers && idx ? __jsx(Divider, null) : null, child);
+  }));
+});
+
+export { Stack };

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@spark-web/stack",
+  "license": "MIT",
+  "version": "1.0.0",
+  "main": "dist/spark-web-stack.cjs.js",
+  "module": "dist/spark-web-stack.esm.js",
+  "devDependencies": {
+    "@types/react": "^17.0.12"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.14.6",
+    "@emotion/css": "^11.7.1",
+    "@spark-web/box": "^1.0.0",
+    "@spark-web/divider": "^1.0.0",
+    "@spark-web/theme": "^1.0.0",
+    "@spark-web/utils": "^1.0.0",
+    "react": "^17.0.2"
+  },
+  "engines": {
+    "node": ">= 14.13"
+  }
+}

package/src/Stack.stories.tsx

@@ -0,0 +1,27 @@
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+import { Placeholder } from '../../../docs/components/example-helpers';
+import type { StackProps } from './Stack';
+import { Stack } from './Stack';
+
+export default {
+  title: 'Page & Layout / Stack',
+  component: Stack,
+} as ComponentMeta<typeof Stack>;
+
+const StackStory: ComponentStory<typeof Stack> = (args: StackProps) => (
+  <Stack {...args} />
+);
+
+export const Default = StackStory.bind({});
+
+Default.args = {
+  gap: 'large',
+  children: (
+    <>
+      <Placeholder height={40} />
+      <Placeholder height={40} />
+      <Placeholder height={40} />
+    </>
+  ),
+} as StackProps;

package/src/Stack.tsx

@@ -0,0 +1,59 @@
+import type { BoxProps } from '@spark-web/box';
+import { Box } from '@spark-web/box';
+import { Divider } from '@spark-web/divider';
+import type { ResponsiveProp } from '@spark-web/theme';
+import { forwardRefWithAs } from '@spark-web/utils/ts';
+import type { ReactElement } from 'react';
+import { Children, Fragment } from 'react';
+
+import type { Align } from './alignment';
+import { alignToAlignItems } from './alignment';
+
+type ValidBoxProps = Omit<
+  BoxProps,
+  | 'display'
+  | 'className'
+  | 'alignItems'
+  | 'flexDirection'
+  | 'justifyContent'
+  | 'flexWrap'
+>;
+
+export type StackProps = {
+  /** Horizontally align items within the stack. */
+  align?: ResponsiveProp<Align>;
+  /** Place a divider between each element. */
+  dividers?: boolean;
+} & ValidBoxProps;
+
+export const Stack = forwardRefWithAs<'div', StackProps>(
+  ({ align = 'stretch', children, dividers, ...props }, forwardedRef) => {
+    const alignItems = alignToAlignItems(align);
+    const rootProps = {
+      ref: forwardedRef,
+      alignItems,
+      display: 'flex',
+      flexDirection: 'column',
+      ...props,
+    } as const;
+
+    // bail early w/o dividers to avoid unnecessary map
+    if (!dividers) {
+      return <Box {...rootProps}>{children}</Box>;
+    }
+
+    // map over children to insert dividers
+    // remove falsy values before mapping, keeps the index in sync
+    const childArray = Children.toArray(children) as ReactElement[];
+    return (
+      <Box {...rootProps}>
+        {childArray.map((child, idx) => (
+          <Fragment key={child.key || idx}>
+            {dividers && idx ? <Divider /> : null}
+            {child}
+          </Fragment>
+        ))}
+      </Box>
+    );
+  }
+);

package/src/alignment.ts

@@ -0,0 +1,12 @@
+import { createResponsiveMapFn } from '@spark-web/theme';
+
+const alignLookup = {
+  left: 'start',
+  center: 'center',
+  right: 'end',
+  stretch: 'stretch',
+} as const;
+
+export type Align = keyof typeof alignLookup;
+
+export const alignToAlignItems = createResponsiveMapFn(alignLookup);

package/src/index.ts

@@ -0,0 +1,5 @@
+export { Stack } from './Stack';
+
+// types
+
+export type { StackProps } from './Stack';