@supersuit/suggest-a-change 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.1.8 (2026-10-17)
+
+- **The news reaches a person whose entry sits in a menu.** In the Cofounders and Us apps the entry lives in a three-dot menu that stays closed and remounts it on every open, so the 0.1.7 dot was never seen and the toast was drawn inside the closed menu. New in `./client`: `<SuggestNews adapters>`, mounted once at the root, shows the toast with no entry on screen (and keeps the outbox moving); `useSuggestNews(adapters)` returns `{ moved }` for the menu's trigger; `<SuggestDot adapters moved>` draws the entry's dot there (nothing at 0), and the class `sac-dot-host` gives the trigger the `position: relative` it needs. The toast is once per page load and account however many times the entry mounts, whichever of these asks first. `<SuggestEntry>` keeps its own dot and, alone, behaves as in 0.1.7.
+
 ## 0.1.7 (2026-10-17)
 
 - **The person who suggested a change is told when it is being made and when it ends.** `createReportHandlers` takes a required `tellSubmitter(e)`, called once per move to `being-made` or an end (`TOLD`, now in the contract) with `{ member, reportId, status, words, meaning, ended, note? }`. The words are the module's own (`wordsFor`/`meaningFor`), never the report's text; `note` is the one-line reason, on `not-now` only. The planning steps, a repeat, a refused move and a maintainer's own report starting tell nobody, and a failure never fails the move. **Breaking:** without `tellSubmitter` the handlers throw at startup; an app with nobody to tell passes `{ none: "<reason>" }`. The `status` tell event also carries `member` and `status`, and a `not-now` row in the member's list carries its `note`.

package/README.md

@@ -73,7 +73,31 @@ The four diagnostics are the app's version, the time, the screen size and the ph
 
 **Identity.** Every screen asks `adapters.identity()` when it mounts, whenever it is handed a different `adapters` object, and whenever the host calls `refreshIdentity()` (exported from `"./client"`; call it after a sign-in, sign-out or account switch). When the account differs, the old account's rows leave the screen and its waiting reports stay on the phone, to be sent only while that account is signed in; every send re-confirms the account first. Keep `adapters` stable where you can; a parent that rebuilds it every render is safe, only slower (one `identity()` call per render).
 
