@alessiofrittoli/react-hooks 4.1.1 → 4.2.1

package/dist/misc/queue/index.d.mts

@@ -0,0 +1,266 @@
+import { Q as Queue, U as UUID, N as NewQueue, a as QueuedItemType, b as QueuedItemsType, O as OptionalQueuedItem, c as OptionalQueuedItems } from '../../types-Cx6f9FS1.mjs';
+export { d as QueueItem, e as QueueItems, f as QueuedItem, g as QueuedItems } from '../../types-Cx6f9FS1.mjs';
+import '@alessiofrittoli/math-utils';
+
+type JumpToOptions<T extends Queue = Queue> = {
+    /**
+     * The item UUID where to jump to.
+     *
+     * If not given, queue will jump to first item.
+     */
+    uuid?: UUID;
+    /**
+     * A new queue to set.
+     *
+     */
+    queue?: NewQueue<T>;
+};
+/**
+ * Jump to a specific item.
+ *
+ * @param options An object defining an optional item UUID where to jump to and an optional new queue to set. See {@link JumpToOptions}.
+ *
+ * @returns The item being set as active if any. It could be included in the main queue, custom queue or the new given queue.
+ */
+type JumpToHandler<T extends Queue = Queue> = (options: JumpToOptions<T>) => QueuedItemType<T> | undefined;
+/**
+ * Defines configuration options for the `useQueue` hook.
+ *
+ */
+interface UseQueueOptions<T extends Queue = Queue> {
+    /**
+     * The queue.
+     *
+     */
+    queue: T;
+    /**
+     * Defines the initial active item in the queue.
+     *
+     */
+    current?: QueuedItemType<T>;
+    /**
+     * Indicates whether repeatition of the given queue is initially active.
+     *
+     * @default true
+     */
+    repeat?: boolean;
+}
+/**
+ * Defines `useQueue` hook API.
+ *
+ */
+interface UseQueue<T extends Queue = Queue> {
+    /**
+     * The main queue.
+     *
+     */
+    queue: T;
+    /**
+     * The current active item.
+     *
+     * It could be included in either the main `queue` or custom queue.
+     */
+    current?: QueuedItemType<T>;
+    /**
+     * Defines the `current` item cursor ID.
+     *
+     */
+    currentId?: QueuedItemType<T>['uuid'];
+    /**
+     * Defines an array of queued items in the custom queue.
+     *
+     */
+    customQueue: QueuedItemsType<T>;
+    /**
+     * Defines the complete queue (main queue + custom queue).
+     *
+     */
+    effectiveQueue: QueuedItemsType<T>;
+    /**
+     * Upcoming main queue items.
+     *
+     */
+    nextFromQueue: QueuedItemsType<T>;
+    /**
+     * Indicates whether the current item has a previous item.
+     *
+     * - `true` if main queue has more than 0 items.
+     * - `true` if `repeat` is enabled.
+     * - `true` if current item index in the main queue is greather than 0.
+     * - `false` otherwise.
+     */
+    hasPrevious: boolean;
+    /**
+     * Indicates whether the current item has a next item.
+     *
+     * - `true` if custom queue has more than 0 items.
+     * - `true` if main queue has more than 0 items.
+     * - `true` if `repeat` is enabled.
+     * - `true` if current item index in the main queue is less than the main queue length.
+     * - `false` otherwise.
+     */
+    hasNext: boolean;
+    /**
+     * Indicates whether shuffle is currently enabled.
+     *
+     */
+    isShuffleEnabled: boolean;
+    /**
+     * Shuffle main queue.
+     *
+     */
+    shuffle: VoidFunction;
+    /**
+     * Un-shuffle main queue.
+     *
+     */
+    unshuffle: VoidFunction;
+    /**
+     * Toggle shuffle for the main queue.
+     *
+     */
+    toggleShuffle: VoidFunction;
+    /**
+     * Indicates whether `repeat` is enabled or not.
+     *
+     */
+    isRepeatEnabled: boolean;
+    /**
+     * Toggle `repeat` on/off.
+     *
+     */
+    toggleRepeat: VoidFunction;
+    /**
+     * Jump to a specific item.
+     *
+     * @param options An object defining an optional item UUID where to jump to and an optional new queue to set. See {@link JumpToOptions}.
+     *
+     * @returns The item being set as active if any. It could be included in the main queue, custom queue or the new given queue.
+     */
+    jumpTo: JumpToHandler<T>;
+    /**
+     * Get previous item.
+     *
+     * @returns The previous item, `undefined` if none has been found.
+     */
+    getPrevious: () => QueuedItemType<T> | undefined;
+    /**
+     * Jump to previous item.
+     *
+     * @returns The previous item being set as active, `undefined` if none has been found.
+     */
+    previous: () => QueuedItemType<T> | undefined;
+    /**
+     * Get next item.
+     *
+     * @returns The next item, `undefined` if none has been found.
+     */
+    getNext: () => QueuedItemType<T> | undefined;
+    /**
+     * Jump to next item.
+     *
+     * @returns The next item being set as active, `undefined` if none has been found.
+     */
+    next: () => QueuedItemType<T> | undefined;
+    /**
+     * Completely overwrite the main queue and optionally generate a new UUID for each queue item.
+     *
+     * @param queue The new queue.
+     */
+    setQueue: (queue: NewQueue<T>) => T;
+    /**
+     * Add a new item the custom queue.
+     *
+     * A new UUID is automatically generated for each item.
+     *
+     * @param item The item or an array of items to add in the queue.
+     */
+    addToQueue: (item: OptionalQueuedItem<QueuedItemType<T>> | OptionalQueuedItems<QueuedItemType<T>>) => void;
+    /**
+     * Remove item from the queues.
+     *
+     * @param uuid The item UUID to remove from the queue.
+     */
+    removeFromQueue: (uuid: UUID) => void;
+    /**
+     * Wipe custom queue.
+     *
+     */
+    clearQueue: VoidFunction;
+}
+/**
+ * Manage a queue of items with support for shuffling, repeating, and custom queue items.
+ *
+ * @template T		The type of the queue, defaults to `Queue`.
+ * @param options	Configuration options for the `useQueue` hook. See {@link UseQueueOptions} for more info.
+ *
+ * @returns An object containing state and utilities. See {@link UseQueue} for more info.
+ */
+declare const useQueue: <T extends Queue = Queue>(options: UseQueueOptions<T>) => UseQueue<T>;
+
+/**
+ * Defines `useShuffle` hook API.
+ *
+ */
+interface UseShuffle {
+    /**
+     * Indicates whether shuffle is currently enabled.
+     *
+     */
+    enabled: boolean;
+    /**
+     * Shuffle given `queue` items.
+     *
+     * @param	queue	The Queue.
+     * @param	uuid	The current queue item UUID. This is used as entry point in order to shuffle upcoming items.
+     *
+     * @returns	The given `queue` with shuffled items.
+     */
+    shuffle: <T extends Queue>(queue: T, uuid?: UUID) => T;
+    /**
+     * Un-shuffle given `queue` items.
+     *
+     * @param	queue	The Queue.
+     * @param	uuid	The current queue item UUID. This is used as entry point in order to restore upcoming items.
+     *
+     * @returns	The given `queue` with restored items order.
+     */
+    unshuffle: <T extends Queue>(queue: T, uuid?: UUID) => T;
+    /**
+     * Shuffle/un-shuffle given `queue` items.
+     *
+     * @param	queue	The Queue.
+     * @param	cursor	The current queue item UUID. This is used as entry point in order to shuffle/restore upcoming items.
+     *
+     * @returns	The given `queue` with shuffled items or the given `queue` with restored items order.
+     */
+    toggleShuffle: <T extends Queue>(queue: T, cursor?: UUID) => T;
+}
+/**
+ * Handle shuffle functionality for queues.
+ *
+ * This hook manages the shuffle state and provides methods to shuffle, unshuffle,
+ * and toggle shuffle for a queue. When shuffling, it preserves the order
+ * of items up to the current cursor position and only shuffles upcoming items.
+ *
+ * @returns An object containing state and utilities. See {@link UseShuffle} for more info.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *  enabled, shuffle, unshuffle, toggleShuffle
+ * } = useShuffle()
+ *
+ * // Shuffle the queue
+ * const shuffledQueue = shuffle( currentQueue, currentUUID )
+ *
+ * // Restore original order
+ * const restoredQueue = unshuffle( currentQueue, currentUUID )
+ *
+ * // Toggle shuffle state
+ * const updatedQueue = toggleShuffle( currentQueue, currentUUID )
+ * ```
+ */
+declare const useShuffle: () => UseShuffle;
+
+export { type JumpToHandler, type JumpToOptions, NewQueue, OptionalQueuedItem, OptionalQueuedItems, Queue, QueuedItemType, QueuedItemsType, UUID, type UseQueue, type UseQueueOptions, type UseShuffle, useQueue, useShuffle };

