New in 0.7

Timeline

New in silverpoint 0.7 and reflex-silverpoint-react 0.7. SpTimeline draws Knight Lab's TimelineJS in silverpoint: a skin on the ground's colours and type, and the ground's own hand-inked frames and tone tiles on its markers, eras and buttons.

Install

In React, Vue and Angular, SpTimeline is on its own subpath, @silverpoint/<framework>/timeline, and @knight-lab/timelinejs (^3.9.13) is an optional peer: install it only if you use the timeline, import the subpath only with it installed, and import its stylesheet before @silverpoint/grounds/timeline.css. The server renders the surface and an empty mount; TimelineJS builds in the browser, and if it cannot be loaded the mount shows your fallback and warns SP025.

In Reflex, sp_timeline is the npm SpTimeline, and @knight-lab/timelinejs is its npm dependency, installed when a page uses it: no Python extra is needed. The [timeline] extra is empty and timeline_available() always returns True; both are kept for older code.

In your code

shell

npm install @knight-lab/timelinejs

tsx

import '@knight-lab/timelinejs/dist/css/timeline.css'; // TimelineJS's stylesheet first
import '@silverpoint/grounds/timeline.css';
import { SpTimeline } from '@silverpoint/react/timeline';

const story = {
  title: { text: { headline: 'From silverpoint to silverpoint' } },
  events: [
    { start_date: { year: 1484 }, text: { headline: 'Dürer at thirteen', text: '…' } },
    { start_date: { year: 1842 }, text: { headline: 'The cyanotype', text: '…' } },
  ],
  eras: [{ start_date: { year: 1400 }, end_date: { year: 1600 }, text: { headline: 'Metalpoint' } }],
};

<SpTimeline
  data={story}
  height="560px"
  palette={sepia} // from '@silverpoint/core/palettes'
  inkedFrames // the ground's hand-drawn frames and tone tiles
  onChange={(uniqueId) => console.log(uniqueId)} // the slide shown
  fallback={<p>The timeline could not be loaded.</p>}
/>

shell

npm install @knight-lab/timelinejs

vue

<script setup lang="ts">
import '@knight-lab/timelinejs/dist/css/timeline.css';
import '@silverpoint/grounds/timeline.css';
import { SpTimeline } from '@silverpoint/vue/timeline';

const story = {
  title: { text: { headline: 'From silverpoint to silverpoint' } },
  events: [
    { start_date: { year: 1484 }, text: { headline: 'Dürer at thirteen', text: '…' } },
    { start_date: { year: 1842 }, text: { headline: 'The cyanotype', text: '…' } },
  ],
  eras: [{ start_date: { year: 1400 }, end_date: { year: 1600 }, text: { headline: 'Metalpoint' } }],
};
</script>

<template>
  <SpTimeline :data="story" height="560px" @change="(id) => console.log(id)">
    <template #fallback><p>The timeline could not be loaded.</p></template>
  </SpTimeline>
</template>

shell

npm install @knight-lab/timelinejs

/* src/styles.css */
@import '@knight-lab/timelinejs/dist/css/timeline.css';
@import '@silverpoint/grounds/timeline.css';

// history.ts
import { Component } from '@angular/core';
import { SpTimeline, SpTimelineFallback } from '@silverpoint/angular/timeline';

const story = {
  title: { text: { headline: 'From silverpoint to silverpoint' } },
  events: [
    { start_date: { year: 1484 }, text: { headline: 'Dürer at thirteen', text: '…' } },
    { start_date: { year: 1842 }, text: { headline: 'The cyanotype', text: '…' } },
  ],
  eras: [{ start_date: { year: 1400 }, end_date: { year: 1600 }, text: { headline: 'Metalpoint' } }],
};

@Component({
  selector: 'app-history',
  imports: [SpTimeline, SpTimelineFallback],
  template: `
    <sp-timeline [data]="story" height="560px" (change)="slide = $event">
      <ng-template spFallback><p>The timeline could not be loaded.</p></ng-template>
    </sp-timeline>
  `,
})
export class History {
  protected slide: string | undefined;
  protected readonly story = story;
}

shell

pip install reflex-silverpoint-react

python

from reflex_silverpoint_react import sp_timeline

DATA = {
    "title": {"text": {"headline": "From silverpoint to silverpoint"}},
    "events": [
        {"start_date": {"year": 1484}, "text": {"headline": "Dürer at thirteen", "text": "…"}},
        {"start_date": {"year": 1842}, "text": {"headline": "The cyanotype", "text": "…"}},
    ],
    "eras": [
        {"start_date": {"year": 1400}, "end_date": {"year": 1600}, "text": {"headline": "Metalpoint"}},
    ],
}

sp_timeline(
    DATA,  # TimelineJS data (or a TimelineData of reflex-knightlab-timeline)
    height=560,
    ground="silverpoint",
    substrate="cream",
    mode="ink",
    palette="sepia",
    inked_frames=True,  # the ground's hand-drawn frames and tone tiles
    on_change=State.on_slide,  # the unique_id of the slide shown
)

Two layers: the skin and the hand

The skin replaces TimelineJS's colours, type and rules with the ground's --sp- properties: the substrate, the inks, EB Garamond, hairline rules, eras hatched by density, the current marker heightened.
The hand reads the ground's own frame and tone masks from hidden probes and lays them on the markers, eras and menubar, so they are drawn with the same pieces as the Sp components. inked_frames=False keeps the skin only; precision, cyanotype and forced colours fall back to exact rules by themselves.

Props and events

The names below are Reflex's; in JavaScript they are camelCase (inkedFrames, onNavNext in React, @nav-next in Vue, (navNext) in Angular), height is a CSS length (default '600px'), and label names the region (the title's headline when omitted).

Prop	Default
`data`	—	TimelineJS data (title, events, eras, scale), a TimelineData, or a state var.
`options`	{}	TimelineJS options; font and theme are ignored (the skin sets both).
`height`	600	Height of the whole timeline (px or a CSS length).
`inked_frames`	True	Lays the ground's hand-drawn frames and tone tiles.
`card`	True	Frames the whole timeline as a card.
`ground, substrate, mode, palette, seed`	—	The surface props.
`on_change`	—	The unique_id of the slide shown.
`on_loaded`	—	TimelineJS's loaded payload.
`on_nav_next, on_nav_previous, on_zoom_in, on_zoom_out, on_back_to_start`	—	The timeline's navigation.

Note

TimelineJS requests its icon font from a relative path (/css/icons/tl-icons.*). Where that path answers with HTML, the browser logs font-decoding warnings and the buttons lose their icons. Copy tl-icons.woff2, .woff and .ttf from @knight-lab/timelinejs/dist/css/icons into your app's assets/css/icons/, as this site does. For a light list of events, use sp_timeline_list.

Timeline

Try it

Install

In your code

Two layers: the skin and the hand

Props and events