@spark-web/columns 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @spark-web/columns
+
+## 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/theme@1.0.0
+  - @spark-web/utils@1.0.0

package/README.md

@@ -0,0 +1,96 @@
+---
+title: Columns
+storybookPath: page-layout-columns--default
+---
+
+Use the columns primitive to layout content in configurable columns.
+
+Each child represents a single column. By default that column will span 1
+fraction of the total number of children.
+
+```jsx live
+<Columns>
+  <Placeholder />
+  <Placeholder />
+  <Placeholder />
+</Columns>
+```
+
+## Examples
+
+### Gap
+
+The spacing between children can be adjusted using the `gap` prop.
+
+```jsx live
+<Columns gap="large">
+  <Placeholder />
+  <Placeholder />
+  <Placeholder />
+</Columns>
+```
+
+### Vertical alignment
+
+Columns can be aligned vertically using the `alignY` prop.
+
+```jsx live
+<Stack gap="medium" dividers>
+  <Columns gap="small" alignY="top">
+    <Placeholder />
+    <Placeholder label="top (default)" height={64} />
+    <Placeholder />
+  </Columns>
+  <Columns gap="small" alignY="center">
+    <Placeholder />
+    <Placeholder label="center" height={64} />
+    <Placeholder />
+  </Columns>
+  <Columns gap="small" alignY="bottom">
+    <Placeholder />
+    <Placeholder label="bottom" height={64} />
+    <Placeholder />
+  </Columns>
+  <Columns gap="small" alignY="stretch">
+    <Placeholder />
+    <Placeholder label="stretch" height={64} />
+    <Placeholder />
+  </Columns>
+</Stack>
+```
+
+### Collapsing across breakpoints
+
+Columns can be collapsed into a single vertical stack responsively using the
+`collapseBelow` prop.
+
+```jsx live
+<Columns gap="large" collapseBelow="desktop">
+  <Placeholder />
+  <Placeholder />
+  <Placeholder />
+</Columns>
+```
+
+## Props
+
+| Prop           | Type                                                    | Default | Description                                                                            |
+| -------------- | ------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------- |
+| alignY?        | [ResponsiveProp][responsive-prop]<AlignY\>              |         | Vertically align items within the container.                                           |
+| children       | React.ReactNode                                         |         | Children elements to be rendered within the column component representing each column. |
+| collapseBelow? | [ResponsiveRangeProps][responsive-range-props]('below') |         | At which breakpoint, if amy, should the columns collapse.                              |
+| gap?           | [Gap][gap]                                              |         | The size of the gap between each column.                                               |
+| template?      | number[]                                                |         | Define the relative width of each column. By default each column is the same width.    |
+
+[`Box`](/package/box) props are also included as `Column` props and are not
+listed here (excluding `display`, `alignItems`, `gap`, `flexDirection`,
+`justifyContent` and `flexWrap`).
+
+Extra props are passed into the underlying [`Box`](/package/box) component.
+
+[responsive-prop]:
+  https://bitbucket.org/brighte-energy/energy/src/537c678a81090af545969504776c6b3d2e67743e/spark-web/packages/theme/src/themeUtils.ts#spark-web/packages/theme/src/themeUtils.ts-11
+[responsive-range-props]:
+  https://bitbucket.org/brighte-energy/energy/src/537c678a81090af545969504776c6b3d2e67743e/spark-web/packages/theme/src/themeutils.ts#spark-web/packages/theme/src/themeutils.ts-130
+[gap]:
+  https://bitbucket.org/brighte-energy/energy/src/537c678a81090af545969504776c6b3d2e67743e/spark-web/packages/columns/src/Columns.tsx#spark-web/packages/columns/src/Columns.tsx-14

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

@@ -0,0 +1,34 @@
+import type { BoxProps } from '@spark-web/box';
+import type { BrighteTheme, ResponsiveProp, ResponsiveRangeProps } from '@spark-web/theme';
+import type { ReactNode } from 'react';
+import type { AlignY } from './alignment';
+declare type Gap = ResponsiveProp<keyof Omit<BrighteTheme['spacing'], 'none'>>;
+declare type ValidBoxProps = Omit<BoxProps, 'display' | 'alignItems' | 'gap' | 'flexDirection' | 'justifyContent' | 'flexWrap'>;
+export declare type ColumnsProps = {
+    /** Vertically align items within the container. */
+    alignY?: ResponsiveProp<AlignY>;
+    /** Elements representing each column. */
+    children: ReactNode;
+    /** At which breakpoint, if any, should the columns collapse. */
+    collapseBelow?: ResponsiveRangeProps['below'];
+    /** The size of the gap between each column. */
+    gap?: Gap;
+    /** Define the relative width of each column. By default each column is the same width. */
+    template?: number[];
+} & ValidBoxProps;
+export declare const Columns: <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"> & {
+    /** Vertically align items within the container. */
+    alignY?: ResponsiveProp<"bottom" | "top" | "stretch" | "center"> | undefined;
+    /** Elements representing each column. */
+    children: ReactNode;
+    /** At which breakpoint, if any, should the columns collapse. */
+    collapseBelow?: ResponsiveRangeProps['below'];
+    /** The size of the gap between each column. */
+    gap?: Gap | undefined;
+    /** Define the relative width of each column. By default each column is the same width. */
+    template?: number[] | undefined;
+} & ValidBoxProps) => import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
+export {};

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

