@inkbar/svelte 0.10.0 → 0.12.0

package/README.md

@@ -30,7 +30,7 @@ Annotations are plain typed objects. Bind them with `bind:annotations` to keep t
 pnpm add @inkbar/svelte @inkbar/core @inkbar/theme
 ```
 
-Svelte 5.46.4 or later is a peer dependency. Add the Vite plugin from `@inkbar/core/vite` so PDF.js can load its worker and fonts; the [`@inkbar/core` README](https://github.com/inkbar/inkbar/tree/main/packages/core#serving-pdfjs-assets) covers it. The package ships `.svelte` sources, so your bundler compiles them for your target, including the server.
+`@inkbar/core` (installed above, at the same version) and Svelte 5.46.4 or later are peer dependencies. Add the Vite plugin from `@inkbar/core/vite` so PDF.js can load its worker and fonts; the [`@inkbar/core` README](https://github.com/inkbar/inkbar/tree/main/packages/core#serving-pdfjs-assets) covers it. The package ships `.svelte` sources, so your bundler compiles them for your target, including the server.
 
 ## Usage
 
@@ -64,7 +64,7 @@ Svelte 5.46.4 or later is a peer dependency. Add the Vite plugin from `@inkbar/c
   const tools = [highlightTool(), redactAreaTool(), noteTool()]
 </script>
 
-<InkRoot src={{ url: signedUrl, key: documentId }} {assets} {tools} bind:annotations>
+<InkRoot src={{ url: signedUrl, key: documentId }} {assets} {tools} bind:annotations history={true}>
   <InkToolbar>
     <InkToolButton tool="select-text" />
     <InkToolButton tool="select" />
@@ -89,9 +89,9 @@ Svelte 5.46.4 or later is a peer dependency. Add the Vite plugin from `@inkbar/c
 </InkRoot>
 ```
 
-`select-text` and `select` are always there. Every other tool is opt-in: pass the ones you offer through `tools`, from the tool factories in `@inkbar/core/dom`, or `allTools()` for all of them. A button for a tool you did not pass renders disabled and hidden, a tool menu renders nothing, and each logs an `InkError('UnknownTool')` to the console once. If the active tool leaves `tools`, the viewer switches to `select-text` and reports it through `onToolChange`.
+`select-text` and `select` are always there. Every other tool is opt-in: pass the ones you offer through `tools`, from the tool factories in `@inkbar/core/dom`, or `allTools()` for all of them. A button for a tool you did not pass renders empty, disabled and `aria-hidden`, the highlight, shape and signature menus render nothing, and each logs an `InkError('UnknownTool')` to the console once. If the active tool leaves `tools`, the viewer switches to `select-text` and reports it through `onToolChange`.
 
-Each toolbar control is a component, so keep the ones you need and put them where you like. Buttons show icons from `@inkbar/icons`. Pass your own as `children` to replace one, and use `InkIcon` to put the same icons on your own buttons. For a button of your own, such as `<InkToolbarButton onclick={download}>Download</InkToolbarButton>`, use `InkToolbarButton`: it joins the toolbar's arrow-key focus and looks like the other buttons. `bind:annotations` makes your list the source of truth. Leave it off and Inkbar keeps the state itself, with undo and redo.
+Each toolbar control is a component, so keep the ones you need and put them where you like. Buttons show icons from `@inkbar/icons`. Pass your own as `children` to replace one, and use `InkIcon` to put the same icons on your own buttons. For a button of your own, such as `<InkToolbarButton onclick={download}>Download</InkToolbarButton>`, use `InkToolbarButton`: it joins the toolbar's arrow-key focus and looks like the other buttons. `bind:annotations` makes your list the source of truth, and `history={true}` keeps undo and redo working with it. Leave the binding off and Inkbar keeps the state itself, with undo and redo on by default.
 
 ## Controlled mode
 
