open-grid 1.0.8 → 1.1.1

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/RenderController.d.ts

@@ -0,0 +1,65 @@
+import { GridRenderer, DetailRenderContext } from './GridRenderer.js';
+import { VirtualScroll } from './VirtualScroll.js';
+import { Pagination } from './Pagination.js';
+import { ColumnLayout } from './ColumnLayout.js';
+import { DataLayer } from './DataLayer.js';
+import { FlatRowModel } from './FlatRowModel.js';
+import { MergeEngine } from './MergeEngine.js';
+import { SortFilterManager } from './SortFilterManager.js';
+import { RowManager } from './RowManager.js';
+import { CellEditManager } from './CellEditManager.js';
+import { GroupTreeManager } from './GroupTreeManager.js';
+import { DetailManager } from './DetailManager.js';
+import { RangeSelectionManager } from './RangeSelectionManager.js';
+import { GridOptions } from './types.js';
+/**
+ * R5(§3.1 C4, §6-R5): 렌더 루프의 유일 진입점. `OpenGrid` God object 에서
+ * `_onResize`/`_recalcWidths`/`_renderHeader`/`_syncHeaderLayout`/`_doRender`/`_visRange`
+ * (+ 전용 헬퍼 `_visCount`/`_paginationHeight`)를 **동작 불변**으로 옮긴 것.
+ *
+ * 스트랭글러 원칙(A2): 협력자(GridRenderer/VirtualScroll/Pagination 등)는 여전히
+ * `OpenGrid._mount` 가 생성·소유하며, 여기에는 `*Deps` 클로저 역전 패턴으로 **주입**만 된다.
+ * 값(컬럼폭·옵션 등)은 늦은-null / 재할당(worksheet 전환 시 colLayout 교체)을 견디도록
+ * 전부 getter 클로저로 읽는다. `fallbackViewportHeight` 클램프 시맨틱과 RenderFrame 구성은
+ * 원본과 1:1 동일하다(회귀 0).
+ */
+export interface RenderControllerDeps<T extends Record<string, any> = any> {
+    getContainer: () => HTMLElement;
+    getOptions: () => Required<GridOptions<T>>;
+    getRenderer: () => GridRenderer | null;
+    getVs: () => VirtualScroll | null;
+    getPagination: () => Pagination | null;
+    getData: () => DataLayer<T>;
+    getColLayout: () => ColumnLayout<T>;
+    getFlatModel: () => FlatRowModel;
+    getMergeEngine: () => MergeEngine;
+    getColWidths: () => number[];
+    setColWidths: (widths: number[]) => void;
+    getUserWidths: () => Map<string, number>;
+    getSfMgr: () => SortFilterManager<T>;
+    getRowMgr: () => RowManager<T>;
+    getEditMgr: () => CellEditManager<T>;
+    getGrpMgr: () => GroupTreeManager<T>;
+    getDetailMgr: () => DetailManager<T>;
+    getRangeMgr: () => RangeSelectionManager<T>;
+    buildDetailRenderContext: () => DetailRenderContext | undefined;
+    renderFooterEl: () => void;
+}
+export declare class RenderController<T extends Record<string, any> = any> {
+    private _deps;
+    private _autoHeightWarned;
+    constructor(deps: RenderControllerDeps<T>);
+    private _paginationHeight;
+    onResize(): void;
+    recalcWidths(totalWidth: number): void;
+    renderHeader(): void;
+    /**
+     * 렌더된 헤더의 실제 높이를 측정해 본문(bodyWrap) 높이와 뷰포트 높이에 반영한다.
+     * 줄바꿈이 없는 헤더는 측정 높이가 headerHeight 이하라 기존 고정 동작과 동일하다.
+     * (public: OpenGrid 가 `_syncHeaderLayout` 위임으로 노출 — 특성화 테스트가 직접 호출한다.)
+     */
+    syncHeaderLayout(): void;
+    doRender(startIndex: number, endIndex: number): void;
+    visRange(): [number, number];
+    private _visCount;
+}

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

