@checkstack/tips-frontend 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# @checkstack/tips-frontend
+
+## 0.2.0
+
+### Minor Changes
+
+- 3547670: Redesign `<Tip>` to be user-triggered instead of auto-opening.
+
+  A small lightbulb icon is now rendered immediately after the wrapped
+  element. The popover only opens when the user clicks the lightbulb.
+  Once the user explicitly dismisses the tip (X, "Got it", or the action
+  button), the lightbulb disappears for that user (per-user when signed
+  in, per-browser when anonymous) and only the underlying element is
+  rendered.
+
+  This replaces the previous auto-open behaviour, which was racing with
+  focus management whenever multiple tips on a page mounted at once
+  (e.g. the Catalog "Add System" + "Add Group" tips would flash open and
+  instantly self-close as Radix's outside-focus handler fired). It also
+  fixes the bug where clicking the anchored button would silently dismiss
+  the tip — the lightbulb model has no implicit dismissal at all.
+
+  The default `align` for the popover changed from `"start"` to `"end"`
+  so the popover hangs off the lightbulb rather than the larger anchor
+  to its left. New optional `triggerClassName` prop on `<TipProps>` lets
+  callers restyle the lightbulb when needed.
+
+- 3547670: Add `@checkstack/tips-*` — first-run tip and onboarding infrastructure for
+  the frontends.
+
+  Three new packages:
+
+  - `@checkstack/tips-common` — RPC contract (`tipsContract`), `TipsApi`
+    client definition, and zod schemas. Fully-qualified tip IDs have shape
+    `<pluginId>.<localTipId>` and are produced exclusively by
+    `qualifyTipId(plugin, localId)` — plugins never write the namespace
+    themselves, and a local id with a leading or trailing `.` is rejected,
+    so one plugin cannot forge or dismiss a tip in another plugin's
+    namespace.
+  - `@checkstack/tips-backend` — Postgres-backed dismissal store
+    (`user_tip_dismissal` with composite PK on `(user_id, tip_id)`),
+    `listDismissed` / `dismiss` / `reset` endpoints scoped to the
+    requesting user via the auto-auth middleware, and a
+    `auth.userDeleted` hook that cleans up dismissals when a user is
+    deleted.
+  - `@checkstack/tips-frontend` — `<Tip>` (anchored popover) and
+    `<TipBanner>` (inline callout) components plus the `useTipState`
+    hook. All three accept `{ plugin, id }` (where `plugin` is the
+    caller's `pluginMetadata`) and route through `qualifyTipId` so the
+    namespace prefix is enforced at the boundary. Persists per-user on
+    the server when logged in, and per-browser in `localStorage`
+    (`checkstack.tips.dismissed`) when anonymous, with cross-tab sync via
+    the `storage` event.
+
+  `@checkstack/ui`'s `<EmptyState>` gains optional `steps` and `actions`
+  props for richer empty-state coaching (numbered onboarding lists +
+  primary CTA), and accepts `ReactNode` for `description`. Existing
+  callers continue to work unchanged.
+
+  `@checkstack/test-utils-backend`'s `createMockDb` now also mocks
+  `insert().values().onConflictDoNothing()` so routers using upsert-or-skip
+  semantics can be unit-tested.
+
+### Patch Changes
+
+- Updated dependencies [42abfff]
+- Updated dependencies [3547670]
+- Updated dependencies [1ef2e79]
+- Updated dependencies [aa89bc5]
+- Updated dependencies [950d6ec]
+- Updated dependencies [3547670]
+  - @checkstack/common@0.9.0
+  - @checkstack/ui@1.8.0
+  - @checkstack/frontend-api@0.5.0
+  - @checkstack/auth-frontend@0.6.0
+  - @checkstack/tips-common@0.2.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@checkstack/tips-frontend",
+  "version": "0.2.0",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "main": "src/index.tsx",
+  "checkstack": {
+    "type": "frontend"
+  },
+  "scripts": {
+    "typecheck": "tsgo -b",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@checkstack/tips-common": "0.1.0",
+    "@checkstack/frontend-api": "0.4.2",
+    "@checkstack/auth-frontend": "0.5.33",
+    "@checkstack/common": "0.8.0",
+    "@checkstack/ui": "1.7.1",
+    "react": "^18.2.0",
+    "lucide-react": "^0.344.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/react": "^18.2.0",
+    "@checkstack/tsconfig": "0.0.7",
+    "@checkstack/scripts": "0.3.0",
+    "@checkstack/test-utils-frontend": "0.0.5"
+  }
+}

package/src/components/Tip.tsx

@@ -0,0 +1,164 @@
+import React, { useState } from "react";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+  Button,
+  cn,
+} from "@checkstack/ui";
+import type { PluginMetadata } from "@checkstack/common";
+import { Lightbulb, X } from "lucide-react";
+import { useTipState } from "../hooks/useTipState";
+
+export interface TipProps {
+  /**
+   * The calling plugin's metadata. The plugin's `pluginId` is automatically
+   * prepended to `id` to produce the fully-qualified tip identifier —
+   * plugins never write the namespace themselves.
+   */
+  plugin: Pick<PluginMetadata, "pluginId">;
+
+  /**
+   * Local tip identifier — the part *after* the plugin's namespace.
+   *
+   * Must not start or end with `.` and must not include the plugin
+   * separator. Two `<Tip>` instances with the same `(plugin, id)` share
+   * dismissal state — useful when the same hint is pinned to multiple
+   * equivalent affordances.
+   */
+  id: string;
+
+  /** Headline shown bold at the top of the popover. */
+  title: string;
+
+  /** Optional explanatory body. Plain text or a node (e.g. for inline links). */
+  description?: React.ReactNode;
+
+  /** Optional CTA shown alongside "Got it". Triggering it also dismisses the tip. */
+  action?: {
+    label: string;
+    onClick: () => void;
+  };
+
+  /** Where the popover opens relative to the lightbulb. Defaults to "bottom". */
+  side?: "top" | "right" | "bottom" | "left";
+
+  /** Alignment of the popover along the chosen side. Defaults to "end". */
+  align?: "start" | "center" | "end";
+
+  /**
+   * The element a tip is configured for. Rendered as-is. The lightbulb
+   * trigger is rendered immediately after, in a shared inline-flex
+   * container so both stay visually grouped without disturbing the
+   * surrounding layout.
+   */
+  children: React.ReactNode;
+
+  /** Optional className applied to the popover content. */
+  contentClassName?: string;
+
+  /** Optional className applied to the lightbulb button. */
+  triggerClassName?: string;
+}
+
+/**
+ * Anchored, user-triggered hint.
+ *
+ * Renders `children` (typically a button, an icon, or any UI element you
+ * want to explain) followed by a small lightbulb that, when clicked,
+ * opens a popover with the tip text.
+ *
+ * The popover never auto-opens — first-time users see the lightbulb as a
+ * subtle "more info available" affordance. Once they read the tip and
+ * confirm with "Got it", the X icon, or the action button, the lightbulb
+ * disappears for that user (per-user when signed in, per-browser when
+ * anonymous) and the underlying element is rendered alone.
+ *
+ * Soft closes (clicking outside the popover, Escape) just close the
+ * popover for now — the lightbulb remains so the user can re-open it.
+ */
+export const Tip: React.FC<TipProps> = ({
+  plugin,
+  id,
+  title,
+  description,
+  action,
+  side = "bottom",
+  align = "end",
+  children,
+  contentClassName,
+  triggerClassName,
+}) => {
+  const { isDismissed, isLoading, dismiss } = useTipState({ plugin, id });
+  const [open, setOpen] = useState(false);
+
+  const handleDismiss = () => {
+    setOpen(false);
+    dismiss();
+  };
+
+  // While we don't yet know whether the tip has been dismissed, render
+  // only the underlying element to avoid a visible lightbulb flicker.
+  if (isLoading || isDismissed) {
+    return <>{children}</>;
+  }
+
+  return (
+    <span className="inline-flex items-center gap-1.5">
+      {children}
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          <button
+            type="button"
+            aria-label={`Show tip: ${title}`}
+            className={cn(
+              "inline-flex size-6 shrink-0 items-center justify-center rounded-full text-amber-500 hover:bg-amber-500/10 hover:text-amber-600 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-amber-500/40 transition-colors",
+              triggerClassName,
+            )}
+          >
+            <Lightbulb className="size-4" />
+          </button>
+        </PopoverTrigger>
+        <PopoverContent
+          side={side}
+          align={align}
+          className={cn("w-80 p-4", contentClassName)}
+        >
+          <div className="flex items-start justify-between gap-2">
+            <p className="text-sm font-semibold text-foreground">{title}</p>
+            <button
+              type="button"
+              onClick={handleDismiss}
+              aria-label="Don't show this tip again"
+              className="text-muted-foreground hover:text-foreground transition-colors"
+            >
+              <X className="size-4" />
+            </button>
+          </div>
+          {description && (
+            <div className="mt-2 text-sm text-muted-foreground">
+              {description}
+            </div>
+          )}
+          <div className="mt-3 flex items-center justify-end gap-2">
+            {action && (
+              <Button
+                size="sm"
+                variant="primary"
+                onClick={() => {
+                  action.onClick();
+                  handleDismiss();
+                }}
+              >
+                {action.label}
+              </Button>
+            )}
+            <Button size="sm" variant="ghost" onClick={handleDismiss}>
+              Got it
+            </Button>
+          </div>
+        </PopoverContent>
+      </Popover>
+    </span>
+  );
+};

