ReleaseTimeline

معرفی

ReleaseTimeline یک فید انتشار (ReleaseNote[]) را به‌صورت صفحهٔ کامل تغییرات رندر می‌کند. هر ریلیز یک واحد مرزدار است و با خودش شناخته می‌شود: سرتیترش «نسخهٔ 4.2.0» است و تاریخ شمسی زیر آن (بدون نسخه، تاریخ به‌تنهایی)، و یک جداکننده و فاصلهٔ عمودیِ سخاوتمندانه آن را از ریلیز بعدی جدا می‌کند. از عرض md هر ریلیز دو ستون دارد — ستونی باریک در سمت شروع با نسخه و تاریخ که تا وقتی تغییرات همان ریلیز در حال پیمایش‌اند چسبان می‌ماند (همان الگوی صفحهٔ تغییرات Linear و Vercel و Supabase)، و ستون تغییرات. در صفحهٔ باریک سرتیتر بالای تغییرات می‌نشیند. هر ریلیز نسخه و تاریخ خودش را دارد، پس هیچ ریلیزی بی‌نام یا بی‌تاریخ نمی‌ماند — دو ریلیزِ یک روز هم.

ریلیز را از همان اجزایی می‌سازد که WhatsNewPanel و WhatsNewSpotlight به کار می‌برند، پس قرارداد همهٔ سطح‌ها یکسان است: همهٔ نسخه‌های منتشرشده و همهٔ تیترها همیشه دیده می‌شوند. هر تغییر یک changes.text کوتاه است؛ تصویر و لینک اختیاری به همان تیتر تعلق دارند. details و body قدیمی نمایش داده نمی‌شوند و summary فقط وقتی changes خالی باشد یک بولت جایگزین است. دکمهٔ بازکردن، آکاردئون و جزئیات بیشتر نداریم.

اولویت عددی priority داخل هر نسخه، بزرگ‌تر را زودتر نشان می‌دهد و تساوی ترتیب ورودی را حفظ می‌کند. بدون اولویت صریح، ترتیب نوع فعلی تغییر مهم، قابلیت جدید، بهبود و رفع اشکال برقرار است؛ ترتیب نسخه‌ها همیشه جدید به قدیم است.

چه زمانی استفاده کنیم

• در صفحهٔ اختصاصی «آخرین تغییرات» محصول، جایی که کاربر از فوتر پنل به آن می‌رسد
• وقتی می‌خواهید تاریخچهٔ بلند را با فضای کافی نشان دهید، نه در یک ستون باریک

چه زمانی استفاده نکنیم

• در هدر یا کنار آن — برای آن WhatsNewPanel هست
• برای رویدادهای عملیاتی کاربر (چه کسی چه کاری کرد) — برای آن ActionTimeline هست
• برای فهرست ساده‌ای که هیچ دسته‌بندی تغییر ندارد؛ آن‌وقت یک فهرست کافی است

استفاده

import { ReleaseTimeline } from '@partodata/ui/release-timeline'

import { whatsNewFeed } from '@/content/whats-new'

export default function WhatsNewPage() {
  return <ReleaseTimeline notes={whatsNewFeed.notes} />
}

در اپی با ProductFrame، صفحهٔ تغییرات را در CustomPage pattern="changelog" بگذارید (بی dsGap)؛ CustomPage را ببینید.

یادداشت‌های تاریخ‌دار در آینده به‌صورت خودکار کنار گذاشته می‌شوند، دقیقاً مثل پنل — یک ریلیز که یک روز زودتر منتشر شود نباید خبرش زودتر بیرون بزند.

حالت‌ها و انواع

گروه‌بندی روزانه (پیش‌فرض)

با groupBy="day" (پیش‌فرض) چند ریلیزی که در یک روز منتشر شده‌اند کنار هم یک روز خوانده می‌شوند: از عرض md جداکنندهٔ بین آن‌ها فقط از ستون تغییرات می‌گذرد، درحالی‌که بین دو روز تمام‌عرض است. هر ریلیز همچنان سرتیتر خودش را دارد — نسخه و تاریخ — و مرز خودش؛ دو ریلیزِ یک روز با نسخه‌شان از هم جدا می‌شوند، نه با یکی شدن.

ریلیزی که پنج تغییر مهم دارد، پنج موردِ هم‌وزن زیر یک برچسب «تغییرات مهم» نشان می‌دهد:

فشرده و بدون گروه‌بندی

density="compact" یک گزینهٔ واقعی است، نه اسمی بی‌اثر: فاصلهٔ بین ریلیزها کمتر، ستون نسخه و تاریخ باریک‌تر، سرتیتر یک پله کوچک‌تر (20 به 16 پیکسل) و سقف ارتفاع تصویرها کمتر می‌شود — برای تاریخچه‌ای که داخل چیز دیگری نشسته (بخشی از تنظیمات، یک کشوی کناری) و صفحه خودش changelog نیست. groupBy="none" هم به هر ریلیز جداکنندهٔ تمام‌عرض می‌دهد، حتی به دو ریلیزِ یک روز.

