@zyncat/ui 0.11.0 → 0.12.0

package/src/components/internal/overlay/modal.tsx

@@ -1,15 +1,20 @@
 'use client';
 
 import './overlay.css';
+
 import { useEffect, useRef, type ReactNode, type RefObject } from 'react';
+
 import { animate, type Layer, type Playback } from '../../../engine';
-import { useMotion, run, type MotionSpec, type MotionSpecs } from '../../../motion/use-motion';
-import { UIMotion } from '../../../tokens/motion-tokens';
-import { useOverlayEntry } from './layer';
-import { useReturnFocus, useFocusTrap } from './focus';
+import type { MotionTimingDefaults, MotionTimings } from '../../../motion/motion-timing';
+import { run, useMotion, type MotionSpec, type MotionSpecs } from '../../../motion/use-motion';
 import { cx } from '../utils/cx';
+import { useFocusTrap, useReturnFocus } from './focus';
+import { useOverlayEntry } from './layer';
 
-const SM = UIMotion;
+export const OV_TAKEOVER_TIMING: MotionTimingDefaults = {
+  open: { duration: 'slow', ease: 'entrance' },
+  close: { duration: 'base', ease: 'standard' },
+};
 
 interface OvScopeLock {
   depth: number;
@@ -58,11 +63,6 @@ function useScopeLock(container?: HTMLElement | null) {
   }, []); // eslint-disable-line react-hooks/exhaustive-deps
 }
 
