@12-apps/ui 6.54.0 → 6.55.0

package/src/components/data-display/InteractiveTooltip/InteractiveTooltip.tsx

@@ -1,124 +1,127 @@
-import MuiTooltip from '@mui/material/Tooltip/index.js';
-import { styled } from '@mui/material/styles/index.js';
-import React from 'react';
+import MuiTooltip from "@mui/material/Tooltip/index.js";
+import type { CSSObject, Theme } from "@mui/material/styles/index.js";
+import React from "react";
 
-import { resolveTooltipProps, useHoverOpen, usePinnedTooltip } from './InteractiveTooltip.hooks';
+import {
+  resolveTooltipProps,
+  useHoverOpen,
+  usePinnedTooltip,
+} from "./InteractiveTooltip.hooks";
 import {
   arrowColor,
   emphasisStyles,
   getSizeStyles,
   tooltipCap,
   variantStyles,
-} from './InteractiveTooltip.styles';
-import type { InteractiveTooltipProps } from './InteractiveTooltip.types';
-
-const StyledTooltip = styled(MuiTooltip, {
-  shouldForwardProp: (prop) =>
-    !['customVariant', 'customSize', 'glow', 'pulse'].includes(prop as string),
-})<{
-  customVariant?: string;
-  customSize?: string;
-  glow?: boolean;
-  pulse?: boolean;
-}>(({ theme, customVariant, customSize, glow, pulse }) => {
-  const sizeStyles = getSizeStyles(customSize);
+} from "./InteractiveTooltip.styles";
+import type { InteractiveTooltipProps } from "./InteractiveTooltip.types";
 
-  return {
-    '& .MuiTooltip-tooltip': {
+/**
+ * The bubble's own look, applied to the BUBBLE (FUT-3093) — see `Tooltip`'s
+ * `bubbleSx`: a `& .MuiTooltip-tooltip` rule on the root never reached the
+ * portalled bubble, so the variants had never been on screen.
+ */
+const bubbleSx =
+  (
+    variant: string | undefined,
+    size: string | undefined,
+    glow: boolean | undefined,
+    pulse: boolean | undefined,
+    maxWidth: number | undefined,
+  ) =>
+  (theme: Theme): CSSObject => {
+    const sizeStyles = getSizeStyles(size);
+    return {
       borderRadius: theme.spacing(1),
       fontSize: sizeStyles.fontSize(theme),
       padding: sizeStyles.padding(theme),
       fontWeight: 500,
-      transition: 'all 0.3s ease',
-      position: 'relative',
-      overflow: 'hidden',
-      ...variantStyles(theme, customVariant),
+      transition: "all 0.3s ease",
+      position: "relative",
+      maxWidth: tooltipCap(maxWidth)(theme),
+      ...variantStyles(theme, variant),
       ...emphasisStyles(theme, glow, pulse),
-    },
-
-    '& .MuiTooltip-arrow': {
-      color: arrowColor(theme, customVariant),
-    },
+    };
   };
-});
 
