@wildo-ai/saas-frontend-lib 1.0.1 → 1.1.0

package/dist/esm/components/sections/surface.js

@@ -0,0 +1,658 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { FRAMEWORK_DEFAULT_SURFACE_POLICIES, SurfaceVariant, UIBehavior, } from '@wildo-ai/presets-components-models';
+import { cn } from '../../core/ui/cn.js';
+import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
+import { computeSurfacePolicyContextValue, mergeSurfacePolicy, SurfacePolicyContext, useSurfacePolicy, } from '../../core/ui/SurfacePolicyContext.js';
+import { useUI } from '../../core/ui/useUI.js';
+import { useMaterialRuntime } from '../../core/ui/material-runtime.js';
+import { SurfaceErrorBoundary } from '../../core/ui/SurfaceErrorBoundary.js';
+import { useSurfaceBodyScrollLock, useSurfaceFocusTrap } from '../../core/ui/surface-a11y.utils.js';
+const POLICY_DRIVEN_UTILITY_PREFIXES = /(?:^|\s)(?:p|pt|pr|pb|pl|pe|ps|px|py|gap|gap-x|gap-y|max-h|min-h|max-w|overflow|z|flex|grid|flex-col|flex-row|flex-col-reverse|flex-row-reverse)-/;
+const logger = LoggerFrontendService.getLogger();
+function paddingTierToCssValue(value) {
+    switch (value) {
+        case 'none':
+            return '0px';
+        case 'field':
+            return 'var(--sp-field)';
+        case 'card-sm':
+            return 'var(--spacing-card-sm)';
+        case 'card':
+            return 'var(--sp-card)';
+        case 'container':
+            return 'var(--sp-container)';
+        default:
+            return undefined;
+    }
+}
+function gapTierToCssValue(value) {
+    switch (value) {
+        case 'none':
+            return '0px';
+        case 'item':
+            return 'var(--sp-item)';
+        case 'field':
+            return 'var(--sp-field)';
+        case 'section':
+            return 'var(--sp-section)';
+        case 'lane':
+            return 'var(--sp-region)';
+        default:
+            return undefined;
+    }
+}
+function textWrapToCssValue(value) {
+    switch (value) {
+        case 'nowrap':
+            return 'nowrap';
+        case 'balance':
+            return 'balance';
+        case 'pretty':
+            return 'pretty';
+        case 'wrap':
+            return 'wrap';
+        default:
+            return undefined;
+    }
+}
+function numericAlignmentToCssValue(value) {
+    switch (value) {
+        case 'tabular':
+            return 'tabular-nums';
+        case 'lining':
+            return 'lining-nums';
+        case 'inherit':
+            return 'inherit';
+        default:
+            return undefined;
+    }
+}
+function overlongTokenStrategyToCssValue(value) {
+    switch (value) {
+        case 'break-word':
+            // CSS `overflow-wrap: break-word` (the framework default): emergency
+            // character-boundary breaking when a token would otherwise overflow,
+            // WITHOUT feeding those break opportunities into min-content sizing.
+            // Catches URLs, dev-time i18n keys, hex hashes, file paths, error
+            // messages with embedded paths.
+            return 'break-word';
+        case 'break-anywhere':
+            // CSS `overflow-wrap: anywhere` — same emergency breaking as
+            // `break-word`, but the break opportunities ALSO shrink the surface's
+            // intrinsic min-content width to one character (which collapses
+            // intrinsically-sized layouts like stat tiles to one letter per line).
+            // Per-surface opt-in only; see `OverlongTokenStrategy` JSDoc.
+            return 'anywhere';
+        case 'overflow':
+            // CSS `overflow-wrap: normal` = browser default. Long tokens
+            // visibly overflow the surface. Useful for code blocks that
+            // intentionally scroll horizontally, or any surface where the
+            // design specifically calls for visible overflow.
+            return 'normal';
+        case 'inherit':
+            return 'inherit';
+        default:
+            return undefined;
+    }
+}
+function stackingTierToCssValue(value) {
+    switch (value) {
+        case 'content':
+            return 'var(--z-content)';
+        case 'overlay':
+            return 'var(--z-overlay)';
+        case 'transient':
+            return 'var(--z-transient)';
+        case 'guidance':
+            return 'var(--z-guidance)';
+        case 'critical':
+            return 'var(--z-critical)';
+        default:
+            return undefined;
+    }
+}
+function actionAlignmentToCssValue(value) {
+    switch (value) {
+        case 'stack':
+            return 'column';
+        case 'row':
+        case 'inherit':
+            return value;
+        case 'column-reverse-on-mobile':
+            return 'row';
+        default:
+            return undefined;
+    }
+}
+function actionAlignmentToMobileCssValue(value) {
+    switch (value) {
+        case 'column-reverse-on-mobile':
+            return 'column-reverse';
+        case 'stack':
+            return 'column';
+        case 'row':
+        case 'inherit':
+            return value;
+        default:
+            return undefined;
+    }
+}
+function responsiveMaxWidthToCssValue(value) {
+    switch (value) {
+        case 'full':
+            return '100%';
+        case 'sm':
+            return '24rem';
+        case 'md':
+            return '28rem';
+        case 'lg':
+            return '32rem';
+        case 'xl':
+            return '36rem';
+        case 'measure':
+            // Reading-measure cap for single-column form/field stacks (T4c).
+            // Themeable via `--measure-max-width`; defaults to 42rem (~672px).
+            return 'var(--measure-max-width, 42rem)';
+        case 'centered-readable':
+            return '72ch';
+        case 'content':
+            // Page-content cap for primary content areas. Themeable via the
+            // `--content-max-width` CSS variable; defaults to 80rem (~1280px).
+            return 'var(--content-max-width, 80rem)';
+        case 'none':
+        default:
+            // `none` is both the explicit tier AND the neutral, for the same reason the
+            // margin companion below returns `0px` rather than `undefined`: policy vars
+            // inherit, so an omitted cap adopts the nearest ancestor surface's cap. Every
+            // tier of the union already returned explicitly, so folding the default in is
+            // inert for every reachable value and only closes the inheritance hole.
+            return 'none';
+    }
+}
+/**
+ * Centering companion to {@link responsiveMaxWidthToCssValue}: a surface capped
+ * to a finite max inline-size is centered in its container via
+ * `margin-inline: auto`. `full`/`none`/unset surfaces fill their container and
+ * are explicitly RESET to `0px`. Applied by the Tailwind base layer at ≥ 640px
+ * alongside the inline-size cap, so the `centered-readable`/`content` tiers
+ * actually center (the cap alone would leave the surface flush to the
+ * inline-start edge).
+ *
+ * The uncapped tiers MUST emit `0px` rather than `undefined`. Policy vars are
+ * CSS custom properties, so they INHERIT: an omitted value is not "no
+ * centering", it is "whatever the nearest ancestor surface asked for". Since
+ * `OVERLAY` is capped (`lg`) and therefore publishes `auto`, every uncapped
+ * surface nested inside a dialog silently inherited `margin-inline: auto` — and
+ * an auto cross-axis margin in a flex column ALSO suppresses the item's
+ * stretch, so those surfaces shrink-wrapped to their content and drifted to the
+ * centre. In the settings hub that turned a column of cards into a ragged
+ * staircase, each card as wide as its longest sentence. The inline-size
+ * companion never showed the defect because its uncapped tier emits an explicit
+ * `'none'`; this one returned `undefined` and inherited instead. Same neutral
+ * -emission discipline as `--surface-policy-safe-area`, which publishes `0px`
+ * rather than omitting itself.
+ */
+function responsiveMaxWidthToMarginCssValue(value) {
+    switch (value) {
+        case 'sm':
+        case 'md':
+        case 'lg':
+        case 'xl':
+        case 'measure':
+        case 'centered-readable':
+        case 'content':
+            return 'auto';
+        case 'full':
+        case 'none':
+        default:
+            // Explicit reset, never `undefined` — see the note above on inheritance.
+            return '0px';
+    }
+}
+function embeddedTablePaddingToCssValue(value) {
+    switch (value) {
+        case 'strip':
+            return '0px';
+        case 'preserve':
+        default:
+            // `preserve` is also the neutral: "no opinion" means keep the surface's own
+            // inline padding. The Tailwind rule spells the same intent as a fallback
+            // (`var(--…-embedded-table-padding-inline, var(--…-padding-inline))`), but a
+            // fallback only fires when the var is UNSET — an inherited value that IS set
+            // wins over it, so a table-bearing surface nested inside a `strip` ancestor
+            // would have inherited `0px`. Emitting it here is what actually shadows that.
+            return 'var(--surface-policy-padding-inline)';
+    }
+}
+function framingModeToAttribute(value) {
+    switch (value) {
+        case 'always':
+        case 'when-orphan':
+        case 'never':
+            return value;
+        default:
+            return undefined;
+    }
+}
+function nestedRadiusStrategyToAttribute(value) {
+    switch (value) {
+        case 'inherit':
+        case 'one-tier-tighter':
+        case 'fixed':
+            return value;
+        default:
+            return undefined;
+    }
+}
+function firstChildEdgeStrategyToAttribute(value) {
+    switch (value) {
+        case 'collapse':
+        case 'preserve':
+            return value;
+        default:
+            return undefined;
+    }
+}
+function dividerStrategyToAttribute(value) {
+    switch (value) {
+        case 'border':
+        case 'gap':
+        case 'rule':
+        case 'none':
+            return value;
+        default:
+            return undefined;
+    }
+}
+function nestedRadiusToCssValue(strategy, isNestedInFramedAncestor) {
+    if (!isNestedInFramedAncestor) {
+        return undefined;
+    }
+    switch (strategy) {
+        case 'inherit':
+            return 'inherit';
+        case 'one-tier-tighter':
+            return 'var(--surface-nested-radius-one-tier-tighter, var(--radius-lg, 0.5rem))';
+        case 'fixed':
+        default:
+            return undefined;
+    }
+}
+function selectableSemanticsToAttribute(value) {
+    switch (value) {
+        case 'wrap-children':
+        case 'self-selectable':
+        case 'forbidden':
+            return value;
+        default:
+            return undefined;
+    }
+}
+function gestureOptInToAttribute(value) {
+    switch (value) {
+        case 'self':
+        case 'children':
+        case 'none':
+            return value;
+        default:
+            return undefined;
+    }
+}
+function landmarkRoleToAttribute(value) {
+    switch (value) {
+        case 'region':
+        case 'dialog':
+        case 'alertdialog':
+        case 'complementary':
+        case 'navigation':
+        case 'status':
+        case 'main':
+            return value;
+        case 'none':
+        case 'reset':
+        default:
+            return undefined;
+    }
+}
+function shouldActivateStackLayout(gap) {
+    return Boolean(gap && gap !== 'none');
+}
+/**
+ * Stack-layout channel for `display` / `flex-direction`, on both the surface
+ * root (`--surface-policy-display`) and its slots (`--surface-policy-slot-display`).
+ *
+ * The NON-stacking branch MUST return a concrete value rather than `undefined`,
+ * for two independent reasons — the second one shipped as a live defect:
+ *
+ * 1. Policy vars are CSS custom properties, so they INHERIT. An omitted value is
+ *    not "no opinion", it is "adopt the nearest ancestor surface's opinion". A
+ *    non-stacking surface nested inside a stacking one therefore picked up
+ *    `display: flex; flex-direction: column` from its ancestor — the same
+ *    inheritance class as the `--surface-policy-responsive-max-width-margin`
+ *    defect (see `responsiveMaxWidthToMarginCssValue`).
+ * 2. Even with NO ancestor to inherit from, omitting the var does not leave the
+ *    element alone. `display: var(--surface-policy-display)` with the var unset
+ *    is invalid at computed-value time, which resolves to `unset` — and `display`
+ *    is not inherited, so that is its INITIAL value, `inline`. The base-layer
+ *    declaration still wins the cascade, so it overrides the UA stylesheet's
+ *    `div { display: block }`. Measured on the running app: the framework's own
+ *    `PrimaryContentWidthBoundary` (a SHELL surface whose `containment.gap` is
+ *    flattened to `'none'` precisely so it stays "a plain block") computed
+ *    `display: inline`, which made its `max-inline-size` cap and `margin-inline:
+ *    auto` centering inert — `max-inline-size` does not apply to non-replaced
+ *    inline boxes. With a 400px cap forced inside a 976px container the surface
+ *    measured 976px wide; publishing `block` measured 400px, centered. The entire
+ *    page-content width cap was silently doing nothing.
+ *
+ * A CSS-wide keyword cannot express "no opinion" here: `revert-layer`, `revert`
+ * and `initial` were each measured through this var in the running app and all
+ * three behaved exactly like the unset case (`display: inline`), because a
+ * CSS-wide keyword arriving via `var()` substitution is not honoured as one. A
+ * consumer-side fallback (`var(--x, block)`) does not help either — an inherited
+ * value that IS set wins over the fallback, which is the whole of reason 1.
+ *
+ * `block` / `row` are the initial-ish values a block container wants. Utility
+ * classes still win: they live in a later cascade layer than this base rule.
+ */
+function stackDisplayCssValue(isStacking) {
+    return isStacking ? 'flex' : 'block';
+}
+/** Companion to {@link stackDisplayCssValue} — see its note on explicit neutrals. */
+function stackFlexDirectionCssValue(isStacking) {
+    return isStacking ? 'column' : 'row';
+}
+/**
+ * Every var below is read by a Tailwind base-layer rule that can match a NESTED
+ * surface, so any `undefined` here is not "neutral" — it is "inherit the nearest
+ * ancestor surface's value". The vars were enumerated against that rule set
+ * (`src/tailwind/index.ts`) and classified; the residuals are recorded so the next
+ * author does not have to re-derive them:
+ *
+ * - SAFE BY CONSTRUCTION — `safe-area` always emits `0px`/`env()`;
+ *   `child-adaptive-gap` is gated by the same boolean as the
+ *   `data-surface-child-adaptive-density` attribute its selector requires, so the
+ *   read is unreachable when the emission is absent.
+ * - BENIGN — `numeric-align`, `text-wrap` and `overflow-wrap` drive CSS properties
+ *   that are THEMSELVES inherited, so inheriting the var is equivalent to
+ *   inheriting the property. No shadowing needed.
+ * - INERT — `framing-mode`, `nested-radius{,-strategy}`, `first-child-edge-strategy`,
+ *   `divider-strategy`, `selectable-semantics` and `gesture-opt-in` are republished
+ *   as `--surface-*` custom properties that NOTHING reads (verified repo-wide);
+ *   behaviour is driven by the matching `data-surface-*` attributes, which do not
+ *   inherit.
+ * - LATENT — the remaining tier-mapped vars (`padding-*`, `overflow`, `max-height`,
+ *   `gap`, `z-tier`, the per-slot gaps, `action-alignment{,-mobile}`) can only reach
+ *   their `undefined` branch through an override that sets the slot explicitly to
+ *   `undefined`: every variant's framework default populates them, and both `'reset'`
+ *   and `'inherit'` resolve to a concrete value (`'reset'` additionally logs an error
+ *   when it cannot). Left as-is rather than changed blind — if one becomes reachable,
+ *   it belongs in the explicit-neutral treatment above.
+ */
+function buildSurfacePolicyStyle(policy) {
+    const containment = policy.containment;
+    const nesting = policy.nesting;
+    const content = policy.content;
+    const interactiveState = policy.interactiveState;
+    const geometry = policy.geometry;
+    const stacking = policy.stacking;
+    const composition = policy.composition;
+    const shouldStack = shouldActivateStackLayout(containment?.gap);
+    return {
+        '--surface-policy-display': stackDisplayCssValue(shouldStack),
+        '--surface-policy-flex-direction': stackFlexDirectionCssValue(shouldStack),
+        '--surface-policy-padding-block': paddingTierToCssValue(containment?.paddingBlock),
+        '--surface-policy-padding-inline': paddingTierToCssValue(containment?.paddingInline),
+        '--surface-policy-overflow': containment?.overflow,
+        '--surface-policy-max-height': containment?.maxHeight === 'none' ? 'none' : containment?.maxHeight,
+        '--surface-policy-gap': gapTierToCssValue(containment?.gap),
+        '--surface-policy-header-gap': gapTierToCssValue(containment?.slotGap?.header ?? containment?.gap),
+        '--surface-policy-body-gap': gapTierToCssValue(containment?.slotGap?.body ?? containment?.gap),
+        '--surface-policy-footer-gap': gapTierToCssValue(containment?.slotGap?.footer ?? containment?.gap),
+        '--surface-policy-framing-mode': framingModeToAttribute(nesting?.framingMode),
+        '--surface-policy-nested-radius-strategy': nestedRadiusStrategyToAttribute(nesting?.nestedRadiusStrategy),
+        '--surface-policy-first-child-edge-strategy': firstChildEdgeStrategyToAttribute(nesting?.firstChildEdgeStrategy),
+        '--surface-policy-divider-strategy': dividerStrategyToAttribute(nesting?.dividerStrategy),
+        '--surface-policy-z-tier': stackingTierToCssValue(stacking?.stackingTier),
+        '--surface-policy-numeric-align': numericAlignmentToCssValue(content?.numericAlignment),
+        '--surface-policy-text-wrap': textWrapToCssValue(content?.wrapStrategy),
+        '--surface-policy-overflow-wrap': overlongTokenStrategyToCssValue(content?.overlongTokenStrategy),
+        '--surface-policy-safe-area': geometry?.safeAreaPadding ? 'env(safe-area-inset-bottom)' : '0px',
+        '--surface-policy-action-alignment': actionAlignmentToCssValue(geometry?.actionAlignment),
+        '--surface-policy-action-alignment-mobile': actionAlignmentToMobileCssValue(geometry?.actionAlignment),
+        '--surface-policy-responsive-max-width': responsiveMaxWidthToCssValue(geometry?.responsiveMaxWidth),
+        '--surface-policy-responsive-max-width-margin': responsiveMaxWidthToMarginCssValue(geometry?.responsiveMaxWidth),
+        '--surface-policy-embedded-table-padding-inline': embeddedTablePaddingToCssValue(composition?.embeddedTablePadding),
+        '--surface-policy-child-adaptive-gap': composition?.childAdaptiveDensity ? 'var(--sp-field)' : undefined,
+        '--surface-policy-selectable-semantics': selectableSemanticsToAttribute(interactiveState?.selectableSemantics),
+        '--surface-policy-gesture-opt-in': gestureOptInToAttribute(interactiveState?.gestureOptIn),
+    };
+}
+/**
+ * Policy families whose values DO produce CSS — `containment` (padding,
+ * overflow, max-height, gap), `nesting` (framing mode → frame visibility),
+ * `content` (text-wrap, numeric alignment), `geometry` (responsiveMaxWidth →
+ * max-inline-size), `stacking` (z-tier). The remaining families (`a11y`,
+ * `interactiveState`, `autoRender`, `skeleton`, `composition`) emit only ARIA
+ * attributes / behavioral data-attributes / runtime hooks and CANNOT
+ * visually conflict with a Tailwind utility class.
+ *
+ * Restricting the collision check to these families eliminates a noisy
+ * false-positive: a Surface that overrides ONLY `a11y.landmarkRole`
+ * (e.g., the public shell using `NON_CANONICAL_SHELL_SURFACE_POLICY_OVERRIDE`)
+ * combined with an `overflow-auto` Tailwind utility on the same node is NOT
+ * a collision — `a11y.landmarkRole` does not emit any CSS property the
+ * utility could fight with.
+ */
+const VISUALLY_IMPACTFUL_POLICY_FAMILIES = new Set([
+    'containment',
+    'nesting',
+    'content',
+    'geometry',
+    'stacking',
+]);
+function hasPolicyDrivenOverride(policyOverride) {
+    if (!policyOverride) {
+        return false;
+    }
+    return Object.entries(policyOverride).some(([familyName, familyOverride]) => {
+        if (!VISUALLY_IMPACTFUL_POLICY_FAMILIES.has(familyName)) {
+            return false;
+        }
+        return familyOverride !== undefined
+            && familyOverride !== null
+            && typeof familyOverride === 'object'
+            && Object.keys(familyOverride).length > 0;
+    });
+}
+function usePolicyChannelCollisionWarning(className, childClassName, policyOverride, emitPolicyVars) {
+    const warnedRef = React.useRef(false);
+    // The collision this warns about — a className layout utility (padding / gap /
+    // flex / …) visually overriding a policy-driven CSS var while children still
+    // read the policy value — can only happen when the policy vars are actually
+    // emitted. A surface with `emitPolicyVars={false}` (e.g. ContentSection section
+    // chrome, which owns layout via recipe classes and may set only a
+    // `nesting.framingMode` override) emits NO vars, so there is nothing for a
+    // utility to override. Skipping the check here removes a guaranteed
+    // false-positive on every such surface.
+    if (!emitPolicyVars) {
+        return;
+    }
+    const conflictingClassName = [className, childClassName].filter(Boolean).join(' ');
+    if (process.env.NODE_ENV !== 'production'
+        && !warnedRef.current
+        && conflictingClassName
+        && hasPolicyDrivenOverride(policyOverride)
+        && POLICY_DRIVEN_UTILITY_PREFIXES.test(conflictingClassName)) {
+        warnedRef.current = true;
+        logger.warn('[Surface] className utilities can visually override policyOverride while child policy context still sees the policy value', {
+            className: conflictingClassName,
+        });
+    }
+}
+function mergeSurfaceStyle(policy, materialStyle, style, emitPolicyVars, rendersOwnFrame, nestedRadius) {
+    if (!emitPolicyVars) {
+        return { ...materialStyle, ...style };
+    }
+    return {
+        ...buildSurfacePolicyStyle(policy),
+        '--surface-policy-nested-radius': nestedRadius,
+        borderWidth: rendersOwnFrame ? undefined : '0px',
+        boxShadow: rendersOwnFrame ? undefined : 'none',
+        borderRadius: nestedRadius ? 'var(--surface-policy-nested-radius)' : undefined,
+        ...materialStyle,
+        ...style,
+    };
+}
+const SurfaceRoot = React.forwardRef(function SurfaceRoot({ variant = SurfaceVariant.BASE, materialRoleOverride, policyOverride, asChild = false, emitPolicyVars = true, modal = false, a11yManagedByHost = false, className, style, children, role, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'data-slot': _dataSlot, 'data-surface': _dataSurface, ...props }, ref) {
+    const { getComposedClasses, getMaterialProfile, getRecipe, getSurfacePolicy, } = useUI();
+    // Optional calls keep the primitive resilient in isolated tests and custom
+    // host adapters that provide the legacy minimal UI context surface.
+    const visualRecipe = getRecipe?.(UIBehavior.SURFACE, variant);
+    const visualRecipeClasses = getComposedClasses?.(UIBehavior.SURFACE, variant);
+    const materialProfile = getMaterialProfile?.(materialRoleOverride ?? visualRecipe?.material);
+    const parentContext = React.useContext(SurfacePolicyContext);
+    const policy = React.useMemo(() => getSurfacePolicy
+        ? getSurfacePolicy(variant, policyOverride, parentContext?.policy)
+        : mergeSurfacePolicy(FRAMEWORK_DEFAULT_SURFACE_POLICIES[variant], undefined, undefined, policyOverride, {
+            variant,
+            parentPolicy: parentContext?.policy,
+            logger,
+        }), [getSurfacePolicy, parentContext?.policy, policyOverride, variant]);
+    const [headerId, setHeaderId] = React.useState();
+    const registerHeaderId = React.useCallback((id) => {
+        setHeaderId(id);
+    }, []);
+    const unregisterHeaderId = React.useCallback((id) => {
+        setHeaderId((current) => (current === id ? undefined : current));
+    }, []);
+    const headerRegistration = React.useMemo(() => ({ headerId, registerHeaderId, unregisterHeaderId }), [headerId, registerHeaderId, unregisterHeaderId]);
+    const contextValue = React.useMemo(() => computeSurfacePolicyContextValue(variant, policy, parentContext, headerRegistration), [headerRegistration, parentContext, policy, variant]);
+    const isNestedInFramedAncestor = Boolean(parentContext?.isInFramedAncestor);
+    const nearestFramedAncestorVariant = isNestedInFramedAncestor
+        ? parentContext?.nearestFramedAncestorVariant ?? undefined
+        : undefined;
+    const nestedRadius = nestedRadiusToCssValue(policy.nesting?.nestedRadiusStrategy, isNestedInFramedAncestor);
+    const childClassName = asChild && React.isValidElement(children)
+        ? children.props.className
+        : undefined;
+    usePolicyChannelCollisionWarning(className, childClassName, policyOverride, emitPolicyVars);
+    const Comp = asChild ? Slot : 'div';
+    const surfaceNodeRef = React.useRef(null);
+    const materialRuntime = useMaterialRuntime(materialProfile, surfaceNodeRef);
+    const composedRef = React.useCallback((node) => {
+        surfaceNodeRef.current = node;
+        if (typeof ref === 'function') {
+            ref(node);
+            return;
+        }
+        if (ref) {
+            ref.current = node;
+        }
+    }, [ref]);
+    const resolvedRole = role ?? landmarkRoleToAttribute(policy.a11y?.landmarkRole);
+    const resolvedAriaLabelledBy = ariaLabelledBy
+        ?? (policy.a11y?.labelStrategy === 'from-header' ? headerId : undefined);
+    const shouldActivateFocusTrap = !a11yManagedByHost
+        && (policy.a11y?.focusTrap === 'on-mount' || (modal && policy.a11y?.focusTrap === 'when-modal'));
+    const shouldActivateScrollContainment = !a11yManagedByHost
+        && modal
+        && policy.a11y?.scrollContainment === 'lock-body';
+    useSurfaceFocusTrap(surfaceNodeRef, shouldActivateFocusTrap);
+    useSurfaceBodyScrollLock(shouldActivateScrollContainment);
+    React.useEffect(() => {
+        if (process.env.NODE_ENV === 'production'
+            // When the host primitive owns a11y (Radix Dialog / Drawer / Sheet /
+            // AlertDialog), the accessible name comes from the host's own title
+            // (e.g. `Dialog.Title` → `aria-labelledby`), NOT from a `Surface.Header`.
+            // The `from-header` strategy is structurally inactive here, so this
+            // warning would fire for EVERY host-managed overlay regardless of whether
+            // it is correctly titled. Defer labelling validation to the host — Radix
+            // emits its own (authoritative) warning when the title is genuinely absent.
+            || a11yManagedByHost
+            || policy.a11y?.labelStrategy !== 'from-header'
+            || !resolvedRole
+            || ariaLabel
+            || ariaLabelledBy
+            || headerId) {
+            return undefined;
+        }
+        const timeout = window.setTimeout(() => {
+            logger.warn('[Surface] labelStrategy "from-header" produced an unlabelled landmark surface', {
+                variant,
+                role: resolvedRole,
+            });
+        }, 0);
+        return () => window.clearTimeout(timeout);
+    }, [a11yManagedByHost, ariaLabel, ariaLabelledBy, headerId, policy.a11y?.labelStrategy, resolvedRole, variant]);
+    const policyStyleAttrs = emitPolicyVars
+        ? {
+            'data-slot': 'surface',
+            'data-surface': '',
+        }
+        : {};
+    const surfaceElement = (_jsx(Comp, { ref: composedRef, ...props, ...policyStyleAttrs, "data-material-kind": materialRuntime['data-material-kind'], "data-material-tier": materialRuntime['data-material-tier'], "data-material-variant": materialRuntime['data-material-variant'], "data-material-depth": materialRuntime['data-material-depth'], "data-material-composition": materialRuntime['data-material-composition'], "data-material-group": materialRuntime['data-material-group'], "data-material-refractive-budget": materialRuntime['data-material-refractive-budget'], tabIndex: shouldActivateFocusTrap && props.tabIndex == null ? -1 : props.tabIndex, "data-surface-focus-trap": shouldActivateFocusTrap ? '' : undefined, "data-surface-scroll-containment": shouldActivateScrollContainment ? '' : undefined, "data-surface-framing-mode": emitPolicyVars ? framingModeToAttribute(policy.nesting?.framingMode) : undefined, "data-surface-frame": emitPolicyVars ? (contextValue.rendersOwnFrame ? 'rendered' : 'suppressed') : undefined, "data-surface-in-framed-ancestor": emitPolicyVars && isNestedInFramedAncestor ? '' : undefined, "data-surface-nearest-framed-ancestor": emitPolicyVars ? nearestFramedAncestorVariant : undefined, "data-surface-nested-radius-strategy": emitPolicyVars ? nestedRadiusStrategyToAttribute(policy.nesting?.nestedRadiusStrategy) : undefined, "data-surface-first-child-edge-strategy": emitPolicyVars ? firstChildEdgeStrategyToAttribute(policy.nesting?.firstChildEdgeStrategy) : undefined, "data-surface-divider-strategy": emitPolicyVars ? dividerStrategyToAttribute(policy.nesting?.dividerStrategy) : undefined, "data-surface-selectable-semantics": emitPolicyVars ? selectableSemanticsToAttribute(policy.interactiveState?.selectableSemantics) : undefined, "data-surface-gesture-opt-in": emitPolicyVars ? gestureOptInToAttribute(policy.interactiveState?.gestureOptIn) : undefined, "data-surface-child-adaptive-density": emitPolicyVars && policy.composition?.childAdaptiveDensity === true ? '' : undefined, "data-surface-selection-column-aware": emitPolicyVars && policy.composition?.selectionColumnAware === true ? '' : undefined, role: resolvedRole, "aria-label": ariaLabel, "aria-labelledby": resolvedAriaLabelledBy, "data-surface-variant": variant, className: cn(visualRecipeClasses, className), style: mergeSurfaceStyle(policy, materialRuntime.style, style, emitPolicyVars, contextValue.rendersOwnFrame, nestedRadius), children: children }));
+    const shouldWrapErrorBoundary = policy.interactiveState?.errorBoundary === 'self';
+    return (_jsx(SurfacePolicyContext.Provider, { value: contextValue, children: shouldWrapErrorBoundary ? (_jsx(SurfaceErrorBoundary, { children: surfaceElement })) : surfaceElement }));
+});
+SurfaceRoot.displayName = 'Surface';
+function surfaceSlotStyle(slot, policy, style) {
+    const gap = policy.containment?.slotGap?.[slot] ?? policy.containment?.gap;
+    const shouldStack = shouldActivateStackLayout(gap);
+    return {
+        '--surface-policy-slot-display': stackDisplayCssValue(shouldStack),
+        '--surface-policy-slot-flex-direction': stackFlexDirectionCssValue(shouldStack),
+        [`--surface-policy-${slot}-gap`]: gapTierToCssValue(gap),
+        ...style,
+    };
+}
+export const SurfaceHeader = React.forwardRef(function SurfaceHeader({ className, id, style, ...props }, ref) {
+    const policy = useSurfacePolicy();
+    const surfaceContext = React.useContext(SurfacePolicyContext);
+    const registerHeaderId = surfaceContext?.registerHeaderId;
+    const unregisterHeaderId = surfaceContext?.unregisterHeaderId;
+    const generatedId = React.useId();
+    const resolvedId = id ?? generatedId;
+    React.useEffect(() => {
+        registerHeaderId?.(resolvedId);
+        return () => unregisterHeaderId?.(resolvedId);
+    }, [registerHeaderId, resolvedId, unregisterHeaderId]);
+    return (_jsx("div", { ref: ref, id: resolvedId, "data-slot": "surface-header", className: cn(className), style: surfaceSlotStyle('header', policy, style), ...props }));
+});
+SurfaceHeader.displayName = 'Surface.Header';
+export const SurfaceBody = React.forwardRef(function SurfaceBody({ className, style, ...props }, ref) {
+    const policy = useSurfacePolicy();
+    return (_jsx("div", { ref: ref, "data-slot": "surface-body", className: cn(className), style: surfaceSlotStyle('body', policy, style), ...props }));
+});
+SurfaceBody.displayName = 'Surface.Body';
+export const SurfaceFooter = React.forwardRef(function SurfaceFooter({ className, style, ...props }, ref) {
+    const policy = useSurfacePolicy();
+    const gap = policy.containment?.slotGap?.footer ?? policy.containment?.gap;
+    const shouldStack = shouldActivateStackLayout(gap);
+    const shouldAlignActions = Boolean(policy.geometry?.actionAlignment && policy.geometry.actionAlignment !== 'inherit');
+    return (_jsx("div", { ref: ref, "data-slot": "surface-footer", className: cn(className), style: {
+            '--surface-policy-slot-display': stackDisplayCssValue(shouldStack || shouldAlignActions),
+            '--surface-policy-slot-flex-direction': stackFlexDirectionCssValue(shouldStack),
+            '--surface-policy-footer-gap': gapTierToCssValue(gap),
+            '--surface-policy-action-alignment': shouldAlignActions
+                ? actionAlignmentToCssValue(policy.geometry?.actionAlignment)
+                : undefined,
+            '--surface-policy-action-alignment-mobile': shouldAlignActions
+                ? actionAlignmentToMobileCssValue(policy.geometry?.actionAlignment)
+                : undefined,
+            ...style,
+        }, ...props }));
+});
+SurfaceFooter.displayName = 'Surface.Footer';
+export const SurfaceAction = React.forwardRef(function SurfaceAction({ className, ...props }, ref) {
+    return (_jsx("div", { ref: ref, "data-slot": "surface-action", className: cn(className), ...props }));
+});
+SurfaceAction.displayName = 'Surface.Action';
+export const Surface = Object.assign(SurfaceRoot, {
+    Header: SurfaceHeader,
+    Body: SurfaceBody,
+    Footer: SurfaceFooter,
+    Action: SurfaceAction,
+});
+//# sourceMappingURL=surface.js.map