René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"UI interface & bindings design","articleBody":"The UI package should basically behave like a design system - exporting various typescript components which render to the terminal using tty (aka clayterm right now).\n\nLet's use this issue to decide the rough structure of the following:\n\n- What belongs in bindings vs the main package\n- What does the usage look like?\n- What initial components we should export\n\n## Initial components\n\nWe can start with:\n\n- Window (or \"region\")\n- Text\n- Box\n\n### Window / Region\n\nWhen creating a TUI, the root is a region of the terminal (columns & rows). To this, we render components which have been composed in a DOM-like tree.\n\n### Text\n\nRender text to the window.\n\n```ts\ninterface TextProps {\n  value: string;\n  color: string;\n  bgColor: string;\n  bold: boolean;\n  underline: boolean;\n}\n```\n\n### Box\n\nRender a box in the window which can contain other components.\n\n```ts\ninterface BoxProps {\n  width: unknown; // what is this? a number?\n  height: unknown; // what is this? a number?\n  padding?: {\n    top?: number;\n    right?: number;\n    down?: number;\n    left?: number;\n  };\n  bgColor?: string;\n  borderTop?: { width: number; color: string; };\n  borderRight?: { width: number; color: string; };\n  borderBottom?: { width: number; color: string; };\n  borderLeft?: { width: number; color: string; };\n}\n```\n\n- Any other properties we're missing here?\n- What about margin?\n\n## Usage / API\n\nWe need to decide what the right API shape is. Something like this:\n\n```ts\nconst doc = ui.createWindow({\n  width: 200,\n  height: 100,\n});\n\ndoc.render(new ui.Box(\n  {}, // properties of a box\n  [ // children of a box\n    new ui.Text('Foo')\n  ]\n));\n```\n\nThis is just quick pseudo-code. We need to iterate on this together to figure out the right shape.\n\nA few important things to take into account:\n\n- We should be able to pass our own writable stream in (i.e. no hard-coded `process.stdout` anywhere other than the default options)\n- Not all components should have children, so we need to control that per component type\n- Although we will have bindings, many will use this package directly, so this shape matters just as much\n- Initially, we don't need to care about multiple regions\n\n## How bindings work\n\nOnce we have a working UI package, we can create \"bindings\" for these. For example, solid or svelte bindings (aka integrations).\n\nA binding implementation should allow you to use all the base components UI provides but in whatever way the chosen framework/library prefers (e.g. using signals).\n\nThis means every binding implementation should basically export all the same components as the UI package but as wrappers which tie into the integration.\n\n## Open questions\n\n- We haven't yet decided how this root window/region works. Given our focus is TUIs here, we do need some root component to allow people to just drop a tree of components in and it automatically be responsive etc. What should that look like in typescript?\n- What is missing from clayterm/tty that we need in order to deliver these base components? (if anything)\n","author":{"url":"https://github.com/43081j","@type":"Person","name":"43081j"},"datePublished":"2026-06-13T13:48:52Z","url":"https://github.com/bombshell-dev/ui/issues/2"}