pivotkit-element 0.0.0-stage → 0.2.0

package/types/element.d.ts

@@ -0,0 +1,428 @@
+/// <reference path="./global.d.ts" />
+import { EVENTS } from "./events.js";
+export { EVENTS };
+export type PivotView = {
+    rows?: string[];
+    cols?: string[];
+    values?: Array<{
+        field?: string | null;
+        agg?: string;
+        format?: string | null;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+};
+export type Template = {
+    /**
+     * shown in the menu; default the view file's name
+     */
+    name?: string;
+    view?: PivotView;
+    /**
+     * a view file ("pivotkit-view") instead of `view`
+     */
+    file?: Record<string, unknown> | string;
+    /**
+     * the group: "Shared views" or "My views"; default "user"
+     * for a deletable entry, else "shared"
+     */
+    scope?: "shared" | "user";
+    /**
+     * offers a delete button (pivot-template-delete)
+     */
+    deletable?: boolean;
+};
+export type FieldDefaults = {
+    /**
+     * aggregator of a new value, when it fits the field's type ("average" for durations)
+     */
+    agg?: string;
+    /**
+     * a format of pivotkit-core ("duration:h", "currency:EUR") for a new value,
+     * and for the field's own numbers in the drill-down unless `drillFormat` is set
+     */
+    format?: string;
+    /**
+     * the format of the field's values in the drill-down ("text": an identifier as it is)
+     */
+    drillFormat?: string;
+    /**
+     * the field's own order of items on Rows or Columns
+     */
+    order?: Array<string | number | boolean | null>;
+    /**
+     * the name shown for the field; views keep the field's own name
+     */
+    label?: string;
+    /**
+     * plain text shown with an "i" next to the field, in its menu and on its headers
+     */
+    description?: string;
+    /**
+     * an https link shown as "Learn more" with the description
+     */
+    href?: string;
+    /**
+     * the type the field's column is read as
+     */
+    type?: "string" | "number" | "date" | "boolean";
+};
+export type TipDismiss = {
+    /**
+     * the tip dismissed, "*" when every tip was switched off, null when tips came back
+     */
+    id: string | null;
+    /**
+     * every dismissed id now: set it as `dismissedTips` next time
+     */
+    dismissed: string[];
+};
+export type CellClick = {
+    /**
+     * key path of the row ([] is the grand total)
+     */
+    row: any[];
+    /**
+     * key path of the column
+     */
+    col: any[];
+    /**
+     * the raw value of the cell
+     */
+    value: unknown;
+    valueIndex: number | undefined;
+    /**
+     * the value as shown
+     */
+    text: string | undefined;
+    /**
+     * source rows behind the cell
+     */
+    count: number;
+    /**
+     * the first `drillDownLimit` of them: the host's row objects
+     */
+    rows: object[];
+};
+export type ExportFile = {
+    /**
+     *   "json": the view file (Views, "Download view"); "copy-table", "copy-json": Export → Copy table,
+     *   Copy data as JSON; "drill-*": the drill-down panel's Export menu
+     */
+    kind: "xlsx" | "csv" | "png" | "json" | "copy-table" | "copy-json" | "drill-copy" | "drill-json" | "drill-csv" | "drill-xlsx";
+    /**
+     * with the extension ("pivot.xlsx"); for a copy the name it would have as a file
+     */
+    fileName: string;
+    blob: Blob;
+    /**
+     * a copy's text
+     */
+    text?: string;
+    /**
+     * a drill-down export: the rows it holds and the rows behind the value
+     */
+    rows?: {
+        shown: number;
+        count: number;
+    };
+};
+export type TemplateSave = {
+    name: string;
+    /**
+     * the normalized view to store
+     */
+    view: PivotView;
+    /**
+     * where it goes: "user", the user's own views
+     */
+    scope: "shared" | "user";
+    /**
+     * call it in the listener with the promise of the
+     * host's save: "Saved" shows when it resolves, the error's message when it rejects
+     */
+    respondWith: (result: unknown) => void;
+};
+export type TemplateDelete = {
+    name: string;
+    /**
+     * the entry's group
+     */
+    scope: "shared" | "user";
+    /**
+     * as for pivot-template-save: the entry goes when
+     * the promise resolves (the host then sets `templates` without it)
+     */
+    respondWith: (result: unknown) => void;
+};
+export type TemplatePublish = {
+    name: string;
+    /**
+     * the user's view to publish as a shared view
+     */
+    view: PivotView;
+    /**
+     * as for pivot-template-save: "Published" shows
+     * when the promise resolves (the host then sets `templates` with the new shared entry)
+     */
+    respondWith: (result: unknown) => void;
+};
+export type SourceEntry = {
+    id: string;
+    name?: string;
+};
+export type SourceSwitch = {
+    /**
+     * the entry of `sources`
+     */
+    source: SourceEntry;
+    /**
+     * the view as the file has it (made for that data, not normalized here)
+     */
+    view: PivotView;
+    /**
+     * the view's name in the file
+     */
+    name?: string;
+};
+/**
+ * A view of pivotkit-core (the report template): plain JSON with field names only, normalized against
+ * the data by the report; anything unknown is dropped. The full type is pivotkit-core's `View`.
+ * @typedef {{ rows?: string[], cols?: string[], values?: Array<{ field?: string | null, agg?: string, format?: string | null, [key: string]: unknown }>, [key: string]: unknown }} PivotView
+ */
+/**
+ * @typedef {object} Template  a saved view of the Views menu: a view, or a view file (its text or object)
+ * @property {string} [name]  shown in the menu; default the view file's name
+ * @property {PivotView} [view]
+ * @property {Record<string, unknown> | string} [file]  a view file ("pivotkit-view") instead of `view`
+ * @property {"shared" | "user"} [scope]  the group: "Shared views" or "My views"; default "user"
+ *   for a deletable entry, else "shared"
+ * @property {boolean} [deletable]  offers a delete button (pivot-template-delete)
+ */
+/**
+ * @typedef {object} FieldDefaults  the host's settings for a field, as pivotkit-react's
+ * @property {string} [agg]  aggregator of a new value, when it fits the field's type ("average" for durations)
+ * @property {string} [format]  a format of pivotkit-core ("duration:h", "currency:EUR") for a new value,
+ *   and for the field's own numbers in the drill-down unless `drillFormat` is set
+ * @property {string} [drillFormat]  the format of the field's values in the drill-down ("text": an identifier as it is)
+ * @property {Array<string | number | boolean | null>} [order]  the field's own order of items on Rows or Columns
+ * @property {string} [label]  the name shown for the field; views keep the field's own name
+ * @property {string} [description]  plain text shown with an "i" next to the field, in its menu and on its headers
+ * @property {string} [href]  an https link shown as "Learn more" with the description
+ * @property {"string" | "number" | "date" | "boolean"} [type]  the type the field's column is read as
+ */
+/**
+ * @typedef {object} TipDismiss  the detail of pivot-tip-dismiss
+ * @property {string | null} id  the tip dismissed, "*" when every tip was switched off, null when tips came back
+ * @property {string[]} dismissed  every dismissed id now: set it as `dismissedTips` next time
+ */
+/**
+ * @typedef {object} CellClick  the detail of pivot-cell-click
+ * @property {any[]} row  key path of the row ([] is the grand total)
+ * @property {any[]} col  key path of the column
+ * @property {unknown} value  the raw value of the cell
+ * @property {number | undefined} valueIndex
+ * @property {string | undefined} text  the value as shown
+ * @property {number} count  source rows behind the cell
+ * @property {object[]} rows  the first `drillDownLimit` of them: the host's row objects
+ */
+/**
+ * @typedef {object} ExportFile  the detail of pivot-export: a file before its download, or a text
+ *   before it goes on the clipboard
+ * @property {"xlsx" | "csv" | "png" | "json" | "copy-table" | "copy-json" | "drill-copy" | "drill-json" | "drill-csv" | "drill-xlsx"} kind
+ *   "json": the view file (Views, "Download view"); "copy-table", "copy-json": Export → Copy table,
+ *   Copy data as JSON; "drill-*": the drill-down panel's Export menu
+ * @property {string} fileName  with the extension ("pivot.xlsx"); for a copy the name it would have as a file
+ * @property {Blob} blob
+ * @property {string} [text]  a copy's text
+ * @property {{ shown: number, count: number }} [rows]  a drill-down export: the rows it holds and the rows behind the value
+ */
+/**
+ * @typedef {object} TemplateSave  the detail of pivot-template-save
+ * @property {string} name
+ * @property {PivotView} view  the normalized view to store
+ * @property {"shared" | "user"} scope  where it goes: "user", the user's own views
+ * @property {(result: unknown) => void} respondWith  call it in the listener with the promise of the
+ *   host's save: "Saved" shows when it resolves, the error's message when it rejects
+ */
+/**
+ * @typedef {object} TemplateDelete  the detail of pivot-template-delete
+ * @property {string} name
+ * @property {"shared" | "user"} scope  the entry's group
+ * @property {(result: unknown) => void} respondWith  as for pivot-template-save: the entry goes when
+ *   the promise resolves (the host then sets `templates` without it)
+ */
+/**
+ * @typedef {object} TemplatePublish  the detail of pivot-template-publish (with `can-publish`)
+ * @property {string} name
+ * @property {PivotView} view  the user's view to publish as a shared view
+ * @property {(result: unknown) => void} respondWith  as for pivot-template-save: "Published" shows
+ *   when the promise resolves (the host then sets `templates` with the new shared entry)
+ */
+/**
+ * @typedef {object} SourceEntry  data the page can show (`sources`), as the report names it
+ * @property {string} id
+ * @property {string} [name]
+ */
+/**
+ * @typedef {object} SourceSwitch  the detail of pivot-source-switch: the user chose to switch to the
+ *   data a loaded view was made for; show that data and set `defaultView` to `view`
+ * @property {SourceEntry} source  the entry of `sources`
+ * @property {PivotView} view  the view as the file has it (made for that data, not normalized here)
+ * @property {string} [name]  the view's name in the file
+ */
+/** The tag the package defines. */
+export declare const TAG = "pivot-report";
+declare const Base: typeof HTMLElement;
+export declare class PivotReportElement extends Base {
+    #private;
+    static get observedAttributes(): string[];
+    constructor();
+    /** The version of pivotkit-element this class comes from (two copies on a page tell each other apart). */
+    static get version(): string;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * @param {string} name
+     * @param {string | null} _old
+     * @param {string | null} value
+     */
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    /** Numbers, dates, sorting and the language of the labels ("de-DE"); else the element's `lang`, else "en-US". */
+    get locale(): string | undefined;
+    set locale(value: string | undefined);
+    /** "auto" (default) follows the nearest data-theme above the report, then the system. */
+    get theme(): "auto" | "light" | "dark";
+    set theme(value: "auto" | "light" | "dark");
+    /** The report's height: a number of pixels or a CSS length (default 640). */
+    get height(): number | string | undefined;
+    set height(value: number | string | undefined);
+    /** The zone `data` is encoded in (default "UTC"). */
+    get timeZone(): string | undefined;
+    set timeZone(value: string | undefined);
+    /** Name of exported files without extension (default "pivot"). */
+    get fileName(): string | undefined;
+    set fileName(value: string | undefined);
+    /** The name of the report's region landmark (default the labels' `report`, "Pivot report"). */
+    get label(): string | undefined;
+    set label(value: string | undefined);
+    /** The panel with the rows behind a clicked value (default true; attribute drill-down="false"). */
+    get drillDown(): boolean;
+    set drillDown(value: boolean);
+    /** Rows passed to the panel and to pivot-cell-click (default 1000). */
+    get drillDownLimit(): number | undefined;
+    set drillDownLimit(value: number | undefined);
+    /** Offers "Save current view" in the Views menu; a save is a pivot-template-save event. */
+    get saveTemplates(): boolean;
+    set saveTemplates(value: boolean);
+    /**
+     * "browser": the user's own views ("My views") are kept in this browser's localStorage under the
+     * storage key, when the page does not take the saves (save-templates).
+     */
+    get templateStore(): string | undefined;
+    set templateStore(value: string | undefined);
+    /**
+     * "open" or "collapsed": the field list of a wide report open or collapsed to a rail; without it
+     * the user's choice (remembered with the tips) decides.
+     */
+    get fieldList(): string | undefined;
+    set fieldList(value: string | undefined);
+    /** Offers "Publish as shared view" on the user's views; a publish is a pivot-template-publish event. */
+    get canPublish(): boolean;
+    set canPublish(value: boolean);
+    /** "on" (default), "off", or a comma-separated list of the tip ids allowed. */
+    get tips(): string | undefined;
+    set tips(value: string | undefined);
+    /**
+     * Remembers dismissed tips in localStorage under this key (and, with template-store="browser",
+     * the user's views); give each report on a page its own.
+     */
+    get storageKey(): string | undefined;
+    set storageKey(value: string | undefined);
+    /** "Copy link" and shared links: true for the page's address, or a base URL (attribute share-link). */
+    get shareLink(): boolean | string | undefined;
+    set shareLink(value: boolean | string | undefined);
+    /** "session": the view is kept for this tab (sessionStorage, per storage-key). */
+    get persistView(): "session" | undefined;
+    set persistView(value: "session" | undefined);
+    /** "on" or "off" decides the "i" of the field descriptions; unset, the user switches it in Options. */
+    get fieldInfo(): "on" | "off" | undefined;
+    set fieldInfo(value: "on" | "off" | undefined);
+    /** "on" or "off" decides the "i" next to the zone titles; unset, the user switches it in Options. */
+    get zoneInfo(): "on" | "off" | undefined;
+    set zoneInfo(value: "on" | "off" | undefined);
+    /** "on" or "off" decides the "i" next to the settings ("Show explanations"); unset, the user switches it. */
+    get settingInfo(): "on" | "off" | undefined;
+    set settingInfo(value: "on" | "off" | undefined);
+    /** The id of the data shown ("sales"): it goes into the view files and links, a view for another source asks first. */
+    get sourceId(): string | undefined;
+    set sourceId(value: string | undefined);
+    /**
+     * The `$schema` of the view files the report writes: a URL (a self-hosted copy of the schema), or
+     * "" to leave it out; unset, pivotkit's published schema.
+     */
+    get schemaUrl(): string | undefined;
+    set schemaUrl(value: string | undefined);
+    /**
+     * "on": the report grows past its height to keep the result's least height (the page scrolls);
+     * "off": it stays inside its height and the result scrolls. Unset: "on" without a height attribute.
+     */
+    get grow(): "on" | "off" | undefined;
+    set grow(value: "on" | "off" | undefined);
+    /** The name of the data shown, for people ("Sales 2026"); with source-id. */
+    get sourceName(): string | undefined;
+    set sourceName(value: string | undefined);
+    /** The page is loading the data: the report shows its skeleton (attribute loading). */
+    get loading(): boolean;
+    set loading(value: boolean);
+    /** Controlled: the view to show; set it again from every pivot-view-change. Undefined: uncontrolled. */
+    get view(): PivotView | undefined;
+    set view(value: PivotView | undefined);
+    /**
+     * Uncontrolled: the start view. A different one (by value) starts the report again on it, with a
+     * new undo history; frameworks often set it only after the element is in the page.
+     */
+    get defaultView(): PivotView | undefined;
+    set defaultView(value: PivotView | undefined);
+    /** The rows: an array of objects; encoded once per array, or once per `dataKey`. */
+    get data(): object[] | undefined;
+    set data(value: object[] | undefined);
+    /** The identity of `data`: a new array with the same key is not encoded again. */
+    get dataKey(): string | number | undefined;
+    set dataKey(value: string | number | undefined);
+    /** The Templates menu; the first three are also offered in the empty state. */
+    get templates(): Template[] | undefined;
+    set templates(value: Template[] | undefined);
+    /** Texts merged over the locale's labels (pivotkit-react's LABELS.en has every key). */
+    get labels(): Record<string, unknown> | undefined;
+    set labels(value: Record<string, unknown> | undefined);
+    /** Per field name: the aggregator and format of a new value, display name, description, column type. */
+    get fieldDefaults(): Record<string, FieldDefaults> | undefined;
+    set fieldDefaults(value: Record<string, FieldDefaults> | undefined);
+    /** Dismissed tip ids from the page's own storage (from pivot-tip-dismiss); "*" switches every tip off. */
+    get dismissedTips(): string[] | undefined;
+    set dismissedTips(value: string[] | undefined);
+    /**
+     * Plain JSON merged over the chart's ECharts option (a font size, axis names); it wins over the
+     * view's chart settings. Functions and values that are not JSON are left out.
+     */
+    get chartOptions(): Record<string, unknown> | undefined;
+    set chartOptions(value: Record<string, unknown> | undefined);
+    /**
+     * The other data the page can show, as { id, name }: a view made for one of them offers "Switch to
+     * <name> and load" (event pivot-source-switch).
+     */
+    get sources(): SourceEntry[] | undefined;
+    set sources(value: SourceEntry[] | undefined);
+    /** pivotkit-core's limits (rows, cells, ...). */
+    get limits(): Record<string, number> | undefined;
+    set limits(value: Record<string, number> | undefined);
+}
+/**
+ * Defines the element under a tag name (default "pivot-report"). A name that is already defined is
+ * left alone, so loading the package twice does not throw; its constructor is returned, and a warning
+ * names both versions when the definition is not this copy's.
+ * @param {string} [name]
+ * @returns {CustomElementConstructor | undefined} undefined without customElements (Node)
+ */
+export declare function define(name?: string): CustomElementConstructor | undefined;

package/types/events.d.ts

@@ -0,0 +1,34 @@
+/** The event names, by what they report. */
+export declare const EVENTS: Readonly<{
+    viewChange: "pivot-view-change";
+    cellClick: "pivot-cell-click";
+    templateSave: "pivot-template-save";
+    templateDelete: "pivot-template-delete";
+    templatePublish: "pivot-template-publish";
+    export: "pivot-export";
+    tipDismiss: "pivot-tip-dismiss";
+    sourceSwitch: "pivot-source-switch";
+}>;
+/**
+ * Dispatches an event on the element.
+ * @param {EventTarget} target
+ * @param {string} type
+ * @param {object} detail
+ * @param {{ cancelable?: boolean }} [options]
+ * @returns {boolean} false when a listener called preventDefault()
+ */
+export declare function emit(target: EventTarget, type: string, detail: object, options?: {
+    cancelable?: boolean;
+}): boolean;
+/**
+ * Dispatches an event whose listener may answer with `event.detail.respondWith(value or promise)`,
+ * called while the event is dispatched (in the listener itself, not later). The returned promise
+ * settles with that answer: the report shows "Saved" (or removes the template) when it resolves, and
+ * an error with its message when it rejects. Without an answer it resolves at once, with a console
+ * warning: the page may have no listener, or call respondWith() too late (after an await).
+ * @param {EventTarget} target
+ * @param {string} type
+ * @param {object} detail
+ * @returns {Promise<unknown>}
+ */
+export declare function request(target: EventTarget, type: string, detail: object): Promise<unknown>;

package/types/global.d.ts

@@ -0,0 +1,33 @@
+// The element in the DOM's type maps: document.createElement("pivot-report") and querySelector give a
+// PivotReportElement, and addEventListener("pivot-view-change", ...) on it (or on a parent: the events
+// bubble and are composed) knows the event's detail. Copied next to the generated declarations by
+// types.js; written by hand because JSDoc cannot augment global interfaces.
+import type { CellClick, ExportFile, PivotReportElement, PivotView, SourceSwitch, TemplateDelete, TemplatePublish, TemplateSave, TipDismiss } from "./element.js";
+
+/** The events of <pivot-report>. */
+export interface PivotReportEventMap {
+    /** Every change of the view, normalized. Controlled: set `view` to `detail.view`. */
+    "pivot-view-change": CustomEvent<{ view: PivotView }>;
+    /** A click (or Enter) on a value or a chart point. */
+    "pivot-cell-click": CustomEvent<CellClick>;
+    /** "Save current view" (shown with `save-templates`); answer with `detail.respondWith(promise)`. */
+    "pivot-template-save": CustomEvent<TemplateSave>;
+    /** Delete of a template marked `deletable`, after the user confirmed; answer with `detail.respondWith(promise)`. */
+    "pivot-template-delete": CustomEvent<TemplateDelete>;
+    /** "Publish as shared view" on a user's view (shown with `can-publish`); answer with `detail.respondWith(promise)`. */
+    "pivot-template-publish": CustomEvent<TemplatePublish>;
+    /** Every exported file before its download and every copy before the clipboard; `preventDefault()` skips it. */
+    "pivot-export": CustomEvent<ExportFile>;
+    /** A tip dismissed, all tips switched off or back on; `detail.dismissed` is the whole list to store. */
+    "pivot-tip-dismiss": CustomEvent<TipDismiss>;
+    /** "Switch to <name> and load" for a view made for other data (one of `sources`): show that data with `detail.view`. */
+    "pivot-source-switch": CustomEvent<SourceSwitch>;
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        "pivot-report": PivotReportElement;
+    }
+    // on the element, a parent, the document and the window: the events bubble and are composed
+    interface GlobalEventHandlersEventMap extends PivotReportEventMap {}
+}

