emoji-picker-react 4.22.3 → 5.0.1

package/src/primitives/Viewport.tsx

@@ -0,0 +1,204 @@
+import * as React from 'react';
+import { cx } from 'shipstyles';
+
+import { ClassNames } from '../DomUtils/classNames';
+import { stylesheet } from '../Stylesheet/stylesheet';
+import { EmojiVariationPicker } from '../components/body/EmojiVariationPicker';
+import { useBodyRef } from '../components/context/ElementRefContext';
+import {
+  useActiveEmojiState,
+  useNavigationRegistry,
+  useVisibleCategoriesState,
+} from '../components/context/PickerContext';
+import { useActiveCategory } from '../components/navigation/CategoryNavigation';
+import { MOUSE_EVENT_SOURCE, useCategoriesConfig } from '../config/useConfig';
+import { useActiveCategoryScrollDetection } from '../hooks/useActiveCategoryScrollDetection';
+import { useOnMouseMove } from '../hooks/useDisallowMouseMove';
+import { useEmojiPreviewEvents } from '../hooks/useEmojiPreviewEvents';
+import { useMouseDownHandlers } from '../hooks/useMouseDownHandlers';
+import { useOnScroll } from '../hooks/useOnScroll';
+import { useSingletonClaim } from '../hooks/useRegisterRegion';
+
+import { filterPrimitiveProps, useMergedRefs } from './nativeProps';
+import {
+  useRootScope,
+  ViewportScopeProvider,
+  ViewportScrollContext,
+  __resetPrimitiveWarningsForTest,
+} from './scope';
+
+// Re-exported for tests.
+export { __resetPrimitiveWarningsForTest };
+
+/* global process: readonly */
+
+export type ViewportProps = Omit<
+  React.HTMLAttributes<HTMLDivElement>,
+  'role' | 'children' | 'dangerouslySetInnerHTML'
+> & {
+  /**
+   * The scrolled content: one `<List>` (it may be wrapped, e.g. by a
+   * styling library), optionally with `<Empty>` and `<Loading>`.
+   */
+  children: React.ReactNode;
+};
+
+const warnedViewportChildren = new Set<string>();
+
+// Composition is validated by behavior, not element identity: List
+// enforces being inside a Viewport (context) and being unique (grid
+// region singleton). Matching `child.type === List` broke under anything
+// that wraps elements — Emotion's css prop, styled(List), memo/HOCs.
+// What remains is a development hint when a Viewport mounts without a
+// List.
+const useWarnWithoutList =
+  process.env.NODE_ENV === 'production'
+    ? () => undefined
+    : useDevWarnWithoutList;
+
+function useDevWarnWithoutList(): void {
+  const registry = useNavigationRegistry();
+  React.useEffect(() => {
+    if (
+      process.env.NODE_ENV !== 'production' &&
+      registry.getRegionsByKind('grid').length === 0 &&
+      !warnedViewportChildren.has('missing-list')
+    ) {
+      warnedViewportChildren.add('missing-list');
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[emoji-picker-react] <Viewport> mounted without a <List>; it ' +
+          'renders no emoji grid. See docs/v5/PRIMITIVES.md.',
+      );
+    }
+  }, [registry]);
+}
+
+// A Viewport without a height constraint grows to the whole dataset:
+// nothing scrolls, so virtualization renders every emoji (~1,900 buttons).
+// A bare Root has no default height, so this is an easy first mistake.
+const useWarnUnboundedViewport: (
+  BodyRef: React.MutableRefObject<HTMLElement | null>,
+) => void =
+  process.env.NODE_ENV === 'production'
+    ? () => undefined
+    : useDevWarnUnboundedViewport;
+
+function useDevWarnUnboundedViewport(
+  BodyRef: React.MutableRefObject<HTMLElement | null>,
+): void {
+  React.useEffect(() => {
+    const viewport = BodyRef.current;
+    if (
+      process.env.NODE_ENV === 'production' ||
+      !viewport ||
+      typeof ResizeObserver === 'undefined' ||
+      warnedViewportChildren.has('unbounded')
+    ) {
+      return;
+    }
+    const observer = new ResizeObserver(() => {
+      const unbounded =
+        viewport.clientHeight > window.innerHeight * 2 &&
+        viewport.scrollHeight <= viewport.clientHeight + 1;
+      if (!unbounded || warnedViewportChildren.has('unbounded')) return;
+      warnedViewportChildren.add('unbounded');
+      observer.disconnect();
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[emoji-picker-react] <Viewport> has no height limit, so every ' +
+          'emoji renders at once. Give Root a height.',
+      );
+    });
+    observer.observe(viewport);
+    return () => observer.disconnect();
+  }, [BodyRef]);
+}
+
+/** Test-only: reset warn-once sets between cases. */
+export function __resetViewportWarningsForTest(): void {
+  warnedViewportChildren.clear();
+}
+
+// Public Viewport primitive.
+//
+// Scroll/measurement container: owns the scroll position, dismissal of
+// transient toggles on scroll, and the managed variation-picker overlay.
+// At most one Viewport is supported per Root. The single List child owns
+// the grid; no consumer children are accepted anywhere else.
+export const Viewport = /* @__PURE__ */ React.forwardRef<
+  HTMLDivElement,
+  ViewportProps
+>(function Viewport(props, forwardedRef) {
+  const inScope = useRootScope('Viewport');
+  useSingletonClaim('viewport');
+  const { children, ...rest } = props;
+  const nativeProps = filterPrimitiveProps(rest as Record<string, unknown>, [
+    'role',
+  ]);
+  useWarnWithoutList();
+
+  const BodyRef = useBodyRef();
+  const mergedRef = useMergedRefs(forwardedRef, BodyRef);
+  const scrollTop = useOnScroll(BodyRef);
+  useWarnUnboundedViewport(BodyRef);
+  useMouseDownHandlers(BodyRef, MOUSE_EVENT_SOURCE.PICKER);
+  useOnMouseMove();
+
+  const { className, style, ...restNative } =
+    nativeProps as React.HTMLAttributes<HTMLDivElement>;
+
+  if (!inScope) {
+    return null;
+  }
+
+  return (
+    <div
+      {...restNative}
+      ref={mergedRef}
+      data-epr-part="viewport"
+      className={cx(styles.viewport, className)}
+      style={style}
+    >
+      <ViewportScrollContext.Provider value={scrollTop}>
+        <ViewportScopeProvider>
+          <ViewportObservers />
+          <EmojiVariationPicker />
+          {children}
+        </ViewportScopeProvider>
+      </ViewportScrollContext.Provider>
+    </div>
+  );
+});
+
+function ViewportObservers() {
+  // Section observation lives with the scroll container, not the tab bar:
+  // tracking must continue when CategoryNav unmounts (single tab) or is
+  // omitted from a composition entirely.
+  const { setActiveCategory } = useActiveCategory();
+  const [, setActiveEmoji] = useActiveEmojiState();
+  // Hover/focus tracking for Preview and useActiveEmoji lives with the
+  // scroll container too, so it works whether or not Preview is rendered.
+  useEmojiPreviewEvents(true, setActiveEmoji);
+  const [, setVisibleCategories] = useVisibleCategoriesState();
+  const categoriesConfig = useCategoriesConfig();
+  // The observer re-subscribes when the merged categories reference
+  // changes (sections added/removed); the reference is stable otherwise.
+  useActiveCategoryScrollDetection({
+    setActiveCategory,
+    setVisibleCategories,
+    categories: categoriesConfig,
+  });
+  return null;
+}
+
+const styles = /* @__PURE__ */ (() =>
+  stylesheet.create({
+    viewport: {
+      '.': ClassNames.scrollBody,
+      flex: '1',
+      overflowY: 'scroll',
+      overflowX: 'hidden',
+      position: 'relative',
+    },
+  }))();

