element-book 3.0.2 → 4.0.0

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

@@ -10,3 +10,5 @@ export type ElementBookEntry = ElementBookChapter | ElementBookPage | ElementBoo
 export declare function isElementBookEntry<SpecificType extends ElementBookEntryTypeEnum>(entry: unknown, entryType: SpecificType): entry is Extract<ElementBookEntry, {
     entryType: SpecificType;
 }>;
+export declare function listBreadcrumbs(entry: ElementBookEntry, includeSelf?: boolean): string[];
+export declare function titleToBreadcrumb(title: string): string;

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

@@ -1,4 +1,22 @@
-import { typedHasProperty } from '@augment-vir/common';
+import { collapseWhiteSpace, typedHasProperty } from '@augment-vir/common';
 export function isElementBookEntry(entry, entryType) {
     return typedHasProperty(entry, 'entryType') && entry.entryType === entryType;
 }
+export function listBreadcrumbs(entry, includeSelf) {
+    const entryBreadcrumb = titleToBreadcrumb(entry.title);
+    if (entry.parent) {
+        return [
+            titleToBreadcrumb(entry.parent.title),
+            ...listBreadcrumbs(entry.parent, false),
+        ].concat(includeSelf ? [entryBreadcrumb] : []);
+    }
+    else if (includeSelf) {
+        return [entryBreadcrumb];
+    }
+    else {
+        return [];
+    }
+}
+export function titleToBreadcrumb(title) {
+    return collapseWhiteSpace(title).toLowerCase().replaceAll(/\s/g, '-');
+}

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

@@ -1,16 +1,13 @@
 import { RequireNonVoid } from '@augment-vir/common';
 import { PropertyInitMapBase, RenderParams, TypedEvent } from 'element-vir';
 import { CSSResult } from 'lit';
