. */ railLabel?: string; /** Default "Add story". Visible label below the AddStoryThumbnail (read from the rail's context). */ addStoryLabel?: string; /** Default "Add story" (contains the visible text — WCAG 2.5.3). aria-label for the AddStoryThumbnail button (read from the rail's context). */ addStoryAriaLabel?: string; /** * Accessible name of a thumbnail. Receives the whole item (incl. `hasUnread` * and `muted`) so hosts can localize / pluralize. Default: * "{username}, muted" / "{username}, unread story" / "{username}, viewed". */ thumbnailAriaLabel?: (item: StoryRailItem) => string; /** Default "Previous stories". Accessible name of the previous arrow. */ previousLabel?: string; /** Default "Next stories". Accessible name of the next arrow. */ nextLabel?: string; /** Default "No stories yet." Renders when items.length === 0 AND no leading AND no realtime. */ emptyState?: string; } export type ResolvedStoryRailLabels = Required; export const DEFAULT_STORY_RAIL_LABELS: ResolvedStoryRailLabels = { railLabel: "Stories", addStoryLabel: "Add story", addStoryAriaLabel: "Add story", thumbnailAriaLabel: (item) => item.muted ? `${item.username}, muted` : item.hasUnread ? `${item.username}, unread story` : `${item.username}, viewed`, previousLabel: "Previous stories", nextLabel: "Next stories", emptyState: "No stories yet.", }; export type StoryRailLocalAction = | { kind: "add"; item: StoryRailItem; position?: "start" | "end" } | { kind: "remove"; itemId: string } | { kind: "viewed"; itemId: string } | { kind: "update"; itemId: string; partial: Partial } | { kind: "subscribe-delta"; delta: StoryRailDelta } | { kind: "reset"; next: StoryRailItem[] }; export interface ThumbnailRenderHelpers { index: number; onClick: () => void; /** Stable id for ARIA wiring inside the slot. */ baseId: string; /** * Whether the default tile would show the gradient ring: * `hasUnread && !muted`. (`isUnread` is the raw `hasUnread`.) */ showRing: boolean; } /** * Where the previous / next arrows render. * - `"none"` (default) — no arrows; pointer drag (mouse included) and Tab focus scroll the rail. * There is no mouse-wheel / trackpad-swipe scrolling (Embla has none without a plugin). * - `"fine-pointer"` — only under `(pointer: fine)` (mouse / trackpad), resolved after mount. * - `"always"` — on every pointer type. */ export type StoryRailArrows = "none" | "fine-pointer" | "always"; export interface StoryRailProps { /** * Controlled items when `onItemsChange` is also passed: the prop wins on * every render, and every mutation (`markViewed`, `dispatch`, `reset`, * subscribe deltas) is reported through `onItemsChange` instead of applied. * To discard a reported change, re-render with a fresh array. * * Passed WITHOUT `onItemsChange` it is read once on mount (the pre-0.4 * behaviour) and a dev-only warning asks you to choose `defaultItems` or * `onItemsChange`. Do not switch between controlled and uncontrolled after mount. */ items?: StoryRailItem[]; /** Uncontrolled seed, read once on mount. Mutations apply internally. */ defaultItems?: StoryRailItem[]; /** * Receives the next list for every mutation. With `items` it makes the rail * controlled; with `defaultItems` (or no items) the rail stays uncontrolled * and only notifies. */ onItemsChange?: (next: StoryRailItem[]) => void; /** Optional content rendered before items (typically ). */ leading?: ReactNode; /** Wrap the rail in card-style chrome (bg-card + border + rounded). Default true. */ framed?: boolean; /** Realtime delta stream. Identity-stable required (useCallback host-side). */ subscribe?: Subscribe; onSubscribeDelta?: (delta: StoryRailDelta) => void; /** * Click handler — object-shape. Host typically opens a story viewer. * v0.2 cutover from positional `(item, index)`. */ onItemClick?: (args: { item: StoryRailItem; index: number }) => void; /** * Called when a preview image fails to load (e.g. an expired signed URL). * Resolve a new URL to retry once with it; resolve nothing (or reject) to * fall back to the avatar card. A new `previewImage` on the item resets it. */ onPreviewError?: (item: StoryRailItem) => Promise; /** * Previous / next arrows. Default `"none"`. Vertically centred on the default * 112px tile; override with `--story-rail-arrow-top` for custom tiles. */ arrows?: StoryRailArrows; /** Text direction. Default: the nearest `[dir]` ancestor, else `"ltr"`. */ dir?: "ltr" | "rtl"; /** Polymorphic root for the thumbnail when getHref provided. Default `"a"`. */ linkComponent?: ElementType; /** When provided, thumbnail renders as `` instead of ` ); } export const StoryThumbnail = memo(StoryThumbnailInner); StoryThumbnail.displayName = "StoryThumbnail"; ``` ### `src/registry/components/data/story-rail/parts/add-story-thumbnail.tsx` ```tsx "use client"; import { memo, useState } from "react"; import { Plus } from "lucide-react"; import { cn } from "@/lib/utils"; import { DEFAULT_STORY_RAIL_LABELS } from "../types"; import { useStoryRailLabels } from "./story-rail-context"; export interface AddStoryThumbnailProps { /** Avatar shown at 50% opacity inside the dashed-border placeholder. */ userAvatar?: string; onClick?: () => void; /** * Visible label below. Default: the enclosing rail's `labels.addStoryLabel` * (when rendered in ``), else "Add story". */ label?: string; /** * aria-label on the button. Default: the enclosing rail's * `labels.addStoryAriaLabel`, else "Add story". */ ariaLabel?: string; className?: string; } function AddStoryThumbnailInner({ userAvatar, onClick, label, ariaLabel, className, }: AddStoryThumbnailProps) { const railLabels = useStoryRailLabels() ?? DEFAULT_STORY_RAIL_LABELS; const [avatarFailed, setAvatarFailed] = useState(null); const showAvatar = !!userAvatar && avatarFailed !== userAvatar; return ( ); } export const AddStoryThumbnail = memo(AddStoryThumbnailInner); AddStoryThumbnail.displayName = "AddStoryThumbnail"; ``` ### `src/registry/components/data/story-rail/hooks/use-story-rail-state.ts` ```ts "use client"; import { useCallback, useEffect, useLayoutEffect, useRef, useState, } from "react"; import type { StoryRailDelta, StoryRailItem, StoryRailLocalAction, Subscribe, } from "../types"; // useLayoutEffect warns during SSR; the effect is only needed in the browser. const useIsoLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect; const EMPTY: StoryRailItem[] = []; // ─── Pure helpers ──────────────────────────────────────────────────────────── function insertAtPosition( state: StoryRailItem[], item: StoryRailItem, position: "start" | "end" | undefined, ): StoryRailItem[] { if (position === "end") return [...state, item]; return [item, ...state]; // default "start" } function removeById(state: StoryRailItem[], id: string): StoryRailItem[] { const next = state.filter((i) => i.id !== id); return next.length === state.length ? state : next; } function patchById( state: StoryRailItem[], id: string, patch: Partial, ): StoryRailItem[] { let mutated = false; const next = state.map((i) => { if (i.id !== id) return i; mutated = true; return { ...i, ...patch }; }); return mutated ? next : state; } // ─── Reducer ───────────────────────────────────────────────────────────────── /** Pure reducer — exported for hosts driving their own state. */ export function storyRailReducer( state: StoryRailItem[], action: StoryRailLocalAction, ): StoryRailItem[] { switch (action.kind) { case "add": return insertAtPosition(state, action.item, action.position); case "remove": return removeById(state, action.itemId); case "viewed": return patchById(state, action.itemId, { hasUnread: false }); case "update": return patchById(state, action.itemId, action.partial); case "subscribe-delta": { const d = action.delta; switch (d.kind) { case "added": return insertAtPosition(state, d.item, d.position); case "removed": return removeById(state, d.itemId); case "viewed": return patchById(state, d.itemId, { hasUnread: false }); case "updated": return patchById(state, d.itemId, d.partial); } return state; } case "reset": return action.next; } } // ─── Hook ──────────────────────────────────────────────────────────────────── export interface UseStoryRailStateOptions { /** Uncontrolled seed — captured ON MOUNT only. Ignored while controlled. */ initialItems?: StoryRailItem[]; /** * Controlled value — controlled only when `onItemsChange` is ALSO passed; * then it wins on every render and mutations are reported instead of applied. */ items?: StoryRailItem[]; /** * Receives the next list for every mutation. With `items` it makes the rail * controlled; without `items` the rail stays uncontrolled and just notifies. */ onItemsChange?: (next: StoryRailItem[]) => void; subscribe?: Subscribe; onSubscribeDelta?: (delta: StoryRailDelta) => void; } export interface UseStoryRailStateResult { items: StoryRailItem[]; /** * Stable identity. Computes the next list from the latest one, applies it * when uncontrolled, and reports it through `onItemsChange` either way. */ dispatch: React.Dispatch; /** True when both `items` and `onItemsChange` are passed. */ isControlled: boolean; } export function useStoryRailState( opts: UseStoryRailStateOptions, ): UseStoryRailStateResult { const [internalItems, setInternalItems] = useState( () => opts.initialItems ?? EMPTY, ); const isControlled = opts.items !== undefined && opts.onItemsChange !== undefined; const items = isControlled ? (opts.items ?? EMPTY) : internalItems; // Mutations compute from the latest list. Between a mutation and the next // render that carries it, a second mutation (a burst of realtime deltas) // must build on the first — so the computed list is kept here and replaced // only when the list the rail renders CHANGES IDENTITY (a new prop / new // internal state). Unrelated rail commits (scroll state) never reset it, so // a host that applies updates asynchronously loses nothing. A controlled // host that rejects a change re-renders with a fresh array to discard it. const latestRef = useRef(items); useIsoLayoutEffect(() => { latestRef.current = items; }, [items]); const isControlledRef = useRef(isControlled); const onItemsChangeRef = useRef(opts.onItemsChange); const onSubscribeDeltaRef = useRef(opts.onSubscribeDelta); useIsoLayoutEffect(() => { isControlledRef.current = isControlled; onItemsChangeRef.current = opts.onItemsChange; onSubscribeDeltaRef.current = opts.onSubscribeDelta; }); const dispatch = useCallback((action: StoryRailLocalAction) => { const prev = latestRef.current; const next = storyRailReducer(prev, action); if (next === prev) return; latestRef.current = next; if (!isControlledRef.current) setInternalItems(next); onItemsChangeRef.current?.(next); }, []); const subscribe = opts.subscribe; useEffect(() => { if (!subscribe) return; const unsub = subscribe((delta) => { onSubscribeDeltaRef.current?.(delta); dispatch({ kind: "subscribe-delta", delta }); }); return unsub; }, [subscribe, dispatch]); return { items, dispatch, isControlled }; } ``` ### `src/registry/components/data/story-rail/parts/story-rail-context.ts` ```ts "use client"; import { createContext, useContext } from "react"; import type { ResolvedStoryRailLabels } from "../types"; /** * Carries the rail's resolved labels to host-rendered parts placed in the * `leading` slot (e.g. `AddStoryThumbnail`), which the rail never renders * itself and so cannot pass props to. `null` outside a rail. */ export const StoryRailLabelsContext = createContext(null); export function useStoryRailLabels(): ResolvedStoryRailLabels | null { return useContext(StoryRailLabelsContext); } ``` ### `src/registry/components/data/story-rail/hooks/use-rail-environment.ts` ```ts "use client"; import { useEffect, useLayoutEffect, useState, useSyncExternalStore } from "react"; const useIsoLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect; function subscribeMedia(query: string) { return (onChange: () => void) => { if (typeof window === "undefined" || !window.matchMedia) return () => {}; const mq = window.matchMedia(query); mq.addEventListener("change", onChange); return () => mq.removeEventListener("change", onChange); }; } function readMedia(query: string): boolean { if (typeof window === "undefined" || !window.matchMedia) return false; return window.matchMedia(query).matches; } const FINE_POINTER = "(pointer: fine)"; const REDUCED_MOTION = "(prefers-reduced-motion: reduce)"; const subscribeFinePointer = subscribeMedia(FINE_POINTER); const subscribeReducedMotion = subscribeMedia(REDUCED_MOTION); const serverFalse = () => false; /** * True under a fine pointer (mouse / trackpad). The server snapshot is `false`, * so the server render and the hydrating client render agree; the real value * lands right after hydration. */ export function useFinePointer(): boolean { return useSyncExternalStore( subscribeFinePointer, () => readMedia(FINE_POINTER), serverFalse, ); } /** `prefers-reduced-motion: reduce`, SSR-safe (server snapshot `false`). */ export function useReducedMotion(): boolean { return useSyncExternalStore( subscribeReducedMotion, () => readMedia(REDUCED_MOTION), serverFalse, ); } /** * Resolves the text direction: the explicit `dir` prop wins; otherwise the * element's computed `direction`, read after mount (so the first client render * matches the server's `"ltr"`). Computed style covers `dir="rtl"` ancestors, * `dir="auto"` and CSS `direction: rtl` alike. A later change is not observed — * pass `dir` when your app switches direction at runtime. */ export function useResolvedDirection( ref: React.RefObject, dirProp: "ltr" | "rtl" | undefined, ): "ltr" | "rtl" { const [ancestorDir, setAncestorDir] = useState<"ltr" | "rtl">("ltr"); useIsoLayoutEffect(() => { if (dirProp) return; const el = ref.current; if (!el) return; // Fallback for environments without a UA stylesheet for `dir` (jsdom): // the nearest explicit, non-`auto` `dir` — in a browser it agrees with // the computed value whenever it says "rtl". const explicit = el .closest('[dir]:not([dir="auto"])') ?.getAttribute("dir") ?.toLowerCase(); const rtl = getComputedStyle(el).direction === "rtl" || explicit === "rtl"; setAncestorDir(rtl ? "rtl" : "ltr"); }, [dirProp, ref]); return dirProp ?? ancestorDir; } ```