package/src/primitives/appearance.tsx

@@ -0,0 +1,7 @@
+import * as React from 'react';
+
+// Every Root resets appearance ownership, including nested Roots.
+export const AppearanceContext = /* @__PURE__ */ React.createContext(false);
+export function useDefaultAppearance(): boolean {
+  return React.useContext(AppearanceContext);
+}

package/src/primitives/components.tsx

@@ -0,0 +1,30 @@
+import * as React from 'react';
+
+import type { ListComponents } from '../components/body/listComponents';
+import type { SkinTones } from '../types/exposedTypes';
+
+/** Spread the managed props onto one native button. Render children or your own content. */
+export type CategoryButtonRenderProps =
+  React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    category: { id: string; name: string; isActive: boolean };
+  };
+export type SkinToneButtonRenderProps =
+  React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    tone: { skinTone: SkinTones; isActive: boolean; isOpen: boolean };
+  };
+export type PickerComponents = ListComponents & {
+  CategoryButton?: React.ComponentType<CategoryButtonRenderProps>;
+  SkinToneButton?: React.ComponentType<SkinToneButtonRenderProps>;
+  ExpandButton?: React.ComponentType<
+    React.ButtonHTMLAttributes<HTMLButtonElement>
+  >;
+  ClearButton?: React.ComponentType<
+    React.ButtonHTMLAttributes<HTMLButtonElement>
+  >;
+};
+export const EMPTY_COMPONENTS: PickerComponents = {};
+export const PickerComponentsContext =
+  /* @__PURE__ */ React.createContext<PickerComponents>(EMPTY_COMPONENTS);
+export function usePickerComponents(): PickerComponents {
+  return React.useContext(PickerComponentsContext);
+}

