gloomberb 0.20.2 → 0.20.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (362) hide show
  1. package/README.md +1 -1
  2. package/README.zh-CN.md +1 -1
  3. package/package.json +2 -1
  4. package/src/account/auth-form.tsx +13 -8
  5. package/src/account/upgrade-dialog.tsx +1 -1
  6. package/src/api-client/central-bank-rates.ts +5 -0
  7. package/src/api-client/data.ts +17 -4
  8. package/src/api-client/debt-maturities.ts +45 -2
  9. package/src/api-client/earnings.ts +4 -2
  10. package/src/api-client/errors.ts +21 -11
  11. package/src/api-client/index.ts +1 -0
  12. package/src/api-client/paths.ts +9 -1
  13. package/src/api-client/social-mentions.ts +47 -0
  14. package/src/api-client/types/econ.ts +4 -0
  15. package/src/app.tsx +11 -1
  16. package/src/cli/command-options.ts +2 -1
  17. package/src/cli/commands/market.ts +111 -29
  18. package/src/cli/commands/options-chain.ts +23 -6
  19. package/src/cli/commands/overview.ts +13 -5
  20. package/src/cli/commands/plugins.ts +49 -18
  21. package/src/cli/commands/search.ts +25 -6
  22. package/src/cli/commands/ticker.ts +4 -2
  23. package/src/cli/fx-quote-rate.ts +49 -1
  24. package/src/cli/glossary.ts +95 -15
  25. package/src/cli/history-rows.ts +9 -25
  26. package/src/cli/index.ts +6 -38
  27. package/src/cli/known-gaps.ts +3 -3
  28. package/src/cli/listing-arg.ts +78 -18
  29. package/src/cli/name-entries.ts +3 -2
  30. package/src/cli/not-a-ticker.ts +6 -2
  31. package/src/cli/pane-functions/capabilities.ts +12 -1
  32. package/src/cli/pane-functions/function-help.ts +23 -11
  33. package/src/cli/pane-functions/headless.ts +3 -1
  34. package/src/cli/pane-functions/index.ts +32 -4
  35. package/src/cli/pane-functions/market-session.ts +8 -3
  36. package/src/cli/pane-functions/resolver.ts +18 -11
  37. package/src/cli/pane-functions/screenshot-payload.ts +36 -6
  38. package/src/cli/pane-functions/screenshot-render.ts +4 -0
  39. package/src/cli/quote-answer.ts +10 -0
  40. package/src/cli/report-tables.ts +22 -2
  41. package/src/cli/result.ts +7 -3
  42. package/src/cli/spreadsheet-hint.ts +43 -0
  43. package/src/cli/symbol-list.ts +58 -4
  44. package/src/cli/symbol-rows.ts +49 -2
  45. package/src/cli/ticker-resolution.ts +98 -5
  46. package/src/cli/unknown-command.ts +88 -0
  47. package/src/components/command-bar/assist/model.ts +6 -1
  48. package/src/components/command-bar/commands/direct/index.ts +9 -1
  49. package/src/components/command-bar/commands/registry.ts +18 -0
  50. package/src/components/command-bar/pane-actions.ts +30 -13
  51. package/src/components/command-bar/panel/index.tsx +6 -3
  52. package/src/components/command-bar/panel/prompt-binding.ts +4 -0
  53. package/src/components/command-bar/panel/types.ts +3 -0
  54. package/src/components/command-bar/routes/header-market.ts +108 -0
  55. package/src/components/command-bar/routes/root/command-items.ts +5 -0
  56. package/src/components/command-bar/routes/root/provider-search.ts +190 -32
  57. package/src/components/command-bar/routes/root/results.ts +3 -0
  58. package/src/components/command-bar/routes/root/runtime.ts +28 -5
  59. package/src/components/command-bar/routes/ticker-search/results.ts +53 -6
  60. package/src/components/command-bar/routing/list-state.ts +38 -0
  61. package/src/components/command-bar/selection-hint.ts +28 -0
  62. package/src/components/command-bar/surface/index.tsx +41 -3
  63. package/src/components/command-bar/view-model.ts +15 -0
  64. package/src/components/command-bar/workflow/tickers.ts +3 -2
  65. package/src/components/company-logo.tsx +20 -2
  66. package/src/components/data-table/export.ts +13 -8
  67. package/src/components/feedback-dialog.tsx +2 -1
  68. package/src/components/form-modal/field-row.tsx +2 -1
  69. package/src/components/input-search-bar.tsx +2 -2
  70. package/src/components/layout/double-escape-close.ts +8 -5
  71. package/src/components/layout/header.tsx +75 -44
  72. package/src/components/layout/market-summary.ts +322 -116
  73. package/src/components/layout/pane/footer/index.tsx +26 -8
  74. package/src/components/layout/pane/footer/model.ts +46 -20
  75. package/src/components/layout/pane/header.tsx +3 -2
  76. package/src/components/layout/shell/chrome.ts +15 -15
  77. package/src/components/layout/status-bar.tsx +8 -7
  78. package/src/components/layout/status-widget-space.ts +8 -0
  79. package/src/components/markdown-editor.tsx +2 -2
  80. package/src/components/onboarding/account-step/form-panel.tsx +0 -3
  81. package/src/components/onboarding/onboarding-keyboard.ts +15 -6
  82. package/src/components/onboarding/onboarding-wizard.tsx +61 -11
  83. package/src/components/onboarding/portfolio-step/broker-fields-panel.tsx +0 -1
  84. package/src/components/onboarding/portfolio-step/positions-panel.tsx +0 -2
  85. package/src/components/price-sparkline/model.ts +26 -10
  86. package/src/components/ticker/list-table-view.tsx +29 -4
  87. package/src/components/ui/button.tsx +13 -2
  88. package/src/components/ui/column-grid.tsx +18 -9
  89. package/src/components/ui/data-table/index.tsx +1 -1
  90. package/src/components/ui/data-table/opentui/index.tsx +2 -1
  91. package/src/components/ui/data-table/types.ts +18 -0
  92. package/src/components/ui/delayed-mark.tsx +3 -2
  93. package/src/components/ui/field-grid.tsx +0 -2
  94. package/src/components/ui/fields.tsx +7 -4
  95. package/src/components/ui/inline-quick-add.tsx +2 -2
  96. package/src/components/ui/key-hint-words.ts +153 -0
  97. package/src/components/ui/key-hints.tsx +73 -0
  98. package/src/components/ui/menu.tsx +3 -1
  99. package/src/components/ui/message-composer.tsx +2 -2
  100. package/src/components/ui/shortcut-hint.tsx +28 -3
  101. package/src/components/ui/tabs.tsx +7 -0
  102. package/src/components/ui/text-prompt-dialog.tsx +2 -1
  103. package/src/core/state/app/command-bar-launch.ts +3 -0
  104. package/src/data/config/store/normalize.ts +6 -0
  105. package/src/docs/snapshot.json +120 -69
  106. package/src/i18n/es.ts +24 -1
  107. package/src/i18n/ja.ts +24 -1
  108. package/src/i18n/ko.ts +24 -1
  109. package/src/i18n/zh-cn.ts +24 -1
  110. package/src/i18n/zh-tw.ts +24 -1
  111. package/src/layout/pane-manager/gridlock.ts +11 -0
  112. package/src/market-data/bars-per-year.ts +27 -9
  113. package/src/market-data/coordinator/quotes.ts +22 -3
  114. package/src/market-data/futures-board.ts +80 -0
  115. package/src/market-data/futures-contract.ts +9 -3
  116. package/src/market-data/market/change-basis.ts +2 -2
  117. package/src/market-data/market/dated-previous-close.ts +163 -47
  118. package/src/market-data/market/format.ts +14 -3
  119. package/src/market-data/market/freshness.ts +24 -7
  120. package/src/market-data/market/header-market.ts +154 -0
  121. package/src/market-data/market/index-level.ts +29 -0
  122. package/src/market-data/market/index-session-venues.ts +44 -0
  123. package/src/market-data/market/status.ts +7 -2
  124. package/src/market-data/market/venue-session.ts +72 -0
  125. package/src/market-data/model-dividend-yield.ts +23 -8
  126. package/src/market-data/options-alternatives.ts +39 -4
  127. package/src/market-data/published-apac-sessions.ts +40 -2
  128. package/src/market-data/quotes/export-identity.ts +76 -0
  129. package/src/market-data/quotes/freshness.ts +22 -0
  130. package/src/market-data/quotes/time.ts +42 -1
  131. package/src/market-data/realized-volatility.ts +11 -7
  132. package/src/market-data/tax-equivalent.ts +145 -27
  133. package/src/plugins/builtin/account-management/pane.tsx +2 -2
  134. package/src/plugins/builtin/alerts/alert-engine.ts +12 -6
  135. package/src/plugins/builtin/alerts/alert-log.ts +6 -2
  136. package/src/plugins/builtin/alerts/calendar-events.ts +74 -12
  137. package/src/plugins/builtin/alerts/cli-forms.ts +11 -1
  138. package/src/plugins/builtin/alerts/cli-move.ts +234 -0
  139. package/src/plugins/builtin/alerts/cli.ts +224 -33
  140. package/src/plugins/builtin/alerts/command.ts +33 -6
  141. package/src/plugins/builtin/alerts/event-rows.ts +18 -4
  142. package/src/plugins/builtin/alerts/events-pane.tsx +6 -2
  143. package/src/plugins/builtin/alerts/events.ts +9 -0
  144. package/src/plugins/builtin/alerts/format.ts +40 -15
  145. package/src/plugins/builtin/alerts/headless.ts +31 -18
  146. package/src/plugins/builtin/alerts/history.ts +1 -0
  147. package/src/plugins/builtin/alerts/index.tsx +86 -12
  148. package/src/plugins/builtin/alerts/live.ts +2 -1
  149. package/src/plugins/builtin/alerts/move-checks.ts +155 -0
  150. package/src/plugins/builtin/alerts/move.ts +160 -0
  151. package/src/plugins/builtin/alerts/pane.tsx +52 -22
  152. package/src/plugins/builtin/alerts/price-text.ts +62 -0
  153. package/src/plugins/builtin/alerts/price.ts +17 -0
  154. package/src/plugins/builtin/alerts/quotes.ts +84 -3
  155. package/src/plugins/builtin/alerts/scheduled-check.ts +7 -1
  156. package/src/plugins/builtin/alerts/storage.ts +20 -7
  157. package/src/plugins/builtin/alerts/types.ts +13 -0
  158. package/src/plugins/builtin/analytics/risk-client.ts +60 -39
  159. package/src/plugins/builtin/analytics/risk-episodes.ts +18 -0
  160. package/src/plugins/builtin/analytics/risk-headless.ts +20 -4
  161. package/src/plugins/builtin/analytics/risk-model.ts +68 -1
  162. package/src/plugins/builtin/analytics/risk-pane.tsx +15 -3
  163. package/src/plugins/builtin/backtest/engine.ts +4 -2
  164. package/src/plugins/builtin/backtest/window.ts +3 -1
  165. package/src/plugins/builtin/broker-manager/sign-in-end.ts +1 -1
  166. package/src/plugins/builtin/central-bank-rates/client.ts +4 -0
  167. package/src/plugins/builtin/central-bank-rates/headless.ts +1 -1
  168. package/src/plugins/builtin/central-bank-rates/model.ts +18 -8
  169. package/src/plugins/builtin/central-bank-rates/pane.tsx +6 -3
  170. package/src/plugins/builtin/chart-composer/cli-options.ts +5 -0
  171. package/src/plugins/builtin/chart-composer/headless-schema.ts +17 -1
  172. package/src/plugins/builtin/chart-composer/headless.ts +2 -0
  173. package/src/plugins/builtin/cloud/upgrade-status-widget.tsx +9 -2
  174. package/src/plugins/builtin/crypto-board/headless.ts +82 -17
  175. package/src/plugins/builtin/crypto-board/index.tsx +24 -2
  176. package/src/plugins/builtin/crypto-board/model.ts +5 -2
  177. package/src/plugins/builtin/crypto-board/pane.tsx +4 -1
  178. package/src/plugins/builtin/debt-maturities/client.ts +111 -6
  179. package/src/plugins/builtin/debt-maturities/headless.ts +84 -1
  180. package/src/plugins/builtin/debt-maturities/model.ts +97 -14
  181. package/src/plugins/builtin/debt-maturities/pane.tsx +165 -15
  182. package/src/plugins/builtin/debt-maturities/series.ts +3 -1
  183. package/src/plugins/builtin/dividend-yield/client.ts +22 -6
  184. package/src/plugins/builtin/dividend-yield/headless.ts +113 -46
  185. package/src/plugins/builtin/dividend-yield/model.ts +5 -2
  186. package/src/plugins/builtin/dividend-yield/pane.tsx +6 -3
  187. package/src/plugins/builtin/dividend-yield/ranking-reads.ts +11 -4
  188. package/src/plugins/builtin/dividend-yield/ranking.ts +113 -18
  189. package/src/plugins/builtin/dividend-yield/types.ts +2 -0
  190. package/src/plugins/builtin/dividend-yield/view.ts +3 -0
  191. package/src/plugins/builtin/econ/calendar-model.ts +21 -3
  192. package/src/plugins/builtin/econ/detail-view.tsx +5 -3
  193. package/src/plugins/builtin/econ/figures.ts +13 -0
  194. package/src/plugins/builtin/econ/fred-catalog.ts +6 -3
  195. package/src/plugins/builtin/econ/index.tsx +5 -3
  196. package/src/plugins/builtin/econ/types.ts +5 -0
  197. package/src/plugins/builtin/equity-screener/footer.ts +45 -0
  198. package/src/plugins/builtin/equity-screener/pane.tsx +4 -18
  199. package/src/plugins/builtin/equity-screener/ticker-check.tsx +2 -1
  200. package/src/plugins/builtin/fixed-income/model.ts +1 -0
  201. package/src/plugins/builtin/futures/table.tsx +1 -1
  202. package/src/plugins/builtin/futures-curve/model.ts +3 -10
  203. package/src/plugins/builtin/help/function-card.tsx +2 -1
  204. package/src/plugins/builtin/help/function-index.ts +1 -0
  205. package/src/plugins/builtin/insider/client.ts +31 -14
  206. package/src/plugins/builtin/insider/signals-model.ts +2 -7
  207. package/src/plugins/builtin/iv-history/headless.ts +1 -2
  208. package/src/plugins/builtin/iv-history/model.ts +33 -23
  209. package/src/plugins/builtin/iv-history/screen-pane.tsx +0 -3
  210. package/src/plugins/builtin/kelly-sizer/headless.ts +64 -16
  211. package/src/plugins/builtin/kelly-sizer/history.ts +37 -28
  212. package/src/plugins/builtin/kelly-sizer/pane.tsx +43 -10
  213. package/src/plugins/builtin/kelly-sizer/sections.tsx +7 -2
  214. package/src/plugins/builtin/kelly-sizer/units.ts +29 -0
  215. package/src/plugins/builtin/news/index.tsx +7 -13
  216. package/src/plugins/builtin/news/overview-headlines.tsx +117 -0
  217. package/src/plugins/builtin/news/ticker-news.ts +35 -0
  218. package/src/plugins/builtin/news/wire/news/detail-view.tsx +8 -6
  219. package/src/plugins/builtin/news/wire/news/row.ts +49 -0
  220. package/src/plugins/builtin/news/wire/news/table.tsx +9 -20
  221. package/src/plugins/builtin/options/analytics.ts +7 -2
  222. package/src/plugins/builtin/options/live-quotes.ts +6 -1
  223. package/src/plugins/builtin/options/table.ts +3 -2
  224. package/src/plugins/builtin/options/view.tsx +11 -9
  225. package/src/plugins/builtin/options-scenario/client.ts +3 -0
  226. package/src/plugins/builtin/options-scenario/headless.ts +1 -1
  227. package/src/plugins/builtin/perps/client.ts +5 -4
  228. package/src/plugins/builtin/perps/headless.ts +134 -124
  229. package/src/plugins/builtin/perps/markets-section.tsx +2 -2
  230. package/src/plugins/builtin/perps/model.ts +8 -4
  231. package/src/plugins/builtin/perps/open-market.ts +4 -4
  232. package/src/plugins/builtin/perps/venue-markets.ts +3 -6
  233. package/src/plugins/builtin/portfolio-list/cell-version.ts +1 -0
  234. package/src/plugins/builtin/portfolio-list/cli/bulk-symbols.ts +34 -10
  235. package/src/plugins/builtin/portfolio-list/cli/period-report.ts +28 -2
  236. package/src/plugins/builtin/portfolio-list/cli/portfolio-command.ts +7 -3
  237. package/src/plugins/builtin/portfolio-list/cli/render.ts +66 -22
  238. package/src/plugins/builtin/portfolio-list/grid.tsx +5 -3
  239. package/src/plugins/builtin/portfolio-list/pane/data.ts +34 -1
  240. package/src/plugins/builtin/portfolio-list/pane/index.tsx +6 -0
  241. package/src/plugins/builtin/portfolio-list/pane/streaming.ts +15 -6
  242. package/src/plugins/builtin/portfolio-list/quick-add/resolution.ts +19 -7
  243. package/src/plugins/builtin/portfolio-list/table.tsx +30 -4
  244. package/src/plugins/builtin/realized-vol/evidence.ts +33 -6
  245. package/src/plugins/builtin/realized-vol/fx-proxy.ts +135 -0
  246. package/src/plugins/builtin/realized-vol/headless.ts +44 -8
  247. package/src/plugins/builtin/realized-vol/model.ts +9 -5
  248. package/src/plugins/builtin/realized-vol/pane.tsx +49 -15
  249. package/src/plugins/builtin/sec/headless.ts +48 -6
  250. package/src/plugins/builtin/sec/index.tsx +6 -4
  251. package/src/plugins/builtin/sec/model.ts +4 -1
  252. package/src/plugins/builtin/shared/earnings-calendar.ts +2 -0
  253. package/src/plugins/builtin/shared/market-cap-bands.ts +12 -0
  254. package/src/plugins/builtin/shared/report-freshness.ts +3 -1
  255. package/src/plugins/builtin/shared/use-quote-board.ts +5 -3
  256. package/src/plugins/builtin/shared/volatility/options.ts +63 -2
  257. package/src/plugins/builtin/social-mentions/headless.ts +72 -3
  258. package/src/plugins/builtin/social-mentions/index.tsx +8 -4
  259. package/src/plugins/builtin/social-mentions/lock-note.ts +6 -2
  260. package/src/plugins/builtin/social-mentions/outliers-client.ts +101 -0
  261. package/src/plugins/builtin/social-mentions/outliers-model.ts +162 -0
  262. package/src/plugins/builtin/social-mentions/outliers-names.ts +51 -0
  263. package/src/plugins/builtin/social-mentions/outliers.tsx +276 -0
  264. package/src/plugins/builtin/social-mentions/pane.tsx +32 -3
  265. package/src/plugins/builtin/supply-chain/graph-pane.tsx +2 -2
  266. package/src/plugins/builtin/thirteenf/api.ts +36 -2
  267. package/src/plugins/builtin/thirteenf/data.ts +4 -1
  268. package/src/plugins/builtin/thirteenf/headless.ts +14 -6
  269. package/src/plugins/builtin/thirteenf/model.ts +56 -1
  270. package/src/plugins/builtin/thirteenf/pane.tsx +8 -8
  271. package/src/plugins/builtin/thirteenf/report-notes.ts +11 -0
  272. package/src/plugins/builtin/thirteenf/table.ts +2 -1
  273. package/src/plugins/builtin/thirteenf/types.ts +6 -0
  274. package/src/plugins/builtin/ticker-detail/data-panes/historical-prices.tsx +23 -3
  275. package/src/plugins/builtin/ticker-detail/financials/model.ts +5 -0
  276. package/src/plugins/builtin/ticker-detail/headless-schema.ts +2 -1
  277. package/src/plugins/builtin/ticker-detail/headless.ts +21 -66
  278. package/src/plugins/builtin/ticker-detail/index.tsx +5 -0
  279. package/src/plugins/builtin/ticker-detail/overview/components.tsx +13 -1
  280. package/src/plugins/builtin/ticker-detail/overview/model.ts +6 -4
  281. package/src/plugins/builtin/ticker-detail/overview/pane.tsx +15 -0
  282. package/src/plugins/builtin/ticker-detail/overview/tax-equivalent.ts +69 -0
  283. package/src/plugins/builtin/ticker-detail/overview-tab.tsx +41 -6
  284. package/src/plugins/builtin/ticker-detail/quote-monitor/card.tsx +47 -24
  285. package/src/plugins/builtin/ticker-detail/quote-monitor/export.ts +46 -0
  286. package/src/plugins/builtin/ticker-detail/quote-monitor/index.tsx +20 -1
  287. package/src/plugins/builtin/ticker-detail/quote-monitor/rows.ts +120 -0
  288. package/src/plugins/builtin/ticker-detail/research-tabs.ts +1 -5
  289. package/src/plugins/builtin/ticker-detail/settings.ts +6 -6
  290. package/src/plugins/builtin/treasury-auctions/cache.ts +85 -19
  291. package/src/plugins/builtin/treasury-auctions/index.tsx +22 -11
  292. package/src/plugins/builtin/treasury-auctions/model.ts +23 -0
  293. package/src/plugins/builtin/treasury-auctions/treasury-direct.ts +128 -0
  294. package/src/plugins/builtin/world-indices/client.ts +2 -0
  295. package/src/plugins/compat.ts +15 -0
  296. package/src/plugins/host-link.ts +6 -1
  297. package/src/plugins/installer.ts +8 -3
  298. package/src/portfolio/column-values.ts +14 -4
  299. package/src/portfolio/listed-symbol.ts +78 -0
  300. package/src/portfolio/real-return.ts +172 -0
  301. package/src/public/__snapshots__/public-api.test.ts.snap +1 -0
  302. package/src/renderers/browser/config-host.ts +56 -15
  303. package/src/renderers/browser/main.tsx +3 -1
  304. package/src/renderers/browser/ui-host.tsx +1 -0
  305. package/src/renderers/cloudflare/http-proxy.ts +1 -0
  306. package/src/renderers/dom/boot-frame.ts +2 -2
  307. package/src/renderers/dom/data-table/row.tsx +4 -1
  308. package/src/renderers/dom/desktop/controls.tsx +4 -4
  309. package/src/renderers/dom/desktop/dialog-actions.tsx +60 -41
  310. package/src/renderers/dom/dom-ui-host.tsx +3 -1
  311. package/src/renderers/dom/host/input.tsx +4 -1
  312. package/src/renderers/dom/host/tabs.tsx +10 -1
  313. package/src/renderers/dom/styles.css +33 -13
  314. package/src/renderers/electrobun/bun/desktop/app-name.ts +1 -1
  315. package/src/renderers/opentui/host.tsx +2 -1
  316. package/src/sources/gloomberb-cloud/fred-series.ts +12 -0
  317. package/src/sources/gloomberb-cloud/index.ts +31 -2
  318. package/src/sources/gloomberb-cloud/normalizers.ts +29 -3
  319. package/src/sources/provider-router/cached-routes.ts +19 -7
  320. package/src/state/pane-table-export-registry.ts +19 -6
  321. package/src/test-support/preload.ts +5 -1
  322. package/src/theme/colors.ts +9 -1
  323. package/src/theme/themes.ts +62 -15
  324. package/src/theme/tone-contrast.ts +40 -0
  325. package/src/theme/ui-tokens.ts +23 -3
  326. package/src/tickers/batched-lookups.ts +57 -8
  327. package/src/tickers/company-name-listing.ts +156 -14
  328. package/src/tickers/company-name.ts +30 -6
  329. package/src/tickers/list.ts +7 -0
  330. package/src/tickers/search/home-listing.ts +31 -9
  331. package/src/tickers/search/index.ts +13 -3
  332. package/src/tickers/search/listing-index.ts +558 -0
  333. package/src/tickers/search/major-listings.chunk.ts +10 -0
  334. package/src/tickers/search/major-listings.json +3346 -0
  335. package/src/tickers/search/ranking.ts +68 -1
  336. package/src/tickers/search/types.ts +4 -0
  337. package/src/tickers/terminal-codes.ts +26 -1
  338. package/src/time-series/calendar-month-returns.ts +47 -0
  339. package/src/time-series/currency-conversion.ts +130 -0
  340. package/src/time-series/hooks.ts +2 -0
  341. package/src/time-series/price-comparison.ts +34 -11
  342. package/src/time-series/resolve-context.ts +3 -0
  343. package/src/time-series/resolve.ts +14 -2
  344. package/src/time-series/spec.ts +1 -0
  345. package/src/time-series/studies/indicators.ts +4 -1
  346. package/src/time-series/types.ts +8 -0
  347. package/src/types/config.ts +8 -0
  348. package/src/types/data-provider.ts +28 -0
  349. package/src/types/financials.ts +20 -2
  350. package/src/types/headless.ts +12 -0
  351. package/src/ui/host.tsx +8 -0
  352. package/src/utils/datetime-format.ts +17 -3
  353. package/src/utils/display-number.ts +15 -0
  354. package/src/utils/double-escape-close.ts +61 -16
  355. package/src/utils/float32-price.ts +24 -0
  356. package/src/utils/forward-dividend.ts +81 -16
  357. package/src/utils/fx-market-hours.ts +11 -0
  358. package/src/utils/plugin-proxy-hosts.json +2 -1
  359. package/src/utils/price-history.ts +7 -6
  360. package/src/utils/report-timing.ts +62 -0
  361. package/src/utils/sec-filings.ts +32 -0
  362. package/src/utils/utc-time.ts +5 -0
