@tcn/ui 0.2.0 → 0.3.0

package/src/overlay/popper/__stories__/context_popper.stories.tsx

@@ -0,0 +1,77 @@
+import { Meta } from '@storybook/react-vite';
+import React, { useRef } from 'react';
+import {
+  ContextPopper as ContextPopperComponent,
+  ContextPopperProps,
+} from '../context_popper.js';
+import { StyleBox } from '../../../stacks/story_components/style_box.js';
+import { VStack } from '../../../stacks/v_stack.js';
+import { BodyText } from '../../../typography/index.js';
+import { HStack } from '../../../stacks/h_stack.js';
+import { SBPopperBaseArgs, SBPopperInitialArgs } from './base_args.js';
+import { PopperDismissal } from '../base/dismissal_decorator.js';
+
+type ElementPopoverStoryProps = Omit<ContextPopperProps, 'anchorElement'> & {
+  clickAwayRefs?: React.RefObject<HTMLElement | null>[];
+};
+
+const meta: Meta<typeof ContextPopperComponent> = {
+  title: 'Overlays/Popper/Context Popper',
+  component: ContextPopperComponent,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'A popper component that displays a content in a portal.',
+      },
+    },
+  },
+  argTypes: SBPopperBaseArgs,
+  args: {
+    ...SBPopperInitialArgs,
+    dismissals: [PopperDismissal.CLICK_AWAY, PopperDismissal.SCROLL_AWAY],
+  },
+};
+
+export default meta;
+
+export function ContextPopper(props: ElementPopoverStoryProps) {
+  const anchorElement = useRef<HTMLButtonElement>(null);
+
+  return (
+    <VStack height="100%" width="100%" minHeight="600px" hAlign="center" vAlign="center">
+      <HStack
+        ref={anchorElement}
+        minWidth="200px"
+        minHeight="100px"
+        vAlign="center"
+        hAlign="center"
+        style={{ cursor: 'context-menu', background: 'blue', color: 'white' }}
+      >
+        Right-click me!
+      </HStack>
+      <ContextPopperComponent
+        anchorElement={anchorElement}
+        verticalAnchor={props.verticalAnchor}
+        verticalOrigin={props.verticalOrigin}
+        verticalOffset={props.verticalOffset}
+        horizontalAnchor={props.horizontalAnchor}
+        horizontalOrigin={props.horizontalOrigin}
+        horizontalOffset={props.horizontalOffset}
+        restoreFocus={props.restoreFocus}
+        dismissals={props.dismissals}
+        veil={props.veil}
+      >
+        <StyleBox
+          className="surface-primary"
+          boxShadow="0 0 10px 1px rgba(0,0,0,0.45)"
+          backgroundColor="white"
+          padding="8px"
+          borderRadius={'8px'}
+        >
+          <BodyText selectable>Hello World</BodyText>
+        </StyleBox>
+      </ContextPopperComponent>
+    </VStack>
+  );
+}

package/src/overlay/popper/__stories__/element_popper.stories.tsx

