Add utilities documentation

This commit is contained in:
Jeremy Thomas
2021-09-19 23:36:15 +01:00
parent e145c9d680
commit f6c0cfc813
19 changed files with 1227 additions and 444 deletions

View File

@@ -44,7 +44,7 @@ $fullhd-enabled: false
{% assign mixins_file_url = "/blob/master/sass/utilities/mixins.sass#L81,L129" | prepend: site.data.meta.github %}
<div class="content">
<p>Bulma has <a href="{{ variables_file_url }}" target="_blank">5 breakpoints</a>:</p>
<p>Bulma has <a href="{{ variables_file_url }}" target="_blank">4 breakpoints</a> which defines <strong>5 screen sizes</strong>:</p>
<ul>
{% for breakpoint_hash in site.data.breakpoints %}
{% assign breakpoint = breakpoint_hash[1] %}
@@ -52,160 +52,17 @@ $fullhd-enabled: false
{% endfor %}
</ul>
<p>Bulma uses <a href="{{ mixins_file_url }}" target="_blank">9 responsive mixins</a>:</p>
<ul>
{% for breakpoint_hash in site.data.breakpoints %}
{% assign breakpoint = breakpoint_hash[1] %}
{% case breakpoint.id %}
{% when 'mobile' %}
<li>
<code>={{ breakpoint.id }}</code><br>
until <code>{{ breakpoint.to }}px</code>
</li>
{% when 'fullhd' %}
<li>
<code>={{ breakpoint.id }}</code><br>
from <code>{{ breakpoint.from }}px</code>
</li>
{% else %}
<li>
<code>={{ breakpoint.id }}</code><br>
from <code>{{ breakpoint.from }}px</code>
</li>
<li>
<code>={{ breakpoint.id }}-only</code><br>
from <code>{{ breakpoint.from }}px</code> and until <code>{{ breakpoint.to }}px</code>
</li>
{% if breakpoint.id == 'tablet' %}
<li>
<code>=touch</code><br>
until <code>{{ breakpoint.to }}px</code>
</li>
{% endif %}
{% endcase %}
{% endfor %}
</ul>
<p>To make use of these breakpoints, Bulma provides <a href="{{ site.url }}/documentation/utilities/responsive-mixins/">9 responsive mixins</a>.</p>
</div>
<div class="table-container">
<table class="table is-bordered">
<thead>
<tr>
{% for breakpoint_hash in site.data.breakpoints %}
{% assign breakpoint = breakpoint_hash[1] %}
<th style="width: 20%;">
{{ breakpoint.name }}<br>
{% if breakpoint.id == 'mobile' %}
Up to <code>{{ breakpoint.to }}px</code>
{% elsif breakpoint.id == 'fullhd' %}
<code>{{ breakpoint.from }}px</code> and above
{% else %}
Between <code>{{ breakpoint.from }}px</code> and <code>{{ breakpoint.to }}px</code>
{% endif %}
</th>
{% endfor %}
</tr>
</thead>
<tbody>
<tr>
<td>
<p class="notification is-success">mobile</p>
</td>
<td colspan="4">
<p class="notification">-</p>
</td>
</tr>
<tr>
<td>
<p class="notification">-</p>
</td>
<td colspan="4">
<p class="notification is-success">tablet</p>
</td>
</tr>
<tr>
<td colspan="2">
<p class="notification">-</p>
</td>
<td colspan="3">
<p class="notification is-success">desktop</p>
</td>
</tr>
<tr>
<td colspan="3">
<p class="notification">-</p>
</td>
<td colspan="2">
<p class="notification is-success">widescreen</p>
</td>
</tr>
<tr>
<td colspan="4">
<p class="notification">-</p>
</td>
<td>
<p class="notification is-success">fullhd</p>
</td>
</tr>
<tr>
<td>
<p class="notification">-</p>
</td>
<td>
<p class="notification is-success">tablet-only</p>
</td>
<td colspan="3">
<p class="notification">-</p>
</td>
</tr>
<tr>
<td colspan="2">
<p class="notification">-</p>
</td>
<td>
<p class="notification is-success">desktop-only</p>
</td>
<td colspan="2">
<p class="notification">-</p>
</td>
</tr>
<tr>
<td colspan="3">
<p class="notification">-</p>
</td>
<td>
<p class="notification is-success">widescreen-only</p>
</td>
<td>
<p class="notification">-</p>
</td>
</tr>
<tr>
<td colspan="2">
<p class="notification is-success">touch</p>
</td>
<td colspan="3">
<p class="notification">-</p>
</td>
</tr>
<tr>
<td colspan="3">
<p class="notification is-success">until-widescreen</p>
</td>
<td colspan="2">
<p class="notification">-</p>
</td>
</tr>
<tr>
<td colspan="4">
<p class="notification is-success">until-fullhd</p>
</td>
<td colspan="1">
<p class="notification">-</p>
</td>
</tr>
</tbody>
</table>
{% include components/breakpoints-table.html %}
{% assign urm_link = site.data.links.by_id['utilities-responsive-mixins'] %}
<div class="content">
<p>
To simplify using these breakpoints, Bulma provides <a href="{{ site.url }}{{ urm_link.path }}">easy-to-use responsive mixins</a>.
</p>
</div>
{% assign vernum = site.data.meta.version | downcase | remove: "." | plus: 0 %}

