@vef-framework/starter 2.0.11 → 2.1.0

package/dist/types/src/components/page/props.d.ts

@@ -0,0 +1,140 @@
+import { Length } from '@vef-framework/components';
+import { PropsWithChildren, ReactNode } from 'react';
+/**
+ * Position type for header and footer.
+ * - `"inside"`: Inside the main content area
+ * - `"outside"`: Spans the full width of the page (including asides)
+ */
+export type Position = "inside" | "outside";
+/**
+ * Resizable width configuration for aside panels.
+ */
+export interface ResizableWidth {
+    /**
+     * Default width of the panel.
+     */
+    defaultWidth?: Length;
+    /**
+     * Minimum width constraint.
+     */
+    minWidth?: Length;
+    /**
+     * Maximum width constraint.
+     */
+    maxWidth?: Length;
+}
+/**
+ * Width type: fixed value or resizable configuration.
+ * - `string | number`: Fixed width, not resizable
+ * - `ResizableWidth`: Resizable with optional constraints
+ */
+export type AsideWidth = Length | ResizableWidth;
+/**
+ * The props of the Page component.
+ */
+export interface PageProps extends PropsWithChildren {
+    /**
+     * The class name of the page container.
+     */
+    className?: string;
+    /**
+     * Whether the page container has margin.
+     * When true, applies var(--vef-spacing-md) margin to the container.
+     *
+     * @default false
+     */
+    margin?: boolean;
+    /**
+     * The gap between grid cells.
+     *
+     * @default "var(--vef-spacing-md)"
+     */
+    gap?: Length;
+    /**
+     * The class name of the main content area.
+     */
+    mainClassName?: string;
+    /**
+     * The left aside content of the page.
+     */
+    leftAside?: ReactNode;
+    /**
+     * The class name of the left aside.
+     */
+    leftAsideClassName?: string;
+    /**
+     * The width of the left aside.
+     * - `number | string`: Fixed width
+     * - `{ defaultWidth?, minWidth?, maxWidth? }`: Resizable with constraints
+     *
+     * @default 280
+     */
+    leftAsideWidth?: AsideWidth;
+    /**
+     * The right aside content of the page.
+     */
+    rightAside?: ReactNode;
+    /**
+     * The class name of the right aside.
+     */
+    rightAsideClassName?: string;
+    /**
+     * The width of the right aside.
+     * - `number | string`: Fixed width
+     * - `{ defaultWidth?, minWidth?, maxWidth? }`: Resizable with constraints
+     *
+     * @default 280
+     */
+    rightAsideWidth?: AsideWidth;
+    /**
+     * The header of the page.
+     */
+    header?: ReactNode;
+    /**
+     * The class name of the header.
+     */
+    headerClassName?: string;
+    /**
+     * The position of the header.
+     * - `"inside"`: Header is inside the main content area (default)
+     * - `"outside"`: Header spans the full width of the page (including asides)
+     *
+     * @default "inside"
+     */
+    headerPosition?: Position;
+    /**
+     * The footer of the page.
+     */
+    footer?: ReactNode;
+    /**
+     * The class name of the footer.
+     */
+    footerClassName?: string;
+    /**
+     * The position of the footer.
+     * - `"inside"`: Footer is inside the main content area (default)
+     * - `"outside"`: Footer spans the full width of the page (including asides)
+     *
+     * @default "inside"
+     */
+    footerPosition?: Position;
+    /**
+     * The action bar of the page.
+     */
+    actionBar?: ReactNode;
+    /**
+     * The class name of the action bar.
+     */
+    actionBarClassName?: string;
+    /**
+     * Whether the page main content is scrollable.
+     */
+    scrollable?: boolean;
+    /**
+     * Whether the scrollable content has automatic margin for scrollbar spacing.
+     * Only effective when scrollable is true.
+     *
+     * @default false
+     */
+    scrollMargin?: boolean;
+}

package/dist/types/src/components/page/styles.d.ts

