@birdycom/omniaui-react 0.0.0-stage → 0.11.0

package/src/components/Heading.tsx

@@ -0,0 +1,27 @@
+import { forwardRef } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface HeadingProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+  title: ReactNode;
+  description?: ReactNode;
+  /** Heading element level (default 2). */
+  level?: 1 | 2 | 3 | 4;
+  /** `sm` = section heading. */
+  size?: "md" | "sm";
+  titleId?: string;
+}
+
+/** `<div class="oc-heading">` title + muted description. */
+export const Heading = forwardRef<HTMLDivElement, HeadingProps>(function Heading(
+  { title, description, level = 2, size = "md", titleId, className, ...rest },
+  ref,
+) {
+  const Tag = `h${level}` as "h2";
+  return (
+    <div ref={ref} className={cx("oc-heading", size === "sm" && "oc-heading--sm", className)} {...rest}>
+      <Tag className="oc-heading-title" id={titleId}>{title}</Tag>
+      {description != null && <p className="oc-heading-description">{description}</p>}
+    </div>
+  );
+});

package/src/components/Icon.tsx

@@ -0,0 +1,25 @@
+import type { SVGProps } from "react";
+
+export interface IconProps extends Omit<SVGProps<SVGSVGElement>, "d"> {
+  /** SVG path data (24x24 viewBox, stroke icon). Use `children` for several shapes. */
+  d?: string;
+}
+
+/** Inline 24x24 stroke icon (`currentColor`), the shape used by the snippets. */
+export function Icon({ d, children, className, ...rest }: IconProps) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      {...rest}
+    >
+      {d ? <path d={d} /> : children}
+    </svg>
+  );
+}

package/src/components/ImageZoom.tsx

@@ -0,0 +1,51 @@
+// File: packages/react/src/components/ImageZoom.tsx
+// Map: props -> ImageZoom (toolbar of radio levels -> viewport -> canvas with the image)
+// Same markup as packages/ui/snippets/image-zoom.html. The chosen level is also written to --oc-zoom,
+// so any number works (the CSS-only :has() rules cover 1, 1.5, 2, 3 and 4).
+"use client";
+
+import { forwardRef, useId, useState } from "react";
+import type { CSSProperties, HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface ImageZoomProps extends HTMLAttributes<HTMLDivElement> {
+  src?: string;
+  alt?: string;
+  /** Zoom levels for the toolbar. Empty array = no toolbar. Default [1, 1.5, 2, 3]. */
+  levels?: number[];
+  /** Starting level. Default 1. */
+  defaultZoom?: number;
+  /** Window ratio: "square", "photo" or a CSS ratio such as "21 / 9". Default 16 / 9. */
+  ratio?: "square" | "photo" | string;
+  /** Replaces the <img> inside the canvas (svg, video, placeholder art). */
+  media?: ReactNode;
+}
+
+/** `.oc-image-zoom`: zoom by making the canvas wider than the viewport; pan by scrolling. */
+export const ImageZoom = forwardRef<HTMLDivElement, ImageZoomProps>(function ImageZoom(
+  { src, alt = "", levels = [1, 1.5, 2, 3], defaultZoom = 1, ratio, media, className, style, ...rest },
+  ref,
+) {
+  const name = `oc-zoom-${useId().replace(/:/g, "")}`;
+  const [zoom, setZoom] = useState(defaultZoom);
+  const preset = ratio === "square" || ratio === "photo" ? ratio : undefined;
+  const vars = { "--oc-zoom": String(zoom), ...(ratio && !preset ? { "--oc-image-zoom-ratio": ratio } : {}) } as CSSProperties;
+  return (
+    <div ref={ref} className={cx("oc-image-zoom", preset && `oc-image-zoom--${preset}`, className)} style={{ ...vars, ...style }} {...rest}>
+      {levels.length > 0 && (
+        <div className="oc-image-zoom__toolbar" role="radiogroup" aria-label="Zoom level">
+          <span className="oc-image-zoom__label">Zoom</span>
+          {levels.map((l) => (
+            <label key={l} className="oc-image-zoom__level">
+              <input type="radio" name={name} value={String(l)} checked={zoom === l} onChange={() => setZoom(l)} />
+              {Math.round(l * 100)}%
+            </label>
+          ))}
+        </div>
+      )}
+      <div className="oc-image-zoom__viewport" tabIndex={0} role="region" aria-label={alt ? `${alt}, scroll to pan` : "Scroll to pan"}>
+        <div className="oc-image-zoom__canvas">{media ?? (src ? <img src={src} alt={alt} /> : <div className="oc-media-art" role="img" aria-label={alt} />)}</div>
+      </div>
+    </div>
+  );
+});

package/src/components/Input.tsx

@@ -0,0 +1,21 @@
+import { forwardRef } from "react";
+import type { InputHTMLAttributes } from "react";
+import { cx } from "../utils";
+
+export interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+  /** Error state: adds `oc-input--error` and `aria-invalid`. */
+  error?: boolean;
+}
+
+/** `<input class="oc-input">` */
+export const Input = forwardRef<HTMLInputElement, InputProps>(function Input({ error, className, type = "text", ...rest }, ref) {
+  return (
+    <input
+      ref={ref}
+      type={type}
+      className={cx("oc-input", error && "oc-input--error", className)}
+      aria-invalid={error ? true : rest["aria-invalid"]}
+      {...rest}
+    />
+  );
+});

