@brika/plugin-weather 0.3.0

package/src/bricks/forecast.tsx

@@ -0,0 +1,136 @@
+import { Avatar, Box, Column, Divider, defineBrick, Grid, type I18nRef, Icon, Row, Spacer, Text, useBrickSize, useLocale, usePreference } from '@brika/sdk/bricks';
+import { useWeather } from '../use-weather';
+import { dayName, formatTempWithUnit, getWeatherVisuals } from '../utils';
+import { CITY_UNIT_CONFIG, WeatherError, WeatherLoading } from './shared';
+
+// ─── Day props shared by both layouts ───────────────────────────────────────
+
+interface DayProps {
+  dayLabel: I18nRef;
+  code: number;
+  high: number;
+  low: number;
+  unit: string;
+}
+
+// ─── List row (narrow) — single-line per day, maximally scannable ───────────
+
+function DayRow({ dayLabel, code, high, low, unit }: Readonly<DayProps>) {
+  const { meta, color } = getWeatherVisuals(code);
+
+  return (
+    <Row gap="sm" align="center">
+      <Avatar icon={meta.icon} color={color} size="sm" />
+      <Column grow>
+        <Text content={dayLabel} variant="body" weight="medium" color="#ffffff" maxLines={1} />
+      </Column>
+      <Text content={formatTempWithUnit(high, unit)} variant="body" weight="bold" color="#ffffff" />
+      <Text content={formatTempWithUnit(low, unit)} variant="body" color="rgba(255,255,255,0.35)" />
+    </Row>
+  );
+}
+
+// ─── Grid cell (wide) — compact vertical card ──────────────────────────────
+
+function DayCell({ dayLabel, code, high, low, unit }: Readonly<DayProps>) {
+  const { meta, color } = getWeatherVisuals(code);
+
+  return (
+    <Column gap="sm" align="center">
+      <Text content={dayLabel} variant="caption" weight="semibold" color="rgba(255,255,255,0.7)" maxLines={1} />
+      <Avatar icon={meta.icon} color={color} size="sm" />
+      <Row gap="sm" align="end">
+        <Text content={formatTempWithUnit(high, unit)} variant="body" weight="bold" color="#ffffff" />
+        <Text content={formatTempWithUnit(low, unit)} variant="caption" color="rgba(255,255,255,0.35)" />
+      </Row>
+    </Column>
+  );
+}
+
+// ─── Brick Definition ────────────────────────────────────────────────────────
+
+export const forecastBrick = defineBrick(
+  {
+    id: 'forecast',
+    families: ['md', 'lg'],
+    minSize: { w: 2, h: 1 },
+    maxSize: { w: 12, h: 6 },
+    config: [
+      ...CITY_UNIT_CONFIG,
+      { type: 'number', name: 'days', default: 7, min: 1, max: 7, step: 1 },
+    ],
+  },
+  () => {
+    const { t } = useLocale();
+    const { weather, unit } = useWeather();
+    const [days] = usePreference<number>('days', 7);
+    const { width, height } = useBrickSize();
+
+    if (weather.loading && weather.daily.length === 0) return <WeatherLoading variant="forecast" />;
+    if (weather.error && weather.daily.length === 0) return <WeatherError message={weather.error} />;
+    if (weather.daily.length === 0) return <WeatherLoading variant="forecast" />;
+
+    const code = weather.current?.weatherCode ?? 3;
+    const { gradient } = getWeatherVisuals(code);
+    const locationName = weather.location?.name ?? '';
+
+    const useGrid = width >= 4;
+
+    // Grid: one row only — cap days by width. List: cap by height.
+    let maxVisible = width;
+    if (!useGrid) {
+      if (height >= 3) maxVisible = 7;
+      else if (height >= 2) maxVisible = 5;
+      else maxVisible = 3;
+    }
+    const visibleDays = weather.daily.slice(0, Math.min(days, maxVisible));
+
+    return (
+      <Box background={gradient} rounded="sm" padding="lg" grow>
+        <Column gap="sm" grow>
+          {/* Header — location left, day count right */}
+          <Row gap="sm" align="center">
+            <Icon name="map-pin" size="sm" color="rgba(255,255,255,0.5)" />
+            <Text content={locationName} variant="body" weight="semibold" color="#ffffff" maxLines={1} />
+            <Spacer />
+            <Text
+              content={t('ui.dayForecast', { count: visibleDays.length })}
+              variant="caption"
+              color="rgba(255,255,255,0.45)"
+            />
+          </Row>
+          <Divider color="rgba(255,255,255,0.1)" />
+
+          {/* Forecast — grid when wide, list when narrow */}
+          {useGrid
+            ? (
+              <Grid columns={visibleDays.length} gap="md">
+                {visibleDays.map((day) => (
+                  <DayCell
+                    dayLabel={dayName(day.date, t)}
+                    code={day.weatherCode}
+                    high={day.tempMax}
+                    low={day.tempMin}
+                    unit={unit}
+                  />
+                ))}
+              </Grid>
+            )
+            : (
+              <Column gap="sm" grow justify="between">
+                {visibleDays.map((day) => (
+                  <DayRow
+                    dayLabel={dayName(day.date, t)}
+                    code={day.weatherCode}
+                    high={day.tempMax}
+                    low={day.tempMin}
+                    unit={unit}
+                  />
+                ))}
+              </Column>
+            )}
+        </Column>
+      </Box>
+    );
+  },
+);

