@scrawl-board/board 0.1.0-beta.1 → 0.1.0-beta.3

package/dist/react.d.ts

@@ -371,8 +371,13 @@ interface StrokePoint extends BoardPoint {
      */
     erase?: number;
 }
-/** Which drawing tool made a stroke; undefined means marker (back-compat). */
-type StrokeTool = "marker" | "highlighter";
+/**
+ * Which drawing tool made a stroke; undefined means marker (back-compat).
+ * `"shape"` (rect/ellipse/line/arrow/polygon/star/heart) renders at its
+ * exact configured width with no pressure variance or end taper — a
+ * geometric outline, not an expressive ink mark.
+ */
+type StrokeTool = "marker" | "highlighter" | "shape";
 interface Stroke extends Lockable {
     id: string;
     color: string;
@@ -685,6 +690,27 @@ interface BoardView {
     y: number;
     zoom: number;
 }
+/**
+ * The rendered board surface's color, reference grid, and shape stroke
+ * width — the subset of {@link ScrawlTheme} that reaches the rendering
+ * engine directly (everything else is UI-chrome-only, applied as CSS). Any
+ * field left unset keeps its current value.
+ */
+interface BoardThemeOptions {
+    /** The board/canvas background color — distinct from UI chrome panels. */
+    surface?: string;
+    /** `"flat"` (default): a plain, uniform board surface. `"textured"`: a subtle "melamine" micro-noise + satin sheen, like a physical whiteboard. */
+    surfaceTexture?: "flat" | "textured";
+    /** `"none"` (default) keeps the board a plain surface; `"line"`/`"dot"` draw a zoom-adaptive reference grid. */
+    gridMode?: "none" | "line" | "dot";
+    gridColor?: string;
+    /** Grid spacing in board units at 100% zoom. Ignored when `gridMode` is `"none"`. */
+    gridSpacing?: number;
+    /** On-screen grid line/dot width in CSS pixels — stays this width at any zoom, since the grid is a reference aid, not content. */
+    gridLineWidth?: number;
+    /** Shape (rectangle, ellipse, arrow, ...) border width, in board units — scales with zoom like ink, since it's part of the drawn content. */
+    shapeStrokeWidth?: number;
+}
 /**
  * A Host-owned comment, summarized for Board-side search and marker
  * rendering. Comments are not Document content — they carry no undo
@@ -895,12 +921,7 @@ interface CreateBoardControllerOptions {
      * changes via `boardTheme.set` below — a headless/browser-tier Host that
      * doesn't use the React theme system can set this directly instead.
      */
-    boardTheme?: {
-        surface?: string;
-        gridMode?: "none" | "line" | "dot";
-        gridColor?: string;
-        gridSpacing?: number;
-    };
+    boardTheme?: BoardThemeOptions;
 }
 interface BoardController {
     readonly document: ReadonlyBoardDocument;
@@ -927,13 +948,8 @@ interface BoardController {
         redo(): void;
     };
     readonly boardTheme: {
-        /** Live update of the board surface color/grid — the controller's identity stays fixed across theme changes. */
-        set(theme: {
-            surface?: string;
-            gridMode?: "none" | "line" | "dot";
-            gridColor?: string;
-            gridSpacing?: number;
-        }): void;
+        /** Live update of the board surface color/grid/shape-stroke-width — the controller's identity stays fixed across theme changes. */
+        set(theme: BoardThemeOptions): void;
     };
     readonly view: {
         fit(): void;
@@ -1032,37 +1048,82 @@ type LocalBoard = {
 type ScrawlThemePreset = "light" | "dark";
 type ScrawlDensity = "comfortable" | "compact";
 type ScrawlGridMode = "none" | "line" | "dot";
+type ScrawlSurfaceTexture = "flat" | "textured";
+/**
+ * Every field is optional — anything you don't set falls back to the
+ * chosen `preset` ("light" or "dark", see {@link resolveScrawlTheme}).
+ * Overrides are semantic, board-local runtime configuration: they never
+ * get written into the Document or into exports, so switching themes is
+ * always non-destructive.
+ */
 interface ScrawlTheme {
+    /** UI chrome background — toolbar/panel base surface. Distinct from `boardSurface` (the canvas itself). */
     surface?: string;
+    /** UI chrome background, one step up from `surface` — popovers, dropdowns, elevated panels. */
     surfaceRaised?: string;
+    /** UI chrome background, one step down from `surface` — subtle fills, hover states. */
     surfaceMuted?: string;
+    /** Primary UI text color. Checked for contrast against `surface`. */
     text?: string;
+    /** Secondary/de-emphasized UI text color. Checked for contrast against `surface`. */
     textMuted?: string;
+    /** Borders and dividers between UI chrome elements. */
     edge?: string;
+    /**
+     * Brand accent color. Drives the active/selected state of toolbar
+     * controls (e.g. the active tool button): its icon/text render in this
+     * color, and its background is automatically derived as a light tint of
+     * it (via `color-mix`) — set this one token and both follow.
+     */
+    primary?: string;
+    /** Focus ring color. Checked for contrast against `surface`. */
     focus?: string;
+    /** Selection highlight color (e.g. selected list items, not board object selection). */
     selection?: string;
+    /** Destructive/error state color (delete confirmations, error text). */
     danger?: string;
+    /** Warning state color. */
     warning?: string;
+    /** Success/confirmation state color. */
     success?: string;
+    /** Font stack for UI chrome (toolbar labels, menus, dialogs). */
     uiFontFamily?: string;
+    /** Font stack for board content and data (e.g. table cell text). */
     dataFontFamily?: string;
+    /** Base UI font size in px. Range: 12–24. */
     baseFontSize?: number;
+    /** Regular UI font weight. Range: 300–900. */
     regularWeight?: number;
+    /** Emphasized UI font weight (headings, active states). Range: 300–900. */
     strongWeight?: number;
+    /** Corner radius for small controls (buttons, inputs) in px. Range: 0–32. */
     controlRadius?: number;
+    /** Corner radius for panels/dialogs in px. Range: 0–32. */
     panelRadius?: number;
+    /** CSS `box-shadow` value for subtle elevation (e.g. toolbar). */
     elevationLow?: string;
+    /** CSS `box-shadow` value for prominent elevation (e.g. modals). */
     elevationHigh?: string;
+    /** UI transition duration in ms. Range: 0–500. */
     motionDuration?: number;
+    /** CSS easing function for UI transitions. */
     motionEasing?: string;
+    /** UI chrome spacing/sizing scale. */
     density?: ScrawlDensity;
     /** The rendered board/canvas surface color — distinct from `surface` (UI chrome panels). */
     boardSurface?: string;
+    /** `"flat"` (default): a plain, uniform board surface. `"textured"`: a subtle "melamine" micro-noise + satin sheen, like a physical whiteboard. */
+    boardSurfaceTexture?: ScrawlSurfaceTexture;
     /** `"none"` (default) keeps the board a plain surface; `"line"`/`"dot"` draw a zoom-adaptive reference grid. */
     gridMode?: ScrawlGridMode;
+    /** Grid line/dot color. Ignored when `gridMode` is `"none"`. */
     gridColor?: string;
     /** Grid spacing in board units at 100% zoom. Ignored when `gridMode` is `"none"`. */
     gridSpacing?: number;
+    /** On-screen grid line/dot width in CSS pixels. Range: 0.5–8. A reference aid, so unlike shape/ink strokes it stays this width at any zoom. */
+    gridLineWidth?: number;
+    /** Shape (rectangle, ellipse, arrow, ...) border width, in board units. Range: 0.01–5. Scales with zoom like ink, since it's part of the drawn content. */
+    shapeStrokeWidth?: number;
 }
 type ResolvedScrawlTheme = Required<ScrawlTheme>;
 interface ScrawlThemeDiagnostic {
@@ -1087,6 +1148,19 @@ interface DefaultBoardChromeProps {
     style?: React.CSSProperties;
     regions?: Partial<Record<DefaultUIRegion, boolean>>;
     slots?: DefaultUISlots;
+    /**
+     * Swap in your own icon for a tool's primary toolbar button — pass any
+     * icon from any library (`<Pencil />`, `<Icon icon="..." />`, an inline
+     * `<svg>`, whatever). A tool with no entry here keeps its default text
+     * label, so this is opt-in per tool, not all-or-nothing. Aria labeling
+     * and the keyboard-shortcut tooltip stay text-based regardless, so the
+     * board remains fully accessible even with icon-only buttons.
+     *
+     * Only affects the six primary toolbar buttons (select/marker/
+     * highlighter/eraser/note/text) — the "more tools" overflow menu is a
+     * native `<select>`, which can only render plain text `<option>`s.
+     */
+    icons?: Partial<Record<BuiltInTool, ReactNode>>;
 }
 type DefaultUIRegion = "tools" | "history" | "view" | "style" | "search" | "import" | "export" | "inlineEditing" | "styleShelf";
 /** Props for the toolbar/topBar/stylePanel/contextMenu slots. */
@@ -1116,7 +1190,7 @@ interface DefaultUISlots {
      */
     contextMenu?: ComponentType<BoardSlotProps> | null;
 }
-declare function DefaultBoardChrome({ controller, snapshot, renderPortal, className, style, regions, slots }: DefaultBoardChromeProps): react.JSX.Element;
+declare function DefaultBoardChrome({ controller, snapshot, renderPortal, className, style, regions, slots, icons }: DefaultBoardChromeProps): react.JSX.Element;
 
 interface InlineEditorsProps {
     controller: BoardController;
@@ -1173,8 +1247,14 @@ interface ScrawlProps extends Omit<CreateBoardControllerOptions, "canvas"> {
     onThemeDiagnostic?: (diagnostic: ScrawlThemeDiagnostic) => void;
     /** Provide null for a headless Board, or an existing canvas to control its identity. */
     canvas?: HTMLCanvasElement | null;
+    /**
+     * Per-tool icon override for the default toolbar's primary buttons —
+     * only applies when you don't supply `children` (i.e. you're using the
+     * SDK's default UI). See DefaultBoardChromeProps.icons.
+     */
+    icons?: Partial<Record<BuiltInTool, ReactNode>>;
 }
-declare function Scrawl({ children, preset, theme, portalContainer, className, style, onReady, onError, onThemeDiagnostic, canvas: suppliedCanvas, ...options }: ScrawlProps): react.JSX.Element;
+declare function Scrawl({ children, preset, theme, portalContainer, className, style, onReady, onError, onThemeDiagnostic, canvas: suppliedCanvas, icons, ...options }: ScrawlProps): react.JSX.Element;
 interface ScrawlCanvasProps {
     element?: HTMLCanvasElement;
     className?: string;
@@ -1189,8 +1269,10 @@ interface ScrawlDefaultUIProps {
     regions?: Partial<Record<DefaultUIRegion, boolean>>;
     /** Replace (component) or hide (null) a coarse region; omit for the SDK default. */
     slots?: DefaultUISlots;
+    /** Per-tool icon override for the primary toolbar buttons — see DefaultBoardChromeProps.icons. */
+    icons?: Partial<Record<BuiltInTool, ReactNode>>;
 }
-declare function ScrawlDefaultUI({ className, style, regions, slots }: ScrawlDefaultUIProps): react.JSX.Element;
+declare function ScrawlDefaultUI({ className, style, regions, slots, icons }: ScrawlDefaultUIProps): react.JSX.Element;
 declare function ScrawlPortal({ children }: {
     children: ReactNode;
 }): react.ReactPortal | null;
@@ -1207,4 +1289,4 @@ 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, 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, ScrawlTheme, ScrawlThemeDiagnostic, ScrawlThemePreset, StyleShelfProps, SupportedAssetMediaType, ToolCancelReason, ToolCapabilities, ToolCursor, ToolId };
+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 };