@lucaismyname/ginger 0.0.57 → 0.0.59

package/README.md

@@ -847,6 +847,32 @@ function PlaylistManual() {
 }
 ```
 
+### `Ginger.Tracks` and `Ginger.Track`
+
+Declare queue entries in JSX instead of (or in addition to) the `initialTracks` array. **`Ginger.Track`** renders nothing; it registers a [`Track`](#track) with the nearest **`Ginger.Tracks`** wrapper, which syncs the merged queue on each update. **`Ginger.Playlist.Track`** remains the **row UI** (it takes an **`index`** into the existing queue); **`Ginger.Track`** is **data only**.
+
+| Prop (`Ginger.Tracks`) | Type | Default | Description |
+|--------|------|---------|-------------|
+| `merge` | `"append" \| "prepend" \| "replace"` | `"append"` | How to combine declarative tracks with `initialTracks` from `Ginger.Provider`: **`append`** → `[...initialTracks, ...declarative]`; **`prepend`** → `[...declarative, ...initialTracks]`; **`replace`** → declarative tracks only (snapshot of `initialTracks` from props is ignored for this subtree’s sync). |
+| `...rest` | `HTMLAttributes<HTMLDivElement>` | - | Passed to a wrapper with `display: contents` (layout-neutral). |
+
+**`Ginger.Track`** accepts the same fields as [`Track`](#track). **`title`** is required; provide **`fileUrl`** or **`src`** (alias for `fileUrl`). Optional **`id`** keeps a stable identity when reordering JSX.
+
+The merge snapshot uses the provider’s latest **`initialTracks` props** (via an internal ref). If you change the queue only with **`setQueue()`** and not via props, a later sync from **`Ginger.Tracks`** can realign the queue with props + declarative children again—prefer updating **`initialTracks`** when mixing approaches, or rely on **`merge="replace"`** with only declarative children.
+
+**Shuffle:** each declarative sync dispatches **`SET_QUEUE`**, which clears shuffle state (same as imperative `setQueue`). Avoid heavy declarative churn while shuffle is on if you need shuffle to persist.
+
+```tsx
+<Ginger.Provider initialTracks={[{ id: "a", title: "Intro", fileUrl: "/a.mp3" }]}>
+  <Ginger.Tracks merge="append">
+    <Ginger.Track title="Main" src="/b.mp3" artist="Band" />
+    <Ginger.Track title="Outro" fileUrl="/c.mp3" />
+  </Ginger.Tracks>
+  <Ginger.Player />
+  <Ginger.Playlist />
+</Ginger.Provider>
+```
+
 ## Types
 
 ### `Track`

package/dist/client.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./ginger-B-W73LQC.cjs"),s=require("./useGinger-BMRLzjmr.cjs"),r=require("./useGingerChapterProgress-DLx-LayX.cjs"),a=require("./liveAudioGraph-0cpHD_Ic.cjs"),n=require("./selectors-CEGlYoFu.cjs"),i=require("./GingerSplitContexts-KSB0vQ5F.cjs");exports.Chapters=e.Chapters;exports.Ginger=e.Ginger;exports.LyricsSynced=e.LyricsSynced;exports.Pause=e.Pause;exports.Play=e.Play;exports.RepeatGlyph=e.RepeatGlyph;exports.ShuffleIcon=e.ShuffleIcon;exports.SkipBack=e.SkipBack;exports.SkipForward=e.SkipForward;exports.Volume2=e.Volume2;exports.VolumeX=e.VolumeX;exports.Wrapper=e.Wrapper;exports.clampPlaybackRate=e.clampPlaybackRate;exports.clampVolume=e.clampVolume;exports.defaultGingerLocale=e.defaultGingerLocale;exports.parseLrc=e.parseLrc;exports.useGingerChapters=e.useGingerChapters;exports.useGingerLocale=e.useGingerLocale;exports.useGingerLyricsSync=e.useGingerLyricsSync;exports.usePlayPauseBinding=e.usePlayPauseBinding;exports.useSeekBarBinding=e.useSeekBarBinding;exports.useVolumeSlider=e.useVolumeSlider;exports.useGinger=s.useGinger;exports.createGingerStore=r.createGingerStore;exports.useGingerChapterProgress=r.useGingerChapterProgress;exports.useGingerDebugLog=r.useGingerDebugLog;exports.useGingerKeyboardShortcuts=r.useGingerKeyboardShortcuts;exports.useGingerLiveAnalyzer=r.useGingerLiveAnalyzer;exports.useGingerPlaybackHistory=r.useGingerPlaybackHistory;exports.useGingerSleepTimer=r.useGingerSleepTimer;exports.useGingerVolumeFade=r.useGingerVolumeFade;exports.useNextTrackPrefetch=r.useNextTrackPrefetch;exports.useSeekDrag=r.useSeekDrag;exports.attachLiveAnalyser=a.attachLiveAnalyser;exports.detachLiveAnalyser=a.detachLiveAnalyser;exports.setProcessingChain=a.setProcessingChain;exports.derivePlaybackUiState=n.derivePlaybackUiState;exports.gingerStateFromContextValues=i.gingerStateFromContextValues;exports.gingerStateFromContexts=i.gingerStateFromContexts;exports.useGingerMedia=i.useGingerMedia;exports.useGingerMediaControls=i.useGingerMediaControls;exports.useGingerPlayback=i.useGingerPlayback;exports.useGingerState=i.useGingerState;exports.useGingerTime=i.useGingerTime;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./ginger-DJwWdIp0.cjs"),s=require("./useGinger-BMRLzjmr.cjs"),r=require("./useGingerChapterProgress-EbJNY5jt.cjs"),a=require("./liveAudioGraph-0cpHD_Ic.cjs"),n=require("./selectors-CEGlYoFu.cjs"),i=require("./GingerSplitContexts-KSB0vQ5F.cjs");exports.Chapters=e.Chapters;exports.Ginger=e.Ginger;exports.LyricsSynced=e.LyricsSynced;exports.Pause=e.Pause;exports.Play=e.Play;exports.RepeatGlyph=e.RepeatGlyph;exports.ShuffleIcon=e.ShuffleIcon;exports.SkipBack=e.SkipBack;exports.SkipForward=e.SkipForward;exports.Volume2=e.Volume2;exports.VolumeX=e.VolumeX;exports.Wrapper=e.Wrapper;exports.clampPlaybackRate=e.clampPlaybackRate;exports.clampVolume=e.clampVolume;exports.defaultGingerLocale=e.defaultGingerLocale;exports.parseLrc=e.parseLrc;exports.useGingerChapters=e.useGingerChapters;exports.useGingerLocale=e.useGingerLocale;exports.useGingerLyricsSync=e.useGingerLyricsSync;exports.usePlayPauseBinding=e.usePlayPauseBinding;exports.useSeekBarBinding=e.useSeekBarBinding;exports.useVolumeSlider=e.useVolumeSlider;exports.useGinger=s.useGinger;exports.createGingerStore=r.createGingerStore;exports.useGingerChapterProgress=r.useGingerChapterProgress;exports.useGingerDebugLog=r.useGingerDebugLog;exports.useGingerKeyboardShortcuts=r.useGingerKeyboardShortcuts;exports.useGingerLiveAnalyzer=r.useGingerLiveAnalyzer;exports.useGingerPlaybackHistory=r.useGingerPlaybackHistory;exports.useGingerSleepTimer=r.useGingerSleepTimer;exports.useGingerVolumeFade=r.useGingerVolumeFade;exports.useNextTrackPrefetch=r.useNextTrackPrefetch;exports.useSeekDrag=r.useSeekDrag;exports.attachLiveAnalyser=a.attachLiveAnalyser;exports.detachLiveAnalyser=a.detachLiveAnalyser;exports.setProcessingChain=a.setProcessingChain;exports.derivePlaybackUiState=n.derivePlaybackUiState;exports.gingerStateFromContextValues=i.gingerStateFromContextValues;exports.gingerStateFromContexts=i.gingerStateFromContexts;exports.useGingerMedia=i.useGingerMedia;exports.useGingerMediaControls=i.useGingerMediaControls;exports.useGingerPlayback=i.useGingerPlayback;exports.useGingerState=i.useGingerState;exports.useGingerTime=i.useGingerTime;
 //# sourceMappingURL=client.cjs.map

package/dist/client.js

@@ -1,6 +1,6 @@
-import { C as s, G as r, L as i, P as u, a as n, R as t, S as o, b as g, c as l, V as c, d as G, W as p, e as d, f as m, g as y, p as S, u as f, h, i as P, j as k, k as L, l as b } from "./ginger-BHu7Ofna.js";
+import { C as s, G as r, L as i, P as u, a as n, R as t, S as o, b as g, c as l, V as c, d as G, W as p, e as d, f as m, g as y, p as S, u as f, h, i as P, j as k, k as L, l as b } from "./ginger-Bc_8qZYi.js";
 import { u as C } from "./useGinger-DKrHZ4NU.js";
-import { c as v, u as B, a as F, b as A, d as R, e as T, f as D, g as M, h as W, i as j } from "./useGingerChapterProgress-DAIWjAtG.js";
+import { c as v, u as B, a as F, b as A, d as R, e as T, f as D, g as M, h as W, i as j } from "./useGingerChapterProgress-CGe9W-te.js";
 import { a as z, d as H, s as I } from "./liveAudioGraph-DvPaxBCP.js";
 import { d as N } from "./selectors-BT3WSsKN.js";
 import { g as X, a as q, u as E, b as J, c as O, d as Q, e as Y } from "./GingerSplitContexts-DQ3rESBu.js";

package/dist/components/tracks/GingerDeclarativeMergeContext.d.ts

@@ -0,0 +1,12 @@
+import { ReactNode } from 'react';
+import { Track } from '../../types';
+export type GingerDeclarativeMergeContextValue = {
+    /** Latest `initialTracks` from `Ginger.Provider` props (via `latestInitRef`). */
+    getInitialTracksSnapshot: () => Track[];
+};
+export declare function GingerDeclarativeMergeProvider({ children, value, }: {
+    children: ReactNode;
+    value: GingerDeclarativeMergeContextValue;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useGingerDeclarativeMerge(): GingerDeclarativeMergeContextValue | null;
+//# sourceMappingURL=GingerDeclarativeMergeContext.d.ts.map

package/dist/components/tracks/GingerDeclarativeMergeContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GingerDeclarativeMergeContext.d.ts","sourceRoot":"","sources":["../../../src/components/tracks/GingerDeclarativeMergeContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAA6B,MAAM,OAAO,CAAC;AAClE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,MAAM,kCAAkC,GAAG;IAC/C,iFAAiF;IACjF,wBAAwB,EAAE,MAAM,KAAK,EAAE,CAAC;CACzC,CAAC;AAMF,wBAAgB,8BAA8B,CAAC,EAC7C,QAAQ,EACR,KAAK,GACN,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,EAAE,kCAAkC,CAAC;CAC3C,2CAMA;AAED,wBAAgB,yBAAyB,IAAI,kCAAkC,GAAG,IAAI,CAErF"}

package/dist/components/tracks/GingerTrack.d.ts

@@ -0,0 +1,17 @@
+import { Track } from '../../types';
+/** Props for declarative queue entries; `title` and `fileUrl` or `src` are required. */
+export type GingerTrackProps = Omit<Partial<Track>, "fileUrl" | "title"> & {
+    title: string;
+    fileUrl?: string;
+    /** Alias for `fileUrl`. */
+    src?: string;
+};
+/**
+ * Declarative queue entry. Renders nothing; registers a {@link Track} with the nearest parent
+ * {@link GingerTracks}. Must be a descendant of `<Ginger.Tracks>`.
+ */
+export declare function GingerTrack(props: GingerTrackProps): null;
+export declare namespace GingerTrack {
+    var displayName: string;
+}
+//# sourceMappingURL=GingerTrack.d.ts.map

package/dist/components/tracks/GingerTrack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GingerTrack.d.ts","sourceRoot":"","sources":["../../../src/components/tracks/GingerTrack.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGzC,wFAAwF;AACxF,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,GAAG;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAmDF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,QAUlD;yBAVe,WAAW"}

package/dist/components/tracks/GingerTracks.d.ts

@@ -0,0 +1,21 @@
+import { HTMLAttributes, ReactNode } from 'react';
+import { GingerTracksMergeMode } from './mergeDeclarativeQueue';
+export type GingerTracksProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    children?: ReactNode;
+    /**
+     * How to combine declarative `Ginger.Track` entries with `initialTracks` from `Ginger.Provider`.
+     * - `append` (default): `[...initialTracks, ...declarative]`
+     * - `prepend`: `[...declarative, ...initialTracks]`
+     * - `replace`: declarative tracks only (`initialTracks` ignored for this subtree’s sync)
+     */
+    merge?: GingerTracksMergeMode;
+};
+/**
+ * Declarative queue definition via `Ginger.Track` children. Coexists with `initialTracks` on the
+ * provider and imperative APIs; see `merge` for combination rules.
+ */
+export declare function GingerTracks({ children, merge, style, hidden: _hidden, ...rest }: GingerTracksProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace GingerTracks {
+    var displayName: string;
+}
+//# sourceMappingURL=GingerTracks.d.ts.map

package/dist/components/tracks/GingerTracks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GingerTracks.d.ts","sourceRoot":"","sources":["../../../src/components/tracks/GingerTracks.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,SAAS,EAA2B,MAAM,OAAO,CAAC;AAMrF,OAAO,EACL,KAAK,qBAAqB,EAG3B,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC,GAAG;IACjF,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,qBAAqB,CAAC;CAC/B,CAAC;AAqCF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,KAAgB,EAChB,KAAK,EACL,MAAM,EAAE,OAAO,EACf,GAAG,IAAI,EACR,EAAE,iBAAiB,2CAiBnB;yBAvBe,YAAY"}

package/dist/components/tracks/GingerTracks.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=GingerTracks.test.d.ts.map

package/dist/components/tracks/GingerTracks.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GingerTracks.test.d.ts","sourceRoot":"","sources":["../../../src/components/tracks/GingerTracks.test.tsx"],"names":[],"mappings":""}

package/dist/components/tracks/GingerTracksRegistryContext.d.ts

@@ -0,0 +1,13 @@
+import { ReactNode } from 'react';
+import { Track } from '../../types';
+/** Mutable registry cleared at the start of each `Ginger.Tracks` render, then filled by child `Ginger.Track` renders. */
+export type GingerTracksRegistry = {
+    slots: Map<string, Track>;
+    order: string[];
+};
+export declare function GingerTracksRegistryProvider({ children, value, }: {
+    children: ReactNode;
+    value: GingerTracksRegistry;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useGingerTracksRegistry(): GingerTracksRegistry;
+//# sourceMappingURL=GingerTracksRegistryContext.d.ts.map

package/dist/components/tracks/GingerTracksRegistryContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GingerTracksRegistryContext.d.ts","sourceRoot":"","sources":["../../../src/components/tracks/GingerTracksRegistryContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAA6B,MAAM,OAAO,CAAC;AAClE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,yHAAyH;AACzH,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAIF,wBAAgB,4BAA4B,CAAC,EAC3C,QAAQ,EACR,KAAK,GACN,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,EAAE,oBAAoB,CAAC;CAC7B,2CAMA;AAED,wBAAgB,uBAAuB,IAAI,oBAAoB,CAM9D"}

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

@@ -0,0 +1,5 @@
+export { GingerDeclarativeMergeProvider, useGingerDeclarativeMerge, type GingerDeclarativeMergeContextValue, } from './GingerDeclarativeMergeContext';
+export { GingerTrack, type GingerTrackProps } from './GingerTrack';
+export { GingerTracks, type GingerTracksProps } from './GingerTracks';
+export { type GingerTracksMergeMode, mergeDeclarativeQueue, tracksQueueShallowEqual, } from './mergeDeclarativeQueue';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/tracks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/tracks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,EACzB,KAAK,kCAAkC,GACxC,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EACL,KAAK,qBAAqB,EAC1B,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC"}

package/dist/components/tracks/mergeDeclarativeQueue.d.ts

@@ -0,0 +1,6 @@
+import { Track } from '../../types';
+export type GingerTracksMergeMode = "append" | "prepend" | "replace";
+export declare function mergeDeclarativeQueue(merge: GingerTracksMergeMode, initialSnapshot: Track[], declarative: Track[]): Track[];
+/** Avoids redundant `SET_QUEUE` dispatches when merged queue is unchanged. */
+export declare function tracksQueueShallowEqual(a: Track[], b: Track[]): boolean;
+//# sourceMappingURL=mergeDeclarativeQueue.d.ts.map

package/dist/components/tracks/mergeDeclarativeQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mergeDeclarativeQueue.d.ts","sourceRoot":"","sources":["../../../src/components/tracks/mergeDeclarativeQueue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAErE,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,qBAAqB,EAC5B,eAAe,EAAE,KAAK,EAAE,EACxB,WAAW,EAAE,KAAK,EAAE,GACnB,KAAK,EAAE,CAWT;AAED,8EAA8E;AAC9E,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,OAAO,CAgBvE"}

package/dist/context/GingerProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GingerProvider.d.ts","sourceRoot":"","sources":["../../src/context/GingerProvider.tsx"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAEV,mBAAmB,EAMpB,MAAM,UAAU,CAAC;AA2BlB,wBAAgB,cAAc,CAAC,EAC7B,QAAQ,EACR,aAAkB,EAClB,YAAgB,EAChB,mBAA0B,EAC1B,cAAsB,EACtB,iBAAyB,EACzB,mBAAgC,EAChC,aAAoB,EACpB,aAAiB,EACjB,YAAoB,EACpB,mBAAuB,EACvB,eAAe,EACf,MAAM,EACN,YAAoB,EACpB,UAAU,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,cAAsB,EACtB,mBAA2B,EAC3B,QAAgB,EAChB,OAAe,EACf,SAAS,EACT,KAAK,EACL,GAAG,EAAE,OAAO,EACZ,2BAA+B,EAC/B,aAAa,EACb,MAAM,EACN,OAAO,EACP,UAAU,EACV,OAAO,EACP,cAAc,EACd,oBAAoB,EACpB,MAAM,EACN,UAAU,GACX,EAAE,mBAAmB,2CAqyBrB"}
+{"version":3,"file":"GingerProvider.d.ts","sourceRoot":"","sources":["../../src/context/GingerProvider.tsx"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAEV,mBAAmB,EAMpB,MAAM,UAAU,CAAC;AA2BlB,wBAAgB,cAAc,CAAC,EAC7B,QAAQ,EACR,aAAkB,EAClB,YAAgB,EAChB,mBAA0B,EAC1B,cAAsB,EACtB,iBAAyB,EACzB,mBAAgC,EAChC,aAAoB,EACpB,aAAiB,EACjB,YAAoB,EACpB,mBAAuB,EACvB,eAAe,EACf,MAAM,EACN,YAAoB,EACpB,UAAU,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,cAAsB,EACtB,mBAA2B,EAC3B,QAAgB,EAChB,OAAe,EACf,SAAS,EACT,KAAK,EACL,GAAG,EAAE,OAAO,EACZ,2BAA+B,EAC/B,aAAa,EACb,MAAM,EACN,OAAO,EACP,UAAU,EACV,OAAO,EACP,cAAc,EACd,oBAAoB,EACpB,MAAM,EACN,UAAU,GACX,EAAE,mBAAmB,2CA8yBrB"}