element-book 6.0.3 → 7.0.1

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

@@ -1,28 +1,32 @@
 import { areJsonEqual, extractErrorMessage } from '@augment-vir/common';
 import { assign, css, defineElement, defineElementEvent, html, listen } from 'element-vir';
-import { entriesToTree } from '../../../data/element-book-entry/entry-tree/entry-tree';
-import { createSearchedTree } from '../../../data/element-book-entry/entry-tree/entry-tree-search';
-import { createElementBookRouter } from '../../../routing/create-element-book-router';
-import { defaultElementBookFullRoute, extractSearchQuery, } from '../../../routing/element-book-routing';
+import { createControlsFromTree, createNewCurrentControls, } from '../../../data/book-entry/book-page/current-controls';
+import { createBookTreeFromEntries } from '../../../data/book-tree/book-tree';
+import { searchFlattenedNodes } from '../../../data/book-tree/search-nodes';
+import { defaultBookFullRoute, extractSearchQuery, } from '../../../routing/book-routing';
+import { createBookRouter } from '../../../routing/create-book-router';
 import { colorThemeCssVars, setThemeCssVars } from '../../color-theme/color-theme';
 import { createTheme } from '../../color-theme/create-color-theme';
 import { ChangeRouteEvent } from '../../events/change-route.event';
-import { ElementBookNav } from '../element-book-nav.element';
-import { ElementBookEntryDisplay } from '../entry-display/element-book-entry-display.element';
+import { BookNav } from '../book-nav.element';
+import { BookError } from '../common/book-error.element';
+import { BookEntryDisplay } from '../entry-display/book-entry-display.element';
+import { BookPageControls } from '../entry-display/book-page/book-page-controls.element';
 import { ElementBookSlotName } from './element-book-app-slots';
