Skip to content
ilinxa/pro-ui

Post Card

alphav0.8.0

Social post composite in four layouts — text expansion, media carousel, engagement bar, and comment thread wired together.

Category: Data DisplayUpdated: 2026-10-29Created: 2026-05-02Author: ilinxa

Context

Sixth ship in the 8-component social-posts-system arc. Third cross-folder import precedent in pro-ui (after media-carousel → video-player and comment-thread → expandable-text + engagement-bar) — declares all five Tier-1 social-posts siblings as registryDependencies; consumer install auto-pulls the family. Migration origin: kasder kas-social-front-v0 AdvancedPostCard.tsx (167 LOC) + PostEngagementPanel.tsx inline-panel UX. `post` is mount-only (a local mirror) unless `onPostChange` is passed (controlled since 0.6.0: the prop wins every render, like / bookmark / poll vote show as an overlay while their promise is in flight and are reported once accepted, rejections roll back); the engagement bar is controlled by the card; realtime engagementSubscribe deltas are applied (uncontrolled) or reported (controlled) and fire onSubscribeEngagementDelta. Inline panels (engagementMode default 'inline'): tap heart toggles like, tap count opens likers strip; tap comment toggles inline CommentThread (with composer); tap share opens searchable user list. `engagementMode='navigate'` deactivates panels for hosts that prefer page navigation. Heart-burst auto-wires when `post.media?.length > 0` AND (`onLike`, or `reactions.onReact` when `reactions` is set) AND `variant ∈ {feed, detail}` (disableHeartBurst opts out). `getHref` double-duty: overlay-link in non-detail variants + Copy-link kebab item. Detail variant embeds <CommentThread> always (ignores engagementMode) with auto-default + `renderCommentSection` slot for full takeover.

Installation

Initialize shadcn (once per project)Seeds lib/utils.ts and components.json. Skip if you've already used any shadcn component.
pnpm dlx shadcn@latest init
Install the component
pnpm dlx shadcn@latest add @ilinxa/post-card

Add -fixtures for dummy data:

pnpm dlx shadcn@latest add @ilinxa/post-card-fixtures

CLI can't resolve @ilinxa? The namespace is listed in the official shadcn registry directory, so current CLIs need no configuration. If yours can't resolve it (older or pinned versions, self-hosted mirrors), register it manually in components.json:

"registries": {
  "@ilinxa": "https://ui.ilinxa.com/r/{name}.json"
}

Preview

IP

Ines Park

@ines

Studio process this week — three iterations on the same composition. Trying to figure out which one carries the message clearest.

Demo source

