element-book 26.12.0 → 26.12.1

package/src/data/book-tree/book-tree.ts

@@ -1,225 +0,0 @@
-import {check} from '@augment-vir/assert';
-import {BookEntryType} from '../book-entry/book-entry-type.js';
-import {type BookEntry, isBookEntry} from '../book-entry/book-entry.js';
-import {listUrlBreadcrumbs, titleToUrlBreadcrumb} from '../book-entry/url-breadcrumbs.js';
-import {bookEntryVerifiers} from '../book-entry/verify-book-entry.js';
-import {type BookTree, type BookTreeNode, isBookTreeNodeMarker} from './book-tree-node.js';
-import {addTreeToCache, getTreeFromCache} from './tree-cache.js';
-
-export function doesNodeHaveEntryType<const EntryType extends BookEntryType>(
-    node: unknown,
-    entryType: EntryType,
-): node is BookTreeNode<EntryType> {
-    return (
-        check.hasKey(node, 'entry') &&
-        check.isObject(node.entry) &&
-        node.entry.entryType === entryType
-    );
-}
-
-export function isBookTreeNode<const SpecificType extends BookEntryType>(
-    input: unknown,
-    entryType: SpecificType,
-): input is BookTreeNode<SpecificType> {
-    return isAnyBookTreeNode(input) && input.entry.entryType === entryType;
-}
-
-export function isAnyBookTreeNode(input: unknown): input is BookTreeNode<BookEntryType> {
-    return !!(
-        check.hasKeys(input, [
-            isBookTreeNodeMarker,
-            'entry',
-        ]) && input[isBookTreeNodeMarker]
-    );
-}
-
-export function createEmptyBookTreeRoot(): BookTreeNode<BookEntryType.Root> {
-    const rootNode: Readonly<BookTreeNode<BookEntryType.Root>> = {
-        [isBookTreeNodeMarker]: true,
-        entry: {
-            entryType: BookEntryType.Root,
-            title: '',
-            parent: undefined,
-            errors: [],
-            descriptionParagraphs: [],
-        },
-        urlBreadcrumb: '',
-        fullUrlBreadcrumbs: [],
-        children: {} as Record<string, BookTreeNode>,
-        manuallyAdded: true,
-    };
-
-    return rootNode;
-}
-
-export function createBookTreeFromEntries({
-    entries,
-    debug,
-}: {
-    entries: ReadonlyArray<BookEntry>;
-    debug: boolean;
-}): BookTree {
-    const cachedTree = getTreeFromCache(entries);
-    if (cachedTree) {
-        return cachedTree;
-    }
-
-    const tree = createEmptyBookTreeRoot();
-
-    entries.forEach((newEntry) => addEntryToTree({tree, newEntry, debug, manuallyAdded: true}));
-
-    const flattenedNodes = flattenTree(tree);
-
-    const bookTree: BookTree = {
-        tree,
-        flattenedNodes,
-    };
-
-    addTreeToCache(entries, bookTree);
-
-    if (debug) {
-        console.info('element-book tree:', tree);
-    }
-
-    return bookTree;
-}
-
-function getOrAddImmediateParent(
-    tree: BookTreeNode<BookEntryType.Root>,
-    entry: BookEntry,
-    debug: boolean,
-): BookTreeNode {
-    if (!entry.parent) {
-        return tree;
-    }
-
-    const immediateParent = traverseToImmediateParent(entry, tree);
-
-    if (immediateParent) {
-        return immediateParent;
-    }
-
-    if (debug) {
-        console.info(`parent of ${entry.title} not found in tree; adding it now.`);
-    }
-
-    addEntryToTree({tree, newEntry: entry.parent, debug, manuallyAdded: false});
-    const immediateParentAfterAdding = traverseToImmediateParent(entry, tree);
-
-    if (!immediateParentAfterAdding) {
-        throw new Error(
-            `Failed to find node despite having just added it: ${listUrlBreadcrumbs(entry, false).join(' > ')}`,
-        );
-    }
-
-    return immediateParentAfterAdding;
-}
-
-function addEntryToTree({
-    tree,
-    newEntry,
-    debug,
-    manuallyAdded,
-}: {
-    tree: BookTreeNode<BookEntryType.Root>;
-    newEntry: BookEntry;
-    debug: boolean;
-    manuallyAdded: boolean;
-}) {
-    const errors = bookEntryVerifiers[newEntry.entryType](newEntry);
-
-    newEntry.errors.push(...errors);
-
-    const immediateParent = getOrAddImmediateParent(tree, newEntry, debug);
-
-    const newEntryUrlBreadcrumb = titleToUrlBreadcrumb(newEntry.title);
-
-    const existingChild = immediateParent.children[newEntryUrlBreadcrumb];
-
-    if (existingChild) {
-        // ignores multiple entries that have been added by following parent chains
-        if (manuallyAdded) {
-            if (existingChild.manuallyAdded) {
-                existingChild.entry.errors.push(
-                    new Error(
-                        `Cannot create duplicate '${newEntryUrlBreadcrumb}'${
-                            immediateParent.urlBreadcrumb
-                                ? ` in parent '${immediateParent.urlBreadcrumb}'.`
-                                : ''
-                        }`,
-                    ),
-                );
-
-                return;
-            }
-
-            existingChild.manuallyAdded = true;
-        }
-
-        return;
-    }
-
-    const newNode: BookTreeNode = {
-        [isBookTreeNodeMarker]: true,
-        children: {},
-        urlBreadcrumb: newEntryUrlBreadcrumb,
-        fullUrlBreadcrumbs: [
-            ...immediateParent.fullUrlBreadcrumbs,
-            newEntryUrlBreadcrumb,
-        ],
-        entry: newEntry,
-        manuallyAdded,
-    };
-
-    immediateParent.children[newEntryUrlBreadcrumb] = newNode;
-
-    if (
-        isBookEntry(newEntry, BookEntryType.Page) &&
-        Object.values(newEntry.elementExamples).length
-    ) {
-        Object.values(newEntry.elementExamples).forEach((elementExample) =>
-            addEntryToTree({tree, newEntry: elementExample, debug, manuallyAdded}),
-        );
-    }
-}
-
-export function traverseToImmediateParent(
-    entryOrNode: Readonly<BookEntry> | BookTreeNode,
-    currentTree: Readonly<BookTreeNode>,
-): BookTreeNode | undefined {
-    const breadcrumbs: string[] = isAnyBookTreeNode(entryOrNode)
-        ? entryOrNode.fullUrlBreadcrumbs.slice(0, -1)
-        : listUrlBreadcrumbs(entryOrNode, false);
-
-    if (!breadcrumbs.length) {
-        return undefined;
-    }
-
-    const immediateParentNode: BookTreeNode | undefined = breadcrumbs.reduce(
-        (currentAncestor, nextBreadcrumb) => {
-            if (!currentAncestor) {
-                return undefined;
-            }
-
-            return currentAncestor.children[nextBreadcrumb];
-        },
-        currentTree as typeof currentTree | undefined,
-    );
-
-    return immediateParentNode;
-}
-
-export function flattenTree(node: Readonly<BookTreeNode>): BookTreeNode[] {
-    const hasErrors: boolean = !!node.entry.errors.length;
-
-    const childNodes = hasErrors
-        ? []
-        : Object.values(node.children).map((child) => flattenTree(child));
-
-    const entries: BookTreeNode[] = [
-        node,
-        ...childNodes,
-    ].flat();
-
-    return entries;
-}