@@ -0,0 +1,80 @@
+import { Meta } from '@storybook/react-vite';
+import React, { useRef, useState } from 'react';
+import {
+  ElementPopper as ElementPopperComponent,
+  ElementPopperProps,
+} from '../element_popper.js';
+import { StyleBox } from '../../../stacks/story_components/style_box.js';
+import { VStack } from '../../../stacks/v_stack.js';
+import { BodyText } from '../../../typography/index.js';
+import { Button } from '../../../actions/index.js';
+import { SBPopperBaseArgs, SBPopperInitialArgs } from './base_args.js';
+
+type ElementPopoverStoryProps = Omit<
+  ElementPopperProps,
+  'anchorElement' | 'open' | 'onClose' | 'isScrollAwayException'
+> & {
+  clickAwayRefs?: React.RefObject<HTMLElement | null>[];
+  isScrollAwayException?: boolean;
+};
+
+const meta: Meta<typeof ElementPopperComponent> = {
+  title: 'Overlays/Popper/Element Popper',
+  component: ElementPopperComponent,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'A popper component that displays a content in a portal.',
+      },
+    },
+  },
+  argTypes: SBPopperBaseArgs,
+  args: SBPopperInitialArgs,
+};
+
+export default meta;
+
+export function ElementPopper(props: ElementPopoverStoryProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const anchorElement = useRef<HTMLButtonElement>(null);
+
+  function open() {
+    setIsOpen(true);
+  }
+
+  function close() {
+    setIsOpen(false);
+  }
+
+  return (
+    <VStack height="100%" width="100%" minHeight="600px" hAlign="center" vAlign="center">
+      <Button onClick={open} ref={anchorElement}>
+        Open
+      </Button>
+      <ElementPopperComponent
+        anchorElement={anchorElement}
+        open={isOpen}
+        onDismissal={close}
+        verticalAnchor={props.verticalAnchor}
+        verticalOrigin={props.verticalOrigin}
+        verticalOffset={props.verticalOffset}
+        horizontalAnchor={props.horizontalAnchor}
+        horizontalOrigin={props.horizontalOrigin}
+        horizontalOffset={props.horizontalOffset}
+        restoreFocus={props.restoreFocus}
+        dismissals={props.dismissals}
+      >
+        <StyleBox
+          className="surface-primary"
+          boxShadow="0 0 10px 1px rgba(0,0,0,0.45)"
+          backgroundColor="white"
+          padding="8px"
+          borderRadius={'8px'}
+        >
+          <BodyText selectable>Hello World</BodyText>
+        </StyleBox>
+      </ElementPopperComponent>
+    </VStack>
+  );
+}

package/src/overlay/popper/__stories__/preview_popper.stories.tsx

@@ -0,0 +1,73 @@
+import { Meta } from '@storybook/react-vite';
+import React, { useRef } from 'react';
+import {
+  PreviewPopper as PreviewPopperComponent,
+  PreviewPopperProps,
+} from '../preview_popper.js';
+import { StyleBox } from '../../../stacks/story_components/style_box.js';
+import { VStack } from '../../../stacks/v_stack.js';
+import { BodyText } from '../../../typography/index.js';
+import { SBPopperBaseArgs, SBPopperInitialArgs } from './base_args.js';
+
+type ElementPopoverStoryProps = Omit<PreviewPopperProps, 'anchorElement'> & {
+  clickAwayRefs?: React.RefObject<HTMLElement | null>[];
+};
+
+const meta: Meta<typeof PreviewPopperComponent> = {
+  title: 'Overlays/Popper/Preview Popper',
+  component: PreviewPopperComponent,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'A popper component that displays a content in a portal.',
+      },
+    },
+  },
+  argTypes: SBPopperBaseArgs,
+  args: SBPopperInitialArgs,
+};
+
+export default meta;
+
+export function SBPreviewPopper(props: ElementPopoverStoryProps) {
+  const anchorElement = useRef<HTMLDivElement>(null);
+
+  return (
+    <VStack height="100%" width="100%" minHeight="600px" hAlign="center" vAlign="center">
+      <StyleBox
+        ref={anchorElement}
+        backgroundColor="red"
+        padding="8px"
+        borderRadius={'8px'}
+        width="200px"
+        height="100px"
+        display="flex"
+        justifyContent="center"
+        alignItems="center"
+      >
+        Hover to open
+      </StyleBox>
+      <PreviewPopperComponent
+        anchorElement={anchorElement}
+        verticalAnchor={props.verticalAnchor}
+        verticalOrigin={props.verticalOrigin}
+        verticalOffset={props.verticalOffset}
+        horizontalAnchor={props.horizontalAnchor}
+        horizontalOrigin={props.horizontalOrigin}
+        horizontalOffset={props.horizontalOffset}
+        restoreFocus={props.restoreFocus}
+      >
+        <StyleBox
+          className="surface-primary"
+          boxShadow="0 0 10px 1px rgba(0,0,0,0.45)"
+          backgroundColor="white"
+          padding="8px"
+          borderRadius={'8px'}
+        >
+          <BodyText selectable>Hello World</BodyText>
+        </StyleBox>
+      </PreviewPopperComponent>
+    </VStack>
+  );
+}

