refactor(topics): 멀티 에이전트용 지식 재편 — _Common(공통 기본기) + Domain_* 구조
에이전트 8종(대화형/프로그래머 C·S/디자이너/설계자/기획자/QA/PD/PM)에게 [공통 기본 능력 + 롤별 Specialty] 2층으로 지식을 주입하기 위한 재분류. 문서 내용·포맷은 무수정, 폴더 이동만 (6,372개 문서 수 보존 확인). - Topic_Programming → Domain_Programming (내부 구조 보존) - Topic_Graphic → Domain_Design - Topic_Business → Domain_Product - Topic_General → Domain_General - _Common 신설: Math(구 Topic_Math_Specialty), Reasoning(구 General/From_Thinking & Reasoning), Reasoning_Creativity(구 General/From_창의성), Communication(Poetic_Blog_Writing + From_writing) - 타 도메인의 From_* 폴더는 유지 (출처 표기일 뿐, 이미 도메인에 맞게 분류된 문서) - 빈 폴더 정리 (memory/procedures) - 에이전트→폴더 매핑은 workspace의 .astra/agent-knowledge-map.json (9개 에이전트) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,175 @@
|
||||
---
|
||||
id: wiki-2026-0508-dom-요소-조작-및-타입-좁히기
|
||||
title: DOM 요소 조작 및 타입 좁히기
|
||||
category: 10_Wiki/Topics
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [DOM Manipulation, Type Narrowing, querySelector Typing]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.9
|
||||
verification_status: applied
|
||||
tags: [typescript, dom, web, type-narrowing]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
tech_stack:
|
||||
language: typescript
|
||||
framework: dom
|
||||
---
|
||||
|
||||
# DOM 요소 조작 및 타입 좁히기
|
||||
|
||||
## 매 한 줄
|
||||
> **"매 DOM API 의 untyped boundary 의 TypeScript narrowing 의 적용"**. 매 `querySelector` 의 default `Element | null` 위 의 generic + instanceof + assertion. 2026 의 strict null checks + satisfies + lib.dom.d.ts 의 mainstream type ergonomics.
|
||||
|
||||
## 매 핵심
|
||||
|
||||
### 매 Type narrowing tools
|
||||
- **Generic param**: `querySelector<HTMLInputElement>(...)` — runtime check 의 X, 매 assertion 만.
|
||||
- **`instanceof`**: 매 runtime check + narrow.
|
||||
- **Type guard function**: `function isInput(el): el is HTMLInputElement`.
|
||||
- **Discriminated property**: `el.tagName === 'INPUT'` (의 narrow X — manual cast 필요).
|
||||
|
||||
### 매 Null safety
|
||||
- `querySelector` 의 `null` 의 always 가능 — 매 explicit check.
|
||||
- `getElementById` 의 same — `HTMLElement | null`.
|
||||
- `as!` non-null assertion 의 last resort — 매 prefer guard.
|
||||
|
||||
### 매 응용
|
||||
1. Form value 추출 + validation.
|
||||
2. Dynamic widget hydration (서버 HTML 위 의 JS enhance).
|
||||
3. Custom element / Web Component 의 typed access.
|
||||
|
||||
## 💻 패턴
|
||||
|
||||
### querySelector with generic
|
||||
```typescript
|
||||
// 매 generic 의 assertion 만 — 매 null 의 still 가능
|
||||
const input = document.querySelector<HTMLInputElement>('#email');
|
||||
if (!input) throw new Error('email input missing');
|
||||
input.value; // 매 narrowed to HTMLInputElement
|
||||
```
|
||||
|
||||
### instanceof guard
|
||||
```typescript
|
||||
const el = document.getElementById('email');
|
||||
if (el instanceof HTMLInputElement) {
|
||||
el.value = 'test@example.com'; // 매 narrowed
|
||||
} else {
|
||||
throw new Error('not an input');
|
||||
}
|
||||
```
|
||||
|
||||
### Custom type guard
|
||||
```typescript
|
||||
function isInput(el: Element | null): el is HTMLInputElement {
|
||||
return el instanceof HTMLInputElement;
|
||||
}
|
||||
function getValue(selector: string): string {
|
||||
const el = document.querySelector(selector);
|
||||
if (!isInput(el)) throw new Error(`${selector} is not input`);
|
||||
return el.value;
|
||||
}
|
||||
```
|
||||
|
||||
### Helper: assertElement
|
||||
```typescript
|
||||
function $<T extends HTMLElement>(
|
||||
selector: string,
|
||||
ctor: new () => T = HTMLElement as new () => T,
|
||||
root: ParentNode = document,
|
||||
): T {
|
||||
const el = root.querySelector(selector);
|
||||
if (!el) throw new Error(`Missing: ${selector}`);
|
||||
if (!(el instanceof ctor)) throw new Error(`Wrong type: ${selector}`);
|
||||
return el as T;
|
||||
}
|
||||
const form = $('#login', HTMLFormElement);
|
||||
const email = $('input[name=email]', HTMLInputElement, form);
|
||||
```
|
||||
|
||||
### Form data — typed
|
||||
```typescript
|
||||
function getFormData<T extends Record<string, string>>(form: HTMLFormElement): T {
|
||||
const fd = new FormData(form);
|
||||
return Object.fromEntries(fd.entries()) as T;
|
||||
}
|
||||
type LoginForm = { email: string; password: string };
|
||||
const data = getFormData<LoginForm>(form);
|
||||
```
|
||||
|
||||
### Event delegation with narrowing
|
||||
```typescript
|
||||
document.addEventListener('click', (e) => {
|
||||
const target = e.target;
|
||||
if (!(target instanceof HTMLElement)) return;
|
||||
const btn = target.closest<HTMLButtonElement>('button[data-action]');
|
||||
if (!btn) return;
|
||||
switch (btn.dataset.action) {
|
||||
case 'save': return save();
|
||||
case 'delete': return remove(btn.dataset.id!);
|
||||
default: throw new Error(`Unknown action: ${btn.dataset.action}`);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Custom element typing
|
||||
```typescript
|
||||
class MyToggle extends HTMLElement {
|
||||
toggle() { this.toggleAttribute('open'); }
|
||||
}
|
||||
customElements.define('my-toggle', MyToggle);
|
||||
|
||||
declare global {
|
||||
interface HTMLElementTagNameMap { 'my-toggle': MyToggle; }
|
||||
}
|
||||
const t = document.querySelector('my-toggle'); // 매 typed as MyToggle | null
|
||||
t?.toggle();
|
||||
```
|
||||
|
||||
### satisfies for config (2026 idiom)
|
||||
```typescript
|
||||
const handlers = {
|
||||
'#save': (el: HTMLButtonElement) => el.addEventListener('click', save),
|
||||
'#email': (el: HTMLInputElement) => el.addEventListener('blur', validate),
|
||||
} satisfies Record<string, (el: HTMLElement) => void>;
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | Pattern |
|
||||
|---|---|
|
||||
| Single fetch + null OK | `querySelector<T>` + null check |
|
||||
| Strict invariant | `$()` helper with ctor |
|
||||
| Multiple element types | instanceof in switch |
|
||||
| Reusable check | Custom type guard |
|
||||
| Event handler | `target instanceof HTMLElement` |
|
||||
| Custom element | HTMLElementTagNameMap augment |
|
||||
|
||||
**기본값**: assertElement helper + instanceof + custom guards. `as` casts 의 last resort 만.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[TypeScript]] · [[DOM]]
|
||||
- 변형: [[Discriminated_Unions]]
|
||||
- 응용: [[DOM 요소 조작]] · [[Web_Components]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: helper 작성, type guard 추출, refactor untyped jQuery → typed TS.
|
||||
**언제 X**: 매 framework (React/Vue/Svelte) 안 — 매 framework type 의 사용.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **`as HTMLInputElement` everywhere**: runtime mismatch 의 silent.
|
||||
- **`!` non-null assertion 남발**: 매 null check 의 미루기 — runtime crash.
|
||||
- **`any` for events**: 매 `Event` subclass 의 사용.
|
||||
- **`getElementById` raw return 사용**: null check skip.
|
||||
- **innerHTML with user input**: 매 XSS — `textContent` / DOMPurify 의 사용.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (TypeScript handbook, lib.dom.d.ts, MDN DOM docs).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — generic/instanceof/guard/helper patterns for typed DOM |
|
||||
Reference in New Issue
Block a user