@trdrs/quickcharts 4.1.0 → 5.0.0

package/CHANGELOG.md

@@ -2,6 +2,96 @@
 
 ## Unreleased
 
+## 5.0.0
+
+The chart settings, one typed tree saved with the chart in place of the appearance overrides, with a dialog of five pages a host can add its own to, the price labels and scale controls they drive, the plus beside the crosshair's price and its price menu, panes that move and maximize, time-scale marks with icons and lines, the optional prices port, and extension seams for legend rows, captures and settings pages.
+
+The chart settings: one typed tree, `ChartSettings`, of every property a viewer tunes on a chart, resolved as the theme's factory values, the host's `settings` option and the viewer's own leaves, and saved with the chart as the viewer's leaves alone. 5.0 replaces the appearance overrides with it, so a host upgrades as the guide below says.
+
+`chart.settings()` answers the effective tree, `chart.applySettings(partial)` layers a partial over the viewer's leaves and `chart.resetSettings()` drops them and returns the price scale to normal; the commands are `chart.settings.apply` with `{ settings }` and `chart.settings.reset`. A leaf the tree does not have, or a value its leaf cannot hold, is ignored. `chartSettingsDefaults(theme)`, `layerChartSettings`, `readPartialChartSettings`, `CHART_SETTINGS_SECTIONS`, `CHART_DATE_FORMATS` and `CHART_FACTORY_COLORS` export the factory values, the ladder and the reading every stored partial goes through.
+
+Every leaf with something behind it draws. The candle, hollow and bars families set the body, borders and wick, each on its own switch and in its own pair, color each bar by the previous bar's close, and draw thin bars and the open tick (`hlcBars`). The line and step line take a solid color or a vertical gradient, stroked from the top color at the highest price on screen to the bottom color at the lowest, the area its line and fills, and the baseline its lines, fills, a width for each half and its base level as a percentage of the pane. The symbol's precision writes every price through the chart's one formatter, so the axis, the legend, the countdown and the drawings agree. The status line shows or hides the legend's mark, its title (the name, the symbol, or both), the bar's values, its change and its volume, and the indicator rows' titles, inputs and values, over a backdrop of the chart's background at an opacity. The price labels keep labels apart, show the countdown, the symbol's last value, its dotted line in its own color and width, and its name, and write each indicator's value and name. The time scale writes the crosshair's date in one of nineteen formats (`chartDateSample` writes a format's sample, `formatChartDate` a date), with the weekday before it, on a clock of 24 hours or of 12 that the axis times follow too. The canvas sets the background, solid or a vertical gradient, each grid's switch, color and stroke, the crosshair's color, stroke and width, the watermark's ticker, interval and description in its own ink (the replay mark is its fourth part), the scales' text color and size and their lines, when the navigation buttons show, and the margins, the right one in bars. The events draw a line at each trading day's start in its own stroke (`sessionBreakTimes` finds them).
+
+The factory look is the reference dialog's: candles, borders and wicks in the series pair, a gradient line from `#d500f9` to `#00bce5`, an area in `#2962ff` over a fill at 28%, grids dotted at 20% of `#f2f2f2` in dark and `#2e2e2e` in light, the crosshair `#9c9c9c` dashed at 1px with its price and time labels in `#3d3d3d` in dark and `#0f0f0f` in light, in white, scale text `#b8b8b8` in dark and `#0f0f0f` in light at 12px, scale lines at no opacity, margins of 10% and 8% and 10 bars, the countdown on, and regular trading hours. The palettes' `scale.grid`, `scale.text`, `scale.crosshair`, `scale.crosshairLabelBackground`, `scale.crosshairLabelText`, `scale.border` and the three session shading roles carry those values, `text.fontSizeAxis` sizes the legend's reading alone, and the theme gains `canvas.watermark`, `control.tipMark`, `control.tipMarkHover`, `overlay.tooltip` and `overlay.tooltipInk`. `CanvasTheme` gains `watermark`, and an extension's `theme()` answers the canvas under the settings in effect.
+
+The catalog gains `command.settingsApply`, `command.settingsReset`, `history.changeSettings`, `legend.volume` and `timezone.quarter` in every built-in language.
+
+The chart settings dialog shows the active chart's settings on five pages, Symbol, Status line, Scales and lines, Canvas and Events, on a 750px card that stands as tall as the page it shows up to the viewport less 40px. The pages sit on a rail of 40px tabs, each with its own icon, beside a page laid out as the drawing settings dialogs lay theirs: a label column as wide as the widest label and 20px clear of the controls, 50px rows around 34px controls, 32px headings in capitals, checkbox rows with a hint or a tip, sub-rows 26px in that stand back while their parent is off, and the colors, lists, numbers and sliders the drawing dialogs use. The Symbol page carries the rows of the chart's style, its trading hours on an intraday chart of a symbol with extended hours, its precision and its timezone; the Status line, Scales and lines, Canvas and Events pages carry every leaf of their sections, a row that depends on an indicator or an intraday chart showing only there. Every change previews on the chart; Cancel, the close and Escape put back the viewer's settings, the price-scale mode and the timezone, and Ok keeps them. The dialog stands over a chart that answers the pointer while it is up, opens centred, keeps its top edge from page to page, and moves with its header.
+
+`ChartExtensionContext.contributeLegendRow({ element, rank })` places an extension's own element as a row of the pane's legend, under the symbol's reading and above the indicator rows, rows of a lower `rank` first; the row wears the status line's backdrop, takes the pointer, stands while the indicator rows collapse, and leaves when the returned function or detach takes it out. `ChartExtensionLegendRow` is its type.
+
+`ChartExtensionContext.contributeCapture({ before, paint })` lets an extension take part in every image the chart produces of itself, by `image.capture()`, `copy()` and `download()` alike: each `before` runs synchronously before the renderer draws every pending change into the image and may answer a restore, run once the image is taken; each `paint` paints over the bitmap's 2D context from the chart element's top left, in a frame of the element's CSS size and the image's pixels per CSS pixel; and a throw in either, or in a restore, is contained without costing the image or another restore. The returned function or detach withdraws it. `ChartExtensionCapture` and `ChartExtensionCaptureFrame` are its types.
+
+`ChartExtensionContext.contributeSettings` adds a page of an extension's own, after the page it names, or rows inside one of the chart's pages, before the first of the rows it names; a page's `after` names one of the chart's pages or another contributed page, or a list of them of which the first the dialog holds wins, read once every contribution is known, so a page follows the contributed page it names whichever attached first; pages that name the same page stand after it in the order their extensions attach, and one extension's pages in the order it contributes them, and a page that names no page the dialog holds stands last; the extension builds them with the form the chart builds its own with (`ChartSettingsForm`, `ChartSettingsControls`), and the dialog calls its `open`, `cancel`, `commit` and `applyDefaults` with the session. `chart.settings.open` opens the dialog on the page `{ page }` names, whether or not the top bar shows its gear. The Template menu applies the defaults, saves the viewer's settings under a name and lists the saved ones, in `saveLoad.templates('chart')`: `TemplateKind` takes `'chart'`, and the REST wire, at version 3, serves the `chart` template collection. The icon catalog gains `settingsSymbol`, `settingsStatusLine`, `settingsScales`, `settingsCanvas`, `settingsEvents`, `tip`, `volume` and `volumeMuted`.
+
+The theme mode leaves the dialog: `ui.topBar.settings.theme` stays accepted and changes nothing. The catalog drops the keys of the dialog's earlier pages, `settings.sectionAppearance`, `settings.upCandles`, `settings.downCandles`, `settings.upBorders`, `settings.downBorders`, `settings.upWicks`, `settings.downWicks`, `settings.sectionDisplay`, `settings.gridLines`, `settings.sessionShading` and `settings.sectionTheme`, and a dictionary of your own leaves them out.
+
+The theme gains `text.caption`, the ink of a dialog's section headings and of the hint lines under its settings.
+
+The line, step line, area and baseline draw each bar from their own `priceSource`: its open, high, low or close, or the average `hl2`, `hlc3`, `ohlc4` or `hlcc4`, and the last-value label and the morph from a bar style follow the same value.
+
+`ChartDatafeed.subscribePrices(symbol, { onPrices })` is an optional port for the prices one symbol stands at, `SymbolPrices`: its `bid`, `ask`, `last`, and `previousClose` or the `change` since it, any of which a delivery may leave out to keep its last value. The chart subscribes only while a setting draws them, and `Capabilities.prices` says whether the feed serves them.
+
+The status line's `lastDayChange` writes the latest price's change since the previous session's close and its percentage after the bar's volume, in green or red by its direction. The previous close is the feed's when its prices state one, and otherwise the last regular-hours close of the trading day before the newest bar's (on a daily or longer chart, the bar before the newest).
+
+The price labels mark the previous session's close on an intraday chart, the high and low of the bars in view, and the bid and ask from the feed's prices: each a value box on the price scale in its own color with white text, a tag on the plot side ("High", "Low", "Bid", "Ask"), and a 1px dotted line across the plot, the value and the line each on their own switch, stacked with the last value's label while labels are kept apart. The high and low wear `#808080` lines and `#142e61` labels while `highLowColor` is null, and `CHART_FACTORY_COLORS` gains `highLowLine`, `highLowLabel` and `scaleLabelText`. The catalog gains `chrome.scaleHigh`, `chrome.scaleLow`, `chrome.scaleBid` and `chrome.scaleAsk`.
+
+The last value's "price and percentage" mode (`symbolValueMode: 'priceAndPercent'`) writes the change since the previous session's close under the price, to two decimals with its sign, and the countdown under that. The label is drawn as the renderer draws its own, one pixel inside the scale, square on the plot side and rounded on the other, 17px tall at 12px with 14px more for each line, in white with the countdown at 75%.
+
+On an intraday chart of regular hours, a symbol whose newest bar stands in a pre-market, post-market or overnight stretch marks that bar's close on the price scale in the stretch's label color (`preMarketLabelColor`, `postMarketLabelColor`, `nightLabelColor`), the value and the dotted line on the `extendedHoursValue` and `extendedHoursLine` switches.
+
+The scales placement (`priceScale.placement`) stands the main series' price scale on the left under `left`, carrying its mode, its framing and every series of the main pane that shares it, and a comparison on a scale of its own moves to the right; `right` and `auto` keep the main scale on the right and such a comparison on the left. A series added without naming a scale takes the main side, and the last value's drawn label mirrors on a left scale.
+
+The scale mode buttons (`priceScale.scaleModeButtons`) stand at the foot of the main price scale while the pointer is over it, always, or never: two 20x22 buttons 4px apart, "A" switching the scale between framing itself and holding where it was dragged and "L" between a regular and a logarithmic scale, filled while on in the emphasis fill a checked box wears (`control.on`) with the letter in `text.inverse`, and outlined while off. The catalog gains `chrome.scaleModes`, `chrome.autoScale`, `chrome.autoScaleMark`, `chrome.logScale` and `chrome.logScaleMark`.
+
+The currency and unit box (`priceScale.currencyAndUnit`) names what the symbol's prices are in, its `currencyCode` and `unitId`, in a box at least 64x26 four pixels inside the top of the main price scale, on the chart's background in a 1px border with a radius of 4, while the pointer is over the scale, always, or never; a symbol that states neither shows none. The catalog gains `chrome.currencyAndUnit`.
+
+The price-to-bar ratio lock (`priceScale.lockPriceToBarRatio`) holds the price one bar's width spans on a regular scale: engaging it with no `priceToBarRatio` takes the ratio on screen, to seven decimals, into the viewer's leaf, the scale stops framing itself, and every zoom of the time scale rescales the price axis by the same factor about its middle; a ratio of the viewer's own holds at once.
+
+Keeping the left edge (`timeScale.keepLeftEdge`) stands a new timeframe's bars from the moment the view's left edge stood at, with as many bar slots in view, asking the feed once for older bars when that moment lies before the first page, rather than fitting the loaded history. A range preset that changes the timeframe frames its own span as before.
+
+The plus button (`priceLabels.plusButton`) is joined to the crosshair's price label while the crosshair is on the main pane's plot. The renderer paints it in the same pass as the label, so the two move as one: a box 20px wide at 12px and exactly as tall as the label, a pixel of the chart short of the scale's edge where the label begins, square where the two face each other and rounded 2px at their outer corners like one pill split by a hairline, in the label's fill (a fifth of the way toward the label's ink under the pointer) with a ringed plus in that ink, mirrored beside a left scale. The pointer wears the pointer cursor over it, through the renderer's own hit test. Its press opens the price menu under it, as wide as its widest row, which holds the actions on that price alone: the `level` rows the extensions contribute, each extension's rows together in the order they attach with a rule between, then "Draw horizontal line at" the price; the right-click menu is unchanged. The chart stays live under the price menu, so the crosshair, its label and the plus stay while the pointer is on the chart, and a press anywhere off the menu closes it without reaching what is under it. A focusable button over the painted plus carries its name and opens the menu from the keyboard. The catalog gains `chrome.priceLevelMenu` and `menu.drawHorizontalLine`.
+
+`chart.drawings.placeHorizontalLine` places a horizontal line at the price it is given, in the tool's default look and selected. It asks what arming the horizontal line asks, so a tool your list leaves out or your policy refuses places none, and it places nothing while lock all holds. Run with no price it places the line at the crosshair's price, on the symbol's own grid, while the crosshair stands on the main pane's plot, and is unavailable anywhere else; its default shortcut, `Alt+KeyH`, runs it so, and the price menu's row prints the shortcut ("Alt + H"). The catalog gains `command.drawingPlaceHorizontalLine`.
+
+The pane buttons (`canvas.paneButtons`) stand at each pane's top right, 4px below its top and 4px in from the plot's edge, for the pane under the pointer, for every pane always, or never: 24px rounded squares 4px apart that move the pane up or down, delete it and what is in it, collapse it or open it, and maximize or restore it. They run the pane operations the legend's rows run, through one memory, and the move and remove verbs, so the policy that refuses a move or a remove leaves its button out. Every pane but the top one moves up and every pane but the bottom one moves down; the main pane moves too, and otherwise carries maximize alone while another pane stands, collapsing every other open pane and giving back exactly those. The icons `paneCollapse`, `paneRestore` and `paneMaximize` gain the buttons' 15px drawings, and the catalog gains `chrome.paneButtons` and `chrome.deletePane`.
+
+The panes move: `chart.panes.moveUp` and `chart.panes.moveDown` swap the pane at the index they are given (the top pane is 0) with its neighbour above or below, the main pane among them, through the renderer's own reordering, so each pane keeps its series, its height and what is drawn on it. Asked with an index, each is unavailable at its end: the top pane cannot move up and the bottom one cannot move down. A pane-placed indicator's legend row moves its pane too. The main pane carries its legend, the overlays, a comparison on its scale or the second one, a new style's series, the drawings, the marks, the watermark and the price scale's controls wherever it stands, and `chart.plotArea()` follows it. Chart content carries `panes`, the panes top to bottom by what stands in each (`main`, `indicator:<id>`, `compare:<symbol>`), so a load stands them in the saved order, and a hidden indicator's pane comes back in its place; content that states no order keeps its panes in the order it stores them: the main pane, the indicators' and then the comparisons'. A move is a step of the history, `paneMove` (`HistoryChange`). The icon catalog gains `paneMoveUp` and `paneMoveDown`, drawn at 18px and 15px, and the catalog gains `legend.movePaneUp`, `legend.movePaneDown` and `history.changeMovePane`.
+
+`commands.available(id, arg)` answers for the argument a command would run with, and `CommandSpec.available(arg)` receives it: a command whose one id spans many subjects says which of them it can act on now, and asked with no argument, whether any. An argument the spec refuses is unavailable. `seriesTargetOf` takes the main pane's index as its fourth argument, `CompareDeps.mainPane` and the `mainPane` option of `attachIndicators` name the pane the main series stands in, and `PaneState.main` names it to `planPaneOp`; each is the first pane when absent.
+
+A mark's color is a theme role or a `MarkColorPair`, `{ light, dark }`, one CSS color for each mode, of which the chart wears the one for the mode in effect. A single color for both modes is not a `MarkColor`, and a pair with a side the chart cannot paint draws in the `neutral` role.
+
+A time-scale mark that names an `icon` draws as a 21px ring in its color, its foot just above the time scale and the chart's background inside, around that glyph, and a mark without one stays a small dot. The icon catalog gains the glyphs a mark may name, each named for its shape: `mark.bolt`, `mark.flag`, `mark.star`, `mark.clock` and `mark.exclamation`, and a host's `icons` drawing for one stands in the ring. `line: { style }` draws a 1px `solid`, `dashed` (5px drawn, 6px clear) or `dotted` line in the mark's color through the whole pane at its time, under the bars. `MarkIconId`, `MarkLine` and `MarkLineStyle` are exported.
+
+A time-scale mark's `line: { style, color, width }` runs through the whole pane at its time under the bars, in its own color (a theme role or a light and dark pair) or its mark's, 1 to 4 CSS pixels wide.
+
+Hovering a time-scale mark, or pressing it with a finger or a pen, runs a dashed line in its color from the top of the pane down to it and tints its ring, and a mark with a `label` shows it in a tooltip above it on the theme's `overlay.tooltip` fill in `overlay.tooltipInk`. A mark without a label shows the line alone.
+
+A time-scale mark at a time after the last bar stands in the empty space after it, at the slot its time falls in, counted in the timeframe's bar interval on from the last bar, and a mark whose time falls between bars stands on the next bar. The chart asks `timescaleMarks` for the loaded window run on to the end of the view and as many bar intervals again as the view spans, and asks again once the view rests past what it asked for. Bar replay draws none after the last bar it shows.
+
+`chart.refreshMarks()`, `ChartExtensionContext.refreshMarks()` and the `chart.marks.refresh` command ask the datafeed for both mark families again at once and draw the answer, so a host's own setting shows its change while its control is still open. The catalog gains `command.marksRefresh`.
+
+### Upgrading to 5.0
+
+5.0 replaces the appearance overrides with the chart settings. Change each where your code names it:
+
+- A dictionary of your own (`ChartCustomLocale`, `ChartDictionary`) carries every key of 5.0.0. The keys the catalog gained within 4.x are required in it from 5.0.0: `command.settingsApply`, `command.settingsOpen`, `command.settingsReset`, `drawing.distance`, `drawing.drawingMenu`, `drawing.hintRemove`, `history.changeSettings`, `legend.volume`, `settings.allHoursBackground`, `settings.alwaysInvisible`, `settings.alwaysVisible`, `settings.ask`, `settings.barChangeValues`, `settings.baseLevel`, `settings.bid`, `settings.bidAndAsk`, `settings.body`, `settings.borders`, `settings.bottomColorOf`, `settings.bottomLine`, `settings.chartValues`, `settings.colorGradient`, `settings.colorOnPreviousClose`, `settings.colorSolid`, `settings.countdown`, `settings.crosshair`, `settings.currencyAndUnit`, `settings.dateFormat`, `settings.dayOfWeek`, `settings.deleteTemplateBody`, `settings.downColor`, `settings.downColorOf`, `settings.extendedHoursBackground`, `settings.extendedHoursLabels`, `settings.fill`, `settings.fillBottomArea`, `settings.fillTopArea`, `settings.headingArea`, `settings.headingBars`, `settings.headingBaseline`, `settings.headingButtons`, `settings.headingCandles`, `settings.headingChartStyles`, `settings.headingDataModification`, `settings.headingHollowCandles`, `settings.headingIndicators`, `settings.headingInstrument`, `settings.headingLine`, `settings.headingMargins`, `settings.headingPriceLabels`, `settings.headingScales`, `settings.headingStepLine`, `settings.headingTimeScale`, `settings.hidden`, `settings.highAndLow`, `settings.hlcBars`, `settings.horizontalGrid`, `settings.hours12`, `settings.hours24`, `settings.indicatorInputs`, `settings.indicatorTitles`, `settings.indicatorValues`, `settings.indicatorsAndFinancials`, `settings.keepLeftEdge`, `settings.labelLine`, `settings.labelName`, `settings.labelValue`, `settings.lastDayChangeValues`, `settings.lastValueMode`, `settings.learnMore`, `settings.lineRow`, `settings.lockPriceToBarRatio`, `settings.logo`, `settings.marginBottom`, `settings.marginRight`, `settings.marginTop`, `settings.navigationButtons`, `settings.night`, `settings.noOverlappingLabels`, `settings.pageCanvas`, `settings.pageEvents`, `settings.pageScales`, `settings.pageStatusLine`, `settings.pageSymbol`, `settings.paneButtons`, `settings.placementAuto`, `settings.placementLeft`, `settings.placementRight`, `settings.plusButton`, `settings.plusButtonTip`, `settings.postMarket`, `settings.preMarket`, `settings.precisionDecimals`, `settings.precisionInteger`, `settings.previousDayClose`, `settings.priceAndPercent`, `settings.priceSource`, `settings.saveTemplate`, `settings.scaleLines`, `settings.scaleModes`, `settings.scaleText`, `settings.scalesPlacement`, `settings.session`, `settings.sessionAllHours`, `settings.sessionBreaks`, `settings.sessionExtended`, `settings.sessionRegular`, `settings.sourceClose`, `settings.sourceHigh`, `settings.sourceHl2`, `settings.sourceHlc3`, `settings.sourceHlcc4`, `settings.sourceLow`, `settings.sourceOhlc4`, `settings.sourceOpen`, `settings.symbolLabel`, `settings.thinBars`, `settings.timeHoursFormat`, `settings.title`, `settings.titleName`, `settings.titleSymbol`, `settings.titleSymbolAndName`, `settings.topColorOf`, `settings.topLine`, `settings.unitBars`, `settings.unitPercent`, `settings.upColor`, `settings.upColorOf`, `settings.valueByScale`, `settings.verticalGrid`, `settings.visibleOnMouseOver`, `settings.volume`, `settings.watermark`, `settings.watermarkDescription`, `settings.watermarkInterval`, `settings.watermarkReplay`, `settings.watermarkTicker`, `settings.wick`, `timezone.quarter`.
+- `ChartOverrides`, `PartialOverrides`, `DEFAULT_OVERRIDES`, `mergeOverrides` and `layerOverrides` go: read `ChartSettings`, `PartialChartSettings`, `chartSettingsDefaults(theme)` and `layerChartSettings` in their place. `BRAND_UP` and `BRAND_DOWN` keep their names and values.
+- The `appearance` option is `settings`, a `PartialChartSettings`. The old leaves live here:
+  - `upColor` and `downColor`: `candles.upColor` and `candles.downColor`, with the same pair in `hollowCandles`, `bars` and the baseline's `topLineColor` and `bottomLineColor`;
+  - `borderUpColor`, `borderDownColor`, `wickUpColor` and `wickDownColor`: the same leaves in `candles`, with `candles.borders` and `candles.wick` switching them;
+  - `background`: `canvas.background`;
+  - `grid`: `canvas.verticalGrid` and `canvas.horizontalGrid`;
+  - `countdown`: `priceLabels.countdown`;
+  - `sessions`: `symbol.session`, `extended` or `allHours` to shade the stretches outside regular hours.
+- `chart.appearance()` is `chart.settings()`, and `chart.applyAppearance({ appearance })` is `chart.applySettings(partial)`, with `chart.resetSettings()` beside it.
+- The commands `chart.appearance.apply` with `{ appearance }` and `chart.appearance.reset` are `chart.settings.apply` with `{ settings }` and `chart.settings.reset`.
+- The catalog keys `command.appearanceApply`, `command.appearanceReset` and `history.changeAppearance` are `command.settingsApply`, `command.settingsReset` and `history.changeSettings`, and the history step `appearance` is `settings` (`HistoryChange`).
+- A chart opens on regular hours. Its subsession is its `symbol.session` setting, saved with the chart: `chart.subsession()` reads it and `chart.setSubsession()` writes it as the viewer's own. A choice an earlier release stored under `quickcharts.subsession.v1` seeds a chart once, as the host's value, and the chart writes that key no more.
+- Chart content is version 5 and carries `settings` and `panes`. A version-4 blob loads with its `appearance` record read into the settings as above and its panes in the order it stores them, so saved charts need nothing from you.
+- `CanvasTheme` holds `watermark`, so code that builds one itself adds it.
+
 ## 4.1.0
 
 Line tools painted as measured, with their words typed along them and their points marked on the axes, a menu of every drawing's own, the bar price sources, the bars pattern modes and the serial version exported from the drawings entry, color panels and the chart's words that keep their measure under a host page's global rules, and a dictionary of your own that may leave out the keys the catalog gains within the major. No public name changes.