sygnal 6.6.0 → 7.1.0

package/src/ui/tooltips.ts

@@ -0,0 +1,92 @@
+/*
+ * PLAN-11 T-1: Tooltips, one behavior for every tooltip of a component (glossary terms in a
+ * paragraph, icon buttons in a toolbar): one state slice and two timers however many triggers
+ * there are, instead of a tooltip() per trigger.
+ *
+ *   Article.uses = { tips: tooltips({ trigger: '.term', tip: '.term-tip' }) }
+ *
+ * Each trigger names its tip with aria-describedby (the tip's id); the tips are `role="tooltip"
+ * popover="manual"` elements placed by CSS anchor positioning, as for tooltip(). One tip shows at
+ * a time. Moving from one trigger to another while a tip is shown switches at once (no second
+ * show delay), as tooltip groups do.
+ *
+ * Options: `trigger`, `tip` (required selectors matching every trigger / every tip),
+ * `showDelay` (500 ms), `hideDelay` (100 ms).
+ * State: { id (the tip of the trigger or tip last entered), open (the id of the tip shown),
+ * pending: null | 'show' | 'hide', hover, focus }. Actions: ENTER / LEAVE ({ via: 'hover' |
+ * 'focus', id }), SHOW / HIDE (the timers), ESCAPE, TOGGLED ({ id, open }). Timers
+ * '<key>.show' / '<key>.hide' as tooltip()'s. Needs makeTimerDriver() (tests: fake timers).
+ * Same rules as tooltip(): pointer and focus tracked apart, touch ignored, hovering the tip keeps
+ * it open (WCAG 1.4.13), Escape listened for only while a tip is shown or about to be.
+ */
+import {ABORT, defineBehavior, dropRepeats, xs} from '../index'
+
+const mouse = (e: any) => e?.pointerType != 'touch'
+const el = (e: any) => e?.ownerTarget || e?.currentTarget || e?.target
+// the trigger's tip id (its aria-describedby: the first id when it lists several), or the tip's own
+const tipOf = (e: any) => String(el(e)?.getAttribute?.('aria-describedby') || '').trim().split(/\s+/)[0] || null
+const idOf = (e: any) => el(e)?.id || null
+const at = (id: string) => `[id="${id.replace(/["\\]/g, '\\$&')}"]`
+
+const base = /*#__PURE__*/ defineBehavior({
+  initialState: {id: null as null | string, open: null as null | string, pending: null as null | string, hover: false, focus: false},
+  timers: (s: any, o: any) => ({
+    show: s?.pending == 'show' && {after: o.showDelay ?? 500, action: 'SHOW'},
+    hide: s?.pending == 'hide' && {after: o.hideDelay ?? 100, action: 'HIDE'},
+  }),
+  intent: ({DOM, STATE}: any, {trigger, tip}: any) => ({
+    ENTER: xs.merge(
+      DOM.pointerenter(trigger).filter(mouse).map((e: any) => ({via: 'hover', id: tipOf(e)})),
+      DOM.pointerenter(tip).filter(mouse).map((e: any) => ({via: 'hover', id: idOf(e)})),
+      DOM.focus(trigger).map((e: any) => ({via: 'focus', id: tipOf(e)})),
+    ).filter((x: any) => !!x.id),
+    LEAVE: xs.merge(
+      DOM.pointerleave(trigger).filter(mouse).map((e: any) => ({via: 'hover', id: tipOf(e)})),
+      DOM.pointerleave(tip).filter(mouse).map((e: any) => ({via: 'hover', id: idOf(e)})),
+      DOM.blur(trigger).map((e: any) => ({via: 'focus', id: tipOf(e)})),
+    ).filter((x: any) => !!x.id),
+    ESCAPE: (STATE ? STATE.stream.map((s: any) => !!(s?.open || s?.pending)).compose(dropRepeats()) : xs.of(true))
+      .map((on: boolean) => (on ? DOM.keydown('document').key().filter((k: string) => k == 'Escape') : xs.never()))
+      .flatten(),
+    TOGGLED: DOM.toggle(tip).map((e: any) => ({id: idOf(e), open: e.newState == 'open'})).filter((x: any) => !!x.id),
+  }),
+  model: {
+    ENTER: {
+      STATE: (s: any, {via, id}: any) => {
+        const k = via == 'focus' ? 'focus' : 'hover'
+        // another trigger: it takes over (a tip already shown switches at once, in ELEMENT)
+        if (id != s.id) return {...s, id, hover: k == 'hover', focus: k == 'focus', pending: s.open ? null : 'show'}
+        const pending = s.open == id ? null : 'show'
+        return s[k] && s.pending == pending ? ABORT : {...s, [k]: true, pending}
+      },
+      // 7.0: outputs get the updated slice; "another trigger than before" reads the previous one
+      ELEMENT: (s: any, {id}: any, _n: any, p: any, _o: any, k: string) => {
+        const w = p?.previousState ? p.previousState[k] : s
+        return id != w.id && w.open && w.open != id ? [{hidePopover: at(w.open)}, {showPopover: at(id)}] : ABORT
+      },
+    },
+    LEAVE: (s: any, {via, id}: any) => {
+      if (id != s.id) return ABORT
+      const k = via == 'focus' ? 'focus' : 'hover'
+      const n = {...s, [k]: false}
+      const pending = n.hover || n.focus ? s.pending : s.open ? 'hide' : null
+      return !s[k] && s.pending == pending ? ABORT : {...n, pending}
+    },
+    SHOW: {
+      STATE: (s: any) => ({...s, pending: null}),
+      ELEMENT: (s: any) => (!s.id || s.open == s.id ? ABORT : s.open ? [{hidePopover: at(s.open)}, {showPopover: at(s.id)}] : {showPopover: at(s.id)}),
+    },
+    HIDE: {
+      STATE: (s: any) => ({...s, pending: null}),
+      ELEMENT: (s: any) => (s.open ? {hidePopover: at(s.open)} : ABORT),
+    },
+    ESCAPE: {
+      STATE: (s: any) => (s.open || s.pending ? {...s, pending: null} : ABORT),
+      ELEMENT: (s: any) => (s.open ? {hidePopover: at(s.open)} : ABORT),
+    },
+    TOGGLED: (s: any, {id, open}: any) => (open ? (s.open == id ? ABORT : {...s, open: id}) : s.open == id ? {...s, open: null} : ABORT),
+  },
+})
+
+/** Every tooltip of a component as one behavior: `uses = { tips: tooltips({ trigger: '.term', tip: '.term-tip' }) }`. */
+export const tooltips = (options: any = {}): any => base({...options, id: null, open: null, pending: null, hover: false, focus: false})