@@ -149,9 +149,17 @@ Inside `InkRoot`, `useHistory()` returns the same object. Its `batch(fn)` runs `
 
 `key` identifies the document. Reuse the same key when only the signed URL changes and the document is not reloaded.
 
+`InkRoot` takes a few more options. `password` opens an encrypted PDF. `storage` sets what the viewer keeps between visits (see [Storage](#storage)). `defaults` sets annotation colours; without it the theme's CSS variables apply. `fonts` sets the families the text style menu offers. `decorateAnnotation` adds attributes, classes and a screen-reader description to each annotation. `bind:page` and `bind:zoom` (or `onPageChange` and `onZoomChange`) follow and drive the viewport, and `bind:tool` (or `onToolChange`) does the same for the active tool. `onError` hears failed opens, form script errors and refused signings. `onActivate` hears the id of each activated annotation. `onFieldsChange` hears form value changes.
+
+## Viewport
+
+`InkViewport` takes `mode`, `rotation`, `gap` (CSS pixels between pages, default 16), `buffer` (pages kept mounted either side of the visible ones, default 2) and `pinchZoom` (default `true`; `false` leaves pinches to the browser, which zooms the whole page). A change to `gap`, `buffer` or `pinchZoom` rebuilds the engine.
+
+On a touch screen, two fingers pinch to zoom the document and scroll it. With `draw`, `sketch`, `shape`, `redact-area` and `freetext`, one finger draws; a finger tap draws nothing, and a pen that lands while a palm rests on the screen takes over. A shape, area redaction or text box gives one-finger scrolling back once it has made something.
+
 ## Forms
 
-`InkViewport` fills the PDF's form fields and runs the form's scripts. `useForm()` returns the fields, their values, and `set` and `reset`. Use `bind:fields` to hold the values in your own state. The form never submits, opens a link, sends mail or prints: `onformaction` hands each request to you. `formHighlight={false}` turns off the field tint, and a change applies to the open document in place.
+`InkViewport` fills the PDF's form fields and runs the form's scripts. `useForm()` returns the fields, their values, and `set` and `reset`. Use `bind:fields` to hold the values in your own state. The form never submits, opens a link, sends mail or prints: `onaction` hands each request to you; so does a link to a URL. `onformaction` still works until 0.13.0. `formHighlight={false}` turns off the field tint, and a change applies to the open document in place.
 
 The [forms guide](https://inkbar.dev/docs/guides/forms/) covers controlled fields, form actions, scripts, signature fields and saving values as Gloss.
 
@@ -163,9 +171,26 @@ A root note with no text and no replies is removed when its popover closes, or w
 
 The highlight tool leaves `contents` free for the comment. `doc.text(page)` returns the page's text items; match the markup's `quads` against them to get the marked text. `InkHighlightMenu` is a split button for the tool: it picks the markup kind and its colour.
 
+## Style menus
+
+`InkColorMenu` (`property="border"`, `"fill"` or `"text"`), `InkLineStyleMenu` (weight, dashes, arrowheads) and `InkTextStyleMenu` (font, size, colour, bold, italic, underline, alignment) edit the selection, or the active tool's style when nothing is selected. A menu disables when nothing supports its properties. `InkShapeMenu` is a split button for the `shape` tool and renders nothing unless `shapeTool` is in `tools`. `fonts` on `InkRoot` sets the families the text style menu offers.
+
 ## Signatures
 
-`InkSignatureMenu` lists saved signatures, picks one for the `signature` tool, removes them, and opens `InkSignatureDialog` to draw, type or upload a new one. The menu needs `signatureTool()` in `tools`. The dialog and signature form fields work without it; the dialog then only saves the signature. These are marks on the page, not cryptographic signatures. Pass `signatures` to `InkRoot` to keep them somewhere: `createLocalSignatureStore(key)` from `@inkbar/core` uses `localStorage`, and without it they last until reload. `signatureFonts` lists the handwriting fonts the Type tab offers; load them with `@font-face`. A placed signature keeps its aspect ratio when resized.
+`InkSignatureMenu` lists saved signatures, picks one for the `signature` tool, removes them, and opens `InkSignatureDialog` to draw, type or upload a new one. The menu needs `signatureTool()` in `tools`. The dialog and signature form fields work without it; the dialog then only saves the signature. These are marks on the page, not cryptographic signatures. `InkRoot` keeps them in its `storage` under the key `signatures`, so without a store they last until reload. A `signatures` store of your own still works and wins over `storage` until 0.13.0, which removes it. `signatureFonts` lists the handwriting fonts the Type tab offers; load them with `@font-face`. A placed signature keeps its aspect ratio when resized.
+
+## Storage
+
+`InkRoot` keeps a few small things between visits: saved signatures, sidebar widths and plugin settings. Pass `storage` to choose where. `createLocalStorage()` from `@inkbar/core` keeps them in `localStorage`, and any `InkStorage` works, including an async one that talks to your server. The default is `createMemoryStorage()`, which forgets everything on reload. Inkbar never touches `localStorage`, cookies or the network unless the store you pass does. The root reads `storage` once, when it is created. See the [`@inkbar/core` README](https://github.com/inkbar/inkbar/tree/main/packages/core#storage) for the keys.
+
+```svelte
+<script lang="ts">
+  import { createLocalStorage } from '@inkbar/core'
+  const storage = createLocalStorage()
+</script>
+
+<InkRoot {src} {assets} {storage}>
+```
 
 ## Plugins
 
@@ -187,7 +212,7 @@ Plugin stores undo with annotations. In controlled mode with `history`, each und
 
 ## Search
 
-`InkFindBar` is the find bar and `InkSearchButton` opens it. Place the bar anywhere inside `InkRoot`, once `InkViewport` is there; Ctrl/Cmd+F opens it while it is mounted. `useSearch()` returns the search `state` and its actions (`open`, `setQuery`, `setMatchCase`, `next`, `previous`, `close`) for your own control. See the [`@inkbar/core` README](https://github.com/inkbar/inkbar/tree/main/packages/core#search) for the API.
+`InkFindBar` is the find bar and `InkSearchButton` opens it. Place the bar anywhere inside `InkRoot`, once `InkViewport` is there; Ctrl/Cmd+F opens it while it is mounted. `useSearch()` returns the search `state` and its actions (`open(query?)`, `setQuery`, `setMatchCase`, `next`, `previous`, `select`, `close`) for your own control. See the [`@inkbar/core` README](https://github.com/inkbar/inkbar/tree/main/packages/core#search) for the API.
 
 The bar handles Escape itself and stops it there, so an `onkeydown` you pass to `InkFindBar` never sees Escape.
 
@@ -196,6 +221,10 @@ The bar handles Escape itself and stops it there, so an `onkeydown` you pass to
 `InkSidebar` holds `InkPanel`s and places nothing itself: put it beside `InkViewport` with your own flex or grid layout. Each panel has an `id`, a `label`, an optional `icon` (an `IconNode` from `@inkbar/icons`) and an optional `badge`, a number or short string hidden when empty or 0. Its children are the panel's content, your own component or one of Inkbar's.
 
 ```svelte