demo.tsxtsx
"use client"; import { useMemo, useRef, useState } from "react";import { Lock, Star, Trash2, Wand2 } from "lucide-react";import { Tabs, TabsContent, TabsTrigger } from "@/components/ui/tabs";import { SwipeTabsList } from "@/components/site/swipe-tabs-list";import { PostCard } from "./post-card";import { defaultPostEngagementActions } from "./lib/defaults";import {  DUMMY_CURSOR_COMMENTS,  DUMMY_DETAIL_THREAD,  DUMMY_NOW,  DUMMY_FEATURED_POST,  DUMMY_LIKERS,  DUMMY_LINK_PREVIEW_POST,  DUMMY_LONG_TEXT_POST,  DUMMY_MIXED_MEDIA_POST,  DUMMY_MULTI_IMAGE_POST,  DUMMY_PINNED_POST,  DUMMY_POLL_CLOSED_POST,  DUMMY_POLL_POST,  DUMMY_POLL_VOTED_POST,  DUMMY_REACTION_KINDS,  DUMMY_REPLY_POST,  DUMMY_REPOST_POST,  DUMMY_RICH_POST,  DUMMY_RTL_POST,  DUMMY_RTL_THREAD,  DUMMY_SENSITIVE_POST,  DUMMY_SINGLE_IMAGE_POST,  DUMMY_TEXT_ONLY_POST,  DUMMY_VIDEO_POST,  DUMMY_VIEWER,  createDummyCommentSubscribe,  createDummyEngagementSubscribe,  generateMoreLikers,  loadDummyCommentPage,} from "./dummy-data";import type { Post, PostCardLabels, PostChange, PostMediaProps } from "./types";import type { CommentMenuItem } from "@/registry/components/data/comment-thread";import type { EngagementAction } from "@/registry/components/data/engagement-bar"; function log(tag: string, payload: unknown) {  if (typeof console !== "undefined") {    console.log(`[demo:post-card:${tag}]`, payload);  }} // ─── Complete locale label sets (the Turkish and Arabic tabs show no English) ─────────── const TR_LABELS: PostCardLabels = {  kebabAriaLabel: "Gönderi işlemleri",  verifiedBadgeLabel: "Doğrulanmış hesap",  pinnedBadgeLabel: "Sabitlendi",  editedSuffix: "(düzenlendi)",  bookmark: "Kaydet",  unbookmark: "Kaydı kaldır",  share: "Paylaş",  copyLink: "Bağlantıyı kopyala",  report: "Şikayet et",  commentsHeading: "Yorumlar",  likersHeading: "Beğenenler",  likersMoreLabel: (_n, f) => `${f} kişi daha`,  hidePanelLabel: "Gizle",  shareHeading: "Şununla paylaş…",  shareSearchPlaceholder: "Kişi ara…",  shareEmptyLabel: "Eşleşme yok.",  openRepost: (name) => `${name} gönderisini aç`,  visibilityPublic: "Herkese açık",  visibilityFollowers: "Takipçiler",  visibilityFriends: "Arkadaşlar",  visibilityCircle: "Yakın çevre",  visibilityOnlyMe: "Yalnızca ben",  visibilityPrivate: "Gizli",  visibilityCustom: "Özel",  pollHeading: "Anket",  pollTotalVotesLabel: (_n, f) => `${f} oy`,  pollClosesAtLabel: (t) => `Bitiş: ${t}`,  pollClosedLabel: "Anket kapandı",  listLikes: (_n, f) => `${f} beğeni`,  listComments: (_n, f) => `${f} yorum`,  listShares: (_n, f) => `${f} paylaşım`,  textLabels: { showMore: "Devamını gör", showLess: "Daha az göster" },  engagementLabels: {    like: "Beğen",    unlike: "Beğenmekten vazgeç",    openLikersPanel: "Beğenenleri göster",    comment: "Yorum yap",    share: "Paylaş",    bookmark: "Kaydet",    unbookmark: "Kaydı kaldır",    viewCount: "Görüntülenme",  },  likersLabels: { loadMore: "Daha fazla" },  shareLabels: { searchLabel: "Kişi ara" },  commentLabels: {    composerPlaceholder: "Yorum yaz…",    composerSend: "Gönder",    composerCancel: "Vazgeç",    reply: "Yanıtla",    like: "Beğen",    unlike: "Beğenmekten vazgeç",    delete: "Sil",    report: "Şikayet et",    loadMore: "Daha eski yorumları yükle",    emptyState: "Henüz yorum yok.",    kebabAriaLabel: (name) => `${name} yorumu için işlemler`,    replyTo: (name) => `${name} adlı kişiye yanıt`,    viewReplies: (n) => `${n} yanıtı gör`,  },}; const TR_MEDIA_PROPS: PostMediaProps = {  labels: {    carouselLabel: "Medya galerisi",    previousSlide: "Önceki",    nextSlide: "Sonraki",    goToSlide: (position) => `${position}. görsele git`,    slideAriaLabel: (position, total) => `${position} / ${total}`,    carouselRoleDescription: "galeri",    slideRoleDescription: "görsel",  },}; const AR_LABELS: PostCardLabels = {  kebabAriaLabel: "إجراءات المنشور",  verifiedBadgeLabel: "حساب موثّق",  pinnedBadgeLabel: "مثبّت",  editedSuffix: "(معدّل)",  bookmark: "حفظ",  unbookmark: "إزالة الحفظ",  share: "مشاركة",  copyLink: "نسخ الرابط",  report: "إبلاغ",  commentsHeading: "التعليقات",  likersHeading: "المعجبون",  hidePanelLabel: "إخفاء",  openRepost: (name) => `فتح منشور ${name}`,  visibilityPublic: "عام",  visibilityFollowers: "المتابعون",  visibilityFriends: "الأصدقاء",  visibilityCircle: "الدائرة المقرّبة",  visibilityOnlyMe: "أنا فقط",  visibilityPrivate: "خاص",  visibilityCustom: "مخصّص",  pollHeading: "استطلاع",  pollTotalVotesLabel: (_n, f) => `${f} صوت`,  pollClosesAtLabel: (t) => `ينتهي ${t}`,  pollClosedLabel: "انتهى الاستطلاع",  textLabels: { showMore: "عرض المزيد", showLess: "عرض أقل" },  engagementLabels: {    like: "أعجبني",    unlike: "إلغاء الإعجاب",    openLikersPanel: "عرض المعجبين",    comment: "تعليق",    share: "مشاركة",    bookmark: "حفظ",    unbookmark: "إزالة الحفظ",    viewCount: "المشاهدات",  },  commentLabels: {    composerPlaceholder: "اكتب تعليقاً…",    composerSend: "إرسال",    composerCancel: "إلغاء",    reply: "ردّ",    like: "أعجبني",    unlike: "إلغاء الإعجاب",    delete: "حذف",    report: "إبلاغ",    loadMore: "تحميل تعليقات أقدم",    emptyState: "لا توجد تعليقات بعد.",    kebabAriaLabel: (name) => `إجراءات تعليق ${name}`,    replyTo: (name) => `الرد على ${name}`,    viewReplies: (n) => `عرض ${n} ردود`,  },}; const AR_MEDIA_PROPS: PostMediaProps = {  labels: {    carouselLabel: "معرض الوسائط",    previousSlide: "السابق",    nextSlide: "التالي",    goToSlide: (position) => `الانتقال إلى الشريحة ${position}`,    slideAriaLabel: (position, total) => `${position} من ${total}`,    carouselRoleDescription: "معرض",    slideRoleDescription: "شريحة",  },}; function FeedTab() {  const likersPageRef = useRef(1);  return (    <div className="mx-auto max-w-xl">      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_MULTI_IMAGE_POST}        currentUser={DUMMY_VIEWER}        likers={DUMMY_LIKERS}        commentThread={DUMMY_DETAIL_THREAD}        shareSuggestions={DUMMY_LIKERS}        onShareTo={(id, user) => log("share-to", { id, user })}        onLike={(id, liked) => log("like", { id, liked })}        onBookmark={(id, bookmarked) => log("bookmark", { id, bookmarked })}        onReport={(id) => log("report", id)}        onAddComment={async (content, parentId) => {          log("add-comment", { content, parentId });        }}        onLikeComment={(id, liked) => log("like-comment", { id, liked })}        onDeleteComment={(id) => log("delete-comment", id)}        onLoadMoreLikers={async () => {          await new Promise((r) => setTimeout(r, 300));          likersPageRef.current += 1;          return generateMoreLikers(likersPageRef.current);        }}        getHref={(p) => `/posts/${p.id}`}      />    </div>  );} function VideoTab() {  return (    <div className="mx-auto max-w-xl">      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_VIDEO_POST}        currentUser={DUMMY_VIEWER}        likers={DUMMY_LIKERS}        commentThread={DUMMY_DETAIL_THREAD}        shareSuggestions={DUMMY_LIKERS}        onShareTo={(id, user) => log("share-to", { id, user })}        onLike={(id, liked) => log("like", { id, liked })}        onBookmark={(id, bookmarked) => log("bookmark", { id, bookmarked })}      />    </div>  );} function CompactTab() {  return (    <div className="mx-auto max-w-sm">      <PostCard        now={DUMMY_NOW}        variant="compact"        post={DUMMY_SINGLE_IMAGE_POST}        onLike={(id, liked) => log("like", { id, liked })}        onComment={(id) => log("comment", id)}        getHref={(p) => `/posts/${p.id}`}      />    </div>  );} function ListTab() {  return (    <div className="flex flex-col gap-3">      <PostCard        now={DUMMY_NOW}        variant="list"        post={DUMMY_FEATURED_POST}        kebabActions={(p) => [          { label: "Pin to top", onClick: () => log("pin", p.id) },          {            label: "Take down",            destructive: true,            onClick: () => log("takedown", p.id),          },        ]}        getHref={(p) => `/posts/${p.id}`}      />      <PostCard        now={DUMMY_NOW}        variant="list"        post={DUMMY_TEXT_ONLY_POST}        kebabActions={(p) => [          { label: "Pin to top", onClick: () => log("pin", p.id) },          { label: "Block author", onClick: () => log("block", p.author.id) },        ]}      />    </div>  );} function DetailTab() {  // v0.2.0 — Detail tab demonstrates the full owner-side surface via  // viewerMode="owner" + all 8 mutation handlers wired. The kebab will  // render Edit / Pin / Change visibility / Mark sensitive / See analytics /  // Bookmark / Share / Copy link / [sep] / Delete.  return (    <div className="mx-auto max-w-2xl">      <PostCard        now={DUMMY_NOW}        variant="detail"        post={DUMMY_PINNED_POST}        currentUser={DUMMY_VIEWER}        commentThread={DUMMY_DETAIL_THREAD}        viewerMode="owner"        onLike={(id, liked) => log("like", { id, liked })}        onShare={(id) => log("share", id)}        onBookmark={(id, bookmarked) => log("bookmark", { id, bookmarked })}        onEdit={(id) => log("edit", id)}        onDelete={(id) => log("delete", id)}        onPin={(id, next) => log("pin", { id, next })}        onChangeVisibility={(id, current) =>          log("change-visibility", { id, current })        }        onMarkSensitive={(id, next) => log("mark-sensitive", { id, next })}        onSeeAnalytics={(id) => log("see-analytics", id)}        onAddComment={async (content, parentId) => {          log("add-comment", { content, parentId });        }}        onLikeComment={(id, liked) =>          log("like-comment", { id, liked })        }        onDeleteComment={(id) => log("delete-comment", id)}        onReportComment={(id) => log("report-comment", id)}        getHref={(p) => `/posts/${p.id}`}      />    </div>  );} // ─── v0.2.0 tabs ────────────────────────────────────────────────────────── function RepostTab() {  // Showcases the nested repost mini-card (Q-D3 / Q-P30). Outer post is a  // public viewer-mode repost; nested mini-card is the original FEATURED post  // with engagementActions={()=>[]} suppressing the inner bar.  return (    <div className="mx-auto max-w-xl">      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_REPOST_POST}        currentUser={DUMMY_VIEWER}        viewerMode="viewer"        onLike={(id, liked) => log("like", { id, liked })}        onShare={(id) => log("share", id)}        onBookmark={(id, bookmarked) => log("bookmark", { id, bookmarked })}        onRepostOfClick={(orig) => log("repost-of-click", orig.id)}        getHref={(p) => `/posts/${p.id}`}      />    </div>  );} function PollTab() {  // Three cards stacked: active poll (vote view) → voted poll (results view  // with viewer choice highlighted) → closed poll (results + closed label).  return (    <div className="mx-auto flex max-w-xl flex-col gap-4">      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_POLL_POST}        currentUser={DUMMY_VIEWER}        viewerMode="viewer"        onVotePoll={(id, optionId) => log("vote-poll", { id, optionId })}        onLike={(id, liked) => log("like", { id, liked })}      />      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_POLL_VOTED_POST}        currentUser={DUMMY_VIEWER}        viewerMode="viewer"        onLike={(id, liked) => log("like", { id, liked })}      />      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_POLL_CLOSED_POST}        currentUser={DUMMY_VIEWER}        viewerMode="viewer"        onLike={(id, liked) => log("like", { id, liked })}      />    </div>  );} function SensitiveTab() {  // Two cards: sensitive gate (viewer taps Show) + link-preview card + rich  // header (visibility / edited / location / mentions / tags).  return (    <div className="mx-auto flex max-w-xl flex-col gap-4">      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_SENSITIVE_POST}        currentUser={DUMMY_VIEWER}        viewerMode="viewer"        onLike={(id, liked) => log("like", { id, liked })}        onRevealSensitive={(id) => log("reveal-sensitive", id)}      />      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_LINK_PREVIEW_POST}        currentUser={DUMMY_VIEWER}        viewerMode="viewer"        onLike={(id, liked) => log("like", { id, liked })}        onLinkPreviewClick={(url) => log("link-preview-click", url)}      />      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_RICH_POST}        currentUser={DUMMY_VIEWER}        viewerMode="viewer"        onLike={(id, liked) => log("like", { id, liked })}        onLocationClick={(loc) => log("location-click", loc)}        onMentionClick={(mid) => log("mention-click", mid)}        onTagClick={(tag) => log("tag-click", tag)}      />      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_REPLY_POST}        currentUser={DUMMY_VIEWER}        viewerMode="viewer"        onLike={(id, liked) => log("like", { id, liked })}        onMentionClick={(mid) => log("reply-mention-click", mid)}      />    </div>  );} function TextOnlyTab() {  return (    <div className="mx-auto max-w-xl">      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_LONG_TEXT_POST}        currentUser={DUMMY_VIEWER}        onLike={(id, liked) => log("like", { id, liked })}        onComment={(id) => log("comment", id)}        onShare={(id) => log("share", id)}        onBookmark={(id, bookmarked) => log("bookmark", { id, bookmarked })}      />    </div>  );} function RealtimeTab() {  const engagementSubscribe = useMemo(    () => createDummyEngagementSubscribe(),    [],  );  const commentSubscribe = useMemo(() => createDummyCommentSubscribe(), []);  return (    <div className="mx-auto max-w-xl">      <PostCard        now={DUMMY_NOW}        variant="detail"        post={DUMMY_VIDEO_POST}        currentUser={DUMMY_VIEWER}        commentThread={DUMMY_DETAIL_THREAD}        engagementSubscribe={engagementSubscribe}        commentSubscribe={commentSubscribe}        onSubscribeEngagementDelta={(d) => log("engagement-delta", d)}        onSubscribeCommentDelta={(d) => log("comment-delta", d)}        onLike={(id, liked) => log("like", { id, liked })}        onAddComment={async (content) => {          log("add-comment", content);        }}      />    </div>  );} function InlineEngagementTab() {  // TR-localized variant — same panels, kasder labels.  const likersPageRef = useRef(1);  return (    <div className="mx-auto max-w-xl">      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_MULTI_IMAGE_POST}        currentUser={DUMMY_VIEWER}        likers={DUMMY_LIKERS}        commentThread={DUMMY_DETAIL_THREAD}        shareSuggestions={DUMMY_LIKERS}        onShareTo={(id, user) => log("share-to", { id, user })}        onLoadMoreLikers={async () => {          await new Promise((r) => setTimeout(r, 300));          likersPageRef.current += 1;          return generateMoreLikers(likersPageRef.current);        }}        onLike={(id, liked) => log("like", { id, liked })}        onBookmark={(id, b) => log("bookmark", { id, b })}        onAddComment={async (content, parentId) => {          log("add-comment", { content, parentId });        }}        onLikeComment={(id, liked) => log("like-comment", { id, liked })}        onDeleteComment={(id) => log("delete-comment", id)}        onReportComment={(id) => log("report-comment", id)}        onLoadMoreComments={async () => {          await new Promise((r) => setTimeout(r, 300));          return [];        }}        locale="tr"        mediaProps={TR_MEDIA_PROPS}        labels={TR_LABELS}      />    </div>  );} // ─── 0.6.0 tabs ─────────────────────────────────────────────────────────── const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); function ControlledTab() {  // The host owns the post. `onPostChange` fires once a request is accepted; the card shows the  // like at once while the promise is in flight, and a rejection rolls it back without reporting.  const [post, setPost] = useState<Post>(DUMMY_MULTI_IMAGE_POST);  const [failNext, setFailNext] = useState(false);  const [lastChange, setLastChange] = useState<PostChange | null>(null);  return (    <div className="mx-auto flex max-w-xl flex-col gap-3">      <label className="flex items-center gap-2 text-sm">        <input          type="checkbox"          checked={failNext}          onChange={(e) => setFailNext(e.target.checked)}        />        Reject the next like / bookmark (rolls back, nothing is reported)      </label>      <PostCard        now={DUMMY_NOW}        variant="feed"        post={post}        currentUser={DUMMY_VIEWER}        engagementMode="navigate"        onPostChange={(next, change) => {          setPost(next);          setLastChange(change);        }}        onLike={async (id, liked) => {          log("like", { id, liked });          await sleep(700);          if (failNext) throw new Error("server said no");        }}        onBookmark={async (id, bookmarked) => {          log("bookmark", { id, bookmarked });          await sleep(700);          if (failNext) throw new Error("server said no");        }}      />      <pre className="overflow-x-auto rounded-md border border-border bg-muted p-3 font-mono text-xs">        {`post prop   likes ${post.likes} · liked ${String(post.isLiked ?? false)} · bookmarked ${String(post.isBookmarked ?? false)}last change ${lastChange ? JSON.stringify(lastChange) : "none yet"}`}      </pre>    </div>  );} function ReactionsTab() {  // `reactions` takes the like's place. Double-tap on the photos applies `defaultKind` when you  // have no reaction yet; with one set it only plays the burst.  const [viewerReaction, setViewerReaction] = useState<string | null>(null);  const [counts, setCounts] = useState<Record<string, number>>(() =>    Object.fromEntries(DUMMY_REACTION_KINDS.map((k) => [k.key, k.count ?? 0])),  );  const totalCount = Object.values(counts).reduce((sum, n) => sum + n, 0);  return (    <div className="mx-auto max-w-xl">      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_MULTI_IMAGE_POST}        currentUser={DUMMY_VIEWER}        engagementMode="navigate"        reactions={{          kinds: DUMMY_REACTION_KINDS,          counts,          totalCount,          viewerReaction,          defaultKind: "love",          onReact: async (id, kind) => {            log("react", { id, kind });            await sleep(400);            setCounts((c) => {              const next = { ...c };              if (viewerReaction) next[viewerReaction] = (next[viewerReaction] ?? 1) - 1;              if (kind) next[kind] = (next[kind] ?? 0) + 1;              return next;            });            setViewerReaction(kind);          },        }}      />    </div>  );} function HeaderSlotsTab() {  // Author link, subtitle, notice, an extra kebab item, a hidden item and a disabled one.  return (    <div className="mx-auto max-w-xl">      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_FEATURED_POST}        currentUser={DUMMY_VIEWER}        viewerMode="owner"        engagementMode="navigate"        permissions={{ disabled: { delete: true } }}        getHref={(p) => `/posts/${p.id}`}        getAuthorHref={(a) => `/people/${a.username ?? a.id}`}        subtitle={() => "Community manager"}        noticeSlot={() => (          <p            role="status"            className="rounded-md border border-border bg-muted px-3 py-2 text-xs text-muted-foreground"          >            This post is under review.          </p>        )}        extraKebabActions={(p): CommentMenuItem[] => [          {            label: "Boost post",            icon: <Star className="h-4 w-4" />,            separatorBefore: true,            onClick: () => log("boost", p.id),          },          { label: "Internal note", hidden: true },        ]}        onEdit={(id) => log("edit", id)}        onDelete={(id) => log("delete", id)}        onBookmark={(id, bookmarked) => log("bookmark", { id, bookmarked })}        labels={{ kebabAriaLabel: "More actions" }}      />    </div>  );} function LocaleTab() {  // One `locale` for the card and everything it composes; label functions carry the plurals.  return (    <div className="mx-auto flex max-w-xl flex-col gap-4">      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_POLL_POST}        currentUser={DUMMY_VIEWER}        engagementMode="navigate"        locale="tr"        onVotePoll={async (id, optionId) => {          log("vote-poll", { id, optionId });          await sleep(500);        }}        mediaProps={TR_MEDIA_PROPS}        labels={TR_LABELS}      />      <PostCard        now={DUMMY_NOW}        variant="list"        post={{ ...DUMMY_FEATURED_POST, likes: 12400 }}        locale="tr"        mediaProps={TR_MEDIA_PROPS}        labels={TR_LABELS}      />    </div>  );} function ThreadTab() {  // `commentThreadProps` hands cursor paging (and anything else the thread takes) to the thread.  return (    <div className="mx-auto max-w-2xl">      <PostCard        now={DUMMY_NOW}        variant="detail"        post={DUMMY_PINNED_POST}        currentUser={DUMMY_VIEWER}        commentThread={DUMMY_CURSOR_COMMENTS.slice(0, 3)}        commentPageSize={3}        commentThreadProps={{          onLoadMoreCursor: loadDummyCommentPage,          onError: (error, context) => log("thread-error", { error, context }),        }}        onAddComment={async (content, parentId) => {          log("add-comment", { content, parentId });        }}        onLikeComment={(id, liked) => log("like-comment", { id, liked })}      />    </div>  );} function RtlTab() {  // Direction comes from the surrounding element; `locale` picks Arabic digits and dates.  return (    <div dir="rtl" lang="ar" className="mx-auto flex max-w-xl flex-col gap-4">      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_RTL_POST}        currentUser={{ id: "viewer-ar", name: "نور الهدى" }}        engagementMode="navigate"        locale="ar"        getAuthorHref={(a) => `/people/${a.username}`}        onLike={(id, liked) => log("like", { id, liked })}        onVotePoll={(id, optionId) => log("vote-poll", { id, optionId })}        mediaProps={AR_MEDIA_PROPS}        labels={AR_LABELS}      />      <PostCard        now={DUMMY_NOW}        variant="detail"        post={{ ...DUMMY_RTL_POST, id: "post-rtl-detail", poll: undefined }}        currentUser={{ id: "viewer-ar", name: "نور الهدى" }}        commentThread={DUMMY_RTL_THREAD}        locale="ar"        onAddComment={async (content) => {          log("add-comment", content);        }}        mediaProps={AR_MEDIA_PROPS}        labels={AR_LABELS}      />    </div>  );} function ModeratorTab() {  // v0.3.0 ILX-3 — viewer-mode card with moderator capability opted in via  // `permissions={{ canModerate: true }}`. `moderatorActions(post)` supplies  // the items; the library wraps them in a section between common items and  // viewer-destructive items, with a divider above. `kebabActions` is left  // unset so the role-aware default kebab assembly runs.  return (    <div className="mx-auto max-w-xl">      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_FEATURED_POST}        currentUser={DUMMY_VIEWER}        viewerMode="viewer"        permissions={{ canModerate: true }}        moderatorActions={(p): CommentMenuItem[] => [          {            label: "Feature post",            icon: <Star className="h-4 w-4" />,            onClick: () => log("mod:feature", p.id),          },          {            label: "Lock comments",            icon: <Lock className="h-4 w-4" />,            onClick: () => log("mod:lock", p.id),          },          {            label: "Remove post",            icon: <Trash2 className="h-4 w-4" />,            destructive: true,            onClick: () => log("mod:remove", p.id),          },        ]}        onLike={(id, liked) => log("like", { id, liked })}        onShare={(id) => log("share", id)}        onBookmark={(id, bookmarked) => log("bookmark", { id, bookmarked })}        onReport={(id) => log("report", id)}        onBlockAuthor={(authorId) => log("block-author", authorId)}        onMuteAuthor={(authorId) => log("mute-author", authorId)}        getHref={(p) => `/posts/${p.id}`}      />    </div>  );} function CustomActionsTab() {  const [extras] = useState({ remixActive: false });  return (    <div className="mx-auto max-w-xl">      <PostCard        now={DUMMY_NOW}        variant="feed"        post={DUMMY_MIXED_MEDIA_POST}        currentUser={DUMMY_VIEWER}        onLike={(id, liked) => log("like", { id, liked })}        onComment={(id) => log("comment", id)}        onShare={(id) => log("share", id)}        onBookmark={(id, bookmarked) => log("bookmark", { id, bookmarked })}        engagementActions={(p, h, v): EngagementAction[] => [          ...defaultPostEngagementActions(p, h, v),          {            kind: "custom",            id: "remix",            label: "Remix",            icon: <Wand2 className="h-4 w-4" />,            active: extras.remixActive,            onClick: () => log("remix", p.id),          },        ]}        kebabActions={(p): CommentMenuItem[] => [          { label: "Pin", onClick: () => log("pin", p.id) },          { label: "Translate", onClick: () => log("translate", p.id) },          {            label: "Block author",            onClick: () => log("block", p.author.id),          },          {            label: "Report",            destructive: true,            onClick: () => log("report", p.id),          },        ]}      />    </div>  );} export default function PostCardDemo() {  return (    <Tabs defaultValue="feed" className="w-full">      <SwipeTabsList>        <TabsTrigger value="feed">Feed</TabsTrigger>        <TabsTrigger value="compact">Compact</TabsTrigger>        <TabsTrigger value="list">List</TabsTrigger>        <TabsTrigger value="detail">Detail</TabsTrigger>        <TabsTrigger value="text">Text-only</TabsTrigger>        <TabsTrigger value="video">Video</TabsTrigger>        <TabsTrigger value="realtime">Realtime</TabsTrigger>        <TabsTrigger value="inline">Inline TR</TabsTrigger>        <TabsTrigger value="controlled">Controlled</TabsTrigger>        <TabsTrigger value="reactions">Reactions</TabsTrigger>        <TabsTrigger value="header">Header</TabsTrigger>        <TabsTrigger value="locale">Locale TR</TabsTrigger>        <TabsTrigger value="thread">Thread</TabsTrigger>        <TabsTrigger value="rtl">RTL</TabsTrigger>        <TabsTrigger value="custom">Custom</TabsTrigger>        <TabsTrigger value="moderator">Moderator</TabsTrigger>        <TabsTrigger value="repost">Repost</TabsTrigger>        <TabsTrigger value="poll">Poll</TabsTrigger>        <TabsTrigger value="sensitive">Sensitive</TabsTrigger>      </SwipeTabsList>      <TabsContent value="feed" className="mt-4">        <FeedTab />      </TabsContent>      <TabsContent value="compact" className="mt-4">        <CompactTab />      </TabsContent>      <TabsContent value="list" className="mt-4">        <ListTab />      </TabsContent>      <TabsContent value="detail" className="mt-4">        <DetailTab />      </TabsContent>      <TabsContent value="text" className="mt-4">        <TextOnlyTab />      </TabsContent>      <TabsContent value="video" className="mt-4">        <VideoTab />      </TabsContent>      <TabsContent value="realtime" className="mt-4">        <RealtimeTab />      </TabsContent>      <TabsContent value="inline" className="mt-4">        <InlineEngagementTab />      </TabsContent>      <TabsContent value="controlled" className="mt-4">        <ControlledTab />      </TabsContent>      <TabsContent value="reactions" className="mt-4">        <ReactionsTab />      </TabsContent>      <TabsContent value="header" className="mt-4">        <HeaderSlotsTab />      </TabsContent>      <TabsContent value="locale" className="mt-4">        <LocaleTab />      </TabsContent>      <TabsContent value="thread" className="mt-4">        <ThreadTab />      </TabsContent>      <TabsContent value="rtl" className="mt-4">        <RtlTab />      </TabsContent>      <TabsContent value="custom" className="mt-4">        <CustomActionsTab />      </TabsContent>      <TabsContent value="moderator" className="mt-4">        <ModeratorTab />      </TabsContent>      <TabsContent value="repost" className="mt-4">        <RepostTab />      </TabsContent>      <TabsContent value="poll" className="mt-4">        <PollTab />      </TabsContent>      <TabsContent value="sensitive" className="mt-4">        <SensitiveTab />      </TabsContent>    </Tabs>  );} 

