chore: import upstream snapshot with attribution

2026-07-13 12:25:07 +08:00
commit a26e856398
1681 changed files with 296950 additions and 0 deletions
@@ -0,0 +1,62 @@
+# `<perspective-viewer>` Custom Element library
+
+`<perspective-viewer>` provides a complete graphical UI for configuring the
+`perspective` library and formatting its output to the provided visualization
+plugins.
+
+Once imported and initialized in JavaScript, the `<perspective-viewer>` Web
+Component will be available in any standard HTML on your site. A simple example:
+
+```html
+<perspective-viewer id="view1"></perspective-viewer>
+<script type="module">
+    import perspective from "@perspective-dev/client";
+    import "@perspective-dev/viewer";
+
+    const worker = await perspective.worker();
+    const table = await worker.table(data);
+    document.getElementById("view1").load(table);
+</script>
+```
+
+## Attributes
+
+`<perspective-viewer>` can be configured via HTML attributes or JavaScript
+properties. When set as attributes, the viewer will apply the configuration on
+initialization:
+
+```html
+<perspective-viewer
+    columns='["Sales", "Profit"]'
+    group-by='["Region"]'
+    sort='[["Sales", "desc"]]'>
+</perspective-viewer>
+```
+
+## UI Features
+
+The viewer provides an interactive side panel with:
+
+- **Column list** - drag and drop columns to configure `group_by`, `split_by`,
+  `sort`, and `filter` fields.
+- **New Column** button - opens an expression editor for creating computed
+  columns via the [expression language](../../explanation/view/config/expressions.md).
+- **Plugin selector** - switch between visualization plugins such as Datagrid,
+  X/Y Line, X/Y Scatter, Treemap, Sunburst, and Heatmap.
+- **Theme** selector - toggle between available themes.
+- **Export** - download the current view as CSV or Arrow.
+- **Copy** - copy the current view to the clipboard.
+- **Reset** - restore the viewer to its default configuration.
+
+## Methods
+
+Key methods on the `<perspective-viewer>` element:
+
+| Method | Description |
+|---|---|
+| `load(table)` | Bind a `Table` to the viewer |
+| `restore(config)` | Apply a saved configuration object |
+| `save()` | Serialize the current configuration |
+| `reset(all)` | Reset configuration (pass `true` to also reset expressions) |
+| `getTable()` | Get the bound `Table` |
+| `flush()` | Wait for any pending UI updates to complete |