@@ -0,0 +1,14 @@
+declare const alignYLookup: {
+    readonly top: "start";
+    readonly center: "center";
+    readonly bottom: "end";
+    readonly stretch: "stretch";
+};
+export declare type AlignY = keyof typeof alignYLookup;
+export declare const alignYToAlignItems: (prop?: import("@spark-web/theme").ResponsiveProp<"bottom" | "top" | "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 { Columns } from './Columns';
+export type { ColumnsProps } from './Columns';

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

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

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

@@ -0,0 +1,70 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _extends = require('@babel/runtime/helpers/esm/extends');
+var _slicedToArray = require('@babel/runtime/helpers/esm/slicedToArray');
+var _objectWithoutProperties = require('@babel/runtime/helpers/esm/objectWithoutProperties');
+var React = require('react');
+var css = require('@emotion/css');
+var box = require('@spark-web/box');
+var theme = require('@spark-web/theme');
+var ts = require('@spark-web/utils/ts');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
+
+var React__default = /*#__PURE__*/_interopDefault(React);
+
+var alignYLookup = {
+  top: 'start',
+  center: 'center',
+  bottom: 'end',
+  stretch: 'stretch'
+};
+var alignYToAlignItems = theme.createResponsiveMapFn(alignYLookup);
+
+var _excluded = ["alignY", "collapseBelow", "gap", "template"];
+var __jsx = React__default["default"].createElement;
+var Columns = ts.forwardRefWithAs(function (_ref, forwardedRef) {
+  var _ref$alignY = _ref.alignY,
+      alignY = _ref$alignY === void 0 ? 'top' : _ref$alignY,
+      collapseBelow = _ref.collapseBelow,
+      gap = _ref.gap,
+      template = _ref.template,
+      props = _objectWithoutProperties(_ref, _excluded);
+
+  var _useTheme = theme.useTheme(),
+      spacing = _useTheme.spacing,
+      utils = _useTheme.utils;
+
+  var alignItems = alignYToAlignItems(alignY);
+  var count = React.Children.count(props.children);
+  var gridTemplateColumns = template ? template.map(function (c) {
+    return "".concat(c, "fr");
+  }).join(' ') : "repeat(".concat(count, ", 1fr)");
+
+  var _utils$responsiveRang = utils.responsiveRange({
+    below: collapseBelow
+  }),
+      _utils$responsiveRang2 = _slicedToArray(_utils$responsiveRang, 4),
+      collapseOnMobile = _utils$responsiveRang2[0],
+      collapseOnTablet = _utils$responsiveRang2[1],
+      collapseOnDesktop = _utils$responsiveRang2[2],
+      collapseOnWide = _utils$responsiveRang2[3];
+
+  return __jsx(box.Box, _extends({
+    ref: forwardedRef,
+    className: css.css(utils.resolveResponsiveProps({
+      alignItems: alignItems,
+      display: 'grid',
+      gap: utils.mapResponsiveScale(gap, spacing),
+      gridTemplateColumns: collapseBelow ? utils.optimizeResponsiveArray([collapseOnMobile ? null : gridTemplateColumns, collapseOnTablet ? null : gridTemplateColumns, collapseOnDesktop ? null : gridTemplateColumns, collapseOnWide ? null : gridTemplateColumns]) : gridTemplateColumns,
+      // fix flex overflow bug that prevents text truncation
+      '> *': {
+        minWidth: 0
+      }
+    }))
+  }, props));
+});
+
+exports.Columns = Columns;

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

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

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

@@ -0,0 +1,70 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _extends = require('@babel/runtime/helpers/esm/extends');
+var _slicedToArray = require('@babel/runtime/helpers/esm/slicedToArray');
+var _objectWithoutProperties = require('@babel/runtime/helpers/esm/objectWithoutProperties');
+var React = require('react');
+var css = require('@emotion/css');
+var box = require('@spark-web/box');
+var theme = require('@spark-web/theme');
+var ts = require('@spark-web/utils/ts');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
+
+var React__default = /*#__PURE__*/_interopDefault(React);
+
+var alignYLookup = {
+  top: 'start',
+  center: 'center',
+  bottom: 'end',
+  stretch: 'stretch'
+};
+var alignYToAlignItems = theme.createResponsiveMapFn(alignYLookup);
+
+var _excluded = ["alignY", "collapseBelow", "gap", "template"];
+var __jsx = React__default["default"].createElement;
+var Columns = ts.forwardRefWithAs(function (_ref, forwardedRef) {
+  var _ref$alignY = _ref.alignY,
+      alignY = _ref$alignY === void 0 ? 'top' : _ref$alignY,
+      collapseBelow = _ref.collapseBelow,
+      gap = _ref.gap,
+      template = _ref.template,
+      props = _objectWithoutProperties(_ref, _excluded);
+
+  var _useTheme = theme.useTheme(),
+      spacing = _useTheme.spacing,
+      utils = _useTheme.utils;
+
+  var alignItems = alignYToAlignItems(alignY);
+  var count = React.Children.count(props.children);
+  var gridTemplateColumns = template ? template.map(function (c) {
+    return "".concat(c, "fr");
+  }).join(' ') : "repeat(".concat(count, ", 1fr)");
+
+  var _utils$responsiveRang = utils.responsiveRange({
+    below: collapseBelow
+  }),
+      _utils$responsiveRang2 = _slicedToArray(_utils$responsiveRang, 4),
+      collapseOnMobile = _utils$responsiveRang2[0],
+      collapseOnTablet = _utils$responsiveRang2[1],
+      collapseOnDesktop = _utils$responsiveRang2[2],
+      collapseOnWide = _utils$responsiveRang2[3];
+
+  return __jsx(box.Box, _extends({
+    ref: forwardedRef,
+    className: css.css(utils.resolveResponsiveProps({
+      alignItems: alignItems,
+      display: 'grid',
+      gap: utils.mapResponsiveScale(gap, spacing),
+      gridTemplateColumns: collapseBelow ? utils.optimizeResponsiveArray([collapseOnMobile ? null : gridTemplateColumns, collapseOnTablet ? null : gridTemplateColumns, collapseOnDesktop ? null : gridTemplateColumns, collapseOnWide ? null : gridTemplateColumns]) : gridTemplateColumns,
+      // fix flex overflow bug that prevents text truncation
+      '> *': {
+        minWidth: 0
+      }
+    }))
+  }, props));
+});
+
+exports.Columns = Columns;

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

@@ -0,0 +1,62 @@
+import _extends from '@babel/runtime/helpers/esm/extends';
+import _slicedToArray from '@babel/runtime/helpers/esm/slicedToArray';
+import _objectWithoutProperties from '@babel/runtime/helpers/esm/objectWithoutProperties';
+import React, { Children } from 'react';
+import { css } from '@emotion/css';
+import { Box } from '@spark-web/box';
+import { createResponsiveMapFn, useTheme } from '@spark-web/theme';
+import { forwardRefWithAs } from '@spark-web/utils/ts';
+
+var alignYLookup = {
+  top: 'start',
+  center: 'center',
+  bottom: 'end',
+  stretch: 'stretch'
+};
+var alignYToAlignItems = createResponsiveMapFn(alignYLookup);
+
+var _excluded = ["alignY", "collapseBelow", "gap", "template"];
+var __jsx = React.createElement;
+var Columns = forwardRefWithAs(function (_ref, forwardedRef) {
+  var _ref$alignY = _ref.alignY,
+      alignY = _ref$alignY === void 0 ? 'top' : _ref$alignY,
+      collapseBelow = _ref.collapseBelow,
+      gap = _ref.gap,
+      template = _ref.template,
+      props = _objectWithoutProperties(_ref, _excluded);
+
+  var _useTheme = useTheme(),
+      spacing = _useTheme.spacing,
+      utils = _useTheme.utils;
+
+  var alignItems = alignYToAlignItems(alignY);
+  var count = Children.count(props.children);
+  var gridTemplateColumns = template ? template.map(function (c) {
+    return "".concat(c, "fr");
+  }).join(' ') : "repeat(".concat(count, ", 1fr)");
+
+  var _utils$responsiveRang = utils.responsiveRange({
+    below: collapseBelow
+  }),
+      _utils$responsiveRang2 = _slicedToArray(_utils$responsiveRang, 4),
+      collapseOnMobile = _utils$responsiveRang2[0],
+      collapseOnTablet = _utils$responsiveRang2[1],
+      collapseOnDesktop = _utils$responsiveRang2[2],
+      collapseOnWide = _utils$responsiveRang2[3];
+
+  return __jsx(Box, _extends({
+    ref: forwardedRef,
+    className: css(utils.resolveResponsiveProps({
+      alignItems: alignItems,
+      display: 'grid',
+      gap: utils.mapResponsiveScale(gap, spacing),
+      gridTemplateColumns: collapseBelow ? utils.optimizeResponsiveArray([collapseOnMobile ? null : gridTemplateColumns, collapseOnTablet ? null : gridTemplateColumns, collapseOnDesktop ? null : gridTemplateColumns, collapseOnWide ? null : gridTemplateColumns]) : gridTemplateColumns,
+      // fix flex overflow bug that prevents text truncation
+      '> *': {
+        minWidth: 0
+      }
+    }))
+  }, props));
+});
+
+export { Columns };

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@spark-web/columns",
+  "license": "MIT",
+  "version": "1.0.0",
+  "main": "dist/spark-web-columns.cjs.js",
+  "module": "dist/spark-web-columns.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/theme": "^1.0.0",
+    "@spark-web/utils": "^1.0.0",
+    "react": "^17.0.2"
+  },
+  "engines": {
+    "node": ">= 14.13"
+  }
+}

