@cnrs/hecate-views-charts 0.2.0

package/package.json

@@ -0,0 +1,134 @@
+{
+  "@comment comments": [
+    "To track and understand the whys of each part of this package.json, ",
+    "in particular dependencies, please explain when you modify this file.",
+    "Please include the name of the section you comment after the `@comment`",
+    "'annotation' to make sure each key is unique (see the JSON spec).",
+    "This is required by JSON validators (like the one built into your IDE).",
+    "Plus, running `npm install <whatever> --save` removes duplicate keys.",
+    "",
+    "package.json documentation: https://docs.npmjs.com/files/package.json"
+  ],
+  "name": "@cnrs/hecate-views-charts",
+  "description": "Views web components available to any web app.",
+  "keywords": [
+    "dataviz",
+    "research",
+    "database",
+    "visualization",
+    "scientific",
+    "javascript",
+    "browser",
+    "library"
+  ],
+  "type": "module",
+  "module": "src/index.js",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "default": "./src/index.js"
+  },
+  "files": [
+    "src/**/*.js"
+  ],
+  "version": "0.2.0",
+  "license": "AGPL",
+  "homepage": "https://datasphere.readthedocs.io/projects/hecate/",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.huma-num.fr/datasphere/hecate/views/charts.git"
+  },
+  "bugs": {
+    "url": "https://gitlab.huma-num.fr/datasphere/hecate/views/charts/-/issues"
+  },
+  "main": "src/index.js",
+  "dependencies": {
+    "d3": "latest"
+  },
+  "@comment devDependencies": {
+    "vite": [
+      "Bundler for javascript project combines many js source files into a ",
+      "single one that is production-ready loadable in the browser.",
+      "- ViteJS website: https://vitejs.dev/"
+    ],
+    "vitest": [
+      "More or less 'all in one' unit testing framework",
+      "@requires vite ≥ 3.0.0 (and node ≥ 14.18)",
+      "- Vitest website: https://vitest.dev/"
+    ],
+    "@vitest/coverage-c8": [
+      "Compute percentage of code covered by tests.",
+      "- Vitest coverage documentation: https://vitest.dev/guide/coverage.html"
+    ],
+    "happy-dom": [
+      "By default, tests framework don't have any access to the DOM.",
+      "This packages simulates a DOM in the context of tests.",
+      "- https://www.npmjs.com/package/happy-dom"
+    ],
+    "eslint": [
+      "To use eslint ECMAScript linter.",
+      "- ESLint documentation: https://eslint.org/"
+    ],
+    "jsdoc": [
+      "Javascript documentation generation tool.",
+      "See `gendoc` script in this same file for some usage details.",
+      "- JSDoc documentation: https://jsdoc.app/"
+    ]
+  },
+  "devDependencies": {
+    "vite": "latest",
+    "vitest": "latest",
+    "@vitest/coverage-v8": "latest",
+    "happy-dom": "<=12.1.5",
+    "eslint": "latest",
+    "jsdoc": "latest"
+  },
+  "@comment scripts": {
+    "dev": [
+      "Starts development server in the local folder: this allows us devs to ",
+      "rapidly see the impacts of our modifications, with no page refresh.",
+      "@requires vite (dev dependency)"
+    ],
+    "test": [
+      "Runs every unit test once, then exits.",
+      "@requires vitest (dev dependency)"
+    ],
+    "test:coverage": [
+      "Runs every unit test once, with coverage percentage.",
+      "@requires vitest @vitest/coverage-v8 (dev dependencies)"
+    ],
+    "test:watch": [
+      "Runs every unit test with coverage %, watching for modifications.",
+      "@requires vitest @vitest/coverage-v8 (dev dependencies)"
+    ],
+    "build": [
+      "Bundles project for production in `dist` folder.",
+      "@requires vite (dev dependency)"
+    ],
+    "lint": [
+      "Checks code style using ESLint. note: Argument pattern is surrounded with ",
+      "double quotes, so its resolution doesn't depend on runtime environment.",
+      "@requires eslint (dev dependency)",
+      "- ESLint configuration file is `eslint.config.mjs`",
+      "- ESLint documentation: https://eslint.org/"
+    ],
+    "doc:html": [
+      "Generates developper documentation using JSDoc.",
+      "Documentation for each module/class/method is written",
+      "in docstring format, directly inside each source file.",
+      "@requires jsdoc (dev dependency)",
+      "- JSDoc configuration file is `.jsdoc.conf.json`.",
+      "- JSDoc config file spec: https://jsdoc.app/about-configuring-jsdoc.html",
+      "- JSDoc repo: https://github.com/jsdoc/jsdoc"
+    ]
+  },
+  "scripts": {
+    "dev": "vite",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest --coverage",
+    "build": "vite build",
+    "lint": "eslint \"src/**/*.js\"",
+    "doc:html": "./node_modules/jsdoc/jsdoc.js -c .jsdoc.conf.json"
+  }
+}