package/dist/misc/queue/index.d.ts

@@ -0,0 +1,266 @@
+import { Q as Queue, U as UUID, N as NewQueue, a as QueuedItemType, b as QueuedItemsType, O as OptionalQueuedItem, c as OptionalQueuedItems } from '../../types-Cx6f9FS1.js';
+export { d as QueueItem, e as QueueItems, f as QueuedItem, g as QueuedItems } from '../../types-Cx6f9FS1.js';
+import '@alessiofrittoli/math-utils';
+
+type JumpToOptions<T extends Queue = Queue> = {
+    /**
+     * The item UUID where to jump to.
+     *
+     * If not given, queue will jump to first item.
+     */
+    uuid?: UUID;
+    /**
+     * A new queue to set.
+     *
+     */
+    queue?: NewQueue<T>;
+};
+/**
+ * Jump to a specific item.
+ *
+ * @param options An object defining an optional item UUID where to jump to and an optional new queue to set. See {@link JumpToOptions}.
+ *
+ * @returns The item being set as active if any. It could be included in the main queue, custom queue or the new given queue.
+ */
+type JumpToHandler<T extends Queue = Queue> = (options: JumpToOptions<T>) => QueuedItemType<T> | undefined;
+/**
+ * Defines configuration options for the `useQueue` hook.
+ *
+ */
+interface UseQueueOptions<T extends Queue = Queue> {
+    /**
+     * The queue.
+     *
+     */
+    queue: T;
+    /**
+     * Defines the initial active item in the queue.
+     *
+     */
+    current?: QueuedItemType<T>;
+    /**
+     * Indicates whether repeatition of the given queue is initially active.
+     *
+     * @default true
+     */
+    repeat?: boolean;
+}
+/**
+ * Defines `useQueue` hook API.
+ *
+ */
+interface UseQueue<T extends Queue = Queue> {
+    /**
+     * The main queue.
+     *
+     */
+    queue: T;
+    /**
+     * The current active item.
+     *
+     * It could be included in either the main `queue` or custom queue.
+     */
+    current?: QueuedItemType<T>;
+    /**
+     * Defines the `current` item cursor ID.
+     *
+     */
+    currentId?: QueuedItemType<T>['uuid'];
+    /**
+     * Defines an array of queued items in the custom queue.
+     *
+     */
+    customQueue: QueuedItemsType<T>;
+    /**
+     * Defines the complete queue (main queue + custom queue).
+     *
+     */
+    effectiveQueue: QueuedItemsType<T>;
+    /**
+     * Upcoming main queue items.
+     *
+     */
+    nextFromQueue: QueuedItemsType<T>;
+    /**
+     * Indicates whether the current item has a previous item.
+     *
+     * - `true` if main queue has more than 0 items.
+     * - `true` if `repeat` is enabled.
+     * - `true` if current item index in the main queue is greather than 0.
+     * - `false` otherwise.
+     */
+    hasPrevious: boolean;
+    /**
+     * Indicates whether the current item has a next item.
+     *
+     * - `true` if custom queue has more than 0 items.
+     * - `true` if main queue has more than 0 items.
+     * - `true` if `repeat` is enabled.
+     * - `true` if current item index in the main queue is less than the main queue length.
+     * - `false` otherwise.
+     */
+    hasNext: boolean;
+    /**
+     * Indicates whether shuffle is currently enabled.
+     *
+     */
+    isShuffleEnabled: boolean;
+    /**
+     * Shuffle main queue.
+     *
+     */
+    shuffle: VoidFunction;
+    /**
+     * Un-shuffle main queue.
+     *
+     */
+    unshuffle: VoidFunction;
+    /**
+     * Toggle shuffle for the main queue.
+     *
+     */
+    toggleShuffle: VoidFunction;
+    /**
+     * Indicates whether `repeat` is enabled or not.
+     *
+     */
+    isRepeatEnabled: boolean;
+    /**
+     * Toggle `repeat` on/off.
+     *
+     */
+    toggleRepeat: VoidFunction;
+    /**
+     * Jump to a specific item.
+     *
+     * @param options An object defining an optional item UUID where to jump to and an optional new queue to set. See {@link JumpToOptions}.
+     *
+     * @returns The item being set as active if any. It could be included in the main queue, custom queue or the new given queue.
+     */
+    jumpTo: JumpToHandler<T>;
+    /**
+     * Get previous item.
+     *
+     * @returns The previous item, `undefined` if none has been found.
+     */
+    getPrevious: () => QueuedItemType<T> | undefined;
+    /**
+     * Jump to previous item.
+     *
+     * @returns The previous item being set as active, `undefined` if none has been found.
+     */
+    previous: () => QueuedItemType<T> | undefined;
+    /**
+     * Get next item.
+     *
+     * @returns The next item, `undefined` if none has been found.
+     */
+    getNext: () => QueuedItemType<T> | undefined;
+    /**
+     * Jump to next item.
+     *
+     * @returns The next item being set as active, `undefined` if none has been found.
+     */
+    next: () => QueuedItemType<T> | undefined;
+    /**
+     * Completely overwrite the main queue and optionally generate a new UUID for each queue item.
+     *
+     * @param queue The new queue.
+     */
+    setQueue: (queue: NewQueue<T>) => T;
+    /**
+     * Add a new item the custom queue.
+     *
+     * A new UUID is automatically generated for each item.
+     *
+     * @param item The item or an array of items to add in the queue.
+     */
+    addToQueue: (item: OptionalQueuedItem<QueuedItemType<T>> | OptionalQueuedItems<QueuedItemType<T>>) => void;
+    /**
+     * Remove item from the queues.
+     *
+     * @param uuid The item UUID to remove from the queue.
+     */
+    removeFromQueue: (uuid: UUID) => void;
+    /**
+     * Wipe custom queue.
+     *
+     */
+    clearQueue: VoidFunction;
+}
+/**
+ * Manage a queue of items with support for shuffling, repeating, and custom queue items.
+ *
+ * @template T		The type of the queue, defaults to `Queue`.
+ * @param options	Configuration options for the `useQueue` hook. See {@link UseQueueOptions} for more info.
+ *
+ * @returns An object containing state and utilities. See {@link UseQueue} for more info.
+ */
+declare const useQueue: <T extends Queue = Queue>(options: UseQueueOptions<T>) => UseQueue<T>;
+
+/**
+ * Defines `useShuffle` hook API.
+ *
+ */
+interface UseShuffle {
+    /**
+     * Indicates whether shuffle is currently enabled.
+     *
+     */
+    enabled: boolean;
+    /**
+     * Shuffle given `queue` items.
+     *
+     * @param	queue	The Queue.
+     * @param	uuid	The current queue item UUID. This is used as entry point in order to shuffle upcoming items.
+     *
+     * @returns	The given `queue` with shuffled items.
+     */
+    shuffle: <T extends Queue>(queue: T, uuid?: UUID) => T;
+    /**
+     * Un-shuffle given `queue` items.
+     *
+     * @param	queue	The Queue.
+     * @param	uuid	The current queue item UUID. This is used as entry point in order to restore upcoming items.
+     *
+     * @returns	The given `queue` with restored items order.
+     */
+    unshuffle: <T extends Queue>(queue: T, uuid?: UUID) => T;
+    /**
+     * Shuffle/un-shuffle given `queue` items.
+     *
+     * @param	queue	The Queue.
+     * @param	cursor	The current queue item UUID. This is used as entry point in order to shuffle/restore upcoming items.
+     *
+     * @returns	The given `queue` with shuffled items or the given `queue` with restored items order.
+     */
+    toggleShuffle: <T extends Queue>(queue: T, cursor?: UUID) => T;
+}
+/**
+ * Handle shuffle functionality for queues.
+ *
+ * This hook manages the shuffle state and provides methods to shuffle, unshuffle,
+ * and toggle shuffle for a queue. When shuffling, it preserves the order
+ * of items up to the current cursor position and only shuffles upcoming items.
+ *
+ * @returns An object containing state and utilities. See {@link UseShuffle} for more info.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *  enabled, shuffle, unshuffle, toggleShuffle
+ * } = useShuffle()
+ *
+ * // Shuffle the queue
+ * const shuffledQueue = shuffle( currentQueue, currentUUID )
+ *
+ * // Restore original order
+ * const restoredQueue = unshuffle( currentQueue, currentUUID )
+ *
+ * // Toggle shuffle state
+ * const updatedQueue = toggleShuffle( currentQueue, currentUUID )
+ * ```
+ */
+declare const useShuffle: () => UseShuffle;
+
+export { type JumpToHandler, type JumpToOptions, NewQueue, OptionalQueuedItem, OptionalQueuedItems, Queue, QueuedItemType, QueuedItemsType, UUID, type UseQueue, type UseQueueOptions, type UseShuffle, useQueue, useShuffle };

