@zyncat/ui 0.8.0

package/src/components/composites/toast/toast-store.ts

@@ -0,0 +1,295 @@
+export type ToastTone = 'default' | 'success' | 'danger' | 'warning' | 'info' | 'loading' | 'custom';
+
+export interface ToastAction {
+  label: string;
+  onClick: () => void;
+}
+
+export interface ToastOptions {
+  id?: string | number;
+  duration?: number;
+  description?: string | null;
+  action?: ToastAction | null;
+}
+
+export interface ToastRecord {
+  id: string;
+  tone: ToastTone;
+  message: string | null;
+  description: string | null;
+  action: ToastAction | null;
+  duration: number;
+  remaining: number;
+  count: number;
+  timerKey: number;
+  node: unknown;
+  dismissible: boolean;
+  expiresAt?: number;
+}
+
+export interface ToastSnapshot {
+  toasts: ToastRecord[];
+  paused: boolean;
+  expanded: boolean;
+}
+
+export type ToastPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+
+export interface ToasterConfig {
+  position: ToastPosition;
+  duration: number;
+  visibleToasts: number;
+  gap: number;
+  offset: number;
+  expand: boolean;
+}
+
+export const DEFAULT_TOASTER_CONFIG: ToasterConfig = {
+  position: 'bottom-right',
+  duration: 0,
+  visibleToasts: 3,
+  gap: 0,
+  offset: 0,
+  expand: false,
+};
+
+const DURATION: Record<string, number> = {
+  default: 5000,
+  success: 5000,
+  info: 5000,
+  warning: 8000,
+  danger: 8000,
+  loading: Infinity,
+};
+
+let uid = 0;
+const timers = new Map<string, ReturnType<typeof setTimeout>>();
+
+interface ToastStore {
+  toasts: ToastRecord[];
+  paused: boolean;
+  expanded: boolean;
+  mounted: boolean;
+  config: ToasterConfig;
+  snap: ToastSnapshot;
+  listeners: Set<() => void>;
+  subscribe(l: () => void): () => void;
+  get(): ToastSnapshot;
+  emit(): void;
+  add(t: ToastRecord): string;
+  update(id: string, patch: Partial<ToastRecord>): string;
+  dismiss(id?: string | null): void;
+  schedule(t: ToastRecord): void;
+  pause(): void;
+  resume(): void;
+  setExpanded(v: boolean): void;
+}
+
+const store: ToastStore = {
+  toasts: [],
+  paused: false,
+  expanded: false,
+  mounted: false,
+  config: { ...DEFAULT_TOASTER_CONFIG },
+  snap: { toasts: [], paused: false, expanded: false },
+  listeners: new Set(),
+  subscribe(l) {
+    store.listeners.add(l);
+    return () => store.listeners.delete(l);
+  },
+  get: () => store.snap,
+  emit() {
+    store.snap = { toasts: store.toasts.slice(), paused: store.paused, expanded: store.expanded };
+    store.listeners.forEach((l) => l());
+  },
+
+  add(t) {
+    const twin = store.toasts.find(
+      (x) => !x.node && !t.node && x.tone === t.tone && x.message === t.message && x.description === t.description,
+    );
+    if (twin) return store.update(twin.id, { count: twin.count + 1 });
+    store.toasts.push(t);
+    store.schedule(t);
+    store.emit();
+    return t.id;
+  },
+
+  update(id, patch) {
+    const t = store.toasts.find((x) => x.id === id);
+    if (!t) return id;
+    Object.assign(t, patch);
+    if ('tone' in patch || 'duration' in patch || 'count' in patch) {
+      t.remaining = t.duration;
+      t.timerKey++;
+      store.schedule(t);
+    }
+    store.emit();
+    return id;
+  },
+
+  dismiss(id) {
+    const gone = id == null ? store.toasts : store.toasts.filter((t) => t.id === id);
+    gone.forEach((t) => {
+      clearTimeout(timers.get(t.id));
+      timers.delete(t.id);
+    });
+    store.toasts = id == null ? [] : store.toasts.filter((t) => t.id !== id);
+    store.emit();
+  },
+
+  schedule(t) {
+    clearTimeout(timers.get(t.id));
+    timers.delete(t.id);
+    if (!isFinite(t.duration)) return;
+    if (store.paused) return;
+    t.expiresAt = performance.now() + t.remaining;
+    timers.set(
+      t.id,
+      setTimeout(() => store.dismiss(t.id), t.remaining),
+    );
+  },
+
+  pause() {
+    if (store.paused) return;
+    store.paused = true;
+    store.toasts.forEach((t) => {
+      if (timers.has(t.id)) {
+        clearTimeout(timers.get(t.id));
+        timers.delete(t.id);
+        t.remaining = Math.max(0, (t.expiresAt ?? performance.now()) - performance.now());
+      }
+    });
+    store.emit();
+  },
+
+  resume() {
+    if (!store.paused) return;
+    store.paused = false;
+    store.toasts.forEach((t) => store.schedule(t));
+    store.emit();
+  },
+
+  setExpanded(v) {
+    if (v === store.expanded) return;
+    store.expanded = v;
+    store.emit();
+  },
+};
+
+let warned = false;
+let warnScheduled = false;
+
+function warnIfDetached(): void {
+  if (store.mounted || warned || warnScheduled || typeof window === 'undefined') return;
+  warnScheduled = true;
+  setTimeout(() => {
+    warnScheduled = false;
+    if (store.mounted || warned) return;
+    warned = true;
+    console.warn(
+      'zyncat-ui: a toast was triggered but no <Toaster /> is mounted, so nothing will render. Mount <Toaster /> once near your app root.',
+    );
+  });
+}
+
+function resolveDuration(tone: ToastTone, opt?: number): number {
+  if (opt != null) return opt;
+  const toneDefault = DURATION[tone];
+  if (toneDefault === Infinity || store.config.duration <= 0) return toneDefault;
+  return store.config.duration;
+}
+
+function make(tone: ToastTone, message: string | null, opts: ToastOptions = {}): string {
+  warnIfDetached();
+  const id = opts.id != null ? String(opts.id) : 'toast-' + ++uid;
+  const duration = resolveDuration(tone, opts.duration);
+  if (store.toasts.some((t) => t.id === id)) {
+    return store.update(id, {
+      tone,
+      message,
+      duration,
+      description: opts.description != null ? opts.description : null,
+      action: opts.action != null ? opts.action : null,
+    });
+  }
+  return store.add({
+    id,
+    tone,
+    message,
+    description: opts.description != null ? opts.description : null,
+    action: opts.action != null ? opts.action : null,
+    duration,
+    remaining: duration,
+    count: 1,
+    timerKey: 0,
+    node: null,
+    dismissible: true,
+  });
+}
+
+type PromiseMsg<V> = string | ((v: V) => string);
+export interface ToastPromiseMsgs<T> {
+  loading?: string;
+  success?: PromiseMsg<T>;
+  error?: PromiseMsg<unknown>;
+}
+
+export interface ToastApi {
+  (message: string, opts?: ToastOptions): string;
+  success(m: string, o?: ToastOptions): string;
+  error(m: string, o?: ToastOptions): string;
+  warning(m: string, o?: ToastOptions): string;
+  info(m: string, o?: ToastOptions): string;
+  loading(m: string, o?: ToastOptions): string;
+  dismiss(id?: string | null): void;
+  update(id: string, patch?: Partial<ToastRecord>): string;
+  promise<T>(promise: Promise<T>, msgs?: ToastPromiseMsgs<T>): Promise<T>;
+  custom(node: unknown, opts?: { id?: string | number; duration?: number; dismissible?: boolean }): string;
+}
+
+const toast = ((message: string, opts?: ToastOptions) => make('default', message, opts)) as ToastApi;
+toast.success = (m, o) => make('success', m, o);
+toast.error = (m, o) => make('danger', m, o);
+toast.warning = (m, o) => make('warning', m, o);
+toast.info = (m, o) => make('info', m, o);
+toast.loading = (m, o) => make('loading', m, o);
+toast.dismiss = (id) => store.dismiss(id);
+
+toast.update = (id, patch = {}) => {
+  if (patch.tone && patch.duration == null) patch = { ...patch, duration: DURATION[patch.tone] };
+  return store.update(id, patch);
+};
+
+toast.promise = function <T>(promise: Promise<T>, msgs: ToastPromiseMsgs<T> = {}): Promise<T> {
+  const id = make('loading', msgs.loading != null ? msgs.loading : 'Working...');
+  const text = <V>(m: PromiseMsg<V> | undefined, fallback: string, v: V): string =>
+    typeof m === 'function' ? (m as (x: V) => string)(v) : m != null ? m : fallback;
+  promise.then(
+    (v) => toast.update(id, { tone: 'success', message: text(msgs.success, 'Done', v) }),
+    (e) => toast.update(id, { tone: 'danger', message: text(msgs.error, 'Something went wrong', e) }),
+  );
+  return promise;
+};
+
+toast.custom = (node, opts = {}) => {
+  warnIfDetached();
+  const id = opts.id != null ? String(opts.id) : 'toast-' + ++uid;
+  const duration = opts.duration != null ? opts.duration : Infinity;
+  if (store.toasts.some((t) => t.id === id)) return store.update(id, { node });
+  return store.add({
+    id,
+    tone: 'custom',
+    node,
+    message: null,
+    description: null,
+    action: null,
+    duration,
+    remaining: duration,
+    count: 1,
+    timerKey: 0,
+    dismissible: opts.dismissible === true,
+  });
+};
+
+export { toast };
+export const UIToast = store;

