@bloklabs/angular 1.7.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloklabs/angular",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Angular block editor — official Angular bindings for Blok, the headless Notion-like rich text editor. Standalone components that render blocks and save to JSON (APF partial-Ivy bundle).",
   "license": "Apache-2.0",
   "author": "JackUait",
@@ -36,7 +36,7 @@
     "@angular/common": ">=20 <23",
     "@angular/core": ">=20 <23",
     "@angular/forms": ">=20 <23",
-    "@bloklabs/core": "1.7.0"
+    "@bloklabs/core": "1.9.0"
   },
   "module": "fesm2022/bloklabs-angular.mjs",
   "typings": "./index.d.ts",

package/types/bloklabs-angular.d.ts

@@ -1,7 +1,7 @@
 import * as i0 from '@angular/core';
-import { AfterViewInit, EventEmitter, OnDestroy, InjectionToken, EnvironmentProviders, Type, Signal, ElementRef } from '@angular/core';
+import { AfterViewInit, DoCheck, EventEmitter, OnDestroy, InjectionToken, EnvironmentProviders, Type, Signal, ElementRef } from '@angular/core';
 import { ControlValueAccessor } from '@angular/forms';
-import { BlokConfig, EditorWidth, Blok, OutputData, API, BlockMutationEvent, ResolvedTheme, BlocksRenderedPayload, BlockRenderedPayload, OutputBlockData, ThemeMode, LooseOutputData, BlockToolData, BlockTuneData, MarkdownImportConfig, ToolboxConfig, BlockAPI, BlockToolConstructorOptions } from '@bloklabs/core';
+import { BlokConfig, EditorWidth, Blok, OutputData, API, BlockMutationEvent, ResolvedTheme, BlocksRenderedPayload, BlockRenderedPayload, OutputBlockData, ThemeMode, LooseOutputData, BlockToolData, BlockTuneData, MarkdownImportConfig, BlockOrigin, BlockToolConstructable, ToolboxConfig, BlockAPI, BlockToolConstructorOptions } from '@bloklabs/core';
 
 /**
  * Configuration for the Angular adapter. Same as `BlokConfig` but without
@@ -26,15 +26,15 @@ type BlokAngularConfig = Omit<BlokConfig, 'holder'> & {
  * `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.
+ * through `editor.render()` (content-deduped via `equalsOutputData`); everything
+ * else seeds construction.
  *
  * Implementation note: classic `@Input()`/`@ViewChild()` decorators are used
  * (not signal `input()`/`viewChild()`) for JIT compatibility — see
  * `BlokContentDirective`. Each reactive input is backed by an internal `signal`
  * so effect-based syncing still works; the public template API is unchanged.
  */