package/src/ui.d.ts

@@ -75,6 +75,41 @@ export interface TooltipActions { ENTER: 'hover' | 'focus' | undefined; LEAVE: '
 /** A tooltip: `uses = { tip: tooltip({ trigger: '.save', tip: '.save-tip' }) }`. Needs makeTimerDriver(). */
 export function tooltip(options: TooltipOptions): Behavior<TooltipState, TooltipActions, {}, TooltipOptions>
 
+// ── Tooltips (PLAN-11) ────────────────────────────────────────────────
+export interface TooltipsState {
+  /** The tip id of the trigger (or tip) last entered */
+  id: string | null
+  /** The id of the tip shown, or null */
+  open: string | null
+  pending: null | 'show' | 'hide'
+  hover: boolean
+  focus: boolean
+}
+export interface TooltipsOptions {
+  /** Every trigger (a selector matching them all); each names its tip with aria-describedby */
+  trigger: BehaviorTarget
+  /** Every tip: role="tooltip" popover="manual" with an id, placed with CSS anchor positioning */
+  tip: BehaviorTarget
+  /** ms before a tip shows (default 500); moving to another trigger while one shows switches at once */
+  showDelay?: number
+  /** ms before it hides (default 100) */
+  hideDelay?: number
+}
+export interface TooltipsActions {
+  ENTER: { via: 'hover' | 'focus'; id: string }
+  LEAVE: { via: 'hover' | 'focus'; id: string }
+  SHOW: any
+  HIDE: any
+  ESCAPE: string
+  TOGGLED: { id: string; open: boolean }
+}
+/**
+ * PLAN-11 (6.7): every tooltip of a component as one behavior (one state slice, two timers):
+ * `uses = { tips: tooltips({ trigger: '.term', tip: '.term-tip' }) }`, each trigger with
+ * `aria-describedby` naming its tip's id. One tip shows at a time. Needs makeTimerDriver().
+ */
+export function tooltips(options: TooltipsOptions): Behavior<TooltipsState, TooltipsActions, {}, TooltipsOptions>
+
 // ── Tabs ──────────────────────────────────────────────────────────────
 export interface TabsState {
   /** The ids' prefix (the key in `uses` unless the `id` option names it) */

package/src/ui.ts

@@ -9,6 +9,7 @@
 export {dialog} from './ui/dialog'
 export {popover} from './ui/popover'
 export {tooltip} from './ui/tooltip'
+export {tooltips} from './ui/tooltips'
 export {tabs, tabsAttrs} from './ui/tabs'
 export {accordion, accordionAttrs} from './ui/accordion'
 export {disclosure, disclosureAttrs} from './ui/disclosure'

package/src/vite/graph.ts

@@ -232,15 +232,23 @@ export function graphMiddleware(server: any, root: string, engine: Promise<LiveE
   }
 }
 
-/** Adds the page's URL under Vite's own when the dev server prints them. */
-export function printGraphUrl(server: any) {
+/** The banner line when the project has no sygnal-check with the graph page (it used to print nothing). */
+export const GRAPH_MISSING_LINE = '  ➜  Sygnal graph: needs sygnal-check 0.10.0 or later in this project (npm i -D sygnal-check)'
+
+/**
+ * Adds the page's URL under Vite's own when the dev server prints them, or, when the project's
+ * sygnal-check is missing or too old for the page (`available` false), a line saying what to install.
+ */
+export function printGraphUrl(server: any, available = true) {
   const print = server?.printUrls
   if (typeof print !== 'function') return
   server.printUrls = function (this: any, ...args: any[]) {
     const out = print.apply(this, args)
     try {
+      const logger = server.config?.logger || console
       const local = server.resolvedUrls?.local?.[0]
-      if (local) (server.config?.logger || console).info(`  ➜  Sygnal graph: ${new URL(local).origin}${GRAPH_PATH}`)
+      if (!available) logger.info(GRAPH_MISSING_LINE)
+      else if (local) logger.info(`  ➜  Sygnal graph: ${new URL(local).origin}${GRAPH_PATH}`)
     } catch (_) {}
     return out
   }

package/src/vite/plugin.d.ts

@@ -12,6 +12,13 @@ export interface DiagnosticsPluginOptions {
    * @default false
    */
   strict?: boolean
+  /**
+   * 7.0 timing audit (SYG257, info): the dev snippet sets `globalThis.__SYGNAL_TIMING_AUDIT__ =
+   * true`, and each output sink that reads a top-level state field its action's STATE changed is
+   * reported (since 7.0 it gets the new value; 6.x gave it the old one). For migrating 6.x code.
+   * @default false
+   */
+  timingAudit?: boolean
   /** Diagnostic codes to drop, e.g. ['SYG105'] (runtime and static) */
   ignore?: string[]
 }

package/src/vite/plugin.ts

@@ -130,7 +130,8 @@
  *      skipped silently when missing; a sygnal-check without the page keeps the checker as in 5)
  *      builds it with createLiveProject on start and after each change: one build gives the page,
  *      the check overlay / console findings of 5, and the component stamps. Its URL is printed
- *      under Vite's ("➜  Sygnal graph: http://localhost:5173/__sygnal/graph"). The modules of the
+ *      under Vite's ("➜  Sygnal graph: http://localhost:5173/__sygnal/graph"; without a sygnal-check
+ *      0.10.0+ in the project, a line saying so instead). The modules of the
  *      scanned files get a tail setting a non-enumerable `__sygnalKey` (the static 'file#name'
  *      key, D521) on each top-level component function, which the runtime inspect() reports as
  *      `key`; with DevTools on, the dev entries also import 'virtual:sygnal/graph'
@@ -191,6 +192,8 @@ export interface DiagnosticsPluginOptions {
   mode?: DiagnosticsMode
   /** Strict (canonical-form, SYG5xx) runtime checks: sets globalThis.__SYGNAL_STRICT__. @default false */
   strict?: boolean
+  /** 7.0 timing audit (SYG257, info): sets globalThis.__SYGNAL_TIMING_AUDIT__. @default false */
+  timingAudit?: boolean
   /** Diagnostic codes to drop, e.g. ['SYG105'] */
   ignore?: string[]
 }
@@ -343,7 +346,7 @@ export default function sygnal(options: SygnalPluginOptions = {}) {
   // Files whose `import ... from 'sygnal'` resolves to the run() wrapper
   const runtimeImporters = new Set<string>()
   // Statements run before the app starts: dev flag (+ strict flag)
-  const flags = DEV_FLAG + (diagnostics.strict ? STRICT_FLAG : '')
+  const flags = DEV_FLAG + (diagnostics.strict ? STRICT_FLAG : '') + (diagnostics.timingAudit ? AUDIT_FLAG : '')
   const devImports = `import 'sygnal/diagnostics';import '${DEV_CLIENT}';`
   // D77: the DevTools bridge, dev only. First, so the diagnostics entry finds it.
   // E-1: the MCP endpoint needs the bridge, so `mcp` turns it on
@@ -535,7 +538,7 @@ export default function sygnal(options: SygnalPluginOptions = {}) {
       // W-2 (D543): the page and its stream, behind the MCP endpoint's guard; its URL in the banner
       if (graphOn && server?.middlewares) {
         server.middlewares.use(graphMiddleware(server, root, engine))
-        if (graphAvailable(root)) printGraphUrl(server)
+        printGraphUrl(server, graphAvailable(root))
       }
     },
 
@@ -790,7 +793,7 @@ function viteMajor(ctx: any, root: string): number {
   return Infinity
 }
 
-interface NormalizedDiagnostics { mode: DiagnosticsMode, strict: boolean, ignore: string[] }
+interface NormalizedDiagnostics { mode: DiagnosticsMode, strict: boolean, timingAudit: boolean, ignore: string[] }
 
 const MODES: DiagnosticsMode[] = ['off', 'collect', 'warn', 'error']
 
@@ -800,7 +803,7 @@ function normalizeDiagnostics(value: SygnalPluginOptions['diagnostics']): Normal
   if (!MODES.includes(mode)) {
     throw new Error(`[vite-plugin-sygnal] diagnostics mode must be one of ${MODES.map(m => `'${m}'`).join(', ')}; got ${JSON.stringify(mode)}`)
   }
-  return { mode, strict: !!o.strict, ignore: Array.isArray(o.ignore) ? o.ignore.map(String) : [] }
+  return { mode, strict: !!o.strict, timingAudit: !!o.timingAudit, ignore: Array.isArray(o.ignore) ? o.ignore.map(String) : [] }
 }
 
 /** Module id without a query or hash. */
@@ -1155,6 +1158,8 @@ function startChecker(server: any, root: string, mod: any, setup: CheckSetup, op
 
 const DEV_FLAG = 'if (globalThis.__SYGNAL_DEV__ === undefined) globalThis.__SYGNAL_DEV__ = true;'
 const STRICT_FLAG = 'if (globalThis.__SYGNAL_STRICT__ === undefined) globalThis.__SYGNAL_STRICT__ = true;'
+// 7.0: the opt-in timing audit (SYG257, 'sygnal/diagnostics' checks/timingAudit.ts)
+const AUDIT_FLAG = 'if (globalThis.__SYGNAL_TIMING_AUDIT__ === undefined) globalThis.__SYGNAL_TIMING_AUDIT__ = true;'
 
 // A top-level (column 0) run(Component, ...) statement: bare, or declaring a
 // new binding. Assignments to existing variables, nested calls and indented