element-book 26.12.0 → 26.12.1

package/dist/ui/color-theme/create-color-theme.js

@@ -0,0 +1,93 @@
+import { mapObjectValues } from '@augment-vir/common';
+import Color from 'colorjs.io';
+import { unsafeCSS } from 'element-vir';
+function colorsObjectToCssResult(colors) {
+    return mapObjectValues(colors, (key, value) => {
+        if (value instanceof Color) {
+            return unsafeCSS(value.toString({ format: 'hex' }));
+        }
+        else {
+            return colorsObjectToCssResult(value);
+        }
+    });
+}
+/**
+ * The default theme color.
+ *
+ * @category Internal
+ */
+export const defaultThemeStartColor = 'dodgerblue';
+function calculateTextColorString(color) {
+    const onWhite = Math.abs(color.contrast('white', 'APCA'));
+    const onBlack = Math.abs(color.contrast('black', 'APCA'));
+    const textColorString = onWhite > onBlack ? 'white' : 'black';
+    return textColorString;
+}
+function createColorPair({ background, foreground, }) {
+    return {
+        background: background ?? new Color(calculateTextColorString(foreground)),
+        foreground: foreground ?? new Color(calculateTextColorString(background)),
+    };
+}
+/**
+ * Theme style options for the element-book app.
+ *
+ * @category Internal
+ */
+export var ThemeStyle;
+(function (ThemeStyle) {
+    ThemeStyle["Dark"] = "dark";
+    ThemeStyle["Light"] = "light";
+})(ThemeStyle || (ThemeStyle = {}));
+function flipBackForeground(input) {
+    return input === 'black' ? 'white' : 'black';
+}
+const faintForegroundColors = {
+    black: {
+        foregroundFaint1: new Color('#ccc'),
+        foregroundFaint2: new Color('#eee'),
+    },
+    white: {
+        foregroundFaint1: new Color('#ccc'),
+        foregroundFaint2: new Color('#eee'),
+    },
+};
+const faintBackgroundColors = {
+    black: {
+        backgroundFaint1: new Color('#666'),
+        backgroundFaint2: new Color('#444'),
+    },
+    white: {
+        backgroundFaint1: new Color('#ccc'),
+        backgroundFaint2: new Color('#fafafa'),
+    },
+};
+/**
+ * Creates a theme from the given theme configuration.
+ *
+ * @category Internal
+ */
+export function createTheme({ themeColor: inputThemeColor = defaultThemeStartColor, themeStyle = ThemeStyle.Light, } = {}) {
+    const themeColor = new Color(inputThemeColor);
+    const backgroundColor = new Color(themeStyle === ThemeStyle.Dark ? 'black' : 'white');
+    const foregroundColorString = calculateTextColorString(backgroundColor);
+    const foregroundColor = new Color(foregroundColorString);
+    const colors = {
+        nav: {
+            hover: createColorPair({ background: themeColor.clone().set({ 'hsl.l': 93 }) }),
+            active: createColorPair({ background: themeColor.clone().set({ 'hsl.l': 90 }) }),
+            selected: createColorPair({ background: themeColor.clone().set({ 'hsl.l': 85 }) }),
+        },
+        accent: {
+            icon: themeColor.clone().set({ 'hsl.l': 40 }),
+        },
+        page: {
+            background: backgroundColor,
+            ...faintBackgroundColors[flipBackForeground(foregroundColorString)],
+            foreground: foregroundColor,
+            ...faintForegroundColors[foregroundColorString],
+        },
+    };
+    const convertedToCssResults = colorsObjectToCssResult(colors);
+    return convertedToCssResults;
+}

package/dist/ui/elements/book-breadcrumbs.element.d.ts

@@ -0,0 +1,6 @@
+import { type BookRouter } from '../../routing/book-router.js';
+import { type BookFullRoute } from '../../routing/book-routing.js';
+export declare const BookBreadcrumbs: import("element-vir").DeclarativeElementDefinition<"book-breadcrumbs", {
+    currentRoute: Readonly<BookFullRoute>;
+    router: Readonly<BookRouter> | undefined;
+}, {}, {}, "book-breadcrumbs-", "book-breadcrumbs-", readonly [], readonly []>;

package/dist/ui/elements/book-breadcrumbs.element.js

