@marlinjai/clearify 1.5.2 → 1.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marlinjai/clearify",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "An open-source documentation site generator. Turn markdown into beautiful docs.",
   "type": "module",
   "bin": {

package/src/theme/Sidebar.tsx

@@ -38,6 +38,14 @@ function findActiveSection(pathname: string, sections: SectionNavigation[]): str
   return bestMatch;
 }
 
+function collectGroupKeys(items: NavigationItem[], prefix = ''): string[] {
+  return items.flatMap((item) => {
+    if (!item.children) return [];
+    const key = prefix ? `${prefix}/${item.label}` : item.label;
+    return [key, ...collectGroupKeys(item.children, key)];
+  });
+}
+
 function SectionSwitcher({
   sections,
   activeId,
@@ -121,6 +129,32 @@ export function Sidebar({ sections, open, onClose }: SidebarProps) {
   const navigation = legacyNavigation ?? activeSection?.navigation ?? [];
   const showSwitcher = isSectionData && sections.length > 1;
 
+  // Centralized expansion state
+  const [expandedGroups, setExpandedGroups] = useState<Set<string>>(() => new Set(collectGroupKeys(navigation)));
+
+  // Re-expand all when section changes
+  useEffect(() => {
+    setExpandedGroups(new Set(collectGroupKeys(navigation)));
+  }, [selectedSectionId]);
+
+  const allGroupKeys = collectGroupKeys(navigation);
+  const hasCollapsibleGroups = allGroupKeys.length >= 2;
+
+  const handleToggleGroup = (key: string) => {
+    setExpandedGroups((prev) => {
+      const next = new Set(prev);
+      if (next.has(key)) {
+        next.delete(key);
+      } else {
+        next.add(key);
+      }
+      return next;
+    });
+  };
+
+  const handleExpandAll = () => setExpandedGroups(new Set(allGroupKeys));
+  const handleCollapseAll = () => setExpandedGroups(new Set());
+
   return (
     <>
       {/* Mobile overlay */}
@@ -163,9 +197,86 @@ export function Sidebar({ sections, open, onClose }: SidebarProps) {
             onSelect={setSelectedSectionId}
           />
         )}
+        {hasCollapsibleGroups && (
+          <div style={{
+            display: 'flex',
+            justifyContent: 'flex-end',
+            gap: '0.25rem',
+            padding: '0.25rem 0.75rem',
+          }}>
+            <button
+              onClick={handleExpandAll}
+              title="Expand all groups"
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                width: 24,
+                height: 24,
+                background: 'none',
+                border: 'none',
+                cursor: 'pointer',
+                color: 'var(--clearify-text-tertiary)',
+                borderRadius: 'var(--clearify-radius-sm)',
+                transition: 'color 0.15s, background-color 0.15s',
+              }}
+              onMouseEnter={(e) => {
+                e.currentTarget.style.color = 'var(--clearify-text-secondary)';
+                e.currentTarget.style.backgroundColor = 'var(--clearify-bg-secondary)';
+              }}
+              onMouseLeave={(e) => {
+                e.currentTarget.style.color = 'var(--clearify-text-tertiary)';
+                e.currentTarget.style.backgroundColor = 'transparent';
+              }}
+            >
+              <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                <polyline points="7 8 12 3 17 8" />
+                <polyline points="7 16 12 21 17 16" />
+              </svg>
+            </button>
+            <button
+              onClick={handleCollapseAll}
+              title="Collapse all groups"
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                width: 24,
+                height: 24,
+                background: 'none',
+                border: 'none',
+                cursor: 'pointer',
+                color: 'var(--clearify-text-tertiary)',
+                borderRadius: 'var(--clearify-radius-sm)',
+                transition: 'color 0.15s, background-color 0.15s',
+              }}
+              onMouseEnter={(e) => {
+                e.currentTarget.style.color = 'var(--clearify-text-secondary)';
+                e.currentTarget.style.backgroundColor = 'var(--clearify-bg-secondary)';
+              }}
+              onMouseLeave={(e) => {
+                e.currentTarget.style.color = 'var(--clearify-text-tertiary)';
+                e.currentTarget.style.backgroundColor = 'transparent';
+              }}
+            >
+              <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                <polyline points="7 3 12 8 17 3" />
+                <polyline points="7 21 12 16 17 21" />
+              </svg>
+            </button>
+          </div>
+        )}
         <nav style={{ padding: '0 0.5rem' }}>
           {navigation.map((item, i) => (
-            <NavItem key={i} item={item} depth={0} onNavigate={onClose} />
+            <NavItem
+              key={i}
+              item={item}
+              depth={0}
+              onNavigate={onClose}
+              expandedGroups={expandedGroups}
+              onToggleGroup={handleToggleGroup}
+              groupKeyPrefix=""
+            />
           ))}
         </nav>
       </aside>