package/src/overlay/popper/base/base_popper.tsx

@@ -0,0 +1,55 @@
+import { type PropsWithChildren } from 'react';
+import { useRestoreFocus } from '../hooks/use_restore_focus.js';
+import {
+  PopperDismissalDecorator,
+  type PopperDismissalDecoratorProps,
+} from './dismissal_decorator.js';
+
+export interface BasePopperOwnProps {
+  open: boolean;
+  restoreFocus?: boolean;
+  veil?: boolean;
+}
+
+export interface BasePopperProps
+  extends BasePopperOwnProps,
+    PopperDismissalDecoratorProps {}
+
+export const BasePopper: React.FC<PropsWithChildren<BasePopperProps>> = ({
+  restoreFocus = false,
+  open,
+  onDismissal,
+  isException,
+  dismissals = [],
+  acceptedRefs,
+  // TODO: add veil
+  // veil = false,
+  children,
+}) => {
+  useRestoreFocus(open, restoreFocus);
+
+  if (!open) return null;
+
+  // if (veil) {
+  //   content = (
+  //     <div
+  //     // TODO: add ref and onClick
+  //     // ref={veilRef}
+  //     // onClick={e => veilRef.current === e.target && onVeilClick && onVeilClick(e)}
+  //     >
+  //       {content}
+  //     </div>
+  //   );
+  // }
+
+  return (
+    <PopperDismissalDecorator
+      dismissals={dismissals}
+      onDismissal={onDismissal}
+      isException={isException}
+      acceptedRefs={acceptedRefs}
+    >
+      {children}
+    </PopperDismissalDecorator>
+  );
+};

package/src/overlay/popper/base/dismissal_decorator.tsx

@@ -0,0 +1,80 @@
+import { forwardRef, type PropsWithChildren } from 'react';
+import { ClickAwayListener } from '../../../utils/click_away_listener.js';
+import { ScrollAwayListener } from '../../../utils/scroll_away_listener.js';
+import { MouseLeaveRegion } from '../../../utils/mouse_leave_region.js';
+
+export enum PopperDismissal {
+  CLICK_AWAY = 'clickAway',
+  SCROLL_AWAY = 'scrollAway',
+  MOUSE_LEAVE = 'mouseLeave',
+  VEIL_CLICK = 'veilClick',
+}
+
+export interface PopperDismissalDecoratorProps {
+  dismissals?: PopperDismissal[];
+  onDismissal?: (dismissal: PopperDismissal) => void;
+  isException?: (dismissal: PopperDismissal, target: HTMLElement) => boolean;
+  acceptedRefs?: React.RefObject<HTMLElement>[];
+}
+
+export const PopperDismissalDecorator = forwardRef<
+  HTMLElement,
+  PropsWithChildren<PopperDismissalDecoratorProps>
+>(function DismissalDecorator(
+  { onDismissal, isException, dismissals = [], children, acceptedRefs = [] },
+  ref
+) {
+  const hasClickAway = dismissals.includes(PopperDismissal.CLICK_AWAY);
+  const hasScrollAway = dismissals.includes(PopperDismissal.SCROLL_AWAY);
+  const hasMouseLeave = dismissals.includes(PopperDismissal.MOUSE_LEAVE);
+  // TODO:
+  // const hasVeilClick = dismissals.includes(PopperDismissal.VEIL_CLICK);
+
+  const buildHandleDismissal = (dismissal: PopperDismissal) => () => {
+    onDismissal?.(dismissal);
+  };
+
+  function buildExceptionHandler(dismissal: PopperDismissal) {
+    if (dismissal in dismissals) {
+      return target => isException?.(dismissal, target) ?? false;
+    }
+    return () => false;
+  }
+
+  let content: React.ReactNode = (
+    <>
+      {children}
+      {hasMouseLeave && (
+        <MouseLeaveRegion
+          elementsRefs={acceptedRefs}
+          onMouseLeave={buildHandleDismissal(PopperDismissal.MOUSE_LEAVE)}
+        />
+      )}
+    </>
+  );
+
+  if (hasScrollAway) {
+    content = (
+      <ScrollAwayListener
+        onScrollAway={buildHandleDismissal(PopperDismissal.SCROLL_AWAY)}
+        isException={buildExceptionHandler(PopperDismissal.SCROLL_AWAY)}
+      >
+        {content}
+      </ScrollAwayListener>
+    );
+  }
+
+  if (hasClickAway) {
+    content = (
+      <ClickAwayListener
+        onClickAway={buildHandleDismissal(PopperDismissal.CLICK_AWAY)}
+        refs={acceptedRefs}
+        isException={buildExceptionHandler(PopperDismissal.CLICK_AWAY)}
+      >
+        {content}
+      </ClickAwayListener>
+    );
+  }
+
+  return content;
+});

