@khanacademy/perseus 40.0.0 → 41.0.0

package/dist/components/hud.d.ts

@@ -5,5 +5,9 @@ type Props = {
     onClick: () => void;
     fixedPosition?: boolean;
 };
+/**
+ * A "heads-up display" (HUD) indicator that includes a short message (usually
+ * used for linting errors). The indicator can be disabled.
+ */
 declare const HUD: ({ message, enabled, onClick, fixedPosition }: Props) => React.JSX.Element;
 export default HUD;

package/dist/components/i18n-context.d.ts

@@ -9,6 +9,10 @@ type I18nContextType = {
     strings: PerseusStrings;
     locale: string;
 };
+export declare const mockPerseusI18nContext: {
+    strings: PerseusStrings;
+    locale: string;
+};
 export declare const PerseusI18nContext: React.Context<I18nContextType>;
 type Props = React.PropsWithChildren<I18nContextType>;
 export declare function PerseusI18nContextProvider({ children, strings, locale }: Props): React.JSX.Element;

package/dist/components/icon.d.ts

@@ -1,5 +1,25 @@
+/// <reference path="../../types/aphrodite.d.ts" />
+import * as React from "react";
+import type { CSSProperties } from "aphrodite";
+export type IconType = {
+    height: number;
+    path: string;
+    width: number;
+};
+type Props = {
+    className?: string;
+    style?: CSSProperties;
+    title?: string;
+    color: string;
+    focusable?: boolean;
+    icon: // If you pass in a string then it's assumed to be just an SVG
+    IconType | string;
+    pathClassName?: string;
+    size?: number;
+    alt?: string;
+};
 /**
- * SVG Icon React Component
+ * An SVG Icon
  *
  * This component is designed to take in SVG paths and render icons based upon
  * them. If you are looking for an icon that we've used before you should look
@@ -10,44 +30,25 @@
  *
  * Sample usage:
  *
- *   const dropdownIcon = `M5,6L0,0L10,0`;
- *   <Icon icon={dropdownIcon} />
+ * ```
+ * const dropdownIcon = `M5,6L0,0L10,0`;
+ * <Icon icon={dropdownIcon} />
+ * ```
  *
  * Or:
  *
+ * ```
  *   const dropdownIcon = {
  *       path: `M5,6L0,0L10,0`,
  *       height: 10,
  *       width: 10,
  *   };
  *   <Icon icon={dropdownIcon} size={20} />
- *
- * A full list of all the existing icons can be seen here:
- * http://localhost:8080/react-sandbox/shared-styles-package/icon.jsx.fixture.js
+ * ```
  *
  * If you want to add an entirely new icon please read the note inside
- * the `icon-paths.js` file.
+ * the `icon-paths.ts` file.
  */