@@ -11,7 +11,7 @@ import {
11
11
  convertedFromText, formatConvertedAmount, formatDividendYield, growthPaymentsText, PAYOUT_NOT_MEANINGFUL, staleHistoryText, toDividendRows, trailingPaymentsText,
12
12
  } from "./view";
13
13
  import { formatDistributionAmount, formatPercent } from "../../../utils/format";
14
- import { forwardDividendBasis, noCurrentDividend, TRAILING_DIVIDEND_BASIS, UNEVEN_REGULAR_PAYMENTS } from "../../../utils/forward-dividend";
14
+ import { forwardDividendBasis, historyEndsText, noCurrentDividend, TRAILING_DIVIDEND_BASIS, UNEVEN_REGULAR_PAYMENTS } from "../../../utils/forward-dividend";
15
15
  import { currencyPriceMinDigits, formatMarketPriceWithCurrency } from "../../../market-data/market/format";
16
16
  import type { Quote } from "../../../types/financials";
17
17
  import { regularSessionValuationPrice } from "../../../market-data/quotes/regular-session-valuation";
@@ -22,11 +22,10 @@ import { MAX_RANKED_SYMBOLS, readDividendRanking, type DividendRankingReads } fr
22
22
  import { REPORT_FILTER, REPORT_ROWS } from "../shared/headless-options";