package/src/components/TipBanner.tsx

@@ -0,0 +1,106 @@
+import React from "react";
+import { Card, CardContent, Button, cn } from "@checkstack/ui";
+import type { PluginMetadata } from "@checkstack/common";
+import { Lightbulb, X } from "lucide-react";
+import { useTipState } from "../hooks/useTipState";
+
+export interface TipBannerProps {
+  /**
+   * The calling plugin's metadata. The plugin's `pluginId` is automatically
+   * prepended to `id` to produce the fully-qualified tip identifier —
+   * plugins never write the namespace themselves.
+   */
+  plugin: Pick<PluginMetadata, "pluginId">;
+  /** Local tip identifier — the part *after* the plugin's namespace. */
+  id: string;
+  title: string;
+  description?: React.ReactNode;
+  action?: {
+    label: string;
+    onClick: () => void;
+  };
+  /**
+   * Optional hint content rendered immediately to the right of the action
+   * button on the same row — useful for short notes that relate to the
+   * primary CTA (e.g. "Look for the lightbulb icons elsewhere in the UI").
+   * Wraps below the button on narrow viewports.
+   */
+  actionHint?: React.ReactNode;
+  icon?: React.ReactNode;
+  className?: string;
+}
+
+/**
+ * Inline, dismissable callout for use at the top of a page or alongside
+ * an empty state. Disappears entirely once dismissed (no anchor remains),
+ * which makes it appropriate for "first-time on this page" coaching where
+ * there's no ongoing UI element to attach to.
+ */
+export const TipBanner: React.FC<TipBannerProps> = ({
+  plugin,
+  id,
+  title,
+  description,
+  action,
+  actionHint,
+  icon,
+  className,
+}) => {
+  const { isDismissed, isLoading, dismiss } = useTipState({ plugin, id });
+
+  if (isDismissed || isLoading) return null;
+
+  return (
+    <Card
+      className={cn(
+        "border border-primary/30 bg-primary/5",
+        className,
+      )}
+    >
+      <CardContent className="flex items-start gap-3 py-4">
+        <div className="text-primary mt-0.5">
+          {icon ?? <Lightbulb className="size-5" />}
+        </div>
+        <div className="flex-1">
+          <p className="text-sm font-semibold text-foreground">{title}</p>
+          {description && (
+            <div className="mt-1 text-sm text-muted-foreground">
+              {description}
+            </div>
+          )}
+          {(action || actionHint) && (
+            <div className="mt-3 flex flex-wrap items-center justify-between gap-x-3 gap-y-2">
+              {action ? (
+                <Button
+                  size="sm"
+                  variant="primary"
+                  onClick={() => {
+                    action.onClick();
+                    dismiss();
+                  }}
+                >
+                  {action.label}
+                </Button>
+              ) : (
+                <span />
+              )}
+              {actionHint && (
+                <div className="text-xs text-muted-foreground sm:text-right ml-auto">
+                  {actionHint}
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+        <button
+          type="button"
+          onClick={dismiss}
+          aria-label="Dismiss tip"
+          className="text-muted-foreground hover:text-foreground transition-colors"
+        >
+          <X className="size-4" />
+        </button>
+      </CardContent>
+    </Card>
+  );
+};

package/src/components/TipsSynchronizer.tsx

@@ -0,0 +1,43 @@
+import { useEffect, useRef } from "react";
+import { useApi, usePluginClient } from "@checkstack/frontend-api";
+import { authApiRef } from "@checkstack/auth-frontend/api";
+import { TipsApi } from "@checkstack/tips-common";
+
+/**
+ * Headless extension that prefetches the user's dismissed-tips list as
+ * soon as the session is known. Without this, the very first <Tip> on
+ * the page would have to issue its own request — visible as a brief
+ * flash of an already-dismissed popover.
+ *
+ * Renders nothing; mounted into NavbarRightSlot so it's present on every
+ * page that uses the standard layout.
+ */
+export const TipsSynchronizer = () => {
+  const authApi = useApi(authApiRef);
+  const tipsClient = usePluginClient(TipsApi);
+  const { data: session, isPending } = authApi.useSession();
+  const lastUserIdRef = useRef<string | undefined>(undefined);
+
+  // The query is keyed by react-query under the plugin's key; using
+  // `useQuery` here is enough to populate the cache for any later
+  // `useTipState` consumer.
+  const dismissedQuery = tipsClient.listDismissed.useQuery(undefined, {
+    enabled: !!session?.user && !isPending,
+    staleTime: Number.POSITIVE_INFINITY,
+  });
+
+  useEffect(() => {
+    const currentUserId = session?.user?.id ?? undefined;
+    if (currentUserId !== lastUserIdRef.current) {
+      lastUserIdRef.current = currentUserId;
+      // Force a refetch when the user changes (login/logout/switch).
+      // staleTime is Infinity, so without this we'd keep the previous
+      // user's dismissals in the cache.
+      if (currentUserId) {
+        void dismissedQuery.refetch();
+      }
+    }
+  }, [session?.user?.id, dismissedQuery]);
+
+  return null;
+};

package/src/hooks/useLocalDismissals.ts

@@ -0,0 +1,74 @@
+import { useCallback, useEffect, useState } from "react";
+
+const STORAGE_KEY = "checkstack.tips.dismissed";
+
+const readStorage = (): Set<string> => {
+  if (globalThis.window === undefined) return new Set();
+  try {
+    const raw = globalThis.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return new Set();
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return new Set();
+    return new Set(parsed.filter((v): v is string => typeof v === "string"));
+  } catch {
+    return new Set();
+  }
+};
+
+const writeStorage = (ids: Set<string>) => {
+  if (globalThis.window === undefined) return;
+  try {
+    globalThis.localStorage.setItem(STORAGE_KEY, JSON.stringify([...ids]));
+  } catch {
+    // Storage may be unavailable (private mode, quota); the in-memory copy
+    // still keeps the dismissal active for the current page load.
+  }
+};
+
+/**
+ * Local-only dismissal store for anonymous (logged-out) users and as a
+ * synchronous fallback while the server query is loading.
+ *
+ * Synchronizes across tabs of the same browser via the `storage` event so
+ * dismissing a tip in one tab hides it in another.
+ */
+export const useLocalDismissals = () => {
+  const [ids, setIds] = useState<Set<string>>(() => readStorage());
+
+  useEffect(() => {
+    if (globalThis.window === undefined) return;
+
+    const onStorage = (event: StorageEvent) => {
+      if (event.key !== STORAGE_KEY) return;
+      setIds(readStorage());
+    };
+
+    globalThis.addEventListener("storage", onStorage);
+    return () => globalThis.removeEventListener("storage", onStorage);
+  }, []);
+
+  const dismiss = useCallback((tipId: string) => {
+    setIds((prev) => {
+      if (prev.has(tipId)) return prev;
+      const next = new Set(prev);
+      next.add(tipId);
+      writeStorage(next);
+      return next;
+    });
+  }, []);
+
+  const reset = useCallback((tipIds?: string[]) => {
+    setIds((prev) => {
+      if (!tipIds || tipIds.length === 0) {
+        writeStorage(new Set());
+        return new Set();
+      }
+      const next = new Set(prev);
+      for (const id of tipIds) next.delete(id);
+      writeStorage(next);
+      return next;
+    });
+  }, []);
+
+  return { ids, dismiss, reset };
+};

package/src/hooks/useTipState.ts

@@ -0,0 +1,126 @@
+import { useCallback, useMemo } from "react";
+import { useApi, usePluginClient } from "@checkstack/frontend-api";
+import { authApiRef } from "@checkstack/auth-frontend/api";
+import { qualifyTipId, TipsApi } from "@checkstack/tips-common";
+import type { PluginMetadata } from "@checkstack/common";
+import { useLocalDismissals } from "./useLocalDismissals";
+
+export interface UseTipStateOptions {
+  /**
+   * The calling plugin's metadata. The plugin's `pluginId` is automatically
+   * prepended to `id` to produce the fully-qualified tip identifier — plugins
+   * never construct that string themselves, which prevents one plugin from
+   * dismissing or forging tips in another plugin's namespace.
+   */
+  plugin: Pick<PluginMetadata, "pluginId">;
+
+  /**
+   * Local tip identifier — the part *after* the plugin's namespace.
+   *
+   * Must not start or end with a `.` and must not contain the plugin
+   * separator manually. Examples: `"systems.create"`, `"first-run"`.
+   */
+  id: string;
+}
+
+export interface UseTipStateResult {
+  /** Fully-qualified tip ID (`<pluginId>.<id>`) — useful for logs / analytics. */
+  tipId: string;
+  /** True once we know the tip should not be shown to this user. */
+  isDismissed: boolean;
+  /**
+   * True while the dismissal list is being fetched for the first time.
+   * Consumers should typically render nothing while loading — showing a tip
+   * and then hiding it would be flicker.
+   */
+  isLoading: boolean;
+  /** Mark this tip dismissed. Idempotent and safe to call repeatedly. */
+  dismiss: () => void;
+  /** Restore this tip so it shows again. Useful for "replay onboarding". */
+  reset: () => void;
+}
+
+/**
+ * Hook for reading and updating the dismissal state of a single tip.
+ *
+ * Persistence model:
+ * - Logged-in users: state lives on the server in `user_tip_dismissal`; fetched
+ *   once per session and kept in sync via react-query. Mutations optimistically
+ *   update the cache.
+ * - Anonymous users: state lives in `localStorage` under
+ *   `checkstack.tips.dismissed` and syncs across tabs via the `storage` event.
+ *
+ * Both stores are consulted on read, so a tip dismissed locally while logged
+ * out stays dismissed after sign-in (the server copy then takes over once
+ * the user dismisses it again).
+ */
+export const useTipState = ({
+  plugin,
+  id,
+}: UseTipStateOptions): UseTipStateResult => {
+  const tipId = useMemo(() => qualifyTipId(plugin, id), [plugin, id]);
+
+  const authApi = useApi(authApiRef);
+  const tipsClient = usePluginClient(TipsApi);
+  const { data: session, isPending: sessionPending } = authApi.useSession();
+  const local = useLocalDismissals();
+
+  const isLoggedIn = !!session?.user;
+
+  const dismissedQuery = tipsClient.listDismissed.useQuery(undefined, {
+    enabled: isLoggedIn && !sessionPending,
+    staleTime: Number.POSITIVE_INFINITY,
+  });
+
+  // Pull only the stable `mutate` references so we don't capture the entire
+  // mutation result object in dependency arrays — that object is recreated
+  // every render and would re-run our callbacks unnecessarily.
+  const { mutate: dismissMutate } = tipsClient.dismiss.useMutation();
+  const { mutate: resetMutate } = tipsClient.reset.useMutation();
+
+  const refetch = dismissedQuery.refetch;
+
+  const isDismissed = useMemo(() => {
+    if (local.ids.has(tipId)) return true;
+    if (!isLoggedIn) return false;
+    if (!dismissedQuery.data) return false;
+    return dismissedQuery.data.dismissed.some((d) => d.tipId === tipId);
+  }, [tipId, isLoggedIn, dismissedQuery.data, local.ids]);
+
+  const dismiss = useCallback(() => {
+    // Always reflect locally for instant feedback and offline / anonymous use.
+    local.dismiss(tipId);
+    if (isLoggedIn) {
+      dismissMutate(
+        { tipId },
+        {
+          onSuccess: () => {
+            void refetch();
+          },
+        },
+      );
+    }
+  }, [tipId, isLoggedIn, dismissMutate, refetch, local]);
+
+  const reset = useCallback(() => {
+    local.reset([tipId]);
+    if (isLoggedIn) {
+      resetMutate(
+        { tipIds: [tipId] },
+        {
+          onSuccess: () => {
+            void refetch();
+          },
+        },
+      );
+    }
+  }, [tipId, isLoggedIn, resetMutate, refetch, local]);
+
+  // While we don't yet know the server answer for a logged-in user, we
+  // consider the state "loading" — the consumer can decide whether to
+  // suppress rendering to avoid flicker.
+  const isLoading =
+    sessionPending || (isLoggedIn && dismissedQuery.isPending);
+
+  return { tipId, isDismissed, isLoading, dismiss, reset };
+};

package/src/index.tsx

@@ -0,0 +1,28 @@
+import {
+  createFrontendPlugin,
+  NavbarRightSlot,
+} from "@checkstack/frontend-api";
+import { pluginMetadata } from "@checkstack/tips-common";
+import { TipsSynchronizer } from "./components/TipsSynchronizer";
+
+export { Tip } from "./components/Tip";
+export type { TipProps } from "./components/Tip";
+export { TipBanner } from "./components/TipBanner";
+export type { TipBannerProps } from "./components/TipBanner";
+export { useTipState } from "./hooks/useTipState";
+export type {
+  UseTipStateOptions,
+  UseTipStateResult,
+} from "./hooks/useTipState";
+
+export const tipsPlugin = createFrontendPlugin({
+  metadata: pluginMetadata,
+  routes: [],
+  extensions: [
+    {
+      id: "tips.navbar.synchronizer",
+      slot: NavbarRightSlot,
+      component: TipsSynchronizer,
+    },
+  ],
+});

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "extends": "@checkstack/tsconfig/frontend.json",
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../auth-frontend"
+    },
+    {
+      "path": "../common"
+    },
+    {
+      "path": "../frontend-api"
+    },
+    {
+      "path": "../test-utils-frontend"
+    },
+    {
+      "path": "../tips-common"
+    },
+    {
+      "path": "../ui"
+    }
+  ]
+}