element-book 22.2.2 → 23.0.0

package/README.md

@@ -2,21 +2,81 @@
 
 An [`element-vir`](https://npmjs.com/package/element-vir) drop-in element for building, testing, and demonstrating a collection of elements (or, in other words, a design system).
 
-# Installation
+## Installation
 
 ```bash
 npm i element-book
 ```
 
-# Terminology
+## Terminology
 
 -   **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
+## Usage
 
-_todo_
+1.  Define element-book pages with [`defineBookPage`](https://electrovir.github.io/element-vir/element-book/functions/defineBookPage.html):
 
-# Why not Storybook?
+    <!-- example-link: ./src/readme-examples/define-page.example.ts -->
+
+    ```TypeScript
+    import {defineBookPage} from '../data/book-entry/book-page/define-book-page.js';
+
+    export const myPage = defineBookPage({
+        /** Use `undefined` if your page is at the top level. */
+        parent: undefined,
+        title: 'My Page',
+    });
+    ```
+
+2.  Inside of a page definition, define an element example:
+
+    <!-- example-link: ./src/readme-examples/define-example.example.ts -->
+
+    ```TypeScript
+    import {html} from 'element-vir';
+    import {defineBookPage} from '../data/book-entry/book-page/define-book-page.js';
+
+    export const myPage = defineBookPage({
+        /** Use `undefined` if your page is at the top level. */
+        parent: undefined,
+        title: 'My Page',
+        defineExamples({defineExample}) {
+            defineExample({
+                title: 'My Example',
+                render() {
+                    return html`
+                        <p>Render your element here.</p>
+                    `;
+                },
+            });
+        },
+    });
+    ```
+
+3.  Instantiate an instance of the [element book app](https://electrovir.github.io/element-vir/element-book/variables/ElementBookApp.html) into your app and pass in all your pages:
+
+    <!-- example-link: ./src/readme-examples/use-app.example.ts -->
+
+    ```TypeScript
+    import {defineElementNoInputs, html} from 'element-vir';
+    import {ElementBookApp} from '../ui/elements/element-book-app/element-book-app.element.js';
+    import {myPage} from './define-page.example.js';
+
+    export const MyApp = defineElementNoInputs({
+        tagName: 'my-app',
+        render() {
+            return html`
+                <${ElementBookApp.assign({
+                    pages: [
+                        myPage,
+                    ],
+                })}></${ElementBookApp}>
+            `;
+        },
+    });
+    ```
+
+## Why not Storybook?
 
 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

@@ -1,11 +1,16 @@
-import { BookEntryTypeEnum } from './book-entry-type';
+import { BookEntryType } from './book-entry-type.js';
+/**
+ * Base properties for all book entry types.
+ *
+ * @category Internal
+ */
 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;
+    entryType: BookEntryType;
     /**
      * The parent page. A value of undefined here indicates that the entry should be at the top
      * level of the element book.

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

@@ -1,4 +1,9 @@
-export declare enum BookEntryTypeEnum {
+/**
+ * All possible types for element-book entries.
+ *
+ * @category Internal
+ */
+export declare enum BookEntryType {
     /** A single element example. */
     ElementExample = "element-example",
     /** An individual book page with element examples and/or sub-pages. */
@@ -6,4 +11,9 @@ export declare enum BookEntryTypeEnum {
     /** Tree root. Not for external use. */
     Root = "root"
 }
-export type AnyBookEntryType = BookEntryTypeEnum.ElementExample | BookEntryTypeEnum.Page | BookEntryTypeEnum.Root;
+/**
+ * A union of all possible element-book entry types.
+ *
+ * @category Internal
+ */
+export type AnyBookEntryType = BookEntryType.ElementExample | BookEntryType.Page | BookEntryType.Root;

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

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

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

@@ -1,7 +1,17 @@
-import { BookEntryTypeEnum } from './book-entry-type';
-import { BookElementExample, BookPage } from './book-page/book-page';
-import { BookRoot } from './book-root';
+import { BookEntryType } from './book-entry-type.js';
+import { BookElementExample, BookPage } from './book-page/book-page.js';
+import { BookRoot } from './book-root.js';
+/**
+ * All possible book entries.
+ *
+ * @category Internal
+ */
 export type BookEntry = BookPage | BookRoot | BookElementExample;
-export declare function isBookEntry<const SpecificType extends BookEntryTypeEnum>(entry: unknown, entryType: SpecificType): entry is Extract<BookEntry, {
+/**
+ * Check if the input is a book entry of the given type.
+ *
+ * @internal
+ */
+export declare function isBookEntry<const SpecificType extends BookEntryType>(entry: unknown, entryType: SpecificType): entry is Extract<BookEntry, {
     entryType: SpecificType;
 }>;

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

@@ -1,4 +1,9 @@
-import { typedHasProperty } from '@augment-vir/common';
+import { check } from '@augment-vir/assert';
+/**
+ * Check if the input is a book entry of the given type.
+ *
+ * @internal
+ */
 export function isBookEntry(entry, entryType) {
-    return typedHasProperty(entry, 'entryType') && entry.entryType === entryType;
+    return check.hasKey(entry, 'entryType') && entry.entryType === entryType;
 }

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

@@ -1,24 +1,62 @@
-export type BookPageControl<ControlType extends BookPageControlTypeEnum = BookPageControlTypeEnum> = {
+import type { EmptyObject } from 'type-fest';
+/**
+ * Adds a control to an element-book page.
+ *
+ * @category Internal
+ */
+export type BookPageControl<ControlType extends BookPageControlType = BookPageControlType> = {
     controlType: ControlType;
     initValue: BookPageControlValueType[ControlType];
     /** The name and label for the control. */
     controlName: string;
-} & (ControlType extends BookPageControlTypeEnum.Dropdown ? {
+} & (ControlType extends BookPageControlType.Dropdown ? {
     options: string[];
-} : {});
-export type BookPageControlInit<ControlType extends BookPageControlTypeEnum> = Omit<BookPageControl<ControlType>, 'controlName'>;
-export declare function isControlInitType<const SpecificControlType extends BookPageControlTypeEnum>(controlInit: BookPageControlInit<any>, specificType: SpecificControlType): controlInit is BookPageControlInit<SpecificControlType>;
+} : EmptyObject);
+/**
+ * Initialization options for an element-book page control.
+ *
+ * @category Internal
+ */
+export type BookPageControlInit<ControlType extends BookPageControlType> = Omit<BookPageControl<ControlType>, 'controlName'>;
+/**
+ * Checks and type guards that the input page control init is of the given type.
+ *
+ * @internal
+ */
+export declare function isControlInitType<const SpecificControlType extends BookPageControlType>(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.
+ *
+ * @category Main
+ */
+export declare function definePageControl<const ControlType extends BookPageControlType>(controlInit: BookPageControlInit<ControlType>): BookPageControlInit<ControlType>;
+/**
+ * Maps an object of user-defined controls to their initial values.
+ *
+ * @category Internal
  */
-export declare function definePageControl<const 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>>;
+/**
+ * Base type for a arbitrary, user-defined object of page controls.
+ *
+ * @category Internal
+ */
+export type BookPageControlsInitBase = Record<string, BookPageControlInit<BookPageControlType>>;
+/**
+ * Base type for a arbitrary, user-defined object of page control values.
+ *
+ * @category Internal
+ */
 export type BookPageControlsValues = ControlsToValues<BookPageControlsInitBase>;
-export declare enum BookPageControlTypeEnum {
+/**
+ * All the supported page control types. One of these must be chosen when defining a page control.
+ *
+ * @category Main
+ */
+export declare enum BookPageControlType {
     Checkbox = "checkbox",
     Color = "color",
     Dropdown = "dropdown",
@@ -27,7 +65,12 @@ export declare enum BookPageControlTypeEnum {
     Number = "number",
     Text = "text"
 }
-declare const controlValueTypes: {
+/**
+ * Specifies the default value for each page control type, as well as its type.
+ *
+ * @category Internal
+ */
+export declare const controlValueTypes: {
     checkbox: boolean;
     color: string;
     dropdown: string;
@@ -35,6 +78,15 @@ declare const controlValueTypes: {
     number: number;
     text: string;
 };
+/**
+ * Each page control type mapped to the type of their value.
+ *
+ * @category Internal
+ */
 export type BookPageControlValueType = typeof controlValueTypes;
+/**
+ * Checks that the given control init object is valid.
+ *
+ * @internal
+ */
 export declare function checkControls(controlsInit: BookPageControlsInitBase | undefined, pageName: string): Error[];
-export {};

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

@@ -1,32 +1,54 @@
+/**
+ * Checks and type guards that the input page control init is of the given type.
+ *
+ * @internal
+ */
 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.
+ *
+ * @category Main
  */
 export function definePageControl(controlInit) {
     return controlInit;
 }
-export var BookPageControlTypeEnum;
-(function (BookPageControlTypeEnum) {
-    BookPageControlTypeEnum["Checkbox"] = "checkbox";
-    BookPageControlTypeEnum["Color"] = "color";
-    BookPageControlTypeEnum["Dropdown"] = "dropdown";
+/**
+ * All the supported page control types. One of these must be chosen when defining a page control.
+ *
+ * @category Main
+ */
+export var BookPageControlType;
+(function (BookPageControlType) {
+    BookPageControlType["Checkbox"] = "checkbox";
+    BookPageControlType["Color"] = "color";
+    BookPageControlType["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 = {}));
+    BookPageControlType["Hidden"] = "hidden";
+    BookPageControlType["Number"] = "number";
+    BookPageControlType["Text"] = "text";
+})(BookPageControlType || (BookPageControlType = {}));
 const anySymbol = Symbol('any-type');
-const controlValueTypes = {
-    [BookPageControlTypeEnum.Checkbox]: false,
-    [BookPageControlTypeEnum.Color]: '',
-    [BookPageControlTypeEnum.Dropdown]: '',
-    [BookPageControlTypeEnum.Hidden]: anySymbol,
-    [BookPageControlTypeEnum.Number]: 0,
-    [BookPageControlTypeEnum.Text]: '',
+/**
+ * Specifies the default value for each page control type, as well as its type.
+ *
+ * @category Internal
+ */
+export const controlValueTypes = {
+    [BookPageControlType.Checkbox]: false,
+    [BookPageControlType.Color]: '',
+    [BookPageControlType.Dropdown]: '',
+    [BookPageControlType.Hidden]: anySymbol,
+    [BookPageControlType.Number]: 0,
+    [BookPageControlType.Text]: '',
 };
+/**
+ * Checks that the given control init object is valid.
+ *
+ * @internal
+ */
 export function checkControls(controlsInit, pageName) {
     if (!controlsInit) {
         return [];

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

@@ -1,22 +1,41 @@
 import { Overwrite, SetOptionalAndNullable } from '@augment-vir/common';
 import { CSSResult, HtmlInterpolation, PropertyInitMapBase, RenderParams, TypedEvent } from 'element-vir';
-import { GlobalValues } from '../../../ui/elements/element-book-app/global-values';
-import { BaseBookEntry } from '../base-book-entry';
-import { BookEntryTypeEnum } from '../book-entry-type';
-import { BookPageControlsInitBase, ControlsToValues } from './book-page-controls';
+import { GlobalValues } from '../../../ui/elements/element-book-app/global-values.js';
+import { BaseBookEntry } from '../base-book-entry.js';
+import { BookEntryType } from '../book-entry-type.js';
+import { BookPageControlsInitBase, ControlsToValues } from './book-page-controls.js';
+/**
+ * An individual element-book page.
+ *
+ * @category Type
+ */
 export type BookPage<GlobalValuesType extends GlobalValues = {}, ParentPage extends BookPage | undefined = any, ControlsInit extends BookPageControlsInitBase = BookPageControlsInitBase> = Overwrite<BaseBookEntry, {
+    /**
+     * The parent page of this page. If this page is meant to be at the top-level, set this to
+     * `undefined`.
+     */
     parent: ParentPage;
-    entryType: BookEntryTypeEnum.Page;
+    entryType: BookEntryType.Page;
 }> & {
     controls: ControlsInit;
     elementExamples: Record<string, BookElementExample>;
 };
+/**
+ * All parameters required for rendering an element-book page.
+ *
+ * @category Internal
+ */
 export type BookPageExampleRenderParams<GlobalValuesType extends GlobalValues, ControlsInit extends BookPageControlsInitBase, StateInit extends PropertyInitMapBase> = Pick<RenderParams<any, any, StateInit, any, any, any, any>, 'state' | 'updateState'> & {
     controls: ControlsToValues<ControlsInit> & GlobalValuesType;
 };
+/**
+ * An individual element example for an element-book page.
+ *
+ * @category Internal
+ */
 export type BookElementExample<GlobalValuesType extends GlobalValues = {}, ControlsInit extends BookPageControlsInitBase = {}, StateInit extends PropertyInitMapBase = {}> = Overwrite<BaseBookEntry, {
     parent: BookPage | undefined;
-    entryType: BookEntryTypeEnum.ElementExample;
+    entryType: BookEntryType.ElementExample;
 } & {
     /** Initialize the state for this example. */
     stateInitStatic?: StateInit | undefined;
@@ -28,10 +47,12 @@ export type BookElementExample<GlobalValuesType extends GlobalValues = {}, Contr
      */
     styles?: CSSResult | undefined;
     /** Render the example. */
-    renderCallback: (renderParams: BookPageExampleRenderParams<GlobalValuesType, ControlsInit, StateInit>) => HtmlInterpolation;
+    render: (renderParams: BookPageExampleRenderParams<GlobalValuesType, ControlsInit, StateInit>) => HtmlInterpolation;
 }>;
 /**
  * The properties that are necessary to initialize an element example. Missing properties will be
- * filling in by the parent.
+ * filled in by the parent.
+ *
+ * @category Internal
  */
 export type BookElementExampleInit<GlobalValuesType extends GlobalValues, Controls extends BookPageControlsInitBase, StateInit extends PropertyInitMapBase> = SetOptionalAndNullable<Omit<BookElementExample<GlobalValuesType, Controls, StateInit>, 'entryType' | 'parent' | 'errors'>, 'descriptionParagraphs'>;

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

@@ -1 +1,2 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type */
 export {};

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

@@ -1,12 +1,32 @@
-import { PartialAndUndefined } from '@augment-vir/common';
-import { BookTreeNode } from '../../book-tree/book-tree-node';
-import { BookPageControlsValues } from './book-page-controls';
+import { PartialWithUndefined } from '@augment-vir/common';
+import { BookTreeNode } from '../../book-tree/book-tree-node.js';
+import { BookPageControlsValues } from './book-page-controls.js';
+/**
+ * Nested page controls.
+ *
+ * @category Internal
+ */
 export type ControlsWrapper = {
     children: {
         [Breadcrumb: string]: ControlsWrapper;
     };
     controls: BookPageControlsValues;
 };
+/**
+ * Find the controls at the given breadcrumbs.
+ *
+ * @category Internal
+ */
 export declare function traverseControls(controlsWrapper: ControlsWrapper, fullUrlBreadcrumbs: ReadonlyArray<string>): BookPageControlsValues;
+/**
+ * Add new controls at the given breadcrumbs.
+ *
+ * @category Internal
+ */
 export declare function createNewControls(controlsWrapper: Readonly<ControlsWrapper>, breadcrumbsForNewValue: ReadonlyArray<string>, newValues: BookPageControlsValues): ControlsWrapper;
-export declare function updateTreeControls(node: BookTreeNode, existingControls: PartialAndUndefined<ControlsWrapper> | undefined): ControlsWrapper;
+/**
+ * Add new controls from the given tree node.
+ *
+ * @category Internal
+ */
+export declare function updateTreeControls(node: BookTreeNode, existingControls: PartialWithUndefined<ControlsWrapper> | undefined): ControlsWrapper;

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

@@ -1,6 +1,11 @@
 import { mapObjectValues } from '@augment-vir/common';
-import { isBookTreeNode } from '../../book-tree/book-tree';
-import { BookEntryTypeEnum } from '../book-entry-type';
+import { isBookTreeNode } from '../../book-tree/book-tree.js';
+import { BookEntryType } from '../book-entry-type.js';
+/**
+ * Find the controls at the given breadcrumbs.
+ *
+ * @category Internal
+ */
 export function traverseControls(controlsWrapper, fullUrlBreadcrumbs) {
     return traverseAndInsertNewControls(controlsWrapper, [
         /** Empty string represents the breadcrumb for the root node */
@@ -24,6 +29,11 @@ function traverseAndInsertNewControls(controlsWrapper, urlBreadcrumbs, newValues
     };
     return allControls;
 }
+/**
+ * Add new controls at the given breadcrumbs.
+ *
+ * @category Internal
+ */
 export function createNewControls(controlsWrapper, breadcrumbsForNewValue, newValues) {
     const newControls = { ...controlsWrapper };
     traverseAndInsertNewControls(newControls, [
@@ -33,9 +43,14 @@ export function createNewControls(controlsWrapper, breadcrumbsForNewValue, newVa
     ], newValues);
     return newControls;
 }
+/**
+ * Add new controls from the given tree node.
+ *
+ * @category Internal
+ */
 export function updateTreeControls(node, existingControls) {
     const controls = existingControls?.controls ||
-        (isBookTreeNode(node, BookEntryTypeEnum.Page)
+        (isBookTreeNode(node, BookEntryType.Page)
             ? mapObjectValues(node.entry.controls, (name, setup) => {
                 return setup.initValue;
             })

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

@@ -1,26 +1,58 @@
 import { SetOptionalAndNullable } from '@augment-vir/common';
 import { PropertyInitMapBase } from 'element-vir';
-import { GlobalValues } from '../../../ui/elements/element-book-app/global-values';
-import { InfiniteRecursionLimiter } from '../../../util/type';
-import { BookElementExampleInit, BookPage } from './book-page';
-import { BookPageControlsInitBase } from './book-page-controls';
+import type { EmptyObject } from 'type-fest';
+import { GlobalValues } from '../../../ui/elements/element-book-app/global-values.js';
+import { InfiniteRecursionLimiter } from '../../../util/type.js';
+import { BookPageControlsInitBase } from './book-page-controls.js';
+import { BookElementExampleInit, BookPage } from './book-page.js';
+/**
+ * The callback type for a book page definition's `defineExample` callback.
+ *
+ * @category Internal
+ */
 export type DefineExampleCallback<GlobalValuesType extends GlobalValues = {}, ControlsInit extends BookPageControlsInitBase = BookPageControlsInitBase> = <StateInit extends PropertyInitMapBase>(exampleInit: BookElementExampleInit<GlobalValuesType, ControlsInit, StateInit>) => void;
+/**
+ * Used for `defineExamples` in a book page's init.
+ *
+ * @category Internal
+ */
 export type ElementExamplesDefiner<GlobalValuesType extends GlobalValues = {}, ControlsInit extends BookPageControlsInitBase = BookPageControlsInitBase> = (params: {
     defineExample: DefineExampleCallback<GlobalValuesType, ControlsInit>;
 }) => void;
-type CollapseControlsInit<ParentPage extends BookPage | undefined, CurrentControlsInit extends BookPageControlsInitBase, 
+/**
+ * Collapses all element-book control inits into a single flag object.
+ *
+ * @category Internal
+ */
+export 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 GlobalValuesType, infer GrandParentPage, infer ParentControls> ? CollapseControlsInit<GrandParentPage, ParentControls, RemainingDepth> : {} : {});
-type CollapseGlobalValuesType<ParentPage extends BookPage | undefined, GlobalValuesType extends GlobalValues, 
+RecursionDepth = InfiniteRecursionLimiter> = CurrentControlsInit & (RecursionDepth extends [any, ...infer RemainingDepth] ? ParentPage extends BookPage<infer GlobalValuesType, infer GrandParentPage, infer ParentControls> ? CollapseControlsInit<GrandParentPage, ParentControls, RemainingDepth> : EmptyObject : EmptyObject);
+/**
+ * Collapses all element-book global values into a single flag object.
+ *
+ * @category Internal
+ */
+export type CollapseGlobalValuesType<ParentPage extends BookPage | undefined, GlobalValuesType extends GlobalValues, 
 /** Prevent infinite recursion TypeScript errors. */
-RecursionDepth = InfiniteRecursionLimiter> = GlobalValuesType & (RecursionDepth extends [any, ...infer RemainingDepth] ? ParentPage extends BookPage<infer GlobalValuesType, infer GrandParentPage, infer ParentControls> ? CollapseGlobalValuesType<GrandParentPage, GlobalValuesType, RemainingDepth> : {} : {});
+RecursionDepth = InfiniteRecursionLimiter> = GlobalValuesType & (RecursionDepth extends [any, ...infer RemainingDepth] ? ParentPage extends BookPage<infer GlobalValuesType, infer GrandParentPage, infer ParentControls> ? CollapseGlobalValuesType<GrandParentPage, GlobalValuesType, RemainingDepth> : EmptyObject : EmptyObject);
+/**
+ * The parameters for initializing a new element-book page.
+ *
+ * @category Type
+ */
 export type BookPageInit<GlobalValuesType extends GlobalValues, ParentPage extends BookPage | undefined, CurrentControlsInit extends BookPageControlsInitBase> = SetOptionalAndNullable<Omit<BookPage<any, ParentPage, CurrentControlsInit>, 'entryType' | 'elementExamples' | 'errors'>, 'controls' | 'descriptionParagraphs'> & {
-    elementExamplesCallback?: ElementExamplesDefiner<CollapseGlobalValuesType<ParentPage, GlobalValuesType>, CollapseControlsInit<ParentPage, CurrentControlsInit>> | undefined;
+    defineExamples?: ElementExamplesDefiner<CollapseGlobalValuesType<ParentPage, GlobalValuesType>, CollapseControlsInit<ParentPage, CurrentControlsInit>> | undefined;
 };
 /**
- * Allows insertion of the global values type to a page. This is not necessary if you aren't using
- * global values in your element-book instance.
+ * A variant of {@link defineBookPage} that allows you specify what the expected global element-book
+ * values are for the page that you are defining.
+ *
+ * @category Main
  */
 export declare function defineBookPageWithGlobals<const GlobalValuesType extends GlobalValues = {}>(): <const ParentPage extends BookPage | undefined = undefined, const ControlsInit extends BookPageControlsInitBase = {}>(pageInit: BookPageInit<GlobalValuesType, ParentPage, ControlsInit>) => BookPage<GlobalValuesType, ParentPage, ControlsInit>;
+/**
+ * Define an element-book page. This is how you create new entries for your element-book instance.
+ *
+ * @category Main
+ */
 export declare function defineBookPage<const GlobalValuesType extends GlobalValues = {}, const ParentPage extends BookPage | undefined = undefined, const ControlsInit extends BookPageControlsInitBase = {}>(pageInit: BookPageInit<GlobalValuesType, ParentPage, ControlsInit>): BookPage<GlobalValuesType, ParentPage, ControlsInit>;
-export {};

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

@@ -1,41 +1,48 @@
-import { isTruthy } from '@augment-vir/common';
-import { BookEntryTypeEnum } from '../book-entry-type';
-import { titleToUrlBreadcrumb } from '../url-breadcrumbs';
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+import { check } from '@augment-vir/assert';
+import { BookEntryType } from '../book-entry-type.js';
+import { titleToUrlBreadcrumb } from '../url-breadcrumbs.js';
 /**
- * Allows insertion of the global values type to a page. This is not necessary if you aren't using
- * global values in your element-book instance.
+ * A variant of {@link defineBookPage} that allows you specify what the expected global element-book
+ * values are for the page that you are defining.
+ *
+ * @category Main
  */
 export function defineBookPageWithGlobals() {
     return (pageInit) => {
         return defineBookPage(pageInit);
     };
 }
+/**
+ * Define an element-book page. This is how you create new entries for your element-book instance.
+ *
+ * @category Main
+ */
 export function defineBookPage(pageInit) {
     const page = {
         ...pageInit,
-        entryType: BookEntryTypeEnum.Page,
+        entryType: BookEntryType.Page,
         elementExamples: {},
         descriptionParagraphs: pageInit.descriptionParagraphs ?? [],
         controls: pageInit.controls ?? {},
         errors: [],
     };
     const alreadyTakenElementExampleNames = new Set();
-    if (pageInit.elementExamplesCallback) {
-        pageInit.elementExamplesCallback({
+    if (pageInit.defineExamples) {
+        pageInit.defineExamples({
             defineExample(elementExampleInit) {
                 const newExample = {
                     ...elementExampleInit,
-                    entryType: BookEntryTypeEnum.ElementExample,
+                    entryType: BookEntryType.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),
+                    ].filter(check.isTruthy),
                 };
                 alreadyTakenElementExampleNames.add(elementExampleInit.title);
-                page.elementExamples[titleToUrlBreadcrumb(newExample.title)] =
-                    newExample;
+                page.elementExamples[titleToUrlBreadcrumb(newExample.title)] = newExample;
             },
         });
     }