@siteswarm/components

@siteswarm/components

Unstyled, layout-shift-free performance and accessibility primitives for SiteSwarm applications.

---

🏛️ Architectural Role & The Anti-Theming Invariant

A central invariant of SiteSwarm’s architecture is the Anti-Theming & Zero Visual Templating Invariant:

The Anti-Theming Invariant: SiteSwarm strictly forbids CSS design tokens, shared styling adapters, or global component styling hierarchies. Client sites must never share visual templates or color variable schemas. Every client application is authored with 100% bespoke markup, layout, and visual styling to guarantee an authentic, unconstrained digital brand.

Why @siteswarm/components Exists

Having a package named components may appear at first glance to conflict with this invariant. However, @siteswarm/components does not provide styled UI elements (such as buttons, cards, dialogs, badges, or headers).

Instead, @siteswarm/components is strictly restricted to unstyled performance and DOM primitives:

• Zero-Layout-Shift Mechanics: Mathematical layout containment (contain: layout paint and explicit aspect-ratio) to eliminate Cumulative Layout Shift (CLS = 0).
• Edge Media Optimization: Automatic multi-format source negotiation (image/avif, image/webp) and responsive srcset generation powered by Cloudflare Images via @siteswarm/media.
• Browser Performance Primitives: Strict LCP (Largest Contentful Paint) optimization, eager/lazy loading switches, and fetchpriority controls.

🚫 Boundary Definitions: What Belongs vs. What Is Forbidden

Category	Allowed in @siteswarm/components?	Examples
Unstyled Performance Primitives	✅ ALLOWED	<Picture.astro>, media source builders, aspect ratio calculation wrappers
Accessibility Primitives	✅ ALLOWED	Unstyled focus traps, screen-reader announcements, skip-links
Styled UI Elements	❌ STRICTLY FORBIDDEN	Buttons, cards, alert banners, modal dialogs, pills
Design System & Theme Tokens	❌ STRICTLY FORBIDDEN	Color palettes, typography presets, border radius scales, shadow tokens
Page / Layout Templates	❌ STRICTLY FORBIDDEN	Header/Footer layouts, hero blocks, testimonial grids

All visual design, colors, typography, and UI component styling remain strictly bespoke within each client application (e.g. apps/bakery, apps/software-agency).

---

🖼️ Core Component: <Picture.astro>

<Picture.astro> is SiteSwarm’s responsive image primitive. It wraps the HTML5 <picture> and <img> elements to guarantee sub-millisecond edge delivery, optimal responsive sizing, and zero layout shift.

Key Performance Capabilities

1. Zero Cumulative Layout Shift (CLS = 0):
   • Renders inline style="aspect-ratio: <ratio>;" derived automatically from intrinsic width and height (or overridden via aspectRatio).
   • Applies CSS containment via .siteswarm-picture { contain: layout paint; } to isolate the element’s layout and rendering tree from the rest of the DOM.
   • Provides a neutral, subtle placeholder background (bg-slate-100 dark:bg-slate-800) while the high-resolution asset loads.
2. Next-Gen Format Negotiation (AVIF & WebP):
   • Emits dual <source type="image/avif"> and <source type="image/webp"> elements with automatically computed srcset variants.
   • Routes through Cloudflare Images (/cdn-cgi/image/...) for edge transcoding and compression.
3. Optimized LCP & Loading Priorities:
   • Standard images default to loading="lazy", decoding="async", and standard fetch priority.
   • Above-the-fold / Hero assets flagged with priority={true} toggle to loading="eager", decoding="sync", and fetchpriority="high" for instant browser discovery and rendering.

---

📖 Component API

<Picture.astro> Props

import type { CloudflareImageFit } from "@siteswarm/components";

