@rchemist/listgrid 0.2.6

package/dist/listgrid/components/list/context/ListGridThemeContext.js

@@ -0,0 +1,157 @@
+'use client';
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from 'react';
+import { cn as cnUtil } from '../../../utils/cn';
+import { defaultListGridTheme } from '../themes/defaultListGridTheme';
+import { mainListGridTheme } from '../themes/variants/mainTheme';
+import { subCollectionListGridTheme } from '../themes/variants/subCollectionTheme';
+import { modalListGridTheme } from '../themes/variants/modalTheme';
+/**
+ * 두 객체를 깊게 병합하는 유틸리티
+ * 커스텀 테마가 기본 테마를 오버라이드
+ */
+const deepMerge = (base, override) => {
+    if (!override)
+        return base;
+    const result = { ...base };
+    for (const key in override) {
+        if (Object.prototype.hasOwnProperty.call(override, key)) {
+            const baseValue = base[key];
+            const overrideValue = override[key];
+            if (baseValue &&
+                overrideValue &&
+                typeof baseValue === 'object' &&
+                typeof overrideValue === 'object' &&
+                !Array.isArray(baseValue) &&
+                !Array.isArray(overrideValue)) {
+                // 중첩 객체 병합
+                result[key] = deepMerge(baseValue, overrideValue);
+            }
+            else if (overrideValue !== undefined) {
+                // 값 오버라이드
+                result[key] = overrideValue;
+            }
+        }
+    }
+    return result;
+};
+/**
+ * Variant에 따른 프리셋 테마 가져오기
+ */
+const getVariantTheme = (variant) => {
+    switch (variant) {
+        case 'main':
+            return mainListGridTheme;
+        case 'subCollection':
+            return subCollectionListGridTheme;
+        case 'modal':
+        case 'popup':
+            return modalListGridTheme;
+        default:
+            return undefined;
+    }
+};
+/**
+ * ListGrid 테마 컨텍스트
+ * ViewListGrid과 하위 컴포넌트에서 스타일을 커스터마이징하는데 사용
+ */
+const ListGridThemeContext = createContext({
+    classNames: defaultListGridTheme,
+    cn: (base, custom) => (custom ? cnUtil(base, custom) : base),
+    variant: 'default',
+});
+/**
+ * ListGrid 테마 Provider
+ *
+ * ListGrid에 테마를 적용할 때 사용합니다.
+ * variant를 지정하면 해당 프리셋 테마가 자동으로 적용됩니다.
+ *
+ * @example
+ * ```tsx
+ * // 서브콜렉션에서 사용
+ * <ListGridThemeProvider variant="subCollection">
+ *   <ViewListGrid {...props} />
+ * </ListGridThemeProvider>
+ *
+ * // 커스텀 테마 적용
+ * const customTheme = {
+ *   panel: { container: 'mt-8 border-2 rounded-2xl' },
+ * };
+ * <ListGridThemeProvider theme={customTheme}>
+ *   <ViewListGrid {...props} />
+ * </ListGridThemeProvider>
+ * ```
+ */
+export const ListGridThemeProvider = ({ theme, variant = 'default', children, }) => {
+    const value = useMemo(() => {
+        // 1. 기본 테마
+        let mergedClassNames = { ...defaultListGridTheme };
+        // 2. Variant 프리셋 적용
+        const variantTheme = getVariantTheme(variant);
+        if (variantTheme) {
+            mergedClassNames = deepMerge(mergedClassNames, variantTheme);
+        }
+        // 3. 커스텀 테마 적용 (최우선)
+        if (theme) {
+            mergedClassNames = deepMerge(mergedClassNames, theme);
+        }
+        return {
+            classNames: mergedClassNames,
+            cn: (base, custom) => {
+                if (!custom)
+                    return base;
+                return cnUtil(base, custom);
+            },
+            variant,
+        };
+    }, [theme, variant]);
+    return _jsx(ListGridThemeContext.Provider, { value: value, children: children });
+};
+/**
+ * ListGrid 테마 훅
+ *
+ * ViewListGrid의 하위 컴포넌트에서 테마 클래스를 가져올 때 사용합니다.
+ *
+ * @example
+ * ```tsx
+ * const { classNames, cn, variant } = useListGridTheme();
+ *
+ * return (
+ *   <div className={cn('flex items-center', classNames.header?.container)}>
+ *     ...
+ *   </div>
+ * );
+ * ```
+ */
+export const useListGridTheme = () => {
+    const context = useContext(ListGridThemeContext);
+    if (!context) {
+        // Context가 없으면 기본값 반환 (Provider 없이도 동작)
+        return {
+            classNames: defaultListGridTheme,
+            cn: (base, custom) => (custom ? cnUtil(base, custom) : base),
+            variant: 'default',
+        };
+    }
+    return context;
+};
+/**
+ * 특정 variant의 테마 클래스를 직접 가져오는 유틸리티
+ *
+ * Provider 없이 특정 variant의 테마를 사용하고 싶을 때 활용합니다.
+ *
+ * @example
+ * ```tsx
+ * const subCollectionTheme = getListGridThemeByVariant('subCollection');
+ * ```
+ */
+export const getListGridThemeByVariant = (variant) => {
+    let mergedClassNames = { ...defaultListGridTheme };
+    const variantTheme = getVariantTheme(variant);
+    if (variantTheme) {
+        mergedClassNames = deepMerge(mergedClassNames, variantTheme);
+    }
+    return mergedClassNames;
+};
+export { ListGridThemeContext };

