@knitli/docs-components 1.1.11 → 1.2.1

package/src/components/ProductCard.astro

@@ -0,0 +1,289 @@
+---
+// SPDX-FileCopyrightText: 2025 Knitli Inc.
+// SPDX-FileContributor: Adam Poulemanos <adam@knit.li>
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Product card for the documentation homepage. Renders a single product
+// from the product catalog with status-driven behavior (clickable link
+// vs static card with "coming soon" stamp).
+
+import { Image } from "astro:assets";
+// @ts-expect-error: 2604
+import { Icon } from "@astrojs/starlight/components";
+import type { StarlightIcon } from "@astrojs/starlight/types";
+import * as logos from "@knitli/shared-layouts";
+import type { ImageMetadata } from "astro";
+import type { Product } from "../data/products.js";
+
+interface Props {
+	/** Product data from the catalog */
+	product: Product;
+	/** Optional Starlight icon (overrides logo) */
+	icon?: StarlightIcon;
+}
+
+const { product, icon } = Astro.props;
+
+/** Resolve a logo key string to an actual ImageMetadata asset from shared-layouts */
+const resolveLogoAsset = (key: string): ImageMetadata | undefined =>
+	(logos as Record<string, ImageMetadata>)[key];
+
+const logo = product.logo ? resolveLogoAsset(product.logo) : undefined;
+const darkLogo = product.darkLogo
+	? resolveLogoAsset(product.darkLogo)
+	: undefined;
+const isClickable = product.docsUrl && product.status !== "coming-soon";
+
+const imageAttrs = {
+	loading: "eager" as const,
+	decoding: "async" as const,
+	width: 48,
+	height: 48,
+	alt: `${product.name} logo`,
+};
+---
+
+{isClickable ? (
+	<a
+		href={product.docsUrl}
+		target={product.external ? "_blank" : "_self"}
+		rel={product.external ? "noopener noreferrer" : undefined}
+	>
+		<article class="card sl-flex linkcard" aria-label="button" tabindex="0">
+			<div class="title-row sl-flex">
+				{(logo || darkLogo) && (
+					<div class="product-logo">
+						{darkLogo && (
+							<Image
+								src={darkLogo}
+								{...imageAttrs}
+								class:list={{ "light:sl-hidden": Boolean(logo) }}
+							/>
+						)}
+						{logo && (
+							<Image
+								src={logo}
+								{...imageAttrs}
+								class="dark:sl-hidden"
+							/>
+						)}
+					</div>
+				)}
+				<p class="title sl-flex">
+					{icon && <Icon name={icon} class="icon" size="1.333em" />}
+					<span>{product.name}</span>
+				</p>
+			</div>
+			<div class="body">
+				<p>
+					{product.description}
+					{product.highlight && (
+						<>
+							<br /><br />
+							<strong>{product.highlight}</strong>
+						</>
+					)}
+					{product.footnote && (
+						<>
+							<br /><br />
+							<em>{product.footnote}</em>
+						</>
+					)}
+				</p>
+				<slot />
+			</div>
+		</article>
+	</a>
+) : (
+	<article class="card sl-flex">
+		<div class="title-row sl-flex">
+			{(logo || darkLogo) && (
+				<div class="product-logo">
+					{darkLogo && (
+						<Image
+							src={darkLogo}
+							{...imageAttrs}
+							class:list={{ "light:sl-hidden": Boolean(logo) }}
+						/>
+					)}
+					{logo && (
+						<Image
+							src={logo}
+							{...imageAttrs}
+							class="dark:sl-hidden"
+						/>
+					)}
+				</div>
+			)}
+			<p class="title sl-flex">
+				{icon && <Icon name={icon} class="icon" size="1.333em" />}
+				<span>{product.name}</span>
+			</p>
+		</div>
+		<div class="body">
+			<p>
+				{product.description}
+				{product.highlight && (
+					<>
+						<br /><br />
+						<strong>{product.highlight}</strong>
+					</>
+				)}
+				{product.footnote && (
+					<>
+						<br /><br />
+						<em>{product.footnote}</em>
+					</>
+				)}
+			</p>
+			<slot />
+		</div>
+		{product.status === "coming-soon" && (
+			<span class="status-badge">Docs coming soon</span>
+		)}
+	</article>
+)}
+
+<style>
+@layer starlight.components {
+  .card {
+    --sl-card-border: var(--knitli-aubergine);
+    --sl-card-bg: var(--sl-color-purple-low);
+    border: 1px solid var(--sl-color-gray-5);
+    background-color: var(--sl-color-black);
+    padding: clamp(1rem, calc(0.125rem + 3vw), 2.5rem);
+    flex-direction: column;
+    gap: clamp(0.5rem, calc(0.125rem + 1vw), 1rem);
+    height: 100%;
+    position: relative;
+    overflow: hidden;
+  }
+  .title {
+    font-weight: 600;
+    font-size: var(--sl-text-h4);
+    color: var(--sl-color-white);
+    line-height: var(--sl-line-height-headings);
+    text-decoration: none;
+    gap: 1rem;
+    align-items: center;
+    margin: 0;
+  }
+  .card .body {
+    margin: 0;
+    text-decoration: none;
+    font-size: clamp(
+      var(--sl-text-sm),
+      calc(0.5rem + 1vw),
+      var(--sl-text-body)
+    );
+    display: flex;
+    flex-direction: column;
+  }
+  .card .body > p {
+    flex: 1;
+    line-height: 1.6;
+  }
+  /* Clickable card styles */
+  a {
+    text-decoration: none !important;
+    color: var(--sl-color-text) !important;
+  }
+  a:hover {
+    text-decoration: none !important;
+    color: var(--sl-color-text) !important;
+    cursor: pointer;
+  }
+  a .linkcard {
+    transition:
+      background-color 0.3s,
+      border-color 0.3s;
+    cursor: pointer;
+  }
+  a .linkcard:hover,
+  a:hover .linkcard {
+    background-color: var(--sl-color-bg-inline-code);
+    border: 0.1rem solid var(--knitli-rust);
+    scale: 1.02;
+    transition: transform 0.3s ease;
+  }
+
+  /* Remove text decoration from all elements inside linked cards */
+  a .linkcard *,
+  a .linkcard .title,
+  a .linkcard .body,
+  a .linkcard .body p {
+    text-decoration: none !important;
+    color: inherit;
+  }
+
+  a .linkcard .title {
+    color: var(--sl-color-white);
+  }
+  .title-row {
+    gap: 1rem;
+    align-items: center;
+    margin-bottom: 1rem;
+  }
+
+  .card .icon {
+    border: 1px solid var(--sl-card-border);
+    background-color: var(--sl-card-bg);
+    padding: 0.2em;
+    border-radius: 0.25rem;
+    flex-shrink: 0;
+  }
+
+  /* Add padding when stamp is present so description doesn't overlap */
+  .card:has(.status-badge) .body {
+    padding-bottom: 3rem;
+  }
+
+  .product-logo {
+    width: 60px;
+    height: 60px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+  }
+  .product-logo img {
+    width: 100%;
+    height: 100%;
+    object-fit: contain;
+  }
+  .product-logo img:hover {
+    scale: 1.05;
+    transition: transform 0.3s ease;
+  }
+  .status-badge {
+    position: absolute;
+    bottom: 1.25rem;
+    right: 1.75rem;
+    transform: rotate(-8deg);
+    transform-origin: center;
+
+    /* Double-border rubber stamp effect */
+    border: 2px solid var(--sl-color-accent);
+    outline: 1px solid var(--sl-color-accent);
+    outline-offset: 3px;
+    border-radius: 1px;
+
+    color: var(--sl-color-accent);
+    background: transparent;
+
+    font-size: 0.6rem;
+    font-weight: 800;
+    text-transform: uppercase;
+    letter-spacing: 0.18em;
+    padding: 0.3em 0.75em;
+
+    /* Worn ink look */
+    opacity: 0.75;
+    white-space: nowrap;
+    z-index: 10;
+    pointer-events: none;
+    user-select: none;
+  }
+}
+</style>

