@struq/skill 0.5.2 → 0.5.3

package/skills/struq/blocks/kit/middle/hours.ts

@@ -0,0 +1,154 @@
+// components/struq/kit/middle/hours.ts (Struq recipe)
+// Opening hours as data: the rows a page prints and the open marker computed from the given hours and the real local
+// time in a given time zone. Never invented: with no hours there is nothing to print and no marker; with hours but no
+// time zone the hours print and the marker stays off. Lifted from footers/footer-contact (one copy: the footer and
+// kit/middle/PlaceHours both import it).
+//
+// const rows: HoursRow[] = [{ days: [1, 2, 3, 4, 5], from: "7:00", to: "18:00" }, { days: [6], from: "8:00", to: "16:00" }];
+// hoursLines(rows, "en");                                   // [{ days: "Monday to Friday", time: "7:00 to 18:00" }, ...]
+// openStatus(rows, wallClock(new Date(), "Europe/Amsterdam"), "en"); // { open: true, text: "Open now, until 18:00" }
+// const now = useNow(Boolean(hours && timeZone));          // null on the server and the first paint, then every minute
+//
+// Exports
+// - HoursRow: { days, from, to }. days are weekdays 1 (Monday) to 7 (Sunday); from and to are "9:00" style times.
+// - HoursLang: "en" (default) or "nl". The words only; the times print as given.
+// - toMinutes(time): minutes since midnight. daysText(days, lang): "Monday to Friday", "Monday, Wednesday and Friday".
+// - hoursText(row, lang): one row as one line, "Monday to Friday, 9:00 to 18:00".
+// - hoursLines(rows, lang): each row as { days, time } for a timetable.
+// - wallClock(now, timeZone): the weekday and time on the wall in that zone ({ dow, h, m, hh, mm }).
+// - openStatus(rows, wall, lang): { open, text } ("Open now, until 18:00", "Today from 9:00", "Tomorrow from 9:00",
+//   "Saturday from 8:00"); text is "" when no row has a day.
+// - useNow(on): the current Date after mount, ticking on the minute; null when off, on the server and on first paint,
+//   so nothing time-dependent is ever rendered on the server.
+import { useEffect, useState } from "react";
+
+export type HoursRow = { days: number[]; from: string; to: string };
+export type HoursLang = "en" | "nl";
+export type Wall = { dow: number; h: number; m: number; hh: string; mm: string };
+export type OpenStatus = { open: boolean; text: string };
+
+const WORDS: Record<HoursLang, { days: string[]; through: string; and: string; to: string; openUntil: string; today: string; tomorrow: string; from: string }> = {
+  en: {
+    days: ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"],
+    through: "to",
+    and: "and",
+    to: "to",
+    openUntil: "Open now, until",
+    today: "Today",
+    tomorrow: "Tomorrow",
+    from: "from",
+  },
+  nl: {
+    days: ["maandag", "dinsdag", "woensdag", "donderdag", "vrijdag", "zaterdag", "zondag"],
+    through: "tot en met",
+    and: "en",
+    to: "tot",
+    openUntil: "Nu open, tot",
+    today: "Vandaag",
+    tomorrow: "Morgen",
+    from: "vanaf",
+  },
+};
+
+const WEEKDAY: Record<string, number> = { Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6, Sun: 7 };
+const cap = (s: string) => s.charAt(0).toUpperCase() + s.slice(1);
+
+/** Minutes since midnight for "9:00" or "18:30". */
+export function toMinutes(time: string): number {
+  const [h, m] = time.split(":").map(Number);
+  return (h || 0) * 60 + (m || 0);
+}
+
+/** The days as words: a run of three or more as "Monday to Friday", other days listed ("Saturday and Sunday"). */
+export function daysText(days: number[], lang: HoursLang = "en"): string {
+  const w = WORDS[lang];
+  const sorted = [...new Set(days)].filter((d) => d >= 1 && d <= 7).sort((a, b) => a - b);
+  if (!sorted.length) return "";
+  const runs: number[][] = [];
+  for (const d of sorted) {
+    const run = runs[runs.length - 1];
+    if (run && d === run[run.length - 1] + 1) run.push(d);
+    else runs.push([d]);
+  }
+  const parts = runs.flatMap((run) =>
+    run.length >= 3
+      ?[`${w.days[run[0] - 1]} ${w.through} ${w.days[run[run.length - 1] - 1]}`]
+      : run.map((d) => w.days[d - 1]),
+  );
+  const text = parts.length === 1 ? parts[0] : `${parts.slice(0, -1).join(", ")} ${w.and} ${parts[parts.length - 1]}`;
+  return cap(text);
+}
+
+/** One row as one line: "Monday to Friday, 9:00 to 18:00". */
+export function hoursText(row: HoursRow, lang: HoursLang = "en"): string {
+  const days = daysText(row.days, lang);
+  if (!days) return "";
+  return `${days}, ${row.from} ${WORDS[lang].to} ${row.to}`;
+}
+
+/** Each row as its days and its time, for a timetable. Rows without a valid day are dropped. */
+export function hoursLines(rows: readonly HoursRow[], lang: HoursLang = "en"): { days: string; time: string }[] {
+  return rows
+    .map((row) => ({ days: daysText(row.days, lang), time: `${row.from} ${WORDS[lang].to} ${row.to}` }))
+    .filter((line) => line.days !== "");
+}
+
+/** The weekday (1 Monday to 7 Sunday) and the time on the wall in `timeZone` at `now`. */
+export function wallClock(now: Date, timeZone: string): Wall {
+  const parts = new Intl.DateTimeFormat("en-GB", { timeZone, weekday: "short", hour: "2-digit", minute: "2-digit", hourCycle: "h23" }).formatToParts(now);
+  const get = (t: string) => parts.find((p) => p.type === t)?.value ?? "";
+  const h = Number(get("hour")) % 24;
+  const m = Number(get("minute"));
+  return { dow: WEEKDAY[get("weekday")] ?? 1, h, m, hh: String(h).padStart(2, "0"), mm: String(m).padStart(2, "0") };
+}
+
+/** Whether the place is open on the wall clock, from the given rows only, and the words for it. */
+export function openStatus(rows: readonly HoursRow[], wall: Wall, lang: HoursLang = "en"): OpenStatus {
+  const w = WORDS[lang];
+  const mins = wall.h * 60 + wall.m;
+  const on = (d: number) => rows.filter((row) => row.days.includes(d));
+  const today = on(wall.dow);
+  const now = today.filter((row) => mins >= toMinutes(row.from) && mins < toMinutes(row.to));
+  if (now.length) {
+    const until = now.reduce((a, b) => (toMinutes(b.to) > toMinutes(a.to) ? b : a));
+    return { open: true, text: `${w.openUntil} ${until.to}` };
+  }
+  const earliest = (list: HoursRow[]) => list.reduce((a, b) => (toMinutes(b.from) < toMinutes(a.from) ? b : a));
+  const later = today.filter((row) => mins < toMinutes(row.from));
+  if (later.length) return { open: false, text: `${w.today} ${w.from} ${earliest(later).from}` };
+  for (let k = 1; k <= 7; k += 1) {
+    const d = ((wall.dow - 1 + k) % 7) + 1;
+    const next = on(d);
+    if (next.length) {
+      const from = earliest(next).from;
+      return { open: false, text: k === 1 ? `${w.tomorrow} ${w.from} ${from}` : `${cap(w.days[d - 1])} ${w.from} ${from}` };
+    }
+  }
+  return { open: false, text: "" };
+}
+
+/** The time now, only when `on` and only after mount (null on the server and the first paint), ticking on the minute. */
+export function useNow(on: boolean): Date | null {
+  const [now, setNow] = useState<Date | null>(null);
+  useEffect(() => {
+    if (!on) return;
+    let timer = 0;
+    const tick = () => {
+      const d = new Date();
+      setNow(d);
+      window.clearTimeout(timer);
+      timer = window.setTimeout(tick, 60_000 - (d.getSeconds() * 1000 + d.getMilliseconds()) + 30);
+    };
+    tick();
+    // A background tab's timers are held back; on return the clock catches up at once.
+    const onShow = () => {
+      if (document.visibilityState === "visible") tick();
+    };
+    document.addEventListener("visibilitychange", onShow);
+    return () => {
+      window.clearTimeout(timer);
+      document.removeEventListener("visibilitychange", onShow);
+    };
+  }, [on]);
+  return on ? now : null;
+}

