Documentation

Timeseries table

@infoplaza/platform/timeseries-table

A portable point-forecast matrix — grouped hourly rows with sticky labels, threshold cell color, and a timeline scrollbar — without the map stack or app chrome. Sibling to the original timeseries table (@infoplaza/platform/timeseries), which is unchanged. The models catalog is the same (GET /api/platform/timeseries-models, or marine-timeseries-models when domain="marine"). Series load from GET /api/platform/timeseries-point-forecast (or marine-timeseries-point-forecast) unless the host passes tables / getTables. See the timeseries table demo. See API request counts and token credits in the charts platform example.

Packaged vs composed

Import only from @infoplaza/platform/timeseries-table. Do not extend the original table package, and do not add LINE to TimeseriesCellView.

<TimeseriesTableForecast
  lat={52.3676}
  lon={4.9041}
  model="gfs"
  showToolbar={false}
/>
<TimeseriesModelsProvider lat={52.3676} lon={4.9041}>
  <TimeseriesTableProvider>
    <TimeseriesTableToolbar />
    <TimeseriesTableBuilder>
      <TimeseriesTable />
    </TimeseriesTableBuilder>
  </TimeseriesTableProvider>
</TimeseriesModelsProvider>

Default groups follow domain: land uses DEFAULT_LAND_TIMESERIES_TABLE_GROUPS (Temperature, Precipitation, Wind); marine uses DEFAULT_MARINE_TIMESERIES_TABLE_GROUPS (Wind, Overall, Sea, Swell). All groups share one time axis. Group-visibility footer pills are off for now. Below Tailwind sm (640px) the table shows one day at a time, with a sticky day pager. At sm and up it keeps the full forecast and a timeline scrollbar that shows the visible hours.

Pass elementGroups to replace those defaults (it does not merge). Optional thresholds paint VALUE cells yellow / orange / red from conditions + ignored_hours.

TimeseriesSheetsForecast from @infoplaza/platform/timeseries-sheets is the same forecast turned vertical: hours are rows, parameters are columns, and the risk rail shows the worst threshold at that hour. Compose it with showDayPager={false} on the table builder.

import { TimeseriesSheetsForecast } from '@infoplaza/platform/timeseries-sheets'

<TimeseriesSheetsForecast
  lat={55.551448725742}
  lon={4.0444930642829116}
  domain="marine"
/>

Model fallback

The catalog is filtered by lat / lon, so a requested model may not exist at that point, or may be marked available: false. By default the first catalog model is used when the slug is missing. Pass onModelFallback to make that decision yourself, the same way weatherConfig.onModelFallback works on the map. It receives { models, model, lat, lon } and returns the slug to show. Unknown, empty or unchanged slugs are ignored and the built-in fallback applies.

const PREFERRED = ['harmonie', 'ecmwf', 'gfs']

<TimeseriesTableForecast
  lat={52.3676}
  lon={4.9041}
  model="harmonie"
  onModelFallback={({ models }) => {
    const visible = models.filter((m) => m.available !== false)
    return PREFERRED.find((slug) => visible.some((m) => m.slug === slug)) ?? visible[0]?.slug ?? ''
  }}
/>

The callback is not called while the catalog loads, and runs again only when the catalog, requested slug or location changes. The fallback is not reported through onModelChange. Keep the callback pure; React may call it twice in Strict Mode.

API

@infoplaza/platform/timeseries-table

Compound API. TimeseriesModelsProvider is the only writer of the catalog. TimeseriesTableProvider loads all groups once and exposes one unified matrix.
import {
  TimeseriesTableForecast,
  TimeseriesModelsProvider,
  TimeseriesTableProvider,
} from '@infoplaza/platform/timeseries-table'

Also exported: DEFAULT_LAND_TIMESERIES_TABLE_GROUPS, DEFAULT_MARINE_TIMESERIES_TABLE_GROUPS, hooks useTimeseriesTable / useTimeseriesTableContext, and types such as TimeseriesTableSnapshot, TimeseriesTableElementGroup, TimeseriesTableView, TimeseriesTableThresholds.

TimeseriesTableForecast

Packaged hourly matrix with toolbar.

