element-book 1.0.2 → 2.0.0

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

@@ -1,13 +1,13 @@
 import { Overwrite } from '@augment-vir/common';
 import { ElementBookEntryTypeEnum } from '../element-book-entry-type';
 export type ElementBookChapter = Overwrite<BaseElementBookEntry, {
-    type: ElementBookEntryTypeEnum.Chapter;
+    entryType: ElementBookEntryTypeEnum.Chapter;
 }>;
 /** This is in the ElementBookChapter file so that they don't circularly depend on each other. */
 export type BaseElementBookEntry = {
     /** Display name for the chapter or page. This is also used to create breadcrumbs and URL paths. */
     title: string;
-    type: ElementBookEntryTypeEnum;
+    entryType: ElementBookEntryTypeEnum;
     /**
      * The parent chapter. A value of undefined here indicates that the chapter or page should be at
      * the top level.
@@ -19,4 +19,4 @@ export type BaseElementBookEntry = {
      */
     descriptionParagraphs?: ReadonlyArray<string> | undefined;
 };
-export declare function defineElementBookChapter(chapterSetup: Omit<ElementBookChapter, 'type'>): ElementBookChapter;
+export declare function defineElementBookChapter(chapterSetup: Omit<ElementBookChapter, 'entryType'>): ElementBookChapter;

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

@@ -9,7 +9,7 @@ export function defineElementBookChapter(chapterSetup) {
         return new Error(`Cannot have an element-book chapter with an empty title.`);
     }
     const chapter = {
-        type: ElementBookEntryTypeEnum.Chapter,
+        entryType: ElementBookEntryTypeEnum.Chapter,
         ...chapterSetup,
     };
     return chapter;

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

@@ -2,11 +2,11 @@ import { ElementBookChapter } from './element-book-chapter/element-book-chapter'
 import { ElementBookEntryTypeEnum } from './element-book-entry-type';
 import { ElementBookPage } from './element-book-page/element-book-page';
 export type ElementBookRoot = {
-    type: ElementBookEntryTypeEnum.Root;
+    entryType: ElementBookEntryTypeEnum.Root;
     title: string;
     parent: undefined;
 };
 export type ElementBookEntry = ElementBookChapter | ElementBookPage | ElementBookRoot;
-export declare function isElementBookEntry<SpecificType extends ElementBookEntryTypeEnum>(entry: unknown, type: SpecificType): entry is Extract<ElementBookEntry, {
-    type: SpecificType;
+export declare function isElementBookEntry<SpecificType extends ElementBookEntryTypeEnum>(entry: unknown, entryType: SpecificType): entry is Extract<ElementBookEntry, {
+    entryType: SpecificType;
 }>;

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

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

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

@@ -0,0 +1,13 @@
+export declare enum ElementBookPageControlTypeEnum {
+    Checkbox = "checkbox",
+    Color = "color",
+    Dropdown = "dropdown",
+    Text = "text"
+}
+export type ElementBookPageControlValueType = {
+    [ElementBookPageControlTypeEnum.Checkbox]: boolean;
+    [ElementBookPageControlTypeEnum.Color]: string;
+    /** Value type corresponds to which option in the dropdown is selected. */
+    [ElementBookPageControlTypeEnum.Dropdown]: string;
+    [ElementBookPageControlTypeEnum.Text]: string;
+};

package/dist/data/element-book-entry/element-book-page/element-book-page-controls/element-book-page-control-type.js

@@ -0,0 +1,7 @@
+export var ElementBookPageControlTypeEnum;
+(function (ElementBookPageControlTypeEnum) {
+    ElementBookPageControlTypeEnum["Checkbox"] = "checkbox";
+    ElementBookPageControlTypeEnum["Color"] = "color";
+    ElementBookPageControlTypeEnum["Dropdown"] = "dropdown";
+    ElementBookPageControlTypeEnum["Text"] = "text";
+})(ElementBookPageControlTypeEnum || (ElementBookPageControlTypeEnum = {}));

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

@@ -0,0 +1,13 @@
+import { ElementBookPageControlTypeEnum, ElementBookPageControlValueType } from './element-book-page-control-type';
+export type ElementBookPageControl<ControlType extends ElementBookPageControlTypeEnum> = {
+    controlType: ControlType;
+    initValue: ElementBookPageControlValueType[ControlType];
+    controlName: string;
+};
+export type ElementBookPageControlInit<ControlType extends ElementBookPageControlTypeEnum> = Omit<ElementBookPageControl<ControlType>, 'controlName'>;
+/** Define a page control. This doesn't do anything fancy but it helps immensely with type inference. */
+export declare function definePageControl<ControlType extends ElementBookPageControlTypeEnum>(controlInit: ElementBookPageControlInit<ControlType>): ElementBookPageControlInit<ControlType>;
+export type ElementBookPageControlMap = Record<string, ElementBookPageControlInit<ElementBookPageControlTypeEnum>>;
+export type PageControlsToValues<Controls extends ElementBookPageControlMap> = {
+    [ControlName in keyof Controls]: Controls[ControlName]['initValue'];
+};

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

@@ -0,0 +1,4 @@
+/** Define a page control. This doesn't do anything fancy but it helps immensely with type inference. */
+export function definePageControl(controlInit) {
+    return controlInit;
+}

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

@@ -1,7 +1,16 @@
-import { PropertyInitMapBase, TypedEvent } from 'element-vir';
+import { RequireNonVoid } from '@augment-vir/common';
+import { PropertyInitMapBase, RenderParams, TypedEvent } from 'element-vir';
 import { CSSResult } from 'lit';
-export type ElementBookPageExample<StateInit extends PropertyInitMapBase = {}> = {
+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>>;
+};
+export type ElementBookPageExampleInit<ParentPage extends ElementBookPage<any>, 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). */
@@ -12,11 +21,9 @@ export type ElementBookPageExample<StateInit extends PropertyInitMapBase = {}> =
      */
     styles?: CSSResult;
     /** Set to true to hide the example controls (example title and buttons). */
