@knitli/docs-components 1.0.3 → 1.1.0

package/src/components/DocsHeader.astro

@@ -1,231 +1,8 @@
 ---
-// Custom header with actual Knitli logo
-const { pathname } = Astro.url;
-
-// Environment-aware URL configuration
-const isDev = import.meta.env.DEV;
-
-const getSiteUrls = () => {
-  if (isDev) {
-    return {
-      marketing: import.meta.env.PUBLIC_MARKETING_URL || 'http://localhost:4321',
-      blog: import.meta.env.PUBLIC_BLOG_URL || 'http://localhost:4322',
-      docs: import.meta.env.PUBLIC_DOCS_URL || 'http://localhost:4323',
-    };
-  }
-
-  return {
-    marketing: 'https://knitli.com',
-    blog: 'https://blog.knitli.com',
-    docs: 'https://docs.knitli.com',
-  };
-};
-
-const urls = getSiteUrls();
-const isDocsHome = pathname === '/' || pathname === '';
-const shouldShowBreadcrumb = !isDocsHome;
-
+// DEPRECATED — This component has been removed.
+// Use PageFrame.astro instead:
+//   starlight({ components: { PageFrame: '@knitli/docs-components/PageFrame.astro' } })
+throw new Error(
+  '@knitli/docs-components: DocsHeader has been removed. Use PageFrame.astro instead.'
+);
 ---
-
-<header class="docs-header">
-  <div class="docs-header-content">
-    <!-- Knitli Logo + Docs Section -->
-    <a href={urls.marketing} class="docs-logo" aria-label="Knitli home">
-      <img src={`${import.meta.env.BASE_URL}/knitli-logo.svg`} alt="Knitli" class="logo-icon" />
-      <span class="logo-text">
-        <span class="logo-separator">/</span>
-        <span class="logo-section">docs</span>
-      </span>
-    </a>
-
-    <!-- Breadcrumb -->
-    {shouldShowBreadcrumb && (
-      <nav class="docs-breadcrumb" aria-label="Breadcrumb">
-        <a href="/">Documentation</a>
-        <span class="breadcrumb-separator" aria-hidden="true">→</span>
-        <a href="/ReCoco" class="breadcrumb-product">
-          ReCoco
-        </a>
-      </nav>
-    )}
-
-    <div class="spacer"></div>
-
-    <!-- Cross-site Navigation -->
-    <nav class="docs-nav" aria-label="Site navigation">
-      <a
-        href="/"
-        class:list={[{ active: isDocsHome }]}
-        aria-current={isDocsHome ? 'page' : undefined}
-      >
-        Docs Home
-      </a>
-      <a href={urls.marketing}>
-        Main Site
-      </a>
-      <a href={urls.blog}>
-        Blog
-      </a>
-      <a
-        href="https://github.com/knitli"
-        class="external"
-        target="_blank"
-        rel="noopener noreferrer"
-        aria-label="Knitli on GitHub (opens in new tab)"
-      >
-        GitHub
-        <span class="external-icon" aria-hidden="true">↗</span>
-      </a>
-    </nav>
-  </div>
-</header>
-
-<style>
-  .docs-header {
-    background: white;
-    border-bottom: 1px solid #e5e7eb;
-    border-radius: 0 0 6px 2px; /* Chamfered bottom corners only */
-    position: sticky;
-    top: 0;
-    z-index: 100;
-  }
-
-  .docs-header-content {
-    max-width: 1400px;
-    margin: 0 auto;
-    padding: 1rem 2rem;
-    display: flex;
-    align-items: center;
-    gap: 2rem;
-  }
-
-  .docs-logo {
-    display: flex;
-    align-items: center;
-    gap: 0.5rem;
-    text-decoration: none;
-    transition: opacity 0.2s ease;
-  }
-
-  .docs-logo:hover {
-    opacity: 0.8;
-  }
-
-  .logo-icon {
-    height: 32px;
-    width: auto;
-    flex-shrink: 0;
-  }
-
-  .logo-text {
-    font-family: system-ui, -apple-system, sans-serif;
-    font-size: 1.125rem;
-    font-weight: 600;
-    line-height: 1;
-    color: #374151;
-  }
-
-  .logo-separator {
-    color: #9ca3af;
-    margin: 0 0.5rem;
-  }
-
-  .logo-section {
-    color: #6b7280;
-  }
-
-  .docs-breadcrumb {
-    display: flex;
-    align-items: center;
-    align-self: flex-end;
-    gap: 0.5rem;
-    font-size: 0.875rem;
-    color: #6b7280;
-  }
-
-  .docs-breadcrumb a {
-    color: inherit;
-    text-decoration: none;
-    transition: color 0.2s ease;
-  }
-
-  .docs-breadcrumb a:hover {
-    color: #111827;
-    text-decoration: underline;
-  }
-
-  .breadcrumb-separator {
-    opacity: 0.5;
-  }
-
-  .breadcrumb-product {
-    font-weight: 500;
-    color: #111827;
-  }
-
-  .spacer {
-    flex: 1;
-  }
-
-  .docs-nav {
-    display: flex;
-    gap: 2rem;
-    align-items: center;
-  }
-
-  .docs-nav a {
-    font-size: 0.9375rem;
-    color: #374151;
-    text-decoration: none;
-    position: relative;
-    padding: 0.25rem 0;
-    transition: color 0.2s ease;
-  }
-
-  .docs-nav a:hover {
-    color: #111827;
-  }
-
-  .docs-nav a.active {
-    color: #111827;
-    font-weight: 500;
-  }
-
-  .docs-nav a.external {
-    display: inline-flex;
-    align-items: center;
-    gap: 0.25rem;
-  }
-
-  .external-icon {
-    font-size: 0.75em;
-    opacity: 0.6;
-  }
-
-  /* Mobile Responsive */
-  @media (max-width: 768px) {
-    .docs-header-content {
-      flex-wrap: wrap;
-      padding: 1rem;
-      gap: 1rem;
-    }
-
-    .docs-breadcrumb {
-      order: 3;
-      width: 100%;
-    }
-
-    .spacer {
-      display: none;
-    }
-
-    .docs-nav {
-      gap: 1rem;
-      font-size: 0.875rem;
-    }
-
-    .logo-icon {
-      height: 28px;
-    }
-  }
-</style>