Wraps TimeseriesModelsProvider and TimeseriesTableProvider, then optional Toolbar, Builder + Table. lat and lon are required. Rows load from GET /api/platform/timeseries-point-forecast (or marine-timeseries-point-forecast when domain is marine) unless you pass tables or getTables. All config groups share one time axis. Applies ip-platform for you.

import { TimeseriesTableForecast } from '@infoplaza/platform/timeseries-table'
  • Do not pass a models array. The catalog is loaded from GET /api/platform/timeseries-models (or marine-timeseries-models when domain is marine).
  • domain defaults to land. Set domain="marine" on Forecast or TimeseriesModelsProvider.
  • Builder renders one unified table, not one table per group.
  • showToolbar defaults to true. showFooter is off for now (group-visibility pills are disabled).
  • This package is a sibling of @infoplaza/platform/timeseries. The original table is unchanged.

Required props

PropTypeDefaultDescription
latnumber—Latitude of the forecast point.
lonnumber—Longitude of the forecast point.

Optional props

PropTypeDefaultDescription
basePathstring'/api/platform'Auth handler mount path.
domain'land' | 'marine''land'Which PlatformAuth proxy to use. land hits timeseries-models and timeseries-point-forecast; marine hits the marine-timeseries-* routes.
model / defaultModel / onModelChangestring—Preferred catalog slug. model without onModelChange (or defaultModel) is the initial selection; model + onModelChange is controlled. If the slug is not in the fetched catalog, the first model is used unless onModelFallback picks one.
onModelFallback(args: TimeseriesModelFallbackArgs) => string—Optional. Called with { models, model, lat, lon } when the requested slug is missing from the location-filtered catalog or is marked available: false. Return the slug to show. Unknown, empty or unchanged slugs are ignored and the built-in first-model fallback is used. Not called while the catalog loads. The fallback is not reported through onModelChange; the requested model stays as passed.
showToolbarbooleantrueRender the model / run pill toolbar.
showFooterbooleanfalseGroup-visibility pills. Off for now; leave false.
elementGroupsTimeseriesTableElementGroup[]DEFAULT_LAND_TIMESERIES_TABLE_GROUPS when domain is land, DEFAULT_MARINE_TIMESERIES_TABLE_GROUPS when marineTable config. Item view is VALUE, DIRECTION, or PRECIPITATION_TYPE. A defined array replaces domain defaults (it does not merge).
visibleGroups / defaultVisibleGroups / onVisibleGroupsChangestring[]—Which group keys are shown. Defaults to every group.
tablesTimeseriesTableSnapshot[]—Host-owned snapshots. When defined, skips the point-forecast fetch.
getTables(options) => TimeseriesTableSnapshot[]—Sync override when tables is omitted. Receives model, run, models, elementGroups, visibleGroups, locale, timezone.
localestring'en'Date headers: 'en' | 'nl' | 'de' | 'it' | 'es' | 'fr'.
thresholdsTimeseriesTableThresholds | null—Optional. conditions + ignored_hours. VALUE cells paint yellow / orange / red when matching groups fire at that hour.
classNamestring—Extra class on the root wrapper.
timestampnumber | null—Selected unix timestamp in seconds. The host owns this value. That hour column stays marked. Omit it and the current hour stays highlighted.
onTimestampChange(timestamp: number) => void—Called with the clicked hour in unix seconds. A drag-to-scroll does not fire it. Clicks in the frozen label columns do not fire it.
hoverTimestampnumber | null—Preview column in unix seconds. Highlights that column when the pointer is off the table. Does not seek timestamp. Pass a chart onHover timestamp here to sync the two.
onHover(hover: TimeseriesTableHover | null) => void—Mouse sample for the hovered hour: { timestamp, values }. timestamp is unix seconds. values maps every row slug to a number or null. Null when the pointer leaves the hour columns. Does not fire for touch, drag-to-scroll, or an external hoverTimestamp.
pinnedTimestampnumber | null—Pinned column in unix seconds. Outlines that hour column with a "Pinned" badge. Independent of timestamp and hoverTimestamp. Omit it and nothing is pinned.

Example

<TimeseriesTableForecast
  lat={52.3676}
  lon={4.9041}
  model="gfs"
  locale="en"