-import { getCurrentTreeEntry } from './get-current-entry';
+import { getCurrentNodes } from './get-current-nodes';
 export const ElementBookApp = defineElement()({
     tagName: 'element-book-app',
     events: {
         pathUpdate: defineElementEvent(),
     },
     stateInitStatic: {
-        currentRoute: defaultElementBookFullRoute,
+        currentRoute: defaultBookFullRoute,
         router: undefined,
         colors: {
             config: undefined,
             theme: createTheme(undefined),
         },
+        treeBasedCurrentControls: undefined,
     },
     styles: css `
         :host {
@@ -45,14 +49,14 @@ export const ElementBookApp = defineElement()({
             position: relative;
         }
 
-        ${ElementBookEntryDisplay} {
+        ${BookEntryDisplay} {
             flex-grow: 1;
             overflow-x: hidden;
             overflow-y: auto;
             max-height: 100%;
         }
 
-        ${ElementBookNav} {
+        ${BookNav} {
             flex-shrink: 0;
             position: sticky;
             overflow-x: hidden;
@@ -91,7 +95,7 @@ export const ElementBookApp = defineElement()({
                 updateRoutes({ paths: inputs.elementBookRoutePaths });
             }
             if (inputs.internalRouterConfig?.useInternalRouter && !state.router) {
-                const router = createElementBookRouter(inputs.internalRouterConfig.basePath);
+                const router = createBookRouter(inputs.internalRouterConfig.basePath);
                 updateState({ router });
                 router.addRouteListener(true, (fullRoute) => {
                     updateState({
@@ -115,54 +119,97 @@ export const ElementBookApp = defineElement()({
                 });
                 setThemeCssVars(host, newTheme);
             }
-            const originalTree = entriesToTree(inputs.entries, inputs.everythingTitle);
+            const debug = inputs.debug ?? false;
+            const originalTree = createBookTreeFromEntries({
+                entries: inputs.entries,
+                everythingTitle: inputs.everythingTitle,
+                everythingDescriptionParagraphs: inputs.everythingDescriptionParagraphs ?? [],
+                debug,
+            });
+            if (!state.treeBasedCurrentControls ||
+                state.treeBasedCurrentControls.trigger !== inputs.entries) {
+                updateState({
+                    treeBasedCurrentControls: {
+                        trigger: inputs.entries,
+                        currentControls: createControlsFromTree(originalTree.tree),
+                    },
+                });
+            }
             const searchQuery = extractSearchQuery(state.currentRoute.paths);
-            const searchedTree = searchQuery
-                ? createSearchedTree({
-                    entries: inputs.entries,
+            const searchedNodes = searchQuery
+                ? searchFlattenedNodes({
+                    flattenedNodes: originalTree.flattenedNodes,
                     searchQuery,
-                    startTree: originalTree,
                 })
-                : originalTree;
-            const currentEntryTreeNode = getCurrentTreeEntry(searchedTree, state.currentRoute.paths, updateRoutes);
+                : undefined;
+            const currentNodes = searchedNodes ??
+                getCurrentNodes(originalTree.flattenedNodes, state.currentRoute.paths, updateRoutes);
+            const currentControls = state.treeBasedCurrentControls?.currentControls;
+            if (!currentControls) {
+                return html `
+                    <${BookError}
+                        ${assign(BookError, { message: 'Failed to generate page controls.' })}
+                    ></${BookError}>
+                `;
+            }
+            if (inputs.debug) {
+                console.info({ currentControls });
+            }
             return html `
                 <div
                     class="root"
                     ${listen(ChangeRouteEvent, (event) => {
-                const entryDisplay = host.shadowRoot.querySelector(ElementBookEntryDisplay.tagName);
+                const entryDisplay = host.shadowRoot.querySelector(BookEntryDisplay.tagName);
                 if (entryDisplay) {
                     entryDisplay.scroll({ top: 0, behavior: 'smooth' });
                 }
                 else {
-                    console.error(`Failed to find '${ElementBookEntryDisplay.tagName}' for scrolling.`);
+                    console.error(`Failed to find '${BookEntryDisplay.tagName}' for scrolling.`);
                 }
                 updateRoutes(event.detail);
+            })}
+                    ${listen(BookPageControls.events.controlValueChange, (event) => {
+                if (!state.treeBasedCurrentControls) {
+                    return;
+                }
+                const newControls = createNewCurrentControls(currentControls, event.detail.fullUrlBreadcrumbs, event.detail.newValues);
+                updateState({
+                    treeBasedCurrentControls: {
+                        ...state.treeBasedCurrentControls,
+                        currentControls: newControls,
+                    },
+                });
             })}
                 >
-                    <${ElementBookNav}
-                        ${assign(ElementBookNav, {
-                tree: originalTree,
+                    <${BookNav}
+                        ${assign(BookNav, {
+                flattenedNodes: originalTree.flattenedNodes,
                 router: state.router,
-                selectedPath: state.currentRoute.paths,
+                selectedPath: searchQuery
+                    ? undefined
+                    : state.currentRoute.paths.slice(1),
             })}
                     >
                         <slot
                             name=${ElementBookSlotName.NavHeader}
                             slot=${ElementBookSlotName.NavHeader}
                         ></slot>
-                    </${ElementBookNav}>
-                    <${ElementBookEntryDisplay}
-                        ${assign(ElementBookEntryDisplay, {
+                    </${BookNav}>
+                    <${BookEntryDisplay}
+                        ${assign(BookEntryDisplay, {
                 currentRoute: state.currentRoute,
-                currentNode: currentEntryTreeNode,
+                currentNodes,
                 router: state.router,
+                debug,
+                currentControls,
+                originalTree: originalTree.tree,
             })}
                     >
                         <slot
                             name=${ElementBookSlotName.Footer}
                             slot=${ElementBookSlotName.Footer}
                         ></slot>
-                    </${ElementBookEntryDisplay}>
+                    </${BookEntryDisplay}>
                 </div>
             `;
         }

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

@@ -1,15 +1,17 @@
 import { PartialAndUndefined } from '@augment-vir/common';
 import { RequireExactlyOne } from 'type-fest';
-import { ElementBookEntry } from '../../../data/element-book-entry/element-book-entry';
+import { BookEntry } from '../../../data/book-entry/book-entry';
 export type ElementBookConfig = {
     /** All element-book entries in order. */
-    entries: ReadonlyArray<ElementBookEntry>;
+    entries: ReadonlyArray<BookEntry>;
 } & PartialAndUndefined<OptionalConfig>;
 type OptionalConfig = {
     /** The base theme color from which all other element-book colors will be generated from. */
     themeColor: string;
     /** The title to use for the "Everything" nav link. */
     everythingTitle: string;
+    everythingDescriptionParagraphs: ReadonlyArray<string>;
+    debug: boolean;
 } & RequireExactlyOne<{
     /**
      * Set this internal router config if element-book is intended to be the current website's

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

@@ -0,0 +1,3 @@
+import { BookTreeNode } from '../../../data/book-tree/book-tree-node';
+import { BookFullRoute, ValidBookPaths } from '../../../routing/book-routing';
+export declare function getCurrentNodes(flattenedNodes: ReadonlyArray<Readonly<BookTreeNode>>, currentPaths: Readonly<ValidBookPaths>, updateRoutes: (newRoute: Partial<BookFullRoute>) => void): BookTreeNode[];

package/dist/ui/elements/element-book-app/get-current-nodes.js

@@ -0,0 +1,23 @@
+import { doBreadcrumbsStartWith } from '../../../data/book-entry/url-breadcrumbs';
+import { defaultBookFullRoute } from '../../../routing/book-routing';
+export function getCurrentNodes(flattenedNodes, currentPaths, updateRoutes) {
+    const filteredNodes = filterNodes(flattenedNodes, currentPaths);
+    if (filteredNodes.length) {
+        return filteredNodes;
+    }
+    else {
+        updateRoutes(defaultBookFullRoute);
+    }
+    const filteredNodesFromDefaultPath = filterNodes(flattenedNodes, defaultBookFullRoute.paths);
+    if (!filteredNodesFromDefaultPath) {
+        throw new Error(`Tried to self-correct for invalid path ${currentPaths.join('/')}
+                        but failed to do so.`);
+    }
+    return filteredNodesFromDefaultPath;
+}
+function filterNodes(flattenedNodes, paths) {
+    return flattenedNodes.filter((node) => doBreadcrumbsStartWith({
+        searchFor: paths.slice(1),
+        searchIn: node.fullUrlBreadcrumbs,
+    }));
+}

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

@@ -0,0 +1,6 @@
+import { BookFullRoute, BookRouter } from '../../../routing/book-routing';
+export declare const BookBreadcrumbsBar: import("element-vir").DeclarativeElementDefinition<"book-breadcrumbs-bar", {
+    currentSearch: string;
+    currentRoute: BookFullRoute;
+    router: BookRouter;
+}, {}, {}, `book-breadcrumbs-bar-${string}`, `book-breadcrumbs-bar-${string}`, import("lit-html").HTMLTemplateResult>;

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

@@ -0,0 +1,65 @@
+import { wait } from '@augment-vir/common';
+import { assign, css, html, listen, renderIf } from 'element-vir';
+import { BookMainRoute, defaultBookFullRoute, } from '../../../routing/book-routing';
+import { colorThemeCssVars } from '../../color-theme/color-theme';
+import { ChangeRouteEvent } from '../../events/change-route.event';
+import { BookBreadcrumbs } from '../book-breadcrumbs.element';
+import { defineBookElement } from '../define-book-element';
+export const BookBreadcrumbsBar = defineBookElement()({
+    tagName: 'book-breadcrumbs-bar',
+    styles: css `
+        :host {
+            position: sticky;
+            top: 0;
+            border-bottom: 1px solid
+                ${colorThemeCssVars['element-book-page-foreground-faint-level-2-color'].value};
+            padding: 4px 8px;
+            background-color: ${colorThemeCssVars['element-book-page-background-color'].value};
+            z-index: 9999999999;
+            display: flex;
+            gap: 16px;
+            justify-content: space-between;
+        }
+    `,
+    renderCallback({ inputs, dispatch }) {
+        return html `
+            ${renderIf(!!inputs.currentSearch, html `
+                     
+                `, html `
+                    <${BookBreadcrumbs}
+                        ${assign(BookBreadcrumbs, {
+            currentRoute: inputs.currentRoute,
+            router: inputs.router,
+        })}
+                    ></${BookBreadcrumbs}>
+                `)}
+            <input
+                placeholder="search"
+                .value=${inputs.currentSearch}
+                ${listen('input', async (event) => {
+            const inputElement = event.currentTarget;
+            if (!(inputElement instanceof HTMLInputElement)) {
+                throw new Error('Failed to find input element for search.');
+            }
+            const preThrottleValue = inputElement.value;
+            // throttle it a bit
+            await wait(200);
+            if (inputElement.value !== preThrottleValue) {
+                return;
+            }
+            if (inputElement.value) {
+                dispatch(new ChangeRouteEvent({
+                    paths: [
+                        BookMainRoute.Search,
+                        encodeURIComponent(inputElement.value),
+                    ],
+                }));
+            }
+            else {
+                dispatch(new ChangeRouteEvent(defaultBookFullRoute));
+            }
+        })}
+            />
+        `;
+    },
+});

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

@@ -0,0 +1,3 @@
+export declare const BookEntryDescription: import("element-vir").DeclarativeElementDefinition<"book-entry-description", {
+    descriptionParagraphs: ReadonlyArray<string>;
+}, {}, {}, `book-entry-description-${string}`, `book-entry-description-${string}`, import("lit-html").HTMLTemplateResult[]>;

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

@@ -0,0 +1,34 @@
+import { css, html } from 'element-vir';
+import { colorThemeCssVars } from '../../color-theme/color-theme';
+import { defineBookElement } from '../define-book-element';
+export const BookEntryDescription = defineBookElement()({
+    tagName: 'book-entry-description',
+    styles: css `
+        :host {
+            color: ${colorThemeCssVars['element-book-page-foreground-faint-level-1-color'].value};
+            display: inline-flex;
+            flex-direction: column;
+            gap: 8px;
+        }
+
+        :host(:hover) {
+            color: ${colorThemeCssVars['element-book-page-foreground-color'].value};
+        }
+
+        p {
+            margin: 0;
+            padding: 0;
+        }
+
+        p:first-child {
+            margin-top: 8px;
+        }
+    `,
+    renderCallback({ inputs }) {
+        return inputs.descriptionParagraphs.map((paragraph) => {
+            return html `
+                <p>${paragraph}</p>
+            `;
+        });
+    },
+});

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

@@ -0,0 +1,12 @@
+import { BookEntryTypeEnum } from '../../../data/book-entry/book-entry-type';
+import { CurrentControls } from '../../../data/book-entry/book-page/current-controls';
+import { BookTreeNode } from '../../../data/book-tree/book-tree-node';
+import { BookFullRoute, BookRouter } from '../../../routing/book-routing';
+export declare const BookEntryDisplay: import("element-vir").DeclarativeElementDefinition<"book-entry-display", {
+    currentRoute: Readonly<BookFullRoute>;
+    currentNodes: ReadonlyArray<BookTreeNode>;
+    originalTree: Readonly<BookTreeNode<BookEntryTypeEnum.Root>>;
+    router: BookRouter;
+    debug: boolean;
+    currentControls: CurrentControls;
+}, {}, {}, `book-entry-display-${string}`, `book-entry-display-${string}`, import("lit-html").HTMLTemplateResult>;

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

@@ -0,0 +1,173 @@
+import { assign, css, html, repeat } from 'element-vir';
+import { BookEntryTypeEnum } from '../../../data/book-entry/book-entry-type';
+import { isLengthAtLeast, mapObjectValues } from '@augment-vir/common';
+import { traverseCurrentControls, } from '../../../data/book-entry/book-page/current-controls';
+import { isBookTreeNode, traverseToImmediateParent } from '../../../data/book-tree/book-tree';
+import { extractSearchQuery } from '../../../routing/book-routing';
+import { BookError } from '../common/book-error.element';
+import { defineBookElement } from '../define-book-element';
+import { ElementBookSlotName } from '../element-book-app/element-book-app-slots';
+import { BookBreadcrumbsBar } from './book-breadcrumbs-bar.element';
+import { BookPageControls } from './book-page/book-page-controls.element';
+import { BookPageWrapper } from './book-page/book-page-wrapper.element';
+import { BookElementExampleWrapper } from './element-example/book-element-example-wrapper.element';
+export const BookEntryDisplay = defineBookElement()({
+    tagName: 'book-entry-display',
+    styles: css `
+        :host {
+            display: flex;
+            flex-direction: column;
+        }
+
+        .all-book-entries-wrapper {
+            flex-grow: 1;
+            padding: 32px;
+        }
+
+        .inline-entry {
+            margin-top: 32px;
+        }
+
+        .inline-entry + .inline-entry {
+            margin-left: 16px;
+        }
+
+        * + .block-entry {
+            margin-top: 32px;
+        }
+
+        h1 {
+            margin: 0;
+            padding: 0;
+        }
+    `,
+    renderCallback: ({ inputs }) => {
+        const currentSearch = extractSearchQuery(inputs.currentRoute.paths);
+        const entryTemplates = createNodeTemplates({
+            currentNodes: inputs.currentNodes,
+            isTopLevel: true,
+            router: inputs.router,
+            isSearching: !!currentSearch,
+            currentControls: inputs.currentControls,
+            originalTree: inputs.originalTree,
+        });
+        return html `
+            <${BookBreadcrumbsBar}
+                ${assign(BookBreadcrumbsBar, {
+            currentSearch,
+            currentRoute: inputs.currentRoute,
+            router: inputs.router,
+        })}
+            ></${BookBreadcrumbsBar}>
+            <div class="all-book-entries-wrapper">${entryTemplates}</div>
+            <slot name=${ElementBookSlotName.Footer}></slot>
+        `;
+    },
+});
+function getFlattenedControlsFromHiddenParents(currentNodes, currentControls, currentNode, originalTree) {
+    const parent = traverseToImmediateParent(currentNode, originalTree);
+    const allControls = [];
+    if (parent) {
+        const parentControls = getFlattenedControlsFromHiddenParents(currentNodes, currentControls, parent, originalTree);
+        if (parentControls) {
+            allControls.push(parentControls);
+        }
+    }
+    if (isBookTreeNode(currentNode, BookEntryTypeEnum.Page) &&
+        !currentNodes.includes(currentNode)) {
+        const currentEntryControls = traverseCurrentControls(currentControls, currentNode.fullUrlBreadcrumbs);
+        allControls.push({
+            config: currentNode.entry.controls,
+            current: currentEntryControls,
+            breadcrumbs: mapObjectValues(currentEntryControls, () => {
+                return currentNode.fullUrlBreadcrumbs;
+            }),
+        });
+    }
+    return allControls.reduce((accum, currentControls) => {
+        return {
+            config: {
+                ...accum.config,
+                ...currentControls.config,
+            },
+            current: {
+                ...accum.current,
+                ...currentControls.current,
+            },
+            breadcrumbs: {
+                ...accum.breadcrumbs,
+                ...currentControls.breadcrumbs,
+            },
+        };
+    }, { config: {}, current: {}, breadcrumbs: {} });
+}
+function createNodeTemplates({ currentNodes, isTopLevel, router, isSearching, currentControls, originalTree, }) {
+    if (!currentNodes.length && isSearching) {
+        return [
+            html `
+                No results
+            `,
+        ];
+    }
+    const hiddenAncestorControls = isLengthAtLeast(currentNodes, 1)
+        ? getFlattenedControlsFromHiddenParents(currentNodes, currentControls, currentNodes[0], originalTree)
+        : undefined;
+    const hiddenAncestorControlsTemplate = hiddenAncestorControls && isLengthAtLeast(currentNodes, 1)
+        ? html `
+                  <${BookPageControls}
+                      ${assign(BookPageControls, {
+            config: hiddenAncestorControls.config,
+            currentValues: hiddenAncestorControls.current,
+            fullUrlBreadcrumbs: hiddenAncestorControls.breadcrumbs,
+        })}
+                  ></${BookPageControls}>
+              `
+        : '';
+    const templates = repeat(currentNodes, (node) => node.fullUrlBreadcrumbs.join('>'), (currentNode, index) => {
+        if (isBookTreeNode(currentNode, BookEntryTypeEnum.Page)) {
+            return html `
+                    <${BookPageWrapper}
+                        class="block-entry"
+                        ${assign(BookPageWrapper, {
+                isTopLevel,
+                pageNode: currentNode,
+                currentControls,
+                router,
+            })}
+                    ></${BookPageWrapper}>
+                `;
+        }
+        else if (isBookTreeNode(currentNode, BookEntryTypeEnum.ElementExample)) {
+            const controlsForElementExample = traverseCurrentControls(currentControls, currentNode.fullUrlBreadcrumbs.slice(0, -1));
+            return html `
+                    <${BookElementExampleWrapper}
+                        class="inline-entry"
+                        ${assign(BookElementExampleWrapper, {
+                elementExampleNode: currentNode,
+                currentPageControls: controlsForElementExample,
+                router,
+            })}
+                    ></${BookElementExampleWrapper}>
+                `;
+        }
+        else if (isBookTreeNode(currentNode, BookEntryTypeEnum.Root)) {
+            return html `
+                    <h1>${currentNode.entry.title}</h1>
+                `;
+        }
+        else {
+            return html `
+                    <${BookError}
+                        class="block-entry"
+                        ${assign(BookError, {
+                message: `Unknown entry type for rendering: '${currentNode.entry.entryType}'`,
+            })}
+                    ></${BookError}>
+                `;
+        }
+    });
+    return [
+        hiddenAncestorControlsTemplate,
+        templates,
+    ];
+}

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

@@ -0,0 +1,17 @@
+import { BookPage } from '../../../../data/book-entry/book-page/book-page';
+import { BookPageControl, BookPageControlsValues } from '../../../../data/book-entry/book-page/book-page-controls';
+export declare const BookPageControls: import("element-vir").DeclarativeElementDefinition<"book-page-controls", {
+    config: BookPage['controls'];
+    /**
+     * If an object (or Record) is given for this input, then each key of the object must correspond
+     * to one of the controls from the input config and the value for each key will be the
+     * breadcrumbs for that specific config.
+     */
+    fullUrlBreadcrumbs: ReadonlyArray<string> | Record<string, ReadonlyArray<string>>;
+    currentValues: Record<string, BookPageControl['initValue']>;
+}, {}, {
+    controlValueChange: import("element-vir").DefinedTypedEventNameDefinition<{
+        fullUrlBreadcrumbs: ReadonlyArray<string>;
+        newValues: BookPageControlsValues;
+    }>;
+}, "book-page-controls-has-controls", `book-page-controls-${string}`, "" | ("" | import("lit-html").HTMLTemplateResult)[]>;