@spark-web/box 1.0.0

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

@@ -0,0 +1,309 @@
+import React, { createContext, useContext } from 'react';
+import { useTheme } from '@spark-web/theme';
+import _extends from '@babel/runtime/helpers/esm/extends';
+import _objectWithoutProperties from '@babel/runtime/helpers/esm/objectWithoutProperties';
+import { cx, css } from '@emotion/css';
+import { resetElementStyles } from '@spark-web/utils/internal';
+import { forwardRefWithAs } from '@spark-web/utils/ts';
+import _defineProperty from '@babel/runtime/helpers/esm/defineProperty';
+
+var __jsx$1 = React.createElement;
+// prepare context
+var backgroundContext = /*#__PURE__*/createContext('body');
+var InternalBackgroundProvider = backgroundContext.Provider;
+var useBackground = function useBackground() {
+  return useContext(backgroundContext);
+}; // conditional provider
+
+function renderBackgroundProvider(background, element) {
+  return background ? __jsx$1(InternalBackgroundProvider, {
+    value: background
+  }, element) : element;
+} // a11y contrast utility
+
+var useBackgroundLightness = function useBackgroundLightness(backgroundOverride) {
+  var backgroundFromContext = useBackground();
+  var background = backgroundOverride || backgroundFromContext;
+
+  var _useTheme = useTheme(),
+      backgroundLightness = _useTheme.backgroundLightness;
+
+  var defaultLightness = backgroundLightness.body; // used by the consumer-facing/external BackgroundProvider
+
+  if (background === 'UNKNOWN_DARK') {
+    return 'dark';
+  }
+
+  if (background === 'UNKNOWN_LIGHT') {
+    return 'light';
+  }
+
+  return background ? backgroundLightness[background] || defaultLightness : defaultLightness;
+};
+
+/** Enforce background "lightness" without applying a background color. */
+var BackgroundProvider = function BackgroundProvider(_ref) {
+  var type = _ref.type,
+      children = _ref.children;
+  return renderBackgroundProvider(type === 'dark' ? 'UNKNOWN_DARK' : 'UNKNOWN_LIGHT', children);
+};
+
+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; }
+// TODO: review responsive props! Now that we're using object syntax, un-mapped properties don't behave as expected
+// types
+
+// Hook
+// ------------------------------
+var useBoxStyles = function useBoxStyles(_ref) {
+  var alignItems = _ref.alignItems,
+      alignSelf = _ref.alignSelf,
+      background = _ref.background,
+      border = _ref.border,
+      borderRadius = _ref.borderRadius,
+      _ref$borderWidth = _ref.borderWidth,
+      borderWidth = _ref$borderWidth === void 0 ? 'standard' : _ref$borderWidth,
+      bottom = _ref.bottom,
+      cursor = _ref.cursor,
+      display = _ref.display,
+      flex = _ref.flex,
+      flexDirection = _ref.flexDirection,
+      flexGrow = _ref.flexGrow,
+      flexShrink = _ref.flexShrink,
+      flexWrap = _ref.flexWrap,
+      gap = _ref.gap,
+      height = _ref.height,
+      justifyContent = _ref.justifyContent,
+      left = _ref.left,
+      margin = _ref.margin,
+      marginBottom = _ref.marginBottom,
+      marginLeft = _ref.marginLeft,
+      marginRight = _ref.marginRight,
+      marginTop = _ref.marginTop,
+      marginX = _ref.marginX,
+      marginY = _ref.marginY,
+      minHeight = _ref.minHeight,
+      minWidth = _ref.minWidth,
+      opacity = _ref.opacity,
+      overflow = _ref.overflow,
+      padding = _ref.padding,
+      paddingBottom = _ref.paddingBottom,
+      paddingLeft = _ref.paddingLeft,
+      paddingRight = _ref.paddingRight,
+      paddingTop = _ref.paddingTop,
+      paddingX = _ref.paddingX,
+      paddingY = _ref.paddingY,
+      position = _ref.position,
+      right = _ref.right,
+      shadow = _ref.shadow,
+      top = _ref.top,
+      userSelect = _ref.userSelect,
+      width = _ref.width,
+      zIndex = _ref.zIndex;
+  var theme = useTheme();
+  var unresponsiveProps = {
+    background: background ? theme.color.background[background] : undefined,
+    boxShadow: shadow ? theme.shadow[shadow] : undefined,
+    cursor: cursor,
+    minHeight: minHeight,
+    minWidth: minWidth,
+    opacity: opacity,
+    overflow: overflow,
+    userSelect: userSelect
+  };
+  var conditionalBorderStyles = border ? {
+    borderStyle: 'solid',
+    borderColor: theme.utils.mapResponsiveScale(border, theme.border.color),
+    borderWidth: theme.utils.mapResponsiveScale(borderWidth, theme.border.width)
+  } : null;
+  return theme.utils.resolveResponsiveProps(_objectSpread(_objectSpread(_objectSpread({}, unresponsiveProps), conditionalBorderStyles), {}, {
+    // allow padding and height/width props to play nice
+    display: theme.utils.mapResponsiveProp(display),
+    // margin
+    marginBottom: theme.utils.mapResponsiveScale(marginBottom || marginY || margin, theme.spacing),
+    marginTop: theme.utils.mapResponsiveScale(marginTop || marginY || margin, theme.spacing),
+    marginLeft: theme.utils.mapResponsiveScale(marginLeft || marginX || margin, theme.spacing),
+    marginRight: theme.utils.mapResponsiveScale(marginRight || marginX || margin, theme.spacing),
+    // padding
+    paddingBottom: theme.utils.mapResponsiveScale(paddingBottom || paddingY || padding, theme.spacing),
+    paddingTop: theme.utils.mapResponsiveScale(paddingTop || paddingY || padding, theme.spacing),
+    paddingLeft: theme.utils.mapResponsiveScale(paddingLeft || paddingX || padding, theme.spacing),
+    paddingRight: theme.utils.mapResponsiveScale(paddingRight || paddingX || padding, theme.spacing),
+    // border
+    borderRadius: theme.utils.mapResponsiveScale(borderRadius, theme.border.radius),
+    // flex: parent
+    alignItems: theme.utils.mapResponsiveScale(alignItems, flexMap.alignItems),
+    gap: theme.utils.mapResponsiveScale(gap, theme.spacing),
+    flexDirection: theme.utils.mapResponsiveScale(flexDirection, flexMap.flexDirection),
+    justifyContent: theme.utils.mapResponsiveScale(justifyContent, flexMap.justifyContent),
+    flexWrap: theme.utils.mapResponsiveProp(flexWrap),
+    // flex: child
+    alignSelf: theme.utils.mapResponsiveScale(alignSelf, flexMap.alignItems),
+    flex: theme.utils.mapResponsiveProp(flex),
+    flexGrow: theme.utils.mapResponsiveProp(flexGrow),
+    flexShrink: theme.utils.mapResponsiveProp(flexShrink),
+    // dimension
+    height: theme.utils.mapResponsiveScale(height, theme.sizing),
+    width: theme.utils.mapResponsiveScale(width, theme.sizing),
+    // position
+    position: theme.utils.mapResponsiveProp(position),
+    bottom: theme.utils.mapResponsiveProp(bottom),
+    left: theme.utils.mapResponsiveProp(left),
+    right: theme.utils.mapResponsiveProp(right),
+    top: theme.utils.mapResponsiveProp(top),
+    zIndex: theme.utils.mapResponsiveScale(zIndex, theme.elevation)
+  }));
+}; // Flex shorthand / adjustments
+// ------------------------------
+
+var flexMap = {
+  alignItems: {
+    start: 'flex-start',
+    center: 'center',
+    end: 'flex-end',
+    stretch: 'stretch'
+  },
+  justifyContent: {
+    start: 'flex-start',
+    center: 'center',
+    end: 'flex-end',
+    spaceBetween: 'space-between',
+    stretch: 'stretch'
+  },
+  flexDirection: {
+    row: 'row',
+    rowReverse: 'row-reverse',
+    column: 'column',
+    columnReverse: 'column-reverse'
+  }
+};
+
+var _excluded$1 = ["alignItems", "alignSelf", "background", "border", "borderRadius", "borderWidth", "bottom", "cursor", "display", "flex", "flexDirection", "flexGrow", "flexShrink", "flexWrap", "gap", "height", "justifyContent", "left", "margin", "marginBottom", "marginLeft", "marginRight", "marginTop", "marginX", "marginY", "minHeight", "minWidth", "opacity", "overflow", "padding", "paddingBottom", "paddingLeft", "paddingRight", "paddingTop", "paddingX", "paddingY", "position", "right", "shadow", "top", "userSelect", "width", "zIndex"];
+/** Separate the style properties from the element attributes. */
+
+function useBoxProps(props) {
+  var alignItems = props.alignItems,
+      alignSelf = props.alignSelf,
+      background = props.background,
+      border = props.border,
+      borderRadius = props.borderRadius,
+      borderWidth = props.borderWidth,
+      bottom = props.bottom,
+      cursor = props.cursor,
+      display = props.display,
+      flex = props.flex,
+      flexDirection = props.flexDirection,
+      flexGrow = props.flexGrow,
+      flexShrink = props.flexShrink,
+      flexWrap = props.flexWrap,
+      gap = props.gap,
+      height = props.height,
+      justifyContent = props.justifyContent,
+      left = props.left,
+      margin = props.margin,
+      marginBottom = props.marginBottom,
+      marginLeft = props.marginLeft,
+      marginRight = props.marginRight,
+      marginTop = props.marginTop,
+      marginX = props.marginX,
+      marginY = props.marginY,
+      minHeight = props.minHeight,
+      minWidth = props.minWidth,
+      opacity = props.opacity,
+      overflow = props.overflow,
+      padding = props.padding,
+      paddingBottom = props.paddingBottom,
+      paddingLeft = props.paddingLeft,
+      paddingRight = props.paddingRight,
+      paddingTop = props.paddingTop,
+      paddingX = props.paddingX,
+      paddingY = props.paddingY,
+      position = props.position,
+      right = props.right,
+      shadow = props.shadow,
+      top = props.top,
+      userSelect = props.userSelect,
+      width = props.width,
+      zIndex = props.zIndex,
+      attributes = _objectWithoutProperties(props, _excluded$1);
+
+  var styles = useBoxStyles({
+    alignItems: alignItems,
+    alignSelf: alignSelf,
+    background: background,
+    border: border,
+    borderRadius: borderRadius,
+    borderWidth: borderWidth,
+    bottom: bottom,
+    cursor: cursor,
+    display: display,
+    flex: flex,
+    flexDirection: flexDirection,
+    flexGrow: flexGrow,
+    flexShrink: flexShrink,
+    flexWrap: flexWrap,
+    gap: gap,
+    height: height,
+    justifyContent: justifyContent,
+    left: left,
+    margin: margin,
+    marginBottom: marginBottom,
+    marginLeft: marginLeft,
+    marginRight: marginRight,
+    marginTop: marginTop,
+    marginX: marginX,
+    marginY: marginY,
+    minHeight: minHeight,
+    minWidth: minWidth,
+    opacity: opacity,
+    overflow: overflow,
+    padding: padding,
+    paddingBottom: paddingBottom,
+    paddingLeft: paddingLeft,
+    paddingRight: paddingRight,
+    paddingTop: paddingTop,
+    paddingX: paddingX,
+    paddingY: paddingY,
+    position: position,
+    right: right,
+    shadow: shadow,
+    top: top,
+    userSelect: userSelect,
+    width: width,
+    zIndex: zIndex
+  });
+  return {
+    styles: styles,
+    attributes: attributes
+  };
+}
+
+var _excluded = ["as", "asElement", "className", "id"];
+var __jsx = React.createElement;
+
+/** Exposes a prop-based API for adding styles to a view, within the constraints of the theme. */
+var Box = forwardRefWithAs(function (_ref, forwardedRef) {
+  var _ref$as = _ref.as,
+      Tag = _ref$as === void 0 ? 'div' : _ref$as,
+      asElement = _ref.asElement,
+      className = _ref.className,
+      id = _ref.id,
+      props = _objectWithoutProperties(_ref, _excluded);
+
+  var _useBoxProps = useBoxProps(props),
+      styles = _useBoxProps.styles,
+      attributes = _useBoxProps.attributes;
+
+  var resetStyles = resetElementStyles(asElement !== null && asElement !== void 0 ? asElement : Tag);
+
+  var element = __jsx(Tag, _extends({
+    ref: forwardedRef,
+    id: id,
+    className: cx(css(resetStyles), css(styles), className)
+  }, attributes));
+
+  return renderBackgroundProvider(props.background, element);
+});
+
+export { BackgroundProvider, Box, useBackground, useBackgroundLightness };

