element-book 26.12.0 → 26.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-book",
-    "version": "26.12.0",
+    "version": "26.12.1",
     "keywords": [
         "book",
         "design system",
@@ -29,9 +29,9 @@
     },
     "sideEffects": false,
     "type": "module",
-    "main": "src/index.ts",
-    "module": "src/index.ts",
-    "types": "src/index.ts",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
     "scripts": {
         "build": "npm run docs",
         "compile": "virmator compile",
@@ -56,7 +56,7 @@
         "@web/test-runner-commands": "^0.9.0",
         "@web/test-runner-playwright": "^0.11.1",
         "@web/test-runner-visual-regression": "^0.10.0",
-        "element-vir": "^26.12.0",
+        "element-vir": "^26.12.1",
         "istanbul-smart-text-reporter": "^1.1.5",
         "markdown-code-example-inserter": "^3.0.3",
         "type-fest": "^5.3.1",

package/src/data/book-entry/book-entry.ts

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

package/src/data/book-entry/book-page/book-page-controls.ts

@@ -1,159 +0,0 @@
-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 BookPageControlType.Dropdown
-    ? {
-          options: string[];
-      }
-    : EmptyObject);
-
-/**
- * Initialization options for an element-book page control.
- *
- * @category Internal
- */
-export type BookPageControlInit<ControlType extends BookPageControlType> = Omit<
-    BookPageControl<ControlType>,
-    // 'controlName' will be inserted later by the page
-    'controlName'
->;
-
-/**
- * Checks and type guards that the input page control init is of the given type.
- *
- * @internal
- */
-export function isControlInitType<const SpecificControlType extends BookPageControlType>(
-    controlInit: BookPageControlInit<any>,
-    specificType: SpecificControlType,
-): controlInit is BookPageControlInit<SpecificControlType> {
-    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<const ControlType extends BookPageControlType>(
-    controlInit: BookPageControlInit<ControlType>,
-) {
-    return controlInit;
-}
-
-/**
- * Maps an object of user-defined controls to their initial values.
- *
- * @category Internal
- */
-export type ControlsToValues<ControlsInit extends BookPageControlsInitBase> = {
-    [ControlName in keyof ControlsInit]: ControlsInit[ControlName]['initValue'];
-};
-
-/**
- * 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>;
-
-/**
- * All the supported page control types. One of these must be chosen when defining a page control.
- *
- * @category Main
- */
-export enum BookPageControlType {
-    Checkbox = 'checkbox',
-    Color = 'color',
-    Dropdown = 'dropdown',
-    /** Hidden controls allow any values but they aren't displayed to the user for editing. */
-    Hidden = 'hidden',
-    Number = 'number',
-    Text = 'text',
-}
-
-const anySymbol = Symbol('any-type');
-
-/**
- * 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 as any,
-    [BookPageControlType.Number]: 0,
-    [BookPageControlType.Text]: '',
-} satisfies Readonly<Record<BookPageControlType, any>>;
-
-/**
- * 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 function checkControls(
-    controlsInit: BookPageControlsInitBase | undefined,
-    pageName: string,
-): Error[] {
-    if (!controlsInit) {
-        return [];
-    }
-
-    const errors: Error[] = [];
-
-    Object.entries(controlsInit).forEach(
-        ([
-            controlName,
-            controlEntry,
-        ]) => {
-            const expectedInitDefault = controlValueTypes[controlEntry.controlType];
-
-            if (expectedInitDefault === anySymbol) {
-                return;
-            }
-
-            if (typeof expectedInitDefault !== typeof controlEntry.initValue) {
-                errors.push(
-                    new Error(
-                        `Control '${controlName}' in page '${pageName}' has invalid initValue '${
-                            controlEntry.initValue
-                        }': expected initValue of type ${typeof expectedInitDefault} because the control is of type ${
-                            controlEntry.controlType
-                        }.`,
-                    ),
-                );
-            }
-            if (!controlName) {
-                errors.push(new Error(`'${pageName}' cannot have an empty control name.`));
-            }
-        },
-    );
-
-    return errors;
-}

package/src/data/book-entry/book-page/book-page.ts

@@ -1,110 +0,0 @@
-/* eslint-disable @typescript-eslint/no-empty-object-type */
-
-import {
-    type Overwrite,
-    type PartialWithUndefined,
-    type SetOptionalAndNullable,
-} from '@augment-vir/common';
-import {
-    type CSSResult,
-    type HtmlInterpolation,
-    type PropertyInitMapBase,
-    type RenderParams,
-    type TypedEvent,
-} from 'element-vir';
-import {type GlobalValues} from '../../../ui/elements/element-book-app/global-values.js';
-import {type BaseBookEntry} from '../base-book-entry.js';
-import {type BookEntryType} from '../book-entry-type.js';
-import {type BookPageControlsInitBase, type ControlsToValues} from './book-page-controls.js';
-
-/**
- * An individual element-book page.
- *
- * @category Type
- */
-export type BookPage<
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    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: BookEntryType.Page;
-    }
-> & {
-    controls: ControlsInit;
-    elementExamples: Record<string, BookElementExample>;
-    useVerticalExamples: boolean;
-};
-
-/**
- * All parameters required for rendering an element-book page.
- *
- * @category Internal
- */
-export type BookPageExampleRenderParams<
-    GlobalValuesType extends GlobalValues,
-    ControlsInit extends BookPageControlsInitBase,
-    State extends PropertyInitMapBase,
-> = Pick<RenderParams<any, any, State, any, 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 = {},
-    State extends PropertyInitMapBase = {},
-> = Overwrite<
-    BaseBookEntry,
-    {
-        parent: BookPage | undefined;
-        entryType: BookEntryType.ElementExample;
-        isVertical: boolean;
-        /** Render the example. */
-        render: (
-            renderParams: BookPageExampleRenderParams<GlobalValuesType, ControlsInit, State>,
-        ) => HtmlInterpolation;
-    } & PartialWithUndefined<{
-        /**
-         * Initialize the state for this example. This is only called once, before the first render
-         * of the example.
-         */
-        state: () => State;
-        /** Specify which events this example should intercept (so the user can see them). */
-        showEvents: ReadonlyArray<string | TypedEvent>;
-        /**
-         * Style the element example. You can even use the :host selector to style this specific
-         * example's wrapper element!
-         */
-        styles: CSSResult;
-    }>
->;
-
-/**
- * The properties that are necessary to initialize an element example. Missing properties will be
- * filled in by the parent.
- *
- * @category Internal
- */
-export type BookElementExampleInit<
-    GlobalValuesType extends GlobalValues,
-    Controls extends BookPageControlsInitBase,
-    State extends PropertyInitMapBase,
-> = SetOptionalAndNullable<
-    Omit<
-        BookElementExample<GlobalValuesType, Controls, State>,
-        'entryType' | 'parent' | 'errors' | 'isVertical'
-    >,
-    'descriptionParagraphs'
->;

