feat(froala): rulerVerticalGutter — reserve the vertical ruler column up front (#24)

Field report: with the horizontal ruler reading ~820px, enabling the
vertical ruler narrowed the content to ~800px. That shift is geometric
truth — the 23px strip has to take its space from somewhere, and the
horizontal ruler correctly re-reads the narrower width — but the reflow
on toggle is jarring.

New opt-in option (default false), scrollbar-gutter: stable style:
- rulerVerticalGutter: true creates the vwrap/strip column at init with
  visibility:hidden, so the 23px is spent once up front and toggling the
  vertical ruler never moves the content.
- hide switches visibility (gutter kept) instead of display:none; the
  horizontal ruler offset applies whenever the gutter exists.
- Default path unchanged: hidden strip still reclaims its width.

Docs: option documented in both root READMEs + froala package READMEs
(en/ko), demo site enables it on the Froala tab, CDN pins @0.12 -> @0.13.

Verified: 91 unit tests green (3 new — gutter reserved up front, no
reflow across toggles, default still reclaims); real-browser check on the
built demo — horizontal ruler 794px and text left edge unchanged (0px
moved) across show/hide.

Author: jlc488

CHANGELOG.md

@@ -9,6 +9,23 @@ with a shared version number.
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-08-06
+
+### Added
+
+- `@devslab/editor-ruler-froala` — **`rulerVerticalGutter` option** (default
+  false): reserves the vertical ruler's 23px column from init, like CSS
+  `scrollbar-gutter: stable`. Without it, showing the vertical ruler narrows
+  the writable area by 23px (the strip has to take its space from somewhere,
+  and the horizontal ruler correctly re-reads the narrower width — e.g.
+  820 → ~797); with the gutter on, that space is always reserved, so toggling
+  the vertical ruler never reflows the content. Prompted by a field report of
+  the width shift — thank you!
+
+### Changed
+
+- README CDN pins bumped `@0.12` → `@0.13`.
+
 ## [0.12.3] - 2026-08-06
 
 ### Fixed
@@ -214,7 +231,8 @@ with a shared version number.
   records one Froala undo step per gesture. iife build exposes the
   `EditorRulerFroala` global (core bundled) for CDN use.
 
-[Unreleased]: https://github.com/devslab-kr/editor-ruler/compare/v0.12.3...HEAD
+[Unreleased]: https://github.com/devslab-kr/editor-ruler/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/devslab-kr/editor-ruler/compare/v0.12.3...v0.13.0
 [0.12.3]: https://github.com/devslab-kr/editor-ruler/compare/v0.12.2...v0.12.3
 [0.12.2]: https://github.com/devslab-kr/editor-ruler/compare/v0.12.1...v0.12.2
 [0.12.1]: https://github.com/devslab-kr/editor-ruler/compare/v0.12.0...v0.12.1

README.ko.md

@@ -44,7 +44,7 @@ ruler.refresh(); // 선택/내용이 바뀔 때마다 호출
 iife 빌드가 전역 `EditorRuler`를 노출합니다:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@devslab/editor-ruler@0.12/dist/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@devslab/editor-ruler@0.13/dist/index.global.js"></script>
 <script>
   const ruler = EditorRuler.createRuler(mountElement, { /* 동일한 옵션 */ });
 </script>
@@ -56,8 +56,8 @@ Froala 어댑터도 동일합니다 — `@devslab/editor-ruler-froala/dist/index
 
 | URL | 의미 |
 |---|---|
-| `@0.12.2` | 정확한 버전 고정 — 절대 안 바뀜, 캐시 최장 |
-| `@0.12` | `0.12.x` 최신 패치 — 버그픽스 자동 반영, 브레이킹 없음 (권장) |
+| `@0.13.0` | 정확한 버전 고정 — 절대 안 바뀜, 캐시 최장 |
+| `@0.13` | `0.13.x` 최신 패치 — 버그픽스 자동 반영, 브레이킹 없음 (권장) |
 | `@latest` (또는 버전 생략) | 항상 최신 릴리스 — 메이저 포함이라 브레이킹 체인지가 예고 없이 들어올 수 있음; jsDelivr가 별칭을 최대 12시간 캐시 |
 
 ## 빠른 시작 (Froala)
@@ -119,7 +119,7 @@ ClassicEditor.create(element, {
 - `rulerOptions` — **권장 단일 버튼**: 줄자 아이콘 드롭다운 하나에 보이기/숨기기 · 세로 줄자 · 가이드 잠금 · 가이드 지우기 + cm / inch / px (활성 상태 체크 표시)
 - `toggleRuler` / `rulerUnit` — 핵심 기능을 버튼을 나눠 쓰고 싶을 때
 
-Froala 옵션: `rulerVertical: true`면 초기화 시 세로 줄자 표시, `rulerGuides: false`면 가이드선 비활성.
+Froala 옵션: `rulerVertical: true`면 초기화 시 세로 줄자 표시, `rulerVerticalGutter: true`면 세로 줄자의 23px 자리를 처음부터 예약해(`scrollbar-gutter: stable`과 같은 발상) 토글해도 본문이 리플로우되지 않음, `rulerGuides: false`면 가이드선 비활성.
 
 ## 기능
 

README.md

@@ -44,7 +44,7 @@ ruler.refresh(); // call whenever selection or content changes
 The iife build exposes an `EditorRuler` global:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@devslab/editor-ruler@0.12/dist/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@devslab/editor-ruler@0.13/dist/index.global.js"></script>
 <script>
   const ruler = EditorRuler.createRuler(mountElement, { /* same options */ });
 </script>
@@ -56,8 +56,8 @@ Version pinning options:
 
 | URL | Meaning |
 |---|---|
-| `@0.12.2` | Exact version — never changes, cached longest |
-| `@0.12` | Latest `0.12.x` patch — bugfixes auto-applied, no breaking changes (recommended) |
+| `@0.13.0` | Exact version — never changes, cached longest |
+| `@0.13` | Latest `0.13.x` patch — bugfixes auto-applied, no breaking changes (recommended) |
 | `@latest` (or no version) | Always the newest release — majors included, so breaking changes can land without warning; jsDelivr caches the alias for up to 12h |
 
 ## Quick start (Froala)
@@ -119,7 +119,7 @@ Model attributes down-cast to plain inline CSS; one undo step per drag. See the
 - `rulerOptions` — **recommended single button**: one ruler-icon dropdown holding Show/Hide, Vertical Ruler, Lock Guides, Clear Guides, plus cm / inch / px (active states checkmarked)
 - `toggleRuler` / `rulerUnit` — the same core functions as separate buttons, for hosts that prefer them split
 
-Froala options: `rulerVertical: true` shows the vertical ruler on init; `rulerGuides: false` disables guide lines.
+Froala options: `rulerVertical: true` shows the vertical ruler on init; `rulerVerticalGutter: true` reserves the strip's 23px column from the start (like `scrollbar-gutter: stable`) so toggling the vertical ruler never reflows the content; `rulerGuides: false` disables guide lines.
 
 ## Features
 

packages/editor-ruler-ckeditor5/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devslab/editor-ruler-ckeditor5",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "description": "CKEditor 5 plugin for @devslab/editor-ruler — a Word-like horizontal ruler with margins, first-line indent, and guide lines.",
   "license": "Apache-2.0",
   "author": "devslab",

packages/editor-ruler-froala/README.ko.md

@@ -17,9 +17,14 @@ import { defineRulerPlugin } from '@devslab/editor-ruler-froala';
 defineRulerPlugin(FroalaEditor); // 에디터 인스턴스 생성 전에 1회
 
 new FroalaEditor('#editor', {
-  rulerEnabled: true, // 기본 true
-  rulerUnit: 'cm',    // 'cm' | 'in' | 'px'
-  toolbarButtons: ['bold', 'italic', '|', 'toggleRuler'], // 툴바 토글 버튼 (선택)
+  rulerEnabled: true,          // 기본 true
+  rulerUnit: 'cm',             // 'cm' | 'in' | 'px'
+  rulerVertical: false,        // 초기화 시 세로 줄자 표시
+  rulerVerticalGutter: false,  // 세로 줄자의 23px 자리를 처음부터 예약
+                               // (scrollbar-gutter: stable 방식) — 토글해도
+                               // 본문이 리플로우되지 않음
+  rulerGuides: true,           // 가이드선 (줄자에서 드래그해 생성)
+  toolbarButtons: ['bold', 'italic', '|', 'rulerOptions'], // 툴바 드롭다운 (선택)
 });
 ```
 
@@ -30,7 +35,7 @@ new FroalaEditor('#editor', {
 CDN 사용 — iife 빌드는 코어를 포함한 단일 파일로 전역 `EditorRulerFroala`를 노출합니다:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@devslab/editor-ruler-froala@0.12/dist/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@devslab/editor-ruler-froala@0.13/dist/index.global.js"></script>
 <script>
   EditorRulerFroala.defineRulerPlugin(FroalaEditor);
 </script>

packages/editor-ruler-froala/README.md

@@ -17,9 +17,14 @@ import { defineRulerPlugin } from '@devslab/editor-ruler-froala';
 defineRulerPlugin(FroalaEditor); // once, before creating editor instances
 
 new FroalaEditor('#editor', {
-  rulerEnabled: true, // default true
-  rulerUnit: 'cm',    // 'cm' | 'in' | 'px'
-  toolbarButtons: ['bold', 'italic', '|', 'toggleRuler'], // optional toolbar toggle
+  rulerEnabled: true,          // default true
+  rulerUnit: 'cm',             // 'cm' | 'in' | 'px'
+  rulerVertical: false,        // show the vertical ruler on init
+  rulerVerticalGutter: false,  // reserve the vertical ruler's 23px column up
+                               // front (scrollbar-gutter: stable style), so
+                               // toggling it never reflows the content
+  rulerGuides: true,           // guide lines (drag out of a ruler)
+  toolbarButtons: ['bold', 'italic', '|', 'rulerOptions'], // optional toolbar dropdown
 });
 ```
 
@@ -30,7 +35,7 @@ If you configure `pluginsEnabled` explicitly, add `'ruler'` to the list.
 CDN usage — the iife build bundles the core into one file and exposes `EditorRulerFroala`:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@devslab/editor-ruler-froala@0.12/dist/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@devslab/editor-ruler-froala@0.13/dist/index.global.js"></script>
 <script>
   EditorRulerFroala.defineRulerPlugin(FroalaEditor);
 </script>

packages/editor-ruler-froala/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devslab/editor-ruler-froala",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "description": "Froala WYSIWYG editor adapter for @devslab/editor-ruler — a Word-like horizontal ruler plugin.",
   "license": "Apache-2.0",
   "author": "devslab",

packages/editor-ruler-froala/src/index.ts

@@ -23,6 +23,13 @@ export interface FroalaRulerOptions {
   rulerUnit?: RulerUnit;
   /** Show the vertical ruler strip on init. Default false. */
   rulerVertical?: boolean;
+  /**
+   * Reserve the vertical ruler's 23px column from the start (like CSS
+   * `scrollbar-gutter: stable`), so toggling the vertical ruler never
+   * reflows the content — hidden means an empty gutter, not reclaimed
+   * width. Default false: the strip only takes space while visible.
+   */
+  rulerVerticalGutter?: boolean;
   /** Enable guide lines (drag down from the ruler strip). Default true. */
   rulerGuides?: boolean;
 }
@@ -135,6 +142,7 @@ export function defineRulerPlugin(FroalaEditor: any, defineOptions: DefineRulerP
       rulerEnabled: true,
       rulerUnit: 'cm' satisfies RulerUnit,
       rulerVertical: false,
+      rulerVerticalGutter: false,
       rulerGuides: true,
       rulerLanguage: null,
     },
@@ -367,9 +375,15 @@ export function defineRulerPlugin(FroalaEditor: any, defineOptions: DefineRulerP
       return parseFloat(win.getComputedStyle(el)[side]) || 0;
     }
 
+    function vGutter(): boolean {
+      return editor.opts.rulerVerticalGutter === true;
+    }
+
     /** Extra x-offset the vertical ruler strip adds in front of the editor. */
     function vRulerOffset(): number {
-      return vVisible ? 23 : 0; // 22px strip + 1px border
+      // 22px strip + 1px border. In gutter mode the column is reserved even
+      // while the strip is hidden, so the offset applies whenever it exists.
+      return vVisible || (vGutter() && vwrap) ? 23 : 0;
     }
 
     function alignMount(): void {
@@ -389,7 +403,7 @@ export function defineRulerPlugin(FroalaEditor: any, defineOptions: DefineRulerP
       return editor.$wp?.get?.(0) ?? editorEl().parentElement ?? editorEl();
     }
 
-    function showVRuler(): void {
+    function ensureVWrap(): void {
       const el = editorEl();
       const doc = el.ownerDocument;
       if (!vwrap) {
@@ -421,14 +435,24 @@ export function defineRulerPlugin(FroalaEditor: any, defineOptions: DefineRulerP
           },
         });
       }
+    }
+
+    function showVRuler(): void {
+      ensureVWrap();
       vmount!.style.display = '';
+      vmount!.style.visibility = '';
       vVisible = true;
       refresh();
     }
 
     function hideVRuler(): void {
       if (!vmount) return;
-      vmount.style.display = 'none';
+      if (vGutter()) {
+        // Keep the reserved column — hide the strip without reclaiming width.
+        vmount.style.visibility = 'hidden';
+      } else {
+        vmount.style.display = 'none';
+      }
       vVisible = false;
       refresh();
     }
@@ -536,7 +560,14 @@ export function defineRulerPlugin(FroalaEditor: any, defineOptions: DefineRulerP
       alignMount();
       visible = true;
 
-      if (editor.opts.rulerVertical === true) showVRuler();
+      if (editor.opts.rulerVertical === true) {
+        showVRuler();
+      } else if (vGutter()) {
+        // Reserve the gutter up front so a later toggle doesn't reflow content.
+        ensureVWrap();
+        vmount!.style.visibility = 'hidden';
+        refresh();
+      }
 
       for (const event of ['mouseup', 'keyup', 'contentChanged', 'commands.after']) {
         editor.events?.on?.(event, refresh);

packages/editor-ruler-froala/test/plugin.test.ts

@@ -236,6 +236,60 @@ describe('defineRulerPlugin', () => {
     expect(container.contains(wrapper)).toBe(true); // wrapper restored to its old place
   });
 
+  it('rulerVerticalGutter reserves the strip column up front, hidden', () => {
+    const FE = makeFroalaConstructor();
+    defineRulerPlugin(FE);
+    const { editor, container } = makeEditor({ rulerVerticalGutter: true });
+    const api = FE.PLUGINS.ruler!(editor);
+    api._init();
+
+    // The gutter exists from init even though the strip is not shown…
+    expect(api.isVRulerVisible()).toBe(false);
+    const vmount = container.querySelector('.edr-froala-vmount') as HTMLElement;
+    expect(vmount).toBeTruthy();
+    expect(vmount.style.visibility).toBe('hidden');
+    expect(vmount.style.display).not.toBe('none');
+    // …and the horizontal ruler is already offset past it.
+    const mount = container.querySelector('.edr-froala-mount') as HTMLElement;
+    expect(mount.style.paddingLeft).toBe('23px');
+  });
+
+  it('rulerVerticalGutter keeps the column (no reflow) across vruler toggles', () => {
+    const FE = makeFroalaConstructor();
+    defineRulerPlugin(FE);
+    const { editor, container } = makeEditor({ rulerVerticalGutter: true });
+    const api = FE.PLUGINS.ruler!(editor);
+    api._init();
+    const vmount = container.querySelector('.edr-froala-vmount') as HTMLElement;
+    const mount = container.querySelector('.edr-froala-mount') as HTMLElement;
+
+    api.toggleVRuler(); // show
+    expect(api.isVRulerVisible()).toBe(true);
+    expect(vmount.style.visibility).toBe('');
+    expect(mount.style.paddingLeft).toBe('23px');
+
+    api.toggleVRuler(); // hide — gutter stays, width untouched
+    expect(api.isVRulerVisible()).toBe(false);
+    expect(vmount.style.visibility).toBe('hidden');
+    expect(vmount.style.display).not.toBe('none');
+    expect(mount.style.paddingLeft).toBe('23px');
+  });
+
+  it('without the gutter option, hiding the vruler reclaims its width', () => {
+    const FE = makeFroalaConstructor();
+    defineRulerPlugin(FE);
+    const { editor, container } = makeEditor({ rulerVertical: true });
+    const api = FE.PLUGINS.ruler!(editor);
+    api._init();
+    const vmount = container.querySelector('.edr-froala-vmount') as HTMLElement;
+    const mount = container.querySelector('.edr-froala-mount') as HTMLElement;
+    expect(mount.style.paddingLeft).toBe('23px');
+
+    api.toggleVRuler(); // hide — strip removed from layout entirely
+    expect(vmount.style.display).toBe('none');
+    expect(mount.style.paddingLeft).toBe('0px');
+  });
+
   it('drags a horizontal guide from the horizontal ruler, vertical from the vertical', () => {
     const FE = makeFroalaConstructor();
     defineRulerPlugin(FE);

packages/editor-ruler-tiptap/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devslab/editor-ruler-tiptap",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "description": "Tiptap extension for @devslab/editor-ruler — a Word-like horizontal ruler with margins, first-line indent, and guide lines.",
   "license": "Apache-2.0",
   "author": "devslab",