@bccampus/ui-components 0.4.1 → 0.4.2

package/src/components/ui/composite/composite-component.tsx

@@ -1,98 +1,69 @@
-import { useCallback, useImperativeHandle, useRef } from "react";
-import { CompositeDataItem } from "./CompositeDataItem";
-import type { CompositeItemKey, CompositeProps } from "./types";
-import { useKeyboardEvent } from "@/hooks/use-keyboard-event";
-import { useCompositeContext } from "./composite-data-context";
+import { useImperativeHandle, useMemo } from "react";
+import type { CompositeProps } from "./types";
 import { CompositeComponentItem } from "./composite-component-item";
 import { useId } from "@/hooks/use-id";
 
+const defaultRoles = {
+  listbox: {
+    rootRole: "listbox",
+    groupRole: "group",
+    itemRole: "option",
+  },
+  grid: {
+    rootRole: "grid",
+    groupRole: "rowgroup",
+    itemRole: "row",
+  },
+  custom: undefined,
+};
+
 export function CompositeComponent<T extends object>({
+  data,
+  variant,
+  rootRole,
+  itemRole,
+  groupRole,
   renderItem,
   className,
   itemClassName,
   ref,
+  handleRef,
   id,
+  itemMouseEventHandler,
+  itemKeyboardEventHandler,
   ...props
 }: CompositeProps<T>) {
-  const compositeData = useCompositeContext<T>();
-  const compositeRef = useRef<HTMLDivElement>(null);
   const compositeId = useId(id);
 
-  const focus = useCallback(
-    (itemKey: CompositeItemKey) => {
-      compositeData.focus(itemKey);
-      // const focusedItemEl = compositeRef.current?.querySelector<HTMLDivElement>(`[data-key="${itemKey}"]`);
-      // if (focusedItemEl) focusedItemEl.focus();
-    },
-    [compositeData]
-  );
-
-  const focusDown = useCallback(() => {
-    if (compositeData.focusedItem.get()?.pointers.down) {
-      focus(compositeData.focusedItem.get()!.pointers.down!);
-    }
-  }, [compositeData, focus]);
-
-  const focusUp = useCallback(() => {
-    if (compositeData.focusedItem.get()?.pointers.up) {
-      focus(compositeData.focusedItem.get()!.pointers.up!);
-    }
-  }, [compositeData, focus]);
-
-  const handleKeyDown = useKeyboardEvent({
-    ArrowUp: focusUp,
-    ArrowLeft: focusUp,
-    ArrowDown: focusDown,
-    ArrowRight: focusDown,
-    Space: () => {
-      if (compositeData.focusedItem.get()) compositeData.toggleSelect(compositeData.focusedItem.get()!);
-    },
-  });
-
-  const handleItemMouseEvent = useCallback(
-    (item: CompositeDataItem<T>) => {
-      focus(item.key);
-      compositeData.toggleSelect(item);
-    },
-    [compositeData, focus]
-  );
-
   useImperativeHandle(
-    ref,
+    handleRef,
     () => {
       return {
-        focusDown() {
-          focusDown();
-        },
-        focusUp() {
-          focusUp();
-        },
-        select() {
-          if (compositeData.focusedItem.get()) compositeData.toggleSelect(compositeData.focusedItem.get()!);
-        },
+        focusProvider: data.focusProvider,
+        selectionProvider: data.selectionProvider,
       };
     },
-    [compositeData, focusDown, focusUp]
+    [data]
+  );
+
+  const roles = useMemo(
+    () => defaultRoles[variant] ?? { rootRole, groupRole, itemRole },
+    [groupRole, itemRole, rootRole, variant]
   );
 
   return (
-    <div
-      ref={compositeRef}
-      id={compositeId}
-      className={className}
-      tabIndex={-1}
-      role="listbox"
-      onKeyDown={handleKeyDown}
-      {...props}
-    >
-      {[...compositeData].map((item) => (
+    <div ref={ref} id={compositeId} className={className} tabIndex={-1} role={roles.rootRole} {...props}>
+      {[...data].map((item) => (
         <CompositeComponentItem
           className={itemClassName}
           id={`${compositeId}-${item.key}`}
+          role={roles.itemRole}
+          groupRole={roles.groupRole}
           item={item}
           key={item.key}
           render={renderItem}
-          mouseEventHandler={handleItemMouseEvent}
+          itemMouseEventHandler={itemMouseEventHandler}
+          itemKeyboardEventHandler={itemKeyboardEventHandler}
         />
       ))}
     </div>

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

@@ -1,4 +1,7 @@
 export * from './composite-component.tsx'
 export * from './composite-component-item.tsx'
-export * from './composite-data-context.tsx'
+export * from './CompositeData.ts'
+export * from './CompositeDataItem.ts'
+export * from './FocusProvider/AbstractFocusProvider.ts'
+export * from './SelectionProvider/AbstractSelectionProvider.ts'
 export * from './types.ts'

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

@@ -0,0 +1,61 @@
+import { CompositeComponent } from "./composite-component";
+import { useCallback, useRef } from "react";
+import { CompositeDataItem } from "./CompositeDataItem";
+import type { BaseCompositeProps } from "./types";
+import { useKeyboardEvent } from "@/hooks/use-keyboard-event";
+
+export function Listbox<T extends object>({ data, ...props }: BaseCompositeProps<T>) {
+  const compositeRef = useRef<HTMLDivElement>(null);
+
+  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();
+    },
+    End: () => {
+      data.focusProvider.focusToLast();
+      focusElement();
+    },
+    Space: () => {
+      data.selectionProvider?.toggleSelect();
+      focusElement();
+    },
+  });
+
+  const handleItemMouseEvent = useCallback(
+    (item: CompositeDataItem<T>) => {
+      data.focusProvider.focus(item.key);
+      data.selectionProvider?.toggleSelect(item);
+      focusElement();
+    },
+    [data.focusProvider, data.selectionProvider, focusElement]
+  );
+
+  return (
+    <CompositeComponent
+      ref={compositeRef}
+      variant="listbox"
+      data={data}
+      onKeyDown={handleKeyboardEvent}
+      itemMouseEventHandler={handleItemMouseEvent}
+      {...props}
+    />
+  );
+}

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

@@ -1,8 +1,29 @@
-import type { KeyboardEventHandler, MouseEventHandler, ReactNode } from "react";
+import type { AriaRole, KeyboardEventHandler, MouseEventHandler, ReactNode } from "react";
 import type { CompositeDataItem } from "./CompositeDataItem";
+import type { AbstractFocusProvider, FocusProvider } from "./FocusProvider/AbstractFocusProvider";
+import type { AbstractSelectionProvider, SelectionProvider } from "./SelectionProvider/AbstractSelectionProvider";
+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 interface CompositeOptions {
     disabledKeys?: CompositeItemKey[];
     selectedKeys?: CompositeItemKey[];
@@ -16,6 +37,11 @@ interface CompositeDataPropGetters<T> {
     getItemChildren: (item: T) => T[] | undefined;
 }
 
+export interface CompositeProviderOptions<T extends object> {
+    focusProvider: AbstractFocusProvider<T>;
+    selectionProvider?: AbstractSelectionProvider<T>;
+}
+
 export type CompositeDataOptions<T> = Required<CompositeOptions> & CompositeDataPropGetters<T>;
 
 export type CompositeDataItemOptions<T> = CompositeDataPropGetters<T> & {
@@ -29,53 +55,48 @@ export interface CompositeDataItemState {
     disabled: boolean;
 }
 
-export interface CompositeProps<T extends object> extends React.ComponentPropsWithoutRef<"div"> {
-    renderItem: CompositeItemRenderFn<T>;
+export interface CompositeEventHandlers {
+    mouseEventHandler?: MouseEventHandler<HTMLElement>;
+    keyboardEventHandler?: KeyboardEventHandler<HTMLElement>;
+}
+
+export interface CompositeItemEventHandlerFunctions<T extends object> {
+    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;
-    ref?: React.Ref<CompositeHandle>
+
 }
 
+export type CompositeProps<T extends object> = BaseCompositeProps<T> & CompositeItemEventHandlerFunctions<T> & CompositeRoles;
 
 export interface CompositeHandle {
-    focusUp: () => void;
-    focusDown: () => void;
-    select: () => void;
-}
-
-export interface CompositeItemEventHandlers {
-    mouseEventHandler?: MouseEventHandler<HTMLElement>;
-    keyboardEventHandler?: KeyboardEventHandler<HTMLElement>;
+    focusProvider: FocusProvider;
+    selectionProvider?: SelectionProvider;
 }
 
 export type CompositeItemRenderFn<T extends object> = (
     item: { data: T; level: number; key: CompositeItemKey },
     state: CompositeDataItemState,
-    eventHandlers: CompositeItemEventHandlers
+    eventHandlers: CompositeEventHandlers
 ) => ReactNode;
 
-export interface CompositeItemProps<T extends object> {
+export interface CompositeItemProps<T extends object> extends CompositeItemEventHandlerFunctions<T> {
     id: string;
     className?: string;
+    role?: AriaRole;
+    groupRole?: AriaRole;
 
     item: CompositeDataItem<T>;
 
-    mouseEventHandler?: (itemAtom: CompositeDataItem<T>) => void;
-    keyboardEventHandler?: (itemAtom: CompositeDataItem<T>) => void;
-
     remove?: () => void;
     render: CompositeItemRenderFn<T>;
 }
-
-export interface CompositeFocusProvider {
-    setPointers: () => void;
-
-    goFirst: () => void;
-    goLast: () => void;
-    
-    goUp: () => void;
-    goDown: () => void;
-    goLeft: () => void;
-    goRight: () => void;
-
-}

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

@@ -1,52 +1,38 @@
 import type { KeyboardEvent, KeyboardEventHandler } from 'react';
 import { useMemo } from 'react';
 
-const MODIFIER_KEYS = new Set(['ctrl', 'shift', 'alt', 'meta']);
-
-const KEY_MAPPINGS: Record<string, string> = {
-  ' ': 'space',
-};
-
-export interface KeyBindings {
+interface KeyBindings {
   [sequence: string]: (event: KeyboardEvent) => void;
 }
-
 interface KeybindingLookupItem {
-  sequence: Set<string>;
+  sequence: RegExp;
   handler: (event: KeyboardEvent) => void;
 }
+const MODIFIER_KEYS = new Set(["ctrl", "shift", "alt", "meta"]);
+
+const KEY_MAPPINGS: Record<string, string> = {
+  " ": "space",
+};
 
 interface UseKeyboardEventOptions {
   eventKeyProp: 'key' | 'code';
 }
 
-function isSequenceEqual<T>(sequenceA: Set<T>, sequenceB: Set<T>) {
-  if (sequenceA.size !== sequenceB.size) return false;
-
-  for (const element of sequenceB) {
-    if (!sequenceA.has(element)) return false;
-  }
-
-  return true;
-}
-
 function parseKeybindings(bindings: KeyBindings) {
   const parsedKeybindings: KeybindingLookupItem[] = [];
   for (const [sequence, handler] of Object.entries(bindings)) {
     const parsedSequence = sequence
       .toLowerCase()
       .trim()
-      .split(/\s*\+\s*/);
+      .split(/\s*\+\s*/g);
 
     if (parsedSequence.length === 1 && MODIFIER_KEYS.has(parsedSequence[0])) {
-      console.error(`[useKeyboardEvent] \`${sequence}\`: A key sequence cannot be only a modifier key.`);
-    }
-    else if (parsedSequence.includes('')) {
-      console.error(`[useKeyboardEvent] \`${sequence}\`: Unknown key defined in the sequence.`);
-    }
-    else {
+      console.error(`[useKeyboardEvent] '${sequence}': A key sequence cannot be only a modifier key.`);
+    } else if (parsedSequence.includes("")) {
+      console.error(`[useKeyboardEvent] '${sequence}': Invalid key sequence defined in the sequence.`);
+    } else {
       parsedKeybindings.push({
-        sequence: new Set(parsedSequence),
+        sequence: new RegExp("^" + parsedSequence.join("\\+") + "$"),
         handler,
       });
     }
@@ -68,21 +54,22 @@ export function keyboardEventHandler(
   const keyBindings = parseKeybindings(bindings);
 
   return (event: KeyboardEvent) => {
-    const keySequence = new Set<string>();
     const eventKey = event[_options.eventKeyProp];
+    const keySequence: string[] = [];
 
-    if (event.ctrlKey) keySequence.add('ctrl');
+    if (event.ctrlKey) keySequence.push("ctrl");
 
-    if (event.shiftKey) keySequence.add('shift');
+    if (event.shiftKey) keySequence.push("shift");
 
-    if (event.altKey) keySequence.add('alt');
+    if (event.altKey) keySequence.push("alt");
 
-    if (event.metaKey) keySequence.add('meta');
+    if (event.metaKey) keySequence.push("meta");
 
-    if (!KEY_MAPPINGS[eventKey]) keySequence.add(eventKey.toLowerCase());
-    else keySequence.add(KEY_MAPPINGS[eventKey]);
+    if (!KEY_MAPPINGS[eventKey]) keySequence.push(eventKey.toLowerCase());
+    else keySequence.push(KEY_MAPPINGS[eventKey]);
 
-    const matchedSequence = keyBindings.find(keyBinding => isSequenceEqual(keySequence, keyBinding.sequence));
+    const matchedSequence = keyBindings.find((keyBinding) => keyBinding.sequence.test(keySequence.join("+")));
+    
     if (matchedSequence) {
       event.preventDefault();
       event.stopPropagation();
@@ -91,16 +78,18 @@ export function keyboardEventHandler(
   };
 }
 
+
 /**
  * Returns a `KeyboardEventHandler`
- * that checks the defined key binding sequences against a keyboard event
+ * that checks the defined key sequences against a keyboard event
  * and executes the handler of the first matched key binding.
- *
- * Limitations:
- *   - Space character (` `) cannot be used in the key sequences.
- *    Use the `space` keyword instead.
- *   - Plus character (`+`) cannot be used in the key sequences.
- *    Use `shit + =` instead.
+ * 
+ * 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 
+ *  - 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.
  *
  * @example
  * ```

package/vite.config.ts

@@ -21,6 +21,10 @@ export default defineConfig({
       entry: {
         'ui-components': path.resolve(__dirname, 'src/components/ui/index.ts'),
         'composite': path.resolve(__dirname, 'src/components/ui/composite/index.ts'),
+        'listbox': path.resolve(__dirname, 'src/components/ui/composite/listbox.tsx'),
+        'SingleSelectionProvider': path.resolve(__dirname, 'src/components/ui/composite/SelectionProvider/SingleSelectionProvider.ts'),
+        'MultipleSelectionProvider': path.resolve(__dirname, 'src/components/ui/composite/SelectionProvider/MultipleSelectionProvider.ts'),
+        'ListboxFocusProvider': path.resolve(__dirname, 'src/components/ui/composite/FocusProvider/ListboxFocusProvider.ts'),
         'icon-generator': path.resolve(__dirname, 'src/components/ui/icon-generator/index.ts'),
         'generate-tiles': path.resolve(__dirname, 'src/components/ui/icon-generator/generate-tiles.tsx'),
         'masked-image-generator': path.resolve(__dirname, 'src/components/ui/icon-generator/masked-image-generator.tsx'),

package/src/components/ui/composite/composite-data-context.tsx

@@ -1,31 +0,0 @@
-import { createContext, useContext, useMemo } from "react";
-import { CompositeData } from "./CompositeData";
-import type { CompositeOptions } from "./types";
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const CompositeDataContext = createContext<CompositeData<any> | undefined>(undefined);
-
-export function useCompositeContext<T extends object>() {
-  const context = useContext(CompositeDataContext);
-
-  if (!context) {
-    throw new Error("No CompositeDataContext has been set, use CompositeDataContext to provide a context");
-  }
-
-  return context as CompositeData<T>;
-}
-
-interface CompositeComponentContextProps<T extends object> extends CompositeOptions {
-  data: T[];
-  children: React.ReactNode;
-}
-
-export function CompositeComponentContext<T extends object>({
-  data,
-  children,
-  ...compositeOptions
-}: CompositeComponentContextProps<T>) {
-  const composite = useMemo(() => new CompositeData(data, compositeOptions), [data, compositeOptions]);
-
-  return <CompositeDataContext value={composite}>{children}</CompositeDataContext>;
-}