package/src/data/book-entry/book-page/controls-wrapper.ts

@@ -1,119 +0,0 @@
-import {type PartialWithUndefined, mapObjectValues} from '@augment-vir/common';
-import {type BookTreeNode} from '../../book-tree/book-tree-node.js';
-import {isBookTreeNode} from '../../book-tree/book-tree.js';
-import {BookEntryType} from '../book-entry-type.js';
-import {type 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 function traverseControls(
-    controlsWrapper: ControlsWrapper,
-    fullUrlBreadcrumbs: ReadonlyArray<string>,
-): BookPageControlsValues {
-    return traverseAndInsertNewControls(
-        controlsWrapper,
-        [
-            /** Empty string represents the breadcrumb for the root node */
-            '',
-            ...fullUrlBreadcrumbs,
-        ],
-        undefined,
-    );
-}
-
-function traverseAndInsertNewControls(
-    controlsWrapper: ControlsWrapper,
-    urlBreadcrumbs: ReadonlyArray<string>,
-    newValues: BookPageControlsValues | undefined,
-): BookPageControlsValues {
-    const nextBreadcrumbs = urlBreadcrumbs.slice(1);
-    const nextBreadcrumb = nextBreadcrumbs[0];
-    /** If we're at the end of the breadcrumbs, then it's time to insert the new controls. */
-    if (!nextBreadcrumb && newValues) {
-        controlsWrapper.controls = newValues;
-    }
-
-    const childControlsWrapper: ControlsWrapper | undefined =
-        controlsWrapper.children[nextBreadcrumb || ''];
-
-    const childrenControls =
-        childControlsWrapper &&
-        traverseAndInsertNewControls(childControlsWrapper, nextBreadcrumbs, newValues);
-
-    const allControls = {
-        ...controlsWrapper.controls,
-        ...childrenControls,
-    };
-
-    return allControls;
-}
-
-/**
- * Add new controls at the given breadcrumbs.
- *
- * @category Internal
- */
-export function createNewControls(
-    controlsWrapper: Readonly<ControlsWrapper>,
-    breadcrumbsForNewValue: ReadonlyArray<string>,
-    newValues: BookPageControlsValues,
-): ControlsWrapper {
-    const newControls = {...controlsWrapper};
-
-    traverseAndInsertNewControls(
-        newControls,
-        [
-            /** Empty string represents the breadcrumb for the root node */
-            '',
-            ...breadcrumbsForNewValue,
-        ],
-        newValues,
-    );
-
-    return newControls;
-}
-
-/**
- * Add new controls from the given tree node.
- *
- * @category Internal
- */
-export function updateTreeControls(
-    node: BookTreeNode,
-    existingControls: PartialWithUndefined<ControlsWrapper> | undefined,
-): ControlsWrapper {
-    const controls =
-        existingControls?.controls ||
-        (isBookTreeNode(node, BookEntryType.Page)
-            ? mapObjectValues(node.entry.controls, (name, setup) => {
-                  return setup.initValue;
-              })
-            : {});
-
-    const controlsWrapper: ControlsWrapper = {
-        children: mapObjectValues(node.children, (childName, childTreeNode): ControlsWrapper => {
-            return updateTreeControls(
-                childTreeNode,
-                existingControls?.children?.[childTreeNode.urlBreadcrumb],
-            );
-        }),
-        controls,
-    };
-
-    return controlsWrapper;
-}

package/src/data/book-entry/book-page/define-book-page.ts

@@ -1,171 +0,0 @@
-/* eslint-disable @typescript-eslint/no-empty-object-type */
-
-import {check} from '@augment-vir/assert';
-import {type SetOptionalAndNullable, type Values} from '@augment-vir/common';
-import {type PropertyInitMapBase} from 'element-vir';
-import {type EmptyObject} from 'type-fest';
-import {type GlobalValues} from '../../../ui/elements/element-book-app/global-values.js';
-import {type InfiniteRecursionLimiter} from '../../../util/type.js';
-import {BookEntryType} from '../book-entry-type.js';
-import {titleToUrlBreadcrumb} from '../url-breadcrumbs.js';
-import {type BookPageControlsInitBase} from './book-page-controls.js';
-import {type BookElementExample, type BookElementExampleInit, type 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,
-> = <State extends PropertyInitMapBase>(
-    exampleInit: BookElementExampleInit<GlobalValuesType, ControlsInit, State>,
-) => 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;
-
-/**
- * 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<
-              // eslint-disable-next-line @typescript-eslint/no-unused-vars
-              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,
-              // eslint-disable-next-line @typescript-eslint/no-unused-vars
-              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' | 'useVerticalExamples'
-> & {
-    defineExamples?:
-        | ElementExamplesDefiner<
-              CollapseGlobalValuesType<ParentPage, GlobalValuesType>,
-              CollapseControlsInit<ParentPage, CurrentControlsInit>
-          >
-        | undefined;
-};
-
-/**
- * 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<const GlobalValuesType extends GlobalValues = {}>() {
-    return <
-        const ParentPage extends BookPage | undefined = undefined,
-        const ControlsInit extends BookPageControlsInitBase = {},
-    >(
-        pageInit: BookPageInit<GlobalValuesType, ParentPage, ControlsInit>,
-    ): BookPage<GlobalValuesType, ParentPage, ControlsInit> => {
-        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<
-    const GlobalValuesType extends GlobalValues = {},
-    const ParentPage extends BookPage | undefined = undefined,
-    const ControlsInit extends BookPageControlsInitBase = {},
->(
-    pageInit: BookPageInit<GlobalValuesType, ParentPage, ControlsInit>,
-): BookPage<GlobalValuesType, ParentPage, ControlsInit> {
-    const page: BookPage<GlobalValuesType, ParentPage, ControlsInit> = {
-        ...pageInit,
-        entryType: BookEntryType.Page,
-        useVerticalExamples: !!pageInit.useVerticalExamples,
-        elementExamples: {},
-        descriptionParagraphs: pageInit.descriptionParagraphs ?? [],
-        controls: pageInit.controls ?? ({} as ControlsInit),
-        errors: [],
-    };
-
-    const alreadyTakenElementExampleNames = new Set<string>();
-
-    if (pageInit.defineExamples) {
-        pageInit.defineExamples({
-            defineExample(elementExampleInit) {
-                const newExample: BookElementExample<any, any, any> = {
-                    ...elementExampleInit,
-                    isVertical: page.useVerticalExamples,
-                    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(check.isTruthy),
-                };
-                alreadyTakenElementExampleNames.add(elementExampleInit.title);
-
-                page.elementExamples[titleToUrlBreadcrumb(newExample.title)] = newExample as Values<
-                    (typeof page)['elementExamples']
-                >;
-            },
-        });
-    }
-
-    return page;
-}

package/src/data/book-entry/book-root.ts

@@ -1,16 +0,0 @@
-import {type Overwrite} from '@augment-vir/common';
-import {type BaseBookEntry} from './base-book-entry.js';
-import {type BookEntryType} from './book-entry-type.js';
-
-/**
- * The root of a book tree.
- *
- * @category Internal
- */
-export type BookRoot = Overwrite<
-    BaseBookEntry,
-    {
-        entryType: BookEntryType.Root;
-        parent: undefined;
-    }
->;