-    hideControls?: boolean | undefined;
+    hideExampleControls?: boolean | undefined;
     /** Render the example. */
-    render: (renderParams: {
-        state: StateInit;
-        updateState: (newState: Partial<StateInit>) => void;
-    }) => unknown;
+    renderCallback: RequireNonVoid<RenderOutput, (renderParams: ElementBookPageExampleRenderParams<ParentPage, StateInit>) => RenderOutput, 'renderCallback is missing a return statement'>;
 };
-export declare function createExample<StateInit extends PropertyInitMapBase>(example: ElementBookPageExample<StateInit>): ElementBookPageExample<StateInit>;
+/** 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,3 +1,20 @@
-export function createExample(example) {
-    return example;
+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;
+    }
 }

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

@@ -1,10 +1,16 @@
 import { Overwrite } from '@augment-vir/common';
+import { SetOptional } from 'type-fest';
 import { BaseElementBookEntry } from '../element-book-chapter/element-book-chapter';
 import { ElementBookEntryTypeEnum } from '../element-book-entry-type';
-import { ElementBookPageExample } from './element-book-page-example';
-export type ElementBookPage = Overwrite<BaseElementBookEntry, {
-    type: ElementBookEntryTypeEnum.Page;
+import { ElementBookPageControlMap } from './element-book-page-controls/element-book-page-control';
+import { ElementBookPageExampleInit } from './element-book-page-example';
+export type ElementBookPage<Controls extends ElementBookPageControlMap = ElementBookPageControlMap> = Overwrite<BaseElementBookEntry, {
+    entryType: ElementBookEntryTypeEnum.Page;
 }> & {
-    examples: ReadonlyArray<ElementBookPageExample<any>>;
+    controls: Controls;
+    examples: Record<string, ElementBookPageExampleInit<any, any, any> | Error>;
+    pageBreadcrumbs: ReadonlyArray<string>;
 };
-export declare function defineElementBookPage(pageSetup: Omit<ElementBookPage, 'type'>): ElementBookPage;
+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 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,36 +1,14 @@
-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) {
-        errors.push(new Error(`Cannot have an element-book page with an empty title.`));
+        throw new Error(`Cannot have an element-book page with an empty title.`);
     }
     const page = {
-        type: ElementBookEntryTypeEnum.Page,
+        entryType: ElementBookEntryTypeEnum.Page,
         ...pageSetup,
+        examples: {},
+        controls: pageSetup.controls ?? {},
+        pageBreadcrumbs: [],
     };
-    const pageBreadcrumbs = listBreadcrumbs(page, true);
-    const exampleTitlesSet = new Set();
-    pageSetup.examples.forEach((example) => {
-        const failureMessage = `Failed to define example '${pageBreadcrumbs
-            .concat(example.title)
-            .join(' > ')}'`;
-        if (exampleTitlesSet.has(example.title)) {
-            errors.push(Error(`${failureMessage}: title '${example.title}' is already being used.`));
-        }
-        else if (!example.title) {
-            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.d.ts

@@ -1,16 +1,16 @@
 import { ElementBookEntry } from '../element-book-entry';
 import { ElementBookEntryTypeEnum } from '../element-book-entry-type';
-export declare function doesNodeHaveEntryType<EntryType extends ElementBookEntryTypeEnum>(node: EntryTreeNode<any>, type: EntryType): node is EntryTreeNode<EntryType>;
+export declare function doesNodeHaveEntryType<EntryType extends ElementBookEntryTypeEnum>(node: EntryTreeNode<any>, entryType: EntryType): node is EntryTreeNode<EntryType>;
 declare const markerKeyName = "isElementBookEntryTreeNode";
 export type EntryTreeNode<EntryType extends ElementBookEntryTypeEnum = ElementBookEntryTypeEnum> = {
     [markerKeyName]: true;
     entry: Extract<ElementBookEntry, {
-        type: EntryType;
+        entryType: EntryType;
     }>;
     breadcrumb: string;
     children: Record<string, EntryTreeNode>;
 };
-export declare function isEntryNode<SpecificType extends ElementBookEntryTypeEnum>(input: unknown, type: SpecificType): input is EntryTreeNode<SpecificType>;
+export declare function isEntryNode<SpecificType extends ElementBookEntryTypeEnum>(input: unknown, entryType: SpecificType): input is EntryTreeNode<SpecificType>;
 export declare function createEmptyEntryTreeRoot(title: string | undefined): EntryTreeNode;
 export declare function titleToBreadcrumb(title: string): string;
 export declare function entriesToTree(entries: ReadonlyArray<ElementBookEntry>, everythingTitle: string | undefined): EntryTreeNode<ElementBookEntryTypeEnum>;

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

@@ -1,22 +1,22 @@
 import { collapseWhiteSpace, isLengthAtLeast, typedHasProperties } from '@augment-vir/common';
 import { ElementBookEntryTypeEnum } from '../element-book-entry-type';
-export function doesNodeHaveEntryType(node, type) {
-    return node.entry.type === type;
+export function doesNodeHaveEntryType(node, entryType) {
+    return node.entry.entryType === entryType;
 }
 const markerKeyName = 'isElementBookEntryTreeNode';
-export function isEntryNode(input, type) {
+export function isEntryNode(input, entryType) {
     return !!(typedHasProperties(input, [
         markerKeyName,
         'entry',
     ]) &&
         input[markerKeyName] &&
-        input.entry.type === type);
+        input.entry.entryType === entryType);
 }
 export function createEmptyEntryTreeRoot(title) {
     const rootNode = {
         [markerKeyName]: true,
         entry: {
-            type: ElementBookEntryTypeEnum.Root,
+            entryType: ElementBookEntryTypeEnum.Root,
             title: title || 'Everything',
             parent: undefined,
         },

package/dist/data/unset.d.ts

@@ -0,0 +1 @@
+export declare const unsetInternalState: unique symbol;

package/dist/data/unset.js

@@ -0,0 +1 @@
+export const unsetInternalState = Symbol('unset-internal-state');

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export * from './data/element-book-entry/element-book-chapter/element-book-chapter';
 export * from './data/element-book-entry/element-book-entry';
 export * from './data/element-book-entry/element-book-page/element-book-page';
+export * from './data/element-book-entry/element-book-page/element-book-page-controls/element-book-page-control';
+export * from './data/element-book-entry/element-book-page/element-book-page-controls/element-book-page-control-type';
 export * from './data/element-book-entry/element-book-page/element-book-page-example';
 export * from './ui/elements/element-book-app/element-book-app.element';
 export * from './ui/elements/element-book-app/element-book-config';

package/dist/index.js

@@ -1,6 +1,8 @@
 export * from './data/element-book-entry/element-book-chapter/element-book-chapter';
 export * from './data/element-book-entry/element-book-entry';
 export * from './data/element-book-entry/element-book-page/element-book-page';
+export * from './data/element-book-entry/element-book-page/element-book-page-controls/element-book-page-control';
+export * from './data/element-book-entry/element-book-page/element-book-page-controls/element-book-page-control-type';
 export * from './data/element-book-entry/element-book-page/element-book-page-example';
 export * from './ui/elements/element-book-app/element-book-app.element';
 export * from './ui/elements/element-book-app/element-book-config';

package/dist/routing/create-element-book-router.js

@@ -1,6 +1,6 @@
 import { isEnumValue } from '@augment-vir/common';
 import { createSpaRouter } from 'spa-router-vir';
-import { ElementBookMainRoute, defaultElementBookFullRoute, } from './element-book-routing';
+import { defaultElementBookFullRoute, ElementBookMainRoute, } from './element-book-routing';
 export function createElementBookRouter(baseRoute) {
     return createSpaRouter({
         routeBase: baseRoute,

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

@@ -4,6 +4,6 @@ export declare enum ElementBookMainRoute {
     Book = "book"
 }
 export type ValidElementBookPaths = [ElementBookMainRoute.Search, string] | [ElementBookMainRoute.Book, ...string[]];
-export type ElementBookFullRoute = Required<Readonly<FullRoute<ValidElementBookPaths, undefined, undefined>>>;
+export type ElementBookFullRoute = Required<Readonly<FullRoute<ValidElementBookPaths, undefined | Record<string, string>, undefined>>>;
 export declare const defaultElementBookFullRoute: Readonly<ElementBookFullRoute>;
-export type ElementBookRouter = Readonly<SpaRouter<ValidElementBookPaths, undefined, undefined>>;
+export type ElementBookRouter = ElementBookFullRoute extends FullRoute<infer Paths, infer Search, infer Hash> ? Readonly<SpaRouter<Paths, Search, Hash>> : never;

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

@@ -6,8 +6,8 @@ type ColorThemeState = {
     theme: ColorTheme;
 };
 export declare const ElementBookApp: import("element-vir").DeclarativeElementDefinition<"element-book-app", ElementBookConfig, {
-    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;
+    currentRoute: Readonly<Required<Readonly<import("spa-router-vir").FullRoute<import("../../../routing/element-book-routing").ValidElementBookPaths, Record<string, string> | undefined, undefined>>>>;
+    router: Readonly<import("spa-router-vir").SpaRouter<import("../../../routing/element-book-routing").ValidElementBookPaths, Record<string, string> | undefined, undefined>> | undefined;
     colors: ColorThemeState;
 }, {
     pathUpdate: import("element-vir").DefinedTypedEventNameDefinition<readonly string[]>;

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

@@ -86,7 +86,7 @@ function createNavigationTree({ indent, entryTreeNode, rootPath, selectedPath, r
     const entryPath = entryTreeNode.breadcrumb
         ? rootPath.concat(entryTreeNode.breadcrumb)
         : rootPath;
-    const isPage = entryTreeNode.entry.type === ElementBookEntryTypeEnum.Page;
+    const isPage = entryTreeNode.entry.entryType === ElementBookEntryTypeEnum.Page;
     const childTemplates = Object.values(entryTreeNode.children).map((child) => {
         return createNavigationTree({
             indent: indent + 1,
@@ -99,7 +99,7 @@ function createNavigationTree({ indent, entryTreeNode, rootPath, selectedPath, r
     return html `
         <div class="nav-tree-entry" style="--indent: ${indent};">
             <slot></slot>
-            <li class=${entryTreeNode.entry.type}>
+            <li class=${entryTreeNode.entry.entryType}>
                 <${ElementBookRouteLink}
                     ${assign(ElementBookRouteLink, {
         router: router,

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

@@ -214,7 +214,7 @@ function createDescriptionTemplate(entry) {
     `;
 }
 function extractNestedPages(node) {
-    if (node.entry.type === ElementBookEntryTypeEnum.Page) {
+    if (node.entry.entryType === ElementBookEntryTypeEnum.Page) {
         return [node];
     }
     const nestedPages = [

package/dist/ui/elements/entry-display/element-book-example-controls.element.d.ts

@@ -1,4 +1,4 @@
-import { ElementBookPageExample } from '../../../data/element-book-entry/element-book-page/element-book-page-example';
+import { ElementBookPageExampleInit } from '../../../data/element-book-entry/element-book-page/element-book-page-example';
 export declare const ElementBookExampleControls: import("element-vir").DeclarativeElementDefinition<"element-book-example-controls", {
-    example: ElementBookPageExample;
+    example: ElementBookPageExampleInit<any, any, any>;
 }, {}, {}, string, string, import("lit-html").HTMLTemplateResult>;

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

@@ -16,7 +16,7 @@ export const ElementBookExampleControls = defineElementBookElement()({
         }
     `,
     renderCallback({ inputs }) {
-        const title = inputs.example.hideControls ? '' : inputs.example.title;
+        const title = inputs.example.hideExampleControls ? '' : inputs.example.title;
         return html `
             <span>
                 ${title || defaultTitle}

package/dist/ui/elements/entry-display/element-book-example-viewer.element.d.ts

@@ -1,7 +1,6 @@
-import { ElementBookPageExample } from '../../../data/element-book-entry/element-book-page/element-book-page-example';
+import { ElementBookPageExampleInit } from '../../../data/element-book-entry/element-book-page/element-book-page-example';
 export declare const ElementBookExampleViewer: import("element-vir").DeclarativeElementDefinition<"element-book-example-viewer", {
-    example: ElementBookPageExample;
+    example: ElementBookPageExampleInit<any, any, any>;
     breadcrumbs: ReadonlyArray<string>;
-}, {
-    internalState: any;
-}, {}, string, string, string | import("lit-html").HTMLTemplateResult>;
+    currentPageControls: Record<string, any>;
+}, any, {}, string, string, string | import("lit-html").HTMLTemplateResult>;

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

@@ -1,27 +1,27 @@
 import { extractErrorMessage } from '@augment-vir/common';
 import { html, renderIf } from 'element-vir';
+import { unsetInternalState } from '../../../data/unset';
 import { defineElementBookElement } from '../define-book-element';
-const unsetInternalState = Symbol('unset-internal-state');
 export const ElementBookExampleViewer = defineElementBookElement()({
     tagName: 'element-book-example-viewer',
     stateInit: {
-        internalState: unsetInternalState,
+        isUnset: unsetInternalState,
     },
     renderCallback({ state, inputs, updateState }) {
-        if (state.internalState === unsetInternalState) {
-            updateState({ internalState: inputs.example.stateInit });
+        if (!inputs.example.renderCallback || typeof inputs.example.renderCallback === 'string') {
+            throw new Error(`Failed to render example '${inputs.example.title}': renderCallback is not a function`);
+        }
+        if (state.isUnset === unsetInternalState) {
+            updateState({
+                isUnset: undefined,
+                ...inputs.example.stateInit,
+            });
         }
         try {
-            const output = inputs.example.render({
-                state: state.internalState,
-                updateState: (newState) => {
-                    updateState({
-                        internalState: {
-                            ...state.internalState,
-                            ...newState,
-                        },
-                    });
-                },
+            const output = inputs.example.renderCallback({
+                state,
+                updateState,
+                controls: inputs.currentPageControls,
             });
             return html `
                 ${renderIf(!!inputs.example.styles, html `
@@ -37,4 +37,7 @@ export const ElementBookExampleViewer = defineElementBookElement()({
             return `${inputs.breadcrumbs.join(' > ')} failed: ${extractErrorMessage(error)}`;
         }
     },
+    options: {
+        allowPolymorphicState: true,
+    },
 });

package/dist/ui/elements/entry-display/element-book-page-controls.element.d.ts

@@ -0,0 +1,11 @@
+import { ElementBookPage } from '../../../data/element-book-entry/element-book-page/element-book-page';
+import { ElementBookPageControlMap } from '../../../data/element-book-entry/element-book-page/element-book-page-controls/element-book-page-control';
+export declare const ElementBookPageControls: import("element-vir").DeclarativeElementDefinition<"element-book-page-controls", {
+    config: ElementBookPage['controls'];
+    currentValues: Record<string, ElementBookPageControlMap['initValue']>;
+}, {}, {
+    controlValueChange: import("element-vir").DefinedTypedEventNameDefinition<{
+        name: string;
+        value: unknown;
+    }>;
+}, string, string, import("lit-html").HTMLTemplateResult[]>;

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

@@ -0,0 +1,65 @@
+import { css, defineElementEvent, html, listen } from 'element-vir';
+import { ElementBookPageControlTypeEnum } from '../../../data/element-book-entry/element-book-page/element-book-page-controls/element-book-page-control-type';
+import { defineElementBookElement } from '../define-book-element';
+export const ElementBookPageControls = defineElementBookElement()({
+    tagName: 'element-book-page-controls',
+    events: {
+        controlValueChange: defineElementEvent(),
+    },
+    styles: css `
+        :host {
+            display: flex;
+            flex-wrap: wrap;
+            gap: 16px;
+        }
+
+        .control-wrapper {
+            display: flex;
+            gap: 4px;
+            flex-direction: column;
+        }
+
+        .error {
+            font-weight: bold;
+            color: red;
+        }
+    `,
+    renderCallback({ inputs, dispatch, events }) {
+        return Object.entries(inputs.config).map(([controlName, controlInit,]) => {
+            const controlInputTemplate = createControlInput(inputs.currentValues[controlName], controlInit.controlType, (newValue) => {
+                dispatch(new events.controlValueChange({
+                    name: controlName,
+                    value: newValue,
+                }));
+            });
+            return html `
+                    <label class="control-wrapper">
+                        <span>${controlName}</span>
+                        ${controlInputTemplate}
+                    </label>
+                `;
+        });
+    },
+});
+function createControlInput(value, controlType, valueChange) {
+    if (controlType === ElementBookPageControlTypeEnum.Text) {
+        return html `
+            <input
+                type="text"
+                .value=${value}
+                ${listen('input', (event) => {
+            const inputElement = event.currentTarget;
+            if (!(inputElement instanceof HTMLInputElement)) {
+                throw new Error("Din't get an input element from the event target.");
+            }
+            valueChange(inputElement.value);
+        })}
+            />
+        `;
+    }
+    else {
+        return html `
+            <p class="error">${controlType} controls are not implemented yet.</p>
+        `;
+    }
+}

package/dist/ui/elements/entry-display/element-book-page-examples.element.d.ts

@@ -2,4 +2,6 @@ import { ElementBookPage } from '../../../data/element-book-entry/element-book-p
 export declare const ElementBookPageExamples: import("element-vir").DeclarativeElementDefinition<"element-book-page-examples", {
     page: ElementBookPage;
     parentBreadcrumbs: ReadonlyArray<string>;
-}, {}, {}, string, string, unknown>;
+}, {
+    unset: symbol;
+}, {}, string, string, import("lit-html").HTMLTemplateResult>;

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

@@ -1,17 +1,31 @@
-import { assign, classMap, css, html, renderIf, repeat } from 'element-vir';
+import { mapObjectValues } from '@augment-vir/common';
+import { assign, classMap, css, html, listen, renderIf, repeat } from 'element-vir';
+import { unsetInternalState } from '../../../data/unset';
 import { colorThemeCssVars } from '../../color-theme/color-theme';
 import { defineElementBookElement } from '../define-book-element';
 import { ElementBookExampleControls } from './element-book-example-controls.element';
 import { ElementBookExampleViewer } from './element-book-example-viewer.element';
+import { ElementBookPageControls } from './element-book-page-controls.element';
 export const ElementBookPageExamples = defineElementBookElement()({
     tagName: 'element-book-page-examples',
     styles: css `
         :host {
+            display: flex;
+            flex-direction: column;
+            gap: 24px;
+        }
+
+        .examples-wrapper {
             display: flex;
             gap: 32px;
             flex-wrap: wrap;
         }
 
+        .error {
+            color: red;
+            font-weight: bold;
+        }
+
         .individual-example-wrapper {
             display: flex;
             flex-direction: column;
@@ -28,14 +42,33 @@ export const ElementBookPageExamples = defineElementBookElement()({
             visibility: hidden;
         }
     `,
-    renderCallback({ inputs }) {
+    stateInit: {
+        unset: unsetInternalState,
+    },
+    renderCallback({ inputs, state, updateState }) {
+        if (state.unset === unsetInternalState) {
+            const newState = mapObjectValues(inputs.page.controls, (key, value) => {
+                return value.initValue;
+            });
+            updateState({
+                unset: undefined,
+                ...newState,
+            });
+        }
         const examples = inputs.page.examples;
-        const allControlsHidden = examples.every((example) => example.hideControls);
+        const allControlsHidden = Object.values(examples).every((example) => 'hideExampleControls' in example && example.hideExampleControls);
         /**
          * Use the repeat directive here, instead of just a map, so that lit doesn't accidentally
          * keep state cached between element book pages.
          */
