portosaurus 3.0.2 → 4.0.0

package/src/theme/components/NoteIndex/index.js

@@ -1,24 +1,23 @@
-import { useRef, useState, useEffect } from "react";
-import Link from "@docusaurus/Link";
 import useBaseUrl from "@docusaurus/useBaseUrl";
 import { usePluginData } from "@docusaurus/useGlobalData";
+import Link from "@docusaurus/Link";
+import { FaBook, FaChevronRight } from "react-icons/fa";
+import Tooltip from "../Tooltip/index.js";
 import { iconMap } from "../../config/iconMappings.js";
 import DocCardList from "@theme/DocCardList";
-import Tooltip from "../Tooltip/index.js";
-
-import { FaBook } from "react-icons/fa";
 import styles from "./styles.module.css";
 
-function indexNotes() {
+/**
+ * Extracts and prepares notes from the filesystem
+ */
+function useNotes() {
   const context = require.context(`@site/notes`, true, /index\.mdx?$|\.mdx?$/);
 
   return context
     .keys()
     .filter((path) => {
       // Skip root index file
-      if (path === "./index.md" || path === "./index.mdx") {
-        return false;
-      }
+      if (path === "./index.md" || path === "./index.mdx") return false;
 
       const pathParts = path.split("/");
       const isTopLevelFile =
@@ -26,136 +25,111 @@ function indexNotes() {
       const isTopLevelDir =
         pathParts.length === 3 && path.match(/index\.mdx?$/);
 
-      // Keep only top-level files & dirs
       return isTopLevelFile || isTopLevelDir;
     })
     .map((path) => {
+      const { frontMatter } = context(path);
       const pathParts = path.split("/");
       const isTopLevelFile = pathParts.length === 2;
 
-      // Extract directory or filename
-      const slug = isTopLevelFile
+      // Extract filename-based slug as fallback
+      const fileSlug = isTopLevelFile
         ? path.replace("./", "").replace(/\.mdx?$/, "")
         : pathParts[1];
 
-      const { frontMatter } = context(path);
+      // Routing logic: slug > id > filename
+      const slug = frontMatter.slug || frontMatter.id || fileSlug;
+
+      // Display logic: title > language > filename
+      const rawTitle = frontMatter.title || frontMatter.language || fileSlug;
+      const title = rawTitle.charAt(0).toUpperCase() + rawTitle.slice(1);
 
-      const title =
-        frontMatter.title || slug.charAt(0).toUpperCase() + slug.slice(1);
       const language = frontMatter.language
         ? frontMatter.language
             .toLowerCase()
             .replace(/ /g, "")
             .replace(/[\s-]/g, "")
         : slug.toLowerCase() || title.toLowerCase();
-      const position = frontMatter.sidebar_position || 999;
-      const description = frontMatter.description || "";
 
       return {
         title,
         language,
-        link: slug,
-        position,
-        description,
+        slug,
+        desc: frontMatter.desc || "",
+        position: frontMatter.sidebar_position || 999,
       };
     })
     .sort((a, b) => a.position - b.position);
 }
-function NoteCard({
-  title,
-  language,
-  link,
-  description,
-  index,
-  docsBasePath,
-  buttonText,
-}) {
-  const noteUrl = useBaseUrl(`${docsBasePath}/${link}`);
+
+/**
+ * Individual Note Card Component
+ */
+function NoteCard({ title, language, slug, desc, index, docsBasePath }) {
+  const noteUrl = useBaseUrl(`${docsBasePath}/${slug}`);
   const { icon: Icon = FaBook, color = "var(--ifm-color-primary)" } =
     iconMap[language] || iconMap[title.toLowerCase()] || {};
 
-  const tooltipContent = description ? (
-    <span
-      style={{
-        textAlign: "center",
-        minWidth: "150px",
-        display: "flex",
-        flexDirection: "column",
-        gap: "6px",
-      }}
-    >
-      <strong style={{ fontSize: "0.95em" }}>{title}</strong>
-      <span
-        style={{
-          fontSize: "0.85em",
-          opacity: 0.85,
-          fontWeight: 400,
-          textAlign: "left",
-        }}
-      >
-        {description}
-      </span>
-    </span>
-  ) : (
-    title
-  );
+  const tooltipContent = desc ? desc : null;
 
-  return (
-    <div
-      key={title}
-      className={`${styles.noteCard} note-card`}
-      style={{ "--card-index": index }}
-      role="listitem"
-      id={`note-${link}`}
+  const cardInner = (
+    <Link
+      to={noteUrl}
+      className={styles.noteCard}
+      style={{ "--card-index": index, "--note-color": color }}
+      aria-label={`Read note: ${title}`}
     >
-      <div className={styles.noteIcon} style={{ color }} aria-hidden="true">
-        <Icon />
+      <div className={styles.iconWrapper}>
+        <Icon className={styles.noteIcon} />
       </div>
-      <Tooltip
-        msg={tooltipContent}
-        position="top"
-        underline={false}
-        color="var(--ifm-color-primary-dark)"
-      >
-        <span className={styles.noteTitle} role="heading" aria-level="3">
-          {title}
-        </span>
-      </Tooltip>
-      <Link
-        className="button button--primary"
-        to={noteUrl}
-        aria-label={`Open ${title} note`}
-      >
-        {buttonText}
-      </Link>
-    </div>
+
+      <div className={styles.cardContent}>
+        <h3 className={styles.noteTitle}>{title}</h3>
+      </div>
+
+      <FaChevronRight className={styles.mobileChevron} />
+    </Link>
+  );
+
+  return tooltipContent ? (
+    <Tooltip msg={tooltipContent} position="top" underline={false} gap={-8}>
+      {cardInner}
+    </Tooltip>
+  ) : (
+    cardInner
   );
 }
 
-export default function NoteCards({ buttonText = "Open Note" }) {
-  const notes = indexNotes();
+/**
+ * Main Notes Grid Component
+ */
+export default function NoteCards() {
+  const notes = useNotes();
   const { path: docsBasePath } = usePluginData(
     "docusaurus-plugin-content-docs",
   );
 
+  if (!notes.length) return null;
+
   return (
-    <div className={styles.notesGrid} role="list" aria-label="Notes collection">
+    <div className={styles.notesGrid} role="list">
       {notes.map((note, index) => (
         <NoteCard
-          key={note.title}
+          key={note.slug}
           {...note}
           index={index}
           docsBasePath={docsBasePath}
-          buttonText={buttonText}
         />
       ))}
     </div>
   );
 }
 
-// List Topics inside Individual Notes
+/**
+ * Topic List Helper (for inside notes)
+ */
 export function TopicList({
-  description = "Click on the links below to explore the topics.",
+  desc = "Click on the links below to explore the topics.",
   style = {
     marginTop: "-2.5rem",
     marginBottom: "2.5rem",
@@ -163,12 +137,9 @@ export function TopicList({
   },
 }) {
   return (
-    <>
-      <p
-        style={style}
-        dangerouslySetInnerHTML={{ __html: description }} // Well we are giving it only HTML :)
-      />
+    <div style={style}>
+      <p dangerouslySetInnerHTML={{ __html: desc }} />
       <DocCardList />
-    </>
+    </div>
   );
 }

package/src/theme/components/NoteIndex/styles.module.css

@@ -1,7 +1,7 @@
-@keyframes fadeIn {
+@keyframes noteFadeIn {
   from {
     opacity: 0;
-    transform: translateY(20px);
+    transform: translateY(15px);
   }
   to {
     opacity: 1;
@@ -12,40 +12,47 @@
 .notesGrid {
   display: flex;
   flex-wrap: wrap;
-  gap: 1.5rem;
+  gap: 1rem;
   justify-content: center;
   margin: 2rem 0;
 }
 
 .noteCard {
   width: 200px;
-  border-radius: var(--ifm-card-border-radius);
-  text-align: center;
-  padding: 1.2rem;
+  min-height: 220px;
   background-color: var(--ifm-card-background-color);
-  opacity: 0;
-  transition:
-    transform 0.3s ease,
-    scale 0.3s ease,
-    z-index 0s;
-  animation: fadeIn 0.5s ease-out forwards;
-  animation-delay: calc(0.2s + (var(--card-index, 0) * 0.1s));
+  border-radius: var(--ifm-card-border-radius);
+  padding: 1.5rem 1rem;
+  text-decoration: none !important;
+  color: var(--ifm-font-color-base) !important;
   display: flex;
   flex-direction: column;
+  align-items: center;
+  justify-content: center;
   position: relative;
-  z-index: 1;
+  overflow: hidden;
+  transition: all 0.3s ease;
+  animation: noteFadeIn 0.5s ease-out forwards;
+  animation-delay: calc(0.1s + (var(--card-index, 0) * 0.05s));
+  opacity: 0;
 }
 
 .noteCard:hover {
-  transform: translateY(-5px);
-  scale: 1.05;
-  z-index: 10;
+  transform: translateY(-8px) scale(1.03);
+  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.2);
+}
+
+.iconWrapper {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  margin-bottom: 1.5rem;
 }
 
 .noteIcon {
-  font-size: 69px;
-  margin-bottom: -1rem;
-  transition: transform 0.2s ease;
+  font-size: 3.5rem;
+  color: var(--note-color);
+  transition: transform 0.3s ease;
 }
 
 .noteCard:hover .noteIcon {
@@ -53,75 +60,62 @@
 }
 
 .noteTitle {
-  margin-bottom: 1.8rem;
-  color: var(--ifm-font-color-base);
-  font-size: 1.8rem;
-  font-weight: 600;
+  margin: 0;
+  font-size: 1.6rem;
+  font-weight: 700;
+  line-height: 1.3;
+  text-align: center;
   display: -webkit-box;
-  line-clamp: 3;
-  -webkit-line-clamp: 3;
+  -webkit-line-clamp: 2;
+  line-clamp: 2;
   -webkit-box-orient: vertical;
   overflow: hidden;
   text-overflow: ellipsis;
-  word-break: break-word;
+  overflow-wrap: anywhere;
 }
 
-.noteCard > a {
-  margin-top: auto;
-  align-self: center;
-}
-
-@media (max-width: 768px) {
-  .noteCard {
-    width: 150px;
-    padding: 0.8rem;
-  }
-
-  .noteIcon {
-    font-size: 45px;
-    margin-bottom: -0.8rem;
-  }
-
-  .noteTitle {
-    font-size: 1.3rem;
-    margin-bottom: 1.5rem;
-  }
+/* Mobile List Style */
+.mobileChevron {
+  display: none;
 }
 
 @media (max-width: 480px) {
   .notesGrid {
-    gap: 0.7rem;
-    margin: 0.8rem auto;
-    justify-content: center;
-    padding: 0 0.05rem;
+    gap: 0.65rem;
+    margin: 0.2rem 0;
+    padding: 0 0.2rem;
+    display: flex;
+    flex-direction: column;
+    align-items: stretch;
+    justify-content: flex-start;
+  }
+
+  /* Force the Tooltip container to be full-width */
+  .notesGrid > span {
+    width: 100%;
+    display: flex !important;
+    justify-content: flex-start;
   }
 
   .noteCard {
     width: 100%;
-    max-width: 400px;
-    padding: 1rem;
-    display: flex;
+    min-height: auto;
     flex-direction: row;
     align-items: center;
-    gap: 1rem;
-    text-align: left;
-    border-radius: var(--ifm-card-border-radius);
+    padding: 0.95rem 1.2rem;
+    justify-content: flex-start;
+    background-color: var(--ifm-card-background-color);
+    border-radius: 12px;
     box-shadow: var(--ifm-global-shadow-md);
-    transition: transform 0.2s ease;
+    gap: 1.2rem;
   }
 
   .noteCard:hover {
     transform: none;
-    scale: 1;
-  }
-
-  .noteCard:active {
-    transform: scale(0.98);
     background-color: var(--ifm-hover-overlay);
   }
 
-  .noteIcon {
-    font-size: 42px;
+  .iconWrapper {
     margin: 0;
     flex-shrink: 0;
     display: flex;
@@ -129,43 +123,45 @@
     justify-content: center;
   }
 
-  /* Remove any absolute positioning or shifts that break centering */
-  .noteIcon > svg {
-    margin: 0;
+  .noteIcon {
+    font-size: 2.8rem;
   }
 
-  .noteTitle {
-    font-size: 1.1rem;
-    margin: 0;
+  .cardContent {
+    text-align: left;
     flex: 1;
     min-width: 0;
-    line-height: 1.3;
-    display: -webkit-box;
+  }
+
+  .noteTitle {
+    font-size: 1.2rem;
+    font-weight: 600;
+    color: var(--ifm-font-color-base);
     -webkit-line-clamp: 2;
     line-clamp: 2;
-    -webkit-box-orient: vertical;
-    overflow: hidden;
-    text-overflow: ellipsis;
+    overflow-wrap: anywhere;
+    text-align: left;
   }
 
-  .noteCard > a {
-    margin: 0 0 0 auto;
-    padding: 0.5rem 0.8rem;
-    font-size: 0.85rem;
-    border-radius: var(--ifm-global-radius);
-    flex-shrink: 0;
-    white-space: nowrap;
+  .mobileChevron {
+    display: block;
+    margin-left: auto;
+    font-size: 1.1rem;
+    opacity: 0.7;
+    color: var(--ifm-color-primary);
+  }
+
+  .noteCard:active {
+    transform: scale(0.98);
+    background-color: var(--ifm-hover-overlay);
   }
 }
 
+/* Accessibility */
 @media (prefers-reduced-motion: reduce) {
   .noteCard {
-    animation: none !important;
+    animation: none;
     opacity: 1;
-    transition: none !important;
-  }
-
-  .noteIcon {
-    transition: none !important;
+    transition: none;
   }
 }

package/src/theme/components/Preview/components/FeedbackStates.js

@@ -6,7 +6,9 @@ import styles from "../styles.module.css";
 export function LoadingState() {
   return (
     <div className={styles.loading}>
-      <div className={styles.spinner} />
+      <div className={styles.loadingIcon}>
+        <div className={styles.spinner} />
+      </div>
       <div className={styles.loadingText}>
         <p>Preparing preview...</p>
         <span>Fetching content from source</span>

package/src/theme/components/Preview/components/PreviewContent.js

@@ -0,0 +1,91 @@
+import React from "react";
+import styles from "../styles.module.css";
+import { LoadingState, ErrorState, OfflineState } from "./FeedbackStates";
+import ImageRenderer from "../renderers/ImageRenderer";
+import PdfRenderer from "../renderers/PdfRenderer";
+import WebRenderer from "../renderers/WebRenderer";
+import CodeRenderer from "../renderers/CodeRenderer";
+
+/**
+ * Component that routes to the appropriate renderer based on file type.
+ * Also handles shared loading, error, and offline states.
+ */
+export default function PreviewContent({
+  currentFile,
+  fileType,
+  fileUrl,
+  isOnline,
+  fetchErrors,
+  textLoading,
+  textContent,
+  zoomLevel,
+  ext,
+  retryFetch,
+  setError,
+}) {
+  const path = currentFile?.path;
+  const isExternal = path?.startsWith("http") || path?.startsWith("//");
+
+  // 1. Offline guard for external resources
+  if (!isOnline && isExternal) {
+    return <OfflineState onRetry={retryFetch} />;
+  }
+
+  // 2. Error state
+  const errorMsg = fetchErrors?.[path];
+  if (errorMsg) {
+    return (
+      <ErrorState
+        path={path}
+        message={errorMsg}
+        fileType={fileType}
+        fileUrl={fileUrl}
+        onRetry={retryFetch}
+      />
+    );
+  }
+
+  // 3. Loading state (for text files only — specialized renderers handle their own loading)
+  if (textLoading && fileType === "text") {
+    return <LoadingState />;
+  }
+
+  // 4. Feature-specific renderers
+  switch (fileType) {
+    case "image":
+      return (
+        <ImageRenderer
+          key={fileUrl}
+          fileUrl={fileUrl}
+          label={currentFile.label}
+          zoomLevel={zoomLevel}
+          onError={(msg) => setError(path, msg)}
+        />
+      );
+    case "pdf":
+      return (
+        <PdfRenderer
+          key={fileUrl}
+          fileUrl={fileUrl}
+          zoomLevel={zoomLevel}
+          onError={(msg) => setError(path, msg)}
+        />
+      );
+    case "web":
+      return (
+        <WebRenderer
+          key={fileUrl}
+          fileUrl={fileUrl}
+          label={currentFile.label}
+          onError={(msg) => setError(path, msg)}
+        />
+      );
+    default: {
+      // Text / code
+      if (!textContent) return <LoadingState />;
+      return (
+        <CodeRenderer code={textContent} language={ext} zoomLevel={zoomLevel} />
+      );
+    }
+  }
+}