23
23
  import type { FundBondFacts } from "../../../api-client/fund-facts";
24
24
  import { resolveTickerInstrumentKind } from "../../../tickers/instrument-kind";
25
- import { isUsListingExchange } from "../../../utils/exchanges";
26
- import { bondClassText, bondFigures, fetchFundBondFacts, NOT_SEC_YIELD } from "../../../market-data/bond-funds";
25
+ import { bondClassText, bondFigures, fetchFundBondFacts, NOT_SEC_YIELD, type BondFigure } from "../../../market-data/bond-funds";
27
26
  import {
28
- analyzeTaxEquivalent, distributionBasis, loadTreasuryTenors, parseTaxRates, TAX_RATE_EXAMPLES, TAX_RATE_OPTIONS, taxEquivalentJson, taxEquivalentLines,
29
- type TaxEquivalentAnalysis, type TreasuryTenor,
27
+ analyzeTaxEquivalent, distributionBasis, loadTreasuryTenors, noBondFigures, parseTaxRates, TAX_RATE_EXAMPLES, TAX_RATE_OPTIONS, taxEquivalentJson,
28
+ taxEquivalentSection, type NoBondFigures, type TaxEquivalentAnalysis, type TreasuryTenor,
30
29
  } from "../../../market-data/tax-equivalent";