@@ -193,16 +304,27 @@ export function Sidebar({ sections, open, onClose }: SidebarProps) {
   );
 }
 
-function NavItem({ item, depth, onNavigate }: { item: NavigationItem; depth: number; onNavigate: () => void }) {
+interface NavItemProps {
+  item: NavigationItem;
+  depth: number;
+  onNavigate: () => void;
+  expandedGroups: Set<string>;
+  onToggleGroup: (key: string) => void;
+  groupKeyPrefix: string;
+}
+
+function NavItem({ item, depth, onNavigate, expandedGroups, onToggleGroup, groupKeyPrefix }: NavItemProps) {
   const location = useLocation();
-  const [expanded, setExpanded] = useState(true);
   const isActive = item.path === location.pathname;
 
   if (item.children) {
+    const groupKey = groupKeyPrefix ? `${groupKeyPrefix}/${item.label}` : item.label;
+    const expanded = expandedGroups.has(groupKey);
+
     return (
       <div style={{ marginBottom: '0.125rem' }}>
         <button
-          onClick={() => setExpanded(!expanded)}
+          onClick={() => onToggleGroup(groupKey)}
           style={{
             display: 'flex',
             alignItems: 'center',
@@ -246,7 +368,15 @@ function NavItem({ item, depth, onNavigate }: { item: NavigationItem; depth: num
         {expanded && (
           <div style={{ animation: 'clearify-fade-in 0.15s ease-out' }}>
             {item.children.map((child, i) => (
-              <NavItem key={i} item={child} depth={depth + 1} onNavigate={onNavigate} />
+              <NavItem
+                key={i}
+                item={child}
+                depth={depth + 1}
+                onNavigate={onNavigate}
+                expandedGroups={expandedGroups}
+                onToggleGroup={onToggleGroup}
+                groupKeyPrefix={groupKey}
+              />
             ))}
           </div>
         )}

package/src/theme/components/OpenAPI.tsx

@@ -42,8 +42,7 @@ export function OpenAPI({
 
   const configuration = useMemo(() => {
     const config: Record<string, unknown> = {
-      // Use 'none' theme so Clearify's CSS variable bridge takes full control
-      theme: 'none',
+      theme: 'default',
       forceDarkModeState: theme === 'dark' ? 'dark' : 'light',
       hideDarkModeToggle,
       showSidebar: !hideSidebar,
@@ -130,6 +129,7 @@ export function OpenAPI({
 
 /** Custom CSS to integrate Scalar with Clearify's design tokens */
 const SCALAR_CUSTOM_CSS = `
+  /* ── Design Token Bridge ── */
   .scalar-app {
     --scalar-font: var(--font-sans);
     --scalar-font-code: var(--font-mono);
@@ -139,22 +139,335 @@ const SCALAR_CUSTOM_CSS = `
     --scalar-color-3: var(--clearify-text-tertiary);
 
     --scalar-color-accent: var(--clearify-primary);
+    --scalar-background-accent: rgba(99, 102, 241, 0.08);
 
     --scalar-background-1: var(--clearify-bg);
     --scalar-background-2: var(--clearify-bg-secondary);
     --scalar-background-3: var(--clearify-bg-tertiary);
+    --scalar-background-4: var(--clearify-bg-tertiary);
 
     --scalar-border-color: var(--clearify-border-strong);
+    --scalar-border-width: 1px;
 
     --scalar-radius: var(--clearify-radius-sm);
     --scalar-radius-lg: var(--clearify-radius);
+    --scalar-radius-xl: var(--clearify-radius-lg);
 
     --scalar-shadow-1: var(--clearify-shadow-sm);
     --scalar-shadow-2: var(--clearify-shadow);
+
+    --scalar-link-color: var(--clearify-primary);
+    --scalar-link-color-hover: var(--clearify-primary-hover);
+    --scalar-text-decoration: none;
+    --scalar-text-decoration-hover: underline;
+
+    --scalar-scrollbar-color: var(--clearify-border-strong);
+    --scalar-scrollbar-color-active: var(--clearify-text-tertiary);
+
+    --scalar-color-green: #059669;
+    --scalar-color-blue: #2563eb;
+    --scalar-color-orange: #d97706;
+    --scalar-color-red: #dc2626;
+    --scalar-color-purple: #7c3aed;
+    --scalar-color-yellow: #ca8a04;
   }
 
+  .dark-mode .scalar-app,
+  .dark .scalar-app {
+    --scalar-background-accent: rgba(129, 140, 248, 0.1);
+    --scalar-color-green: #34d399;
+    --scalar-color-blue: #60a5fa;
+    --scalar-color-orange: #fbbf24;
+    --scalar-color-red: #f87171;
+    --scalar-color-purple: #a78bfa;
+    --scalar-color-yellow: #facc15;
+  }
+
+  /* ── Layout ── */
   .scalar-app .section {
     padding-left: 0;
     padding-right: 0;
   }
+
+  .scalar-app .references-layout {
+    --refs-content-max-width: 100%;
+  }
+
+  /* ── Introduction Card ── */
+  .scalar-app .introduction-card {
+    border: 1px solid var(--clearify-border);
+    border-radius: var(--clearify-radius);
+    background: var(--clearify-bg-secondary);
+    overflow: hidden;
+  }
+
+  /* ── Section Headers ── */
+  .scalar-app .section-header {
+    font-family: var(--font-sans);
+    letter-spacing: -0.01em;
+  }
+
+  /* ── Endpoint Cards ── */
+  .scalar-app .section-accordion {
+    border: 1px solid var(--clearify-border);
+    border-radius: var(--clearify-radius);
+    overflow: hidden;
+    transition: border-color 0.2s ease, box-shadow 0.2s ease;
+  }
+
+  .scalar-app .section-accordion:hover {
+    border-color: var(--clearify-border-strong);
+    box-shadow: var(--clearify-shadow-sm);
+  }
+
+  .scalar-app .section-accordion-content-card {
+    border-radius: var(--clearify-radius);
+  }
+
+  /* ── Method Badges ── */
+  .scalar-app .endpoint-method {
+    font-family: var(--font-mono);
+    font-size: 0.6875rem;
+    font-weight: 700;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    padding: 0.15rem 0.5rem;
+    border-radius: 4px;
+    line-height: 1.5;
+  }
+
+  .scalar-app .endpoint-method.get {
+    background: rgba(5, 150, 105, 0.12);
+    color: var(--scalar-color-green);
+  }
+  .scalar-app .endpoint-method.post {
+    background: rgba(37, 99, 235, 0.12);
+    color: var(--scalar-color-blue);
+  }
+  .scalar-app .endpoint-method.put {
+    background: rgba(217, 119, 6, 0.12);
+    color: var(--scalar-color-orange);
+  }
+  .scalar-app .endpoint-method.delete {
+    background: rgba(220, 38, 38, 0.12);
+    color: var(--scalar-color-red);
+  }
+  .scalar-app .endpoint-method.patch {
+    background: rgba(124, 58, 237, 0.12);
+    color: var(--scalar-color-purple);
+  }
+
+  /* ── Endpoint Paths ── */
+  .scalar-app .endpoint-path,
+  .scalar-app .endpoint-label-path {
+    font-family: var(--font-mono);
+    font-size: 0.8125rem;
+    letter-spacing: -0.01em;
+  }
+
+  /* ── Request / Response Cards ── */
+  .scalar-app .scalar-card {
+    border: 1px solid var(--clearify-border);
+    border-radius: var(--clearify-radius);
+    overflow: hidden;
+  }
+
+  .scalar-app .scalar-card-header {
+    background: var(--clearify-bg-secondary);
+    border-bottom: 1px solid var(--clearify-border);
+  }
+
+  .scalar-app .scalar-card-header-tabs button {
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    font-weight: 500;
+    letter-spacing: 0.02em;
+    transition: color 0.15s ease, background-color 0.15s ease;
+    border-radius: var(--clearify-radius-sm);
+  }
+
+  /* ── Code Blocks ── */
+  .scalar-app .scalar-codeblock-pre,
+  .scalar-app .cm-editor {
+    font-family: var(--font-mono);
+    font-size: 0.8125rem;
+    line-height: 1.7;
+    border-radius: var(--clearify-radius);
+  }
+
+  .scalar-app .scalar-code-block {
+    border: 1px solid var(--clearify-border);
+    border-radius: var(--clearify-radius);
+    overflow: hidden;
+  }
+
+  .scalar-app .scalar-code-copy {
+    border-radius: var(--clearify-radius-sm);
+    opacity: 0;
+    transition: opacity 0.15s ease;
+  }
+
+  .scalar-app .scalar-code-block:hover .scalar-code-copy {
+    opacity: 1;
+  }
+
+  /* ── Parameters ── */
+  .scalar-app .parameter-item {
+    border-bottom: 1px solid var(--clearify-border);
+    transition: background-color 0.15s ease;
+  }
+
+  .scalar-app .parameter-item:last-child {
+    border-bottom: none;
+  }
+
+  .scalar-app .parameter-item:hover {
+    background-color: var(--clearify-bg-secondary);
+  }
+
+  .scalar-app .parameter-item-name {
+    font-family: var(--font-mono);
+    font-size: 0.8125rem;
+    font-weight: 600;
+  }
+
+  .scalar-app .parameter-item--required .parameter-item-required-optional {
+    color: var(--scalar-color-orange);
+    font-size: 0.6875rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+  }
+
+  /* ── Schema / Properties ── */
+  .scalar-app .schema-card {
+    border: 1px solid var(--clearify-border);
+    border-radius: var(--clearify-radius);
+    overflow: hidden;
+  }
+
+  .scalar-app .property-name {
+    font-family: var(--font-mono);
+    font-size: 0.8125rem;
+    font-weight: 500;
+  }
+
+  .scalar-app .property-required {
+    color: var(--scalar-color-orange);
+    font-size: 0.6875rem;
+    font-weight: 600;
+  }
+
+  .scalar-app .property-read-only {
+    color: var(--scalar-color-blue);
+    font-size: 0.6875rem;
+  }
+
+  .scalar-app .property-write-only {
+    color: var(--scalar-color-green);
+    font-size: 0.6875rem;
+  }
+
+  .scalar-app .schema-type {
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    color: var(--clearify-text-tertiary);
+  }
+
+  .scalar-app .property-enum-value {
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    background: var(--clearify-bg-secondary);
+    border: 1px solid var(--clearify-border);
+    border-radius: 4px;
+    padding: 0.1rem 0.4rem;
+  }
+
+  /* ── Client Libraries ── */
+  .scalar-app .client-libraries-icon {
+    max-width: 48px;
+    max-height: 48px;
+  }
+
+  .scalar-app .client-libraries {
+    border: 1px solid var(--clearify-border);
+    border-radius: var(--clearify-radius);
+  }
+
+  /* ── Buttons ── */
+  .scalar-app .scalar-button {
+    border-radius: var(--clearify-radius-sm);
+    font-weight: 500;
+    font-size: 0.8125rem;
+    transition: all 0.15s ease;
+  }
+
+  /* ── Tooltips ── */
+  .scalar-app .scalar-tooltip {
+    font-size: 0.75rem;
+    border-radius: var(--clearify-radius-sm);
+  }
+
+  /* ── Auth Section ── */
+  .scalar-app .security-scheme-label {
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    border-radius: 4px;
+  }
+
+  /* ── Smooth Transitions ── */
+  .scalar-app .section-accordion-content {
+    animation: clearify-fade-in 0.2s ease-out;
+  }
+
+  .scalar-app .section-accordion-chevron {
+    transition: transform 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+  }
+
+  /* ── Server & Auth Intro Cards ── */
+  .scalar-app .introduction-card-item {
+    border-bottom: 1px solid var(--clearify-border);
+  }
+
+  .scalar-app .introduction-card-item:last-child {
+    border-bottom: none;
+  }
+
+  /* ── Operation Details ── */
+  .scalar-app .operation-details-card {
+    border: 1px solid var(--clearify-border);
+    border-radius: var(--clearify-radius);
+    overflow: hidden;
+  }
+
+  /* ── Try It / Request Editor ── */
+  .scalar-app .request-card {
+    border: 1px solid var(--clearify-border);
+    border-radius: var(--clearify-radius);
+    overflow: hidden;
+  }
+
+  .scalar-app .response-card {
+    border: 1px solid var(--clearify-border);
+    border-radius: var(--clearify-radius);
+    overflow: hidden;
+  }
+
+  /* ── Sidebar (when visible) ── */
+  .scalar-app {
+    --scalar-sidebar-background-1: var(--clearify-bg);
+    --scalar-sidebar-color-1: var(--clearify-text);
+    --scalar-sidebar-color-2: var(--clearify-text-secondary);
+    --scalar-sidebar-color-active: var(--clearify-primary);
+    --scalar-sidebar-border-color: var(--clearify-border);
+    --scalar-sidebar-item-hover-background: var(--clearify-bg-secondary);
+    --scalar-sidebar-item-active-background: var(--clearify-primary-soft);
+  }
+
+  /* ── Syntax Highlighting ── */
+  .scalar-app .hljs-keyword { color: var(--clearify-primary); }
+  .scalar-app .hljs-string { color: var(--scalar-color-green); }
+  .scalar-app .hljs-number { color: var(--scalar-color-orange); }
+  .scalar-app .hljs-attr { color: var(--scalar-color-blue); }
+  .scalar-app .hljs-comment { color: var(--clearify-text-tertiary); font-style: italic; }
 `;

package/src/theme/components/OpenAPIPage.tsx

@@ -7,7 +7,7 @@ import openapiSpec from 'virtual:clearify/openapi-spec';
 export default function OpenAPIPage() {
   const basePath = config.openapi?.basePath ?? '/api';
   return (
-    <div className="clearify-openapi-page" style={{ margin: '0 -1.5rem', maxWidth: 'none' }}>
+    <div className="clearify-openapi-page" style={{ maxWidth: 'none' }}>
       <OpenAPI spec={openapiSpec} hideSidebar={true} pathRouting={{ basePath }} />
     </div>
   );

package/src/theme/styles/globals.css

@@ -361,3 +361,131 @@ a:hover {
   0% { background-position: -200% 0; }
   100% { background-position: 200% 0; }
 }
+
+/* ─── OpenAPI container isolation ─── */
+/* Remove Content wrapper constraints when rendering API reference */
+.clearify-prose:has(.clearify-openapi-page) {
+  max-width: none !important;
+  padding-left: 0 !important;
+  padding-right: 0 !important;
+}
+
+/* Prevent clearify-prose typography and global styles from bleeding into Scalar */
+.clearify-openapi-container h1,
+.clearify-openapi-container h2,
+.clearify-openapi-container h3,
+.clearify-openapi-container h4 {
+  font-size: inherit;
+  font-weight: inherit;
+  margin: initial;
+  padding: initial;
+  line-height: inherit;
+  letter-spacing: normal;
+  color: inherit;
+  border-bottom: none;
+  text-transform: none;
+}
+
+.clearify-openapi-container p {
+  margin: initial;
+  color: inherit;
+}
+
+.clearify-openapi-container ul,
+.clearify-openapi-container ol {
+  margin: initial;
+  padding: initial;
+  color: inherit;
+}
+
+.clearify-openapi-container li {
+  margin: initial;
+}
+
+.clearify-openapi-container img {
+  max-width: initial;
+  border-radius: initial;
+  border: initial;
+}
+
+.clearify-openapi-container code {
+  background-color: initial;
+  padding: initial;
+  border-radius: initial;
+  font-size: inherit;
+  font-family: inherit;
+  font-weight: inherit;
+  color: inherit;
+  border: initial;
+}
+
+.clearify-openapi-container pre {
+  background-color: initial;
+  border: initial;
+  border-radius: initial;
+  padding: initial;
+  overflow-x: initial;
+  margin: initial;
+  font-size: inherit;
+  line-height: inherit;
+  font-family: inherit;
+}
+
+.clearify-openapi-container table {
+  width: initial;
+  border-collapse: initial;
+  border-spacing: initial;
+  margin: initial;
+  font-size: inherit;
+  border-radius: initial;
+  overflow: initial;
+  border: initial;
+}
+
+.clearify-openapi-container th,
+.clearify-openapi-container td {
+  padding: initial;
+  text-align: initial;
+  border-bottom: initial;
+}
+
+.clearify-openapi-container th {
+  background-color: initial;
+  font-weight: inherit;
+  font-size: inherit;
+  text-transform: initial;
+  letter-spacing: initial;
+  color: inherit;
+}
+
+.clearify-openapi-container strong {
+  font-weight: inherit;
+  color: inherit;
+}
+
+.clearify-openapi-container blockquote {
+  border-left: initial;
+  padding: initial;
+  color: inherit;
+  margin: initial;
+  background: initial;
+  border-radius: initial;
+  font-style: initial;
+}
+
+.clearify-openapi-container hr {
+  border: initial;
+  border-top: initial;
+  margin: initial;
+}
+
+.clearify-openapi-container a {
+  color: inherit;
+  text-decoration: initial;
+  transition: initial;
+}
+
+.clearify-openapi-container a:hover {
+  color: inherit;
+  text-decoration: initial;
+}