@tcn/ui 0.1.1 → 0.3.0

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>
+    </>
+  );
+});

package/src/overlay/tethered/__stories__/element/element_tethered.stories.tsx

@@ -0,0 +1,57 @@
+import { useRef } from 'react';
+import { HStack, VStack } from '../../../../stacks/index.js';
+import { ElementTethered, type ElementTetheredProps } from '../../element_tethered.js';
+import { tetheredArgTypes, tetheredArgs } from '../shared/base_story_config.js';
+
+import styles from './element_tethered_stories.module.css';
+
+export default {
+  title: 'Overlays/Element Tethered',
+  component: ElementTethered,
+  tags: ['autodocs'],
+  argTypes: tetheredArgTypes,
+  args: tetheredArgs,
+};
+
+type ElementTetheredStoryProps = Omit<ElementTetheredProps, 'anchorElement'>;
+
+export const Default = (args: ElementTetheredStoryProps) => {
+  const anchorElement = useRef<HTMLDivElement>(null);
+
+  return (
+    <VStack height="100%" width="100%" hAlign="center" vAlign="center">
+      <VStack
+        className={styles.container}
+        hAlign="center"
+        vAlign="center"
+        height="500px"
+        width="500px"
+      >
+        <HStack
+          padding="16px"
+          width="auto"
+          height="auto"
+          ref={anchorElement}
+          className={styles.anchor}
+          hAlign="center"
+          vAlign="center"
+        >
+          Anchor Element
+        </HStack>
+
+        <ElementTethered anchorElement={anchorElement} {...args}>
+          <HStack
+            className={styles.tethered}
+            width="auto"
+            height="auto"
+            padding="16px"
+            hAlign="center"
+            vAlign="center"
+          >
+            Tethered to Anchor Element
+          </HStack>
+        </ElementTethered>
+      </VStack>
+    </VStack>
+  );
+};

package/src/overlay/tethered/__stories__/element/element_tethered_stories.module.css

@@ -0,0 +1,14 @@
+.container {
+  background-color: #f0eee7; /* eggshell */
+}
+
+.anchor {
+  background: white;
+  border-radius: 8px;
+}
+
+.tethered {
+  background: white;
+  border-radius: 8px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
+}

package/src/overlay/tethered/__stories__/shared/base_story_config.ts

@@ -0,0 +1,52 @@
+import type { ArgTypes } from '@storybook/react-vite';
+import type { TetheredProps } from '../../tethered.js';
+
+type TetheredStoryArgs = Pick<
+  TetheredProps,
+  | 'verticalAnchor'
+  | 'horizontalAnchor'
+  | 'verticalOrigin'
+  | 'horizontalOrigin'
+  | 'verticalOffset'
+  | 'horizontalOffset'
+>;
+
+export const tetheredArgTypes: ArgTypes<TetheredStoryArgs> = {
+  verticalAnchor: {
+    options: ['top', 'center', 'bottom'],
+    control: { type: 'radio' },
+    description: 'The anchor to position the popper vertically.',
+  },
+  horizontalAnchor: {
+    options: ['start', 'center', 'end'],
+    control: { type: 'radio' },
+    description: 'The anchor to position the popper horizontally.',
+  },
+  verticalOrigin: {
+    options: ['top', 'center', 'bottom'],
+    control: { type: 'radio' },
+    description: 'The origin to position the popper vertically.',
+  },
+  horizontalOrigin: {
+    options: ['start', 'center', 'end'],
+    control: { type: 'radio' },
+    description: 'The origin to position the popper horizontally.',
+  },
+  verticalOffset: {
+    control: { type: 'number' },
+    description: 'The offset to position the popper vertically.',
+  },
+  horizontalOffset: {
+    control: { type: 'number' },
+    description: 'The offset to position the popper horizontally.',
+  },
+};
+
+export const tetheredArgs: TetheredStoryArgs = {
+  verticalAnchor: 'top',
+  horizontalAnchor: 'center',
+  verticalOrigin: 'bottom',
+  horizontalOrigin: 'center',
+  verticalOffset: 0,
+  horizontalOffset: 0,
+};

