@twentyfirstmedia/ui-core 0.1.1 → 0.2.1

package/src/components/types.ts

@@ -1,8 +1,9 @@
 import type { ChangeEvent, CSSProperties, MouseEvent, ReactNode } from "react";
 import type { IconName } from "../icons.js";
 import type { ToastOptions } from "../toast-store.js";
+import type { Surface } from "../provider.js";
 
-export type { IconName, ToastOptions };
+export type { IconName, ToastOptions, Surface };
 
 /* Props of every component, ported from the reference (design-system/components/index.d.ts). */
 
@@ -160,6 +161,8 @@ export interface CardProps extends BaseProps {
   onClick?: () => void;
   children?: ReactNode;
   eyebrow?: ReactNode;
+  /** `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. */
+  surface?: Surface;
 }
 export interface EventCardProps extends BaseProps {
   kind?: "meeting" | "deadline" | "review" | "launch" | "incident";
@@ -177,6 +180,8 @@ export interface PanelProps extends BaseProps {
   subtitle?: string;
   action?: ReactNode;
   children?: ReactNode;
+  /** `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. */
+  surface?: Surface;
 }
 export interface PageHeaderProps extends BaseProps {
   crumbs?: string[];
@@ -211,6 +216,39 @@ export interface SideRailProps extends BaseProps {
   top?: RailItem[];
   bottom?: RailItem[];
 }
+export interface FloatingLayoutProps extends BaseProps {
+  /** What the UI floats over, filling the layout: a map, a 3D canvas, a video, a photo. */
+  background?: ReactNode;
+  /** Bar along the top edge (search, filters, title). */
+  top?: ReactNode;
+  /** Column on the start side (layers, lists, settings). */
+  start?: ReactNode;
+  /** Column on the end side (details of the selected thing). */
+  end?: ReactNode;
+  /** Bar along the bottom edge (dock, playback, a summary). */
+  bottom?: ReactNode;
+  /** Height of the layout (default 640). Below 720px of width the slots stack: top, start, end, bottom. */
+  height?: number | string;
+  /** Glass for every surface in the slots (default) or solid surfaces. */
+  surface?: Surface;
+  /** Accessible name of the region. */
+  label?: string;
+  children?: ReactNode;
+}
+export interface AmbientProps extends BaseProps {
+  /** Colours of the soft fields (any CSS colour); default the kit's `--ambient-1…4`. */
+  colors?: string[];
+  /** A photo (or, with `video`, a video) instead of the fields, under a scrim that keeps it calm. */
+  src?: string;
+  /** Treat `src` as a video (muted, looping, still with motion off). */
+  video?: boolean;
+  /** Let the fields drift slowly (default true). Still with motion off; paused off screen. */
+  animate?: boolean;
+  /** Cover the window behind the page instead of the nearest container. */
+  fixed?: boolean;
+  /** Your own layer (a canvas, WebGL, a map) instead of fields or media. */
+  children?: ReactNode;
+}
 export interface DockItem {
   label: string;
   icon: IconName;
@@ -220,6 +258,8 @@ export interface DockItem {
 export interface DockProps extends BaseProps {
   items: DockItem[];
   label?: string;
+  /** `"glass"`: translucent glass over what is behind (maps, 3D, video, photos); `"solid"` opts out inside a glass `UIProvider`. */
+  surface?: Surface;
 }
 export interface TableColumn {
   key: string;
@@ -282,7 +322,10 @@ export interface StaggerProps extends BaseProps {
   as?: string;
   className?: string;
   style?: CSSProperties;
+  /** Extra delay before the first child, in ms. */
   delay?: number;
+  /** Below the fold, wait until the group scrolls into view (default true). */
+  reveal?: boolean;
   children?: ReactNode;
 }
 export interface CountUpProps extends BaseProps {
@@ -404,6 +447,8 @@ export interface ModalProps extends BaseProps {
   onClose?: () => void;
   style?: CSSProperties;
   children?: ReactNode;
+  /** Optional: with `open` the component stays mounted while it animates out; without it, render it only while open. */
+  open?: boolean;
 }
 /** Mounts a demo page with a "Replay motion" button that re-runs every entrance. */
 export interface SubNavItem {
@@ -428,6 +473,8 @@ export interface DrawerProps extends BaseProps, DrawerSide {
   width?: number | string;
   inline?: boolean;
   children?: ReactNode;
+  /** Optional: with `open` the component stays mounted while it animates out; without it, render it only while open. */
+  open?: boolean;
 }
 export interface PaletteItem {
   id?: string | number;
@@ -450,6 +497,8 @@ export interface CommandPaletteProps extends BaseProps {
   empty?: ReactNode;
   /** Called with the query as the user types, for searching on a server. */
   onQueryChange?: (query: string) => void;
+  /** Optional: with `open` the component stays mounted while it animates out; without it, render it only while open. */
+  open?: boolean;
 }
 export interface DrawerSide {
   /** Edge the sheet slides in from (default right). */
@@ -1787,8 +1836,11 @@ export interface MapViewProps extends BaseProps {
   renderPopup?: (p: MapPoint) => ReactNode;
   legend?: ReactNode;
   controls?: ReactNode;
-  height?: number;
+  /** Height in px (default 320) or any CSS length, e.g. "100%" to fill a FloatingLayout. */
+  height?: number | string;
   label?: string;
+  /** `"glass"`: the legend, controls and popup float as glass over the map (for a live map in `background`). */
+  surface?: Surface;
   className?: string;
 }
 

package/src/components/workspace.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import * as React from "react";
+import { leaving, usePresence } from "../presence.js";
 import { formatMoney } from "../format.js";
 import { Icon } from "../Icon.js";
 import { useScrollFocus, useTrap } from "../hooks.js";
@@ -65,9 +66,12 @@ export function SubNav(p: SubNavProps) {
 }
 export function Drawer(p: DrawerProps) {
   const ref = React.useRef<HTMLElement>(null);
+  const pr = usePresence(p.open ?? true);
   useTrap(ref, p.onClose);
+  if (!pr.mounted) return null;
   return (
     <div
+      {...leaving(pr.closing)}
       className={cx("tf-drawer-wrap", p.inline && "inline")}
       onMouseDown={(e) => {
         if (e.target === e.currentTarget && p.onClose) p.onClose?.();
@@ -120,7 +124,8 @@ export function Drawer(p: DrawerProps) {
 export function CommandPalette(p: CommandPaletteProps) {
   const q = React.useState(""),
     idx = React.useState(0),
-    ref = React.useRef<HTMLDivElement>(null);
+    ref = React.useRef<HTMLDivElement>(null),
+    pr = usePresence(p.open ?? true);
   useTrap(ref, p.onClose);
   const ql = q[0].toLowerCase().trim(),
     all = p.items || [];
@@ -168,8 +173,10 @@ export function CommandPalette(p: CommandPaletteProps) {
       });
     groups[groups.length - 1].items.push([it, i]);
   });
+  if (!pr.mounted) return null;
   return (
     <div
+      {...leaving(pr.closing)}
       className={cx("tf-palette-wrap", p.inline && "inline")}
       onMouseDown={(e) => {
         if (e.target === e.currentTarget && p.onClose) p.onClose?.();

package/src/cx.ts

@@ -3,17 +3,34 @@ export function cx(...parts: unknown[]): string {
   return parts.filter((x): x is string => typeof x === "string" && x !== "").join(" ");
 }
 
-/** True when the user asked for reduced motion (false on the server). */
-export function reduced(): boolean {
+/**
+ * True when motion is off for `el` (or the page): the reader asked for reduced motion, or the
+ * nearest `data-motion` says "off". False on the server.
+ */
+export function reduced(el?: Element | null): boolean {
   try {
-    return (
-      typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches
-    );
+    if (typeof window === "undefined") return false;
+    if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) return true;
+    const host = (el ?? document.documentElement).closest("[data-motion]");
+    return host?.getAttribute("data-motion") === "off";
   } catch {
     return false;
   }
 }
 
+/** The entrance delay of the card `el` sits in (Stagger, `tf-in`), in ms. */
+export function enterDelay(el?: Element | null): number {
+  try {
+    const host = el?.closest(".tf-stagger > *, .tf-in");
+    if (!host) return 0;
+    const d = getComputedStyle(host).animationDelay.split(",")[0]?.trim() ?? "";
+    const n = parseFloat(d);
+    return isNaN(n) ? 0 : d.endsWith("ms") ? n : n * 1000;
+  } catch {
+    return 0;
+  }
+}
+
 /** Initials for avatars: first letters of up to two words. */
 export function initials(name?: string): string {
   return (

package/src/index.ts

@@ -16,8 +16,11 @@ export {
   type Kit,
   type Theme,
   type Density,
+  type Motion,
 } from "./provider.js";
 export { Portal } from "./portal.js";
+export { startViewTransition, useMotion } from "./motion.js";
+export { usePresence, leaving, type Presence } from "./presence.js";
 export {
   THEME_VARS,
   THEME_PRESETS,

package/src/motion.ts

@@ -0,0 +1,48 @@
+"use client";
+import { useEffect, useState } from "react";
+import { reduced } from "./cx.js";
+import { useUI, type Motion } from "./provider.js";
+
+/**
+ * Runs `update` (a route change, a tab switch, new data) as a view transition: the old page fades
+ * out and the new one rises in, in the kit's motion. Falls back to a plain update where the
+ * browser has no view transitions or motion is off.
+ */
+export async function startViewTransition(update: () => void | Promise<void>): Promise<void> {
+  const doc = typeof document === "undefined" ? undefined : document;
+  const start = (
+    doc as
+      | (Document & {
+          startViewTransition?: (cb: () => void | Promise<void>) => { finished: Promise<void> };
+        })
+      | undefined
+  )?.startViewTransition;
+  if (!doc || !start || reduced()) {
+    await update();
+    return;
+  }
+  try {
+    await start.call(doc, update).finished;
+  } catch {
+    // an interrupted transition still ran the update
+  }
+}
+
+/**
+ * The motion level in effect: "off" while the reader asks for reduced motion or the nearest
+ * provider turns motion off, otherwise the provider's level ("standard" by default).
+ */
+export function useMotion(): Motion {
+  const { motion } = useUI();
+  const [off, setOff] = useState(false);
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return;
+    const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const on = () => setOff(mq.matches);
+    on();
+    mq.addEventListener("change", on);
+    return () => mq.removeEventListener("change", on);
+  }, []);
+  if (off) return "off";
+  return motion ?? "standard";
+}

package/src/presence.ts

@@ -0,0 +1,58 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+import { durationToken, reduced } from "./cx.js";
+
+export interface Presence {
+  /** Render the layer: while open and while it plays its exit. */
+  mounted: boolean;
+  /** The layer is leaving: it carries `data-closing` (exit animation) and is inert. */
+  closing: boolean;
+}
+
+/**
+ * Keeps a layer (menu, popover, dialog, drawer, toast) in the page for `--dur-exit` after it
+ * closes, so it can animate out. With motion off, reduced motion or no exit duration it leaves at
+ * once, as before.
+ */
+export function usePresence(open: boolean): Presence {
+  const [mounted, setMounted] = useState(open);
+  const [closing, setClosing] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => {
+    if (timer.current) {
+      clearTimeout(timer.current);
+      timer.current = null;
+    }
+    if (open) {
+      setMounted(true);
+      setClosing(false);
+      return;
+    }
+    if (!mounted) return;
+    const ms = reduced() ? 0 : durationToken("--dur-exit", 0);
+    if (ms <= 0) {
+      setMounted(false);
+      setClosing(false);
+      return;
+    }
+    setClosing(true);
+    timer.current = setTimeout(() => {
+      timer.current = null;
+      setMounted(false);
+      setClosing(false);
+    }, ms);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- only the open state drives this
+  }, [open]);
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+  return { mounted: mounted || open, closing: closing && !open };
+}
+
+/** Props for the layer's root while it leaves. */
+export function leaving(closing: boolean): { "data-closing"?: ""; inert?: boolean } {
+  return closing ? { "data-closing": "", inert: true } : {};
+}

package/src/provider.tsx

@@ -13,6 +13,13 @@ import { themeStyle, type ThemeInput, type ThemeValues } from "./theme.js";
 export type Kit = "halo" | "pro";
 export type Theme = "light" | "dark" | "system";
 export type Density = "compact" | "comfortable";
+/** How surfaces paint: solid (the default) or glass, translucent over what is behind them. */
+export type Surface = "solid" | "glass";
+/**
+ * How much things move: "standard" (the kit's own motion), "expressive" (longer, staggered page
+ * entrances, more travel; Pro stays crisp) or "off". A reduced-motion setting always means "off".
+ */
+export type Motion = "off" | "standard" | "expressive";
 
 export interface UIProviderProps {
   /** Which kit's CSS applies (sets `data-kit`). Only matters when both kits are loaded (`themes.css`). */
@@ -33,6 +40,19 @@ export interface UIProviderProps {
    * per mode. For a fixed theme, CSS is simpler (see `themeCss`); this is for runtime brands.
    */
   tokens?: ThemeValues | ThemeInput;
+  /**
+   * `"glass"` turns every top-level surface (Panel, Card, Dock, map legend and controls) and every
+   * floating layer (menus, popovers, dialogs, drawers) inside into translucent glass, for UI that
+   * floats over a map, a 3D scene, video or photos (sets `data-surface`). Single surfaces take
+   * `surface="glass"` themselves; `surface="solid"` on one opts it out.
+   */
+  surface?: Surface;
+  /**
+   * Motion level for everything inside (sets `data-motion`): `"standard"` (default), `"expressive"`
+   * for orchestrated page entrances, or `"off"`, e.g. for a setting in your app. The reader's
+   * reduced-motion setting always turns motion off.
+   */
+  motion?: Motion;
   className?: string;
   style?: CSSProperties;
   children?: ReactNode;
@@ -42,6 +62,8 @@ export interface UIContextValue {
   kit: Kit | undefined;
   theme: Theme | undefined;
   density: Density | undefined;
+  surface: Surface | undefined;
+  motion: Motion | undefined;
   /** Element portals render into (null: document.body). */
   portalRoot: HTMLElement | null;
 }
@@ -50,6 +72,8 @@ const UIContext = createContext<UIContextValue>({
   kit: undefined,
   theme: undefined,
   density: undefined,
+  surface: undefined,
+  motion: undefined,
   portalRoot: null,
 });
 
@@ -83,9 +107,16 @@ const isThemeInput = (t: ThemeValues | ThemeInput): t is ThemeInput =>
   "light" in t || "dark" in t || "radius" in t;
 
 export function UIProvider(p: UIProviderProps) {
+  const parent = useUI();
   const scope = p.scope ?? "document";
+  // a nested provider keeps what it does not set itself
+  const kit = p.kit ?? parent.kit;
+  const theme = p.theme ?? parent.theme;
+  const density = p.density ?? parent.density;
+  const surface = p.surface ?? parent.surface;
+  const motion = p.motion ?? parent.motion;
   const perMode = !!p.tokens && isThemeInput(p.tokens);
-  const dark = useDarkMode(p.theme, p.kit, perMode);
+  const dark = useDarkMode(theme, kit, perMode);
   const vars = useMemo(() => {
     if (!p.tokens) return undefined;
     if (!isThemeInput(p.tokens)) return themeStyle(p.tokens);
@@ -118,13 +149,19 @@ export function UIProvider(p: UIProviderProps) {
     set("data-kit", p.kit);
     set("data-theme", p.theme);
     set("data-density", p.density);
-  }, [scope, p.kit, p.theme, p.density]);
+    set("data-surface", p.surface);
+    set("data-motion", p.motion);
+  }, [scope, p.kit, p.theme, p.density, p.surface, p.motion]);
 
   const [portalRoot, setPortalRoot] = useState<HTMLElement | null>(null);
   const ctx = useMemo<UIContextValue>(
-    () => ({ kit: p.kit, theme: p.theme, density: p.density, portalRoot }),
-    [p.kit, p.theme, p.density, portalRoot],
+    () => ({ kit, theme, density, surface, motion, portalRoot }),
+    [kit, theme, density, surface, motion, portalRoot],
   );
+  // Derived colours (glass, hover shades, Pro's scale) are worked out where data-theme sits. A
+  // subtree with its own tokens needs data-theme too, or they would keep the outer values.
+  const subtreeTheme =
+    p.theme ?? (vars ? (theme ?? (kit === "pro" ? "dark" : "system")) : undefined);
   const content = p.children;
   if (scope === "subtree") {
     return (
@@ -133,8 +170,10 @@ export function UIProvider(p: UIProviderProps) {
           className={p.className}
           style={vars ? ({ ...vars, ...p.style } as CSSProperties) : p.style}
           data-kit={p.kit}
-          data-theme={p.theme}
+          data-theme={subtreeTheme}
           data-density={p.density}
+          data-surface={p.surface}
+          data-motion={p.motion}
         >
           {content}
           <div ref={setPortalRoot} data-tf-portal="" />

package/src/toast-store.ts

@@ -16,6 +16,8 @@ export interface ToastData extends ToastOptions {
   id: string;
   tone: ToastTone;
   duration: number;
+  /** Animating out; removed after `--dur-exit`. */
+  leaving?: boolean;
 }
 
 let list: ToastData[] = [];
@@ -36,9 +38,34 @@ export function toast(o: ToastOptions | string): string {
   return t.id;
 }
 toast.dismiss = (id: string): void => {
-  list = list.filter((t) => t.id !== id);
+  const ms = exitMs();
+  if (ms <= 0) {
+    list = list.filter((t) => t.id !== id);
+    emit();
+    return;
+  }
+  list = list.map((t) => (t.id === id ? { ...t, leaving: true } : t));
   emit();
+  setTimeout(() => {
+    list = list.filter((t) => t.id !== id);
+    emit();
+  }, ms);
 };
+
+/** How long a toast takes to leave (0 without motion). */
+function exitMs(): number {
+  try {
+    if (typeof window === "undefined") return 0;
+    if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) return 0;
+    if (document.documentElement.closest("[data-motion]")?.getAttribute("data-motion") === "off")
+      return 0;
+    const raw = getComputedStyle(document.documentElement).getPropertyValue("--dur-exit").trim();
+    const n = parseFloat(raw);
+    return isNaN(n) ? 0 : raw.endsWith("ms") ? n : n * 1000;
+  } catch {
+    return 0;
+  }
+}
 toast.clear = (): void => {
   list = [];
   emit();