package/dist/listgrid/components/list/context/index.d.ts

@@ -0,0 +1,2 @@
+export { ListGridThemeContext, ListGridThemeProvider, useListGridTheme, getListGridThemeByVariant, } from './ListGridThemeContext';
+export type { ListGridThemeProviderProps } from './ListGridThemeContext';

package/dist/listgrid/components/list/context/index.js

@@ -0,0 +1 @@
+export { ListGridThemeContext, ListGridThemeProvider, useListGridTheme, getListGridThemeByVariant, } from './ListGridThemeContext';

package/dist/listgrid/components/list/hooks/searchFormUrlSync.d.ts

@@ -0,0 +1,42 @@
+import { SearchForm } from '../../../form/SearchForm';
+import { ListGridUrlState } from './urlStateParsers';
+/**
+ * Convert SearchForm to URL state object
+ * @param searchForm - The SearchForm instance to convert
+ * @param quickSearchPropertyName - Name of the quick search field (for backward compatibility)
+ * @param orFields - Additional fields that are searched with OR condition in quick search
+ * @returns URL state object
+ */
+export declare function searchFormToUrlState(searchForm: SearchForm, quickSearchPropertyName?: string, orFields?: string[]): ListGridUrlState;
+/**
+ * Convert URL state to SearchForm
+ * @param urlState - URL state object
+ * @param quickSearchPropertyName - Name of the quick search field
+ * @param baseSearchForm - Optional base SearchForm to clone
+ * @param orFields - Additional fields that are searched with OR condition in quick search
+ * @returns New SearchForm instance
+ */
+export declare function urlStateToSearchForm(urlState: ListGridUrlState, quickSearchPropertyName?: string, baseSearchForm?: SearchForm, orFields?: string[]): SearchForm;
+/**
+ * Merge URL state with sessionStorage state
+ * Priority: URL > sessionStorage > default
+ *
+ * @param urlState - State from URL
+ * @param sessionSearchForm - SearchForm from sessionStorage (can be undefined)
+ * @param quickSearchPropertyName - Quick search field name
+ * @param orFields - Additional fields that are searched with OR condition in quick search
+ * @returns Merged SearchForm
+ */
+export declare function mergeUrlAndSessionState(urlState: ListGridUrlState, sessionSearchForm: SearchForm | undefined, quickSearchPropertyName?: string, orFields?: string[]): SearchForm;
+/**
+ * Extract quick search value from SearchForm
+ * @param searchForm - SearchForm to extract from
+ * @param quickSearchPropertyName - Quick search field name
+ * @param orFields - Additional fields that are searched with OR condition (for determining mode)
+ * @returns Quick search value or empty string
+ */
+export declare function getQuickSearchFromSearchForm(searchForm: SearchForm, quickSearchPropertyName?: string, orFields?: string[]): string;
+/**
+ * Check if two URL states are equal
+ */
+export declare function areUrlStatesEqual(a: ListGridUrlState, b: ListGridUrlState): boolean;

package/dist/listgrid/components/list/hooks/searchFormUrlSync.js