-        return repeat(examples, (example) => inputs.parentBreadcrumbs.concat(example.title).join('>'), (example) => {
+        const examplesTemplate = repeat(Object.values(examples), (example) => inputs.parentBreadcrumbs
+            .concat(example instanceof Error ? example.message : example.title)
+            .join('>'), (example) => {
+            if (example instanceof Error) {
+                return html `
+                        <p class="error">${example.message}</p>
+                    `;
+            }
             const exampleBreadcrumbs = inputs.parentBreadcrumbs.concat(example.title);
             return html `
                     <div class="individual-example-wrapper">
@@ -47,7 +80,7 @@ export const ElementBookPageExamples = defineElementBookElement()({
                  * every control so that they take up space, but just hide
                  * them.
                  */
-                'hidden-controls': !!example.hideControls,
+                'hidden-controls': !!example.hideExampleControls,
             })}
                                     ${assign(ElementBookExampleControls, {
                 example,
@@ -58,10 +91,26 @@ export const ElementBookPageExamples = defineElementBookElement()({
                             ${assign(ElementBookExampleViewer, {
                 example,
                 breadcrumbs: exampleBreadcrumbs,
+                currentPageControls: state,
             })}
                         ></${ElementBookExampleViewer}>
                     </div>
                 `;
         });
+        return html `
+            <${ElementBookPageControls}
+                ${assign(ElementBookPageControls, {
+            config: inputs.page.controls,
+            currentValues: state,
+        })}
+                ${listen(ElementBookPageControls.events.controlValueChange, (event) => {
+            updateState({ [event.detail.name]: event.detail.value });
+        })}
+            ></${ElementBookPageControls}>
+            <section class="examples-wrapper">${examplesTemplate}</section>
+        `;
+    },
+    options: {
+        allowPolymorphicState: true,
     },
 });

