Breakpoint (#733)

* feat(breakpoint): add Breakpoint

* docs(breakpoint): update docs

* refactor(breakpoint): add prop descriptions, type slot

* docs: add missing semicolon to last typedef

* docs: decrease margin bottom for inline snippet

* docs: add Breakpoint to new components [ci skip]

* docs(config): use "scripts-markup-styles" for svelteSortOrder [ci skip]

* docs(breakpoint): label on:match event [ci skip]

COMPONENT_INDEX.md

@@ -1,6 +1,6 @@
 # Component Index
 
-> 170 components exported from carbon-components-svelte@0.39.0.
+> 171 components exported from carbon-components-svelte@0.39.0.
 
 ## Components
 
@@ -11,6 +11,7 @@
 - [`Breadcrumb`](#breadcrumb)
 - [`BreadcrumbItem`](#breadcrumbitem)
 - [`BreadcrumbSkeleton`](#breadcrumbskeleton)
+- [`Breakpoint`](#breakpoint)
 - [`Button`](#button)
 - [`ButtonSet`](#buttonset)
 - [`ButtonSkeleton`](#buttonskeleton)
@@ -344,6 +345,36 @@ None.
 | mouseenter | forwarded | --     |
 | mouseleave | forwarded | --     |
 
+## `Breakpoint`
+
+### Types
+
+```ts
+export type BreakpointSize = "sm" | "md" | "lg" | "xlg" | "max";
+
+export type BreakpointValue = 320 | 672 | 1056 | 1312 | 1584;
+```
+
+### Props
+
+| Prop name   | Kind               | Reactive | Type                                                 | Default value                                                             | Description                                       |
+| :---------- | :----------------- | :------- | :--------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
+| sizes       | <code>let</code>   | Yes      | <code>Record<BreakpointSize, boolean></code>         | <code>{ sm: false, md: false, lg: false, xlg: false, max: false, }</code> | Carbon grid sizes as an object                    |
+| size        | <code>let</code>   | Yes      | <code>BreakpointSize</code>                          | --                                                                        | Determine the current Carbon grid breakpoint size |
+| breakpoints | <code>const</code> | No       | <code>Record<BreakpointSize, BreakpointValue></code> | <code>{ sm: 320, md: 672, lg: 1056, xlg: 1312, max: 1584, }</code>        | Reference the Carbon grid breakpoints             |
+
+### Slots
+
+| Slot name | Default | Props                                                                           | Fallback |
+| :-------- | :------ | :------------------------------------------------------------------------------ | :------- |
+| --        | Yes     | <code>{ size: BreakpointSize; sizes: Record<BreakpointSize, boolean>; } </code> | --       |
+
+### Events
+
+| Event name | Type       | Detail                                                                   |
+| :--------- | :--------- | :----------------------------------------------------------------------- |
+| match      | dispatched | <code>{ size: BreakpointSize; breakpointValue: BreakpointValue; }</code> |
+
 ## `Button`
 
 ### Props

docs/src/COMPONENT_API.json

@@ -1,5 +1,5 @@
 {
-  "total": 170,
+  "total": 171,
   "components": [
     {
       "moduleName": "Accordion",
@@ -344,6 +344,67 @@
       "typedefs": [],
       "rest_props": { "type": "Element", "name": "div" }
     },
+    {
+      "moduleName": "Breakpoint",
+      "filePath": "src/Breakpoint/Breakpoint.svelte",
+      "props": [
+        {
+          "name": "size",
+          "kind": "let",
+          "description": "Determine the current Carbon grid breakpoint size",
+          "type": "BreakpointSize",
+          "isFunction": false,
+          "constant": false,
+          "reactive": true
+        },
+        {
+          "name": "sizes",
+          "kind": "let",
+          "description": "Carbon grid sizes as an object",
+          "type": "Record<BreakpointSize, boolean>",
+          "value": "{     sm: false,     md: false,     lg: false,     xlg: false,     max: false,   }",
+          "isFunction": false,
+          "constant": false,
+          "reactive": true
+        },
+        {
+          "name": "breakpoints",
+          "kind": "const",
+          "description": "Reference the Carbon grid breakpoints",
+          "type": "Record<BreakpointSize, BreakpointValue>",
+          "value": "{     sm: 320,     md: 672,     lg: 1056,     xlg: 1312,     max: 1584,   }",
+          "isFunction": false,
+          "constant": true,
+          "reactive": false
+        }
+      ],
+      "slots": [
+        {
+          "name": "__default__",
+          "default": true,
+          "slot_props": "{ size: BreakpointSize; sizes: Record<BreakpointSize, boolean>; }"
+        }
+      ],
+      "events": [
+        {
+          "type": "dispatched",
+          "name": "match",
+          "detail": "{ size: BreakpointSize; breakpointValue: BreakpointValue; }"
+        }
+      ],
+      "typedefs": [
+        {
+          "type": "\"sm\" | \"md\" | \"lg\" | \"xlg\" | \"max\"",
+          "name": "BreakpointSize",
+          "ts": "type BreakpointSize = \"sm\" | \"md\" | \"lg\" | \"xlg\" | \"max\""
+        },
+        {
+          "type": "320 | 672 | 1056 | 1312 | 1584",
+          "name": "BreakpointValue",
+          "ts": "type BreakpointValue = 320 | 672 | 1056 | 1312 | 1584"
+        }
+      ]
+    },
     {
       "moduleName": "Button",
       "filePath": "src/Button/Button.svelte",

docs/src/components/ComponentApi.svelte

@@ -141,7 +141,7 @@
     style="margin-top: var(--cds-spacing-08)"
     class="my-layout-01-03"
     type="multi"
-    code="{component.typedefs.map((t) => t.ts).join(';\n\n')}"
+    code="{component.typedefs.map((t) => t.ts).join(';\n\n')};"
   />
 {:else}
   <p class="my-layout-01-03">No typedefs.</p>

docs/src/components/InlineSnippet.svelte

@@ -11,6 +11,6 @@
 
 <style>
   div {
-    margin-bottom: var(--cds-spacing-04);
+    margin-bottom: var(--cds-spacing-03);
   }
 </style>

docs/src/pages/_layout.svelte

@@ -20,7 +20,7 @@
   import Footer from "../components/Footer.svelte";
 
   const deprecated = ["ToggleSmall", "Icon"];
-  const new_components = ["ProgressBar", "RecursiveList", "TreeView"];
+  const new_components = ["Breakpoint", "RecursiveList", "TreeView"];
 
   let isOpen = false;
   let isSideNavOpen = true;

docs/src/pages/components/Breakpoint.svx

@@ -0,0 +1,27 @@
+
+<script>
+  import {
+    Breakpoint, UnorderedList, ListItem
+  } from "carbon-components-svelte";
+  import Preview from "../../components/Preview.svelte";
+</script>
+
+The [Carbon Design System grid implementation](https://carbondesignsystem.com/guidelines/2x-grid/implementation#responsive-options) defines five responsive breakpoints:
+
+<UnorderedList svx-ignore style="margin-bottom: var(--cds-spacing-08)">
+  <ListItem><strong>Small</strong>: less than 672px</ListItem>
+  <ListItem><strong>Medium</strong>: 672 - 1056px</ListItem>
+  <ListItem><strong>Large</strong>: 1056 - 1312px</ListItem>
+  <ListItem><strong>X-Large</strong>: 1312 - 1584px</ListItem>
+  <ListItem><strong>Max</strong>: greater than 1584px</ListItem>
+</UnorderedList>
+
+This utility component uses the [Window.matchMedia API](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) to declaratively determine the current Carbon breakpoint size.
+
+### Default
+
+Bind to the `size` prop to determine the current breakpoint size. Possible values include: `"sm" | "md" | "lg" | "xlg" | "max"`.
+
+The `"on:match"` event will fire only when a breakpoint change event occurs (e.g., the browser width is resized).
+
+<FileSource src="/framed/Breakpoint/Breakpoint" />

docs/src/pages/framed/Breakpoint/Breakpoint.svelte

@@ -0,0 +1,28 @@
+<script>
+  import { Breakpoint } from "carbon-components-svelte";
+
+  let size;
+  let events = [];
+</script>
+
+<Breakpoint bind:size on:match="{(e) => (events = [...events, e.detail])}" />
+
+<p>Resize the width of your browser.</p>
+<h6>Breakpoint size</h6>
+<h1>{size}</h1>
+
+<h6>on:match</h6>
+<pre>
+  {JSON.stringify(events,null, 2)}
+</pre>
+
+<style>
+  p,
+  h1 {
+    margin-bottom: var(--cds-spacing-08);
+  }
+
+  h6 {
+    margin-bottom: var(--cds-spacing-03);
+  }
+</style>

docs/svelte.config.js

@@ -68,6 +68,7 @@ function plugin() {
       const formattedCode = format(scriptBlock + node.value, {
         parser: "svelte",
         svelteBracketNewLine: true,
+        svelteSortOrder: "scripts-markup-styles",
       });
       const highlightedCode = Prism.highlight(
         formattedCode,

src/Breakpoint/Breakpoint.svelte

@@ -0,0 +1,100 @@
+<script>
+  /**
+   * @typedef {"sm" | "md" | "lg" | "xlg" | "max"} BreakpointSize
+   * @typedef {320 | 672 | 1056 | 1312 | 1584} BreakpointValue
+   * @event {{ size: BreakpointSize; breakpointValue: BreakpointValue; }} match
+   * @slot {{ size: BreakpointSize; sizes: Record<BreakpointSize, boolean>; }}
+   */
+
+  /**
+   * Determine the current Carbon grid breakpoint size
+   * @type {BreakpointSize}
+   */
+  export let size = undefined;
+
+  /**
+   * Carbon grid sizes as an object
+   * @type {Record<BreakpointSize, boolean>}
+   */
+  export let sizes = {
+    sm: false,
+    md: false,
+    lg: false,
+    xlg: false,
+    max: false,
+  };
+
+  /**
+   * Reference the Carbon grid breakpoints
+   * @type {Record<BreakpointSize, BreakpointValue>}
+   */
+  export const breakpoints = {
+    sm: 320,
+    md: 672,
+    lg: 1056,
+    xlg: 1312,
+    max: 1584,
+  };
+
+  import { createEventDispatcher, onMount } from "svelte";
+
+  const dispatch = createEventDispatcher();
+
+  onMount(() => {
+    const width = window.innerWidth;
+
+    if (width > breakpoints.max) size = "max";
+    else if (width < breakpoints.md) size = "sm";
+    else if (width >= breakpoints.md && width <= breakpoints.lg) size = "md";
+    else if (width >= breakpoints.lg && width <= breakpoints.xlg) size = "lg";
+    else if (width >= breakpoints.xlg && width <= breakpoints.max) size = "xlg";
+
+    const match = {
+      sm: window.matchMedia(`(max-width: ${breakpoints.md}px)`),
+      md: window.matchMedia(
+        `(min-width: ${breakpoints.md}px) and (max-width: ${breakpoints.lg}px)`
+      ),
+      lg: window.matchMedia(
+        `(min-width: ${breakpoints.lg}px) and (max-width: ${breakpoints.xlg}px)`
+      ),
+      xlg: window.matchMedia(
+        `(min-width: ${breakpoints.xlg}px) and (max-width: ${breakpoints.max}px)`
+      ),
+      max: window.matchMedia(`(min-width: ${breakpoints.max}px)`),
+    };
+    const matchers = Object.entries(match);
+    const matchersBySize = Object.fromEntries(
+      matchers.map(([size, queryList]) => [queryList.media, size])
+    );
+
+    function handleChange({ matches, media }) {
+      const size = matchersBySize[media];
+
+      sizes = { ...sizes };
+      sizes[size] = matches;
+
+      if (matches)
+        dispatch("match", { size, breakpointValue: breakpoints[size] });
+    }
+
+    matchers.forEach(([size, queryList]) =>
+      queryList.addEventListener("change", handleChange)
+    );
+
+    return () => {
+      matchers.forEach(([size, queryList]) =>
+        queryList.removeEventListener("change", handleChange)
+      );
+    };
+  });
+
+  $: {
+    if (sizes.sm) size = "sm";
+    if (sizes.md) size = "md";
+    if (sizes.lg) size = "lg";
+    if (sizes.xlg) size = "xlg";
+    if (sizes.max) size = "max";
+  }
+</script>
+
+<slot size="{size}" sizes="{sizes}" />

src/Breakpoint/index.js

@@ -0,0 +1 @@
+export { default as Breakpoint } from "./Breakpoint.svelte";

src/index.js

@@ -1,6 +1,7 @@
 export { Accordion, AccordionItem, AccordionSkeleton } from "./Accordion";
 export { AspectRatio } from "./AspectRatio";
 export { Breadcrumb, BreadcrumbItem, BreadcrumbSkeleton } from "./Breadcrumb";
+export { Breakpoint } from "./Breakpoint";
 export { Button, ButtonSkeleton, ButtonSet } from "./Button";
 export { Checkbox, CheckboxSkeleton } from "./Checkbox";
 export { ContentSwitcher, Switch } from "./ContentSwitcher";

tests/Breakpoint.test.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+  import { Breakpoint } from "../types";
+
+  let size;
+</script>
+
+<Breakpoint
+  bind:size
+  let:size="{currentSize}"
+  on:match="{(e) => {
+    console.log(e.detail);
+  }}"
+>
+  {currentSize}
+</Breakpoint>

types/Breakpoint/Breakpoint.d.ts

@@ -0,0 +1,37 @@
+/// <reference types="svelte" />
+import { SvelteComponentTyped } from "svelte";
+
+export type BreakpointSize = "sm" | "md" | "lg" | "xlg" | "max";
+
+export type BreakpointValue = 320 | 672 | 1056 | 1312 | 1584;
+
+export interface BreakpointProps {
+  /**
+   * Determine the current Carbon grid breakpoint size
+   */
+  size?: BreakpointSize;
+
+  /**
+   * Carbon grid sizes as an object
+   * @default { sm: false, md: false, lg: false, xlg: false, max: false, }
+   */
+  sizes?: Record<BreakpointSize, boolean>;
+
+  /**
+   * Reference the Carbon grid breakpoints
+   * @constant
+   * @default { sm: 320, md: 672, lg: 1056, xlg: 1312, max: 1584, }
+   */
+  breakpoints?: { sm: 320; md: 672; lg: 1056; xlg: 1312; max: 1584 };
+}
+
+export default class Breakpoint extends SvelteComponentTyped<
+  BreakpointProps,
+  {
+    match: CustomEvent<{
+      size: BreakpointSize;
+      breakpointValue: BreakpointValue;
+    }>;
+  },
+  { default: { size: BreakpointSize; sizes: Record<BreakpointSize, boolean> } }
+> {}

types/index.d.ts

@@ -5,6 +5,7 @@ export { default as AspectRatio } from "./AspectRatio/AspectRatio";
 export { default as Breadcrumb } from "./Breadcrumb/Breadcrumb";
 export { default as BreadcrumbItem } from "./Breadcrumb/BreadcrumbItem";
 export { default as BreadcrumbSkeleton } from "./Breadcrumb/BreadcrumbSkeleton";
+export { default as Breakpoint } from "./Breakpoint/Breakpoint";
 export { default as Button } from "./Button/Button";
 export { default as ButtonSkeleton } from "./Button/ButtonSkeleton";
 export { default as ButtonSet } from "./Button/ButtonSet";