hb-stylus-notebook — integrator guide

Category: inputs · Tags: inputs, drawing · Package: @htmlbricks/hb-stylus-notebook

Declared layout size: fullscreen (see extra/docs.ts).

Summary

hb-stylus-notebook is a notebook shell around the drawing web component hb-stylus-paper. It renders a toolbar (part="controller") and a paper region (part="paper-container") that hosts the nested canvas. The shell wires mode switching (draw / select / eraser), undo/redo, a Save action that exports the current drawing as JSON via a download, load and insert flows using hb-input-file, and optional restoration of strokes from a load_draw payload.

Peer components: this package expects hb-stylus-paper and hb-input-file to be registered (see extra/docs.ts → dependencies).

Custom element

hb-stylus-notebook

Attributes (snake_case, string-friendly)

HTML and setAttribute only expose strings. Serialize objects as JSON strings.

| Attribute | Required | Description | | --- | --- | --- | | id | No | Optional host identifier string. | | style | No | Optional inline style string (reserved in typings; not applied inside component.wc.svelte today). | | load_draw | No | JSON string of a saved notebook payload (TSave). When the value is a non-empty string, the component attempts JSON.parse in an effect. Passed through to hb-stylus-paper as a serialized string when set. |

load_draw / save payload shape (TSave)

From types/webcomponent.type.d.ts:

• type: "pdf" | "json" | "png" | "svg" | "jpg"
• draw: array of IStroke objects (strokes, multipaths, eraser, move, etc.)
• id, draw_id, name, version: strings / numbers as defined in the type file

Strokes include fields such as type, id, visible, actionIndex, optional path, pathData, color, opacity, bounds min/max, and related metadata. Treat the typings as the source of truth for exact fields.

Toolbar and nested paper (runtime behavior)

The controller part contains:

• clear — switches hb-stylus-paper to eraser mode
• select — select mode
• draw — draw mode
• undo / redo — driven by history index from the paper’s historyIndex event
• save — sets an internal save_as { name: "test", type: "json" }, then clears it after the paper fires save; the handler downloadObjectAsJson saves {detail}.name + ".json"
• brush — disabled unless mode is draw
• load — hb-input-file reads a text file and **JSON.parse**s it into load_draw
• insert — hb-input-file reads an image file as data URL and passes insert_image to the paper (PNG/JPG inferred from the data URL)

The paper-container part wraps hb-stylus-paper with props including mode, goto (history navigation), save_as, load_draw, insert_image, insert_text, background_color (currently "green" in source), and listeners for historyIndex and save.

Events

No custom events are declared for this component (Events is {} in types/webcomponent.type.d.ts).

Styling

• Bulma 1.x is included for the shell; theme with --bulma-* variables on :host or ancestors (see Bulma CSS variables).

CSS custom properties (styleSetup)

| Variable | Role | | --- | --- | | --bulma-scheme-main-bis | Background behind the nested paper in #paper-container (falls back in SCSS if unset). |

CSS parts

| Part | Role | | --- | --- | | controller | Toolbar row: modes, undo/redo, save, and file inputs. | | paper-container | Region that hosts hb-stylus-paper. |

Layout (styles/webcomponent.scss)

:host is a fullscreen-sized grid (position: absolute; inset: 0; width/height 100%) with rows header (toolbar) and paper (canvas area, min-height: 0 for correct flex/grid scrolling).

Slots

None (htmlSlots is empty in extra/docs.ts).

Examples

Minimal

<hb-stylus-notebook></hb-stylus-notebook>

With load_draw (attribute must be a JSON string)

<hb-stylus-notebook
  load_draw='{"type":"json","id":"stylus-paper","draw_id":"example","name":"sketch","version":0,"draw":[]}'
></hb-stylus-notebook>

Replace the JSON value with a real TSave payload exported from your app or from a previous session.

Related packages

• @htmlbricks/hb-stylus-paper — drawing surface API (modes, history, save detail, inserts).
• @htmlbricks/hb-input-file — file picking for load / insert rows in the toolbar.

License

See extra/docs.ts → licenses (Apache-2.0 entry) for catalog metadata.