package/package.json

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

package/src/BackgroundProvider.tsx

@@ -0,0 +1,19 @@
+import type { ReactElement } from 'react';
+
+import { renderBackgroundProvider } from './context';
+
+export type BackgroundProviderProps = {
+  type: 'light' | 'dark';
+  children: ReactElement;
+};
+
+/** Enforce background "lightness" without applying a background color. */
+export const BackgroundProvider = ({
+  type,
+  children,
+}: BackgroundProviderProps) => {
+  return renderBackgroundProvider(
+    type === 'dark' ? 'UNKNOWN_DARK' : 'UNKNOWN_LIGHT',
+    children
+  );
+};

package/src/Box.stories.tsx

@@ -0,0 +1,26 @@
+import { Text } from '@spark-web/text';
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+import type { BoxProps } from './Box';
+import { Box } from './Box';
+
+export default {
+  title: 'Page & Layout / Box',
+  component: Box,
+} as ComponentMeta<typeof Box>;
+
+const BoxStory: ComponentStory<typeof Box> = (
+  args: Omit<BoxProps, 'className'>
+) => (
+  <Box {...args}>
+    <Text>I'm some text inside a Box</Text>
+  </Box>
+);
+
+export const Default = BoxStory.bind({});
+
+Default.args = {
+  padding: 'small',
+  shadow: 'medium',
+  borderRadius: 'medium',
+} as BoxProps;

