element-book 26.12.0 → 26.12.1

package/src/ui/elements/book-nav/book-nav-filter.ts

@@ -1,30 +0,0 @@
-import {check} from '@augment-vir/assert';
-import {BookEntryType} from '../../../data/book-entry/book-entry-type.js';
-import {type BookTreeNode} from '../../../data/book-tree/book-tree-node.js';
-
-export function shouldShowTreeNodeInNav(
-    currentNode: Readonly<BookTreeNode>,
-    selectedPath: undefined | ReadonlyArray<string>,
-): boolean {
-    if (currentNode.entry.entryType === BookEntryType.Root) {
-        return false;
-    }
-
-    if (currentNode.entry.entryType === BookEntryType.Page) {
-        return true;
-    }
-
-    const isParentSelected = check.jsonEquals(
-        selectedPath as unknown,
-        currentNode.fullUrlBreadcrumbs.slice(0, -1),
-    );
-
-    if (isParentSelected) {
-        return true;
-    }
-
-    return check.jsonEquals(
-        selectedPath?.slice(0, -1),
-        currentNode.fullUrlBreadcrumbs.slice(0, -1),
-    );
-}

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

@@ -1,48 +0,0 @@
-import {css, html, listen} from 'element-vir';
-import {shouldClickEventTriggerRouteChange} from 'spa-router-vir';
-import {type BookRouter} from '../../../routing/book-router.js';
-import {type BookFullRoute} from '../../../routing/book-routing.js';
-import {ChangeRouteEvent} from '../../events/change-route.event.js';
-import {defineBookElement} from '../define-book-element.js';
-
-export const BookRouteLink = defineBookElement<{
-    route: Partial<BookFullRoute>;
-    router: Readonly<BookRouter> | undefined;
-}>()({
-    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: string =
-            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/src/ui/elements/define-book-element.ts

@@ -1,5 +0,0 @@
-import {wrapDefineElement} from 'element-vir';
-
-export type BookTagName = `book-${string}`;
-
-export const defineBookElement = wrapDefineElement<BookTagName>();

package/src/ui/elements/element-book-app/element-book-app.element.ts

@@ -1,380 +0,0 @@
-import {check} from '@augment-vir/assert';
-import {extractErrorMessage, makeWritable} from '@augment-vir/common';
-import {waitForAnimationFrame} from '@augment-vir/web';
-import {css, defineElement, defineElementEvent, html, listen} from 'element-vir';
-import {
-    type ControlsWrapper,
-    createNewControls,
-    updateTreeControls,
-} from '../../../data/book-entry/book-page/controls-wrapper.js';
-import {createBookTreeFromEntries} from '../../../data/book-tree/book-tree.js';
-import {searchFlattenedNodes} from '../../../data/book-tree/search-nodes.js';
-import {type BookRouter, createBookRouter} from '../../../routing/book-router.js';
-import {
-    type BookFullRoute,
-    defaultBookFullRoute,
-    extractSearchQuery,
-} from '../../../routing/book-routing.js';
-import {
-    type ColorTheme,
-    colorThemeCssVars,
-    setThemeCssVars,
-} from '../../color-theme/color-theme.js';
-import {type ThemeConfig, createTheme} from '../../color-theme/create-color-theme.js';
-import {ChangeRouteEvent} from '../../events/change-route.event.js';
-import {BookNav, scrollSelectedNavElementIntoView} from '../book-nav/book-nav.element.js';
-import {BookError} from '../common/book-error.element.js';
-import {BookPageControls} from '../entry-display/book-page/book-page-controls.element.js';
-import {BookEntryDisplay} from '../entry-display/entry-display/book-entry-display.element.js';
-import {ElementBookSlotName} from './element-book-app-slots.js';
-import {type ElementBookConfig} from './element-book-config.js';
-import {getCurrentNodes} from './get-current-nodes.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 const ElementBookApp = defineElement<ElementBookConfig>()({
-    tagName: 'element-book-app',
-    state() {
-        return {
-            currentRoute: defaultBookFullRoute,
-            router: undefined as undefined | BookRouter,
-            loading: true,
-            colors: {
-                config: undefined,
-                theme: createTheme(undefined),
-            } as ColorThemeState,
-            treeBasedControls: undefined as
-                | {
-                      pages: ElementBookConfig['pages'];
-                      lastGlobalInputs: GlobalValues;
-                      controls: ControlsWrapper;
-                  }
-                | undefined,
-            originalWindowTitle: undefined as string | undefined,
-        };
-    },
-    events: {
-        pathUpdate: defineElementEvent<ReadonlyArray<string>>(),
-    },
-    styles: css`
-        :host {
-            display: flex;
-            flex-direction: column;
-            height: 100%;
-            width: 100%;
-            font-family: sans-serif;
-            background-color: ${colorThemeCssVars['element-book-page-background-color'].value};
-            color: ${colorThemeCssVars['element-book-page-foreground-color'].value};
-        }
-
-        .error {
-            color: red;
-        }
-
-        .root {
-            flex-grow: 1;
-            width: 100%;
-            display: flex;
-            position: relative;
-        }
-
-        ${BookEntryDisplay} {
-            flex-grow: 1;
-            max-height: 100%;
-        }
-
-        ${BookNav} {
-            flex-shrink: 0;
-            overflow-x: hidden;
-            overflow-y: auto;
-            max-height: 100%;
-            top: 0;
-            max-width: min(400px, 40%);
-        }
-    `,
-    init({host, state}) {
-        setTimeout(async () => {
-            await scrollNav(host, extractSearchQuery(state.currentRoute.paths), state.currentRoute);
-        }, 500);
-    },
-    cleanup({state, updateState}) {
-        if (state.router) {
-            state.router.destroy();
-            updateState({router: undefined});
-        }
-    },
-    render: ({state, inputs, host, updateState, dispatch, events}) => {
-        if (inputs._debug) {
-            console.info('rendering element-book app');
-        }
-
-        function mergeRoutes(newRouteInput: Partial<BookFullRoute>) {
-            return {
-                ...state.currentRoute,
-                ...newRouteInput,
-            };
-        }
-
-        function areRoutesNew(newRouteInput: Partial<BookFullRoute>) {
-            const newRoute = mergeRoutes(newRouteInput);
-
-            return !check.jsonEquals(state.currentRoute, newRoute);
-        }
-
-        function updateWindowTitle(topNodeTitle: string | undefined) {
-            if (!inputs.preventWindowTitleChange) {
-                if (!state.originalWindowTitle) {
-                    updateState({originalWindowTitle: document.title});
-                }
-                document.title = [
-                    state.originalWindowTitle,
-                    topNodeTitle,
-                ]
-                    .filter(check.isTruthy)
-                    .join(' - ');
-            }
-        }
-
-        function updateRoutes(newRouteInput: Partial<BookFullRoute>) {
-            if (!areRoutesNew(newRouteInput)) {
-                return;
-            }
-            const newRoute = mergeRoutes(newRouteInput);
-
-            if (state.router) {
-                state.router.setRoute(newRoute);
-            } else {
-                updateState({
-                    currentRoute: {
-                        ...state.currentRoute,
-                        ...newRoute,
-                    },
-                });
-            }
-
-            if (
-                inputs.elementBookRoutePaths &&
-                !check.jsonEquals(inputs.elementBookRoutePaths, state.currentRoute.paths)
-            ) {
-                dispatch(new events.pathUpdate(newRoute.paths));
-            }
-        }
-
-        try {
-            if (
-                inputs.elementBookRoutePaths &&
-                !check.jsonEquals(inputs.elementBookRoutePaths, state.currentRoute.paths)
-            ) {
-                updateRoutes({paths: makeWritable(inputs.elementBookRoutePaths)});
-            }
-
-            if (inputs.internalRouterConfig?.useInternalRouter && !state.router) {
-                const router = createBookRouter(inputs.internalRouterConfig.basePath);
-                updateState({router});
-
-                router.listen(true, (fullRoute) => {
-                    updateState({
-                        currentRoute: fullRoute,
-                    });
-                });
-            } else if (!inputs.internalRouterConfig?.useInternalRouter && state.router) {
-                state.router.destroy();
-            }
-
-            const inputThemeConfig: ThemeConfig = {
-                themeColor: inputs.themeColor,
-            };
-            if (!check.jsonEquals<unknown, unknown>(inputThemeConfig, state.colors.config)) {
-                const newTheme = createTheme(inputThemeConfig);
-                updateState({
-                    colors: {
-                        config: inputThemeConfig,
-                        theme: newTheme,
-                    },
-                });
-                setThemeCssVars(host, newTheme);
-            }
-
-            const debug: boolean = inputs._debug ?? false;
-
-            const originalTree = createBookTreeFromEntries({
-                entries: inputs.pages,
-                debug,
-            });
-
-            if (
-                !state.treeBasedControls ||
-                state.treeBasedControls.pages !== inputs.pages ||
-                state.treeBasedControls.lastGlobalInputs !== inputs.globalValues
-            ) {
-                if (inputs._debug) {
-                    console.info('regenerating global controls');
-                }
-                updateState({
-                    treeBasedControls: {
-                        pages: inputs.pages,
-                        lastGlobalInputs: inputs.globalValues ?? {},
-                        controls: updateTreeControls(originalTree.tree, {
-                            children: state.treeBasedControls?.controls.children,
-                            controls: inputs.globalValues,
-                        }),
-                    },
-                });
-            }
-
-            const searchQuery = extractSearchQuery(state.currentRoute.paths);
-
-            const searchedNodes = searchQuery
-                ? searchFlattenedNodes({
-                      flattenedNodes: originalTree.flattenedNodes,
-                      searchQuery,
-                  })
-                : undefined;
-
-            const currentNodes =
-                searchedNodes ??
-                getCurrentNodes(
-                    originalTree.flattenedNodes,
-                    state.currentRoute.paths,
-                    updateRoutes,
-                );
-
-            updateWindowTitle(currentNodes[0]?.entry.title);
-
-            const currentControls = state.treeBasedControls?.controls;
-
-            if (!currentControls) {
-                return html`
-                    <${BookError.assign({
-                        message: 'Failed to generate page controls.',
-                    })}></${BookError}>
-                `;
-            }
-
-            if (inputs._debug) {
-                console.info({currentControls});
-            }
-
-            return html`
-                <div
-                    class="root"
-                    ${listen(ChangeRouteEvent, async (event) => {
-                        const newRoute = event.detail;
-
-                        if (!areRoutesNew(newRoute)) {
-                            return;
-                        }
-
-                        updateState({loading: true});
-
-                        updateRoutes(newRoute);
-
-                        const navElement = host.shadowRoot.querySelector(BookNav.tagName);
-
-                        if (!(navElement instanceof BookNav)) {
-                            throw new TypeError(`Failed to find child '${BookNav.tagName}'`);
-                        }
-                        await scrollNav(host, searchQuery, state.currentRoute);
-                    })}
-                    ${listen(BookPageControls.events.controlValueChange, (event) => {
-                        if (!state.treeBasedControls) {
-                            return;
-                        }
-                        const newControls = createNewControls(
-                            currentControls,
-                            event.detail.fullUrlBreadcrumbs,
-                            event.detail.newValues,
-                        );
-
-                        updateState({
-                            treeBasedControls: {
-                                ...state.treeBasedControls,
-                                controls: newControls,
-                            },
-                        });
-                    })}
-                >
-                    <${BookNav.assign({
-                        flattenedNodes: originalTree.flattenedNodes,
-                        router: state.router,
-                        selectedPath: searchQuery ? undefined : state.currentRoute.paths.slice(1),
-                    })}>
-                        <slot
-                            name=${ElementBookSlotName.NavHeader}
-                            slot=${ElementBookSlotName.NavHeader}
-                        ></slot>
-                    </${BookNav}>
-                    <${BookEntryDisplay.assign({
-                        controls: currentControls,
-                        currentNodes,
-                        currentRoute: state.currentRoute,
-                        debug,
-                        originalTree: originalTree.tree,
-                        router: state.router,
-                        showLoading: state.loading,
-                    })}
-                        ${listen(BookEntryDisplay.events.loadingRender, async (event) => {
-                            await waitForAnimationFrame();
-                            const entryDisplay = host.shadowRoot.querySelector(
-                                BookEntryDisplay.tagName,
-                            );
-
-                            if (entryDisplay) {
-                                entryDisplay.scroll({top: 0, behavior: 'instant'});
-                            } else {
-                                console.error(
-                                    `Failed to find '${BookEntryDisplay.tagName}' for scrolling.`,
-                                );
-                            }
-                            await waitForAnimationFrame();
-                            updateState({loading: !event.detail});
-                        })}
-                    >
-                        <slot
-                            name=${ElementBookSlotName.Footer}
-                            slot=${ElementBookSlotName.Footer}
-                        ></slot>
-                    </${BookEntryDisplay}>
-                </div>
-            `;
-        } catch (error) {
-            console.error(error);
-            return html`
-                <p class="error">${extractErrorMessage(error)}</p>
-            `;
-        }
-    },
-});
-
-async function scrollNav(
-    host: typeof ElementBookApp.InstanceType,
-    searchQuery: string,
-    currentRoutes: BookFullRoute,
-) {
-    /** If there is a search query, then there will be no selected nav to scroll to. */
-    if (searchQuery) {
-        return;
-    }
-    if (currentRoutes.paths.length <= 1) {
-        return;
-    }
-    const navElement = host.shadowRoot.querySelector(BookNav.tagName);
-
-    if (!(navElement instanceof BookNav)) {
-        throw new TypeError(`Failed to find child '${BookNav.tagName}'`);
-    }
-
-    await scrollSelectedNavElementIntoView(navElement);
-}

