4.0.0

.gitignore

@@ -57,3 +57,5 @@ typings/
 # dotenv environment variables file
 .env
 
+# sass map
+*.css.map

CHANGELOG.md

@@ -1,9 +1,27 @@
-# semanticforms changelog
+# Semantic Forms changelog
 
 ## Next version
 
 - Put your changes here...
 
+## 4.0.0
+
+- Breaking: Overhauled entire codebase to drive it using mostly CSS grid instead of flexbox. This makes everything more flexible overall and fit more designs better. However the CSS and markup changes will likely cause breaking changes to previous integrations, so when upgrading make some time to visually test all your pages to alter any CSS overrides you had in place accordingly. You also might want to make some markup changes to make use of new available classes to tweak the fit of individual form fields on specific forms.
+- Altered fields to fit available space better at various screen sizes.
+- Added multiple utility classes that define how wide inputs will span in the responsive layout.
+- Added support for input type=image.
+- Added support for secondary labels.
+- Added styling for invalid form fields.
+- Added asterisk that appears on required inputs.
+- Improved accessibility considerably. Now has 100% Lighthouse score.
+- Added feature to progressively nest fieldsets with progressively darker/lighter background colors.
+- Fixed bug causing clear button appearing on disabled inputs.
+- Fixed bug causing clear button to overlap with scrollbars on textareas.
+- Fixed bug causing nested fieldset to have incorrect padding and margins.
+- Fixed various other small bugs.
+- Replaced the `less` CSS preprocessor with `sass`.
+- Updated various dependencies.
+
 ## 3.2.1
 
 - Fixed a bug that could cause checkboxes and radio buttons to not submit their values to the server properly.
@@ -59,7 +77,7 @@
 
 ## 3.0.0
 
-- Removed defualt two column layout. Now defaults to as many columns as the container is wide.
+- Removed default two column layout. Now defaults to as many columns as the container is wide.
 - Added `x2` class you can put on `dd` elements to double the width of a form. Does not apply on small screens.
 
 ## 2.1.2

README.md

