hearald 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-10-26
+
+### Fixed
+
+- The dashboard crashed (`Cannot read properties of undefined (reading 'map')`) on a `ui` layout written
+  the way the README showed it, `{ title, fields }`. Sections now accept `title` or `menuName` and
+  `fields` or `stats`, and a section with neither renders empty.
+
+### Changed
+
+- The README now documents the `ui` layout (sections, tiles, `chartContexts`).
+
+## [0.1.1] - 2026-10-09
+
+### Fixed
+
+- The dashboard threw errors the first time it loaded with no data (`Cannot read properties of
+  undefined (reading 'map')` and `(reading 'users')`). It now shows zeros and empty menus when there
+  are no events, no metrics for the chosen chart context, or no `ui` layout.
+
+### Added
+
+- Tests that render the dashboard in a fake browser (happy-dom) against a real hearald router.
+
 ## [0.1.0] - 2026-10-07
 
 ### Security
@@ -117,7 +141,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release of Hearald
 
-[Unreleased]: https://github.com/pariser/hearald/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/pariser/hearald/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/pariser/hearald/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/pariser/hearald/compare/v0.0.5...v0.1.0
 [0.0.5]: https://github.com/pariser/hearald/compare/v0.0.4...v0.0.5
 [0.0.4]: https://github.com/pariser/hearald/compare/v0.0.3...v0.0.4

package/README.md

@@ -113,6 +113,11 @@ const statDefinitions = {
 };
 ```
 
+`ui` sets the dashboard layout. Each section has a `title` (or `menuName`; `""` for no heading) and a
+list of tiles in `fields` (or `stats`); a tile is `{ key, label, type }` with `type` one of `number`,
+`percent` or `histogram`, and an optional `span`. `chartContexts` (`[{ id, menuName }]`) fills the chart's
+"Context" menu. Both are optional; a dashboard with no `ui` shows only the chart.
+
 Names with dots become nested objects in the result. `hidden: true` leaves a metric out of the output
 (useful for sets that only feed a computed metric). A computed metric that names a formula that does
 not exist is an error; one whose inputs are missing is simply left out.

package/dist/analytics.html

@@ -461,7 +461,7 @@ th {
       onLoadProgress(i, n);
 
       const json = await getDataFn({ n: 1, d: iso(day) });
-      const v = json.metrics[context][field] || 0;
+      const v = json?.metrics?.[context]?.[field] || 0;
 
       data.unshift({ date: iso(day), value: v });
       max = Math.max(max, v);
@@ -687,14 +687,14 @@ th {
       fetchStats: getJson,
     });
 
-  let UI = [];
+  let UI = {};
 
   async function fetchUI() {
     try {
       const res = await fetch(window.location.href + "/layout");
-      UI = await res.json();
+      UI = (await res.json()) || {};
     } catch (e) {
-      UI = [];
+      UI = {};
     }
   }
 
@@ -830,7 +830,7 @@ th {
                         name="context"
                         onchange=${(e) => this.changeChartContext(e)}
                       >
-                        ${UI.chartContexts.map(
+                        ${(UI.chartContexts || []).map(
                           ({ id, menuName }) =>
                             m`
                               <option
