{"id":21803563,"url":"https://github.com/terrestris/d3-util","last_synced_at":"2025-04-13T19:14:22.668Z","repository":{"id":41380788,"uuid":"146865493","full_name":"terrestris/d3-util","owner":"terrestris","description":"A helper library to create d3 charts","archived":false,"fork":false,"pushed_at":"2024-08-30T23:03:59.000Z","size":3054,"stargazers_count":4,"open_issues_count":4,"forks_count":3,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-05T17:16:04.778Z","etag":null,"topics":["bar-chart","chart","d3","hacktoberfest","line-chart"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/terrestris.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-31T08:41:33.000Z","updated_at":"2023-02-14T11:36:58.000Z","dependencies_parsed_at":"2023-02-18T04:15:35.229Z","dependency_job_id":"ed5823c7-8dc6-4876-a3fd-128d6a0c18dd","html_url":"https://github.com/terrestris/d3-util","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrestris%2Fd3-util","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrestris%2Fd3-util/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrestris%2Fd3-util/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrestris%2Fd3-util/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/terrestris","download_url":"https://codeload.github.com/terrestris/d3-util/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248766768,"owners_count":21158301,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bar-chart","chart","d3","hacktoberfest","line-chart"],"created_at":"2024-11-27T11:45:15.381Z","updated_at":"2025-04-13T19:14:22.614Z","avatar_url":"https://github.com/terrestris.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# d3-util\n\n[![Build Status](https://travis-ci.com/terrestris/d3-util.svg?branch=master)](https://travis-ci.com/terrestris/d3-util)\n[![Coverage Status](https://coveralls.io/repos/github/terrestris/d3-util/badge.svg?branch=master)](https://coveralls.io/github/terrestris/d3-util?branch=master)\n\nA set of helper classes for working with d3 charts.\n\n## Installation\n\n```javascript static\nnpm i @terrestris/d3-util\n```\n\nIn order to use the library in your project, make sure you load\n[the moment.js library](https://momentjs.com/) as well.\n\n## Usage\n\n### General notes\n\nThe `ChartRenderer` is the main entry point to render a chart. It features a\n`render` method that can be used to render its components to a given DOM node.\n\nThe chart renderer can be constructed with a few parameters:\n\n* `components`: a list of chart components constituting the chart\n* `size`: the desired chart size in pixels\n* `zoomType`: the desired zoom type. `'none'` for no zoom, `'transform'` for a\n  zoom using the svg `transform` attribute without rebuilding the DOM or\n  `'rerender'` for a zoom rebuilding the DOM. Using the transform method has the\n  effect of also zooming the shapes, i.e. a line of 1px will get bigger when\n  zooming in.\n* `onMouseMoveFunc`: the function that will be called on every mouse move over the\n  entire `svg`.\n\n### Components\n\n#### LegendComponent\n\nThe legend component simply renders a list of legend elements. It accepts the\nfollowing configuration parameters:\n\n* `extraClasses`: a string with extra CSS classes to add to the legend group\n* `legendEntryMaxLength`: a number with the max number of characters per line\n  for legend labels\n* `position`: an array `[x, y]` with the desired position within the svg\n* `items`: an array of legend element configurations\n\nThe legend items can have the following configuration parameters:\n\n* `contextmenuHandler`: can be a function that is called in case the user\n  right clicks or long touches the item. Argument is the `d3.event` event\n* `customRenderer`: can be a function that is called during rendering and will\n  be called with the item's group element. Can be used to e.g. render custom\n  buttons for the legend element\n* `onClick`: can be a function getting the current `d3.event` once an item is\n  clicked\n* `onHover`: can be a function getting the current `d3.event` once the mouse is\n  over the item\n* `onMouseOut`: can be a function getting the current `d3.event` once the mouse is\n  leaving the item\n* `style`: can be an object with svg style parameters such as `stroke`,\n  `stroke-width` etc. in order to style the legend icon\n* `title`: the legend text\n* `value`: if set, a `value` attribute will be added to the legend node\n* `type`: can be `'line'`, `'bar'`, `'area'` or `'background'` in order to\n  render a line, a small bar chart icon, a line with the area below it filled or\n  just a filled block\n\n#### BarComponent\n\nThe bar component can render (grouped) bar charts. It accepts the following\nconfiguration parameters:\n\n* `axes`: an axis configuration object (see below)\n* `backgroundColor`: can be a hex color string\n* `extraClasses`: a string with extra CSS classes to set on the bar chart node\n* `position`: the `[x, y]` coordinates\n* `rotateBarLabel`: if true, the labels will be rotated by 90°\n* `size`: the `[width, height]` size\n* `title`: if set, a heading will be rendered with this text\n* `titleColor`: the color hex string\n* `titlePadding`: title padding from the top\n* `titleSize`: title size\n* `groupedInitiallyHidden`: a list of grouping indexes for bars that should initially be hidden\n* `groupsInitiallyHidden`: a list of group indexes for bars that should initially be hidden\n* `data`: the data object. Example:\n\n```javascript\n{\n  data: [{\n    value: 'Value 1',\n    values: [{\n      index: 'Group 1',\n      value: 23,\n      uncertainty: undefined,\n      color: '#ff0000',\n      belowThreshold: false,\n      label: '23',\n      tooltipFunc: target =\u003e 'Tooltip'\n    }, {\n      index: 'Group 3',\n      value: 42,\n      uncertainty: 5.6,\n      color: '#00ff00',\n      belowThreshold: true,\n      label: '\u003c'\n    }]\n  }],\n  grouped: ['Group 1', 'Group 2', 'Group 3']\n}\n```\n\nThe `grouped` field contains a list of the grouped indexes, the data list\ncontains the actual groups. A group object contains a `value` with the group\nname/label and a list of `values` corresponding to the actual bars.\n\nThe bar objects can have a number of configuration values:\n\n* `index`: corresponds to one of the value in the `grouped` list (not all\n  grouped values must be contained in every group)\n* `value`: the actual y value\n* `uncertainty`: if set to a value, an uncertainty indicator will be rendered\n  on top of the bar\n* `color`: the hex color value\n* `belowThreshold`: if true, no bar will be drawn, just the label\n* `label`: if set, a label will be rendered onto the bar\n* `tooltipFunc`: if set, the function will be called with the bar element upon\n  mouseover\n\n#### TimeseriesComponent\n\nThe timeseries component can render multiple line charts. It supports the\nfollowing configuration parameters:\n\n* `axes`: an axis configuration object (see below)\n* `backgroundColor`: as color hex string\n* `extraClasses`: extra classes to set on the timeseries chart node\n* `position`: the `[x, y]` coordinates\n* `size`: the `[width, height]` size\n* `title`: if set, a heading will be rendered with this text\n* `titleColor`: the color hex string\n* `titlePadding`: title padding from the top\n* `titleSize`: title size\n* `initialZoom`: if set, an initial zoom transform object (with `x`, `y`, `kx` and `ky` set)\n* `moveToRight`: if set to `true`, the `initialZoom` will be modified so the timeseries is scrolled completely to the right\n* `series`: a list of line chart configurations as follows\n\nA line chart configuration has the following options:\n\n* `axes`: a list of axis ids referencing x and y axis configurations like\n  `['x', 'y0']`\n* `color`: the color hex string\n* `curveType`: a d3 curve type string like `curveStepBefore`\n* `shapeType`: usually `'line'`, can also be `'area'`\n* `useTooltipFunc`: a boolean indicating whether the third data value is a\n  tooltip mouseover function and fifth value is a mouseout function\n* `data`: an array with the data: `[xvalue, yvalue, mouseOverFunc, styleObject, mouseOutFunc]`\n* `initiallyVisible`: a boolean indicating whether the line is initially visible\n  defaulting to true\n\nThe tooltip function is optional as well as the style. If the style is set, it\nis used to configure the corresponding point symbol. Examples for style objects\nwould be:\n\n```json\n      {\n          \"type\": \"circle\",\n          \"radius\": \"5\"\n      }\n      {\n          \"type\": \"circle\",\n          \"radius\": \"10\"\n      }\n      {\n          \"type\": \"star\",\n          \"sides\": 5,\n          \"radius\": 10\n      }\n      {\n          \"type\": \"rect\",\n          \"width\": 15,\n          \"height\": 20\n      }\n```\n\n#### Axis configuration objects\n\nThe axis configuration objects configure the scales and axes of a chart. You'll\nneed to configure at least an `x` and a `y` axis, but at least for line charts\nmultiple y axes are allowed (you still must use the same x axis for all lines).\n\nThe object maps axis ids (with `x` and `y` mandatory) to axis configurations,\nwhich may have the following options:\n\n* `display`: boolean that determines whether the axis is drawn or not\n* `format`: a d3 format string like `\",.2f\"`, `\"dynamic\"`, a format array or a format function\n* `label`: an optional axis label\n* `labelColor`: the label color hex string\n* `labelPadding`: label padding\n* `labelRotation`: label rotation\n* `labelSize`: label size\n* `max`: the axis and scale max value (optional)\n* `min`: the axis and scale min value (optional)\n* `orientation`: the axis orientation (x or y)\n* `sanitizeLabels`: if set to true, overlapping tick labels will be removed\n  (only supported for y axes)\n* `scale`: the scale to use (linear, log, time)\n* `tickPadding`: the tick padding\n* `tickSize`: the tick size\n* `factor`: if set, the axis' max value will be divided by this value so\n  you can get a bigger interval when using auto calculated min/max values\n\nIf the format is set to `\"dynamic\"`, it will be dynamically adjusted to the\nfollowing d3-format equivalents, based on the rendered value:\n\n* `value \u003c 1`: `.3f`\n* `1 \u003c value \u003c 10`: `.2f`\n* `10 \u003c value \u003c 100`: `.1f`\n* `100 \u003c value`: `.0f`\n\nIf the format is set to an array, it must be an array of objects\nlike this:\n\n```json\n[{\n  \"min\": 0,\n  \"max\": 1,\n  \"format\": \".3f\"\n}, {\n  \"min\": 1,\n  \"max\": 100,\n  \"format\": \".0f\"\n}]\n```\n\nA format matches a value, if the value is `\u003e= min` and `\u003c max`. You can use\n`\"-Infinity\"` and `\"Infinity\"` for min and max to get unbounded classes.\n\nA note on line charts: you can have multiple y axes here. Using the line chart\naxis references you can have some lines correspond to one y axis and some lines\ncorrespond to another y axis. As noted above, you still need to use the same x\naxis for all lines (else the chart would supposedly be confusing anyway).\n\n## Development\n\nIf you want to contribute, you can build the project like this:\n\n* `git checkout https://github.com/terrestris/d3-util`\n* `cd d3-util`\n* `npm i`\n\nand then either\n\n* `npm run build:dev`\n\nin order to get a development build or\n\n* `npm run build:dist`\n\nin order to get a production build.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterrestris%2Fd3-util","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fterrestris%2Fd3-util","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterrestris%2Fd3-util/lists"}