package/src/bricks/shared.tsx

@@ -0,0 +1,49 @@
+import { type BrickTypeSpec, Column, Icon, Skeleton, Text, type TextContent } from '@brika/sdk/bricks';
+
+// ─── Shared brick config (city + unit dropdown) ─────────────────────────────
+
+export const CITY_UNIT_CONFIG: NonNullable<BrickTypeSpec['config']> = [
+  { type: 'text', name: 'city' },
+  {
+    type: 'dropdown',
+    name: 'unit',
+    options: [{ value: 'default' }, { value: 'celsius' }, { value: 'fahrenheit' }],
+    default: 'default',
+  },
+];
+
+// ─── Shared Loading / Error states ──────────────────────────────────────────
+
+export function WeatherLoading({ variant = 'default' }: Readonly<{ variant?: 'compact' | 'default' | 'forecast' }>) {
+  if (variant === 'compact') {
+    return (
+      <Column gap="sm" align="center" justify="center" grow>
+        <Skeleton variant="circle" width="32px" height="32px" />
+        <Skeleton variant="text" width="60%" />
+      </Column>
+    );
+  }
+  if (variant === 'forecast') {
+    return (
+      <Column gap="md" align="center" justify="center" grow>
+        <Skeleton variant="text" width="40%" />
+        <Skeleton variant="rect" width="100%" height="80px" />
+      </Column>
+    );
+  }
+  return (
+    <Column gap="md" align="center" justify="center" grow>
+      <Skeleton variant="circle" width="48px" height="48px" />
+      <Skeleton variant="text" width="60%" lines={2} />
+    </Column>
+  );
+}
+
+export function WeatherError({ message }: Readonly<{ message: TextContent }>) {
+  return (
+    <Column gap="sm" align="center" justify="center" grow>
+      <Icon name="cloud-off" size="lg" color="muted" />
+      <Text content={message} variant="caption" color="muted" align="center" />
+    </Column>
+  );
+}

package/src/index.tsx

@@ -0,0 +1,13 @@
+import { log, onStop } from '@brika/sdk/lifecycle';
+
+export { compactBrick } from './bricks/compact';
+// Bricks (board UI)
+export { currentBrick } from './bricks/current';
+export { forecastBrick } from './bricks/forecast';
+
+// Lifecycle
+onStop(() => {
+  log.info('Weather plugin stopping');
+});
+
+log.info('Weather plugin loaded');

package/src/types.ts