package/src/ui/elements/element-book-app/element-book-config.ts

@@ -1,52 +0,0 @@
-import {type PartialWithUndefined} from '@augment-vir/common';
-import {type RequireExactlyOne} from 'type-fest';
-import {type BookPage} from '../../../data/book-entry/book-page/book-page.js';
-import {type ValidBookPaths} from '../../../routing/book-routing.js';
-import {type GlobalValues} from './global-values.js';
-
-/**
- * Full configuration for an element-book app.
- *
- * @category Type
- */
-export type ElementBookConfig = {
-    /** All element-book pages in order. */
-    pages: ReadonlyArray<BookPage>;
-} & PartialWithUndefined<OptionalConfig>;
-
-/**
- * Options for {@link ElementBookConfig} that are optional.
- *
- * @category Internal
- */
-export type OptionalConfig = {
-    /** The base theme color from which all other element-book colors will be generated from. */
-    themeColor: string;
-    _debug: boolean;
-    globalValues: GlobalValues;
-    preventWindowTitleChange: boolean;
-} & RequireExactlyOne<
-    Readonly<{
-        /**
-         * Set this internal router config if element-book is intended to be the current website's
-         * entire web app. Meaning, you're not embedded element-book within another website.
-         *
-         * In this case, element-book will create its own internal router for managing the URL. In
-         * other cases, when element-book is embedded in another website, use the
-         * elementBookRoutePaths input property instead.
-         */
-        internalRouterConfig: Readonly<{
-            useInternalRouter: true;
-            /**
-             * Path to this page, used for routing. For example, if this page is hosted at
-             * www.example.org/my-page then this value should be `my-page`.
-             */
-            basePath?: string | undefined;
-        }>;
-        /**
-         * Current route paths for element-book to handle. These are intended to come from a router
-         * that's external to the element-book app itself.
-         */
-        elementBookRoutePaths: Readonly<ValidBookPaths>;
-    }>
->;

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

