dennisreimann / uiengine

Workbench for UI-driven development

UIengine

Workbench for UI-driven development: A tool for developers and designers to build and document web sites and apps.

Useful if you want to …

• Create a living pattern library
• Document your design system
• Prototype with your apps components and templates
• Use code as a single source of truth

🚀 What it enables

• Establish a UI-driven workflow and structure your web UI into modular components.
• Give your team and stakeholders a central spot to develop and discuss the UI.
• Replace deliverables with usable, testable and production ready output/code.
• Make documentation fun and easy by providing structure and nice looking pages.

🏎 Quickstart

To explore the features yourself you can quickly initialize a project with some demo content:

mkdir uiengine-demo && cd uiengine-demo && npm init -y
npm install @uiengine/core @uiengine/adapter-html --save-dev
npx uiengine init --demo
npx uiengine build --serve --watch

See the getting started guide for further details. There are also some introduction videos:

<iframe title="UIengine Introduction Videos" src="https://www.youtube-nocookie.com/embed/videoseries?list=PLBXz0hPvV2jNAFb9KxvV-2Op8cy3tA8E2" frameborder="0" allow="autoplay; encrypted-media; picture-in-picture" allowfullscreen></iframe>

🖥 Examples and Screenshots

To get an idea of what a real-world project looks like, see the React sample project:

• Tasty BBQ Design System: The UIengine output for this sample project
• Tasty BBQ Website: The corresponding website, built with React and Next.js.
• Tasty BBQ Source Code.

📘 Documentation

See the documentation site, which is also generated with the UIengine.

🔩 Technical TL;DR

⚒ How does it work?

At its core, the UIengine is a static site generator. It can be used in standalone mode or integrated into your build process.

➡️ Input: Your projects components, templates, pages and documentation

⬅️ Output: A static site that can be used as a workbench for development and deployed documentation

It consumes the files and structure of your project and generates the documentation based on this. In development mode the output is regenerated on file change and synced to the browser. This provides you with a development environment for creating the components, prototyping and writing the docs.

💯 Main features

• Templating agnostic: Various templating engines are integrated via adapters. This gives you flexibility of choice and the option to integrate custom ones. It works with whatever can be rendered via JavaScript, e.g. JSX, Vue, EJS, Pug/Jade, Handlebars.
• Prototyping environment: Build your UI without the need for an existing backend/API. Render your templates and components with mock data. Build various variants for pages by providing different data to your views.
• Best practice approach: The tool guides you towards best practices like the component folder pattern, the modlet workflow and by proposing a separation of data and template/component.
• In sync with the end product: The docs are generated from the code that is used in your application. Hence you get a living pattern library – not a separate thing that needs to be looked after regularly.
• Flexible integrations: Templating engines can be configured so you can fit it to your needs. Same goes for the markdown parsing/rendering which is configurable too.
• Covers green- and brownfield projects: Whether you start out with a pattern library or want to transition your process and refactor your existing UI into modular components, the UIengine has you covered.

For the evaluation process you might also want to have a look at the alternatives.

🗜 Prerequisites

UIengine requires at least Node.js 16.16 (tracking the latest active Node.js LTS version). This guarantees a reasonable level of backwards compatibility.

🖖 Alternatives

OK, the UIengine looks really cool but it's not quite what you are looking for? Or you want to first compare a few solutions to see which one is the right fit? Here are some other projects that you might want to evaluate:

• Storybook
• Pattern Lab
• or have a look at the ever growing list of similar tools.

🛠 Development

You like this project and are interested in participating? See the development docs for an introduction and workflows when hacking on the UIengine.

✨ Contributors

Thanks goes to these wonderful people:

Jan Persiel 🎨

Cos Anca 🎨 💻

Michael Geers 💻

Matteo Fogli 💻

Jonas Havers 📖

René Mäkeler 💡

This project follows the all-contributors specification. Contributions of any kind welcome!

---

👨🏻‍💻 Brought to you by the nice people behind UIengineering. 👨🏻‍💻

uiengine's Issues

Update default neutral colors and accent colors

Is your feature request related to a problem?
I find some of the default colors (especially the neutral colors) are "too gray-ish".

Describe the solution you'd like
Update the --uie-color-neutral-* and --uie-color-accent-* custom properties to slightly different shades from their current values.

Describe alternatives you've considered
Overwriting these custom properties work as well, but the main idea behind this request is to refresh the default overall look of the application.

Update inline code style