@@ -2,10 +2,23 @@
 
 [![npm](https://img.shields.io/npm/v/semantic-forms.svg)](https://www.npmjs.com/package/semantic-forms)
 
-A pattern library of forms based on semantic HTML enhanced with a modern UX.
+A pattern library of attractive forms for your website with the following design goals:
+
+- Attractive, modern float label visual design.
+- Responsive layout based on modern CSS grid technique.
+- Clear fields.
+- Light and dark mode.
+- Invalid field styling.
+- Good accessibility.
+- Semantic HTML (no div soup).
+- Uses a progressive enhancement approach so that core functionality and most of the features still work with JavaScript disabled.
+- Sets no global styles and is scoped by a single class name `semanticForms` applied to `<form>` elements.
+- No dependencies.
 
 See a [live demo here](https://kethinov.github.io/semanticforms/semanticForms.html).
 
+This module was built and is maintained by the [Roosevelt web framework](https://github.com/rooseveltframework/roosevelt) [team](https://github.com/orgs/rooseveltframework/people), but it can be used independently of Roosevelt as well.
+
 # Usage
 
 Include the `semanticForms.css` and `semanticForms.js` files from this repo into your project.
@@ -18,17 +31,21 @@ Then apply the `semanticForms` class to your `<form>` elements:
 </form>
 ```
 
+Then apply the JavaScript enhancements:
+
+```javascript
+window.semanticForms()
+```
+
 Then the CSS/JS enhancements to your forms will apply automatically, assuming the markup structure you use is one of the supported patterns.
 
-This library also monitors changes to the DOM and will enhance any additional `semanticForms` forms you insert, but the monitoring may not be perfect. If you want to re-scan for new forms to enhance manually, simply call `window.semanticForms()`. If you only want to reinitialize one form instead of all of them, call `window.semanticForms.reinitialize(formName)`.
+If you make changes to the DOM after Semantic Forms is activated and want to activate any additional `semanticForms` forms you insert, you can re-scan for new forms by calling `window.semanticForms()` again. If you only want to reinitialize one form instead of all of them, call `window.semanticForms.reinitialize(formElement)`.
 
 # Features
 
-Overview of pattern library features:
-
 ## Float label inputs
 
-The float label input pattern is notoriously difficult to implement in a fashion that doesn't degrade HTML semantics or accessibility. This pattern library implements a solution that solves that problem. Your label doesn't need to be a sibling of your input like with other implementations. This implementation also has a custom clear field driven by SVG embedded in the CSS.
+The float label input pattern is notoriously difficult to implement in a fashion that doesn't degrade HTML semantics or accessibility. This pattern library implements a solution that solves that problem. Your label doesn't need to be a sibling of your input like with other implementations. This implementation also has a custom clear button for each input.
 
 ### Example
 
@@ -52,25 +69,141 @@ The float label input pattern is notoriously difficult to implement in a fashion
 </form>
 ```
 
-If you would like to manipulate the size of the area on the input field reserved for the click event of the clear field, apply one or both of the following `data-` attributes to your form:
+### Add help text
 
-Adjust the horizontal offset of the clear field's click event click area (the default is 21):
+Include a label in the `<dd>` element with a matching `for` attribute to place help text beneath the input:
 
 ```html
-<form class="semanticForms" data-clearfield-horizontal-offset="21">
-  <!-- your form here -->
+<form class="semanticForms">
+  <dl>
+    <dt><label for="password">Password</label></dt>
+    <dd>
+      <input id="password" name="password" type="password" placeholder="Enter a password" minlength="8" required>
+      <label for="password">Must be at least 8 characters long.</label>
+    </dd>
+  </dl>
 </form>
 ```
 
-Adjust the vertical offset of the clear field's click event click area (the default is 5):
+## Responsive columns
+
+This feature makes it so the form fields will grow, shrink, expand the number of columns, or reduce the number of columns based on how much space exists in the container. You can customize it by applying various `colspan-#` classes to various elements in the form markup structure.
+
+### Set number of columns for a group of forms
+
+You can limit the number of columns on your forms using the `colspan-#` class on a `<dl>` element:
 
 ```html
-<form class="semanticForms" data-clearfield-vertical-offset="5">
-  <!-- your form here -->
+<form class="semanticForms">
+  <dl class="colspan-2">
+    <dt><label for="input-a">Input A</label></dt>
+    <dd><input type="text" id="input-a" name="input-a"></dd>
+
+    <dt><label for="input-b">Input B</label></dt>
+    <dd><input type="text" id="input-b" name="input-b"></dd>
+
+    <!-- wraps to the next row -->
+    <dt><label for="input-c">Input C</label></dt>
+    <dd><input type="text" id="input-c" name="input-c"></dd>
+  </dl>
+</form>
+```
+
+You can also apply the class to a `<fieldset>` which will apply that styling to all nested `<dl>` elements:
+
+```html
+<form class="semanticForms">
+  <fieldset class="colspan-3">
+    <!-- inherits 3 column class -->
+    <dl>
+      <dt><label for="input-a">Input A</label></dt>
+      <dd><input type="text" id="input-a" name="input-a"></dd>
+
+      <dt><label for="input-b">Input B</label></dt>
+      <dd><input type="text" id="input-b" name="input-b"></dd>
+
+      <dt><label for="input-c">Input C</label></dt>
+      <dd><input type="text" id="input-c" name="input-c"></dd>
+    </dl>
+
+    <!-- has 4 columns -->
+    <dl class="colspan-4">
+      <dt><label for="input-d">Input D</label></dt>
+      <dd><input type="text" id="input-d" name="input-d"></dd>
+
+      <dt><label for="input-e">Input E</label></dt>
+      <dd><input type="text" id="input-e" name="input-e"></dd>
+
+      <dt><label for="input-f">Input F</label></dt>
+      <dd><input type="text" id="input-f" name="input-f"></dd>
+    </dl>
+  </fieldset>
+</form>
+```
+
+### Set number of columns a single input field takes up
+You can specify the number of columns an input will span using the `colspan-#` class on the `<dd>` element. The inputs are responsive and will shrink according to available space. Available numbered classes are `colspan-1` through `colspan-5`:
+
+
+```html
+<form class="semanticForms">
+  <fieldset>
+    <dl>
+      <dt><label for="input-a">Input A</label></dt>
+      <!-- 1 column -->
+      <dd class="colspan-1"><input type="text" id="input-a" name="input-a"></dd>
+
+      <dt><label for="input-b">Input B</label></dt>
+      <!-- 2 columns  -->
+      <dd class="colspan-2"><input type="text" id="input-b" name="input-b"></dd>
+
+      <dt><label for="input-c">Input C</label></dt>
+      <!-- 5 columns (max) -->
+      <dd class="colspan-5"><input type="text" id="input-c" name="input-c"></dd>
+    </dl>
+  </fieldset>
 </form>
 ```
 
-If you want to double the width of the input field (on screens with the extra space), add a `x2` class to the `dd` element.
+`colspan-full` can also be used to force an input to take up the entire width of a form:
+
+```html
+<form class="semanticForms">
+  <fieldset>
+    <dl>
+      <dt><label for="input-a">Input A</label></dt>
+      <!-- this spans 2 columns on row 1 -->
+      <dd class="colspan-2"><input type="text" id="input-a" name="input-a"></dd>
+
+      <dt><label for="input-b">Input B</label></dt>
+      <!-- this spans the full width of row 2 -->
+      <dd class="colspan-full"><input type="text" id="input-b" name="input-b"></dd>
+
+      <!-- this spans 1 column on row 3 -->
+      <dt><label for="input-c">Input C</label></dt>
+      <dd><input type="text" id="input-c" name="input-c"></dd>
+    </dl>
+  </fieldset>
+</form>
+```
+
+#### Set number of columns a single input field takes up on the low flow (JavaScript disabled flow)
+
+To apply `colspan-#` styles to low flow (JavaScript disabled flow) form inputs, you will need to manually wrap your `<dt>` and `<dd>` elements in a `<div>`:
+
+```html
+<form class="semanticForms">
+  <fieldset>
+    <dl>
+      <div>
+        <dt><label for="input-a">Input A</label></dt>
+        <!-- this spans 2 columns on row 1 -->
+        <dd class="colspan-2"><input type="text" id="input-a" name="input-a"></dd>
+			</div>
+    </dl>
+  </fieldset>
+</form>
+```
 
 ## Button groups
 
@@ -154,21 +287,48 @@ Not too different than other inputs:
 </form>
 ```
 
-## Other features
+## Validation styles
+
+Inputs with the `required` attribute will result in a visual indicator (*) being added to its label. You can disable this indicator with the `data-no-asterisk` attribute on the label element:
+
+```html
+<form class="semanticForms">
+  <dl>
+    <dt><label for="input" data-no-asterisk>Input label</label></dt>
+    <dd><input type="text" name="input" id="input" required>
+  </dl>
+</form>
+```
+
+You can adjust the tooltip text of the asterisk with the `data-asterisk-text` attribute:
+
+```html
+<form class="semanticForms">
+  <dl>
+    <dt><label for="input" data-asterisk-text="This is a custom tooltip.">Input label</label></dt>
+    <dd><input type="text" name="input" id="input" required>
+  </dl>
+</form>
+```
+## Dark mode
+
+To set the dark mode, apply an additional class of `dark` to your `<form>` elements to force the dark mode.
+
+## Low flow (JavaScript disabled) mode
+
+The low flow will be displayed if JS is disabled.
 
-- Custom-styled select boxes with a custom drawn arrow graphic driven by SVG embedded in the CSS.
-- Custom-styled submit buttons to match the aesthetic of the custom-styled forms.
-- Responsive: on wide screens, the forms split into multiple columns. On smaller screens, they collapse to a single column.
-- Dark mode: apply an additional class of `dark` to your `<form>` elements to use the dark mode.
-- Low-flow mode that displays on old browsers, JS-disabled browsers, or can be activated manually by adding the `lowFlow` class to your `<form>` element. The low-flow mode reverts the float label pattern to traditional labels and collapses the forms to single column mode, but preserves the other visual design enhancements driven purely by CSS.
+You can also activate the low flow (JavaScript disabled) mode manually by adding the `lowFlow` class to your `<form>` element.
 
-See `semanticForms.html` or the [live demo](https://kethinov.github.io/semanticforms/semanticForms.html) for a full demo of all the markup patterns.
+The low-flow mode reverts the float label pattern to traditional labels and doesn't include other JS-exclusive enhancements, but preserves the other visual design enhancements driven purely by CSS.
 
 # Contributing
 
 - Fork/clone this repo.
 - `npm ci`
-- Make your changes. If you want to alter the CSS, do the changes in the `.less` files.
-- `npm run build`. The build step compiles the LESS file into CSS.
+- Make your changes. If you want to alter the CSS, do the changes in the `.scss` files.
+- `npm run build`. The build step compiles the SCSS file into CSS.
+  - You can also run `npm run watch` automatically compiles the CSS file after a change is detected in the SCSS file.
 - Test your changes by opening `semanticForms.html` in your browser.
+  - If you want to test your work on an actual HTTP server, run `npm run dev` or `npm run d`.
 - Commit, push, open pull request.