@twentyfirstmedia/elements 0.1.0 → 0.2.0

package/dist/elements.d.ts

@@ -135,6 +135,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;
@@ -292,6 +305,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";
@@ -309,6 +324,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[];
@@ -343,6 +360,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;
@@ -352,6 +402,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;
@@ -414,7 +466,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 {
@@ -536,6 +591,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 {
@@ -560,6 +617,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;
@@ -582,6 +641,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). */
@@ -1919,8 +1980,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;
 }
 
@@ -2968,6 +3032,10 @@ export type TfTopBarElement = TfElement<TopBarProps>;
 export type TfSideRailElement = TfElement<SideRailProps>;
 /** `<tf-dock>`: The Dock component as a custom element. */
 export type TfDockElement = TfElement<DockProps>;
+/** `<tf-floating-layout>`: UI floating over a full-bleed background: a map, a 3D scene, a video or a photo. */
+export type TfFloatingLayoutElement = TfElement<FloatingLayoutProps>;
+/** `<tf-ambient>`: A calm, living background for glass UI: soft colour fields from the kit (pastels in Halo, a faint aurora in Pro) that drift slowly, a photo or video under a scrim, or your own layer. */
+export type TfAmbientElement = TfElement<AmbientProps>;
 /** `<tf-app-shell>`: The AppShell component as a custom element. */
 export type TfAppShellElement = TfElement<AppShellProps>;
 /** `<tf-chat-launcher>`: Site-wide chrome for customer-facing apps: ChatLauncher (floating assistant with page context), CookieConsent and AnnouncementBar. */
@@ -3203,6 +3271,8 @@ declare global {
     "tf-top-bar": TfTopBarElement;
     "tf-side-rail": TfSideRailElement;
     "tf-dock": TfDockElement;
+    "tf-floating-layout": TfFloatingLayoutElement;
+    "tf-ambient": TfAmbientElement;
     "tf-app-shell": TfAppShellElement;
     "tf-chat-launcher": TfChatLauncherElement;
     "tf-cookie-consent": TfCookieConsentElement;