@atlaskit/primitives 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @atlaskit/primitives
 
+## 0.3.0
+
+### Minor Changes
+
+- [`7c280fead96`](https://bitbucket.org/atlassian/atlassian-frontend/commits/7c280fead96) - Add new responsive helpers, breakpoints config, and types into `@atlaskit/primitives/responsive`. Exports are treated as `UNSAFE_` and experimental until modified as they're being worked on in parallel to our Alpha Grid.
+
 ## 0.2.2
 
 ### Patch Changes

package/dist/cjs/helpers/responsive/build-media-query-css.js

@@ -0,0 +1,88 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.UNSAFE_buildBelowMediaQueryCSS = exports.UNSAFE_buildAboveMediaQueryCSS = void 0;
+var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _react = require("@emotion/react");
+var _constants = require("./constants");
+var _mediaHelper = require("./media-helper");
+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) { (0, _defineProperty2.default)(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; }
+/**
+ * Build a map of breakpoints to css with media queries and nested styles.
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ *
+ * @example
+ * A map to build optional `display:none` for consumption on a div.
+ * ```ts
+ * const hideMediaQueries = buildAboveMediaQueryCSS({ display: 'none' });
+ *
+ * const Component = ({ hideAtBreakpoints: ('xs' | 'sm')[], children: ReactNode }) => {
+ *   return <div css={hideAtBreakpoints.map(b => hideMediaQueries[b])}>{children}</div>;
+ * }
+ * ```
+ *
+ * This roughly builds a map that will look roughly like this (if done manually):
+ * ```ts
+ * {
+ *   xxs: css({ '@media (min-width: 0px)': { display: 'none' } }),
+ *   xs: css({ '@media (min-width: …px)': { display: 'none' } }),
+ *   sm: css({ '@media (min-width: …px)': { display: 'none' } }),
+ * }
+ * ```
+ */
+var UNSAFE_buildAboveMediaQueryCSS = function UNSAFE_buildAboveMediaQueryCSS(input) {
+  return _constants.UNSAFE_BREAKPOINTS_ORDERED_LIST.reduce(function (acc, breakpoint) {
+    return _objectSpread(_objectSpread({}, acc), {}, (0, _defineProperty2.default)({}, breakpoint, (0, _react.css)((0, _defineProperty2.default)({}, _mediaHelper.UNSAFE_media.above[breakpoint], typeof input === 'function' ? input(breakpoint) : input))));
+  }, {});
+};
+
+/**
+ * Build a map of breakpoints to css with media queries and nested styles.
+ *
+ * WARNING: The smallest breakpoint is not a valid key as a media query below 0px is misleading.
+ * This is separated from `buildAboveMediaQueryCSS` for that specific reason, you cannot have type safety with this variance.
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ *
+ * @example
+ * A map to build optional `display:none` for consumption on a div.
+ * ```ts
+ * const hideMediaQueries = buildBelowMediaQueryCSS({ display: 'none' });
+ *
+ * const Component = ({ hideAtBreakpoints: ('xs' | 'sm')[], children: ReactNode }) => {
+ *   return <div css={hideAtBreakpoints.map(b => hideMediaQueries[b])}>{children}</div>;
+ * }
+ * ```
+ *
+ * This roughly builds a map that will look roughly like this (if done manually):
+ * ```ts
+ * {
+ *   xs: css({ '@media (max-width: …px)': { display: 'none' } }),
+ *   sm: css({ '@media (max-width: …px)': { display: 'none' } }),
+ * }
+ * ```
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ */
+exports.UNSAFE_buildAboveMediaQueryCSS = UNSAFE_buildAboveMediaQueryCSS;
+var UNSAFE_buildBelowMediaQueryCSS = function UNSAFE_buildBelowMediaQueryCSS(input) {
+  /**
+   * WARNING: it's very important that these are in the correct order.
+   * If they are not, cascading is not in the order higher/low breakpoints do not override as expected.
+   */
+  var reversedBreakpoints = (0, _toConsumableArray2.default)(_constants.UNSAFE_BREAKPOINTS_ORDERED_LIST).reverse();
+  return reversedBreakpoints.reduce(function (acc, breakpoint) {
+    // Omit `media.below.xxs` as it's not available as that would be `<0px`…
+    if (breakpoint === _constants.SMALLEST_BREAKPOINT) {
+      return acc;
+    }
+    return _objectSpread(_objectSpread({}, acc), {}, (0, _defineProperty2.default)({}, breakpoint, (0, _react.css)((0, _defineProperty2.default)({}, _mediaHelper.UNSAFE_media.below[breakpoint], typeof input === 'function' ? input(breakpoint) : input))));
+  }, {});
+};
+exports.UNSAFE_buildBelowMediaQueryCSS = UNSAFE_buildBelowMediaQueryCSS;

package/dist/cjs/helpers/responsive/constants.js

@@ -0,0 +1,85 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.UNSAFE_BREAKPOINTS_ORDERED_LIST = exports.UNSAFE_BREAKPOINTS_CONFIG = exports.SMALLEST_BREAKPOINT = void 0;
+/**
+ * Our internal configuration for breakpoints configuration.
+ *
+ * @experimental Unsafe for consumption outside of the design system itself.
+ */
+var UNSAFE_BREAKPOINTS_CONFIG = {
+  // mobile
+  xxs: {
+    gridItemGutter: "var(--ds-space-200, 16px)",
+    gridMargin: "var(--ds-space-200, 16px)",
+    min: 0,
+    max: 479
+  },
+  // phablet
+  xs: {
+    gridItemGutter: "var(--ds-space-200, 16px)",
+    gridMargin: "var(--ds-space-200, 16px)",
+    min: 480,
+    max: 767
+  },
+  // tablet
+  sm: {
+    gridItemGutter: "var(--ds-space-200, 16px)",
+    gridMargin: "var(--ds-space-300, 24px)",
+    min: 768,
+    max: 1023
+  },
+  // laptop desktop
+  md: {
+    gridItemGutter: "var(--ds-space-300, 24px)",
+    gridMargin: "var(--ds-space-400, 32px)",
+    min: 1024,
+    max: 1439
+  },
+  // monitor
+  lg: {
+    gridItemGutter: "var(--ds-space-400, 32px)",
+    gridMargin: "var(--ds-space-400, 32px)",
+    min: 1440,
+    max: 1767
+  },
+  // large high res
+  xl: {
+    gridItemGutter: "var(--ds-space-400, 32px)",
+    gridMargin: "var(--ds-space-500, 40px)",
+    min: 1768,
+    max: 2159
+  },
+  // extra large high res
+  xxl: {
+    gridItemGutter: "var(--ds-space-500, 40px)",
+    gridMargin: "var(--ds-space-500, 40px)",
+    min: 2160,
+    max: Number.MAX_SAFE_INTEGER
+  }
+};
+
+/**
+ * The list of breakpoints in order from smallest to largest.  You may need to clone and reverse this list if you want the opposite.
+ *
+ * This is intentional for cascading with `min-width` or `media.above`. Media queries go from lowest width to highest.
+ *
+ * @experimental Unsafe for consumption outside of the design system itself.
+ */
+exports.UNSAFE_BREAKPOINTS_CONFIG = UNSAFE_BREAKPOINTS_CONFIG;
+var UNSAFE_BREAKPOINTS_ORDERED_LIST = Object.keys(UNSAFE_BREAKPOINTS_CONFIG).sort(function (a, b) {
+  return UNSAFE_BREAKPOINTS_CONFIG[a].min - UNSAFE_BREAKPOINTS_CONFIG[b].min;
+});
+
+/**
+ * This is our smallest breakpoint with a few nuances to it:
+ * 1. It is the default value for shorthands, eg. `<GridItem span={6} />` maps to `{ [SMALLEST_BREAKPOINT]: props.span }`
+ * 2. It's omitted in `media.below` as there's nothing below `0px`.
+ *
+ * @experimental There's a chance this will change in _value_, but should only be used in a way that it will not matter if this value changes.
+ */
+exports.UNSAFE_BREAKPOINTS_ORDERED_LIST = UNSAFE_BREAKPOINTS_ORDERED_LIST;
+var SMALLEST_BREAKPOINT = UNSAFE_BREAKPOINTS_ORDERED_LIST[0];
+exports.SMALLEST_BREAKPOINT = SMALLEST_BREAKPOINT;

package/dist/cjs/helpers/responsive/index.js

@@ -0,0 +1,38 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "UNSAFE_BREAKPOINTS_CONFIG", {
+  enumerable: true,
+  get: function get() {
+    return _constants.UNSAFE_BREAKPOINTS_CONFIG;
+  }
+});
+Object.defineProperty(exports, "UNSAFE_BREAKPOINTS_ORDERED_LIST", {
+  enumerable: true,
+  get: function get() {
+    return _constants.UNSAFE_BREAKPOINTS_ORDERED_LIST;
+  }
+});
+Object.defineProperty(exports, "UNSAFE_buildAboveMediaQueryCSS", {
+  enumerable: true,
+  get: function get() {
+    return _buildMediaQueryCss.UNSAFE_buildAboveMediaQueryCSS;
+  }
+});
+Object.defineProperty(exports, "UNSAFE_buildBelowMediaQueryCSS", {
+  enumerable: true,
+  get: function get() {
+    return _buildMediaQueryCss.UNSAFE_buildBelowMediaQueryCSS;
+  }
+});
+Object.defineProperty(exports, "UNSAFE_media", {
+  enumerable: true,
+  get: function get() {
+    return _mediaHelper.UNSAFE_media;
+  }
+});
+var _mediaHelper = require("./media-helper");
+var _buildMediaQueryCss = require("./build-media-query-css");
+var _constants = require("./constants");