@@ -0,0 +1,53 @@
+// ─── Geocoding ─────────────────────────────────────────────────────────────
+
+export interface GeoLocation {
+  name: string;
+  latitude: number;
+  longitude: number;
+  country: string;
+  timezone: string;
+}
+
+// ─── Current Weather ───────────────────────────────────────────────────────
+
+export interface CurrentWeather {
+  temperature: number;
+  apparentTemperature: number;
+  humidity: number;
+  weatherCode: number;
+  windSpeed: number;
+  windDirection: number;
+  pressure: number;
+}
+
+// ─── Hourly Forecast ───────────────────────────────────────────────────────
+
+export interface HourlyForecast {
+  time: string;
+  temperature: number;
+  weatherCode: number;
+  precipitationProbability: number;
+}
+
+// ─── Daily Forecast ────────────────────────────────────────────────────────
+
+export interface DailyForecast {
+  date: string;
+  weatherCode: number;
+  tempMax: number;
+  tempMin: number;
+  precipitationSum: number;
+  windSpeedMax: number;
+}
+
+// ─── Shared Store State ────────────────────────────────────────────────────
+
+export interface WeatherState {
+  location: GeoLocation | null;
+  current: CurrentWeather | null;
+  daily: DailyForecast[];
+  hourly: HourlyForecast[];
+  lastUpdated: number | null;
+  loading: boolean;
+  error: string | null;
+}

package/src/use-weather.ts

@@ -0,0 +1,75 @@
+/**
+ * useWeather — unified hook for weather brick instances.
+ *
+ * Handles city resolution (per-instance → plugin-level → auto-detect),
+ * unit resolution (per-instance → plugin-level → celsius), polling
+ * lifecycle, and store subscription. All in one call.
+ *
+ * @example
+ * ```tsx
+ * const { weather, city, unit } = useWeather();
+ * // weather.current?.temperature, weather.loading, weather.error
+ * ```
+ */
+
+import { getDeviceLocation } from '@brika/sdk';
+import {
+  useEffect,
+  usePluginPreference,
+  usePreference,
+  useState,
+} from '@brika/sdk/bricks';
+import type { WeatherState } from './types';
+import { acquirePolling, DEFAULT_WEATHER, useWeatherMap } from './weather-store';
+
+interface UseWeatherResult {
+  /** Weather data for the resolved city. */
+  weather: WeatherState;
+  /** The resolved city name being displayed. */
+  city: string;
+  /** The resolved temperature unit ('celsius' | 'fahrenheit'). */
+  unit: string;
+}
+
+/**
+ * Unified weather hook.
+ *
+ * Resolution order for **city**: brick config → plugin preference → auto-detect → "Zurich"
+ * Resolution order for **unit**: brick config → plugin preference → "celsius"
+ */
+export function useWeather(): UseWeatherResult {
+  // ─── City resolution ──────────────────────────────────────────────
+  const [brickCity] = usePreference<string>('city', '');
+  const pluginCity = usePluginPreference<string>('city', '');
+  const [autoCity, setAutoCity] = useState('');
+
+  const configuredCity = brickCity || pluginCity;
+
+  // Auto-detect location when no city is configured
+  useEffect(() => {
+    if (configuredCity) return;
+    getDeviceLocation()
+      .then((loc) => {
+        if (loc?.city) setAutoCity(loc.city);
+      })
+      .catch(() => {
+        // Permission denied or location not configured — fall back to default city
+      });
+  }, [configuredCity]);
+
+  const resolvedCity = configuredCity || autoCity || 'Zurich';
+
+  // ─── Unit resolution ──────────────────────────────────────────────
+  const [brickUnit] = usePreference<string>('unit', 'default');
+  const pluginUnit = usePluginPreference<string>('unit', 'celsius');
+  const unit = brickUnit && brickUnit !== 'default' ? brickUnit : pluginUnit;
+
+  // ─── Polling lifecycle ────────────────────────────────────────────
+  useEffect(() => acquirePolling(resolvedCity), [resolvedCity]);
+
+  // ─── Store subscription ───────────────────────────────────────────
+  const weatherMap = useWeatherMap();
+  const weather = weatherMap[resolvedCity] ?? DEFAULT_WEATHER;
+
+  return { weather, city: resolvedCity, unit };
+}

package/src/utils.ts

