@stackql/docusaurus-plugin-aeo 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.4.1
+
+Cosmetic patch. No API, option-shape, behavior, or placement changes.
+
+### Changed
+
+- Provider icons swapped from [simple-icons](https://simpleicons.org) (monochrome) to [@lobehub/icons](https://github.com/lobehub/lobe-icons) (colored brand variants). Resolves the ChatGPT-fallback-glyph issue from v0.3.0-v0.4.0: Claude, Perplexity, and Gemini now render in their brand colors via lobehub's `.Color` variants, and ChatGPT renders the OpenAI mark tinted with ChatGPT green (lobehub does not ship a `.Color` variant for OpenAI as of 5.10.0, so the monochrome mark is tinted inline).
+- `ListItemIcon` now uses `sx={{ minWidth: 32, color: 'inherit' }}` so MUI's default tint does not override the brand colors.
+
+### Removed
+
+- `simple-icons` dependency.
+
+### Added
+
+- `@lobehub/icons` (`^5.10.0`, MIT) as a runtime dependency.
+
+## 0.4.0
+
+Visual refresh of the Ask AI button (feature 3) to match the look-and-feel of MUI-based dropdown components used elsewhere on consumer sites. No changes to features 1, 2, or 4.
+
+### Changed (breaking)
+
+- `@mui/material`, `@mui/icons-material`, `@emotion/react`, `@emotion/styled` are now required peer dependencies when `askAi.enabled` is `true`. Consumers that already use MUI (common in Docusaurus sites) get a single deduped copy at install time; consumers without MUI will get a clean npm peer-dependency install error pointing at exactly what to install. Consumers who disable the button (`askAi.enabled: false`) can skip these - the theme components are not registered and MUI is never imported.
+
+### Changed
+
+- Ask AI button reimplemented with MUI primitives: outlined `Button` (small, with `KeyboardArrowDownIcon` caret) for the trigger; `Menu` with `MenuItem`s containing `ListItemIcon` (the simple-icons brand SVGs from v0.3.0) and `ListItemText`. Menu is anchored bottom-right of the trigger and opens with transform-origin top-right.
+- Button is hidden on viewports under 997px (matches the Docusaurus mobile breakpoint).
+
+### Removed
+
+- Custom click-outside and Esc-to-close handlers. MUI `Menu` provides both natively. Net reduction in `src/theme/AskAiButton/index.jsx`: ~25 lines.
+- All custom trigger / menu CSS classes. The CSS module is now a 2-rule wrapper that controls only the responsive show/hide; all other styling lives on the MUI `sx` prop.
+
 ## 0.3.0
 
 Focused UX upgrade to the Ask AI button (feature 3). No changes to features 1, 2, or 4.

package/README.md

@@ -170,7 +170,7 @@ Behavior:
 
 ## Feature 3: "Ask AI" button
 
-A solid pill dropdown reading "Ask AI about this page" is injected at the top of every doc and blog-post content area, right-aligned in the breadcrumb row. Each item in the dropdown opens the corresponding AI surface in a new tab with a prefilled prompt that references the current page's `.md` companion.
+An outlined pill button with a caret reading "Ask AI about this page" is injected at the top of every doc and blog-post content area, right-aligned in the breadcrumb row. Each item in the dropdown opens the corresponding AI surface in a new tab with a prefilled prompt that references the current page's `.md` companion. The button is hidden on viewports under 997px to keep the breadcrumb row uncluttered on mobile.
 
 Placement specifics:
 
@@ -194,9 +194,9 @@ Read https://your-site.example/path/to/page.md and help me with the following qu
 
 The trailing space is intentional - the cursor lands ready for the user to type.
 
-Provider icons are real brand SVGs sourced from [simple-icons](https://simpleicons.org). Three of four (Claude, Perplexity, Gemini) come from the upstream catalog directly. OpenAI / ChatGPT was removed from simple-icons in 2024 following a takedown, so the ChatGPT row shows a neutral chat-bubble glyph as a placeholder.
+Provider icons are real brand SVGs in each provider's brand color, sourced from [@lobehub/icons](https://github.com/lobehub/lobe-icons). Claude, Perplexity, and Gemini render via their `.Color` variants directly; OpenAI ships only a monochrome mark, so the ChatGPT row uses that mark tinted with the ChatGPT brand green so it visually pairs with the colored icons.
 
-**Trademark note.** Brand logos are trademarks of their respective owners; their inclusion via simple-icons does not imply endorsement. Consumers using the Ask AI button in commercial contexts should review each provider's brand-usage policy.
+**Trademark note.** Brand logos are trademarks of their respective owners; their inclusion via @lobehub/icons does not imply endorsement. Consumers using the Ask AI button in commercial contexts should review each provider's brand-usage policy.
 
 Options:
 
@@ -207,7 +207,22 @@ Options:
 | `askAi.promptTemplate` | `'Read {pageUrl}.md and help me with the following question about it: '` | Prompt sent to each provider. `{pageUrl}` is the page's canonical URL (no trailing slash). If feature 1 is disabled, the consumer should remove the `.md` from the template. |
 | `askAi.placement` | `'breadcrumb-row'` | `'breadcrumb-row'` puts the button at the top of every doc/blog page (docs breadcrumb row, or above the blog title). `'none'` does not register any theme components - swizzle the button into your preferred location manually. |
 
-Styling uses CSS modules and reads from Docusaurus's theme tokens (`--ifm-color-primary`, `--ifm-color-primary-darker`, `--ifm-color-emphasis-300`, etc.) so dark/light mode work automatically without extra rules.
+The button is built from [MUI](https://mui.com) primitives - outlined `Button` with a `KeyboardArrowDownIcon` caret as the trigger, and a `Menu` of `MenuItem` rows for the providers. Theming reads `--ifm-color-primary` and `--ifm-font-family-base` via MUI's `sx` prop, so dark/light mode work automatically. The MUI `Menu` handles click-outside-to-close and Esc-to-close natively.
+
+### Peer dependencies
+
+When `askAi.enabled` is `true` (the default), the following peer dependencies must be installed by the consumer site:
+
+| Package | Range |
+| --- | --- |
+| `@mui/material` | `^5.0.0 \|\| ^6.0.0 \|\| ^7.0.0` |
+| `@mui/icons-material` | `^5.0.0 \|\| ^6.0.0 \|\| ^7.0.0` |
+| `@emotion/react` | `^11.0.0` |
+| `@emotion/styled` | `^11.0.0` |
+
+These are declared as peer dependencies (not direct dependencies) so consumers that already use MUI - common in Docusaurus sites - get a single deduped copy at install time. Consumers without MUI will get a clean npm peer-dependency error pointing at exactly what to install.
+
+Consumers who disable the Ask AI button (`askAi.enabled: false`) can ignore these peers; the theme components are not registered in that case and MUI is never imported.
 
 ### Customizing placement
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackql/docusaurus-plugin-aeo",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "AEO (Answer Engine Optimization) helpers for Docusaurus: .md companion files, llms.txt / llms-full.txt, an Ask AI dropdown, and /ai/* route conventions.",
   "main": "src/index.js",
   "exports": {
@@ -21,12 +21,30 @@
   },
   "peerDependencies": {
     "@docusaurus/core": "^3.0.0",
+    "@emotion/react": "^11.0.0",
+    "@emotion/styled": "^11.0.0",
+    "@mui/icons-material": "^5.0.0 || ^6.0.0 || ^7.0.0",
+    "@mui/material": "^5.0.0 || ^6.0.0 || ^7.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
+  "peerDependenciesMeta": {
+    "@mui/material": {
+      "optional": false
+    },
+    "@mui/icons-material": {
+      "optional": false
+    },
+    "@emotion/react": {
+      "optional": false
+    },
+    "@emotion/styled": {
+      "optional": false
+    }
+  },
   "dependencies": {
-    "gray-matter": "^4.0.3",
-    "simple-icons": "^16.22.0"
+    "@lobehub/icons": "^5.10.0",
+    "gray-matter": "^4.0.3"
   },
   "overrides": {
     "serialize-javascript": "^7.0.5",

package/src/theme/AskAiButton/icons.js

@@ -1,72 +1,45 @@
-// Brand icons for the four supported AI providers.
+// Brand icons for the four supported AI providers, sourced from
+// @lobehub/icons. Each provider's package exports a default Mono
+// component with .Color, .Text, .Combine, .Avatar attached as
+// properties. We prefer .Color (multi-color brand variant) when the
+// provider ships one; OpenAI does not, so we fall back to Mono and
+// tint it with the ChatGPT brand green via inline style.
 //
-// Three of four come from simple-icons (siClaude, siPerplexity,
-// siGooglegemini). OpenAI / ChatGPT was removed from simple-icons in
-// 2024 following a takedown, so for that one we ship a neutral inline
-// chat-bubble glyph. The same fallback path is reused for any future
-// icon that disappears from upstream.
-//
-// All icons render as a 24x24 viewBox SVG with `fill="currentColor"`,
-// so the menu CSS can size them via font-size or width/height and tint
-// them via the surrounding text color. ESM `import` is used so webpack
-// can tree-shake unused simple-icons exports out of the bundle.
+// Deep import paths (@lobehub/icons/es/<Provider>) are used because
+// the package does not declare a subpath exports map; the deep path
+// is stable across the 5.x line and tree-shakes cleanly because each
+// per-provider module's dependency footprint is just React.
 
 import React from 'react';
-import { siClaude, siPerplexity, siGooglegemini } from 'simple-icons';
+import ClaudeIcons from '@lobehub/icons/es/Claude';
+import OpenAIIcons from '@lobehub/icons/es/OpenAI';
+import PerplexityIcons from '@lobehub/icons/es/Perplexity';
+import GeminiIcons from '@lobehub/icons/es/Gemini';
 
-function svg(children) {
-  return React.createElement(
-    'svg',
-    {
-      xmlns: 'http://www.w3.org/2000/svg',
-      width: '1em',
-      height: '1em',
-      viewBox: '0 0 24 24',
-      fill: 'currentColor',
-      role: 'img',
-      'aria-hidden': 'true',
-    },
-    children,
-  );
-}
+const ICON_SIZE = 18;
 
-function fromSimpleIcons(si) {
-  if (!si || typeof si.path !== 'string') {
-    return GenericAiIcon;
-  }
-  return function BrandIcon() {
-    return svg(React.createElement('path', { d: si.path }));
-  };
-}
+// OpenAI ships only the monochrome mark (Color variant absent from
+// @lobehub/icons as of 5.10.0). Use the known ChatGPT brand green so
+// the row visually matches the other three colored marks.
+const CHATGPT_GREEN = '#10A37F';
 
-// Neutral chat-bubble glyph - used when a brand icon isn't available
-// upstream. Not a brand mark, no trademark concerns.
-function GenericAiIcon() {
-  return svg(
-    React.createElement('path', {
-      d: 'M4 4h16a2 2 0 0 1 2 2v10a2 2 0 0 1-2 2h-8l-5 4v-4H4a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2Zm3 6h2v2H7v-2Zm4 0h2v2h-2v-2Zm4 0h2v2h-2v-2Z',
-    }),
-  );
+function makeColorIcon(IconNamespace, fallbackColor) {
+  const Component = IconNamespace.Color || IconNamespace;
+  const usingFallback = !IconNamespace.Color;
+  return function Icon() {
+    const props = { size: ICON_SIZE };
+    if (usingFallback && fallbackColor) {
+      props.style = { color: fallbackColor };
+    }
+    return React.createElement(Component, props);
+  };
 }
 
 const icons = {
-  claude: fromSimpleIcons(siClaude),
-  // simple-icons dropped OpenAI/ChatGPT in 2024; fall back to a neutral
-  // chat-bubble glyph rather than failing the build or shipping a guess
-  // at the wordmark.
-  chatgpt: GenericAiIcon,
-  perplexity: fromSimpleIcons(siPerplexity),
-  gemini: fromSimpleIcons(siGooglegemini),
+  claude: makeColorIcon(ClaudeIcons),
+  chatgpt: makeColorIcon(OpenAIIcons, CHATGPT_GREEN),
+  perplexity: makeColorIcon(PerplexityIcons),
+  gemini: makeColorIcon(GeminiIcons),
 };
 
-if (typeof console !== 'undefined') {
-  for (const [name, icon] of Object.entries(icons)) {
-    if (icon === GenericAiIcon && name !== 'chatgpt') {
-      console.warn(
-        `[plugin-aeo] AskAiButton: brand icon for "${name}" missing from simple-icons; using generic AI glyph`,
-      );
-    }
-  }
-}
-
 export default icons;

package/src/theme/AskAiButton/index.jsx

@@ -1,4 +1,10 @@
-import React, { useCallback, useEffect, useRef, useState } from 'react';
+import React, { useState } from 'react';
+import Button from '@mui/material/Button';
+import Menu from '@mui/material/Menu';
+import MenuItem from '@mui/material/MenuItem';
+import ListItemIcon from '@mui/material/ListItemIcon';
+import ListItemText from '@mui/material/ListItemText';
+import KeyboardArrowDownIcon from '@mui/icons-material/KeyboardArrowDown';
 import { useLocation } from '@docusaurus/router';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import { usePluginData } from '@docusaurus/useGlobalData';
@@ -19,51 +25,24 @@ const PROVIDER_URLS = {
   gemini: 'https://gemini.google.com/app?q=',
 };
 
-function buildPrompt(template, pageUrl) {
-  return template.replace('{pageUrl}', pageUrl);
-}
+const DEFAULT_PROMPT_TEMPLATE =
+  'Read {pageUrl}.md and help me with the following question about it: ';
 
-export default function AskAiButton(props) {
+export default function AskAiButton() {
   const { siteConfig } = useDocusaurusContext();
   const data = usePluginData('@stackql/docusaurus-plugin-aeo') || {};
   const cfg = data.askAi || {};
   const location = useLocation();
 
-  const [open, setOpen] = useState(false);
-  const wrapperRef = useRef(null);
-
-  useEffect(() => {
-    function onDocClick(e) {
-      if (wrapperRef.current && !wrapperRef.current.contains(e.target)) {
-        setOpen(false);
-      }
-    }
-    function onEsc(e) {
-      if (e.key === 'Escape') setOpen(false);
-    }
-    if (open) {
-      document.addEventListener('mousedown', onDocClick);
-      document.addEventListener('keydown', onEsc);
-    }
-    return () => {
-      document.removeEventListener('mousedown', onDocClick);
-      document.removeEventListener('keydown', onEsc);
-    };
-  }, [open]);
-
-  const toggle = useCallback(() => setOpen((v) => !v), []);
+  const [anchorEl, setAnchorEl] = useState(null);
+  const open = Boolean(anchorEl);
 
   if (cfg.enabled === false) return null;
 
   const baseUrl = (siteConfig.url || '').replace(/\/$/, '');
   const pageUrl = `${baseUrl}${location.pathname.replace(/\/$/, '') || ''}`;
-  const promptTemplate =
-    cfg.promptTemplate ||
-    'Read {pageUrl}.md and help me with the following question about it: ';
-  const targetUrl = cfg.companionsEnabled === false
-    ? pageUrl
-    : pageUrl; // template controls .md suffix; pageUrl is the HTML route
-  const prompt = buildPrompt(promptTemplate, targetUrl);
+  const promptTemplate = cfg.promptTemplate || DEFAULT_PROMPT_TEMPLATE;
+  const prompt = promptTemplate.replace('{pageUrl}', pageUrl);
   const encoded = encodeURIComponent(prompt);
 
   const order =
@@ -71,60 +50,76 @@ export default function AskAiButton(props) {
       ? cfg.providerOrder
       : ['claude', 'chatgpt', 'perplexity', 'gemini'];
 
+  const handleOpen = (e) => setAnchorEl(e.currentTarget);
+  const handleClose = () => setAnchorEl(null);
+
   return (
-    <div className={styles.wrapper} ref={wrapperRef}>
-      <button
-        type="button"
-        className={styles.trigger}
+    <div className={styles.dropdownWrapper}>
+      <Button
+        variant="outlined"
+        size="small"
+        endIcon={<KeyboardArrowDownIcon />}
+        onClick={handleOpen}
         aria-haspopup="menu"
         aria-expanded={open}
-        onClick={toggle}
+        sx={{
+          textTransform: 'none',
+          fontFamily: 'var(--ifm-font-family-base)',
+          fontWeight: 600,
+          fontSize: '0.75rem',
+          borderColor: 'var(--ifm-color-primary)',
+          color: 'var(--ifm-color-primary)',
+          '&:hover': {
+            borderColor: 'var(--ifm-color-primary)',
+            backgroundColor: 'rgba(0, 65, 101, 0.04)',
+          },
+        }}
+      >
+        Ask AI about this page
+      </Button>
+      <Menu
+        anchorEl={anchorEl}
+        open={open}
+        onClose={handleClose}
+        anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+        transformOrigin={{ vertical: 'top', horizontal: 'right' }}
+        sx={{
+          '& .MuiPaper-root': {
+            fontFamily: 'var(--ifm-font-family-base)',
+            minWidth: 200,
+          },
+        }}
       >
-        <span>Ask AI about this page</span>
-        <span
-          className={`${styles.caret}${open ? ` ${styles.caretOpen}` : ''}`}
-          aria-hidden="true"
-        >
-          {/* Inline chevron-down so we don't depend on a font glyph. */}
-          <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="0.75em"
-            height="0.75em"
-            viewBox="0 0 24 24"
-            fill="currentColor"
-          >
-            <path d="M6 9l6 6 6-6H6z" />
-          </svg>
-        </span>
-      </button>
-      {open && (
-        <ul className={styles.menu} role="menu">
-          {order.map((key) => {
-            const Icon = icons[key];
-            const label = PROVIDER_LABELS[key] || key;
-            const base = PROVIDER_URLS[key];
-            if (!base || !Icon) return null;
-            const href = `${base}${encoded}`;
-            return (
-              <li key={key} className={styles.item} role="none">
-                <a
-                  role="menuitem"
-                  className={styles.itemLink}
-                  href={href}
-                  target="_blank"
-                  rel="noopener noreferrer"
-                  onClick={() => setOpen(false)}
-                >
-                  <span className={styles.icon}>
-                    <Icon />
-                  </span>
-                  <span>{label}</span>
-                </a>
-              </li>
-            );
-          })}
-        </ul>
-      )}
+        {order.map((key) => {
+          const Icon = icons[key];
+          const label = PROVIDER_LABELS[key];
+          const base = PROVIDER_URLS[key];
+          if (!base || !Icon) return null;
+          const href = `${base}${encoded}`;
+          return (
+            <MenuItem
+              key={key}
+              component="a"
+              href={href}
+              target="_blank"
+              rel="noopener noreferrer"
+              onClick={handleClose}
+            >
+              <ListItemIcon sx={{ minWidth: 32, color: 'inherit' }}>
+                <Icon />
+              </ListItemIcon>
+              <ListItemText
+                primaryTypographyProps={{
+                  fontSize: '0.85rem',
+                  fontFamily: 'var(--ifm-font-family-base)',
+                }}
+              >
+                {label}
+              </ListItemText>
+            </MenuItem>
+          );
+        })}
+      </Menu>
     </div>
   );
 }