Is your feature request related to a problem? Please describe.
Currently for the inline code the only customisation is to change the background color which is sufficient for most cases. However, adding a slightly darker border around the inline code would make it "prettier" and stand out better from the rest of the text.

Describe the solution you'd like
Update the elements.styl file.
Potentially introduce a new custom property, like --uie-color-border-inline-code that will allow users to overwrite it.

Additional context
Refresh the overall look of the application.

Update the layout and style of the component content header

Is your feature request related to a problem? Please describe.
The current style looks a bit cluttered, especially when there are "Composed of...", "Used within..." and the list of links to the variants of the component available on the page. Also the style is pretty basic and there isn't really any visual hierarchy of all the elements included.

Describe the solution you'd like

• Increase the font-size of the title to create a better visual hierarchy of the page content.
• Vertically align all components in relation to the label (title).
• Update tab triggers style to look like a button group.
• Update tags and labels styles.
• Move the edit icon to the right hand side, before the button group to have all actions grouped together.
• Move the on-page navigation (the links to variants) to the right hand side of the window as a fixed component for a better overview and in-page navigation.

Additional context
Refresh the overall look of the application.

Change default font-family and improve font rendering

Is your feature request related to a problem?
On macOS font rendering is not as sharp as it could be.

Describe the solution you'd like
Replace current Merriweathersans font family with Inter and set -webkit-font-smoothing: antialiased; and -moz-osx-font-smoothing: grayscale; for smoother font rendering on macOS.

Describe alternatives you've considered
As Inter is pretty close to Arial and San Francisco font in macOS I've also thought of setting system-ui as the default font-family of the application.

There are both positive and negative things about using system-ui.

• Positive: The main advantage to this could be a slight performance improvement and FOUT avoidance (no need of font-display), also this means a reduced dependency in terms of assets (by removing the custom typeface) and implicitly a reduced overall weight of the project.
• Negative (and the reason I ended up proposing Inter): The default font will be different from one platform to another (macOS and iOS: San Francisco, Android and ChromeOS: Roboto, Windows: Segoe UI) so there will be a lot of inconsitencies cross platform.

The advantage of using Inter is that it also comes as a variable font (variable fonts support) so there can be only one file for all font weights and styles.

Additional context
Refresh the overall look of the application.

Re-add component source code

Describe the bug
Since version v2.2.0 the rendered HTML code source is missing. This is a side effect of removing the rendered HTML from the state (it did bloat it), but does not allow to access the HTML code rendered from the adapter. This is useful for integrators and developers adopting the component in its final rendered output instead of the template technology

To Reproduce
Steps to reproduce the behavior:

1. git checkout v2.1.0
2. yarn run test-project
3. open http://localhost:3000/patterns/molecules/formfield/
4. click on code
5. see HTML panel with rendered output
6. git checkout master
7. repeat steps 2-4
8. no HTML panel is visible

Expected behavior
see the HTML code block

Additional context
It should be fairly easy to use the iframe content instead of the rendered part previously stored in the vuejs store to restore the code panel. it could be loaded dynamically when the panel is opened to avoid bloating the DOM. Something along this.contentDocument.querySelector('#app').innerHTML.

Again I will take a chance at it with a PR, but I'm overwhelmed right now and it'll take some time.

Workaround
Update documentation 😇

Iframe not resizing properly after switching to jsx-adapter

Hey Dennis!

Describe the bug
I wanted to switch from the default template uiengine.html to a template using the jsx-adapter.
While this seemed to work at first, I noticed that after switching the iFrame of the variant-previews does not resize properly anymore.
For some reasons this only happens in Chrome and Safari. In Firefox it still works as expected.

To Reproduce
I have a minimal example repo here:
https://github.com/MrAvantiC/uiengine-jsx-template-demo

The relevant commit is this one:
https://github.com/MrAvantiC/uiengine-jsx-template-demo/commit/60af39f3d8ae7d7693d4c36ea05a032f7edc0302

Any idea what could cause this to happen?

Local sample server JS crashes on load - r.index is undefined

Describe the bug
Accessing localhost:3000 gives the error r.index is undefined. The UI admin page (Port 3001) works perfectly.

To Reproduce
Follow the steps in the example setup process up to npx uiengine build --serve --watch.

Expected behavior
I can see a rendered page.

Screenshots

Collaborate

Hey Dennis!

How are you? This looks like an awesome project you're working on!

Over at Storybook we're working on something very similar, and we have pretty much the same goals!

Would you be interested in collaborating on it?

