Border Beam

1"use client"
2 
3import { cn } from "@/lib/utils"
4 
5 
6 
7// @interlace/border-beam v1.1.0 — Interlace design system.
8// Docs, props and live preview: https://ds.interlace.tools/c/border-beam
9// What changed since: https://ds.interlace.tools/c/border-beam#history
10// Generated banner — keep it, the upgrade diff reads this version.
11 
12/**
13 * @interlace/ui — BorderBeam
14 *
15 * A single gradient square that travels around the inside edge of its parent,
16 * drawn with `offset-path` and a two-layer CSS mask so only the border ring
17 * shows. Drop it inside any `relative`, rounded container to give that
18 * container a moving outline.
19 *
20 * It positions itself `absolute inset-0` and inherits the parent's radius, so
21 * the only thing the parent has to supply is a stacking context.
22 *
23 * Our reimplementation of the Magic UI component of the same name, rebuilt on
24 * CSS `offset-path` instead of Framer Motion — the whole effect is one
25 * compositor-driven property and this file imports no animation library.
26 *
27 * ## Anatomy
28 *
29 *   div                              (absolute inset-0, rounded-[inherit],
30 *                                     transparent border + mask-intersect —
31 *                                     this is what clips the beam to the ring)
32 *     └─ div.animate-border-beam     (the beam: an aspect-square gradient
33 *                                     riding `offset-path: rect(… round Npx)`)
34 *
35 * ## Motion
36 *
37 * Pure CSS, and covered twice: `.animate-border-beam` is named in the
38 * `prefers-reduced-motion: reduce` block in `styles/tokens.css`
39 * (`animation: none !important`) and also caught by the `animation-duration`
40 * wildcard in `styles/preflight.css`. There is no `useReducedMotion` call and
41 * none is needed. Note what `reduce` leaves behind: with the animation off,
42 * `offset-distance` sits at its initial `0%`, so the beam parks as a static
43 * gradient square at the start of the path rather than disappearing.
44 *
45 * ## Colour, and why `--chart-2` is allowed here
46 *
47 * `colorFrom` / `colorTo` default to `var(--primary)` → `var(--chart-2)`, the
48 * brand orange-to-green sweep. They were the raw literals `#ffaa40` / `#9c40ff`
49 * (R19), which also meant the beam did not re-resolve per theme.
50 *
51 * `--chart-2` is a 3:1-class token, not a 4.5:1 one, and that is the right
52 * choice HERE specifically: the beam is a decorative overlay inside a container
53 * that draws its own `border`, so it is neither text (SC 1.4.3) nor the
54// … truncated