package/src/Box.tsx

@@ -0,0 +1,45 @@
+import { css, cx } from '@emotion/css';
+import { resetElementStyles } from '@spark-web/utils/internal';
+import { forwardRefWithAs } from '@spark-web/utils/ts';
+import type { ReactNode } from 'react';
+
+import { renderBackgroundProvider } from './context';
+import { useBoxProps } from './useBoxProps';
+import type { BoxStyleProps } from './useBoxStyles';
+
+export type BoxProps = {
+  children?: ReactNode;
+
+  /** An identifier which must be unique in the whole document. */
+  id?: string;
+
+  // experiment
+  className?: string;
+
+  // TODO: this API is less than ideal, consider alternative
+  /**
+   * When providing a component using the "as" prop, optionally tell the system
+   * what the underlying element will be. Used internally to manage reset
+   * styles.
+   */
+  asElement?: keyof HTMLElementTagNameMap;
+} & BoxStyleProps;
+
+/** Exposes a prop-based API for adding styles to a view, within the constraints of the theme. */
+export const Box = forwardRefWithAs<'div', BoxProps>(
+  ({ as: Tag = 'div', asElement, className, id, ...props }, forwardedRef) => {
+    const { styles, attributes } = useBoxProps(props);
+    const resetStyles = resetElementStyles(asElement ?? Tag);
+
+    const element = (
+      <Tag
+        ref={forwardedRef}
+        id={id}
+        className={cx(css(resetStyles), css(styles), className)}
+        {...attributes}
+      />
+    );
+
+    return renderBackgroundProvider(props.background, element);
+  }
+);