-declare class BlokEditorComponent implements AfterViewInit, ControlValueAccessor {
+declare class BlokEditorComponent implements AfterViewInit, DoCheck, ControlValueAccessor {
     private readonly ngZone;
     /** App-wide defaults from `provideBlok()`; merged UNDER per-instance inputs. */
     private readonly defaults;
@@ -124,9 +124,12 @@ declare class BlokEditorComponent implements AfterViewInit, ControlValueAccessor
     /** Changing this input's identity destroys and recreates the editor (≙ React `deps`). */
     recreateKey: unknown;
     /**
-     * Content the editor currently reflects. Set when seeded or rendered (the data
-     * effect below). A controlled `data` echo that deep-equals this baseline is a
-     * no-op, so it won't clobber the caret. Renders are serialized via `renderChain`.
+     * Content the editor currently reflects. Set when seeded, when the data effect
+     * renders, when the editor emits its own output (`coreOnSave`) and when the
+     * imperative `render()` facade lands. A controlled `data` echo that
+     * content-equals this baseline is a no-op, so it won't clobber the caret.
+     * Renders are serialized via `renderChain`. `undefined` means "nothing recorded
+     * yet" — never an empty document.
      */
     private lastRenderedData?;
     /** Last token set pushed through `tokens.set`, for deep-equal deduping. */
@@ -148,8 +151,40 @@ declare class BlokEditorComponent implements AfterViewInit, ControlValueAccessor
      * it straight back into `data` deep-equals the baseline and is deduped to a
      * no-op (no redundant render, no caret reset). Re-enters the Angular zone since
      * the editor runs outside it.
+     *
+     * Falls back to an escape-hatch `[config]` callback when nothing Angular-side
+     * consumes the save — the baseline is recorded either way, so the controlled
+     * `data` dedupe works on both paths.
      */
     private readonly coreOnSave;
+    /**
+     * Stable wrappers for the remaining live callbacks. Each resolves its target
+     * at call time (an observed output, else the `[config]` escape hatch), so a
+     * pushed handler never goes stale and only PRESENCE has to be synced.
+     */
+    private readonly coreOnChange;
+    private readonly coreOnAfterRender;
+    private readonly coreOnBeforeRender;
+    private readonly coreOnEnter;
+    private readonly coreOnSubmit;
+    /** provideBlok defaults merged under the `[config]` escape hatch. */
+    private escapeHatchConfig;
+    /** True when an output, a two-way binding or Angular forms consumes `onSave`. */
+    private hasSaveConsumer;
+    /**
+     * The live callbacks this component currently wires into core, keyed by
+     * handler name — `undefined` for the ones nothing consumes.
+     *
+     * PRESENCE is the semantics in core (an `onSubmit` turns Enter into
+     * serialize-and-submit, an `onSave` arms the change-observation pipeline), so
+     * an unconsumed callback must stay absent. One source of truth for both the
+     * construction config and the runtime sync in `ngDoCheck`, so the two cannot
+     * drift.
+     * @returns the wrappers to install, `undefined` where nothing is wired
+     */
+    private liveHandlers;
+    /** Handler presence installed on the live editor (the sync dedupe baseline). */
+    private appliedHandlers;
     /** Live Blok instance, or null until `isReady` resolves / after destroy. */
     readonly instance: i0.Signal<Blok | null>;
     /** Guards `ready` to one emission per editor instance. */
@@ -161,11 +196,38 @@ declare class BlokEditorComponent implements AfterViewInit, ControlValueAccessor
      */
     buildConfig(): Partial<BlokAngularConfig>;
     ngAfterViewInit(): void;
+    /**
+     * Reactive callback presence.
+     *
+     * Callback wiring was decided once, at construction, and in core the presence
+     * of a handler IS the semantics: an `onSubmit` makes Enter serialize-and-submit
+     * instead of splitting the block, an `onSave` arms the whole change-observation
+     * pipeline. A `[config]` swap, an `*ngIf`-gated `(save)` output or a
+     * `registerOnChange` from Angular forms arriving after mount therefore needed a
+     * `recreateKey` bump — destroying the editor and losing caret and undo history.
+     *
+     * Diff the wired handlers against what is installed and push genuine flips
+     * through the runtime `handlers.set` API, writing `undefined` for a handler
+     * that lost its consumer so the change stays reversible. `ngDoCheck` (not an
+     * `effect`) because `EventEmitter.observed` and the plain `@Input` transforms
+     * are not signals; the comparison is six identity checks against stable
+     * wrappers, so an unchanged cycle pushes nothing.
+     */
+    ngDoCheck(): void;
     /** Serialize the current content. Resolves undefined until the editor is ready. */
     save$(): Promise<OutputData> | undefined;
     /** Move the caret into the editor. */
     focus(atEnd?: boolean): void;
-    /** Replace the editor content. Resolves undefined until the editor is ready. */
+    /**
+     * Replace the editor content. Resolves undefined until the editor is ready.
+     *
+     * Safe to mix with a controlled `[data]` input: the rendered document becomes
+     * the content baseline once the call lands, so a later `[data]` change back to
+     * the previous document still re-renders instead of being deduped against a
+     * baseline the editor no longer reflects. Recorded only on the resolved path —
+     * a failed render leaves the editor on its previous content.
+     * @param data - the document to render
+     */
     render(data: OutputData | LooseOutputData): Promise<void> | undefined;
     constructor();
     /** Seeds/renders an externally-set form value through the same dedup machinery. */
@@ -597,6 +659,37 @@ interface PropSchemaEntry {
  */
 type PropSchema = Record<string, PropSchemaEntry>;
 
+/**
+ * Every STATIC member of core's block-tool contract an Angular block may declare
+ * for itself — `ownsChildren`, `keepsChildrenOnEnter`, `conversionConfig`,
+ * `pasteConfig`, `sanitize`, `shortcut`, `upgradeData`, and whatever core adds
+ * next. Derived from
+ * `BlockToolConstructable` rather than enumerated, so a new core static needs no
+ * adapter change to become reachable.
+ *
+ * `toolbox` and `isReadOnlySupported` are excluded because the factory owns
+ * them: `toolbox` is authored as {@link CreateAngularBlockSpec.toolbox}, and
+ * in-place read-only support is unconditional.
+ */
+type BlockToolStatics = Omit<BlockToolConstructable, 'toolbox' | 'isReadOnlySupported'>;
+/**
+ * Second argument of {@link CreateAngularBlockSpec.onMounted} and
+ * {@link CreateAngularBlockSpec.onCreated} — everything the block cannot read
+ * off its own `BlockAPI`.
+ */
+interface AngularBlockMountedContext {
+    /**
+     * Why this block instance was constructed: a CREATION origin (`user`, `api`,
+     * `convert`) means the author just made it, so seeding default children is
+     * correct; a RESTORE origin (`load`, `replay`, `paste`) means the document
+     * already says what the children are. `probe` is an off-tree instance built
+     * only to read a tool's default data — it must not touch the block tree at
+     * all. Defaults to `'api'` when the constructor was handed no origin.
+     */
+    origin: BlockOrigin;
+    /** The editor-level API (`api.blocks`, `api.caret`, `api.events`…). */
+    api: API;
+}
 /** Spec for {@link createAngularBlock}. Authored as a standalone component. */
 interface CreateAngularBlockSpec<Data = BlockToolData> {
     /** Tool type name (registered key). */
@@ -610,8 +703,90 @@ interface CreateAngularBlockSpec<Data = BlockToolData> {
      * per-block context via `inject(BLOK_BLOCK_CONTEXT)`.
      */
     component: Type<unknown>;
+    /**
+     * Static members of core's tool contract, forwarded verbatim onto the
+     * generated tool class — the single channel for everything core reads off the
+     * CLASS rather than the instance (`ownsChildren`, `keepsChildrenOnEnter`,
+     * `conversionConfig`, `pasteConfig`, `sanitize`, `shortcut`, `upgradeData`…).
+     * Without it the only way to declare one was to subclass the generated class.
+     *
+     * `keepsChildrenOnEnter` is the per-tool Enter POLICY: declare it and Enter on
+     * this container's empty LAST child creates the new line INSIDE the container
+     * instead of escaping to the container's parent (Blok's default, which is
+     * Notion's callout behaviour). Core cannot read that off the DOM — a callout
+     * renders the same `data-blok-nested-blocks` slot as a column yet wants the
+     * escape — so before it existed a layout container (a card, a `steps` block)
+     * had to hijack the editor-global `config.onEnter` and re-derive containment.
+     *
+     * `toolbox` and `isReadOnlySupported` are owned by the factory and cannot be
+     * overridden here (see {@link BlockToolStatics}).
+     */
+    statics?: BlockToolStatics;
+    /**
+     * The element the +/drag toolbar should vertically center on — core's
+     * `getToolbarAnchorElement` hook, resolved against this block's host element
+     * on every call (never cached, so it tracks re-renders).
+     *
+     * A container block whose own chrome is not editable needs it: with no anchor,
+     * core centers the toolbar on the first `[contenteditable]` under the host,
+     * which for a container is its FIRST CHILD BLOCK. Return `null`/`undefined`
+     * (or omit the field) to keep core's default.
+     * @param host - this block's mutation-free host element
+     * @param block - this block's per-block API
+     */
+    getToolbarAnchorElement?: (host: HTMLElement, block: BlockAPI) => HTMLElement | null | undefined;
     /** Optional lifecycle callbacks mapped from Blok's block hooks. */
     onRendered?: (block: BlockAPI) => void;
+    /**
+     * Fired ONCE per block instance, once the component's DOM (and, for a
+     * container, the child holders its `ctx.mountChildren` adopted) exists.
+     * Angular mounts the block synchronously while core is still inside
+     * `render()`, so this lands with `rendered()` — the first hook at which the
+     * host is also in the document. The React and Vue adapters spell the same
+     * contract; there it is genuinely LATER than `onRendered`, because their
+     * portals commit a frame after core returns.
+     *
+     * It is also the create-vs-restore signal: `context.origin` says whether the
+     * author just made this block (`user`/`api`/`convert`) or the document is
+     * being re-materialised (`load`/`replay`/`paste`) — so a container can seed
+     * its default children here exactly once, without the "children are
+     * transiently empty during a replay" trap.
+     * @example
+     * ```ts
+     * onMounted: (block, { origin, api }) => {
+     *   if (origin === 'user' && block.getChildren().length === 0) {
+     *     api.blocks.insertInsideParent(block.id);
+     *   }
+     * }
+     * ```
+     */
+    onMounted?: (block: BlockAPI, context: AngularBlockMountedContext) => void;
+    /**
+     * The SEEDING hook: `onMounted`, narrowed to a genuine creation. Fired ONCE
+     * per block instance, once the component's DOM exists, and only when this
+     * instance is the author making a new block (`origin` of `user`, `api` or
+     * `convert`) — never for a `load`/`replay`/`paste` restore, and never for the
+     * off-tree `probe` instance core builds to read a tool's default data.
+     *
+     * That predicate is why the hook exists rather than leaving every block to
+     * read `context.origin` in `onMounted`: the intuitive `origin === 'user'` test
+     * is wrong. It drops `api.blocks.insert('steps')` and turn-into, so a
+     * container seeded that way comes up empty for every path except a keystroke.
+     * Core refused to ship that axis into its own `column`/`column_list`; this
+     * encodes the correct one once, here.
+     *
+     * The `context` is the same object {@link CreateAngularBlockSpec.onMounted}
+     * receives, so a block that only seeds can read `origin` for finer decisions.
+     * @example
+     * ```ts
+     * onCreated: (block, { api }) => {
+     *   if (block.getChildren().length === 0) {
+     *     api.blocks.insertInsideParent(block.id);
+     *   }
+     * }
+     * ```
+     */
+    onCreated?: (block: BlockAPI, context: AngularBlockMountedContext) => void;
     onMoved?: (block: BlockAPI) => void;
     onRemoved?: (block: BlockAPI) => void;
 }
@@ -636,11 +811,12 @@ declare function createAngularBlock<Data = BlockToolData>(spec: CreateAngularBlo
     save(): BlockToolData;
     setData(newData: BlockToolData): Promise<boolean>;
     setReadOnly(state: boolean): void;
+    getToolbarAnchorElement(): HTMLElement | undefined;
     rendered(): void;
     moved(): void;
     removed(): void;
     destroy(): void;
-}) & {
+}) & BlockToolStatics & {
     readonly __isBlokAngularBlock: true;
     readonly toolbox: ToolboxConfig | undefined;
     readonly isReadOnlySupported: boolean;
@@ -723,6 +899,14 @@ interface InjectBlokReadyOptions {
  */
 declare function injectBlokReady(options?: InjectBlokReadyOptions): Signal<boolean>;
 
+/**
+ * One child's decoration: attribute name → value. `null`/`undefined` removes the
+ * attribute; a boolean or number is stringified (so `false` writes
+ * `data-active="false"`, which CSS can select, rather than dropping the hook).
+ */
+type ChildAttributes = Record<string, string | number | boolean | null | undefined>;
+/** The per-child decorator accepted by {@link AngularBlockRenderContext.mountChildren}. */
+type ChildAttributesFn = (child: BlockAPI, index: number) => ChildAttributes;
 /**
  * Context handed to a `createAngularBlock` component. Delivered via DI (the
  * BLOK_BLOCK_CONTEXT token) rather than @Input, because core constructs the tool
@@ -736,6 +920,17 @@ interface AngularBlockRenderContext<Data> {
     commit: (patch: Partial<Data>) => void;
     /** This block's per-block API (id, getChildren, dispatchChange…). */
     block: BlockAPI;
+    /**
+     * The EDITOR-level API this block belongs to (`api.blocks`, `api.caret`,
+     * `api.toolbar`…) — the same object a vanilla tool receives in its
+     * constructor. Reach for it when a block has to drive the document around it
+     * instead of routing everything through `block.call()` string dispatch.
+     *
+     * For the reactive, id/parentId-relative view of the tree (and to re-render
+     * when your own children change), pair `injectBlocks` with
+     * `injectBlokInstance()` instead — the api handle itself is not reactive.
+     */
+    api: API;
     /**
      * Reactive read-only flag. Read `readOnly()` in the template to disable
      * editing (drop `contenteditable`, hide controls). Toggled IN PLACE by core's
@@ -749,11 +944,57 @@ interface AngularBlockRenderContext<Data> {
      * (a `data-blok-nested` element the author owns). Call it once in
      * `ngAfterViewInit`; the factory re-runs the same mount on every data change
      * so late-added children appear. Angular must NOT manage these child holders.
+     *
+     * `childAttributes` decorates each child's HOLDER after the holders are
+     * mounted, and is REMEMBERED — every later remount re-applies it. Named hooks
+     * (`data-step-index`, `data-active`…) replace positional `:nth-child()` CSS
+     * over Blok's holders, which breaks the moment a child is inserted, removed or
+     * reordered. The holders stay DIRECT children of `host` — core requires that
+     * (hierarchy reparenting and caret navigation compare `holder.parentElement`
+     * by identity), so decoration is attributes, never wrapper elements.
+     * Attributes the callback stops producing are removed on the next pass.
+     *
+     * Writing on a child's holder is inert by design: core's mutation filter drops
+     * a holder-targeted attribute record for the child block and suppresses it for
+     * the container. The guarantee stops at the holder and its
+     * `[data-blok-element-content]` wrapper — writing AT or BELOW a child's tool
+     * root DOES score as that child's edit.
      */
-    mountChildren: (host: HTMLElement) => void;
+    mountChildren: (host: HTMLElement, childAttributes?: ChildAttributesFn) => void;
 }
 /** DI token carrying the per-block render context into the authored component. */
 declare const BLOK_BLOCK_CONTEXT: InjectionToken<AngularBlockRenderContext<unknown>>;
 
-export { BLOK_BLOCK_CONTEXT, BLOK_DEFAULT_CONFIG, BlokContentDirective, BlokEditorComponent, createAngularBlock, injectBlocks, injectBlokReady, provideBlok };
-export type { AngularBlockRenderContext, BlockNode, BlokAngularConfig, BlokReadyScope, CaretTarget, CreateAngularBlockSpec, InjectBlokReadyOptions, InsertPosition, InsertSpec, MoveTarget, PropSchema, PropSchemaEntry, TreeInsertSpec, UseBlocksApi };
+/**
+ * DI token carrying the LIVE editor instance (as a signal) into every block
+ * mounted by `createAngularBlock`. `BlokContentDirective` publishes its own
+ * `instance` signal through it, so the value is null before the editor is ready
+ * and after teardown — matching the React/Vue adapters' pre-ready contract.
+ *
+ * Provided on the block's ELEMENT injector by the portal registry, so it is
+ * per-EDITOR: two editors on one page each publish their own instance.
+ */
+declare const BLOK_EDITOR_INSTANCE: InjectionToken<Signal<Blok | null>>;
+/**
+ * The live Blok instance the component is mounted inside, as a signal, or a
+ * signal of null before it exists. Inside a `createAngularBlock` component this
+ * is the block's OWN editor — so a block can drive the tree it lives in without
+ * the host prop-drilling the instance into it:
+ *
+ * ```ts
+ * private readonly editor = injectBlokInstance();
+ * private readonly blocks = injectBlocks(this.editor);
+ * ```
+ *
+ * That pairing is also what makes a container block REACTIVE to its own child
+ * tree: `injectBlocks` refreshes on the editor's `block changed` event, which
+ * core emits for every structural mutation — including children the adapter
+ * itself never sees (a pasted paragraph, a Tab-indent from the keyboard).
+ *
+ * Call it in an injection context (a field initializer or the constructor).
+ * Outside an editor it returns a signal of null.
+ */
+declare function injectBlokInstance(): Signal<Blok | null>;
+
+export { BLOK_BLOCK_CONTEXT, BLOK_DEFAULT_CONFIG, BLOK_EDITOR_INSTANCE, BlokContentDirective, BlokEditorComponent, createAngularBlock, injectBlocks, injectBlokInstance, injectBlokReady, provideBlok };
+export type { AngularBlockMountedContext, AngularBlockRenderContext, BlockNode, BlockToolStatics, BlokAngularConfig, BlokReadyScope, CaretTarget, ChildAttributes, ChildAttributesFn, CreateAngularBlockSpec, InjectBlokReadyOptions, InsertPosition, InsertSpec, MoveTarget, PropSchema, PropSchemaEntry, TreeInsertSpec, UseBlocksApi };