package/skills/struq/blocks/kit/middle/index.ts

@@ -0,0 +1,14 @@
+// components/struq/kit/middle/index.ts (Struq recipe)
+// The middle scenes: designed middles of a page, each with two or three variants extracted from the blocks, filled
+// through typed slots. Pick a scene and a variant and fill it with the client's own words; never compose a middle from
+// raw GSAP and a grid. Each renders its own data-scene root, takes a tone (ground, inverse, field), orders its parts in
+// one timeline from one trigger and is timed by the site's temperament (../feel). Optional facts (hours, phone,
+// address) have no defaults and render nothing when absent; a variant missing what it needs falls back in code.
+export { ProcessStrip, resolveProcessVariant } from "./ProcessStrip";
+export type { ProcessVariant, Step } from "./ProcessStrip";
+export { PlaceHours, resolvePlaceVariant } from "./PlaceHours";
+export type { PlaceDoor, PlaceVariant } from "./PlaceHours";
+export { ServicesList, resolveServicesVariant, TONE_CLASS } from "./ServicesList";
+export type { SceneTone, Service, ServicesVariant } from "./ServicesList";
+export { daysText, hoursLines, hoursText, openStatus, wallClock } from "./hours";
+export type { HoursLang, HoursRow } from "./hours";

package/skills/struq/blocks/kit/motion/HoverLink.tsx