package/src/primitives/hooks.ts

@@ -0,0 +1,165 @@
+import * as React from 'react';
+
+import {
+  useActiveEmojiState,
+  useActiveSkinToneState,
+  useReactionsModeState,
+} from '../components/context/PickerContext';
+import { usePickerDataContext } from '../components/context/PickerDataContext';
+import {
+  useActiveCategory,
+  useJumpToCategory,
+  useVisibleCategoryConfigs,
+} from '../components/navigation/CategoryNavigation';
+import {
+  categoryIdFromCategoryConfig,
+  categoryNameFromCategoryConfig,
+} from '../config/categoryConfig';
+import { useMutableConfig } from '../config/mutableConfig';
+import {
+  useEmojiStyleConfig,
+  useGetEmojiUrlConfig,
+  useAllowExpandReactions,
+} from '../config/useConfig';
+import { skinToneFromEmoji } from '../dataUtils/emojiUtils';
+import { emojiClickOutput } from '../hooks/useMouseDownHandlers';
+import {
+  useEmojiDataState as useDataState,
+  EmojiDataState,
+} from '../hooks/useResolvedEmojiData';
+import {
+  useAcceptedSearchValue,
+  useSetSearchValue,
+  useClearSearchValue,
+} from '../hooks/useSearchController';
+import { useVisibleSearchResultCount } from '../hooks/useSearchResults';
+import { EmojiClickData, SkinTones } from '../types/exposedTypes';
+
+import { useRootScope } from './scope';
+
+// Public state hooks for custom compositions. Each must be called inside
+// <Root>; they read the same Root-scoped state the managed parts use, so a
+// hand-built preview, skin tone control or empty state stays in sync with
+// the grid, keyboard navigation and callbacks.
+
+/**
+ * The emoji currently hovered or keyboard-focused in the grid, in the same
+ * shape `onEmojiClick` receives, or null. Use it to build a custom preview.
+ */
+export function useActiveEmoji(): EmojiClickData | null {
+  useRootScope('useActiveEmoji');
+  const [activeEmoji] = useActiveEmojiState();
+  const [activeSkinTone] = useActiveSkinToneState();
+  const { emojiByUnified } = usePickerDataContext();
+  const emojiStyle = useEmojiStyleConfig();
+  const getEmojiUrl = useGetEmojiUrlConfig();
+
+  return React.useMemo(() => {
+    if (!activeEmoji) {
+      return null;
+    }
+    const emoji = emojiByUnified(
+      activeEmoji.unified ?? activeEmoji.originalUnified,
+    );
+    if (!emoji) {
+      return null;
+    }
+    const skinTone = skinToneFromEmoji(
+      emoji,
+      activeEmoji.unified,
+      activeSkinTone,
+    );
+    return emojiClickOutput(
+      { ...emoji, renderUnified: activeEmoji.unified },
+      skinTone,
+      emojiStyle,
+      getEmojiUrl,
+    );
+  }, [activeEmoji, activeSkinTone, emojiByUnified, emojiStyle, getEmojiUrl]);
+}
+
+/**
+ * The active skin tone and a setter that behaves exactly like choosing a
+ * tone in the built-in control: it updates the grid and calls
+ * `onSkinToneChange` (when `skinTone` is controlled, only the callback
+ * fires and the parent decides).
+ */
+export function useSkinTone(): [SkinTones, (skinTone: SkinTones) => void] {
+  const inScope = useRootScope('useSkinTone');
+  const [skinTone, setActiveSkinTone] = useActiveSkinToneState();
+  // The mutable config ref is stable and read at call time, so the setter
+  // keeps a stable identity and always reaches the latest callback.
+  const { current: callbacks } = useMutableConfig();
+  const setSkinTone = React.useCallback(
+    (next: SkinTones) => {
+      if (!inScope) return;
+      setActiveSkinTone(next);
+      callbacks.onSkinToneChange?.(next);
+    },
+    [setActiveSkinTone, callbacks, inScope],
+  );
+  return [skinTone, setSkinTone];
+}
+
+export type SearchState = {
+  /** Accepted raw search text (controlled value or last committed edit). */
+  search: string;
+  /**
+   * Emojis the list shows for the applied search, or null while no search
+   * is applied. Debounced like the list itself.
+   */
+  resultCount: number | null;
+};
+
+/** Read-only search state, e.g. for a custom status line or empty state. */
+export function useSearchState(): SearchState {
+  useRootScope('useSearchState');
+  const search = useAcceptedSearchValue();
+  const resultCount = useVisibleSearchResultCount();
+  return React.useMemo(() => ({ search, resultCount }), [search, resultCount]);
+}
+
+/** Dataset loading, recoverable failure and retry for this Root. */
+export function useEmojiDataState(): EmojiDataState {
+  useRootScope('useEmojiDataState');
+  return useDataState();
+}
+
+/** Propose/commit raw text. Clear also restores focus to a mounted SearchInput. */
+export function useSearchActions() {
+  useRootScope('useSearchActions');
+  const setValue = useSetSearchValue();
+  const clear = useClearSearchValue();
+  return React.useMemo(() => ({ setValue, clear }), [setValue, clear]);
+}
+
+/** Public section identities and the same deferred jump used by CategoryNav. */
+export function useCategoryNavigation() {
+  useRootScope('useCategoryNavigation');
+  const { activeCategory } = useActiveCategory();
+  const configs = useVisibleCategoryConfigs();
+  const jumpToCategory = useJumpToCategory();
+  const categories = configs.map((config) => ({
+    id: categoryIdFromCategoryConfig(config),
+    name: categoryNameFromCategoryConfig(config),
+  }));
+  return { categories, activeCategory, jumpToCategory };
+}
+
+/** Expansion respects allowExpandReactions; collapse activates the reactions bar. */
+export function usePickerMode() {
+  useRootScope('usePickerMode');
+  const [reactionsOpen, setReactionsOpen] = useReactionsModeState();
+  const canExpand = useAllowExpandReactions();
+  const expand = React.useCallback(() => {
+    if (canExpand) setReactionsOpen(false);
+  }, [canExpand, setReactionsOpen]);
+  const collapse = React.useCallback(
+    () => setReactionsOpen(true),
+    [setReactionsOpen],
+  );
+  return React.useMemo(
+    () => ({ reactionsOpen, canExpand, expand, collapse }),
+    [reactionsOpen, canExpand, expand, collapse],
+  );
+}

