@warpgogol/werkstatt-shared 0.2.0

package/src/share/schemas/section-cta.ts

@@ -0,0 +1,74 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+[RFC-0104] Canonical CtaConfig and CtaGroupConfig — one structured shape used
+by every section that renders a call-to-action. Replaces the four ad-hoc CTA
+shapes that lived on hero / final-cta / hero-decision-card / notausgang-block.
+</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+import { horizontalAlignSchema } from "./horizontal-align.ts";
+import { vendorIconConfigSchema } from "./standard-list-item.ts";
+
+export const ctaVariantSchema = z.enum(["primary", "secondary", "ghost", "danger"]);
+export type CtaVariant = z.infer<typeof ctaVariantSchema>;
+
+export const ctaSizeSchema = z.enum(["sm", "md", "lg"]);
+export type CtaSize = z.infer<typeof ctaSizeSchema>;
+
+export const ctaIconPositionSchema = z.enum(["leading", "trailing"]);
+export type CtaIconPosition = z.infer<typeof ctaIconPositionSchema>;
+
+export const ctaTargetSchema = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("internal"),
+      pageId: z.string().min(1),
+      anchor: z.string().optional(),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("external"),
+      href: z.string().min(1),
+      rel: z.string().optional(),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("anchor"),
+      anchor: z.string().min(1),
+    })
+    .strict(),
+]);
+export type CtaTarget = z.infer<typeof ctaTargetSchema>;
+
+export const ctaConfigSchema = z
+  .object({
+    label: z.string().min(1),
+    target: ctaTargetSchema,
+    ariaLabel: z.string().optional(),
+    variant: ctaVariantSchema.optional(),
+    icon: vendorIconConfigSchema.optional(),
+    iconPosition: ctaIconPositionSchema.optional(),
+    size: ctaSizeSchema.optional(),
+    fullWidth: z.boolean().optional(),
+  })
+  .strict();
+export type CtaConfig = z.infer<typeof ctaConfigSchema>;
+
+export const ctaGroupConfigSchema = z
+  .object({
+    align: horizontalAlignSchema.optional(),
+    items: z.array(ctaConfigSchema).min(1),
+  })
+  .strict();
+export type CtaGroupConfig = z.infer<typeof ctaGroupConfigSchema>;

package/src/share/schemas/section-header.ts

@@ -0,0 +1,77 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+[RFC-0102] Canonical SectionHeader contract — structured heading (string or
+tone-segmented array), optional subheading, independent alignment, optional
+section number, optional level override.
+</purpose>
+<non-goals>
+  <item>Do not declare body content (RFC-0103) or CTA shape (RFC-0104).</item>
+  <item>Do not couple header alignment to body alignment (each is independent).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+import { horizontalAlignSchema } from "./horizontal-align.ts";
+import { effectStackSchema } from "./effects.ts";
+
+export const headingToneSchema = z.enum(["default", "primary", "accent", "muted", "inverse"]);
+export type HeadingTone = z.infer<typeof headingToneSchema>;
+
+export const headingSegmentSchema = z
+  .object({
+    text: z.string().min(1),
+    tone: headingToneSchema.optional(),
+  })
+  .strict();
+export type HeadingSegment = z.infer<typeof headingSegmentSchema>;
+
+/**
+ * RFC-0102 — HeadingContent. Either a plain string (entire title renders in
+ * tone "default") or an array of tone-segmented runs that the renderer wraps
+ * in <span class="section-header__title-segment section-header__title-segment--{tone}">.
+ */
+export const headingContentSchema = z.union([
+  z.string().min(1),
+  z.array(headingSegmentSchema).min(1),
+]);
+export type HeadingContent = z.infer<typeof headingContentSchema>;
+
+export const sectionHeaderLevelSchema = z.union([z.literal(1), z.literal(2)]);
+export type SectionHeaderLevel = z.infer<typeof sectionHeaderLevelSchema>;
+
+export const sectionHeaderSchema = z
+  .object({
+    /** Resolved upstream by blocks-renderer. */
+    sectionNumber: z.string().optional(),
+    /** Suppress the section number even if blocks-renderer supplied one. */
+    hideSectionNumber: z.boolean().optional(),
+    heading: headingContentSchema,
+    /** RFC-0567 — short contextual label rendered above the heading. */
+    eyebrow: z.string().optional(),
+    /** One short paragraph under the title. Longer copy belongs in body.kind: paragraphs (RFC-0103). */
+    subheading: z.string().optional(),
+    /** Independent header alignment; default "left". */
+    align: horizontalAlignSchema.optional(),
+    /** h1 for hero archetype, h2 otherwise. Default 2. */
+    level: sectionHeaderLevelSchema.optional(),
+    /** Used as aria-labelledby target by <SectionShell>. */
+    id: z.string().optional(),
+    /**
+     * RFC-0151 — resolved typographic effect stack for the `heading` target.
+     * Section composites pass resolveEffectsForTarget(effects, "heading").
+     * When absent or empty, the header renders exactly as before.
+     */
+    headingEffects: effectStackSchema.optional(),
+    /**
+     * RFC-0151 — resolved typographic effect stack for the `subheading` target.
+     */
+    subheadingEffects: effectStackSchema.optional(),
+  })
+  .strict();
+
+export type SectionHeaderProps = z.infer<typeof sectionHeaderSchema>;

