Files
community-rule/docs/create-flow.md
T
adilallo 6498d52541 Skip setup questions on the template path and collect name, photo, and description without recommendations.
Customize opens a dialog then walks the template decks; Use without changes lands on final review with Has Name Field. Template cards stay first, the engine is not called, and the catalog no longer shows a recommended tag.
2026-11-09 17:34:33 -07:00

20 KiB
Raw Blame History

Create rule flow (custom wizard) — canonical reference

Product/engineering reference for the custom “Create rule” experience: URL order, persistence, and entry points. Canon wizard alignment (docs, [screenId] routing, footer progress) shipped under CR-89 (Done). Draft resume vs profile, server hydration, and “new rule” vs continue draft are tracked with CR-86 (profile dashboard). See also docs/guides/backend-linear-tickets.md Ticket 17.


Product stages (Figma)

The Figma Create Community sequence is the source of truth for the first segment of the wizard. After review, the flow continues with Create Custom CommunityRule and Review and complete stages. The shipped URL sequence in FLOW_STEP_ORDER follows that trajectory; stages are a product slice of that linear order, not separate routers today.

Stage (Figma) Purpose (summary) CreateFlowStep values (in order)
Create Community Intro, naming, structure, context, size, optional setup questions, upload, save progress (email), then community review. informational → community-name → community-structure → community-context → community-size → setup-questions → community-upload → community-save → review
Create Custom CommunityRule Author the CommunityRule content and structure (core values + four card-stack categories). core-values → communication-methods → membership-methods → decision-approaches → conflict-management
Review and complete Final card, invite members, finish, success. final-review → confirm-stakeholders → completed

Treat these stages as the canonical product sections when adding chrome (e.g. stage headers, progress copy), breaking work across teams, or reusing flows in other surfaces. Layout kind is not encoded in the URL; it lives in CREATE_FLOW_SCREEN_REGISTRY (Figma node id + layoutKind per step). Figma still names eight layout kinds: informational, text, select, upload, review, card, right-rail, completed. Question-and-options steps (select, card, right-rail) share CreateFlowTwoColumnSelectShell and Selection size variants (s chip, m tile, l row). app/(app)/create/screens/ still mirrors the Figma kind names.

Create from template: Starting from a template skips size, kind, scale, maturity, and the six setup questions. The group enters only name, photo, and description. There is no recommendation engine on this path. Customize opens a dialog, then walks values and the four decks with the template’s cards first. Use without changes skips the dialog and decks and lands on final review with the template’s cards. Identity is collected in the Customize dialog or on the final-review Rule card (Has Name Field). The pin is pendingTemplateAction: { slug, mode } on CreateFlowState.


Step order and URLs

Order is defined in code by FLOW_STEP_ORDER and the CreateFlowStep type. Wizard steps use a single dynamic route: app/(app)/create/[screenId]/page.tsx, which validates screenId and renders CreateFlowScreenView. Implementation files are grouped under app/(app)/create/screens/ by Figma layout kind (subfolders: informational, text, select, upload, review, card, right-rail, completed). /create redirects to the first step.

Order Figma stage Step ID (screenId) Path
1 Create Community informational /create/informational
2 Create Community community-name /create/community-name
3 Create Community community-structure /create/community-structure
4 Create Community community-context /create/community-context
5 Create Community community-size /create/community-size
6 Create Community setup-questions /create/setup-questions
7 Create Community community-upload /create/community-upload
8 Create Community community-save /create/community-save
9 Create Community (review frame) review /create/review
10 Create Custom CommunityRule core-values /create/core-values
11 Create Custom CommunityRule communication-methods /create/communication-methods
12 Create Custom CommunityRule membership-methods /create/membership-methods
13 Create Custom CommunityRule decision-approaches /create/decision-approaches
14 Create Custom CommunityRule conflict-management /create/conflict-management
15 Review and complete final-review /create/final-review
16 Review and complete confirm-stakeholders /create/confirm-stakeholders
17 Review and complete completed /create/completed

Primary entry: marketing header Create rule and profile Create new custom Rule both run prepareFreshCreateFlowEntry then navigate to /create, which redirects to /create/informational (see Top.container.tsx and ProfilePageClient.tsx).

Active step for chrome and navigation is resolved from the pathname via parseCreateFlowScreenFromPathname inside useCreateFlowNavigation.

Custom-rule facet catalog and /create path helpers (CR-92)

CUSTOM_RULE_FACETS is the single table for template category keys, CreateFlowStep, footer confirm bindings, selected* / strip keys, and the four GET /api/create-flow/methods?section= ids. Update that module (and related tests) when adding or renaming a custom-rule facet instead of scattering new switches across applyTemplatePrefill, customRuleConfirmFooterSteps, buildFinalReviewCategories, stripCustomRuleSelectionFields, etc.

createFlowPaths centralises /create/{step} builders and shared constants (CREATE_ROUTES, syncDraft helpers). Prefer these over raw string literals in layout, hooks, and redirects.

