ionic-team/stencil-site

Stencil site and documentation source.

Stencil Site

The Stencil site is the place for documentation on how to use Stencil.

Contributing Documentation Updates

The documentation content is formatted in markdown and can be found in the docs directory. Easiest way to make edits is to navigate to the markdown file to be updated, and click the Edit button in the top right (the pencil icon). After making the edit, submitting the changes will create a Pull Request (PR) for reviewed. Please feel free to ask any questions within the discord channel, we're happy to help.

Building the Site

To build the site from the source, ensure you're using the most recent versions of Node and Npm, and pull the latest from master. Next, run npm install, npm run docs to build the docs files and npm start to launch the site in development mode.

Related

• Stencil Documentation
• Ionic Discord
• Ionic
• Ionicons
• Capacitor

License

• MIT

stencil-site's Issues

Conflicting `manifest.json` `icons` requirements

I've loved the concept of Web Components, and really enjoyed working with Ionic before I started working with React. I was crazy stoked when I learned about Stencil!

I'm starting to develop a new PWA app that will include a web extension (maybe "interact" or be partnered with" a web extension is more clear). Since Stencil can build components that can be used in a PWA or other html document Stencil seems like an awesome fit, at just the right time.

So I spun up the Stencil template and made a new component.
But when I started to try to wrap the resulting www/index.html into a web component, I hit a snag.

Specifically:

• Stencil / Web Component manifest.json expects an array of icons:

