@appright/funnelshift 0.0.0-stage → 0.16.0

package/src/blocks/blocks.css

@@ -0,0 +1,364 @@
+/* funnel-kit blocks: Hero, Choice, Cta. Theme through --fk-* variables on :root; every use carries its default
+   ("appright clean"), so the blocks look right with no theme at all:
+   --fk-bg #f7f7f3  --fk-ink #0b0b0b  --fk-muted #64645e  --fk-accent #d6f84c  --fk-radius 16px */
+
+/* ---------- Cta ---------- */
+
+.fk-cta {
+  box-sizing: border-box;
+  width: 100%;
+  margin-top: auto;
+  padding: 12px 0 calc(16px + env(safe-area-inset-bottom, 0px));
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+}
+
+.fk-cta__button {
+  position: relative;
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 12px;
+  width: 100%;
+  min-height: 58px;
+  padding: 16px 28px;
+  border: 0;
+  border-radius: var(--fk-radius, 16px);
+  background: var(--fk-ink, #0b0b0b);
+  color: var(--fk-bg, #f7f7f3);
+  font: inherit;
+  font-size: 18px;
+  font-weight: 700;
+  line-height: 1.2;
+  letter-spacing: -0.01em;
+  cursor: pointer;
+  -webkit-tap-highlight-color: transparent;
+  touch-action: manipulation;
+  transition: transform 140ms ease-out, box-shadow 180ms ease-out, background-color 180ms ease-out, opacity 180ms ease-out;
+}
+
+@media (hover: hover) {
+  .fk-cta__button:hover:not(:disabled) {
+    transform: translateY(-2px);
+    box-shadow: 0 10px 24px -10px color-mix(in srgb, var(--fk-ink, #0b0b0b) 55%, transparent);
+  }
+}
+
+.fk-cta__button:focus-visible {
+  outline: 3px solid var(--fk-ink, #0b0b0b);
+  outline-offset: 4px;
+}
+
+.fk-cta__button:active:not(:disabled) {
+  transform: scale(0.98);
+  box-shadow: none;
+}
+
+.fk-cta__button:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+/* pending: still the same text, a small ring spins next to it */
+.fk-cta__button[aria-busy="true"] {
+  opacity: 1;
+  cursor: progress;
+  background: color-mix(in srgb, var(--fk-ink, #0b0b0b) 86%, var(--fk-bg, #f7f7f3));
+}
+
+.fk-cta__button[aria-busy="true"]::after {
+  content: "";
+  flex: none;
+  width: 18px;
+  height: 18px;
+  box-sizing: border-box;
+  border: 2.5px solid color-mix(in srgb, var(--fk-bg, #f7f7f3) 30%, transparent);
+  border-top-color: var(--fk-accent, #d6f84c);
+  border-radius: 50%;
+  animation: fk-spin 700ms linear infinite;
+}
+
+@keyframes fk-spin { to { transform: rotate(360deg); } }
+
+/* phones: the button is pinned to the bottom of the screen, content fades out underneath it */
+@media (max-width: 639.98px) {
+  .fk-cta {
+    position: sticky;
+    bottom: 0;
+    z-index: 2;
+    background: linear-gradient(to top, var(--fk-bg, #f7f7f3) 72%, transparent);
+  }
+}
+
+@media (min-width: 640px) {
+  .fk-cta { max-width: 360px; margin-inline: auto; padding-bottom: 8px; }
+}
+
+/* ---------- Hero ---------- */
+
+.fk-hero {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  min-height: 100dvh;
+  max-width: 720px;
+  margin: 0 auto;
+  padding: 24px 20px 0;
+  background: var(--fk-bg, #f7f7f3);
+  color: var(--fk-ink, #0b0b0b);
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  text-align: center;
+  -webkit-font-smoothing: antialiased;
+}
+
+.fk-hero__main {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 20px;
+  padding-bottom: 6dvh; /* sits a little above the geometric centre */
+}
+
+.fk-hero__visual {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  margin-bottom: 8px;
+  font-size: clamp(96px, 28vw, 120px);
+  line-height: 1;
+}
+
+.fk-hero__visual > img,
+.fk-hero__visual > svg {
+  display: block;
+  width: auto;
+  max-width: 100%;
+  height: clamp(96px, 28vw, 120px);
+}
+
+.fk-hero__title {
+  margin: 0;
+  max-width: 14em;
+  font-size: clamp(2.25rem, 1.6rem + 3.2vw, 3.5rem);
+  font-weight: 800;
+  line-height: 1.05;
+  letter-spacing: -0.03em;
+  text-wrap: balance;
+}
+
+.fk-hero__subtitle {
+  margin: 0;
+  max-width: 30ch;
+  color: var(--fk-muted, #64645e);
+  font-size: clamp(1.0625rem, 1rem + 0.25vw, 1.1875rem);
+  line-height: 1.45;
+  text-wrap: pretty;
+}
+
+/* ---------- Brush: the highlight painted by hand in two strokes ----------
+   Stroke 1 (::before) sweeps left to right low on the text; stroke 2 (::after) sweeps back right to left a bit
+   higher and shorter. 380 ms + 320 ms = 700 ms, ease-out, starting 150 ms after mount. The marker lives behind
+   the glyphs (isolation + z-index -1), so the text stays readable at every moment. */
+
+.fk-brush {
+  position: relative;
+  isolation: isolate;
+  padding: 0 0.1em;
+  background: none;
+  color: inherit;
+}
+
+.fk-brush::before,
+.fk-brush::after {
+  content: "";
+  position: absolute;
+  z-index: -1;
+  pointer-events: none;
+  clip-path: inset(-20% -10% -20% -10%); /* the finished marker; the animation only plays the way to it */
+  animation-timing-function: cubic-bezier(0.22, 0.9, 0.3, 1);
+  animation-fill-mode: backwards; /* hidden during the start delay; no forwards fill (a held fill lifts the marker above the text) */
+}
+
+.fk-brush::before {
+  left: -0.04em;
+  right: -0.06em;
+  bottom: 0.03em;
+  height: 0.36em;
+  background: var(--fk-accent, #d6f84c);
+  border-radius: 0.16em 0.34em 0.2em 0.38em / 0.3em 0.18em 0.34em 0.2em;
+  transform: skewX(-7deg) rotate(-0.8deg);
+  transform-origin: left center;
+  animation-name: fk-brush-1;
+  animation-duration: 380ms;
+  animation-delay: 150ms;
+}
+
+.fk-brush::after {
+  left: 0.14em;
+  right: 0.02em;
+  bottom: 0.25em;
+  height: 0.31em;
+  background: var(--fk-accent, #d6f84c);
+  mix-blend-mode: multiply; /* where the second stroke crosses the first the colour deepens, like a real marker */
+  border-radius: 0.32em 0.14em 0.36em 0.18em / 0.2em 0.3em 0.18em 0.32em;
+  transform: skewX(-5deg) rotate(0.9deg);
+  transform-origin: right center;
+  animation-name: fk-brush-2;
+  animation-duration: 320ms;
+  animation-delay: 530ms; /* 150 + 380 */
+}
+
+@keyframes fk-brush-1 { from { clip-path: inset(-20% 110% -20% -10%); } }
+@keyframes fk-brush-2 { from { clip-path: inset(-20% -10% -20% 110%); } }
+
+/* A highlight that wraps onto several lines (Hero adds this class): the pseudo strokes cannot follow the lines, so the
+   same two strokes are drawn as background layers of every line fragment. */
+.fk-brush--wrap::before,
+.fk-brush--wrap::after { display: none; }
+
+.fk-brush--wrap {
+  -webkit-box-decoration-break: clone;
+  box-decoration-break: clone;
+  background-repeat: no-repeat;
+  background-image: linear-gradient(var(--fk-accent, #d6f84c), var(--fk-accent, #d6f84c)), linear-gradient(var(--fk-accent, #d6f84c), var(--fk-accent, #d6f84c));
+  background-position: left 0 bottom 3%, right 2% bottom 25%;
+  background-size: 100% 36%, 84% 31%;
+  background-blend-mode: multiply;
+  animation: fk-brush-wrap 700ms 150ms backwards;
+}
+
+@keyframes fk-brush-wrap {
+  from { background-size: 0% 36%, 0% 31%; animation-timing-function: cubic-bezier(0.22, 0.9, 0.3, 1); }
+  54%  { background-size: 100% 36%, 0% 31%; animation-timing-function: cubic-bezier(0.22, 0.9, 0.3, 1); }
+  to   { background-size: 100% 36%, 84% 31%; }
+}
+
+/* reduced motion: the finished marker at once. `fk-brush--static` is the same state, set by Hero from matchMedia. */
+.fk-brush--static::before,
+.fk-brush--static::after,
+.fk-brush--wrap.fk-brush--static {
+  animation: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .fk-brush::before,
+  .fk-brush::after,
+  .fk-brush--wrap {
+    animation: none;
+  }
+  .fk-cta__button { transition: none; }
+  .fk-cta__button[aria-busy="true"]::after { animation: none; border-top-color: var(--fk-bg, #f7f7f3); }
+  .fk-choice__option { transition: none; }
+}
+
+/* ---------- Shot: one screen drawn as a thumbnail in the admin (?__step=<id>&__shot=1) ----------
+   FunnelApp wraps the step in .fk-shot. Nothing moves (the marker is already finished, same as fk-brush--static), and the
+   funnel's own progress bar and back button, marked data-fk-chrome (or hidden by useFunnel().shot), are not drawn. */
+
+.fk-shot *,
+.fk-shot *::before,
+.fk-shot *::after {
+  animation: none !important;
+  transition: none !important;
+  caret-color: transparent;
+}
+
+.fk-shot [data-fk-chrome] { display: none !important; }
+
+/* ---------- Choice ---------- */
+
+.fk-choice {
+  box-sizing: border-box;
+  display: grid;
+  gap: 12px;
+  width: 100%;
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+}
+
+.fk-choice__option {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  width: 100%;
+  min-height: 60px;
+  padding: 12px 18px 12px 16px;
+  border: 2px solid color-mix(in srgb, var(--fk-ink, #0b0b0b) 12%, transparent);
+  border-radius: var(--fk-radius, 16px);
+  background: var(--fk-bg, #f7f7f3);
+  color: var(--fk-ink, #0b0b0b);
+  font: inherit;
+  font-size: 18px;
+  font-weight: 600;
+  line-height: 1.25;
+  text-align: left;
+  cursor: pointer;
+  -webkit-tap-highlight-color: transparent;
+  touch-action: manipulation;
+  transition: border-color 160ms ease-out, background-color 160ms ease-out, transform 120ms ease-out, box-shadow 160ms ease-out;
+}
+
+@media (hover: hover) {
+  .fk-choice__option:hover {
+    border-color: color-mix(in srgb, var(--fk-ink, #0b0b0b) 38%, transparent);
+  }
+}
+
+.fk-choice__option:active { transform: scale(0.985); }
+
+.fk-choice__option:focus-visible {
+  outline: 3px solid var(--fk-ink, #0b0b0b);
+  outline-offset: 3px;
+}
+
+.fk-choice__option[aria-checked="true"] {
+  border-color: color-mix(in srgb, var(--fk-accent, #d6f84c) 55%, var(--fk-ink, #0b0b0b));
+  background: color-mix(in srgb, var(--fk-accent, #d6f84c) 38%, var(--fk-bg, #f7f7f3));
+  box-shadow: 0 6px 18px -10px color-mix(in srgb, var(--fk-ink, #0b0b0b) 40%, transparent);
+}
+
+.fk-choice__icon {
+  flex: none;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  font-size: 28px;
+  line-height: 1;
+}
+
+.fk-choice__label { flex: 1; min-width: 0; overflow-wrap: anywhere; }
+
+/* round indicator on the right; a check mark when chosen */
+.fk-choice__mark {
+  position: relative;
+  flex: none;
+  box-sizing: border-box;
+  width: 24px;
+  height: 24px;
+  border: 2px solid color-mix(in srgb, var(--fk-ink, #0b0b0b) 28%, transparent);
+  border-radius: 50%;
+  transition: background-color 160ms ease-out, border-color 160ms ease-out;
+}
+
+/* MultiChoice: a square box, the rows are checkboxes */
+.fk-choice--multi .fk-choice__mark { border-radius: 6px; }
+
+.fk-choice__option[aria-checked="true"] .fk-choice__mark {
+  border-color: var(--fk-ink, #0b0b0b);
+  background: var(--fk-ink, #0b0b0b);
+}
+
+.fk-choice__option[aria-checked="true"] .fk-choice__mark::after {
+  content: "";
+  position: absolute;
+  left: 7px;
+  top: 3px;
+  width: 5px;
+  height: 10px;
+  border: solid var(--fk-accent, #d6f84c);
+  border-width: 0 2.5px 2.5px 0;
+  transform: rotate(45deg);
+}

package/templates/init/CLAUDE.md

@@ -0,0 +1,10 @@
+# Воронки проекта
+
+Правила — инструмент `get_guide` MCP-сервера `funnels`. Работай по разделу «Рабочий цикл».
+
+Токен проекта только в переменной `FUNNELS_TOKEN`, в файлы его не записывай.
+
+События (раздел guide «События»): ответы, нажатия и вызовы функций kit шлёт сам. Ответ записывай `f.set(ключ, значение, текст)` — третьим аргументом текст, который видел человек (`Choice`, `MultiChoice` и поле ввода его не требуют). Кнопке с текстом, собранным на ходу, ставь `data-track="имя"`. Предупреждения `funnel-kit build` (`warning`) читай и исправляй; ложные предупреждения оставь (число в переменной без текста, текст кнопки из `t()` в пропсе) — сборка идёт. После каждой загрузки и прохода по превью вызови `check_funnel` и исправь то, что он нашёл, до `publish`.
+
+Серверные функции (по желанию) — в `functions/index.ts` в корне: `export default defineFunctions({...})` из `@appright/funnelshift/functions`, со страницы — `await server('имя', payload)` из `@appright/funnelshift`. `funnel-kit build` сам собирает их в сборку. Бизнес-события и деньги — только из функции: `ctx.track('signup_completed')`.
+Ключи сторонних сервисов — только секреты проекта в сервисе (`set_secret`), в функции они приходят как `ctx.secrets`. В репо и в код их не клади.

package/templates/init/funnels/welcome/index.tsx

@@ -0,0 +1,129 @@
+import { defineFunnel, defineStep, useFunnel, t, Hero, Choice, MultiChoice, Cta } from '@appright/funnelshift'
+
+// A five-screen example: intro, one question, a question with several answers, a text field, a closing screen. Replace the
+// texts and the options with your own; every visible text goes through t('key', 'default'), so it can be edited later
+// without a rebuild.
+//
+// Every answer set() on a step is sent with that step, together with the text the person saw (label_<key>): the admin
+// shows "Saving money", not "save". In onChange, Choice and MultiChoice hand the option texts to set() by themselves; in
+// onPick you get the texts and pass them on yourself. A text field needs none (the value is the text); anything else gets
+// it as the third argument: f.set(key, value, label).
+
+function Intro() {
+  const f = useFunnel()
+  return (
+    <Hero
+      visual={<span aria-hidden="true">👋</span>}
+      title={t('intro.title', 'Let’s find what fits you best')}
+      highlight={t('intro.highlight', 'fits you best')}
+      subtitle={t('intro.subtitle', 'A few quick questions, it takes a minute.')}
+      cta={t('intro.cta', 'Start')}
+      onCta={() => f.next()}
+    />
+  )
+}
+
+type Goal = 'save' | 'learn' | 'time'
+
+// One answer: onChange passes the value to set() as it is, and the option text goes with it.
+function Pick() {
+  const f = useFunnel()
+  return (
+    <main className="screen">
+      <section className="screen__body" aria-labelledby="pick-title">
+        <h1 id="pick-title">{t('pick.title', 'What matters most to you?')}</h1>
+        <Choice
+          name="goal"
+          labelledBy="pick-title"
+          value={f.answers.goal as Goal | undefined}
+          onChange={v => f.set('goal', v)}
+          options={[
+            { value: 'save', label: t('pick.save', 'Saving money'), icon: '💸' },
+            { value: 'learn', label: t('pick.learn', 'Learning something new'), icon: '📚' },
+            { value: 'time', label: t('pick.time', 'Saving time'), icon: '⏳' },
+          ]}
+        />
+      </section>
+      <Cta onClick={() => f.next()} disabled={!f.answers.goal}>{t('pick.cta', 'Continue')}</Cta>
+    </main>
+  )
+}
+
+type Topic = 'tips' | 'news' | 'offers'
+
+// Several answers and a Continue button. Here the answer is recorded in onPick, so the texts come from onPick (its second
+// argument) and go to set() as the third argument; onChange={v => f.set('topics', v)} would send the same texts by itself.
+function Topics() {
+  const f = useFunnel()
+  const topics = (f.answers.topics as Topic[] | undefined) ?? []
+  return (
+    <main className="screen">
+      <section className="screen__body" aria-labelledby="topics-title">
+        <h1 id="topics-title">{t('topics.title', 'What would you like to hear about?')}</h1>
+        <MultiChoice
+          name="topics"
+          labelledBy="topics-title"
+          value={topics}
+          onPick={(values, texts) => f.set('topics', values, texts)}
+          options={[
+            { value: 'tips', label: t('topics.tips', 'Practical tips'), icon: '💡' },
+            { value: 'news', label: t('topics.news', 'Product news'), icon: '📰' },
+            { value: 'offers', label: t('topics.offers', 'Special offers'), icon: '🎁' },
+          ]}
+        />
+      </section>
+      <Cta onClick={() => f.next()} disabled={!topics.length}>{t('topics.cta', 'Continue')}</Cta>
+    </main>
+  )
+}
+
+// Free text: what the person typed is the answer and its text at once.
+function Name() {
+  const f = useFunnel()
+  const name = (f.answers.name as string | undefined) ?? ''
+  return (
+    <main className="screen">
+      <section className="screen__body">
+        <label className="field">
+          <span className="field__label">{t('name.label', 'What should we call you?')}</span>
+          <input
+            className="field__input"
+            name="name"
+            autoComplete="given-name"
+            maxLength={80}
+            value={name}
+            placeholder={t('name.placeholder', 'Your first name')}
+            onChange={e => f.set('name', e.target.value)}
+          />
+        </label>
+      </section>
+      <Cta onClick={() => f.next()} disabled={!name.trim()}>{t('name.cta', 'Continue')}</Cta>
+    </main>
+  )
+}
+
+// The last step must call next() too: that is what makes the kit send $funnel_complete.
+function Done() {
+  const f = useFunnel()
+  return (
+    <Hero
+      visual={<span aria-hidden="true">🎉</span>}
+      title={t('done.title', 'Thanks, that is all for now')}
+      highlight={t('done.highlight', 'Thanks')}
+      subtitle={t('done.subtitle', 'Your answers help us make this better.')}
+      cta={t('done.cta', 'Finish')}
+      onCta={() => f.next()}
+    />
+  )
+}
+
+export default defineFunnel({
+  id: 'welcome',
+  steps: [
+    defineStep({ id: 'intro', component: Intro, sample: {} }),
+    defineStep({ id: 'pick', component: Pick, sample: { answers: { goal: 'save' } } }),
+    defineStep({ id: 'topics', component: Topics, sample: { answers: { topics: ['tips', 'news'] } } }),
+    defineStep({ id: 'name', component: Name, sample: { answers: { name: 'Alex' } } }),
+    defineStep({ id: 'done', component: Done, sample: {} }),
+  ],
+})

package/templates/init/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.funnel-kit/
+.env
+.env.*

package/templates/init/package.json.tmpl

@@ -0,0 +1,20 @@
+{
+  "name": "{{project}}-funnels",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "funnel-kit build --funnel welcome",
+    "upload": "funnel-kit upload --funnel welcome"
+  },
+  "dependencies": {
+    "@appright/funnelshift": "^{{kit_version}}",
+    "react": "^19",
+    "react-dom": "^19"
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "typescript": "^7",
+    "vite": "^8"
+  }
+}

package/templates/init/theme.css

@@ -0,0 +1,77 @@
+/* "appright clean". The blocks bring their own styles; this file overrides the --fk-* variables and lays out the screens. */
+:root {
+  --fk-bg: #f7f7f3;
+  --fk-ink: #0b0b0b;
+  --fk-muted: #64645e;
+  --fk-accent: #d6f84c;
+  --fk-radius: 16px;
+}
+
+body {
+  margin: 0;
+  background: var(--fk-bg);
+  color: var(--fk-ink);
+  font: 17px/1.5 system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+
+h1 {
+  margin: 0;
+  font-size: clamp(36px, 9vw, 56px);
+  line-height: 1.05;
+  letter-spacing: -0.03em;
+  text-wrap: balance;
+}
+
+/* A screen: one centered column, the content in the middle, the Cta at the bottom. */
+.screen {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  min-height: 100dvh;
+  max-width: 480px;
+  margin: 0 auto;
+  padding: 24px 20px 0;
+}
+
+.screen__body {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  gap: 28px;
+  padding-bottom: 6dvh;
+}
+
+/* A text field: the question as a large label, the input as one of the choice rows. */
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+}
+
+.field__label {
+  font-size: clamp(30px, 7.5vw, 44px);
+  font-weight: 700;
+  line-height: 1.1;
+  letter-spacing: -0.02em;
+  text-wrap: balance;
+}
+
+.field__input {
+  box-sizing: border-box;
+  width: 100%;
+  min-height: 56px;
+  padding: 14px 18px;
+  border: 1.5px solid color-mix(in srgb, var(--fk-ink) 14%, transparent);
+  border-radius: var(--fk-radius);
+  background: #fff;
+  color: var(--fk-ink);
+  font: inherit;
+}
+
+.field__input:focus {
+  outline: none;
+  border-color: var(--fk-ink);
+  box-shadow: 0 0 0 4px var(--fk-accent);
+}

package/templates/init/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "compilerOptions": {
+    "target": "ES2022", "module": "ESNext", "moduleResolution": "Bundler", "jsx": "react-jsx",
+    "strict": true, "noEmit": true, "skipLibCheck": true
+  },
+  "include": ["funnels", "components", "functions"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.