Documentation

Timeseries

@infoplaza/platform/timeseries

A portable forecast table for other platforms — no map stack or app chrome. The models catalog and point-forecast rows load through PlatformAuth. Hosts may still override rows with blocks / getBlocks. See the timeseries demo. See API request counts and token credits in the charts platform example.

Packaged vs composed

Wrap host UI in ip-platform when you compose the stack yourself. Import only from @infoplaza/platform/timeseries.

<TimeseriesForecast
  lat={52.3676}
  lon={4.9041}
  showToolbar={false}
  showFooter={false}
/>

<TimeseriesModelsProvider lat={52.3676} lon={4.9041}>
  <TimeseriesProvider>
    <TimeseriesToolbar />
    <TimeseriesBuilder>
      <TimeseriesChart />
    </TimeseriesBuilder>
    <TimeseriesFooter />
  </TimeseriesProvider>
</TimeseriesModelsProvider>

Data flow: lat/lon → GET /api/platform/timeseries-models (or marine-timeseries-models when domain="marine") → selection → GET /api/platform/timeseries-point-forecast (or marine-timeseries-point-forecast) (unless blocks / getBlocks) → Builder maps blocks onto Chart.

API

@infoplaza/platform/timeseries

Compound API. TimeseriesModelsProvider is the only writer of the catalog. TimeseriesProvider loads chart rows by default.

import {
  TimeseriesForecast,
  TimeseriesModelsProvider,
  TimeseriesProvider,
} from '@infoplaza/platform/timeseries'

Also exported: TimeseriesPills, ScrollSync, TIMESERIES_CELL_VIEWS, DEFAULT_TIMESERIES_ELEMENT_GROUPS, hooks useTimeseries / useTimeseriesContext / useTimeseriesBlock, and types such as TimeseriesBlock, TimeseriesRow, TimeseriesCell.

TimeseriesForecast

Packaged forecast table with toolbar, table, and footer.

Wraps TimeseriesModelsProvider and TimeseriesProvider, then renders optional Toolbar, Builder + Chart, and Footer. lat and lon are required. Chart rows load from GET /api/platform/timeseries-point-forecast (or marine-timeseries-point-forecast when domain is marine) unless you pass blocks or getBlocks. Applies the ip-platform class for you.

import { TimeseriesForecast } from '@infoplaza/platform/timeseries'

Do not pass a models array. The catalog is loaded from the auth route using lat and lon.
domain defaults to land. Set domain="marine" to use the marine timeseries catalog and point-forecast routes.
showToolbar and showFooter default to true. Set both to false for a chart-only table.
All TimeseriesProvider selection and display props are forwarded.

Required props

Prop	Type	Default	Description
lat	number	—	Latitude of the forecast point.
lon	number	—	Longitude of the forecast point.

Optional props

Prop	Type	Default	Description
basePath	string	'/api/platform'	Auth handler mount path. Requests go to ${basePath}/timeseries-models (or marine-timeseries-models when domain is marine).
domain	'land' \| 'marine'	'land'	Which PlatformAuth proxy to use. land hits timeseries-models and timeseries-point-forecast; marine hits the marine-timeseries-* routes.
showToolbar	boolean	true	Render the model / run pill toolbar.
showFooter	boolean	true	Render the element-group footer pills.
locale	string	'en'	Date headers: 'en' \| 'nl' \| 'de' \| 'it' \| 'es' \| 'fr'. Others fall back to en.
blocks	TimeseriesBlock[]	—	Host-owned rows. When defined, skips the point-forecast fetch.
getBlocks	(options) => TimeseriesBlock[]	—	Sync override used when blocks is omitted. Receives model, run, elementGroup, models, elementGroups.
showPalette	boolean	false	When true, cell background and text colors from the palette are applied.
headerFormat	[string, string]	—	Date header formats, e.g. ['EEEEEE d MMM', 'HH'].
scrollToCurrentTime	boolean	—	Scroll the table to the current hour on mount.
getIconSrc	(value: number \| null) => string \| null	—	Host-supplied ICON cell images. The package does not bundle weather icons.
className	string	—	Extra class on the root ip-platform wrapper.

Example

<TimeseriesForecast
  lat={52.3676}
  lon={4.9041}
  locale="en"
  headerFormat={['EEEEEE d MMM', 'HH']}
  scrollToCurrentTime
/>

TimeseriesModelsProvider

Location-filtered models catalog.

Required lat and lon. Fetches GET {basePath}/timeseries-models?lat=&lon= (or marine-timeseries-models when domain is marine). Context is read-only: { models, loading, error, lat, lon, basePath, domain }. There is no models setter.

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

The catalog is API-only. Do not pass a models array into Provider or Forecast.
useTimeseriesModels() throws outside this provider. useTimeseriesModelsContext() is nullable.

Required props

Prop	Type	Default	Description
lat	number	—	Latitude.
lon	number	—	Longitude.

Optional props

