Weather Catalog

Weather-specific UI components for displaying forecasts, conditions, and alerts.

This catalog was built using the Freesail custom catalog system. The guide below covers everything you need to understand, modify, or extend it.

Quick Start

npm install
npm run build

Project Structure

src/
  weather-catalog.json      # Generated catalog (do not edit manually)
  index.ts                  # Catalog entry point
  includes/
    catalog.include.json    # Declare which packages to import from
    generated-includes.ts   # Auto-generated bridge (do not edit)
  components/
    components.json         # Component schemas
    components.tsx          # React implementations
  functions/
    functions.json          # Function schemas
    functions.ts            # Function implementations

Catalog ID

The catalogId in the catalog JSON is derived from the npm package name's org scope:

• @acme/weather-catalog → https://acme.local/catalogs/weather-catalog.json

Override it via package.json:

{
  "freesail": {
    "catalogId": "https://mycompany.com/catalogs/weather-catalog.json",
    "title": "Weather Catalog",
    "description": "Weather UI components"
  }
}

Build Pipeline

{
  "scripts": {
    "prepare:catalog": "freesail prepare catalog",
    "prebuild": "freesail prepare catalog && freesail validate catalog",
    "build": "tsc"
  }
}

• freesail prepare catalog — reads catalog.include.json, merges imported and local schemas, writes the catalog JSON and generated-includes.ts
• freesail validate catalog — checks every JSON-declared component/function has a matching implementation

Importing from a Catalog Package

Pull components and functions from any installed catalog package into this one:

npx freesail include catalog --package @freesail/standard-catalog

Edit catalog.include.json afterwards to remove anything you don't need:

{
  "includes": {
    "@freesail/standard-catalog": {
      "catalogPath": "dist/standard-catalog.json",
      "components": ["Card", "Button", "Text"],
      "functions": ["formatString"]
    }
  }
}

Step 1: Define Custom Schemas (components/components.json)

{
  "components": {
    "WeatherCard": {
      "type": "object",
      "allOf": [
        { "$ref": "#/$defs/ComponentCommon" },
        {
          "type": "object",
          "description": "Displays current weather conditions for a location.",
          "properties": {
            "component": { "const": "WeatherCard" },
            "location":    { "type": "string", "description": "City name" },
            "temperature": { "type": "number", "description": "Temperature value" },
            "unit":        { "type": "string", "enum": ["C","F"], "description": "Temperature unit" },
            "condition":   { "type": "string", "description": "e.g. sunny, rainy, cloudy" }
          },
          "required": ["component", "location"]
        }
      ]
    }
  }
}

Key rules:

• Component name keys (e.g. WeatherCard) are the names agents use in "component": "WeatherCard".
• description fields appear in the agent's system prompt — write them precisely.
• Use allOf + $ref: "#/$defs/ComponentCommon" for consistent structure.
• Never edit the generated {name}-catalog.json directly.

After editing, run:

npx freesail prepare catalog

Step 2: Implement Components (components/components.tsx)

import React, { type CSSProperties } from 'react';
import type { FreesailComponentProps } from '@freesail/react';
import { includedComponents } from '../includes/generated-includes.js';

export function WeatherCard({ component }: FreesailComponentProps) {
  const location    = String((component['location'] as string) ?? 'Unknown');
  const temperature = component['temperature'] !== undefined
    ? parseFloat(String(component['temperature'])) : undefined;
  const unit      = (component['unit'] as string) ?? 'C';
  const condition = (component['condition'] as string) ?? 'sunny';

  const style: CSSProperties = {
    padding: 'var(--freesail-space-lg)',
    borderRadius: 'var(--freesail-radius-lg)',
    backgroundColor: 'var(--freesail-bg-raised, #ffffff)',
    border: '1px solid var(--freesail-border, #e2e8f0)',
    boxShadow: 'var(--freesail-shadow-md)',
    color: 'var(--freesail-text-main, #0f172a)',
  };

  return (
    <div style={style}>
      <div style={{ fontSize: 'var(--freesail-type-h4)', fontWeight: 600 }}>
        {location}
      </div>
      {temperature !== undefined && (
        <div style={{ fontSize: 'var(--freesail-type-h1)', fontWeight: 200 }}>
          {Math.round(temperature)}°{unit}
        </div>
      )}
      <div style={{ color: 'var(--freesail-text-muted, #64748b)', textTransform: 'capitalize' }}>
        {condition}
      </div>
    </div>
  );
}

