Get site ready to release Clearwater 1.0

[jgaskins]

For the final release of Clearwater 1.0, I want the docs to be ready for people to jump in and start writing Clearwater apps confidently. This issue is the one issue to rule them all, and in the tracker bind them.

Since the docs app is a Clearwater app, all pages need to be components, but we can figure out the content here in the issues with Markdown to make it simple[1].

Here are the things I was thinking of documenting. There are a lot of things here, but most of them are individual methods to document, so a lot of them can be crossed off very quickly. As always, suggestions are most welcome:

• Design
  • It looks kinda dumb. Any ideas to make it better?
• Guides
  • The Ember JS site has a "Guides" and "API" section and I absolutely love that idea. That way we can separate high-level overviews from "here's how you need to define/call this method".
  • Installation/Setup
    • Exists, but needs to be cleaned up a bit.
  • Components
    • Basic rendering
    • Handling user input
      • Individual events
      • Forms
    • Component state
      • App root components and routing targets are forever
      • All other components are ephemeral and should not store state
    • Render caching with Clearwater::CachedRender
  • Routing
    • Basic routing
    • Routing params
    • Route callback methods
• API
  • Application (Application #4)
    • #call(&block) — registers an app with the Clearwater app registry and renders it
    • #render(&block) — re-renders an app
    • #render_current_url(&block) — wires up components based on route, re-renders
  • BlackBoxNode
    • #node — override to define the initial structure of the component
    • #mount(element) — called by Clearwater just before this object is added to the DOM
    • #update(previous, element)
    • #unmount(element)
  • CachedRender
    • #should_render?(previous)
  • Component (Component #5)
    • HTML5 tag names as shorthand methods to create virtual-DOM nodes. For example, div(properties, content) delegates to tag(:div, properties, content).
    • #tag(attributes={}, content=nil)
    • #call — re-render all Clearwater apps mounted in the registry
    • #params
  • DOMReference
    • Proxy for a Bowser::Element that gets populated on DOM render
  • Link
    • Link.new is nearly the same as Component#a. Only difference is that Link components have their click events trapped, but a tags are unmodified.
  • Router
    • #route(path_segment => target, &block)
    • #params
  • VirtualDOM
    • .node(type, attributes, content)
    • .create(virtual_node)
    • .diff(from, to)
    • .patch(dom_element, diff)
  • Bowser
    • Clearwater uses the bowser gem as its browser abstraction. Clearwater apps will need to interact with some of its objects, so we'll document them here since it's also a Clearwater project.
    • Bowser::Document
      • #body
      • #[]
      • #create_element
    • Bowser::Element
      • #inner_dom= — provided for compatibility with
      • #inner_html
      • #children
      • #empty?
      • #clear
      • #remove_child
      • #type
      • #append
      • #checked?
      • #files
      • #file
      • Document delegation to native element
    • Bowser::Event
      • #target
      • #prevent
      • #stop_propagation
      • #prevented?
      • meta? / alt? / ctrl? / shift?
      • #to_n — this is an Opal convention for "to native"
    • Bowser::File — An entry in a FileList
      • #name
      • #size
      • #type
      • #last_modified
      • #read
    • Bowser::FileList — the files property for an <input type="file" /> element
      • #[]
      • #length / #size
      • #to_a
      • Enumerable mixed in
    • Bowser::HTTP — AJAX support
      • #fetch(url, method: :get) — we should make this work just like ES6 fetch, but this is what it does atm.
      • #upload(url, data, content_type: 'application/json', method: :post)
      • #upload_files(url, files, key: 'files', suffix: '[]', method: :post)
      • #upload_file(url, file, key: 'file', suffix: nil, method: :post)
    • Bowser::WebSocket
      • #initialize(url)
      • #on(event_name, &block)
      • #send_message(message)
    • Bowser::Window
      • .delay(seconds, &block)
      • .interval(seconds, &block)
      • .animation_frame(&block)
      • .scroll(x, y)

[1] What would be awesome would be a pure-Ruby Markdown parser that could output Clearwater components rather than HTML, but we're not there yet. :-)

[jgaskins]

cc @vaidehijoshi @Ch4s3