package/dist/cjs/helpers/responsive/media-helper.js

@@ -0,0 +1,84 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.UNSAFE_media = void 0;
+var _constants = require("./constants");
+/**
+ * To ensure min-width and max-width do both target at the same time, we subtract a value.
+ * We use a fractional value here as used in other libraries and described in @link https://www.w3.org/TR/mediaqueries-4/#mq-min-max: "…possibility of fractional viewport sizes which can occur as a result of non-integer pixel densities…"
+ */
+var BELOW_PRECISION = 0.02;
+
+/**
+ * This is the full internal version.  The import has been separated to only expose as-needed.
+ */
+var internalMedia = {
+  /**
+   * A media query to target viewports above the min width of a given breakpoint.
+   * Note that `media.above.xs` is redundant and should not be used, but it's included for programatic purposes.
+   */
+  above: {
+    /**
+     * `above.xxs` is redundant and no media query should be used, but it's included for programatic purposes…
+     *
+     * Eg. this is `@media (min-width: 0px)`
+     */
+    xxs: "@media (min-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.xxs.min, "px)"),
+    xs: "@media (min-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.xs.min, "px)"),
+    sm: "@media (min-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.sm.min, "px)"),
+    md: "@media (min-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.md.min, "px)"),
+    lg: "@media (min-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.lg.min, "px)"),
+    xl: "@media (min-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.xl.min, "px)"),
+    xxl: "@media (min-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.xxl.min, "px)")
+  },
+  below: {
+    /**
+     * A media query to target viewports below the min width of a given breakpoint.
+     * Note that `media.below.xxs` is intentionally omitted as this would be `@media (max-width: 0px)`
+     */
+    xs: "@media (max-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.xs.min - BELOW_PRECISION, "px)"),
+    sm: "@media (max-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.sm.min - BELOW_PRECISION, "px)"),
+    md: "@media (max-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.md.min - BELOW_PRECISION, "px)"),
+    lg: "@media (max-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.lg.min - BELOW_PRECISION, "px)"),
+    xl: "@media (max-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.xl.min - BELOW_PRECISION, "px)"),
+    xxl: "@media (max-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.xxl.min - BELOW_PRECISION, "px)")
+  },
+  /**
+   * A media query to target viewports exactly between the min and max of a given breakpoint.
+   */
+  only: {
+    xxs: "@media (min-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.xxs.min, "px) and (max-width: ").concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.xxs.max, "px)"),
+    xs: "@media (min-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.xs.min, "px) and (max-width: ").concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.xs.max, "px)"),
+    sm: "@media (min-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.sm.min, "px) and (max-width: ").concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.sm.max, "px)"),
+    md: "@media (min-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.md.min, "px) and (max-width: ").concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.md.max, "px)"),
+    lg: "@media (min-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.lg.min, "px) and (max-width: ").concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.lg.max, "px)"),
+    xl: "@media (min-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.xl.min, "px) and (max-width: ").concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.xl.max, "px)"),
+    xxl: "@media (min-width: ".concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.xxl.min, "px) and (max-width: ").concat(_constants.UNSAFE_BREAKPOINTS_CONFIG.xxl.max, "px)")
+  }
+};
+
+/**
+ * This is an object of usable media query helpers using our internal breakpoints configuration.
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ */
+var UNSAFE_media = {
+  above: internalMedia.above,
+  below: internalMedia.below
+};
+
+/**
+ * With these types:
+ * ```
+ * type MediaQuery = `@media (${string})`;
+ * type ResponsiveMediaObject = Record<Breakpoint, MediaQuery>;
+ * ```
+ *
+ * TODO: This `media` object as of typescript@4.9, would benefit from satisfies, eg.:
+ * ```
+ * const UNSAFE_media = { … } satisfies Record<'above' | 'only', ResponsiveMediaObject> & { below: Omit<ResponsiveMediaObject, 'xxs'> }
+ * ```
+ */
+exports.UNSAFE_media = UNSAFE_media;

