@tacc/core-styles 0.9.0 → 0.11.0

package/src/lib/_imports/README.md

@@ -5,10 +5,8 @@ Styles here should be isolated UI patterns and be imported by other stylesheets.
 ## Rules
 
 1. Files **must** be [organized appropriately](#directory-organization).
-1. Files **must** be [documented appropriately](#documentation-format).
-1. Files **must** follow the [style guide][tacc-style-guide].
-
-- Styles **should** be for [structure](#structure-vs-skin) and **may** be for [skin](#structure-vs-skin).
+2. Files **must** be [documented appropriately](#documentation-format).
+3. Files **must** follow the [style guide][tacc-style-guide].
 
 ## Directory Organization
 
@@ -18,30 +16,25 @@ These directories are based on [ITCSS][tacc-itcss].
 
 ## Documentation Format
 
-```css
-/*
-Styles Name
-
-Description of the purpose and use case of styles. Use the `Markup:` property to link to sample markup. The documentation format is [KSS Node](https://github.com/kss-node/kss-node/blob/master/README.md).
-
-Markup: x-stylesheet-name.html
+See [Fractal: User Guide: Components][fractal-docs-guide]. (What we call "Patterns", Fractal calls "Components".)
 
-Styleguide __StylesSection__.__StylesName__
-*/
+### Overview
 
-.some-selector {
-  text-transform: none;
-}
-```
+1. The `./*/README.md` files describe the type of patterns in its folders.
+2. Underscore-prefixed files and folders are documentation templates.
+3. Nested folders named after patterns have their docs, templates, and config.
+4. Old-style pattern docs are `/* ... Styleguide ... */` and `.html` files.
 
 ## Style Guide
 
 See [TACC: CSS Style Guide][tacc-style-guide].
 
-## Structure vs. Skin
+### Object-Oriented Styles
 
-- Most Core styles will be _only **or** mostly_ for [structure][tacc-oocss].
-- Some core styles may be [skin][tacc-oocss].
+- Pattern developers should understand [container vs. content][tacc-oocss].
+- Most styles will be _only **or** mostly_ for [structure][tacc-oocss].
+- Some styles may be for [skin][tacc-oocss].
 
 [tacc-oocss]: https://confluence.tacc.utexas.edu/x/VwALBg 'TACC: Object-Oriented CSS'
 [tacc-style-guide]: https://confluence.tacc.utexas.edu/x/ZQALBg 'TACC: CSS Style Guide'
+[fractal-docs-guide]: https://fractal.build/guide/components/#what-defines-a-component 'Fractal: User Guide: Components'

package/src/lib/_imports/_partials/bootstrap.css.hbs

@@ -0,0 +1 @@
+<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">

package/src/lib/_imports/_partials/bootstrap.js.hbs

@@ -0,0 +1,2 @@
+<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
+<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js" integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous"></script>

package/src/lib/_imports/_partials/cms.css.hbs

@@ -0,0 +1,3 @@
+{{!-- To render atop styles dependent on CMS e.g. `rem` font size --}}
+{{!-- SEE: src/lib/_imports/assets/elements/html-elements.cms.css --}}
+<link rel='stylesheet' href='{{path "/assets/elements/html-elements.cms.css"}}' />

package/src/lib/_imports/_partials/css.hbs

@@ -0,0 +1,27 @@
+{{!-- To render library basics consistently regardless of external styles --}}
+{{!-- FAQ: overwrite CMS and/or Bootstrap (if present) --}}
+<style>
+  dl dl {
+    margin-block: 0;
+  }
+  dt, dd {
+    font-family: Arial, sans;
+    color: #484848;
+    line-height: normal;
+  }
+  dt {
+    font-weight: normal;
+    margin-bottom: 10px;
+  }
+  dt:not(:first-of-type) {
+    margin-top: 20px;
+  }
+  dd {
+    margin-bottom: 10px;
+    margin-left: 25px;
+  }
+  dd > * {
+    margin-right: 5px;
+    vertical-align: middle;
+  }
+</style>

package/src/lib/_imports/_partials/loremipsum.hbs

@@ -0,0 +1,18 @@
+<p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
+<p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
+<p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
+<p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
+<p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
+<p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
+<p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
+<p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
+<p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
+<p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
+<p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
+<p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
+<p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
+<p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
+<p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
+<p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
+<p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
+<p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>

package/src/lib/_imports/_partials/text-and-button-as-link.hbs

@@ -0,0 +1 @@
+<p>Pack my red box with five dozen quality jugs. A quick brown fox jumps over the <button class="c-button c-button--as-link">lazy dog</button>. A waxy gent chuckled over my fab jazzy quips.</p>

package/src/lib/_imports/_partials/text-and-link.hbs

@@ -0,0 +1 @@
+<p>Pack my red box with five dozen quality jugs. A quick brown fox jumps over the <a href="#">lazy dog</a>. A waxy gent chuckled over my fab jazzy quips.</p>

package/src/lib/_imports/_partials/text-of-one-paragraph.hbs

@@ -0,0 +1 @@
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

package/src/lib/_imports/_preview.bootstrap-cms.hbs

@@ -0,0 +1,5 @@
+{{> @bootstrap.css }}
+
+{{> @preview.cms subdir=_target.context.subdir }}
+
+{{> @bootstrap.js }}

package/src/lib/_imports/_preview.bootstrap.hbs

@@ -0,0 +1,5 @@
+{{> @bootstrap.css }}
+
+{{> @preview subdir=_target.context.subdir }}
+
+{{> @bootstrap.js }}

package/src/lib/_imports/_preview.cms.hbs

@@ -0,0 +1,3 @@
+{{> @cms.css }}
+
+{{> @preview subdir=_target.context.subdir }}

package/src/lib/_imports/_preview.hbs

@@ -1,13 +1,22 @@
-{{! styles: base (the current component) }}
+{{! To ensure HTML comments that follow are within the head, not before it }}
+{{! FAQ: Any <link>s, and comments AFTER the first, are migrated to <head> }}
+<link rel='author' href='https://github.com/TACC/Core-Styles' />
+
+<!-- styles: support (the current component) -->
+{{#each _target.context.supportStyles}}
+  <link rel='stylesheet' href='{{path this}}' />
+{{/each}}
+<!-- styles: base (the current component) -->
 {{#unless styles.shouldSkipBase}}
   <link
     rel='stylesheet'
-    href='{{path "/{{ subdir }}/{{ _target.baseHandle }}.css"}}'
+    href='{{path "/assets/{{ _target.context.subdir }}/{{ _target.baseHandle }}.css"}}'
   />
 {{/unless}}
 
-{{! styles: global (for every component) }}
-{{! (manually configured) }}
+
+<!-- styles: global (for every component) -->
+<!-- (manually configured) -->
 {{#each styles.external.global}}
   <link rel='stylesheet' href='{{this}}' />
 {{/each}}
@@ -15,8 +24,8 @@
   <link rel='stylesheet' href='{{path this}}' />
 {{/each}}
 
-{{! styles: local (for current component) }}
-{{! (automatically found) }}
+<!-- styles: local (for current component) -->
+<!-- (automatically found) -->
 {{#each _target.resources.assets}}
   {{#if isCSS}}
     <link
@@ -25,7 +34,7 @@
     />
   {{/if}}
 {{/each}}
-{{! (manually configured) }}
+<!-- (manually configured) -->
 {{#each styles.external.local}}
   <link rel='stylesheet' href='{{this}}' />
 {{/each}}
@@ -33,8 +42,11 @@
   <link rel='stylesheet' href='{{path this}}' />
 {{/each}}
 
-{{! scripts: local (for current component) }}
-{{! (automatically found) }}
+{{! styles: specific to pattern library (so pattern library can override any) }}
+{{> @css }}
+
+<!-- scripts: local (for current component) -->
+<!-- (automatically found) -->
 {{#each _target.resources.assets}}
   {{#if isJS}}
     <script
@@ -43,5 +55,5 @@
   {{/if}}
 {{/each}}
 
-{{! markup }}
+<!-- markup (for current component) -->
 {{{yield}}}

package/src/lib/_imports/components/_components.config.yml

@@ -1 +1,2 @@
-preview: "@components.preview"
+context:
+  subdir: "components"

package/src/lib/_imports/components/bootstrap/bootstrap--container.hbs

@@ -0,0 +1,4 @@
+<div class="container">
+  <h1>Lorem Ipsum</h1>
+  {{> @loremipsum }}
+</div>

package/src/lib/_imports/components/bootstrap/bootstrap--container.readme.md

@@ -0,0 +1,54 @@
+To add wider [Bootstrap Grid](https://getbootstrap.com/docs/4.0/layout/grid/) containers.
+
+> **⚠️ Important**
+>
+> Because Bootstrap grid is so complex, only essential changes are recommended.
+
+> **ⓘ Notice**
+>
+> Bootstrap grid is powerful, popular, and present; so we do use it as our grid.
+
+<table style="caption-side: bottom;">
+  <caption>
+
+  The columns are added using TACC's `xx-wide` and `xxx-wide` custom properties and media queries.
+
+  <caption>
+  <thead>
+    <tr>
+      <th></th>
+      <th>Extra extra large <br>
+        <small>≥1680px</small>
+      </th>
+      <th>Extra extra extra large <br>
+        <small>≥1920px</small>
+      </th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Max container width</td>
+      <td>1580px</td>
+      <td>1800px</td>
+    </tr>
+    <tr>
+      <td># of columns</td>
+      <td colspan="2">12</td>
+    </tr>
+    <tr>
+      <td>Gutter width</td>
+      <td colspan="2">30px (15px on each side of a column)</td>
+    </tr>
+    <tr>
+      <td>Nestable</td>
+      <td colspan="2">Yes</td>
+    </tr>
+  </tbody>
+</table>
+
+<script>
+/* To open external links in new window */
+Array.from(document.links)
+  .filter(link => link.hostname != window.location.hostname)
+  .forEach(link => link.target = '_blank');
+</script>

package/src/lib/_imports/components/bootstrap/bootstrap--form.docs.css

@@ -0,0 +1,5 @@
+/* This CSS is ONLY for the pattern library. It is NOT part of the pattern. */
+
+form {
+    margin: 1em;
+}

package/src/lib/_imports/components/bootstrap/bootstrap--form.hbs

@@ -0,0 +1,17 @@
+<form>
+  <label for="field-name">Name</label>
+  <input type="text" class="form-control" id="field-name" name="name" placeholder="Jane Doe">
+  <br />
+  <label for="field-username">Username</label>
+  <div class="input-group">
+    <div class="input-group-prepend">
+      <div class="input-group-text">@</div>
+    </div>
+    <input type="text" class="form-control" id="field-username" name="username" placeholder="Username">
+  </div>
+  <br />
+  <label for="field-intro">Tell us about yourself</label>
+  <textarea class="form-control" id="field-intro" name="intro" rows="3"></textarea>
+  <br />
+  <button type="submit" class="c-button c-button--primary">Submit</button>
+</form>

package/src/lib/_imports/components/bootstrap/bootstrap--form.readme.md

@@ -0,0 +1,17 @@
+To override and extend [Bootstrap Forms](https://getbootstrap.com/docs/4.3/components/forms/).
+
+> **⚠️ WARNING**
+>
+> Core Styles are negligible, because this is used **only on Portal** to extend **its** overrides of Bootstrap.
+
+> **→ TO DO**
+>
+> - [ ] **Either** migrate Portal Bootstrap form styling to this component.
+> - [ ] **Or** return these styles to Portal (and remove form Core Styles).
+
+<script>
+/* To open external links in new window */
+Array.from(document.links)
+  .filter(link => link.hostname != window.location.hostname)
+  .forEach(link => link.target = '_blank');
+</script>

package/src/lib/_imports/components/bootstrap/bootstrap--modal.docs.css

@@ -0,0 +1,12 @@
+/* This CSS is ONLY for the pattern library. It is NOT part of the pattern. */
+
+#exampleModalStatic {
+    position: relative;
+    top: auto;
+    right: auto;
+    bottom: auto;
+    left: auto;
+    z-index: 1;
+    display: block;
+    height: auto;
+}

package/src/lib/_imports/components/bootstrap/bootstrap--modal.hbs

@@ -0,0 +1,51 @@
+<dl>
+  <dt>Dynamic</dt>
+  <dd>
+    <button type="button" class="c-button c-button--secondary" data-toggle="modal" data-target="#exampleModalScrollable">
+      Launch modal
+    </button>
+    <div id="exampleModalScrollable" class="modal" tabindex="-1" role="dialog" aria-labelledby="exampleModalScrollableTitle">
+      <div class="modal-dialog modal-dialog-scrollable" role="document">
+        <div class="modal-content">
+          <div class="modal-header">
+            <h5 class="modal-title" id="exampleModalScrollableTitle">Modal title</h5>
+            <button type="button" class="close" data-dismiss="modal" aria-label="Close">
+              <span aria-hidden="true">&times;</span>
+            </button>
+          </div>
+          <div class="modal-body">
+            {{> @loremipsum }}
+          </div>
+          <div class="modal-footer">
+            <button type="button" class="c-button c-button--secondary" data-dismiss="modal">
+              Close
+            </button>
+            <button type="button" class="c-button c-button--primary">
+              Fake action
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  </dd>
+  <dt>Static</dt>
+  <dd>
+    <div id="exampleModalStatic" class="modal" tabindex="-1" role="dialog" aria-labelledby="exampleModalStaticTitle">
+      <div class="modal-dialog" role="document">
+        <div class="modal-content">
+          <div class="modal-header">
+            <h5 class="modal-title" id="exampleModalStaticTitle">Modal title</h5>
+          </div>
+          <div class="modal-body">
+            <p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
+          </div>
+          <div class="modal-footer">
+            <button type="button" class="c-button c-button--primary">
+              Fake action
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  </dd>
+</dl>

package/src/lib/_imports/components/bootstrap/bootstrap--modal.readme.md

@@ -0,0 +1,8 @@
+To override and extend [Bootstrap Modals](https://getbootstrap.com/docs/4.3/components/modal/).
+
+<script>
+/* To open external links in new window */
+Array.from(document.links)
+  .filter(link => link.hostname != window.location.hostname)
+  .forEach(link => link.target = '_blank');
+</script>

package/src/lib/_imports/components/bootstrap/bootstrap.hbs

@@ -0,0 +1,6 @@
+<dl>
+    <dt>TACC Usage</dt>
+    <dd>TACC Core minimizes its legacy dependency on Bootstrap.</dd>
+    <dt>More Information</dt>
+    <dd>See "Notes" tab.<dd>
+</dl>

package/src/lib/_imports/components/bootstrap/bootstrap.readme.md

@@ -0,0 +1,14 @@
+> **ⓘ Notice**
+>
+> [Despite high usage and awareness of Bootstrap, it has low and decreasing satisfaction and interest.](https://2021.stateofcss.com/en-US/technologies/css-frameworks) TACC Core use its components only when building our own would be more work than overwriting Bootstrap.
+
+> **ⓘ Notice**
+>
+> Overwriting Bootstrap is cumbersome and **not** the [appropriate way to theme Bootstrap](https://getbootstrap.com/docs/4.0/getting-started/theming/), but TACC Core is **not** using SASS; it uses PostCSS.
+
+<script>
+/* To open external links in new window */
+Array.from(document.links)
+  .filter(link => link.hostname != window.location.hostname)
+  .forEach(link => link.target = '_blank');
+</script>

package/src/lib/_imports/components/bootstrap/config.yml

@@ -0,0 +1,16 @@
+preview: '@preview.bootstrap'
+variants:
+  - name: default
+    hidden: true
+  - name: container
+    status: ready
+  - name: modal
+    context:
+      supportStyles:
+        - /assets/components/c-button.css
+  - name: form
+    label: (Portal) Form
+    status: prototype
+    context:
+      supportStyles:
+        - /assets/components/c-button.css

package/src/lib/_imports/components/bootstrap/docs.css

@@ -0,0 +1,7 @@
+/* This CSS is ONLY for the pattern library. It is NOT part of the pattern. */
+
+/* All Bootstrap pattern library CSS loads for every component */
+/* FAQ: To support legacy client imports, Bootstrap file organization is odd */
+
+@import url("./bootstrap--form.docs.css");
+@import url("./bootstrap--modal.docs.css");

package/src/lib/_imports/components/bootstrap.container.css

@@ -1,18 +1,10 @@
-/*
-Container (Bootstrap)
-
-Add to Bootstrap styles. See:
-
-- [Bootstrap Grid](https://getbootstrap.com/docs/4.0/layout/grid/)
-
-Styleguide Components.Bootstrap.Grid
-*/
+@import url("../settings/max-width.css");
 @import url("../tools/media-queries.css");
 
-@media (--x-wide-and-above) {
+@media (--xx-wide-and-above) {
   .container { max-width: var(--global-max-width--x-wide); }
 }
-@media (--xx-wide-and-above) {
+@media (--xxx-wide-and-above) {
   .container { max-width: var(--global-max-width--xx-wide); }
 }
 /* FAQ: We can do this, but Design does not want to stretch this wide */

package/src/lib/_imports/components/bootstrap.css

@@ -0,0 +1,3 @@
+/* EMPTY ON PURPOSE! */
+/* FAQ: Created to avoid 404 in pattern library. */
+/* WARNING: This file should never have styles. */

package/src/lib/_imports/components/bootstrap.form.css

@@ -1,10 +1,3 @@
-/*
-Form (Bootstrap)
-Override Bootstrap styles. See:
-- [ReactStrap Forms](https://reactstrap.github.io/components/form/)
-- [Bootstrap Forms](https://getbootstrap.com/docs/4.4/components/forms/)
-Styleguide Components.Bootstrap.Form
-*/
 @import url('../settings/border.css');
 
 .form-control {

package/src/lib/_imports/components/bootstrap.modal.css

@@ -1,15 +1,3 @@
-/* TODO: Migrate any other should-be-global Portal modal styles to here */
-/* FP-344: Consider a Modal component and a CSS module */
-/*
-Modal (Bootstrap)
-
-Override Bootstrap styles. See:
-
-- [ReactStrap Forms](https://reactstrap.github.io/components/modals/)
-- [Bootstrap Forms](https://getbootstrap.com/docs/4.4/components/modal/)
-
-Styleguide Components.Bootstrap.Modal
-*/
 @import url('../tools/x-truncate.css');
 
 .modal-content,