package/src/primitives/index.ts

@@ -0,0 +1,94 @@
+export { Root } from './Root';
+export { Panel } from './Panel';
+export type { PanelProps } from './Panel';
+export { Reactions } from './Reactions';
+export type { ReactionsProps } from './Reactions';
+export type {
+  PickerComponents,
+  CategoryButtonRenderProps,
+  SkinToneButtonRenderProps,
+} from './components';
+// Runtime configuration values must stay on this data-free entry: importing
+// them from the main entry also registers its synchronous English dataset.
+export {
+  Categories,
+  EmojiStyle,
+  SkinTones,
+  SkinTonePickerLocation,
+  SuggestionMode,
+  Theme,
+} from '../types/exposedTypes';
+export type {
+  CategoryConfig,
+  CategoryIcons,
+  EmojiClickData,
+  EmojiData,
+  EmojiStyleValue,
+  SkinTonesValue,
+  SuggestionModeValue,
+  ThemeValue,
+} from '../types/exposedTypes';
+export type {
+  PickerLabels,
+  PreviewConfig,
+  EmojiClickHandler,
+  SkinToneChangeHandler,
+  OnEmojiClickApi,
+} from '../config/config';
+export type { CustomEmoji } from '../config/customEmojiConfig';
+export {
+  defaultPickerTokens,
+  structuralPickerTokens,
+  lightPickerTokens,
+  darkPickerTokens,
+} from './tokens';
+export { Empty } from './Empty';
+export { Loading } from './Loading';
+export { LoadError } from './LoadError';
+export { useEmojiDataState } from './hooks';
+export { SkinTone } from './SkinTone';
+export {
+  useActiveEmoji,
+  useSkinTone,
+  useSearchState,
+  useSearchActions,
+  useCategoryNavigation,
+  usePickerMode,
+} from './hooks';
+export type { SearchState } from './hooks';
+export { Search } from './Search';
+export { SearchInput } from './SearchInput';
+export { CategoryNav } from './CategoryNav';
+export { Viewport } from './Viewport';
+export type { ViewportProps } from './Viewport';
+export { List } from './List';
+export { Preview } from './Preview';
+export type {
+  CategoryNavProps,
+  EmptyProps,
+  LoadingProps,
+  LoadErrorProps,
+  SkinToneProps,
+  ListProps,
+  PickerAppearanceProps,
+  PickerCompositionProps,
+  PreviewProps,
+  RootBehaviorProps,
+  RootProps,
+  SearchProps,
+  SearchInputProps,
+  SearchInputElement,
+  SearchInputComponent,
+} from './types';
+export type {
+  CategoryHeaderRenderProps,
+  EmojiRenderProps,
+  ListComponents,
+  ListEmoji,
+} from '../components/body/listComponents';
+export type {
+  EmojiDataInput,
+  EmojiDataLoader,
+  EmojiDataLoaderOptions,
+  EmojiDataState,
+} from '../hooks/useResolvedEmojiData';