package/dist/misc/queue/index.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }var _chunkSV2TCLLEjs = require('../../chunk-SV2TCLLE.js');var _react = require('react');var _webutils = require('@alessiofrittoli/web-utils');var M=()=>{let[F,v]=_react.useState.call(void 0, !1),[I,x]=_react.useState.call(void 0, ),h=_react.useRef.call(void 0, !1),U=_react.useCallback.call(void 0, (s,a)=>{let{items:l}=s;if(l.length<=1)return s;v(!0),h.current||x(l.map(({uuid:p})=>p)),h.current=!0;let f=_chunkSV2TCLLEjs.e.call(void 0, l,a),c=l.slice(0,f+1),n=l.slice(f+1);return n.length<=1?s:{...s,items:[...c,..._webutils.shuffle.call(void 0, n)]}},[]),g=_react.useCallback.call(void 0, (s,a)=>{if(!I)return s;v(!1);let{items:l}=s,f=new Map(I.map((m,u)=>[m,u]));h.current=!1;let c=_chunkSV2TCLLEjs.e.call(void 0, l,a),n=l.slice(0,c+1),b=[...l.slice(c+1)].sort((m,u)=>(_nullishCoalesce(f.get(m.uuid), () => (0)))-(_nullishCoalesce(f.get(u.uuid), () => (0))));return x(void 0),{...s,items:[...n,...b]}},[I]),S=_react.useCallback.call(void 0, (s,a)=>h.current?g(s,a):U(s,a),[U,g]);return{enabled:F,shuffle:U,unshuffle:g,toggleShuffle:S}};var pe=F=>{let{queue:v,repeat:I=!0,current:x}=F,{enabled:h,shuffle:U,unshuffle:g,toggleShuffle:S}=M(),[s,a]=_react.useState.call(void 0, I),l=_react.useCallback.call(void 0, ()=>a(e=>!e),[]),[f,c]=_react.useState.call(void 0, v),[n,p]=_react.useState.call(void 0, []),[b,m]=_react.useState.call(void 0, x),[u,N]=_react.useState.call(void 0, _optionalChain([x, 'optionalAccess', _2 => _2.uuid])),t=f.items,T=_optionalChain([b, 'optionalAccess', _3 => _3.uuid]),A=_react.useMemo.call(void 0, ()=>_chunkSV2TCLLEjs.f.call(void 0, {queue:t,customQueue:n,uuid:T}),[t,n,T]),B=_react.useMemo.call(void 0, ()=>t.length<=0?!1:s?!0:u?_chunkSV2TCLLEjs.e.call(void 0, t,u)>0:t.length>0,[t,u,s]),z=_react.useMemo.call(void 0, ()=>n.length>0?!0:t.length<=0?!1:s?!0:u?_chunkSV2TCLLEjs.e.call(void 0, t,u)<t.length-1:t.length>0,[t,n,u,s]),O=_react.useCallback.call(void 0, e=>{let r={...e,items:_chunkSV2TCLLEjs.d.call(void 0, e.items)};return c(r),r},[]),G=_react.useCallback.call(void 0, e=>p(r=>[...r,..._chunkSV2TCLLEjs.b.call(void 0, e)]),[]),K=_react.useCallback.call(void 0, e=>{let r=o=>o.uuid===e,Q=o=>o.uuid!==e;c(o=>o.items.find(r)?{...o,items:o.items.filter(Q)}:o),p(o=>o.find(r)?o.filter(Q):o)},[]),L=_react.useCallback.call(void 0, ()=>p([]),[]),W=_react.useCallback.call(void 0, ({uuid:e,queue:r})=>{let Q=r?O(r).items:t;if(n.length>0){let w=_chunkSV2TCLLEjs.e.call(void 0, n,e);if(w>=0){let H=n.at(w);return m(H),p(n.slice(w+1)),H}}let o=e?_chunkSV2TCLLEjs.e.call(void 0, Q,e):0,E=Q[o===-1?0:o];return m(E),N(_optionalChain([E, 'optionalAccess', _4 => _4.uuid])),E},[t,n,O]),P=_react.useCallback.call(void 0, ()=>{if(!T)return t.at(-1);let e=!!t.find(o=>o.uuid===T),r=_chunkSV2TCLLEjs.e.call(void 0, t,e?T:u);return t.at(e?_webutils.getPreviousIndex.call(void 0, t.length,r):r)},[T,u,t]),X=_react.useCallback.call(void 0, ()=>{let e=P();return m(e),N(_optionalChain([e, 'optionalAccess', _5 => _5.uuid])),e},[P]),R=_react.useCallback.call(void 0, ()=>{if(n.length>0)return n.at(0);let e=_chunkSV2TCLLEjs.e.call(void 0, f.items,u);return f.items.at(_webutils.getNextIndex.call(void 0, f.items.length,e))},[f,n,u]),Y=_react.useCallback.call(void 0, ()=>{if(n.length>0){let[r,...Q]=n;return m(r),p(Q),r}let e=R();return m(e),N(_optionalChain([e, 'optionalAccess', _6 => _6.uuid])),e},[n,R]),Z=_react.useCallback.call(void 0, ()=>c(e=>U(e,u)),[u,U]),_=_react.useCallback.call(void 0, ()=>c(e=>g(e,u)),[u,g]),$=_react.useCallback.call(void 0, ()=>c(e=>S(e,u)),[u,S]),ee=_react.useMemo.call(void 0, ()=>u?t.slice(_chunkSV2TCLLEjs.e.call(void 0, t,u)+1):t,[t,u]);return{queue:f,currentId:T,current:b,customQueue:n,effectiveQueue:A,nextFromQueue:ee,hasPrevious:B,hasNext:z,isShuffleEnabled:h,shuffle:Z,unshuffle:_,toggleShuffle:$,isRepeatEnabled:s,toggleRepeat:l,jumpTo:W,getPrevious:P,previous:X,getNext:R,next:Y,setQueue:O,addToQueue:G,removeFromQueue:K,clearQueue:L}};exports.useQueue = pe; exports.useShuffle = M;

