@rchemist/listgrid 0.2.6

package/dist/listgrid/components/fields/abstract/ListableFormField.d.ts

@@ -0,0 +1,140 @@
+import React from 'react';
+import { FormField, FormFieldProps, ViewRenderProps, ViewRenderResult } from './FormField';
+import { EntityField, FilterRenderParameters } from '../../../config/EntityField';
+import { EntityForm } from '../../../config/EntityForm';
+import { LabelType, RenderType } from '../../../config/Config';
+import { TextAlignType } from '../../../common/type';
+import { QueryConditionType } from '../../../form/SearchForm';
+/**
+ * 중첩 객체에서 dot notation 경로로 값을 가져온다.
+ * 예: getNestedValue(item, 'score.student.name') -> item.score.student.name
+ * @param obj 대상 객체
+ * @param path dot notation 경로 (예: 'score.student.name')
+ * @returns 경로에 해당하는 값 또는 undefined
+ */
+export declare function getNestedValue(obj: any, path: string): any;
+export interface ViewListProps {
+    entityForm: EntityForm;
+    item: any;
+    router: any;
+    viewUrl: string;
+}
+export interface ViewListResult {
+    result: React.ReactNode | null;
+    linkOnCell?: boolean;
+}
+export interface IListConfig {
+    support?: boolean | undefined;
+    quickSearch?: boolean | undefined;
+    filterable?: boolean | undefined;
+    sortable?: boolean | undefined;
+    order?: number | undefined;
+    label?: LabelType | undefined;
+    align?: TextAlignType | undefined;
+    viewRaw?: boolean | undefined;
+    op?: QueryConditionType | undefined;
+    multiFilter?: boolean | undefined;
+}
+export interface UserListFieldProps {
+    order?: number;
+    quickSearch?: boolean;
+    sortable?: boolean;
+    filterable?: boolean;
+    multiFilter?: boolean;
+}
+export interface ListableFormFieldProps<TValue = any, TForm extends object = any> extends FormFieldProps<TValue, TForm> {
+    listConfig?: IListConfig;
+    showList?: boolean;
+    overrideRenderListItem?: (props: ViewListProps) => Promise<ViewListResult>;
+    overrideRenderListFilter?(params: FilterRenderParameters<TForm, TValue>): Promise<React.ReactNode | null>;
+}
+export declare abstract class ListableFormField<TSelf extends ListableFormField<TSelf, TValue, TForm>, TValue = any, TForm extends object = any> extends FormField<TSelf, TValue, TForm> {
+    listConfig?: IListConfig;
+    overrideRenderListItem?: (props: ViewListProps) => Promise<ViewListResult>;
+    overrideRenderListFilter?(params: FilterRenderParameters<TForm, TValue>): Promise<React.ReactNode | null>;
+    /**
+     * 각 필드의 핵심 리스트 필터 렌더링 로직을 구현하는 추상 메소드
+     * null을 반환하면 기본 필터 로직(원본 renderListFilter)을 적용
+     */
+    protected renderListFilterInstance(params: FilterRenderParameters<TForm, TValue>): Promise<React.ReactNode | null>;
+    /**
+     * 각 필드의 핵심 리스트 아이템 렌더링 로직을 구현하는 추상 메소드
+     * null을 반환하면 기본 리스트 아이템 로직(원본 renderListItem)을 적용
+     */
+    protected renderListItemInstance(props: ViewListProps): Promise<ViewListResult | null>;
+    /**
+     * ListGrid 에서 List 를 출력할 때 각 항목을 출력하는 방식.
+     * EntityForm 설정에서 overrideRenderList 를 이용해 오버라이드 할 수 있다.
+     * @param props
+     */
+    viewListItem(props: ViewListProps): Promise<ViewListResult>;
+    /**
+     * 목록의 통합 검색 표시
+     * EntityForm 을 설정할 때 overrideRenderListFilter 를 통해 override 할 수도 있다.
+     * 설정된 오버라이드가 없으면 #renderListFilter 를 실행한다.
+     * @param params
+     */
+    viewListFilter(params: FilterRenderParameters<TForm, TValue>): Promise<React.ReactNode | null>;
+    /**
+     * 리스트 필터 렌더링 - renderListFilterInstance가 null이면 원본 기본 로직 사용
+     */
+    protected renderListFilter(params: FilterRenderParameters<TForm, TValue>): Promise<React.ReactNode | null>;
+    /**
+     * 각 필드 별로 목록에 필터 처리가 될 때 어떻게 표시해야 하는지에 대한 기본 설정.
+     * ListableFormField 를 구현한 필드들에서 기본적인 렌더링 외에 필요한 처리가 있다면 이 메소드를 오버라이드 한다.
+     * 예를 들어, 날짜 필드는 단순 날짜 입력이 아니라 날짜 범위 입력이 가능하게 해야 한다든가 하는 등의 처리를 한다.
+     * @param onChange
+     * @param params
+     * @protected
+     */
+    protected renderListFilterOriginal({ onChange, ...params }: FilterRenderParameters<TForm, TValue>): Promise<React.ReactNode | null>;
+    /**
+     * 리스트 아이템 렌더링 - renderListItemInstance가 null이면 원본 기본 로직 사용
+     */
+    protected renderListItem(props: ViewListProps): Promise<ViewListResult>;
+    /**
+     * 각 필드 별로 목록에 표시할 때 어떻게 표시해야 하는지 처리한다.
+     * 기본적으로는 단순 문자열로 취급하지만,
+     * Boolean 타입인 경우 Badge 로 표시한다든가 날짜일 때는 몇 시간 전, 등의 표시로 바꾼다든가 각 필드 별로 이 메소드를 오버라이드 해 사용한다.
+     * @param props
+     * @protected
+     */
+    protected renderListItemOriginal(props: ViewListProps): Promise<ViewListResult>;
+    /**
+     * View 모드에서 필드 값을 렌더링하는 메소드 (ListableFormField 오버라이드)
+     * renderListItemInstance의 로직을 재사용하여 일관된 포맷 제공
+     *
+     * @param props View 렌더링에 필요한 파라미터
+     * @returns 렌더링 결과
+     */
+    protected renderViewInstance(props: ViewRenderProps): Promise<ViewRenderResult>;
+    useListField(props?: number | UserListFieldProps): this;
+    withListConfig(list?: IListConfig): this;
+    withOverrideRenderListItem(overrideRenderList?: (props: ViewListProps) => Promise<ViewListResult>): this;
+    withOverrideRenderListFilter(overrideRenderFilter?: (params: FilterRenderParameters<TForm, TValue>) => Promise<React.ReactNode | null>): this;
+    isSupportList(): boolean;
+    getListConfig(): IListConfig | undefined;
+    getListFieldAlignType(): TextAlignType;
+    /**
+     * 목록 필터 사용 여부 설정.
+     * 설정이 없는 한 필터 사용은 true 이다.
+     * 하지만 필터 처리를 하지 말아야 하는 경우에는 이 값을 false 로 명시적으로 선언해야 한다.
+     * @param filterable
+     */
+    withFilterable(filterable?: boolean): this;
+    /**
+     * EntityForm 이 저장될 때 서버로 전송할 값을 override 하는 메소드
+     * @param saveValue
+     */
+    withSaveValue(saveValue: (entityForm: EntityForm<TForm>, field: EntityField, renderType?: RenderType) => Promise<TValue>): this;
+    /**
+     * 목록 정렬 사용 여부 설정
+     * 설정이 없는 한 정렬 사용은 true 이다.
+     * 하지만 정렬을 하지 말아야 하는 경우에는 이 값을 false 로 명시적으로 선언해야 한다.
+     * @param sortable
+     */
+    withSortable(sortable?: boolean): this;
+    isFilterable(): boolean;
+    isSortable(): boolean;
+    protected copyFields(origin: ListableFormFieldProps<TValue, TForm>, includeValue?: boolean): this;
+}