@@ -0,0 +1,53 @@
+import { SkinTokenDelta } from './types.js';
+export interface SkinDefineResult {
+    /** 실제 등록된(가드레일 클램프가 반영된) 델타. */
+    readonly delta: SkinTokenDelta;
+    /** 접근성 가드레일이 조정한 토큰 경고(있으면 콘솔에도 출력). */
+    readonly warnings: string[];
+}
+/** 스킨 델타가 색 리터럴을 담고 있는지 검사하고, 위반 시 던진다(FORM-only, Rule 2). */
+export declare function assertFormOnly(id: string, delta: SkinTokenDelta): void;
+/**
+ * HANMS 접근성 가드레일(불변식) 적용 — 정의 시점 클램프(§6.4, HANMS P0-4).
+ *  - focus-width < 2px → 2px 로 클램프(가시 포커스 비협상).
+ *  - focus-style: none → solid.
+ * 반환은 조정된 델타 + 경고 목록(silent override 아님 — 무엇을 클램프했는지 알린다).
+ */
+export declare function applyGuardrails(id: string, delta: SkinTokenDelta): SkinDefineResult;
+/**
+ * 프로세스 전역 스킨 등록소. defineSkin(사용자) 는 검증+가드레일+`<style>` 주입,
+ * registerBuiltin(내장) 은 검증+가드레일만(CSS 는 skins.css 정적 번들 소유).
+ */
+export declare class SkinRegistry {
+    private _skins;
+    private _styleEl;
+    /** 내장 스킨 등록(주입 없음 — CSS 는 skins.css 가 전달). 검증/가드레일은 동일 적용. */
+    registerBuiltin(id: string, delta: SkinTokenDelta): void;
+    /**
+     * 사용자 스킨 등록. FORM-only 검증 + 가드레일 클램프 후 런타임 `<style>` 로
+     * `.og-container[data-og-skin="id"]` 블록을 주입(브라우저 환경). 반환은 조정 결과.
+     */
+    define(id: string, delta: SkinTokenDelta): SkinDefineResult;
+    has(id: string): boolean;
+    get(id: string): SkinTokenDelta | undefined;
+    /** 등록된 모든 스킨 id(내장 + 사용자). */
+    list(): string[];
+    /** 런타임 `<style>` 주입(테스트/SSR 등 document 없으면 no-op). 같은 태그를 누적 사용. */
+    private _inject;
+}
+/** Sharp/Gothic — 엔터프라이즈 고밀도·각짐(§3.1). HANMS: APPROVE-WITH-GUARDRAIL(G-S1). */
+export declare const SKIN_SHARP: SkinTokenDelta;
+/** Rounded — 소비자 SaaS 소프트(§3.2). HANMS: APPROVE. */
+export declare const SKIN_ROUNDED: SkinTokenDelta;
+/** Stitch — 핸드크래프트(§3.3). HANMS: APPROVE-WITH-GUARDRAIL(G-ST1~3). 색(리넨/자수)은 theme 축. */
+export declare const SKIN_STITCH: SkinTokenDelta;
+/** Flat/Minimal — 플랫 2.0(§3.5). HANMS: APPROVE-WITH-GUARDRAIL(G-F1: 플로팅 표면 1px 보더). */
+export declare const SKIN_FLAT: SkinTokenDelta;
+/** High-Contrast — 접근성 우선·레퍼런스(§3.6). HANMS: APPROVE(안전 폴백). */
+export declare const SKIN_HIGH_CONTRAST: SkinTokenDelta;
+/** Material/Elevated — Neumorph 대체(HANMS §3): 중간 반경 + 정직한 그림자 엘리베이션. APPROVE. */
+export declare const SKIN_MATERIAL: SkinTokenDelta;
+/** 내장 스킨 카탈로그(HANMS 확정 6종, Neumorph 제외). id → 델타. */
+export declare const BUILTIN_SKINS: ReadonlyArray<readonly [string, SkinTokenDelta]>;
+/** 프로세스 전역 기본 레지스트리 — 내장 스킨을 부트스트랩 등록(주입 없음, CSS=skins.css). */
+export declare const skinRegistry: SkinRegistry;

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;

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

