@knitli/docs-components 1.0.0

package/src/components/DocsBreadcrumb.astro

@@ -0,0 +1,154 @@
+---
+// SPDX-FileCopyrightText: 2025 Knitli Inc.
+// SPDX-FileContributor: Adam Poulemanos <adam@knit.li>
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Optional breadcrumb component for product-specific navigation
+
+interface Props {
+  product?: 'ReCoco' | 'CodeWeaver' | 'Thread';
+  productUrl?: string;
+  path?: string;
+  variant?: 'default' | 'compact';
+}
+
+const {
+  product,
+  productUrl = product ? `/${product}` : '',
+  path = '',
+  variant = 'default',
+} = Astro.props;
+
+// Parse path into segments for breadcrumb display
+const segments = path
+  .split('/')
+  .filter(Boolean)
+  .map((segment) => ({
+    name: segment.replace(/-/g, ' ').replace(/\b\w/g, (l) => l.toUpperCase()),
+    path: segment,
+  }));
+---
+
+{product && (
+  <nav
+    class:list={['docs-breadcrumb-nav', { compact: variant === 'compact' }]}
+    aria-label="Breadcrumb"
+  >
+    <ol class="breadcrumb-list">
+      <li class="breadcrumb-item">
+        <a href="/">Documentation</a>
+      </li>
+
+      <li class="breadcrumb-separator" aria-hidden="true">→</li>
+
+      <li class="breadcrumb-item">
+        {productUrl ? (
+          <a href={productUrl}>{product}</a>
+        ) : (
+          <span class="breadcrumb-current">{product}</span>
+        )}
+      </li>
+
+      {segments.map((segment, index) => (
+        <>
+          <li class="breadcrumb-separator" aria-hidden="true">→</li>
+          <li class="breadcrumb-item">
+            {index < segments.length - 1 ? (
+              <a href={`${productUrl}/${segments.slice(0, index + 1).map((s) => s.path).join('/')}`}>
+                {segment.name}
+              </a>
+            ) : (
+              <span class="breadcrumb-current" aria-current="page">
+                {segment.name}
+              </span>
+            )}
+          </li>
+        </>
+      ))}
+    </ol>
+  </nav>
+)}
+
+<style>
+  :root {
+    --docs-copper: oklch(0.58 0.08 50);
+    --docs-slate: oklch(0.35 0.02 240);
+    --docs-parchment: oklch(0.96 0.015 70);
+  }
+
+  .docs-breadcrumb-nav {
+    padding: 1rem 0;
+    font-family: "Inter", -apple-system, BlinkMacSystemFont, sans-serif;
+  }
+
+  .docs-breadcrumb-nav.compact {
+    padding: 0.5rem 0;
+  }
+
+  .breadcrumb-list {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.5rem;
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  .breadcrumb-item {
+    font-size: 0.875rem;
+  }
+
+  .breadcrumb-item a {
+    color: var(--docs-slate);
+    text-decoration: none;
+    opacity: 0.7;
+    transition: all 0.2s ease;
+  }
+
+  .breadcrumb-item a:hover {
+    opacity: 1;
+    text-decoration: underline;
+    color: var(--docs-copper);
+  }
+
+  .breadcrumb-current {
+    color: var(--docs-slate);
+    font-weight: 500;
+  }
+
+  .breadcrumb-separator {
+    color: var(--docs-slate);
+    opacity: 0.4;
+    font-size: 0.875rem;
+  }
+
+  /* Mobile Responsive */
+  @media (max-width: 768px) {
+    .breadcrumb-list {
+      gap: 0.375rem;
+      font-size: 0.8125rem;
+    }
+
+    .breadcrumb-item,
+    .breadcrumb-separator {
+      font-size: 0.8125rem;
+    }
+  }
+
+  /* Accessibility */
+  .breadcrumb-item a:focus-visible {
+    outline: 3px solid var(--docs-copper);
+    outline-offset: 4px;
+    border-radius: 4px;
+  }
+
+  /* Reduced motion */
+  @media (prefers-reduced-motion: reduce) {
+    * {
+      animation-duration: 0.01ms !important;
+      transition-duration: 0.01ms !important;
+    }
+  }
+</style>

package/src/components/DocsFooter.astro

@@ -0,0 +1,181 @@
+---
+// SPDX-FileCopyrightText: 2025 Knitli Inc.
+// SPDX-FileContributor: Adam Poulemanos <adam@knit.li>
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Simple footer for Knitli documentation sites
+
+interface Props {
+  variant?: 'default' | 'minimal';
+}
+
+const { variant = 'default' } = Astro.props;
+
+// 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 currentYear = new Date().getFullYear();
+---
+
+<footer class:list={['docs-footer', { minimal: variant === 'minimal' }]}>
+  <div class="footer-content">
+    {variant === 'default' && (
+      <nav class="footer-nav" aria-label="Footer navigation">
+        <a href={urls.marketing}>Main Site</a>
+        <a href={urls.blog}>Blog</a>
+        <a href="https://github.com/knitli" target="_blank" rel="noopener noreferrer">
+          GitHub
+        </a>
+        <a href={`${urls.marketing}/privacy`}>Privacy</a>
+      </nav>
+    )}
+
+    <div class="footer-legal">
+      <p class="copyright">
+        © {currentYear} <a href={urls.marketing}>Knitli Inc.</a> All rights reserved.
+      </p>
+      {variant === 'default' && (
+        <p class="license">
+          Documentation licensed under{' '}
+          <a
+            href="https://github.com/knitli/knitli-site/blob/main/LICENSE"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            MIT OR Apache-2.0
+          </a>
+        </p>
+      )}
+    </div>
+  </div>
+</footer>
+
+<style>
+  :root {
+    --docs-copper: oklch(0.58 0.08 50);
+    --docs-slate: oklch(0.35 0.02 240);
+    --docs-parchment: oklch(0.96 0.015 70);
+  }
+
+  .docs-footer {
+    background: var(--docs-parchment);
+    border-top: 1px solid oklch(0.85 0.01 50);
+    margin-top: 4rem;
+    padding: 2rem 0;
+  }
+
+  .docs-footer.minimal {
+    margin-top: 2rem;
+    padding: 1rem 0;
+  }
+
+  .footer-content {
+    max-width: 1400px;
+    margin: 0 auto;
+    padding: 0 2rem;
+    display: flex;
+    flex-direction: column;
+    gap: 1.5rem;
+    align-items: center;
+  }
+
+  .footer-nav {
+    display: flex;
+    gap: 2rem;
+    align-items: center;
+    flex-wrap: wrap;
+    justify-content: center;
+  }
+
+  .footer-nav a {
+    font-family: "Inter", -apple-system, BlinkMacSystemFont, sans-serif;
+    font-size: 0.875rem;
+    color: var(--docs-slate);
+    text-decoration: none;
+    transition: color 0.2s ease;
+  }
+
+  .footer-nav a:hover {
+    color: var(--docs-copper);
+  }
+
+  .footer-legal {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+    text-align: center;
+  }
+
+  .copyright,
+  .license {
+    font-family: "Inter", -apple-system, BlinkMacSystemFont, sans-serif;
+    font-size: 0.8125rem;
+    color: var(--docs-slate);
+    opacity: 0.7;
+    margin: 0;
+  }
+
+  .copyright a,
+  .license a {
+    color: inherit;
+    text-decoration: none;
+    transition: opacity 0.2s ease;
+  }
+
+  .copyright a:hover,
+  .license a:hover {
+    opacity: 1;
+    text-decoration: underline;
+  }
+
+  /* Mobile Responsive */
+  @media (max-width: 768px) {
+    .footer-content {
+      padding: 0 1rem;
+    }
+
+    .footer-nav {
+      gap: 1rem;
+      flex-direction: column;
+    }
+
+    .footer-legal {
+      font-size: 0.75rem;
+    }
+  }
+
+  /* Accessibility */
+  .footer-nav a:focus-visible,
+  .copyright a:focus-visible,
+  .license a:focus-visible {
+    outline: 3px solid var(--docs-copper);
+    outline-offset: 4px;
+    border-radius: 4px;
+  }
+
+  /* Reduced motion */
+  @media (prefers-reduced-motion: reduce) {
+    * {
+      animation-duration: 0.01ms !important;
+      transition-duration: 0.01ms !important;
+    }
+  }
+</style>

package/src/components/DocsHeader.astro

@@ -0,0 +1,328 @@
+---
+// SPDX-FileCopyrightText: 2025 Knitli Inc.
+// SPDX-FileContributor: Adam Poulemanos <adam@knit.li>
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Main branded header for Knitli documentation sites
+// Provides navigation, branding, and breadcrumb support
+
+interface Props {
+  currentProduct?: 'ReCoco' | 'CodeWeaver' | 'Thread';
+  currentPath?: string;
+  productUrl?: string;
+  showBreadcrumb?: boolean;
+  variant?: 'default' | 'minimal';
+}
+
+const {
+  currentProduct,
+  currentPath = '',
+  productUrl = '',
+  showBreadcrumb = true,
+  variant = 'default',
+} = Astro.props;
+
+// 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 = currentPath === '/' || currentPath === '';
+const shouldShowBreadcrumb = showBreadcrumb && !isDocsHome && currentProduct;
+---
+
+<header class:list={['docs-header', { minimal: variant === 'minimal' }]}>
+  <div class="docs-header-content">
+    <!-- Knitli Logo + Docs Section -->
+    <a href={urls.marketing} class="docs-logo" aria-label="Knitli home">
+      <svg class="logo-icon" width="32" height="32" viewBox="0 0 100 100" fill="none" aria-hidden="true">
+        <!-- Simplified Knitli knot icon -->
+        <circle cx="50" cy="50" r="35" fill="var(--docs-copper)" opacity="0.15"/>
+        <path
+          d="M50 20 L50 50 L65 50"
+          stroke="var(--docs-slate)"
+          stroke-width="4"
+          fill="none"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        />
+        <path
+          d="M35 50 L50 50 L50 80"
+          stroke="var(--docs-slate)"
+          stroke-width="4"
+          fill="none"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        />
+        <circle cx="50" cy="50" r="6" fill="var(--docs-copper)"/>
+      </svg>
+      <span class="logo-text">
+        <span class="logo-brand">Knitli</span>
+        <span class="logo-separator">/</span>
+        <span class="logo-section">docs</span>
+      </span>
+    </a>
+
+    <!-- Breadcrumb (if not on docs home and product specified) -->
+    {shouldShowBreadcrumb && (
+      <nav class="docs-breadcrumb" aria-label="Breadcrumb">
+        <a href="/">Documentation</a>
+        <span class="breadcrumb-separator" aria-hidden="true">→</span>
+        <a href={productUrl || `/${currentProduct}`} class="breadcrumb-product">
+          {currentProduct}
+        </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>
+  :root {
+    --docs-copper: oklch(0.58 0.08 50); /* #b56c30 */
+    --docs-slate: oklch(0.35 0.02 240); /* #485563 */
+    --docs-parchment: oklch(0.96 0.015 70);
+  }
+
+  .docs-header {
+    background: var(--docs-parchment);
+    border-bottom: 1px solid oklch(0.85 0.01 50);
+    position: sticky;
+    top: 0;
+    z-index: 100;
+
+    /* Copper accent line */
+    box-shadow:
+      inset 0 -2px 0 var(--docs-copper),
+      0 1px 3px rgba(0, 0, 0, 0.05);
+  }
+
+  .docs-header.minimal {
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.05);
+    border-bottom: 1px solid oklch(0.90 0.01 60);
+  }
+
+  .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.75rem;
+    text-decoration: none;
+    transition: opacity 0.2s ease;
+  }
+
+  .docs-logo:hover {
+    opacity: 0.8;
+  }
+
+  .logo-icon {
+    flex-shrink: 0;
+  }
+
+  .logo-text {
+    font-family: "DM Mono", "Roboto Mono", "Courier New", monospace;
+    font-size: 1.125rem;
+    font-weight: 600;
+    line-height: 1;
+  }
+
+  .logo-brand {
+    color: var(--docs-slate);
+  }
+
+  .logo-separator {
+    color: var(--docs-copper);
+    opacity: 0.5;
+    margin: 0 0.25rem;
+  }
+
+  .logo-section {
+    color: var(--docs-copper);
+  }
+
+  .docs-breadcrumb {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-family: "Inter", -apple-system, BlinkMacSystemFont, sans-serif;
+    font-size: 0.875rem;
+    color: var(--docs-slate);
+    opacity: 0.7;
+  }
+
+  .docs-breadcrumb a {
+    color: inherit;
+    text-decoration: none;
+    transition: opacity 0.2s ease;
+  }
+
+  .docs-breadcrumb a:hover {
+    opacity: 1;
+    text-decoration: underline;
+  }
+
+  .breadcrumb-separator {
+    opacity: 0.5;
+  }
+
+  .breadcrumb-product {
+    font-weight: 500;
+    opacity: 1;
+  }
+
+  .spacer {
+    flex: 1;
+  }
+
+  .docs-nav {
+    display: flex;
+    gap: 2rem;
+    align-items: center;
+  }
+
+  .docs-nav a {
+    font-family: "Inter", -apple-system, BlinkMacSystemFont, sans-serif;
+    font-size: 0.9375rem;
+    color: var(--docs-slate);
+    text-decoration: none;
+    position: relative;
+    padding: 0.25rem 0;
+    transition: color 0.2s ease;
+  }
+
+  .docs-nav a::after {
+    content: '';
+    position: absolute;
+    bottom: 0;
+    left: 0;
+    width: 0;
+    height: 1px;
+    background: var(--docs-copper);
+    transition: width 0.2s ease;
+  }
+
+  .docs-nav a:hover::after,
+  .docs-nav a.active::after {
+    width: 100%;
+  }
+
+  .docs-nav a.active {
+    color: var(--docs-copper);
+    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%;
+      padding-left: 0;
+    }
+
+    .spacer {
+      display: none;
+    }
+
+    .docs-nav {
+      gap: 1rem;
+      font-size: 0.875rem;
+    }
+
+    .logo-text {
+      font-size: 1rem;
+    }
+  }
+
+  /* Tablet */
+  @media (min-width: 769px) and (max-width: 1024px) {
+    .docs-nav {
+      gap: 1.5rem;
+    }
+  }
+
+  /* Accessibility */
+  .docs-logo:focus-visible,
+  .docs-nav a:focus-visible,
+  .docs-breadcrumb a:focus-visible {
+    outline: 3px solid var(--docs-copper);
+    outline-offset: 4px;
+    border-radius: 4px;
+  }
+
+  /* Reduced motion */
+  @media (prefers-reduced-motion: reduce) {
+    * {
+      animation-duration: 0.01ms !important;
+      transition-duration: 0.01ms !important;
+    }
+  }
+</style>

package/src/index.ts

@@ -0,0 +1,15 @@
+// SPDX-FileCopyrightText: 2025 Knitli Inc.
+// SPDX-FileContributor: Adam Poulemanos <adam@knit.li>
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Main exports for @knitli/docs-components package
+
+// Export type definitions
+export * from './types/index.js';
+
+// Components are exported via package.json exports field
+// Import them directly:
+// import DocsHeader from '@knitli/docs-components/DocsHeader.astro';
+// import DocsFooter from '@knitli/docs-components/DocsFooter.astro';
+// import DocsBreadcrumb from '@knitli/docs-components/DocsBreadcrumb.astro';