@mocanvas/editor 4.4.1 → 4.4.3

package/dist/index.d.ts

@@ -12250,251 +12250,6 @@ declare class WebGL2Backend implements RenderBackend {
  */
 declare function createBackend(canvas: HTMLCanvasElement): RenderBackend;
 
-/**
- * What the `Canvas` component slot is handed.
- *
- * A host replacing the canvas gets only presentation: a class name and
- * children. It deliberately does *not* receive the editor as a prop — the
- * replacement is rendered inside the editor's provider and reads it with
- * `useEditor()`, so a slot cannot be rendered against a different editor than
- * the one it is inside of.
- */
-interface TLCanvasComponentProps {
-    className?: string;
-    children?: ReactNode;
-}
-interface CanvasProps {
-    editor: Editor;
-    className?: string;
-    style?: CSSProperties;
-    /** Extra layers rendered above the canvas (UI, menus). */
-    children?: ReactNode;
-    /** Override the default selection/brush indicators. */
-    components?: Partial<CanvasComponents>;
-    /**
-     * The overlay util that paints shape indicators onto the canvas layer.
-     *
-     * A *class*, not an instance — one is constructed per editor. Pass
-     * `ShapeIndicatorCompositor.configure({ lineWidth })` to restyle, or a
-     * subclass to control which shapes get an outline.
-     */
-    indicatorOverlayUtil?: typeof ShapeIndicatorCompositor;
-}
-interface CanvasComponents {
-    Indicators: (props: {
-        editor: Editor;
-    }) => ReactNode;
-    Brush: (props: {
-        editor: Editor;
-    }) => ReactNode;
-    Background: (props: {
-        editor: Editor;
-    }) => ReactNode;
-}
-/**
- * The canvas: a WebGL2 surface driven by the engine, a DOM overlay for shapes
- * that render through `ShapeUtil.component`, a 2D canvas overlay for shape
- * indicators, and an SVG layer for the selection handles, snap lines, the brush
- * — and for any util still on the deprecated `indicator()` hook.
- */
-declare function Canvas({ editor, className, style, children, components, indicatorOverlayUtil }: CanvasProps): react.JSX.Element;
-/**
- * The outline to draw over one shape: whatever its util's `indicator()`
- * returns, or a rectangle around the shape's geometry bounds when the util has
- * no indicator (or returns nothing). Both are expressed in *shape-local*
- * coordinates; the caller wraps them in the shape's page transform.
- *
- * Pure and exported so a custom `Indicators` component can reuse the same rule
- * instead of guessing at it.
- *
- * @deprecated The SVG indicator layer only draws utils still on the deprecated
- * `indicator()` hook. A util that implements `getIndicatorPath` is stroked on
- * the canvas overlay by `ShapeIndicatorCompositor` instead.
- */
-declare function getShapeIndicatorNode<T extends UnknownShape>(util: {
-    indicator?(shape: T): ReactNode;
-}, shape: T, bounds: {
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-} | undefined): ReactNode;
-
-declare const EditorContext: react.Context<Editor | null>;
-/** The editor of the nearest `<EditorProvider>` / `<Canvas>`. */
-declare function useEditor(): Editor;
-declare function useMaybeEditor(): Editor | null;
-/** Props of {@link EditorProvider}. */
-interface EditorProviderProps {
-    /** The editor every `useEditor()` below this point resolves to. */
-    editor: Editor;
-    children?: ReactNode;
-}
-/**
- * Publishes an editor to the React tree.
- *
- * Takes the editor as `editor` rather than a context provider's `value`, so a
- * test — or an app rendering chrome outside `<Canvas>` — writes
- * `<EditorProvider editor={editor}>` and never has to know that a context is
- * what is underneath. {@link EditorContext} is still exported for the rare
- * caller that wants the raw provider (to publish `null`, say).
- */
-declare function EditorProvider({ editor, children }: EditorProviderProps): react.JSX.Element;
-
-interface HTMLContainerProps extends HTMLAttributes<HTMLDivElement> {
-    children?: ReactNode;
-    ref?: Ref<HTMLDivElement>;
-}
-/**
- * The DOM body of a shape. Fills the shape's bounds; anything else — size,
- * pointer-events, overflow, a class of your own — is set through `style` and
- * `className`, which are merged over the defaults rather than replacing them.
- */
-declare function HTMLContainer({ children, className, style, ...rest }: HTMLContainerProps): react.JSX.Element;
-interface SVGContainerProps extends SVGAttributes<SVGSVGElement> {
-    children?: ReactNode;
-    ref?: Ref<SVGSVGElement>;
-}
-/**
- * The SVG body of a shape: an `<svg>` filling the shape's bounds, whose user
- * space is the shape's own local coordinate space, so a `<path>` drawn at
- * `(0, 0)` sits at the shape's origin at any pan, zoom or rotation.
- */
-declare function SVGContainer({ children, className, style, ...rest }: SVGContainerProps): react.JSX.Element;
-/**
- * Stop an event travelling any further up the tree.
- *
- * The canvas listens for pointer events on its container, so a click on a
- * piece of chrome rendered over it — a toolbar button, a menu, a panel —
- * would also start a canvas interaction. Hanging this on the chrome's root
- * (`onPointerDown={stopEventPropagation}`) keeps the two apart.
- *
- * Typed structurally rather than against `React.SyntheticEvent` so it can be
- * handed to a native listener, a React handler, or a test double alike.
- */
-declare function stopEventPropagation(event: {
-    stopPropagation(): void;
-}): void;
-
-/**
- * The bridge from the theme to CSS: the canvas container stamps the theme's
- * surface colours as custom properties, and everything drawn in CSS or SVG
- * reads them.
- *
- * Only the *surface* half of a ramp is published — the colours that belong to
- * the canvas rather than to any one shape. A shape's paint comes from its
- * style props through `getDisplayValues`, not from a variable, because a
- * shape is drawn on the GPU where a CSS variable means nothing.
- */
-/**
- * Which theme colour each custom property carries.
- *
- * The names are the ones `ui.css` already declares and `Canvas` already reads,
- * so an app that themed mocanvas by overriding the variables by hand keeps
- * working: the theme now writes the same variables it used to have to be told.
- */
-declare const CANVAS_THEME_VARS: {
-    readonly "--mocanvas-selection": "selectStroke";
-    readonly "--mocanvas-selection-fg": "background";
-    readonly "--mocanvas-brush-fill": "selectFill";
-    readonly "--mocanvas-brush-stroke": "selectStroke";
-    readonly "--mocanvas-snap": "hint";
-    readonly "--mocanvas-background": "background";
-    readonly "--mocanvas-surface": "solid";
-    readonly "--mocanvas-text": "text";
-    readonly "--mocanvas-grid": "grid";
-};
-/**
- * The camera, as custom properties.
- *
- * Separate from the colours because these change on every zoom rather than on
- * a theme swap, and because they are the two variables an app most often needs
- * in CSS: anything drawn in the DOM over a zooming canvas has to divide by the
- * zoom to keep a constant on-screen size. `@mocanvas/compat` maps tldraw's
- * `--tl-zoom` and `--tl-scale` onto them; without them every `calc()` in a
- * migrated stylesheet resolved to nothing and took its whole declaration with
- * it.
- */
-declare function getCameraCssVars(zoom: number): CSSProperties;
-/** {@link getCameraCssVars} for an editor, tracked reactively. */
-declare function useCameraCssVars(editor: Editor): CSSProperties;
-/**
- * The custom properties for one resolved ramp.
- *
- * SEMANTICS-ASSUMED: `--mocanvas-selection-fg` is the fill of a solid
- * selection handle, and is mapped to the theme's `background`. A handle is a
- * chip of the page punched out of the selection stroke, so it has to match the
- * page it sits on or it reads as a light dot on a dark canvas — which is
- * exactly what the hard-coded `#ffffff` did before the theme existed.
- *
- * A colour the ramp does not carry is skipped rather than written as
- * `undefined`, so the literal fallback in `var(--x, …)` still applies.
- */
-declare function getThemeCssVars(colors: TLThemeColors | undefined): CSSProperties;
-/**
- * The theme's custom properties for an editor, tracked reactively — swapping a
- * theme or flipping to dark restamps the container without anything being
- * invalidated by hand.
- *
- * Takes the editor rather than reading it from context, because the element
- * that carries the variables is the canvas container itself: the hook runs
- * above the provider that would supply it. The theme manager is read
- * defensively for the same reason `useColorMode` does — a stand-in editor in a
- * chrome test has no theme at all.
- */
-declare function useThemeCssVars(editor: Editor): CSSProperties;
-
-/**
- * Where an app self-hosts the files the UI loads at runtime.
- *
- * mocanvas itself needs none of them — its icons are inline SVG and it ships
- * no translation bundles — so the map is carried, not consumed: it exists so a
- * component an app drops into a chrome slot can ask for the same base paths
- * the host configured, instead of every such component growing a prop for it.
- *
- * Kept as nested string maps rather than a fixed shape because the categories
- * are the app's, not ours; the four named below are only the ones a
- * self-hosting setup usually has.
- */
-interface TLAssetUrls {
-    fonts?: Readonly<Record<string, string>>;
-    icons?: Readonly<Record<string, string>>;
-    embedIcons?: Readonly<Record<string, string>>;
-    translations?: Readonly<Record<string, string>>;
-    [category: string]: Readonly<Record<string, string>> | undefined;
-}
-/**
- * The editor's half of the map: the fonts the canvas loads.
- *
- * A separate name from {@link TLAssetUrls} because the editor package can only
- * promise what it itself uses — the UI layer adds icons and translations on
- * top, as {@link TLUiAssetUrls}.
- */
-interface TLEditorAssetUrls extends TLAssetUrls {
-    fonts?: Readonly<Record<string, string>>;
-}
-/**
- * The UI layer's half: the icons and translation bundles a self-hosting app
- * serves itself.
- */
-interface TLUiAssetUrls extends TLEditorAssetUrls {
-    icons?: Readonly<Record<string, string>>;
-    embedIcons?: Readonly<Record<string, string>>;
-    translations?: Readonly<Record<string, string>>;
-}
-interface AssetUrlsProviderProps {
-    assetUrls: TLAssetUrls;
-    children?: ReactNode;
-}
-/** Publishes an {@link TLAssetUrls} map to everything below it. */
-declare function AssetUrlsProvider({ assetUrls, children }: AssetUrlsProviderProps): react.JSX.Element;
-/**
- * The asset urls the host configured. Empty outside a provider — a component
- * that needs a file should fall back to its own default rather than fail,
- * because most mounts configure nothing at all.
- */
-declare function useAssetUrls(): TLAssetUrls;
-
 /**
  * The UI override surface: the types an app uses to replace mocanvas's chrome
  * and to add its own tools to it.
@@ -12807,6 +12562,257 @@ interface TLUiOverrides {
  */
 type TLUiTranslations = Record<string, Record<string, string>>;
 
+/**
+ * What the `Canvas` component slot is handed.
+ *
+ * A host replacing the canvas gets only presentation: a class name and
+ * children. It deliberately does *not* receive the editor as a prop — the
+ * replacement is rendered inside the editor's provider and reads it with
+ * `useEditor()`, so a slot cannot be rendered against a different editor than
+ * the one it is inside of.
+ */
+interface TLCanvasComponentProps {
+    className?: string;
+    children?: ReactNode;
+}
+interface CanvasProps {
+    editor: Editor;
+    className?: string;
+    style?: CSSProperties;
+    /** Extra layers rendered above the canvas (UI, menus). */
+    children?: ReactNode;
+    /** Override the default selection/brush indicators. */
+    components?: Partial<CanvasComponents>;
+    /**
+     * The overlay util that paints shape indicators onto the canvas layer.
+     *
+     * A *class*, not an instance — one is constructed per editor. Pass
+     * `ShapeIndicatorCompositor.configure({ lineWidth })` to restyle, or a
+     * subclass to control which shapes get an outline.
+     */
+    indicatorOverlayUtil?: typeof ShapeIndicatorCompositor;
+}
+interface CanvasComponents {
+    Indicators: (props: {
+        editor: Editor;
+    }) => ReactNode;
+    Brush: (props: {
+        editor: Editor;
+    }) => ReactNode;
+    Background: (props: {
+        editor: Editor;
+    }) => ReactNode;
+    /**
+     * The grid, behind the scene. Rendered only in grid mode, and handed the
+     * camera and the document's step rather than reading them — see
+     * `TLComponents.Grid`. `null` draws none; omitted uses {@link DefaultGrid}.
+     */
+    Grid: ((props: TLGridProps) => ReactNode) | null;
+}
+/**
+ * The canvas: a WebGL2 surface driven by the engine, a DOM overlay for shapes
+ * that render through `ShapeUtil.component`, a 2D canvas overlay for shape
+ * indicators, and an SVG layer for the selection handles, snap lines, the brush
+ * — and for any util still on the deprecated `indicator()` hook.
+ */
+declare function Canvas({ editor, className, style, children, components, indicatorOverlayUtil }: CanvasProps): react.JSX.Element;
+/**
+ * The outline to draw over one shape: whatever its util's `indicator()`
+ * returns, or a rectangle around the shape's geometry bounds when the util has
+ * no indicator (or returns nothing). Both are expressed in *shape-local*
+ * coordinates; the caller wraps them in the shape's page transform.
+ *
+ * Pure and exported so a custom `Indicators` component can reuse the same rule
+ * instead of guessing at it.
+ *
+ * @deprecated The SVG indicator layer only draws utils still on the deprecated
+ * `indicator()` hook. A util that implements `getIndicatorPath` is stroked on
+ * the canvas overlay by `ShapeIndicatorCompositor` instead.
+ */
+declare function getShapeIndicatorNode<T extends UnknownShape>(util: {
+    indicator?(shape: T): ReactNode;
+}, shape: T, bounds: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+} | undefined): ReactNode;
+
+declare const EditorContext: react.Context<Editor | null>;
+/** The editor of the nearest `<EditorProvider>` / `<Canvas>`. */
+declare function useEditor(): Editor;
+declare function useMaybeEditor(): Editor | null;
+/** Props of {@link EditorProvider}. */
+interface EditorProviderProps {
+    /** The editor every `useEditor()` below this point resolves to. */
+    editor: Editor;
+    children?: ReactNode;
+}
+/**
+ * Publishes an editor to the React tree.
+ *
+ * Takes the editor as `editor` rather than a context provider's `value`, so a
+ * test — or an app rendering chrome outside `<Canvas>` — writes
+ * `<EditorProvider editor={editor}>` and never has to know that a context is
+ * what is underneath. {@link EditorContext} is still exported for the rare
+ * caller that wants the raw provider (to publish `null`, say).
+ */
+declare function EditorProvider({ editor, children }: EditorProviderProps): react.JSX.Element;
+
+interface HTMLContainerProps extends HTMLAttributes<HTMLDivElement> {
+    children?: ReactNode;
+    ref?: Ref<HTMLDivElement>;
+}
+/**
+ * The DOM body of a shape. Fills the shape's bounds; anything else — size,
+ * pointer-events, overflow, a class of your own — is set through `style` and
+ * `className`, which are merged over the defaults rather than replacing them.
+ */
+declare function HTMLContainer({ children, className, style, ...rest }: HTMLContainerProps): react.JSX.Element;
+interface SVGContainerProps extends SVGAttributes<SVGSVGElement> {
+    children?: ReactNode;
+    ref?: Ref<SVGSVGElement>;
+}
+/**
+ * The SVG body of a shape: an `<svg>` filling the shape's bounds, whose user
+ * space is the shape's own local coordinate space, so a `<path>` drawn at
+ * `(0, 0)` sits at the shape's origin at any pan, zoom or rotation.
+ */
+declare function SVGContainer({ children, className, style, ...rest }: SVGContainerProps): react.JSX.Element;
+/**
+ * Stop an event travelling any further up the tree.
+ *
+ * The canvas listens for pointer events on its container, so a click on a
+ * piece of chrome rendered over it — a toolbar button, a menu, a panel —
+ * would also start a canvas interaction. Hanging this on the chrome's root
+ * (`onPointerDown={stopEventPropagation}`) keeps the two apart.
+ *
+ * Typed structurally rather than against `React.SyntheticEvent` so it can be
+ * handed to a native listener, a React handler, or a test double alike.
+ */
+declare function stopEventPropagation(event: {
+    stopPropagation(): void;
+}): void;
+
+/**
+ * The bridge from the theme to CSS: the canvas container stamps the theme's
+ * surface colours as custom properties, and everything drawn in CSS or SVG
+ * reads them.
+ *
+ * Only the *surface* half of a ramp is published — the colours that belong to
+ * the canvas rather than to any one shape. A shape's paint comes from its
+ * style props through `getDisplayValues`, not from a variable, because a
+ * shape is drawn on the GPU where a CSS variable means nothing.
+ */
+/**
+ * Which theme colour each custom property carries.
+ *
+ * The names are the ones `ui.css` already declares and `Canvas` already reads,
+ * so an app that themed mocanvas by overriding the variables by hand keeps
+ * working: the theme now writes the same variables it used to have to be told.
+ */
+declare const CANVAS_THEME_VARS: {
+    readonly "--mocanvas-selection": "selectStroke";
+    readonly "--mocanvas-selection-fg": "background";
+    readonly "--mocanvas-brush-fill": "selectFill";
+    readonly "--mocanvas-brush-stroke": "selectStroke";
+    readonly "--mocanvas-snap": "hint";
+    readonly "--mocanvas-background": "background";
+    readonly "--mocanvas-surface": "solid";
+    readonly "--mocanvas-text": "text";
+    readonly "--mocanvas-grid": "grid";
+};
+/**
+ * The camera, as custom properties.
+ *
+ * Separate from the colours because these change on every zoom rather than on
+ * a theme swap, and because they are the two variables an app most often needs
+ * in CSS: anything drawn in the DOM over a zooming canvas has to divide by the
+ * zoom to keep a constant on-screen size. `@mocanvas/compat` maps tldraw's
+ * `--tl-zoom` and `--tl-scale` onto them; without them every `calc()` in a
+ * migrated stylesheet resolved to nothing and took its whole declaration with
+ * it.
+ */
+declare function getCameraCssVars(zoom: number): CSSProperties;
+/** {@link getCameraCssVars} for an editor, tracked reactively. */
+declare function useCameraCssVars(editor: Editor): CSSProperties;
+/**
+ * The custom properties for one resolved ramp.
+ *
+ * SEMANTICS-ASSUMED: `--mocanvas-selection-fg` is the fill of a solid
+ * selection handle, and is mapped to the theme's `background`. A handle is a
+ * chip of the page punched out of the selection stroke, so it has to match the
+ * page it sits on or it reads as a light dot on a dark canvas — which is
+ * exactly what the hard-coded `#ffffff` did before the theme existed.
+ *
+ * A colour the ramp does not carry is skipped rather than written as
+ * `undefined`, so the literal fallback in `var(--x, …)` still applies.
+ */
+declare function getThemeCssVars(colors: TLThemeColors | undefined): CSSProperties;
+/**
+ * The theme's custom properties for an editor, tracked reactively — swapping a
+ * theme or flipping to dark restamps the container without anything being
+ * invalidated by hand.
+ *
+ * Takes the editor rather than reading it from context, because the element
+ * that carries the variables is the canvas container itself: the hook runs
+ * above the provider that would supply it. The theme manager is read
+ * defensively for the same reason `useColorMode` does — a stand-in editor in a
+ * chrome test has no theme at all.
+ */
+declare function useThemeCssVars(editor: Editor): CSSProperties;
+
+/**
+ * Where an app self-hosts the files the UI loads at runtime.
+ *
+ * mocanvas itself needs none of them — its icons are inline SVG and it ships
+ * no translation bundles — so the map is carried, not consumed: it exists so a
+ * component an app drops into a chrome slot can ask for the same base paths
+ * the host configured, instead of every such component growing a prop for it.
+ *
+ * Kept as nested string maps rather than a fixed shape because the categories
+ * are the app's, not ours; the four named below are only the ones a
+ * self-hosting setup usually has.
+ */
+interface TLAssetUrls {
+    fonts?: Readonly<Record<string, string>>;
+    icons?: Readonly<Record<string, string>>;
+    embedIcons?: Readonly<Record<string, string>>;
+    translations?: Readonly<Record<string, string>>;
+    [category: string]: Readonly<Record<string, string>> | undefined;
+}
+/**
+ * The editor's half of the map: the fonts the canvas loads.
+ *
+ * A separate name from {@link TLAssetUrls} because the editor package can only
+ * promise what it itself uses — the UI layer adds icons and translations on
+ * top, as {@link TLUiAssetUrls}.
+ */
+interface TLEditorAssetUrls extends TLAssetUrls {
+    fonts?: Readonly<Record<string, string>>;
+}
+/**
+ * The UI layer's half: the icons and translation bundles a self-hosting app
+ * serves itself.
+ */
+interface TLUiAssetUrls extends TLEditorAssetUrls {
+    icons?: Readonly<Record<string, string>>;
+    embedIcons?: Readonly<Record<string, string>>;
+    translations?: Readonly<Record<string, string>>;
+}
+interface AssetUrlsProviderProps {
+    assetUrls: TLAssetUrls;
+    children?: ReactNode;
+}
+/** Publishes an {@link TLAssetUrls} map to everything below it. */
+declare function AssetUrlsProvider({ assetUrls, children }: AssetUrlsProviderProps): react.JSX.Element;
+/**
+ * The asset urls the host configured. Empty outside a provider — a component
+ * that needs a file should fall back to its own default rather than fail,
+ * because most mounts configure nothing at all.
+ */
+declare function useAssetUrls(): TLAssetUrls;
+
 /**
  * Resolving a UI string id through an app's `TLUiOverrides.translations`.
  *