element-book 23.4.2 → 24.0.0

package/README.md

@@ -10,8 +10,8 @@ npm i element-book
 
 ## 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.
+-   **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
 

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

@@ -25,7 +25,7 @@ export type BookPage<GlobalValuesType extends GlobalValues = {}, ParentPage exte
  *
  * @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'> & {
+export type BookPageExampleRenderParams<GlobalValuesType extends GlobalValues, ControlsInit extends BookPageControlsInitBase, State extends PropertyInitMapBase> = Pick<RenderParams<any, any, State, any, any, any, any>, 'state' | 'updateState'> & {
     controls: ControlsToValues<ControlsInit> & GlobalValuesType;
 };
 /**
@@ -33,12 +33,15 @@ export type BookPageExampleRenderParams<GlobalValuesType extends GlobalValues, C
  *
  * @category Internal
  */
-export type BookElementExample<GlobalValuesType extends GlobalValues = {}, ControlsInit extends BookPageControlsInitBase = {}, StateInit extends PropertyInitMapBase = {}> = Overwrite<BaseBookEntry, {
+export type BookElementExample<GlobalValuesType extends GlobalValues = {}, ControlsInit extends BookPageControlsInitBase = {}, State extends PropertyInitMapBase = {}> = Overwrite<BaseBookEntry, {
     parent: BookPage | undefined;
     entryType: BookEntryType.ElementExample;
 } & {
-    /** Initialize the state for this example. */
-    stateInitStatic?: StateInit | undefined;
+    /**
+     * Initialize the state for this example. This is only called once, before the first render
+     * of the example.
+     */
+    state?: (() => State) | undefined;
     /** Specify which events this example should intercept (so the user can see them). */
     showEvents?: ReadonlyArray<string | TypedEvent> | undefined;
     /**
@@ -47,7 +50,7 @@ export type BookElementExample<GlobalValuesType extends GlobalValues = {}, Contr
      */
     styles?: CSSResult | undefined;
     /** Render the example. */
-    render: (renderParams: BookPageExampleRenderParams<GlobalValuesType, ControlsInit, StateInit>) => HtmlInterpolation;
+    render: (renderParams: BookPageExampleRenderParams<GlobalValuesType, ControlsInit, State>) => HtmlInterpolation;
 }>;
 /**
  * The properties that are necessary to initialize an element example. Missing properties will be
@@ -55,4 +58,4 @@ export type BookElementExample<GlobalValuesType extends GlobalValues = {}, Contr
  *
  * @category Internal
  */
-export type BookElementExampleInit<GlobalValuesType extends GlobalValues, Controls extends BookPageControlsInitBase, StateInit extends PropertyInitMapBase> = SetOptionalAndNullable<Omit<BookElementExample<GlobalValuesType, Controls, StateInit>, 'entryType' | 'parent' | 'errors'>, 'descriptionParagraphs'>;
+export type BookElementExampleInit<GlobalValuesType extends GlobalValues, Controls extends BookPageControlsInitBase, State extends PropertyInitMapBase> = SetOptionalAndNullable<Omit<BookElementExample<GlobalValuesType, Controls, State>, 'entryType' | 'parent' | 'errors'>, 'descriptionParagraphs'>;

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

@@ -10,7 +10,7 @@ import { BookElementExampleInit, BookPage } from './book-page.js';
  *
  * @category Internal
  */
-export type DefineExampleCallback<GlobalValuesType extends GlobalValues = {}, ControlsInit extends BookPageControlsInitBase = BookPageControlsInitBase> = <StateInit extends PropertyInitMapBase>(exampleInit: BookElementExampleInit<GlobalValuesType, ControlsInit, StateInit>) => void;
+export type DefineExampleCallback<GlobalValuesType extends GlobalValues = {}, ControlsInit extends BookPageControlsInitBase = BookPageControlsInitBase> = <State extends PropertyInitMapBase>(exampleInit: BookElementExampleInit<GlobalValuesType, ControlsInit, State>) => void;
 /**
  * Used for `defineExamples` in a book page's init.
  *

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

@@ -1,4 +1,4 @@
-import { FullRoute } from 'spa-router-vir';
+import { FullSpaRoute } from 'spa-router-vir';
 /**
  * Top level routes supported by the element-book app.
  *
@@ -19,7 +19,7 @@ export type ValidBookPaths = [BookMainRoute.Search, string] | [BookMainRoute.Boo
  *
  * @category Internal
  */
-export type BookFullRoute = Required<Readonly<FullRoute<ValidBookPaths, undefined, undefined>>>;
+export type BookFullRoute = Readonly<FullSpaRoute<ValidBookPaths, undefined, undefined>>;
 /**
  * Extract the current search query from the current route paths.
  *

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

@@ -1,2 +1,2 @@
 export type BookTagName = `book-${string}`;
-export declare const defineBookElement: <Inputs extends {}>() => <const TagName extends `book-${string}`, StateInit extends {}, EventsInit extends {}, const HostClassKeys extends `${TagName}-${string}` = `${TagName}-`, const CssVarKeys extends `${TagName}-${string}` = `${TagName}-`, const SlotNames extends ReadonlyArray<string> = readonly []>(inputs: import("element-vir").VerifiedElementInit<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>) => import("element-vir").DeclarativeElementDefinition<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>, defineBookElementNoInputs: <const TagName extends `book-${string}`, Inputs extends {}, StateInit extends {}, EventsInit extends {}, const HostClassKeys extends `${TagName}-${string}` = `${TagName}-`, const CssVarKeys extends `${TagName}-${string}` = `${TagName}-`, const SlotNames extends ReadonlyArray<string> = readonly []>(inputs: import("element-vir").VerifiedElementNoInputsInit<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>) => import("element-vir").DeclarativeElementDefinition<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
+export declare const defineBookElement: <Inputs extends {}>(...errorParams: import("element-vir").DeclarativeElementInputErrorParams<Inputs>) => <const TagName extends `book-${string}`, State extends {}, EventsInit extends {}, const HostClassKeys extends `${TagName}-${string}` = `${TagName}-`, const CssVarKeys extends `${TagName}-${string}` = `${TagName}-`, const SlotNames extends ReadonlyArray<string> = readonly []>(inputs: import("element-vir").DeclarativeElementInit<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames>) => import("element-vir").DeclarativeElementDefinition<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames>, defineBookElementNoInputs: <const TagName extends `book-${string}`, Inputs extends {}, State extends {}, EventsInit extends {}, const HostClassKeys extends `${TagName}-${string}` = `${TagName}-`, const CssVarKeys extends `${TagName}-${string}` = `${TagName}-`, const SlotNames extends ReadonlyArray<string> = readonly []>(inputs: import("element-vir").DeclarativeElementInit<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames>) => import("element-vir").DeclarativeElementDefinition<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;

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

@@ -20,7 +20,7 @@ export type ColorThemeState = {
  * @category Main
  */
 export declare const ElementBookApp: import("element-vir").DeclarativeElementDefinition<"element-book-app", ElementBookConfig, {
-    currentRoute: Readonly<Required<Readonly<import("spa-router-vir").FullRoute<import("../../../routing/book-routing.js").ValidBookPaths, undefined, undefined>>>>;
+    currentRoute: Readonly<Readonly<Required<import("spa-router-vir").SpaRoute<import("../../../routing/book-routing.js").ValidBookPaths, undefined, undefined>>>>;
     router: undefined | BookRouter;
     loading: boolean;
     colors: ColorThemeState;

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

@@ -24,20 +24,22 @@ import { getCurrentNodes } from './get-current-nodes.js';
  */
 export const ElementBookApp = defineElement()({
     tagName: 'element-book-app',
+    state() {
+        return {
+            currentRoute: defaultBookFullRoute,
+            router: undefined,
+            loading: true,
+            colors: {
+                config: undefined,
+                theme: createTheme(undefined),
+            },
+            treeBasedControls: undefined,
+            originalWindowTitle: undefined,
+        };
+    },
     events: {
         pathUpdate: defineElementEvent(),
     },
-    stateInitStatic: {
-        currentRoute: defaultBookFullRoute,
-        router: undefined,
-        loading: true,
-        colors: {
-            config: undefined,
-            theme: createTheme(undefined),
-        },
-        treeBasedControls: undefined,
-        originalWindowTitle: undefined,
-    },
     styles: css `
         :host {
             display: flex;

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

@@ -5,8 +5,10 @@ import { BookError } from '../../common/book-error.element.js';
 import { defineBookElement } from '../../define-book-element.js';
 export const BookElementExampleViewer = defineBookElement()({
     tagName: 'book-element-example-viewer',
-    stateInitStatic: {
-        isUnset: unsetInternalState,
+    state() {
+        return {
+            isUnset: unsetInternalState,
+        };
     },
     render({ state, inputs, updateState }) {
         try {
@@ -23,7 +25,7 @@ export const BookElementExampleViewer = defineBookElement()({
             if (state.isUnset === unsetInternalState) {
                 updateState({
                     isUnset: undefined,
-                    ...inputs.elementExampleNode.entry.stateInitStatic,
+                    ...inputs.elementExampleNode.entry.state?.(),
                 });
             }
             const output = inputs.elementExampleNode.entry.render({

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

@@ -7,6 +7,11 @@ import { BookBreadcrumbsBar } from '../book-breadcrumbs-bar.element.js';
 import { createNodeTemplates } from './create-node-templates.js';
 export const BookEntryDisplay = defineBookElement()({
     tagName: 'book-entry-display',
+    state() {
+        return {
+            lastElement: undefined,
+        };
+    },
     styles: css `
         :host {
             display: flex;
@@ -67,9 +72,6 @@ export const BookEntryDisplay = defineBookElement()({
     events: {
         loadingRender: defineElementEvent(),
     },
-    stateInitStatic: {
-        lastElement: undefined,
-    },
     render: ({ inputs, dispatch, events, state, updateState }) => {
         const currentSearch = extractSearchQuery(inputs.currentRoute.paths);
         const entryTemplates = createNodeTemplates({

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-book",
-    "version": "23.4.2",
+    "version": "24.0.0",
     "keywords": [
         "book",
         "design system",
@@ -41,28 +41,28 @@
         "test:docs": "virmator docs check"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.9.2",
-        "@augment-vir/common": "^31.9.2",
-        "@augment-vir/web": "^31.9.2",
+        "@augment-vir/assert": "^31.10.0",
+        "@augment-vir/common": "^31.10.0",
+        "@augment-vir/web": "^31.10.0",
         "colorjs.io": "0.5.2",
         "lit-css-vars": "^3.0.11",
-        "spa-router-vir": "^4.0.8",
-        "typed-event-target": "^4.0.2",
-        "vira": "^23.4.2"
+        "spa-router-vir": "^5.3.1",
+        "typed-event-target": "^4.0.3",
+        "vira": "^24.0.0"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.9.2",
+        "@augment-vir/test": "^31.10.0",
         "@web/dev-server-esbuild": "^1.0.4",
         "@web/test-runner": "^0.20.0",
         "@web/test-runner-commands": "^0.9.0",
         "@web/test-runner-playwright": "^0.11.0",
         "@web/test-runner-visual-regression": "^0.10.0",
-        "element-vir": "^23.4.2",
+        "element-vir": "^24.0.0",
         "istanbul-smart-text-reporter": "^1.1.5",
         "markdown-code-example-inserter": "^3.0.3",
-        "type-fest": "^4.35.0",
+        "type-fest": "^4.37.0",
         "typedoc": "^0.27.9",
-        "typescript": "5.7.3"
+        "typescript": "5.8.2"
     },
     "peerDependencies": {
         "element-vir": ">=17"