{"id":21951025,"url":"https://github.com/fr0stbyter/faust-ui","last_synced_at":"2025-04-23T03:27:51.755Z","repository":{"id":42204180,"uuid":"192998848","full_name":"Fr0stbyteR/faust-ui","owner":"Fr0stbyteR","description":"Faust UI Compositor","archived":false,"fork":false,"pushed_at":"2025-01-24T09:50:25.000Z","size":6022,"stargazers_count":23,"open_issues_count":5,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-15T19:04:56.396Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Fr0stbyteR.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-20T23:24:25.000Z","updated_at":"2025-04-03T05:35:17.000Z","dependencies_parsed_at":"2024-10-26T03:22:50.642Z","dependency_job_id":"190d2df0-f3ed-4acb-ba54-0fa33ecf09d2","html_url":"https://github.com/Fr0stbyteR/faust-ui","commit_stats":{"total_commits":113,"total_committers":2,"mean_commits":56.5,"dds":0.07964601769911506,"last_synced_commit":"c637349d2dccda5aef9a8dd880cea9c5d94357df"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fr0stbyteR%2Ffaust-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fr0stbyteR%2Ffaust-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fr0stbyteR%2Ffaust-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fr0stbyteR%2Ffaust-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Fr0stbyteR","download_url":"https://codeload.github.com/Fr0stbyteR/faust-ui/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250363495,"owners_count":21418269,"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-11-29T06:11:28.569Z","updated_at":"2025-04-23T03:27:51.733Z","avatar_url":"https://github.com/Fr0stbyteR.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FaustUI [![Badge](https://img.shields.io/badge/link-996.icu-%23FF4D5B.svg?style=flat-square)](https://996.icu/#/en_US)\n\nThis project is an user interface parser, compositor and components renderer for Faust Programming language. [Faust user interface widgets/primitives](https://faust.grame.fr/doc/manual/index.html#user-interface-primitives-and-configuration) allow for an **abstract** description of a user interface from within the Faust code. This description is independent from any GUI toolkits/frameworks and is purely abstract. Widgets can be **discrete** (e.g., `button`, `checkbox`, etc.), **continuous** (e.g., `hslider`, `vslider`, `nentry`), and  **organizational** (e.g., `vgroup`, `hgroup`).\n\nDiscrete and continuous elements are signal generators. For example, a `button` produces a signal which is 1 when the button is pressed and 0 otherwise: \n\nWhen a Faust DSP code is compiled, a corresponding JSON file will be generated with data related to the DSP including its UI structure information. FaustUI takes these information as input in order to generate an user interface in an HTML environment with hooks to communicate with the actual DSP.\n\n## Communicator\n`./src/FaustUI.ts` is the main class that can be loaded in a seperate browser `window` or `iframe`. the class listens to messages that comes by `window.postMessage`.\nTwo type of messages are listening by the `FaustUI` class. \n1. Parameter change: If the message has a `type` key with a value of `param`, the corresponding UI component with a same parameter path will display the changed parameter.\n2. New UI: If tye message has a `type` key with a value of `ui`, the class will re-render the incoming new UI.\n\nWhen a message is received, the window that initiated this message will be considered as the `host`. Then if a UI component is changed by user, the component will call `FaustUI` class's `paramChangeByUI` function which posts a `param` message to the `host` window. \n\nUser can also override the `paramChangeByUI` function or manually call `paramChangeByDSP` method to communicate differently with the UI or the DSP.\n\nOnce a new UI needs to be rendered, the class will firstly send it to a layout parser/calculator in order to get the coordination and size of each component.\n\n## Parser\nA structure definition of the UI information provided by Faust compiler can be found in `./src/types.d.ts`. The parser `./src/layout/Layout.ts` analyses the raw UI object recursively, then transform each UI component into a corresponding layout class instance. The class adds the dimensions and methods of components in order to calculate and adjust the position and the size of them. \n\n### Grid system\nThe layout calculation uses `grids` as unit as components has an original width and height in `grids`. Once the layout is calculated, the amount of grids of each components should be fixed. Renderer can simply multiply these amount by a factor to change the actual relative size without recalculating their positions and dimensions.\n\n### Primitives and their variations\nFaust have 3 organizational UI primitives, aka groups, a group contains other UI items that can also be groups: \n\n`vgroup` for a group whose items are aligned vertically\n\n`hgroup` for a group whose items are aligned horizontally\n\n`tgroup` for a group that has tabs to switch panels for each item.\n\n5 \"input\" UI primitives that are UI-to-DSP controllers:\n\n`button` for a buton that gives `1` on press and `0` on release.\n\n`checkbox` for a toggle that gives `1` or `0` by its state.\n\n`hslider` for a horizontal slider.\n\n`vslider` for a vertical slider.\n\n`nentry` for a numerical entry that is basically an input box\n\n2 \"output\" UI primitives that are DSP-to-UI monitors:\n\n`hbargraph` for a horizontal bar-graph that can be used to show any number in range. (e.g. signal level meter)\n\n`vbargraph` for a vertical bar-graph\n\nBy defining a `style` metadata, user can eventually override the look of a UI primitive. Variations that are supported officially for `hslider`, `vslider` and `nentry`:\n\n`knob` (`[style:knob]` Metadata) for a rotary control knob\n\n`menu` (`[style:menu{'Name0':value0;'Name1':value1}]` Metadata) for a drop-down menu that provide options and their values.\n\n`radio` (`[style:radio{'Name0':value0;'Name1':value1}]` Metadata) for a radio menu.\n\n`hbargraph` and `vbargraph`'s variations:\n\n`led` (`[style:led]` Metadata) for a colored light.\n\n`numerical` (`[style:numerical)` Metadata) for a numerical box that displays only values.\n\n### Sizing\nEach UI component has its initial dimensions in grids. Then some of them can be extensible in one or two axis if they have extra spaces. \n\n| type      | vertically extensible          | horizontal extensible          |\n|-----------|--------------------------------|--------------------------------|\n| hgroup    | if has v-extensible descendant | if has h-extensible descendant |\n| vgroup    | if has v-extensible descendant | if has h-extensible descendant |\n| tgroup    | if has v-extensible descendant | if has h-extensible descendant |\n| button    | no                             | yes                            |\n| checkbox  | no                             | yes                            |\n| hslider   | no                             | yes                            |\n| vslider   | yes                            | no                             |\n| nentry    | no                             | no                             |\n| knob      | no                             | no                             |\n| menu      | no                             | yes                            |\n| radio     | yes                            | yes                            |\n| hbargraph | no                             | yes                            |\n| vbargraph | yes                            | no                             |\n| led       | no                             | no                             |\n| numerical | no                             | no                             |\n\n### Padding\nIn order to render the layout elegantly, some paddings are added to the groups and between each items. These values can be found under `./src/layout/AbstractGroup.ts`. \n\n## Layout Calculation\nThe layout calculation is done in 4 phases:\n1. inject height and width information to each items.\n2. calculate groups' initial size by sum up descendants' size.\n3. expand items if they are extensible. The extra space in a group should be shared by all extensibles.\n4. calculate the coordination of each item, align them to the middle line of the group. This adds absolute position (x, y relative to root: `left` and `top`) and relative position (x, y relative to parent group: `offsetLeft` and `offsetTop`).\n\nEach phase of the calculation is called recursively and initiate by a \"root\" group. Thus once it's calculated, the \"root\" group and its descendants contains all information about position and size.\n\n## Rendering\nComponent rendering constructors can be found below `./src/components` folder. After the layout calculation, `FaustUI` construct the `root` group with the group constructor that will construct all its descendants.\n\nThe UI rendering is also done in 4 phases:\n1. construct each component by its corresponding class constructor. The component register itself using `FaustUI` class's `register` method.\n2. `componentWillMount` method is called by a component's parent group, the component should prepare all DOM elements that need to be mounted to DOM tree.\n3. `mount` method is called by a component's parent group, the component should get its `container` mounted with children DOM elements. Then the parent group will fill its `container` by its children's `container`s.\n4. `componentDidMount` method is called by a component's parent group, the component now have all its DOM elements connected to the page. Thus their `getBoundingRect` method can be used in order to justify and draw canvas etc. It should also bind events to state changes in this phase.\n\nA more detailed description of UI component class can be found in `./src/components/Component.ts`\n\n## Building\nInstall dev dependencies:\n\n```bash\nnpm install\n```\n\nIf you don't want to build the minified js for testing purpose:\n\n```bash\nnpm run build\n```\n\nOtherwise use:\n\n```bash\nnpm run dist\n```\nTo test, put the directory in a local server, then open the following page: `./dist/test.html`\n\n## Versioning \nYou'll have to raise the package version number in `package.json` for `npm run update` to properly work.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffr0stbyter%2Ffaust-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffr0stbyter%2Ffaust-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffr0stbyter%2Ffaust-ui/lists"}