package/src/overlay/popper/context_popper.tsx

@@ -0,0 +1,43 @@
+import { forwardRef, type PropsWithChildren } from 'react';
+import { BasePopper, type BasePopperProps } from './base/base_popper.js';
+import { Tethered, type TetheredProps } from '../tethered/tethered.js';
+import { useContextTrigger } from './hooks/use_context_trigger.js';
+import { PopperDismissal } from './base/dismissal_decorator.js';
+
+export type ContextPopperProps = Omit<BasePopperProps, 'open' | 'onDismissal'> &
+  Omit<TetheredProps, 'anchor'> & {
+    anchorElement: React.RefObject<HTMLElement>;
+  };
+
+export const ContextPopper = forwardRef<
+  HTMLDivElement,
+  PropsWithChildren<ContextPopperProps>
+>(function ContextPopper(
+  {
+    anchorElement,
+    restoreFocus,
+    children,
+    acceptedRefs = [],
+    isException,
+    dismissals = [PopperDismissal.CLICK_AWAY, PopperDismissal.SCROLL_AWAY],
+    ...tetheredProps
+  },
+  ref
+) {
+  const { isOpen, close, rectangle } = useContextTrigger(anchorElement);
+
+  return (
+    <BasePopper
+      open={isOpen && rectangle != null}
+      onDismissal={close}
+      restoreFocus={restoreFocus}
+      dismissals={dismissals}
+      acceptedRefs={acceptedRefs}
+      isException={isException}
+    >
+      <Tethered ref={ref} anchor={rectangle} {...tetheredProps}>
+        {children}
+      </Tethered>
+    </BasePopper>
+  );
+});

package/src/overlay/popper/element_popper.tsx

@@ -0,0 +1,42 @@
+import { forwardRef, type PropsWithChildren } from 'react';
+import { BasePopper, type BasePopperProps } from './base/base_popper.js';
+import {
+  ElementTethered,
+  type ElementTetheredProps,
+} from '../tethered/element_tethered.js';
+
+export type ElementPopperProps = BasePopperProps & ElementTetheredProps;
+
+export const ElementPopper = forwardRef<
+  HTMLDivElement,
+  PropsWithChildren<ElementPopperProps>
+>(function ElementPopper(
+  {
+    restoreFocus,
+    open,
+    onDismissal,
+    isException,
+    acceptedRefs,
+    veil,
+    dismissals,
+    children,
+    ...elementTetheredProps
+  },
+  ref
+) {
+  return (
+    <BasePopper
+      restoreFocus={restoreFocus}
+      open={open}
+      onDismissal={onDismissal}
+      isException={isException}
+      dismissals={dismissals}
+      acceptedRefs={acceptedRefs}
+      veil={veil}
+    >
+      <ElementTethered ref={ref} {...elementTetheredProps}>
+        {children}
+      </ElementTethered>
+    </BasePopper>
+  );
+});

