@inkbar/svelte 0.8.0 → 0.10.0

package/README.md

@@ -53,6 +53,7 @@ Svelte 5.46.4 or later is a peer dependency. Add the Vite plugin from `@inkbar/c
     InkZoomIn,
     InkThreadPopover,
   } from '@inkbar/svelte'
+  import { highlightTool, noteTool, redactAreaTool } from '@inkbar/core/dom'
   import type { Annotation } from '@inkbar/core'
   import { assets } from 'virtual:inkbar-assets'
   import '@inkbar/theme/theme.css'
@@ -60,9 +61,10 @@ Svelte 5.46.4 or later is a peer dependency. Add the Vite plugin from `@inkbar/c
   let { signedUrl, documentId }: { signedUrl: string; documentId: string } = $props()
 
   let annotations = $state.raw<Annotation[]>([])
+  const tools = [highlightTool(), redactAreaTool(), noteTool()]
 </script>
 
-<InkRoot src={{ url: signedUrl, key: documentId }} {assets} bind:annotations>
+<InkRoot src={{ url: signedUrl, key: documentId }} {assets} {tools} bind:annotations>
   <InkToolbar>
     <InkToolButton tool="select-text" />
     <InkToolButton tool="select" />
@@ -87,7 +89,9 @@ Svelte 5.46.4 or later is a peer dependency. Add the Vite plugin from `@inkbar/c
 </InkRoot>
 ```
 
-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. `bind:annotations` makes your list the source of truth. Leave it off and Inkbar keeps the state itself, with undo and redo.
+`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`.
+
+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.
 
 ## Controlled mode
 
@@ -161,7 +165,7 @@ The highlight tool leaves `contents` free for the comment. `doc.text(page)` retu
 
 ## Signatures
 
-`InkSignatureMenu` lists saved signatures, picks one for the `signature` tool, removes them, and opens `InkSignatureDialog` to draw, type or upload a new one. 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. 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.
 
 ## Plugins
 
@@ -187,11 +191,71 @@ Plugin stores undo with annotations. In controlled mode with `history`, each und
 
 The bar handles Escape itself and stops it there, so an `onkeydown` you pass to `InkFindBar` never sees Escape.
 