package/types/index.d.ts

@@ -0,0 +1,22 @@
+/// <reference path="./global.d.ts" />
+export type PivotView = import("./element.js").PivotView;
+export type Template = import("./element.js").Template;
+export type FieldDefaults = import("./element.js").FieldDefaults;
+export type CellClick = import("./element.js").CellClick;
+export type ExportFile = import("./element.js").ExportFile;
+export type TemplateSave = import("./element.js").TemplateSave;
+export type TemplateDelete = import("./element.js").TemplateDelete;
+export type TemplatePublish = import("./element.js").TemplatePublish;
+export type PivotReportEventMap = import("./global.js").PivotReportEventMap;
+/**
+ * @typedef {import("./element.js").PivotView} PivotView
+ * @typedef {import("./element.js").Template} Template
+ * @typedef {import("./element.js").FieldDefaults} FieldDefaults
+ * @typedef {import("./element.js").CellClick} CellClick
+ * @typedef {import("./element.js").ExportFile} ExportFile
+ * @typedef {import("./element.js").TemplateSave} TemplateSave
+ * @typedef {import("./element.js").TemplateDelete} TemplateDelete
+ * @typedef {import("./element.js").TemplatePublish} TemplatePublish
+ * @typedef {import("./global.js").PivotReportEventMap} PivotReportEventMap
+ */
+export { EVENTS, PivotReportElement, TAG, define } from "./element.js";

