@structuralists/scaffolding 0.0.1

package/src/components/Overlays/Popover/index.tsx

@@ -0,0 +1,175 @@
+import {
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+} from 'react';
+import { createPortal } from 'react-dom';
+import type { PopoverPlacement, PopoverProps } from './types';
+import { cx } from '../../../utils';
+import styles from './styles.module.css';
+
+const GAP = 6;
+
+type Position = {
+  top: number;
+  left: number;
+  /** Side of the panel that's closest to the anchor — used as transform-origin
+   *  so the open animation grows *from* the trigger, not from panel center. */
+  originV: 'top' | 'bottom';
+  originH: 'left' | 'right';
+};
+
+const computePosition = (
+  anchor: DOMRect,
+  panel: DOMRect,
+  preferred: PopoverPlacement,
+): Position => {
+  const winW = window.innerWidth;
+  const winH = window.innerHeight;
+
+  const preferBottom =
+    preferred === 'auto'
+      ? winH - anchor.bottom >= panel.height + GAP ||
+        winH - anchor.bottom >= anchor.top
+      : preferred.startsWith('bottom');
+
+  const preferStart =
+    preferred === 'auto'
+      ? anchor.left + panel.width <= winW
+      : preferred.endsWith('-start');
+
+  const top = preferBottom
+    ? anchor.bottom + GAP
+    : anchor.top - panel.height - GAP;
+  const left = preferStart ? anchor.left : anchor.right - panel.width;
+
+  // 8px viewport margin keeps a near-edge anchor from pushing the panel off.
+  const clampedLeft = Math.max(8, Math.min(left, winW - panel.width - 8));
+  const clampedTop = Math.max(8, Math.min(top, winH - panel.height - 8));
+
+  return {
+    top: clampedTop,
+    left: clampedLeft,
+    originV: preferBottom ? 'top' : 'bottom',
+    originH: preferStart ? 'left' : 'right',
+  };
+};
+
+export const Popover = (props: PopoverProps) => {
+  const {
+    anchorRef,
+    isOpen,
+    onClose,
+    title,
+    actions,
+    ariaLabel,
+    placement = 'auto',
+    matchAnchorWidth,
+    hasBodyPadding = true,
+    children,
+  } = props;
+
+  const panelRef = useRef<HTMLDivElement>(null);
+  const restoreFocusRef = useRef<HTMLElement | null>(null);
+  const [position, setPosition] = useState<Position | null>(null);
+  const titleId = useId();
+
+  useLayoutEffect(() => {
+    if (!isOpen) {
+      setPosition(null);
+      return;
+    }
+    const anchor = anchorRef.current;
+    const panel = panelRef.current;
+    if (!anchor || !panel) return;
+
+    const anchorRect = anchor.getBoundingClientRect();
+
+    // Apply the anchor width *before* measuring the panel rect so the panel's
+    // height reflects the final width (content may wrap differently).
+    if (matchAnchorWidth) {
+      panel.style.width = `${anchorRect.width}px`;
+      panel.style.minWidth = `${anchorRect.width}px`;
+    }
+
+    setPosition(
+      computePosition(anchorRect, panel.getBoundingClientRect(), placement),
+    );
+  }, [isOpen, anchorRef, placement, matchAnchorWidth]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handleMouseDown = (e: MouseEvent) => {
+      const target = e.target as Node;
+      if (panelRef.current?.contains(target)) return;
+      if (anchorRef.current?.contains(target)) return;
+      onClose();
+    };
+
+    const handleKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+
+    window.addEventListener('mousedown', handleMouseDown);
+    window.addEventListener('keydown', handleKey);
+    return () => {
+      window.removeEventListener('mousedown', handleMouseDown);
+      window.removeEventListener('keydown', handleKey);
+    };
+  }, [isOpen, anchorRef, onClose]);
+
+  // Capture the anchor at open time so a rerender that swaps the element
+  // still restores focus to whatever the user originally engaged.
+  useEffect(() => {
+    if (isOpen) {
+      restoreFocusRef.current = anchorRef.current;
+      return;
+    }
+    if (restoreFocusRef.current) {
+      restoreFocusRef.current.focus();
+      restoreFocusRef.current = null;
+    }
+  }, [isOpen, anchorRef]);
+
+  if (!isOpen) return null;
+
+  const style: CSSProperties = position
+    ? {
+        top: position.top,
+        left: position.left,
+        transformOrigin: `${position.originV} ${position.originH}`,
+      }
+    : { top: 0, left: 0, visibility: 'hidden' };
+
+  // Portal to <body> so we sit at the same DOM depth as every other layer
+  // (modal, future tooltip/menu when they get layered). Stacking falls out
+  // of mount order — the most-recently-opened layer is the last child of
+  // <body> and paints on top, no z-index tier required.
+  return createPortal(
+    <div
+      ref={panelRef}
+      className={styles.panel}
+      role="dialog"
+      aria-labelledby={title ? titleId : undefined}
+      aria-label={!title ? ariaLabel : undefined}
+      style={style}
+    >
+      {title && (
+        <div id={titleId} className={styles.title}>
+          {title}
+        </div>
+      )}
+      <div className={cx(styles.body, !hasBodyPadding && styles.bodyFlush)}>
+        {children}
+      </div>
+      {actions && <div className={styles.actions}>{actions}</div>}
+    </div>,
+    document.body,
+  );
+};
+
+export type { PopoverProps, PopoverPlacement };