package/dist/cjs/helpers/responsive/types.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/dist/cjs/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/primitives",
-	"version": "0.2.2",
+	"version": "0.3.0",
 	"sideEffects": false
 }

package/dist/es2019/helpers/responsive/build-media-query-css.js

@@ -0,0 +1,85 @@
+import { css } from '@emotion/react';
+import { SMALLEST_BREAKPOINT, UNSAFE_BREAKPOINTS_ORDERED_LIST } from './constants';
+import { UNSAFE_media } from './media-helper';
+/**
+ * Build a map of breakpoints to css with media queries and nested styles.
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ *
+ * @example
+ * A map to build optional `display:none` for consumption on a div.
+ * ```ts
+ * const hideMediaQueries = buildAboveMediaQueryCSS({ display: 'none' });
+ *
+ * const Component = ({ hideAtBreakpoints: ('xs' | 'sm')[], children: ReactNode }) => {
+ *   return <div css={hideAtBreakpoints.map(b => hideMediaQueries[b])}>{children}</div>;
+ * }
+ * ```
+ *
+ * This roughly builds a map that will look roughly like this (if done manually):
+ * ```ts
+ * {
+ *   xxs: css({ '@media (min-width: 0px)': { display: 'none' } }),
+ *   xs: css({ '@media (min-width: …px)': { display: 'none' } }),
+ *   sm: css({ '@media (min-width: …px)': { display: 'none' } }),
+ * }
+ * ```
+ */
+export const UNSAFE_buildAboveMediaQueryCSS = input => {
+  return UNSAFE_BREAKPOINTS_ORDERED_LIST.reduce((acc, breakpoint) => ({
+    ...acc,
+    [breakpoint]: css({
+      // eslint-disable-next-line @repo/internal/styles/no-nested-styles
+      [UNSAFE_media.above[breakpoint]]: typeof input === 'function' ? input(breakpoint) : input
+    })
+  }), {});
+};
+
+/**
+ * Build a map of breakpoints to css with media queries and nested styles.
+ *
+ * WARNING: The smallest breakpoint is not a valid key as a media query below 0px is misleading.
+ * This is separated from `buildAboveMediaQueryCSS` for that specific reason, you cannot have type safety with this variance.
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ *
+ * @example
+ * A map to build optional `display:none` for consumption on a div.
+ * ```ts
+ * const hideMediaQueries = buildBelowMediaQueryCSS({ display: 'none' });
+ *
+ * const Component = ({ hideAtBreakpoints: ('xs' | 'sm')[], children: ReactNode }) => {
+ *   return <div css={hideAtBreakpoints.map(b => hideMediaQueries[b])}>{children}</div>;
+ * }
+ * ```
+ *
+ * This roughly builds a map that will look roughly like this (if done manually):
+ * ```ts
+ * {
+ *   xs: css({ '@media (max-width: …px)': { display: 'none' } }),
+ *   sm: css({ '@media (max-width: …px)': { display: 'none' } }),
+ * }
+ * ```
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ */
+export const UNSAFE_buildBelowMediaQueryCSS = input => {
+  /**
+   * WARNING: it's very important that these are in the correct order.
+   * If they are not, cascading is not in the order higher/low breakpoints do not override as expected.
+   */
+  const reversedBreakpoints = [...UNSAFE_BREAKPOINTS_ORDERED_LIST].reverse();
+  return reversedBreakpoints.reduce((acc, breakpoint) => {
+    // Omit `media.below.xxs` as it's not available as that would be `<0px`…
+    if (breakpoint === SMALLEST_BREAKPOINT) {
+      return acc;
+    }
+    return {
+      ...acc,
+      [breakpoint]: css({
+        // eslint-disable-next-line @repo/internal/styles/no-nested-styles
+        [UNSAFE_media.below[breakpoint]]: typeof input === 'function' ? input(breakpoint) : input
+      })
+    };
+  }, {});
+};

package/dist/es2019/helpers/responsive/constants.js