package/dist/misc/queue/index.mjs

@@ -0,0 +1 @@
+import{b as V,d as J,e as d,f as j}from"../../chunk-OXQJOVCZ.mjs";import{useCallback as i,useMemo as D,useState as y}from"react";import{getNextIndex as se,getPreviousIndex as re}from"@alessiofrittoli/web-utils";import{useCallback as C,useRef as te,useState as k}from"react";import{shuffle as ne}from"@alessiofrittoli/web-utils";var A=()=>{let[F,v]=k(!1),[I,x]=k(),h=te(!1),U=C((s,a)=>{let{items:l}=s;if(l.length<=1)return s;v(!0),h.current||x(l.map(({uuid:p})=>p)),h.current=!0;let f=d(l,a),c=l.slice(0,f+1),n=l.slice(f+1);return n.length<=1?s:{...s,items:[...c,...ne(n)]}},[]),g=C((s,a)=>{if(!I)return s;v(!1);let{items:l}=s,f=new Map(I.map((m,u)=>[m,u]));h.current=!1;let c=d(l,a),n=l.slice(0,c+1),b=[...l.slice(c+1)].sort((m,u)=>(f.get(m.uuid)??0)-(f.get(u.uuid)??0));return x(void 0),{...s,items:[...n,...b]}},[I]),S=C((s,a)=>h.current?g(s,a):U(s,a),[U,g]);return{enabled:F,shuffle:U,unshuffle:g,toggleShuffle:S}};var Qe=F=>{let{queue:v,repeat:I=!0,current:x}=F,{enabled:h,shuffle:U,unshuffle:g,toggleShuffle:S}=A(),[s,a]=y(I),l=i(()=>a(e=>!e),[]),[f,c]=y(v),[n,p]=y([]),[b,m]=y(x),[u,N]=y(x?.uuid),t=f.items,T=b?.uuid,B=D(()=>j({queue:t,customQueue:n,uuid:T}),[t,n,T]),z=D(()=>t.length<=0?!1:s?!0:u?d(t,u)>0:t.length>0,[t,u,s]),G=D(()=>n.length>0?!0:t.length<=0?!1:s?!0:u?d(t,u)<t.length-1:t.length>0,[t,n,u,s]),O=i(e=>{let r={...e,items:J(e.items)};return c(r),r},[]),K=i(e=>p(r=>[...r,...V(e)]),[]),L=i(e=>{let r=o=>o.uuid===e,Q=o=>o.uuid!==e;c(o=>o.items.find(r)?{...o,items:o.items.filter(Q)}:o),p(o=>o.find(r)?o.filter(Q):o)},[]),W=i(()=>p([]),[]),X=i(({uuid:e,queue:r})=>{let Q=r?O(r).items:t;if(n.length>0){let w=d(n,e);if(w>=0){let H=n.at(w);return m(H),p(n.slice(w+1)),H}}let o=e?d(Q,e):0,E=Q[o===-1?0:o];return m(E),N(E?.uuid),E},[t,n,O]),P=i(()=>{if(!T)return t.at(-1);let e=!!t.find(o=>o.uuid===T),r=d(t,e?T:u);return t.at(e?re(t.length,r):r)},[T,u,t]),Y=i(()=>{let e=P();return m(e),N(e?.uuid),e},[P]),R=i(()=>{if(n.length>0)return n.at(0);let e=d(f.items,u);return f.items.at(se(f.items.length,e))},[f,n,u]),Z=i(()=>{if(n.length>0){let[r,...Q]=n;return m(r),p(Q),r}let e=R();return m(e),N(e?.uuid),e},[n,R]),_=i(()=>c(e=>U(e,u)),[u,U]),$=i(()=>c(e=>g(e,u)),[u,g]),ee=i(()=>c(e=>S(e,u)),[u,S]),ue=D(()=>u?t.slice(d(t,u)+1):t,[t,u]);return{queue:f,currentId:T,current:b,customQueue:n,effectiveQueue:B,nextFromQueue:ue,hasPrevious:z,hasNext:G,isShuffleEnabled:h,shuffle:_,unshuffle:$,toggleShuffle:ee,isRepeatEnabled:s,toggleRepeat:l,jumpTo:X,getPrevious:P,previous:Y,getNext:R,next:Z,setQueue:O,addToQueue:K,removeFromQueue:L,clearQueue:W}};export{Qe as useQueue,A as useShuffle};

