@bloklabs/angular 1.8.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloklabs/angular",
-  "version": "1.8.0",
+  "version": "1.10.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.8.0"
+    "@bloklabs/core": "1.10.0"
   },
   "module": "fesm2022/bloklabs-angular.mjs",
   "typings": "./index.d.ts",

package/types/bloklabs-angular.d.ts

@@ -822,6 +822,28 @@ declare function createAngularBlock<Data = BlockToolData>(spec: CreateAngularBlo
     readonly isReadOnlySupported: boolean;
 };
 
+/** Options for {@link injectBlocks}. */
+interface InjectBlocksOptions {
+    /**
+     * Invalidate reads only for changes inside the subtree rooted at this block id
+     * (the block itself or any descendant). Omit — or pass `null` — for the
+     * document-wide default.
+     *
+     * This bounds REACTIVITY, not reads: the returned API still sees the whole
+     * tree, so a scoped consumer can still `getById` anything. Reach for it in a
+     * container block that renders only its own children — unscoped, such a block
+     * invalidates on every keystroke anywhere in the document, and a page of N
+     * containers turns one keystroke into N re-renders.
+     *
+     * Accepted as a plain value or a signal (like `editor`) and read at EMIT time,
+     * so changing it takes effect immediately with no re-subscription.
+     *
+     * A change whose block cannot be placed in the tree (a removal that emits
+     * after the block is gone) counts as in-scope: skipping it would leave a
+     * container rendering a child that no longer exists.
+     */
+    within?: Signal<string | null> | string | null;
+}
 /**
  * Angular factory exposing an id/parentId-relative, reactive view of the block
  * tree. Reads refresh whenever the editor emits `block changed`; mutators route
@@ -855,8 +877,10 @@ declare function createAngularBlock<Data = BlockToolData>(spec: CreateAngularBlo
  * `ed === sub.editor` makes it a no-op, so no double-subscription occurs.
  *
  * @param editor - a signal of the Blok instance, or null pre-ready
+ * @param options - reactivity options; see {@link InjectBlocksOptions.within} to
+ *   scope invalidation to one block's subtree
  */
-declare function injectBlocks(editor: Signal<Blok | null>): UseBlocksApi;
+declare function injectBlocks(editor: Signal<Blok | null>, options?: InjectBlocksOptions): UseBlocksApi;
 
 /** How the caller names the DOM scope to observe. */
 type BlokReadyScope = (() => Element | ElementRef<Element> | null | undefined) | ElementRef<Element> | Element | null;
@@ -954,13 +978,44 @@ interface AngularBlockRenderContext<Data> {
      * by identity), so decoration is attributes, never wrapper elements.
      * Attributes the callback stops producing are removed on the next pass.
      *
+     * `childContentAttributes` is the same decoration applied one level IN — on
+     * each child's `[data-blok-element-content]` wrapper instead of its holder —
+     * and is remembered the same way. Core's decoration law blesses both, and a
+     * container needs both: the holder is the child's outer box (rails, indices,
+     * hover states), the content wrapper is where the child's own text box begins,
+     * which is what a numbered rail or a connector line has to align to. Reach for
+     * it instead of walking core's wrapper chain from a holder hook (`[data-step] >
+     * [data-blok-element-content] > …`) — those selectors encode engine DOM in host
+     * CSS and break when that structure changes. A child whose DOM has not
+     * committed yet has no wrapper to write to and is stamped 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, childAttributes?: ChildAttributesFn) => void;
+    mountChildren: (host: HTMLElement, childAttributes?: ChildAttributesFn, childContentAttributes?: ChildAttributesFn) => void;
+    /**
+     * Name the element the +/drag toolbar should vertically center on, from inside
+     * the component: `ctx.setToolbarAnchor(this.head().nativeElement)` in
+     * `ngAfterViewInit`. The Angular counterpart of React's/Vue's
+     * `toolbarAnchorRef` — core's `getToolbarAnchorElement` is otherwise a
+     * `(host, block) => Element` hook resolved OUTSIDE the component, so pointing
+     * at an element the template renders meant inventing a data attribute and
+     * `querySelector`-ing for it from
+     * `CreateAngularBlockSpec.getToolbarAnchorElement`.
+     *
+     * A container block whose own chrome is not editable needs an anchor: with
+     * none, core centers the toolbar on the first `[contenteditable]` under the
+     * host, which for a container is its FIRST CHILD BLOCK — parking the +/drag
+     * handles halfway down, beside content that has a toolbar of its own.
+     *
+     * The element set here outranks the declared hook while it is MOUNTED; once it
+     * detaches (or `null` is passed) the hook takes over again, so the toolbar is
+     * never positioned against a stale node. Never calling it keeps core's default.
+     */
+    setToolbarAnchor: (element: HTMLElement | null) => void;
 }
 /** DI token carrying the per-block render context into the authored component. */
 declare const BLOK_BLOCK_CONTEXT: InjectionToken<AngularBlockRenderContext<unknown>>;
@@ -997,4 +1052,4 @@ declare const BLOK_EDITOR_INSTANCE: InjectionToken<Signal<Blok | 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 };
+export type { AngularBlockMountedContext, AngularBlockRenderContext, BlockNode, BlockToolStatics, BlokAngularConfig, BlokReadyScope, CaretTarget, ChildAttributes, ChildAttributesFn, CreateAngularBlockSpec, InjectBlocksOptions, InjectBlokReadyOptions, InsertPosition, InsertSpec, MoveTarget, PropSchema, PropSchemaEntry, TreeInsertSpec, UseBlocksApi };