@@ -0,0 +1,74 @@
+/**
+ * Our internal configuration for breakpoints configuration.
+ *
+ * @experimental Unsafe for consumption outside of the design system itself.
+ */
+export const UNSAFE_BREAKPOINTS_CONFIG = {
+  // mobile
+  xxs: {
+    gridItemGutter: "var(--ds-space-200, 16px)",
+    gridMargin: "var(--ds-space-200, 16px)",
+    min: 0,
+    max: 479
+  },
+  // phablet
+  xs: {
+    gridItemGutter: "var(--ds-space-200, 16px)",
+    gridMargin: "var(--ds-space-200, 16px)",
+    min: 480,
+    max: 767
+  },
+  // tablet
+  sm: {
+    gridItemGutter: "var(--ds-space-200, 16px)",
+    gridMargin: "var(--ds-space-300, 24px)",
+    min: 768,
+    max: 1023
+  },
+  // laptop desktop
+  md: {
+    gridItemGutter: "var(--ds-space-300, 24px)",
+    gridMargin: "var(--ds-space-400, 32px)",
+    min: 1024,
+    max: 1439
+  },
+  // monitor
+  lg: {
+    gridItemGutter: "var(--ds-space-400, 32px)",
+    gridMargin: "var(--ds-space-400, 32px)",
+    min: 1440,
+    max: 1767
+  },
+  // large high res
+  xl: {
+    gridItemGutter: "var(--ds-space-400, 32px)",
+    gridMargin: "var(--ds-space-500, 40px)",
+    min: 1768,
+    max: 2159
+  },
+  // extra large high res
+  xxl: {
+    gridItemGutter: "var(--ds-space-500, 40px)",
+    gridMargin: "var(--ds-space-500, 40px)",
+    min: 2160,
+    max: Number.MAX_SAFE_INTEGER
+  }
+};
+
+/**
+ * The list of breakpoints in order from smallest to largest.  You may need to clone and reverse this list if you want the opposite.
+ *
+ * This is intentional for cascading with `min-width` or `media.above`. Media queries go from lowest width to highest.
+ *
+ * @experimental Unsafe for consumption outside of the design system itself.
+ */
+export const UNSAFE_BREAKPOINTS_ORDERED_LIST = Object.keys(UNSAFE_BREAKPOINTS_CONFIG).sort((a, b) => UNSAFE_BREAKPOINTS_CONFIG[a].min - UNSAFE_BREAKPOINTS_CONFIG[b].min);
+
+/**
+ * This is our smallest breakpoint with a few nuances to it:
+ * 1. It is the default value for shorthands, eg. `<GridItem span={6} />` maps to `{ [SMALLEST_BREAKPOINT]: props.span }`
+ * 2. It's omitted in `media.below` as there's nothing below `0px`.
+ *
+ * @experimental There's a chance this will change in _value_, but should only be used in a way that it will not matter if this value changes.
+ */
+export const SMALLEST_BREAKPOINT = UNSAFE_BREAKPOINTS_ORDERED_LIST[0];

package/dist/es2019/helpers/responsive/index.js

@@ -0,0 +1,3 @@
+export { UNSAFE_media } from './media-helper';
+export { UNSAFE_buildAboveMediaQueryCSS, UNSAFE_buildBelowMediaQueryCSS } from './build-media-query-css';
+export { UNSAFE_BREAKPOINTS_ORDERED_LIST, UNSAFE_BREAKPOINTS_CONFIG } from './constants';

package/dist/es2019/helpers/responsive/media-helper.js

@@ -0,0 +1,78 @@
+import { UNSAFE_BREAKPOINTS_CONFIG } from './constants';
+
+/**
+ * To ensure min-width and max-width do both target at the same time, we subtract a value.
+ * We use a fractional value here as used in other libraries and described in @link https://www.w3.org/TR/mediaqueries-4/#mq-min-max: "…possibility of fractional viewport sizes which can occur as a result of non-integer pixel densities…"
+ */
+const BELOW_PRECISION = 0.02;
+
+/**
+ * This is the full internal version.  The import has been separated to only expose as-needed.
+ */
+const internalMedia = {
+  /**
+   * A media query to target viewports above the min width of a given breakpoint.
+   * Note that `media.above.xs` is redundant and should not be used, but it's included for programatic purposes.
+   */
+  above: {
+    /**
+     * `above.xxs` is redundant and no media query should be used, but it's included for programatic purposes…
+     *
+     * Eg. this is `@media (min-width: 0px)`
+     */
+    xxs: `@media (min-width: ${UNSAFE_BREAKPOINTS_CONFIG.xxs.min}px)`,
+    xs: `@media (min-width: ${UNSAFE_BREAKPOINTS_CONFIG.xs.min}px)`,
+    sm: `@media (min-width: ${UNSAFE_BREAKPOINTS_CONFIG.sm.min}px)`,
+    md: `@media (min-width: ${UNSAFE_BREAKPOINTS_CONFIG.md.min}px)`,
+    lg: `@media (min-width: ${UNSAFE_BREAKPOINTS_CONFIG.lg.min}px)`,
+    xl: `@media (min-width: ${UNSAFE_BREAKPOINTS_CONFIG.xl.min}px)`,
+    xxl: `@media (min-width: ${UNSAFE_BREAKPOINTS_CONFIG.xxl.min}px)`
+  },
+  below: {
+    /**
+     * A media query to target viewports below the min width of a given breakpoint.
+     * Note that `media.below.xxs` is intentionally omitted as this would be `@media (max-width: 0px)`
+     */
+    xs: `@media (max-width: ${UNSAFE_BREAKPOINTS_CONFIG.xs.min - BELOW_PRECISION}px)`,
+    sm: `@media (max-width: ${UNSAFE_BREAKPOINTS_CONFIG.sm.min - BELOW_PRECISION}px)`,
+    md: `@media (max-width: ${UNSAFE_BREAKPOINTS_CONFIG.md.min - BELOW_PRECISION}px)`,
+    lg: `@media (max-width: ${UNSAFE_BREAKPOINTS_CONFIG.lg.min - BELOW_PRECISION}px)`,
+    xl: `@media (max-width: ${UNSAFE_BREAKPOINTS_CONFIG.xl.min - BELOW_PRECISION}px)`,
+    xxl: `@media (max-width: ${UNSAFE_BREAKPOINTS_CONFIG.xxl.min - BELOW_PRECISION}px)`
+  },
+  /**
+   * A media query to target viewports exactly between the min and max of a given breakpoint.
+   */
+  only: {
+    xxs: `@media (min-width: ${UNSAFE_BREAKPOINTS_CONFIG.xxs.min}px) and (max-width: ${UNSAFE_BREAKPOINTS_CONFIG.xxs.max}px)`,
+    xs: `@media (min-width: ${UNSAFE_BREAKPOINTS_CONFIG.xs.min}px) and (max-width: ${UNSAFE_BREAKPOINTS_CONFIG.xs.max}px)`,
+    sm: `@media (min-width: ${UNSAFE_BREAKPOINTS_CONFIG.sm.min}px) and (max-width: ${UNSAFE_BREAKPOINTS_CONFIG.sm.max}px)`,
+    md: `@media (min-width: ${UNSAFE_BREAKPOINTS_CONFIG.md.min}px) and (max-width: ${UNSAFE_BREAKPOINTS_CONFIG.md.max}px)`,
+    lg: `@media (min-width: ${UNSAFE_BREAKPOINTS_CONFIG.lg.min}px) and (max-width: ${UNSAFE_BREAKPOINTS_CONFIG.lg.max}px)`,
+    xl: `@media (min-width: ${UNSAFE_BREAKPOINTS_CONFIG.xl.min}px) and (max-width: ${UNSAFE_BREAKPOINTS_CONFIG.xl.max}px)`,
+    xxl: `@media (min-width: ${UNSAFE_BREAKPOINTS_CONFIG.xxl.min}px) and (max-width: ${UNSAFE_BREAKPOINTS_CONFIG.xxl.max}px)`
+  }
+};
+
+/**
+ * This is an object of usable media query helpers using our internal breakpoints configuration.
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ */
+export const UNSAFE_media = {
+  above: internalMedia.above,
+  below: internalMedia.below
+};
+
+/**
+ * With these types:
+ * ```
+ * type MediaQuery = `@media (${string})`;
+ * type ResponsiveMediaObject = Record<Breakpoint, MediaQuery>;
+ * ```
+ *
+ * TODO: This `media` object as of typescript@4.9, would benefit from satisfies, eg.:
+ * ```
+ * const UNSAFE_media = { … } satisfies Record<'above' | 'only', ResponsiveMediaObject> & { below: Omit<ResponsiveMediaObject, 'xxs'> }
+ * ```
+ */

