Skip to content

The Open Standard for Generative UI

3.8 KB
Raw Blame
// Pure path/ramp math for the funnel's multi-ring halo. Kept out of the
// component so the trapezoid geometry, the layer ramp, and the percentage
// semantic are unit-testable in isolation.

export type FunnelOrientation = "horizontal" | "vertical";
export type FunnelEdges = "curved" | "straight";

// Cross-axis half-extent factor: the widest ring spans 0.88 of the cross-axis
// (2 × 0.44), leaving a 12% margin — the headroom a hover scale-pop would use.
const HALF_EXTENT = 0.44;
// Bezier control factor: > 0.5 pushes the curve's inflection past center for a
// fuller "belly" on the tapered edge.
const BEZIER_CONTROL = 0.55;

/**
 * One ring's SVG path for a HORIZONTAL funnel cell (local coords, origin at the
 * cell's top-left; the cell tapers from `normStart` on the left edge to
 * `normEnd` on the right). `layerScale` shrinks the ring toward the core.
 */
export function hSegmentPath(
  normStart: number,
  normEnd: number,
  segW: number,
  H: number,
  layerScale: number,
  straight = false,
): string {
  const my = H / 2;
  const h0 = normStart * H * HALF_EXTENT * layerScale;
  const h1 = normEnd * H * HALF_EXTENT * layerScale;

  if (straight) {
    return `M 0 ${my - h0} L ${segW} ${my - h1} L ${segW} ${my + h1} L 0 ${my + h0} Z`;
  }

  const cx = segW * BEZIER_CONTROL;
  const top = `M 0 ${my - h0} C ${cx} ${my - h0}, ${segW - cx} ${my - h1}, ${segW} ${my - h1}`;
  const bot = `L ${segW} ${my + h1} C ${segW - cx} ${my + h1}, ${cx} ${my + h0}, 0 ${my + h0}`;
  return `${top} ${bot} Z`;
}

/**
 * One ring's SVG path for a VERTICAL funnel cell (local coords, origin at the
 * cell's top-left; the cell tapers from `normStart` on the top edge to
 * `normEnd` on the bottom).
 */
export function vSegmentPath(
  normStart: number,
  normEnd: number,
  segH: number,
  W: number,
  layerScale: number,
  straight = false,
): string {
  const mx = W / 2;
  const w0 = normStart * W * HALF_EXTENT * layerScale;
  const w1 = normEnd * W * HALF_EXTENT * layerScale;

  if (straight) {
    return `M ${mx - w0} 0 L ${mx - w1} ${segH} L ${mx + w1} ${segH} L ${mx + w0} 0 Z`;
  }

  const cy = segH * BEZIER_CONTROL;
  const left = `M ${mx - w0} 0 C ${mx - w0} ${cy}, ${mx - w1} ${segH - cy}, ${mx - w1} ${segH}`;
  const right = `L ${mx + w1} ${segH} C ${mx + w1} ${segH - cy}, ${mx + w0} ${cy}, ${mx + w0} 0`;
  return `${left} ${right} Z`;
}

export interface FunnelRing {
  /** Multiplier on the cross-axis extent; outer rings are larger (scale 1). */
  layerScale: number;
  /** The ring's own opacity in the halo ramp, before any hover dim. */
  ringOpacity: number;
}

/**
 * The halo ramp: `layers` concentric rings, OUTERMOST FIRST (so the solid core
 * paints last — SVG render order is z-order). Outer rings are larger and
 * fainter; the innermost (last) ring is the solid core. A single ring
 * (`layers === 1`) is fully opaque — the raw ramp would otherwise leave a lone
 * core at 0.18, near-invisible.
 */
export function funnelHaloRamp(layers: number): FunnelRing[] {
  const L = Math.max(1, Math.round(layers));
  return Array.from({ length: L }, (_, l) => ({
    layerScale: 1 - (l / L) * 0.35,
    ringOpacity: L === 1 ? 1 : 0.18 + (l / (L - 1)) * 0.65,
  }));
}

/**
 * Funnel percentage: relative to the FIRST stage (stage 0 = 100% = retention),
 * NOT share-of-total. `reference` is the first stage's value. Can exceed 100%
 * or go negative for non-monotonic data — that is informative, not a bug.
 */
export function funnelPercentage(value: number, reference: number): number {
  if (!Number.isFinite(reference) || reference === 0) return 0;
  return (value / reference) * 100;
}

/** A funnel percentage for display: whole numbers, and "<1%" for a stage that
 * isn't empty but rounds to zero. */
export function formatFunnelPercentage(pct: number): string {
  if (pct > 0 && pct < 0.5) return "<1%";
  return `${Math.round(pct)}%`;
}