sourcejs/source

[ON HOLD] Living Style Guides Engine and Maintenance Environment for Front-end Components. Core repository.

source's Issues

Specs API

We're working on specs API that will contain parsed information from all spec example sections (with HTML) and all information about spec pages (from info.json).

Here's first example of API usage http://youtu.be/cefy_U5NU4o. In video, you can see that Design-lego tools takes navigation tree from Source specs API and draws selected elements from example section in working space.

If you want to get some specific API queries, please drop your thoughts in comment below.

Move git ingored files from Source to custom folder

Recommended setup for using Source is to keep two git repos - first is Source repo, second contains all specs in public folder. For now, we have files that aren't stored in any repo and are git ignored by default in Source, those files are stored in /user folder and /client-side/plugins.

I'm thinking about moving all files that are now git ignored in Source to another common folder with /public contents to unite them in one repo. This will make sync process in team much easier, all setting files will be in repos and we'll be able to deploy Source to remote through git.

As I see, the only downside of this refactoring is that repos with specs must be restructured this way:

//specs repo
user

specs
  //from Source
  docs
  core
  test

  //user spec catalogues ant settings
  main
  user

To leave a possibility to use custom settings on each setup, we can add custom git ignored options, where path to /user could be overridden.

Also, maybe someone have thoughts about renaming /user folder, this folder is used for custom client and server side settings that are overriding default Source settings.

Add possibility to create custom templates for clarify module

Redirect from host shortlink to localhost:8080 on Windows

Redirecting from host shortlink, say, 'source' to localhost:8080 can be perfomed by the following command:

netsh interface portproxy add v4tov4 listenport=80 listenaddress=127.0.0.1 connectport=8080 connectaddress=YOUR_LOCAL_ADDRESS

Clarify: Scope CSS of helper panel

Place Clarify Helper panel in Shadow DOM with scoped CSS to prevent conflicts with examples styles.

Auto-generated documentation for JS

I'm thinking about integrating some of this tools https://github.com/nevir/groc http://jashkenas.github.io/docco or JSDoc based compiler into Source Spec pages.

With this kind of integration, we could get auto-generated JS docs right inside our Source Spec pages with access to all Source plugins.

Transcribing search results

Make available to use different languages in search with transcription using latin letters and vice versa.

example:

you search "lenta" - you get "лента"
you search "триггер" - you get "trigger"

Interactive graphics documentation

http://d.pr/i/RwpI

• Images folder parsing
• Search through existing images
• Filters by size/color
• Drag n drop icon to create a PR with new or updated icon

Incorrect link to examples/specs

When trying to open specs it leads to incorrect destination (404 page).

Change volojs to bower for plugin dependencies

404 page link adviser

Link proposal service, based on your (incorrect) url request

404 page design

Formatted code examples UI improvements

Hi,

Would be great to prevent blinking source code, when using <code class="src-html source_visible"></code>, showing only formatted version with prism, when it's ready.

Also, we need to check if code examples drawing is delaying final Spec Ready event, to keep scrollToHash working properly. Check http://sourcejs.com/docs/api/load-events/

Passing GET params to spec causes error, branch v.0.4.0

Hi! Trying to pass GET params to spec causes error, for example:

http://localhost:8080/design/hosting/login/index.src?test=1

Debugged and found Source/core/middleware/read.js line 16:
var physicalPath = global.app.get('user') + req.url;

and line 75:
var requestedDir = req.url;

then correct it to:
var physicalPath = global.app.get('user') + req.path;
var requestedDir = req.path;

default.css overriding project typographic styles in .source_example blocks

Currently, project.css base styles for typographic elements (p, ul, li, small etc.) in .source_example blocks are overridden by default.css.

These elements are being styled via the following properties in reset.less, and are not overridden by project.css due to it being linked earlier in the document:

// reset.less
body {
    ...
    font: 14px/1.5 Arial, Helvetica, sans-serif;
    color: #333;
    ...
    }

font and color can be declared on html so that users declaring those properties on their own html element can easily override them.

Furthermore, core.css is, by default, linked after project.css.

This does the following:

1. ensures base typographic Source styles outside of .source_example are always applied (desirable, but not essential)
2. values set on body / html will override those of project.css as a result of being later in the source order (undesirable)