View File

@@ -0,0 +1,13 @@
---
title: Utilities
layout: documentation
doc-tab: utilities
hide_tabs: true
hide_pagination: true
breadcrumb:
- home
- documentation
- utilities
---
{% include components/links.html category_id='utilities' %}

View File

@@ -1,68 +1,130 @@
---
title: Mixins
title: Form Control Mixins
layout: documentation
doc-tab: overview
doc-subtab: mixins
doc-tab: utilities
doc-subtab: control-mixins
breadcrumb:
- home
- documentation
- overview
- overview-mixins
- utilities
- utilities-control-mixins
---
<div class="table-container">
<table class="table is-bordered">
<tr>
<td><code>=arrow($color)</code></td>
<td>Creates a CSS-only down arrow. Used for the dropdown select.</td>
</tr>
<tr>
<td><code>=block</code></td>
<td>Defines a margin-bottom of 1.5rem, except when the element is the last child. Used for almost all block elements.</td>
</tr>
<tr>
<td><code>=clearfix</code></td>
<td>Adds a clearfix at the end of the element. Used for the "is-clearfix" helper.</td>
</tr>
<tr>
<td><code>=center($size)</code></td>
<td>Positions an element in the exact center of its parent. Used for the spinner in a loading button.</td>
</tr>
<tr>
<td><code>=delete</code></td>
<td>Creates a CSS-only cross. Used for the delete element in modals, messages, tags...</td>
</tr>
<tr>
<td><code>=fa($size, $dimensions)</code></td>
<td>Sets the style of a Font Awesome icon container.</td>
</tr>
<tr>
<td><code>=hamburger($dimensions)</code></td>
<td>Creates a CSS-only hamburger menu with 3 bars. Used for the "nav-toggle".</td>
</tr>
<tr>
<td><code>=loader</code></td>
<td>Creates a CSS-only loading spinner. Used for the ".loader" element, and for input and button spinners.</td>
</tr>
<tr>
<td><code>=overflow-touch</code></td>
<td>Sets the style of a container so that it keeps momentum when scrolling on iOS devices.</td>
</tr>
<tr>
<td><code>=overlay($offset: 0)</code></td>
<td>Makes the element overlay its parent container, like the transparent modal background.</td>
</tr>
<tr>
<td><code>=placeholder</code></td>
<td>Sets the styles of an input placeholder.</td>
</tr>
<tr>
<td><code>=unselectable</code></td>
<td>Turns the element unselectable. Used for buttons to prevent selection when clicking.</td>
</tr>
</table>
<div class="content">
<p>
In Bulma, the <strong>form controls</strong> are an essential part of the framework. They comprise the following elements:
</p>
<ul>
<li>
<code>.button</code>
</li>
<li>
<code>.input</code>
</li>
<li>
<code>.select</code>
</li>
<li>
<code>.file-cta</code>
<code>.file-name</code>
</li>
<li>
<code>.pagination-previous</code>
<code>.pagination-next</code>
<code>.pagination-link</code>
<code>.pagination-ellipsis</code>
</li>
</ul>
<p>
The <code>control()</code> mixin ensures <strong>consistency</strong> by providing a set of styles that are shared between all these form controls. You can use it to create additional controls:
</p>
</div>
{% highlight sass %}.bulma-control-mixin {
@include control;
background: deeppink;
color: white;
}{% endhighlight %}
{% capture control-mixin %}
<button class="bulma-control-mixin">
My control
</button>
{% endcapture %}
{% include elements/snippet.html content=control-mixin %}
{% include elements/anchor.html name="Sizes" %}
<div class="content">
<p>These mixins are already used throughout Bulma, but you can use them as well to extend your own styles.</p>
<p>
Controls have a default font size of <code>$size-normal</code> also come in <strong>3 additional sizes</strong>, which can be accessed via 3 additional mixins:
</p>
<ul>
<li>
{% include elements/snippet-inline.html content="@include control-small;" %} with a font size <code>$size-small</code>
</li>
<li>
{% include elements/snippet-inline.html content="@include control-medium;" %} with a font size <code>$size-medium</code>
</li>
<li>
{% include elements/snippet-inline.html content="@include control-large;" %} with a font size <code>$size-large</code>
</li>
</ul>
</div>
{% highlight sass %}.bulma-control-mixin {
&.is-small {
@include control-small;
}
&.is-medium {
@include control-medium;
}
&.is-large {
@include control-large;
}
}{% endhighlight %}
{% capture control-mixin-sizes %}
<button class="bulma-control-mixin is-small">
Small
</button>
<button class="bulma-control-mixin">
Normal
</button>
<button class="bulma-control-mixin is-medium">
Medium
</button>
<button class="bulma-control-mixin is-large">
Large
</button>
{% endcapture %}
{% include elements/snippet.html content=control-mixin-sizes %}
{% include elements/anchor.html name="Control placeholder" %}
<div class="content">
<p>
The <code>control()</code> mixin also exists as <a href="https://sass-lang.com/documentation/at-rules/extend#placeholder-selectors" target="_blank">Sass placeholder</a> <code>%control</code>
</p>
</div>
{% highlight sass %}.bulma-control-extend {
@extend %control;
background: mediumblue;
color: white;
}{% endhighlight %}
{% capture control-extend %}
<button class="bulma-control-extend">
My control
</button>
{% endcapture %}
{% include elements/snippet.html content=control-extend %}

