element-book 0.0.13 → 1.0.0

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

@@ -1,7 +1,12 @@
 import { ElementBookEntryTypeEnum } from '../element-book-entry-type';
 export function defineElementBookChapter(chapterSetup) {
     if (!chapterSetup.title) {
-        throw new Error(`Cannot have an element-book chapter with an empty title.`);
+        /**
+         * We don't want the Error type to actually be a part of this function's return type, cause
+         * users shouldn't actually return errors, but we still want to pass errors to element-book
+         * so element-book can handle them.
+         */
+        return new Error(`Cannot have an element-book chapter with an empty title.`);
     }
     const chapter = {
         type: ElementBookEntryTypeEnum.Chapter,

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

@@ -1,8 +1,10 @@
+import { combineErrors } from '@augment-vir/common';
 import { ElementBookEntryTypeEnum } from '../element-book-entry-type';
 import { listBreadcrumbs } from '../entry-tree/entry-tree';
 export function defineElementBookPage(pageSetup) {
+    const errors = [];
     if (!pageSetup.title) {
-        throw new Error(`Cannot have an element-book page with an empty title.`);
+        errors.push(new Error(`Cannot have an element-book page with an empty title.`));
     }
     const page = {
         type: ElementBookEntryTypeEnum.Page,
@@ -15,12 +17,20 @@ export function defineElementBookPage(pageSetup) {
             .concat(example.title)
             .join(' > ')}'`;
         if (exampleTitlesSet.has(example.title)) {
-            throw new Error(`${failureMessage}: example title '${example.title}' is already being used.`);
+            errors.push(Error(`${failureMessage}: title '${example.title}' is already being used.`));
         }
         else if (!example.title) {
-            throw new Error(`${failureMessage}: example title is missing or empty.`);
+            errors.push(Error(`${failureMessage}: example title is missing or empty.`));
         }
         exampleTitlesSet.add(example.title);
     });
+    if (errors.length) {
+        /**
+         * We don't want the Error type to actually be a part of this function's return type, cause
+         * users shouldn't actually return errors, but we still want to pass errors to element-book
+         * so element-book can handle them.
+         */
+        return combineErrors(errors);
+    }
     return page;
 }

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

@@ -31,10 +31,17 @@ export function titleToBreadcrumb(title) {
 export function entriesToTree(entries, everythingTitle) {
     const tree = createEmptyEntryTreeRoot(everythingTitle);
     entries.forEach((newEntry) => {
+        /**
+         * The type for newEntry does not include Error but if errors occur during entry definition
+         * they will be replaced with errors.
+         */
+        if (newEntry instanceof Error) {
+            throw newEntry;
+        }
         const immediateParent = traverseToImmediateParent(newEntry, tree);
         const breadcrumb = titleToBreadcrumb(newEntry.title);
         if (breadcrumb in immediateParent.children) {
-            throw new Error(`Cannot create duplicate entry '${breadcrumb}' in parent '${immediateParent.breadcrumb}'.`);
+            throw new Error(`Cannot create duplicate entry '${breadcrumb}'${immediateParent.breadcrumb ? ` in parent '${immediateParent.breadcrumb}'.` : ''}`);
         }
         const newNode = {
             [markerKeyName]: true,

package/dist/routing/create-element-book-router.d.ts

@@ -1,2 +1,2 @@
 import { ElementBookRouter } from './element-book-routing';
-export declare function createElementBookRouter(baseRoute: string): ElementBookRouter;
+export declare function createElementBookRouter(baseRoute: string | undefined): ElementBookRouter;

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

@@ -9,5 +9,7 @@ export declare const ElementBookApp: import("element-vir").DeclarativeElementDef
     currentRoute: Readonly<Required<Readonly<import("spa-router-vir").FullRoute<import("../../../routing/element-book-routing").ValidElementBookPaths, undefined, undefined>>>>;
     router: Readonly<import("spa-router-vir").SpaRouter<import("../../../routing/element-book-routing").ValidElementBookPaths, undefined, undefined>> | undefined;
     colors: ColorThemeState;
-}, {}, "", "", import("lit-html").HTMLTemplateResult>;
+}, {
+    pathUpdate: import("element-vir").DefinedTypedEventNameDefinition<readonly string[]>;
+}, "", "", import("lit-html").HTMLTemplateResult>;
 export {};

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

@@ -1,6 +1,6 @@
 import { areJsonEqual, extractErrorMessage, getOrSetFromMap } from '@augment-vir/common';
-import { assign, css, defineElement, html, listen } from 'element-vir';
-import { entriesToTree, findEntryByBreadcrumbs, listBreadcrumbs, } from '../../../data/element-book-entry/entry-tree/entry-tree';
+import { assign, css, defineElement, defineElementEvent, html, listen } from 'element-vir';
+import { entriesToTree, findEntryByBreadcrumbs, } from '../../../data/element-book-entry/entry-tree/entry-tree';
 import { createElementBookRouter } from '../../../routing/create-element-book-router';
 import { ElementBookMainRoute, defaultElementBookFullRoute, } from '../../../routing/element-book-routing';
 import { colorThemeCssVars, setThemeCssVars } from '../../color-theme/color-theme';
@@ -11,6 +11,9 @@ import { ElementBookEntryDisplay } from '../entry-display/element-book-entry-dis
 const treeCache = new Map();
 export const ElementBookApp = defineElement()({
     tagName: 'element-book-app',
+    events: {
+        pathUpdate: defineElementEvent(),
+    },
     stateInit: {
         currentRoute: defaultElementBookFullRoute,
         router: undefined,
@@ -56,32 +59,8 @@ export const ElementBookApp = defineElement()({
             top: 0;
         }
     `,
-    initCallback({ updateState, state, inputs, host }) {
-        if (inputs.baseUrl && !state.router) {
-            const router = createElementBookRouter(inputs.baseUrl);
-            updateState({ router });
-            router.addRouteListener(true, (fullRoute) => {
-                updateState({
-                    currentRoute: fullRoute,
-                });
-            });
-        }
-    },
-    renderCallback: ({ state, inputs, host, updateState }) => {
+    renderCallback: ({ state, inputs, host, updateState, dispatch, events }) => {
         try {
-            const inputThemeConfig = {
-                themeColor: inputs.themeColor,
-            };
-            if (!areJsonEqual(inputThemeConfig, state.colors?.config)) {
-                const newTheme = createTheme(inputThemeConfig);
-                updateState({
-                    colors: {
-                        config: inputThemeConfig,
-                        theme: newTheme,
-                    },
-                });
-                setThemeCssVars(host, newTheme);
-            }
             function updateRoutes(newRoute) {
                 if (state.router) {
                     state.router.setRoutes(newRoute);
@@ -94,29 +73,45 @@ export const ElementBookApp = defineElement()({
                         },
                     });
                 }
+                dispatch(new events.pathUpdate(newRoute.paths ?? []));
+            }
+            if (inputs.internalRouterConfig?.useInternalRouter && !state.router) {
+                const router = createElementBookRouter(inputs.internalRouterConfig.basePath);
+                updateState({ router });
+                router.addRouteListener(true, (fullRoute) => {
+                    updateState({
+                        currentRoute: fullRoute,
+                    });
+                });
+            }
+            else if (!inputs.internalRouterConfig?.useInternalRouter && state.router) {
+                state.router.removeAllRouteListeners();
+            }
+            const inputThemeConfig = {
+                themeColor: inputs.themeColor,
+            };
+            if (!areJsonEqual(inputThemeConfig, state.colors?.config)) {
+                const newTheme = createTheme(inputThemeConfig);
+                updateState({
+                    colors: {
+                        config: inputThemeConfig,
+                        theme: newTheme,
+                    },
+                });
+                setThemeCssVars(host, newTheme);
             }
             const entriesTree = getOrSetFromMap(treeCache, inputs.entries, () => entriesToTree(inputs.entries, inputs.everythingTitle));
-            const initialNode = findEntryByBreadcrumbs(state.currentRoute.paths.slice(1), entriesTree);
-            if (!initialNode) {
-                const firstChild = Object.values(entriesTree.children)[0];
-                if (!firstChild) {
-                    throw new Error(`No entries exist.`);
-                }
-                const firstEntryBreadcrumbs = listBreadcrumbs(firstChild.entry, true);
-                const defaultPath = inputs.defaultPath ??
-                    (firstEntryBreadcrumbs.length ? firstEntryBreadcrumbs : undefined);
-                if (defaultPath && defaultPath.length) {
-                    const newRoute = {
-                        paths: [
-                            ElementBookMainRoute.Book,
-                            ...defaultPath,
-                        ],
-                    };
-                    updateRoutes(newRoute);
-                }
+            const entryTreeNodeByInitialPath = findEntryByBreadcrumbs(state.currentRoute.paths.slice(1), entriesTree);
+            if (!entryTreeNodeByInitialPath) {
+                const newRoute = {
+                    paths: [
+                        ElementBookMainRoute.Book,
+                    ],
+                };
+                updateRoutes(newRoute);
             }
-            const currentNode = findEntryByBreadcrumbs(state.currentRoute.paths.slice(1), entriesTree);
-            if (!currentNode) {
+            const currentEntryTreeNode = findEntryByBreadcrumbs(state.currentRoute.paths.slice(1), entriesTree);
+            if (!currentEntryTreeNode) {
                 throw new Error(`Tried to self-correct for invalid path ${state.currentRoute.paths.join('/')}
                         but failed to do so.`);
             }
@@ -146,7 +141,7 @@ export const ElementBookApp = defineElement()({
                     <${ElementBookEntryDisplay}
                         ${assign(ElementBookEntryDisplay, {
                 currentRoute: state.currentRoute,
-                currentNode,
+                currentNode: currentEntryTreeNode,
                 router: state.router,
             })}
                     ></${ElementBookEntryDisplay}>
@@ -154,6 +149,7 @@ export const ElementBookApp = defineElement()({
             `;
         }
         catch (error) {
+            console.error(error);
             return html `
                 <p class="error">${extractErrorMessage(error)}</p>
             `;

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

@@ -1,20 +1,36 @@
 import { PartialAndUndefined } from '@augment-vir/common';
+import { RequireExactlyOne } from 'type-fest';
 import { ElementBookEntry } from '../../../data/element-book-entry/element-book-entry';
 export type ElementBookConfig = {
     /** All element-book entries in order. */
     entries: ReadonlyArray<ElementBookEntry>;
 } & PartialAndUndefined<OptionalConfig>;
 type OptionalConfig = {
-    /**
-     * 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`.
-     */
-    baseUrl: string;
-    /** Starting /book/ path. */
-    defaultPath: ReadonlyArray<string>;
-    /** Color from which to base all element-book colors from. */
+    /** 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;
-};
+} & RequireExactlyOne<{
+    /**
+     * 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: {
+        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;
+    };
+    /**
+     * 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: ReadonlyArray<string>;
+}>;
 export {};

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

@@ -59,6 +59,7 @@ export const ElementBookNav = defineElementBookElement()({
             display: inline-flex;
             gap: 8px;
             align-items: center;
+            font-size: 0.75em;
         }
 
         ${VirIcon} {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-book",
-    "version": "0.0.13",
+    "version": "1.0.0",
     "keywords": [
         "book",
         "design system",
@@ -41,9 +41,9 @@
         "@augment-vir/common": "^13.4.0",
         "@electrovir/icon-element": "^0.0.2",
         "colorjs.io": "^0.4.3",
-        "element-vir": "^12.4.4",
+        "element-vir": "^12.4.6",
         "lit-css-vars": "^2.0.2",
-        "spa-router-vir": "^2.0.3",
+        "spa-router-vir": "^2.1.0",
         "typed-event-target": "^1.2.0"
     },
     "devDependencies": {