@@ -0,0 +1,50 @@
+import { css, html } from 'element-vir';
+import { BookMainRoute } from '../../routing/book-routing.js';
+import { BookRouteLink } from './common/book-route-link.element.js';
+import { defineBookElement } from './define-book-element.js';
+export const BookBreadcrumbs = defineBookElement()({
+    tagName: 'book-breadcrumbs',
+    styles: css `
+        :host {
+            display: flex;
+            color: #999;
+        }
+
+        .spacer {
+            padding: 0 4px;
+        }
+    `,
+    render: ({ inputs }) => {
+        const bookPaths = inputs.currentRoute.paths.slice(1);
+        if (!bookPaths.length) {
+            return html `
+                 
+            `;
+        }
+        return bookPaths.map((currentPath, pathIndex, pathsArray) => {
+            const isLastPath = pathIndex >= pathsArray.length - 1;
+            const fullPathSoFar = pathsArray.slice(0, pathIndex + 1);
+            const spacer = isLastPath
+                ? ''
+                : html `
+                      <span class="spacer">&gt;</span>
+                  `;
+            return html `
+                <${BookRouteLink.assign({
+                route: {
+                    hash: undefined,
+                    search: undefined,
+                    paths: [
+                        BookMainRoute.Book,
+                        ...fullPathSoFar,
+                    ],
+                },
+                router: inputs.router,
+            })}>
+                    ${currentPath}
+                </${BookRouteLink}>
+                ${spacer}
+            `;
+        });
+    },
+});

package/dist/ui/elements/book-nav/book-nav-filter.d.ts

@@ -0,0 +1,2 @@
+import { type BookTreeNode } from '../../../data/book-tree/book-tree-node.js';
+export declare function shouldShowTreeNodeInNav(currentNode: Readonly<BookTreeNode>, selectedPath: undefined | ReadonlyArray<string>): boolean;

package/dist/ui/elements/book-nav/book-nav-filter.js

@@ -0,0 +1,15 @@
+import { check } from '@augment-vir/assert';
+import { BookEntryType } from '../../../data/book-entry/book-entry-type.js';
+export function shouldShowTreeNodeInNav(currentNode, selectedPath) {
+    if (currentNode.entry.entryType === BookEntryType.Root) {
+        return false;
+    }
+    if (currentNode.entry.entryType === BookEntryType.Page) {
+        return true;
+    }
+    const isParentSelected = check.jsonEquals(selectedPath, currentNode.fullUrlBreadcrumbs.slice(0, -1));
+    if (isParentSelected) {
+        return true;
+    }
+    return check.jsonEquals(selectedPath?.slice(0, -1), currentNode.fullUrlBreadcrumbs.slice(0, -1));
+}

package/dist/ui/elements/book-nav/book-nav.element.d.ts

@@ -0,0 +1,8 @@
+import { type BookTreeNode } from '../../../data/book-tree/book-tree-node.js';
+import { type BookRouter } from '../../../routing/book-router.js';
+export declare const BookNav: import("element-vir").DeclarativeElementDefinition<"book-nav", {
+    flattenedNodes: ReadonlyArray<Readonly<BookTreeNode>>;
+    selectedPath: ReadonlyArray<string> | undefined;
+    router: BookRouter | undefined;
+}, {}, {}, "book-nav-", "book-nav-internal-indent", readonly [], readonly []>;
+export declare function scrollSelectedNavElementIntoView(bookNavInstance: typeof BookNav.InstanceType): Promise<void>;

package/{src/ui/elements/book-nav/book-nav.element.ts → dist/ui/elements/book-nav/book-nav.element.js}