package/src/components/InputGroup.tsx

@@ -0,0 +1,24 @@
+import { forwardRef } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface InputGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, "prefix"> {
+  /** Addon before the input (currency sign...). */
+  prefix?: ReactNode;
+  /** Addon after the input (%, unit...). */
+  suffix?: ReactNode;
+}
+
+/** `<div class="oc-input-group">` with `oc-input-addon` spans around the child `<Input>`. */
+export const InputGroup = forwardRef<HTMLDivElement, InputGroupProps>(function InputGroup(
+  { prefix, suffix, className, children, ...rest },
+  ref,
+) {
+  return (
+    <div ref={ref} className={cx("oc-input-group", className)} {...rest}>
+      {prefix != null && <span className="oc-input-addon">{prefix}</span>}
+      {children}
+      {suffix != null && <span className="oc-input-addon">{suffix}</span>}
+    </div>
+  );
+});

package/src/components/LanguageSelect.tsx

@@ -0,0 +1,64 @@
+// File: packages/react/src/components/LanguageSelect.tsx
+// Map: types -> globe icon -> component (label pill: icon + native select)
+// Same markup as packages/ui/snippets/language-select.html. The app decides what "change" does.
+"use client";
+
+import { forwardRef } from "react";
+import type { ReactNode, SelectHTMLAttributes } from "react";
+import { cx } from "../utils";
+import { useControllable } from "../hooks";
+
+export interface LanguageSelectOption {
+  value: string;
+  label: string;
+}
+
+export interface LanguageSelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, "value" | "defaultValue" | "onChange"> {
+  options: LanguageSelectOption[];
+  value?: string;
+  defaultValue?: string;
+  onChange?: (value: string) => void;
+  /** Currency look (symbol in primary color). */
+  currency?: boolean;
+  /** No frame until hover / focus. */
+  ghost?: boolean;
+  /** Replaces the globe icon (e.g. "€"). */
+  icon?: ReactNode;
+  /** Class for the wrapping label (`className` goes to the select). */
+  labelClassName?: string;
+}
+
+/** Small globe drawn with currentColor. */
+const Globe = () => (
+  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <circle cx="12" cy="12" r="9" />
+    <path d="M3 12h18M12 3a14 14 0 0 1 0 18M12 3a14 14 0 0 0 0 18" />
+  </svg>
+);
+
+/** `.oc-language-select`: native select in a pill with a leading icon. */
+export const LanguageSelect = forwardRef<HTMLSelectElement, LanguageSelectProps>(function LanguageSelect(
+  { options, value, defaultValue, onChange, currency, ghost, icon, labelClassName, className, ...rest },
+  ref,
+) {
+  const [current, setCurrent] = useControllable<string>(value, defaultValue ?? options[0]?.value ?? "", onChange);
+  return (
+    <label className={cx("oc-language-select", ghost && "oc-language-select--ghost", currency && "oc-language-select--currency", labelClassName)}>
+      <span className="oc-language-select-icon" aria-hidden="true">{icon ?? (currency ? "\u20AC" : <Globe />)}</span>
+      <select
+        ref={ref}
+        className={cx("oc-language-select-control", className)}
+        aria-label={currency ? "Currency" : "Language"}
+        value={current}
+        onChange={(e) => setCurrent(e.target.value)}
+        {...rest}
+      >
+        {options.map((o) => (
+          <option key={o.value} value={o.value}>
+            {o.label}
+          </option>
+        ))}
+      </select>
+    </label>
+  );
+});