@@ -0,0 +1,160 @@
+// ─── WMO Weather Codes ─────────────────────────────────────────────────────
+
+export type WeatherCondition =
+  | 'clear'
+  | 'partly-cloudy'
+  | 'cloudy'
+  | 'fog'
+  | 'drizzle'
+  | 'rain'
+  | 'snow'
+  | 'showers'
+  | 'thunderstorm';
+
+export interface WeatherMeta {
+  condition: WeatherCondition;
+  /** i18n key under `conditions.*` */
+  labelKey: string;
+  icon: string;
+}
+
+const WMO_MAP: Record<number, WeatherMeta> = {
+  0:  { condition: 'clear',          labelKey: 'conditions.clearSky',             icon: 'sun' },
+  1:  { condition: 'partly-cloudy',  labelKey: 'conditions.mainlyClear',          icon: 'cloud-sun' },
+  2:  { condition: 'partly-cloudy',  labelKey: 'conditions.partlyCloudy',         icon: 'cloud-sun' },
+  3:  { condition: 'cloudy',         labelKey: 'conditions.overcast',             icon: 'cloud' },
+  45: { condition: 'fog',            labelKey: 'conditions.fog',                  icon: 'cloud-fog' },
+  48: { condition: 'fog',            labelKey: 'conditions.rimeFog',              icon: 'cloud-fog' },
+  51: { condition: 'drizzle',        labelKey: 'conditions.lightDrizzle',         icon: 'cloud-drizzle' },
+  53: { condition: 'drizzle',        labelKey: 'conditions.drizzle',              icon: 'cloud-drizzle' },
+  55: { condition: 'drizzle',        labelKey: 'conditions.denseDrizzle',         icon: 'cloud-drizzle' },
+  56: { condition: 'drizzle',        labelKey: 'conditions.freezingDrizzle',      icon: 'cloud-drizzle' },
+  57: { condition: 'drizzle',        labelKey: 'conditions.heavyFreezingDrizzle', icon: 'cloud-drizzle' },
+  61: { condition: 'rain',           labelKey: 'conditions.lightRain',            icon: 'cloud-rain' },
+  63: { condition: 'rain',           labelKey: 'conditions.rain',                 icon: 'cloud-rain' },
+  65: { condition: 'rain',           labelKey: 'conditions.heavyRain',            icon: 'cloud-rain' },
+  66: { condition: 'rain',           labelKey: 'conditions.freezingRain',         icon: 'cloud-rain' },
+  67: { condition: 'rain',           labelKey: 'conditions.heavyFreezingRain',    icon: 'cloud-rain' },
+  71: { condition: 'snow',           labelKey: 'conditions.lightSnow',            icon: 'snowflake' },
+  73: { condition: 'snow',           labelKey: 'conditions.snow',                 icon: 'snowflake' },
+  75: { condition: 'snow',           labelKey: 'conditions.heavySnow',            icon: 'snowflake' },
+  77: { condition: 'snow',           labelKey: 'conditions.snowGrains',           icon: 'snowflake' },
+  80: { condition: 'showers',        labelKey: 'conditions.lightShowers',         icon: 'cloud-rain-wind' },
+  81: { condition: 'showers',        labelKey: 'conditions.showers',              icon: 'cloud-rain-wind' },
+  82: { condition: 'showers',        labelKey: 'conditions.heavyShowers',         icon: 'cloud-rain-wind' },
+  85: { condition: 'snow',           labelKey: 'conditions.snowShowers',          icon: 'snowflake' },
+  86: { condition: 'snow',           labelKey: 'conditions.heavySnowShowers',     icon: 'snowflake' },
+  95: { condition: 'thunderstorm',   labelKey: 'conditions.thunderstorm',         icon: 'cloud-lightning' },
+  96: { condition: 'thunderstorm',   labelKey: 'conditions.thunderstormHail',     icon: 'cloud-lightning' },
+  99: { condition: 'thunderstorm',   labelKey: 'conditions.severeThunderstorm',   icon: 'cloud-lightning' },
+};
+
+const FALLBACK: WeatherMeta = { condition: 'cloudy', labelKey: 'conditions.unknown', icon: 'cloud' };
+
+export function getWeatherMeta(code: number): WeatherMeta {
+  return WMO_MAP[code] ?? FALLBACK;
+}
+
+// ─── Gradient Backgrounds ───────────────────────────────────────────────────
+// All gradients dark enough for white text (WCAG AA on lightest stop).
+
+const CONDITION_GRADIENTS: Record<WeatherCondition, string> = {
+  clear:           'linear-gradient(135deg, #1a56a0 0%, #2875c8 50%, #3d8fd4 100%)',
+  'partly-cloudy': 'linear-gradient(135deg, #2a5078 0%, #3b6a96 50%, #4d80ab 100%)',
+  cloudy:          'linear-gradient(135deg, #363d47 0%, #454e5b 50%, #545f6e 100%)',
+  fog:             'linear-gradient(135deg, #3e4652 0%, #4f5966 50%, #5e6b78 100%)',
+  drizzle:         'linear-gradient(135deg, #2a4c72 0%, #3a6490 50%, #4a7aaa 100%)',
+  rain:            'linear-gradient(135deg, #1a3352 0%, #264a72 50%, #336190 100%)',
+  snow:            'linear-gradient(135deg, #3a5a78 0%, #4d7396 50%, #608aab 100%)',
+  showers:         'linear-gradient(135deg, #142a48 0%, #1e3f68 50%, #2a5588 100%)',
+  thunderstorm:    'linear-gradient(135deg, #1a1530 0%, #2a2250 50%, #3a3070 100%)',
+};
+
+export function getGradient(code: number): string {
+  const { condition } = getWeatherMeta(code);
+  return CONDITION_GRADIENTS[condition];
+}
+
+// ─── Icon Accent Colors ─────────────────────────────────────────────────────
+
+const CONDITION_COLORS: Record<WeatherCondition, string> = {
+  clear: '#fbbf24',
+  'partly-cloudy': '#fbbf24',
+  cloudy: '#94a3b8',
+  fog: '#cbd5e1',
+  drizzle: '#7dd3fc',
+  rain: '#60a5fa',
+  snow: '#e0e7ff',
+  showers: '#60a5fa',
+  thunderstorm: '#c4b5fd',
+};
+
+export function getConditionColor(code: number): string {
+  const { condition } = getWeatherMeta(code);
+  return CONDITION_COLORS[condition];
+}
+
+// ─── Weather Visuals (meta + color + gradient in one lookup) ────────────────
+
+export interface WeatherVisuals {
+  meta: WeatherMeta;
+  color: string;
+  gradient: string;
+}
+
+/** Single lookup for all display properties of a weather code. */
+export function getWeatherVisuals(code: number): WeatherVisuals {
+  const meta = getWeatherMeta(code);
+  return {
+    meta,
+    color: CONDITION_COLORS[meta.condition],
+    gradient: CONDITION_GRADIENTS[meta.condition],
+  };
+}
+
+// ─── Temperature Formatting ────────────────────────────────────────────────
+
+export function formatTemp(celsius: number, unit: string): string {
+  if (unit === 'fahrenheit') {
+    return `${Math.round(celsius * 9 / 5 + 32)}`;
+  }
+  return `${Math.round(celsius)}`;
+}
+
+export function tempUnit(unit: string): string {
+  return unit === 'fahrenheit' ? '\u00b0F' : '\u00b0C';
+}
+
+/** formatTemp + tempUnit combined — e.g. "23°C" or "72°F" */
+export function formatTempWithUnit(celsius: number, unit: string): string {
+  return `${formatTemp(celsius, unit)}${tempUnit(unit)}`;
+}
+
+// ─── Wind Direction ────────────────────────────────────────────────────────
+
+export function windDirectionLabel(degrees: number): string {
+  const dirs = ['N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW'] as const;
+  const index = Math.round(degrees / 45) % 8;
+  return dirs[index];
+}
+
+// ─── Day Name Formatting ───────────────────────────────────────────────────
+
+import type { I18nRef } from '@brika/sdk/bricks';
+
+export type TranslateFn = (key: string, params?: Record<string, string | number>) => I18nRef;
+
+const WEEKDAY_KEYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'] as const;
+
+export function dayName(dateStr: string, t: TranslateFn): I18nRef {
+  const date = new Date(dateStr + 'T00:00:00');
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+
+  const tomorrow = new Date(today);
+  tomorrow.setDate(tomorrow.getDate() + 1);
+
+  if (date.getTime() === today.getTime()) return t('days.today');
+  if (date.getTime() === tomorrow.getTime()) return t('days.tomorrow');
+  return t(`days.${WEEKDAY_KEYS[date.getDay()]}`);
+}

