astro-component-kit 0.0.1 → 0.1.0

package/src/components/lib/Galaxy3D.astro

@@ -0,0 +1,308 @@
+---
+interface Props {
+  className?: string;
+}
+
+const { className = '' } = Astro.props;
+---
+
+<div class="galaxy-3d-container {className}" id="galaxy-3d-wrapper">
+  <canvas id="galaxy-3d-canvas"></canvas>
+</div>
+
+<style>
+  .galaxy-3d-container {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    z-index: 0;
+    pointer-events: none;
+  }
+  #galaxy-3d-canvas {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+  }
+</style>
+
+<script is:inline>
+  (async function() {
+    const THREE = await import('https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.module.js');
+
+    const canvas = document.getElementById('galaxy-3d-canvas');
+    if (!canvas) return;
+
+    const container = canvas.parentElement;
+    if (!container) return;
+
+    // Scene setup
+    const scene = new THREE.Scene();
+    const camera = new THREE.PerspectiveCamera(75, 1, 0.1, 100);
+    camera.position.set(0, 0, 5);
+    camera.lookAt(0, 0, 0);
+
+    const renderer = new THREE.WebGLRenderer({ canvas, alpha: true, antialias: true });
+    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+
+    function resize() {
+      const w = container.clientWidth;
+      const h = container.clientHeight;
+      renderer.setSize(w, h);
+      camera.aspect = w / h;
+      camera.updateProjectionMatrix();
+    }
+
+    resize();
+    window.addEventListener('resize', resize);
+
+    // Corporate color palette (gold, white, subtle blue accents)
+    const galaxyColors = [
+      new THREE.Color('#fef3c7'), // Light gold
+      new THREE.Color('#fbbf24'), // Gold
+      new THREE.Color('#d4a017'), // Dark gold
+      new THREE.Color('#ffffff'), // White
+      new THREE.Color('#b8860b'), // Darker gold
+    ];
+
+    const bgStarColors = [
+      new THREE.Color('#ffffff'),
+      new THREE.Color('#fef3c7'),
+      new THREE.Color('#fde68a'),
+    ];
+
+    // ========== GALAXY ==========
+    const galaxyParams = {
+      count: 8000,
+      size: 0.025,
+      radius: 2.8,
+      branches: 5,
+      spin: 1.5,
+      randomness: 0.35,
+      randomnessPower: 2.5,
+      colors: galaxyColors,
+    };
+
+    function createGalaxy() {
+      const geometry = new THREE.BufferGeometry();
+      const positions = new Float32Array(galaxyParams.count * 3);
+      const colors = new Float32Array(galaxyParams.count * 3);
+      const sizes = new Float32Array(galaxyParams.count);
+      const randomness = new Float32Array(galaxyParams.count);
+
+      for (let i = 0; i < galaxyParams.count; i++) {
+        const i3 = i * 3;
+        const radius = Math.random() * galaxyParams.radius;
+        const spinAngle = radius * galaxyParams.spin;
+        const branchIndex = i % galaxyParams.branches;
+        const branchAngle = (branchIndex / galaxyParams.branches) * Math.PI * 2;
+
+        const power = galaxyParams.randomnessPower;
+        const randomX = Math.pow(Math.random(), power) * (Math.random() < 0.5 ? 1 : -1) * galaxyParams.randomness * radius;
+        const randomY = Math.pow(Math.random(), power) * (Math.random() < 0.5 ? 1 : -1) * galaxyParams.randomness * radius * 0.15;
+        const randomZ = Math.pow(Math.random(), power) * (Math.random() < 0.5 ? 1 : -1) * galaxyParams.randomness * radius;
+
+        const angle = branchAngle + spinAngle;
+        positions[i3] = Math.cos(angle) * radius + randomX;
+        positions[i3 + 1] = randomY;
+        positions[i3 + 2] = Math.sin(angle) * radius + randomZ;
+
+        // Color based on radius
+        const colorIndex = Math.floor(Math.random() * galaxyColors.length);
+        const color = galaxyColors[colorIndex];
+        const mixFactor = Math.random() * 0.3 + (radius / galaxyParams.radius) * 0.7;
+        const finalColor = color.clone().lerp(galaxyColors[(colorIndex + 1) % galaxyColors.length], mixFactor);
+
+        colors[i3] = finalColor.r;
+        colors[i3 + 1] = finalColor.g;
+        colors[i3 + 2] = finalColor.b;
+
+        sizes[i] = (Math.random() + 0.8) * galaxyParams.size;
+        randomness[i] = Math.random();
+
+        // Store for animation
+        randomness[i3] = randomX;
+        randomness[i3 + 1] = randomY;
+        randomness[i3 + 2] = randomZ;
+      }
+
+      geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+      geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+      geometry.setAttribute('size', new THREE.BufferAttribute(sizes, 1));
+
+      const material = new THREE.PointsMaterial({
+        size: galaxyParams.size,
+        sizeAttenuation: true,
+        depthWrite: false,
+        blending: THREE.AdditiveBlending,
+        vertexColors: true,
+        transparent: true,
+        opacity: 0.85,
+      });
+
+      const points = new THREE.Points(geometry, material);
+      // Tilt the galaxy slightly for dramatic effect
+      points.rotation.x = -0.3;
+      points.rotation.z = 0.15;
+      scene.add(points);
+
+      return { points, geometry };
+    }
+
+    const galaxy = createGalaxy();
+
+    // ========== BACKGROUND STARS ==========
+    const bgStarsParams = {
+      count: 1500,
+      size: 0.012,
+      spread: 15,
+    };
+
+    function createBgStars() {
+      const geometry = new THREE.BufferGeometry();
+      const positions = new Float32Array(bgStarsParams.count * 3);
+      const colors = new Float32Array(bgStarsParams.count * 3);
+      const opacities = new Float32Array(bgStarsParams.count);
+
+      for (let i = 0; i < bgStarsParams.count; i++) {
+        const i3 = i * 3;
+        positions[i3] = (Math.random() - 0.5) * bgStarsParams.spread;
+        positions[i3 + 1] = (Math.random() - 0.5) * bgStarsParams.spread;
+        positions[i3 + 2] = (Math.random() - 0.5) * bgStarsParams.spread * 0.5 - 3;
+
+        const color = bgStarColors[Math.floor(Math.random() * bgStarColors.length)];
+        colors[i3] = color.r;
+        colors[i3 + 1] = color.g;
+        colors[i3 + 2] = color.b;
+
+        opacities[i] = Math.random() * 0.5 + 0.2;
+      }
+
+      geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+      geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+
+      const material = new THREE.PointsMaterial({
+        size: bgStarsParams.size,
+        sizeAttenuation: true,
+        depthWrite: false,
+        transparent: true,
+        opacity: 0.5,
+        vertexColors: true,
+        blending: THREE.AdditiveBlending,
+      });
+
+      const stars = new THREE.Points(geometry, material);
+      scene.add(stars);
+      return stars;
+    }
+
+    const bgStars = createBgStars();
+
+    // ========== CENTRAL GLOW ==========
+    const glowGeometry = new THREE.SphereGeometry(0.3, 16, 16);
+    const glowMaterial = new THREE.MeshBasicMaterial({
+      color: new THREE.Color('#fef3c7'),
+      transparent: true,
+      opacity: 0.15,
+    });
+    const glow = new THREE.Mesh(glowGeometry, glowMaterial);
+    glow.position.z = -0.2;
+    scene.add(glow);
+
+    // ========== AMBIENT PARTICLES (floating dust) ==========
+    const dustCount = 500;
+    const dustGeometry = new THREE.BufferGeometry();
+    const dustPositions = new Float32Array(dustCount * 3);
+    const dustColors = new Float32Array(dustCount * 3);
+
+    for (let i = 0; i < dustCount; i++) {
+      const i3 = i * 3;
+      dustPositions[i3] = (Math.random() - 0.5) * 6;
+      dustPositions[i3 + 1] = (Math.random() - 0.5) * 3;
+      dustPositions[i3 + 2] = (Math.random() - 0.5) * 2;
+
+      const color = galaxyColors[Math.floor(Math.random() * galaxyColors.length)];
+      dustColors[i3] = color.r;
+      dustColors[i3 + 1] = color.g;
+      dustColors[i3 + 2] = color.b;
+    }
+
+    dustGeometry.setAttribute('position', new THREE.BufferAttribute(dustPositions, 3));
+    dustGeometry.setAttribute('color', new THREE.BufferAttribute(dustColors, 3));
+
+    const dustMaterial = new THREE.PointsMaterial({
+      size: 0.008,
+      sizeAttenuation: true,
+      depthWrite: false,
+      transparent: true,
+      opacity: 0.3,
+      vertexColors: true,
+      blending: THREE.AdditiveBlending,
+    });
+
+    const dust = new THREE.Points(dustGeometry, dustMaterial);
+    scene.add(dust);
+
+    // ========== MOUSE INTERACTION ==========
+    const mouse = { x: 0, y: 0 };
+    let targetMouseX = 0;
+    let targetMouseY = 0;
+
+    container.addEventListener('mousemove', (e) => {
+      const rect = canvas.getBoundingClientRect();
+      targetMouseX = ((e.clientX - rect.left) / rect.width) * 2 - 1;
+      targetMouseY = -((e.clientY - rect.top) / rect.height) * 2 + 1;
+    });
+
+    container.addEventListener('mouseleave', () => {
+      targetMouseX = 0;
+      targetMouseY = 0;
+    });
+
+    // ========== ANIMATION ==========
+    const clock = new THREE.Clock();
+
+    function animate() {
+      requestAnimationFrame(animate);
+      const elapsed = clock.getElapsedTime();
+
+      // Smooth mouse movement
+      mouse.x += (targetMouseX - mouse.x) * 0.05;
+      mouse.y += (targetMouseY - mouse.y) * 0.05;
+
+      // Rotate galaxy slowly
+      if (galaxy.points) {
+        galaxy.points.rotation.y = elapsed * 0.06;
+      }
+
+      // Rotate background stars
+      bgStars.rotation.y = elapsed * 0.01;
+      bgStars.rotation.x = elapsed * 0.005;
+
+      // Animate dust particles
+      const dustPos = dust.geometry.attributes.position.array;
+      for (let i = 0; i < dustCount; i++) {
+        const i3 = i * 3;
+        dustPos[i3] += Math.sin(elapsed + i) * 0.0003;
+        dustPos[i3 + 1] += Math.cos(elapsed * 0.8 + i) * 0.0002;
+      }
+      dust.geometry.attributes.position.needsUpdate = true;
+
+      // Central glow pulse
+      const pulseScale = 1 + Math.sin(elapsed * 2) * 0.1;
+      glow.scale.set(pulseScale, pulseScale, pulseScale);
+      glowMaterial.opacity = 0.12 + Math.sin(elapsed * 2) * 0.03;
+
+      // Camera follows mouse slightly
+      camera.position.x = mouse.x * 0.3;
+      camera.position.y = mouse.y * 0.3;
+      camera.lookAt(0, 0, 0);
+
+      renderer.render(scene, camera);
+    }
+
+    animate();
+  })();
+</script>

