@farming-labs/svelte-theme 0.0.50 → 0.0.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/svelte-theme",
-  "version": "0.0.50",
+  "version": "0.0.52",
   "description": "Svelte UI components for @farming-labs/docs — layout, sidebar, TOC, search, and theme toggle",
   "keywords": [
     "docs",
@@ -82,8 +82,8 @@
   "dependencies": {
     "gray-matter": "^4.0.3",
     "sugar-high": "^0.9.5",
-    "@farming-labs/svelte": "0.0.50",
-    "@farming-labs/docs": "0.0.50"
+    "@farming-labs/docs": "0.0.52",
+    "@farming-labs/svelte": "0.0.52"
   },
   "peerDependencies": {
     "svelte": ">=5.0.0"

package/src/components/DocsContent.svelte

@@ -12,6 +12,7 @@
   let openDropdownMenu = $state(false);
   let copyLabel = $state("Copy page");
   let copied = $state(false);
+  let selectedFeedback = $state(null);
 
   let titleSuffix = $derived(
     config?.metadata?.titleTemplate
@@ -121,6 +122,26 @@
   );
   let showActionsAbove = $derived(pageActionsPosition === "above-title" && showPageActions);
   let showActionsBelow = $derived(pageActionsPosition === "below-title" && showPageActions);
+  let feedbackConfig = $derived.by(() => {
+    const defaults = {
+      enabled: false,
+      question: "How is this guide?",
+      positiveLabel: "Good",
+      negativeLabel: "Bad",
+      onFeedback: undefined,
+    };
+
+    const feedback = config?.feedback;
+    if (feedback === undefined || feedback === false) return defaults;
+    if (feedback === true) return { ...defaults, enabled: true };
+    return {
+      enabled: feedback.enabled !== false,
+      question: feedback.question ?? defaults.question,
+      positiveLabel: feedback.positiveLabel ?? defaults.positiveLabel,
+      negativeLabel: feedback.negativeLabel ?? defaults.negativeLabel,
+      onFeedback: typeof feedback.onFeedback === "function" ? feedback.onFeedback : undefined,
+    };
+  });
 
   function handleCopyPage() {
     let text = "";
@@ -170,6 +191,44 @@
     closeDropdown();
   }
 
+  function handleFeedback(value) {
+    selectedFeedback = value;
+
+    const pathname =
+      typeof window !== "undefined"
+        ? window.location.pathname.replace(/\/$/, "") || "/"
+        : data.slug
+          ? `/${data.entry ?? config?.entry ?? "docs"}/${data.slug}`
+          : `/${data.entry ?? config?.entry ?? "docs"}`;
+
+    const payload = {
+      value,
+      title: data.title,
+      description: data.description,
+      url: typeof window !== "undefined" ? window.location.href : pathname,
+      pathname,
+      path: pathname,
+      entry: data.entry ?? config?.entry ?? "docs",
+      slug: data.slug ?? "",
+      locale: data.locale,
+    };
+
+    try {
+      feedbackConfig.onFeedback?.(payload);
+    } catch {}
+
+    try {
+      const docsWindow = typeof window !== "undefined" ? window : undefined;
+      if (docsWindow && typeof docsWindow.__fdOnFeedback__ === "function") {
+        docsWindow.__fdOnFeedback__(payload);
+      }
+    } catch {}
+
+    if (typeof window !== "undefined") {
+      window.dispatchEvent(new CustomEvent("fd:feedback", { detail: payload }));
+    }
+  }
+
   function handleClickOutside(e) {
     const target = e.target;
     if (openDropdownMenu && !target?.closest?.(".fd-page-action-dropdown")) {
@@ -344,6 +403,52 @@
       {/if}
 
       {@html htmlWithoutFirstH1}
+
+      {#if feedbackConfig.enabled}
+        <section class="fd-feedback" aria-label="Page feedback">
+          <div class="fd-feedback-content">
+            <p class="fd-feedback-question">{feedbackConfig.question}</p>
+            <div class="fd-feedback-actions" role="group" aria-label={feedbackConfig.question}>
+              <button
+                type="button"
+                class="fd-page-action-btn"
+                aria-pressed={selectedFeedback === "positive"}
+                data-selected={selectedFeedback === "positive" ? "true" : undefined}
+                onclick={() => handleFeedback("positive")}
+              >
+                <svg width="14" height="14" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+                  <path
+                    d="M7 21H5a2 2 0 0 1-2-2v-7a2 2 0 0 1 2-2h2m0 11V10m0 11h9.28a2 2 0 0 0 1.97-1.66l1.2-7A2 2 0 0 0 17.48 10H13V6.5a2.5 2.5 0 0 0-2.5-2.5L7 10"
+                    stroke="currentColor"
+                    stroke-width="2"
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                  />
+                </svg>
+                <span>{feedbackConfig.positiveLabel}</span>
+              </button>
+              <button
+                type="button"
+                class="fd-page-action-btn"
+                aria-pressed={selectedFeedback === "negative"}
+                data-selected={selectedFeedback === "negative" ? "true" : undefined}
+                onclick={() => handleFeedback("negative")}
+              >
+                <svg width="14" height="14" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+                  <path
+                    d="M17 3h2a2 2 0 0 1 2 2v7a2 2 0 0 1-2 2h-2M17 3v11m0-11H7.72a2 2 0 0 0-1.97 1.66l-1.2 7A2 2 0 0 0 6.52 14H11v3.5a2.5 2.5 0 0 0 2.5 2.5L17 14"
+                    stroke="currentColor"
+                    stroke-width="2"
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                  />
+                </svg>
+                <span>{feedbackConfig.negativeLabel}</span>
+              </button>
+            </div>
+          </div>
+        </section>
+      {/if}
     </div>
   {/snippet}
 </DocsPage>

package/src/components/DocsPage.svelte

@@ -40,6 +40,25 @@
     return { ...page, url: withLang(page.url, activeLocale) };
   }
 
+  function setHoverLinkOpen(root, open) {
+    if (!(root instanceof HTMLElement)) return;
+    const trigger = root.querySelector(".fd-hover-link-trigger");
+    const popover = root.querySelector(".fd-hover-link-popover");
+    if (!(trigger instanceof HTMLElement) || !(popover instanceof HTMLElement)) return;
+
+    root.classList.toggle("fd-hover-link-open", open);
+    trigger.setAttribute("aria-expanded", String(open));
+    popover.setAttribute("aria-hidden", String(!open));
+  }
+
+  function closeOpenHoverLinks(event) {
+    document.querySelectorAll("[data-hover-link].fd-hover-link-open").forEach((root) => {
+      if (!(root instanceof HTMLElement)) return;
+      if (event.target instanceof Node && root.contains(event.target)) return;
+      setHoverLinkOpen(root, false);
+    });
+  }
+
   onMount(() => {
     scanHeadings();
     wireInteractive();
@@ -115,6 +134,75 @@
         const localized = withLang(href, locale);
         if (localized) link.setAttribute("href", localized);
       });
+
+      document.querySelectorAll("[data-hover-link]").forEach((root) => {
+        if (!(root instanceof HTMLElement)) return;
+        if (root.dataset.fdHoverLinkBound === "true") return;
+        root.dataset.fdHoverLinkBound = "true";
+
+        const trigger = root.querySelector(".fd-hover-link-trigger");
+        const popover = root.querySelector(".fd-hover-link-popover");
+        if (!(trigger instanceof HTMLElement) || !(popover instanceof HTMLElement)) return;
+
+        let closeTimer = 0;
+        const setOpen = (open) => {
+          if (closeTimer !== 0) {
+            window.clearTimeout(closeTimer);
+            closeTimer = 0;
+          }
+          setHoverLinkOpen(root, open);
+        };
+
+        const containsTarget = (target) => target instanceof Node && root.contains(target);
+        const closeSoon = () => {
+          if (closeTimer !== 0) window.clearTimeout(closeTimer);
+          closeTimer = window.setTimeout(() => setOpen(false), 90);
+        };
+
+        trigger.addEventListener("pointerenter", () => setOpen(true));
+        trigger.addEventListener("pointerleave", (event) => {
+          if (containsTarget(event.relatedTarget)) return;
+          closeSoon();
+        });
+        trigger.addEventListener("focus", (event) => {
+          if (!(event.currentTarget instanceof HTMLElement)) return;
+          if (typeof event.currentTarget.matches === "function" && !event.currentTarget.matches(":focus-visible")) {
+            return;
+          }
+          setOpen(true);
+        });
+        trigger.addEventListener("blur", (event) => {
+          if (containsTarget(event.relatedTarget)) return;
+          closeSoon();
+        });
+        trigger.addEventListener("click", (event) => {
+          event.preventDefault();
+          setOpen(true);
+        });
+
+        popover.addEventListener("pointerenter", () => setOpen(true));
+        popover.addEventListener("pointerleave", (event) => {
+          if (containsTarget(event.relatedTarget)) return;
+          closeSoon();
+        });
+        popover.addEventListener("focusin", () => setOpen(true));
+        popover.addEventListener("focusout", (event) => {
+          if (containsTarget(event.relatedTarget)) return;
+          closeSoon();
+        });
+
+        root.addEventListener("keydown", (event) => {
+          if (event.key !== "Escape") return;
+          setOpen(false);
+        });
+      });
+
+      if (document.documentElement.dataset.fdHoverLinkGlobalBound !== "true") {
+        document.documentElement.dataset.fdHoverLinkGlobalBound = "true";
+
+        document.addEventListener("pointerdown", closeOpenHoverLinks);
+        document.addEventListener("focusin", closeOpenHoverLinks);
+      }
     });
   }
 </script>

package/src/themes/colorful.js

@@ -30,6 +30,7 @@ const ColorfulUIDefaults = {
   components: {
     Callout: { variant: "soft", icon: true },
     CodeBlock: { showCopyButton: true },
+    HoverLink: { linkLabel: "Open page", showIndicator: false },
     Tabs: { style: "default" },
   },
 };

package/src/themes/darksharp.js

@@ -30,6 +30,7 @@ const DarksharpUIDefaults = {
   components: {
     Callout: { variant: "soft", icon: true },
     CodeBlock: { showCopyButton: true },
+    HoverLink: { linkLabel: "Open page", showIndicator: false },
     Tabs: { style: "default" },
   },
 };

package/src/themes/default.js

@@ -30,6 +30,7 @@ const DefaultUIDefaults = {
   components: {
     Callout: { variant: "soft", icon: true },
     CodeBlock: { showCopyButton: true },
+    HoverLink: { linkLabel: "Open page", showIndicator: false },
     Tabs: { style: "default" },
   },
 };

package/src/themes/greentree.js

@@ -30,6 +30,7 @@ const GreenTreeUIDefaults = {
   components: {
     Callout: { variant: "soft", icon: true },
     CodeBlock: { showCopyButton: true },
+    HoverLink: { linkLabel: "Open page", showIndicator: false },
     Tabs: { style: "default" },
   },
 };

package/src/themes/pixel-border.js

@@ -27,7 +27,9 @@ const PixelBorderUIDefaults = {
     toc: { enabled: true, depth: 3 },
     header: { height: 56, sticky: true },
   },
-  components: {},
+  components: {
+    HoverLink: { linkLabel: "Open page", showIndicator: false },
+  },
 };
 
 export const pixelBorder = createTheme({

package/styles/docs.css

@@ -644,10 +644,19 @@ samp {
   color: var(--color-fd-foreground);
 }
 
+.fd-page-action-btn[data-selected="true"] {
+  color: var(--color-fd-accent-foreground);
+  background: var(--color-fd-accent);
+}
+
 .fd-page-action-btn svg {
   flex-shrink: 0;
 }
 
+.fd-page-action-btn[data-selected="true"] svg {
+  color: currentColor;
+}
+
 .fd-page-action-dropdown {
   position: relative;
 }
@@ -715,6 +724,35 @@ samp {
   margin-bottom: 1rem;
 }
 
+.fd-feedback {
+  margin-top: 2rem;
+  padding-top: 1.25rem;
+  border-top: 1px solid var(--color-fd-border);
+}
+
+.fd-feedback-content {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  flex-wrap: wrap;
+}
+
+.fd-feedback-question {
+  margin: 0;
+  font-size: 0.9375rem;
+  font-weight: 600;
+  line-height: 1.5;
+  color: var(--color-fd-foreground);
+}
+
+.fd-feedback-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
 /* ─── Breadcrumb ─────────────────────────────────────────────────────── */
 
 .fd-breadcrumb {
@@ -914,6 +952,206 @@ samp {
   opacity: 0.8;
 }
 
+.fd-hover-link {
+  position: relative;
+  display: inline-block;
+  vertical-align: baseline;
+  max-width: 100%;
+}
+
+.fd-hover-link-trigger {
+  display: inline !important;
+  border: none;
+  background: transparent;
+  padding: 0;
+  margin: 0;
+  color: var(--color-fd-foreground);
+  cursor: pointer;
+  text-decoration: underline;
+  text-decoration-style: dashed;
+  text-decoration-thickness: 0.08em;
+  text-underline-offset: 0.22em;
+  text-decoration-color: color-mix(in srgb, var(--color-fd-foreground) 46%, transparent);
+  font: inherit;
+  line-height: inherit;
+  vertical-align: baseline;
+  appearance: none;
+  transition: text-decoration-color 180ms ease, opacity 180ms ease;
+}
+
+.fd-hover-link-trigger:hover,
+.fd-hover-link-trigger:focus-visible,
+.fd-hover-link-open > .fd-hover-link-trigger {
+  text-decoration-color: color-mix(in srgb, var(--color-fd-foreground) 68%, transparent);
+}
+
+.fd-hover-link-trigger:focus-visible {
+  outline: none;
+}
+
+.fd-hover-link-popover {
+  --fd-hover-link-rest-x: -50%;
+  --fd-hover-link-rest-y: 8px;
+  --fd-hover-link-open-x: -50%;
+  --fd-hover-link-open-y: 0;
+  position: absolute;
+  top: calc(100% + var(--fd-hover-link-side-offset, 12px));
+  left: 50%;
+  z-index: 40;
+  width: min(22rem, calc(100vw - 2rem));
+  max-width: min(22rem, calc(100vw - 2rem));
+  opacity: 0;
+  visibility: hidden;
+  pointer-events: none;
+  transform: translate3d(var(--fd-hover-link-rest-x), var(--fd-hover-link-rest-y), 0);
+  transition: opacity 180ms ease, transform 180ms ease, visibility 180ms linear;
+}
+
+.fd-hover-link[data-align="start"] > .fd-hover-link-popover {
+  left: 0;
+  --fd-hover-link-rest-x: 0;
+  --fd-hover-link-open-x: 0;
+}
+
+.fd-hover-link[data-align="end"] > .fd-hover-link-popover {
+  left: auto;
+  right: 0;
+  --fd-hover-link-rest-x: 0;
+  --fd-hover-link-open-x: 0;
+}
+
+.fd-hover-link[data-side="top"] > .fd-hover-link-popover {
+  top: auto;
+  bottom: calc(100% + var(--fd-hover-link-side-offset, 12px));
+  --fd-hover-link-rest-y: -8px;
+  --fd-hover-link-open-y: 0;
+}
+
+.fd-hover-link[data-side="right"] > .fd-hover-link-popover {
+  top: 50%;
+  left: calc(100% + var(--fd-hover-link-side-offset, 12px));
+  right: auto;
+  --fd-hover-link-rest-x: 8px;
+  --fd-hover-link-rest-y: -50%;
+  --fd-hover-link-open-x: 0;
+  --fd-hover-link-open-y: -50%;
+}
+
+.fd-hover-link[data-side="right"][data-align="start"] > .fd-hover-link-popover {
+  top: 0;
+  --fd-hover-link-rest-y: 0;
+  --fd-hover-link-open-y: 0;
+}
+
+.fd-hover-link[data-side="right"][data-align="end"] > .fd-hover-link-popover {
+  top: auto;
+  bottom: 0;
+  --fd-hover-link-rest-y: 0;
+  --fd-hover-link-open-y: 0;
+}
+
+.fd-hover-link[data-side="left"] > .fd-hover-link-popover {
+  top: 50%;
+  left: auto;
+  right: calc(100% + var(--fd-hover-link-side-offset, 12px));
+  --fd-hover-link-rest-x: -8px;
+  --fd-hover-link-rest-y: -50%;
+  --fd-hover-link-open-x: 0;
+  --fd-hover-link-open-y: -50%;
+}
+
+.fd-hover-link[data-side="left"][data-align="start"] > .fd-hover-link-popover {
+  top: 0;
+  --fd-hover-link-rest-y: 0;
+  --fd-hover-link-open-y: 0;
+}
+
+.fd-hover-link[data-side="left"][data-align="end"] > .fd-hover-link-popover {
+  top: auto;
+  bottom: 0;
+  --fd-hover-link-rest-y: 0;
+  --fd-hover-link-open-y: 0;
+}
+
+.fd-hover-link-open > .fd-hover-link-popover {
+  opacity: 1;
+  visibility: visible;
+  pointer-events: auto;
+  transform: translate3d(var(--fd-hover-link-open-x), var(--fd-hover-link-open-y), 0);
+}
+
+.fd-hover-link-card {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  width: 100%;
+  border-radius: calc(var(--radius, 0.75rem) + 2px);
+  border: 1px solid color-mix(in srgb, var(--color-fd-border) 88%, transparent);
+  background: var(--color-fd-popover, var(--color-fd-background));
+  color: var(--color-fd-popover-foreground, var(--color-fd-foreground));
+  padding: 0.95rem 1rem;
+  box-shadow: 0 20px 45px color-mix(in srgb, var(--color-fd-background) 78%, transparent);
+  backdrop-filter: blur(14px);
+}
+
+.fd-hover-link-body {
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+
+.fd-hover-link-preview-label {
+  font-size: 0.68rem;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  font-family: var(--fd-font-mono, var(--font-geist-mono, ui-monospace, monospace));
+  color: color-mix(in srgb, var(--color-fd-popover-foreground, var(--color-fd-foreground)) 55%, transparent);
+}
+
+.fd-hover-link-title,
+.fd-hover-link-cta {
+  text-decoration: none !important;
+}
+
+.fd-hover-link-title {
+  color: var(--color-fd-popover-foreground, var(--color-fd-foreground));
+  font-size: 1rem;
+  font-weight: 600 !important;
+  line-height: 1.3;
+}
+
+.fd-hover-link-title:hover,
+.fd-hover-link-cta:hover {
+  opacity: 1;
+}
+
+.fd-hover-link-description {
+  font-size: 0.92rem;
+  line-height: 1.6;
+  color: color-mix(in srgb, var(--color-fd-popover-foreground, var(--color-fd-foreground)) 74%, transparent);
+}
+
+.fd-hover-link-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  padding-top: 0.25rem;
+  border-top: 1px solid color-mix(in srgb, var(--color-fd-border) 72%, transparent);
+}
+
+.fd-hover-link-cta {
+  display: inline-flex !important;
+  align-items: center;
+  gap: 0.4rem;
+  color: var(--color-fd-primary);
+  font-size: 0.8rem;
+  font-weight: 600 !important;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  font-family: var(--fd-font-mono, var(--font-geist-mono, ui-monospace, monospace));
+}
+
 .fd-page-body h1 {
   font-size: var(--fd-h1-size, 2.25rem);
   font-weight: var(--fd-h1-weight, 700);