Usage

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.

`post`: controlled, or read once at mount

Without onPostChange the card reads post once, at mount, and keeps a local mirror: likes, bookmarks, poll votes and realtime engagementSubscribedeltas change the mirror. A handler that returns a promise makes the change optimistic — a rejection rolls it back (only the latest request per action decides). To push an external post in, use the handle's reset(next).

With onPostChange the post is controlled: postwins on every render. A like, bookmark or poll vote shows over it while the handler's promise is in flight (turn that off with optimistic={false}); once the promise resolves — at once for a handler that returns nothing, and for a realtime delta — the card calls onPostChange(next, change). It never applies the change itself; a rejection drops the overlay and reports nothing. change is { kind: "like" | "bookmark" | "poll-vote" | "delta", … }. reset(next) also works here: it drops in-flight changes and the sensitive reveal. getCurrentPost() returns the post as shown.

const [post, setPost] = useState(initialPost);

<PostCard
  variant="feed"
  post={post}
  onPostChange={(next, change) => setPost(next)}    // controlled
  onLike={(id, liked) => api.like(id, liked)}        // return the promise: rolled back on reject
  onBookmark={(id, b) => api.bookmark(id, b)}
  onVotePoll={(id, optionId) => api.vote(id, optionId)}
/>

likers goes straight to the likers strip: it shows the prop on every render plus the pages it loaded through onLoadMoreLikers.

