From 213d4debe71439349e8a62f7477d2af6cb04f5c8 Mon Sep 17 00:00:00 2001
From: Harald Brunner <brunnerh@users.noreply.github.com>
Date: Sun, 20 Feb 2022 16:50:22 +0100
Subject: [PATCH] Remove additional exports of breakpoint symbols. Restore
 typedef entries in `Breakpoint` component. Generate type definitions for
 `constants.js` and `breakpointObserver.js`. Validate size passed to
 `smallerThan`/`largerThan`. Document `breakpointObserver`/`breakpoints`. Fix
 `Breakpoint` component docs/example.

---
 COMPONENT_INDEX.md                            |  8 +++++++
 docs/src/COMPONENT_API.json                   | 13 ++++++++++-
 docs/src/pages/components/Breakpoint.svx      | 12 ++++++++--
 .../pages/framed/Breakpoint/Breakpoint.svelte |  4 ++--
 .../Breakpoint/BreakpointObserver.svelte      | 15 ++++++++++++
 src/Breakpoint/Breakpoint.svelte              |  2 ++
 src/Breakpoint/breakpointObserver.d.ts        | 19 +++++++++++++++
 src/Breakpoint/breakpointObserver.js          | 23 ++++++++++++++-----
 src/Breakpoint/constants.d.ts                 |  5 ++++
 src/Breakpoint/index.d.ts                     |  2 ++
 src/index.js                                  |  2 +-
 types/Breakpoint/Breakpoint.svelte.d.ts       |  4 ++++
 types/index.d.ts                              |  2 --
 13 files changed, 97 insertions(+), 14 deletions(-)
 create mode 100644 docs/src/pages/framed/Breakpoint/BreakpointObserver.svelte
 create mode 100644 src/Breakpoint/breakpointObserver.d.ts
 create mode 100644 src/Breakpoint/constants.d.ts
 create mode 100644 src/Breakpoint/index.d.ts

diff --git a/COMPONENT_INDEX.md b/COMPONENT_INDEX.md
index 4c5249f1..e9196814 100644
--- a/COMPONENT_INDEX.md
+++ b/COMPONENT_INDEX.md
@@ -348,6 +348,14 @@ None.
 
 ## `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                                       |
diff --git a/docs/src/COMPONENT_API.json b/docs/src/COMPONENT_API.json
index 7b5c2ea3..74132829 100644
--- a/docs/src/COMPONENT_API.json
+++ b/docs/src/COMPONENT_API.json
@@ -403,7 +403,18 @@
           "detail": "{ size: BreakpointSize; breakpointValue: BreakpointValue; }"
         }
       ],
-      "typedefs": []
+      "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",
diff --git a/docs/src/pages/components/Breakpoint.svx b/docs/src/pages/components/Breakpoint.svx
index 082f57bc..22bf672f 100644
--- a/docs/src/pages/components/Breakpoint.svx
+++ b/docs/src/pages/components/Breakpoint.svx
@@ -22,6 +22,14 @@ This utility component uses the [Window.matchMedia API](https://developer.mozill
 
 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).
+The `"on:change"` event will fire when the size is initially determined and when a breakpoint change event occurs (e.g., the browser width is resized).
 
-<FileSource src="/framed/Breakpoint/Breakpoint" />
\ No newline at end of file
+<FileSource src="/framed/Breakpoint/Breakpoint" />
+
+### Store and Breakpoint Values
+
+As an alternative to the component, `breakpointObserver` can be used to get the current size as a Svelte store. The store has two additional functions which create derived stores that return a `boolean` indicating whether the size is smaller/larger than a certain breakpoint.
+
+There also exists a `breakpoints` dictionary mapping from `BreakpointSize` to `BreakpointValue`.
+
+<FileSource src="/framed/Breakpoint/BreakpointObserver" />
diff --git a/docs/src/pages/framed/Breakpoint/Breakpoint.svelte b/docs/src/pages/framed/Breakpoint/Breakpoint.svelte
index 83116706..b1b7e0a1 100644
--- a/docs/src/pages/framed/Breakpoint/Breakpoint.svelte
+++ b/docs/src/pages/framed/Breakpoint/Breakpoint.svelte
@@ -5,13 +5,13 @@
   let events = [];
 </script>
 
