@khanacademy/wonder-blocks-modal 3.0.6 → 3.0.8

package/dist/components/modal-header.d.ts

@@ -0,0 +1,93 @@
+import * as React from "react";
+import { Breadcrumbs } from "@khanacademy/wonder-blocks-breadcrumbs";
+type Common = {
+    /**
+     * The main title rendered in larger bold text.
+     */
+    title: string;
+    /**
+     * Whether to display the "light" version of this component instead, for
+     * use when the item is used on a dark background.
+     */
+    light: boolean;
+    /**
+     * An id to provide a selector for the title element.
+     */
+    titleId: string;
+    /**
+     * Test ID used for e2e testing.
+     *
+     * In this case, this component is internal, so `testId` is composed with
+     * the `testId` passed down from the Dialog variant + a suffix to scope it
+     * to this component.
+     *
+     * @example
+     * For testId="some-random-id"
+     * The result will be: `some-random-id-modal-header`
+     */
+    testId?: string;
+};
+type WithSubtitle = Common & {
+    /**
+     * The dialog subtitle.
+     */
+    subtitle: string;
+};
+type WithBreadcrumbs = Common & {
+    /**
+     * Adds a breadcrumb-trail, appearing in the ModalHeader, above the title.
+     */
+    breadcrumbs: React.ReactElement<React.ComponentProps<typeof Breadcrumbs>>;
+};
+type Props = Common | WithSubtitle | WithBreadcrumbs;
+type DefaultProps = {
+    light: Props["light"];
+};
+/**
+ * This is a helper component that is never rendered by itself. It is always
+ * pinned to the top of the dialog, is responsive using the same behavior as its
+ * parent dialog, and has the following properties:
+ * - title
+ * - breadcrumb OR subtitle, but not both.
+ *
+ * **Accessibility notes:**
+ *
+ * - By default (e.g. using [OnePaneDialog](/#onepanedialog)), `titleId` is
+ *   populated automatically by the parent container.
+ * - If there is a custom Dialog implementation (e.g. `TwoPaneDialog`), the
+ *   ModalHeader doesn’t have to have the `titleId` prop however this is
+ *   recommended. It should match the `aria-labelledby` prop of the
+ *   [ModalDialog](/#modaldialog) component. If you want to see an example of
+ *   how to generate this ID, check [IDProvider](/#idprovider).
+ *
+ * **Implementation notes:**
+ *
+ * If you are creating a custom Dialog, make sure to follow these guidelines:
+ * - Make sure to include it as part of [ModalPanel](/#modalpanel) by using the
+ *   `header` prop.
+ * - Add a title (required).
+ * - Optionally add a subtitle or breadcrumbs.
+ * - We encourage you to add `titleId` (see Accessibility notes).
+ * - If the `ModalPanel` has a dark background, make sure to set `light` to
+ *   `false`.
+ * - If you need to create e2e tests, make sure to pass a `testId` prop and
+ *   add a sufix to scope the testId to this component: e.g.
+ *   `some-random-id-ModalHeader`. This scope will also be passed to the title
+ *   and subtitle elements: e.g. `some-random-id-ModalHeader-title`.
+ *
+ * Example:
+ *
+ * ```js
+ * <ModalHeader
+ *      title="Sidebar using ModalHeader"
+ *      subtitle="subtitle"
+ *      titleId="uniqueTitleId"
+ *      light={false}
+ *  />
+ * ```
+ */
+export default class ModalHeader extends React.Component<Props> {
+    static defaultProps: DefaultProps;
+    render(): React.ReactElement;
+}
+export {};

package/dist/components/modal-header.js.flow