@@ -0,0 +1,17 @@
+import { SerializedStyles } from '@emotion/serialize';
+export declare const page: SerializedStyles;
+export declare const leftAside: SerializedStyles;
+export declare const rightAside: SerializedStyles;
+export declare const asideContent: SerializedStyles;
+export declare const resizeHandleGrip: SerializedStyles;
+export declare const resizeHandleLeft: SerializedStyles;
+export declare const resizeHandleRight: SerializedStyles;
+export declare const main: SerializedStyles;
+export declare const header: SerializedStyles;
+export declare const headerOutside: SerializedStyles;
+export declare const content: SerializedStyles;
+export declare const scrollWrapper: SerializedStyles;
+export declare const scrollContainer: SerializedStyles;
+export declare const footer: SerializedStyles;
+export declare const footerOutside: SerializedStyles;
+export declare const actionBar: SerializedStyles;

package/dist/types/src/components/page/viewport-context.d.ts

@@ -0,0 +1,7 @@
+import { Provider } from 'react';
+/**
+ * Hook to get the viewport height from Page component.
+ * Must be used within Page component with scrollable prop set to true.
+ */
+export declare function useViewportHeight(): number;
+export declare const ViewportProvider: Provider<number | null>;

package/dist/types/src/components/pro-search/components/advanced-search-toggler.d.ts

@@ -0,0 +1,7 @@
+import { MemoExoticComponent } from 'react';
+interface AdvancedSearchTogglerProps {
+    isVisible: boolean;
+    onToggle: () => void;
+}
+export declare const AdvancedSearchToggler: MemoExoticComponent<({ isVisible, onToggle }: AdvancedSearchTogglerProps) => import("@emotion/react/jsx-runtime").JSX.Element>;
+export {};

package/dist/types/src/components/pro-search/components/advanced-search.d.ts

@@ -0,0 +1,6 @@
+import { PropsWithChildren, MemoExoticComponent } from 'react';
+interface AdvancedSearchProps {
+    isVisible: boolean;
+}
+export declare const AdvancedSearch: MemoExoticComponent<({ children, isVisible }: PropsWithChildren<AdvancedSearchProps>) => import("@emotion/react/jsx-runtime").JSX.Element>;
+export {};

package/dist/types/src/components/pro-search/components/index.d.ts

@@ -0,0 +1,3 @@
+export { AdvancedSearch } from './advanced-search';
+export { AdvancedSearchToggler } from './advanced-search-toggler';
+export { SearchActions } from './search-actions';

package/dist/types/src/components/pro-search/components/search-actions.d.ts

@@ -0,0 +1,10 @@
+import { ProSearchProps } from '../props';
+import { MemoExoticComponent } from 'react';
+interface SearchActionsProps {
+    loading?: boolean;
+    searchButtonProps?: ProSearchProps<never>["searchButtonProps"];
+    resetButtonProps?: ProSearchProps<never>["resetButtonProps"];
+    onReset?: () => void;
+}
+export declare const SearchActions: MemoExoticComponent<({ loading, searchButtonProps, resetButtonProps, onReset }: SearchActionsProps) => import("@emotion/react/jsx-runtime").JSX.Element>;
+export {};

package/dist/types/src/components/pro-search/index.d.ts

@@ -0,0 +1,5 @@
+import { Awaitable } from '@vef-framework/shared';
+import { FC, ReactNode } from 'react';
+import { ProSearchProps } from './props';
+export declare const ProSearch: (<TValues = unknown>(props: ProSearchProps<TValues>) => Awaitable<ReactNode>) & Pick<FC, "displayName">;
+export type { ProSearchProps } from './props';

package/dist/types/src/components/pro-search/props.d.ts

