@kaizen/components 1.48.0 → 1.49.1

package/src/RichTextEditor/EditableRichTextContent/_docs/dummyContent.json

@@ -1,11 +1,50 @@
 [
+  {
+    "type": "paragraph",
+    "content": [
+      {
+        "type": "text",
+        "text": "User text goes here"
+      }
+    ]
+  },
   {
     "type": "paragraph",
     "content": [
       {
         "type": "text",
         "marks": [{ "type": "strong" }],
-        "text": "Some notes I'd like to share in bold text:"
+        "text": "bold"
+      }
+    ]
+  },
+  {
+    "type": "paragraph",
+    "content": [
+      {
+        "type": "text",
+        "marks": [{ "type": "em" }],
+        "text": "underline"
+      }
+    ]
+  },
+  {
+    "type": "paragraph",
+    "content": [
+      {
+        "type": "text",
+        "text": "link",
+        "marks": [
+          {
+            "type": "link",
+            "attrs": {
+              "href": "https://cultureamp.design",
+              "_metadata": null,
+              "target": "_blank",
+              "rel": "noreferrer"
+            }
+          }
+        ]
       }
     ]
   },
@@ -17,24 +56,7 @@
         "content": [
           {
             "type": "paragraph",
-            "content": [
-              { "type": "text", "text": "Note 1 " },
-              {
-                "type": "text",
-                "marks": [
-                  {
-                    "type": "link",
-                    "attrs": {
-                      "href": "https://cultureamp.design",
-                      "_metadata": null,
-                      "target": "_blank",
-                      "rel": "noreferrer"
-                    }
-                  }
-                ],
-                "text": "with link"
-              }
-            ]
+            "content": [{ "type": "text", "text": "Bullet list" }]
           },
           {
             "type": "bulletList",
@@ -73,29 +95,12 @@
         "content": [
           {
             "type": "paragraph",
-            "content": [
-              { "type": "text", "text": "Another really " },
-              {
-                "type": "text",
-                "marks": [{ "type": "underline" }],
-                "text": "important note"
-              },
-              { "type": "text", "text": " " },
-              {
-                "type": "text",
-                "marks": [{ "type": "em" }],
-                "text": "(that I'd like to emphasise)"
-              }
-            ]
+            "content": [{ "type": "text", "text": "List item" }]
           }
         ]
       }
     ]
   },
