{"id":18116888,"url":"https://github.com/vijithassar/bisonica","last_synced_at":"2025-10-28T19:41:02.904Z","repository":{"id":37104106,"uuid":"503793361","full_name":"vijithassar/bisonica","owner":"vijithassar","description":"accessible data visualizations with Vega Lite","archived":false,"fork":false,"pushed_at":"2025-07-02T04:40:43.000Z","size":1624,"stargazers_count":15,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-10-04T01:44:51.687Z","etag":null,"topics":["accessibility","data-visualization","vega","vega-lite","visualization"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/vijithassar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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,"zenodo":null}},"created_at":"2022-06-15T14:10:19.000Z","updated_at":"2025-10-03T23:22:10.000Z","dependencies_parsed_at":"2025-04-14T14:03:17.840Z","dependency_job_id":null,"html_url":"https://github.com/vijithassar/bisonica","commit_stats":{"total_commits":596,"total_committers":2,"mean_commits":298.0,"dds":0.001677852348993314,"last_synced_commit":"7656ee2c0a2b2b0dfaa4d51d725fca2c8589ab56"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/vijithassar/bisonica","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vijithassar%2Fbisonica","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vijithassar%2Fbisonica/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vijithassar%2Fbisonica/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vijithassar%2Fbisonica/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vijithassar","download_url":"https://codeload.github.com/vijithassar/bisonica/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vijithassar%2Fbisonica/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281504331,"owners_count":26512864,"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","status":"online","status_checked_at":"2025-10-28T02:00:06.022Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["accessibility","data-visualization","vega","vega-lite","visualization"],"created_at":"2024-11-01T04:16:37.857Z","updated_at":"2025-10-28T19:41:02.898Z","avatar_url":"https://github.com/vijithassar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Overview\n\nbisonica is a minimalist and accessibility-first alternative renderer for the open source [Vega Lite](https://vega.github.io/vega-lite/) standard for data visualization, a replacement for the [original `vega-lite.js` library](https://github.com/vega/vega-lite) which reads in the same [JSON configuration objects](https://vega.github.io/vega-lite/docs/) and outputs charts.\n\n# Install\n\nInstall from [npm](https://www.npmjs.com/package/bisonica) using your tool of choice. For example:\n\n```bash\nnpm install bisonica\n```\n\n# Quick Start\n\nThe `chart()` function takes a Vega Lite JSON specification object and uses it to create a chart rendering function which can be run using [`d3-selection`](https://github.com/d3/d3-selection).\n\n```javascript\nimport { select } from 'd3';\nimport { chart } from 'bisonica';\n\nconst dimensions = {\n    x: 500,\n    y: 500\n};\n\n// create a chart rendering function\nconst renderer = chart(specification, dimensions);\n\n// render the chart\nrenderer(select('div'));\n```\n\nOr the equivalent syntax with `selection.call()`:\n\n```javascript\n// render the chart\nselect('div').call(renderer);\n```\n\nYou'll probably want to load the included stylesheet? Feel free to use your own alternative if you want, though.\n\nYou can load it directly:\n\n```html\n\u003chead\u003e\n    \u003clink rel=\"stylesheet\" href=\"./source/index.css\" /\u003e\n\u003c/head\u003e\n```\n\nOr import with a packager or build tool:\n\n```javascript\nimport \"bisonica/styles.css\";\n```\n\n# Specifications\n\nIn the preceding code, the `specification` variable is a JSON object that describes the chart according to the [Vega Lite](https://vega.github.io/vega-lite/) open standard. Explaining the structure of that object is beyond the scope of the bisonica documentation and would be duplicative in any case. Instead, please refer to the excellent [examples](https://vega.github.io/vega-lite/examples/), [API documentation](https://vega.github.io/vega-lite/docs/), and [tutorials](https://vega.github.io/vega-lite/tutorials/getting_started.html) provided by the Vega Lite project.\n\n# Tooltips\n\nVega Lite and bisonica both support attaching tooltips to chart content if the specification requests it. Please see the [Vega Lite tooltip documentation](https://vega.github.io/vega-lite/docs/tooltip.html) for more details on the numerous useful ways this can be configured.\n\nBy default, bisonica renders tooltip content as [svg `\u003ctitle\u003e` nodes](https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/title) within each piece of the chart, which browsers typically reveal on mouseover.\n\nYou can also add your own custom tooltips by calling the `.tooltip()` method attached to a chart renderer and passing it an arbitrary function.\n\n```javascript\nconst renderer = chart(specification, dimensions);\nrenderer.tooltip(myCustomTooltipFunction);\n```\n\nWhen it is called, your tooltip function will be passed an object containing the data point, the SVG DOM node, the browser event, and key/value pairs of any data fields itemized in the specification object used to create the chart.\n\nNote that the tooltip API is only loosely defined in the Vega Lite standard and also has not yet stabilized in bisonica.\n\n# Why?\n\n## Accessibility\n\nWhen faced with an accessibility concern, bisonica typically just defaults to the most accessible option, whereas `vega-lite.js` might require more elaborate JSON in the specification object in order to achieve the same result. Some accessibility features such as the keyboard navigation and audio sonification cannot be replicated with the standard `vega-lite.js` renderer at all.\n\n## Performance\n\nbisonica is often considerably faster than rendering the same chart using `vega-lite.js`. This will depend on the specific chart configuration and the input data, but as an example, pie charts have been clocked rendering in as little as 1.25 milliseconds.\n\n## Customization\n\nUnlike `vega-lite.js`, bisonica renders legends as HTML next to the SVG instead of inside the SVG, and as a result they are much easier to restyle with CSS or even control with custom JavaScript behaviors.\n\n# Comparison\n\nIn general, bisonica may be a good choice if you need to render straightforward charts with strong accessibility properties using Vega Lite's JSON as the backing format and you can handle writing the custom CSS that will probably be necessary to get the generated graphics over the finish line for your use case.\n\nOn the other hand, the standard `vega-lite.js` renderer is definitely still the way to go if you need its more elaborate graphical options, [faceted trellis plots](https://vega.github.io/vega-lite/docs/facet.html), charts which don't rely on custom styling, a dynamic exploratory workflow powered by [evaluating string expressions](https://github.com/vega/vega-expression), or any of the features bisonica has intentionally omitted.\n\n## Omissions\n\nbisonica is still a work in progress and as such supports only a subset of Vega Lite functionality. The supported chart forms are listed in [`marks.js`](./source/marks.js).\n\nData loading will not [parse inline strings](https://vega.github.io/vega-lite/docs/data.html#inline).\n\nNested fields must be looked up using dot notation (e.g. `datum.field`), not bracket notation (e.g. `datum['field']`).\n\n[Predicates](https://vega.github.io/vega-lite/docs/predicate.html) defined with string expressions only support simple comparisons (e.g. `\"datum.value \u003c 100\"` or `\"datum.group === 'a'\"`).\n\nThe [calculate transform](https://vega.github.io/vega-lite/docs/calculate.html) only supports deriving new fields with string concatenation and static functions but can't do arbitrary math. (If you need arbitrary math, do it in JavaScript and attach the results to your specification before rendering.)\n\nEscaping special characters in field names is not supported. Instead, you should mutate your data before rendering to clean up the affected field names.\n\n[Geographic maps](https://vega.github.io/vega-lite/examples/#maps-geographic-displays) are not implemented.\n\nAdvanced Vega Lite features like [`facet`](https://vega.github.io/vega-lite/docs/composition.html#faceting) and [`parameters`](https://vega.github.io/vega-lite/docs/parameter.html) are not yet available.\n\nRendering to alternative output formats such as `\u003ccanvas\u003e` instead of `\u003csvg\u003e` will most likely never be supported.\n\n# Errors\n\n## Throwing\n\nErrors inside the chart library are nested, and error handling typically appends information to `error.message` and then re-throws the same error object. This naturally has the effect of augmenting the messages generated by the runtime with written explanations meant for humans at every layer of the stack, sort of a \"semantic stack trace.\"\n\n## Catching\n\nTo set a custom error handler, pass a function to the `.error()` method.\n\n```javascript\n// create a chart renderer\nconst renderer = chart(specification, dimensions)\n\n// error handling function\nconst errorHandler = (error) =\u003e alert(error.message);\n\n// attach the error handling function to the chart renderer\nrenderer.error(errorHandler);\n```\n\nBy default, errors are handled at the top level with `console.error`, equivalent to `renderer.error(console.error)`.\n\n## Disabling\n\nTo disable default trapping of errors and instead surface the semantic stack traces to the consumer:\n\n```javascript\n// disable catching and allow errors\n// to propagate up to the caller\nrenderer.error(null);\n```\n\nYou'll then want to handle these in your page or application.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvijithassar%2Fbisonica","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvijithassar%2Fbisonica","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvijithassar%2Fbisonica/lists"}