mdsquare 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ordidxzero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,219 @@
-# Temporary Holding Version
+# mdsquare
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CodeMirror 6 기반의 하이브리드(라이브 미리보기) 마크다운 에디터입니다.
+원문은 마크다운 그대로 두고, 커서가 없는 곳은 결과처럼 보여 줍니다. (HyperMD / Obsidian 방식)
+
+- 강조, 제목, 목록·작업 목록, 링크·이미지, 각주, 해시태그·멘션
+- 인용과 콜아웃(`> [!note]`), 코드 블록(구문 강조, VS Code 테마, 복사 버튼)
+- 수식(KaTeX), TikZ 그림(선택)
+- GFM 표: 칸 편집, 행/열 손잡이 메뉴(삽입·복제·삭제·이동·정렬), 행/열/칸 색
+
+## 설치
+
+```sh
+npm install mdsquare
+```
+
+번들러(Vite, webpack, Rollup 등)를 쓰는 ESM 환경을 기준으로 합니다.
+
+## 사용
+
+```ts
+import MDSquareEditor from "mdsquare";
+import "mdsquare/style.css"; // 수식(KaTeX) 글꼴과 스타일
+
+const editor = new MDSquareEditor({
+  parent: document.getElementById("editor")!,
+  value: "# 안녕하세요\n\n**mdsquare**로 마크다운을 편집합니다.",
+  onChange: (markdown) => console.log(markdown),
+});
+
+editor.getValue(); // 지금 문서 (마크다운)
+editor.setValue("# 새 문서");
+```
+
+### 파일 열기
+
+파일을 읽고 저장하는 것은 앱이 맡고, 에디터에는 글자만 넘깁니다. 다른 파일로 바꿀 때는 `open`을 씁니다.
+(`setValue`로 바꾸면 Ctrl+Z로 이전 파일 내용이 돌아오고, `onChange`가 불려 방금 연 파일을 바로 저장하게 됩니다)
+
+```ts
+async function openFile(file: File) {
+  editor.open(await file.text());
+}
+```
+
+에디터 높이는 CSS로 정합니다. (기본: 내용만큼 늘어남)
+
+```css
+#editor .cm-editor { height: 480px; }
+```
+
+### 옵션
+
+| 옵션 | 기본값 | 설명 |
+|---|---|---|
+| `parent` | – | 에디터를 넣을 요소. 없으면 `editor.dom`을 직접 붙입니다 |
+| `value` | `""` | 처음 문서 |
+| `onChange(value, editor)` | – | 문서가 바뀔 때마다 (setValue 포함) |
+| `theme` | `"auto"` | `"light"`, `"dark"`, `"auto"`(시스템 설정을 따름) |
+| `readOnly` | `false` | 읽기 전용 |
+| `placeholder` | – | 문서가 비었을 때 보여줄 글 |
+| `lineNumbers` | `false` | 줄 번호 |
+| `features` | 모두 켬 | 기능 끄기. 예: `{ table: false, math: false }` |
+| `codeBlock` | – | `{ languages, theme, copyButton }`. 언어는 기본으로 `@codemirror/language-data`(쓸 때 불러옴), VS Code 테마는 `vscodeTheme(json)` |
+| `image` | – | `{ resolveUrl }`: 상대 경로 이미지 주소 바꾸기 |
+| `link` | – | `{ openLink }`: 링크를 눌렀을 때 |
+| `math` | – | `{ katex }`: KaTeX 옵션 (매크로 등) |
+| `tikz` | 끔 | 주면 TikZ 그림을 켭니다. 아래 참고 |
+| `markdown` | – | 목록 Enter 동작 등 문법 옵션 |
+| `extensions` | – | 덧붙일 CodeMirror 확장 |
+
+`features`로 끌 수 있는 기능: `emphasis`, `heading`, `hashtag`, `mention`, `escape`, `inlineCode`, `list`, `task`, `link`, `image`, `horizontalRule`, `footnote`, `quote`, `callout`, `codeBlock`, `math`, `table`
+
+### 메서드
+
+| 메서드 | 설명 |
+|---|---|
+| `getValue()` | 지금 문서 |
+| `open(value)` | 다른 파일(문서) 열기. 실행 취소 기록을 새로 시작하고 `onChange`를 부르지 않음. 커서는 처음, 스크롤은 맨 위 |
+| `setValue(value)` | 지금 문서의 내용 바꾸기. 편집처럼 실행 취소할 수 있고 `onChange`도 부름 |
+| `focus()` | 에디터에 포커스 |
+| `setTheme(theme)` | 테마 바꾸기 |
+| `setReadOnly(readOnly)` | 읽기 전용 바꾸기 |
+| `destroy()` | 에디터 없애기 |
+| `view` / `dom` | CodeMirror `EditorView` / 바깥 요소 |
+
+### TikZ 그림 (선택)
+
+```` ```tikz ```` 코드 블록을 그림으로 바꿉니다. 기본 렌더러는 브라우저에서 TeX을 돌리는
+[TikZJax](https://github.com/drgrice1/tikzjax)(`@drgrice1/tikzjax`, **GPL-3.0**)입니다.
+라이선스 때문에 mdsquare에 포함하지 않으며, 앱이 TikZJax의 `dist` 폴더를 같은 출처에서 제공해야 합니다.
+
+```ts
+new MDSquareEditor({
+  parent,
+  tikz: { tikzjax: { src: "/tikzjax/tikzjax.js" } },
+  // 또는 직접 만든 렌더러 (서버 렌더링 등): tikz: { render: async (doc) => svgString }
+});
+```
+
+### CodeMirror 확장으로 쓰기
+
+에디터를 직접 구성하려면 확장을 가져와 씁니다.
+
+```ts
+import { EditorView } from "@codemirror/view";
+import { basicSetup, extendedMarkdown, emphasis, table, math } from "mdsquare/extensions";
+
+new EditorView({ parent, extensions: [basicSetup(), extendedMarkdown(), emphasis(), table(), math()] });
+```
+
+## 개발
+
+```sh
+npm run dev        # 플레이그라운드 (playground/)
+npm test           # 테스트
+npm run build      # dist/ 만들기
+```
+
+Node 22.12 이상이 필요합니다. (개발 도구 기준)
+
+## 라이선스
+
+[MIT](./LICENSE)
+
+TikZ 그림의 기본 렌더러인 TikZJax(`@drgrice1/tikzjax`)는 GPL-3.0이며 mdsquare에 포함되어 있지 않습니다.
+TikZ를 켜는 앱이 TikZJax 파일을 직접 제공하므로, 그 앱은 TikZJax의 라이선스도 따라야 합니다.
+
+## Features
+
+- [x] Emphasis
+  1. [x] Bold: `**`, `__`
+  2. [x] Italic: `*`, `_`
+  3. [x] Strikethrough: `~~`
+  4. [x] Underline: `--`
+  5. [x] Highlight: `==`
+- [x] Inline Code
+- [x] Escape
+- [x] Heading
+  1. [x] Normal Heading: `#`
+  2. [x] SetextHeading(`===`, `---` 밑줄) 비활성: `===`는 글, 문단 바로 아래 `---`는 수평선. 켜려면 `markdown: { setextHeadings: true }` (확장으로 쓸 때는 `extendedMarkdown({ setextHeadings: true })`)
+- [x] HashTag
+  1. [x] Hierarchical HashTag: `#parent/child`
+- [x] Mention
+- [x] Bullet List
+- [x] Task List
+- [x] Ordered List
+  1. [ ] Roman Numerals: `i.`, `ii.`, `Ⅰ.` (검토 중: 원문은 표준 숫자 `1.`로 두고 화면에서만 깊이별로 로마 숫자 등으로 표시하는 방식 권장. 원문 문법으로 지원하면 비표준이고 `I. M. Pei` 같은 이니셜 오인식이 생김)
+- [x] Image
+  1. [x] Caption / Size / Align: `![caption|300x200|center](url)`
+- [x] Link
+- [x] HorizontalRule
+- [x] Footnote
+  1. [ ] Tooltip 디자인 변경 (현재: `src/footnote.ts`의 `.cm-footnote-tooltip` 기본 스타일)
+- [x] CodeBlock (Fenced Code)
+  1. [x] 구문 강조: CodeMirror 언어 파서(Lezer), 블록마다 따로 파싱·증분 파싱 (`languages`에 `@codemirror/language-data` 등)
+  2. [x] VS Code 색 테마: `vscodeTheme(json)` (JSON/JSONC, TextMate 스코프 매칭. Lezer 문법이 구분하지 않는 일부 토큰은 근사)
+  3. [x] 도구 모음: 마우스를 올리면 언어 + 복사 버튼
+- [x] Quote
+- [x] GFM Alert (Obsidian Callout)
+  1. [x] 유형/별칭: note, abstract, info, todo, tip, success, question, warning, failure, danger, bug, example, quote
+  2. [x] 접기: `[!type]+`, `[!type]-`
+  3. [x] 중첩 콜아웃
+- [ ] Front matter
+- [x] LaTeX (KaTeX)
+  1. [x] 인라인: `$...$` (Pandoc 규칙: `$5와 $6`은 수식 아님), 문단 안의 `$$...$$`는 디스플레이 모양
+  2. [x] 블록: `$$ ... $$` (여러 줄/한 줄, 인용·목록·콜아웃 안 포함, 편집 중 미리보기)
+- [x] TikZ (```` ```tikz ```` 코드 블록 → 그림)
+  1. [x] Obsidian TikZJax 형식(`\usepackage`, `\usetikzlibrary`, `\begin{document}`)과 tikzpicture만 쓴 형식
+  2. [x] 렌더러 교체 가능 (`tikz({ render })`), 기본은 TikZJax(`@drgrice1/tikzjax`, GPL-3.0이므로 라이브러리에 포함하지 않음. 앱이 `/tikzjax/`에 제공)
+  3. [x] 편집 중 미리보기, 렌더링 중 표시, 오류 표시, 결과 캐시, 어두운 테마에서 색 반전
+- [x] Table (GFM 표, 원문은 그대로 두고 화면에서만 표로)
+  1. [x] 칸 테두리, `|`·구분 줄 숨김, 열 너비는 내용에 맞춤(줄마다 subgrid), 좁으면 칸 안에서 줄바꿈, 열 정렬(`:-:`)
+  2. [x] 칸 안의 서식(굵게, 링크, 수식 등)은 다른 확장이 그대로 그림
+  3. [x] 제목 행/제목 열: 첫 행/첫 열 손잡이 메뉴로 켜고 끔, 표 윗줄 `<!-- table: header-column no-header-row -->` 주석에 저장
+  4. [x] 열 정렬: 열마다 위쪽 손잡이 메뉴에서 왼쪽/가운데/오른쪽 (구분 줄의 그 칸만 길이를 유지해 바꿈)
+  5. [x] Enter: 새 행 (빈 마지막 행에서 Enter는 표 끝내기), Tab/Shift+Tab: 칸 이동 (마지막 칸에서 새 행, 모자란 칸 채우기)
+  6. [x] 칸 경계에서 Backspace/Delete는 `|`를 지우지 않고 옆 칸으로, 칸 사이는 한 번에 이동
+     - 커서는 앞 `|` 앞(접두어 포함)이나 뒤 `|` 뒤에 놓이지 않음 (키보드, 클릭, Home/End, 처음 상태 모두)
+     - ←/→는 행 경계를 넘어 윗행 끝/아랫행 처음으로, ↑/↓는 칸 안 줄바꿈 → 위/아래 행의 같은 열 → 표 밖
+     - 표 바로 바깥 줄에서 Delete/Backspace로 표 줄과 합치지 않음
+     - `|` 옆 공백 한 칸만 숨김(나머지 공백은 보임). 숨긴 범위 안에 커서가 생기지 않아 입력 위치가 어긋나지 않음
+  7. [x] 인용, 중첩 인용, 목록, 콜아웃 안의 표
+  8. [x] 머리글보다 많은 칸은 마지막 칸 안에 흐린 원문으로 (넘치지 않음). 칸 안 이미지의 크기는 `![a\|16x16](url)` (Obsidian과 같음)
+  9. [x] 행/열 메뉴 (모든 행 왼쪽·모든 열 위쪽 손잡이): 위/아래·왼쪽/오른쪽에 삽입, 복제, 내용 지우기, 삭제
+     - 원문은 줄마다 필요한 곳만 바꿈 (칸 하나 + `|` 하나). 첫 행 위 삽입/첫 행 삭제 시 구분 줄을 옮겨 GFM 표 유지
+     - 하나뿐인 행/열을 지우면 표(설정 주석 포함)를 지움
+  10. [x] 행/열 끌어서 옮기기, 행/열 색, 메뉴 검색
+     - 손잡이를 짧게 누르면 메뉴, 끌면 옮기기 (놓일 자리를 파란 선으로 표시). 첫 행으로 옮기면 구분 줄이 따라감
+     - 색: 글자 색/배경 색 9가지 (Notion과 같은 색). 한 행/열에 글자 색과 배경 색을 따로 지정. 설정 주석에 저장 `<!-- table: row-2:red row-2:yellow-bg col-1:blue -->` (번호는 1부터)
+     - 행/열 추가·삭제·복제·이동, Enter로 행 추가 시 색 번호도 함께 옮김 (직접 `|`나 줄을 지우는 편집은 따라가지 않음)
+     - 메뉴 검색: 한글/영어 이름, 하위 메뉴의 색과 정렬도 검색. ↑/↓/Enter, Esc
+  11. [x] 칸 색: 칸 내용 맨 앞의 숨은 주석 표식 `| <!--fg:red bg:blue--> 값 |` (다른 렌더러에서는 보이지 않음)
+     - 색이 칸 내용과 함께 움직임 (직접 편집, 잘라 붙이기, 행/열 이동·복제에도 유지). 글자 색과 배경 색은 따로
+     - 칸 색 > 행 색 > 열 색. 표식은 숨기고 커서가 닿으면 원문을 보여 줌. 칸 처음에 입력해도 표식 뒤에 들어가고 Backspace로 지워지지 않음
+     - 칸 범위 선택: 두 칸 이상을 끌어 고르면 사각형 칸 선택 (Notion처럼). 칸에서 오른쪽 클릭 → 색 / 내용 지우기 (고른 범위 안이면 범위 전체)
+
+## UI 개선 (TODO)
+
+문법마다 화면 디자인(색, 간격, 기호 표시, 위젯 모양, 어두운 테마)을 다듬습니다.
+
+- [ ] Emphasis (굵게, 기울임, 취소선, 밑줄, 하이라이트)
+- [ ] Inline Code
+- [ ] Escape
+- [ ] Heading
+- [ ] HashTag
+- [ ] Mention
+- [ ] Bullet List / Ordered List
+- [ ] Task List
+- [ ] Image
+- [ ] Link
+- [ ] HorizontalRule
+- [ ] Footnote (툴팁 디자인 포함)
+- [ ] CodeBlock
+- [ ] Quote
+- [ ] GFM Alert (Obsidian Callout)
+- [ ] LaTeX (KaTeX)
+- [ ] TikZ
+- [ ] Table

package/dist/callout.d.ts

@@ -0,0 +1,17 @@
+import type { Extension } from "@codemirror/state";
+import { ViewPlugin } from "@codemirror/view";
+export declare const calloutPlugin: ViewPlugin<import("./extensions.js").RevealPluginValue, undefined>;
+/**
+ * Obsidian 콜아웃 / GFM 알림을 보여주는 확장입니다.
+ *
+ * ```
+ * > [!note] 제목          유형: note, abstract, info, todo, tip, success, question,
+ * > 내용                   warning, failure, danger, bug, example, quote (+ 별칭)
+ * > [!faq]- 접힌 콜아웃   +: 접을 수 있음(펼침), -: 접을 수 있음(기본 접힘)
+ * ```
+ * - 유형별 색 배경 + 아이콘 + 제목. 제목이 없으면 유형 이름을 제목으로 보여줍니다.
+ * - 커서가 콜아웃 안에 들어오면 콜아웃 전체(안쪽 콜아웃 포함)를 원문으로 보여줍니다. (Obsidian과 같은 편집 방식)
+ * - 중첩 콜아웃은 바깥 상자 안의 상자로 그립니다. (3단계까지 정확히, 더 깊으면 3단계로)
+ * - quote()를 포함합니다. (`>` 숨김, 콜아웃이 아닌 인용의 세로줄)
+ */
+export declare function callout(): Extension;