package/dist/ui/events/change-route.event.d.ts

@@ -1 +1 @@
-export declare const ChangeRouteEvent: import("element-vir").DefinedTypedEvent<"change-page", Partial<Required<Readonly<import("spa-router-vir").FullRoute<import("../../routing/element-book-routing").ValidElementBookPaths, undefined, undefined>>>>>;
+export declare const ChangeRouteEvent: import("element-vir").DefinedTypedEvent<"change-route", Partial<Required<Readonly<import("spa-router-vir").FullRoute<import("../../routing/element-book-routing").ValidElementBookPaths, Record<string, string> | undefined, undefined>>>>>;

package/dist/ui/events/change-route.event.js

@@ -1,2 +1,2 @@
 import { defineTypedEvent } from 'element-vir';
-export const ChangeRouteEvent = defineTypedEvent()('change-page');
+export const ChangeRouteEvent = defineTypedEvent()('change-route');

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-book",
-    "version": "1.0.2",
+    "version": "2.0.0",
     "keywords": [
         "book",
         "design system",
@@ -38,16 +38,16 @@
         "test:types": "tsc --noEmit"
     },
     "dependencies": {
-        "@augment-vir/common": "^13.4.0",
+        "@augment-vir/common": "^14.2.0",
         "@electrovir/icon-element": "^0.0.2",
         "colorjs.io": "^0.4.3",
-        "element-vir": "^12.4.6",
+        "element-vir": "^12.5.2",
         "lit-css-vars": "^2.0.2",
         "spa-router-vir": "^2.1.0",
         "typed-event-target": "^1.2.0"
     },
     "devDependencies": {
-        "@augment-vir/browser-testing": "^13.4.0",
+        "@augment-vir/browser-testing": "^14.2.0",
         "@open-wc/testing": "^3.1.8",
         "@types/mocha": "^10.0.1",
         "@web/dev-server-esbuild": "^0.4.1",
@@ -56,7 +56,7 @@
         "@web/test-runner-playwright": "^0.10.0",
         "@web/test-runner-visual-regression": "^0.8.0",
         "istanbul-smart-text-reporter": "^1.1.1",
-        "type-fest": "^3.10.0",
+        "type-fest": "^3.11.0",
         "typescript": "^5.0.4"
     }
 }