@bccampus/ui-components 0.3.0 → 0.4.1

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

@@ -0,0 +1,144 @@
+import { omit } from "@/lib/object";
+import { map, type PreinitializedMapStore, } from "nanostores";
+import type { CompositeDataItemState, CompositeItemKey, CompositeDataItemOptions } from "./types";
+
+export class CompositeDataItem<T extends object> implements Iterable<CompositeDataItem<T>> {
+    #key: CompositeItemKey;
+    parent: CompositeDataItem<T> | null = null;
+    children?: CompositeDataItem<T>[];
+    level: number;
+
+    data: PreinitializedMapStore<T>;
+    state: PreinitializedMapStore<CompositeDataItemState>;
+
+    pointers: {
+        left?: CompositeItemKey;
+        right?: CompositeItemKey;
+        up?: CompositeItemKey;
+        down?: CompositeItemKey;
+    };
+    childrenProp: string
+
+    constructor(item: T, options: CompositeDataItemOptions<T>, parent: CompositeDataItem<T> | null) {
+        this.#key = options.getItemKey(item);
+        this.data = map(omit(item, [options.itemChildrenProp]));
+        this.state = map({
+            focused: false,
+            selected: false,
+            disabled: false,
+            ...options.initialState
+        })
+        this.pointers = {};
+        this.parent = parent;
+        this.level = parent ? parent.level + 1 : 0;
+
+        this.childrenProp = options.itemChildrenProp;
+
+        const children = options.getItemChildren(item);
+        if (children) {
+            this.children = children.map(child => {
+                const childItem = new CompositeDataItem(child, options, this);
+                return childItem;
+            })
+        }
+    }
+
+    get key() {
+        return this.#key;
+    }
+
+    *[Symbol.iterator](): Iterator<CompositeDataItem<T>> {
+        if (this.key !== "ALL") yield this;
+        if (this.children)
+            for (const child of this.children)
+                for (const item of child) yield item;
+    }
+
+    toJSON() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const json: any = { ...this.data.get() };
+
+        if (this.children) {
+            json[this.childrenProp] = [];
+            for (const child of this.children)
+                json[this.childrenProp].push(child.toJSON());
+        }
+
+        return json as T;
+    }
+
+    descendants() {
+        if (!this.children) return [];
+
+        const descendants: CompositeDataItem<T>[] = [];
+        this.children.forEach((child) => {
+            descendants.push(child);
+            const childDescendants = child.descendants();
+            if (childDescendants) descendants.push(...childDescendants);
+        }
+        )
+
+        return descendants;
+    }
+
+    ancestors() {
+        const ancestors: CompositeDataItem<T>[] = [];
+        let parent = this.parent;
+        while (parent) {
+            ancestors.push(parent);
+            parent = parent.parent;
+        }
+
+        return ancestors;
+    }
+
+
+    toggleSelect(recursive: boolean = false) {
+        if (this.state.get().selected) this.deselect(recursive);
+        else this.select(recursive);
+    }
+
+    select(recursive: boolean = false): CompositeItemKey[] {
+        this.state.setKey("selected", true);
+
+        if (recursive && this.children) {
+            const selectedChildKeys = this.children.map(child => child.select(true)).flat();
+            return [this.key, ...selectedChildKeys];
+        }
+
+        return [this.key]
+    }
+
+    deselect(recursive: boolean = false): CompositeItemKey[] {
+        this.state.setKey("selected", false);
+
+        if (recursive && this.children) {
+            const deselectedChildKeys = this.children.map(child => child.deselect(true)).flat();
+            return [this.key, ...deselectedChildKeys];
+        }
+
+        return [this.key];
+    }
+
+    disable(recursive: boolean = false): CompositeItemKey[] {
+        this.state.setKey("disabled", true);
+
+        if (recursive && this.children) {
+            const disabledChildKeys = this.children.map(child => child.disable(true)).flat();
+            return [this.key, ...disabledChildKeys];
+        }
+
+        return [this.key]
+    }
+
+    enable(recursive: boolean = false): CompositeItemKey[] {
+        this.state.setKey("disabled", false);
+
+        if (recursive && this.children) {
+            const enabledChildKeys = this.children.map(child => child.enable(true)).flat();
+            return [this.key, ...enabledChildKeys];
+        }
+
+        return [this.key];
+    }
+}

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

