gss / compiler

GSS compiler

GSS runtime

WARNING: GSS is highly unstable right now, there be dragons...

Compiles and runs Grid Style Sheet (GSS) rules. GSS is an implementation of Badros & Borning's Constraint Cascading Style Sheets, enabling far better layout control through building relational rules between different elements.

GSS supports the following syntaxes for defining layout rules:

• CCSS - direct constraints related to position and size of DOM elements
• VFL - horizontal and vertical spacing constraints based on Apple's Visual Format Language

Additionally, support for GTL, based on the W3C Grid Template Language is planned.

The main GSS repository provides a Component library handling both the compilation and application of the layout constraints.

Installation

You need to include the GSS runtime library to the pages where you want to utilize GSS rules:

<script src="gss.js"></script>

Additionally you need to make the GSS constraint solver Web Worker available on the same server.

Installation via Component

If you're using Component for managing your project dependencies you can also include the project into your build dependencies, in which case it doesn't need to be included to the pages separately.

{
  "dependencies": {
    "the-gss/gss": "*"
  }
}

Usage via HTML

The easiest way to run GSS is to include the JavaScript file into your pages, and then simply write some rules inside a style tag:

<style type="text/gss">
  /* Ensure nodes are square and of touchable size */
  [node-width] == 58;
  the-graph-process[width] == the-graph-process[height];
  the-graph-process[width] == [node-width];

  /* Center process label */
  .the-graph-process-label[left] == [node-width]/2 - .the-graph-process-label[intrinsic-width]/2;
</style>

The GSS runtime will find all these style tags and apply the constraints from them.

Usage via JavaScript

First load the GSS runtime CommonJS module:

var GSS = require('gss');

To utilize the GSS runtime you need to instantiate it. Each instance of GSS needs to know the URL where the Web Worker file is available.

var engine = new GSS('/some/path/to/gss-solver.min.js');

Optionally you can limit the GSS engine to some particular are of your DOM by giving it a containing element. In that case the rules will only apply to elements inside the given container:

var container = document.querySelect('.container');
var engine = new GSS('/some/path/to/gss-solver.min.js', container);

Once you have the GSS runtime instantiated, you can solve rules by sending them to the instance:

engine.run('@horizontal [#box1]-[#box2]-[#box3]-[#box4]-[#box5]-[#box6];');

You can provide as many GSS rules as you need in the string. You can also call the run method multiple times to register new rules.

The GSS runtime will invoke the GSS engine, which measures the DOM elements specified in the rules, and solves their optimal sizes and places using the Cassowary constraint solver. The GSS engine will then update the CSS rules on the page accordingly.

compiler's Issues

Remove remotes array from component.json

As instructed in the component spec.

I found out the hard way that the existence of this causes any dependencies in component.json to fail, and possibly other unexpected behavior.

No license

An MIT license is listed in package.json but not present in the repo.

Also, the URL in package.json is broken.

Use local reference for chai in spec runner

Currently being loaded from http://chaijs.com/chai.js

Throw compiler errors

Currently the GSS compiler uses console.warn (or .error?) to log compiler errors. They should be thrown instead so that they can be caught by a GSS editing UI.