package/dist/es2019/helpers/responsive/types.js

@@ -0,0 +1 @@
+export {};

package/dist/es2019/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/primitives",
-	"version": "0.2.2",
+	"version": "0.3.0",
 	"sideEffects": false
 }

package/dist/esm/helpers/responsive/build-media-query-css.js

@@ -0,0 +1,79 @@
+import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+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; }
+import { css } from '@emotion/react';
+import { SMALLEST_BREAKPOINT, UNSAFE_BREAKPOINTS_ORDERED_LIST } from './constants';
+import { UNSAFE_media } from './media-helper';
+/**
+ * Build a map of breakpoints to css with media queries and nested styles.
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ *
+ * @example
+ * A map to build optional `display:none` for consumption on a div.
+ * ```ts
+ * const hideMediaQueries = buildAboveMediaQueryCSS({ display: 'none' });
+ *
+ * const Component = ({ hideAtBreakpoints: ('xs' | 'sm')[], children: ReactNode }) => {
+ *   return <div css={hideAtBreakpoints.map(b => hideMediaQueries[b])}>{children}</div>;
+ * }
+ * ```
+ *
+ * This roughly builds a map that will look roughly like this (if done manually):
+ * ```ts
+ * {
+ *   xxs: css({ '@media (min-width: 0px)': { display: 'none' } }),
+ *   xs: css({ '@media (min-width: …px)': { display: 'none' } }),
+ *   sm: css({ '@media (min-width: …px)': { display: 'none' } }),
+ * }
+ * ```
+ */
+export var UNSAFE_buildAboveMediaQueryCSS = function UNSAFE_buildAboveMediaQueryCSS(input) {
+  return UNSAFE_BREAKPOINTS_ORDERED_LIST.reduce(function (acc, breakpoint) {
+    return _objectSpread(_objectSpread({}, acc), {}, _defineProperty({}, breakpoint, css(_defineProperty({}, UNSAFE_media.above[breakpoint], typeof input === 'function' ? input(breakpoint) : input))));
+  }, {});
+};
+
+/**
+ * Build a map of breakpoints to css with media queries and nested styles.
+ *
+ * WARNING: The smallest breakpoint is not a valid key as a media query below 0px is misleading.
+ * This is separated from `buildAboveMediaQueryCSS` for that specific reason, you cannot have type safety with this variance.
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ *
+ * @example
+ * A map to build optional `display:none` for consumption on a div.
+ * ```ts
+ * const hideMediaQueries = buildBelowMediaQueryCSS({ display: 'none' });
+ *
+ * const Component = ({ hideAtBreakpoints: ('xs' | 'sm')[], children: ReactNode }) => {
+ *   return <div css={hideAtBreakpoints.map(b => hideMediaQueries[b])}>{children}</div>;
+ * }
+ * ```
+ *
+ * This roughly builds a map that will look roughly like this (if done manually):
+ * ```ts
+ * {
+ *   xs: css({ '@media (max-width: …px)': { display: 'none' } }),
+ *   sm: css({ '@media (max-width: …px)': { display: 'none' } }),
+ * }
+ * ```
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ */
+export var UNSAFE_buildBelowMediaQueryCSS = function UNSAFE_buildBelowMediaQueryCSS(input) {
+  /**
+   * WARNING: it's very important that these are in the correct order.
+   * If they are not, cascading is not in the order higher/low breakpoints do not override as expected.
+   */
+  var reversedBreakpoints = _toConsumableArray(UNSAFE_BREAKPOINTS_ORDERED_LIST).reverse();
+  return reversedBreakpoints.reduce(function (acc, breakpoint) {
+    // Omit `media.below.xxs` as it's not available as that would be `<0px`…
+    if (breakpoint === SMALLEST_BREAKPOINT) {
+      return acc;
+    }
+    return _objectSpread(_objectSpread({}, acc), {}, _defineProperty({}, breakpoint, css(_defineProperty({}, UNSAFE_media.below[breakpoint], typeof input === 'function' ? input(breakpoint) : input))));
+  }, {});
+};

