nwl-components 1.8.0 → 2.1.0

package/README.md

@@ -193,6 +193,138 @@ Loading the tokens twice on a page (e.g. `tokens.css` and `dist/style.css`) is h
 `npm run lint` fails on a hex colour in `src/**/*.{vue,css}` outside `tokens.css`, and on a
 `var(--nwl-…)` that `tokens.css` doesn't define. Since 1.8.0.
 
+## Base styles and cascade layers
+
+Since 2.0.0 all the library's CSS is in three cascade layers, declared in this order at the
+top of each stylesheet it ships (`dist/style.css`, `nwl-components/base.css`,
+`nwl-components/sort/style.css`):
+
+```css
+@layer nwl.base, nwl.widgets, nwl.components;
+```
+
+- `nwl.base`: `src/styles/base.css` (below);
+- `nwl.widgets`: `src/styles/widgets.css`, the widget classes (see "Widgets");
+- `nwl.components`: the components' styles (scoped or not), `sortable.css`, and the CSS of
+  bundled dependencies (splitpanes).
+
+The tokens (`tokens.css`) stay outside the layers: they only define custom properties.
+**An app's own CSS, which is not in a layer, always wins over the library's**, whatever the
+load order or the selectors' specificity: `button { … }` in an app overrides `Button`'s scoped
+rules. No `!important` and no `html …` prefix are needed. (An app that puts its own CSS in
+layers must declare them after `nwl.components` to keep this.)
+
+`base.css` replaces 1.x's global `* { box-sizing: border-box; font-size: 14px; color: white }`
+rule, which is gone. Its selectors are wrapped in `:where()` (no specificity), and they apply
+inside the wrapper (`.app`, the root of `Wrapper`) only, except two:
+
+- `html`: `font-size: var(--nwl-text-md)` (1rem = 14px, as in 1.x), and `body`: `margin: 0`;
+- `.app`: font (`--nwl-font-body`, `--nwl-text-md`) and colour (`--nwl-text`), inherited by
+  everything inside; `box-sizing: border-box`, inherited by every element and pseudo-element;
+- headings, `small`, `sub`, `sup`, `code`, `pre` and form controls take their parent's font
+  size; form controls and `<dialog>` their parent's colour (the controls' font family stays
+  the browser's); links `--nwl-link`;
+- keyboard focus: `:focus-visible` gets a 2px solid `--nwl-focus` outline, 2px away
+  (`--nwl-focus` is `--nwl-text`, white). Mouse focus shows nothing on buttons; browsers
+  show it on text fields and Chromium on `<select>`, as they decide what is `:focus-visible`.
+
+`dist/style.css` includes `base.css`. A page without the Vue components (e.g. a Mustache page
+that wants the same font, colour and focus style) can load it alone, after the tokens:
+
+```js
+import 'nwl-components/tokens.css';
+import 'nwl-components/base.css'; // webpack 4 too (a copy at the package root)
+```
+
+```html
+<link rel="stylesheet" href="/lib/nwl-components/tokens.css">
+<link rel="stylesheet" href="/lib/nwl-components/base.css">
+<div class="app">…</div>
+```
+
+Outside `.app`, nothing sets font, colour or box-sizing any more: an app's own markup on a
+page that loads `dist/style.css` gets them from the app's CSS (or from being inside `.app`).
+
+## Widgets
+
+Since 2.1.0, `src/styles/widgets.css` holds class-based widgets for markup that isn't Vue
+(Mustache pages, the viewers' tool panels); the library's `Button` uses them too. They are in
+`@layer nwl.widgets` and every selector is wrapped in `:where()`, so **an app rule with one
+class wins** over them. Colours, borders and radii come from the semantic tokens.
+
+State is an ARIA attribute, not a class, so screen readers get it too: `aria-pressed="true"` on
+a tool button that is on, `aria-selected="true"` on a selected table row, `disabled` (or
+`aria-disabled="true"` on a link) on a button. The apps' classes (`.pressed`, `.mui-pressed`,
+`.selected`) don't style the widgets.
+
+Push button (Save, Cancel): 1px `--nwl-border-strong` outline, `--nwl-radius-md`, bold, on a
+`<button>`, `<a>`, `<select>` or `<input type="button|submit">`. Hover: `--nwl-bg-pressed`;
+disabled: opacity .4.
+
+```html
+<button class="nwl-push-button">Save</button>
+```
+
+Tool button (a viewer's tool panel): 24px high, 1px `--nwl-border`, `--nwl-radius-sm`; it fills
+its container's width, less its 1px margins, as the apps' div tools did. On a native `<button>`
+it is in the tab order with no script. Pressed: `aria-pressed="true"` gives `--nwl-bg-pressed`.
+Hover: `--nwl-bg-pressed` on a text button, opacity .5 on a button whose only element is an
+icon (`img`, `svg` or `.nwl-icon`; CSS can't see text, so a button with an icon and text counts
+as an icon button). `.nwl-tool-button--sub`: a tool inside a group (no border, 22px).
+
+```html
+<div style="flex: 1"><button class="nwl-tool-button" aria-pressed="true">Sag</button></div>
+<div style="flex: 1">
+  <button class="nwl-tool-button" aria-pressed="false" aria-label="Full screen">
+    <img class="nwl-icon" src="/img/fullscreen.svg" alt="">
+  </button>
+</div>
+```
+
+Icon button: an icon with no border; opacity .5 on hover. It shows no text, so give it an
+accessible name with `aria-label`, and an empty `alt` to its image.
+
+```html
+<button class="nwl-icon-button" aria-label="Zoom in"><img class="nwl-icon" src="/img/zoomIn.svg" alt=""></button>
+```
+
+Icon: 16px, aligned with the text (`vertical-align: middle`), not selectable.
+
+```html
+<img class="nwl-icon" src="/img/home.svg" alt="Home">
+```
+
+Text field (`<input>`, `<textarea>`): its parent's font size and colour, `--nwl-bg-input`, 1px
+`--nwl-border`, `--nwl-radius-sm`, no padding (as the apps' `.text`), placeholder in
+`--nwl-text-placeholder`.
+
+```html
+<input class="nwl-text-field" placeholder="Project name">
+```
+
+Selected row: `aria-selected="true"` on a `<tr>` gives `--nwl-bg-elevated`.
+
+```html
+<tr aria-selected="true"><td>axolotl</td></tr>
+```
+
+Keyboard focus on the widgets shows `base.css`'s outline (2px `--nwl-focus`), also outside
+`.app`. Links take `--nwl-link` (hover `--nwl-link-hover`), both the text colour: keep their
+underline (the browser's) where they sit in text, so they don't depend on colour alone.
+
+`dist/style.css` includes the widgets. A page with no bundle links the three files, in this
+order (microdraw serves `node_modules/nwl-components/dist/` as `/lib/nwl-components/`):
+
+```html
+<link rel="stylesheet" href="/lib/nwl-components/tokens.css">
+<link rel="stylesheet" href="/lib/nwl-components/base.css">
+<link rel="stylesheet" href="/lib/nwl-components/widgets.css">
+```
+
+With a bundler: `import 'nwl-components/widgets.css'` after the tokens and base (webpack 4 too:
+a copy at the package root). Storybook's `Library/Widgets` shows each widget in plain HTML, with
+its states.
+
 ## Single File Components
 
 This project makes use of Vue SFCs: _Single File Components_, that have the `.vue` extension.

package/base.css

@@ -0,0 +1,63 @@
+@layer nwl.base, nwl.widgets, nwl.components;
+@layer nwl.base {
+/* nwl-components base styles: `import 'nwl-components/base.css'` (after `nwl-components/tokens.css`,
+   whose tokens it reads). dist/style.css includes it.
+
+   The build puts this file in `@layer nwl.base`, the lowest of the library's layers
+   (`@layer nwl.base, nwl.widgets, nwl.components`), so any app rule wins over it. Selectors are
+   wrapped in :where(), so they add no specificity.
+
+   Font and colour are set once, on the wrapper (`.app`, the root of `Wrapper`), and inherited:
+   there is no `*` rule setting them on every element. */
+
+/* 1rem = 14px, as in 1.x (where the `*` rule set it on <html>): the components' rem sizes */
+:where(html) {
+  font-size: var(--nwl-text-md);
+}
+
+:where(body) {
+  margin: 0;
+}
+
+:where(.app) {
+  box-sizing: border-box;
+  font-family: var(--nwl-font-body);
+  font-size: var(--nwl-text-md);
+  color: var(--nwl-text);
+}
+
+:where(.app) *,
+:where(.app) *::before,
+:where(.app) *::after {
+  box-sizing: inherit;
+}
+
+/* Elements the browser gives a size of their own (headings, small print, code, form controls)
+   take their parent's, as 1.x's `*` rule made them do. */
+:where(.app) :where(h1, h2, h3, h4, h5, h6, small, sub, sup, big, code, kbd, samp, pre, tt, button, input, select, textarea) {
+  font-size: inherit;
+}
+
+/* Form controls and dialogs don't inherit the colour by default either. The controls' font
+   family stays the browser's, as it was in 1.x. */
+:where(.app) :where(button, input, select, textarea, dialog) {
+  color: inherit;
+}
+
+/* links: the link colour, not the browser's blue. The browser's underline stays: links are
+   the text colour (--nwl-link), so the underline is what tells them apart (WCAG 1.4.1). */
+:where(.app a) {
+  color: var(--nwl-link);
+}
+
+:where(.app a:hover) {
+  color: var(--nwl-link-hover);
+}
+
+/* Keyboard focus: a 2px outline in --nwl-focus. Mouse focus shows nothing (browsers match
+   :focus-visible on a mouse click only for text fields). */
+:where(.app :focus-visible) {
+  outline: 2px solid var(--nwl-focus);
+  outline-offset: 2px;
+}
+}

package/dist/base.css

@@ -0,0 +1,63 @@
+@layer nwl.base, nwl.widgets, nwl.components;
+@layer nwl.base {
+/* nwl-components base styles: `import 'nwl-components/base.css'` (after `nwl-components/tokens.css`,
+   whose tokens it reads). dist/style.css includes it.
+
+   The build puts this file in `@layer nwl.base`, the lowest of the library's layers
+   (`@layer nwl.base, nwl.widgets, nwl.components`), so any app rule wins over it. Selectors are
+   wrapped in :where(), so they add no specificity.
+
+   Font and colour are set once, on the wrapper (`.app`, the root of `Wrapper`), and inherited:
+   there is no `*` rule setting them on every element. */
+
+/* 1rem = 14px, as in 1.x (where the `*` rule set it on <html>): the components' rem sizes */
+:where(html) {
+  font-size: var(--nwl-text-md);
+}
+
+:where(body) {
+  margin: 0;
+}
+
+:where(.app) {
+  box-sizing: border-box;
+  font-family: var(--nwl-font-body);
+  font-size: var(--nwl-text-md);
+  color: var(--nwl-text);
+}
+
+:where(.app) *,
+:where(.app) *::before,
+:where(.app) *::after {
+  box-sizing: inherit;
+}
+
+/* Elements the browser gives a size of their own (headings, small print, code, form controls)
+   take their parent's, as 1.x's `*` rule made them do. */
+:where(.app) :where(h1, h2, h3, h4, h5, h6, small, sub, sup, big, code, kbd, samp, pre, tt, button, input, select, textarea) {
+  font-size: inherit;
+}
+
+/* Form controls and dialogs don't inherit the colour by default either. The controls' font
+   family stays the browser's, as it was in 1.x. */
+:where(.app) :where(button, input, select, textarea, dialog) {
+  color: inherit;
+}
+
+/* links: the link colour, not the browser's blue. The browser's underline stays: links are
+   the text colour (--nwl-link), so the underline is what tells them apart (WCAG 1.4.1). */
+:where(.app a) {
+  color: var(--nwl-link);
+}
+
+:where(.app a:hover) {
+  color: var(--nwl-link-hover);
+}
+
+/* Keyboard focus: a 2px outline in --nwl-focus. Mouse focus shows nothing (browsers match
+   :focus-visible on a mouse click only for text fields). */
+:where(.app :focus-visible) {
+  outline: 2px solid var(--nwl-focus);
+  outline-offset: 2px;
+}
+}