@@ -0,0 +1,212 @@
+import { SearchForm } from '../../../form/SearchForm';
+import { hasUrlParams } from './urlStateParsers';
+/**
+ * Convert SearchForm to URL state object
+ * @param searchForm - The SearchForm instance to convert
+ * @param quickSearchPropertyName - Name of the quick search field (for backward compatibility)
+ * @param orFields - Additional fields that are searched with OR condition in quick search
+ * @returns URL state object
+ */
+export function searchFormToUrlState(searchForm, quickSearchPropertyName, orFields) {
+    const urlState = {
+        page: null,
+        pageSize: null,
+        q: null,
+        sort: null,
+        filters: null,
+    };
+    // Page (only if not 0)
+    const page = searchForm.getPage();
+    if (page > 0) {
+        urlState.page = page;
+    }
+    // PageSize (only if not default 20)
+    const pageSize = searchForm.getPageSize();
+    if (pageSize !== 20) {
+        urlState.pageSize = pageSize;
+    }
+    // Sort
+    const sorts = searchForm.getSorts();
+    if (sorts.size > 0) {
+        // Get the first sort (primary sort)
+        const [field, direction] = Array.from(sorts.entries())[0];
+        // Only include if not the default createdAt:DESC
+        if (field !== 'createdAt' || direction !== 'DESC') {
+            urlState.sort = { field, direction };
+        }
+    }
+    // Filters
+    const filters = searchForm.getFilters();
+    const quickSearchFields = searchForm.getQuickSearchFields();
+    if (filters.size > 0 || quickSearchFields.length > 0) {
+        const filtersState = {};
+        // Get quick search value from SearchForm (filters.OR 기반)
+        const quickSearchValue = searchForm.getQuickSearchValue();
+        // Process AND filters
+        const andFilters = filters.get('AND');
+        if (andFilters && andFilters.length > 0) {
+            const urlFilters = [];
+            for (const filter of andFilters) {
+                // Skip quick search filter with subFilters (handled via q parameter)
+                if (filter.subFilters &&
+                    filter.subFilters.size > 0 &&
+                    quickSearchFields.includes(filter.name)) {
+                    continue;
+                }
+                // Extract quick search to separate q parameter (legacy single field search)
+                if (quickSearchPropertyName &&
+                    filter.name === quickSearchPropertyName &&
+                    !orFields?.length) {
+                    // Legacy mode: if quickSearchValue is not set yet, use this filter's value
+                    if (!quickSearchValue) {
+                        urlState.q = filter.value ?? null;
+                    }
+                    continue; // Don't include in filters
+                }
+                // Skip NOT conditions (developer filters, not user filters)
+                if (filter.not) {
+                    continue;
+                }
+                urlFilters.push(filter);
+            }
+            if (urlFilters.length > 0) {
+                filtersState.AND = urlFilters;
+            }
+        }
+        // Process OR filters (exclude quick search fields)
+        const orFilters = filters.get('OR');
+        if (orFilters && orFilters.length > 0) {
+            // Filter out quick search filters and NOT conditions
+            const urlFilters = orFilters.filter((f) => !f.not && !quickSearchFields.includes(f.name));
+            if (urlFilters.length > 0) {
+                filtersState.OR = urlFilters;
+            }
+        }
+        // Set quick search from SearchForm
+        if (quickSearchValue) {
+            urlState.q = quickSearchValue;
+        }
+        // Set filters if any exist
+        if (filtersState.AND?.length || filtersState.OR?.length) {
+            urlState.filters = filtersState;
+        }
+    }
+    return urlState;
+}
+/**
+ * Convert URL state to SearchForm
+ * @param urlState - URL state object
+ * @param quickSearchPropertyName - Name of the quick search field
+ * @param baseSearchForm - Optional base SearchForm to clone
+ * @param orFields - Additional fields that are searched with OR condition in quick search
+ * @returns New SearchForm instance
+ */
+export function urlStateToSearchForm(urlState, quickSearchPropertyName, baseSearchForm, orFields) {
+    const searchForm = baseSearchForm?.clone() ?? SearchForm.create();
+    // Page
+    if (urlState.page !== null) {
+        searchForm.withPage(urlState.page);
+    }
+    // PageSize
+    if (urlState.pageSize !== null) {
+        searchForm.withPageSize(urlState.pageSize);
+    }
+    // Sort
+    if (urlState.sort) {
+        searchForm.withSort(urlState.sort.field, urlState.sort.direction);
+    }
+    // Quick search - reconstruct OR conditions if orFields exist
+    if (urlState.q && quickSearchPropertyName) {
+        if (orFields && orFields.length > 0) {
+            // Use handleQuickSearch for OR condition search
+            const allFields = [quickSearchPropertyName, ...orFields];
+            searchForm.handleQuickSearch(urlState.q, allFields);
+        }
+        else {
+            // Legacy single field search
+            searchForm.handleAndFilter(quickSearchPropertyName, urlState.q, 'LIKE');
+        }
+    }
+    // Filters
+    if (urlState.filters) {
+        if (urlState.filters.AND && urlState.filters.AND.length > 0) {
+            searchForm.withFilter('AND', ...urlState.filters.AND);
+        }
+        if (urlState.filters.OR && urlState.filters.OR.length > 0) {
+            searchForm.withFilter('OR', ...urlState.filters.OR);
+        }
+    }
+    return searchForm;
+}
+/**
+ * Merge URL state with sessionStorage state
+ * Priority: URL > sessionStorage > default
+ *
+ * @param urlState - State from URL
+ * @param sessionSearchForm - SearchForm from sessionStorage (can be undefined)
+ * @param quickSearchPropertyName - Quick search field name
+ * @param orFields - Additional fields that are searched with OR condition in quick search
+ * @returns Merged SearchForm
+ */
+export function mergeUrlAndSessionState(urlState, sessionSearchForm, quickSearchPropertyName, orFields) {
+    // If URL has any params, use URL state (URL priority)
+    if (hasUrlParams(urlState)) {
+        // Start with session form as base to preserve non-URL state
+        return urlStateToSearchForm(urlState, quickSearchPropertyName, sessionSearchForm, orFields);
+    }
+    // No URL params, use sessionStorage if available
+    if (sessionSearchForm) {
+        return sessionSearchForm.clone();
+    }
+    // Neither URL nor session, return empty
+    return SearchForm.create();
+}
+/**
+ * Extract quick search value from SearchForm
+ * @param searchForm - SearchForm to extract from
+ * @param quickSearchPropertyName - Quick search field name
+ * @param orFields - Additional fields that are searched with OR condition (for determining mode)
+ * @returns Quick search value or empty string
+ */
+export function getQuickSearchFromSearchForm(searchForm, quickSearchPropertyName, orFields) {
+    // First, try to get value from _quickSearch filter (OR condition search)
+    const quickSearchValue = searchForm.getQuickSearchValue();
+    if (quickSearchValue) {
+        return quickSearchValue;
+    }
+    // Fallback: try legacy single field search (only when not using OR search mode)
+    // When orFields exist, we're in OR search mode and AND filters on quickSearch fields
+    // should NOT be treated as quick search values
+    if (!quickSearchPropertyName || (orFields && orFields.length > 0)) {
+        return '';
+    }
+    const filters = searchForm.getFilter(quickSearchPropertyName);
+    if (filters.length > 0 && filters[0].filters.length > 0) {
+        return filters[0].filters[0].value ?? '';
+    }
+    return '';
+}
+/**
+ * Check if two URL states are equal
+ */
+export function areUrlStatesEqual(a, b) {
+    // Page
+    if (a.page !== b.page)
+        return false;
+    // PageSize
+    if (a.pageSize !== b.pageSize)
+        return false;
+    // Quick search
+    if (a.q !== b.q)
+        return false;
+    // Sort
+    if (a.sort?.field !== b.sort?.field || a.sort?.direction !== b.sort?.direction) {
+        return false;
+    }
+    // Filters (deep compare via JSON)
+    const aFilters = JSON.stringify(a.filters);
+    const bFilters = JSON.stringify(b.filters);
+    if (aFilters !== bFilters)
+        return false;
+    return true;
+}

