@khanacademy/wonder-blocks-core 4.6.2 → 4.8.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @khanacademy/wonder-blocks-core
 
+## 4.8.0
+
+### Minor Changes
+
+-   873f4a14: Update aphrodite lib def and StyleType
+
+### Patch Changes
+
+-   d816af08: Update build and test configs use TypeScript
+-   3891f544: Update babel config to include plugins that Storybook needed
+-   0d28bb1c: Configured TypeScript
+-   3d05f764: Fix HOCs and other type errors
+-   c2ec4902: Update eslint configuration, fix lint
+-   2983c05b: Include 'types' field in package.json
+-   77ff6a66: Generate Flow types from TypeScript types
+-   ec8d4b7f: Fix miscellaneous TypeScript errors
+
+## 4.7.0
+
+### Minor Changes
+
+-   91cb727c: Convert enums to POJOs
+
+### Patch Changes
+
+-   91cb727c: Remove file extensions from imports
+
 ## 4.6.2
 
 ### Patch Changes

package/dist/components/id-provider.d.ts

@@ -0,0 +1,58 @@
+import * as React from "react";
+import type { IIdentifierFactory } from "../util/types";
+type Props = {
+    /**
+     * Use the children-as-function pattern to pass a uniqueId string for
+     * use anywhere within children. This provides a way of adding a unique identifier
+     * to a given component for a11y purposes.
+     */
+    children: (uniqueId: string) => React.ReactElement;
+    /**
+     * Scope for the unique identifier
+     */
+    scope: string;
+    /**
+     * An optional id parameter for the title. If one is
+     * not provided, a unique id will be generated.
+     */
+    id?: string;
+    /**
+     * Test ID used for e2e testing.
+     */
+    testId?: string;
+};
+/**
+ * This is a wrapper that returns an identifier. If the `id` prop is set, the
+ * component will return the same id to be consumed by its children. Otherwise,
+ * a unique id will be provided. This is beneficial for accessibility purposes,
+ * among other things.
+ *
+ * The main difference with `UniqueIDProvider` is that `IDProvider` has a single
+ * responsibility, to return an identifier that can by used by the children that
+ * are rendered internally.
+ *
+ * This way, the wrapped component will receive this custom ID and will use it
+ * to connect different elements.
+ *
+ * e.g. It uses the same generated id to connect a Dialog with its main title,
+ * or form label with the associated input element, etc.
+ *
+ * ## Usage
+ *
+ * ```jsx
+ * import {IDProvider} from "@khanacademy/wonder-blocks-core";
+ *
+ * <IDProvider scope="field">
+ *  {(uniqueId) => (
+ *     Unique ID: {uniqueId}
+ *  )}
+ * </IDProvider>
+ * ```
+ *
+ */
+export default class IDProvider extends React.Component<Props> {
+    static defaultId: string;
+    renderChildren(ids?: IIdentifierFactory): React.ReactNode;
+    render(): React.ReactElement;
+}
+export {};

package/dist/components/id-provider.js.flow

@@ -0,0 +1,67 @@
+/**
+ * Flowtype definitions for id-provider
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import * as React from "react";
+import type { IIdentifierFactory } from "../util/types";
+declare type Props = {
+  /**
+   * Use the children-as-function pattern to pass a uniqueId string for
+   * use anywhere within children. This provides a way of adding a unique identifier
+   * to a given component for a11y purposes.
+   */
+  children: (uniqueId: string) => React.Element<>,
+
+  /**
+   * Scope for the unique identifier
+   */
+  scope: string,
+
+  /**
+   * An optional id parameter for the title. If one is
+   * not provided, a unique id will be generated.
+   */
+  id?: string,
+
+  /**
+   * Test ID used for e2e testing.
+   */
+  testId?: string,
+  ...
+};
+/**
+ * This is a wrapper that returns an identifier. If the `id` prop is set, the
+ * component will return the same id to be consumed by its children. Otherwise,
+ * a unique id will be provided. This is beneficial for accessibility purposes,
+ * among other things.
+ *
+ * The main difference with `UniqueIDProvider` is that `IDProvider` has a single
+ * responsibility, to return an identifier that can by used by the children that
+ * are rendered internally.
+ *
+ * This way, the wrapped component will receive this custom ID and will use it
+ * to connect different elements.
+ *
+ * e.g. It uses the same generated id to connect a Dialog with its main title,
+ * or form label with the associated input element, etc.
+ *
+ * ## Usage
+ *
+ * ```jsx
+ * import {IDProvider} from "@khanacademy/wonder-blocks-core";
+ *
+ * <IDProvider scope="field">
+ *  {(uniqueId) => (
+ *     Unique ID: {uniqueId}
+ *  )}
+ * </IDProvider>
+ * ```
+ */
+declare export default class IDProvider mixins React.Component<Props> {
+  static defaultId: string;
+  renderChildren(ids?: IIdentifierFactory): React.Node;
+  render(): React.Element<>;
+}

