@oxy.so/bloom 2.8.0 → 2.10.0

package/src/media-card/types.ts

@@ -0,0 +1,395 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+/** Cover side in the `tile` layout: `large` 200, `medium` 160 (default), `small` 120. */
+export type MediaCardSize = 'large' | 'medium' | 'small';
+
+/**
+ * `tile` — artwork on top, text under it (a shelf or a grid).
+ * `row` — a 56 (48 at `small`) cover on the left, text, then a trailing slot (a list).
+ */
+export type MediaCardLayout = 'tile' | 'row';
+
+/**
+ * When the overlaid play button shows.
+ *
+ * `auto` (default): on web it fades and slides in while the card is hovered or
+ * holds keyboard focus; on native it is not drawn (a tap on the card plays).
+ * Either way it stays visible while the card is `playing`, `loading` or `current`.
+ * `always`: drawn on both platforms. `never`: not drawn.
+ */
+export type MediaCardPlayButton = 'auto' | 'always' | 'never';
+
+/** One row of the card's "More options" menu. */
+export interface MediaCardMenuItem {
+  label: string;
+  onPress?: () => void;
+  /** Leading icon element. */
+  icon?: ReactNode;
+  disabled?: boolean;
+  destructive?: boolean;
+}
+
+/** The props every card that plays something shares. */
+export interface MediaCardCommonProps {
+  /** Opens the item. On web with `href` the default navigation is replaced. */
+  onPress?: () => void;
+  /** Makes the card a real link on web (`<a href>`); native opens it when there is no `onPress`. */
+  href?: string;
+  /** Plays / pauses. Without it no play button is drawn. */
+  onPlay?: () => void;
+  /** The item is playing: the play button draws pause and stays visible. */
+  playing?: boolean;
+  /** The play button shows its spinner (buffering) and stays visible. */
+  loading?: boolean;
+  /** The item is the one loaded in the player (playing or paused): the button stays visible. */
+  current?: boolean;
+  /** Default `auto`. */
+  playButton?: MediaCardPlayButton;
+  /** Rows of the "More options" menu. Also opened by a right-click (web) or a long press (native). */
+  menuItems?: ReadonlyArray<MediaCardMenuItem>;
+  /** Menu content as nodes (`DropdownMenuItem`s …) — takes precedence over `menuItems`. */
+  menu?: ReactNode;
+  /** The menu trigger's name. Default `"More options"`. */
+  menuLabel?: string;
+  /** Default `medium`. */
+  size?: MediaCardSize;
+  /** Default `tile`. */
+  layout?: MediaCardLayout;
+  /** Paints the selected wash; `aria-current` on web, `selected` state on native. */
+  selected?: boolean;
+  /** Draws the shimmering placeholder instead of the card. */
+  skeleton?: boolean;
+  /** Replaces the composed accessible name. */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+/** Props shared by the cards that draw one piece of artwork. */
+export interface MediaCardArtworkProps {
+  /** A URL, or an id the app's `ImageResolver` turns into one. */
+  artwork?: string;
+  /** Passed to the `ImageResolver` with an id. */
+  artworkVariant?: string;
+  /**
+   * The artwork's dominant colour (hex from the backend). Paints the
+   * placeholder gradient when there is no artwork; neutral without it.
+   */
+  artworkColor?: string;
+}
+
+// ---------------------------------------------------------------------------
+//  MediaCard — the shared anatomy, also usable directly
+// ---------------------------------------------------------------------------
+
+export type MediaCardArtworkShape = 'square' | 'round';
+
+export interface MediaCardProps extends MediaCardCommonProps, MediaCardArtworkProps {
+  title: string;
+  /** The first line under the title (text or nodes). */
+  subtitle?: ReactNode;
+  /** Further lines under the subtitle. */
+  meta?: ReadonlyArray<string>;
+  /** What the item is ("Album", "Podcast"), used in the accessible name. */
+  typeLabel?: string;
+  /** Default `square`. */
+  artworkShape?: MediaCardArtworkShape;
+  /** Corner radius of a square cover. Default 8 (6 at `small` and in rows). */
+  artworkRadius?: number;
+  /** Width : height of the cover. Default `1`. */
+  artworkAspectRatio?: number;
+  /** Replaces the drawn artwork (a mosaic, a generated cover). Sized by the card. */
+  renderArtwork?: (box: { width: number; height: number }) => ReactNode;
+  /** Static decoration drawn over the cover, under the play button (a date leaf). */
+  artworkOverlay?: ReactNode;
+  /** Glyph drawn on the generated placeholder cover. */
+  placeholderIcon?: React.ComponentType<{ width?: number; height?: number; fill?: string }>;
+  /** Drawn after the title on its line (an explicit badge, a verified mark). */
+  titleAccessory?: ReactNode;
+  /** Words the accessory adds to the accessible name ("Explicit", "Verified"). */
+  titleAccessoryLabel?: string;
+  /** Lines the title may take. Default 1. */
+  titleLines?: number;
+  /** Lines the subtitle may take. Default 1. */
+  subtitleLines?: number;
+  /** The subtitle holds its own pressables (artist links): it is drawn above the card link. */
+  interactiveSubtitle?: boolean;
+  /** Row layout only: between the text and the menu (duration, like button). */
+  trailing?: ReactNode;
+  /** Under the text, outside the link (progress, action buttons). Indented to the text in a row. */
+  footer?: ReactNode;
+  /** Words appended to the accessible name ("Played", "12 min left"). */
+  accessibilityDetail?: string;
+  /** Text lines are centred under the cover (tile layout). */
+  centered?: boolean;
+  /** A caption above the title ("12 Sep · 48 min"). */
+  eyebrow?: string;
+  /** Up to two lines after the meta lines. */
+  description?: string;
+  /** Drawn before the title on its line (the now-playing bars). */
+  titleLeading?: ReactNode;
+  /** Replaces the cover's width (and, through the aspect ratio, its height). */
+  artworkSize?: number;
+  /** Row layout: centre the parts vertically (default) or align them to the top. */
+  rowAlign?: 'center' | 'top';
+}
+
+// ---------------------------------------------------------------------------
+//  Typed cards
+// ---------------------------------------------------------------------------
+
+export interface SongCardArtist {
+  name: string;
+  id?: string;
+}
+
+export interface SongCardProps extends MediaCardCommonProps, MediaCardArtworkProps {
+  title: string;
+  /** Names, or `{ name, id }` — each is pressable when `onPressArtist` is set. */
+  artists?: ReadonlyArray<string | SongCardArtist>;
+  onPressArtist?: (artist: SongCardArtist, index: number) => void;
+  /** Row layout: the album, a second line after the artists. */
+  album?: string;
+  explicit?: boolean;
+  /** Pre-formatted ("3:45"). Drawn in the row layout. */
+  duration?: string;
+  /** Row layout: draws a `LikeButton`. */
+  liked?: boolean;
+  onLikedChange?: (liked: boolean) => void;
+  /** Default `"Song"`. */
+  typeLabel?: string;
+}
+
+export type AlbumCardType = 'album' | 'single' | 'ep' | 'compilation';
+
+export interface AlbumCardProps extends MediaCardCommonProps, MediaCardArtworkProps {
+  title: string;
+  artist?: string;
+  /** Pre-formatted ("2026"). */
+  year?: string;
+  /** Default `album`. */
+  albumType?: AlbumCardType;
+  /** The words for each type. Default Album / Single / EP / Compilation. */
+  typeLabels?: Partial<Record<AlbumCardType, string>>;
+  explicit?: boolean;
+}
+
+export interface ArtistCardProps extends MediaCardCommonProps, MediaCardArtworkProps {
+  name: string;
+  verified?: boolean;
+  /** Pre-formatted ("1.2M followers"). */
+  followers?: string;
+  /** Default `"Artist"`. */
+  typeLabel?: string;
+  /** Default `"Verified"`. */
+  verifiedLabel?: string;
+}
+
+export interface PlaylistCardProps extends MediaCardCommonProps, MediaCardArtworkProps {
+  title: string;
+  /** The owner's display name: "By Maya". */
+  owner?: string;
+  /** Default `"By"`. */
+  ownerPrefix?: string;
+  /** Pre-formatted ("42 songs"). */
+  trackCount?: string;
+  /** Without `artwork`: up to four track covers drawn as a 2×2 mosaic. */
+  mosaic?: ReadonlyArray<string>;
+  /** Draws the shared-playlist glyph before the owner line. */
+  collaborative?: boolean;
+  /** Default `"Collaborative"`. */
+  collaborativeLabel?: string;
+  /** Default `"Playlist"`. */
+  typeLabel?: string;
+}
+
+export interface MixCardProps extends MediaCardCommonProps {
+  title: string;
+  /** The generated cover's colour (hex). Neutral without it. */
+  artworkColor?: string;
+  /** The words drawn big on the cover. Default: `title`. */
+  coverTitle?: string;
+  /** Up to four artist photos (URLs or ids) drawn small on the cover. */
+  faces?: ReadonlyArray<string>;
+  /** Pre-formatted artists line ("Mara Vell, Juno Park and more"). */
+  description?: string;
+  /** Default `"Mix"`. */
+  typeLabel?: string;
+}
+
+export interface PodcastCardProps extends MediaCardCommonProps, MediaCardArtworkProps {
+  title: string;
+  publisher?: string;
+  /** Default `"Podcast"`. */
+  typeLabel?: string;
+}
+
+export interface EpisodeCardProps extends MediaCardCommonProps, MediaCardArtworkProps {
+  title: string;
+  /** The show's name. */
+  show?: string;
+  /** Pre-formatted ("12 Sep"). */
+  date?: string;
+  /** Pre-formatted ("48 min"). */
+  duration?: string;
+  /** Clamped to two lines. */
+  description?: string;
+  explicit?: boolean;
+  /** Listened fraction, `0..1`. Drawn as a bar when above 0 and not `played`. */
+  progress?: number;
+  /** Pre-formatted ("12 min left"), beside the bar. */
+  remaining?: string;
+  /** Finished: a check and `playedLabel` replace the bar. */
+  played?: boolean;
+  /** Default `"Played"`. */
+  playedLabel?: string;
+  /** Icon buttons after the progress (save, download). */
+  actions?: ReactNode;
+  /** Default `"Episode"`. */
+  typeLabel?: string;
+}
+
+export interface AudiobookCardProps extends MediaCardCommonProps, MediaCardArtworkProps {
+  title: string;
+  author?: string;
+  /** The narrator's name: "Narrated by Ines Calder". */
+  narrator?: string;
+  /** Default `"Narrated by"`. */
+  narratorPrefix?: string;
+  /** Pre-formatted ("11 h 20 min"). */
+  duration?: string;
+  /** Listened fraction, `0..1`. */
+  progress?: number;
+  /** Default `"Audiobook"`. */
+  typeLabel?: string;
+}
+
+export interface GenreCardProps
+  extends Pick<MediaCardCommonProps, 'onPress' | 'href' | 'size' | 'accessibilityLabel' | 'skeleton' | 'style' | 'testID'> {
+  title: string;
+  /** The tile colour (hex). Darkened as far as needed to keep the title legible. */
+  color?: string;
+  /** Artwork that peeks, rotated, from the bottom-right corner. */
+  artwork?: string;
+  artworkVariant?: string;
+}
+
+export interface EventCardProps extends MediaCardCommonProps {
+  title: string;
+  /** Pre-formatted month abbreviation ("Oct"). */
+  month: string;
+  /** Pre-formatted day ("14"). */
+  day: string;
+  /** A URL or resolver id. */
+  image?: string;
+  imageVariant?: string;
+  venue?: string;
+  city?: string;
+  /** Pre-formatted ("Fri 20:00"). */
+  time?: string;
+  /** The tickets button. */
+  action?: ReactNode;
+  soldOut?: boolean;
+  /** Default `"Sold out"`. */
+  soldOutLabel?: string;
+  /** Default `"Event"`. */
+  typeLabel?: string;
+}
+
+export interface ProfileCardProps extends MediaCardCommonProps, MediaCardArtworkProps {
+  name: string;
+  /** Adds "Follows you" to the label line. */
+  followsYou?: boolean;
+  /** Default `"Profile"`. */
+  typeLabel?: string;
+  /** Default `"Follows you"`. */
+  followsYouLabel?: string;
+  /** Pre-formatted ("214 followers"). */
+  followers?: string;
+  /** The follow button. */
+  action?: ReactNode;
+}
+
+export interface FriendActivityCardProps
+  extends Pick<
+    MediaCardCommonProps,
+    'onPress' | 'href' | 'skeleton' | 'selected' | 'accessibilityLabel' | 'style' | 'testID'
+  > {
+  name: string;
+  /** Avatar URL or resolver id. */
+  avatar?: string;
+  track: string;
+  artist: string;
+  /** Where it plays from ("Late Hours Playlist"). */
+  context?: string;
+  /** `playlist` (default) or `album` — the context line's glyph. */
+  contextType?: 'playlist' | 'album';
+  /** Listening right now: the avatar dot and moving bars replace `time`. */
+  live?: boolean;
+  /** Pre-formatted ("12 min"). */
+  time?: string;
+  /** Default `"Listening now"`. */
+  liveLabel?: string;
+}
+
+export interface QuickAccessTileProps
+  extends Pick<
+    MediaCardCommonProps,
+    | 'onPress'
+    | 'href'
+    | 'onPlay'
+    | 'playing'
+    | 'loading'
+    | 'current'
+    | 'skeleton'
+    | 'selected'
+    | 'accessibilityLabel'
+    | 'style'
+    | 'testID'
+  >,
+    MediaCardArtworkProps {
+  title: string;
+  /** Round cover (an artist). */
+  round?: boolean;
+  /** What the item is, for the accessible name. */
+  typeLabel?: string;
+}
+
+export interface RecapHighlight {
+  /** "Top artist". */
+  label: string;
+  title: string;
+  artwork?: string;
+  round?: boolean;
+}
+
+export interface RecapCardProps {
+  /** "Your 2026 in sound". */
+  eyebrow?: string;
+  /** The big number, pre-formatted ("48,210"). */
+  value: string;
+  /** "minutes listened". */
+  unit?: string;
+  /** Hex the gradient is built from. Neutral without it. */
+  artworkColor?: string;
+  highlights?: ReadonlyArray<RecapHighlight>;
+  onShare?: () => void;
+  /** Default `"Share"`. */
+  shareLabel?: string;
+  skeleton?: boolean;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+export interface ShareCardProps extends MediaCardArtworkProps {
+  title: string;
+  artist: string;
+  /** Lines of a lyrics excerpt, drawn in a block under the title. */
+  lyrics?: ReadonlyArray<string>;
+  /** Under everything (a small wordmark, a link). */
+  footer?: ReactNode;
+  explicit?: boolean;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}

package/src/media-controls/ExplicitBadge.tsx

@@ -0,0 +1,73 @@
+import React, { memo, useMemo } from 'react';
+import { View } from 'react-native';
+
+import { useTheme } from '../theme/use-theme';
+import { Text } from '../typography';
+import type { TypeScaleVariant } from '../typography/scale';
+import { resolveMediaControlsPaint } from './shared';
+import type { ExplicitBadgeProps, ExplicitBadgeSize } from './types';
+
+/**
+ * The small square "E" beside a track title.
+ *
+ *            square   radius   letter
+ *   small    14       2        caption-2-bold (line height 14)
+ *   medium   16       3        caption-2-bold
+ *
+ * Fill neutral-500 (dark neutral-400), letter in the page background colour.
+ * Square rather than a pill: it is a mark, not a button-like badge.
+ *
+ * Accessibility: one `img` named by `label` ("Explicit"); the drawn letter is
+ * hidden so the name is not announced as "E".
+ */
+
+const SIZE_CONFIG: Record<ExplicitBadgeSize, { box: number; radius: number; type: TypeScaleVariant }> = {
+  small: { box: 14, radius: 2, type: 'caption-2-bold' },
+  medium: { box: 16, radius: 3, type: 'caption-2-bold' },
+};
+
+function ExplicitBadgeComponent({
+  size = 'medium',
+  letter = 'E',
+  label = 'Explicit',
+  style,
+  testID,
+}: ExplicitBadgeProps) {
+  const theme = useTheme();
+  const paint = useMemo(() => resolveMediaControlsPaint(theme), [theme]);
+  const { box, radius, type } = SIZE_CONFIG[size];
+
+  return (
+    <View
+      role="img"
+      accessibilityLabel={label}
+      style={[
+        {
+          width: box,
+          height: box,
+          borderRadius: radius,
+          backgroundColor: paint.badge,
+          alignItems: 'center',
+          justifyContent: 'center',
+          flexShrink: 0,
+        },
+        style,
+      ]}
+      testID={testID}
+    >
+      <Text
+        variant={type}
+        importantForAccessibility="no"
+        accessibilityElementsHidden
+        aria-hidden
+        numberOfLines={1}
+        style={{ color: paint.onBadge, lineHeight: box, letterSpacing: 0 }}
+      >
+        {letter}
+      </Text>
+    </View>
+  );
+}
+
+export const ExplicitBadge = memo(ExplicitBadgeComponent);
+ExplicitBadge.displayName = 'ExplicitBadge';

package/src/media-controls/LikeButton.tsx

@@ -0,0 +1,109 @@
+import React, { memo, useEffect, useMemo, useState } from 'react';
+import { Pressable, View, type GestureResponderEvent } from 'react-native';
+
+import { webDataSet } from '../checkbox/shared';
+import { RiHeart3Fill } from '../icons/remix/RiHeart3Fill';
+import { RiHeart3Line } from '../icons/remix/RiHeart3Line';
+import { adoptStyleSheet } from '../styles/adopt-style-sheet';
+import { borderRadius } from '../styles/tokens';
+import type { WebCssStyle } from '../styles/web-view-style';
+import { useTheme } from '../theme/use-theme';
+import {
+  IS_WEB,
+  MEDIA_CONTROLS_CSS,
+  MEDIA_CONTROLS_STYLE_ID,
+  resolveMediaControlsPaint,
+} from './shared';
+import type { LikeButtonProps, LikeButtonSize } from './types';
+
+/**
+ * The heart that saves a track, album or playlist to the library.
+ *
+ *            glyph   hit area
+ *   small    16      32
+ *   medium   20      32
+ *   large    24      40
+ *
+ *   rest    outline heart, muted neutral; hover: the text colour
+ *   liked   filled heart in the theme accent (or `activeColor`)
+ *
+ * Colour change only — no scale, no bounce.
+ *
+ * Accessibility: a toggle button, so it carries its state in both spellings —
+ * `aria-pressed` for web and `accessibilityState.selected` for native (React
+ * Native has no pressed state). The NAME says what pressing does ("Save to Your
+ * Library" / "Remove from Your Library"). The press does not reach a pressable
+ * row behind it.
+ */
+
+const SIZE_CONFIG: Record<LikeButtonSize, { glyph: number; box: number }> = {
+  small: { glyph: 16, box: 32 },
+  medium: { glyph: 20, box: 32 },
+  large: { glyph: 24, box: 40 },
+};
+
+function LikeButtonComponent({
+  liked,
+  onLikedChange,
+  size = 'medium',
+  activeColor,
+  disabled = false,
+  accessibilityLabel = 'Save to Your Library',
+  style,
+  testID,
+}: LikeButtonProps) {
+  const theme = useTheme();
+  useEffect(() => {
+    adoptStyleSheet(MEDIA_CONTROLS_STYLE_ID, MEDIA_CONTROLS_CSS);
+  }, []);
+  const paint = useMemo(() => resolveMediaControlsPaint(theme), [theme]);
+  const [hovered, setHovered] = useState(false);
+  const { glyph, box } = SIZE_CONFIG[size];
+
+  const color = liked
+    ? (activeColor ?? paint.accent)
+    : hovered && !disabled
+      ? paint.text
+      : paint.textMuted;
+  const Glyph = liked ? RiHeart3Fill : RiHeart3Line;
+
+  const rootStyle: WebCssStyle = {
+    width: box,
+    height: box,
+    borderRadius: borderRadius.full,
+    alignItems: 'center',
+    justifyContent: 'center',
+    opacity: disabled ? 0.5 : 1,
+    '--bloom-media-ring': paint.ring,
+  };
+
+  return (
+    <Pressable
+      {...webDataSet({ bloomMediaFocusable: '', bloomLikeButton: liked ? 'liked' : '' })}
+      role="button"
+      accessibilityLabel={accessibilityLabel}
+      aria-pressed={liked}
+      accessibilityState={{ selected: liked, disabled }}
+      aria-disabled={disabled || undefined}
+      disabled={disabled}
+      onHoverIn={() => setHovered(true)}
+      onHoverOut={() => setHovered(false)}
+      onPress={(event: GestureResponderEvent) => {
+        if (IS_WEB) {
+          event.preventDefault?.();
+          event.stopPropagation?.();
+        }
+        onLikedChange(!liked);
+      }}
+      style={[rootStyle, style]}
+      testID={testID}
+    >
+      <View pointerEvents="none" style={{ width: glyph, height: glyph }}>
+        <Glyph width={glyph} height={glyph} fill={color} />
+      </View>
+    </Pressable>
+  );
+}
+
+export const LikeButton = memo(LikeButtonComponent);
+LikeButton.displayName = 'LikeButton';