-<Breakpoint bind:size on:match="{(e) => (events = [...events, e.detail])}" />
+<Breakpoint bind:size on:change="{(e) => (events = [...events, e.detail])}" />
 
 <p>Resize the width of your browser.</p>
 <h6>Breakpoint size</h6>
 <h1>{size}</h1>
 
-<h6>on:match</h6>
+<h6>on:change</h6>
 <pre>
   {JSON.stringify(events, null, 2)}
 </pre>
diff --git a/docs/src/pages/framed/Breakpoint/BreakpointObserver.svelte b/docs/src/pages/framed/Breakpoint/BreakpointObserver.svelte
new file mode 100644
index 00000000..a37e4683
--- /dev/null
+++ b/docs/src/pages/framed/Breakpoint/BreakpointObserver.svelte
@@ -0,0 +1,15 @@
+<script>
+  import {
+    breakpointObserver,
+    breakpoints,
+  } from "carbon-components-svelte/src/Breakpoint";
+
+  const size = breakpointObserver();
+  const smaller = size.smallerThan("md");
+  const larger = size.largerThan("md");
+</script>
+
+<p>Current breakpoint size: {$size}</p>
+<p>Current breakpoint value: {breakpoints[$size]}px</p>
+<p>Smaller than medium: {$smaller}</p>
+<p>Larger than medium: {$larger}</p>
diff --git a/src/Breakpoint/Breakpoint.svelte b/src/Breakpoint/Breakpoint.svelte
index 740d6ea2..8eb93c8c 100644
--- a/src/Breakpoint/Breakpoint.svelte
+++ b/src/Breakpoint/Breakpoint.svelte
@@ -1,5 +1,7 @@
 <script>
   /**
+   * @typedef {"sm" | "md" | "lg" | "xlg" | "max"} BreakpointSize
+   * @typedef {320 | 672 | 1056 | 1312 | 1584} BreakpointValue
    * @event {{ size: BreakpointSize; breakpointValue: BreakpointValue; }} change
    * @slot {{ size: BreakpointSize; sizes: Record<BreakpointSize, boolean>; }}
    */
diff --git a/src/Breakpoint/breakpointObserver.d.ts b/src/Breakpoint/breakpointObserver.d.ts
new file mode 100644
index 00000000..46da45a8
--- /dev/null
+++ b/src/Breakpoint/breakpointObserver.d.ts
@@ -0,0 +1,19 @@
+/**
+ * Creates a readable store that returns the current {@link BreakpointSize}.
+ * It also provides functions for creating derived stores used to do comparisons.
+ */
+export function breakpointObserver(): {
+    subscribe: (this: void, run: import("svelte/store").Subscriber<any>, invalidate?: (value?: any) => void) => import("svelte/store").Unsubscriber;
+    /**
+     * Returns a store readable store that returns whether the current
+     * breakpoint is smaller than {@link size}.
+     * @param {BreakpointSize} size Size to compare against.
+     */
+    smallerThan: (size: BreakpointSize) => import("svelte/store").Readable<boolean>;
+    /**
+     * Returns a store readable store that returns whether the current
+     * breakpoint is larger than {@link size}.
+     * @param {BreakpointSize} size Size to compare against.
+     */
+    largerThan: (size: BreakpointSize) => import("svelte/store").Readable<boolean>;
+};
diff --git a/src/Breakpoint/breakpointObserver.js b/src/Breakpoint/breakpointObserver.js
index 7d54d7d3..3f5418cd 100644
--- a/src/Breakpoint/breakpointObserver.js
+++ b/src/Breakpoint/breakpointObserver.js
@@ -53,19 +53,30 @@ export function breakpointObserver() {
 
   return {
     subscribe: store.subscribe,
+
     /**
      * Returns a store readable store that returns whether the current
-     * breakpoint smaller than {@link size}.
+     * breakpoint is smaller than {@link size}.
      * @param {BreakpointSize} size Size to compare against.
      */
-    smallerThan: (size) =>
-      derived(store, ($size) => breakpoints[$size] < breakpoints[size]),
+    smallerThan: (size) => {
+      checkSizeValid(size);
+      return derived(store, ($size) => breakpoints[$size] < breakpoints[size]);
+    },
+
     /**
      * Returns a store readable store that returns whether the current
-     * breakpoint larger than {@link size}.
+     * breakpoint is larger than {@link size}.
      * @param {BreakpointSize} size Size to compare against.
      */
-    largerThan: (size) =>
-      derived(store, ($size) => breakpoints[$size] > breakpoints[size]),
+    largerThan: (size) => {
+      checkSizeValid(size);
+      return derived(store, ($size) => breakpoints[$size] > breakpoints[size]);
+    },
   };
 }
