pivotkit-element 0.2.0 → 0.4.0

package/types/element.d.ts

@@ -171,6 +171,57 @@ export type SourceEntry = {
     id: string;
     name?: string;
 };
+export type DataLoad = {
+    /**
+     * a file loaded ("load": preventDefault()
+     * refuses it, the data stays), the page's data shown again, one of those undone or redone, or the
+     * file shown again by an element with storage-key put back into the page ("restore")
+     */
+    cause: "load" | "original" | "undo" | "redo" | "restore";
+    /**
+     * the data shown now: the file's (its id names
+     * the views kept for it), or the element's source-id and source-name
+     */
+    source: {
+        id?: string;
+        name?: string;
+    } | null;
+    file: {
+        name: string;
+        size: number;
+        type: string;
+    } | null;
+    /**
+     * the sheet of a workbook
+     */
+    sheet: string | null;
+    rows: number;
+    columns: Array<{
+        name: string;
+        type: string;
+    }>;
+    /**
+     * the readers' notes ("load")
+     */
+    notes: Array<{
+        code: string;
+        params: Record<string, unknown>;
+        message: string;
+    }>;
+};
+export type ReaderPlugin = {
+    apiVersion: 1;
+    kind: "reader";
+    name: string;
+    label: string;
+    accept: readonly string[];
+    load: () => Promise<unknown>;
+};
+export type ColumnarData = {
+    columns: string[];
+    types?: Array<"string" | "number" | "date" | "boolean" | null>;
+    data: unknown[][];
+};
 export type SourceSwitch = {
     /**
      * the entry of `sources`
@@ -185,92 +236,6 @@ export type SourceSwitch = {
      */
     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;
@@ -372,6 +337,12 @@ export declare class PivotReportElement extends Base {
     /** The name of the data shown, for people ("Sales 2026"); with source-id. */
     get sourceName(): string | undefined;
     set sourceName(value: string | undefined);
+    /**
+     * People may load a file into the report (attribute allow-import): a Data button with "Load
+     * data…", a file dropped onto the report, a preview first. Read in the browser, nothing uploaded.
+     */
+    get allowImport(): boolean;
+    set allowImport(value: boolean);
     /** The page is loading the data: the report shows its skeleton (attribute loading). */
     get loading(): boolean;
     set loading(value: boolean);
@@ -384,9 +355,12 @@ export declare class PivotReportElement extends Base {
      */
     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 rows: an array of objects, or columnar data ({ columns, types, data }, one array per column);
+     * encoded once per array or object, or once per `dataKey`.
+     */
+    get data(): object[] | ColumnarData | undefined;
+    set data(value: object[] | ColumnarData | 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);
@@ -414,6 +388,12 @@ export declare class PivotReportElement extends Base {
      */
     get sources(): SourceEntry[] | undefined;
     set sources(value: SourceEntry[] | undefined);
+    /**
+     * Reader plugins for more formats with allow-import (pivotkit-xlsx for Excel workbooks); CSV, TSV,
+     * text and JSON are built in.
+     */
+    get plugins(): ReaderPlugin[] | undefined;
+    set plugins(value: ReaderPlugin[] | undefined);
     /** pivotkit-core's limits (rows, cells, ...). */
     get limits(): Record<string, number> | undefined;
     set limits(value: Record<string, number> | undefined);

package/types/events.d.ts

@@ -8,6 +8,7 @@ export declare const EVENTS: Readonly<{
     export: "pivot-export";
     tipDismiss: "pivot-tip-dismiss";
     sourceSwitch: "pivot-source-switch";
+    dataLoad: "pivot-data-load";
 }>;
 /**
  * Dispatches an event on the element.

package/types/global.d.ts

@@ -2,7 +2,7 @@
 // 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";
+import type { CellClick, DataLoad, ExportFile, PivotReportElement, PivotView, SourceSwitch, TemplateDelete, TemplatePublish, TemplateSave, TipDismiss } from "./element.js";
 
 /** The events of <pivot-report>. */
 export interface PivotReportEventMap {
@@ -22,6 +22,8 @@ export interface PivotReportEventMap {
     "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>;
+    /** The data shown changed (with `allow-import`): a file loaded (`preventDefault()` refuses it), the page's data again, or one of those undone or redone. */
+    "pivot-data-load": CustomEvent<DataLoad>;
 }
 
 declare global {

package/types/jsx.d.ts

@@ -8,7 +8,7 @@ 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";
+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" | "allowImport" | "plugins";
 
 /** The props of <pivot-report> in JSX. */
 export type PivotReportJsxProps = DetailedHTMLProps<HTMLAttributes<PivotReportElement>, PivotReportElement> &