@stack-spot/citric-react 0.42.0-beta.0 → 0.43.0

package/src/components/Overlay/index.tsx

@@ -1,182 +1,182 @@
-import { useEffect, useRef } from 'react'
-import { showOverlay } from '../../overlay'
-import { HTMLTag } from '../../types'
-import { focusFirstChild } from '../../utils/acessibility'
-import { delay } from '../../utils/time'
-import { OverlayProvider } from './context'
-import { OverlayController, OverlayProps } from './types'
-export { useOverlayController } from './context'
-
-/**
- * An arbitrary time to wait for the next React render to be performed
- */
-const arbitraryRenderTime = 20
-
-/**
- * These todos are in order of priority.
- * 
- * TODO: update position when the size changes. Currently, the top position seems out of place whenever the height changes. The same is
- * probably true for the left position if the width changes.
- * TODO (minor): use React Portal to implement overlays. The current implementation will lose every React context in the tree.
- */
-
-/**
- * Creates an overlay for the child component. The overlay can be any React element. The overlay can be triggered by "click" or "hover"
- * (default).
- * 
- * The overlay can be hidden from within its content through the hook `useOverlayController()`.
- * 
- * @example
- * 
- * ```
- * const overlay = <Card>Hey, this is my overlay!</Card>
- * 
- * return (
- *   <Overlay content={overlay} attributes={{ style: { margin: '20px' } }}>
- *     <Button>Hover to see the overlay</Button>
- *   </Overlay>
- * )
- * ```
- */
-export function Overlay<T extends keyof HTMLTag>({
-  tag,
-  children,
-  content,
-  position = 'top',
-  triggerOn = 'hover',
-  alignment = 'center',
-  attributes,
-  onRenderChild,
-  autoFocusBehavior = 'keyboard',
-  openDelayMS,
-  closeDelayMS,
-  ...props
-}: OverlayProps<T>,
-) {
-  const controller = useRef<OverlayController>({ close: () => Promise.resolve() })
-  const wrapper = useRef<HTMLDivElement | null>(null)
-  // props that don't require removing and reattaching the event listeners
-  const dynamic = useRef({ tag, content, position, alignment, attributes })
-
-  useEffect(() => {
-    dynamic.current = { tag, content, position, alignment, attributes }
-  }, [tag, content, position, alignment, attributes])
-
-  useEffect(() => {
-    let visible = false
-    let hideOnClickOutside: ((event: Event) => void) | undefined
-    let hideOnEsc: ((event: Event) => void) | undefined
-    let hideOverlay: ((immediately?: boolean) => Promise<void>) | undefined
-    let removeRefocusTargetListener: (() => void) | undefined
-
-    function getTarget() {
-      const target = wrapper.current?.firstChild
-      return target instanceof HTMLElement ? target : undefined
-    }
-
-    if (onRenderChild) {
-      const target = getTarget()
-      if (target) onRenderChild(target)
-    }
-
-    async function show(event: Event) {
-      if (visible) return
-      visible = true
-      const target = getTarget()
-      if (openDelayMS && triggerOn === 'hover') {
-        await delay(openDelayMS)
-        if (!target?.matches(':hover, :focus')) {
-          visible = false
-          return
-        }
-      }
-      if (!target) return
-      const { overlay, hide: hideFn } = showOverlay({
-        tag: dynamic.current.tag,
-        content: ['string', 'number', 'boolean'].includes(typeof dynamic.current.content)
-          ? dynamic.current.content
-          : <OverlayProvider value={controller.current}>{dynamic.current.content}</OverlayProvider>,
-        target,
-        position: dynamic.current.position,
-        alignment: dynamic.current.alignment,
-        attributes: dynamic.current.attributes,
-      })
-      hideOverlay?.(true) // ensures there's no lost opened overlay.
-      hideOverlay = hideFn
-
-      function onHide(condition: (event: Event) => boolean) {
-        return (event: Event) => {
-          if (condition(event)) controller.current.close()
-        }
-      }
-
-      if (event.type === 'click') {
-        hideOnEsc = onHide(e => e instanceof KeyboardEvent && e.key === 'Escape')
-        setTimeout(() => {
-          hideOnClickOutside = onHide(e => e instanceof MouseEvent && e.button === 0 && !overlay.contains(e.target as HTMLElement))
-          document.addEventListener('click', hideOnClickOutside)
-        }, arbitraryRenderTime)
-        document.addEventListener('keydown', hideOnEsc)
-      }
-
-      // focus target when the last overlay element loses focus
-      function refocusTarget(e: KeyboardEvent) {
-        if (e.key === 'Tab' && e.target instanceof HTMLElement) {
-          const allItems = Array.from(e.target.closest('[data-citric="menu"]')?.querySelectorAll('a, button') ?? [])
-          if (e.target === allItems[allItems.length - 1]) {
-            getTarget()?.focus()
-            e.preventDefault()
-          }
-        }
-      }
-      overlay.addEventListener('keydown', refocusTarget)
-      removeRefocusTargetListener = () => overlay.removeEventListener('keydown', refocusTarget)
-
-      // auto-focus
-      const openedWithMouse = event instanceof MouseEvent && event.detail > 0
-      if (autoFocusBehavior === 'always' || (autoFocusBehavior === 'keyboard' && !openedWithMouse)) {
-        setTimeout(() => focusFirstChild(overlay), arbitraryRenderTime)
-      }
-    }
-
-    controller.current.close = async (immediately = false) => {
-      if (!immediately && (closeDelayMS ?? 0) > 0) {
-        await delay(closeDelayMS ?? 0)
-      }
-      visible = false
-      if (hideOnClickOutside) document.removeEventListener('click', hideOnClickOutside)
-      if (hideOnEsc) document.removeEventListener('keydown', hideOnEsc)
-      removeRefocusTargetListener?.()
-      await hideOverlay?.()
-    }
-
-    if (triggerOn === 'hover') {
-      const close = () => controller.current.close()
-      getTarget()?.addEventListener('mouseenter', show)
-      getTarget()?.addEventListener('mouseleave', close)
-      getTarget()?.addEventListener('focus', show)
-      getTarget()?.addEventListener('blur', close)
-      return () => {
-        getTarget()?.removeEventListener('mouseenter', show)
-        getTarget()?.removeEventListener('mouseleave', close)
-        getTarget()?.removeEventListener('focus', show)
-        getTarget()?.removeEventListener('blur', close)
-      }
-    }
-
-    if (triggerOn === 'click') {
-      getTarget()?.addEventListener('click', show)
-      return () => {
-        controller.current.close()
-        getTarget()?.removeEventListener('click', show)
-        if (hideOnClickOutside) document.removeEventListener('click', hideOnClickOutside)
-      }
-    }
-  }, [wrapper.current, triggerOn])
-
-  useEffect(() => () => {
-    controller.current?.close(true)
-  }, [])
-
-  return <div ref={wrapper} {...props}>{children}</div>
-}
+import { useEffect, useRef } from 'react'
+import { showOverlay } from '../../overlay'
+import { HTMLTag } from '../../types'
+import { focusFirstChild } from '../../utils/acessibility'
+import { delay } from '../../utils/time'
+import { OverlayProvider } from './context'
+import { OverlayController, OverlayProps } from './types'
+export { useOverlayController } from './context'
+
+/**
+ * An arbitrary time to wait for the next React render to be performed
+ */
+const arbitraryRenderTime = 20
+
+/**
+ * These todos are in order of priority.
+ * 
+ * TODO: update position when the size changes. Currently, the top position seems out of place whenever the height changes. The same is
+ * probably true for the left position if the width changes.
+ * TODO (minor): use React Portal to implement overlays. The current implementation will lose every React context in the tree.
+ */
+
+/**
+ * Creates an overlay for the child component. The overlay can be any React element. The overlay can be triggered by "click" or "hover"
+ * (default).
+ * 
+ * The overlay can be hidden from within its content through the hook `useOverlayController()`.
+ * 
+ * @example
+ * 
+ * ```
+ * const overlay = <Card>Hey, this is my overlay!</Card>
+ * 
+ * return (
+ *   <Overlay content={overlay} attributes={{ style: { margin: '20px' } }}>
+ *     <Button>Hover to see the overlay</Button>
+ *   </Overlay>
+ * )
+ * ```
+ */
+export function Overlay<T extends keyof HTMLTag>({
+  tag,
+  children,
+  content,
+  position = 'top',
+  triggerOn = 'hover',
+  alignment = 'center',
+  attributes,
+  onRenderChild,
+  autoFocusBehavior = 'keyboard',
+  openDelayMS,
+  closeDelayMS,
+  ...props
+}: OverlayProps<T>,
+) {
+  const controller = useRef<OverlayController>({ close: () => Promise.resolve() })
+  const wrapper = useRef<HTMLDivElement | null>(null)
+  // props that don't require removing and reattaching the event listeners
+  const dynamic = useRef({ tag, content, position, alignment, attributes })
+
+  useEffect(() => {
+    dynamic.current = { tag, content, position, alignment, attributes }
+  }, [tag, content, position, alignment, attributes])
+
+  useEffect(() => {
+    let visible = false
+    let hideOnClickOutside: ((event: Event) => void) | undefined
+    let hideOnEsc: ((event: Event) => void) | undefined
+    let hideOverlay: ((immediately?: boolean) => Promise<void>) | undefined
+    let removeRefocusTargetListener: (() => void) | undefined
+
+    function getTarget() {
+      const target = wrapper.current?.firstChild
+      return target instanceof HTMLElement ? target : undefined
+    }
+
+    if (onRenderChild) {
+      const target = getTarget()
+      if (target) onRenderChild(target)
+    }
+
+    async function show(event: Event) {
+      if (visible) return
+      visible = true
+      const target = getTarget()
+      if (openDelayMS && triggerOn === 'hover') {
+        await delay(openDelayMS)
+        if (!target?.matches(':hover, :focus')) {
+          visible = false
+          return
+        }
+      }
+      if (!target) return
+      const { overlay, hide: hideFn } = showOverlay({
+        tag: dynamic.current.tag,
+        content: ['string', 'number', 'boolean'].includes(typeof dynamic.current.content)
+          ? dynamic.current.content
+          : <OverlayProvider value={controller.current}>{dynamic.current.content}</OverlayProvider>,
+        target,
+        position: dynamic.current.position,
+        alignment: dynamic.current.alignment,
+        attributes: dynamic.current.attributes,
+      })
+      hideOverlay?.(true) // ensures there's no lost opened overlay.
+      hideOverlay = hideFn
+
+      function onHide(condition: (event: Event) => boolean) {
+        return (event: Event) => {
+          if (condition(event)) controller.current.close()
+        }
+      }
+
+      if (event.type === 'click') {
+        hideOnEsc = onHide(e => e instanceof KeyboardEvent && e.key === 'Escape')
+        setTimeout(() => {
+          hideOnClickOutside = onHide(e => e instanceof MouseEvent && e.button === 0 && !overlay.contains(e.target as HTMLElement))
+          document.addEventListener('click', hideOnClickOutside)
+        }, arbitraryRenderTime)
+        document.addEventListener('keydown', hideOnEsc)
+      }
+
+      // focus target when the last overlay element loses focus
+      function refocusTarget(e: KeyboardEvent) {
+        if (e.key === 'Tab' && e.target instanceof HTMLElement) {
+          const allItems = Array.from(e.target.closest('[data-citric="menu"]')?.querySelectorAll('a, button') ?? [])
+          if (e.target === allItems[allItems.length - 1]) {
+            getTarget()?.focus()
+            e.preventDefault()
+          }
+        }
+      }
+      overlay.addEventListener('keydown', refocusTarget)
+      removeRefocusTargetListener = () => overlay.removeEventListener('keydown', refocusTarget)
+
+      // auto-focus
+      const openedWithMouse = event instanceof MouseEvent && event.detail > 0
+      if (autoFocusBehavior === 'always' || (autoFocusBehavior === 'keyboard' && !openedWithMouse)) {
+        setTimeout(() => focusFirstChild(overlay), arbitraryRenderTime)
+      }
+    }
+
+    controller.current.close = async (immediately = false) => {
+      if (!immediately && (closeDelayMS ?? 0) > 0) {
+        await delay(closeDelayMS ?? 0)
+      }
+      visible = false
+      if (hideOnClickOutside) document.removeEventListener('click', hideOnClickOutside)
+      if (hideOnEsc) document.removeEventListener('keydown', hideOnEsc)
+      removeRefocusTargetListener?.()
+      await hideOverlay?.()
+    }
+
+    if (triggerOn === 'hover') {
+      const close = () => controller.current.close()
+      getTarget()?.addEventListener('mouseenter', show)
+      getTarget()?.addEventListener('mouseleave', close)
+      getTarget()?.addEventListener('focus', show)
+      getTarget()?.addEventListener('blur', close)
+      return () => {
+        getTarget()?.removeEventListener('mouseenter', show)
+        getTarget()?.removeEventListener('mouseleave', close)
+        getTarget()?.removeEventListener('focus', show)
+        getTarget()?.removeEventListener('blur', close)
+      }
+    }
+
+    if (triggerOn === 'click') {
+      getTarget()?.addEventListener('click', show)
+      return () => {
+        controller.current.close()
+        getTarget()?.removeEventListener('click', show)
+        if (hideOnClickOutside) document.removeEventListener('click', hideOnClickOutside)
+      }
+    }
+  }, [wrapper.current, triggerOn])
+
+  useEffect(() => () => {
+    controller.current?.close(true)
+  }, [])
+
+  return <div ref={wrapper} {...props}>{children}</div>
+}

