devicectl-core 0.1.0__py3-none-any.whl

devicectl/web/static/js/drafts.js

@@ -0,0 +1,312 @@
+/* Unsent edits: one store for the whole page, a view of it for each card,
+ * and the header's count of everything that is waiting.
+ *
+ * Each card used to hold its own edits in its own `useState`.  That had
+ * three consequences that were each worth fixing and that one store fixes
+ * together.  A card that was not on screen -- a tab switched away from, in
+ * a program that only builds the tab being looked at -- lost what had been
+ * typed into it.  Two cards showing the same setting (a protection on the
+ * dashboard's band and in the settings table) each had their own idea of
+ * whether it had been changed.  And the header could only ever speak for
+ * one page's edits, so an edit on a card with an Apply of its own was
+ * invisible from anywhere but that card.
+ *
+ * So edits live here, in module state, filed by *scope*: the name of the
+ * thing a write goes to -- a device's settings table, one endpoint of a
+ * charger.  A card asks for a view of its scope, narrowed to the names it
+ * shows if it shares the scope with other cards; the view counts, clears
+ * and applies only those.  Whoever knows how to send a scope says so once,
+ * with `offerWriter`, and from then on the card's tick, the header's Apply
+ * and anything else that asks all send it the same way.
+ *
+ * It belongs to the device, not to the tree: the program calls
+ * `resetDrafts` when the device changes, since an edit made for one battery
+ * is not an edit for the next.
+ */
+
+import { Confirm } from '/core/js/ui.js';
+import { html, useEffect, useState } from '/core/vendor/preact-htm.module.js';
+
+const scopes = new Map(); // scope -> { edits, writer }
+const listeners = new Set();
+let applying = false;
+let asking = null; // { jobs, answer } while the plan is on screen
+
+function held(scope) {
+  if (!scopes.has(scope)) scopes.set(scope, { edits: {}, writer: null });
+  return scopes.get(scope);
+}
+
+function announce() {
+  for (const listener of [...listeners]) listener();
+}
+
+/* A key's field: `cellConWireRes[3]` is an element of `cellConWireRes`, and
+ * a card that shows the field shows every element of it. */
+function field(key) {
+  return key.replace(/\[\d+\]$/, '');
+}
+
+function narrow(edits, names) {
+  if (!names) return edits;
+  return Object.fromEntries(Object.entries(edits).filter(([key]) => names.has(field(key))));
+}
+
+/* Drop what was sent, and only if it is still what was sent. */
+function settle(scope, sent) {
+  const entry = held(scope);
+  const next = { ...entry.edits };
+  for (const [key, value] of Object.entries(sent)) {
+    if (key in next && next[key] === value) delete next[key];
+  }
+  entry.edits = next;
+}
+
+/* Re-render on any change to the store.  Every view calls it; so does
+ * anything else that shows a count. */
+export function useDrafts() {
+  const [, bump] = useState(0);
+  useEffect(() => {
+    const wake = () => bump((n) => n + 1);
+    listeners.add(wake);
+    return () => {
+      listeners.delete(wake);
+    };
+  }, []);
+}
+
+/* Forget every edit: another device. */
+export function resetDrafts() {
+  for (const entry of scopes.values()) entry.edits = {};
+  asking?.answer(false);
+  asking = null;
+  announce();
+}
+
+/* How a scope is sent.  Called while rendering, by whoever has what it
+ * takes -- the program, for a scope several tabs edit; the card itself,
+ * where only it does -- and the latest call wins, so `busy` and `disabled`
+ * are always the current ones.  It is not a hook and takes nothing down
+ * when its caller goes away: a tab that is not on screen still has edits,
+ * and the header must still be able to send them.
+ *
+ *   write(edits)  -> a promise; the edits are dropped when it resolves.
+ *   plan(edits)   -> a promise of the changes it would make, each
+ *                    `{ name, label, oldText, newText }`: shown, and asked
+ *                    about, before `write`.  Left out, `write` goes at once.
+ *   title         -> what the scope is called where several are asked
+ *                    about together.
+ *
+ * `write` and `plan` say what went wrong themselves (a toast); a rejection
+ * here only stops what was going to follow it. */
+export function offerWriter(scope, writer) {
+  held(scope).writer = writer;
+}
+
+/* One card's edits: the scope's, or those of `names` among them.
+ *
+ * `get` is the whole point: a field reads through the draft and falls back
+ * to what the device last said, so an untouched value keeps following the
+ * device between polls while an edited one stays put.  `apply` sends this
+ * view's edits the way the scope's writer says to, and `clear` drops them. */
+export function useDraft(scope, { names } = {}) {
+  useDrafts();
+  const only = names ? new Set(names) : null;
+  const entry = held(scope);
+  const edits = narrow(entry.edits, only);
+  const count = Object.keys(edits).length;
+  return {
+    scope,
+    edits,
+    count,
+    dirty: count > 0,
+    get: (key, live) => (key in entry.edits ? entry.edits[key] : live),
+    has: (key) => key in entry.edits,
+    set: (key, value) => {
+      entry.edits = { ...entry.edits, [key]: value };
+      announce();
+    },
+    drop: (key) => {
+      if (!(key in entry.edits)) return;
+      const next = { ...entry.edits };
+      delete next[key];
+      entry.edits = next;
+      announce();
+    },
+    clear: () => {
+      const keep = only
+        ? Object.fromEntries(Object.entries(entry.edits).filter(([key]) => !only.has(field(key))))
+        : {};
+      entry.edits = keep;
+      announce();
+    },
+    apply: () => applyDrafts([{ scope, names: only }]),
+    /* Whether this view has somewhere to go, and whether it can go now --
+     * read when the card draws, after the writer has been offered. */
+    get writable() {
+      return Boolean(held(scope).writer);
+    },
+    get busy() {
+      return applying || Boolean(held(scope).writer?.busy);
+    },
+    get disabled() {
+      return Boolean(held(scope).writer?.disabled);
+    },
+  };
+}
+
+/* Everything waiting, across every scope. */
+function pendingCount() {
+  let n = 0;
+  for (const entry of scopes.values()) n += Object.keys(entry.edits).length;
+  return n;
+}
+
+/* Send some scopes' edits: plan the ones that plan, ask once about all of
+ * it, then write them in turn.  A write that fails stops the rest, and what
+ * was not written stays in the draft to be tried again. */
+export async function applyDrafts(parts) {
+  if (applying) return;
+  const jobs = parts
+    .map(({ scope, names }) => {
+      const entry = held(scope);
+      return { scope, writer: entry.writer, edits: narrow(entry.edits, names) };
+    })
+    .filter((job) => job.writer && !job.writer.disabled && Object.keys(job.edits).length);
+  if (!jobs.length) return;
+  applying = true;
+  announce();
+  try {
+    if (jobs.some((job) => job.writer.plan)) {
+      for (const job of jobs) {
+        job.changes = job.writer.plan ? await job.writer.plan(job.edits) : null;
+      }
+      const yes = await new Promise((answer) => {
+        asking = { jobs, answer };
+        announce();
+      });
+      /* A value the device already holds is not an edit, whatever the
+       * answer was: the plan has just said so. */
+      for (const job of jobs) if (job.changes && !job.changes.length) settle(job.scope, job.edits);
+      if (!yes) return;
+    }
+    for (const job of jobs) {
+      if (job.changes && !job.changes.length) continue;
+      await job.writer.write(job.edits);
+      settle(job.scope, job.edits);
+    }
+  } catch {
+    /* The writer has said what went wrong. */
+  } finally {
+    applying = false;
+    asking = null;
+    announce();
+  }
+}
+
+function applyAll() {
+  return applyDrafts([...scopes.keys()].map((scope) => ({ scope })));
+}
+
+function discardAll() {
+  for (const entry of scopes.values()) entry.edits = {};
+  announce();
+}
+
+/* --- the header's count ---------------------------------------------------
+ *
+ * Every card with an edit says so in its own title, with its own tick and
+ * cross.  This is the same thing for the whole page, pinned to the top of
+ * the window: how many edits are waiting anywhere -- on this tab or on
+ * one not being looked at -- a way to drop them all and a way to send them
+ * all.  Nothing at all until something has been changed.  See `.page-apply`
+ * in core.css for why it moves nothing else in the header. */
+export function PageApply() {
+  useDrafts();
+  const count = pendingCount();
+  if (!count) return null;
+  const what = `${count} change${count === 1 ? '' : 's'}`;
+  const said = `${what} not sent yet`;
+  const writable = [...scopes.values()].some(
+    (entry) => entry.writer && !entry.writer.disabled && Object.keys(entry.edits).length
+  );
+  const busy = applying || [...scopes.values()].some((entry) => entry.writer?.busy);
+  return html`<div class="page-apply" role="group" aria-label=${said}>
+    <span class="dot" aria-hidden="true"></span>
+    <span class="state">${said}</span>
+    <button class="btn small ghost" disabled=${applying} onClick=${discardAll}>Discard</button>
+    <button class="btn small primary" disabled=${busy || !writable} onClick=${applyAll}>
+      Apply ${what}
+    </button>
+  </div>`;
+}
+
+/* --- the plan, before anything goes -------------------------------------- */
+
+function planLine(change) {
+  const label = change.label && change.label !== change.name ? change.label : null;
+  return html`<li key=${change.name}>
+    <span>${label || html`<span class="mono">${change.name}</span>`}</span>
+    <span class="muted">${change.oldText} →</span>
+    <b>${change.newText}</b>
+  </li>`;
+}
+
+/* A plan, asked about: what each value is and what it will be.  The same
+ * dialog whatever made the plan -- a card's tick, the header's Apply, or a
+ * program's own button (a chemistry preset) -- so a write looks the same
+ * however it was asked for. */
+export function PlanDialog({ plan, title, onCancel, onConfirm, note, sections }) {
+  const groups = sections || [{ changes: plan }];
+  const count = groups.reduce((n, group) => n + (group.changes?.length ?? group.count ?? 0), 0);
+  return html`<${Confirm}
+    title=${count ? title || `Apply ${count} change${count === 1 ? '' : 's'}?` : 'Nothing to change'}
+    danger=${false}
+    confirmLabel=${count ? 'Apply' : 'Close'}
+    onCancel=${onCancel}
+    onConfirm=${count ? onConfirm : onCancel}
+    body=${count
+      ? html`<div>
+          <p class="muted">Values the device already holds are left out.</p>
+          ${note || null}
+          ${groups.map((group) =>
+            group.changes
+              ? group.changes.length
+                ? html`<div key=${group.title || 'plan'}>
+                    ${group.title ? html`<h4 class="plan-head">${group.title}</h4>` : null}
+                    <ul class="list">
+                      ${group.changes.map(planLine)}
+                    </ul>
+                  </div>`
+                : null
+              : html`<div key=${group.title}>
+                  <h4 class="plan-head">${group.title}</h4>
+                  <p class="muted">
+                    ${group.count} change${group.count === 1 ? '' : 's'}, sent as they are.
+                  </p>
+                </div>`
+          )}
+        </div>`
+      : html`<p class="muted">The device already holds every value you set.</p>`}
+  />`;
+}
+
+/* Where the question is asked.  Rendered once, at the root of the page: the
+ * header that starts most of these draws its own children inside a blurred
+ * layer, which a dialog cannot escape from. */
+export function DraftDialog() {
+  useDrafts();
+  if (!asking) return null;
+  const { jobs, answer } = asking;
+  const titled = jobs.length > 1;
+  const sections = jobs.map((job) => ({
+    title: titled ? job.writer.title || job.scope : null,
+    changes: job.changes,
+    count: job.changes ? undefined : Object.keys(job.edits).length,
+  }));
+  return html`<${PlanDialog}
+    sections=${sections}
+    onCancel=${() => answer(false)}
+    onConfirm=${() => answer(true)}
+  />`;
+}

