Add Content Switcher to articles and deep-dive item views

Author: webstackdev

.cache/pages.json

@@ -90,71 +90,71 @@
   "contact",
   {
     "deep-dive": [
-      "alert-fatigue-reduction-triage-actionable-alerts/pdf",
-      "api-deprecation-sunset-headers-consumer-migration/pdf",
-      "api-gateway-metrics-traces-logs-debugging/pdf",
-      "api-usage-metering-quotas-cost-attribution/pdf",
-      "argocd-sync-failures-gitops-debugging-troubleshooting/pdf",
-      "availability-targets-five-nines-cost-benefit-analysis/pdf",
-      "backpressure-load-shedding-admission-control-overload/pdf",
-      "blameless-postmortem-incident-analysis-systemic-causes/pdf",
-      "blue-green-canary-deployment-strategy-comparison/pdf",
-      "cdn-edge-caching-cache-keys-vary-headers/pdf",
-      "chaos-engineering-failure-injection-low-cost-experiments/pdf",
-      "ci-pipeline-caching-docker-layers-dependency-cache/pdf",
-      "circuit-breaker-retry-budget-cascade-failure-prevention/pdf",
-      "consumer-driven-contract-testing-pact-internal-apis/pdf",
-      "container-vulnerability-scanning-ci-shift-left-security/pdf",
-      "database-schema-migrations-continuous-deployment-zero-downtime/pdf",
-      "dead-letter-queue-design-replay-debugging/pdf",
-      "distributed-tracing-sampling-strategies-head-tail/pdf",
-      "eol-runtime-upgrade-dependency-hell-migration/pdf",
-      "ephemeral-preview-environments-cost-control-cleanup/pdf",
-      "flaky-test-diagnosis-race-conditions-e2e-stabilization/pdf",
-      "golden-paths-developer-experience-standardization-autonomy/pdf",
-      "grafana-dashboard-hygiene-pruning-actionable-metrics/pdf",
-      "helm-release-management-drift-detection-debugging/pdf",
-      "idempotent-message-handlers-deduplication-retries/pdf",
-      "internal-cli-kubectl-terraform-wrapper-abstraction/pdf",
-      "internal-developer-portal-platform-self-service-actions/pdf",
-      "internal-platform-api-versioning-deprecation-breaking-changes/pdf",
-      "kubernetes-cluster-upgrade-playbook-risk-reduction/pdf",
-      "kubernetes-cost-optimization-resource-sizing-spot-instances/pdf",
-      "kubernetes-decision-framework-when-not-to-use/pdf",
-      "kubernetes-dns-debugging-ndots-coredns-troubleshooting/pdf",
-      "kubernetes-hpa-autoscaling-metrics-tuning-latency/pdf",
-      "kubernetes-ingress-gateway-api-comparison-migration/pdf",
-      "kubernetes-multi-cluster-fleet-management-configuration/pdf",
-      "kubernetes-pod-resource-requests-limits-qos-classes/pdf",
-      "kubernetes-secrets-external-secrets-operator-csi-vault/pdf",
-      "legacy-code-testing-characterization-tests-seams/pdf",
-      "monorepo-affected-builds-remote-caching-ci-optimization/pdf",
-      "mtls-certificate-rotation-service-mesh-authentication/pdf",
-      "nginx-haproxy-reverse-proxy-production-tuning/pdf",
-      "on-call-rotation-small-teams-sustainable-coverage/pdf",
-      "opa-conftest-policy-as-code-infrastructure-guardrails/pdf",
-      "openapi-spec-documentation-sdk-generation-validation/pdf",
-      "opentelemetry-span-design-granularity-overhead/pdf",
-      "performance-testing-load-models-benchmark-accuracy/pdf",
-      "platform-architecture-control-plane-data-plane-separation/pdf",
-      "platform-engineering-metrics-lead-time-developer-friction/pdf",
-      "postgresql-connection-pooling-saturation-sizing/pdf",
-      "private-networking-dns-routing-tls-debugging/pdf",
-      "prometheus-high-cardinality-metrics-label-design/pdf",
-      "rate-limiting-token-bucket-leaky-bucket-implementation/pdf",
-      "release-quality-gates-automated-deployment-validation/pdf",
-      "reverse-engineering-documentation-legacy-systems/pdf",
-      "service-catalog-metadata-schema-ownership-tracking/pdf",
-      "service-decommissioning-scream-test-shutdown/pdf",
-      "slo-error-budget-practical-guide/pdf",
-      "slsa-build-provenance-artifact-signing-supply-chain/pdf",
-      "strangler-fig-migration-complete-guide/pdf",
-      "structured-logging-correlation-ids-log-schema-design/pdf",
-      "symptom-based-alerting-runbooks-alert-design/pdf",
-      "synthetic-test-data-pii-anonymization-fixtures/pdf",
-      "terraform-module-design-defaults-versioning-interfaces/pdf",
-      "terraform-state-locking-corruption-recovery-backend/pdf",
-      "workload-identity-federation-keyless-cloud-authentication/pdf"
+      "alert-fatigue-reduction-triage-actionable-alerts",
+      "api-deprecation-sunset-headers-consumer-migration",
+      "api-gateway-metrics-traces-logs-debugging",
+      "api-usage-metering-quotas-cost-attribution",
+      "argocd-sync-failures-gitops-debugging-troubleshooting",
+      "availability-targets-five-nines-cost-benefit-analysis",
+      "backpressure-load-shedding-admission-control-overload",
+      "blameless-postmortem-incident-analysis-systemic-causes",
+      "blue-green-canary-deployment-strategy-comparison",
+      "cdn-edge-caching-cache-keys-vary-headers",
+      "chaos-engineering-failure-injection-low-cost-experiments",
+      "ci-pipeline-caching-docker-layers-dependency-cache",
+      "circuit-breaker-retry-budget-cascade-failure-prevention",
+      "consumer-driven-contract-testing-pact-internal-apis",
+      "container-vulnerability-scanning-ci-shift-left-security",
+      "database-schema-migrations-continuous-deployment-zero-downtime",
+      "dead-letter-queue-design-replay-debugging",
+      "distributed-tracing-sampling-strategies-head-tail",
+      "eol-runtime-upgrade-dependency-hell-migration",
+      "ephemeral-preview-environments-cost-control-cleanup",
+      "flaky-test-diagnosis-race-conditions-e2e-stabilization",
+      "golden-paths-developer-experience-standardization-autonomy",
+      "grafana-dashboard-hygiene-pruning-actionable-metrics",
+      "helm-release-management-drift-detection-debugging",
+      "idempotent-message-handlers-deduplication-retries",
+      "internal-cli-kubectl-terraform-wrapper-abstraction",
+      "internal-developer-portal-platform-self-service-actions",
+      "internal-platform-api-versioning-deprecation-breaking-changes",
+      "kubernetes-cluster-upgrade-playbook-risk-reduction",
+      "kubernetes-cost-optimization-resource-sizing-spot-instances",
+      "kubernetes-decision-framework-when-not-to-use",
+      "kubernetes-dns-debugging-ndots-coredns-troubleshooting",
+      "kubernetes-hpa-autoscaling-metrics-tuning-latency",
+      "kubernetes-ingress-gateway-api-comparison-migration",
+      "kubernetes-multi-cluster-fleet-management-configuration",
+      "kubernetes-pod-resource-requests-limits-qos-classes",
+      "kubernetes-secrets-external-secrets-operator-csi-vault",
+      "legacy-code-testing-characterization-tests-seams",
+      "monorepo-affected-builds-remote-caching-ci-optimization",
+      "mtls-certificate-rotation-service-mesh-authentication",
+      "nginx-haproxy-reverse-proxy-production-tuning",
+      "on-call-rotation-small-teams-sustainable-coverage",
+      "opa-conftest-policy-as-code-infrastructure-guardrails",
+      "openapi-spec-documentation-sdk-generation-validation",
+      "opentelemetry-span-design-granularity-overhead",
+      "performance-testing-load-models-benchmark-accuracy",
+      "platform-architecture-control-plane-data-plane-separation",
+      "platform-engineering-metrics-lead-time-developer-friction",
+      "postgresql-connection-pooling-saturation-sizing",
+      "private-networking-dns-routing-tls-debugging",
+      "prometheus-high-cardinality-metrics-label-design",
+      "rate-limiting-token-bucket-leaky-bucket-implementation",
+      "release-quality-gates-automated-deployment-validation",
+      "reverse-engineering-documentation-legacy-systems",
+      "service-catalog-metadata-schema-ownership-tracking",
+      "service-decommissioning-scream-test-shutdown",
+      "slo-error-budget-practical-guide",
+      "slsa-build-provenance-artifact-signing-supply-chain",
+      "strangler-fig-migration-complete-guide",
+      "structured-logging-correlation-ids-log-schema-design",
+      "symptom-based-alerting-runbooks-alert-design",
+      "synthetic-test-data-pii-anonymization-fixtures",
+      "terraform-module-design-defaults-versioning-interfaces",
+      "terraform-state-locking-corruption-recovery-backend",
+      "workload-identity-federation-keyless-cloud-authentication"
     ]
   },
   "hero",

