d3ro-voice/packages/core/src/popup-placement.ts

269 lines
10 KiB
TypeScript

// packages/core — 팝업/오버레이 배치 기하 정본.
//
// 두 가지를 담는다:
// 1) 좌표 공간 — UIA(사이드카)는 물리 픽셀, Electron screen API 는 DIP 를 쓴다. 둘을 같은
// `UiRect` 로 섞으면 125%/150% 배율에서 오버레이가 캐럿에서 멀리 떨어지거나 작업 영역
// 모서리에 붙는다. 그래서 공간을 타입으로 표기하고(PhysicalRect/DipRect), 변환은
// ScreenGeometryPort 한 곳(Electron 어댑터)에서만 한다 — core 는 좌표를 만든 OS API 를 모른다.
// 2) 배치 정책 — 캐럿/요소 앵커 배치(anchorFloatingPanel), 커서 기준 팝업 배치
// (placeNearCursor), 내용 높이에 맞춘 창 줄이기(fitAnchoredPanel).
//
// 순수 함수만 둔다 — Electron/Node 의존 금지.
// ============================================================
// 좌표 공간
// ============================================================
export interface UiRect {
x: number
y: number
width: number
height: number
}
export interface UiPoint {
x: number
y: number
}
export interface UiSize {
width: number
height: number
}
/** 타입 전용 표지 — 런타임 값은 없다. */
declare const COORDINATE_SPACE: unique symbol
/**
* 물리 픽셀 사각형 (UIA BoundingRectangle, GetWindowRect 등 DPI-aware 네이티브 API 가 주는 값).
*
* 표지는 선택적이다 — 네이티브 경계(UIA 페이로드)에서 들어온 평범한 UiRect 도 받아들이되,
* DipRect 는 받지 않는다(표지 값이 'dip' 이라 충돌한다).
*/
export type PhysicalRect = UiRect & { readonly [COORDINATE_SPACE]?: 'physical' }
/** Electron DIP 사각형 — 반드시 ScreenGeometryPort(또는 asDipRect)로만 만든다. */
export type DipRect = UiRect & { readonly [COORDINATE_SPACE]: 'dip' }
/** Electron DIP 점. */
export type DipPoint = UiPoint & { readonly [COORDINATE_SPACE]: 'dip' }
/** 이미 DIP 인 값(Electron screen API 결과)에 표지를 붙인다. 어댑터 경계에서만 쓴다. */
export function asDipRect(rect: UiRect): DipRect {
return { x: rect.x, y: rect.y, width: rect.width, height: rect.height } as DipRect
}
/** 이미 DIP 인 점(Electron screen API 결과)에 표지를 붙인다. 어댑터 경계에서만 쓴다. */
export function asDipPoint(point: UiPoint): DipPoint {
return { x: point.x, y: point.y } as DipPoint
}
/**
* 화면 기하 포트 — 좌표 공간 변환과 작업 영역 조회를 한 곳에 모은다 (DIP).
*
* Electron 어댑터는 win32 에서 screen.screenToDipRect 를, 그 밖에서는 항등 변환을 쓴다.
* 배치 정책은 이 포트만 보고 DIP 로만 계산한다.
*/
export interface ScreenGeometryPort {
/** 물리 픽셀 사각형 → DIP (배율이 다른 모니터에서도 그 모니터 기준으로 변환한다) */
toDip(rect: PhysicalRect): DipRect
/** 이 점에서 가장 가까운 모니터의 작업 영역 (DIP) */
workAreaNear(point: DipPoint): DipRect
/** 마우스 커서 위치 (DIP) */
cursor(): DipPoint
}
// ============================================================
// 캐럿/요소 앵커 배치
// ============================================================
/**
* 앵커 rect 가 케어렛(한 줄 위치)인지 포커스 요소 전체인지.
*
* 케어렛을 못 주는 제공자가 많아(Chrome, Windows Terminal 등 caret=-1) 그때는
* elementRect 로 폴백하는데, 두 경우는 배치 전략이 달라야 한다 — 케어렛은 "그
* 줄 아래" 에 붙이면 되지만, elementRect(멀티라인/큰 입력창 전체)는 그 규칙을
* 그대로 쓰면 텍스트와 멀리 떨어지거나 텍스트 위에 겹친다.
*/
export type AnchorKind = 'caret' | 'element' | null
function clamp(value: number, min: number, max: number): number {
if (max < min) return min
return Math.max(min, Math.min(value, max))
}
function fitsInWorkArea(x: number, y: number, size: UiSize, workArea: UiRect): boolean {
return (
x >= workArea.x &&
y >= workArea.y &&
x + size.width <= workArea.x + workArea.width &&
y + size.height <= workArea.y + workArea.height
)
}
function isUsableRect(rect: UiRect | null): rect is UiRect {
return rect !== null && rect.width >= 0 && rect.height >= 0
}
/**
* 오버레이 좌표 계산.
*
* 모든 인자는 같은 좌표 공간이어야 한다 — 공간을 타입으로 강제하려면
* anchorFloatingPanelInDips 를 쓴다.
*
* 케어렛 앵커(또는 앵커 없음 → 커서)는 앵커 아래에 붙이는 것이 기본 — IME 후보창과
* 같은 관례다. 아래 공간이 없으면 위로 뒤집는다.
* 요소 앵커(케어렛을 못 얻어 elementRect 로 폴백한 경우)는 요소 "바깥" 에 붙인다 —
* 아래/위/오른쪽/왼쪽 순으로 작업영역에 들어맞는 첫 방향을 쓴다.
* 마지막으로 항상 작업영역 안으로 클램프한다.
*/
export function anchorFloatingPanel(
anchor: UiRect | null,
anchorKind: AnchorKind,
cursor: UiPoint,
size: UiSize,
workArea: UiRect,
gap = 6
): UiPoint {
if (anchorKind === 'element' && isUsableRect(anchor)) {
return anchorOutsideElement(anchor, size, workArea, gap)
}
const rect: UiRect = isUsableRect(anchor) ? anchor : { x: cursor.x, y: cursor.y, width: 0, height: 0 }
const anchorBottom = rect.y + Math.max(rect.height, 0)
const desiredY = anchorBottom + gap
const fitsBelow = desiredY + size.height <= workArea.y + workArea.height
const above = rect.y - gap - size.height
const y = fitsBelow ? desiredY : above >= workArea.y ? above : desiredY
return {
x: clamp(rect.x, workArea.x, workArea.x + workArea.width - size.width),
y: clamp(y, workArea.y, workArea.y + workArea.height - size.height)
}
}
/** anchorFloatingPanel 의 DIP 전용 형태 — 물리 픽셀 값이 섞이면 컴파일되지 않는다. */
export function anchorFloatingPanelInDips(
anchor: DipRect | null,
anchorKind: AnchorKind,
cursor: DipPoint,
size: UiSize,
workArea: DipRect,
gap = 6
): DipPoint {
return asDipPoint(anchorFloatingPanel(anchor, anchorKind, cursor, size, workArea, gap))
}
/**
* 요소 앵커를 요소 "바깥" 에 배치한다.
*
* 케어렛을 못 얻어 elementRect(입력창 전체)로 폴백했을 때, 기존 "앵커 아래/위" 규칙을
* 그대로 쓰면 큰/여러 줄 요소에서는 텍스트와 멀리 떨어지거나 텍스트 위에 겹친다
* (실측: 2·3번째 생성에서 패널이 튐). 아래→위→오른쪽→왼쪽 순으로 작업영역에
* 맞는 첫 방향을 쓰고, 전부 안 맞으면 요소 안쪽 우하단 모서리로 물러난다.
*/
function anchorOutsideElement(element: UiRect, size: UiSize, workArea: UiRect, gap: number): UiPoint {
const candidates: UiPoint[] = [
{ x: element.x, y: element.y + element.height + gap }, // 아래
{ x: element.x, y: element.y - gap - size.height }, // 위
{ x: element.x + element.width + gap, y: element.y }, // 오른쪽
{ x: element.x - gap - size.width, y: element.y } // 왼쪽
]
for (const candidate of candidates) {
if (fitsInWorkArea(candidate.x, candidate.y, size, workArea)) return candidate
}
const fallback = {
x: element.x + element.width - size.width - gap,
y: element.y + element.height - size.height - gap
}
return {
x: clamp(fallback.x, workArea.x, workArea.x + workArea.width - size.width),
y: clamp(fallback.y, workArea.y, workArea.y + workArea.height - size.height)
}
}
/**
* 앵커 기준으로 배치한 패널 자리. 창 높이는 내용에 따라 줄어들 수 있다(fitAnchoredPanel).
*
* `grow` 는 내용이 늘 때 창이 자라는 방향이다 — 앵커 위로 뒤집혀 배치됐으면 아래쪽 모서리를
* 앵커 곁에 고정하고 위로 자란다.
*/
export interface AnchoredPanelPlacement {
x: number
y: number
width: number
/** 배치 계산에 쓴 최대 높이 */
maxHeight: number
grow: 'down' | 'up'
}
/**
* 물리 픽셀 앵커로 오버레이 자리를 잡는다 — 변환은 포트로 한 번만 한다.
*
* 모니터 선택도 변환된 DIP 점으로 한다 (물리 좌표로 고르면 배율이 다른 모니터가 여럿일 때
* 엉뚱한 모니터의 작업 영역을 고른다).
*/
export function placeAnchoredPanel(
port: ScreenGeometryPort,
anchor: PhysicalRect | null,
anchorKind: AnchorKind,
size: UiSize,
gap = 6
): AnchoredPanelPlacement {
const cursor = port.cursor()
const dipAnchor = isUsableRect(anchor) ? port.toDip(anchor) : null
const anchorPoint = dipAnchor
? asDipPoint({ x: dipAnchor.x, y: dipAnchor.y + dipAnchor.height })
: cursor
const workArea = port.workAreaNear(anchorPoint)
const position = anchorFloatingPanelInDips(dipAnchor, anchorKind, cursor, size, workArea, gap)
const referenceTop = dipAnchor ? dipAnchor.y : cursor.y
return {
x: position.x,
y: position.y,
width: size.width,
maxHeight: size.height,
grow: position.y + size.height <= referenceTop ? 'up' : 'down'
}
}
/**
* 배치된 패널 창을 실제 내용 높이로 줄인다.
*
* 투명 창이라도 창 영역은 클릭을 삼킨다 — 보이지 않는 여백이 캐럿 아래 줄의 클릭을 막지
* 않도록 창을 그려진 패널만큼만 둔다. 위로 뒤집힌 배치는 아래 모서리(앵커 쪽)를 고정한다.
*/
export function fitAnchoredPanel(placement: AnchoredPanelPlacement, contentHeight: number): UiRect {
const height = clamp(Math.round(contentHeight), 1, placement.maxHeight)
const y = placement.grow === 'up' ? placement.y + placement.maxHeight - height : placement.y
return { x: placement.x, y, width: placement.width, height }
}
// ============================================================
// 커서 기준 팝업 배치
// ============================================================
/**
* 커서 기준 팝업 배치 (녹음 팁 · 결과 · 기록 · 명령 팝업 공통).
*
* 커서 위 `gap` 에 가로 가운데로 두고, 위 공간이 없으면 커서 아래로 뒤집는다.
* 그다음 작업 영역 안으로 네 방향 모두 클램프한다 (아래로 뒤집힌 큰 팝업이 화면 밖으로
* 잘리지 않게). 음수 좌표(주 모니터 왼쪽/위쪽 모니터)도 그대로 다룬다.
*/
export function placeNearCursor(cursor: UiPoint, size: UiSize, workArea: UiRect, gap = 20): UiPoint {
const x = clamp(
cursor.x - Math.round(size.width / 2),
workArea.x,
workArea.x + workArea.width - size.width
)
let y = cursor.y - size.height - gap
if (y < workArea.y) y = cursor.y + gap
if (y + size.height > workArea.y + workArea.height) {
y = Math.max(workArea.y, workArea.y + workArea.height - size.height)
}
return { x, y }
}