package/src/components/index.js

@@ -0,0 +1 @@
+export { Sample } from './sample.js';

package/src/components/sample.js

@@ -0,0 +1,37 @@
+/**
+ * Sample web component.
+ * It just displays a string.
+ */
+class Sample extends HTMLElement {
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    this.data = "placeholder";
+  }
+  /** Static property returning an array of attributes observed by the browser
+   */
+  static get observedAttributes() {
+    return ['data'];
+  }
+  /**
+   * This is called when an observed attribute is
+   * defined in the HTML or changed using Javascript.
+   */
+  attributeChangedCallback(property, old, now) {
+    if (old === now) return;  // don't bother to render if there is nothing new
+    this[property] = now;
+  }
+
+  /**
+   * Called when the element is connected to a DOM.
+   * Runs any required rendering.
+   */
+  connectedCallback() {
+    this.shadowRoot.innerHTML += `<p>${this.data}</p>`;
+  }
+}
+
+
+
+export { Sample };

package/src/index.js

@@ -0,0 +1,2 @@
+export * from './views/index.js';
+export * from './components/index.js';

package/src/init.js

@@ -0,0 +1,8 @@
+import { Sample, } from './components/';
+import { BarChart, Histogram, ScatterPlot, LineChart } from './views/';
+
+customElements.define('sample-component', Sample);
+customElements.define('scatter-plot', ScatterPlot);
+customElements.define('bar-chart', BarChart);
+customElements.define('histogram-chart', Histogram);
+customElements.define('line-chart', LineChart);

package/src/views/barchart.js