Reactions

Pass reactions and the default actions show a reaction picker in place of the like. counts merge into the kinds, totalCount / viewerReaction / clearOnTap pass through, and a pick calls onReact(post.id, kind | null) (return a promise to roll back on reject). Pass viewerReaction (a key or null) to control it. Double-tap on the media applies defaultKind (default: the first kind) when the viewer has no reaction yet, and plays the heart burst once; with a reaction set it only bursts — it never clears one. The burst is wired when onLike or reactions.onReact is set. Without reactions the like path is unchanged.

<PostCard
  variant="feed"
  post={post}
  reactions={{
    kinds: [{ key: "like", icon: "👍", label: "Like" }, { key: "love", icon: "❤️", label: "Love" }],
    counts: { like: 212, love: 131 },
    totalCount: 343,
    viewerReaction,                       // string | null: controlled
    defaultKind: "love",                  // what double-tap applies
    onReact: (id, kind) => api.react(id, kind),
  }}
/>

Header

  • getAuthorHref(author, post) — the avatar and the name become links rendered with linkComponent (default a), stacked above the card's overlay link. Only the name link is focusable; the avatar link is aria-hidden with tabIndex=-1.
  • subtitle (a node or (post) => node) — a line under the name. noticeSlot(post) — a notice above the content (every variant that renders content); return null for none.
  • labels.kebabAriaLabelnames the actions menu (default "Post actions"). renderHeader(post, { currentUser, kebab }) — kebab is the built actions menu (or nullwhen it has no visible items), so a custom header keeps it.
  • extraKebabActions(post) — items appended after the default ones (after the destructive group; not gated by canModerate); ignored when kebabActions takes over. A menu item with hidden: true is left out, and a menu with only hidden items is not rendered.
  • permissions.disabled — { delete: true } keeps the item visible but disabled (legacy handler-driven and role-aware modes). It never allows an action the matrix denies; a permissions object that carries only disabled keeps the legacy items.
