TypeScript Types

Every template ships a types.d.ts file in its root folder. Import or reference it to get full type-safety when integrating template logic into a TypeScript project.

/// <reference path="./types.d.ts" />

interface KPIMetric {
  value:     number;
  label:     string;
  trend:     number;        // delta as a fraction — 0.124 = +12.4%
  direction: 'up' | 'down' | 'neutral';
  unit?:     string;        // e.g. '$', '%', 'ms'
  sub?:      string;        // secondary label
}

interface TimeSeriesPoint {
  timestamp: string;  // ISO 8601 — "2024-06-15T09:00:00Z"
  value:     number;
}

type TimeSeries = TimeSeriesPoint[];

interface BarChartData {
  labels:  string[];
  series:  {
    name:  string;
    data:  number[];
    color?: string;
  }[];
}

interface PieChartData {
  name:  string;
  value: number;
  color?: string;
}[]

type TableRow = Record<string, string | number | boolean | null>;

Each template declares its own payload types, named after the template slug:

// marketing-performance-hub/types.d.ts

interface MarketingDashboardPayload {
  period:      '7d' | '30d' | '90d' | 'YTD';
  channels:    ChannelMetrics[];
  funnel:      FunnelStage[];
  campaigns:   CampaignRow[];
  topKeywords: KeywordRow[];
}

interface ChannelMetrics {
  name:       string;
  spend:      number;
  revenue:    number;
  roas:       number;
  cac:        number;
  trend:      number;
}

interface FunnelStage {
  label:      string;
  count:      number;
  conversion: number;   // fraction relative to previous stage
}

// shared/dt-utils.d.ts

declare module 'dt-utils' {
  export function updateKPI(id: string, data: KPIUpdateOptions): void;

  export interface KPIUpdateOptions {
    value:      string;
    trend?:     string;
    direction?: 'up' | 'down' | 'neutral';
    sub?:       string;
  }

  export function createDataTable(options: DataTableOptions): DataTableInstance;

  export interface DataTableOptions {
    container: HTMLElement;
    columns:   ColumnDef[];
    rows:      TableRow[];
    pageSize?: number;
  }

  export interface ColumnDef {
    key:       string;
    label:     string;
    sortable?: boolean;
    format?:   'currency' | 'date' | 'percent' | 'number';
    render?:   (value: unknown, row: TableRow) => string;
  }

  export const fmt: {
    currency: (n: number, currency?: string) => string;
    percent:  (n: number, decimals?: number) => string;
    number:   (n: number)                   => string;
    compact:  (n: number)                   => string;
    date:     (s: string)                   => string;
  };

  export const PALETTE: string[];
}

import type { MarketingDashboardPayload } from './types';

async function fetchDashboard(): Promise<MarketingDashboardPayload> {
  const res = await fetch('/api/marketing/dashboard');
  return res.json();
}

<script setup lang="ts">
import type { KPIMetric } from './types';

const props = defineProps<{
  metrics: KPIMetric[];
}>();
</script>

import type { MarketingDashboardPayload } from '../client/types';

app.get('/api/marketing/dashboard', (req, res) => {
  const payload: MarketingDashboardPayload = buildPayload();
  res.json(payload);
});