@scrawl-board/board 0.1.0-beta.4 → 0.1.0-beta.6

package/dist/react.d.ts

@@ -587,6 +587,7 @@ interface BoardSnapshot {
     readonly zoom: number;
     readonly readOnly: boolean;
     readonly selection: readonly string[];
+    readonly focusedItem: FocusedItem | null;
     readonly strokeCount: number;
     readonly objectCount: number;
     readonly canUndo: boolean;
@@ -597,6 +598,27 @@ interface BoardSnapshot {
         readonly collaboration: CollaborationSnapshot;
     };
 }
+/**
+ * `selection` collapsed into the one thing a selected-object toolbar needs:
+ * what's selected, its lock state, and where to anchor above it. `null`
+ * when nothing is selected, or when the selection mixes types/objects that
+ * don't resolve to a single focus (anything but one object, or several
+ * strokes sharing a `clusterId` — a multi-stroke shape).
+ *
+ * Raw lock fields, not a derived `canUnlock` — this API has no notion of
+ * "the local user" to judge that against (see `canUnlockItem` in `../core`,
+ * which takes a `userId` the Host already owns). A Custom object's lock
+ * shape doesn't carry a holder name, so it always reports `locked: false`
+ * here, matching the engine's own internal selection-badge behavior.
+ */
+interface FocusedItem {
+    readonly type: "stroke" | "note" | "text" | "table" | "image" | "timer" | "custom";
+    readonly id: string;
+    readonly locked: boolean;
+    readonly lockedBy?: string;
+    readonly lockedByName?: string;
+    readonly screenPosition?: ScreenPoint;
+}
 interface BoardControllerError {
     source: "controller" | "renderer" | "persistence" | "collaboration";
     code: string;
@@ -963,6 +985,17 @@ interface BoardController {
         add(input: BoardObjectInput): string;
         update(id: string, patch: BoardObjectPatch): void;
         remove(ids: readonly string[]): void;
+        /**
+         * Clone each given object as a new, unlocked copy offset by a small
+         * fixed cascade (matching the Duplicate affordance's established Host
+         * convention), as one undoable step. Order-preserving: `result[i]` is
+         * the clone of `ids[i]`. Strokes that share a `clusterId` among the
+         * given ids get a single fresh shared `clusterId` in the result, so
+         * duplicating a whole multi-stroke shape (e.g. an arrow's shaft + head)
+         * keeps it one shape — pass every member's id together, not just one.
+         * Unknown ids are silently skipped, matching `remove`'s convention.
+         */
+        duplicate(ids: readonly string[]): readonly string[];
         table: {
             addRow(tableId: string): void;
             addCol(tableId: string): void;
@@ -1162,7 +1195,7 @@ interface DefaultBoardChromeProps {
      */
     icons?: Partial<Record<BuiltInTool, ReactNode>>;
 }
-type DefaultUIRegion = "tools" | "history" | "view" | "style" | "search" | "import" | "export" | "inlineEditing" | "styleShelf";
+type DefaultUIRegion = "tools" | "history" | "view" | "style" | "search" | "import" | "export" | "inlineEditing" | "styleShelf" | "focusedItemToolbar";
 /** Props for the toolbar/topBar/stylePanel/contextMenu slots. */
 interface BoardSlotProps {
     controller: BoardController;
@@ -1215,12 +1248,56 @@ interface MultiplayerCursorsProps {
  */
 declare function MultiplayerCursors({ controller, onSelectUser, onJumpToUser }: MultiplayerCursorsProps): react.JSX.Element | null;
 
+interface FocusedItemToolbarProps {
+    controller: BoardController;
+    snapshot: BoardSnapshot;
+}
+/**
+ * Floating toolbar above the focused note, shape, or text block — Colour,
+ * Size (note/text) or Width (shape), Lock/Unlock, Duplicate, Delete.
+ * Table/image/timer/custom objects and plain (non-shape) ink strokes never
+ * get a toolbar here — out of scope for this destination.
+ *
+ * Lock/Unlock carries no per-user ownership gating: nothing else in this
+ * SDK enforces lock ownership either (`content.update` never checks
+ * `locked`, and the engine's own internal unlock check has no way for a
+ * Host to ever supply a real user id) — locking is advisory UI state
+ * throughout, and this toolbar matches that rather than inventing an
+ * enforcement story alone.
+ *
+ * A shape can be several strokes sharing one `clusterId` (e.g. an arrow's
+ * shaft + head) — every action here applies to the whole cluster. Resolved
+ * via `query.all()` + `clusterId`, not `snapshot.selection`: a canvas click
+ * on one member selects every member internally, but the public selection
+ * bridge only ever reports one id (`FocusedItem.id` is singular by design),
+ * so reconstructing the cluster from the document is the reliable path
+ * regardless of how the selection was made.
+ *
+ * A focused note also gets drag-to-resize corner handles — notes have no
+ * gizmo of their own (the native selection gizmo is ink-stroke/shape-only),
+ * so this is that capability's default-ui-owned equivalent. Proportional
+ * (always-square) resize from the note's own centre, clamped to
+ * `[MIN_SIZE, MAX_SIZE]`, independent of which corner is grabbed.
+ */
+declare function FocusedItemToolbar({ controller, snapshot }: FocusedItemToolbarProps): react.JSX.Element | null;
+
 interface StyleShelfProps {
     controller: BoardController;
     snapshot: BoardSnapshot;
+    /**
+     * Root-relative screen point (e.g. the active tool button's own position)
+     * to anchor above instead of the default: centred over the whole
+     * `.scrawl-board__tools` toolbar. `DefaultBoardChrome` supplies this
+     * automatically; omit it when rendering `StyleShelf` standalone (its own
+     * layout has no toolbar button to anchor to) to keep the centred default.
+     */
+    anchor?: {
+        x: number;
+        y: number;
+    };
 }
 /** Contextual per-tool style controls — visible while a styleable tool is active. */
-declare function StyleShelf({ controller, snapshot }: StyleShelfProps): react.JSX.Element | null;
+declare function StyleShelf({ controller, snapshot, anchor }: StyleShelfProps): react.JSX.Element | null;
 
 type ThemeStyle = CSSProperties & Record<`--scrawl-${string}`, string | number | undefined>;
 interface ScrawlProviderProps {
@@ -1288,5 +1365,5 @@ type ScrawlBoardProps = {
 };
 declare function ScrawlBoard({ documentId, initialDocument, onReady, className, style }: ScrawlBoardProps): react.JSX.Element;
 
-export { AssetResolutionError, DefaultBoardChrome, InlineEditors, MultiplayerCursors, SUPPORTED_ASSET_MEDIA_TYPES, Scrawl, ScrawlBoard, ScrawlCanvas, ScrawlDefaultUI, ScrawlPortal, ScrawlProvider, StyleShelf, assetRef, clampAssetCacheBytes, cloneCustomObject, isAssetRef, resolveScrawlTheme, scrawlThemePresets, useScrawlController, useScrawlSnapshot, useScrawlTheme, validateScrawlTheme };
-export type { AssetDiagnostic, AssetIngestRequest, AssetIngestResult, AssetIngestor, AssetKind, AssetPurpose, AssetRef, AssetResolutionErrorCode, AssetResolveRequest, AssetResolveResult, AssetResolver, BoardController, BoardKeyInput, BoardPointerInput, BoardScene, BoardSlotProps, BoardSnapshot, BoardStyle, BoardThemeOptions, CommentMarker, CreateBoardControllerOptions, CustomBoardObject, CustomObjectAddInput, CustomObjectDefinition, CustomTool, CustomToolDefinition, DefaultBoardChromeProps, DefaultUIRegion, DefaultUISlot, DefaultUISlots, DialogSlotProps, ExtensionCommand, ExtensionDiagnostic, ExtensionHitResult, ExtensionId, ExtensionRequirement, InlineEditorsProps, InputModifiers, JsonObject, JsonValue, LocalBoard, LocalBoardSnapshot, Mat2x3, MultiplayerCursorsProps, ObjectDescribeContext, ObjectIntent, ObjectType, PresenceCursor, PresenceUser, PresenceView, QueryableBoardObject, ReadonlyCustomObject, SceneEllipse, SceneGroup, SceneImage, ScenePath, SceneRect, SceneText, ScrawlBoardProps, ScrawlCanvasProps, ScrawlDefaultUIProps, ScrawlDensity, ScrawlExtension, ScrawlGridMode, ScrawlProps, ScrawlProviderProps, ScrawlResolvedTheme, ScrawlSurfaceTexture, ScrawlTheme, ScrawlThemeDiagnostic, ScrawlThemePreset, StyleShelfProps, SupportedAssetMediaType, ToolCancelReason, ToolCapabilities, ToolCursor, ToolId };
+export { AssetResolutionError, DefaultBoardChrome, FocusedItemToolbar, InlineEditors, MultiplayerCursors, SUPPORTED_ASSET_MEDIA_TYPES, Scrawl, ScrawlBoard, ScrawlCanvas, ScrawlDefaultUI, ScrawlPortal, ScrawlProvider, StyleShelf, assetRef, clampAssetCacheBytes, cloneCustomObject, isAssetRef, resolveScrawlTheme, scrawlThemePresets, useScrawlController, useScrawlSnapshot, useScrawlTheme, validateScrawlTheme };
+export type { AssetDiagnostic, AssetIngestRequest, AssetIngestResult, AssetIngestor, AssetKind, AssetPurpose, AssetRef, AssetResolutionErrorCode, AssetResolveRequest, AssetResolveResult, AssetResolver, BoardController, BoardKeyInput, BoardPointerInput, BoardScene, BoardSlotProps, BoardSnapshot, BoardStyle, BoardThemeOptions, CommentMarker, CreateBoardControllerOptions, CustomBoardObject, CustomObjectAddInput, CustomObjectDefinition, CustomTool, CustomToolDefinition, DefaultBoardChromeProps, DefaultUIRegion, DefaultUISlot, DefaultUISlots, DialogSlotProps, ExtensionCommand, ExtensionDiagnostic, ExtensionHitResult, ExtensionId, ExtensionRequirement, FocusedItem, FocusedItemToolbarProps, InlineEditorsProps, InputModifiers, JsonObject, JsonValue, LocalBoard, LocalBoardSnapshot, Mat2x3, MultiplayerCursorsProps, ObjectDescribeContext, ObjectIntent, ObjectType, PresenceCursor, PresenceUser, PresenceView, QueryableBoardObject, ReadonlyCustomObject, SceneEllipse, SceneGroup, SceneImage, ScenePath, SceneRect, SceneText, ScrawlBoardProps, ScrawlCanvasProps, ScrawlDefaultUIProps, ScrawlDensity, ScrawlExtension, ScrawlGridMode, ScrawlProps, ScrawlProviderProps, ScrawlResolvedTheme, ScrawlSurfaceTexture, ScrawlTheme, ScrawlThemeDiagnostic, ScrawlThemePreset, StyleShelfProps, SupportedAssetMediaType, ToolCancelReason, ToolCapabilities, ToolCursor, ToolId };