<PostCard
  variant="feed"
  post={post}
  viewerMode="owner"
  permissions={{ disabled: { delete: true } }}
  getAuthorHref={(a) => `/people/${a.username}`}
  subtitle="Community manager"
  noticeSlot={(p) => (underReview.has(p.id) ? <p role="status">Under review</p> : null)}
  extraKebabActions={(p) => [{ label: "Boost post", onClick: () => api.boost(p.id) }]}
  renderHeader={(p, { kebab }) => <MyHeader post={p}>{kebab}</MyHeader>}
/>

Locale, time zone and the clock

locale (default "en") reaches the carousel, the engagement bar, the likers strip, the share menu and the comment thread; counts use Intl.NumberFormat(locale, { notation: "compact" }) unless you pass formatCount. Relative times use English "Just now" / "5m" / "2h" for "en" (a timeZone only moves the absolute dates), Intl.RelativeTimeFormat for any other locale, and a spelled-out date after five weeks; formatRelativeTime replaces the formatter (the old labels.formatRelativeTimeis still honoured when the prop is not set). The edited timestamp's tooltip follows locale and timeZone.

The card never reads the clock while rendering. Pass nowfor a fixed "now" (tests, server rendering); without it the server render and the first client render print no relative text (an empty <time>), and the clock is read right after mount and every minute. A poll's closed check and countdown use the same now (before it is known the poll counts as open, with no countdown). Direction comes from the surrounding element: wrap the card in <div dir="rtl" lang="ar">.