package/src/components/Overlays/Popover/styles.module.css

@@ -0,0 +1,59 @@
+.panel {
+  position: fixed;
+  /* Same z-index as ModalShell's .layer — all portal layers share one tier
+   * and rely on DOM-append order for stacking. The most-recently-opened
+   * layer is the last child of <body> and paints on top. */
+  z-index: 100;
+  min-width: 18rem;
+  max-width: min(480px, calc(100vw - 32px));
+  background-color: var(--ui-background-0);
+  border: 1px solid var(--ui-border);
+  border-radius: var(--ui-radius);
+  box-shadow: 0 4px 16px var(--ui-shadow-soft);
+  display: flex;
+  flex-direction: column;
+  /* Clip the bg-1 title/actions strips to the panel's rounded corners. */
+  overflow: hidden;
+  /* transform-origin is set inline from the computed placement so the panel
+     grows from the side closest to the anchor. */
+  animation: popoverIn 110ms ease-out;
+}
+
+@keyframes popoverIn {
+  from {
+    opacity: 0;
+    transform: scale(0.96);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+.title {
+  padding: var(--ui-space-1) var(--ui-space-3);
+  border-bottom: 1px solid var(--ui-border-subtle);
+  background-color: var(--ui-background-1);
+  font-size: var(--ui-text-xsmall);
+  font-weight: 600;
+  color: var(--ui-foreground);
+  user-select: none;
+  white-space: nowrap;
+}
+
+.body {
+  padding: var(--ui-space-3);
+}
+
+.bodyFlush {
+  padding: 0;
+}
+
+.actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--ui-space-2);
+  padding: var(--ui-space-1) var(--ui-space-3);
+  border-top: 1px solid var(--ui-border-subtle);
+  background-color: var(--ui-background-1);
+}

package/src/components/Overlays/Popover/types.ts

@@ -0,0 +1,34 @@
+import type { ReactNode, RefObject } from 'react';
+
+export type PopoverPlacement =
+  | 'auto'
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'top-start'
+  | 'top-end';
+
+export type PopoverProps = {
+  /** Ref of the element the popover anchors to. Popover reads its rect on open. */
+  anchorRef: RefObject<HTMLElement | null>;
+  /** Visibility — controlled by the caller. */
+  isOpen: boolean;
+  /** Fires on outside click, Escape, or when the anchor unmounts. */
+  onClose: () => void;
+  /** Optional title bar — small muted label above the body. Also becomes the
+   *  accessible name when `ariaLabel` isn't provided. */
+  title?: string;
+  /** Optional actions bar — right-aligned flex row below the body. Typically
+   *  a Cancel + Save pair for inline-form popovers. */
+  actions?: ReactNode;
+  /** Accessible name. Optional when `title` is provided (title labels the dialog). */
+  ariaLabel?: string;
+  /** Preferred placement relative to the anchor. `auto` picks the side with more room. */
+  placement?: PopoverPlacement;
+  /** If true, the panel's width is pinned to the anchor's width. Disables the
+   *  default min-width. Used by select-style triggers so the menu aligns flush. */
+  matchAnchorWidth?: boolean;
+  /** Defaults to true. Set false for edge-to-edge body content like option lists. */
+  hasBodyPadding?: boolean;
+  /** Popover body contents — typically a small form or inline editor. */
+  children: ReactNode;
+};