@@ -1,35 +0,0 @@
-import {doBreadcrumbsStartWith} from '../../../data/book-entry/url-breadcrumbs.js';
-import {type BookTreeNode} from '../../../data/book-tree/book-tree-node.js';
-import {
-    type BookFullRoute,
-    type ValidBookPaths,
-    defaultBookFullRoute,
-} from '../../../routing/book-routing.js';
-
-export function getCurrentNodes(
-    flattenedNodes: ReadonlyArray<Readonly<BookTreeNode>>,
-    currentPaths: Readonly<ValidBookPaths>,
-    updateRoutes: (newRoute: Partial<BookFullRoute>) => void,
-): BookTreeNode[] {
-    const filteredNodes = filterNodes(flattenedNodes, currentPaths);
-
-    if (filteredNodes.length) {
-        return filteredNodes;
-    } else {
-        updateRoutes(defaultBookFullRoute);
-    }
-
-    return filterNodes(flattenedNodes, defaultBookFullRoute.paths);
-}
-
-function filterNodes(
-    flattenedNodes: ReadonlyArray<Readonly<BookTreeNode>>,
-    paths: ReadonlyArray<string>,
-): BookTreeNode[] {
-    return flattenedNodes.filter((node) =>
-        doBreadcrumbsStartWith({
-            searchFor: paths.slice(1),
-            searchIn: node.fullUrlBreadcrumbs,
-        }),
-    );
-}

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

