@tcn/ui 0.1.1 → 0.3.0

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';

package/src/stacks/box/box.tsx

@@ -45,8 +45,14 @@ export interface BoxProps extends HTMLAttributes<HTMLElement> {
   enableResizeOnRight?: boolean;
   horizontalHandleProps?: HandleProps;
   verticalHandleProps?: HandleProps;
-  onWidthResize?: (width: number) => void;
-  onHeightResize?: (width: number) => void;
+  onWidthResize?: (
+    width: number
+    // origin: 'left' | 'right'
+  ) => void;
+  onHeightResize?: (
+    height: number
+    // origin: 'top' | 'bottom'
+  ) => void;
   onWidthResizeEnd?: (width: number) => void;
   onHeightResizeEnd?: (width: number) => void;
 }

package/src/stacks/h_stack.stories.tsx

@@ -80,7 +80,7 @@ const meta: Meta<HStackProps> = {
 
 export default meta;
 
-export function HStack(props: HStackProps) {
+export function SB_HStack(props: HStackProps) {
   return (
     <StyleBox border="1px dashed #ccc" backgroundColor="white">
       <HStackComponent {...props}>
@@ -99,7 +99,7 @@ export function HStack(props: HStackProps) {
   );
 }
 
-HStack.storyName = 'HStack';
+SB_HStack.storyName = 'HStack';
 
 export function ManyChildren(props: HStackProps) {
   return (

package/src/stacks/v_stack.stories.tsx

@@ -80,7 +80,7 @@ const meta: Meta<VStackProps> = {
 
 export default meta;
 
-export function VStack(props: VStackProps) {
+export function SBVStack(props: VStackProps) {
   return (
     <StyleBox
       borderLeft="1px dashed #ccc"
@@ -102,7 +102,7 @@ export function VStack(props: VStackProps) {
   );
 }
 
-VStack.storyName = 'VStack';
+SBVStack.storyName = 'VStack';
 
 export function Padding() {
   return (

package/src/surfaces/card/card.stories.tsx

@@ -0,0 +1,64 @@
+import { BugIcon } from '@tcn/icons/bug_icon.js';
+import { GridOneIcon } from '@tcn/icons/grid_one_icon.js';
+import { Header } from '../../layouts/header/header.js';
+import { VBody } from '../../layouts/body/v_body.js';
+import { UtilityBar } from '../../layouts/utility_bar/utility_bar.js';
+import { Box, Spacer } from '../../stacks/index.js';
+import { Title } from '../../typography/title/title.js';
+import { SlimButton } from '../../actions/index.js';
+import { Card } from './card.js';
+
+// Styles
+import styles from './card_stories.module.css';
+
+export default {
+  title: 'Surfaces/Card',
+  component: Card,
+  tags: ['autodocs'],
+};
+
+export const Default = () => {
+  return (
+    <div className={styles['stories-container']}>
+      <Card maxHeight="400px">
+        <Header>
+          <Title>Card Header</Title>
+          <Spacer />
+          <SlimButton hierarchy="tertiary">
+            <GridOneIcon />
+          </SlimButton>
+          <SlimButton hierarchy="tertiary">
+            <GridOneIcon />
+          </SlimButton>
+        </Header>
+        <UtilityBar>
+          <Title>Utility Bar</Title>
+          <Spacer />
+          <SlimButton hierarchy="tertiary">
+            <BugIcon />
+          </SlimButton>
+          <SlimButton hierarchy="tertiary">
+            <BugIcon />
+          </SlimButton>
+          <SlimButton size="md" hierarchy="tertiary">
+            <BugIcon />
+          </SlimButton>
+          <SlimButton hierarchy="tertiary">
+            <BugIcon />
+          </SlimButton>
+        </UtilityBar>
+
+        <VBody>
+          <Box className={styles['content-box']} />
+        </VBody>
+        {/* Cards typically do not have a footer */}
+        {/* <Footer>
+          <Title>Footer</Title>
+          <Spacer />
+          <Button hierarchy="secondary">Secondary</Button>
+          <Button hierarchy="primary">Primary</Button>
+        </Footer> */}
+      </Card>
+    </div>
+  );
+};

package/src/surfaces/card/card.tsx

@@ -1,8 +1,8 @@
-import { VStack, type VStackProps } from '../../stacks/v_stack.js';
 import { clsx } from 'clsx';
 import React from 'react';
+import { Scaffold, type ScaffoldProps } from '../../layouts/scaffold/scaffold.js';
 
-export interface CardProps extends Omit<VStackProps, 'as' | 'children'> {
+export interface CardProps extends Omit<ScaffoldProps, 'as' | 'children'> {
   children?: React.ReactNode;
 }
 
@@ -11,8 +11,8 @@ export const Card = React.forwardRef<HTMLElement, CardProps>(function Card(
   ref
 ) {
   return (
-    <VStack ref={ref} as="section" className={clsx(className, 'tcn-card')} {...props}>
+    <Scaffold ref={ref} className={clsx(className, 'tcn-surface', 'tcn-card')} {...props}>
       {children}
-    </VStack>
+    </Scaffold>
   );
 });

package/src/surfaces/card/card_stories.module.css

@@ -0,0 +1,13 @@
+.content-box {
+  background: rgba(0, 128, 0, 0.5);
+  min-height: 200px;
+  width: 100%;
+}
+
+.stories-container {
+  width: 100%;
+  height: 100%;
+  padding: 16px;
+  background-color: #ccc;
+  overflow: auto;
+}

package/src/surfaces/index.ts

@@ -1,14 +1,16 @@
 export * from './alert/alert.js';
 export * from './card/card.js';
 export * from './confirm/confirm.js';
-export * from './modal/modal.js';
 export * from './page/h_page.js';
 export * from './page/v_page.js';
 export * from './panel/h_panel.js';
 export * from './panel/v_panel.js';
 export * from './popover/popover.js';
-export * from './window/window.js';
 export * from './drawers/drawer_bottom/drawer_bottom.js';
 export * from './drawers/drawer_top/drawer_top.js';
 export * from './drawers/drawer_start/drawer_start.js';
 export * from './drawers/drawer_end/drawer_end.js';
+export { Window, type WindowProps } from './window/window.js';
+export { Modal, type ModalProps } from './modal/modal.js';
+export { Tooltip, type TooltipProps } from './tooltip/tooltip.js';
+export { PopConfirm, type PopConfirmProps } from './pop_confirm/pop_confirm.js';