package/src/overlay/popper/hooks/use_context_trigger.ts

@@ -0,0 +1,50 @@
+import { useCallback, useLayoutEffect, useState } from 'react';
+import type { Rectangle } from '../../../utils/types/dimensions.js';
+
+function getContextMenuRectangle(
+  element: HTMLElement | null,
+  mouseEvent: MouseEvent
+): Rectangle | null {
+  if (!element) return null;
+
+  const position = { x: mouseEvent.clientX, y: mouseEvent.clientY };
+
+  return {
+    position,
+    dimensions: {
+      width: 8,
+      height: 8,
+    },
+  };
+}
+
+export function useContextTrigger(anchorElement: React.RefObject<HTMLElement>) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [rectangle, setRectangle] = useState<Rectangle | null>(null);
+
+  const close = useCallback(() => {
+    setIsOpen(false);
+  }, []);
+
+  const handleContextMenu = useCallback(
+    (e: MouseEvent) => {
+      e.preventDefault();
+      setRectangle(getContextMenuRectangle(anchorElement.current, e));
+      setIsOpen(true);
+    },
+    [anchorElement]
+  );
+
+  useLayoutEffect(() => {
+    const element = anchorElement.current;
+    if (!element) return;
+
+    element.addEventListener('contextmenu', handleContextMenu);
+
+    return () => {
+      element.removeEventListener('contextmenu', handleContextMenu);
+    };
+  }, [anchorElement, handleContextMenu]);
+
+  return { isOpen, close, rectangle };
+}

package/src/overlay/popper/hooks/use_hover_trigger.ts

@@ -0,0 +1,24 @@
+import { useCallback, useLayoutEffect, useState } from 'react';
+
+export function usePreviewElement(anchorElement: React.RefObject<HTMLElement>) {
+  const [isOpen, setIsOpen] = useState(false);
+  const close = useCallback(() => {
+    setIsOpen(false);
+  }, []);
+
+  const open = useCallback(() => setIsOpen(true), []);
+
+  // Open on hover on the anchor element
+  useLayoutEffect(() => {
+    const anchor = anchorElement.current;
+    if (!anchor) return;
+
+    anchor.addEventListener('mouseenter', open);
+
+    return () => {
+      anchor.removeEventListener('mouseenter', open);
+    };
+  }, [anchorElement, open]);
+
+  return { isOpen, close, open };
+}

package/src/overlay/popper/hooks/use_restore_focus.ts

@@ -0,0 +1,16 @@
+import { useLayoutEffect, useRef } from 'react';
+
+export function useRestoreFocus(open: boolean, restoreFocus: boolean) {
+  const activeElementRef = useRef<HTMLElement | null>(null);
+
+  useLayoutEffect(() => {
+    if (open) {
+      activeElementRef.current = window.document.activeElement as HTMLElement;
+    } else {
+      const restoreToElement = activeElementRef.current;
+      requestAnimationFrame(() => {
+        restoreFocus && restoreToElement?.focus();
+      });
+    }
+  }, [open, restoreFocus]);
+}

package/src/overlay/popper/{popper.stories.tsx → legacy/popper.stories.tsx}

@@ -1,11 +1,11 @@
 import { Meta } from '@storybook/react-vite';
-import { BodyText } from '../../typography/index.js';
+import { BodyText } from '../../../typography/index.js';
 import React, { useLayoutEffect, useRef, useState } from 'react';
 import { Popper as PopperComponent, PopperProps } from './popper.js';