package/src/data/book-tree/search-nodes.ts

@@ -1,104 +0,0 @@
-import {check} from '@augment-vir/assert';
-import {randomString} from '@augment-vir/common';
-import {convertTemplateToString} from 'element-vir';
-import {fuzzySearch} from '../../util/fuzzy-search.js';
-import {type BookTreeNode} from './book-tree-node.js';
-
-const searchJoin = randomString(32);
-
-function createBreadcrumbsSearchKey(breadcrumbs: ReadonlyArray<string>): string {
-    return breadcrumbs.join(searchJoin);
-}
-
-type SearchInclusions = Record<string, boolean>;
-
-function getFullTreeKeysToInclude(breadcrumbs: ReadonlyArray<string>): string[] {
-    if (!breadcrumbs.length) {
-        return [];
-    }
-
-    const currentKey = createBreadcrumbsSearchKey(breadcrumbs);
-
-    const ancestorKeys = getFullTreeKeysToInclude(breadcrumbs.slice(0, -1));
-
-    return [
-        currentKey,
-        ...ancestorKeys,
-    ];
-}
-
-const errorQueries = [
-    'error',
-    'errors',
-];
-function isSearchingForErrors(searchQuery: string): boolean {
-    return errorQueries.includes(searchQuery);
-}
-
-export function searchFlattenedNodes({
-    flattenedNodes,
-    searchQuery,
-}: {
-    flattenedNodes: ReadonlyArray<BookTreeNode>;
-    searchQuery: string;
-}): ReadonlyArray<BookTreeNode> {
-    const includeInSearchResults: SearchInclusions = {};
-
-    function addChildren(treeNode: BookTreeNode) {
-        const childrenKeys = Object.values(treeNode.children).map((child) => {
-            addChildren(child);
-            return createBreadcrumbsSearchKey(child.fullUrlBreadcrumbs);
-        });
-
-        childrenKeys.forEach((keyToInclude) => (includeInSearchResults[keyToInclude] = true));
-    }
-
-    flattenedNodes.forEach((treeNode) => {
-        const matchesErrors = treeNode.entry.errors.length && isSearchingForErrors(searchQuery);
-        const currentNodeSearchKey = createBreadcrumbsSearchKey(treeNode.fullUrlBreadcrumbs);
-        const shouldInclude =
-            fuzzySearch({
-                searchIn: [
-                    treeNode.entry.title,
-                    ...treeNode.entry.descriptionParagraphs.map((paragraph) => {
-                        if (check.isString(paragraph)) {
-                            return paragraph;
-                        } else {
-                            return convertTemplateToString(paragraph);
-                        }
-                    }),
-                ]
-                    .join(' ')
-                    .toLowerCase(),
-                searchQuery: searchQuery.toLowerCase(),
-            }) ||
-            matchesErrors ||
-            includeInSearchResults[currentNodeSearchKey];
-
-        if (shouldInclude) {
-            const keysToInclude = getFullTreeKeysToInclude(treeNode.fullUrlBreadcrumbs);
-
-            addChildren(treeNode);
-
-            keysToInclude.forEach((keyToInclude) => (includeInSearchResults[keyToInclude] = true));
-        } else {
-            includeInSearchResults[currentNodeSearchKey] = false;
-        }
-    });
-
-    return flattenedNodes.filter((treeNode): boolean => {
-        const inSearchResultsKey = createBreadcrumbsSearchKey(treeNode.fullUrlBreadcrumbs);
-
-        const shouldInclude = includeInSearchResults[inSearchResultsKey];
-
-        if (!check.isBoolean(shouldInclude)) {
-            throw new TypeError(
-                `Failed to find '${treeNode.fullUrlBreadcrumbs.join(
-                    ' > ',
-                )}' in includeInSearchResults.`,
-            );
-        }
-
-        return shouldInclude;
-    });
-}

