@wistia/rich-text-editor 0.0.0-stage → 0.0.0

package/README.md

@@ -1,3 +1,149 @@
-# Temporary Holding Version
+# @wistia/rich-text-editor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A rich text editor for Wistia apps. It is built on [Slate](https://docs.slatejs.org/).
+
+## Installation
+
+```sh
+yarn add @wistia/rich-text-editor
+```
+
+The package needs these peer dependencies: `react`, `react-dom`, and `styled-components` 6.
+
+## Fonts
+
+The editor does not load a font. Render it inside `UIProvider` from `@wistia/ui` or `VHSProvider`
+from `@wistia/vhs`:
+
+- `UIProvider` defines `--wui-typography-family-default`. The editor uses that font.
+- `VHSProvider` sets the Wistia font on `body`. The editor inherits it.
+
+Without a provider, the editor inherits the font of the page. To choose a font yourself, set
+`--rte-font-family` on the editor or on a parent.
+
+## Usage
+
+```tsx
+import { RichTextEditor } from '@wistia/rich-text-editor';
+
+<RichTextEditor
+  aria-label="Description"
+  defaultValue="<p>Join us for a <strong>live tour</strong>.</p>"
+  onBlur={(nodes) => save(nodes)}
+/>;
+```
+
+Give the editor a name. Use `aria-label`, `aria-labelledby`, or a `<label for>` that points at its
+`id`.
+
+`defaultValue` takes an HTML string or editor nodes. The editor reads it on the first render only.
+
+The editor reads HTML with the browser's `DOMParser`. On a server, `DOMParser` does not exist, so
+an HTML `defaultValue` and `rteDeserializeHTML` throw there. For server rendering, give editor nodes,
+or render the editor in the browser only.
+
+## Forms
+
+With `name`, the editor adds a hidden input. Its value is the content as HTML. A native form
+submission and `FormData` include it.
+
+```tsx
+<form onSubmit={handleSubmit}>
+  <RichTextEditor
+    aria-label="Description"
+    name="description"
+  />
+</form>
+```
+
+Inside a `FormField` from `@wistia/ui`, the field gives the editor its `id`, `name`, and
+description. The label names the editor. A click on the label puts the cursor in the editor.
+
+```tsx
+<Form
+  action={save}
+  aria-label="Event details"
+>
+  <FormField
+    description="Shown on the registration page"
+    label="Description"
+    name="description"
+  >
+    <RichTextEditor />
+  </FormField>
+</Form>
+```
+
+A disabled editor does not send its content with the form.
+
+## Controlled content
+
+Use `value` and `onChange` to keep the content in state. The editor reads `value` on the first
+render. After that, it reads `value` again only in two cases:
+
+- `value` is the empty value: `[{ type: 'paragraph', children: [{ text: '' }] }]`.
+- `useExternalValue` is `true`. Set it when code outside the editor changes the content, for
+  example a reset button.
+
+The editor skips a `value` that matches content it sent through `onChange` in the last 10 seconds.
+So a slow save that sends an older `onChange` value back does not undo typing or move the cursor.
+
+## HTML
+
+`onChange` and `onBlur` give editor nodes. Two helpers change nodes to HTML and back:
+
+```ts
+import { rteDeserializeHTML, rteSerializeToHTML } from '@wistia/rich-text-editor';
+
+const html = rteSerializeToHTML(nodes);
+const nodesAgain = rteDeserializeHTML(html);
+```
+
+## Formats
+
+`enabledFormats` sets the toolbar buttons. Without it, the toolbar shows every format.
+
+```tsx
+<RichTextEditor
+  aria-label="Description"
+  enabledFormats={['BOLD', 'ITALIC', 'HEADING_1', 'LINK', 'BULLETED_LIST']}
+/>
+```
+
+`rteFormatTypes` lists every format: `BOLD`, `ITALIC`, `UNDERLINE`, `STRIKETHROUGH`, `HEADING_1`,
+`HEADING_2`, `BLOCKQUOTE`, `NUMBERED_LIST`, `BULLETED_LIST`, `LINK`, and `IMAGE`. The order of the
+list does not change the order of the toolbar.
+
+- `LINK`: select text, then click the button. The editor asks for a URL. Links open in a new tab.
+- `IMAGE`: click the button. The editor asks for an image URL and adds the image as its own block.
+  The URL must contain one of `jpg`, `jpeg`, `png`, `gif`, `webp`, `avif`, `svg`, `tiff`, `bmp`, or
+  `dcm`. If it does not, the editor shows a message and does not change. To remove an image, select
+  it and press Backspace or Delete.
+
+## Custom properties
+
+Set these CSS custom properties on the editor (`style` or `className`) or on any parent:
+
+| Property                      | Default              | Changes                                                    |
+| ----------------------------- | -------------------- | ---------------------------------------------------------- |
+| `--rte-accent-color`          | `#2949e5`            | links, active toolbar buttons, the selected image line     |
+| `--rte-background`            | `#fff`               | the background of the text area and toolbar                |
+| `--rte-border-color`          | `#c4c4c8`            | the outer border and the line below the toolbar            |
+| `--rte-border-radius`         | `4px`                | the corners of the outer border                            |
+| `--rte-focus-color`           | `--rte-accent-color` | the outline of the outer box while the text area has focus |
+| `--rte-font-family`           | the provider font    | the font of the content                                    |
+| `--rte-icon-color`            | `#62626c`            | inactive toolbar buttons                                   |
+| `--rte-text-color`            | `#37373c`            | the content                                                |
+| `--rte-toolbar-button-radius` | `1000px`             | the corners of toolbar buttons                             |
+
+## Development
+
+Run these commands from the root of the repository:
+
+```sh
+yarn storybook:rich-text-editor
+yarn vp run @wistia/rich-text-editor#test
+yarn vp run @wistia/rich-text-editor#typecheck
+```
+
+Storybook runs at <http://127.0.0.1:6009>.

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+
+import { AriaAttributes, CSSProperties, FC } from "react";
+import { Editor } from "slate";
+import "slate-history";
+import { ReactEditor } from "slate-react";
+//#region src/components/RichTextEditor/types.d.ts
+type NodeElementObject = {
+  attributes?: Record<string, string>;
+  children?: NodeLeafObject[];
+  type?: string;
+  url?: string;
+};
+type NodeObject = NodeElementObject | NodeLeafObject;
+type NodeLeafObject = {
+  attributes?: Record<string, string>;
+  bold?: boolean;
+  code?: boolean;
+  italic?: boolean;
+  parent?: NodeObject;
+  children?: NodeLeafObject[];
+  strikethrough?: boolean;
+  text?: string;
+  type?: string;
+  url?: string;
+  underline?: boolean;
+};
+//#endregion
+//#region src/components/RichTextEditor/utilities/rteFormatTypes.d.ts
+export declare const rteFormatTypes: {
+  readonly BOLD: "BOLD";
+  readonly ITALIC: "ITALIC";
+  readonly UNDERLINE: "UNDERLINE";
+  readonly STRIKETHROUGH: "STRIKETHROUGH";
+  readonly HEADING_1: "HEADING_1";
+  readonly HEADING_2: "HEADING_2";
+  readonly BLOCKQUOTE: "BLOCKQUOTE";
+  readonly NUMBERED_LIST: "NUMBERED_LIST";
+  readonly BULLETED_LIST: "BULLETED_LIST";
+  readonly LINK: "LINK";
+  readonly IMAGE: "IMAGE";
+};
+//#endregion
+//#region src/components/RichTextEditor/RichTextEditor.d.ts
+type RichTextEditorProps = AriaAttributes & {
+  /**
+   * Same as `aria-labelledby`. `aria-labelledby` wins when both are set.
+   */
+  ariaLabelledBy?: string | undefined;
+  /**
+   * Class name for the outer box (border, toolbar, and text area)
+   */
+  className?: string | undefined;
+  /**
+   * Test id for the outer box
+   */
+  "data-testid"?: string;
+  /**
+   * Starting content when `value` is not set: an HTML string or editor nodes.
+   * The editor does not read it again after the first render.
+   */
+  defaultValue?: NodeObject[] | string | undefined;
+  /**
+   * Determines whether editor is clickable/read-only
+   */
+  disabled?: boolean;
+  /**
+   * Formats to enable in editor, restricted to rteFormatTypes
+   */
+  enabledFormats?: (keyof typeof rteFormatTypes)[];
+  /**
+   * Custom height of editor
+   */
+  height?: string | undefined;
+  /**
+   * Id of the text area. A `<label for>` with this id names the text area and focuses it on click.
+   */
+  id?: string | undefined;
+  /**
+   * Adds a hidden input with this name. Its value is the content as HTML, so a native form
+   * submission or `FormData` includes it.
+   */
+  name?: string | undefined;
+  /**
+   * Function to be called when editor loses focus
+   */
+  onBlur?: ((value: NodeElementObject[]) => void) | undefined;
+  /**
+   * Function to be called after editor state update
+   */
+  onChange?: ((value: NodeElementObject[]) => void) | undefined;
+  /**
+   * Placeholder text
+   */
+  placeholder?: string;
+  /**
+   * Inline styles for the outer box
+   */
+  style?: CSSProperties | undefined;
+  /**
+   * Whether to update the editor when the value prop changes
+   */
+  useExternalValue?: boolean;
+  /**
+   * Content of the editor. The editor reads it on the first render. After that, it reads it again
+   * when it is the empty value (to clear the editor), or when `useExternalValue` is true.
+   */
+  value?: NodeObject[] | undefined;
+};
+export declare const RichTextEditor: FC<RichTextEditorProps>;
+//#endregion
+//#region src/components/RichTextEditor/serializers.d.ts
+export declare const rteSerializeToHTML: (value: NodeObject[]) => string | null;
+export declare const rteDeserializeHTML: (htmlString: string) => (NodeObject | string | null)[] | NodeObject | string | null | undefined;
+//#endregion
+export type { NodeElementObject, NodeLeafObject, NodeObject, RichTextEditorProps };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/components/RichTextEditor/types.ts","../src/components/RichTextEditor/utilities/rteFormatTypes.ts","../src/components/RichTextEditor/RichTextEditor.tsx","../src/components/RichTextEditor/serializers.ts"],"mappings":";;;;;;KAIY;EACV,aAAa;EACb,WAAW;EACX;EACA;;KAGU,aAAa,oBAAoB;KAEjC;EACV,aAAa;EACb;EACA;EACA;EACA,SAAS;EACT,WAAW;EACX;EACA;EACA;EACA;EACA;;;;qBCxBW;WACF;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;;;;KCyDC,sBAAsB;;;;EAIhC;;;;EAIA;;;;EAIA;;;;;EAKA,eAAe;;;;EAIf;;;;EAIA,+BAA+B;;;;EAI/B;;;;EAIA;;;;;EAKA;;;;EAIA,WAAW,OAAO;;;;EAIlB,aAAa,OAAO;;;;EAIpB;;;;EAIA,QAAQ;;;;EAIR;;;;;EAKA,QAAQ;;qBAgBG,gBAAgB,GAAG;;;qBCXnB,qBAAsB,OAAO;qBAgP7B,qBACX,wBACE,gCAAgC"}