Astro core

astro-core is a collection of core Astro components designed to streamline asset management and simplify form creation in your Astro projects, among other features. These components provide a flexible, powerful set of tools for handling images, videos, form fields, buttons, anchor, external links, etc.

npm install @terrahq/astro-core

🚀 How to import

To use the components from astro-core, simply import them into your Astro project:

//Import example
import { Asset, ButtonLink } from "@terrahq/astro-core";

Components

Asset

/**
 * Renders an asset component (Image, Video, or Lottie) dynamically based on the type provided in the payload.
 *
 * @param {Object} Astro.props - The props object passed into the component.
 * @param {Object} Astro.props.payload - Contains asset data and options.
 * @param {string} Astro.props.payload.type - The type of the asset, which determines which component to render. Expected values are:
 *  - `"Image"`: Renders the `Image` component.
 *  - `"Video"`: Renders the `Video` component.
 *  - `"Lottie"`: Renders the `Lottie` component.
 *
 * @example Usage:
 */

<Asset
  payload={{
    type: "Image",
    url: "https://example.com/image.jpg",
    alt: "Example Image",
    customClass: "image-class",
  }}
/>

<Asset
  payload={{
    type: "Lottie",
    url: "https://example.com/animation.json",
    customClass: "my-lottie-animation",
    animType: "canvas",
    loop: true,
    autoplay: false,
    name: "myLottie"
  }}
/>

<Asset
  payload={{
    type: "Video",
    url: "https://example.com/video.mp4",
    customClass: "my-video",
    attributes: { controls: true, poster: "https://example.com/poster.jpg" },
    width: 1280,
    height: 720
  }}
/>

Type Image

/**
 * Renders an image element with lazy loading, aspect ratio, srcset, and other configurable attributes.
 * 
 * Dynamic Behavior:
 * - Lazy Loading: If `lazy` is `true`, the `data-src` and `data-srcset` attributes are used instead of `src` and `srcset`, enabling lazy loading.
 * - Aspect Ratio: If `aspectRatio` is `true` and both `width` and `height` are provided, an `aspect-ratio` style is applied to maintain the image's aspect ratio.
 * - Srcset: Automatically generates a `srcset` for responsive images if `width` is provided in the `attributes`.
 *
 * @param {Object} Astro.props - The props object passed into the component.
 * @param {Object} Astro.props.payload - Contains image-related data and options.
 * @param {string} Astro.props.payload.url - The image URL.
 * @param {string} [Astro.props.payload.sizes] - The sizes attribute for responsive images.
 * @param {string} [Astro.props.payload.alt] - The alt text for the image (important for accessibility).
 * @param {string} [Astro.props.payload.customClass] - Custom classes to apply to the image.
 * @param {boolean} [Astro.props.payload.lazy=true] - Enables lazy loading for the image. Default is `true`.
 * @param {boolean} [Astro.props.payload.aspectRatio=true] - Enables aspect ratio styling for the image. Default is `true`.
 * @param {boolean} [Astro.props.payload.decodingAsync=true] - Determines if the image should be decoded asynchronously. Default is `true`.
 * @param {boolean} [Astro.props.payload.fetchPriority=false] - Determines if the image should have high fetch priority. Default is `false`.
 * @param {Object} [Astro.props.payload.attributes] - Additional image attributes like width, height, etc.
 *
 * @example Usage:
 */

 <Asset
   payload={{
     type: "Image",
     url: "https://example.com/image.jpg",
     sizes: "(max-width: 600px) 480px, 800px",
     alt: "Example image",
     customClass: "image-class",
     lazy: true,
     aspectRatio: true,
     decodingAsync: true,
     fetchPriority: true,
     attributes: {
       width: 1024,
       height: 768
     }
   }}
 />

Type Video

