sonahang-ui 1.0.3 → 1.0.5

package/README.md

@@ -88,6 +88,8 @@ Navigation: `Tabs`, `Breadcrumb`, `Pagination`, `Stepper`, `Accordion`
 
 Data display: `Avatar`, `Tag`, `Chip`, `Carousel`
 
+Media: `AudioPlayer`, `AudioPlaylist`
+
 Every component, every prop, and every state is documented with live controls
 in [Storybook](https://github.com/sonangrai/sonahang-ui) — that's the real
 reference, this file is the summary.

package/dist/components/AudioPlayer/AudioPlayer.d.ts

@@ -0,0 +1,48 @@
+import type { AudioHTMLAttributes, ReactNode, Ref } from "react";
+import "./AudioPlayer.css";
+export type AudioPlayerLabels = {
+    play?: string;
+    pause?: string;
+    previous?: string;
+    next?: string;
+    seek?: string;
+    mute?: string;
+    unmute?: string;
+    volume?: string;
+    /** Shown in place of the controls when the source fails to load. */
+    error?: string;
+};
+export type AudioPlayerProps = {
+    /** URL of the audio file. */
+    src: string;
+    /** Track name, shown above the controls. Also names the player region. */
+    title?: ReactNode;
+    /** Secondary line under the title — an artist, show, or episode. */
+    subtitle?: ReactNode;
+    /** Hides the volume controls, e.g. where the OS volume is all that matters. */
+    hideVolume?: boolean;
+    /** Initial volume, 0–1. Defaults to 1. */
+    defaultVolume?: number;
+    /** Accessible names for the controls — override to localise. */
+    labels?: AudioPlayerLabels;
+    /** Renders a Previous button beside Play. Omit for a single track. */
+    onPrevious?: () => void;
+    /** Renders a Next button beside Play. Omit for a single track. */
+    onNext?: () => void;
+    /** Extra controls, placed in the control row before the volume. */
+    actions?: ReactNode;
+    /** Class for the wrapper element. */
+    className?: string;
+    /** Ref to the underlying `<audio>` element, for imperative control. */
+    ref?: Ref<HTMLAudioElement>;
+} & Omit<AudioHTMLAttributes<HTMLAudioElement>, "src" | "title" | "className" | "controls">;
+/**
+ * Custom controls over a native `<audio>` element.
+ *
+ * The element stays the source of truth: playing, position, and volume are
+ * read back from its media events rather than tracked alongside it, so the UI
+ * can't drift from what's actually playing — even when something else drives
+ * the element through `ref`. The seek and volume bars are `RangeSlider`s, so
+ * arrow keys, Home/End, and screen-reader announcements come from the platform.
+ */
+export declare function AudioPlayer({ src, title, subtitle, hideVolume, defaultVolume, labels, onPrevious, onNext, actions, className, ref, onPlay, onPause, onEnded, onTimeUpdate, onLoadedMetadata, onDurationChange, onVolumeChange, onError, ...props }: AudioPlayerProps): import("react").JSX.Element;

package/dist/components/AudioPlayer/AudioPlaylist.d.ts

@@ -0,0 +1,59 @@
+import type { ReactNode, Ref } from "react";
+import type { AudioPlayerLabels } from "./AudioPlayer";
+import type { PlayMode } from "./playlistOrder";
+import "./AudioPlaylist.css";
+export type AudioTrack = {
+    src: string;
+    title: ReactNode;
+    subtitle?: ReactNode;
+    /**
+     * Length in seconds, shown in the track list. Optional — the player learns
+     * it once a track loads, but the list can't without loading every file.
+     */
+    duration?: number;
+    /** Stable key. Falls back to the index and `src`. */
+    id?: string;
+};
+export type AudioPlaylistLabels = AudioPlayerLabels & {
+    /** Prefix for the play-mode button's name, e.g. "Play mode: Shuffle". */
+    playMode?: string;
+    /** Names of the individual modes. */
+    modes?: Partial<Record<PlayMode, string>>;
+    /** Name of the track list. */
+    tracks?: string;
+};
+export type AudioPlaylistProps = {
+    tracks: readonly AudioTrack[];
+    /** Names the playlist as a whole. Defaults to "Playlist". */
+    label?: string;
+    /** Current track — makes the playlist's position controlled. */
+    trackIndex?: number;
+    /** Initial track when uncontrolled. Defaults to the first. */
+    defaultTrackIndex?: number;
+    /** Fired with the index of the track being moved to. */
+    onTrackChange?: (index: number) => void;
+    /** Current play mode — makes it controlled. */
+    playMode?: PlayMode;
+    /** Initial play mode when uncontrolled. Defaults to `sequential`. */
+    defaultPlayMode?: PlayMode;
+    /** Fired with the next mode when the play-mode button is pressed. */
+    onPlayModeChange?: (mode: PlayMode) => void;
+    /** Hides the track list, leaving the player and its skip buttons. */
+    hideTrackList?: boolean;
+    hideVolume?: boolean;
+    /** Initial volume, 0–1. Carries across tracks. */
+    defaultVolume?: number;
+    labels?: AudioPlaylistLabels;
+    className?: string;
+    /** Ref to the underlying `<audio>` element. */
+    ref?: Ref<HTMLAudioElement>;
+};
+/**
+ * An `AudioPlayer` that works through a list of tracks, with Previous/Next,
+ * a play-mode button cycling through in order, repeat all, repeat one and
+ * shuffle, and a track list to jump around in.
+ *
+ * Volume and mute carry from track to track — it's one `<audio>` element
+ * whose source changes, not a player per track.
+ */
+export declare function AudioPlaylist({ tracks, label, trackIndex, defaultTrackIndex, onTrackChange, playMode, defaultPlayMode, onPlayModeChange, hideTrackList, hideVolume, defaultVolume, labels, className, ref, }: AudioPlaylistProps): import("react").JSX.Element | null;

package/dist/components/AudioPlayer/formatAudioTime.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Formats a playback position as `m:ss`, or `h:mm:ss` once it passes an hour.
+ *
+ * Anything that isn't a finite, non-negative number comes back as `--:--`.
+ * That covers the `NaN` a media element reports before its metadata loads and
+ * the `Infinity` it reports for a live stream — neither has a length to show.
+ */
+export declare function formatAudioTime(seconds: number): string;

package/dist/components/AudioPlayer/index.d.ts

@@ -0,0 +1,7 @@
+export { AudioPlayer } from "./AudioPlayer";
+export type { AudioPlayerProps, AudioPlayerLabels } from "./AudioPlayer";
+export { AudioPlaylist } from "./AudioPlaylist";
+export type { AudioPlaylistProps, AudioPlaylistLabels, AudioTrack } from "./AudioPlaylist";
+export { formatAudioTime } from "./formatAudioTime";
+export { playModes, getNextTrack, getPreviousTrack, createShuffleOrder, } from "./playlistOrder";
+export type { PlayMode, PlaylistAdvance, PlaylistPosition, PlaylistStep, } from "./playlistOrder";

package/dist/components/AudioPlayer/playlistOrder.d.ts

@@ -0,0 +1,45 @@
+export declare const playModes: readonly ["sequential", "repeat-all", "repeat-one", "shuffle"];
+export type PlayMode = (typeof playModes)[number];
+/** What moved the playlist on: the track finishing, or the Next button. */
+export type PlaylistAdvance = "ended" | "next";
+export type PlaylistPosition = {
+    /** Index of the current track. */
+    index: number;
+    /** Number of tracks in the playlist. */
+    count: number;
+    mode: PlayMode;
+    /**
+     * Shuffled play order, as track indices. Only read in `shuffle` mode; an
+     * order that no longer fits the playlist is replaced.
+     */
+    order?: readonly number[];
+    /** Source of randomness, for deterministic tests. Defaults to `Math.random`. */
+    random?: () => number;
+};
+export type PlaylistStep = {
+    /** Track to move to, or `null` to stop where we are. */
+    index: number | null;
+    /** The shuffle order to keep for the next step. */
+    order: number[];
+};
+/**
+ * A random permutation of `0..count-1` that starts with `first`, so turning
+ * shuffle on never jumps away from the track that's playing.
+ */
+export declare function createShuffleOrder(count: number, first: number, random?: () => number): number[];
+/**
+ * Where the playlist goes after the current track.
+ *
+ * - `sequential` stops after the last track when it ends; Next wraps.
+ * - `repeat-all` wraps either way.
+ * - `repeat-one` replays the track when it ends; Next still moves on, since
+ *   pressing it is asking for a different track.
+ * - `shuffle` walks a shuffled order and reshuffles once every track has
+ *   played, never starting the new round on the track that just finished.
+ */
+export declare function getNextTrack(position: PlaylistPosition, advance: PlaylistAdvance): PlaylistStep;
+/**
+ * Where Previous goes. In `shuffle` it retraces the shuffled order and stays
+ * on the first track of the round; otherwise it steps back and wraps.
+ */
+export declare function getPreviousTrack(position: PlaylistPosition): PlaylistStep;

package/dist/components/Tooltip/Tooltip.d.ts

@@ -16,12 +16,19 @@ export type TooltipProps = {
     /** Tip body. Nothing renders when this is empty. */
     content?: ReactNode;
     /**
-     * Which side of the trigger the tip sits on. Defaults to `top`.
+     * Which side of the trigger the tip prefers. Defaults to `top`.
      *
-     * `auto` measures the trigger against the viewport each time the tip opens
-     * and picks a side with room for it.
+     * The tip is measured against the viewport each time it opens. If the
+     * preferred side has no room, it flips to the opposite side, then to
+     * whichever side does. `auto` is the same as `top`.
      */
     placement?: TooltipPlacement;
+    /**
+     * Keeps the tip on screen by flipping it to another side and sliding it
+     * away from the viewport edge. Defaults to `true`. Turn it off to pin the
+     * tip to `placement` exactly.
+     */
+    avoidCollisions?: boolean;
     /** Milliseconds to wait before showing on hover. Defaults to 150. */
     delay?: number;
     /** Open state — makes the component controlled. */
@@ -41,4 +48,4 @@ export type TooltipProps = {
  * needs, because it can't be reached by touch and disappears on the way to
  * anything else. Use it to name an icon button or expand an abbreviation.
  */
-export declare function Tooltip({ children, content, placement, delay, open: controlledOpen, defaultOpen, onOpenChange, disabled, className, ...props }: TooltipProps): import("react").JSX.Element;
+export declare function Tooltip({ children, content, placement, avoidCollisions, delay, open: controlledOpen, defaultOpen, onOpenChange, disabled, className, ...props }: TooltipProps): import("react").JSX.Element;

package/dist/components/Tooltip/index.d.ts

@@ -1,4 +1,4 @@
 export { Tooltip } from "./Tooltip";
 export type { TooltipProps } from "./Tooltip";
-export { resolveTooltipPlacement } from "./resolveTooltipPlacement";
-export type { TooltipPlacement, TooltipSide, TooltipRect, ResolveTooltipPlacementOptions, } from "./resolveTooltipPlacement";
+export { resolveTooltipPlacement, resolveTooltipShift } from "./resolveTooltipPlacement";
+export type { TooltipPlacement, TooltipSide, TooltipRect, ResolveTooltipPlacementOptions, ResolveTooltipShiftOptions, } from "./resolveTooltipPlacement";

package/dist/components/Tooltip/resolveTooltipPlacement.d.ts

@@ -23,17 +23,49 @@ export type ResolveTooltipPlacementOptions = {
     };
     /** Separation between trigger and tip. Defaults to 8, matching the CSS. */
     gap?: number;
+    /**
+     * The side to keep whenever it fits. Defaults to `top`. When it doesn't,
+     * the opposite side is tried next, so a tip that can't go above a trigger
+     * goes below it rather than off to one side.
+     */
+    preferred?: TooltipSide;
+};
+export type ResolveTooltipShiftOptions = {
+    /** The side the tip is on — from `resolveTooltipPlacement`. */
+    side: TooltipSide;
+    trigger: TooltipRect;
+    tip: {
+        width: number;
+        height: number;
+    };
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Minimum distance kept between the tip and the viewport edge. Defaults to 8. */
+    padding?: number;
 };
 /**
  * Picks the side of the trigger with room for the tip.
  *
- * Returns the first side in preference order that fits. When none do — a
- * trigger in a cramped scroll container, say — it returns whichever side
- * overflows least, so the tip is still mostly readable.
+ * Returns the preferred side if it fits, then its opposite, then the first
+ * remaining side that fits. When none do — a trigger in a cramped scroll
+ * container, say — it returns whichever side overflows least, so the tip is
+ * still mostly readable.
+ *
+ * This looks at the primary axis only. Keeping the tip inside the viewport
+ * along the other axis is `resolveTooltipShift`'s job.
+ */
+export declare function resolveTooltipPlacement({ trigger, tip, viewport, gap, preferred, }: ResolveTooltipPlacementOptions): TooltipSide;
+/**
+ * How far to slide the tip off-centre so it stays inside the viewport.
+ *
+ * A `top` or `bottom` tip is centred on its trigger, so a trigger near the
+ * left or right edge pushes half of it off screen; the result is a horizontal
+ * offset in pixels that pulls it back. For `left` and `right` it's vertical.
  *
- * This looks at the primary axis only: a `top` tip is centred horizontally
- * and can still overrun the left or right edge of a narrow viewport. Shifting
- * along the cross axis would need the tip to be positioned in JavaScript
- * rather than by CSS.
+ * When the tip is wider than the viewport, its start edge wins, because that's
+ * where reading begins. The shift is capped so the arrow always stays on the
+ * tip and keeps pointing at the trigger.
  */
-export declare function resolveTooltipPlacement({ trigger, tip, viewport, gap, }: ResolveTooltipPlacementOptions): TooltipSide;
+export declare function resolveTooltipShift({ side, trigger, tip, viewport, padding, }: ResolveTooltipShiftOptions): number;

package/dist/index.d.ts

@@ -74,6 +74,8 @@ export { Switch, SwitchGroup } from './components/Switch';
 export type { SwitchProps, SwitchGroupProps } from './components/Switch';
 export { SegmentedControl } from './components/SegmentedControl';
 export type { SegmentedControlProps, SegmentedControlOption, } from './components/SegmentedControl';
+export { AudioPlayer, AudioPlaylist, formatAudioTime, playModes, getNextTrack, getPreviousTrack, createShuffleOrder, } from './components/AudioPlayer';
+export type { AudioPlayerProps, AudioPlayerLabels, AudioPlaylistProps, AudioPlaylistLabels, AudioTrack, PlayMode, PlaylistAdvance, PlaylistPosition, PlaylistStep, } from './components/AudioPlayer';
 /**
  * Design tokens. The stylesheet already defines every color as a CSS var
  * (`--color-accent-600`, `--color-bg-surface`, …) — these are the same