-import { HStack } from '../../stacks/h_stack.js';
-import { StyleBox } from '../../stacks/story_components/style_box.js';
-import { VStack } from '../../stacks/v_stack.js';
-import { ZStack } from '../../stacks/z_stack.js';
+import { HStack } from '../../../stacks/h_stack.js';
+import { StyleBox } from '../../../stacks/story_components/style_box.js';
+import { VStack } from '../../../stacks/v_stack.js';
+import { ZStack } from '../../../stacks/z_stack.js';
 
 type PopoverStoryProps = Omit<PopperProps, 'anchorElement' | 'open' | 'onClose'> & {
   clickAwayRefs?: React.RefObject<HTMLElement | null>[];
@@ -72,6 +72,11 @@ const meta: Meta<typeof PopperComponent> = {
       defaultValue: false,
       description: 'Whether to display a veil when the popper is open.',
     },
+    isScrollAwayException: {
+      control: { type: 'boolean' },
+      defaultValue: false,
+      description: 'Whether to scroll away the popper when the scroll area is scrolled.',
+    },
   },
 };
 
@@ -106,6 +111,7 @@ export function Popper(props: PopoverStoryProps) {
         horizontalOffset={props.horizontalOffset}
         restoreFocus={props.restoreFocus}
         veil={props.veil}
+        isScrollAwayException={props.isScrollAwayException}
       >
         <StyleBox
           className="surface-primary"

package/src/overlay/popper/{popper.tsx → legacy/popper.tsx}

@@ -1,6 +1,6 @@
-import { ClickAwayListener, ScrollAwayListener } from '../../utils/index.js';
+import { ClickAwayListener, ScrollAwayListener } from '../../../utils/index.js';
 import React, { useLayoutEffect, useRef, useState } from 'react';
-import { Portal } from '../portal/portal.js';
+import { Portal } from '../../portal/portal.js';
 import styles from './popper.module.css';
 
 export interface PopperProps {
@@ -23,6 +23,7 @@ export interface PopperProps {
   disableClickAway?: boolean;
 }
 
+// This component is being phased out in favor of ElementPopper - need to ensure parity beforehand.
 export function Popper({
   anchorElement,
   verticalAnchor = 'bottom',

package/src/overlay/popper/preview_popper.tsx

@@ -0,0 +1,54 @@
+import { forwardRef, useRef, type PropsWithChildren } from 'react';
+import { BasePopper, type BasePopperProps } from './base/base_popper.js';
+import { useForkRef } from '../../utils/index.js';
+import {
+  ElementTethered,
+  type ElementTetheredProps,
+} from '../tethered/element_tethered.js';
+import { usePreviewElement } from './hooks/use_hover_trigger.js';
+import { PopperDismissal } from './base/dismissal_decorator.js';
+
+export type PreviewPopperProps = Omit<BasePopperProps, 'open' | 'onDismissal'> &
+  ElementTetheredProps;
+
+export const PreviewPopper = forwardRef<
+  HTMLElement,
+  PropsWithChildren<PreviewPopperProps>
+>(function PreviewPopper(
+  {
+    anchorElement,
+    restoreFocus,
+    children,
+    acceptedRefs = [],
+    isException,
+    dismissals = [PopperDismissal.MOUSE_LEAVE],
+    ...elementTetheredProps
+  },
+  ref
+) {
+  const popperRef = useRef<HTMLElement>(null);
+  const merged = useForkRef(ref, popperRef);
+
+  const { isOpen, close } = usePreviewElement(anchorElement);
+
+  return (
+    <>
+      <BasePopper
+        restoreFocus={restoreFocus}
+        open={isOpen}
+        onDismissal={close}
+        isException={isException}
+        dismissals={dismissals}
+        acceptedRefs={[popperRef, ...acceptedRefs]}
+      >
+        <ElementTethered
+          ref={merged}
+          anchorElement={anchorElement}
+          {...elementTetheredProps}
+        >
+          {children}
+        </ElementTethered>
+      </BasePopper>
+    </>
+  );
+});