Getting Started

<section class="slab  slab--bg-gradient-grey  slab--has-ripple-top  align-full">
    <div class="slab__inner">
        <div class="wrap">

            <header class="tickertape">
                <h2 class="tickertape__highlight">
                    Getting Started
                </h2>
            </header>

            <p class="intro">The component library contains some guidance on what components are for and how to use them
                from both a content editor, and developer viewpoint on each individual component. There are also some more
                globally applicable guidelines for things like Typography, Colour, Spacing and Layout on other pages in this
                section.</p>
            <p class="intro"><strong>This is mostly technical documentation intended for those using and maintaining the
                    component library. If you don't write code, this might not be the page you're looking for, skip
                    it :)</strong></p>
            <p class="intro">In this guide you will find some (hopefully) useful notes on:</p>
            <ul class="">
                <li><a href="#fractal">Fractal and setting it up</a></li>
                <li><a href="#file-structure">Front-end architecture / file structure</a></li>
                <li><a href="#build-process">Build process / Code compilation (Gulp)</a></li>
                <li><a href="#adding-a-new-component">Guide: How to add a new component</a></li>
            </ul>
        </div>
    </div>
</section>

<section class="slab  slab--bg-gradient-grey  slab--has-ripple-top  align-full" id="fractal">
    <div class="slab__inner">
        <div class="wrap">

            <header class="tickertape">
                <h2 class="tickertape__highlight">
                    Fractal <small>(with Gulp/NPM)</small>
                </h2>
            </header>

            <p>The component library is managed using <a href="https://fractal.build">Fractal</a>, which has great documentation
                worth familiarising yourself with, it's already set up to run in the repo, you'll just need it installed on your
                system, see: <a href="https://fractal.build/guide/installation.html#installing-the-fractal-cli-tool">Installing the
                    Fractal CLI tool</a></p>

            <p>We'll run Fractal through <a href="https://gulpjs.com/docs/en/getting-started/quick-start">Gulp</a>,
                more on this later, but you'll need this on your system. At time of writing, Node v20 (NPM v10) is a prequisite.</p>

            <p>The <code>package.json</code> file in the root of the repository should list everything you need to run the project
                locally. Just run:</p>

            <pre>npm install</pre>

            <p>to grab the packages. To quickly check everything is working, you should now be able to run:</p>

            <pre>gulp</pre>

            <p>To get a viewable localhost version running on your system at this point. You can kill the process after you confirm it's
                working.</p>

            <p>Some of Fractal's settings can be found in <code>config.yml</code> in the root and some can be found in <code>gulpfile.babel.js</code>, references as to how to configure Fractal can be found in <a href="https://fractal.build/guide/project-settings.html">the docs</a>. Changing anything in this file will
                need a restart of Fractal to take effect. You likely won't need to change anything here.</p>
        </div>
    </div>
</section>

<section class="slab  slab--bg-gradient-grey  slab--has-ripple-top  align-full" id="file-structure">
    <div class="slab__inner">
        <div class="wrap">

            <header class="tickertape">
                <h2 class="tickertape__highlight">
                    File Structure
                </h2>
            </header>

            <p>The file structure for Fractal is set in <code>config.yml</code> for components, assets, docs and the build folder.</p>

            <p>The docs folder is unused, we have a folder in components (<code>src/components/01-globals-and-docs</code>) for these
                docs (yes, these ones you're reading now), as it's a bit easier to add fancier styles and examples here.</p>

            <h3 class="h4">The Build Folder</h3>
            <p>The <code>design-system</code> folder is the <strong>build folder</strong>. This contains <strong>generated code and
                    should not be edited</strong>. It will be overwritten when building a static version of the component library.
                More on this later.</p>

            <h3 class="h4">The Source Folder</h3>
            <p>This contains everything you'll edit. It runs the localhost version while you're building things, and is
                then compiled when <a href="https://fractal.build/guide/web/exporting-static-html.html#configuration">exporting a
                    static HTML version</a>.</p>

            <p>You might see this referred to as <code>/src/</code> as a placeholder later in these docs.</p>

            <div class="box  box--padded  size-line-length-max">
                <p>As this will be a <strong>Drupal</strong> project eventually, we've set this up at the likely Drupal theme path of <code>web/themes/custom/um-ssw</code>.
                    This will allow you to 'tightly integrate' components with Twig, including them directly from the components folder passing them data if
                    you'd like to only maintain them in one place. If you edit or extend components in this folder so that they can be included by a CMS,
                    you should <strong>make sure the components still work in Fractal's version of Twig</strong> (ie. Don't include any Drupal specific functions,
                    abstract these in a Drupal template and pass the raw data to the component).</p>
                <p>You can also move Fractal out of this location if you choose, just change the paths in <code>config.yml</code></p>
            </div>

            <h3 class="h4">Templating Note</h3>
            <p>You'll notice that all the template files use <a href="https://twig.symfony.com">Twig</a> as a <a href="https://fractal.build/guide/customisation/template-engines.html">templating language</a>. This means
                components can be built to be directly included in Drupal and WordPress (using <a href="https://github.com/timber/timber">Timber</a> or likewise).</p>
            <p>If you just want to use this as a reference library, <strong>Plain ol' HTML is valid Twig, and the compiled HTML can be viewed for all components from within Fractal in
                    the HTML tab along the bottom of the screen</strong>.</p>

            <h3 class="h4">Global Assets</h3>
            <p>Assets like fonts, images, js and styles (in <a href="https://sass-lang.com">Sass</a>) are stored in
                <code>assets</code>. Edit them here, they get copied to the build folder when building a static version of the
                component library.
            </p>

            <h3 class="h4">Components</h3>
            <p>Each component has a folder in <code>components</code>. This normally contains a <code>.twig</code> view
                template (for the HTML), some contain a config file to add context, dynamically created variants, control naming and
                ordering. Ideally all the styles and JS for a component will live here also. At the time of writing, all the
                components have their own <code>.scss</code> file for styles, but the JS is in one <code>app.js</code> file in
                <code>assets</code>.
            </p>
            <p>The JavaScript could probably use breaking up and bundling better. Ideally it'd be nice to do a similar thing with JS
                for each component as we do for Sass styles, so:</p>

            <pre>
