Add the dashboard settings channel, wired for theme and lock

A dashboard could only ever receive as a set of tiles. This adds the dashboard
itself as a receiver: `settings` maps a name to a value plus an optional
binding. Unbound, the setting is simply its value — a wall panel that is always
dark costs no flow. Bound, a flow drives it live and the value is the fallback.

Two settings are wired: `theme` (system/light/dark) and `locked` (read-only).
There is no schedule field on purpose — a node publishing to the bound message
on a cron is what a schedule is here, which is the point of a channel.

- `messages_for()` now walks a dashboard's bound settings as well as its
  widgets' bindings. Without this a paired screen is refused its own theme
  message, on the one surface the setting exists for; it bounds the socket too.
- `locked` is gated in `usePublish`, so every control inherits it, and each
  control also draws itself disabled — a dead button reads as broken otherwise.
  The panel surface says Read-only in the corner.
- The theme is a class on the dashboard's own surface, never the root: inside
  the app shell it must not flip the chrome. `.light` gains the tokens `.dark`
  already had (mirrored in the index repo) so both directions work on a subtree.
- Settings bindings are type-checked from the document alone, the rule widget
  bindings follow, and mirrored on the server.
- A bound setting is drawn on the flow canvas as a dashboard-level endpoint.
- The demo's house flow now publishes `home.panel_theme`, which the demo
  dashboard's theme binds to: the panel goes dark after sunset, at no tile cost.
This commit is contained in:
2026-08-22 13:17:56 +02:00
parent 9993df456c
commit 1002241258
18 changed files with 784 additions and 62 deletions
@@ -0,0 +1,126 @@
import { createContext, useContext } from "react"
import type { DashboardDef_Output, SettingDef } from "@/client"
import { useLiveValue } from "@/components/Flow/liveStore"
/**
* The dashboard's own settings channel.
*
* A widget is a receiver a dashboard *contains*; this is the dashboard itself
* as one. Each setting is a value plus an optional binding:
*
* - **Unbound** — no message — the setting is simply its value. That is what
* gives a wall panel which is always dark without a flow behind it.
* - **Bound** — a flow drives it live, and the stored value is the fallback:
* what the dashboard uses until something arrives, and whenever the message
* is silent.
*
* A schedule is not a third case. A node publishing to the bound message on a
* cron *is* the schedule here, which is the whole reason this is a channel
* rather than a switching rule bolted onto each setting.
*
* A bound setting is read the way a widget reads a value — the same live store
* and the same socket — so a panel's own settings messages are part of what
* its credential is entitled to (`flow/panels.py`, `messages_for`).
*/
/**
* What a setting may be driven by, by payload type. The same table is enforced
* on the server (`app/flow/dashboards.py`); a name missing from it is a
* setting this build does not act on rather than an error.
*/
export const SETTING_DTYPES: Record<string, string> = {
theme: "str",
locked: "bool",
}
/** The settings this build actually wires up. */
export type SettingName = "theme" | "locked"
/** What `theme` may be set to. `system` follows whatever the device says. */
export const THEME_CHOICES = [
["system", "System"],
["light", "Light"],
["dark", "Dark"],
] as const
/** The generated client marks the map optional, because the server fills it in. */
export function settingOf(
dashboard: DashboardDef_Output | undefined,
name: SettingName,
): SettingDef {
return dashboard?.settings?.[name] ?? {}
}
/**
* What is wrong with a setting's binding, if anything.
*
* Judged from the document alone — the picker records the payload type beside
* the name — so this is the same rule `widgetIssue` holds a tile to, and the
* editor cannot author a document the server would refuse.
*/
export function settingIssue(name: string, setting: SettingDef): string | null {
const want = SETTING_DTYPES[name]
if (!want || !setting.message || !setting.dtype) return null
if (setting.dtype === want) return null
return `${setting.message} is a ${setting.dtype}; ${name} is driven by a ${want}.`
}
/** What the setting is worth now: live if it is bound, stored otherwise. */
function useSetting(
dashboard: DashboardDef_Output | undefined,
name: SettingName,
): unknown {
const setting = settingOf(dashboard, name)
// `undefined` while nothing has arrived, which is exactly when the stored
// value is meant to stand in.
const live = useLiveValue(setting.message || undefined)
return live?.value ?? setting.value
}
/**
* The class that themes a dashboard's own surface, or `""` to follow the app.
*
* A class rather than the root, because inside the app shell this must not
* flip the chrome around it. `.light` and `.dark` both redefine the tokens on
* whatever carries them (`index.css`), so either direction works on a subtree.
*/
export function useDashboardTheme(
dashboard: DashboardDef_Output | undefined,
): "" | "light" | "dark" {
const value = useSetting(dashboard, "theme")
return value === "dark" || value === "light" ? value : ""
}
/** Whether this dashboard is read-only, live if the setting is bound. */
export function useDashboardLocked(
dashboard: DashboardDef_Output | undefined,
): boolean {
return useSetting(dashboard, "locked") === true
}
const LockedContext = createContext(false)
/**
* Marks everything drawn under it read-only.
*
* A context rather than a prop threaded through sixteen renderers: what a
* control needs to know is one bit, and the one place it is acted on is
* `usePublish`. Edit mode deliberately never mounts this — arranging a
* dashboard is not the same as using it.
*/
export function LockedProvider({
dashboard,
children,
}: {
dashboard: DashboardDef_Output | undefined
children: React.ReactNode
}) {
const locked = useDashboardLocked(dashboard)
return (
<LockedContext.Provider value={locked}>{children}</LockedContext.Provider>
)
}
/** Whether the dashboard around this control is read-only. */
export const useLocked = () => useContext(LockedContext)