@tcn/ui 0.2.0 → 0.3.1

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

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

@@ -0,0 +1,90 @@
+import { Box, VStack } from '../../../../stacks/index.js';
+import type { Rectangle } from '../../../../utils/index.js';
+import { Portal } from '../../../portal/portal.js';
+import { Tethered, type TetheredProps } from '../../tethered.js';
+import { tetheredArgTypes, tetheredArgs } from '../shared/base_story_config.js';
+import { SBReferencePoints } from '../shared/components/sb_reference_points.js';
+
+import styles from './tethered_stories.module.css';
+
+export default {
+  title: 'Overlays/Tethered',
+  component: Tethered,
+  tags: ['autodocs'],
+  argTypes: tetheredArgTypes,
+  args: tetheredArgs,
+};
+
+type TetheredStoryProps = Omit<TetheredProps, 'anchor'>;
+
+export const Default = (args: TetheredStoryProps) => {
+  const anchorRect: Rectangle = {
+    dimensions: {
+      width: 150,
+      height: 75,
+    },
+    position: {
+      x: 150,
+      y: 200,
+    },
+  };
+
+  const tetherRect = {
+    dimensions: {
+      width: 200,
+      height: 50,
+    },
+    position: {
+      x: 100,
+      y: 100,
+    },
+  };
+
+  return (
+    <VStack height="100%" width="100%" hAlign="center" vAlign="center">
+      <VStack
+        className={styles.container}
+        hAlign="center"
+        vAlign="center"
+        height="500px"
+        width="500px"
+      >
+        <Portal>
+          <Box
+            className={styles.anchor}
+            height={anchorRect.dimensions.height}
+            width={anchorRect.dimensions.width}
+            style={
+              {
+                '--anchor-top': `${anchorRect.position.y}px`,
+                '--anchor-left': `${anchorRect.position.x}px`,
+              } as React.CSSProperties
+            }
+          >
+            Anchor Rectangle
+            <SBReferencePoints
+              dimensions={anchorRect.dimensions}
+              vertical={args.verticalAnchor || 'top'}
+              horizontal={args.horizontalAnchor || 'start'}
+            />
+          </Box>
+        </Portal>
+
+        <Tethered anchor={anchorRect} {...args}>
+          <Box
+            className={styles.tether}
+            height={tetherRect.dimensions.height}
+            width={tetherRect.dimensions.width}
+          >
+            Tether to Anchor Rectangle
+            <SBReferencePoints
+              dimensions={tetherRect.dimensions}
+              vertical={args.verticalOrigin || 'top'}
+              horizontal={args.horizontalOrigin || 'start'}
+            />
+          </Box>
+        </Tethered>
+      </VStack>
+    </VStack>
+  );
+};

package/src/overlay/tethered/__stories__/tethered/tethered_stories.module.css

@@ -0,0 +1,25 @@
+.container {
+  background-color: grey;
+  position: relative;
+}
+
+.anchor {
+  background-color: blue;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  color: white;
+  position: absolute;
+  top: var(--anchor-top);
+  left: var(--anchor-left);
+}
+
+.tether {
+  background-color: green;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  color: white;
+}

package/src/overlay/tethered/element_tethered.tsx

@@ -0,0 +1,62 @@
+import { forwardRef, useLayoutEffect, useState, type PropsWithChildren } from 'react';
+import { type Rectangle } from '../../utils/index.js';
+import { Tethered, type TetheredProps } from './tethered.js';
+
+export interface ElementTetheredProps extends Omit<TetheredProps, 'anchor'> {
+  anchorElement: React.RefObject<HTMLElement>;
+}
+
+function getElementRect(element: HTMLElement | null): Rectangle | null {
+  if (!element) return null;
+
+  const clientRect = element.getBoundingClientRect();
+
+  return {
+    position: { x: clientRect.left, y: clientRect.top },
+    dimensions: {
+      width: clientRect.width,
+      height: clientRect.height,
+    },
+  };
+}
+
+export const ElementTethered = forwardRef<
+  HTMLElement,
+  PropsWithChildren<ElementTetheredProps>
+>(function ElementTether({ anchorElement, children, ...rest }, ref) {
+  const [rectangle, setRectangle] = useState<Rectangle | null>(null);
+
+  useLayoutEffect(() => {
+    const element = anchorElement.current;
+    if (!element) return;
+
+    const update = () => {
+      setRectangle(getElementRect(element));
+    };
+
+    update();
+
+    // Track size/position changes of the anchor element via ResizeObserver
+    const resizeObserver = new ResizeObserver(update);
+    resizeObserver.observe(element);
+
+    // Track scroll-induced position changes
+    // TODO: might need to bypass react state here (setRectangle on scroll event) - to an OV or setting css variables/attributes directly
+    // This is a slight lag - not a huge deal, but could be improved.
+    window.addEventListener('scroll', update, true);
+    // Track window resize-induced position changes
+    window.addEventListener('resize', update);
+
+    return () => {
+      resizeObserver.disconnect();
+      window.removeEventListener('scroll', update, true);
+      window.removeEventListener('resize', update);
+    };
+  }, [anchorElement]);
+
+  return (
+    <Tethered ref={ref} anchor={rectangle} {...rest}>
+      {children}
+    </Tethered>
+  );
+});