export const weatherCatalogComponents = {
  ...includedComponents,
  WeatherCard,
};

Conventions:

• Export each component as a named export function.
• Cast all prop values with as string / as number — values arrive as unknown.
• Use var(--freesail-*) CSS custom properties for theming (see Token Reference below).
• Always include a hardcoded fallback in var(): var(--freesail-bg-raised, #ffffff).
• Map keys must exactly match the component names in the JSON schema.

FreesailComponentProps reference

| Prop | Type | Purpose | |------|------|---------| | component | A2UIComponent | All resolved props the agent sent for this component instance | | children | ReactNode | Rendered child components (for containers) | | scopeData | unknown | Current item data when inside a dynamic list template | | dataModel | Record<string, unknown> | Full surface data model (read-only snapshot) | | onAction | (name, context) => void | Dispatch a named action to the agent | | onDataChange | (path, value) => void | Write a value to the local data model (two-way binding) | | onFunctionCall | (call) => void | Execute a client-side function call |

Two-way binding (input components)

export function MyInput({ component, onDataChange }: FreesailComponentProps) {
  const value = (component['value'] as string) ?? '';
  const rawValue = component['__rawValue'] as { path?: string } | string | undefined;
  const boundPath = typeof rawValue === 'object' && rawValue?.path
    ? rawValue.path : `/input/${component.id}`;

  return (
    <input
      value={value}
      onChange={(e) => onDataChange?.(boundPath, e.target.value)}
    />
  );
}

Step 3: Add Custom Functions (functions/functions.ts)

import type { FunctionImplementation } from '@freesail/react';
import { includedFunctions } from '../includes/generated-includes.js';

const formatWindSpeed: FunctionImplementation = (args) => {
  const speed = Number((args as Record<string, unknown>)?.['speed'] ?? 0);
  const unit  = String((args as Record<string, unknown>)?.['unit'] ?? 'km/h');
  return `${speed} ${unit}`;
};

export const weatherCatalogFunctions = {
  ...includedFunctions,
  formatWindSpeed,
};

Also declare the function in src/functions/functions.json.

Step 4: Wire Up index.ts

import type { CatalogDefinition } from '@freesail/react';
import { weatherCatalogComponents } from './components/components.js';
import { weatherCatalogFunctions } from './functions/functions.js';
import catalogSchema from './weather-catalog.json';

export const WeatherCatalog: CatalogDefinition = {
  namespace: catalogSchema.catalogId,
  schema: catalogSchema,
  components: weatherCatalogComponents,
  functions: weatherCatalogFunctions,
};

formatString is required. Import it from @freesail/standard-catalog via catalog.include.json, or implement it yourself. The agent system prompt relies on it.

Registering the Catalog

import { FreesailProvider } from '@freesail/react';
import { WeatherCatalog } from '@freesail-community/weather-catalog';
import { StandardCatalog } from '@freesail/standard-catalog';

function App() {
  return (
    <FreesailProvider
      catalogs={[StandardCatalog, WeatherCatalog]}
    >
      {/* your app */}
    </FreesailProvider>
  );
}

Validation

npx freesail prepare catalog   # Merge schemas and regenerate catalog JSON
npx freesail validate catalog  # Check implementations match the schema

Both accept --dir <path> to target a different directory.

Theme Token Reference

All --freesail-* CSS custom properties are injected by FreesailProvider. Always use them instead of hardcoded colours to support light/dark mode and host-app theming.

Background

| CSS Custom Property | Light default | Dark default | Usage | |---|---|---|---| | --freesail-bg | #f8fafc | #020617 | Page / surface base background | | --freesail-bg-raised | #ffffff | #0f172a | Cards, modals, input fields, raised panels | | --freesail-bg-muted | #f1f5f9 | #1e293b | Subtle fills, alternating rows, chips | | --freesail-bg-overlay | rgba(0,0,0,0.5) | rgba(0,0,0,0.7) | Modal/drawer backdrop |

Text

| CSS Custom Property | Light default | Dark default | Usage | |---|---|---|---| | --freesail-text-main | #0f172a | #f8fafc | Primary body text, headings | | --freesail-text-muted | #64748b | #94a3b8 | Secondary/helper text, labels |

Brand & Interactive

| CSS Custom Property | Light default | Dark default | Usage | |---|---|---|---| | --freesail-primary | #2563eb | #3b82f6 | Buttons, links, active states | | --freesail-primary-hover | #1d4ed8 | #2563eb | Hover state for primary elements | | --freesail-primary-text | #ffffff | #ffffff | Text on primary-coloured backgrounds |

Semantic Status

| CSS Custom Property | Light default | Dark default | Usage | |---|---|---|---| | --freesail-error | #ef4444 | #f87171 | Error states, destructive actions | | --freesail-success | #22c55e | #4ade80 | Success states, confirmations | | --freesail-warning | #f59e0b | #fbbf24 | Warning states, advisories | | --freesail-info | #3b82f6 | #60a5fa | Informational highlights |

Subtle status backgrounds — derive with color-mix:

background: color-mix(in srgb, var(--freesail-warning) 12%, var(--freesail-bg));

Structure & Shape

| CSS Custom Property | Light default | Dark default | Usage | |---|---|---|---| | --freesail-border | #cbd5e1 | #334155 | Dividers, input borders | | --freesail-radius-sm | 0.25rem | — | Chips, badges | | --freesail-radius-md | 0.5rem | — | Buttons, inputs, cards | | --freesail-radius-lg | 0.75rem | — | Modals, large panels | | --freesail-shadow-sm | — | — | Subtle elevation | | --freesail-shadow-md | — | — | Moderate elevation |

Fluid Spacing (clamp() · container-relative)

| CSS Custom Property | Range | |---|---| | --freesail-space-xs | 2px – 4px | | --freesail-space-sm | 4px – 8px | | --freesail-space-md | 8px – 16px | | --freesail-space-lg | 16px – 24px | | --freesail-space-xl | 24px – 40px |

Fluid Typography

| CSS Custom Property | Range | |---|---| | --freesail-type-caption | 10px – 12px | | --freesail-type-label | 11px – 13px | | --freesail-type-body | 13px – 15px | | --freesail-type-h5 | 13px – 15px | | --freesail-type-h4 | 15px – 18px | | --freesail-type-h3 | 17px – 22px | | --freesail-type-h2 | 20px – 28px | | --freesail-type-h1 | 24px – 36px |

Fluid Icon Sizes

| CSS Custom Property | Range | |---|---| | --freesail-icon-sm | 14px – 16px | | --freesail-icon-md | 18px – 20px | | --freesail-icon-lg | 20px – 24px | | --freesail-icon-xl | 28px – 32px |

Full style example

const style: CSSProperties = {
  padding: 'var(--freesail-space-md)',
  backgroundColor: 'var(--freesail-bg-raised, #ffffff)',
  color: 'var(--freesail-text-main, #0f172a)',
  border: '1px solid var(--freesail-border, #e2e8f0)',
  borderRadius: 'var(--freesail-radius-md)',
  boxShadow: 'var(--freesail-shadow-sm)',
  fontSize: 'var(--freesail-type-body)',
};

CatalogDefinition API Reference

| Property | Type | Required | Description | |----------|------|----------|-------------| | namespace | string | ✅ | The catalogId URI — must match schema.catalogId | | schema | object | ✅ | The parsed JSON schema object | | components | Record<string, ComponentType<FreesailComponentProps>> | ✅ | Component name → React component map | | functions | Record<string, FunctionImplementation> | ✅ | Function name → implementation map (must include formatString) |

Build Commands

| Command | Description | | --- | --- | | npx freesail prepare catalog | Merge schemas and regenerate catalog JSON | | npx freesail validate catalog | Validate implementations match the schema | | npx freesail include catalog --package <name> | Include components/functions from a catalog package | | npm run build | Compile TypeScript (runs prepare + validate automatically) | | npm run dev | Watch mode for development | | npm run clean | Remove build artifacts |

License

MIT — see LICENSE