TACC Core Styles

The shared styles for TACC WMA Workspace Portals & Websites

Known Clients

• Core CMS, the base CMS code for TACC WMA CMS Websites
• Core Portal, the base Portal code for TACC WMA CMS Websites
• TUP UI, the client code for TACC User Portal
• TACC Docs, the documentation for TACC
  • and, indirectly, DesignSafe User Guide
• Tapis Authenticator, the web server for Tapis v3 auth
• Hazmapper, a TACC application for geospatial data
• DesignSafe Portal, the DesignSafe-CI Portal code

Table of Contents

• External Project Usage
  • A. Load from a Project
  • B. Install into a Project
• Local Development Setup
• Testing
• Deployment
• Contributing
• Bootstrap

External Project Usage

A. Load from a Project

[!NOTE] This is likely the easier and simpler solution. Try this first.

See QUICKSTART.md.

B. Install into a Project

Install This Package

1. Install with any package manager e.g.:

   • npm install @tacc/core-styles
   • yarn add @tacc/core-styles

2. Import stylesheets of either type:

   • pre-compiled, from /dist
   • source files, from /src/lib/_imports

Build from Source

Via Your Environment's PostCSS

Please review the plugins expected.

Via Core-Styles API

JavaScript

const buildStylesheets = require('core-styles').buildStylesheets;

buildStylesheets(
  // Parse CSS files from which directory (required)
  `path/to/your/css/src`,
  // Output CSS files to which directory (required)
  `path/to/put/css/output`,
  {
    // List of YAML config files (optional)
    // (The first file is merged on top of the base config.)
    // (Each successive file overwrites the file before it.)
    // SEE: https://github.com/postcss/postcss-load-config#postcssrc
    customConfigs: [
      // The "base" config is `/.postcssrc.base.yml`
      `path/to/custom/config/that/extends/base/.postcssrc.yml`,
      `path/to/custom/config/that/extends/above/.postcssrc.yml`,
    ],
    // Print more info from build log (optional, default: false)
    verbose: true,
    // Print version of this software (optional, default: false)
    version: true,
    // Any value to help identify the build (optional, default: app version)
    buildId: process.env.npm_package_version + someUniqueId,
  }
);

CLI

Usage: core-styles [options] [command]

Options:
  -V, --version      output the version number
  -h, --help         display help for command

Commands:
  build [options]    build stylesheets with TACC standard process:
  - "post-css" plugins
  - custom input path
  - custom output path
  - custom configs
  - prepend build id

  help [command]     display help for command

Usage: core-styles build [options]

build stylesheets with TACC standard process:
- "post-css" plugins
- custom input path
- custom output path
- custom configs
- prepend build id

Options:
  -i, --input <path>               parse source at which path¹
  -o, --output <path>              output CSS files to which path¹
  -v, --verbose                    print more info during build process
  -c, --custom-configs <paths...>  extend base config with YAML files²³
  -b, --build-id <identifier>      any value to identify the build (default: version of app)
  -m, --base-mirror-dir <path>     if input folder structure is mirrored, this path is not⁴
  -h, --help                       display help for command

Notes:
  ¹ Folder structure of "--input-dir" mirrored in "--output-dir" i.e.

    given input
    - "input_dir/x.css"
    - "input_dir/sub_dir_a/y.css"
    - "input_dir"
    - "input_dir/**/*"

    expect output
    - "output_dir/x.css"
    - "output_dir/sub_dir_a/y.css"
    - "output_dir/..." (all files from input not in sub-directories)
    - "output_dir/.../..." (all files from input as nested)

  ² The file formats are like ".postcssrc.yml" from
    https://github.com/postcss/postcss-load-config#postcssrc

  ³ The first file is merged on top of the base config.
    Each successive file overwrites the file before it.

  ⁴ Given '-i "a/b*" -o "x/" -m "a/"' output is "x/b/...".
    Given '-i "a/b*" -o "x/" -m "a/b/"' output is "x/...".
    Given '-i "a/b*" -o "x/" -m "not-a/"' output is "x/abs-path-to-input/...".

Local Development Setup

Prerequisites for Running

• Nodejs 15.x

Quick Start

0. (initially) Install dependencies:
   npm ci

1. (optional) Make changes to /src/lib files.

2. Build the styles*:
   npm run build:css

3. Build and preview the styles*:
   npm start

4. (to debug) Review output in respective /dist or /demo files.*

* Stylesheets are built from source files in src/lib directory to compiled files in dist directory.

Preview After Development

1. Build stylesheets and build static demo:

   npm run build

2. Run the static demo:

   npx serve demo

   Web page will live-reload on demo build, but not on change of source files.

3. Open the web interface. The build command will output the URL (and may even open it for you).

Preview During Development

Run each of these commands in its own terminal.

1. Build stylesheets and re-build on change:

   npm run watch

2. Run the auto-refresh demo:

   npm run start

Web page will live-reload twice on change of source files. The second reload will show changes.

Build Options

Regular CSS Build

npm run build:css

Custom Build ID

npm run build:css -- --build-id="..."

Testing

All testing is done manually.

Deployment

Production Deployment

The Core Styles are not independently deployed.

Currently, the demo is served by Core CMS (since v3.9.0).

Later, the demo may be deployed indpendently and core-styles.….css served from a CDN.

Contributing

To contribute, first read How to Contirbute.

Bootstrap

Core Styles was an effort to replace Bootstrap. Core Styles is compatible with Bootstrap. Learn more.