-/// <reference path="../../types/aphrodite.d.ts" />
-import * as React from "react";
-import type { CSSProperties } from "aphrodite";
-export type IconType = {
-    height: number;
-    path: string;
-    width: number;
-};
-type Props = {
-    className?: string;
-    style?: CSSProperties;
-    title?: string;
-    color: string;
-    focusable?: boolean;
-    icon: // If you pass in a string then it's assumed to be just an SVG
-    IconType | string;
-    pathClassName?: string;
-    size?: number;
-    alt?: string;
-};
 declare class Icon extends React.Component<Props> {
     static defaultProps: {
         color: string;

package/dist/components/image-loader.d.ts

@@ -1,12 +1,3 @@
-/**
- * Component to display an image (or other React components) while the desired
- * image is loading.
- *
- * Derived from
- * https://github.com/hzdg/react-imageloader/blob/master/src/index.js
- * to better suit our environment/build tools. Additionally, this one does
- * not introduce a wrapper element, which makes styling easier.
- */
 import * as React from "react";
 import type { Dimensions } from "../types";
 declare const Status: {
@@ -35,6 +26,15 @@ type Props = {
 type State = {
     status: (typeof Status)[keyof typeof Status];
 };
+/**
+ * Component to display an image (or other React components) while the desired
+ * image is loading.
+ *
+ * Derived from
+ * https://github.com/hzdg/react-imageloader/blob/master/src/index.js
+ * to better suit our environment/build tools. Additionally, this one does
+ * not introduce a wrapper element, which makes styling easier.
+ */
 declare class ImageLoader extends React.Component<Props, State> {
     img: HTMLImageElement | null | undefined;
     constructor(props: Props);

package/dist/components/inline-icon.d.ts

@@ -10,11 +10,7 @@ type InlineIconProps = {
  * A stripped version of Icon.jsx from webapp. Takes an SVG icon and renders it
  * inline like Font Awesome did.
  *
- * If you are looking for an icon that we've used before you should look in
- * webapp's `icon-paths.js` which is a reference file for all the SVG paths
- * that we've used. You'll need to copy the object from that file into
- * whichever file you're using the icon and explicitly pass it in to the
- * <InlineIcon/> React component.
+ * You can refer to `icon-paths.ts` for all available SVG icons.
  *
  * We assume that the viewBox is cropped and aligned to (0, 0), but icons can
  * be defined differently. At some point we might want to add these attributes
@@ -22,13 +18,14 @@ type InlineIconProps = {
  *
  * Sample usage:
  *
- *   const editIcon = {
+ * ```
+ * const editIcon = {
  *      path: "M41.209 53.753l5.39 0l0 5.39l3.136 0l6.468-6.517-8.477-8.526-6.517 6.517l0 3.136zm33.173-34.937q-.882-.882-1.862.049l-19.6 19.6q-.931.98-.049 1.862t1.862-.049l19.6-19.6q.931-.98.049-1.862zm-38.563 45.668l0-16.121l37.632-37.632 16.17 16.121-37.632 37.632l-16.17 0zm43.022-12.397l0 10.633q-.049 6.713-4.753 11.417t-11.368 4.704l-46.599 0q-6.713 0-11.417-4.753t-4.704-11.368l0-46.599q0-6.664 4.753-11.417t11.368-4.704l46.599 0q3.528 0 6.566 1.372.833.392.98 1.323t-.49 1.617l-2.744 2.744q-.784.784-1.96.441t-2.352-.343l-46.599 0q-3.675 0-6.321 2.646t-2.646 6.321l0 46.599q0 3.675 2.646 6.321t6.321 2.646l46.599 0q3.675 0 6.321-2.646t2.646-6.321l0-7.056q0-.735.49-1.225l3.577-3.577q.833-.833 1.96-.392t1.127 1.617zm7.203-51.646q2.254 0 3.773 1.568l8.526 8.526q1.568 1.568 1.568 3.822t-1.568 3.773l-5.145 5.145-16.121-16.121 5.145-5.145q1.568-1.568 3.822-1.568z",
  *      width: 100,
  *      height: 78.912,
- *   };
- *   <InlineIcon {...editIcon} />
- *
+ * };
+ * <InlineIcon {...editIcon} />
+ * ```
  */
 declare const InlineIcon: ({ path, width, height, style, title, }: InlineIconProps) => React.ReactElement;
 export default InlineIcon;

package/dist/components/lint.d.ts

@@ -6,12 +6,25 @@ declare enum Severity {
     OfflineReportingOnly = 4
 }
 type Props = {
+    /** The children are the linty content we're highlighting */
     children: React.ReactNode;
+    /** Inline lint is highlighted differently than block lint. */
     inline?: boolean;
+    /** This is the text that appears in the tooltip */
     message: string;
+    /** This is used as the fragment id (hash) in the URL of the link */
     ruleName: string;
+    /** Lint warnings inside tables are handled specially */
     insideTable: boolean;
+    /**
+     * Should lint highlighting be rendered as a block to the left of
+     * the lint instead of on the right gutter?
+     */
     blockHighlight?: boolean;
+    /**
+     * How important this lint message is for the editor. Severity goes
+     * from 1 (indicating an error) to 4 (offline reporting only)
+     */
     severity?: Severity;
 };
 type State = {

package/dist/components/math-input.d.ts

@@ -2,8 +2,8 @@ import { CursorContext, MathInputI18nContext } from "@khanacademy/math-input";
 import * as React from "react";
 import { PerseusI18nContext } from "./i18n-context";
 import type { LegacyButtonSets } from "../perseus-types";
-import type { PerseusDependenciesV2 } from "../types";
 import type { Keys, MathFieldInterface } from "@khanacademy/math-input";
+import type { AnalyticsEventHandlerFn } from "@khanacademy/perseus-core";
 type ButtonsVisibleType = "always" | "never" | "focused";
 type KeypadButtonSets = {
     advancedRelations?: boolean;
@@ -40,7 +40,7 @@ type Props = {
      * - `never` means that the keypad is **never shown**.
      */
     buttonsVisible?: ButtonsVisibleType;
-    analytics: PerseusDependenciesV2["analytics"];
+    onAnalyticsEvent: AnalyticsEventHandlerFn;
 };
 type InnerProps = Props & {
     mathInputStrings: any;

package/dist/components/multi-button-group.d.ts

@@ -1,12 +1,38 @@
 import * as React from "react";
 type Props = {
+    /**
+     * The initial values of the buttons selected, defaults to null (no
+     * selection).
+     */
     values: ReadonlyArray<any> | null | undefined;
+    /**
+     * The set of buttons to display in this MultiButtonGroup.
+     */
     buttons: ReadonlyArray<{
+        /**
+         * the value returned when the button is selected
+         */
         value: any;
+        /**
+         * The content shown within the button, typically a string that gets
+         * rendered as the button's display text.
+         */
         content: React.ReactNode;
+        /**
+         * The title-text shown on hover
+         */
         title?: string;
     }>;
+    /**
+     * A function that is provided with the updated set of selected value
+     * (which it then is responsible for updating)
+     */
     onChange: (values?: any) => unknown;
+    /**
+     * If false, at least one button must be selected at all times.
+     *
+     * Defaults to `true`
+     */
     allowEmpty?: boolean;
 };
 type DefaultProps = {

package/dist/components/number-input.d.ts

@@ -2,6 +2,25 @@ import PropTypes from "prop-types";
 import * as React from "react";
 import { PerseusI18nContext } from "./i18n-context";
 import type { MathFormat } from "../perseus-types";
+/**
+ * An input box that accepts only numeric strings
+ *
+ * Calls `onChange(value, format)` for valid numbers.
+ *
+ * Reverts to the current value `onBlur` or on [ENTER],
+ *   but maintains the format (i.e. 3/2, 1 1/2, 150%)
+ *
+ * Accepts empty input and sends it to `onChange` as `null` if no numeric
+ * placeholder is set.
+ *
+ * If given a `checkValidity` function, will turn the background/outline red
+ * when invalid.
+ *
+ * If `useArrowKeys` is set to `true`, up/down arrows will increment/decrement
+ * integers.
+ *
+ * Optionally takes a `size` (`"mini"`, `"small"`,` `"normal"`)
+ */
 declare class NumberInput extends React.Component<any, any> {
     static contextType: React.Context<{
         strings: import("../strings").PerseusStrings;

package/dist/components/range-input.d.ts

@@ -1,5 +1,8 @@
 import PropTypes from "prop-types";
 import * as React from "react";
+/**
+ * A minor abstraction on top of `NumberInput` for ranges
+ */
 declare class RangeInput extends React.Component<any> {
     static propTypes: {
         value: PropTypes.Validator<any[]>;

package/dist/components/stub-tag-editor.d.ts

@@ -1,3 +1,5 @@
+import PropTypes from "prop-types";
+import * as React from "react";
 /**
  * Stub Tag Editor.
  *
@@ -11,8 +13,6 @@
  * It also gives a nicer interface for the group metadata editor
  * in local demo mode.
  */
-import PropTypes from "prop-types";
-import * as React from "react";
 declare class StubTagEditor extends React.Component<any> {
     static propTypes: {
         value: PropTypes.Requireable<(string | null | undefined)[]>;

package/dist/components/svg-image.d.ts

@@ -12,16 +12,46 @@ type Props = {
         labels: ReadonlyArray<any>;
     };
     height?: number;
+    /**
+     * When the DOM updates to replace the preloader with the image, or
+     * vice-versa, we trigger this callback.
+     */
     onUpdate: () => void;
+    /**
+     * If alt is provided, DO NOT set aria-hidden=true unless this override flag
+     * is set.
+     */
     overrideAriaHidden?: boolean;
     preloader?: (dimensions: Dimensions) => React.ReactNode;
+    /**
+     * By default, this component attempts to be responsive whenever
+     * possible (specifically, when width and height are passed in).
+     *
+     * You can expliclty force unresponsive behavior by *either*
+     * not passing in width/height *or* setting this prop to false.
+     *
+     * The difference is that forcing via this prop will result in
+     * explicit width and height styles being set on the rendered
+     * component.
+     */
     responsive: boolean;
     scale: number;
     src: string;
     title?: string;
     trackInteraction?: () => void;
     width?: number;
+    /**
+     * Whether clicking this image will allow it to be fully zoomed in to
+     * its original size on click, and allow the user to scroll in that
+     * state. This also does some hacky viewport meta tag changing to
+     * ensure this works on mobile devices, so I (david@) don't recommend
+     * enabling this on desktop yet.
+     */
     zoomToFullSizeOnMobile?: boolean;
+    /**
+     * If provided, use AssetContext.Consumer, see renderer.jsx.
+     * If not, it defaults to a no-op.
+     */
     setAssetStatus: (assetKey: string, loaded: boolean) => void;
 };
 type DefaultProps = {

package/dist/components/tooltip.d.ts

@@ -1,33 +1,3 @@
-/**
- * A generic tooltip library for React.js
- *
- * This should eventually end up in react-components
- *
- * Interface: ({a, b} means one of a or b)
- * import Tooltip from "./tooltip";
- * <Tooltip
- *     className="class-for-tooltip-contents"
- *     horizontalPosition={HoriziontalDirection.Left}
- *     horizontalAlign={HoriziontalDirection.Left}
- *     verticalPosition={VerticalDirection.Top}
- *     arrowSize={10} // arrow size in pixels
- *     borderColor="#ccc" // color of the border for the tooltip
- *     show={true} // whether the tooltip should currently be visible
- *     targetContainerStyle={targetContainerStyle}
- * >
- *     <TargetElementOfTheTooltip />
- *     <TooltipContents1 />
- *     <TooltipContents2 />
- * </Tooltip>
- *
- * To show/hide the tooltip, the parent component should call the
- * .show() and .hide() methods of the tooltip when appropriate.
- * (These are usually set up as handlers of events on the target element.)
- *
- * Notes:
- *     className should not specify a border; that is handled by borderColor
- *     so that the arrow and tooltip match
- */
 import * as React from "react";
 export declare enum HorizontalDirection {
     Left = "left",
@@ -60,6 +30,47 @@ type DefaultProps = {
 type State = {
     height: number | null;
 };
+/**
+ * DEPRECATED! Use Wonder Blocks tooltip instead.
+ *
+ * A generic tooltip library for React.js
+ *
+ * ```
+ * import Tooltip from "./tooltip";
+ * <Tooltip
+ *     className="class-for-tooltip-contents"
+ *     horizontalPosition={HoriziontalDirection.Left}
+ *     horizontalAlign={HoriziontalDirection.Left}
+ *     verticalPosition={VerticalDirection.Top}
+ *     arrowSize={10} // arrow size in pixels
+ *     borderColor="#ccc" // color of the border for the tooltip
+ *     show={true} // whether the tooltip should currently be visible
+ *     targetContainerStyle={targetContainerStyle}
+ * >
+ *     <TargetElementOfTheTooltip />
+ *     <TooltipContents1 />
+ *     <TooltipContents2 />
+ * </Tooltip>
+ * ```
+ *
+ * To show/hide the tooltip, the parent component should call the
+ * `.show()` and `.hide()` methods of the tooltip when appropriate.
+ * (These are usually set up as handlers of events on the target element.)
+ *
+ * Notes:
+ *     `className` should not specify a border; that is handled by `borderColor`
+ *     so that the arrow and tooltip match
+ *
+ * ```
+ *          __,,--``\\
+ *  _,,-''``         \\     ,
+ * '----------_.------'-.___|\__
+ *    _.--''``    `)__   )__   @\__
+ *   (  .. ''---/___,,E/__,E'------`
+ *    `-''`''
+ * Here be dragons.
+ * ```
+ */
 declare class Tooltip extends React.Component<Props, State> {
     static defaultProps: DefaultProps;
     state: State;

package/dist/es/index.css

@@ -4521,3 +4521,9 @@ html body .mq-editable-field .mq-selection .mq-nthroot-container * {
     stroke: black;
     stroke-width: 1px;
 }
+
+.mafs-sr-only {
+    height: 0;
+    width: 0;
+    overflow: hidden;
+}