View File

@@ -1,68 +1,59 @@
---
title: Mixins
title: Extends
layout: documentation
doc-tab: overview
doc-subtab: mixins
doc-tab: utilities
doc-subtab: extends
breadcrumb:
- home
- documentation
- overview
- overview-mixins
- utilities
- utilities-extends
---
<div class="table-container">
<table class="table is-bordered">
<tr>
<td><code>=arrow($color)</code></td>
<td>Creates a CSS-only down arrow. Used for the dropdown select.</td>
</tr>
<tr>
<td><code>=block</code></td>
<td>Defines a margin-bottom of 1.5rem, except when the element is the last child. Used for almost all block elements.</td>
</tr>
<tr>
<td><code>=clearfix</code></td>
<td>Adds a clearfix at the end of the element. Used for the "is-clearfix" helper.</td>
</tr>
<tr>
<td><code>=center($size)</code></td>
<td>Positions an element in the exact center of its parent. Used for the spinner in a loading button.</td>
</tr>
<tr>
<td><code>=delete</code></td>
<td>Creates a CSS-only cross. Used for the delete element in modals, messages, tags...</td>
</tr>
<tr>
<td><code>=fa($size, $dimensions)</code></td>
<td>Sets the style of a Font Awesome icon container.</td>
</tr>
<tr>
<td><code>=hamburger($dimensions)</code></td>
<td>Creates a CSS-only hamburger menu with 3 bars. Used for the "nav-toggle".</td>
</tr>
<tr>
<td><code>=loader</code></td>
<td>Creates a CSS-only loading spinner. Used for the ".loader" element, and for input and button spinners.</td>
</tr>
<tr>
<td><code>=overflow-touch</code></td>
<td>Sets the style of a container so that it keeps momentum when scrolling on iOS devices.</td>
</tr>
<tr>
<td><code>=overlay($offset: 0)</code></td>
<td>Makes the element overlay its parent container, like the transparent modal background.</td>
</tr>
<tr>
<td><code>=placeholder</code></td>
<td>Sets the styles of an input placeholder.</td>
</tr>
<tr>
<td><code>=unselectable</code></td>
<td>Turns the element unselectable. Used for buttons to prevent selection when clicking.</td>
</tr>
</table>
</div>
<div class="content">
<p>These mixins are already used throughout Bulma, but you can use them as well to extend your own styles.</p>
<p>
In Bulma, a lot of element <strong>share</strong> a set of styles. While mixins allow sharing, they repeat the CSS rules everytime they are used.
</p>
<p>
To avoid the repetition, Bulma uses the <code>@extend</code> rule to share code. This rule tells Sass that one selector should inherit the styles of another. <a href="https://sass-lang.com/documentation/at-rules/extend" target="_blank">Learn more about the extend rule</a>.
</p>
<p>
Instead of creating CSS classes that might not be used to be the <strong>source</strong> of the set of styles, Bulma uses Sass <strong>placeholders</strong>:
</p>
<ul>
<li>
{% include elements/snippet-inline.html content="%control" %}
</li>
<li>
{% include elements/snippet-inline.html content="%unselectable" %}
</li>
<li>
{% include elements/snippet-inline.html content="%arrow" %}
</li>
<li>
{% include elements/snippet-inline.html content="%block" %}
</li>
<li>
{% include elements/snippet-inline.html content="%delete" %}
</li>
<li>
{% include elements/snippet-inline.html content="%loader" %}
</li>
<li>
{% include elements/snippet-inline.html content="%overlay" %}
</li>
<li>
{% include elements/snippet-inline.html content="%reset" %}
</li>
</ul>
{% assign mixins_link = site.data.links.by_id['utilities-mixins'] %}
{% assign controls_link = site.data.links.by_id['utilities-control-mixins'] %}
<p>
Each of these placeholders are simply the <code>@extend</code> version of their <a href="{{ site.url }}{{ mixins_link.path }}">corresponding mixins</a> (here for the <a href="{{ site.url }}{{ controls_link.path }}">control mixin</a>).
</p>
</div>