package/dist/esm/helpers/responsive/constants.js

@@ -0,0 +1,76 @@
+/**
+ * Our internal configuration for breakpoints configuration.
+ *
+ * @experimental Unsafe for consumption outside of the design system itself.
+ */
+export var UNSAFE_BREAKPOINTS_CONFIG = {
+  // mobile
+  xxs: {
+    gridItemGutter: "var(--ds-space-200, 16px)",
+    gridMargin: "var(--ds-space-200, 16px)",
+    min: 0,
+    max: 479
+  },
+  // phablet
+  xs: {
+    gridItemGutter: "var(--ds-space-200, 16px)",
+    gridMargin: "var(--ds-space-200, 16px)",
+    min: 480,
+    max: 767
+  },
+  // tablet
+  sm: {
+    gridItemGutter: "var(--ds-space-200, 16px)",
+    gridMargin: "var(--ds-space-300, 24px)",
+    min: 768,
+    max: 1023
+  },
+  // laptop desktop
+  md: {
+    gridItemGutter: "var(--ds-space-300, 24px)",
+    gridMargin: "var(--ds-space-400, 32px)",
+    min: 1024,
+    max: 1439
+  },
+  // monitor
+  lg: {
+    gridItemGutter: "var(--ds-space-400, 32px)",
+    gridMargin: "var(--ds-space-400, 32px)",
+    min: 1440,
+    max: 1767
+  },
+  // large high res
+  xl: {
+    gridItemGutter: "var(--ds-space-400, 32px)",
+    gridMargin: "var(--ds-space-500, 40px)",
+    min: 1768,
+    max: 2159
+  },
+  // extra large high res
+  xxl: {
+    gridItemGutter: "var(--ds-space-500, 40px)",
+    gridMargin: "var(--ds-space-500, 40px)",
+    min: 2160,
+    max: Number.MAX_SAFE_INTEGER
+  }
+};
+
+/**
+ * The list of breakpoints in order from smallest to largest.  You may need to clone and reverse this list if you want the opposite.
+ *
+ * This is intentional for cascading with `min-width` or `media.above`. Media queries go from lowest width to highest.
+ *
+ * @experimental Unsafe for consumption outside of the design system itself.
+ */
+export var UNSAFE_BREAKPOINTS_ORDERED_LIST = Object.keys(UNSAFE_BREAKPOINTS_CONFIG).sort(function (a, b) {
+  return UNSAFE_BREAKPOINTS_CONFIG[a].min - UNSAFE_BREAKPOINTS_CONFIG[b].min;
+});
+
+/**
+ * This is our smallest breakpoint with a few nuances to it:
+ * 1. It is the default value for shorthands, eg. `<GridItem span={6} />` maps to `{ [SMALLEST_BREAKPOINT]: props.span }`
+ * 2. It's omitted in `media.below` as there's nothing below `0px`.
+ *
+ * @experimental There's a chance this will change in _value_, but should only be used in a way that it will not matter if this value changes.
+ */
+export var SMALLEST_BREAKPOINT = UNSAFE_BREAKPOINTS_ORDERED_LIST[0];

package/dist/esm/helpers/responsive/index.js

@@ -0,0 +1,3 @@
+export { UNSAFE_media } from './media-helper';
+export { UNSAFE_buildAboveMediaQueryCSS, UNSAFE_buildBelowMediaQueryCSS } from './build-media-query-css';
+export { UNSAFE_BREAKPOINTS_ORDERED_LIST, UNSAFE_BREAKPOINTS_CONFIG } from './constants';

package/dist/esm/helpers/responsive/media-helper.js

