@kaizen/components 1.47.6 → 1.49.0

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

@@ -2,25 +2,43 @@
 @import "~@kaizen/design-tokens/sass/border";
 @import "~@kaizen/design-tokens/sass/color";
 @import "~@kaizen/design-tokens/sass/spacing";
+@import "~@kaizen/design-tokens/sass/typography";
+
+.editorLabel {
+  margin-bottom: $spacing-6;
+  display: inline-block;
+}
 
 .editableContainer :global(.ProseMirror) {
-  padding: $spacing-sm;
+  padding: calc($spacing-12 - $border-solid-border-width);
   position: relative;
   border-radius: $border-solid-border-radius;
-  border: $border-focus-ring-border-width $border-focus-ring-border-style
-    transparent;
+  border: $border-solid-border-width $border-solid-border-style $color-gray-500;
   transition:
     background-color $animation-duration-immediate,
     border-color $animation-duration-immediate;
-  background-color: $color-gray-200;
+  background-color: $color-white;
+  min-height: $typography-paragraph-body-line-height;
 }
 
 .editableContainer:hover :global(.ProseMirror) {
   background-color: $color-gray-200;
-  border-color: $color-blue-500;
 }
 
 .editableContainer .hiddenButton:focus-within + * > :global(.ProseMirror) {
-  border: $border-focus-ring-border-width $border-focus-ring-border-style
-    $color-blue-500;
+  background-color: $color-gray-200;
+
+  &::before {
+    $focus-ring-offset: calc((#{$border-focus-ring-border-width} * 2) + 1px);
+
+    pointer-events: none;
+    content: "";
+    position: absolute;
+    background: transparent;
+    border: $border-focus-ring-border-width $border-focus-ring-border-style
+      $color-blue-500;
+    border-radius: 10px;
+    inset: calc(-1 * #{$focus-ring-offset});
+    z-index: 1;
+  }
 }

package/src/RichTextEditor/EditableRichTextContent/EditableRichTextContent.tsx

@@ -37,7 +37,9 @@ export const EditableRichTextContent = ({
   ...restProps
 }: EditableRichTextContentProps): JSX.Element => (
   <>
-    {!isLabelHidden && <Label labelText={labelText} />}
+    {!isLabelHidden && (
+      <Label classNameOverride={styles.editorLabel} labelText={labelText} />
+    )}
     {/* Disabling these a11y linting errors because there is a <button> that mitigates these concerns. The onClick here is just an additional layer. */}
     {/* eslint-disable-next-line jsx-a11y/no-static-element-interactions, jsx-a11y/click-events-have-key-events */}
     <div

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

@@ -1,5 +1,5 @@
 import { Canvas, Controls, Meta } from "@storybook/blocks"
-import { ResourceLinks, KAIOInstallation, LinkTo } from "~storybook/components"
+import { ResourceLinks, KAIOInstallation } from "~storybook/components"
 import * as EditableRichTextContentStories from "./EditableRichTextContent.stories"
 
 <Meta of={EditableRichTextContentStories} />
@@ -15,15 +15,17 @@ import * as EditableRichTextContentStories from "./EditableRichTextContent.stori
 
 ## Overview
 
-To render the contents of your <LinkTo pageId="components-richtexteditor">RichTextEditor</LinkTo> using the same structure for both components.
+To render the contents of your [RichTextEditor](/docs/components-richtexteditor-richtexteditor--docs) using the same structure for both components.
 
 <Canvas of={EditableRichTextContentStories.Playground} />
 <Controls of={EditableRichTextContentStories.Playground} />
 
 ## Usage
 
-The general idea is to use this component in combination with the <LinkTo pageId="components-richtexteditor">RichTextEditor</LinkTo> to toggle between a read only state
-and an editable state.
+The `EditableRichTextContent` indicates interactivity similar to a `text` or `textarea` input and should be used in combination with the [RichTextEditor](/docs/components-richtexteditor-richtexteditor--docs) to toggle between inactive and editable states.
+
+This differs from the [RichTextContent](/docs/components-richtexteditor-richtextcontent--docs) component, which is used to render `RichTextEditor` content as read-only text.
+
 
 ```tsx
 const [editMode, setEditMode] = useState<boolean>(false);

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

@@ -0,0 +1,98 @@
+import React from "react"
+import { action } from "@storybook/addon-actions"
+import { Meta } from "@storybook/react"
+import {
+  StickerSheet,
+  StickerSheetStory,
+} from "~storybook/components/StickerSheet"
+import { EditableRichTextContent } from "../index"
+import defaultContent from "./defaultContent.json"
+
+const meta = {
+  title: "Components/RichTextEditor/EditableRichTextContent",
+  component: EditableRichTextContent,
+} satisfies Meta<typeof EditableRichTextContent>
+
+export default meta
+
+const StickerSheetTemplate: StickerSheetStory = {
+  render: () => (
+    <div>
+      <StickerSheet className="" heading="Pseudo states">
+        <StickerSheet.Body>
+          <StickerSheet.Row rowTitle="Default">
+            <StickerSheet.Cell className=" w-1/2">
+              <EditableRichTextContent
+                onClick={action("Toggle RTE")}
+                content={[]}
+                labelText="Label"
+              />
+            </StickerSheet.Cell>
+            <StickerSheet.Cell className=" w-1/2">
+              <EditableRichTextContent
+                onClick={action("Toggle RTE")}
+                content={defaultContent}
+                labelText="Label"
+              />
+            </StickerSheet.Cell>
+          </StickerSheet.Row>
+          <StickerSheet.Row rowTitle="Hover">
+            <StickerSheet.Cell className=" w-1/2">
+              <EditableRichTextContent
+                onClick={action("Toggle RTE")}
+                data-sb-pseudo-styles="hover"
+                content={[]}
+                labelText="Label"
+              />
+            </StickerSheet.Cell>
+            <StickerSheet.Cell className=" w-1/2">
+              <EditableRichTextContent
+                onClick={action("Toggle RTE")}
+                data-sb-pseudo-styles="hover"
+                content={defaultContent}
+                labelText="Label"
+              />
+            </StickerSheet.Cell>
+          </StickerSheet.Row>
+          <StickerSheet.Row rowTitle="Focus">
+            <StickerSheet.Cell className=" w-1/2">
+              <EditableRichTextContent
+                onClick={action("Toggle RTE")}
+                data-sb-pseudo-styles="focusWithin"
+                content={[]}
+                labelText="Label"
+              />
+            </StickerSheet.Cell>
+            <StickerSheet.Cell className=" w-1/2">
+              <EditableRichTextContent
+                onClick={action("Toggle RTE")}
+                data-sb-pseudo-styles="focusWithin"
+                content={defaultContent}
+                labelText="Label"
+              />
+            </StickerSheet.Cell>
+          </StickerSheet.Row>
+        </StickerSheet.Body>
+      </StickerSheet>
+    </div>
+  ),
+  parameters: {
+    pseudo: {
+      hover: ['[data-sb-pseudo-styles="hover"]'],
+      focusWithin: [
+        '[data-sb-pseudo-styles="focusWithin"] > [class^="VisuallyHidden"]',
+      ],
+    },
+  },
+}
+
+export const StickerSheetDefault: StickerSheetStory = {
+  ...StickerSheetTemplate,
+  name: "Sticker Sheet (Default)",
+}
+
+export const StickerSheetRTL: StickerSheetStory = {
+  ...StickerSheetTemplate,
+  name: "Sticker Sheet (RTL)",
+  parameters: { textDirection: "rtl" },
+}

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

@@ -8,14 +8,14 @@ import {
   RichTextEditorProps,
 } from "../../index"
 import { EditableRichTextContent } from "../index"
-import dummyContent from "./dummyContent.json"
+import defaultContent from "./defaultContent.json"
 
 const meta = {
   title: "Components/RichTextEditor/EditableRichTextContent",
   component: EditableRichTextContent,
   args: {
-    content: dummyContent,
-    labelText: "Editable rich text content",
+    content: [],
+    labelText: "Label",
     onClick: fn(),
   },
   argTypes: {
@@ -32,7 +32,7 @@ const EditableRichTextContentTemplate: Story = {
   render: props => {
     const [editMode, setEditMode] = useState<boolean>(false)
     const [readRteData, setReadRTEData] = useState<EditorContentArray>(
-      props.content || dummyContent
+      props.content
     )
     const [editRteData, setEditRTEData] = useState<EditorContentArray>([])
 
@@ -65,7 +65,7 @@ const EditableRichTextContentTemplate: Story = {
             defaultValue={editRteData}
             onChange={handleOnChange}
           />
-          <div className="flex justify-end mt-8">
+          <div className="flex justify-end mt-12 gap-8">
             <Button label="Cancel" secondary onClick={handleCancel} />
             <Button label="Save" primary onClick={handleSave} />
           </div>
@@ -81,6 +81,9 @@ const EditableRichTextContentTemplate: Story = {
       />
     )
   },
+  args: {
+    content: defaultContent,
+  },
 }
 
 export const Playground: Story = {

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

@@ -0,0 +1,11 @@
+[
+  {
+    "type": "paragraph",
+    "content": [
+      {
+        "type": "text",
+        "text": "User text goes here"
+      }
+    ]
+  }
+]

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} />
+