/>

TimeseriesModelsProvider

Location-filtered timeseries catalog (re-exported).

Same provider as @infoplaza/platform/timeseries. Required lat and lon. Fetches GET {basePath}/timeseries-models?lat=&lon= (or marine-timeseries-models when domain is marine). Re-exported so composed tables can import from one package.

import { TimeseriesModelsProvider, useTimeseriesModels } from '@infoplaza/platform/timeseries-table'

Required props

PropTypeDefaultDescription
latnumber—Latitude of the forecast point.
lonnumber—Longitude of the forecast point.

Optional props

PropTypeDefaultDescription
basePathstring'/api/platform'Auth handler mount path.
domain'land' | 'marine''land'land uses timeseries-models; marine uses marine-timeseries-models.

TimeseriesTableProvider

Selection, snapshots, and group visibility.

Must sit under TimeseriesModelsProvider. Holds model / run / visibleGroups, loads table snapshots, and exposes them to Toolbar, Builder, and Footer. No models prop. Fetches point forecast unless tables / getTables is passed.

import { TimeseriesTableProvider, useTimeseriesTable } from '@infoplaza/platform/timeseries-table'
  • useTimeseriesTable() throws outside the provider. useTimeseriesTableContext() is nullable.

Required props

None.

Optional props

PropTypeDefaultDescription
model / defaultModel / onModelChangestring—Preferred catalog slug. model without onModelChange (or defaultModel) is the initial selection; model + onModelChange is controlled.
onModelFallback(args: TimeseriesModelFallbackArgs) => string—Optional. Called with { models, model, lat, lon } when the requested slug is missing from the location-filtered catalog or is marked available: false. Return the slug to show. Unknown, empty or unchanged slugs are ignored and the built-in first-model fallback is used. Not called while the catalog loads. The fallback is not reported through onModelChange; the requested model stays as passed.
run / defaultRun / onRunChangenumber | 'all'—Runtime selection. all fetches one payload per catalog runtime.
elementGroupsTimeseriesTableElementGroup[]—Replaces domain defaults when defined (does not merge).
visibleGroups / defaultVisibleGroups / onVisibleGroupsChangestring[]—Group keys currently shown.
tablesTimeseriesTableSnapshot[]—Host-owned snapshots. Skips the fetch.
getTables(options) => TimeseriesTableSnapshot[]—Sync override when tables is omitted.
localestring'en'Date header locale.
thresholdsTimeseriesTableThresholds | null—Optional. conditions + ignored_hours. Paints VALUE cells.
timestampnumber | null—Selected unix timestamp in seconds. Flows to TimeseriesTable.
onTimestampChange(timestamp: number) => void—Called with the clicked hour in unix seconds.
hoverTimestampnumber | null—Preview column in unix seconds. Flows to TimeseriesTable.
onHover(hover: TimeseriesTableHover | null) => void—Called from the table under the pointer. Null when that pointer leaves.
pinnedTimestampnumber | null—Pinned column in unix seconds. Flows to TimeseriesTable.

TimeseriesTableToolbar

Model and run pills.

Resolves props ?? context and returns null if neither exists — it does not throw. Reuses timeseries pills internally, not map controls.

import { TimeseriesTableToolbar } from '@infoplaza/platform/timeseries-table'

Required props

None.

Optional props

PropTypeDefaultDescription
modelstring—Falls back to context.
onModelChange(slug: string) => void—Falls back to context.
runnumber | 'all'—Falls back to context.
onRunChange(run: number | 'all') => void—Falls back to context.

TimeseriesTableBuilder

Loading skeleton and compact day pager. Does not fetch.

Requires TimeseriesTableProvider. Loading skeleton, then a single child — typically TimeseriesTable. Below Tailwind sm (640px) it shows a sticky day pager so the matrix windows to one calendar day.

import { TimeseriesTableBuilder, TimeseriesTable } from '@infoplaza/platform/timeseries-table'

Required props

None.

Optional props

PropTypeDefaultDescription
childrenReactNode—Typically <TimeseriesTable />. Sheets use <TimeseriesSheets />.
showDayPagerbooleantrueCompact day pager below 640px. TimeseriesSheetsForecast sets this to false so every day stays in the vertical list.