package/src/components/Overlays/Tooltip/Tooltip.stories.tsx

@@ -0,0 +1,41 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Tooltip } from './index';
+import type { TooltipPlacement } from './types';
+import { Button } from '../../Forms/Button';
+
+const meta: Meta<typeof Tooltip> = {
+  title: 'Overlays/Tooltip',
+  component: Tooltip,
+  decorators: [
+    (Story) => (
+      <div style={{ padding: 80 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Tooltip>;
+
+export const Default: Story = {
+  render: () => (
+    <Tooltip label="Hello, tooltip">
+      <Button>Hover or focus me</Button>
+    </Tooltip>
+  ),
+};
+
+const PLACEMENTS: TooltipPlacement[] = ['top', 'bottom', 'left', 'right'];
+
+export const Placements: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 32, flexWrap: 'wrap' }}>
+      {PLACEMENTS.map((placement) => (
+        <Tooltip key={placement} label={`Placement: ${placement}`} placement={placement}>
+          <Button>{placement}</Button>
+        </Tooltip>
+      ))}
+    </div>
+  ),
+};

package/src/components/Overlays/Tooltip/index.tsx

@@ -0,0 +1,115 @@
+import {
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+} from 'react';
+import { createPortal } from 'react-dom';
+import type { TooltipPlacement, TooltipProps } from './types';
+import styles from './styles.module.css';
+
+const ENTER_DELAY_MS = 400;
+const GAP = 4;
+
+type Position = { top: number; left: number };
+
+const computePosition = (
+  host: DOMRect,
+  tip: DOMRect,
+  placement: TooltipPlacement,
+): Position => {
+  switch (placement) {
+    case 'top':
+      return {
+        top: host.top - tip.height - GAP,
+        left: host.left + (host.width - tip.width) / 2,
+      };
+    case 'bottom':
+      return {
+        top: host.bottom + GAP,
+        left: host.left + (host.width - tip.width) / 2,
+      };
+    case 'left':
+      return {
+        top: host.top + (host.height - tip.height) / 2,
+        left: host.left - tip.width - GAP,
+      };
+    case 'right':
+      return {
+        top: host.top + (host.height - tip.height) / 2,
+        left: host.right + GAP,
+      };
+  }
+};
+
+export const Tooltip = (props: TooltipProps) => {
+  const { label, placement = 'top', children } = props;
+
+  const hostRef = useRef<HTMLSpanElement>(null);
+  const tipRef = useRef<HTMLSpanElement>(null);
+  const enterTimer = useRef<number | null>(null);
+
+  const [isVisible, setIsVisible] = useState(false);
+  const [position, setPosition] = useState<Position | null>(null);
+
+  const open = () => {
+    if (enterTimer.current != null) return;
+    enterTimer.current = window.setTimeout(() => {
+      enterTimer.current = null;
+      setIsVisible(true);
+    }, ENTER_DELAY_MS);
+  };
+
+  const close = () => {
+    if (enterTimer.current != null) {
+      clearTimeout(enterTimer.current);
+      enterTimer.current = null;
+    }
+    setIsVisible(false);
+    setPosition(null);
+  };
+
+  useEffect(
+    () => () => {
+      if (enterTimer.current != null) clearTimeout(enterTimer.current);
+    },
+    [],
+  );
+
+  useLayoutEffect(() => {
+    if (!isVisible) return;
+    const host = hostRef.current;
+    const tip = tipRef.current;
+    if (!host || !tip) return;
+    setPosition(
+      computePosition(host.getBoundingClientRect(), tip.getBoundingClientRect(), placement),
+    );
+  }, [isVisible, placement, label]);
+
+  const tipStyle: CSSProperties = position
+    ? { top: position.top, left: position.left }
+    : { top: 0, left: 0, visibility: 'hidden' };
+
+  return (
+    <span
+      ref={hostRef}
+      className={styles.host}
+      onMouseEnter={open}
+      onMouseLeave={close}
+      onFocus={open}
+      onBlur={close}
+    >
+      {children}
+      {isVisible &&
+        createPortal(
+          <span ref={tipRef} role="tooltip" className={styles.tip} style={tipStyle}>
+            {label}
+          </span>,
+          document.body,
+        )}
+    </span>
+  );
+};
+
+export type { TooltipProps, TooltipPlacement };

package/src/components/Overlays/Tooltip/styles.module.css

@@ -0,0 +1,25 @@
+.host {
+  position: relative;
+  display: inline-flex;
+  /* Don't stretch to fill a flex/grid parent's cross axis — the JS that
+   * positions the tip measures this span and would center on the stretched
+   * width. Block parents ignore align-self, so this is harmless there. */
+  align-self: start;
+  width: fit-content;
+}
+
+.tip {
+  position: fixed;
+  /* Same z-index as every other portal layer (Modal, Popover, Menu). Stacking
+   * order between layers comes from DOM-append order, not z-index. */
+  z-index: 100;
+  pointer-events: none;
+  padding: var(--ui-space-1) var(--ui-space-2);
+  background-color: var(--ui-foreground);
+  color: var(--ui-background-0);
+  font-family: var(--ui-font);
+  font-size: var(--ui-text-small);
+  line-height: 1.2;
+  border-radius: var(--ui-radius);
+  white-space: nowrap;
+}

package/src/components/Overlays/Tooltip/types.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+
+export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
+
+export type TooltipProps = {
+  /** Tooltip text shown on hover/focus of the trigger. */
+  label: string;
+  /** Side of the trigger to render on. Defaults to `'top'`. */
+  placement?: TooltipPlacement;
+  /** The trigger element. Should be a single focusable element so that
+   *  `:focus-within` reveal works. The tooltip text is purely visual —
+   *  triggers should still carry their own accessible name (e.g. an
+   *  `aria-label` on an IconButton). */
+  children: ReactNode;
+};

package/src/components/Primitives/EmptyValue/EmptyValue.stories.tsx

@@ -0,0 +1,18 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { EmptyValue } from './index';
+
+const meta: Meta<typeof EmptyValue> = {
+  title: 'Primitives/EmptyValue',
+  component: EmptyValue,
+};
+
+export default meta;
+type Story = StoryObj<typeof EmptyValue>;
+
+export const Default: Story = {
+  render: () => (
+    <div style={{ padding: 24 }}>
+      Last login: <EmptyValue />
+    </div>
+  ),
+};

package/src/components/Primitives/EmptyValue/index.tsx

@@ -0,0 +1,3 @@
+import styles from './styles.module.css';
+
+export const EmptyValue = () => <span className={styles.dash}>—</span>;

package/src/components/Primitives/EmptyValue/styles.module.css

@@ -0,0 +1,3 @@
+.dash {
+  color: var(--ui-muted);
+}

package/src/components/Primitives/LinedStack/LinedStack.stories.tsx

@@ -0,0 +1,101 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { LinedStack } from './index';
+import { Text } from '../../Content/Text';
+
+const meta: Meta<typeof LinedStack> = {
+  title: 'Primitives/LinedStack',
+  component: LinedStack,
+};
+
+export default meta;
+type Story = StoryObj<typeof LinedStack>;
+
+const wrap = { padding: 24, display: 'flex', gap: 32 };
+
+export const Plain: Story = {
+  name: 'Plain — non-interactive',
+  render: () => (
+    <div style={wrap}>
+      <LinedStack>
+        <strong>Alice Park</strong>
+        <Text isMuted size="xsmall">
+          alice.park@example.com
+        </Text>
+      </LinedStack>
+    </div>
+  ),
+};
+
+export const AsRouterLink: Story = {
+  name: 'As router link — `to` prop',
+  render: () => (
+    <div style={wrap}>
+      <LinedStack to="/users/usr_1234">
+        <strong>Alice Park</strong>
+        <Text isMuted size="xsmall">
+          alice.park@example.com
+        </Text>
+      </LinedStack>
+    </div>
+  ),
+};
+
+export const AsAnchor: Story = {
+  name: 'As anchor — `href` prop (typically external)',
+  render: () => (
+    <div style={wrap}>
+      <LinedStack href="https://example.com/u/alice" isExternal>
+        <strong>Alice Park</strong>
+        <Text isMuted size="xsmall">
+          example.com/u/alice
+        </Text>
+      </LinedStack>
+    </div>
+  ),
+};
+
+export const AsButton: Story = {
+  name: 'As button — `onClick` prop',
+  render: () => (
+    <div style={wrap}>
+      <LinedStack onClick={() => alert('clicked')}>
+        <strong>Alice Park</strong>
+        <Text isMuted size="xsmall">
+          alice.park@example.com
+        </Text>
+      </LinedStack>
+    </div>
+  ),
+};
+
+export const Mixed: Story = {
+  name: 'Side-by-side: plain, router link, anchor, button',
+  render: () => (
+    <div style={wrap}>
+      <LinedStack>
+        <strong>Plain</strong>
+        <Text isMuted size="xsmall">
+          no interactivity
+        </Text>
+      </LinedStack>
+      <LinedStack to="/users/usr_1234">
+        <strong>Router Link</strong>
+        <Text isMuted size="xsmall">
+          renders &lt;Link to&gt;
+        </Text>
+      </LinedStack>
+      <LinedStack href="https://example.com" isExternal>
+        <strong>Anchor</strong>
+        <Text isMuted size="xsmall">
+          renders &lt;a href&gt;
+        </Text>
+      </LinedStack>
+      <LinedStack onClick={() => alert('clicked')}>
+        <strong>Button</strong>
+        <Text isMuted size="xsmall">
+          renders &lt;button&gt;
+        </Text>
+      </LinedStack>
+    </div>
+  ),
+};

package/src/components/Primitives/LinedStack/index.tsx

@@ -0,0 +1,41 @@
+import { Link as RouterLink } from 'react-router';
+import { cx } from '../../../utils';
+import type { LinedStackProps } from './types';
+import styles from './styles.module.css';
+
+export const LinedStack = (props: LinedStackProps) => {
+  const { children, to, href, isExternal, onClick } = props;
+
+  if (to != null) {
+    return (
+      <RouterLink to={to} className={cx(styles.stack, styles.interactive)}>
+        {children}
+      </RouterLink>
+    );
+  }
+
+  if (href != null) {
+    return (
+      <a
+        href={href}
+        target={isExternal ? '_blank' : undefined}
+        rel={isExternal ? 'noopener noreferrer' : undefined}
+        className={cx(styles.stack, styles.interactive)}
+      >
+        {children}
+      </a>
+    );
+  }
+
+  if (onClick != null) {
+    return (
+      <button type="button" onClick={onClick} className={cx(styles.stack, styles.interactive)}>
+        {children}
+      </button>
+    );
+  }
+
+  return <div className={styles.stack}>{children}</div>;
+};
+
+export type { LinedStackProps };

package/src/components/Primitives/LinedStack/styles.module.css

@@ -0,0 +1,27 @@
+.stack {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+}
+
+.interactive {
+  cursor: pointer;
+  text-decoration: none;
+  color: inherit;
+  background: none;
+  border: none;
+  padding: 0;
+  font: inherit;
+  text-align: left;
+  border-radius: var(--ui-radius);
+  transition: background-color 0.12s;
+}
+
+.interactive:hover {
+  background-color: var(--ui-background-1);
+}
+
+.interactive:focus-visible {
+  outline: 2px solid var(--ui-accent);
+  outline-offset: 2px;
+}