-export const InteractiveTooltip = React.forwardRef<HTMLDivElement, InteractiveTooltipProps>(
-  (rawProps, ref) => {
-    const {
-      variant,
-      size,
-      glow,
-      pulse,
-      maxWidth,
-      dataTestId,
-      hoverContent,
-      pinnedContent,
-      clickable,
-      onPin,
-      onUnpin,
-      className,
-      children,
-      onOpen,
-      onClose,
-      ...props
-    } = resolveTooltipProps(rawProps);
+export const InteractiveTooltip = React.forwardRef<
+  HTMLDivElement,
+  InteractiveTooltipProps
+>((rawProps, ref) => {
+  const {
+    variant,
+    size,
+    glow,
+    pulse,
+    maxWidth,
+    dataTestId,
+    hoverContent,
+    pinnedContent,
+    clickable,
+    onPin,
+    onUnpin,
+    className,
+    children,
+    onOpen,
+    onClose,
+    ...props
+  } = resolveTooltipProps(rawProps);
 
-    const { isPinned, isControlledOpen, wrapperRef, handleClick } = usePinnedTooltip({
+  const { isPinned, isControlledOpen, wrapperRef, handleClick } =
+    usePinnedTooltip({
       clickable,
       onPin,
       onUnpin,
     });
-    const hover = useHoverOpen(isPinned, onOpen, onClose);
+  const hover = useHoverOpen(isPinned, onOpen, onClose);
 
-    // Determine which content to show
-    const tooltipContent = isPinned ? pinnedContent : hoverContent;
+  // Determine which content to show
+  const tooltipContent = isPinned ? pinnedContent : hoverContent;
 
-    // Child with click handler and ref
-    const childElement = children as React.ReactElement<{
-      onClick?: (e: React.MouseEvent) => void;
-      'data-testid'?: string;
-    }>;
+  // Child with click handler and ref
+  const childElement = children as React.ReactElement<{
+    onClick?: (e: React.MouseEvent) => void;
+    "data-testid"?: string;
+  }>;
 
-    const childWithProps = React.cloneElement(childElement, {
-      onClick: (e: React.MouseEvent) => {
-        handleClick(e);
-        // Call original onClick if it exists
-        childElement.props.onClick?.(e);
-      },
-      'data-testid': dataTestId ? `${dataTestId}-trigger` : undefined,
-    });
+  const childWithProps = React.cloneElement(childElement, {
+    onClick: (e: React.MouseEvent) => {
+      handleClick(e);
+      // Call original onClick if it exists
+      childElement.props.onClick?.(e);
+    },
+    "data-testid": dataTestId ? `${dataTestId}-trigger` : undefined,
+  });
 
-    return (
-      <div ref={wrapperRef} className={className}>
-        <StyledTooltip
-          ref={ref}
-          customVariant={variant}
-          customSize={size}
-          glow={glow}
-          pulse={pulse}
-          title={tooltipContent}
-          open={isPinned ? isControlledOpen : hover.open}
-          onOpen={hover.onOpen}
-          onClose={hover.onClose}
-          enterDelay={isPinned ? 0 : 100}
-          leaveDelay={0}
-          disableHoverListener={isPinned}
-          disableFocusListener={isPinned}
-          disableTouchListener={isPinned}
-          slotProps={{
-            tooltip: {
-              sx: { maxWidth: tooltipCap(maxWidth) },
-              role: 'tooltip',
-              ...(dataTestId && { 'data-testid': `${dataTestId}-content` }),
-            },
-          }}
-          {...props}
-        >
-          {childWithProps}
-        </StyledTooltip>
-      </div>
-    );
-  },
-);
+  return (
+    <div ref={wrapperRef} className={className}>
+      <MuiTooltip
+        ref={ref}
+        title={tooltipContent}
+        open={isPinned ? isControlledOpen : hover.open}
+        onOpen={hover.onOpen}
+        onClose={hover.onClose}
+        enterDelay={isPinned ? 0 : 100}
+        leaveDelay={0}
+        disableHoverListener={isPinned}
+        disableFocusListener={isPinned}
+        disableTouchListener={isPinned}
+        slotProps={{
+          tooltip: {
+            sx: bubbleSx(variant, size, glow, pulse, maxWidth),
+            role: "tooltip",
+            ...(dataTestId && { "data-testid": `${dataTestId}-content` }),
+          },
+          arrow: {
+            sx: (theme: Theme) => ({ color: arrowColor(theme, variant) }),
+          },
+        }}
+        {...props}
+      >
+        {childWithProps}
+      </MuiTooltip>
+    </div>
+  );
+});
 
-InteractiveTooltip.displayName = 'InteractiveTooltip';
+InteractiveTooltip.displayName = "InteractiveTooltip";

package/src/components/data-display/Tooltip/Tooltip.tsx

@@ -1,11 +1,11 @@
-import MuiTooltip from '@mui/material/Tooltip/index.js';
-import { alpha, keyframes, styled } from '@mui/material/styles/index.js';
-import type { CSSObject, Theme } from '@mui/material/styles/index.js';
-import React from 'react';
+import MuiTooltip from "@mui/material/Tooltip/index.js";
+import { alpha, keyframes } from "@mui/material/styles/index.js";
+import type { CSSObject, Theme } from "@mui/material/styles/index.js";
+import React from "react";
 
-import type { TooltipProps } from './Tooltip.types';
-import { absoluteInk, neutralTones } from '../../../tokens/ink';
-import { rem, rems, sxRem } from '../../../tokens/relative';
+import type { TooltipProps } from "./Tooltip.types";
+import { absoluteInk, neutralTones } from "../../../tokens/ink";
+import { rem, rems, sxRem } from "../../../tokens/relative";
 
 // Define pulse animation
 const pulseAnimation = keyframes`
@@ -36,24 +36,24 @@ const getSizeStyles = (
 
 const variantStyles = (theme: Theme, variant?: string): CSSObject => {
   switch (variant) {
-    case 'default':
+    case "default":
       return {
-        backgroundColor: alpha(neutralTones(theme).inverseSurface, 0.9),
+        backgroundColor: neutralTones(theme).inverseSurface,
         color: absoluteInk(theme).white,
       };
-    case 'dark':
+    case "dark":
       return {
         backgroundColor: neutralTones(theme).inverseSurface,
         color: absoluteInk(theme).white,
       };
-    case 'light':
+    case "light":
       return {
         backgroundColor: absoluteInk(theme).white,
         color: theme.palette.text.primary,
         border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
         boxShadow: theme.shadows[4],
       };
-    case 'glass':
+    case "glass":
       return {
         backgroundColor: alpha(theme.palette.background.paper, 0.1),
         backdropFilter: `blur(${rem(theme, 20)})`,
@@ -67,10 +67,14 @@ const variantStyles = (theme: Theme, variant?: string): CSSObject => {
 
 // glow and pulse are independent flags. The three combinations used to be spelled
 // out one by one, but each is just the union of whichever flags are set.
-const emphasisStyles = (theme: Theme, glow?: boolean, pulse?: boolean): CSSObject => ({
+const emphasisStyles = (
+  theme: Theme,
+  glow?: boolean,
+  pulse?: boolean,
+): CSSObject => ({
   ...(glow && {
     boxShadow: `${rems(theme, 0, 0, 15, 3)} ${alpha(theme.palette.primary.main, 0.4)} !important`,
-    filter: 'brightness(1.05)',
+    filter: "brightness(1.05)",
   }),
   ...(pulse && {
     animation: `${pulseAnimation} 2s infinite`,
@@ -79,46 +83,48 @@ const emphasisStyles = (theme: Theme, glow?: boolean, pulse?: boolean): CSSObjec
 
 const arrowColor = (theme: Theme, variant?: string): string => {
   switch (variant) {
-    case 'light':
+    case "light":
       return absoluteInk(theme).white;
-    case 'glass':
+    case "glass":
       return alpha(theme.palette.background.paper, 0.1);
-    case 'dark':
+    case "dark":
       return neutralTones(theme).inverseSurface;
     default:
-      return alpha(neutralTones(theme).inverseSurface, 0.9);
+      return neutralTones(theme).inverseSurface;
   }
 };
 
-const StyledTooltip = styled(MuiTooltip, {
-  shouldForwardProp: (prop) =>
-    !['customVariant', 'customSize', 'glow', 'pulse'].includes(prop as string),
-})<{
-  customVariant?: string;
-  customSize?: string;
-  glow?: boolean;
-  pulse?: boolean;
-}>(({ theme, customVariant, customSize, glow, pulse }) => {
-  const sizeStyles = getSizeStyles(customSize);
-
-  return {
-    '& .MuiTooltip-tooltip': {
+/**
+ * The bubble's own look, applied to the BUBBLE (FUT-3093).
+ *
+ * It used to sit on a `styled(MuiTooltip)` root as `& .MuiTooltip-tooltip`, but
+ * MUI renders the bubble in a portal, outside that root — so none of it ever
+ * reached the screen, and every tooltip wore MUI's see-through grey instead of
+ * the variant it asked for. `slotProps.tooltip.sx` lands on the bubble itself.
+ * No `overflow: hidden`: now that it applies, it would clip an `arrow`.
+ */
+const bubbleSx =
+  (
+    variant: string,
+    size: string,
+    glow: boolean,
+    pulse: boolean,
+    maxWidth: number | undefined,
+  ) =>
+  (theme: Theme): CSSObject => {
+    const sizeStyles = getSizeStyles(size);
+    return {
       borderRadius: theme.spacing(1),
       fontSize: sizeStyles.fontSize(theme),
       padding: sizeStyles.padding(theme),
       fontWeight: 500,
-      transition: 'all 0.3s ease',
-      position: 'relative',
-      overflow: 'hidden',
-      ...variantStyles(theme, customVariant),
+      transition: "all 0.3s ease",
+      position: "relative",
+      maxWidth: tooltipCap(maxWidth)(theme),
+      ...variantStyles(theme, variant),
       ...emphasisStyles(theme, glow, pulse),
-    },
-
-    '& .MuiTooltip-arrow': {
-      color: arrowColor(theme, customVariant),
-    },
+    };
   };
-});
 
 /**
  * The tooltip's cap: 300 design px unless the caller says otherwise. `sx` has
@@ -134,8 +140,8 @@ const tooltipCap =
 export const Tooltip = React.forwardRef<HTMLDivElement, TooltipProps>(
   (
     {
-      variant = 'default',
-      size = 'md',
+      variant = "default",
+      size = "md",
       glow = false,
       pulse = false,
       maxWidth,
@@ -146,18 +152,17 @@ export const Tooltip = React.forwardRef<HTMLDivElement, TooltipProps>(
     ref,
   ) => {
     const childWithTestId = dataTestId
-      ? React.cloneElement(children as React.ReactElement<{ 'data-testid'?: string }>, {
-          'data-testid': `${dataTestId}-trigger`,
-        })
+      ? React.cloneElement(
+          children as React.ReactElement<{ "data-testid"?: string }>,
+          {
+            "data-testid": `${dataTestId}-trigger`,
+          },
+        )
       : children;
 
     return (
-      <StyledTooltip
+      <MuiTooltip
         ref={ref}
-        customVariant={variant}
-        customSize={size}
-        glow={glow}
-        pulse={pulse}
         enterDelay={0}
         leaveDelay={0}
         disableHoverListener={false}
@@ -165,17 +170,20 @@ export const Tooltip = React.forwardRef<HTMLDivElement, TooltipProps>(
         disableTouchListener={false}
         slotProps={{
           tooltip: {
-            sx: { maxWidth: tooltipCap(maxWidth) },
-            role: 'tooltip',
-            ...(dataTestId && { 'data-testid': `${dataTestId}-content` }),
+            sx: bubbleSx(variant, size, glow, pulse, maxWidth),
+            role: "tooltip",
+            ...(dataTestId && { "data-testid": `${dataTestId}-content` }),
+          },
+          arrow: {
+            sx: (theme: Theme) => ({ color: arrowColor(theme, variant) }),
           },
         }}
         {...props}
       >
         {childWithTestId}
-      </StyledTooltip>
+      </MuiTooltip>
     );
   },
 );
 
-Tooltip.displayName = 'Tooltip';
+Tooltip.displayName = "Tooltip";

package/src/tokens/color.ts

@@ -157,6 +157,27 @@ export function lighten(color: string, coefficient: number): string {
   return recomposeColor({ type: decomposed.type, values });
 }
 
+/**
+ * `overlay` laid over `background` at `opacity` (0 to 1), flattened to one
+ * OPAQUE `rgb()` — the colour a translucent wash actually shows, as a colour
+ * that stays that colour whatever it is later painted on.
+ *
+ * MUI's `blend` at its default gamma, rounding each channel as it does. One
+ * deliberate difference: an `hsl()` input is converted to rgb first, where
+ * MUI's reads hue, saturation and lightness as if they were red, green and
+ * blue. Any alpha on either input is ignored, as in MUI.
+ */
+export function blend(background: string, overlay: string, opacity: number): string {
+  const rgbOf = (color: string): number[] =>
+    decomposeColor(color.startsWith('hsl') ? hslToRgb(color) : color).values;
+  const base = rgbOf(background);
+  const top = rgbOf(overlay);
+  const amount = clamp(opacity);
+  const channel = (index: number): number =>
+    Math.round((base[index] ?? 0) * (1 - amount) + (top[index] ?? 0) * amount);
+  return recomposeColor({ type: 'rgb', values: [channel(0), channel(1), channel(2)] });
+}
+
 /** Darken a light colour or lighten a dark one, by `coefficient`. */
 export function emphasize(color: string, coefficient = 0.15): string {
   return getLuminance(color) > 0.5 ? darken(color, coefficient) : lighten(color, coefficient);

package/src/tokens/ink.ts

@@ -29,7 +29,10 @@ import {
  * - the NEUTRAL tones, over the grey ramp, named by what they do rather than by
  *   their step, so a host that re-greys the ramp re-greys every one;
  * - `uiInk(theme)`, the colours with no palette role at all (`./ink.core.ts`),
- *   which a host can replace through `theme.uiInk`.
+ *   which a host can replace through `theme.uiInk`;
+ * - `surfaces(theme)` and `softSignal(theme, signal)` (`./surfaces.ts`), the
+ *   grounds a board and its cards sit on and a signal's soft background,
+ *   which a host can replace through `theme.uiSurfaces` / `theme.uiSoftSignal`.
  *
  * Every default is the value the component drew before, so moving a component
  * onto these changed nothing on screen. `scripts/ui-tokens-gate.mjs` refuses a

package/src/tokens/scales.ts

@@ -19,6 +19,8 @@ export { rem, rems, remPx, resetRootFontCache, sxRem } from './relative';
 // Every colour by role (FUT-2593): ink roles, neutral tones, the named sets.
 export * from './ink';
 export * from './ink.core';
+// The surface and soft-signal roles (FUT-3098): `surfaces`, `softSignal`.
+export * from './surfaces';
 export { DEFAULT_FIELD_RADIUS, fieldRadius, fieldRadiusOverrides, fieldRadiusPx, fieldRootStyles } from './field-radius';
 export {
   asFieldSize,

package/src/tokens/surfaces.ts

@@ -0,0 +1,108 @@
+import type { Theme } from '@mui/material/styles/index.js';
+
+import { blend } from './color';
+
+/**
+ * THE SURFACE AND SOFT-SIGNAL ROLES (FUT-3098, under FUT-2585).
+ *
+ * Three colours a component or a host needs and the palette has no role for,
+ * so until now each caller computed its own:
+ *
+ * - a ground BELOW the page, for a board that holds cards (a floor plan, a
+ *   kanban), so a card on it reads as nearer;
+ * - the border a card draws on that ground — `divider` is often the very tone
+ *   the sunken ground wants, and a border in the ground's own colour vanishes;
+ * - a soft background per signal. Components tint `palette.<signal>.main` by
+ *   hand at whatever opacity each author chose (0.05, 0.08, 0.1…), so no two
+ *   of them agree by design.
+ *
+ * Each role reads the theme with a host override layered on top, in the shape
+ * `uiInk` uses (`./ink.ts`): `theme.uiSurfaces` and `theme.uiSoftSignal`. A
+ * host builds one theme per mode, so it states each mode's values on that
+ * mode's theme; with nothing stated, every role falls back to a formula over
+ * the mode's own palette, and dark mode therefore resolves its own values.
+ *
+ * **Every default leaves a host that sets nothing unchanged.** `raised` is the
+ * card MUI already paints (`background.paper`), `sunken` is the page itself
+ * (`background.default` — no step; a host opts in to a darker ground by
+ * stating one), and `borderOnSunken` is `divider`.
+ */
+
+/** A signal with a soft background: the four MUI semantic colours. */
+export type SoftSignal = 'success' | 'warning' | 'error' | 'info';
+
+/** Every signal {@link softSignal} answers for, in a stable order. */
+export const SOFT_SIGNALS: readonly SoftSignal[] = ['success', 'warning', 'error', 'info'];
+
+/**
+ * How much of a signal's `main` its soft background carries by default, over
+ * `background.paper` — the value the most careful of the hand tints already
+ * used (`PasswordStrength`'s success wash).
+ */
+export const SOFT_SIGNAL_OPACITY = 0.08;
+
+/**
+ * The three surface roles.
+ *
+ * **Not `neutralTones(theme).raised`.** That one is a fixed step on the grey
+ * ramp (800) — a dark panel on a light UI, whatever the mode. `raised` here is
+ * the mode's own card surface, the one that sits nearer than `sunken`.
+ */
+export interface UiSurfaces {
+  /** The ground below the page: a board, a floor, a lane that holds cards. */
+  sunken: string;
+  /** A card or panel lifted above the ground. */
+  raised: string;
+  /** The border of a `raised` card sitting on the `sunken` ground. */
+  borderOnSunken: string;
+}
+
+declare module '@mui/material/styles' {
+  interface Theme {
+    /** Surface roles the host states. See `@12-apps/ui/tokens`' `surfaces`. */
+    uiSurfaces?: Partial<UiSurfaces>;
+    /** Soft signal backgrounds the host states. See `@12-apps/ui/tokens`' `softSignal`. */
+    uiSoftSignal?: Partial<Record<SoftSignal, string>>;
+  }
+  interface ThemeOptions {
+    /**
+     * Replace any of the surface roles, per key; a key left out keeps its
+     * default. One theme is one mode, so a host states each mode's values on
+     * that mode's theme.
+     */
+    uiSurfaces?: Partial<UiSurfaces>;
+    /**
+     * Replace the soft background of any signal, per key. Each value must be
+     * OPAQUE: a translucent wash takes on whatever sits under it (FUT-854).
+     */
+    uiSoftSignal?: Partial<Record<SoftSignal, string>>;
+  }
+}
+
+/** The surface roles, with the host's `theme.uiSurfaces` layered over the defaults. */
+export function surfaces(theme: Theme): UiSurfaces {
+  const { background, divider } = theme.palette;
+  const stated = theme.uiSurfaces;
+  // `??` per key rather than a spread, so a key a host passes as `undefined`
+  // (a conditional in its theme file) keeps the default instead of erasing it.
+  return {
+    sunken: stated?.sunken ?? background.default,
+    raised: stated?.raised ?? background.paper,
+    borderOnSunken: stated?.borderOnSunken ?? divider,
+  };
+}
+
+/**
+ * The soft background for a signal: the host's `theme.uiSoftSignal[signal]`
+ * when stated, otherwise the signal's `main` at {@link SOFT_SIGNAL_OPACITY}
+ * composited over `background.paper` into one OPAQUE colour.
+ *
+ * Opaque on purpose. A translucent `alpha(main, 0.08)` is a different colour
+ * on every surface it lands on, and its contrast with the signal's own text
+ * cannot be known in advance; a composited value is the same colour anywhere.
+ */
+export function softSignal(theme: Theme, signal: SoftSignal): string {
+  const stated = theme.uiSoftSignal?.[signal];
+  if (stated) return stated;
+  return blend(theme.palette.background.paper, theme.palette[signal].main, SOFT_SIGNAL_OPACITY);
+}