@bicharts/chart-host 0.6.99 → 0.6.103

package/dist/types/exportTable.d.ts

@@ -0,0 +1,100 @@
+/** The kind of value one exported column holds. Anything that is not a number, a date or a yes/no is text. */
+export type ExportColumnType = "text" | "number" | "date" | "boolean";
+/** One exported column, in the order the reader sees it. */
+export interface ExportColumn {
+    /** The header, as the reader sees it. */
+    name: string;
+    type: ExportColumnType;
+    /** The d3-format specifier the chart prints this number with (a number column only). Wins over modelFormat. */
+    d3Format?: string | null;
+    /** The data model's own number format (an Excel / Power BI format string), used when there is no d3Format. */
+    modelFormat?: string | null;
+}
+/** One cell's value. A blank (null, undefined, "" or a value its column's type cannot read) is an empty cell. */
+export type ExportCell = string | number | boolean | Date | null | undefined;
+/** What a chart hands out: the visible columns in display order, and the rows in display order. */
+export interface ExportTable {
+    /** Names the file and the worksheet. Absent: "table". */
+    title?: string | null;
+    columns: ExportColumn[];
+    rows: ExportCell[][];
+}
+export type ExportFormat = "csv" | "xlsx";
+/** The formats a chart may offer, best first. */
+export declare const EXPORT_FORMATS: readonly ExportFormat[];
+/** A finished file, as a host's file service receives it. */
+export interface ExportFile {
+    /** A file name with its extension, safe on every file system. */
+    name: string;
+    format: ExportFormat;
+    mime: string;
+    bytes: Uint8Array;
+    /** The same content as text, for a text format (the CSV); absent for a binary one. */
+    text?: string;
+    /**
+     * The table the file was written from, for a host that keeps it its own way (a spreadsheet add-in that must give
+     * the new sheet a name the open workbook does not already use, and so writes the workbook again under that name).
+     */
+    table: ExportTable;
+}
+export declare const XLSX_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+export declare const CSV_MIME = "text/csv";
+/**
+ * Excel's day number for a UTC time: days since 1899-12-30, the fraction being the time of day. Excel counts a
+ * 29 February 1900 that never was (day 60), so a day before 1 March 1900 is one lower to read back as itself.
+ */
+export declare function excelSerial(t: number): number;
+/**
+ * The Excel number format for an exported number column, or null for General. `values` are the column's numbers, so a
+ * format that shows "up to" some decimals shows as many as the data has.
+ */
+export declare function excelNumberFormat(col: Pick<ExportColumn, "d3Format" | "modelFormat">, values?: readonly number[]): string | null;
+/**
+ * The table as CSV text: a header row, then one line per row, CRLF between lines, RFC 4180 quoting. A number is its
+ * plain value (a point for the decimal, no grouping), a date its ISO day (and time, when the column has one), a yes/no
+ * TRUE or FALSE. The text starts with a byte-order mark so a spreadsheet reads it as UTF-8.
+ */
+export declare function tableToCsv(table: ExportTable): string;
+/** A1-style column letters for a 0-based column index. */
+export declare function columnLetters(ci: number): string;
+/** A worksheet name Excel accepts: at most 31 characters, none of []:*?/\, not blank, not starting or ending with '. */
+export declare function sheetName(title: string | null | undefined): string;
+/** A file name safe on every file system, from a title: no reserved characters, at most 80 characters. */
+export declare function exportFileName(title: string | null | undefined, format: ExportFormat): string;
+/**
+ * The table as an .xlsx workbook's bytes. One worksheet named after the title: a bold header row, frozen, with filter
+ * buttons; typed cells (numbers with their format where Excel can carry it, dates as dates, TRUE/FALSE); each column as
+ * wide as its widest value, within limits. Rows past Excel's limit are left out (a sheet holds 1,048,576 rows).
+ */
+export declare function tableToXlsx(table: ExportTable): Uint8Array;
+/**
+ * A ZIP archive of the given files, stored without compression (method 0) - every reader of a workbook accepts it. The
+ * entries carry a fixed timestamp, so the same table always gives the same bytes.
+ */
+export declare function zipStored(files: Array<[string, string | Uint8Array]>): Uint8Array;
+/** Builds the finished file for a table in one of the export formats. */
+export declare function buildExportFile(table: ExportTable, format: ExportFormat): ExportFile;
+/** Base64 of a file's bytes, for a host whose file service takes binary content as base64 text. */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/** A host's file service: saves a finished file the host's own way. False, a throw or a rejection means it did not. */
+export type SaveFileService = (file: ExportFile) => boolean | void | Promise<boolean | void>;
+/** The chart-facing export: what options.exportTable is. Resolves true when the host saved the file. */
+export type ExportTableService = (table: ExportTable, format: ExportFormat) => Promise<boolean>;
+/**
+ * The formats a host's file service takes, best first: the host's own list (when it names one) kept to the formats
+ * this module writes, in EXPORT_FORMATS order, without repeats. Absent or not a list: every format. An empty result
+ * means the host can save none of them, so it gets no export.
+ */
+export declare function exportFormatsFor(hostFormats?: readonly unknown[] | null): ExportFormat[];
+/**
+ * Builds the chart-facing exportTable from a host's file service. Never throws and never rejects: a table that cannot
+ * be written, a format the host does not take, or a host that refuses, resolves false, and the chart says the export
+ * did not happen.
+ */
+export declare function exportTableService(save: SaveFileService, formats?: readonly ExportFormat[]): ExportTableService;
+/**
+ * A file service for a page in a browser: the file downloads through a link the page never shows. For a React or
+ * Blazor page, a Fabric App, or any page whose browser allows downloads; a sandboxed frame without the
+ * "allow-downloads" permission silently drops it, so a host in one passes its own service (or none) instead.
+ */
+export declare function browserSaveFile(doc?: Document): SaveFileService;

