import './data-grid/data-grid.js'; import './data-list/data-list.js'; import './data-card/data-card.js'; import '@operato/list-state/ox-list-state.js'; import { LitElement, PropertyValues } from 'lit'; import { PagePreferenceProvider } from '@operato/p13n'; import { DataCard } from './data-card/data-card.js'; import { DataConsumer } from './data-consumer.js'; import { DataGrid } from './data-grid/data-grid.js'; import { DataList } from './data-list/data-list.js'; import { ColumnConfig, CountHandler, FetchHandler, FilterValue, GristConfig, GristData, GristRecord, GristSelectFunction, PaginationConfig, SortersConfig, ValidationReason } from './types.js'; import { RowEdits } from './edit-rebase.js'; /** * A custom element for rendering data in a grid, list, or card format. * * @element ox-grist */ export declare class DataGrist extends LitElement implements DataConsumer { static styles: import("lit").CSSResult[]; /** * The rendering mode of the component, which can be 'GRID', 'LIST', or 'CARD'. * Default is 'GRID'. * * @property {string} */ mode: 'GRID' | 'LIST' | 'CARD'; /** * The mode to draw in while the grist is narrower than `narrowWidth` - a report read as a table on a wide screen * and as cards on a phone (2026-11-06). The grist's own width decides, not the device: a narrow window on a * desktop and a page beside an open panel are narrow too. Unset, `mode` holds at every width. */ narrowMode?: 'GRID' | 'LIST' | 'CARD'; /** The width, in px, under which `narrowMode` is drawn. */ narrowWidth: number; private narrow; /** The mode the records are drawn in now: `narrowMode` while narrow, otherwise `mode`. */ get shownMode(): 'GRID' | 'LIST' | 'CARD'; /** * The grid's name, set by the caller as ``. * * role=grid sits on an inner wrapper, so an aria-label on the host does not reach it; the value * is taken here and forwarded to ox-grid. */ gridLabel?: string; /** * The configuration object for the data grist. * * @property {Object} */ config: any; /** * The data to be displayed in the data grist. * * @property {GristData} */ data: GristData; /** * An array of selected records in the data grist. * * @property {GristRecord[]} */ selectedRecords?: GristRecord[]; /** * Indicates whether explicit fetching of data is enabled. If true, data will be fetched * only when `fetch` method is called. Default is false. * * @property {boolean} */ explicitFetch: boolean; /** * The fetch handler function used to retrieve data from a remote source. * * @property {FetchHandler} */ /** * 검색 낱말이 서버까지 가는 길. * * `columns`(기본) — 격자가 **칸의 선언**(`filter: 'search'`)을 보고 필드마다 필터를 만든다. 화면이 * 서버의 `searchables` 를 손으로 베껴 칸에 적어야 하고, 하나도 안 적으면 낱말이 **조용히 버려진다**. * * `term` — 낱말을 그대로 실어 보내고(`fetchHandler` 의 `search`) 서버가 자기 `searchables` 로 푼다. * 화면에서 사본이 사라진다. 이 모드에서는 칸의 `filter: 'search'` 선언을 **읽지 않는다** — 그래야 * 같은 낱말이 두 번 걸리지 않는다. * * 기본을 `columns` 로 두는 것은 이 부품을 우리 저장소 밖에서도 쓰기 때문이다. 기본을 뒤집는 것과 * 옛 길을 지우는 것은 그 소비자들에게 알린 뒤의 별도 결정이다. */ searchMode: 'columns' | 'term'; /** `term` 모드의 낱말. 옛 모드에서는 낱말이 `filters` 안에 있으므로 이 자리는 비어 있다. */ private _searchTerm; fetchHandler?: FetchHandler; /** The counts beside the filter choices, read with each fetch's conditions (ADR-0190): see `CountHandler`. */ countHandler?: CountHandler; /** The last counts `countHandler` answered for the rows shown. */ counts?: Record>; /** * Additional fetch options to be passed to the fetch handler. * * @property {Object} */ fetchOptions: any; /** * An array of filter values to be applied to the data grist. * * @property {FilterValue[]} */ filters?: FilterValue[]; /** * An array of sorters to determine the order of records in the data grist. * * @property {SortersConfig} */ sorters?: SortersConfig; /** * The pagination configuration for the data grist. * * @property {PaginationConfig} */ pagination?: PaginationConfig; /** * Indicates whether URL parameters are sensitive to changes. If true, changes in URL * parameters will trigger data fetching. Default is undefined. * * @property {boolean} */ urlParamsSensitive?: boolean; personalConfigProvider: PagePreferenceProvider; personalConfig?: { columns?: Partial[]; [key: string]: any; }; _data: GristData; _config: GristConfig; private _showSpinner; /** * 한 번이라도 조회했는가. 빈 목록에 대한 안내를 낼지 이 값이 정한다. * * 조회 전에도 records 는 비어 있다. 그러나 그것은 「없다」가 아니라 「아직 모른다」이다. * 둘을 같게 두면 확인하지 않은 사실을 화면이 단정하게 된다. */ private _fetched; private _fetchError; head: HTMLElement; grist: DataGrid | DataList | DataCard; private wrap; private timeCapsule?; private snapshotTaker?; private dataProvider?; private pulltorefreshHandle?; /** How many reads `fetch` has started. A page refresh reads again only the grids its page did not read. */ get reads(): number; private readsStarted; private headroom?; private headResizeObserver?; private stopAddress?; private addressPath?; private addressContext; private addressRequest?; private addressError?; private draftBase?; get allowFetch(): boolean; /** Shell owns persistence; the grid only supplies its model and query identity. */ private reportDraft; get draftSnapshot(): { value: GristData; base: string | number | null; } | undefined; get draftRevision(): string; restoreUnsavedDraft(value: GristData, base: string | number | null): void; private queryIdentity; private pendingFetch?; /** * The configured filter defaults, or `undefined` while the configuration is not compiled. An address without * `filters` means these (§7 D7 of address-centralization-problem-2026-10-19). */ private configDefaults; /** Writes the defaults just applied into the address, so it says what the list shows. */ private reflectDefaults; private restoreAddress; private fetchParamsChangeEventHandler; firstUpdated(): Promise; connectedCallback(): Promise; disconnectedCallback(): void; private resetPullToRefresh; private setPullToRefresh; applyUpdatedConfiguration(): void; /** * 머리가 끝나는 자리까지 본문을 민다. 위에 있을 때는 margin, 스크롤 중일 때는 padding 이다. * * ── 머리 높이를 그대로 쓰면 안 된다 ───────────────────────────────────────── * 머리는 `position: absolute; top: 0` 이라 **host 의 padding 박스 맨 위**에 얹힌다. 즉 위쪽 * padding 을 덮고 있다. 그런데 본문(`ox-grid`)은 그 padding **뒤에서** 시작한다. * * 그래서 머리 높이만큼 밀면 그 padding 이 **머리 아래로 나타난다.** 머리의 위쪽 여백은 0 이고 * 아래쪽은 padding 만큼 넓어져, 머리 안의 내용(필터 칩 같은 것)이 위로 붙어 보인다. * * 실측(2026-09-03, 결재함 필터 줄): host padding-top 8px · 머리 34px · 밀린 값 34px * * 머리 151 ~ 185 * 본문 193 ← 159(padding 뒤) + 34. 머리와 본문 사이에 8px 이 생긴다 * 칩 위 4px · 아래 12px * * 덮은 만큼 빼면 머리 위아래가 **머리 자신의 여백**만 남아 저절로 대칭이 된다. 머리가 얼마나 * 복잡하든, padding 을 얼마로 두든 따라간다 — 여백의 양은 머리가 정하고, 이 함수는 자리만 맞춘다. */ private applyHeadOffset; private setHeadroom; render(): import("lit-html").TemplateResult<1>; private onKeydown; private _onDocumentKeydown; /** * Gets the current state of the component. The state includes information about the * dirty records and their changes. * * @getter * @public * @type {string} */ get state(): string; /** * Undoes the previous change in the component's data by restoring it to the previous state. * This method is part of the TimeCapsule feature, allowing users to revert changes. */ undo(): void; /** * Redoes the previously undone change in the component's data by restoring it to the next state. * This method is part of the TimeCapsule feature, allowing users to reapply changes. */ redo(): void; /** * Fetches data from a data source and updates the component's data. This method is used to retrieve * new data or refresh the existing data in the component. * * @method * @param {boolean} reset - If true, the method resets the scroll position to the top. */ fetch(reset?: boolean): Promise; updated(changes: PropertyValues): Promise; /** * Represents the compiled configuration of the component, which includes various settings and * column configurations. You can access this property to get information about how the component * is configured. * * @getter * @public * @type {GristConfig} */ get compiledConfig(): GristConfig; /** * Returns the dirty data in the component, which includes the records that have been added, * modified, or deleted but have not been committed to the main data yet. * * @getter * @public * @type {GristData} - An object representing the dirty data. */ get dirtyData(): GristData; flushEdits(): void; /** * Returns an array of GristRecord objects representing the records in the dirty state. These are * the records that have been added, modified, or deleted but have not been committed to the main * data yet. * * @getter * @public * @type {GristRecord[]} - An array of GristRecord objects representing the dirty records. */ get dirtyRecords(): GristRecord[]; /** * Exports a list of patches representing the changes in the dirty state of records. Each patch * contains information about whether a record was added, modified, or deleted, along with the * record's unique identifier and the changed field values. * * @param {Object} options - Export options that control the format of the patch list. * @param {string} options.flagName - The name of the flag field in the patch indicating the change type (default: 'patchFlag'). * @param {string} options.addedFlag - The flag value for added records (default: '+'). * @param {string} options.deletedFlag - The flag value for deleted records (default: '-'). * @param {string} options.modifiedFlag - The flag value for modified records (default: 'M'). * @param {string} options.idField - The name of the unique identifier field (default: 'id'). * @returns {Object[]} - An array of objects representing the patches. */ exportPatchList({ flagName, addedFlag, deletedFlag, modifiedFlag, idField }: { flagName?: string | undefined; addedFlag?: string | undefined; deletedFlag?: string | undefined; modifiedFlag?: string | undefined; idField?: string | undefined; }): any[]; /** * Exports the selected records or all records in the component, depending on the specified options. * You can use this method to export data from the component in various formats or for different purposes. * * One meaning per door (2026-11-22): a list's own export (the page's exportable) is the rows the list shows, whatever * is picked; the picked rows go out by the selection bar's 「선택 내보내기」, which asks for them. Before, no options * meant the picked rows if any, else all - so picking one row to act on made the list's export that one row. * * @param {Object} options - Export options that control the behavior of the export. * @param {boolean} options.ifSelectedOnly - If true, exports the selected records only (none when none is selected). * If false (the default), exports all records the component holds. * @param {boolean} options.includeHiddenField - If true, includes hidden fields in the exported data. * @returns {Object[]} - An array of objects representing the exported records. */ exportRecords({ ifSelectedOnly, includeHiddenField }?: { ifSelectedOnly?: boolean | undefined; includeHiddenField?: boolean | undefined; }): any[]; /** * Gets the currently selected records in the component. It returns an array of GristRecord objects * that are currently selected. You can access this getter to retrieve the selected records. * * @getter * @public * @type {GristRecord[]} */ get selected(): GristRecord[]; /** * Sets the currently selected records in the component. You can use this setter to programmatically * select specific records by providing an array of GristRecord objects to be selected. * * @setter * @public * @type {GristRecord[]} */ set selected(selected: GristRecord[]); /** * Selects records in the component based on the provided selector function. You can use this method * to programmatically select specific records in the component. * * @method * @param {GristSelectFunction} selector - A function that determines which records to select. * @param {boolean} reset - If true, clears the previous selection before applying the new one. * If false, adds to the existing selection. */ select(selector: GristSelectFunction, reset?: boolean): void; /** * Shows the loading spinner in the component's UI to indicate ongoing data loading or processing. * You can call this method to display the spinner when necessary. */ showSpinner(): void; /** * Hides the loading spinner in the component's UI to indicate that data loading or processing has completed. * You can call this method to hide the spinner when loading or processing is finished. */ hideSpinner(): void; /** * The fetch threw. A failed read is not an empty list: with no rows the note says "could not load" * and offers retry; with rows from before, a band says they are not a fresh result. */ fetchFailed(error: unknown): void; /** The fetch answered - whatever was said about a failure no longer holds. */ fetchSucceeded(): void; /** * Focuses on the component, making it the active element in the document. This method is useful * when you want to programmatically set focus to the component. */ focus(): void; /** * Commits the changes made in the dirty state to the component's data. This method updates the * component's data with the changes made in the dirty state and clears the dirty state. */ commit(): void; /** * Shows the headroom element in the component. The headroom element is typically used for * displaying additional information or controls at the top of the component. */ showHeadroom(): void; /** * Hides the headroom element in the component. This method hides the additional information * or controls displayed at the top of the component. */ hideHeadroom(): void; /** * Toggles the visibility of the headroom element in the component. If the headroom element is * currently visible, this method hides it. If it's hidden, this method shows it. */ toggleHeadroom(): void; /** * Forced internal data to be reflected on the screen * Data changing through a normal method is automatically reflected on the screen, so it is a method that does not need to be used in general. * Therefore, it will be deprecated. * @method */ refresh(): void; /** * Resets the component's data to its original state before any changes were made. * This method discards all unsaved changes and restores the data to its initial state. * * @method * @public */ /** * 목록이 비었을 때 무슨 말을 하나. **판단은 여기서 한 번만** 한다. * * 모드가 셋이고(GRID · CARD · LIST) 셋 다 자기 자리에 안내를 그린다. 판단까지 각자 하면 세 벌이 * 되고, 실제로 그랬다 — 셋이 같은 문장을 하드코딩하고 있었다. 여기서 정해 내려보낸다. * * ── 빈 목록은 두 가지 다른 사실을 말해야 한다 ────────────────────────────── * * 아직 아무것도 없다 이 표에 만들어진 것이 없다 * 찾는 것이 없다 찾거나 걸러 본 결과가 없다 * * 합치면 결함이 「고를 게 없다」로 보인다. 질의가 빈 배열을 내는데 화면이 「해당하는 것이 * 없습니다」라고 말하면 아무도 그것이 결함인 줄 모른다. * * 조건이 걸렸을 때는 **화면이 준 emptyNote 를 쓰지 않는다.** 그 말은 「아직 없다」를 위해 쓴 * 것이라 조건이 걸린 자리에서는 거짓이 된다. */ private noteWhenEmpty; reset(discard?: boolean): void; private traverseReset; private traverseExpanded; /** * Reads the list again and lays the given edits back on the rows read (`edit-rebase.ts`): after a save, the edits * made while it was out stay edits instead of being replaced by the list read; after a refused save, the person's * edits stay on the latest rows. The scroll stays where it is. Resolves to the edits whose row was not read - on * another page, filtered out, or deleted meanwhile - for the screen to keep. * * The edits kept in this browser (ADR-0098) were the ones before the save; they are settled before the read so the * read is not offered them back, and the edits laid back are kept again as they are laid. A read that fails changes * nothing on the screen: the edits stay there and are kept in the browser again, and the failure is thrown. */ fetchKeepingEdits(edits: readonly RowEdits[]): Promise; /** * Checks for dirty records in the component's data and marks them as dirty. * Dirty records are those that have unsaved changes. */ checkDirties(): void; /** * Clones the selected records in the component's data. It creates a copy of the selected records * and marks them as new (added) records. */ cloneSelectedRecords(): void; /** * Adds child nodes to selected records in the component's tree data. It allows users to add child nodes * to the selected parent records. */ addChildNodes(): void; /** * Adds sibling nodes to selected records in the component's tree data. It allows users to add sibling nodes * to the selected records. */ addSiblingNodes(): void; /** * Deletes the selected records in the component's data. It removes the selected records from the data, * optionally marking them as deleted. * * @method * @param {boolean} dirty - If true, the method marks the records as deleted. */ deleteSelectedRecords(dirty?: boolean): void; /** * Adds a new record to the data grid. The added record is marked as newly created * by setting the `__dirty__` flag to '+'. This flag indicates that the record * is in a "new" state and hasn't been committed to the main data yet. * * @param {GristRecord} [record] - An optional record to add. If no record is provided, * an empty record with the `__dirty__` flag set to '+' will be added. */ addRecord(record?: GristRecord): void; /** * Adds a new record to the top of the data grid. The added record is marked as newly created * by setting the `__dirty__` flag to '+'. This flag indicates that the record * is in a "new" state and hasn't been committed to the main data yet. * * This method is useful when you need to add new records at the top of the grid * without changing the default behavior of the appendable row. * * @param {GristRecord} [record] - An optional record to add. If no record is provided, * an empty record with the `__dirty__` flag set to '+' will be added. */ addRecordToTop(record?: GristRecord): void; /** * Starts a new row where it is seen: at the top, with the grid's draft values (`rows.newRecord`) under `values`, the * view scrolled to it and the first editable cell focused - the same path for every screen's 「행 추가」. Returns the * new record; it is marked new (`__dirty__: '+'`) and its dirty mark removes it again until it is saved. */ addNewRecord(values?: GristRecord): GristRecord; /** * Retrieves the search text used for filtering records. * * @property {string} */ get searchText(): string; /** * Sets the search text for filtering records. * * @property {string} */ set searchText(searchText: string); /** * Returns the current pagination limit. * @returns {number} The current pagination limit value */ getCurrentLimit(): number; /** * Checks the validity of dirty records. * @returns {Array<{record: GristRecord, invalidFields: Array<{field: string, reason: ValidationReason}>}>} List of invalid records and their corresponding invalid fields */ checkDirtyRecordsValidity(): { record: GristRecord; invalidFields: { field: string; reason: ValidationReason; }[]; }[]; }