31
30
 
32
31
  /** The history options' defaults: a ranking lists no history, so only these leave it unchanged. */
@@ -46,6 +45,10 @@ function paymentColumns(converted: boolean, subUnit?: string) {
46
45
  ];
47
46
  }
48
47
 
48
+ /** Last, once a fund's sponsor gave a row its history lacks: who published each row so given. */
49
+ const SOURCE_COLUMN = { key: "source", header: "Source",
50
+ format: (value: unknown) => typeof value === "string" ? value : "" };
51
+
49
52
  /** After the amount, for a company declaring in another currency than the listing pays: what it declared. */
50
53
  const DECLARED_COLUMN = { key: "declared", header: "Declared", align: "right" as const,
51
54
  format: (value: unknown, row: Record<string, unknown>) => typeof value === "number" && typeof row.declaredCurrency === "string"
@@ -56,8 +59,13 @@ export type DividendReadContext = Pick<HeadlessPaneContext, "marketData" | "apiC
56
59
 
57
60
  export interface DividendYieldHeadlessDependencies {
58
61
  loadData(symbol: string, context: DividendReadContext): Promise<DividendData>;
59
- /** A US-listed fund's bond facts (SEC yield, yield to worst, duration); null for any other listing. */
60
- loadBond?(symbol: string, context: DividendReadContext): Promise<FundBondFacts | null>;
62
+ /**
63
+ * A US-listed fund's bond facts (SEC yield, yield to worst, duration), null
64
+ * for a fund without them, or why the listing has none to read
65
+ * (NoBondFigures: not a fund, or a fund listed abroad). Rejects when the
66
+ * check itself fails.
67
+ */
68
+ loadBond?(symbol: string, context: DividendReadContext): Promise<FundBondFacts | NoBondFigures | null>;
61
69
  /** The Treasury par curve GC shows, for the muni/Treasury ratio; null when it cannot be read. */
62
70
  loadTreasury?(context: HeadlessPaneContext): Promise<TreasuryTenor[] | null>;
63
71
  }
@@ -65,6 +73,9 @@ export interface DividendYieldHeadlessDependencies {
65
73
  /** Already logged at the quote boundary; keep it distinct from absent bond facts. */
66
74
  class BondClassificationError extends Error {}
67
75
 
76
+ /** What a failed fund facts read leaves in place of the tax-equivalent yield. */
77
+ const BOND_FACTS_CHECK_FAILED = "Bond fund facts check failed";
78
+
68
79
  const defaultDependencies: DividendYieldHeadlessDependencies = {
69
80
  async loadData(symbol, context) {
70
81
  let currentPrice: number | null = null;
@@ -105,8 +116,7 @@ const defaultDependencies: DividendYieldHeadlessDependencies = {
105
116
  throw new BondClassificationError("Bond fund quote check failed");
106
117
  });
107
118
  const venue = exchange || quote?.exchangeName || "";
108
- if (resolveTickerInstrumentKind(null, { quote }) !== "fund" || (venue && !isUsListingExchange(venue))) return null;
109
- return fetchFundBondFacts(instrument?.symbol ?? symbol, context.apiClient);
119
+ return noBondFigures(resolveTickerInstrumentKind(null, { quote }), venue) ?? fetchFundBondFacts(instrument?.symbol ?? symbol, context.apiClient);
110
120
  },
111
121
  loadTreasury: (context) => loadTreasuryTenors(context.apiClient),
112
122
  };
@@ -114,7 +124,9 @@ const defaultDependencies: DividendYieldHeadlessDependencies = {
114
124
  /**
115
125
  * How a ranking reads each ticker: `fn DVD`'s, and the DVD pane's with the
116
126
  * app's market data, so both read the same listing at the same price. A
117
- * fund's bond facts never fail its row: without them it ranks as before.
127
+ * fund's bond facts never fail its row: a check that fails is kept on it
128
+ * (`bondError`, in the words single-ticker DVD uses), and without them it
129
+ * ranks as before.
118
130
  */
119
131
  export function dividendRankingReads(
120
132
  context: DividendReadContext,
@@ -124,8 +136,11 @@ export function dividendRankingReads(
124
136
  return {
125
137
  loadData: (symbol) => dependencies.loadData(symbol, context),
126
138
  ...loadBond ? {
127
- loadBond: (symbol: string) => loadBond(symbol, context).catch((error) => error instanceof BondClassificationError ? null
128
- : logFailure("dividend-yield.headless", "Read bond fund facts for ranking failed", null)(error)),
139
+ loadBond: (symbol: string) => loadBond(symbol, context).catch((error) => {
140
+ if (error instanceof BondClassificationError) throw error;
141
+ logFailure("dividend-yield.headless", "Read bond fund facts for ranking failed")(error);
142
+ throw new Error(BOND_FACTS_CHECK_FAILED);
143
+ }),
129
144
  } : {},
130
145
  };
131
146
  }
@@ -135,6 +150,8 @@ function growthText(growth: number | null, payments: GrowthPayments | null | und
135
150
  return growth == null && payments ? growthPaymentsText(payments) : formatPercent(growth ?? undefined);
136
151
  }
137
152
 
153
+ const isoDay = (date: Date | null | undefined): string | null => date ? date.toISOString().slice(0, 10) : null;
154
+
138
155
  function dateEntry(label: string, date: Date | null) {
139
156
  return { label, value: date, formatted: date ? date.toISOString().slice(0, 10) : "—" };
140
157
  }
@@ -173,14 +190,18 @@ export function projectDividendYieldHeadless(
173
190
  declarationDate: payment?.declarationDate?.toISOString() ?? null,
174
191
  type: payment?.type ?? null,
175
192
  ...(row.declared ? { declared: row.declared.amount, declaredCurrency: row.declared.currency } : {}),
193
+ ...(payment?.source ? { source: payment.source.publisher, sourceUrl: payment.source.url } : {}),
176
194
  };
177
195
  });
178
196
  // A listing paid in another currency than its company declares (South32's rand) has its amounts converted from that one.
179
197
  const convertedFrom = data.convertedFrom;
180
198
  const subUnit = data.convertedSubUnit;
181
199
  const paymentColumnList = paymentColumns(!!convertedFrom, subUnit);
182
- const declaredColumns = rows.some((row) => row.declared)
183
- ? [...paymentColumnList.slice(0, 2), DECLARED_COLUMN, ...paymentColumnList.slice(2)] : paymentColumnList;
200
+ const historyColumns = [
201
+ ...(rows.some((row) => row.declared)
202
+ ? [...paymentColumnList.slice(0, 2), DECLARED_COLUMN, ...paymentColumnList.slice(2)] : paymentColumnList),
203
+ ...(rows.some((row) => row.source) ? [SOURCE_COLUMN] : []),
204
+ ];
184
205
  const metrics = data.metrics;
185
206
  const currency = data.currency ?? data.payments[0]?.currency ?? "";
186
207
  const cashRate = (value: number | null) => !currency ? "—" : !convertedFrom ? formatDistributionAmount(value ?? undefined, currency)
@@ -190,50 +211,87 @@ export function projectDividendYieldHeadless(
190
211
  const shortfall = trailingPaymentsText(metrics.trailingPayments, { cadence: true });
191
212
  const errors = [data.historyError, data.summaryError, tax?.checkError].filter((error): error is string => !!error);
192
213
 
214
+ // A monthly payer's history that ends early: its yields and last ex-date stop there, and each says so.
215
+ const historyEnd = metrics.lapse?.historyEnds ? metrics.lapse.lastPaid : null;
216
+ const trailingNotes = [TRAILING_DIVIDEND_BASIS, shortfall ? `counts ${shortfall}` : null, historyEnd ? historyEndsText(historyEnd) : null]
217
+ .filter((note): note is string => !!note).join("; ");
218
+ const trailingLabel = bond ? `Trailing distribution yield (${NOT_SEC_YIELD})` : "Trailing yield";
219
+ const forwardLabel = bond ? `Forward distribution yield (${NOT_SEC_YIELD})` : "Forward yield";
220
+ const forwardText = metrics.lapse ? noCurrentDividend(metrics.lapse) : null;
221
+ const lastEx = isoDay(metrics.lastExDividendDate);
222
+ const growthEntry = (label: string, value: number | null, payments: GrowthPayments | null | undefined) =>
223
+ ({ label, value: roundedRatio(value), formatted: growthText(value, payments) });
224
+ const datesAndCash = [
225
+ dateEntry("Last ex-dividend", metrics.lastExDividendDate),
226
+ dateEntry("Next ex-dividend", metrics.nextExDividendDate),
227
+ dateEntry("Next pay", metrics.nextPayDate),
228
+ ...(data.payments.length > 0 && metrics.trailingRate === 0
229
+ ? [{ label: "Cash status", value: "No cash distributions reported in the past 12 months." }] : []),
230
+ ];
231
+ const figures = bond ? bondFigures(bond) : [];
232
+ const figureLabel = (figure: BondFigure) => figure.key === "secYield" ? "30-day SEC yield" : figure.label;
233
+ const priceStatusText = !priceStatus ? null : priceStatus === "stale"
234
+ ? "Stale reference price; cash yield may be out of date."
235
+ : "Reference price time unavailable; cash yield may be out of date.";
193
236
  return {
194
237
  ...(errors.length > 0 ? { complete: false, errors } : {}),
195
238
  sections: [
196
239
  {
197
240
  title: "Dividend metrics",
198
- entries: [
241
+ // What the text report says of each figure: its basis, its date and why one is missing, in one line.
242
+ textEntries: [
199
243
  { label: "Price", value: data.price, ...(data.price != null && currency ? { formatted: formatMarketPriceWithCurrency(data.price, currency, { minimumFractionDigits: currencyPriceMinDigits(currency) }) } : {}) },
200
244
  ...(data.stale ? [{ label: "History status", value: staleHistoryText(data.fetchedAt) }] : []),
201
- ...(priceStatus ? [{ label: "Price status", value: priceStatus === "stale"
202
- ? "Stale reference price; cash yield may be out of date."
203
- : "Reference price time unavailable; cash yield may be out of date." }] : []),
204
- { label: bond ? `Trailing distribution yield (${NOT_SEC_YIELD})` : "Trailing yield", value: roundedRatio(metrics.trailingYield),
205
- formatted: metrics.trailingYield == null ? formatDividendYield(null)
206
- : `${formatDividendYield(metrics.trailingYield)} (${TRAILING_DIVIDEND_BASIS}${shortfall ? `; counts ${shortfall}` : ""})` },
207
- { label: bond ? `Forward distribution yield (${NOT_SEC_YIELD})` : "Forward yield", value: roundedRatio(metrics.forwardYield),
208
- formatted: metrics.lapse ? noCurrentDividend(metrics.lapse)
209
- : metrics.forwardYield == null ? formatDividendYield(null)
245
+ ...(priceStatusText ? [{ label: "Price status", value: priceStatusText }] : []),
246
+ { label: trailingLabel, value: roundedRatio(metrics.trailingYield),
247
+ formatted: metrics.trailingYield == null ? formatDividendYield(null) : `${formatDividendYield(metrics.trailingYield)} (${trailingNotes})` },
248
+ { label: forwardLabel, value: roundedRatio(metrics.forwardYield),
249
+ formatted: forwardText
250
+ ?? (metrics.forwardYield == null ? formatDividendYield(null)
210
251
  : `${formatDividendYield(metrics.forwardYield)} (${metrics.forwardBasis === "uneven" ? UNEVEN_REGULAR_PAYMENTS
211
- : forwardDividendBasis(metrics.forwardRateAsOf, { payDate: forwardPayDate(metrics), declared: data.declared, currency })})` },
212
- ...(bond ? bondFigures(bond).map((figure) => ({
213
- label: figure.key === "secYield" ? "30-day SEC yield" : figure.label,
252
+ : forwardDividendBasis(metrics.forwardRateAsOf, { payDate: forwardPayDate(metrics), declared: data.declared, currency })})`) },
253
+ ...figures.map((figure) => ({
254
+ label: figureLabel(figure),
214
255
  value: figure.value,
215
256
  formatted: `${figure.text}${figure.date ? ` (as of ${figure.date})` : ""}`,
216
- })) : []),
257
+ })),
217
258
  { label: "Trailing rate", value: metrics.trailingRate, formatted: cashRate(metrics.trailingRate) },
218
259
  { label: "Forward rate", value: metrics.forwardRate, formatted: cashRate(metrics.forwardRate) },
219
260
  { label: "Earnings Payout", value: roundedRatio(metrics.payoutRatio), formatted: metrics.payoutNotMeaningful ? PAYOUT_NOT_MEANINGFUL : formatDividendYield(metrics.payoutRatio) },
220
- { label: "1Y Cash Growth", value: roundedRatio(metrics.growth1Y), formatted: growthText(metrics.growth1Y, metrics.growth1YPayments) },
221
- { label: "3Y Cash CAGR", value: roundedRatio(metrics.growth3Y), formatted: growthText(metrics.growth3Y, metrics.growth3YPayments) },
261
+ growthEntry("1Y Cash Growth", metrics.growth1Y, metrics.growth1YPayments),
262
+ growthEntry("3Y Cash CAGR", metrics.growth3Y, metrics.growth3YPayments),
222
263
  { label: "Frequency", value: metrics.paymentFrequency },
223
- dateEntry("Last ex-dividend", metrics.lastExDividendDate),
224
- dateEntry("Next ex-dividend", metrics.nextExDividendDate),
225
- dateEntry("Next pay", metrics.nextPayDate),
226
- ...(data.payments.length > 0 && metrics.trailingRate === 0
227
- ? [{ label: "Cash status", value: "No cash distributions reported in the past 12 months." }] : []),
264
+ ...datesAndCash,
265
+ ],
266
+ // What exports and JSON keep: each figure as a number in its unit, dated by its own observation (the price a
267
+ // yield is over, the day a sponsor gives a figure as of, the ex-date a rate is from), as the multi-fund ranking writes.
268
+ entries: [
269
+ { label: "Price", value: data.price, ...(data.price != null && currency ? { unit: currency } : {}), asOf: data.priceAsOf ?? null },
270
+ ...(data.stale ? [{ label: "History status", value: staleHistoryText(data.fetchedAt), asOf: data.fetchedAt ?? null }] : []),
271
+ ...(priceStatusText ? [{ label: "Price status", value: priceStatusText, asOf: data.priceAsOf ?? null }] : []),
272
+ { label: trailingLabel, value: roundedRatio(metrics.trailingYield), formatted: formatDividendYield(metrics.trailingYield),
273
+ exportUnit: "pct", asOf: metrics.trailingYield == null ? null : data.priceAsOf ?? null },
274
+ { label: forwardLabel, value: roundedRatio(metrics.forwardYield), formatted: metrics.forwardYield == null ? forwardText ?? "—" : formatDividendYield(metrics.forwardYield),
275
+ exportUnit: "pct", asOf: metrics.forwardYield == null ? null : data.priceAsOf ?? null },
276
+ ...figures.map((figure) => figure.key === "duration"
277
+ ? { label: figureLabel(figure), value: figure.value, unit: "years", asOf: bond?.duration?.asOf ?? null }
278
+ : { label: figureLabel(figure), value: figure.value, formatted: figure.text, exportUnit: "pct", asOf: bond?.[figure.key]?.asOf ?? null }),
279
+ { label: "Trailing rate", value: metrics.trailingRate, ...(metrics.trailingRate != null && currency && !convertedFrom ? { unit: currency } : { formatted: cashRate(metrics.trailingRate) }),
280
+ asOf: metrics.trailingRate == null ? null : lastEx },
281
+ { label: "Forward rate", value: metrics.forwardRate, ...(metrics.forwardRate != null && currency && !convertedFrom ? { unit: currency } : { formatted: cashRate(metrics.forwardRate) }),
282
+ asOf: metrics.forwardRate == null ? null : metrics.forwardRateAsOf },
283
+ { label: "Earnings Payout", value: roundedRatio(metrics.payoutRatio), formatted: metrics.payoutNotMeaningful ? PAYOUT_NOT_MEANINGFUL : formatDividendYield(metrics.payoutRatio),
284
+ exportUnit: "pct", asOf: null },
285
+ { ...growthEntry("1Y Cash Growth", metrics.growth1Y, metrics.growth1YPayments), exportUnit: "pct", asOf: metrics.growth1Y == null ? null : lastEx },
286
+ { ...growthEntry("3Y Cash CAGR", metrics.growth3Y, metrics.growth3YPayments), exportUnit: "pct", asOf: metrics.growth3Y == null ? null : lastEx },
287
+ { label: "Frequency", value: metrics.paymentFrequency, asOf: null },
288
+ ...datesAndCash.map((entry) => ({ ...entry, asOf: null })),
228
289
  ],
229
290
  },
230
- ...(tax ? [{
231
- title: "Tax-equivalent yield",
232
- entries: taxEquivalentLines(tax).map((line) => ({ label: line.label, value: line.value, formatted: line.text })),
233
- }] : []),
291
+ ...(tax ? [taxEquivalentSection(tax)] : []),
234
292
  {
235
293
  title: convertedFrom ? `Dividend history (amounts ${convertedFromText(convertedFrom)})` : "Dividend history",
236
- columns: declaredColumns,
294
+ columns: historyColumns,
237
295
  rows,
238
296
  // Each amount is in its own row's currency.
239
297
  rowUnitKey: "currency",
@@ -263,6 +321,8 @@ export function projectDividendYieldHeadless(
263
321
  growth1YPayments: metrics.growth1YPayments ?? null,
264
322
  growth3YPayments: metrics.growth3YPayments ?? null,
265
323
  forwardRateAsOf: metrics.forwardRateAsOf,
324
+ // Set when a monthly payer's history stops more than 40 days ago: its forward yield is withheld and its trailing yield counts the history to then.
325
+ historyEnds: metrics.lapse?.historyEnds ? metrics.lapse.lastPaid : null,
266
326
  // "uneven": the year's regular payments differ too widely for one to be annualized, so the forward rate is their total.
267
327
  forwardBasis: metrics.forwardBasis ?? null,
268
328
  // Declared and unpaid, apart from the paid history the table and every figure read.
@@ -323,7 +383,7 @@ export function createDividendYieldHeadless(
323
383
  if (args.symbols.length <= 1) {
324
384
  const symbol = args.symbols[0] ?? String(args.argument);
325
385
  let bondCheckError: string | undefined;
326
- const [data, bond, treasury] = await Promise.all([
386
+ const [data, bondRead, treasury] = await Promise.all([
327
387
  dependencies.loadData(symbol, context),
328
388
  // Optional enrichment without a tax rate; a requested tax check must distinguish failure from absence.
329
389
  dependencies.loadBond?.(symbol, context)
@@ -332,23 +392,23 @@ export function createDividendYieldHeadless(
332
392
  bondCheckError = error.message;
333
393
  } else {
334
394
  logFailure("dividend-yield.headless", "Read bond fund facts for report failed")(error);
335
- bondCheckError = "Bond fund facts check failed";
395
+ bondCheckError = BOND_FACTS_CHECK_FAILED;
336
396
  }
337
397
  return null;
338
398
  }) ?? null,
339
399
  rates ? dependencies.loadTreasury?.(context)
340
400
  .catch(logFailure("dividend-yield.headless", "Read Treasury curve for tax comparison failed", null)) ?? null : null,
341
401
  ]);
402
+ // A stock, or a fund listed abroad, has no bond figures, and its tax line says why rather than that none are loaded.
403
+ const bond = typeof bondRead === "string" ? null : bondRead;
342
404
  const forward = data.metrics.lapse ? null : distributionBasis(data.metrics.forwardYield, "forward", data.metrics.forwardRateAsOf ?? null);
343
405
  const tax = rates ? analyzeTaxEquivalent({
344
406
  symbol: symbol.toUpperCase(), bond, rates, treasury, checkError: bondCheckError,
407
+ noBondFigures: typeof bondRead === "string" ? bondRead : null,
345
408
  distribution: forward ?? distributionBasis(data.metrics.trailingYield, "trailing"),
346
409
  }) : null;
347
410
  return projectDividendYieldHeadless(data, args, { bond, tax });
348
411
  }
349
- if (rates) {
350
- throw new Error("--tax-rate reads one fund's yield against the Treasury curve, and a ranking of several gives none. Drop it, or run DVD on one ticker.");
351
- }
352
412
  // They choose rows of one ticker's payment history, which a ranking does not list: refused rather than dropped.
353
413
  const historyOptions = [
354
414
  ...(String(args.options.type ?? DEFAULT_TYPE) !== DEFAULT_TYPE ? ["--type"] : []),
@@ -357,7 +417,14 @@ export function createDividendYieldHeadless(
357
417
  if (historyOptions.length > 0) {
358
418
  throw new Error(`${historyOptions.join(" and ")} ${historyOptions.length === 1 ? "filters" : "filter"} one ticker's payment history, and a ranking of several lists none. Drop ${historyOptions.length === 1 ? "it" : "them"}, or run DVD on one ticker.`);
359
419
  }
360
- return projectDividendRanking(await readDividendRanking(args.symbols, dividendRankingReads(context, dependencies)));
420
+ // With --tax-rate each fund's row adds its yield to worst, duration, tax-equivalent yield and muni/Treasury ratio,
421
+ // over the one Treasury curve read beside the funds.
422
+ const [entries, treasury] = await Promise.all([
423
+ readDividendRanking(args.symbols, dividendRankingReads(context, dependencies)),
424
+ rates ? dependencies.loadTreasury?.(context)
425
+ .catch(logFailure("dividend-yield.headless", "Read Treasury curve for tax ranking failed", null)) ?? null : null,
426
+ ]);
427
+ return projectDividendRanking(entries, new Date(), rates ? { rates, treasury } : null);
361
428
  },
362
429
  };
363
430
  }
@@ -2,7 +2,7 @@ import type { DataTableColumn } from "../../../components";
2
2
  import { compareSortValues, type SortDirection } from "../../../utils/sort-values";
3
3
  import type { DividendRow } from "./view";
4
4
 
5
- export type DividendColumnId = "exDate" | "amount" | "declared" | "currency";
5
+ export type DividendColumnId = "exDate" | "amount" | "declared" | "currency" | "source";
6
6
  export type DividendColumn = DataTableColumn & { id: DividendColumnId };
7
7
 
8
8
  export interface DividendSortPreference {
@@ -20,14 +20,16 @@ export const DEFAULT_SORT_PREFERENCE: DividendSortPreference = {
20
20
  * amount follows it only for a company declaring in another currency than the
21
21
  * listing pays (BP's dollars beside its pence). The currency column shows only
22
22
  * when the payments mix currencies; otherwise the amount's own symbol says it.
23
+ * The source column shows only when a fund's sponsor gave a row its history lacks.
23
24
  */
24
- export function buildDividendColumns(rows: readonly Pick<DividendRow, "currency" | "declared">[] = []): DividendColumn[] {
25
+ export function buildDividendColumns(rows: readonly Pick<DividendRow, "currency" | "declared" | "source">[] = []): DividendColumn[] {
25
26
  const mixed = new Set(rows.map((row) => row.currency)).size > 1;
26
27
  return [
27
28
  { id: "exDate", label: "EX-DATE", width: 10, align: "left" },
28
29
  { id: "amount", label: "AMOUNT", width: 12, align: "right" },
29
30
  ...(rows.some((row) => row.declared) ? [{ id: "declared" as const, label: "DECLARED", width: 10, align: "right" as const }] : []),
30
31
  ...(mixed ? [{ id: "currency" as const, label: "CCY", width: 6, align: "left" as const }] : []),
32
+ ...(rows.some((row) => row.source) ? [{ id: "source" as const, label: "SOURCE", width: 12, align: "left" as const }] : []),
31
33
  ];
32
34
  }
33
35
 
@@ -37,6 +39,7 @@ function getSortValue(columnId: DividendColumnId, row: DividendRow): string | nu
37
39
  case "amount": return row.amount;
38
40
  case "declared": return row.declared?.amount ?? null;
39
41
  case "currency": return row.currency;
42
+ case "source": return row.source ?? null;
40
43
  }
41
44
  }
42
45
 
@@ -23,7 +23,7 @@ import { TextAttributes, useUiCapabilities } from "../../../ui";
23
23
  import { displayWidth, formatCurrency, formatDistributionAmount, formatPercentRaw } from "../../../utils/format";
24
24
  import { resolveCurrencyUnit } from "../../../utils/currency-units";
25
25
  import { parsePublicTickerKey } from "../../../utils/exchanges";
26
- import { forwardDividendNote, lastPaidNote, NO_CURRENT_DIVIDEND, UNEVEN_REGULAR_PAYMENTS } from "../../../utils/forward-dividend";
26
+ import { forwardDividendNote, lapseValue, lastPaidNote, UNEVEN_REGULAR_PAYMENTS } from "../../../utils/forward-dividend";
27
27
  import { nextHeaderSort } from "../../../utils/sort-values";
28
28
  import { handleRefreshKey, loadingErrorFooterInfo } from "../../../components/data-table/table-pane";
29
29
  import { SignInWall } from "../cloud/auth-actions";
@@ -114,9 +114,10 @@ function buildMetricItems(metrics: DividendMetrics, currency: string, hasHistory
114
114
  { id: "ttm-yield", label: ttmLabel, value: formatDividendYield(metrics.trailingYield), color: priceColor(metrics.trailingYield ?? 0),
115
115
  ...(trailingNote ? { detail: trailingNote } : {}) },
116
116
  // Dated by the distribution it annualizes, or marked declared (with its stated amount) beside the next ex-date;
117
- // a dividend that stopped has none, dated by its last ex-date. docs/research-data.md says how it is built.
117
+ // a dividend that stopped has none, dated by its last ex-date, and a monthly payer's history that ends says so.
118
+ // docs/research-data.md says how it is built.
118
119
  metrics.lapse
119
- ? { id: "forward-yield", label: fwdLabel, value: NO_CURRENT_DIVIDEND, ...(forwardNote ? { detail: forwardNote } : {}) }
120
+ ? { id: "forward-yield", label: fwdLabel, value: lapseValue(metrics.lapse), ...(forwardNote ? { detail: forwardNote } : {}) }
120
121
  : { id: "forward-yield", label: fwdLabel, value: formatDividendYield(metrics.forwardYield), color: priceColor(metrics.forwardYield ?? 0),
121
122
  ...(forwardNote ? { detail: forwardNote } : {}) },
122
123
  // The 30-day SEC yield as the fund's sponsor publishes it, dated.
@@ -167,6 +168,8 @@ function renderCell(
167
168
  return { text: row.declared ? formatDistributionAmount(row.declared.amount, row.declared.currency) : "", color: colors.textDim };
168
169
  case "currency":
169
170
  return { text: row.currency, color: colors.textDim };
171
+ case "source":
172
+ return { text: row.source ?? "", color: colors.textDim };
170
173
  }
171
174
  }
172
175
 
@@ -1,5 +1,6 @@
1
1
  import { ApiRequestError } from "../../../api-client/errors";
2
2
  import type { FundBondFacts } from "../../../api-client/fund-facts";
3
+ import type { NoBondFigures } from "../../../market-data/tax-equivalent";
3
4
  import { createConcurrencyLimiter } from "../../../utils/concurrency";
4
5
  import type { DividendData } from "./client";
5
6
  import type { DividendRankingEntry } from "./ranking";
@@ -18,8 +19,12 @@ const rankingReads = createConcurrencyLimiter(RANKING_CONCURRENCY);
18
19
  /** How a ranking reads one ticker. */
19
20
  export interface DividendRankingReads {
20
21
  loadData(symbol: string): Promise<DividendData>;
21
- /** A fund's bond facts, null for any other listing. It never rejects: without them the fund ranks as before. */
22
- loadBond?(symbol: string): Promise<FundBondFacts | null>;
22
+ /**
23
+ * A fund's bond facts, null for a fund without them, or why the listing has
24
+ * none (NoBondFigures). A rejection is a check that failed, which the row
25
+ * keeps as `bondError`; the fund ranks as before either way.
26
+ */
27
+ loadBond?(symbol: string): Promise<FundBondFacts | NoBondFigures | null>;
23
28
  }
24
29
 
25
30
  interface RankingReadOptions {
@@ -63,9 +68,11 @@ export function readDividendRanking(
63
68
  { sleep = wait }: RankingReadOptions = {},
64
69
  ): Promise<DividendRankingEntry[]> {
65
70
  return Promise.all(symbols.slice(0, MAX_RANKED_SYMBOLS).map((symbol) => rankingReads(async (): Promise<DividendRankingEntry> => {
66
- const bond = reads.loadBond?.(symbol) ?? null;
71
+ const bond = Promise.resolve(reads.loadBond?.(symbol) ?? null).then(
72
+ (read) => typeof read === "string" ? { bond: null, noBondFigures: read } : { bond: read },
73
+ (error: unknown) => ({ bond: null, bondError: error instanceof Error ? error.message : String(error) }));
67
74
  try {
68
- return { symbol, data: await retryRateLimitedOnce(() => reads.loadData(symbol), sleep), bond: await bond };
75
+ return { symbol, data: await retryRateLimitedOnce(() => reads.loadData(symbol), sleep), ...await bond };
69
76
  } catch (error) {
70
77
  return { symbol, error: error instanceof Error ? error.message : String(error) };
71
78
  }
@@ -4,13 +4,19 @@ import type { DividendData } from "./client";
4
4
  import { formatDividendYield, growthPaymentsDetail, PAYOUT_NOT_MEANINGFUL, trailingPaymentsText } from "./view";
5
5
  import type { FundBondFacts } from "../../../api-client/fund-facts";
6
6
  import { NOT_SEC_YIELD } from "../../../market-data/bond-funds";
7
+ import { historyEndsText } from "../../../utils/forward-dividend";
8
+ import {
9
+ analyzeTaxEquivalent, distributionBasis, formatMuniTreasuryRatio, type NoBondFigures, type TaxEquivalentAnalysis, type TaxRates, type TreasuryTenor,
10
+ } from "../../../market-data/tax-equivalent";
7
11
 
8
12
  /**
9
13
  * One symbol of `fn DVD A B C`: what DVD read for it, or why it read nothing.
10
- * A bond fund's facts give its SEC yield, which its cash yields are not.
14
+ * A bond fund's facts give its SEC yield, which its cash yields are not; a
15
+ * listing that has none says why (`noBondFigures`), and a check of them that
16
+ * failed says so (`bondError`), which leaves a `--tax-rate` ranking partial.
11
17
  */
12
18
  export type DividendRankingEntry =
13
- | { symbol: string; data: DividendData; bond?: FundBondFacts | null }
19
+ | { symbol: string; data: DividendData; bond?: FundBondFacts | null; noBondFigures?: NoBondFigures; bondError?: string }
14
20
  | { symbol: string; error: string };
15
21
 
16
22
  const isoDay = (date: Date | null | undefined): string | null => date ? date.toISOString().slice(0, 10) : null;
@@ -47,16 +53,24 @@ function incompleteNote(entry: DividendRankingEntry): string | null {
47
53
  return summaryError ? `no summary${forward}` : null;
48
54
  }
49
55
 
50
- /** How a row's trailing yield was counted, when its year holds fewer payments than its cadence pays; null otherwise. */
56
+ /**
57
+ * How a row's trailing yield was counted, when its year holds fewer payments
58
+ * than its cadence pays, or where a monthly payer's history ends; null
59
+ * otherwise.
60
+ */
51
61
  function yieldBasis(entry: DividendRankingEntry): string | null {
52
- const counted = "data" in entry ? trailingPaymentsText(entry.data.metrics.trailingPayments, { cadence: true }) : null;
62
+ if (!("data" in entry)) return null;
63
+ const lapse = entry.data.metrics.lapse;
64
+ if (lapse?.historyEnds && lapse.lastPaid) return historyEndsText(lapse.lastPaid);
65
+ const counted = trailingPaymentsText(entry.data.metrics.trailingPayments, { cadence: true });
53
66
  return counted ? `counts ${counted}` : null;
54
67
  }
55
68
 
56
69
  /** What a row is missing, in full, for the report's errors; null for a whole read. */
57
- function incompleteReason(entry: DividendRankingEntry): string | null {
70
+ function incompleteReason(entry: DividendRankingEntry, tax = false): string | null {
58
71
  if ("error" in entry) return entry.error;
59
- const reasons = [entry.data.historyError, entry.data.summaryError].filter((reason): reason is string => !!reason);
72
+ // With --tax-rate a failed bond facts check leaves the row's tax figures unknown, as it does single-ticker DVD's.
73
+ const reasons = [entry.data.historyError, entry.data.summaryError, tax ? entry.bondError : null].filter((reason): reason is string => !!reason);
60
74
  return reasons.length > 0 ? reasons.join(" ") : null;
61
75
  }
62
76
 
@@ -69,18 +83,70 @@ function secYieldFields(entry: DividendRankingEntry): { secYield: number | null;
69
83
  return { secYield: sec ? roundedRatio(sec.value / 100) : null, secYieldAsOf: sec?.asOf ?? null };
70
84
  }
71
85
 
86
+ /** What `--tax-rate` reads a ranking with: the rates, and the Treasury curve its muni/Treasury ratios divide by. */
87
+ export interface RankingTaxOptions {
88
+ rates: TaxRates;
89
+ treasury: readonly TreasuryTenor[] | null;
90
+ }
91
+
92
+ /** A row's tax-equivalent yield and muni/Treasury ratio, on its SEC yield or else its distribution yield, as single-fund DVD reads them. */
93
+ function rankingTaxAnalysis(entry: DividendRankingEntry, tax: RankingTaxOptions): TaxEquivalentAnalysis | null {
94
+ if (!("data" in entry)) return null;
95
+ const metrics = entry.data.metrics;
96
+ const forward = metrics.lapse ? null : distributionBasis(metrics.forwardYield, "forward", metrics.forwardRateAsOf ?? null);
97
+ return analyzeTaxEquivalent({
98
+ symbol: entry.symbol.toUpperCase(), bond: entry.bond ?? null, rates: tax.rates, treasury: tax.treasury,
99
+ distribution: forward ?? distributionBasis(metrics.trailingYield, "trailing"),
100
+ ...entry.bondError ? { checkError: entry.bondError } : {}, noBondFigures: entry.noBondFigures ?? null,
101
+ });
102
+ }
103
+
104
+ /** Why a row has no tax-equivalent yield, or what it is on when not the SEC yield, in a few words. */
105
+ function taxNote(analysis: TaxEquivalentAnalysis | null, entry: DividendRankingEntry): string | null {
106
+ if (!analysis || !("data" in entry)) return "error" in entry ? "not read" : null;
107
+ if (entry.bondError) return "bond facts check failed";
108
+ if (entry.noBondFigures) return entry.noBondFigures === "not-a-fund" ? "not a fund" : "fund listed outside the US";
109
+ if (!entry.bond) return "no sponsor bond figures";
110
+ if (entry.bond.kind !== "municipal") return "taxable fund";
111
+ if (analysis.taxEquivalentYield == null) return "no yield";
112
+ const notes = [analysis.basis?.kind === "distribution" ? "on distribution yield" : null, analysis.ratio ? null : "no duration for a ratio"];
113
+ return notes.filter(Boolean).join("; ") || null;
114
+ }
115
+
116
+ /**
117
+ * With `--tax-rate`: each row's yield to worst and duration as its sponsor
118
+ * publishes them, its tax-equivalent yield and muni/Treasury ratio as ratios,
119
+ * the Treasury tenor the ratio divides by, and why a row has none.
120
+ */
121
+ function taxFields(entry: DividendRankingEntry, tax: RankingTaxOptions) {
122
+ const bond = "data" in entry ? entry.bond : null;
123
+ const analysis = rankingTaxAnalysis(entry, tax);
124
+ return {
125
+ yieldToWorst: bond?.yieldToWorst ? roundedRatio(bond.yieldToWorst.value / 100) : null,
126
+ yieldToWorstAsOf: bond?.yieldToWorst?.asOf ?? null,
127
+ duration: bond?.duration?.value ?? null,
128
+ durationUnit: "years",
129
+ durationAsOf: bond?.duration?.asOf ?? null,
130
+ taxEquivalentYield: analysis?.taxEquivalentYield != null ? roundedRatio(analysis.taxEquivalentYield / 100) : null,
131
+ muniTreasuryRatio: analysis?.ratio ? roundedRatio(analysis.ratio.value) : null,
132
+ treasuryTenor: analysis?.ratio?.treasury.tenor ?? null,
133
+ taxNote: taxNote(analysis, entry),
134
+ };
135
+ }
136
+
72
137
  /**
73
138
  * Rows ranked by trailing yield, highest first; a symbol without one, then
74
139
  * one that failed, last, in the order typed. Yield and growth are ratios, so
75
140
  * listings in different currencies rank together. With a bond fund among
76
141
  * them, each row carries the SEC yield after its forward yield.
77
142
  */
78
- function rankDividendEntries(entries: readonly DividendRankingEntry[], now = new Date()): Record<string, unknown>[] {
79
- const bonds = entries.some(isBondEntry);
143
+ function rankDividendEntries(entries: readonly DividendRankingEntry[], now = new Date(), tax: RankingTaxOptions | null = null): Record<string, unknown>[] {
144
+ const bonds = !!tax || entries.some(isBondEntry);
80
145
  const rows = entries.map((entry, index) => {
81
146
  if ("error" in entry) {
82
147
  return { index, failed: true, trailingYield: null, row: { symbol: entry.symbol, currency: null, price: null, priceAsOf: null, trailingYield: null, forwardYield: null,
83
- ...bonds ? secYieldFields(entry) : {}, payoutRatio: null, growth1Y: null, growth3Y: null, lastExDate: null, payDate: null, frequency: null, note: incompleteNote(entry), error: entry.error } };
148
+ ...bonds ? secYieldFields(entry) : {}, ...tax ? taxFields(entry, tax) : {},
149
+ payoutRatio: null, growth1Y: null, growth3Y: null, lastExDate: null, payDate: null, frequency: null, note: incompleteNote(entry), error: entry.error } };
84
150
  }
85
151
  const { data } = entry;
86
152
  const metrics = data.metrics;
@@ -98,6 +164,7 @@ function rankDividendEntries(entries: readonly DividendRankingEntry[], now = new
98
164
  trailingYield: roundedRatio(metrics.trailingYield),
99
165
  forwardYield: roundedRatio(metrics.forwardYield),
100
166
  ...bonds ? secYieldFields(entry) : {},
167
+ ...tax ? taxFields(entry, tax) : {},
101
168
  payoutRatio: roundedRatio(metrics.payoutRatio),
102
169
  payoutNotMeaningful: metrics.payoutNotMeaningful === true,
103
170
  growth1Y: roundedRatio(metrics.growth1Y),
@@ -158,11 +225,33 @@ const SEC_YIELD_COLUMNS: HeadlessPaneColumn[] = [
158
225
  description: "The date the sponsor gives its SEC yield as of." },
159
226
  ];
160
227
 
161
- /** The ranking's columns: a bond fund's SEC yield after the forward yield once one is ranked. */
162
- function rankingColumns(bonds: boolean): HeadlessPaneColumn[] {
228
+ const years = (value: unknown) => typeof value === "number" && Number.isFinite(value) ? `${value.toFixed(2)} yrs` : "—";
229
+
230
+ /** Shown after the SEC yield with `--tax-rate`: the rest of a bond fund's sponsor figures, then what the tax rate makes of its yield. */
231
+ const TAX_COLUMNS: HeadlessPaneColumn[] = [
232
+ { key: "yieldToWorst", header: "YTW", align: "right", format: ratio,
233
+ description: "A bond fund's yield to worst as its sponsor publishes it (yieldToWorstAsOf dates it)." },
234
+ { key: "duration", header: "Duration", align: "right", unitKey: "durationUnit", unitColumn: false, format: years, textFormat: years,
235
+ description: "A bond fund's duration in years as its sponsor publishes it (durationAsOf dates it)." },
236
+ { key: "taxEquivalentYield", header: "TEY", align: "right", format: ratio,
237
+ description: "A muni fund's tax-equivalent yield at --tax-rate: its SEC yield (else its distribution yield) / (1 - the rate). Blank for a taxable fund." },
238
+ // To one decimal, as single-ticker DVD and DES draw it.
239
+ { key: "muniTreasuryRatio", header: "Muni/Tsy", align: "right",
240
+ format: (value) => typeof value === "number" && Number.isFinite(value) ? formatMuniTreasuryRatio(value) : "—",
241
+ description: "A muni fund's yield over the Treasury par yield at the tenor nearest its duration (treasuryTenor)." },
242
+ { key: "treasuryTenor", header: "Tenor", format: day, shrink: false, stackPriority: 4,
243
+ description: "The Treasury tenor the muni/Treasury ratio divides by." },
244
+ ];
245
+
246
+ /** Shown with `--tax-rate` once a row has no tax-equivalent yield, or one on its distribution yield. */
247
+ const TAX_NOTE_COLUMN: HeadlessPaneColumn = { key: "taxNote", header: "Tax note", format: (value) => typeof value === "string" ? value : "",
248
+ description: "Why a row has no tax-equivalent yield (a taxable fund, not a fund, a fund listed outside the US, no sponsor bond figures, or a bond facts check that failed), or what it is on when not the SEC yield." };
249
+
250
+ /** The ranking's columns: a bond fund's SEC yield after the forward yield once one is ranked, and with `--tax-rate` its tax columns after it. */
251
+ function rankingColumns(bonds: boolean, tax = false): HeadlessPaneColumn[] {
163
252
  if (!bonds) return RANKING_COLUMNS;
164
253
  const after = RANKING_COLUMNS.findIndex((column) => column.key === "forwardYield") + 1;
165
- return [...RANKING_COLUMNS.slice(0, after), ...SEC_YIELD_COLUMNS, ...RANKING_COLUMNS.slice(after)];
254
+ return [...RANKING_COLUMNS.slice(0, after), ...SEC_YIELD_COLUMNS, ...tax ? TAX_COLUMNS : [], ...RANKING_COLUMNS.slice(after)];
166
255
  }
167
256
 
168
257
  /** Shown once a row is incomplete, so a missing figure never reads as a non-payer's. */
@@ -173,13 +262,13 @@ const NOTE_COLUMN: HeadlessPaneColumn = { key: "note", header: "Note", format: (
173
262
  const YIELD_BASIS_COLUMN: HeadlessPaneColumn = { key: "yieldBasis", header: "Yield basis", format: (value) => typeof value === "string" ? value : "",
174
263
  description: "How many payments the trailing yield counts when a regular payer's year holds fewer than its cadence pays (a gap in its ex-dates)." };
175
264
 
176
- /** `fn DVD A B C`: one table of every symbol, ranked by trailing yield. */
177
- export function projectDividendRanking(entries: readonly DividendRankingEntry[], now = new Date()): HeadlessBundleResult {
178
- const rows = rankDividendEntries(entries, now);
179
- const bonds = entries.some(isBondEntry);
265
+ /** `fn DVD A B C`: one table of every symbol, ranked by trailing yield; with `--tax-rate`, each fund's bond and tax columns. */
266
+ export function projectDividendRanking(entries: readonly DividendRankingEntry[], now = new Date(), tax: RankingTaxOptions | null = null): HeadlessBundleResult {
267
+ const rows = rankDividendEntries(entries, now, tax);
268
+ const bonds = !!tax || entries.some(isBondEntry);
180
269
  // A failed read, or one without its cash history or summary, is as incomplete as single-ticker DVD says it is.
181
270
  const incomplete = entries.flatMap((entry) => {
182
- const reason = incompleteReason(entry);
271
+ const reason = incompleteReason(entry, !!tax);
183
272
  return reason ? [{ symbol: entry.symbol, reason }] : [];
184
273
  });
185
274
  return {
@@ -190,7 +279,8 @@ export function projectDividendRanking(entries: readonly DividendRankingEntry[],
190
279
  } : {}),
191
280
  sections: [{
192
281
  title: `Ranked by trailing yield; payout is over TTM diluted EPS${bonds ? `; a bond fund's yields are distribution yields, ${NOT_SEC_YIELD}` : ""}`,
193
- columns: [...rankingColumns(bonds), ...incomplete.length > 0 ? [NOTE_COLUMN] : [], ...rows.some((row) => row.yieldBasis) ? [YIELD_BASIS_COLUMN] : []],
282
+ columns: [...rankingColumns(bonds, !!tax), ...rows.some((row) => row.note) ? [NOTE_COLUMN] : [], ...rows.some((row) => row.yieldBasis) ? [YIELD_BASIS_COLUMN] : [],
283
+ ...tax && rows.some((row) => row.taxNote) ? [TAX_NOTE_COLUMN] : []],
194
284
  rows,
195
285
  // Every figure is a percent; each exported row names its ticker and the time of the price its yields are over.
196
286
  unit: "pct",
@@ -205,6 +295,11 @@ export function projectDividendRanking(entries: readonly DividendRankingEntry[],
205
295
  growthMethod: "Trailing twelve-month cash per share now against one and three years before; 3Y is a compound annual rate.",
206
296
  payDateMethod: "Pay date of the next declared distribution; past distributions carry ex-dates only.",
207
297
  ...bonds ? { secYieldMethod: `A bond fund's 30-day SEC yield as its sponsor publishes it, dated by secYieldAsOf, as a ratio like the other yields; its trailingYield and forwardYield are distribution yields, ${NOT_SEC_YIELD}.` } : {},
298
+ ...tax ? {
299
+ taxRates: tax.rates,
300
+ taxEquivalentMethod: "A muni fund's SEC yield (else its distribution yield) / (1 - (federal rate + the state rate for a single-state fund of --state)), as a ratio; blank for a taxable fund.",
301
+ muniTreasuryRatioMethod: "A muni fund's yield over the Treasury par yield at the tenor nearest its sponsor's duration (treasuryTenor), from GC's curve.",
302
+ } : {},
208
303
  },
209
304
  };
210
305
  }
@@ -11,6 +11,8 @@ export interface DividendPayment {
11
11
  type: "cash" | "special" | "stock" | "unknown";
12
12
  /** The amount as the company declared it, in another currency than `currency` (BP's dollars beside the pence its London line paid). */
13
13
  declared?: { amount: number; currency: string };
14
+ /** Who published it when not the listing's history: the fund's sponsor (DividendAction.source). */
15
+ source?: { publisher: string; url: string };
14
16
  }
15
17
 
16
18
  /** A short year a growth figure would compare: its payments, and the day it ends (absent for the trailing year). */