@hitgrab/finder 0.1.17-alpha → 0.1.19-alpha

package/dist/index.d.mts

@@ -0,0 +1,538 @@
+import * as react0 from "react";
+import { ElementType, PropsWithChildren, ReactElement, ReactNode, RefObject } from "react";
+import * as react_jsx_runtime4 from "react/jsx-runtime";
+
+//#region src/core/types/rule-types.d.ts
+/**
+ * Select a property from the item to sort by.
+ */
+type FinderPropertySelector<FItem, FContext = any> = (item: FItem, context: FContext) => string | number;
+interface Rule {
+  id: string;
+  debounceMilliseconds?: number;
+  label?: string;
+  hidden?: boolean;
+}
+type RuleDefinition<FItem = any, FContext = any> = SearchRuleDefinition<FItem, FContext> | FilterRuleDefinition<FItem, FContext> | SortByRuleDefinition<FItem, FContext> | GroupByRuleDefinition<FItem, FContext>;
+interface SearchRuleDefinition<FItem = any, FContext = any> extends Omit<Rule, "id"> {
+  id?: string;
+  searchFn?: (item: FItem, context: FContext) => string | string[];
+}
+/**
+ * Describes the display of a filter or sort option.
+ */
+interface FilterOption<FValue = any> {
+  label?: string;
+  value: FValue;
+  disabled?: boolean;
+}
+interface FilterRuleDefinition<FItem = any, FValue = any, FContext = any> extends Rule {
+  filterFn: (item: FItem, value: FValue, context: FContext) => boolean;
+  required?: boolean;
+  strictOptions?: boolean;
+  multiple?: boolean;
+  boolean?: boolean;
+  options?: FilterOption<FValue>[] | ((options: {
+    items: FItem[];
+    context: FContext;
+  }) => FilterOption<FValue>[]);
+}
+type AnyFilterRuleDefinition<FItem = any, FValue = any> = Omit<FilterRuleDefinition<FItem, FValue>, "options">;
+interface FilterRuleWithBooleanValue<FItem = any, FValue = boolean, FContext = any> extends FilterRuleDefinition<FItem, FValue, FContext> {
+  multiple?: false;
+  boolean: true;
+  defaultValue?: boolean;
+  options?: never;
+}
+interface FilterRuleWithSingleValue<FItem = any, FValue = any, FContext = any> extends FilterRuleDefinition<FItem, FValue, FContext> {
+  multiple?: false;
+  boolean?: false;
+  defaultValue?: FValue;
+}
+interface FilterRuleWithMultipleValues<FItem = any, FValue = any, FContext = any> extends FilterRuleDefinition<FItem, FValue, FContext> {
+  multiple: true;
+  boolean?: false;
+  defaultValue?: FValue[];
+}
+/**
+ * A hydrated filter has rendered any option generator functions, and narrowed ambiguous properties from FilterRule.
+ */
+interface HydratedFilterRuleDefinition<FItem = any, FValue = any, FContext = any> extends FilterRuleDefinition<FItem, FValue, FContext> {
+  options?: FilterOption<FValue>[];
+  multiple: boolean;
+  boolean: boolean;
+  _isHydrated: true;
+}
+interface SortByRuleDefinition<FItem = any, FContext = any> extends Rule {
+  sortFn: FinderPropertySelector<FItem, FContext> | FinderPropertySelector<FItem, FContext>[];
+  defaultSortDirection?: SortDirection;
+}
+interface GroupByRuleDefinition<FItem = any, FContext = any> extends Rule {
+  groupFn: FinderPropertySelector<FItem, FContext>;
+  sortGroupFn?: FinderPropertySelector<FinderResultGroup<FItem>, FContext>;
+  defaultGroupSortDirection?: SortDirection;
+  sticky?: {
+    header?: string | string[];
+    footer?: string | string[];
+  };
+}
+interface FilterTestOptions {
+  rules: HydratedFilterRuleDefinition[];
+  values?: Record<string, any>;
+  isAdditive?: boolean;
+}
+interface FilterTestRuleOptions {
+  rule: string | AnyFilterRuleDefinition;
+  value: any;
+  isAdditive?: boolean;
+}
+//#endregion
+//#region src/core/core-constants.d.ts
+declare const EVENTS: {
+  readonly INIT: "init";
+  readonly FIRST_USER_INTERACTION: "firstUserInteraction";
+  readonly READY: "ready";
+  readonly CHANGE: "change";
+  readonly SET_ITEMS: "setItems";
+  readonly SET_IS_LOADING: "setIsLoading";
+  readonly SET_IS_DISABLED: "setIsDisabled";
+  readonly SET_CONTEXT: "setContext";
+  readonly SET_SEARCH_TERM: "setSearchTerm";
+  readonly RESET_SEARCH_TERM: "resetSearchTerm";
+  readonly SET_FILTER: "setFilter";
+  readonly RESET_FILTERS: "resetFilters";
+  readonly SET_SORT_BY: "setSortBy";
+  readonly SET_SORT_BY_DIRECTION: "setSortDirection";
+  readonly SET_GROUP_BY: "setGroupBy";
+  readonly SET_GROUP_SORT_BY_DIRECTION: "setGroupBySortDirection";
+  readonly SET_PAGE: "setPage";
+  readonly SET_NUM_ITEMS_PER_PAGE: "setNumItemsPerPage";
+  readonly SYNC_UPDATED_AT: "syncUpdatedAt";
+};
+declare const EVENT_SOURCE: {
+  readonly CORE: "core";
+  readonly SEARCH: "search";
+  readonly FILTERS: "filters";
+  readonly GROUP_BY: "groupBy";
+  readonly SORT_BY: "sortBy";
+  readonly PAGINATION: "pagination";
+};
+//#endregion
+//#region src/core/types/event-types.d.ts
+type FinderTouchSource = (typeof EVENT_SOURCE)[keyof typeof EVENT_SOURCE];
+interface FinderSharedEventProps {
+  source: string;
+  event: FinderEventName;
+  timestamp: number;
+  instance: FinderCore;
+}
+interface FinderInitEvent extends FinderSharedEventProps {
+  source: "core";
+  event: "init";
+}
+interface FinderFirstUserInteractionEvent extends FinderSharedEventProps {
+  source: "core";
+  event: "firstUserInteraction";
+}
+interface FinderReadyEvent extends FinderSharedEventProps {
+  source: "core";
+  event: "ready";
+}
+type FinderEvent = FinderInitEvent | FinderFirstUserInteractionEvent | FinderReadyEvent | FinderChangeEvent;
+type FinderOnInitCallback = (event: FinderInitEvent) => void;
+type FinderOnReadyCallback = (event: FinderReadyEvent) => void;
+type FinderOnFirstUserInteractCallback = (event: FinderFirstUserInteractionEvent) => void;
+type FinderOnChangeCallback = (event: FinderChangeEvent) => void;
+/**
+ * Internal communication between mixins and core
+ */
+interface FinderTouchEvent {
+  source: FinderTouchSource;
+  event: FinderEventName;
+  current: any;
+  initial: any;
+  rule?: RuleDefinition;
+}
+/**
+ * External type that consumers will receive
+ */
+type FinderChangeEvent = FinderTouchEvent & FinderSharedEventProps;
+type FinderEventName = (typeof EVENTS)[keyof typeof EVENTS];
+//#endregion
+//#region src/core/finder-core.d.ts
+/**
+ * This thin wrapper around FinderCoreImplementation defines the mixin interfaces and hides private methods.
+ */
+declare class FinderCore<FItem = any, FContext = any> {
+  #private;
+  constructor(items: FItem[] | null | undefined, options: FinderConstructorOptions<FItem, FContext>);
+  get items(): FItem[];
+  get context(): FContext;
+  get isReady(): boolean;
+  get isEmpty(): boolean;
+  get hasMatches(): boolean;
+  get isLoading(): boolean;
+  get disabled(): boolean;
+  get state(): "loading" | "empty" | "groups" | "items" | "noMatches";
+  get updatedAt(): number;
+  get events(): {
+    on: (event: FinderEventName, callback: EventCallback) => void;
+    off: (event: FinderEventName, callback: EventCallback) => void;
+    silently: (callback: EventCallback) => void;
+    isSilent: () => boolean;
+  };
+  /**
+   * Mixin interfaces
+   */
+  get matches(): ResultSnapshot<FItem>;
+  get search(): {
+    rule: SearchRuleDefinition<unknown, any> | undefined;
+    searchTerm: string;
+    hasSearchTerm: boolean;
+    hasSearchRule: boolean;
+    setSearchTerm: (value: string) => void;
+    reset: () => void;
+    test: (searchTerm: string, isAdditive?: boolean) => FItem[];
+  };
+  get filters(): {
+    values: Record<string, any>;
+    raw: Record<string, any>;
+    activeRules: HydratedFilterRuleDefinition<any, any, any>[];
+    rules: HydratedFilterRuleDefinition<any, any, any>[];
+    isActive: (identifier: string | AnyFilterRuleDefinition<any, any>) => boolean;
+    get: (identifier: string | AnyFilterRuleDefinition<any, any>) => any;
+    add: <FValue>(identifier: string | AnyFilterRuleDefinition<any, FValue>, optionValue?: FValue | FilterOption<FValue>) => void;
+    has: (identifier: string | AnyFilterRuleDefinition<any, any>, optionValue?: any) => boolean;
+    getRule: (identifier: string | AnyFilterRuleDefinition<any, any>) => HydratedFilterRuleDefinition<any, any, any>;
+    toggle: <FValue>(identifier: string | AnyFilterRuleDefinition<any, FValue>, optionValue?: FValue | FilterOption<FValue>) => void;
+    set: <FValue>(identifier: string | AnyFilterRuleDefinition<any, FValue>, value?: FValue | FValue[]) => void;
+    delete: <FValue>(identifier: string | AnyFilterRuleDefinition<any, FValue>, optionValue?: FValue | FilterOption<FValue>) => void;
+    reset: () => void;
+    test: (options: FilterTestOptions) => any[];
+    testRule: ({
+      rule: identifier,
+      value,
+      ...options
+    }: FilterTestRuleOptions) => any[];
+    testRuleOptions: (identifier: string | AnyFilterRuleDefinition<any, any>, isAdditive?: boolean) => Map<any, any>;
+  };
+  get sortBy(): {
+    activeRule: SortByRuleDefinition<unknown, any> | undefined;
+    sortDirection: SortDirection;
+    userHasSetSortDirection: boolean;
+    rules: SortByRuleDefinition<unknown, any>[];
+    set: (identifier?: string | SortByRuleDefinition, incomingSortDirection?: SortDirection) => void;
+    setSortDirection: (incomingSortDirection?: SortDirection) => void;
+    cycleSortDirection: () => void;
+    toggleSortDirection: () => void;
+    reset: () => void;
+  };
+  get groupBy(): {
+    activeRule: GroupByRuleDefinition<unknown, any> | undefined;
+    requireGroup: boolean;
+    rules: GroupByRuleDefinition<unknown, any>[];
+    groupBySortDirection: SortDirection | undefined;
+    set: (identifier?: string | GroupByRuleDefinition<any, any>) => void;
+    toggle: (identifier: string | GroupByRuleDefinition<any, any>) => void;
+    setGroupSortDirection: (direction?: SortDirection) => void;
+    reset: () => void;
+  };
+  get pagination(): {
+    page: number;
+    offset: number;
+    numItemsPerPage: number | undefined;
+    numTotalItems: number;
+    lastPage: number | undefined;
+    isPaginated: boolean;
+    setPage: (value: number) => void;
+    setNumItemsPerPage: (value?: number) => void;
+  };
+  /**
+   * Mutators
+   */
+  setItems(items: FItem[] | null | undefined): void;
+  setIsLoading(value?: boolean): void;
+  setIsDisabled(value?: boolean): void;
+  setRules(definitions: RuleDefinition<FItem>[]): void;
+  setContext(context: FContext): void;
+  /**
+   * Utils
+   */
+  test(mixins: SnapshotSerializedMixins, isAdditive?: boolean): FItem[];
+  getRule<T extends RuleDefinition<FItem>>(identifier: string | RuleDefinition<FItem>): T | undefined;
+  toJSON(): Omit<FinderConstructorOptions<FItem, any>, "rules">;
+}
+//#endregion
+//#region src/core/types/effect-types.d.ts
+interface RuleEffect<FItem = any, FContext = any> {
+  rules: string | RuleDefinition<FItem> | (string | RuleDefinition<FItem>)[] | ((items: FItem[], context: FContext) => string | RuleDefinition<FItem> | (string | RuleDefinition<FItem>)[]);
+  onChange: (instance: FinderCore<FItem, FContext>, rule: RuleDefinition<FItem>) => void;
+}
+interface SearchEffect<FItem = any, FContext = any> {
+  haystack: string | string[] | ((items: FItem[], context: FContext) => string | string[]);
+  onChange: (instance: FinderCore<FItem, FContext>, searchTerm: string) => void;
+}
+//#endregion
+//#region src/core/types/core-types.d.ts
+interface FinderConstructorOptions<FItem, FContext = any> {
+  rules: RuleDefinition<FItem>[];
+  effects?: (RuleEffect | SearchEffect)[];
+  context?: FContext;
+  isLoading?: boolean;
+  disabled?: boolean;
+  initialSearchTerm?: string;
+  initialSortBy?: string;
+  initialSortDirection?: SortDirection;
+  initialGroupBy?: string;
+  initialGroupBySortDirection?: SortDirection;
+  initialFilters?: Record<string, any>;
+  ignoreSortByRulesWhileSearchRuleIsActive?: boolean;
+  requireGroup?: boolean;
+  page?: number;
+  numItemsPerPage?: number;
+  onInit?: FinderOnInitCallback;
+  onReady?: FinderOnReadyCallback;
+  onFirstUserInteraction?: FinderOnFirstUserInteractCallback;
+  onChange?: FinderOnChangeCallback;
+}
+interface FinderResultGroup<FItem> {
+  id: string;
+  items: FItem[];
+}
+type SortDirection = "asc" | "desc" | ("asc" | "desc")[];
+interface ResultSnapshot<FItem> {
+  items?: FItem[];
+  groups?: FinderResultGroup<FItem>[];
+  numMatchedItems: number;
+  numTotalItems: number;
+  hasGroupByRule: boolean;
+}
+type EventCallback = (payload?: any) => void;
+interface SnapshotSerializedMixins {
+  search?: SerializedSearchMixin;
+  filters?: SerializedFiltersMixin;
+  sortBy?: SerializedSortByMixin;
+  pagination?: SerializedPaginationMixin;
+  groupBy?: SerializedGroupByMixin;
+}
+interface SerializedSearchMixin {
+  searchTerm: string;
+  rule?: SearchRuleDefinition;
+}
+interface SerializedFiltersMixin {
+  rules: HydratedFilterRuleDefinition[];
+  values: Record<string, any>;
+}
+interface SerializedSortByMixin {
+  rule?: SortByRuleDefinition;
+  sortDirection?: SortDirection;
+}
+interface SerializedPaginationMixin {
+  page: number;
+  numItemsPerPage?: number;
+}
+interface SerializedGroupByMixin {
+  rule?: GroupByRuleDefinition;
+  groupBySortDirection?: SortDirection;
+}
+interface PaginationMixinInterface {
+  page: number;
+  offset: number;
+  numItemsPerPage: number | undefined;
+  numTotalItems: number;
+  lastPage: number | undefined;
+  isPaginated: boolean;
+  setPage: (value: number) => void;
+  setNumItemsPerPage: (value: number) => void;
+}
+//#endregion
+//#region src/core/types/string-match-types.d.ts
+/**
+ *  These values all point to the transformed haystack.
+ */
+interface StringMatchSegment {
+  index: number;
+  length: number;
+  is_match: boolean;
+  value: string;
+}
+//#endregion
+//#region src/react/types/react-types.d.ts
+interface FinderProps<FItem, FContext> extends FinderConstructorOptions<FItem, FContext>, PropsWithChildren {
+  items: FItem[] | undefined | null;
+  controllerRef?: RefObject<FinderCore<FItem, FContext> | null>;
+}
+interface FinderContentProps<FItem = any, FContext = any> {
+  empty: {
+    pagination: PaginationMixinInterface;
+    context: FContext;
+  };
+  loading: {
+    pagination: PaginationMixinInterface;
+    context: FContext;
+  };
+  noMatches: {
+    pagination: PaginationMixinInterface;
+    context: FContext;
+  };
+  items: {
+    items: FItem[];
+    pagination: PaginationMixinInterface;
+    context: FContext;
+  };
+  groups: {
+    groups: FinderResultGroup<FItem>[];
+    pagination: PaginationMixinInterface;
+    context: FContext;
+  };
+}
+interface StringMatchSegmentProps {
+  segment: StringMatchSegment;
+  segmentIndex: number;
+}
+type FinderSearchTermProp = keyof HTMLElementTagNameMap | ElementType | ElementType<StringMatchSegmentProps>;
+//#endregion
+//#region src/core/utils/rule-type-enforcers.d.ts
+/**
+ * Enforce structure for an array of rule of mixed types.
+ */
+declare function finderRuleset<FItem, FContext = any>(rules: RuleDefinition<FItem, FContext>[]): RuleDefinition<FItem, FContext>[];
+declare function searchRule<FItem, FContext = any>(rule: SearchRuleDefinition<FItem, FContext>): SearchRuleDefinition<FItem, FContext>;
+declare function filterRule<FItem, FValue = any, FContext = any, T = FilterRuleWithMultipleValues<FItem, FValue, FContext>>(rule: T): FilterRuleWithMultipleValues<FItem, FValue>;
+declare function filterRule<FItem, FValue = boolean, FContext = any, T = FilterRuleWithBooleanValue<FItem, FValue, FContext>>(rule: T): FilterRuleWithBooleanValue<FItem, FValue>;
+declare function filterRule<FItem, FValue = any, FContext = any, T = FilterRuleWithSingleValue<FItem, FValue, FContext>>(rule: T): FilterRuleWithSingleValue<FItem, FValue>;
+declare function sortByRule<FItem, FContext = any>(rule: SortByRuleDefinition<FItem, FContext>): SortByRuleDefinition<FItem, FContext>;
+declare function groupByRule<FItem, FContext = any>(rule: GroupByRuleDefinition<FItem, FContext>): GroupByRuleDefinition<FItem, FContext>;
+declare function ruleEffect<FItem, FContext = any>(rules: string | RuleDefinition<FItem> | (string | RuleDefinition<FItem>)[] | ((items: FItem[], context: FContext) => string | RuleDefinition<FItem> | (string | RuleDefinition<FItem>)[]), onChange: (instance: FinderCore<FItem, FContext>, rule: RuleDefinition) => void): RuleEffect<FItem, FContext>;
+declare function searchEffect<FItem, FContext = any>(haystack: string | string[] | ((items: FItem[], context: FContext) => string | string[]), onChange: (instance: FinderCore<FItem, FContext>, searchTerm: string) => void): SearchEffect<FItem, FContext>;
+declare function transformFilterToSingleValue<FItem, FValue, FContext = any>(filter: AnyFilterRuleDefinition<FItem, FValue>): FilterRuleWithMultipleValues<FItem, FValue, FContext>;
+declare function transformFilterToBoolean<FItem, FValue, FContext = any>(filter: AnyFilterRuleDefinition<FItem, FValue>): FilterRuleWithBooleanValue<FItem, boolean, FContext>;
+declare function transformFilterToMultiple<FItem, FValue, FContext = any>(filter: AnyFilterRuleDefinition<FItem, FValue>): FilterRuleWithMultipleValues<FItem, FValue, FContext>;
+//#endregion
+//#region src/react/hooks/use-finder.d.ts
+declare function useFinder<FItem = any, FContext = undefined>(): FinderCore<FItem, FContext>;
+//#endregion
+//#region src/react/components/finder-content-loading.d.ts
+interface FinderContentLoadingProps<FItem, FContext> {
+  children: ElementType<FinderContentProps<FItem, FContext>["loading"]> | ReactElement<FinderContentProps<FItem, FContext>["loading"]> | Iterable<ReactNode>;
+}
+declare function FinderContentLoading<FItem, FContext>({
+  children: Component
+}: FinderContentLoadingProps<FItem, FContext>): react_jsx_runtime4.JSX.Element | Iterable<ReactNode> | null;
+//#endregion
+//#region src/react/components/finder-content-empty.d.ts
+interface FinderContentEmptyProps<FItem, FContext> {
+  children: ElementType<FinderContentProps<FItem, FContext>["empty"]> | ReactElement<FinderContentProps<FItem, FContext>["empty"]> | Iterable<ReactNode>;
+}
+declare function FinderContentEmpty<FItem = any, FContext = any>({
+  children: Component
+}: FinderContentEmptyProps<FItem, FContext>): react_jsx_runtime4.JSX.Element | Iterable<ReactNode> | null;
+//#endregion
+//#region src/react/components/finder-content-no-matches.d.ts
+interface FinderContentNoMatchesProps<FItem, FContext> {
+  children: ElementType<FinderContentProps<FItem, FContext>["noMatches"]> | ReactElement<FinderContentProps<FItem, FContext>["noMatches"]> | Iterable<ReactNode>;
+}
+declare function FinderContentNoMatches<FItem = any, FContext = any>({
+  children: Component
+}: FinderContentNoMatchesProps<FItem, FContext>): react_jsx_runtime4.JSX.Element | Iterable<ReactNode> | null;
+//#endregion
+//#region src/react/components/finder-content-items.d.ts
+interface FinderContentItemsProps<FItem, FContext> {
+  children: ElementType<FinderContentProps<FItem, FContext>["items"]> | ReactElement<FinderContentProps<FItem, FContext>["items"]> | Iterable<ReactNode>;
+}
+declare function FinderContentItems<FItem = any, FContext = any>({
+  children: Component
+}: FinderContentItemsProps<FItem, FContext>): react_jsx_runtime4.JSX.Element | Iterable<ReactNode> | null;
+//#endregion
+//#region src/react/components/finder-content-groups.d.ts
+interface FinderContentGroupsProps<FItem, FContext> {
+  children: ElementType<FinderContentProps<FItem, FContext>["groups"]> | ReactElement<FinderContentProps<FItem, FContext>["groups"]> | Iterable<ReactNode>;
+}
+declare function FinderContentGroups<FItem = any, FContext = any>({
+  children: Component
+}: FinderContentGroupsProps<FItem, FContext>): react_jsx_runtime4.JSX.Element | Iterable<ReactNode> | null;
+//#endregion
+//#region src/react/components/finder-content.d.ts
+interface FinderContentContainerProps<FItem, FContext> {
+  children: {
+    loading?: ElementType<FinderContentProps<FItem, FContext>["loading"]> | ReactElement<FinderContentProps<FItem, FContext>["loading"]> | Iterable<ReactNode>;
+    empty?: ElementType<FinderContentProps<FItem, FContext>["empty"]> | ReactElement<FinderContentProps<FItem, FContext>["empty"]> | Iterable<ReactNode>;
+    noMatches?: ElementType<FinderContentProps<FItem, FContext>["noMatches"]> | ReactElement<FinderContentProps<FItem, FContext>["noMatches"]> | Iterable<ReactNode>;
+    items?: ElementType<FinderContentProps<FItem, FContext>["items"]> | ReactElement<FinderContentProps<FItem, FContext>["items"]> | Iterable<ReactNode>;
+    groups?: ElementType<FinderContentProps<FItem, FContext>["groups"]> | ReactElement<FinderContentProps<FItem, FContext>["groups"]> | Iterable<ReactNode>;
+  };
+}
+declare function FinderContent<FItem = any, FContext = any>({
+  children: renderProps
+}: FinderContentContainerProps<FItem, FContext>): (react_jsx_runtime4.JSX.Element | undefined)[];
+declare namespace FinderContent {
+  var Loading: typeof FinderContentLoading;
+  var Empty: typeof FinderContentEmpty;
+  var NoMatches: typeof FinderContentNoMatches;
+  var Items: typeof FinderContentItems;
+  var Groups: typeof FinderContentGroups;
+}
+//#endregion
+//#region src/react/components/finder-search-term-haystack.d.ts
+interface FinderSearchTermHaystackProps {
+  children: string;
+  Match?: FinderSearchTermProp;
+  Miss?: FinderSearchTermProp;
+}
+declare function FinderSearchTermHaystack({
+  Match,
+  Miss,
+  children: haystack
+}: FinderSearchTermHaystackProps): string | react_jsx_runtime4.JSX.Element;
+//#endregion
+//#region src/react/components/finder.d.ts
+declare function Finder<FItem = any, FContext = any>({
+  items,
+  rules,
+  effects,
+  initialSearchTerm,
+  initialSortBy,
+  initialSortDirection,
+  initialGroupBy,
+  initialGroupBySortDirection,
+  initialFilters,
+  context,
+  isLoading,
+  disabled,
+  page,
+  numItemsPerPage,
+  requireGroup,
+  ignoreSortByRulesWhileSearchRuleIsActive,
+  onInit,
+  onReady,
+  onFirstUserInteraction,
+  onChange,
+  controllerRef,
+  children
+}: FinderProps<FItem, FContext>): react_jsx_runtime4.JSX.Element;
+declare namespace Finder {
+  var Content: typeof FinderContent;
+  var SearchTermHaystack: typeof FinderSearchTermHaystack;
+}
+//#endregion
+//#region src/react/hooks/use-finder-ref.d.ts
+declare function useFinderRef<FItem = any, FContext = any>(): react0.RefObject<FinderCore<FItem, FContext> | null>;
+//#endregion
+//#region src/react/components/string-match.d.ts
+interface StringMatchProps {
+  needle: string;
+  haystack: string;
+  Match?: FinderSearchTermProp;
+  Miss?: FinderSearchTermProp;
+}
+/**
+ * Split a string into result segment components .
+ */
+declare function StringMatch({
+  needle,
+  haystack,
+  Match,
+  Miss
+}: StringMatchProps): string | (string | react_jsx_runtime4.JSX.Element)[];
+//#endregion
+export { type AnyFilterRuleDefinition, type FilterOption, type FilterRuleDefinition, Finder, type FinderChangeEvent, type FinderConstructorOptions, type FinderContentProps, type FinderEvent, type FinderFirstUserInteractionEvent, type FinderInitEvent, type FinderProps, type FinderReadyEvent, type FinderResultGroup, type GroupByRuleDefinition, type RuleEffect, type SearchEffect, type SearchRuleDefinition, type SortByRuleDefinition, type SortDirection, StringMatch, type StringMatchSegmentProps, filterRule, finderRuleset, groupByRule, ruleEffect, searchEffect, searchRule, sortByRule, transformFilterToBoolean, transformFilterToMultiple, transformFilterToSingleValue, useFinder, useFinderRef };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{createContext as e,useContext as t,useImperativeHandle as n,useMemo as r,useRef as i,useState as a}from"react";import{jsx as o}from"react/jsx-runtime";import{clamp as s,debounce as c,groupBy as l,isEqual as u,orderBy as d,range as f,uniqBy as p}from"lodash";function m(e){return e}function h(e){return e}function g(e){return e}function _(e){return e}function v(e){return e}function y(e,t){return{rules:e,onChange:t}}function b(e,t){return{haystack:e,onChange:t}}function x(e){let t={...e};return delete t.boolean,delete t.multiple,t}function S(e){let t={...e};return delete t.multiple,{...t,boolean:!0}}function C(e){let t={...e};return delete t.boolean,{...t,multiple:!0}}const w=e(null);function T(){let e=t(w);if(e===null)throw Error(`useFinder requires a FinderContext.`);let[n]=e;return n}function E({children:e}){let t=T();return t.isLoading?typeof e==`function`?o(e,{pagination:t.pagination,context:t.context}):e:null}function D({children:e}){let t=T();return t.isEmpty?typeof e==`function`?o(e,{pagination:t.pagination,context:t.context}):e:null}function O({children:e}){let t=T();return t.isEmpty===!1&&t.hasMatches===!1?typeof e==`function`?o(e,{pagination:t.pagination,context:t.context}):e:null}function k({children:e}){let t=T();return t.hasMatches&&t.matches.items?typeof e==`function`?o(e,{items:t.matches.items,pagination:t.pagination,context:t.context}):e:null}function A({children:e}){let t=T();return t.hasMatches&&t.matches.groups?typeof e==`function`?o(e,{groups:t.matches.groups,pagination:t.pagination,context:t.context}):e:null}function j({children:e}){if(Object.values(e).length===0)throw Error(`No render props were found.`);return[e.loading&&o(E,{children:e.loading},`loading`),e.empty&&o(D,{children:e.empty},`empty`),e.noMatches&&o(O,{children:e.noMatches},`noMatches`),e.items&&o(k,{children:e.items},`items`),e.groups&&o(A,{children:e.groups},`groups`)]}j.Loading=E,j.Empty=D,j.NoMatches=O,j.Items=k,j.Groups=A;function M(e){return e.toLowerCase().replace(/[^\w\d]+/g,``)}function N(e,t){let n=new RegExp(/"(.*?)"/g),r=t,i=[],a,o=!1;for(;(a=n.exec(t))!==null&&o===!1;){let t=ee(e,M(String(a[1])));t===void 0?o=!0:(i=i.concat(t),r=r.replace(a[0],``))}if(o)return;let s=te(e,M(r));if(s!==void 0)return i=i.concat(s),i.sort((e,t)=>e-t)}function ee(e,t){if(e.length<t.length)return;let n=e.indexOf(t);if(n!==-1)return f(n,n+t.length).map(e=>e)}function te(e,t){if(e.length<t.length)return;let n=Array.from(t),r=[],i=e,a=0,o=!1;for(let e of n){let t=i.indexOf(e);if(t===-1&&(o=!0),o===!1){r.push(a+t);let e=t+1;a+=e,i=i.substring(e)}}if(!o)return r}var ne=class e{#e;constructor(t){this.source=t;let n=e.composeTransformedHaystackSegments(t);this.#e=n,this.transformed=n.map(e=>e.value).join(``).toLowerCase()}getSourceCharacterIndex(e){let t=0;return this.#e.reduce((n,r)=>{if(n!==1/0)return n;let i=t+r.value.length;if(e>=t&&e<=i){let i=e-t;n=r.index+i}return t+=r.value.length,n},1/0)}static composeTransformedHaystackSegments(e){let t=e.matchAll(/[\w\d]+/g),n=[];for(let e of t)n.push({value:e[0],index:e.index,length:e[0].length});return n}};function re(e,t){return(Array.isArray(e)?e:[e]).map(e=>new ne(e)).reduce((e,n)=>{if(e!==void 0)return e;let r=N(n.transformed,t);return r===void 0?e:oe(ae(n,ie(r,n.transformed)))},void 0)}function ie(e,t){let n=[...e],r=[],i=0;for(;n.length>0&&i<100;){let e=n.at(0);if(e===void 0)throw Error(`Should never get here`);let a=1;for(let t=1;t<=n.length;t+=1){let r=n.at(t);r!==void 0&&e+t===r&&(a+=1)}let o=e,s=e+a,c=t.substring(o,s);r.push({index:o,value:c,is_match:!0,length:c.length}),n.splice(0,a),i+=1}return r}function ae(e,t){return t.reduce((n,r,i)=>{if(i===0&&r.index!==0){let t=e.source.substring(0,e.getSourceCharacterIndex(r.index));n.push({index:0,value:t,is_match:!1,length:t.length})}let a=e.getSourceCharacterIndex(r.index),o=e.getSourceCharacterIndex(r.index+r.length),s=e.source.substring(a,o);n.push({index:a,value:s,is_match:!0,length:s.length});let c=t.at(i+1);if(c){let t=e.getSourceCharacterIndex(r.index+r.length),i=e.getSourceCharacterIndex(c.index),a=e.source.substring(t,i);n.push({index:t,value:a,is_match:!1,length:a.length})}else if(a+s.length!==e.source.length){let t=a+s.length,r=e.source.substring(t);n.push({index:t,value:r,is_match:!1,length:r.length})}return n},[])}function oe(e){let t=/\S/,n=[...e];return n.forEach((e,r)=>{if(e.is_match){let i=e.value.search(t);if(i!==0){let t=n.at(r-1);t&&(t.length+=i,t.value+=e.value.substring(0,i),e.value=e.value.substring(i),e.index+=i)}}}),n}function se(e,t){return(Array.isArray(e)?e:[e]).some(e=>N(M(e),t)!==void 0)}function P({needle:e,haystack:t,Match:n=`mark`,Miss:i}){let a=r(()=>re(t,e),[t,e]);return a===void 0?t:a.map((e,t)=>{let r=[e.value,t].join();return e.is_match?typeof n==`string`?o(n,{"data-is-match":e.is_match,children:e.value},r):o(n,{"data-is-match":e.is_match,segment:e,segmentIndex:t},r):i===void 0?e.value:typeof i==`string`?o(i,{"data-is-match":e.is_match,children:e.value},r):o(i,{"data-is-match":e.is_match,segment:e,segmentIndex:t},r)})}function ce({Match:e=`mark`,Miss:t,children:n}){let r=T();return r.search.hasSearchTerm===!1?n:o(P,{needle:r.search.searchTerm,haystack:n,Match:e,Miss:t})}function le(){let e=new Map;return(t,n)=>t.debounceMilliseconds===void 0?n():(e.has(t)===!1&&e.set(t,c(e=>e(),t.debounceMilliseconds)),e.get(t)?.(n))}var ue=class{#e=new Map;#t=!1;on(e,t){this.#e.has(e)===!1&&this.#e.set(e,new Set),this.#e.get(e)?.add(t)}off(e,t){if(this.#e.has(e)!==!1){if(t===void 0){this.#e.delete(e);return}this.#e.get(e)?.delete(t)}}emit(e,t){this.#t||this.#e.get(e)?.forEach(e=>{e(t)})}silently(e){this.#t=!0,e(),this.#t=!1}isSilent(){return this.#t}};const F={INIT:`init`,FIRST_USER_INTERACTION:`firstUserInteraction`,READY:`ready`,CHANGE:`change`,SET_ITEMS:`setItems`,SET_IS_LOADING:`setIsLoading`,SET_IS_DISABLED:`setIsDisabled`,SET_CONTEXT:`setContext`,SET_SEARCH_TERM:`setSearchTerm`,RESET_SEARCH_TERM:`resetSearchTerm`,SET_FILTER:`setFilter`,RESET_FILTERS:`resetFilters`,SET_SORT_BY:`setSortBy`,SET_SORT_BY_DIRECTION:`setSortDirection`,SET_GROUP_BY:`setGroupBy`,SET_GROUP_SORT_BY_DIRECTION:`setGroupBySortDirection`,SET_PAGE:`setPage`,SET_NUM_ITEMS_PER_PAGE:`setNumItemsPerPage`,SYNC_UPDATED_AT:`syncUpdatedAt`},I={CORE:`core`,SEARCH:`search`,FILTERS:`filters`,GROUP_BY:`groupBy`,SORT_BY:`sortBy`,PAGINATION:`pagination`},L={RULE_NOT_FOUND:`Finder could not locate requested rule`,WRONG_RULE_TYPE_FOR_MIXIN:`The requested rule is not valid for this mixin.`,NO_SEARCH_RULE_SET:`Unable to set search term; no SearchRule was found.`,INVALID_SEARCH_TERM_TYPE:`Search terms must be strings.`,NO_MATCHING_OPTION_FOUND_WITH_STRICT_OPTIONS:`Finder could not find a matching option with the passed value could be found. If this is intended, set 'strictOptions:false' in the rule definition.`,SETTING_MULTIPLE_FILTER_WITHOUT_ARRAY:`Finder could not set this filter value, as the rule requires an array.`,ADDING_OPTION_TO_MULTIPLE_FILTER_WITHOUT_OPTION_VALUE:`Finder could not add to this filter, as no optionValue was passed.`,DELETING_OPTION_VALUE_FROM_NON_MULTIPLE_FILTER:`Finder could not delete an option from this filter, as it does not support multiple values.`,SETTING_BOOLEAN_FILTER_WITHOUT_BOOLEAN_VALUE:`Finder could not set this filter value, as the rule requires a boolean.`,ADDING_OPTION_VALUE_TO_NON_MULTIPLE_FILTER:`Finder could not add to this filter value, as the rule is a boolean.`,TOGGLING_OPTION_ON_RULE_WITH_NO_OPTIONS:`Finder could not toggle this filter rule option, as the filter does not have any options.`,TOGGLING_OPTION_ON_RULE_WITH_SINGLE_VALUE:`Finder could not toggle this filter rule option, as the rule does not allow multiple values.`,TOGGLING_OPTION_THAT_DOES_NOT_EXIST:`Finder could not toggle this filter rule option, as the option was not found.`,TOGGLING_OPTION_WITHOUT_PASSING_OPTION:`Finder could not toggle this filter rule option, as the option was not found.`,TOGGLING_BOOLEAN_FILTER_WITH_UNUSED_VALUE:`Finder could not toggle this filter rule option, as boolean filters do not have options.`,TESTING_OPTIONS_ON_RULE_WITH_NO_OPTIONS:`Finder was unable to test the options for this filter rule. It must be a boolean or have defined options.`,INVALID_RULE_WITHOUT_ID:`Init failed: Missing rule id.`,INVALID_RULE_SHAPE:`Init failed: Malformed rule definition`,INVALID_RULE_DUPLICATE:`Init failed: Duplicate rule id.`};var R=class extends Error{constructor(e,t){let n=`${e} ${JSON.stringify({...t})}`;super(n),this.name=`FinderError`}};function z(e){return typeof e==`object`&&!!e&&`sortFn`in e}function B(e){return typeof e==`object`&&!!e&&`searchFn`in e}function V(e){return typeof e==`object`&&!!e&&`filterFn`in e}function H(e){return V(e)&&typeof e.options!=`function`}function U(e){return typeof e==`object`&&!!e&&`groupFn`in e}function de(e){return typeof e==`object`&&!!e&&(`rules`in e||`callback`in e)}function fe(e){return typeof e==`object`&&!!e&&(`haystack`in e||`callback`in e)}function pe(e){return V(e)&&e.boolean===!0}function me(e){return V(e)&&e.multiple===!0}function he(e){return V(e)&&e.multiple!==!0&&e.boolean!==!0}function ge(e){return{validate(t){if(t!==void 0&&typeof t!=`boolean`)throw new R(L.SETTING_BOOLEAN_FILTER_WITHOUT_BOOLEAN_VALUE,{rule:e,value:t});return!0},parse(t){return typeof t!=`boolean`&&t!==void 0?!1:t===void 0?e.required?!0:e.defaultValue===void 0?!1:e.defaultValue:t},has(e){return this.parse(e)},toggle(t,n){let r=this.parse(t);if(typeof r!=`boolean`)throw new R(L.SETTING_BOOLEAN_FILTER_WITHOUT_BOOLEAN_VALUE,{rule:e,value:r,optionValue:n});return!r},add(t,n){throw new R(L.ADDING_OPTION_VALUE_TO_NON_MULTIPLE_FILTER,{rule:e,value:t,optionValue:n})},delete(t,n){if(n!==void 0)throw new R(L.DELETING_OPTION_VALUE_FROM_NON_MULTIPLE_FILTER,{rule:e,value:t,optionValue:n})},isActive(t){return e.required?!0:this.parse(t)===!0},isMatch(t,n,r){return e.filterFn(t,n,r)}}}function _e(e){return{validate(t){if(t!==void 0&&Array.isArray(t)===!1)throw new R(L.SETTING_MULTIPLE_FILTER_WITHOUT_ARRAY,{rule:e,value:t});if(e.strictOptions&&Array.isArray(e.options)&&Array.isArray(t)&&t.every(t=>e.options?.some(e=>e.value===t))===!1)throw new R(L.NO_MATCHING_OPTION_FOUND_WITH_STRICT_OPTIONS,{rule:e,value:t});return!0},parse(t){if(t===void 0)return e.required&&Array.isArray(e.options)&&e.options.length>0?[e.options.at(0)?.value]:[];if(Array.isArray(t))return t;throw new R(L.SETTING_MULTIPLE_FILTER_WITHOUT_ARRAY,{rule:e,value:t})},has(t,n){if(n===void 0)return Array.isArray(t)&&t.length>0;if(Array.isArray(n))return n.every(t=>this.has(e,t));let r=e.options?.find(e=>typeof n==`object`&&`value`in n?e.value===n.value:e.value===n);return Array.isArray(t)&&r!==void 0&&t.includes(r.value)},toggle(t,n){let r=this.parse(t);if(Array.isArray(r)===!1)throw new R(L.SETTING_MULTIPLE_FILTER_WITHOUT_ARRAY,{rule:e,value:r});if(n===void 0)throw new R(L.TOGGLING_OPTION_WITHOUT_PASSING_OPTION,{rule:e});if(e.options===void 0)throw new R(L.TOGGLING_OPTION_ON_RULE_WITH_NO_OPTIONS,{rule:e,optionValue:n});let i=e.options.find(e=>typeof n==`object`&&`value`in n?e.value===n.value:e.value===n);if(i===void 0)throw new R(L.TOGGLING_OPTION_THAT_DOES_NOT_EXIST,{rule:e,optionValue:n});return r.includes(i.value)?[...r.filter(e=>e!==i.value)]:[...r,i.value]},add(t,n){let r=this.parse(t);if(n===void 0)throw new R(L.ADDING_OPTION_TO_MULTIPLE_FILTER_WITHOUT_OPTION_VALUE,{rule:e,optionValue:n});let i=e.options?.find(e=>typeof n==`object`&&`value`in n?e.value===n.value:e.value===n);return i===void 0?[...r,n]:r.includes(i.value)===!1?[...r,i.value]:r},delete(t,n){if(n===void 0)return;let r=this.parse(t),i=e.options?.find(e=>typeof n==`object`&&`value`in n?e.value===n.value:e.value===n);return i!==void 0&&r.includes(i.value)?r.filter(e=>e!==i.value):r.filter(e=>e!==n)},isActive(t){return e.required?!0:this.parse(t).length>0},isMatch(t,n,r){return Array.isArray(n)?n.some(n=>e.filterFn(t,n,r)):!1}}}function ve(e){return{validate(t){if(e.strictOptions&&Array.isArray(e.options)&&e.options.find(e=>e.value===t)===void 0)throw new R(L.NO_MATCHING_OPTION_FOUND_WITH_STRICT_OPTIONS,{rule:e,value:t});return!0},parse(t){if(t===void 0&&e.required){if(e.defaultValue)return e.defaultValue;if(Array.isArray(e.options)&&e.options.length>0)return e.options.at(0)?.value}return t},has(e){return e!==void 0},toggle(t,n){throw new R(L.TOGGLING_OPTION_ON_RULE_WITH_SINGLE_VALUE,{rule:e,value:t,optionValue:n})},add(t,n){throw new R(L.ADDING_OPTION_VALUE_TO_NON_MULTIPLE_FILTER,{rule:e,value:t,optionValue:n})},delete(t,n){if(n!==void 0)throw new R(L.DELETING_OPTION_VALUE_FROM_NON_MULTIPLE_FILTER,{rule:e,value:t,optionValue:n})},isActive(t){return e.required?!0:!(t===void 0||typeof t==`string`&&t.trim()===``)},isMatch(t,n,r){return e.filterFn(t,n,r)}}}function W(e){if(me(e))return _e(e);if(pe(e))return ge(e);if(he(e))return ve(e);throw new R(L.INVALID_RULE_SHAPE,{definition:e})}var G=class{#e;#t;constructor({initialFilters:e},t){this.#e=e??{},this.#t=t}set(e,t){if(this.#t.isDisabled())return;let n=this.getRule(e),r=this.get(e),i=typeof t==`string`&&t.trim()===``?void 0:t;W(n).validate(t),!(this.#e[n.id]!==void 0&&this.#e[n.id]===i)&&this.#t.debouncer(n,()=>{this.#e={...this.#e,[n.id]:i},this.#t.touch({source:I.FILTERS,event:F.SET_FILTER,current:i,initial:r,rule:n})})}get rules(){return this.#t.getRuleBook().rules.filter(H)}get activeRules(){return this.rules.filter(e=>W(e).isActive(this.#e[e.id]))}get(e){let t=this.getRule(e),n=this.#e[t.id];return W(t).parse(n)}has(e,t){let n=this.getRule(e),r=this.#e[n.id];return W(n).has(r,t)}getRule(e){let t=this.#t.getRuleBook().getRule(e);if(!H(t))throw new R(L.WRONG_RULE_TYPE_FOR_MIXIN,{rule:t});return t}add(e,t){let n=this.getRule(e),r=this.#e[n.id];this.set(n,W(n).add(r,t))}delete(e,t){let n=this.getRule(e),r=this.#e[n.id];this.set(n,W(n).delete(r,t))}toggle(e,t){let n=this.getRule(e),r=this.#e[n.id];if(n.boolean&&t!==void 0)throw new R(L.TOGGLING_BOOLEAN_FILTER_WITH_UNUSED_VALUE,{rule:n,value:r});let i=W(n).toggle(r,t);this.set(n,i)}reset(){let e=this.values;this.#e={},this.#t.touch({source:I.FILTERS,event:F.RESET_FILTERS,current:this.values,initial:e})}isRuleActive(e){let t=this.getRule(e),n=this.#e[t.id];return W(t).isActive(n)}test(e){if(this.#t.isLoading())return[];if(e.isAdditive){let t=p([...this.rules,...e.rules],`id`),n={...this.values,...e.values};return this.#t.test({filters:{rules:t,values:n}},!0)}return this.#t.test({filters:{rules:e.rules,values:e.values??{}}})}testRule({rule:e,value:t,...n}){let r=this.getRule(e);return this.test({rules:[r],values:{[r.id]:t},...n})}testRuleOptions(e,t){if(this.#t.isLoading())return new Map;let n=this.getRule(e);if(n.boolean){let e=new Map;return e.set(!0,this.testRule({rule:n,value:!0})),e.set(!1,this.testRule({rule:n,value:!1})),e}if(Array.isArray(n.options)){let e=new Map;return n.options.forEach(r=>{let i;i=n.multiple?[r.value]:r.value,e.set(r,this.testRule({rule:n,value:i,isAdditive:t}))}),e}throw new R(L.TESTING_OPTIONS_ON_RULE_WITH_NO_OPTIONS,n)}get values(){return this.rules.reduce((e,t)=>(e[t.id]=this.get(t),e),{})}get raw(){return this.#e}serialize(){return{rules:this.rules,values:this.values}}static process(e,t,n){let r=e.rules.filter(t=>H(t)&&W(t).isActive(e.values[t.id]));return r.length===0?t:t.filter(t=>r.every(r=>H(r)&&W(r).isMatch(t,e.values[r.id],n)))}},K=class{#e;#t;#n;constructor({initialGroupBy:e,initialGroupBySortDirection:t,requireGroup:n},r){this.#n=r,e&&(this.#e=this.getRule(e)),this.#t=t,this.requireGroup=n}getRule(e){let t=this.#n.getRuleBook().getRule(e);if(U(t)===!1)throw new R(L.WRONG_RULE_TYPE_FOR_MIXIN,{rule:t});return t}get rules(){return this.#n.getRuleBook().rules.filter(U)}get activeRule(){let e=this.requireGroup?this.rules.at(0):void 0;return this.#e??e}get hasGroupByRule(){return this.activeRule!==void 0}get groupBySortDirection(){return this.#t??this.activeRule?.defaultGroupSortDirection}set(e){if(this.#n.isDisabled())return;let t=this.#e,n,r=typeof e==`string`&&e.trim()===``;r&&(n=void 0),r===!1&&e!==void 0&&(n=this.getRule(e)),this.#e!==n&&(this.#e=n,this.#t=void 0,this.#n.touch({source:I.GROUP_BY,event:F.SET_GROUP_BY,current:n?.id,initial:t?.id,rule:n}))}setGroupSortDirection(e){let t=this.#t;this.#t=e,this.#n.touch({source:I.GROUP_BY,event:F.SET_GROUP_SORT_BY_DIRECTION,current:e,initial:t,rule:this.activeRule})}toggle(e){let t=this.getRule(e);if(this.activeRule===t){this.set(void 0);return}this.set(t)}reset(){this.setGroupSortDirection(void 0),this.set(void 0)}serialize(){return{rule:this.activeRule,groupBySortDirection:this.#t}}static process(e,t,n){let r=l(t,t=>e.rule?.groupFn(t,n)),i=Object.entries(r).map(([e,t])=>({id:e,items:t})),a=e.rule?.sticky!==void 0,o=[],s=[];return a&&e.rule&&(o.push(ye(e.rule)),s.push(`asc`)),e.rule?.sortGroupFn&&(o.push(e.rule.sortGroupFn),s.push(e.groupBySortDirection??`asc`)),o.length>0?d(i,o,s):i}};function ye(e){let t=[];e.sticky?.header!==void 0&&(Array.isArray(e.sticky.header)&&(t=e.sticky.header),typeof e.sticky.header==`string`&&(t=[e.sticky.header]));let n=[];return e.sticky?.footer!==void 0&&(Array.isArray(e.sticky.footer)&&(n=e.sticky.footer),typeof e.sticky.footer==`string`&&(n=[e.sticky.footer])),e=>{if(t.includes(e.id)){let n=t.findIndex(t=>e.id===t);return(t.length-n)*-1}return n.includes(e.id)?1+n.findIndex(t=>e.id===t):0}}var q=class{#e;#t;constructor({page:e,numItemsPerPage:t},n){this.#e=e??1,this.numItemsPerPage=t,this.#t=n}setPage(e){if(e!==this.#e){let t=this.#e;this.#e=e,this.#t.touch({source:I.PAGINATION,event:F.SET_PAGE,current:{page:this.#e},initial:{page:t}})}}setNumItemsPerPage(e){if(e!==this.numItemsPerPage){let t=this.numItemsPerPage;this.numItemsPerPage=e,this.#t.touch({source:I.PAGINATION,event:F.SET_NUM_ITEMS_PER_PAGE,current:{numItemsPerPage:this.numItemsPerPage},initial:{numItemsPerPage:t}})}}get lastPage(){if(this.numItemsPerPage!==void 0)return Math.ceil(this.#t.getItems().length/this.numItemsPerPage)}get numTotalItems(){return this.#t.getItems().length}get page(){return this.numItemsPerPage&&this.lastPage?s(this.#e,1,this.lastPage):this.#e}get offset(){return this.numItemsPerPage&&this.lastPage?(s(this.#e,1,this.lastPage)-1)*this.numItemsPerPage:0}serialize(){return{page:this.#e,numItemsPerPage:this.numItemsPerPage}}static process(e,t){if(e.numItemsPerPage===void 0)return t;let n=Math.ceil(t.length/e.numItemsPerPage),r=(s(e.page,1,n)-1)*e.numItemsPerPage;return t.slice(r,r+e.numItemsPerPage)}};function be(e,t){let n=e.length/t.length,r=1,i=1,a=0;for(let t=0;t<e.length;t+=1)a!==void 0&&e.at(t)===a+1&&(i+=1,i>=r&&(r=i)),a=e.at(t);return{percentOfHaystackMatched:n,longestSequentialSequence:r}}function xe(e,t,n){let r=t.reduce((t,r)=>{if(e.rule?.searchFn===void 0)return t;let i=e.rule.searchFn(r,n),a=(Array.isArray(i)?i.map(M):[M(i)]).reduce((t,n)=>{let r=N(n,e.searchTerm);return r!==void 0&&t.push(be(r,n)),t},[]);if(a.length>0){let e=d(a,[`percentOfHaystackMatched`,`longestSequentialSequence`],[`desc`,`asc`]).at(0);e&&t.push({item:r,score:e})}return t},[]),i=r.reduce((e,t)=>(t.score.longestSequentialSequence>e&&(e=t.score.longestSequentialSequence),e),0);return d(r,[e=>e.score.percentOfHaystackMatched*100+e.score.longestSequentialSequence/i*100],[`desc`]).map(e=>e.item)}var J=class{#e;constructor({initialSearchTerm:e},t){if(this.searchTerm=``,e&&t.getRuleBook().rules.find(B)===void 0)throw new R(L.NO_SEARCH_RULE_SET);this.searchTerm=e??``,this.#e=t}get rule(){return this.#e.getRuleBook().rules.find(B)}get hasSearchRule(){return this.rule!==void 0}get hasSearchTerm(){return this.searchTerm!==``}setSearchTerm(e){let t=this.rule;if(!t)throw new R(L.NO_SEARCH_RULE_SET);if(typeof e!=`string`)throw new R(L.INVALID_SEARCH_TERM_TYPE);if(this.#e.isDisabled())return;let n=this.searchTerm;this.searchTerm=e,n!==e&&this.#e.debouncer(t,()=>{this.#e.touch({source:I.SEARCH,event:F.SET_SEARCH_TERM,current:e,initial:n,rule:t})})}reset(){if(this.#e.isDisabled())return;let e=this.searchTerm;this.searchTerm=``,this.#e.touch({source:I.SEARCH,event:F.RESET_SEARCH_TERM,current:``,initial:e,rule:this.rule})}serialize(){return{searchTerm:this.searchTerm,rule:this.rule}}test(e,t=!1){return this.#e.test({search:{searchTerm:e,rule:this.rule}},t)}static process(e,t,n){if(e.rule===void 0)throw new R(L.NO_SEARCH_RULE_SET);return e.searchTerm===``?t:xe(e,t,n)}};const Y=[void 0,`desc`,`asc`];var X=class{#e;#t;#n;constructor({initialSortBy:e,initialSortDirection:t},n){this.#n=n,e&&(this.#e=this.getRule(e)),this.#t=t}getRule(e){let t=this.#n.getRuleBook().getRule(e);if(z(t)===!1)throw new R(L.WRONG_RULE_TYPE_FOR_MIXIN,{rule:t});return t}get rules(){return this.#n.getRuleBook().rules.filter(z)}get activeRule(){let e=this.rules.at(0);return this.#e??e}get sortDirection(){return this.#t??this.activeRule?.defaultSortDirection??`asc`}get userHasSetSortDirection(){return this.#t!==void 0}setSortDirection(e){if(this.#n.isDisabled()||!this.activeRule)return;let t=this.#t;this.#t=e,this.#n.touch({source:I.SORT_BY,event:F.SET_SORT_BY_DIRECTION,current:{sortDirection:e},initial:{sortDirection:t},rule:this.activeRule})}cycleSortDirection(){let e=Y.findIndex(e=>e===this.#t);if(e!==-1){let t=e+1%(Y.length-1);this.setSortDirection(Y[t])}}toggleSortDirection(){if((this.#t??this.activeRule?.defaultSortDirection)===`desc`){this.setSortDirection(`asc`);return}this.setSortDirection(`desc`)}set(e,t){if(this.#n.isDisabled()||!this.activeRule)return;let n=this.#t,r=this.#e,i=e?this.getRule(e):void 0;this.#e=i,this.#t=t,this.#n.touch({source:I.SORT_BY,event:F.SET_SORT_BY,current:{rule:i?.id,sortDirection:t},initial:{rule:r?.id,sortDirection:n},rule:this.activeRule})}reset(){this.set(void 0,void 0)}serialize(){return{rule:this.activeRule,sortDirection:this.sortDirection}}static process(e,t,n){return e.rule===void 0?t:d(t,t=>typeof e.rule?.sortFn==`function`?e.rule.sortFn(t,n):-1/0,e.sortDirection)}},Z=class e{constructor(){this.snapshot={},this.isStale=!0}setIsStale(e){this.isStale=e}takeSnapshot({items:t,context:n,mixins:r}){let i=e.test({mixins:r,items:t,context:n}),a=r.pagination?q.process(r.pagination,i):i,o=[],s=r.groupBy!==void 0;r.groupBy&&(o=K.process(r.groupBy,a,n)),this.snapshot={items:s?void 0:a,groups:s?o:void 0,numMatchedItems:i.length,numTotalItems:t.length,hasGroupByRule:s}}static test({mixins:e,items:t,context:n}){let r=[...t];return e.search&&(r=J.process(e.search,r,n)),e.filters&&(r=G.process(e.filters,r,n)),e.sortBy&&(r=X.process(e.sortBy,r,n)),r}},Se=class{#e;constructor(e){this.effects=[],this.#e=e}hydrateDefinitions(e,t){this.effects=this.#e.map(n=>{let r=typeof n.rules==`function`?n.rules(e,t):n.rules,i=Array.isArray(r)?r:[r];return{...n,rules:i,_isHydrated:!0}})}setEffects(e){this.#e=e}onChange(e,t){this.effects.forEach(n=>{n.rules.some(t=>typeof t==`string`&&e.id===t||typeof t==`object`&&e.id===t.id)&&n.onChange(t,e)})}},Ce=class e{constructor(t){this.rules=[],e.validateDefinitions(t),this.definitions=t}hydrateDefinitions(e,t){this.rules=this.definitions.map(n=>{if(V(n)){let r=typeof n.options==`function`?n.options({items:e,context:t}):n.options;return{...n,boolean:!!n.boolean,multiple:!!n.multiple,strictOptions:n.strictOptions??!0,options:r}}return n})}getRule(e){let t=this.rules.find(t=>typeof e==`object`?t.id===e.id:t.id===e);if(t===void 0)throw new R(L.RULE_NOT_FOUND,e);return t}setRules(t){e.validateDefinitions(t),this.definitions=t}static validateDefinitions(e){if(e.length===0)return!1;let t=[B,V,z,U],n=new Set;return e.forEach(e=>{if(e.id===void 0&&!B(e))throw new R(L.INVALID_RULE_WITHOUT_ID,e);if(t.some(t=>t(e))===!1)throw new R(L.INVALID_RULE_SHAPE,e);if(e.id){if(n.has(e.id))throw new R(L.INVALID_RULE_DUPLICATE,e);n.add(e.id)}}),!0}},we=class{#e;constructor(e){this.effects=[],this.#e=e}hydrateDefinitions(e,t){this.effects=this.#e.map(n=>{let r=typeof n.haystack==`function`?n.haystack(e,t):n.haystack,i=Array.isArray(r)?r:[r];return{...n,haystack:i}})}setEffects(e){this.#e=e}processSearchTerm(e,t){this.effects.forEach(n=>{se(n.haystack,e)&&n.onChange(t,e)})}},Q=class{constructor({rules:e,ruleEffects:t,searchEffects:n}){this.list=new Ce(e),this.ruleEffects=new Se(t),this.searchEffects=new we(n)}hydrateDefinitions(e,t){this.list.hydrateDefinitions(e,t),this.searchEffects.hydrateDefinitions(e,t),this.ruleEffects.hydrateDefinitions(e,t)}onChange(e,t){B(e)&&t.search.hasSearchTerm&&this.searchEffects.processSearchTerm(t.search.searchTerm,t),this.ruleEffects.onChange(e,t)}},Te=class{#e;#t=!1;#n;#r=new ue;#i=new Z;#a;constructor(e,{rules:t,effects:n,initialSearchTerm:r,initialSortBy:i,initialSortDirection:a,initialGroupBy:o,initialGroupBySortDirection:s,initialFilters:c,context:l,page:u,numItemsPerPage:d,isLoading:f,disabled:p,requireGroup:m,ignoreSortByRulesWhileSearchRuleIsActive:h,onInit:g,onReady:_,onFirstUserInteraction:v,onChange:y},b){this.isReady=!1,this.#e=e,this.disabled=!!p,this.isLoading=!!f,this.isReady=!f&&Array.isArray(e)&&e.length>0,this.getInstanceInterfaceFn=b,this.updatedAt=Date.now(),this.context=l,this.#n=h,this.#a=new Q({rules:t,ruleEffects:n?.filter(de)??[],searchEffects:n?.filter(fe)??[]}),this.#a.hydrateDefinitions(e??[],l);let x={getItems:()=>this.items,getRuleBook:()=>this.#a.list,isLoading:()=>this.isLoading,isDisabled:()=>this.disabled,test:(e,t)=>this.test(e,t),touch:e=>this.#o(e),debouncer:le()};this.search=new J({initialSearchTerm:r},x),this.filters=new G({initialFilters:c},x),this.sortBy=new X({initialSortBy:i,initialSortDirection:a},x),this.groupBy=new K({initialGroupBy:o,initialGroupBySortDirection:s,requireGroup:!!m},x),this.pagination=new q({page:u,numItemsPerPage:d},x),this.#r.silently(()=>{let e={source:I.CORE,event:F.INIT,timestamp:Date.now(),instance:this.getInstanceInterfaceFn()};g&&g(e)}),y&&this.#r.on(F.CHANGE,y),v&&this.#r.on(F.FIRST_USER_INTERACTION,v),_&&this.isReady&&_({source:I.CORE,event:F.READY,timestamp:Date.now(),instance:this.getInstanceInterfaceFn()}),this.isReady===!1&&_&&this.#r.on(F.READY,_)}#o(e){if(this.#r.isSilent())return;this.emitFirstUserInteraction(),this.#c(),this.#i.setIsStale(!0);let t={...e,timestamp:Date.now(),instance:this.getInstanceInterfaceFn()};this.#r.emit(F.CHANGE,t),this.#r.silently(()=>{e.rule&&this.#a.onChange(e.rule,this.getInstanceInterfaceFn())})}#s(e){this.#i.setIsStale(!0),this.#c();let t={...e,timestamp:Date.now(),instance:this.getInstanceInterfaceFn()};this.#r.emit(e.event,t)}#c(){this.updatedAt=Date.now(),this.#r.emit(F.SYNC_UPDATED_AT,this.updatedAt)}emitFirstUserInteraction(){if(this.#t===!1){this.#t=!0;let e={source:I.CORE,event:F.FIRST_USER_INTERACTION,timestamp:Date.now(),instance:this.getInstanceInterfaceFn()};this.#r.emit(F.FIRST_USER_INTERACTION,e)}}#l(){this.isReady===!1&&(this.isReady=!0,this.#r.emit(F.READY,{source:I.CORE,event:F.READY,timestamp:Date.now()}))}get items(){return Array.isArray(this.#e)?this.#e:[]}get matches(){return this.#i.isStale&&(this.#i.takeSnapshot({items:this.items,context:this.context,mixins:this.#u()}),this.#i.setIsStale(!1)),this.#i.snapshot}test(e,t=!1){if(t){let t={...this.#u(),...e};return Z.test({mixins:t,items:this.items,context:this.context})}return Z.test({mixins:e,items:this.items,context:this.context})}#u(){let e=this.search.hasSearchRule&&this.search.hasSearchTerm,t=e&&this.#n,n={};return e&&(n.search=this.search.serialize()),this.filters.activeRules.length>0&&(n.filters=this.filters.serialize()),this.pagination.numItemsPerPage&&(n.pagination=this.pagination.serialize()),t===!1&&(n.sortBy=this.sortBy.serialize()),this.groupBy.activeRule!==void 0&&(n.groupBy=this.groupBy.serialize()),n}get isEmpty(){return this.isLoading===!1&&this.items.length===0}get hasMatches(){let e=Array.isArray(this.matches.items)&&this.matches.items.length>0,t=Array.isArray(this.matches.groups)&&this.matches.groups.length>0;return e||t}get events(){return{on:(e,t)=>this.#r.on(e,t),off:(e,t)=>this.#r.off(e,t),silently:e=>this.#r.silently(e),isSilent:()=>this.#r.isSilent()}}getRule(e){return this.#a.list.getRule(e)}get state(){if(this.isLoading)return`loading`;if(this.isEmpty)return`empty`;let e=this.groupBy.activeRule!==void 0;return e&&Array.isArray(this.matches.groups)&&this.matches.groups.length>0?`groups`:e===!1&&Array.isArray(this.matches.items)&&this.matches.items.length>0?`items`:`noMatches`}setItems(e){if(u(e,this.#e)===!1){let t=this.#e;this.#e=e,this.#a.hydrateDefinitions(this.items,this.context),this.#s({source:I.CORE,event:F.SET_ITEMS,current:e,initial:t})}}setIsLoading(e){if(!!e!==this.isLoading){let t=this.isLoading;this.isLoading=!!e,this.#s({source:I.CORE,event:F.SET_IS_LOADING,current:!!e,initial:t}),this.isLoading===!1&&this.#l()}}setIsDisabled(e){if(!!e!==this.disabled){let t=this.disabled;this.disabled=!!e,this.#s({source:I.CORE,event:F.SET_IS_DISABLED,current:!!e,initial:t})}}setRules(e){u(e,this.#a.list.definitions)===!1&&(this.#a.list.setRules(e),this.#a.list.hydrateDefinitions(this.items,this.context))}setContext(e){let t=this.context;u(e,t)===!1&&(this.context=e,this.#a.hydrateDefinitions(this.items,this.context),this.#s({source:I.CORE,event:F.SET_CONTEXT,current:e,initial:t}))}toJSON(){return{disabled:this.disabled,initialSearchTerm:this.search.searchTerm,initialFilters:this.filters.raw,page:this.pagination.page,numItemsPerPage:this.pagination.numItemsPerPage,initialSortBy:this.sortBy.activeRule?.id,initialSortDirection:this.sortBy.sortDirection,ignoreSortByRulesWhileSearchRuleIsActive:this.#n,initialGroupBy:this.groupBy.activeRule?.id,initialGroupBySortDirection:this.groupBy.groupBySortDirection,requireGroup:this.groupBy.requireGroup}}},Ee=class{#e;constructor(e,t){this.#e=new Te(e,t,()=>this)}get items(){return this.#e.items}get context(){return this.#e.context}get isReady(){return this.#e.isReady}get isEmpty(){return this.#e.isEmpty}get hasMatches(){return this.#e.hasMatches}get isLoading(){return this.#e.isLoading}get disabled(){return this.#e.disabled}get state(){return this.#e.state}get updatedAt(){return this.#e.updatedAt}get events(){return this.#e.events}get matches(){return this.#e.matches}get search(){let e=this.#e.search;return{rule:e.rule,searchTerm:e.searchTerm,hasSearchTerm:e.hasSearchTerm,hasSearchRule:e.hasSearchRule,setSearchTerm:e.setSearchTerm.bind(e),reset:e.reset.bind(e),test:e.test.bind(e)}}get filters(){let e=this.#e.filters;return{values:e.values,raw:e.raw,activeRules:e.activeRules,rules:e.rules,isActive:e.isRuleActive.bind(e),get:e.get.bind(e),add:e.add.bind(e),has:e.has.bind(e),getRule:e.getRule.bind(e),toggle:e.toggle.bind(e),set:e.set.bind(e),delete:e.delete.bind(e),reset:e.reset.bind(e),test:e.test.bind(e),testRule:e.testRule.bind(e),testRuleOptions:e.testRuleOptions.bind(e)}}get sortBy(){let e=this.#e.sortBy;return{activeRule:e.activeRule,sortDirection:e.sortDirection,userHasSetSortDirection:e.userHasSetSortDirection,rules:e.rules,set:e.set.bind(e),setSortDirection:e.setSortDirection.bind(e),cycleSortDirection:e.cycleSortDirection.bind(e),toggleSortDirection:e.toggleSortDirection.bind(e),reset:e.reset.bind(e)}}get groupBy(){let e=this.#e.groupBy;return{activeRule:e.activeRule,requireGroup:e.requireGroup,rules:e.rules,groupBySortDirection:e.groupBySortDirection,set:e.set.bind(e),toggle:e.toggle.bind(e),setGroupSortDirection:e.setGroupSortDirection.bind(e),reset:e.reset.bind(e)}}get pagination(){let e=this.#e.pagination;return{page:e.page,offset:e.offset,numItemsPerPage:e.numItemsPerPage,numTotalItems:e.numTotalItems,lastPage:e.lastPage,isPaginated:e.numItemsPerPage!==void 0,setPage:e.setPage.bind(e),setNumItemsPerPage:e.setNumItemsPerPage.bind(e)}}setItems(e){return this.#e.setItems(e)}setIsLoading(e){return this.#e.setIsLoading(e)}setIsDisabled(e){return this.#e.setIsDisabled(e)}setRules(e){return this.#e.setRules(e)}setContext(e){return this.#e.setContext(e)}test(e,t=!1){return this.#e.test(e,t)}getRule(e){return this.#e.getRule(e)}toJSON(){return this.#e.toJSON()}};function $({items:e,rules:t,effects:i,initialSearchTerm:s,initialSortBy:c,initialSortDirection:l,initialGroupBy:u,initialGroupBySortDirection:d,initialFilters:f,context:p,isLoading:m,disabled:h,page:g,numItemsPerPage:_,requireGroup:v,ignoreSortByRulesWhileSearchRuleIsActive:y,onInit:b,onReady:x,onFirstUserInteraction:S,onChange:C,controllerRef:T,children:E}){let[D,O]=a(Date.now()),[k]=a(()=>{let n=new Ee(e,{rules:t,effects:i,initialSearchTerm:s,initialSortBy:c,initialSortDirection:l,initialGroupBy:u,initialGroupBySortDirection:d,initialFilters:f,context:p,isLoading:m,disabled:h,page:g,numItemsPerPage:_,requireGroup:v,ignoreSortByRulesWhileSearchRuleIsActive:y,onInit:b,onReady:x,onFirstUserInteraction:S,onChange:C});return n.events.on(F.SYNC_UPDATED_AT,e=>O(e)),n});k.setItems(e),k.setIsLoading(m),k.setIsDisabled(h),k.setRules(t),p!==void 0&&k.setContext(p),g!==void 0&&k.pagination.setPage(g),_!==void 0&&k.pagination.setNumItemsPerPage(_),n(T,()=>k,[k]);let A=r(()=>[k,D],[k,D]);return o(w.Provider,{value:A,children:E})}$.Content=j,$.SearchTermHaystack=ce;function De(){return i(null)}export{$ as Finder,P as StringMatch,g as filterRule,m as finderRuleset,v as groupByRule,y as ruleEffect,b as searchEffect,h as searchRule,_ as sortByRule,S as transformFilterToBoolean,C as transformFilterToMultiple,x as transformFilterToSingleValue,T as useFinder,De as useFinderRef};

package/package.json

@@ -1,30 +1,21 @@
 {
     "name": "@hitgrab/finder",
-    "version": "0.1.17-alpha",
-    "description": "Headless datatables for things that aren't tables.",
+    "version": "0.1.19-alpha",
+    "description": "Effortless data manipulation with static rules.",
     "type": "module",
     "files": [
         "dist/**/*"
     ],
-    "main": "./dist/index.umd.cjs",
-    "types": "./dist/index.d.ts",
+    "main": "./dist/index.cjs",
+    "types": "./dist/index.d.cts",
     "module": "./dist/index.js",
     "exports": {
-        ".": {
-            "import": {
-                "types": "./dist/index.d.ts",
-                "default": "./dist/index.js"
-            },
-            "require": {
-                "types": "./dist/index.d.ts",
-                "default": "./dist/index.umd.cjs"
-            }
-        },
+        ".": "./dist/index.cjs",
         "./package.json": "./package.json"
     },
     "scripts": {
         "dev": "vite",
-        "build": "vite build && tsc --project tsconfig.production.json",
+        "build": "tsdown",
         "build:docs": "npm --prefix docusaurus run build && rm -r docs && cp -r ./docusaurus/build ./docs && mkdir ./docs/examples && mkdir ./docs/examples/armory && mkdir ./docs/examples/shoes",
         "build:armory": "npm --prefix examples/pixel-armory run build && rm -r ./docs/examples/armory && cp -r ./examples/pixel-armory/dist ./docs/examples/armory",
         "build:shoes": "npm --prefix examples/shoe-store run build && rm -r ./docs/examples/shoes && cp -r ./examples/shoe-store/dist ./docs/examples/shoes",
@@ -39,7 +30,8 @@
         "filter",
         "search",
         "sort",
-        "group"
+        "group",
+        "paginate"
     ],
     "author": "HitGrab Inc.",
     "license": "ISC",
@@ -57,6 +49,7 @@
         "eslint-plugin-react": "^7.37.5",
         "eslint-plugin-react-hooks": "^5.2.0",
         "prettier": "^3.6.2",
+        "tsdown": "^0.16.1",
         "typescript": "^5.9.3",
         "typescript-eslint": "^8.46.1",
         "vite": "^7.1.9",