+
+function checkSizeValid(size) {
+  if (size in breakpoints == false)
+    throw new Error(`"${size}" is not a valid breakpoint size.`);
+}
diff --git a/src/Breakpoint/constants.d.ts b/src/Breakpoint/constants.d.ts
new file mode 100644
index 00000000..357b04d5
--- /dev/null
+++ b/src/Breakpoint/constants.d.ts
@@ -0,0 +1,5 @@
+/**
+ * Pixel sizes of Carbon grid breakpoints.
+ * @type {Record<BreakpointSize, BreakpointValue>}
+ */
+export const breakpoints: Record<BreakpointSize, BreakpointValue>;
diff --git a/src/Breakpoint/index.d.ts b/src/Breakpoint/index.d.ts
new file mode 100644
index 00000000..ec1563a6
--- /dev/null
+++ b/src/Breakpoint/index.d.ts
@@ -0,0 +1,2 @@
+export { breakpointObserver } from "./breakpointObserver";
+export { breakpoints } from "./constants";
diff --git a/src/index.js b/src/index.js
index a57b29e7..0b8733d3 100644
--- a/src/index.js
+++ b/src/index.js
@@ -1,7 +1,7 @@
 export { Accordion, AccordionItem, AccordionSkeleton } from "./Accordion";
 export { AspectRatio } from "./AspectRatio";
 export { Breadcrumb, BreadcrumbItem, BreadcrumbSkeleton } from "./Breadcrumb";
-export { Breakpoint, breakpoints, breakpointObserver } from "./Breakpoint";
+export { Breakpoint } from "./Breakpoint";
 export { Button, ButtonSkeleton, ButtonSet } from "./Button";
 export { Checkbox, CheckboxSkeleton } from "./Checkbox";
 export { ContentSwitcher, Switch } from "./ContentSwitcher";
diff --git a/types/Breakpoint/Breakpoint.svelte.d.ts b/types/Breakpoint/Breakpoint.svelte.d.ts
index f247939e..3fd72642 100644
--- a/types/Breakpoint/Breakpoint.svelte.d.ts
+++ b/types/Breakpoint/Breakpoint.svelte.d.ts
@@ -1,6 +1,10 @@
 /// <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
diff --git a/types/index.d.ts b/types/index.d.ts
index 2df62c5b..2aed619a 100644
--- a/types/index.d.ts
+++ b/types/index.d.ts
@@ -6,8 +6,6 @@ export { default as Breadcrumb } from "./Breadcrumb/Breadcrumb.svelte";
 export { default as BreadcrumbItem } from "./Breadcrumb/BreadcrumbItem.svelte";
 export { default as BreadcrumbSkeleton } from "./Breadcrumb/BreadcrumbSkeleton.svelte";
 export { default as Breakpoint } from "./Breakpoint/Breakpoint.svelte";
-export { default as breakpoints } from "./Breakpoint";
-export { default as breakpointObserver } from "./Breakpoint";
 export { default as Button } from "./Button/Button.svelte";
 export { default as ButtonSkeleton } from "./Button/ButtonSkeleton.svelte";
 export { default as ButtonSet } from "./Button/ButtonSet.svelte";