package/dist/listgrid/components/fields/abstract/ListableFormField.js

@@ -0,0 +1,285 @@
+import { FormField } from './FormField';
+import { isTrue } from '../../../utils/BooleanUtil';
+/**
+ * 중첩 객체에서 dot notation 경로로 값을 가져온다.
+ * 예: getNestedValue(item, 'score.student.name') -> item.score.student.name
+ * @param obj 대상 객체
+ * @param path dot notation 경로 (예: 'score.student.name')
+ * @returns 경로에 해당하는 값 또는 undefined
+ */
+export function getNestedValue(obj, path) {
+    if (!obj || !path)
+        return undefined;
+    // dot notation이 아니면 직접 접근
+    if (!path.includes('.')) {
+        return obj[path];
+    }
+    // dot notation 경로를 따라 값을 가져옴
+    const keys = path.split('.');
+    let value = obj;
+    for (const key of keys) {
+        if (value === null || value === undefined) {
+            return undefined;
+        }
+        value = value[key];
+    }
+    return value;
+}
+export class ListableFormField extends FormField {
+    /**
+     * 각 필드의 핵심 리스트 필터 렌더링 로직을 구현하는 추상 메소드
+     * null을 반환하면 기본 필터 로직(원본 renderListFilter)을 적용
+     */
+    async renderListFilterInstance(params) {
+        return null;
+    }
+    /**
+     * 각 필드의 핵심 리스트 아이템 렌더링 로직을 구현하는 추상 메소드
+     * null을 반환하면 기본 리스트 아이템 로직(원본 renderListItem)을 적용
+     */
+    async renderListItemInstance(props) {
+        return null;
+    }
+    /**
+     * ListGrid 에서 List 를 출력할 때 각 항목을 출력하는 방식.
+     * EntityForm 설정에서 overrideRenderList 를 이용해 오버라이드 할 수 있다.
+     * @param props
+     */
+    async viewListItem(props) {
+        if (this.overrideRenderListItem) {
+            return this.overrideRenderListItem(props);
+        }
+        return this.renderListItem(props);
+    }
+    /**
+     * 목록의 통합 검색 표시
+     * EntityForm 을 설정할 때 overrideRenderListFilter 를 통해 override 할 수도 있다.
+     * 설정된 오버라이드가 없으면 #renderListFilter 를 실행한다.
+     * @param params
+     */
+    async viewListFilter(params) {
+        if (this.overrideRenderListFilter) {
+            return this.overrideRenderListFilter?.(params);
+        }
+        return this.renderListFilter(params);
+    }
+    /**
+     * 리스트 필터 렌더링 - renderListFilterInstance가 null이면 원본 기본 로직 사용
+     */
+    renderListFilter(params) {
+        return (async () => {
+            const customFilter = await this.renderListFilterInstance(params);
+            if (customFilter !== null) {
+                return customFilter;
+            }
+            // 원본 기본 필터 로직 실행
+            return this.renderListFilterOriginal(params);
+        })();
+    }
+    /**
+     * 각 필드 별로 목록에 필터 처리가 될 때 어떻게 표시해야 하는지에 대한 기본 설정.
+     * ListableFormField 를 구현한 필드들에서 기본적인 렌더링 외에 필요한 처리가 있다면 이 메소드를 오버라이드 한다.
+     * 예를 들어, 날짜 필드는 단순 날짜 입력이 아니라 날짜 범위 입력이 가능하게 해야 한다든가 하는 등의 처리를 한다.
+     * @param onChange
+     * @param params
+     * @protected
+     */
+    renderListFilterOriginal({ onChange, ...params }) {
+        return this.render({
+            ...params,
+            required: false,
+            onChange: (value) => onChange(value),
+        });
+    }
+    /**
+     * 리스트 아이템 렌더링 - renderListItemInstance가 null이면 원본 기본 로직 사용
+     */
+    renderListItem(props) {
+        return (async () => {
+            const customItem = await this.renderListItemInstance(props);
+            if (customItem !== null) {
+                return customItem;
+            }
+            // 원본 기본 리스트 아이템 로직 실행
+            return this.renderListItemOriginal(props);
+        })();
+    }
+    /**
+     * 각 필드 별로 목록에 표시할 때 어떻게 표시해야 하는지 처리한다.
+     * 기본적으로는 단순 문자열로 취급하지만,
+     * Boolean 타입인 경우 Badge 로 표시한다든가 날짜일 때는 몇 시간 전, 등의 표시로 바꾼다든가 각 필드 별로 이 메소드를 오버라이드 해 사용한다.
+     * @param props
+     * @protected
+     */
+    renderListItemOriginal(props) {
+        // 중첩 객체 접근 지원 (예: score.student.name)
+        const value = String(getNestedValue(props.item, this.name) ?? '');
+        return Promise.resolve({ result: value });
+    }
+    /**
+     * View 모드에서 필드 값을 렌더링하는 메소드 (ListableFormField 오버라이드)
+     * renderListItemInstance의 로직을 재사용하여 일관된 포맷 제공
+     *
+     * @param props View 렌더링에 필요한 파라미터
+     * @returns 렌더링 결과
+     */
+    async renderViewInstance(props) {
+        // ViewListProps 형태로 변환하여 renderListItemInstance 호출
+        const viewListProps = {
+            entityForm: props.entityForm ?? {},
+            item: props.item,
+            router: null,
+            viewUrl: '',
+        };
+        // 기존 renderListItemInstance 로직 재사용
+        const listResult = await this.renderListItemInstance(viewListProps);
+        if (listResult !== null) {
+            return { result: listResult.result };
+        }
+        // renderListItemInstance가 null을 반환하면 기본 로직 사용
+        const originalResult = await this.renderListItemOriginal(viewListProps);
+        return { result: originalResult.result };
+    }
+    useListField(props) {
+        if (typeof props === 'number') {
+            props = { order: props };
+        }
+        const base = { ...this.listConfig, support: true };
+        if (props?.order !== undefined)
+            base.order = props.order;
+        this.listConfig = base;
+        // quickSearch는 명시적으로 설정된 경우에만 적용
+        // (원칙: quickSearch: true가 명시적으로 설정된 필드들만 대상으로 한다)
+        if (props?.quickSearch !== undefined) {
+            this.listConfig.quickSearch = props.quickSearch;
+        }
+        if (props?.sortable !== undefined) {
+            this.listConfig.sortable = props.sortable;
+        }
+        if (props?.filterable !== undefined) {
+            this.listConfig.filterable = props.filterable;
+        }
+        return this;
+    }
+    withListConfig(list) {
+        if (list) {
+            this.listConfig = { ...list };
+            if (this.listConfig.label === undefined) {
+                this.listConfig.label = this.getLabel();
+            }
+            if (this.listConfig.support === undefined) {
+                this.listConfig.support = true;
+            }
+        }
+        else {
+            delete this.listConfig;
+        }
+        return this;
+    }
+    withOverrideRenderListItem(overrideRenderList) {
+        if (overrideRenderList !== undefined)
+            this.overrideRenderListItem = overrideRenderList;
+        else
+            delete this.overrideRenderListItem;
+        return this;
+    }
+    withOverrideRenderListFilter(overrideRenderFilter) {
+        if (overrideRenderFilter !== undefined)
+            this.overrideRenderListFilter = overrideRenderFilter;
+        else
+            delete this.overrideRenderListFilter;
+        return this;
+    }
+    isSupportList() {
+        return this.listConfig !== undefined && isTrue(this.listConfig.support);
+    }
+    getListConfig() {
+        const listConfig = { ...this.listConfig };
+        if (!this.isSupportList()) {
+            return listConfig;
+        }
+        // 기본값 설정
+        if (!listConfig.order) {
+            listConfig.order = this.order;
+        }
+        if (!listConfig.label) {
+            listConfig.label = this.getLabel();
+        }
+        return listConfig;
+    }
+    getListFieldAlignType() {
+        const config = this.getListConfig();
+        if (config?.align !== undefined) {
+            return config.align;
+        }
+        if (this.type === 'select' ||
+            this.type === 'multiselect' ||
+            this.type === 'date' ||
+            this.type === 'datetime' ||
+            this.type === 'boolean' ||
+            this.type === 'year' ||
+            this.type === 'month' ||
+            this.type === 'time' ||
+            this.type === 'file' ||
+            this.type === 'image') {
+            return 'center';
+        }
+        return 'left';
+    }
+    /**
+     * 목록 필터 사용 여부 설정.
+     * 설정이 없는 한 필터 사용은 true 이다.
+     * 하지만 필터 처리를 하지 말아야 하는 경우에는 이 값을 false 로 명시적으로 선언해야 한다.
+     * @param filterable
+     */
+    withFilterable(filterable) {
+        this.listConfig = { ...this.getListConfig(), filterable: isTrue(filterable, true) };
+        return this;
+    }
+    /**
+     * EntityForm 이 저장될 때 서버로 전송할 값을 override 하는 메소드
+     * @param saveValue
+     */
+    withSaveValue(saveValue) {
+        this.saveValue = saveValue;
+        return this;
+    }
+    /**
+     * 목록 정렬 사용 여부 설정
+     * 설정이 없는 한 정렬 사용은 true 이다.
+     * 하지만 정렬을 하지 말아야 하는 경우에는 이 값을 false 로 명시적으로 선언해야 한다.
+     * @param sortable
+     */
+    withSortable(sortable) {
+        this.listConfig = { ...this.getListConfig(), sortable: isTrue(sortable, true) };
+        return this;
+    }
+    isFilterable() {
+        if (!this.isSupportList()) {
+            if (this.listConfig !== undefined) {
+                return isTrue(this.listConfig.filterable, true);
+            }
+            return false;
+        }
+        return isTrue(this.getListConfig()?.filterable, true);
+    }
+    isSortable() {
+        if (!this.isSupportList()) {
+            if (this.listConfig !== undefined) {
+                return isTrue(this.listConfig.sortable, true);
+            }
+            return false;
+        }
+        return isTrue(this.getListConfig()?.sortable, true);
+    }
+    copyFields(origin, includeValue = true) {
+        super
+            .copyFields(origin, includeValue)
+            .withListConfig(origin.listConfig)
+            .withOverrideRenderListItem(origin.overrideRenderListItem);
+        if (isTrue(origin.showList)) {
+            this.useListField();
+        }
+        return this;
+    }
+}

