@zyncat/ui 0.11.0 → 0.12.0

package/src/components/internal/glass/glass.css

@@ -1,100 +1,104 @@
-/* Glass surface - translucent tint + backdrop blur + a sheen layer; consumer sets --glass-tint and --glass-fg. */
+@layer zyncat.tokens, zyncat.components;
 
-.glass {
-  --glass-fg: var(--text-body);
-  --glass-tint: var(--glass-tint-neutral);
+@layer zyncat.components {
+  /* Glass surface - translucent tint + backdrop blur + a sheen layer; consumer sets --glass-tint and --glass-fg. */
 
-  position: relative;
-  isolation: isolate; /* local stacking for the sheen */
-  color: var(--glass-fg);
+  .glass {
+    --glass-fg: var(--text-body);
+    --glass-tint: var(--glass-tint-neutral);
 
-  background: var(--glass-tint);
-  -webkit-backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturate));
-  backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturate));
-  box-shadow:
-    var(--glass-highlight),
-    inset 0 0 0 var(--border-hairline) color-mix(in oklab, var(--glass-fg) 22%, transparent),
-    var(--glass-shadow);
+    position: relative;
+    isolation: isolate; /* local stacking for the sheen */
+    color: var(--glass-fg);
 
-  transition:
-    transform var(--duration-base) var(--ease-standard),
-    box-shadow var(--duration-base) var(--ease-standard),
-    background-color var(--duration-base) var(--ease-standard);
-}
-
-/* Sheen on its own layer so hover animates opacity/transform - gradients can't transition directly. */
-.glass::before {
-  content: '';
-  position: absolute;
-  inset: 0;
-  z-index: 0;
-  border-radius: inherit;
-  background: var(--glass-sheen);
-  opacity: var(--glass-sheen-rest);
-  pointer-events: none;
-  transition:
-    opacity var(--duration-base) var(--ease-standard),
-    transform var(--duration-slow) var(--ease-entrance);
-}
-.glass > * {
-  position: relative;
-  z-index: 1;
-} /* content rides above the sheen */
-
-.glass--strong {
-  --glass-blur: var(--glass-blur-strong);
-}
+    background: var(--glass-tint);
+    -webkit-backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturate));
+    backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturate));
+    box-shadow:
+      var(--glass-highlight),
+      inset 0 0 0 var(--border-hairline) color-mix(in oklab, var(--glass-fg) 22%, transparent),
+      var(--glass-shadow);
 
-.glass--interactive:hover {
-  transform: translateY(calc(var(--space-px) * -1));
-  box-shadow:
-    var(--glass-highlight),
-    inset 0 0 0 var(--border-hairline) color-mix(in oklab, var(--glass-fg) 26%, transparent),
-    var(--glass-shadow-hover);
-}
-.glass--interactive:hover::before {
-  opacity: var(--glass-sheen-hover);
-  transform: translateY(-8%);
-}
-
-/* Glint - one-shot light sweep; add .glass-glint to fire, remove after it ends (sits above content, z-index 2). */
-.glass-glint::after {
-  content: '';
-  position: absolute;
-  inset: 0;
-  z-index: 2;
-  border-radius: inherit;
-  pointer-events: none;
-  opacity: 0; /* resting state is invisible - no mid-sweep flash */
-  background: linear-gradient(118deg, transparent 36%, rgb(255 255 255 / 0.7) 50%, transparent 64%);
-  animation: glass-glint var(--duration-slow) var(--ease-standard) 1 forwards;
-}
-@keyframes glass-glint {
-  0% {
-    opacity: 0;
-    transform: translateX(-28%);
-  }
-  40% {
-    opacity: 1;
+    transition:
+      transform var(--duration-base) var(--ease-standard),
+      box-shadow var(--duration-base) var(--ease-standard),
+      background-color var(--duration-base) var(--ease-standard);
   }
-  100% {
-    opacity: 0;
-    transform: translateX(28%);
-  }
-}
 