+## Sidebars
+
+`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
+<InkRoot {src} {assets}>
+  <div class="app">
+    <InkSidebar side="left" layout="rail" bind:open>
+      <InkPanel id="pages" label="Pages" icon={Square}>
+        <InkThumbnails />
+      </InkPanel>
+      <InkPanel id="notes" label="Notes" icon={MessageSquare} badge={noteCount}>
+        <MyNotes />
+      </InkPanel>
+    </InkSidebar>
+    <InkViewport />
+  </div>
+</InkRoot>
+```
+
+`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.
+
+## Thumbnails
+
+`InkThumbnail` draws one page (0-based `page`) as a small image, with its annotations and plugin marks. Give it a `width` or a `height` and the other follows the page; with neither it is 120px wide. `annotations={false}` and `marks={false}` leave those out, and `label` replaces its accessible name ("Page 4" for page 3). It is an image with no focus or click behaviour, so wrap it in the control you need, a checkbox label in a dialog for instance.
+
+`InkThumbnails` lists the pages as thumbnails, each a button that scrolls the viewport to its page, with the current page marked `aria-current="page"`. It fills its parent's height and scrolls. `pages` lists the pages to show, in order. The thumbnails fill the list's width less a 16px gutter each side and follow it as it resizes; `width` fixes them at that many pixels instead. `annotations` and `marks` pass to each thumbnail. Only the items near the visible part are mounted. The `item` snippet adds to each item after its page number:
+
+```svelte
+<InkThumbnails>
+  {#snippet item({ page, current })}
+    <span class="page-count">{counts[page]}</span>
+  {/snippet}
+</InkThumbnails>
+```
+
+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.
+
+## 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>`:
+
+```svelte
+<InkPanel id="suggestions" label="Suggestions" icon={MessageSquare} badge={count}>
+  <InkRecordList records="review.suggestions" bind:count>
+    {#snippet empty()}No suggestions left.{/snippet}
+  </InkRecordList>
+</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.
+
+`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.
+
+To build your own, `useRecords<T>(name)` returns the live `records` and the `handle` to read and write them, each write one undo step, and `useRecordSelection(name)` returns `selected` and `select(id | null)`. Both need `InkRoot`. Plugins are set up once it has mounted, so until then `handle` is null, `records` is empty and nothing is selected. Both lists fill their parent's height and render empty on the server. The keys, focus and announcements are core's: see the [`@inkbar/core` README](https://github.com/inkbar/inkbar/tree/main/packages/core#record-lists).
+
 ## 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 }`. 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` 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.
+
+`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`, `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`, `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`.
 
 ```svelte
 <InkToolbar>
@@ -209,6 +273,7 @@ The scroll area takes focus. From there:
 - With the `note` tool active, `Enter` places a note at the centre of the current page and opens it.
 - With the `signature` tool active, `Enter` places the chosen signature at the centre of the current page.
 - `Ctrl` or `Cmd` + `Z` undoes. `Ctrl` or `Cmd` + `Shift` + `Z`, or `Ctrl` + `Y`, redoes. `Ctrl` and `Cmd` both work on every platform. The keys do what `InkUndo` and `InkRedo` do, from anywhere in `InkRoot`, toolbars included, and act only while that button is enabled. In a text field or editable content the keys stay with the element, so a field keeps its own text undo. In a `<select>` they are left to the browser, which does nothing with them.
+- `Ctrl` or `Cmd` + `P` prints the PDF and `Ctrl` or `Cmd` + `S` downloads it, as `InkPrintButton` and `InkDownloadButton` do, from anywhere in `InkRoot` once the document is ready. Outside `InkRoot` the browser keeps them.
 
 On a focused annotation:
 
@@ -226,7 +291,7 @@ Components carry state on data attributes, for example `[data-annotation][data-s
 
 ## Hooks
 
-`useDocument`, `useAnnotations`, `useTool`, `useSelection`, `useZoom`, `usePage`, `useHistory`, `useEmbedded` and `useCommand` 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`, `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.
 
 ## Licence
 

package/dist/components/InkDownloadButton.svelte

@@ -0,0 +1,62 @@
+<script lang="ts" module>
+  import type { ChildSnippet } from './child-snippet.js'
+  import type { Snippet } from 'svelte'
+  import type { HTMLButtonAttributes } from 'svelte/elements'
+
+  export interface InkDownloadButtonProps extends Omit<HTMLButtonAttributes, 'children'> {
+    children?: Snippet | undefined
+    /** Render your own button: spread `props` on it. */
+    child?: ChildSnippet | undefined
+    /** The name to save under. Default: the document's `fileName`. */
+    filename?: string | undefined
+  }
+</script>
+
+<script lang="ts">
+  /*
+   * Saves the open document's file through the browser's download, under its `fileName`
+   * or `filename`. Disabled until the document is ready. Today that is the file as it was opened,
+   * without this session's annotations.
+   */
+  import { downloadDocument } from '@inkbar/core/dom'
+  import { Download } from '@inkbar/icons'
+  import { Toolbar } from 'bits-ui'
+
+  import { useInkContext } from '../context.js'
+
+  import { asBitsProps } from './child-snippet.js'
+  import InkIcon from './InkIcon.svelte'
+
+  let {
+    class: className,
+    children,
+    child,
+    disabled,
+    onclick,
+    filename,
+    ...rest
+  }: InkDownloadButtonProps = $props()
+
+  const ctx = useInkContext('InkDownloadButton')
+  const ready = $derived(ctx.document !== null && ctx.status.state === 'ready')
+</script>
+
+<Toolbar.Button
+  class={['ink-download', className]}
+  data-ink-download=""
+  aria-label="Download"
+  title="Download"
+  disabled={!ready || !!disabled}
+  {...child ? { child } : {}}
+  {...asBitsProps(rest)}
+  onclick={(e) => {
+    onclick?.(e)
+    const doc = ctx.document
+    if (e.defaultPrevented || !doc) return
+    void downloadDocument(doc, filename === undefined ? {} : { filename }).catch(
+      () => undefined
+    )
+  }}
+>
+  {#if children}{@render children()}{:else}<InkIcon icon={Download} />{/if}
+</Toolbar.Button>

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

@@ -0,0 +1,14 @@
+import type { ChildSnippet } from './child-snippet.js';
+import type { Snippet } from 'svelte';
+import type { HTMLButtonAttributes } from 'svelte/elements';
+export interface InkDownloadButtonProps extends Omit<HTMLButtonAttributes, 'children'> {
+    children?: Snippet | undefined;
+    /** Render your own button: spread `props` on it. */
+    child?: ChildSnippet | undefined;
+    /** The name to save under. Default: the document's `fileName`. */
+    filename?: string | undefined;
+}
+declare const InkDownloadButton: import("svelte").Component<InkDownloadButtonProps, {}, "">;
+type InkDownloadButton = ReturnType<typeof InkDownloadButton>;
+export default InkDownloadButton;
+//# sourceMappingURL=InkDownloadButton.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"InkDownloadButton.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/InkDownloadButton.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAE3D,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAAC,oBAAoB,EAAE,UAAU,CAAC;IACpF,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC9B,oDAAoD;IACpD,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAA;IAChC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC9B;AAyDH,QAAA,MAAM,iBAAiB,4DAAwC,CAAC;AAChE,KAAK,iBAAiB,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC9D,eAAe,iBAAiB,CAAC"}

package/dist/components/InkFindBar.svelte

@@ -18,7 +18,7 @@
    * Closing returns focus to where it was before the bar opened, else to the document.
    */
   import { findAnnouncer, findCountText } from '@inkbar/core/dom'
-  import { CaseSensitive, ChevronDown, ChevronUp, X } from '@inkbar/icons'
+  import { CaseSensitive, ChevronDown, ChevronUp, Search, X } from '@inkbar/icons'
   import { untrack } from 'svelte'
 
   import { useInkContext } from '../context.js'
@@ -149,20 +149,23 @@
     hidden={!open}
     {@attach into(target)}
   >
-    <input
-      bind:this={field}
-      type="text"
-      aria-label="Find in document"
-      autocomplete="off"
-      spellcheck={false}
-      oninput={(e) => search.setQuery(e.currentTarget.value)}
-      onkeydown={(e) => {
-        if (e.key !== 'Enter' || e.isComposing) return
-        e.preventDefault()
-        if (e.shiftKey) search.previous()
-        else search.next()
-      }}
-    />
+    <div class="ink-input-group">
+      <span class="ink-input-accessory"><InkIcon icon={Search} /></span>
+      <input
+        bind:this={field}
+        type="text"
+        aria-label="Find in document"
+        autocomplete="off"
+        spellcheck={false}
+        oninput={(e) => search.setQuery(e.currentTarget.value)}
+        onkeydown={(e) => {
+          if (e.key !== 'Enter' || e.isComposing) return
+          e.preventDefault()
+          if (e.shiftKey) search.previous()
+          else search.next()
+        }}
+      />
+    </div>
     <span class="ink-find-count" data-ink-find-count=""
       >{findCountText(search.state)}</span
     >

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

@@ -1 +1 @@
-{"version":3,"file":"InkFindBar.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/InkFindBar.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC,CAC/E;AAmLD,QAAA,MAAM,UAAU,qDAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}
+{"version":3,"file":"InkFindBar.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/InkFindBar.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC,CAC/E;AAsLD,QAAA,MAAM,UAAU,qDAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/dist/components/InkHighlightMenu.svelte

@@ -30,8 +30,9 @@
   import { Popover, Toolbar } from 'bits-ui'
 
   import { useDocument } from '../hooks/useDocument.svelte.js'
+  import { useRegisteredTool } from '../hooks/useRegisteredTool.svelte.js'
   import { useTool } from '../hooks/useTool.svelte.js'
-  import { useToolOptions } from '../hooks/useToolOptions.svelte.js'
+  import { useToolOptionsWhile } from '../hooks/useToolOptions.svelte.js'
 
   import InkColorMenu from './InkColorMenu.svelte'
   import InkIcon from './InkIcon.svelte'
@@ -41,7 +42,12 @@
 
   const current = useTool()
   const inkDocument = useDocument()
-  const highlight = useToolOptions<HighlightOptions>('highlight')
+  // Nothing renders while no `highlight` tool is registered.
+  const registered = useRegisteredTool('highlight')
+  const highlight = useToolOptionsWhile<HighlightOptions>(
+    'highlight',
+    () => registered.current
+  )
   let open = $state(false)
   /** The split button: the panel lines up under it rather than the chevron. */
   let group = $state<HTMLElement | null>(null)
@@ -72,97 +78,99 @@
   }
 </script>
 
-<div
-  bind:this={group}
-  role="group"
-  aria-label="Highlight"
-  class={['ink-split-button ink-highlight-menu', className]}
-  data-ink-highlight-menu=""
-  {...rest}
->
-  <Toolbar.Button
-    class="ink-tool-button ink-highlight-button"
-    data-ink-tool-button=""
-    data-ink-highlight-button=""
-    data-tool="highlight"
-    data-kind={model.kind}
-    data-state={active ? 'on' : 'off'}
-    aria-pressed={active}
-    aria-label={model.label}
-    title={model.label}
-    onclick={() => current.setTool('highlight')}
+{#if registered.current}
+  <div
+    bind:this={group}
+    role="group"
+    aria-label="Highlight"
+    class={['ink-split-button ink-highlight-menu', className]}
+    data-ink-highlight-menu=""
+    {...rest}
   >
-    {#if children}{@render children()}{:else}<InkIcon
-        icon={MARKUP_ICONS[model.kind]}
-      />{/if}
-  </Toolbar.Button>
-  <Popover.Root bind:open>
-    <Popover.Trigger>
-      {#snippet child({ props })}
-        <Toolbar.Button
-          {...props}
-          class="ink-menu-trigger ink-highlight-menu-trigger"
-          data-ink-highlight-menu-trigger=""
-          data-state={open ? 'open' : 'closed'}
-          aria-label="Choose highlight"
-          title="Choose highlight"
-          aria-haspopup="menu"
-          onkeydown={onTriggerKeydown}
+    <Toolbar.Button
+      class="ink-tool-button ink-highlight-button"
+      data-ink-tool-button=""
+      data-ink-highlight-button=""
+      data-tool="highlight"
+      data-kind={model.kind}
+      data-state={active ? 'on' : 'off'}
+      aria-pressed={active}
+      aria-label={model.label}
+      title={model.label}
+      onclick={() => current.setTool('highlight')}
+    >
+      {#if children}{@render children()}{:else}<InkIcon
+          icon={MARKUP_ICONS[model.kind]}
+        />{/if}
+    </Toolbar.Button>
+    <Popover.Root bind:open>
+      <Popover.Trigger>
+        {#snippet child({ props })}
+          <Toolbar.Button
+            {...props}
+            class="ink-menu-trigger ink-highlight-menu-trigger"
+            data-ink-highlight-menu-trigger=""
+            data-state={open ? 'open' : 'closed'}
+            aria-label="Choose highlight"
+            title="Choose highlight"
+            aria-haspopup="menu"
+            onkeydown={onTriggerKeydown}
+          >
+            <InkIcon icon={ChevronDown} />
+          </Toolbar.Button>
+        {/snippet}
+      </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Content
+          bind:ref={menu}
+          role="menu"
+          aria-label="Highlights"
+          class="ink-select-content ink-menu-content"
+          data-ink-select-content=""
+          data-ink-menu="highlight"
+          customAnchor={group}
+          side="bottom"
+          align="start"
+          sideOffset={4}
+          collisionPadding={8}
+          onOpenAutoFocus={(e) => openFocus.onOpenAutoFocus(e, menu)}
+          onfocusin={openFocus.onfocusin}
+          onkeydowncapture={(e: KeyboardEvent) => menu && handleMenuKeys(e, menu)}
         >
-          <InkIcon icon={ChevronDown} />
-        </Toolbar.Button>
-      {/snippet}
-    </Popover.Trigger>
-    <Popover.Portal>
-      <Popover.Content
-        bind:ref={menu}
-        role="menu"
-        aria-label="Highlights"
-        class="ink-select-content ink-menu-content"
-        data-ink-select-content=""
-        data-ink-menu="highlight"
-        customAnchor={group}
-        side="bottom"
-        align="start"
-        sideOffset={4}
-        collisionPadding={8}
-        onOpenAutoFocus={(e) => openFocus.onOpenAutoFocus(e, menu)}
-        onfocusin={openFocus.onfocusin}
-        onkeydowncapture={(e: KeyboardEvent) => menu && handleMenuKeys(e, menu)}
-      >
-        <div role="group" aria-label="Kinds" class="ink-highlight-kinds">
-          {#each model.items as item (item.kind)}
-            <button
-              type="button"
-              role="menuitemradio"
-              class="ink-select-item ink-menu-item ink-highlight-item"
-              data-ink-select-item=""
+          <div role="group" aria-label="Kinds" class="ink-highlight-kinds">
+            {#each model.items as item (item.kind)}
+              <button
+                type="button"
+                role="menuitemradio"
+                class="ink-select-item ink-menu-item ink-highlight-item"
+                data-ink-select-item=""
+                tabindex={-1}
+                data-key={item.kind}
+                aria-checked={item.checked}
+                data-state={item.checked ? 'checked' : 'unchecked'}
+                onclick={() => choose(item.kind)}
+              >
+                <InkIcon icon={MARKUP_ICONS[item.kind]} size={16} />
+                {item.label}
+              </button>
+            {/each}
+          </div>
+          <div role="separator" class="ink-select-separator"></div>
+          <div role="group" aria-label="Colour" class="ink-highlight-colour">
+            <span class="ink-highlight-colour-label" aria-hidden="true">Colour</span>
+            <!-- Capture on the panel moves on from this item before its own ArrowDown opens it. -->
+            <InkColorMenu
+              property="border"
+              group="markup"
+              label="Highlight colour"
+              standalone
+              {fallback}
+              role="menuitem"
               tabindex={-1}
-              data-key={item.kind}
-              aria-checked={item.checked}
-              data-state={item.checked ? 'checked' : 'unchecked'}
-              onclick={() => choose(item.kind)}
-            >
-              <InkIcon icon={MARKUP_ICONS[item.kind]} size={16} />
-              {item.label}
-            </button>
-          {/each}
-        </div>
-        <div role="separator" class="ink-select-separator"></div>
-        <div role="group" aria-label="Colour" class="ink-highlight-colour">
-          <span class="ink-highlight-colour-label" aria-hidden="true">Colour</span>
-          <!-- Capture on the panel moves on from this item before its own ArrowDown opens it. -->
-          <InkColorMenu
-            property="border"
-            group="markup"
-            label="Highlight colour"
-            standalone
-            {fallback}
-            role="menuitem"
-            tabindex={-1}
-          />
-        </div>
-      </Popover.Content>
-    </Popover.Portal>
-  </Popover.Root>
-</div>
+            />
+          </div>
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover.Root>
+  </div>
+{/if}

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

@@ -1 +1 @@
-{"version":3,"file":"InkHighlightMenu.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/InkHighlightMenu.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD;;;;;GAKG;AACH,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CACjD,cAAc,CAAC,cAAc,CAAC,EAC9B,UAAU,CACX;IACC,uCAAuC;IACvC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC/B;AA2GH,QAAA,MAAM,gBAAgB,2DAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"InkHighlightMenu.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/InkHighlightMenu.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD;;;;;GAKG;AACH,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CACjD,cAAc,CAAC,cAAc,CAAC,EAC9B,UAAU,CACX;IACC,uCAAuC;IACvC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC/B;AAoHH,QAAA,MAAM,gBAAgB,2DAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}

package/dist/components/InkPanel.svelte

@@ -0,0 +1,73 @@
+<script module lang="ts">
+  import type { IconNode } from '@inkbar/icons'
+  import type { Snippet } from 'svelte'
+
+  export interface InkPanelProps {
+    /** Names the panel in the sidebar's `open`. */
+    id: string
+    /** Names its trigger. */
+    label: string
+    /** An `@inkbar/icons` node, shown on the rail. */
+    icon?: IconNode | undefined
+    /** A count or short text beside it, hidden when empty or 0. */
+    badge?: string | number | undefined
+    /** The panel's content. */
+    children?: Snippet | undefined
+  }
+</script>
+
+<script lang="ts">
+  /*
+   * One panel of an `InkSidebar`, holding `children` as its content. Closed, the panel stays
+   * mounted and hidden. In a stack it renders its own header above its content.
+   */
+  import { useSidebarContext } from './sidebar-context.js'
+  import SidebarTrigger from './SidebarTrigger.svelte'
+
+  import type { SidebarPanelInfo } from '@inkbar/core/dom'
+
+  let { id, label, icon, badge, children }: InkPanelProps = $props()
+
+  const ctx = useSidebarContext('InkPanel')
+  let wrapper = $state<HTMLDivElement | null>(null)
+
+  const info = (): SidebarPanelInfo => ({
+    id,
+    label,
+    ...(icon !== undefined && { icon }),
+    ...(badge !== undefined && { badge }),
+  })
+  // Registered now, so the server renders this panel's attributes; ordered once in the DOM.
+  const unregister = ctx.register({ info, element: () => wrapper })
+  $effect(() => {
+    ctx.arrange()
+    return unregister
+  })
+
+  const view = $derived.by(() => {
+    const s = ctx.state.current
+    return {
+      stack: s.layout === 'stack',
+      trigger: ctx.controller.triggerAttrs(id),
+      panel: ctx.controller.panelAttrs(id),
+    }
+  })
+</script>
+
+<!-- A section in a stack; in rail and tabs the theme leaves the layout to the panel. Kept in
+     every layout, so the content is never remounted. -->
+<div
+  bind:this={wrapper}
+  class={['ink-sidebar-slot', view.stack && 'ink-sidebar-section']}
+>
+  {#if view.stack}
+    <button class="ink-sidebar-header" {...view.trigger}>
+      <SidebarTrigger panel={info()} rail={false} />
+    </button>
+  {/if}
+  <div class="ink-sidebar-panel" {...view.panel}>
+    <!-- The rail button names the panel for assistive technology; this repeats it on screen. -->
+    <div class="ink-sidebar-panel-title" aria-hidden="true">{label}</div>
+    <div class="ink-sidebar-panel-body">{@render children?.()}</div>
+  </div>
+</div>

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

@@ -0,0 +1,18 @@
+import type { IconNode } from '@inkbar/icons';
+import type { Snippet } from 'svelte';
+export interface InkPanelProps {
+    /** Names the panel in the sidebar's `open`. */
+    id: string;
+    /** Names its trigger. */
+    label: string;
+    /** An `@inkbar/icons` node, shown on the rail. */
+    icon?: IconNode | undefined;
+    /** A count or short text beside it, hidden when empty or 0. */
+    badge?: string | number | undefined;
+    /** The panel's content. */
+    children?: Snippet | undefined;
+}
+declare const InkPanel: import("svelte").Component<InkPanelProps, {}, "">;
+type InkPanel = ReturnType<typeof InkPanel>;
+export default InkPanel;
+//# sourceMappingURL=InkPanel.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"InkPanel.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/components/InkPanel.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AAErC,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAA;IACV,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,kDAAkD;IAClD,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC3B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IACnC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC/B;AAiEH,QAAA,MAAM,QAAQ,mDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}