package/dist/listgrid/components/fields/abstract/OptionalField.d.ts

@@ -0,0 +1,96 @@
+import { ListableFormField, ListableFormFieldProps, ViewListProps } from './ListableFormField';
+import { ComboProps, FieldType, RenderType } from '../../../config/Config';
+import { MinMaxLimit, SelectOption } from '../../../form/Type';
+import { ValidateResult } from '../../../validations/Validation';
+import { EntityForm } from '../../../config/EntityForm';
+import { Session } from '../../../auth/types';
+/**
+ * Chip UI 설정
+ */
+export interface ChipConfig {
+    enabled: boolean;
+    maxOptions?: number;
+    maxLabelLength?: number;
+}
+export interface OptionalFieldProps<TValue = any, TForm extends object = any> extends ListableFormFieldProps<TValue, TForm> {
+    combo?: ComboProps;
+    options?: SelectOption[];
+    preservedOptions?: SelectOption[];
+    chipConfig?: ChipConfig;
+    singleFilter?: boolean;
+}
+export declare abstract class OptionalField<TSelf extends OptionalField<TSelf, TValue, TForm>, TValue = any, TForm extends object = any> extends ListableFormField<TSelf, TValue, TForm> {
+    combo?: ComboProps;
+    options?: SelectOption[];
+    preservedOptions?: SelectOption[];
+    chipConfig?: ChipConfig;
+    singleFilter?: boolean;
+    /**
+     * 목록 필터에서 단일 선택만 허용하도록 설정합니다.
+     * true로 설정하면 필터가 EQUAL 조건으로 동작하고, RadioChip으로 렌더링됩니다.
+     * @param enabled 단일 선택 여부 (기본값: true)
+     */
+    withSingleFilter(enabled?: boolean): this;
+    /**
+     * 이 필드를 라디오 버튼이나 Checkbox 타입으로 표시하는 경우 이 메소드를 호출한다.
+     * @param props direction 설정
+     */
+    withComboType(props?: ComboProps): this;
+    withOptions(options?: SelectOption[]): this;
+    withPreservedOptions(options?: SelectOption[]): this;
+    /**
+     * Chip UI를 사용하도록 설정
+     * @param enabled Chip UI 활성화 여부 (기본값: true)
+     * @param config 추가 설정 (maxOptions, maxLabelLength)
+     */
+    useChip(enabled?: boolean, config?: Partial<Omit<ChipConfig, 'enabled'>>): this;
+    /**
+     * Chip UI로 렌더링할 조건을 충족하는지 확인
+     * - chipConfig가 undefined: 옵션 수/라벨 길이 조건 자동 체크
+     * - useChip(true): 강제 Chip 사용
+     * - useChip(false): 강제 Chip 사용 안 함
+     */
+    shouldRenderAsChip(): boolean;
+    changeOptions(options: SelectOption[], defaultValue?: TValue): boolean;
+    revertOptions(renderType?: RenderType): boolean;
+    protected copyFields(origin: OptionalFieldProps<TValue, TForm>, includeValue?: boolean): this;
+}
+export interface MultipleOptionalFieldProps<TValue = any, TForm extends object = any> extends OptionalFieldProps<TValue, TForm> {
+    limit?: MinMaxLimit;
+}
+export declare abstract class MultipleOptionalField<TSelf extends MultipleOptionalField<TSelf, TValue, TForm>, TValue = any, TForm extends object = any> extends OptionalField<TSelf, TValue, TForm> {
+    limit?: MinMaxLimit;
+    /**
+     * 복수 선택할 수 있는 최소, 최대 개수 설정
+     * 설정된 최소값이 있다면 해당 개수 미만을 선택하면 에러
+     * 설정된 최대값이 있다면 해당 개수를 초과하면 에러
+     * @param limit
+     */
+    withLimit(limit?: MinMaxLimit): this;
+    /**
+     * 복수 선택할 수 있는 최소 개수만 설정
+     * @param min
+     */
+    withMin(min?: number): this;
+    /**
+     * 복수 선택할 수 있는 최대 개수 설정
+     * @param max
+     */
+    withMax(max?: number): this;
+    protected createCacheKey(renderType?: RenderType): string;
+    protected constructor(name: string, order: number, type: FieldType, options?: SelectOption[], limit?: MinMaxLimit);
+    protected copyFields(origin: OptionalFieldProps<TValue, TForm>, includeValue?: boolean): this;
+    validate(entityForm: EntityForm<TForm>, session?: Session): Promise<ValidateResult | ValidateResult[]>;
+    private validateWithLimit;
+}
+export declare function renderListOptionalField(field: OptionalField<any>, props: ViewListProps): Promise<{
+    result: string;
+}> | Promise<{
+    result: import("react/jsx-runtime").JSX.Element;
+    linkOnCell: boolean;
+}>;
+export declare function renderListMultipleOptionalField(field: OptionalField<any>, props: ViewListProps): Promise<{
+    result: string;
+}> | Promise<{
+    result: import("react/jsx-runtime").JSX.Element;
+}>;