@@ -0,0 +1,50 @@
+import { useMemo } from "react";
+import type { CompositeItemEventHandlers, CompositeItemProps } from "./types";
+import { useStore } from "@nanostores/react";
+
+export function CompositeComponentItem<T extends object>({
+  id,
+  className,
+  item,
+  mouseEventHandler,
+  keyboardEventHandler,
+  render,
+}: CompositeItemProps<T>) {
+  const data = useStore(item.data);
+  const state = useStore(item.state);
+
+  const handlers: CompositeItemEventHandlers = useMemo(() => {
+    if (state.disabled) return {};
+
+    return {
+      mouseEventHandler: () => mouseEventHandler?.(item),
+      keyboardEventHandler: () => keyboardEventHandler?.(item),
+    };
+  }, [state.disabled, item, keyboardEventHandler, mouseEventHandler]);
+
+  return (
+    <div
+      id={id}
+      role="option"
+      aria-disabled={state.disabled}
+      data-key={item.key}
+      tabIndex={!state.disabled ? (state.focused ? 0 : -1) : undefined}
+      className={className}
+    >
+      {render({ data, key: item.key, level: item.level }, state, handlers)}
+      {item.children &&
+        item.children.length > 0 &&
+        [...item.children].map((child) => (
+          <CompositeComponentItem
+            id={`${id}-${item.key}`}
+            item={child}
+            key={child.key}
+            render={render}
+            className={className}
+            mouseEventHandler={mouseEventHandler}
+            keyboardEventHandler={keyboardEventHandler}
+          />
+        ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,100 @@
+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 { CompositeComponentItem } from "./composite-component-item";
+import { useId } from "@/hooks/use-id";
+
+export function CompositeComponent<T extends object>({
+  renderItem,
+  className,
+  itemClassName,
+  ref,
+  id,
+  ...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,
+    () => {
+      return {
+        focusDown() {
+          focusDown();
+        },
+        focusUp() {
+          focusUp();
+        },
+        select() {
+          if (compositeData.focusedItem.get()) compositeData.toggleSelect(compositeData.focusedItem.get()!);
+        },
+      };
+    },
+    [compositeData, focusDown, focusUp]
+  );
+
+  return (
+    <div
+      ref={compositeRef}
+      id={compositeId}
+      className={className}
+      tabIndex={-1}
+      role="listbox"
+      onKeyDown={handleKeyDown}
+      {...props}
+    >
+      {[...compositeData].map((item) => (
+        <CompositeComponentItem
+          className={itemClassName}
+          id={`${compositeId}-${item.key}`}
+          item={item}
+          key={item.key}
+          render={renderItem}
+          mouseEventHandler={handleItemMouseEvent}
+        />
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,31 @@
+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>;
+}

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

@@ -0,0 +1,4 @@
+export * from './composite-component.tsx'
+export * from './composite-component-item.tsx'
+export * from './composite-data-context.tsx'
+export * from './types.ts'

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

@@ -0,0 +1,81 @@
+import type { KeyboardEventHandler, MouseEventHandler, ReactNode } from "react";
+import type { CompositeDataItem } from "./CompositeDataItem";
+
+export type CompositeItemKey = string | number;
+
+export interface CompositeOptions {
+    disabledKeys?: CompositeItemKey[];
+    selectedKeys?: CompositeItemKey[];
+
+    itemKeyProp?: string;
+    itemChildrenProp?: string;
+}
+
+interface CompositeDataPropGetters<T> {
+    getItemKey: (item: T) => CompositeItemKey;
+    getItemChildren: (item: T) => T[] | undefined;
+}
+
+export type CompositeDataOptions<T> = Required<CompositeOptions> & CompositeDataPropGetters<T>;
+
+export type CompositeDataItemOptions<T> = CompositeDataPropGetters<T> & {
+    initialState?: CompositeDataItemState;
+    itemChildrenProp: string;
+};
+
+export interface CompositeDataItemState {
+    focused: boolean;
+    selected: boolean;
+    disabled: boolean;
+}
+
+export interface CompositeProps<T extends object> extends React.ComponentPropsWithoutRef<"div"> {
+    renderItem: CompositeItemRenderFn<T>;
+    className?: string;
+    itemClassName?: string;
+    ref?: React.Ref<CompositeHandle>
+}
+
+
+export interface CompositeHandle {
+    focusUp: () => void;
+    focusDown: () => void;
+    select: () => void;
+}
+
+export interface CompositeItemEventHandlers {
+    mouseEventHandler?: MouseEventHandler<HTMLElement>;
+    keyboardEventHandler?: KeyboardEventHandler<HTMLElement>;
+}
+
+export type CompositeItemRenderFn<T extends object> = (
+    item: { data: T; level: number; key: CompositeItemKey },
+    state: CompositeDataItemState,
+    eventHandlers: CompositeItemEventHandlers
+) => ReactNode;
+
+export interface CompositeItemProps<T extends object> {
+    id: string;
+    className?: string;
+
+    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/components/ui/icon-generator/index.ts

@@ -0,0 +1,2 @@
+export * from "./icon-generator.tsx"
+export * from "./types"

package/src/components/ui/popover.tsx

@@ -0,0 +1,46 @@
+import * as React from "react"
+import * as PopoverPrimitive from "@radix-ui/react-popover"
+
+import { cn } from "@/lib/utils"
+
+function Popover({
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Root>) {
+  return <PopoverPrimitive.Root data-slot="popover" {...props} />
+}
+
+function PopoverTrigger({
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Trigger>) {
+  return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />
+}
+
+function PopoverContent({
+  className,
+  align = "center",
+  sideOffset = 4,
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Content>) {
+  return (
+    <PopoverPrimitive.Portal>
+      <PopoverPrimitive.Content
+        data-slot="popover-content"
+        align={align}
+        sideOffset={sideOffset}
+        className={cn(
+          "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-72 origin-(--radix-popover-content-transform-origin) rounded-md border p-4 shadow-md outline-hidden",
+          className
+        )}
+        {...props}
+      />
+    </PopoverPrimitive.Portal>
+  )
+}
+
+function PopoverAnchor({
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Anchor>) {
+  return <PopoverPrimitive.Anchor data-slot="popover-anchor" {...props} />
+}
+
+export { Popover, PopoverTrigger, PopoverContent, PopoverAnchor }

package/src/hooks/use-effect-after-mount.ts

@@ -0,0 +1,27 @@
+import type { DependencyList, EffectCallback } from 'react';
+
+import { useEffect, useRef } from 'react';
+
+export function useEffectAfterMount(fn: EffectCallback, dependencies?: DependencyList) {
+  const mounted = useRef(false);
+
+  useEffect(
+    () => () => {
+      mounted.current = false;
+    },
+    []
+  );
+
+  useEffect(
+    () => {
+      if (mounted.current) {
+        return fn();
+      }
+
+      mounted.current = true;
+      return undefined;
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    dependencies
+  );
+}

package/src/hooks/use-id.ts

@@ -0,0 +1,5 @@
+import { useId as reactUseId } from "react";
+
+export function useId(id?: string): string {
+  return id ?? reactUseId();
+}

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

@@ -0,0 +1,144 @@
+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 {
+  [sequence: string]: (event: KeyboardEvent) => void;
+}
+
+interface KeybindingLookupItem {
+  sequence: Set<string>;
+  handler: (event: KeyboardEvent) => void;
+}
+
+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*/);
+
+    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 {
+      parsedKeybindings.push({
+        sequence: new Set(parsedSequence),
+        handler,
+      });
+    }
+  }
+
+  return parsedKeybindings;
+}
+
+const defaultOptions: UseKeyboardEventOptions = {
+  eventKeyProp: 'key',
+};
+
+export function keyboardEventHandler(
+  bindings: KeyBindings,
+  options: UseKeyboardEventOptions = defaultOptions
+): KeyboardEventHandler {
+  const _options = { ...options, ...defaultOptions }
+
+  const keyBindings = parseKeybindings(bindings);
+
+  return (event: KeyboardEvent) => {
+    const keySequence = new Set<string>();
+    const eventKey = event[_options.eventKeyProp];
+
+    if (event.ctrlKey) keySequence.add('ctrl');
+
+    if (event.shiftKey) keySequence.add('shift');
+
+    if (event.altKey) keySequence.add('alt');
+
+    if (event.metaKey) keySequence.add('meta');
+
+    if (!KEY_MAPPINGS[eventKey]) keySequence.add(eventKey.toLowerCase());
+    else keySequence.add(KEY_MAPPINGS[eventKey]);
+
+    const matchedSequence = keyBindings.find(keyBinding => isSequenceEqual(keySequence, keyBinding.sequence));
+    if (matchedSequence) {
+      event.preventDefault();
+      event.stopPropagation();
+      matchedSequence.handler(event);
+    }
+  };
+}
+
+/**
+ * Returns a `KeyboardEventHandler`
+ * that checks the defined key binding 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.
+ *
+ * @example
+ * ```
+ * export function Input({ value, onChange }: Props) {
+ *   const [inputValue, setInputValue] = useState<string>('');
+ *
+ *   const clearInput = () => {
+ *     setInputValue('');
+ *   };
+ *
+ *   const addItem = () => {
+ *     if (inputValue) {
+ *       onChange([...value, inputValue]);
+ *       clearInput();
+ *     }
+ *   };
+ *
+ *   const deleteAll = () => {
+ *     onChange([]);
+ *     clearInput();
+ *   };
+ *
+ *   const handleKeyDown = useKeyboardEvent({
+ *     'enter': addItem,
+ *     'escape': clearInput,
+ *     'ctrl+c': clearInput,
+ *     'ctrl + shift + c': deleteAll,
+ *   });
+ *
+ *   return (
+ *      <input
+ *        value={inputValue}
+ *        onChange={event => setInputValue(event.target.value)}
+ *        onKeyDown={handleKeyDown}
+ *      />;
+ * }
+ * ```
+ */
+export function useKeyboardEvent(bindings: KeyBindings, options?: UseKeyboardEventOptions) {
+  return useMemo(() => keyboardEventHandler(bindings, options), [bindings, options]);
+}

package/src/lib/object.ts

@@ -0,0 +1,48 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+export const get = <T extends object>(object: T, prop: string) => prop
+    .split('.')
+    .reduce<any>((reducedObject, key) => (reducedObject && key in reducedObject) ? reducedObject[key] : undefined, object);
+
+export const set = <T extends object, V>(object: T, prop: string, value: V) => {
+    const propChunks = prop.split('.');
+    const lastChunk = propChunks.pop();
+    if (!lastChunk) return object;
+
+    const ref = propChunks.reduce<any>((reducedObject, key) => {
+        reducedObject[key] = {};
+        return reducedObject[key];
+    }, object);
+
+    ref[lastChunk] = value;
+
+    return object;
+}
+
+export const pick = <T extends object>(object: T, props: string[]) => {
+
+    return props.reduce<Record<string, unknown>>((result, key) => {
+
+        set(result, key, get(object, key));
+
+        return result;
+    }, {}) as Partial<T>;
+}
+
+export const omit = <T extends object>(object: T, props: string[]) => {
+    const result: Partial<T> = { ...object };
+
+    props.forEach(prop => {
+        const propChunks = prop.split('.');
+        const lastChunk = propChunks.pop();
+        if (lastChunk) {
+            const ref = propChunks.reduce<any>((reducedObject, key) => (reducedObject && key in reducedObject) ? reducedObject[key] : undefined, result);
+            if (ref && lastChunk in ref) delete ref[lastChunk];
+        }
+    })
+
+    return result;
+}
+
+export const isObject = (object: unknown) => (typeof object === 'object' && !Array.isArray(object) && object !== null);
+