package/src/weather-store.ts

@@ -0,0 +1,128 @@
+/**
+ * Shared weather store — city-keyed, one polling loop per city.
+ *
+ * Built on `defineSharedStore` from the SDK. Multiple brick instances
+ * can show different cities; polling is reference-counted per city.
+ *
+ * @example
+ * ```tsx
+ * // In a brick:
+ * const weather = useWeatherMap()['Zurich'] ?? DEFAULT_WEATHER;
+ * useEffect(() => acquirePolling('Zurich'), []);
+ * ```
+ */
+
+import { log } from '@brika/sdk';
+import { defineSharedStore } from '@brika/sdk/bricks';
+import { fetchWeather, geocodeCity } from './api';
+import type { GeoLocation, WeatherState } from './types';
+
+// ─── Default state for a city with no data yet ──────────────────────────────
+
+export const DEFAULT_WEATHER: WeatherState = {
+  location: null,
+  current: null,
+  daily: [],
+  hourly: [],
+  lastUpdated: null,
+  loading: false,
+  error: null,
+};
+
+// ─── Store: city → weather data ──────────────────────────────────────────────
+
+export const useWeatherMap = defineSharedStore<Record<string, WeatherState>>({});
+
+// ─── Per-city polling ────────────────────────────────────────────────────────
+
+const POLL_MS = 10 * 60 * 1000; // 10 minutes
+
+interface CityEntry {
+  refCount: number;
+  timer: ReturnType<typeof setInterval> | null;
+  cachedLocation: GeoLocation | null;
+}
+
+const cities = new Map<string, CityEntry>();
+
+function getEntry(city: string): CityEntry {
+  let entry = cities.get(city);
+  if (!entry) {
+    entry = { refCount: 0, timer: null, cachedLocation: null };
+    cities.set(city, entry);
+  }
+  return entry;
+}
+
+function updateCity(city: string, patch: Partial<WeatherState>): void {
+  useWeatherMap.set((prev) => ({
+    ...prev,
+    [city]: { ...(prev[city] ?? DEFAULT_WEATHER), ...patch },
+  }));
+}
+
+async function pollCity(city: string): Promise<void> {
+  const entry = cities.get(city);
+  if (!entry) return;
+
+  try {
+    let location = entry.cachedLocation;
+    if (!location) {
+      updateCity(city, { loading: true, error: null });
+      location = await geocodeCity(city);
+      if (!location) {
+        updateCity(city, { loading: false, error: `City not found: ${city}` });
+        return;
+      }
+      entry.cachedLocation = location;
+    }
+
+    const data = await fetchWeather(location.latitude, location.longitude);
+    if (!data) {
+      updateCity(city, { loading: false, error: 'Failed to fetch weather data' });
+      return;
+    }
+
+    useWeatherMap.set((prev) => ({
+      ...prev,
+      [city]: {
+        location,
+        current: data.current,
+        daily: data.daily,
+        hourly: data.hourly,
+        lastUpdated: Date.now(),
+        loading: false,
+        error: null,
+      },
+    }));
+  } catch (err) {
+    log.error(`Weather poll for "${city}" failed: ${err instanceof Error ? err.message : String(err)}`);
+    updateCity(city, { loading: false, error: 'Network error' });
+  }
+}
+
+/**
+ * Acquire polling for a specific city.
+ * Starts polling on first subscriber, stops on last.
+ * Returns a release function to call on unmount.
+ */
+export function acquirePolling(city: string): () => void {
+  const entry = getEntry(city);
+  entry.refCount++;
+
+  if (entry.refCount === 1) {
+    pollCity(city);
+    entry.timer = setInterval(() => pollCity(city), POLL_MS);
+  }
+
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    entry.refCount--;
+    if (entry.refCount === 0 && entry.timer) {
+      clearInterval(entry.timer);
+      entry.timer = null;
+    }
+  };
+}