@uwdata/mosaic-spec 0.5.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, UW Interactive Data Lab
+
+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,57 @@
+# mosaic-spec
+
+Declarative specification of Mosaic-powered applications as JSON or YAML files. This package provides a parser and code generation framework for reading specifications in a JSON format and generating live Mosaic visualizations and dashboards using the [vgplot](https://github.com/uwdata/mosaic/tree/main/packages/vgplot) API.
+
+## Usage
+
+To parse a specification and generate round-trip JSON output (`.toJSON()`), JavaScript module code (`astToESM`), or a live web application (`astToDOM`):
+
+```js
+import { parseSpec, astToDOM, astToESM } from '@uwdata/mosaic-spec';
+
+// declarative specification in JSON format
+const spec = {
+  plot: [
+    {
+      mark: 'lineY',
+      data: { from: 'table' },
+      x: 'date',
+      y: 'value'
+    }
+  ],
+  width: 640,
+  height: 200
+};
+
+// parse specification to internal AST (abstract syntax tree)
+const ast = parseSpec(spec);
+
+// serialize back to a normalized JSON format
+const json = ast.toJSON();
+
+// generate ESM (ECMAScript Module) code
+const code = astToESM(ast);
+
+// instantiate a running application
+// assumes standard browser facilities in globabl variable `window`
+const {
+  element, // root DOM element of the application
+  params   // Map of all named Params and Selections
+} = await astToDOM(ast);
+
+// add application to current web page
+document.body.appendChild(element);
+```
+
+To parse specifications in YAML format, import the `yaml` library and use it to parse input specification files:
+
+```js
+import { parseSpec } from '@uwdata/mosaic-spec';
+import { parse } from 'yaml';
+
+const yaml = /* load yaml file file */;
+const spec = parse(yaml); // parse yaml to JS objects
+
+// parse specification to internal AST (abstract syntax tree)
+const ast = parseSpec(spec);
+```