I've tried ui engine's test example, and got it to work after just a little bit of puzzling, and I'm really impressed with it supporting so many frameworks already. Storybook supports React, React Native, HTML + Web Components, Angular, Vue, Polymer, and there is work on a few others by the community of maintainers.

Care for a chat?

Create and render custom ejs templates for tokens

Is your feature request related to a problem? Please describe.
I would like to be able to render the same tokens defined in the yaml files in different ways and also be able to control it.

Describe the solution you'd like
I was trying to create different ejs templates for the same tokens (ej. 2 custom templates for the same color tokens) so I can use them in different places.

Any thoughts on this?

Thanks!

Update iconography

Is your feature request related to a problem? Please describe.
Current icons used throughout the project have very thin strokes :)

Describe the solution you'd like
Having a new set of icons with a bit thicker stroke can make them stand out better.

Additional context
Refresh the overall look of the application.

Update style of the spaces token representation

Is your feature request related to a problem? Please describe.
Current representation of the spaces token has the potential of not giving an accurate "understanding at first glance" of the space applied to an element or component especially when applied on the Y axis (top and bottom).

Describe the solution you'd like

• Update the style of the token representation to render a square rather than a bar (this would give a better hint to users on the size of the rendered space they are about to use vertically on the components).
• Update the default background color and border color.
• Potentially add an option to toggle this representation to a bar (as currently) or a square.

Additional context
Refresh the default overall look of the application.

Update the layout and style of the icons token

Is your feature request related to a problem? Please describe.
The icons usage throughout a project is most of the time pretty general for every icon and can be documented in the markdown file that appears at the top of the token page.

Describe the solution you'd like

• Create a simpler style for icon representation, where only the actual icon and its name are showcased. This should create a better overview of the entire iconography stack of the project.
• Potentially introduce new custom properties for further customization, like: --uie-icon-token-background, --uie-icon-token-border-width, --uie-icon-token-border-style, --uie-icon-token-border-color and --uie-icon-token-border-radius.

Additional context
Refresh the default overall look of the application.

Assets path is not unified

Describe the bug
Hi, I just created a standalone index.html (npx uiengine build) and threw it onto my server under /doc.