package/src/primitives/nativeProps.ts

@@ -0,0 +1,90 @@
+import * as React from 'react';
+
+// Native prop forwarding for public primitives.
+//
+// Every primitive forwards ordinary native props valid for its root
+// element (id, non-reserved aria-*, non-reserved data-*, title, className,
+// style, ordinary event handlers). The library owns `role` on every
+// primitive and reserves `data-epr-*`, internal focus-management
+// attributes, and required hidden/inert state.
+
+/** Keys never forwarded to the DOM (in addition to `data-epr-*`). */
+export function filterPrimitiveProps(
+  props: object,
+  reserved: readonly string[],
+): Record<string, unknown> {
+  const forwarded: Record<string, unknown> = {};
+  const values = props as Record<string, unknown>;
+  for (const key of Object.keys(values)) {
+    if (
+      reserved.includes(key) ||
+      key === 'dangerouslySetInnerHTML' ||
+      key === 'children'
+    ) {
+      continue;
+    }
+    if (key.startsWith('data-epr-')) {
+      continue;
+    }
+    forwarded[key] = values[key];
+  }
+  return forwarded;
+}
+
+/**
+ * Handler composition: the library behavioral handler
+ * runs first, the consumer handler second with the same event. Consumer
+ * `preventDefault()` is not a supported way to disable required behavior.
+ * Event-handler exceptions propagate per normal React/browser behavior;
+ * primitives never catch them and no ErrorBoundary is installed.
+ */
+export function composeHandlers<E>(
+  libraryHandler: ((event: E) => void) | undefined,
+  consumerHandler: ((event: E) => void) | undefined,
+): ((event: E) => void) | undefined {
+  if (!libraryHandler) {
+    return consumerHandler;
+  }
+  if (!consumerHandler) {
+    return libraryHandler;
+  }
+  return (event: E) => {
+    libraryHandler(event);
+    consumerHandler(event);
+  };
+}
+
+/** Merge any number of refs (context ref + forwarded ref) onto one node. */
+export function mergeRefs<T>(
+  ...refs: Array<React.Ref<T> | undefined>
+): React.RefCallback<T> {
+  const cleanups = new Map<React.Ref<T>, () => void>();
+  return (node: T | null) => {
+    for (const ref of refs) {
+      if (!ref) {
+        continue;
+      }
+      if (typeof ref === 'function') {
+        const cleanup = cleanups.get(ref);
+        if (node === null && cleanup) {
+          cleanups.delete(ref);
+          cleanup();
+        } else {
+          const result = (ref as (node: T | null) => unknown)(node);
+          if (typeof result === 'function')
+            cleanups.set(ref, result as () => void);
+        }
+      } else {
+        (ref as React.MutableRefObject<T | null>).current = node;
+      }
+    }
+  };
+}
+
+/** Keep callback refs attached while the refs themselves are unchanged. */
+export function useMergedRefs<T>(
+  first: React.Ref<T> | undefined,
+  second: React.Ref<T> | undefined,
+): React.RefCallback<T> {
+  return React.useMemo(() => mergeRefs(first, second), [first, second]);
+}