package/src/context.tsx

@@ -0,0 +1,54 @@
+import { useTheme } from '@spark-web/theme';
+import type { ReactElement } from 'react';
+import { createContext, useContext } from 'react';
+
+import type { BoxStyleProps } from './useBoxStyles';
+
+export type BackgroundVariant =
+  | NonNullable<BoxStyleProps['background']>
+  | 'UNKNOWN_DARK'
+  | 'UNKNOWN_LIGHT';
+
+// prepare context
+
+const backgroundContext = createContext<BackgroundVariant>('body');
+export const InternalBackgroundProvider = backgroundContext.Provider;
+export const useBackground = () => useContext(backgroundContext);
+
+// conditional provider
+
+export function renderBackgroundProvider(
+  background: BackgroundVariant | undefined,
+  element: ReactElement | null
+) {
+  return background ? (
+    <InternalBackgroundProvider value={background}>
+      {element}
+    </InternalBackgroundProvider>
+  ) : (
+    element
+  );
+}
+
+// a11y contrast utility
+
+export const useBackgroundLightness = (
+  backgroundOverride?: ReturnType<typeof useBackground>
+) => {
+  const backgroundFromContext = useBackground();
+  const background = backgroundOverride || backgroundFromContext;
+  const { backgroundLightness } = useTheme();
+  const defaultLightness = backgroundLightness.body;
+
+  // used by the consumer-facing/external BackgroundProvider
+  if (background === 'UNKNOWN_DARK') {
+    return 'dark';
+  }
+  if (background === 'UNKNOWN_LIGHT') {
+    return 'light';
+  }
+
+  return background
+    ? backgroundLightness[background] || defaultLightness
+    : defaultLightness;
+};