package/dist/types/host.d.ts

@@ -257,8 +257,9 @@ export interface ChartHostConfig {
     /**
      * NOTES ON MARKS. Each annotation names a key - a value in a column of this chart's data, such as a
      * country code - and the host draws a badge on that key's mark after every render, wherever a filter,
-     * a re-query or a zoom has put it. Keyed by value, never by row position. Change them with
-     * setAnnotations; none (the default) draws nothing.
+     * a re-query, a zoom or a scroll has put it. A chart that declares NOTE_STYLE_ATTR="dot" gets a small
+     * dot at a fixed spot instead, the label in its tooltip. Keyed by value, never by row position. Change
+     * them with setAnnotations; none (the default) draws nothing.
      */
     annotations?: MarkAnnotation[];
     /** A badge was clicked. The mark beneath is not selected. */

package/dist/types/hostLinks.d.ts

@@ -0,0 +1,11 @@
+/** The clipboard half a host can supply: navigator.clipboard, or anything with the same writeText. */
+export interface ClipboardLike {
+    writeText?: (text: string) => Promise<void>;
+}
+/** The two services, ready to spread into a host's render options: each is absent when the host supplied nothing for it. */
+export interface HostLinkServices {
+    openUrl?: (url: string) => void;
+    copyText?: (text: string) => boolean | Promise<boolean>;
+}
+/** Builds openUrl and copyText from a host's own opener and clipboard. */
+export declare function hostLinkServices(open: ((url: string) => void) | undefined | null, clipboard: ClipboardLike | undefined | null): HostLinkServices;

package/dist/types/index.d.ts

@@ -1,5 +1,7 @@
-export { HOST_CONTRACT_VERSION, GEO_POINT_PRECISIONS, MARK_CLASS, LEGEND_MARK_CLASS, AXIS_FILTER_CLASS, ROW_IDX_ATTR, LIFT_SELECTED_CLASS, CONTROL_CLASS, NO_ROW_MARKS_ATTR, SELECTION_RULE_ATTR, SELECTION_RULE_CLICKED_MARKS, MARK_KEY_ATTR, CONTAINER_SLOT_CLICKED_MARKS, SNAPSHOT_SVG_ATTR, XFILTER_REFRESH_EVENT, CONTAINER_SLOT_ANIM_STOP, CONTAINER_SLOT_XF_CLEAR, CONTAINER_SLOT_INITIAL_XF_MARK, CONTAINER_SLOT_UI_STATE, CONTAINER_SLOT_SCROLL, VIEW_ONLY_UI_STATE_KEYS, withoutViewOnlyKeys, HOST_CONTAINER_CLASS, SELECTION_ACTIVE_CLASS, MARK_SELECTED_CLASS, ACTIVE_TICK_CLASS, DIM_OPACITY_VAR, DIM_OPACITY_DEFAULT, DIM_OPACITY_MIN, chartOwnsTimeline, periodTickSuppressesFeedback, ANIM_PLAY_SPEED_DEFAULT, ANIM_PLAY_SPEED_MIN, ANIM_PLAY_SPEED_MAX, ANIM_LOOP_DELAY_DEFAULT, ANIM_LOOP_DELAY_MIN, ANIM_MAX_IDEAL_FRAMES_DEFAULT, ANIM_MAX_IDEAL_FRAMES_MIN, ANIM_MAX_IDEAL_FRAMES_MAX, ANIMATION_OPTION_KEYS, COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT, COLOR_SCALE_SELF_CLAMP_PCT_MIN, COLOR_SCALE_SELF_CLAMP_PCT_MAX, FLIP_MODE_DEFAULT, FLIP_INTERVAL_MIN_MS, FLIP_INTERVAL_MAX_MS, FLIP_DIRECTION_DEFAULT, APPROXIMATE_POSITIONS_DEFAULT, VALUE_AXIS_BASELINE_DEFAULT, SEASONAL_MARKERS_DEFAULT, MAX_MAP_POINTS_DEFAULT, type GeoPointPrecision, type GeoMapKind, type TimelineStyle, type FlipMode, type FlipDirection, type ApproximatePositions, type ValueAxisBaseline, type SeasonalMarkers, type ColorScaleScope, type RenderOptions, type ViewStateProvider, type ChartControlChange, type XfilterRefreshDetail, } from "./contract";
+export { HOST_CONTRACT_VERSION, GEO_POINT_PRECISIONS, MARK_CLASS, LEGEND_MARK_CLASS, AXIS_FILTER_CLASS, ROW_IDX_ATTR, LIFT_SELECTED_CLASS, CONTROL_CLASS, NO_ROW_MARKS_ATTR, NOTE_STYLE_ATTR, SELECTION_RULE_ATTR, SELECTION_RULE_CLICKED_MARKS, MARK_KEY_ATTR, CONTAINER_SLOT_CLICKED_MARKS, SNAPSHOT_SVG_ATTR, XFILTER_REFRESH_EVENT, CONTAINER_SLOT_ANIM_STOP, CONTAINER_SLOT_XF_CLEAR, CONTAINER_SLOT_INITIAL_XF_MARK, CONTAINER_SLOT_UI_STATE, CONTAINER_SLOT_SCROLL, VIEW_ONLY_UI_STATE_KEYS, withoutViewOnlyKeys, HOST_CONTAINER_CLASS, SELECTION_ACTIVE_CLASS, MARK_SELECTED_CLASS, ACTIVE_TICK_CLASS, DIM_OPACITY_VAR, DIM_OPACITY_DEFAULT, DIM_OPACITY_MIN, chartOwnsTimeline, periodTickSuppressesFeedback, ANIM_PLAY_SPEED_DEFAULT, ANIM_PLAY_SPEED_MIN, ANIM_PLAY_SPEED_MAX, ANIM_LOOP_DELAY_DEFAULT, ANIM_LOOP_DELAY_MIN, ANIM_MAX_IDEAL_FRAMES_DEFAULT, ANIM_MAX_IDEAL_FRAMES_MIN, ANIM_MAX_IDEAL_FRAMES_MAX, ANIMATION_OPTION_KEYS, COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT, COLOR_SCALE_SELF_CLAMP_PCT_MIN, COLOR_SCALE_SELF_CLAMP_PCT_MAX, FLIP_MODE_DEFAULT, FLIP_INTERVAL_MIN_MS, FLIP_INTERVAL_MAX_MS, FLIP_DIRECTION_DEFAULT, APPROXIMATE_POSITIONS_DEFAULT, VALUE_AXIS_BASELINE_DEFAULT, SEASONAL_MARKERS_DEFAULT, MAX_MAP_POINTS_DEFAULT, type GeoPointPrecision, type GeoMapKind, type TimelineStyle, type FlipMode, type FlipDirection, type ApproximatePositions, type ValueAxisBaseline, type SeasonalMarkers, type ColorScaleScope, type RenderOptions, type ViewStateProvider, type ChartControlChange, type XfilterRefreshDetail, } from "./contract";
 export { resolveOptions, type ResolveOptionsInput } from "./defaults";
+export { hostLinkServices, type HostLinkServices, type ClipboardLike } from "./hostLinks";
+export { tableToCsv, tableToXlsx, buildExportFile, exportFileName, sheetName as exportSheetName, excelNumberFormat, excelSerial, bytesToBase64, exportFormatsFor, exportTableService, browserSaveFile, EXPORT_FORMATS, XLSX_MIME, CSV_MIME, type ExportTable, type ExportColumn, type ExportColumnType, type ExportCell, type ExportFormat, type ExportFile, type SaveFileService, type ExportTableService, } from "./exportTable";
 export { OPTIONS_VOCABULARY, LIVE_OPTION_KEYS, MAX_MAP_POINTS_MIN, MAX_MAP_POINTS_MAX, LIMIT_COUNT_MAX, wireLimitCount, codeReadsOption, type OptionVocabularyEntry, type OptionTiming, type OptionWire, type OptionKey, } from "./optionsVocabulary";
 export { loadGeo, geoFromCache, registerGeo, registerGeoAsset, geoAssetFor, clearGeoCache, type GeoAssetName, } from "./geoLazy";
 /** REPLACE the bundled city gazetteer with another packed table. Rarely needed — see the
@@ -21,6 +23,7 @@ export { captureSvgSnapshot, svgToDataUrl, svgNaturalSize, rasterizeSvgToPngData
 export { shouldReview, buildReviewWire, bareBase64, actionFor, type ReviewGate, type ReviewWire, type ReviewVerdict, type ReviewAction } from "./review";
 export { askApplyImprovements, type ReviewDialogOptions, type ReviewDialogText } from "./reviewDialog";
 export { mountProductFeedbackBox, normaliseProductFeedbackText, productFeedbackSendable, buildProductFeedbackPayload, PRODUCT_FEEDBACK_MAX_CHARS, PRODUCT_FEEDBACK_MIN_CHARS, type ProductFeedbackBox, type ProductFeedbackBoxOptions, type ProductFeedbackText, type ProductFeedbackSendResult, type ProductFeedbackPayload, type ProductFeedbackIdentity, type ProductFeedbackHost, } from "./productFeedback";
+export { mountShareRateLine, shareRateLineModel, type ShareRateLine, type ShareRateLineOptions, type ShareRateText, type ShareRateModel, type ShareLink, type ShareAskWire, type ShareTargetWire, } from "./shareRate";
 export { qualifyGroupHeadingFor, newQualifyGroupState, type QualifyGroupRow, type QualifyGroupState, type QualifyGroupHeading, orderRefusalsForDisplay, refusalIsSelectable, hasRefusalsToShow, qualifyRefusalHeadingFor, newQualifyRefusalGroupState, qualifyRefusalReason, QUALIFY_REFUSAL_UNSPECIFIED, refusalIsTileBound, QUALIFY_TILE_REFUSAL_CODES, QUALIFY_TOO_SMALL_HEADING, type QualifyRefusalRow, type QualifyRefusalGroupState, type QualifyRefusalHeading, } from "./qualifyGroups";
 export { qualifyPick, qualifyAuto, qualifyCancel, launchGenerates, launchFavorStyle, chooserFitsViewport, shouldOpenChooserOnGenerate, shouldOpenInlineChooserOnGenerate, canConfirmLaunch, confirmLaunch, qualifyFailureFallsOpen, CHOOSER_MIN_WIDTH_PX, CHOOSER_MIN_HEIGHT_PX, type QualifyLaunchOutcome, type ChooserGateInput, } from "./qualifyLaunch";
 export { normalizeFilterTerm, filterQualifyRows, readQualifyChartRow, readQualifyRefusalRow, DEFAULT_FILTER_MATCH_STYLE, filterMatchStyleOf, type FilterMatchStyle, filterFitsChooser, listNeedsFilter, qualifyFilterGate, inlineFilterGate, FILTER_MIN_TERM_CHARS, FILTER_ROW_PX, FILTER_MIN_WIDTH_PX, FILTER_MIN_HEIGHT_PX, INLINE_FILTER_MIN_ROWS, computeQualifyFilterView, qualifyFilterCountText, type QualifyFilterTier, type QualifyFilterResult, type QualifyFilterRead, type QualifyFilterGateReason, type QualifyFilterGateInput, type QualifyFilterRow, type QualifyFilterGroup, type QualifyFilterView, type QualifyFilterNoteKind, } from "./qualifyFilter";

package/dist/types/shareRate.d.ts

@@ -0,0 +1,90 @@
+/** The block as the service sends it. Either casing is accepted, because the hosts' status calls serialise differently.
+ *  shape-core types the same block on the status answer (GetLicenseStatusResult.shareAsk); it is restated here because
+ *  this package's published declarations import nothing they do not ship, and a typecheck test holds the two equal. */
+export interface ShareAskWire {
+    productUrl?: string;
+    ProductUrl?: string;
+    rateUrl?: string;
+    RateUrl?: string;
+    targets?: ShareTargetWire[];
+    Targets?: ShareTargetWire[];
+}
+export interface ShareTargetWire {
+    id?: string;
+    Id?: string;
+    label?: string;
+    Label?: string;
+    url?: string;
+    Url?: string;
+}
+export interface ShareLink {
+    /** Short network id ("li", "fb", "x"); a host's click counter names it. */
+    id: string;
+    label: string;
+    url: string;
+}
+export interface ShareRateModel {
+    share: ShareLink[];
+    /** The listing to rate; null when the block had none worth drawing. */
+    rateUrl: string | null;
+}
+/**
+ * The links to draw for a service block, or null to draw nothing. Absent block, nothing https, or nothing usable: null.
+ * A target whose URL is not https, whose id is malformed or repeated, or which has no label is dropped; the order the
+ * service sent is kept.
+ */
+export declare function shareRateLineModel(ask: ShareAskWire | null | undefined): ShareRateModel | null;
+/** The words a reader sees. Hosts localize; every field has an English default. Network names come from the service. */
+export interface ShareRateText {
+    /** Before the network links: "Like it? Share it on". */
+    lead?: string;
+    /** Between the network links. */
+    separator?: string;
+    /** Between the share links and the rate link: ", or". */
+    or?: string;
+    /** The rate link after share links: "rate it on AppSource". */
+    rate?: string;
+    /** The rate link when there is nothing to share: "Like it? Rate it on AppSource". */
+    rateAlone?: string;
+    /** After the links: "Your ratings and feedback encourage us to do more." */
+    note?: string;
+    /** Menu layout, first: "Thanks for rating it." */
+    thanks?: string;
+    /** Menu layout, the rate link: "Rate it on AppSource too". */
+    rateToo?: string;
+    /** Menu layout, the toggle that reveals the networks: "Share it". */
+    shareMenu?: string;
+}
+export interface ShareRateLineOptions {
+    /** The service's block, as it arrived. Nothing is drawn when it yields no links. */
+    ask: ShareAskWire | null | undefined;
+    /** Opens a URL through the host's own door. The line never navigates by itself. */
+    open: (url: string) => void;
+    text?: ShareRateText;
+    /** Added to the wrapper so the host can skin it. */
+    className?: string;
+    /** "inline" (the landing line: the networks named in the sentence) or "menu" (after a vote: a short thank-you, the
+     *  rate link, and a "Share it" toggle that reveals the networks). The links, their order and the click contract are
+     *  the same either way. */
+    layout?: "inline" | "menu";
+    /** Menu layout: the "Share it" toggle opened the networks. */
+    onMenu?: () => void;
+    /** Called once, when the line is mounted - the host's "shown" counter. A host that folds the line away counts it
+     *  itself instead and passes nothing here. */
+    onShown?: () => void;
+    /** A network link was clicked. */
+    onShare?: (id: string) => void;
+    /** The rate link was clicked. */
+    onRate?: () => void;
+}
+export interface ShareRateLine {
+    element: HTMLElement;
+    destroy(): void;
+}
+/**
+ * Draw the line inside `container`, or return null (and draw nothing) when the block yields no links. The wrapper carries
+ * `bic-share-rate`; network links `bic-share-rate-share` with `data-target`; the rate link `bic-share-rate-rate`; the
+ * note `bic-share-rate-note`. Every link carries its real href (so it reads as a link, and a reader can copy it), but a
+ * click is cancelled and handed to `open`.
+ */
+export declare function mountShareRateLine(container: HTMLElement, opts: ShareRateLineOptions): ShareRateLine | null;

package/dist/zoom-memory.mjs

@@ -1,7 +1,7 @@
 /*! @bicharts/chart-host — Apache-2.0. Bundled reference data: GeoNames (https://www.geonames.org/) CC BY 4.0; Natural Earth and US Census/TIGER (public domain). Full text: NOTICE in this package. */
 import {
   K
-} from "./chunk-W5L6OH25.mjs";
+} from "./chunk-CNT3QA3R.mjs";
 import "./chunk-GHODWOAL.mjs";
 
 // src/zoomMemory/zoomMemory.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-host",
-  "version": "0.6.99",
+  "version": "0.6.103",
   "description": "Run a BIC-generated D3 chart in any web host: compiles the generated render() function, applies the shared option defaults, resolves mark clicks (through tooltip overlays), owns the selection affordance, and translates row indices between cross-filtered charts. The same contract the BIC Power BI visual implements, minus Power BI. React bindings at @bicharts/chart-host/react.",
   "license": "Apache-2.0",
   "type": "module",