import { TemplateResult } from 'lit'; import { DataCardField } from './data-card/data-card-field.js'; import { DataCardGutter } from './data-card/data-card-gutter.js'; import { RecordCard } from './data-card/record-card.js'; import { DataGridField } from './data-grid/data-grid-field.js'; import { DataListField } from './data-list/data-list-field.js'; import { DataListGutter } from './data-list/data-list-gutter.js'; import { RecordPartial } from './data-list/record-partial.js'; import { DataReportField } from './data-report/data-report-field.js'; import { OxGristEditor } from './editors/index.js'; import { QueryFilter, OxFiltersForm } from './filters/index.js'; import { OxGristRenderer } from './renderers/ox-grist-renderer.js'; /** * Configuration object for defining the structure and behavior of a Grist table. * * @typedef {Object} GristConfig * @property {ColumnConfig[]} columns - An array of column configurations. * @property {RowsConfig} rows - Configuration for rows and their behavior. * @property {ListConfig} list - Configuration for the list view. * @property {TreeConfig} tree - Configuration for tree-related settings. * @property {PaginationConfig} [pagination] - Configuration for pagination settings (optional). * @property {SortersConfig} [sorters] - Configuration for sorting settings (optional). * @property {FiltersConfig} [filters] - Configuration for filtering settings (optional). */ export type GristConfig = { columns: ColumnConfig[]; rows: RowsConfig; list: ListConfig; tree: TreeConfig; pagination?: PaginationConfig; sorters?: SortersConfig; filters?: FiltersConfig; /** * 아직 아무것도 없을 때 화면이 하는 말. * * 전에는 「NO RECORDS」가 컴포넌트에 박혀 있었다. 그 문장은 다음에 무엇을 할지 알려 주지 않는다 — * **비어 있는 화면이야말로** 「여기서 무엇을 만들 수 있고 그것이 무엇에 쓰이나」를 말해야 하는 자리이고, * 처음 오는 사람이 가장 먼저 보는 화면이기도 하다. * * 정하지 않으면 예전 문장이 그대로 나온다. */ emptyNote?: { title?: string; description?: string; icon?: string; }; }; /** * Configuration object for specifying sorting options. * * @typedef {Object} SorterConfig * @property {string} name - The name of the sorting option. * @property {boolean} [desc] - Optional. Indicates whether the sorting is in descending order (optional). */ export type SorterConfig = { name: string; desc?: boolean; }; /** * Configuration array for specifying multiple sorting options. * * @typedef {SorterConfig[]} SortersConfig */ export type SortersConfig = SorterConfig[]; /** * Enumeration of filter operators used to define filter conditions. * * @typedef {'search' | 'eq' | 'between' | 'gte' | 'lte' | 'is_not_true' | 'in' | 'like' | 'i_like' | 'noteq' | * 'is_empty_num_id' | 'is_blank' | 'is_present' | 'is_not_false' | 'is_true' | 'is_false' | 'is_not_null' | * 'is_null' | 'notin_with_null' | 'notin' | 'gt' | 'lt' | 'i_nlike' | 'nlike'} FilterOperator */ export type FilterOperator = 'search' | 'eq' | 'between' | 'gte' | 'lte' | 'is_not_true' | 'in' | 'like' | 'i_like' | 'noteq' | 'is_empty_num_id' | 'is_blank' | 'is_present' | 'is_not_false' | 'is_true' | 'is_false' | 'is_not_null' | 'is_null' | 'notin_with_null' | 'notin' | 'gt' | 'lt' | 'i_nlike' | 'nlike'; export type SelectOptionObject = { name: string; display?: never; value: string; } | { display: string; name?: never; value: string; }; export type SelectOption = SelectOptionObject | string; export type FilterChangedCallback = (value: any, form: OxFiltersForm) => boolean; /** * Configuration object for specifying filter conditions. * * @typedef {Object} FilterConfigObject * @property {string} type - The type of the filter condition. * @property {FilterOperator} [operator] - The filter operator used to compare values (optional). * @property {Object} [options] - Additional options or parameters for the filter condition (optional). * @property {boolean|undefined} [hidden] - The hidden flag for the filter condition (optional). * @property {string|number|boolean|string[]|number[]|undefined} [value] - The value to compare with in the filter condition (optional). * @property {string} [label] - The label to display for the filter condition (optional). */ export type FilterConfigObject = { type: string; operator?: FilterOperator; options?: { [key: string]: any; }; value?: string | number | boolean | string[] | number[] | undefined; label?: string; boundTo?: string[]; hidden?: boolean; onchange?: FilterChangedCallback; }; /** * Configuration option for specifying filter conditions. * * The `FilterConfig` type can take one of the following forms: * - A `FilterConfigObject` representing a specific filter condition. * - A `FilterOperator` representing a predefined filter operator. * - A boolean value to enable or disable filtering for a specific column. * * @typedef {Object|FilterOperator|boolean} FilterConfig */ export type FilterConfig = FilterConfigObject | FilterOperator | boolean; /** * Represents a filter condition with the following properties: * * - `name`: The name of the column or field being filtered. * - `operator`: The filter operator used for comparison. * - `value`: The value or values to compare against. * * @typedef {Object} FilterValue * @property {string} name - The name of the column or field. * @property {FilterOperator} operator - The filter operator. * @property {string|number|boolean|string[]|number[]|undefined} value - The value(s) to compare. */ export type FilterValue = { name: string; operator: FilterOperator; value: string | number | boolean | string[] | number[] | undefined; }; /** * Configuration options for filters. * * @typedef {Object} FiltersConfig * @property {boolean} [header] - Specifies whether to provide filtering functionality in the header. */ export type FiltersConfig = { header?: boolean; }; /** * Configuration options for pagination. * * @typedef {Object} PaginationConfig * @property {number} [page] - The current page number. * @property {number} [limit] - The maximum number of records to display per page. * @property {number[]} [pages] - An array of available page numbers. * @property {boolean} [infinite] - Specifies whether to use infinite scrolling for pagination. */ export type PaginationConfig = { page?: number; limit?: number; pages?: number[]; infinite?: boolean; }; /** * Option to specify the inheritance behavior for including data from parent domains. * * - 'None': Do not include data from the parent domain. * - 'Include': Include data from the parent domain along with current domain data. * - 'Only': Include data only from the parent domain, excluding current domain data. * * @enum {string} */ export declare enum InheritedValueType { None = "None", Include = "Include", Only = "Only" } /** * Configuration options for fetching data from a data source. * * @typedef {Object} FetchOption * @property {number} [page] - The page number to retrieve. * @property {number} [limit] - The maximum number of records to retrieve per page. * @property {SortersConfig} [sorters] - An array of sorting configurations for data. Only one of these options needs to be set. * @property {SortersConfig} [sortings] - An array of sorting configurations for data. Only one of these options needs to be set. * @property {QueryFilter[]} [filters] - An array of filtering criteria. * @property {string} [search] - A single free-text term, carried as given. The resolver matches it across the fields it declares as searchable, so the screen does not carry a copy of that list. * @property {InheritedValueType} [inherited] - Specifies the inheritance behavior for including data from parent domains. * @property {object} [options] - Additional options for customizing data fetching behavior. */ export type FetchOption = { page?: number; limit?: number; sorters?: SortersConfig; sortings?: SortersConfig; filters?: QueryFilter[]; search?: string; inherited?: InheritedValueType; options?: object; /** Aborted once a later read replaces this one or the grid is invalidated: pass it to the request. */ signal?: AbortSignal; }; /** * Represents the result of a data fetching operation. * * @typedef {Object} FetchResult * @property {number} [page] - The page number of the fetched data. * @property {number} [limit] - The maximum number of records per page. * @property {number} total - The total number of records in the data source. * @property {GristRecord[]} records - An array of fetched data records. */ export type FetchResult = { page?: number; limit?: number; total: number; records: GristRecord[]; } | void; /** * A function that handles data fetching operations. * * @param param - The fetch options specifying how data should be retrieved. * @returns A promise that resolves to a `FetchResult`. */ export type FetchHandler = (param: FetchOption) => Promise; /** * The counts a list shows beside its filter choices (a chip's number), read with the same conditions as the rows: * `{ [column name]: { [option value]: count } }`. Run beside each fetch that replaces the rows, under its signal. */ export type CountHandler = (param: FetchOption) => Promise>>; /** * Represents a Grist event handler function. * * @typedef {Function} GristEventHandler * @param {ColumnConfig[]} columns - An array of column configurations. * @param {GristData} [data] - The Grist data associated with the event. * @param {ColumnConfig} [column] - The column configuration related to the event (if applicable). * @param {GristRecord} [record] - The Grist record related to the event (if applicable). * @param {number} [rowIndex] - The index of the row related to the event (if applicable). * @param {any} [target] - The target element or object related to the event (if applicable). * @param {Event} [e] - The event object (if applicable). * @returns {void} */ export type GristEventHandler = (columns: ColumnConfig[], data?: GristData, column?: ColumnConfig, record?: GristRecord, rowIndex?: number, target?: any, e?: Event) => void; /** * Represents an accumulator function for data aggregation and accumulation. * * @typedef {string|'sum'|'avg'|'count'|'min'|'max'|Function} AccumulatorFunc * @param {GristData} data - The Grist data for aggregation. * @param {ColumnConfig} column - The column configuration for aggregation. * @returns {string|number} - The aggregated result. */ export type AccumulatorFunc = 'sum' | 'avg' | 'count' | 'min' | 'max' | ((data: GristData, column: ColumnConfig) => string | number); /** * Type representing an accumulator function or configuration object. * * An accumulator is used for data aggregation and accumulation purposes. It can be either * a predefined accumulator function (e.g., 'sum', 'avg', 'count', etc.) or a configuration * object specifying the type of accumulator and labeling options. * * @typedef {AccumulatorFunc|{type: AccumulatorFunc, tag?: boolean}} AccumulatorObject * @property {AccumulatorFunc} [type] - The type of accumulator function or predefined function name. * @property {boolean} [tag] - An option for adding a label to represent the result of an aggregation function. This label is added in front of the aggregated value. * * @example * // Using a predefined accumulator function: * const accumulator: AccumulatorObject = 'sum'; // Represents a 'sum' accumulator. * * // Using an accumulator configuration object: * const accumulatorConfig: AccumulatorObject = { * type: 'avg', // Specifies the type of accumulator ('avg' for average). * tag: true, // Option for adding a label to represent the result of an aggregation function. This label is added in front of the aggregated value. * }; */ export type AccumulatorObject = AccumulatorFunc | { type: AccumulatorFunc; tag?: boolean; }; /** * Type representing column configuration information. * * @typedef {object} ColumnConfig * @property {string} type - Represents the data type of the column (e.g., 'text', 'number', 'date', 'gutter', etc.). * @property {string} name - Represents the name of the column. * @property {('button'|'sequence'|'row-selector'|'dirty')} [gutterName] - If the column type is 'gutter', specifies the name of one of the registered gutters (only set when the type is 'gutter'). * @property {boolean} [fixed] - In case of a grid type column, specifies whether the column's position should be fixed and unaffected by horizontal scrolling (optional). * @property {HeaderConfig} header - Object representing the header configuration of the column. * @property {RecordConfig} record - Object representing the record configuration of the column. * @property {GristEventHandlerSet} handlers - Object representing the Grist event handler settings. * @property {LabelConfig} label - Object representing the label configuration of the column. This property is used to represent the label of the column's information in list mode, card mode, and when displaying the column in a filter form (ox-filters-form). * @property {boolean} [hidden] - Indicates whether the column is hidden or not (optional). * @property {boolean} [sortable] - Indicates whether the column is sortable or not (optional). If this setting is true, the header provides the ability to toggle the sorting direction. * @property {boolean} [resizable] - Indicates whether the column is resizable or not (optional). This setting determines whether the column's width can be adjusted. * @property {(number|string|ColumnWidthCallback)} [width] - Represents the width of the column (e.g., 100, '50%', or a callback function to calculate width). * @property {boolean} [forList] - Indicates whether the column is intended for display in list mode (optional, applicable only to gutter type columns). * @property {boolean} [forCard] - Indicates whether the column is intended for display in card mode (optional, applicable only to gutter type columns). * @property {ValidationCallback} [validation] - Callback function for column validation (optional). This function validates whether the value of the column is valid when edited. * @property {AccumulatorObject} [accumulator] - Object used for accumulating values of the column (optional, applicable only in grid mode). It specifies a function to automatically aggregate the values of the column for all records. The aggregated result is displayed in a row below the last record (accumulation record). * @property {FilterConfig} [filter] - Object representing the filter configuration of the column. * @property {(ImexConfig|boolean)} [imex] - Object or boolean value representing the configuration for importing and exporting column data. * @property {boolean} [multiple] - Indicates whether the column allows multiple selections or not (optional). * @property {boolean} [rowCount] - Indicates whether the column shows the row count or not (optional). */ export type ColumnConfig = { type: string; name: string; /** * "gutter" 타입의 컬럼인 경우, 등록된 gutter들 중의 하나의 이름을 명시합니다(type이 gutter인 경우에만 설정합니다). * (e.g., 'button', 'sequence', 'row-selector', 'dirty', etc) * * "Gutter" 는 테이블에서 각 행의 왼쪽이나 오른쪽에 놓이는 추가 열(column)을 뜻합니다. * 이 열은 주로 각 행(row)을 식별하거나 특정 작업을 수행하기 위한 버튼 또는 링크와 같은 요소를 표시하는 데 사용됩니다. * Gutter 열은 주로 데이터 행에 대한 조작 또는 행의 상태를 나타내는 데 사용됩니다. * 예를 들어, 테이블에서 각 행이 특정 작업을 수행하는 버튼을 포함할 때, 이러한 버튼이 Gutter 열에 배치될 수 있습니다. * 또한 Gutter 열은 행을 선택하거나 행의 상태를 나타내는 체크박스를 포함할 수도 있습니다. */ gutterName?: 'button' | 'sequence' | 'row-selector' | 'dirty'; title?: string; fixed?: boolean; /** [begin] only for button gutter column */ icon?: string; iconOnly?: boolean; danger?: boolean; /** * CARD mode, gutter columns: draw this button only while the card is hovered (or focused). A * function decides per record - e.g. a favorite star that is quiet until set, then stays. On a * device with no hover (touch) quiet gutters are always drawn, so nothing becomes unreachable. */ quiet?: boolean | ((record: GristRecord) => boolean); /** [end] only for button gutter column */ header: HeaderConfig; record: RecordConfig; handlers: GristEventHandlerSet; label: LabelConfig; hidden?: boolean; sortable?: boolean; resizable?: boolean; width?: number | string | ColumnWidthCallback; forList?: boolean; forCard?: boolean; validation?: ValidationCallback; accumulator?: AccumulatorObject; filter?: FilterConfig; imex?: ImexConfig | boolean; multiple?: boolean; rowCount?: boolean; /** 특정 도구에 의해서 사용되는 옵션으로, 일반적인 용도로 사용되지 않음을 표현할 수 있다. */ unusable?: boolean; multiline?: boolean; }; /** * Callback function type for column validation. * * This function is used to validate whether the value of a column is valid when edited. * * @callback ValidationCallback * @param {any} after - The new value of the column after editing. * @param {any} before - The previous value of the column before editing. * @param {GristRecord} record - The record being edited. * @param {ColumnConfig} column - The configuration of the column being edited. * @returns {boolean} - Returns `true` if the value is valid, `false` otherwise. */ export type ValidationCallback = (after: any, before: any, record: GristRecord, column: ColumnConfig) => boolean | Promise; /** * Configuration options for column labels. * * The label for a column can be customized using various options. * * @typedef {string|boolean|Object} LabelConfig * @property {LabelRenderer} [renderer] - A custom renderer function for the column label. * * @example * // Using a string as a label: * const label: LabelConfig = "Column Label"; // Sets the label as "Column Label". * * // Using a boolean to determine label visibility: * const label: LabelConfig = true; // Shows the default label based on the header configuration. * * // Using a custom renderer function for the label: * const label: LabelConfig = { * renderer: customLabelRenderer, // Specifies a custom renderer function. * }; */ export type LabelConfig = string | boolean | { renderer: LabelRenderer; /** Same as HeaderConfig.text — the name itself, not what was drawn from it. */ text?: string; }; /** * Custom label renderer function for generating column labels. * * @callback LabelRenderer * @param {ColumnConfig} column - The column configuration object for which the label is being generated. * @returns {void} */ export type LabelRenderer = (column: ColumnConfig) => void; /** * Custom callback function for calculating column width. * * @callback ColumnWidthCallback * @param {ColumnConfig} column - The column configuration object for which the width is being calculated. * @returns {string} - The calculated width as a string (e.g., '100', '50%'). */ export type ColumnWidthCallback = (column: ColumnConfig) => string; /** * Configuration for defining the header of a column. * * @typedef {Object} HeaderConfig * @property {HeaderRenderer} renderer - The function used to render the column header. * @property {string} [style] - Optional CSS style for the column header. * @property {string} [group] - Optional group identifier for the column header. * @property {string} [groupStyle] - Optional CSS style for the header group. */ export type HeaderConfig = { renderer: HeaderRenderer; /** * The column's name as plain text. * * `renderer` returns whatever gets drawn — a lit template, an icon — and the name cannot be read * back out of that. So a name given as a string in the config is kept here, for the places that * need it outside of rendering: the accessible name of a cell, and header filter inputs. */ text?: string; style?: string; group?: string; groupStyle?: string; }; /** * Function type for rendering column headers. * * @callback HeaderRenderer * @param {ColumnConfig} column - The column configuration object. * @returns {*} - The rendered header content. */ export type HeaderRenderer = (column: ColumnConfig) => any; /** * Configuration for specifying default values for fields in a record. * Default values can be set using predefined value generator functions or custom user-defined functions. * This configuration allows you to define the default value generation method and any additional parameters. * * @typedef {Object|Function} DefaultValueFnConfig * @property {string} [name] - The name of the default value function to be used for the column. * @property {any[]} [params] - The parameters to be passed to the default value function. * @property {Function} [Function] - A custom user-defined function for generating default values. */ export type DefaultValueFnConfig = { /** * The name of the default value function to be used for the column. */ name: string; /** * The parameters to be passed to the default value function. */ params?: any[]; } | Function; /** * Configuration for defining fields within a record. * Each field can have various settings such as rendering, editing, alignment, etc. * The 'defaultValue' property is used to specify the default value generation method and parameters. * * @typedef {Object} RecordConfig * @property {FieldRenderer} renderer - The rendering function for the field. * @property {FieldEditor|undefined} [editor] - The editing function for the field (optional). * @property {boolean|Function} [editable] - Specifies if the field is editable. It can be a boolean or a function (optional). * @property {boolean} [mandatory] - Specifies if the field is mandatory (optional). * @property {GristClassifier} classifier - A classifier function for the field. * @property {'left'|'right'|'center'} [align] - The alignment of the field's content (optional). * @property {*} options - Additional options for the field. * @property {string|undefined} [rowOptionField] - The name of a field for row-level options associated with this field (optional). * @property {DefaultValueFnConfig|undefined} [defaultValue] - Configuration for specifying the default value for the field. * It can be a predefined value generator function or a custom user-defined function (optional). * @property {Object.|undefined} [extended] - Additional extended properties that can be added as needed for specific field configurations (optional). * @property {boolean} [wide] - Specifies if the field should occupy a larger width within the viewer or editor. * When set to `true`, the field will attempt to span across multiple columns or occupy more space horizontally. */ export type RecordConfig = { renderer: FieldRenderer; editor?: FieldEditor; editable?: boolean | Function; mandatory?: boolean; disabled?: boolean | Function; classifier: GristClassifier; align?: 'left' | 'right' | 'center'; options: any; rowOptionField?: string; defaultValue?: DefaultValueFnConfig; wide?: boolean; /** * Draw the field even when the record has no value for it (card mode's thumbnail). * * A thumbnail with no value is normally not drawn at all, so a list of records without images * does not show a column of broken-image marks. A renderer that draws the empty case itself — * and anything it overlays on the picture — needs the element regardless, and only the renderer * knows that. Off by default. */ renderEmpty?: boolean; /** * A select column edits through a list with a search box on top, as select2 does, instead of the browser's own * `