package/src/index.ts

@@ -0,0 +1,8 @@
+export { BackgroundProvider } from './BackgroundProvider';
+export { Box } from './Box';
+export { useBackground, useBackgroundLightness } from './context';
+
+// types
+
+export type { BackgroundProviderProps } from './BackgroundProvider';
+export type { BoxProps } from './Box';

package/src/useBoxProps.ts

@@ -0,0 +1,99 @@
+import type { BoxStyleProps } from './useBoxStyles';
+import { useBoxStyles } from './useBoxStyles';
+
+/** Separate the style properties from the element attributes. */
+export function useBoxProps(props: BoxStyleProps) {
+  const {
+    alignItems,
+    alignSelf,
+    background,
+    border,
+    borderRadius,
+    borderWidth,
+    bottom,
+    cursor,
+    display,
+    flex,
+    flexDirection,
+    flexGrow,
+    flexShrink,
+    flexWrap,
+    gap,
+    height,
+    justifyContent,
+    left,
+    margin,
+    marginBottom,
+    marginLeft,
+    marginRight,
+    marginTop,
+    marginX,
+    marginY,
+    minHeight,
+    minWidth,
+    opacity,
+    overflow,
+    padding,
+    paddingBottom,
+    paddingLeft,
+    paddingRight,
+    paddingTop,
+    paddingX,
+    paddingY,
+    position,
+    right,
+    shadow,
+    top,
+    userSelect,
+    width,
+    zIndex,
+    ...attributes
+  } = props;
+  const styles = useBoxStyles({
+    alignItems,
+    alignSelf,
+    background,
+    border,
+    borderRadius,
+    borderWidth,
+    bottom,
+    cursor,
+    display,
+    flex,
+    flexDirection,
+    flexGrow,
+    flexShrink,
+    flexWrap,
+    gap,
+    height,
+    justifyContent,
+    left,
+    margin,
+    marginBottom,
+    marginLeft,
+    marginRight,
+    marginTop,
+    marginX,
+    marginY,
+    minHeight,
+    minWidth,
+    opacity,
+    overflow,
+    padding,
+    paddingBottom,
+    paddingLeft,
+    paddingRight,
+    paddingTop,
+    paddingX,
+    paddingY,
+    position,
+    right,
+    shadow,
+    top,
+    userSelect,
+    width,
+    zIndex,
+  });
+
+  return { styles, attributes };
+}