@@ -0,0 +1,78 @@
+import { UNSAFE_BREAKPOINTS_CONFIG } from './constants';
+
+/**
+ * To ensure min-width and max-width do both target at the same time, we subtract a value.
+ * We use a fractional value here as used in other libraries and described in @link https://www.w3.org/TR/mediaqueries-4/#mq-min-max: "…possibility of fractional viewport sizes which can occur as a result of non-integer pixel densities…"
+ */
+var BELOW_PRECISION = 0.02;
+
+/**
+ * This is the full internal version.  The import has been separated to only expose as-needed.
+ */
+var internalMedia = {
+  /**
+   * A media query to target viewports above the min width of a given breakpoint.
+   * Note that `media.above.xs` is redundant and should not be used, but it's included for programatic purposes.
+   */
+  above: {
+    /**
+     * `above.xxs` is redundant and no media query should be used, but it's included for programatic purposes…
+     *
+     * Eg. this is `@media (min-width: 0px)`
+     */
+    xxs: "@media (min-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.xxs.min, "px)"),
+    xs: "@media (min-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.xs.min, "px)"),
+    sm: "@media (min-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.sm.min, "px)"),
+    md: "@media (min-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.md.min, "px)"),
+    lg: "@media (min-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.lg.min, "px)"),
+    xl: "@media (min-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.xl.min, "px)"),
+    xxl: "@media (min-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.xxl.min, "px)")
+  },
+  below: {
+    /**
+     * A media query to target viewports below the min width of a given breakpoint.
+     * Note that `media.below.xxs` is intentionally omitted as this would be `@media (max-width: 0px)`
+     */
+    xs: "@media (max-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.xs.min - BELOW_PRECISION, "px)"),
+    sm: "@media (max-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.sm.min - BELOW_PRECISION, "px)"),
+    md: "@media (max-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.md.min - BELOW_PRECISION, "px)"),
+    lg: "@media (max-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.lg.min - BELOW_PRECISION, "px)"),
+    xl: "@media (max-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.xl.min - BELOW_PRECISION, "px)"),
+    xxl: "@media (max-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.xxl.min - BELOW_PRECISION, "px)")
+  },
+  /**
+   * A media query to target viewports exactly between the min and max of a given breakpoint.
+   */
+  only: {
+    xxs: "@media (min-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.xxs.min, "px) and (max-width: ").concat(UNSAFE_BREAKPOINTS_CONFIG.xxs.max, "px)"),
+    xs: "@media (min-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.xs.min, "px) and (max-width: ").concat(UNSAFE_BREAKPOINTS_CONFIG.xs.max, "px)"),
+    sm: "@media (min-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.sm.min, "px) and (max-width: ").concat(UNSAFE_BREAKPOINTS_CONFIG.sm.max, "px)"),
+    md: "@media (min-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.md.min, "px) and (max-width: ").concat(UNSAFE_BREAKPOINTS_CONFIG.md.max, "px)"),
+    lg: "@media (min-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.lg.min, "px) and (max-width: ").concat(UNSAFE_BREAKPOINTS_CONFIG.lg.max, "px)"),
+    xl: "@media (min-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.xl.min, "px) and (max-width: ").concat(UNSAFE_BREAKPOINTS_CONFIG.xl.max, "px)"),
+    xxl: "@media (min-width: ".concat(UNSAFE_BREAKPOINTS_CONFIG.xxl.min, "px) and (max-width: ").concat(UNSAFE_BREAKPOINTS_CONFIG.xxl.max, "px)")
+  }
+};
+
+/**
+ * This is an object of usable media query helpers using our internal breakpoints configuration.
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ */
+export var UNSAFE_media = {
+  above: internalMedia.above,
+  below: internalMedia.below
+};
+
+/**
+ * With these types:
+ * ```
+ * type MediaQuery = `@media (${string})`;
+ * type ResponsiveMediaObject = Record<Breakpoint, MediaQuery>;
+ * ```
+ *
+ * TODO: This `media` object as of typescript@4.9, would benefit from satisfies, eg.:
+ * ```
+ * const UNSAFE_media = { … } satisfies Record<'above' | 'only', ResponsiveMediaObject> & { below: Omit<ResponsiveMediaObject, 'xxs'> }
+ * ```
+ */

package/dist/esm/helpers/responsive/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/primitives",
-	"version": "0.2.2",
+	"version": "0.3.0",
 	"sideEffects": false
 }

package/dist/types/helpers/responsive/build-media-query-css.d.ts

@@ -0,0 +1,57 @@
+import { CSSObject } from '@emotion/react';
+import { SMALLEST_BREAKPOINT } from './constants';
+import type { Breakpoint } from './types';
+/**
+ * Build a map of breakpoints to css with media queries and nested styles.
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ *
+ * @example
+ * A map to build optional `display:none` for consumption on a div.
+ * ```ts
+ * const hideMediaQueries = buildAboveMediaQueryCSS({ display: 'none' });
+ *
+ * const Component = ({ hideAtBreakpoints: ('xs' | 'sm')[], children: ReactNode }) => {
+ *   return <div css={hideAtBreakpoints.map(b => hideMediaQueries[b])}>{children}</div>;
+ * }
+ * ```
+ *
+ * This roughly builds a map that will look roughly like this (if done manually):
+ * ```ts
+ * {
+ *   xxs: css({ '@media (min-width: 0px)': { display: 'none' } }),
+ *   xs: css({ '@media (min-width: …px)': { display: 'none' } }),
+ *   sm: css({ '@media (min-width: …px)': { display: 'none' } }),
+ * }
+ * ```
+ */
+export declare const UNSAFE_buildAboveMediaQueryCSS: (input: CSSObject | ((breakpoint: Breakpoint) => CSSObject)) => Required<Partial<Record<Breakpoint, import("@emotion/react").SerializedStyles>>>;
+/**
+ * Build a map of breakpoints to css with media queries and nested styles.
+ *
+ * WARNING: The smallest breakpoint is not a valid key as a media query below 0px is misleading.
+ * This is separated from `buildAboveMediaQueryCSS` for that specific reason, you cannot have type safety with this variance.
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ *
+ * @example
+ * A map to build optional `display:none` for consumption on a div.
+ * ```ts
+ * const hideMediaQueries = buildBelowMediaQueryCSS({ display: 'none' });
+ *
+ * const Component = ({ hideAtBreakpoints: ('xs' | 'sm')[], children: ReactNode }) => {
+ *   return <div css={hideAtBreakpoints.map(b => hideMediaQueries[b])}>{children}</div>;
+ * }
+ * ```
+ *
+ * This roughly builds a map that will look roughly like this (if done manually):
+ * ```ts
+ * {
+ *   xs: css({ '@media (max-width: …px)': { display: 'none' } }),
+ *   sm: css({ '@media (max-width: …px)': { display: 'none' } }),
+ * }
+ * ```
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ */
+export declare const UNSAFE_buildBelowMediaQueryCSS: (input: CSSObject | ((breakpoint: Exclude<Breakpoint, typeof SMALLEST_BREAKPOINT>) => CSSObject)) => Required<Omit<Partial<Record<Breakpoint, import("@emotion/react").SerializedStyles>>, "xxs">>;

package/dist/types/helpers/responsive/constants.d.ts

@@ -0,0 +1,23 @@
+import type { Breakpoint, BreakpointConfig } from './types';
+/**
+ * Our internal configuration for breakpoints configuration.
+ *
+ * @experimental Unsafe for consumption outside of the design system itself.
+ */
+export declare const UNSAFE_BREAKPOINTS_CONFIG: Record<Breakpoint, BreakpointConfig>;
+/**
+ * The list of breakpoints in order from smallest to largest.  You may need to clone and reverse this list if you want the opposite.
+ *
+ * This is intentional for cascading with `min-width` or `media.above`. Media queries go from lowest width to highest.
+ *
+ * @experimental Unsafe for consumption outside of the design system itself.
+ */
+export declare const UNSAFE_BREAKPOINTS_ORDERED_LIST: ["xxs", "xs", "sm", "md", "lg", "xl", "xxl"];
+/**
+ * This is our smallest breakpoint with a few nuances to it:
+ * 1. It is the default value for shorthands, eg. `<GridItem span={6} />` maps to `{ [SMALLEST_BREAKPOINT]: props.span }`
+ * 2. It's omitted in `media.below` as there's nothing below `0px`.
+ *
+ * @experimental There's a chance this will change in _value_, but should only be used in a way that it will not matter if this value changes.
+ */
+export declare const SMALLEST_BREAKPOINT: "xxs";

