{"$schema":"https:\/\/ui.particle.academy\/schema\/registry-item.json","name":"track-item","type":"registry:ui","title":"TrackItem","description":"One track as a row - position, artwork, title, artist, duration, a now-playing mark and room for actions.","package":"react-fancy","dependencies":["tailwind-merge","lucide-react"],"registryDependencies":["icon","channel-player"],"files":[{"path":"components\/fancy\/track-item\/TrackItem.tsx","content":"import { forwardRef } from \"react\";\nimport { cn } from \"..\/lib\/utils\/cn\";\nimport { fillLabel } from \"..\/lib\/utils\/label-template\";\nimport { formatMediaTime } from \"..\/lib\/utils\/format-media-time\";\nimport { visuallyHidden } from \"..\/lib\/utils\/visually-hidden\";\nimport { Icon } from \"..\/icon\/Icon\";\nimport { FOCUS_RING, TEXT, TEXT_MUTED, TEXT_SOFT } from \"..\/channel-player\/media-classes\";\nimport type { TrackItemLabels, TrackItemProps } from \".\/TrackItem.types\";\n\nconst DEFAULT_LABELS: TrackItemLabels = {\n  nowPlaying: \"Now playing\",\n  play: \"Play {title}\",\n};\n\n\/** One track as a row: artwork, title, artist, duration, a now-playing mark and optional actions. *\/\nexport const TrackItem = forwardRef<HTMLDivElement, TrackItemProps>(function TrackItem(\n  { track, index, active = false, playing = false, onSelect, actions, labels: labelsProp, className, ...rest },\n  ref,\n) {\n  const labels = { ...DEFAULT_LABELS, ...labelsProp };\n  const body = (\n    <>\n      {track.artwork && <img src={track.artwork} alt=\"\" className=\"h-9 w-9 shrink-0 rounded object-cover\" \/>}\n      <span className=\"flex min-w-0 flex-col text-start\">\n        <span className={cn(\"truncate text-sm\", active ? \"font-semibold\" : \"font-medium\", TEXT)}>{track.title}<\/span>\n        {track.artist && <span className={cn(\"truncate text-xs\", TEXT_MUTED)}>{track.artist}<\/span>}\n      <\/span>\n    <\/>\n  );\n\n  return (\n    <div\n      ref={ref}\n      data-react-fancy-track-item=\"\"\n      data-track-id={track.id}\n      data-active={active ? \"true\" : \"false\"}\n      className={cn(\"flex min-w-0 items-center gap-3 px-2 py-1.5\", className)}\n      {...rest}\n    >\n      {index != null && (\n        <span aria-hidden=\"true\" className={cn(\"w-5 shrink-0 text-end text-xs tabular-nums\", TEXT_MUTED)}>\n          {active && playing ? <Icon name=\"audio-lines\" size=\"xs\" \/> : index}\n        <\/span>\n      )}\n      {onSelect ? (\n        <button\n          type=\"button\"\n          data-track-select=\"\"\n          aria-label={fillLabel(labels.play, { title: track.title, artist: track.artist ?? \"\" })}\n          onClick={() => onSelect(track.id)}\n          className={cn(\"flex min-h-11 min-w-0 flex-1 items-center gap-3 rounded\", FOCUS_RING)}\n        >\n          {body}\n        <\/button>\n      ) : (\n        <span data-track-select=\"\" className=\"flex min-w-0 flex-1 items-center gap-3\">\n          {body}\n        <\/span>\n      )}\n      {active && playing && (\n        <span data-track-now-playing=\"\" className=\"sr-only\" style={visuallyHidden}>\n          {labels.nowPlaying}\n        <\/span>\n      )}\n      {track.duration != null && (\n        <span data-track-duration=\"\" className={cn(\"shrink-0 text-xs tabular-nums\", TEXT_SOFT)}>\n          {formatMediaTime(track.duration)}\n        <\/span>\n      )}\n      {actions && <span className=\"flex shrink-0 items-center gap-1\">{actions}<\/span>}\n    <\/div>\n  );\n});\n\nTrackItem.displayName = \"TrackItem\";\n","type":"registry:ui","target":"components\/fancy\/track-item\/TrackItem.tsx"},{"path":"components\/fancy\/track-item\/TrackItem.types.ts","content":"import type { HTMLAttributes, ReactNode } from \"react\";\nimport type { MediaTrack } from \"..\/lib\/utils\/media-channel\";\n\nexport interface TrackItemLabels {\n  \/** Read out beside the current track while it plays. *\/\n  nowPlaying: string;\n  \/** The select button's name. Slots: `{title}`, `{artist}`. *\/\n  play: string;\n}\n\nexport interface TrackItemProps extends Omit<HTMLAttributes<HTMLDivElement>, \"onSelect\"> {\n  track: MediaTrack;\n  \/** 1-based position, shown before the title. *\/\n  index?: number;\n  \/** The current track. *\/\n  active?: boolean;\n  \/** The current track is playing. *\/\n  playing?: boolean;\n  \/** Makes the title a button. *\/\n  onSelect?: (trackId: string) => void;\n  \/** Controls at the end of the row (Playlist's move \/ remove). *\/\n  actions?: ReactNode;\n  \/** Every visible string. English defaults. *\/\n  labels?: Partial<TrackItemLabels>;\n}\n","type":"registry:ui","target":"components\/fancy\/track-item\/TrackItem.types.ts"},{"path":"components\/fancy\/track-item\/index.ts","content":"export { TrackItem } from \".\/TrackItem\";\nexport type { TrackItemProps, TrackItemLabels } from \".\/TrackItem.types\";\n","type":"registry:ui","target":"components\/fancy\/track-item\/index.ts"},{"path":"components\/fancy\/lib\/utils\/cn.ts","content":"import { twMerge } from \"tailwind-merge\";\n\n\/**\n * A class value: a string, a number, a conditional map, an array of any of\n * those, or nothing. Mirrors what `clsx` accepted, because every component in\n * this package already passes these shapes.\n *\/\nexport type ClassValue =\n  | string\n  | number\n  | bigint\n  | null\n  | undefined\n  | false\n  | ClassDictionary\n  | ClassValue[];\n\ntype ClassDictionary = Record<string, unknown>;\n\n\/**\n * Flatten class values into a space-separated string.\n *\n * This was `clsx` until 2026-08-19. It is roughly twenty lines of logic, it\n * shipped as a RUNTIME dependency to every consumer of this package, and its\n * last commit was 801 days old \u2014 so it fell to the rule that third-party code\n * must be both approved and actively maintained. Owning it costs less than\n * carrying it.\n *\n * `tailwind-merge` deliberately stays: deciding which of two conflicting\n * Tailwind utilities wins requires modelling the entire utility space, which is\n * emphatically not twenty lines, and it is actively maintained.\n *\n * Falsy values are dropped \u2014 including `0` and `\"\"`, which is what `clsx` did\n * and what `tests\/cn.test.ts` pins. A truthy number is kept, because digits are\n * legal class names. `bigint` is admitted because clsx's signature did and\n * the compiler proved it reachable from two call sites here.\n *\/\nfunction flatten(value: ClassValue): string {\n  if (!value) return \"\";\n\n  if (typeof value === \"string\" || typeof value === \"number\" || typeof value === \"bigint\") {\n    return String(value);\n  }\n\n  if (Array.isArray(value)) {\n    let out = \"\";\n    for (const item of value) {\n      const part = flatten(item);\n      if (part) out = out ? `${out} ${part}` : part;\n    }\n    return out;\n  }\n\n  let out = \"\";\n  for (const key in value) {\n    if (value[key]) out = out ? `${out} ${key}` : key;\n  }\n  return out;\n}\n\nexport function cn(...inputs: ClassValue[]): string {\n  return twMerge(flatten(inputs));\n}\n","type":"registry:lib","target":"components\/fancy\/lib\/utils\/cn.ts"},{"path":"components\/fancy\/lib\/utils\/label-template.ts","content":"\/**\n * Fill a label template's `{name}` slots: `\"Digit {n} of {total}\"`,\n * `\"Open {host}\"`. Single braces, for translatable labels only; a slot with no\n * value stays as written. Literal replacement, never evaluated.\n *\/\nexport function fillLabel(template: string, values: Record<string, string | number>): string {\n  return template.replace(\/\\{(\\w+)\\}\/g, (whole: string, name: string) =>\n    Object.prototype.hasOwnProperty.call(values, name) ? String(values[name]) : whole,\n  );\n}\n","type":"registry:lib","target":"components\/fancy\/lib\/utils\/label-template.ts"},{"path":"components\/fancy\/lib\/utils\/format-media-time.ts","content":"\/** `m:ss`, or `h:mm:ss` past an hour; `--:--` for an unknown or negative time. *\/\nexport function formatMediaTime(seconds: number | undefined): string {\n  if (seconds == null || !Number.isFinite(seconds) || seconds < 0) return \"--:--\";\n  const s = Math.floor(seconds);\n  const h = Math.floor(s \/ 3600);\n  const m = Math.floor((s % 3600) \/ 60);\n  const ss = String(s % 60).padStart(2, \"0\");\n  return h > 0 ? `${h}:${String(m).padStart(2, \"0\")}:${ss}` : `${m}:${ss}`;\n}\n","type":"registry:lib","target":"components\/fancy\/lib\/utils\/format-media-time.ts"},{"path":"components\/fancy\/lib\/utils\/visually-hidden.ts","content":"import type { CSSProperties } from \"react\";\n\n\/**\n * The standard sr-only clip pattern as an inline style: the same declarations\n * Tailwind's `sr-only` utility emits. Pair it with `className=\"sr-only\"`.\n *\n * Inline because a visually hidden element must not depend on the host's\n * Tailwind build having generated `sr-only` for react-fancy's classes. Without\n * it the element renders as visible, unclipped text (genie#1290).\n *\n * The element is `position: absolute`, so whatever holds it must be positioned\n * too. Otherwise it escapes to the nearest positioned ancestor, which can sit\n * outside an unpositioned scroll container and stretch the document.\n *\/\nexport const visuallyHidden: CSSProperties = {\n  position: \"absolute\",\n  width: \"1px\",\n  height: \"1px\",\n  padding: 0,\n  margin: \"-1px\",\n  overflow: \"hidden\",\n  clip: \"rect(0, 0, 0, 0)\",\n  whiteSpace: \"nowrap\",\n  border: 0,\n};\n","type":"registry:lib","target":"components\/fancy\/lib\/utils\/visually-hidden.ts"},{"path":"components\/fancy\/lib\/utils\/media-channel.ts","content":"\/**\n * The channel model: a channel is a single track, a playlist of tracks, or a\n * live stream from any service. Every shape is plain JSON, so a host, a server\n * or an agent can emit it.\n *\n * Every channel component (ChannelPlayer, ChannelGuide, Playlist, MediaQueue)\n * is controlled through ONE {@link ChannelPlayerValue}, and every move they\n * make goes through the pure functions below. An agent bridge calls the same\n * functions, so \"next\", \"shuffle\" or \"remove\" cannot mean one thing in the UI\n * and another to an agent.\n *\/\n\n\/** Where a track or a live channel plays from. *\/\nexport type ChannelSource =\n  \/** A finite file: MP3, M4A, MP4, WebM... Seekable. *\/\n  | { type: \"file\"; url: string; mime?: string; media?: \"audio\" | \"video\" }\n  \/**\n   * An endless stream. `protocol` defaults by guess: `.m3u8` is HLS, `.mpd` is\n   * DASH, anything else is an Icecast \/ Shoutcast mount.\n   *\/\n  | { type: \"stream\"; url: string; protocol?: \"icecast\" | \"hls\" | \"dash\"; media?: \"audio\" | \"video\" }\n  \/** A provider's own player in an iframe: `youtube`, `vimeo`, `twitch`, or one a host registers. *\/\n  | { type: \"embed\"; provider: string; id: string; params?: Record<string, string> };\n\nexport type EmbedSource = Extract<ChannelSource, { type: \"embed\" }>;\n\nexport interface MediaTrack {\n  \/** Stable identity: `value.trackId`, `data-track-id`. Unique within a channel. *\/\n  id: string;\n  title: string;\n  artist?: string;\n  album?: string;\n  \/** Seconds, when known up front (shown before the file loads). *\/\n  duration?: number;\n  \/** Image URL. *\/\n  artwork?: string;\n  source: ChannelSource;\n}\n\nexport type LiveStatus = \"live\" | \"offline\" | \"starting\" | \"ended\";\n\nexport interface ChannelBase {\n  \/** Stable identity: `value.channelId`, `data-channel-id`. *\/\n  id: string;\n  name: string;\n  description?: string;\n  artwork?: string;\n  tags?: string[];\n}\n\nexport type TrackChannel = ChannelBase & { kind: \"track\"; track: MediaTrack };\nexport type PlaylistChannel = ChannelBase & { kind: \"playlist\"; tracks: MediaTrack[] };\nexport type LiveChannel = ChannelBase & {\n  kind: \"live\";\n  source: ChannelSource;\n  \/** Supplied by the host (a provider API, an Icecast status poll). Default `\"live\"`. *\/\n  status?: LiveStatus;\n  \/** What is on air, supplied by the host. *\/\n  nowPlaying?: string;\n};\n\nexport type Channel = TrackChannel | PlaylistChannel | LiveChannel;\nexport type ChannelKind = Channel[\"kind\"];\n\nexport type RepeatMode = \"off\" | \"all\" | \"one\";\n\n\/** The whole state of a channel UI, in one JSON object. *\/\nexport interface ChannelPlayerValue {\n  channelId: string | null;\n  \/** The current track: within a playlist, the track channel's own track, or `null` on live. *\/\n  trackId: string | null;\n  \/** Whether the host wants media playing. Components set it back to `false` when the browser refuses. *\/\n  playing: boolean;\n  \/** Seconds into the current track. Ignored on live. Moving it seeks. *\/\n  position: number;\n  \/** 0..1 *\/\n  volume: number;\n  muted: boolean;\n  shuffle: boolean;\n  repeat: RepeatMode;\n  \/** The shuffled play order (track ids), or `null` for playlist order. *\/\n  order: string[] | null;\n}\n\n\/** A playlist edit held for a person to confirm (an agent proposes, a human accepts). *\/\nexport type PendingQueueEdit =\n  | { id: string; op: \"remove\"; trackId: string }\n  | { id: string; op: \"clear\" }\n  | { id: string; op: \"replace\"; tracks: MediaTrack[] };\n\ntype Random = () => number;\n\n\/** Seconds into a track before \"previous\" restarts it instead of going back. *\/\nconst RESTART_THRESHOLD = 3;\n\nexport function createChannelValue(patch: Partial<ChannelPlayerValue> = {}): ChannelPlayerValue {\n  return {\n    channelId: null,\n    trackId: null,\n    playing: false,\n    position: 0,\n    volume: 1,\n    muted: false,\n    shuffle: false,\n    repeat: \"off\",\n    order: null,\n    ...patch,\n  };\n}\n\nexport function findChannel(channels: readonly Channel[], id: string | null | undefined): Channel | undefined {\n  return id == null ? undefined : channels.find((c) => c.id === id);\n}\n\n\/** The tracks a channel plays: one, the list, or none for live. *\/\nexport function channelTracks(channel: Channel | undefined): MediaTrack[] {\n  if (!channel) return [];\n  if (channel.kind === \"track\") return [channel.track];\n  if (channel.kind === \"playlist\") return channel.tracks;\n  return [];\n}\n\n\/** Fisher-Yates over a copy; `first`, when given and present, leads. *\/\nexport function shuffleIds(ids: readonly string[], random: Random = Math.random, first?: string | null): string[] {\n  const out = ids.filter((id) => id !== first);\n  for (let i = out.length - 1; i > 0; i--) {\n    const j = Math.min(i, Math.floor(random() * (i + 1)));\n    [out[i], out[j]] = [out[j]!, out[i]!];\n  }\n  return first != null && ids.includes(first) ? [first, ...out] : out;\n}\n\n\/**\n * The order tracks play in. A held shuffle order is used only while it names\n * exactly the channel's tracks; a stale one (tracks added or removed since)\n * is repaired: unknown ids dropped, missing ones appended.\n *\/\nexport function playOrder(channel: Channel | undefined, value: ChannelPlayerValue): string[] {\n  const ids = channelTracks(channel).map((t) => t.id);\n  if (!value.shuffle || !value.order) return ids;\n  const kept = value.order.filter((id) => ids.includes(id));\n  return [...kept, ...ids.filter((id) => !kept.includes(id))];\n}\n\nexport function currentTrack(channel: Channel | undefined, value: ChannelPlayerValue): MediaTrack | undefined {\n  if (value.trackId == null) return undefined;\n  return channelTracks(channel).find((t) => t.id === value.trackId);\n}\n\n\/** Tune to a channel: its first track (in shuffle order when shuffling), from the start. *\/\nexport function selectChannel(\n  value: ChannelPlayerValue,\n  channel: Channel | undefined,\n  random: Random = Math.random,\n): ChannelPlayerValue {\n  if (!channel) return { ...value, channelId: null, trackId: null, position: 0, order: null };\n  const ids = channelTracks(channel).map((t) => t.id);\n  const order = value.shuffle && channel.kind === \"playlist\" ? shuffleIds(ids, random) : null;\n  return {\n    ...value,\n    channelId: channel.id,\n    trackId: (order ?? ids)[0] ?? null,\n    position: 0,\n    order,\n  };\n}\n\nexport function selectTrack(value: ChannelPlayerValue, trackId: string): ChannelPlayerValue {\n  return { ...value, trackId, position: 0 };\n}\n\nexport function toggleShuffle(\n  value: ChannelPlayerValue,\n  channel: Channel | undefined,\n  random: Random = Math.random,\n): ChannelPlayerValue {\n  if (value.shuffle) return { ...value, shuffle: false, order: null };\n  const ids = channelTracks(channel).map((t) => t.id);\n  return { ...value, shuffle: true, order: shuffleIds(ids, random, value.trackId) };\n}\n\nexport function cycleRepeat(value: ChannelPlayerValue): ChannelPlayerValue {\n  const next: Record<RepeatMode, RepeatMode> = { off: \"all\", all: \"one\", one: \"off\" };\n  return { ...value, repeat: next[value.repeat] };\n}\n\n\/** The next track by hand. At the end: wraps with repeat all, otherwise nothing changes. *\/\nexport function nextTrack(value: ChannelPlayerValue, channel: Channel | undefined): ChannelPlayerValue {\n  const order = playOrder(channel, value);\n  if (order.length === 0) return value;\n  const at = value.trackId == null ? -1 : order.indexOf(value.trackId);\n  if (at < order.length - 1) return selectTrack(value, order[at + 1]!);\n  return value.repeat === \"all\" ? selectTrack(value, order[0]!) : value;\n}\n\n\/** Restart a track more than 3s in; otherwise the one before (wrapping with repeat all). *\/\nexport function previousTrack(value: ChannelPlayerValue, channel: Channel | undefined): ChannelPlayerValue {\n  const order = playOrder(channel, value);\n  if (order.length === 0) return value;\n  if (value.position > RESTART_THRESHOLD) return { ...value, position: 0 };\n  const at = value.trackId == null ? 0 : order.indexOf(value.trackId);\n  if (at > 0) return selectTrack(value, order[at - 1]!);\n  if (value.repeat === \"all\") return selectTrack(value, order[order.length - 1]!);\n  return { ...value, position: 0 };\n}\n\n\/** What a track finishing does: replay, advance, wrap, or stop. *\/\nexport function trackEnded(value: ChannelPlayerValue, channel: Channel | undefined): ChannelPlayerValue {\n  const order = playOrder(channel, value);\n  if (order.length === 0) return { ...value, playing: false, position: 0 };\n  if (value.repeat === \"one\" || (order.length === 1 && value.repeat === \"all\")) return { ...value, position: 0 };\n  const at = value.trackId == null ? -1 : order.indexOf(value.trackId);\n  if (at < order.length - 1) return selectTrack(value, order[at + 1]!);\n  if (value.repeat === \"all\") return selectTrack(value, order[0]!);\n  return { ...value, playing: false, position: 0 };\n}\n\n\/** What plays after the current track, in play order (wrapping with repeat all). *\/\nexport function upNext(channel: Channel | undefined, value: ChannelPlayerValue): MediaTrack[] {\n  const tracks = channelTracks(channel);\n  const order = playOrder(channel, value);\n  const at = value.trackId == null ? -1 : order.indexOf(value.trackId);\n  const after = order.slice(at + 1);\n  const ids = value.repeat === \"all\" && at >= 0 ? [...after, ...order.slice(0, at)] : after;\n  return ids.map((id) => tracks.find((t) => t.id === id)!).filter(Boolean);\n}\n\nexport function moveTrack(tracks: readonly MediaTrack[], trackId: string, toIndex: number): MediaTrack[] {\n  const from = tracks.findIndex((t) => t.id === trackId);\n  if (from < 0) return [...tracks];\n  const out = tracks.filter((t) => t.id !== trackId);\n  const to = Math.max(0, Math.min(out.length, Math.floor(toIndex)));\n  out.splice(to, 0, tracks[from]!);\n  return out;\n}\n\n\/** Add a track (at the end, or at `index`). A duplicate id is refused: the same array comes back. *\/\nexport function addTrack<T extends readonly MediaTrack[]>(tracks: T, track: MediaTrack, index?: number): T | MediaTrack[] {\n  if (tracks.some((t) => t.id === track.id)) return tracks;\n  const out = [...tracks];\n  out.splice(index == null ? out.length : Math.max(0, Math.min(out.length, index)), 0, track);\n  return out;\n}\n\nexport function removeTrack(tracks: readonly MediaTrack[], trackId: string): MediaTrack[] {\n  return tracks.filter((t) => t.id !== trackId);\n}\n\nexport function applyQueueEdit(tracks: readonly MediaTrack[], edit: PendingQueueEdit): MediaTrack[] {\n  if (edit.op === \"remove\") return removeTrack(tracks, edit.trackId);\n  if (edit.op === \"clear\") return [];\n  return [...edit.tracks];\n}\n\n\/**\n * Bring a value back in step after a channel's tracks changed. A current track\n * that was removed gives way to the one that took its place (or the first);\n * an emptied channel stops. A shuffle order keeps its sequence, drops removed\n * ids and appends added ones. Another channel's value comes back untouched.\n *\/\nexport function reconcileValue(\n  value: ChannelPlayerValue,\n  channel: Channel,\n  previous?: Channel,\n): ChannelPlayerValue {\n  if (value.channelId !== channel.id) return value;\n  const ids = channelTracks(channel).map((t) => t.id);\n  const order = value.shuffle && value.order ? playOrder(channel, value) : null;\n  const sameOrder =\n    order === value.order ||\n    (order !== null && value.order !== null && order.length === value.order.length && order.every((id, i) => id === value.order![i]));\n  if (value.trackId != null && ids.includes(value.trackId)) {\n    return sameOrder ? value : { ...value, order };\n  }\n  if (ids.length === 0) return { ...value, trackId: null, playing: false, position: 0, order: value.shuffle ? [] : null };\n  \/\/ The first survivor after the removed track, in the order that was playing\n  \/\/ (known from `previous`, or from a held shuffle order); else the first.\n  const before = previous ? playOrder(previous, value) : (value.order ?? []);\n  const oldIndex = value.trackId == null ? -1 : before.indexOf(value.trackId);\n  const survivor = oldIndex >= 0 ? before.slice(oldIndex + 1).find((id) => ids.includes(id)) : undefined;\n  return { ...value, trackId: survivor ?? (order ?? ids)[0]!, position: 0, order };\n}\n","type":"registry:lib","target":"components\/fancy\/lib\/utils\/media-channel.ts"}]}