package/{src/components/render-state-context.js → dist/components/render-state-context.d.ts}

@@ -1,12 +1,9 @@
-// @flow
 import * as React from "react";
-
-export enum RenderState {
-    Root = "root",
-    Initial = "initial",
-    Standard = "standard",
-}
-
+export declare const RenderState: {
+    readonly Root: "root";
+    readonly Initial: "initial";
+    readonly Standard: "standard";
+};
 /**
  * This is the context that tracks who is doing what in our SSR component tree.
  *
@@ -22,5 +19,4 @@ export enum RenderState {
  * standard:
  *   means that we're all now doing non-SSR rendering
  */
-export const RenderStateContext: React.Context<RenderState> =
-    React.createContext(RenderState.Root);
+export declare const RenderStateContext: React.Context<typeof RenderState[keyof typeof RenderState]>;

package/dist/components/render-state-context.js.flow

@@ -0,0 +1,32 @@
+/**
+ * Flowtype definitions for render-state-context
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import * as React from "react";
+declare export var RenderState: {
+  +Root: "root",
+  +Initial: "initial",
+  +Standard: "standard",
+  ...
+};
+/**
+ * This is the context that tracks who is doing what in our SSR component tree.
+ *
+ * root:
+ *   no one has instigated an initial SSR render so the component that sees
+ *   this "root" state is responsible for controlling initial versus standard
+ *   rendering semantics
+ *
+ * initial:
+ *   this means the SSR render has started, and all SSR components should act
+ *   as though they are on the server
+ *
+ * standard:
+ *   means that we're all now doing non-SSR rendering
+ */
+declare export var RenderStateContext: React.Context<
+  $ElementType<typeof RenderState, $Keys<typeof RenderState>>
+>;

package/dist/components/render-state-root.d.ts

@@ -0,0 +1,10 @@
+import * as React from "react";
+type Props = {
+    children: React.ReactNode;
+    /**
+     * Whether the component should throw when nested.  Defaults to `true`.
+     */
+    throwIfNested?: boolean;
+};
+declare const RenderStateRoot: React.FC<Props>;
+export { RenderStateRoot };

package/dist/components/render-state-root.js.flow

@@ -0,0 +1,19 @@
+/**
+ * Flowtype definitions for render-state-root
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import * as React from "react";
+declare type Props = {
+  children: React.Node,
+
+  /**
+   * Whether the component should throw when nested.  Defaults to `true`.
+   */
+  throwIfNested?: boolean,
+  ...
+};
+declare var RenderStateRoot: React.FC<Props>;
+declare export { RenderStateRoot };

package/dist/components/text.d.ts

@@ -0,0 +1,25 @@
+import * as React from "react";
+import type { TextViewSharedProps } from "../util/types";
+type Props = TextViewSharedProps & {
+    tag: string;
+};
+type DefaultProps = {
+    tag: Props["tag"];
+};
+/**
+ * Text is a building block for constructing other components. `Text` roughly
+ * maps to `span`. You can override which tag is used to render the component
+ * (for semantic purposes) by specifying the `tag` prop.
+ *
+ * These components can take styles (via the `style` prop) in a variety of
+ * manners:
+ *
+ * - An inline style object
+ * - An `aphrodite` StyleSheet style
+ * - An array combining the above
+ */
+export default class Text extends React.Component<Props> {
+    static defaultProps: DefaultProps;
+    render(): React.ReactElement;
+}
+export {};

