@checkstack/announcement-frontend 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# @checkstack/announcement-frontend
+
+## 0.2.0
+
+### Minor Changes
+
+- dee86ec: feat: add portal announcement system
+
+  Introduces a complete announcement system for communicating with portal users:
+
+  - **announcement-common**: Zod schemas for announcements (severity, visibility, display mode), oRPC contract with 6 procedures (public retrieval, user dismissal, admin CRUD), access rules, and `ANNOUNCEMENT_UPDATED` signal definition
+  - **announcement-backend**: Drizzle schema with `announcements` and `announcement_dismissals` tables, router with temporal filtering, visibility control, per-user dismissal persistence, user cleanup hook, real-time signal broadcasting on create/update/delete, and command palette registration ("Create Announcement", "Manage Announcements" with `⇧⌘A` shortcut)
+  - **announcement-frontend**: Admin management page with create/edit dialog, global banner component above the navbar (severity-colored, expandable markdown), dashboard cards with compact expand/collapse, admin menu link, and real-time WebSocket signal subscription for instant UI updates
+  - **frontend**: Integrates AnnouncementBanner into App.tsx for global visibility
+
+### Patch Changes
+
+- Updated dependencies [dee86ec]
+  - @checkstack/announcement-common@0.2.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@checkstack/announcement-frontend",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "src/index.tsx",
+  "checkstack": {
+    "type": "frontend"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/announcement-common": "0.1.0",
+    "@checkstack/auth-frontend": "0.5.17",
+    "@checkstack/common": "0.6.4",
+    "@checkstack/frontend-api": "0.3.8",
+    "@checkstack/signal-frontend": "0.0.14",
+    "@checkstack/ui": "1.2.0",
+    "date-fns": "^4.1.0",
+    "lucide-react": "^0.344.0",
+    "react": "^18.2.0",
+    "react-router-dom": "^6.20.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/react": "^18.2.0",
+    "@checkstack/tsconfig": "0.0.4",
+    "@checkstack/scripts": "0.1.2"
+  }
+}

package/src/components/AnnouncementBanner.tsx