@@ -1,78 +0,0 @@
-import {wait} from '@augment-vir/common';
-import {css, html, listen, renderIf} from 'element-vir';
-import {type BookRouter} from '../../../routing/book-router.js';
-import {
-    type BookFullRoute,
-    BookMainRoute,
-    defaultBookFullRoute,
-} from '../../../routing/book-routing.js';
-import {colorThemeCssVars} from '../../color-theme/color-theme.js';
-import {ChangeRouteEvent} from '../../events/change-route.event.js';
-import {BookBreadcrumbs} from '../book-breadcrumbs.element.js';
-import {defineBookElement} from '../define-book-element.js';
-
-export const BookBreadcrumbsBar = defineBookElement<{
-    currentSearch: string;
-    currentRoute: Readonly<BookFullRoute>;
-    router: Readonly<BookRouter> | undefined;
-}>()({
-    tagName: 'book-breadcrumbs-bar',
-    styles: css`
-        :host {
-            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};
-            display: flex;
-            gap: 16px;
-            justify-content: space-between;
-        }
-    `,
-    render({inputs, dispatch}) {
-        return html`
-            ${renderIf(
-                !!inputs.currentSearch,
-                html`
-                    &nbsp;
-                `,
-                html`
-                    <${BookBreadcrumbs.assign({
-                        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 TypeError('Failed to find input element for search.');
-                    }
-                    const preThrottleValue = inputElement.value;
-                    // throttle it a bit
-                    await wait({milliseconds: 200});
-
-                    if (inputElement.value !== preThrottleValue) {
-                        return;
-                    }
-
-                    if (inputElement.value) {
-                        dispatch(
-                            new ChangeRouteEvent({
-                                paths: [
-                                    BookMainRoute.Search,
-                                    encodeURIComponent(inputElement.value),
-                                ],
-                            }),
-                        );
-                    } else {
-                        dispatch(new ChangeRouteEvent(defaultBookFullRoute));
-                    }
-                })}
-            />
-        `;
-    },
-});