@@ -0,0 +1,33 @@
+// components/struq/kit/motion/HoverLink.tsx (Struq recipe)
+// A text link with the site's one hover style. Pick the style once per site and use it for every text link on it
+// (nav, footer, inline, "view the work"). CSS only, so it works before hydration and in a server component. Extracted
+// from the live site's .link (one rule, one origin, reverses from wherever it is) and the kit's footer rule draw.
+//
+// <HoverLink href="/work" look="draw">See the work</HoverLink>
+//
+// Props
+// - href, children, and any other <a> attribute (target, rel, aria-current, onClick).
+// - look: "draw" (default: a rule draws in from the left under the text and draws back the same way), "slide" (the
+//   resting rule slides out to the right and a new one slides in from the left) or "color" (the text turns to the
+//   accent, no rule).
+// - className: on the <a>. The link inherits its type and colour; set them on it or its parent.
+//
+// Motion: the rule moves over the feel's --dur-hover-line on --ease-enter, the colour over --dur-hover-color, read from
+// [data-temperament] (blocks.css, "--- motion ---"). Keyboard focus shows the same state as hover, plus the locked
+// focus ring. Reduced motion: the same states, cut in without movement.
+import type { AnchorHTMLAttributes, ReactNode } from "react";
+
+type Props = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "children"> & {
+  href: string;
+  children: ReactNode;
+  look?: "draw" | "slide" | "color";
+  className?: string;
+};
+
+export function HoverLink({ href, children, look = "draw", className = "", ...rest }: Props) {
+  return (
+    <a {...rest} href={href} data-hover-link={look} className={className}>
+      {children}
+    </a>
+  );
+}

package/skills/struq/blocks/kit/motion/ImageCurtain.tsx