package/src/components/Overlay/types.ts

@@ -1,75 +1,75 @@
-import { OverlayOptions } from '../../overlay'
-import { HTMLTag } from '../../types'
-
-export type TriggerOn = 'hover' | 'click'
-
-export interface BaseOverlayProps<T extends keyof HTMLTag> extends Omit<OverlayOptions<T>, 'target'> {
-  /**
-   * When should the overlay element be created? When the child is clicked or when the child is hovered?
-   * 
-   * Accessibility:
-   * Click = focus + press enter to open; focus + enter to close OR esc.
-   * Hover = focus to open; blur to close.
-   * 
-   * @default 'hover'
-   */
-  triggerOn?: TriggerOn,
-  /**
-   * Only valid if `triggerOn` is "hover".
-   * 
-   * Waits the given amount of milliseconds before closing the overlay.
-   * 
-   * @default 0
-   */
-  closeDelayMS?: number,
-  /**
-   * Only valid if `triggerOn` is "hover".
-   * 
-   * Waits the given amount of milliseconds before opening the overlay.
-   * 
-   * @default 0
-   */
-  openDelayMS?: number,
-  /**
-   * TODO: not implemented yet.
-   * 
-   * - Never: the focus won't changes when the overlay opens.
-   * - All: the focus always changes when the overlay opens (given there's a focusable element in the overlay).
-   * - Keyboard (default): the focus only changes when the overlay is opened via the keyboard.
-   * 
-   * The first focusable element in the overlay will be focused as soon as it's rendered. When it's closed, the child element
-   * (`children`) regains focus.
-   * 
-   * The focus control will be such that, after the last element in the overlay is focused, the next focus will move to the child element
-   * (`children`).
-   * 
-   * If the overlay has no focusable element, this properties makes no difference.
-   * 
-   * Attention: focusable elements inside the overlay can be ignored by setting `auto-focus` to false.
-   * 
-   * @default 'keyboard'
-   */
-  autoFocusBehavior?: 'never' | 'always' | 'keyboard',
-  /**
-   * The element to receive the overlay.
-   */
-  children: React.ReactElement,
-  /**
-   * Function to run when the child is rendered. It receives the child element as a parameter.
-   * 
-   * This is useful for easily adding attributes to the element (mainly accessibility ones).
-   * @param element the child element, the one that receives the overlay.
-   */
-  onRenderChild?: (element: HTMLElement) => void,
-}
-
-export type OverlayProps<T extends keyof HTMLTag> = Omit<React.JSX.IntrinsicElements['div'], 'content'> & BaseOverlayProps<T>
-
-export interface OverlayController {
-  /**
-   * Closes the tooltip.
-   * @param immediately when true, ignores the closeDelayMS parameter.
-   * @returns a promise that resolves when the overlay is removed from the DOM.
-   */
-  close: (immediately?: boolean) => Promise<void>,
-}
+import { OverlayOptions } from '../../overlay'
+import { HTMLTag } from '../../types'
+
+export type TriggerOn = 'hover' | 'click'
+
+export interface BaseOverlayProps<T extends keyof HTMLTag> extends Omit<OverlayOptions<T>, 'target'> {
+  /**
+   * When should the overlay element be created? When the child is clicked or when the child is hovered?
+   * 
+   * Accessibility:
+   * Click = focus + press enter to open; focus + enter to close OR esc.
+   * Hover = focus to open; blur to close.
+   * 
+   * @default 'hover'
+   */
+  triggerOn?: TriggerOn,
+  /**
+   * Only valid if `triggerOn` is "hover".
+   * 
+   * Waits the given amount of milliseconds before closing the overlay.
+   * 
+   * @default 0
+   */
+  closeDelayMS?: number,
+  /**
+   * Only valid if `triggerOn` is "hover".
+   * 
+   * Waits the given amount of milliseconds before opening the overlay.
+   * 
+   * @default 0
+   */
+  openDelayMS?: number,
+  /**
+   * TODO: not implemented yet.
+   * 
+   * - Never: the focus won't changes when the overlay opens.
+   * - All: the focus always changes when the overlay opens (given there's a focusable element in the overlay).
+   * - Keyboard (default): the focus only changes when the overlay is opened via the keyboard.
+   * 
+   * The first focusable element in the overlay will be focused as soon as it's rendered. When it's closed, the child element
+   * (`children`) regains focus.
+   * 
+   * The focus control will be such that, after the last element in the overlay is focused, the next focus will move to the child element
+   * (`children`).
+   * 
+   * If the overlay has no focusable element, this properties makes no difference.
+   * 
+   * Attention: focusable elements inside the overlay can be ignored by setting `auto-focus` to false.
+   * 
+   * @default 'keyboard'
+   */
+  autoFocusBehavior?: 'never' | 'always' | 'keyboard',
+  /**
+   * The element to receive the overlay.
+   */
+  children: React.ReactElement,
+  /**
+   * Function to run when the child is rendered. It receives the child element as a parameter.
+   * 
+   * This is useful for easily adding attributes to the element (mainly accessibility ones).
+   * @param element the child element, the one that receives the overlay.
+   */
+  onRenderChild?: (element: HTMLElement) => void,
+}
+
+export type OverlayProps<T extends keyof HTMLTag> = Omit<React.JSX.IntrinsicElements['div'], 'content'> & BaseOverlayProps<T>
+
+export interface OverlayController {
+  /**
+   * Closes the tooltip.
+   * @param immediately when true, ignores the closeDelayMS parameter.
+   * @returns a promise that resolves when the overlay is removed from the DOM.
+   */
+  close: (immediately?: boolean) => Promise<void>,
+}