Selection 과 Range — toString 너머

"Selection.toString 이 텍스트 줘. Range 가 rectangle, 둘러싼 context, anchor 와 focus node, selection 을 programmatic 으로 grow / shrink 할 능력 줘. Lesson 3 가 ClipDeck 이 highlight / screenshot / 결국 둘러싼-문단 capture 에 필요한 deep cut."

Selection vs Range

두 object, 관련 있지만 distinct:

• Selection — user 가 현재 document 에서 highlight 한 것. document 당 정확히 하나의 Selection, window.getSelection() 통해 access. 현대 browser 에서 0 또는 1 개 range 가짐 (multi-range 는 Firefox-only feature 였음).
• Range — DOM tree 의 두 지점 사이 span. User selection 과 독립; 원하는 만큼 만들고 highlight / scroll / 측정 / 스크롤에 사용 가능.

User 의 selection 이 window.getSelection().getRangeAt(0). 그 Range 에서 ClipDeck 의 clip metadata 에 중요한 모든 것 read 가능.

Range field

• range.startContainer / range.endContainer — selection 이 시작 / 끝나는 DOM node. 종종 Text node, 가끔 Element node.
• range.startOffset / range.endOffset — Text node 안 문자 offset, 또는 Element node 안 child index.
• range.commonAncestorContainer — 두 endpoint 다 포함하는 가장 낮은 DOM node. 둘러싼 문단이나 article 찾기에 유용.
• range.collapsed — start === end 일 때 true (길이 0 selection, cursor blink).
• range.toString() — selection.toString() 과 같은 plain text.
• range.cloneContents() — 선택 node 들이 deep-clone 된 DocumentFragment 반환. Clip 에 formatting (link / bold / code span) 보존에 사용.
• range.getBoundingClientRect() — selection 의 visible 위치 union rect. Screenshot 과 floating UI 배치용.
• range.getClientRects() — rect 배열, 줄 당 하나. Selection 이 여러 줄 걸칠 때 유용.

둘러싼 문단으로 grow

Default user selection 은 highlight 한 거 — 종종 mid-sentence 나 그냥 phrase. ClipDeck 이 'expand to paragraph' 를 tweak 으로 제공 가능:

function expandToParagraph(range) {
  const ancestor = range.commonAncestorContainer;
  const para = (ancestor.nodeType === 1 ? ancestor : ancestor.parentElement)
    .closest('p, li, blockquote, h1, h2, h3, h4, h5, h6, div');
  if (!para) return range;
  const newRange = document.createRange();
  newRange.selectNodeContents(para);
  return newRange;
}

'highlight 한 문장만 아닌 전체 문단 원함' 에 유용. Preview-and-confirm UI (Lesson 6) 에서 제공.

Clip 의 formatting 보존

ClipDeck v1 이 plain text 저장. Formatting 선택적으로 보존 원하면:

const fragment = range.cloneContents();
const tmp = document.createElement('div');
tmp.appendChild(fragment);
const htmlContent = tmp.innerHTML; // 저장 전 DOMPurify 통해 sanitize

text (toString 에서) 와 optional html field 둘 다 저장. Side panel 이 html 있으면 렌더; clipboard 는 항상 text 받음.

Multi-line selection bound

User 가 텍스트 여러 줄 highlight 하면, getBoundingClientRect() 가 다 감싸는 큰 rectangle 하나 반환 — 영역 screenshot 에 유용하지만 line-by-line UI 엔 부정확. getClientRects() 가 줄 당 rect 하나 반환, 정확한 highlight overlay 그릴 때 원하는 거:

const rects = Array.from(range.getClientRects());
rects.forEach((r) => drawHighlightOverlay(r));

Programmatic selection

Selection 을 programmatic 으로 설정 / 복원 (예: user 가 '이 clip 이 어디서 왔는지 보여 줘' click 후):

const selection = window.getSelection();
selection.removeAllRanges();
selection.addRange(rangeIRestored);

range.startContainer.scrollIntoView({ behavior: 'smooth', block: 'center' }) 와 결합, user 를 clip 의 원래 위치로 teleport 하고 다시 highlight 가능. ClipDeck v2 feature.