chore(docs): add docs for dialog component (#5351)

* chore(docs): add docs for dialog component

* update docs for diloag component

documentation-site/components/yard/config/dialog.ts

@@ -0,0 +1,141 @@
+/*
+Copyright (c) Uber Technologies, Inc.
+
+This source code is licensed under the MIT license found in the
+LICENSE file in the root directory of this source tree.
+*/
+import { Dialog, SIZE, PLACEMENT } from "baseui/dialog";
+import { Button, KIND } from "baseui/button";
+import { PropTypes } from "react-view";
+import type { TConfig } from "../types";
+
+const DialogConfig: TConfig = {
+  componentName: "Dialog",
+  imports: {
+    "baseui/dialog": {
+      named: ["Dialog"],
+    },
+    "baseui/button": {
+      named: ["Button", "KIND"],
+    },
+  },
+  scope: {
+    Dialog,
+    SIZE,
+    PLACEMENT,
+    Button,
+    KIND,
+  },
+  theme: [],
+  props: {
+    isOpen: {
+      value: false,
+      type: PropTypes.Boolean,
+      description: "Toggles Dialog visibility.",
+      stateful: true,
+    },
+    artwork: {
+      value: undefined,
+      type: PropTypes.ReactNode,
+      description: "Optional leading icon or content.",
+    },
+    onDismiss: {
+      value: "() => setIsOpen(false);",
+      type: PropTypes.Function,
+      description: "A callback that controls dimissle of the dialog.",
+      propHook: {
+        what: "false",
+        into: "isOpen",
+      },
+    },
+    showDismissButton: {
+      value: true,
+      type: PropTypes.Boolean,
+      description:
+        "Determines whether the dismiss button is shown. Ignored if handleDismiss is null or undefined.",
+    },
+    heading: {
+      value: "Dialog Heading",
+      type: PropTypes.String,
+      description: "The value of the dialog heading.",
+    },
+    buttonDock: {
+      value: `{
+        primaryAction: <Button>Primary Action</Button>,
+        secondaryActions: [
+          <Button kind={KIND.secondary} key="first">
+            Secondary Action
+          </Button>,
+        ],
+      }`,
+      type: PropTypes.Object,
+      description: "Directly exposes the ButttonDock API",
+    },
+    hasOverlay: {
+      value: true,
+      type: PropTypes.Boolean,
+      description: "Determines whether Dialog is presented modally.",
+    },
+    numHeadingLines: {
+      value: 2,
+      defaultValue: 2,
+      type: PropTypes.Number,
+      description:
+        "The maximum number of lines the heading can wrap to before truncation.",
+    },
+    overrides: {
+      value: undefined,
+      type: PropTypes.Custom,
+      description: "Lets you customize all aspects of the component.",
+      custom: {
+        names: [
+          "Root",
+          "ScrollContainer",
+          "Heading",
+          "Body",
+          "ButtonDock",
+          "DismissButton",
+        ],
+        sharedProps: {},
+      },
+    },
+    placement: {
+      value: "PLACEMENT.center",
+      defaultValue: "PLACEMENT.center",
+      options: PLACEMENT,
+      enumName: "PLACEMENT",
+      type: PropTypes.Enum,
+      description: "The position of Dialog relative to the viewport",
+      imports: {
+        "baseui/dialog": {
+          named: ["PLACEMENT"],
+        },
+      },
+    },
+    size: {
+      value: "SIZE.xSmall",
+      defaultValue: "SIZE.xSmall",
+      options: SIZE,
+      enumName: "SIZE",
+      type: PropTypes.Enum,
+      description: "Determines the size of the open Dialog",
+      imports: {
+        "baseui/dialog": {
+          named: ["SIZE"],
+        },
+      },
+    },
+    children: {
+      value: `<p>
+      At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium
+      voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati
+      cupiditate non provident, similique sunt in culpa qui officia deserunt mollitia animi, id
+      est laborum et dolorum fuga. Et harum quidem rerum facilis est et expedita distinctio.
+    </p>`,
+      type: PropTypes.ReactNode,
+      description: "Content of the dialog.",
+    },
+  },
+};
+
+export default DialogConfig;

documentation-site/examples/dialog/images/index.d.ts

@@ -0,0 +1,10 @@
+/*
+Copyright (c) Uber Technologies, Inc.
+
+This source code is licensed under the MIT license found in the
+LICENSE file in the root directory of this source tree.
+*/
+declare module "*.jpg" {
+  const content: string;
+  export default content;
+}

documentation-site/examples/dialog/with-background-image.tsx

@@ -0,0 +1,65 @@
+import * as React from "react";
+import { Dialog, SIZE } from "baseui/dialog";
+import { Button, KIND } from "baseui/button";
+import veniceJpg from "./images/venice.jpg";
+
+const BackgroundArtwork: React.FC = () => (
+  <div
+    style={{
+      width: "100%",
+      height: "200px",
+      backgroundImage: `url(${veniceJpg})`,
+      backgroundSize: "cover",
+      backgroundPosition: "center",
+    }}
+  ></div>
+);
+
+export default function Example() {
+  const [isOpen, setIsOpen] = React.useState(false);
+  return (
+    <div>
+      <div>
+        <Button
+          onClick={() => {
+            setIsOpen(!isOpen);
+          }}
+        >
+          Open
+        </Button>
+      </div>
+      <Dialog
+        artwork={BackgroundArtwork}
+        heading="Heading"
+        size={SIZE.medium}
+        hasOverlay={true}
+        isOpen={isOpen}
+        onDismiss={() => setIsOpen(false)}
+        buttonDock={{
+          primaryAction: <Button>Primary Action</Button>,
+          dismissiveAction: (
+            <Button onClick={() => setIsOpen(false)} kind={KIND.tertiary}>
+              Dismiss
+            </Button>
+          ),
+          secondaryActions: [
+            <Button kind={KIND.secondary} key="first">
+              Secondary Action
+            </Button>,
+          ],
+        }}
+      >
+        <p>
+          Nam libero tempore, cum soluta nobis est eligendi optio cumque nihil
+          impedit quo minus id quod maxime placeat facere possimus, omnis
+          voluptas assumenda est, omnis dolor repellendus. Temporibus autem
+          quibusdam et aut officiis debitis aut rerum necessitatibus saepe
+          eveniet ut et voluptates repudiandae sint et molestiae non recusandae.
+          Itaque earum rerum hic tenetur a sapiente delectus, ut aut reiciendis
+          voluptatibus maiores alias consequatur aut perferendis doloribus
+          asperiores repellat.
+        </p>
+      </Dialog>
+    </div>
+  );
+}

documentation-site/examples/dialog/without-overlay.tsx

@@ -0,0 +1,45 @@
+import * as React from "react";
+import { Dialog, SIZE } from "baseui/dialog";
+import { Button, KIND } from "baseui/button";
+
+export default function Example() {
+  const [isOpen, setIsOpen] = React.useState(false);
+  return (
+    <div>
+      <div>
+        <Button
+          onClick={() => {
+            setIsOpen(!isOpen);
+          }}
+        >
+          Open
+        </Button>
+      </div>
+      <Dialog
+        heading="This is the heading"
+        numHeadingLines={1}
+        size={SIZE.medium}
+        hasOverlay={false}
+        isOpen={isOpen}
+        onDismiss={() => setIsOpen(false)}
+        buttonDock={{
+          primaryAction: <Button>Primary Action</Button>,
+          dismissiveAction: <Button kind={KIND.tertiary}>Dismiss</Button>,
+          secondaryActions: [
+            <Button kind={KIND.secondary} key="first">
+              Secondary Action
+            </Button>,
+          ],
+        }}
+      >
+        <p>
+          At vero eos et accusamus et iusto odio dignissimos ducimus qui
+          blanditiis praesentium voluptatum deleniti atque corrupti quos dolores
+          et quas molestias excepturi sint occaecati cupiditate non provident,
+          similique sunt in culpa qui officia deserunt mollitia animi, id est
+          laborum et dolorum fuga.
+        </p>
+      </Dialog>
+    </div>
+  );
+}

documentation-site/pages/components/dialog.mdx

@@ -0,0 +1,44 @@
+import Example from "../../components/example";
+import Exports from "../../components/exports";
+import Layout from "../../components/layout";
+
+import WithoutOverlay from "examples/dialog/without-overlay.tsx";
+import WithBackgroundImage from "examples/dialog/with-background-image.tsx";
+
+import { Dialog, SIZE, PLACEMENT, CLOSE_KIND } from "baseui/dialog";
+import * as DialogExports from "baseui/dialog";
+
+import Yard from "../../components/yard/index";
+import dialogYardConfig from "../../components/yard/config/dialog";
+
+export default Layout;
+
+# Dialog
+
+<Yard placeholderHeight={52} {...dialogYardConfig} />
+
+A dialog is a container that floats on top of another surface. Dialogs focus a user's attention on a single-step task, question, or message.
+
+Dialogs can be presented both modally (i.e. accompanied by a grayed out background) and nonmodally (akin to a popup).
+
+When the content of the dialog is longer than the available vertical space, the body content and artwork will scroll internally, leaving the heading stuck to the top and the button dock unaffected.
+
+## Examples
+
+<Example title="Non-modal dialog" path="dialog/without-overlay.tsx">
+  <WithoutOverlay />
+</Example>
+
+By default, Dialog is presented with an overlay that grays out the background content. When `hasOverlay` is false, Dialog will be presented without the overlay, and will function as more of a popup than a modal.
+
+<Example title="Artwork" path="dialog/with-background-image.tsx">
+  <WithBackgroundImage />
+</Example>
+
+The `artwork` prop can accommodate a react component or a rendered element. In this example, the artwork is decorative, so we use the `background-image` css property. If the artwork has semantic meaning, it is appropriate to use an img element.
+
+<Exports
+  component={DialogExports}
+  title="Dialog exports"
+  path="baseui/dialog"
+/>

documentation-site/routes.jsx

@@ -358,6 +358,10 @@ const routes = [
             title: "Card",
             itemId: "/components/card",
           },
+          {
+            title: "Dialog",
+            itemId: "/components/dialog",
+          },
           {
             title: "Drawer",
             itemId: "/components/drawer",