package/dist/components/text.js.flow

@@ -0,0 +1,36 @@
+/**
+ * Flowtype definitions for text
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import * as React from "react";
+import type { TextViewSharedProps } from "../util/types";
+declare type Props = {
+  ...TextViewSharedProps,
+  ...{
+    tag: string,
+    ...
+  },
+};
+declare type DefaultProps = {
+  tag: $PropertyType<Props, "tag">,
+  ...
+};
+/**
+ * Text is a building block for constructing other components. `Text` roughly
+ * maps to `span`. You can override which tag is used to render the component
+ * (for semantic purposes) by specifying the `tag` prop.
+ *
+ * These components can take styles (via the `style` prop) in a variety of
+ * manners:
+ *
+ * - An inline style object
+ * - An `aphrodite` StyleSheet style
+ * - An array combining the above
+ */
+declare export default class Text mixins React.Component<Props> {
+  static defaultProps: DefaultProps;
+  render(): React.Element<>;
+}

package/dist/components/unique-id-provider.d.ts

@@ -0,0 +1,69 @@
+import * as React from "react";
+import type { IIdentifierFactory } from "../util/types";
+type Props = {
+    /**
+     * A render prop that takes an instance of IIdentifierFactory and returns
+     * the content to be rendered.
+     *
+     * If mockOnFirstRender is false, this is only called after
+     * the initial render has occurred -- it will be blank for the
+     * the first render -- and will always be called with the same
+     * IIdentifierFactory instance.
+     *
+     * If mockOnFirstRender is true, this is called once with
+     * a mock IIdentifierFactory for the initial render, and then a unique ID
+     * factory thereafter.
+     *
+     * Full type with `IIdentifierFactory` definition inlined is:
+     *
+     * `{get(id: string): string} => React.Node`
+     */
+    children: (arg1: IIdentifierFactory) => React.ReactElement;
+    /**
+     * If mockOnFirstRender is false, children is only called
+     * after the initial render has occurred.
+     * If mockOnFirstRender is true, children is called once with
+     * a mock IIdentifierFactory for the initial render, and then a unique ID
+     * factory thereafter.
+     */
+    mockOnFirstRender: boolean;
+    /**
+     * If this prop is specified, any identifiers provided will contain the
+     * given scope. This can be useful for making easily readable identifiers.
+     */
+    readonly scope?: string;
+};
+/**
+ * The `UniqueIDProvider` component is how Wonder Blocks components obtain
+ * unique identifiers. This component ensures that server-side rendering and
+ * initial client rendering match while allowing the provision of unique
+ * identifiers for the client.
+ *
+ * In all but the first render, the children are rendered with the same
+ * `IIdentifierFactory` instance, ensuring that the same calls will return the
+ * same identifiers.
+ *
+ * The `get` method of the identifier factory ensures that the same identifier
+ * is returned for like requests, but also that all identifiers provided are
+ * unique. Therefore, `get("test")` will always equal `get("test")`, and
+ * `get("test2")` will always equal `get("test2")`, but `get("test")` will
+ * never equal `get("test2")`.
+ *
+ * ## Usage
+ *
+ * ```jsx
+ * import {UniqueIDProvider} from "@khanacademy/wonder-blocks-core";
+ *
+ * <UniqueIDProvider mockOnFirstRender={false} scope="field">
+ *  {(ids) => (
+ *     <>The id returned for "my-identifier": {ids.get("my-identifier")}</>
+ *  )}
+ * </UniqueIDProvider>
+ * ```
+ */
+export default class UniqueIDProvider extends React.Component<Props> {
+    _idFactory: IIdentifierFactory;
+    _performRender(firstRender: boolean): React.ReactNode;
+    render(): React.ReactElement;
+}
+export {};

