Skip to content

feat(editor): add a searchable KingSejong language reference panel - #5

Merged
0xmhha merged 1 commit into
mainfrom
feat/language-reference
Oct 29, 2026
Merged

0xmhha merged 1 commit into
mainfrom
feat/language-reference

Conversation

@0xmhha

@0xmhha 0xmhha commented Oct 29, 2026

Copy link
Copy Markdown
Member

Summary

Adds a searchable KingSejong syntax and keyword reference beside the editor.

  • Where it opens:
    • a "문법 참고 / Reference" toggle in the header (it stays pressed while the panel is open);
    • the ☰ menu, at every width;
    • the command palette (F1).
  • Content: 43 entries in 9 topics:
    • basics, operators, conditions and loops, functions, arrays;
    • particles (조사), errors and async;
    • built-in functions, modules and the standard library.
  • Search: filters as you type. It matches Korean keywords, English names (for, print, filter ...), descriptions and example code. Results whose name matches the query come first.
  • Insert: puts the entry's example at the editor cursor as one undoable edit (Ctrl/Cmd+Z removes all of it).
  • Translation: every title and description is in Korean and English, and the panel chrome is in messages/{ko,en}.json. The example code is shared between locales.
  • Other languages: when Python or Go is selected, the examples are read-only and the panel offers a "킹세종으로 바꾸기 / Switch to KingSejong" button.

Also fixes a development-build crash. The first time the file list was opened, the page showed the error screen ("InstantiationService has been disposed"). A new E2E test covers it.

Design

  • Source of the content. src/features/reference/entries.ts is written from kingsejong-lang/docs/LANGUAGE_REFERENCE.md and STDLIB_REFERENCE.md (v0.6).
    • Every example is a complete program. I ran all 43 with the v0.6 interpreter (kingsejong, built from the language repository), and each printed what its # ... comments say.
    • Built-ins for files, directories, HTTP, SQLite and environment variables are left out, because a sandboxed run should not offer them.
  • Placement. The panel is not modal, so learners can read it while they type (the Impeccable craft floor rules out a modal for a task that needs neither interruption nor protected focus).
    • From lg it is docked on the right of the workspace, 320 px wide (384 px from xl).
    • Below lg it is an overlay drawer with a scrim, like the file list.
    • Esc, the scrim and the close button all close it. The search box takes focus when the panel opens.
  • Visual system. It uses the existing Code Sanctuary tokens and parts: hairline dividers, sticky topic headings, the accent text shade for syntax, a void-ground code block, and a ghost "넣기 / Insert" button. No new colours were added.
    • The browser's default search-clear glyph is replaced by the app's own clear button.
    • The Impeccable detector reports no findings for the changed UI files.
  • Insertion rule (insertionEdit in CodeEditor.tsx):
    • a selection is replaced;
    • on an empty line the text goes at the cursor;
    • on a line with code it goes on a new line below.
    • The cursor ends after the inserted text.
  • Lazy loading. The panel is a lazily loaded chunk of 26.8 KB (10.1 KB gzip). The initial page bundle does not change.
  • Crash fix. next/dynamic panels without a loading option suspend the page's top-level <Suspense> while their chunk loads. That tears down Monaco, and recreating it threw. FileTree and the new panel now pass loading: () => null. I reproduced the crash on main with next dev; a next start build of main did not crash.

Testing

  • npx vitest run: 268 tests pass. New tests cover:
    • entry integrity: unique ids, both locales filled, no empty topics;
    • search: Korean, English, multiple terms, decomposed Hangul, ranking;
    • the panel: filtering, the empty state, both clear buttons, insert, the read-only note with the switch button, Esc and close;
    • insertionEdit.
  • npx playwright test tests/e2e/fake: 18 tests pass, including the new ones:
    • reference.spec.ts: search for "filter", insert below existing code, one undo restores the file, and the read-only mode for Python with the switch to KingSejong;
    • playground.spec.ts: opening the file list keeps the editor. This test fails on main.
  • Production check. On a next build and next start build of this branch, opening the file list and then the reference panel causes no page errors and no error screen.
  • npm run typecheck: passes.
  • npm run lint: 0 errors and 12 warnings, the same count as main.
  • npm run build: passes.
  • Visual check. I took screenshots at 1440×900 in ko and en, with KingSejong and with Python, and at 390×844 for the drawer.

Not verified

  • I did not run the examples through the playground backend, only through the local v0.6 interpreter. If the backend's sandbox runs a different interpreter version, or blocks the stdlib import path or time functions, the import, time or random examples may behave differently.
  • I did not test the undo keystroke itself in a headless browser, because Playwright's keyboard input does not reach Monaco's EditContext reliably there. The E2E test undoes through the editor model instead.

Learners can now look up KingSejong syntax and built-in functions next
to the editor. The panel opens from the header (and the "more" menu and
command palette), lists 43 entries in nine topics, filters as you type
in Korean or English, and inserts an entry's example at the editor
cursor as a single undoable edit.

- Content follows the language's LANGUAGE_REFERENCE.md and
  STDLIB_REFERENCE.md (v0.6). Every example was run with the v0.6
  interpreter and prints what its comments say. Built-ins for files,
  network, databases and the environment are left out.
- Titles and descriptions are written in Korean and English; examples
  are shared code.
- The panel is not modal so it can stay open while typing: docked on
  the right from the lg breakpoint, an overlay drawer below it.
- For other languages the examples are read-only and the panel offers
  to switch to KingSejong.
- Results whose name matches the query come before matches in the
  description.

Lazily loaded panels now get a `loading` placeholder. Without one, the
first time the file list was opened in a development build the whole
page suspended and the Monaco editor crashed when it was recreated
("InstantiationService has been disposed").
@0xmhha
0xmhha force-pushed the feat/language-reference branch from d266e4a to 58670b8 Compare October 29, 2026 03:32
@0xmhha
0xmhha merged commit 0eb2833 into main Oct 29, 2026
2 checks passed
@0xmhha
0xmhha deleted the feat/language-reference branch October 29, 2026 03:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant