@anton-gustafsson/snapshot-core 0.0.6 → 0.4.1

package/dist/snapshot-nav-list.js

@@ -12,6 +12,7 @@ import { snapshotService as defaultSnapshotService } from './snapshot-service';
 function isMarkupIcon(icon) {
     return icon.trimStart().startsWith('<');
 }
+const DEFAULT_EDIT_ICON = '✎';
 /**
  * Visual identity: a contact sheet. Every tile is a "frame" — numbered like a strip
  * of negatives — because that's literally what a snapshot thumbnail is. All colors
@@ -22,8 +23,11 @@ export class SnapshotNavList extends LitElement {
     constructor() {
         super(...arguments);
         this.items = [];
-        this.variant = 'icon-only';
-        /** icon-only tile overlay: tint behind the title so it stays legible over any image. Transparent by default — opt into a scrim explicitly. */
+        /** `card` by default — a framed preview with title/description underneath. `tile` is the compact contact-sheet grid, `list` a sidebar row. */
+        this.variant = 'card';
+        /** Lets the host itself scroll (see `--snapshot-nav-list-max-height`) instead of growing unbounded. */
+        this.scrollable = false;
+        /** tile overlay: tint behind the title so it stays legible over any image. Transparent by default — opt into a scrim explicitly. */
         this.overlayTint = 'none';
         /** caption background tint strength, 0-1 */
         this.textOverlayOpacity = 0.35;
