@tcn/ui 0.2.0 → 0.3.0

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

package/src/overlay/tethered/hooks/calculate_position.ts

@@ -0,0 +1,110 @@
+import type { HorizontalTether, VerticalTether } from '../types.js';
+import type { Rectangle } from '../../../utils/index.js';
+import type { Dimensions } from '../../../utils/index.js';
+
+export interface CalculateTetheredPositionParams {
+  anchor: Rectangle;
+  tether: Rectangle;
+  direction: 'ltr' | 'rtl';
+  verticalAnchor: VerticalTether;
+  verticalOrigin: VerticalTether;
+  horizontalAnchor: HorizontalTether;
+  horizontalOrigin: HorizontalTether;
+  verticalOffset: number;
+  horizontalOffset: number;
+  viewport: Dimensions;
+}
+
+export const calculateTetheredPosition = ({
+  anchor,
+  tether,
+  direction,
+  verticalAnchor,
+  verticalOrigin,
+  horizontalAnchor,
+  horizontalOrigin,
+  verticalOffset,
+  horizontalOffset,
+  viewport,
+}: CalculateTetheredPositionParams) => {
+  const isRtl = direction === 'rtl';
+
+  let top = anchor.position.y;
+  let left = anchor.position.x;
+
+  // Calculate vertical position
+  switch (verticalAnchor) {
+    case 'top':
+      top += verticalOffset;
+      break;
+    case 'center':
+      top += anchor.dimensions.height / 2;
+      break;
+    case 'bottom':
+      top += anchor.dimensions.height - verticalOffset;
+      break;
+  }
+
+  switch (verticalOrigin) {
+    case 'top':
+      break;
+    case 'center':
+      top -= tether.dimensions.height / 2;
+      break;
+    case 'bottom':
+      top -= tether.dimensions.height;
+      break;
+  }
+
+  // Calculate horizontal position with direction sensitivity
+  if (horizontalAnchor === 'start') {
+    left += isRtl ? anchor.dimensions.width + horizontalOffset : horizontalOffset;
+  } else if (horizontalAnchor === 'center') {
+    left += anchor.dimensions.width / 2;
+  } else if (horizontalAnchor === 'end') {
+    left += isRtl ? -horizontalOffset : anchor.dimensions.width + horizontalOffset;
+  }
+
+  // Adjust the origin based on RTL direction
+  let adjustedHorizontalOrigin = horizontalOrigin;
+  if (isRtl) {
+    if (horizontalOrigin === 'start') {
+      adjustedHorizontalOrigin = 'end';
+    } else if (horizontalOrigin === 'end') {
+      adjustedHorizontalOrigin = 'start';
+    }
+  }
+
+  // Apply adjusted origin to the position calculation
+  if (adjustedHorizontalOrigin === 'start') {
+    // No adjustment needed
+  } else if (adjustedHorizontalOrigin === 'center') {
+    left -= tether.dimensions.width / 2;
+  } else if (adjustedHorizontalOrigin === 'end') {
+    left -= tether.dimensions.width;
+  }
+
+  // Ensure the popover stays within the viewport
+  // Prevent overflow to the right
+  if (left + tether.dimensions.width > viewport.width) {
+    left = viewport.width - tether.dimensions.width;
+  }
+
+  // Prevent overflow to the left
+  if (left < 0) {
+    left = 0;
+  }
+
+  // Prevent overflow to the bottom
+  // FIXME: doesn't account for padding.
+  if (top + tether.dimensions.height > viewport.height) {
+    top = viewport.height - tether.dimensions.height;
+  }
+
+  // Prevent overflow to the top
+  if (top < 0) {
+    top = 0;
+  }
+
+  return { top, left };
+};

package/src/overlay/tethered/hooks/useTether.ts