package/src/theme/AskAiButton/styles.module.css

@@ -1,87 +1,11 @@
-.wrapper {
-  position: relative;
-  display: inline-block;
+.dropdownWrapper {
+  display: none;
+  flex-shrink: 0;
 }
 
-.trigger {
-  display: inline-flex;
-  align-items: center;
-  gap: 0.5rem;
-  padding: 0.4rem 0.9rem;
-  background: var(--ifm-color-primary);
-  color: var(--ifm-color-primary-contrast-foreground, #fff);
-  border: none;
-  border-radius: 999px;
-  font-size: 0.875rem;
-  font-weight: 500;
-  line-height: 1.2;
-  cursor: pointer;
-  white-space: nowrap;
-  transition: background-color 0.15s ease;
-}
-
-.trigger:hover {
-  background: var(--ifm-color-primary-darker, var(--ifm-color-primary-dark));
-}
-
-.trigger:focus-visible {
-  outline: 2px solid var(--ifm-color-primary-light, currentColor);
-  outline-offset: 2px;
-}
-
-.caret {
-  display: inline-block;
-  font-size: 0.7em;
-  opacity: 0.9;
-  transition: transform 0.15s ease;
-}
-
-.caretOpen {
-  transform: rotate(180deg);
-}
-
-.menu {
-  position: absolute;
-  top: calc(100% + 0.4rem);
-  right: 0;
-  z-index: 100;
-  min-width: 200px;
-  margin: 0;
-  padding: 0.25rem 0;
-  list-style: none;
-  background: var(--ifm-background-surface-color, var(--ifm-background-color));
-  border: 1px solid var(--ifm-color-emphasis-300);
-  border-radius: 0.5rem;
-  box-shadow: 0 6px 24px -8px rgba(0, 0, 0, 0.18);
-}
-
-.item {
-  margin: 0;
-}
-
-.itemLink {
-  display: flex;
-  align-items: center;
-  gap: 0.65rem;
-  padding: 0.5rem 0.85rem;
-  color: var(--ifm-color-content, var(--ifm-font-color-base));
-  text-decoration: none;
-  font-size: 0.875rem;
-}
-
-.itemLink:hover {
-  background: var(--ifm-color-emphasis-100);
-  color: var(--ifm-color-content, var(--ifm-font-color-base));
-  text-decoration: none;
-}
-
-.icon {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 18px;
-  height: 18px;
-  font-size: 18px;
-  color: var(--ifm-color-content, var(--ifm-font-color-base));
-  flex: 0 0 auto;
+@media screen and (min-width: 997px) {
+  .dropdownWrapper {
+    display: flex;
+    align-items: center;
+  }
 }