@teleporthq/teleport-shared 0.43.70 → 0.43.71

package/src/scroll-scene/engine-source.ts

@@ -0,0 +1,330 @@
+/**
+ * The scroll-scene lane engine as SOURCE TEXT: the constants, the lane presets
+ * and the functions that parse a `data-scroll-bind`, read a lane at a progress
+ * and write it onto an element. It is plain DOM JavaScript with no framework in
+ * it, which is why two runtimes can share it word for word:
+ *
+ *   - the Next export wraps it in the TqScrollScene React component, where
+ *     framer-motion supplies the scroll progress;
+ *   - the HTML export wraps it in a small vanilla controller, where a scroll
+ *     listener supplies the same progress.
+ *
+ * One copy means a new lane property or preset reaches both exports at once.
+ * The text mirrors the canvas renderer's scroll-scene-lanes module, so the
+ * canvas, the Next site and the HTML site move identically. (No backticks in
+ * the engine's own comments: it is a template literal.)
+ */
+import { settledMomentForLanes } from './moment'
+import { activeChapterIndex } from './chapter-index'
+import { passedScenePoints, scenePointList, scenePointRank } from './points'
+import { unclipStickyAncestors } from './unclip'
+
+export const scrollSceneEngineSource = (): string => `const SCROLL_BIND_ATTR = 'data-scroll-bind'
+// A chapter coming on stage is announced on the chapter element (bubbling), so
+// a workflow trigger bound to the chapter can listen without knowing the scene.
+const CHAPTER_REACHED_EVENT = 'tq-chapter-reached'
+const CHAPTER_ACTIVE_ATTR = 'data-chapter-active'
+const CHAPTER_COUNT_ATTR = 'data-chapter-count'
+// Scrolling DOWN past a quarter / halfway / three quarters / the end of the
+// scene is announced on the track (the element with the scene's id), bubbling;
+// the furthest point passed so far is stamped for listeners that attach later.
+const SCENE_POINT_EVENT = 'tq-scene-point-passed'
+const SCENE_POINT_ATTR = 'data-scene-point'
+
+const LANE_PROPS = [
+  'x',
+  'y',
+  'scale',
+  'rotate',
+  'rotate-x',
+  'rotate-y',
+  'opacity',
+  'blur',
+  'grayscale',
+  'saturate',
+  'brightness',
+  'clip',
+  'clip-y',
+  'count',
+]
+
+// Mirrors SCROLL_COUNT_ATTR / SCROLL_COUNT_CSS in the editor's lane contract.
+const COUNT_ATTR = 'data-scroll-count'
+const HIDDEN_ATTR = 'data-scene-hidden'
+const HIDDEN_CSS =
+  '[data-scene-hidden], [data-scene-hidden] * { pointer-events: none !important; }'
+const COUNT_CSS =
+  '[data-scroll-count]::before { counter-reset: tq-count var(--tq-count, 0); content: counter(tq-count); }'
+const clampPercent = (value) => Math.min(100, Math.max(0, Math.round(value * 100) / 100))
+
+const LANE_PRESETS = {
+  'depth-1': [{ prop: 'y', at: [0, 1], values: [40, -40] }],
+  'depth-2': [{ prop: 'y', at: [0, 1], values: [80, -80] }],
+  'depth-3': [{ prop: 'y', at: [0, 1], values: [140, -140] }],
+  'fade-window': [{ prop: 'opacity', at: [0, 0.15, 0.85, 1], values: [0, 1, 1, 0] }],
+  'rail-x': [{ prop: 'x', at: [0, 1], values: [0, -100], unit: '%' }],
+  'zoom-through': [{ prop: 'scale', at: [0, 1], values: [0.85, 1.1] }],
+  'unblur-in': [{ prop: 'blur', at: [0, 0.3], values: [10, 0] }],
+  'rise-in': [
+    { prop: 'y', at: [0, 0.35], values: [70, 0] },
+    { prop: 'opacity', at: [0, 0.3], values: [0, 1] },
+  ],
+  'ghost-out': [
+    { prop: 'opacity', at: [0.7, 1], values: [1, 0] },
+    { prop: 'blur', at: [0.7, 1], values: [0, 8] },
+  ],
+  'color-in': [{ prop: 'grayscale', at: [0, 0.45], values: [1, 0] }],
+  'sun-up': [{ prop: 'brightness', at: [0, 0.4], values: [0.35, 1] }],
+  'fade-to-mono': [
+    { prop: 'grayscale', at: [0.6, 1], values: [0, 1] },
+    { prop: 'saturate', at: [0.6, 1], values: [1, 0.6] },
+  ],
+  'crash-zoom': [
+    { prop: 'scale', at: [0, 0.25], values: [1.6, 1] },
+    { prop: 'opacity', at: [0, 0.15], values: [0, 1] },
+  ],
+  'tilt-reveal': [
+    { prop: 'rotate-x', at: [0, 0.4], values: [35, 0] },
+    { prop: 'opacity', at: [0, 0.3], values: [0, 1] },
+  ],
+  'spin-in': [
+    { prop: 'rotate', at: [0, 0.35], values: [-90, 0] },
+    { prop: 'opacity', at: [0, 0.25], values: [0, 1] },
+  ],
+  breathe: [{ prop: 'scale', at: [0, 0.5, 1], values: [0.98, 1.03, 0.98] }],
+}
+
+const isValidLane = (lane) => {
+  if (!lane || typeof lane !== 'object' || !LANE_PROPS.includes(lane.prop)) {
+    return false
+  }
+  if (!Array.isArray(lane.at) || !Array.isArray(lane.values)) {
+    return false
+  }
+  if (lane.at.length < 2 || lane.at.length !== lane.values.length) {
+    return false
+  }
+  const numbers = (list) => list.every((entry) => typeof entry === 'number' && isFinite(entry))
+  if (!numbers(lane.at) || !numbers(lane.values)) {
+    return false
+  }
+  for (let index = 1; index < lane.at.length; index++) {
+    if (lane.at[index] < lane.at[index - 1]) {
+      return false
+    }
+  }
+  return lane.unit === undefined || lane.unit === 'px' || lane.unit === '%' || lane.unit === 'vw'
+}
+
+${settledMomentForLanes.toString()}
+
+${activeChapterIndex.toString()}
+
+${scenePointList.toString()}
+
+${passedScenePoints.toString()}
+
+${scenePointRank.toString()}
+
+${unclipStickyAncestors.toString()}
+
+const parseScrollBind = (value) => {
+  const raw = String(value || '').trim()
+  if (!raw) {
+    return []
+  }
+  if (LANE_PRESETS[raw]) {
+    return LANE_PRESETS[raw].map((lane) => ({ ...lane }))
+  }
+  if (!raw.startsWith('[')) {
+    return []
+  }
+  try {
+    const parsed = JSON.parse(raw)
+    return Array.isArray(parsed) ? parsed.filter(isValidLane) : []
+  } catch (e) {
+    return []
+  }
+}
+
+const laneValueAt = (lane, p) => {
+  const at = lane.at
+  const values = lane.values
+  if (p <= at[0]) {
+    return values[0]
+  }
+  if (p >= at[at.length - 1]) {
+    return values[values.length - 1]
+  }
+  for (let index = 1; index < at.length; index++) {
+    if (p <= at[index]) {
+      const span = at[index] - at[index - 1]
+      const local = span === 0 ? 1 : (p - at[index - 1]) / span
+      return values[index - 1] + (values[index] - values[index - 1]) * local
+    }
+  }
+  return values[values.length - 1]
+}
+
+const FILTER_PROP_ORDER = ['blur', 'grayscale', 'saturate', 'brightness']
+
+// Motion lanes write the INDIVIDUAL transform properties (translate / scale /
+// rotate) and never the transform property itself: the browser composes them
+// with whatever the author put in transform (a translateX(-50%) centering, a
+// tilt), so the scene never clobbers the user's own layout. 3D lanes use the
+// axis form of rotate; the stage supplies the vanishing point. Mirrors the
+// canvas. (No backticks in this file's comments — it is a template literal.)
+const applyLanesAt = (element, lanes, p) => {
+  const filterByProp = {}
+  let translateX
+  let translateY
+  let rotate
+  let scale
+  for (const lane of lanes) {
+    const value = laneValueAt(lane, p)
+    switch (lane.prop) {
+      case 'x':
+        translateX = value + (lane.unit || 'px')
+        break
+      case 'y':
+        translateY = value + (lane.unit || 'px')
+        break
+      case 'scale':
+        scale = String(value)
+        break
+      case 'rotate':
+        rotate = rotate === undefined ? value + 'deg' : rotate
+        break
+      case 'rotate-x':
+        rotate = 'x ' + value + 'deg'
+        break
+      case 'rotate-y':
+        rotate = 'y ' + value + 'deg'
+        break
+      case 'opacity':
+        element.style.opacity = String(value)
+        // A faded-out element must not swallow clicks (stacked chapters: the
+        // invisible top one would take every tap meant for the visible story).
+        // Attribute + CSS rule, never inline pointer-events, so lanes cannot
+        // overwrite a pointer-events the author set. Mirrors the editor.
+        if (value <= 0.02) {
+          element.setAttribute(HIDDEN_ATTR, '')
+        } else {
+          element.removeAttribute(HIDDEN_ATTR)
+        }
+        break
+      case 'blur':
+        filterByProp.blur = 'blur(' + value + 'px)'
+        break
+      case 'grayscale':
+        filterByProp.grayscale = 'grayscale(' + value + ')'
+        break
+      case 'saturate':
+        filterByProp.saturate = 'saturate(' + value + ')'
+        break
+      case 'brightness':
+        filterByProp.brightness = 'brightness(' + value + ')'
+        break
+      case 'clip':
+        element.style.clipPath = 'inset(0 ' + clampPercent(100 - value) + '% 0 0)'
+        break
+      case 'clip-y':
+        element.style.clipPath = 'inset(0 0 ' + clampPercent(100 - value) + '% 0)'
+        break
+      case 'count':
+        element.style.setProperty('--tq-count', String(Math.round(value)))
+        if (!element.hasAttribute(COUNT_ATTR)) {
+          element.setAttribute(COUNT_ATTR, '')
+        }
+        break
+    }
+  }
+  if (translateX !== undefined || translateY !== undefined) {
+    element.style.translate = (translateX || '0px') + ' ' + (translateY || '0px')
+  }
+  if (scale !== undefined) {
+    element.style.scale = scale
+  }
+  if (rotate !== undefined) {
+    element.style.rotate = rotate
+  }
+  const filterParts = FILTER_PROP_ORDER.map((prop) => filterByProp[prop]).filter(Boolean)
+  if (filterParts.length > 0) {
+    element.style.filter = filterParts.join(' ')
+  }
+}
+
+// A scene set to keep the story for visitors who ask for less motion
+// (scene-reduced-motion "story"): the scroll still drives the scene, chapters
+// still come and go and every text still appears in turn, but nothing moves.
+// Slides, zooms, rotations and wipes are dropped, so each element stays where
+// the layout puts it; fades and filters still follow the scroll; a counting
+// number shows the figure it counts to. Mirrors the editor's lane contract.
+const MOVEMENT_PROPS = ['x', 'y', 'scale', 'rotate', 'rotate-x', 'rotate-y', 'clip', 'clip-y']
+
+const storyLanes = (lanes) =>
+  lanes
+    .filter((lane) => !MOVEMENT_PROPS.includes(lane.prop))
+    .map((lane) => {
+      if (lane.prop !== 'count') {
+        return lane
+      }
+      const figure = lane.values[lane.values.length - 1]
+      return { prop: 'count', at: [0, 1], values: [figure, figure] }
+    })
+
+// What a moving lane painted, taken off again when the scene switches to the
+// story without movement while the page is open.
+const clearMovement = (element, lanes) => {
+  for (const lane of lanes) {
+    if (lane.prop === 'x' || lane.prop === 'y') {
+      element.style.translate = ''
+    } else if (lane.prop === 'scale') {
+      element.style.scale = ''
+    } else if (lane.prop === 'rotate' || lane.prop === 'rotate-x' || lane.prop === 'rotate-y') {
+      element.style.rotate = ''
+    } else if (lane.prop === 'clip' || lane.prop === 'clip-y') {
+      element.style.clipPath = ''
+    }
+  }
+}
+
+// A row wider than the stage that travelled sideways with the scroll (a
+// rail) would show only its first cards once the movement is dropped, so it
+// becomes a row the visitor swipes: every card stays reachable.
+const SWIPE_ATTR = 'data-scene-swipe'
+const letRowsSwipe = (bound, stage) => {
+  if (!stage) {
+    return
+  }
+  const stageWidth = stage.getBoundingClientRect().width
+  for (const child of bound) {
+    const travels = child.lanes.some((lane) => lane.prop === 'x')
+    if (!travels || child.element.getBoundingClientRect().width <= stageWidth + 1) {
+      continue
+    }
+    child.element.style.maxWidth = '100%'
+    child.element.style.overflowX = 'auto'
+    child.element.setAttribute(SWIPE_ATTR, '')
+  }
+}
+
+const collectBound = (track) => {
+  const bound = []
+  track.querySelectorAll('[' + SCROLL_BIND_ATTR + ']').forEach((element) => {
+    const lanes = parseScrollBind(element.getAttribute(SCROLL_BIND_ATTR))
+    if (lanes.length > 0) {
+      bound.push({ element, lanes })
+    }
+  })
+  return bound
+}
+
+const normalizeSceneLength = (value) => {
+  const match = /^(\\d{2,4})vh$/.exec(String(value || '').trim())
+  if (!match) {
+    return '300vh'
+  }
+  // Hard safety bound only — the editor owns the story-sized soft cap.
+  return Math.min(4000, Math.max(100, Number(match[1]))) + 'vh'
+}`