@@ -0,0 +1,66 @@
+import { ResetButtonProps, SubmitButtonProps } from '@vef-framework/components';
+import { Except } from '@vef-framework/shared';
+import { ReactNode } from 'react';
+/**
+ * Props for the ProSearch component
+ *
+ * @template TValues - The type of the search form values
+ */
+export interface ProSearchProps<TValues = unknown> {
+    /**
+     * CSS class name
+     */
+    className?: string;
+    /**
+     * Default search values
+     */
+    defaultValues?: TValues;
+    /**
+     * Extra content on the left side
+     */
+    extra?: ReactNode;
+    /**
+     * Basic search content
+     */
+    basicSearch?: ReactNode;
+    /**
+     * Advanced search content
+     */
+    advancedSearch?: ReactNode;
+    /**
+     * Disabled state
+     */
+    disabled?: boolean;
+    /**
+     * Loading state
+     */
+    loading?: boolean;
+    /**
+     * Search button props
+     */
+    searchButtonProps?: Except<SubmitButtonProps, "onSubmit" | "disabled" | "loading">;
+    /**
+     * Reset button props, or false to hide the reset button
+     */
+    resetButtonProps?: Except<ResetButtonProps, "onReset" | "disabled" | "loading"> | false;
+    /**
+     * Callback when search values change
+     */
+    onSearch?: (values: NoInfer<TValues>) => void;
+    /**
+     * Callback when search is reset
+     */
+    onReset?: (defaultValues?: NoInfer<TValues>) => void;
+    /**
+     * Whether advanced search is visible by default (uncontrolled)
+     */
+    defaultAdvancedSearchVisible?: boolean;
+    /**
+     * Whether advanced search is visible (controlled)
+     */
+    advancedSearchVisible?: boolean;
+    /**
+     * Callback when advanced search visibility changes
+     */
+    onAdvancedSearchVisibleChange?: (visible: boolean) => void;
+}

package/dist/types/src/components/pro-search/styles.d.ts

@@ -0,0 +1,6 @@
+import { SerializedStyles } from '@emotion/serialize';
+export declare const content: SerializedStyles;
+export declare const contentLeft: SerializedStyles;
+export declare const contentRight: SerializedStyles;
+export declare const advancedSearchToggler: SerializedStyles;
+export declare const advancedSearch: SerializedStyles;

package/dist/types/src/components/pro-table/components/column-setting-item.d.ts

@@ -0,0 +1,12 @@
+import { Key } from '@vef-framework/shared';
+import { ReactNode, NamedExoticComponent } from 'react';
+interface ColumnSettingItemProps {
+    columnId: Key;
+    title: ReactNode;
+    fixed?: "start" | "end" | false;
+    width?: number;
+    visible: boolean;
+    index: number;
+}
+export declare const ColumnSettingItem: NamedExoticComponent<ColumnSettingItemProps>;
+export {};

package/dist/types/src/components/pro-table/components/column-settings-panel.d.ts

@@ -0,0 +1,2 @@
+import { MemoExoticComponent } from 'react';
+export declare const ColumnSettingsPanel: MemoExoticComponent<() => import("@emotion/react/jsx-runtime").JSX.Element>;

package/dist/types/src/components/pro-table/components/column-settings.d.ts

@@ -0,0 +1,6 @@
+import { NamedExoticComponent } from 'react';
+interface ColumnSettingsProps {
+    className?: string;
+}
+export declare const ColumnSettings: NamedExoticComponent<ColumnSettingsProps>;
+export {};

package/dist/types/src/components/pro-table/components/index.d.ts

@@ -0,0 +1,8 @@
+export { ColumnSettingItem } from './column-setting-item';
+export { ColumnSettings } from './column-settings';
+export { ColumnSettingsPanel } from './column-settings-panel';
+export { OperationButtonGroup, type OperationButtonGroupProps } from './operation-button-group';
+export { ProTableRefHolder } from './ref';
+export { NonPaginatedTable, PaginatedTable } from './table';
+export { TableSubscriber, type TableSubscriberProps } from './table-subscriber';
+export { WidthPopover } from './width-popover';

package/dist/types/src/components/pro-table/components/operation-button-group.d.ts

@@ -0,0 +1,7 @@
+import { FC, ReactNode } from 'react';
+import { ProTableState } from '../store';
+export interface OperationButtonGroupProps<TSelected = NoInfer<ProTableState>> {
+    selector?: (state: NoInfer<ProTableState>) => TSelected;
+    children: ((state: NoInfer<TSelected>) => ReactNode) | ReactNode;
+}
+export declare const OperationButtonGroup: (<TSelected = NoInfer<ProTableState>>(props: OperationButtonGroupProps<TSelected>) => ReactNode) & Pick<FC, "displayName">;

package/dist/types/src/components/pro-table/components/ref.d.ts

@@ -0,0 +1,3 @@
+import { PropsWithRef } from '@vef-framework/components';
+import { ProTableRef } from '../types';
+export declare function ProTableRefHolder({ ref }: PropsWithRef<ProTableRef>): null;