package/src/share/schemas/section-image.ts

@@ -0,0 +1,77 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+[RFC-0104 + RFC-0118] Canonical SectionImageProps + ImageFade for the shared
+<SectionImage> primitive. Image fades become a property of the image, not of
+the surrounding section. Parallax accepts boolean | number | object per
+RFC-0118 to align with RFC-0106 ParallaxVariant semantics.
+</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+import { livePhotoSchema } from "./live-photo.ts";
+
+export const imageFadeSchema = z
+  .object({
+    top: z.boolean().optional(),
+    bottom: z.boolean().optional(),
+    left: z.boolean().optional(),
+    right: z.boolean().optional(),
+    /** 0..0.5 — fade band width as a fraction of the image. Default 0.25. */
+    width: z.number().min(0).max(0.5).optional(),
+  })
+  .strict();
+export type ImageFade = z.infer<typeof imageFadeSchema>;
+
+/**
+ * RFC-0118: explicit parallax config. Mirrors RFC-0106 ParallaxVariant for
+ * vocabulary consistency.
+ */
+export const sectionImageParallaxSchema = z
+  .object({
+    variant: z.enum(["subtle", "balanced", "dramatic"]).optional(),
+    /** 0..2; takes precedence over variant default. */
+    speed: z.number().min(0).max(2).optional(),
+    respectReducedMotion: z.boolean().optional(),
+  })
+  .strict();
+export type SectionImageParallax = z.infer<typeof sectionImageParallaxSchema>;
+
+/**
+ * RFC-0118: section image parallax accepts three authoring forms:
+ *  - boolean — true is equivalent to { variant: "balanced" }; false disables.
+ *  - number  — direct speed (0..2).
+ *  - object  — { variant, speed, respectReducedMotion }.
+ */
+export const sectionImageParallaxPropSchema = z.union([
+  z.boolean(),
+  z.number().min(0).max(2),
+  sectionImageParallaxSchema,
+]);
+export type SectionImageParallaxProp = z.infer<typeof sectionImageParallaxPropSchema>;
+
+export const sectionImagePropsSchema = z
+  .object({
+    /** Bare image name (RFC-0053). */
+    imageName: z.string().min(1),
+    alt: z.string().min(1),
+    fit: z.enum(["cover", "contain"]).optional(),
+    quality: z.enum(["low", "mid", "high", "max"]).optional(),
+    loading: z.enum(["eager", "lazy"]).optional(),
+    aspectRatio: z.string().optional(),
+    fade: imageFadeSchema.optional(),
+    parallax: sectionImageParallaxPropSchema.optional(),
+    /** RFC-0202: opt-in living photo — looping sibling `<imageName>.webm` over this image. */
+    live: livePhotoSchema.optional(),
+    lang: z.string().optional(),
+    subPath: z.string().optional(),
+  })
+  .strict();
+export type SectionImageProps = z.infer<typeof sectionImagePropsSchema>;

package/src/share/schemas/section-motion.ts

@@ -0,0 +1,52 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+[RFC-0106] Canonical SectionMotionConfig. Consumed by <SectionShell motion>;
+the shell emits data-motion-reveal / data-motion-stagger / data-parallax-speed
+attributes that the GSAP scripts pick up via selectors.
+</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const revealVariantSchema = z.enum(["fade", "fade-up", "fade-up-stagger"]);
+export type RevealVariant = z.infer<typeof revealVariantSchema>;
+
+export const parallaxVariantSchema = z.enum(["subtle", "balanced", "dramatic"]);
+export type ParallaxVariant = z.infer<typeof parallaxVariantSchema>;
+
+export const sectionMotionConfigSchema = z
+  .object({
+    reveal: z
+      .object({
+        variant: revealVariantSchema.optional(),
+        once: z.boolean().optional(),
+        threshold: z.number().min(0).max(1).optional(),
+      })
+      .strict()
+      .optional(),
+    parallax: z
+      .object({
+        variant: parallaxVariantSchema.optional(),
+        speed: z.number().min(0).max(2).optional(),
+      })
+      .strict()
+      .optional(),
+    stagger: z
+      .object({
+        delay: z.number().min(0).max(2).optional(),
+        childSelector: z.string().optional(),
+      })
+      .strict()
+      .optional(),
+    off: z.boolean().optional(),
+  })
+  .strict();
+export type SectionMotionConfig = z.infer<typeof sectionMotionConfigSchema>;