Wizard step → React screen rendering lives in createFlowScreenComponents.tsx (renderCreateFlowScreen), paired with CREATE_FLOW_SCREEN_REGISTRY for Figma/layout metadata.

Stakeholder emails (confirm-stakeholders)

The step persists stakeholderEmails on CreateFlowState (validated on PUT /api/drafts/me). On first publish (POST /api/rules) with a session, the server records RuleStakeholder rows and emails each address a one-time link to GET /api/invites/rule-stakeholder/verify. Guests can still publish; invites are skipped until they sign in. Opening the link creates or signs in the account for that email and redirects to the public rule; the rule also appears on the invitee’s profile with view access (not manage). After publish, owners manage invites from /create/edit-rule via Manage Stakeholders, which opens /create/confirm-stakeholders?reviewReturn=edit-rule&manageStakeholders=1 (same screen layout as the pre-publish step, backed by GET / POST DELETE / resend). PATCH /api/rules/[id] still does not read stakeholder emails from the wizard draft.

Fresh start vs continue draft (signed-in + sync)

Established pattern: anonymous and signed-in users should see the same wizard when starting a new rule from marketing or profile: empty state at the first step, with no surprise reload of old work. Both can publish (guests get an unlisted public /rules/{id} with no owner). Both see Save & Exit from community-structure onward (and edit-rule). On /create/completed, guests still get Save & Exit (keep-this-rule magic-link modal); signed-in users get Exit. Wizard guests open the save-progress magic-link modal; signed-in users may PUT /api/drafts/me when NEXT_PUBLIC_ENABLE_BACKEND_SYNC=true.

  • New rule entry (always a clean slate): call prepareFreshCreateFlowEntry before router.push into /create or /create/review-template/.... It clears create-flow-anonymous and the core-value-details localStorage key; when sync is on, it DELETEs /api/drafts/me so SignedInDraftHydration does not rehydrate a stale server draft after local storage was wiped.
  • Continue saved draft (profile): do not call prepareFreshCreateFlowEntry. Clear the same localStorage keys only (see ProfilePageClient handleContinueDraft) so the client mirror is empty, then navigate to /create/{savedStep}. Hydration loads the server draft; the URL may be corrected to currentStep when it differs from the path.
  • Local-only wipe without touching the server: clearCreateFlowPersistedDrafts (same two localStorage keys). Prefer prepareFreshCreateFlowEntry for any user-facing “start new rule” navigation so signed-in + sync stays aligned with anonymous.

Call sites for prepareFreshCreateFlowEntry: Top.container.tsx (Create rule), profile Create new custom Rule (ProfilePageClient.tsx), home Popular templates (RuleStack.container.tsx), and direct /templates template picks (TemplatesPageClient.tsx) when fromFlow is absent.


Auxiliary route (not a wizard step or Figma stage)

Path Purpose
/create/review-template/[slug] Template preview in the create shell; uses the same layout/footer chrome as other create pages but is not part of FLOW_STEP_ORDER or the three Figma stages above.
/create/templates In-flow template catalog after review Create from template. Same create chrome (Back, Save & Exit); cards link to /create/review-template/[slug]?fromFlow=1. Marketing /templates stays the public catalog.

From that page, Customize opens a dialog for name, optional logo, description (“What does your community do?”), and optional city or region. Continue prefills the template’s cards and values (via buildTemplateCustomizePrefill plus catalog copy from templatePresetDetailsFromPrefill), pins pendingTemplateAction: { slug, mode: "customize" }, and routes to /create/core-values. Size, kind, scale, maturity, and setup questions are skipped. The decks show the template’s cards first, then the rest of the deck, with no RECOMMENDED tag, no seven-card cut, and no engine call (templateDeck in deckRecommend.ts). Confirm on each deck walks communication → membership → decisions → conflict → final review. Back from values returns to template review; Back from named final review returns to the conflict deck.

Exit on template preview. Direct catalog / marketing entry (/create/review-template/[slug] without ?fromFlow=1) has nothing to save — top-nav Exit clears client state and goes home, with no save-progress modal and no leave confirm. In-flow (?fromFlow=1) still has community progress, so Exit keeps the usual save / leave-confirm path.

Use without changes skips the dialog, seeds the template’s cards (chip ids from templateChips.json plus state.sections titles), pins pendingTemplateAction: { slug, mode: "useWithoutChanges" }, and routes to /create/final-review. Direct catalog entry clears leftover identity so the Rule card can collect name, photo, and description. In-flow keeps the community answers already given. Continue on final review waits for a name, then opens Invite your members. Finishing there runs handleFinalize → publishRule. Guests can publish without signing in (POST /api/rules with userId null); stakeholder invites are sent only when a session exists. Every card that reads the group’s share uses three quarters (LAUNCH_SUPERMAJORITY_SHARE); final review does not ask for a share.

