@dereekb/util 13.0.7 → 13.2.0

package/src/lib/value/indexed.d.ts

@@ -31,8 +31,8 @@ export interface IndexRef {
 /**
  * Convenience function for calling readKeysToMap() and keying the values by their index number.
  *
- * @param items
- * @returns
+ * @param items - array of IndexRef items to index
+ * @returns a Map keyed by each item's index number
  */
 export declare function indexRefMap<T extends IndexRef>(items: T[]): Map<IndexNumber, T>;
 /**
@@ -40,10 +40,16 @@ export declare function indexRefMap<T extends IndexRef>(items: T[]): Map<IndexNu
  */
 export type MaybeIndexRef<T extends IndexRef> = Omit<T, 'i'> & Partial<Pick<T, 'i'>>;
 /**
- * Creates a SortCompareFunction<T> that sorts by index on IndexRef values.
+ * Creates a SortCompareFunction that sorts IndexRef values in ascending order by their index number.
  *
- * @param input
- * @returns
+ * @returns a compare function suitable for Array.sort()
+ *
+ * @example
+ * ```ts
+ * const items = [{ i: 4 }, { i: 0 }, { i: 2 }];
+ * items.sort(sortAscendingIndexNumberRefFunction());
+ * // items[0].i === 0
+ * ```
  */
 export declare function sortAscendingIndexNumberRefFunction<T extends IndexRef>(): SortCompareFunction<T>;
 /**
@@ -57,8 +63,8 @@ export type ReadMaybeIndexFunction<T> = (value: T) => Maybe<IndexNumber>;
 /**
  * Reads an IndexNumber from an IndexRef.
  *
- * @param indexRef
- * @returns
+ * @param indexRef - the ref to read from
+ * @returns the index number value
  */
 export declare function readIndexNumber(indexRef: IndexRef): IndexNumber;
 export interface IndexDeltaGroup<T> {
@@ -77,14 +83,42 @@ export interface IndexDeltaGroup<T> {
      */
     readonly deletedItems?: T[];
 }
+/**
+ * Function that separates items into new, current, and deleted groups based on their index assignment.
+ */
 export type IndexDeltaGroupFunction<T> = (inputItems: T[], previousItems?: Maybe<T[]>) => IndexDeltaGroup<T>;
+/**
+ * Creates an {@link IndexDeltaGroupFunction} that separates items into new (no index), current (has index),
+ * and deleted (present in previous but missing from current) groups. Useful for computing deltas when
+ * items are added or removed from an indexed collection.
+ *
+ * @param readIndex - reads an item's index, returning null/undefined for unindexed items
+ * @returns a function that groups items by their index state
+ *
+ * @example
+ * ```ts
+ * const groupFn = indexDeltaGroupFunction<{ x: string; i?: number }>((x) => x.i);
+ * const result = groupFn([{ x: 'a' }, { x: 'b', i: 0 }, { x: 'c', i: 1 }]);
+ *
+ * // result.newItems.length === 1     (item without an index)
+ * // result.currentItems.length === 2 (items with indexes)
+ * ```
+ */
 export declare function indexDeltaGroupFunction<T>(readIndex: ReadMaybeIndexFunction<T>): IndexDeltaGroupFunction<T>;
+/**
+ * Convenience function that creates and immediately invokes an {@link IndexDeltaGroupFunction}.
+ *
+ * @param readIndex - reads an item's index
+ * @param inputItems - the current set of items
+ * @param previousItems - the previous set of items for computing deletions
+ * @returns the grouped delta result
+ */
 export declare function indexDeltaGroup<T>(readIndex: ReadMaybeIndexFunction<T>, inputItems: T[], previousItems?: Maybe<T[]>): IndexDeltaGroup<T>;
 /**
- * Creates a SortCompareFunction<T> that sorts by the read index.
+ * Creates a SortCompareFunction that sorts items in ascending order using a custom index reader.
  *
- * @param input
- * @returns
+ * @param readIndex - extracts the index number from each item
+ * @returns a compare function suitable for Array.sort()
  */
 export declare function sortByIndexAscendingCompareFunction<T>(readIndex: ReadIndexFunction<T>): SortCompareFunction<T>;
 /**
@@ -94,11 +128,28 @@ export declare function sortByIndexAscendingCompareFunction<T>(readIndex: ReadIn
  */
 export type ComputeNextFreeIndexFunction<T> = (values: T[]) => IndexNumber;
 /**
- * Creates a new ComputeNextFreeIndexFunction.
+ * Creates a {@link ComputeNextFreeIndexFunction} that finds the maximum index in the input and returns the next available one.
+ * Returns 0 when the input is empty.
+ *
+ * @param readIndex - extracts the index number from each item
+ * @param nextIndex - optional custom function to compute the next index from the max item; defaults to max + 1
+ * @returns a function that computes the next free index for a given array
+ *
+ * @example
+ * ```ts
+ * const fn = computeNextFreeIndexFunction<IndexRef>((x) => x.i);
+ * const nextIndex = fn([{ i: 0 }, { i: 1 }, { i: 5 }]);
+ * // nextIndex === 6
+ * ```
  */
 export declare function computeNextFreeIndexFunction<T>(readIndex: ReadIndexFunction<T>, nextIndex?: (value: T) => IndexNumber): ComputeNextFreeIndexFunction<T>;
 /**
- * Creates a new ComputeNextFreeIndexFunction that assumes that the input values are sorted in ascending order, with the latest index at the end.
+ * Creates a {@link ComputeNextFreeIndexFunction} optimized for pre-sorted input arrays.
+ * Instead of scanning all items for the maximum, it reads only the last element.
+ *
+ * @param readIndex - extracts the index number from each item
+ * @param nextIndex - optional custom function to compute the next index from the last item; defaults to last + 1
+ * @returns a function that computes the next free index from sorted arrays
  */
 export declare function computeNextFreeIndexOnSortedValuesFunction<T>(readIndex: ReadIndexFunction<T>, nextIndex?: (value: T) => IndexNumber): ComputeNextFreeIndexFunction<T>;
 /**
@@ -108,17 +159,25 @@ export type MinAndMaxIndexFunction<T> = ((values: Iterable<T>) => MinAndMaxFunct
     readonly _readIndex: ReadIndexFunction<T>;
 };
 /**
- * Returns a MinAndMaxIndexFunction.
+ * Creates a {@link MinAndMaxIndexFunction} that extracts the minimum and maximum index numbers from a collection.
  *
- * @param readIndex
- * @returns
+ * @param readIndex - extracts the index number from each item
+ * @returns a function returning the min/max indexes, or null for empty input
+ *
+ * @example
+ * ```ts
+ * const fn = minAndMaxIndexFunction<IndexRef>((x) => x.i);
+ * const result = fn([{ i: 3 }, { i: 0 }, { i: 5 }]);
+ * // result?.min === 0, result?.max === 5
+ * ```
  */
 export declare function minAndMaxIndexFunction<T>(readIndex: ReadIndexFunction<T>): MinAndMaxIndexFunction<T>;
 /**
- * Returns the min and max index value from the input IndexRef values.
+ * Returns the min and max index numbers from an array of IndexRef values.
+ * Convenience wrapper around {@link minAndMaxIndexFunction} using {@link readIndexNumber}.
  *
- * @param values
- * @returns
+ * @param values - the IndexRef items to scan
+ * @returns the min/max indexes, or null for empty input
  */
 export declare function minAndMaxIndex<T extends IndexRef>(values: T[]): MinAndMaxFunctionResult<IndexNumber>;
 /**
@@ -128,17 +187,18 @@ export type MinAndMaxIndexItemsFunction<T> = MinAndMaxFunction<T> & {
     readonly _readIndex: ReadIndexFunction<T>;
 };
 /**
- * Returns a MinAndMaxIndexItemsFunction.
+ * Creates a {@link MinAndMaxIndexItemsFunction} that returns the actual items (not just index numbers)
+ * with the minimum and maximum index values.
  *
- * @param readIndex
- * @returns
+ * @param readIndex - extracts the index number from each item
+ * @returns a function returning the min/max items, or null for empty input
  */
 export declare function minAndMaxIndexItemsFunction<T>(readIndex: ReadIndexFunction<T>): MinAndMaxIndexItemsFunction<T>;
 /**
- * Creates a HashSet with items keyed by their IndexNumber for the input values.
+ * Creates a HashSet with items keyed by their IndexNumber, providing O(1) lookups by index.
  *
- * @param input
- * @returns
+ * @param input - optional initial values to populate the set
+ * @returns a HashSet keyed by index number
  */
 export declare function hashSetForIndexed<T extends IndexRef>(input?: ArrayOrValue<T>): HashSet<IndexNumber, T>;
 export interface FindItemsByIndexInput<T extends IndexRef> extends Pick<FindValuesFromInput<T, IndexNumber>, 'values' | 'exclude'> {
@@ -148,40 +208,63 @@ export interface FindItemsByIndexInput<T extends IndexRef> extends Pick<FindValu
     readonly indexes: ArrayOrValue<IndexNumber>;
 }
 /**
- * Convenience function to return all values that match one of the input indexes.
+ * Returns all values whose index matches one of the specified indexes.
+ *
+ * @param config - specifies the values to search, indexes to match, and optional exclusion flag
+ * @returns the matching items
  *
- * @param values
+ * @example
+ * ```ts
+ * const values = [{ i: 0, name: '0' }, { i: 1, name: '1' }, { i: 2, name: '2' }];
+ * const result = findItemsByIndex({ values, indexes: [1, 2] });
+ * // result contains items with i === 1 and i === 2
+ * ```
  */
 export declare function findItemsByIndex<T extends IndexRef>(config: FindItemsByIndexInput<T>): T[];
 /**
  * Finds the best index match given the configured objects and returns the best match.
  */
 export type FindBestIndexMatchFunction<T> = <I extends IndexRef>(value: I) => T;
-export declare function findBestIndexMatchFunction<T extends IndexRef>(items: Iterable<T>): FindBestIndexMatchFunction<T>;
 /**
- * Finds the best match given the input.
+ * Creates a {@link FindBestIndexMatchFunction} from a set of IndexRef items.
+ * Given an input index, returns the item with the highest index that is less than or equal to the input.
+ *
+ * @param items - the available match options; must not be empty
+ * @returns a function that finds the best match for any input index
+ * @throws {Error} When the input iterable is empty
  *
- * Throws an error if the input is an empty array.
+ * @example
+ * ```ts
+ * const options = [{ i: 0 }, { i: 5 }, { i: 10 }];
+ * const fn = findBestIndexMatchFunction(options);
  *
- * @param input
- * @param i
- * @returns
+ * fn({ i: 4 });  // returns { i: 0 }
+ * fn({ i: 6 });  // returns { i: 5 }
+ * fn({ i: 11 }); // returns { i: 10 }
+ * ```
  */
-export declare function findBestIndexMatch<T extends IndexRef>(input: T[], i: IndexNumber): T;
+export declare function findBestIndexMatchFunction<T extends IndexRef>(items: Iterable<T>): FindBestIndexMatchFunction<T>;
 /**
- * Finds the best match given the input.
+ * Finds the best match for the given index from the input array.
+ * Returns the item with the highest index that is less than or equal to `i`.
  *
- * Returns undefined if the input is an empty array.
+ * @param input - the available match options
+ * @param i - the target index to match against
+ * @returns the best matching item
+ * @throws {Error} When the input array is empty
+ */
+export declare function findBestIndexMatch<T extends IndexRef>(input: T[], i: IndexNumber): T;
+/**
+ * Safe variant of {@link findBestIndexMatch} that returns undefined instead of throwing when input is empty or null.
  *
- * @param input
- * @param i
- * @returns
+ * @param input - the available match options, or null/undefined
+ * @param i - the target index to match against
+ * @returns the best matching item, or undefined if input is empty/null
  */
 export declare function safeFindBestIndexMatch<T extends IndexRef>(input: Maybe<T[]>, i: IndexNumber): Maybe<T>;
 /**
- * Creates a FilterUniqueFunction that filters by the input value's index.
- *
- * @param readIndex
+ * Pre-built filter function that removes duplicate items based on their index number,
+ * keeping the first occurrence of each index.
  */
 export declare const filterUniqueByIndex: <T>(input: T[], exclude?: FilterUniqueFunctionExcludeKeysInput<T, IndexNumber>) => T[];
 /**
@@ -202,10 +285,11 @@ export interface IndexRange {
  */
 export type ReadIndexRangeFunction<T> = FactoryWithRequiredInput<IndexRange, T>;
 /**
- * Creates a SortCompareFunction<T> that sorts by the read index.
+ * Creates a SortCompareFunction that sorts items by their IndexRange in ascending order.
+ * Sorts by minIndex first, then by maxIndex for items with equal minIndex values.
  *
- * @param input
- * @returns
+ * @param readIndexRange - extracts the IndexRange from each item
+ * @returns a compare function suitable for Array.sort()
  */
 export declare function sortByIndexRangeAscendingCompareFunction<T>(readIndexRange: ReadIndexRangeFunction<T>): SortCompareFunction<T>;
 /**
@@ -220,44 +304,71 @@ export interface IndexRangeReaderPair<T = unknown> {
  */
 export type IndexRangeReaderPairFactory<T> = FactoryWithRequiredInput<IndexRangeReaderPair<T>, T>;
 /**
- * Creates a new IndexRangeReaderPairFactory
+ * Creates a new {@link IndexRangeReaderPairFactory} that pairs each value with its computed IndexRange.
  *
- * @param reader
- * @returns
+ * @param reader - reads the IndexRange from the input value
+ * @returns a factory that creates IndexRangeReaderPair instances
  */
 export declare function indexRangeReaderPairFactory<T>(reader: ReadIndexRangeFunction<T>): IndexRangeReaderPairFactory<T>;
 /**
- * An IndexNumber that represenst a range of a single index, or an IndexRange.
+ * An IndexNumber representing a single index, or a full IndexRange. Used as flexible input for functions
+ * that can accept either form.
  */
 export type IndexRangeInput = IndexNumber | IndexRange;
 /**
- * Creates an IndexRange from the input.
+ * Normalizes an {@link IndexRangeInput} to a full {@link IndexRange}. When given a single number,
+ * creates a range spanning that single index (minIndex = input, maxIndex = input + 1).
  *
- * @param input
- * @returns
+ * @param input - a single index number or an IndexRange
+ * @returns the normalized IndexRange
  */
 export declare function indexRange(input: IndexRangeInput): IndexRange;
+/**
+ * Clamps an IndexNumber to fit within a given IndexRange (inclusive min, exclusive max).
+ */
 export type FitToIndexRangeFunction = (input: IndexNumber) => IndexNumber;
+/**
+ * Creates a {@link FitToIndexRangeFunction} that clamps index numbers to the given range boundaries.
+ *
+ * @param input - the range to clamp to
+ * @returns a function that clamps any index to the range
+ */
 export declare function fitToIndexRangeFunction(input: IndexRange): FitToIndexRangeFunction;
+/**
+ * Wraps an IndexNumber around to the other side of a range when it goes out of bounds.
+ */
 export type WrapIndexNumberFunction = WrapNumberFunction;
 /**
- * Creates a WrapNumberFunction.
+ * Creates a {@link WrapIndexNumberFunction} that wraps index numbers around the range boundaries,
+ * similar to modular arithmetic. Values that exceed the max wrap to the min side and vice versa.
+ *
+ * @param input - the index range to wrap within
+ * @param fencePosts - whether to use fencepost semantics (maxIndex is exclusive); defaults to true
+ * @returns a function that wraps any index into the range
  *
- * @param input
- * @param fencePosts
- * @returns
+ * @example
+ * ```ts
+ * const wrap = wrapIndexRangeFunction({ minIndex: 0, maxIndex: 6 });
+ * wrap(6);  // 0 (wraps from positive side)
+ * wrap(-1); // 5 (wraps from negative side)
+ * ```
  */
 export declare function wrapIndexRangeFunction(input: IndexRange, fencePosts?: boolean): WrapIndexNumberFunction;
 /**
- * Checks whether or not the input number is in the range.
+ * Checks whether an item's index falls within a configured range.
  */
 export type IndexRefRangeCheckFunction<T> = (value: T) => boolean;
 /**
- * Creates an IndexRefRangeCheckFunction
+ * Creates an {@link IndexRefRangeCheckFunction} that reads an item's index and checks whether it falls
+ * within the specified range. For IndexRef types, the index is read from `i` automatically.
  *
- * @param range
+ * @param input - the range or range config to check against
  */
 export declare function indexRangeCheckReaderFunction<T extends IndexRef>(input: IndexRangeFunctionInput): IndexRefRangeCheckFunction<T>;
+/**
+ * @param input - the range or range config to check against
+ * @param read - custom function to extract the index from the item
+ */
 export declare function indexRangeCheckReaderFunction<T>(input: IndexRangeFunctionInput, read: ReadIndexFunction<T>): IndexRefRangeCheckFunction<T>;
 /**
  * Checks whether or not the input number is in the range.
@@ -273,87 +384,147 @@ export interface IndexRangeFunctionConfig {
      */
     readonly inclusiveMaxIndex: boolean;
 }
+/**
+ * Flexible input for range-checking functions: either a plain {@link IndexRange} or a full {@link IndexRangeFunctionConfig}
+ * with inclusive/exclusive options.
+ */
 export type IndexRangeFunctionInput = IndexRange | IndexRangeFunctionConfig;
+/**
+ * Normalizes an {@link IndexRangeFunctionInput} to a full {@link IndexRangeFunctionConfig},
+ * defaulting `inclusiveMaxIndex` to false when a plain IndexRange is provided.
+ *
+ * @param input - the range or config to normalize
+ * @returns the normalized config
+ */
 export declare function asIndexRangeCheckFunctionConfig(input: IndexRangeFunctionInput): IndexRangeFunctionConfig;
 /**
- * Creates an IndexRangeCheckFunction
+ * Creates an {@link IndexRangeCheckFunction} that tests whether an index number falls within the configured range.
+ * The min is inclusive and the max is exclusive by default unless `inclusiveMaxIndex` is set.
  *
- * @param range
+ * @param input - the range or range config to check against
+ * @returns a predicate function for index numbers
  */
 export declare function indexRangeCheckFunction(input: IndexRangeFunctionInput): IndexRangeCheckFunction;
 /**
  * Returns true if the input index is contained within the configured IndexRange.
  */
 export type IsIndexNumberInIndexRangeFunction = (index: IndexNumber) => boolean;
+/**
+ * Checks whether a single index number falls within the given IndexRange.
+ *
+ * @param index - the index number to test
+ * @param indexRange - the range to test against
+ * @param inclusiveMaxIndex - whether the max boundary is inclusive; defaults to false
+ * @returns true if the index is within range
+ */
 export declare function isIndexNumberInIndexRange(index: IndexNumber, indexRange: IndexRange, inclusiveMaxIndex?: boolean): boolean;
 /**
- * Creates an IsIndexNumberInIndexRangeFunction
+ * Creates an {@link IsIndexNumberInIndexRangeFunction} bound to the given range configuration.
  *
- * @param indexRange
- * @returns
+ * @param input - the range or range config to bind
+ * @returns a predicate that tests index numbers against the bound range
  */
 export declare function isIndexNumberInIndexRangeFunction(input: IndexRangeFunctionInput): IsIndexNumberInIndexRangeFunction;
 /**
  * Returns true if the input IndexRange is contained within the configured IndexRange.
  */
 export type IsIndexRangeInIndexRangeFunction = (indexRange: IndexRange) => boolean;
+/**
+ * Checks whether `compareIndexRange` is entirely contained within `indexRange`.
+ *
+ * @param compareIndexRange - the range to test
+ * @param indexRange - the bounding range
+ * @returns true if the compare range is fully contained
+ */
 export declare function isIndexRangeInIndexRange(compareIndexRange: IndexRange, indexRange: IndexRange): boolean;
 /**
- * Creates an IsIndexRangeInIndexRangeFunction
+ * Creates an {@link IsIndexRangeInIndexRangeFunction} bound to the given range configuration.
  *
- * @param indexRange
- * @returns
+ * @param input - the bounding range or range config to bind
+ * @returns a predicate that tests whether index ranges are fully contained
  */
 export declare function isIndexRangeInIndexRangeFunction(input: IndexRangeFunctionInput): IsIndexRangeInIndexRangeFunction;
 /**
  * Returns true if the input IndexRange overlaps the configured IndexRange in any way.
  */
 export type IndexRangeOverlapsIndexRangeFunction = (indexRange: IndexRange) => boolean;
+/**
+ * Checks whether `compareIndexRange` overlaps `indexRange` in any way (partial or full).
+ *
+ * @param compareIndexRange - the range to test for overlap
+ * @param indexRange - the reference range
+ * @returns true if any portion of the ranges overlap
+ */
 export declare function indexRangeOverlapsIndexRange(compareIndexRange: IndexRange, indexRange: IndexRange): boolean;
 /**
- * Creates an IndexRangeOverlapsIndexRangeFunction
+ * Creates an {@link IndexRangeOverlapsIndexRangeFunction} bound to the given range configuration.
  *
- * @param indexRange
- * @returns
+ * @param input - the reference range or range config to bind
+ * @returns a predicate that tests for overlap with the bound range
  */
 export declare function indexRangeOverlapsIndexRangeFunction(input: IndexRangeFunctionInput): IndexRangeOverlapsIndexRangeFunction;
 /**
- * Returns an array of all IndexNumbers within the input IndexRange.
- *
- * maxIndex is exclusive.
+ * Returns an array of all IndexNumbers within the input IndexRange (minIndex inclusive, maxIndex exclusive).
  *
- * @param indexRange
- * @returns
+ * @param indexRange - the range to enumerate
+ * @returns an array of sequential index numbers
  */
 export declare function allIndexesInIndexRange(indexRange: IndexRange): IndexNumber[];
+/**
+ * Configuration for {@link stepsFromIndexFunction}.
+ */
 export interface StepsFromIndexFunctionConfig {
+    /**
+     * The index range to step within.
+     */
     readonly range: IndexRange;
     /**
-     * Whether or not to fit start indexes that are outside of the range. If false, then returns undefined.
+     * Whether to clamp out-of-range start indexes into the range. When false, out-of-range starts return undefined.
      */
     readonly fitToRange?: boolean;
     /**
-     * Whether or not to wrap the index to the other side of the range when stepping outside the bounds of the range.
+     * Whether to wrap around to the other side of the range when stepping past the boundaries.
      */
     readonly wrapAround?: boolean;
     /**
-     * Whether or not to use fencePosts. Defaults to true.
+     * Whether to use fencepost semantics for wrapping. Defaults to true.
      */
     readonly fencePosts?: boolean;
+    /**
+     * Default number of steps to take. Defaults to 1.
+     */
     readonly steps?: number;
 }
+/**
+ * Steps forward or backward from a start index within a range, with optional wrap-around and fit-to-range behavior.
+ * Exposes its bound config via the `_config` property.
+ */
 export type StepsFromIndexFunction = ((startIndex: number, wrapAround?: boolean, steps?: number) => Maybe<number>) & {
     readonly _config: StepsFromIndexFunctionConfig;
 };
-export declare function stepsFromIndexFunction(config: StepsFromIndexFunctionConfig): StepsFromIndexFunction;
 /**
- * Steps to the next index in the given direction based on the number of steps to take.
+ * Creates a {@link StepsFromIndexFunction} that computes the next index after stepping from a start position.
+ * Returns undefined when the result falls outside the range (unless wrapping or fitting is enabled).
  *
- * Starting indexes less than the minIndex are considered to not exist and will return undefined.
+ * @param config - stepping behavior configuration
+ * @returns a function that computes the stepped index
+ */
+export declare function stepsFromIndexFunction(config: StepsFromIndexFunctionConfig): StepsFromIndexFunction;
+/**
+ * Convenience function that steps from a start index within a range without pre-creating a reusable function.
  *
- * When wrapAround is true, indexes that are larger than the max index will be used to find an index that is that many steps into the index range.
+ * Start indexes outside the range return undefined. When `wrapAround` is true, out-of-bound results
+ * wrap to the other side of the range (e.g., stepping past maxIndex wraps to minIndex).
  *
- * For instance, an index of 5 on a range of 0 to 3 will return the index 1.
+ * @param range - the index range to step within
+ * @param startIndex - the starting position
+ * @param step - number of steps to take (positive or negative); defaults to 1
+ * @param wrapAround - whether to wrap out-of-bound results; defaults to false
+ * @returns the resulting index, or undefined if out of bounds without wrapping
  */
 export declare function stepsFromIndex(range: IndexRange, startIndex: number, step?: number, wrapAround?: boolean): Maybe<number>;
+/**
+ * Pre-built decision function factory for determining whether an IndexRef item is selected,
+ * using the item's index number as the selection key.
+ */
 export declare const isSelectedIndexDecisionFunction: import("..").IsSelectedDecisionFunctionFactory<IndexRef, number>;

package/src/lib/value/label.d.ts

@@ -1,20 +1,31 @@
 import { type PrimativeKey } from '../key';
 /**
- * Refernce to a label string.
+ * Reference to a human-readable label string.
  */
 export interface LabelRef {
     label: string;
 }
 /**
- * Labeled value
+ * Pairs a value with a human-readable label, useful for dropdown options, tags, and display lists.
  */
 export interface LabeledValue<T> extends LabelRef {
     value: T;
 }
 /**
- * Creates a new Map of LabeledValue values.
+ * Creates a {@link Map} from an array of {@link LabeledValue} items, keyed by each item's value.
  *
- * @param values
- * @returns
+ * Enables fast lookup of labeled items by their value key.
+ *
+ * @param values - array of labeled values to index
+ *
+ * @example
+ * ```ts
+ * const items: LabeledValue<string>[] = [
+ *   { value: 'a', label: 'Alpha' },
+ *   { value: 'b', label: 'Beta' }
+ * ];
+ * const map = labeledValueMap(items);
+ * map.get('a')?.label; // 'Alpha'
+ * ```
  */
 export declare function labeledValueMap<V extends LabeledValue<T>, T extends PrimativeKey>(values: V[]): Map<T, V>;