@operato/scene-storage 10.0.0-beta.40 → 10.0.0-beta.42

package/dist/rack-grid.d.ts

@@ -1,80 +1,301 @@
-import { Component, ComponentNature, ContainerAbstract, Control, Properties, RealObject } from '@hatiolab/things-scene';
+import { Component, ComponentNature, Control, Properties, RealObject } from '@hatiolab/things-scene';
 import type { State } from '@hatiolab/things-scene';
 import * as THREE from 'three';
-/** RackGrid 컴포넌트 state */
+import { SlotTarget, type Alignment, type Heights, type PlacementArchetype, type SlotRecord, type SlottedHolder } from '@operato/scene-base';
+import RackGridCell from './rack-grid-cell.js';
+/** 한 (col, row) 위치의 메타데이터. 명시되지 않은 위치는 *룰의 기본값* 적용 (= location 없음). */
+export interface CellOverride {
+    /** Location 의 `{s}` 부분. unit 과 함께 명시되어야 location 부여됨. */
+    section?: string;
+    /** Location 의 `{u}` 부분. section 과 함께 명시되어야 location 부여됨. */
+    unit?: string;
+    /**
+     * 명시적 통로/공실 표시. 의미:
+     *   - location 미부여 (이 cell 로는 외부 location key 매칭 불가)
+     *   - increaseLocation 의 aisle row 로 인식 (skipNumbering 시 건너뜀)
+     * 자식 컴포넌트 종류는 무관 — Crane/AGV/forklift/비움 모두 OK.
+     */
+    isEmpty?: boolean;
+    /** 4-side border style (top/left/bottom/right) — modeling 시각 용. */
+    border?: any;
+    /** Grid merge — 시각 표현. */
+    merged?: boolean;
+    rowspan?: number;
+    colspan?: number;
+}
 export interface RackGridState extends State {
-    rows?: number;
+    /** Grid 가로 칸 수 (X 축). 각 칸 ≈ 1 column 의 StorageRack (또는 Crane 등). */
     columns?: number;
-    zone?: string;
+    /** Grid 세로 칸 수 (Z 축, depth). 통상 1, double-deep rack 등은 2. */
+    rows?: number;
+    /** 각 (col, row) 의 수직 shelf 수 (Y 축, level). 자식 StorageRack 의 levels 와 일치. */
     shelves?: number;
+    /**
+     * 첫 shelf 의 시작 높이 (mm, 3D Y 축, 바닥부터). 미명시 0 (바닥 = 첫 shelf).
+     * 양수 시 그만큼 위로 올라가 *stocker port / conveyor 같은 컴포넌트가 들어갈 빈 공간*
+     * 확보. Frame uprights 는 바닥 ~ 천장 그대로.
+     */
+    shelfBaseHeight?: number;
+    zone?: string;
+    /** 기본 `'{z}{s}-{u}-{sh}'`. placeholders: {z} {s} {u} {sh}. */
     locPattern?: string;
+    /** Section 숫자 자리수 (zero-pad). 기본 2. */
     sectionDigits?: number;
+    /** Unit 숫자 자리수 (zero-pad). 기본 2. */
     unitDigits?: number;
+    /** Shelf label CSV. 예: '1,2,3' / ',,,04'. 빈 자리는 1-based 인덱스 default. */
     shelfLocations?: string;
-    stockScale?: number;
+    /** Sparse cell metadata. key = posKey = `${col-1}-${row-1}` (0-based, 2 segments). */
+    cellOverrides?: {
+        [posKey: string]: CellOverride;
+    };
+    /**
+     * Stock records — `{ cellId: 'col-row-shelf', type, ... }`. cellId 가 RackGrid 의
+     * cell 위치 (3 segments) 와 매칭되는 record 만 InstancedMesh instance 로 렌더링.
+     * Plan A 정신 — sparse 데이터, 자식 컴포넌트 없이 batched 시각화.
+     */
+    data?: Array<{
+        cellId: string;
+        [key: string]: any;
+    }>;
+    /**
+     * Popup 컴포넌트 id — 클릭 시 그 popup 을 invoke (anchor = 클릭된 cell 의 SlotTarget).
+     * 미명시 시 click event (`rack-grid-cell-click`) 만 emit.
+     */
+    popupRef?: string;
     hideRackFrame?: boolean;
+    hideHorizontalFrame?: boolean;
     legendTarget?: string;
     hideEmptyStock?: boolean;
     widths?: number[];
     heights?: number[];
 }
