pivotkit-element 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,143 @@
+# Changelog
+
+All notable changes to `pivotkit-element` are documented in this file. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this package adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-11-08
+
+### Added
+
+- pivotkit-react's warning for a view's unused parts, in plain words
+  ([#56](https://github.com/eizedev/pivotkit/issues/56)): its words are a chunk of their own (the
+  load group "unused", 4.2 KiB measured, budget 4.7), loaded only when a view has such parts; the
+  first load holds the warning's frame and pivotkit-core's issue codes (149.4 KiB measured, budget
+  raised from 149 to 150). Label changes as in pivotkit-react: `unusedParts`, `unusedPath`, `unusedMore` and `unusedFewer` new,
+  `issues`, `viewMissingFields`, `viewOtherIssue` and `viewOtherIssues` gone, `labels.unused` for the
+  lines. No new attribute or event.
+- pivotkit-react's sorting with a click on a table header
+  ([#55](https://github.com/eizedev/pivotkit/issues/55)): a value's name sorts the innermost row
+  field by it, a row field's name A to Z and Z to A; a `pivot-view-change` like the chip menu's sort.
+  No new attribute or event.
+- pivotkit-react's Save, Save as and New for views
+  ([#60](https://github.com/eizedev/pivotkit/issues/60)): Save on a user's view sends
+  `pivot-template-save` (with `save-templates`) or writes the browser store, Save on a shared view
+  sends `pivot-template-publish` (with `can-publish` and after the user confirmed, else it is off
+  with the reason), Save as onto a name that exists asks the user first. No new attribute or event.
+- Host notes: `pivot-template-save` and `pivot-template-publish` come with a name that exists for
+  Save and for Save as after the user confirmed: the page replaces the view of that name (an upsert
+  by name), it does not add a second one.
+
+### Changed
+
+- pivotkit-react's field chip menu with each setting in one line and folded menu sections that say
+  what they hold ([#57](https://github.com/eizedev/pivotkit/issues/57)); no new attribute or event.
+  The menus' size budget is 20 KiB (19.3 measured).
+
+- What runs only after a click left the first load
+  ([#73](https://github.com/eizedev/pivotkit/issues/73)): the menus' view changes, sharing's copy,
+  download and load, the drill-down's table and the texts only they show load with the menus, the
+  chart's label layout with the chart. The first load is 147.8 KiB gzip (152.2 before, measured on one
+  Mac), the menus 22.8, their German texts 4.4. Every size budget of a loaded chunk is now 3 to 5 % above what CI
+  measures, the first load's about 1 KiB: initial 149, chart 211, export 11.5, link 7.3, menus 24, texts 4.9. No new attribute
+  or event.
+
+- pivotkit-react's menu texts in German are a chunk of their own, loaded with the menus only for a
+  German report or when `locale` changes to German, and the menus' sections moved out of the first
+  load ([#73](https://github.com/eizedev/pivotkit/issues/73)): the menus 20.6 to 17.9 KiB gzip, the
+  first load 152.1 to 152.2 with the loading of the texts and English standing in when they fail
+  (measured on one Mac); a German page loads the texts' 4.0 KiB on top. The
+  size check has a group "texts" for it (budget 4.5 KiB).
+
+- The README, the package's page on npm, is a short landing page: what pivotkit-element is, one screenshot,
+  install, one example and a table of links into the
+  [documentation site](https://pivotkit.eize.dev/), which holds the details.
+- pivotkit-react's toolbar: Views is the last button to move into "More", so it stays in the toolbar
+  from about 1280 px (the chart type moves into "More" before it); New is in the Views menu only.
+  Every save closes the Views menu; the question before a view is replaced has the focus on Cancel;
+  the view loaded has a check mark in its group, and More the dot for unsaved changes while Views
+  is in it.
+
+### Fixed
+
+- No `pivot-export` for an empty report: its Export entries are off with "Add a field first."
+  ([#61](https://github.com/eizedev/pivotkit/issues/61)).
+
+## [0.1.0] - 2026-11-07
+
+First release.
+
+### Added
+
+- The attribute `field-list` (`"open"`, `"collapsed"`): the field list collapsed to a rail, as
+  pivotkit-react's `fieldList`.
+- Templates as pivotkit-react's: `templates` entries with `scope` and `file`, the attributes
+  `template-store` (`"browser"`: "My views" in localStorage, no event for its saves and deletes) and
+  `can-publish`, the event `pivot-template-publish` (`{ name, view, respondWith }`), and `scope` in
+  the details of `pivot-template-save` and `pivot-template-delete`.
+- `pivot-export` also for every copy and the drill-down's exports: kinds `copy-table`, `copy-json`,
+  `drill-copy`, `drill-json`, `drill-csv`, `drill-xlsx`; a copy has `text`, a drill-down export
+  `rows: { shown, count }`; `preventDefault()` keeps a copy from the clipboard as it keeps a file
+  from the download. The Export menu loads with the menus (first load 151.0 KiB measured, budget 152
+  unchanged); the menus' budget is 17.5 KiB (16.4 measured), the export's 11.5 (10.6 with the rows
+  export, TSV and JSON); the size check follows the chunks a chunk loads (the export is loaded from
+  the menus).
+- Attributes `share-link`, `persist-view`, `loading`, `field-info` and `zone-info`, and the property
+  `chartOptions`, as pivotkit-react's props; `pivot-export` also for a downloaded view (`kind`
+  `"json"`). pivotkit-core's link module is a chunk of its own, loaded on the first link; the size
+  budget of the first load is 152 KiB (150.7 measured with the chart display settings, sharing, the
+  skeleton, the menu changes, the value conditions and locale number entry).
+- Attributes `tips` ("on", "off" or a comma-separated list of tip ids) and `storage-key`, the property
+  `dismissedTips` and the event `pivot-tip-dismiss` (`{ id, dismissed }`), as pivotkit-react's tips
+  props; `fieldDefaults` takes `label`, `description`, `href` and `type`.
+- The attribute `grow` (pivotkit-react's `grow`: past the height or inside it).
+- The menus' texts load with the menus (pivotkit-react's `menu-labels.js`): the first load stays
+  within its 152 KiB budget (151.0 measured with the automatic chart type, the field list's keys, the
+  touch targets and the settings' explanations loaded with the menus); the menus' budget is 15 KiB
+  (13.8 measured).
+- The attribute `schema-url` (pivotkit-react's `schemaUrl`: the `$schema` of the view files; `""` for none).
+- Attributes `setting-info` (the "i" next to the settings, as pivotkit-react's `settingInfo`),
+  `source-id` and `source-name` (the data shown, for the shared view files and the check before a
+  view for other data loads), the property `sources` and the event `pivot-source-switch`
+  (`{ source, view, name }`: "Switch to … and load"). Full screen works on the report inside the
+  shadow root.
+
+- `<pivot-report>`: pivotkit-react's `<PivotReport>` as a custom element in an open shadow root, with
+  its own React 18.3.1, ReactDOM, pivotkit-react, pivotkit-core and @dnd-kit in the bundle; ECharts
+  (bar, line, pie and heatmap only) and the XLSX/CSV export are chunks loaded on first use.
+- Properties `data`, `dataKey`, `view`, `defaultView`, `templates`, `labels`, `fieldDefaults`, `limits`;
+  reflected attributes `locale` (else the element's `lang`), `theme`, `height`, `time-zone`,
+  `file-name`, `drill-down`, `drill-down-limit`, `save-templates`; JSON attributes `view` and
+  `default-view`. Controlled and uncontrolled as in pivotkit-react; a different `defaultView` starts
+  the report again on it, the view the report last reported does not. `height="100%"` fills the
+  element.
+- Events `pivot-view-change`, `pivot-cell-click`, `pivot-template-save` and `pivot-template-delete`
+  (answered with `detail.respondWith(promise)`, a console warning when nothing answered), and
+  `pivot-export` (cancelable: the page keeps the file); all bubble and are composed.
+- Styles in the shadow root as one shared constructed stylesheet (a `<style>` element where there is
+  none); the `--pk-*` tokens are declared on `:host`, so the page themes the element with rules on it
+  and nothing else crosses; `data-pk-theme` on the element tells the theme shown.
+- Lifecycle: properties set before the definition are taken over, a disconnected element unmounts its
+  React root (a move in the same task keeps it), a reconnected one mounts again on its last view.
+- `define(name)` for another tag name; loading the package twice does not throw and warns with both
+  versions (`PivotReportElement.version`). Imports in Node without defining anything.
+- Type declarations: the element, `PivotReportEventMap`, `HTMLElementTagNameMap` and the event map of
+  the DOM; `pivotkit-element/jsx` declares the element in React's JSX.
+- `dist/THIRD_PARTY_LICENSES.txt` with the license texts of the bundled packages; a size budget per
+  load group (`npm run size`).
+- `fieldDefaults[field].drillFormat` as in pivotkit-react: the format of a field's values in the
+  drill-down.
+- Attribute and property `label`: the name of the report's region landmark, one per report on a
+  page.
+- Everything of pivotkit-core and pivotkit-react 0.1.0 in the bundle, among it number ranges with
+  "Starting at", custom sort orders (`fieldDefaults[field].order`, reversed too, also for saved views),
+  unclickable empty cells with a text for screen readers, row labels that wrap on a phone and are
+  shown whole in the status line of a long table, one header for a single value, year ranges without
+  thousands separators, CSV percentages and calculations as the table shows them, heatmaps without
+  grey empty cells.
+
+[Unreleased]: https://github.com/eizedev/pivotkit/compare/pivotkit-element@0.2.0...HEAD
+[0.2.0]: https://github.com/eizedev/pivotkit/compare/pivotkit-element@0.1.0...pivotkit-element@0.2.0
+[0.1.0]: https://github.com/eizedev/pivotkit/releases/tag/pivotkit-element@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eizedev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# pivotkit-element
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The pivot report builder of [pivotkit](https://pivotkit.eize.dev/) as one web component,
+`<pivot-report>`, for pages without React: Angular apps, PHP and other server-rendered pages, plain
+HTML. It brings its own React ([which version](https://pivotkit.eize.dev/browser-support/#react)), [pivotkit-react](https://www.npmjs.com/package/pivotkit-react),
+[pivotkit-core](https://www.npmjs.com/package/pivotkit-core) and @dnd-kit, renders into an open shadow
+root and loads ECharts on the first chart. Everything the React component does works the same: field
+list, drag and drop, table and chart, filters, drill-down, undo, saved and shared views, export.
+
+![A line chart of monthly revenue per category](https://pivotkit.eize.dev/assets/screenshots/chart-light.png)
+
+## Install
+
+```bash
+npm install pivotkit-element
+```
+
+With a bundler, `import "pivotkit-element";` once defines `<pivot-report>`. Without one, serve the
+package's whole `dist/` directory: its chunks are loaded by relative URL from `dist/index.js`, so
+`index.js` alone is not enough. The package has no runtime dependency; the licenses of what it
+bundles are in `dist/THIRD_PARTY_LICENSES.txt`. Browsers: Chrome 111, Firefox 113, Safari 16.4 or
+later.
+
+## Example
+
+```html
+<script type="module" src="/assets/pivotkit-element/dist/index.js"></script>
+
+<pivot-report
+    locale="de-DE"
+    height="640"
+    default-view='{"rows":["Region"],"values":[{"field":"Sales","agg":"sum"}]}'
+></pivot-report>
+
+<script type="module" src="/assets/report.js"></script>
+```
+
+```js
+// report.js
+const report = document.querySelector("pivot-report");
+report.data = rows;                        // an array of objects, property only
+report.templates = [{ name: "By region", view: { rows: ["Region"] } }];
+report.addEventListener("pivot-view-change", (e) => localStorage.setItem("view", JSON.stringify(e.detail.view)));
+```
+
+## Where in the docs
+
+| Topic | Page |
+| --- | --- |
+| Getting started: install, first report, saving views on a server | [Getting started with the web component](https://pivotkit.eize.dev/getting-started/web-component/) |
+| PHP and server-rendered pages | [PHP and other server-rendered pages](https://pivotkit.eize.dev/getting-started/web-component/#php-and-other-server-rendered-pages) |
+| Angular | [Angular](https://pivotkit.eize.dev/getting-started/web-component/#angular), [Angular and zone.js](https://pivotkit.eize.dev/reference/element/#angular-and-zonejs) |
+| A page with React of its own | [React on the page](https://pivotkit.eize.dev/reference/element/#react-on-the-page) |
+| Entries, loading from a CDN | [Entries](https://pivotkit.eize.dev/reference/element/#entries), [Loading](https://pivotkit.eize.dev/reference/element/#loading) |
+| Every property and attribute | [Properties and attributes](https://pivotkit.eize.dev/reference/element/#properties-and-attributes) |
+| Controlled and uncontrolled | [Controlled and uncontrolled](https://pivotkit.eize.dev/reference/element/#controlled-and-uncontrolled) |
+| Events | [Events](https://pivotkit.eize.dev/reference/element/#events) |
+| Styles and theming | [Styles](https://pivotkit.eize.dev/reference/element/#styles), [Theming](https://pivotkit.eize.dev/reference/theming/#on-the-web-component) |
+| Languages and labels | [Localisation](https://pivotkit.eize.dev/reference/localisation/) |
+| The view, saved and shared views | [Views and saved views](https://pivotkit.eize.dev/concepts/views/), [Templates and shared views](https://pivotkit.eize.dev/concepts/templates/), [View file format](https://pivotkit.eize.dev/reference/view-file/) |
+| TypeScript | [Types](https://pivotkit.eize.dev/reference/element/#types) |
+| Bundle size | [Bundle size](https://pivotkit.eize.dev/reference/element/#bundle-size) |
+| Content-Security-Policy | [Security](https://pivotkit.eize.dev/security/#content-security-policy) |
+| Limits | [Locale, time zones, limits and errors](https://pivotkit.eize.dev/concepts/limits/#limits) |
+| Browser support | [Browser support](https://pivotkit.eize.dev/browser-support/) |
+| Recipes | [Recipes](https://pivotkit.eize.dev/embed/recipes/) |
+| What the people using the report can do | [Use a report](https://pivotkit.eize.dev/use/) |
+| Try it | [Live demo and the element example](https://pivotkit.eize.dev/demo/#the-web-component-example), [feature list](https://pivotkit.eize.dev/features/), [FAQ](https://pivotkit.eize.dev/faq/) |
+| Changes | [CHANGELOG](https://github.com/eizedev/pivotkit/blob/main/packages/pivotkit-element/CHANGELOG.md) |
+
+## License
+
+[MIT](https://github.com/eizedev/pivotkit/blob/main/LICENSE); the bundled packages under their own
+licenses, see `dist/THIRD_PARTY_LICENSES.txt`.