زیر یک هدر چسبان

ستون نسخه و تاریخ 1.5rem پایین‌تر از بالای ناحیهٔ پیمایش می‌چسبد. اگر محصول هدر چسبانی بالای صفحه دارد و صفحه را در همان سند پیمایش می‌کند، متغیر --release-timeline-sticky-top را روی خودِ ReleaseTimeline یا یکی از والدهایش برابر ارتفاع هدر به‌علاوهٔ همان فاصله بگذارید.

زیر SiteHeader با اندازهٔ پیش‌فرضش (md) ارتفاع هدر همان توکن --layout-header-height است؛ از خودِ توکن استفاده کنید تا اگر ارتفاع هدر عوض شد، فاصله هم با آن عوض شود:

// SiteHeader (اندازهٔ پیش‌فرض) + فاصلهٔ 1.5rem
<ReleaseTimeline
  notes={whatsNewFeed.notes}
  className="[--release-timeline-sticky-top:calc(var(--layout-header-height)+1.5rem)]"
/>

برای هدرِ دیگری با ارتفاع ثابت همان عدد را بنویسید، مثلاً برای نواری 56 پیکسلی (3.5rem): className="[--release-timeline-sticky-top:5rem]".

راهنمای استفاده

Props

این کامپوننت دیگر نگاشتی روی ActionTimeline نیست (به هشدار بالا مراجعه کنید)، پس propهای ActionTimeline را نمی‌پذیرد. تنها ویژگی‌های استاندارد یک <div> (React.HTMLAttributes<HTMLDivElement> — مثل id، style، onClick) پاس داده می‌شوند؛ hideConnector هم دیگر معنایی ندارد چون این layout اصلاً خط اتصالی ندارد. ردیف‌های این خط زمان عمداً قابل کلیک نیستند: یادداشت انتشار مقصدی برای رفتن ندارد.

دسترسی‌پذیری

• فهرست ریلیزها یک <ol> است و هر ریلیز یک <article> در یک <li>، که با سرتیتر خودش نام‌گذاری شده: یک <h2> با «نسخهٔ 4.2.0» و تاریخ (بدون نسخه، تاریخ به‌تنهایی). هیچ تغییری سرتیتر نیست — هر تغییر یک <li> در فهرستِ گروهش است — پس کاربری که با کلید سرتیترها (H) حرکت می‌کند از ریلیزی به ریلیز دیگر می‌رود. دو ریلیزِ یک روز هر کدام سرتیتر خودشان را دارند.
• جداکننده‌ها فقط حاشیه‌اند (border-t روی <li> هر ریلیز، یا از md روی ستون تغییراتِ ریلیز دومِ یک روز) و عنصری در درخت دسترسی‌پذیری نیستند؛ مرز ریلیزها را ساختار <li>/<article> اعلام می‌کند، نه خط.
• تاریخ در <time dateTime> با مقدار میلادیِ ماشین‌خوان می‌آید، درحالی‌که کاربر شمسی می‌بیند. زمان نسبی («3 روز پیش») حذف شد: در صفحه‌ای که تاریخ سرتیتر است، دو نمایش زمان با هم رقابت می‌کردند، و با آهنگ حدوداً یک تغییر در هفته، جدیدترین ورودی «1 هفته پیش» می‌خواند که روی سطحی که باید مهم به‌نظر برسد، بی‌توجهی را می‌رساند.
• آیکون نوع تغییر aria-hidden است و همان معنا در متنِ برچسب کنارش تکرار می‌شود، پس هیچ اطلاعاتی فقط در رنگ نمی‌ماند — و این عمدی است، چون فاصلهٔ رنگیِ دو نوعِ پرتکرار به‌تنهایی قابل اتکا نیست.
• هر گروه تغییر role="group" با نام دسترسی‌پذیر دارد و برچسبِ دیداری‌اش aria-hidden است، وگرنه صفحه‌خوان برچسب را دو بار می‌خواند.
• نسخه یک جزیرهٔ dir="ltr" با ارقام لاتین است، بعد از واژهٔ «نسخهٔ»؛ صفحه‌خوان بین نسخه و تاریخ ویرگول می‌شنود.

کامپوننت‌های مرتبط

• WhatsNew — زنگوله، پنل و مودال؛ اگر دنبال سطح داخل هدر هستید از آن‌جا شروع کنید
• ActionTimeline — برای فید فعالیت (چه کسی چه کاری کرد)؛ اگر داده‌تان یادداشت انتشار نیست آن را به کار ببرید
• Markdown — تیتر کوتاه تغییرها با همین رندرکننده نمایش داده می‌شود