+<script lang="ts">
+  import { Square, MessageSquare } from '@inkbar/icons'
+</script>
+
 <InkRoot {src} {assets}>
   <div class="app">
     <InkSidebar side="left" layout="rail" bind:open>
@@ -213,7 +242,13 @@ The bar handles Escape itself and stops it there, so an `onkeydown` you pass to
 
 `layout` is `rail` (default: icon buttons beside the document, and activating the open panel's button closes it), `tabs` (labelled tabs, one panel open) or `stack` (a header per panel, any number expanded). `side` (`left` by default) decides which edge the rail and border sit on. `bind:open` is the open panel's id, or `null`, for rail and tabs, and the expanded ids for stack. Left out, the first panel starts open. When the open panel goes (an `{#if}`), rail and tabs open the first one left and stack drops it, and the bound `open` receives the new value. In the rail, the open panel shows its label as a title above its content. `visible` (default `true`) shows or hides the whole sidebar; it keeps the open panel, its content and its scroll for when it shows again. Your code decides when: `visible={hits > 0}` keeps a results sidebar out of the way until a search finds something.
 
-Panels take their place in the order they appear in the markup, including one added later with `{#if}`. A closed panel stays mounted and hidden, so its content keeps its state and scroll position, across layout changes too. The keys and ARIA are core's: see the [`@inkbar/core` README](https://github.com/inkbar/inkbar/tree/main/packages/core#sidebars). The sidebar needs no document and works outside `InkRoot`. On the server it renders its frame with the open panel showing, and the stack headers; rail and tab buttons follow once it has mounted.
+Panels take their place in the order they appear in the markup, including one added later with `{#if}`. A closed panel stays mounted and hidden, so its content keeps its state and scroll position, across layout changes too. The keys and ARIA are core's: see the [`@inkbar/core` README](https://github.com/inkbar/inkbar/tree/main/packages/core#sidebars). The sidebar needs no document and works outside `InkRoot`. On the server it renders its frame at its width with the open panel showing, the stack headers and the resize handle; rail and tab buttons follow once it has mounted.
+
+Each sidebar has a resize handle on its inner edge. Drag it, or focus it and use the arrow keys (16px a step), Home and End. Enter or a double-click resets the width. The width starts at `defaultWidth` (320) and stays between `minWidth` (240) and `maxWidth` (480), and never past half of the sidebar's container. The sidebar sets `--ink-sidebar-width` inline, so a CSS override of it no longer applies. Pass `defaultWidth` instead. Inside `InkRoot` the sidebar saves its width in the root's `storage` under `sidebar.<name>.width`, where `name` defaults to the side; give two sidebars on one side different names. Pass `storage` to the sidebar to use another store, or to save its width outside `InkRoot`. The sidebar reads `storage` and `name` once, when it is created. To control the width, bind `width` to a number: the handle then only updates the binding, and the sidebar neither reads nor writes storage. Bind it to a value that starts `undefined` and you only receive the width; the sidebar keeps saving it.
+
+```svelte
+<InkSidebar name="tools" side="right" defaultWidth={360} bind:width={toolsWidth}>
+```
 
 ## Thumbnails
 
@@ -231,6 +266,20 @@ Panels take their place in the order they appear in the markup, including one ad
 
 An item's height is worked out from its page alone, so position what you add absolutely. The `item` snippet renders inside the item's `<button>`: keep it non-interactive, with no links, buttons or inputs. Both need `InkRoot` and render empty on the server.
 
+## Outline and Back
+
+`InkOutline` shows the document's outline as a tree. Clicking an item, or Enter on it, follows it: a destination scrolls there (without changing the zoom), a web address goes to the host as an `open-url` action. The chevron expands and collapses an item without following it. The item the reader has reached is marked `aria-current="location"` and kept in view. It fills its parent's height and scrolls, so put it in a panel:
+
+```svelte
+<InkPanel id="outline" label="Outline" icon={List}>
+  <InkOutline emptyText="No outline" />
+</InkPanel>
+```
+
+`emptyText` is shown when the document has no outline. The `item` snippet, given the item and `{ current, expanded }`, replaces an item's title. The keys and ARIA are core's, as in the thumbnails. Needs `InkRoot`; the tree renders empty on the server.
+
+`InkBack` and `InkForward` return to where the view was before a jump (a link, an outline item) and undo that. Each is disabled until there is somewhere to go, and takes a `child` snippet. Put them in an `InkToolbar`.
+
 ## Record lists
 
 `InkRecordList` lists a plugin's records as cards, the same cards their marks open, with the same actions. Name the records `<plugin>.<name>`:
@@ -243,7 +292,7 @@ An item's height is worked out from its page alone, so position what you add abs
 </InkPanel>
 ```
 
-The list and the marks share one selection: choosing a card selects its mark and scrolls the viewer there, and activating a mark selects its card. Each action runs in one undo step. `card`, `where` and `sort` replace the marks' card, filter and reading order. A new function rebuilds the list, so define them once in the script, never inline in the markup. `bind:count` receives the number listed whenever it changes, ready for a panel badge. The `empty` snippet replaces "Nothing here yet.". To list something of your own, pass a `source` (a `RecordListSource`, as core's `recordsSource` and `searchSource` build) in place of `records`: it gets the same cards, keys and selection. With both, `source` wins.
+The list and the marks share one selection: choosing a card selects its mark and scrolls the viewer there, and activating a mark selects its card. Each action runs in one undo step. `card`, `where` and `sort` replace the marks' card, filter and reading order. A new function rebuilds the list, so define them once in the script, never inline in the markup. They do not apply to a `source`, which carries its own. `bind:count` receives the number listed whenever it changes, ready for a panel badge. The `empty` snippet replaces "Nothing here yet.". To list something of your own, pass a `source` (a `RecordListSource`, as core's `recordsSource` and `searchSource` build) in place of `records`: it gets the same cards, keys and selection. With both, `source` wins.
 
 `InkSearchResults` is the same list over the document search: one card per hit, titled with its page ("Page 2"), with its place on that page ("Match 3") and the text around it. Choosing a card makes its hit current, as the find bar's next and previous do. It has its own field, labelled "Find in document", above the cards and the find bar's match count in a footer below them; `field={false}` leaves the field out when a find bar is on the page. Field and find bar share the search state, so they never disagree.
 
@@ -251,11 +300,11 @@ To build your own, `useRecords<T>(name)` returns the live `records` and the `han
 
 ## Custom rendering
 
-Slots are snippets. `InkViewport` takes `loading`, `empty`, `error`, `annotation` and `pageError`. `InkThreadPopover` takes `children` as a snippet that receives the popover's props. `InkToolButton` takes `children` as a snippet of `{ active, label }`, and `InkCommand` one of `{ label, busy }`. `InkThumbnails` takes `item`, and `InkRecordList` takes `empty`. The props each receives are typed as `AnnotationSlotProps` and `ThreadPopoverSlotProps`, the same types the Vue and React packages export.
+Slots are snippets. `InkViewport` takes `loading`, `empty`, `error`, `annotation` and `pageError`. `InkThreadPopover` takes `children` as a snippet that receives the popover's props. `InkToolButton` takes `children` as a snippet of `{ active, label }`, and `InkCommand` one of `{ label, busy }`. `InkThumbnails` and `InkOutline` take `item`, and `InkRecordList` takes `empty`. The props each receives are typed as `AnnotationSlotProps` and `ThreadPopoverSlotProps`, the same types the Vue and React packages export.
 
 `InkDownloadButton` and `InkPrintButton` download and print the open PDF; `filename` names the download (the opened `File`'s name, else the URL's last segment, else `document.pdf`). Printing loads the file into a hidden frame and opens the browser's print dialog for it; on iOS the PDF opens in a new tab instead. Until saving into the PDF ships, both give the file as it was opened, without this session's annotations.
 
-`InkRoot`, `InkToolbar`, `InkToolButton`, `InkCommand`, `InkUndo`, `InkRedo`, `InkDownloadButton`, `InkPrintButton`, `InkPrevPage`, `InkNextPage`, `InkZoomIn` and `InkZoomOut` take a `child` snippet to render your own element. Spread the `props` it gives you on that element. The snippet type is exported as `ChildSnippet`.
+`InkRoot`, `InkToolbar`, `InkToolButton`, `InkToolbarButton`, `InkCommand`, `InkUndo`, `InkRedo`, `InkDownloadButton`, `InkPrintButton`, `InkSearchButton`, `InkPrevPage`, `InkNextPage`, `InkBack`, `InkForward`, `InkZoomIn` and `InkZoomOut` take a `child` snippet to render your own element. Spread the `props` it gives you on that element. The snippet type is exported as `ChildSnippet`.
 
 ```svelte
 <InkToolbar>
@@ -277,11 +326,12 @@ The scroll area takes focus. From there:
 
 On a focused annotation:
 
-- `Enter` or `Space` selects and activates it. A note or text markup opens its thread; other types are only selected.
+- `Enter` or `Space` selects and activates it. A note or text markup opens its thread; other types are only selected. `Enter` on an editable text box opens its editor instead.
 - `ArrowUp` and `ArrowDown` move to the previous or next annotation on the page.
 - `Shift` + arrow moves it by 1 pt, or by 10 pt with `Alt` as well.
 - `Ctrl` or `Cmd` + `Shift` + arrow resizes an area redaction, text box or shape.
 - `Delete` or `Backspace` removes it.
+- `Escape` clears the selection.
 
 The full table, with the zoom and page keys, is in the [`@inkbar/core` README](https://github.com/inkbar/inkbar/tree/main/packages/core#tools-and-keyboard).
 
@@ -291,7 +341,7 @@ Components carry state on data attributes, for example `[data-annotation][data-s
 
 ## Hooks
 
-`useDocument`, `useAnnotations`, `useTool`, `useSelection`, `useZoom`, `usePage`, `useHistory`, `useEmbedded`, `useCommand`, `useRecords` and `useRecordSelection` read the state of the nearest `InkRoot`. Call them during component initialisation, as you would `getContext`. Each returns an object whose reactive members are getters: read `useZoom().zoom` in your template or an effect and it tracks; destructure it (`const { zoom } = useZoom()`) and you copy the value once. Keep the object and read through it. Tool options, such as the shape kind, last as long as `InkRoot`. The tool style that `useToolStyle` reads and sets (colours, line style, text style) belongs to the document: opening another one starts again from the theme's defaults.
+`useDocument`, `useAnnotations`, `useTool`, `useSelection`, `useZoom`, `usePage`, `useHistory`, `useEmbedded`, `useCommand`, `useForm`, `useSearch`, `useToolStyle`, `useToolOptions`, `useRecords` and `useRecordSelection` read the state of the nearest `InkRoot`. Call them during component initialisation, as you would `getContext`. Each returns an object whose reactive members are getters: read `useZoom().zoom` in your template or an effect and it tracks; destructure it (`const { zoom } = useZoom()`) and you copy the value once. Keep the object and read through it. `useToolOptions('shape')` reads and sets a tool's options, such as the shape kind, which last as long as `InkRoot`. The tool style that `useToolStyle` reads and sets (colours, line style, text style) belongs to the document: opening another one starts again from the theme's defaults.
 
 ## Licence
 

package/dist/components/InkBack.svelte

@@ -0,0 +1,40 @@
+<script lang="ts">
+  import { ArrowLeft } from '@inkbar/icons'
+  import { Toolbar } from 'bits-ui'
+
+  import { useInkContext } from '../context.js'
+  import { useReadable } from '../use-readable.svelte.js'
+
+  import { asBitsProps } from './child-snippet.js'
+  import InkIcon from './InkIcon.svelte'
+
+  import type { InkPageButtonProps } from './page-button.js'
+
+  let {
+    class: className,
+    children,
+    child,
+    disabled,
+    onclick,
+    ...rest
+  }: InkPageButtonProps = $props()
+
+  const ctx = useInkContext('InkBack')
+  const can = useReadable(() => ctx.navigation?.canGoBack, false)
+</script>
+
+<Toolbar.Button
+  class={['ink-back', className]}
+  data-ink-back=""
+  aria-label="Back"
+  title="Back"
+  disabled={!can.current || !!disabled}
+  {...child ? { child } : {}}
+  {...asBitsProps(rest)}
+  onclick={(e) => {
+    onclick?.(e)
+    if (!e.defaultPrevented) ctx.navigation?.back()
+  }}
+>
+  {#if children}{@render children()}{:else}<InkIcon icon={ArrowLeft} />{/if}
+</Toolbar.Button>

package/dist/components/InkBack.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { InkPageButtonProps } from './page-button.js';
+declare const InkBack: import("svelte").Component<InkPageButtonProps, {}, "">;
+type InkBack = ReturnType<typeof InkBack>;
+export default InkBack;
+//# sourceMappingURL=InkBack.svelte.d.ts.map

package/dist/components/InkBack.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InkBack.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/InkBack.svelte.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAoC3D,QAAA,MAAM,OAAO,wDAAwC,CAAC;AACtD,KAAK,OAAO,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAC1C,eAAe,OAAO,CAAC"}

package/dist/components/InkForward.svelte

@@ -0,0 +1,40 @@
+<script lang="ts">
+  import { ArrowRight } from '@inkbar/icons'
+  import { Toolbar } from 'bits-ui'
+
+  import { useInkContext } from '../context.js'
+  import { useReadable } from '../use-readable.svelte.js'
+
+  import { asBitsProps } from './child-snippet.js'
+  import InkIcon from './InkIcon.svelte'
+
+  import type { InkPageButtonProps } from './page-button.js'
+
+  let {
+    class: className,
+    children,
+    child,
+    disabled,
+    onclick,
+    ...rest
+  }: InkPageButtonProps = $props()
+
+  const ctx = useInkContext('InkForward')
+  const can = useReadable(() => ctx.navigation?.canGoForward, false)
+</script>
+
+<Toolbar.Button
+  class={['ink-forward', className]}
+  data-ink-forward=""
+  aria-label="Forward"
+  title="Forward"
+  disabled={!can.current || !!disabled}
+  {...child ? { child } : {}}
+  {...asBitsProps(rest)}
+  onclick={(e) => {
+    onclick?.(e)
+    if (!e.defaultPrevented) ctx.navigation?.forward()
+  }}
+>
+  {#if children}{@render children()}{:else}<InkIcon icon={ArrowRight} />{/if}
+</Toolbar.Button>

package/dist/components/InkForward.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { InkPageButtonProps } from './page-button.js';
+declare const InkForward: import("svelte").Component<InkPageButtonProps, {}, "">;
+type InkForward = ReturnType<typeof InkForward>;
+export default InkForward;
+//# sourceMappingURL=InkForward.svelte.d.ts.map

package/dist/components/InkForward.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InkForward.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/InkForward.svelte.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAoC3D,QAAA,MAAM,UAAU,wDAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/dist/components/InkOutline.svelte

@@ -0,0 +1,170 @@
+<script module lang="ts">
+  import type { OutlineItem } from '@inkbar/core'
+  import type { Snippet } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+
+  export interface InkOutlineProps extends Omit<
+    HTMLAttributes<HTMLDivElement>,
+    'children'
+  > {
+    /** Shown when the document has no outline. Default: "This document has no outline". */
+    emptyText?: string | undefined
+    /**
+     * Replaces an item's title, given the item and whether it is the current one and whether it
+     * is expanded. Keep what it renders non-interactive.
+     */
+    item?: Snippet<[OutlineItem, { current: boolean; expanded: boolean }]> | undefined
+  }
+</script>
+
+<script lang="ts">
+  /*
+   * The open document's outline as a tree: `createOutline`'s markup on core's outline controller,
+   * which holds what is expanded, the Tab stop, the keys, the current item and Back's history.
+   * Clicking an item, or Enter on it, follows it; its chevron expands and collapses it. It fills
+   * its parent's height and scrolls, and keeps the item the reader has reached in view. The
+   * `item` snippet replaces an item's title. Inside `InkRoot`; the tree is empty on the server.
+   */
+  import {
+    createOutlineController,
+    outlineTreeAttrs,
+    type OutlineController,
+  } from '@inkbar/core/dom'
+  import { ChevronRight } from '@inkbar/icons'
+  import { untrack } from 'svelte'
+
+  import { useInkContext } from '../context.js'
+  import { toReadable } from '../to-readable.svelte.js'
+
+  import InkIcon from './InkIcon.svelte'
+
+  let {
+    emptyText = 'This document has no outline',
+    item: renderItem,
+    class: className,
+    ...rest
+  }: InkOutlineProps = $props()
+
+  const ctx = useInkContext('InkOutline')
+  const deps = {
+    document: toReadable(() => ctx.document),
+    viewport: toReadable(() => ctx.viewport),
+    navigation: toReadable(() => ctx.navigation),
+  }
+
+  let root = $state<HTMLDivElement | null>(null)
+  let controller = $state.raw<OutlineController | null>(null)
+  // Until the controller is built after mount, and on the server: nothing listed.
+  let items = $state.raw<readonly OutlineItem[]>([])
+  let loading = $state.raw(false)
+  let expanded = $state.raw<ReadonlySet<string>>(new Set())
+  let current = $state.raw<string | null>(null)
+  let focused = $state.raw<string | null>(null)
+
+  // Built once the element exists, as the other controller-backed components do: it subscribes
+  // to the document, so nothing is created while rendering on the server.
+  $effect(() => {
+    const el = root
+    if (!el) return
+    return untrack(() => {
+      const c = createOutlineController(deps)
+      controller = c
+      items = c.items.get()
+      loading = c.loading.get()
+      expanded = c.expanded.get()
+      current = c.current.get()
+      focused = c.focused.get()
+      const stops = [
+        c.items.subscribe((v) => (items = v)),
+        c.loading.subscribe((v) => (loading = v)),
+        c.expanded.subscribe((v) => (expanded = v)),
+        c.current.subscribe((v) => (current = v)),
+        c.focused.subscribe((v) => (focused = v)),
+        c.bindScroll(el),
+      ]
+      return () => {
+        for (const stop of stops) stop()
+        c.destroy()
+        controller = null
+      }
+    })
+  })
+
+  /** The item's attributes. Reading the stores here makes a render follow them. */
+  function attrs(id: string): Record<string, string | undefined> {
+    void [expanded, current, focused]
+    return controller?.itemAttrs(id) ?? {}
+  }
+
+  const level = (id: string): number => id.split('.').length - 1
+</script>
+
+{#snippet nodes(list: readonly OutlineItem[])}
+  {#each list as entry (entry.id)}
+    {@const c = controller!}
+    {@const open = expanded.has(entry.id)}
+    <li
+      class="ink-outline-item"
+      data-ink-outline-item={entry.id}
+      data-bold={entry.bold ? '' : undefined}
+      data-italic={entry.italic ? '' : undefined}
+      style:--ink-outline-level={level(entry.id)}
+      {...attrs(entry.id)}
+    >
+      <!-- The tree's keys come from the controller, so the row itself is not focusable. -->
+      <div
+        class="ink-outline-row"
+        {...c.rowAttrs(entry.id)}
+        onclick={() => c.activate(entry.id)}
+      >
+        {#if entry.children.length > 0}
+          <span
+            class="ink-outline-toggle"
+            aria-hidden="true"
+            onclick={(e) => {
+              // Expanding is not following: the row's own click is not reached.
+              e.stopPropagation()
+              c.toggle(entry.id)
+            }}
+          >
+            <InkIcon icon={ChevronRight} />
+          </span>
+        {:else}
+          <span class="ink-outline-spacer" aria-hidden="true"></span>
+        {/if}
+        <span class="ink-outline-title" {...c.titleAttrs(entry.id)}>
+          {#if renderItem}
+            {@render renderItem(entry, { current: current === entry.id, expanded: open })}
+          {:else}
+            {entry.title}
+          {/if}
+        </span>
+      </div>
+      {#if entry.children.length > 0}
+        <ul class="ink-outline-group" role="group" hidden={!open}>
+          {@render nodes(entry.children)}
+        </ul>
+      {/if}
+    </li>
+  {/each}
+{/snippet}
+
+<div
+  {...rest}
+  bind:this={root}
+  class={['ink-outline', className]}
+  data-ink-outline=""
+  aria-busy={loading ? 'true' : undefined}
+>
+  <ul
+    class="ink-outline-tree"
+    {...outlineTreeAttrs()}
+    hidden={items.length === 0}
+    onkeydown={(e) => controller?.onKeydown(e)}
+  >
+    {#if controller}{@render nodes(items)}{/if}
+  </ul>
+  {#if controller && !loading && items.length === 0}
+    <p class="ink-outline-empty">{emptyText}</p>
+  {/if}
+</div>

package/dist/components/InkOutline.svelte.d.ts

@@ -0,0 +1,19 @@
+import type { OutlineItem } from '@inkbar/core';
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+export interface InkOutlineProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** Shown when the document has no outline. Default: "This document has no outline". */
+    emptyText?: string | undefined;
+    /**
+     * Replaces an item's title, given the item and whether it is the current one and whether it
+     * is expanded. Keep what it renders non-interactive.
+     */
+    item?: Snippet<[OutlineItem, {
+        current: boolean;
+        expanded: boolean;
+    }]> | undefined;
+}
+declare const InkOutline: import("svelte").Component<InkOutlineProps, {}, "">;
+type InkOutline = ReturnType<typeof InkOutline>;
+export default InkOutline;
+//# sourceMappingURL=InkOutline.svelte.d.ts.map

package/dist/components/InkOutline.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InkOutline.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/InkOutline.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAC3C,cAAc,CAAC,cAAc,CAAC,EAC9B,UAAU,CACX;IACC,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,WAAW,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC,GAAG,SAAS,CAAA;CACnF;AA+IH,QAAA,MAAM,UAAU,qDAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/dist/components/InkRoot.svelte

@@ -7,7 +7,7 @@
     DocumentSource,
     FieldsChange,
     FieldValues,
-    FormAction,
+    ViewerAction,
     InkDocument,
     InkError,
     InkStatus,
@@ -52,8 +52,13 @@
      * are controlled, after the bound value is written.
      */
     onFieldsChange?: ((next: FieldValues, change: FieldsChange) => void) | undefined
-    /** The form asked to submit, open a link, send mail, print or prompt. Inkbar does none. */
-    onformaction?: ((action: FormAction) => void) | undefined
+    /**
+     * The viewer asked the host to submit a form, open a link, send mail, print or prompt.
+     * Inkbar does none of these.
+     */
+    onaction?: ((action: ViewerAction) => void) | undefined
+    /** @deprecated Use `onaction`. Removed in 0.13.0. Ignored when `onaction` is given. */
+    onformaction?: ((action: ViewerAction) => void) | undefined
     /** Tints fillable form fields. Default true. A change applies to the open document in place. */
     formHighlight?: boolean | undefined
     tool?: ToolId | undefined
@@ -87,9 +92,16 @@
      */
     fonts?: string[] | undefined
     /**
-     * Where saved signatures live. Default: memory, gone on reload.
-     * `createLocalSignatureStore` keeps them in the browser; a host can keep them anywhere.
-     * A new store takes effect at once, for the menus and the `signature` tool alike.
+     * Where the viewer keeps what lasts between visits: saved signatures, each `InkSidebar`'s
+     * width and the plugins' settings. Default: memory, gone on reload. `createLocalStorage`
+     * keeps them in the browser; a host can keep them anywhere. Read once, when the root is
+     * created.
+     */
+    storage?: InkStorage | undefined
+    /**
+     * Where saved signatures live, in place of `storage`. A new store takes effect at once, for
+     * the menus and the `signature` tool alike.
+     * @deprecated Pass `storage`; signatures are kept in it under `signatures`. Removed in 0.13.0.
      */
     signatures?: SignatureStore | undefined
     /** The handwriting fonts a typed signature offers; the host loads them. */
@@ -121,9 +133,10 @@
 
 <script lang="ts">
   import {
-    createMemorySignatureStore,
+    createMemoryStorage,
     createSignatureLibrary,
     createSnapshotHistory,
+    createStorageSignatureStore,
     InkError as InkErrorClass,
     openDocument,
     readonly,
@@ -153,8 +166,9 @@
   import { registeredToolIds } from '../hooks/useRegisteredTool.svelte.js'
   import { useReadable } from '../use-readable.svelte.js'
 
-  import type { PluginHistory } from '@inkbar/core'
+  import type { InkStorage, PluginHistory } from '@inkbar/core'
   import type {
+    Navigation,
     PluginHost,
     SearchController,
     ToolController,
@@ -171,6 +185,7 @@
     onChange,
     fields = $bindable(),
     onFieldsChange,
+    onaction,
     onformaction,
     formHighlight,
     tool = $bindable(),
@@ -179,6 +194,7 @@
     plugins,
     decorateAnnotation,
     fonts,
+    storage: storageProp,
     signatures: signatureStore,
     signatureFonts,
     page = $bindable(),
@@ -197,9 +213,11 @@
 
   type TestHookElement = HTMLElement & { __inkDocument?: InkDocument | undefined }
 
-  const signatures = $derived(
-    createSignatureLibrary(signatureStore ?? createMemorySignatureStore())
-  )
+  // Read once, like `plugins`: the sidebars and the plugins load from it as they are created.
+  const storage = untrack(() => storageProp ?? createMemoryStorage())
+  const storageSignatures = createStorageSignatureStore(storage)
+  // The deprecated `signatures` wins when both are given.
+  const signatures = $derived(createSignatureLibrary(signatureStore ?? storageSignatures))
   $effect(() => {
     void signatures.refresh()
   })
@@ -233,6 +251,7 @@
   let activatedNow: string | null = null
   let viewport = $state.raw<Viewport | null>(null)
   let tools = $state.raw<ToolController | null>(null)
+  let navigation = $state.raw<Navigation | null>(null)
 
   const documentStatus = useReadable<InkStatus>(() => document?.status, IDLE)
   const status = $derived(override ?? documentStatus.current)
@@ -428,7 +447,16 @@
     zoom = z
     onZoomChange?.(z)
   }
+  /**
+   * Whether the host has given `page` a value of its own, as React's `page` prop. Until then the
+   * page written back below is only a report, so the next document opens at its first page
+   * instead of the last one's. Not reactive: it flips only with a change to `page`, which
+   * `pageModel`'s readers already track.
+   */
+  let hostPage = untrack(() => page) !== undefined
+  let reportedPage: number | undefined
   function reportPage(p: number): void {
+    reportedPage = p
     page = p
     onPageChange?.(p)
   }
@@ -529,6 +557,7 @@
         decorate: () => decorateAnnotation,
         viewport: () => viewport,
         search: viewerSearchOf(controller),
+        storage,
       })
     )
     search = controller
@@ -628,6 +657,12 @@
     get viewport() {
       return viewport
     },
+    get navigation() {
+      return navigation
+    },
+    setNavigation(n) {
+      navigation = n
+    },
     get tools() {
       return tools
     },
@@ -651,6 +686,7 @@
       return fonts ?? FONT_FAMILIES
     },
     toolOptions,
+    storage,
     get signatures() {
       return signatures
     },
@@ -664,7 +700,8 @@
       return zoom
     },
     get pageModel() {
-      return page
+      if (page !== undefined && page !== reportedPage) hostPage = true
+      return hostPage ? page : undefined
     },
     reportZoom,
     reportPage,
@@ -683,7 +720,7 @@
     get formHighlight() {
       return formHighlight
     },
-    reportFormAction: (a) => onformaction?.(a),
+    reportAction: (a) => (onaction ?? onformaction)?.(a),
     reportError: (e) => onError?.(e),
   }
   setInkContext(context, () => activatedNow)