package/src/share/schemas/section-shell.ts

@@ -0,0 +1,63 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+[RFC-0101] Canonical SectionShellProps — the typed contract for the universal
+<SectionShell> wrapper used by every shared section in packages/ui. Section
+content and authoring shape live in RFC-0102 (header) and RFC-0103 (body); this
+module owns visual + structural wrapper props only.
+</purpose>
+<non-goals>
+  <item>Do not declare header, body, cta, or motion props (their own RFCs).</item>
+  <item>Do not import Astro types; this is a framework-agnostic schema module.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+import { sectionBackgroundSchema } from "./section-background.ts";
+import { effectsSchema } from "./effects.ts";
+import { sectionMotionConfigSchema } from "./section-motion.ts";
+
+export const sectionDensitySchema = z.enum(["compact", "normal", "spacious"]);
+export type SectionDensity = z.infer<typeof sectionDensitySchema>;
+
+export const sectionToneSchema = z.enum(["default", "warning", "success", "muted"]);
+export type SectionTone = z.infer<typeof sectionToneSchema>;
+
+export const sectionContainerVariantSchema = z.enum(["default", "narrow", "full"]);
+export type SectionContainerVariant = z.infer<typeof sectionContainerVariantSchema>;
+
+export const sectionShellAnimatedSchema = z.enum(["none", "reveal"]);
+export type SectionShellAnimated = z.infer<typeof sectionShellAnimatedSchema>;
+
+export const sectionShellPropsSchema = z
+  .object({
+    /** BEM prefix for the section, e.g. "transparency". Used for data attributes. */
+    slug: z.string().min(1),
+    /** Anchor id (resolved by resolveSectionAnchor upstream). */
+    sectionId: z.string().optional(),
+    /** Zero-padded section index — used to generate unique ARIA IDs per section instance. */
+    sectionNumber: z.string().optional(),
+    ariaLabel: z.string().optional(),
+    ariaLabelledBy: z.string().optional(),
+    background: sectionBackgroundSchema.optional(),
+    effects: effectsSchema.optional(),
+    density: sectionDensitySchema.optional(),
+    tone: sectionToneSchema.optional(),
+    containerVariant: sectionContainerVariantSchema.optional(),
+    /**
+     * RFC-0106 motion bridge. `reveal` opts the section into the platform
+     * reveal animation when the biome motion stance permits it. Full motion
+     * config (parallax, stagger) lives on a sibling `motion` prop introduced
+     * by RFC-0106; this enum is the minimal hook landed with RFC-0101.
+     */
+    animated: sectionShellAnimatedSchema.optional(),
+    /** RFC-0106: full motion config (reveal / parallax / stagger / off). */
+    motion: sectionMotionConfigSchema.optional(),
+  })
+  .strict();
+
+export type SectionShellProps = z.infer<typeof sectionShellPropsSchema>;

package/src/share/schemas/section-stats.ts

@@ -0,0 +1,37 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+[RFC-0103] Canonical StatItem schema consumed by <SectionStats>.
+GSAP scroll-triggered counter animation (RFC-0040) hooks into the optional
+numericValue / prefix / suffix / decimals / duration fields.
+</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const statItemSchema = z
+  .object({
+    /** Static display fallback — always required so SSR renders something before JS runs. */
+    value: z.string().min(1),
+    label: z.string().min(1),
+    /** Numeric target for the GSAP counter; absent means the value renders statically. */
+    numericValue: z.number().optional(),
+    /** Symbol rendered before the number (e.g. "€"). */
+    prefix: z.string().optional(),
+    /** Unit rendered after the number (e.g. "+", "%", "K"). */
+    suffix: z.string().optional(),
+    /** Decimal places for Intl.NumberFormat. Default 0. */
+    decimals: z.number().int().nonnegative().optional(),
+    /** GSAP tween duration in seconds. Default 1.8. */
+    duration: z.number().positive().optional(),
+  })
+  .strict();
+
+export type StatItem = z.infer<typeof statItemSchema>;