@@ -1,35 +1,26 @@
-import {check} from '@augment-vir/assert';
-import {checkIfEntirelyInScrollView, waitForAnimationFrame} from '@augment-vir/web';
-import {classMap, css, html, renderIf} from 'element-vir';
-import {Element16Icon, ViraIcon} from 'vira';
-import {BookEntryType} from '../../../data/book-entry/book-entry-type.js';
-import {type BookTreeNode} from '../../../data/book-tree/book-tree-node.js';
-import {isBookTreeNode} from '../../../data/book-tree/book-tree.js';
-import {type BookRouter} from '../../../routing/book-router.js';
-import {BookMainRoute, defaultBookFullRoute} from '../../../routing/book-routing.js';
-import {colorThemeCssVars} from '../../color-theme/color-theme.js';
-import {BookRouteLink} from '../common/book-route-link.element.js';
-import {defineBookElement} from '../define-book-element.js';
-import {ElementBookSlotName} from '../element-book-app/element-book-app-slots.js';
-import {shouldShowTreeNodeInNav} from './book-nav-filter.js';
-
-export const BookNav = defineBookElement<{
-    flattenedNodes: ReadonlyArray<Readonly<BookTreeNode>>;
-    selectedPath: ReadonlyArray<string> | undefined;
-    router: BookRouter | undefined;
-}>()({
+import { check } from '@augment-vir/assert';
+import { checkIfEntirelyInScrollView, waitForAnimationFrame } from '@augment-vir/web';
+import { classMap, css, html, renderIf } from 'element-vir';
+import { Element16Icon, ViraIcon } from 'vira';
+import { BookEntryType } from '../../../data/book-entry/book-entry-type.js';
+import { isBookTreeNode } from '../../../data/book-tree/book-tree.js';
+import { BookMainRoute, defaultBookFullRoute } from '../../../routing/book-routing.js';
+import { colorThemeCssVars } from '../../color-theme/color-theme.js';
+import { BookRouteLink } from '../common/book-route-link.element.js';
+import { defineBookElement } from '../define-book-element.js';
+import { ElementBookSlotName } from '../element-book-app/element-book-app-slots.js';
+import { shouldShowTreeNodeInNav } from './book-nav-filter.js';
+export const BookNav = defineBookElement()({
     tagName: 'book-nav',
     cssVars: {
         'book-nav-internal-indent': '0',
     },
-    styles: ({cssVars}) => css`
+    styles: ({ cssVars }) => css `
         :host {
             display: flex;
             flex-direction: column;
             padding: 16px 0;
-            background-color: ${colorThemeCssVars[
-                'element-book-page-background-faint-level-2-color'
-            ].value};
+            background-color: ${colorThemeCssVars['element-book-page-background-faint-level-2-color'].value};
         }
 
         .title-row:hover {
@@ -39,15 +30,15 @@ export const BookNav = defineBookElement<{
 
         .title-row:active {
             background-color: ${colorThemeCssVars['element-book-nav-active-background-color']
-                .value};
+        .value};
             color: ${colorThemeCssVars['element-book-nav-active-foreground-color'].value};
         }
 
         .title-row {
             display: block;
             ${BookRouteLink.cssVars['book-route-link-anchor-padding']
-                .name}: 1px 24px 1px calc(calc(16px * ${cssVars['book-nav-internal-indent']
-                .value}) + 8px);
+        .name}: 1px 24px 1px calc(calc(16px * ${cssVars['book-nav-internal-indent']
+        .value}) + 8px);
         }
 
         ul {
@@ -59,7 +50,7 @@ export const BookNav = defineBookElement<{
         .selected,
         .selected:hover {
             background-color: ${colorThemeCssVars['element-book-nav-selected-background-color']
-                .value};
+        .value};
             color: ${colorThemeCssVars['element-book-nav-selected-foreground-color'].value};
             pointer-events: none;
         }
@@ -79,52 +70,47 @@ export const BookNav = defineBookElement<{
             color: ${colorThemeCssVars['element-book-accent-icon-color'].value};
         }
     `,
-    render({inputs}) {
+    render({ inputs }) {
         const navTreeTemplates = inputs.flattenedNodes.map((treeNode) => {
             if (!shouldShowTreeNodeInNav(treeNode, inputs.selectedPath)) {
                 return;
             }
-            const liStyle = css`
+            const liStyle = css `
                 --book-nav-internal-indent: ${treeNode.fullUrlBreadcrumbs.length - 1};
             `;
-
-            return html`
+            return html `
                 <li style=${liStyle}>
                     <${BookRouteLink.assign({
-                        router: inputs.router,
-                        route: {
-                            paths: [
-                                BookMainRoute.Book,
-                                ...treeNode.fullUrlBreadcrumbs,
-                            ],
-                        },
-                    })}
+                router: inputs.router,
+                route: {
+                    paths: [
+                        BookMainRoute.Book,
+                        ...treeNode.fullUrlBreadcrumbs,
+                    ],
+                },
+            })}
                         class=${classMap({
-                            'title-row': true,
-                            selected: inputs.selectedPath
-                                ? check.jsonEquals(inputs.selectedPath, treeNode.fullUrlBreadcrumbs)
-                                : false,
-                        })}
+                'title-row': true,
+                selected: inputs.selectedPath
+                    ? check.jsonEquals(inputs.selectedPath, treeNode.fullUrlBreadcrumbs)
+                    : false,
+            })}
                     >
                         <div class="title-text">
