Post Card

When to use

Reach for PostCard when you need a social-post surface in any of four shapes: feed (Instagram-post), compact (sidebar widget), list (admin / search row), or detail (full page with embedded comment thread). Composes all five Tier-1 social primitives — expandable-text, media-carousel, engagement-bar, comment-thread, plus video-player transitively — and ships with kasder-style inline engagement panels (likes / comments / share) on by default.

Inline engagement panels (default)

Out of the box, every variant except detail wires kasder-style inline panels:

• Tap heart → toggle like (and auto-open likers panel on a fresh like, controlled by openLikersOnLike).
• Tap like count → open inline likers strip (horizontal swipable avatar list with paginating +N pill).
• Tap comment icon → open inline <CommentThread> with composer; scrollable, height configurable via inlineCommentsMaxHeight (default 24rem).
• Tap share icon → open inline searchable user list (when shareSuggestions provided); local filter or async onShareSearch.

Pass engagementMode="navigate" to deactivate the panels and revert to single-button like / onComment(id) navigation. The detail variant ignores engagementMode — its thread is always embedded.

Footgun: the `post` prop is mount-only

Component captures post as initial state on mount; subsequent prop reference changes are ignored. RealtimeengagementSubscribe + optimistic onLike/onBookmarkmutate the internal mirror. To push external updates, use the imperative handle's reset(next):

const ref = useRef<PostCardHandle>(null);
useEffect(() => {
  ref.current?.reset(externalPost);
}, [externalPost]);

<PostCard ref={ref} variant="feed" post={externalPost} ... />

Basic feed

<PostCard
  variant="feed"
  post={post}
  currentUser={viewer}
  likers={preloadedLikers}              // enables inline likers panel
  commentThread={preloadedComments}     // enables inline comments panel
  shareSuggestions={recentContacts}     // enables inline share menu
  onLike={(id, liked) => api.likePost(id, liked)}
  onBookmark={(id, b) => api.bookmark(id, b)}
  onShareTo={(id, user) => api.shareTo(id, user)}
  onAddComment={(content, parentId) => api.addComment(post.id, { content, parentId })}
  onLikeComment={api.likeComment}
  onLoadMoreLikers={() => api.fetchMoreLikers(post.id)}
  getHref={(p) => `/posts/${p.id}`}    // overlay-link + Copy-link kebab item
/>

Detail with embedded thread + realtime

const engagementSubscribe = useCallback<Subscribe<EngagementDelta>>(
  (h) => channel.on(`post-${post.id}-engagement`, h),
  [post.id, channel],
);
const commentSubscribe = useCallback<Subscribe<CommentDelta>>(
  (h) => channel.on(`post-${post.id}-comments`, h),
  [post.id, channel],
);

<PostCard
  variant="detail"
  post={post}
  currentUser={viewer}
  commentThread={preloadedComments}
  engagementSubscribe={engagementSubscribe}
  commentSubscribe={commentSubscribe}
  onLike={api.likePost}
  onAddComment={(content, parentId) => api.addComment(post.id, { content, parentId })}
  onLikeComment={api.likeComment}
  onDeleteComment={api.deleteComment}
  onLoadMoreComments={(page) => api.fetchComments(post.id, page)}
/>

Navigate mode (no inline panels)

<PostCard
  variant="feed"
  post={post}
  engagementMode="navigate"
  onLike={api.likePost}
  onComment={(id) => router.push(`/posts/${id}#comments`)}
  onShare={(id) => navigator.share?.({ url: `/posts/${id}` })}
/>

Custom engagement actions (extending defaults)

import { defaultPostEngagementActions } from "@/components/post-card";

<PostCard
  variant="feed"
  post={post}
  engagementActions={(p, h, v) => [
    ...defaultPostEngagementActions(p, h, v),
    { kind: "custom", id: "remix", label: "Remix", icon: <Wand2 />, onClick: () => openRemix(p.id) },
  ]}
/>

Custom kebab actions (full takeover)