package/src/components/ProductGrid.astro

@@ -0,0 +1,54 @@
+---
+// SPDX-FileCopyrightText: 2025 Knitli Inc.
+// SPDX-FileContributor: Adam Poulemanos <adam@knit.li>
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Product grid layout — 3-column on desktop with optional staggered offset.
+
+interface Props {
+	staggered?: boolean;
+	stagger?: boolean;
+}
+
+const { staggered, stagger = staggered ?? false } = Astro.props;
+---
+
+<div class:list={["card-grid", { stagger }]}><slot /></div>
+
+<style>
+/** biome-ignore: lint/complexity/noImportantStyles */
+@layer starlight.components {
+  .card-grid {
+    display: grid;
+    grid-template-columns: 100%;
+    gap: 1rem;
+  }
+
+  .card-grid > :global(*) {
+    margin-top: 0 !important;
+  }
+
+  @media (min-width: 50rem) {
+    .card-grid {
+      grid-template-columns: 1fr 1fr 1fr;
+      gap: 1.5rem;
+    }
+    .stagger {
+      --stagger-height: 2.5rem;
+      padding-top: var(--stagger-height);
+    }
+
+    /* Pattern: Up, Baseline, Up */
+    .stagger > :global(*):nth-child(3n + 1) {
+      transform: translateY(calc(-1 * var(--stagger-height)));
+    }
+    .stagger > :global(*):nth-child(3n + 2) {
+      transform: translateY(0);
+    }
+    .stagger > :global(*):nth-child(3n + 3) {
+      transform: translateY(calc(-1 * var(--stagger-height)));
+    }
+  }
+}
+</style>