├── components
│   └── slider
│   │   ├── slider.twig
│   │   ├── slider--variant.twig
│   │   ├── slider.config.yml
│   │   ├── _sliders.scss
│   │   └── _sliders.js
</pre>

            <p><strong>Useful:</strong> <a href="https://fractal.build/guide/components/">Fractal Docs on Components</a></p>

        </div>
    </div>
</section>

<section class="slab  slab--bg-gradient-grey  slab--has-ripple-top  align-full" id="build-process">
    <div class="slab__inner">
        <div class="wrap">

            <header class="tickertape">
                <h2 class="tickertape__highlight">
                    Build process / Code compilation (Gulp)
                </h2>
            </header>

            <p class="intro">The build process has been set up using <a href="https://gulpjs.com/docs/en/getting-started/quick-start">Gulp</a> for simplicity, cross-platform
                compatibility, and extensibility. It probably has some room for improvement, but it 'just works' for now 😬. If
                improved, remember to update these docs.</p>

            <p>If you've never used Gulp on your system, <a href="https://gulpjs.com/docs/en/getting-started/quick-start/#install-the-gulp-command-line-utility">install the CLI</a> with:</p>

            <pre>npm install --global gulp-cli</pre>

            <p>Our goal for a build process, among other things is:</p>
            <ul>
                <li>Sass to CSS compilation</li>
                <li>Sass syntax checking</li>
                <li>Compact output style, works best for git diffs, but compressed (minified) is an option</li>
                <li>Source maps</li>
                <li>PostCSS/Autoprefixer</li>
                <li>Theme image optimisation (for SVG, JPEG, PNG, etc.)</li>
                <li>JavaScript transpilation (Babel)</li>
                <li>ESLint syntax checking</li>
                <li>JS minification if not taken care of by the CMS</li>
                <li>JS source maps</li>
            </ul>

            <p>There is a gulpfile in the root where a basic command-line build process for Sass/JS has been set up.</p>

            <p>The build process watches Sass/JS and compiles on the fly, and also runs the equivelant of <code>fractal start</code>
                to running a localhost with BrowserSync. This is the default gulp task, so you just need to run:</p>

            <pre>gulp</pre>

            <p>A <code>gulp build</code> task has been set up, which currently just runs <code>fractal build</code>, but could be extended.</p>
            <p>There's also a <code>gulp compile</code> task which runs a one-time compile of styles and script without booting Fractal's webserver.
                This is handy for really quick edits, but ideally, check your components within Fractal!</p>
            <p>There's also potential for a <code>gulp deploy</code> task, which in future could be modified to generate minified assets if needed for the target environment.</p>

            <h3 class="h4">Sass (to CSS)</h3>

            <p>Global styles are located in <code>[src]/assets/styles/</code>.</p>

            <p>The entry point / manifest for generation of the main CSS is in <code>[src]/assets/styles/main.scss</code></p>

            <ul>
                <li><code>__vars</code> is used for variables/settings, nothing in this folder outputs code, it's just variables and
                    mixins to be called from other places. <strong>Change things here, and they'll likely cascade across the site
                        (and any subthemes).</strong></li>
                <li><code>_global</code> contains global, non-componentized styles required for everything, like base typography,
                    and some layout code.
                </li>
                <li><code>_grid</code> contains the code that actually outputs the grid system, it doesn't need to be edited unless
                    you want to for example, significantly rename classes. You can
                    <em>extend</em> the grid system by editing its settings <code>_grid.scss</code> <strong> in
                        <code>__vars</code></strong>. (See the Docs on Grid)
                </li>
                <li><code>_utils</code> contains code which outputs some useful utility classes (mostly to be used sparingly, think a slightly less horrible CSS !important but for HTML)</li>
                <li><code>_vendor</code> is a place to add third-party styles if they can't be enqueued in another way. We mostly
                    just use this to include <a href="https://necolas.github.io/normalize.css/">Normalize</a>.
                </li>
            </ul>

            <p><strong>Component styles</strong> are separated out into their component folders, and are included by main.scss. It
                'reaches out' of the assets folder and into each component, for example:</p>

            <pre>