-                            ${renderIf(
-                                isBookTreeNode(treeNode, BookEntryType.ElementExample),
-                                html`
-                                    <${ViraIcon.assign({icon: Element16Icon})}></${ViraIcon}>
-                                `,
-                            )}
+                            ${renderIf(isBookTreeNode(treeNode, BookEntryType.ElementExample), html `
+                                    <${ViraIcon.assign({ icon: Element16Icon })}></${ViraIcon}>
+                                `)}
                             ${treeNode.entry.title}
                         </div>
                     </${BookRouteLink}>
                 </li>
             `;
         });
-
-        return html`
+        return html `
             <${BookRouteLink.assign({
-                route: defaultBookFullRoute,
-                router: inputs.router,
-            })}>
+            route: defaultBookFullRoute,
+            router: inputs.router,
+        })}>
                 <slot name=${ElementBookSlotName.NavHeader}>Book</slot>
             </${BookRouteLink}>
             <ul>
@@ -133,21 +119,14 @@ export const BookNav = defineBookElement<{
         `;
     },
 });
-
-export async function scrollSelectedNavElementIntoView(
-    bookNavInstance: typeof BookNav.InstanceType,
-) {
+export async function scrollSelectedNavElementIntoView(bookNavInstance) {
     await waitForAnimationFrame(2);
-
     const selected = bookNavInstance.shadowRoot.querySelector('.selected');
-
     if (!selected) {
         throw new Error('Failed to find selected nav tree element.');
     }
-
     if (await checkIfEntirelyInScrollView(selected)) {
         return;
     }
-
-    selected.scrollIntoView({behavior: 'smooth', block: 'center'});
+    selected.scrollIntoView({ behavior: 'smooth', block: 'center' });
 }

package/dist/ui/elements/common/book-error.element.d.ts

@@ -0,0 +1,3 @@
+export declare const BookError: import("element-vir").DeclarativeElementDefinition<"book-error", {
+    message: string | ReadonlyArray<string>;
+}, {}, {}, "book-error-", "book-error-", readonly [], readonly []>;

package/{src/ui/elements/common/book-error.element.ts → dist/ui/elements/common/book-error.element.js}

@@ -1,10 +1,9 @@
-import {check} from '@augment-vir/assert';
-import {css, html} from 'element-vir';
-import {defineBookElement} from '../define-book-element.js';
-
-export const BookError = defineBookElement<{message: string | ReadonlyArray<string>}>()({
+import { check } from '@augment-vir/assert';
+import { css, html } from 'element-vir';
+import { defineBookElement } from '../define-book-element.js';
+export const BookError = defineBookElement()({
     tagName: 'book-error',
-    styles: css`
+    styles: css `
         :host {
             display: flex;
             flex-direction: column;
@@ -17,13 +16,10 @@ export const BookError = defineBookElement<{message: string | ReadonlyArray<stri
             padding: 0;
         }
     `,
-    render({inputs}) {
+    render({ inputs }) {
         const paragraphs = check.isArray(inputs.message) ? inputs.message : [inputs.message];
-
-        return paragraphs.map(
-            (paragraph) => html`
+        return paragraphs.map((paragraph) => html `
                 <p>${paragraph}</p>
-            `,
-        );
+            `);
     },
 });

package/dist/ui/elements/common/book-route-link.element.d.ts

@@ -0,0 +1,6 @@
+import { type BookRouter } from '../../../routing/book-router.js';
+import { type BookFullRoute } from '../../../routing/book-routing.js';
+export declare const BookRouteLink: import("element-vir").DeclarativeElementDefinition<"book-route-link", {
+    route: Partial<BookFullRoute>;
+    router: Readonly<BookRouter> | undefined;
+}, {}, {}, "book-route-link-", "book-route-link-anchor-padding", readonly [], readonly []>;

package/dist/ui/elements/common/book-route-link.element.js

@@ -0,0 +1,40 @@
+import { css, html, listen } from 'element-vir';
+import { shouldClickEventTriggerRouteChange } from 'spa-router-vir';
+import { ChangeRouteEvent } from '../../events/change-route.event.js';
+import { defineBookElement } from '../define-book-element.js';
+export const BookRouteLink = defineBookElement()({
+    tagName: 'book-route-link',
+    cssVars: {
+        'book-route-link-anchor-padding': '',
+    },
+    styles: ({ cssVars }) => css `
+        a {
+            box-sizing: border-box;
+            display: block;
+            padding: ${cssVars['book-route-link-anchor-padding'].value};
+            text-decoration: inherit;
+            color: inherit;
+            height: 100%;
+            width: 100%;
+        }
+    `,
+    render: ({ inputs, dispatch }) => {
+        const linkUrl = inputs.router?.createRouteUrl({
+            ...inputs.route,
+        }) ?? '#';
+        return html `
+            <a
+                href=${linkUrl}
+                ${listen('click', (clickEvent) => {
+            if (!inputs.router || shouldClickEventTriggerRouteChange(clickEvent)) {
+                clickEvent.preventDefault();
+                window.scrollTo(0, 0);
+                dispatch(new ChangeRouteEvent(inputs.route));
+            }
+        })}
+            >
+                <slot></slot>
+            </a>
+        `;
+    },
+});

package/dist/ui/elements/define-book-element.d.ts

@@ -0,0 +1,2 @@
+export type BookTagName = `book-${string}`;
+export declare const defineBookElement: <Inputs extends {}>(...errorParams: import("element-vir").DeclarativeElementInputErrorParams<Inputs>) => <const TagName extends `book-${string}`, State extends {}, EventsInit extends {}, const HostClassKeys extends `${TagName}-${string}` = `${TagName}-`, const CssVarKeys extends `${TagName}-${string}` = `${TagName}-`, const SlotNames extends ReadonlyArray<string> = readonly [], const TestIds extends ReadonlyArray<string> = readonly []>(inputs: import("element-vir").DeclarativeElementInit<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames, TestIds>) => import("element-vir").DeclarativeElementDefinition<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames, TestIds>;

package/dist/ui/elements/define-book-element.js

@@ -0,0 +1,2 @@
+import { wrapDefineElement } from 'element-vir';
+export const defineBookElement = wrapDefineElement();

package/{src/ui/elements/element-book-app/element-book-app-slots.ts → dist/ui/elements/element-book-app/element-book-app-slots.d.ts}

@@ -3,15 +3,15 @@
  *
  * @category Main
  */
-export enum ElementBookSlotName {
+export declare enum ElementBookSlotName {
     /**
      * Used to specify a footer for the main element example viewer. It always appears at the bottom
      * of the viewer's scroll area.
      */
-    Footer = 'book-footer',
+    Footer = "book-footer",
     /**
      * Used to specify a header above the navigation sidebar. This is a particularly good place for
      * branding.
      */
-    NavHeader = 'book-nav-header',
+    NavHeader = "book-nav-header"
 }

package/dist/ui/elements/element-book-app/element-book-app-slots.js

@@ -0,0 +1,18 @@
+/**
+ * Slots to be used on an element-book app instance for inserting custom HTML into the app.
+ *
+ * @category Main
+ */
+export var ElementBookSlotName;
+(function (ElementBookSlotName) {
+    /**
+     * Used to specify a footer for the main element example viewer. It always appears at the bottom
+     * of the viewer's scroll area.
+     */
+    ElementBookSlotName["Footer"] = "book-footer";
+    /**
+     * Used to specify a header above the navigation sidebar. This is a particularly good place for
+     * branding.
+     */
+    ElementBookSlotName["NavHeader"] = "book-nav-header";
+})(ElementBookSlotName || (ElementBookSlotName = {}));

package/dist/ui/elements/element-book-app/element-book-app.element.d.ts

@@ -0,0 +1,35 @@
+import { type ControlsWrapper } from '../../../data/book-entry/book-page/controls-wrapper.js';
+import { type BookRouter } from '../../../routing/book-router.js';
+import { type ColorTheme } from '../../color-theme/color-theme.js';
+import { type ThemeConfig } from '../../color-theme/create-color-theme.js';
+import { type ElementBookConfig } from './element-book-config.js';
+import { type GlobalValues } from './global-values.js';
+/**
+ * Current color theme state used inside of {@link ElementBookApp}.
+ *
+ * @category Internal
+ */
+export type ColorThemeState = {
+    config: ThemeConfig | undefined;
+    theme: ColorTheme;
+};
+/**
+ * The element-book app itself. Instantiate one of these where you want your element-book pages to
+ * render. Make sure to also provide an array of pages to actually render!
+ *
+ * @category Main
+ */
+export declare const ElementBookApp: import("element-vir").DeclarativeElementDefinition<"element-book-app", ElementBookConfig, {
+    currentRoute: Readonly<Readonly<Required<import("spa-router-vir").SpaRoute<import("../../../routing/book-routing.js").ValidBookPaths, undefined, undefined>>>>;
+    router: undefined | BookRouter;
+    loading: boolean;
+    colors: ColorThemeState;
+    treeBasedControls: {
+        pages: ElementBookConfig["pages"];
+        lastGlobalInputs: GlobalValues;
+        controls: ControlsWrapper;
+    } | undefined;
+    originalWindowTitle: string | undefined;
+}, {
+    pathUpdate: import("element-vir").DefineEvent<readonly string[]>;
+}, "element-book-app-", "element-book-app-", readonly [], readonly []>;