@trdrs/quickcharts 2.2.0 → 2.3.0

package/dist/{format-ConXazzy.d.ts → symbology-D3SLclrU.d.ts}

@@ -102,37 +102,4 @@ declare function parseTickBands(variableTickSize: string): TickBand[];
  *  so a spread writes both sides in one column. */
 declare function tickBandFor(bands: readonly TickBand[], price: number): TickBand | null;
 
-/** How a formatted price is punctuated. A price localizes the decimal sign only, so
- *  `groupSign` defaults to '' (no thousands separator) and a host that wants grouping asks for it
- *  explicitly. */
-interface NumericPunctuation {
-    /** What separates the whole part from the decimals. Default '.', or the locale's sign when a
-     *  `locale` is given. */
-    decimalSign?: string;
-    /** What separates thousands in the whole part. Default '': a price is written ungrouped, because
-     *  a grouped price is harder to compare against the axis beside it. */
-    groupSign?: string;
-}
-interface PriceFormatterOptions {
-    /** A BCP 47 tag used ONCE, at construction, to derive the decimal sign. Anything explicit in
-     *  `numericPunctuation` wins over it. */
-    locale?: string;
-    numericPunctuation?: NumericPunctuation;
-}
-/** A resolved formatter for one symbol. `format` and `parse` are exact inverses over every price
- *  that lands on the symbol's own grid. */
-interface PriceFormatter {
-    /** The price as the symbol writes it. */
-    format(price: number): string;
-    /** The number a viewer typed, or null when the text is not a price in this symbol's format. */
-    parse(text: string): number | null;
-    /** How many digits `format` writes after the decimal sign. 0 for a fractional format, which
-     *  writes none; the widest band's width for a variable-tick format, so a column sized from it
-     *  never has to reflow. */
-    precision(): number;
-}
-/** Build the formatter for one symbol's price format. The result is stateless and reusable; a host
- *  resolves a symbol once and keeps its formatter for as long as the symbol is on screen. */
-declare function createPriceFormatter(format: PriceFormat, options?: PriceFormatterOptions): PriceFormatter;
-
-export { type DataStatus as D, type NumericPunctuation as N, type PriceFormatter as P, type SymbolInfo as S, type TickBand as T, type PriceFormat as a, type PriceFormatterOptions as b, type Subsession as c, type SubsessionId as d, createPriceFormatter as e, parseTickBands as p, tickBandFor as t };
+export { type DataStatus as D, type PriceFormat as P, type SymbolInfo as S, type TickBand as T, type Subsession as a, type SubsessionId as b, parseTickBands as p, tickBandFor as t };

package/dist/symbols-BL1fD4CS.d.ts

