@workday/canvas-kit-react 16.0.0-alpha.0499-next.0 → 16.0.0-alpha.0500-next.0

package/common/lib/theming/sanaTheme.ts

@@ -0,0 +1,133 @@
+/**
+ * Sana Canvas theme presets.
+ *
+ * Sana is a distinct theme from classic Canvas — not a delta on `defaultCanvasTheme`.
+ * Full visual treatment (fonts, shapes, system surfaces) comes from global CSS:
+ * import `@workday/canvas-tokens-web/css/sana/_variables.css` and set
+ * `data-theme="sana-canvas"` on `<html>`.
+ *
+ * These JS presets reference Sana brand CSS variables so `CanvasProvider` can forward
+ * them to popup containers (menus, selects, modals). Keep in sync with
+ * `@workday/canvas-tokens-web/css/sana/_variables.css`.
+ *
+ * | Preset | Use case |
+ * |--------|----------|
+ * | `sanaCanvasNumericalTheme` | Numerical `brand` shape for popup forwarding |
+ * | `sanaCanvasProviderTheme` | Same — pass to root `CanvasProvider` when `<html>` is unavailable |
+ */
+import {base, brand} from '@workday/canvas-tokens-web';
+
+import type {CanvasNumericalBrandTheme} from './types';
+
+/** Reference a canvas-tokens CSS variable (resolves under `[data-theme="sana-canvas"]`). */
+const varRef = (token: string) => `var(${token})`;
+
+/**
+ * Sana extends the neutral ramp with steps not yet exported from canvas-tokens-web JS.
+ * Defined in `@workday/canvas-tokens-web/css/sana/_variables.css`.
+ */
+const sanaBrandNeutral = {
+  '150': '--cnvs-brand-neutral-150',
+  '850': '--cnvs-brand-neutral-850',
+  A150: '--cnvs-brand-neutral-a150',
+} as const;
+
+/**
+ * Sana Canvas brand tokens for scoped `CanvasProvider` / popup forwarding.
+ * Values are `var()` references to Sana brand variables — not merged from `defaultCanvasTheme`.
+ */
+export const sanaCanvasNumericalTheme: CanvasNumericalBrandTheme = {
+  // Explicit brand vars only — multi-key ramps write 1:1; no system shortcut bundles run.
+  themeScope: 'brand',
+  brand: {
+    action: {
+      base: varRef(brand.neutral975),
+      dark: varRef(brand.neutral950),
+      darkest: varRef(brand.neutral900),
+      accent: varRef(base.neutral0),
+      lightest: varRef(brand.neutral25),
+      lighter: varRef(brand.neutral50),
+      light: varRef(brand.neutral200),
+    },
+    neutral: {
+      '25': varRef(brand.neutral25),
+      '50': varRef(brand.neutral50),
+      '100': varRef(brand.neutral100),
+      '150': varRef(sanaBrandNeutral['150']),
+      '200': varRef(brand.neutral200),
+      '300': varRef(brand.neutral300),
+      '400': varRef(brand.neutral400),
+      '500': varRef(brand.neutral500),
+      '600': varRef(brand.neutral600),
+      '700': varRef(brand.neutral700),
+      '800': varRef(brand.neutral800),
+      '850': varRef(sanaBrandNeutral['850']),
+      '900': varRef(brand.neutral900),
+      '950': varRef(brand.neutral950),
+      '975': varRef(brand.neutral975),
+      A25: varRef(brand.neutralA25),
+      A50: varRef(brand.neutralA50),
+      A100: varRef(brand.neutralA100),
+      A150: varRef(sanaBrandNeutral.A150),
+      A200: varRef(brand.neutralA200),
+    },
+    primary: {
+      '500': varRef(brand.primary500),
+      '600': varRef(brand.primary600),
+      '700': varRef(brand.primary700),
+      A25: varRef(brand.primaryA25),
+      A50: varRef(brand.primaryA50),
+      A100: varRef(brand.primaryA100),
+    },
+    critical: {
+      '500': varRef(brand.critical500),
+      '600': varRef(brand.critical600),
+      '700': varRef(brand.critical700),
+      A25: varRef(brand.criticalA25),
+      A50: varRef(brand.criticalA50),
+    },
+    caution: {
+      '400': varRef(brand.caution400),
+      '500': varRef(brand.caution500),
+      A25: varRef(brand.cautionA25),
+      A50: varRef(brand.cautionA50),
+    },
+    positive: {
+      '600': varRef(brand.positive600),
+      '800': varRef(brand.positive800),
+      A25: varRef(brand.positiveA25),
+      A50: varRef(brand.positiveA50),
+    },
+  },
+  selected: {
+    fg: varRef(brand.neutralA900),
+    surface: varRef(brand.neutralA100),
+  },
+};
+
+/**
+ * Pass to root `CanvasProvider` to forward Sana brand CSS variables onto popup containers
+ * (menus, selects, modals, tooltips).
+ *
+ * **When to use it**
+ * - **Required** when you cannot set `data-theme="sana-canvas"` on `<html>` (embedded apps,
+ *   microfrontends, third-party shells). Popups portal to `document.body` and will not inherit
+ *   a nested `data-theme` — this preset copies Sana brand vars onto the popup stack container.
+ * - Also useful in tests without global Sana CSS, or custom popup hosts outside normal cascade.
+ *
+ * **When you can skip it**
+ * - Prefer setting `data-theme="sana-canvas"` on `<html>` with Sana CSS imported. Popups then
+ *   inherit brand variables from the document and no `theme` prop is needed.
+ *
+ * @example
+ * ```tsx
+ * // Preferred — control <html>
+ * import '@workday/canvas-tokens-web/css/sana/_variables.css';
+ * // <html data-theme="sana-canvas">
+ * <CanvasProvider><App /></CanvasProvider>
+ *
+ * // No access to <html> — required for popup parity
+ * <CanvasProvider theme={sanaCanvasProviderTheme}><App /></CanvasProvider>
+ * ```
+ */
+export const sanaCanvasProviderTheme = sanaCanvasNumericalTheme;

