fron 0.2.0rc1 → 1.0.0rc1

data/website/examples/my_box.rb

@@ -0,0 +1,9 @@
+# My Box....MINE!MIIINEEEE!!!
+class MyBox < Fron::Component
+  tag 'my-box'
+
+  style background: :red,
+        display: :block,
+        height: 100.px,
+        width: 100.px
+end

data/website/examples/my_button.rb

@@ -0,0 +1,27 @@
+# Simple button class
+class MyButton < Fron::Component
+  # Set the tag
+  tag 'my-button'
+
+  # When clicked greet the user
+  on :click, :greet
+
+  # Some styling...
+  style border: '1px solid #CCC',
+        display: 'inline-block',
+        background: '#F9F9F9',
+        padding: '5px 15px',
+        borderRadius: 5.px,
+        cursor: :pointer
+
+  # Set default text
+  def initialize
+    super
+    self.text = 'Click Me!'
+  end
+
+  # Greet the user
+  def greet
+    alert('Hello there!')
+  end
+end

data/website/examples/my_green_box.rb

@@ -0,0 +1,14 @@
+# Hulk SMASH!
+class MyGreenBox < MyBox
+  tag 'my-green-box'
+
+  style justifyContent: :center,
+        alignItems: :center,
+        background: :green,
+        display: :flex,
+        span: { fontWeight: :bold,
+                fontSize: 20.px,
+                color: '#FFF' }
+
+  component :span, :span, text: 'Doh!'
+end

data/website/examples/source_reader.rb

@@ -0,0 +1,32 @@
+# Source Reader
+class SourceReader < Fron::Component
+  # Set the tag
+  tag 'source-reader'
+
+  # Button for initialize loading
+  component :button, 'button', text: 'Load source...'
+
+  # Styles
+  style whiteSpace: 'pre-wrap',
+        background: '#F9F9F9',
+        borderRadius: 5.px,
+        display: :block,
+        padding: 20.px
+
+  # Event to load
+  on :click, :button, :load
+
+  # Load source
+  def load
+    request.get do |response|
+      self.text = response.body.split("\n")[0..2].join("\n") + "\n..."
+    end
+  end
+
+  private
+
+  # Request object
+  def request
+    @request ||= Fron::Request.new '/assets/pages/utilities/request.md'
+  end
+end

data/website/examples/text_area.rb

@@ -0,0 +1,42 @@
+# Text Area component
+class TextArea < Fron::Component
+  # Set the tag
+  tag 'text-area'
+
+  # Create textarea
+  component :textarea, :textarea
+
+  # Save on input
+  on :input, :save
+
+  # Styles
+  style textarea: { border: '1px solid #EEE',
+                    fontFamily: 'Open Sans',
+                    minHeight: 100.px,
+                    fontSize: 18.px,
+                    padding: 20.px,
+                    width: '100%' }
+
+  # Load on initialization
+  def initialize
+    super
+    load
+  end
+
+  # Load from LocalStorage
+  def load
+    @textarea.value = storage.get(:value).to_s
+  end
+
+  # Save to LocalStorage
+  def save
+    storage.set :value, @textarea.value
+  end
+
+  private
+
+  # Helper method
+  def storage
+    Fron::Storage::LocalStorage
+  end
+end

data/website/pages/components.md.erb