-const ovScrimTiming = {
-  open: { duration: SM.dur.slow, ease: SM.ease.entrance },
-  close: { duration: SM.dur.base, ease: SM.ease.standard },
-};
-
 function OverlayScrim({
   dismissible,
   onPress,
@@ -98,6 +98,7 @@ export function ModalShell({
   panelRef: externalPanelRef = null,
   panelProps = {},
   layerProps = {},
+  timings,
   animate: animateSpec,
   exit,
   children,
@@ -111,6 +112,7 @@ export function ModalShell({
   panelRef?: RefObject<HTMLElement> | null;
   panelProps?: Record<string, any>;
   layerProps?: Record<string, any>;
+  timings: MotionTimings;
   children: ReactNode;
 } & MotionSpecs) {
   const layerRef = useRef<HTMLDivElement>(null);
@@ -120,7 +122,7 @@ export function ModalShell({
   const entry = useOverlayEntry({ nodeRef: layerRef, dismissible, requestClose });
 
   const withScrim = (dir: 'open' | 'close', panelSpec: MotionSpec | undefined) => (): Playback[] => {
-    const fade: Layer = { opacity: dir === 'open' ? [0, 1] : [0], timing: ovScrimTiming[dir] };
+    const fade: Layer = { opacity: dir === 'open' ? [0, 1] : [0], timing: timings[dir] };
     const plays = scrimRef.current ? [animate(scrimRef.current, fade)] : [];
     return panelRef.current ? plays.concat(run(panelSpec, panelRef.current)) : plays;
   };
@@ -128,7 +130,7 @@ export function ModalShell({
   useMotion(layerRef, { animate: withScrim('open', animateSpec), exit: withScrim('close', exit) });
   useScopeLock(container);
   useReturnFocus(layerRef);
-  useFocusTrap({ panelRef, entry });
+  useFocusTrap({ panelRef, entry, scoped: !!container });
   return (
     <div
       {...layerProps}

package/src/components/internal/overlay/overlay.css

@@ -1,26 +1,30 @@
-/* overlay.css - the modal shell geometry shared by dialog and sheet: a fixed
+@layer zyncat.tokens, zyncat.components;
+
+@layer zyncat.components {
+  /* overlay.css - the modal shell geometry shared by dialog and sheet: a fixed
    full-viewport layer, the scrim filling it, and the grid cell the panel
    mounts in (min 0 + max 100% give a scroll constraint chain). Per-component
    placement lives with each consumer (dialog.css, sheet.css); the popover
    paints itself entirely from popover.css. */
-.overlay-layer {
-  position: fixed;
-  inset: 0;
-  display: grid;
-}
-.overlay-layer--scoped {
-  position: absolute;
-}
-.overlay-scrim {
-  position: absolute;
-  inset: 0;
-  background: var(--bg-overlay);
-}
+  .overlay-layer {
+    position: fixed;
+    inset: 0;
+    display: grid;
+  }
+  .overlay-layer--scoped {
+    position: absolute;
+  }
+  .overlay-scrim {
+    position: absolute;
+    inset: 0;
+    background: var(--bg-overlay);
+  }
 
-.overlay-panel {
-  position: relative;
-  display: grid;
-  outline: none;
-  min-width: 0;
-  min-height: 0;
+  .overlay-panel {
+    position: relative;
+    display: grid;
+    outline: none;
+    min-width: 0;
+    min-height: 0;
+  }
 }

package/src/components/internal/overlay/position.ts

@@ -1,8 +1,11 @@
 'use client';
 
 import { useLayoutEffect, type RefObject } from 'react';
+
 import { tokenPx } from '../utils/token-px';
 
+const GLIDE = 'left var(--duration-fast) var(--ease-standard), top var(--duration-fast) var(--ease-standard)';
+
 export interface VirtualAnchor {
   getBoundingClientRect(): DOMRect;
 }
@@ -18,7 +21,7 @@ interface UseAnchorPositionProps {
 
 export function useAnchorPosition({ side, align, arrow, anchor, triggerRef, panelRef }: UseAnchorPositionProps) {
   useLayoutEffect(() => {
-    const place = () => {
+    const place = (moved: boolean) => {
       const t = anchor ?? triggerRef.current;
       const p = panelRef.current;
       if (!t || !p) return;
@@ -70,8 +73,13 @@ export function useAnchorPosition({ side, align, arrow, anchor, triggerRef, pane
         x = Math.max(Math.min(x, vw - pw - edge), edge);
       }
 
-      p.style.left = Math.round(x) + 'px';
-      p.style.top = Math.round(y) + 'px';
+      const left = Math.round(x) + 'px';
+      const top = Math.round(y) + 'px';
+      if (p.style.left !== left || p.style.top !== top) {
+        p.style.transition = moved && p.style.left ? GLIDE : '';
+        p.style.left = left;
+        p.style.top = top;
+      }
 
       p.setAttribute('data-side', s);
       p.setAttribute('data-align', align);
@@ -91,17 +99,19 @@ export function useAnchorPosition({ side, align, arrow, anchor, triggerRef, pane
       }
     };
 
-    place();
+    place(true);
+
+    const track = () => place(false);
 
-    window.addEventListener('scroll', place, true);
-    window.addEventListener('resize', place);
+    window.addEventListener('scroll', track, true);
+    window.addEventListener('resize', track);
 
-    const ro = new ResizeObserver(place);
+    const ro = new ResizeObserver(track);
     ro.observe(panelRef.current!);
 
     return () => {
-      window.removeEventListener('scroll', place, true);
-      window.removeEventListener('resize', place);
+      window.removeEventListener('scroll', track, true);
+      window.removeEventListener('resize', track);
       ro.disconnect();
     };
   }, [side, align, arrow, anchor]); // eslint-disable-line react-hooks/exhaustive-deps

package/src/components/internal/overlay/trigger.css

@@ -0,0 +1,13 @@
+@layer zyncat.tokens, zyncat.components;
+
+@layer zyncat.components {
+  [data-activate='pointerdown'][aria-haspopup]:active:not(:disabled):not(.is-loading) {
+    transform: none;
+  }
+
+  [data-activate='pointerdown'][aria-haspopup][aria-expanded='true']:not(:disabled):not(.is-loading) {
+    transform: none;
+    border-color: var(--accent);
+    box-shadow: var(--ring-accent);
+  }
+}

package/src/components/internal/support/types.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react';
+
+export interface SupportAction {
+  /** Stable identity. Handed back to `onSelect` and used as the React key. */
+  id: string;
+  /** The visible name - "Live chat", "Book a call". */
+  label: string;
+  /** Leading glyph. Any node; the widget sizes the box it sits in. */
+  icon?: ReactNode;
+  /** Trailing metadata - a wait time, a slot, a ticket number. Set in mono. */
+  meta?: string;
+  /** Second line under the label. The rail shows it; the fan puts it in the caption. */
+  description?: string;
+  /** Fires when this action commits, before the widget's own `onSelect`. */
+  onSelect?: () => void;
+}

package/src/components/internal/utils/activation.ts

@@ -0,0 +1,78 @@
+'use client';
+
+import type { MouseEvent as ReactMouseEvent, PointerEvent as ReactPointerEvent } from 'react';
+
+/** When a library-owned trigger fires: on `pointerdown` (snappier) or on `click`. */
+export type ActivateOn = 'pointerdown' | 'click';
+
+type AnyPointerEvent = ReactPointerEvent<Element> | PointerEvent;
+type AnyMouseEvent = ReactMouseEvent<Element> | MouseEvent;
+
+const drivesActivation = (pointerType: string | undefined) => pointerType === 'mouse' || pointerType === 'pen';
+
+let activatedOnPointerDown = false;
+
+function isInert(target: EventTarget | null) {
+  const el = target as (Element & { disabled?: boolean }) | null;
+  return Boolean(el?.disabled) || el?.getAttribute?.('aria-disabled') === 'true';
+}
+
+function takeFocus(target: EventTarget | null) {
+  const el = target as (HTMLElement & { tabIndex?: number }) | null;
+  if (!el || typeof el.focus !== 'function' || (el.tabIndex ?? -1) < 0) return;
+  if (el !== document.activeElement) el.focus({ preventScroll: true });
+}
+
+export function pointerDownActivates(e: AnyPointerEvent, holdFocus = false) {
+  activatedOnPointerDown =
+    !e.defaultPrevented &&
+    e.button === 0 &&
+    !e.ctrlKey &&
+    !e.metaKey &&
+    !e.shiftKey &&
+    !e.altKey &&
+    drivesActivation(e.pointerType) &&
+    !isInert(e.currentTarget);
+  if (!activatedOnPointerDown) return false;
+  if (holdFocus) e.preventDefault();
+  else takeFocus(e.currentTarget);
+  return true;
+}
+
+export function declinePointerDown() {
+  activatedOnPointerDown = false;
+}
+
+export function clickActivates(e: AnyMouseEvent) {
+  const native = ('nativeEvent' in e ? e.nativeEvent : e) as PointerEvent;
+  if (isInert(e.currentTarget)) return false;
+  return !drivesActivation(native.pointerType) || !activatedOnPointerDown;
+}
+
+export interface ActivationOptions<E extends Element> {
+  /** The component supplies its own default; `activateOn` overrides it. @default 'click' */
+  on?: ActivateOn;
+  /** For rows inside a panel that places focus itself - the press leaves focus untouched. @default false */
+  holdFocus?: boolean;
+  /** Runs before the built-in activation, and can cancel it with `preventDefault()`. */
+  onPointerDown?: (e: ReactPointerEvent<E>) => void;
+  /** Runs before the built-in activation on click and on keyboard activation. */
+  onClick?: (e: ReactMouseEvent<E>) => void;
+}
+
+export function activationProps<E extends Element>(
+  activate: (e: ReactPointerEvent<E> | ReactMouseEvent<E>) => void,
+  { on = 'click', holdFocus, onPointerDown, onClick }: ActivationOptions<E> = {},
+) {
+  return {
+    onPointerDown: (e: ReactPointerEvent<E>) => {
+      onPointerDown?.(e);
+      if (on !== 'pointerdown') return declinePointerDown();
+      if (pointerDownActivates(e, holdFocus)) activate(e);
+    },
+    onClick: (e: ReactMouseEvent<E>) => {
+      onClick?.(e);
+      if (clickActivates(e)) activate(e);
+    },
+  };
+}

package/src/components/primitives/avatar/Avatar.tsx

@@ -1,7 +1,9 @@
 'use client';
 
 import './avatar.css';
+
 import { useState, type CSSProperties, type HTMLAttributes, type ReactNode } from 'react';
+
 import type { DataAttributes } from '../../../dom-props';
 import { cx } from '../../internal/utils/cx';
 

package/src/components/primitives/avatar/Avatar.usage.md

@@ -0,0 +1,12 @@
+# Avatar - @zyncat/ui/avatar
+
+Group: data-display
+Docs: https://ui.zyncat.app/avatar
+
+Identity mark: image, initials, or silhouette.
+
+name, src, size xs|sm|md|lg|xl, status online|away|busy|offline, shape, paletteIndex, icon.
+
+```tsx
+<Avatar name="Ana Ng" src="..." status="online" />
+```

package/src/components/primitives/avatar/AvatarGroup.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import './avatar.css';
+
 import {
   Children,
   cloneElement,
@@ -10,9 +11,10 @@ import {
   type ReactElement,
   type ReactNode,
 } from 'react';
-import type { AvatarSize } from './Avatar';
+
 import type { DataAttributes } from '../../../dom-props';
 import { cx } from '../../internal/utils/cx';
+import type { AvatarSize } from './Avatar';
 
 interface AvatarGroupOwnProps {
   /** The `Avatar` elements to stack; each is cloned to force `size`, then sliced to `max`. */

package/src/components/primitives/avatar/AvatarGroup.usage.md

@@ -0,0 +1,15 @@
+# AvatarGroup - @zyncat/ui/avatar-group
+
+Group: data-display
+Docs: https://ui.zyncat.app/avatar
+
+Overlapping avatars with +N overflow.
+
+max, size; children are <Avatar>s.
+
+```tsx
+<AvatarGroup max={4} size="sm">
+  <Avatar name="Ana Ng" />
+  ...
+</AvatarGroup>
+```