package/dist/types/src/components/pro-table/components/table-subscriber.d.ts

@@ -0,0 +1,9 @@
+import { FC, ReactNode } from 'react';
+import { ProTableState } from '../store';
+export interface TableSubscriberProps<TSelected = NoInfer<ProTableState>, TRow = unknown> {
+    selector?: (state: NoInfer<ProTableState> & {
+        data: readonly TRow[];
+    }) => TSelected;
+    children: ((state: NoInfer<TSelected>) => ReactNode) | ReactNode;
+}
+export declare const TableSubscriber: (<TSelected = NoInfer<ProTableState>>(props: TableSubscriberProps<TSelected>) => ReactNode) & Pick<FC, "displayName">;

package/dist/types/src/components/pro-table/components/table-summary.d.ts

@@ -0,0 +1,7 @@
+import { ReactNode, NamedExoticComponent } from 'react';
+interface TableSummaryProps {
+    summary: ReactNode;
+    data: readonly unknown[];
+}
+export declare const TableSummary: NamedExoticComponent<TableSummaryProps>;
+export {};

package/dist/types/src/components/pro-table/components/table-title.d.ts

@@ -0,0 +1,7 @@
+import { ReactNode, NamedExoticComponent } from 'react';
+interface TableTitleProps {
+    title: ReactNode;
+    data: readonly unknown[];
+}
+export declare const TableTitle: NamedExoticComponent<TableTitleProps>;
+export {};

package/dist/types/src/components/pro-table/components/table.d.ts

