@bccampus/ui-components 0.7.0 → 0.7.2

package/src/components/ui/composite/listbox.tsx

@@ -1,58 +1,61 @@
 import { CompositeComponent } from "./composite-component";
-import { useCallback, useRef } from "react";
+import { useCallback } from "react";
 import { CompositeDataItem } from "./CompositeDataItem";
 import type { BaseCompositeProps } from "./types";
 import { useKeyboardEvent } from "@/hooks/use-keyboard-event";
+import { useRequiredRef } from "@/hooks/use-required-ref";
 
-export function Listbox<T extends object>({ data, ...props }: BaseCompositeProps<T>) {
-  const compositeRef = useRef<HTMLDivElement>(null);
+export function Listbox<T extends object>({
+  data,
+  rootRef,
+  handleRef,
+  initialFocus = "SelectedItem",
+  ...props
+}: BaseCompositeProps<T>) {
+  const $handleRef = useRequiredRef(handleRef);
 
-  const focusElement = useCallback(() => {
-    const itemKey = data.focusProvider.focusedItem.get()?.key;
-
-    if (itemKey && compositeRef.current) {
-      const focusedItemEl = compositeRef.current.querySelector<HTMLDivElement>(`[data-key="${itemKey}"]`);
-      if (focusedItemEl) focusedItemEl.focus();
-    }
-  }, [data]);
-
-  const handleKeyboardEvent = useKeyboardEvent({
-    ArrowUp: () => {
-      data.focusProvider.focusUp();
-      focusElement();
-    },
-    ArrowDown: () => {
-      data.focusProvider.focusDown();
-      focusElement();
-    },
-    Home: () => {
-      data.focusProvider.focusToFirst();
-      focusElement();
+  const handleKeyboardEvent = useKeyboardEvent(
+    {
+      ArrowUp: () => {
+        data.focusProvider.focusUp();
+        $handleRef.current?.focusElement();
+      },
+      ArrowDown: () => {
+        data.focusProvider.focusDown();
+        $handleRef.current?.focusElement();
+      },
+      Home: () => {
+        data.focusProvider.focusToFirst();
+        $handleRef.current?.focusElement();
+      },
+      End: () => {
+        data.focusProvider.focusToLast();
+        $handleRef.current?.focusElement();
+      },
+      Space: () => {
+        data.selectionProvider?.toggleSelect();
+        $handleRef.current?.focusElement();
+      },
     },
-    End: () => {
-      data.focusProvider.focusToLast();
-      focusElement();
-    },
-    Space: () => {
-      data.selectionProvider?.toggleSelect();
-      focusElement();
-    },
-  });
+    [$handleRef, data.focusProvider],
+  );
 
   const handleItemMouseEvent = useCallback(
     (item: CompositeDataItem<T>) => {
       data.focusProvider.focus(item.key);
       data.selectionProvider?.toggleSelect(item);
-      focusElement();
+      $handleRef.current?.focusElement();
     },
-    [data.focusProvider, data.selectionProvider, focusElement]
+    [$handleRef, data.focusProvider, data.selectionProvider],
   );
 
   return (
     <CompositeComponent
-      ref={compositeRef}
+      rootRef={rootRef}
+      handleRef={$handleRef}
       variant="listbox"
       data={data}
+      initialFocus={initialFocus}
       onKeyDown={handleKeyboardEvent}
       itemMouseEventHandler={handleItemMouseEvent}
       {...props}

package/src/components/ui/composite/types.ts

@@ -6,97 +6,111 @@ import type { CompositeData } from "./CompositeData";
 
 export type CompositeItemKey = string | number;
 
-;
-export type CompositeRoles = {
-    variant: 'listbox'
-    rootRole?: never
-    itemRole?: never
-    groupRole?: never
-} | {
-    variant: 'grid'
-    rootRole?: never
-    itemRole?: never
-    groupRole?: never
-} | {
-    variant: 'custom'
-    rootRole: AriaRole
-    itemRole: AriaRole
-    groupRole: AriaRole
-};
+export type CompositeRoles =
+  | {
+      variant: "listbox";
+      rootRole?: never;
+      itemRole?: never;
+      groupRole?: never;
+    }
+  | {
+      variant: "grid";
+      rootRole?: never;
+      itemRole?: never;
+      groupRole?: never;
+    }
+  | {
+      variant: "custom";
+      rootRole: AriaRole;
+      itemRole: AriaRole;
+      groupRole: AriaRole;
+    };
+
+export type InitialFocusTarget = "None" | "LastFocusedItem" | "SelectedItem" | "FirstItem";
 
 export interface CompositeOptions {
-    disabledKeys?: CompositeItemKey[];
-    selectedKeys?: CompositeItemKey[];
+  disabledKeys?: CompositeItemKey[];
+  selectedKeys?: CompositeItemKey[];
 
-    itemKeyProp?: string;
-    itemChildrenProp?: string;
+  itemKeyProp?: string;
+  itemChildrenProp?: string;
 }
 
 interface CompositeDataPropGetters<T> {
-    getItemKey: (item: T) => CompositeItemKey;
-    getItemChildren: (item: T) => T[] | undefined;
+  getItemKey: (item: T) => CompositeItemKey;
+  getItemChildren: (item: T) => T[] | undefined;
 }
 
 export interface CompositeProviderOptions<T extends object> {
-    focusProvider: AbstractFocusProvider<T>;
-    selectionProvider?: AbstractSelectionProvider<T>;
+  focusProvider: AbstractFocusProvider<T>;
+  selectionProvider?: AbstractSelectionProvider<T>;
 }
 
 export type CompositeDataOptions<T> = Required<CompositeOptions> & CompositeDataPropGetters<T>;
 
 export type CompositeDataItemOptions<T> = CompositeDataPropGetters<T> & {
-    initialState?: CompositeDataItemState;
-    itemChildrenProp: string;
+  initialState?: CompositeDataItemState;
+  itemChildrenProp: string;
 };
 
 export interface CompositeDataItemState {
-    focused: boolean;
-    selected: boolean;
-    disabled: boolean;
+  focused: boolean;
+  selected: boolean;
+  disabled: boolean;
 }
 
 export interface CompositeEventHandlers {
-    mouseEventHandler?: MouseEventHandler<HTMLElement>;
-    keyboardEventHandler?: KeyboardEventHandler<HTMLElement>;
+  mouseEventHandler?: MouseEventHandler<HTMLElement>;
+  keyboardEventHandler?: KeyboardEventHandler<HTMLElement>;
 }
 
 export interface CompositeItemEventHandlerFunctions<T extends object> {
-    itemMouseEventHandler?: (itemAtom: CompositeDataItem<T>) => void;
-    itemKeyboardEventHandler?: (itemAtom: CompositeDataItem<T>) => void;
+  itemMouseEventHandler?: (itemAtom: CompositeDataItem<T>) => void;
+  itemKeyboardEventHandler?: (itemAtom: CompositeDataItem<T>) => void;
 }
 
 export interface BaseCompositeProps<T extends object> extends React.ComponentPropsWithoutRef<"div"> {
-    data: CompositeData<T>;
-    className?: string;
-    ref?: React.Ref<HTMLDivElement>
-    handleRef?: React.Ref<CompositeHandle>
-
-    renderItem: CompositeItemRenderFn<T>;
-    itemClassName?: string;
-
+  data: CompositeData<T>;
+  className?: string;
+  rootRef?: React.RefObject<HTMLDivElement | null>;
+  handleRef?: React.RefObject<CompositeHandle<T> | null>;
+
+  renderItem: CompositeItemRenderFn<T>;
+  itemClassName?: string;
+
+  initialFocus?: InitialFocusTarget;
+  /**
+   * Set `item.focused = true`, but not focus on the HTMLElement
+   */
+  softFocus?: boolean;
 }
 
-export type CompositeProps<T extends object> = BaseCompositeProps<T> & CompositeItemEventHandlerFunctions<T> & CompositeRoles;
+export type CompositeProps<T extends object> = BaseCompositeProps<T> &
+  CompositeItemEventHandlerFunctions<T> &
+  CompositeRoles;
 
-export interface CompositeHandle {
-    focusProvider: FocusProvider;
-    selectionProvider?: SelectionProvider;
+export interface CompositeHandle<T extends object> {
+  focusProvider: FocusProvider<T>;
+  focusElement: () => void;
+  selectionProvider?: SelectionProvider<T>;
 }
 
 export type CompositeItemRenderFn<T extends object> = (
-    item: { data: T; level: number; key: CompositeItemKey },
-    state: CompositeDataItemState,
-    eventHandlers: CompositeEventHandlers
+  item: { data: T; level: number; key: CompositeItemKey },
+  state: CompositeDataItemState,
+  eventHandlers: CompositeEventHandlers,
 ) => ReactNode;
 
 export interface CompositeItemProps<T extends object> extends CompositeItemEventHandlerFunctions<T> {
-    id: string;
-    className?: string;
-    role?: AriaRole;
-    groupRole?: AriaRole;
+  id: string;
+  className?: string;
+  role?: AriaRole;
+  groupRole?: AriaRole;
+
+  item: CompositeDataItem<T>;
 
-    item: CompositeDataItem<T>;
+  remove?: () => void;
+  render: CompositeItemRenderFn<T>;
 
-    remove?: () => void;
-    render: CompositeItemRenderFn<T>;
+  softFocus?: boolean;
 }

package/src/hooks/use-keyboard-event.ts

@@ -1,5 +1,5 @@
-import type { KeyboardEvent, KeyboardEventHandler } from 'react';
-import { useMemo } from 'react';
+import type { KeyboardEvent, KeyboardEventHandler } from "react";
+import { useMemo } from "react";
 
 interface KeyBindings {
   [sequence: string]: (event: KeyboardEvent) => void;
@@ -15,7 +15,7 @@ const KEY_MAPPINGS: Record<string, string> = {
 };
 
 interface UseKeyboardEventOptions {
-  eventKeyProp: 'key' | 'code';
+  eventKeyProp: "key" | "code";
 }
 
 function parseKeybindings(bindings: KeyBindings) {
@@ -42,14 +42,14 @@ function parseKeybindings(bindings: KeyBindings) {
 }
 
 const defaultOptions: UseKeyboardEventOptions = {
-  eventKeyProp: 'key',
+  eventKeyProp: "key",
 };
 
 export function keyboardEventHandler(
   bindings: KeyBindings,
-  options: UseKeyboardEventOptions = defaultOptions
+  options: UseKeyboardEventOptions = defaultOptions,
 ): KeyboardEventHandler {
-  const _options = { ...options, ...defaultOptions }
+  const _options = { ...options, ...defaultOptions };
 
   const keyBindings = parseKeybindings(bindings);
 
@@ -69,7 +69,7 @@ export function keyboardEventHandler(
     else keySequence.push(KEY_MAPPINGS[eventKey]);
 
     const matchedSequence = keyBindings.find((keyBinding) => keyBinding.sequence.test(keySequence.join("+")));
-    
+
     if (matchedSequence) {
       event.preventDefault();
       event.stopPropagation();
@@ -78,16 +78,15 @@ export function keyboardEventHandler(
   };
 }
 
-
 /**
  * Returns a `KeyboardEventHandler`
  * that checks the defined key sequences against a keyboard event
  * and executes the handler of the first matched key binding.
- * 
+ *
  * Key Sequence Rules:
  *  - Multiple key must be seperated by `+`
  *  - Only the following modifier key values as allowed: ctrl, shift, alt, meta
- *  - Modifier key must followed by a key 
+ *  - Modifier key must followed by a key
  *  - Space character (` `) cannot be used in the key sequences. Use the `space` keyword instead.
  *  - Plus character (`+`) cannot be used in the key sequences. Use the `shit + =` sequence instead.
  *
@@ -117,7 +116,7 @@ export function keyboardEventHandler(
  *     'escape': clearInput,
  *     'ctrl+c': clearInput,
  *     'ctrl + shift + c': deleteAll,
- *   });
+ *   },[]);
  *
  *   return (
  *      <input
@@ -128,6 +127,7 @@ export function keyboardEventHandler(
  * }
  * ```
  */
-export function useKeyboardEvent(bindings: KeyBindings, options?: UseKeyboardEventOptions) {
-  return useMemo(() => keyboardEventHandler(bindings, options), [bindings, options]);
+export function useKeyboardEvent(bindings: KeyBindings, deps: React.DependencyList, options?: UseKeyboardEventOptions) {
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  return useMemo(() => keyboardEventHandler(bindings, options), [deps]);
 }

package/src/hooks/use-required-ref.ts

@@ -0,0 +1,6 @@
+import { useRef } from "react";
+
+export function useRequiredRef<T>(ref?: React.RefObject<T | null>) {
+  const emptyRef = useRef<T>(null);
+  return ref ?? emptyRef;
+}