package/src/Columns.stories.tsx

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

package/src/Columns.tsx

@@ -0,0 +1,85 @@
+import { css } from '@emotion/css';
+import type { BoxProps } from '@spark-web/box';
+import { Box } from '@spark-web/box';
+import type {
+  BrighteTheme,
+  ResponsiveProp,
+  ResponsiveRangeProps,
+} from '@spark-web/theme';
+import { useTheme } from '@spark-web/theme';
+import { forwardRefWithAs } from '@spark-web/utils/ts';
+import type { ReactNode } from 'react';
+import { Children } from 'react';
+
+import type { AlignY } from './alignment';
+import { alignYToAlignItems } from './alignment';
+
+type Gap = ResponsiveProp<keyof Omit<BrighteTheme['spacing'], 'none'>>;
+type ValidBoxProps = Omit<
+  BoxProps,
+  | 'display'
+  | 'alignItems'
+  | 'gap'
+  | 'flexDirection'
+  | 'justifyContent'
+  | 'flexWrap'
+>;
+
+export type ColumnsProps = {
+  /** Vertically align items within the container. */
+  alignY?: ResponsiveProp<AlignY>;
+  /** Elements representing each column. */
+  children: ReactNode;
+  /** At which breakpoint, if any, should the columns collapse. */
+  collapseBelow?: ResponsiveRangeProps['below'];
+  /** The size of the gap between each column. */
+  gap?: Gap;
+  /** Define the relative width of each column. By default each column is the same width. */
+  template?: number[];
+} & ValidBoxProps;
+
+export const Columns = forwardRefWithAs<'div', ColumnsProps>(
+  (
+    { alignY = 'top', collapseBelow, gap, template, ...props },
+    forwardedRef
+  ) => {
+    const { spacing, utils } = useTheme();
+    const alignItems = alignYToAlignItems(alignY);
+    const count = Children.count(props.children);
+    const gridTemplateColumns = template
+      ? template.map(c => `${c}fr`).join(' ')
+      : `repeat(${count}, 1fr)`;
+
+    const [
+      collapseOnMobile,
+      collapseOnTablet,
+      collapseOnDesktop,
+      collapseOnWide,
+    ] = utils.responsiveRange({ below: collapseBelow });
+
+    return (
+      <Box
+        ref={forwardedRef}
+        className={css(
+          utils.resolveResponsiveProps({
+            alignItems,
+            display: 'grid',
+            gap: utils.mapResponsiveScale(gap, spacing),
+            gridTemplateColumns: collapseBelow
+              ? utils.optimizeResponsiveArray([
+                  collapseOnMobile ? null : gridTemplateColumns,
+                  collapseOnTablet ? null : gridTemplateColumns,
+                  collapseOnDesktop ? null : gridTemplateColumns,
+                  collapseOnWide ? null : gridTemplateColumns,
+                ])
+              : gridTemplateColumns,
+
+            // fix flex overflow bug that prevents text truncation
+            '> *': { minWidth: 0 },
+          })
+        )}
+        {...props}
+      />
+    );
+  }
+);

package/src/alignment.ts

@@ -0,0 +1,12 @@
+import { createResponsiveMapFn } from '@spark-web/theme';
+
+const alignYLookup = {
+  top: 'start',
+  center: 'center',
+  bottom: 'end',
+  stretch: 'stretch',
+} as const;
+
+export type AlignY = keyof typeof alignYLookup;
+
+export const alignYToAlignItems = createResponsiveMapFn(alignYLookup);

package/src/index.ts

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