Example

<TimeseriesTableBuilder>
  <TimeseriesTable />
</TimeseriesTableBuilder>

TimeseriesTable

Unified hourly matrix.

Reads snapshots from TimeseriesTableProvider (or explicit tables). Sticky group / label / unit columns, day and hour headers, VALUE / DIRECTION / PRECIPITATION_TYPE cells, night-hour header shading, past-hour mute, optional threshold fills, and a timeline scrollbar that shows where the visible hours sit in the forecast. Below Tailwind sm it windows to one day.

import { TimeseriesTable } from '@infoplaza/platform/timeseries-table'

Required props

None.

Optional props

PropTypeDefaultDescription
tablesTimeseriesTableSnapshot[]—Explicit snapshots. Otherwise reads provider context.
localestring—Date formatting locale.
timezonestring | null—Header timezone.
thresholdsTimeseriesTableThresholds | null—Falls back to TimeseriesTableProvider.
timestampnumber | null—Selected unix timestamp in seconds. Falls back to TimeseriesTableProvider.
onTimestampChange(timestamp: number) => void—Falls back to TimeseriesTableProvider. A drag-to-scroll does not fire it.
hoverTimestampnumber | null—Preview column in unix seconds. The pointer wins while it is over the table. Falls back to TimeseriesTableProvider.
onHover(hover: TimeseriesTableHover | null) => void—Mouse sample: { timestamp, values }. Null when the pointer leaves. Does not fire for an external hoverTimestamp. Falls back to TimeseriesTableProvider.
pinnedTimestampnumber | null—Pinned column in unix seconds. Outlines that hour column with a "Pinned" badge. Falls back to TimeseriesTableProvider.

TimeseriesTableHover

Pointer sample from onHover. Import the type from @infoplaza/platform/timeseries-table.

Fields

NameTypeDefaultDescription
timestampnumber—Hovered hour in unix seconds.
valuesRecord<string, number | null>—Every row slug at that hour.

TimeseriesSheetsForecast

Packaged vertical sheet. Same config as the table.

Same wrapper as TimeseriesTableForecast: models catalog, point forecast, and optional toolbar. Renders TimeseriesSheets instead of the horizontal matrix, and turns the compact day pager off.

import { TimeseriesSheetsForecast } from '@infoplaza/platform/timeseries-sheets'
  • Props match TimeseriesTableForecast. elementGroups, thresholds, tables, and getTables are unchanged.
  • Hours run down the page. Parameters run across, under their group titles.

Required props

PropTypeDefaultDescription
latnumber—Latitude of the forecast point.
lonnumber—Longitude of the forecast point.

Optional props

PropTypeDefaultDescription
domain'land' | 'marine''land'Same catalog and forecast routes as the table.
elementGroupsTimeseriesTableElementGroup[]—Same config as TimeseriesTableForecast. A defined array replaces domain defaults.
thresholdsTimeseriesTableThresholds | null—Worst matching level at each hour paints the risk rail. Green when nothing matches. Value cells stay uncolored.
showToolbarbooleantrueRender the model / run pill toolbar.

Example

<TimeseriesSheetsForecast
  lat={55.551448725742}
  lon={4.0444930642829116}
  domain="marine"
/>

TimeseriesSheets

Vertical hourly sheet.

Reads the same snapshots as TimeseriesTable. Sticky group, title, and unit header. Sticky risk and time columns. Day bands split the hours. Consecutive hours with the same formatted value merge inside a day. Direction columns keep the compass / arrow toggle in the unit header.

import { TimeseriesSheets } from '@infoplaza/platform/timeseries-sheets'

Required props

None.

Optional props

PropTypeDefaultDescription
tablesTimeseriesTableSnapshot[]—Explicit snapshots. Otherwise reads provider context.
localestring—Date formatting locale.
timezonestring | null—Header timezone.
thresholdsTimeseriesTableThresholds | null—Falls back to TimeseriesTableProvider. Paints the risk rail.

Example

<TimeseriesTableBuilder showDayPager={false}>
  <TimeseriesSheets />
</TimeseriesTableBuilder>