Prop	Type	Default	Description
basePath	string	'/api/platform'	Auth mount path. Trailing slashes are stripped.
domain	'land' \| 'marine'	'land'	land uses timeseries-models; marine uses marine-timeseries-models. Point-forecast fetches follow the same domain from this context.
children	ReactNode	—	Usually TimeseriesProvider.

TimeseriesProvider

Selection, blocks, and display settings.

Must sit under TimeseriesModelsProvider. Holds model / run / elementGroup / directionView, loads chart rows, and exposes them to Toolbar, Builder, and Footer. No models, lat, or lon props — those live on the models provider.

import { TimeseriesProvider, useTimeseries } from '@infoplaza/platform/timeseries'

Selection is hybrid: model + onModelChange (controlled) or defaultModel / omit (provider-owned). Same for run, elementGroup, directionView.
Unknown slugs are clamped to the fetched catalog.
blocks wins over getBlocks wins over the default point-forecast fetch.
run === 'all' fetches one point-forecast request per catalog runtime and returns one block per runtime.
useTimeseries() throws outside the provider. useTimeseriesContext() is nullable.

Required props

None.

Optional props

Prop	Type	Default	Description
model / defaultModel / onModelChange	string	—	Selected catalog slug. Empty selection falls back to the first model.
run / defaultRun / onRunChange	number \| 'all'	—	Selected runtime. Invalid values fall back to the latest runtime or all.
elementGroups	TimeseriesElementGroup[]	DEFAULT_TIMESERIES_ELEMENT_GROUPS	Footer groups. Default keys include overview, temperature, wind, precipitation, and more.
blocks	TimeseriesBlock[]	—	When defined, skips fetching.
getBlocks	(TimeseriesGetBlocksOptions) => TimeseriesBlock[]	—	Sync host override when blocks is omitted.
locale	string	'en'	Date header locale.
timezone	string \| null	null	IANA timezone for headers. Null uses the runtime default.
views	TimeseriesCellViewMap	—	Override built-in cell views: VALUE, VALUE_ROUND, DIRECTION, PRECIPITATION_TYPE, ICON.
showPalette	boolean	—	Forwarded to the table. Defaults to false on TimeseriesTable.

TimeseriesToolbar

Model and run pills.

Resolves props ?? context and returns null if models, model, handlers, or run are missing — it does not throw. Shows at most five model pills plus overflow. Adds an All run pill when the catalog has more than one runtime.

import { TimeseriesToolbar } from '@infoplaza/platform/timeseries'

Required props

None.

Optional props

Prop	Type	Default	Description
model	string	—	Falls back to context.
onModelChange	(slug: string) => void	—	Falls back to context.
run	number \| 'all'	—	Falls back to context.
onRunChange	(run: number \| 'all') => void	—	Falls back to context.
locale	string	—	Falls back to context, then 'en'.

TimeseriesBuilder

Maps blocks onto Chart. Does not fetch.

Requires TimeseriesProvider. Shows a loading skeleton, then wraps each TimeseriesBlock in a block context and ScrollSync. Clone children once per block.

import { TimeseriesBuilder, TimeseriesChart } from '@infoplaza/platform/timeseries'

Required props

None.

Optional props

Prop	Type	Default	Description
children	ReactNode	—	Typically <TimeseriesChart />. Repeated once per block.

Example

<TimeseriesBuilder>
  <TimeseriesChart />
</TimeseriesBuilder>

TimeseriesChart

Bridge from block / provider context to TimeseriesTable.

All props are optional Partial<TimeseriesTableProps>. Rows come from the prop, then the current block. Returns null if there are no rows.

import { TimeseriesChart } from '@infoplaza/platform/timeseries'

Required props

None.

Optional props

Prop	Type	Default	Description
rows	TimeseriesRow[]	—	Explicit rows. Otherwise reads the current builder block.

TimeseriesFooter

Element-group pills.

Resolves props ?? context. Loading renders a pulse skeleton. Returns null if there are no items or handler.

import { TimeseriesFooter } from '@infoplaza/platform/timeseries'

Required props

None.

Optional props

Prop	Type	Default	Description
elementGroups	TimeseriesElementGroup[]	—	Falls back to context.
elementGroup	string	—	Selected group key.
onElementGroupChange	(key: string) => void	—	Falls back to context.

TimeseriesTable

Low-level forecast grid.

Frozen labels, drag-scroll, grouped date headers, current-hour highlight, optional hidden-rows expander, and the cell-view registry. Used by TimeseriesChart; you can also render it standalone with rows.

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

Required props

Prop	Type	Default	Description
rows	TimeseriesRow[]	—	Table rows. Each cell has timestamp, value, and color { background, text }.

Optional props

Prop	Type	Default	Description
headerFormat	[string, string]	['EEEEEE d MMM', 'HH']	date-fns format strings for the grouped header and the hour row.
scrollToCurrentTime	boolean	false	Scroll the grid to the current hour on mount.
showPalette	boolean	false	Apply cell background and text colors.
scrollbar	boolean	true	Show the horizontal scrollbar.
hideEmptyRows	boolean	false	Hide rows whose cells are all empty.