open-grid 1.0.8 → 1.1.0

package/dist/types/core/OpenGrid.d.ts

@@ -1,8 +1,12 @@
 import { EventEmitter } from './EventEmitter.js';
 import { FilterSelectConfig } from './FilterSelect.js';
 import { MergeCell } from './MergeEngine.js';
+import { FlatRowModel } from './FlatRowModel.js';
+import { ChartInstance } from './ChartManager.js';
+import { ChartConfig } from './chart/types.js';
 import { OverrideLayer } from './OverrideKernel.js';
-import { GridOptions, OpenGridInstance, ColumnDef, SortItem, FilterItem, ExportOptions, Position, TriggerHandler, TriggerEvent, OverrideApi, OverrideCallOptions } from './types.js';
+import { FormulaErrorCode } from './formula/types.js';
+import { GridOptions, OpenGridInstance, ColumnDef, SortItem, FilterItem, ExportOptions, Position, TriggerHandler, TriggerEvent, OverrideApi, OverrideCallOptions, CellRange, RangeStats } from './types.js';
 export declare class OpenGrid<T extends Record<string, any> = any> extends EventEmitter implements OpenGridInstance<T> {
     private _container;
     private _options;
@@ -36,6 +40,22 @@ export declare class OpenGrid<T extends Record<string, any> = any> extends Event
     private _findMgr;
     private _grpMgr;
     private _cellEvt;
+    /** F1: 범위 선택 + 채우기 핸들 배선 관리자(11_design_F1_v2.md). */
+    private _rangeMgr;
+    /** F2: 마스터/디테일 배선(11_design_F2_v2.md). 헤드리스 코어(core/detail/*)를 소비. */
+    private _detailMgr;
+    /** F4: 그리드 데이터 통합 차트 오케스트레이터(11_design_F4_v2.md). 헤드리스 chart/* 소비. */
+    private _chartMgr;
+    /** Phase 0(C0.3): flat/visual index ↔ data 리졸버. 어떤 기능도 켜지지 않아도 항상 존재. */
+    private _flatModel;
+    /** F3: 셀 수식 헤드리스 오케스트레이터(core/formula/* 소비, 재구현 아님). 항상 존재(헤드리스라 유휴 비용 0). */
+    private _recalc;
+    /** F3(C2): writeCell 단건 쓰기가 쌓아두는 dirty seed. endBatch/즉시 flush 시 onValuesChanged 1회로 소비. */
+    private _formulaDirtySeeds;
+    /** reentrant 카운터. 0 초과면 배치 중(writeCell 이 render/dataChange 를 지연). */
+    private _batchDepth;
+    /** 배치 구간 중 실제 쓰기가 1건이라도 있었는지(빈 배치는 endBatch 에서 아무 것도 안 함). */
+    private _batchDirty;
     private _ovk;
     /** 공개 override API (호출가능 + .strategy). 생성자 말미에 부착. */
     override: OverrideApi<T>;
@@ -88,6 +108,8 @@ export declare class OpenGrid<T extends Record<string, any> = any> extends Event
      */
     private _syncHeaderLayout;
     private _doRender;
+    /** F2(§4.5/§6.1): masterDetail.enabled 아니면 undefined(GridRenderer 는 기존 경로 그대로). */
+    private _buildDetailRenderContext;
     private _handleGroupToggle;
     private _visRange;
     private _visCount;
@@ -157,6 +179,73 @@ export declare class OpenGrid<T extends Record<string, any> = any> extends Event
     getDisplayValue(rowIndex: number, field: string): string;
     writeCell(rowIndex: number, field: string, value: any): void;
     getRowAt(rowIndex: number): T;
+    /** flat/visual index ↔ data 리졸버(C0.3). F1/F3/F4 는 이 모델만 경유해야 한다. */
+    getFlatRowModel(): FlatRowModel;
+    /**
+     * 배치 쓰기 시작(C2.1). 이후 writeCell 호출들은 render/dataChange 를 지연·coalesce 한다.
+     * 중첩 호출은 카운팅(reentrant) — 가장 바깥 endBatch 에서만 실제로 flush 된다.
+     */
+    beginBatch(): void;
+    /**
+     * 배치 종료(C2.1). 카운터가 0 이 되는 시점에 한해 배치 중 발생한 쓰기가 있으면
+     * _doRender 1회 + dataChange 1회를 발생시킨다(둘 다 0회 또는 1회 — 폭주 차단).
+     * 향후 F3 재계산 훅 지점: 아래 flush 블록 안에 RecalcCoordinator.onValuesChanged(dirtyKeys)
+     * 1회 호출을 끼워 넣는다(Phase 0 시점엔 미구현 — 계약 §C2.1 참조).
+     */
+    endBatch(): void;
+    /** writeCell 이 적립한 dirty seed 를 1회 onValuesChanged 로 소비하고 formulaRecalc 를 emit. */
+    private _flushFormulaRecalc;
+    /**
+     * RecalcCoordinator 호출 결과를 표면화: formulaError 는 onFormulaError 콜백에서 이미 개별
+     * emit 되므로 여기선 배치당 1회 formulaRecalc 만 emit(C2.2 개명, `recalc`→`formulaRecalc`).
+     * Spike-A §8 교훈: 폐포가 큰 재계산은 large 플래그로 표시(가이드 문서화/모니터링용).
+     */
+    private _afterRecalc;
+    private _handleFormulaError;
+    private _formulaErrorMessageKo;
+    /** F3 accessor(C0/C0.5/C1) — FlatRowModel + ColumnLayout.visibleLeaves + DataLayer(rowId 기반)만 본다. */
+    private _buildFormulaAccessor;
+    setCellFormula(rowIndex: number, field: string, formula: string): void;
+    private _setCellFormulaByRowId;
+    getCellFormula(rowIndex: number, field: string): string | null;
+    hasCellFormula(rowIndex: number, field: string): boolean;
+    clearCellFormula(rowIndex: number, field: string): void;
+    getCellError(rowIndex: number, field: string): FormulaErrorCode | null;
+    getDependents(rowIndex: number, field: string): Array<{
+        rowIndex: number;
+        field: string;
+    }>;
+    getPrecedents(rowIndex: number, field: string): Array<{
+        rowIndex: number;
+        field: string;
+    }>;
+    recalculate(): void;
+    recalculateCell(rowIndex: number, field: string): void;
+    /** C3(F1 fill 전용): srcRowId/srcField 수식의 상대축만 dRow/dCol 오프셋한 새 수식 원문. */
+    offsetFormula(srcRowId: string, srcField: string, dRow: number, dCol: number): string;
+    /** F3 렌더 배선(§4.4/C7, §7.4/§7.5/§7.6) — 셀 수식 메타(없으면 null). */
+    private _getFormulaMeta;
+    /**
+     * beginBatch+루프+endBatch 래퍼(C2.1). patches 의 rowIndex 는 flat index — 대상이
+     * FlatRowModel.resolveFlatRow 로 해소해 kind!=='data' (group/tree/detail 의사행)이면
+     * 쓰기 전에 skip 한다(C0.3 쓰기 안전, filler 에 writeCell 절대 금지).
+     * 건너뛴 셀 수를 반환하고, 1건이라도 있으면 announce + 'writeCellsSkip' 이벤트로 표면화한다.
+     */
+    writeCells(patches: Array<{
+        rowIndex: number;
+        field: string;
+        value: any;
+    }>): number;
+    getRangeSelection(): CellRange[];
+    getActiveRange(): CellRange | null;
+    setRangeSelection(range: CellRange | CellRange[]): void;
+    clearRangeSelection(): void;
+    getRangeValues(): any[][];
+    getRangeStats(): RangeStats | null;
+    fillRange(source: CellRange, target: CellRange, mode?: 'copy' | 'series'): void;
+    createChart(config: ChartConfig): ChartInstance;
+    getCharts(): ChartInstance[];
+    destroyCharts(): void;
     getChanges(): {
         added: T[];
         edited: T[];
@@ -213,6 +302,8 @@ export declare class OpenGrid<T extends Record<string, any> = any> extends Event
     resetOrder(): void;
     setFilter(field: string, filterItems: FilterItem[]): void;
     resetFilter(field?: string): void;
+    /** F3-R13/MCCONNELL-03(P0): 정렬/필터 후 범위-보유(hasRangeRef) 수식 전부 dirty(§3.5). */
+    private _recalcRangeBearingFormulas;
     getFilterState(): Record<string, FilterItem[]>;
     restoreFilter(state: Record<string, FilterItem[]>): void;
     private _applyFilters;
@@ -234,6 +325,23 @@ export declare class OpenGrid<T extends Record<string, any> = any> extends Event
     expandNodes(ids: any | any[], open?: boolean): void;
     expandAllNodes(): void;
     collapseAllNodes(): void;
+    expandRow(rowRef: number | {
+        id: string;
+    }): void;
+    collapseRow(rowRef: number | {
+        id: string;
+    }): void;
+    toggleRow(rowRef: number | {
+        id: string;
+    }): void;
+    isRowExpanded(rowRef: number | {
+        id: string;
+    }): boolean;
+    collapseAllDetails(): void;
+    getDetailInstance<D = any>(rowRef: number | {
+        id: string;
+    }): D | undefined;
+    resyncPanelWidths(): void;
     addTreeRow(_item: Partial<T>, _pid: string, _pos?: Position): void;
     exportExcel(options?: ExportOptions | string): void;
     exportCsv(options?: ExportOptions | string): void;

package/dist/types/core/RangeSelectionManager.d.ts

@@ -0,0 +1,95 @@
+import { DataLayer } from './DataLayer.js';
+import { ColumnLayout } from './ColumnLayout.js';
+import { GridRenderer } from './GridRenderer.js';
+import { CellEditManager } from './CellEditManager.js';
+import { FlatRowModel } from './FlatRowModel.js';
+import { GridOptions } from './types.js';
+import { RangeStats } from './range/RangeQuery.js';
+import { CellRange, Direction, FillMode, FillPreview } from './range/types.js';
+export interface RangeSelectionDeps<T extends Record<string, any>> {
+    getOptions: () => Required<GridOptions<T>>;
+    getData: () => DataLayer<T>;
+    getColLayout: () => ColumnLayout<T>;
+    getFlatModel: () => FlatRowModel;
+    getRenderer: () => GridRenderer | null;
+    getEditMgr: () => CellEditManager<T>;
+    setFocusCell: (ri: number, ci: number) => void;
+    writeCells: (patches: Array<{
+        rowIndex: number;
+        field: string;
+        value: any;
+    }>) => number;
+    getDisplayValue: (ri: number, field: string) => string;
+    emit: (event: string, ...args: any[]) => void;
+    doRender: () => void;
+    announce: (msg: string) => void;
+    hasCellFormula?: (rowId: string, field: string) => boolean;
+    offsetFormula?: (rowId: string, field: string, dRow: number, dCol: number) => string;
+    setCellFormulaByRowId?: (rowId: string, field: string, formula: string) => void;
+}
+export declare class RangeSelectionManager<T extends Record<string, any> = any> {
+    private _d;
+    private _model;
+    private _isDragging;
+    private _fillDragSource;
+    private _fillDragStart;
+    private _fillPreview;
+    private _handlePointerId;
+    private _autoScrollRAF;
+    private _autoScrollVX;
+    private _autoScrollVY;
+    private _overlayEl;
+    private _borderEl;
+    private _previewEl;
+    private _handleEl;
+    private _mountedWrap;
+    constructor(deps: RangeSelectionDeps<T>);
+    isEnabled(): boolean;
+    private _rangeOpts;
+    private _editorActive;
+    hasSelection(): boolean;
+    getRangeSelection(): CellRange[];
+    getActiveRange(): CellRange | null;
+    getFillPreview(): FillPreview | null;
+    getRangeValues(): any[][];
+    getRangeStats(): RangeStats | null;
+    private _queryCtx;
+    handleCellMouseDown(ri: number, ci: number, e: MouseEvent): void;
+    handleCellMouseMove(ri: number, ci: number, e: MouseEvent): void;
+    handleCellMouseUp(_ri: number, _ci: number, _e: MouseEvent): void;
+    handleClick(ri: number, ci: number, shiftKey: boolean): void;
+    extendFocus(dir: Direction): void;
+    clear(): void;
+    clearRangeSelection(): void;
+    setRangeSelection(range: CellRange | CellRange[]): void;
+    /** applySort/applyFilter 직후 호출(C0.5, §2.5) — 선택은 rowId 집합 기준으로 재투영(해제 아님). */
+    reproject(): void;
+    private _afterModelChange;
+    private _announceSelection;
+    ctrlFill(axis: 'down' | 'right'): void;
+    /** 공개 API(§6.2): source→target 채우기. axis 는 두 rect 의 상대 위치로 추론한다. */
+    fillRange(source: CellRange, target: CellRange, mode?: FillMode): void;
+    private _isEditable;
+    private _commitFill;
+    /** KeyboardManager._copyToClipboard 가 소비. 범위 없으면 null(호출측이 기존 경로로 폴백). */
+    copyText(): string | null;
+    /** KeyboardManager._pasteFromClipboard 가 소비. true = 처리함(배치 경유), false = 범위 없음(폴백). */
+    pasteText(text: string): boolean;
+    private _maybeAutoscroll;
+    private _scrollSpeed;
+    private _runAutoscroll;
+    private _stopAutoscroll;
+    /** bodyWrap 자식으로 오버레이 1회 생성(renderBody 파괴 회피, CON-3 해법). */
+    mount(bodyWrap: HTMLElement): void;
+    /** _doRender 매 호출 뒤 실행(M-6 통합점) — 코너 셀 실측 → 연속 테두리/핸들/프리뷰 갱신(QA-2, CON-4). */
+    repaint(): void;
+    private _hideOverlay;
+    /** OpenGrid._doRender 가 renderBody extraOpts 로 전달(M-6). */
+    getOverlayExtraOpts(): {
+        _rangeRects: CellRange[];
+    };
+    private _resolveCellAtPoint;
+    private _onHandlePointerDown;
+    private _onHandlePointerMove;
+    private _onHandlePointerUp;
+}

package/dist/types/core/SortFilterManager.d.ts

@@ -14,6 +14,8 @@ export interface SortFilterDeps<T extends Record<string, any>> {
     doRender: () => void;
     announce: (msg: string) => void;
     emit: (event: string, ...args: any[]) => void;
+    /** C0.5/§2.5: 정렬/필터 후 F1 범위 선택을 rowId 집합 기준으로 재투영(해제 아님). */
+    onReproject?: () => void;
 }
 export declare class SortFilterManager<T extends Record<string, any> = any> {
     private _sortList;

package/dist/types/core/chart/CanvasAdapter.d.ts

@@ -0,0 +1,52 @@
+import { ChartAdapter, ChartDataModel, ChartPoint, ChartRenderSpec } from './types.js';
+import { PointGeom } from './hittest.js';
+export declare class CanvasAdapter implements ChartAdapter {
+    readonly id = "builtin-canvas";
+    private _host;
+    private _canvas;
+    private _a11yTable;
+    private _legend;
+    private _tooltip;
+    private _live;
+    private _spec;
+    private _model;
+    private _w;
+    private _h;
+    private _geoms;
+    private _hidden;
+    private _cursor;
+    private _onPoint;
+    init(host: HTMLElement, spec: ChartRenderSpec): Promise<void>;
+    render(model: ChartDataModel, spec: ChartRenderSpec): void;
+    resize(width: number, height: number): void;
+    onPointClick(cb: (p: ChartPoint) => void): void;
+    destroy(): void;
+    /** 렌더된 포인트 기하(hittest.spec/adapter.spec 검증용). */
+    getGeometry(): readonly PointGeom[];
+    private _renderA11yTable;
+    /**
+     * diff 렌더: series 수/이름이 이전과 동일하면 기존 버튼 DOM 을 재사용해 aria-pressed·색·
+     * 라벨만 갱신한다(포커스 보존). series 구성 자체가 바뀔 때만 통째로 재생성하되, 재생성 직전
+     * activeElement 가 범례 내부 버튼이면 재생성 후 동일 index 버튼에 포커스를 복원한다
+     * (코드리뷰 MAJOR: 라이브 재렌더가 범례 innerHTML='' 로 키보드 포커스를 유실하던 문제).
+     */
+    private _renderLegend;
+    /** 범례 버튼의 aria-pressed/색상 스와치/라벨(패턴 병기)을 현재 상태로 갱신(DOM 은 그대로). */
+    private _updateLegendButton;
+    private _styles;
+    private _plotRect;
+    private _valueExtent;
+    private _computeGeometry;
+    private _paint;
+    private _localXY;
+    private _onMouseMove;
+    private _onMouseLeave;
+    private _onClick;
+    private _onKeyDown;
+    private _cursorPoint;
+    private _announceCursor;
+    private _pointOf;
+    private _emitPoint;
+    private _showTooltip;
+    private _hideTooltip;
+}

package/dist/types/core/chart/DataExtractor.d.ts

@@ -0,0 +1,49 @@
+import { CellRange } from '../types.js';
+import { ChartAggregate, ChartDataModel, ChartSeriesSpec, ChartSource } from './types.js';
+import { ChartNumberFormat } from './a11y.js';
+/** ColumnLayout.visibleLeaves 의 최소 투영(field/header/type 만 필요, C0.4). */
+export interface ChartColumnRef {
+    field: string;
+    header?: string | undefined;
+    type?: string | undefined;
+}
+export interface ChartExtractDeps {
+    /** getData() 전체(display 순서) — kind='all'|'columns' */
+    getAllRows(): Array<Record<string, any>>;
+    /** getSelections() — kind='selection' */
+    getSelectedRows(): Array<Record<string, any>>;
+    /** getChecked() 의 row 부분 — kind='checked' */
+    getCheckedRows(): Array<Record<string, any>>;
+    /** ColumnLayout.visibleLeaves 투영(숨김 제외, C0.4) */
+    getVisibleColumns(): ChartColumnRef[];
+    /**
+     * kind='range' 전용: 스냅샷/현재 range 에 대응하는 행 배열(FlatRowModel 로 이미
+     * pseudo-row 를 제외한 상태, C0.3). 부재 시 range 소스는 selection 으로 강등한다(§7).
+     */
+    getRangeRows?: ((range: CellRange) => Array<Record<string, any>>) | undefined;
+    /** kind='range' 전용: range.startCol..endCol 에 대응하는 visibleLeaves 서브셋(C0.4). */
+    getRangeColumns?: ((range: CellRange) => ChartColumnRef[]) | undefined;
+    /** range 생략 시 초기값 취득(C4). 없거나 null 이면 selection 으로 강등(§7). */
+    getActiveRange?: (() => CellRange | null) | undefined;
+}
+export interface ChartExtractConfig {
+    /** 축 카테고리 컬럼 override(FR-2). 미지정 시 §2.2 자동 추론. */
+    category?: string | undefined;
+    /** 시리즈 컬럼 override(FR-2). 'columns' 소스는 필수(source.series 로도 지정 가능). */
+    series?: Array<string | ChartSeriesSpec> | undefined;
+    /** 동일 category 중복 시 축약(FR-3). 미지정 시 중복 category 를 그대로 유지(비집계). */
+    aggregate?: ChartAggregate | undefined;
+    title?: string | undefined;
+    numberFormat?: ChartNumberFormat | undefined;
+}
+/** 소스 강등 없이 실제로 사용된 소스 종류(§7 fallback 반영, 배지 판단에 쓰라고 반환). */
+export interface ChartExtractResult {
+    model: ChartDataModel;
+    /** true 면 kind='range' 요청이 selection 으로 강등됐다(F1 부재/range 미해소, §7 HANMS-04). */
+    rangeFallback: boolean;
+}
+/**
+ * 소스(§2.1)로부터 `ChartDataModel`을 산출한다(FR-1: 4소스 → 동형 모델).
+ * `meta.a11yTable`은 항상 채운다(§B 하드 게이트, "생성비용 0" 미러).
+ */
+export declare function extractChartData(source: ChartSource, deps: ChartExtractDeps, config?: ChartExtractConfig): ChartExtractResult;

package/dist/types/core/chart/a11y.d.ts

@@ -0,0 +1,21 @@
+import { ChartDataModel, A11yTableModel } from './types.js';
+export type ChartNumberFormat = (v: number, ctx: {
+    axis: 'x' | 'y' | 'tooltip' | 'legend';
+    field?: string;
+}) => string;
+export interface BuildA11yTableOptions {
+    title?: string | undefined;
+    numberFormat?: ChartNumberFormat | undefined;
+}
+/**
+ * `ChartDataModel`(categories/series 부분)을 시각숨김 `<table>` 미러 데이터로 변환한다(§B.1).
+ * - colHeaders: ['category', ...series names]
+ * - rows: [category, v1, v2, ...] (locale 포맷 문자열, 결측=빈 문자열)
+ * - caption: 요약 — 카테고리 수·시리즈명 나열(스크린리더가 표 진입 전 듣는 개요).
+ */
+export declare function buildA11yTable(model: Pick<ChartDataModel, 'categories' | 'series'>, opts?: BuildA11yTableOptions): A11yTableModel;
+/**
+ * `<canvas role="img" aria-label="...">` 에 쓸 요약 문자열(§B.1).
+ * "{title}: {category}별 {series} — {요약}" 형태. 상세 값은 형제 `<table>`(aria-describedby)로.
+ */
+export declare function chartAriaLabel(model: Pick<ChartDataModel, 'categories' | 'series'>, title?: string): string;

package/dist/types/core/chart/downsample.d.ts

@@ -0,0 +1,25 @@
+import { ChartDataModel, ChartType } from './types.js';
+import { ChartNumberFormat } from './a11y.js';
+/**
+ * LTTB 코어 — x(=category index 0..n-1)·y(대표값) 에서 threshold 개 인덱스를 고른다.
+ * 항상 첫/마지막을 포함한다. threshold>=n 이면 전 인덱스 반환.
+ */
+export declare function lttbIndices(y: Array<number | null>, threshold: number): number[];
+export interface DownsampleResult {
+    model: ChartDataModel;
+    /** true 면 축약이 일어났다(배지 §C). */
+    sampled: boolean;
+}
+export interface DownsampleOptions {
+    title?: string | undefined;
+    numberFormat?: ChartNumberFormat | undefined;
+}
+/**
+ * `ChartDataModel`을 maxPoints 이하로 축약한다(§8.2). categories/series 를 함께 줄여
+ * 정합을 유지하고, meta.sampled/sampledFrom/sampledTo 를 채운다(배지 §C). a11yTable 은
+ * 축약된 데이터로 재생성해 모델 자기정합을 유지한다(§B.4: 셀 수 == categories×(series+1)).
+ *
+ * - line/area: 공유 인덱스 LTTB + 각 series 엔벨로프(argmin/argmax) 강제 포함 → 극값 정확 보존.
+ * - 그 외(bar): 인접 category 를 균등 버킷으로 묶어 대표(첫 category 라벨) + 값 합산.
+ */
+export declare function downsampleModel(model: ChartDataModel, maxPoints: number, type: ChartType, opts?: DownsampleOptions): DownsampleResult;

package/dist/types/core/chart/hittest.d.ts

@@ -0,0 +1,20 @@
+import { ChartType } from './types.js';
+/** 렌더된 데이터포인트 하나의 기하. bar=사각형(x,y,w,h), line/marker=중심(cx,cy). */
+export interface PointGeom {
+    seriesIndex: number;
+    categoryIndex: number;
+    /** 사각형 좌상단(bar). line 은 마커 bbox 좌상단으로도 채울 수 있다. */
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** 중심 좌표(line 마커 최근접용, bar 도 중심 계산해 채운다). */
+    cx: number;
+    cy: number;
+}
+/**
+ * 포인터 좌표(px,py)에 해당하는 데이터포인트 기하를 찾는다(§8.3).
+ * - bar/bar-*: 사각형 contains(미스면 null → 툴팁 숨김).
+ * - line/area: 최근접 x → 최근접 y(항상 하나 반환, 미스 개념 없음).
+ */
+export declare function hitTest(geoms: readonly PointGeom[], px: number, py: number, type: ChartType): PointGeom | null;

package/dist/types/core/chart/palette.d.ts

@@ -0,0 +1,56 @@
+import { ChartSeries } from './types.js';
+/** Okabe-Ito 8색(색약 안전 세트) — 배치 순서는 인접 대비≥3:1이 되도록 §D에 맞춰 조정. */
+export declare const OKABE_ITO: readonly string[];
+/** 색 외 구분(§D): series 인덱스 순환 배정. bar=텍스처, line=대시+마커에 대응. */
+export declare const PATTERN_CYCLE: ReadonlyArray<NonNullable<ChartSeries['pattern']>>;
+export interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/** '#rgb'/'#rrggbb'/'rgb(a)()' → RGB(0-255). 실패 시 null. */
+export declare function parseColor(input: string): Rgb | null;
+/** 'rgba(r, g, b, 1)' 정규화 문자열 — UR-2 theme_bind 비교용(§1). */
+export declare function normalizeColor(input: string): string | null;
+/** WCAG relative luminance (0..1). */
+export declare function relativeLuminance(c: Rgb): number;
+/** WCAG 대비비 (1..21). 파싱 실패 색은 1로 취급. */
+export declare function contrastRatio(a: string, b: string): number;
+export type Dichromacy = 'deuteranopia' | 'protanopia';
+/** 색약 변환 시뮬레이션 — RGB in/out(0-255). */
+export declare function simulateDichromacy(c: Rgb, kind: Dichromacy): Rgb;
+/** 단순 유클리드 RGB 거리(ΔE 근사, 0..441). palette.spec 임계 비교용. */
+export declare function colorDistance(a: Rgb, b: Rgb): number;
+/**
+ * 인접 대비를 **최대화**하도록 팔레트를 그리디 재배치한다(§D "미달 시 팔레트 재배치").
+ * 첫 색에서 시작해 매번 직전 색과 대비가 가장 큰 색을 이어붙인다(O(n²), 결정론적).
+ *
+ * ⚠️ 정직한 한계(설계 갱신 필요): 8색 색약안전 팔레트는 **어떤 순열로도** 인접 luminance
+ * 대비 ≥3:1 을 전부 만족할 수 없다(수학적 상한 ≈1.52, 브루트포스 확인). WCAG 3:1 은 본디
+ * 전경-배경(텍스트/UI) 기준이지 인접 카테고리 기준이 아니다. 색약 구별의 실보증은 (1) 색약
+ * 시뮬 ΔE 분리(§simulateDichromacy, 인접 최소 ≈78)와 (2) 색 외 중복 부호화(패턴/대시/마커,
+ * PATTERN_CYCLE)에 있다. 본 함수는 대비를 "가능한 만큼" 키우는 best-effort 재배치다.
+ */
+export declare function orderByAdjacentContrast(colors: readonly string[]): string[];
+/** 인접 색쌍의 최소 대비비(테스트/재배치 판정용). */
+export declare function minAdjacentContrast(colors: readonly string[]): number;
+/** 인접 색쌍의 색약 시뮬 ΔE 최소값(deuteranopia/protanopia 중 나쁜 쪽). 색약 구별 실보증. */
+export declare function minAdjacentDichromacyDeltaE(colors: readonly string[]): number;
+export interface ResolvedSeriesStyle {
+    color: string;
+    pattern: NonNullable<ChartSeries['pattern']>;
+}
+/**
+ * series 별 색/패턴을 결정한다(§D).
+ * - series.color 명시가 최우선.
+ * - primary(테마 --og-primary)가 주어지면 첫 팔레트 색으로 유도하되, 다음 색과의
+ *   대비가 3:1 미달이면 안전 팔레트 원본을 그대로 쓴다(§D "fallback으로만").
+ * - 패턴은 인덱스 순환(유일성은 series≤4에서 보장, 초과 시 색+패턴 조합으로 구분).
+ */
+export declare function resolveSeriesStyles(series: ReadonlyArray<{
+    color?: string | undefined;
+    pattern?: ChartSeries['pattern'] | undefined;
+}>, opts?: {
+    palette?: readonly string[] | undefined;
+    primary?: string | undefined;
+}): ResolvedSeriesStyle[];

package/dist/types/core/chart/scales.d.ts

@@ -0,0 +1,24 @@
+/**
+ * F4 — nice-number 축 눈금 스케일(순수 함수, 헤드리스). §8.1(자동검증 대상 수학).
+ *
+ * 표준 Heckbert "Nice Numbers for Graph Labels" 알고리즘. 목표 tick 수(default 6)에 맞춰
+ * step 을 1/2/5×10^n 중에서 선택하고, [min,max] 를 그 step 배수로 확장한다.
+ *
+ * 한계(정직 명시): 이 알고리즘은 min=0 류의 "원점 기준" 범위에서는 매우 안정적으로
+ * tick 5~6개를 낸다(설계서 §8.1 문서화 예시 [0,97]→6 tick 포함). min≠0 인 임의 구간에서는
+ * step 후보가 {1,2,5,10} 로 성기어(coarse) tick 수가 4개나 7개로 튈 수 있다 — 표준 알고리즘의
+ * 알려진 한계이며, 본 구현은 문서화된 대표 입력(§8.1)에 대해서만 5~6 불변식을 보장한다.
+ */
+export interface NiceScale {
+    min: number;
+    max: number;
+    step: number;
+    ticks: number[];
+}
+/** range 를 1/2/5×10^n 중 하나로 반올림한다(round=true: 가장 가까운 값, false: 올림 쪽 느슨한 값). */
+export declare function niceNum(range: number, round: boolean): number;
+/**
+ * [dataMin,dataMax] → nice range/step/tick 배열(§8.1). maxTicks 는 목표 tick 수(default 6).
+ * dataMin===dataMax(degenerate) 이면 값 주변으로 인위 확장한다.
+ */
+export declare function niceScale(dataMin: number, dataMax: number, maxTicks?: number): NiceScale;