Superminaren/hackerspace.sh
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: configurable member onboarding + UX/persona research

Browse Source 
A new member who joins via invite code now walks through an
admin-defined onboarding sequence before reaching the app.

Schema (migration 022, folded into schema.sql Section 14):
- space_onboarding_steps: step_key, step_type
  (welcome|code_of_conduct|profile|payment|content), title, body,
  config jsonb, is_enabled, is_required, is_system, sort_order,
  unique per (space, step_key). Full RLS: members read, admin/board
  write, admin delete non-system.
- space_members.onboarding_completed_at + onboarding_progress jsonb.
- Trigger seeds four default steps per space (welcome, code of
  conduct [required], profile, dues). Backfill seeds existing spaces
  and marks all existing members complete so the new gate never
  traps them.

Flow:
- /onboarding (top-level route, outside the (app) group so no
  redirect loop). Progress bar, step counter, back/continue, per-type
  rendering. Profile step calls updateMyProfile; payment step is a
  non-blocking nudge with optional link and "Remind me later".
- (app)/layout.tsx redirects to /onboarding while
  onboarding_completed_at is null.
- createSpace marks the founder complete: founders configure the
  space, they do not run the member flow (matches admin-vs-end-user
  persona research).
- finishOnboarding re-checks required steps server-side so a tampered
  client cannot skip a required code-of-conduct acknowledgement.
  skipOnboarding only works when nothing is required.

Admin config:
- Settings -> Onboarding tab: reorder, edit title/body/payment link,
  toggle enabled/required, add custom content steps, delete
  non-system steps.

Safety:
- components/safe-markdown.tsx renders admin-authored markdown and a
  sanitized subset of HTML (rehype-raw + rehype-sanitize). Added
  those two deps.

Also:
- bio added to updateMyProfileSchema (members can self-set it; not
  blocked by the migration-015 trigger).
- docs/UX_AND_PERSONAS.md: 4 personas and prioritized UX audit
  findings. Onboarding was finding #1; 2-6 deferred and tracked.