View File

@@ -1,13 +1,13 @@
---
title: Functions
layout: documentation
doc-tab: overview
doc-tab: utilities
doc-subtab: functions
breadcrumb:
- home
- documentation
- overview
- overview-functions
- utilities
- utilities-functions
---
<div class="content">
@@ -203,6 +203,7 @@ breadcrumb:
<br>
For example, this shade of <span class="bd-color" style="background: hsl(294, 71%, 79%); float: none; height: 16px; width: 16px; margin-right: 0; vertical-align: middle;"></span> purple has a color luminance of <code>0.5529</code>. It can be preferable to set a color invert of white instead of transparent black:
</p>
<div class="table-container">
<table class="table is-bordered">
<tbody>
@@ -252,3 +253,77 @@ breadcrumb:
The <code>findLightColor($color)</code> and <code>findDarkColor($color)</code> functions take a <strong>color</strong> as an input, and output that color's light and dark versions respectively</code>:
</p>
</div>
<div class="table-container">
<table class="table is-bordered">
<thead>
<tr>
<th>color</th>
<th>findLightColor</th>
<th>findDarkColor</th>
</tr>
</thead>
<tbody>
<tr>
<td>
{% include elements/color-square.html value="hsl(171deg, 100%, 41%)" %}
</td>
<td>
{% include elements/color-square.html value="hsl(171deg, 100%, 96%)" %}
</td>
<td>
{% include elements/color-square.html value="hsl(171deg, 100%, 29%)" %}
</td>
</tr>
<tr>
<td>
{% include elements/color-square.html value="hsl(229deg 53% 53%)" %}
</td>
<td>
{% include elements/color-square.html value="hsl(229deg 52% 96%)" %}
</td>
<td>
{% include elements/color-square.html value="hsl(229deg 53% 47%)" %}
</td>
</tr>
<tr>
<td>
{% include elements/color-square.html value="hsl(153deg 53% 53%)" %}
</td>
<td>
{% include elements/color-square.html value="hsl(153deg 52% 96%)" %}
</td>
<td>
{% include elements/color-square.html value="hsl(153deg 53% 31%)" %}
</td>
</tr>
<tr>
<td>
{% include elements/color-square.html value="hsl(44deg 100% 77%)" %}
</td>
<td>
{% include elements/color-square.html value="hsl(45deg 100% 96%)" %}
</td>
<td>
{% include elements/color-square.html value="hsl(44deg 100% 29%)" %}
</td>
</tr>
<tr>
<td>
{% include elements/color-square.html value="hsl(348deg 86% 61%)" %}
</td>
<td>
{% include elements/color-square.html value="hsl(347deg 90% 96%)" %}
</td>
<td>
{% include elements/color-square.html value="hsl(348deg 86% 43%)" %}
</td>
</tr>
</tbody>
</table>
</div>

View File