@@ -0,0 +1,110 @@
+/**
+ * Flowtype definitions for modal-header
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import * as React from "react";
+import { Breadcrumbs } from "@khanacademy/wonder-blocks-breadcrumbs";
+declare type Common = {
+  /**
+   * The main title rendered in larger bold text.
+   */
+  title: string,
+
+  /**
+   * Whether to display the "light" version of this component instead, for
+   * use when the item is used on a dark background.
+   */
+  light: boolean,
+
+  /**
+   * An id to provide a selector for the title element.
+   */
+  titleId: string,
+
+  /**
+   * Test ID used for e2e testing.
+   *
+   * In this case, this component is internal, so `testId` is composed with
+   * the `testId` passed down from the Dialog variant + a suffix to scope it
+   * to this component.
+   * @example For testId="some-random-id"
+   * The result will be: `some-random-id-modal-header`
+   */
+  testId?: string,
+  ...
+};
+declare type WithSubtitle = {
+  ...Common,
+  ...{
+    /**
+     * The dialog subtitle.
+     */
+    subtitle: string,
+    ...
+  },
+};
+declare type WithBreadcrumbs = {
+  ...Common,
+  ...{
+    /**
+     * Adds a breadcrumb-trail, appearing in the ModalHeader, above the title.
+     */
+    breadcrumbs: React.Element<React.ComponentProps<typeof Breadcrumbs>>,
+    ...
+  },
+};
+declare type Props = Common | WithSubtitle | WithBreadcrumbs;
+declare type DefaultProps = {
+  light: $PropertyType<Props, "light">,
+  ...
+};
+/**
+ * This is a helper component that is never rendered by itself. It is always
+ * pinned to the top of the dialog, is responsive using the same behavior as its
+ * parent dialog, and has the following properties:
+ * - title
+ * - breadcrumb OR subtitle, but not both.
+ *
+ * **Accessibility notes:**
+ *
+ * - By default (e.g. using [OnePaneDialog](/#onepanedialog)), `titleId` is
+ *   populated automatically by the parent container.
+ * - If there is a custom Dialog implementation (e.g. `TwoPaneDialog`), the
+ *   ModalHeader doesn’t have to have the `titleId` prop however this is
+ *   recommended. It should match the `aria-labelledby` prop of the
+ *   [ModalDialog](/#modaldialog) component. If you want to see an example of
+ *   how to generate this ID, check [IDProvider](/#idprovider).
+ *
+ * **Implementation notes:**
+ *
+ * If you are creating a custom Dialog, make sure to follow these guidelines:
+ * - Make sure to include it as part of [ModalPanel](/#modalpanel) by using the
+ *   `header` prop.
+ * - Add a title (required).
+ * - Optionally add a subtitle or breadcrumbs.
+ * - We encourage you to add `titleId` (see Accessibility notes).
+ * - If the `ModalPanel` has a dark background, make sure to set `light` to
+ *   `false`.
+ * - If you need to create e2e tests, make sure to pass a `testId` prop and
+ *   add a sufix to scope the testId to this component: e.g.
+ *   `some-random-id-ModalHeader`. This scope will also be passed to the title
+ *   and subtitle elements: e.g. `some-random-id-ModalHeader-title`.
+ *
+ * Example:
+ *
+ * ```js
+ * <ModalHeader
+ *      title="Sidebar using ModalHeader"
+ *      subtitle="subtitle"
+ *      titleId="uniqueTitleId"
+ *      light={false}
+ *  />
+ * ```
+ */
+declare export default class ModalHeader mixins React.Component<Props> {
+  static defaultProps: DefaultProps;
+  render(): React.Element<>;
+}

package/dist/components/modal-launcher.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+import type { ModalElement } from "../util/types";
+declare const _default: React.ForwardRefExoticComponent<{
+    children?: ((arg1: {
+        openModal: () => unknown;
+    }) => React.ReactNode) | undefined;
+    onClose?: (() => unknown) | undefined;
+    testId?: string | undefined;
+    initialFocusId?: string | undefined;
+    backdropDismissEnabled?: boolean | undefined;
+    opened?: boolean | undefined;
+    modal: ModalElement | React.FC<{
+        closeModal: () => void;
+    }>;
+    closedFocusId?: string | undefined;
+} & React.RefAttributes<unknown>>;
+export default _default;

package/dist/components/modal-launcher.js.flow