-  {
-    "type": "paragraph",
-    "content": [{ "type": "text", "text": "Additionally:" }]
-  },
   {
     "type": "orderedList",
     "attrs": { "order": 1 },
@@ -105,7 +110,7 @@
         "content": [
           {
             "type": "paragraph",
-            "content": [{ "type": "text", "text": "Point one" }]
+            "content": [{ "type": "text", "text": "Numbered list" }]
           },
           {
             "type": "orderedList",
@@ -149,7 +154,7 @@
         "content": [
           {
             "type": "paragraph",
-            "content": [{ "type": "text", "text": "Point two" }]
+            "content": [{ "type": "text", "text": "List item" }]
           }
         ]
       }

package/src/RichTextEditor/RichTextContent/_docs/RichTextContent.mdx

@@ -15,7 +15,17 @@ import * as RichTextContentStories from "./RichTextContent.stories"
 
 ## Overview
 
-To render your rich text content data structure as read-only text.
+To render rich content as it appears in the [RichTextEditor](/docs/components-richtexteditor-richtexteditor--docs) in read-only format.
 
 <Canvas of={RichTextContentStories.Playground} />
 <Controls of={RichTextContentStories.Playground} />
+
+
+## Usage
+
+A common use case of `RichTextContent` is to display user generated output as read-only text.
+
+<Canvas of={RichTextContentStories.ReadOnly} />
+
+This should not be used out of the box to toggle between active and inactive states of the `RichTextEditor`. Instead we recommend using the [EditableRichTextContent](/docs/components-richtexteditor-editablerichtextcontent--docs#usage) pattern, which indicates interactivity to the user and ensures compliance with WCAG guidelines.
+

package/src/RichTextEditor/RichTextContent/_docs/RichTextContent.stories.tsx

@@ -1,12 +1,23 @@
+import React from "react"
 import { Meta, StoryObj } from "@storybook/react"
+import { Text } from "~components/Text"
 import { RichTextContent } from "../index"
-import dummyContent from "./dummyContent.json"
 
 const meta = {
   title: "Components/RichTextEditor/RichTextContent",
   component: RichTextContent,
   args: {
-    content: dummyContent,
+    content: [
+      {
+        type: "paragraph",
+        content: [
+          {
+            type: "text",
+            text: "User text goes here",
+          },
+        ],
+      },
+    ],
   },
   argTypes: {
     content: { control: false },
@@ -22,3 +33,37 @@ export const Playground: Story = {
     chromatic: { disable: false },
   },
 }
+
+export const ReadOnly: Story = {
+  parameters: {
+    chromatic: { disable: false },
+  },
+  args: {
+    content: [
+      {
+        type: "paragraph",
+        content: [
+          {
+            type: "text",
+            text: "User text goes here",
+          },
+        ],
+      },
+    ],
+  },
+  render: args => (
+    <>
+      {/* Note that since RichTextContent is not content editable, it is essentially just a div. This is why we haven't used the Label component */}
+      <Text
+        variant="small"
+        tag="div"
+        classNameOverride="block mb-6 leading-paragraph font-weight-heading"
+      >
+        Read only state
+      </Text>
+      <div className="p-12 bg-gray-200 rounded-default">
+        <RichTextContent {...args} />
+      </div>
+    </>
+  ),
+}

package/src/RichTextEditor/RichTextEditor/RichTextEditor.module.scss

@@ -16,7 +16,7 @@
     border-color $animation-duration-immediate;
 
   &:hover,
-  &:focus {
+  &:focus-visible {
     border-color: $color-gray-600;
     background: $color-gray-200;
   }
@@ -46,6 +46,11 @@
   border-top-right-radius: 0;
 }
 
+.editorLabel {
+  margin-bottom: $spacing-6;
+  display: inline-block;
+}
+
 /* stylelint-disable no-descending-specificity */
 .editorWrapper {
   position: relative;

package/src/RichTextEditor/RichTextEditor/RichTextEditor.spec.stories.tsx

@@ -147,3 +147,51 @@ export const IncreaseIndent: Story = {
     })
   },
 }
+
+export const CreateALink: Story = {
+  ...TestBase,
+  name: "Create a link",
+  play: async context => {
+    const { canvasElement, step } = context
+    const { getByRole, getByText } = within(canvasElement)
+    const editor = getByRole("textbox")
+    await step("Focus on editor", async () => {
+      await userEvent.click(editor)
+      expect(editor).toHaveFocus()
+    })
+
+    await step("Input text and select the first word", async () => {
+      await userEvent.keyboard("Link me")
+      await userEvent.pointer([
+        {
+          target: getByText("Link me"),
+          offset: 0,
+          keys: "[MouseLeft>]",
+        },
+        { offset: 4 },
+      ])
+    })
+
+    await step("click the link button", async () => {
+      await userEvent.click(getByRole("button", { name: "Link" }))
+    })
+
+    // wait for the transition to end and focus to shift
+    await new Promise(resolve => setTimeout(resolve, 500))
+
+    await step("Enter text", async () => {
+      await userEvent.keyboard("https://www.google.com")
+    })
+
+    await new Promise(resolve => setTimeout(resolve, 500))
+
+    await step("Tab and save", async () => {
+      await userEvent.keyboard("{Tab}{Enter}")
+    })
+
+    await step("Link exists in the RTE", async () => {
+      const link = getByRole("link", { name: "Link" })
+      expect(link).toBeInTheDocument()
+    })
+  },
+}

package/src/RichTextEditor/RichTextEditor/RichTextEditor.tsx

@@ -159,8 +159,13 @@ export const RichTextEditor = ({
 
   return (
     <>
-      {!labelledBy && labelText && <Label id={labelId} labelText={labelText} />}
-      {/* TODO: add a bit of margin here once we have a classNameOverride on Label */}
+      {!labelledBy && labelText && (
+        <Label
+          classNameOverride={styles.editorLabel}
+          id={labelId}
+          labelText={labelText}
+        />
+      )}
       <div className={classnames(styles.editorWrapper, styles[status])}>
         {controls && (
           <Toolbar

package/src/RichTextEditor/RichTextEditor/_docs/RichTextEditor.mdx

@@ -1,5 +1,7 @@
 import { Canvas, Controls, DocsStory, Meta } from "@storybook/blocks"
 import { ResourceLinks, KAIOInstallation } from "~storybook/components"
+import * as EditableRichTextContentStories from "../../EditableRichTextContent/_docs/EditableRichTextContent.stories"
+import * as RichTextContentStories from "../../RichTextContent/_docs/RichTextContent.stories"
 import * as RichTextEditorStories from "./RichTextEditor.stories"
 
 <Meta of={RichTextEditorStories} />
@@ -24,21 +26,78 @@ A text area with additional capabilities for users to format the input text.
 
 ## API
 
-<DocsStory of={RichTextEditorStories.Controls} />
+### Controls
 
-### Default Value
-Note: In order to provide the RichTextEditor with a default value that contains rich text you must also apply the corresponding controls.
-eg. if your default text contains Bold text, you must add the Bold control
+`controls` accepts an array of `ToolbarItems` that are used to create the `RichTextEditor` schema and build out its core functionality. It also offers the ability to group the items in the toolbar.
+
+<Canvas of={RichTextEditorStories.Controls} />
+
+As the schema is defined by the `controls`, removing an item will remove its functionality from the `RichTextEditor`.
+
+<Canvas of={RichTextEditorStories.ControlsWithoutBold} />
+
+With all controls, the Kaizen `RichTextEditor` can create and render formatted text, lists, and links.
+
+<Canvas of={RichTextEditorStories.AllAvailableContent} />
+
+
+### The EditorContentArray and defaultValue
+
+The `defaultValue` is the initial content of the `RichTextEditor`. It accepts an array of objects in the [ProseMirror's rich text format](https://cultureamp.atlassian.net/wiki/spaces/TV/pages/3380543671/ProseMirror+rich+formatted+text+data+format).
 
 <Canvas of={RichTextEditorStories.DefaultValue} />
 
-#### Malformed Content
-If your default value does not conform correctly, the RTE will throw an error.
+As mentioned in the previous section, the data (`EditorContentArray`) that is passed to the `defaultValue` must be able to map to the `controls` provided.
+
+For example: if your `defaultValue` contains bolded text, you must pass bold into your `controls`.
+
+```
+<RichTextEditor
+  labelText="Rich text"
+  defaultValue={rteData}
+  onChange={handleOnChange}
+  controls: [
+    { name: "bold", group: "inline" },
+    {/* other controls */}
+  ]
+/>
+```
+
+### Data errors and onDataError
+When content is passed to the `defaultValue` that does not match to the `RichTextEditor`'s [schema](https://github.com/cultureamp/kaizen-design-system/blob/main/packages/components/src/RichTextEditor/RichTextEditor/schema.ts), the component will throw and render a generic error.
 
 <Canvas of={RichTextEditorStories.MalformedContent} />
 
-<DocsStory of={RichTextEditorStories.Rows} />
+This will also throw if you have passed in an `EditorContentArray` that contains data that cannot map to the `controls` provided to the component.
+
+<Canvas of={RichTextEditorStories.IncorrectDataForControls}/>
+
+The `dataError` React Node and `onDataError` callback also allows you to handle these edge cases without breaking the page.
+
+### Rows
+
+Sets the minimum height for the editable area of the RichTextEditor.
+
+<Canvas of={RichTextEditorStories.Rows} />
 
 <DocsStory of={RichTextEditorStories.Description} />
 
 <DocsStory of={RichTextEditorStories.Validation} />
+
+
+### Inactive states and read-only text
+
+In addition to the `RichTextEditor`, there are two additional Kaizen components that support rendering data in the RTE format.
+
+#### EditableRichTextContent
+
+For rendering editable content that can toggle between an active and inactive state we recommend the [EditableRichTextContent](/docs/components-richtexteditor-editablerichtextcontent--docs).
+
+<Canvas of={EditableRichTextContentStories.UsageExample} />
+
+#### RichTextContent
+
+For rendering content as read-only text we recommend using the [RichTextContent](/docs/components-richtexteditor-richtextcontent--docs).
+
+<Canvas of={RichTextContentStories.Playground} />
+

package/src/RichTextEditor/RichTextEditor/_docs/RichTextEditor.stories.tsx

@@ -1,5 +1,7 @@
 import React, { useState } from "react"
 import { Meta, StoryObj } from "@storybook/react"
+import { fn } from "@storybook/test"
+import dummyContent from "../../EditableRichTextContent/_docs/dummyContent.json"
 import { EditorContentArray } from "../../index"
 import { RichTextEditor, RichTextEditorProps } from "../index"
 
@@ -77,9 +79,26 @@ export const Controls: Story = {
       { name: "bold", group: "inline" },
       { name: "italic", group: "inline" },
       { name: "underline", group: "inline" },
-      { name: "orderedList", group: "list" },
-      { name: "bulletList", group: "list" },
-      { name: "link", group: "link" },
+    ],
+  },
+}
+
+export const ControlsWithoutBold: Story = {
+  args: {
+    controls: [
+      { name: "italic", group: "inline" },
+      { name: "underline", group: "inline" },
+    ],
+    defaultValue: [
+      {
+        type: "paragraph",
+        content: [
+          {
+            type: "text",
+            text: "This user text cannot be bolded",
+          },
+        ],
+      },
     ],
   },
 }
@@ -92,7 +111,7 @@ export const DefaultValue: Story = {
         content: [
           {
             type: "text",
-            text: "Some notes I'd like to share",
+            text: "User text goes here",
           },
         ],
       },
@@ -100,6 +119,20 @@ export const DefaultValue: Story = {
   },
 }
 
+export const AllAvailableContent: Story = {
+  args: {
+    defaultValue: dummyContent,
+    controls: [
+      { name: "bold", group: "inline" },
+      { name: "italic", group: "inline" },
+      { name: "underline", group: "inline" },
+      { name: "orderedList", group: "list" },
+      { name: "bulletList", group: "list" },
+      { name: "link", group: "link" },
+    ],
+  },
+}
+
 export const Rows: Story = {
   args: {
     labelText: "1 Row",
@@ -109,13 +142,13 @@ export const Rows: Story = {
 
 export const Description: Story = {
   args: {
-    description: "I am a rich text editor",
+    description: "Description text",
   },
 }
 
 export const Validation: Story = {
   args: {
-    validationMessage: "something went wrong",
+    validationMessage: "Error message",
     status: "error",
   },
 }
@@ -129,10 +162,30 @@ export const MalformedContent: Story = {
           {
             type: "text",
             marks: [{ type: "strong" }],
-            text: "Some notes I'd like to share in bold text:",
+            text: "User text goes here in bold text",
+          },
+        ],
+      },
+    ],
+  },
+}
+
+export const IncorrectDataForControls: Story = {
+  args: {
+    defaultValue: [
+      {
+        type: "paragraph",
+        content: [
+          {
+            type: "text",
+            marks: [{ type: "strong" }],
+            text: "User text goes here in bold text",
           },
         ],
       },
     ],
+    controls: [{ name: "italic", group: "inline" }],
+    dataError: <>Cannot bold text without a bold control</>,
+    onDataError: () => fn(),
   },
 }

package/src/RichTextEditor/_mixins.scss

@@ -11,6 +11,7 @@
   position: relative;
   white-space: pre-wrap;
   box-sizing: content-box;
+  color: $color-purple-800;
 
   > p {
     margin: 0 0 $spacing-16;

package/src/RichTextEditor/utils/plugins/LinkManager/components/LinkModal/LinkModal.module.scss

@@ -0,0 +1,5 @@
+.validationErrorMessage {
+  ul {
+    margin-bottom: 0;
+  }
+}

package/src/RichTextEditor/utils/plugins/LinkManager/components/LinkModal/LinkModal.spec.stories.tsx

@@ -0,0 +1,37 @@
+import { Meta, StoryObj } from "@storybook/react"
+import { userEvent, waitFor, fn, expect } from "@storybook/test"
+import { LinkModal } from "./LinkModal"
+
+const meta = {
+  title: "Components/RichTextEditor/Subcomponents/LinkModal/Tests",
+  component: LinkModal,
+  args: {
+    onSubmit: fn(),
+    onDismiss: fn(),
+    onAfterLeave: fn(),
+    isOpen: true,
+  },
+} satisfies Meta<typeof LinkModal>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const InvalidLink: Story = {
+  parameters: {
+    chromatic: { disable: false },
+  },
+  args: {
+    defaultHref: "google.com",
+  },
+  play: async () => {
+    await new Promise(resolve => setTimeout(resolve, 500))
+    await userEvent.keyboard("{Tab}{Enter}")
+
+    await waitFor(() => {
+      expect(document.activeElement).toHaveAccessibleDescription(
+        /Empty or invalid link\. Links must start with http or https/
+      )
+    })
+  },
+}

package/src/RichTextEditor/utils/plugins/LinkManager/components/LinkModal/LinkModal.stories.tsx

@@ -0,0 +1,33 @@
+import { Meta, StoryObj } from "@storybook/react"
+import { fn } from "@storybook/test"
+import { LinkModal } from "./LinkModal"
+
+const meta = {
+  title: "Components/RichTextEditor/Subcomponents/LinkModal",
+  component: LinkModal,
+  args: {
+    onSubmit: fn(),
+    onDismiss: fn(),
+    onAfterLeave: fn(),
+    isOpen: true,
+  },
+} satisfies Meta<typeof LinkModal>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const AddLink: Story = {
+  parameters: {
+    chromatic: { disable: false },
+  },
+}
+
+export const EditLink: Story = {
+  parameters: {
+    chromatic: { disable: false },
+  },
+  args: {
+    defaultHref: "http://google.com",
+  },
+}

package/src/RichTextEditor/utils/plugins/LinkManager/components/LinkModal/LinkModal.tsx

@@ -2,6 +2,7 @@ import React, { useRef, useState } from "react"
 import { InputEditModal } from "~components/Modal"
 import { TextField } from "~components/TextField"
 import { ValidationResponse, validateLink } from "../../validation"
+import styles from "./LinkModal.module.scss"
 
 type LinkModalProps = {
   onSubmit: (href: string) => void
@@ -51,8 +52,15 @@ export const LinkModal = ({
         type="text"
         defaultValue={href ?? ""}
         labelText="Link URL"
+        description="Must start with http:// or https://"
         inputRef={inputRef}
-        validationMessage={validationStatus.message}
+        validationMessage={
+          validationStatus?.message && (
+            <div className={styles.validationErrorMessage}>
+              {validationStatus.message}
+            </div>
+          )
+        }
         status={validationStatus.status}
         onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
           setHref(e.target.value)

package/src/RichTextEditor/utils/plugins/LinkManager/{validation.ts → validation.tsx}

@@ -1,3 +1,5 @@
+import React from "react"
+
 export type ValidationResponse = {
   status: "success" | "error" | "default"
   message?: React.ReactNode
@@ -9,7 +11,15 @@ export const validateLink = (href: string): ValidationResponse => {
   if (!isValidLink) {
     return {
       status: "error",
-      message: "Please enter a valid URL",
+      message: (
+        <>
+          Empty or invalid link. Links must start with http or https, e.g:
+          <ul>
+            <li>https://google.com</li>
+            <li>http://www.google.com</li>
+          </ul>
+        </>
+      ),
     }
   }
 

package/src/Select/Select.tsx

@@ -35,6 +35,11 @@ export type SelectProps = {
    * @default false
    */
   fullWidth?: boolean
+  /**
+   * @deprecated Use of placeholder text goes against our a11y standards.
+   * Use the `labelText` prop to provide a concise name, and the `description` prop for any help text.
+   */
+  placeholder?: string
 } & ReactSelectProps<any, boolean>
 
 /**
@@ -53,6 +58,7 @@ export const Select = React.forwardRef<any, SelectProps>(
       fullWidth: propsFullWidth,
       className: propsClassName,
       isDisabled,
+      placeholder,
       ...props
     },
     ref
@@ -92,6 +98,7 @@ export const Select = React.forwardRef<any, SelectProps>(
           {...props}
           ref={ref}
           aria-labelledby={labelId}
+          placeholder={placeholder || ""}
           components={{
             Control,
             Placeholder,
@@ -126,12 +133,13 @@ interface AsyncProps
 
 export const AsyncSelect = React.forwardRef(
   (
-    { className: propsClassName, ...props }: AsyncProps,
+    { className: propsClassName, placeholder, ...props }: AsyncProps,
     ref: React.Ref<any>
   ) => (
     <Async
       {...props}
       ref={ref}
+      placeholder={placeholder || ""}
       components={{
         Control,
         Placeholder,