@@ -0,0 +1,222 @@
+import { S as SymbolInfo } from './symbology-D3SLclrU.js';
+
+/** The theme roles a mark may wear. A host names a meaning and the mode resolves the color, so a
+ *  mark stays readable when the viewer switches to light. */
+type MarkColorRole = 'neutral' | 'up' | 'down' | 'info' | 'warning' | 'positive' | 'negative';
+/** Where a bar mark sits relative to its bar. */
+type MarkPlacement = 'above' | 'below';
+/** The glyph a bar mark draws. */
+type MarkShape = 'circle' | 'square' | 'arrowUp' | 'arrowDown';
+/** One mark on a bar. */
+interface BarMark {
+    /** Stable within one symbol and window, so a refetch replaces rather than duplicates. */
+    id: string;
+    /** Epoch SECONDS at the bar's bucket open, the same clock every bar uses. */
+    time: number;
+    color: MarkColorRole;
+    /** The letter or two the glyph carries. */
+    text?: string;
+    /** The longer words a host would show beside the mark. Carried, never drawn by the chart. */
+    label?: string;
+    shape?: MarkShape;
+    placement?: MarkPlacement;
+}
+/** One mark under the time scale. */
+interface TimescaleMark {
+    id: string;
+    /** Epoch SECONDS. */
+    time: number;
+    color: MarkColorRole;
+    label?: string;
+}
+
+/** One OHLCV bar on the wire: `t` = epoch SECONDS at bucket open (never milliseconds, never an
+ *  update's wall time), strictly ascending within any batch, one bar per timestamp. */
+interface FeedBar {
+    t: number;
+    o: number;
+    h: number;
+    l: number;
+    c: number;
+    v: number;
+}
+/** A symbol-search result row. `exchange` names the venue the market lists on. `dataSource` names
+ *  where the market's data comes from, and a row names one only when that source publishes the
+ *  symbol's data. The row's source cell shows the venue, or the data source for a row with none. */
+interface SymbolRow {
+    symbol: string;
+    name: string;
+    exchange: string;
+    type: string;
+    dataSource?: string | null;
+    /** What the market is priced in, when the feed knows it here. A PAIR market writes itself as
+     *  `BASE / QUOTE` wherever it is named, and a ticker alone cannot say what the quote is; a row
+     *  without it keeps the name the feed sent instead. `resolve()` states the same fact for the
+     *  charted symbol, so a row and the legend that follows it agree. */
+    currencyCode?: string;
+}
+interface SearchPage {
+    hits: SymbolRow[];
+    /** Exact: another page exists at offset + hits.length (never a guess at a page boundary). */
+    hasMore: boolean;
+}
+interface HistoryPage {
+    bars: FeedBar[];
+    /** True when a countBack ask found NOTHING — the "no more history, stop scrolling back" signal.
+     *  Plain from/to asks never set it (an empty window can be a mid-history gap). */
+    noData: boolean;
+    /** OPTIONAL gap hint on an EMPTY page that is not the end of history: the epoch-seconds time of
+     *  the closest bar older than the asked window (a market holiday between `to` and the data).
+     *  A consumer may retry ONCE with `to = nextTime` to jump the gap instead of dead-ending —
+     *  {@link olderPageVerdict} is that rule. Feeds without the concept simply never set it. */
+    nextTime?: number;
+}
+type OlderPageVerdict = {
+    kind: 'bars';
+} | {
+    kind: 'hop';
+    to: number;
+} | {
+    kind: 'end';
+} | {
+    kind: 'stop';
+};
+/** The one scroll-back rule for an older-history page, shared by every paging consumer so the gap
+ *  semantics can't drift between them:
+ *  - `bars` — the page has data; prepend it (bars are never discarded, whatever flags ride along).
+ *  - `hop` — empty but `nextTime` points strictly older and this ask wasn't already a hop: re-ask
+ *    once anchored there (the session-gap answer). One hop per gap keeps a lying feed bounded —
+ *    an honest hint names a real bar, so the hop can't come back empty.
+ *  - `end` — empty, `noData`, and no hint: feed inception, the one verdict that seals scroll-back.
+ *  - `stop` — every other empty page (a transient, or an unusable hint): end this flight WITHOUT
+ *    sealing; the next gesture asks again. */
+declare function olderPageVerdict(page: HistoryPage, askedTo: number, alreadyHopped: boolean): OlderPageVerdict;
+/** Push events from a live bar subscription. A `snapshot` REPLACES the recent window (delivered on
+ *  connect and on every transport reconnect — the feed's self-healing re-sync); a `bar` mutates the
+ *  last bar or appends the next one (bucket-open time). */
+type BarsEvent = {
+    kind: 'snapshot';
+    bars: FeedBar[];
+} | {
+    kind: 'bar';
+    bar: FeedBar;
+};
+interface SubscribeHandlers {
+    onBars(e: BarsEvent): void;
+    /** Feed status codes: 'live' | 'no-data' | server codes ('not_entitled', 'feed_down', …). */
+    onStatus?(status: string): void;
+}
+/** Thrown by `history` when the backend has NO feed configured for the symbol — a TERMINAL state
+ *  (the chart shows "market data unavailable" and closes the live subscription), unlike a transient
+ *  fetch failure which is retried. */
+declare class FeedUnavailableError extends Error {
+    /** The server's typed refusal (e.g. not_entitled / feed_down),
+     *  when it sent one — lets the host name the actual cause instead of a generic "unavailable". */
+    readonly code: string | null;
+    constructor(message?: string, 
+    /** The server's typed refusal (e.g. not_entitled / feed_down),
+     *  when it sent one — lets the host name the actual cause instead of a generic "unavailable". */
+    code?: string | null);
+}
+/** One class in a feed's catalog that holds narrower classes: a `spot` class over its `usdc` and
+ *  `usdt` quotes, say. `id` is the token the feed is searched with, as a plain string entry is, and
+ *  `children` are the narrower classes, as tokens or nodes of their own. The search renders two
+ *  levels, a top-level class and its children: a child's own `children` are not offered, and the
+ *  child narrows by its `id` alone. */
+interface SearchClassNode {
+    readonly id: string;
+    readonly children?: readonly (string | SearchClassNode)[];
+}
+/** What a feed's `search` is asked with. `cls` and `classes` say which classes to narrow to; both
+ *  absent is every class. */
+interface DatafeedSearchOptions {
+    /** One class to narrow to. When the viewer may select several classes it is set only while
+     *  exactly one is selected, so a feed that reads `cls` alone still narrows a single chip. */
+    cls?: string;
+    /** Every class to narrow to, sent only when the search lets the viewer select several classes at
+     *  once: a row matches when it is in any of them. A feed may ignore it and read `cls` alone. */
+    classes?: readonly string[];
+    limit?: number;
+    offset?: number;
+}
+/** A feed's coarse, feed-LEVEL capability declaration. Everything optional and the method itself
+ *  optional: an ABSENT declaration means unconstrained, and a feed must only
+ *  declare what is true — a finite `resolutions` list from a feed that serves any timeframe would
+ *  be a lie the chart then enforces. Symbol-level truth (price format, resolutions, session) stays
+ *  on {@link SymbolInfo}. */
+interface DatafeedConfig {
+    /** The wire timeframe tokens this feed can serve ('1m', '4h', '1d', …). Absent = any. */
+    resolutions?: readonly string[];
+    /** Asset-class tokens the catalog carries, in the order the search offers them. An entry is a
+     *  token, or a {@link SearchClassNode} whose children the search offers beneath it once it is
+     *  selected. Absent = unspecified. */
+    classes?: readonly (string | SearchClassNode)[];
+}
+/** The datafeed a chart consumes. Implementations must follow the bar rules on {@link FeedBar} and
+ *  {@link BarsEvent}; everything else (transport, caching, auth) is the implementation's business. */
+interface ChartDatafeed {
+    /** OPTIONAL capability negotiation, read once at mount: the widget constrains itself to what the
+     *  feed declares (e.g. its initial timeframe must be servable). Omit it entirely when the feed
+     *  has no fixed capability set. */
+    config?(): Promise<DatafeedConfig>;
+    /** Server-side symbol search, paged. `cls` narrows to one asset class ('' / absent = all), and
+     *  `classes`, when present, to any of several (see {@link DatafeedSearchOptions}). */
+    search(q: string, opts?: DatafeedSearchOptions): Promise<SearchPage>;
+    /** Resolve one symbol's metadata; null when the symbol is unknown to the feed's catalogs. */
+    resolve(symbol: string): Promise<SymbolInfo | null>;
+    /** Historical sealed bars: a [from,to] window (epoch seconds, INCLUSIVE of both ends — the chart
+     *  pages with `to = oldest − 1` and never re-requests a bar it holds), or `countBack` = the LAST
+     *  N bars at/before `to` (outranks `from`; the count is an obligation — reach across closures).
+     *  No range = the feed's default recent window. Throws {@link FeedUnavailableError} when no feed
+     *  serves the symbol. */
+    history(symbol: string, tf: string, range?: {
+        from?: number;
+        to?: number;
+        countBack?: number;
+    }): Promise<HistoryPage>;
+    /** Live bar push for one (symbol, timeframe). Returns the unsubscribe. The transport owns
+     *  reconnection and re-syncs by emitting a fresh `snapshot`. */
+    subscribeBars(symbol: string, tf: string, handlers: SubscribeHandlers): () => void;
+    /** Server clock (epoch seconds) — countdown skew correction. Optional: a feed without one leaves
+     *  the chart on the client clock. */
+    serverTime?(): Promise<number>;
+    /** OPTIONAL depth of history for a symbol: the epoch seconds of its earliest available bar, or
+     *  null when the feed does not know. The range presets read it (a listing from last year offers
+     *  no five-year range); the chart never probes for it. Omit it entirely when the feed cannot
+     *  say, and every preset is offered. */
+    earliestBar?(symbol: string): Promise<number | null>;
+    /** OPTIONAL neutral bar marks over a window (epoch seconds, inclusive of both ends). A mark is a
+     *  note about a moment: its color is a theme role, its words are the host's, and the chart
+     *  draws it as given. Omit it entirely when the feed serves none. */
+    marks?(symbol: string, from: number, to: number, resolution: string): Promise<readonly BarMark[]>;
+    /** OPTIONAL neutral time-scale marks over the same window. */
+    timescaleMarks?(symbol: string, from: number, to: number, resolution: string): Promise<readonly TimescaleMark[]>;
+}
+
+/** The ticker inside a feed symbol. Only a well-formed `VENUE:TICKER` sheds its prefix; a spread
+ *  expression, or anything else the pattern does not admit, is its own label and passes through. */
+declare function bareTicker(symbol: string): string;
+/** The three ways one market is written, from one rule. */
+interface SymbolNames {
+    /** The compact mark a label wears at a glance: a pair closed up (`BTCUSDC`, `EURUSD`), otherwise
+     *  the bare ticker (`ES1!`, `AAPL`). A spread expression is its own mark, operators and all. */
+    mark: string;
+    /** The title a reading wears: a pair spaced (`BTC / USDC`), otherwise the feed's short name where
+     *  it stated one apart from the description, otherwise the bare ticker. */
+    title: string;
+    /** The description beside a mark: a pair spaced, otherwise the feed's long description, otherwise
+     *  the bare ticker, so a market never repeats its own mark for want of a name. */
+    description: string;
+}
+/** How a market is named, from a resolved `SymbolInfo`, a search row, or the feed symbol alone
+ *  before either has landed.
+ *
+ *  A pair market reads as `BTC / USDC` or `EUR / USD`, both sides in the codes the market itself
+ *  trades in, never a spelled-out currency name. The quote comes from `currencyCode`, and a ticker
+ *  written as a slash pair (`BTC/USD`) needs no currency to say so. Before a symbol resolves there
+ *  is no pair to write, so the bare ticker stands on its own rather than guessing at a quote. A
+ *  market that is not a pair keeps the feed's own words: the short name as its title, the long
+ *  description beside its mark. */
+declare function symbolNames(symbol: SymbolInfo | SymbolRow | string): SymbolNames;
+
+export { type BarMark as B, type ChartDatafeed as C, type DatafeedConfig as D, type FeedBar as F, type HistoryPage as H, type MarkColorRole as M, type OlderPageVerdict as O, type SymbolRow as S, type TimescaleMark as T, type SearchClassNode as a, type BarsEvent as b, type DatafeedSearchOptions as c, FeedUnavailableError as d, type MarkPlacement as e, type MarkShape as f, type SearchPage as g, type SubscribeHandlers as h, type SymbolNames as i, bareTicker as j, olderPageVerdict as o, symbolNames as s };

package/dist/symbols.d.ts

@@ -0,0 +1,2 @@
+export { i as SymbolNames, j as bareTicker, s as symbolNames } from './symbols-BL1fD4CS.js';
+import './symbology-D3SLclrU.js';

package/dist/symbols.js

@@ -0,0 +1,9 @@
+import {
+  bareTicker,
+  symbolNames
+} from "./chunk-GFQQSY47.js";
+export {
+  bareTicker,
+  symbolNames
+};
+//# sourceMappingURL=symbols.js.map

package/dist/symbols.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trdrs/quickcharts",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Quick Charts: a datafeed-driven charting library with drawings, indicators, layouts and replay over host-supplied data and storage ports.",
   "keywords": [
     "charts",
@@ -49,6 +49,10 @@
       "types": "./dist/glyphs.d.ts",
       "import": "./dist/glyphs.js"
     },
+    "./symbols": {
+      "types": "./dist/symbols.d.ts",
+      "import": "./dist/symbols.js"
+    },
     "./styles.css": "./dist/quickcharts.css"
   },
   "files": [