@@ -31,15 +35,26 @@ export class SnapshotNavList extends LitElement {
         this.imageOverlayOpacity = 0;
         /** backdrop blur behind the title, in px */
         this.overlayBlur = 0;
-        /** icon-only only: 'bottom' is the caption strip (default), 'center' centers a larger title. */
+        /** tile only: 'bottom' is the caption strip (default), 'center' centers a larger title. */
         this.labelPosition = 'bottom';
         /** Defaults to the shared singleton — set your own instance (e.g. a namespaced or custom-storage SnapshotService) per <snapshot-nav-list> if needed. */
         this.snapshotService = defaultSnapshotService;
-        /** Shows a top-right edit button per card. Off by default — clicking it fires `nav-edit` instead of `nav-select`; the host decides what "edit" means (e.g. open its own dialog component). */
+        /** Shows an edit button per card. Off by default — clicking it fires `nav-edit` instead of `nav-select`; the host decides what "edit" means (e.g. open its own dialog component). Overridable per row via `NavItem.editable`. */
         this.editable = false;
+        /** Where the edit button sits: `overlay` (default) floats it over the thumbnail; `meta` pins it to the right edge of the title row, with the description below. Ignored by the icon-only variant, whose caption is itself an overlay. */
+        this.editButtonPosition = 'overlay';
+        /** Edit button glyph. Same convention as `NavItem.icon`: a plain-text glyph (e.g. an emoji), or markup — a string starting with `<` renders as raw HTML/SVG, so a consumer can pass its own icon (e.g. `<svg>...</svg>`). */
+        this.editIcon = DEFAULT_EDIT_ICON;
         this.thumbs = new Map();
         this.loadingIds = new Set();
-        /** In-flight dedup guard, separate from `loadingIds` (which is only for spinner display) so a repeat `loadThumb` call for an id already being fetched is a no-op. */
+        /**
+         * In-flight dedup guard, separate from `loadingIds` (which is only for
+         * spinner display) so a repeat `loadThumb` call for an id already being
+         * fetched is a no-op. Keyed by `${variant}\0${id}` — not just `id` — so a
+         * `variantKey` switch mid-flight doesn't have the new variant's fetch
+         * silently dropped because the *previous* variant's id is still marked
+         * in-flight.
+         */
         this.fetchingIds = new Set();
     }
     static { this.styles = css `
@@ -47,6 +62,16 @@ export class SnapshotNavList extends LitElement {
       display: block;
       font-family: var(--snapshot-nav-list-font, inherit);
       --frame-accent: var(--snapshot-nav-list-accent, #ff5a1f);
+      max-height: var(--snapshot-nav-list-max-height, none);
+    }
+    /* scrollable: the host owns the scroll, so a long list in a flex sidebar
+       doesn't push its siblings off-screen and the consumer doesn't have to
+       reach in with its own overflow/min-height CSS. */
+    :host([scrollable]) {
+      flex: 1 1 auto;
+      min-height: 0;
+      overflow-y: auto;
+      overscroll-behavior: contain;
     }
     ul {
       list-style: none;
@@ -182,10 +207,10 @@ export class SnapshotNavList extends LitElement {
       -webkit-backdrop-filter: blur(var(--overlay-blur, 0px));
       pointer-events: none;
     }
-    /* the overlay exists so icon-only's overlaid title stays legible — list
+    /* the overlay exists so a tile's overlaid title stays legible — list
        variant shows the label beside the thumb, not on top of it, so the
        tint has nothing to do there. */
-    :host(:not([variant='icon-only'])) .image-overlay {
+    :host(:not([variant='tile'])) .image-overlay {
       display: none;
     }
 
@@ -243,6 +268,50 @@ export class SnapshotNavList extends LitElement {
       outline: 2px solid var(--frame-accent);
       outline-offset: 1px;
     }
+    .edit-button svg {
+      width: 1em;
+      height: 1em;
+      display: block;
+      fill: currentColor;
+    }
+
+    /* Transparent by default (display: contents) so the existing per-variant
+       .label/.meta rules — including icon-only's absolute caption strip —
+       keep applying unchanged; it only becomes a real row when the edit
+       button moves in beside the title. */
+    .label-row {
+      display: contents;
+    }
+    /* edit-button-position="meta": button on the title's line, description
+       still on its own line underneath. Not offered for icon-only, whose
+       .meta is an absolutely positioned overlay strip — the overlay button is
+       already the right place there. */
+    :host([edit-button-position='meta']:not([variant='icon-only'])) .label-row {
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+      min-width: 0;
+    }
+    /* the title takes the whole row so the button lands on the card's right
+       edge, still on the title's own line (the description sits below it);
+       min-width: 0 keeps a long title ellipsising instead of pushing out. */
+    :host([edit-button-position='meta']:not([variant='icon-only'])) .label {
+      flex: 1;
+      min-width: 0;
+    }
+    :host([edit-button-position='meta']:not([variant='icon-only'])) .edit-button {
+      position: static;
+      flex-shrink: 0;
+      /* in-flow, over the host's own background: currentColor-derived instead
+         of the overlay's dark scrim, and always visible (it isn't covering
+         anything, so hiding it until hover would just make it hard to find) */
+      background: color-mix(in srgb, currentColor 10%, transparent);
+      color: inherit;
+      opacity: 1;
+    }
+    :host([edit-button-position='meta']:not([variant='icon-only'])) .edit-button:hover {
+      background: color-mix(in srgb, currentColor 20%, transparent);
+    }
 
     /* list: a compact thumb reads better in a narrow sidebar than the grid's 160x100 */
     :host([variant='list']) .thumb-wrap {
@@ -250,25 +319,25 @@ export class SnapshotNavList extends LitElement {
       height: 68px;
     }
 
-    /* icon-only: contact-sheet grid, caption strip pinned to the bottom of each frame */
-    :host([variant='icon-only']) ul {
+    /* tile: contact-sheet grid, caption strip pinned to the bottom of each frame */
+    :host([variant='tile']) ul {
       flex-direction: row;
       flex-wrap: wrap;
       gap: 0.6rem;
     }
-    :host([variant='icon-only']) li {
+    :host([variant='tile']) li {
       position: relative;
       width: var(--snapshot-nav-list-tile-width, 160px);
       height: var(--snapshot-nav-list-tile-height, 100px);
       padding: 0;
       overflow: hidden;
     }
-    :host([variant='icon-only']) .thumb-wrap {
+    :host([variant='tile']) .thumb-wrap {
       width: 100%;
       height: 100%;
       border-radius: var(--snapshot-nav-list-radius, 10px);
     }
-    :host([variant='icon-only']) .meta {
+    :host([variant='tile']) .meta {
       position: absolute;
       inset: auto 0 0 0;
       margin: var(--snapshot-nav-list-overlay-margin, 0);
@@ -281,28 +350,28 @@ export class SnapshotNavList extends LitElement {
       backdrop-filter: blur(var(--overlay-blur, 0px));
       -webkit-backdrop-filter: blur(var(--overlay-blur, 0px));
     }
-    :host([variant='icon-only']) .label {
+    :host([variant='tile']) .label {
       white-space: normal;
     }
-    :host([variant='icon-only']) .description {
+    :host([variant='tile']) .description {
       color: color-mix(in srgb, var(--overlay-text, #fff) 75%, transparent);
     }
 
     /* label-position="center": title big and centered */
-    :host([variant='icon-only'][label-position='center']) .meta {
+    :host([variant='tile'][label-position='center']) .meta {
       inset: 0;
       align-items: center;
       justify-content: center;
       padding: 0.6rem;
     }
-    :host([variant='icon-only'][label-position='center']) .label {
+    :host([variant='tile'][label-position='center']) .label {
       font-size: 1.15rem;
       font-weight: 600;
       text-align: center;
     }
 
     /* card: a contained (never cropped) preview above real body text below it —
-       text never sits on top of the image, so unlike icon-only it needs no
+       text never sits on top of the image, so unlike a tile it needs no
        overlay tint to stay legible. Modeled on a typical "preview card"
        pattern: framed shot, title + description underneath, shadow on hover. */
     :host([variant='card']) ul {
@@ -367,15 +436,25 @@ export class SnapshotNavList extends LitElement {
       font-size: 0.8125rem;
     }
   `; }