package/dist/types/helpers/responsive/index.d.ts

@@ -0,0 +1,4 @@
+export { UNSAFE_media } from './media-helper';
+export { UNSAFE_buildAboveMediaQueryCSS, UNSAFE_buildBelowMediaQueryCSS, } from './build-media-query-css';
+export { UNSAFE_BREAKPOINTS_ORDERED_LIST, UNSAFE_BREAKPOINTS_CONFIG, } from './constants';
+export type { Breakpoint, ResponsiveObject, ResponsiveCSSObject, } from './types';

package/dist/types/helpers/responsive/media-helper.d.ts

@@ -0,0 +1,45 @@
+/**
+ * This is an object of usable media query helpers using our internal breakpoints configuration.
+ *
+ * @experimental Unsafe for usage as the API is not finalized.
+ */
+export declare const UNSAFE_media: {
+    readonly above: {
+        /**
+         * `above.xxs` is redundant and no media query should be used, but it's included for programatic purposes…
+         *
+         * Eg. this is `@media (min-width: 0px)`
+         */
+        readonly xxs: `@media (min-width: ${number}px)`;
+        readonly xs: `@media (min-width: ${number}px)`;
+        readonly sm: `@media (min-width: ${number}px)`;
+        readonly md: `@media (min-width: ${number}px)`;
+        readonly lg: `@media (min-width: ${number}px)`;
+        readonly xl: `@media (min-width: ${number}px)`;
+        readonly xxl: `@media (min-width: ${number}px)`;
+    };
+    readonly below: {
+        /**
+         * A media query to target viewports below the min width of a given breakpoint.
+         * Note that `media.below.xxs` is intentionally omitted as this would be `@media (max-width: 0px)`
+         */
+        readonly xs: `@media (max-width: ${number}px)`;
+        readonly sm: `@media (max-width: ${number}px)`;
+        readonly md: `@media (max-width: ${number}px)`;
+        readonly lg: `@media (max-width: ${number}px)`;
+        readonly xl: `@media (max-width: ${number}px)`;
+        readonly xxl: `@media (max-width: ${number}px)`;
+    };
+};
+/**
+ * With these types:
+ * ```
+ * type MediaQuery = `@media (${string})`;
+ * type ResponsiveMediaObject = Record<Breakpoint, MediaQuery>;
+ * ```
+ *
+ * TODO: This `media` object as of typescript@4.9, would benefit from satisfies, eg.:
+ * ```
+ * const UNSAFE_media = { … } satisfies Record<'above' | 'only', ResponsiveMediaObject> & { below: Omit<ResponsiveMediaObject, 'xxs'> }
+ * ```
+ */

package/dist/types/helpers/responsive/types.d.ts

@@ -0,0 +1,47 @@
+import { css } from '@emotion/react';
+import { token } from '@atlaskit/tokens';
+/**
+ * The breakpoints we have for responsiveness.
+ */
+export declare type Breakpoint = 'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+/**
+ * An object type mapping a value to each breakpoint (optionally)
+ */
+export declare type ResponsiveObject<T> = Partial<Record<Breakpoint, T>>;
+/**
+ * A map of breakpoints to CSS, commonly used to build maps given a responsive object
+ * so we can statically compile CSS upfront, but dynamically apply it.
+ *
+ * @example Here we could conditionally load margins based a `setMarginBreakpoints={['xs', 'md']}` type prop.
+ * ```tsx
+ * const marginMediaQueries = {
+ *   xxs: css({ [media.above.xxs]: margin: 0 } }),
+ *   xs: css({ [media.above.xs]: margin: 4 } }),
+ *   //…
+ * }
+ *
+ * return <div css={setMarginBreakpoints.map(breakpoint => marginMediaQueries[breakpoint])} />
+ * ```
+ */
+export declare type ResponsiveCSSObject = ResponsiveObject<ReturnType<typeof css>>;
+/**
+ * Our internal breakpoint config used to build media queries and define attributes for certain components.
+ */
+export declare type BreakpointConfig = {
+    /**
+     * The gap between a `GridItem`.
+     */
+    gridItemGutter: ReturnType<typeof token>;
+    /**
+     * The outer whitespace of a `Grid` item.
+     */
+    gridMargin: ReturnType<typeof token>;
+    /**
+     * The min-width used in media queries
+     */
+    min: number;
+    /**
+     * The max-width used in media queries
+     */
+    max: number;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlaskit/primitives",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Primitives are token-backed low-level building blocks.",
   "author": "Atlassian Pty Ltd",
   "license": "Apache-2.0",
@@ -34,7 +34,8 @@
     ".": "./src/index.tsx",
     "./box": "./src/components/box.tsx",
     "./stack": "./src/components/stack.partial.tsx",
-    "./inline": "./src/components/inline.partial.tsx"
+    "./inline": "./src/components/inline.partial.tsx",
+    "./responsive": "./src/helpers/responsive/index.tsx"
   },
   "dependencies": {
     "@atlaskit/ds-explorations": "*",

package/responsive/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@atlaskit/primitives/responsive",
+  "main": "../dist/cjs/helpers/responsive/index.js",
+  "module": "../dist/esm/helpers/responsive/index.js",
+  "module:es2019": "../dist/es2019/helpers/responsive/index.js",
+  "sideEffects": false,
+  "types": "../dist/types/helpers/responsive/index.d.ts",
+  "typesVersions": {
+    ">=4.0 <4.5": {
+      "*": [
+        "../dist/types-ts4.0/helpers/responsive/index.d.ts"
+      ]
+    }
+  }
+}