[Feature] Improve DX

CHANGELOG.md

@@ -7,6 +7,7 @@ All notable changes to this project will be documented in this file. The format
 ### Added
 
 - Add browser storage utilities: `createStorage`, `useLocalStorage`, `useSessionStorage`, `useUrlSearchParams`, `useUrlSearchParamsInHash` ([#671](https://github.com/studiometa/js-toolkit/pull/671))
+- Add `logTree` helper to inspect the component tree from the console ([#654](https://github.com/studiometa/js-toolkit/pull/654))
 
 ## [v3.5.0](https://github.com/studiometa/js-toolkit/compare/3.4.3..3.5.0) (2026-03-25)
 

packages/docs/.vitepress/config.ts

@@ -254,6 +254,7 @@ function getHelpersSidebar() {
     { text: 'importWhenPrefersMotion', link: '/api/helpers/importWhenPrefersMotion.html' },
     { text: 'importWhenVisible', link: '/api/helpers/importWhenVisible.html' },
     { text: 'isDirectChild', link: '/api/helpers/isDirectChild.html' },
+    { text: 'logTree', link: '/api/helpers/logTree.html' },
     { text: 'registerComponent', link: '/api/helpers/registerComponent.html' },
   ];
 }

packages/docs/api/helpers/logTree.md

@@ -0,0 +1,42 @@
+# logTree
+
+Log the component tree to the browser console starting from a given instance. Uses the global instance registry and DOM containment to build the tree — does **not** rely on the deprecated `$children` API.
+
+Components with children are displayed as collapsed groups. Each entry shows:
+- **●** for mounted instances, **○** for unmounted
+- The instance `$id`
+- A reference to the DOM element
+
+## Usage
+
+### From the console (zero config)
+
+When using `createApp`, a `$logTree()` function is automatically registered on `globalThis` in development mode. Just open your browser console and type:
+
+```js
+$logTree()
+```
+
+### Programmatic usage
+
+```js
+import { logTree } from '@studiometa/js-toolkit';
+
+// From any component
+logTree(this);
+```
+
+```js
+import { createApp, logTree } from '@studiometa/js-toolkit';
+
+const useApp = createApp(App);
+useApp().then((app) => logTree(app));
+```
+
+### Parameters
+
+- `instance` (`Base`): The root component instance to log the tree from.
+
+### Return value
+
+- `void`: Logs to the console, does not return a value.

packages/js-toolkit/helpers/createApp.ts

@@ -2,6 +2,8 @@ import type { Base, BaseConstructor, BaseProps } from '../Base/index.js';
 import type { Features } from '../Base/features.js';
 import { features } from '../Base/features.js';
 import { defineFeatures } from './defineFeatures.js';
+import { isDev } from '../utils/index.js';
+import { logTree } from './logTree.js';
 
 export type CreateAppOptions = Partial<Features> & {
   root?: HTMLElement;
@@ -27,6 +29,9 @@ export function createApp<S extends BaseConstructor<Base>, T extends BaseProps =
   async function init() {
     app = new App(root) as S & Base<T>;
     await app.$mount();
+    if (isDev) {
+      globalThis.$logTree = () => logTree(app);
+    }
     return app;
   }
 

packages/js-toolkit/helpers/index.ts

@@ -8,6 +8,7 @@ export * from './importOnMediaQuery.js';
 export * from './importWhenIdle.js';
 export * from './importWhenPrefersMotion.js';
 export * from './importWhenVisible.js';
+export * from './logTree.js';
 export * from './registerComponent.js';
 export {
   type QueryOptions,

packages/js-toolkit/helpers/logTree.ts

@@ -0,0 +1,102 @@
+import type { Base } from '../Base/Base.js';
+import { getInstances } from '../Base/index.js';
+
+/**
+ * Build a tree structure from a flat set of instances using DOM containment.
+ */
+function buildTree(root: Base): TreeNode {
+  const allInstances = getInstances();
+  const rootNode: TreeNode = { instance: root, children: [] };
+
+  // Collect all instances that are descendants of root (excluding root itself)
+  const descendants: Base[] = [];
+  for (const instance of allInstances) {
+    if (instance !== root && root.$el.contains(instance.$el)) {
+      descendants.push(instance);
+    }
+  }
+
+  // Sort by DOM order (depth-first)
+  descendants.sort((a, b) => {
+    const position = a.$el.compareDocumentPosition(b.$el);
+    if (position & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
+    if (position & Node.DOCUMENT_POSITION_PRECEDING) return 1;
+    return 0;
+  });
+
+  // Build tree: assign each instance to its closest ancestor in the tree
+  const nodeMap = new Map<Base, TreeNode>();
+  nodeMap.set(root, rootNode);
+
+  for (const instance of descendants) {
+    const node: TreeNode = { instance, children: [] };
+    nodeMap.set(instance, node);
+
+    // Find the closest ancestor that is already in the tree
+    let parentNode = rootNode;
+    for (const [candidate, candidateNode] of nodeMap) {
+      if (
+        candidate !== instance &&
+        candidate.$el.contains(instance.$el) &&
+        // Pick the most specific (deepest) container
+        parentNode.instance.$el.contains(candidate.$el)
+      ) {
+        parentNode = candidateNode;
+      }
+    }
+
+    parentNode.children.push(node);
+  }
+
+  return rootNode;
+}
+
+interface TreeNode {
+  instance: Base;
+  children: TreeNode[];
+}
+
+/**
+ * Log a tree node and its children using console groups.
+ */
+function logNode(node: TreeNode): void {
+  const { instance } = node;
+  const name = instance.$config.name;
+  const mounted = instance.$isMounted;
+  const status = mounted ? '●' : '○';
+  const label = `${status} ${instance.$id}`;
+
+  if (node.children.length > 0) {
+    console.groupCollapsed(label, instance.$el);
+    for (const child of node.children) {
+      logNode(child);
+    }
+    console.groupEnd();
+  } else {
+    console.log(label, instance.$el);
+  }
+}
+
+/**
+ * Log the component tree starting from the given instance.
+ *
+ * Uses the global instance registry and DOM containment to build the tree,
+ * without relying on the deprecated `$children` API.
+ *
+ * @param   {Base} instance The root component instance.
+ * @example
+ * ```js
+ * import { createApp, logTree } from '@studiometa/js-toolkit';
+ *
+ * const useApp = createApp(App);
+ * useApp().then((app) => logTree(app));
+ * ```
+ */
+export function logTree(instance: Base): void {
+  const tree = buildTree(instance);
+  console.group(`🌳 ${instance.$config.name}`);
+  for (const child of tree.children) {
+    logNode(child);
+  }
+  console.groupEnd();
+}

packages/tests/helpers/index.spec.ts

@@ -16,6 +16,7 @@ test('helpers exports', () => {
       "importWhenPrefersMotion",
       "importWhenVisible",
       "isDirectChild",
+      "logTree",
       "queryComponent",
       "queryComponentAll",
       "registerComponent",