src/components/Breadcrumbs/index.astro

@@ -37,7 +37,7 @@ const breadcrumbSchema =
 
 {
   breadcrumbs.length > 1 && (
-    <div id="breadcrumbs" class="mt-4">
+    <div class="min-w-0">
       <nav aria-label="Breadcrumbs" class="breadcrumbs sm:pl-4">
         <ol class="flex items-center space-x-2 text-sm sm:text-base text-primary-offset">
           {breadcrumbs.map((item, index) => (

src/components/Content/Layout/index.astro

@@ -9,8 +9,9 @@
 import type { CollectionEntry } from 'astro:content'
 import { Picture } from 'astro:assets'
 import MarkdownLayout from '@layouts/MarkdownLayout.astro'
-import Shares from '@components/Social/Shares/index.astro'
 import Carousel from '@components/Carousel/index.astro'
+import ContentSwitcher from '@components/Content/Switcher/index.astro'
+import Shares from '@components/Social/Shares/index.astro'
 import WebMentions from '@components/WebMentions/index.astro'
 
 export type Props = {
@@ -45,6 +46,11 @@ const { author, article, path, readingTime, section } = Astro.props
   tags={article.data.tags?.map(t => (typeof t === 'string' ? t : t.id)) ?? []}
   {...readingTime && { readingTime }}
 >
+  {/** SLOT: breadcrumb-row */}
+  <div class="" slot="breadcrumb-row">
+    <ContentSwitcher path={path} />
+  </div>
+
   {/** SLOT: hero-image */}
   {
     article.data.cover && (

src/components/Content/Switcher/client/index.ts

@@ -63,11 +63,11 @@ export class ContentSwitcherElement extends LitElement {
 					role="switch"
 					aria-checked="${isDeepDive ? 'true' : 'false'}"
 					aria-label="Toggle between Overview and Deep Dive"
-					class="content-switcher-track group relative inline-flex h-7 w-12 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent bg-trim-offset transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-secondary"
+					class="content-switcher-track group relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent bg-trim-offset transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-secondary"
 					data-switcher-toggle
 				>
 					<span
-						class="content-switcher-thumb pointer-events-none inline-block size-5 translate-x-0.5 rounded-full bg-page-base shadow-sm ring-0 transition-transform"
+						class="content-switcher-thumb pointer-events-none inline-block size-3 translate-x-0.5 rounded-full bg-page-base shadow-sm ring-0 transition-transform"
 					></span>
 				</a>
 

src/components/Content/Switcher/index.astro

@@ -1,14 +1,40 @@
 ---
+import { parseContentPath } from './server'
+import { BuildError } from '@lib/errors/BuildError'
 import './index.css'
 
 export type Props = {
-  /** The currently active variant, used to determine the position of the switcher thumb */
-  currentVariant: 'overview' | 'deep-dive'
-  /** Shared slug used to navigate between overview and deep-dive routes */
-  slug: string
+  /** The URL path component e.g. 'articles/my-article' */
+  path?: string
+  /** Legacy current variant for client rendering */
+  currentVariant?: 'overview' | 'deep-dive'
+  /** Legacy slug for client rendering */
+  slug?: string
 }
 
-const { currentVariant, slug } = Astro.props
+const {
+  path,
+  currentVariant: legacyCurrentVariant,
+  slug: legacySlug = '',
+} = Astro.props
+
+let currentVariant: 'overview' | 'deep-dive'
+let slug: string
+
+if (path) {
+  const parsed = parseContentPath(path)
+  currentVariant = parsed.currentVariant === 'articles' ? 'overview' : 'deep-dive'
+  slug = parsed.slug
+} else if (legacyCurrentVariant) {
+  currentVariant = legacyCurrentVariant
+  slug = legacySlug
+} else {
+  throw new BuildError('Content/Switcher: expected either `path` or `currentVariant` prop.', {
+    phase: 'compilation',
+    filePath: 'src/components/Content/Switcher/index.astro',
+    tool: 'content-switcher',
+  })
+}
 ---
 
 <content-switcher current-variant={currentVariant} slug={slug}></content-switcher>

src/components/Content/Switcher/index.css

@@ -7,5 +7,5 @@
 }
 
 .content-switcher-track[aria-checked='true'] .content-switcher-thumb {
-  transform: translateX(1.25rem);
+  transform: translateX(1.125rem);
 }

src/components/Content/Switcher/server/__tests__/index.spec.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest'
+import { BuildError } from '@lib/errors/BuildError'
+import { parseContentPath } from '../index'
+
+describe('parseContentPath', () => {
+	it('parses an articles path into currentVariant and slug', () => {
+		expect(parseContentPath('articles/my-article')).toEqual({
+			currentVariant: 'articles',
+			slug: 'my-article',
+		})
+	})
+
+	it('parses a deep-dive path into currentVariant and slug', () => {
+		expect(parseContentPath('deep-dive/web-vitals')).toEqual({
+			currentVariant: 'deep-dive',
+			slug: 'web-vitals',
+		})
+	})
+
+	it('normalizes leading and trailing slashes', () => {
+		expect(parseContentPath('/articles/my-article/')).toEqual({
+			currentVariant: 'articles',
+			slug: 'my-article',
+		})
+	})
+
+	it('normalizes extra whitespace around path', () => {
+		expect(parseContentPath('  /deep-dive/platform-reliability/  ')).toEqual({
+			currentVariant: 'deep-dive',
+			slug: 'platform-reliability',
+		})
+	})
+
+	it('preserves nested slug segments', () => {
+		expect(parseContentPath('articles/category/subcategory/my-article')).toEqual({
+			currentVariant: 'articles',
+			slug: 'category/subcategory/my-article',
+		})
+	})
+
+	it('returns an empty slug when only the variant is provided', () => {
+		expect(parseContentPath('articles')).toEqual({
+			currentVariant: 'articles',
+			slug: '',
+		})
+	})
+
+	it('throws BuildError for unsupported variant', () => {
+		expect(() => parseContentPath('services/my-service')).toThrow(BuildError)
+		expect(() => parseContentPath('services/my-service')).toThrow(
+			'Content/Switcher: invalid path variant.'
+		)
+	})
+
+	it('throws BuildError for an empty path', () => {
+		const parse = () => parseContentPath('   ')
+
+		expect(parse).toThrow(BuildError)
+		expect(parse).toThrow('Content/Switcher: invalid path variant.')
+	})
+
+	it('includes detailed context in the thrown BuildError', () => {
+		try {
+			parseContentPath('/unknown/thing')
+			throw new Error('Expected parseContentPath to throw BuildError')
+		} catch (error) {
+			const typedError = error as BuildError
+
+			expect(typedError).toBeInstanceOf(BuildError)
+			expect(typedError.phase).toBe('compilation')
+			expect(typedError.tool).toBe('content-switcher')
+			expect(typedError.filePath).toBe('src/components/Content/Switcher/server/index.ts')
+			expect(typedError.cause).toEqual({
+				providedPath: '/unknown/thing',
+				normalizedPath: 'unknown/thing',
+				receivedVariant: 'unknown',
+				expectedVariants: ['articles', 'deep-dive'],
+			})
+		}
+	})
+})

src/components/Content/Switcher/server/index.ts

@@ -0,0 +1,32 @@
+import { BuildError } from '@lib/errors/BuildError'
+type ContentVariant = 'articles' | 'deep-dive'
+
+export const parseContentPath = (path: string) => {
+  const normalizedPath = path.trim().replace(/^\/+|\/+$/g, '')
+  const [variant, ...slugParts] = normalizedPath.split('/').filter(Boolean)
+  const candidateVariant = variant ?? ''
+
+  const isSupportedVariant = (value: string): value is ContentVariant => {
+    return value === 'articles' || value === 'deep-dive'
+  }
+
+  if (!isSupportedVariant(candidateVariant)) {
+    const errorDetails = {
+      providedPath: path,
+      normalizedPath,
+      receivedVariant: variant ?? null,
+      expectedVariants: ['articles', 'deep-dive'],
+    }
+
+    throw new BuildError(new Error('Content/Switcher: invalid path variant.', { cause: errorDetails }), {
+      phase: 'compilation',
+      filePath: 'src/components/Content/Switcher/server/index.ts',
+      tool: 'content-switcher',
+    })
+  }
+
+  return {
+    currentVariant: candidateVariant,
+    slug: slugParts.join('/'),
+  }
+}