package/src/data/book-tree/tree-cache.ts

@@ -1,13 +0,0 @@
-import {getOrSetFromMap} from '@augment-vir/common';
-import {type BookEntry} from '../book-entry/book-entry.js';
-import {type BookTree} from './book-tree-node.js';
-
-const treeCache = new Map<ReadonlyArray<BookEntry>, BookTree>();
-
-export function getTreeFromCache(entries: ReadonlyArray<BookEntry>): BookTree | undefined {
-    return treeCache.get(entries);
-}
-
-export function addTreeToCache(entries: ReadonlyArray<BookEntry>, tree: BookTree): void {
-    getOrSetFromMap(treeCache, entries, () => tree);
-}

package/src/ui/color-theme/color-theme.ts

@@ -1,152 +0,0 @@
-import {check} from '@augment-vir/assert';
-import {type CSSResult} from 'element-vir';
-import {type SingleCssVarDefinition, defineCssVars, setCssVarValue} from 'lit-css-vars';
-import {type NestedType} from '../../util/type.js';
-
-/**
- * A single background and foreground color pairing.
- *
- * @category Internal
- */
-export type ColorPair = {background: CSSResult; foreground: CSSResult};
-
-/**
- * Color pairs for everything used by the element-book app.
- *
- * @category Internal
- */
-export type ColorTheme = {
-    nav: {
-        hover: ColorPair;
-        active: ColorPair;
-        selected: ColorPair;
-    };
-    accent: {
-        icon: CSSResult;
-    };
-    page: ColorPair & {
-        backgroundFaint1: CSSResult;
-        backgroundFaint2: CSSResult;
-        foregroundFaint1: CSSResult;
-        foregroundFaint2: CSSResult;
-    };
-};
-
-type CssResultToCssVar<StartingPoint> = {
-    [PropName in keyof StartingPoint]: StartingPoint[PropName] extends CSSResult
-        ? SingleCssVarDefinition
-        : CssResultToCssVar<StartingPoint[PropName]>;
-};
-
-type ColorThemeCssVars = CssResultToCssVar<ColorTheme>;
-
-/**
- * All color theme CSS vars for the element-book app.
- *
- * @category Internal
- */
-export const colorThemeCssVars = defineCssVars({
-    'element-book-nav-hover-background-color': 'magenta',
-    'element-book-nav-hover-foreground-color': 'magenta',
-    'element-book-nav-active-background-color': 'magenta',
-    'element-book-nav-active-foreground-color': 'magenta',
-    'element-book-nav-selected-background-color': 'magenta',
-    'element-book-nav-selected-foreground-color': 'magenta',
-    'element-book-accent-icon-color': 'magenta',
-    'element-book-page-background-color': 'magenta',
-    'element-book-page-background-faint-level-1-color': 'magenta',
-    'element-book-page-background-faint-level-2-color': 'magenta',
-    'element-book-page-foreground-color': 'magenta',
-    'element-book-page-foreground-faint-level-1-color': 'magenta',
-    'element-book-page-foreground-faint-level-2-color': 'magenta',
-});
-
-const colorThemeCssVarMapping: ColorThemeCssVars = {
-    nav: {
-        hover: {
-            background: colorThemeCssVars['element-book-nav-hover-background-color'],
-            foreground: colorThemeCssVars['element-book-nav-hover-foreground-color'],
-        },
-        active: {
-            background: colorThemeCssVars['element-book-nav-active-background-color'],
-            foreground: colorThemeCssVars['element-book-nav-active-foreground-color'],
-        },
-        selected: {
-            background: colorThemeCssVars['element-book-nav-selected-background-color'],
-            foreground: colorThemeCssVars['element-book-nav-selected-foreground-color'],
-        },
-    },
-    accent: {
-        icon: colorThemeCssVars['element-book-accent-icon-color'],
-    },
-    page: {
-        background: colorThemeCssVars['element-book-page-background-color'],
-        backgroundFaint1: colorThemeCssVars['element-book-page-background-faint-level-1-color'],
-        backgroundFaint2: colorThemeCssVars['element-book-page-background-faint-level-2-color'],
-        foreground: colorThemeCssVars['element-book-page-foreground-color'],
-        foregroundFaint1: colorThemeCssVars['element-book-page-foreground-faint-level-1-color'],
-        foregroundFaint2: colorThemeCssVars['element-book-page-foreground-faint-level-2-color'],
-    },
-};
-
-/**
- * Sets a new color theme's CSS vars on the given HTML element for the element-book app.
- *
- * @category Internal
- */
-export function setThemeCssVars(element: HTMLElement, theme: ColorTheme) {
-    recursiveSetThemeCssVars(element, theme, colorThemeCssVarMapping);
-}
-
-function isCssResult(input: unknown): input is CSSResult {
-    return check.hasKey(input, '_$cssResult$');
-}
-
-function isCssVarDefinition(input: unknown): input is SingleCssVarDefinition {
-    return (
-        check.hasKeys(input, [
-            'name',
-            'value',
-            'default',
-        ]) &&
-        check.isString(input.default) &&
-        isCssResult(input.name) &&
-        isCssResult(input.value)
-    );
-}
-
-function recursiveSetThemeCssVars(
-    element: HTMLElement,
-    nestedCssResult: NestedType<CSSResult>,
-    nestedCssVars: NestedType<SingleCssVarDefinition>,
-) {
-    Object.entries(nestedCssResult).forEach(
-        ([
-            key,
-            value,
-        ]) => {
-            const nestedCssVar = nestedCssVars[key];
-
-            if (!nestedCssVar) {
-                throw new Error(`no nestedCssVar at key '${key}'`);
-            }
-
-            if (isCssResult(value)) {
-                if (!isCssVarDefinition(nestedCssVar)) {
-                    throw new Error(`got a CSS result at '${key}' but no CSS var`);
-                }
-
-                setCssVarValue({
-                    forCssVar: nestedCssVar,
-                    onElement: element,
-                    toValue: String(value),
-                });
-            } else {
-                if (isCssVarDefinition(nestedCssVar)) {
-                    throw new Error(`got no CSS result at '${key}' but did find a CSS var`);
-                }
-                recursiveSetThemeCssVars(element, value, nestedCssVar);
-            }
-        },
-    );
-}