export interface Props {
  /** Source URL or asset path */
  src: string;
  /** Accessible image description */
  alt: string;
  /** Intrinsic image width in pixels */
  width: number;
  /** Intrinsic image height in pixels */
  height: number;
  /** Responsive widths array for srcset generation (default: [360, 640, 1024, 1920]) */
  widths?: readonly number[];
  /** Media query sizes attribute (default: "(max-width: 640px) 100vw, (max-width: 1024px) 75vw, 50vw") */
  sizes?: string;
  /** Image transform compression quality (1-100, default: 80) */
  quality?: number;
  /** Prioritize above-the-fold assets for Largest Contentful Paint (default: false) */
  priority?: boolean;
  /** Cloudflare image fit behavior: "scale-down" | "contain" | "cover" | "crop" | "pad" (default: "scale-down") */
  fit?: CloudflareImageFit;
  /** CSS class list applied to the inner <img> tag (default: "h-auto w-full object-cover") */
  class?: string;
  /** CSS class list applied to the outer <picture> wrapper (default: "") */
  pictureClass?: string;
  /** Optional custom Cloudflare zone domain override (e.g. "media.example.com") */
  zoneDomain?: string;
  /** Custom aspect-ratio override string (e.g. "16/9", "4/3", "1/1") */
  aspectRatio?: string;
}

---

💻 Usage Examples

1. Basic Content Image

---
import Picture from "@siteswarm/components/Picture.astro";
---

<Picture
  src="/assets/artisan-sourdough.jpg"
  alt="Freshly baked artisan sourdough loaf"
  width={1200}
  height={800}
  class="rounded-xl shadow-lg"
/>

2. High-Priority Hero Banner (LCP Optimized)

For hero images, set priority={true} to configure eager loading, synchronous decoding, and high fetch priority:

---
import Picture from "@siteswarm/components/Picture.astro";
---

<section class="relative w-full overflow-hidden">
  <Picture
    src="/hero-cover.jpg"
    alt="Agency studio team collaborating on edge software"
    width={1920}
    height={1080}
    priority={true}
    sizes="100vw"
    widths={[640, 1024, 1440, 1920]}
    class="h-full w-full object-cover"
    pictureClass="w-full h-[60vh] max-h-[720px]"
  />
</section>

3. Custom Aspect Ratio and Cloudflare Fit Mode

---
import Picture from "@siteswarm/components/Picture.astro";
---

<!-- Force a strict 1:1 square crop regardless of intrinsic dimensions -->
<Picture
  src="/team/founder.jpg"
  alt="Founder portrait"
  width={800}
  height={600}
  aspectRatio="1/1"
  fit="cover"
  class="rounded-full object-cover"
  pictureClass="w-48 h-48 mx-auto"
/>

4. Custom Cloudflare Zone Domain

When media is hosted on a dedicated CDN zone or external domain:

---
import Picture from "@siteswarm/components/Picture.astro";
---

<Picture
  src="/catalog/pastry-01.png"
  alt="Croissant with powdered sugar"
  width={1000}
  height={1000}
  zoneDomain="cdn.clientdomain.com"
  quality={85}
/>

---

🔧 Re-Exported Media Utilities

For convenience, @siteswarm/components re-exports core utilities and TypeScript types from @siteswarm/media:

import {
  buildCloudflareImageUrl,
  generateResponsiveSrcSet,
  generatePictureSources,
  generateMediaKey,
  calculateAspectRatio,
  IMMUTABLE_MEDIA_CACHE_CONTROL,
  DEFAULT_RESPONSIVE_WIDTHS,
  type CloudflareImageFormat,
  type CloudflareImageFit,
  type CloudflareImageTransformOptions,
  type PictureSourceDefinition,
} from "@siteswarm/components";

Example: Manual URL Construction

import { buildCloudflareImageUrl } from "@siteswarm/components";

const optimizedUrl = buildCloudflareImageUrl("/assets/logo.png", {
  width: 400,
  quality: 90,
  format: "webp",
  fit: "contain",
});

---

🧪 Verification & Testing

Unit tests and type checks verify contract adherence:

# Run TypeScript compilation check
pnpm --filter @siteswarm/components check

# Execute test suite
pnpm --filter @siteswarm/components test