umwelt-js 0.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2023-present, the Umwelt contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,90 @@
+# umwelt-js
+
+Embed the [Umwelt](https://umwelt-data.github.io/umwelt/) viewer in any web app. From a single
+spec, `umwelt-js` renders three coordinated views of a dataset — a **visualization**, a
+**sonification**, and an accessible, keyboard-navigable **textual structure** (powered by
+[Olli](https://umwelt-data.github.io/olli/)). It renders internally with SolidJS, but you never
+touch that: you hand it a spec and a container element.
+
+## Install
+
+```bash
+npm install umwelt-js
+```
+
+## Usage
+
+```js
+import { createViewer } from 'umwelt-js';
+import 'umwelt-js/style.css';
+
+const spec = {
+  data: {
+    name: 'stocks.csv',
+    url: 'https://raw.githubusercontent.com/vega/vega-datasets/master/data/stocks.csv',
+  },
+  fields: [
+    { name: 'symbol', type: 'nominal' },
+    { name: 'date', type: 'temporal' },
+    { name: 'price', type: 'quantitative' },
+  ],
+  key: ['symbol', 'date'],
+  visual: {
+    units: [
+      {
+        name: 'vis_unit_0',
+        mark: 'line',
+        encoding: {
+          x: { field: 'date' },
+          y: { field: 'price' },
+          color: { field: 'symbol' },
+        },
+      },
+    ],
+  },
+  audio: {
+    units: [
+      {
+        name: 'audio_unit_0',
+        encoding: { pitch: { field: 'price' } },
+        traversal: [{ field: 'symbol' }, { field: 'date' }],
+      },
+    ],
+  },
+};
+
+const viewer = createViewer(spec, document.getElementById('umwelt-viewer'));
+```
+
+Import `umwelt-js/style.css` once per page. You don't have to write specs by hand — author one in
+the [editor](https://umwelt-data.github.io/umwelt/editor/) and copy the JSON from its Export tab,
+or start from a [gallery example](https://umwelt-data.github.io/umwelt/gallery/).
+
+## API
+
+`createViewer(spec, container)` mounts the viewer and returns an `UmweltViewer`:
+
+| Method | Description |
+| --- | --- |
+| `updateSpec(newSpec)` | Replace the spec and re-render. |
+| `getSpec()` | The current spec. |
+| `getContainer()` | The container element. |
+| `destroy()` | Unmount and release audio/event resources. The instance can't be reused afterward. |
+| `getIsDestroyed()` | Whether `destroy()` has been called. |
+
+Call `destroy()` before removing the container from the DOM (e.g. in your framework's unmount
+hook). TypeScript users can import the spec/data types:
+
+```ts
+import type { UmweltSpec, UmweltDataset, UmweltDatum, UmweltValue } from 'umwelt-js';
+```
+
+## Documentation
+
+- [Quickstart](https://umwelt-data.github.io/umwelt/docs/quickstart)
+- [Viewer API](https://umwelt-data.github.io/umwelt/docs/viewer-api)
+- [UmweltSpec reference](https://umwelt-data.github.io/umwelt/docs/spec)
+
+## License
+
+BSD-3-Clause © the Umwelt contributors. See [LICENSE](./LICENSE).

package/dist/index.css

@@ -0,0 +1 @@
+body{margin:0}._App_1uzho_5{font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Oxygen,Ubuntu,Cantarell,Fira Sans,Droid Sans,Helvetica Neue,sans-serif;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;display:flex;flex-direction:row;height:100vh;overflow:hidden}._App_1uzho_5 ._column_1uzho_14{flex:1;min-width:0;padding:1em;height:100%;overflow-y:auto;box-sizing:border-box}._App_1uzho_5 h1{margin-top:0}._App_1uzho_5 code{font-family:source-code-pro,Menlo,Monaco,Consolas,Courier New,monospace}._Editor_1uzho_29,._Viewer_1uzho_29{font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Oxygen,Ubuntu,Cantarell,Fira Sans,Droid Sans,Helvetica Neue,sans-serif;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}._Editor_1uzho_29 h1,._Viewer_1uzho_29 h1{margin-top:0}._Editor_1uzho_29 h2,._Editor_1uzho_29 h3,._Editor_1uzho_29 h4,._Editor_1uzho_29 h5,._Viewer_1uzho_29 h2,._Viewer_1uzho_29 h3,._Viewer_1uzho_29 h4,._Viewer_1uzho_29 h5{margin-bottom:.5em}._Editor_1uzho_29 h3,._Viewer_1uzho_29 h3{margin-top:1.5em}._Editor_1uzho_29 table,._Viewer_1uzho_29 table{display:block;width:100%;max-height:200px;overflow:auto}._Editor_1uzho_29 td,._Editor_1uzho_29 th,._Viewer_1uzho_29 td,._Viewer_1uzho_29 th{text-align:left;padding-right:5px}._Editor_1uzho_29 details>summary,._Viewer_1uzho_29 details>summary{cursor:pointer}._Editor_1uzho_29 input[type=checkbox],._Editor_1uzho_29 input[type=radio],._Viewer_1uzho_29 input[type=checkbox],._Viewer_1uzho_29 input[type=radio]{margin:0 .5em 0 0;position:relative;top:1px}._Editor_1uzho_29 ol,._Viewer_1uzho_29 ol{list-style:decimal;padding-left:1.2em}

package/dist/index.d.ts

@@ -0,0 +1,231 @@
+import { Mark } from 'vega-lite/build/src/mark';
+import { Sort } from 'vega-lite/build/src/sort';
+import { LogicalComposition, FieldPredicate } from '@umwelt-data/umwelt-utils/predicate';
+import { Dataset, Datum, MeasureType as MeasureType$1, DataValue } from '@umwelt-data/umwelt-utils/data';
+
+type UmweltValue = DataValue;
+type UmweltDatum = Datum;
+type UmweltDataset = Dataset;
+declare const aggregateOps: readonly ["mean", "median", "min", "max", "sum", "count"];
+type UmweltAggregateOp = (typeof aggregateOps)[number];
+declare const timeUnits: readonly ["year", "quarter", "month", "yearmonth", "day", "date", "hours", "minutes", "seconds"];
+type UmweltTimeUnit = (typeof timeUnits)[number];
+type ScaleDomain = {
+    domain?: UmweltValue[];
+    zero?: boolean;
+    nice?: boolean | number;
+};
+type ScaleRange = {
+    range?: number[] | string[];
+};
+type MeasureType = MeasureType$1;
+interface UmweltDataSource {
+    name: string;
+}
+interface ExportableUmweltValuesDataSource {
+    name?: string;
+    values: UmweltDataset;
+}
+interface ExportableUmweltURLDataSource {
+    name?: string;
+    url: string;
+}
+interface ExportableUmweltNameDataSource {
+    name: string;
+}
+type ExportableUmweltDataSource = ExportableUmweltValuesDataSource | ExportableUmweltURLDataSource | ExportableUmweltNameDataSource;
+type UmweltPredicate = LogicalComposition<FieldPredicate>;
+declare const visualPropNames: readonly ["x", "y", "color", "shape", "size", "opacity", "order", "facet"];
+declare const audioPropNames: readonly ["pitch", "duration", "volume"];
+type VisualPropName = (typeof visualPropNames)[number];
+type AudioPropName = (typeof audioPropNames)[number];
+type EncodingPropName = VisualPropName | AudioPropName;
+declare const NONE = "None";
+type FieldName = string;
+interface EncodingRef {
+    property: EncodingPropName;
+    unit: string;
+}
+interface FieldDef {
+    active: boolean;
+    name: FieldName;
+    type?: MeasureType;
+    encodings: EncodingRef[];
+    scale?: ScaleDomain;
+    timeUnit?: UmweltTimeUnit;
+    aggregate?: UmweltAggregateOp;
+    bin?: boolean;
+    sort?: Sort<any>;
+}
+interface VisualEncodingFieldDef {
+    field: FieldName;
+    /** overrides the field's measure type for this visual channel only
+     * (e.g. render a temporal field as a nominal color scale) */
+    type?: MeasureType;
+    scale?: ScaleDomain & ScaleRange;
+    timeUnit?: UmweltTimeUnit | typeof NONE;
+    aggregate?: UmweltAggregateOp | typeof NONE;
+    bin?: boolean;
+    sort?: Sort<any>;
+}
+interface AudioEncodingFieldDef {
+    field: FieldName;
+    /** overrides the field's measure type for this audio channel only */
+    type?: MeasureType;
+    scale?: ScaleDomain & ScaleRange;
+    timeUnit?: UmweltTimeUnit | typeof NONE;
+    aggregate?: UmweltAggregateOp | typeof NONE;
+    sort?: Sort<any>;
+    bin?: undefined;
+}
+interface AudioTraversalFieldDef {
+    field: FieldName;
+    /** overrides the field's measure type for this traversal only */
+    type?: MeasureType;
+    scale?: ScaleDomain & ScaleRange;
+    timeUnit?: UmweltTimeUnit | typeof NONE;
+    bin?: boolean;
+    aggregate?: undefined;
+}
+type VisualEncoding = {
+    [prop in VisualPropName]?: VisualEncodingFieldDef;
+};
+type VisualUnitSpec = {
+    name: string;
+    mark: Mark;
+    encoding: VisualEncoding;
+};
+type AudioEncoding = {
+    [prop in AudioPropName]?: AudioEncodingFieldDef;
+};
+type AudioTraversal = AudioTraversalFieldDef[];
+type AudioUnitSpec = {
+    name: string;
+    encoding: AudioEncoding;
+    traversal: AudioTraversal;
+};
+declare const viewCompositions: string[];
+type ViewComposition = (typeof viewCompositions)[number];
+interface VisualSpec {
+    units: VisualUnitSpec[];
+    composition: ViewComposition;
+}
+interface AudioSpec {
+    units: AudioUnitSpec[];
+    composition: ViewComposition;
+}
+type TextNodeId = string;
+interface TextFieldRef {
+    field: FieldName;
+    type?: MeasureType;
+    timeUnit?: UmweltTimeUnit | typeof NONE;
+    bin?: boolean;
+}
+interface TextGroupNode {
+    id: TextNodeId;
+    nodeType: 'group';
+    groupby: TextFieldRef[];
+    children: TextNode[];
+}
+interface TextPredicateNode {
+    id: TextNodeId;
+    nodeType: 'predicate';
+    predicate: UmweltPredicate;
+    name?: string;
+    reasoning?: string;
+    children: TextNode[];
+}
+type TextNode = TextGroupNode | TextPredicateNode;
+interface TextSpec {
+    structures: Record<string, TextNode[]>;
+}
+interface UmweltSpec {
+    data: UmweltDataSource;
+    fields: FieldDef[];
+    key: FieldName[];
+    visual: VisualSpec;
+    audio: AudioSpec;
+    text: TextSpec;
+}
+type ExportableFieldDef = Omit<FieldDef, 'encodings' | 'active'>;
+interface ExportableVisualSpec {
+    units: VisualUnitSpec[];
+    composition?: ViewComposition;
+}
+interface ExportableAudioSpec {
+    units: AudioUnitSpec[];
+    composition?: ViewComposition;
+}
+interface ExportableTextSpec {
+    structures: Record<string, TextNode[]>;
+}
+interface ExportableSpec extends Omit<UmweltSpec, 'fields' | 'data' | 'visual' | 'audio' | 'text'> {
+    data: ExportableUmweltDataSource;
+    fields: ExportableFieldDef[];
+    visual: ExportableVisualSpec;
+    audio: ExportableAudioSpec;
+    text?: ExportableTextSpec;
+}
+
+interface UmweltViewerOptions {
+    spec: ExportableSpec;
+    container: HTMLElement;
+}
+/**
+ * Framework-agnostic Umwelt viewer that can be embedded in any web application.
+ * Internally uses SolidJS but exposes a simple JavaScript API.
+ */
+declare class UmweltViewer {
+    private options;
+    private disposal?;
+    private isDestroyed;
+    constructor(options: UmweltViewerOptions);
+    private mount;
+    /**
+     * Update the viewer with a new specification.
+     * This will re-render the entire viewer with the new data and configuration.
+     */
+    updateSpec(newSpec: ExportableSpec): void;
+    /**
+     * Get the current specification.
+     */
+    getSpec(): ExportableSpec;
+    /**
+     * Get the container element.
+     */
+    getContainer(): HTMLElement;
+    private cleanup;
+    /**
+     * Destroy the viewer and clean up all resources.
+     * The viewer cannot be used after calling this method.
+     */
+    destroy(): void;
+    /**
+     * Check if the viewer has been destroyed.
+     */
+    getIsDestroyed(): boolean;
+}
+/**
+ * Convenience function to create and mount an Umwelt viewer.
+ *
+ * @param spec The Umwelt specification defining the data and visualizations
+ * @param container The DOM element to render the viewer into
+ * @returns A new UmweltViewer instance
+ *
+ * @example
+ * ```javascript
+ * import { createViewer } from 'umwelt-js';
+ *
+ * const viewer = createViewer(mySpec, document.getElementById('viewer'));
+ *
+ * // Later update the data
+ * viewer.updateSpec(newSpec);
+ *
+ * // Clean up when done
+ * viewer.destroy();
+ * ```
+ */
+declare function createViewer(spec: ExportableSpec, container: HTMLElement): UmweltViewer;
+
+export { UmweltViewer, createViewer };
+export type { UmweltDataset, UmweltDatum, ExportableSpec as UmweltSpec, UmweltValue, UmweltViewerOptions };