package/src/scroll-scene/index.ts

@@ -0,0 +1,12 @@
+export { settledMomentForLanes, MomentLane } from './moment'
+export { activeChapterIndex } from './chapter-index'
+export { passedScenePoints, scenePointList, scenePointRank } from './points'
+export { unclipStickyAncestors } from './unclip'
+export { scrollSceneEngineSource as engineSource } from './engine-source'
+export {
+  announcementsSource,
+  restackBodySource,
+  chapterHelpersSource,
+  anchorNavigationBodySource,
+  gentleSnapBodySource,
+} from './controller-source'

package/src/scroll-scene/moment.ts

@@ -0,0 +1,64 @@
+/**
+ * The progress where a chapter is fully ON STAGE — every lane has arrived
+ * and none has started leaving — the centre of that settled span, in the
+ * lanes' own (absolute) progress space. The gentle snap and anchor
+ * navigation aim here instead of the window's midpoint, which catches the
+ * last beat still rising (a half-visible line, a half-arrived card).
+ * Null when nothing settles (a chapter made only of through-motion, e.g. a
+ * crossing line — its best moment is the window's middle, the caller's
+ * fallback).
+ *
+ * MIRRORED VERBATIM from teleport-gui's chapter-window.ts (the editor draws
+ * the same moment on the timeline). Plain JS inside: this function's SOURCE
+ * is injected into the generated TqScrollScene runtime via toString(), so no
+ * TypeScript-only runtime constructs and no template literals.
+ */
+export interface MomentLane {
+  at: number[]
+  values: number[]
+}
+
+export function settledMomentForLanes(lanes: MomentLane[]): number | null {
+  let arrive = -Infinity
+  let leave = Infinity
+  let lastStop = -Infinity
+  let found = false
+  for (const lane of lanes) {
+    if (lane.at.length < 3) {
+      continue
+    }
+    let settledAt: number | null = null
+    for (let index = 1; index < lane.values.length - 1; index++) {
+      if (lane.values[index] === lane.values[index + 1] && lane.values[index] !== lane.values[0]) {
+        settledAt = index
+        break
+      }
+    }
+    if (settledAt === null && lane.values[0] === lane.values[1]) {
+      settledAt = 0
+    }
+    if (settledAt === null) {
+      continue
+    }
+    found = true
+    arrive = Math.max(arrive, lane.at[settledAt])
+    lastStop = Math.max(lastStop, lane.at[lane.at.length - 1])
+    const settledValue = lane.values[settledAt]
+    for (let index = settledAt + 1; index < lane.values.length; index++) {
+      if (lane.values[index] !== settledValue) {
+        leave = Math.min(leave, lane.at[index - 1])
+        break
+      }
+    }
+  }
+  if (!found) {
+    return null
+  }
+  if (leave === Infinity) {
+    leave = lastStop
+  }
+  if (leave < arrive) {
+    return null
+  }
+  return Math.round(((arrive + leave) / 2) * 10000) / 10000
+}