The pin stays for the rest of the wizard so decks skip the engine, final review shows Has Name Field, and Back knows the path. If a leftover pin lands on /create/review, CommunityReviewScreen replaces to core-values (Customize) or final-review (Use without changes).

  • Customize — dialog, then values and the four decks, then final review with the dialog’s Community name filled in. Add chips on final review open that template deck or the template values; Confirm returns to final review (?reviewReturn=final-review).
  • Use without changes (direct) — home Popular templates, /templates without fromFlow, or a pasted review-template URL. Identity is collected on the final-review Rule card. Back returns to template review.
  • Use without changes (in-flow) — /create/review → /create/templates → template. Community identity is already collected. Back still returns to template review.

Direct entry vs in-flow template pick. The same /create/review-template/[slug] URL is reached from two different origins. We disambiguate at the click site, not on the review-template page. Direct picks call prepareFreshCreateFlowEntry before navigation (local + server draft when sync is on — see Fresh start vs continue draft above). In-flow picks skip that call so the user’s community-stage state survives the detour. Because CreateFlowProvider reads localStorage in its useState initializer, clearing before push means a direct entry mounts without stale anonymous keys; signed-in users also avoid a stale server draft overwriting the empty mirror.

Origin Click-site behavior URL the user lands on
Home marketing "Popular templates" (RuleStack.container.tsx) always await prepareFreshCreateFlowEntry() then navigate /create/review-template/[slug]
/templates index (TemplatesPageClient.tsx) visited directly / via pasted URL fromFlow absent → await prepareFreshCreateFlowEntry() then navigate /create/review-template/[slug]
In-flow: /create/review footer "Create from template" → /create/templates → template click no fresh-entry prep; cards are ?fromFlow=1 links /create/review-template/[slug]?fromFlow=1

Only one ?fromFlow=1 marker exists on template-review URLs. In-flow catalog clicks on /create/templates always include it so Use without changes can keep in-flow identity instead of clearing it. Profile still uses marketing /templates?fromFlow=1. Templates on /templates and /create/templates show in curated order with no RECOMMENDED tag; facet scoring is unused.

Resume from profile remains explicit-only: Continue clears local mirrors then opens /create/{step} so SignedInDraftHydration can load /api/drafts/me when the client buffer is empty. There is no automatic “pick template from marketing → silently merge server draft” path.

Final-review Rule category chips are derived from CreateFlowState via buildFinalReviewCategoriesFromState: for the Customize / plain custom-rule path it resolves selected{Communication,Membership,DecisionApproach,ConflictManagement}MethodIds against the curated method presets in messages/en/create/customRule/*.json, and buildCoreValuesForDocument supplies the Values row from coreValuesChipsSnapshot + selectedCoreValueIds. For the Use-without-changes path the template body lives in state.sections; the helper renders categoryName + entry titles directly, and preset ids from the chip file keep chips editable. The demo chips shipped in finalReview.json remain the fallback only when nothing in state resolves to any chip (e.g. direct navigation for development).


Persistence and exit

Mode Where progress lives Save & Exit / publish
Anonymous localStorage key create-flow-anonymous Save & Exit (from community-structure onward, plus edit-rule) opens the save-progress magic-link modal; after verify, optional PUT /api/drafts/me when NEXT_PUBLIC_ENABLE_BACKEND_SYNC=true (see Tickets 4–5 in guides/backend-linear-tickets.md). Publish POSTs /api/rules without a session (userId null) and sets httpOnly cr_rule_claim. Landing on /create/completed opens a keep-this-rule magic-link modal (no draft transfer); the top nav stays Save & Exit so they can reopen it (Continue without saving from that control leaves the flow). After Publish, skip on the auto-opened modal stays on completed. Edit shows when a last-published rule is in session storage. The public URL works; the row is omitted from GET /api/rules until claimed. Signing in on the same browser attaches userId (profile, edit, invites).
Signed-in In-memory React state in CreateFlowContext Save & Exit from the community-structure step onward (and edit-rule) may PUT /api/drafts/me when sync is on. Completed is Exit. Publish stores the rule with userId. Sign out is on profile, not in the create top nav.

Details and edge cases (conflict confirm, banners, ?syncDraft=1) match Ticket 4, Ticket 5, and docs/guides/backend-roadmap.md §12.


Known implementation gaps

  • Profile + drafts (CR-86): The profile page lists the server draft. Continue clears anonymous localStorage (and core-value details) then deep-links to /create/{currentStep} so hydration loads the server draft. Create new custom Rule and marketing Create rule use prepareFreshCreateFlowEntry (local + DELETE /api/drafts/me when sync is on) before opening the wizard so signed-in behavior matches a fresh anonymous start. SignedInDraftHydration may router.replace to the saved step when it applies a server draft so the URL matches hydrated state. Remaining edge cases (e.g. template review routes) are handled when they surface in QA.
  • Inner “text/select shells”: deferred until Create Community is stable; screens use CreateFlowStepShell only for Stage 1.