-import { RackGridCell } from './rack-grid-cell.js';
-import type { StockMaterialProvider } from './stock.js';
-export default class RackGrid extends ContainerAbstract implements StockMaterialProvider {
-    get state(): RackGridState;
-    _focused_cell?: RackGridCell;
-    _stock_materials: THREE.Material[];
-    _default_material?: THREE.Material;
-    _empty_material?: THREE.Material;
+declare const RackGrid_base: any;
+export default class RackGrid extends RackGrid_base implements SlottedHolder {
+    state: RackGridState;
+    static placement: PlacementArchetype;
+    static align: Alignment;
+    static defaultDepth: (h: Heights) => number;
+    get nature(): ComponentNature;
+    get anchors(): never[];
+    /**
+     * Serialize 시 자식 RackGridCell 의 redundant 속성 제거:
+     *  - 좌표/변환 (left/top/width/height/zPos/rotation/scale/translate) — table layout 이
+     *    runtime 에 자동 결정. state 저장하면 layout 결과와 불일치 위험.
+     *  - **refid** — *동적 생성* 되는 자식이라 *부모의 refid 가 그대로 들어가면 충돌*
+     *    ("Refid Index replaced" 경고). 자식의 refid 는 *load 시 새로 자동 부여*. (외부
+     *    참조용 *id* 는 사용자 명시 시만 유지)
+     *
+     * 유지: cellId, section, unit, isEmpty, border, shelfLocations 등 *own 데이터*.
+     */
+    get hierarchy(): any;
+    /** Focusible — children (RackGridCell) 도 editor 의 selection 가능 (rack-table 동일). */
+    get focusible(): boolean;
+    /** Lifecycle — children 자동 생성. columns × rows 만큼 RackGridCell 자식. */
+    created(): void;
+    /** columns/rows 변경 시 children 재구성. rack-table.buildCells 패턴. */
+    onchange(after: Properties, _before: Properties): void;
+    /** state.data 변경 시 호출 (things-scene 의 onchange<PropName>). */
+    onchangeData(): void;
+    /** state.data 의 records — Plan A 의 stock 보관소. */
+    get records(): Array<{
+        cellId: string;
+        [key: string]: any;
+    }>;
     private _legendTarget?;
+    /**
+     * Legend 컴포넌트 lookup. 우선순위:
+     *   1) state.legendTarget id 명시
+     *   2) scene 전체 의 type='legend' 첫 번째 컴포넌트 (자동 발견)
+     */
     get legendTarget(): Component | undefined;
-    get hideEmptyStock(): boolean;
     private _onLegendChanged;
-    private _resetMaterials;
-    buildRealObject(): RealObject | undefined;
-    dispose(): void;
-    created(): void;
-    get focusible(): boolean;
-    get widths(): number[];
-    get heights(): number[];
-    buildCells(newrows: number, newcolumns: number, oldrows: number, oldcolumns: number): void;
-    get layout(): any;
-    get rows(): any;
-    setCellsStyle(cells: RackGridCell[], style: any, where: string): void;
-    getRowColumn(cell: RackGridCell): {
-        column: number;
-        row: number;
-    };
-    getCellsByRow(row: number): Component[];
-    getCellsByColumn(column: number): Component[];
-    deleteRows(cells: RackGridCell[]): void;
-    deleteColumns(cells: RackGridCell[]): void;
-    insertCellsAbove(cells: RackGridCell[]): false | undefined;
-    insertCellsBelow(cells: RackGridCell[]): false | undefined;
-    insertCellsLeft(cells: RackGridCell[]): false | undefined;
-    insertCellsRight(cells: RackGridCell[]): false | undefined;
-    distributeHorizontal(cells: RackGridCell[]): void;
-    distributeVertical(cells: RackGridCell[]): void;
-    increaseLocation(type: string, skipNumbering: boolean, startSection: number, startUnit: number): void;
-    get columns(): any;
-    get lefts(): Component[];
-    get centers(): Component[];
-    get rights(): Component[];
-    get tops(): Component[];
-    get middles(): Component[];
-    get bottoms(): Component[];
-    get all(): Component[];
-    get widths_sum(): any;
-    get heights_sum(): any;
-    get nature(): ComponentNature;
-    get controls(): Array<Control> | undefined;
-    onchange(after: Properties, before: Properties): void;
+    /**
+     * record 의 legend.field 값을 ranges 와 매칭해 색상 해석.
+     *   - `range.value === recordValue` (카테고리 일치)
+     *   - `range.min ≤ Number(v) < range.max` (수치 범위)
+     *   - 매칭 없으면 `defaultColor` 또는 undefined
+     */
     get eventMap(): {
         '(self)': {
-            '(descendant)': {
-                change: (after: Properties, before: Properties) => void;
+            '(self)': {
+                click: (mouseEvent: MouseEvent) => void;
             };
         };
     };
-    oncellchanged(after: Properties, before: Properties): void;
+    private _onViewClick;
+    /** state.popupRef Popup 컴포넌트 invoke. anchor = 클릭된 cell 의 SlotTarget. */
+    private _invokePopup;
+    /** raycast → 우리 RackGrid 의 어떤 mesh 가 closest hit 인지. */
+    private _raycastHit;
+    /** world point → cellId (col-row-shelf) 역산. */
+    private _cellIdFromWorldPoint;
+    resolveLegendColor(record: any): string | undefined;
+    /**
+     * 새 (rows × columns) 에 맞춰 children 재구성. rack-table.buildCells 정확 클론.
+     */
+    private _buildCells;
+    /** children 의 state.cellId 가 *순서 기반 bayKey* 와 일치하도록 동기화. */
+    private _syncChildCellIds;
+    /** Row 인덱스의 cell 들. rack-table-cell 의 rowCells 가 사용. */
+    getCellsByRow(row: number): Component[];
+    /** Column 인덱스의 cell 들. */
+    getCellsByColumn(column: number): Component[];
+    /** (col, row) 위치의 cell-component. */
+    cellAt(col: number, row?: number): RackGridCell | null;
+    /** bayKey 의 cell-component. */
+    cellAtBayKey(bayKey: string): RackGridCell | null;
+    /**
+     * (col, row) bay 가 *isEmpty* 인가. cell-component 의 state.isEmpty 가 source of
+     * truth, 없으면 cellOverrides[posKey].isEmpty fallback.
+     */
+    isBayEmpty(col: number, row?: number): boolean;
+    buildRealObject(): RealObject | undefined;
+    get layout(): any;
+    get widths(): number[];
+    get heights(): number[];
+    get widths_sum(): number;
+    get heights_sum(): number;
+    /** Column / Row 사이 드래그 핸들 — editor 의 widths/heights 가변 조절. */
+    get controls(): Array<Control> | undefined;
+    render(ctx: CanvasRenderingContext2D): void;
+    get columns(): number;
+    get rackRows(): number;
+    get shelves(): number;
+    /** posKey = `${col-1}-${row-1}` (0-based, 2 segments). 1-based input. */
+    posKeyOf(col: number, row?: number): string;
+    /** cellId = `${col-1}-${row-1}-${shelf-1}` (0-based, 3 segments). 1-based input. */
+    cellIdOf(col: number, row?: number, shelf?: number): string;
+    parseCellId(cellId: string): {
+        col: number;
+        row: number;
+        shelf: number;
+    } | null;
+    parsePosKey(posKey: string): {
+        col: number;
+        row: number;
+    } | null;
+    get cellOverrides(): {
+        [posKey: string]: CellOverride;
+    };
+    getCellOverride(posKey: string): CellOverride | undefined;
+    /**
+     * Parse `state.shelfLocations` 를 levels 길이 array 로. 빈 슬롯은 1-based index default.
+     *   '1,2,3'    → ['1', '2', '3', ...]
+     *   ',,,04'    → ['1', '2', '3', '04']
+     *   undefined  → ['1', '2', '3', '4', ...]
+     */
+    get shelfLabels(): string[];
+    /**
+     * cellId → location string. 우선순위:
+     *   1. cell-component (state.section/unit) — source of truth
+     *   2. cellOverrides[posKey] — 호환성 fallback
+     * section/unit 둘 다 있고 isEmpty=false 일 때만 부여. 미부여 시 null.
+     */
+    locationOf(cellId: string): string | null;
+    /** cell.state.shelfLocations 명시 시 그것, 아니면 RackGrid 의 shelfLabels. */
+    private _shelfLabelsFromCell;
+    /** location string → cellId. sparse 역인덱스 lookup. 없으면 null. */
+    cellIdOfLocation(location: string): string | null;
+    /** 모든 (override 명시된) cell 의 location 목록. inspection 용. */
+    get allLocations(): Array<{
+        cellId: string;
+        location: string;
+    }>;
+    private _locationIndexCache?;
+    private get _locationIndex();
+    /** 룰 / cellOverrides 변경 시 호출. things-scene 의 onchange* 가 자동 호출. */
+    invalidateLocationIndex(): void;
+    onchangeCellOverrides(): void;
+    onchangeLocPattern(): void;
+    onchangeShelfLocations(): void;
+    onchangeZone(): void;
+    onchangeSectionDigits(): void;
+    onchangeUnitDigits(): void;
+    onchangeShelves(): void;
+    /**
+     * (col, row) 위치의 자식 StorageRack. 자식이 StorageRack 이 아닌 경우 (Crane, AGV 등)
+     * 는 null — Carrier 보관은 StorageRack 만.
+     *
+     * 자식의 grid 위치 식별: 자식의 state.column / state.row (1-based) 명시. RackGrid 가
+     * 자식 추가 시 자동 할당 또는 사용자가 명시.
+     */
+    private _childRackAt;
+    hasCarrierAt(slotId: string): boolean;
+    obtainCarrier(slotIdOrLocation: string): Component | null;
+    canReceiveAt(slotIdOrLocation: string, carrier?: Component): boolean;
+    receiveAt(slotIdOrLocation: string, carrier: Component, options?: any): Promise<void>;
+    recordFromCarrier(carrier: Component, slotId: string): SlotRecord;
+    /**
+     * Slot 의 attach object3d — Stock InstancedMesh 의 instance 와 *같은 world 위치* 에
+     * 위치한 invisible Object3D. popup tether / Carriable.applyHolderAttachPoint 가 이
+     * object3d 의 matrixWorld 를 사용. lazy 생성 + cache.
+     */
+    private _attachAnchorByCell;
+    getSlotAttachObject3d(slotId: string): THREE.Object3D | undefined;
+    getSlotSize(slotId: string): {
+        width: number;
+        height: number;
+        depth: number;
+    } | undefined;
+    cellCenter2D(slotId: string): {
+        x: number;
+        y: number;
+    } | null;
+    slotTargetAt(slotIdOrLocation: string): SlotTarget;
+    /**
+     * 외부 입력 → 내부 cellId 변환:
+     *   - "N-N-N" (3 segments, 모두 숫자) → cellId 그대로 (dual-accept)
+     *   - 그 외 → location 으로 간주, locationIndex lookup
+     */
+    private _resolveToCellId;
+    private _isCellIdFormat;
+    /**
+     * 한 위치의 cellOverride 를 갱신 (merge). 기존 필드는 유지, 새 필드만 덮어씀.
+     * `partial` 의 필드가 *undefined* 면 *그 필드 삭제* (override 키에서 제거).
+     */
+    setCellOverride(posKey: string, partial: Partial<CellOverride>): void;
+    /** 한 위치의 override 전체 삭제. */
+    clearCellOverride(posKey: string): void;
+    /**
+     * 여러 위치의 isEmpty 일괄 토글. cell-component 있으면 cell.set(), 없으면 cellOverrides.
+     */
+    setIsEmpty(posKeys: string[], isEmpty: boolean): void;
+    /**
+     * 여러 위치의 border 스타일 일괄 설정. `where` ('top'|'left'|'bottom'|'right'|'all').
+     *   - style = null → 해당 side 삭제
+     *   - where = 'all' → 4면 모두 동일 style
+     */
+    setBorder(posKeys: string[], style: any, where?: 'all' | 'top' | 'left' | 'bottom' | 'right'): void;
+    /**
+     * 자동 채번 — 선택된 cell 들에 section/unit 자동 부여.
+     *
+     * @param posKeys     채번 대상 (선택 영역). 빈 array 면 *전체 grid*.
+     * @param direction   순회 방향:
+     *                      'cw'              — 한 row 내 col 증가 → 다음 row 는 반대 방향 (boustrophedon)
+     *                      'ccw'             — 반대 방향
+     *                      'zigzag'          — col 우선 증가 (cw 의 90° 회전)
+     *                      'zigzag-reverse'  — 반대
+     * @param skipNumbering  true 면 isEmpty cell 건너뜀 (단위 번호 안 증가).
+     * @param startSection   첫 section 번호 (default 1)
+     * @param startUnit      첫 unit 번호 (default 1)
+     *
+     * Aisle row (모든 cell isEmpty) 는 section 경계로 인식 — section 번호가 다음 row 에서 +1.
+     *
+     * setState 한 번 (cellOverrides 일괄 갱신) → location 역인덱스 1회 무효화.
+     */
+    increaseLocation(posKeys: string[], direction?: 'cw' | 'ccw' | 'zigzag' | 'zigzag-reverse', skipNumbering?: boolean, startSection?: number, startUnit?: number): void;
+    /**
+     * 모든 grid 위치 (전체 columns × rows) 의 posKey 목록.
+     */
+    private _allPosKeys;
+    /**
+     * Row 의 col 순회 순서 결정. boustrophedon (S 자형) 패턴 지원.
+     *   cw   : 짝수 row 는 좌→우, 홀수 row 는 우→좌
+     *   ccw  : 짝수 row 는 우→좌, 홀수 row 는 좌→우
+     *   zigzag         : 모든 row 좌→우 (단순)
+     *   zigzag-reverse : 모든 row 우→좌
+     */
+    private _orderCols;
 }
+export {};