@womp/kookie-ui 0.3.25 → 0.4.0

package/src/helpers/font-config.ts

@@ -1,194 +1,176 @@
 /**
- * Font configuration utilities for Kookie UI
+ * Runtime font configuration for Kookie UI.
  *
- * These utilities help users configure custom fonts through CSS variables
- * and provide type-safe font configuration options.
+ * This is a thin, typed wrapper over the CSS tokens in `styles/tokens/font-family.css` —
+ * it writes the same variables you would write by hand, and nothing else. Prefer plain CSS
+ * where you can; reach for this when the stacks are only known at runtime (a theme editor,
+ * a user-selectable typeface).
+ *
+ * Two tiers, matching the CSS:
+ *
+ *   - `stacks` — which typefaces exist: `sans`, `mono`, `serif`. Written to `:root`.
+ *   - `roles`  — which stack each role uses: `body`, `heading`, `code`, `strong`, `em`,
+ *                `quote`. Written to the theme element, since roles are per-theme.
  */
 
-/**
- * Font family configuration interface
- */
-export interface FontConfig {
-  /** Sans-serif font stack for fontFamily="sans" */
+/** Tier 1 — the typefaces available to the theme. */
+export interface FontStacks {
+  /** Sans-serif stack. Backs `font="sans"` and, by default, body text. */
   sans?: string;
-  /** Monospace font stack for fontFamily="mono" */
+  /** Monospace stack. Backs `font="mono"` and `Code`. */
   mono?: string;
-  /** Serif font stack for fontFamily="serif" */
+  /** Serif stack. Backs `font="serif"`, `Em` and `Quote`. */
   serif?: string;
-  /** Base Inter font replacement */
-  inter?: string;
-  /** Base JetBrains Mono font replacement */
-  jetbrainsMono?: string;
-  /** Base Playfair Display font replacement */
-  playfairDisplay?: string;
 }
 
-/**
- * CSS variable names used by Kookie UI for fonts
- */
-export const FONT_CSS_VARIABLES = {
+/** Tier 2 — which stack each role of text uses. */
+export interface FontRoles {
+  /** Body text: `Text`, inputs, buttons, and anything that does not opt out. */
+  body?: string;
+  /** `Heading`. Follows `body` when left unset. */
+  heading?: string;
+  /** `Code`. */
+  code?: string;
+  /** `Strong`. */
+  strong?: string;
+  /** `Em`. */
+  em?: string;
+  /** `Quote`. */
+  quote?: string;
+}
+
+export interface FontConfig {
+  stacks?: FontStacks;
+  roles?: FontRoles;
+}
+
+/** CSS custom properties backing each stack. Declared on `:root`. */
+export const FONT_STACK_VARIABLES = {
   sans: '--font-sans',
   mono: '--font-mono',
   serif: '--font-serif',
-  inter: '--font-inter',
-  jetbrainsMono: '--font-jetbrains-mono',
-  playfairDisplay: '--font-playfair-display',
-  defaultFamily: '--default-font-family',
-  headingFamily: '--heading-font-family',
-  strongFamily: '--strong-font-family',
-  codeFamily: '--code-font-family',
-} as const;
+} as const satisfies Record<keyof FontStacks, `--font-${string}`>;
+
+/** CSS custom properties backing each role. Declared on the theme element. */
+export const FONT_ROLE_VARIABLES = {
+  body: '--font-body',
+  heading: '--font-heading',
+  code: '--font-code',
+  strong: '--font-strong',
+  em: '--font-em',
+  quote: '--font-quote',
+} as const satisfies Record<keyof FontRoles, `--font-${string}`>;
 
 /**
- * Popular font stacks for common use cases
+ * Ready-made stacks, each ending in a system fallback.
+ *
+ * The webfont entries assume the face is already loaded — via
+ * `import '@womp/kookie-ui/fonts.css'`, `next/font`, or your own `@font-face`.
+ * Kookie's core stylesheet deliberately loads none.
  */
 export const FONT_STACKS = {
-  // Sans-serif options
-  inter: "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
-  system: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif",
-  poppins: "'Poppins', 'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
-  openSans: "'Open Sans', 'Inter', -apple-system, BlinkMacSystemFont, sans-serif",
-
-  // Monospace options
-  jetbrainsMono: "'JetBrains Mono', 'Fira Code', 'Consolas', 'Liberation Mono', monospace",
-  firaCode: "'Fira Code', 'JetBrains Mono', 'Consolas', 'Liberation Mono', monospace",
-  sourceCodePro: "'Source Code Pro', 'JetBrains Mono', 'Consolas', monospace",
-  systemMono: "'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', 'Courier New', monospace",
-
-  // Serif options
-  playfair: "'Playfair Display', 'Times New Roman', 'Times', 'Georgia', 'Cambria', serif",
-  times: "'Times New Roman', 'Times', 'Georgia', 'Cambria', serif",
+  // Sans
+  system: "-apple-system, BlinkMacSystemFont, 'Segoe UI (Custom)', Roboto, 'Helvetica Neue', system-ui, sans-serif",
+  inter: "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI (Custom)', Roboto, system-ui, sans-serif",
+  poppins: "'Poppins', -apple-system, BlinkMacSystemFont, system-ui, sans-serif",
+  openSans: "'Open Sans (Custom)', -apple-system, BlinkMacSystemFont, system-ui, sans-serif",
+
+  // Mono
+  systemMono: "'Menlo', 'Consolas (Custom)', 'Bitstream Vera Sans Mono', monospace",
+  jetbrainsMono: "'JetBrains Mono', 'Menlo', 'Consolas (Custom)', monospace",
+  firaCode: "'Fira Code', 'Menlo', 'Consolas (Custom)', monospace",
+  sourceCodePro: "'Source Code Pro', 'Menlo', 'Consolas (Custom)', monospace",
+
+  // Serif
+  systemSerif: "'Times New Roman', 'Times', 'Georgia', 'Cambria', serif",
+  playfair: "'Playfair Display', 'Times New Roman', 'Georgia', serif",
   georgia: "'Georgia', 'Times New Roman', 'Times', serif",
-  lora: "'Lora', 'Times New Roman', 'Times', serif",
+  lora: "'Lora', 'Georgia', 'Times New Roman', serif",
 } as const;
 
-/**
- * Apply font configuration to CSS variables
- *
- * @param config Font configuration object
- * @param target Target element (defaults to document.documentElement)
- *
- * @example
- * ```ts
- * // Use Google Fonts
- * applyFontConfig({
- *   sans: FONT_STACKS.poppins,
- *   mono: FONT_STACKS.firaCode
- * });
- *
- * // Use system fonts only
- * applyFontConfig({
- *   sans: FONT_STACKS.system,
- *   mono: FONT_STACKS.systemMono
- * });
- * ```
- */
-export function applyFontConfig(config: FontConfig, target: HTMLElement = document.documentElement): void {
-  const style = target.style;
-
-  if (config.sans) {
-    style.setProperty(FONT_CSS_VARIABLES.sans, config.sans);
-  }
-
-  if (config.mono) {
-    style.setProperty(FONT_CSS_VARIABLES.mono, config.mono);
-  }
-
-  if (config.serif) {
-    style.setProperty(FONT_CSS_VARIABLES.serif, config.serif);
-  }
-
-  if (config.inter) {
-    style.setProperty(FONT_CSS_VARIABLES.inter, config.inter);
-  }
-
-  if (config.jetbrainsMono) {
-    style.setProperty(FONT_CSS_VARIABLES.jetbrainsMono, config.jetbrainsMono);
+function write<K extends string>(target: HTMLElement, variables: Record<K, string>, values: Partial<Record<K, string>>) {
+  for (const key of Object.keys(variables) as K[]) {
+    const value = values[key];
+    if (value) target.style.setProperty(variables[key], value);
   }
+}
 
-  if (config.playfairDisplay) {
-    style.setProperty(FONT_CSS_VARIABLES.playfairDisplay, config.playfairDisplay);
+function clear(target: HTMLElement, variables: Record<string, string>) {
+  for (const variable of Object.values(variables)) {
+    target.style.removeProperty(variable);
   }
 }
 
 /**
- * Generate CSS string for font configuration
+ * Apply a font configuration.
  *
- * @param config Font configuration object
- * @returns CSS string that can be injected into a stylesheet
+ * Stacks land on `:root` and roles on `themeElement`, mirroring where the stylesheet
+ * declares them — writing a role to `:root` would not survive, because the theme
+ * element declares its own.
  *
  * @example
  * ```ts
- * const css = generateFontCSS({
- *   sans: FONT_STACKS.poppins,
- *   mono: FONT_STACKS.firaCode
+ * // Serif headings over a sans body
+ * applyFontConfig({
+ *   stacks: { sans: FONT_STACKS.inter, serif: FONT_STACKS.playfair },
+ *   roles: { heading: 'var(--font-serif)' },
  * });
- *
- * // Inject into document
- * const style = document.createElement('style');
- * style.textContent = css;
- * document.head.appendChild(style);
  * ```
  */
-export function generateFontCSS(config: FontConfig): string {
-  const rules: string[] = [':root {'];
-
-  if (config.sans) {
-    rules.push(`  ${FONT_CSS_VARIABLES.sans}: ${config.sans};`);
-  }
-
-  if (config.mono) {
-    rules.push(`  ${FONT_CSS_VARIABLES.mono}: ${config.mono};`);
-  }
-
-  if (config.serif) {
-    rules.push(`  ${FONT_CSS_VARIABLES.serif}: ${config.serif};`);
-  }
+export function applyFontConfig(
+  config: FontConfig,
+  { root = document.documentElement, themeElement = document.querySelector<HTMLElement>('.radix-themes') }: { root?: HTMLElement; themeElement?: HTMLElement | null } = {},
+): void {
+  if (config.stacks) write(root, FONT_STACK_VARIABLES, config.stacks);
+  if (config.roles && themeElement) write(themeElement, FONT_ROLE_VARIABLES, config.roles);
+}
 
-  if (config.inter) {
-    rules.push(`  ${FONT_CSS_VARIABLES.inter}: ${config.inter};`);
-  }
+/**
+ * Render a font configuration as a CSS string, for injecting into a stylesheet or
+ * emitting server-side.
+ */
+export function generateFontCSS(config: FontConfig): string {
+  const blocks: string[] = [];
 
-  if (config.jetbrainsMono) {
-    rules.push(`  ${FONT_CSS_VARIABLES.jetbrainsMono}: ${config.jetbrainsMono};`);
+  const stacks = Object.entries(config.stacks ?? {}).filter(([, value]) => value);
+  if (stacks.length) {
+    blocks.push([':root {', ...stacks.map(([key, value]) => `  ${FONT_STACK_VARIABLES[key as keyof FontStacks]}: ${value};`), '}'].join('\n'));
   }
 
-  if (config.playfairDisplay) {
-    rules.push(`  ${FONT_CSS_VARIABLES.playfairDisplay}: ${config.playfairDisplay};`);
+  const roles = Object.entries(config.roles ?? {}).filter(([, value]) => value);
+  if (roles.length) {
+    blocks.push(['.radix-themes {', ...roles.map(([key, value]) => `  ${FONT_ROLE_VARIABLES[key as keyof FontRoles]}: ${value};`), '}'].join('\n'));
   }
 
-  rules.push('}');
-
-  return rules.join('\n');
+  return blocks.join('\n\n');
 }
 
-/**
- * Reset fonts to Kookie UI defaults
- */
-export function resetFonts(target: HTMLElement = document.documentElement): void {
-  const style = target.style;
-
-  // Remove custom font variables to fall back to defaults
-  style.removeProperty(FONT_CSS_VARIABLES.sans);
-  style.removeProperty(FONT_CSS_VARIABLES.mono);
-  style.removeProperty(FONT_CSS_VARIABLES.serif);
-  style.removeProperty(FONT_CSS_VARIABLES.inter);
-  style.removeProperty(FONT_CSS_VARIABLES.jetbrainsMono);
-  style.removeProperty(FONT_CSS_VARIABLES.playfairDisplay);
+/** Drop every inline font override, falling back to the stylesheet's defaults. */
+export function resetFonts({ root = document.documentElement, themeElement = document.querySelector<HTMLElement>('.radix-themes') }: { root?: HTMLElement; themeElement?: HTMLElement | null } = {}): void {
+  clear(root, FONT_STACK_VARIABLES);
+  if (themeElement) clear(themeElement, FONT_ROLE_VARIABLES);
 }
 
-/**
- * Get current font configuration from CSS variables
- */
-export function getCurrentFontConfig(target: HTMLElement = document.documentElement): FontConfig {
-  const computedStyle = getComputedStyle(target);
+/** Read the stacks and roles currently in effect. */
+export function getCurrentFontConfig({ themeElement = document.querySelector<HTMLElement>('.radix-themes') }: { themeElement?: HTMLElement | null } = {}): Required<FontConfig> {
+  // Roles resolve against the theme element, so read both tiers from it — it inherits
+  // the stacks from `:root` and is the only place the roles are declared.
+  const computed = getComputedStyle(themeElement ?? document.documentElement);
+  const read = (variable: string) => computed.getPropertyValue(variable).trim() || undefined;
 
   return {
-    sans: computedStyle.getPropertyValue(FONT_CSS_VARIABLES.sans).trim() || undefined,
-    mono: computedStyle.getPropertyValue(FONT_CSS_VARIABLES.mono).trim() || undefined,
-    serif: computedStyle.getPropertyValue(FONT_CSS_VARIABLES.serif).trim() || undefined,
-    inter: computedStyle.getPropertyValue(FONT_CSS_VARIABLES.inter).trim() || undefined,
-    jetbrainsMono: computedStyle.getPropertyValue(FONT_CSS_VARIABLES.jetbrainsMono).trim() || undefined,
-    playfairDisplay: computedStyle.getPropertyValue(FONT_CSS_VARIABLES.playfairDisplay).trim() || undefined,
+    stacks: {
+      sans: read(FONT_STACK_VARIABLES.sans),
+      mono: read(FONT_STACK_VARIABLES.mono),
+      serif: read(FONT_STACK_VARIABLES.serif),
+    },
+    roles: {
+      body: read(FONT_ROLE_VARIABLES.body),
+      heading: read(FONT_ROLE_VARIABLES.heading),
+      code: read(FONT_ROLE_VARIABLES.code),
+      strong: read(FONT_ROLE_VARIABLES.strong),
+      em: read(FONT_ROLE_VARIABLES.em),
+      quote: read(FONT_ROLE_VARIABLES.quote),
+    },
   };
 }

package/src/helpers/get-margin-styles.ts

@@ -1,5 +1,3 @@
-import classNames from 'classnames';
-
 import { getResponsiveStyles } from './get-responsive-styles.js';
 import { mergeStyles } from './merge-styles.js';
 import { marginPropDefs } from '../props/margin.props.js';
@@ -7,75 +5,44 @@ import { marginPropDefs } from '../props/margin.props.js';
 import type { MarginProps } from '../props/margin.props.js';
 
 const marginValues = marginPropDefs.m.values;
+const marginValueSet: ReadonlySet<string> = new Set(marginValues);
+
+// Static table so the common case — a component with no margin props at all —
+// is seven property reads and nothing else.
+const MARGIN_PROPS: ReadonlyArray<{
+  key: keyof MarginProps;
+  className: string;
+  customProperties: `--${string}`[];
+}> = [
+  { key: 'm', className: 'rt-r-m', customProperties: ['--margin'] },
+  { key: 'mx', className: 'rt-r-mx', customProperties: ['--margin-left', '--margin-right'] },
+  { key: 'my', className: 'rt-r-my', customProperties: ['--margin-top', '--margin-bottom'] },
+  { key: 'mt', className: 'rt-r-mt', customProperties: ['--margin-top'] },
+  { key: 'mr', className: 'rt-r-mr', customProperties: ['--margin-right'] },
+  { key: 'mb', className: 'rt-r-mb', customProperties: ['--margin-bottom'] },
+  { key: 'ml', className: 'rt-r-ml', customProperties: ['--margin-left'] },
+];
 
 export function getMarginStyles(props: MarginProps) {
-  const [mClassNames, mCustomProperties] = getResponsiveStyles({
-    className: 'rt-r-m',
-    customProperties: ['--margin'],
-    propValues: marginValues,
-    value: props.m,
-  });
-
-  const [mxClassNames, mxCustomProperties] = getResponsiveStyles({
-    className: 'rt-r-mx',
-    customProperties: ['--margin-left', '--margin-right'],
-    propValues: marginValues,
-    value: props.mx,
-  });
-
-  const [myClassNames, myCustomProperties] = getResponsiveStyles({
-    className: 'rt-r-my',
-    customProperties: ['--margin-top', '--margin-bottom'],
-    propValues: marginValues,
-    value: props.my,
-  });
-
-  const [mtClassNames, mtCustomProperties] = getResponsiveStyles({
-    className: 'rt-r-mt',
-    customProperties: ['--margin-top'],
-    propValues: marginValues,
-    value: props.mt,
-  });
-
-  const [mrClassNames, mrCustomProperties] = getResponsiveStyles({
-    className: 'rt-r-mr',
-    customProperties: ['--margin-right'],
-    propValues: marginValues,
-    value: props.mr,
-  });
-
-  const [mbClassNames, mbCustomProperties] = getResponsiveStyles({
-    className: 'rt-r-mb',
-    customProperties: ['--margin-bottom'],
-    propValues: marginValues,
-    value: props.mb,
-  });
-
-  const [mlClassNames, mlCustomProperties] = getResponsiveStyles({
-    className: 'rt-r-ml',
-    customProperties: ['--margin-left'],
-    propValues: marginValues,
-    value: props.ml,
-  });
-
-  return [
-    classNames(
-      mClassNames,
-      mxClassNames,
-      myClassNames,
-      mtClassNames,
-      mrClassNames,
-      mbClassNames,
-      mlClassNames
-    ),
-    mergeStyles(
-      mCustomProperties,
-      mxCustomProperties,
-      myCustomProperties,
-      mtCustomProperties,
-      mrCustomProperties,
-      mbCustomProperties,
-      mlCustomProperties
-    ),
-  ] as const;
+  let classes: string[] | undefined;
+  let style: ReturnType<typeof mergeStyles>;
+
+  for (let i = 0; i < MARGIN_PROPS.length; i++) {
+    const { key, className, customProperties } = MARGIN_PROPS[i];
+    const value = props[key];
+    if (value === undefined) continue;
+
+    const [propClassNames, propCustomProperties] = getResponsiveStyles({
+      className,
+      customProperties,
+      propValues: marginValues,
+      propValueSet: marginValueSet,
+      value,
+    });
+
+    if (propClassNames) (classes ??= []).push(propClassNames);
+    if (propCustomProperties) style = mergeStyles(style, propCustomProperties);
+  }
+
+  return [classes !== undefined ? classes.join(' ') : '', style] as const;
 }

package/src/helpers/get-responsive-styles.ts

@@ -4,11 +4,21 @@ import { isResponsiveObject } from './is-responsive-object.js';
 
 import type { Responsive, Union } from '../props/prop-def.js';
 
+/**
+ * Membership test against a prop def's enum values. Callers that already hold a
+ * compiled prop def pass `propValueSet` for an O(1) lookup; the handful of call
+ * sites that build options inline fall back to scanning the array.
+ */
+function includesValue(propValues: string[] | readonly string[], propValueSet: ReadonlySet<string> | undefined, value: string): boolean {
+  return propValueSet !== undefined ? propValueSet.has(value) : propValues.includes(value);
+}
+
 interface GetResponsiveStylesOptions {
   className: string;
   customProperties: `--${string}`[];
   value: Responsive<Union> | Responsive<string> | undefined;
   propValues: string[] | readonly string[];
+  propValueSet?: ReadonlySet<string>;
   parseValue?: (value: string) => string | undefined;
 }
 
@@ -28,28 +38,25 @@ interface GetResponsiveClassNamesOptions {
   className: string;
   value: Responsive<Union> | Responsive<string> | undefined;
   propValues: string[] | readonly string[];
+  propValueSet?: ReadonlySet<string>;
   parseValue?: (value: string) => string | undefined;
 }
 
-function getResponsiveClassNames({
-  allowArbitraryValues,
-  value,
-  className,
-  propValues,
-  parseValue = (value) => value,
-}: GetResponsiveClassNamesOptions): string | undefined {
-  const classNames: string[] = [];
-
+function getResponsiveClassNames({ allowArbitraryValues, value, className, propValues, propValueSet, parseValue = (value) => value }: GetResponsiveClassNamesOptions): string | undefined {
   if (!value) {
     return undefined;
   }
 
-  if (typeof value === 'string' && propValues.includes(value)) {
-    return getBaseClassName(className, value, parseValue);
+  if (typeof value === 'string') {
+    if (includesValue(propValues, propValueSet, value)) {
+      return getBaseClassName(className, value, parseValue);
+    }
+    return allowArbitraryValues ? className : undefined;
   }
 
   if (isResponsiveObject(value)) {
     const object = value;
+    const classNames: string[] = [];
 
     for (const bp in object) {
       // Make sure we are not iterating over keys that aren't breakpoints
@@ -60,7 +67,7 @@ function getResponsiveClassNames({
       const value = object[bp];
 
       if (value !== undefined) {
-        if (propValues.includes(value)) {
+        if (includesValue(propValues, propValueSet, value)) {
           const baseClassName = getBaseClassName(className, value, parseValue);
           const bpClassName = bp === 'initial' ? baseClassName : `${bp}:${baseClassName}`;
           classNames.push(bpClassName);
@@ -71,7 +78,7 @@ function getResponsiveClassNames({
       }
     }
 
-    return classNames.join(' ');
+    return classNames.length > 0 ? classNames.join(' ') : '';
   }
 
   if (allowArbitraryValues) {
@@ -79,11 +86,7 @@ function getResponsiveClassNames({
   }
 }
 
-function getBaseClassName(
-  className: string,
-  value: string,
-  parseValue: (value: string) => string | undefined
-): string {
+function getBaseClassName(className: string, value: string, parseValue: (value: string) => string | undefined): string {
   const delimiter = className ? '-' : '';
   const matchedValue = parseValue(value);
   const isNegative = matchedValue?.startsWith('-');
@@ -96,24 +99,25 @@ interface GetResponsiveCustomPropertiesOptions {
   customProperties: `--${string}`[];
   value: Responsive<Union> | Responsive<string> | undefined;
   propValues: string[] | readonly string[];
+  propValueSet?: ReadonlySet<string>;
   parseValue?: (value: string) => string | undefined;
 }
 
-function getResponsiveCustomProperties({
-  customProperties,
-  value,
-  propValues,
-  parseValue = (value) => value,
-}: GetResponsiveCustomPropertiesOptions) {
-  let styles: Record<string, string | undefined> = {};
-
+function getResponsiveCustomProperties({ customProperties, value, propValues, propValueSet, parseValue = (value) => value }: GetResponsiveCustomPropertiesOptions) {
   // Don't generate custom properties if the value is not arbitrary
-  if (!value || (typeof value === 'string' && propValues.includes(value))) {
+  if (!value || (typeof value === 'string' && includesValue(propValues, propValueSet, value))) {
     return undefined;
   }
 
+  let styles: Record<string, string | undefined> | undefined;
+
   if (typeof value === 'string') {
-    styles = Object.fromEntries(customProperties.map((prop) => [prop, value]));
+    const parsed = parseValue(value);
+    styles = {};
+    for (const customProperty of customProperties) {
+      styles[customProperty] = parsed;
+    }
+    return styles;
   }
 
   if (isResponsiveObject(value)) {
@@ -128,25 +132,20 @@ function getResponsiveCustomProperties({
       const value = object[bp];
 
       // Don't generate a custom property if the value is not arbitrary
-      if (propValues.includes(value)) {
+      if (value === undefined || includesValue(propValues, propValueSet, value)) {
         continue;
       }
 
+      const parsed = parseValue(value);
+      styles ??= {};
       for (const customProperty of customProperties) {
         const bpProperty = bp === 'initial' ? customProperty : `${customProperty}-${bp}`;
-        styles[bpProperty] = value;
+        styles[bpProperty] = parsed;
       }
     }
   }
 
-  for (const key in styles) {
-    const value = styles[key];
-    if (value !== undefined) {
-      styles[key] = parseValue(value);
-    }
-  }
-
-  return styles;
+  return styles ?? {};
 }
 
 export { getResponsiveStyles, getResponsiveCustomProperties, getResponsiveClassNames };

package/src/helpers/use-deprecation-warning.ts

@@ -0,0 +1,26 @@
+import * as React from 'react';
+
+const PANEL_BACKGROUND_MESSAGE = 'Warning: The `panelBackground` prop is deprecated and will be removed in a future version. Use `material` prop instead.';
+
+const warned = new Set<string>();
+
+function warnOnce(message: string) {
+  if (warned.has(message)) return;
+  warned.add(message);
+  console.warn(message);
+}
+
+/**
+ * Warns, in development only, that `panelBackground` is deprecated.
+ *
+ * The `process.env.NODE_ENV` check is a compile-time constant, so a production
+ * bundle minifies the effect body away to an empty function instead of reading
+ * props and formatting a message per mounted component. The message is also
+ * logged once per session rather than once per component instance.
+ */
+export function useDeprecatedPanelBackgroundWarning(panelBackground: unknown) {
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === 'production') return;
+    if (panelBackground !== undefined) warnOnce(PANEL_BACKGROUND_MESSAGE);
+  }, [panelBackground]);
+}