polymerelements / iron-component-page Goto Github PK

A reusable landing page for elements

HTML 35.11% JavaScript 64.89%

iron-component-page's Introduction

<iron-component-page>

iron-component-page is a full-page documentation browser for custom elements, mixins, classes, and more. It consumes the JSON descriptor format produced by Polymer Analyzer.

See: Documentation, Demo.

You may also be interested in the iron-doc-* element collection which underlies this element and can be used to embed documentation in other apps (for example, webcomponents.org does this).

Usage

Documenting your element

iron-component-page is designed to make it easy to view documentation for your custom element project.

Install the Polymer CLI with npm install -g polymer-cli. This gives you a command-line interface to Polymer Analyzer (among other things).
cd to your project directory. This can be a custom element, a full app, or even a plain JavaScript library. Polymer Analyzer will discover all of the interesting items recursively in your project directory.
Analyze your project with polymer analyze > analysis.json. This produces a JSON descriptor file. By default iron-component-page will look for a file called analysis.json (you can override this with the descriptor-url property).
Add iron-component-page as a dev dependency of your project: npm install @polymer/iron-component-page --save-dev.
Create an HTML file to instantiate an iron-component-page element (e.g. index.html or docs.html). Note that you may need to adjust your import paths depending on your project layout:

<!doctype html>
<html>
  <head>
    <script type="module">
      import '@polymer/iron-component-page/iron-component-page.js';
    </script>
  </head>

  <body>
    <iron-component-page></iron-component-page>
  </body>
</html>

Serve that page using polymer serve --npm.

Routing

iron-component-page handles URL routing (via iron-doc-viewer) to provide permanent addresses for all locations in the documentation tree, including scroll anchor targets.