@@ -0,0 +1,34 @@
+/**
+ * Flowtype definitions for modal-launcher
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import * as React from "react";
+import type { ModalElement } from "../util/types";
+declare var _default: React.ForwardRefExoticComponent<{
+  ...{
+    children?:
+      | ((arg1: {
+          openModal: () => mixed,
+          ...
+        }) => React.Node)
+      | void,
+    onClose?: (() => mixed) | void,
+    testId?: string | void,
+    initialFocusId?: string | void,
+    backdropDismissEnabled?: boolean | void,
+    opened?: boolean | void,
+    modal:
+      | ModalElement
+      | React.FC<{
+          closeModal: () => void,
+          ...
+        }>,
+    closedFocusId?: string | void,
+    ...
+  },
+  ...React.RefAttributes<mixed>,
+}>;
+declare export default typeof _default;

package/dist/components/modal-panel.d.ts

@@ -0,0 +1,84 @@
+import * as React from "react";
+import type { StyleType } from "@khanacademy/wonder-blocks-core";
+import ModalContent from "./modal-content";
+import ModalHeader from "./modal-header";
+import ModalFooter from "./modal-footer";
+type Props = {
+    /**
+     * The main contents of the ModalPanel. All other parts of the panel
+     * are positioned around it.
+     */
+    content: React.ReactElement<React.ComponentProps<typeof ModalContent>> | React.ReactNode;
+    /**
+     * The modal header to show at the top of the panel.
+     */
+    header?: React.ReactElement<React.ComponentProps<typeof ModalHeader>> | React.ReactNode;
+    /**
+     * A footer to show beneath the contents.
+     */
+    footer?: React.ReactElement<React.ComponentProps<typeof ModalFooter>> | React.ReactNode;
+    /**
+     * When true, the close button is shown; otherwise, the close button is not shown.
+     */
+    closeButtonVisible: boolean;
+    /**
+     * Should the contents of the panel become scrollable should they
+     * become too tall?
+     */
+    scrollOverflow: boolean;
+    /**
+     * Whether to display the "light" version of this component instead, for
+     * use when the item is used on a dark background.
+     */
+    light: boolean;
+    /**
+     * Any optional styling to apply to the panel.
+     */
+    style?: StyleType;
+    /**
+     * Called when the close button is clicked.
+     *
+     * If you're using `ModalLauncher`, you should not use this prop!
+     * Instead, to listen for when the modal closes, add an `onClose` handler
+     * to the `ModalLauncher`.  Doing so will throw an error.
+     */
+    onClose?: () => unknown;
+    /**
+     * Test ID used for e2e testing.
+     *
+     * In this case, this `testId` comes from the `testId` prop defined in the
+     * Dialog variant (e.g. OnePaneDialog).
+     */
+    testId?: string;
+};
+type DefaultProps = {
+    closeButtonVisible: Props["closeButtonVisible"];
+    scrollOverflow: Props["scrollOverflow"];
+    light: Props["light"];
+};
+/**
+ * ModalPanel is  the content container.
+ *
+ * **Implementation notes:**
+ *
+ * If you are creating a custom Dialog, make sure to follow these guidelines:
+ * - Make sure to add this component inside the [ModalDialog](/#modaldialog).
+ * - If needed, you can also add a [ModalHeader](/#modalheader) using the
+ *   `header` prop. Same goes for [ModalFooter](/#modalfooter).
+ * - If you need to create e2e tests, make sure to pass a `testId` prop. This
+ *   will be passed down to this component using a sufix: e.g.
+ *   `some-random-id-ModalPanel`. This scope will be propagated to the
+ *   CloseButton element as well: e.g. `some-random-id-CloseButton`.
+ *
+ * ```js
+ * <ModalDialog>
+ *      <ModalPanel content={"custom content goes here"} />
+ * </ModalDialog>
+ * ```
+ */
+export default class ModalPanel extends React.Component<Props> {
+    static defaultProps: DefaultProps;
+    renderMainContent(): React.ReactNode;
+    render(): React.ReactElement;
+}
+export {};