package/dist/components/unique-id-provider.js.flow

@@ -0,0 +1,78 @@
+/**
+ * Flowtype definitions for unique-id-provider
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import * as React from "react";
+import type { IIdentifierFactory } from "../util/types";
+declare type Props = {
+  /**
+   * A render prop that takes an instance of IIdentifierFactory and returns
+   * the content to be rendered.
+   *
+   * If mockOnFirstRender is false, this is only called after
+   * the initial render has occurred -- it will be blank for the
+   * the first render -- and will always be called with the same
+   * IIdentifierFactory instance.
+   *
+   * If mockOnFirstRender is true, this is called once with
+   * a mock IIdentifierFactory for the initial render, and then a unique ID
+   * factory thereafter.
+   *
+   * Full type with `IIdentifierFactory` definition inlined is:
+   *
+   * `{get(id: string): string} => React.Node`
+   */
+  children: (arg1: IIdentifierFactory) => React.Element<>,
+
+  /**
+   * If mockOnFirstRender is false, children is only called
+   * after the initial render has occurred.
+   * If mockOnFirstRender is true, children is called once with
+   * a mock IIdentifierFactory for the initial render, and then a unique ID
+   * factory thereafter.
+   */
+  mockOnFirstRender: boolean,
+
+  /**
+   * If this prop is specified, any identifiers provided will contain the
+   * given scope. This can be useful for making easily readable identifiers.
+   */
+  +scope?: string,
+  ...
+};
+/**
+ * The `UniqueIDProvider` component is how Wonder Blocks components obtain
+ * unique identifiers. This component ensures that server-side rendering and
+ * initial client rendering match while allowing the provision of unique
+ * identifiers for the client.
+ *
+ * In all but the first render, the children are rendered with the same
+ * `IIdentifierFactory` instance, ensuring that the same calls will return the
+ * same identifiers.
+ *
+ * The `get` method of the identifier factory ensures that the same identifier
+ * is returned for like requests, but also that all identifiers provided are
+ * unique. Therefore, `get("test")` will always equal `get("test")`, and
+ * `get("test2")` will always equal `get("test2")`, but `get("test")` will
+ * never equal `get("test2")`.
+ *
+ * ## Usage
+ *
+ * ```jsx
+ * import {UniqueIDProvider} from "@khanacademy/wonder-blocks-core";
+ *
+ * <UniqueIDProvider mockOnFirstRender={false} scope="field">
+ *  {(ids) => (
+ *     <>The id returned for "my-identifier": {ids.get("my-identifier")}</>
+ *  )}
+ * </UniqueIDProvider>
+ * ```
+ */
+declare export default class UniqueIDProvider mixins React.Component<Props> {
+  _idFactory: IIdentifierFactory;
+  _performRender(firstRender: boolean): React.Node;
+  render(): React.Element<>;
+}

package/dist/components/view.d.ts

@@ -0,0 +1,43 @@
+import * as React from "react";
+import type { TextViewSharedProps } from "../util/types";
+type ValidViewTags = "div" | "article" | "aside" | "nav" | "section";
+type Props = TextViewSharedProps & {
+    /**
+     * The HTML tag to render.
+     */
+    tag: ValidViewTags;
+};
+type DefaultProps = {
+    tag: Props["tag"];
+};
+/**
+ * View is a building block for constructing other components. `View` roughly
+ * maps to `div`. You can override which tag is used to render the component
+ * (for semantic purposes) by specifying the `tag` prop.
+ *
+ * These components can take styles (via the `style` prop) in a variety of
+ * manners:
+ *
+ * - An inline style object
+ * - An `aphrodite` StyleSheet style
+ * - An array combining the above
+ *
+ * `View` sets the following defaults:
+ *
+ * - `display: "flex"`
+ * - `flexDirection: "column"`
+ * - they each get their own stacking context.
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import {View} from "@khanacademy/wonder-blocks-core";
+ *
+ * <View>This is a View!</View>
+ * ```
+ */
+export default class View extends React.Component<Props> {
+    static defaultProps: DefaultProps;
+    render(): React.ReactElement;
+}
+export {};

