@hybridly/vue 0.4.4 → 0.5.0

package/dist/index.d.cts

@@ -7,6 +7,7 @@ import { Axios, AxiosResponse, AxiosProgressEvent } from 'axios';
 import * as _vue_shared from '@vue/shared';
 import { RequestData } from '@hybridly/utils';
 import { SearchableObject, Path, PathValue } from '@clickbar/dot-diver';
+import * as hybridly from 'hybridly';
 
 interface ProgressOptions {
     /**
@@ -121,6 +122,14 @@ declare const RouterLink: vue.DefineComponent<{
         type: PropType<boolean | "hover" | "mount">;
         default: boolean;
     };
+    preserveScroll: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    preserveState: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
 }, (props: _vue_shared.LooseRequired<{
     readonly data: RequestData;
     readonly method: "delete" | Method$1 | "get" | "post" | "put" | "patch";
@@ -130,6 +139,8 @@ declare const RouterLink: vue.DefineComponent<{
     readonly disabled: boolean;
     readonly preload: boolean | "hover" | "mount";
     readonly text?: string | undefined;
+    readonly preserveScroll?: boolean | undefined;
+    readonly preserveState?: boolean | undefined;
     readonly href?: string | undefined;
 } & {}>) => vue.VNode<vue.RendererNode, vue.RendererElement, {
     [key: string]: any;
@@ -172,9 +183,19 @@ declare const RouterLink: vue.DefineComponent<{
         type: PropType<boolean | "hover" | "mount">;
         default: boolean;
     };
+    preserveScroll: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    preserveState: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
 }>>, {
     data: RequestData;
     text: string;
+    preserveScroll: boolean;
+    preserveState: boolean;
     href: string;
     method: "delete" | Method$1 | "get" | "post" | "put" | "patch";
     options: Omit<HybridRequestOptions$1, "data" | "url" | "method">;
@@ -185,7 +206,7 @@ declare const RouterLink: vue.DefineComponent<{
 }, {}>;
 
 /** Accesses all current properties. */
-declare function useProperties<T extends object, Global extends GlobalHybridlyProperties>(): vue.DeepReadonly<vue.UnwrapNestedRefs<T & Global>>;
+declare function useProperties<T extends object, Global extends GlobalHybridlyProperties = GlobalHybridlyProperties>(): vue.DeepReadonly<vue.UnwrapNestedRefs<T & Global>>;
 /** Accesses a property with a dot notation. */
 declare function useProperty<Override = never, T extends SearchableObject = GlobalHybridlyProperties, P extends Path<T> & string = Path<T> & string, ReturnType = [Override] extends [never] ? PathValue<T, P> : Override>(path: [Override] extends [never] ? P : string): ComputedRef<ReturnType>;
 /**
@@ -255,7 +276,7 @@ interface Hooks extends RequestHooks {
          */
     initialized: (context: InternalRouterContext) => MaybePromise<any>;
     /**
-     * Called after Hybridly's initial page load.
+     * Called after Hybridly's initial load.
      */
     ready: (context: InternalRouterContext) => MaybePromise<any>;
     /**
@@ -265,15 +286,21 @@ interface Hooks extends RequestHooks {
     /**
      * Called when a component navigation is being made.
      */
-    navigating: (options: NavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
+    navigating: (options: InternalNavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
     /**
      * Called when a component has been navigated to.
      */
-    navigated: (options: NavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
+    navigated: (options: InternalNavigationOptions, context: InternalRouterContext) => MaybePromise<any>;
     /**
      * Called when a component has been navigated to and was mounted by the adapter.
      */
-    mounted: (context: InternalRouterContext) => MaybePromise<any>;
+    mounted: (options: InternalNavigationOptions & MountedHookOptions, context: InternalRouterContext) => MaybePromise<any>;
+}
+interface MountedHookOptions {
+    /**
+     * Whether the component being mounted is a dialog.
+     */
+    isDialog: boolean;
 }
 
 interface RoutingConfiguration {
@@ -300,9 +327,9 @@ interface NavigationOptions {
      * one. This affects the browser's "back" and "forward" features.
      */
     replace?: ConditionalNavigationOption<boolean>;
-    /** Whether to preserve the scrollbars positions on the page. */
+    /** Whether to preserve the scrollbars positions on the view. */
     preserveScroll?: ConditionalNavigationOption<boolean>;
-    /** Whether to preserve the current page component's state. */
+    /** Whether to preserve the current view component's state. */
     preserveState?: ConditionalNavigationOption<boolean>;
     /** Whether to preserve the current URL. */
     preserveUrl?: ConditionalNavigationOption<boolean>;
@@ -321,16 +348,22 @@ interface NavigationOptions {
      * @internal This is an advanced property meant to be used internally.
      */
     updateHistoryState?: boolean;
+}
+interface InternalNavigationOptions extends NavigationOptions {
     /**
-     * Defines whether this navigation is a back/forward navigation from the popstate event.
-     * @internal This is an advanced property meant to be used internally.
+     * Defines the kind of navigation being performed.
+     * - initial: the initial load's navigation
+     * - server: a navigation initiated by a server round-trip
+     * - local: a navigation initiated by `router.local`
+     * - back-forward: a navigation initiated by the browser's `popstate` event
+     * @internal
      */
-    isBackForward?: boolean;
+    type: 'initial' | 'local' | 'back-forward' | 'server';
     /**
-     * Defines whether this navigation is the first to happen after a direct page load.
-     * @internal This is an advanced property meant to be used internally.
+     * Defines whether this navigation opens a dialog.
+     * @internal
      */
-    isInitial?: boolean;
+    hasDialog?: boolean;
 }
 type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 interface HybridRequestOptions extends Omit<NavigationOptions, 'payload'> {
@@ -375,15 +408,17 @@ interface PendingNavigation {
     /** Current status. */
     status: 'pending' | 'success' | 'error';
 }
-/** A page or dialog component. */
+/** A view or dialog component. */
 interface View {
     /** Name of the component to use. */
-    component: string;
+    component?: string;
     /** Properties to apply to the component. */
     properties: Properties;
+    /** Deferred properties for this view. */
+    deferred: string[];
 }
-interface Dialog extends View {
-    /** URL that is the base background page when navigating to the dialog directly. */
+interface Dialog extends Required<View> {
+    /** URL that is the base background view when navigating to the dialog directly. */
     baseUrl: string;
     /** URL to which the dialog should redirect when closed. */
     redirectUrl: string;
@@ -403,6 +438,8 @@ interface SwapOptions<T> {
     preserveState?: boolean;
     /** Current dialog. */
     dialog?: Dialog;
+    /** On mounted callback. */
+    onMounted?: (options: MountedHookOptions) => void;
 }
 type ViewComponent = any;
 type ResolveComponent = (name: string) => Promise<ViewComponent>;
@@ -579,6 +616,20 @@ declare global {
         meta: PaginatorMeta;
         links: PaginatorLink[];
     }
+    /**
+     * Simple-paginated data with metadata in a `meta` wrap.
+     */
+    interface SimplePaginator<T = any> {
+        data: T[];
+        meta: SimplePaginatorMeta;
+    }
+    /**
+     * Cursor paginator.
+     */
+    interface CursorPaginator<T = any> {
+        data: T[];
+        meta: CursorPaginatorMeta;
+    }
     /**
      * Paginated data without metadata wrapping.
      */
@@ -592,6 +643,24 @@ interface PaginatorLink {
     label: string;
     active: boolean;
 }
+interface CursorPaginatorMeta {
+    path: string;
+    per_page: number;
+    previous_cursor: string;
+    next_cursor: string;
+    next_page_url?: string;
+    previous_page_url?: string;
+}
+interface SimplePaginatorMeta {
+    path: string;
+    per_page: number;
+    current_page: number;
+    next_page_url?: string;
+    first_page_url: string;
+    prev_page_url?: string;
+    from: number;
+    to: number;
+}
 interface PaginatorMeta {
     path: string;
     from: number;
@@ -599,56 +668,17 @@ interface PaginatorMeta {
     total: number;
     per_page: number;
     current_page: number;
+    first_page: number;
     last_page: number;
     first_page_url: string;
     last_page_url: string;
-    next_page_url: string | undefined;
-    prev_page_url: string | undefined;
-    links?: PaginatorLink[];
+    next_page_url?: string;
+    prev_page_url?: string;
 }
-interface Item {
-    url: string | undefined;
-    label: string;
-    isPage: boolean;
-    isActive: boolean;
-    isPrevious: boolean;
-    isNext: boolean;
-    isCurrent: boolean;
-    isSeparator: boolean;
-}
-declare function usePaginator<T = any>(paginator: UnwrappedPaginator<T> | Paginator<T> | PaginatorMeta): {
-    pages: Item[];
-    items: Item[];
-    previous: Item;
-    next: Item;
-    first: {
-        isActive: boolean;
-        label: string;
-        url: string | undefined;
-        isPage: boolean;
-        isPrevious: boolean;
-        isNext: boolean;
-        isCurrent: boolean;
-        isSeparator: boolean;
-    };
-    last: {
-        isActive: boolean;
-        label: string;
-        url: string | undefined;
-        isPage: boolean;
-        isPrevious: boolean;
-        isNext: boolean;
-        isCurrent: boolean;
-        isSeparator: boolean;
-    };
-    total: number;
-    from: number;
-    to: number;
-};
 
 type Layout = any;
 /**
- * Sets the persistent layout for this page.
+ * Sets the persistent layout for this view.
  */
 declare function defineLayout<T extends Record<string, K>, K = any>(layout: Layout, properties?: T): void;
 declare function defineLayout(layouts: Layout[]): void;
@@ -804,11 +834,105 @@ declare function useRefinements<Properties extends object, RefinementsKey extend
     /**
      * Available filters.
      */
-    filters: FilterRefinement[];
+    filters: {
+        /**
+         * Applies this filter.
+         */
+        apply: (value: any, options?: AvailableHybridRequestOptions) => Promise<_hybridly_core.NavigationResponse | undefined>;
+        /**
+         * Clears this filter.
+         */
+        clear: (options?: AvailableHybridRequestOptions) => Promise<_hybridly_core.NavigationResponse>;
+        /**
+         * Whether this filter is currently active.
+         */
+        is_active: boolean;
+        /**
+         * The type of this filter.
+         */
+        type: string;
+        /**
+         * The label of the filter.
+         */
+        label: string;
+        /**
+         * The metadata attributes of the filter.
+         */
+        metadata: Record<string, any>;
+        /**
+         * The name of the fitler.
+         */
+        name: string;
+        /**
+         * The current value of the filter.
+         */
+        value: any;
+        /**
+         * Whether this filter is hidden.
+         */
+        hidden: boolean;
+        /**
+         * The default value of the filter.
+         */
+        default: any;
+    }[];
     /**
      * Available sorts.
      */
-    sorts: SortRefinement[];
+    sorts: {
+        /**
+         * Toggles this sort.
+         */
+        toggle: (options?: ToggleSortOptions) => Promise<_hybridly_core.NavigationResponse | undefined>;
+        /**
+         * Checks if this sort is active.
+         */
+        isSorting: (direction?: SortDirection) => boolean;
+        /**
+         * Clears this sort.
+         */
+        clear: (options?: AvailableHybridRequestOptions) => Promise<_hybridly_core.NavigationResponse>;
+        /**
+         * Whether this sort is currently active.
+         */
+        is_active: boolean;
+        /**
+         * The current direction of the sort.
+         */
+        direction?: SortDirection | undefined;
+        /**
+         * The default direction of the sort.
+         */
+        default?: SortDirection | undefined;
+        /**
+         * The label of the sort.
+         */
+        label: string;
+        /**
+         * The metadata attributes of the sort.
+         */
+        metadata: Record<string, any>;
+        /**
+         * The name of the sort.
+         */
+        name: string;
+        /**
+         * The value corresponding to the descending sort.
+         */
+        desc: string;
+        /**
+         * The value corresponding to the ascending sort.
+         */
+        asc: string;
+        /**
+         * The value that will be applied on toggle.
+         */
+        next: string;
+        /**
+         * Whether this sort is hidden.
+         */
+        hidden: boolean;
+    }[];
     /**
      * Gets a filter by name.
      */
@@ -828,7 +952,7 @@ declare function useRefinements<Properties extends object, RefinementsKey extend
     /**
      * Whether a sort is active.
      */
-    isSorting: (name?: string) => boolean;
+    isSorting: (name?: string, direction?: SortDirection) => boolean;
     /**
      * Whether a filter is active.
      */
@@ -864,4 +988,237 @@ declare function useRoute(): {
     matches: <T extends string>(name: MaybeRefOrGetter<T>, parameters?: Record<string, any> | undefined) => boolean;
 };
 
-export { type Layout, RouterLink, defineLayout, defineLayoutProperties, initializeHybridly, registerHook, setProperty, useBackForward, useContext, useDialog, useForm, useHistoryState, usePaginator, useProperties, useProperty, useRefinements, useRoute };
+interface BulkSelection<T = any> {
+    /** Whether all records are selected. */
+    all: boolean;
+    /** Included records. */
+    only: Set<T>;
+    /** Excluded records. */
+    except: Set<T>;
+}
+declare function useBulkSelect<T = any>(): {
+    allSelected: vue.ComputedRef<boolean>;
+    selectAll: () => void;
+    deselectAll: () => void;
+    select: (...records: T[]) => void;
+    deselect: (...records: T[]) => void;
+    toggle: (record: T, force?: boolean) => void;
+    selected: (record: T) => boolean;
+    selection: vue.Ref<{
+        all: boolean;
+        only: Set<T>;
+        except: Set<T>;
+    }>;
+};
+
+declare global {
+    interface Table<T extends Record<string, any> = any, PaginatorKind extends 'cursor' | 'length-aware' | 'simple' = 'length-aware'> {
+        id: string;
+        keyName: string;
+        scope?: string;
+        columns: Column<T>[];
+        inlineActions: InlineAction[];
+        bulkActions: BulkAction[];
+        records: T[];
+        paginator: Exclude<PaginatorKind extends 'cursor' ? CursorPaginator<T> : (PaginatorKind extends 'simple' ? SimplePaginator<T> : Paginator<T>), 'data'>;
+        refinements: Refinements;
+        endpoint: string;
+    }
+}
+interface Column<T extends object = never> {
+    /** The name of this column. */
+    name: keyof T;
+    /** The label of this column. */
+    label: string;
+    /** The type of this column. */
+    type: string;
+    /** Custom metadata for this column. */
+    metadata: any;
+}
+interface Action {
+    /** The name of this action. */
+    name: string;
+    /** The label of this action. */
+    label: string;
+    /** The type of this action. */
+    type: string;
+    /** Custom metadata for this action. */
+    metadata: any;
+}
+interface BulkAction extends Action {
+    /** Should deselect all records after action. */
+    deselect: boolean;
+}
+interface BulkActionOptions {
+    /** Force deselecting all records after action. */
+    deselect?: boolean;
+}
+interface InlineAction extends Action {
+}
+type RecordIdentifier = string | number;
+/**
+ * Provides utilities for working with tables.
+ */
+declare function useTable<RecordType extends (Props[PropsKey] extends Table<infer RecordType, any> ? RecordType : never), PaginatorKindName extends (Props[PropsKey] extends Table<RecordType, infer PaginatorKind> ? PaginatorKind : never), TableType extends (Props[PropsKey] extends Table<RecordType, PaginatorKindName> ? Table<RecordType, PaginatorKindName> : never), Props extends Record<string, unknown>, PropsKey extends keyof Props>(props: Props, key: PropsKey, defaultOptions?: AvailableHybridRequestOptions): {
+    bindFilter: <T = any>(name: string, options?: BindFilterOptions<T>) => vue.Ref<T>;
+    filters: {
+        apply: (value: any, options?: AvailableHybridRequestOptions | undefined) => Promise<hybridly.NavigationResponse | undefined>;
+        clear: (options?: AvailableHybridRequestOptions | undefined) => Promise<hybridly.NavigationResponse>;
+        is_active: boolean;
+        type: string;
+        label: string;
+        metadata: Record<string, any>;
+        name: string;
+        value: any;
+        hidden: boolean;
+        default: any;
+    }[];
+    sorts: {
+        toggle: (options?: ToggleSortOptions | undefined) => Promise<hybridly.NavigationResponse | undefined>;
+        isSorting: (direction?: SortDirection | undefined) => boolean;
+        clear: (options?: AvailableHybridRequestOptions | undefined) => Promise<hybridly.NavigationResponse>;
+        is_active: boolean;
+        direction?: SortDirection | undefined;
+        default?: SortDirection | undefined;
+        label: string;
+        metadata: Record<string, any>;
+        name: string;
+        desc: string;
+        asc: string;
+        next: string;
+        hidden: boolean;
+    }[];
+    getFilter: (name: string) => FilterRefinement | undefined;
+    getSort: (name: string) => SortRefinement | undefined;
+    reset: (options?: AvailableHybridRequestOptions) => Promise<hybridly.NavigationResponse>;
+    toggleSort: (name: string, options?: ToggleSortOptions | undefined) => Promise<hybridly.NavigationResponse | undefined>;
+    isSorting: (name?: string | undefined, direction?: SortDirection | undefined) => boolean;
+    isFiltering: (name?: string | undefined) => boolean;
+    currentSorts: () => SortRefinement[];
+    currentFilters: () => FilterRefinement[];
+    clearFilter: (filter: string, options?: AvailableHybridRequestOptions) => Promise<hybridly.NavigationResponse>;
+    clearSorts: (options?: AvailableHybridRequestOptions) => Promise<hybridly.NavigationResponse>;
+    clearFilters: (options?: AvailableHybridRequestOptions) => Promise<hybridly.NavigationResponse>;
+    applyFilter: (name: string, value: any, options?: AvailableHybridRequestOptions) => Promise<hybridly.NavigationResponse | undefined>;
+    selectAll: () => void;
+    deselectAll: () => void;
+    isSelected: (record: RecordType) => boolean;
+    allSelected: boolean;
+    selection: {
+        all: boolean;
+        only: Set<RecordIdentifier>;
+        except: Set<RecordIdentifier>;
+    };
+    toggle: (record: RecordType) => void;
+    select: (record: RecordType) => void;
+    deselect: (record: RecordType) => void;
+    inlineActions: {
+        /** The name of this action. */
+        name: string;
+        /** The label of this action. */
+        label: string;
+        /** The type of this action. */
+        type: string;
+        /** Custom metadata for this action. */
+        metadata: any;
+        /** Executes the action. */
+        execute: (record: RecordType | RecordIdentifier) => Promise<hybridly.NavigationResponse>;
+    }[];
+    bulkActions: {
+        /** Should deselect all records after action. */
+        deselect: boolean;
+        /** The name of this action. */
+        name: string;
+        /** The label of this action. */
+        label: string;
+        /** The type of this action. */
+        type: string;
+        /** Custom metadata for this action. */
+        metadata: any;
+        /** Executes the action. */
+        execute: (options?: BulkActionOptions) => Promise<hybridly.NavigationResponse>;
+    }[];
+    executeInlineAction: (action: Action | string, record: RecordType | RecordIdentifier) => Promise<hybridly.NavigationResponse>;
+    executeBulkAction: (action: Action | string, options?: BulkActionOptions) => Promise<hybridly.NavigationResponse>;
+    columns: {
+        /** Toggles sorting for this column. */
+        toggleSort: (options?: ToggleSortOptions) => Promise<hybridly.NavigationResponse | undefined>;
+        /** Checks whether the column is being sorted. */
+        isSorting: (direction?: SortDirection) => boolean;
+        /** Applies the filer for this column. */
+        applyFilter: (value: any, options?: AvailableHybridRequestOptions) => Promise<hybridly.NavigationResponse | undefined>;
+        /** Clears the filter for this column. */
+        clearFilter: (options?: AvailableHybridRequestOptions) => Promise<hybridly.NavigationResponse>;
+        /** Checks whether the column is sortable. */
+        isSortable: {
+            toggle: (options?: ToggleSortOptions | undefined) => Promise<hybridly.NavigationResponse | undefined>;
+            isSorting: (direction?: SortDirection | undefined) => boolean;
+            clear: (options?: AvailableHybridRequestOptions | undefined) => Promise<hybridly.NavigationResponse>;
+            is_active: boolean;
+            direction?: SortDirection | undefined;
+            default?: SortDirection | undefined;
+            label: string;
+            metadata: Record<string, any>;
+            name: string;
+            desc: string;
+            asc: string;
+            next: string;
+            hidden: boolean;
+        } | undefined;
+        /** Checks whether the column is filterable. */
+        isFilterable: {
+            apply: (value: any, options?: AvailableHybridRequestOptions | undefined) => Promise<hybridly.NavigationResponse | undefined>;
+            clear: (options?: AvailableHybridRequestOptions | undefined) => Promise<hybridly.NavigationResponse>;
+            is_active: boolean;
+            type: string;
+            label: string;
+            metadata: Record<string, any>;
+            name: string;
+            value: any;
+            hidden: boolean;
+            default: any;
+        } | undefined;
+        /** The name of this column. */
+        name: keyof RecordType;
+        /** The label of this column. */
+        label: string;
+        /** The type of this column. */
+        type: string;
+        /** Custom metadata for this column. */
+        metadata: any;
+    }[];
+    records: {
+        /** The actual record. */
+        record: RecordType;
+        /** The key of the record. Use this instead of `id`. */
+        key: RecordIdentifier;
+        /** Executes the given inline action. */
+        execute: (action: string | InlineAction) => Promise<hybridly.NavigationResponse>;
+        /** Gets the available inline actions. */
+        actions: {
+            /** Executes the action. */
+            execute: () => Promise<hybridly.NavigationResponse>;
+            /** The name of this action. */
+            name: string;
+            /** The label of this action. */
+            label: string;
+            /** The type of this action. */
+            type: string;
+            /** Custom metadata for this action. */
+            metadata: any;
+        }[];
+        /** Selects this record. */
+        select: () => void;
+        /** Deselects this record. */
+        deselect: () => void;
+        /** Toggles the selection for this record. */
+        toggle: (force?: boolean) => void;
+        /** Checks whether this record is selected. */
+        selected: boolean;
+        /** Gets the value of the record for the specified column. */
+        value: (column: string | Column<RecordType>) => RecordType[string | keyof RecordType];
+    }[];
+    paginator: Exclude<PaginatorKindName extends "cursor" ? CursorPaginator<RecordType> : PaginatorKindName extends "simple" ? SimplePaginator<RecordType> : Paginator<RecordType>, "data">;
+};
+
+export { type Action, type AvailableHybridRequestOptions, type BindFilterOptions, type BulkAction, type BulkSelection, type Column, type InlineAction, type Layout, type RecordIdentifier, RouterLink, type SortDirection, type ToggleSortOptions, defineLayout, defineLayoutProperties, initializeHybridly, registerHook, setProperty, useBackForward, useBulkSelect, useContext, useDialog, useForm, useHistoryState, useProperties, useProperty, useRefinements, useRoute, useTable };