/**
 * Renders a video component based on the `payload` properties.
 *
 * @param {Object} Astro.props - The props object passed into the component.
 * @param {Object} Astro.props.payload - Contains video data and options.
 * @param {boolean} Astro.props.payload.isBoostify - Whether the video uses Boostify integration.
 * @param {string} Astro.props.payload.video_type - The type of video source: "url" or "file".
 * @param {string} Astro.props.payload.video_url - The URL of the video (for embeds).
 * @param {string} Astro.props.payload.video_file - The file path of the video (for file-based rendering).
 * @param {string} Astro.props.payload.format - Video format (e.g., mp4).
 * @param {string} Astro.props.payload.poster_url - Poster image URL for the video.
 * @param {boolean} Astro.props.payload.hasPosterImg - Indicates if a poster image slot is provided.
 * @param {string} Astro.props.payload.customClass - Custom CSS class for styling.
 * @param {string} Astro.props.payload.boostifyClass - CSS class for Boostify integration.
 * @param {number} Astro.props.payload.width - Width of the video.
 * @param {number} Astro.props.payload.height - Height of the video.
 * 
 * @example Usage:
 */

<Asset
  payload={{
    type: "Video",    
    video_type: 'url',
    video_url: 'https://www.youtube.com/watch?v=your-video-id',
    customClass: 'video-class',
    isBoostify: false,
  }}
/>

<Asset
  payload={{
    type: "Video",    
    video_type: 'file',
    video_file: '/asset/video/placeholder.mp4',
    hasPosterImg: true,
    poster_url: 'https://example.com/image.jpg'
    customClass: 'video-class',
  }}
/>

Type Lottie

:warning: For lotties use dependency @terrahq/helpers.

/**
 * Renders a Lottie animation element using a `div` with custom data attributes.
 *
 * @param {Object} Astro.props - The props object passed into the component.
 * @param {Object} Astro.props.payload - Contains Lottie-related data and options.
 * @param {string} Astro.props.payload.url - The URL to the Lottie JSON animation file.
 * @param {string} [Astro.props.payload.customClass] - Custom classes to apply to the Lottie `div`.
 * @param {string} [Astro.props.payload.animType="svg"] - The type of animation format.
 * @param {boolean} [Astro.props.payload.loop=true] - Whether the animation should loop. Default is `true`.
 * @param {boolean} [Astro.props.payload.autoplay=false] - Whether the animation should start playing automatically. Default is `true`.
 * @param {string} [Astro.props.payload.name="lottie-asset"] - The name identifier for the Lottie animation instance. Default is `"lottie-asset"`.
 *
 * @example Usage:
 */

 <Asset
   payload={{
    type: "Lottie",
    url: "https://example.com/animation.json",
    customClass: "my-lottie-animation",
    animType: "canvas",
    loop: true,
    autoplay: false,
    name: "myLottie"
   }}
 />

Button Link

/**
 * @param {Object} payload - The configuration object for the link/button.
 * @param {string} [payload.href] - URL for external links.
 * @param {string} [payload.label] - Text label for the link/button (used if no children are passed).
 * @param {string} [payload.option='external_link'] - Determines link behavior: 'internal_link', 'external_link', 'scroll_to_section', or 'open_modal'.
 * @param {string} [payload.section_id] - ID of the section to scroll to.
 * @param {string} [payload.modal_id] - ID of the modal to open.
 * @param {string} [payload.ariaLabel] - Accessibility label for the link/button.
 * @param {string} [payload.customClass=''] - CSS class to apply to the rendered element.
 *
 * @returns {JSX.Element} - Returns an <a>, <button>, or <div> with a slot based on the configuration.
 *
 * @examples
 */

<ButtonLink payload={{ href: "/about-us", option: "internal_link", customClass: "link-class", label: "About Us" }} />
// Render as: <a href="/about-us" class="link-class">About Us</a>
// NOTE: For Sanity projects, use getURL() helper function for internal links. See src/utilities/astro/getUrl.js  on Terra front repository for reference.

<ButtonLink payload={{ href: "https://example.com", option: "external_link", customClass: "external-link", label: "Visit Example" }} />
//Render as: <a href="https://example.com" class="external-link" target="_blank">Visit Example</a>

<ButtonLink payload={{ option: "scroll_to_section", customClass: "scroll-button", label: "Scroll Down" }} />
//Render as: <button class="scroll-button">Scroll Down</button>

<ButtonLink payload={{ option: "open_modal", customClass: "modal-button", label: "Open Modal" }} />
//Render as: <button class="modal-button">Open Modal</button>

<ButtonLink payload={{ option: "button", customClass: "action-button", label: "Click Me" }} />
//Render as: <button class="action-button">Click Me</button>

<ButtonLink payload={{ label: "Default Content" }} />
//Render as: <div>Default Content</div>