package/dist/components/view.js.flow

@@ -0,0 +1,54 @@
+/**
+ * Flowtype definitions for view
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import * as React from "react";
+import type { TextViewSharedProps } from "../util/types";
+declare type ValidViewTags = "div" | "article" | "aside" | "nav" | "section";
+declare type Props = {
+  ...TextViewSharedProps,
+  ...{
+    /**
+     * The HTML tag to render.
+     */
+    tag: ValidViewTags,
+    ...
+  },
+};
+declare type DefaultProps = {
+  tag: $PropertyType<Props, "tag">,
+  ...
+};
+/**
+ * View is a building block for constructing other components. `View` roughly
+ * maps to `div`. You can override which tag is used to render the component
+ * (for semantic purposes) by specifying the `tag` prop.
+ *
+ * These components can take styles (via the `style` prop) in a variety of
+ * manners:
+ *
+ * - An inline style object
+ * - An `aphrodite` StyleSheet style
+ * - An array combining the above
+ *
+ * `View` sets the following defaults:
+ *
+ * - `display: "flex"`
+ * - `flexDirection: "column"`
+ * - they each get their own stacking context.
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import {View} from "@khanacademy/wonder-blocks-core";
+ *
+ * <View>This is a View!</View>
+ * ```
+ */
+declare export default class View mixins React.Component<Props> {
+  static defaultProps: DefaultProps;
+  render(): React.Element<>;
+}

package/dist/components/with-ssr-placeholder.d.ts

@@ -0,0 +1,63 @@
+import * as React from "react";
+import { RenderState } from "./render-state-context";
+/**
+ * We use render functions so that we don't do any work unless we need to.
+ * This avoids rendering but not mounting potentially complex component trees.
+ */
+type Props = {
+    /**
+     * The content that is client-only.  This is what is rendered when
+     * not server-side rendering, or (when server-side rendering) after
+     * the initial rehydration has finished.
+     */
+    children: () => React.ReactElement;
+    /**
+     * What to render during server-side rendering, or null not to
+     * render anything.
+     *
+     * NOTE: Make sure the placeholder will render the same for both
+     * client and server -- that is, it does the same thing for both
+     * the server-side renderer and the rehydration -- or it defeats
+     * the purpose of using the WithSSRPlaceholder component.
+     */
+    placeholder: () => React.ReactElement | null | undefined;
+};
+type State = {
+    mounted: boolean;
+};
+/**
+ * Defer or change rendering until the component did mount.
+ *
+ * The purpose of this component is to disable or modify server-side rendering
+ * of certain components. Disabling rendering on the server, by itself, would
+ * not be sufficient, since the initial render of the component must match what
+ * is rendered on the server. Therefore, this component also disables rendering
+ * the first time around on the client.
+ *
+ * If `WithSSRPlaceholder` components are nested within one another, the root
+ * `WithSSRPlaceholder` component will handle the initial render, but nested
+ * `WithSSRPlaceholder` components will delegate to the root one, meaning that
+ * we don't cascade delayed rendering down the component tree. This will also be
+ * the case across portal boundaries.
+ *
+ * ## Usage
+ *
+ * ```js
+ * import {WithSSRPlaceholder} from "@khanacademy/wonder-blocks-core";
+ *
+ * <WithSSRPlaceholder placeholder={() => <div>Renders on the server!</div>}>
+ *   {() => (
+ *      <div>This is rendered only by the client, for all renders after the rehydration render</div>
+ *   )}
+ * </WithSSRPlaceholder>
+ * ```
+ */
+export default class WithSSRPlaceholder extends React.Component<Props, State> {
+    state: State;
+    componentDidMount(): void;
+    _isTheRootComponent: boolean;
+    _renderAsRootComponent(): React.ReactNode;
+    _maybeRender(renderState: typeof RenderState[keyof typeof RenderState]): React.ReactNode;
+    render(): React.ReactElement;
+}
+export {};