package/src/components/Footer.astro

@@ -0,0 +1,244 @@
+---
+// SPDX-FileCopyrightText: 2025 Knitli Inc.
+// SPDX-FileContributor: Adam Poulemanos <adam@knit.li>
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Starlight Footer override for Knitli product documentation sites.
+// Renders Starlight's native page-level footer (edit link, last updated,
+// pagination, optional credits) followed by the Knitli site footer.
+//
+// Usage in astro.config.mjs:
+//   starlight({ components: { Footer: '@knitli/docs-components/Footer.astro' } })
+
+// @ts-expect-error: virtual modules are typed in virtual-internal.d.ts (not in Starlight's public exports map)
+import EditLink from 'virtual:starlight/components/EditLink';
+// @ts-expect-error
+import LastUpdated from 'virtual:starlight/components/LastUpdated';
+// @ts-expect-error
+import Pagination from 'virtual:starlight/components/Pagination';
+// @ts-expect-error
+import config from 'virtual:starlight/user-config';
+import { Icon } from '@astrojs/starlight/components';
+
+const currentYear = new Date().getFullYear();
+---
+
+<footer class="sl-flex knitli-page-footer">
+
+	<!-- Starlight's native page-level footer: edit link, last updated, pagination, optional credits -->
+	<div class="sl-flex page-actions">
+		<div class="meta sl-flex">
+			<EditLink />
+			<LastUpdated />
+		</div>
+		<Pagination />
+		{config.credits && (
+			<a class="kudos sl-flex" href="https://starlight.astro.build">
+				<Icon name="starlight" /> {Astro.locals.t('builtWithStarlight.label')}
+			</a>
+		)}
+	</div>
+
+	<!-- Knitli site footer -->
+	<div class="site-footer sl-flex">
+		<div class="footer-content sl-flex">
+
+			<div class="footer-brand">
+				<p class="copyright">© {currentYear} Knitli, Inc. All rights reserved.</p>
+				<div class="social-links sl-flex">
+					<a href="https://github.com/knitli" aria-label="GitHub" class="social-link" target="_blank" rel="noopener noreferrer">
+						<Icon name="github" size="1.1rem" />
+					</a>
+					<a href="https://x.com/knitli_inc" aria-label="X" class="social-link" target="_blank" rel="noopener noreferrer">
+						<Icon name="x.com" size="1.1rem" />
+					</a>
+					<a href="https://bsky.app/profile/knitli.com" aria-label="Bluesky" class="social-link" target="_blank" rel="noopener noreferrer">
+						<Icon name="blueSky" size="1.1rem" />
+					</a>
+					<a href="https://linkedin.com/company/knitli" aria-label="LinkedIn" class="social-link" target="_blank" rel="noopener noreferrer">
+						<Icon name="linkedin" size="1.1rem" />
+					</a>
+				</div>
+			</div>
+
+			<nav class="footer-nav" aria-label="Knitli">
+				<p class="nav-heading">Knitli</p>
+				<ul>
+					<li><a href="https://knitli.com">knitli.com</a></li>
+					<li><a href="https://blog.knitli.com">Blog</a></li>
+				</ul>
+			</nav>
+
+			<nav class="footer-nav" aria-label="Documentation">
+				<p class="nav-heading">Docs</p>
+				<ul>
+					<li><a href="https://docs.knitli.com">Developer Docs</a></li>
+					<li><a href="https://docs.knitli.com/ReCoco">ReCoco</a></li>
+					<li>
+						<span class="link-disabled">
+							CodeWeaver
+							<span class="soon-badge">soon</span>
+						</span>
+					</li>
+					<li>
+						<a href="https://docs.rs/thread" target="_blank" rel="noopener noreferrer">
+							Thread ↗
+						</a>
+					</li>
+				</ul>
+			</nav>
+
+		</div>
+	</div>
+
+</footer>
+
+<style>
+	@layer starlight.core {
+		/* ---- Outer wrapper ---- */
+		.knitli-page-footer {
+			flex-direction: column;
+			gap: 0;
+		}
+
+		/* ---- Starlight native page actions (replicated from Starlight's Footer) ---- */
+		.page-actions {
+			flex-direction: column;
+			gap: 1.5rem;
+		}
+
+		.meta {
+			gap: 0.75rem 3rem;
+			justify-content: space-between;
+			flex-wrap: wrap;
+			margin-top: 3rem;
+			font-size: var(--sl-text-sm);
+			color: var(--sl-color-gray-3);
+		}
+
+		.meta > :global(p:only-child) {
+			margin-inline-start: auto;
+		}
+
+		.kudos {
+			align-items: center;
+			gap: 0.5em;
+			margin: 1.5rem auto;
+			font-size: var(--sl-text-xs);
+			text-decoration: none;
+			color: var(--sl-color-gray-3);
+		}
+
+		.kudos:hover {
+			color: var(--sl-color-white);
+		}
+
+		/* ---- Knitli site footer ---- */
+		.site-footer {
+			flex-direction: column;
+			border-top: 1px solid var(--sl-color-gray-5);
+			padding-top: 2rem;
+			margin-top: 2rem;
+			gap: 1.5rem;
+		}
+
+		.footer-content {
+			flex-wrap: wrap;
+			gap: 2rem 4rem;
+			align-items: flex-start;
+		}
+
+		.footer-brand {
+			flex: 1;
+			min-width: 200px;
+			display: flex;
+			flex-direction: column;
+			gap: 0.75rem;
+		}
+
+		.copyright {
+			margin: 0;
+			font-size: var(--sl-text-sm);
+			color: var(--sl-color-gray-3);
+		}
+
+		.social-links {
+			gap: 0.75rem;
+			align-items: center;
+		}
+
+		.social-link {
+			display: flex;
+			align-items: center;
+			color: var(--sl-color-gray-3);
+			text-decoration: none;
+			transition: color 0.2s ease;
+		}
+
+		.social-link:hover {
+			color: var(--sl-color-accent-high);
+		}
+
+		.footer-nav {
+			display: flex;
+			flex-direction: column;
+			gap: 0.5rem;
+		}
+
+		.nav-heading {
+			margin: 0 0 0.5rem;
+			font-size: var(--sl-text-xs);
+			font-weight: 600;
+			text-transform: uppercase;
+			letter-spacing: 0.08em;
+			color: var(--sl-color-accent);
+		}
+
+		.footer-nav ul {
+			list-style: none;
+			padding: 0;
+			margin: 0;
+			display: flex;
+			flex-direction: column;
+			gap: 0.4rem;
+		}
+
+		.footer-nav a {
+			font-size: var(--sl-text-sm);
+			color: var(--sl-color-gray-2);
+			text-decoration: none;
+			transition: color 0.2s ease;
+		}
+
+		.footer-nav a:hover {
+			color: var(--sl-color-accent-high);
+		}
+
+		.link-disabled {
+			font-size: var(--sl-text-sm);
+			color: var(--sl-color-gray-4);
+			display: flex;
+			align-items: center;
+			gap: 0.4rem;
+		}
+
+		.soon-badge {
+			font-size: var(--sl-text-xs);
+			padding: 0.1em 0.4em;
+			border-radius: 3px;
+			background: var(--sl-color-accent-low);
+			color: var(--sl-color-accent-high);
+			font-weight: 600;
+			letter-spacing: 0.05em;
+			text-transform: uppercase;
+		}
+	}
+
+	@layer starlight.components {
+		/* Starlight icon color in the kudos link */
+		.kudos :global(svg) {
+			color: var(--sl-color-orange);
+		}
+	}
+</style>

