@tcn/ui 0.2.0 → 0.3.1

package/src/layouts/utility_bar/utility_bar.module.css

@@ -1,7 +1,4 @@
 .utility-bar {
   width: 100%;
   min-height: 0;
-  border-bottom: 1px solid rgb(221, 221, 221);
-  padding: var(--padding-medium);
-  gap: var(--gap-medium);
 }

package/src/overlay/frame/frame.module.css

@@ -0,0 +1,5 @@
+.frame {
+  padding: 0;
+  border: none;
+  background: none;
+}

package/src/overlay/frame/frame.stories.tsx

@@ -6,7 +6,7 @@ import { BodyText } from '../../typography/index.js';
 import { Header } from '../../layouts/index.js';
 import styles from './frame_stories.module.css';
 export default {
-  title: 'Overlay/Floating/Frame',
+  title: 'Overlays/Floating/Frame',
   component: Frame,
   tags: ['autodocs'],
 

package/src/overlay/frame/frame.tsx

@@ -3,6 +3,10 @@ import { ZStack, type ZStackProps } from '../../stacks/index.js';
 import { Portal } from '../portal/portal.js';
 import { Draggable } from '../../utils/dnd/draggable/draggable.js';
 
+// Styles
+import styles from './frame.module.css';
+import { clsx } from 'clsx';
+
 export interface FrameOwnProps {
   isOpen?: boolean;
   children?: React.ReactNode;
@@ -13,7 +17,14 @@ export interface FrameOwnProps {
 export type FrameProps = ZStackProps & FrameOwnProps;
 
 export const Frame = React.forwardRef<HTMLDialogElement, FrameProps>(function Frame(
-  { children, isOpen = false, draggable = true, veil = false, ...rest }: FrameProps,
+  {
+    children,
+    isOpen = false,
+    draggable = true,
+    veil = false,
+    className,
+    ...rest
+  }: FrameProps,
   ref
 ) {
   if (!isOpen) {
@@ -22,9 +33,14 @@ export const Frame = React.forwardRef<HTMLDialogElement, FrameProps>(function Fr
 
   return (
     <Portal>
-      <ZStack width="100%" height="100%" data-is-veil={veil} className="tcn-frame">
+      <ZStack width="100%" height="100%" data-is-veil={veil} className="tcn-frame-veil">
         <Draggable draggable={draggable}>
-          <ZStack ref={ref} {...rest}>
+          <ZStack
+            as="dialog"
+            ref={ref}
+            className={clsx(styles['frame'], 'tcn-frame', className)}
+            {...rest}
+          >
             {children}
           </ZStack>
         </Draggable>

package/src/overlay/index.ts

@@ -1,6 +1,33 @@
 export * from './portal/portal.js';
 export * from './context_menu/context_menu.js';
 export * from './menu/menu.js';
-export * from './tooltip/tooltip.js';
-export * from './popper/popper.js';
+
 export { Frame, type FrameOwnProps, type FrameProps } from './frame/frame.js';
+export {
+  ElementTethered,
+  type ElementTetheredProps,
+} from './tethered/element_tethered.js';
+export { Tethered, type TetheredProps } from './tethered/tethered.js';
+export { type HorizontalTether, type VerticalTether } from './tethered/types.js';
+export * from './popper/legacy/popper.js';
+export {
+  PopperDismissal,
+  type PopperDismissalDecoratorProps,
+} from './popper/base/dismissal_decorator.js';
+export {
+  PreviewPopper,
+  type PreviewPopperProps,
+} from './popper/preview_popper.js';
+export {
+  ContextPopper,
+  type ContextPopperProps,
+} from './popper/context_popper.js';
+export {
+  ElementPopper,
+  type ElementPopperProps,
+} from './popper/element_popper.js';
+export {
+  type BasePopperOwnProps,
+  type BasePopperProps,
+  BasePopper,
+} from './popper/base/base_popper.js';

package/src/overlay/menu/menu.tsx

@@ -4,7 +4,7 @@ import { HStack } from '../../stacks/h_stack.js';
 import { VStack } from '../../stacks/v_stack.js';
 import type { HStackProps } from '../../stacks/h_stack.js';
 import type { VStackProps } from '../../stacks/v_stack.js';
-import { Popper, type PopperProps } from '../../overlay/popper/popper.js';
+import { Popper, type PopperProps } from '../popper/legacy/popper.js';
 import React, { useLayoutEffect, useRef, useState } from 'react';
 import styles from './menu.module.css';
 import { clsx } from 'clsx';

package/src/overlay/popper/__stories__/base_args.ts

@@ -0,0 +1,75 @@
+import { type ArgTypes } from '@storybook/react-vite';
+import { PopperDismissal } from '../base/dismissal_decorator.js';
+import type { BasePopperProps } from '../base/base_popper.js';
+import type { BaseTetheredOwnProps } from '../../tethered/tethered.js';
+
+export type SB_PopoverStoryProps = Pick<
+  BasePopperProps,
+  'restoreFocus' | 'dismissals' | 'veil'
+> &
+  BaseTetheredOwnProps;
+
+export const SBPopperInitialArgs: SB_PopoverStoryProps = {
+  verticalAnchor: 'top',
+  horizontalAnchor: 'center',
+  verticalOrigin: 'bottom',
+  horizontalOrigin: 'center',
+  verticalOffset: 0,
+  horizontalOffset: 0,
+  restoreFocus: false,
+  veil: false,
+};
+
+export const SBPopperBaseArgs: ArgTypes<SB_PopoverStoryProps> = {
+  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' },
+    defaultValue: 0,
+    description: 'The offset to position the popper vertically.',
+  },
+  horizontalOffset: {
+    control: { type: 'number' },
+    defaultValue: 0,
+    description: 'The offset to position the popper horizontally.',
+  },
+  restoreFocus: {
+    control: { type: 'boolean' },
+    defaultValue: false,
+    description: 'Whether to restore focus when the popper is closed.',
+  },
+  dismissals: {
+    options: [
+      PopperDismissal.SCROLL_AWAY,
+      PopperDismissal.CLICK_AWAY,
+      PopperDismissal.MOUSE_LEAVE,
+      PopperDismissal.VEIL_CLICK,
+    ],
+    control: { type: 'multi-select' },
+    defaultValue: [PopperDismissal.SCROLL_AWAY, PopperDismissal.CLICK_AWAY],
+    description: 'The dismissals to apply to the popper.',
+  },
+  veil: {
+    control: { type: 'boolean' },
+    defaultValue: false,
+    description: 'Whether to display a veil when the popper is open.',
+  },
+};

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