useBuildOn

Location: src/hooks/useBuildOn.js

Overview

Manages the "Build On" feature, which lets users create new posts that reference and respond to an existing post. This establishes a dialogue chain between posts. The hook handles composer state, post submission with the builds_on_post_id reference, optional quoted excerpts, circle linking, author notification, and W.E.L. cultural prompts.

Signature

function useBuildOn(
  userId: string,
  userDisplayName: string
): {
  isComposerOpen: boolean,
  originalPost: Post | null,
  quotedText: string,
  isSubmitting: boolean,
  error: string | null,
  openBuildOn: (post: Post, selectedText?: string) => void,
  closeBuildOn: () => void,
  submitBuildOn: (options: { content: string, intent: string, audience?: string, circleIds?: string[] }) => Promise<{ success: boolean, post?: Post, error?: string }>,
  canBuildOn: (post: Post) => boolean,
  setQuotedText: (text: string) => void,
  welPrompt: object | null,
  dismissWelPrompt: () => void
}

Parameters

Parameter	Type	Required	Description
userId	string	Yes	The current user's ID
userDisplayName	string	Yes	The current user's display name (used in notification body)

Return Value

Property	Type	Description
isComposerOpen	boolean	Whether the Build On composer is open
originalPost	Post | null	The post being built upon
quotedText	string	Text selected/quoted from the original post
isSubmitting	boolean	Whether the Build On post is being submitted
error	string | null	Error message if submission failed
openBuildOn	(post, selectedText?) => void	Open the composer targeting a specific post, optionally with selected text
closeBuildOn	() => void	Close the composer and reset all state
submitBuildOn	(options) => Promise<Result>	Create the Build On post. Options: content (required), intent (required), audience (default 'friends'), circleIds (for circle audience).
canBuildOn	(post) => boolean	Check if a post can be built upon (any visible post with an ID)
setQuotedText	(text) => void	Update the quoted text excerpt
welPrompt	object | null	W.E.L. cultural prompt (10% chance after successful Build On)
dismissWelPrompt	() => void	Dismiss the W.E.L. prompt

Usage

import { useBuildOn } from '../hooks/useBuildOn';

function PostCard({ post, currentUser }) {
  const {
    isComposerOpen,
    originalPost,
    openBuildOn,
    closeBuildOn,
    submitBuildOn,
    canBuildOn
  } = useBuildOn(currentUser.id, currentUser.display_name);

  return (
    <div>
      <PostContent post={post} />
      {canBuildOn(post) && (
        <button onClick={() => openBuildOn(post)}>Build On This</button>
      )}
      {isComposerOpen && originalPost?.id === post.id && (
        <BuildOnComposer
          originalPost={originalPost}
          onSubmit={({ content, intent }) => submitBuildOn({ content, intent })}
          onClose={closeBuildOn}
        />
      )}
    </div>
  );
}

Notes

• The new post is inserted with builds_on_post_id set to the original post's ID and quoted_excerpt for any selected text.
• If the audience is 'circle', the post is also linked to the specified circles via the post_circles table.
• A notification of type 'build_on' is sent to the original author (unless the user is building on their own post).
• Build On posts have sharing_allowed: true by default.

---

Last updated: 2026-02-07