@@ -0,0 +1,16 @@
+# 4. Components
+Components are the main part of Fron. Everything is built around / for them, although nothing in the library is using them so you can say that they are the end product.
+
+## What is a component?
+A **component** is basically a custom **HTML Element** that you can **add methods to**, **extend** and **compose** into other components. It is defined by **Fron::Component** class.
+
+An input field using contenteditable attribute:
+<%= example 'ContentEditable' %>
+
+## How does it work?
+Basically the **native HTML Element** is **wrapped** in a Ruby class instance. If you are curious about the implementation check the source [here](https://github.com/digitalnatives/fron/blob/master/opal/fron/dom/element.rb) and [here](https://github.com/digitalnatives/fron/blob/master/opal/fron/core/component.rb)
+
+## How it is different from Web Components?
+[Web Components](https://css-tricks.com/modular-future-web-components/) use new technologies that are not available everywhere, also they introduce a lot of concepts that seem odd and complicated.
+
+Fron components are straightforward and easy to learn.

data/website/pages/components/composition.md.erb

@@ -0,0 +1,9 @@
+# 4.2. Composition
+Components can be composited together with the **component** DSL method.
+This allows you to create more complex components like this paragraph component:
+
+<%= example 'ImageParagraph' %>
+
+As you can see the components we defined (**image** and **content**) are accessible with
+**instance variables** also with **instance methods** but only if there is no method
+defined with that name.

data/website/pages/components/events.md.erb

@@ -0,0 +1,20 @@
+# 4.3. Events
+Handling events are pretty easy by using the **on** DSL method in a component:
+when an **event** happens on the element the given **instance method** is called.
+
+There are two ways of adding events:
+* Adding events directly to the component is used when it's not important which
+	child component triggered the event, or the event isn't delegateable like
+	**focus** or **blur**:
+  ```ruby
+  on :blur, :close
+  ```
+* Delegating events with a **selector** is usefull if we only want to handle events
+  that were trigger child components matching a specific selector.
+  ```ruby
+  on :click, 'button > span', :open
+  ```
+
+For example let's say there is a component for converting **celsius** to **fahrenheit**:
+
+<%= example 'Converter' %>

data/website/pages/components/inheritance.md.erb

@@ -0,0 +1,19 @@
+# 4.1. Inheritance
+Because **components** are just **ruby classes**, that means that they can be exteded
+and reused.
+
+Let's say that there is a **Button** component that greets you when you click it,
+and we would like to have an icon before the text, but it doesn't support that:
+
+<%= example 'MyButton' %>
+
+What we can do is to create an **IconButton** component that extends the **Button** component,
+and add the functionality to that:
+
+<%= example 'IconButton' %>
+
+What we did was:
+* we extended the **Button** component so the events, styles and methods are inherited
+* we added two components one for the **icon** and one for the **text (span)**
+* we delegated the two methods **text** and **text=** in order to not break the API
+* we added some styles to the **icon** component

data/website/pages/components/routes.md.erb

@@ -0,0 +1,49 @@
+# 4.4. Routes
+Routing is supported in Fron via the **Fron::Behaviors::Routes** module, and
+currently is very sparse.
+
+When used in a **component**, routes can be defined in order to call an
+_instance method_ when the page location changes to match a perticular
+regular expression or string:
+
+```ruby
+class Main < Fron::Component
+  include Fron::Behaviors::Routes
+
+  route '/users', :users
+  route '/posts', :posts
+
+  def users
+    # Display users
+  end
+
+  def posts
+    # Display posts
+  end
+end
+```
+
+## Handling Parameters
+
+If capture groups are defined for the regular expression than they will be
+forwarded to the method as arguments:
+
+```ruby
+class Main < Fron::Component
+  include Fron::Behaviors::Routes
+
+  route '/users/(.*)', :show_user
+
+  def show_user(id)
+    # Display user with the given id
+  end
+end
+```
+
+Things to keep in mind when handling routes:
+* Multiple components can include this module and define routes
+* If multiple components matches a route then only one (the first) will
+  be called
+* Components that are not in the DOM can handle routes too
+* The best practice is to have one component to handle all the routes and then
+  delegate down the component tree

data/website/pages/components/styles.md.erb

@@ -0,0 +1,38 @@
+# 4.5. Styles
+One of the things that makes Fron unqiue is the ability to style components
+directly on them. To achieve this we will use the **Fron::Behaviors::Style**
+module (which is automatically included into every component).
+
+Once the application is initailized all of the styles are rendered into a
+**style** tag into the head of the document.
+
+## Basic Usage
+To define styles to a **component** you only need to call the **style** DSL
+method with the object for the properties and values:
+
+<%= example 'MyBox' %>
+
+Tips on creating great style objects:
+* For numbers there is two helper modules **px** and **em**, use them often
+* Symbols can be used for non hypenated CSS values such as _block_ or _flex_
+* Any value can be a Ruby expression
+* Any value can be a lambda that is evaluated when the style is rendered
+* Use caplitalized keys. They are converted to their hypenated versions
+
+## Inheritance
+When a component extends an other component that have styles, all of the style
+definitions are copied over (this happens when the style DSL is used, otherwise
+the **ensure_styles!** method needs to be called). Styles that are defined on the
+child component have priority over the ones defined in the parent component.
+
+Also if properties defined multiple times, only the last one will be used.
+
+<%= example 'MyBlueBox' %>
+
+## Styling Nested Components
+
+If the component have **nested components** then they can be styled by having
+a key with a selectors (like in raw CSS) and the associated value as a hash
+containing the CSS properties and values:
+
+<%= example 'MyGreenBox' %>

data/website/pages/getting-started.md

@@ -0,0 +1,8 @@
+# 2. Getting Started
+This guide is for anyone who wants to get started with Fron. It's recommended to have a basic understanding of the **Ruby / JavaScript / CSS** programming languages and be familiar the **DOM**.
+
+In order to try the examples the following prerequisites must be installed:
+* Working Ruby installation. You can get the lastest Ruby from [Ruby download page](https://www.ruby-lang.org/en/downloads/)
+* A web browser such as [Chrome](https://www.mozilla.org/en-US/firefox/new/) or [Firefox](http://www.google.com/chrome/)
+
+You can find the examples [here]().

data/website/pages/home.md

@@ -0,0 +1,4 @@
+# Fron
+## User Interface with the power of Ruby
+
+Fron is a component based User Interface framework.

data/website/pages/intro.md

@@ -0,0 +1,30 @@
+# 1. Introduction
+This guide will walk you through the basic concepts behind Fron. Fron is a library
+for creating dynamic **composeable user interfaces** with Ruby (through Opal).
+
+## Features
+* **Custom components** that can be extended and composed
+* **Behaviors** to specify how components behave
+* **Utilities** such as **Request**, **Shortcuts** or **Drag & Drop**
+* **Testable** with **RSpec**
+
+## Resources
+* Source Code: [https://github.com/digitalnatives/fron](https://github.com/digitalnatives/fron)
+* Yard Documentation: [http://www.rubydoc.info/github/digitalnatives/fron/master](http://www.rubydoc.info/github/digitalnatives/fron/master)
+
+## Why Ruby?
+We chose ruby for these awesome features:
+* It is a **mature language** (20 years)
+* Has a very good **module** and **class** system
+* A **coding style guide** is already present
+* **Testing** is and always have been a core part (Rspec)
+* The **tooling** is great (Rubycritic, Rubocop, Sprockets just to name a few)
+
+## How it is different from [Volt](http://voltframework.com/) or [Vienna](https://github.com/opal/vienna)?
+Both of those frameworks apply the same logic that has been used to create web sites for decades, namely the MVC pattern and templates, also they are not using the DOM
+in a Rubyesque way, they treat the frontend as you would in a Rails application.
+
+Fron is different because it is not trying to be a full featured web application, it is just the **fron(tend) part** in **Ruby**.
+
+## It is used in production?
+Currently we use it in production in one of our inhouse products [Nostromo](https://nostromo.io).

data/website/pages/utilities.md

@@ -0,0 +1,10 @@
+# 5. Utilities
+Fron provides a few **utility classes** by default:
+
+* **Request** - Making and handling requests
+* **LocalStorage** - LocalStorage wrapper
+* **Keyboard** - Adding and handling shortcuts
+* **Drag** - Low level dragging support
+
+These classes are not connected to the interfaces directly but helps you solve a lot
+of issues that generally come up for web applications.

data/website/pages/utilities/local-storage.md.erb

@@ -0,0 +1,16 @@
+# 5.2. Local Storage
+
+*Notice: Only the LocalStorage and SessionStorage is implemented, we plan to implement CookieStorage with the same interface.*
+
+This utility is for storing things in [LocalStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) you can see the API documentation [here](http://www.rubydoc.info/github/digitalnatives/fron/master/Fron/Storage/LocalStorage).
+
+It implements the following class methods:
+* **all** - Returns all keys and their values in a hash
+* **clear** - Clears all keys
+* **get(key)** - Get the value of the given key
+* **remove(key)** - Removes the given key
+* **set(key, value)** - Sets the given value to the given key
+
+As an example the contents of this textarea persists between reloads:
+
+<%= example 'TextArea' %>

data/website/pages/utilities/request.md.erb

@@ -0,0 +1,12 @@
+# 5.1. Request
+
+*Warning: Not all features are available yet, but it's usable.*
+
+This class is a wrapper for the [XMLHttpRequest](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest). You can see the API documentation [here](http://www.rubydoc.info/github/digitalnatives/fron/master/Fron/Request).
+
+As an example we want to display the first there lines of the source of this page in a component:
+
+<%= example 'SourceReader' %>
+
+As you can see we instantiated a new [**Fron::Request**](http://www.rubydoc.info/github/digitalnatives/fron/master/Fron/Request) object and called
+the **get** method to get the source which returned a [**Fron::Response**](http://www.rubydoc.info/github/digitalnatives/fron/master/Fron/Response) object.

data/website/setup.rb

@@ -0,0 +1,162 @@
+require 'fron'
+require 'vendor/highlight'
+require 'vendor/highlight.ruby'
+require 'vendor/marked.min'
+
+require 'examples/my_button'
+require 'examples/my_box'
+require_tree './examples'
+
+%x{
+  marked.setOptions({
+    highlight: function(code) {
+      return hljs.highlightAuto(code).value;
+    }
+  });
+}
+
+class Sidebar < Fron::Component
+  class Item < Fron::Component
+    tag 'header-item'
+  end
+
+  component :title,      'sidebar-title', target: :home, text: 'Fron'
+  component :about,      'sidebar-item', target: 'intro', text: 'Introduction'
+  component :dom,        'sidebar-item', target: 'getting-started', text: 'Getting Started'
+  component :setup,      'sidebar-item', target: 'the-dom', text: 'The DOM'
+  component :components, 'sidebar-item', target: 'components', text: 'Components'
+  component :components, 'sidebar-sub-item', target: 'components/inheritance', text: 'Inheritance'
+  component :components, 'sidebar-sub-item', target: 'components/composition', text: 'Composition'
+  component :components, 'sidebar-sub-item', target: 'components/events', text: 'Events'
+  component :components, 'sidebar-sub-item', target: 'components/routes', text: 'Routes'
+  component :components, 'sidebar-sub-item', target: 'components/styles', text: 'Styles'
+  component :behaviors,  'sidebar-item', target: 'utilities', text: 'Utilities'
+  component :behaviors,  'sidebar-sub-item', target: 'utilities/request', text: 'Request'
+  component :behaviors,  'sidebar-sub-item', target: 'utilities/local-storage', text: 'Local Storage'
+
+  style counterReset: :items,
+        padding: 20.px,
+        'sidebar-title' => {
+          borderBottom: '2px solid #EEE',
+          paddingBottom: 5.px,
+          marginBottom: 10.px,
+          display: :block,
+          fontWeight: 600,
+          fontSize: 24.px
+        },
+        '[target]' => {
+          cursor: :pointer
+        },
+        'sidebar-item' => {
+          borderBottom: '1px solid #EEE',
+          counterIncrement: :items,
+          counterReset: :subitems,
+          padding: '10px 0',
+          display: :block,
+          '&:before' => {
+            content: 'counter(items) ". "'
+          }
+        },
+        'sidebar-sub-item' => {
+          borderBottom: '1px solid #EEE',
+          counterIncrement: :subitems,
+          padding: '10px 0',
+          paddingLeft: 10.px,
+          display: :block,
+          '&:before' => {
+            content: 'counter(items) "." counter(subitems) ". "'
+          }
+        }
+
+  on :click, '[target]', :navigate
+
+  def navigate(event)
+    DOM::Window.state = "/#{event.target[:target]}"
+  end
+end
+
+class Main < Fron::Component
+  include Fron::Behaviors::Routes
+
+  component :sidebar, Sidebar
+  component :wrapper, :wrapper do
+    component :container, :container
+  end
+
+  style fontFamily: 'Open Sans',
+        width: 1200.px,
+        margin: '0 auto',
+        color: '#444',
+        a: {
+          textDecoration: :none,
+          color: '#00ACE6'
+        },
+        sidebar: {
+          width: 240.px,
+          float: :left
+        },
+        pre: {
+          background: '#F9F9F9',
+          borderRadius: 5.px,
+          padding: 20.px
+        },
+        wrapper: {
+          overflow: :auto,
+          padding: 40.px,
+          paddingBottom: 60.px,
+          marginLeft: 240.px,
+          display: :block
+        },
+        h1: {
+          lineHeight: '1em',
+          marginTop: 0
+        }
+
+  route '(.*)', :page
+
+  def initialize
+    super
+    @pages = {}
+    Fron::Sheet.render_style_tag
+    Fron::Behaviors::Routes.listen
+  end
+
+  def home
+    DOM::Window.state = '/home'
+  end
+
+  def page(page)
+    return home if page == '/'
+    load page do |html|
+      @wrapper.container.html = html
+      @wrapper.container.find_all('example').each do |example|
+        example << Module.const_get(example['class']).new
+      end
+    end
+  end
+
+  def load(page)
+    return yield @pages[page] if @pages[page]
+    Fron::Request.new("/assets/pages#{page}.md").get do |response|
+      @pages[page] = `marked(#{response.body})`
+      yield @pages[page]
+    end
+  end
+end
+
+Fron::Behaviors::Style::Sheet.add_rule '*', { boxSizing: 'border-box' }, '0'
+Fron::Behaviors::Style::Sheet.add_rule 'body', { margin: 0,
+                                                 overflowY: :scroll,
+                                                 fontSize: 18.px,
+                                                 lineHeight: 26.px }, '1'
+
+['//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css',
+ '//fonts.googleapis.com/css?family=Open+Sans:400,600,700',
+ '//cdnjs.cloudflare.com/ajax/libs/highlight.js/8.5/styles/tomorrow.min.css'
+ ].each do |url|
+  link = DOM::Element.new 'link'
+  link[:rel] = :stylesheet
+  link[:type] = 'text/css'
+  link[:href] = url
+  link >> DOM::Document.head
+end