-@media (prefers-reduced-motion: reduce) {
-  .glass,
+  /* Sheen on its own layer so hover animates opacity/transform - gradients can't transition directly. */
   .glass::before {
-    transition: none;
+    content: '';
+    position: absolute;
+    inset: 0;
+    z-index: 0;
+    border-radius: inherit;
+    background: var(--glass-sheen);
+    opacity: var(--glass-sheen-rest);
+    pointer-events: none;
+    transition:
+      opacity var(--duration-base) var(--ease-standard),
+      transform var(--duration-slow) var(--ease-entrance);
   }
+  .glass > * {
+    position: relative;
+    z-index: 1;
+  } /* content rides above the sheen */
+
+  .glass--strong {
+    --glass-blur: var(--glass-blur-strong);
+  }
+
   .glass--interactive:hover {
-    transform: none;
+    transform: translateY(calc(var(--space-px) * -1));
+    box-shadow:
+      var(--glass-highlight),
+      inset 0 0 0 var(--border-hairline) color-mix(in oklab, var(--glass-fg) 26%, transparent),
+      var(--glass-shadow-hover);
   }
   .glass--interactive:hover::before {
-    transform: none;
+    opacity: var(--glass-sheen-hover);
+    transform: translateY(-8%);
   }
+
+  /* Glint - one-shot light sweep; add .glass-glint to fire, remove after it ends (sits above content, z-index 2). */
   .glass-glint::after {
-    animation: none;
+    content: '';
+    position: absolute;
+    inset: 0;
+    z-index: 2;
+    border-radius: inherit;
+    pointer-events: none;
+    opacity: 0; /* resting state is invisible - no mid-sweep flash */
+    background: linear-gradient(118deg, transparent 36%, rgb(255 255 255 / 0.7) 50%, transparent 64%);
+    animation: glass-glint var(--duration-slow) var(--ease-standard) 1 forwards;
+  }
+  @keyframes glass-glint {
+    0% {
+      opacity: 0;
+      transform: translateX(-28%);
+    }
+    40% {
+      opacity: 1;
+    }
+    100% {
+      opacity: 0;
+      transform: translateX(28%);
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .glass,
+    .glass::before {
+      transition: none;
+    }
+    .glass--interactive:hover {
+      transform: none;
+    }
+    .glass--interactive:hover::before {
+      transform: none;
+    }
+    .glass-glint::after {
+      animation: none;
+    }
   }
 }

package/src/components/internal/hooks/use-media-query.ts

@@ -0,0 +1,20 @@
+'use client';
+
+import { useCallback, useSyncExternalStore } from 'react';
+
+export function useMediaQuery(query: string): boolean {
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      const list = matchMedia(query);
+      list.addEventListener('change', onChange);
+      return () => list.removeEventListener('change', onChange);
+    },
+    [query],
+  );
+
+  return useSyncExternalStore(
+    subscribe,
+    () => matchMedia(query).matches,
+    () => false,
+  );
+}

package/src/components/internal/hooks/use-typeahead.ts

@@ -0,0 +1,28 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+const TYPEAHEAD_RESET_MS = 600;
+
+export interface Typeahead {
+  push: (char: string) => string;
+  buffered: () => boolean;
+}
+
+export function useTypeahead(): Typeahead {
+  const state = useRef({ buffer: '', timer: 0 as ReturnType<typeof setTimeout> | 0 });
+  const api = useRef<Typeahead>(null);
+
+  api.current ||= {
+    push: (char) => {
+      const s = state.current;
+      clearTimeout(s.timer);
+      s.timer = setTimeout(() => (s.buffer = ''), TYPEAHEAD_RESET_MS);
+      return (s.buffer += char.toLowerCase());
+    },
+    buffered: () => state.current.buffer.length > 0,
+  };
+
+  useEffect(() => () => clearTimeout(state.current.timer), []);
+  return api.current;
+}