@@ -0,0 +1,244 @@
+import React, { useState, useCallback } from "react";
+import { usePluginClient } from "@checkstack/frontend-api";
+import {
+  AnnouncementApi,
+  ANNOUNCEMENT_UPDATED,
+  type Announcement,
+} from "@checkstack/announcement-common";
+import { useSignal } from "@checkstack/signal-frontend";
+import { MarkdownBlock } from "@checkstack/ui";
+import {
+  Info,
+  AlertTriangle,
+  AlertOctagon,
+  X,
+  ChevronDown,
+  ChevronUp,
+} from "lucide-react";
+
+const DISMISSED_STORAGE_KEY = "checkstack-dismissed-announcements";
+
+/**
+ * Returns a severity-specific icon component.
+ */
+function SeverityIcon({ severity }: { severity: Announcement["severity"] }) {
+  switch (severity) {
+    case "critical": {
+      return <AlertOctagon className="h-4 w-4 flex-shrink-0" />;
+    }
+    case "warning": {
+      return <AlertTriangle className="h-4 w-4 flex-shrink-0" />;
+    }
+    default: {
+      return <Info className="h-4 w-4 flex-shrink-0" />;
+    }
+  }
+}
+
+/**
+ * Returns Tailwind class names for the severity-based banner styling.
+ */
+function getSeverityStyles(severity: Announcement["severity"]): {
+  bg: string;
+  text: string;
+  border: string;
+  dismissHover: string;
+} {
+  switch (severity) {
+    case "critical": {
+      return {
+        bg: "bg-destructive/10",
+        text: "text-destructive",
+        border: "border-destructive/20",
+        dismissHover: "hover:bg-destructive/20",
+      };
+    }
+    case "warning": {
+      return {
+        bg: "bg-warning/10",
+        text: "text-warning",
+        border: "border-warning/20",
+        dismissHover: "hover:bg-warning/20",
+      };
+    }
+    default: {
+      return {
+        bg: "bg-primary/10",
+        text: "text-primary",
+        border: "border-primary/20",
+        dismissHover: "hover:bg-primary/20",
+      };
+    }
+  }
+}
+
+/**
+ * Get dismissed announcement IDs from localStorage (for anonymous users).
+ */
+function getLocalDismissedIds(): Set<string> {
+  try {
+    const stored = localStorage.getItem(DISMISSED_STORAGE_KEY);
+    if (!stored) return new Set();
+    const ids: unknown = JSON.parse(stored);
+    if (Array.isArray(ids)) {
+      return new Set(ids.filter((id): id is string => typeof id === "string"));
+    }
+    return new Set();
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Add an announcement ID to the localStorage dismissed set.
+ */
+function saveLocalDismissedId(id: string) {
+  const current = getLocalDismissedIds();
+  current.add(id);
+  localStorage.setItem(DISMISSED_STORAGE_KEY, JSON.stringify([...current]));
+}
+
+/**
+ * A single banner strip for one announcement.
+ */
+function BannerItem({
+  announcement,
+  onDismiss,
+}: {
+  announcement: Announcement;
+  onDismiss: (id: string) => void;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  const styles = getSeverityStyles(announcement.severity);
+
+  // Only show expand toggle if the message is longer than just the title
+  const hasExpandableContent = announcement.message.length > 0;
+
+  return (
+    <div
+      className={`${styles.bg} ${styles.border} border-b px-4 py-2 transition-all duration-200`}
+    >
+      <div className="flex items-center gap-3 max-w-7xl mx-auto">
+        <SeverityIcon severity={announcement.severity} />
+
+        <span className={`text-sm font-medium ${styles.text} flex-1`}>
+          {announcement.title}
+        </span>
+
+        {hasExpandableContent && (
+          <button
+            type="button"
+            onClick={() => setExpanded(!expanded)}
+            className={`${styles.text} p-1 rounded ${styles.dismissHover} transition-colors`}
+            aria-label={expanded ? "Collapse details" : "Expand details"}
+          >
+            {expanded ? (
+              <ChevronUp className="h-4 w-4" />
+            ) : (
+              <ChevronDown className="h-4 w-4" />
+            )}
+          </button>
+        )}
+
+        <button
+          type="button"
+          onClick={() => onDismiss(announcement.id)}
+          className={`${styles.text} p-1 rounded ${styles.dismissHover} transition-colors`}
+          aria-label="Dismiss announcement"
+        >
+          <X className="h-4 w-4" />
+        </button>
+      </div>
+
+      {expanded && hasExpandableContent && (
+        <div className="max-w-7xl mx-auto mt-2 pl-7 pb-1">
+          <div className="text-sm opacity-90">
+            <MarkdownBlock size="sm">{announcement.message}</MarkdownBlock>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Severity sort priority for sorting banners (critical first).
+ */
+const SEVERITY_ORDER: Record<string, number> = {
+  critical: 0,
+  warning: 1,
+  info: 2,
+};
+
+/**
+ * Global announcement banner component.
+ * Renders active banner announcements as slim strips above the navbar.
+ *
+ * Must be rendered in App.tsx outside of auth-gated areas since it needs
+ * to work for unauthenticated users viewing public announcements.
+ */
+export const AnnouncementBanner: React.FC = () => {
+  const announcementClient = usePluginClient(AnnouncementApi);
+  const [localDismissedIds, setLocalDismissedIds] = useState<Set<string>>(() =>
+    getLocalDismissedIds(),
+  );
+
+  const { data, isLoading, refetch } =
+    announcementClient.getActiveAnnouncements.useQuery();
+
+  // Refetch own query immediately + invalidate all announcement queries
+  // (including the dashboard's includeDismissed variant) for cross-component freshness.
+  // oRPC query keys are structured as [[...path], { type, input }].
+  useSignal(ANNOUNCEMENT_UPDATED, () => {
+    void refetch();
+  });
+
+  // Server-side dismiss — extract stable mutate function to avoid re-renders
+  const { mutate: dismissOnServer } =
+    announcementClient.dismissAnnouncement.useMutation({});
+
+  // Filter to banner-visible announcements
+  const bannerAnnouncements = React.useMemo(() => {
+    if (!data?.announcements) return [];
+
+    return data.announcements
+      .filter((a) => a.displayMode === "banner" || a.displayMode === "both")
+      .filter((a) => !localDismissedIds.has(a.id))
+      .toSorted(
+        (a, b) =>
+          (SEVERITY_ORDER[a.severity] ?? 2) - (SEVERITY_ORDER[b.severity] ?? 2),
+      );
+  }, [data?.announcements, localDismissedIds]);
+
+  const handleDismiss = useCallback(
+    (id: string) => {
+      // Always save to localStorage (works for anonymous and authenticated)
+      saveLocalDismissedId(id);
+      setLocalDismissedIds((prev) => {
+        const next = new Set(prev);
+        next.add(id);
+        return next;
+      });
+
+      // Also dismiss server-side (fire-and-forget, silently fails for anonymous)
+      dismissOnServer({ announcementId: id });
+    },
+    [dismissOnServer],
+  );
+
+  if (isLoading || bannerAnnouncements.length === 0) {
+    return <></>;
+  }
+
+  return (
+    <div className="w-full">
+      {bannerAnnouncements.map((announcement) => (
+        <BannerItem
+          key={announcement.id}
+          announcement={announcement}
+          onDismiss={handleDismiss}
+        />
+      ))}
+    </div>
+  );
+};

package/src/components/AnnouncementMenuItems.tsx

@@ -0,0 +1,30 @@
+import React from "react";
+import { Link } from "react-router-dom";
+import { Megaphone } from "lucide-react";
+import type { UserMenuItemsContext } from "@checkstack/frontend-api";
+import { DropdownMenuItem } from "@checkstack/ui";
+import { resolveRoute } from "@checkstack/common";
+import {
+  announcementRoutes,
+  announcementAccess,
+  pluginMetadata,
+} from "@checkstack/announcement-common";
+
+export const AnnouncementMenuItems = ({
+  accessRules: userPerms,
+}: UserMenuItemsContext) => {
+  const qualifiedId = `${pluginMetadata.pluginId}.${announcementAccess.manage.id}`;
+  const canManage = userPerms.includes("*") || userPerms.includes(qualifiedId);
+
+  if (!canManage) {
+    return <React.Fragment />;
+  }
+
+  return (
+    <Link to={resolveRoute(announcementRoutes.routes.manage)}>
+      <DropdownMenuItem icon={<Megaphone className="w-4 h-4" />}>
+        Announcements
+      </DropdownMenuItem>
+    </Link>
+  );
+};

package/src/components/DashboardAnnouncements.tsx

@@ -0,0 +1,147 @@
+import React, { useState } from "react";
+import { usePluginClient } from "@checkstack/frontend-api";
+import { AnnouncementApi, ANNOUNCEMENT_UPDATED, type Announcement } from "@checkstack/announcement-common";
+import { useSignal } from "@checkstack/signal-frontend";
+import { MarkdownBlock } from "@checkstack/ui";
+import {
+  Info,
+  AlertTriangle,
+  AlertOctagon,
+  ChevronDown,
+  ChevronUp,
+  Megaphone,
+} from "lucide-react";
+
+/**
+ * Returns the right icon for a severity level.
+ */
+function SeverityIcon({
+  severity,
+  className,
+}: {
+  severity: Announcement["severity"];
+  className?: string;
+}) {
+  switch (severity) {
+    case "critical": {
+      return <AlertOctagon className={className} />;
+    }
+    case "warning": {
+      return <AlertTriangle className={className} />;
+    }
+    default: {
+      return <Info className={className} />;
+    }
+  }
+}
+
+/**
+ * Severity to border/accent color mapping.
+ */
+function getSeverityColor(severity: Announcement["severity"]): string {
+  switch (severity) {
+    case "critical": {
+      return "border-l-destructive text-destructive";
+    }
+    case "warning": {
+      return "border-l-warning text-warning";
+    }
+    default: {
+      return "border-l-primary text-primary";
+    }
+  }
+}
+
+/**
+ * A single compact announcement card with expand/collapse.
+ */
+function AnnouncementCard({ announcement }: { announcement: Announcement }) {
+  const [expanded, setExpanded] = useState(false);
+  const severityColor = getSeverityColor(announcement.severity);
+  const [borderClass, textClass] = severityColor.split(" ");
+
+  return (
+    <div
+      className={`bg-card border border-border rounded-lg border-l-4 ${borderClass} transition-all duration-200`}
+    >
+      <button
+        type="button"
+        onClick={() => setExpanded(!expanded)}
+        className="w-full px-4 py-3 flex items-center gap-3 text-left hover:bg-muted/50 rounded-r-lg transition-colors"
+      >
+        <SeverityIcon
+          severity={announcement.severity}
+          className={`h-4 w-4 flex-shrink-0 ${textClass}`}
+        />
+        <span className="text-sm font-medium text-foreground flex-1 truncate">
+          {announcement.title}
+        </span>
+        {expanded ? (
+          <ChevronUp className="h-4 w-4 text-muted-foreground flex-shrink-0" />
+        ) : (
+          <ChevronDown className="h-4 w-4 text-muted-foreground flex-shrink-0" />
+        )}
+      </button>
+
+      {expanded && (
+        <div className="px-4 pb-3 pl-11 animate-in slide-in-from-top-1 duration-200">
+          <div className="text-sm text-muted-foreground">
+            <MarkdownBlock size="sm">{announcement.message}</MarkdownBlock>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Dashboard announcement section.
+ * Renders inside the Overview section as compact, expandable cards.
+ * Only shows when there are active dashboard-mode announcements.
+ */
+export const DashboardAnnouncements: React.FC = () => {
+  const announcementClient = usePluginClient(AnnouncementApi);
+
+  // Always refetch on mount so the dashboard shows fresh data when navigated to.
+  // Also subscribe to signals for instant updates while actively viewing.
+  const { data, isLoading, refetch } =
+    announcementClient.getActiveAnnouncements.useQuery(
+      { includeDismissed: true },
+      { refetchOnMount: "always" },
+    );
+
+  useSignal(ANNOUNCEMENT_UPDATED, () => {
+    void refetch();
+  });
+
+  const dashboardAnnouncements = React.useMemo(() => {
+    if (!data?.announcements) return [];
+
+    return data.announcements.filter(
+      (a) => a.displayMode === "dashboard" || a.displayMode === "both",
+    );
+  }, [data?.announcements]);
+
+  if (isLoading || dashboardAnnouncements.length === 0) {
+    return <></>;
+  }
+
+  return (
+    <section className="animate-in fade-in duration-300">
+      <div className="flex items-center gap-2 mb-3">
+        <Megaphone className="w-4 h-4 text-muted-foreground" />
+        <h3 className="text-sm font-medium text-muted-foreground">
+          Announcements
+        </h3>
+      </div>
+      <div className="space-y-2">
+        {dashboardAnnouncements.map((announcement) => (
+          <AnnouncementCard
+            key={announcement.id}
+            announcement={announcement}
+          />
+        ))}
+      </div>
+    </section>
+  );
+};

package/src/index.tsx

@@ -0,0 +1,42 @@
+import {
+  createFrontendPlugin,
+  createSlotExtension,
+  UserMenuItemsSlot,
+  DashboardSlot,
+} from "@checkstack/frontend-api";
+import {
+  announcementRoutes,
+  pluginMetadata,
+  announcementAccess,
+} from "@checkstack/announcement-common";
+import { AnnouncementManagePage } from "./pages/AnnouncementManagePage";
+import { AnnouncementMenuItems } from "./components/AnnouncementMenuItems";
+import { DashboardAnnouncements } from "./components/DashboardAnnouncements";
+
+export default createFrontendPlugin({
+  metadata: pluginMetadata,
+  routes: [
+    {
+      route: announcementRoutes.routes.manage,
+      element: <AnnouncementManagePage />,
+      title: "Manage Announcements",
+      accessRule: announcementAccess.manage,
+    },
+  ],
+  apis: [],
+  extensions: [
+    createSlotExtension(UserMenuItemsSlot, {
+      id: "announcement.user-menu.items",
+      component: AnnouncementMenuItems,
+    }),
+    {
+      id: "announcement.dashboard.cards",
+      slot: DashboardSlot,
+      component:
+        DashboardAnnouncements as React.ComponentType<unknown>,
+    },
+  ],
+});
+
+// Re-export components for direct use in App.tsx
+export { AnnouncementBanner } from "./components/AnnouncementBanner";

package/src/pages/AnnouncementManagePage.tsx

@@ -0,0 +1,618 @@
+import React, { useState } from "react";
+import {
+  usePluginClient,
+  accessApiRef,
+  useApi,
+  wrapInSuspense,
+} from "@checkstack/frontend-api";
+import {
+  AnnouncementApi,
+  announcementAccess,
+  type Announcement,
+  type AnnouncementSeverity,
+  type AnnouncementVisibility,
+  type AnnouncementDisplayMode,
+} from "@checkstack/announcement-common";
+import {
+  PageLayout,
+  Card,
+  CardHeader,
+  CardTitle,
+  CardContent,
+  Button,
+  Badge,
+  LoadingSpinner,
+  EmptyState,
+  Table,
+  TableHeader,
+  TableRow,
+  TableHead,
+  TableBody,
+  TableCell,
+  Select,
+  SelectTrigger,
+  SelectValue,
+  SelectContent,
+  SelectItem,
+  useToast,
+  ConfirmationModal,
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogFooter,
+  Input,
+  Label,
+  Textarea,
+} from "@checkstack/ui";
+import {
+  Plus,
+  Megaphone,
+  Trash2,
+  Edit2,
+  Clock,
+  Eye,
+  EyeOff,
+  Monitor,
+  LayoutDashboard,
+  Columns,
+} from "lucide-react";
+import { formatDistanceToNow, format } from "date-fns";
+
+// ---------------------------------------------------------------------------
+// Editor Dialog
+// ---------------------------------------------------------------------------
+
+interface AnnouncementEditorProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  announcement?: Announcement;
+  onSave: () => void;
+}
+
+const AnnouncementEditor: React.FC<AnnouncementEditorProps> = ({
+  open,
+  onOpenChange,
+  announcement,
+  onSave,
+}) => {
+  const announcementClient = usePluginClient(AnnouncementApi);
+  const toast = useToast();
+  const isEdit = !!announcement;
+
+  const [title, setTitle] = useState(announcement?.title ?? "");
+  const [message, setMessage] = useState(announcement?.message ?? "");
+  const [severity, setSeverity] = useState<AnnouncementSeverity>(
+    announcement?.severity ?? "info",
+  );
+  const [visibility, setVisibility] = useState<AnnouncementVisibility>(
+    announcement?.visibility ?? "all",
+  );
+  const [displayMode, setDisplayMode] = useState<AnnouncementDisplayMode>(
+    announcement?.displayMode ?? "both",
+  );
+  const [active, setActive] = useState(announcement?.active ?? true);
+  const [startsAt, setStartsAt] = useState(
+    announcement?.startsAt
+      ? format(new Date(announcement.startsAt), "yyyy-MM-dd'T'HH:mm")
+      : "",
+  );
+  const [expiresAt, setExpiresAt] = useState(
+    announcement?.expiresAt
+      ? format(new Date(announcement.expiresAt), "yyyy-MM-dd'T'HH:mm")
+      : "",
+  );
+
+  // Reset form when dialog opens with new data
+  React.useEffect(() => {
+    if (open) {
+      setTitle(announcement?.title ?? "");
+      setMessage(announcement?.message ?? "");
+      setSeverity(announcement?.severity ?? "info");
+      setVisibility(announcement?.visibility ?? "all");
+      setDisplayMode(announcement?.displayMode ?? "both");
+      setActive(announcement?.active ?? true);
+      setStartsAt(
+        announcement?.startsAt
+          ? format(new Date(announcement.startsAt), "yyyy-MM-dd'T'HH:mm")
+          : "",
+      );
+      setExpiresAt(
+        announcement?.expiresAt
+          ? format(new Date(announcement.expiresAt), "yyyy-MM-dd'T'HH:mm")
+          : "",
+      );
+    }
+  }, [open, announcement]);
+
+  const createMutation = announcementClient.createAnnouncement.useMutation({
+    onSuccess: () => {
+      toast.success("Announcement created");
+      onOpenChange(false);
+      onSave();
+    },
+    onError: (error) => {
+      toast.error(error instanceof Error ? error.message : "Failed to create");
+    },
+  });
+
+  const updateMutation = announcementClient.updateAnnouncement.useMutation({
+    onSuccess: () => {
+      toast.success("Announcement updated");
+      onOpenChange(false);
+      onSave();
+    },
+    onError: (error) => {
+      toast.error(error instanceof Error ? error.message : "Failed to update");
+    },
+  });
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+
+    const data = {
+      title,
+      message,
+      severity,
+      visibility,
+      displayMode,
+      active,
+      startsAt: startsAt ? new Date(startsAt) : undefined,
+      expiresAt: expiresAt ? new Date(expiresAt) : undefined,
+    };
+
+    if (isEdit && announcement) {
+      updateMutation.mutate({ id: announcement.id, ...data });
+    } else {
+      createMutation.mutate(data);
+    }
+  };
+
+  const isPending = createMutation.isPending || updateMutation.isPending;
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent size="lg">
+        <DialogHeader>
+          <DialogTitle>
+            {isEdit ? "Edit Announcement" : "Create Announcement"}
+          </DialogTitle>
+          <DialogDescription>
+            {isEdit
+              ? "Update the announcement details below."
+              : "Create a new announcement to display in the portal."}
+          </DialogDescription>
+        </DialogHeader>
+
+        <form onSubmit={handleSubmit} className="space-y-4">
+          {/* Title */}
+          <div className="space-y-2">
+            <Label htmlFor="ann-title">Title</Label>
+            <Input
+              id="ann-title"
+              value={title}
+              onChange={(e) => setTitle(e.target.value)}
+              placeholder="Announcement title"
+              required
+            />
+          </div>
+
+          {/* Message (Markdown) */}
+          <div className="space-y-2">
+            <Label htmlFor="ann-message">Message (Markdown)</Label>
+            <Textarea
+              id="ann-message"
+              value={message}
+              onChange={(e) => setMessage(e.target.value)}
+              placeholder="Write your announcement message in Markdown..."
+              rows={6}
+              required
+            />
+          </div>
+
+          {/* Severity + Visibility + Display Mode row */}
+          <div className="grid grid-cols-3 gap-4">
+            <div className="space-y-2">
+              <Label>Severity</Label>
+              <Select
+                value={severity}
+                onValueChange={(v) => setSeverity(v as AnnouncementSeverity)}
+              >
+                <SelectTrigger>
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="info">Info</SelectItem>
+                  <SelectItem value="warning">Warning</SelectItem>
+                  <SelectItem value="critical">Critical</SelectItem>
+                </SelectContent>
+              </Select>
+            </div>
+
+            <div className="space-y-2">
+              <Label>Visibility</Label>
+              <Select
+                value={visibility}
+                onValueChange={(v) =>
+                  setVisibility(v as AnnouncementVisibility)
+                }
+              >
+                <SelectTrigger>
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="all">Everyone</SelectItem>
+                  <SelectItem value="authenticated">
+                    Authenticated Only
+                  </SelectItem>
+                </SelectContent>
+              </Select>
+            </div>
+
+            <div className="space-y-2">
+              <Label>Display Mode</Label>
+              <Select
+                value={displayMode}
+                onValueChange={(v) =>
+                  setDisplayMode(v as AnnouncementDisplayMode)
+                }
+              >
+                <SelectTrigger>
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="banner">Banner Only</SelectItem>
+                  <SelectItem value="dashboard">Dashboard Only</SelectItem>
+                  <SelectItem value="both">Both</SelectItem>
+                </SelectContent>
+              </Select>
+            </div>
+          </div>
+
+          {/* Active toggle + date scheduling */}
+          <div className="grid grid-cols-3 gap-4">
+            <div className="space-y-2">
+              <Label>Status</Label>
+              <Select
+                value={active ? "active" : "inactive"}
+                onValueChange={(v) => setActive(v === "active")}
+              >
+                <SelectTrigger>
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="active">Active</SelectItem>
+                  <SelectItem value="inactive">Inactive</SelectItem>
+                </SelectContent>
+              </Select>
+            </div>
+
+            <div className="space-y-2">
+              <Label htmlFor="ann-starts">Starts At (optional)</Label>
+              <Input
+                id="ann-starts"
+                type="datetime-local"
+                value={startsAt}
+                onChange={(e) => setStartsAt(e.target.value)}
+              />
+            </div>
+
+            <div className="space-y-2">
+              <Label htmlFor="ann-expires">Expires At (optional)</Label>
+              <Input
+                id="ann-expires"
+                type="datetime-local"
+                value={expiresAt}
+                onChange={(e) => setExpiresAt(e.target.value)}
+              />
+            </div>
+          </div>
+
+          <DialogFooter>
+            <Button
+              type="button"
+              variant="outline"
+              onClick={() => onOpenChange(false)}
+            >
+              Cancel
+            </Button>
+            <Button type="submit" disabled={isPending}>
+              {isPending
+                ? "Saving..."
+                : isEdit
+                  ? "Update"
+                  : "Create"}
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Status computation
+// ---------------------------------------------------------------------------
+
+function getAnnouncementStatus(
+  announcement: Announcement,
+): "active" | "scheduled" | "expired" | "inactive" {
+  if (!announcement.active) return "inactive";
+
+  const now = new Date();
+
+  if (announcement.startsAt && new Date(announcement.startsAt) > now) {
+    return "scheduled";
+  }
+
+  if (announcement.expiresAt && new Date(announcement.expiresAt) <= now) {
+    return "expired";
+  }
+
+  return "active";
+}
+
+function StatusBadge({ announcement }: { announcement: Announcement }) {
+  const status = getAnnouncementStatus(announcement);
+
+  switch (status) {
+    case "active": {
+      return <Badge variant="success">Active</Badge>;
+    }
+    case "scheduled": {
+      return <Badge variant="info">Scheduled</Badge>;
+    }
+    case "expired": {
+      return <Badge variant="secondary">Expired</Badge>;
+    }
+    case "inactive": {
+      return <Badge variant="secondary">Inactive</Badge>;
+    }
+  }
+}
+
+function SeverityBadge({ severity }: { severity: AnnouncementSeverity }) {
+  switch (severity) {
+    case "critical": {
+      return <Badge variant="destructive">Critical</Badge>;
+    }
+    case "warning": {
+      return <Badge variant="warning">Warning</Badge>;
+    }
+    default: {
+      return <Badge variant="info">Info</Badge>;
+    }
+  }
+}
+
+function DisplayModeIcon({ mode }: { mode: AnnouncementDisplayMode }) {
+  switch (mode) {
+    case "banner": {
+      return (
+        <span title="Banner">
+          <Monitor className="h-4 w-4 text-muted-foreground" />
+        </span>
+      );
+    }
+    case "dashboard": {
+      return (
+        <span title="Dashboard">
+          <LayoutDashboard className="h-4 w-4 text-muted-foreground" />
+        </span>
+      );
+    }
+    case "both": {
+      return (
+        <span title="Both">
+          <Columns className="h-4 w-4 text-muted-foreground" />
+        </span>
+      );
+    }
+  }
+}
+
+function VisibilityIcon({
+  visibility,
+}: {
+  visibility: AnnouncementVisibility;
+}) {
+  switch (visibility) {
+    case "all": {
+      return (
+        <span title="Everyone">
+          <Eye className="h-4 w-4 text-muted-foreground" />
+        </span>
+      );
+    }
+    case "authenticated": {
+      return (
+        <span title="Authenticated only">
+          <EyeOff className="h-4 w-4 text-muted-foreground" />
+        </span>
+      );
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main Page
+// ---------------------------------------------------------------------------
+
+const AnnouncementManageContent: React.FC = () => {
+  const announcementClient = usePluginClient(AnnouncementApi);
+  const accessApi = useApi(accessApiRef);
+  const toast = useToast();
+
+  const { allowed: canManage, loading: accessLoading } = accessApi.useAccess(
+    announcementAccess.manage,
+  );
+
+  const [editorOpen, setEditorOpen] = useState(false);
+  const [editingAnnouncement, setEditingAnnouncement] = useState<
+    Announcement | undefined
+  >();
+  const [deleteId, setDeleteId] = useState<string | undefined>();
+
+  const {
+    data: announcementsData,
+    isLoading,
+    refetch,
+  } = announcementClient.listAllAnnouncements.useQuery();
+
+  const deleteMutation = announcementClient.deleteAnnouncement.useMutation({
+    onSuccess: () => {
+      toast.success("Announcement deleted");
+      void refetch();
+      setDeleteId(undefined);
+    },
+    onError: (error) => {
+      toast.error(error instanceof Error ? error.message : "Failed to delete");
+    },
+  });
+
+  const announcements = announcementsData?.announcements ?? [];
+
+  const handleCreate = () => {
+    setEditingAnnouncement(undefined);
+    setEditorOpen(true);
+  };
+
+  const handleEdit = (a: Announcement) => {
+    setEditingAnnouncement(a);
+    setEditorOpen(true);
+  };
+
+  const handleDelete = () => {
+    if (!deleteId) return;
+    deleteMutation.mutate({ id: deleteId });
+  };
+
+  const handleSave = () => {
+    void refetch();
+  };
+
+  return (
+    <PageLayout
+      title="Announcement Management"
+      subtitle="Create and manage portal announcements for your users"
+      icon={Megaphone}
+      loading={accessLoading}
+      allowed={canManage}
+      actions={
+        <Button onClick={handleCreate}>
+          <Plus className="h-4 w-4 mr-2" />
+          New Announcement
+        </Button>
+      }
+    >
+      <Card>
+        <CardHeader className="border-b border-border">
+          <div className="flex items-center gap-2">
+            <Megaphone className="h-5 w-5 text-muted-foreground" />
+            <CardTitle>Announcements</CardTitle>
+          </div>
+        </CardHeader>
+        <CardContent className="p-0">
+          {isLoading ? (
+            <div className="p-12 flex justify-center">
+              <LoadingSpinner />
+            </div>
+          ) : announcements.length === 0 ? (
+            <EmptyState
+              title="No announcements yet"
+              description="Create your first announcement to inform users about important updates."
+            />
+          ) : (
+            <Table>
+              <TableHeader>
+                <TableRow>
+                  <TableHead>Title</TableHead>
+                  <TableHead>Severity</TableHead>
+                  <TableHead>Status</TableHead>
+                  <TableHead>Display</TableHead>
+                  <TableHead>Visibility</TableHead>
+                  <TableHead>Created</TableHead>
+                  <TableHead className="w-24">Actions</TableHead>
+                </TableRow>
+              </TableHeader>
+              <TableBody>
+                {announcements.map((a) => (
+                  <TableRow key={a.id}>
+                    <TableCell>
+                      <p className="font-medium truncate max-w-xs">
+                        {a.title}
+                      </p>
+                    </TableCell>
+                    <TableCell>
+                      <SeverityBadge severity={a.severity} />
+                    </TableCell>
+                    <TableCell>
+                      <StatusBadge announcement={a} />
+                    </TableCell>
+                    <TableCell>
+                      <DisplayModeIcon mode={a.displayMode} />
+                    </TableCell>
+                    <TableCell>
+                      <VisibilityIcon visibility={a.visibility} />
+                    </TableCell>
+                    <TableCell>
+                      <div className="flex items-center gap-1 text-sm text-muted-foreground">
+                        <Clock className="h-3 w-3" />
+                        <span>
+                          {formatDistanceToNow(new Date(a.createdAt), {
+                            addSuffix: true,
+                          })}
+                        </span>
+                      </div>
+                    </TableCell>
+                    <TableCell>
+                      <div className="flex gap-1">
+                        <Button
+                          variant="ghost"
+                          size="sm"
+                          onClick={() => handleEdit(a)}
+                        >
+                          <Edit2 className="h-4 w-4" />
+                        </Button>
+                        <Button
+                          variant="ghost"
+                          size="sm"
+                          onClick={() => setDeleteId(a.id)}
+                        >
+                          <Trash2 className="h-4 w-4 text-destructive" />
+                        </Button>
+                      </div>
+                    </TableCell>
+                  </TableRow>
+                ))}
+              </TableBody>
+            </Table>
+          )}
+        </CardContent>
+      </Card>
+
+      <AnnouncementEditor
+        open={editorOpen}
+        onOpenChange={setEditorOpen}
+        announcement={editingAnnouncement}
+        onSave={handleSave}
+      />
+
+      <ConfirmationModal
+        isOpen={!!deleteId}
+        onClose={() => setDeleteId(undefined)}
+        title="Delete Announcement"
+        message="Are you sure you want to delete this announcement? This action cannot be undone."
+        confirmText="Delete"
+        variant="danger"
+        onConfirm={handleDelete}
+        isLoading={deleteMutation.isPending}
+      />
+    </PageLayout>
+  );
+};
+
+export const AnnouncementManagePage = wrapInSuspense(
+  AnnouncementManageContent,
+);

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/frontend.json",
+  "include": [
+    "src"
+  ]
+}