@bloklabs/angular 1.3.0 → 1.4.0

package/README.md

@@ -0,0 +1,65 @@
+# @bloklabs/angular
+
+The Angular block editor bindings for [Blok](https://blokeditor.com) — a headless, Notion-like rich text editor whose content is JSON blocks, not HTML.
+
+## Install
+
+```bash
+npm install @bloklabs/angular @bloklabs/core
+```
+
+`@bloklabs/core` and `@angular/core` / `@angular/common` / `@angular/forms` are peer dependencies.
+
+## Usage
+
+`BlokEditorComponent` is a standalone component: it mounts the editor, manages its lifecycle, and takes every editor config option as an input.
+
+```typescript
+import { Component } from '@angular/core';
+import { BlokEditorComponent } from '@bloklabs/angular';
+import { Header, Paragraph, List } from '@bloklabs/core/tools';
+
+@Component({
+  selector: 'app-editor',
+  standalone: true,
+  imports: [BlokEditorComponent],
+  template: `<blok-editor [tools]="tools" />`,
+})
+export class EditorComponent {
+  tools = {
+    paragraph: Paragraph,
+    header: { class: Header, placeholder: 'Enter a heading' },
+    list: List,
+  };
+}
+```
+
+## Saving
+
+The `(save)` output fires with the latest content on every change, so you never have to call `save()` by hand.
+
+```typescript
+import type { OutputData } from '@bloklabs/core';
+
+// template: <blok-editor [tools]="tools" (save)="onSave($event)" />
+onSave(data: OutputData) {
+  console.log(data.blocks);
+}
+```
+
+The component also implements `ControlValueAccessor`, so it works with `[(ngModel)]` and reactive forms.
+
+## Also exported
+
+- `BlokContentDirective` (`[blokContent]`) — the mount point, if you drive the editor yourself.
+- `injectBlocks()` — a reactive snapshot of the block tree plus a manipulation API.
+- `createAngularBlock` — author block tools as Angular components.
+- `provideBlok` / `BLOK_DEFAULT_CONFIG` — share default editor config through DI.
+
+## Docs
+
+- [Quick start](https://blokeditor.com/docs/quick-start?framework=angular)
+- [`BlokEditor` reference](https://blokeditor.com/docs/blok-editor?framework=angular)
+- [`useBlocks` reference](https://blokeditor.com/docs/use-blocks?framework=angular)
+
+Licensed under Apache-2.0.

package/fesm2022/bloklabs-angular.mjs

@@ -1754,9 +1754,15 @@ const DATA_ATTR = {
     /** Editor or element is empty */
     empty: 'data-blok-empty',
     /** Present on the editor wrapper while read-only mode is active.
-     *  Public styling hook — lets hosts (and Blok's own CSS, e.g. the
-     *  gutter auto-collapse) key rules off the editing state without JS. */
+     *  Public styling hook — lets hosts key rules off the editing state
+     *  without JS. Deliberately does NOT collapse the gutter: plain
+     *  read-only still shows the block-hover copy-link control there, and
+     *  in-place readOnly.set() flips must not shift the layout. */
     readonly: 'data-blok-readonly',
+    /** Present on the editor wrapper while read-only mode hides ALL editor
+     *  controls (readOnly: { hideControls: true }). Public styling hook —
+     *  drives the gutter auto-collapse for genuinely chromeless read-only. */
+    controlsHidden: 'data-blok-controls-hidden',
     /** Present on the editor wrapper when config.hideToolbar is true.
      *  Public styling hook — drives the gutter auto-collapse (the gutter
      *  exists solely to house the toolbar's +/⠿ controls). */
@@ -2067,8 +2073,16 @@ const mountChildBlocks = (container, children) => {
  * `BlokEditor`). Delegates instance lifecycle to an internal `BlokContentDirective`
  * and layers the typed reactive input/output API on top.
  *
- * Reactive inputs (`readOnly`, `theme`, `width`, `placeholder`, `autofocus`) are
- * synced in place after mount via effects; everything else seeds construction.
+ * Reactive inputs (`readOnly`, `hideToolbar`, `inlineToolbar`, `theme`,
+ * `width`, `placeholder`, `autofocus`, `styleTokens`, `i18n`, `data`) are
+ * synced in place after mount via effects — `hideToolbar` through
+ * `editor.toolbar.setHidden()`, `inlineToolbar` through
+ * `editor.tools.setInlineToolbar()` (content-compared),
+ * `styleTokens` through `editor.tokens.set()` (replace semantics),
+ * `i18n` through `editor.i18n.update()` (deep-equal–deduped; seeded at
+ * construction so the locale resolves during boot) and `data`
+ * through `editor.render()` (deep-equal–deduped); everything else seeds
+ * construction.
  *
  * Implementation note: classic `@Input()`/`@ViewChild()` decorators are used
  * (not signal `input()`/`viewChild()`) for JIT compatibility — see
@@ -2117,11 +2131,24 @@ class BlokEditorComponent {
     // ---- Reactive inputs (signal-backed setters; synced in place, never recreate) ----
     // Default undefined (not false) so an unset input falls back to a provideBlok
     // default; the readOnly effect / buildConfig coerce undefined to false.
+    // Accepts the object form (`{ hideControls }`) too — it flows through
+    // buildConfig unchanged and the effect expands it to
+    // `readOnly.set(enabled, { hideControls })`.
     readOnly$ = signal(undefined, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "readOnly$" }] : /* istanbul ignore next */ []));
     set readOnly(value) {
         this.readOnly$.set(value);
     }
+    hideToolbar$ = signal(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "hideToolbar$" }] : /* istanbul ignore next */ []));
+    set hideToolbar(value) {
+        this.hideToolbar$.set(value);
+    }
+    inlineToolbar$ = signal(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "inlineToolbar$" }] : /* istanbul ignore next */ []));
+    set inlineToolbar(value) {
+        this.inlineToolbar$.set(value);
+    }
     theme$ = signal(undefined, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "theme$" }] : /* istanbul ignore next */ []));
     set theme(value) {
@@ -2147,6 +2174,18 @@ class BlokEditorComponent {
     set styleTokens(value) {
         this.styleTokens$.set(value);
     }
+    /**
+     * Locale, host message overrides and text direction. `config.i18n` was
+     * consumed once at boot, so a host driving a language switcher had to
+     * recreate the editor (losing caret, focus and undo stack) to relabel the
+     * UI; this drives the runtime `i18n.update` API instead. `defaultLocale` is
+     * not forwarded — it only affects the INITIAL locale resolution.
+     */
+    i18n$ = signal(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "i18n$" }] : /* istanbul ignore next */ []));
+    set i18n(value) {
+        this.i18n$.set(value);
+    }
     autofocus$ = signal(false, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "autofocus$" }] : /* istanbul ignore next */ []));
     set autofocus(value) {
@@ -2162,7 +2201,7 @@ class BlokEditorComponent {
     tools;
     /**
      * Escape hatch: a full config object for keys without a dedicated input
-     * (i18n, sanitizer, minHeight, inlineToolbar, …). Layered between provideBlok
+     * (sanitizer, minHeight, …). Layered between provideBlok
      * defaults and the discrete inputs.
      */
     config;
@@ -2176,6 +2215,12 @@ class BlokEditorComponent {
     lastRenderedData;
     /** Last token set pushed through `tokens.set`, for deep-equal deduping. */
     appliedTokens;
+    /** Last i18n config pushed through `i18n.update`, for deep-equal deduping. */
+    appliedI18n;
+    /** Editor instance the i18n baseline above belongs to. */
+    i18nAppliedFor = null;
+    /** Last value pushed through `tools.setInlineToolbar`, for content-compare deduping. */
+    appliedInlineToolbar;
     seededEditor = null;
     renderChain = Promise.resolve();
     /** Registered by `ControlValueAccessor.registerOnChange` (Angular forms). */
@@ -2210,7 +2255,17 @@ class BlokEditorComponent {
     buildConfig() {
         // Precedence: provideBlok defaults < [config] escape hatch < discrete inputs.
         const cfg = { ...this.defaults, ...this.config };
+        // The object form ({ hideControls }) is preserved as-is; the readOnly
+        // effect expands it into `readOnly.set(enabled, { hideControls })`.
         cfg.readOnly = this.readOnly$() ?? this.config?.readOnly ?? this.defaults.readOnly ?? false;
+        const hideToolbar = this.hideToolbar$();
+        if (hideToolbar !== undefined) {
+            cfg.hideToolbar = hideToolbar;
+        }
+        const inlineToolbar = this.inlineToolbar$();
+        if (inlineToolbar !== undefined) {
+            cfg.inlineToolbar = inlineToolbar;
+        }
         // tools registries are MERGED (not replaced) across all three layers so a
         // shared registry composes with per-instance additions.
         if (this.tools !== undefined ||
@@ -2234,6 +2289,12 @@ class BlokEditorComponent {
         if (placeholder !== undefined) {
             cfg.placeholder = placeholder;
         }
+        // Seeded at construction (not applied by the i18n effect) so the locale is
+        // resolved during boot instead of flashing the default language first.
+        const i18n = this.i18n$();
+        if (i18n !== undefined) {
+            cfg.i18n = i18n;
+        }
         // Opt-in: only attach each core callback when the consumer actually consumes
         // it (an observed output, a registered forms hook, or a provided transform).
         // Their mere presence makes the core serialize / run hooks on every change.
@@ -2282,11 +2343,39 @@ class BlokEditorComponent {
         // (the Angular analog of React's `editor` effect-dependency).
         effect(() => {
             const editor = this.instance();
-            const readOnly = this.readOnly$();
+            const readOnly = this.readOnly$() ?? this.config?.readOnly;
             if (editor) {
-                void editor.readOnly.set(readOnly ?? normalizeReadOnlyConfig(this.config?.readOnly).enabled);
+                const { enabled, hideControls } = normalizeReadOnlyConfig(readOnly);
+                // Only the object form carries options; the boolean form keeps the
+                // one-argument call so it never clobbers a config-seeded hideControls.
+                if (typeof readOnly === 'object' && readOnly !== null) {
+                    void editor.readOnly.set(enabled, { hideControls });
+                }
+                else {
+                    void editor.readOnly.set(enabled);
+                }
+            }
+        });
+        effect(() => {
+            const editor = this.instance();
+            const hideToolbar = this.hideToolbar$();
+            if (editor && hideToolbar !== undefined) {
+                editor.toolbar.setHidden(hideToolbar);
             }
         });
+        // Content-compared (not identity): a new array with the same tool names is
+        // a no-op, so template-inline array literals don't thrash the assignment.
+        effect(() => {
+            const editor = this.instance();
+            const inlineToolbar = this.inlineToolbar$();
+            if (!editor ||
+                inlineToolbar === undefined ||
+                deepEqual(inlineToolbar, this.appliedInlineToolbar)) {
+                return;
+            }
+            this.appliedInlineToolbar = Array.isArray(inlineToolbar) ? [...inlineToolbar] : inlineToolbar;
+            editor.tools.setInlineToolbar(inlineToolbar);
+        });
         effect(() => {
             const editor = this.instance();
             const theme = this.theme$();
@@ -2317,6 +2406,34 @@ class BlokEditorComponent {
             this.appliedTokens = { ...tokens };
             editor.tokens.set(tokens);
         });
+        effect(() => {
+            const editor = this.instance();
+            const i18n = this.i18n$() ?? this.config?.i18n;
+            if (!editor) {
+                return;
+            }
+            /*
+             * A freshly constructed editor already resolved this config during its
+             * own boot (buildConfig seeds it), so record the baseline and push
+             * nothing — re-applying it here would reload the locale after mount and
+             * flash the default language.
+             */
+            if (this.i18nAppliedFor !== editor) {
+                this.i18nAppliedFor = editor;
+                this.appliedI18n = i18n === undefined ? undefined : { ...i18n };
+                return;
+            }
+            if (i18n === undefined || deepEqual(i18n, this.appliedI18n)) {
+                return;
+            }
+            this.appliedI18n = { ...i18n };
+            const { locale, messages, direction } = i18n;
+            void editor.i18n.update({
+                ...(locale === undefined ? {} : { locale }),
+                ...(messages === undefined ? {} : { messages }),
+                ...(direction === undefined ? {} : { direction }),
+            });
+        });
         effect(() => {
             const editor = this.instance();
             if (editor && this.autofocus$()) {
@@ -2397,7 +2514,7 @@ class BlokEditorComponent {
         this.readOnly$.set(isDisabled);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: BlokEditorComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "22.0.7", type: BlokEditorComponent, isStandalone: true, selector: "blok-editor", inputs: { onBeforeRender: "onBeforeRender", onBeforePaste: "onBeforePaste", readOnly: "readOnly", theme: "theme", width: "width", placeholder: "placeholder", styleTokens: "styleTokens", autofocus: "autofocus", data: "data", tools: "tools", config: "config", recreateKey: "recreateKey" }, outputs: { ready: "ready", dataChange: "dataChange", save: "save", change: "change", afterRender: "afterRender", themeChange: "themeChange", blocksRendered: "blocksRendered", blockRendered: "blockRendered" }, providers: [
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "22.0.7", type: BlokEditorComponent, isStandalone: true, selector: "blok-editor", inputs: { onBeforeRender: "onBeforeRender", onBeforePaste: "onBeforePaste", readOnly: "readOnly", hideToolbar: "hideToolbar", inlineToolbar: "inlineToolbar", theme: "theme", width: "width", placeholder: "placeholder", styleTokens: "styleTokens", i18n: "i18n", autofocus: "autofocus", data: "data", tools: "tools", config: "config", recreateKey: "recreateKey" }, outputs: { ready: "ready", dataChange: "dataChange", save: "save", change: "change", afterRender: "afterRender", themeChange: "themeChange", blocksRendered: "blocksRendered", blockRendered: "blockRendered" }, providers: [
             {
                 provide: NG_VALUE_ACCESSOR,
                 useExisting: forwardRef(() => BlokEditorComponent),
@@ -2447,6 +2564,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
                 type: Input
             }], readOnly: [{
                 type: Input
+            }], hideToolbar: [{
+                type: Input
+            }], inlineToolbar: [{
+                type: Input
             }], theme: [{
                 type: Input
             }], width: [{
@@ -2455,6 +2576,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
                 type: Input
             }], styleTokens: [{
                 type: Input
+            }], i18n: [{
+                type: Input
             }], autofocus: [{
                 type: Input
             }], data: [{
@@ -2786,9 +2909,58 @@ function injectBlocks(editor) {
     };
 }
 
+// packages/angular/src/useBlokReady.ts
+/**
+ * Resolves the caller's scope description to an element, or null when it is
+ * not available yet.
+ * @param within - the scope description passed in options
+ */
+function resolveScope(within) {
+    const value = typeof within === 'function' ? within() : within;
+    if (value === null || value === undefined) {
+        return null;
+    }
+    return value instanceof ElementRef ? value.nativeElement : value;
+}
+/**
+ * Angular factory exposing the live readiness of the Blok editors in a DOM
+ * scope as a boolean signal.
+ *
+ * The readiness logic itself is framework-agnostic and lives in core
+ * (`Blok.readyState` / `Blok.subscribeReady`) — the SAME implementation behind
+ * React's and Vue's `useBlokReady`, so the three adapters cannot drift. This
+ * wrapper supplies only Angular's reactivity: a signal re-read on every
+ * registry change, unsubscribed through the injector's `DestroyRef`.
+ *
+ * Call it in an injection context (component constructor / field initializer).
+ * The signal starts `false` and takes its first real reading in
+ * `afterNextRender` — browser-only by contract, and late enough for a
+ * `@ViewChild` scope to exist. Over-waiting is safe; under-waiting is a bug.
+ * @param options - scope and readiness depth
+ */
+function injectBlokReady(options = {}) {
+    const { within, settleOn } = options;
+    const ready = signal(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "ready" }] : /* istanbul ignore next */ []));
+    const read = () => {
+        const scope = within === undefined ? null : resolveScope(within);
+        // A scope that was asked for but has not resolved yet is NOT the global
+        // scope — reporting ready here would gate on the wrong set of editors.
+        ready.set(within !== undefined && scope === null
+            ? false
+            : Blok.readyState({
+                within: scope,
+                settleOn,
+            }).ready);
+    };
+    inject(DestroyRef).onDestroy(Blok.subscribeReady(read));
+    afterNextRender(read);
+    return ready.asReadonly();
+}
+
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { BLOK_BLOCK_CONTEXT, BLOK_DEFAULT_CONFIG, BlokContentDirective, BlokEditorComponent, createAngularBlock, injectBlocks, provideBlok };
+export { BLOK_BLOCK_CONTEXT, BLOK_DEFAULT_CONFIG, BlokContentDirective, BlokEditorComponent, createAngularBlock, injectBlocks, injectBlokReady, provideBlok };
 //# sourceMappingURL=bloklabs-angular.mjs.map