@checkstack/notification-frontend 0.2.36 → 0.3.1

package/src/components/NotificationSubscriptionsManager.tsx

@@ -0,0 +1,239 @@
+import React from "react";
+import { Bell, BellOff, BellRing } from "lucide-react";
+import {
+  Button,
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogFooter,
+  useToast,
+  cn,
+} from "@checkstack/ui";
+import { usePluginClient } from "@checkstack/frontend-api";
+import {
+  NotificationApi,
+  subscriptionGroupId,
+  type NotificationTarget,
+} from "@checkstack/notification-common";
+import { extractErrorMessage } from "@checkstack/common";
+import { SubscriptionRow } from "./SubscriptionRow";
+
+export interface NotificationSubscriptionsManagerProps<TResource> {
+  /**
+   * The notification target — typed handle on a kind of resource.
+   * Drives which subscription specs the dialog enumerates.
+   */
+  target: NotificationTarget<TResource>;
+  /**
+   * The specific resource (e.g. a system or group object). Forwarded
+   * to per-spec sub-control panels via the SubControls registry.
+   */
+  resource: TResource;
+  /** Trigger size; defaults to icon-only Bell button. */
+  triggerSize?: "default" | "sm" | "lg" | "icon";
+  triggerClassName?: string;
+}
+
+/**
+ * Single component used on every "manage notifications for this
+ * resource" surface. The dialog enumerates registered subscription
+ * specs *from the backend's spec registry* (single source of truth) —
+ * so a row appears for every spec the platform knows about, not just
+ * the ones a frontend plugin remembered to wire up. Sub-controls
+ * (e.g. anomaly's per-field mute) attach via the
+ * `registerSubscriptionSubControls` registry, keyed by specId.
+ */
+export function NotificationSubscriptionsManager<TResource>({
+  target,
+  resource,
+  triggerSize = "icon",
+  triggerClassName,
+}: NotificationSubscriptionsManagerProps<TResource>) {
+  const [open, setOpen] = React.useState(false);
+  const notificationClient = usePluginClient(NotificationApi);
+  const toast = useToast();
+
+  const resourceKey = target.keyOf(resource);
+  const resourceLabel = target.labelOf(resource);
+
+  const { data: allSpecs = [] } =
+    notificationClient.listSubscriptionSpecs.useQuery(
+      {},
+      { staleTime: 60_000 },
+    );
+
+  const specs = React.useMemo(
+    () => allSpecs.filter((s) => s.targetTypeId === target.targetTypeId),
+    [allSpecs, target.targetTypeId],
+  );
+
+  const groupIds = React.useMemo(
+    () => specs.map((s) => subscriptionGroupId(s, resourceKey)),
+    [specs, resourceKey],
+  );
+
+  const { data: statusMap = {}, refetch: refetchStatus } =
+    notificationClient.getMySubscriptionStatus.useQuery(
+      { groupIds },
+      { enabled: groupIds.length > 0, staleTime: 30_000 },
+    );
+
+  const subscribedCount = groupIds.filter((id) => statusMap[id]).length;
+  const totalCount = groupIds.length;
+  const allSubscribed = totalCount > 0 && subscribedCount === totalCount;
+  const anySubscribed = subscribedCount > 0;
+
+  const subscribeMutation = notificationClient.subscribe.useMutation();
+  const unsubscribeMutation = notificationClient.unsubscribe.useMutation();
+  const isPending =
+    subscribeMutation.isPending || unsubscribeMutation.isPending;
+
+  const handleSubscribeAll = async () => {
+    try {
+      await Promise.all(
+        groupIds
+          .filter((id) => !statusMap[id])
+          .map((groupId) => subscribeMutation.mutateAsync({ groupId })),
+      );
+      toast.success(`Subscribed to all notifications for ${resourceLabel}`);
+      void refetchStatus();
+    } catch (error) {
+      toast.error(extractErrorMessage(error, "Failed to subscribe to all"));
+    }
+  };
+
+  const handleUnsubscribeAll = async () => {
+    try {
+      await Promise.all(
+        groupIds
+          .filter((id) => statusMap[id])
+          .map((groupId) => unsubscribeMutation.mutateAsync({ groupId })),
+      );
+      toast.success(
+        `Unsubscribed from all notifications for ${resourceLabel}`,
+      );
+      void refetchStatus();
+    } catch (error) {
+      toast.error(
+        extractErrorMessage(error, "Failed to unsubscribe from all"),
+      );
+    }
+  };
+
+  const TriggerIcon = anySubscribed ? BellRing : Bell;
+
+  return (
+    <>
+      <Button
+        type="button"
+        variant={anySubscribed ? "primary" : "ghost"}
+        size={triggerSize}
+        onClick={() => setOpen(true)}
+        className={cn(
+          "transition-all duration-200",
+          !anySubscribed && "text-muted-foreground hover:text-foreground",
+          triggerClassName,
+        )}
+        title={`Manage notifications for ${resourceLabel}`}
+        aria-label={`Manage notifications for ${resourceLabel}`}
+      >
+        <TriggerIcon
+          className={cn("h-4 w-4", anySubscribed && "fill-current")}
+          aria-hidden="true"
+        />
+      </Button>
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent size="lg">
+          <DialogHeader>
+            <DialogTitle className="flex items-center gap-2">
+              <Bell className="h-4 w-4" />
+              Notifications for {resourceLabel}
+            </DialogTitle>
+            <DialogDescription>
+              Choose which notification types you want to receive for
+              this {target.resourceKind}.
+            </DialogDescription>
+          </DialogHeader>
+
+          <div className="space-y-3">
+            {totalCount === 0 ? (
+              <div className="rounded-md border border-border bg-muted/20 p-4 text-sm text-muted-foreground">
+                No notification types are available for this{" "}
+                {target.resourceKind} yet.
+              </div>
+            ) : (
+              <>
+                <div className="flex items-center justify-between gap-3 rounded-md border border-border bg-muted/20 p-3">
+                  <div className="text-sm min-w-0">
+                    <div className="font-medium">
+                      {subscribedCount} of {totalCount} subscribed
+                    </div>
+                    <div className="text-xs text-muted-foreground">
+                      Toggle every notification type at once.
+                    </div>
+                  </div>
+                  <div className="flex items-center gap-2 shrink-0">
+                    {allSubscribed ? (
+                      <Button
+                        type="button"
+                        variant="outline"
+                        size="sm"
+                        disabled={isPending}
+                        onClick={handleUnsubscribeAll}
+                      >
+                        <BellOff className="mr-1 h-3 w-3" />
+                        Unsubscribe from all
+                      </Button>
+                    ) : (
+                      <Button
+                        type="button"
+                        variant="primary"
+                        size="sm"
+                        disabled={isPending}
+                        onClick={handleSubscribeAll}
+                      >
+                        <BellRing className="mr-1 h-3 w-3" />
+                        Subscribe to all
+                      </Button>
+                    )}
+                  </div>
+                </div>
+                <div className="overflow-hidden rounded-md border border-border">
+                  {specs.map((spec) => {
+                    const groupId = subscriptionGroupId(spec, resourceKey);
+                    return (
+                      <SubscriptionRow
+                        key={spec.specId}
+                        specId={spec.specId}
+                        title={spec.display.title}
+                        description={spec.display.description}
+                        iconName={spec.display.iconName}
+                        groupId={groupId}
+                        resource={resource}
+                        isDirectlySubscribed={statusMap[groupId] ?? false}
+                        onToggled={() => void refetchStatus()}
+                      />
+                    );
+                  })}
+                </div>
+              </>
+            )}
+          </div>
+
+          <DialogFooter>
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={() => setOpen(false)}
+            >
+              Done
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

package/src/components/SubjectKindRegistry.ts

@@ -0,0 +1,57 @@
+import type { ComponentType } from "react";
+import { Box } from "lucide-react";
+import type { LucideIcon } from "lucide-react";
+
+/**
+ * Frontend rendering metadata for a notification subject `kind`. Domain
+ * plugins register their kinds at module load (typically from each
+ * `*-frontend` package's plugin entry point) so the bell and notifications
+ * page can show kind-appropriate icons and labels.
+ *
+ * Kinds are namespaced as `<pluginId>.<localKind>` (matching the backend
+ * convention enforced by `NotificationSubjectSchema`). Unknown kinds
+ * (e.g., from a plugin the current user hasn't installed) fall back to a
+ * generic chip.
+ */
+export interface SubjectKindRenderer {
+  /** Human-readable singular label, e.g., "System". */
+  label: string;
+  /** Lucide icon component shown in the chip. */
+  icon: LucideIcon | ComponentType<{ className?: string }>;
+}
+
+const registry = new Map<string, SubjectKindRenderer>();
+
+/**
+ * Register frontend rendering metadata for a notification subject kind.
+ * Idempotent — re-registering the same kind overwrites the prior entry.
+ *
+ * Example:
+ * ```ts
+ * import { Server } from "lucide-react";
+ * import { registerSubjectKind } from "@checkstack/notification-frontend";
+ *
+ * registerSubjectKind("catalog.system", { label: "System", icon: Server });
+ * ```
+ */
+export function registerSubjectKind(
+  kind: string,
+  renderer: SubjectKindRenderer,
+): void {
+  registry.set(kind, renderer);
+}
+
+/** Default renderer used for unknown / unregistered kinds. */
+const FALLBACK_RENDERER: SubjectKindRenderer = {
+  label: "Subject",
+  icon: Box,
+};
+
+/**
+ * Look up the renderer for a kind, falling back to a generic chip when the
+ * kind hasn't been registered (e.g., emitted by a plugin not loaded in
+ * this frontend bundle).
+ */
+export function getSubjectKindRenderer(kind: string): SubjectKindRenderer {
+  return registry.get(kind) ?? FALLBACK_RENDERER;
+}

package/src/components/SubscriptionRow.tsx

@@ -0,0 +1,191 @@
+import React from "react";
+import { Bell, BellOff, ChevronDown, ChevronRight } from "lucide-react";
+import { Button, DynamicIcon, type LucideIconName, useToast } from "@checkstack/ui";
+import { usePluginClient } from "@checkstack/frontend-api";
+import { NotificationApi } from "@checkstack/notification-common";
+import { extractErrorMessage } from "@checkstack/common";
+import {
+  getSubscriptionSubControls,
+  type SubscriptionSubControlsComponent,
+} from "./SubscriptionSubControlsRegistry";
+
+/**
+ * Inheritance source enriched with display data. The row reveals these
+ * as a small "Inherited from: …" hint when the user is reachable via a
+ * parent group rather than a direct subscription.
+ */
+export interface ResolvedInheritance {
+  groupId: string;
+  label: string;
+  /** True if the user is subscribed to this parent group. */
+  subscribed: boolean;
+}
+
+export interface SubscriptionRowProps {
+  /** specId — also the lookup key into the SubControls registry. */
+  specId: string;
+  /** Display fields lifted off the registered spec record. */
+  title: string;
+  description: string;
+  iconName?: string;
+  /**
+   * The fully-resolved groupId for this (spec × resource). Computed by
+   * the manager so the row doesn't need the spec object.
+   */
+  groupId: string;
+  /**
+   * The resource handed to the optional SubControls component (anomaly
+   * mute list, etc.). Untyped here because the registry stores
+   * components keyed by specId — the registering plugin owns the type
+   * contract.
+   */
+  resource: unknown;
+  /** Whether the current user is directly subscribed to `groupId`. */
+  isDirectlySubscribed: boolean;
+  /**
+   * Pre-resolved inheritance sources. Optional, cosmetic — the backend
+   * dispatcher already walks parent edges at notification time.
+   */
+  inheritance?: ResolvedInheritance[];
+  /** Map of inherited groupId → subscribed?. Optional. */
+  inheritanceStatus?: Record<string, boolean>;
+  /** Re-fetch the surrounding status query after a successful toggle. */
+  onToggled?: () => void;
+}
+
+/**
+ * Generic row that powers every notification-subscription dialog row.
+ * Owns the subscribe toggle, the inheritance hint, and the optional
+ * sub-controls panel. Driven entirely by display fields from the
+ * backend's spec registry — no ties to a slot extension.
+ */
+export function SubscriptionRow({
+  specId,
+  title,
+  description,
+  iconName,
+  groupId,
+  resource,
+  isDirectlySubscribed,
+  inheritance,
+  inheritanceStatus,
+  onToggled,
+}: SubscriptionRowProps) {
+  const notificationClient = usePluginClient(NotificationApi);
+  const toast = useToast();
+  const [expanded, setExpanded] = React.useState(false);
+
+  const SubControls = getSubscriptionSubControls(specId) as
+    | SubscriptionSubControlsComponent<unknown>
+    | undefined;
+
+  const inheritedActive = (inheritance ?? []).filter(
+    (i) => inheritanceStatus?.[i.groupId],
+  );
+  const isReachable = isDirectlySubscribed || inheritedActive.length > 0;
+
+  const subscribeMutation = notificationClient.subscribe.useMutation({
+    onSuccess: () => onToggled?.(),
+    onError: (error) =>
+      toast.error(
+        extractErrorMessage(error, "Failed to subscribe to notifications"),
+      ),
+  });
+  const unsubscribeMutation = notificationClient.unsubscribe.useMutation({
+    onSuccess: () => onToggled?.(),
+    onError: (error) =>
+      toast.error(
+        extractErrorMessage(error, "Failed to unsubscribe from notifications"),
+      ),
+  });
+
+  const isPending =
+    subscribeMutation.isPending || unsubscribeMutation.isPending;
+
+  const handleToggle = () => {
+    if (isDirectlySubscribed) {
+      unsubscribeMutation.mutate({ groupId });
+    } else {
+      subscribeMutation.mutate({ groupId });
+    }
+  };
+
+  const ToggleIcon = isDirectlySubscribed ? BellOff : Bell;
+
+  return (
+    <div className="flex flex-col border-b last:border-b-0">
+      <div className="flex items-center gap-3 px-4 py-3">
+        <div className="shrink-0 rounded-md bg-muted/40 p-2 text-muted-foreground">
+          {iconName ? (
+            <DynamicIcon
+              name={iconName as LucideIconName}
+              className="h-4 w-4"
+              fallback={Bell}
+            />
+          ) : (
+            <Bell className="h-4 w-4" />
+          )}
+        </div>
+        <div className="flex-1 min-w-0">
+          <div className="text-sm font-medium">{title}</div>
+          <div className="text-xs text-muted-foreground">{description}</div>
+          {!isDirectlySubscribed && inheritedActive.length > 0 && (
+            <div className="text-[11px] text-muted-foreground mt-1">
+              Inherited from:{" "}
+              {inheritedActive.map((i, idx) => (
+                <React.Fragment key={i.groupId}>
+                  {idx > 0 ? ", " : undefined}
+                  <span className="font-medium">{i.label}</span>
+                </React.Fragment>
+              ))}
+              <Button
+                type="button"
+                variant="link"
+                size="sm"
+                className="ml-1 h-auto p-0 text-[11px]"
+                disabled={isPending}
+                onClick={handleToggle}
+              >
+                Override here
+              </Button>
+            </div>
+          )}
+        </div>
+        <div className="flex items-center gap-2 shrink-0">
+          {SubControls && isReachable && (
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              className="h-7 px-2 text-[11px] gap-1"
+              onClick={() => setExpanded((e) => !e)}
+            >
+              {expanded ? (
+                <ChevronDown className="h-3 w-3" />
+              ) : (
+                <ChevronRight className="h-3 w-3" />
+              )}
+              Details
+            </Button>
+          )}
+          <Button
+            type="button"
+            variant={isDirectlySubscribed ? "outline" : "primary"}
+            size="sm"
+            className="h-7 px-2 text-[11px] gap-1"
+            disabled={isPending}
+            onClick={handleToggle}
+          >
+            <ToggleIcon className="h-3 w-3" />
+            {isDirectlySubscribed ? "Unsubscribe" : "Subscribe"}
+          </Button>
+        </div>
+      </div>
+      {SubControls && isReachable && expanded && (
+        <div className="px-4 pb-4 pt-1 border-t bg-muted/20">
+          <SubControls resource={resource} groupId={groupId} />
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/SubscriptionSubControlsRegistry.ts

@@ -0,0 +1,45 @@
+import type { ComponentType } from "react";
+import type { NotificationSubscriptionSpec } from "@checkstack/notification-common";
+
+/**
+ * Optional per-spec sub-control panel — anomaly's per-field mute list,
+ * future severity / channel filters, etc. The dialog renders rows from
+ * the backend's spec registry (single source of truth), but plugins
+ * that want sub-granularity register their React component here keyed
+ * by `specId`.
+ *
+ * Registration is idempotent — re-registering the same spec overwrites
+ * the prior entry.
+ */
+export type SubscriptionSubControlsComponent<TResource = unknown> =
+  ComponentType<{
+    resource: TResource;
+    groupId: string;
+  }>;
+
+const registry = new Map<string, SubscriptionSubControlsComponent<unknown>>();
+
+/**
+ * Register a sub-control panel for a subscription spec. Most plugins
+ * never call this — only the few that want sub-granularity (anomaly's
+ * mute list).
+ */
+export function registerSubscriptionSubControls<TResource>(
+  spec: NotificationSubscriptionSpec<TResource>,
+  Component: SubscriptionSubControlsComponent<TResource>,
+): void {
+  registry.set(
+    spec.specId,
+    Component as SubscriptionSubControlsComponent<unknown>,
+  );
+}
+
+/**
+ * Look up the registered sub-control component for a spec id; returns
+ * undefined when none was registered.
+ */
+export function getSubscriptionSubControls(
+  specId: string,
+): SubscriptionSubControlsComponent<unknown> | undefined {
+  return registry.get(specId);
+}

package/src/components/collapse.ts

@@ -0,0 +1,59 @@
+import type { Notification } from "@checkstack/notification-common";
+
+/**
+ * A group of related notifications that share a `collapseKey`. The newest
+ * notification (`representative`) drives the rendered title/body/action;
+ * `count` is the total number of notifications in the group;
+ * `notifications` is the full chronological list (newest first) for
+ * timeline expansion.
+ */
+export interface CollapsedNotification {
+  /** Unique key for React reconciliation. The collapse key, or the notification id when no collapse key is set. */
+  key: string;
+  /** Whether this group represents multiple underlying notifications. */
+  collapsed: boolean;
+  count: number;
+  representative: Notification;
+  notifications: Notification[];
+}
+
+/**
+ * Group notifications by `collapseKey`. Notifications without a key remain
+ * as singletons. Within a group, the representative is the newest by
+ * `createdAt`. Group order is the order of first appearance in the input,
+ * so a list ordered by `createdAt desc` produces groups whose order
+ * matches their newest member.
+ */
+export function groupByCollapseKey(
+  notifications: readonly Notification[],
+): CollapsedNotification[] {
+  const order: string[] = [];
+  const groups = new Map<string, Notification[]>();
+
+  for (const n of notifications) {
+    const key = n.collapseKey ?? `__nokey:${n.id}`;
+    if (!groups.has(key)) {
+      groups.set(key, []);
+      order.push(key);
+    }
+    groups.get(key)!.push(n);
+  }
+
+  return order.map((key) => {
+    const items = groups.get(key)!;
+    // Sort newest first within the group; createdAt is a Date in the
+    // schema-validated response.
+    const sorted = items.toSorted(
+      (a, b) =>
+        new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
+    );
+    const representative = sorted[0]!;
+    return {
+      key,
+      collapsed: sorted.length > 1,
+      count: sorted.length,
+      representative,
+      notifications: sorted,
+    };
+  });
+}

package/src/index.tsx

@@ -13,6 +13,29 @@ import { NotificationsPage } from "./pages/NotificationsPage";
 import { NotificationSettingsPage } from "./pages/NotificationSettingsPage";
 import { NotificationUserMenuItems } from "./components/UserMenuItems";
 
+// Plugin-extensible kind registry — domain frontends call `registerSubjectKind`
+// at module load to bind their kinds (e.g., "catalog.system") to icon + label.
+export {
+  registerSubjectKind,
+  getSubjectKindRenderer,
+} from "./components/SubjectKindRegistry";
+export type { SubjectKindRenderer } from "./components/SubjectKindRegistry";
+export { NotificationSubjects } from "./components/NotificationSubjects";
+export {
+  SubscriptionRow,
+  type SubscriptionRowProps,
+  type ResolvedInheritance,
+} from "./components/SubscriptionRow";
+export {
+  NotificationSubscriptionsManager,
+  type NotificationSubscriptionsManagerProps,
+} from "./components/NotificationSubscriptionsManager";
+export {
+  registerSubscriptionSubControls,
+  getSubscriptionSubControls,
+  type SubscriptionSubControlsComponent,
+} from "./components/SubscriptionSubControlsRegistry";
+
 export const notificationPlugin = createFrontendPlugin({
   metadata: pluginMetadata,
   routes: [