@@ -1,11 +1,231 @@
---
title: Mixins
title: Responsive Mixins
layout: documentation
doc-tab: utilities
doc-subtab: mixins
doc-subtab: responsive-mixins
fullmain: true
breadcrumb:
- home
- documentation
- utilities
- utilities-responsive-mixins
---
<div class="content">
<p>
Bulma is <strong>responsive by default</strong>. <a href="{{ site.url}}/overview/responsiveness/">Learn more about Bulma's responsiveness</a>.
</p>
<div class="content">
By having <strong>4 breakpoints</strong> and supporting <strong>5 screen sizes</strong>, Bulma can support a lot of different setups. To simplify your development process, the framework provides several <strong>responsive mixins</strong> that you can use to create a <strong>responsive design</strong>:
</div>
</div>
{% capture inc-mobile %}
@include mobile {
// Styles applied
// below $tablet
}
{% endcapture %}
{% capture inc-tablet %}
@include tablet {
// Styles applied
// above $tablet
}
{% endcapture %}
{% capture inc-tablet-only %}
@include tablet-only {
// Styles applied
// between $tablet
// and $desktop
}
{% endcapture %}
{% capture inc-desktop-only %}
@include desktop-only {
// Styles applied
// between $desktop
// and $widescreen
}
{% endcapture %}
{% capture inc-widescreen-only %}
@include widescreen-only {
// Styles applied
// between $widescreen
// and $fullhd
}
{% endcapture %}
{% capture inc-desktop %}
@include desktop {
// Styles applied
// above $desktop
}
{% endcapture %}
{% capture inc-widescreen %}
@include widescreen {
// Styles applied
// above $widescreen
}
{% endcapture %}
{% capture inc-fullhd %}
@include fullhd {
// Styles applied
// above $fullhd
}
{% endcapture %}
{% capture inc-touch %}
@include touch {
// Styles applied
// below $desktop
}
{% endcapture %}
{% capture inc-until-widescreen %}
@include until-widescreen {
// Styles applied
// below $widescreen
}
{% endcapture %}
{% capture inc-until-fullhd %}
@include until {
// Styles applied
// below $fullhd
}
{% endcapture %}
<div class="table-container">
<table class="table is-bordered">
<thead>
<tr>
{% for breakpoint_hash in site.data.breakpoints %}
{% assign breakpoint = breakpoint_hash[1] %}
<th style="width: 20%;">
{{ breakpoint.name }}<br>
{% if breakpoint.id == 'mobile' %}
Up to <code>{{ breakpoint.to }}px</code>
{% elsif breakpoint.id == 'fullhd' %}
<code>{{ breakpoint.from }}px</code> and above
{% else %}
Between <code>{{ breakpoint.from }}px</code> and <code>{{ breakpoint.to }}px</code>
{% endif %}
</th>
{% endfor %}
</tr>
</thead>
<tbody>
<tr>
<td>
{% highlight sass %}{{ inc-mobile }}{% endhighlight %}
</td>
<td colspan="4">
<p class="notification">-</p>
</td>
</tr>
<tr>
<td>
<p class="notification">-</p>
</td>
<td colspan="4">
{% highlight sass %}{{ inc-tablet }}{% endhighlight %}
</td>
</tr>
<tr>
<td colspan="2">
<p class="notification">-</p>
</td>
<td colspan="3">
{% highlight sass %}{{ inc-desktop }}{% endhighlight %}
</td>
</tr>
<tr>
<td colspan="3">
<p class="notification">-</p>
</td>
<td colspan="2">
{% highlight sass %}{{ inc-widescreen }}{% endhighlight %}
</td>
</tr>
<tr>
<td colspan="4">
<p class="notification">-</p>
</td>
<td>
{% highlight sass %}{{ inc-fullhd }}{% endhighlight %}
</td>
</tr>
<tr>
<td>
<p class="notification">-</p>
</td>
<td>
{% highlight sass %}{{ inc-tablet-only }}{% endhighlight %}
</td>
<td colspan="3">
<p class="notification">-</p>
</td>
</tr>
<tr>
<td colspan="2">
<p class="notification">-</p>
</td>
<td>
{% highlight sass %}{{ inc-desktop-only }}{% endhighlight %}
</td>
<td colspan="2">
<p class="notification">-</p>
</td>
</tr>
<tr>
<td colspan="3">
<p class="notification">-</p>
</td>
<td>
{% highlight sass %}{{ inc-widescreen-only }}{% endhighlight %}
</td>
<td>
<p class="notification">-</p>
</td>
</tr>
<tr>
<td colspan="2">
{% highlight sass %}{{ inc-touch }}{% endhighlight %}
</td>
<td colspan="3">
<p class="notification">-</p>
</td>
</tr>
<tr>
<td colspan="3">
{% highlight sass %}{{ inc-until-widescreen }}{% endhighlight %}
</td>
<td colspan="2">
<p class="notification">-</p>
</td>
</tr>
<tr>
<td colspan="4">
{% highlight sass %}{{ inc-until-fullhd }}{% endhighlight %}
</td>
<td colspan="1">
<p class="notification">-</p>
</td>
</tr>
</tbody>
</table>
</div>
{% assign or_link = site.data.links.by_id['overview-responsiveness'] %}
<div class="content">
<p>
Learn more about <a href="{{ site.url }}{{ or_link.path }}">Bulma responsiveness</a>.
</p>
</div>