package/dist/components/modal-panel.js.flow

@@ -0,0 +1,102 @@
+/**
+ * Flowtype definitions for modal-panel
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import * as React from "react";
+import type { StyleType } from "@khanacademy/wonder-blocks-core";
+import ModalContent from "./modal-content";
+import ModalHeader from "./modal-header";
+import ModalFooter from "./modal-footer";
+declare type Props = {
+  /**
+   * The main contents of the ModalPanel. All other parts of the panel
+   * are positioned around it.
+   */
+  content:
+    | React.Element<React.ComponentProps<typeof ModalContent>>
+    | React.Node,
+
+  /**
+   * The modal header to show at the top of the panel.
+   */
+  header?: React.Element<React.ComponentProps<typeof ModalHeader>> | React.Node,
+
+  /**
+   * A footer to show beneath the contents.
+   */
+  footer?: React.Element<React.ComponentProps<typeof ModalFooter>> | React.Node,
+
+  /**
+   * When true, the close button is shown; otherwise, the close button is not shown.
+   */
+  closeButtonVisible: boolean,
+
+  /**
+   * Should the contents of the panel become scrollable should they
+   * become too tall?
+   */
+  scrollOverflow: boolean,
+
+  /**
+   * Whether to display the "light" version of this component instead, for
+   * use when the item is used on a dark background.
+   */
+  light: boolean,
+
+  /**
+   * Any optional styling to apply to the panel.
+   */
+  style?: StyleType,
+
+  /**
+   * Called when the close button is clicked.
+   *
+   * If you're using `ModalLauncher`, you should not use this prop!
+   * Instead, to listen for when the modal closes, add an `onClose` handler
+   * to the `ModalLauncher`.  Doing so will throw an error.
+   */
+  onClose?: () => mixed,
+
+  /**
+   * Test ID used for e2e testing.
+   *
+   * In this case, this `testId` comes from the `testId` prop defined in the
+   * Dialog variant (e.g. OnePaneDialog).
+   */
+  testId?: string,
+  ...
+};
+declare type DefaultProps = {
+  closeButtonVisible: $PropertyType<Props, "closeButtonVisible">,
+  scrollOverflow: $PropertyType<Props, "scrollOverflow">,
+  light: $PropertyType<Props, "light">,
+  ...
+};
+/**
+ * ModalPanel is  the content container.
+ *
+ * **Implementation notes:**
+ *
+ * If you are creating a custom Dialog, make sure to follow these guidelines:
+ * - Make sure to add this component inside the [ModalDialog](/#modaldialog).
+ * - If needed, you can also add a [ModalHeader](/#modalheader) using the
+ *   `header` prop. Same goes for [ModalFooter](/#modalfooter).
+ * - If you need to create e2e tests, make sure to pass a `testId` prop. This
+ *   will be passed down to this component using a sufix: e.g.
+ *   `some-random-id-ModalPanel`. This scope will be propagated to the
+ *   CloseButton element as well: e.g. `some-random-id-CloseButton`.
+ *
+ * ```js
+ * <ModalDialog>
+ *      <ModalPanel content={"custom content goes here"} />
+ * </ModalDialog>
+ * ```
+ */
+declare export default class ModalPanel mixins React.Component<Props> {
+  static defaultProps: DefaultProps;
+  renderMainContent(): React.Node;
+  render(): React.Element<>;
+}

package/dist/components/one-pane-dialog.d.ts

