@tai42/studio-sdk 0.12.0 → 0.14.0

package/src/index.ts

@@ -80,6 +80,8 @@ export {
   useAppNavigate,
   useResolvePath,
   usePluginNavigation,
+  useNavigationGuard,
+  useNavigationGate,
 } from './navigation';
 export type {
   AppLinkProps,
@@ -89,6 +91,7 @@ export type {
   PageProps,
   NavigationContextValue,
   PluginSearch,
+  NavigationGuardHandler,
 } from './navigation';
 
 // -- Utilities ---------------------------------------------------------------
@@ -148,6 +151,9 @@ export { Dialog } from './components/dialog';
 export type { DialogProps } from './components/dialog';
 export { ConfirmDialog } from './components/confirm-dialog';
 export type { ConfirmDialogProps } from './components/confirm-dialog';
+export { GuardedTabs, useRegisterDirty } from './components/dirty-guard';
+export { FormDialog } from './components/form-dialog';
+export type { FormDialogProps } from './components/form-dialog';
 export { Drawer } from './components/drawer';
 export type { DrawerProps } from './components/drawer';
 export { Tooltip } from './components/tooltip';
@@ -212,6 +218,19 @@ export type {
 } from './components/folder-nav';
 export { CodeBlock } from './components/code-block';
 export type { CodeBlockProps } from './components/code-block';
+export { Markdown, parseMarkdown } from './components/markdown';
+export type { MarkdownProps, MarkdownBlock, HeadingLevel } from './components/markdown';
+export {
+  DateRangePicker,
+  formatRangeLabel,
+  normalizeCustomRange,
+  DEFAULT_DATE_RANGE_PRESETS,
+} from './components/date-range-picker';
+export type {
+  DateRangePickerProps,
+  DateRangePreset,
+  DateRangeValue,
+} from './components/date-range-picker';
 export { FleetReport } from './components/fleet-report';
 export type { FleetReportProps } from './components/fleet-report';
 export { ExternalLinkButton, isSafeHttpUrl } from './components/external-link';

package/src/navigation/context.tsx

@@ -3,20 +3,109 @@ import {
   createElement,
   useCallback,
   useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
   type AriaAttributes,
   type MouseEvent,
   type ReactNode,
 } from 'react';
 
-import type { NavigationContextValue, RouteSearch, RouteToken } from './types';
+import type {
+  NavigationContextValue,
+  NavigationGuardHandler,
+  RouteSearch,
+  RouteToken,
+} from './types';
+
+/** Shell-provided navigation; no default, so use outside {@link NavigationProvider} throws. */
+const NavigationContext = createContext<NavigationContextValue | null>(null);
 
 /**
- * Shell-provided navigation. The context has no default: a feature rendered
- * outside the shell's {@link NavigationProvider} is a wiring bug, so
- * {@link useNavigation} raises loudly rather than silently no-op'ing a
- * transition.
+ * One armed navigation guard. The registry holds this exact object (not a
+ * snapshot), so flipping `when` or swapping `handler` on re-render takes effect
+ * without re-registering.
  */
-const NavigationContext = createContext<NavigationContextValue | null>(null);
+interface GuardEntry {
+  when: boolean;
+  handler: NavigationGuardHandler;
+}
+
+/**
+ * The guards active under one {@link NavigationProvider} — the single registry
+ * every SDK-controlled navigation consults, so feature and plugin-page guards
+ * compose against the same set. `run` stops at the first veto (at most one confirm
+ * dialog); `subscribe` re-evaluates browser-level listeners when the armed set changes.
+ */
+class NavigationGuardRegistry {
+  private readonly guards = new Set<GuardEntry>();
+  private readonly listeners = new Set<() => void>();
+
+  /** Register a guard; returns the unregister function. */
+  add(entry: GuardEntry): () => void {
+    this.guards.add(entry);
+    this.emit();
+    return () => {
+      this.guards.delete(entry);
+      this.emit();
+    };
+  }
+
+  /** Notify subscribers that a guard's `when` may have changed. */
+  touch(): void {
+    this.emit();
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  hasArmedGuards(): boolean {
+    for (const entry of this.guards) {
+      if (entry.when) return true;
+    }
+    return false;
+  }
+
+  /** Resolve `true` only if every armed guard allows the navigation. */
+  async run(): Promise<boolean> {
+    for (const entry of this.guards) {
+      if (!entry.when) continue;
+      const allowed = await entry.handler();
+      if (!allowed) return false;
+    }
+    return true;
+  }
+
+  private emit(): void {
+    for (const listener of this.listeners) listener();
+  }
+}
+
+/**
+ * Carries the provider's guard registry to {@link useNavigationGuard}. Separate from
+ * {@link NavigationContext} so the shell-supplied value stays exactly the shell's
+ * contract — the registry is SDK-owned.
+ */
+const GuardRegistryContext = createContext<NavigationGuardRegistry | null>(null);
+
+/** Records an approved raw-path transition as the committed history entry, so a later
+ * back/forward restores to it exactly as it does after a token navigation. */
+const CommitHrefContext = createContext<((href: string) => void) | null>(null);
+
+function useGuardRegistry(): NavigationGuardRegistry {
+  const registry = useContext(GuardRegistryContext);
+  if (registry === null) {
+    throw new Error(
+      'useNavigationGuard must be used within a <NavigationProvider> (the shell provides it).',
+    );
+  }
+  return registry;
+}
 
 export function NavigationProvider({
   value,
@@ -25,7 +114,144 @@ export function NavigationProvider({
   value: NavigationContextValue;
   children: ReactNode;
 }): ReactNode {
-  return createElement(NavigationContext.Provider, { value }, children);
+  const registryRef = useRef<NavigationGuardRegistry | null>(null);
+  registryRef.current ??= new NavigationGuardRegistry();
+  const registry = registryRef.current;
+
+  // The last committed history entry the SDK observed (URL + `history.state`): what a
+  // canceled back/forward restores to. URL changes made outside the SDK's navigate
+  // entry points are unobservable by design at this layer.
+  const committedRef = useRef<{ href: string; state: unknown } | null>(null);
+
+  // Mirror the registry's armed state into React so the browser listeners attach only
+  // while at least one guard is armed.
+  const [armed, setArmed] = useState(false);
+  useEffect(() => {
+    setArmed(registry.hasArmedGuards());
+    return registry.subscribe(() => {
+      setArmed(registry.hasArmedGuards());
+    });
+  }, [registry]);
+
+  useEffect(() => {
+    if (!armed) return;
+
+    // The protected entry (URL + state); a back/forward landing elsewhere is first
+    // canceled back to here while the guard is consulted.
+    committedRef.current = { href: window.location.href, state: window.history.state };
+    // Set while replaying a guard-approved back/forward, so its `popstate` passes
+    // through instead of being re-intercepted.
+    let bypass = false;
+    // Latched while a decision is pending, so a second Back mid-decision keeps canceling
+    // without starting a concurrent `registry.run()` — one gesture, one dialog.
+    let pending = false;
+    // Restore pushes stacked for the pending decision, so an approved replay unwinds
+    // exactly that far in one `go(-depth)`. Reset per decision.
+    let restores = 0;
+
+    const onPopState = () => {
+      if (bypass) {
+        bypass = false;
+        committedRef.current = { href: window.location.href, state: window.history.state };
+        return;
+      }
+      if (!registry.hasArmedGuards()) {
+        committedRef.current = { href: window.location.href, state: window.history.state };
+        return;
+      }
+      const committed = committedRef.current;
+      if (committed === null) return;
+      // Cancel the browser's move by pushing the committed entry on top of wherever it
+      // landed. popstate exposes no direction/distance and the router owns
+      // `history.state`, so restore can only push, not delete. A vetoed forward thus
+      // strands a stub entry — an accepted limit the next pushState truncates.
+      window.history.pushState(committed.state, '', committed.href);
+      restores += 1;
+      if (pending) return;
+      pending = true;
+      void registry.run().then((allowed) => {
+        pending = false;
+        const depth = restores;
+        restores = 0;
+        if (!allowed) return;
+        bypass = true;
+        window.history.go(-depth);
+      });
+    };
+
+    const onBeforeUnload = (event: BeforeUnloadEvent) => {
+      event.preventDefault();
+      // Browsers below the floor (Chrome 108) gate the prompt on a set `returnValue`,
+      // not `preventDefault` alone; the string is ignored. Typed deprecated, still required.
+      // eslint-disable-next-line @typescript-eslint/no-deprecated -- required beforeunload trigger for the supported browser range.
+      event.returnValue = '';
+    };
+
+    window.addEventListener('popstate', onPopState);
+    window.addEventListener('beforeunload', onBeforeUnload);
+    return () => {
+      committedRef.current = null;
+      window.removeEventListener('popstate', onPopState);
+      window.removeEventListener('beforeunload', onBeforeUnload);
+    };
+  }, [armed, registry]);
+
+  // Wrap the shell's transitions so an armed guard is consulted before they commit.
+  // With no guard armed the call stays synchronous — identical to the raw shell value.
+  const guarded = useMemo<NavigationContextValue>(() => {
+    const navigate: NavigationContextValue['navigate'] = (token, search) => {
+      if (!registry.hasArmedGuards()) {
+        value.navigate(token, search);
+        return;
+      }
+      void registry.run().then((allowed) => {
+        if (!allowed) return;
+        value.navigate(token, search);
+        // Advance the committed entry to the resolved destination (the router may commit
+        // async, so `window.location` would be stale). Its router state is unobservable
+        // here, hence `state: null`.
+        if (committedRef.current !== null) {
+          committedRef.current = { href: value.resolvePath(token, search), state: null };
+        }
+      });
+    };
+    const navigatePlugin: NavigationContextValue['navigatePlugin'] = (
+      pluginId,
+      pagePath,
+      params,
+      search,
+    ) => {
+      if (!registry.hasArmedGuards()) {
+        value.navigatePlugin(pluginId, pagePath, params, search);
+        return;
+      }
+      void registry.run().then((allowed) => {
+        if (!allowed) return;
+        value.navigatePlugin(pluginId, pagePath, params, search);
+        if (committedRef.current !== null) {
+          committedRef.current = {
+            href: value.resolvePluginPath(pluginId, pagePath, params, search),
+            state: null,
+          };
+        }
+      });
+    };
+    return { ...value, navigate, navigatePlugin };
+  }, [value, registry]);
+
+  const commitHref = useCallback((href: string) => {
+    if (committedRef.current !== null) committedRef.current = { href, state: null };
+  }, []);
+
+  return createElement(
+    GuardRegistryContext.Provider,
+    { value: registry },
+    createElement(
+      CommitHrefContext.Provider,
+      { value: commitHref },
+      createElement(NavigationContext.Provider, { value: guarded }, children),
+    ),
+  );
 }
 
 function useNavigation(): NavigationContextValue {
@@ -48,6 +274,50 @@ export function useResolvePath(): NavigationContextValue['resolvePath'] {
   return useNavigation().resolvePath;
 }
 
+/**
+ * Block navigation away from the current page while `when` is true. `handler` is
+ * consulted before any SDK-controlled navigation commits — a route-token navigate,
+ * a plugin navigate, or a browser back/forward — and the navigation proceeds only if
+ * it resolves `true`; a promise lets the handler drive a confirm dialog. A full-page
+ * unload (tab close / refresh) is additionally covered by a native `beforeunload`
+ * prompt that fires whenever any guard is armed.
+ *
+ * Guards compose against the provider's shared registry: a feature and a plugin page
+ * may each arm one, and any veto blocks.
+ */
+export function useNavigationGuard(when: boolean, handler: NavigationGuardHandler): void {
+  const registry = useGuardRegistry();
+  const entryRef = useRef<GuardEntry>({ when, handler });
+  // Keep the registered entry pointing at the latest inputs without re-registering.
+  entryRef.current.when = when;
+  entryRef.current.handler = handler;
+
+  useEffect(() => registry.add(entryRef.current), [registry]);
+  useEffect(() => {
+    registry.touch();
+  }, [registry, when]);
+}
+
+/**
+ * Consult the armed navigation guards before a transition the shell drives itself
+ * (a chrome link whose target is outside the route-token map). Resolves `true` when
+ * the navigation may proceed. Token and plugin navigations already run this gate
+ * inside {@link NavigationProvider}; this is the escape hatch for the shell's own
+ * raw-path links, without which such a link would bypass every armed guard.
+ */
+export function useNavigationGate(): (href: string) => Promise<boolean> {
+  const registry = useGuardRegistry();
+  const commitHref = useContext(CommitHrefContext);
+  return useCallback(
+    async (href: string) => {
+      if (registry.hasArmedGuards() && !(await registry.run())) return false;
+      commitHref?.(href);
+      return true;
+    },
+    [registry, commitHref],
+  );
+}
+
 /**
  * Plugin-page navigation: `navigatePlugin` drives a client-side transition to a
  * runtime plugin path, `resolvePluginPath` yields its href. These are the ONLY

package/src/navigation/index.ts

@@ -4,6 +4,8 @@ export {
   useAppNavigate,
   useResolvePath,
   usePluginNavigation,
+  useNavigationGuard,
+  useNavigationGate,
 } from './context';
 export type { AppLinkProps } from './context';
 export type {
@@ -13,4 +15,5 @@ export type {
   PageProps,
   NavigationContextValue,
   PluginSearch,
+  NavigationGuardHandler,
 } from './types';

package/src/navigation/types.ts

@@ -113,3 +113,15 @@ export interface NavigationContextValue {
     search?: PluginSearch,
   ) => string;
 }
+
+/**
+ * A navigation guard's decision function, run while armed before any SDK-controlled
+ * navigation commits ({@link NavigationContextValue.navigate},
+ * {@link NavigationContextValue.navigatePlugin}, or a browser back/forward). Returns
+ * `true` to proceed, `false` to veto; a promise lets it await a confirm dialog.
+ *
+ * Guards compose — navigation proceeds only if every armed guard allows, and the first
+ * veto blocks (at most one dialog). A full-page unload can't await, so it is covered by
+ * a `beforeunload` prompt independent of this handler.
+ */
+export type NavigationGuardHandler = () => boolean | Promise<boolean>;