@bloklabs/react 1.16.0 → 2.0.0

package/src/createReactInlineTool.tsx

@@ -1,406 +0,0 @@
-import { createContext, useContext, useMemo, type ComponentType, type ReactElement } from 'react';
-import { markSanitizerConfig } from '@bloklabs/core/adapters';
-import {
-  BLOK_PORTAL_REGISTRY_CONFIG_KEY,
-  BLOK_TOOL_NAME_CONFIG_KEY,
-  type BlockPortalRegistry,
-} from './block-portal-registry';
-import type { API, SanitizerConfig } from '@/types';
-import type { MarkSnapshot, MarkSpec } from '@/types';
-import type { InlineTool, InlineToolConstructorOptions, MenuConfig } from '@/types/tools';
-
-/** Adapter-internal config keys, stripped before the config reaches the component. */
-const INTERNAL_CONFIG_KEYS: readonly string[] = [
-  BLOK_PORTAL_REGISTRY_CONFIG_KEY,
-  BLOK_TOOL_NAME_CONFIG_KEY,
-];
-
-/**
- * Unique portal-registry key per tool instance (inline tools have no block id
- * to key on, and multiple instances of the same tool can coexist — e.g. the
- * visible toolbar's instance plus a shortcut render-probe).
- * @param toolName - name the tool is registered under
- */
-const generatePortalKey = (toolName: string): string =>
-  `__blok-inline-tool__:${toolName}:${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
-
-/** Props handed to a React inline tool's `component` (its toolbar icon/UI). */
-export interface ReactInlineToolRenderProps<Config = Record<string, unknown>> {
-  /**
-   * Whether the tool's formatting is active for the current selection —
-   * derived from the spec's `checkState` every time the toolbar queries it.
-   * Pushed IN PLACE (no remount), so the icon restyles live.
-   */
-  active: boolean;
-  /**
-   * The tool's `config` from the consumer's `tools` map (adapter-internal
-   * keys stripped) — the channel for host props (palette, locale…).
-   */
-  config: Readonly<Partial<Config>>;
-}
-
-/** The spec's mark operations, bound to the live selection via `api.marks`. */
-export interface InlineToolMarkOps<State = void> {
-  /** Whether the whole selection currently carries the mark. */
-  has(): boolean;
-  /** Toggle the mark on the selection; returns true when now applied. */
-  toggle(state?: State): boolean;
-  /** Apply (or update in place) the mark on the selection. */
-  apply(state?: State): HTMLElement[];
-  /** Remove the mark from the selection. */
-  remove(): HTMLElement[];
-  /** Read the mark's current declared values at the selection. */
-  read(): MarkSnapshot | null;
-}
-
-/**
- * Everything a React inline tool's component (and any component nested in it —
- * swatches, popovers) can reach via {@link useInlineTool} without prop-drilling.
- */
-export interface InlineToolHandle<Config = Record<string, unknown>, State = void> {
-  /** Live active state, same value as the component's `active` prop. */
-  active: boolean;
-  /** The tool's config, same value as the component's `config` prop. */
-  config: Readonly<Partial<Config>>;
-  /** The editor API handed to the tool's constructor (undefined outside core). */
-  api: API | undefined;
-  /**
-   * Operations bound to the spec's `mark` — null when the spec declares no
-   * mark or the editor api provides no `marks` surface.
-   */
-  mark: InlineToolMarkOps<State> | null;
-}
-
-const InlineToolContext = createContext<InlineToolHandle | null>(null);
-
-/**
- * Reach the enclosing React inline tool from any component inside its
- * portaled UI: live `active` state, the tool `config`, the editor `api`, and
- * the spec's mark operations bound to the live selection.
- */
-export function useInlineTool<Config = Record<string, unknown>, State = void>(): InlineToolHandle<Config, State> {
-  const handle = useContext(InlineToolContext);
-
-  if (handle === null) {
-    throw new Error('useInlineTool() must be called from a component rendered by createReactInlineTool');
-  }
-
-  return handle as InlineToolHandle<Config, State>;
-}
-
-/** Spec for {@link createReactInlineTool}. */
-export interface CreateReactInlineToolSpec<Config = Record<string, unknown>, State = void> {
-  /** Tool type name — the MenuConfig item name (fallback when the tools-map key is unavailable). */
-  type: string;
-  /** Optional toolbar item title (shown in overflow/search contexts). */
-  title?: string;
-  /**
-   * Translation key for the toolbar label, resolved by core i18n as
-   * `toolNames.{titleKey}` (or used verbatim when it contains a dot). Without
-   * it a custom tool's label is only localizable through the legacy
-   * capitalized-tool-name fallback.
-   */
-  titleKey?: string;
-  /** The component rendered as the tool's toolbar icon/UI. */
-  component: ComponentType<ReactInlineToolRenderProps<Config>>;
-  /**
-   * Declarative description of the wrapper this tool produces. When present,
-   * `surround` (toggle), `checkState` (whole-range coverage) and `sanitize`
-   * are derived from it — range-aware splitting, adjacent-run semantics and
-   * the trailing-whitespace fix come from the editor's mark engine
-   * (`api.marks`) with no DOM plumbing in the tool.
-   */
-  mark?: MarkSpec<State>;
-  /**
-   * Applies/removes the formatting on the LIVE selection's range (captured at
-   * activation time). Receives the editor API as its second argument.
-   * Takes precedence over the `mark` derivation.
-   */
-  surround?: (range: Range, api: API | undefined) => void;
-  /**
-   * Reports whether the formatting is active for the given selection.
-   * Receives the editor API as its second argument.
-   * Takes precedence over the `mark` derivation.
-   */
-  checkState?: (selection: Selection | null, api: API | undefined) => boolean;
-  /** Keyboard shortcut (e.g. `CMD+SHIFT+C`). */
-  shortcut?: string;
-  /**
-   * Inline sanitizer config declaring the markup this tool produces.
-   * Defaults to the config derived from `mark` when one is declared.
-   */
-  sanitize?: SanitizerConfig;
-  /** Whether the tool stays available in read-only mode. */
-  isReadOnlySupported?: boolean;
-}
-
-/**
- * Author a first-party React inline tool. Returns an inline-tool constructable
- * registered exactly like a vanilla tool (`tools: { color: createReactInlineTool(...) }`).
- *
- * Mirrors the `createReactBlock` portal pattern: `render()` returns a
- * `MenuConfig` whose `icon` is a Blok-owned host element
- * (`data-blok-mutation-free`) the component is portaled into via the editor's
- * shared `BlockPortalHost` tree — app-level context (themes, styled-components
- * providers) reaches the icon with no consumer-managed `createRoot`, and
- * `destroy()` (called by the inline toolbar on close/teardown) unregisters the
- * portal so the component unmounts deterministically — no leaked React roots.
- *
- * The editor `api` handed to the constructor is kept: it reaches `surround`/
- * `checkState` as their second argument, powers the `mark` derivation, and is
- * exposed to the portaled component tree via {@link useInlineTool}.
- *
- * Without an injected registry (vanilla core, no `useBlok`), the tool still
- * renders a valid MenuConfig — the host element just stays empty.
- */
-export function createReactInlineTool<Config = Record<string, unknown>, State = void>(
-  spec: CreateReactInlineToolSpec<Config, State>
-): (new (options: InlineToolConstructorOptions) => InlineTool) & {
-  readonly __isBlokReactInlineTool: true;
-  readonly isInline: true;
-  readonly type: string;
-  readonly title: string | undefined;
-  readonly titleKey: string;
-  readonly shortcut: string | undefined;
-  readonly mark: MarkSpec<State> | undefined;
-  readonly sanitize: SanitizerConfig | undefined;
-  readonly isReadOnlySupported: boolean;
-} {
-  return class ReactInlineTool implements InlineTool {
-    /** Marker so `useBlok` can detect react inline tools and inject the registry. */
-    public static readonly __isBlokReactInlineTool = true as const;
-    public static readonly isInline = true as const;
-
-    /** The tool's type name — also the default translation key and mark tag context. */
-    public static get type(): string {
-      return spec.type;
-    }
-
-    public static get title(): string | undefined {
-      return spec.title;
-    }
-
-    /**
-     * Translation key core i18n resolves as `toolNames.{titleKey}`. Defaults to
-     * the tool `type` so a custom mark localizes through the conventional
-     * `toolNames.{type}` key (as built-in tools do) instead of silently falling
-     * to the un-translated capitalized tool name. When the consumer supplies no
-     * matching i18n entry, core still falls through to that same label — the
-     * default is a no-op there and never a regression.
-     */
-    public static get titleKey(): string {
-      return spec.titleKey ?? spec.type;
-    }
-
-    public static get shortcut(): string | undefined {
-      return spec.shortcut;
-    }
-
-    /**
-     * The declared mark spec (if any). Exposed as a static so consumers can
-     * assert a tool's mark in unit tests without mocking the factory.
-     */
-    public static get mark(): MarkSpec<State> | undefined {
-      return spec.mark;
-    }
-
-    public static get sanitize(): SanitizerConfig | undefined {
-      if (spec.sanitize !== undefined) {
-        return spec.sanitize;
-      }
-
-      return spec.mark !== undefined ? markSanitizerConfig(spec.mark) : undefined;
-    }
-
-    public static get isReadOnlySupported(): boolean {
-      return spec.isReadOnlySupported ?? false;
-    }
-
-    private readonly registry: BlockPortalRegistry | undefined;
-    /** The editor API — kept (not discarded) so the tool has the same reach as a vanilla one. */
-    private readonly api: API | undefined;
-    /** Name this tool is registered under in the consumer's `tools` map. */
-    private readonly toolName: string;
-    /** Unique portal-registry key — inline tools have no block id. */
-    private readonly portalKey: string;
-    /** The consumer's tool config with adapter-internal keys stripped. */
-    private readonly toolConfig: Readonly<Partial<Config>>;
-    /**
-     * Stable provider component wrapping `spec.component` with the
-     * {@link useInlineTool} context. Created once per instance so prop pushes
-     * (setProps) re-render without remounting the consumer's component.
-     */
-    private readonly portalComponent: ComponentType<ReactInlineToolRenderProps<Config>>;
-    /** Last active state pushed to the mounted component (change-dedup baseline). */
-    private active = false;
-    /** True while this instance owns a registered portal entry. */
-    private registered = false;
-
-    public constructor(options: InlineToolConstructorOptions) {
-      const config: Record<string, unknown> = options?.config ?? {};
-
-      this.api = options?.api;
-      this.registry = config[BLOK_PORTAL_REGISTRY_CONFIG_KEY] as BlockPortalRegistry | undefined;
-
-      const toolName = config[BLOK_TOOL_NAME_CONFIG_KEY];
-
-      this.toolName = typeof toolName === 'string' ? toolName : spec.type;
-      this.portalKey = generatePortalKey(this.toolName);
-
-      const publicConfig: Record<string, unknown> = {};
-
-      for (const [key, value] of Object.entries(config)) {
-        if (!INTERNAL_CONFIG_KEYS.includes(key)) {
-          publicConfig[key] = value;
-        }
-      }
-      this.toolConfig = Object.freeze(publicConfig) as Readonly<Partial<Config>>;
-      this.portalComponent = this.createPortalComponent();
-    }
-
-    public render(): MenuConfig {
-      // The Blok-owned host: React reconciles the icon portaled INTO it, and
-      // this attribute makes core's MutationObserver ignore those mutations.
-      const host = document.createElement('div');
-
-      host.setAttribute('data-blok-mutation-free', 'true');
-
-      if (this.registry !== undefined) {
-        this.registry.register(this.portalKey, {
-          hostEl: host,
-          component: this.portalComponent as unknown as ComponentType<Record<string, unknown>>,
-          props: { active: this.active, config: this.toolConfig },
-          toolName: this.toolName,
-        });
-        this.registered = true;
-      }
-
-      return {
-        name: this.toolName,
-        title: spec.title,
-        icon: host,
-        onActivate: (): void => {
-          this.activate();
-        },
-        isActive: (): boolean => this.refreshActiveState(),
-      };
-    }
-
-    /**
-     * Idempotent teardown, called by the inline toolbar when this instance is
-     * dropped (toolbar close, editor destroy, or a throwaway render probe).
-     * Unregisters the portal entry so React unmounts the icon component —
-     * the unmount signal consumer-managed `createRoot` hacks never had.
-     */
-    public destroy(): void {
-      if (!this.registered) {
-        return;
-      }
-
-      this.registered = false;
-      this.registry?.unregister(this.portalKey);
-    }
-
-    /**
-     * Run the tool's formatting action: an explicit `surround` on the LIVE
-     * selection's range (captured at activation time, matching
-     * wrapLegacyInlineTool — never a range snapshotted at render), or the
-     * mark derivation (`api.marks.toggle`) when only a `mark` is declared.
-     */
-    private activate(): void {
-      if (typeof spec.surround === 'function') {
-        const selection = window.getSelection();
-
-        if (!selection || selection.rangeCount === 0) {
-          return;
-        }
-
-        spec.surround(selection.getRangeAt(0), this.api);
-
-        return;
-      }
-
-      if (spec.mark !== undefined && this.api?.marks !== undefined) {
-        this.api.marks.toggle(spec.mark);
-      }
-    }
-
-    /**
-     * Recompute the active state from the live selection and push it to the
-     * mounted component ONLY when it actually changed (no redundant
-     * external-store notifications).
-     */
-    private refreshActiveState(): boolean {
-      const active = this.computeActiveState();
-
-      if (active !== this.active) {
-        this.active = active;
-
-        if (this.registered) {
-          this.registry?.setProps(this.portalKey, { active });
-        }
-      }
-
-      return active;
-    }
-
-    /**
-     * Explicit `checkState` wins; otherwise the mark derivation answers
-     * "does the WHOLE selection carry the mark" via `api.marks.has`.
-     */
-    private computeActiveState(): boolean {
-      if (typeof spec.checkState === 'function') {
-        return Boolean(spec.checkState(window.getSelection(), this.api));
-      }
-
-      if (spec.mark !== undefined && this.api?.marks !== undefined) {
-        return this.api.marks.has(spec.mark);
-      }
-
-      return false;
-    }
-
-    /**
-     * Build the per-instance provider component: the consumer's component
-     * rendered inside the {@link useInlineTool} context, so nested
-     * swatches/popovers reach the tool without prop-drilling.
-     */
-    private createPortalComponent(): ComponentType<ReactInlineToolRenderProps<Config>> {
-      const api = this.api;
-      const mark = spec.mark;
-      const Component = spec.component;
-
-      const markOps: InlineToolMarkOps<State> | null = mark !== undefined && api?.marks !== undefined
-        ? {
-            has: (): boolean => api.marks.has(mark),
-            toggle: (state?: State): boolean => api.marks.toggle(mark, state),
-            apply: (state?: State): HTMLElement[] => api.marks.apply(mark, state),
-            remove: (): HTMLElement[] => api.marks.remove(mark),
-            read: (): MarkSnapshot | null => api.marks.read(mark),
-          }
-        : null;
-
-      const PortalComponent = (props: ReactInlineToolRenderProps<Config>): ReactElement => {
-        const handle = useMemo<InlineToolHandle>(
-          () => ({
-            active: props.active,
-            config: props.config,
-            api,
-            mark: markOps as InlineToolMarkOps | null,
-          }),
-          [props.active, props.config]
-        );
-
-        return (
-          <InlineToolContext.Provider value={handle}>
-            <Component active={props.active} config={props.config} />
-          </InlineToolContext.Provider>
-        );
-      };
-
-      PortalComponent.displayName = `BlokInlineTool(${this.toolName})`;
-
-      return PortalComponent;
-    }
-  };
-}

package/src/deep-equal.ts

@@ -1,7 +0,0 @@
-/**
- * Re-export of the framework-agnostic deep equality used to dedupe reactive
- * `data` updates. The implementation now lives in `src/shared/deep-equal.ts`
- * (shared with the Angular adapter); this module is kept for back-compat with
- * existing `./deep-equal` importers in the React adapter.
- */
-export { deepEqual } from '@bloklabs/core/adapters';

package/src/holder-map.ts

@@ -1,17 +0,0 @@
-/**
- * Module-level WeakMap associating editor instances with their detached holder divs.
- * WeakMap ensures no memory leaks — when the editor is garbage collected, the holder reference is released.
- */
-const holders = new WeakMap<WeakKey, HTMLDivElement>();
-
-export function setHolder(editor: WeakKey, holder: HTMLDivElement): void {
-  holders.set(editor, holder);
-}
-
-export function getHolder(editor: WeakKey): HTMLDivElement | undefined {
-  return holders.get(editor);
-}
-
-export function removeHolder(editor: WeakKey): void {
-  holders.delete(editor);
-}

package/src/index.ts

@@ -1,62 +0,0 @@
-export { useBlok } from './useBlok';
-// Host-i18n bridge (#41): re-export the direction/normalization helpers so a
-// host that owns its locale state can compute `dir` and validate tags without
-// deep-importing core. `<BlokEditor locale>` pairs with these.
-export { getDirection, normalizeLocale } from '@bloklabs/core/locales';
-export { BlokContent } from './BlokContent';
-export { BlokEditor } from './BlokEditor';
-export { useBlokHandle } from './useBlokHandle';
-export type { BlokEditorHandle } from './useBlokHandle';
-export { BlokProvider, useBlokDefaults } from './provide-blok';
-export { useBlokInstance } from './blok-instance-context';
-export type { UseBlokConfig, BlokContentProps } from './types';
-// The config/DOM prop split `BlokEditor` applies: a key not in this list is
-// spread onto the container div instead of routing into the editor config.
-// Hosts that filter props themselves must read it from here, not copy it.
-export { USE_BLOK_CONFIG_KEYS } from './config-keys';
-export type { BlokEditorProps } from './BlokEditor';
-export { useBlocks } from './useBlocks';
-export type { UseBlocksOptions } from './useBlocks';
-export { useBlokReady } from './useBlokReady';
-export type { UseBlokReadyOptions } from './useBlokReady';
-export { BlokView } from './BlokView';
-export type { BlokViewProps } from './BlokView';
-export { useBlokView } from './useBlokView';
-export { createReactBlock } from './createReactBlock';
-export type {
-  BlockChildrenProps,
-  BlockToolStatics,
-  ChildAttributes,
-  CreateReactBlockSpec,
-  ReactBlockMountedContext,
-  ReactBlockRenderProps,
-  ReactBlockViewProps,
-  ReactToolboxConfig,
-  ReactToolboxConfigEntry,
-  PropSchema,
-  PropSchemaEntry,
-} from './createReactBlock';
-export { createReactInlineTool, useInlineTool } from './createReactInlineTool';
-export type {
-  CreateReactInlineToolSpec,
-  ReactInlineToolRenderProps,
-  InlineToolHandle,
-  InlineToolMarkOps,
-} from './createReactInlineTool';
-export {
-  createBlockPortalRegistry,
-  BLOK_PORTAL_REGISTRY_CONFIG_KEY,
-  BLOK_TOOL_NAME_CONFIG_KEY,
-} from './block-portal-registry';
-export type { BlockPortalRegistry, BlockPortalEntry } from './block-portal-registry';
-export { BlockPortalHost } from './BlockPortalHost';
-export type { BlockPortalHostProps } from './BlockPortalHost';
-export type {
-  BlockNode,
-  CaretTarget,
-  InsertSpec,
-  TreeInsertSpec,
-  InsertPosition,
-  MoveTarget,
-  UseBlocksApi,
-} from './blocks-snapshot';

package/src/live-tool-config.ts

@@ -1,154 +0,0 @@
-/**
- * Live tool-config functions: the reason a consumer should never have to freeze
- * callback identities (`useState(() => ...)`) or recreate the editor to get
- * fresh closures into tool configs.
- *
- * Core snapshots each tool's config when a block instance is constructed
- * (`ToolClass.settings` builds a merged copy), so a function passed in `tools`
- * at editor construction would otherwise be pinned forever — consumers worked
- * around it by freezing identities and smuggling live values through external
- * stores. Instead, `useBlok` hands core STABLE wrapper functions that delegate
- * to whatever closure the LATEST render passed at the same config path. New
- * render → new closure → the wrapper calls it; the editor is never recreated.
- */
-
-type AnyFunction = (...args: unknown[]) => unknown;
-
-const isPlainObject = (value: unknown): value is Record<string, unknown> => {
-  if (typeof value !== 'object' || value === null) {
-    return false;
-  }
-
-  const proto: unknown = Object.getPrototypeOf(value);
-
-  return proto === Object.prototype || proto === null;
-};
-
-/** Walk `root` down `path`, returning undefined the moment the shape diverges. */
-const resolveAtPath = (root: unknown, path: readonly (string | number)[]): unknown =>
-  path.reduce<unknown>((node, key) => {
-    if (Array.isArray(node)) {
-      return typeof key === 'number' ? node[key] : undefined;
-    }
-
-    if (isPlainObject(node)) {
-      return node[key];
-    }
-
-    return undefined;
-  }, root);
-
-/**
- * Build the component-facing `config` for a react block from the LATEST render's
- * raw config, preferring the stable live wrapper from `wrappedConfig` wherever
- * both sides hold a function at the same path. The result carries the newest
- * non-function VALUES while keeping function identities stable across renders
- * (wrappers already delegate to the latest closure), so a deep-equal dedupe of
- * successive results only fires when a value genuinely changed.
- */
-export const buildLiveBlockConfig = (
-  wrappedConfig: unknown,
-  latestConfig: unknown
-): Record<string, unknown> => {
-  const merge = (latest: unknown, wrapped: unknown): unknown => {
-    if (typeof latest === 'function') {
-      return typeof wrapped === 'function' ? wrapped : latest;
-    }
-
-    if (Array.isArray(latest)) {
-      const wrappedArray = Array.isArray(wrapped) ? wrapped : [];
-
-      return latest.map((item, index) => merge(item, wrappedArray[index]));
-    }
-
-    if (isPlainObject(latest)) {
-      const wrappedObject = isPlainObject(wrapped) ? wrapped : {};
-      const result: Record<string, unknown> = {};
-
-      for (const [key, value] of Object.entries(latest)) {
-        result[key] = merge(value, wrappedObject[key]);
-      }
-
-      return result;
-    }
-
-    return latest;
-  };
-
-  const merged = merge(latestConfig, wrappedConfig);
-
-  return isPlainObject(merged) ? merged : {};
-};
-
-/**
- * Return a copy of `tools` where every function inside a tool's `config` is
- * replaced by a stable wrapper that calls the function found at the same path
- * in `getLatestTools()` (falling back to the construction-time original when
- * the latest config no longer carries one). Tool classes and non-function
- * values pass through untouched; the consumer's objects are never mutated.
- */
-export const bindLiveToolConfigFunctions = (tools: unknown, getLatestTools: () => unknown): unknown => {
-  if (!isPlainObject(tools)) {
-    return tools;
-  }
-
-  const result: Record<string, unknown> = {};
-
-  for (const [name, entry] of Object.entries(tools)) {
-    if (!isPlainObject(entry) || !isPlainObject(entry.config)) {
-      result[name] = entry;
-
-      continue;
-    }
-
-    const seen = new WeakSet();
-
-    const wrapNode = (node: unknown, path: readonly (string | number)[]): unknown => {
-      if (typeof node === 'function') {
-        const original = node as AnyFunction;
-
-        return function liveConfigFunction(this: unknown, ...args: unknown[]): unknown {
-          const latestTools = getLatestTools();
-          const latestEntry = isPlainObject(latestTools) ? latestTools[name] : undefined;
-          const latestConfig = isPlainObject(latestEntry) ? latestEntry.config : undefined;
-          const latest = resolveAtPath(latestConfig, path);
-          const target = typeof latest === 'function' ? (latest as AnyFunction) : original;
-
-          // Preserve the call-site `this` (config functions may be invoked as
-          // methods of their config object).
-          return Reflect.apply(target, this, args);
-        };
-      }
-
-      if (Array.isArray(node)) {
-        if (seen.has(node)) {
-          return node;
-        }
-        seen.add(node);
-
-        return node.map((item, index) => wrapNode(item, [...path, index]));
-      }
-
-      if (isPlainObject(node)) {
-        if (seen.has(node)) {
-          return node;
-        }
-        seen.add(node);
-
-        const wrapped: Record<string, unknown> = {};
-
-        for (const [key, value] of Object.entries(node)) {
-          wrapped[key] = wrapNode(value, [...path, key]);
-        }
-
-        return wrapped;
-      }
-
-      return node;
-    };
-
-    result[name] = { ...entry, config: wrapNode(entry.config, []) };
-  }
-
-  return result;
-};