@@ -0,0 +1,79 @@
+"use client";
+// components/struq/kit/motion/ImageCurtain.tsx (Struq recipe)
+// A panel in the page's ground colour covers a photo and lifts off it as it enters, while the photo settles. Use it
+// for a photo that should be uncovered, as if the page itself drew back; MaskWipe is the plainer cut. Extracted from
+// showpieces/panel-wipe (ground-colour panels travelling off on the structural ease, the photo settling under them),
+// made a single panel on enter.
+//
+// <ImageCurtain className="aspect-[3/2]"><img src="/rooms/table.jpg" alt="The long table by the window" className="h-full w-full object-cover" /></ImageCurtain>
+//
+// Props
+// - children: the photo (an img, a next/image with fill, or kit/MediaFrame with reveal="none"). Give the wrapper its
+//   size (className) when the photo fills it.
+// - lift: where the panel goes: "up" (default), "down", "left" or "right".
+// - on: "scroll" (default, once at the feel's trigger) or "load" (on mount, for a hero).
+// - delay: seconds before it starts. className: on the wrapper. The panel takes bg-surface-0, the scene's ground,
+//   so it reads correctly inside scene-inverse and scene-field too.
+//
+// Motion: the panel travels off over dur("curtain", size) on the feel's curtain ease; the photo settles from
+// feel().travel.media scale to 1 over dur("settle", size) on the enter ease, both from the same moment. Reduced
+// motion, no scripts or the server render: the photo uncovered and at rest. No layout shift: only transforms move.
+import { useRef, type ReactNode } from "react";
+import { feel, LOCKED, prefersReduced } from "../feel";
+import { gsap, useGSAP } from "../gsap";
+
+type Lift = "up" | "down" | "left" | "right";
+
+type Props = {
+  children: ReactNode;
+  lift?: Lift;
+  on?: "scroll" | "load";
+  delay?: number;
+  className?: string;
+};
+
+const AWAY: Record<Lift, gsap.TweenVars> = {
+  up: { yPercent: -100 },
+  down: { yPercent: 100 },
+  left: { xPercent: -100 },
+  right: { xPercent: 100 },
+};
+
+export function ImageCurtain({ children, lift = "up", on = "scroll", delay = 0, className = "" }: Props) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  useGSAP(
+    () => {
+      const el = ref.current;
+      const panel = el?.querySelector<HTMLElement>("[data-curtain-panel]");
+      const photo = el?.querySelector<HTMLElement>("[data-curtain-photo]");
+      if (!el || !panel || !photo) return;
+      if (prefersReduced()) {
+        el.dataset.ready = "1";
+        return;
+      }
+      const f = feel(el);
+      const size = lift === "up" || lift === "down" ? el.offsetHeight : el.offsetWidth;
+      // The panel stands in place until the trigger; CSS holds it there before hydration. x and y are zeroed too:
+      // GSAP reads the resting CSS transform (translate -100%) into x or y in px, which would keep it off the photo.
+      gsap.set(panel, { x: 0, y: 0, xPercent: 0, yPercent: 0 });
+      const tl = gsap.timeline({
+        delay,
+        scrollTrigger: on === "scroll" ? { trigger: el, start: LOCKED.trigger.start, once: LOCKED.trigger.once } : undefined,
+      });
+      tl.to(panel, { ...AWAY[lift], duration: f.dur("curtain", size), ease: f.ease.curtain }, 0);
+      tl.fromTo(photo, { scale: f.travel.media }, { scale: 1, duration: f.dur("settle", size), ease: f.ease.enter }, 0);
+      el.dataset.ready = "1";
+    },
+    { scope: ref, dependencies: [lift, on, delay] },
+  );
+
+  return (
+    <div ref={ref} data-curtain={lift} className={`relative overflow-hidden ${className}`}>
+      <div data-curtain-photo="" className="absolute inset-0">
+        {children}
+      </div>
+      <span aria-hidden data-curtain-panel="" className="absolute inset-0 bg-surface-0" />
+    </div>
+  );
+}

package/skills/struq/blocks/kit/motion/MaskWipe.tsx