@@ -881,7 +881,7 @@ th {
                     !chartData.loading &&
                     m`
                       <div class="bar-chart__scale">${chartData.max}</div>
-                      ${chartData.data.map(
+                      ${(chartData.data || []).map(
                         (v) =>
                           m`
                             <div
@@ -899,16 +899,16 @@ th {
                     `}
                   </div>
                 </section>
-                ${UI.sections.map((statsSection) => {
+                ${(UI.sections || []).map((statsSection) => {
+                  const sectionTitle =
+                    statsSection.menuName ?? statsSection.title ?? "";
                   return m`
                     <section class="analytics analytics--${statsSection.id}">
-                      ${statsSection.menuName !== "" &&
+                      ${sectionTitle !== "" &&
                       m`
-                        <h2 class="analytics__title">
-                          ${statsSection.menuName}
-                        </h2>
+                        <h2 class="analytics__title">${sectionTitle}</h2>
                       `}
-                      ${statsSection.stats.map((f) => {
+                      ${(statsSection.stats || statsSection.fields || []).map((f) => {
                         return m`
                           <${Tile}
                             title="${f.label}"

package/dist/index.js

@@ -63,7 +63,7 @@
       onLoadProgress(i, n);
 
       const json = await getDataFn({ n: 1, d: iso(day) });
-      const v = json.metrics[context][field] || 0;
+      const v = json?.metrics?.[context]?.[field] || 0;
 
       data.unshift({ date: iso(day), value: v });
       max = Math.max(max, v);
@@ -289,14 +289,14 @@
       fetchStats: getJson,
     });
 
-  let UI = [];
+  let UI = {};
 
   async function fetchUI() {
     try {
       const res = await fetch(window.location.href + "/layout");
-      UI = await res.json();
+      UI = (await res.json()) || {};
     } catch (e) {
-      UI = [];
+      UI = {};
     }
   }
 
@@ -432,7 +432,7 @@
                         name="context"
                         onchange=${(e) => this.changeChartContext(e)}
                       >
-                        ${UI.chartContexts.map(
+                        ${(UI.chartContexts || []).map(
                           ({ id, menuName }) =>
                             m`
                               <option
@@ -483,7 +483,7 @@
                     !chartData.loading &&
                     m`
                       <div class="bar-chart__scale">${chartData.max}</div>
-                      ${chartData.data.map(
+                      ${(chartData.data || []).map(
                         (v) =>
                           m`
                             <div
@@ -501,16 +501,16 @@
                     `}
                   </div>
                 </section>
-                ${UI.sections.map((statsSection) => {
+                ${(UI.sections || []).map((statsSection) => {
+                  const sectionTitle =
+                    statsSection.menuName ?? statsSection.title ?? "";
                   return m`
                     <section class="analytics analytics--${statsSection.id}">
-                      ${statsSection.menuName !== "" &&
+                      ${sectionTitle !== "" &&
                       m`
-                        <h2 class="analytics__title">
-                          ${statsSection.menuName}
-                        </h2>
+                        <h2 class="analytics__title">${sectionTitle}</h2>
                       `}
-                      ${statsSection.stats.map((f) => {
+                      ${(statsSection.stats || statsSection.fields || []).map((f) => {
                         return m`
                           <${Tile}
                             title="${f.label}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hearald",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A single server drop-in file system based metrics and analytics library.",
   "main": "src/index.js",
   "exports": {
@@ -27,6 +27,7 @@
     "chalk": "^4.1.0"
   },
   "devDependencies": {
+    "@happy-dom/global-registrator": "^20.14.6",
     "@rollup/plugin-commonjs": "^15.1.0",
     "@rollup/plugin-json": "^4.1.0",
     "@rollup/plugin-node-resolve": "^13.3.0",
@@ -39,6 +40,7 @@
     "eslint-plugin-react-hooks": "^4.6.0",
     "express": "^5.2.1",
     "express4": "npm:express@^4.21.2",
+    "happy-dom": "^20.14.6",
     "htm": "^3.0.3",
     "preact": "^10.3.3",
     "prettier": "2.2.1",

package/src/public/js/App.js

@@ -75,14 +75,14 @@ const getDataFn = ({ n, d, q }) =>
     fetchStats: getJson,
   });
 
-let UI = [];
+let UI = {};
 
 async function fetchUI() {
   try {
     const res = await fetch(window.location.href + "/layout");
-    UI = await res.json();
+    UI = (await res.json()) || {};
   } catch (e) {
-    UI = [];
+    UI = {};
   }
 }
 
@@ -218,7 +218,7 @@ class App extends Component {
                         name="context"
                         onchange=${(e) => this.changeChartContext(e)}
                       >
-                        ${UI.chartContexts.map(
+                        ${(UI.chartContexts || []).map(
                           ({ id, menuName }) =>
                             html`
                               <option
@@ -269,7 +269,7 @@ class App extends Component {
                     !chartData.loading &&
                     html`
                       <div class="bar-chart__scale">${chartData.max}</div>
-                      ${chartData.data.map(
+                      ${(chartData.data || []).map(
                         (v) =>
                           html`
                             <div
@@ -287,16 +287,16 @@ class App extends Component {
                     `}
                   </div>
                 </section>
-                ${UI.sections.map((statsSection) => {
+                ${(UI.sections || []).map((statsSection) => {
+                  const sectionTitle =
+                    statsSection.menuName ?? statsSection.title ?? "";
                   return html`
                     <section class="analytics analytics--${statsSection.id}">
-                      ${statsSection.menuName !== "" &&
+                      ${sectionTitle !== "" &&
                       html`
-                        <h2 class="analytics__title">
-                          ${statsSection.menuName}
-                        </h2>
+                        <h2 class="analytics__title">${sectionTitle}</h2>
                       `}
-                      ${statsSection.stats.map((f) => {
+                      ${(statsSection.stats || statsSection.fields || []).map((f) => {
                         return html`
                           <${Tile}
                             title="${f.label}"

package/src/public/js/util.js

@@ -48,7 +48,7 @@ export async function fetchChartData({
     onLoadProgress(i, n);
 
     const json = await getDataFn({ n: 1, d: iso(day) });
-    const v = json.metrics[context][field] || 0;
+    const v = json?.metrics?.[context]?.[field] || 0;
 
     data.unshift({ date: iso(day), value: v });
     max = Math.max(max, v);