@atlaskit/primitives 0.2.2 → 0.3.1

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 { SerializedStyles } 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<SerializedStyles>;
+/**
+ * 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.1",
   "description": "Primitives are token-backed low-level building blocks.",
   "author": "Atlassian Pty Ltd",
   "license": "Apache-2.0",
@@ -34,10 +34,10 @@
     ".": "./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": "*",
     "@atlaskit/tokens": "^1.2.0",
     "@babel/runtime": "^7.0.0",
     "@emotion/react": "^11.7.1",

package/report.api.md

@@ -26,7 +26,6 @@ import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
 import { SerializedStyles } from '@emotion/react';
-import { UNSAFE_Breakpoint } from '@atlaskit/ds-explorations';
 
 // @public (undocumented)
 type AlignBlock = 'baseline' | 'center' | 'end' | 'start';
@@ -138,7 +137,7 @@ type BaseBoxPropsFoundation<T extends ElementType> = {
   backgroundColor?: BackgroundColor;
   shadow?: Shadow;
   borderStyle?: BorderStyle;
-  borderWidth?: BorderWidth | Partial<Record<UNSAFE_Breakpoint, BorderWidth>>;
+  borderWidth?: BorderWidth | ResponsiveObject<BorderWidth>;
   borderColor?: BorderColor;
   borderRadius?: BorderRadius;
   layer?: Layer;
@@ -149,28 +148,18 @@ type BaseBoxPropsFoundation<T extends ElementType> = {
   overflow?: Overflow;
   overflowInline?: OverflowInline;
   overflowBlock?: OverflowBlock;
-  padding?: Padding | Partial<Record<UNSAFE_Breakpoint, Padding>>;
-  paddingBlock?:
-    | PaddingBlock
-    | Partial<Record<UNSAFE_Breakpoint, PaddingBlock>>;
-  paddingBlockStart?:
-    | PaddingBlockStart
-    | Partial<Record<UNSAFE_Breakpoint, PaddingBlockStart>>;
-  paddingBlockEnd?:
-    | PaddingBlockEnd
-    | Partial<Record<UNSAFE_Breakpoint, PaddingBlockEnd>>;
-  paddingInline?:
-    | PaddingInline
-    | Partial<Record<UNSAFE_Breakpoint, PaddingInline>>;
+  padding?: Padding | ResponsiveObject<Padding>;
+  paddingBlock?: PaddingBlock | ResponsiveObject<PaddingBlock>;
+  paddingBlockStart?: PaddingBlockStart | ResponsiveObject<PaddingBlockStart>;
+  paddingBlockEnd?: PaddingBlockEnd | ResponsiveObject<PaddingBlockEnd>;
+  paddingInline?: PaddingInline | ResponsiveObject<PaddingInline>;
   paddingInlineStart?:
     | PaddingInlineStart
-    | Partial<Record<UNSAFE_Breakpoint, PaddingInlineStart>>;
-  paddingInlineEnd?:
-    | PaddingInlineEnd
-    | Partial<Record<UNSAFE_Breakpoint, PaddingInlineEnd>>;
+    | ResponsiveObject<PaddingInlineStart>;
+  paddingInlineEnd?: PaddingInlineEnd | ResponsiveObject<PaddingInlineEnd>;
   width?: Width;
   height?: Height;
-  display?: Display | Partial<Record<UNSAFE_Breakpoint, Display>>;
+  display?: Display | ResponsiveObject<Display>;
   position?: Position;
   ref?: ComponentPropsWithRef<T>['ref'];
 };
@@ -275,6 +264,9 @@ export type BoxProps<T extends ElementType = 'div'> = Omit<
 // @public (undocumented)
 type BoxResponsiveProp = typeof BOX_RESPONSIVE_PROPS[number];
 
+// @public
+type Breakpoint = 'lg' | 'md' | 'sm' | 'xl' | 'xs' | 'xxl' | 'xxs';
+
 // @public
 type CustomStyles = Pick<
   CSSProperties,
@@ -487,6 +479,9 @@ type PublicBoxPropsBase = {
   customStyles?: CustomStyles;
 };
 
+// @public
+type ResponsiveObject<T> = Partial<Record<Breakpoint, T>>;
+
 // @public (undocumented)
 type Shadow = keyof typeof shadowMap;
 

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"
+      ]
+    }
+  }
+}

package/tmp/api-report-tmp.d.ts

@@ -15,7 +15,6 @@ import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
 import { SerializedStyles } from '@emotion/react';
-import { UNSAFE_Breakpoint } from '@atlaskit/ds-explorations';
 
 // @public (undocumented)
 type AlignBlock = 'baseline' | 'center' | 'end' | 'start';
@@ -122,7 +121,7 @@ type BaseBoxPropsFoundation<T extends ElementType> = {
     backgroundColor?: BackgroundColor;
     shadow?: Shadow;
     borderStyle?: BorderStyle;
-    borderWidth?: BorderWidth | Partial<Record<UNSAFE_Breakpoint, BorderWidth>>;
+    borderWidth?: BorderWidth | ResponsiveObject<BorderWidth>;
     borderColor?: BorderColor;
     borderRadius?: BorderRadius;
     layer?: Layer;
@@ -133,16 +132,16 @@ type BaseBoxPropsFoundation<T extends ElementType> = {
     overflow?: Overflow;
     overflowInline?: OverflowInline;
     overflowBlock?: OverflowBlock;
-    padding?: Padding | Partial<Record<UNSAFE_Breakpoint, Padding>>;
-    paddingBlock?: PaddingBlock | Partial<Record<UNSAFE_Breakpoint, PaddingBlock>>;
-    paddingBlockStart?: PaddingBlockStart | Partial<Record<UNSAFE_Breakpoint, PaddingBlockStart>>;
-    paddingBlockEnd?: PaddingBlockEnd | Partial<Record<UNSAFE_Breakpoint, PaddingBlockEnd>>;
-    paddingInline?: PaddingInline | Partial<Record<UNSAFE_Breakpoint, PaddingInline>>;
-    paddingInlineStart?: PaddingInlineStart | Partial<Record<UNSAFE_Breakpoint, PaddingInlineStart>>;
-    paddingInlineEnd?: PaddingInlineEnd | Partial<Record<UNSAFE_Breakpoint, PaddingInlineEnd>>;
+    padding?: Padding | ResponsiveObject<Padding>;
+    paddingBlock?: PaddingBlock | ResponsiveObject<PaddingBlock>;
+    paddingBlockStart?: PaddingBlockStart | ResponsiveObject<PaddingBlockStart>;
+    paddingBlockEnd?: PaddingBlockEnd | ResponsiveObject<PaddingBlockEnd>;
+    paddingInline?: PaddingInline | ResponsiveObject<PaddingInline>;
+    paddingInlineStart?: PaddingInlineStart | ResponsiveObject<PaddingInlineStart>;
+    paddingInlineEnd?: PaddingInlineEnd | ResponsiveObject<PaddingInlineEnd>;
     width?: Width;
     height?: Height;
-    display?: Display | Partial<Record<UNSAFE_Breakpoint, Display>>;
+    display?: Display | ResponsiveObject<Display>;
     position?: Position;
     ref?: ComponentPropsWithRef<T>['ref'];
 };
@@ -228,6 +227,9 @@ export type BoxProps<T extends ElementType = 'div'> = Omit<BaseBoxProps<T>, 'UNS
 // @public (undocumented)
 type BoxResponsiveProp = typeof BOX_RESPONSIVE_PROPS[number];
 
+// @public
+type Breakpoint = 'lg' | 'md' | 'sm' | 'xl' | 'xs' | 'xxl' | 'xxs';
+
 // @public
 type CustomStyles = Pick<CSSProperties, 'flex' | 'flexBasis' | 'float' | 'height' | 'insetBlockStart' | 'insetInlineEnd' | 'insetInlineStart' | 'margin' | 'marginBlock' | 'marginBlockEnd' | 'marginBlockStart' | 'marginInline' | 'marginInlineEnd' | 'marginInlineStart' | 'maxHeight' | 'maxWidth' | 'minHeight' | 'minWidth' | 'paddingBottom' | 'paddingLeft' | 'paddingRight' | 'paddingTop' | 'width'>;
 
@@ -413,6 +415,9 @@ type PublicBoxPropsBase = {
     customStyles?: CustomStyles;
 };
 
+// @public
+type ResponsiveObject<T> = Partial<Record<Breakpoint, T>>;
+
 // @public (undocumented)
 type Shadow = keyof typeof shadowMap;