feat(editor): add permanent global toggle for code block line numbers (#15381)

Add a persistent "Show line numbers in code blocks" setting to Editor
Settings that controls line-number visibility across all code blocks.
Individual blocks can still override the global default via the
per-block More menu toggle.

## Changes

- **schema.ts** - add `codeBlockLineNumbers: z.boolean().default(true)`
to `AffineEditorSettingSchema`
- **code-block.ts** - read `codeBlockLineNumbers` from
`EditorSettingProvider` reactively via a stable `signal(true)` updated
by `effect()` in `connectedCallback`; expose `showLineNumbers` getter as
single source of truth used by both `renderBlock()` and the toolbar
- **config.ts** - toolbar line-number toggle reads
`blockComponent.showLineNumbers` (resolved state) instead of
`model.props.lineNumber ?? true`
- **general.tsx** - add `DefaultCodeBlockLineNumberSettings` Switch row
in editor general settings
- **en.json + i18n.gen.ts** - add i18n strings for the new setting
- **line-numbers.spec.ts** - add 7 e2e tests covering default
visibility, global toggle on/off, per-block override in both directions,
multi-block, newly created blocks, and persistence across reload

## Behaviour

| State | Result |
|---|---|
| Global ON (default), no per-block override | Line numbers shown |
| Global OFF, no per-block override | Line numbers hidden |
| Global OFF, per-block explicitly ON | Line numbers shown |
| Global ON, per-block explicitly OFF | Line numbers hidden |
| Mobile (feature flag) | Always hidden regardless of settings |

## Notes

- Existing per-block toggle behaviour is fully preserved and unchanged
- Default is `true` so no regression for existing users
- The blocksuite-side reads `codeBlockLineNumbers` via a type cast (`as
Record<string, unknown>`) because the key lives in the AFFiNE-level
`EditorSettingSchema`, not in blocksuite's own `GeneralSettingSchema` -
this is an intentional architectural boundary

Closes #14965


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a global setting to show or hide line numbers in code blocks by
default.
  * Added localized title and description text for the new setting.
  * Preserved per-code-block overrides through the block’s More menu.

* **Bug Fixes**
* Line-number visibility now stays consistent across existing and newly
created code blocks, including after reloads.

* **Tests**
* Added end-to-end coverage for defaults, overrides, persistence, and
multiple code blocks.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

blocksuite/affine/blocks/code/src/code-block.ts

@@ -8,6 +8,7 @@ import {
 import {
   BlockElementCommentManager,
   DocModeProvider,
+  EditorSettingProvider,
   NotificationProvider,
 } from '@blocksuite/affine-shared/services';
 import { getViewportElement } from '@blocksuite/affine-shared/utils';
@@ -97,6 +98,16 @@ export class CodeBlockComponent extends CaptionedBlockComponent<CodeBlockModel>
     return this.std.get(CodeBlockHighlighter);
   }
 
+  /** Whether line numbers are currently shown for this block, accounting for the global setting and feature flags. */
+  get showLineNumbers(): boolean {
+    // Feature flag: mobile (or any other consumer) can hard-disable via CodeBlockConfigExtension.
+    const featureEnabled =
+      this.std.getOptional(CodeBlockConfigExtension.identifier)
+        ?.showLineNumbers ?? true;
+    if (!featureEnabled) return false;
+    // Per-block prop overrides the global default; global defaults to true.
+    return this.model.props.lineNumber ?? this._showLineNumbersGlobal$.value;
+  }
   override get topContenteditableElement() {
     if (this.std.get(DocModeProvider).getEditorMode() === 'edgeless') {
       return this.closest<BlockComponent>(
@@ -159,9 +170,32 @@ export class CodeBlockComponent extends CaptionedBlockComponent<CodeBlockModel>
     }
   }
 
+  /**
+   * Stable signal: true when the global editor setting enables line numbers.
+   * Defaults to true. Updated reactively by an effect in connectedCallback.
+   * Using a writable signal (not reassigned to computed) keeps the reference
+   * stable so any downstream computed/effect that captures it stays correct.
+   */
+  private readonly _showLineNumbersGlobal$: Signal<boolean> = signal(true);
+
   override connectedCallback() {
     super.connectedCallback();
 
+    // Reactively sync the global line-number preference from EditorSettingProvider
+    // into the stable _showLineNumbersGlobal$ signal. Using effect() keeps the
+    // signal reference constant (no identity change) while still tracking updates.
+    const editorSetting = this.std.getOptional(EditorSettingProvider);
+    if (editorSetting) {
+      this.disposables.add(
+        effect(() => {
+          const val = (
+            editorSetting.setting$.value as Record<string, unknown>
+          )?.['codeBlockLineNumbers'];
+          this._showLineNumbersGlobal$.value = val !== false;
+        })
+      );
+    }
+
     // set highlight options getter used by "exportToHtml"
     this.disposables.add(
       effect(() => {
@@ -410,11 +444,7 @@ export class CodeBlockComponent extends CaptionedBlockComponent<CodeBlockModel>
   }
 
   override renderBlock(): TemplateResult<1> {
-    const showLineNumbers =
-      (this.std.getOptional(CodeBlockConfigExtension.identifier)
-        ?.showLineNumbers ??
-        true) &&
-      (this.model.props.lineNumber ?? true);
+    const showLineNumbers = this.showLineNumbers;
 
     const preview = this.preview$.value;
     const previewContext = this.std.getOptional(

blocksuite/affine/blocks/code/src/code-toolbar/config.ts

@@ -234,15 +234,13 @@ export const toggleGroup: MenuItemGroup<CodeBlockToolbarContext> = {
         return {
           action: () => {},
           render: () => {
-            const lineNumber = blockComponent.model.props.lineNumber ?? true;
+            const lineNumber = blockComponent.showLineNumbers;
             const label = lineNumber ? 'Cancel line number' : 'Line number';
             return html`
               <editor-menu-action
                 @click=${() => {
-                  const currentLineNumber =
-                    blockComponent.model.props.lineNumber ?? true;
                   blockComponent.store.updateBlock(blockComponent.model, {
-                    lineNumber: !currentLineNumber,
+                    lineNumber: !blockComponent.showLineNumbers,
                   });
                 }}
                 aria-label=${label}

packages/frontend/core/src/desktop/dialogs/setting/general-setting/editor/general.tsx

@@ -674,6 +674,36 @@ const MiddleClickPasteSettings = () => {
   );
 };
 
+const DefaultCodeBlockLineNumberSettings = () => {
+  const t = useI18n();
+  const editorSettingService = useService(EditorSettingService);
+  const settings = useLiveData(editorSettingService.editorSetting.settings$);
+
+  const onToggle = useCallback(
+    (checked: boolean) => {
+      editorSettingService.editorSetting.set('codeBlockLineNumbers', checked);
+    },
+    [editorSettingService.editorSetting]
+  );
+
+  return (
+    <SettingRow
+      name={t[
+        'com.affine.settings.editorSettings.general.default-code-block.line-numbers.title'
+      ]()}
+      desc={t[
+        'com.affine.settings.editorSettings.general.default-code-block.line-numbers.description'
+      ]()}
+    >
+      <Switch
+        data-testid="code-block-line-numbers-trigger"
+        checked={settings.codeBlockLineNumbers}
+        onChange={onToggle}
+      />
+    </SettingRow>
+  );
+};
+
 export const General = () => {
   const t = useI18n();
 
@@ -685,11 +715,9 @@ export const General = () => {
       <FontSizeSettings />
       <NewDocDefaultModeSettings />
       <NewDocDateTitleSettings />
+      <DefaultCodeBlockLineNumberSettings />
       {BUILD_CONFIG.isElectron && <SpellCheckSettings />}
       {environment.isLinux && <MiddleClickPasteSettings />}
-      {/* // TODO(@akumatus): implement these settings
-        <DeFaultCodeBlockSettings />
-       */}
     </SettingWrapper>
   );
 };

packages/frontend/core/src/modules/editor-setting/schema.ts

@@ -50,6 +50,7 @@ const AffineEditorSettingSchema = z.object({
     .default('open-in-active-view'),
   // linux only:
   enableMiddleClickPaste: z.boolean().default(false),
+  codeBlockLineNumbers: z.boolean().default(true),
 });
 
 export const EditorSettingSchema = BSEditorSettingSchema.merge(

packages/frontend/i18n/src/i18n.gen.ts

@@ -5497,6 +5497,14 @@ export function useAFFiNEI18N(): {
       * `Code blocks default language`
       */
     ["com.affine.settings.editorSettings.general.default-code-block.language.title"](): string;
+    /**
+      * `Show line numbers in all code blocks by default.`
+      */
+    ["com.affine.settings.editorSettings.general.default-code-block.line-numbers.description"](): string;
+    /**
+      * `Show line numbers in code blocks`
+      */
+    ["com.affine.settings.editorSettings.general.default-code-block.line-numbers.title"](): string;
     /**
       * `Encapsulate code snippets for better readability.`
       */

packages/frontend/i18n/src/resources/en.json

@@ -1368,6 +1368,8 @@
   "com.affine.settings.editorSettings.general.ai.title": "AFFiNE AI",
   "com.affine.settings.editorSettings.general.default-code-block.language.description": "Set a default programming language.",
   "com.affine.settings.editorSettings.general.default-code-block.language.title": "Code blocks default language",
+  "com.affine.settings.editorSettings.general.default-code-block.line-numbers.description": "Show line numbers in all code blocks by default.",
+  "com.affine.settings.editorSettings.general.default-code-block.line-numbers.title": "Show line numbers in code blocks",
   "com.affine.settings.editorSettings.general.default-code-block.wrap.description": "Encapsulate code snippets for better readability.",
   "com.affine.settings.editorSettings.general.default-code-block.wrap.title": "Wrap code in code blocks",
   "com.affine.settings.editorSettings.general.default-new-doc.description": "Default mode for new doc.",

tests/affine-local/e2e/blocksuite/code/line-numbers.spec.ts

@@ -0,0 +1,192 @@
+import { test } from '@affine-test/kit/playwright';
+import { openHomePage } from '@affine-test/kit/utils/load-page';
+import {
+  addCodeBlock,
+  waitForEditorLoad,
+} from '@affine-test/kit/utils/page-logic';
+import {
+  closeSettingModal,
+  openEditorSetting,
+} from '@affine-test/kit/utils/setting';
+import { expect, type Page } from '@playwright/test';
+
+import { initCodeBlockByOneStep, openCodeBlockMoreMenu } from './utils';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Opens Editor Settings and returns a locator for the
+ * "Show line numbers in code blocks" toggle switch.
+ */
+async function openLineNumbersSetting(page: Page) {
+  await openEditorSetting(page);
+  return page.getByTestId('code-block-line-numbers-trigger');
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+test.describe('Global code block line numbers setting', () => {
+  test('line numbers are visible by default', async ({ page }) => {
+    await initCodeBlockByOneStep(page);
+
+    const lineNumber = page.locator('affine-code .line-number');
+    await expect(lineNumber).toBeVisible();
+  });
+
+  test('global toggle hides line numbers on all existing code blocks', async ({
+    page,
+  }) => {
+    await initCodeBlockByOneStep(page);
+
+    const lineNumber = page.locator('affine-code .line-number');
+    await expect(lineNumber).toBeVisible();
+
+    // Turn the global setting OFF
+    const toggle = await openLineNumbersSetting(page);
+    await expect(toggle).toBeVisible();
+    await toggle.click();
+    await closeSettingModal(page);
+
+    // Line numbers must now be hidden
+    await expect(lineNumber).toBeHidden();
+  });
+
+  test('turning global toggle back on restores line numbers', async ({
+    page,
+  }) => {
+    await initCodeBlockByOneStep(page);
+
+    const lineNumber = page.locator('affine-code .line-number');
+
+    // OFF
+    const toggle = await openLineNumbersSetting(page);
+    await toggle.click();
+    await closeSettingModal(page);
+    await expect(lineNumber).toBeHidden();
+
+    // ON again
+    const toggle2 = await openLineNumbersSetting(page);
+    await toggle2.click();
+    await closeSettingModal(page);
+    await expect(lineNumber).toBeVisible();
+  });
+
+  test('per-block toggle shows line numbers when global is off', async ({
+    page,
+  }) => {
+    await initCodeBlockByOneStep(page);
+
+    const lineNumber = page.locator('affine-code .line-number');
+
+    // Turn global setting OFF
+    const toggle = await openLineNumbersSetting(page);
+    await toggle.click();
+    await closeSettingModal(page);
+    await expect(lineNumber).toBeHidden();
+
+    // Per-block: explicitly enable for this block
+    const { lineNumberButton } = await openCodeBlockMoreMenu(page);
+    await lineNumberButton.click();
+    await expect(lineNumber).toBeVisible();
+  });
+
+  test('per-block toggle can hide line numbers when global is on', async ({
+    page,
+  }) => {
+    await initCodeBlockByOneStep(page);
+
+    const lineNumber = page.locator('affine-code .line-number');
+    // Global is ON by default
+    await expect(lineNumber).toBeVisible();
+
+    // Per-block: hide for this block
+    const { cancelLineNumberButton } = await openCodeBlockMoreMenu(page);
+    await cancelLineNumberButton.click();
+    // Click away to dismiss menu
+    await page.mouse.click(300, 300);
+    await expect(lineNumber).toBeHidden();
+
+    // Turn global setting OFF and then ON - per-block override persists
+    const toggle = await openLineNumbersSetting(page);
+    await toggle.click(); // OFF
+    await toggle.click(); // ON
+    await closeSettingModal(page);
+    // Per-block explicitly set to false - still hidden
+    await expect(lineNumber).toBeHidden();
+  });
+
+  test('global setting is reflected on newly created code blocks', async ({
+    page,
+  }) => {
+    // Start on the home page and disable line numbers globally first
+    await openHomePage(page);
+    await waitForEditorLoad(page);
+
+    const toggle = await openLineNumbersSetting(page);
+    await toggle.click(); // OFF
+    await closeSettingModal(page);
+
+    // Now create a fresh code block
+    await initCodeBlockByOneStep(page);
+
+    const lineNumber = page.locator('affine-code .line-number');
+    await expect(lineNumber).toBeHidden();
+  });
+
+  test('global toggle affects all code blocks on the page', async ({
+    page,
+  }) => {
+    await initCodeBlockByOneStep(page);
+
+    // Exit the code block (Mod+Enter creates a paragraph below and moves focus there)
+    const isMac = process.platform === 'darwin';
+    await page.keyboard.press(isMac ? 'Meta+Enter' : 'Control+Enter');
+    // Add a second code block in the new paragraph
+    await addCodeBlock(page);
+
+    // Both blocks should show line numbers by default
+    const lineNumbers = page.locator('affine-code .line-number');
+    await expect(lineNumbers).toHaveCount(2);
+    await expect(lineNumbers.first()).toBeVisible();
+    await expect(lineNumbers.last()).toBeVisible();
+
+    // Turn global OFF - both must hide
+    const toggle = await openLineNumbersSetting(page);
+    await toggle.click();
+    await closeSettingModal(page);
+
+    await expect(lineNumbers.first()).toBeHidden();
+    await expect(lineNumbers.last()).toBeHidden();
+
+    // Turn global ON - both must show again
+    const toggle2 = await openLineNumbersSetting(page);
+    await toggle2.click();
+    await closeSettingModal(page);
+
+    await expect(lineNumbers.first()).toBeVisible();
+    await expect(lineNumbers.last()).toBeVisible();
+  });
+
+  test('global setting persists across page reload', async ({ page }) => {
+    await initCodeBlockByOneStep(page);
+
+    const lineNumber = page.locator('affine-code .line-number');
+    await expect(lineNumber).toBeVisible();
+
+    // Turn global OFF
+    const toggle = await openLineNumbersSetting(page);
+    await toggle.click();
+    await closeSettingModal(page);
+    await expect(lineNumber).toBeHidden();
+
+    // Reload the page - setting must survive
+    await page.reload();
+    await waitForEditorLoad(page);
+
+    await expect(lineNumber).toBeHidden();
+  });
+});

tests/affine-local/e2e/blocksuite/code/utils.ts

@@ -21,3 +21,26 @@ export const initCodeBlockByOneStep = async (page: Page) => {
   await gotoContentFromTitle(page);
   await addCodeBlock(page);
 };
+
+/**
+ * Opens the "More" menu on the first code block and returns locators for
+ * the line-number toggle buttons inside it.
+ * Uses .first() to stay deterministic when multiple code blocks are present.
+ */
+export const openCodeBlockMoreMenu = async (page: Page) => {
+  const codeBlock = page.locator('affine-code').first();
+  await codeBlock.hover();
+
+  const moreButton = page
+    .locator('affine-code-toolbar')
+    .getByRole('button', { name: 'More' });
+  await moreButton.click();
+
+  const menu = page.locator('.more-popup-menu');
+  const lineNumberButton = menu.getByRole('button', { name: 'Line number' });
+  const cancelLineNumberButton = menu.getByRole('button', {
+    name: 'Cancel line number',
+  });
+
+  return { menu, lineNumberButton, cancelLineNumberButton };
+};