package/src/components/composites/toast/toast.css

@@ -0,0 +1,257 @@
+/* toast.css - the glass notification card, tinted per tone (a draining timer ring). */
+
+.toast-viewport {
+  position: fixed;
+  width: min(22.5rem, calc(100vw - 2 * var(--toast-offset, var(--space-6))));
+  z-index: var(--layer-toast);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  pointer-events: none; /* only the cards themselves are live */
+}
+
+/* Anchored by [data-position]; --toast-offset (set by <Toaster offset>) overrides the edge inset. */
+.toast-viewport[data-position^='top'] {
+  top: var(--toast-offset, var(--space-6));
+}
+.toast-viewport[data-position^='bottom'] {
+  bottom: var(--toast-offset, var(--space-6));
+}
+.toast-viewport[data-position$='right'] {
+  right: var(--toast-offset, var(--space-6));
+}
+.toast-viewport[data-position$='left'] {
+  left: var(--toast-offset, var(--space-6));
+}
+.toast-viewport[data-position$='center'] {
+  left: 50%;
+  transform: translateX(-50%);
+}
+
+/* The card - a glass consumer (.glass is set in JSX). */
+.toast {
+  /* tone hooks - set by [data-tone] below */
+  --toast-hue: var(--text-subtle);
+  --glass-fg: var(--text-strong);
+  --glass-tint: color-mix(in oklab, var(--glass-tint-neutral) 75%, transparent);
+  --glass-sheen-rest: 0.45;
+
+  position: absolute;
+  left: 0;
+  width: 100%;
+  box-sizing: border-box;
+  overflow: hidden; /* custom content stays in the pane   */
+  pointer-events: auto;
+  border-radius: var(--radius-lg);
+
+  /* Motion owns transform - keep only the color/shadow transitions (never smooth Motion's writes) */
+  transition:
+    background-color var(--duration-base) var(--ease-standard),
+    box-shadow var(--duration-base) var(--ease-standard);
+}
+
+/* Cards pin to the stack's edge; Motion offsets each one away from it (up from bottom, down from top). */
+.toast-viewport[data-position^='bottom'] .toast {
+  bottom: 0;
+  transform-origin: center bottom;
+}
+.toast-viewport[data-position^='top'] .toast {
+  top: 0;
+  transform-origin: center top;
+}
+
+/* rich panes for genuine status, diluted to stay glass; neutral otherwise */
+.toast[data-tone='success'] {
+  --toast-hue: var(--success);
+  --glass-fg: var(--success-text);
+  --glass-tint: color-mix(in oklab, var(--glass-tint-success) 70%, transparent);
+}
+.toast[data-tone='danger'] {
+  --toast-hue: var(--danger);
+  --glass-fg: var(--danger-text);
+  --glass-tint: color-mix(in oklab, var(--glass-tint-danger) 70%, transparent);
+}
+.toast[data-tone='warning'] {
+  --toast-hue: var(--warning);
+  --glass-fg: var(--warning-text);
+  --glass-tint: color-mix(in oklab, var(--glass-tint-warning) 70%, transparent);
+}
+.toast[data-tone='info'] {
+  --toast-hue: var(--info);
+  --glass-fg: var(--info-text);
+  --glass-tint: color-mix(in oklab, var(--glass-tint-info) 70%, transparent);
+}
+
+/* receding cards fall quiet: tone drains out, sheen dims, content fades */
+.toast[data-behind] {
+  --glass-tint: color-mix(in oklab, var(--glass-tint-neutral) 75%, transparent);
+  --glass-sheen-rest: 0.3;
+}
+.toast[data-behind] .toast__inner,
+.toast[data-behind] .toast__custom {
+  opacity: 0;
+}
+
+.toast__inner {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  padding: var(--space-3) var(--space-4);
+  transition: var(--transition-opacity);
+}
+
+/* the dial - glyph centered in the timer ring; one instrument, not two */
+.toast__icon {
+  position: relative;
+  flex: none;
+  display: grid;
+  place-items: center;
+  width: calc(var(--icon-md) + 2 * var(--space-2));
+  height: calc(var(--icon-md) + 2 * var(--space-2));
+  color: var(--toast-hue);
+}
+.toast__icon-glyph {
+  display: grid;
+  place-items: center;
+}
+
+/* the ring - a draining arc; linear by design, animation-duration set at runtime to the toast's lifetime */
+.toast__ring {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  transform: rotate(-90deg); /* arc starts at 12 o'clock           */
+  pointer-events: none;
+}
+.toast__ring circle {
+  fill: none;
+  stroke-width: var(--border-emphasis);
+}
+.toast__ring-track {
+  stroke: color-mix(in oklab, var(--toast-hue) 16%, transparent);
+}
+.toast__ring-arc {
+  stroke: var(--toast-hue);
+  stroke-linecap: round;
+  stroke-dasharray: 1; /* pathLength=1 - offset is a fraction */
+  animation-name: toast-ring;
+  animation-timing-function: linear;
+  animation-fill-mode: both;
+}
+.toast-viewport.is-paused .toast__ring-arc {
+  animation-play-state: paused;
+}
+@keyframes toast-ring {
+  from {
+    stroke-dashoffset: 0;
+  }
+  to {
+    stroke-dashoffset: 1;
+  }
+}
+
+.toast__text {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+.toast__message {
+  margin: 0;
+  font: var(--type-label);
+  color: var(--glass-fg);
+  text-wrap: pretty;
+}
+.toast__desc {
+  margin: var(--space-1) 0 0;
+  font: var(--type-caption);
+  color: color-mix(in oklab, var(--glass-fg) 76%, transparent);
+  text-wrap: pretty;
+}
+
+/* coalesce counter - same toast refired becomes a xN counter (mono) */
+.toast__count {
+  flex: none;
+  font-family: var(--font-mono);
+  font-size: var(--size-micro);
+  line-height: var(--leading-micro);
+  font-variant-numeric: tabular-nums;
+  color: var(--glass-fg);
+  background: color-mix(in oklab, var(--glass-fg) 9%, transparent);
+  border-radius: var(--radius-sm);
+  padding: 0 var(--space-1);
+}
+
+.toast__action {
+  flex: none;
+}
+
+/* dismiss - appears only while the card is hovered or holds focus */
+.toast__close {
+  flex: none;
+  appearance: none;
+  display: grid;
+  place-items: center;
+  width: var(--space-6);
+  height: var(--space-6);
+  margin: 0;
+  padding: 0;
+  border: none;
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: color-mix(in oklab, var(--glass-fg) 64%, transparent);
+  cursor: pointer;
+  opacity: 0;
+  transition:
+    var(--transition-control),
+    opacity var(--duration-fast) var(--ease-standard);
+}
+.toast:hover .toast__close,
+.toast:focus-within .toast__close {
+  opacity: 1;
+}
+.toast__close:hover {
+  background: color-mix(in oklab, var(--glass-fg) 9%, transparent);
+  color: var(--glass-fg);
+}
+.toast__close:active {
+  background: color-mix(in oklab, var(--glass-fg) 14%, transparent);
+}
+.toast__close:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring);
+  opacity: 1;
+}
+
+/* Loading spinner - continuous --duration-spin (linear is allowed for loops; reduced motion slows, never freezes) */
+.toast__spinner {
+  display: block;
+  box-sizing: border-box;
+  width: var(--icon-sm);
+  height: var(--icon-sm);
+  border-radius: var(--radius-full);
+  border: var(--border-emphasis) solid currentColor;
+  border-right-color: transparent;
+  color: var(--text-muted);
+  animation: toast-spin var(--duration-spin) linear infinite;
+}
+@keyframes toast-spin {
+  to {
+    transform: rotate(1turn);
+  }
+}
+
+/* Custom slot - bare neutral glass; the consumer owns the interior. */
+.toast__custom {
+  padding: var(--space-3) var(--space-4);
+  transition: var(--transition-opacity);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  /* travel/gestures collapse via the tokens; the ring is data, so it keeps running */
+  .toast,
+  .toast__close,
+  .toast__inner,
+  .toast__custom {
+    transition: none;
+  }
+}