package/src/components/PageFrame.astro

@@ -0,0 +1,189 @@
+---
+// SPDX-FileCopyrightText: 2025 Knitli Inc.
+// SPDX-FileContributor: Adam Poulemanos <adam@knit.li>
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Starlight PageFrame override for Knitli product documentation sites.
+// Adds the cross-site subnav bar (with breadcrumb) above the Starlight header.
+//
+// Usage in astro.config.mjs:
+//   starlight({ components: { PageFrame: '@knitli/docs-components/PageFrame.astro' } })
+//
+// Required env variable: PUBLIC_DOCS_PRODUCT = 'ReCoco' | 'CodeWeaver' | 'Thread'
+// The --sl-subnav-height CSS variable defaults to 2rem if not set in customCss.
+
+// @ts-expect-error: virtual:starlight/components/* are typed in virtual-internal.d.ts,
+// which is not in Starlight's public exports map
+import MobileMenuToggle from 'virtual:starlight/components/MobileMenuToggle';
+import DocsBreadcrumb from './DocsBreadcrumb.astro';
+
+const { hasSidebar } = Astro.locals.starlightRoute;
+
+const product = import.meta.env.PUBLIC_DOCS_PRODUCT as
+  | 'ReCoco'
+  | 'CodeWeaver'
+  | 'Thread'
+  | undefined;
+
+// Strip the configured base URL to get the within-product path for the breadcrumb.
+// e.g. for base='/ReCoco/' and pathname='/ReCoco/guide/start', path = 'guide/start'
+const basePath = (import.meta.env.BASE_URL ?? '/').replace(/\/?$/, '/');
+const currentPath = Astro.url.pathname
+  .slice(basePath.length)
+  .replace(/^\//, '');
+---
+
+<div class="page sl-flex">
+
+  <nav class="knitli-subnav sl-flex" aria-label="Knitli">
+    {product && (
+      <div class="subnav-breadcrumb">
+        <DocsBreadcrumb
+          product={product}
+          productUrl={basePath}
+          path={currentPath}
+          variant="inline"
+        />
+      </div>
+    )}
+    <div class="subnav-links sl-flex">
+      <a href="https://knitli.com" class="subnav-link">Knitli Home</a>
+      <a href="https://blog.knitli.com" class="subnav-link">Blog</a>
+    </div>
+  </nav>
+
+  <header class="header"><slot name="header" /></header>
+
+  {
+    hasSidebar && (
+      <nav class="sidebar print:hidden" aria-label={Astro.locals.t('sidebarNav.accessibleLabel')}>
+        <MobileMenuToggle />
+        <div id="starlight__sidebar" class="sidebar-pane">
+          <div class="sidebar-content sl-flex">
+            <slot name="sidebar" />
+          </div>
+        </div>
+      </nav>
+    )
+  }
+
+  <div class="main-frame"><slot /></div>
+</div>
+
+<style>
+  @layer starlight.core {
+    /* Replicated from Starlight's PageFrame — only positional values modified */
+    .page {
+      flex-direction: column;
+      min-height: 100vh;
+    }
+
+    .header {
+      z-index: var(--sl-z-index-navbar);
+      position: fixed;
+      inset-inline-start: 0;
+      inset-block-start: var(--sl-subnav-height, 2rem); /* offset below subnav */
+      width: 100%;
+      height: var(--sl-nav-height);
+      border-bottom: 1px solid var(--sl-color-hairline-shade);
+      padding: var(--sl-nav-pad-y) var(--sl-nav-pad-x);
+      padding-inline-end: var(--sl-nav-pad-x);
+      background-color: var(--sl-color-bg-nav);
+    }
+
+    :global([data-has-sidebar]) .header {
+      padding-inline-end: calc(
+        var(--sl-nav-gap) + var(--sl-nav-pad-x) + var(--sl-menu-button-size)
+      );
+    }
+
+    .sidebar-pane {
+      visibility: var(--sl-sidebar-visibility, hidden);
+      position: fixed;
+      z-index: var(--sl-z-index-menu);
+      inset-block: calc(var(--sl-nav-height) + var(--sl-subnav-height, 2rem)) 0;
+      inset-inline-start: 0;
+      width: 100%;
+      background-color: var(--sl-color-black);
+      overflow-y: auto;
+    }
+
+    :global([aria-expanded='true']) ~ .sidebar-pane {
+      --sl-sidebar-visibility: visible;
+    }
+
+    .sidebar-content {
+      height: 100%;
+      min-height: max-content;
+      padding: 1rem var(--sl-sidebar-pad-x) 0;
+      flex-direction: column;
+      gap: 1rem;
+    }
+
+    @media (min-width: 50rem) {
+      .sidebar-content::after {
+        content: '';
+        padding-bottom: 1px;
+      }
+    }
+
+    .main-frame {
+      padding-top: calc(
+        var(--sl-nav-height) + var(--sl-subnav-height, 2rem) + var(--sl-mobile-toc-height)
+      );
+      padding-inline-start: var(--sl-content-inline-start);
+    }
+
+    @media (min-width: 50rem) {
+      :global([data-has-sidebar]) .header {
+        padding-inline-end: var(--sl-nav-pad-x);
+      }
+      .sidebar-pane {
+        --sl-sidebar-visibility: visible;
+        width: var(--sl-sidebar-width);
+        background-color: var(--sl-color-bg-sidebar);
+        border-inline-end: 1px solid var(--sl-color-hairline-shade);
+      }
+    }
+
+    /* Knitli cross-site subnav */
+    .knitli-subnav {
+      position: fixed;
+      inset-block-start: 0;
+      inset-inline-start: 0;
+      width: 100%;
+      height: var(--sl-subnav-height, 2rem);
+      z-index: var(--sl-z-index-navbar);
+      background-color: var(--sl-color-bg-nav);
+      padding-inline: var(--sl-nav-pad-x);
+      justify-content: space-between;
+      align-items: center;
+      gap: 1rem;
+    }
+
+    .subnav-breadcrumb {
+      flex: 1;
+      min-width: 0; /* allows breadcrumb to shrink and truncate */
+      overflow: hidden;
+    }
+
+    .subnav-links {
+      gap: 1.25rem;
+      align-items: center;
+      flex-shrink: 0;
+    }
+
+    .subnav-link {
+      font-size: var(--sl-text-xs);
+      color: var(--sl-color-gray-3);
+      text-decoration: none;
+      transition: color 0.2s ease;
+      white-space: nowrap;
+    }
+
+    .subnav-link:hover {
+      color: var(--sl-color-white);
+    }
+  }
+</style>

package/src/styles/docs-theme.css

@@ -5,7 +5,8 @@
  */
 
 /* Import color palette and variables */
-@import "./variables.css";
+@import "@knitli/layouts/styles/variables.css";
+@import "@knitli/layouts/styles/textures.css";
 
 /* ========================================
    GOOGLE FONTS
@@ -24,7 +25,7 @@
 }
 
 html {
-  font-size: 16px;
+  font-size: var(--font-sm);
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
 }
@@ -32,8 +33,8 @@ html {
 body {
   margin: 0;
   padding: 0;
-  font-family: var(--font-docs-body);
-  font-size: var(--text-base);
+  font-family: var(--font-cw-body);
+  font-size: var(--font-base);
   line-height: var(--leading-normal);
   color: var(--docs-text-primary);
   background: var(--docs-parchment);