Forwarding to the parts

  • mediaProps — aspect, minRatio, maxRatio, loop, showCounter, onMediaError, labels… spread onto every carousel the card renders (items, variant and the double-tap stay the card's).
  • engagementBarProps — formatCount, optimistic, likersPreview, reactionsPreview, trailing, onReactionPickerOpenChange, className, actionClassName — spread onto the built-in bar.
  • commentThreadProps — everything else the thread takes (cursor paging onLoadMoreCursor, onLoadReplies, onCommentsChange, onEditComment, moderation, extraActions, reactions…). The card's own comment props (onAddComment, commentActions, commentPageSize…) win when defined; the card's locale / timeZone / now are the default; labels.commentLabels is laid over commentThreadProps.labels. The inline panel and the detail variant share one props object and one stable comments array (an empty one when you pass none).
  • Nested labels: labels.engagementLabels, commentLabels, likersLabels, shareLabels, textLabelspass through to the bar, the thread, the likers strip, the share menu and the body's "Show more" toggle. The flat keys (likersHeading, hidePanelLabel, shareHeading…) still work; the nested ones win.

Breaking in 0.6.0: label functions

Labels that carry a value are functions now; no placeholder is filled by .replace. formatted is the count in locale.

// before (0.5.x)                                  after (0.6.0)
likersMoreLabel: "+{count} more"                   likersMoreLabel: (count, formatted) => `+${formatted} more`
pollTotalVotesLabel: "{count} votes"               pollTotalVotesLabel: (count, formatted) => `${formatted} ${count === 1 ? "vote" : "votes"}`
pollClosesAtLabel: "Closes {time}"                 pollClosesAtLabel: (time) => `Closes ${time}`
// list variant meta ("12 likes · 3 comments · 2 shares") is new:
listLikes / listComments / listShares: (count, formatted) => string
// new: kebabAriaLabel (string)

Visible English change: the list meta counts and the poll total are now compact-formatted in locale (or by formatCount): 8,700 likes reads "8.7K likes", where 0.5.x printed the raw number. A single vote still reads "1 vote". Pass formatCount={(n) => String(n)} to keep plain numbers. Poll percentages follow localetoo ("42%" in English, "%42" in Turkish).

A value that is not a function for one of these keys is ignored (the default stays) and a development build logs one warning per key. defaultPostCardLabels and the ResolvedPostCardLabels type are exported; DEFAULT_POST_CARD_LABELS is a deprecated alias.

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

<PostCard
  locale="tr"
  labels={{
    // header / kebab
    bookmark: "Kaydet", unbookmark: "Kaldır", share: "Paylaş",
    copyLink: "Bağlantıyı kopyala", report: "Şikayet et",
    kebabAriaLabel: "Gönderi işlemleri",
    // inline panels
    likersHeading: "Beğenenler",
    likersMoreLabel: (count, formatted) => `${formatted} kişi daha`,
    shareHeading: "Şununla paylaş…",
    shareSearchPlaceholder: "Kişi ara…",
    shareEmptyLabel: "Eşleşme yok.",
    hidePanelLabel: "Gizle",
    // poll + list meta
    pollTotalVotesLabel: (count, formatted) => `${formatted} oy`,
    pollClosesAtLabel: (time) => `Bitiş: ${time}`,
    listLikes: (count, formatted) => `${formatted} beğeni`,
    // forwarded
    engagementLabels: { /* engagement-bar labels */ },
    commentLabels: { /* comment-thread labels */ },
    textLabels: { showMore: "Devamını gör", showLess: "Daha az" },
    likersLabels: { /* wins over the flat likers keys */ },
    shareLabels: { /* wins over the flat share keys */ },
  }}
/>

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 (or reactions.onReact) 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.

Features

  • v0.8.0 — follows media-carousel 0.4.0: `PostMediaItem.caption` (shown under its slide), `mediaProps.aspect` takes `"W:H"` (`"4:5"`, `"1.91:1"`), `mediaProps.captionLines` / `captionClassName`, `mediaProps.labels.captionShowMore` / `captionShowLess` / `video` (the carousel videos' labels; `PostMediaVideoLabels`)
  • v0.7.0 — `likersStripProps` (profile links, full names, badges, touch size) and `shareMenuProps` (a header row, per-person send state, touch size) forward to the inline panels; with send state the share panel stays open after a pick; `engagementBarProps` forwards `size` and `hideZeroCounts`; `reactions` takes `tapAction` / `primaryKey` / `hoverOpenDelay` for one-tap reactions
  • v0.7.0 — the likers panel a heart tap opens takes the heart as its opener (`onLike` / `PostHandlers.onLike` receive the click event as a third argument), and the `engagementActions` slot receives the inline disclosure as a fourth argument (`PostInlineDisclosure`, now with `likes`), so a host's own actions report the open panel and return focus on Safari
  • v0.7.0 — the inline comments panel scrolls in a focusable, named region (`commentLabels.commentsRegion`, else `labels.commentsHeading`), so keyboard users can scroll it
  • v0.6.0 — controlled `post` + `onPostChange(next, change)`: the prop wins on every render; like / bookmark / poll vote show at once while their promise is in flight and are reported once accepted; a rejection rolls back (both modes); latest request wins; `optimistic`
  • v0.6.0 — `reactions` (kinds, counts, viewer reaction, `onReact`, `defaultKind`) replaces the like with a reaction picker; double-tap applies the default reaction when none is set and bursts once
  • v0.6.0 — header: `getAuthorHref` (avatar + name links), `subtitle`, `noticeSlot`, labelled kebab that survives `renderHeader(post, { kebab })`, `extraKebabActions` appended, `hidden` items, `permissions.disabled`
  • v0.6.0 — `locale`, `timeZone`, `now`, `formatRelativeTime`, `formatCount`: no clock read during render (relative time renders after mount), the poll uses the same clock, the edited tooltip is locale-formatted; one `locale` reaches the carousel, bar, likers, share menu and thread
  • v0.6.0 — forwarding bags `mediaProps`, `engagementBarProps`, `commentThreadProps` (cursor paging, replies, `onCommentsChange`, the `moderation` add-on…); nested `likersLabels` / `shareLabels` / `textLabels`
  • v0.6.0 — **breaking:** `likersMoreLabel`, `pollTotalVotesLabel`, `pollClosesAtLabel` are functions (`(count, formatted) => …` / `(time) => …`); list meta via `listLikes` / `listComments` / `listShares`; `openRepost(name)`
  • v0.6.1 — inline panels carry disclosure state (`aria-expanded` / `aria-controls` on the comment, share and likers-count buttons, via the engagement bar's `expanded` / `controls`); for those three buttons the opener is the clicked button, so focus returns to it on Safari and macOS Firefox (the likers panel a heart tap auto-opens still takes `document.activeElement` as the opener, which is the card on Safari); actions built in the `engagementActions` slot carry no disclosure state
  • 4 variants: feed (Instagram-post) / compact (sidebar widget) / list (admin row, full-height thumb) / detail (full page + embedded thread)
  • Composes 5 Tier-1 social siblings via cross-folder imports (declared registryDependencies)
  • Inline engagement panels DEFAULT — tap heart to like, tap count to open likers strip; tap comment for inline thread+composer; tap share for searchable user list
  • engagementMode='navigate' opt-out for hosts that prefer page-navigation UX (single-button like, comment fires onComment(id))
  • v0.2.0 — Permissions matrix + viewerMode (owner|viewer) + canPerformAction predicate; dual-mode defaultPostKebabActions preserves zero v0.1 drift
  • v0.2.0 — 12 new optional Post fields: isPinned, isSensitive, sensitiveReason, visibility, editedAt, mentions, tags, location, language, replyTo, repostOf, linkPreview, poll
  • v0.2.0 — Inline poll widget with optimistic vote (vote buttons / live results bar chart with width transition; motion-reduce safe)
  • v0.2.0 — Sensitive-media gate with reveal button (per-post; analytics hook via onRevealSensitive)
  • v0.2.0 — OG link-preview card (host pre-fetches; library is fetch-free)
  • v0.2.0 — Nested repost mini-card (compact + navigate + empty engagementActions; recursion-strip)
  • v0.2.0 — Header badges: pinned, visibility (6 base values + branded extension), edited suffix, replyTo sub-line, location chip
  • v0.2.0 — MentionText + TagChips sub-exports for inline mention highlighting via renderContent slot
  • v0.2.0 — RepostOfCard + PollWidget sub-exports for standalone use outside the auto-rendered slot
  • v0.2.0 — Responsive sweep: padding / avatar / body-text / list-thumb step at sm / md / lg per description §2.1-B; touch targets ≥44×44 (kebab fixed)
  • v0.2.0 — engagement-bar v0.2.x dependency (LikersStrip + ShareMenu sub-exports re-exported here for soft-compat)
  • v0.2.0 — Imperative handle gains 5 trigger methods: triggerEdit / triggerDelete / triggerPin / revealSensitive / votePoll
  • v0.3.0 — Moderator section in kebab (ILX-3): `moderatorActions(post)` slot + `canModerate` permission + `"moderate"` action discriminator. Orthogonal to viewerMode (never auto-derived). Renders between common items and viewer-destructive items with a divider above.
  • v0.3.1 — F-S1 cross-procomp cleanup: 32 absolute `@/registry/components/...` imports across 9 files converted to relative + specific-file paths (the F-S1 lock pattern). Latent v0.2.0 bug where shadcn 4.6.0's path-rewriter mangled cross-procomp barrel imports — surfaced post-push by the v0.3.0 smoke; consumers couldn't tsc-pass after install. Zero public-API change.
  • v0.3.2 — Cross-category MediaItem inline-copy: shadcn rewriter mangles cross-category `/types` imports in unpredictable ways (sometimes to wrong-slug, sometimes preserving an invalid `<cat>/` prefix). Local `PostMediaItem` type defined in `types.ts` (structurally identical to media-carousel's MediaItem); `MediaItem` retained as soft-compat alias for v0.2.x consumers. Drops the broken cross-category re-export from `index.ts`.
  • LikersStrip part — horizontal swipable avatar strip + paginating +N pill (touch swipe + desktop drag-to-scroll)
  • ShareMenu part — searchable user picker; local filter when no async wired, optional onShareSearch for backend search
  • Auto-wired canonical heart-burst on double-tap (heuristic; disableHeartBurst opt-out)
  • Engagement bar runs controlled by the card: realtime deltas and optimistic changes flow through one shown post
  • Wrapped engagement handlers — defaultPostEngagementActions(post, handlers, variant, onLikeCountClick?(event), reactions?, inline?) gets pre-wrapped handlers
  • Default kebab — Bookmark / Share / Copy link / Report (legacy); role-aware kebab with Edit / Delete / Pin / Change visibility / Mark sensitive / See analytics / Block / Mute / Translate when viewerMode set
  • kebabActions slot for full takeover (moderator semantics)
  • engagementActions slot — defaultPostEngagementActions exported for extend-not-replace
  • Overlay-link via getHref + linkComponent (polymorphic root) — non-detail variants only
  • Two separate subscribe props (engagementSubscribe + commentSubscribe) — distinct delta types stay distinct
  • Embedded CommentThread in detail variant + renderCommentSection slot
  • renderHeader / renderContent / renderMedia / renderEngagementBar slots — full takeover at every seam
  • v0.2.0 — Additional slots: renderPoll / renderLinkPreview / renderRepostOf / renderSensitiveGate + disableXxxRender opt-outs
  • VerifiedBadge sub-export — RSC-compatible (no `"use client"`)
  • `post` is mount-only unless `onPostChange` is passed (controlled); ref.current.reset(next) pushes a post in uncontrolled mode and clears overlays, the poll vote and the sensitive reveal in both
  • Tailwind v4-clean (no legacy class names)
  • No new shadcn primitives needed (avatar / button / card / dropdown-menu / input / popover present)
  • No framer-motion — inherits engagement-heart-burst CSS from engagement-bar
  • Uses the `engagement-bar` like-action `onCountClick` split (heart vs count) when in inline mode
  • v0.5 barrel completeness: the eleven `Post` / `PostCardProps` sub-shapes (PostMention, PostPoll, PostPollOption, PostLocation, PostReplyTo, LinkPreview, PostVisibility, PostViewerMode, PostPermissions, PostPermissionAction, PostMutationHandlers) are now importable from the package root — previously a consumer could hold a `Post` and still not name the type of a field they were building. Type-only, additive.
  • v0.5.1 — Double-tap on the media never removes a like: unliked → like + heart burst; already liked → burst only; no like applicable (no `like` action in the bar, or a `renderEngagementBar` takeover) → no burst. Handle `triggerLike()` keeps toggle semantics but bursts only when the result is liked. Previously double-tap on a liked post UNLIKED it while the heart played, and bar-less posts burst with no effect.

Tags

post-cardsocialposttier-2compositefeeddetailcompactlistrealtimeheart-burstinline-panelssharelikers

Dependencies

shadcn primitives: avatar, button, dropdown-menu
npm peer deps: lucide-react@^1.11.0
internal: expandable-text, media-carousel, engagement-bar, comment-thread