@swiftbrowser/web 0.1.0

package/src/styles.ts

@@ -0,0 +1,373 @@
+/**
+ * Colors, ShapeStyles and visual effects → CSS (docs/phase6/styles.md).
+ *
+ * Everything a view is painted with (`style.foreground`, `style.background`,
+ * a shape's `fill` and `stroke.color`) is a `ShapeStyle`: a `Color`
+ * (explicit sRGB, a semantic token or a catalog color), a hierarchical level,
+ * a gradient or a material. A ShapeStyle resolves differently by *role*:
+ * `.secondary` is the secondary label color as text and the secondary fill
+ * color as a background. `styleToCSS` therefore takes the role and returns
+ * the CSS pieces the renderer needs; the renderer decides which property
+ * each piece lands in.
+ *
+ * This module is DOM-free so it can be unit-tested under node.
+ */
+
+import { assetColorVar } from './assets';
+import {
+  isAssetColor,
+  isColor,
+  isColorGradientStyle,
+  isHierarchicalStyle,
+  isLinearGradientStyle,
+  isMaterialStyle,
+  isNamedColor,
+  isRadialGradientStyle,
+  type Color,
+  type GradientStop,
+  type MaterialName,
+  type ShapeStyle,
+  type Style,
+  type UnitPoint,
+} from './protocol';
+
+// ---------------------------------------------------------------------------
+// Colors
+// ---------------------------------------------------------------------------
+
+const SEMANTIC_COLOR_VAR: Record<string, string> = {
+  primary: 'var(--sb-color-primary)',
+  secondary: 'var(--sb-color-secondary)',
+  accent: 'var(--sb-color-accent)',
+  systemBackground: 'var(--sb-color-system-background)',
+  secondarySystemBackground: 'var(--sb-color-secondary-system-background)',
+  clear: 'transparent',
+};
+
+/** CSS `<color>` for a protocol `Color`. */
+export function colorToCSS(color: Color): string {
+  if (isAssetColor(color)) {
+    // The catalog's light/dark values live in `--sb-asset-color-<slug>`
+    // (see `Renderer.setAssetCatalog`); a name the catalog lacks has no
+    // property and falls back to magenta so it stands out.
+    return withOpacity(`var(${assetColorVar(color.named)}, magenta)`, color.opacity);
+  }
+  if (isNamedColor(color)) {
+    const token = SEMANTIC_COLOR_VAR[color.name] ?? `var(--sb-color-${camelToKebab(color.name)})`;
+    if (token === 'transparent') return token;
+    // Opacity multiplier on a semantic token. `color-mix` keeps the token
+    // live across theme changes; mixing with `transparent` scales alpha.
+    return withOpacity(token, color.a);
+  }
+  const c = (v: number) => Math.round(clamp01(v) * 255);
+  const a = color.a ?? 1;
+  return `rgba(${c(color.r)}, ${c(color.g)}, ${c(color.b)}, ${clamp01(a)})`;
+}
+
+function clamp01(v: number): number {
+  return Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : 1;
+}
+
+/** `token` at `alpha` (0...1): `color-mix` with transparent keeps a `var()` live across themes. */
+function withOpacity(token: string, alpha: number | undefined): string {
+  if (alpha == null || !Number.isFinite(alpha) || alpha >= 1) return token;
+  const pct = Math.round(clamp01(alpha) * 1000) / 10;
+  return `color-mix(in srgb, ${token} ${pct}%, transparent)`;
+}
+
+function camelToKebab(name: string): string {
+  return name.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+}
+
+// ---------------------------------------------------------------------------
+// ShapeStyles
+// ---------------------------------------------------------------------------
+
+/**
+ * `text`: the style colors glyphs (`style.foreground`). `paint`: it fills an
+ * area (`style.background`, a shape's `fill` or `stroke.color`).
+ */
+export type PaintRole = 'text' | 'paint';
+
+export interface PaintCSS {
+  /** `color` for a flat style, `gradient` for a CSS `<image>`, `material` for a translucent fill. */
+  kind: 'color' | 'gradient' | 'material';
+  /**
+   * What to paint with: a `<color>` (`color`, `material`) or an `<image>`
+   * (`gradient`). Valid as a `background` shorthand value either way.
+   */
+  value: string;
+  /**
+   * A `<color>` that stands in for the style where an image cannot be used:
+   * border colors, `currentColor` consumers such as symbols, the text color
+   * behind a gradient. The value itself for flat styles, the first stop for
+   * gradients, the base color for materials.
+   */
+  solid: string;
+  /** Materials only: the `backdrop-filter` to apply alongside `value`. */
+  backdropFilter?: string;
+}
+
+/** Label colors (text role) and fill colors (paint role) per hierarchical level. */
+const HIERARCHICAL_TEXT: Record<1 | 2 | 3 | 4, string> = {
+  1: 'var(--sb-color-primary)',
+  2: 'var(--sb-color-secondary)',
+  3: 'var(--sb-color-tertiary-label)',
+  4: 'var(--sb-color-quaternary-label)',
+};
+const HIERARCHICAL_PAINT: Record<1 | 2 | 3 | 4, string> = {
+  1: 'var(--sb-color-fill)',
+  2: 'var(--sb-color-secondary-fill)',
+  3: 'var(--sb-color-tertiary-fill)',
+  4: 'var(--sb-color-quaternary-fill)',
+};
+
+/** Opacity of the system background each material shows over the blurred backdrop. */
+export const MATERIAL_ALPHA: Record<MaterialName, number> = {
+  ultraThin: 0.55,
+  thin: 0.7,
+  regular: 0.82,
+  thick: 0.9,
+  ultraThick: 0.96,
+};
+export const MATERIAL_BLUR = 'blur(20px)';
+
+/**
+ * Resolve a ShapeStyle for a role. Unknown shapes resolve to magenta so they
+ * stand out. A non-color style's top-level `opacity` multiplies the result
+ * (each stop of a gradient, the material's alpha) like a semantic color's `a`.
+ */
+export function styleToCSS(style: ShapeStyle, role: PaintRole): PaintCSS {
+  if (isColor(style)) {
+    const value = colorToCSS(style);
+    return { kind: 'color', value, solid: value };
+  }
+  const opacity = style.opacity;
+  if (isHierarchicalStyle(style)) {
+    const level = hierarchicalLevel(style.hierarchical);
+    const value = withOpacity(role === 'text' ? HIERARCHICAL_TEXT[level] : HIERARCHICAL_PAINT[level], opacity);
+    return { kind: 'color', value, solid: value };
+  }
+  if (isLinearGradientStyle(style)) {
+    const { stops, start, end } = style.linearGradient;
+    return gradient(linearGradientCSS(stops ?? [], start, end, opacity), stops, opacity);
+  }
+  if (isRadialGradientStyle(style)) {
+    const { stops, center, startRadius, endRadius } = style.radialGradient;
+    return gradient(radialGradientCSS(stops ?? [], center, startRadius, endRadius, opacity), stops, opacity);
+  }
+  if (isColorGradientStyle(style)) {
+    const base = colorToCSS(style.colorGradient);
+    const light = withOpacity(`color-mix(in srgb, ${base}, white 12%)`, opacity);
+    const dark = withOpacity(`color-mix(in srgb, ${base}, black 12%)`, opacity);
+    return { kind: 'gradient', value: `linear-gradient(to bottom, ${light}, ${dark})`, solid: withOpacity(base, opacity) };
+  }
+  if (isMaterialStyle(style)) {
+    const alpha = MATERIAL_ALPHA[style.material] ?? MATERIAL_ALPHA.regular;
+    const value = `rgba(var(--sb-color-material-base), ${round(alpha * (opacity == null || !Number.isFinite(opacity) ? 1 : clamp01(opacity)))})`;
+    return { kind: 'material', value, solid: value, backdropFilter: MATERIAL_BLUR };
+  }
+  return { kind: 'color', value: 'magenta', solid: 'magenta' };
+}
+
+function hierarchicalLevel(level: number): 1 | 2 | 3 | 4 {
+  return level === 2 || level === 3 || level === 4 ? level : 1;
+}
+
+function gradient(value: string, stops: readonly GradientStop[] | undefined, opacity: number | undefined): PaintCSS {
+  const first = stops?.[0]?.color;
+  return { kind: 'gradient', value, solid: first ? withOpacity(colorToCSS(first), opacity) : 'transparent' };
+}
+
+/**
+ * `linear-gradient(<angle>, ...)` for a gradient from `start` to `end` (unit
+ * points). CSS measures angles clockwise from "to top", so the angle is
+ * atan2(dx, −dy). The gradient line of a CSS gradient always spans the whole
+ * box, so the stop locations are mapped onto the projections of `start` and
+ * `end` on that line (exact for axis-aligned gradients; a unit square is
+ * assumed otherwise, which is close enough for the usual corner-to-corner
+ * gradients).
+ */
+export function linearGradientCSS(
+  stops: readonly GradientStop[],
+  start: UnitPoint | undefined,
+  end: UnitPoint | undefined,
+  opacity?: number,
+): string {
+  const sx = unit(start?.x, 0.5);
+  const sy = unit(start?.y, 0);
+  const ex = unit(end?.x, 0.5);
+  const ey = unit(end?.y, 1);
+  const dx = ex - sx;
+  const dy = ey - sy;
+  const radians = dx === 0 && dy === 0 ? Math.PI : Math.atan2(dx, -dy);
+  const degrees = round((((radians * 180) / Math.PI) % 360 + 360) % 360);
+  // Position of a unit point along the gradient line (0 at its start, 1 at its end).
+  const sin = Math.sin(radians);
+  const cos = Math.cos(radians);
+  const length = Math.abs(sin) + Math.abs(cos);
+  const along = (x: number, y: number) => ((x - 0.5) * sin - (y - 0.5) * cos) / length + 0.5;
+  const from = along(sx, sy);
+  const to = along(ex, ey);
+  const stopList = stopsCSS(stops, (location) => from + location * (to - from), opacity);
+  return `linear-gradient(${degrees}deg, ${stopList})`;
+}
+
+/** `radial-gradient(circle <endRadius>px at <cx>% <cy>%, ...)`; the stops span startRadius...endRadius. */
+export function radialGradientCSS(
+  stops: readonly GradientStop[],
+  center: UnitPoint | undefined,
+  startRadius: number | undefined,
+  endRadius: number | undefined,
+  opacity?: number,
+): string {
+  const cx = unit(center?.x, 0.5);
+  const cy = unit(center?.y, 0.5);
+  const r1 = endRadius != null && Number.isFinite(endRadius) && endRadius > 0 ? endRadius : null;
+  const r0 = Math.max(0, startRadius != null && Number.isFinite(startRadius) ? startRadius : 0);
+  const size = r1 == null ? 'farthest-corner' : `${round(r1)}px`;
+  const list = stopsCSS(stops, (location) => (r1 == null ? location : (r0 + location * (r1 - r0)) / r1), opacity);
+  return `radial-gradient(circle ${size} at ${round(cx * 100)}% ${round(cy * 100)}%, ${list})`;
+}
+
+/**
+ * `color pct%, ...`, with `map` turning a stop location into a 0...1 position
+ * and `opacity` multiplying every stop. Degenerate lists are padded to two stops.
+ */
+function stopsCSS(stops: readonly GradientStop[], map: (location: number) => number, opacity: number | undefined): string {
+  const list = stops
+    .filter((stop) => stop && typeof stop === 'object' && stop.color)
+    .map((stop) => `${withOpacity(colorToCSS(stop.color), opacity)} ${round(clamp01(map(unit(stop.location, 0))) * 100)}%`);
+  if (list.length === 0) return 'transparent 0%, transparent 100%';
+  if (list.length === 1) return `${list[0]}, ${list[0]!.replace(/ [\d.]+%$/, ' 100%')}`;
+  return list.join(', ');
+}
+
+function unit(v: number | undefined, fallback: number): number {
+  return v != null && Number.isFinite(v) ? v : fallback;
+}
+
+function round(v: number): number {
+  return Math.round(v * 1000) / 1000;
+}
+
+// ---------------------------------------------------------------------------
+// Visual effects
+// ---------------------------------------------------------------------------
+
+export interface EffectsCSS {
+  /**
+   * `translate(...) rotate(...) perspective(...) rotate3d(...) scale(...)`,
+   * in that order (Phase 8 adds the 3D pair); undefined when none applies.
+   */
+  transform?: string;
+  /** From `rotationAnchor`, else `rotation3D.anchor`, else `scaleAnchor` (unit point → percentages). */
+  transformOrigin?: string;
+  /** `blur(radius)` (Phase 8) then `drop-shadow(x y radius color)`, whichever apply. */
+  filter?: string;
+  /** Phase 7 `.hidden()`: `visibility: hidden; pointer-events: none` (the layout is kept). */
+  hidden?: boolean;
+  /** Phase 7 `.mask { }`: the `mask-image` (and `-webkit-mask-image`) value, see `maskImageCSS`. */
+  maskImage?: string;
+}
+
+/** CSS perspective distance (px) for SwiftUI's default `perspective: 1`. */
+export const PERSPECTIVE_BASE_PX = 500;
+
+/**
+ * The CSS of a style's offset, rotation, 3D rotation, scale, blur and shadow.
+ * The transform is composed as translate, then rotate, then (Phase 8)
+ * `perspective() rotate3d()`, then scale: CSS applies the list right to left,
+ * so the box is scaled first, turned in 3D and projected, turned in 2D and
+ * finally offset, which is the order SwiftUI's modifiers nest in
+ * (`.scaleEffect` innermost, `.offset` outermost) in the HackingWithSwift
+ * examples. CSS has one `transform-origin`, so when several anchors are
+ * present and differ the rotation anchor wins, then the 3D anchor, then the
+ * scale anchor (see docs/phase6/styles.md). The 3D perspective distance is
+ * `500px / perspective` (a smaller SwiftUI perspective is a flatter
+ * projection, as `perspective: 0.5` is in SwiftUI).
+ */
+export function effectsCSS(style: Style): EffectsCSS {
+  const out: EffectsCSS = {};
+  const transforms: string[] = [];
+  if (style.offset) {
+    const x = finite(style.offset.x);
+    const y = finite(style.offset.y);
+    if (x || y) transforms.push(`translate(${x}px, ${y}px)`);
+  }
+  if (style.rotation != null && Number.isFinite(style.rotation) && style.rotation !== 0) {
+    transforms.push(`rotate(${round(style.rotation)}deg)`);
+  }
+  // Phase 8 `.rotation3DEffect`: a zero angle or a zero axis is the identity.
+  const r3 = style.rotation3D;
+  if (r3 && typeof r3 === 'object' && Number.isFinite(r3.angle) && r3.angle !== 0) {
+    const ax = finite(r3.axis?.x);
+    const ay = finite(r3.axis?.y);
+    const az = finite(r3.axis?.z);
+    if (ax || ay || az) {
+      const p = r3.perspective != null && Number.isFinite(r3.perspective) && r3.perspective > 0 ? r3.perspective : 1;
+      transforms.push(`perspective(${round(PERSPECTIVE_BASE_PX / p)}px)`);
+      transforms.push(`rotate3d(${round(ax)}, ${round(ay)}, ${round(az)}, ${round(r3.angle)}deg)`);
+    }
+  }
+  if (style.scale) {
+    const x = style.scale.x != null && Number.isFinite(style.scale.x) ? style.scale.x : 1;
+    const y = style.scale.y != null && Number.isFinite(style.scale.y) ? style.scale.y : 1;
+    if (x !== 1 || y !== 1) transforms.push(`scale(${round(x)}, ${round(y)})`);
+  }
+  if (transforms.length) out.transform = transforms.join(' ');
+  const anchor = style.rotationAnchor ?? (r3 && typeof r3 === 'object' ? r3.anchor : undefined) ?? style.scaleAnchor;
+  if (anchor && transforms.length) {
+    out.transformOrigin = `${round(unit(anchor.x, 0.5) * 100)}% ${round(unit(anchor.y, 0.5) * 100)}%`;
+  }
+  const filters: string[] = [];
+  // Phase 8 `.blur(radius:)` first, so the shadow is cast by the blurred shape.
+  if (style.blur != null && Number.isFinite(style.blur) && style.blur > 0) {
+    filters.push(`blur(${round(style.blur)}px)`);
+  }
+  if (style.shadow) {
+    const { color, radius, x, y } = style.shadow;
+    const css = color ? colorToCSS(color) : 'rgba(0, 0, 0, 0.33)';
+    filters.push(`drop-shadow(${finite(x)}px ${finite(y)}px ${Math.max(0, finite(radius))}px ${css})`);
+  }
+  if (filters.length) out.filter = filters.join(' ');
+  // Phase 7.
+  if (style.hidden === true) out.hidden = true;
+  if (style.mask && typeof style.mask === 'object') out.maskImage = maskImageCSS(style.mask);
+  return out;
+}
+
+/**
+ * Phase 7 `.mask { }` with a ShapeStyle: a CSS `mask-image` whose alpha is
+ * the style's. A `linearGradient` / `radialGradient` becomes the matching CSS
+ * gradient (only its alpha matters to a mask, so the stop colors are kept as
+ * they are); `Color.gradient` the same vertical gradient the paint uses; a
+ * `Color` a solid mask at the color's alpha (`rgba(0, 0, 0, a)` twice, so a
+ * clear color hides the view and an opaque one shows it whole); a
+ * hierarchical style or material a solid mask at its `opacity` (1 by default).
+ */
+export function maskImageCSS(style: ShapeStyle): string {
+  if (isLinearGradientStyle(style)) {
+    const { stops, start, end } = style.linearGradient;
+    return linearGradientCSS(stops ?? [], start, end, style.opacity);
+  }
+  if (isRadialGradientStyle(style)) {
+    const { stops, center, startRadius, endRadius } = style.radialGradient;
+    return radialGradientCSS(stops ?? [], center, startRadius, endRadius, style.opacity);
+  }
+  if (isColorGradientStyle(style)) return styleToCSS(style, 'paint').value;
+  const alpha = isColor(style) ? colorAlpha(style) : clamp01(style.opacity ?? 1);
+  const solid = `rgba(0, 0, 0, ${round(alpha)})`;
+  return `linear-gradient(${solid}, ${solid})`;
+}
+
+/** The alpha of a protocol `Color`: `a` (explicit and semantic), `opacity` (catalog); `clear` is 0. */
+function colorAlpha(color: Color): number {
+  if (isAssetColor(color)) return clamp01(color.opacity ?? 1);
+  if (isNamedColor(color)) return color.name === 'clear' ? 0 : clamp01(color.a ?? 1);
+  return clamp01(color.a ?? 1);
+}
+
+function finite(v: number | undefined): number {
+  return v != null && Number.isFinite(v) ? v : 0;
+}

