element-book 26.12.1 → 26.13.0

package/dist/data/book-entry/book-entry.d.ts

@@ -10,7 +10,7 @@ export type BookEntry = BookPage | BookRoot | BookElementExample;
 /**
  * Check if the input is a book entry of the given type.
  *
- * @internal
+ * @category Internal
  */
 export declare function isBookEntry<const SpecificType extends BookEntryType>(entry: unknown, entryType: SpecificType): entry is Extract<BookEntry, {
     entryType: SpecificType;

package/dist/data/book-entry/book-entry.js

@@ -2,7 +2,7 @@ import { check } from '@augment-vir/assert';
 /**
  * Check if the input is a book entry of the given type.
  *
- * @internal
+ * @category Internal
  */
 export function isBookEntry(entry, entryType) {
     return check.hasKey(entry, 'entryType') && entry.entryType === entryType;

package/dist/data/book-entry/book-page/book-page-controls.d.ts

@@ -21,7 +21,7 @@ export type BookPageControlInit<ControlType extends BookPageControlType> = Omit<
 /**
  * Checks and type guards that the input page control init is of the given type.
  *
- * @internal
+ * @category Internal
  */
 export declare function isControlInitType<const SpecificControlType extends BookPageControlType>(controlInit: BookPageControlInit<any>, specificType: SpecificControlType): controlInit is BookPageControlInit<SpecificControlType>;
 /**
@@ -87,6 +87,6 @@ export type BookPageControlValueType = typeof controlValueTypes;
 /**
  * Checks that the given control init object is valid.
  *
- * @internal
+ * @category Internal
  */
 export declare function checkControls(controlsInit: BookPageControlsInitBase | undefined, pageName: string): Error[];

package/dist/data/book-entry/book-page/book-page-controls.js

@@ -1,7 +1,7 @@
 /**
  * Checks and type guards that the input page control init is of the given type.
  *
- * @internal
+ * @category Internal
  */
 export function isControlInitType(controlInit, specificType) {
     return controlInit.controlType === specificType;
@@ -47,7 +47,7 @@ export const controlValueTypes = {
 /**
  * Checks that the given control init object is valid.
  *
- * @internal
+ * @category Internal
  */
 export function checkControls(controlsInit, pageName) {
     if (!controlsInit) {

package/dist/data/book-entry/book-page/define-book-page.js

@@ -2,6 +2,7 @@
 import { check } from '@augment-vir/assert';
 import { BookEntryType } from '../book-entry-type.js';
 import { titleToUrlBreadcrumb } from '../url-breadcrumbs.js';
+import { getPageTitleError } from '../verify-book-entry.js';
 /**
  * A variant of {@link defineBookPage} that allows you specify what the expected global element-book
  * values are for the page that you are defining.
@@ -41,6 +42,7 @@ export function defineBookPage(pageInit) {
                     errors: [
                         alreadyTakenElementExampleNames.has(elementExampleInit.title) &&
                             new Error(`Example title '${elementExampleInit.title}' in page '${pageInit.title}' is already taken.`),
+                        getPageTitleError(elementExampleInit.title),
                     ].filter(check.isTruthy),
                 };
                 alreadyTakenElementExampleNames.add(elementExampleInit.title);

package/dist/data/book-entry/url-breadcrumbs.d.ts

@@ -2,20 +2,20 @@ import { type BookEntry } from './book-entry.js';
 /**
  * Create a list of URL breadcrumbs for the given element-book entry.
  *
- * @internal
+ * @category Internal
  */
 export declare function listUrlBreadcrumbs(entry: BookEntry, includeSelf: boolean): string[];
 /**
  * Convert an element-book entry's title to a URL-safe breadcrumb title.
  *
- * @internal
+ * @category Internal
  */
 export declare function titleToUrlBreadcrumb(title: string): string;
 /**
  * Check if a full list of URL breadcrumbs (`searchIn`) starts with the subset list of URL
  * breadcrumbs (`searchFor`).
  *
- * @internal
+ * @category Internal
  */
 export declare function doBreadcrumbsStartWith({ searchFor, searchIn, }: {
     searchIn: ReadonlyArray<string>;

package/dist/data/book-entry/url-breadcrumbs.js

@@ -2,7 +2,7 @@ import { collapseWhiteSpace } from '@augment-vir/common';
 /**
  * Create a list of URL breadcrumbs for the given element-book entry.
  *
- * @internal
+ * @category Internal
  */
 export function listUrlBreadcrumbs(entry, includeSelf) {
     const entryBreadcrumb = titleToUrlBreadcrumb(entry.title);
@@ -22,7 +22,7 @@ export function listUrlBreadcrumbs(entry, includeSelf) {
 /**
  * Convert an element-book entry's title to a URL-safe breadcrumb title.
  *
- * @internal
+ * @category Internal
  */
 export function titleToUrlBreadcrumb(title) {
     return collapseWhiteSpace(title).toLowerCase().replaceAll(/\s/g, '-');
@@ -31,7 +31,7 @@ export function titleToUrlBreadcrumb(title) {
  * Check if a full list of URL breadcrumbs (`searchIn`) starts with the subset list of URL
  * breadcrumbs (`searchFor`).
  *
- * @internal
+ * @category Internal
  */
 export function doBreadcrumbsStartWith({ searchFor, searchIn, }) {
     return searchFor.every((breadcrumb, index) => {

package/dist/data/book-entry/verify-book-entry.d.ts

@@ -1,3 +1,4 @@
 import { BookEntryType } from './book-entry-type.js';
 import { type BookEntry } from './book-entry.js';
+export declare function getPageTitleError(title: string): Error | undefined;
 export declare const bookEntryVerifiers: { [EntryType in BookEntryType]: (entry: BookEntry) => Error[]; };

package/dist/data/book-entry/verify-book-entry.js

@@ -1,14 +1,27 @@
 import { check } from '@augment-vir/assert';
 import { BookEntryType } from './book-entry-type.js';
 import { checkControls } from './book-page/book-page-controls.js';
+import { titleToUrlBreadcrumb } from './url-breadcrumbs.js';
+/** Characters that are not allowed in book entry titles because they would break URL routing. */
+const invalidTitleCharacters = /[/?#&=]/;
+export function getPageTitleError(title) {
+    const invalidMatch = title.match(invalidTitleCharacters);
+    return title.trim()
+        ? titleToUrlBreadcrumb(title)
+            ? invalidMatch
+                ? new Error(`Book page title has invalid character '${invalidMatch[0]}'.`)
+                : undefined
+            : new Error(`Book page title resolved to empty breadcrumb.`)
+        : new Error(`Cannot define an element-book page with an empty title.`);
+}
 export const bookEntryVerifiers = {
     [BookEntryType.ElementExample]: () => {
-        // currently all element example checking happens on page definition
+        /** Currently all element example checking happens on page definition. */
         return [];
     },
     [BookEntryType.Page]: (bookPage) => {
         return [
-            !bookPage.title && new Error(`Cannot define an element-book page with an empty title.`),
+            getPageTitleError(bookPage.title),
             ...checkControls(bookPage.controls, bookPage.title),
         ].filter(check.isTruthy);
     },

package/dist/ui/elements/entry-display/entry-display/book-lazy-entry.element.d.ts

@@ -0,0 +1,13 @@
+import { type HtmlInterpolation } from 'element-vir';
+export declare const BookLazyEntry: import("element-vir").DeclarativeElementDefinition<"book-lazy-entry", {
+    /**
+     * The content to lazily render. This cannot be rendered via a `<slot>` because then they won't
+     * be lazily rendered.
+     */
+    content: HtmlInterpolation;
+}, {
+    /** Whether the content has been rendered (and should stay rendered). */
+    hasRendered: boolean;
+    /** Reference to the placeholder element for cleanup. */
+    placeholderElement: Element | undefined;
+}, {}, "book-lazy-entry-", "book-lazy-entry-", readonly [], readonly []>;

package/dist/ui/elements/entry-display/entry-display/book-lazy-entry.element.js

@@ -0,0 +1,115 @@
+import { convertDuration } from 'date-vir';
+import { css, html, onDomCreated } from 'element-vir';
+import { defineBookElement } from '../../define-book-element.js';
+/** Debounce time in milliseconds before rendering an entry that becomes visible. */
+const visibilityDebounce = {
+    milliseconds: 10,
+};
+/**
+ * Shared IntersectionObserver instance for all BookLazyEntry elements. Using a single observer is
+ * more performant than creating one per element.
+ */
+let sharedObserver;
+/** Map of observed elements to their callbacks. */
+const observedElements = new Map();
+/** Map of elements to their debounce timeout IDs. */
+const debounceTimeouts = new Map();
+function getSharedObserver() {
+    if (!sharedObserver) {
+        sharedObserver = new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                const element = entry.target;
+                const callback = observedElements.get(element);
+                if (!callback) {
+                    continue;
+                }
+                if (entry.isIntersecting) {
+                    // Element became visible - start debounce timer
+                    if (!debounceTimeouts.has(element)) {
+                        const timeoutId = globalThis.setTimeout(() => {
+                            debounceTimeouts.delete(element);
+                            callback();
+                            // Stop observing after rendering
+                            sharedObserver?.unobserve(element);
+                            observedElements.delete(element);
+                        }, convertDuration(visibilityDebounce, {
+                            milliseconds: true,
+                        }).milliseconds);
+                        debounceTimeouts.set(element, timeoutId);
+                    }
+                }
+                else {
+                    // Element left viewport - cancel debounce if pending
+                    const existingTimeout = debounceTimeouts.get(element);
+                    if (existingTimeout) {
+                        clearTimeout(existingTimeout);
+                        debounceTimeouts.delete(element);
+                    }
+                }
+            }
+        }, {
+            /** Use a small margin to start loading slightly before the element is visible. */
+            rootMargin: '100px',
+        });
+    }
+    return sharedObserver;
+}
+function unobserveElement(element) {
+    const timeout = debounceTimeouts.get(element);
+    if (timeout) {
+        clearTimeout(timeout);
+        debounceTimeouts.delete(element);
+    }
+    observedElements.delete(element);
+    sharedObserver?.unobserve(element);
+}
+export const BookLazyEntry = defineBookElement()({
+    tagName: 'book-lazy-entry',
+    state() {
+        return {
+            /** Whether the content has been rendered (and should stay rendered). */
+            hasRendered: false,
+            /** Reference to the placeholder element for cleanup. */
+            placeholderElement: undefined,
+        };
+    },
+    styles: css `
+        :host {
+            display: contents;
+        }
+
+        .placeholder {
+            /* Minimum height to ensure the placeholder is observable */
+            min-height: 50px;
+            display: block;
+        }
+    `,
+    cleanup({ state }) {
+        if (state.placeholderElement) {
+            unobserveElement(state.placeholderElement);
+        }
+    },
+    render({ inputs, state, updateState }) {
+        if (state.hasRendered) {
+            return inputs.content;
+        }
+        return html `
+            <div
+                class="placeholder"
+                ${onDomCreated((element) => {
+            // Clean up previous observation if any
+            if (state.placeholderElement) {
+                unobserveElement(state.placeholderElement);
+            }
+            updateState({ placeholderElement: element });
+            observedElements.set(element, () => {
+                updateState({ hasRendered: true });
+            });
+            getSharedObserver().observe(element);
+        })}
+            >
+                &nbsp;
+            </div>
+        `;
+    },
+});

package/dist/ui/elements/entry-display/entry-display/create-node-templates.js

@@ -8,6 +8,7 @@ import { BookError } from '../../common/book-error.element.js';
 import { BookPageControls } from '../book-page/book-page-controls.element.js';
 import { BookPageWrapper } from '../book-page/book-page-wrapper.element.js';
 import { BookElementExampleWrapper } from '../element-example/book-element-example-wrapper.element.js';
+import { BookLazyEntry } from './book-lazy-entry.element.js';
 function getFlattenedControlsFromHiddenParents(currentNodes, currentControls, currentNode, originalTree) {
     const parent = traverseToImmediateParent(currentNode, originalTree);
     const allControls = [];
@@ -81,7 +82,7 @@ export function createNodeTemplates({ currentNodes, isTopLevel, router, isSearch
         }
         else if (isBookTreeNode(currentNode, BookEntryType.ElementExample)) {
             const controlsForElementExample = traverseControls(controls, currentNode.fullUrlBreadcrumbs.slice(0, -1));
-            return html `
+            const content = html `
                     <${BookElementExampleWrapper.assign({
                 elementExampleNode: currentNode,
                 currentPageControls: controlsForElementExample,
@@ -92,18 +93,28 @@ export function createNodeTemplates({ currentNodes, isTopLevel, router, isSearch
             })}"
                     ></${BookElementExampleWrapper}>
                 `;
+            return html `
+                    <${BookLazyEntry.assign({
+                content,
+            })}></${BookLazyEntry}>
+                `;
         }
         else if (isBookTreeNode(currentNode, BookEntryType.Root)) {
             return nothing;
         }
         else {
-            return html `
+            const content = html `
                     <${BookError.assign({
                 message: `Unknown entry type for rendering: '${currentNode.entry.entryType}'`,
             })}
                         class="block-entry"
                     ></${BookError}>
                 `;
+            return html `
+                    <${BookLazyEntry.assign({
+                content,
+            })}></${BookLazyEntry}>
+                `;
         }
     });
     return [

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-book",
-    "version": "26.12.1",
+    "version": "26.13.0",
     "keywords": [
         "book",
         "design system",
@@ -41,28 +41,29 @@
         "test:docs": "virmator docs check"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.54.3",
-        "@augment-vir/common": "^31.54.3",
-        "@augment-vir/web": "^31.54.3",
+        "@augment-vir/assert": "^31.57.3",
+        "@augment-vir/common": "^31.57.3",
+        "@augment-vir/web": "^31.57.3",
         "colorjs.io": "0.5.2",
+        "date-vir": "^8.1.0",
         "lit-css-vars": "^3.0.11",
         "spa-router-vir": "^6.4.1",
         "typed-event-target": "^4.1.0"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.54.3",
+        "@augment-vir/test": "^31.57.3",
         "@web/dev-server-esbuild": "^1.0.4",
         "@web/test-runner": "^0.20.2",
         "@web/test-runner-commands": "^0.9.0",
         "@web/test-runner-playwright": "^0.11.1",
         "@web/test-runner-visual-regression": "^0.10.0",
-        "element-vir": "^26.12.1",
+        "element-vir": "^26.13.0",
         "istanbul-smart-text-reporter": "^1.1.5",
         "markdown-code-example-inserter": "^3.0.3",
         "type-fest": "^5.3.1",
         "typedoc": "^0.28.15",
         "typescript": "5.9.3",
-        "vira": "^28.11.0"
+        "vira": "^28.13.0"
     },
     "peerDependencies": {
         "element-vir": ">=17",