@@ -0,0 +1,246 @@
+import * as d3 from 'd3';
+
+
+/**
+ * BarChart web component.
+ * @see https://en.wikipedia.org/wiki/Bar_chart
+ */
+class BarChart extends HTMLElement{
+
+  constructor(){
+    super();
+    this.attachShadow({ mode: 'open' });
+    this.hera =  {};
+    this.settings = {};
+  }
+
+    /** Static property returning an array of attributes observed by the browser
+     */
+    static get observedAttributes() {
+      return ['data-hera', 'data-settings'];
+    }
+
+  get items() { return this.hera.items || []; }
+  get entities() { return this.hera.entities || []; }
+  get properties() { return this.hera.properties || []; }
+
+  get pidx() { return this.settings.x || 'x'; }
+  get pidy() { return this.settings.y || 'y'; }
+  get color() { return this.settings.color || '#7b4c98'; }
+
+  /**
+   * This is called when an observed attribute is
+   * defined in the HTML or changed using Javascript.
+   * @param {!string} attribute - Attribute name
+   * @param old - Previous value for `attribute`
+   * @param now - Current value for `attribute`
+   */
+  attributeChangedCallback(attribute, old, now) {
+    if (old === now) return;  // don't bother if there is nothing new
+    this[attribute] = now;
+    // data-* attributes can only be strings, so we cannot deserialize JSON
+    // in them ; so we use plain object fields to store deserialized values
+    // we trim the prefix to get the field name, so 'data-x' becomes 'x'
+    const fieldName = attribute.split('-').slice(1).join('-');
+    this[fieldName] = JSON.parse(now);
+    // note that this does not defeat the purpose of using data-* attributes
+    // in the first place, as if a name clash should happen in the future,
+    // we could edit this class with no impact on the users code
+  }
+    
+    //js method called everytime the component is added to the dom
+  connectedCallback(){
+    var dataset = this.prepareData(this.hera, this.settings);
+  
+        //creation of scene 
+        const margin = { top : 70, right : 30, bottom: 40, left : 80};
+        const {sceneWidth, sceneHeight, barWidth, svg} = this.createScene(500, 500, this.items.length, margin);
+        
+        //addition of axises
+        var {y_scale, x_scale} = this.createAxisScales(sceneHeight, sceneWidth, dataset);
+        this.addAxises(x_scale, y_scale, sceneHeight, sceneWidth, margin, svg)
+
+        this.displayChart(sceneHeight, barWidth, dataset, y_scale, x_scale, svg);
+
+    }
+
+    /**
+     * Sets the shadow dom of the component, currently creates a single div 
+     * @returns the element that was appended to the shadow dom
+     */ 
+  createShadowDom() {
+    const e = document.createElement('div');
+    this.shadowRoot.appendChild(e);
+    return e;
+  }
+
+    /**
+     * Prepare the data by giving it the correct format
+     * @param {object} rawData - the data as it was passed , it's a js object type 
+     * @param {object} rawSettings - the settings as it was passed, it's a js object type
+     * @returns js object that contains the elements of metadata, each key representing a different pid
+     */
+    prepareData(rawData, rawSettings){
+        var barValues = [];
+        var barLabels = [];
+        rawData.items.forEach(item => {
+            item.metadata.forEach(meta => {
+                if (meta.pid === this.pidy) {  // Y axis is height of bars
+                    barValues.push(parseInt(meta.value));
+                }
+                if (meta.pid === this.pidx) {  // X axis is "label for each bar"
+                    barLabels.push(meta.value);
+                }
+            });
+        });
+        const dataset = barLabels.map((label, index) => ({
+            label: label,
+            value: barValues[index]
+        }));
+        return dataset;
+    }
+
+    /**
+     * creates a svg element that will contain the viewer 
+     * @param {number} width - desired width for the svg
+     * @param {number} height - desired height for the svg
+     * @param {number} dataLength - number of elements in data
+     * @param {object} margin - to leave space for the axises, a js object containing 4 margins
+     * @returns the svg and its height, width and the width of each bars
+     */
+    createScene(width, height, dataLength, margin){
+
+        const sceneWidth = width - margin.left - margin.right; //to set barwidth, the key scenewith in the return is not recognized yet 
+        const sceneHeight = height - margin.top - margin.bottom; 
+        const barWidth = sceneWidth/dataLength
+        
+        const divElem = this.createShadowDom();
+        const container =  d3.select(divElem);
+        
+        //addition of container to the svg 
+        const svg = container.append("svg")
+            .attr("width", sceneWidth + margin.left + margin.right)
+            .attr("height", sceneHeight + margin.top + margin.bottom)
+            .append("g")
+            .attr("transform", `translate(${margin.left},${margin.top})`);
+        
+        return {
+            sceneWidth : sceneWidth, 
+            sceneHeight : sceneHeight, 
+            barWidth : barWidth,
+            svg : svg
+        };   
+    }
+
+    /**
+     * create the x and y linear scales
+     * @param {number} sceneHeight 
+     * @param {number} sceneWidth 
+     * @param {object} dataset 
+     * @returns y_scale and x_scales
+     */
+    createAxisScales(sceneHeight, sceneWidth, dataset){
+        var y_scale = d3.scaleLinear()
+            .range([sceneHeight,0])
+            .domain([0,d3.max(dataset.map(function(d) { return d.value; }))]);
+        
+        var x_scale = d3.scaleBand()
+            .range([ 0, sceneWidth ])
+            .domain(dataset.map(function(d) { return d.label; }))
+            .padding(0.2);
+        
+        return{
+            y_scale : y_scale,
+            x_scale : x_scale
+        }
+    }
+
+    /**
+     * add the left and bottom axises, with their Label
+     * @param {map} x_scale - linear scale for the x axis 
+     * @param {map} y_scale - linear scale for the y axis
+     * @param {number} sceneHeight - the height of the svg
+     * @param {number} sceneWidth - the width of the svg
+     * @param {object} margins 
+     * @param {object} dataset 
+     * @param {tag} svg 
+     */
+    addAxises(x_scale, y_scale, sceneHeight, sceneWidth, margins, svg){
+        var y_axis = d3.axisLeft(y_scale);
+        var x_axis = d3.axisBottom(x_scale);
+        const labels = this.getAxesLabels();
+
+        svg.append("g")
+            .call(y_axis)
+            /*TO DO : allow the user to customize the appearance of the axis
+            the line below removes the line of vertical axis*/
+            //.call((g) => g.select(".domain").remove()) 
+            .call((g) => g.append("text")
+                .attr("x", -margins.left)
+                .attr("y",-10)
+                .attr("fill", "currentColor")
+                .attr("text-anchor", "start")
+                .text(labels.y));
+
+        svg.append("g")
+            .attr("transform", `translate(0,${sceneHeight})`)
+            .call(x_axis)
+            .call((g) => g.append("text")
+            .attr("x", sceneWidth)
+            .attr("y", margins.bottom - 4)
+            .attr("fill", "currentColor")
+            .attr("text-anchor", "end")
+            .text(labels.x))
+            .selectAll("text");
+                //TO DO : this lines allows to rotate the text of the horizontal axis
+                //.attr("transform", `translate(-10,0)rotate(-45)`) 
+
+    }
+
+    /**
+     * display the bar and puts it in the svg
+     * @param {number} sceneHeight - the height of the svg
+     * @param {number} barWidth - the width of each bars
+     * @param {object} dataset 
+     * @param {map} y_scale 
+     * @param {map} x_scale 
+     * @param {*} svg 
+     */
+    displayChart(sceneHeight, barWidth, dataset, y_scale, x_scale, svg){
+        svg.selectAll("rect")
+            .data(dataset)
+            .enter()
+            .append("rect")
+            .attr("y", function(d) {
+                return y_scale(d.value); 
+            })
+            .attr("x", function(d) {
+                return x_scale(d.label); 
+            })
+            .attr("height", function(d) { 
+                return sceneHeight - y_scale(d.value); 
+            })
+            .attr("width", barWidth) //add bar distance in future?
+
+            .attr("fill", this.color)
+            .attr("stroke","black");
+    }
+
+  getAxesLabels() {
+    const px = this.getProperty(this.pidx);
+    const py = this.getProperty(this.pidy);
+    return {
+      x: px ? px.name : `Missing property '${this.pidx}'`,
+      y: py ? py.name : `Missing property '${this.pidy}'`,
+    };
+  }
+
+  getProperty(pid) {
+    const found = this.properties.find((p) => p['@id'] === pid);
+    return found ? found : null;
+  }
+}
+
+
+
+export { BarChart };

