tickslate 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,195 @@
+# Changelog
+
+All notable changes to Tickslate are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/).
+
+## 0.1.0 — Unreleased
+
+The first release. The date is filled in when it is published. Version 0.0.0
+was only ever a private scaffold, so nothing is breaking for anyone who has
+installed from npm. The Changed and Breaking entries below describe how this
+release differs from the development builds that came before it, for anyone
+who tried the repository early.
+
+### Added
+
+A grid that works from markup
+
+- `<ts-grid>`: lays out its children as a resizable dashboard that reflows
+  across 4, 3 and 2 columns, with phone and tablet reflow and gap-filling
+  placement that matches CSS `grid-auto-flow: dense`. With no `layout` set,
+  every child becomes a tile. Its type comes from the tag, its size from the
+  child's `size` attribute (else the first size it supports), and its id from
+  `item`. The grid keeps the user's arrangement when the host re-renders.
+  Setting `layout` to a `Layout` or an array of items switches to explicit mode.
+- Per-child sizing: each child's `spec`, or its `sizes` and `label` attributes,
+  decides what it snaps to, so two children of one type can differ.
+- Market and closed layouts that switch on a `schedule`, with `override()` for
+  the manual switch and a replaceable `clock`.
+- `persistLayout(grid, { key, defaults?, storage? })`: loads the user's layout
+  for the current device, saves each `ts-layout-change`, switches between phone
+  and desktop entries, repairs corrupt data and treats throwing storage as
+  empty. Returns `{ reset(device?), dispose() }`.
+- Events: `ts-layout-change` (with `items`, `previous`, and on a remove `index`
+  and `item`; reasons include `'undo'` and `'add'`), `ts-columns-change` (with
+  `initial`, fired once after the first measure), `ts-layout-issues`,
+  `ts-edit-change` and `ts-action`.
+- Core: `readLayout` (which also takes a plain array, and
+  `{ unknown: 'keep' }` to keep items no catalog knows), pure editing
+  operations, `dropIndex`, `sizeForExtent`, `DEFAULT_PROFILE`, `typeForTag`,
+  and catalogs given as a function `(item) => spec | null`.
+
+Editing that is safe and accessible
+
+- Edit like an iPhone home screen: long press or `editing` to start, drag with
+  live reflow, a resize handle that snaps between supported sizes, remove
+  badges, edge auto-scroll and full keyboard support.
+- Built-in controls, so no host has to build UI: a visually hidden "Edit layout"
+  button that is the grid's first Tab stop, and a floating edit pill
+  (`part="edit-pill"`) with Done and "Add back (n)". Hide them with `locked` or
+  `edit-controls="off"`.
+- `locked`: a read-only dashboard.
+- `grid.undo()` (20 steps per profile, Ctrl or Cmd+Z while editing) and an undo
+  toast after a remove (`part="toast"`, `undo-toast="off"` to suppress).
+  `grid.hiddenItems` and `grid.restore(id)` bring removed tiles back.
+- Tap-to-place for users who cannot drag (WCAG 2.5.7), shared with the keyboard
+  moves, plus polite status announcements for every edit and focus handling
+  that survives reorders, removes and the end of editing.
+- An empty board message ("No widgets on this layout yet", replaceable through
+  `slot="empty"`), with Add back when tiles are hidden.
+- Development warnings (`tickslate:` prefix) for the common integration
+  mistakes: an explicit-mode child with no `item`, a layout item with no
+  child, a dashed tag that is never defined, and repeated generated ids.
+
+Widgets
+
+- `<ts-card>`: a themed tile for any content, including another library's
+  chart, at all seven sizes. Slots `value`, `actions`, `footer` and `empty`; the
+  default slot is a body that a `height: 100%` child fills. Attributes `label`,
+  `sizes`, `live`, `as-of` and `scrollable`.
+- `<ts-metric>`: a KPI tile at S, Wide and M with a signed change (from `delta`,
+  `deltaPct` or `previous`), `goodWhen`, a sparkline, a target bar, and
+  `number`, `money`, `percent` and `duration` formats plus `unit` and `compact`.
+- `<ts-chart>`: line and area trends for up to four series at Wide, M, L and XL,
+  from `{ series }` or `{ rows, x, y }`, with a legend, gridlines and axis labels
+  by size. The kind never relies on colour alone.
+- `<ts-today-pnl>`, `<ts-equity-curve>` and `<ts-session-clock>`: the finance
+  set, with an intraday curve, peak and max drawdown with range buttons, and
+  exchange session lanes.
+- The widget base `TsWidget` for your own widgets: open shadow root, shared
+  themed CSS, `data`, `size`, `label`, `clock`, `static spec`,
+  `static dataShape`, one render per microtask and `every()` for timers that
+  pause while the page is hidden. See `docs/guide/your-own-widget.md`.
+- Every widget has `spec`, `tickslateVersion` and the loading, empty and error
+  views below.
+
+Data and states
+
+- Loading, empty and error views on every widget. Data never set shows a
+  skeleton and `aria-busy`; `data = null` shows the empty state; the `state`
+  attribute and `error` property show the error view, with Retry when `actions`
+  includes `'retry'`. A `slot="empty"` child replaces the empty text.
+- The `data` attribute: a value starting with `{` or `[` is parsed as JSON, so a
+  server template can pass data with no script.
+- `toTime(v)` and `toDay(v, timeZone?)`: instants as epoch seconds or
+  milliseconds, a `Date`, an ISO 8601 string (including six-digit microseconds)
+  or a numeric string. `toNumber` accepts decimal-library objects with a
+  `toNumber()` method. Time zones flow through `equitySeries`, `equityStats`
+  and `filterRange`.
+- Development checks against each widget's `dataShape`, naming the element, its
+  `item`, the path and what arrived; warnings for invalid JSON, an invalid
+  `locale`, `currency` or `time-zone`, dropped rows and data still unset after
+  10 s. A render failure logs the element and a docs link, in production too.
+- Formatting: `createFormatter` (signed money with the true minus sign, lakh
+  grouping, compact forms, prices, percents, 24-hour times, durations, `fit`)
+  and `configure` for defaults. `fmt.unit(value, unit)` formats units, and
+  `fit` takes `{ style: 'money' | 'number' | 'percent' }`. Invalid options fall
+  back to the defaults and are listed in `formatter.issues`.
+- Session calendars: `createCalendar` with holidays and special sessions,
+  `state`, `nextChange`, `candleClose` and `windows`; NSE and MCX presets;
+  `activeProfile` and `nextProfileChange`.
+
+Install and theming
+
+- Tiles look finished with only `import 'tickslate/elements'`: the default
+  tokens are adopted in `@layer tickslate.defaults` when the page has none, and
+  anything you define wins. Before the elements upgrade, tiles reserve their
+  height so the page does not jump.
+- Theme through `--ts-*` tokens only. Paper (light) and Graphite (dark), light
+  and dark islands with `data-theme`, `--ts-axis`, `--ts-focus` and
+  `--ts-series-1` to `--ts-series-6`, plus the layout tokens `--ts-row-compact`,
+  `--ts-gap-compact`, `--ts-num-weight`, `--ts-shadow-lift`, `--ts-motion` and
+  `--ts-ease`.
+- A development build: `tickslate/elements` resolves to `elements.dev.js` under
+  the `development` export condition, with every warning. Production builds
+  resolve `elements.js`, which has none.
+- Types for everything, including `grid.d.ts` and `widget.d.ts`.
+
+Documentation
+
+- A README from install to a saved dashboard, framework recipes for React,
+  Vue, Svelte and Angular, and guides for saving layouts, server templates and
+  bringing your own chart.
+- Reference pages for every element, every core export, every event and every
+  theme token, in `docs/`.
+- `examples/` (quickstart, generic dashboard, bare), a playground and a widget
+  gallery.
+
+### Changed
+
+- Dark mode follows the page, not the OS, by default; see Breaking.
+- `--ts-font-num` falls back to a system sans stack after Newsreader instead of
+  Georgia, whose digits are old-style and proportional.
+- `fit` tries the full form, then (for `number` and `percent`) no decimals, then
+  compact, and returns the compact form only when it is shorter. Money still
+  goes straight from full to compact.
+- `<ts-grid>` reads every layout with `unknown: 'keep'`, so a tile whose tag is
+  not defined yet survives a save, and fires `ts-layout-issues` only when the
+  host sets `layout` or `catalog`.
+- A widget with no label is named by its tag, and registering a tag that
+  another class owns warns in development.
+- The edit chrome is a plain container with three sibling buttons (handle,
+  Remove, Resize); managed tiles are `inert` while editing; focus rings are
+  `outline`, so they survive forced colours; Escape ends editing only when
+  focus is inside the grid.
+- Double-clicking a remove badge, or pressing Delete twice, removes one tile.
+- Requires Node 20 or later wherever Node is used (`engines`).
+- The dark theme is called Graphite in the docs and demos. `data-theme="dark"`,
+  `.dark` and every token name are unchanged.
+
+### Breaking
+
+- OS dark mode is opt-in. With no `data-theme` and no `.dark` class, tiles stay
+  light whatever `prefers-color-scheme` says. Set `data-theme="auto"` on
+  `<html>` or any ancestor to follow the OS.
+- A widget whose `data` was never set (`undefined`) shows a loading skeleton,
+  not "No data". Set `data = null` to show the empty state. A view model that
+  throws shows the error view instead of the empty state.
+- A number below 1e11 in an instant field is read as epoch seconds, not
+  milliseconds. Millisecond values from before March 1973 would be misread;
+  send an ISO string for those.
+- `toNumber` is stricter: `'0x10'`, `'0b1'`, `'Infinity'` and `''` are `NaN`.
+  Only decimal and exponent strings parse.
+- The grid's edit chrome markup is `.chrome > .handle + .remove + .resize`. A
+  host reaching into the shadow root for `.chrome[role=button]` must update.
+  Attributes, parts and events are unchanged.
+- Hosts that listen for `ts-layout-change` should expect the new reasons
+  `'undo'` and `'add'`.
+- The playground's old saved layout (`tickslate-playground-layout`) is no
+  longer read.
+
+### Internal
+
+- Tests run with `node --test` and need no install. Real-browser tests run
+  with `npm run test:browser` in Chromium, WebKit and an iPhone profile,
+  including axe checks over every widget and the grid in both themes.
+- `npm run release` runs test, build:lib, build:dev, build:umd, pack:lib,
+  verify:package and size. `verify:package` checks the manifest, exports,
+  version agreement, DOM-free imports and the tarball allowlist. `npm run size`
+  enforces gzipped budgets of 9.5 kB for the core and the UMD build and 50 kB
+  for `tickslate/elements` with its core, each measured plus 10 %.
+- `docs/rfc/0002-integration-and-ux.md` is the approved contract for this
+  release, `docs/ACCESSIBILITY.md` the definition of done for every widget, and
+  `docs/RELEASING.md` the maintainer's publish steps.
+- Tests, docs and demos use made-up figures only.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shreeshyla Hanasoge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,243 @@
-# Temporary Holding Version
+# Tickslate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Dashboard widgets for the web: a resizable grid, KPI tiles, charts and cards
+for any data, with a finance set built in.
+
+The widgets are custom elements, so the same code runs in plain HTML, Vue,
+React, Svelte and Angular. The core has no runtime dependencies, every colour
+is a `--ts-*` CSS variable, and your app passes the data in: Tickslate never
+fetches anything.
+
+- **A grid users can rearrange.** Seven fixed sizes on a 4-column grid that
+  drops to 3 columns on tablets and 2 on phones. Long-press to edit, drag to
+  move, drag the corner to resize, and Undo or Add back after a removal.
+- **Generic widgets.** `<ts-metric>` (a KPI tile with change, sparkline and
+  target), `<ts-chart>` (line and area trends) and `<ts-card>` (a themed tile
+  for any content, such as your own Chart.js or ECharts chart).
+- **A finance set.** Today's P&L, an equity curve and an exchange session
+  clock, with more to come.
+- **Accessible by default.** Each widget is a labelled region, charts state
+  their result in words, gains and losses carry a sign as well as a colour, and
+  motion respects `prefers-reduced-motion`. See [docs/ACCESSIBILITY.md](docs/ACCESSIBILITY.md).
+
+## Install
+
+```bash
+npm install tickslate
+```
+
+```js
+import 'tickslate/elements' // registers <ts-grid> and the widgets
+```
+
+Without a bundler, load it from jsDelivr. Pin an exact version so a release
+can never change your page. This works once 0.1.0 is published to npm.
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/tickslate@0.1.0/elements.js"></script>
+```
+
+To use a named export from a page script, import it from the same URL:
+`import { persistLayout } from 'https://cdn.jsdelivr.net/npm/tickslate@0.1.0/elements.js'`.
+
+### Fonts (optional)
+
+Text is set in Geist and figures in Newsreader. Both are optional: without
+them the tiles fall back to the system UI font, with tabular digits so live
+numbers don't jitter. To use them, load them yourself:
+
+```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600&family=Newsreader:wght@500;600&display=swap">
+```
+
+Or point `--ts-font-ui` and `--ts-font-num` at your own fonts (see Theming).
+
+### tokens.css
+
+The elements carry their default theme, so tiles look finished with no
+stylesheet at all. Linking `tokens.css` is still the clearest way to see and
+override every variable, and it always beats the built-in defaults:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tickslate@0.1.0/tokens.css">
+```
+
+```js
+import 'tickslate/tokens.css'
+```
+
+## Quick start
+
+Markup is the whole layout: the grid reads its children, in order. The
+`persistLayout` line saves what users change and restores it on the next visit.
+
+<!-- quickstart -->
+```html
+<ts-grid>
+  <ts-metric label="Signups" size="S" data='{"value": 1204, "previous": 1075, "compareLabel": "vs last week"}'></ts-metric>
+  <ts-chart label="Revenue" size="Wide" data='{"series": [{"name": "Revenue", "points": [{"x": "2026-09-01", "y": 11800}, {"x": "2026-09-02", "y": 12400}, {"x": "2026-09-03", "y": 12100}]}]}'></ts-chart>
+  <ts-card label="Notes" sizes="S Wide M"><p>Deploy freeze from Friday.</p></ts-card>
+</ts-grid>
+<script type="module">
+  import { persistLayout } from 'tickslate/elements'
+  persistLayout(document.querySelector('ts-grid'), { key: 'ops-dashboard' })
+</script>
+```
+<!-- /quickstart -->
+
+[examples/quickstart.html](examples/quickstart.html) is this snippet as a page.
+Run `npm run dev` and open `/examples/quickstart.html`. All figures in this
+repository are made up.
+
+## Data in
+
+Every widget renders the `data` you give it. Set it as a property (any
+framework can) or, in server-rendered pages, as a JSON attribute.
+
+```js
+document.querySelector('ts-metric').data = { value: 1204, previous: 1075 }
+```
+
+| You set | The tile shows |
+|---|---|
+| Nothing yet (`undefined`) | A loading skeleton shaped like the content |
+| `null` | The empty state ("No data yet"), or your `slot="empty"` content |
+| `state = 'loading'` | The skeleton again, over existing data, during a re-fetch |
+| `error = 'Could not load'` | An error message, and a Retry button if `actions = ['retry']` |
+| An object | The content |
+
+Dates and times can be ISO strings, `Date`s or numbers (below 1e11 means
+seconds). Decimal strings such as `"12.50"` are read as numbers, because some
+backends send decimals that way.
+
+### JSON attributes
+
+For Blade, Django, Rails and static pages, put the data in the `data`
+attribute. A value starting with `{` or `[` is parsed as JSON; once you set the
+`data` property, the attribute is ignored. A parse error shows the error view
+and, in development builds, a console warning with the position. See
+[docs/guide/server-templates.md](docs/guide/server-templates.md).
+
+```html
+<ts-metric label="Signups" data='{"value": 1204, "previous": 1075}'></ts-metric>
+```
+
+## Saving layouts
+
+```js
+import { persistLayout } from 'tickslate/elements'
+
+persistLayout(document.querySelector('ts-grid'), { key: 'ops-dashboard' })
+```
+
+This loads the saved layout for the current device (desktop and phone are kept
+apart), saves every change to `localStorage`, and ignores storage that is full
+or blocked. It returns `{ reset(device?), dispose() }`. To save somewhere else,
+listen for `ts-layout-change` and store `event.detail.layout`. See
+[docs/guide/saving-layouts.md](docs/guide/saving-layouts.md).
+
+## Edit mode
+
+Editing is on by default. A long press (or the visually hidden **Edit layout**
+button, the grid's first Tab stop) starts it. While editing, a floating pill
+offers **Done** and, once a tile has been removed, **Add back (n)**. Tapping
+outside the grid, or pressing Escape, ends it. Removing a tile shows an Undo
+toast, and Ctrl or Cmd+Z undoes while editing.
+
+| Attribute or property | Effect |
+|---|---|
+| `locked` | A read-only dashboard: no edit mode and no controls |
+| `edit-controls="off"` | Hides the built-in button, pill and Add back, for hosts with their own UI. Long press still works |
+| `undo-toast="off"` | No toast after a removal |
+| `editing` | Starts or ends edit mode from code |
+| `grid.hiddenItems`, `grid.restore(id)`, `grid.undo()` | Build your own Add back and Undo |
+
+## Events
+
+All events bubble and are composed, so you can listen on the grid or higher up.
+
+| Event | Fired by | `detail` |
+|---|---|---|
+| `ts-layout-change` | `<ts-grid>`, after an edit | `{ layout, items, previous, profile, reason, id, index?, item? }`; `reason` is `move`, `resize`, `remove`, `add` or `undo`. Save `layout` |
+| `ts-layout-issues` | `<ts-grid>`, when a layout you set was repaired | `{ issues }` |
+| `ts-edit-change` | `<ts-grid>` | `{ editing }` |
+| `ts-columns-change` | `<ts-grid>`, also once after the first measure | `{ columns, device, initial }` |
+| `ts-profile-change` | `<ts-grid>`, when a schedule or override switches profile | `{ profile, reason }` |
+| `ts-action` | any widget | `{ action, ... }`, such as `retry` or an equity curve's `range` |
+
+## Theming
+
+Dark mode is opt-in, and every colour, radius and font is a variable. Override
+a few anywhere in your CSS:
+
+```css
+:root {
+  --ts-accent: #0b6bcb;
+  --ts-surface: #fff;
+  --ts-radius: 6px;
+  --ts-font-ui: 'Inter', system-ui, sans-serif;
+}
+```
+
+Set `data-theme="auto"` on `<html>` to follow the operating system, or
+`data-theme="dark"` (or a `.dark` class) for the dark theme, called Graphite.
+`data-theme="light"` makes a light island inside a dark page. The light theme
+is called Paper.
+
+## Browser support
+
+Chrome 111, Safari 16.2 and Firefox 113 or later: the grid needs custom
+elements, shadow DOM, `ResizeObserver`, `color-mix()` and `:where()`.
+Server-side rendering is safe: importing the package where there is no DOM
+registers nothing.
+
+## ESM only
+
+The package is ES modules only. If Jest has to transform it, let it through:
+
+```js
+transformIgnorePatterns: ['/node_modules/(?!tickslate/)']
+```
+
+## Guides
+
+- Frameworks: [React](docs/guide/frameworks/react.md),
+  [Vue](docs/guide/frameworks/vue.md),
+  [Svelte](docs/guide/frameworks/svelte.md),
+  [Angular](docs/guide/frameworks/angular.md)
+- [Saving layouts](docs/guide/saving-layouts.md)
+- [Your own widget](docs/guide/your-own-widget.md)
+- Reference: [widgets](docs/widgets/), [core](docs/reference/core.md),
+  [events](docs/reference/events.md), [theming](docs/theming.md)
+- [Server templates](docs/guide/server-templates.md) (Blade, Django)
+- [Bring your own chart](docs/guide/bring-your-own-chart.md) (Chart.js, ECharts)
+- The contract: [RFC 0001](docs/rfc/0001-api.md) and
+  [RFC 0002](docs/rfc/0002-integration-and-ux.md). Data shapes are in the
+  `.d.ts` files: [elements](src/elements/index.d.ts),
+  [grid](src/elements/grid.d.ts) and [core](src/core/index.d.ts).
+
+### Widgets
+
+| Tag | Sizes | For |
+|---|---|---|
+| `<ts-metric>` | S, Wide, M | A KPI with change, sparkline and target |
+| `<ts-chart>` | Wide, M, L, XL | Line and area trends (rows or series) |
+| `<ts-card>` | all seven | Any content, such as your own chart |
+| `<ts-today-pnl>` | S, Wide, M | Today's net, realized and unrealized P&L |
+| `<ts-equity-curve>` | Wide, M, XL | Cumulative P&L with ranges and drawdown |
+| `<ts-session-clock>` | S, Banner | Exchange session status |
+
+## Development
+
+```bash
+npm install
+npm run dev        # playground at http://localhost:5173
+npm test           # node --test, no install needed
+npm run release    # test, build ESM + UMD, assemble dist-lib/
+```
+
+Publishing is done from the assembled folder: `npm publish ./dist-lib`.
+
+## Licence
+
+MIT © Shreeshyla Hanasoge

package/elements.d.ts

@@ -0,0 +1,214 @@
+import type { Calendar, DayResult, Layout, LayoutItem, Numeric, SizeName, Time } from './index.js'
+import { TsWidget } from './widget.js'
+import type { ViewModelContext } from './widget.js'
+
+export { version } from './index.js'
+// widget.d.ts is shipped beside this file (scripts/pack-lib.mjs), so this
+// import resolves both in the repo and in the published package.
+export { TsWidget } from './widget.js'
+export type { ViewModelContext, WidgetState } from './widget.js'
+// grid.d.ts is shipped beside this file too (scripts/pack-lib.mjs).
+export * from './grid.js'
+import type { TsGrid } from './grid.js'
+
+export interface PersistLayoutOptions {
+  /** Each device is stored under `${key}:${device}`. */
+  key: string
+  /** A Layout or item array serves both devices; in the object form `phone` falls back to `desktop`. */
+  defaults?: Layout | LayoutItem[] | { desktop: Layout | LayoutItem[]; phone?: Layout | LayoutItem[] }
+  /** Defaults to `localStorage` when it exists. Storage that throws is treated as empty. */
+  storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null
+}
+
+/** Loads the grid's layout for its device, saves every `ts-layout-change`, and reloads when the device changes. */
+export declare function persistLayout(
+  grid: TsGrid,
+  options: PersistLayoutOptions
+): { reset(device?: 'desktop' | 'phone'): void; dispose(): void }
+
+/** Freshness, allowed on every widget's data (RFC 0001 §8.1). */
+export interface WidgetFreshness {
+  /** When the data was taken: any Time, read with toTime (RFC 0002 §4.1). */
+  asOf?: Time
+  /** Shows the pulsing dot. */
+  live?: boolean
+}
+
+export interface CardData extends WidgetFreshness {}
+
+/**
+ * <ts-card>, every size. Slots: default (the body), value, actions, footer and empty.
+ * Attributes: label, sizes (whitespace-separated, default all seven), live, as-of, scrollable.
+ * `data` only updates the header; `data = null` never replaces slotted content.
+ */
+export declare class TsCard extends TsWidget<CardData> {
+  static dataOptional: true
+  /** From the sizes and label attributes. */
+  get spec(): { label: string; sizes: SizeName[] }
+}
+
+export interface MetricData extends WidgetFreshness {
+  value: Numeric
+  /** Default 'number'. 'percent' takes a fraction (0.12 is 12%); 'duration' takes milliseconds. */
+  format?: 'number' | 'money' | 'percent' | 'duration'
+  decimals?: number
+  /** Formatted with `fmt.unit`: '182 ms', '3 seats'. */
+  unit?: string
+  /** '1.2M' at every size. Without it, S still goes compact when the figure is too long. */
+  compact?: boolean
+  /** With format 'percent': value, previous, delta and target are 0 to 100. */
+  percentPoints?: boolean
+  previous?: Numeric
+  /** The absolute change; wins over `previous`. */
+  delta?: Numeric
+  /** The change as a fraction (0.12 is 12%); always a fraction, whatever `percentPoints` says. */
+  deltaPct?: Numeric
+  /** Shown after the delta, e.g. 'vs last week'. */
+  compareLabel?: string
+  /** Which way is good, for the delta's colour. Default 'up'. */
+  goodWhen?: 'up' | 'down' | 'neither'
+  /** Wide and M: the sparkline. Plain numbers are spaced evenly. */
+  series?: Array<{ t: Time; v: Numeric }> | Numeric[]
+  /** M: the bar's goal; no bar when 0 or less. */
+  target?: Numeric
+  /** M: one line under the bar. */
+  caption?: string
+}
+
+export interface MetricModel {
+  label: string
+  live: boolean
+  time: string
+  sparkLabel: string
+  ariaLabel: string
+  value: string
+  delta: string
+  arrow: '▲' | '▼' | ''
+  tone: 'pos' | 'neg' | 'mut'
+  compare: string
+  line: string
+  area: string
+  targetPct: string
+  targetWidth: number
+  caption: string
+  dropped: number
+}
+
+/** <ts-metric>, sizes S · Wide · M. */
+export declare class TsMetric extends TsWidget<MetricData> {
+  /** Pure: data to display strings, paths and the accessible name. */
+  static metricModel(data: MetricData, variant: SizeName, ctx: ViewModelContext): MetricModel
+}
+
+export type ChartKind = 'line' | 'area'
+
+export interface ChartSeries {
+  id?: string
+  name: string
+  /** Default 'line'. */
+  kind?: ChartKind
+  /** Read in any order; x with `toTime` (or `toNumber` when `xType` is 'number'), y with `toNumber`. */
+  points: Array<{ x: Time; y: Numeric }>
+}
+
+export interface ChartOptions extends WidgetFreshness {
+  /** How x is read. Default 'time'. */
+  xType?: 'time' | 'number'
+  /** How each series' last value is shown. Default 'number'; 'percent' takes fractions, 'duration' milliseconds. */
+  format?: 'number' | 'money' | 'percent' | 'duration'
+  decimals?: number
+  /** Formatted with `fmt.unit`: '182 ms'. */
+  unit?: string
+  /** Accepted for parity with `<ts-metric>`; no chart size shows a change yet. */
+  goodWhen?: 'up' | 'down' | 'neither'
+}
+
+/** Either named series, or rows with the keys to read. At most four series are drawn. */
+export type ChartData = ChartOptions &
+  (
+    | { series: ChartSeries[] }
+    | {
+        rows: Array<Record<string, unknown>>
+        /** The row key for x. */
+        x: string
+        y: string | string[] | Array<{ key: string; name?: string; kind?: ChartKind }>
+      }
+  )
+
+export interface ChartModel {
+  /** What the svg's `aria-label` says: 'Revenue, last 12,400; Cost, last 8,100'. */
+  ariaLabel: string
+  series: Array<{ name: string; kind: ChartKind; line: string; area: string; last: string }>
+  /** `index` 1 to 4 picks `--ts-series-<n>`. */
+  legend: Array<{ name: string; index: number }>
+  axis: { start: string; middle: string; end: string }
+  /** Where the zero line falls in the 400 by 100 drawing box, drawn in `--ts-axis`. */
+  zeroY: number
+  /** Rows or points that couldn't be read. */
+  dropped: number
+}
+
+/** <ts-chart>, sizes Wide · M · L · XL. Lines and areas, up to four series, legend from M up. */
+export declare class TsChart extends TsWidget<ChartData> {
+  /** Pure: data to paths, labels and the accessible name. */
+  static chartModel(data: ChartData, variant: SizeName, ctx: ViewModelContext): ChartModel
+}
+
+export interface TodayPnlData extends WidgetFreshness {
+  /** Shown exactly as given; the widget never recomputes it from the parts. */
+  net: Numeric
+  realized: Numeric
+  unrealized: Numeric
+  /** Shown as a deduction whichever way it is signed. */
+  fees: Numeric
+  closedCount?: number
+  openCount?: number
+  /** M: the curve. Readings need not arrive in order. */
+  intraday?: Array<{ t: Time; v: Numeric }>
+  /** M: dots on the curve; ones outside the readings are left out. */
+  marks?: Array<{ t: Time; kind: 'entry' | 'exit'; label?: string }>
+  /** M: the x-axis span, e.g. today's session from `calendar.hours()`. Defaults to the readings' span. */
+  window?: { from: Time; to: Time }
+}
+
+/** <ts-today-pnl>, sizes S · Wide · M. */
+export declare class TsTodayPnl extends TsWidget<TodayPnlData> {}
+
+export type EquityRange = '1W' | '1M' | '3M' | 'YTD' | 'All'
+
+export interface EquityCurveData extends WidgetFreshness {
+  /** The daily P&L series; the widget accumulates it. */
+  days: DayResult[]
+  /** M, XL: for the whole series, so not shown for a range that cuts it. */
+  fees?: Numeric
+  /** XL: for the whole series, so not shown for a range that cuts it. Falls back to the sum of `days[].trades`. */
+  trades?: number
+}
+
+/** <ts-equity-curve>, sizes Wide · M · XL. XL's range buttons fire `ts-action` with action 'range'. */
+export declare class TsEquityCurve extends TsWidget<EquityCurveData> {
+  /** Reflects the `range` attribute; an unknown value reads as 'All'. */
+  range: EquityRange
+}
+
+export interface SessionClockData {
+  calendar: Calendar
+  /** Session ids, one lane each on Banner. S shows the first. */
+  sessions: string[]
+  /** Banner: candle-close ticks. Only the first two are drawn. */
+  timeframes?: number[]
+}
+
+/** <ts-session-clock>, sizes S · Banner. Ticks by itself every second; set `clock` to freeze it. */
+export declare class TsSessionClock extends TsWidget<SessionClockData> {}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ts-card': TsCard
+    'ts-metric': TsMetric
+    'ts-chart': TsChart
+    'ts-today-pnl': TsTodayPnl
+    'ts-equity-curve': TsEquityCurve
+    'ts-session-clock': TsSessionClock
+  }
+}