-import { ElementBookPage, PageControlsFromPage } from './element-book-page';
-import { PageControlsToValues } from './element-book-page-controls/element-book-page-control';
-export type ElementBookPageExampleRenderParams<ParentPage extends ElementBookPage<any>, StateInit extends PropertyInitMapBase> = Pick<RenderParams<any, any, StateInit, any, any, any>, 'state' | 'updateState'> & {
-    controls: PageControlsToValues<PageControlsFromPage<ParentPage>>;
+import { ElementBookPageControlMap, PageControlsToValues } from './element-book-page-controls/element-book-page-control';
+export type ElementBookPageExampleRenderParams<ParentControls extends ElementBookPageControlMap, StateInit extends PropertyInitMapBase> = Pick<RenderParams<any, any, StateInit, any, any, any>, 'state' | 'updateState'> & {
+    controls: PageControlsToValues<ParentControls>;
 };
-export type ElementBookPageExampleInit<ParentPage extends ElementBookPage<any>, StateInit extends PropertyInitMapBase, RenderOutput> = {
+export type ElementBookPageExampleInit<ParentControls extends ElementBookPageControlMap, StateInit extends PropertyInitMapBase, RenderOutput> = {
     /** This example's title. Each title in a page must be unique. */
     title: string;
-    /** The page that this example belongs to. */
-    parent: ParentPage;
     /** Initialize the state for this example. */
     stateInit?: StateInit;
     /** Specify which events this example should intercept (so the user can see them). */
@@ -21,7 +18,5 @@ export type ElementBookPageExampleInit<ParentPage extends ElementBookPage<any>,
      */
     styles?: CSSResult;
     /** Render the example. */
-    renderCallback: RequireNonVoid<RenderOutput, (renderParams: ElementBookPageExampleRenderParams<ParentPage, StateInit>) => RenderOutput, 'renderCallback is missing a return statement'>;
+    renderCallback: RequireNonVoid<RenderOutput, (renderParams: ElementBookPageExampleRenderParams<ParentControls, StateInit>) => RenderOutput, 'renderCallback is missing a return statement'>;
 };
-/** Inserts the defined element example into its parent page. */
-export declare function insertElementExample<ParentPage extends ElementBookPage<any>, StateInit extends PropertyInitMapBase = {}, RenderOutput = any>(exampleInit: ElementBookPageExampleInit<ParentPage, StateInit, RenderOutput>): void;

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

@@ -1,20 +1 @@
-import { combineErrors } from '@augment-vir/common';
-/** Inserts the defined element example into its parent page. */
-export function insertElementExample(exampleInit) {
-    const errors = [];
-    const failureMessage = `Failed to define example '${exampleInit.parent.pageBreadcrumbs
-        .concat(exampleInit.title)
-        .join(' > ')}'`;
-    if (exampleInit.parent.examples.hasOwnProperty(exampleInit.title)) {
-        errors.push(new Error(`${failureMessage}: title '${exampleInit.title}' is already being used.`));
-    }
-    else if (!exampleInit.title) {
-        errors.push(new Error(`${failureMessage}: example title is missing or empty.`));
-    }
-    if (errors.length) {
-        exampleInit.parent.examples[exampleInit.title] = combineErrors(errors);
-    }
-    else {
-        exampleInit.parent.examples[exampleInit.title] = exampleInit;
-    }
-}
+export {};

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

@@ -1,4 +1,5 @@
 import { Overwrite } from '@augment-vir/common';
+import { PropertyInitMapBase } from 'element-vir';
 import { SetOptional } from 'type-fest';
 import { BaseElementBookEntry } from '../element-book-chapter/element-book-chapter';
 import { ElementBookEntryTypeEnum } from '../element-book-entry-type';
@@ -12,5 +13,9 @@ export type ElementBookPage<Controls extends ElementBookPageControlMap = Element
     pageBreadcrumbs: ReadonlyArray<string>;
 };
 export type PageControlsFromPage<Page extends ElementBookPage<any>> = Page extends ElementBookPage<infer Controls> ? Controls : never;
-export type ElementBookPageInit<Controls extends ElementBookPageControlMap> = SetOptional<Omit<ElementBookPage<Controls>, 'entryType' | 'examples' | 'allExampleTitles' | 'pageBreadcrumbs'>, 'controls'>;
+export type ElementBookPageInit<Controls extends ElementBookPageControlMap> = Overwrite<SetOptional<Omit<ElementBookPage<Controls>, 'entryType' | 'allExampleTitles' | 'pageBreadcrumbs' | 'examples'>, 'controls'>, {
+    defineExamplesCallback?: (params: {
+        defineExample: <StateInit extends PropertyInitMapBase = {}, RenderOutput = any>(exampleInit: ElementBookPageExampleInit<Controls, StateInit, RenderOutput>) => void;
+    }) => void;
+}>;
 export declare function defineElementBookPage<Controls extends ElementBookPageControlMap = {}>(pageSetup: ElementBookPageInit<Controls>): ElementBookPage<Controls>;

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

@@ -1,14 +1,41 @@
+import { combineErrors } from '@augment-vir/common';
+import { listBreadcrumbs } from '../element-book-entry';
 import { ElementBookEntryTypeEnum } from '../element-book-entry-type';
+function insertElementExample(parentExamples, parentBreadcrumbs, exampleInit) {
+    const errors = [];
+    const failureMessage = `Failed to define example '${parentBreadcrumbs
+        .concat(exampleInit.title)
+        .join(' > ')}'`;
+    if (parentExamples.hasOwnProperty(exampleInit.title)) {
+        errors.push(new Error(`${failureMessage}: title '${exampleInit.title}' is already being used.`));
+    }
+    else if (!exampleInit.title) {
+        errors.push(new Error(`${failureMessage}: example title is missing or empty.`));
+    }
+    if (errors.length) {
+        parentExamples[exampleInit.title] = combineErrors(errors);
+    }
+    else {
+        parentExamples[exampleInit.title] = exampleInit;
+    }
+}
 export function defineElementBookPage(pageSetup) {
     if (!pageSetup.title) {
         throw new Error(`Cannot have an element-book page with an empty title.`);
     }
+    const allExamples = {};
     const page = {
         entryType: ElementBookEntryTypeEnum.Page,
         ...pageSetup,
-        examples: {},
+        examples: allExamples,
         controls: pageSetup.controls ?? {},
         pageBreadcrumbs: [],
     };
+    page.pageBreadcrumbs = listBreadcrumbs(page);
+    if (pageSetup.defineExamplesCallback) {
+        pageSetup.defineExamplesCallback({
+            defineExample: (exampleInit) => insertElementExample(allExamples, page.pageBreadcrumbs, exampleInit),
+        });
+    }
     return page;
 }

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

@@ -13,8 +13,6 @@ export type EntryTreeNode<EntryType extends ElementBookEntryTypeEnum = any> = {
 };
 export declare function isEntryNode<SpecificType extends ElementBookEntryTypeEnum>(input: unknown, entryType: SpecificType): input is EntryTreeNode<SpecificType>;
 export declare function createEmptyEntryTreeRoot(title: string | undefined): EntryTreeNode<ElementBookEntryTypeEnum.Root>;
-export declare function titleToBreadcrumb(title: string): string;
 export declare function entriesToTree(entries: ReadonlyArray<ElementBookEntry>, everythingTitle: string | undefined): EntryTreeNode<ElementBookEntryTypeEnum.Root>;
-export declare function listBreadcrumbs(entry: ElementBookEntry, includeSelf?: boolean): string[];
 export declare function findEntryByBreadcrumbs(breadcrumbs: ReadonlyArray<string>, tree: Readonly<EntryTreeNode>): Readonly<EntryTreeNode> | undefined;
 export {};

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

@@ -1,4 +1,5 @@
-import { collapseWhiteSpace, isLengthAtLeast, typedHasProperties } from '@augment-vir/common';
+import { isLengthAtLeast, typedHasProperties } from '@augment-vir/common';
+import { listBreadcrumbs, titleToBreadcrumb } from '../element-book-entry';
 import { ElementBookEntryTypeEnum } from '../element-book-entry-type';
 import { addTreeToCache, getTreeFromCache } from './tree-cache';
 export function doesNodeHaveEntryType(node, entryType) {
@@ -26,9 +27,6 @@ export function createEmptyEntryTreeRoot(title) {
     };
     return rootNode;
 }
-export function titleToBreadcrumb(title) {
-    return collapseWhiteSpace(title).toLowerCase().replaceAll(/\s/g, '-');
-}
 export function entriesToTree(entries, everythingTitle) {
     const baseTree = createBaseTree(entries, everythingTitle);
     return baseTree;
@@ -76,21 +74,6 @@ function traverseToImmediateParent(entry, currentTree) {
     }, currentTree);
     return immediateParentNode;
 }
