{"_id":"@deloitte-digital-au/dd-breakpoint-container","_rev":"4-2de5e3324017289c87b6ed1bb7642bd0","name":"@deloitte-digital-au/dd-breakpoint-container","dist-tags":{"latest":"0.8.6"},"versions":{"0.8.6":{"name":"@deloitte-digital-au/dd-breakpoint-container","version":"0.8.6","description":"Flexible container queries for responsive design in React and SCSS.","author":{"name":"Deloitte Digital Australia","url":"http://deloittedigital.com.au"},"license":"BSD-3-Clause","repository":{"type":"git","url":"git+https://github.com/DeloitteDigitalAPAC/dd-breakpoint-container.git"},"homepage":"https://github.com/DeloitteDigitalAPAC/dd-breakpoint-container/blob/master/README.md","main":"./lib/index.js","module":"./dist/dd.BreakpointContainer.esm.js","types":"./lib/index.d.ts","dependencies":{"classnames":"^2.2.5","core-js":"^3.4.1","react-resize-detector":"^3.4.0"},"peerDependencies":{"react":"^16.2.0"},"devDependencies":{"@babel/cli":"^7.6.4","@babel/core":"^7.6.4","@babel/preset-env":"^7.6.3","@babel/preset-typescript":"^7.6.0","@deloitte-digital-au/babel-preset-app-react":"^3.0.0","@deloitte-digital-au/eslint-config-react":"^3.4.0","@deloitte-digital-au/stylelint-config":"^2.0.1","@types/classnames":"^2.2.9","@types/react-resize-detector":"^4.0.2","@typescript-eslint/eslint-plugin":"^2.5.0","@typescript-eslint/parser":"^2.5.0","autoprefixer":"^9.6.5","babel-eslint":"^8.2.3","babel-plugin-module-resolver":"^3.2.0","cross-env":"^5.2.1","cssnano":"^4.1.10","eslint":"^5.16.0","eslint-config-prettier":"^4.3.0","eslint-import-resolver-babel-module":"^5.1.0","eslint-plugin-module-resolver":"^0.15.0","eslint-plugin-prettier":"^3.1.1","husky":"^2.7.0","lint-staged":"^8.2.1","node-sass":"^4.12.0","npm-run-all":"^4.1.5","npm-watch":"^0.6.0","postcss-preset-env":"^6.7.0","prettier":"^1.18.2","rollup":"^1.25.2","rollup-plugin-babel":"^4.3.3","rollup-plugin-babel-minify":"^7.0.0","rollup-plugin-commonjs":"^9.3.4","rollup-plugin-delete":"^0.2.2","rollup-plugin-node-resolve":"^4.2.4","rollup-plugin-postcss":"^2.0.3","rollup-plugin-progress":"^1.1.1","rollup-plugin-size-snapshot":"^0.8.0","rollup-plugin-typescript2":"^0.24.3","rollup-plugin-visualizer":"^0.9.2","stylelint-config-prettier":"^5.3.0","stylelint-prettier":"^1.1.1","tslib":"^1.10.0","typescript":"^3.6.4"},"scripts":{"doctoc":"doctoc README.md --title '## Index' --maxlevel 4 --bitbucket","start":"npm-watch","build":"run-s --silent check-types build:*","build:pre":"node ./scripts/text/dd-logo.js","build:clean":"rm -rf lib dist/cjs","build:dev":"cross-env NODE_ENV=development && rollup --config ./rollup.dev.js","build:prod":"cross-env NODE_ENV=production && rollup --config ./rollup.prod.js","build:lib":"babel ./src --out-dir lib --extensions \".js,.jsx,.ts,.tsx\" --source-maps inline --copy-files && rm -rf ./lib/scss","build:sass":"node-sass ./src/scss --output ./src/css","build:types":"tsc --project ./tsconfig.types.json","build:post":"node ./scripts/buildMixins.js && node ./scripts/text/build-complete.js","prettify":"prettier ./src/**/*.{js,jsx,ts,tsx}","check-types":"tsc","lint":"run-s --silent lint:* && node scripts/text/no-issues.js","lint:js":"eslint --fix --ext .js,.jsx,.ts,.tsx ./src","lint:css":"stylelint --fix ./src/**/*.{scss,css,js,js,ts,tsx}","test":"run-s --silent test:* && node scripts/text/no-issues.js","test:unit":"node scripts/text/no-issues.js","test:coverage":"npm run test:unit -- --coverage","prepublishOnly":"run-s --silent lint check-types test build"},"husky":{"hooks":{"pre-commit":"lint-staged","pre-push":"npm run test:unit && npm run check-types"}},"lint-staged":{"src/**/*.{js,jsx,ts,tsx}":["eslint --fix","stylelint --fix","prettier --write","git add"],"src/**/*.{scss,css}":["stylelint --fix","git add"]},"watch":{"build:sass":{"patterns":["src/scss"],"extensions":"scss","runOnChangeOnly":true},"build:lib":{"patterns":["src"],"extensions":"ts,tsx,js,scss","runOnChangeOnly":true,"delay":2000}},"keywords":["container-query","element-query","breakpoint","responsive","reactjs","react","react-component"],"engines":{"node":">=8.5.0"},"browserslist":{"production":[">0.2%","not dead","IE 11","not op_mini all"],"development":["last 1 chrome version","last 1 firefox version","last 1 safari version","IE 11"]},"gitHead":"aa04510ead8f1a73571841f793b6275d4d416262","bugs":{"url":"https://github.com/DeloitteDigitalAPAC/dd-breakpoint-container/issues"},"_id":"@deloitte-digital-au/dd-breakpoint-container@0.8.6","_nodeVersion":"12.13.0","_npmVersion":"6.12.0","dist":{"integrity":"sha512-E7y0OdWf8hJa500E01yhPfn3OdwBL5M+Xwccuvc8ku/zwmEzZUANiAe3H4TRdhE9bH+2XsDU2rgUZPRQ8D8Gnw==","shasum":"faa4014f40a827ea21cf447604754302f738da57","tarball":"https://registry.npmjs.org/@deloitte-digital-au/dd-breakpoint-container/-/dd-breakpoint-container-0.8.6.tgz","fileCount":29,"unpackedSize":379040,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJd1IC1CRA9TVsSAnZWagAAWXYP/iLyPwCqpqc7X26SMgaW\nqaDHZYMm9VnVS5zwSNdFCkEQ2DNbCr/KfcI8rf7bEZ7J3raFwbVhRzb9pvHt\nSfMilfxkK1/fezp7BTe3VPktqRe4cPkM7JSelpxor4l05EGZD8sRsY4IQkwt\nLQnqFut9nt9CYjq4Mje1zscCZEn8DLxmyEz951U0SaVYHTIvvlm1i0FmAyJ+\neU+m3Ntt+UtRpsBi6uCl8TucIiFOA11MzGBQ86wQAc5Cc1Orq+lKhNxqMYdY\nM51gj3WrZpvO5YciuFoPzR/8sUZ5sh7iaqSVvDZZ9ZsJgHMhIL5Cng05JaDy\nTcr0pezD9AwNSnAdFxz0xAZcF26cnjPV8Q4uEDrgVjt8PuNwb/JH8ohaQp/V\n5szvqAL2BEJpGjF2ypn61Af0W5lRb6a1scQPUgsbnnVZsVWxFRSp0LKw69fe\nG7sSaU3R1VwBMXz+E7QeoyBz5HZ6VXWJvgpboTzTaXVxR7DMV19bYp1MXRVM\nmh2Ae0zsdu8JAq+g83T/zHa2TqtjZLhAxYYT6uLZ7aRG7mCBwFDIzirfn3rN\n3r1vrgdef8TjBSmTPTG87YXK/nPaEqejim4Hj3UFE2ILIip2DmioaYFdORVf\nFF9ogmx0/A7ffYfNZg1aHbirF9jMBNNDCO20fk6Hu2di5BB4y4xmPZeRvgt+\nBVHc\r\n=rPFA\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIAUZCHqVLAOMDSVyLcPM+j7UomzYEVp/vR9oUx/Xr4v0AiEA5AfIvzLZFDikIaoL0CrW51umAYDKHa4B080pLYadts8="}]},"maintainers":[{"name":"saxoncameron","email":"mail@saxoncameron.com"},{"name":"theflyingcoder","email":"tomrowecodechimp@gmail.com"},{"name":"dkeeghan","email":"dkeeghan@gmail.com"},{"name":"jennasalau","email":"jenna.salau@gmail.com"}],"_npmUser":{"name":"saxoncameron","email":"mail@saxoncameron.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/dd-breakpoint-container_0.8.6_1574207668615_0.5677098254759678"},"_hasShrinkwrap":false}},"time":{"created":"2019-11-19T23:54:28.384Z","0.8.6":"2019-11-19T23:54:28.789Z","modified":"2022-04-05T03:42:24.661Z"},"maintainers":[{"email":"chuang.june@gmail.com","name":"juscc"},{"email":"dkeeghan@gmail.com","name":"dkeeghan"},{"email":"jenna.salau@gmail.com","name":"jennasalau"}],"description":"Flexible container queries for responsive design in React and SCSS.","homepage":"https://github.com/DeloitteDigitalAPAC/dd-breakpoint-container/blob/master/README.md","keywords":["container-query","element-query","breakpoint","responsive","reactjs","react","react-component"],"repository":{"type":"git","url":"git+https://github.com/DeloitteDigitalAPAC/dd-breakpoint-container.git"},"author":{"name":"Deloitte Digital Australia","url":"http://deloittedigital.com.au"},"bugs":{"url":"https://github.com/DeloitteDigitalAPAC/dd-breakpoint-container/issues"},"license":"BSD-3-Clause","readme":"# :warning: Alpha release :warning:\n\nThis package is now in a state of public alpha release. Though we consider its behaviour to be stable it's missing some essential package infrastructure necessary for a `1.0.0` release. Namely - more explicit CSS-in-js support, unit tests and integration tests, some consensus items, potential refactoring, and more.\n\nAs such, please be aware that the first major version is liable to have significant API changes.\n\nUntil that time, `0.x.x` semver releases will not be disruptive or introduce breaking changes, and therefore keeping up to date with latest minor and patch releases is advised.\n\n![Deloitte Digital](dd-logo.png)\n\n# DDBreakpointContainer\n\nA container query toolkit for flexible responsive design in React and CSS. Make modular components that look great no matter what size their container, and say goodbye to media queries.\n\nFeatures for JS (React) rendering, SCSS (mixins), and support for CSS-in-js approaches (coming soon).\n\n<!-- Note: Re-generate with 'npm run doctoc' (install 'doctoc' globally) -->\n<!-- Note: If you experience issues with doctoc regen, replace below START/END with just 'START doctoc' and 'END doctoc' HTML comments and rerun -->\n<!-- START doctoc generated TOC please keep comment here to allow auto update -->\n\n<!-- END doctoc generated TOC please keep comment here to allow auto update -->\n\n## Install\n\nTo install via [npm](https://www.npmjs.com/):\n\n```\nnpm install @deloitte-digital-au/dd-breakpoint-container\n```\n\n## Usage\n\nQuick note: this library features named breakpoints, e.g. where `'s'` (small) equals 640px, `'m'` (medium) 768px and so on; keep that in mind for some of the subsequent queries.\n\n### 1. Wrap your App in `<BrowserContainer/>`\n\n```\nimport { BrowserContainer } from '@deloitte-digital-au/dd-breakpoint-container';\n...\n<BrowserContainer>\n\t<App/>\n<BrowserContainer/>\n```\n\n**Don't skip this step!** Here's why this is important:\n\n- Provides backwards-compatibility for media-query like functionality in your CSS (via the legacy `bp()` mixin/function)\n- Contains the `AppBreakpoint` React Context Provider, which makes your app's overall size/breakpoint available to your components\n- Allows `<Breakpoint/>` modules to be used anywhere within your app, not just within a `<BreakpointContainer/>`\n- If you're using `customBreakpoints`, you can set it once on `<BrowserContainer/>` instead on each and every `<BreakpointContainer/>`\n\n(Also, it doesn't matter if your app isn't fullscreen, the net result is the same).\n\n### 2. Use `<BreakpointContainer/>` in your components\n\n```\nimport { BreakpointContainer } from '@deloitte-digital-au/dd-breakpoint-container';\n...\n<BreakpointContainer>\n\t<div>My Component</div>\n<BreakpointContainer/>\n```\n\nOnce you've done this, you have a number of approaches you can use based on preference:\n\n#### SCSS pattern\n\nIf you are using SCSS, first your `<BreakpointContainer/>` will need a `className`:\n\n```\n<BreakpointContainer className=\"my-component-name\">\n\t...\n</BreakpointContainer>\n```\n\nThen you'll need to import the library's stylesheet in your own SCSS stylesheet:\n\n`@import '~@deloitte-digital-au/dd-breakpoint-container/lib/mixins.scss';`\n\nNow you can use the container query mixin in your `.scss` files. Note that the `className` you specified on your component must be the parent selector.\n\n```\n.my-component {\n\t// Core styles\n\n\t// Between 0px width and 'xs' mixin (inclusive)\n\t@include bp(0, xs) {\n\t\t...\n\t}\n\n\t// 's' breakpoint and above\n\t@include bpc(s) {\n\t\t...\n\t}\n\n\t// 'm' breakpoint only\n\t@include bpc(m, m) {\n\t\t...\n\t}\n\n\t// Between 'm' and 'l' breakpoints (inclusive)\n\t@include bpc(m, l) {\n\t\t...\n\t}\n}\n```\n\nYou can also use the existing `bp()` mixin to specify styles relative to the overall width of your app (emulating the behaviour of media queries). If the above isn't intuitive for you, check out the complete documentation in [**DDBreakpoints**](https://github.com/DeloitteDigitalAPAC/DDBreakpoints), where the behaviour is the same.\n\n#### CSS-in-js pattern\n\nOfficial support coming soon; in the meantime it is possible to bootstrap this utilising the `resolveBp` export.\n\n#### Child function pattern\n\nIf you'd like to work with responsive logic in your component JS, you can expose the current breakpoint name and container size in pixels:\n\n```\n<BreakpointContainer>\n\t{ (bpName, bpSize) => {\n\t\treturn `The current breakpoint is ${bpName}, at size ${bpSize} pixels.`.\n\t}}\n</BreakpointContainer>\n```\n\n#### Callback pattern\n\nOperate on a callback that triggers when the breakpoint changes. **Note: this is only when the active breakpoint changes (not for every change in pixel size!).**\n\n```\n<BreakpointContainer\n\tonChange={bpName => {\n\t\t...\n\t}}\n>\n\t...\n</BreakpointContainer>\n```\n\n## Conditional rendering\n\nYou can use the `<Breakpoint/>` export to conditionally render markup according to a breakpoint query, like so:\n\n```\n<div>\n    <Breakpoint query=\"s\">\n        <p>This will only render on 's' breakpoint and above</p>\n    </Breakpoint>\n    <Breakpoint query=\"xs, m\">\n        <p>This will only render between 'xs' and 'm'</p>\n    </Breakpoint>\n    <Breakpoint query=\"m, m\">\n        <p>This will only render on 'm' bp</p>\n    </Breakpoint>\n</div>\n```\n\nYou can also specify exact px:\n\n`<Breakpoint query=\"300, 600\"/>`\n\nThe component automatically detects which `<BreakpointContainer/>` it's in. Or, if it's not within one, it falls back to the app's `<BrowserContainer/>`.\n\n## Options & exports\n\n### BreakpointContainer\n\n`import { BreakpointContainer } from '@deloitte-digital-au/dd-breakpoint-container';`\n\n| Name              | Type            | Default value | Description                                                                                                                                                                                         |\n| ----------------- | --------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| className         | String          | null          | Class name(s) applied to container div, i.e. direct parent to component children                                                                                                                    |\n| containerClass    | String          | null          | Class name(s) applied to wrapper div, i.e. grandparent to component children                                                                                                                        |\n| customBreakpoints | Object          | null          | Provide your own custom breakpoints by passing in an object of key:value pairs, where the key (string) is the breakpoint name, and the value (number) is the corresponding minimum width in pixels. |\n| identifier        | String          | 'default'     | A unique id for the component. For `<Breakpoint/>` components to reference.                                                                                                                         |\n| children          | Function / Node | (required)    | Optionally receive 'bpName' (String) and 'bpSize' (Number) props. Refer to 'Child function pattern' above.                                                                                          |\n| onChange          | Function        | null          | Callback when active breakpoint changes                                                                                                                                                             |\n| debug             | Boolean         | null          | Toggles debug mode: border + breakpoint indicator                                                                                                                                                   |\n| noBpClasses       | Boolean         | false         | Opt-out of breakpoint classes, if you're not using the SCSS mixins. (Only if you want to keep the DOM a little cleaner)                                                                             |\n\n### BrowserContainer component\n\nSee above options table; this is essentially a proxy component for `<BreakpointContainer/>`, with pre-configured options `identifier=\"browser\"` and `className=\"bpc__browser\"`.\n\nThe only real difference is the behaviour of `customBreakpoints`, which, if set on your app's `<BrowserContainer/>`, will propagate down to all of the `<BreakpointContainer/>` modules within.\n\n#### AppBreakpoint context\n\nThis React Context export provides the `value` of `({ bpName: string, bpSize: number })` of the app's `<BrowserContainer/>` wrapper, so you can access your app's breakpoint in your components.\n\nNote this Context value export is an object, which you can destructure like so:\n\n```\nimport { AppBreakpoint } from '@deloitte-digital-au/dd-breakpoint-container';\n...\n<AppBreakpoint.Consumer>\n\t{({ bpName, bpSize }) =>\n\t\t<p>`Current bp name is: '${bpName}'`</p>\n\t\t<p>`Current bp size: '${bpSize}'`</p>\n\t}\n</AppBreakpoint.Consumer>\n```\n\n### Breakpoint component\n\n`import { Breakpoint } from '@deloitte-digital-au/dd-breakpoint-container';`\n\n| Name       | Type            | Default value | Description                                                                                                                                      |\n| ---------- | --------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |\n| query      | String / Number | 0             | Breakpoint query string \"$lower, $upper\", where lower/upper are either named breakpoints or pixel values. Refer to 'Usage' section for examples. |\n| q          | String / Number | -             | Shorthand for `query` prop                                                                                                                       |\n| identifier | String          | 'default'     | Define which `<BreakpointContainer/>` to work with, e.g. if you want to target the browser container.                                            |\n| children   | Node            | (required)    |                                                                                                                                                  |\n\n### HOCs\n\nBoth `<BreakpointContainer/>` and its derivative `<BrowserContainer/>` are also available as Higher Order Components:\n\n```\nexport withBreakpointContainer(MyComponent, { ...options });\n```\n\n```\nexport withBrowserContainer(MyComponent, { ...options });\n```\n\nWhich expose the `bpName: string` (the name of the active breakpoint) and `bpSize: number` (the size of the container in pixels) props to the wrapped component.\n\n### Functions\n\n`resolveBp(query: string, bp: string|number) : boolean`: The core function that much of the library is based on; it resolves a breakpoint query against a specified breakpoint or value.\n\nThe query must be in format `${lower}, ${upper}` (comma/space separated), where lower/upper are either named breakpoints or px values.\n\nThe query is generally quite forgiving: the upper value is optional and any pixel values can either be numbers (e.g. 700) or px values (e.g. 700px); they are the same, and are normalised within the function.\n\n`getBpUpperLimit(bpName: string) : number`: A function that takes a named breakpoint and returns its upper-limit.\n\nFor example, `getBpUpperLimit('s')` returns `768` (the 'm' breakpoint), as that value is the first width at which the 's' breakpoint is no longer active (aka, the upper-limit).\n\n### Other\n\n`BREAKPOINTS`: A object of key:value pairs for breakpoint names and their pixel values. The default values are:\n\n```\nBREAKPOINTS = {\n  none: 0,\n  xxxs: 320,\n  xxs: 359,\n  xs: 480,\n  s: 640,\n  m: 768,\n  l: 1024,\n  xl: 1244,\n  xxl: 1410,\n  xxxl: 1690,\n};\n```\n\n## Debug features\n\nBy default, `<BrowserContainer>` will show you a helpful breakpoint indicator in the top-left of your screen in your development builds, to show you the active breakpoint of your app. This can be turned off with the the prop `debug={false}`.\n\nConversely, you can set `debug={true}` on any `<BreakpointContainer/>` module to see the outline of its contents, as will as its own respective active breakpoint. This is very useful\n\nAll debug indicators are turned off if you have `NODE_ENV=production` set in your build, so you needn't worry about them slipping into your builds and deployments.\n\nYou can also set either of these debug flags globally using custom environment variables `BPC_DEBUG_BROWSER=true` and `BPC_DEBUG_CONTAINERS=true`.\n\n## Disclaimers\n\n### Performance\n\nThis library uses [react-resize-detector](https://github.com/maslianok/react-resize-detector) which utilises native browser support for [ResizeObservers](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver), and a [polyfill](https://github.com/que-etc/resize-observer-polyfill) for backwards compatibility with older browsers.\n\nWhile we haven't experienced any noticeable performance loss in our testing and usage, we would recommend discreet usage of this library by careful and thoughtful design. For example, if your app features a common layout or divider system, you could apply `<BreakpointContainer/>` modules to those containers instead of each of your components.\n\n### Consider media queries\n\nContainer queries are very powerful and enable new ways for responsive component development. However, if your needs are simpler and you don't need container queries, consider just using media queries. We highly recommend [**DDBreakpoints**](https://github.com/DeloitteDigitalAPAC/DDBreakpoints); our long-standing and preferred approach towards responsive design, which utilises media queries.\n\n### DDBreakpoints Backwards compatibility\n\n**DDBreakpointContainer** can be\\* a fully backwards-compatible replacement for the original [**DDBreakpoints**](https://github.com/DeloitteDigitalAPAC/DDBreakpoints) core SCSS mixin; any existing stylesheets with the `bp()` mixin will work the same. And in your design we would still encourage you use a mix of 'media queries' `bp()` and 'container queries' `bpc()` as makes sense in the context of your app.\n\n\\* Note that this functionality depends on the proper set-up of the `<BrowserContainer/>` component as per the instructions above in the 'Getting started' section.\n\n## About Deloitte Digital Australia\n\n### Key contributors\n\n- @saxoncameron\n\n### Who are we?\n\n**Part Business. Part Creative. Part Technology. One hundred per cent digital.**\n\nPioneered in Australia, Deloitte Digital is committed to helping clients unlock the business value of emerging technologies. We provide clients with a full suite of digital services, covering digital strategy, user experience, content, creative, engineering and implementation across mobile, web and social media channels.\n\n[http://www.deloittedigital.com/au](http://www.deloittedigital.com/au)\n\n## Licence\n\nBSD-3-Clause ([View License](LICENSE))\n","readmeFilename":"README.md"}