package/common/lib/theming/types.ts

@@ -281,3 +281,295 @@ declare module '@emotion/react' {
  * @deprecated ⚠️ `EmotionCanvasTheme` is deprecated. In previous versions of Canvas Kit, we allowed teams to pass a theme object, this supported [Emotion's theming](https://emotion.sh/docs/theming). Now that we're shifting to a global theming approach based on CSS variables, we advise to no longer using the theme prop. For more information, view our [Theming Docs](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs#-preferred-approach-v14).
  */
 export type EmotionCanvasTheme = {canvas: CanvasTheme};
+
+/**
+ * Numerical brand ramp keys. Each key maps 1:1 to a `--cnvs-brand-{family}-{key}` CSS variable.
+ *
+ * Common keys:
+ * - `'600'` — main accent / button fill / default brand fg
+ * - `'700'` — strong fg / selected text (when not using `selected.fg`)
+ * - `'500'` — focus rings and border primary (independent of `'600'`)
+ * - `'A50'` — selected surface tint (when not using `selected.surface`)
+ * - `'25'` / `'A25'` — subtle brand surfaces
+ *
+ * Neutral-only Sana steps (`'150'`, `'850'`, `'A150'`) live on {@link CanvasNeutralBrandRamp}.
+ */
+export type CanvasBrandRamp = Partial<
+  Record<
+    | '25'
+    | '50'
+    | '100'
+    | '200'
+    | '300'
+    | '400'
+    | '500'
+    | '600'
+    | '700'
+    | '800'
+    | '900'
+    | '950'
+    | '975'
+    | 'A25'
+    | 'A50'
+    | 'A100'
+    | 'A200',
+    string
+  >
+>;
+
+/**
+ * Neutral brand ramp — includes Sana-only steps (`150` / `850` / `A150`) that are not
+ * exported for primary/critical/caution/positive families.
+ */
+export type CanvasNeutralBrandRamp = CanvasBrandRamp &
+  Partial<Record<'150' | '850' | 'A150', string>>;
+
+/** Semantic keys for `brand.action.*` CSS variables (PrimaryButton, etc.). */
+export type CanvasActionBrandRamp = Partial<
+  Record<
+    'base' | 'lightest' | 'lighter' | 'light' | 'dark' | 'darkest' | 'darker' | 'accent',
+    string
+  >
+>;
+
+/**
+ * Controls how partial theme input is expanded.
+ *
+ * - `'brand'` (default): predictable, design-aligned behavior. Setting only
+ *   `brand.primary['600']` themes PrimaryButton and selected list/menu
+ *   states. Other keys write only their CSS variable — no auto-generated ramps.
+ * - `'full'`: legacy behavior for the deprecated `canvas.palette` shape — auto-fills
+ *   lightest→darkest via `shiftColor` and forwards to many `system.color.brand.*`
+ *   tokens. On the numerical `brand` shape, `'full'` disables the primary shortcut
+ *   and writes each ramp key literally.
+ */
+export type CanvasThemingScope = 'brand' | 'full';
+
+/**
+ * Preferred theme input for `CanvasProvider`. Each value maps directly to brand CSS
+ * variables unless noted as a shortcut below.
+ *
+ * @example Minimal — brand buttons + selected states only
+ * ```tsx
+ * <CanvasProvider theme={{brand: {primary: {'600': base.magenta600}}}} />
+ * ```
+ *
+ * @example Explicit — focus independent of primary
+ * ```tsx
+ * <CanvasProvider theme={{
+ *   brand: {primary: {'600': base.red600, '500': base.blue500}},
+ *   selected: {fg: base.red700, surface: base.redA50},
+ * }} />
+ * ```
+ *
+ * @see sanaCanvasProviderTheme when `<html>` is unavailable and popups need Sana brand forwarding
+ */
+export interface CanvasNumericalBrandTheme {
+  brand?: {
+    /**
+     * Primary brand ramp (`--cnvs-brand-primary-*`).
+     *
+     * **Shortcut (brand scope only):** when `'600'` is the only key under `primary`,
+     * also sets:
+     * - `PrimaryButton` — `brand.action.base`, `accent.primary`, `accent.action`
+     * - Selected `Menu.Item` — `system.color.brand.fg.selected`, `surface.selected`
+     *
+     * Does **not** set focus rings — use `'500'` or `canvas.palette.common.focusOutline`.
+     *
+     * | Key | CSS variable | Typical consumers |
+     * |-----|--------------|-------------------|
+     * | `'600'` | `--cnvs-brand-primary-600` | PrimaryButton, brand links, accent.primary |
+     * | `'700'` | `--cnvs-brand-primary-700` | Strong primary fg, selected text |
+     * | `'500'` | `--cnvs-brand-primary-500` | Focus rings, border primary |
+     * | `'A50'` | `--cnvs-brand-primary-A50` | Selected/hover surfaces |
+     */
+    primary?: CanvasBrandRamp;
+
+    /**
+     * Button-specific ramp (`--cnvs-brand-action-*`). PrimaryButton reads
+     * these **before** `brand.primary`.
+     *
+     * | Key | Typical consumers |
+     * |-----|-------------------|
+     * | `base` | PrimaryButton background |
+     * | `dark` / `darkest` | PrimaryButton hover / pressed |
+     * | `accent` | PrimaryButton label color |
+     */
+    action?: CanvasActionBrandRamp;
+
+    /**
+     * Critical/error ramp (`--cnvs-brand-critical-*`).
+     *
+     * | Key | Typical consumers |
+     * |-----|-------------------|
+     * | `'600'` | TextInput error, DeleteButton, critical fg |
+     * | `'500'` | Critical focus ring, error border |
+     * | `'A25'` / `'A50'` | Error surface tints |
+     */
+    critical?: CanvasBrandRamp;
+
+    /**
+     * Caution/warning ramp (`--cnvs-brand-caution-*`).
+     *
+     * | Key | Typical consumers |
+     * |-----|-------------------|
+     * | `'400'` | Caution accent, TextInput caution |
+     * | `'500'` | Caution focus outer, caution border |
+     * | `'A25'` / `'A50'` | Caution surface tints |
+     */
+    caution?: CanvasBrandRamp;
+
+    /**
+     * Positive/success ramp (`--cnvs-brand-positive-*`).
+     *
+     * | Key | Typical consumers |
+     * |-----|-------------------|
+     * | `'600'` | Checkbox/Radio checked, success fg |
+     * | `'A25'` / `'A50'` | Success surface tints |
+     */
+    positive?: CanvasBrandRamp;
+
+    /**
+     * Neutral brand ramp (`--cnvs-brand-neutral-*`). Sana Canvas uses `base.neutral*`
+     * instead of legacy `base.slate*` — see {@link sanaCanvasNumericalTheme}.
+     *
+     * Affects brand-neutral text, borders, and surfaces where components reference
+     * `brand.neutral.*` or `system.color.brand` tokens tied to neutral.
+     */
+    neutral?: CanvasNeutralBrandRamp;
+  };
+
+  /**
+   * Selected-state shortcuts. Prefer these over indirect `brand.primary['700']` /
+   * `brand.primary.A50` when customizing list/menu selection.
+   *
+   * | Key | CSS variable | Typical consumers |
+   * |-----|--------------|-------------------|
+   * | `fg` | `--cnvs-sys-color-brand-fg-selected` | Menu.Item, SegmentedControl selected text |
+   * | `surface` | `--cnvs-sys-color-brand-surface-selected` | Menu.Item, list selected background |
+   */
+  selected?: {
+    /** Selected text/icon color */
+    fg?: string;
+    /** Selected row/chip background */
+    surface?: string;
+  };
+
+  /**
+   * Escape hatch for `system.color.brand.*` tokens not covered by `brand` ramps.
+   * Keys mirror the token path, e.g. `{color: {brand: {focus: {primary: '#00f'}}}}`.
+   */
+  system?: {
+    color?: {
+      brand?: Record<string, unknown>;
+    };
+  };
+
+  /** Text direction for the provider subtree. */
+  direction?: ContentDirection;
+
+  /**
+   * @default 'brand'
+   * @see CanvasThemingScope
+   */
+  themeScope?: CanvasThemingScope;
+}
+
+/**
+ * Theme input accepted by {@link CanvasProvider}.
+ * - Numerical `brand` shape (preferred)
+ * - Deprecated `canvas.palette` shape (legacy)
+ */
+export type CanvasProviderTheme =
+  | (PartialEmotionCanvasTheme & {themeScope?: CanvasThemingScope})
+  | CanvasNumericalBrandTheme;
+
+export function isNumericalTheme(
+  theme: CanvasProviderTheme | undefined
+): theme is CanvasNumericalBrandTheme {
+  if (!theme) {
+    return false;
+  }
+  if ('canvas' in theme) {
+    return false;
+  }
+  // `direction` / `themeScope` alone are valid numerical themes (e.g. RTL-only).
+  return (
+    'brand' in theme ||
+    'system' in theme ||
+    'selected' in theme ||
+    'direction' in theme ||
+    'themeScope' in theme
+  );
+}
+
+const EXTENDED_RAMP_KEYS = new Set([
+  '25',
+  '50',
+  '100',
+  '200',
+  '300',
+  '400',
+  '500',
+  '600',
+  '700',
+  '800',
+  '900',
+  '950',
+  '975',
+  'A25',
+  'A50',
+  'A100',
+  'A200',
+  'lightest',
+  'lighter',
+  'light',
+  'main',
+  'dark',
+  'darkest',
+  'contrast',
+]);
+
+export function resolveThemingScope(theme: CanvasProviderTheme | undefined): CanvasThemingScope {
+  if (!theme) {
+    return 'brand';
+  }
+  if (theme.themeScope) {
+    return theme.themeScope;
+  }
+
+  if (isNumericalTheme(theme)) {
+    return theme.themeScope ?? 'brand';
+  }
+
+  const palette = theme.canvas?.palette;
+  if (!palette) {
+    return 'brand';
+  }
+
+  if (palette.common && Object.keys(palette.common).length > 0) {
+    const commonOnlyFocus =
+      Object.keys(palette.common).length === 1 && palette.common.focusOutline != null;
+    if (!commonOnlyFocus) {
+      return 'full';
+    }
+  }
+
+  for (const color of ['primary', 'error', 'alert', 'success', 'neutral'] as const) {
+    const colorPalette = palette[color];
+    if (!colorPalette) {
+      continue;
+    }
+    for (const key of Object.keys(colorPalette)) {
+      // `main` alone uses brand-scope bundles for every semantic palette color.
+      if (key === 'main') {
+        continue;
+      }
+      if (EXTENDED_RAMP_KEYS.has(key)) {
+        return 'full';
+      }
+    }
+  }
+
+  return 'brand';
+}