@khanacademy/wonder-blocks-tooltip 1.4.6 → 1.4.7

package/dist/components/tooltip.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The Tooltip component provides the means to anchor some additional
+ * information to some content. The additional information is shown in a
+ * callout that hovers above the page content. This additional information is
+ * invoked by hovering over the anchored content, or focusing all or part of the
+ * anchored content.
+ *
+ * This component is structured as follows:
+ *
+ * Tooltip (this component)
+ * - TooltipAnchor (provides hover/focus behaviors on anchored content)
+ *   - TooltipPortalMounter (creates portal into which the callout is rendered)
+ * --------------------------- [PORTAL BOUNDARY] ------------------------------
+ * - TooltipPopper (provides positioning for the callout using react-popper)
+ *   - TooltipBubble (renders the callout borders, background and shadow)
+ *     - TooltipContent (renders the callout content; the actual information)
+ *     - TooltipTail (renders the callout tail and shadow that points from the
+ *                     callout to the anchor content)
+ */
+import * as React from "react";
+import { IIdentifierFactory } from "@khanacademy/wonder-blocks-core";
+import type { Typography } from "@khanacademy/wonder-blocks-typography";
+import type { AriaProps } from "@khanacademy/wonder-blocks-core";
+import TooltipContent from "./tooltip-content";
+import type { Placement } from "../util/types";
+type Props = AriaProps & {
+    /**
+     * The content for anchoring the tooltip.
+     * This component will be used to position the tooltip.
+     */
+    children: React.ReactElement<any> | string;
+    /**
+     * The title of the tooltip.
+     * Optional.
+     */
+    title?: string | React.ReactElement<React.ComponentProps<Typography>>;
+    /**
+     * The content to render in the tooltip.
+     */
+    content: string | React.ReactElement<React.ComponentProps<typeof TooltipContent>>;
+    /**
+     * The unique identifier to give to the tooltip. Provide this in cases where
+     * you want to override the default accessibility solution. This identifier
+     * will be applied to the tooltip bubble content.
+     *
+     * By providing this identifier, the children that this tooltip anchors to
+     * will not be automatically given the aria-desribedby attribute. Instead,
+     * the accessibility solution is the responsibility of the caller.
+     *
+     * If this is not provided, the aria-describedby attribute will be added
+     * to the children with a unique identifier pointing to the tooltip bubble
+     * content.
+     */
+    id?: string;
+    /**
+     * When true, if a tabindex attribute is not already present on the element
+     * wrapped by the anchor, the element will be given tabindex=0 to make it
+     * keyboard focusable; otherwise, does not attempt to change the ability to
+     * focus the anchor element.
+     *
+     * Defaults to true.
+     *
+     * One might set this to false in circumstances where the wrapped component
+     * already can receive focus or contains an element that can.
+     * Use good judgement when overriding this value, the tooltip content should
+     * be accessible via keyboard in all circumstances where the tooltip would
+     * appear using the mouse, so verify those use-cases.
+     *
+     * Also, note that the aria-describedby attribute is attached to the root
+     * anchor element, so you may need to implement an additional accessibility
+     * solution when overriding anchor focusivity.
+     */
+    forceAnchorFocusivity?: boolean;
+    /**
+     * Where the tooltip should appear in relation to the anchor element.
+     * Defaults to "top".
+     */
+    placement: Placement;
+    /**
+     * Renders the tooltip when true, renders nothing when false.
+     *
+     * Using this prop makes the component behave as a controlled component. The
+     * parent is responsible for managing the opening/closing of the tooltip
+     * when using this prop.
+     */
+    opened?: boolean;
+    /**
+     * Test ID used for e2e testing.
+     */
+    testId?: string;
+};
+type State = {
+    /**
+     * Whether the tooltip is open by hovering/focusing on the anchor element.
+     */
+    active: boolean;
+    /**
+     * Whether the tooltip is open by hovering on the tooltip bubble.
+     */
+    activeBubble: boolean;
+    /**
+     * The element that activates the tooltip.
+     */
+    anchorElement: HTMLElement | null | undefined;
+};
+type DefaultProps = {
+    forceAnchorFocusivity: Props["forceAnchorFocusivity"];
+    placement: Props["placement"];
+};
+/**
+ * Use a tooltip to help describe an on screen object.
+ *
+ * Tooltips:
+ *  - contain text
+ *  - (optional) contain small graphic elements to complement the text
+ *  - appear on hover or focus (for non-assistive tech keyboard users)
+ *  - must have a tail that points to a parent object
+ *  - DO NOT include actions
+ *
+ * For more rich content see Popovers, for taking action on an object, see
+ * Snackbars (proposed).
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import Tooltip from "@khanacademy/wonder-blocks-tooltip";
+ *
+ * <Tooltip content="This is a text tooltip">
+ *  Tooltip anchor
+ * </Tooltip>
+ * ```
+ *
+ */
+export default class Tooltip extends React.Component<Props, State> {
+    static defaultProps: DefaultProps;
+    /**
+     * Used to sync the `opened` state when Tooltip acts as a controlled
+     * component
+     */
+    static getDerivedStateFromProps(props: Props, state: State): Partial<State> | null;
+    state: State;
+    static ariaContentId: string;
+    _updateAnchorElement(ref?: Element | null): void;
+    _renderBubbleContent(): React.ReactElement<React.ComponentProps<typeof TooltipContent>>;
+    _renderPopper(ids?: IIdentifierFactory): React.ReactNode;
+    _getHost(): Element | null | undefined;
+    _renderTooltipAnchor(ids?: IIdentifierFactory): React.ReactNode;
+    render(): React.ReactElement;
+}
+export {};