package/src/components/ProductShowcase.astro

@@ -0,0 +1,22 @@
+---
+// SPDX-FileCopyrightText: 2025 Knitli Inc.
+// SPDX-FileContributor: Adam Poulemanos <adam@knit.li>
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Composite component that renders the full product showcase grid
+// from the product catalog. Requires zero configuration — just
+// import and use: <ProductShowcase />
+
+import { featuredProducts } from "../data/products.js";
+import ProductCard from "./ProductCard.astro";
+import ProductGrid from "./ProductGrid.astro";
+
+const products = featuredProducts();
+---
+
+<ProductGrid staggered>
+	{products.map((product) => (
+		<ProductCard key={product.name} product={product} />
+	))}
+</ProductGrid>

package/src/components/SeoMeta.astro

@@ -0,0 +1,53 @@
+---
+// SPDX-FileCopyrightText: 2026 Knitli Inc.
+// SPDX-FileContributor: Adam Poulemanos <adam@knit.li>
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Knitli-branded wrapper around astro-seo-meta Seo component.
+// Pre-applies brand theme color, color scheme, and OG defaults.
+//
+// Usage:
+//   <SeoMeta title="Getting Started" description="..." />
+//   <SeoMeta title="API Reference" twitter={{ card: "summary" }} />
+
+import { Seo } from "astro-seo-meta";
+
+type ColorScheme = "normal" | "light dark" | "dark light" | "only light";
+
+export interface Props {
+  title?: string;
+  description?: string;
+  keywords?: string[];
+  icon?: string;
+  /** Theme color for browser chrome. Defaults to Knitli aubergine. */
+  themeColor?: string;
+  colorScheme?: ColorScheme;
+  facebook?: {
+    image?: string;
+    type?: string;
+    url?: string;
+  };
+  twitter?: {
+    image?: string;
+    card?: string;
+    site?: string;
+  };
+  robots?: string;
+}
+
+const {
+  themeColor = "#1e061b",
+  colorScheme = "light dark",
+  twitter = {},
+  ...rest
+} = Astro.props;
+
+const mergedTwitter = {
+  card: "summary_large_image",
+  site: "@knitli_inc",
+  ...twitter,
+};
+---
+
+<Seo themeColor={themeColor} colorScheme={colorScheme} twitter={mergedTwitter} {...rest} />

package/src/data/products.json

@@ -0,0 +1,45 @@
+[
+  {
+    "slug": "recoco",
+    "name": "Recoco",
+    "tagline": "Intelligent data pipelines",
+    "description": "Build intelligent data pipelines and ETL workflows. Only process changed data.",
+    "highlight": "Pure Rust, minimal dependencies, maximum efficiency.",
+    "status": "available",
+    "docsUrl": "/recoco/",
+    "external": false,
+    "logo": "recocoLogoSm",
+    "darkLogo": "recocoLogoSm",
+    "order": 1,
+    "featured": true
+  },
+  {
+    "slug": "codeweaver",
+    "name": "CodeWeaver",
+    "tagline": "AI code context engine",
+    "description": "Your AI code assistants can do better.",
+    "highlight": "CodeWeaver gives AI agents tailored code context and project understanding, stopping hallucinations, cutting token waste, and supercharging your AI coding workflows.",
+    "footnote": "Now in Alpha.",
+    "status": "coming-soon",
+    "external": false,
+    "logo": "codeweaverPrimary",
+    "darkLogo": "codeweaverReverse",
+    "order": 2,
+    "featured": true
+  },
+  {
+    "slug": "thread",
+    "name": "Thread",
+    "tagline": "Ultra-fast codebase analysis",
+    "description": "An ultra-fast, Rust-native, codebase analysis platform.",
+    "highlight": "Real-time code understanding and navigation for the largest codebases. Delivers 50x+ speed improvements over comparable tools with minimal resource usage. Works locally, on the edge, or in the cloud.",
+    "footnote": "Limited features available now, full release coming soon.",
+    "status": "available",
+    "docsUrl": "https://docs.rs/thread",
+    "external": true,
+    "logo": "threadLogoLight",
+    "darkLogo": "threadLogoDark",
+    "order": 3,
+    "featured": true
+  }
+]