@@ -0,0 +1,12 @@
+import { AnyObject } from '@vef-framework/shared';
+import { NonPaginatedProTableProps, PaginatedProTableProps } from '../props';
+import { ColumnSettingsProp } from '../types';
+type PaginatedTableProps<TRow extends AnyObject, TParams extends AnyObject> = Pick<PaginatedProTableProps<TRow, TParams>, "className" | "style" | "size" | "queryFn" | "queryEnabled" | "queryParams" | "columns" | "rowKey" | "rowSelection" | "showSequenceColumn" | "operationColumn" | "selectedRowKeys" | "virtual" | "title" | "summary" | "onSelectedRowKeysChange"> & {
+    columnSettings: ColumnSettingsProp;
+};
+type NonPaginatedTableProps<TRow extends AnyObject, TParams extends AnyObject> = Pick<NonPaginatedProTableProps<TRow, TParams>, "className" | "style" | "size" | "queryFn" | "queryEnabled" | "queryParams" | "columns" | "rowKey" | "rowSelection" | "showSequenceColumn" | "operationColumn" | "selectedRowKeys" | "virtual" | "title" | "summary" | "onSelectedRowKeysChange"> & {
+    columnSettings: ColumnSettingsProp;
+};
+export declare function PaginatedTable<TRow extends AnyObject, TParams extends AnyObject>({ className, style, size, queryFn, columns, columnSettings, rowKey, rowSelection, queryEnabled, queryParams, showSequenceColumn, operationColumn, selectedRowKeys, virtual, title, summary, onSelectedRowKeysChange }: PaginatedTableProps<TRow, TParams>): import("@emotion/react/jsx-runtime").JSX.Element;
+export declare function NonPaginatedTable<TRow extends AnyObject, TParams extends AnyObject>({ className, style, size, queryFn, columns, columnSettings, rowKey, rowSelection, queryEnabled, queryParams, showSequenceColumn, operationColumn, selectedRowKeys, virtual, title, summary, onSelectedRowKeysChange }: NonPaginatedTableProps<TRow, TParams>): import("@emotion/react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/src/components/pro-table/components/width-popover.d.ts

@@ -0,0 +1,9 @@
+import { ReactNode, NamedExoticComponent } from 'react';
+interface WidthPopoverProps {
+    currentWidth?: number;
+    disabled?: boolean;
+    children: ReactNode;
+    onWidthChange: (width: number) => void;
+}
+export declare const WidthPopover: NamedExoticComponent<WidthPopoverProps>;
+export {};

package/dist/types/src/components/pro-table/context.d.ts

@@ -0,0 +1,5 @@
+import { Provider } from 'react';
+export declare const DataProvider: Provider<readonly unknown[]>;
+export declare function useData(): readonly unknown[];
+export declare const ColumnSettingsStorageKeyProvider: Provider<string | undefined>;
+export declare function useColumnSettingsStorageKey(): string | undefined;

package/dist/types/src/components/pro-table/event.d.ts

@@ -0,0 +1,16 @@
+import { EventEmitter } from '@vef-framework/shared';
+export type ProTableEvents = {
+    /**
+     * Trigger table data refetch
+     */
+    refetch: void;
+    /**
+     * Emitted when table starts loading data
+     */
+    loading: void;
+    /**
+     * Emitted when table finishes loading data
+     */
+    loaded: void;
+};
+export declare function createEventEmitter(): EventEmitter<ProTableEvents>;

package/dist/types/src/components/pro-table/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export { clearColumnSettingsStorage, useColumnSettingsPersistence } from './use-column-settings-persistence';
+export { useRowSelection } from './use-row-selection';
+export { useTableColumns } from './use-table-columns';

package/dist/types/src/components/pro-table/hooks/use-column-settings-persistence.d.ts

@@ -0,0 +1,7 @@
+export declare function clearColumnSettingsStorage(storageKey: string): {
+    skipNextSave: () => void;
+};
+/**
+ * Hook to handle column settings persistence to localStorage
+ */
+export declare function useColumnSettingsPersistence(storageKey: string | undefined): void;

package/dist/types/src/components/pro-table/hooks/use-row-selection.d.ts

@@ -0,0 +1,7 @@
+import { TableRowSelection } from '@vef-framework/components';
+import { Key } from '@vef-framework/shared';
+import { RowSelectionConfig } from '../types';
+/**
+ * Hook to create row selection configuration for ProTable.
+ */
+export declare function useRowSelection<TRow>(config: RowSelectionConfig<TRow> | true | undefined, selectedRowKeys?: Key[], onSelectedRowKeysChange?: (selectedRowKeys: Key[], selectedRows: TRow[]) => void): TableRowSelection<TRow> | undefined;

package/dist/types/src/components/pro-table/hooks/use-table-columns.d.ts

@@ -0,0 +1,13 @@
+import { TableColumn } from '@vef-framework/components';
+import { AnyObject } from '@vef-framework/shared';
+import { ColumnSettingsProp, OperationColumnConfig } from '../types';
+/**
+ * The hook to use the table columns.
+ *
+ * @param tableColumns - The columns of the table.
+ * @param operationColumn - The operation column of the table.
+ * @param showSequenceColumn - Whether to show the sequence column. Default is true.
+ * @param columnSettingsProp - Column settings configuration.
+ * @returns The table columns.
+ */
+export declare function useTableColumns<TRow extends AnyObject>(tableColumns: Array<TableColumn<TRow>>, operationColumn?: OperationColumnConfig<TRow>, showSequenceColumn?: boolean, columnSettingsProp?: ColumnSettingsProp): Array<TableColumn<TRow>>;

package/dist/types/src/components/pro-table/index.d.ts

@@ -0,0 +1,11 @@
+import { AnyObject, Awaitable } from '@vef-framework/shared';
+import { FC, ReactNode } from 'react';
+import { ProTableProps } from './props';
+import { ProTableRef } from './types';
+export declare const ProTable: (<TRow extends AnyObject, TParams extends AnyObject>(props: ProTableProps<TRow, TParams> & {
+    ref?: React.Ref<ProTableRef>;
+}) => Awaitable<ReactNode>) & Pick<FC, "displayName">;
+export { OperationButtonGroup, TableSubscriber as ProTableSubscriber, type OperationButtonGroupProps, type TableSubscriberProps as ProTableSubscriberProps } from './components';
+export type { ProTableProps } from './props';
+export type { ProTableState } from './store';
+export type { ColumnSettingsConfig, ColumnSettingsProp, OperationColumnConfig, ParamsWithPagination, ParamsWithSort, ProTableRef, RowSelectionConfig } from './types';

package/dist/types/src/components/pro-table/props.d.ts

@@ -0,0 +1,127 @@
+import { TableColumn, TableProps } from '@vef-framework/components';
+import { PaginationResult, QueryFunction } from '@vef-framework/core';
+import { AnyObject, DeepKeys, Key } from '@vef-framework/shared';
+import { CSSProperties, ReactNode } from 'react';
+import { ColumnSettingsProp, OperationColumnConfig, ParamsWithPagination, ParamsWithSort, RowSelectionConfig } from './types';
+/**
+ * Base props for ProTable component
+ *
+ * @template TRow - The type of table row data
+ * @template TParams - The type of query parameters
+ */
+interface BaseProTableProps<TRow extends AnyObject, TParams extends AnyObject> extends Pick<TableProps<TRow>, "size"> {
+    /**
+     * Class name for the table container
+     */
+    className?: string;
+    /**
+     * Inline styles for the table container
+     */
+    style?: CSSProperties;
+    /**
+     * Table column definitions
+     */
+    columns: Array<TableColumn<NoInfer<TRow>>>;
+    /**
+     * Column settings configuration.
+     * - `false`: Disable column settings feature
+     * - `{ storageKey?: string }`: Enable with optional localStorage persistence
+     *
+     * @default {}
+     */
+    columnSettings?: ColumnSettingsProp;
+    /**
+     * Whether to show the sequence (row number) column. Default is true.
+     */
+    showSequenceColumn?: boolean;
+    /**
+     * Row key extractor: either a deep key of the row model or a function
+     */
+    rowKey?: DeepKeys<NoInfer<TRow>> | ((row: NoInfer<TRow>) => Key);
+    /**
+     * Enable virtual scrolling for the table to improve performance with large datasets
+     *
+     * @default false
+     */
+    virtual?: boolean;
+    /**
+     * Currently selected row keys
+     */
+    selectedRowKeys?: Key[];
+    /**
+     * Operation column configuration for per-row actions
+     */
+    operationColumn?: OperationColumnConfig<NoInfer<TRow>>;
+    /**
+     * Row selection configuration
+     * - `true`: Enable row selection with default configuration
+     * - `RowSelectionConfig<TRow>`: Enable row selection with custom configuration
+     * - `undefined`: Disable row selection (default)
+     */
+    rowSelection?: RowSelectionConfig<NoInfer<TRow>> | true;
+    /**
+     * Function to determine whether the query should be enabled
+     */
+    queryEnabled?: (params?: TParams) => boolean;
+    /**
+     * Query parameters that trigger re-fetching when changed.
+     */
+    queryParams?: TParams;
+    /**
+     * Custom header content to be rendered above the title
+     */
+    header?: ReactNode;
+    /**
+     * Title to be displayed above the table
+     */
+    title?: ReactNode;
+    /**
+     * Summary information to be displayed below the table
+     */
+    summary?: ReactNode;
+    /**
+     * Custom footer content to be rendered below the summary
+     */
+    footer?: ReactNode;
+    /**
+     * Callback when selected row keys change
+     */
+    onSelectedRowKeysChange?: (keys: Key[], rows: TRow[]) => void;
+}
+/**
+ * Props for paginated ProTable
+ *
+ * @template TRow - The type of table row data
+ * @template TParams - The type of query parameters
+ */
+export interface PaginatedProTableProps<TRow extends AnyObject, TParams extends AnyObject> extends BaseProTableProps<TRow, TParams> {
+    /**
+     * Enable pagination mode. Default is true.
+     */
+    isPaginated?: true;
+    /**
+     * Query function for fetching paginated data
+     */
+    queryFn: QueryFunction<PaginationResult<TRow>, ParamsWithSort<ParamsWithPagination<TParams>>>;
+}
+/**
+ * Props for non-paginated ProTable
+ *
+ * @template TRow - The type of table row data
+ * @template TParams - The type of query parameters
+ */
+export interface NonPaginatedProTableProps<TRow extends AnyObject, TParams extends AnyObject> extends BaseProTableProps<TRow, TParams> {
+    /**
+     * Disable pagination mode for this variant
+     */
+    isPaginated: false;
+    /**
+     * Query function for fetching the full list data
+     */
+    queryFn: QueryFunction<TRow[], ParamsWithSort<TParams>>;
+}
+/**
+ * Discriminated union of paginated and non-paginated ProTable props
+ */
+export type ProTableProps<TRow extends AnyObject, TParams extends AnyObject> = PaginatedProTableProps<TRow, TParams> | NonPaginatedProTableProps<TRow, TParams>;
+export {};