Merge pull request #108 from UrbanInstitute/patch-storybook-descriptions

Update component descriptions and associated declaration

.github/pull_request_template.md

@@ -17,3 +17,4 @@ Tell us what this PR does or link to any related issues that describe the goal h
 - [ ] Added any changes in this PR to the `CHANGELOG.md` `Next` section
 - [ ] If this pull request includes a new component or feature, has it been exported from one of the library's entry points?
 - [ ] Does the component dispatch relevant interaction events? (ie: on:click, on:change, etc.)
+- [ ] Does the component directory include description and usage information in `.stories.svelte`?

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 - Patch: Update BasicDropdown with better accessibility (icon hidden from screen readers)
 - Feature: GitHub source links for components via [@etchteam/storybook-addon-github-link](https://storybook.js.org/addons/@etchteam/storybook-addon-github-link) in storybook docs
+- Patch: Update method of declaring Storybook component descriptions and add import instructions to components
+- Patch: Remove description field from top level `meta` object in component `.stories.svelte` files (do not render)
 
 ## v0.10.2
 

src/docs/stories/BasicPage.stories.svelte

@@ -1,14 +1,6 @@
 <script context="module">
   export const meta = {
-    title: "Examples/Stories/BasicPage",
-    description: "An example of collecting several components into a basic page",
-    parameters: {
-      docs: {
-        description: {
-          component: "a basic content block."
-        }
-      }
-    }
+    title: "Examples/Stories/BasicPage"
   };
 </script>
 

src/docs/stories/CustomSVGMap.stories.svelte

@@ -1,25 +1,13 @@
 <script context="module">
   export const meta = {
-    title: "Examples/Stories/CustomSVGMap",
-    parameters: {
-      docs: {
-        description: {
-          component: "An custom SVGMap with a ColorLegend and tooltip."
-        }
-      }
-    }
+    title: "Examples/Stories/CustomSVGMap"
   };
 </script>
 
 <script>
   import { Story, Template } from "@storybook/addon-svelte-csf";
   import { ChartBlock } from "$lib";
-  import {
-    SVGPolygonLayer,
-    SVGLabelLayer,
-    SVGPointLayer,
-    SVGMap
-  } from "$lib/maps";
+  import { SVGPolygonLayer, SVGLabelLayer, SVGPointLayer, SVGMap } from "$lib/maps";
   import ColorLegend from "$lib/maps/ColorLegend/ColorLegend.svelte";
   import county_air_quality_topo from "../../docs/sample-data/county_air_quality_topo.json";
   import { urbanColors } from "$lib/utils";
@@ -33,7 +21,6 @@
   let airQualityScale = scaleQuantile()
     .domain(county_air_quality.features.map((d) => d.properties.index_air_quality))
     .range(urbanColors.getDivergingColors());
-
 </script>
 
 <Template></Template>

src/docs/stories/DatawrapperSwitching.stories.svelte

@@ -1,7 +1,6 @@
 <script context="module">
   export const meta = {
-    title: "Examples/Stories/Datawrapper Switching",
-    description: "Examples of switching between Datawrapper iframes"
+    title: "Examples/Stories/Datawrapper Switching"
   };
 </script>
 

src/docs/stories/DynamicInfoStores.stories.svelte

@@ -1,7 +1,6 @@
 <script context="module">
   export const meta = {
-    title: "Examples/Stories/Dynamic Info With Stores",
-    description: "Example of writable/derived Svelte store for dynamic data lookup"
+    title: "Examples/Stories/Dynamic Info With Stores"
   };
 </script>
 

src/lib/Analytics/Analytics.docs.mdx

@@ -1,13 +1,24 @@
 import * as Stories from "./Analytics.stories.svelte";
-import { Meta, Story, Stories as StoriesDocBlock, Canvas, Controls, Primary, Source } from '@storybook/blocks';
-
+import {
+  Meta,
+  Story,
+  Stories as StoriesDocBlock,
+  Canvas,
+  Controls,
+  Primary,
+  Source
+} from "@storybook/blocks";
 
 <Meta title="Components/Analytics" of={Stories} />
 
 # Analytics
 
 A component that adds Urban Institute's Google Analytics to your page. This will enable tracking of page views and custom events in your project.
 
+```js
+import { Analytics } from "@urbaninstitute/dataviz-components";
+```
+
 ## Properties
 
 The `Analytics` component has the following properties.
@@ -18,47 +29,54 @@ The `Analytics` component has the following properties.
 
 By default, this will add Google analytics' `gtag` to your page and fire a page view. If you are using Urban Institute's dataviz project template, you'll likely want to include this in your `+layout.svelte` or on your `+page.svelte` routes.
 
-<Source dark code={`
+<Source
+  dark
+  code={`
 <script>
 import { Analytics } from "@urbaninstitute/dataviz-components";
 </script>
 <Analytics title="My project title" />
-`} language="html"/>
+`}
+  language="html"
+/>
 
 If you'd like to avoid firing a pageview because you're creating an en embed or for any other reason, you can do so by setting `sendPageview` to `false`.
 
-<Source dark code={`
+<Source
+  dark
+  code={`
 <script>
 import { Analytics } from "@urbaninstitute/dataviz-components";
 </script>
 <Analytics title="My project title" sendPageview={false}/>
-`} language="html"/>
+`}
+  language="html"
+/>
 
 Anytime you have an event handler, use this one-line function call to send relevant data through to Google Analytics:
 
 <Source dark code={`
 import { logClickToGA } from "@urbaninstitute/dataviz-components";
 
-/**
- * sends event data to GTM and GA. call in event handlers for each event type you wish to track.
- * A function that logs a click event to Google Analytics.
- * @param {HTMLElement} target The DOM element that triggered the event.
- * @param {string} eventName A string in the format "event_name--event_specifics" where "event_name is the type of event, such as "map_click" or "dropdown_select" and "event_specifics" refers to the selected option, region, or specific function.
- */
-logClickToGA(target, eventName);
-`} language="js"/>
+/\*\*
+
+- sends event data to GTM and GA. call in event handlers for each event type you wish to track.
+- A function that logs a click event to Google Analytics.
+- @param {HTMLElement} target The DOM element that triggered the event.
+- @param {string} eventName A string in the format "event_name--event_specifics" where "event_name is the type of event, such as "map_click" or "dropdown_select" and "event_specifics" refers to the selected option, region, or specific function.
+  \*/
+  logClickToGA(target, eventName);
+  `} language="js"/>
 
 An example of logClickToGA in action:
 
 <Source dark code={`
 import { logClickToGA } from "@urbaninstitute/dataviz-components";
 
 myElement.addEventListener("click", (e) => {
-  logClickToGA(
-    e.target,
-    "map_click--" + e.detail.hoverData.hoverCounty + ", " + e.detail.hoverData.hoverStateName
-  );
+logClickToGA(
+e.target,
+"map_click--" + e.detail.hoverData.hoverCounty + ", " + e.detail.hoverData.hoverStateName
+);
 });
 `} language="js"/>
-
-

src/lib/Analytics/Analytics.stories.svelte

@@ -3,14 +3,8 @@
 
   export const meta = {
     title: "Components/Analytics",
-    description: "A component that provides Google Analytics functionality to your page.",
     component: Analytics,
     parameters: {
-      docs: {
-        description: {
-          component: "A component that provides Google Analytics functionality to your page."
-        }
-      },
       githubLink: {
         url: "/Analytics/Analytics.svelte"
       }

src/lib/BasicDropdown/BasicDropdown.docs.md

@@ -0,0 +1,5 @@
+Basic HTML dropdown adhering to Urban styles.
+
+```js
+import { BasicDropdown } from "@urbaninstitute/dataviz-components";
+```

src/lib/BasicDropdown/BasicDropdown.stories.svelte

@@ -2,10 +2,10 @@
   import BasicDropdown from "./BasicDropdown.svelte";
   import IconDownload from "$lib/Button/IconDownload.svelte";
   import urbanColors from "$lib/utils/urbanColors.js";
+  import docs from "./BasicDropdown.docs.md?raw";
 
   export const meta = {
     title: "Components/BasicDropdown",
-    description: "A basic dropdown component that uses a <select> element under the hood.",
     component: BasicDropdown,
     tags: ["autodocs"],
     argTypes: {
@@ -21,7 +21,7 @@
     parameters: {
       docs: {
         description: {
-          component: "Basic HTML dropdown adhering to Urban styles."
+          component: docs
         }
       },
       githubLink: {

src/lib/Block/Block.docs.md

@@ -0,0 +1,5 @@
+A basic content block with several width options. This helps when building a page layout if you'd like to place your own components inside a container that aligns with the body well of a typical urban.org layout, a wider block, or a full width block.
+
+```js
+import { Block } from "@urbaninstitute/dataviz-components";
+```

src/lib/Block/Block.stories.svelte

@@ -1,9 +1,9 @@
 <script context="module">
   import Block from "./Block.svelte";
+  import docs from "./Block.docs.md?raw";
 
   export const meta = {
     title: "Components/Block",
-    description: "A basic building block of a page",
     component: Block,
     tags: ["autodocs"],
     argTypes: {
@@ -16,8 +16,7 @@
     parameters: {
       docs: {
         description: {
-          component:
-            "A basic content block with several width options. This helps when building a page layout if you'd like to place your own components inside a container that aligns with the body well of a typical urban.org layout, a wider block, or a full width block."
+          component: docs
         }
       },
       githubLink: {

src/lib/Button/Button.docs.md

@@ -0,0 +1,5 @@
+Basic HTML Button adhering to Urban styles.
+
+```js
+import { Button } from "@urbaninstitute/dataviz-components";
+```

src/lib/Button/Button.stories.svelte

@@ -1,10 +1,10 @@
 <script context="module">
   import Button from "./Button.svelte";
   import IconDownload from "./IconDownload.svelte";
+  import docs from "./Button.docs.md?raw";
 
   export const meta = {
     title: "Components/Button",
-    description: "A basic button component.",
     component: Button,
     tags: ["autodocs"],
     argTypes: {
@@ -22,7 +22,7 @@
     parameters: {
       docs: {
         description: {
-          component: "Basic HTML Button adhering to Urban styles."
+          component: docs
         }
       },
       githubLink: {

src/lib/ChartBlock/ChartBlock.docs.md

@@ -0,0 +1,5 @@
+A basic wrapper for charts that includes, title, description, source, and notes. The default slot can be used to include any type of content or visualization between the provided text.
+
+```js
+import { ChartBlock } from "@urbaninstitute/dataviz-components";
+```

src/lib/ChartBlock/ChartBlock.stories.svelte

@@ -1,10 +1,10 @@
 <script context="module">
   import ChartBlock from "./ChartBlock.svelte";
   import DatawrapperIframe from "../DatawrapperIframe/DatawrapperIframe.svelte";
+  import docs from "./ChartBlock.docs.md?raw";
 
   export const meta = {
     title: "Components/ChartBlock",
-    description: "A basic wrapper for charts that includes, title, description, source, and notes.",
     component: ChartBlock,
     tags: ["autodocs"],
     argTypes: {
@@ -24,8 +24,7 @@
       },
       docs: {
         description: {
-          component:
-            "A basic wrapper for charts that includes, title, description, source, and notes. The default slot can be used to include any type of content or visualization between the provided text."
+          component: docs
         }
       },
       githubLink: {

src/lib/DatawrapperIframe/DatawrapperIframe.docs.md

@@ -0,0 +1,11 @@
+Datawrapper iframe with [event dispatching](https://developer.datawrapper.de/docs/listening-to-chart-interaction-events) enabled. All interaction events are accessible via `on:eventname` (**no periods**) on the `DatawrapperIframe` Svelte component itself. The complete event list and associated descriptions can be found [here](https://developer.datawrapper.de/docs/listening-to-chart-interaction-events#visualization-events).
+
+Examples of how to setup "switching" between Datawrapper charts with a dropdown or button controls can be found [in the Examples section here](/docs/examples-datawrapper-switching--docs).
+
+In April 2024, the `vis.rendered` event was added to the Datawrapper event list (per the Urban team's request) in order to track when a visualization had been rendered/painted on the page. This is useful if there is a longer loading visualization (like a large map) and you'd like to indicate to the user that the visualization is still loading.
+
+The `startrender` event is available via the component's `beforeUpdate()` function in order to track when the iframe starts to load. This can be combined with the `vis.rendered` event to track when the visualization has been rendered/painted on the page in combination with the [LoadingWrapper](/docs/components-loadingwrapper--docs) component.
+
+```js
+import { DatawrapperIframe } from "@urbaninstitute/dataviz-components";
+```

src/lib/DatawrapperIframe/DatawrapperIframe.stories.svelte

@@ -1,16 +1,15 @@
 <script context="module">
   import DatawrapperIframe from "./DatawrapperIframe.svelte";
+  import docs from "./DatawrapperIframe.docs.md?raw";
 
   export const meta = {
     title: "Components/DatawrapperIframe",
-    description: "Datawrapper iframe",
     component: DatawrapperIframe,
     tags: ["autodocs"],
     parameters: {
       docs: {
         description: {
-          component:
-            "Datawrapper iframe with <a href='https://developer.datawrapper.de/docs/listening-to-chart-interaction-events' target='_blank'>event dispatching</a> enabled. All interaction events are accessible via <code>on:eventname</code> (<b>no periods</b>) on the `DatawrapperIframe` Svelte component itself. The complete event list and associated descriptions can be found <a href='https://developer.datawrapper.de/docs/listening-to-chart-interaction-events#visualization-events' target='_blank'>here</a>.<br/><br/>Examples of how to setup \"switching\" between Datawrapper charts with a dropdown or button controls can be found <a href='/docs/examples-datawrapper-switching--docs'>in the Examples section here</a>.<br/><br/>In April 2024, the <code>vis.rendered</code> event was added to the Datawrapper event list (per the Urban team's request) in order to track when a visualization had been rendered/painted on the page. This is useful if there is a longer loading visualization (like a large map) and you'd like to indicate to the user that the visualization is still loading.<br><br>The `startrender` event is available via the component's `beforeUpdate()` function in order to track when the iframe starts to load. This can be combined with the `vis.rendered` event to track when the visualization has been rendered/painted on the page in combination with the <a href='/docs/components-loadingwrapper--docs' >LoadingWrapper</a> component."
+          component: docs
         }
       },
       githubLink: {

src/lib/Fonts/Fonts.docs.mdx

@@ -10,7 +10,7 @@ If you need to load the Urban brand fonts in your SvelteKit-powered project, you
 
 Import and use either `<FontsUrban />` or `<FontsWorkrise />` to add the necessary markup to the `<head>` of you html like so:
 
-```html
+```svelte
 <script>
   import { FontsUrban } from "@urbaninstitute/dataviz-components/fonts";
 </script>

src/lib/HeadingAlt/HeadingAlt.docs.md

@@ -0,0 +1,5 @@
+Alternate title heading in all caps, useful for h2 tags and lower.
+
+```js
+import { HeadingAlt } from "@urbaninstitute/dataviz-components";
+```

src/lib/HeadingAlt/HeadingAlt.stories.svelte

@@ -1,15 +1,15 @@
 <script context="module">
   import Heading from "./HeadingAlt.svelte";
+  import docs from "./HeadingAlt.docs.md?raw";
 
   export const meta = {
     title: "Components/HeadingAlt",
-    description: "A block for an alternate heading",
     component: Heading,
     tags: ["autodocs"],
     parameters: {
       docs: {
         description: {
-          component: "Alternate title heading in all caps, useful for h2 tags and lower."
+          component: docs
         }
       },
       githubLink: {

src/lib/Headline/Headline.docs.md

@@ -0,0 +1,5 @@
+A basic headline component.
+
+```js
+import { Headline } from "@urbaninstitute/dataviz-components";
+```

src/lib/Headline/Headline.stories.svelte

@@ -1,9 +1,9 @@
 <script context="module">
   import Headline from "./Headline.svelte";
+  import docs from "./Headline.docs.md?raw";
 
   export const meta = {
     title: "Components/Headline",
-    description: "A basic headline",
     component: Headline,
     tags: ["autodocs"],
     argTypes: {
@@ -28,7 +28,7 @@
       },
       docs: {
         description: {
-          component: "A basic headline component."
+          component: docs
         }
       },
       githubLink: {