@tcn/ui 0.0.1

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

@@ -0,0 +1,431 @@
+import { Meta } from '@storybook/react-vite';
+import { BodyText } from '../../typography/index.js';
+import React, { useLayoutEffect, useRef, useState } from 'react';
+import { Popper, 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';
+
+type PopoverStoryProps = Omit<PopperProps, 'anchorElement' | 'open' | 'onClose'> & {
+  clickAwayRefs?: React.RefObject<HTMLElement | null>[];
+};
+
+const meta: Meta<typeof Popper> = {
+  title: 'Popover',
+  component: Popper,
+  tags: ['autodocs'],
+  argTypes: {
+    children: { table: { disable: true } },
+    open: { table: { disable: true } },
+    onClose: { table: { disable: true } },
+    verticalAnchor: {
+      options: ['top', 'center', 'bottom'],
+      control: { type: 'radio' },
+    },
+    horizontalAnchor: {
+      options: ['start', 'center', 'end'],
+      control: { type: 'radio' },
+    },
+    verticalOrigin: {
+      options: ['top', 'center', 'bottom'],
+      control: { type: 'radio' },
+    },
+    horizontalOrigin: {
+      options: ['start', 'center', 'end'],
+      control: { type: 'radio' },
+    },
+    verticalOffset: {
+      control: { type: 'number' },
+      defaultValue: 0,
+    },
+    horizontalOffset: {
+      control: { type: 'number' },
+      defaultValue: 0,
+    },
+    restoreFocus: {
+      control: { type: 'boolean' },
+      defaultValue: false,
+    },
+    veil: {
+      control: { type: 'boolean' },
+      defaultValue: false,
+    },
+  },
+};
+
+export default meta;
+
+export function Baseline(props: PopoverStoryProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [anchorElement, setAnchorElement] = useState<HTMLElement | null>(null);
+
+  function open(event: React.MouseEvent<HTMLButtonElement>) {
+    setAnchorElement(event.currentTarget);
+    setIsOpen(true);
+  }
+
+  function close() {
+    setAnchorElement(null);
+    setIsOpen(false);
+  }
+
+  return (
+    <VStack height="100%" width="100%" minHeight="600px" hAlign="center" vAlign="center">
+      <button onClick={open}>Open</button>
+      <Popper
+        anchorElement={anchorElement}
+        open={isOpen}
+        onClose={close}
+        verticalAnchor={props.verticalAnchor}
+        verticalOrigin={props.verticalOrigin}
+        verticalOffset={props.verticalOffset}
+        horizontalAnchor={props.horizontalAnchor}
+        horizontalOrigin={props.horizontalOrigin}
+        horizontalOffset={props.horizontalOffset}
+        restoreFocus={props.restoreFocus}
+        veil={props.veil}
+      >
+        <StyleBox
+          className="surface-primary"
+          boxShadow="0 0 10px 1px rgba(0,0,0,0.45)"
+          padding="8px"
+          borderRadius={'8px'}
+        >
+          <BodyText selectable>Hello World</BodyText>
+        </StyleBox>
+      </Popper>
+    </VStack>
+  );
+}
+
+export function Focus(props: PopoverStoryProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [anchorElement, setAnchorElement] = useState<HTMLElement | null>(null);
+  const containerRef = useRef<HTMLButtonElement | null>(null);
+
+  function open(event: React.MouseEvent<HTMLButtonElement>) {
+    setAnchorElement(event.currentTarget);
+    setIsOpen(true);
+  }
+
+  function close() {
+    setAnchorElement(null);
+    setIsOpen(false);
+  }
+
+  useLayoutEffect(() => {
+    if (isOpen && containerRef.current) {
+      requestAnimationFrame(() => containerRef.current?.focus());
+    }
+  }, [isOpen]);
+
+  return (
+    <VStack height="100%" width="100%" minHeight="600px" hAlign="center" vAlign="center">
+      <button onClick={open}>Open</button>
+      <Popper
+        anchorElement={anchorElement}
+        open={isOpen}
+        onClose={close}
+        verticalAnchor={props.verticalAnchor}
+        verticalOrigin={props.verticalOrigin}
+        verticalOffset={props.verticalOffset}
+        horizontalAnchor={props.horizontalAnchor}
+        horizontalOrigin={props.horizontalOrigin}
+        horizontalOffset={props.horizontalOffset}
+        restoreFocus={props.restoreFocus}
+        veil={props.veil}
+      >
+        <StyleBox
+          tabIndex={0}
+          className="surface-primary"
+          boxShadow="0 0 10px 1px rgba(0,0,0,0.45)"
+          padding="8px"
+          borderRadius={'8px'}
+        >
+          <button ref={containerRef}>Hello World</button>
+        </StyleBox>
+      </Popper>
+    </VStack>
+  );
+}
+
+export function ScrollTest(props: PopoverStoryProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [anchorElement, setAnchorElement] = useState<HTMLElement | null>(null);
+
+  function open(event: React.MouseEvent<HTMLButtonElement>) {
+    setAnchorElement(event.currentTarget);
+    setIsOpen(true);
+  }
+
+  function close() {
+    setAnchorElement(null);
+    setIsOpen(false);
+  }
+
+  return (
+    <VStack
+      height="100%"
+      width="100%"
+      minHeight="600px"
+      maxHeight="800px"
+      overflowY="auto"
+    >
+      <VStack height="4000px" hAlign="center" vAlign="center">
+        <button onClick={open}>Open</button>
+        <Popper
+          anchorElement={anchorElement}
+          open={isOpen}
+          onClose={close}
+          verticalAnchor={props.verticalAnchor}
+          verticalOrigin={props.verticalOrigin}
+          verticalOffset={props.verticalOffset}
+          horizontalAnchor={props.horizontalAnchor}
+          horizontalOrigin={props.horizontalOrigin}
+          horizontalOffset={props.horizontalOffset}
+          restoreFocus={props.restoreFocus}
+          veil={props.veil}
+        >
+          <StyleBox
+            className="surface-primary"
+            boxShadow="0 0 10px 1px rgba(0,0,0,0.45)"
+            padding="8px"
+            borderRadius={'8px'}
+          >
+            <BodyText selectable>Hello World</BodyText>
+          </StyleBox>
+        </Popper>
+      </VStack>
+    </VStack>
+  );
+}
+
+export function ScrollWithinPopover(props: PopoverStoryProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [anchorElement, setAnchorElement] = useState<HTMLElement | null>(null);
+
+  function open(event: React.MouseEvent<HTMLButtonElement>) {
+    setAnchorElement(event.currentTarget);
+    setIsOpen(true);
+  }
+
+  function close() {
+    setAnchorElement(null);
+    setIsOpen(false);
+  }
+
+  return (
+    <VStack
+      height="100%"
+      width="100%"
+      minHeight="600px"
+      maxHeight="800px"
+      overflowY="auto"
+    >
+      <VStack height="4000px" hAlign="center" vAlign="center">
+        <button onClick={open}>Open</button>
+        <Popper
+          anchorElement={anchorElement}
+          open={isOpen}
+          onClose={close}
+          verticalAnchor={props.verticalAnchor}
+          verticalOrigin={props.verticalOrigin}
+          verticalOffset={props.verticalOffset}
+          horizontalAnchor={props.horizontalAnchor}
+          horizontalOrigin={props.horizontalOrigin}
+          horizontalOffset={props.horizontalOffset}
+          restoreFocus={props.restoreFocus}
+          veil={props.veil}
+        >
+          <StyleBox
+            className="surface-primary"
+            boxShadow="0 0 10px 1px rgba(0,0,0,0.45)"
+            padding="8px"
+            borderRadius={'8px'}
+            overflow="auto"
+            height="300px"
+            width="300px"
+          >
+            <ZStack height="1000px">Hello</ZStack>
+          </StyleBox>
+        </Popper>
+      </VStack>
+    </VStack>
+  );
+}
+
+export function ClickAwayRefs(props: PopoverStoryProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [anchorElement, setAnchorElement] = useState<HTMLElement | null>(null);
+  const safeElementRef = useRef<HTMLDivElement>(null);
+  const anotherSafeElementRef = useRef<HTMLDivElement>(null);
+
+  function open(event: React.MouseEvent<HTMLButtonElement>) {
+    setAnchorElement(event.currentTarget);
+    setIsOpen(true);
+  }
+
+  function close() {
+    setAnchorElement(null);
+    setIsOpen(false);
+  }
+
+  // Create refs that match the Popover's expected type
+  const clickAwayRefs: React.RefObject<HTMLElement>[] = [
+    safeElementRef as unknown as React.RefObject<HTMLElement>,
+    anotherSafeElementRef as unknown as React.RefObject<HTMLElement>,
+  ];
+
+  return (
+    <VStack hAlign="center" vAlign="center" gap="16px">
+      <HStack gap="16px">
+        <button onClick={open}>Open Popover</button>
+        <div
+          ref={safeElementRef}
+          style={{
+            padding: '8px',
+            backgroundColor: '#e0e0e0',
+            borderRadius: '4px',
+            cursor: 'pointer',
+          }}
+        >
+          Safe to click (won't close popover)
+        </div>
+        <div
+          ref={anotherSafeElementRef}
+          style={{
+            padding: '8px',
+            backgroundColor: '#e0e0e0',
+            borderRadius: '4px',
+            cursor: 'pointer',
+          }}
+        >
+          Also safe to click
+        </div>
+      </HStack>
+      <Popper
+        anchorElement={anchorElement}
+        open={isOpen}
+        onClose={close}
+        clickAwayRefs={clickAwayRefs}
+        verticalAnchor={props.verticalAnchor}
+        verticalOrigin={props.verticalOrigin}
+        verticalOffset={props.verticalOffset}
+        horizontalAnchor={props.horizontalAnchor}
+        horizontalOrigin={props.horizontalOrigin}
+        horizontalOffset={props.horizontalOffset}
+        restoreFocus={props.restoreFocus}
+        veil={props.veil}
+      >
+        <StyleBox
+          className="surface-primary"
+          boxShadow="0 0 10px 1px rgba(0,0,0,0.45)"
+          padding="8px"
+          borderRadius={'8px'}
+        >
+          <BodyText selectable>
+            Click outside to close, but the gray boxes are safe to click!
+          </BodyText>
+        </StyleBox>
+      </Popper>
+    </VStack>
+  );
+}
+
+export function DisableClickAway(props: PopoverStoryProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [anchorElement, setAnchorElement] = useState<HTMLElement | null>(null);
+
+  function open(event: React.MouseEvent<HTMLButtonElement>) {
+    setAnchorElement(event.currentTarget);
+    setIsOpen(true);
+  }
+
+  function close() {
+    setAnchorElement(null);
+    setIsOpen(false);
+  }
+
+  return (
+    <VStack hAlign="center" vAlign="center" gap="16px">
+      <HStack gap="16px">
+        <button onClick={open}>Open Popover</button>
+        <button onClick={close}>Close Popover</button>
+      </HStack>
+      <Popper
+        anchorElement={anchorElement}
+        open={isOpen}
+        onClose={close}
+        disableClickAway={true}
+        verticalAnchor={props.verticalAnchor}
+        verticalOrigin={props.verticalOrigin}
+        verticalOffset={props.verticalOffset}
+        horizontalAnchor={props.horizontalAnchor}
+        horizontalOrigin={props.horizontalOrigin}
+        horizontalOffset={props.horizontalOffset}
+        restoreFocus={props.restoreFocus}
+        veil={props.veil}
+      >
+        <StyleBox
+          className="surface-primary"
+          boxShadow="0 0 10px 1px rgba(0,0,0,0.45)"
+          padding="8px"
+          borderRadius={'8px'}
+        >
+          <BodyText selectable>
+            This popover won't close when clicking outside. Use the Close button to close
+            it.
+          </BodyText>
+        </StyleBox>
+      </Popper>
+    </VStack>
+  );
+}
+
+export function VeilClick(props: PopoverStoryProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [anchorElement, setAnchorElement] = useState<HTMLElement | null>(null);
+
+  function open(event: React.MouseEvent<HTMLButtonElement>) {
+    setAnchorElement(event.currentTarget);
+    setIsOpen(true);
+  }
+
+  function close() {
+    setAnchorElement(null);
+    setIsOpen(false);
+  }
+
+  return (
+    <VStack hAlign="center" vAlign="center" gap="16px">
+      <HStack gap="16px">
+        <button onClick={open}>Open Popover</button>
+      </HStack>
+      <Popper
+        anchorElement={anchorElement}
+        open={isOpen}
+        onClose={close}
+        disableClickAway={true}
+        onVeilClick={close}
+        veil={true}
+        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)"
+          padding="8px"
+          borderRadius={'8px'}
+        >
+          <BodyText selectable>This popover will close on clicking the veil.</BodyText>
+        </StyleBox>
+      </Popper>
+    </VStack>
+  );
+}

package/src/overlay/popper/popper.tsx

@@ -0,0 +1,218 @@
+import { ClickAwayListener, ScrollAwayListener } from '../../utils/index.js';
+import React, { useLayoutEffect, useRef, useState } from 'react';
+import { Portal } from '../portal/portal.js';
+import styles from './popper.module.css';
+
+export interface PopperProps {
+  anchorElement: HTMLElement | null;
+  verticalAnchor?: 'top' | 'center' | 'bottom';
+  verticalOrigin?: 'top' | 'center' | 'bottom';
+  verticalOffset?: number;
+  horizontalAnchor?: 'start' | 'center' | 'end';
+  horizontalOrigin?: 'start' | 'center' | 'end';
+  horizontalOffset?: number;
+  open: boolean;
+  onClose: () => void;
+  restoreFocus?: boolean;
+  children: React.ReactNode;
+  veil?: boolean;
+  onVeilClick?: (e: React.MouseEvent<HTMLDivElement, MouseEvent>) => void;
+  clickAwayRefs?: React.RefObject<HTMLElement>[];
+  isClickAwayException?: (target: HTMLElement) => boolean;
+  isScrollAwayException?: (target: HTMLElement) => boolean;
+  disableClickAway?: boolean;
+}
+
+export function Popper({
+  anchorElement,
+  verticalAnchor = 'bottom',
+  verticalOrigin = 'top',
+  verticalOffset = 0,
+  horizontalAnchor = 'start',
+  horizontalOrigin = 'start',
+  horizontalOffset = 0,
+  restoreFocus = false,
+  veil = false,
+  onVeilClick,
+  clickAwayRefs = [],
+  open,
+  onClose,
+  children,
+  disableClickAway = false,
+  isClickAwayException,
+  isScrollAwayException,
+}: PopperProps) {
+  const anchorElementRef = useRef(anchorElement);
+  const [position, setPosition] = useState({ top: 0, left: 0 });
+  const activeElementRef = useRef<HTMLElement | null>(null);
+  const popoverRef = useRef<HTMLDivElement>(null);
+  const canOpen = open && anchorElement != null;
+  const finalClickAwayRefs: React.RefObject<HTMLElement>[] = clickAwayRefs ?? [];
+  const enableClickAway = !disableClickAway;
+  const veilRef = useRef<HTMLDivElement>(null);
+  function close() {
+    onClose && onClose();
+  }
+
+  // eslint-disable-next-line complexity
+  const updatePosition = () => {
+    if (!anchorElement || !popoverRef.current) return;
+
+    const anchorRect = anchorElement.getBoundingClientRect();
+    const popoverRect = popoverRef.current.getBoundingClientRect();
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+
+    // Determine the text direction (ltr or rtl)
+    const computedStyle = getComputedStyle(anchorElement);
+    const isRtl = computedStyle.direction === 'rtl';
+
+    let top = anchorRect.top;
+    let left = anchorRect.left;
+
+    // Calculate vertical position
+    switch (verticalAnchor) {
+      case 'top':
+        top += verticalOffset;
+        break;
+      case 'center':
+        top += anchorRect.height / 2;
+        break;
+      case 'bottom':
+        top += anchorRect.height - verticalOffset;
+        break;
+    }
+
+    switch (verticalOrigin) {
+      case 'top':
+        break;
+      case 'center':
+        top -= popoverRect.height / 2;
+        break;
+      case 'bottom':
+        top -= popoverRect.height;
+        break;
+    }
+
+    // Calculate horizontal position with direction sensitivity
+    if (horizontalAnchor === 'start') {
+      left += isRtl ? anchorRect.width + horizontalOffset : horizontalOffset;
+    } else if (horizontalAnchor === 'center') {
+      left += anchorRect.width / 2;
+    } else if (horizontalAnchor === 'end') {
+      left += isRtl ? -horizontalOffset : anchorRect.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 -= popoverRect.width / 2;
+    } else if (adjustedHorizontalOrigin === 'end') {
+      left -= popoverRect.width;
+    }
+
+    // Ensure the popover stays within the viewport
+    // Prevent overflow to the right
+    if (left + popoverRect.width > viewportWidth) {
+      left = viewportWidth - popoverRect.width;
+    }
+
+    // Prevent overflow to the left
+    if (left < 0) {
+      left = 0;
+    }
+
+    // Prevent overflow to the bottom
+    if (top + popoverRect.height > viewportHeight) {
+      top = viewportHeight - popoverRect.height;
+    }
+
+    // Prevent overflow to the top
+    if (top < 0) {
+      top = 0;
+    }
+
+    // Only update if position has changed to avoid unnecessary re-renders
+    if (top !== position.top || left !== position.left) {
+      setPosition({ top, left });
+    }
+  };
+
+  useLayoutEffect(() => {
+    updatePosition();
+    window.addEventListener('resize', updatePosition);
+    return () => {
+      window.removeEventListener('resize', updatePosition);
+    };
+  });
+
+  useLayoutEffect(() => {
+    if (open) {
+      activeElementRef.current = window.document.activeElement as HTMLElement;
+    } else {
+      const restoreToElement = activeElementRef.current;
+      requestAnimationFrame(() => {
+        restoreFocus && restoreToElement?.focus();
+      });
+    }
+  }, [open, restoreFocus]);
+
+  if (!canOpen) {
+    return null;
+  }
+
+  anchorElementRef.current = anchorElement;
+
+  let content = (
+    <ScrollAwayListener onScrollAway={close} isException={isScrollAwayException}>
+      <div
+        ref={popoverRef}
+        className={styles.popover}
+        style={{
+          top: `${position.top}px`,
+          left: `${position.left}px`,
+        }}
+      >
+        {children}
+      </div>
+    </ScrollAwayListener>
+  );
+
+  if (enableClickAway) {
+    content = (
+      <ClickAwayListener
+        onClickAway={close}
+        refs={[anchorElementRef, ...finalClickAwayRefs]}
+        isException={isClickAwayException}
+      >
+        {content}
+      </ClickAwayListener>
+    );
+  }
+
+  return (
+    <Portal>
+      {veil && (
+        <div
+          ref={veilRef}
+          onClick={e => veilRef.current === e.target && onVeilClick && onVeilClick(e)}
+          className={styles['popover-veil']}
+        >
+          {content}
+        </div>
+      )}
+      {!veil && content}
+    </Portal>
+  );
+}

package/src/overlay/portal/portal.css

@@ -0,0 +1,35 @@
+body > * {
+  position: relative;
+  z-index: 0;
+}
+
+.portal {
+  position: absolute;
+  top: 0px;
+  left: 0px;
+  bottom: 0px;
+  right: 0px;
+  overflow: hidden;
+  padding: 0px;
+  margin: 0px;
+  pointer-events: none;
+}
+
+.portal > * {
+  pointer-events: auto;
+}
+
+.portal-platform {
+  position: fixed;
+  top: 0px;
+  left: 0px;
+  bottom: 0px;
+  right: 0px;
+  overflow: hidden;
+  padding: 0px;
+  margin: 0px;
+  background-color: rgba(0, 0, 0, 0);
+  pointer-events: none;
+  transform: none;
+  z-index: 1;
+}