Guide: Building Interactive Marketing Tools

This document outlines the standard structure and component usage patterns for creating interactive calculation/estimation tools within the marketing site, based on the example of the “SaaS Valuation Multiple Estimator”.

Goal

To create reusable, consistent, and maintainable interactive tools that integrate seamlessly with the Astro marketing site structure. The core interaction is typically handled by React components loaded client-side.

Standard File Structure

A typical tool will reside in its own directory within apps/marketing/src/pages/tools/, for example, saas-valuation-multiple-estimator/. The key files are:

• index.astro: The main Astro page file. Sets up the overall page layout, loads static content, and embeds the interactive React component.
• calculator.tsx (or similar name): The main React component handling the tool’s logic, state, inputs, and results display.
• description.mdx: An MDX file containing detailed descriptive text, methodology, explanations, etc., about the tool. This is rendered within the Astro layout.
• common/ directory (Shared): Located at apps/marketing/src/pages/tools/common/. Contains reusable React components and hooks used across different tools.
  • inputs.tsx: Provides standardized Input, InputGroup components, and the useQueryParamState hook.
  • summary.tsx: Provides a standardized Summary component for displaying results.

Page Entry Point (index.astro)

• Purpose: Serves as the main HTML page structure. Integrates the static and dynamic parts of the tool.
• Layout: Uses a standard ToolLayout (e.g., ../../../layouts/ToolLayout.astro) to ensure consistent page structure, navigation, and SEO metadata.
• Static Content: Includes the main <h1> title and introductory <p> paragraph directly in the Astro file.
• Interactive Component: Embeds the main React component (e.g., <Calculator />) using an Astro directive like client:load to ensure it hydrates and becomes interactive on the client-side.
• Descriptive Content: Renders the content from the .mdx file (e.g., <Description />) usually below the interactive component, often within a prose styled container for good readability.
• Navigation: May include links back to a tools index page or related resources.

Interactive Calculator (calculator.tsx)

• Purpose: Encapsulates the tool’s core functionality: user input, state management, calculations, and result presentation.
• State Management:
  • Uses standard React hooks (useState, useEffect).
  • Crucially, uses the useQueryParamState hook (from common/inputs.tsx) for input fields. This synchronizes the input field’s state with URL query parameters (e.g., ?arr=10000000&growth=40).
    • Benefits: Allows users to share links with pre-filled values, maintains state on page refresh or back/forward navigation.
    • Usage: const [value, setValue] = useQueryParamState('paramName', 'defaultValue');
  • May use separate useState for calculated results or error messages specific to the component.
• Input Handling:
  • Uses the InputGroup component (from common/inputs.tsx) to wrap multiple Input components, providing a responsive grid layout (e.g., sm:col-span-2).
  • Uses the Input component (from common/inputs.tsx) for each user input field.
  • Configuration: Configures Input props extensively:
    • label: Visible label text.
    • id: HTML id attribute (should match label’s htmlFor).
    • type: Set to "number" for numeric inputs (the component handles underlying type/inputmode and formatting).
    • value: Bound to the state variable from useQueryParamState.
    • onChange: Uses the custom onChange handler provided by the Input component. This handler receives the event and a parsedValue string (cleaned of non-numeric characters except decimal/minus for type="number"). The component’s state setter (from useQueryParamState) should be called with this parsedValue.
    • leadingAddon/trailingAddon: For symbols like $ or %.
    • placeholder: Example input value.
    • error: Bound to an error state variable to display validation errors.
    • tooltip: Adds an info icon with a tooltip next to the label (via the Input component’s internal handling).
• Calculation Logic:
  • Typically performed within a useEffect hook that depends on the state variables holding the parsed input values (e.g., arr, growthRate, profitMargin).
  • Includes validation (e.g., checking for isNaN, positive numbers) before attempting calculations.
  • Updates state variables holding the calculated results (e.g., calculatedMultiple, valuationRange).
• Result Display:
  • Uses the Summary component (from common/summary.tsx) to display the key calculated results in a structured format.
  • Data Structure: Prepares an array of SummaryItem objects to pass to the Summary component’s items prop. Each item object includes:
    • label: Text or ReactNode for the label (can include tooltips via Summary’s internal handling if needed, though often tooltips are on the Input instead).
    • value: The calculated value, often formatted using helper functions (e.g., formatCurrencyCompact from summary.tsx). Display ’-’ or similar if not calculated.
    • highlightColor (optional): Tailwind text color class (e.g., 'text-indigo-600', 'text-green-600') to emphasize certain results.
    • tooltip (optional): Adds an info icon with a tooltip next to the summary item label.
  • Passes other props to Summary like title (for screen readers), mainTitle, and mainDescription.

Common Components (common/)

inputs.tsx

• Input Component:
  • Provides a styled, accessible input field with integrated label.
  • Handles common patterns: leading/trailing addons (text/symbols), leading/trailing icons.
  • Crucially, handles number formatting and parsing: When type="number", it displays formatted numbers (commas) but manages the underlying state as a clean numeric string via the parsedValue in its onChange. It also attempts to maintain cursor position during formatting.
  • Includes error state styling (red border, background).
  • Manages focus styling (focus-within on the container).
  • Supports tooltips next to the label.
• InputGroup Component:
  • A simple wrapper using CSS Grid to arrange multiple Input components responsively. Child Input components need grid column classes (e.g., sm:col-span-2).
• useQueryParamState Hook:
  • Abstracts the logic of reading from/writing to URL query parameters.
  • Takes the parameter name and a default value.
  • Returns a state variable and a setter function, similar to useState. The setter updates both the React state and the URL (using history.replaceState to avoid excessive history entries).
  • Handles SSR safety (typeof window === 'undefined').
  • Listens to popstate events to update state if the user navigates via browser buttons.

summary.tsx

• Summary Component:
  • Provides a styled container for displaying key results or summaries.
  • Typically shows a main title/description on the left (larger screens) and a list of label-value pairs on the right.
  • Uses Radix UI Tooltip internally to provide optional tooltips for list item labels via the tooltip property in the items array.
  • Accepts an items array (SummaryItem[]) defining the label-value pairs to display.
  • Supports highlighting specific values using the highlightColor property.
• Utility Functions: May export related formatting functions (e.g., formatCurrencyCompact).

Content (description.mdx)

• Purpose: Holds the detailed textual content explaining the tool’s purpose, methodology, assumptions, limitations, and definitions of terms.
• Format: Uses Markdown (MDX) for rich text formatting, allowing lists, links, code blocks, and potentially embedding other React components if needed (though typically not necessary for the description).
• Integration: Imported into index.astro and rendered, usually styled using @tailwindcss/typography (prose classes).

Workflow Summary

1. Page Load: User accesses the /tools/tool-name/ URL. index.astro renders the layout, static text, and placeholders for React components.
2. Client-Side Hydration: The React component (Calculator) specified with client:load (or similar) hydrates.
3. Initial State: The useQueryParamState hooks within Calculator read initial values from the URL query parameters (or use defaults). The component renders with these initial values.
4. User Interaction: The user types into the Input fields.
5. State Update: The Input component’s onChange handler provides the parsedValue to the Calculator. The Calculator’s state setter (from useQueryParamState) updates the React state and the URL query parameter.
6. Calculation: The useEffect hook in Calculator, dependent on the input state variables, re-runs. It performs calculations based on the new input values.
7. Result Update: The calculation results update state variables used by the Summary component.
8. Re-render: React re-renders the Calculator component, updating the Input values (if formatted) and the Summary display with the new results.