package/src/overlay/tethered/__stories__/shared/components/sb_point.module.css

@@ -0,0 +1,20 @@
+.point {
+  position: absolute;
+  left: var(--point-x);
+  top: var(--point-y);
+  border-radius: 50%;
+  background: black;
+  pointer-events: none;
+  opacity: 0.5;
+  translate: -50% -50%;
+  width: var(--point-size);
+  height: var(--point-size);
+}
+
+.point[data-selected="true"] {
+  width: calc(var(--point-size) * 1.5);
+  height: calc(var(--point-size) * 1.5);
+  opacity: 1;
+  background: var(--accent-color);
+  border: 1px solid white;
+}

package/src/overlay/tethered/__stories__/shared/components/sb_point.tsx

@@ -0,0 +1,34 @@
+import { Box, type BoxProps } from '../../../../../stacks/index.js';
+import type { Position } from '../../../../../utils/index.js';
+
+import styles from './sb_point.module.css';
+
+export interface SB_TetheredPointProps extends BoxProps {
+  point: Position;
+  isSelected: boolean;
+  size?: number;
+}
+
+export const SB_TetheredPoint: React.FC<SB_TetheredPointProps> = ({
+  point,
+  isSelected,
+  style,
+  size = 8,
+  ...rest
+}) => {
+  return (
+    <Box
+      className={styles.point}
+      data-selected={isSelected}
+      style={
+        {
+          ...style,
+          '--point-size': `${size}px`,
+          '--point-x': `${point.x}px`,
+          '--point-y': `${point.y}px`,
+        } as React.CSSProperties
+      }
+      {...rest}
+    />
+  );
+};

package/src/overlay/tethered/__stories__/shared/components/sb_reference_points.tsx

@@ -0,0 +1,54 @@
+import type { Dimensions } from '../../../../../utils/index.js';
+import type { VerticalTether, HorizontalTether } from '../../../types.js';
+import { SB_TetheredPoint } from './sb_point.js';
+
+type PointValue = `${VerticalTether}-${HorizontalTether}`;
+
+type SBReferencePoint = {
+  x: number;
+  y: number;
+  value: PointValue;
+};
+
+const mid = (value: number) => value / 2;
+
+const getPoints = (dimensions: Dimensions): SBReferencePoint[] => {
+  const mWidth = mid(dimensions.width);
+  const mHeight = mid(dimensions.height);
+  const { width, height } = dimensions;
+  return [
+    { x: 0, y: 0, value: 'top-start' },
+    { x: mWidth, y: 0, value: 'top-center' },
+    { x: width, y: 0, value: 'top-end' },
+    { x: 0, y: mHeight, value: 'center-start' },
+    { x: mWidth, y: mHeight, value: 'center-center' },
+    { x: width, y: mHeight, value: 'center-end' },
+    { x: 0, y: height, value: 'bottom-start' },
+    { x: mWidth, y: height, value: 'bottom-center' },
+    { x: width, y: height, value: 'bottom-end' },
+  ];
+};
+
+const getAnchorValue = (
+  verticalAnchor: VerticalTether,
+  horizontalAnchor: HorizontalTether
+): PointValue => {
+  return `${verticalAnchor}-${horizontalAnchor}`;
+};
+
+export const SBReferencePoints: React.FC<{
+  dimensions: Dimensions;
+  vertical: VerticalTether;
+  horizontal: HorizontalTether;
+}> = ({ dimensions, vertical, horizontal }) => {
+  const anchorPoints = getPoints(dimensions);
+  return (
+    <>
+      {anchorPoints.map((point, index) => {
+        const value = getAnchorValue(vertical, horizontal);
+        const isSelected = value === point.value;
+        return <SB_TetheredPoint key={index} point={point} isSelected={isSelected} />;
+      })}
+    </>
+  );
+};