-**Telling the person in the app, with no setup.** The entry asks `mine()` once when it mounts and compares each report's status with the one this account last opened (kept on the phone beside the cached views, per app and account, and cleared on sign-out). A report that has since been started or ended (`TOLD`) shows a dot on the entry, says New on its row in My suggestions, and the newest such move gets one toast per app open in the module's words (`words.text.movedToast`, given the status's own word and, on `not-now`, the reason: "Your suggestion: Done", "Your suggestion: Not now. too big for now"). Opening the report clears it. A report this phone sees for the first time is recorded silently, so an app taking this release does not announce every old report. The list's `not-now` rows carry their one-line `note` for this. Out of the app, the server's `tellSubmitter` does the telling (below).
+**Telling the person in the app, with no setup.** The entry asks `mine()` once when it mounts and compares each report's status with the one this account last opened (kept on the phone beside the cached views, per app and account, and cleared on sign-out). A report that has since been started or ended (`TOLD`) shows a dot on the entry, says New on its row in My suggestions, and the newest such move gets one toast per page load in the module's words (`words.text.movedToast`, given the status's own word and, on `not-now`, the reason: "Your suggestion: Done", "Your suggestion: Not now. too big for now"). Opening the report clears it. A report this phone sees for the first time is recorded silently, so an app taking this release does not announce every old report. The list's `not-now` rows carry their one-line `note` for this. Out of the app, the server's `tellSubmitter` does the telling (below).
+
+**When the entry sits in a menu.** A host that shows the entry inside a menu that stays closed (a three-dot menu, often remounting its rows on every open) would never show the dot, and the toast would be drawn inside the closed menu. Mount `<SuggestNews>` once at the app's root, always mounted: it asks `mine()` when it mounts, shows the page load's one toast with no entry on screen, and keeps the outbox moving. Put the dot on the menu's own trigger with `useSuggestNews(adapters)`, which returns `{ moved }`, and `<SuggestDot>`, which draws the entry's dot (nothing when `moved` is 0). The trigger needs `position: relative`; the class `sac-dot-host` does it. The toast is once per page load and account however many times the entry mounts, whichever of these asks first. The entry in the menu keeps its own dot.
+
+```tsx
+import { SuggestDot, SuggestEntry, SuggestNews, useSuggestNews } from "@supersuit/suggest-a-change/client";
+
+// once, at the root
+<SuggestNews adapters={adapters} />
+
+// the menu's trigger
+function MoreButton({ onClick }: { onClick(): void }) {
+  const { moved } = useSuggestNews(adapters);
+  return (
+    <button type="button" className="sac-dot-host" aria-label="More" onClick={onClick}>
+      ...<SuggestDot adapters={adapters} moved={moved} />
+    </button>
+  );
+}
+
+// inside the menu, as before
+<SuggestEntry adapters={adapters} role="menuitem" onOpen={() => setOpen(true)} />
+```
+
+`<SuggestNews>` also takes `children`, a function given `{ moved }`, for a root that draws the trigger itself. A host using only the hook renders `<Toasts />` somewhere always mounted so the toast has a place to show.
 
 **Follow-ups.** Words and voice notes added to a report afterwards are queued in the outbox like the report (a `followUp` write, then one part per voice note), keep the app's refusal with a Try again, and delete their local copy only once they have landed. `StoreAdapter.append` must therefore dedupe by report id and `more.followId`.
 

package/dist/client/entry.d.ts

@@ -1,10 +1,33 @@
-import { type AriaRole } from 'react';
+import { type AriaRole, type ReactNode } from 'react';
 import type { Adapters } from './adapters.ts';
 /** Keeps the phone's outbox moving (on reconnect and every 15 seconds) for as long as it is mounted, with nothing drawn.
  *  <SuggestEntry> already does this; a host with no always-mounted entry mounts this once, high in the app. */
 export declare function KeepSending({ adapters }: {
     adapters: Adapters;
 }): null;
+/** For a host that shows the entry where it is not always visible (inside a menu): call this where the menu's trigger is
+ *  drawn. It asks the app once per mount and returns how many of this person's suggestions moved since they last opened
+ *  them (draw `<SuggestDot>` with it). The page load's one toast is shown by whichever of this, `<SuggestNews>` or the
+ *  entry asks first; a host using only this hook must also render `<Toasts />` somewhere always mounted. */
+export declare function useSuggestNews(adapters: Adapters): {
+    moved: number;
+};
+/** Mount once at the app's root, always mounted: shows the page load's one toast when a suggestion moved, with no entry
+ *  on screen, and keeps the outbox moving (as `<KeepSending>` does). `children`, if given, receives `{ moved }`. */
+export declare function SuggestNews({ adapters, children }: {
+    adapters: Adapters;
+    children?: (news: {
+        moved: number;
+    }) => ReactNode;
+}): import("react").JSX.Element;
+/** The entry's dot, for a host's own trigger (the three-dot button of a menu the entry sits in). Draws nothing when
+ *  `moved` is 0. It is positioned like the entry's dot, so the trigger needs `position: relative` (the class
+ *  `sac-dot-host` in the module's styles does it). */
+export declare function SuggestDot({ adapters, moved: count, className }: {
+    adapters: Adapters;
+    moved: number;
+    className?: string;
+}): import("react").JSX.Element | null;
 export declare function SuggestEntry({ adapters, onOpen, className, role }: {
     adapters: Adapters;
     onOpen(): void;

package/dist/client/entry.js

@@ -16,18 +16,14 @@ export function KeepSending({ adapters }) {
     useRuntime(adapters);
     return null;
 }
-export function SuggestEntry({ adapters, onOpen, className, role }) {
+// THE NEWS: once per mount, asks the app for this person's reports and compares each with what they last opened. A move
+// since then is counted (the dot), and the newest one gets the page load's one toast, whichever of the entry or a
+// root-mounted SuggestNews asks first (the guard is per page load and account, in seen.ts). Opening a report anywhere
+// recounts. `toasted` says this mount showed the toast, so a standalone entry knows to draw a toast host for it.
+function useNews(adapters, rt) {
     const S = stringsFor(adapters.words);
-    const [why, setWhy] = useState('');
-    const [busy, setBusy] = useState(false);
-    // The runtime keeps the outbox moving while the entry is mounted (what <KeepSending> does).
-    const { rt, who } = useRuntime(adapters);
     const [news, setNews] = useState(0);
-    const [toasting, setToasting] = useState(false);
-    useEffect(() => { setWhy(''); }, [adapters]);
-    useClearOnSignOut(rt, who, adapters.words.app);
-    // Once per mount, asks the app for this person's reports and compares each with what they last opened: a move since
-    // then shows the dot, and the newest one gets the open's one toast. Opening a report (anywhere) clears it.
+    const [toasted, setToasted] = useState(false);
     useEffect(() => {
         setNews(0);
         if (!rt)
@@ -65,13 +61,47 @@ export function SuggestEntry({ adapters, onOpen, className, role }) {
             const at = (x) => rows.find((r) => r.id === x)?.at ?? 0;
             const top = [...m].sort((a, b) => at(b.id) - at(a.id))[0];
             const note = top.status === 'not-now' ? rows.find((r) => r.id === top.id)?.note : undefined;
-            setToasting(true);
+            setToasted(true);
             toast({ id: `sac-moved-${top.id}`, text: S.movedToast(statusWords(top.status, adapters.words.owner), typeof note === 'string' && note ? note : undefined), ms: 6000 });
         })();
         const off = onSeen(() => { void count(); });
         return () => { live = false; off(); };
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [rt]);
+    return { moved: news, toasted };
+}
+/** For a host that shows the entry where it is not always visible (inside a menu): call this where the menu's trigger is
+ *  drawn. It asks the app once per mount and returns how many of this person's suggestions moved since they last opened
+ *  them (draw `<SuggestDot>` with it). The page load's one toast is shown by whichever of this, `<SuggestNews>` or the
+ *  entry asks first; a host using only this hook must also render `<Toasts />` somewhere always mounted. */
+export function useSuggestNews(adapters) {
+    const { rt } = useRuntime(adapters);
+    return { moved: useNews(adapters, rt).moved };
+}
+/** Mount once at the app's root, always mounted: shows the page load's one toast when a suggestion moved, with no entry
+ *  on screen, and keeps the outbox moving (as `<KeepSending>` does). `children`, if given, receives `{ moved }`. */
+export function SuggestNews({ adapters, children }) {
+    const news = useSuggestNews(adapters);
+    return _jsxs(_Fragment, { children: [_jsx(Toasts, {}), children ? children(news) : null] });
+}
+/** The entry's dot, for a host's own trigger (the three-dot button of a menu the entry sits in). Draws nothing when
+ *  `moved` is 0. It is positioned like the entry's dot, so the trigger needs `position: relative` (the class
+ *  `sac-dot-host` in the module's styles does it). */
+export function SuggestDot({ adapters, moved: count, className }) {
+    const S = stringsFor(adapters.words);
+    if (!count)
+        return null;
+    return _jsxs(_Fragment, { children: [_jsx("span", { className: `sac-entry-dot${className ? ` ${className}` : ''}`, "data-sac-moved": "", "aria-hidden": "true" }), _jsx("span", { className: "sac-sr", children: S.entryMoved })] });
+}
+export function SuggestEntry({ adapters, onOpen, className, role }) {
+    const S = stringsFor(adapters.words);
+    const [why, setWhy] = useState('');
+    const [busy, setBusy] = useState(false);
+    // The runtime keeps the outbox moving while the entry is mounted (what <KeepSending> does).
+    const { rt, who } = useRuntime(adapters);
+    const { moved: news, toasted: toasting } = useNews(adapters, rt);
+    useEffect(() => { setWhy(''); }, [adapters]);
+    useClearOnSignOut(rt, who, adapters.words.app);
     async function press() {
         setBusy(true);
         let who = null;
@@ -89,7 +119,7 @@ export function SuggestEntry({ adapters, onOpen, className, role }) {
         setWhy('');
         onOpen();
     }
-    return (_jsxs("span", { className: "sac-entry-wrap", children: [_jsxs("button", { type: "button", role: role, "data-suggest-entry": "", className: `sac-entry${className ? ` ${className}` : ''}`, "aria-busy": busy || undefined, onClick: () => void press(), children: [S.entry, news ? _jsxs(_Fragment, { children: [_jsx("span", { className: "sac-entry-dot", "data-sac-moved": "", "aria-hidden": "true" }), _jsx("span", { className: "sac-sr", children: S.entryMoved })] }) : null] }), why ? _jsx("span", { role: "status", className: "sac-entry-why", children: why }) : null, toasting ? _jsx(Toasts, {}) : null] }));
+    return (_jsxs("span", { className: "sac-entry-wrap", children: [_jsxs("button", { type: "button", role: role, "data-suggest-entry": "", className: `sac-entry${className ? ` ${className}` : ''}`, "aria-busy": busy || undefined, onClick: () => void press(), children: [S.entry, _jsx(SuggestDot, { adapters: adapters, moved: news })] }), why ? _jsx("span", { role: "status", className: "sac-entry-why", children: why }) : null, toasting ? _jsx(Toasts, {}) : null] }));
 }
 /** For an error screen: opens the sheet as "something is broken", with the screen and what went wrong filled in. */
 export function ReportProblem({ adapters, screen, error }) {

package/dist/client/seen.js

@@ -60,7 +60,8 @@ export function moved(store, id, rows) {
         return out;
     });
 }
-/** One toast per app open, per account: a remounted entry in the same open does not say it again. */
+/** One toast per page load, per account, whoever asks: a remounted entry (a menu that remounts it on every open) or a
+ *  root-mounted SuggestNews beside it never says it again until the page is loaded again. */
 const toasted = new Set();
 export function firstToastThisOpen(id) {
     const k = seenKey(id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/suggest-a-change",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "The report format and flow behind a Suggest a change button: what a report is, who acts at each step, the screens, and the check every app runs. The contract has zero dependencies.",
   "type": "module",
   "bin": {

package/src/client/entry.tsx

@@ -2,9 +2,9 @@
 // THE ENTRY: one control, `data-suggest-entry`, which is the contract the screen checker looks for.
 // Signed out, it opens nothing and says why. Signed in, it hands over to the host (`onOpen`), which
 // shows the sheet. `<ReportProblem>` is the same control for an error screen, already filled in.
-import { useEffect, useState, type AriaRole } from 'react'
+import { useEffect, useState, type AriaRole, type ReactNode } from 'react'
 import type { Adapters } from './adapters.ts'
-import { useRuntime } from './runtime.ts'
+import { useRuntime, type Runtime } from './runtime.ts'
 import { firstToastThisOpen, moved, onSeen } from './seen.ts'
 import { SuggestSheet } from './sheet.tsx'
 import { toast, Toasts } from './toast.tsx'
@@ -18,18 +18,14 @@ export function KeepSending({ adapters }: { adapters: Adapters }) {
   return null
 }
 
-export function SuggestEntry({ adapters, onOpen, className, role }: { adapters: Adapters; onOpen(): void; className?: string; /** An ARIA role for the button (for example `menuitem` when the host shows it as a menu row). Unset by default. */ role?: AriaRole }) {
+// THE NEWS: once per mount, asks the app for this person's reports and compares each with what they last opened. A move
+// since then is counted (the dot), and the newest one gets the page load's one toast, whichever of the entry or a
+// root-mounted SuggestNews asks first (the guard is per page load and account, in seen.ts). Opening a report anywhere
+// recounts. `toasted` says this mount showed the toast, so a standalone entry knows to draw a toast host for it.
+function useNews(adapters: Adapters, rt: Runtime | null): { moved: number; toasted: boolean } {
   const S = stringsFor(adapters.words)
-  const [why, setWhy] = useState('')
-  const [busy, setBusy] = useState(false)
-  // The runtime keeps the outbox moving while the entry is mounted (what <KeepSending> does).
-  const { rt, who } = useRuntime(adapters)
   const [news, setNews] = useState(0)
-  const [toasting, setToasting] = useState(false)
-  useEffect(() => { setWhy('') }, [adapters])
-  useClearOnSignOut(rt, who, adapters.words.app)
-  // Once per mount, asks the app for this person's reports and compares each with what they last opened: a move since
-  // then shows the dot, and the newest one gets the open's one toast. Opening a report (anywhere) clears it.
+  const [toasted, setToasted] = useState(false)
   useEffect(() => {
     setNews(0)
     if (!rt) return
@@ -52,13 +48,50 @@ export function SuggestEntry({ adapters, onOpen, className, role }: { adapters:
       const at = (x: string) => rows!.find((r) => r.id === x)?.at ?? 0
       const top = [...m].sort((a, b) => at(b.id) - at(a.id))[0]
       const note = top.status === 'not-now' ? rows.find((r) => r.id === top.id)?.note : undefined
-      setToasting(true)
+      setToasted(true)
       toast({ id: `sac-moved-${top.id}`, text: S.movedToast(statusWords(top.status, adapters.words.owner), typeof note === 'string' && note ? note : undefined), ms: 6000 })
     })()
     const off = onSeen(() => { void count() })
     return () => { live = false; off() }
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [rt])
+  return { moved: news, toasted }
+}
+
+/** For a host that shows the entry where it is not always visible (inside a menu): call this where the menu's trigger is
+ *  drawn. It asks the app once per mount and returns how many of this person's suggestions moved since they last opened
+ *  them (draw `<SuggestDot>` with it). The page load's one toast is shown by whichever of this, `<SuggestNews>` or the
+ *  entry asks first; a host using only this hook must also render `<Toasts />` somewhere always mounted. */
+export function useSuggestNews(adapters: Adapters): { moved: number } {
+  const { rt } = useRuntime(adapters)
+  return { moved: useNews(adapters, rt).moved }
+}
+
+/** Mount once at the app's root, always mounted: shows the page load's one toast when a suggestion moved, with no entry
+ *  on screen, and keeps the outbox moving (as `<KeepSending>` does). `children`, if given, receives `{ moved }`. */
+export function SuggestNews({ adapters, children }: { adapters: Adapters; children?: (news: { moved: number }) => ReactNode }) {
+  const news = useSuggestNews(adapters)
+  return <><Toasts />{children ? children(news) : null}</>
+}
+
+/** The entry's dot, for a host's own trigger (the three-dot button of a menu the entry sits in). Draws nothing when
+ *  `moved` is 0. It is positioned like the entry's dot, so the trigger needs `position: relative` (the class
+ *  `sac-dot-host` in the module's styles does it). */
+export function SuggestDot({ adapters, moved: count, className }: { adapters: Adapters; moved: number; className?: string }) {
+  const S = stringsFor(adapters.words)
+  if (!count) return null
+  return <><span className={`sac-entry-dot${className ? ` ${className}` : ''}`} data-sac-moved="" aria-hidden="true" /><span className="sac-sr">{S.entryMoved}</span></>
+}
+
+export function SuggestEntry({ adapters, onOpen, className, role }: { adapters: Adapters; onOpen(): void; className?: string; /** An ARIA role for the button (for example `menuitem` when the host shows it as a menu row). Unset by default. */ role?: AriaRole }) {
+  const S = stringsFor(adapters.words)
+  const [why, setWhy] = useState('')
+  const [busy, setBusy] = useState(false)
+  // The runtime keeps the outbox moving while the entry is mounted (what <KeepSending> does).
+  const { rt, who } = useRuntime(adapters)
+  const { moved: news, toasted: toasting } = useNews(adapters, rt)
+  useEffect(() => { setWhy('') }, [adapters])
+  useClearOnSignOut(rt, who, adapters.words.app)
   async function press() {
     setBusy(true)
     let who = null
@@ -72,7 +105,7 @@ export function SuggestEntry({ adapters, onOpen, className, role }: { adapters:
     <span className="sac-entry-wrap">
       <button type="button" role={role} data-suggest-entry="" className={`sac-entry${className ? ` ${className}` : ''}`} aria-busy={busy || undefined} onClick={() => void press()}>
         {S.entry}
-        {news ? <><span className="sac-entry-dot" data-sac-moved="" aria-hidden="true" /><span className="sac-sr">{S.entryMoved}</span></> : null}
+        <SuggestDot adapters={adapters} moved={news} />
       </button>
       {why ? <span role="status" className="sac-entry-why">{why}</span> : null}
       {toasting ? <Toasts /> : null}

package/src/client/seen.ts

@@ -61,7 +61,8 @@ export function moved(store: Store, id: Id, rows: { id: string; status: string }
   })
 }
 
-/** One toast per app open, per account: a remounted entry in the same open does not say it again. */
+/** One toast per page load, per account, whoever asks: a remounted entry (a menu that remounts it on every open) or a
+ *  root-mounted SuggestNews beside it never says it again until the page is loaded again. */
 const toasted = new Set<string>()
 export function firstToastThisOpen(id: Id): boolean {
   const k = seenKey(id)

package/src/client/styles.css

@@ -45,7 +45,7 @@
 .sac-item { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 8px; }
 .sac-row-button { width: 100%; text-align: left; display: flex; flex-direction: column; gap: 2px; }
 .sac-row-status { font-weight: 600; }
-.sac-entry { position: relative; }
+.sac-entry, .sac-dot-host { position: relative; }
 .sac-entry-dot { position: absolute; top: 6px; right: 6px; width: 10px; height: 10px; border-radius: 50%; background: var(--sac-accent); box-shadow: 0 0 0 2px var(--sac-bg); }
 .sac-new { align-self: flex-start; font-size: 0.8rem; font-weight: 600; padding: 1px 8px; border-radius: 999px; background: var(--sac-accent); color: var(--sac-accent-fg); }
 .sac-muted { color: var(--sac-muted); font-size: 0.9rem; }