docs(summary-detail): add website documentation (#3760)

* docs(summary-detail): add website documentation * chore: fixes * fix: pr review fixes * fix: pr review fixes
twilio-labs · Feb 7, 2024 · 478a15a · 478a15a
1 parent 336066b
commit 478a15a
Show file tree

Hide file tree

Showing 7 changed files with 343 additions and 0 deletions.
diff --git a/cypress/integration/sitemap-vrt/constants.ts b/cypress/integration/sitemap-vrt/constants.ts
@@ -203,6 +203,9 @@ export const SITEMAP = [
   "/components/slider/",
   "/components/slider/api",
   "/components/slider/changelog",
+  "/components/summary-detail/",
+  "/components/summary-detail/api",
+  "/components/summary-detail/changelog",
   "/components/switch/",
   "/components/switch/api",
   "/components/switch/changelog",

diff --git a/packages/paste-core/components/summary-detail/stories/index.stories.tsx b/packages/paste-core/components/summary-detail/stories/index.stories.tsx
@@ -1,4 +1,5 @@
 import type { StoryFn } from "@storybook/react";
+import { Anchor } from "@twilio-paste/anchor";
 import { Box } from "@twilio-paste/box";
 import { Card } from "@twilio-paste/card";
 import { Paragraph } from "@twilio-paste/paragraph";
@@ -32,6 +33,9 @@ export const Default: StoryFn = () => {
           </Text>
           <Text as="p" fontSize="fontSize20" fontWeight="fontWeightLight">
             Jan 11, 2023
+            <Anchor href="#" marginLeft="space30">
+              (View transcript)
+            </Anchor>
           </Text>
         </SummaryDetailHeadingContent>
       </SummaryDetailHeading>

diff --git a/packages/paste-website/package.json b/packages/paste-website/package.json
@@ -117,6 +117,7 @@
     "@twilio-paste/status": "^2.1.1",
     "@twilio-paste/style-props": "^9.1.1",
     "@twilio-paste/styling-library": "^3.0.0",
+    "@twilio-paste/summary-detail": "^1.0.0",
     "@twilio-paste/switch": "^5.1.1",
     "@twilio-paste/syntax-highlighter-library": "^3.0.0",
     "@twilio-paste/table": "^8.2.0",

diff --git a/packages/paste-website/src/pages/components/summary-detail/api.mdx b/packages/paste-website/src/pages/components/summary-detail/api.mdx
@@ -0,0 +1,76 @@
+export const meta = {
+  title: 'Summary Detail - Components - API',
+  description:
+    'A Summary Detail is a collapsible container that can be used to hide or show content.',
+  slug: '/components/summary-detail/api',
+};
+
+import Changelog from '@twilio-paste/summary-detail/CHANGELOG.md'; // I don't know why this is needed but if you remove it the page fails to render
+import packageJson from '@twilio-paste/summary-detail/package.json';
+
+import {SidebarCategoryRoutes} from '../../../constants';
+import ComponentPageLayout from '../../../layouts/ComponentPageLayout';
+import {getFeature, getNavigationData, getComponentApi} from '../../../utils/api';
+
+export default ComponentPageLayout;
+
+export const getStaticProps = async () => {
+  const navigationData = await getNavigationData();
+  const feature = await getFeature('Summary Detail');
+  const {componentApi, componentApiTocData} = getComponentApi('@twilio-paste/summary-detail');
+  return {
+    props: {
+      data: {
+        ...packageJson,
+        ...feature,
+      },
+      componentApi,
+      mdxHeadings: [...mdxHeadings, ...componentApiTocData],
+      navigationData,
+      pageHeaderData: {
+        categoryRoute: SidebarCategoryRoutes.COMPONENTS,
+        githubUrl: 'https://github.com/twilio-labs/paste/tree/main/packages/paste-core/components/summary-detail',
+        storybookUrl: '/?path=/story/components-summarydetail--default',
+      },
+    },
+  };
+};
+
+## Installation
+
+```bash
+yarn add @twilio-paste/summary-detail - or - yarn add @twilio-paste/core
+```
+
+## Usage
+
+```jsx
+import {
+  SummaryDetail,
+  SummaryDetailContent,
+  SummaryDetailHeading,
+  SummaryDetailHeadingContent,
+  SummaryDetailToggleButton,
+} from '@twilio-paste/core/summary-detail';
+import {Text} from '@twilio-paste/core/text';
+
+const SummaryDetailExample = () => {
+  return (
+    <SummaryDetail>
+      <SummaryDetailHeading>
+        <SummaryDetailToggleButton />
+        <SummaryDetailHeadingContent>
+            Inbound Call
+        </SummaryDetailHeadingContent>
+      </SummaryDetailHeading>
+      <SummaryDetailContent>
+        <Text as="p">This is the content of the summary detail.</Text>
+      </SummaryDetailContent>
+    </SummaryDetail>
+  );
+};
+```
+
+## Props
+
+<PropsTable componentApi={props.componentApi} />
diff --git a/packages/paste-website/src/pages/components/summary-detail/changelog.mdx b/packages/paste-website/src/pages/components/summary-detail/changelog.mdx
@@ -0,0 +1,37 @@
+export const meta = {
+  title: 'Summary Detail - Components - Changelog',
+  description:
+    'A Summary Detail is a collapsible container that can be used to hide or show content.',
+  slug: '/components/summary-detail/changelog',
+};
+
+import Changelog from '@twilio-paste/summary-detail/CHANGELOG.md';
+import packageJson from '@twilio-paste/summary-detail/package.json';
+
+import {SidebarCategoryRoutes} from '../../../constants';
+import ComponentPageLayout from '../../../layouts/ComponentPageLayout';
+import {getFeature, getNavigationData} from '../../../utils/api';
+
+export default ComponentPageLayout;
+
+export const getStaticProps = async () => {
+  const navigationData = await getNavigationData();
+  const feature = await getFeature('Summary Detail');
+  return {
+    props: {
+      data: {
+        ...packageJson,
+        ...feature,
+      },
+      navigationData,
+      mdxHeadings,
+      pageHeaderData: {
+        categoryRoute: SidebarCategoryRoutes.COMPONENTS,
+        githubUrl: 'https://github.com/twilio-labs/paste/tree/main/packages/paste-core/components/summary-detail',
+        storybookUrl: '/?path=/story/components-summarydetail--default',
+      },
+    },
+  };
+};
+
+<Changelog />
diff --git a/packages/paste-website/src/pages/components/summary-detail/index.mdx b/packages/paste-website/src/pages/components/summary-detail/index.mdx
@@ -0,0 +1,221 @@
+export const meta = {
+  title: 'Summary Detail - Components',
+  description:
+    'A Summary Detail is a collapsible container that can be used to hide or show content.',
+  slug: '/components/summary-detail',
+};
+
+import {Anchor} from '@twilio-paste/anchor';
+import {Avatar} from '@twilio-paste/avatar';
+import {Box} from '@twilio-paste/box';
+import {Button} from '@twilio-paste/button';
+import {Card} from '@twilio-paste/card';
+import {Heading} from '@twilio-paste/heading';
+import {Paragraph} from '@twilio-paste/paragraph';
+import {SummaryDetail} from '@twilio-paste/summary-detail';
+import {Stack} from '@twilio-paste/stack';
+import {Table, THead, TBody, Tr, Td, Th} from '@twilio-paste/table';
+import {Text} from '@twilio-paste/text';
+import {CalendarIcon} from '@twilio-paste/icons/esm/CalendarIcon';
+import packageJson from '@twilio-paste/summary-detail/package.json';
+import {SidebarCategoryRoutes} from '../../../constants';
+import ComponentPageLayout from '../../../layouts/ComponentPageLayout';
+import {getFeature, getNavigationData} from '../../../utils/api';
+
+export default ComponentPageLayout;
+
+export const getStaticProps = async () => {
+  const navigationData = await getNavigationData();
+  const feature = await getFeature('Summary Detail');
+  return {
+    props: {
+      data: {
+        ...packageJson,
+        ...feature,
+      },
+      navigationData,
+      mdxHeadings,
+      pageHeaderData: {
+        categoryRoute: SidebarCategoryRoutes.COMPONENTS,
+        githubUrl: 'https://github.com/twilio-labs/paste/tree/main/packages/paste-core/components/summary-detail',
+        storybookUrl: '/?path=/story/components-summarydetail--default',
+      },
+    },
+  };
+};
+
+
+<StoryPreview
+  title="Standard Summary Detail"
+  storyID="components-summarydetail--default"
+  height="200px"
+  code={`
+<SummaryDetail>
+  <SummaryDetailHeading>
+    <SummaryDetailToggleButton aria-label="BOOP" />
+    <SummaryDetailHeadingContent>
+      <Text as="p" fontWeight="fontWeightBold">
+        Inbound Call
+      </Text>
+      <Text as="p" fontSize="fontSize20" fontWeight="fontWeightLight">
+        Jan 11, 2023
+        <Anchor href="#" marginLeft="space30">
+          (View transcript)
+        </Anchor>
+      </Text>
+    </SummaryDetailHeadingContent>
+  </SummaryDetailHeading>
+  <SummaryDetailContent>
+    <Text as="strong">Agent: </Text>
+    <Text as="span">John Doe</Text>
+    <Text as="span" marginX="space40" color="colorTextWeaker">
+      |
+    </Text>
+    <Text as="strong">Duration: </Text>
+    <Text as="span">3m 14s</Text>
+  </SummaryDetailContent>
+</SummaryDetail>`}
+/>
+
+## Guidelines
+
+### About Summary Detail
+
+The Summary Detail component displays a summary of information that can be expanded to show more information.
+It can be used when you need more click targets and actions in a Disclosure Heading.
+
+
+### Accessibility
+
+- Only the toggle button is tabbable and clickable to reveal the content.
+- The toggle button is labelled by the `SummaryDetailHeadingContent` component.
+  - If the heading content is unclear or too verbose, you can provide an `aria-label` to `SummaryDetailToggleButton` directly to enable a more descriptive label.
+
+## Examples
+
+### Basic usage
+
+This example shows how you can compose the [Text component](/primitives/text) to compose a
+basic Summary Detail.
+
+<StoryPreview
+  title="Standard Summary Detail"
+  storyID="components-summarydetail--default"
+  height="200px"
+  code={`
+<SummaryDetail>
+  <SummaryDetailHeading>
+    <SummaryDetailToggleButton aria-label="BOOP" />
+    <SummaryDetailHeadingContent>
+      <Text as="p" fontWeight="fontWeightBold">
+        Inbound Call
+      </Text>
+      <Text as="p" fontSize="fontSize20" fontWeight="fontWeightLight">
+        Jan 11, 2023
+        <Anchor href="#" marginLeft="space30">
+          (View transcript)
+        </Anchor>
+      </Text>
+    </SummaryDetailHeadingContent>
+  </SummaryDetailHeading>
+  <SummaryDetailContent>
+    <Text as="strong">Agent: </Text>
+    <Text as="span">John Doe</Text>
+    <Text as="span" marginX="space40" color="colorTextWeaker">
+      |
+    </Text>
+    <Text as="strong">Duration: </Text>
+    <Text as="span">3m 14s</Text>
+  </SummaryDetailContent>
+</SummaryDetail>`}
+/>
+
+### Open by default
+
+You can set the content to be visible by default with the `visible` prop.
+
+<StoryPreview
+  title="Open by default Summary Detail"
+  storyID="components-summarydetail--open-by-default"
+  height="200px"
+  code={`
+<SummaryDetail visible>
+  <SummaryDetailHeading>
+    <SummaryDetailToggleButton aria-label="BOOP" />
+    <SummaryDetailHeadingContent>
+      <Text as="p" fontWeight="fontWeightBold">
+        Inbound Call
+      </Text>
+      <Text as="p" fontSize="fontSize20" fontWeight="fontWeightLight">
+        Jan 11, 2023
+      </Text>
+    </SummaryDetailHeadingContent>
+  </SummaryDetailHeading>
+  <SummaryDetailContent>
+    <Text as="strong">Agent: </Text>
+    <Text as="span">John Doe</Text>
+    <Text as="span" marginX="space40" color="colorTextWeaker">
+      |
+    </Text>
+    <Text as="strong">Duration: </Text>
+    <Text as="span">3m 14s</Text>
+  </SummaryDetailContent>
+</SummaryDetail>`}
+/>
+
+### State hook
+
+You can control the internal behavior of the Summary Detail component by way of [inversion of control](https://kentcdodds.com/blog/inversion-of-control).
+This is useful for when you want to control the visibility of the Summary Detail component from a parent component.
+
+<StoryPreview
+  title="State hook example"
+  storyID="components-summarydetail--state-hook"
+  height="300px"
+  code={`const useDelayedSummaryDetailState = ({
+  delay,
+  ...initialState
+}) => {
+  const disclosure = useSummaryDetailState(initialState);
+  const [transitioning, setTransitioning] = React.useState(false);
+  return {
+    ...disclosure,
+    transitioning,
+    toggle: () => {
+      setTransitioning(true);
+      setTimeout(() => {
+        disclosure.toggle();
+        setTransitioning(false);
+      }, delay);
+    },
+  };
+};
+const StateHook = () => {
+  const { transitioning, ...summaryDetailState } = useDelayedSummaryDetailState({
+    delay: 500,
+  });
+  const clickableHeading = summaryDetailState.visible ? "Hide with delay" : "Show with delay";
+  return (
+    <>
+      <Paragraph>This Disclosure should be visible on load, and take 1 second to open and close.</Paragraph>
+      <SummaryDetail state={summaryDetailState}>
+        <SummaryDetailHeading>
+          <SummaryDetailToggleButton />
+          <SummaryDetailHeadingContent>
+            {transitioning ? "Please wait..." : clickableHeading}
+          </SummaryDetailHeadingContent>
+        </SummaryDetailHeading>
+        <SummaryDetailContent>
+          <Text as="strong">Agent: </Text>
+          <Text as="span">John Doe</Text>
+          <Text as="span" marginX="space40" color="colorTextWeaker">
+            |
+          </Text>
+          <Text as="strong">Duration: </Text>
+          <Text as="span">3m 14s</Text>
+        </SummaryDetailContent>
+      </SummaryDetail>
+    </>
+  );
+};`}
+/>
diff --git a/yarn.lock b/yarn.lock
@@ -15827,6 +15827,7 @@ __metadata:
     "@twilio-paste/status": ^2.1.1
     "@twilio-paste/style-props": ^9.1.1
     "@twilio-paste/styling-library": ^3.0.0
+    "@twilio-paste/summary-detail": ^1.0.0
     "@twilio-paste/switch": ^5.1.1
     "@twilio-paste/syntax-highlighter-library": ^3.0.0
     "@twilio-paste/table": ^8.2.0