<PostCard
  variant="list"
  post={post}
  kebabActions={(p) => [
    { label: "Pin", onClick: () => api.pin(p.id) },
    { label: "Take down", destructive: true, onClick: () => api.takeDown(p.id) },
    { label: "Block author", onClick: () => api.block(p.author.id) },
  ]}
/>

kebabActions is full-takeover — it bypasses the role-aware default assembly entirely. For an additive moderator section on top of the default kebab, use moderatorActions below.

v0.3.0 — Moderator section (ILX-3)

Moderation is orthogonal to viewerMode — a moderator is usually a viewer (or sometimes an owner) with extra capability. Opt the viewer in via permissions.canModerate: true (or the universal canPerformAction("moderate", post) predicate) AND supply the menu items via moderatorActions(post). The library renders them as a section between common items (Bookmark / Share / Copy link / Translate) and viewer-destructive items (Mute / Block / Report), with a divider above. Setting kebabActions still wins (full takeover).

<PostCard
  variant="feed"
  post={post}
  currentUser={viewer}
  viewerMode="viewer"
  permissions={{ canModerate: viewer.role === "mod" || viewer.role === "admin" }}
  moderatorActions={(p) => [
    { label: "Feature post", icon: <Star className="h-4 w-4" />, onClick: () => api.feature(p.id) },
    { label: "Lock comments", icon: <Lock className="h-4 w-4" />, onClick: () => api.lockThread(p.id) },
    { label: "Remove post", icon: <Trash2 className="h-4 w-4" />, destructive: true, onClick: () => api.removePost(p.id) },
  ]}
  // viewer-side defaults still resolve:
  onReport={api.report}
  onBlockAuthor={api.block}
  onMuteAuthor={api.mute}
/>

Resolution: moderatorActions runs only when canPerformAction("moderate", post) returns true (wins) OR permissions.canModerate === true. Default for both viewer modes is false — moderators must be opted in explicitly; never auto-derived from viewerMode.

i18n

labels={{
  // header / kebab
  bookmark: "Kaydet", unbookmark: "Kaldır", share: "Paylaş",
  copyLink: "Bağlantıyı kopyala", report: "Şikayet et",
  // inline panels
  likersHeading: "Beğenenler",
  shareHeading: "Şununla paylaş…",
  shareSearchPlaceholder: "Kişi ara…",
  shareEmptyLabel: "Eşleşme yok.",
  hidePanelLabel: "Gizle",
  // forwarded
  engagementLabels: { /* engagement-bar labels */ },
  commentLabels: { /* comment-thread labels */ },
}}

Notes

• engagementMode defaults to "inline" — tap-to-open panels everywhere. Pass "navigate" to deactivate.
• Heart-burst auto-wires when post.media?.length > 0 AND onLike is provided AND variant ∈ {feed, detail}. Opt out via disableHeartBurst.
• getHrefdouble-duty: makes the card clickable via overlay-link in feed / compact / list AND adds a "Copy link" kebab item. Detail variant ignores overlay-link.
• Default kebab is "Bookmark / Share / Copy link / Report" — each item only appears when its handler is wired (or for Copy link, when getHref is provided).
• v0.3.0 — moderatorActions(post) + permissions.canModerate + "moderate" action discriminator. Orthogonal to viewerMode (never auto-derived). The section sits between common items and viewer-destructive items with a divider above. kebabActions full-takeover still wins.
• The split heart-vs-count behavior comes from engagement-bar's like action (onCountClickon the action) — it's the bar feature, not card-specific. Hosts using the bar directly can wire the same split.
• renderHeader, renderContent, renderMedia, renderEngagementBar, renderCommentSection are full-takeover slots at every connective seam.
• List variant's thumbnail stretches to fill the card height edge-to-edge; content area gets its own padding so the seams stay flush.
• Realtime: two separate subscribe props. engagementSubscribe is owned by the card (delta routes to mirror); commentSubscribe forwards directly to the embedded CommentThread in detail variant or to the inline thread when opened.