Add integrations page (#9155)

* update useSettings * Integration page skeleton * add descriptions * update design * Integration page style update * clean up * update integration card Co-authored-by: Tom Moor <tom.moor@gmail.com> * Update integration icon size Co-authored-by: Tom Moor <tom.moor@gmail.com> * Update all integrations menu item * update IntegrationCard to use the `Text` component * update card status * fix: Google analytics never shows as installed fix: Styling tweaks Move webhooks out of integrations * Add breadcrumbs * Add filtering * refactor * Add hover state, tweak descriptions --------- Co-authored-by: Tess99854 <tesnimesb@gmail.com> Co-authored-by: Mahmoud Mohammed Ali <ibn.el4ai5@gmail.com> Co-authored-by: Mahmoud Ali <mahmoud.ali.khallaf@gmail.com>
2025-12-17 16:54:31 -06:00 · 2025-05-10 09:59:41 -04:00
parent fd984774d0
commit d0bd2baa9f
20 changed files with 255 additions and 21 deletions
--- a/app/components/Sidebar/Settings.tsx
+++ b/app/components/Sidebar/Settings.tsx
@@ -27,7 +27,12 @@ function SettingsSidebar() {
  const { t } = useTranslation();
  const history = useHistory();
  const location = useLocation();
-  const configs = useSettingsConfig();
+  let configs = useSettingsConfig();
+
+  configs = configs.filter((item) =>
+    "isActive" in item ? item.isActive : true
+  );
+
  const groupedConfig = groupBy(configs, "group");

  const returnToApp = React.useCallback(() => {
@@ -65,7 +70,7 @@ function SettingsSidebar() {
                    to={item.path}
                    onClickIntent={item.preload}
                    active={
-                      item.path !== settingsPath()
+                      item.path.startsWith(settingsPath("templates"))
                        ? location.pathname.startsWith(item.path)
                        : undefined
                    }
--- a/app/hooks/useSettingsConfig.ts
+++ b/app/hooks/useSettingsConfig.ts
@@ -13,11 +13,13 @@ import {
  ImportIcon,
  ShapesIcon,
  Icon,
+  PlusIcon,
  InternetIcon,
 } from "outline-icons";
 import React, { ComponentProps } from "react";
 import { useTranslation } from "react-i18next";
 import { integrationSettingsPath } from "@shared/utils/routeHelpers";
+import { Integrations } from "~/scenes/Settings/Integrations";
 import ZapierIcon from "~/components/Icons/ZapierIcon";
 import { createLazyComponent as lazy } from "~/components/LazyLoad";
 import { Hook, PluginManager } from "~/utils/PluginManager";
@@ -27,6 +29,7 @@ import { useComputed } from "./useComputed";
 import useCurrentTeam from "./useCurrentTeam";
 import useCurrentUser from "./useCurrentUser";
 import usePolicy from "./usePolicy";
+import useStores from "./useStores";

 const ApiKeys = lazy(() => import("~/scenes/Settings/ApiKeys"));
 const Applications = lazy(() => import("~/scenes/Settings/Applications"));
@@ -50,17 +53,24 @@ export type ConfigItem = {
  path: string;
  icon: React.FC<ComponentProps<typeof Icon>>;
  component: React.ComponentType;
+  description?: string;
  preload?: () => void;
  enabled: boolean;
  group: string;
+  isActive?: boolean;
 };

 const useSettingsConfig = () => {
+  const { integrations } = useStores();
  const user = useCurrentUser();
  const team = useCurrentTeam();
  const can = usePolicy(team);
  const { t } = useTranslation();

+  React.useEffect(() => {
+    void integrations.fetchAll();
+  }, [integrations]);
+
  const config = useComputed(() => {
    const items: ConfigItem[] = [
      // Account
@@ -210,6 +220,14 @@ const useSettingsConfig = () => {
        group: t("Integrations"),
        icon: ZapierIcon,
      },
+      {
+        name: `${t("Install")}…`,
+        path: settingsPath("integrations"),
+        component: Integrations,
+        enabled: true,
+        group: t("Integrations"),
+        icon: PlusIcon,
+      },
    ];

    // Plugins
@@ -225,12 +243,17 @@ const useSettingsConfig = () => {
            ? integrationSettingsPath(plugin.id)
            : settingsPath(plugin.id),
        group: t(group),
+        description: plugin.value.description,
        component: plugin.value.component.Component,
        preload: plugin.value.component.preload,
        enabled: plugin.value.enabled
          ? plugin.value.enabled(team, user)
          : can.update,
        icon: plugin.value.icon,
+        isActive: integrations.orderedData.some(
+          (integration) =>
+            integration.service.toLowerCase() === plugin.id.toLowerCase()
+        ),
      } as ConfigItem);
    });

--- a/app/scenes/Settings/Integrations.tsx
+++ b/app/scenes/Settings/Integrations.tsx
@@ -0,0 +1,62 @@
+import * as React from "react";
+import { Trans, useTranslation } from "react-i18next";
+import styled from "styled-components";
+import Flex from "@shared/components/Flex";
+import Heading from "~/components/Heading";
+import InputSearch from "~/components/InputSearch";
+import Scene from "~/components/Scene";
+import Text from "~/components/Text";
+import useSettingsConfig from "~/hooks/useSettingsConfig";
+import { settingsPath } from "~/utils/routeHelpers";
+import IntegrationCard from "./components/IntegrationCard";
+import { StickyFilters } from "./components/StickyFilters";
+
+export function Integrations() {
+  const { t } = useTranslation();
+  let items = useSettingsConfig();
+  const [query, setQuery] = React.useState("");
+
+  const handleQuery = (event: React.ChangeEvent<HTMLInputElement>) => {
+    setQuery(event.target.value);
+  };
+
+  items = items
+    .filter(
+      (item) =>
+        item.group === "Integrations" &&
+        item.enabled &&
+        item.path !== settingsPath("integrations") &&
+        item.name.toLowerCase().includes(query.toLowerCase())
+    )
+    .sort((item) => (item.isActive ? -1 : 1));
+
+  return (
+    <Scene title={t("Integrations")}>
+      <Heading>{t("Integrations")}</Heading>
+      <Text as="p" type="secondary">
+        <Trans>
+          Configure a variety of integrations with third-party services.
+        </Trans>
+      </Text>
+      <StickyFilters gap={8}>
+        <InputSearch
+          short
+          value={query}
+          placeholder={`${t("Filter")}…`}
+          onChange={handleQuery}
+        />
+      </StickyFilters>
+
+      <CardsFlex gap={30} wrap>
+        {items.map((item) => (
+          <IntegrationCard key={item.path} integration={item} />
+        ))}
+      </CardsFlex>
+    </Scene>
+  );
+}
+
+const CardsFlex = styled(Flex)`
+  margin-top: 20px;
+  width: "100%";
+`;
--- a/app/scenes/Settings/components/IntegrationCard.tsx
+++ b/app/scenes/Settings/components/IntegrationCard.tsx
@@ -0,0 +1,91 @@
+import * as React from "react";
+import { useTranslation } from "react-i18next";
+import { Link } from "react-router-dom";
+import styled from "styled-components";
+import { s, ellipsis } from "@shared/styles";
+import { ConfigItem } from "~/hooks/useSettingsConfig";
+import Button from "../../../components/Button";
+import Flex from "../../../components/Flex";
+import Text from "../../../components/Text";
+
+type Props = {
+  integration: ConfigItem;
+};
+
+function IntegrationCard({ integration }: Props) {
+  const { t } = useTranslation();
+  return (
+    <Card as={Link} to={integration.path}>
+      <Flex align="center" gap={8}>
+        <integration.icon size={48} />
+        <Flex auto column>
+          <Name>{integration.name}</Name>
+          {integration.isActive && <Status>{t("Connected")}</Status>}
+        </Flex>
+        <Button as={Link} to={integration.path} neutral>
+          {integration.isActive ? t("Configure") : t("Connect")}
+        </Button>
+      </Flex>
+
+      <Description>{integration.description}</Description>
+    </Card>
+  );
+}
+
+export default IntegrationCard;
+
+const Card = styled.div`
+  display: flex;
+  flex-direction: column;
+  flex-grow: 1;
+  padding: 20px;
+  width: 300px;
+  background: ${s("background")};
+  border: 1px solid ${s("inputBorder")};
+  color: ${s("text")};
+  border-radius: 8px;
+  transition: box-shadow 200ms ease;
+  cursor: var(--pointer);
+
+  &:hover {
+    box-shadow: rgba(0, 0, 0, 0.08) 0px 2px 4px, rgba(0, 0, 0, 0.06) 0px 4px 8px;
+  }
+`;
+
+const Name = styled(Text)`
+  margin: 0;
+  font-size: 16px;
+  font-weight: 600;
+  color: ${s("text")};
+  ${ellipsis()}
+`;
+
+const Description = styled(Text)`
+  margin: 8px 0 0;
+  font-size: 15px;
+  max-width: 100%;
+  color: ${s("textTertiary")};
+`;
+
+const Status = styled(Text).attrs({
+  type: "secondary",
+  size: "small",
+  as: "span",
+})`
+  display: inline-flex;
+  align-items: center;
+
+  &::after {
+    content: "";
+    display: inline-block;
+    width: 17px;
+    height: 17px;
+
+    background: radial-gradient(
+      circle at center,
+      ${s("accent")} 0 33%,
+      transparent 33%
+    );
+    border-radius: 50%;
+  }
+`;
--- a/app/scenes/Settings/components/IntegrationScene.tsx
+++ b/app/scenes/Settings/components/IntegrationScene.tsx
@@ -0,0 +1,33 @@
+import { SettingsIcon } from "outline-icons";
+import * as React from "react";
+import { useTranslation } from "react-i18next";
+import Breadcrumb from "~/components/Breadcrumb";
+import Scene from "~/components/Scene";
+import { settingsPath } from "~/utils/routeHelpers";
+
+export function IntegrationScene({
+  children,
+  ...rest
+}: React.ComponentProps<typeof Scene>) {
+  const { t } = useTranslation();
+
+  return (
+    <Scene
+      left={
+        <Breadcrumb
+          items={[
+            {
+              type: "route",
+              title: t("Integrations"),
+              icon: <SettingsIcon />,
+              to: settingsPath("integrations"),
+            },
+          ]}
+        />
+      }
+      {...rest}
+    >
+      {children}
+    </Scene>
+  );
+}
--- a/app/utils/PluginManager.ts
+++ b/app/utils/PluginManager.ts
@@ -28,8 +28,10 @@ type PluginValueMap = {
    after?: string;
    /** The displayed icon of the plugin. */
    icon: React.ElementType;
-    /** The settings screen somponent, should be lazy loaded. */
+    /** The lazy loaded settings screen component. */
    component: LazyComponent<React.ComponentType>;
+    /** The description that will show on the plugins card. */
+    description?: string;
    /** Whether the plugin is enabled in the current context. */
    enabled?: (team: Team, user: User) => boolean;
  };
--- a/plugins/github/client/Settings.tsx
+++ b/plugins/github/client/Settings.tsx
@@ -4,6 +4,7 @@ import * as React from "react";
 import { useTranslation, Trans } from "react-i18next";
 import { IntegrationService } from "@shared/types";
 import { ConnectedButton } from "~/scenes/Settings/components/ConnectedButton";
+import { IntegrationScene } from "~/scenes/Settings/components/IntegrationScene";
 import { AvatarSize } from "~/components/Avatar";
 import Flex from "~/components/Flex";
 import Heading from "~/components/Heading";
@@ -11,7 +12,6 @@ import List from "~/components/List";
 import ListItem from "~/components/List/Item";
 import Notice from "~/components/Notice";
 import PlaceholderText from "~/components/PlaceholderText";
-import Scene from "~/components/Scene";
 import TeamLogo from "~/components/TeamLogo";
 import Text from "~/components/Text";
 import Time from "~/components/Time";
@@ -38,7 +38,7 @@ function GitHub() {
  }, [integrations]);

  return (
-    <Scene title="GitHub" icon={<GitHubIcon />}>
+    <IntegrationScene title="GitHub" icon={<GitHubIcon />}>
      <Heading>GitHub</Heading>

      {error === "access_denied" && (
@@ -146,7 +146,7 @@ function GitHub() {
          </Trans>
        </Notice>
      )}
-    </Scene>
+    </IntegrationScene>
  );
 }

--- a/plugins/github/client/index.tsx
+++ b/plugins/github/client/index.tsx
@@ -10,6 +10,8 @@ PluginManager.add([
    value: {
      group: "Integrations",
      icon: Icon,
+      description:
+        "Connect your GitHub account to Outline to enable rich, realtime, issue and pull request previews inside documents.",
      component: createLazyComponent(() => import("./Settings")),
    },
  },
--- a/plugins/googleanalytics/client/Settings.tsx
+++ b/plugins/googleanalytics/client/Settings.tsx
@@ -6,12 +6,12 @@ import { useTranslation, Trans } from "react-i18next";
 import { toast } from "sonner";
 import { IntegrationType, IntegrationService } from "@shared/types";
 import Integration from "~/models/Integration";
+import { IntegrationScene } from "~/scenes/Settings/components/IntegrationScene";
 import SettingRow from "~/scenes/Settings/components/SettingRow";
 import Button from "~/components/Button";
 import Heading from "~/components/Heading";
 import GoogleIcon from "~/components/Icons/GoogleIcon";
 import Input from "~/components/Input";
-import Scene from "~/components/Scene";
 import Text from "~/components/Text";
 import useStores from "~/hooks/useStores";

@@ -75,7 +75,7 @@ function GoogleAnalytics() {
  );

  return (
-    <Scene title={t("Google Analytics")} icon={<GoogleIcon />}>
+    <IntegrationScene title={t("Google Analytics")} icon={<GoogleIcon />}>
      <Heading>{t("Google Analytics")}</Heading>

      <Text as="p" type="secondary">
@@ -100,7 +100,7 @@ function GoogleAnalytics() {
          {formState.isSubmitting ? `${t("Saving")}…` : t("Save")}
        </Button>
      </form>
-    </Scene>
+    </IntegrationScene>
  );
 }

--- a/plugins/googleanalytics/client/index.tsx
+++ b/plugins/googleanalytics/client/index.tsx
@@ -10,6 +10,8 @@ PluginManager.add([
    value: {
      group: "Integrations",
      icon: Icon,
+      description:
+        "Measure adoption and engagement by sending view and event analytics directly to your GA4 dashboard.",
      component: createLazyComponent(() => import("./Settings")),
    },
  },
--- a/plugins/googleanalytics/plugin.json
+++ b/plugins/googleanalytics/plugin.json
@@ -1,5 +1,5 @@
 {
-  "id": "googleanalytics",
+  "id": "google-analytics",
  "name": "Google Analytics",
  "priority": 30,
  "description": "Adds support for reporting analytics to a Google."
--- a/plugins/linear/client/index.tsx
+++ b/plugins/linear/client/index.tsx
@@ -10,6 +10,8 @@ PluginManager.add([
    value: {
      group: "Integrations",
      icon: Icon,
+      description:
+        "Connect your Linear account to Outline to enable rich, realtime, issue previews inside documents.",
      component: createLazyComponent(() => import("./Settings")),
    },
  },
--- a/plugins/matomo/client/Settings.tsx
+++ b/plugins/matomo/client/Settings.tsx
@@ -6,11 +6,11 @@ import { useTranslation, Trans } from "react-i18next";
 import { toast } from "sonner";
 import { IntegrationType, IntegrationService } from "@shared/types";
 import Integration from "~/models/Integration";
+import { IntegrationScene } from "~/scenes/Settings/components/IntegrationScene";
 import SettingRow from "~/scenes/Settings/components/SettingRow";
 import Button from "~/components/Button";
 import Heading from "~/components/Heading";
 import Input from "~/components/Input";
-import Scene from "~/components/Scene";
 import Text from "~/components/Text";
 import useStores from "~/hooks/useStores";
 import Icon from "./Icon";
@@ -82,7 +82,7 @@ function Matomo() {
  );

  return (
-    <Scene title="Matomo" icon={<Icon />}>
+    <IntegrationScene title="Matomo" icon={<Icon />}>
      <Heading>Matomo</Heading>

      <Text as="p" type="secondary">
@@ -121,7 +121,7 @@ function Matomo() {
          {formState.isSubmitting ? `${t("Saving")}…` : t("Save")}
        </Button>
      </form>
-    </Scene>
+    </IntegrationScene>
  );
 }

--- a/plugins/matomo/client/index.tsx
+++ b/plugins/matomo/client/index.tsx
@@ -11,6 +11,8 @@ PluginManager.add([
    value: {
      group: "Integrations",
      icon: Icon,
+      description:
+        "Track your docs with a self-hosted, open-source analytics platform, link Outline to Matomo for 100% data ownership, GDPR compliance, and deep usage insights on your own servers.",
      component: createLazyComponent(() => import("./Settings")),
      enabled: (_, user) => user.role === UserRole.Admin,
    },
--- a/plugins/slack/client/Settings.tsx
+++ b/plugins/slack/client/Settings.tsx
@@ -6,6 +6,7 @@ import { IntegrationService, IntegrationType } from "@shared/types";
 import Collection from "~/models/Collection";
 import Integration from "~/models/Integration";
 import { ConnectedButton } from "~/scenes/Settings/components/ConnectedButton";
+import { IntegrationScene } from "~/scenes/Settings/components/IntegrationScene";
 import SettingRow from "~/scenes/Settings/components/SettingRow";
 import Flex from "~/components/Flex";
 import Heading from "~/components/Heading";
@@ -13,7 +14,6 @@ import CollectionIcon from "~/components/Icons/CollectionIcon";
 import List from "~/components/List";
 import ListItem from "~/components/List/Item";
 import Notice from "~/components/Notice";
-import Scene from "~/components/Scene";
 import Text from "~/components/Text";
 import env from "~/env";
 import useCurrentTeam from "~/hooks/useCurrentTeam";
@@ -67,7 +67,7 @@ function Slack() {
  const appName = env.APP_NAME;

  return (
-    <Scene title="Slack" icon={<SlackIcon />}>
+    <IntegrationScene title="Slack" icon={<SlackIcon />}>
      <Heading>Slack</Heading>

      {error === "access_denied" && (
@@ -205,7 +205,7 @@ function Slack() {
          </List>
        </>
      )}
-    </Scene>
+    </IntegrationScene>
  );
 }

--- a/plugins/slack/client/index.tsx
+++ b/plugins/slack/client/index.tsx
@@ -11,6 +11,8 @@ PluginManager.add([
    value: {
      group: "Integrations",
      icon: Icon,
+      description:
+        "Search your knowledge base directly in Slack, get /outline search, rich link previews, and notifications on new or updated docs.",
      component: createLazyComponent(() => import("./Settings")),
      enabled: (_, user) =>
        [UserRole.Member, UserRole.Admin].includes(user.role),
--- a/plugins/umami/client/Settings.tsx
+++ b/plugins/umami/client/Settings.tsx
@@ -6,11 +6,11 @@ import { useTranslation, Trans } from "react-i18next";
 import { toast } from "sonner";
 import { IntegrationType, IntegrationService } from "@shared/types";
 import Integration from "~/models/Integration";
+import { IntegrationScene } from "~/scenes/Settings/components/IntegrationScene";
 import SettingRow from "~/scenes/Settings/components/SettingRow";
 import Button from "~/components/Button";
 import Heading from "~/components/Heading";
 import Input from "~/components/Input";
-import Scene from "~/components/Scene";
 import Text from "~/components/Text";
 import useStores from "~/hooks/useStores";
 import Icon from "./Icon";
@@ -85,7 +85,7 @@ function Umami() {
  );

  return (
-    <Scene title="Umami" icon={<Icon />}>
+    <IntegrationScene title="Umami" icon={<Icon />}>
      <Heading>Umami</Heading>

      <Text as="p" type="secondary">
@@ -145,7 +145,7 @@ function Umami() {
          {formState.isSubmitting ? `${t("Saving")}…` : t("Save")}
        </Button>
      </form>
-    </Scene>
+    </IntegrationScene>
  );
 }

--- a/plugins/umami/client/index.tsx
+++ b/plugins/umami/client/index.tsx
@@ -11,6 +11,8 @@ PluginManager.add([
    value: {
      group: "Integrations",
      icon: Icon,
+      description:
+        "Gain privacy-first insights into how your team consumes docs, inject your self-hosted Umami script across Outline pages to track views and engagement while retaining full control of your data.",
      component: createLazyComponent(() => import("./Settings")),
      enabled: (_, user) => user.role === UserRole.Admin,
    },
--- a/plugins/webhooks/client/index.tsx
+++ b/plugins/webhooks/client/index.tsx
@@ -8,8 +8,11 @@ PluginManager.add([
    ...config,
    type: Hook.Settings,
    value: {
-      group: "Integrations",
+      group: "Workspace",
+      after: "Shared Links",
      icon: Icon,
+      description:
+        "Automate downstream workflows with real-time JSON POSTs, subscribe to events in Outline so external systems can react instantly.",
      component: createLazyComponent(() => import("./Settings")),
    },
  },
--- a/shared/i18n/locales/en_US/translation.json
+++ b/shared/i18n/locales/en_US/translation.json
@@ -529,6 +529,7 @@
  "Shared Links": "Shared Links",
  "Import": "Import",
  "Integrations": "Integrations",
+  "Install": "Install",
  "Revoke token": "Revoke token",
  "Revoke": "Revoke",
  "Show path to document": "Show path to document",
@@ -974,6 +975,8 @@
  "{{ count }} document imported_plural": "{{ count }} documents imported",
  "You can import a zip file that was previously exported from an Outline installation – collections, documents, and images will be imported. In Outline, open <em>Export</em> in the Settings sidebar and click on <em>Export Data</em>.": "You can import a zip file that was previously exported from an Outline installation – collections, documents, and images will be imported. In Outline, open <em>Export</em> in the Settings sidebar and click on <em>Export Data</em>.",
  "Drag and drop the zip file from the Markdown export option in {{appName}}, or click to upload": "Drag and drop the zip file from the Markdown export option in {{appName}}, or click to upload",
+  "Configure": "Configure",
+  "Connect": "Connect",
  "Last active": "Last active",
  "Guest": "Guest",
  "Never used": "Never used",
@@ -1034,6 +1037,7 @@
  "Enterprise": "Enterprise",
  "Quickly transfer your existing documents, pages, and files from other tools and services into {{appName}}. You can also drag and drop any HTML, Markdown, and text documents directly into Collections in the app.": "Quickly transfer your existing documents, pages, and files from other tools and services into {{appName}}. You can also drag and drop any HTML, Markdown, and text documents directly into Collections in the app.",
  "Recent imports": "Recent imports",
+  "Configure a variety of integrations with third-party services.": "Configure a variety of integrations with third-party services.",
  "Could not load members": "Could not load members",
  "Everyone that has signed into {{appName}} is listed here. It’s possible that there are other users who have access through {{signinMethods}} but haven’t signed in yet.": "Everyone that has signed into {{appName}} is listed here. It’s possible that there are other users who have access through {{signinMethods}} but haven’t signed in yet.",
  "Receive a notification whenever a new document is published": "Receive a notification whenever a new document is published",
@@ -1144,7 +1148,6 @@
  "Expires today": "Expires today",
  "Expires tomorrow": "Expires tomorrow",
  "Expires {{ date }}": "Expires {{ date }}",
-  "Connect": "Connect",
  "Whoops, you need to accept the permissions in GitHub to connect {{appName}} to your workspace. Try again?": "Whoops, you need to accept the permissions in GitHub to connect {{appName}} to your workspace. Try again?",
  "Something went wrong while authenticating your request. Please try logging in again.": "Something went wrong while authenticating your request. Please try logging in again.",
  "The owner of GitHub account has been requested to install the {{githubAppName}} GitHub app. Once approved, previews will be shown for respective links.": "The owner of GitHub account has been requested to install the {{githubAppName}} GitHub app. Once approved, previews will be shown for respective links.",