@drift-beacon/plugin 0.2.1 → 0.2.3

package/README.md

@@ -222,6 +222,8 @@ Settings items have `name` (unique), `title`, `type` and optional `description`
 
 `connect()` performs a handshake with the web app and resolves to the UI `ctx`. It rejects with `unsupported` when the app doesn't run this UI's API version, and with `unavailable` outside Drift Beacon or after 10 seconds without an answer. `ctx.onDataChange` fires after every update (data, settings, storage, or other plugins' status and state; not their events).
 
+The app runs a built UI in a sandboxed frame (`allow-scripts` only): it has no storage, cookies, popups or modal dialogs, and a `<form>` never submits. Handle Enter and your button's press yourself instead of relying on a form's `submit`.
+
 With React, re-render on every update:
 
 ```tsx
@@ -256,6 +258,8 @@ Models keep their identity when their data changes: key `React.memo` and `useMem
 const activity = ctx.activities.get(id);
 activity?.category?.name;   // links
 activity?.isLive;           // the current user has a live session of it
+activity?.isPinned;         // the current user has it pinned
+activity?.goal;             // { type: "duration", seconds } or { type: "count", count }, or null
 await activity?.track();    // start a span / mark a point
 activity?.data;             // the plain row, a new frozen object whenever it changes
 
@@ -277,10 +281,22 @@ ctx.sessions.live({ mine: true });
 {activity.iconPath && <svg viewBox="0 0 24 24" fill="currentColor"><path d={activity.iconPath} /></svg>}
 ```
 
+- From 0.2.2, activities carry their goal, its period and their pins:
+  - `goal` is `{ type: "duration", seconds }` or `{ type: "count", count }`, or `null` when the activity has none. A point activity's goal always counts marks; a span activity's counts sessions or totals their duration, as the user chose.
+  - `period` is `"day"`, `"week"`, `"month"` or `"year"`: calendar periods from local midnight, weeks starting on Sunday. `null` means progress covers all history. Local means the browser's time zone in a UI, like the app's own progress, but the server's (its `TZ` environment variable) in main code: if the server runs in UTC and the user doesn't, main code's periods are off by the whole difference, all period long. Set `TZ` on the server to the household's zone.
+  - `pinnedBy` lists the users who have the activity pinned (each user pins at most one). Main code sees every user's pins, a UI only its own user's. `isPinned` is the current user's pin in both.
+  - Progress isn't included: add up `sessions()` in the current period. Drift Beacon counts every member's completed sessions from the period's start (a span counts on the day it started), plus the time so far of the current user's live session.
+  - A Drift Beacon older than 0.2.2 provides none of these, to main code as well as to UIs (main code uses the models of the Drift Beacon that runs it): `goal`, `period` and `pinnedBy` are `undefined`, which is why they are optional and how to tell (from 0.2.2, `pinnedBy` is always an array), and `isPinned` is `false` in a UI but `undefined` in main code. Test `isPinned` for truthiness.
+
+```ts
+// The activity to show: the user's live one, else the one they pinned.
+const shown = ctx.sessions.live({ mine: true })[0]?.activity ?? ctx.activities.list().find((a) => a.isPinned);
+```
+
 | Activity | |
 |---|---|
-| `id`, `name`, `description`, `trackingType`, `icon`, `iconPath`, `color`, `categoryId`, `archived`, `sortOrder`, `unit` | Fields (`color` is resolved from the category when needed) |
-| `isSpan`, `isPoint`, `isLive`, `category` | Derived values and links |
+| `id`, `name`, `description`, `trackingType`, `icon`, `iconPath`, `color`, `categoryId`, `archived`, `sortOrder`, `unit`, `goal`, `period`, `pinnedBy` | Fields (`color` is resolved from the category when needed) |
+| `isSpan`, `isPoint`, `isLive`, `isPinned`, `category` | Derived values and links |
 | `sessions(filter?)`, `live({ mine? })` | Its sessions |
 | `start()`, `mark()`, `track()`, `end()` | Actions (`end()` ends the current user's live session of it) |
 
@@ -461,8 +477,25 @@ Users add the repository URL in **Plugins → Repositories** and install from th
 
 - `apiVersion` in the manifest must match the SDK: `dbplugin`, `vite build` and the server all check it.
 - Before 1.0, each minor version (`0.1`, `0.2`) may change the API, and a server runs only its exact version. Install the SDK with `@0.2` to stay on it.
-- Patch releases (`0.2.x`) fix bugs and may add to API 0.2. An addition that needs the app, such as UI events in 0.2.1, does nothing on an older Drift Beacon. Ignore fields and string values you don't recognise (such as a new `trackingType`).
+- Patch releases (`0.2.x`) fix bugs and may add to API 0.2. An addition that needs the app, such as UI events in 0.2.1 or activity goals and pins in 0.2.2, does nothing on an older Drift Beacon. Ignore fields and string values you don't recognise (such as a new `trackingType`).
 
 ## License
 
 MIT
+
+## Host theme (SDK 0.2.3)
+
+`connect()` installs the host's theme as `--db-*` CSS variables on `<html>` before resolving. It keeps them synchronized without reloading the UI. It also sets `data-color-mode`, `color-scheme`, and the `light`/`dark` class. Use semantic tokens instead of copying the app's palette or forcing a dark class.
+
+```css
+body { background: var(--db-background); color: var(--db-foreground); }
+.card { background: var(--db-surface); color: var(--db-surface-foreground); border: 1px solid var(--db-border); }
+```
+
+The tokens are `background`, `foreground`, `surface`, `surface-foreground`, `surface-raised`, `muted`, `border`, `accent`, `accent-foreground`, `danger`, `danger-foreground`, `success`, `success-foreground`, `warning`, `warning-foreground`, and `focus`, all prefixed with `--db-`. `background` is the containing surface; `surface` is a card; `surface-raised` is a more prominent surface. Values are complete CSS colors, not HSL channels. Activity and device colors remain domain data, separate from these UI colors.
+
+`ctx.theme: UiTheme` is an immutable snapshot (`mode: "light" | "dark"`, `colors: UiThemeColors` using camelCase token names). `ctx.onThemeChange(callback): Unsubscribe` runs after CSS is updated, only when the theme changes. Canvas/chart renderers can subscribe here; theme-only updates do not fire `onDataChange`. Convert CSS colors to sRGB if the rendering library does not accept modern CSS color syntax.
+
+Older hosts omit the theme. The SDK then supplies a stable dark fallback palette; an old-host reconnect restores that fallback. Missing theme fields in ordinary state updates leave the current theme unchanged. Invalid theme snapshots are ignored. Older UI bundles ignore the new fields and keep their existing appearance; rebuild and migrate their styles to adopt them.
+
+Render the main UI after `connect()` resolves. Give loading/error UI fallback colors, and handle a rejected connection. Framework adapters should map their library's colors to these tokens; the SDK does not require React or HeroUI.

package/dist/internal/models.js

@@ -11,6 +11,9 @@ const ACTIVITY_FIELDS = [
     "archived",
     "sortOrder",
     "unit",
+    "goal",
+    "period",
+    "pinnedBy",
 ];
 const CATEGORY_FIELDS = [
     "id",
@@ -61,6 +64,9 @@ class ActivityModel {
     get isLive() {
         return this.live({ mine: true }).length > 0;
     }
+    get isPinned() {
+        return this.data.pinnedBy?.includes(this.#models.userId) ?? false;
+    }
     get category() {
         const categoryId = this.data.categoryId;
         return categoryId === null ? undefined : this.#models.category(categoryId);

package/dist/internal/theme.js

@@ -0,0 +1,75 @@
+export const THEME_COLOR_KEYS = [
+    "background",
+    "foreground",
+    "surface",
+    "surfaceForeground",
+    "surfaceRaised",
+    "muted",
+    "border",
+    "accent",
+    "accentForeground",
+    "danger",
+    "dangerForeground",
+    "success",
+    "successForeground",
+    "warning",
+    "warningForeground",
+    "focus",
+];
+export function fallbackTheme(mode = "dark") {
+    const dark = mode === "dark";
+    return Object.freeze({
+        mode,
+        colors: Object.freeze({
+            background: dark ? "#09090b" : "#f8f8f8",
+            foreground: dark ? "#fafafa" : "#18181b",
+            surface: dark ? "#18181b" : "#ffffff",
+            surfaceForeground: dark ? "#fafafa" : "#18181b",
+            surfaceRaised: dark ? "#27272a" : "#f4f4f5",
+            muted: dark ? "#a1a1aa" : "#71717a",
+            border: dark ? "#3f3f46" : "#d4d4d8",
+            accent: "#2563eb",
+            accentForeground: "#ffffff",
+            danger: dark ? "#ef4444" : "#b91c1c",
+            dangerForeground: "#ffffff",
+            success: dark ? "#4ade80" : "#15803d",
+            successForeground: dark ? "#052e16" : "#ffffff",
+            warning: dark ? "#fbbf24" : "#a16207",
+            warningForeground: dark ? "#422006" : "#ffffff",
+            focus: "#3b82f6",
+        }),
+    });
+}
+export function readTheme(value) {
+    if (!value || typeof value !== "object")
+        return;
+    const { mode, colors } = value;
+    if ((mode !== "light" && mode !== "dark") || !colors || typeof colors !== "object")
+        return;
+    const result = {};
+    for (const key of THEME_COLOR_KEYS) {
+        const color = colors[key];
+        if (typeof color !== "string" ||
+            !color.trim() ||
+            color.length > 512 ||
+            /[;{}]/.test(color) ||
+            /(?:var|url)\s*\(/i.test(color))
+            return;
+        if (typeof CSS !== "undefined" && CSS.supports && !CSS.supports("color", color))
+            return;
+        result[key] = color;
+    }
+    return Object.freeze({ mode, colors: Object.freeze(result) });
+}
+export function applyTheme(theme) {
+    if (typeof document === "undefined")
+        return;
+    const root = document.documentElement;
+    for (const key of THEME_COLOR_KEYS) {
+        root.style.setProperty(`--db-${key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`, theme.colors[key]);
+    }
+    root.dataset.colorMode = theme.mode;
+    root.style.colorScheme = theme.mode;
+    root.classList.toggle("dark", theme.mode === "dark");
+    root.classList.toggle("light", theme.mode === "light");
+}

package/dist/types.d.ts

@@ -4,11 +4,25 @@
  * Workspace data comes as models: an `Activity`, `Category` or `Session` with its fields, links,
  * derived values and actions. Models read the latest snapshot the app sent, synchronously; there is
  * one model per row for the life of a `ctx`, and `model.data` is its plain, frozen row. Later API
- * versions may add fields and new values to string unions such as `trackingType`, so plugins must
- * ignore what they don't recognise.
+ * versions may add fields and new values to string unions such as `trackingType`, `goal.type` and
+ * `period`, so plugins must ignore what they don't recognise.
  */
 /** Stops a subscription. Subscriptions made through `ctx` also stop when the instance stops. */
 export type Unsubscribe = () => void;
+/** An activity's goal: a total duration (seconds) or a number of times, per period. */
+export type ActivityGoal = {
+    readonly type: "duration";
+    readonly seconds: number;
+} | {
+    readonly type: "count";
+    readonly count: number;
+};
+/**
+ * The calendar period a goal resets over, starting at local midnight (weeks start on Sunday). Local is the browser's
+ * time zone in a UI, like the app's own progress, but the server process's (its `TZ`) in main code, which can be hours
+ * off the user's for the whole period.
+ */
+export type GoalPeriod = "day" | "week" | "month" | "year";
 /** An activity's plain row: what `activity.data` returns. */
 export interface ActivityData {
     readonly id: string;
@@ -25,6 +39,24 @@ export interface ActivityData {
     /** Position within the activity's category. */
     readonly sortOrder: number;
     readonly unit: string | null;
+    /**
+     * The activity's goal (from 0.2.2), or null when it has none. A point activity's goal is always a count of marks; a
+     * span activity's counts sessions or totals their duration, as the user chose. Progress isn't included: work it out
+     * from the sessions in the current `period`. `undefined` when the Drift Beacon running the plugin predates goals
+     * (main code and UIs alike).
+     */
+    readonly goal?: ActivityGoal | null;
+    /**
+     * The period progress towards `goal` covers (from 0.2.2), or null when it covers all history. `undefined` when the
+     * Drift Beacon running the plugin predates goals.
+     */
+    readonly period?: GoalPeriod | null;
+    /**
+     * Users who have this activity pinned, sorted (from 0.2.2); a user pins at most one activity. Main code sees every
+     * user's pins, a UI only its own user's: use `isPinned` for the current user. `undefined` when the Drift Beacon
+     * running the plugin predates pins.
+     */
+    readonly pinnedBy?: readonly string[];
 }
 /** A category's plain row: what `category.data` returns. */
 export interface CategoryData {
@@ -63,6 +95,11 @@ export interface Activity extends Readonly<ActivityData>, Model<ActivityData> {
     readonly isPoint: boolean;
     /** The current user has a live session of this activity. */
     readonly isLive: boolean;
+    /**
+     * The current user has this activity pinned (from 0.2.2). Test it for truthiness: main code gets its models from the
+     * Drift Beacon running it, and on one older than 0.2.2 this is `undefined` (a UI bundles its own models: false).
+     */
+    readonly isPinned: boolean;
     readonly category: Category | undefined;
     /** This activity's sessions, newest first. */
     sessions(filter?: Omit<SessionFilter, "activityId">): readonly Session[];
@@ -252,4 +289,28 @@ export interface PluginsApi {
     /** This plugin itself, as other plugins see it. */
     readonly self: PluginPeer;
 }
+/** Semantic colors supplied by the UI host (SDK 0.2.3). Values are complete CSS colors. */
+export interface UiThemeColors {
+    readonly background: string;
+    readonly foreground: string;
+    readonly surface: string;
+    readonly surfaceForeground: string;
+    readonly surfaceRaised: string;
+    readonly muted: string;
+    readonly border: string;
+    readonly accent: string;
+    readonly accentForeground: string;
+    readonly danger: string;
+    readonly dangerForeground: string;
+    readonly success: string;
+    readonly successForeground: string;
+    readonly warning: string;
+    readonly warningForeground: string;
+    readonly focus: string;
+}
+/** An immutable theme snapshot. background is the surface containing this plugin. */
+export interface UiTheme {
+    readonly mode: "light" | "dark";
+    readonly colors: Readonly<UiThemeColors>;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/ui.d.ts

@@ -1,9 +1,13 @@
-import type { ActivitiesApi, CategoriesApi, PluginConfig, PluginInfo, PluginsApi, SessionsApi, StorageApi, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
+import type { ActivitiesApi, CategoriesApi, PluginConfig, PluginInfo, PluginsApi, SessionsApi, StorageApi, UiTheme, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
 export { PluginError } from "./errors.ts";
 export type * from "./types.ts";
 export { API_VERSION } from "./version.ts";
 /** Everything a plugin UI can use. */
 export interface UiContext {
+    /** Current host theme; SDK 0.2.3 applies --db-* variables before connect resolves. Older hosts use a dark fallback. */
+    readonly theme: UiTheme;
+    /** Theme-only updates do not fire onDataChange. CSS updates before this callback runs. */
+    onThemeChange(callback: (theme: UiTheme) => void): Unsubscribe;
     /** The installed plugin; it can change while the UI is open, for example to a new version. */
     readonly plugin: PluginInfo;
     readonly user: UserInfo;

package/dist/ui.js

@@ -6,6 +6,7 @@ import { jsonEqual } from "./internal/json-equal.js";
 import { WorkspaceModels } from "./internal/models.js";
 import { commandArgumentsProblem, commandBudgetMs, eventNameProblem, samePluginStatus } from "./internal/peers.js";
 import { isUiMessage, UI_CHANNEL, } from "./internal/protocol.js";
+import { applyTheme, fallbackTheme, readTheme } from "./internal/theme.js";
 import { API_VERSION } from "./version.js";
 export { PluginError } from "./errors.js";
 export { API_VERSION } from "./version.js";
@@ -80,6 +81,8 @@ function open(timeoutMs) {
 class UiClient {
     post;
     context;
+    theme;
+    themeListeners = new Set();
     config;
     plugin;
     rows = {
@@ -107,6 +110,8 @@ class UiClient {
     peerObjects = new Map();
     constructor(welcome, post) {
         this.post = post;
+        this.theme = readTheme(welcome.theme) ?? fallbackTheme();
+        applyTheme(this.theme);
         this.config = welcome.config;
         this.plugin = welcome.plugin;
         this.peersShared = welcome.peers !== undefined;
@@ -129,6 +134,10 @@ class UiClient {
         const apis = this.models.apis();
         const self = this;
         this.context = {
+            get theme() {
+                return self.theme;
+            },
+            onThemeChange: (callback) => subscribe(self.themeListeners, callback),
             get plugin() {
                 return self.plugin;
             },
@@ -283,6 +292,7 @@ class UiClient {
     receive(message) {
         if (message.type === "welcome") {
             this.plugin = message.plugin;
+            this.updateTheme(readTheme(message.theme) ?? fallbackTheme());
             this.receive({
                 channel: message.channel,
                 type: "state",
@@ -310,6 +320,11 @@ class UiClient {
         }
         if (message.type !== "state")
             return;
+        if (message.theme) {
+            const theme = readTheme(message.theme);
+            if (theme)
+                this.updateTheme(theme);
+        }
         if (message.config)
             this.config = message.config;
         if (message.data)
@@ -321,7 +336,16 @@ class UiClient {
         }
         if (message.peers)
             this.applyPeers(message.peers);
-        notify(this.dataListeners, (listener) => listener());
+        if (message.config || message.data || message.storage || message.peers) {
+            notify(this.dataListeners, (listener) => listener());
+        }
+    }
+    updateTheme(theme) {
+        if (jsonEqual(this.theme, theme))
+            return;
+        this.theme = theme;
+        applyTheme(theme);
+        notify(this.themeListeners, (listener) => listener(theme));
     }
     applyEvent({ plugin, event, payload }) {
         if (!this.listed.has(plugin))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drift-beacon/plugin",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "The Drift Beacon plugin SDK: APIs for plugin main code and UIs, the driftBeacon() Vite plugin and the dbplugin CLI",
   "license": "MIT",
   "author": {