"icons": [
    {
      "src": "assets/icon/icon.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]

• WebExtensions' manifest.json expects an icons object:

  "icons": {
    "48": "icons/beasts-48.png",
    "96": "icons/beasts-96.png"
  },

During development of Stencil components, is there a way to specify alternative manifest.json files? For example, instead of a www directory being made and maintained, having pwa and webext directories made and maintained with their respective manifest files?

Minor structure changes

• in the left menu, call it "Basics" instead of "Component Basics"
• Stencil configuration link should be moved to the Advanced section in the left menu
• "Building Components" should be renamed to "Decorators"
• think we need to improve how we list out the various Decorators and what they do
• Learn JSX should probably be renamed to "Templating" or something
• Rename "My First Stencil Component" to "My First Component"

How to move the generated doc to a subpath?

I'm trying to translate the documents and to deploy it on Github Pages.
But the generated files and the request in the script are based on the root of domain.

How to move it into a sub path? ( such as username.github.io/stencil-site)

I changed every path in source code which start with / to /stencil-site/ and modified the config files as below:

stencil.config.js:

exports.config = {
  bundles: [
    { components: ['stencil-site', 'site-header', 'landing-page', 'lazy-iframe', 'site-menu'] },
    { components: ['app-marked', 'document-component'] },
    { components: ['demos-page'] },
    { components: ['resources-page'] },
    { components: ['pwas-page'] }
  ],
  collections: [{ name: '@stencil/router' }],
  wwwDir: 'www/stencil-site',
  publicPatg: '/stencil-site/build'
};

exports.devServer = {
  root: 'www',
  watchGlob: '**/**'
};

gulpfile.js:

var gulp = require('gulp');
var markdown = require('gulp-markdown');
var hljs = require('highlight.js');
gulp.task('default', function() {
  return gulp
    .src('./docs-md/**/*.md')
    .pipe(
      markdown({
        highlight: function(code) {
          return hljs.highlightAuto(code).value;
        }
      })
    )
    .pipe(gulp.dest('./www/stencil-site/docs-content'));
});

It works well under development mode.
But the prerender result is wrong.

It rendered another stencil-site folder in the stencil-site.
How to correct it?

Or, what is the correct way to move the generated documents to a subpath?

Add slot docs

Stencil's Slack "invite link is no longer active."

On https://stenciljs.com/ —and without already having a slack account for the stencil group— click the "Stencil Slack" link (lower-left corner). The redirect page states, "This invite link is no longer active. Please check with the person who shared it with you to see if there's a new link available."

When the correct link is identified, it needs to be updated in the site-menu component (should be around somewhere close to here - https://github.com/ionic-team/stencil-site/blob/master/src/components/site-menu/site-menu.tsx#L150).

The content does not match the images with the documents

Description

Content does not match what's in the images shown in Learning JSX.

Not sure if the content is right or the images just aren't those supposed to be on the same page.
Please ensure images or the content are relevant such as there are no p tags in any of the images, comma in between divs and no comma is found in any of the images.

Please look into fixing the contents and/ or the images.

Beef up stencil-router docs

related to #51

npm run dev fails on windows after the first time

Cloned the repo, npm install, npm run dev, worked perfectly.
Ctrl + C
npm run dev (and all npm run dev after that:

amitm@Amit-PC MINGW64 /d/xampp/htdocs/stencil-site (master)
$ npm run dev

> @stencil/[email protected] dev D:\xampp\htdocs\stencil-site
> gulp && sd concurrent "stencil build --dev --watch" "stencil-dev-server"

[22:49:02] Using gulpfile D:\xampp\htdocs\stencil-site\gulpfile.js
[22:49:02] Starting 'default'...
[22:49:02] Finished 'default' after 46 ms
events.js:182
      throw er; // Unhandled 'error' event
      ^

Error: listen EADDRINUSE :::3333
    at Object.exports._errnoException (util.js:1016:11)
    at exports._exceptionWithHostPort (util.js:1039:20)
    at Server.setupListenHandle [as _listen2] (net.js:1307:14)
    at listenInCluster (net.js:1355:12)
    at Server.listen (net.js:1455:7)
    at Object.<anonymous> (D:\xampp\htdocs\stencil-site\node_modules\@stencil\dev-server\dist\index.js:84:64)
    at Generator.next (<anonymous>)
    at fulfilled (D:\xampp\htdocs\stencil-site\node_modules\@stencil\dev-server\dist\index.js:4:58)
    at <anonymous>
    at process._tickCallback (internal/process/next_tick.js:169:7)
[49:02.9]  build, dev mode, started ...
[49:02.9]  compile started ...
[49:04.4]  compile finished in 1.52 s
[49:04.4]  bundle styles started ...
[49:04.4]  bundle modules started ...
[49:04.5]  bundle styles finished in 130 ms
[49:04.6]  bundle modules finished in 227 ms
[49:04.6]  prerender index html started ...
[49:05.3]  prerender index html finished in 619 ms

[ ERROR ]  EPERM: operation not permitted, lstat 'D:\xampp\htdocs\stencil-site\www\build\app\demos-page.css'

[49:17.9]  build failed, watching for changes... in 15.03 s

Of course, this is on everyone's "favorite" OS - Windows

The slack link is no longer active

After clicking the slack link on the Contributors.md page slack reports that the "Invite link is no longer active". The link is currently https://join.slack.com/t/stencil-worldwide/shared_invite/enQtMjQ2MzkyMTY0MTk0LTQ4ODgzYjFjNjdkNDY3YWVhMmNlMTljMWQxNTM3Yjg0ZTIyZTM1MmU2YWE5YzNjNzE1MmQ3ZTk2NjQ1YzM5ZDM.
The src/components/site-menu/site-menu.tsx is using the same link.
Should it be remove or updated?

Docs on how publicPath works in loader script

Start w/ simple JSX example

Learn JSX doesn't have a bare-bones simple example. Should show just raw JSX, without any if or for loops.

link to homepage from site logo

The stencil logo in the top left of the page should always link to the root homepage /

Add docs on stencil service worker setup

Partially wrong linking of Next button or missing buttons

Hi everyone,

I was reading through the docs and I realized that the Next button on the Component Life Cycle page links to the Stencil Config page rather than Forms.

Additionally are the buttons Next and Back completely missing on the pages Forms, Updating Arrays and Objects and Unit Testing.

I'm happy to submit a PR to fix this.

Cheers,
Dominik

Using a component inside <p>...</p> causes to render the componet 2 times (added to the wrong repo)

import { Component, Prop } from '@stencil/core';

@Component({
  tag: 'my-name',
  styleUrl: 'my-name.scss'
})
export class MyName {

  @Prop() first: string;
  @Prop() last: string;

  render() {
    return (
      <p>
        <my-child name="Emil" />
      </p>
    );
  }
}

The above code outputs this in the DOM tree:

I'm very amazed about this work, and thank you for the presentation at Polymer Summit 👍

Add Listen element reference docs

@Listen('window:scroll')

https://github.com/ionic-team/stencil/blob/51c094248bf9ee93556a96c2fc2ebda0229c391f/src/util/helpers.ts#L58

:hover effect for standard content links

The links in the /demos page should some sort of :hover effect

How integrate PostCSS

Hi, here we need to drop sass and switch to PostCSS, is there a way to integrate and configurate it with stencil?

add docs on distributing and sharing components

Typos in new contributing file

I will send a PR.

Add Prop connect docs

@Prop({connect: 'ion-animation-controller'})

Add Listen keycode docs

@Listen('keyup.enter')

Available keycodes: https://github.com/ionic-team/stencil/blob/51c094248bf9ee93556a96c2fc2ebda0229c391f/src/util/constants.ts#L77

Move present stencil section on https://stenciljs.com/resources

Possibly should consider moving that iframe to below the community articles / blog section so that it can be lazy loaded with IntersectionObserver like we do the youtube video iframe. It loads 226.9kb of javascript that id rather the user only have to load if they need it

Pretty up HTML tables

Could use some css to pretty up a table's formatting:
https://stenciljs.com/docs/stencil-config

Demo site for StencilJS points to repo

Super tiny change; sorry I don't have the time at the moment to submit a PR.

https://github.com/ionic-team/stencil-site/blob/fa69b7d257f31beed05d51481f10161c475c9f11/src/components/demos-page/demos-page.tsx

demos = [ { title: 'Stenciljs.com', description: 'Yep, this site is also built with Stencil!', url: 'https://github.com/ionic-team/stencil-site', source: 'https://github.com/ionic-team/stencil-site', },

Describe how lazy loading should be used in other projects

I've recently found out about stencil and want to use it in an angular[5] application. Being used to webpack pre-bundling, the concept of lazy loading didn't resonate with me. Not that I don't like it, just not sure how that'll work with a bundled application.

In the current ditribution docs, it simply says:

Put a script tag similar to this <script src='node_modules/my-name/dist/myname.js></script> in the head of your index.html

That is not true when bundling and deploying the application, since node_modules won't exist. What should really happen is 'copy' the dist folder of the stencil component to the dist folder of the app.

I think it'd worth explaining the concept of lazy loading a bit better and maybe provide better instruction for such a common use case.

---

For anyone interested, my angular5 solution is the following:

1. npm install (or npm link during development) the stencil components dependency
2. add something like the following to your .angular-cli.json, where my-name is the dependency's package.json name

{
  "apps": [{
    "assets": [
      { "glob": "**/*", "input": "../node_modules/my-name/dist", "output": "./components" }
    ]
  }]
}

3. add <script src='components/mycomponent.js'></script> to your index.html. The name of mycomponent.js comes from the actual setup of the stencil project.
4. use your components

<my-component first="Stencil" last="'Don't call me a framework' JS"></my-component>

*The names used above are exactly the same names used in stencil-component-starter

component docs dead link

There is a dead link that leads to https://stenciljs.com/components from https://stenciljs.com/docs/getting-started under the Developing header

When we save, we'll have our component updated with the new changes. To learn more about what's going on in this component, check out component docs

Update stencil config docs

Update document.title

document.title should update for each page. Probably need to investigate more the ideal way to do this.

Highlight active page in left menu

Should be doable now with updated stencil router links

Add Prop context docs

ionic-team/stencil#75 (comment)

Update copy config docs

After digging through some code answering a question on slack i figured the documentation regarding the copy configuration could do with a little more explanation.

I´ll be happy to make a PR adding a little more information regarding the structure and properties required.

Add Prop default value, validation & required docs

ionic-team/stencil#236

Add docs for querying Local DOM

Polymer provides this.$.item in order to access parts of the template. Documenting how to use this would be beneficial to newcomers.

Demo of nested routing

The following page highlights how easy it is to get routing working in a Stencil app: https://stenciljs.com/docs/routing/

However after reading the paragraph about nested routes/components:

When navigating to /demos/rendering based on the above configuration, the demos-page component will be loaded with a child component fiber-demo. Nested routes/components just work.

I'm not sure I understand how this hangs together. Maybe a more details demo would be useful to see what a demos-pageand fiber-demo child component living at /demos/rendering might look like?

Also what does exact do? 😄

Add docs on using isServer with prerendering

Docs hierarchy

Docs, as organized now, aren't the most communicative of all the features stencil offers.

Here are a couple examples that happened to me during my first hit on coding a stencil project:

1. Coming into typescript, it was interesting to know that decorators will decorate the following method. On the decorators page, the lead in copy doesn't support the page - what decorators are. This is a perfect opportunity to explain at a high level what a decorator does to make stencil better than other web component options.

2. All decorators would benefit from having their own page. This was a challenge to me, learning what each decorators goals were. Additionally, because there's no decorator archive page > decorator single page hierarchy, it was easy for me to gloss over the @Element decorator, especially since it has a low footprint compared to the other decorators and their documentation on the same page.

3. Collections don't have documentation. Today, I began working on a seperate collection of components that I could import into my original project. The project needed a collections file, but I wasn't sure why that wasn't being generated. Documenting this would be super helpful.

--

With that feedback being said, here's a proposed hierarchy - unsure where this fits into your roadmap (I wouldn't know where to place the other GH issues)

Home
└ What is Stencil (About)
└ Getting Started (arguably, "starting a new proj" could be on the home page)
└ Basics
◽└ Components
◽└ Lifecycle
◽└ Templating (here, detail using @Element)
◽└ Decorators
◽◽└ @Component
◽◽└ @Prop
◽◽└ @PropWillChange
◽◽└ @PropDidChange
◽◽└ @State
◽◽└ @Method
◽◽└ @Element
◽◽└ @Event
◽◽└ @Listen
└ Advanced
◽└ Configuration
◽└ Collections
◽└ Serverside Rendering
└ Add-ons
◽└ Router
◽└ Submit yours? (I have a couple I could submit, but I'd prefer to put them on webcomponents.org)

--

Thoughts?

On Android (Pixel XL - any Chrome browser) there is black flicker when changing route

On Android (Pixel XL - any Chrome browser) there is black flicker when changing route

Tested in Canary, Beta, Dev and Stable

Add Prerendering docs

In the left menu, add it to the Advanced section, and above Server Side Rendering

Add Component decorator host option docs

Explain host option:

@Component({
  host: {
    theme: 'toggle',
    role: 'checkbox'
  }
)

Examples of best practices with forms in Stencil

site-header hides title on narrow devices

The site-header wraps to a new line and hides the top part of the title on narrow devices (e.g. iPhone SE).

All the pages linked to are empty

Small syntax error in distribution docs

It looks like the <script src='node_modules/my-name/dist/myname.js></script> is missing a ' in the src.

Next and Previous buttons at the bottom of each doc

Make next and previous links at the bottom of each doc, with the anchor's text of the next and previous page. Basically to make it easier to go through the process.

Document Unit Testing with @stenci/core/testing

@stencil/core/testing landed in 0.0.6-2

https://github.com/ionic-team/ionic/blob/d3e79fb46267e375905dd493829eaa36d9c1dc36/packages/core/src/components/button/test/button.spec.ts

scrollToTop when clicking a new link

Ensure that when you're scroll to the bottom of a doc, and when you click the next link, the top of the next doc is scrolled into view.

Routing related issue on the site

After pressing back button few times at the Stencil website, I ended up to the URL https://stenciljs.com/docs/building-components that looked nothing like the normal site. Apparently route was looping the same home page component again and again.

Screenshot shows what the page looked like in Firefox:

Also tried to load the URL with the Chrome browser, and it kept loading indefinitely without the main page content becoming visible.

Browser version:
Firefox 55.0.2

Typos and spelling issues in documentation

In page https://stenciljs.com/docs/my-first-component

• In the last paragraph it says: "Any property decorated with @props() ...", but the @Props decorator does not exist. It should say "Any property decorated with @prop() ...".
• Also in the last paragraph, it says: "our component would fire it's render function again". It should say "our component would fire its render function again".
  • "It's" is a contraction of "it is", whereas "its" indicates posession.

In page https://stenciljs.com/docs/forms

• At the end of the first section, it says "Lets go over what is happening here". It should say "Let's go over what is happening here".
  • "Lets" is the third person singular of "Let", as in "he lets you do it", whereas "Let's" is a contraction of "Let us".
• I did a search for "lets" and found two other places where it is misspelled:
  • docs-md/advanced/service-worker/index.md: "Lets go through the steps..."
  • docs-md/addons/stencil-router.md: "Now lets go over how..."

typo in the docs-md/advanced/angular-integration/index.md

stencil-site/docs-md/advanced/angular-integration/index.md

Line 11 in 2af659e

Including the CUSTOM_ELEMENTS_SCHEMA in the nodule allows the use of the web components in the HTML markup without the compiler producing errors. Here is an example of adding it to `AppModule`:

Including the CUSTOM_ELEMENTS_SCHEMA in the nodule allows the use of the web components in the HTML markup without the compiler producing errors. Here is an example of adding it to AppModule:

Does the nodule mean to "module" ?