asljs-ui-debug 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,51 @@
+# Permissive No-Derivatives License 1.0
+
+Copyright (c) 2026 Alexandrite Software Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software (the "Software") to:
+
+1. Use the Software for any purpose, including commercial purposes.
+2. Copy and redistribute the Software, including as part of another application,
+   library, or package.
+3. Modify the Software for private or internal use.
+
+Subject to the following conditions:
+
+## 1. No Distribution of Modified Versions
+
+Modified versions of the Software, or substantial portions thereof, must not be
+distributed without prior written permission from the copyright holder.
+
+Routine build transformations, including minification, transpilation, and
+bundling, are permitted for distribution, provided they do not intentionally
+alter the Software's functionality.
+
+## 2. Licence and Copyright Preservation
+
+All distributed copies of the Software must retain this copyright notice and
+licence.
+
+The Software itself, including copies incorporated into other applications,
+libraries, or packages, remains subject to this licence.
+
+The Software must not be sublicensed or redistributed under a different licence.
+
+## 3. Use in Other Software
+
+Applications and libraries that merely use, import, link to, or bundle the
+Software are not considered modified versions of the Software and may be
+distributed under any licence.
+
+Such use, incorporation, or bundling does not grant permission to relicense the
+Software or distribute modified versions of it.
+
+### 4. No Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# debug
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Part of [Alexandrite Software Library][#1] - a set of high-quality, performant
+> JavaScript libraries and tools for everyday use.
+
+## Overview
+
+`asljs-ui-debug` adds a debug menu to a page built with the ASLJS UI components.
+A small `…` button in the corner of the page opens the menu; its Components item
+opens a popup with the tree of the components on the page at that moment and the
+values of their properties.
+
+## Scope
+
+- The menu is off unless the `asljs-debug=1` cookie is set; importing the
+  package then adds it once the page has loaded.
+- The tree lists each element with a registered model definition, or an `asljs-`
+  tag, and the properties its definition names.
+- The menu and the popup render in their own shadow roots, so the page's styles
+  do not reach them.
+
+## Installation
+
+```bash
+npm install asljs-ui-debug
+```
+
+NPM package: [asljs-ui-debug][NPM]
+
+## Usage
+
+Import the package once, after the component packages the page uses:
+
+```ts
+import 'asljs-ui-button';
+import 'asljs-ui-debug';
+```
+
+Turn the menu on for the site, then reload the page:
+
+```ts
+import { setDebugEnabled }
+  from 'asljs-ui-debug';
+
+setDebugEnabled(true);
+```
+
+Setting the cookie by hand works the same, for example from the browser console:
+`document.cookie = 'asljs-debug=1; path=/'`.
+
+## Further reading
+
+- [Debug Menu][DOC] - the cookie, the menu items and the component tree.
+
+Questions and bugs: [asljs/issues][ISS].
+
+## Related packages
+
+- [ui][UI] - the shared theme, the component model registry and the other UI
+  packages.
+
+## License
+
+MIT License. See [LICENSE][LIC] for details.
+
+[#1]: https://github.com/AlexandriteSoftware/asljs
+[DOC]: <docs/Debug Menu.md>
+[ISS]: https://github.com/AlexandriteSoftware/asljs/issues
+[LIC]: LICENSE.md
+[NPM]: https://www.npmjs.com/package/asljs-ui-debug
+[UI]: ../core/README.md

package/dist/component-tree.d.ts

@@ -0,0 +1,25 @@
+import { type ComponentModelPropertyType } from 'asljs-ui';
+export interface ComponentPropertyNode {
+    name: string;
+    title: string;
+    type: ComponentModelPropertyType | 'unknown';
+    value: string;
+}
+export interface ComponentNode {
+    element: Element;
+    tagName: string;
+    title: string;
+    properties: ComponentPropertyNode[];
+    children: ComponentNode[];
+}
+/**
+ * The tree of the components under `root`: every element with a registered
+ * model definition or an `asljs-` tag, nested as they are nested in the DOM,
+ * open shadow roots included. Elements between two components are skipped,
+ * and the debug elements are left out.
+ */
+export declare function collectComponents(root: ParentNode): ComponentNode[];
+/**
+ * A short, one-line text of `value` for the property list.
+ */
+export declare function describeValue(value: unknown): string;

package/dist/component-tree.js

@@ -0,0 +1,91 @@
+import { getComponentModel } from 'asljs-ui';
+const COMPONENT_TAG_PREFIX = 'asljs-';
+const DEBUG_TAG_PREFIX = 'asljs-debug-';
+const VALUE_LENGTH = 60;
+/**
+ * The tree of the components under `root`: every element with a registered
+ * model definition or an `asljs-` tag, nested as they are nested in the DOM,
+ * open shadow roots included. Elements between two components are skipped,
+ * and the debug elements are left out.
+ */
+export function collectComponents(root) {
+    const nodes = [];
+    for (const child of childrenOf(root)) {
+        const tagName = child.tagName.toLowerCase();
+        if (tagName.startsWith(DEBUG_TAG_PREFIX)) {
+            continue;
+        }
+        const definition = getComponentModel(tagName);
+        if (definition === null
+            && !tagName.startsWith(COMPONENT_TAG_PREFIX)) {
+            nodes.push(...collectComponents(child));
+            continue;
+        }
+        nodes.push({ element: child,
+            tagName,
+            title: definition?.title ?? tagName,
+            properties: describeProperties(child, definition),
+            children: collectComponents(child) });
+    }
+    return nodes;
+}
+/**
+ * A short, one-line text of `value` for the property list.
+ */
+export function describeValue(value) {
+    if (value === null
+        || value === undefined) {
+        return String(value);
+    }
+    if (typeof value
+        === 'string') {
+        return JSON.stringify(shorten(value));
+    }
+    if (typeof value
+        === 'function') {
+        return `ƒ ${value.name || 'anonymous'}()`;
+    }
+    if (Array.isArray(value)) {
+        return `Array(${value.length})`;
+    }
+    if (typeof value
+        === 'object') {
+        const name = value.constructor?.name ?? 'Object';
+        const keys = Object.keys(value);
+        return keys.length === 0
+            ? `${name} {}`
+            : `${name} { ${shorten(keys.join(', '))} }`;
+    }
+    return String(value);
+}
+function childrenOf(root) {
+    const children = [...root.children];
+    const shadowRoot = root.shadowRoot;
+    if (shadowRoot) {
+        children.push(...shadowRoot.children);
+    }
+    return children;
+}
+function describeProperties(element, definition) {
+    const values = element;
+    if (definition !== null) {
+        return definition.properties.map(property => ({ name: property.name,
+            title: property.title ?? property.name,
+            type: property.type,
+            value: describeValue(values[property.name]) }));
+    }
+    // Without a definition, a Lit element still lists its reactive properties.
+    const reactive = element.constructor
+        .elementProperties;
+    return [...reactive?.keys() ?? []]
+        .filter((key) => typeof key === 'string')
+        .map(name => ({ name,
+        title: name,
+        type: 'unknown',
+        value: describeValue(values[name]) }));
+}
+function shorten(text) {
+    return text.length > VALUE_LENGTH
+        ? `${text.slice(0, VALUE_LENGTH - 1)}…`
+        : text;
+}

package/dist/components-popup.d.ts

@@ -0,0 +1,18 @@
+import { LitElement, type TemplateResult } from 'lit';
+import { type ComponentNode } from './component-tree.js';
+/**
+ * A popup with the tree of the components under `root` and their properties.
+ * The tree is taken when the popup opens and again on Refresh; closing removes
+ * the popup from the page.
+ */
+export declare class ComponentsPopup extends LitElement {
+    static styles: import("lit").CSSResult;
+    accessor root: ParentNode | null;
+    accessor components: ComponentNode[];
+    connectedCallback(): void;
+    /** Takes the tree of the components again. */
+    refresh(): void;
+    /** Removes the popup and dispatches `close`. */
+    close(): void;
+    render(): TemplateResult;
+}

package/dist/components-popup.js

@@ -0,0 +1,165 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { css, html, LitElement, nothing } from 'lit';
+import { customElement, property, state } from 'lit/decorators.js';
+import { collectComponents } from './component-tree.js';
+/**
+ * A popup with the tree of the components under `root` and their properties.
+ * The tree is taken when the popup opens and again on Refresh; closing removes
+ * the popup from the page.
+ */
+let ComponentsPopup = class ComponentsPopup extends LitElement {
+    static { this.styles = css `
+    :host {
+      position: fixed;
+      right: 1rem;
+      bottom: 3.5rem;
+      z-index: 2147483646;
+      display: flex;
+      flex-direction: column;
+      width: min(36rem, calc(100vw - 2rem));
+      max-height: min(32rem, calc(100vh - 5rem));
+      background: #fff;
+      color: #212529;
+      border: 1px solid #ced4da;
+      border-radius: 0.5rem;
+      box-shadow: 0 0.5rem 1.5rem rgb(0 0 0 / 20%);
+      font: 13px/1.4 system-ui, sans-serif;
+    }
+    header {
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+      padding: 0.5rem 0.75rem;
+      border-bottom: 1px solid #dee2e6;
+    }
+    h2 {
+      flex: 1;
+      margin: 0;
+      font-size: 14px;
+    }
+    button {
+      font: inherit;
+      padding: 0.125rem 0.5rem;
+      cursor: pointer;
+    }
+    .tree {
+      overflow: auto;
+      padding: 0.5rem 0.75rem;
+    }
+    details {
+      margin-left: 1rem;
+    }
+    .tree > details {
+      margin-left: 0;
+    }
+    summary {
+      cursor: pointer;
+    }
+    .tag {
+      font-family: ui-monospace, monospace;
+      color: #6f42c1;
+    }
+    .title {
+      color: #6c757d;
+      margin-left: 0.5rem;
+    }
+    table {
+      margin: 0.25rem 0 0.25rem 1rem;
+      border-collapse: collapse;
+    }
+    td {
+      padding: 0 0.75rem 0 0;
+      vertical-align: top;
+    }
+    .name {
+      font-weight: 600;
+    }
+    .type {
+      color: #6c757d;
+    }
+    .value {
+      font-family: ui-monospace, monospace;
+      word-break: break-all;
+    }
+    .empty {
+      color: #6c757d;
+    }
+  `; }
+    #root_accessor_storage = null;
+    get root() { return this.#root_accessor_storage; }
+    set root(value) { this.#root_accessor_storage = value; }
+    #components_accessor_storage = [];
+    get components() { return this.#components_accessor_storage; }
+    set components(value) { this.#components_accessor_storage = value; }
+    connectedCallback() {
+        super.connectedCallback();
+        this.refresh();
+    }
+    /** Takes the tree of the components again. */
+    refresh() {
+        this.components =
+            collectComponents(this.root ?? this.ownerDocument.body);
+    }
+    /** Removes the popup and dispatches `close`. */
+    close() {
+        this.remove();
+        this.dispatchEvent(new Event('close'));
+    }
+    render() {
+        return html `
+      <header>
+        <h2>Components</h2>
+        <button type="button"
+                data-role="refresh"
+                @click=${() => this.refresh()}>Refresh</button>
+        <button type="button"
+                data-role="close"
+                aria-label="Close"
+                @click=${() => this.close()}>×</button>
+      </header>
+      <div class="tree">
+        ${this.components.length === 0
+            ? html `<p class="empty">No components on the page.</p>`
+            : this.components.map(node => renderNode(node))}
+      </div>
+    `;
+    }
+};
+__decorate([
+    property({ attribute: false })
+], ComponentsPopup.prototype, "root", null);
+__decorate([
+    state()
+], ComponentsPopup.prototype, "components", null);
+ComponentsPopup = __decorate([
+    customElement('asljs-debug-components')
+], ComponentsPopup);
+export { ComponentsPopup };
+function renderNode(node) {
+    const id = node.element.id === ''
+        ? ''
+        : `#${node.element.id}`;
+    return html `
+    <details open>
+      <summary>
+        <span class="tag">&lt;${node.tagName}${id}&gt;</span>${node.title === node.tagName
+        ? nothing
+        : html `<span class="title">${node.title}</span>`}
+      </summary>
+      ${node.properties.length === 0
+        ? nothing
+        : html `<table>${node.properties.map(property => html `<tr>
+              <td class="name"
+                  title=${property.title}>${property.name}</td>
+              <td class="type">${property.type}</td>
+              <td class="value">${property.value}</td>
+            </tr>`)}</table>`}
+      ${node.children.map(child => renderNode(child))}
+    </details>
+  `;
+}

package/dist/cookie.d.ts

@@ -0,0 +1,11 @@
+export declare const DEBUG_COOKIE_NAME = "asljs-debug";
+/**
+ * Whether the cookie `asljs-debug=1` is among `cookie`, by default the
+ * cookies of the current document.
+ */
+export declare function isDebugEnabled(cookie?: string): boolean;
+/**
+ * Sets or removes the `asljs-debug` cookie of `document`, for the whole site.
+ * The change takes effect on the next page load.
+ */
+export declare function setDebugEnabled(enabled: boolean, document?: Document): void;

package/dist/cookie.js

@@ -0,0 +1,20 @@
+export const DEBUG_COOKIE_NAME = 'asljs-debug';
+/**
+ * Whether the cookie `asljs-debug=1` is among `cookie`, by default the
+ * cookies of the current document.
+ */
+export function isDebugEnabled(cookie = globalThis.document?.cookie ?? '') {
+    return cookie
+        .split(';')
+        .some(entry => entry.trim() === `${DEBUG_COOKIE_NAME}=1`);
+}
+/**
+ * Sets or removes the `asljs-debug` cookie of `document`, for the whole site.
+ * The change takes effect on the next page load.
+ */
+export function setDebugEnabled(enabled, document = globalThis.document) {
+    document.cookie =
+        enabled
+            ? `${DEBUG_COOKIE_NAME}=1; path=/; SameSite=Lax`
+            : `${DEBUG_COOKIE_NAME}=; path=/; max-age=0; SameSite=Lax`;
+}

package/dist/debug-menu.d.ts

@@ -0,0 +1,25 @@
+import { LitElement, type TemplateResult } from 'lit';
+import './components-popup.js';
+export interface DebugMenuItem {
+    label: string;
+    run(menu: DebugMenu): void;
+}
+/**
+ * The item that opens the popup with the tree of the page's components, or
+ * closes it when it is open.
+ */
+export declare const COMPONENTS_MENU_ITEM: DebugMenuItem;
+/**
+ * The item that removes the `asljs-debug` cookie and the menu.
+ */
+export declare const DISABLE_MENU_ITEM: DebugMenuItem;
+/**
+ * The `…` button in the corner of the page that opens the debug menu.
+ */
+export declare class DebugMenu extends LitElement {
+    #private;
+    static styles: import("lit").CSSResult;
+    accessor items: readonly DebugMenuItem[];
+    accessor expanded: boolean;
+    render(): TemplateResult;
+}

package/dist/debug-menu.js

@@ -0,0 +1,135 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { css, html, LitElement, nothing } from 'lit';
+import { customElement, property, state } from 'lit/decorators.js';
+import './components-popup.js';
+import { setDebugEnabled } from './cookie.js';
+/**
+ * The item that opens the popup with the tree of the page's components, or
+ * closes it when it is open.
+ */
+export const COMPONENTS_MENU_ITEM = Object.freeze({ label: 'Components',
+    run: toggleComponentsPopup });
+/**
+ * The item that removes the `asljs-debug` cookie and the menu.
+ */
+export const DISABLE_MENU_ITEM = Object.freeze({ label: 'Disable debug menu',
+    run: disableDebugMenu });
+/**
+ * The `…` button in the corner of the page that opens the debug menu.
+ */
+let DebugMenu = class DebugMenu extends LitElement {
+    static { this.styles = css `
+    :host {
+      position: fixed;
+      right: 1rem;
+      bottom: 1rem;
+      z-index: 2147483647;
+      font: 13px/1.4 system-ui, sans-serif;
+    }
+    .toggle {
+      width: 2rem;
+      height: 2rem;
+      border: 1px solid #ced4da;
+      border-radius: 50%;
+      background: #fff;
+      color: #212529;
+      box-shadow: 0 0.25rem 0.75rem rgb(0 0 0 / 15%);
+      cursor: pointer;
+      font: inherit;
+      font-weight: 700;
+      opacity: 0.6;
+    }
+    .toggle:hover,
+    .toggle[aria-expanded="true"] {
+      opacity: 1;
+    }
+    ul {
+      position: absolute;
+      right: 0;
+      bottom: 2.5rem;
+      min-width: 12rem;
+      margin: 0;
+      padding: 0.25rem 0;
+      list-style: none;
+      background: #fff;
+      border: 1px solid #ced4da;
+      border-radius: 0.375rem;
+      box-shadow: 0 0.5rem 1.5rem rgb(0 0 0 / 20%);
+    }
+    li button {
+      display: block;
+      width: 100%;
+      padding: 0.375rem 0.75rem;
+      border: 0;
+      background: none;
+      color: #212529;
+      text-align: left;
+      font: inherit;
+      cursor: pointer;
+    }
+    li button:hover {
+      background: #e9ecef;
+    }
+  `; }
+    #items_accessor_storage = [COMPONENTS_MENU_ITEM,
+        DISABLE_MENU_ITEM];
+    get items() { return this.#items_accessor_storage; }
+    set items(value) { this.#items_accessor_storage = value; }
+    #expanded_accessor_storage = false;
+    get expanded() { return this.#expanded_accessor_storage; }
+    set expanded(value) { this.#expanded_accessor_storage = value; }
+    render() {
+        return html `
+      <button type="button"
+              class="toggle"
+              aria-label="Debug menu"
+              aria-haspopup="menu"
+              aria-expanded=${this.expanded
+            ? 'true'
+            : 'false'}
+              @click=${() => this.expanded = !this.expanded}>…</button>
+      ${this.expanded
+            ? html `<ul role="menu">${this.items.map(item => html `<li role="none">
+                <button type="button"
+                        role="menuitem"
+                        @click=${() => this.#run(item)}>${item.label}</button>
+              </li>`)}</ul>`
+            : nothing}
+    `;
+    }
+    #run(item) {
+        this.expanded = false;
+        item.run(this);
+    }
+};
+__decorate([
+    property({ attribute: false })
+], DebugMenu.prototype, "items", null);
+__decorate([
+    state()
+], DebugMenu.prototype, "expanded", null);
+DebugMenu = __decorate([
+    customElement('asljs-debug-menu')
+], DebugMenu);
+export { DebugMenu };
+function toggleComponentsPopup(menu) {
+    const document = menu.ownerDocument;
+    const open = document.querySelector('asljs-debug-components');
+    if (open) {
+        open.remove();
+        return;
+    }
+    document.body.appendChild(document.createElement('asljs-debug-components'));
+}
+function disableDebugMenu(menu) {
+    setDebugEnabled(false, menu.ownerDocument);
+    menu.ownerDocument
+        .querySelector('asljs-debug-components')
+        ?.remove();
+    menu.remove();
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { collectComponents, describeValue, type ComponentNode, type ComponentPropertyNode } from './component-tree.js';
+export { ComponentsPopup } from './components-popup.js';
+export { DEBUG_COOKIE_NAME, isDebugEnabled, setDebugEnabled } from './cookie.js';
+export { COMPONENTS_MENU_ITEM, DebugMenu, DISABLE_MENU_ITEM, type DebugMenuItem } from './debug-menu.js';
+export { initDebug } from './init.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+import { initDebug } from './init.js';
+export { collectComponents, describeValue } from './component-tree.js';
+export { ComponentsPopup } from './components-popup.js';
+export { DEBUG_COOKIE_NAME, isDebugEnabled, setDebugEnabled } from './cookie.js';
+export { COMPONENTS_MENU_ITEM, DebugMenu, DISABLE_MENU_ITEM } from './debug-menu.js';
+export { initDebug } from './init.js';
+// A page that imports the package gets the menu when the cookie is set.
+if (globalThis.document) {
+    initDebug();
+}

package/dist/init.d.ts

@@ -0,0 +1,7 @@
+import './debug-menu.js';
+/**
+ * Adds `asljs-debug-menu` to the body of `document` when the `asljs-debug`
+ * cookie is set, once the document has loaded. Returns whether the menu is
+ * enabled; calling it again adds no second menu.
+ */
+export declare function initDebug(document?: Document): boolean;

package/dist/init.js

@@ -0,0 +1,24 @@
+import { isDebugEnabled } from './cookie.js';
+import './debug-menu.js';
+/**
+ * Adds `asljs-debug-menu` to the body of `document` when the `asljs-debug`
+ * cookie is set, once the document has loaded. Returns whether the menu is
+ * enabled; calling it again adds no second menu.
+ */
+export function initDebug(document = globalThis.document) {
+    if (!isDebugEnabled(document.cookie)) {
+        return false;
+    }
+    const addMenu = () => {
+        if (!document.querySelector('asljs-debug-menu')) {
+            document.body.appendChild(document.createElement('asljs-debug-menu'));
+        }
+    };
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', addMenu, { once: true });
+    }
+    else {
+        addMenu();
+    }
+    return true;
+}

package/docs/Debug Menu.md

@@ -0,0 +1,68 @@
+# Debug Menu
+
+How the debug menu of `asljs-ui-debug` is turned on, what it holds, and how the
+component tree is taken.
+
+## Turning it on
+
+The menu is controlled by the `asljs-debug` cookie:
+
+- If the cookie is `asljs-debug=1`, then importing the package adds
+  `asljs-debug-menu` to the end of the body, once the document has loaded.
+- If the cookie is absent or has any other value, then importing the package
+  adds nothing.
+
+`initDebug(document?)` does the check and is what the import runs; calling it
+again adds no second menu. `isDebugEnabled(cookie?)` reads the cookie, and
+`setDebugEnabled(enabled, document?)` sets it for the whole site (`path=/`) or
+removes it. A change takes effect on the next page load.
+
+## The menu
+
+`asljs-debug-menu` is a round `…` button fixed to the bottom right corner of the
+page. Clicking it opens and closes the list of its `items`; choosing an item
+closes the list and calls the item's `run(menu)`. The default items:
+
+- `COMPONENTS_MENU_ITEM`, Components - opens `asljs-debug-components`, or
+  removes it when it is open.
+- `DISABLE_MENU_ITEM`, Disable debug menu - removes the cookie, the popup and
+  the menu.
+
+A page adds its own items by setting `items`:
+
+```ts
+menu.items =
+  [ ...menu.items,
+    { label: 'Clear cache',
+      run: () => clearCache() } ];
+```
+
+## The component tree
+
+`asljs-debug-components` is a popup above the menu button. It takes the tree of
+the components under its `root`, by default the body, when it is added to the
+page and again on Refresh; the tree does not follow later changes on its own.
+Closing it removes it and dispatches `close`.
+
+`collectComponents(root)` builds the tree:
+
+- An element is a component if `getComponentModel` of `asljs-ui` has a model
+  definition for its tag, or if its tag starts with `asljs-`.
+- A component's children are the components inside it; the elements between two
+  components are skipped, and open shadow roots are walked as well.
+- The `asljs-debug-` elements are left out.
+
+Each component lists its properties:
+
+- If it has a model definition, then the properties are the definition's, with
+  their title and type.
+- If it has none but is a Lit element, then the properties are its reactive
+  properties, with the type `unknown`.
+
+`describeValue(value)` gives the shown value: strings are quoted and cut at 60
+characters, functions show their name, arrays their length, and objects their
+constructor and keys.
+
+A component package registers its definition with `defineComponentModel(tag,
+definition)` of `asljs-ui` where it defines the element; every package of `ui/`
+does.

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "asljs-ui-debug",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "A debug menu for pages built with the ASLJS UI components: a tree of the components on the page and their properties.",
+  "type": "module",
+  "asljs": {
+    "type": "lib"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE.md",
+    "docs/**"
+  ],
+  "scripts": {
+    "flint": "toolkit flint",
+    "clean": "toolkit clean",
+    "build": "npm run codegen --if-present && tsc -p tsconfig.build.json",
+    "build:dist": "npm run codegen --if-present && tsc -p tsconfig.dist.json",
+    "typecheck": "npm run codegen --if-present && tsc -p tsconfig.build.json --noEmit",
+    "guard:clean-git": "toolkit ensure-clean-working-directory",
+    "prepack": "npm run clean && npm run build:dist && npm run build && npm run test && npm run guard:clean-git",
+    "postpublish": "toolkit tag-release-revision",
+    "test": "node --test --enable-source-maps \"build/**/*.test.js\"",
+    "test:watch": "node --watch --test \"build/**/*.test.js\"",
+    "coverage": "npm run build && node --test --experimental-test-coverage --enable-source-maps --test-coverage-exclude=\"**/*.test.js\" \"build/**/*.test.js\"",
+    "release:patch": "toolkit release-patch",
+    "all": "npm run clean && npm run build:dist && npm run flint && npm run typecheck && npm run build && npm run test"
+  },
+  "keywords": [
+    "web-components",
+    "lit",
+    "ui",
+    "debug"
+  ],
+  "author": "\"Alex Netkachov\" <alex.netkachov@gmail.com>",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "homepage": "https://github.com/AlexandriteSoftware/asljs#readme",
+  "bugs": {
+    "url": "https://github.com/AlexandriteSoftware/asljs/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexandriteSoftware/asljs.git"
+  },
+  "dependencies": {
+    "asljs-ui": "^0.1.1",
+    "lit": "^3.3.1"
+  },
+  "devDependencies": {
+    "asljs-testing": "^0.1.1",
+    "asljs-toolkit": "^0.1.0"
+  }
+}