@@ -0,0 +1,124 @@
+import * as React from "react";
+import { Breadcrumbs } from "@khanacademy/wonder-blocks-breadcrumbs";
+import type { StyleType } from "@khanacademy/wonder-blocks-core";
+import ModalHeader from "./modal-header";
+type Common = {
+    /**
+     * The content of the modal, appearing between the titlebar and footer.
+     */
+    content: React.ReactNode;
+    /**
+     * The title of the modal, appearing in the titlebar.
+     */
+    title: string;
+    /**
+     * The content of the modal's footer. A great place for buttons!
+     *
+     * Content is right-aligned by default. To control alignment yourself,
+     * provide a container element with 100% width.
+     */
+    footer?: React.ReactNode;
+    /**
+     * Called when the close button is clicked.
+     *
+     * If you're using `ModalLauncher`, you probably shouldn't use this prop!
+     * Instead, to listen for when the modal closes, add an `onClose` handler
+     * to the `ModalLauncher`.  Doing so will result in a console.warn().
+     */
+    onClose?: () => unknown;
+    /**
+     * When true, the close button is shown; otherwise, the close button is not shown.
+     */
+    closeButtonVisible?: boolean;
+    /**
+     * When set, provides a component that can render content above the top of the modal;
+     * when not set, no additional content is shown above the modal.
+     * This prop is passed down to the ModalDialog.
+     */
+    above?: React.ReactNode;
+    /**
+     * When set, provides a component that will render content below the bottom of the modal;
+     * when not set, no additional content is shown below the modal.
+     * This prop is passed down to the ModalDialog.
+     *
+     * NOTE: Devs can customize this content by rendering the component assigned to this prop with custom styles,
+     * such as by wrapping it in a View.
+     */
+    below?: React.ReactNode;
+    /**
+     * When set, overrides the default role value. Default role is "dialog"
+     * Roles other than dialog and alertdialog aren't appropriate for this
+     * component
+     */
+    role?: "dialog" | "alertdialog";
+    /**
+     * Optional custom styles.
+     */
+    style?: StyleType;
+    /**
+     * Test ID used for e2e testing. This ID will be passed down to the Dialog.
+     */
+    testId?: string;
+    /**
+     * An optional id parameter for the title. If one is
+     * not provided, a unique id will be generated.
+     */
+    titleId?: string;
+    /**
+     * The ID of the content describing this dialog, if applicable.
+     */
+    ["aria-describedby"]?: string;
+};
+type WithSubtitle = Common & {
+    /**
+     * The subtitle of the modal, appearing in the titlebar, below the title.
+     */
+    subtitle: string;
+};
+type WithBreadcrumbs = Common & {
+    /**
+     * Adds a breadcrumb-trail, appearing in the ModalHeader, above the title.
+     */
+    breadcrumbs: React.ReactElement<React.ComponentProps<typeof Breadcrumbs>>;
+};
+type Props = Common | WithSubtitle | WithBreadcrumbs;
+type DefaultProps = {
+    closeButtonVisible: Props["closeButtonVisible"];
+};
+/**
+ * This is the standard layout for most straightforward modal experiences.
+ *
+ * The ModalHeader is required, but the ModalFooter is optional.
+ * The content of the dialog itself is fully customizable, but the
+ * left/right/top/bottom padding is fixed.
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import {OnePaneDialog} from "@khanacademy/wonder-blocks-modal";
+ * import {Body} from "@khanacademy/wonder-blocks-typography";
+ *
+ * <OnePaneDialog
+ *     title="Some title"
+ *     content={
+ *         <Body>
+ *             {`Lorem ipsum dolor sit amet, consectetur adipiscing
+ *             elit, sed do eiusmod tempor incididunt ut labore et
+ *             dolore magna aliqua. Ut enim ad minim veniam,
+ *             quis nostrud exercitation ullamco laboris nisi ut
+ *             aliquip ex ea commodo consequat. Duis aute irure
+ *             dolor in reprehenderit in voluptate velit esse
+ *             cillum dolore eu fugiat nulla pariatur. Excepteur
+ *             sint occaecat cupidatat non proident, sunt in culpa
+ *             qui officia deserunt mollit anim id est.`}
+ *         </Body>
+ *     }
+ * />
+ * ```
+ */
+export default class OnePaneDialog extends React.Component<Props> {
+    static defaultProps: DefaultProps;
+    renderHeader(uniqueId: string): React.ReactElement<React.ComponentProps<typeof ModalHeader>>;
+    render(): React.ReactElement;
+}
+export {};