package/dist/misc/queue/utils.d.mts

@@ -0,0 +1,104 @@
+import { g as QueuedItems, U as UUID, d as QueueItem, f as QueuedItem, e as QueueItems } from '../../types-Cx6f9FS1.mjs';
+import '@alessiofrittoli/math-utils';
+
+/**
+ * Adds a UUID to the given item.
+ *
+ * @template T	The type of the given item, must extend object.
+ * @param item	The item to add a UUID to.
+ * @returns		A new item with the same properties as the input item plus a UUID.
+ *
+ * @example
+ * ```ts
+ * const item       = { foo: 'bar' }
+ * const newItem    = addItemUUID( item )
+ * // Returns: { foo: 'bar', uuid: 'XXXXXXXX-XXXX-4XXX-YXXX-XXXXXXXXXXXX' }
+ * ```
+ */
+declare const addItemUUID: <T extends object = object>(item: QueueItem<T> | QueuedItem<T>) => QueuedItem<T>;
+/**
+ * Adds a UUID to one or more items.
+ *
+ * If a single item is provided, it is normalized to an array and returned as
+ * a one-element list with generated UUIDs.
+ *
+ * @template T	The type of the given item, must extend object.
+ * @param items	A single item or an array of items where UUIDs are added to.
+ * @returns		An array of items with a UUID on each item.
+ *
+ * @example
+ * ```ts
+ * const result = addItemsUUID( [ { foo: 'bar' } ] )
+ * // Returns: [ { foo: 'bar', uuid: '...' } ]
+ * ```
+ */
+declare const addItemsUUID: <T extends object = object>(items: QueueItem<T> | QueuedItem<T> | QueueItems<T> | QueuedItems<T>) => QueuedItems<T>;
+/**
+ * Adds a UUID to the given item only when it does not already define one.
+ *
+ * @template T	The type of the given item, must extend object.
+ * @param item	The item to normalize with a UUID.
+ * @returns		A new item with a guaranteed UUID.
+ *
+ * @example
+ * ```ts
+ * const result = maybeAddItemUUID( { foo: 'bar' } )
+ * // Returns: { foo: 'bar', uuid: '...' }
+ * ```
+ */
+declare const maybeAddItemUUID: <T extends object = object>(item: QueueItem<T> | QueuedItem<T>) => QueuedItem<T>;
+/**
+ * Adds UUIDs to one or more items, preserving existing UUIDs when present.
+ *
+ * If a single item is provided, it is normalized to an array and returned as
+ * a one-element list.
+ *
+ * @template T	The type of the given item, must extend object.
+ * @param items	A single item or an array of items to normalize with UUIDs.
+ * @returns		An array of items with UUIDs on each item.
+ *
+ * @example
+ * ```ts
+ * const result = maybeAddItemsUUID( [ { foo: 'bar' }, { foo: 'baz', uuid: '1' } ] )
+ * // Returns: [ { foo: 'bar', uuid: '...' }, { foo: 'baz', uuid: '1' } ]
+ * ```
+ */
+declare const maybeAddItemsUUID: <T extends object = object>(items: QueueItem<T> | QueuedItem<T> | (QueueItem<T> | QueuedItem<T>)[]) => QueuedItems<T>;
+/**
+ * Finds the index of the item matching the given UUID.
+ *
+ * @param items	The queue items to search in.
+ * @param uuid	The UUID to match.
+ * @returns		The matching index, or `-1` when the UUID is missing or not found.
+ */
+declare const findIndexByUUID: (items: QueuedItems, uuid?: UUID) => number;
+interface GetEffectiveQueueOptions<T extends object = object> {
+    /**
+     * The main queue.
+     *
+     */
+    queue: QueuedItems<T>;
+    /**
+     * The custom queue.
+     *
+     */
+    customQueue: QueuedItems<T>;
+    /**
+     * The UUID after which the custom items are inserted.
+     *
+     */
+    uuid?: UUID;
+}
+/**
+ * Returns the queue with `customQueue` inserted after the item identified by `uuid`.
+ *
+ * If `uuid` is not provided, the original queue is returned unchanged. If `uuid`
+ * is provided but not found, `customQueue` is appended to the end of `queue`.
+ *
+ * @template T		The type of the queue items, must extend object.
+ * @param options	An object defining required parameters. See {@link GetEffectiveQueueOptions}.
+ * @returns			The effective queue.
+ */
+declare const getEffectiveQueue: <T extends object = object>(options: GetEffectiveQueueOptions<T>) => QueuedItems<T>;
+
+export { type GetEffectiveQueueOptions, addItemUUID, addItemsUUID, findIndexByUUID, getEffectiveQueue, maybeAddItemUUID, maybeAddItemsUUID };