element-book 7.0.7 → 8.0.0

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

@@ -1,14 +1,15 @@
 import { Overwrite, RequireNonVoid, SetOptionalAndNullable } from '@augment-vir/common';
 import { PropertyInitMapBase, RenderParams, TypedEvent } from 'element-vir';
 import { CSSResult } from 'lit';
+import { GlobalValues } from '../../../ui/elements/element-book-app/element-book-config';
 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 BookPageExampleRenderParams<GlobalValuesType extends GlobalValues, ControlsInit extends BookPageControlsInitBase, StateInit extends PropertyInitMapBase> = Pick<RenderParams<any, any, StateInit, any, any, any>, 'state' | 'updateState'> & {
+    controls: ControlsToValues<ControlsInit> & GlobalValuesType;
 };
-export type BookElementExample<ControlsInit extends BookPageControlsInitBase = {}, StateInit extends PropertyInitMapBase = {}, RenderOutput = unknown> = Overwrite<BaseBookEntry, {
+export type BookElementExample<GlobalValuesType extends GlobalValues = {}, ControlsInit extends BookPageControlsInitBase = {}, StateInit extends PropertyInitMapBase = {}, RenderOutput = unknown> = Overwrite<BaseBookEntry, {
     parent: BookPage | undefined;
     entryType: BookEntryTypeEnum.ElementExample;
 } & {
@@ -22,10 +23,10 @@ export type BookElementExample<ControlsInit extends BookPageControlsInitBase = {
      */
     styles?: CSSResult | undefined;
     /** Render the example. */
-    renderCallback: RequireNonVoid<RenderOutput, (renderParams: BookPageExampleRenderParams<ControlsInit, StateInit>) => RenderOutput, 'renderCallback is missing a return statement'>;
+    renderCallback: RequireNonVoid<RenderOutput, (renderParams: BookPageExampleRenderParams<GlobalValuesType, 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> = SetOptionalAndNullable<Omit<BookElementExample<Controls, StateInit, RenderOutput>, 'entryType' | 'parent' | 'errors'>, 'descriptionParagraphs'>;
+export type BookElementExampleInit<GlobalValuesType extends GlobalValues, Controls extends BookPageControlsInitBase, StateInit extends PropertyInitMapBase, RenderOutput> = SetOptionalAndNullable<Omit<BookElementExample<GlobalValuesType, Controls, StateInit, RenderOutput>, 'entryType' | 'parent' | 'errors'>, 'descriptionParagraphs'>;

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

@@ -1,9 +1,10 @@
 import { Overwrite } from '@augment-vir/common';
+import { GlobalValues } from '../../../ui/elements/element-book-app/element-book-config';
 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, {
+export type BookPage<GlobalValuesType extends GlobalValues = {}, ParentPage extends BookPage | undefined = any, ControlsInit extends BookPageControlsInitBase = BookPageControlsInitBase> = Overwrite<BaseBookEntry, {
     parent: ParentPage;
     entryType: BookEntryTypeEnum.Page;
 }> & {

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

@@ -1,3 +1,4 @@
+import { GlobalValues } from '../../../ui/elements/element-book-app/element-book-config';
 import { BookTreeNode } from '../../book-tree/book-tree-node';
 import { BookPageControlsValues } from './book-page-controls';
 export type ControlsWrapper = {
@@ -9,4 +10,4 @@ export type CurrentControls = {
 };
 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;
+export declare function createControlsFromTree(node: BookTreeNode, globalControls: GlobalValues): CurrentControls;

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

@@ -43,7 +43,7 @@ export function createNewCurrentControls(currentControls, fullUrlBreadcrumbs, ne
     internalTraverseCurrentControls(newCurrentControls, fullUrlBreadcrumbs, newValues);
     return newCurrentControls;
 }
-export function createControlsFromTree(node) {
+export function createControlsFromTree(node, globalControls) {
     const currentControls = mapObjectValues(node.children, (childName, child) => {
         if (!isBookTreeNode(child, BookEntryTypeEnum.Page)) {
             return {
@@ -52,10 +52,13 @@ export function createControlsFromTree(node) {
             };
         }
         return {
-            children: createControlsFromTree(child),
-            controls: mapObjectValues(child.entry.controls, (name, setup) => {
-                return setup.initValue;
-            }),
+            children: createControlsFromTree(child, {}),
+            controls: {
+                ...globalControls,
+                ...mapObjectValues(child.entry.controls, (name, setup) => {
+                    return setup.initValue;
+                }),
+            },
         };
     });
     return currentControls;

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

@@ -1,18 +1,27 @@
 import { SetOptionalAndNullable } from '@augment-vir/common';
 import { PropertyInitMapBase } from 'element-vir';
+import { GlobalValues } from '../../../ui/elements/element-book-app/element-book-config';
 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 DefineExampleCallback<ControlsInit extends BookPageControlsInitBase = BookPageControlsInitBase> = <StateInit extends PropertyInitMapBase, RenderOutput>(exampleInit: BookElementExampleInit<ControlsInit, StateInit, RenderOutput>) => void;
-export type ElementExamplesDefiner<ControlsInit extends BookPageControlsInitBase = BookPageControlsInitBase> = (params: {
-    defineExample: DefineExampleCallback<ControlsInit>;
+export type DefineExampleCallback<GlobalValuesType extends GlobalValues = {}, ControlsInit extends BookPageControlsInitBase = BookPageControlsInitBase> = <StateInit extends PropertyInitMapBase, RenderOutput>(exampleInit: BookElementExampleInit<GlobalValuesType, ControlsInit, StateInit, RenderOutput>) => void;
+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, 
 /** 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> = SetOptionalAndNullable<Omit<BookPage<ParentPage, CurrentControlsInit>, 'entryType' | 'elementExamples' | 'errors'>, 'controls' | 'descriptionParagraphs'> & {
-    elementExamplesCallback?: ElementExamplesDefiner<CollapseControlsInit<ParentPage, CurrentControlsInit>> | undefined;
+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, 
+/** 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> : {} : {});
+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;
 };
-export declare function defineBookPage<const ParentPage extends BookPage | undefined, const ControlsInit extends BookPageControlsInitBase = {}>(pageInit: BookPageInit<ParentPage, ControlsInit>): BookPage<ParentPage, ControlsInit>;
+/**
+ * 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.
+ */
+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>;
+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,6 +1,15 @@
 import { isTruthy } from '@augment-vir/common';
 import { BookEntryTypeEnum } from '../book-entry-type';
 import { titleToUrlBreadcrumb } from '../url-breadcrumbs';
+/**
+ * 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.
+ */
+export function defineBookPageWithGlobals() {
+    return (pageInit) => {
+        return defineBookPage(pageInit);
+    };
+}
 export function defineBookPage(pageInit) {
     const page = {
         ...pageInit,

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from './data/book-entry/book-element-example/book-element-example';
+export * from './data/book-entry/book-entry';
+export * from './data/book-entry/book-entry-type';
 export * from './data/book-entry/book-page/book-page';
 export * from './data/book-entry/book-page/book-page-controls';
 export * from './data/book-entry/book-page/define-book-page';

package/dist/index.js

@@ -1,4 +1,6 @@
 export * from './data/book-entry/book-element-example/book-element-example';
+export * from './data/book-entry/book-entry';
+export * from './data/book-entry/book-entry-type';
 export * from './data/book-entry/book-page/book-page';
 export * from './data/book-entry/book-page/book-page-controls';
 export * from './data/book-entry/book-page/define-book-page';

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

@@ -1,7 +1,7 @@
 import { CurrentControls } from '../../../data/book-entry/book-page/current-controls';
 import { ColorTheme } from '../../color-theme/color-theme';
 import { ThemeConfig } from '../../color-theme/create-color-theme';
-import { ElementBookConfig } from './element-book-config';
+import { ElementBookConfig, GlobalValues } from './element-book-config';
 type ColorThemeState = {
     config: ThemeConfig | undefined;
     theme: ColorTheme;
@@ -11,7 +11,8 @@ export declare const ElementBookApp: import("element-vir").DeclarativeElementDef
     router: Readonly<import("spa-router-vir").SpaRouter<import("../../../routing/book-routing").ValidBookPaths, Record<string, string> | undefined, undefined>> | undefined;
     colors: ColorThemeState;
     treeBasedCurrentControls: {
-        trigger: ElementBookConfig['entries'];
+        entries: ElementBookConfig['entries'];
+        globalControls: GlobalValues;
         currentControls: CurrentControls;
     } | undefined;
 }, {

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

@@ -132,11 +132,13 @@ export const ElementBookApp = defineElement()({
                 debug,
             });
             if (!state.treeBasedCurrentControls ||
-                state.treeBasedCurrentControls.trigger !== inputs.entries) {
+                state.treeBasedCurrentControls.entries !== inputs.entries ||
+                state.treeBasedCurrentControls.globalControls !== inputs.globalControls) {
                 updateState({
                     treeBasedCurrentControls: {
-                        trigger: inputs.entries,
-                        currentControls: createControlsFromTree(originalTree.tree),
+                        entries: inputs.entries,
+                        globalControls: inputs.globalControls ?? {},
+                        currentControls: createControlsFromTree(originalTree.tree, inputs.globalControls ?? {}),
                     },
                 });
             }

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

@@ -5,6 +5,7 @@ export type ElementBookConfig = {
     /** All element-book entries in order. */
     entries: ReadonlyArray<BookEntry>;
 } & PartialAndUndefined<OptionalConfig>;
+export type GlobalValues = Readonly<Record<string, unknown>>;
 type OptionalConfig = {
     /** The base theme color from which all other element-book colors will be generated from. */
     themeColor: string;
@@ -12,6 +13,7 @@ type OptionalConfig = {
     everythingTitle: string;
     everythingDescriptionParagraphs: ReadonlyArray<string>;
     debug: boolean;
+    globalControls: GlobalValues;
 } & RequireExactlyOne<{
     /**
      * Set this internal router config if element-book is intended to be the current website's

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-book",
-    "version": "7.0.7",
+    "version": "8.0.0",
     "keywords": [
         "book",
         "design system",
@@ -41,13 +41,13 @@
     "dependencies": {
         "@augment-vir/browser": "^15.3.0",
         "@augment-vir/common": "^15.3.0",
-        "colorjs.io": "0.4.3",
+        "colorjs.io": "0.4.5",
         "element-vir": "^14.0.3",
         "lit-css-vars": "^2.0.3",
         "object-shape-tester": "^0.3.0",
-        "spa-router-vir": "^2.1.0",
-        "typed-event-target": "^1.2.1",
-        "vira": "^0.5.1"
+        "spa-router-vir": "^2.1.1",
+        "typed-event-target": "^1.3.0",
+        "vira": "^0.6.0"
     },
     "devDependencies": {
         "@augment-vir/browser-testing": "^15.3.0",
@@ -61,6 +61,6 @@
         "@web/test-runner-visual-regression": "^0.8.0",
         "istanbul-smart-text-reporter": "^1.1.2",
         "type-fest": "^3.12.0",
-        "typescript": "^5.1.3"
+        "typescript": "^5.1.6"
     }
 }