Unfortunately, i could not display my documentation. I think its mainly because the path that is used for "_assets" is different on several occasions (sometime with /_assets and sometimes without

To Reproduce
Steps to reproduce the behavior:

1. "npx uiengine build" on any available project
2. Put the "/dist/*" contents onto a server domain subdirectory (like /test/)
3. Open your domain.tld/test/
4. See error

Expected behavior
I would like the complete working documentation here. Instead only some parts get loaded due to JS and CSS loading errors (try to load domain.tld/_assets/ instead of domain.tld/test/_assets/

Screenshots
imagine a white page with white letters and a white logo over white clouds

Keep initial page template in sync with getting started instructions

Describe the bug
The initial page (packages/cli/src/templates/initial_page.js) lists commands differently than the getting-started page (docs/getting-started.md), e.g. without "npx".

Expected behavior
The commands should be the same on both pages.
The two pages should be in sync, or at least the parts of them that list the commands.

Run demo

Hi, I'm try run demo but I get an error with the command "npm run demo"

14:41 $ npm run demo

> @uiengine/monorepo@ demo /Users/user/uiengine
> rimraf test/demo && sleep 1 && uiengine init --dir test/demo --demo && cd test/demo && uiengine build -s -w

sh: uiengine: command not found
npm ERR! file sh
npm ERR! code ELIFECYCLE
npm ERR! errno ENOENT
npm ERR! syscall spawn
npm ERR! @uiengine/monorepo@ demo: `rimraf test/demo && sleep 1 && uiengine init --dir test/demo --demo && cd test/demo && uiengine build -s -w`
npm ERR! spawn ENOENT
npm ERR!
npm ERR! Failed at the @uiengine/monorepo@ demo script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/user/.npm/_logs/2018-12-24T13_41_23_160Z-debug.log

Could not find module `babel-runtime` in @uiengine/theme

The getting started example throws an error when trying to start uiengine. Looks like babel-runtime dependency is missing.

$ uiengine build --watch --serve
🚧  Building …
🚨  Build failed!

Error: Could not load "@uiengine/theme" theme:

Error: Cannot find module 'babel-runtime/core-js/object/assign'
    at Function.Module._resolveFilename (module.js:536:15)
    at Function.Module._load (module.js:466:25)
    at Module.require (module.js:579:17)
    at require (internal/module.js:11:18)

We've been able to work around this by manually adding it to the projects dependencies. I'm not sure about the right place for this dependency.

Workaround:

npm install --save-dev babel-runtime

Custom script added to the uiengine.html template does not render

Hello Dennis!

I'm trying to add a custom script to the uiengine.html template but it's not rendering. It's like any change I make to the template does not render when building the application.

The config.js is correct, though.

Any ideas on why this might be failing?

Thanks!

Update the default style of the tables

Is your feature request related to a problem? Please describe.
Current table styles don't create a good distinction of the table header from the table body.

Describe the solution you'd like
Update elements.styl file with slightly improved styles for the tables

Additional context
Refresh the overall look of the application.

Extend tokens to include representations for other css properties

Is your feature request related to a problem? Please describe.
Currently tokens representation is only done for space, icons, colors and typography but there are many more other things that would bring valuable information to users through a representation.

Describe the solution you'd like

• Add representations for box-shadow, border-width, border-style, border-radius, opacity.

Additional context
Refresh the default overall look of the application.

Question - Sass Support

Is your feature request related to a problem? Please describe.
I looked through the documentation but I could not see how I would go about adding sass support to a project. Ideally I would add the main scss file here.

Describe the solution you'd like
I'd like to either know how to do this, or if you could point me in the right direction to how I can contribute this feature to the project.

Describe alternatives you've considered
I tried adding babel-plugin-sass-export as a plugin to the js adapter but it ended up crashing uiengine.

Support syntax highlighting for other languages

Is your feature request related to a problem? Please describe.
It looks like at the moment, only javascript syntax highlighting is supported

Describe the solution you'd like
Is there a way to to enable other languages such as Go, Java, etc.

If this feature does already exist here is what happens when I try to change the language (Go in this example)

and then here is the js (javascript example)

I have noticed that highlight-js does support Go and other languages.
https://highlightjs.readthedocs.io/en/latest/css-classes-reference.html

I wonder If I am doing something wrong.

Update the layout and style of the navigation sidebar

Is your feature request related to a problem? Please describe.
A major feature request from people interacting with the application was the ability to include a logo for the project.

Describe the solution you'd like

• Add option for project logo in uiengine.config.js file and render the logo at the top of the navigation sidebar.
• Relocate the project title from the topbar into the navigation sidebar and render it underneath the logo for increased identity of the project.
• Create a simpler, minimal style with better spacing for the navigation items and move carets (sub-navigation toggle buttons) to the right.

Additional context
Refresh the overall look of the application.

"getting started" setup fails

Describe the bug
I cannot start the demo as described in https://uiengine.uix.space/basics/getting-started/

To Reproduce
follow steps from https://uiengine.uix.space/basics/getting-started/
the step
npx uiengine build --serve --watch
fails.

Expected behavior
a basic UIengine demo project running.

Screenshots
If applicable, add screenshots to help explain your problem.

Additional context
node -v
v8.15.0
npm -v
6.4.1

console output:
/uiengine-demo$ npx uiengine build --serve --watch
🚨 Build failed!

TypeError: Expected cwd to be of type string but received type undefined
at module.exports (/home/boris/spoco-mce/uiengine-demo/node_modules/dir-glob/index.js:44:25)
at globDirs (/home/boris/spoco-mce/uiengine-demo/node_modules/globby/index.js:58:9)
at getPattern (/home/boris/spoco-mce/uiengine-demo/node_modules/globby/index.js:61:64)
at Promise.all.globTasks.map.task (/home/boris/spoco-mce/uiengine-demo/node_modules/globby/index.js:72:69)
at Array.map ()
at module.exports (/home/boris/spoco-mce/uiengine-demo/node_modules/globby/index.js:72:41)
at findPageIds (/home/boris/spoco-mce/uiengine-demo/node_modules/@uiengine/core/src/page.js:57:27)
at Object.fetchAll (/home/boris/spoco-mce/uiengine-demo/node_modules/@uiengine/core/src/page.js:67:25)
at Object.generate (/home/boris/spoco-mce/uiengine-demo/node_modules/@uiengine/core/src/core.js:68:29)
at

debounce is not a function when changing uiengine.config.js

uiengine crashes with the following error, when I change the uiengine.config.js file in the root directory of the project.

$ uiengine build --serve --watch
[...]
Watching files...
./node_modules/@uiengine/core/lib/uiengine.js:66
    return debounce('handleFileChange', () => {
           ^

TypeError: debounce is not a function
    at handleFileChange (./node_modules/@uiengine/core/lib/uiengine.js:66:12)
    at FSWatcher.chokidar.watch.on.on.on.filePath (./node_modules/@uiengine/core/lib/uiengine.js:82:206)
    at emitTwo (events.js:126:13)
    at FSWatcher.emit (events.js:214:7)
    at FSWatcher.<anonymous> (./node_modules/chokidar/index.js:199:15)
    at awfEmit (./node_modules/chokidar/index.js:216:9)
    at FSWatcher.<anonymous> (./node_modules/chokidar/index.js:319:9)
    at FSReqWrap.oncomplete (fs.js:153:5)

Add tags for pages and components

React Context not available in components

Hey Dennis!
Sorry for this neverending story, but I have another problem using the jsx/webpack adapter. :/

Describe the bug
We have a use case where we need data available to every component. To avoid "prop drilling" we want to make use of the Context-API for this.

I tried to make use of the react-server-render and react-client-render for this to make the context available to every component/variant in UIEngine.
This looked good at first, since the Context-Provider showed up in the component tree:

Unfortunately, the actual context is not accessible in the components of the UIEngine. It appears like the context is not passed through to all the underlying components.

To Reproduce
Steps to reproduce the behavior:

1. A minimal example of the problem can be found here: https://github.com/MrAvantiC/uiengine-context
2. Install dependencies and start development server
3. See the console-ouput of the render() method in <Footer />

Expected behavior
The context should be available in the <Footer /> component.
I can confirm that the same code works in CRA/Next.js.

Kind regards,
René

Documentation about Design Tokens

Description
The documentation talks about defining the design-tokens in the configuration of the page (page.config.js). The example project has them all definied inside the main configuration-file (uiengine.config.js).

You should align the description with the example.

UIEngine and i18n

Hey Dennis,
I have a question regarding how to handle i18n in UIEngine, maybe you have some experience here already.
What I already did is setup a basic setup using react-i18next which can be found here:
https://github.com/MrAvantiC/uiengine-i18n

One constraint I have is, that since I want to use components that are built in the UIEngine later in our Next.js application, I have to differentiate where to import the relevant functions to translate texts from.
In case of Next.js that means I need the functions of the next-i18next package whereas in UIEngine I'd need the same function of the react-i18next package.

I managed to solve this by "injecting" the translation-function using the webpack-renderers for each component, like this:

const { useTranslation } = require('react-i18next')

module.exports = function serverRender(Component, props) {
  const newProps = { ...props, useTranslation }

  return renderToString(Component(newProps))
}

...which allows me to use them in the Component itself.
Now, I'm able to do the same in Next.js when I use the component, which works fine for now.

What doesn't work yet

I would really like to display the different translations as variants in UIEngine. Unfortunately, I have not yet found a way to achieve that.

Approach 1
My first approach was to change the language of react-i18next based on the property I pass into each component.
So, my variant would be called like this:

// Footer/variants/german.jsx

import React from 'react'
import Footer from '../Footer.jsx'

// the default language is set to en
export default props => <Footer {...props} language='de'/>

...and then use it when webpack renders the component, like that:

module.exports = function serverRender(Component, props) {
  const { language } = props
  // change language based on prop

Contrary to my assumptions on how the build-process works, the props in this function are not the ones passed into the variant but are instead always empty. So this doesn't work... :/

Approach 2
The other place where I could think of to setup the language without actually affecting the implementation of the component itself was to change the language when configuring the variants:

// Footer/variants/german.jsx

import React from 'react'
import Footer from '../Footer.jsx'
import i18n from '../../../../i18n/i18n'

export default props => {
  i18n.changeLanguage('de') // the default language is set to en

  return <Footer {...props} />
}

Strangely enough, this seems to work on the server side - so the initial html contains the german translation - and then on client-side hydration, it changes back to the default (english) translation.

I can't figure out at the moment why this behaves differently on the client-side.
Do you have an idea what is missing here, or maybe even a better approach in the first place? :)

Regards,
René

use CSS in create-react-app style

Greetings, we have a react component that looks like this:

import React from 'react'
import './test.css'

export default function(props) {
  return <h1 className="test123">Testing!</h1>
}

A "create-react-app"-app understands this css import(css-loader in webpack probably). How can we make uiengine do the same?

UIEngine Quickstart failing on Windows at the last step (npx uiengine build --serve --watch)

uiengine build failed!
All prior steps were taken and executed as expected.

C:\box\react\uiengine-demo
$ npx uiengine build --serve --watch
🚨  Build failed!

Child page "elements" does not exist for page "patterns".
Here is a list of available child pages:
- patterns\components
- patterns\elements

Steps to reproduce the behavior:

1. Use Windows and follow the README.md steps

Adding a FE framework's CSS and JS only once.

I've just installed uiengine and added several components with variants.
I have the following in ./src/templates/variant-preview.pug :

doctype
html(class=`preview-${variant.id}`)
  head
    title= variant.title
    link(rel="stylesheet" href="../../../../uikit/dist/css/uikit-core.css")
  body
    != variant.rendered
    script(src="../../../../uikit/dist/js/uikit-core.js")

This is repeated in every component's iframe.

But I'd rather include the link and script of the FE framework only once. Is this possible ?
Probably not because of the iframes.
Or is there a way to not use iframe for components (that is not documented) ?

Update layout and style of the variant preview

Is your feature request related to a problem? Please describe.
The main problem I found with current implementation is the discoverability of the Breaktpoints switcher.

Describe the solution you'd like

• Move Breakpoints outside of the dropdown into an inline list of buttons and add new styles for them. This should highly improve their discoverability.
• Add new style to the current width indicator in the top left corner of the variant preview.
• Change the preview border style.
• Potentially introduce new custom properties for further customization, like --uie-variant-preview-border-style, --uie-variant-preview-border-color and --uie-variant-preview-border-radius

Additional context
Refresh the overall look of the application.

Lazy load iframe variants

Is your feature request related to a problem? Please describe.
When components have a high number of variants, the web page slows down to a crawl loading all of the iframes for the variants.

Describe the solution you'd like
We integrated Yall.js https://github.com/malchata/yall.js/ and patched the component template to lazy load the variant iframe. This, combined with the existing anchor navigation, allows to load only variants needed for display, speeding up the page considerably. We have pages with 30 to 40 variants (which means 10 ~ 15 variants over 3 themes).

Describe alternatives you've considered
None.

Additional context
We have a PR ready but would like to discuss the overall benefit for the project and/or additional use cases before submitting it. Of course we can open a PR to share the code. Let us know what would work best.

Update the style of the variant content header

Describe the solution you'd like

• Replace "Preview" and "Code" labels with icons and placed them in a button group.
• Update the other icons before the button group to the new iconography stack.
• Vertically align all items in relation to the title.

Additional context
Refresh the overall look of the application.

Hydrate JSX-Templates on the Client

Hi Dennis! :)

Is your feature request related to a problem? Please describe.
We've been using UIEngine with the JSX-Adapter. So far, the Adapter renders the JSX-Code into static html and outputs them.
This is fine for simple components that only receive props and don't offer much interactivity, yet we run into trouble once there is functionality that is supposed to run on the client.

Describe the solution you'd like
To support client-side functionality we would need to move from "using JSX as a templating engine" to also "hydrate the components on the client".
I'm not really sure how to go about this to be honest.

Let's consider the following, simple component:

import React, { Component } from 'react'

class Heading extends Component {
  componentDidMount() {
    console.log('component says hi')
  }

  render() {
    return (
      <h1>Hello World</h1>
    )
  }
}

export default Heading

From what I understand, the JSX-Adapter is applied on every variant, and each variant (or rather the output for it) is separate from all other components/variants in its own html-file.
When reading about this subject it appears that - in order to cause hydration for a component - you'd need to call:

const app = document.getElementById( "app" )
ReactDOM.hydrate( <Element /> , app )

Now, to bring these two points together, my impulse is that the JSX-Adapter is the right place to generate this code since it's the only part that knows which component it is currently rendering and therefore needs to hydrate on the client.

And this is where I begin to wonder.
Of course, If i just put the code into a template-literal and output it as a script-tag on the client, it won't work since the Browser doesn't know about React or JSX.

So, I tried transpiling the template-literal itself with babel:

  let Element = require(filePath)

  const code = `
      const Element = ${Element}
      const app = document.getElementById( "app" )
      ReactDOM.hydrate( <Element /> , app )
  `

  const transformed = await babel.transformAsync(code, {
    filename: filePath,
  })
  const hydration = transformed.code

  return (
    html +
    `
    <script type="text/javascript">
      ${hydration}
    </script>
  `
  )

Unfortunately, the output now contains code like

var _react2 = _interopRequireDefault(require("react"));

...which the browser doesn't understand either because of the require.

At this point it starts to feel like a rabbit hole for me and I'm no longer sure whether this is the right direction to go.

Do you have any opinion on how to tackle this problem?

Regards,
René

Question: Template Engine Extensions/Helpers?

Just posting for discussion and opinion:

How to work with template engine extensions? Like Twig has many helper libraries and
I guess other engines have them too, for example a "money formatter" ?

Is the goal to not rely on them anymore for "simplicity" ?

More flexible configuration

Currently the project config has to be done via the uiengine.yml file and can on ly be written in YAML. Even though this works nicely, it would be a good addition to be able to have the config available in differnt formats, i.e. in the package.json or a separate uiengine.config.js file as know from other js projects.

The current YAML configuration should still be available.

Possible packages to help with implementing this:

• cosmiconfig

Bug: globby -> fast-glob regression

Describe the bug
A fresh install fails to build the demo project.

To Reproduce
Steps to reproduce the behavior:

1. follow the quick start:

mkdir uiengine-demo && cd uiengine-demo && npm init -y
npm install @uiengine/core @uiengine/adapter-html --save-dev
npx uiengine init --demo
npx uiengine build --serve --watch

2. the build fails with:

🚨  Build failed!

Child page "elements" does not exist for page "patterns".

Here is a list of available child pages:

notably, the list of available child pages is empty.

Expected behavior
The build succeeds

Additional context
Tried a fresh install with Node v10, v12, v13, same results. This did not happen in the past and does not seem to be tied to version 2.6.x. Tried with v2.5.9 and it still breaks. This seems to be a problem with a downward dependency.

EDIT: found the culprit in fast-glob. Version 3.1.1 works fine. version 3.2.2 fails.
Quick workaround:

rm -rf node_modules/fast-glob
npm i [email protected]

Any course of action to avoid this?
Thanks in advance,
Matteo

Replace variantId inside the variant render error message

Describe the bug
The variant id inside the variant render error message is misleading (for me).

File: src/components/Footer/variants/footer-vue-sfc.vhtml

Example Error:

Variant "Footer/footer-vue-sfc.vhtml-1" could not be rendered!

When I read the message, I thought the UIengine created a wrong file path (including the "-1" suffix) and did not find the file (due to a missing configuration or sth like that).

Also the debug option did not provide any details for me. Am I missing something in the config?

        vhtml: {
            module: '@uiengine/adapter-vue',
            options: {
                debug: true,
                bundle: '...bundle...'
            }
        }

Expected behavior
The variant id is an internal (undocumented) UIengine detail. The cause for the error is not clear (missing file, wrong file name, render error etc.) for the user and the variant id inside the message is misleading.

Besides more details, I'd expect to be given the variant file's path relative to the project or to the component in the error message.

Move component retrieval to adapters

Currently the location of components is configures via the source.components configuration. This is not flexible enough as projects likely differ on where components are stored. React and Vue.js projects are structured differently than i.e. projects that use Handlebars or Pug for rendering.

Hence the logic or source configuration for the components should be moved to the individual adapters. Eventually the current retrieval can be used as a fallback in case the adapter does not provide the methods to be implemented.

styled-components: CSS not being applied

Hi Dennis! :)

Describe the bug

I tried to take UIEngine for a spin with a project from scratch using the jsx-adapter and styled-components.

While the definition of the components works as expected and the styled-components library applies its generated classes to the elements, the actual css seems to get lost somewhere along the way.

To Reproduce

I setup a minimalistic project to reproduce the described behaviour if you take a look at the Heading-component here:
https://github.com/MrAvantiC/uiengine-test

Expected behavior

The code

const Heading = styled.h1`
  color: red;
`

should result in a red font-color.

Component/variants for a theme

Hi, I'm starting to use uiengine and I was wondering if there is a way to show a variant only for a specific theme? we have an exception for a card and I would like to maybe specify this in the component config instead of just hiding it in the other themes.

Thanks! 👍

React Hooks not working

Hey Dennis!

Describe the bug
I have a minimal example to reproduce the problem here:
https://github.com/MrAvantiC/uiengine-hooks
It contains a simple functional component Footer that is supposed to set a counter using React Hooks.
But if you start up the development mode and visit http://localhost:3000/_variants/_default/Footer/Footer.jsx-1.html you can see the an error in the console:

Uncaught Invariant Violation: Invalid hook call. Hooks can only be called inside of the body of a function component.

I checked the common mistakes that lead to this error:

✅ You might have mismatching versions of React and React DOM.
✅ You might have more than one copy of React in the same app.

$ npm ls react
[email protected]
└── [email protected]

$ npm ls react-dom
[email protected]
└── [email protected]

✅ Call them at the top level in the body of a function component.

export default function Footer(props) {
  const [count, setCount] = useState(0)

That should be fine.
And if I use the exact same code inside an application setup with create-react-app it works fine, see this repository: https://github.com/MrAvantiC/hooks-example

To Reproduce

1. Clone https://github.com/MrAvantiC/uiengine-hooks
2. Install dependencies
3. Run npm run dev
4. Visit http://localhost:3000/_variants/_default/Footer/Footer.jsx-1.html
5. See console

Expected behavior
Should be able to update state using hooks

Regards,
René

Update style of the variant code panel

Describe the solution you'd like

• Add new style to the accordion items.
• Change “Code” accordion item label to “Source Code”.
• Potentially add an option through the config file to render only certain code segments.

A good example behind the last point above is:

• Given an ASP.NET project that's separated from UIengine.
• Front-end developer creates the components in a template language other than the one used in the final project (pug in my case)
• Back-end developer picks up component implementation in the final project following the documentation and the rendered output in UIengine but has to come across all the code segments he's not interested in (Source Code - being whatever template language was used by the front-end developer and also Context) while he only needs the Rendered HTML code to copy into the ASP template.

Additional context
Refresh the default overall look of the application.

Update the layout and style of the topbar

Is your feature request related to a problem? Please describe.
One major issue with the topbar I found throughout different projects is when having multiple themes, the theme switcher is barely discoverable, mainly because it doesn't have an indicator that it could reveal a dropdown list of options.
This proposal goes further though to also improve the layout of the topbar.

Describe the solution you'd like

• Remove the project title from the topbar (will be relocated into the navigation sidebar).
• Move the search input in the center (this can have a good effect into driving users to use more the search field to look for various items in the project rather than diving through the navigation tree).
• Move the theme switcher to the far right hand side while also applying a new and more meaningful style for better discoverability.
• Update the default background color to make it stand out even more from the rest of the application.

Additional context
Refresh the overall look of the application.

Last scroll position is shared between pages

Describe the bug
When I scroll down on a page in the UI Engine documentation that's currently deployed, the last scroll position remains the same when I switch to another page.

To Reproduce
Steps to reproduce the behavior:

1. Go to 'https://uiengine.uix.space/basics/getting-started/'
2. Scroll down about 200px
3. Click on 'Configuration'
4. The scroll position remains at 200px and is not (re)set to the top (i.e. 0)

Expected behavior
When I switch pages, I always want to start at the top of the page.

Screenshots
See http://g.recordit.co/LUqQDZToCb.gif

Technical documentation

Cover the details for …

• Configuration file
• Adapters
• Components
• Variations
• Templates
• Pages
• YAML frontmatter and custom schemes
• Theme

Template placeholders for configuration values (e.g. application base path)

Users should be able to reference configuration values (like the application base path) in HTML templates. The base path is configured in ui.base in uiengine.config.js. It would be great to be able to insert a template placeholder that is replaced with the configured base path at build time.

Example:

<script src="${config.ui.base}/something.js"></script>

=> <script src="/my-base-path/something.js"></script>

To solve this with a template comment like <!-- uiengine:basepath --> or <!-- uiengine:config:base --> (which is probably not be the best solution in this case), the change would be made in core/src/builder.js I guess.

Error when rendering uiengine-theme-default/lib/components/navigation/navigation.pug

Moin!

When running yarn run uiengine generate, I am getting this error when it tries to render pages or variants:

Page "atoms" could not be generated!

Pug could not render "/Users/ahaller/Desktop/test/node_modules/uiengine-theme-default/lib/templates/page.pug"!

TypeError: /Users/ahaller/Desktop/test/node_modules/uiengine-theme-default/lib/components/navigation/navigation.pug:4
    2|   nav.navigation&attributes(attributes)
    3|     .wrap.wrap--wide
  > 4|       a.navigation__config(href=h.pageLink(navigation['index']))
    5|         | #{config.name} (#{config.version})
    6|       ul.navigation__tree
    7|         +navigationItem('index')

Cannot read property 'path' of undefined

I was starting with a blank project "test". Here is what I did.

mkdir test && cd test && yarn init
…
yarn add -D uiengine uiengine-adapter-pug
yarn run uiengine init
yarn run uiengine component button
yarn run uiengine page atoms
mkdir src/templates &&  touch src/templates/variant-preview.pug
yarn run uiengine generate

💥

Any ideas?

Getting Started guide

Document the basic steps to get the project going and creating the first pages, components, variations, and templates.