@khanacademy/wonder-blocks-core 0.0.0-PR2089-20231019161345

package/CHANGELOG.md

@@ -0,0 +1,245 @@
+# @khanacademy/wonder-blocks-core
+
+## 0.0.0-PR2089-20231019161345
+
+### Minor Changes
+
+-   ab3f7875: Make useOnMountEffect accept functions with void return types
+
+## 6.2.0
+
+### Minor Changes
+
+-   4b97b9a2: Remove deps argument from `usePreHydrationEffect`
+
+## 6.1.1
+
+### Patch Changes
+
+-   2871f0a9: Add new usePreHydrationEffect hook to module exports
+
+## 6.1.0
+
+### Minor Changes
+
+-   efb59c29: Add `usePreHydrationEffect`
+
+### Patch Changes
+
+-   8bc40ed2: Change the return type of `useLatestRef` from `RefObject<T>` to
+    `{readonly current: T}`, so the `current` property is not nullable.
+
+    This fixes a bug introduced by the migration to TypeScript.
+
+## 6.0.2
+
+### Patch Changes
+
+-   f19da46e: Allow 'title' on View and typography components
+
+## 6.0.1
+
+### Patch Changes
+
+-   1920feb8: `RenderStateRoot` now wraps children in a React fragment
+
+## 6.0.0
+
+### Major Changes
+
+-   674a1e5c: POJOs have been replace with TS enums
+
+### Patch Changes
+
+-   674a1e5c: We're no longer building flow types
+
+## 5.4.0
+
+### Minor Changes
+
+-   1344436f: Add `PropsFor` type to simplify `JSX.LibraryManagedAttributes` usage
+
+## 5.3.1
+
+### Patch Changes
+
+-   9f3752d4: Used named functions in componenets with forwarded refs
+
+## 5.3.0
+
+### Minor Changes
+
+-   c37b99aa: Forward refs for Text and Title
+-   c4cef3e6: Added ref forwarding to View
+
+## 5.2.3
+
+### Patch Changes
+
+-   d4c412b5: Update useForceUpdate to ensure consuming hooks properly refresh
+
+## 5.2.2
+
+### Patch Changes
+
+-   64a188e3: Fix useForceUpdate so that regardless of how many times it is called before a new render, it will always cause a new render
+
+## 5.2.1
+
+### Patch Changes
+
+-   5a1ea891: Make sure that React contexts are named
+-   df9a10aa: Update state and props to be readonly in components using getDerivedStateFromProps()
+
+## 5.2.0
+
+### Minor Changes
+
+-   fa70c895: Add 'lang', 'className' and 'htmlFor' properties to Text and View
+
+### Patch Changes
+
+-   19ab0408: Update flowgen to convert React.ForwardRefExoticComponent<> and React.FowardedRef<> properly
+-   fa70c895: Remove all TypeScript error suppressions on JSX attributes
+
+## 5.1.0
+
+### Minor Changes
+
+-   3c400719: Add useLatestRef hook to wonder-blocks-core
+
+### Patch Changes
+
+-   a6164ed0: Don't use React.FC<> for functional components
+
+## 5.0.4
+
+### Patch Changes
+
+-   c20f48f3: Don't transpile classes when building bundles
+
+## 5.0.3
+
+### Patch Changes
+
+-   b281e2eb: Fix generate Flow types for real
+
+## 5.0.2
+
+### Patch Changes
+
+-   21ce20c7: Fix issues with generate flow types in wonder-blocks-core
+
+## 5.0.1
+
+### Patch Changes
+
+-   ccb6fe00: Miscellaneous TS type fixes
+-   d4c2b18c: Fix a variety of issues with Flow types generated by flowgen
+
+## 5.0.0
+
+### Major Changes
+
+-   1ca4d7e3: Fix minor issue with generate Flow types (this is a major bump b/c I forgot to do one after doing the TS conversion)
+
+## 4.9.1
+
+### Patch Changes
+
+-   b5ba5568: Ensure that flow lib defs use React.ElementConfig<> isntead of JSX.LibraryManagedAttributes<>
+
+## 4.9.0
+
+### Minor Changes
+
+-   779b031d: Update AriaProps to use React's AriaAttributes and AriaRole types
+
+## 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
+
+-   496119f2: Cleanup WB interdependencies
+
+## 4.6.1
+
+## 4.6.0
+
+### Minor Changes
+
+-   b561425a: Add useIsMounted() hook
+-   a566e232: Add useOnMountEffect hook
+-   d2b21a6e: Export useOnMountEffect hook
+
+## 4.5.0
+
+### Minor Changes
+
+-   175a2dd2: Add 'useRenderState' hook
+
+## 4.4.0
+
+### Minor Changes
+
+-   6ee20af9: Add `useOnline` hook to encapsulate navigator.onLine and the offline/online events
+
+## 4.3.2
+
+### Patch Changes
+
+-   5f4a4297: Make dependency on `flow-enums-runtime` explicit
+-   2b96fd59: Change flow-enums-runtime to be peer dependencies
+
+## 4.3.1
+
+## 4.3.0
+
+### Minor Changes
+
+-   246a921d: NEW: `useForceUpdate` hook. This should rarely be used and likely only ever from other hooks.
+
+## 4.2.1
+
+## 4.2.0
+
+### Minor Changes
+
+-   0aed8723: Adds `throwIfNested` required prop to `RenderStateRoot`.
+
+## 4.1.0
+
+### Minor Changes
+
+-   45588e5f: Fix an issue with `useUniqueIdWithMock`/`useUniqueIdWithoutMock`
+    rerender more than was needed. The fix introduces `<RenderStateRoot>`
+    which must be an ancestor to all components uses these hooks.
+-   875b7893: Nesting of `RenderStateRoot`s inside each other can result in extra renders
+    and potentially incorrect behavior. `RenderStateRoot` now throws if it
+    appears as a descendent of another `RenderStateRoot`.

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.ReactNode;
+    /**
+     * 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.ReactNode;
+}
+export {};

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

@@ -0,0 +1,23 @@
+import * as React from "react";
+export declare enum 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 const RenderStateContext: React.Context<RenderState>;
+export { RenderStateContext };

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: ({ children, throwIfNested, }: Props) => React.ReactElement;
+export { RenderStateRoot };

package/dist/components/text.d.ts

@@ -0,0 +1,66 @@
+import * as React from "react";
+/**
+ * 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 const Text: React.ForwardRefExoticComponent<{
+    children?: React.ReactNode;
+    style?: import("../util/types").StyleType;
+    testId?: string | undefined;
+    lang?: string | undefined;
+    className?: string | undefined;
+    htmlFor?: string | undefined;
+    tabIndex?: number | undefined;
+    id?: string | undefined;
+    title?: string | undefined;
+    "data-modal-launcher-portal"?: boolean | undefined;
+    "data-placement"?: string | undefined;
+} & Readonly<import("../util/aria-types").AriaAttributes> & Readonly<{
+    role?: import("../util/aria-types").AriaRole | undefined;
+}> & {
+    onMouseDown?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onMouseUp?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onMouseMove?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onClick?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onDoubleClick?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onMouseEnter?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onMouseLeave?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onMouseOut?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onMouseOver?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onDrag?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onDragEnd?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onDragEnter?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onDragExit?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onDragLeave?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onDragOver?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onDragStart?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+    onDrop?: ((e: React.MouseEvent<Element, MouseEvent>) => unknown) | undefined;
+} & {
+    onKeyDown?: ((e: React.KeyboardEvent<Element>) => unknown) | undefined;
+    onKeyPress?: ((e: React.KeyboardEvent<Element>) => unknown) | undefined;
+    onKeyUp?: ((e: React.KeyboardEvent<Element>) => unknown) | undefined;
+} & {
+    onChange?: ((e: React.ChangeEvent<HTMLInputElement>) => unknown) | undefined;
+    onInput?: ((e: React.ChangeEvent<HTMLInputElement>) => unknown) | undefined;
+    onInvalid?: ((e: React.ChangeEvent<HTMLInputElement>) => unknown) | undefined;
+    onSubmit?: ((e: React.ChangeEvent<HTMLInputElement>) => unknown) | undefined;
+} & {
+    onTouchCancel?: ((e: React.TouchEvent<Element>) => unknown) | undefined;
+    onTouchEnd?: ((e: React.TouchEvent<Element>) => unknown) | undefined;
+    onTouchMove?: ((e: React.TouchEvent<Element>) => unknown) | undefined;
+    onTouchStart?: ((e: React.TouchEvent<Element>) => unknown) | undefined;
+} & {
+    onFocus?: ((e: React.FocusEvent<Element, Element>) => unknown) | undefined;
+    onBlur?: ((e: React.FocusEvent<Element, Element>) => unknown) | undefined;
+} & {
+    tag?: string | undefined;
+} & React.RefAttributes<unknown>>;
+export default Text;

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.ReactNode;
+    /**
+     * 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.ReactNode;
+}
+export {};

package/dist/components/view.d.ts

@@ -0,0 +1,37 @@
+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;
+};
+/**
+ * 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 const View: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLElement>>;
+export default View;

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.ReactNode;
+    /**
+     * 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.ReactNode) | null;
+};
+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.ReactNode;
+}
+export {};