package/src/swipe.ts

@@ -0,0 +1,110 @@
+/**
+ * Phase 8 swipe-action geometry (docs/ops-protocol.md, "Swipe actions"),
+ * DOM-free so it can be unit-tested: how far a row's content may slide, and
+ * where it settles when the pointer lifts.
+ *
+ * Offsets are the content's horizontal translation in points: negative
+ * reveals the trailing actions (on the right), positive the leading ones.
+ */
+
+/** Width of one swipe action button. */
+export const SWIPE_ACTION_WIDTH = 74;
+/** Pulling this far past the actions' total width performs the first action. */
+export const SWIPE_FULL_EXTRA = 60;
+/** The content must travel this far before a pan counts as a swipe. */
+export const SWIPE_START_DISTANCE = 8;
+/** A release faster than this (points per second) opens or closes in the direction of travel. */
+export const SWIPE_FLING_VELOCITY = 300;
+
+export type SwipeEdge = 'leading' | 'trailing';
+
+export interface SwipeEdgeSpec {
+  /** Number of actions on this edge (0: nothing to reveal). */
+  count: number;
+  /** Whether pulling past the actions' width + 60 performs the first one. */
+  fullSwipe: boolean;
+}
+
+export interface SwipeSpec {
+  trailing: SwipeEdgeSpec;
+  leading: SwipeEdgeSpec;
+}
+
+/** Total width of an edge's action buttons. */
+export function swipeActionsWidth(count: number): number {
+  return Math.max(0, count) * SWIPE_ACTION_WIDTH;
+}
+
+/** The edge a content offset reveals (`null` at rest). */
+export function swipeEdgeOf(offset: number): SwipeEdge | null {
+  if (offset < 0) return 'trailing';
+  if (offset > 0) return 'leading';
+  return null;
+}
+
+/**
+ * Clamp a raw pan offset to what the row can show: nothing toward an edge
+ * without actions; otherwise up to the actions' width, then with rubber-band
+ * resistance (a full swipe is still reachable) up to the row's width.
+ */
+export function clampSwipeOffset(raw: number, spec: SwipeSpec, rowWidth: number): number {
+  const edge = swipeEdgeOf(raw);
+  if (!edge) return 0;
+  const count = spec[edge].count;
+  if (count === 0) return 0;
+  const sign = edge === 'trailing' ? -1 : 1;
+  const distance = Math.abs(raw);
+  const total = swipeActionsWidth(count);
+  if (distance <= total) return sign * distance;
+  // Past the buttons the content keeps following, slowed down, up to the row width.
+  const extra = distance - total;
+  const slowed = spec[edge].fullSwipe ? extra * 0.85 : extra * 0.35;
+  return sign * Math.min(rowWidth, total + slowed);
+}
+
+export type SwipeSettle = 'closed' | 'open' | 'full';
+
+/**
+ * Where the content goes when the pointer lifts at `offset` with `velocity`
+ * (points per second, same sign convention): `full` performs the edge's
+ * first action, `open` parks at the actions' width, `closed` returns to 0.
+ */
+export function settleSwipe(offset: number, velocity: number, spec: SwipeSpec): SwipeSettle {
+  const edge = swipeEdgeOf(offset);
+  if (!edge) return 'closed';
+  const { count, fullSwipe } = spec[edge];
+  if (count === 0) return 'closed';
+  const total = swipeActionsWidth(count);
+  const distance = Math.abs(offset);
+  const sign = edge === 'trailing' ? -1 : 1;
+  // Velocity in the revealing direction is positive.
+  const along = velocity * sign;
+  if (fullSwipe && distance > total + SWIPE_FULL_EXTRA) return 'full';
+  if (along > SWIPE_FLING_VELOCITY) return 'open';
+  if (along < -SWIPE_FLING_VELOCITY) return 'closed';
+  return distance > total / 2 ? 'open' : 'closed';
+}
+
+/** The resting offset of a settled row. */
+export function swipeRestOffset(settle: SwipeSettle, edge: SwipeEdge, spec: SwipeSpec): number {
+  if (settle === 'closed') return 0;
+  const sign = edge === 'trailing' ? -1 : 1;
+  return sign * swipeActionsWidth(spec[edge].count);
+}
+
+/**
+ * Velocity estimate from pointer samples: the displacement over the samples
+ * of the last `windowMs` (at least the last two), in points per second.
+ */
+export function velocityFrom(samples: readonly { t: number; x: number; y: number }[], windowMs = 100): { x: number; y: number } {
+  if (samples.length < 2) return { x: 0, y: 0 };
+  const last = samples[samples.length - 1]!;
+  let first = samples[samples.length - 2]!;
+  for (let i = samples.length - 2; i >= 0; i--) {
+    const s = samples[i]!;
+    if (last.t - s.t > windowMs) break;
+    first = s;
+  }
+  const dt = Math.max(1, last.t - first.t);
+  return { x: ((last.x - first.x) / dt) * 1000, y: ((last.y - first.y) / dt) * 1000 };
+}