package/dist/components/tooltip.js.flow

@@ -0,0 +1,159 @@
+/**
+ * Flowtype definitions for tooltip
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import * as React from "react";
+import { IIdentifierFactory } from "@khanacademy/wonder-blocks-core";
+import type { Typography } from "@khanacademy/wonder-blocks-typography";
+import type { AriaProps } from "@khanacademy/wonder-blocks-core";
+import TooltipContent from "./tooltip-content";
+import type { Placement } from "../util/types";
+declare type Props = {
+  ...AriaProps,
+  ...{
+    /**
+     * The content for anchoring the tooltip.
+     * This component will be used to position the tooltip.
+     */
+    children: React.Element<any> | string,
+
+    /**
+     * The title of the tooltip.
+     * Optional.
+     */
+    title?: string | React.Element<React.ComponentProps<Typography>>,
+
+    /**
+     * The content to render in the tooltip.
+     */
+    content:
+      | string
+      | React.Element<React.ComponentProps<typeof TooltipContent>>,
+
+    /**
+     * The unique identifier to give to the tooltip. Provide this in cases where
+     * you want to override the default accessibility solution. This identifier
+     * will be applied to the tooltip bubble content.
+     *
+     * By providing this identifier, the children that this tooltip anchors to
+     * will not be automatically given the aria-desribedby attribute. Instead,
+     * the accessibility solution is the responsibility of the caller.
+     *
+     * If this is not provided, the aria-describedby attribute will be added
+     * to the children with a unique identifier pointing to the tooltip bubble
+     * content.
+     */
+    id?: string,
+
+    /**
+     * When true, if a tabindex attribute is not already present on the element
+     * wrapped by the anchor, the element will be given tabindex=0 to make it
+     * keyboard focusable; otherwise, does not attempt to change the ability to
+     * focus the anchor element.
+     *
+     * Defaults to true.
+     *
+     * One might set this to false in circumstances where the wrapped component
+     * already can receive focus or contains an element that can.
+     * Use good judgement when overriding this value, the tooltip content should
+     * be accessible via keyboard in all circumstances where the tooltip would
+     * appear using the mouse, so verify those use-cases.
+     *
+     * Also, note that the aria-describedby attribute is attached to the root
+     * anchor element, so you may need to implement an additional accessibility
+     * solution when overriding anchor focusivity.
+     */
+    forceAnchorFocusivity?: boolean,
+
+    /**
+     * Where the tooltip should appear in relation to the anchor element.
+     * Defaults to "top".
+     */
+    placement: Placement,
+
+    /**
+     * Renders the tooltip when true, renders nothing when false.
+     *
+     * Using this prop makes the component behave as a controlled component. The
+     * parent is responsible for managing the opening/closing of the tooltip
+     * when using this prop.
+     */
+    opened?: boolean,
+
+    /**
+     * Test ID used for e2e testing.
+     */
+    testId?: string,
+    ...
+  },
+};
+declare type State = {
+  /**
+   * Whether the tooltip is open by hovering/focusing on the anchor element.
+   */
+  active: boolean,
+
+  /**
+   * Whether the tooltip is open by hovering on the tooltip bubble.
+   */
+  activeBubble: boolean,
+
+  /**
+   * The element that activates the tooltip.
+   */
+  anchorElement: HTMLElement | null | void,
+  ...
+};
+declare type DefaultProps = {
+  forceAnchorFocusivity: $PropertyType<Props, "forceAnchorFocusivity">,
+  placement: $PropertyType<Props, "placement">,
+  ...
+};
+/**
+ * Use a tooltip to help describe an on screen object.
+ *
+ * Tooltips:
+ *  - contain text
+ *  - (optional) contain small graphic elements to complement the text
+ *  - appear on hover or focus (for non-assistive tech keyboard users)
+ *  - must have a tail that points to a parent object
+ *  - DO NOT include actions
+ *
+ * For more rich content see Popovers, for taking action on an object, see
+ * Snackbars (proposed).
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import Tooltip from "@khanacademy/wonder-blocks-tooltip";
+ *
+ * <Tooltip content="This is a text tooltip">
+ *  Tooltip anchor
+ * </Tooltip>
+ * ```
+ */
+declare export default class Tooltip mixins React.Component<Props, State> {
+  static defaultProps: DefaultProps;
+
+  /**
+   * Used to sync the `opened` state when Tooltip acts as a controlled
+   * component
+   */
+  static getDerivedStateFromProps(
+    props: Props,
+    state: State
+  ): $Rest<State, { ... }> | null;
+  state: State;
+  static ariaContentId: string;
+  _updateAnchorElement(ref?: Element | null): void;
+  _renderBubbleContent(): React.Element<
+    React.ComponentProps<typeof TooltipContent>
+  >;
+  _renderPopper(ids?: IIdentifierFactory): React.Node;
+  _getHost(): Element | null | void;
+  _renderTooltipAnchor(ids?: IIdentifierFactory): React.Node;
+  render(): React.Element<>;
+}