element-book 6.0.2 → 7.0.0

package/README.md

@@ -1,8 +1,8 @@
 # element-book
 
-An [`element-vir`](https://npmjs.com/element-vir) drop-in element for building, testing, and demonstrating a collection of elements (or a design system).
+An [`element-vir`](https://npmjs.com/element-vir) drop-in element for building, testing, and demonstrating a collection of elements (or, in other words, a design system).
 
-Currently in MVP form. Functional, but WIP.
+Currently in MVP form. Functional, but WIP and frequently changing.
 
 [Example here.](https://electrovir.github.io/element-book/)
 
@@ -14,8 +14,8 @@ npm i element-book
 
 # Terminology
 
--   **Chapter**: a group of sub-chapters or element examples. Chapters can be infinitely nested.
--   **Example**: an individual element example with independent state, styles, and title.
+-   **Page**: a group of pages and / or element examples. Pages can be infinitely nested.
+-   **Element Example**: an individual element example with independent state, styles, title, etc.
 
 # Usage
 
@@ -23,4 +23,4 @@ _todo_
 
 # Why not Storybook?
 
-Because Storybook is un-composable, impossible to debug, and full of behind-the-scenes \*magic\* that you can't backtrack without deeply understand the inner workings of Storybook. With `element-book`, it's all just imports that you can directly follow with the TypeScript compiler.
+Because Storybook is un-composable, impossible to debug, and full of behind-the-scenes \*magic\* that you can't backtrack without already understanding the inner workings of Storybook itself. With `element-book`, it's all just imports that you can directly follow with the TypeScript compiler.

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

@@ -0,0 +1,20 @@
+import { BookEntryTypeEnum } from './book-entry-type';
+export type BaseBookEntry = {
+    /**
+     * Title for the entry. This is used to create breadcrumbs and URL paths. Each title must be
+     * unique within a given entry's parent.
+     */
+    title: string;
+    entryType: BookEntryTypeEnum;
+    /**
+     * The parent page. A value of undefined here indicates that the entry should be at the top
+     * level of the element book.
+     */
+    parent: unknown;
+    /**
+     * A description that will be displayed below the entry title. Each item in the array will be a
+     * separate paragraph.
+     */
+    descriptionParagraphs: string[];
+    errors: Error[];
+};

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

@@ -0,0 +1,32 @@
+import { Overwrite, RequireNonVoid } from '@augment-vir/common';
+import { PropertyInitMapBase, RenderParams, TypedEvent } from 'element-vir';
+import { CSSResult } from 'lit';
+import { SetOptional } from 'type-fest';
+import { BaseBookEntry } from '../base-book-entry';
+import { BookEntryTypeEnum } from '../book-entry-type';
+import { BookPage } from '../book-page/book-page';
+import { BookPageControlsInitBase, ControlsToValues } from '../book-page/book-page-controls';
+export type BookPageExampleRenderParams<ControlsInit extends BookPageControlsInitBase, StateInit extends PropertyInitMapBase> = Pick<RenderParams<any, any, StateInit, any, any, any>, 'state' | 'updateState'> & {
+    controls: ControlsToValues<ControlsInit>;
+};
+export type BookElementExample<ControlsInit extends BookPageControlsInitBase = {}, StateInit extends PropertyInitMapBase = {}, RenderOutput = unknown> = Overwrite<BaseBookEntry, {
+    parent: BookPage | undefined;
+    entryType: BookEntryTypeEnum.ElementExample;
+} & {
+    /** Initialize the state for this example. */
+    stateInitStatic?: StateInit;
+    /** Specify which events this example should intercept (so the user can see them). */
+    showEvents?: ReadonlyArray<string | TypedEvent>;
+    /**
+     * Style the element example. You can even use the :host selector to style this specific
+     * example's wrapper element!
+     */
+    styles?: CSSResult;
+    /** Render the example. */
+    renderCallback: RequireNonVoid<RenderOutput, (renderParams: BookPageExampleRenderParams<ControlsInit, StateInit>) => RenderOutput, 'renderCallback is missing a return statement'>;
+}>;
+/**
+ * The properties that are necessary to initialize an element example. Missing properties will be
+ * filling in by the parent.
+ */
+export type BookElementExampleInit<Controls extends BookPageControlsInitBase, StateInit extends PropertyInitMapBase, RenderOutput> = SetOptional<Omit<BookElementExample<Controls, StateInit, RenderOutput>, 'entryType' | 'parent' | 'errors'>, 'descriptionParagraphs'>;

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

@@ -0,0 +1,9 @@
+export declare enum BookEntryTypeEnum {
+    /** A single element example. */
+    ElementExample = "element-example",
+    /** An individual book page with element examples and/or sub-pages. */
+    Page = "page",
+    /** Tree root. Not for external use. */
+    Root = "root"
+}
+export type AnyBookEntryType = BookEntryTypeEnum.ElementExample | BookEntryTypeEnum.Page | BookEntryTypeEnum.Root;

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

@@ -0,0 +1,9 @@
+export var BookEntryTypeEnum;
+(function (BookEntryTypeEnum) {
+    /** A single element example. */
+    BookEntryTypeEnum["ElementExample"] = "element-example";
+    /** An individual book page with element examples and/or sub-pages. */
+    BookEntryTypeEnum["Page"] = "page";
+    /** Tree root. Not for external use. */
+    BookEntryTypeEnum["Root"] = "root";
+})(BookEntryTypeEnum || (BookEntryTypeEnum = {}));

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

@@ -0,0 +1,8 @@
+import { BookElementExample } from './book-element-example/book-element-example';
+import { BookEntryTypeEnum } from './book-entry-type';
+import { BookPage } from './book-page/book-page';
+import { BookRoot } from './book-root';
+export type BookEntry = BookPage | BookRoot | BookElementExample;
+export declare function isBookEntry<SpecificType extends BookEntryTypeEnum>(entry: unknown, entryType: SpecificType): entry is Extract<BookEntry, {
+    entryType: SpecificType;
+}>;

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

@@ -0,0 +1,4 @@
+import { typedHasProperty } from '@augment-vir/common';
+export function isBookEntry(entry, entryType) {
+    return typedHasProperty(entry, 'entryType') && entry.entryType === entryType;
+}

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

@@ -0,0 +1,41 @@
+export type BookPageControl<ControlType extends BookPageControlTypeEnum = BookPageControlTypeEnum> = {
+    controlType: ControlType;
+    initValue: BookPageControlValueType[ControlType];
+    /** The name and label for the control. */
+    controlName: string;
+} & (ControlType extends BookPageControlTypeEnum.Dropdown ? {
+    options: string[];
+} : {});
+export type BookPageControlInit<ControlType extends BookPageControlTypeEnum> = Omit<BookPageControl<ControlType>, 'controlName'>;
+export declare function isControlInitType<SpecificControlType extends BookPageControlTypeEnum>(controlInit: BookPageControlInit<any>, specificType: SpecificControlType): controlInit is BookPageControlInit<SpecificControlType>;
+/**
+ * Define a page control. This doesn't do anything fancy (in fact it only returns the input) but it
+ * helps immensely with type inference.
+ */
+export declare function definePageControl<ControlType extends BookPageControlTypeEnum>(controlInit: BookPageControlInit<ControlType>): BookPageControlInit<ControlType>;
+export type ControlsToValues<ControlsInit extends BookPageControlsInitBase> = {
+    [ControlName in keyof ControlsInit]: ControlsInit[ControlName]['initValue'];
+};
+export type BookPageControlsInitBase = Record<string, BookPageControlInit<BookPageControlTypeEnum>>;
+export type BookPageControlsValues = ControlsToValues<BookPageControlsInitBase>;
+export declare enum BookPageControlTypeEnum {
+    Checkbox = "checkbox",
+    Color = "color",
+    Dropdown = "dropdown",
+    /** Hidden controls allow any values but they aren't displayed to the user for editing. */
+    Hidden = "hidden",
+    Number = "number",
+    Text = "text"
+}
+declare const controlValueTypes: {
+    checkbox: boolean;
+    color: string;
+    /** The number type here indicates which index in the options are selected. */
+    dropdown: number;
+    hidden: any;
+    number: number;
+    text: string;
+};
+export type BookPageControlValueType = typeof controlValueTypes;
+export declare function checkControls(controlsInit: BookPageControlsInitBase | undefined, pageName: string): Error[];
+export {};

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

@@ -0,0 +1,49 @@
+export function isControlInitType(controlInit, specificType) {
+    return controlInit.controlType === specificType;
+}
+/**
+ * Define a page control. This doesn't do anything fancy (in fact it only returns the input) but it
+ * helps immensely with type inference.
+ */
+export function definePageControl(controlInit) {
+    return controlInit;
+}
+export var BookPageControlTypeEnum;
+(function (BookPageControlTypeEnum) {
+    BookPageControlTypeEnum["Checkbox"] = "checkbox";
+    BookPageControlTypeEnum["Color"] = "color";
+    BookPageControlTypeEnum["Dropdown"] = "dropdown";
+    /** Hidden controls allow any values but they aren't displayed to the user for editing. */
+    BookPageControlTypeEnum["Hidden"] = "hidden";
+    BookPageControlTypeEnum["Number"] = "number";
+    BookPageControlTypeEnum["Text"] = "text";
+})(BookPageControlTypeEnum || (BookPageControlTypeEnum = {}));
+const anySymbol = Symbol('any-type');
+const controlValueTypes = {
+    [BookPageControlTypeEnum.Checkbox]: false,
+    [BookPageControlTypeEnum.Color]: '',
+    /** The number type here indicates which index in the options are selected. */
+    [BookPageControlTypeEnum.Dropdown]: 0,
+    [BookPageControlTypeEnum.Hidden]: anySymbol,
+    [BookPageControlTypeEnum.Number]: 0,
+    [BookPageControlTypeEnum.Text]: '',
+};
+export function checkControls(controlsInit, pageName) {
+    if (!controlsInit) {
+        return [];
+    }
+    const errors = [];
+    Object.entries(controlsInit).forEach(([controlName, controlEntry,]) => {
+        const expectedInitDefault = controlValueTypes[controlEntry.controlType];
+        if (expectedInitDefault === anySymbol) {
+            return;
+        }
+        if (typeof expectedInitDefault !== typeof controlEntry.initValue) {
+            errors.push(new Error(`Control '${controlName}' in page '${pageName}' has invalid initValue '${controlEntry.initValue}': expected initValue of type ${typeof expectedInitDefault} because the control is of type ${controlEntry.controlType}.`));
+        }
+        if (!controlName) {
+            errors.push(new Error(`'${pageName}' cannot have an empty control name.`));
+        }
+    });
+    return errors;
+}

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

@@ -0,0 +1,12 @@
+import { Overwrite } from '@augment-vir/common';
+import { BaseBookEntry } from '../base-book-entry';
+import { BookElementExample } from '../book-element-example/book-element-example';
+import { BookEntryTypeEnum } from '../book-entry-type';
+import { BookPageControlsInitBase } from './book-page-controls';
+export type BookPage<ParentPage extends BookPage | undefined = any, ControlsInit extends BookPageControlsInitBase = BookPageControlsInitBase> = Overwrite<BaseBookEntry, {
+    parent: ParentPage;
+    entryType: BookEntryTypeEnum.Page;
+}> & {
+    controls: ControlsInit;
+    elementExamples: Record<string, BookElementExample>;
+};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,12 @@
+import { BookTreeNode } from '../../book-tree/book-tree-node';
+import { BookPageControlsValues } from './book-page-controls';
+export type ControlsWrapper = {
+    children: CurrentControls;
+    controls: BookPageControlsValues;
+};
+export type CurrentControls = {
+    [Breadcrumb: string]: ControlsWrapper;
+};
+export declare function traverseCurrentControls(currentControls: CurrentControls, fullUrlBreadcrumbs: ReadonlyArray<string>): BookPageControlsValues;
+export declare function createNewCurrentControls(currentControls: CurrentControls, fullUrlBreadcrumbs: ReadonlyArray<string>, newValues: BookPageControlsValues): CurrentControls;
+export declare function createControlsFromTree(node: BookTreeNode): CurrentControls;

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

@@ -0,0 +1,62 @@
+import { copyThroughJson, mapObjectValues } from '@augment-vir/common';
+import { isBookTreeNode } from '../../book-tree/book-tree';
+import { BookEntryTypeEnum } from '../book-entry-type';
+function getOrCreateControlsWrapper(currentControls, currentBreadcrumb, newValues) {
+    const controlsWrapper = currentControls[currentBreadcrumb];
+    if (controlsWrapper) {
+        return controlsWrapper;
+    }
+    if (newValues) {
+        const newControls = {
+            children: {},
+            controls: {},
+        };
+        currentControls[currentBreadcrumb] = newControls;
+        return newControls;
+    }
+    return undefined;
+}
+export function traverseCurrentControls(currentControls, fullUrlBreadcrumbs) {
+    return internalTraverseCurrentControls(currentControls, fullUrlBreadcrumbs, undefined);
+}
+function internalTraverseCurrentControls(currentControls, fullUrlBreadcrumbs, newValues) {
+    const currentBreadcrumb = fullUrlBreadcrumbs[0];
+    if (!currentBreadcrumb) {
+        return {};
+    }
+    const controlsWrapper = getOrCreateControlsWrapper(currentControls, currentBreadcrumb, newValues);
+    if (!controlsWrapper) {
+        return {};
+    }
+    const nextBreadcrumbs = fullUrlBreadcrumbs.slice(1);
+    if (!nextBreadcrumbs.length && newValues) {
+        controlsWrapper.controls = newValues;
+    }
+    const controlsValues = controlsWrapper.controls;
+    return {
+        ...controlsValues,
+        ...internalTraverseCurrentControls(controlsWrapper.children, nextBreadcrumbs, newValues),
+    };
+}
+export function createNewCurrentControls(currentControls, fullUrlBreadcrumbs, newValues) {
+    const newCurrentControls = copyThroughJson(currentControls);
+    internalTraverseCurrentControls(newCurrentControls, fullUrlBreadcrumbs, newValues);
+    return newCurrentControls;
+}
+export function createControlsFromTree(node) {
+    const currentControls = mapObjectValues(node.children, (childName, child) => {
+        if (!isBookTreeNode(child, BookEntryTypeEnum.Page)) {
+            return {
+                children: {},
+                controls: {},
+            };
+        }
+        return {
+            children: createControlsFromTree(child),
+            controls: mapObjectValues(child.entry.controls, (name, setup) => {
+                return setup.initValue;
+            }),
+        };
+    });
+    return currentControls;
+}

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

@@ -0,0 +1,17 @@
+import { PropertyInitMapBase } from 'element-vir';
+import { SetOptional } from 'type-fest';
+import { InfiniteRecursionLimiter } from '../../../util/type';
+import { BookElementExampleInit } from '../book-element-example/book-element-example';
+import { BookPage } from './book-page';
+import { BookPageControlsInitBase } from './book-page-controls';
+export type ElementExamplesDefiner<ControlsInit extends BookPageControlsInitBase = BookPageControlsInitBase> = (params: {
+    defineExample: <StateInit extends PropertyInitMapBase, RenderOutput>(exampleInit: BookElementExampleInit<ControlsInit, StateInit, RenderOutput>) => void;
+}) => void;
+type CollapseControlsInit<ParentPage extends BookPage | undefined, CurrentControlsInit extends BookPageControlsInitBase, 
+/** Prevent infinite recursion TypeScript errors. */
+RecursionDepth = InfiniteRecursionLimiter> = CurrentControlsInit & (RecursionDepth extends [any, ...infer RemainingDepth] ? ParentPage extends BookPage<infer GrandParentPage, infer ParentControls> ? CollapseControlsInit<GrandParentPage, ParentControls, RemainingDepth> : {} : {});
+export type BookPageInit<ParentPage extends BookPage | undefined, CurrentControlsInit extends BookPageControlsInitBase> = SetOptional<Omit<BookPage<ParentPage, CurrentControlsInit>, 'entryType' | 'elementExamples' | 'errors'>, 'controls' | 'descriptionParagraphs'> & {
+    elementExamplesCallback?: ElementExamplesDefiner<CollapseControlsInit<ParentPage, CurrentControlsInit>> | undefined;
+};
+export declare function defineBookPage<const ParentPage extends BookPage | undefined, const ControlsInit extends BookPageControlsInitBase = {}>(pageInit: BookPageInit<ParentPage, ControlsInit>): BookPage<ParentPage, ControlsInit>;
+export {};

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

@@ -0,0 +1,34 @@
+import { isTruthy } from '@augment-vir/common';
+import { BookEntryTypeEnum } from '../book-entry-type';
+import { titleToUrlBreadcrumb } from '../url-breadcrumbs';
+export function defineBookPage(pageInit) {
+    const page = {
+        ...pageInit,
+        entryType: BookEntryTypeEnum.Page,
+        elementExamples: {},
+        descriptionParagraphs: pageInit.descriptionParagraphs ?? [],
+        controls: pageInit.controls ?? {},
+        errors: [],
+    };
+    const alreadyTakenElementExampleNames = new Set();
+    if (pageInit.elementExamplesCallback) {
+        pageInit.elementExamplesCallback({
+            defineExample(elementExampleInit) {
+                const newExample = {
+                    ...elementExampleInit,
+                    entryType: BookEntryTypeEnum.ElementExample,
+                    parent: page,
+                    descriptionParagraphs: elementExampleInit.descriptionParagraphs ?? [],
+                    errors: [
+                        alreadyTakenElementExampleNames.has(elementExampleInit.title) &&
+                            new Error(`Example title '${elementExampleInit.title}' in page '${pageInit.title}' is already taken.`),
+                    ].filter(isTruthy),
+                };
+                alreadyTakenElementExampleNames.add(elementExampleInit.title);
+                page.elementExamples[titleToUrlBreadcrumb(newExample.title)] =
+                    newExample;
+            },
+        });
+    }
+    return page;
+}

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

@@ -0,0 +1,7 @@
+import { Overwrite } from '@augment-vir/common';
+import { BaseBookEntry } from './base-book-entry';
+import { BookEntryTypeEnum } from './book-entry-type';
+export type BookRoot = Overwrite<BaseBookEntry, {
+    entryType: BookEntryTypeEnum.Root;
+    parent: undefined;
+}>;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,7 @@
+import { BookEntry } from './book-entry';
+export declare function listUrlBreadcrumbs(entry: BookEntry, includeSelf: boolean): string[];
+export declare function titleToUrlBreadcrumb(title: string): string;
+export declare function doBreadcrumbsStartWith({ searchFor, searchIn, }: {
+    searchIn: ReadonlyArray<string>;
+    searchFor: ReadonlyArray<string>;
+}): boolean;

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

@@ -0,0 +1,24 @@
+import { collapseWhiteSpace } from '@augment-vir/common';
+export function listUrlBreadcrumbs(entry, includeSelf) {
+    const entryBreadcrumb = titleToUrlBreadcrumb(entry.title);
+    if (entry.parent) {
+        return [
+            ...listUrlBreadcrumbs(entry.parent, false),
+            titleToUrlBreadcrumb(entry.parent.title),
+        ].concat(includeSelf ? [entryBreadcrumb] : []);
+    }
+    else if (includeSelf) {
+        return [entryBreadcrumb];
+    }
+    else {
+        return [];
+    }
+}
+export function titleToUrlBreadcrumb(title) {
+    return collapseWhiteSpace(title).toLowerCase().replaceAll(/\s/g, '-');
+}
+export function doBreadcrumbsStartWith({ searchFor, searchIn, }) {
+    return searchFor.every((breadcrumb, index) => {
+        return searchIn[index] === breadcrumb;
+    });
+}

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

@@ -0,0 +1,6 @@
+import { BookEntry } from './book-entry';
+export declare const bookEntryVerifiers: {
+    "element-example": (entry: BookEntry) => Error[];
+    page: (entry: BookEntry) => Error[];
+    root: (entry: BookEntry) => Error[];
+};

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

@@ -0,0 +1,18 @@
+import { isTruthy } from '@augment-vir/common';
+import { BookEntryTypeEnum } from './book-entry-type';
+import { checkControls } from './book-page/book-page-controls';
+export const bookEntryVerifiers = {
+    [BookEntryTypeEnum.ElementExample]: () => {
+        // currently all element example checking happens on page definition
+        return [];
+    },
+    [BookEntryTypeEnum.Page]: (bookPage) => {
+        return [
+            !bookPage.title && new Error(`Cannot define an element-book page with an empty title.`),
+            ...checkControls(bookPage.controls, bookPage.title),
+        ].filter(isTruthy);
+    },
+    [BookEntryTypeEnum.Root]: () => {
+        return [];
+    },
+};

package/dist/data/book-tree/book-tree-node.d.ts

@@ -0,0 +1,27 @@
+import { PropertyValueType } from '@augment-vir/common';
+import { BookEntry } from '../book-entry/book-entry';
+import { AnyBookEntryType, BookEntryTypeEnum } from '../book-entry/book-entry-type';
+export declare const isBookTreeNodeMarker = "_isBookTreeNode";
+type InternalBookTreeNodeType<Entry> = {
+    [isBookTreeNodeMarker]: true;
+    entry: Entry;
+    /** UrlBreadcrumb is different from entry.title because it's modified to support URLs. */
+    urlBreadcrumb: string;
+    fullUrlBreadcrumbs: ReadonlyArray<string>;
+    children: Record<string, BookTreeNode>;
+    /**
+     * False when an entry has been added by traversing manually added parents. True when the entry
+     * was added as an explicit entry.
+     */
+    manuallyAdded: boolean;
+};
+export type BookTreeNode<EntryTypes extends BookEntryTypeEnum = AnyBookEntryType> = PropertyValueType<{
+    [EntryType in EntryTypes]: InternalBookTreeNodeType<Extract<BookEntry, {
+        entryType: EntryType;
+    }>>;
+}> | (AnyBookEntryType extends EntryTypes ? InternalBookTreeNodeType<BookEntry> : never);
+export type BookTree = Readonly<{
+    tree: Readonly<BookTreeNode<BookEntryTypeEnum.Root>>;
+    flattenedNodes: ReadonlyArray<Readonly<BookTreeNode>>;
+}>;
+export {};

package/dist/data/book-tree/book-tree-node.js

@@ -0,0 +1 @@
+export const isBookTreeNodeMarker = '_isBookTreeNode';

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

@@ -0,0 +1,16 @@
+import { BookEntry } from '../book-entry/book-entry';
+import { BookEntryTypeEnum } from '../book-entry/book-entry-type';
+import { BookTree, BookTreeNode } from './book-tree-node';
+export declare function doesNodeHaveEntryType<EntryType extends BookEntryTypeEnum>(node: BookTreeNode<any>, entryType: EntryType): node is BookTreeNode<EntryType>;
+export declare function isBookTreeNode<SpecificType extends BookEntryTypeEnum>(input: unknown, entryType: SpecificType): input is BookTreeNode<SpecificType>;
+export declare function isAnyBookTreeNode(input: unknown): input is BookTreeNode<BookEntryTypeEnum>;
+export declare function createEmptyBookTreeRoot(title: string | undefined, descriptionParagraphs: ReadonlyArray<string>): BookTreeNode<BookEntryTypeEnum.Root>;
+export declare function createBookTreeFromEntries({ entries, everythingTitle, everythingDescriptionParagraphs, debug, }: {
+    entries: ReadonlyArray<BookEntry>;
+    everythingTitle: string | undefined;
+    everythingDescriptionParagraphs: ReadonlyArray<string>;
+    debug: boolean;
+}): BookTree;
+export declare function traverseToImmediateParent(entryOrNode: Readonly<BookEntry> | BookTreeNode, currentTree: Readonly<BookTreeNode>): BookTreeNode | undefined;
+export declare function getSortedNodeChildren(nodeA: Readonly<BookTreeNode>, nodeB: Readonly<BookTreeNode>): number;
+export declare function flattenTree(node: Readonly<BookTreeNode>): BookTreeNode[];

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

@@ -0,0 +1,148 @@
+import { makeWritable, typedHasProperties } from '@augment-vir/common';
+import { isBookEntry } from '../book-entry/book-entry';
+import { BookEntryTypeEnum } from '../book-entry/book-entry-type';
+import { listUrlBreadcrumbs, titleToUrlBreadcrumb } from '../book-entry/url-breadcrumbs';
+import { bookEntryVerifiers } from '../book-entry/verify-book-entry';
+import { isBookTreeNodeMarker } from './book-tree-node';
+import { addTreeToCache, getTreeFromCache } from './tree-cache';
+export function doesNodeHaveEntryType(node, entryType) {
+    return node.entry.entryType === entryType;
+}
+export function isBookTreeNode(input, entryType) {
+    return !!(isAnyBookTreeNode(input) && input.entry.entryType === entryType);
+}
+export function isAnyBookTreeNode(input) {
+    return !!(typedHasProperties(input, [
+        isBookTreeNodeMarker,
+        'entry',
+    ]) && input[isBookTreeNodeMarker]);
+}
+export function createEmptyBookTreeRoot(title, descriptionParagraphs) {
+    const rootNode = {
+        [isBookTreeNodeMarker]: true,
+        entry: {
+            entryType: BookEntryTypeEnum.Root,
+            title: title || 'Everything',
+            parent: undefined,
+            errors: [],
+            descriptionParagraphs: makeWritable(descriptionParagraphs),
+        },
+        urlBreadcrumb: '',
+        fullUrlBreadcrumbs: [],
+        children: {},
+        manuallyAdded: true,
+    };
+    return rootNode;
+}
+export function createBookTreeFromEntries({ entries, everythingTitle, everythingDescriptionParagraphs, debug, }) {
+    const cachedTree = getTreeFromCache(entries);
+    if (cachedTree) {
+        return cachedTree;
+    }
+    const tree = createEmptyBookTreeRoot(everythingTitle, everythingDescriptionParagraphs);
+    entries.forEach((newEntry) => addEntryToTree({ tree, newEntry, debug, manuallyAdded: true }));
+    const flattenedNodes = flattenTree(tree);
+    const bookTree = {
+        tree,
+        flattenedNodes,
+    };
+    addTreeToCache(entries, bookTree);
+    if (debug) {
+        console.info('element-book tree:', tree);
+    }
+    return bookTree;
+}
+function getOrAddImmediateParent(tree, entry, debug) {
+    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)}`);
+    }
+    return immediateParentAfterAdding;
+}
+function addEntryToTree({ tree, newEntry, debug, manuallyAdded, }) {
+    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 = {
+        [isBookTreeNodeMarker]: true,
+        children: {},
+        urlBreadcrumb: newEntryUrlBreadcrumb,
+        fullUrlBreadcrumbs: [
+            ...immediateParent.fullUrlBreadcrumbs,
+            newEntryUrlBreadcrumb,
+        ],
+        entry: newEntry,
+        manuallyAdded,
+    };
+    immediateParent.children[newEntryUrlBreadcrumb] = newNode;
+    bookEntryVerifiers;
+    if (isBookEntry(newEntry, BookEntryTypeEnum.Page) &&
+        Object.values(newEntry.elementExamples ?? {}).length) {
+        Object.values(newEntry.elementExamples ?? {}).forEach((elementExample) => addEntryToTree({ tree, newEntry: elementExample, debug, manuallyAdded }));
+    }
+}
+export function traverseToImmediateParent(entryOrNode, currentTree) {
+    const breadcrumbs = isAnyBookTreeNode(entryOrNode)
+        ? entryOrNode.fullUrlBreadcrumbs.slice(0, -1)
+        : listUrlBreadcrumbs(entryOrNode, false);
+    if (!breadcrumbs.length) {
+        return undefined;
+    }
+    const immediateParentNode = breadcrumbs.reduce((currentAncestor, nextBreadcrumb) => {
+        if (!currentAncestor) {
+            return undefined;
+        }
+        return currentAncestor.children[nextBreadcrumb];
+    }, currentTree);
+    return immediateParentNode;
+}
+export function getSortedNodeChildren(nodeA, nodeB) {
+    if (nodeA.entry.entryType !== nodeB.entry.entryType) {
+        if (isBookEntry(nodeA.entry, BookEntryTypeEnum.ElementExample)) {
+            return -1;
+        }
+        if (isBookEntry(nodeB.entry, BookEntryTypeEnum.ElementExample)) {
+            return 1;
+        }
+    }
+    return nodeA.entry.title.localeCompare(nodeB.entry.title);
+}
+export function flattenTree(node) {
+    const hasErrors = !!node.entry.errors.length;
+    const childNodes = hasErrors
+        ? []
+        : Object.values(node.children)
+            .sort(getSortedNodeChildren)
+            .map((child) => flattenTree(child));
+    const entries = [
+        node,
+        ...childNodes,
+    ].flat();
+    return entries;
+}

package/dist/data/book-tree/search-nodes.d.ts

@@ -0,0 +1,5 @@
+import { BookTreeNode } from './book-tree-node';
+export declare function searchFlattenedNodes({ flattenedNodes, searchQuery, }: {
+    flattenedNodes: ReadonlyArray<BookTreeNode>;
+    searchQuery: string;
+}): ReadonlyArray<BookTreeNode>;