package/src/data/products.ts

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2025 Knitli Inc.
+// SPDX-FileContributor: Adam Poulemanos <adam@knit.li>
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Product catalog — single source of truth for all Knitli product metadata.
+// Edit products.json to add, remove, reorder, or update products.
+
+import catalogData from "./products.json" with { type: "json" };
+
+export type ProductStatus = "available" | "coming-soon" | "alpha" | "beta";
+
+export interface Product {
+  /** URL slug used in docs paths, e.g. "recoco" */
+  slug: string;
+  /** Display name */
+  name: string;
+  /** Short tagline for cards/nav */
+  tagline: string;
+  /** Primary description */
+  description: string;
+  /** Bold/emphasized callout text */
+  highlight?: string;
+  /** Italicized footnote (e.g. "Now in Alpha.") */
+  footnote?: string;
+  /** Product status — drives card rendering and footer links */
+  status: ProductStatus;
+  /** Docs URL — relative for hosted docs, absolute for external */
+  docsUrl?: string;
+  /** Whether docs are hosted externally (e.g. docs.rs) */
+  external?: boolean;
+  /** Logo asset key from DocsAssets */
+  logo: string;
+  /** Dark-mode logo asset key from DocsAssets */
+  darkLogo?: string;
+  /** Sort order for display */
+  order: number;
+  /** Set false to hide from docs-home without deleting */
+  featured?: boolean;
+}
+
+/** All products from the catalog */
+export const products: Product[] = catalogData as Product[];
+
+/** Products marked as featured (or not explicitly unfeatured), sorted by order */
+export function featuredProducts(): Product[] {
+  return products
+    .filter((p) => p.featured !== false)
+    .sort((a, b) => a.order - b.order);
+}
+
+/** Products with available documentation (not coming-soon) */
+export function availableProducts(): Product[] {
+  return products.filter((p) => p.status !== "coming-soon");
+}
+
+/** Look up a single product by slug */
+export function getProduct(slug: string): Product | undefined {
+  return products.find((p) => p.slug === slug);
+}
+
+/** Look up a product by display name */
+export function getProductByName(name: string): Product | undefined {
+  return products.find((p) => p.name === name);
+}
+
+/** All valid product display names, derived from catalog */
+export function productNames(): string[] {
+  return products.map((p) => p.name);
+}
+
+/** Generate sitemap URLs for products with hosted (non-external) docs */
+export function getProductSitemaps(
+  baseUrl = "https://docs.knitli.com",
+): string[] {
+  return products
+    .filter((p) => p.docsUrl && !p.external && p.status !== "coming-soon")
+    .map((p) => `${baseUrl}/${p.slug}/sitemap-index.xml`);
+}

package/src/index.ts

@@ -5,7 +5,8 @@
 //
 // Main exports for @knitli/docs-components package
 
-// Export type definitions
+export * from "./data/products.js";
+// Export type definitions and product catalog
 export * from "./types/index.js";
 
 import { faviconIco, faviconSvg } from "./assets/favicon/index.js";
@@ -54,6 +55,14 @@ const components = {
   DocsBreadcrumb: async () => await import("./components/DocsBreadcrumb.astro"),
   DocsFooter: async () => await import("./components/Footer.astro"),
   PageFrame: async () => await import("./components/PageFrame.astro"),
+  Contributors: async () => await import("./components/Contributors.astro"),
+  AllContributors: async () =>
+    await import("./components/AllContributors.astro"),
+  SeoMeta: async () => await import("./components/SeoMeta.astro"),
+  ProductCard: async () => await import("./components/ProductCard.astro"),
+  ProductGrid: async () => await import("./components/ProductGrid.astro"),
+  ProductShowcase: async () =>
+    await import("./components/ProductShowcase.astro"),
 };
 
 export default {

package/src/types/index.ts

@@ -5,10 +5,8 @@
 //
 // TypeScript type definitions for docs-components package
 
-/**
- * Supported Knitli products for documentation
- */
-export type ProductName = "Recoco" | "CodeWeaver" | "Thread";
+// Product catalog types and helpers are exported from ../data/products.ts
+// and re-exported via the package's main index.ts entry point.
 
 /**
  * Site URLs configuration
@@ -26,7 +24,7 @@ export interface DocsBreadcrumbProps {
   /**
    * Current product name
    */
-  product?: ProductName;
+  product?: string;
 
   /**
    * URL to the product's documentation home
@@ -42,5 +40,5 @@ export interface DocsBreadcrumbProps {
    * Visual variant of the breadcrumb
    * @default 'default'
    */
-  variant?: "default" | "compact";
+  variant?: "default" | "compact" | "inline";
 }