package/src/components/composites/tooltip/Tooltip.tsx

@@ -0,0 +1,110 @@
+'use client';
+
+import './tooltip.css';
+import {
+  Fragment,
+  useEffect,
+  useId,
+  useRef,
+  type FocusEvent,
+  type HTMLAttributes,
+  type PointerEvent,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { store, useHostElection, OPEN_DELAY, CLOSE_GRACE, TOOLTIP_DOM_ID, type Placement } from './tooltip-store';
+import { TooltipHost } from './tooltip-host';
+import type { DataAttributes } from '../../../dom-props';
+import { cx } from '../../internal/utils/cx';
+
+export interface TooltipProps {
+  /** The hint - a string or small node; never interactive content. */
+  content: ReactNode;
+  /** Optional keyboard hint, rendered as mono metadata ("⌘↩", "S"). */
+  shortcut?: string | null;
+  /** Preferred side; flips automatically when out of viewport room. */
+  placement?: Placement;
+  /** Suppress the tooltip entirely (trigger renders untouched). */
+  disabled?: boolean;
+  /** ms before a cold hover shows; warm hovers + focus are instant. Default 350. */
+  openDelay?: number;
+  /** ms the bubble lingers after leaving (bridges moving to a neighbour). Default 140. */
+  closeDelay?: number;
+  /** Stable id for this trigger's store entry - lets overlapping triggers race safely under
+   *  the one shared tooltip host. Not rendered to the DOM. Auto-generated when omitted. */
+  id?: string;
+  /** Exactly one element. */
+  children: ReactElement;
+  /** Standard <span> attributes forwarded to the anchor wrapper. */
+  htmlProps?: HTMLAttributes<HTMLSpanElement> & DataAttributes;
+}
+
+export function Tooltip({
+  content,
+  shortcut = null,
+  placement = 'top',
+  disabled = false,
+  openDelay = OPEN_DELAY,
+  closeDelay = CLOSE_GRACE,
+  id,
+  children,
+  htmlProps,
+}: TooltipProps) {
+  const wrapRef = useRef<HTMLSpanElement | null>(null);
+  const openTimer = useRef<ReturnType<typeof setTimeout> | 0>(0);
+  const myId = id || 'tip-' + useId();
+  const isHost = useHostElection();
+
+  const anchorEl = (): HTMLElement | null => (wrapRef.current?.firstElementChild as HTMLElement) ?? null;
+
+  useEffect(
+    () => () => {
+      clearTimeout(openTimer.current);
+      store.close(myId, 0);
+    },
+    [],
+  ); // eslint-disable-line react-hooks/exhaustive-deps
+
+  function show(immediate: boolean) {
+    if (disabled) return;
+    clearTimeout(openTimer.current);
+    const el = anchorEl();
+    if (!el) return;
+    el.setAttribute('aria-describedby', TOOLTIP_DOM_ID);
+    const open = () =>
+      store.open({ id: myId, content, shortcut, placement, rect: () => anchorEl()!.getBoundingClientRect() });
+    if (immediate || store.isWarm()) open();
+    else openTimer.current = setTimeout(open, openDelay);
+  }
+  function hide() {
+    clearTimeout(openTimer.current);
+    const el = anchorEl();
+    if (el) el.removeAttribute('aria-describedby');
+    store.close(myId, closeDelay);
+  }
+
+  const onEnter = (e: PointerEvent) => {
+    if (e.pointerType !== 'touch') show(false);
+  };
+  const onFocusIn = (e: FocusEvent) => {
+    if ((e.target as HTMLElement).matches(':focus-visible')) show(true);
+  };
+
+  return (
+    <Fragment>
+      <span
+        {...htmlProps}
+        ref={wrapRef}
+        className={cx('tooltip-anchor', htmlProps?.className)}
+        onPointerEnter={onEnter}
+        onPointerLeave={hide}
+        onPointerDown={hide}
+        onFocus={onFocusIn}
+        onBlur={hide}
+      >
+        {children}
+      </span>
+      {isHost && <TooltipHost />}
+    </Fragment>
+  );
+}