@import "__vars/_all";
@import "../../components/card/cards";
</pre>

            <p><strong>NB: We do not (currently) use Sass 'globbing' to include all files (such as components) - eg. <code>@import
                        "../../components/*/*";</code></strong>. Partially as some Sass compilers don't support it for 'reasons',
                and partially to control the ordering of what gets imported (one of the 'reasons' some Sass compilers opt not to
                support globbing). Thus, with the current build process, when you add a partial, you'll need to <strong>manually
                    (purposefully) add it to <code>main.scss</code> (and any other subthemes created)</strong>. More on this in the
                guide below.</p>

            <h3 class="h4">JavaScript</h3>

            <p>Our first rule is to use sparingly. If a JavaScript-free solution is available (like <a href="https://developer.mozilla.org/en/docs/Web/HTML/Element/details">&lt;details&gt;</a>),
                prefer it!</p>
            <p>That said, it's mad to think we can eliminate JavaScript completely.</p>
            <p>JavaScript lives in <code>[src]/assets/js</code> and is processed by gulp.</p>
            <p>The entry point is <code>app.js</code>, which could use <a href="https://www.npmjs.com/package/gulp-include">gulp-include</a> syntax to bring in third-party
                libraries we might want to keep in <code>[src]/assets/js/vendor/</code>. Using "proper" best practice package management for this would be a great idea.
            </p>
            <p>It ain't perfect, but it Works For Now&trade;.</p>

            <p>The result of <code>gulp default</code> is output at <code>src/assets/dev/js</code>, which is referenced in Fractal's localhost, and copied to the build folder when building.</p>
            <p>There's a <code>src/assets/dist</code> folder which would be used by <code>gulp deploy</code> to create minified assets, but this is currently not in use. If the target CMS environment doesn't
                support concatenation and minification of CSS/JS, this is worth looking into for performance.</p>

        </div>
    </div>
</section>

<section class="slab  slab--bg-gradient-grey  slab--has-ripple-top  align-full" id="adding-a-new-component">
    <div class="slab__inner">
        <div class="wrap">

            <header class="tickertape">
                <h2 class="tickertape__highlight">
                    Guide: Adding a new component
                </h2>
            </header>

            <ol>
                <li>From command line, run
                    <pre>gulp</pre>
                    from the root of the project, this should start Fractal, Sass/JS filewatching, and open your browser to the localhost.
                </li>
                <li>Create a folder for the component in <code>[src]/components/</code>, eg.
                    <code>[src]/components/your-component/</code>
                </li>
                <li>Create a <code>.twig</code> template file (for the HTML) inside the folder, .eg <code>[src]/components/your-component/your-component.twig</code>
                    - as soon as you do this, Fractal should refresh and the component should appear in the components list on the
                    left
                </li>
                <li>Create a <code>.scss</code> 'partial' file prefixed with an underscore (this lets the compiler know not to
                    directly compile the file, because it is included by another file), eg. <code>[src]/components/your-component/_your-component.scss</code>
                </li>
                <li>Reference the partial <code>.scss</code> in <code>[src]/assets/styles/main.scss</code>*, so that it's brought into
                    the site CSS, by adding a line like so:
                    <pre>@import "../../components/your-component/your-component";</pre>
                    For now, this will be compiled to <code>[src]/assets/styles/main.css</code>, which is referenced in Fractal.
                </li>
                <li>Write the HTML and Sass for your component</li>
                <li>When you're done, <a href="https://fractal.build/guide/web/exporting-static-html.html#configuration">run a build to a static HTML version</a> by running
                    <pre>gulp build</pre>
                    from the command line. This will compile .twig to static HTML, and copy all (already compilied on-the-fly) assets (fonts/img/css/js) to the <code>design-system</code>
                    folder, so the component library can be viewed without having to run a localhost version
                </li>
                <li>Add the new/modified files to your chosen flavour of source control</li>
                <li>Repeat!</li>
            </ol>

            <p><sup>* this will add the component to the main site styles, to include in sub-themes, add to their Sass file too, eg.
                    <code>main-subtheme.scss</code></sup></p>
        </div>
    </div>
</section>