@@ -0,0 +1,91 @@
+"use client";
+// components/struq/kit/motion/MaskWipe.tsx (Struq recipe)
+// Wipes an element or a photo in from one edge with a clip-path, on enter or with the scroll. Use it for media,
+// panels and blocks of colour that should open rather than fade. Extracted from kit/MediaFrame's curtain (inset clip
+// from one edge, the photo settling inside it) with the edge made a prop.
+//
+// <MaskWipe from="left" settle className="aspect-[4/5]"><img src="/work/vase.jpg" alt="A celadon vase" className="h-full w-full object-cover" /></MaskWipe>
+//
+// Props
+// - children: what is wiped in. Give the wrapper its size (className) when the child is absolutely placed.
+// - from: the edge it opens from: "bottom" (default), "top", "left" or "right".
+// - on: "scroll" (default, once at the feel's trigger), "load" (on mount) or "scrub" (opens with the scroll, closes
+//   going back).
+// - settle: the first child also settles from feel().travel.media scale to 1 (for a photo). Default false.
+// - delay: seconds before it starts (load and scroll only). as: "div" (default) or "figure". className: on the wrapper.
+//
+// Motion: the clip opens on the feel's curtain ease over dur("curtain", height), so a tall photo opens slower than a
+// strip; settle runs over dur("settle", height) on the enter ease; scrubbed both run linear with scrub.flow. Reduced
+// motion, no scripts or the server render: fully open, at rest. No layout shift: only clip-path and transform move.
+import { useRef, type ReactNode } from "react";
+import { feel, LOCKED, prefersReduced } from "../feel";
+import { gsap, useGSAP } from "../gsap";
+
+type Edge = "bottom" | "top" | "left" | "right";
+
+type Props = {
+  children: ReactNode;
+  from?: Edge;
+  on?: "scroll" | "load" | "scrub";
+  settle?: boolean;
+  delay?: number;
+  as?: "div" | "figure";
+  className?: string;
+};
+
+/** The closed clip for each edge: everything inset from the opposite side. */
+export const CLOSED: Record<Edge, string> = {
+  bottom: "inset(100% 0% 0% 0%)",
+  top: "inset(0% 0% 100% 0%)",
+  left: "inset(0% 100% 0% 0%)",
+  right: "inset(0% 0% 0% 100%)",
+};
+const OPEN = "inset(0% 0% 0% 0%)";
+
+export function MaskWipe({ children, from = "bottom", on = "scroll", settle = false, delay = 0, as = "div", className = "" }: Props) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  useGSAP(
+    () => {
+      const el = ref.current;
+      if (!el) return;
+      if (prefersReduced()) {
+        el.dataset.ready = "1";
+        return;
+      }
+      const f = feel(el);
+      const size = el.offsetHeight;
+      const scrub = on === "scrub";
+      const scrollTrigger = scrub
+        ? { trigger: el, start: "top 95%", end: "top 40%", scrub: f.scrub.flow }
+        : on === "scroll"
+          ? { trigger: el, start: LOCKED.trigger.start, once: LOCKED.trigger.once }
+          : undefined;
+      const tl = gsap.timeline({ delay: scrub ? 0 : delay, scrollTrigger });
+      tl.fromTo(
+        el,
+        { clipPath: CLOSED[from] },
+        { clipPath: OPEN, duration: f.dur("curtain", size), ease: scrub ? f.ease.scrub : f.ease.curtain },
+        0,
+      );
+      const media = el.firstElementChild;
+      if (settle && media) {
+        tl.fromTo(
+          media,
+          { scale: f.travel.media },
+          { scale: 1, duration: f.dur("settle", size), ease: scrub ? f.ease.scrub : f.ease.enter },
+          0,
+        );
+      }
+      el.dataset.ready = "1";
+    },
+    { scope: ref, dependencies: [from, on, settle, delay] },
+  );
+
+  const Tag = as as "div";
+  return (
+    <Tag ref={ref} data-wipe={from} className={`relative overflow-hidden ${className}`}>
+      {children}
+    </Tag>
+  );
+}

package/skills/struq/blocks/kit/motion/Pressable.tsx

@@ -0,0 +1,58 @@
+// components/struq/kit/motion/Pressable.tsx (Struq recipe)
+// A button or link that answers the hand: it lifts a little under the pointer and gives way when pressed. Pick the
+// press style once per site. CSS only, so it works before hydration and in a server component. Extracted from the
+// live site's .btn press (a 1px sink in about 0.12s, settling back on the arrival ease) and the kit MagneticButton's
+// rising ink fill, here on the press.
+//
+// <Pressable href="#book" press="sink" className="bg-accent px-8 py-4 text-small font-medium text-accent-ink">Book a table</Pressable>
+//
+// Props
+// - href: renders an <a>; without it a <button type="button"> (pass type="submit" for a form). onClick, disabled,
+//   aria-* and the rest pass through.
+// - press: "sink" (default: it moves down by the feel's sink) or "fill" (an ink fill floods up from the bottom edge
+//   and the label turns to the ground colour). Set --press-fill on it to fill with another colour.
+// - lift: the hover lift by the feel's --press-lift (default true). Off for buttons in a dense row.
+// - className: the look (ground, ink, padding, type). Pressable adds only the behaviour.
+//
+// Motion: the press goes in over --dur-press-in and settles back over --dur-press-out on --ease-enter; the lift and
+// the hover share the settle. Keyboard focus lifts as hover does and keeps the locked focus ring. Reduced motion: no
+// lift and no sink; the fill still shows, cut in.
+import type { ButtonHTMLAttributes, ReactNode } from "react";
+
+type Common = {
+  children: ReactNode;
+  press?: "sink" | "fill";
+  lift?: boolean;
+  className?: string;
+};
+
+type Props = Common &
+  (
+    | ({ href: string } & Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "children" | "className">)
+    | ({ href?: undefined } & Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "className">)
+  );
+
+export function Pressable(props: Props) {
+  const { children, press = "sink", lift = true, className = "", ...rest } = props;
+  const data = { "data-pressable": press, "data-lift": lift ? "" : undefined };
+  const inner = (
+    <>
+      {press === "fill" ? <span aria-hidden data-press-fill="" /> : null}
+      <span data-press-label="">{children}</span>
+    </>
+  );
+  if ("href" in rest && typeof rest.href === "string") {
+    const anchor = rest as React.AnchorHTMLAttributes<HTMLAnchorElement>;
+    return (
+      <a {...anchor} {...data} className={`relative inline-flex items-center justify-center ${className}`}>
+        {inner}
+      </a>
+    );
+  }
+  const button = rest as ButtonHTMLAttributes<HTMLButtonElement>;
+  return (
+    <button type="button" {...button} {...data} className={`relative inline-flex items-center justify-center ${className}`}>
+      {inner}
+    </button>
+  );
+}

