hearald 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-11-08
+
+### Fixed
+
+- Fix the dashboard chart's initial loading state when the app does not have a `users` field.
+- Fix the dashboard's timezone to match the server's daily bucketing (Pacific time).
+
+## [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

package/README.md

@@ -113,6 +113,13 @@ 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.
+The chart starts on the `users` field and the `all` context when the app has them, otherwise on the
+first field and the first `chartContexts` entry. The page's date defaults to today in Pacific time.
+
 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

@@ -405,6 +405,36 @@ th {
 
   var m=e.bind(_);
 
+  // A Date whose UTC fields hold the current Pacific wall-clock time, so `iso()` (which reads UTC
+  // fields) names the Pacific day. The instant it represents is not "now"; it is only for day buckets.
+  const nowAsPstDate = (now = new Date()) => {
+    const parts = Object.fromEntries(
+      new Intl.DateTimeFormat("en-US", {
+        timeZone: "America/Los_Angeles",
+        hourCycle: "h23",
+        year: "numeric",
+        month: "numeric",
+        day: "numeric",
+        hour: "numeric",
+        minute: "numeric",
+        second: "numeric",
+      })
+        .formatToParts(now)
+        .map((p) => [p.type, p.value])
+    );
+    return new Date(
+      Date.UTC(
+        Number(parts.year),
+        Number(parts.month) - 1,
+        Number(parts.day),
+        Number(parts.hour),
+        Number(parts.minute),
+        Number(parts.second),
+        now.getMilliseconds()
+      )
+    );
+  };
+
   function iso(time) {
     return [
       time.getUTCFullYear(),
@@ -413,6 +443,10 @@ th {
     ].join("-");
   }
 
+  // Today's calendar date in Pacific time as YYYY-MM-DD (daylight saving included), the same day
+  // buckets the server uses. The dashboard page defaults its date to this, not the browser's UTC date.
+  const pacificToday = (now = new Date()) => iso(nowAsPstDate(now));
+
   /* START methods for fetching data from the server */
 
   const dataCache = {};
@@ -485,6 +519,18 @@ th {
 
   /* END methods for fetching data from the server */
 
+  // Keeps the preferred chart field/context when they exist, otherwise falls back to the first
+  // available one, so the menus (which show the first option when nothing matches) and the chart agree.
+  function resolveChartDefaults({ chartField, chartContext, stats, contexts }) {
+    const fields = Object.keys(stats?.metrics?.all || {});
+    const contextIds = (contexts || []).map((c) => c.id);
+    return {
+      chartField: fields.length && !fields.includes(chartField) ? fields[0] : chartField,
+      chartContext:
+        contextIds.length && !contextIds.includes(chartContext) ? contextIds[0] : chartContext,
+    };
+  }
+
   /* START helper methods */
 
   const getJson = async (url) => {
@@ -622,8 +668,6 @@ th {
     }
   }
 
-  const DATE = new Date().toISOString().split("T")[0];
-
   const Logo = () => m`
   <svg
     width="256"
@@ -703,7 +747,7 @@ th {
       super(props);
       this.state = {
         numDays: 30,
-        date: DATE,
+        date: pacificToday(),
         chartField: "users",
         chartContext: "all",
         uiSectionsLoaded: false,
@@ -713,25 +757,22 @@ th {
     async componentDidMount() {
       await fetchUI();
       this.setState({ uiSectionsLoaded: true });
-      fetchData({
+      // The chart waits for the stats so its field and context can be checked against them.
+      let stats = null;
+      await fetchData({
         numDays: this.state.numDays,
         date: this.state.date,
         getDataFn,
-        onLoadComplete: (stats) => this.setState({ stats }),
+        onLoadComplete: (s) => (stats = s),
       });
-      fetchChartData({
-        numDays: this.state.numDays,
-        date: this.state.date,
-        chartContext: this.state.chartContext,
+      const { chartField, chartContext } = resolveChartDefaults({
         chartField: this.state.chartField,
-        getDataFn,
-        onLoadProgress: (i, n) => {
-          this.setState({ chartData: { loading: { max: n, value: i } } });
-        },
-        onLoadComplete: (data, max) => {
-          this.setState({ chartData: { loading: false, data, max } });
-        },
+        chartContext: this.state.chartContext,
+        stats,
+        contexts: UI.chartContexts,
       });
+      this.setState({ stats, chartField, chartContext });
+      this.fetchChartData({ chartField, chartContext });
     }
 
     async fetchChartData({ numDays, date, chartContext, chartField }) {
@@ -881,7 +922,7 @@ th {
                     !chartData.loading &&
                     m`
                       <div class="bar-chart__scale">${chartData.max}</div>
-                      ${chartData.data.map(
+                      ${(chartData.data || []).map(
                         (v) =>
                           m`
                             <div
@@ -900,15 +941,15 @@ th {
                   </div>
                 </section>
                 ${(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

@@ -7,6 +7,36 @@
 
   var m=e.bind(_);
 
+  // A Date whose UTC fields hold the current Pacific wall-clock time, so `iso()` (which reads UTC
+  // fields) names the Pacific day. The instant it represents is not "now"; it is only for day buckets.
+  const nowAsPstDate = (now = new Date()) => {
+    const parts = Object.fromEntries(
+      new Intl.DateTimeFormat("en-US", {
+        timeZone: "America/Los_Angeles",
+        hourCycle: "h23",
+        year: "numeric",
+        month: "numeric",
+        day: "numeric",
+        hour: "numeric",
+        minute: "numeric",
+        second: "numeric",
+      })
+        .formatToParts(now)
+        .map((p) => [p.type, p.value])
+    );
+    return new Date(
+      Date.UTC(
+        Number(parts.year),
+        Number(parts.month) - 1,
+        Number(parts.day),
+        Number(parts.hour),
+        Number(parts.minute),
+        Number(parts.second),
+        now.getMilliseconds()
+      )
+    );
+  };
+
   function iso(time) {
     return [
       time.getUTCFullYear(),
@@ -15,6 +45,10 @@
     ].join("-");
   }
 
+  // Today's calendar date in Pacific time as YYYY-MM-DD (daylight saving included), the same day
+  // buckets the server uses. The dashboard page defaults its date to this, not the browser's UTC date.
+  const pacificToday = (now = new Date()) => iso(nowAsPstDate(now));
+
   /* START methods for fetching data from the server */
 
   const dataCache = {};
@@ -87,6 +121,18 @@
 
   /* END methods for fetching data from the server */
 
+  // Keeps the preferred chart field/context when they exist, otherwise falls back to the first
+  // available one, so the menus (which show the first option when nothing matches) and the chart agree.
+  function resolveChartDefaults({ chartField, chartContext, stats, contexts }) {
+    const fields = Object.keys(stats?.metrics?.all || {});
+    const contextIds = (contexts || []).map((c) => c.id);
+    return {
+      chartField: fields.length && !fields.includes(chartField) ? fields[0] : chartField,
+      chartContext:
+        contextIds.length && !contextIds.includes(chartContext) ? contextIds[0] : chartContext,
+    };
+  }
+
   /* START helper methods */
 
   const getJson = async (url) => {
@@ -224,8 +270,6 @@
     }
   }
 
-  const DATE = new Date().toISOString().split("T")[0];
-
   const Logo = () => m`
   <svg
     width="256"
@@ -305,7 +349,7 @@
       super(props);
       this.state = {
         numDays: 30,
-        date: DATE,
+        date: pacificToday(),
         chartField: "users",
         chartContext: "all",
         uiSectionsLoaded: false,
@@ -315,25 +359,22 @@
     async componentDidMount() {
       await fetchUI();
       this.setState({ uiSectionsLoaded: true });
-      fetchData({
+      // The chart waits for the stats so its field and context can be checked against them.
+      let stats = null;
+      await fetchData({
         numDays: this.state.numDays,
         date: this.state.date,
         getDataFn,
-        onLoadComplete: (stats) => this.setState({ stats }),
+        onLoadComplete: (s) => (stats = s),
       });
-      fetchChartData({
-        numDays: this.state.numDays,
-        date: this.state.date,
-        chartContext: this.state.chartContext,
+      const { chartField, chartContext } = resolveChartDefaults({
         chartField: this.state.chartField,
-        getDataFn,
-        onLoadProgress: (i, n) => {
-          this.setState({ chartData: { loading: { max: n, value: i } } });
-        },
-        onLoadComplete: (data, max) => {
-          this.setState({ chartData: { loading: false, data, max } });
-        },
+        chartContext: this.state.chartContext,
+        stats,
+        contexts: UI.chartContexts,
       });
+      this.setState({ stats, chartField, chartContext });
+      this.fetchChartData({ chartField, chartContext });
     }
 
     async fetchChartData({ numDays, date, chartContext, chartField }) {
@@ -483,7 +524,7 @@
                     !chartData.loading &&
                     m`
                       <div class="bar-chart__scale">${chartData.max}</div>
-                      ${chartData.data.map(
+                      ${(chartData.data || []).map(
                         (v) =>
                           m`
                             <div
@@ -502,15 +543,15 @@
                   </div>
                 </section>
                 ${(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.1",
+  "version": "0.1.3",
   "description": "A single server drop-in file system based metrics and analytics library.",
   "main": "src/index.js",
   "exports": {

package/src/public/js/App.js

@@ -7,10 +7,10 @@ import {
   getData,
   fetchChartData,
   fetchData,
+  resolveChartDefaults,
 } from "./util.js";
 import Tile from "./Tile.js";
-
-const DATE = new Date().toISOString().split("T")[0];
+import { pacificToday } from "../../shared/utils.js";
 
 const Logo = () => html`
   <svg
@@ -91,7 +91,7 @@ class App extends Component {
     super(props);
     this.state = {
       numDays: 30,
-      date: DATE,
+      date: pacificToday(),
       chartField: "users",
       chartContext: "all",
       uiSectionsLoaded: false,
@@ -101,25 +101,22 @@ class App extends Component {
   async componentDidMount() {
     await fetchUI();
     this.setState({ uiSectionsLoaded: true });
-    fetchData({
+    // The chart waits for the stats so its field and context can be checked against them.
+    let stats = null;
+    await fetchData({
       numDays: this.state.numDays,
       date: this.state.date,
       getDataFn,
-      onLoadComplete: (stats) => this.setState({ stats }),
+      onLoadComplete: (s) => (stats = s),
     });
-    fetchChartData({
-      numDays: this.state.numDays,
-      date: this.state.date,
-      chartContext: this.state.chartContext,
+    const { chartField, chartContext } = resolveChartDefaults({
       chartField: this.state.chartField,
-      getDataFn,
-      onLoadProgress: (i, n) => {
-        this.setState({ chartData: { loading: { max: n, value: i } } });
-      },
-      onLoadComplete: (data, max) => {
-        this.setState({ chartData: { loading: false, data, max } });
-      },
+      chartContext: this.state.chartContext,
+      stats,
+      contexts: UI.chartContexts,
     });
+    this.setState({ stats, chartField, chartContext });
+    this.fetchChartData({ chartField, chartContext });
   }
 
   async fetchChartData({ numDays, date, chartContext, chartField }) {
@@ -269,7 +266,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
@@ -288,15 +285,15 @@ class App extends Component {
                   </div>
                 </section>
                 ${(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

@@ -72,6 +72,18 @@ export async function fetchData({
 
 /* END methods for fetching data from the server */
 
+// Keeps the preferred chart field/context when they exist, otherwise falls back to the first
+// available one, so the menus (which show the first option when nothing matches) and the chart agree.
+export function resolveChartDefaults({ chartField, chartContext, stats, contexts }) {
+  const fields = Object.keys(stats?.metrics?.all || {});
+  const contextIds = (contexts || []).map((c) => c.id);
+  return {
+    chartField: fields.length && !fields.includes(chartField) ? fields[0] : chartField,
+    chartContext:
+      contextIds.length && !contextIds.includes(chartContext) ? contextIds[0] : chartContext,
+  };
+}
+
 /* START helper methods */
 
 export const getJson = async (url) => {

package/src/shared/utils.js

@@ -65,3 +65,7 @@ export function defaultEndDate(now = nowAsPstDate()) {
   yesterday.setUTCHours(0, 0, 0, 0);
   return yesterday;
 }
+
+// Today's calendar date in Pacific time as YYYY-MM-DD (daylight saving included), the same day
+// buckets the server uses. The dashboard page defaults its date to this, not the browser's UTC date.
+export const pacificToday = (now = new Date()) => iso(nowAsPstDate(now));