@tai42/studio-sdk 0.11.0 → 0.13.0

package/src/hooks/useSystemKinds.tsx

@@ -0,0 +1,97 @@
+/**
+ * `useFeatureOff` — the PROACTIVE read of a DB-backed feature's OFF state, off the
+ * system kind-status table (`GET /api/system/kinds`), fetched once per auth flip and
+ * held as SDK state.
+ *
+ * A deployment leaves a database-backed feature cleanly OFF by configuring no store
+ * for it; the kind-status table then reports that kind's `state` as `off` (rather
+ * than `active` / `default`). A write affordance for an OFF feature reads this and
+ * hides itself BEFORE the user acts, instead of learning OFF only from a write's 501
+ * refusal — the reactive `isFeatureDisabled` swallow stays as the backstop for a
+ * stale table.
+ *
+ * A PLAIN fetch state machine (`loading` / `ready` / `failed`), NOT TanStack Query:
+ * the SDK is the shared leaf across the plugin boundary and holds no query context,
+ * exactly as `useCapabilities` does. It is DELIBERATELY non-blocking — a kind counts
+ * as not-off until the table is `ready`, and a failed fetch leaves every kind not-off
+ * so the surface falls back to its reactive 501 handling, never a hard-failed page.
+ */
+import {
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useState,
+  type ReactNode,
+} from 'react';
+import type { KindStatus } from '@tai42/api-client';
+
+import { useApi } from './useApi';
+import { useAuth } from './useAuth';
+
+export type SystemKindsState =
+  | { readonly status: 'loading' }
+  | { readonly status: 'ready'; readonly kinds: readonly KindStatus[] }
+  | { readonly status: 'failed'; readonly error: unknown };
+
+const SystemKindsContext = createContext<SystemKindsState | null>(null);
+
+/**
+ * Fetch the kind-status table once the caller is authenticated and hold it as SDK
+ * state. Gated on `isAuthenticated` (the table is an authed read), so the login
+ * screen never fires a doomed request; a fetch failure settles into `failed`
+ * QUIETLY — no unauthorized routing, no loud error — because the consuming
+ * affordance falls back to its reactive OFF handling.
+ */
+export function SystemKindsProvider({ children }: { children: ReactNode }) {
+  const { isAuthenticated } = useAuth();
+  const api = useApi();
+  const [state, setState] = useState<SystemKindsState>({ status: 'loading' });
+
+  useEffect(() => {
+    if (!isAuthenticated) {
+      // No credential → nothing to read. Reset to the neutral `loading` state so the
+      // next sign-in re-fetches cleanly; every kind reads not-off meanwhile.
+      setState({ status: 'loading' });
+      return;
+    }
+    const controller = new AbortController();
+    setState({ status: 'loading' });
+    api.getSystemKinds(controller.signal).then(
+      (kinds) => {
+        if (!controller.signal.aborted) setState({ status: 'ready', kinds });
+      },
+      (error: unknown) => {
+        if (!controller.signal.aborted) setState({ status: 'failed', error });
+      },
+    );
+    return () => {
+      controller.abort();
+    };
+  }, [api, isAuthenticated]);
+
+  return createElement(SystemKindsContext.Provider, { value: state }, children);
+}
+
+/**
+ * The live kind-status state. Falls back to `loading` when no provider is mounted, so
+ * a consumer rendered outside the shell reads every kind as not-off rather than
+ * throwing — the fail-open default this proactive-hiding idiom relies on.
+ */
+export function useSystemKinds(): SystemKindsState {
+  return useContext(SystemKindsContext) ?? { status: 'loading' };
+}
+
+/**
+ * Whether `kind` is reported OFF by the kind-status table — the single proactive
+ * predicate a write affordance folds in to hide itself before a doomed write. It is
+ * `true` ONLY once the table is `ready` AND that kind's row carries `state: 'off'`;
+ * while the table is loading/failed, no provider is mounted, or the kind is unknown,
+ * it is `false` (treat as not-off until known — under-hiding is safe, the reactive
+ * 501 backstop still catches a genuinely-off feature).
+ */
+export function useFeatureOff(kind: string): boolean {
+  const state = useSystemKinds();
+  if (state.status !== 'ready') return false;
+  return state.kinds.some((row) => row.kind === kind && row.state === 'off');
+}

package/src/index.ts

@@ -64,6 +64,8 @@ export {
   coversWrite,
 } from './hooks/useCapabilities';
 export type { CapabilityState, CapabilityContextValue } from './hooks/useCapabilities';
+export { SystemKindsProvider, useSystemKinds, useFeatureOff } from './hooks/useSystemKinds';
+export type { SystemKindsState } from './hooks/useSystemKinds';
 export { ThemeProvider, useTheme } from './hooks/useTheme';
 export type { Theme, ThemePreference, ThemeState } from './hooks/useTheme';
 export { useBreakpoint } from './hooks/useBreakpoint';
@@ -78,6 +80,7 @@ export {
   useAppNavigate,
   useResolvePath,
   usePluginNavigation,
+  useNavigationGuard,
 } from './navigation';
 export type {
   AppLinkProps,
@@ -87,6 +90,7 @@ export type {
   PageProps,
   NavigationContextValue,
   PluginSearch,
+  NavigationGuardHandler,
 } from './navigation';
 
 // -- Utilities ---------------------------------------------------------------
@@ -146,6 +150,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';
@@ -210,6 +217,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,105 @@ 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);
+
+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 +110,136 @@ 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]);
+
+  return createElement(
+    GuardRegistryContext.Provider,
+    { value: registry },
+    createElement(NavigationContext.Provider, { value: guarded }, children),
+  );
 }
 
 function useNavigation(): NavigationContextValue {
@@ -48,6 +262,30 @@ 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]);
+}
+
 /**
  * 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,7 @@ export {
   useAppNavigate,
   useResolvePath,
   usePluginNavigation,
+  useNavigationGuard,
 } from './context';
 export type { AppLinkProps } from './context';
 export type {
@@ -13,4 +14,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>;