@@ -0,0 +1,181 @@
+import { CellRange } from '../types.js';
+/**
+ * Phase1 MVP = 'bar'|'line'. 나머지는 Phase2/3 예약(타입만 선언, 미구현).
+ *
+ * ⚠️ 'bar-stacked': 공개 타입으로 노출되어 있으나 내장(builtin-canvas) 렌더러는 현재 스택
+ * 누적을 구현하지 않는다 — 지정해도 'bar-grouped'와 동일하게 그룹형(side-by-side)으로
+ * 폴백 렌더된다(CanvasAdapter._computeGeometry). 하위호환을 위해 타입 자체는 유지한다.
+ */
+export type ChartType = 'bar' | 'line' | 'area' | 'pie' | 'doughnut' | 'bar-stacked' | 'bar-grouped';
+export interface ChartSeriesSpec {
+    field: string;
+    name?: string;
+    color?: string;
+    pattern?: ChartSeries['pattern'];
+    type?: 'bar' | 'line' | 'area';
+}
+export type ChartSource = {
+    kind: 'range';
+    range?: CellRange;
+} | {
+    kind: 'selection';
+} | {
+    kind: 'checked';
+} | {
+    kind: 'all';
+} | {
+    kind: 'columns';
+    category?: string;
+    series: Array<string | ChartSeriesSpec>;
+};
+export type ChartAggregateOp = 'sum' | 'avg' | 'count' | 'min' | 'max';
+export type ChartAggregate = ChartAggregateOp | ((values: number[], category: string) => number);
+export interface A11yTableModel {
+    /** aria-label 요약 캡션 */
+    caption: string;
+    /** ['category', ...series names] */
+    colHeaders: string[];
+    /** [category, v1, v2, ...] — locale 포맷 문자열 */
+    rows: string[][];
+}
+export interface ChartSeries {
+    /** 범례 라벨(기본값 = 원본 컬럼 header/field) */
+    name: string;
+    /** categories 와 동일 순서로 정렬. 결측=null */
+    data: Array<number | null>;
+    color?: string;
+    /** 색 외 구분(HANMS-19) */
+    pattern?: 'solid' | 'hatch' | 'dot' | 'cross';
+}
+export interface ChartDataModelMeta {
+    sourceKind: ChartSource['kind'];
+    /** 원본 포인트(행) 수 */
+    total: number;
+    /** LTTB 다운샘플 또는 category 집계로 축약됐는가 → 배지(§C) */
+    sampled: boolean;
+    sampledFrom?: number;
+    sampledTo?: number;
+    aggregatedOp?: 'sum' | 'avg' | 'count' | 'min' | 'max' | 'custom';
+    pieReducedToFirst?: boolean;
+    negativesAbsInPie?: boolean;
+    /** SR 폴백 — extractor 가 렌더러와 무관하게 항상 채운다(§B 하드 게이트) */
+    a11yTable: A11yTableModel;
+}
+export interface ChartDataModel {
+    categories: string[];
+    series: ChartSeries[];
+    meta: ChartDataModelMeta;
+}
+export interface ChartTheme {
+    primary: string;
+    border: string;
+    text: string;
+    bg: string;
+    gridLine: string;
+    fontFamily: string;
+    fontSize: number;
+    palette: string[];
+}
+export interface ChartRenderSpec {
+    type: ChartType;
+    title?: string;
+    legend?: boolean | {
+        position: 'top' | 'bottom' | 'left' | 'right';
+    };
+    tooltip?: boolean;
+    axis?: {
+        xLabel?: string;
+        yLabel?: string;
+        yMin?: number;
+        yMax?: number;
+        stacked?: boolean;
+    };
+    palette?: string[];
+    theme: ChartTheme;
+    numberFormat?: (v: number, ctx: {
+        axis: 'x' | 'y' | 'tooltip' | 'legend';
+        field?: string;
+    }) => string;
+    a11y: A11yTableModel;
+}
+export interface ChartPoint {
+    seriesName: string;
+    category: string;
+    value: number | null;
+    index: number;
+    rowId?: string;
+}
+export interface ChartAdapter {
+    readonly id: string;
+    init(host: HTMLElement, spec: ChartRenderSpec): Promise<void>;
+    render(model: ChartDataModel, spec: ChartRenderSpec): void;
+    resize(width: number, height: number): void;
+    toBlob?(mime?: string): Promise<Blob | null>;
+    onPointClick?(cb: (p: ChartPoint) => void): void;
+    destroy(): void;
+}
+/** createChart 반환 핸들(§6). 구현은 ChartManager. */
+export interface ChartInstance {
+    readonly id: string;
+    update(patch?: Partial<ChartConfig>): void;
+    /**
+     * 모델을 재추출하고 렌더 스펙(테마 포함)을 재스냅샷해 재렌더한다(§5.3). 그리드는 테마 변경
+     * 이벤트를 발행하지 않으므로(`setTheme`/`setThemeVar`는 CSS 만 갱신) 다크모드 토글처럼 데이터
+     * 변화 없는 순수 테마 전환 후에는, 열려 있는 각 차트에 대해 이 메서드를 호출해야 새 테마
+     * (색·글꼴·팔레트)가 재적용된다. `update()`/`setType()`도 내부적으로 동일 경로를 탄다.
+     */
+    refresh(): void;
+    setType(type: ChartType): void;
+    destroy(): void;
+    toBlob(mime?: string): Promise<Blob | null>;
+    getModel(): ChartDataModel;
+    on(ev: 'chartRender' | 'chartPointClick', cb: (...a: any[]) => void): void;
+}
+/** GridOptions.chart 로 중첩되는 전역 옵션(C5.1, 최상위 flat 키 금지). */
+export interface ChartGlobalOptions {
+    enabled?: boolean;
+    defaultEngine?: 'builtin' | 'chartjs' | 'echarts';
+    defaultType?: ChartType;
+    placement?: 'docked' | 'modal' | 'inline' | 'floating';
+    maxPoints?: number;
+    debounceMs?: number;
+    palette?: string[];
+    numberFormat?: (v: number, ctx: {
+        axis: 'x' | 'y' | 'tooltip' | 'legend';
+        field?: string;
+    }) => string;
+    onChartCreate?: (i: ChartInstance) => void;
+    onChartRender?: (e: {
+        id: string;
+        model: ChartDataModel;
+    }) => void;
+    onChartPointClick?: (e: {
+        id: string;
+        point: ChartPoint;
+    }) => void;
+    onChartDestroy?: (e: {
+        id: string;
+    }) => void;
+}
+export interface ChartConfig {
+    source: ChartSource;
+    type: ChartType;
+    engine?: 'builtin' | 'chartjs' | 'echarts' | ChartAdapter;
+    placement?: 'docked' | 'modal' | 'inline' | 'floating';
+    mount?: HTMLElement;
+    category?: string;
+    series?: Array<string | ChartSeriesSpec>;
+    aggregate?: ChartAggregate;
+    maxPoints?: number;
+    live?: boolean;
+    title?: string;
+    legend?: ChartRenderSpec['legend'];
+    tooltip?: boolean;
+    axis?: ChartRenderSpec['axis'];
+    palette?: string[];
+    numberFormat?: ChartRenderSpec['numberFormat'];
+    size?: {
+        width: number;
+        height: number;
+    };
+}