package/src/scroll-scene/points.ts

@@ -0,0 +1,46 @@
+/**
+ * The "scrolled past a point" contract of a published Scroll Scene: the four
+ * plain points in scroll order, which of them a move from one progress to
+ * another passes DOWNWARD, and the rank of a point for late listeners. The
+ * scene announces every passed point as a `tq-scene-point-passed` DOM event
+ * on its track (the element carrying the scene's id) and stamps the furthest
+ * point passed so far as `data-scene-point`.
+ *
+ * Plain JS inside: these functions' SOURCE is injected into the generated
+ * runtime via toString(), so no TypeScript-only runtime constructs, no
+ * template literals and no reference to anything outside the function. The
+ * list mirrors SCROLL_POINT_PROGRESS in teleport-plugin-next-workflows
+ * (pinned by a test).
+ */
+export function scenePointList(): Array<{ key: string; at: number }> {
+  return [
+    { key: 'quarter', at: 0.25 },
+    { key: 'half', at: 0.5 },
+    { key: 'three-quarters', at: 0.75 },
+    { key: 'end', at: 1 },
+  ]
+}
+
+/** Points passed going DOWN from one progress to another, in scroll order; none when going up. */
+export function passedScenePoints(from: number, to: number): string[] {
+  const passed = []
+  const points = scenePointList()
+  for (let index = 0; index < points.length; index++) {
+    const point = points[index]
+    if (point.at > from + 0.000001 && point.at <= to + 0.000001) {
+      passed.push(point.key)
+    }
+  }
+  return passed
+}
+
+/** 1-based rank of a point in scroll order, 0 for anything else. */
+export function scenePointRank(key: string): number {
+  const points = scenePointList()
+  for (let index = 0; index < points.length; index++) {
+    if (points[index].key === key) {
+      return index + 1
+    }
+  }
+  return 0
+}

