@wyxos/vibe 5.16.9 → 5.17.0

package/README.md

@@ -5,6 +5,8 @@ Vibe is an initializable Vue 3 media feed with virtualized masonry and reel layo
 Try the [live demo](https://vibe.wyxos.com/) to explore the feed and its controls.
 Read the [full documentation](./docs/index.md) for guided setup, layout and data-loading concepts, and the API reference.
 
+For an existing host-owned player and large queue, use the [host-controlled reel](./docs/reference/controlled-reel.md) with a bounded previous/current/next projection and stable media slot.
+
 [![Vibe demo: scroll a masonry feed, open a card in the reel, and press Escape to return to the same scroll position.](https://raw.githubusercontent.com/wyxos/vibe/master/docs/assets/vibe-demo.gif)](https://vibe.wyxos.com/)
 
 The preview uses synthetic sample media. Open a masonry card to view it in a reel,

package/lib/components/VibeControlledReel.vue.d.ts

@@ -0,0 +1,24 @@
+import type { VibeControlledReelDirection, VibeControlledReelProps, VibeControlledReelSlotProps } from '../core/controlledReel';
+type __VLS_Slots = {
+    default(props: VibeControlledReelSlotProps): unknown;
+    previous?(props: VibeControlledReelSlotProps): unknown;
+    next?(props: VibeControlledReelSlotProps): unknown;
+};
+declare function navigate(direction: VibeControlledReelDirection): Promise<void>;
+declare const __VLS_base: import("vue").DefineComponent<VibeControlledReelProps, {
+    navigate: typeof navigate;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    navigationError: (error: unknown) => any;
+}, string, import("vue").PublicProps, Readonly<VibeControlledReelProps> & Readonly<{
+    onNavigationError?: ((error: unknown) => any) | undefined;
+}>, {
+    label: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/lib/core/controlledReel.d.ts

@@ -0,0 +1,41 @@
+import type { VibeItemId } from '../types';
+export type VibeControlledReelDirection = 'next' | 'previous';
+export interface VibeControlledReelItem {
+    id: VibeItemId;
+    artwork?: string;
+    label?: string;
+}
+/** A bounded projection of a host-owned queue. No full queue is required. */
+export interface VibeControlledReelState {
+    /** Change whenever source, order, membership or selection invalidates navigation. */
+    revision: string | number;
+    current: VibeControlledReelItem | null;
+    previous?: VibeControlledReelItem | null;
+    next?: VibeControlledReelItem | null;
+    canPrevious: boolean;
+    canNext: boolean;
+    /** Zero-based position, when known. */
+    position?: number;
+    total?: number;
+}
+export interface VibeControlledReelRequest {
+    direction: VibeControlledReelDirection;
+    snapshot: Readonly<VibeControlledReelState>;
+    signal: AbortSignal;
+}
+export interface VibeControlledReelProps {
+    state: VibeControlledReelState;
+    /** Commit through the host queue, then push state. false declines the intent. */
+    onNavigate: (request: VibeControlledReelRequest) => boolean | void | Promise<boolean | void>;
+    label?: string;
+}
+export interface VibeControlledReelSlotProps {
+    item: VibeControlledReelItem | null;
+    pending: boolean;
+}
+export interface VibeControlledReelExpose {
+    /** The pushed host state, rather than this promise, acknowledges selection. */
+    navigate: (direction: VibeControlledReelDirection) => Promise<void>;
+}
+/** Settle on abort even if an obsolete host callback ignores its signal. */
+export declare function waitForControlledReelNavigation(navigate: VibeControlledReelProps['onNavigate'], context: VibeControlledReelRequest): Promise<boolean | void>;

package/lib/core/reelScrollTransition.d.ts

@@ -1 +1,2 @@
-export declare function transitionReelScroll(element: HTMLElement, top: number, immediate: boolean): Promise<void>;
+export declare function prefersReducedReelMotion(): boolean;
+export declare function transitionReelScroll(element: HTMLElement, top: number, immediate: boolean, signal?: AbortSignal): Promise<void>;

package/lib/core/reelViewport.d.ts

@@ -0,0 +1,2 @@
+/** Shared native scroll-snap selection rule for feed and controlled reels. */
+export declare function reelIndexAtScrollOffset(top: number, height: number, count: number): number;