{"id":13481553,"url":"https://github.com/GlobalWebIndex/d3scription","last_synced_at":"2025-03-27T12:31:00.648Z","repository":{"id":44618521,"uuid":"64957974","full_name":"GlobalWebIndex/d3scription","owner":"GlobalWebIndex","description":"D3.js tooltip plugin made simple. With single-page apps in mind.","archived":false,"fork":false,"pushed_at":"2022-02-04T10:54:40.000Z","size":376,"stargazers_count":30,"open_issues_count":0,"forks_count":2,"subscribers_count":42,"default_branch":"master","last_synced_at":"2024-04-14T11:54:14.789Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GlobalWebIndex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-04T18:27:11.000Z","updated_at":"2023-09-11T10:51:36.000Z","dependencies_parsed_at":"2022-09-02T04:02:29.293Z","dependency_job_id":null,"html_url":"https://github.com/GlobalWebIndex/d3scription","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlobalWebIndex%2Fd3scription","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlobalWebIndex%2Fd3scription/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlobalWebIndex%2Fd3scription/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlobalWebIndex%2Fd3scription/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GlobalWebIndex","download_url":"https://codeload.github.com/GlobalWebIndex/d3scription/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245844851,"owners_count":20681790,"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":[],"created_at":"2024-07-31T17:00:52.769Z","updated_at":"2025-03-27T12:31:00.361Z","avatar_url":"https://github.com/GlobalWebIndex.png","language":"TypeScript","funding_links":[],"categories":["Utils"],"sub_categories":[],"readme":"# d3scription\n\nD3 tooltip description following mouse cursor. With window edge collision solved.\n\n![screenshot](media/screenshot.png)\n\nThis plugin tries to be as universal and simple as possible.\nYou can install it using your favorite dependency manager - doesn't matter if it is [NPM](http://npmjs.org/) or [bower](https://bower.io/).\nYou can also **directly download distribution** if you do not use any of these. It supports many module systems (commonjs, AMD, TypeScript).\nYou can easily customize look in your css and overwrite all default values by providing your own.\n\n# Instalation\n\n## NPM\n\nThis will install npm package with **commonjs** module system:\n\n```\nnpm install d3scription --save\n```\n\n## Bower\n\nThis will install bower package with **AMD** module and **global `d3scription` variable**:\n\n```\nbower install d3scription --save\n```\n\n## Direct download\n\nIf you do not want to use any dependency manager in your project you can simply download [distribution](dist/d3scription.js)\nand place it in your project. This is exactly the same file as installed using bower. It supports **AMD modules or global `d3scription` function**.\n\n```\ncurl https://raw.githubusercontent.com/GlobalWebIndex/d3scription/master/dist/d3scription.js \u003e d3scription.js\n```\n\n# Usage\nYou can use this plugin with both **JavaScript and TypeScript**. Please see [demos](demo/) for some example usage.\n\n## JavaScript\n\nAssume you have d3scription.js file already loaded in browser together with d3.js or AMD manager is used you're able to use this plugin in similar fashion.\nDon't forget, that this plugin itself is dependent on D3 so you need to include d3 before you load d3scription!\n\n```js\n// define some example data\nvar data = [\n    {\n        x: 50,\n        y: 100,\n        desc: 'We are your friends...'\n    },\n    {\n        x: 200,\n        y: 50,\n        desc: 'I love it!'\n    }\n]\n\n// select SVG element and create main group\nvar el = d3.select('svg')\n    .append('g');\n\n// setup plugin with description getter function and default options.\n// if you want to overwrite default z-index, offset or class name please see `api:setup:options section`\nvar tipFactory = d3scription(function(d) { return d.desc; });\n\n// create tip for our main group element\nvar tip = tipFactory()\n    .element(el);\n\n// set data to circles\nvar circles = el.selectAll('.circle')\n    .data(data);\n\n// draw circles\nvar cEnter = circles.enter()\n    .append('circle')\n    .attr('class', 'circle')\n    .attr('r', 30)\n    .attr('cx', function(d) { return d.x; })\n    .attr('cy', function(d) { return d.y; })\n    // setup show and hide action on mouse events\n    .on('mouseover', tip.show)\n    .on('mouseout', tip.hide);\n```\n\n## Typescript\n\nUsage with typescript is quite simmilar as usage with any other module system.\n\n```typescript\nimport d3scription from 'd3scription';\n\ninterface Data {\n    x : number;\n    y : number;\n    desc : string;\n}\n\n// define some example data\nconst data : Data[] = [\n    {\n        x: 50,\n        y: 100,\n        desc: 'We are your friends...'\n    },\n    {\n        x: 200,\n        y: 50,\n        desc: 'I love it!'\n    }\n]\n\n// select SVG element and create main group\nconst el = d3.select('#first-example')\n    .append('g');\n\n// setup plugin with description getter function and default options.\n// if you want to overwrite default z-index, offset or class name please see `api:setup:options section`\nconst tipFactory = d3scription((d : Data) =\u003e d.desc);\n\n// create tip for our main group element\nconst tip = tipFactory()\n    .element(el);\n\n// set data to circles\nconst circles = el.selectAll('.circle')\n    .data(data);\n\n// draw circles\nconst cEnter = circles.enter()\n    .append('circle')\n    .attr('class', 'circle')\n    .attr('r', 30)\n    .attr('cx', d =\u003e d.x)\n    .attr('cy', d =\u003e d.y)\n    // setup show and hide action on mouse events\n    .on('mouseover', tip.show)\n    .on('mouseout', tip.hide);\n```\n\n# Styles\n\nYou can import or copy [default styles](css/style.css) to your project if you want.\nAnyway as you can see writing your own styles for tooltip is really simple.\n\n# API\n\nApi is design as three steps process to make reuse and flow as clean as possible.\nThese steps are `setup` \u003e `initialize` \u003e `use`. Folloving paragraphs describes each step individually.\n\n## Setup\n\nFirst you need to setup new Tip factory (you can think about it as alternative to subclassing base class with necessary options even it's not really uses classes at all).\nThis is done using the only public function provided by d3scription out of the box - `de3scription([contentGetter], [optionalOptions])`.\n\nThis function accept two parameters - `contentGetter` and `options`.\n\n**Content getter** is just regular function which takes `data` and returns `string` content of tip.\nThis works the same way as many d3 methods like `.attr('x', [getter])` or `.style('fill', [getter])`.\n\n### Options\n\nAre used for overwriting default settings of plugin. It's a **hash** where every key is optional.\nFor typescript plugin exports this interface under name `Options`.\nThere are all possible values:\n\n* `zIndex` sets css z-index of tip element (default is 100).\n* `class` set custom class name for element (default is `d3scription-tip`).\n* `offset[\"top\"]` top offset of tip (default is `-10`).\n* `offset[\"left\"]` left offset of tip (default is `10`).\n\nYou can create one settuped tipFactory and reuse it on multiple places or create as many of these factories as you wish.\n\n### Example\n\n```js\nfunction getDescription(data) {\n  return data.toolTipText;\n}\nvar options = {\n  zIndex: 1000,\n  class: 'my-tooltip',\n  offset: {\n    top: 20,\n    left: 20\n  }\n}\nvar myD3scription = d3Scription(getDescription, options);\nvar defaultD3scription = d3scription(getDescription);\n```\n\n## Factory\n\nSettup function return another function which takes **element** in which tip should be active.\nThis is element in which tip will follow mouse. This function also creates final tip.\nYou can create many tips from one factory using this function.\n\n### Example\n\n```js\nvar element = d3.select('svg').append('g');\nvar tip = myD3scription().element(element); // this function was returned by setup\n```\n\n## Tip\n\nFinally you'll have a tip instance returned by from factory (after passing element).\nNow you can call methods on this tip as you wish. Most common case is to `show(data)` and `hide()`\non mouse events. you can also take advantage of `element(element)` for changing orginal element of tip\nor using `destroy()`.\n\n## Tip API\n\n* `show(data)` sets content of tip and displays it.\n* `hide()` hides tip\n* `element(element)` sets new element for tip\n* `destroy()` removes tip from dom\n\n## Basic Example of usage\n\n```js\n// define circle elements and bind data for them\nvar circles = el.selectAll('.circle')\n    .data(data);\n\n// create circles and add tips actions to them\nvar cEnter = circles.enter()\n    .append('circle')\n    .attr('class', 'circle')\n    .attr('r', 30)\n    .attr('cx', function(d) { return d.x; })\n    .attr('cy', function(d) { return d.y; })\n    // show tip on mouseover\n    // NOTE: will use binded data for setting content of tip\n    .on('mouseover', tip.show)\n    // hide tip on mouseout event\n    .on('mouseout', tip.hide);\n```\n# Changelog\n\n- v1.0.1 - update position on show (fixes situations where `show` is called but `mouseMove` event doesn't happen)\n- v1.0.0 - improve API\n- v0.0.2 - window edge collision detections\n- v0.0.1 - initial release\n\n# Building localy\n\nAll PRs are welcome! This is why we tried to made whole development setup as simple as possible.\n\nClone repository:\n\n```\ngit clone git@github.com:GlobalWebIndex/d3scription.git\n```\n\nInstall all dependecies via NPM and Bower:\n\n```\nnpm install \u0026\u0026 bower install\n```\n\nThe main file you want to work with is [index.ts](index.ts). There are also [demo examples](demo/) where you can play with plugin.\n\n## Building project\n\nThere are few handy npm scripts already settuped up.\n\nIf you want to run project as watch run:\n\n```\nnpm run watch\n```\n\nyou can then open [demo/index.html](examples) in browser. Project will be compiled in background if you made any change to source.\n\nFor building distribution please run following.\n\n```\nnpm run compile\n```\n\nThis will compile all versions of plugin (including commonjs for usage with NPM).\n\n# License\n\nMIT\n\n## About GlobalWebIndex\n\n![globalwebindex](https://pbs.twimg.com/profile_images/468332770624679937/wd2TMi0i_400x400.png)\n\nd3scription is maintained by GlobalWebIndex Ltd.\n\nSee more about us at [www.globalwebindex.net](https://www.globalwebindex.net).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGlobalWebIndex%2Fd3scription","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGlobalWebIndex%2Fd3scription","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGlobalWebIndex%2Fd3scription/lists"}