-export function listBreadcrumbs(entry, includeSelf) {
-    const entryBreadcrumb = titleToBreadcrumb(entry.title);
-    if (entry.parent) {
-        return [
-            titleToBreadcrumb(entry.parent.title),
-            ...listBreadcrumbs(entry.parent, false),
-        ].concat(includeSelf ? [entryBreadcrumb] : []);
-    }
-    else if (includeSelf) {
-        return [entryBreadcrumb];
-    }
-    else {
-        return [];
-    }
-}
 export function findEntryByBreadcrumbs(breadcrumbs, tree) {
     if (!isLengthAtLeast(breadcrumbs, 1)) {
         return tree;

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

@@ -1,9 +1,9 @@
 import { wait } from '@augment-vir/common';
 import { VirIcon } from '@electrovir/icon-element';
 import { assign, css, html, listen, renderIf } from 'element-vir';
-import { isElementBookEntry } from '../../../data/element-book-entry/element-book-entry';
+import { isElementBookEntry, listBreadcrumbs, } from '../../../data/element-book-entry/element-book-entry';
 import { ElementBookEntryTypeEnum } from '../../../data/element-book-entry/element-book-entry-type';
-import { isEntryNode, listBreadcrumbs, } from '../../../data/element-book-entry/entry-tree/entry-tree';
+import { isEntryNode } from '../../../data/element-book-entry/entry-tree/entry-tree';
 import { ElementBookMainRoute, defaultElementBookFullRoute, extractSearchQuery, } from '../../../routing/element-book-routing';
 import { colorThemeCssVars } from '../../color-theme/color-theme';
 import { ChangeRouteEvent } from '../../events/change-route.event';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-book",
-    "version": "3.0.2",
+    "version": "4.0.0",
     "keywords": [
         "book",
         "design system",
@@ -41,7 +41,7 @@
         "@augment-vir/common": "^14.2.0",
         "@electrovir/icon-element": "^0.0.2",
         "colorjs.io": "^0.4.3",
-        "element-vir": "^12.5.2",
+        "element-vir": "^12.5.4",
         "lit-css-vars": "^2.0.2",
         "spa-router-vir": "^2.1.0",
         "typed-event-target": "^1.2.0"