package/skills/struq/blocks/kit/motion/RevealText.tsx

@@ -0,0 +1,103 @@
+"use client";
+// components/struq/kit/motion/RevealText.tsx (Struq recipe)
+// Text that rises out of a mask, line by line or word by word. Use it for every headline or statement that should
+// arrive; never hand-roll a SplitText reveal. Extracted from kit/SplitHeadline (lines: SplitText, autoSplit re-cuts on
+// resize and font load) and the live site's word reveal (words set in their own masks at render, no layout cost).
+//
+// <RevealText as="h2" by="lines" className="font-display text-h2 max-w-[18ch]">Grown slowly, poured by hand.</RevealText>
+//
+// Props
+// - children: plain text (lines may carry an <em> accent; words take a string only).
+// - as: "h1" | "h2" | "h3" | "p" | "span" | "div" (default "h2").
+// - by: "lines" (default) or "words".
+// - on: "scroll" (default, once at the feel's trigger), "load" (on mount, for a hero) or "scrub" (tied to the scroll
+//   while the text crosses the lower half of the screen, reverses going back).
+// - delay: seconds before it starts (load and scroll only). className: on the element.
+//
+// Motion: each line or word starts feel().travel.text percent below its mask and rises on the feel's enter ease, over
+// duration.line, staggered by stagger.line or stagger.word; scrubbed it runs linear with scrub.flow smoothing. The
+// masks use the shared .struq-line-mask room, so g, j, p and y are never clipped and the layout never moves. Reduced
+// motion, no scripts or the server render: the finished text.
+import { useRef, type ReactNode } from "react";
+import { feel, LOCKED, prefersReduced } from "../feel";
+import { gsap, SplitText, useGSAP } from "../gsap";
+
+type Props = {
+  children: ReactNode;
+  as?: "h1" | "h2" | "h3" | "p" | "span" | "div";
+  by?: "lines" | "words";
+  on?: "scroll" | "load" | "scrub";
+  delay?: number;
+  className?: string;
+};
+
+/** The words of a string, each in its own shared mask, with the spaces kept as text so the line breaks as before. */
+function wordsOf(text: string) {
+  const parts = text.split(/(\s+)/).filter((part) => part !== "");
+  return parts.map((part, i) =>
+    /^\s+$/.test(part) ? (
+      part
+    ) : (
+      <span key={i} className="struq-line-mask" data-word="">
+        <span data-word-rise="">{part}</span>
+      </span>
+    ),
+  );
+}
+
+export function RevealText({ children, as = "h2", by = "lines", on = "scroll", delay = 0, className = "" }: Props) {
+  const ref = useRef<HTMLElement>(null);
+
+  useGSAP(
+    () => {
+      const el = ref.current;
+      if (!el) return;
+      if (prefersReduced()) {
+        el.dataset.ready = "1";
+        return;
+      }
+      const f = feel(el);
+      const trigger =
+        on === "scrub"
+          ? { trigger: el, start: "top 90%", end: "top 50%", scrub: f.scrub.flow }
+          : on === "scroll"
+            ? { trigger: el, start: LOCKED.trigger.start, once: LOCKED.trigger.once }
+            : undefined;
+      const rise = (targets: Element[], stagger: number) =>
+        gsap.from(targets, {
+          yPercent: f.travel.text,
+          duration: f.duration.line,
+          ease: on === "scrub" ? f.ease.scrub : f.ease.enter,
+          stagger,
+          delay: on === "scrub" ? 0 : delay,
+          scrollTrigger: trigger,
+        });
+
+      if (by === "words") {
+        rise(Array.from(el.querySelectorAll("[data-word-rise]")), f.stagger.word);
+        el.dataset.ready = "1";
+        return;
+      }
+      const split = SplitText.create(el, {
+        type: "lines",
+        mask: "lines",
+        linesClass: "struq-line",
+        autoSplit: true,
+        onSplit(self) {
+          return rise(self.lines, f.stagger.line);
+        },
+      });
+      el.dataset.ready = "1";
+      return () => split.revert();
+    },
+    { scope: ref, dependencies: [by, on, delay] },
+  );
+
+  const Tag = as as "h2";
+  const content = by === "words" && typeof children === "string" ? wordsOf(children) : children;
+  return (
+    <Tag ref={ref as React.RefObject<HTMLHeadingElement>} data-reveal-text={by} className={className}>
+      {content}
+    </Tag>
+  );
+}