package/src/share/schemas/site-background.ts

@@ -0,0 +1,78 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+[RFC-0105] Canonical SiteBackgroundConfig — global viewport background shell
+block, independent of section-level SectionBackground.
+</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+const colorLayer = z
+  .object({
+    kind: z.literal("color"),
+    color: z.string().min(1).optional(),
+  })
+  .strict();
+
+const imageLayer = z
+  .object({
+    kind: z.literal("image"),
+    imageName: z.string().min(1),
+    fit: z.enum(["cover", "tile", "stretch-width", "stretch-height"]).optional(),
+    quality: z.enum(["low", "mid", "high", "max"]).optional(),
+    loading: z.enum(["eager", "lazy"]).optional(),
+    tint: z
+      .object({
+        color: z.string().min(1).optional(),
+        opacity: z.number().min(0).max(1).optional(),
+      })
+      .strict()
+      .optional(),
+    parallax: z
+      .object({
+        speed: z.number().min(0).max(2).optional(),
+        respectReducedMotion: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+const gradientStop = z
+  .object({
+    at: z.number().min(0).max(1),
+    color: z.string().min(1),
+    opacity: z.number().min(0).max(1).optional(),
+  })
+  .strict();
+
+const gradientLayer = z
+  .object({
+    kind: z.literal("gradient"),
+    direction: z.enum(["vertical", "horizontal", "radial"]),
+    stops: z.array(gradientStop).min(2),
+  })
+  .strict();
+
+export const siteBackgroundLayerSchema = z.discriminatedUnion("kind", [
+  colorLayer,
+  imageLayer,
+  gradientLayer,
+]);
+export type SiteBackgroundLayer = z.infer<typeof siteBackgroundLayerSchema>;
+
+export const siteBackgroundConfigSchema = z
+  .object({
+    layers: z.array(siteBackgroundLayerSchema).min(1),
+    lang: z.string().optional(),
+  })
+  .strict();
+export type SiteBackgroundConfig = z.infer<typeof siteBackgroundConfigSchema>;

package/src/share/schemas/standard-list-item.ts

@@ -0,0 +1,38 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+[RFC-0100 + RFC-0103] Canonical StandardListItem schema mirrored in
+@warpgogol/werkstatt-shared/share so body components can validate items without importing from
+@warpgogol/werkstatt-site/ui (which would create a cyclic dependency). The same shape is
+re-exported by @warpgogol/werkstatt-site/ui/icons/icon-resolver for backwards compatibility.
+</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const vendorIconConfigSchema = z
+  .object({
+    vendor: z.string().min(1),
+    collection: z.string().min(1),
+    name: z.string().min(1),
+    size: z.number().int().positive().optional(),
+  })
+  .strict();
+
+export type VendorIconConfig = z.infer<typeof vendorIconConfigSchema>;
+
+export const standardListItemSchema = z
+  .object({
+    text: z.string().min(1),
+    icon: vendorIconConfigSchema.optional(),
+  })
+  .strict();
+
+export type StandardListItem = z.infer<typeof standardListItemSchema>;

package/src/share/scripts/external-links.ts

@@ -0,0 +1,45 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Applies security attributes to external anchor elements on the page.</purpose>
+<non-goals>
+  <item>Do not handle internal navigation or routing.</item>
+  <item>Do not modify non-HTTP links (mailto:, tel:, etc.).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0011 Phase 2: Extracted from layout.astro inline script into src/scripts canonical pattern.</item>
+  <item>Migrated to @warpgogol/werkstatt-shared/share/scripts for platform-wide reuse.</item>
+</CHANGE_SUMMARY>
+*/
+
+// @ai-invariant: This function must only modify external HTTP/HTTPS links. Never touch mailto:, tel:, or internal links.
+export function applyExternalLinkBehavior(): void {
+  const anchors = document.querySelectorAll("a[href]");
+
+  for (const anchor of anchors) {
+    const href = anchor.getAttribute("href");
+
+    if (!href) {
+      continue;
+    }
+
+    let resolvedUrl;
+
+    try {
+      resolvedUrl = new URL(href, window.location.href);
+    } catch {
+      continue;
+    }
+
+    const isHttpLink = resolvedUrl.protocol === "http:" || resolvedUrl.protocol === "https:";
+    const isExternalLink = isHttpLink && resolvedUrl.origin !== window.location.origin;
+
+    if (!isExternalLink) {
+      continue;
+    }
+
+    anchor.setAttribute("data-external-link", "1");
+    anchor.setAttribute("target", "_blank");
+    anchor.setAttribute("rel", "noopener noreferrer");
+  }
+}