package/src/views/histogram.js

@@ -0,0 +1,222 @@
+import * as d3 from 'd3';
+
+
+/**
+ * Histogram web component.
+ * @see https://en.wikipedia.org/wiki/Histogram
+ */
+class Histogram extends HTMLElement{
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    this.hera = {};
+    this.settings = {};
+  }
+  /**
+   * Static property returning the array of attributes
+   * observed by the browser.
+   * @returns {Array<string>} Attribute names
+   */
+  static get observedAttributes() {
+    return ['data-hera', 'data-settings'];
+  }
+
+  get items() { return this.hera.items || []; }
+  get entities() { return this.hera.entities || []; }
+  get properties() { return this.hera.properties || []; }
+
+  get pidx() { return this.settings.x || 'x'; }
+  get pidy() { return this.settings.y || 'y'; }
+  get color() { return this.settings.color || '#7b4c98'; }
+
+  get padding() {
+    return this.settings.padding
+        || { top: 20, right: 20, bottom: 30, left: 40 };
+  }
+
+  /**
+   * This is called when an observed attribute is
+   * defined in the HTML or changed using Javascript.
+   * @param {!string} attribute - Attribute name
+   * @param old - Previous value for `attribute`
+   * @param now - Current value for `attribute`
+   */
+  attributeChangedCallback(attribute, old, now) {
+    if (old === now) return;  // don't bother if there is nothing new
+    this[attribute] = now;
+    // data-* attributes can only be strings, so we cannot deserialize JSON
+    // in them ; so we use plain object fields to store deserialized values
+    // we trim the prefix to get the field name, so 'data-x' becomes 'x'
+    const fieldName = attribute.split('-').slice(1).join('-');
+    this[fieldName] = JSON.parse(now);
+    // note that this does not defeat the purpose of using data-* attributes
+    // in the first place, as if a name clash should happen in the future,
+    // we could edit this class with no impact on the users code
+  }
+
+  /**
+   * Called when the element is connected to a DOM.
+   * Runs any required rendering.
+   */
+  connectedCallback(){
+
+    this.width = this.parentElement.clientWidth;
+    this.height = this.parentElement.clientHeight;
+
+    const container = document.createElement('div');
+    this.shadowRoot.appendChild(container);
+
+    // group items into "bins", so that scene creation is easier
+    const bins = this.prepareData();
+    // create viewport, ie. d3 "scale" functions for axes
+    const { vx, vy } = this.createViewport(bins);
+    // create a SVG container for the whole scene
+    const scene = d3.select(container).append('svg')
+            .attr('width', this.width)
+            .attr('height', this.height)
+            .attr('viewBox', [0, 0, this.width, this.height])
+            .attr('style', 'max-width: 100%; height: auto;')
+      ;
+    // create callback for visual feedback when hovering on each histogram bar
+    const { mouseover, mouseleave } = this.createHoverCallbacks();
+    // create histogram bars
+    scene.append('g')
+      .attr('fill', this.color)
+      .selectAll()
+      .data(bins)
+        .join('rect')
+          .attr('x', (d) => vx(d.x0) + 1)
+          .attr('width', (d) => vx(d.x1) - vx(d.x0) - 1)
+          .attr('y', (d) => vy(d.length))
+          .attr('height', (d) => vy(0) - vy(d.length))
+          .on('mouseover', mouseover)
+          .on('mouseleave', mouseleave)
+          .append('title')
+            .text((bin) => this.getBinLabel(bin))
+    ;
+    // add X axis and Y axis to scene
+    this.addAxes(scene, vx, vy);
+  }
+
+  /**
+   * Prepare the data by organize so that scene creation is simpler.
+   * For this, we need to turn quantitative values into consecutive,
+   * non-overlapping intervals called "bins", which we can in turn use
+   * to group values in nice histogram bars.
+   * @return Bin generator
+   * @see https://d3js.org/d3-array/bin
+   */
+  prepareData() {
+    var barValues = [];
+    var classValues = [];
+    this.items.forEach(item => {
+      item.metadata.forEach(meta => {
+        if (meta.pid === this.pidx) {
+          barValues.push(parseInt(meta.value));
+        }
+        if (meta.pid === this.pidy){
+          classValues.push(meta.value);
+        }
+      });
+    });
+    const dataset = classValues.map((label, index) => ({
+        class: label,
+        value: barValues[index],
+      }));
+    // Now, "bin" the dataset:
+    const bins = d3.bin()
+        //.thresholds(40)
+      // if thresholds are specified as a number, the domain will be uniformly
+      // divided into approximately that many bins: so if .thresholds(40) is
+      // called, the resulting Histogram will have _appoximately_ 40 bars;
+      // if thresholds is not specified, the current threshold generator will
+      // be used, and by default it implements Sturges’ formula
+        .value((d) => d.value)(dataset);
+    return bins;
+  }
+
+  /**
+   * Creates callbacks for changing each bar color when hovering onto.
+   */
+  createHoverCallbacks(msg) {
+    return {
+      mouseover: function(d) {
+        d3.select(this).style('opacity', .5)
+      },
+      mouseleave: function(d) {
+        d3.select(this).style('opacity', 1)
+      },
+    };
+  }
+
+  /**
+   * Creates two scale functions. vx (resp. vy) is used to convert x (resp. y)
+   * to a number between 0 and the width (resp. height) of the viewer.
+   * @param {Array<Object>} bins - Array containing bins
+   * @returns {Viewport} This viewer current viewport
+   */
+  createViewport(bins){
+    return {
+      vx: d3.scaleLinear()
+        .domain([bins[0].x0, bins[bins.length - 1].x1])
+        .range([this.padding.left, this.width - this.padding.right]),
+      vy: d3.scaleLinear()
+        .domain([0, d3.max(bins, (d) => d.length)])
+        .range([this.height - this.padding.bottom, this.padding.top]),
+    };
+  }
+
+  getBinLabel(bin) {
+    const py = this.getProperty(this.pidy);
+    const name = py ? py.name : `Missing property '${this.pidy}'`;
+    return `No. of ${name}: ${bin.length}`;
+  }
+
+  /**
+   * Add X and Y axes to the SVG scene.
+   */
+  addAxes(svg, vx, vy) {
+    const labels = this.getAxesLabels();
+    // add X-axis and label
+    svg.append('g')
+      .attr('transform', `translate(0,${this.height - this.padding.bottom})`)
+      .call(d3.axisBottom(vx).ticks(this.width / 80).tickSizeOuter(0))
+      .call((g) => g.append('text')
+        .attr('x', this.width)
+        .attr('y', this.padding.bottom - 4)
+        .attr('fill', 'currentColor')
+        .attr('text-anchor', 'end')
+        .text(labels.x)
+      );
+    // add Y-axis and label
+    svg.append('g')
+      .attr('transform', `translate(${this.padding.left},0)`)
+      .call(d3.axisLeft(vy).ticks(this.height / 40))
+      .call((g) => g.append('text')
+        .attr('x', -this.padding.left)
+        .attr('y', 10)
+        .attr('fill', 'currentColor')
+        .attr('text-anchor', 'start')
+        .text(`Frequency (#${labels.y})`)
+      );
+  }
+
+  getAxesLabels() {
+    const px = this.getProperty(this.pidx);
+    const py = this.getProperty(this.pidy);
+    return {
+      x: px ? px.name : `Missing property '${this.pidx}'`,
+      y: py ? py.name : `Missing property '${this.pidy}'`,
+    };
+  }
+
+  getProperty(pid) {
+    const found = this.properties.find((p) => p['@id'] === pid);
+    return found ? found : null;
+  }
+}
+
+
+
+export { Histogram };

package/src/views/index.js

@@ -0,0 +1,12 @@
+export { BarChart } from './barchart.js';
+export { Histogram } from './histogram.js';
+export { LineChart } from './linechart.js';
+export { ScatterPlot } from './scatterplot.js';
+
+/**
+ * This object is a wrapper for three arrays
+ * @typedef {Object} Hera
+ * @property {Array<Object>} items - Items list
+ * @property {Array<Object>} entities - Entities list
+ * @property {Array<Object>} properties - Properties list
+ */