+    fetchKey(variant, id) {
+        return `${variant ?? ''}\0${id}`;
+    }
     subscribeToService() {
         this.unsubscribe?.();
-        this.unsubscribe = this.snapshotService.subscribe((id, url) => {
+        this.unsubscribe = this.snapshotService.subscribe((id, url, variant) => {
             // Ignore captures for ids this list isn't showing — the service is
             // often a shared singleton, so without this guard `thumbs` would grow
             // forever with urls for every snapshot captured anywhere on the page,
             // not just this list's own items.
             if (!this.items.some((item) => item.id === id))
                 return;
+            // Same reason, one dimension over: a dark-theme capture must not
+            // overwrite the light-theme tile this list is currently showing. Folds
+            // '' and undefined together on both sides — SnapshotService.keyOf()
+            // does the same, so a caller that sets variantKey to '' instead of
+            // leaving it undefined must still match a plain (no-variant) capture.
+            if ((variant || undefined) !== (this.variantKey || undefined))
+                return;
             if (url === null) {
                 this.thumbs.delete(id);
             }
@@ -400,14 +479,23 @@ export class SnapshotNavList extends LitElement {
     // update instead of triggering Lit's "update scheduled from updated()"
     // warning that came from doing this same flip inside updated().
     willUpdate(changed) {
-        if (changed.has('items')) {
+        // 'icon-only' is the pre-0.3 name for 'tile'. Normalising here (rather
+        // than in a setter) keeps the reflected attribute — and therefore every
+        // CSS selector — on the one canonical value.
+        if (this.variant === 'icon-only')
+            this.variant = 'tile';
+        // A variant-key switch (e.g. light -> dark) invalidates every thumbnail:
+        // they're separate snapshots under separate keys.
+        if (changed.has('variantKey'))
+            this.thumbs.clear();
+        if (changed.has('items') || changed.has('variantKey')) {
             const ids = new Set(this.items.map((item) => item.id));
             for (const id of this.thumbs.keys()) {
                 if (!ids.has(id))
                     this.thumbs.delete(id);
             }
             for (const item of this.items) {
-                if (!this.thumbs.has(item.id) && !this.fetchingIds.has(item.id)) {
+                if (!this.thumbs.has(item.id) && !this.fetchingIds.has(this.fetchKey(this.variantKey, item.id))) {
                     this.loadingIds.add(item.id);
                 }
             }
@@ -417,25 +505,42 @@ export class SnapshotNavList extends LitElement {
         if (changed.has('snapshotService')) {
             this.subscribeToService();
         }
-        if (changed.has('items')) {
-            this.items.forEach((item) => this.loadThumb(item.id));
+        if (changed.has('items') || changed.has('variantKey')) {
+            void this.loadThumbs();
         }
     }
-    async loadThumb(id) {
-        if (this.thumbs.has(id) || this.fetchingIds.has(id))
+    /**
+     * One batched read for the whole list — `getMany()` collapses to a single
+     * query/round-trip on a storage that implements `loadMany`, instead of one
+     * per row. `fetchingIds` still guards per id, so an `items` reassignment
+     * mid-flight doesn't re-request what's already coming.
+     */
+    async loadThumbs() {
+        const variant = this.variantKey;
+        const wanted = this.items.filter((item) => !this.thumbs.has(item.id) && !this.fetchingIds.has(this.fetchKey(variant, item.id)));
+        if (wanted.length === 0)
             return;
-        this.fetchingIds.add(id);
+        const ids = wanted.map((item) => item.id);
+        ids.forEach((id) => this.fetchingIds.add(this.fetchKey(variant, id)));
         try {
-            const url = await this.snapshotService.get(id);
-            if (url)
-                this.thumbs.set(id, url);
+            const urls = await this.snapshotService.getMany(ids, { variant });
+            // Dropped if the variant changed while the read was in flight — those
+            // urls belong to the previous theme.
+            if (variant !== this.variantKey)
+                return;
+            for (const [id, url] of urls) {
+                if (url)
+                    this.thumbs.set(id, url);
+            }
         }
         catch (err) {
-            console.error(`snapshot-nav-list: failed to load thumbnail for "${id}"`, err);
+            console.error('snapshot-nav-list: failed to load thumbnails', err);
         }
         finally {
-            this.fetchingIds.delete(id);
-            this.loadingIds.delete(id);
+            ids.forEach((id) => {
+                this.fetchingIds.delete(this.fetchKey(variant, id));
+                this.loadingIds.delete(id);
+            });
             this.requestUpdate();
         }
     }
@@ -460,24 +565,36 @@ export class SnapshotNavList extends LitElement {
         const text = this.overlayTint === 'light' ? '#111' : '#fff';
         return { '--overlay-bg': bg, '--overlay-text': text, '--overlay-blur': blur };
     }
+    // Both events carry the whole item — including `data` — so a handler never
+    // has to look the item back up by id.
     select(item) {
-        this.dispatchEvent(new CustomEvent('nav-select', {
-            detail: { id: item.id, route: item.route },
-            bubbles: true,
-            composed: true,
-        }));
+        this.dispatchEvent(new CustomEvent('nav-select', { detail: item, bubbles: true, composed: true }));
     }
     edit(e, item) {
         e.stopPropagation();
-        this.dispatchEvent(new CustomEvent('nav-edit', {
-            detail: { id: item.id, route: item.route },
-            bubbles: true,
-            composed: true,
-        }));
+        this.dispatchEvent(new CustomEvent('nav-edit', { detail: item, bubbles: true, composed: true }));
+    }
+    isEditable(item) {
+        return item.editable ?? this.editable;
+    }
+    renderEditButton(item) {
+        const icon = this.editIcon || DEFAULT_EDIT_ICON;
+        return html `<button
+      type="button"
+      class="edit-button"
+      part="edit-button"
+      aria-label="Edit ${item.label}"
+      @click=${(e) => this.edit(e, item)}
+    >
+      ${isMarkupIcon(icon) ? unsafeHTML(icon) : icon}
+    </button>`;
     }
     render() {
         const imageOverlayStyle = this.imageOverlayStyle;
         const metaStyle = this.metaStyle;
+        // icon-only's caption is itself an overlay strip on the image, so there's
+        // no in-flow text row to put the button in — fall back to the overlay.
+        const editInMeta = this.editButtonPosition === 'meta' && this.variant !== 'icon-only';
         return html `
       <ul role="listbox">
         ${this.items.map((item) => html `
@@ -501,20 +618,13 @@ export class SnapshotNavList extends LitElement {
                         >
                       </div>`}
                 <div class="image-overlay" part="overlay" style=${styleMap(imageOverlayStyle)}></div>
-                ${this.editable
-            ? html `<button
-                      type="button"
-                      class="edit-button"
-                      part="edit-button"
-                      aria-label="Edit ${item.label}"
-                      @click=${(e) => this.edit(e, item)}
-                    >
-                      ✎
-                    </button>`
-            : ''}
+                ${this.isEditable(item) && !editInMeta ? this.renderEditButton(item) : ''}
               </div>
               <div class="meta" part="meta" style=${styleMap(metaStyle)}>
-                <span class="label" part="label">${item.label}</span>
+                <div class="label-row" part="label-row">
+                  <span class="label" part="label">${item.label}</span>
+                  ${this.isEditable(item) && editInMeta ? this.renderEditButton(item) : ''}
+                </div>
                 ${item.description ? html `<span class="description" part="description">${item.description}</span>` : ''}
               </div>
             </li>
@@ -529,6 +639,12 @@ __decorate([
 __decorate([
     property({ reflect: true })
 ], SnapshotNavList.prototype, "variant", void 0);
+__decorate([
+    property({ attribute: 'variant-key' })
+], SnapshotNavList.prototype, "variantKey", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], SnapshotNavList.prototype, "scrollable", void 0);
 __decorate([
     property({ attribute: 'overlay-tint' })
 ], SnapshotNavList.prototype, "overlayTint", void 0);
@@ -550,12 +666,20 @@ __decorate([
 __decorate([
     property({ type: Boolean })
 ], SnapshotNavList.prototype, "editable", void 0);
+__decorate([
+    property({ reflect: true, attribute: 'edit-button-position' })
+], SnapshotNavList.prototype, "editButtonPosition", void 0);
+__decorate([
+    property({ attribute: 'edit-icon' })
+], SnapshotNavList.prototype, "editIcon", void 0);
 __decorate([
     state()
 ], SnapshotNavList.prototype, "thumbs", void 0);
 __decorate([
     state()
 ], SnapshotNavList.prototype, "loadingIds", void 0);
-if (!customElements.get('snapshot-nav-list')) {
+// Guarded so importing this package in a DOM-less process (SSR, Node, a test
+// runner without jsdom) is a no-op instead of a crash.
+if (typeof customElements !== 'undefined' && !customElements.get('snapshot-nav-list')) {
     customElements.define('snapshot-nav-list', SnapshotNavList);
 }

package/dist/snapshot-service.d.ts

@@ -1,4 +1,5 @@
-import type { SnapshotStorage } from './snapshot-storage';
+import type { EncodeOptions } from './encode';
+import type { SnapshotKey, SnapshotStorage } from './snapshot-storage';
 export interface SnapshotServiceConfig {
     /** Provide your own backend-backed implementation to persist across devices. */
     storage?: SnapshotStorage;
@@ -11,21 +12,85 @@ export interface SnapshotServiceConfig {
      * their keys and live-update notifications can't collide.
      */
     keyPrefix?: string;
+    /** Re-encode applied to every capture before it's stored. Defaults to none (the raw html2canvas PNG). */
+    encode?: EncodeOptions;
+    /**
+     * Escape hatch for an existing store whose keys don't follow
+     * `keyPrefix + id [+ '@' + variant]` — return the key to use. Note that
+     * `parseKey()` (and therefore `prune()`) can't reverse a custom shape.
+     */
+    keyFor?: (key: SnapshotKey) => string;
+}
+/** `url` is null when the id was removed (or invalidated) rather than (re)captured. */
+type Listener = (id: string, url: string | null, variant?: string) => void;
+export interface VariantOptions {
+    /**
+     * A second dimension on the id — a theme, a density, a locale. Stored under
+     * its own key, so `get(id, { variant: 'dark' })` never returns the light one.
+     */
+    variant?: string;
+}
+export interface CaptureOptions extends VariantOptions {
+    /** Per-call override of the instance `scale`. */
+    scale?: number;
+    /** Per-call override of the instance `encode`. */
+    encode?: EncodeOptions;
 }
-/** `url` is null when the id was removed rather than (re)captured. */
-type Listener = (id: string, url: string | null) => void;
 export declare class SnapshotService {
     private storage;
     private scale;
     private keyPrefix;
-    private channel;
+    private encode?;
+    private keyFor?;
+    /** Absent under Node/SSR (or any environment without BroadcastChannel) — same-tab notification still works. */
+    private channel?;
     private listeners;
+    /** In-flight captures, keyed by storage key, so two callers racing on the same view do one render. */
+    private capturing;
     constructor(config?: SnapshotServiceConfig);
-    /** Capture works on any element — a snapshot-nav-list item is one convention, not a requirement. */
-    capture(el: HTMLElement, id: string): Promise<string>;
-    get(id: string): Promise<string | null>;
+    /**
+     * The fully-qualified storage key for an id (+ variant) under this instance.
+     * `id`/`variant` are `encodeURIComponent`-escaped before joining, so a `@`
+     * (or any other character) inside either can never be mistaken for the
+     * separator itself — without escaping, `id: 'a@b'` and `id: 'a', variant: 'b'`
+     * would otherwise land on the exact same key.
+     */
+    keyOf(id: string, opts?: VariantOptions): SnapshotKey;
+    /**
+     * Inverse of `keyOf()` for the default key shape — splits a stored key back
+     * into `{ id, variant }`. Returns `null` for a key belonging to a different
+     * `keyPrefix`, or for any key when a custom `keyFor` is configured (a custom
+     * shape isn't reversible).
+     */
+    parseKey(key: string): SnapshotKey | null;
+    /**
+     * Capture works on any element — a snapshot-nav-list item is one convention,
+     * not a requirement. Concurrent calls for the same id/variant share one
+     * render instead of racing two.
+     */
+    capture(el: HTMLElement, id: string, opts?: CaptureOptions): Promise<string>;
+    private runCapture;
+    get(id: string, opts?: VariantOptions): Promise<string | null>;
+    /**
+     * Batch read, keyed by bare id. Uses the storage's `loadMany()` when it has
+     * one (a single query/round-trip for a whole list) and falls back to parallel
+     * `load()`s when it doesn't.
+     */
+    getMany(ids: string[], opts?: VariantOptions): Promise<Map<string, string | null>>;
     /** Deletes a stored snapshot and notifies subscribers (this tab and others) that `id` is gone. */
-    remove(id: string): Promise<void>;
+    remove(id: string, opts?: VariantOptions): Promise<void>;
+    /**
+     * Deletes every stored snapshot (all variants) whose id isn't in `keepIds`,
+     * so thumbnails don't outlive the entities they belong to. Requires a storage
+     * that implements `keys()`; returns the number of snapshots removed.
+     */
+    prune(keepIds: Iterable<string>): Promise<number>;
+    /**
+     * Warms the storage for a list of ids ahead of render (one `loadMany()` where
+     * the storage supports it) and publishes whatever it finds, so any mounted
+     * `<snapshot-nav-list>` paints from the first frame instead of spinning.
+     */
+    prefetch(ids: string[], opts?: VariantOptions): Promise<void>;
     /**
      * Announces a URL for `id` to subscribers (this tab and others) without
      * touching storage. For a storage layer that resolves a fresher value
@@ -33,7 +98,7 @@ export declare class SnapshotService {
      * local cache in front of a slower authoritative database — call this once
      * the slow read settles so any mounted <snapshot-nav-list> updates live.
      */
-    publish(id: string, url: string): void;
+    publish(id: string, url: string, opts?: VariantOptions): void;
     /**
      * Tells subscribers to drop their locally cached thumbnail for `id` and
      * treat it as not-yet-loaded — without deleting anything from storage.
@@ -41,12 +106,22 @@ export declare class SnapshotService {
      * it again. Useful when the underlying data changed out from under the
      * cache (or, for a demo, to replay a loading state on demand).
      */
-    invalidate(id: string): void;
-    subscribe(cb: Listener): () => boolean;
+    invalidate(id: string, opts?: VariantOptions): void;
+    subscribe(cb: Listener): () => void;
     /** Releases the cross-tab BroadcastChannel. Call when this instance (a non-default, namespaced one) is no longer needed. */
     close(): void;
     private notify;
 }
-/** Default singleton (IndexedDB-backed). Replace with your own SnapshotService({ storage }) if you need a real backend. */
+/**
+ * The shared IndexedDB-backed instance, created on first call — so importing
+ * this package never opens a BroadcastChannel or an IndexedDB connection an
+ * app that brings its own `SnapshotService` would never use.
+ */
+export declare function getDefaultSnapshotService(): SnapshotService;
+/**
+ * @deprecated Use `getDefaultSnapshotService()`. A lazy stand-in for the
+ * default instance: it forwards every access to the real service, constructing
+ * it on first touch rather than at import time.
+ */
 export declare const snapshotService: SnapshotService;
 export {};