package/types/jsx.d.ts

@@ -0,0 +1,25 @@
+// Opt-in JSX types for React: `import type {} from "pivotkit-element/jsx";` once in a React app
+// makes <pivot-report> a known element with its properties and its events as `on<event-name>` props.
+// They describe React 19, which sets a prop as a property when the element has one and listens for a
+// custom event through `on` + its exact name (react.dev, "Custom HTML elements"). React 18 passes
+// every prop as an attribute and has no custom event props: set objects and listeners in a ref there.
+// Copied next to the generated declarations by types.js; needs @types/react 18.3 or later.
+import type { DetailedHTMLProps, HTMLAttributes } from "react";
+import type { PivotReportElement } from "./element.js";
+import type { PivotReportEventMap } from "./global.js";
+
+type Settable = "data" | "dataKey" | "view" | "defaultView" | "templates" | "labels" | "fieldDefaults" | "limits" | "locale" | "theme" | "height" | "timeZone" | "fileName" | "label" | "drillDown" | "drillDownLimit" | "saveTemplates" | "templateStore" | "canPublish" | "tips" | "storageKey" | "dismissedTips" | "chartOptions" | "shareLink" | "persistView" | "loading" | "fieldInfo" | "zoneInfo" | "settingInfo" | "sourceId" | "sourceName" | "sources" | "schemaUrl" | "grow" | "fieldList";
+
+/** The props of <pivot-report> in JSX. */
+export type PivotReportJsxProps = DetailedHTMLProps<HTMLAttributes<PivotReportElement>, PivotReportElement> &
+    Partial<Pick<PivotReportElement, Settable>> & {
+        [K in keyof PivotReportEventMap as `on${K}`]?: (event: PivotReportEventMap[K]) => void;
+    };
+
+declare module "react" {
+    namespace JSX {
+        interface IntrinsicElements {
+            "pivot-report": PivotReportJsxProps;
+        }
+    }
+}