@kaizen/components 3.2.0 → 3.3.0

package/dist/types/Focusable/Focusable.d.ts

@@ -1,6 +1,11 @@
-import { type HTMLAttributes, type ReactNode } from 'react';
+import { type ElementType, type HTMLAttributes, type ReactNode } from 'react';
 import { type FocusableOptions } from 'react-aria';
-export type FocusableProps = {
+export type FocusableProps<T extends ElementType = 'div'> = {
     children: ReactNode;
+    /**
+     * The HTML element to render as. Defaults to `div` to avoid an api change
+     * but should be set to 'span' if rendering within something like a 'p' tag to avoid invalid HTML.
+     */
+    tag?: T;
 } & FocusableOptions & HTMLAttributes<HTMLDivElement>;
-export declare const Focusable: ({ children, className, ...props }: FocusableProps) => JSX.Element;
+export declare const Focusable: <T extends ElementType = "div">({ children, className, tag, ...props }: FocusableProps<T>) => JSX.Element;

package/dist/types/MultiSelect/MultiSelect.d.ts

@@ -1,9 +1,10 @@
-import { type HTMLAttributes } from 'react';
+import React, { type HTMLAttributes } from 'react';
 import { type FieldMessageProps } from "../FieldMessage";
 import { type OverrideClassName } from "../types/OverrideClassName";
 import { type MultiSelectOptionsProps } from './subcomponents/MultiSelectOptions';
 import { type MultiSelectOption, type ValidationMessage } from './types';
 export type MultiSelectProps = {
+    inputRef?: React.Ref<HTMLButtonElement>;
     label: string;
     items: MultiSelectOptionsProps['options'];
     selectedValues: Set<MultiSelectOption['value']>;
@@ -18,6 +19,6 @@ export type MultiSelectProps = {
     validationMessage?: ValidationMessage;
 } & OverrideClassName<HTMLAttributes<HTMLDivElement>>;
 export declare const MultiSelect: {
-    ({ id: propsId, label, items, selectedValues, description, onSelectedValuesChange, isOpen, onOpenChange, classNameOverride, validationMessage, ...restProps }: MultiSelectProps): JSX.Element;
+    ({ id: propsId, label, items, selectedValues, description, onSelectedValuesChange, isOpen, onOpenChange, classNameOverride, validationMessage, inputRef, ...restProps }: MultiSelectProps): JSX.Element;
     displayName: string;
 };

package/dist/types/Notification/index.d.ts

@@ -1,3 +1,4 @@
 export * from './InlineNotification';
 export * from './GlobalNotification';
 export * from './ToastNotification';
+export * from './types';

package/dist/types/RichTextEditor/RichTextEditor/RichTextEditor.d.ts

@@ -4,6 +4,7 @@ import type { EditorContentArray, EditorRows, ToolbarItems } from '../types';
 import { ProseMirrorState } from '../utils/prosemirror';
 type BaseRichTextEditorProps = {
     id?: string;
+    inputRef?: React.Ref<HTMLElement>;
     onChange: (content: ProseMirrorState.EditorState) => void;
     defaultValue: EditorContentArray;
     controls?: ToolbarItems[];
@@ -38,7 +39,7 @@ export type RichTextEditorProps = BaseRichTextEditorProps & (WithLabelText | Wit
  * {@link https://cultureamp.design/?path=/docs/components-richtexteditor--docs Storybook}
  */
 export declare const RichTextEditor: {
-    ({ id, onChange, defaultValue, labelText, "aria-labelledby": labelledBy, "aria-describedby": describedBy, classNameOverride, controls, rows, dataError, onDataError, validationMessage, description, status, ...restProps }: RichTextEditorProps): JSX.Element;
+    ({ id, inputRef, onChange, defaultValue, labelText, "aria-labelledby": labelledBy, "aria-describedby": describedBy, classNameOverride, controls, rows, dataError, onDataError, validationMessage, description, status, ...restProps }: RichTextEditorProps): JSX.Element;
     displayName: string;
 };
 export {};

package/dist/types/RichTextEditor/utils/core/createRichTextEditor.d.ts

@@ -3,6 +3,7 @@ import { type CommandOrTransaction } from './types';
 type EditorAPI = {
     destroy: () => void;
     dispatchTransaction: (maybeCommand: CommandOrTransaction) => void;
+    dom: HTMLElement;
 };
 type EditorArgs = {
     initialEditorState: EditorState;

package/dist/types/RichTextEditor/utils/core/hooks/useRichTextEditor.d.ts

@@ -1,7 +1,8 @@
 import { type EditorState } from 'prosemirror-state';
 import { type CommandOrTransaction } from '../types';
 type RTEOptions = {
-    editable: boolean;
+    editable?: boolean;
+    inputRef?: React.Ref<HTMLElement>;
 };
 type SetEditableStatus = (status: boolean) => void;
 type UseRichTextEditorReturnValue = [
@@ -18,5 +19,5 @@ type UseRichTextEditorReturnValue = [
  * @param {initialEditorState} ProseMirror state
  * @returns {Array}
  */
-export declare const useRichTextEditor: (initialEditorState: EditorState, attributes?: Record<string, string>, options?: RTEOptions) => UseRichTextEditorReturnValue;
+export declare const useRichTextEditor: (initialEditorState: EditorState, attributes?: Record<string, string>, { editable, inputRef }?: RTEOptions) => UseRichTextEditorReturnValue;
 export {};

package/dist/types/SingleSelect/SingleSelect.d.ts

@@ -1,5 +1,4 @@
 import React from 'react';
-import { type UseFloatingReturn } from '@floating-ui/react-dom';
 import { type SelectProps as AriaSelectProps } from '@react-stately/select';
 import { type Key } from '@react-types/shared';
 import { type OverrideClassName } from "../types/OverrideClassName";
@@ -12,13 +11,14 @@ export type SingleSelectProps<Option extends SingleSelectOption = SingleSelectOp
      */
     items: SingleSelectItem<Option>[];
     id?: string;
+    inputRef?: React.Ref<HTMLButtonElement>;
     /**
      * Optional render function that allows custom rendering of the trigger button.
      * The function receives the `selectToggleProps` and a `ref` to be applied
      * to the button element.
      */
     trigger?: (selectToggleProps: SelectToggleProps & {
-        ref: UseFloatingReturn<HTMLButtonElement>['refs']['setReference'];
+        ref: React.Ref<HTMLButtonElement>;
     }) => JSX.Element;
     /**
      * Optional render function that allows custom rendering of the items in the dropdown.
@@ -56,7 +56,7 @@ export type SingleSelectProps<Option extends SingleSelectOption = SingleSelectOp
  * {@link https://cultureamp.design/?path=/docs/components-select--docs Storybook}
  */
 export declare const SingleSelect: {
-    <Option extends SingleSelectOption = SingleSelectOption>({ label, items, id: propsId, trigger, children, status, validationMessage, isReversed, isRequired, isFullWidth, classNameOverride, selectedKey, description, isDisabled, onSelectionChange, portalContainerId, ...restProps }: SingleSelectProps<Option>): JSX.Element;
+    <Option extends SingleSelectOption = SingleSelectOption>({ label, items, id: propsId, trigger, children, status, validationMessage, isReversed, isRequired, isFullWidth, classNameOverride, selectedKey, description, isDisabled, onSelectionChange, portalContainerId, inputRef, ...restProps }: SingleSelectProps<Option>): JSX.Element;
     displayName: string;
     Section: {
         <Option extends SingleSelectOption = SingleSelectOption>({ section, }: import("./subcomponents").ListBoxSectionProps<Option>): JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaizen/components",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Kaizen component library",
   "author": "Geoffrey Chong <geoff.chong@cultureamp.com>",
   "homepage": "https://cultureamp.design",

package/src/Avatar/Avatar.tsx

@@ -91,21 +91,29 @@ const renderInitials = (
   const isLongName = initials.length > 2 && size !== 'small'
   const renderFallback = disableInitials || initials === ''
 
-  return renderFallback ? (
-    <FallbackIcon alt={alt} />
-  ) : (
-    <abbr className={classnames(styles.initials, isLongName && styles.longName)} title={alt}>
-      {isLongName ? (
-        // Only called if 3 or more initials, fits text width for long names
-        //
+  if (renderFallback) {
+    return <FallbackIcon alt={alt} />
+  }
+
+  if (isLongName) {
+    return (
+      <abbr
+        className={classnames(styles.initials, styles.longName)}
+        title={alt}
         // Ignore Chromatic diffs since the font-size calculation has shown itself to be slightly non-deterministic,
         // causing flaky tests.
-        <Textfit mode="single" max={getMaxFontSizePixels(size)} data-chromatic="ignore">
+        data-chromatic="ignore"
+      >
+        <Textfit mode="single" max={getMaxFontSizePixels(size)}>
           {initials}
         </Textfit>
-      ) : (
-        getInitials(fullName, size === 'small')
-      )}
+      </abbr>
+    )
+  }
+
+  return (
+    <abbr className={styles.initials} title={alt}>
+      {getInitials(fullName, size === 'small')}
     </abbr>
   )
 }

package/src/Focusable/Focusable.tsx

@@ -1,26 +1,36 @@
-import React, { useRef, type HTMLAttributes, type ReactNode } from 'react'
+import React, { useRef, type ElementType, type HTMLAttributes, type ReactNode } from 'react'
 import classnames from 'classnames'
 import { useFocusable, type FocusableOptions } from 'react-aria'
 import styles from './Focusable.module.css'
 
-export type FocusableProps = {
+export type FocusableProps<T extends ElementType = 'div'> = {
   children: ReactNode
+  /**
+   * The HTML element to render as. Defaults to `div` to avoid an api change
+   * but should be set to 'span' if rendering within something like a 'p' tag to avoid invalid HTML.
+   */
+  tag?: T
 } & FocusableOptions &
   HTMLAttributes<HTMLDivElement>
 
-export const Focusable = ({ children, className, ...props }: FocusableProps): JSX.Element => {
+export const Focusable = <T extends ElementType = 'div'>({
+  children,
+  className,
+  tag,
+  ...props
+}: FocusableProps<T>): JSX.Element => {
   const ref = useRef<HTMLDivElement>(null)
   const { focusableProps } = useFocusable(props, ref)
+  const Element = tag ?? 'div'
 
   return (
-    <div
+    <Element
       ref={ref}
       className={classnames(styles.focusableWrapper, className)}
       {...focusableProps}
       data-inline-hidden-content
-      // We want the div to be focusable for keyboard users,
+      // We want the element to be focusable for keyboard users,
       // but screen readers will have the VisuallyHidden content
-      // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
       tabIndex={0}
       // aria-describedby on div doesn't do anthing so we instead render the content in VisuallyHidden from tooltip
       // but because RAC adds it as it assumes it's interactive element we remove it here
@@ -28,6 +38,6 @@ export const Focusable = ({ children, className, ...props }: FocusableProps): JS
       {...props}
     >
       {children}
-    </div>
+    </Element>
   )
 }

package/src/MultiSelect/MultiSelect.tsx

@@ -1,4 +1,5 @@
 import React, { useId, useRef, type HTMLAttributes } from 'react'
+import { mergeRefs } from '@react-aria/utils'
 import classnames from 'classnames'
 import { type ReactFocusOnProps } from 'react-focus-on/dist/es5/types'
 import { FieldMessage, type FieldMessageProps } from '~components/FieldMessage'
@@ -14,6 +15,7 @@ import { type MultiSelectOption, type ValidationMessage } from './types'
 import styles from './MultiSelect.module.scss'
 
 export type MultiSelectProps = {
+  inputRef?: React.Ref<HTMLButtonElement>
   label: string
   items: MultiSelectOptionsProps['options']
   selectedValues: Set<MultiSelectOption['value']>
@@ -39,6 +41,7 @@ export const MultiSelect = ({
   onOpenChange,
   classNameOverride,
   validationMessage,
+  inputRef,
   ...restProps
 }: MultiSelectProps): JSX.Element => {
   const fallbackId = useId()
@@ -88,7 +91,7 @@ export const MultiSelect = ({
 
       <div ref={refs.setReference} className={styles.toggleContainer}>
         <MultiSelectToggle
-          ref={toggleButtonRef}
+          ref={mergeRefs(toggleButtonRef, inputRef)}
           id={`${id}--toggle`}
           aria-labelledby={`${id}--label`}
           aria-describedby={`${validationId} ${descriptionId}`}

package/src/Notification/index.ts

@@ -1,3 +1,4 @@
 export * from './InlineNotification'
 export * from './GlobalNotification'
 export * from './ToastNotification'
+export * from './types'

package/src/RichTextEditor/RichTextEditor/RichTextEditor.tsx

@@ -22,6 +22,7 @@ import styles from './RichTextEditor.module.scss'
 
 type BaseRichTextEditorProps = {
   id?: string
+  inputRef?: React.Ref<HTMLElement>
   onChange: (content: ProseMirrorState.EditorState) => void
   defaultValue: EditorContentArray
   controls?: ToolbarItems[]
@@ -60,6 +61,7 @@ export type RichTextEditorProps = BaseRichTextEditorProps & (WithLabelText | Wit
  */
 export const RichTextEditor = ({
   id,
+  inputRef,
   onChange,
   defaultValue,
   labelText,
@@ -105,6 +107,7 @@ export const RichTextEditor = ({
           'role': 'textbox',
           'aria-describedby': ariaDescribedBy,
         },
+        { inputRef },
       )
     } catch {
       return new Error('Bad data error')

package/src/RichTextEditor/utils/core/createRichTextEditor.spec.ts

@@ -32,7 +32,7 @@ describe('createRichTextEditor()', () => {
       initialEditorState: testEditorState,
     })
 
-    expect(Object.keys(returnValue)).toEqual(['destroy', 'dispatchTransaction'])
+    expect(Object.keys(returnValue)).toEqual(['destroy', 'dispatchTransaction', 'dom'])
     expect(typeof returnValue.destroy).toEqual('function')
     expect(typeof returnValue.dispatchTransaction).toEqual('function')
   })

package/src/RichTextEditor/utils/core/createRichTextEditor.ts

@@ -5,6 +5,7 @@ import { type CommandOrTransaction } from './types'
 type EditorAPI = {
   destroy: () => void
   dispatchTransaction: (maybeCommand: CommandOrTransaction) => void
+  dom: HTMLElement
 }
 
 type EditorArgs = {
@@ -60,5 +61,6 @@ export const createRichTextEditor = ({
   return {
     destroy: () => editorView.destroy(),
     dispatchTransaction: dispatchCommandOrTransaction,
+    dom: editorView.dom,
   }
 }

package/src/RichTextEditor/utils/core/hooks/useRichTextEditor.spec.tsx

@@ -10,9 +10,11 @@ const user = userEvent.setup()
 const Scenario = ({
   onChange = () => undefined,
   editable = true,
+  inputRef,
 }: {
   onChange?: (editorState: EditorState) => void
   editable?: boolean
+  inputRef?: React.Ref<HTMLElement>
 }): JSX.Element => {
   const command: Command = (state, dispatch) => {
     // Insert text at the current selection point, which is the start because
@@ -25,7 +27,7 @@ const Scenario = ({
   const [ref, editorState, dispatchTransaction, setEditableStatus] = useRichTextEditor(
     testEditorState,
     { 'aria-labelledby': 'label-ref-id', 'data-testid': '12345678' },
-    { editable },
+    { editable, inputRef },
   )
 
   useEffect(() => {
@@ -151,14 +153,17 @@ describe('useRichTextEditor()', () => {
     })
   })
 
-  it('is removed from DOM when unmounted', async () => {
-    const { unmount } = render(<Scenario />)
+  it('assigns ref on mount and cleans up DOM/ref on unmount', async () => {
+    const inputRef = React.createRef<HTMLElement>()
+    const { unmount } = render(<Scenario inputRef={inputRef} />)
 
     const editor = screen.getByTestId('testid--editor')
     expect(editor).toBeInTheDocument()
+    expect(inputRef.current).toHaveAttribute('contenteditable', 'true')
 
     unmount()
 
     expect(screen.queryByTestId('testid--editor')).not.toBeInTheDocument()
+    expect(inputRef.current).toBeNull()
   })
 })

package/src/RichTextEditor/utils/core/hooks/useRichTextEditor.ts

@@ -1,10 +1,12 @@
 import { useCallback, useRef, useState } from 'react'
 import { type EditorState } from 'prosemirror-state'
+import { isRefObject } from '~components/utils/isRefObject'
 import { createRichTextEditor } from '../createRichTextEditor'
 import { type CommandOrTransaction } from '../types'
 
 type RTEOptions = {
-  editable: boolean
+  editable?: boolean
+  inputRef?: React.Ref<HTMLElement>
 }
 
 type SetEditableStatus = (status: boolean) => void
@@ -30,12 +32,8 @@ export const useRichTextEditor = (
    * Pass in HTML attributes into the parent RTE node
    */
   attributes?: Record<string, string>,
-  options?: RTEOptions,
+  { editable = true, inputRef }: RTEOptions = {},
 ): UseRichTextEditorReturnValue => {
-  options = {
-    editable: true,
-    ...options,
-  }
   const [editorState, setEditorState] = useState<EditorState>(initialEditorState)
   // Refs to hold the methods returned from ProseMirror’s initialization
   const destroyEditorRef = useRef<() => void>()
@@ -53,7 +51,11 @@ export const useRichTextEditor = (
   )
 
   // Hold editableStatus as a ref so we can toggle its status
-  const editableStatusRef = useRef<boolean>(options.editable)
+  const editableStatusRef = useRef<boolean>(editable)
+
+  // Stable ref to avoid recreating editorRef when inputRef callback identity changes
+  const inputRefRef = useRef(inputRef)
+  inputRefRef.current = inputRef
   const setEditableStatus = useCallback<SetEditableStatus>(
     (status) => {
       editableStatusRef.current = status
@@ -76,6 +78,11 @@ export const useRichTextEditor = (
           destroyEditorRef.current()
           destroyEditorRef.current = undefined
         }
+        if (inputRefRef.current && isRefObject(inputRefRef.current)) {
+          ;(inputRefRef.current as React.MutableRefObject<HTMLElement | null>).current = null
+        } else {
+          inputRefRef.current?.(null)
+        }
         return
       }
 
@@ -88,6 +95,12 @@ export const useRichTextEditor = (
       })
       destroyEditorRef.current = instance.destroy
       dispatchTransactionRef.current = instance.dispatchTransaction
+
+      if (inputRefRef.current && isRefObject(inputRefRef.current)) {
+        ;(inputRefRef.current as React.MutableRefObject<HTMLElement | null>).current = instance.dom
+      } else {
+        inputRefRef.current?.(instance.dom)
+      }
     },
 
     // Including editorState in the dependencies here will cause an endless

package/src/SingleSelect/SingleSelect.tsx

@@ -1,7 +1,7 @@
 import React, { useEffect, useId, useState } from 'react'
-import { type UseFloatingReturn } from '@floating-ui/react-dom'
 import { useButton } from '@react-aria/button'
 import { HiddenSelect, useSelect } from '@react-aria/select'
+import { mergeRefs } from '@react-aria/utils'
 import { useSelectState, type SelectProps as AriaSelectProps } from '@react-stately/select'
 import { type Key } from '@react-types/shared'
 import classnames from 'classnames'
@@ -32,6 +32,7 @@ export type SingleSelectProps<Option extends SingleSelectOption = SingleSelectOp
    */
   items: SingleSelectItem<Option>[]
   id?: string
+  inputRef?: React.Ref<HTMLButtonElement>
   /**
    * Optional render function that allows custom rendering of the trigger button.
    * The function receives the `selectToggleProps` and a `ref` to be applied
@@ -39,7 +40,7 @@ export type SingleSelectProps<Option extends SingleSelectOption = SingleSelectOp
    */
   trigger?: (
     selectToggleProps: SelectToggleProps & {
-      ref: UseFloatingReturn<HTMLButtonElement>['refs']['setReference']
+      ref: React.Ref<HTMLButtonElement>
     },
   ) => JSX.Element
   /**
@@ -95,6 +96,7 @@ export const SingleSelect = <Option extends SingleSelectOption = SingleSelectOpt
   isDisabled,
   onSelectionChange,
   portalContainerId,
+  inputRef,
   ...restProps
 }: SingleSelectProps<Option>): JSX.Element => {
   const { refs } = useFloating<HTMLButtonElement>()
@@ -153,7 +155,7 @@ export const SingleSelect = <Option extends SingleSelectOption = SingleSelectOpt
     status,
     'isDisabled': triggerProps.isDisabled,
     isReversed,
-    'ref': refs.setReference,
+    'ref': mergeRefs(inputRef, refs.setReference),
     'aria-describedby': classnames(validationMessage && validationId, description && descriptionId),
     'aria-required': isRequired,
   }