package/skills/struq/blocks/kit/motion/Rise.tsx

@@ -0,0 +1,77 @@
+"use client";
+// components/struq/kit/motion/Rise.tsx (Struq recipe)
+// A block that rises a little and comes up from clear as it enters: a paragraph, a list of rows, a caption, a row of
+// doors. Use it for everything that arrives after a heading; RevealText is for the heading itself. Extracted from the
+// kit's Reveal and the soft rise the sections share (a short travel in px with the opacity), put on the feel.
+//
+// <Rise as="ul" each className="grid gap-4">{rows.map((row) => <li key={row.term}>{row.text}</li>)}</Rise>
+//
+// Props
+// - children: what rises.
+// - as: "div" (default), "p", "ul", "ol", "figure", "figcaption" or "span".
+// - each: the direct children rise one after another, staggered by the feel's stagger.block (default false: the
+//   element rises whole).
+// - on: "scroll" (default, once at the feel's trigger) or "load" (on mount).
+// - delay: seconds before it starts. className: on the element.
+//
+// riseFrom(feel) and riseTo(feel) return the same start and end state, so a scene that orders its own parts in one
+// timeline rises its details exactly as Rise does.
+//
+// Motion: from feel().travel.block px below and clear, to rest, over duration.enter on the feel's enter ease; with
+// each, stagger.block between children. Crisp travels 24px quickly, weighted 48px, slow 72px over a long settle.
+// Reduced motion, no scripts or the server render: the block at rest. No layout shift: only transform and opacity.
+import { useRef, type ReactNode } from "react";
+import { feel, LOCKED, prefersReduced, type Feel } from "../feel";
+import { gsap, useGSAP } from "../gsap";
+
+type Props = {
+  children: ReactNode;
+  as?: "div" | "p" | "ul" | "ol" | "figure" | "figcaption" | "span";
+  each?: boolean;
+  on?: "scroll" | "load";
+  delay?: number;
+  className?: string;
+};
+
+/** The start of a rise in this feel: a block's travel below, clear. */
+export function riseFrom(f: Feel): gsap.TweenVars {
+  return { y: f.travel.block, autoAlpha: 0 };
+}
+
+/** The end of a rise in this feel: at rest, over duration.enter on the enter ease. */
+export function riseTo(f: Feel): gsap.TweenVars {
+  return { y: 0, autoAlpha: 1, duration: f.duration.enter, ease: f.ease.enter };
+}
+
+export function Rise({ children, as = "div", each = false, on = "scroll", delay = 0, className = "" }: Props) {
+  const ref = useRef<HTMLElement>(null);
+
+  useGSAP(
+    () => {
+      const el = ref.current;
+      if (!el) return;
+      if (prefersReduced()) {
+        el.dataset.ready = "1";
+        return;
+      }
+      const f = feel(el);
+      const targets = each ? Array.from(el.children) : [el];
+      // fromTo, so the pre-paint gate's opacity is never read as the end state.
+      gsap.fromTo(targets, riseFrom(f), {
+        ...riseTo(f),
+        stagger: each ? f.stagger.block : 0,
+        delay,
+        scrollTrigger: on === "scroll" ? { trigger: el, start: LOCKED.trigger.start, once: LOCKED.trigger.once } : undefined,
+      });
+      el.dataset.ready = "1";
+    },
+    { scope: ref, dependencies: [each, on, delay] },
+  );
+
+  const Tag = as as "div";
+  return (
+    <Tag ref={ref as React.RefObject<HTMLDivElement>} data-rise={each ? "each" : ""} className={className}>
+      {children}
+    </Tag>
+  );
+}