BaseSurface

Usage

Best Practices

• Prefer TxCard for normal product containers; reach for TxBaseSurface only when a page needs direct material or fallback tuning.
• Use moving when the parent already owns animation state. Use autoDetect for legacy transform transitions where explicit state is unavailable.
• Keep fallbackMode="mask" for readable blur/glass content during motion; use pure only when a flat color is visually acceptable.
• Treat refractionStrength, refractionProfile, and refractionTone as the high-level API. Touch raw channel offsets only for visual experiments.
• Use refractionRenderer="css" only when the page can tolerate the CSS renderer's lower optical fidelity; keep svg for the default premium material.
• Use fake when matching existing .fake-background layering; otherwise keep normal layer rendering for clearer DOM/debugging.

API Reference

TxBaseSurface Props

Slots

Events

None. TxBaseSurface is a visual primitive and does not emit interaction or lifecycle events.

Exposed Methods

None. Drive motion fallback with moving or autoDetect, and update visual state through props.

CSS Variables

Relationship with TxCard

• Use TxCard for out-of-the-box product usage (header/footer/loading/inertial/interaction states).
• Use TxBaseSurface for low-level material tuning (filter/refraction/glass parameter matrix).
• Recommended split: TxCard handles container semantics + interaction, TxBaseSurface handles material rendering.

Background Modes

Five modes compared: pure solid color, mask semi-transparent overlay, blur backdrop blur, glass glass layer, and refraction glass+filter refraction.

Mode Comparison

Advanced Parameter Lab

Use this low-level lab to tune material parameters in filter / refraction workflows. For product-facing card usage, TxCard is still the recommended first choice.

Advanced Lab

Fake Pseudo-Element Mode

Enable pseudo-element background rendering via the fake prop. Slot content naturally sits above the background without extra z-index management. Useful when you need consistency with the existing .fake-background pattern.

Fake Mode

Motion Fallback

When blur or glass mode elements are in a CSS transform animation, backdrop-filter becomes invalidated (known Chromium bug).

Use the moving prop for manual control, or auto-detect for automatic transform detection. The component degrades to fallbackMode (default mask) during motion and smoothly recovers afterward. Refraction degrades per layer: the sampling-stale glass / blur layers fade themselves out while a translucent motion cover holds the visual weight, then cross-fade back on settle — nothing near-opaque ever covers the surface.

Click the button to trigger real transform movement on both blur and glass cards. The cards contain scrollable content inside.

Multi-Mode Motion Fallback

Raw vs BaseSurface Comparison

Left side uses raw backdrop-filter — blur breaks completely during transform motion. Right side uses BaseSurface — gracefully degrades to mask during motion, then smoothly recovers to glass when stopped.

Motion Comparison

Overview

• tag controls the root element and the default slot is rendered above all material layers.
• pure mode renders only the root background; mask renders the mask layer and clamps opacity to 0..1.
• blur and glass degrade while moving=true or auto-detected transform motion is active. fallbackMode='mask' uses fallbackMaskOpacity when provided; fallbackMode='pure' renders no mask layer.
• glass and refraction forward normalized geometry and optical props to TxGlassSurface; brightness <= 3 is treated as a multiplier and converted to a percentage.
• refraction renders glass, filter, mask, optional motion-cover, and edge layers, plus renderer/profile/tone classes and light/strength CSS variables.
• Passing any of refractionStrength / refractionAngle / refractionProfile switches to the derived refraction model (shouldUseRefractionModel); unset ones fall back to 62 / -24 / 'filmic'.
• autoDetect observes the root and ancestor style mutations plus transitionstart, transitionend, and transitioncancel; listeners and observers are removed on unmount.
• settleDelay and transitionDuration both affect fallback recovery. The actual settle timer is at least the transition duration.
• refraction keeps the refraction renderer active during motion, but blends optical parameters down while moving and back up during recovery.

Technologies

• Reviewed against packages/tuffex/packages/components/src/base-surface/src/TxBaseSurface.vue, types.ts, base-surface-motion.ts, base-surface-math.ts, and style/index.scss.
• The CSS-variable table covers every runtime variable the component emits (rows marked internal are interpolation outputs, not override points) plus the consumed theming hook --tx-surface-refraction-mask-color.
• Existing tests cover root tag/radius/color variables, mask opacity clamping, blur fallback, pure fallback, normalized TxGlassSurface props, refraction classes/light variables, and auto-detect teardown.
• No events or exposed methods exist in source; visual state is controlled through props and CSS variables.
• Component source: packages/tuffex/packages/components/src/base-surface/src/TxBaseSurface.vue.
• Types: packages/tuffex/packages/components/src/base-surface/src/types.ts.
• Motion helper: packages/tuffex/packages/components/src/base-surface/src/base-surface-motion.ts.
• Math helper: packages/tuffex/packages/components/src/base-surface/src/base-surface-math.ts.
• Styles: packages/tuffex/packages/components/src/base-surface/src/style/index.scss.
• Verified coverage: packages/tuffex/packages/components/src/base-surface/__tests__/base-surface.test.ts verifies mode rendering, fallback behavior, refraction parameters, and observer cleanup.