package/src/components/lib/GlassNavbar.astro

@@ -1,15 +1,18 @@
 ---
 // src/components/lib/GlassNavbar.astro
+import LogoWithGalaxy from './LogoWithGalaxy.astro';
+
 interface Props {
-  brand?: string;
   brandHref?: string;
 }
-const { brand = 'Astro Components', brandHref = '/' } = Astro.props;
+const { brandHref = '/' } = Astro.props;
 ---
 
 <header class="glass-nav">
   <div class="glass-nav__inner">
-    <a href={brandHref} class="glass-nav__brand">{brand}</a>
+    <a href={brandHref} class="glass-nav__brand">
+      <LogoWithGalaxy size="small" />
+    </a>
     <nav class="glass-nav__links">
       <slot name="links" />
     </nav>
@@ -29,22 +32,21 @@ const { brand = 'Astro Components', brandHref = '/' } = Astro.props;
 
   .glass-nav__inner {
     padding: 0 1.5rem;
-    height: 56px;
+    height: 70px;
     display: flex;
     align-items: center;
     gap: 2rem;
   }
 
   .glass-nav__brand {
-    font-size: 1rem;
-    font-weight: 800;
-    color: #f1f5f9;
     text-decoration: none;
-    background: linear-gradient(135deg, #818cf8, #c084fc);
-    -webkit-background-clip: text;
-    -webkit-text-fill-color: transparent;
-    background-clip: text;
     flex-shrink: 0;
+    display: flex;
+    align-items: center;
+  }
+
+  .glass-nav__brand:hover {
+    opacity: 0.9;
   }
 
   .glass-nav__links {

package/src/components/lib/LogoWithGalaxy.astro

@@ -0,0 +1,63 @@
+---
+import AnimatedGalaxy from './AnimatedGalaxy.astro';
+
+interface Props {
+  size?: 'small' | 'medium' | 'large';
+  className?: string;
+}
+
+const { size = 'medium', className = '' } = Astro.props;
+
+const sizes = {
+  small: { logoHeight: '36px', galaxyWidth: '160px', galaxyHeight: '96px', galaxyTop: '-5px', galaxyLeft: '-40px' },
+  medium: { logoHeight: '48px', galaxyWidth: '220px', galaxyHeight: '132px', galaxyTop: '0px', galaxyLeft: '-55px' },
+  large: { logoHeight: '70px', galaxyWidth: '320px', galaxyHeight: '192px', galaxyTop: '5px', galaxyLeft: '-70px' },
+};
+
+const s = sizes[size];
+---
+
+<div class="logo-container {className}">
+  <!-- Galaxy behind, bottom-left -->
+  <div class="galaxy-wrap">
+    <AnimatedGalaxy class="galaxy-svg" style={`width: ${s.galaxyWidth}; height: ${s.galaxyHeight};`} />
+  </div>
+  <!-- Logo text on top -->
+  <div class="logo-text">
+    <img src="/logo.svg" alt="Astro Kit Components" />
+  </div>
+</div>
+
+<style>
+  .logo-container {
+    position: relative;
+    display: inline-block;
+    vertical-align: middle;
+  }
+
+  .galaxy-wrap {
+    position: absolute;
+    top: v-bind('s.galaxyTop');
+    left: v-bind('s.galaxyLeft');
+    z-index: 0;
+    pointer-events: none;
+    overflow: visible;
+  }
+
+  .galaxy-wrap :global(.galaxy-svg) {
+    display: block;
+    opacity: 0.7;
+  }
+
+  .logo-text {
+    position: relative;
+    z-index: 2;
+    display: block;
+  }
+
+  .logo-text img {
+    height: v-bind('s.logoHeight');
+    width: auto;
+    display: block;
+  }
+</style>

package/src/components/lib/buttons/3dPushButton.astro

@@ -1,4 +1,13 @@
 ---
+/**
+ * 3dPushButton — A satisfying tactile 3D button that depresses when clicked, with depth layers.
+ * 
+ * @param {string} href - Optional. If provided, renders an <a> tag instead of <button>.
+ * @param {'button'|'submit'|'reset'} type - Optional. The HTML button type. Default is 'button'.
+ * @param {string} color - Optional. The base color to generate the 3D depth shades from. Default is '#3b82f6'.
+ * @param {'sm'|'md'|'lg'} size - Optional. The size variant of the button. Default is 'md'.
+ * @param {boolean} disabled - Optional. Whether the button is disabled. Default is false.
+ */
 interface Props {
   href?: string;
   type?: 'button' | 'submit' | 'reset';

package/src/components/lib/buttons/AnimatedIconButton.astro

@@ -1,4 +1,14 @@
 ---
+/**
+ * AnimatedIconButton — A button that elegantly slides an icon into view on hover.
+ * 
+ * @param {string} href - Optional. If provided, renders an <a> tag instead of <button>.
+ * @param {'button'|'submit'|'reset'} type - Optional. The HTML button type. Default is 'button'.
+ * @param {'primary'|'secondary'|'ghost'} variant - Optional. The visual style variant. Default is 'primary'.
+ * @param {'sm'|'md'|'lg'} size - Optional. The size variant of the button. Default is 'md'.
+ * @param {'left'|'right'} iconPos - Optional. Side where the icon slides in. Default is 'right'.
+ * @param {boolean} disabled - Optional. Whether the button is disabled. Default is false.
+ */
 interface Props {
   href?: string;
   type?: 'button' | 'submit' | 'reset';

package/src/components/lib/buttons/BorderDrawButton.astro

@@ -1,4 +1,13 @@
 ---
+/**
+ * BorderDrawButton — A button that animates its SVG border being drawn on hover.
+ * 
+ * @param {string} href - Optional. If provided, renders an <a> tag instead of <button>.
+ * @param {'button'|'submit'|'reset'} type - Optional. The HTML button type. Default is 'button'.
+ * @param {string} color - Optional. The stroke color of the drawing border. Default is '#3b82f6'.
+ * @param {'sm'|'md'|'lg'} size - Optional. The size variant of the button. Default is 'md'.
+ * @param {boolean} disabled - Optional. Whether the button is disabled. Default is false.
+ */
 interface Props {
   href?: string;
   type?: 'button' | 'submit' | 'reset';

package/src/components/lib/buttons/CyberpunkButton.astro

@@ -1,4 +1,14 @@
 ---
+/**
+ * CyberpunkButton — A glitchy, neon-styled button inspired by futuristic sci-fi aesthetics.
+ * 
+ * @param {string} href - Optional. If provided, renders an <a> tag instead of <button>.
+ * @param {'button'|'submit'|'reset'} type - Optional. The HTML button type. Default is 'button'.
+ * @param {string} primaryColor - Optional. The main neon background. Default is '#ff003c'.
+ * @param {string} secondaryColor - Optional. The glitch accent. Default is '#00e0ff'.
+ * @param {'sm'|'md'|'lg'} size - Optional. The size variant of the button. Default is 'md'.
+ * @param {string} label - Optional. Text used exclusively for duplicate glitch iterations. Default is 'READY'.
+ */
 interface Props {
   href?: string;
   type?: 'button' | 'submit' | 'reset';

package/src/components/lib/buttons/DoubleBorderButton.astro

@@ -1,4 +1,13 @@
 ---
+/**
+ * DoubleBorderButton — A button with a sophisticated offset double-border effect and sleek hover transitions.
+ * 
+ * @param {string} href - Optional. If provided, renders an <a> tag instead of <button>.
+ * @param {'button'|'submit'|'reset'} type - Optional. The HTML button type. Default is 'button'.
+ * @param {'primary'|'secondary'|'ghost'} variant - Optional. The visual style variant. Default is 'primary'.
+ * @param {'sm'|'md'|'lg'} size - Optional. The size variant of the button. Default is 'md'.
+ * @param {boolean} disabled - Optional. Whether the button is disabled. Default is false.
+ */
 interface Props {
   href?: string;
   type?: 'button' | 'submit' | 'reset';

package/src/components/lib/buttons/GhostOutlineButton.astro

@@ -1,4 +1,14 @@
 ---
+/**
+ * GhostOutlineButton — A minimalist transparent button with gradient outlines and animated borders.
+ * 
+ * @param {string} href - Optional. If provided, renders an <a> tag instead of <button>.
+ * @param {'button'|'submit'|'reset'} type - Optional. The HTML button type. Default is 'button'.
+ * @param {string} primaryColor - Optional. Starts the gradient outline color.
+ * @param {string} secondaryColor - Optional. Ends the gradient outline color.
+ * @param {'sm'|'md'|'lg'} size - Optional. The size variant of the button. Default is 'md'.
+ * @param {boolean} disabled - Optional. Whether the button is disabled. Default is false.
+ */
 interface Props {
   href?: string;
   type?: 'button' | 'submit' | 'reset';

package/src/components/lib/buttons/GlassButton.astro

@@ -1,4 +1,13 @@
 ---
+/**
+ * GlassButton — A premium button with glassmorphism effect, gradient border and smooth hover animations.
+ * 
+ * @param {string} href - Optional. If provided, renders an <a> tag instead of <button>.
+ * @param {'button'|'submit'|'reset'} type - Optional. The HTML button type. Default is 'button'.
+ * @param {'primary'|'secondary'|'ghost'} variant - Optional. The visual style variant. Default is 'primary'.
+ * @param {'sm'|'md'|'lg'} size - Optional. The size variant of the button. Default is 'md'.
+ * @param {boolean} disabled - Optional. Whether the button is disabled. Default is false.
+ */
 interface Props {
   href?: string;
   type?: 'button' | 'submit' | 'reset';
@@ -10,32 +19,10 @@ interface Props {
 const { href, type = 'button', variant = 'primary', size = 'md', disabled = false } = Astro.props;
 const Tag = href ? 'a' : 'button';
 ---
-<Tag 
-  href={href} 
+<Tag
+  href={href}
   type={href ? undefined : type}
-  disabled={disabled} 
-  class={`glass-btn glass-btn--${variant} glass-btn--${size}`}
->
-  <slot />
-</Tag>
-
-<style>
----
-interface Props {
-  href?: string;
-  type?: 'button' | 'submit' | 'reset';
-  variant?: 'primary' | 'secondary' | 'ghost';
-  size?: 'sm' | 'md' | 'lg';
-  disabled?: boolean;
-}
-
-const { href, type = 'button', variant = 'primary', size = 'md', disabled = false } = Astro.props;
-const Tag = href ? 'a' : 'button';
----
-<Tag 
-  href={href} 
-  type={href ? undefined : type}
-  disabled={disabled} 
+  disabled={disabled}
   class={`glass-btn glass-btn--${variant} glass-btn--${size}`}
 >
   <span class="glass-btn__shimmer"></span>
@@ -50,7 +37,7 @@ const Tag = href ? 'a' : 'button';
     --btn-border: rgba(255, 255, 255, 0.1);
     --btn-text: var(--c-text-1, #d4d4d4);
     --btn-glow: rgba(184, 134, 11, 0);
-    
+
     display: inline-flex;
     align-items: center;
     justify-content: center;
@@ -73,7 +60,6 @@ const Tag = href ? 'a' : 'button';
     color: var(--btn-text);
   }
 
-  /* Shimmer Effect */
   .glass-btn__shimmer {
     position: absolute;
     inset: 0;
@@ -94,7 +80,6 @@ const Tag = href ? 'a' : 'button';
     transform: translateX(100%);
   }
 
-  /* Glass Border Glow */
   .glass-btn::after {
     content: '';
     position: absolute;
@@ -130,7 +115,6 @@ const Tag = href ? 'a' : 'button';
     filter: grayscale(1);
   }
 
-  /* Variants */
   .glass-btn--primary {
     --btn-bg: linear-gradient(135deg, rgba(184, 134, 11, 0.7), rgba(212, 160, 23, 0.7));
     --btn-text: #0a0a0a;
@@ -156,10 +140,7 @@ const Tag = href ? 'a' : 'button';
     border-color: rgba(184, 134, 11, 0.4);
   }
 
-  /* Sizes */
   .glass-btn--sm { padding: 0.45rem 1.1rem; font-size: 0.85rem; }
   .glass-btn--md { padding: 0.75rem 1.6rem; font-size: 0.95rem; }
   .glass-btn--lg { padding: 1.1rem 2.4rem; font-size: 1.1rem; }
 </style>
-</style>
-

package/src/components/lib/buttons/GlowButton.astro

@@ -1,4 +1,13 @@
 ---
+/**
+ * GlowButton — A button with an animated glow effect that pulsates on hover.
+ * 
+ * @param {string} color - Optional. The base color for the glow effect. Default is '#6366f1'.
+ * @param {string} href - Optional. If provided, renders an <a> tag instead of <button>.
+ * @param {'button'|'submit'|'reset'} type - Optional. The HTML button type. Default is 'button'.
+ * @param {'sm'|'md'|'lg'} size - Optional. The size variant of the button. Default is 'md'.
+ * @param {boolean} disabled - Optional. Whether the button is disabled. Default is false.
+ */
 interface Props {
   color?: string;
   href?: string;

package/src/components/lib/buttons/LiquidButton.astro

@@ -1,4 +1,13 @@
 ---
+/**
+ * LiquidButton — A button featuring a fluid, liquid-like animated background layer.
+ * 
+ * @param {string} href - Optional. If provided, renders an <a> tag instead of <button>.
+ * @param {'button'|'submit'|'reset'} type - Optional. The HTML button type. Default is 'button'.
+ * @param {string} color - Optional. The base color for the fluid liquid effect. Default is '#3b82f6'.
+ * @param {'sm'|'md'|'lg'} size - Optional. The size variant of the button. Default is 'md'.
+ * @param {boolean} disabled - Optional. Whether the button is disabled. Default is false.
+ */
 interface Props {
   href?: string;
   type?: 'button' | 'submit' | 'reset';

package/src/components/lib/buttons/LoadingButton.astro

@@ -1,4 +1,14 @@
 ---
+/**
+ * LoadingButton — A button supporting async states with a built-in spinner and disabled logic.
+ * 
+ * @param {string} href - Optional. If provided, renders an <a> tag instead of <button>.
+ * @param {'button'|'submit'|'reset'} type - Optional. The HTML button type. Default is 'button'.
+ * @param {'primary'|'secondary'|'ghost'} variant - Optional. The visual style variant. Default is 'primary'.
+ * @param {'sm'|'md'|'lg'} size - Optional. The size variant of the button. Default is 'md'.
+ * @param {boolean} isLoading - Required indicator to display spinner state and lock interaction. Default is false.
+ * @param {boolean} disabled - Optional. Whether the button is strictly disabled aside from loading. Default is false.
+ */
 interface Props {
   isLoading?: boolean;
   href?: string;

package/src/components/lib/buttons/MagneticButton.astro

@@ -1,4 +1,14 @@
 ---
+/**
+ * MagneticButton — A button that physically follows the user's cursor when hovered, providing a satisfying magnetic snap effect.
+ * 
+ * @param {string} href - Optional. If provided, renders an <a> tag instead of <button>.
+ * @param {'button'|'submit'|'reset'} type - Optional. The HTML button type. Default is 'button'.
+ * @param {'primary'|'secondary'|'ghost'} variant - Optional. The visual style variant. Default is 'primary'.
+ * @param {'sm'|'md'|'lg'} size - Optional. The size variant of the button. Default is 'md'.
+ * @param {number} strength - Optional. How intense the magnetic pull effect is. Default is 40.
+ * @param {boolean} disabled - Optional. Whether the button is disabled. Default is false.
+ */
 interface Props {
   href?: string;
   type?: 'button' | 'submit' | 'reset';

package/src/components/lib/buttons/MinimalPillButton.astro

@@ -1,4 +1,13 @@
 ---
+/**
+ * MinimalPillButton — A cleanly rounded pill button optimized for minimal interactions and tags.
+ * 
+ * @param {string} href - Optional. If provided, renders an <a> tag instead of <button>.
+ * @param {'button'|'submit'|'reset'} type - Optional. The HTML button type. Default is 'button'.
+ * @param {'primary'|'secondary'|'ghost'} variant - Optional. The visual style variant. Default is 'primary'.
+ * @param {'sm'|'md'|'lg'} size - Optional. The size variant of the button. Default is 'md'.
+ * @param {boolean} disabled - Optional. Whether the button is disabled. Default is false.
+ */
 interface Props {
   href?: string;
   type?: 'button' | 'submit' | 'reset';