@@ -0,0 +1,85 @@
+import { useCallback, useLayoutEffect, useRef, useState } from 'react';
+import type { HorizontalTether, VerticalTether } from '../types.js';
+import { type Rectangle } from '../../../utils/index.js';
+import { calculateTetheredPosition } from './calculate_position.js';
+
+export interface UseTetherParams {
+  anchor: Rectangle | null;
+  verticalAnchor?: VerticalTether;
+  verticalOrigin?: VerticalTether;
+  horizontalOrigin?: HorizontalTether;
+  horizontalAnchor?: HorizontalTether;
+  verticalOffset?: number;
+  horizontalOffset?: number;
+}
+
+export function useTether({
+  anchor,
+  verticalAnchor = 'bottom',
+  verticalOrigin = 'top',
+  horizontalAnchor = 'start',
+  horizontalOrigin = 'start',
+  verticalOffset = 0,
+  horizontalOffset = 0,
+}: UseTetherParams) {
+  const [position, setPosition] = useState({ top: 0, left: 0 });
+  const tetherRef = useRef<HTMLDivElement>(null);
+
+  const getPosition = useCallback(() => {
+    if (!anchor || !tetherRef.current) return;
+
+    const tether = tetherRef.current.getBoundingClientRect();
+    const computedStyle = getComputedStyle(tetherRef.current);
+
+    return calculateTetheredPosition({
+      anchor: anchor,
+      tether: {
+        dimensions: {
+          width: tether.width,
+          height: tether.height,
+        },
+        position: {
+          x: tether.left,
+          y: tether.top,
+        },
+      },
+      direction: computedStyle.direction as 'ltr' | 'rtl',
+      verticalAnchor: verticalAnchor,
+      verticalOrigin: verticalOrigin,
+      horizontalAnchor: horizontalAnchor,
+      horizontalOrigin: horizontalOrigin,
+      verticalOffset: verticalOffset,
+      horizontalOffset: horizontalOffset,
+      viewport: {
+        width: window.innerWidth,
+        height: window.innerHeight,
+      },
+    });
+  }, [
+    anchor,
+    verticalAnchor,
+    verticalOrigin,
+    horizontalAnchor,
+    horizontalOrigin,
+    verticalOffset,
+    horizontalOffset,
+  ]);
+
+  // Update the position when the window is resized
+  useLayoutEffect(() => {
+    const update = () => {
+      const newPosition = getPosition();
+      if (!newPosition) return;
+      if (position.top !== newPosition.top || position.left !== newPosition.left) {
+        setPosition(newPosition);
+      }
+    };
+    update();
+    window.addEventListener('resize', update);
+    return () => {
+      window.removeEventListener('resize', update);
+    };
+  });
+
+  return { position, tetherRef };
+}

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

@@ -0,0 +1,8 @@
+.tethered {
+  display: inline-block;
+  position: absolute;
+  width: auto;
+  height: auto;
+  left: var(--tethered-left, 0);
+  top: var(--tethered-top, 0);
+}

package/src/overlay/tethered/tethered.tsx

@@ -0,0 +1,72 @@
+import { forwardRef, type PropsWithChildren } from 'react';
+import type { HorizontalTether, VerticalTether } from './types.js';
+import { ZStack, type ZStackProps } from '../../stacks/index.js';
+import { useForkRef, type Rectangle } from '../../utils/index.js';
+import { useTether } from './hooks/useTether.js';
+import { clsx } from 'clsx';
+import { Portal } from '../portal/portal.js';
+
+// Styles
+import styles from './tethered.module.css';
+
+export interface BaseTetheredOwnProps {
+  verticalAnchor?: VerticalTether;
+  verticalOrigin?: VerticalTether;
+  horizontalOrigin?: HorizontalTether;
+  horizontalAnchor?: HorizontalTether;
+  verticalOffset?: number;
+  horizontalOffset?: number;
+}
+
+export interface TetheredOwnProp extends BaseTetheredOwnProps {
+  anchor: Rectangle | null;
+}
+export interface TetheredProps extends TetheredOwnProp, ZStackProps {}
+
+export const Tethered = forwardRef<HTMLElement, PropsWithChildren<TetheredProps>>(
+  function Tethered(
+    {
+      anchor,
+      verticalAnchor = 'bottom',
+      verticalOrigin = 'top',
+      horizontalAnchor = 'start',
+      horizontalOrigin = 'start',
+      verticalOffset = 0,
+      horizontalOffset = 0,
+      children,
+      style,
+      className,
+      ...rest
+    },
+    ref
+  ) {
+    const { position, tetherRef } = useTether({
+      anchor,
+      verticalAnchor,
+      verticalOrigin,
+      horizontalAnchor,
+      horizontalOrigin,
+      verticalOffset,
+      horizontalOffset,
+    });
+    const forkedRef = useForkRef(ref, tetherRef);
+
+    const cssVariables = {
+      '--tethered-top': `${position.top}px`,
+      '--tethered-left': `${position.left}px`,
+    };
+
+    return (
+      <Portal>
+        <ZStack
+          ref={forkedRef}
+          className={clsx(styles.tethered, className)}
+          style={{ position: 'absolute', ...cssVariables, ...style }}
+          {...rest}
+        >
+          {children}
+        </ZStack>
+      </Portal>
+    );
+  }
+);

package/src/overlay/tethered/types.ts

@@ -0,0 +1,2 @@
+export type VerticalTether = 'top' | 'center' | 'bottom';
+export type HorizontalTether = 'start' | 'center' | 'end';