package/src/primitives/scope.tsx

@@ -0,0 +1,109 @@
+import * as React from 'react';
+
+/* global process: readonly */
+
+// Primitive scope validation.
+//
+// Render-time context validation fails immediately in development:
+// - any primitive outside Root;
+// - List outside Viewport.
+// In production the validators warn once and report out-of-scope so the
+// primitive renders null: production avoids the hard crash, and a null is
+// diagnosable whereas continuing would die later with a confusing
+// TypeError deep inside provider-dependent behavior.
+// Registration-time singleton validation lives in the navigation registry.
+// Server rendering performs only render-time context validation; there is
+// no post-mount validation during SSR. Exact development error text is not
+// semver API.
+
+interface RootScope {
+  readonly root: true;
+}
+
+const RootScopeContext = /* @__PURE__ */ React.createContext<RootScope | null>(
+  null,
+);
+
+export function RootScopeProvider({ children }: { children: React.ReactNode }) {
+  const value = React.useMemo<RootScope>(() => ({ root: true }), []);
+  return (
+    <RootScopeContext.Provider value={value}>
+      {children}
+    </RootScopeContext.Provider>
+  );
+}
+
+const warnedOutsideRoot = new Set<string>();
+
+export function useRootScope(primitive: string): boolean {
+  const scope = React.useContext(RootScopeContext);
+  if (scope) {
+    return true;
+  }
+  if (process.env.NODE_ENV === 'production') {
+    if (!warnedOutsideRoot.has(primitive)) {
+      warnedOutsideRoot.add(primitive);
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[emoji-picker-react] <${primitive}> rendered outside <Root>.`,
+      );
+    }
+    return false;
+  }
+  throw new Error(
+    (primitive.startsWith('use')
+      ? `[emoji-picker-react] ${primitive}() must be called inside <Root>. `
+      : `[emoji-picker-react] <${primitive}> must be rendered inside <Root>. `) +
+      `See docs/v5/PRIMITIVES.md composition grammar.`,
+  );
+}
+
+const ViewportScopeContext =
+  /* @__PURE__ */ React.createContext<boolean>(false);
+
+export const ViewportScrollContext =
+  /* @__PURE__ */ React.createContext<number>(0);
+
+export function useViewportScrollTop(): number {
+  return React.useContext(ViewportScrollContext);
+}
+export function ViewportScopeProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <ViewportScopeContext.Provider value={true}>
+      {children}
+    </ViewportScopeContext.Provider>
+  );
+}
+
+const warnedOutsideViewport = new Set<string>();
+
+export function useViewportScope(primitive: string): boolean {
+  const inside = React.useContext(ViewportScopeContext);
+  if (inside) {
+    return true;
+  }
+  if (process.env.NODE_ENV === 'production') {
+    if (!warnedOutsideViewport.has(primitive)) {
+      warnedOutsideViewport.add(primitive);
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[emoji-picker-react] <${primitive}> must be inside <Viewport>.`,
+      );
+    }
+    return false;
+  }
+  throw new Error(
+    `[emoji-picker-react] <${primitive}> must be rendered inside ` +
+      `<Viewport>. See docs/v5/PRIMITIVES.md composition grammar.`,
+  );
+}
+
+/** Test-only: reset warn-once sets between cases. */
+export function __resetPrimitiveWarningsForTest(): void {
+  warnedOutsideRoot.clear();
+  warnedOutsideViewport.clear();
+}