Solutions

@import project.css In user.css

This is the solution I've gone with for now.

My project.css is now applied across all my spec pages, and there is no issue with basic typographic elements inheriting Source styles (since all typographic elements are now styled via project.css).

This has the added bonus of making the spec more consistent with the theme of the project.

If this is the preferred solution, I'll be happy to add it to the documentation.

Apply Source Styles Everywhere Except In .source_example

I've attempted some combinations of selecting everything except for the contents of .source_example to apply Source styling to no avail:

:not(.source_example) {
    font: "...";   // Source base font styles
    color: "..."; // Source base colours
}

I'm not sure if someone else can come up with something using :not that works - this would be the most elegant solution, and wouldn't require any amendments to documentation or work after initiating a Source instance.

Move Base Styles To Their Own Stylesheet

Move base styles, and styles applied to naked elements (without classes), to a separate css file which is linked before project.css

• this ensures that base fonts, colours, and sizes used by Source can be easily overridden
• it has the side effect that project.css styles will override all Source styles, thus changing how Source looks
  • makes styling across the site inconsistent for pages not linking project.css
• more stylesheets need to be managed

Do Not Apply Styles Directly To 'Naked' Elements

Do not apply any styles directly to any elements that do not have a source_ class, or are not immediate children of a source_ class.
i.e. font and color in core.css / default.css are only ever applied in the following manner:

.source_section > p,
.source_section > small, 
    .
    .
    . {
    font: "...";
    color: "...";
}

etc.

This may turn out to be a maintenance nightmare, and will have strange side effects should a user surround a paragraph in a div in their documentation.

I may be missing something huge here, so feel free to correct me if I'm wrong!

// end of blog post

Create yeoman generator for Source init

Create yeoman generator for Source init instead of running grunt init. Refactor some file structure for easier first setup.

Configure custom Spec pages as separate modules

Add configuration scenario to add this kind of Interactive Specs as a dependency from separate repo https://github.com/sourcejs/styles.

Among plugins, Source could have custom pages (small application) for different team needs. After Styles page will be also release Graphics page and Front-end resources management dashboard.

Source as service

I have some ideas for creating Source as service and hosting private and public documentations.

The workflow with Source as service could look like this:

Client "feeds" their repository with public contents and gets private space for documentation based on Source engine. Also, there could be some integrations with Dropbox Storage API.

What do you think about it?

About possible *NIX JSDom problems.

Some cases can make you to have following error:

<approot>/node_modules/jsdom/node_modules/contextify/node_modules/bindings/bindings.js:91 throw err
Error: Could not locate the bindings file. Tried:
<approot>/node_modules/jsdom/node_modules/contextify/build/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/build/Debug/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/build/Release/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/out/Debug/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/Debug/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/out/Release/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/Release/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/build/default/contextify.node
<approot>/node_modules/jsdom/node_modules/contextify/compiled/0.10.28/linux/x64/contextify.node
    at bindings (<approot>/node_modules/jsdom/node_modules/contextify/node_modules/bindings/bindings.js:88:9)
    at Object.<anonymous> (<approot>/node_modules/jsdom/node_modules/contextify/lib/contextify.js:1:96)
    at Module._compile (module.js:456:26)
    at Object.Module._extensions..js (module.js:474:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Module.require (module.js:364:17)
    at require (module.js:380:17)
    at Object.<anonymous> (<approot>/node_modules/jsdom/lib/jsdom/browser/index.js:17:21)
    at Module._compile (module.js:456:26)

Typically it is caused by node_modules folder copying to another location (deployment or smth like that).

It can be solved by the following steps:

cd <approot>/node_modules/jsdom/node_modules/contextify
npm i

Please follow this link to get more details.

Drawing navigation from nested catalogues

Add a possibility to draw navigation from nested catalogues without index.html on same level (buttons):

docs/
├──base/
   ├──buttons/
      ├──promo/
      ├──basic/

now it's possible only with this structure:

docs/
├──base/
   ├──buttons/
      ├──promo/
      ├──basic/
   ├──index.html

Also, there must be a possibility to have few catalogues with same name, like:

docs/
├──base/
   ├──buttons/
      ├──promo/

├──custom/
   ├──buttons/

That would be generated from this hooks:

<div class="source_catalog" data-nav="base/buttons"></div>
<div class="source_catalog" data-nav="custom/buttons"></div>

Clarify: Add responsive layout testing menu

Like in pattern lab http://demo.patternlab.io/?p=organisms-article-body http://d.pr/i/4U02

Client-side development mode

Client-side development mode with special options, for disabling some Source plugins in dev mode. The same modes functionality will be used to turn on some dev plugins in the production mode.

Inner navigation changes url to index.html

Inner navigation changes url to index.html in pages with different names like index2.html. Need to get rid off index.html dependency.

Tests

Apply tests with jasmine and dalek.js to all core functionality

.src files support with header/footer include on server side

.src files support will free us from copy/pasting common parts of spec pages like resources in <head> and Source header/footer, as we do now in .html files.

Data for custom parts of included content will be regulated from info.json file next to index.src.

As this files will be processed through node.js (with ejs templating engine), soon we will have a possibility to write a markdown markup directly in Spec Pages under .src extension.

Use shadow DOM for isolating `source_example` scope from external CSS

Right now, to isolate SourceJS UI styles from source_example blocks, we generate complex CSS selectors with Less. Would be great to replace this in future with Shadow DOM, as these guys are doing http://styleguide.sc5.io.

Fix scroll to section

Fix scroll to section in cases where page is loading slower than scroll navigation + loader for spec page to get rid of nasty page jumps.

Renaming /client folder

It seems like /client isn't a best name for folder with client side part of Source engine, we have some thoughts about renaming it to:

• client-side
• front-side
• front-end
• front

What do you think about it?

Make SourceJS as global or local node module

With custom, abstract commands like:

sourcejs run
sourcejs deploy

Which will take current run folder as user.

Moving SourceJS to global module, will probably help to install it much easier to understand.

Intended workflow

I'm looking at using Source for a new project, and have been trying to work out the workflow with regards to creating and updating specs, as well as the non-spec templates found in client/init/.

This is my understanding of some of how Source works:

• grunt update minifies and copies only the files found under client/src/ to public/
• grunt initClient copies the files from both client/src/ and those from client/init/user to public/
• public/ is the build folder, and is therefore gitignored
• user/ holds user specific settings, and is therefore also gitignored

From this it seems as though this should be my workflow:

1. all spec'ing is done inside client/src/docs/
2. use grunt runWatch to watch for changes in client/src/ to dynamically build public/
3. to update footer.inc.html, header.inc.html, and the Source home page, edit the contents of client/init/, and then run grunt initClient

Is this the correct approach in using Source?

Search results better output

So far we got live-search results in main input field.
Few improvements to suggest here:

• ability to cmd/ctrl - click on result and have it opened in a tab or whatever (alternatively we could use extra link to open all results in separate tabs)
• have a new link to open separate page with all possible results on query
  Something like this: http://puu.sh/9evEI/66f6628168.png

Implement git dates for defining last change date of Specs

Last changed date from local file is not stable, and easy to lose. We're going to implement git dates support.

Full .src files support

• Adding .src files support to all level pages in Source
• Custom views (ejs templates) for different page types
• Enhancing Spec page templets for easy resource linking in head and etc
• Clarify (@Leikam) support for .src files
• Removing mention of index.html across all Source code, replacing it with higher abstraction - specPage
• ? Migration script .html -> .src

Task for full Source deploy on remote

Create grunt task for Source server side deploy on remote server

Auto generate catalogue description

Calling

<div class="source_catalog" data-nav="base">

We need to get

<div class="source_catalog" data-nav="base">
    <h2 class="source_catalog_title"><a class="source_a_bl" href="{base.url}">{base.title}</a></h2>

    <div class="source_catalog_tx">{base.description}</div>

    <ul class="source_catalog_list">
        {base.specs}
    </ul>
</div>

Where

• base.url - is an url to full list of base/ catalogue specs
• base.title/description - its title and description from info.json
• base.specs - all nested specs

Screencasts

We're planing to record some screencasts about Source workflow, which topics do we need to cover most?

Using Source as Skins viewer

Source works nice when you have one CSS (main product styles) and want to apply it different HTML elements, thanks for this 👍

Our main product has different skins (logos, css) for different customers and i want to use source for skins system documentation.

First I'm want to solve such problem - i have one HTML code and want to apply different CSS skins to it. Idea is to show how template page (core/view/skins.ejs) looks with different styles (/skins/ sub folders).
To demonstrate i created simple project https://github.com/ashmigelski/sourcejs-skins-viewer compatible with current v.0.4.0 branch. It uses very straightforward logic - every skin is a spec with info.json and
index.src inside.
Any tips or suggestions how to make it easier and more efficient? Thanks

h1 & h3 heading inside of the .example_code section get's parsed as a Section Heading for the nav

h1 & h3 heading inside of the .example_code section get's parsed as a Section Heading for the nav

app.js -> source.js

version and development

Ребят, плохо с английским, опишу на русском.

Изменения на проекте

Хотелось бы видеть историю изменения блока. От версии к версии бывает блоки меняются, нужно оповещать разработчиков об этих изменениях. А так же возможность сравнить эти изменения.

Про разработку в Source

Должен быть механизм draft'ов. То есть разрабатываемый блок весит в draft пока не пройдет разработку, согласование, тестирование. После уже переводим в статус published и делаем оповещение разработчиков.

Catalog and menu redesign

This involves preview showing as well

About problems on Windows with JSdom

If somebody is facing problems with installing JSdom dependency for SourceJS engine on Windows, the easiest way to solve it, is to use already built binaries:

• Download them from mihaifm/jsdom_binaries for Node.js 0.10.x, 0.11.x or szarouski/jsdom_binaries for 0.12.x
• Remove jsdom dependency from package.json and run npm i
• Copy contents of jsdom_binaries/node_modules to sourcejs/node_modules, replacing old folders
• Run SourceJS

The problem comes when npm install downloads JSdom and tries to compile it locally, having xcode command line tools on OSx everything goes fine, but Windows by default doesn't have necessary tools for JSdom compilation and installation fails.

If you still want to compile binaries on your machine, or mentioned built binaries does not help, check official solution from JSdom https://github.com/tmpvar/jsdom/tree/1.5.0#contextify and alternative with node-gyp set-up instructions https://github.com/TooTallNate/node-gyp#installation.

You can also find some help with Windows set-up in this topic sourcejs/sourcejs.com#1.

JSDom is already planned to replace with Cheerio in SourceJS 0.6.x #99.

Create visual specs catalogue

Using spec screenshots from API #28, create secondary layout for specs navigation (http://sourcejs.com/docs/) with preview.

Pull request etiquette

Are you guys open to pull requests?

If so, should I issue pull requests from a topical branch straight into Source's master?

Seperate modules responsible for showing source code and inner navigation from client side core

Seperating those scripts we could use them as a light lib for any generated Style Guides.

Live templates collection for IDEA/Webstorm/PHPStorm

We have some live templates collection with fast snippets to work with Source that need to be shared with public and published in separate repository.

Setting spec path outside of Sourcejs directory causes broken tree links.

Setting my user/options/options.json to include:

  "common": {
    "pathToSpecs": "../styleguide"
   }

so that in my projects I can gitignore the Sourcejs folder and have the following structure:

/ -
   |- Sourcejs (ignored / not commited / setup by script)
   |- styleguide (Generated public folder, with core/ copied)
   |- etc ...

The generated pages tree json has broken links (e.g. ocs/buttons).
The issue can be rectified by changing as in this commit.

Links on main page based on often search results for each user

It would be great to make more personalized service using user spec search requests. Output can be built / sort by request weight.

Search settings can be saved in local account storage.

Improve navigation calatogues

http://sourcejs.com/docs/data-nav/index.src

• Add a possibility to exclude spec from search
• Add scopes (default, extended, force-all etc) for generated navigation, default scope will not show marked inner specs

Searching in nested catalogues

Can't find spec in nested catalogues through search in tolbar.

docs/
├──base/
   ├──spec/
   ├──buttons/
      ├──promo/
          ├──index.html
      ├──index.html
   ├──index.html

With this structure, search won't promo/index.html.

Problem lies in parseFileTree.js, that returns nested object for live complete plugin that search is using. getAllPages must return flat object, and if there are few kind of same named folder, the parent folders must be added to spec name in the object.