FusionSurface

Installation

pnpm add @talex-touch/tuffex

import { TxFusionSurface } from '@talex-touch/tuffex/fusion-surface'
import '@talex-touch/tuffex/fusion-surface/style.css'
import '@talex-touch/tuffex/base.css' // tokens + resets, once per app

Usage

Toolbar Tray

With a stable id, a new center slides the bud over; removing it from buds closes it in place.

Split into a Drop

Once detach passes the break point, the neck snaps: the bud becomes a drop and the stub sinks back into the edge.

Buds on Every Edge

edge picks the side a bud grows from; a bud pushed toward a corner is clamped onto the straight edge.

Best Practices

• Keep buds on one edge apart: each takes its width plus a fillet on each side.
• Keep a bud's id stable while it moves; a new id closes the old bud and grows another.
• To replay a split, close the bud (open: false, or drop it from buds) or use a new id; lowering detach only moves the drop back.
• Give the root no background, border, or box-shadow, and never clip it (overflow: hidden, clip-path, contain: paint); buds take no layout space, so pad the parent.
• Color the surface with var(--tx-…) tokens to follow the theme, and give the shadow to shadow, not to children.

API Reference

Props

Events

Slots

Types

FusionSurfaceBud, one entry of buds:

import type {
  FusionSurfaceBud,
  FusionSurfaceEdge, // 'top' | 'right' | 'bottom' | 'left'
  FusionSurfaceEmits,
  FusionSurfaceProps,
  FusionSurfaceTransition, // 'snappy' | 'smooth' | 'bouncy' | SpringConfig
  TxFusionSurfaceInstance,
  // fusionSurfacePath(), see Geometry function
  FusionSurfaceBudShape,
  FusionSurfaceGeometry,
  FusionSurfaceGeometryInput,
  FusionSurfaceRect,
  FusionSurfaceSpan,
  FusionSurfaceSplit,
} from '@talex-touch/tuffex/fusion-surface'

CSS Variables

The first four are written only for props you pass, so an ancestor or theme can set them.

Geometry function

fusionSurfacePath() is the component's geometry as a pure function, with no Vue or DOM. Use it to draw buds, necks, and drops over a host that can't become a TxFusionSurface.

import type { FusionSurfaceSplit } from '@talex-touch/tuffex/fusion-surface'
import {
  FUSION_SURFACE_BREAK_PINCH,
  fusionSurfacePath,
  fusionSurfacePinch,
  springSteps,
} from '@talex-touch/tuffex/fusion-surface'

const overlayPath = document.querySelector<SVGPathElement>('#composer-overlay path')!
let detach = 0
let velocity = 0
let split: FusionSurfaceSplit | null = null

function frame(dt: number) {
  // The component's spring, velocity kept across retargets.
  ;[detach, velocity] = springSteps(detach, velocity, 44, 'smooth', dt)
  const pinch = fusionSurfacePinch(detach, 28)
  // Latch the break as the component does (it also caps detach at the break point).
  if (!split && pinch >= FUSION_SURFACE_BREAK_PINCH)
    split = { center: 208, width: 168, height: 36, detach, drift: 0, remnant: 1, tail: 1 }
  // …then spring split.remnant and split.tail down to 0 ('snappy').

  const { d } = fusionSurfacePath({
    width: 320,
    height: 48,
    radius: 16,
    includeBody: false, // the host draws its own body
    buds: [{ id: 'message', center: 208, width: 168, height: 36, detach, pinch, split }],
  })
  overlayPath.setAttribute('d', d)
}

A path from includeBody: false closes inside the host. To stroke it, clip away the part inside the host and break the host's own border along spans.

Input

FusionSurfaceGeometryInput:

FusionSurfaceBudShape takes the other fields of FusionSurfaceBud, but describes the current frame rather than a target:

FusionSurfaceSplit:

Output

FusionSurfaceGeometry:

Helpers

• fusionSurfacePinch(detach, breakAt): the component's neck curve; 0 for the first quarter of breakAt, then easing in to 1.
• FUSION_SURFACE_BREAK_PINCH: 0.985, the pinch at which the component latches the split.
• springSteps(position, velocity, target, config, dt): the component's spring integrator; dt is in seconds, and it returns [position, velocity].

Overview

• The silhouette is an SVG inside the root at z-index: -1, pointer-events: none and aria-hidden, under the slot content.
• A bud added to buds grows in place; a removed bud closes first, its content still mounted and inert.
• open, center, width, height, detach, and drift are springs with their own velocity, so a new target bends the motion instead of restarting it.
• A split is latched: lowering detach never rejoins it. Closing a split bud shrinks the drop and its content about the drop's center.
• shadow skips inset and spread layers; a var() layer passes through whole and must hold one layer, like --tx-elevation-*.
• Under reduced motion, tracked live, every spring lands in one frame; a pull past the break still fires break.

Technologies

• One requestAnimationFrame loop per surface integrates the shared springs (liquid/src/spring.ts), recomputes one sharp SVG path, and writes bud layer styles directly; it sleeps at rest.
• The attached bud follows the Dock on uiarc.dev, whose technique was observed and no code taken; the neck is this library's own profile model.
• Source: packages/tuffex/packages/components/src/fusion-surface/.

Use cases

• A toolbar or dock whose tools grow option trays, submenus, or tooltips out of the bar.
• A panel that grows a bubble or badge from its edge and lets it go.
• Sending a message: the composer pinches it off into the thread; over a host you draw yourself, use fusionSurfacePath().

Related components