{"id":13554109,"url":"https://github.com/apnex/fractal","last_synced_at":"2025-04-03T06:31:06.614Z","repository":{"id":143858668,"uuid":"135673998","full_name":"apnex/fractal","owner":"apnex","description":"Project Fractal is a prototype 'Diagram-as-Code' framework to render structured geometric recursive topological diagrams in SVG format","archived":false,"fork":false,"pushed_at":"2018-06-11T13:33:26.000Z","size":94,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-04T02:32:44.637Z","etag":null,"topics":["as-code","diagram","fractal","network","svg"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apnex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-06-01T05:58:18.000Z","updated_at":"2022-09-14T10:46:12.000Z","dependencies_parsed_at":"2024-01-19T17:57:20.496Z","dependency_job_id":"f104e7f2-a5dd-411b-8bc5-2589bed33229","html_url":"https://github.com/apnex/fractal","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apnex%2Ffractal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apnex%2Ffractal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apnex%2Ffractal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apnex%2Ffractal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apnex","download_url":"https://codeload.github.com/apnex/fractal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246947894,"owners_count":20859338,"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":["as-code","diagram","fractal","network","svg"],"created_at":"2024-08-01T12:02:39.760Z","updated_at":"2025-04-03T06:31:06.128Z","avatar_url":"https://github.com/apnex.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","others"],"sub_categories":[],"readme":"#### What\nFractal is both an image format specification, and an engine to render that format.  \nIn essence, Fractal allows you to focuse on the intent of your diagram and ask the engine to determine placement and method to correctly render it.  \nSelf-contained, pure javascript, browser rendered.  \nSVG path object coordinates are always represented as whole integers - no fractions ever.  \nRecursive rendering  \nJSON Defined  \nAutomatic scaling  \nDeterministic outcome  \nPerfect Alignment of nodes  \n![nodeCluster](./examples/nodeCluster.svg)\n\n![nodeClover](./examples/nodeClover.svg)\n\n![nodeCpu](./examples/nodeCpu.svg)\n\n![nodeRouter](./examples/nodeRouter.svg)\n#### Problem\ncreate new diagrams are hard  \nx,y positioning is annoying  \nalignment of object is annoying  \nlinking objects is manual  \nchanges after-the-fact are hard  \nsymmetry, node placement, and line-routing techniques are manual and error prone    \n\n#### Intent\nHave an engine that allows one to create diagrams-as-code.  \nDiagrams result in a cleanly-defined, minimal SVG image format  \nAvoid manual x,y placement - all 'nodes' are automatically relatively aligned to geometric infrastructure of schema.  \nRecursive in nature - schemas can externally referenced and reused, and schemas can be nested for recursive rendering.    \nTemplates can be build as infrastructure for node placement, nodes can then be added after the fact.  \n\n#### Setup\n- Create a plain html file, and link `head.load.js` in the `head` of the document.  \n- Load the `fractal.js` engine along with the initial fractal **schema** to render - in this case `example1.js`.  \n- Finally, create an anchor `svg` element, and call the `fractal.render` method via the `svg.onload` attribute.  \n- Pass in a function to the `render` method - this function is specified in the `example1.js` asset\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\t\u003chead\u003e\n\t\t\u003cscript src=\"head.load.js\"\u003e\u003c/script\u003e\n\t\t\u003cscript\u003e\n\t\t\thead.load([\n\t\t\t\t'fractal.js',\n\t\t\t\t'example1.js'\n\t\t\t]);\n\t\t\u003c/script\u003e\n\t\u003c/head\u003e\t\n\t\u003csvg id='core' onload='start()' xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\"\u003e\n\t\t\u003cscript\u003e\n\t\t\t\u003c![CDATA[\n\t\t\t\tfunction start() {\n\t\t\t\t\tfractal.render(example1());\n\t\t\t\t}\n\t\t\t]]\u003e\n\t\t\u003c/script\u003e\n\t\u003c/svg\u003e\n\u003c/html\u003e\n```\n\nWith a correctly formatted **schema**, the `fractal.js` engine will render the resultant object returned from `example()`, as a set of svg constructs.  \n\n#### Schemas\n##### So what is a **schema** and how do you define one?\nPut simply, a fractal schema is a json object structured in certain way to define the relationship, relative position, size and style of **nodes** on a diagram.  \nIt defines where **nodes** are placed, relative to one-another, along with hints for css attributes (stroke, stroke-width, fill etc..).  \nA **schema** also provides additional syntax to control certain construction attributes to influence placement, style and links between nodes.  \n\n- **`body`**  \n`body` is a 2 dimensional **ARRAY** of labels.  \nIt defines the *relative* spatial position of cells with respect to each other on the page.  \nThis is essentially used as a grid of coordinates to place `cells`.  \nThe `\u003ccell-label\u003e` is an arbitrary user-defined **INTEGER** that references the grid location.  \nThis is used by the `map` construct to decide what gets rendered there.  \n`\u003ccell-labels\u003e` do not have to be unique - this allows for a `node` to be duplicated at multiple locations.  \nSyntax of a cell `body` is:  \n```javascript\nbody: [\n\t[\u003ccell-label1\u003e, \u003ccell-label2\u003e ... \u003ccell-label3\u003e],\n\t[\u003ccell-label1\u003e, \u003ccell-label2\u003e ... \u003ccell-label3\u003e],\n\t                      .\n\t                      .\n\t                      .\n\t[\u003ccell-label1\u003e, \u003ccell-label2\u003e ... \u003ccell-label3\u003e]\n]\n```\n- **`map`**\nthe map does stuff  \ntalk about the map overrides\n- `link`\nlinks do stuff\n- `size`\nsize is important\n- `style`\nstyles well - style things\n- `opts`\nopts do things\n\nFor the **schema** file, it is defined as an external javascript asset (like `example1.js` above), with a single function returning a json object.  \nSyntax of a single `cell` is:  \n```javascript\ncell: {\n\tbody: [\n\t\t[\u003ccell-label1\u003e, \u003ccell-label2\u003e ... \u003ccell-label3\u003e],\n\t\t[\u003ccell-label1\u003e, \u003ccell-label2\u003e ... \u003ccell-label3\u003e],\n\t\t                      .\n\t\t                      .\n\t\t                      .\n\t\t[\u003ccell-label1\u003e, \u003ccell-label2\u003e ... \u003ccell-label3\u003e]\n\t]\n}\n```\nThis looks like:  \n```javascript\nfunction example1() {\n\treturn {\n\t\tbody: [\n\t\t\t[0]\n\t\t],\n\t\tmap: {\n\t\t\t0: {}\n\t\t}\n\t};\n}\n```\n\nThis is the smallest possible **schema** definition supported by fractal to visibly render an object to the page.  \nThe resultant image rendered in the browser is:  \n![example1](./examples/example1.svg)  \n**Note:** As we did not specify any `opts` or a `style` to this object, CSS attributes have inherited their defaults.  \n\n#### Examples\nA number of examples for different diagram construction methods.  \nFor purposes of brevity - the `function` and `return` statements will be ommitted, with the examples instead focusing on their json construction syntax.  \n\n##### oneNode\nThis example shows a single node.\nIt also defines `size`, `opts`, and `style` attributes.  \n![test](./examples/oneNode.svg)  \n```javascript\n{\n\tbody: [\n\t\t[0]\n\t],\n\tmap: {\n\t\t0: {\n\t\t\tsize: {\n\t\t\t\tx: 8, y: 8\n\t\t\t},\n\t\t\topts: {\n\t\t\t\tradius: 20\n\t\t\t},\n\t\t\tstyle: {\n\t\t\t\t\"stroke\": \"mBlue-700\",\n\t\t\t\t\"stroke-width\": 4,\n\t\t\t\t\"fill\": \"mYellow-300\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n- 9-Node  \n- 9-Node-Gap  \n\n#### TODO - in no particular order\n##### Engine\n- Use javascript to dynamically specify svg element height/width at build time\n- Anchor resultant image at 0,0 within SVG, and use HTML CSS to shift asset into viewable window\n- Allow for native SVG/PNG export (via right-click)\n- Replace head.js with custom, minimal asset loader with added svg embedded script load support\n- Implement lexical local/global link tags\n- Implement proper {style} inheritance between cell parents and children - currently broken - need to merge {style} attrs\n- Optimise and collapse engine components (fewer js files)\n- Collapse {size} into {opts} construct\n- Correct global {opts} inheritance\n\n##### Compiler\n- Optimise resultant SVG to leverage chained \u003cuse xlink\u003e for smaller output\n- Deduplicate CSS classes and move to defs\n- Add circle and rect support for compiled output\n\n##### Interface\n- Add svg text support\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapnex%2Ffractal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapnex%2Ffractal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapnex%2Ffractal/lists"}