package/src/components/LauncherCard.tsx

@@ -0,0 +1,50 @@
+import { forwardRef } from "react";
+import type { AnchorHTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface LauncherCardProps extends Omit<AnchorHTMLAttributes<HTMLElement>, "title"> {
+  /** Tinted icon tile content (inline SVG). */
+  icon?: ReactNode;
+  title: ReactNode;
+  /** Trailing badge inside the title. */
+  badge?: ReactNode;
+  description?: ReactNode;
+  /** Footer text, e.g. why the card is disabled. */
+  footer?: ReactNode;
+  /** Current card (`aria-current="true"`). */
+  active?: boolean;
+  /** Not clickable (`aria-disabled`); renders a <span>. */
+  disabled?: boolean;
+}
+
+/** `.oc-launcher`: an `<a>` (with `href`), a `<button>` (with `onClick`), or a `<span>` when disabled. */
+export const LauncherCard = forwardRef<HTMLElement, LauncherCardProps>(function LauncherCard(
+  { icon, title, badge, description, footer, active, disabled, className, href, onClick, ...rest },
+  ref,
+) {
+  const content = (
+    <>
+      {icon != null && <span className="oc-launcher-icon" aria-hidden="true">{icon}</span>}
+      <h3 className="oc-launcher-title">{title}{badge != null && <> {badge}</>}</h3>
+      {description != null && <p className="oc-launcher-description">{description}</p>}
+      {footer != null && <span className="oc-launcher-footer">{footer}</span>}
+    </>
+  );
+  const cls = cx("oc-launcher", className);
+  const common = { className: cls, "aria-current": active ? ("true" as const) : undefined };
+  if (disabled) {
+    return <span ref={ref} {...common} aria-disabled="true">{content}</span>;
+  }
+  if (href === undefined && onClick) {
+    return (
+      <button ref={ref as React.Ref<HTMLButtonElement>} type="button" {...common} onClick={onClick as never}>
+        {content}
+      </button>
+    );
+  }
+  return (
+    <a ref={ref as React.Ref<HTMLAnchorElement>} href={href} {...common} onClick={onClick} {...rest}>
+      {content}
+    </a>
+  );
+});

package/src/components/Lightbox.tsx

@@ -0,0 +1,83 @@
+// File: packages/react/src/components/Lightbox.tsx
+// Map: types -> Lightbox (thumbnails + <dialog> with a snap track of slides) -> jump-to-slide effect
+// Same markup as packages/ui/snippets/lightbox.html. Prev / next stay plain anchor links (no JS needed);
+// React only opens the dialog and scrolls to the clicked photo.
+"use client";
+
+import { forwardRef, useEffect, useId, useRef, useState } from "react";
+import type { DialogHTMLAttributes, ReactNode } from "react";
+import { attrs, cx } from "../utils";
+import { useDialog, useMergedRef } from "../hooks";
+import type { DialogState } from "../hooks";
+
+export interface LightboxImage {
+  /** Image URL. Leave empty to show placeholder art (`.oc-media-art`). */
+  src?: string;
+  alt: string;
+  caption?: ReactNode;
+  /** Smaller image for the thumbnail (defaults to `src`). */
+  thumb?: string;
+}
+
+export interface LightboxProps extends Omit<DialogHTMLAttributes<HTMLDialogElement>, "title" | "open" | "onClose">, DialogState {
+  images: LightboxImage[];
+  /** Text in the top bar (`oc-lightbox__title`). */
+  title?: ReactNode;
+  /** Render the thumbnail grid that opens the viewer. Default true. */
+  thumbnails?: boolean;
+}
+
+const media = (img: LightboxImage, src?: string) =>
+  src ? <img src={src} alt={img.alt} /> : <span className="oc-media-art" role="img" aria-label={img.alt} />;
+
+/** `.oc-lightbox-thumbs` + `<dialog class="oc-lightbox">`. Controlled with `open` / `onOpenChange`, or uncontrolled. */
+export const Lightbox = forwardRef<HTMLDialogElement, LightboxProps>(function Lightbox(
+  { images, title, thumbnails = true, open, defaultOpen, onOpenChange, className, "aria-label": label = "Photo viewer", ...rest },
+  forwardedRef,
+) {
+  const inner = useRef<HTMLDialogElement>(null);
+  const ref = useMergedRef(inner, forwardedRef);
+  const base = `oc-lightbox-${useId().replace(/:/g, "")}`;
+  const [start, setStart] = useState(0);
+  const dlg = useDialog(inner, { open, defaultOpen, onOpenChange });
+  const single = images.length === 1;
+  const slideId = (i: number) => `${base}-${((i % images.length) + images.length) % images.length + 1}`;
+
+  // After opening: jump (without animation) to the photo that was clicked.
+  useEffect(() => {
+    if (dlg.open) document.getElementById(slideId(start))?.scrollIntoView?.({ behavior: "instant" as ScrollBehavior, block: "nearest", inline: "center" });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [dlg.open, start]);
+
+  return (
+    <>
+      {thumbnails && (
+        <div className="oc-lightbox-thumbs">
+          {images.map((img, i) => (
+            <button key={i} type="button" className="oc-lightbox-thumb" aria-label={`Open photo ${i + 1}: ${img.alt}`} onClick={() => { setStart(i); dlg.setOpen(true); }}>
+              {media(img, img.thumb ?? img.src)}
+            </button>
+          ))}
+        </div>
+      )}
+      <dialog ref={ref} className={cx("oc-lightbox", single && "oc-lightbox--single", className)} aria-label={label} {...attrs({ closedby: "any" })} {...rest} onClose={dlg.onClose}>
+        <div className="oc-lightbox__bar">
+          {title != null ? <h2 className="oc-lightbox__title">{title}</h2> : <span />}
+          <button type="button" className="oc-lightbox__close" aria-label="Close" onClick={dlg.close}>&#10005;</button>
+        </div>
+        <div className="oc-lightbox__track" tabIndex={0} aria-label="Photos, use the arrow keys">
+          {images.map((img, i) => (
+            <figure key={i} className="oc-lightbox__slide" id={slideId(i)}>
+              <div className="oc-lightbox__media">{media(img, img.src)}</div>
+              {!single && <a className="oc-lightbox__nav oc-lightbox__nav--prev" href={`#${slideId(i - 1)}`} aria-label="Previous photo">&#8592;</a>}
+              {!single && <a className="oc-lightbox__nav oc-lightbox__nav--next" href={`#${slideId(i + 1)}`} aria-label="Next photo">&#8594;</a>}
+              <figcaption className="oc-lightbox__caption">
+                {!single && <span className="oc-lightbox__counter">{i + 1} / {images.length}</span>} {img.caption ?? img.alt}
+              </figcaption>
+            </figure>
+          ))}
+        </div>
+      </dialog>
+    </>
+  );
+});

package/src/components/LinkArrow.tsx

@@ -0,0 +1,27 @@
+// File: packages/react/src/components/LinkArrow.tsx | Map: types -> LinkArrow (a.oc-link-arrow + modifiers)
+import { forwardRef } from "react";
+import type { AnchorHTMLAttributes } from "react";
+import { cx } from "../utils";
+
+export type LinkArrowDirection = "forward" | "back" | "external";
+
+export interface LinkArrowProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  direction?: LinkArrowDirection;
+  tone?: "default" | "accent" | "muted";
+  size?: "sm" | "default" | "lg";
+}
+
+/** `<a class="oc-link-arrow">`: text link with an arrow that moves on hover and focus. */
+export const LinkArrow = forwardRef<HTMLAnchorElement, LinkArrowProps>(function LinkArrow(
+  { direction = "forward", tone = "default", size = "default", className, ...rest },
+  ref,
+) {
+  const classes = cx(
+    "oc-link-arrow",
+    direction !== "forward" && `oc-link-arrow--${direction}`,
+    tone !== "default" && `oc-link-arrow--${tone}`,
+    size !== "default" && `oc-link-arrow--${size}`,
+    className,
+  );
+  return <a ref={ref} className={classes} {...rest} />;
+});

package/src/components/ListToolbar.tsx

@@ -0,0 +1,67 @@
+// File: packages/react/src/components/ListToolbar.tsx
+// Map: ListToolbar = toolbar row -> search -> count -> spacer -> view radios -> actions
+// The view toggle is a radio group. In React you usually render only the active view yourself
+// (use `view` + `onViewChange`); the CSS-only `.oc-list-toolbar-scope` switch also works.
+"use client";
+
+import { forwardRef, useId } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+import { useControllable } from "../hooks";
+
+export interface ListToolbarView {
+  /** "cards", "table" or "list" (matches `.oc-list-toolbar-panel[data-view]`). */
+  value: string;
+  label: string;
+  icon: ReactNode;
+}
+
+export interface ListToolbarProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+  /** Search area content, e.g. `<input class="oc-input" type="search">`. */
+  search?: ReactNode;
+  /** Result count text, e.g. "3 items". */
+  count?: ReactNode;
+  views?: ListToolbarView[];
+  view?: string;
+  defaultView?: string;
+  onViewChange?: (view: string) => void;
+  viewsLabel?: string;
+  actions?: ReactNode;
+  sticky?: boolean;
+  bordered?: boolean;
+}
+
+/** `.oc-list-toolbar`: search, count, view toggle and actions above a list. */
+export const ListToolbar = forwardRef<HTMLDivElement, ListToolbarProps>(function ListToolbar(
+  { search, count, views, view, defaultView, onViewChange, viewsLabel = "View", actions, sticky, bordered, className, ...rest },
+  ref,
+) {
+  const name = `oc-list-view-${useId().replace(/:/g, "")}`;
+  const [current, setCurrent] = useControllable(view, defaultView ?? views?.[0]?.value ?? "", onViewChange);
+  const cls = cx("oc-list-toolbar", sticky && "oc-list-toolbar--sticky", bordered && "oc-list-toolbar--bordered", className);
+  return (
+    <div ref={ref} className={cls} role="toolbar" {...rest}>
+      {search != null && <div className="oc-list-toolbar-search">{search}</div>}
+      {count != null && <span className="oc-list-toolbar-count">{count}</span>}
+      <span className="oc-list-toolbar-spacer" />
+      {views && views.length > 0 && (
+        <div className="oc-list-toolbar-views" role="radiogroup" aria-label={viewsLabel}>
+          {views.map((v) => (
+            <label className="oc-list-toolbar-view" title={v.label} key={v.value}>
+              <input
+                type="radio"
+                name={name}
+                value={v.value}
+                aria-label={v.label}
+                checked={current === v.value}
+                onChange={() => setCurrent(v.value)}
+              />
+              {v.icon}
+            </label>
+          ))}
+        </div>
+      )}
+      {actions != null && <div className="oc-list-toolbar-actions">{actions}</div>}
+    </div>
+  );
+});

package/src/components/Marquee.tsx

@@ -0,0 +1,38 @@
+// File: packages/react/src/components/Marquee.tsx | Map: props -> Marquee (track with items + aria-hidden copy)
+import { forwardRef } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface MarqueeProps extends HTMLAttributes<HTMLDivElement> {
+  /** Items of the strip. They are rendered twice; the copy is aria-hidden. */
+  items: ReactNode[];
+  reverse?: boolean;
+  speed?: "default" | "slow" | "fast";
+  /** Text only, no pills. */
+  plain?: boolean;
+  /** No soft fade at the edges. */
+  noFade?: boolean;
+}
+
+/** `.oc-marquee`: endless strip that pauses on hover / focus and stands still with reduced motion. */
+export const Marquee = forwardRef<HTMLDivElement, MarqueeProps>(function Marquee(
+  { items, reverse = false, speed = "default", plain = false, noFade = false, className, ...rest },
+  ref,
+) {
+  const classes = cx(
+    "oc-marquee",
+    reverse && "oc-marquee--reverse",
+    speed !== "default" && `oc-marquee--${speed}`,
+    plain && "oc-marquee--plain",
+    noFade && "oc-marquee--no-fade",
+    className,
+  );
+  return (
+    <div ref={ref} className={classes} {...rest}>
+      <div className="oc-marquee__track">
+        {items.map((item, i) => <span className="oc-marquee__item" key={i}>{item}</span>)}
+        {items.map((item, i) => <span className="oc-marquee__item" aria-hidden="true" key={`copy-${i}`}>{item}</span>)}
+      </div>
+    </div>
+  );
+});

package/src/components/MediaCard.tsx

@@ -0,0 +1,47 @@
+// File: packages/react/src/components/MediaCard.tsx
+// Map: props -> MediaCard (MediaThumb -> body: avatar, title link + meta, menu button -> popover menu)
+// Same markup as packages/ui/snippets/media-card.html.
+import { forwardRef, useId } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { attrs, cx } from "../utils";
+import { MediaThumb } from "./MediaThumb";
+import type { MediaThumbProps } from "./MediaThumb";
+
+export interface MediaCardProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+  title: ReactNode;
+  /** Link of the title; it covers the whole card. */
+  href: string;
+  /** "Channel · 24K views · 3 days ago". */
+  meta?: ReactNode;
+  /** Initials, an <img>, or any node. Leave out for no avatar. */
+  avatar?: ReactNode;
+  /** Props for the MediaThumb on top (src, duration, progress, …). */
+  thumb?: MediaThumbProps;
+  /** Items of the ⋮ menu (`.oc-dropdown-item` elements). No menu button when empty. */
+  menu?: ReactNode;
+  compact?: boolean;
+}
+
+/** `article.oc-media-card`. */
+export const MediaCard = forwardRef<HTMLElement, MediaCardProps>(function MediaCard(
+  { title, href, meta, avatar, thumb, menu, compact, className, ...rest },
+  ref,
+) {
+  const menuId = `oc-media-card-menu-${useId().replace(/:/g, "")}`;
+  return (
+    <article ref={ref} className={cx("oc-media-card", compact && "oc-media-card--compact", className)} {...rest}>
+      <MediaThumb {...thumb} />
+      <div className="oc-media-card__body">
+        {avatar != null && <span className="oc-media-card__avatar" aria-hidden="true">{avatar}</span>}
+        <div className="oc-media-card__text">
+          <h3 className="oc-media-card__title"><a href={href}>{title}</a></h3>
+          {meta != null && <p className="oc-media-card__meta">{meta}</p>}
+        </div>
+        {menu != null && (
+          <button type="button" className="oc-media-card__menu" aria-label="More actions" {...attrs({ popovertarget: menuId })}>&#8942;</button>
+        )}
+      </div>
+      {menu != null && <div className="oc-dropdown-menu" id={menuId} {...attrs({ popover: "" })}>{menu}</div>}
+    </article>
+  );
+});

package/src/components/MediaRow.tsx

@@ -0,0 +1,53 @@
+// File: packages/react/src/components/MediaRow.tsx
+// Map: MediaRowList (ul / ol, numbered) -> MediaRow (MediaThumb -> title link + meta -> menu button + popover)
+// Same markup as packages/ui/snippets/media-row.html.
+import { forwardRef, useId } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { attrs, cx } from "../utils";
+import { MediaThumb } from "./MediaThumb";
+import type { MediaThumbProps } from "./MediaThumb";
+
+export interface MediaRowListProps extends HTMLAttributes<HTMLElement> {
+  /** Numbered playlist: renders an <ol> with a counter column. */
+  numbered?: boolean;
+}
+
+/** `ul.oc-media-row-list` or `ol.oc-media-row-list--numbered`. */
+export const MediaRowList = forwardRef<HTMLElement, MediaRowListProps>(function MediaRowList({ numbered, className, ...rest }, ref) {
+  const Tag = (numbered ? "ol" : "ul") as "ul";
+  return <Tag ref={ref as React.Ref<HTMLUListElement>} className={cx("oc-media-row-list", numbered && "oc-media-row-list--numbered", className)} {...(rest as HTMLAttributes<HTMLUListElement>)} />;
+});
+
+export interface MediaRowProps extends Omit<HTMLAttributes<HTMLLIElement>, "title"> {
+  title: ReactNode;
+  href: string;
+  meta?: ReactNode;
+  thumb?: MediaThumbProps;
+  /** Now playing (`aria-current="true"`). */
+  current?: boolean;
+  /** Items of the ⋮ menu. No menu button when empty. */
+  menu?: ReactNode;
+}
+
+/** `li.oc-media-row`: thumb | title + meta | menu. */
+export const MediaRow = forwardRef<HTMLLIElement, MediaRowProps>(function MediaRow(
+  { title, href, meta, thumb, current, menu, className, ...rest },
+  ref,
+) {
+  const menuId = `oc-media-row-menu-${useId().replace(/:/g, "")}`;
+  return (
+    <li ref={ref} className={cx("oc-media-row", className)} aria-current={current ? "true" : undefined} {...rest}>
+      <MediaThumb {...thumb} />
+      <div className="oc-media-row__text">
+        <h3 className="oc-media-row__title"><a href={href}>{title}</a></h3>
+        {meta != null && <p className="oc-media-row__meta">{meta}</p>}
+      </div>
+      {menu != null && (
+        <>
+          <button type="button" className="oc-media-row__menu" aria-label="More actions" {...attrs({ popovertarget: menuId })}>&#8942;</button>
+          <div className="oc-dropdown-menu" id={menuId} {...attrs({ popover: "" })}>{menu}</div>
+        </>
+      )}
+    </li>
+  );
+});

package/src/components/MediaThumb.tsx

@@ -0,0 +1,49 @@
+// File: packages/react/src/components/MediaThumb.tsx
+// Map: props -> MediaThumb (<a> or <div> -> picture -> badge -> duration -> progress)
+// Same markup as packages/ui/snippets/media-thumb.html.
+import { forwardRef } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface MediaThumbProps extends HTMLAttributes<HTMLElement> {
+  /** Picture URL. Empty = placeholder art (`.oc-media-art`, pick a variant with `art`). */
+  src?: string;
+  alt?: string;
+  /** Placeholder art variant 1-6 (only without `src`). */
+  art?: number;
+  /** Renders an <a> when set. */
+  href?: string;
+  /** "12:04" in the bottom-right corner. */
+  duration?: ReactNode;
+  /** Top-left label ("New", "LIVE"). */
+  badge?: ReactNode;
+  live?: boolean;
+  /** Watched part, 0-100. Shows the progress bar when set. */
+  progress?: number;
+  watched?: boolean;
+  ratio?: "video" | "square" | "portrait";
+}
+
+/** `.oc-media-thumb`: 16:9 video thumbnail. */
+export const MediaThumb = forwardRef<HTMLElement, MediaThumbProps>(function MediaThumb(
+  { src, alt = "", art, href, duration, badge, live, progress, watched, ratio = "video", className, children, ...rest },
+  ref,
+) {
+  const Tag = (href ? "a" : "div") as "a";
+  return (
+    <Tag
+      ref={ref as React.Ref<HTMLAnchorElement>}
+      href={href}
+      className={cx("oc-media-thumb", ratio !== "video" && `oc-media-thumb--${ratio}`, watched && "is-watched", className)}
+      {...(rest as HTMLAttributes<HTMLAnchorElement>)}
+    >
+      {src ? <img src={src} alt={alt} /> : <div className={cx("oc-media-art", art != null && art > 1 && `oc-media-art--${art}`)} />}
+      {badge != null && <span className={cx("oc-media-thumb__badge", live && "oc-media-thumb__badge--live")}>{badge}</span>}
+      {duration != null && <span className="oc-media-thumb__duration">{duration}</span>}
+      {progress != null && (
+        <progress className="oc-media-thumb__progress" value={progress} max={100} aria-label={`Watched ${progress}%`}>{progress}%</progress>
+      )}
+      {children}
+    </Tag>
+  );
+});