By default it uses the URL fragment for routing (e.g. docs.html#/elements/my-element#property-foo), in order to support simple static file hosts.

To use the real URL path for routing, set the base-href property to the server mount point (e.g. /api/docs or empty string for the root path). Note that this requires a host that serves the application from all paths that should be handled by the doc viewer.

Styling

iron-component-page uses the default theme from iron-doc-viewer. See its documentation for styling. The following custom properties and mixins are also available:

Custom property	Description	Default
`--iron-component-page-header-color`	Background color of main header.	`paper-pink-600`

Contributing

If you want to send a PR to this element, here are the instructions for running the tests and demo locally:

Installation

git clone https://github.com/PolymerElements/iron-component-page
cd iron-component-page
npm install
npm install -g polymer-cli

Running the demo locally

polymer serve --npm
open http://127.0.0.1:<port>/demo/

Running the tests

polymer test --npm

iron-component-page's People

Contributors

Stargazers

Watchers

iron-component-page's Issues

src argument ignored beause Analyzer is already loading a document

You can never load anything but default doc in

iron-doc-viewer starts loading in ready()
that happens before
iron-component-page._moduleNameChanged which triggers
iron-doc-viewer._srcChanged which fails with
Analyzer is already loading a document

Fixing it is tricky. Curious to see what you do.

Touch scrolling vertically from code view does not scroll

demoPath is not a property

in _updateDemoUrl, it checks this.demoPath, but it is not a public attribute, or it is not initialized anywhere. So _demoUrl will always be empty.

is this a bug?

How to specify demo view?

README.md tab

(In addition to a test tab) I would really like to see yet another tab added for the README.md.

With some very small changes I think iron-component-page could actually be polymer's most powerful developer tool. Typically, in my elements readme file I put a roadmap, just a simple checklist so everyone know what the planned evolution for a particular element is.

I think these 4 tabs would really give every developer a good bang for their buck.

Road map Planning
API docs and goals
Demos and examples.
Testing

Doesn't render element description if element is served in a valid HTML document.

Custom elements defined in an <html> will render the element description, so long as a <head> and <body> are not defined. All properties, methods and events do render properly. The HTML document specification requires these elements, and many browsers automatically add them, if they are missing. Polymer itself properly imports elements defined in this manner, as well.

Broken Example:

<html>
    <head>
    </head>
    <body>
        <!-- Custom element description (does not render) -->
        <dom-module id="custom-element">
        </dom-module>
        <script>/* Element registration */</script>
    </body>
</html>

Working Documentation:

<html>
    <!-- Custom element description (does render) -->
    <dom-module id="custom-element">
    </dom-module>
</html>

The concern here is that as a document, when viewed in browser inspector, the document still has the document.head and document.body properties. In cases where a head or body is not specified, any <link> above the first element or custom element actually appears in the document.head. The document.body does not begin until the first non-metadata element

Again, Polymer recognizes the HTML document specification behavior and still loads the import properly, so this inconsistency should probably be resolved.

_activeChanged throws if null _activeElement, do not reference descriptor.

If there is nothing to be parsed, _activeChanged throws because _activeElement is null, and it derefs this._activeElement.jsdoc.

Same code should not be referencing jsdoc. Demo elements are stored as descriptor.demos[], not inside jsdoc.

Support absolute URLs for @demo

Currently only relative paths are supported for @demo. It would be great if absolute URLs were supported.

There are times when absolute URLs are desired.

Linking to another domain or location hosting the demo
Allowing other programs (other than iron-component-page) to parse @demo to show the demo

component.kitchen, for example, parses the documentation. If @demo is an absolute URL it uses the @demo link to signify whether or not a component has a demo. It also uses this parsed link to show the demo on component.kitchen.

This code comes from iron-component-page.html.

_frameSrc: function(view) {
      if (!view || view.indexOf("demo:") !== 0) return "about:blank";
      var src = view.split(':')[1];
      return new URL(src, this.base).toString();
}

If @demo is an absolute URL the iframe source that iron-component-page generates is broken as illustrated in the following situation (using the code above).

view comes through as "demo:http://coderfin.github.io/byutv-jsonp/components/byutv-jsonp/demo/index.html" and splits on the colon returning http as src. The final result is a URL with a path that ends in /http (http://coderfin.github.io/byutv-jsonp/components/byutv-jsonp/http).

Example text is not selectable.

From @scheib on June 24, 2015 20:55

Example: https://elements.polymer-project.org/elements/paper-item has text

<paper-item>
  <paper-item-body two-line>
    <div>Show your status</div>
    <div secondary>Your status is visible to everyone</div>
  </paper-item-body>
  <iron-icon icon="warning"></iron-icon>
</paper-item>

which is not selectable on the page. This breaks copy-paste of example code.

Copied from original issue: Polymer/polymer#1961

Core API navigation is confusing

The drop-down menu in the core docs tends to obscure what's available. Would be much better to have a drawer panel with a menu of available packages/modules/whatever we call them.

The catalog probably wants to do something else here. iron-component-page probably has to support both these use cases (built-in navigation & external navigation).

iron-component-page accessibility issues

Keyboard focus: I am unable to get to the show private API / collapse / expand controls using just the keyboard.

Once we fix the keyboard navigation issues here, please make sure that focus is visible for these controls.

Also, there currently doesn't appear to be any content in the drop down menu in the upper left hand corner, but please test that this works with keyboard (e.g. you can navigate to the menu with tab, press enter to open, use teh arrows to go through the contents, and escape to close).

Contrast: contrast on show private API is poor - please darken that text.

Test tab

I'd like to see a tab for test. I added a simple link myself which points to ./test/index.html. However, It would be nice If I could just run them inline. (Currently, WCT has some issues running inside of an iframe I'm assuming it's because it makes heavy use of them itself. )

Bonus points for reporting test coverage.

JSON.parse() fails for asciidoctor comments

I wonder if iron-components-page should perhaps strip out comments when it tries to parse an HTML file. I'm using Asciidoctor to generate labs from HTML files, and it chokes on the standard Asciidoc identifiers for code snippets. For example:

<!-- tag::body[] -->
<body unresolved>   <!--1-->
      <h1>Hacking Web Components: Polymer Deluxe Counter</h1>
      <iron-component-page src="deluxe-counter.html"</iron-component-page>  <!--2-->
  </div>
</paper-header-panel>
</body>
<!-- end::body[] -->

This snippet chokes in JSON.parse() in iron-component-page.html:

    _loadJson: function() {
...
        var json = JSON.parse(textContent);
    },

Full stack trace:

 end::body[] SyntaxError: Unexpected token e(…)Polymer._loadJson @ iron-component-page.html:281Polymer.ready @ iron-component-page.html:250Polymer.Base._addFeature._invokeBehavior @ polymer-micro.html:356Polymer.Base._addFeature._doBehavior @ polymer-micro.html:351Polymer.Base._addFeature._readySelf @ polymer-mini.html:80Polymer.Base._addFeature._ready @ polymer-mini.html:67Polymer.Base._addFeature._tryReady @ polymer-mini.html:56Polymer.Base._addFeature._initFeatures @ polymer.html:3221Polymer.Base.createdCallback @ polymer-micro.html:151
iron-component-page.html:277 Uncaught SyntaxError: Unexpected token ePolymer._loadJson @ iron-component-page.html:277Polymer.ready @ iron-component-page.html:250Polymer.Base._addFeature._invokeBehavior @ polymer-micro.html:356Polymer.Base._addFeature._doBehavior @ polymer-micro.html:351Polymer.Base._addFeature._readySelf @ polymer-mini.html:80Polymer.Base._addFeature._ready @ polymer-mini.html:67Polymer.Base._addFeature._tryReady @ polymer-mini.html:56Polymer.Base._addFeature._initFeatures @ polymer.html:3221Polymer.Base.createdCallback @ polymer-micro.html:151

Demo button tries to get currentUrl/https

After following the reusable elements guide and publishing the repo, I can't get the demo button on the component page to show the demo page. It tries to load the current url + https.

This the component page:
http://eudes.github.io/ph-animated-text-ticker/components/ph-animated-text-ticker/
When the demo button is pressed, it tries to get (and fails)
http://eudes.github.io/ph-animated-text-ticker/components/ph-animated-text-ticker/https

It doesn't work on local with polyserve either.

Demo page and properties' default value won't show when import from polygit

Is it a bug or something else? Everything is alright when using bower.

paper-responsive-change event name cut off in documentation

Moved from PolymerElements/paper-drawer-panel#64

In the documentation page for paper-drawer-panel, the name of the paper-responsive-change event title is cut off, and appears to be paper-responsive-.

I believe this is because the description of the event does not flow onto multiple lines. Note the top of the "h" is peaking out from the next line.

Docs: copied docs from other elements

https://github.com/PolymerElements/iron-component-page/blob/master/iron-component-page.html#L15-L38

references iron-doc-element and iron-doc-page. This element needs its own docs.

Getters are shown as a method instead of property.

e.g.

    /**
     * Returns the scrollable element.
     *
     * @property scroller
     * @type Object
     */
    get scroller() {
      return null;
    },

This is explicitly annotated as a property; however:

"No documentation found" when documentation is rendering

Should be a paper spinner or blank unless we know that we can't find docs for an element(analyzer has no elements, etc).

Copied from googlearchive/polymer-element-catalog#84

Support multiple sources

Elements that are not imported by another element are not picked up by the system:

The component page does not include all of the elements:

In 0.5, <core-component-page sources='["paper-tabs.html", "paper-tab.html"]'> worked for this.

iframes in Safari

This is generally problematic in Safari <= 9.0.1. A few issues:

iframe content isn't sized automatically so users can't scroll.
Poor UX in mobile iOS
mousewheel event is not triggered inside an iframe in safari <=8 #48, https://bugs.webkit.org/show_bug.cgi?id=124139
This issue is also present in the catalog https://github.com/Polymer/polymer-element-catalog

Proposed solution:

Open the demos in a new window. (aka target="_blank") That will fix all the issues without adding more complexity.

Demo page is invisible when import webcomponentjs

everything inside <iframe> can be seen in dev tool, even the edge of elements, but it's just invisible!!!

Properties that take functions as input should still be listed as properties, not methods

Per title, right now a property of type: Function ends up in the 'methods' section which is mightily confusing to element consumers. Examples:

http://polymer.github.io/polymer/ and then the dom-repeat (can't link directly)
http://david-mulder.github.io/paper-datatable/components/paper-datatable/demo/api.html?datatable (so have a direct link here)

Support multiple `demo`'s

For one the element catalog already supports this, and it kind of sucks that 'we normal people' have to list to an ugly index.html instead of a beautiful menu xD

(Looked around and can't find an issue for this, if there is one then I apologize)

Support aggregated import file of elements

We have an import (google-web-components.html) with a bunch of other imports in it. The docs do not render those transitive imports. I see iron-doc-viewer has transitive, but that also will include polymer core lib imports.

Hydrolysis errors if using ES6 classes

I recently tried using an ES6 class for my element's definition and saw the following hydrolysis error when viewing the docs.

Failed to load source at: http://localhost:8080/components/quick-alert/quick-alert.html TypeError: Cannot read property 'forEach' of undefined
    at annotateElement (http://localhost:8080/components/hydrolysis/hydrolysis.js:1061:24)
    at Array.forEach (native)
    at Analyzer.annotate (http://localhost:8080/components/hydrolysis/hydrolysis.js:470:17)
    at http://localhost:8080/components/hydrolysis/hydrolysis.js:177:16

I'm wondering if this PR should fix the issue or if it still requires more work. cc @garlicnation

Element definition is here if you want to repro:

<link rel="import" href="../polymer/polymer.html">

<!--
An element providing a solution to no problem in particular.
Example:
    <quick-alert></quick-alert>
@group Seed Elements
@element quick-alert
@demo demo/index.html
@hero hero.svg
-->
<dom-module id="quick-alert">
  <style>
    :host {
      display: block;
      position: fixed;
      top: 0;
      left: 0;
      right: 0;
    }
    .alert {
      background-color: #4CAF50;
      color: white;
      padding: 16px;
      font-family: Roboto, Helvetica, sans-serif;
    }
    [hidden] {
      display: none;
    }
  </style>
  <template>
    <div class="alert" hidden="{{!shown}}">
      <content></content>
    </div>
  </template>
</dom-module>

<script>
  'use strict';

  class QuickAlert {
    get is() {
      return 'quick-alert';
    }

    get properties() {
      return {
        shown: {
          type: Boolean,
          value: false
        }
      }
    }
  }

  Polymer(QuickAlert.prototype);
</script>

"No documentation found" page leaves artifacts from previously viewed element

Example from paper-styles

/cc @justinfagnani

Moved from googlearchive/polymer-element-catalog#57

Publish vulcanized version

Right now bowering iron-component-page results in 27 components. This pollutes the components folder with a lot of otherwise potentially unnecessary stuff. A vulcanized version of iron-component-page would produce just 1 component in the components folder which would be a nice simplification.

The goal is to facilitate iron-component-page being a direct dependency of elements rather than a devDependency. This way the docs are available whenever a user installs the element.

The vulcanize step should be part of the release process for iron-component-page.

Support deep-linking of API docs

For example, on:

http://polymer.github.io/polymer/

How do I link to dom-repeat.filter()?

Not sure whether this issue belongs here, iron-doc-viewer, or elsewhere, but we should support this both in the core API docs and in the catalog.

Request: Generate event description automatically for properties with notify: true

Especially for users unfamiliar or new to Polymer, it's not usually clear that the small notifies notation on the property actually means firing a *-changed event.

Generating event descriptions in the Events section automatically for these events would drastically improve the readability of the API for users.

Multiple demos not supported

Need a UI when multiple demos are there.

Support for custom area's of documentation (Styling for example)

I would like to include a section on Styling my element, maybe just a way to say what custom variables and mixins I have provided.

Would something like this be feasible?

Rewrite this entire element

Documentation for a behavior is duplicated when trying to document extended behaviors

When trying to document a behavior that extends existing behaviors I end up using the @polymerBehavior annotation in two places; once above the implementation of the behavior, and once before declaring the array with the existing behaviors. So basically code is as follows:

/** @polymerBehavior BehaviorName */
BehaviorImpl = {
...
}

/** @polymerBehavior **/
BehaviorName = [ExistingBehavior, BehaviorImpl];

From looking at the Polymer code base I have concluded that this is the correct way to annotate this.

The problem arises when I use iron-component-page to create a documentation viewer for all of my elements and behaviors. In the select in the top left corner my behavior is listed twice because of the duplicate annotation. When I try moving the annotations around, I either get a single incomplete documentation page (properties or behaviors will be missing), or multiple complete ones depending on how the annotations are set up.

Ideally I would like a single, complete documentation page.

Is there anyway to do that in the current annotation scheme?

My iron-component-page looks like:

<iron-component-page src="elements.html"></iron-component-page>

Where elements.html is simply a series of html imports pulling in the elements and behaviors.

Choose the default doc to show for repositories with multiple elements

I would like a way to choose which doc page is shown by default for repositories with multiple elements.

hidden$="[[_activeDescriptor]]" causes JSON serialization error

_activeDescriptor is a big doc, and a circular structure. Trying to JSON.serialize(_activeDescriptor) throws "TypeError: Converting circular structure to JSON"

It is very sensible to bind it to a hidden attribute.

It is not sensible for Polymer to serialize _activeDescriptor just to set a boolean.

Parenthesis added in shadow DOM

When you load up the element in shadow DOM weird () are shown behind each property name. Additionally in shadow DOM anchor tags do not work so those should probably be disabled.

rawgit URL rewrite breaks custom github pages implementations.

Could we make the rawgit URL rewrite configurable on/off? I'm trying to place my documentation on github pages, and some of the elements are not hosted on my master branch, so this currently fails for me when the pages URL is rewritten to a rawgit URL.

Styles look funky for params on seed-element

When following the docs to generate a component page for seed-element, the styles seem to fall apart.

I can fix by changing a margin defined in iron-component-page (shown in dodgy gif video below), but I don't see the issue on the official seed-element component page. The issue can be seen live on the component page of my clone of seed-element.

Chrome

Firefox

Publishing for gh-pages

I was following the instructions set out here
https://www.polymer-project.org/1.0/docs/start/reusableelements.html

and besides some other issues (Polymer/tools#53) I did manage to manually follow the instructions in their gp.sh to push a gh-page branch with my demo.

However, there doesn't seem to be any icon-component-page that got sent to my gh-page aswell. My main question - is this something that this Repo needs to address, or is it part of the Tooling chain? How do I get my nice looking iron-component-page online with minimal fuss

Documenting dependencies when run from incorrect directory structure

If you have a directories like:

your_component/index.html
your_component/your_component.html
your_component/bower_components/depenencies...

And you run iron-component-page from index.html, and in your your_component.html you reference your dependencies like bower_components/iron-image/iron-image.html, then the resulting documentation will include all your dependencies, including polymer itself.

When, however, you move your component to your_component/bower_components/your_component /and change the dependencies paths to ../iron-image/iron-image then it works as expected: we only document the elements in your_component.html.

Can this please be made explicit in the documentation and the article at https://www.polymer-project.org/1.0/tools/documentation.html ? Because it's not at the moment. And it causes pain, much pain.

New base property causes _srcChanged() to be invoked before this.src is set

4bc8531 introduced a race condition in which the new base property causes the _srcChanged() observer to be called before the src property is set.

Inside _srcChanged(), the check for this.src ends up being evaluated to false even if src is set on the element, since it hasn't been copied over to this yet.

This breaks doc pages when the src is meant to be something other than the parent directory's name with the .html suffix.

Ignoring Specific Components

I've got a composite Polymer control that is composed of a number of elements, some of which are only used internally. Is there any way of preventing a particular control (html import) from appearing in the documentation. I have a wrapper html import that just imports the components that I want to expose documentation for, but the internal ones also appear in the documentation because they're sub imports.

if 'No documentation found.' import readme.md markdown?

Support multiple sources

Can we have a multiple source support. like:

sources='["one.html", "two.html", "three.html"]'

Remove old branches

I think that we can remove the old branches:

22-scroll-fix-kschaaf (already merged)
danrs-redesign
devDeps (already merged)
fix-default-active (already merged)
polish (already merged)
transitiveBehaviors
update-for-0.9 (already merged)

attributes vs. properties

A recurring problem that people seem to have is the new attribute to property mapping in 1.0.

They try something like <custom-element myProperty="{{something}}"> because myProperty is listed in the element docs, where they should be using <custom-element my-property="{{something}}">

It would be nice to somehow display both the property and the attribute name in the generated docs. Especially beginners won't find their way all the way to the "property name mapping" part in the docs.

Should display the properties defined in behaviors.

The main doc should display the properties defined in behaviors, so people won't need to click on each behavior to know what properties they can use.

polybuild failing when page is including iron-component-page

I've ran into an issue with the 1.1.3 release of iron-component-page that is causing the polybuild of my project to fail with an error like this:

[15:59:44] Error in plugin "polyclean"
Message:
    Line 257: Unexpected token (
Details:
    index: 7362
    lineNumber: 257
    column: 27
    description: Unexpected token (

I've tracked it down to this change in commit 37481d3 made in PR #76 . Not sure if it was intentional or not, but looks like an ES2015 method definition is being used. Uglifyjs apparently does not support ES2015 yet. Simple fix would be to define the method without using ES2015 method definition.

_setActiveFromHash: function(hash) {

https problem with demo URL on gh-pages

Unfortunately github has the bad habit of redirecting https://name.github.io/my-element/components/my-element/demo to http://name.github.io/my-element/components/my-element/demo/ which results in the iframe not being loaded when accessing the gh pages via https.

This is really a github issue (and I will report it accordingly) but setting the _demoUrl to demo/ instead of demo by default would also prevent this issue.

Is this live somewhere?

If so, it would be nice to set the website of this GitHub repo to point to the live instance.

Example:

https://elements.polymer-project.org/elements maybe?