package/dist/listgrid/components/list/hooks/urlStateParsers.d.ts

@@ -0,0 +1,63 @@
+import { Direction, FilterItem } from '../../../form/SearchForm';
+/**
+ * URL page parameter parser
+ * URL: 1-indexed (user-friendly)
+ * Internal: 0-indexed
+ */
+export declare const parseAsPage: import("../../../urlState").UrlParser<number>;
+/**
+ * URL pageSize parameter parser
+ * Default: 20
+ */
+export declare const parseAsPageSize: import("../../../urlState").UrlParser<number>;
+/**
+ * URL sort parameter parser
+ * Format: "field:direction" (e.g., "createdAt:DESC")
+ */
+export interface SortState {
+    field: string;
+    direction: Direction;
+}
+export declare const parseAsSort: import("../../../urlState").UrlParser<SortState | null>;
+/**
+ * URL filters parameter parser
+ * Human-readable format: "field:value,field:op:value"
+ *
+ * Examples:
+ *   ?filters=status:ACTIVE,type:FRESHMAN
+ *   ?filters=status:ACTIVE,name:like:홍길동,createdAt:gte:2024-01-01
+ *
+ * Format:
+ *   - Simple equality: field:value
+ *   - With operator: field:operator:value
+ *   - Multiple filters separated by comma
+ *   - Supported operators: eq, ne, like, gt, gte, lt, lte, in, isnull
+ */
+export interface FiltersState {
+    AND?: FilterItem[];
+    OR?: FilterItem[];
+}
+export declare const parseAsFilters: import("../../../urlState").UrlParser<FiltersState | null>;
+/**
+ * URL quick search parameter parser
+ * Simple string with URL encoding handled by nuqs
+ */
+export declare const parseAsQuickSearch: import("../../../urlState").UrlParser<string | null>;
+/**
+ * Type definitions for URL state
+ */
+export interface ListGridUrlState {
+    page: number | null;
+    pageSize: number | null;
+    q: string | null;
+    sort: SortState | null;
+    filters: FiltersState | null;
+}
+/**
+ * Default URL state
+ */
+export declare const defaultUrlState: ListGridUrlState;
+/**
+ * Check if URL has any ListGrid params
+ */
+export declare function hasUrlParams(urlState: ListGridUrlState): boolean;