package/src/scroll-scene/unclip.ts

@@ -0,0 +1,44 @@
+/**
+ * Keep a pinned scene's stage pinnable: an ancestor with `overflow: hidden`
+ * (either axis) turns position:sticky off, silently. Authors and the AI write
+ * it for good reasons (a horizontal rail must clip its overhang — run
+ * e7f332df wrote `section.rail-scene { overflow: hidden }` around the
+ * homepage's story and the stage scrolled straight through). `overflow: clip`
+ * keeps the clipping and, unlike hidden, does not make the element a scroll
+ * container, so the stage sticks again. Ancestors that really scroll (auto /
+ * scroll) are left alone: sticky then rightly binds to that container.
+ *
+ * Injected into the generated widget via toString — no imports, no template
+ * literals (the generated project transpiles it).
+ */
+export function unclipStickyAncestors(
+  track: Element,
+  getStyle: (element: Element) => CSSStyleDeclaration
+): string[] {
+  const unclipped: string[] = []
+  let element = track.parentElement
+  while (element && element !== element.ownerDocument.documentElement) {
+    const style = getStyle(element)
+    const both = style.overflow === 'hidden'
+    const axes: string[] = []
+    if (both || style.overflowX === 'hidden') {
+      axes.push('x')
+    }
+    if (both || style.overflowY === 'hidden') {
+      axes.push('y')
+    }
+    if (axes.length > 0) {
+      const host = element as HTMLElement
+      for (let i = 0; i < axes.length; i++) {
+        host.style.setProperty('overflow-' + axes[i], 'clip')
+      }
+      host.setAttribute('data-scene-unclipped', axes.join(''))
+      unclipped.push(
+        host.tagName.toLowerCase() +
+          (host.className ? '.' + String(host.className).split(' ')[0] : '')
+      )
+    }
+    element = element.parentElement
+  }
+  return unclipped
+}