devicectl/web/static/js/notify.js

@@ -0,0 +1,272 @@
+/* Being told the page was raised, when you are not looking at the page.
+ *
+ * Raising a tab from inside it is mostly wishful: `window.focus()` is a
+ * silent no-op in Firefox outside a user gesture, and a tab whose title
+ * changed is not highlighted, coloured or animated by anything -- the flash
+ * is only readable when the strip is short enough to show more than
+ * a truncated program name.  A notification is the one signal that leaves
+ * the browser
+ * altogether, and a click on it *is* a user gesture, so its handler is
+ * allowed the `focus()` the event itself is not.
+ *
+ * It has to be asked for, from a click of your own.  Firefox takes
+ * `Notification.requestPermission()` only from a user gesture, and a page
+ * that asks the moment it loads is the reason for that rule; a refusal is
+ * also remembered by the browser for good.  So nothing here happens until
+ * the bell in the header is pressed, and the answer is kept per browser,
+ * next to the theme.
+ */
+
+import { html, useState } from '/core/vendor/preact-htm.module.js';
+
+/* What the program calls itself, in the four sentences this module writes
+ * and in the two keys it keeps: the wish, in this browser's storage, and
+ * the tag that makes a second run replace the first one's note rather than
+ * stack under it.  Set once, from the program's own module, before the
+ * bell is rendered. */
+let program = 'this program';
+let wantKey = 'devicectl-notify';
+let noteTag = 'devicectl-focus';
+
+export function configure({ name }) {
+  program = name;
+  wantKey = `${name}-notify`;
+  noteTag = `${name}-focus`;
+}
+
+/* Long enough to find on another screen, short enough not to pile up. */
+const NOTE_MS = 20000;
+
+/* Notifications are for secure contexts: this page opened on the machine
+ * serving it, or served over https.  Shared over plain http to someone
+ * else's machine (a `--listen` of somebody else's), Firefox and Chrome take
+ * the question away rather than answer it, and the bell has nothing to
+ * offer. */
+function supported() {
+  return (
+    typeof Notification !== 'undefined' &&
+    typeof Notification.requestPermission === 'function' &&
+    window.isSecureContext !== false
+  );
+}
+
+/* Which of the two reasons it is, in a sentence.
+ *
+ * Worth telling apart, because one of them is somebody's own doing and can
+ * be undone.  A program whose device is on the far end of a serial cable
+ * gets run on the machine the cable is in and read from a laptop across the
+ * room, and `http://192.168.1.x:8080` is not a secure context -- so the
+ * same page that had a bell on the machine serving it has none over the
+ * network, which is where it is actually used.  That is worth a sentence
+ * rather than a control that quietly is not there.
+ */
+function whyNot() {
+  return window.isSecureContext === false
+    ? `This page is not a secure context, so the browser will not offer notifications. ` +
+        `Open ${program} on the machine serving it, or put it behind https.`
+    : 'This browser does not offer notifications.';
+}
+
+function permission() {
+  return supported() ? Notification.permission : 'unsupported';
+}
+
+function wanted() {
+  return localStorage.getItem(wantKey) === '1';
+}
+
+/* Show one, and let a click on it do the thing the page may not do itself. */
+function show(title, body) {
+  try {
+    const note = new Notification(title, { body, tag: noteTag, renotify: true });
+    note.onclick = () => {
+      /* A click is a user gesture, so this focus() is honoured where the
+       * one the focus event tries is quietly dropped. */
+      window.focus();
+      note.close();
+    };
+    setTimeout(() => note.close(), NOTE_MS);
+    return true;
+  } catch {
+    /* Android's Chrome sends notifications only through a service worker,
+     * which this page has none of.  Nothing to do but leave it to the
+     * toast, which the tab shows either way. */
+    return false;
+  }
+}
+
+/* The bell's state and the two things it can do, plus the call the event
+ * stream makes when the server says a second run of the program wanted this tab.
+ *
+ * `state` is one of `unsupported` (no notifications in this browser, or not
+ * offered on this page), `off`, `on`, or `blocked` -- refused once, which
+ * only the browser's own site permissions can undo.
+ */
+export function useTabAlerts() {
+  const [state, setState] = useState(() => {
+    const answer = permission();
+    if (answer === 'unsupported') return 'unsupported';
+    if (answer === 'denied') return 'blocked';
+    return answer === 'granted' && wanted() ? 'on' : 'off';
+  });
+
+  /* Call this from a click and from nothing else; the browser will not take
+   * the question any other way.  Returns what it answered. */
+  const enable = async () => {
+    let answer;
+    try {
+      answer = permission() === 'granted' ? 'granted' : await Notification.requestPermission();
+    } catch {
+      answer = 'unsupported'; /* offered, then refused to be asked */
+    }
+    if (answer === 'unsupported') {
+      setState('unsupported');
+      return answer;
+    }
+    if (answer !== 'granted') {
+      setState(answer === 'denied' ? 'blocked' : 'off');
+      return answer;
+    }
+    localStorage.setItem(wantKey, '1');
+    setState('on');
+    /* One right away: it proves the whole path works, at the moment the
+     * question is still in mind, rather than a week later. */
+    return show(`${program} ui`, 'Notifications are on. This is what one looks like.')
+      ? 'granted'
+      : 'unsupported';
+  };
+
+  const disable = () => {
+    localStorage.removeItem(wantKey);
+    setState('off');
+  };
+
+  /* Read the wish and the permission afresh rather than closing over
+   * `state`: this is called from the event stream's handler, wired up on
+   * the first render and remembering nothing since. */
+  const notify = () => {
+    if (!wanted() || permission() !== 'granted') return false;
+    /* You are looking straight at the tab: the toast has already said it. */
+    if (document.hasFocus()) return false;
+    return show(
+      `${program} ui was started again`,
+      'This is the tab it meant -- click here to come back to it.'
+    );
+  };
+
+  return { state, enable, disable, notify };
+}
+
+const BELL_TITLES = {
+  off: 'notify me when this program raises this tab',
+  on: 'notifications are on -- click to turn them off',
+  blocked: 'this browser has blocked notifications for this page',
+  unsupported: 'notifications are not available on this page -- click to find out why',
+};
+
+/* The bell, drawn rather than typed.
+ *
+ * It was the characters U+1F514 and U+1F515, which every platform draws in
+ * its own colour at its own size: a fat orange bell next to a 15px line
+ * drawing of a theme and a 15px line drawing of a pulse.  Same box, same
+ * stroke, same cap as those two, so the header's icons are one set -- and
+ * the same shape in both programs, which a font cannot promise.
+ *
+ * On is the bell; off is the bell with the stroke through it that every
+ * other muted thing wears.  The state is in the shape, not only in the
+ * colour, so it survives a screen with no colour to read.
+ */
+const BELL_SVG = {
+  viewBox: '0 0 16 16',
+  width: 15,
+  height: 15,
+  fill: 'none',
+  stroke: 'currentColor',
+  'stroke-width': 1.5,
+  'stroke-linecap': 'round',
+  'stroke-linejoin': 'round',
+  'aria-hidden': 'true',
+  focusable: 'false',
+};
+
+/* The body, in one stroke: the crown, the shoulder falling away to a skirt
+ * that flares, and the flat lip across the bottom.
+ *
+ * It had been an arch on a rule -- two verticals, a half-round on top and a
+ * line under it -- which is the silhouette of a doorway, a tombstone or a
+ * tunnel, and at fifteen pixels beside a sun and a pulse it read as none of
+ * them in particular.  A bell is recognised by its skirt: the sides do not
+ * come down straight, they swing out at the bottom.  That flare is the
+ * whole of the difference, and it costs two curves. */
+const BELL_BODY =
+  'M8 1.6a4.4 4.4 0 0 0-4.4 4.4c0 2.6-.5 4-1.2 4.9a.6.6 0 0 0 .5 1h10.2a.6.6 0 0 0 .5-1' +
+  'c-.7-.9-1.2-2.3-1.2-4.9A4.4 4.4 0 0 0 8 1.6z';
+
+/* The clapper, swinging under the lip. */
+const BELL_CLAPPER = 'M6.4 13.3a1.7 1.7 0 0 0 3.2 0';
+
+const BELL_ICON = {
+  on: html`<svg ...${BELL_SVG}>
+    <path d=${BELL_BODY} />
+    <path d=${BELL_CLAPPER} />
+  </svg>`,
+  off: html`<svg ...${BELL_SVG}>
+    <path d=${BELL_BODY} />
+    <path d=${BELL_CLAPPER} />
+    <path d="M2.6 13.6 13.4 2.4" />
+  </svg>`,
+};
+
+/* The one control, in the header beside the theme: on, off, blocked and not
+ * ours to unblock, or not on offer here at all.
+ *
+ * Always drawn, including that last case.  It used to return nothing at
+ * all when the browser would not take the question, which is how a program
+ * read over a plain-http `--listen` came to have no bell in its header
+ * while the one next to it, opened on the machine serving it, had one --
+ * the same header, the same module, a control present in one and absent in
+ * the other, with nothing anywhere saying why.  An absent control cannot be
+ * asked what became of it.  This one can: it is there, struck through like
+ * every other muted thing, and clicking it says what would have to change.
+ */
+export function Bell({ alerts, toast }) {
+  const state = alerts.state;
+  const click = async () => {
+    if (state === 'unsupported') {
+      toast.info(whyNot());
+      return;
+    }
+    if (state === 'on') {
+      alerts.disable();
+      toast.info('Notifications off.');
+      return;
+    }
+    if (state === 'blocked') {
+      toast.error(
+        'This browser has blocked notifications for this page. Allow them in its site permissions to turn them on.'
+      );
+      return;
+    }
+    const answer = await alerts.enable();
+    if (answer === 'granted') {
+      toast.ok(`Notifications on: ${program} will say when this is the tab it meant.`);
+    } else if (answer === 'denied') {
+      toast.error(
+        'Notifications blocked. Only this browser can undo that, in its site permissions.'
+      );
+    } else if (answer === 'unsupported') {
+      toast.error('This browser offered notifications and then would not send one.');
+    } else {
+      toast.info('The browser was not answered, so nothing changed.');
+    }
+  };
+  return html`<button
+    class="btn small ghost icon"
+    title=${BELL_TITLES[state]}
+    aria-label=${BELL_TITLES[state]}
+    aria-pressed=${state === 'on'}
+    onClick=${click}
+  >
+    ${BELL_ICON[state === 'on' ? 'on' : 'off']}
+  </button>`;
+}