{"id":15284195,"url":"https://github.com/wikibonsai/treehouze","last_synced_at":"2025-08-24T06:08:42.908Z","repository":{"id":144711089,"uuid":"608258029","full_name":"wikibonsai/treehouze","owner":"wikibonsai","description":"Graph utilities for handling and housing markdown wikis -- and (semantic) trees!","archived":false,"fork":false,"pushed_at":"2023-10-12T22:25:51.000Z","size":100,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-09T04:20:34.647Z","etag":null,"topics":["d3","force-graph","graph","memory-palace","wikibonsai"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/treehouze","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wikibonsai.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}},"created_at":"2023-03-01T16:39:29.000Z","updated_at":"2024-12-30T22:27:49.000Z","dependencies_parsed_at":"2023-12-01T05:44:24.948Z","dependency_job_id":null,"html_url":"https://github.com/wikibonsai/treehouze","commit_stats":{"total_commits":4,"total_committers":1,"mean_commits":4.0,"dds":0.0,"last_synced_commit":"791340374643aab0b3f384990722fba72428dfef"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikibonsai%2Ftreehouze","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikibonsai%2Ftreehouze/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikibonsai%2Ftreehouze/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikibonsai%2Ftreehouze/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wikibonsai","download_url":"https://codeload.github.com/wikibonsai/treehouze/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248644209,"owners_count":21138569,"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":["d3","force-graph","graph","memory-palace","wikibonsai"],"created_at":"2024-09-30T14:51:01.717Z","updated_at":"2025-04-12T23:22:10.173Z","avatar_url":"https://github.com/wikibonsai.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# treehouze\n\n[![A WikiBonsai Project](https://img.shields.io/badge/%F0%9F%8E%8B-A%20WikiBonsai%20Project-brightgreen)](https://github.com/wikibonsai/wikibonsai)\n[![NPM package](https://img.shields.io/npm/v/treehouze)](https://npmjs.org/package/treehouze)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./treehouze.svg\" width=\"300\" height=\"300\"/\u003e\n\u003c/p\u003e\n\nTreehouze is a single graph instance that may be translated between [2D](https://github.com/vasturiano/force-graph), [3D](https://github.com/vasturiano/3d-force-graph), [VR](https://github.com/vasturiano/3d-force-graph-vr), and [AR](https://github.com/vasturiano/3d-force-graph-ar) representations without any changes to its shape or structure.\n\nIt's designed to be as general-purpose as possible, but was built with [`[[wikirefs]]`](https://github.com/wikibonsai/wikirefs) and [semantic trees](https://github.com/wikibonsai/semtree) structures in mind with the aim of facilitating tangible digital [memory palaces](https://artofmemory.com/blog/how-to-build-a-memory-palace/).\n\n🏡 Build and maintain a treehouze to play in in your [WikiBonsai](https://github.com/wikibonsai/wikibonsai) digital garden.\n\n## Install\n\nInstall with [npm](https://docs.npmjs.com/cli/v9/commands/npm-install):\n\n```\nnpm install treehouze\n```\n\nOr use a script tag:\n\n```html\n\u003cscript type=\"module\" src=\"//unpkg.com/treehouze\"\u003e\u003c/script\u003e\n```\n\n## Use\n\nAdd 2 div elements to your `html` -- one for the graph itself and another for the element that wraps it (this is for [selecting multiple nodes](#shift--click) to work)\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chead\u003e\n  \u003c!-- ... --\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n  \u003cdiv id=\"graph-view\"\u003e\n    \u003cdiv id=\"graph\"\u003e\u003c/div\u003e\n  \u003c/div\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n```js\nimport { TreeHouze } from 'treehouze';\n\n// get graph's html elements\nlet elementWrap = document.getElementById('graph-view');\nlet elementGraph = document.getElementById('graph');\n// create graph instance\nlet graph = new TreeHouze(elementWrap, elementGraph, opts);\n// set options\nlet opts = {\n  nodestate: (node) =\u003e return node.state,\n  // some defaults listed below\n  ctrls: { enabled: true },\n  nodekinds: {\n    'doc': '#3e5c50',\n    'template': '#F8F0E3',\n    'zombie': '#00000000',\n  },\n  nodetypes: {\n    'default': \"#31AF31\",\n  }\n};\n// create data payload\nlet data = {\n  'nodes': [\n    {\n      id: '12345',        // used for linking nodes\n      label: 'label-txt', // used to label nodes\n      kind: 'nodekind',   // used to colorize nodes and for filtering\n      type: 'nodetype',   // used to colorize nodes\n      state: 0,           // used to calculate glow strength ('ctx.shadowBlur')\n    },\n    // ...\n  ],\n  'links': [\n    {\n      kind: 'linkkind',  // used for filtering\n      source: '12345',   // should be a node id\n      target: '67890',   // should be a node id\n    },\n    // ...\n  ],\n};\n// draw graph\ngraph.draw(data, opts);\n```\n\n## API\n\n### `data`\n\nGraph data -- should contain `nodes` and `links`:\n\n#### `nodes`\n\n```json\n{\n  \"id\": \"12345\",        // used for linking nodes\n  \"label\": \"label-txt\", // used to label nodes\n  \"kind\": \"nodekind\",   // used to colorize nodes and for filtering\n  \"type\": \"nodetype\",   // used to colorize nodes\n  \"state\": 0,           // used to calculate glow strength ('ctx.shadowBlur')\n  // (web-only)\n  \"neighbors\": {        // used to highlight neighboring nodes\n    \"nodes\": [],        // array of neighbor node ids\n    \"links\": [],        // array of neighbor links\n  },\n  // (tree-only)\n  \"lineage\": {          // used to highlight lineage nodes\n    \"nodes\": [],        // array of lineage node ids\n    \"links\": [],        // array of lineage links\n  },\n},\n```\n\n#### `links`\n\n```json\n{\n  \"kind\": \"linkkind\",  // used for filtering\n  \"source\": \"12345\",   // should be a node id\n  \"target\": \"6789\",    // should be a node id\n},\n```\n\n#### `draw([data][, opts])`\n\nDraw the graph from the given `data`. If redrawing the graph, `data` may be empty. `opts` may be used to reset any graph options.\n\n### Options\n\n#### `centerSpeed: number`\n\nSpeed at which to center nodes (3D-only).\n\nDefault is `1000`.\n\n#### `colors: { string: string }`\n\nHash of graph object names to color hexes.\n\nDefaults:\n\n```json\n{\n// graph\n\"background\": \"#000011\",\n// node\n\"text\"      : \"#e6e1e8\", // node labels\n\"band\"      : \"#44434d\", // node band\n\"current\"   : \"#F0C61F\", // 'current node'\n// link\n\"link\"      : \"#44434d\",\n\"particle\"  : \"#959396\", // link particles\n}\n```\n\n#### `current(node): boolean`\n\nA function that should return if a given node is the 'current' node. The current node will glow a specific color, to distinguish it from its type.\n\nDefault is:\n```js\n(node) =\u003e { return false; }\n```\n\n#### `dagHeight: number`\n\nA number value to set the height of each level in the tree graph.\n\nDefault is `100`.\n\n#### `nodekinds: { string: string }`\n\nA record that maps `nodekind` name strings to hex color strings; value can be a string or a function that returns a string.\n\nDefaults are:\n\n```json\n{\n  \"doc\"     : \"#3e5c50\",\n  \"template\": \"#F8F0E3\",\n  \"zombie\"  : \"#959DA5\",\n}\n```\n\n#### `nodetypes: { string: string }`\n\nA record that maps `nodetype` name strings to hex color strings; value can be a string or a function that returns a string.\n\nDefault is:\n\n```json\n{\n  \"default\": \"#3e5c50\"\n}\n```\n\n#### `ctrls`\n\nOptions for graph controls.\n\nAll boolean `ctrls` default to `true`.\n\n##### `ctrls.autosync: boolean`\n\nSet auto-sync to on/off.\n\n##### `ctrls.click: boolean`\n\nSet default node clickability to on/off.\n\n##### `ctrls.dim: '2d' | '3d' | 'vr' | 'ar'`\n\nWhat `dim`ension to render the graph in. Can be: `2d`, `3d`, `vr`, or `ar` (See `DimEnum` for details).\n\nDefault is `2d`.\n\n##### `ctrls.drag: boolean`\n\nSet default node draggability to on/off.\n\n##### `ctrls.enabled: boolean`\n\nEnable or disable graph controls.\n\n##### `ctrls.exclude: string[]`\n\nWhich controls to exclude. Can be: `kind`, `dim`, `filter`, `fix`, `flip`, `follow`, `glow`, `autosync`, `click`, `drag`, `hover`, `save`, `sync`, `data`. (See `CtrlEnum` for details).\n\nDefault is an empty array.\n\n##### `ctrls.filter: { nodes: }`\n\nAn object with `nodes` and `links` keys that point to arrays of string values from `doc`, `template`, and `zombie` (see `NodeKindEnum`) and `fam` for the tree graph and `attr`, `link`, `embed` for the web graph (see `LinkKindEnum`).\n\n##### `ctrls.fix: boolean`\n\nSet default of fixed (sticky) nodes (as opposed to force (free-floating)) to on/off.\n\n##### `ctrls.follow: boolean`\n\nSet default of active node following to on/off.\n\n##### `ctrls.hover: boolean`\n\nSet default node hoverability to on/off.\n\n##### `ctrls.glow: boolean`\n\nSet default glow to on/off.\n\n##### `ctrls.kind: 'tree' | 'web'`\n\nWhich kind  of graph to draw. Can be: `'tree'` or `'web'` (can access via `GraphKindEnum` for details).\n\nDefault is `web`.\n\n### Overridable Methods\n\nThe following methods provide default behavior for interacting with the graph. They may be overriden by subclassing the graph and provding your own implementation and/or calling `super.\u003cmethod\u003e()`.\n\n#### Graph Actions\n\n#### `onClickNode(node, event)`\n\nCenters the node in the graph. If `shift` is also pressed, then the node is added to `selectedNodes`.\n\n#### `onDragNode(node, translate)`\n\nDrags node along cursor path.\n\n#### `onDragEndNode(node)`\n\nEnds dragging a node. The node will stay in place if [`fix`](#ctrlsfix-boolean) is set to `true.\n\n#### `onHoverNode(node, prevNode)`\n\nHighlights the hovered node and either its `neighbors` in the `web` graph or its `lineage` in the `tree` graph. All links connecting these nodes will highlight.\n\n#### `onHoverLink(link)`\n\nHighlights the hovered link and the two nodes it connects to.\n\n#### `onSelectStart(evt)`\n\nBegin box selection of multiple nodes.\n\n#### `onSelect(evt)`\n\nSelecting multiple nodes via box selection.\n\n#### `onSelectEnd(evt)`\n\nEnd selecting multiple nodes via box selection.\n\n#### Graph Properties\n\n#### `autosync(data)`\n\nRedraws the graph from the given data. This method is unused internally and is meant for auto-syncing with whatever system is managing this graph instance.\n\n#### `save()`\n\nReturns the internal `dataCache`.\n\nThis method is recommended to be overriden: It is useful for saving the graph data. It is called when the user clicks the `save` data button.\n\n#### `sync()`\n\nRedraws the graph from the internal `dataCache`.\n\nThis method is recommended to be overriden: It is useful for syncing the graph data between some other source and itself. It is called when the user clicks the `sync` button and is meant for auto-sync-ing if implemented downstream.\n\n#### force-graph\n\nAs a sidenote, this project showcases a unified instance of [@vasturiano's](https://github.com/vasturiano) force-graph libraries ([2D](https://github.com/vasturiano/force-graph), [3D](https://github.com/vasturiano/3d-force-graph), [VR](https://github.com/vasturiano/3d-force-graph-vr), [AR](https://github.com/vasturiano/3d-force-graph-ar)).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwikibonsai%2Ftreehouze","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwikibonsai%2Ftreehouze","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwikibonsai%2Ftreehouze/lists"}