package/src/components/internal/icon/Icon.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import './icon.css';
+
 import {
   ArrowUp,
   Calendar,
@@ -20,6 +21,7 @@ import {
   X,
 } from '@phosphor-icons/react';
 import type { IconWeight } from '@phosphor-icons/react';
+
 import { cx } from '../utils/cx';
 
 type Glyph = typeof X;

package/src/components/internal/icon/IconSlot.tsx

@@ -1,7 +1,9 @@
 'use client';
 
 import './icon.css';
+
 import type { ReactNode } from 'react';
+
 import type { IconSize } from './Icon';
 
 export function IconSlot({ size = 'md', children }: { size?: IconSize; children?: ReactNode }) {

package/src/components/internal/icon/icon.css

@@ -1,33 +1,37 @@
-/* Icon - base layout (inline/flex seating); size and color come from props/tokens. */
+@layer zyncat.tokens, zyncat.components;
 
-.icon {
-  flex: none;
-  vertical-align: middle;
-}
+@layer zyncat.components {
+  /* Icon - base layout (inline/flex seating); size and color come from props/tokens. */
 
-/* icon-slot - locks a consumer icon node to the token size and currentColor. */
-.icon-slot {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  flex: none;
-  color: currentColor;
-}
-.icon-slot--sm {
-  width: var(--icon-sm);
-  height: var(--icon-sm);
-}
-.icon-slot--md {
-  width: var(--icon-md);
-  height: var(--icon-md);
-}
-.icon-slot--lg {
-  width: var(--icon-lg);
-  height: var(--icon-lg);
-}
-.icon-slot > svg,
-.icon-slot > img {
-  width: 100%;
-  height: 100%;
-  display: block;
+  .icon {
+    flex: none;
+    vertical-align: middle;
+  }
+
+  /* icon-slot - locks a consumer icon node to the token size and currentColor. */
+  .icon-slot {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex: none;
+    color: currentColor;
+  }
+  .icon-slot--sm {
+    width: var(--icon-sm);
+    height: var(--icon-sm);
+  }
+  .icon-slot--md {
+    width: var(--icon-md);
+    height: var(--icon-md);
+  }
+  .icon-slot--lg {
+    width: var(--icon-lg);
+    height: var(--icon-lg);
+  }
+  .icon-slot > svg,
+  .icon-slot > img {
+    width: 100%;
+    height: 100%;
+    display: block;
+  }
 }

package/src/components/internal/menu/menu-row.tsx

@@ -0,0 +1,34 @@
+'use client';
+
+import './menu-surface.css';
+
+import type { HTMLAttributes, ReactNode, Ref } from 'react';
+
+import type { DataAttributes } from '../../../dom-props';
+import { IconSlot } from '../icon/IconSlot';
+import { cx } from '../utils/cx';
+
+export interface MenuRowProps extends HTMLAttributes<HTMLDivElement>, DataAttributes {
+  ref?: Ref<HTMLDivElement>;
+  icon?: ReactNode;
+  label: ReactNode;
+  description?: ReactNode;
+  trailing?: ReactNode;
+}
+
+export function MenuRow({ ref, icon, label, description, trailing, className, ...rest }: MenuRowProps) {
+  return (
+    <div ref={ref} className={cx('menu-row', className)} {...rest}>
+      {icon && (
+        <span className="menu-row__icon">
+          <IconSlot size="sm">{icon}</IconSlot>
+        </span>
+      )}
+      <span className="menu-row__text">
+        <span className="menu-row__label">{label}</span>
+        {description && <span className="menu-row__desc">{description}</span>}
+      </span>
+      {trailing}
+    </div>
+  );
+}

package/src/components/internal/menu/menu-surface.css

@@ -0,0 +1,127 @@
+@layer zyncat.tokens, zyncat.components;
+
+@layer zyncat.components {
+  /* The floating menu surface shared by Select's listbox and Dropdown's menu: panel chrome,
+   scroll box, row skeleton and the travelling hover pill. Everything that differs between the
+   two is a custom property set by the component, so neither sheet has to restate a rule.
+   Enter/exit are Motion-owned inline styles; transform-origin belongs to the component. */
+
+  .menu-surface {
+    position: fixed;
+    margin: 0;
+    inset: auto; /* JS sets top/left - anchor() needs the top layer, which we don't use */
+    z-index: var(
+      --layer-overlay
+    ); /* base of the overlay band (tokens/layers.css) - a nested menu is pushed one step up */
+    width: max-content;
+    max-width: var(--menu-max-width, min(22rem, 92vw));
+    padding: var(--space-1);
+    background: var(--bg-surface-raised);
+    border: var(--border-hairline) solid var(--border-default);
+    border-radius: var(--radius-lg);
+    box-shadow: var(--shadow-lg);
+    outline: none;
+    font-family: var(--font-sans);
+  }
+
+  /* data-side/data-align are written by useAnchorPosition after any flip - grow from the anchored edge. */
+  .menu-surface[data-align='start'] {
+    --menu-origin: var(--space-4);
+  }
+  .menu-surface[data-align='center'] {
+    --menu-origin: 50%;
+  }
+  .menu-surface[data-align='end'] {
+    --menu-origin: calc(100% - var(--space-4));
+  }
+  .menu-surface[data-side='bottom'] {
+    transform-origin: var(--menu-origin) top;
+  }
+  .menu-surface[data-side='top'] {
+    transform-origin: var(--menu-origin) bottom;
+  }
+  .menu-surface[data-side='right'] {
+    transform-origin: left var(--menu-origin);
+  }
+  .menu-surface[data-side='left'] {
+    transform-origin: right var(--menu-origin);
+  }
+
+  .menu-scroller {
+    max-height: var(--menu-max-height, 16.5rem);
+    overflow-y: auto;
+    overscroll-behavior: contain;
+    scrollbar-width: none;
+  }
+  .menu-scroller::-webkit-scrollbar {
+    width: 0;
+    height: 0;
+    display: none;
+  }
+
+  /* position: relative keeps the row above the pill, which is a single absolute child. */
+  .menu-row {
+    position: relative;
+    display: flex;
+    align-items: center;
+    gap: var(--space-2);
+    padding: var(--menu-row-padding, var(--space-1)) var(--menu-row-inline, var(--space-3));
+    margin-block-end: var(--menu-row-gap, var(--space-1));
+    border-radius: var(--radius-sm);
+    cursor: pointer;
+    user-select: none;
+    outline: none;
+    color: var(--text-body);
+  }
+
+  .menu-row__icon {
+    display: inline-flex;
+    flex: 0 0 auto;
+    font-size: var(--icon-sm);
+    color: var(--text-muted);
+  }
+  .menu-row__text {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-1);
+    min-width: 0;
+    flex: 1 1 auto;
+  }
+  .menu-row__label {
+    font-size: var(--size-body);
+    line-height: var(--leading-body);
+    font-weight: var(--weight-medium);
+  }
+  .menu-row__desc {
+    font: var(--type-caption);
+    color: var(--text-subtle);
+  }
+  .menu-row__label,
+  .menu-row__desc {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .menu-group-label {
+    padding: var(--space-2) var(--menu-row-inline, var(--space-3)) var(--space-1);
+    font: var(--type-micro);
+    text-transform: uppercase;
+    letter-spacing: var(--tracking-caps);
+    color: var(--text-subtle);
+  }
+
+  /* One persistent fill (../../../motion/glide) that travels to the active row and animates its
+   real size, so it is never clipped and never scales. GlidePill writes x/y/width/height inline -
+   nothing here may transition those. */
+  .menu-glide {
+    position: absolute;
+    top: 0;
+    left: 0;
+    z-index: 0;
+    border-radius: var(--radius-sm);
+    background: var(--menu-glide-fill, var(--neutral-wash));
+    pointer-events: none;
+    transition: background-color var(--duration-fast) var(--ease-standard);
+  }
+}

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

@@ -1,12 +1,19 @@
 'use client';
 
-import { useEffect, type RefObject } from 'react';
-import { type OverlayEntry, ovIsTop, ovInOverlayAbove } from './layer';
+import { useEffect, useRef, type RefObject } from 'react';
+
+import { ovInOverlayAbove, ovIsTop, type OverlayEntry } from './layer';
 
 export function useReturnFocus(nodeRef: RefObject<HTMLElement>) {
-  useEffect(() => {
-    const prev = document.activeElement as HTMLElement | null;
-    return () => {
+  const opener = useRef<HTMLElement | null | undefined>(undefined);
+
+  if (opener.current === undefined && typeof document !== 'undefined') {
+    opener.current = document.activeElement as HTMLElement | null;
+  }
+
+  useEffect(
+    () => () => {
+      const prev = opener.current;
       const a = document.activeElement;
       const orphaned = !a || a === document.body || (nodeRef.current && nodeRef.current.contains(a));
       if (orphaned && prev && prev.isConnected && typeof prev.focus === 'function') {
@@ -14,15 +21,24 @@ export function useReturnFocus(nodeRef: RefObject<HTMLElement>) {
           if (prev.isConnected) prev.focus({ preventScroll: true });
         });
       }
-    };
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+    },
+    [], // eslint-disable-line react-hooks/exhaustive-deps
+  );
 }
 
 const OV_FOCUSABLE =
   'a[href], button:not([disabled]), input:not([disabled]):not([type="hidden"]), ' +
   'select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
-export function useFocusTrap({ panelRef, entry }: { panelRef: RefObject<HTMLElement>; entry: OverlayEntry }) {
+export function useFocusTrap({
+  panelRef,
+  entry,
+  scoped,
+}: {
+  panelRef: RefObject<HTMLElement>;
+  entry: OverlayEntry;
+  scoped: boolean;
+}) {
   useEffect(() => {
     const panel = panelRef.current;
     if (!panel) return undefined;
@@ -59,10 +75,10 @@ export function useFocusTrap({ panelRef, entry }: { panelRef: RefObject<HTMLElem
     };
 
     panel.addEventListener('keydown', onKeyDown);
-    document.addEventListener('focusin', onFocusIn);
+    if (!scoped) document.addEventListener('focusin', onFocusIn);
     return () => {
       panel.removeEventListener('keydown', onKeyDown);
-      document.removeEventListener('focusin', onFocusIn);
+      if (!scoped) document.removeEventListener('focusin', onFocusIn);
     };
   }, []); // eslint-disable-line react-hooks/exhaustive-deps
 }

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

@@ -1,17 +1,25 @@
 'use client';
 
+import './trigger.css';
+
 import {
   cloneElement,
   useEffect,
   useLayoutEffect,
   useRef,
+  useSyncExternalStore,
   type ReactElement,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type MouseEvent as ReactMouseEvent,
   type ReactNode,
+  type PointerEvent as ReactPointerEvent,
   type Ref,
   type RefObject,
 } from 'react';
 import { createPortal } from 'react-dom';
 
+import { activationProps, type ActivateOn } from '../utils/activation';
+
 interface OverlayEntry {
   contains: (t: EventTarget | null) => boolean;
   isDismissible: () => boolean;
@@ -105,22 +113,45 @@ function ovCloneTrigger(
   {
     open,
     onPress,
+    onKeyDown,
     panelId,
     haspopup,
     triggerRef,
-  }: { open: boolean; onPress: () => void; panelId: string; haspopup: string; triggerRef: RefObject<HTMLElement> },
+    activateOn,
+  }: {
+    open: boolean;
+    onPress: () => void;
+    onKeyDown?: (e: ReactKeyboardEvent<HTMLElement>) => void;
+    panelId: string;
+    haspopup: string;
+    triggerRef: RefObject<HTMLElement>;
+    activateOn?: ActivateOn;
+  },
 ): ReactElement | null {
   if (!trigger) return null;
-  const own = trigger.props as { onClick?: (...args: unknown[]) => void };
+  const own = trigger.props as {
+    onClick?: (e: ReactMouseEvent<HTMLElement>) => void;
+    onPointerDown?: (e: ReactPointerEvent<HTMLElement>) => void;
+    onKeyDown?: (e: ReactKeyboardEvent<HTMLElement>) => void;
+  };
   const ownRef = (trigger as ReactElement & { ref?: Ref<HTMLElement> }).ref;
+  const keys = onKeyDown && {
+    onKeyDown: (e: ReactKeyboardEvent<HTMLElement>) => {
+      own.onKeyDown?.(e);
+      onKeyDown(e);
+    },
+  };
   return cloneElement(trigger, {
     'aria-haspopup': haspopup,
     'aria-expanded': open,
     'aria-controls': open ? panelId : undefined,
-    onClick: (...args: unknown[]) => {
-      own.onClick?.(...args);
-      onPress();
-    },
+    'data-activate': activateOn === 'pointerdown' ? 'pointerdown' : undefined,
+    ...activationProps<HTMLElement>(() => onPress(), {
+      on: activateOn,
+      onPointerDown: own.onPointerDown,
+      onClick: own.onClick,
+    }),
+    ...keys,
     ref: (node: HTMLElement | null) => {
       triggerRef.current = node;
       if (typeof ownRef === 'function') ownRef(node);
@@ -129,10 +160,20 @@ function ovCloneTrigger(
   } as Partial<typeof trigger.props>);
 }
 
+const subscribeToNothing = () => () => {};
+
+function useHydrated() {
+  return useSyncExternalStore(
+    subscribeToNothing,
+    () => true,
+    () => false,
+  );
+}
+
 function OverlayPortal({ container, children }: { container?: HTMLElement | null; children: ReactNode }) {
-  const host = container ?? (typeof document === 'undefined' ? null : document.body);
-  if (!host) return null;
-  return createPortal(<div data-overlay-root="">{children}</div>, host);
+  const hydrated = useHydrated();
+  if (!hydrated) return null;
+  return createPortal(<div data-overlay-root="">{children}</div>, container ?? document.body);
 }
 
 export { ovIsTop, ovInOverlayAbove, useOverlayEntry, useOutsidePress, ovCloneTrigger, OverlayPortal };