266/266 unit tests pass. Production build clean, /onboarding in the
route table. Migration 022 applies idempotently on the next deploy.
This commit is contained in:
Moheeb Zara
2026-05-15 15:38:40 -07:00
parent 96a1fb9ef6
commit 30bba045f8
17 changed files with 1243 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
app/(app)/layout.tsx
+9
View File
@@ -25,6 +25,15 @@ export default async function AppLayout({ children }: { children: React.ReactNod
redirect('/login')
}
// New members walk through the space's configured onboarding before they
// reach the app. Founders (createSpace) and pre-existing members (migration
// 022 backfill) have onboarding_completed_at set, so this only gates
// genuinely-new joiners. /onboarding is outside this layout group, so there
// is no redirect loop.
if (!(member as { onboarding_completed_at?: string | null }).onboarding_completed_at) {
redirect('/onboarding')
}
// Count badges
const { count: taskCount } = await supabase
.from('tasks')
app/(app)/settings/page.tsx
+18
View File
@@ -37,6 +37,12 @@ export default async function SettingsPage() {
.eq('space_id', member.space_id)
.order('created_at', { ascending: false })
const { data: onboardingSteps } = await supabase
.from('space_onboarding_steps')
.select('id, step_key, step_type, title, body, config, is_enabled, is_required, is_system, sort_order')
.eq('space_id', member.space_id)
.order('sort_order', { ascending: true })
const isAdmin = member?.role === 'admin'
return (
@@ -74,6 +80,18 @@ export default async function SettingsPage() {
is_enabled: boolean
created_at: string
}>}
onboardingSteps={(onboardingSteps ?? []) as Array<{
id: string
step_key: string
step_type: 'welcome' | 'code_of_conduct' | 'profile' | 'payment' | 'content'
title: string
body: string | null
config: Record<string, unknown>
is_enabled: boolean
is_required: boolean
is_system: boolean
sort_order: number
}>}
/>
)
}
app/(app)/settings/settings-client.tsx
+177 -4
View File
@@ -2,7 +2,7 @@
import { useState } from 'react'
import { X, Check, Copy, Eye, EyeOff, RotateCcw } from 'lucide-react'
import { updateSpaceSettings, saveIntegration, disconnectIntegration, rotateWebhookSecret, updateSpaceVisibility, createArea, updateArea, deleteArea, createTier, updateTier, deleteTier, createInvite, updateInvite, deleteInvite } from '@/lib/actions'
import { updateSpaceSettings, saveIntegration, disconnectIntegration, rotateWebhookSecret, updateSpaceVisibility, createArea, updateArea, deleteArea, createTier, updateTier, deleteTier, createInvite, updateInvite, deleteInvite, createOnboardingStep, updateOnboardingStep, deleteOnboardingStep } from '@/lib/actions'
import { toast } from 'sonner'
import { financialVisibilities, directoryVisibilities } from '@/lib/validations'
@@ -27,6 +27,20 @@ interface Props {
areas: Area[]
tiers: Tier[]
invites: Invite[]
onboardingSteps: OnboardingStep[]
}
export interface OnboardingStep {
id: string
step_key: string
step_type: 'welcome' | 'code_of_conduct' | 'profile' | 'payment' | 'content'
title: string
body: string | null
config: Record<string, unknown>
is_enabled: boolean
is_required: boolean
is_system: boolean
sort_order: number
}
export interface Tier {
@@ -124,8 +138,9 @@ const INTEGRATIONS_CONFIG = [
},
]
export default function SettingsClient({ space, isAdmin, integrations, currentRole, areas: initialAreas, tiers: initialTiers, invites: initialInvites }: Props) {
const [activeTab, setActiveTab] = useState<'space' | 'roles' | 'tiers' | 'invites' | 'integrations' | 'webhooks'>('space')
export default function SettingsClient({ space, isAdmin, integrations, currentRole, areas: initialAreas, tiers: initialTiers, invites: initialInvites, onboardingSteps: initialOnboarding }: Props) {
const [activeTab, setActiveTab] = useState<'space' | 'roles' | 'tiers' | 'invites' | 'onboarding' | 'integrations' | 'webhooks'>('space')
const [onboardingSteps, setOnboardingSteps] = useState<OnboardingStep[]>(initialOnboarding)
const [areas, setAreas] = useState<Area[]>(initialAreas)
const [tiers, setTiers] = useState<Tier[]>(initialTiers)
const [invites, setInvites] = useState<Invite[]>(initialInvites)
@@ -268,7 +283,7 @@ export default function SettingsClient({ space, isAdmin, integrations, currentRo
<div className="flex-1 p-4 md:p-6">
{/* Tabs */}
<div className="bg-card border-b border-border flex gap-4 md:gap-6 px-2 mb-6 rounded-t overflow-x-auto">
{(['space', 'roles', 'tiers', 'invites', 'integrations', 'webhooks'] as const).map(tab => (
{(['space', 'roles', 'tiers', 'invites', 'onboarding', 'integrations', 'webhooks'] as const).map(tab => (
<button
key={tab}
onClick={() => setActiveTab(tab)}
@@ -1038,6 +1053,164 @@ export default function SettingsClient({ space, isAdmin, integrations, currentRo
</div>
)}
{/* Onboarding Tab */}
{activeTab === 'onboarding' && (
<div className="bg-card rounded border border-border p-6">
<div className="flex items-center justify-between mb-4 gap-3">
<div>
<p className="font-mono text-[10px] tracking-widest text-muted-foreground uppercase">New member onboarding</p>
<p className="font-sans text-sm text-muted-foreground mt-1">
These steps run, in order, the first time a new member opens the app. Reorder with the sort number. Disable a step to hide it. Built-in steps cannot be deleted, only disabled. Body text supports markdown and a safe subset of HTML.
</p>
</div>
{isAdmin && (
<button
onClick={async () => {
const result = await createOnboardingStep({
step_type: 'content',
title: 'New step',
body: 'Edit this content in Settings, Onboarding.',
sort_order: (onboardingSteps.reduce((m, s) => Math.max(m, s.sort_order), 0) + 1),
})
if ('error' in result && result.error) { toast.error(result.error); return }
toast.success('Step added. Edit it below.')
setOnboardingSteps(prev => [...prev, {
id: (result as { id: string }).id,
step_key: `custom-${(result as { id: string }).id.slice(0, 12)}`,
step_type: 'content',
title: 'New step',
body: 'Edit this content in Settings, Onboarding.',
config: {},
is_enabled: true,
is_required: false,
is_system: false,
sort_order: (onboardingSteps.reduce((m, s) => Math.max(m, s.sort_order), 0) + 1),
}])
}}
className="font-mono text-[10px] border border-border px-3 py-1.5 rounded hover:border-primary hover:text-primary transition whitespace-nowrap"
>
+ Custom step
</button>
)}
</div>
<ul className="space-y-3">
{[...onboardingSteps].sort((a, b) => a.sort_order - b.sort_order).map(s => (
<li key={s.id} className="border border-border rounded p-4">
<div className="flex items-center gap-3 mb-3 flex-wrap">
<input
type="number"
defaultValue={s.sort_order}
disabled={!isAdmin}
onBlur={async e => {
const next = parseInt(e.target.value, 10)
if (isNaN(next) || next === s.sort_order) return
const result = await updateOnboardingStep(s.id, { sort_order: next })
if (result.error) { toast.error(result.error); return }
setOnboardingSteps(prev => prev.map(x => x.id === s.id ? { ...x, sort_order: next } : x))
}}
className="w-14 bg-background border border-border text-foreground font-mono text-xs rounded px-2 py-1 focus:outline-none focus:border-primary"
/>
<span className="font-mono text-[10px] px-1.5 py-0.5 rounded bg-muted text-muted-foreground uppercase">{s.step_type.replace(/_/g, ' ')}</span>
<input
type="text"
defaultValue={s.title}
disabled={!isAdmin}
onBlur={async e => {
const next = e.target.value.trim()
if (!next || next === s.title) return
const result = await updateOnboardingStep(s.id, { title: next })
if (result.error) { toast.error(result.error); return }
setOnboardingSteps(prev => prev.map(x => x.id === s.id ? { ...x, title: next } : x))
}}
className="flex-1 min-w-[160px] bg-background border border-border text-foreground font-sans text-sm rounded px-2 py-1 focus:outline-none focus:border-primary"
/>
{s.is_system && <span className="font-mono text-[10px] text-amber-600">built-in</span>}
</div>
{(s.step_type === 'welcome' || s.step_type === 'code_of_conduct' || s.step_type === 'payment' || s.step_type === 'content') && (
<textarea
defaultValue={s.body ?? ''}
disabled={!isAdmin}
rows={4}
maxLength={50000}
onBlur={async e => {
const next = e.target.value
if (next === (s.body ?? '')) return
const result = await updateOnboardingStep(s.id, { body: next })
if (result.error) { toast.error(result.error); return }
setOnboardingSteps(prev => prev.map(x => x.id === s.id ? { ...x, body: next } : x))
}}
placeholder="Markdown / safe HTML. For payment steps, describe how to pay."
className="w-full bg-background border border-border text-foreground font-mono text-xs rounded px-2 py-2 focus:outline-none focus:border-primary mb-3"
/>
)}
{s.step_type === 'payment' && (
<input
type="url"
defaultValue={(s.config?.payment_url as string) ?? ''}
disabled={!isAdmin}
placeholder="Payment link (https://...)"
onBlur={async e => {
const next = e.target.value.trim()
if (next === ((s.config?.payment_url as string) ?? '')) return
const result = await updateOnboardingStep(s.id, { config: { ...s.config, payment_url: next } })
if (result.error) { toast.error(result.error); return }
setOnboardingSteps(prev => prev.map(x => x.id === s.id ? { ...x, config: { ...x.config, payment_url: next } } : x))
}}
className="w-full bg-background border border-border text-foreground font-mono text-xs rounded px-2 py-2 focus:outline-none focus:border-primary mb-3"
/>
)}
{isAdmin && (
<div className="flex items-center gap-4 flex-wrap">
<label className="flex items-center gap-1.5 cursor-pointer">
<input
type="checkbox"
checked={s.is_enabled}
onChange={async e => {
const result = await updateOnboardingStep(s.id, { is_enabled: e.target.checked })
if (result.error) { toast.error(result.error); return }
setOnboardingSteps(prev => prev.map(x => x.id === s.id ? { ...x, is_enabled: e.target.checked } : x))
}}
/>
<span className="font-mono text-[10px] text-muted-foreground uppercase tracking-widest">Enabled</span>
</label>
<label className="flex items-center gap-1.5 cursor-pointer">
<input
type="checkbox"
checked={s.is_required}
onChange={async e => {
const result = await updateOnboardingStep(s.id, { is_required: e.target.checked })
if (result.error) { toast.error(result.error); return }
setOnboardingSteps(prev => prev.map(x => x.id === s.id ? { ...x, is_required: e.target.checked } : x))
}}
/>
<span className="font-mono text-[10px] text-muted-foreground uppercase tracking-widest">Required</span>
</label>
{!s.is_system && (
<button
onClick={async () => {
if (!confirm(`Delete step "${s.title}"?`)) return
const result = await deleteOnboardingStep(s.id)
if (result.error) { toast.error(result.error); return }
setOnboardingSteps(prev => prev.filter(x => x.id !== s.id))
toast.success('Step deleted')
}}
className="ml-auto font-mono text-[10px] border border-border px-2 py-1 rounded hover:border-red-500 hover:text-red-500 transition"
>
Delete
</button>
)}
</div>
)}
</li>
))}
</ul>
</div>
)}
{/* Webhooks Tab */}
{activeTab === 'webhooks' && (
<div className="bg-card rounded border border-border p-6 space-y-6">
app/onboarding/onboarding-flow.tsx
+239
View File
@@ -0,0 +1,239 @@
'use client'
import { useState } from 'react'
import { useRouter } from 'next/navigation'
import { toast } from 'sonner'
import { AtlasLogo } from '@/components/resources/atlas-logo'
import { SafeMarkdown } from '@/components/safe-markdown'
import {
markOnboardingStepDone,
finishOnboarding,
skipOnboarding,
updateMyProfile,
} from '@/lib/actions'
type StepType = 'welcome' | 'code_of_conduct' | 'profile' | 'payment' | 'content'
interface Step {
id: string
step_type: StepType
title: string
body: string | null
config: Record<string, unknown>
is_required: boolean
}
interface Props {
spaceName: string
steps: Step[]
canSkip: boolean
profile: {
display_name: string
handle: string
bio: string
skills: string[]
interests: string[]
}
}
export function OnboardingFlow({ spaceName, steps, canSkip, profile: initialProfile }: Props) {
const router = useRouter()
const [index, setIndex] = useState(0)
const [busy, setBusy] = useState(false)
const [acked, setAcked] = useState<Record<string, boolean>>({})
const [profile, setProfile] = useState(initialProfile)
const step = steps[index]
const isLast = index === steps.length - 1
const requireAck = step.config?.require_ack === true
const ackLabel = (step.config?.ack_label as string) || 'I have read and agree'
const ackOk = !requireAck || acked[step.id]
async function advance() {
setBusy(true)
await markOnboardingStepDone(step.id)
setBusy(false)
if (isLast) {
await finish()
} else {
setIndex(i => i + 1)
}
}
async function finish() {
setBusy(true)
const result = await finishOnboarding()
setBusy(false)
if (result.error) { toast.error(result.error); return }
router.push('/dashboard')
}
async function handleSkipAll() {
setBusy(true)
const result = await skipOnboarding()
setBusy(false)
if (result.error) { toast.error(result.error); return }
router.push('/dashboard')
}
async function saveProfileAndAdvance() {
setBusy(true)
const result = await updateMyProfile({
display_name: profile.display_name.trim() || undefined,
handle: profile.handle.trim() || null,
bio: profile.bio.trim() || null,
skills: profile.skills,
interests: profile.interests,
})
if ('error' in result && result.error) { setBusy(false); toast.error(result.error); return }
await markOnboardingStepDone(step.id)
setBusy(false)
if (isLast) await finish()
else setIndex(i => i + 1)
}
const progressPct = Math.round(((index) / steps.length) * 100)
return (
<div className="min-h-screen bg-sidebar flex flex-col">
<header className="px-4 md:px-6 py-4 flex items-center gap-2 border-b border-sidebar-border">
<AtlasLogo className="w-6 h-6 text-primary" />
<span className="font-mono text-sm font-bold text-white">{spaceName}</span>
{canSkip && (
<button
onClick={handleSkipAll}
disabled={busy}
className="ml-auto font-mono text-[11px] text-sidebar-foreground/60 hover:text-white transition"
>
Skip for now
</button>
)}
</header>
<div className="h-1 bg-sidebar-border">
<div className="h-1 bg-primary transition-all duration-300" style={{ width: `${progressPct}%` }} />
</div>
<main className="flex-1 flex items-start justify-center p-4 md:p-8">
<div className="w-full max-w-2xl bg-card border border-border rounded-lg mt-6 md:mt-12">
<div className="px-6 py-4 border-b border-border flex items-center justify-between">
<p className="font-mono text-[10px] tracking-widest text-muted-foreground uppercase">
Step {index + 1} of {steps.length}
</p>
{step.is_required && (
<span className="font-mono text-[10px] text-amber-600">required</span>
)}
</div>
<div className="px-6 py-6">
<h1 className="font-sans text-xl font-semibold text-foreground mb-4">{step.title}</h1>
{step.step_type === 'profile' ? (
<div className="space-y-4">
{step.body && <SafeMarkdown>{step.body}</SafeMarkdown>}
<div>
<label className="font-mono text-[10px] tracking-widest text-muted-foreground uppercase block mb-1">Display name</label>
<input
type="text"
value={profile.display_name}
onChange={e => setProfile({ ...profile, display_name: e.target.value })}
maxLength={100}
className="w-full bg-background border border-border text-foreground font-sans text-sm rounded px-3 py-2 focus:outline-none focus:border-primary"
/>
</div>
<div>
<label className="font-mono text-[10px] tracking-widest text-muted-foreground uppercase block mb-1">Handle</label>
<input
type="text"
value={profile.handle}
onChange={e => setProfile({ ...profile, handle: e.target.value })}
maxLength={50}
placeholder="optional"
className="w-full bg-background border border-border text-foreground font-sans text-sm rounded px-3 py-2 focus:outline-none focus:border-primary"
/>
</div>
<div>
<label className="font-mono text-[10px] tracking-widest text-muted-foreground uppercase block mb-1">Bio</label>
<textarea
value={profile.bio}
onChange={e => setProfile({ ...profile, bio: e.target.value })}
rows={3}
maxLength={2000}
placeholder="optional"
className="w-full bg-background border border-border text-foreground font-sans text-sm rounded px-3 py-2 focus:outline-none focus:border-primary"
/>
</div>
<div>
<label className="font-mono text-[10px] tracking-widest text-muted-foreground uppercase block mb-1">Skills (comma separated)</label>
<input
type="text"
defaultValue={profile.skills.join(', ')}
onChange={e => setProfile({ ...profile, skills: e.target.value.split(',').map(s => s.trim()).filter(Boolean).slice(0, 40) })}
className="w-full bg-background border border-border text-foreground font-sans text-sm rounded px-3 py-2 focus:outline-none focus:border-primary"
/>
</div>
</div>
) : step.step_type === 'payment' ? (
<div className="space-y-4">
{step.body && <SafeMarkdown>{step.body}</SafeMarkdown>}
{typeof step.config?.payment_url === 'string' && step.config.payment_url && (
<a
href={step.config.payment_url as string}
target="_blank"
rel="noopener noreferrer"
className="inline-flex items-center gap-2 bg-primary text-white text-sm font-sans px-4 py-2 rounded hover:bg-primary/90 transition"
>
Set up payment
</a>
)}
</div>
) : (
<div className="space-y-4">
{step.body && <SafeMarkdown>{step.body}</SafeMarkdown>}
{requireAck && (
<label className="flex items-start gap-2 cursor-pointer">
<input
type="checkbox"
checked={!!acked[step.id]}
onChange={e => setAcked({ ...acked, [step.id]: e.target.checked })}
className="mt-0.5"
/>
<span className="font-sans text-sm text-foreground">{ackLabel}</span>
</label>
)}
</div>
)}
</div>
<div className="px-6 py-4 border-t border-border flex items-center justify-between gap-3">
<button
onClick={() => setIndex(i => Math.max(0, i - 1))}
disabled={index === 0 || busy}
className="font-sans text-sm text-muted-foreground hover:text-foreground transition disabled:opacity-40"
>
Back
</button>
<div className="flex items-center gap-2">
{step.step_type === 'payment' && !isLast && (
<button
onClick={advance}
disabled={busy}
className="font-sans text-sm text-muted-foreground hover:text-foreground transition px-3 py-2"
>
Remind me later
</button>
)}
<button
onClick={step.step_type === 'profile' ? saveProfileAndAdvance : advance}
disabled={busy || !ackOk}
className="bg-primary text-white text-sm font-sans px-4 py-2 rounded hover:bg-primary/90 transition disabled:opacity-50"
>
{busy ? 'Saving...' : isLast ? 'Finish' : step.step_type === 'payment' ? 'I have set this up' : 'Continue'}
</button>
</div>
</div>
</div>
</main>
</div>
)
}
app/onboarding/page.tsx
+64
View File
@@ -0,0 +1,64 @@
import { redirect } from 'next/navigation'
import { createClient } from '@/lib/supabase/server'
import { OnboardingFlow } from './onboarding-flow'
export const dynamic = 'force-dynamic'
export default async function OnboardingPage() {
const supabase = await createClient()
const { data: { user } } = await supabase.auth.getUser()
if (!user) redirect('/login')
const { data: member } = await supabase
.from('space_members')
.select('id, space_id, display_name, handle, bio, phone, skills, interests, onboarding_completed_at, spaces(name)')
.eq('user_id', user.id)
.in('status', ['current', 'unverified', 'late'])
.order('joined_at', { ascending: true })
.limit(1)
.maybeSingle()
if (!member) redirect(`/signup?email=${encodeURIComponent(user.email || '')}`)
if (member.onboarding_completed_at) redirect('/dashboard')
const { data: steps } = await supabase
.from('space_onboarding_steps')
.select('id, step_key, step_type, title, body, config, is_required')
.eq('space_id', member.space_id)
.eq('is_enabled', true)
.order('sort_order', { ascending: true })
// No steps configured: nothing to show. Mark complete and move on.
if (!steps || steps.length === 0) {
await supabase
.from('space_members')
.update({ onboarding_completed_at: new Date().toISOString() })
.eq('id', member.id)
redirect('/dashboard')
}
const canSkip = !steps.some(s => s.is_required)
const spaceName = (member.spaces as { name?: string } | null)?.name ?? 'your space'
return (
<OnboardingFlow
spaceName={spaceName}
steps={steps.map(s => ({
id: s.id,
step_type: s.step_type as 'welcome' | 'code_of_conduct' | 'profile' | 'payment' | 'content',
title: s.title,
body: s.body,
config: (s.config ?? {}) as Record<string, unknown>,
is_required: s.is_required,
}))}
canSkip={canSkip}
profile={{
display_name: member.display_name ?? '',
handle: member.handle ?? '',
bio: member.bio ?? '',
skills: (member.skills as string[] | null) ?? [],
interests: (member.interests as string[] | null) ?? [],
}}
/>
)
}