Improve documentation for npm usage

[pixelbucket-dev]

It's simply not clear how to use it when installing it from here https://www.npmjs.com/package/elix

Some examples (e.g. carousel component) would be appreciated and could improve adoption and general interest in the library.

[JanMiksovsky]

You're right, we can do better in our ReadMe.

I'll take a shot at that before our upcoming 4.0 release, and give you a heads up so that you can review what we've written. Sound good?

[pixelbucket-dev]

Sounds great, thanks :). Let me know if you need help.

[JanMiksovsky]

I've added a Quick Start section near the top of the ReadMe.

@NudelSieb Please take a look and let me know what you think.

[pixelbucket-dev]

@JanMiksovsky thanks, that's fine now. Maybe add an example for usage in frameworks, e.g. React or Stencil. I used the follwing in Stencil:

import 'elix/src/Carousel.js';

...

render() {
    return        
        <elix-carousel>
          <!-- Content -->
        </elix-carousel>;

[pixelbucket-dev]

Also on another note, I noticed that the component-specific docs could be easier to consume. What's missing is usage examples on how to use the component declaratively (and maybe imparatively). How do I set props/attributes on the element, does that even work? Concrete examples on how to set attributes and register events are necessary for newcomers.

I propose that simple usage examples sit at the top and more complex API documentations follows for people who want to dive deaper. I could imagine code snippets to sit underneath each visual example (that you already have). So one does not have to open devtools/inspector.

This would help the lib to get faster traction and adoption.

[pixelbucket-dev]

Hi @JanMiksovsky how would use a component declaratively in JSX? You added the import example but I would like to avoid appendChild. Is it possble to just import a component and then its markup automatically registered to be used in the DOM?

[pixelbucket-dev]

I just answered my own question.

import FilterComboBox from 'elix/src/FilterComboBox.js';
new FilterComboBox();

This registers <elix-filter-combo-box>, it works 😄 .

[JanMiksovsky]

Yes, the import statement alone should register the component.

[zenwork]

One more thought. You provide TS support for the mixins but not for the components. Any reason why? Any tips on how to get going in a webcomponent project based on TS?

[JanMiksovsky]

@zenwork Elix supports TypeScript for both mixins and components. The components don't require separate .d.ts files because TypeScript can generally infer the necessary information about the component from the .js files alone.

Using Elix in a TypeScript project is essentially the same as in a JavaScript project. Add the elix dependency to your project, then import the components along the lines of @NudelSieb's sample above or the quick start example in the ReadMe. In either case, TypeScript should recognize the correct typings for the component properties and methods.

I'm going to close this out since I believe the original issue has been addressed. If you have general questions about using Elix, please feel free to send mail to jan@component.kitchen. I'd be interested in hearing more about where you'd like to use the Elix components.