package/src/ui/color-theme/create-color-theme.ts

@@ -1,139 +0,0 @@
-import {type PartialWithUndefined, mapObjectValues} from '@augment-vir/common';
-import Color from 'colorjs.io';
-import {type CSSResult, unsafeCSS} from 'element-vir';
-import {type RequireExactlyOne} from 'type-fest';
-import {type NestedType} from '../../util/type.js';
-import {type ColorTheme} from './color-theme.js';
-
-// as cast because colorjs.io's types for itself are wrong
-type FixedColor = Color & {
-    set: (input: Record<string, number>) => Color;
-};
-
-type NestedColors = NestedType<Color>;
-
-type NestedColorsToCssResult<Colors extends Readonly<NestedColors>> = {
-    [PropName in keyof Colors]: Colors[PropName] extends Color
-        ? CSSResult
-        : NestedColorsToCssResult<Exclude<Colors[PropName], Color>>;
-};
-
-function colorsObjectToCssResult<const Colors extends NestedColors>(
-    colors: Colors,
-): NestedColorsToCssResult<Colors> {
-    return mapObjectValues(colors, (key, value) => {
-        if (value instanceof Color) {
-            return unsafeCSS(value.toString({format: 'hex'}));
-        } else {
-            return colorsObjectToCssResult(value);
-        }
-    }) as NestedColorsToCssResult<Colors>;
-}
-
-/**
- * The default theme color.
- *
- * @category Internal
- */
-export const defaultThemeStartColor = 'dodgerblue';
-
-type BackForeGroundColor = 'black' | 'white';
-
-function calculateTextColorString(color: Color): BackForeGroundColor {
-    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,
-}: RequireExactlyOne<{background: Color; foreground: Color}>) {
-    return {
-        background: background ?? new Color(calculateTextColorString(foreground)),
-        foreground: foreground ?? new Color(calculateTextColorString(background)),
-    };
-}
-
-/**
- * Theme style options for the element-book app.
- *
- * @category Internal
- */
-export enum ThemeStyle {
-    Dark = 'dark',
-    Light = 'light',
-}
-
-/**
- * Theme configuration options for the element-book app.
- *
- * @category Internal
- */
-export type ThemeConfig = PartialWithUndefined<{
-    themeColor: string;
-    themeStyle: ThemeStyle;
-}>;
-
-function flipBackForeground(input: BackForeGroundColor): BackForeGroundColor {
-    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'),
-    },
-} as const;
-
-const faintBackgroundColors = {
-    black: {
-        backgroundFaint1: new Color('#666'),
-        backgroundFaint2: new Color('#444'),
-    },
-    white: {
-        backgroundFaint1: new Color('#ccc'),
-        backgroundFaint2: new Color('#fafafa'),
-    },
-} as const;
-
-/**
- * Creates a theme from the given theme configuration.
- *
- * @category Internal
- */
-export function createTheme({
-    themeColor: inputThemeColor = defaultThemeStartColor,
-    themeStyle = ThemeStyle.Light,
-}: ThemeConfig = {}): ColorTheme {
-    const themeColor = new Color(inputThemeColor) as FixedColor;
-    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],
-        },
-    } as const;
-
-    const convertedToCssResults = colorsObjectToCssResult(colors);
-
-    return convertedToCssResults;
-}

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

@@ -1,60 +0,0 @@
-import {css, html} from 'element-vir';
-import {type BookRouter} from '../../routing/book-router.js';
-import {type BookFullRoute, 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<{
-    currentRoute: Readonly<BookFullRoute>;
-    router: Readonly<BookRouter> | undefined;
-}>()({
-    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`
-                &nbsp;
-            `;
-        }
-
-        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}
-            `;
-        });
-    },
-});