Merge branch 'develop' of https://github.com/Amsterdam/design-system …

…into feature/DES-670-file-input
Amsterdam · May 23, 2024 · 7af9ca6 · 7af9ca6
2 parents d8082bf + 7b98773
commit 7af9ca6
Show file tree

Hide file tree

Showing 132 changed files with 2,591 additions and 1,663 deletions.
diff --git a/.github/workflows/feature-branch-deploy.yml b/.github/workflows/feature-branch-deploy.yml
@@ -35,7 +35,7 @@ jobs:
         with:
           node-version: 20
 
-      - uses: pnpm/action-setup@v3
+      - uses: pnpm/action-setup@v4
         name: Install pnpm
         id: pnpm-install
         with:

diff --git a/.github/workflows/lint-test.yml b/.github/workflows/lint-test.yml
@@ -19,7 +19,7 @@ jobs:
           node-version: "20"
 
       - name: Install pnpm
-        uses: pnpm/action-setup@v3
+        uses: pnpm/action-setup@v4
         id: pnpm-install
         with:
           version: 9
@@ -57,7 +57,7 @@ jobs:
           node-version: "20"
 
       - name: Install pnpm
-        uses: pnpm/action-setup@v3
+        uses: pnpm/action-setup@v4
         id: pnpm-install
         with:
           version: 9

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -38,7 +38,7 @@ jobs:
         if: ${{ steps.release.outputs.releases_created == 'true' }}
 
       - name: Install pnpm
-        uses: pnpm/action-setup@v3
+        uses: pnpm/action-setup@v4
         id: pnpm-install
         with:
           version: 9

diff --git a/documentation/storybook.md b/documentation/storybook.md
@@ -21,18 +21,36 @@ We write our documentation in English, the stories are Dutch.
 ## Best practices for controls
 
 Controls are automatically generated based on the component’s typing.
-If you want to document native HTML attributes, you can use [`argTypes`](https://storybook.js.org/docs/api/arg-types).
-You can also use `argTypes` to override the automatically generated controls.
+
+### Prop descriptions
+
+We use JSDoc to describe each prop to keep documentation close to the actual definition.
+This also helps IDEs pick up the description and display it in their user interface.
+The description briefly explains the essence of the prop.
+A guideline on how to use the prop may be added, as well as a description of its effect, e.g. visually.
+Prevent mentioning the component’s name in a prop description – that should be obvious.
+Prop types that aren’t exported don’t require their properties to be described.
+
+### Arg Types
+
+Add [`argTypes`](https://storybook.js.org/docs/api/arg-types) to the Story to document native HTML attributes or override the generated controls.
 Be sure to follow these guidelines when you do:
 
-1. For props offering five options or less, use radio buttons rather than a select.
+1. Add a `description` field instead of a JSDoc comment for native HTML attributes.
+   Use terse sentences that end with a full stop.
+   When adding a prop, check for a corresponding existing prop and copy its description.
+2. When mentioning a component, write its name in title case, e.g. ‘Card’ or ‘Form Field’.
+   This represents the component more strongly and helps users recognise them as such.
+3. For props offering five options or less, use radio buttons rather than a select.
    This makes it easier to compare the options.
    It saves the user a click to select each option and shows everything up front.
-2. Don’t use inline radios.
+4. Don’t use inline radios.
    Their options appear rather small, making them difficult to target with a pointing device.
 
 More to follow.
 
+### The `children` prop
+
 By default, we hide the `children` prop from the controls.
 Children of React components are often React components themselves, which isn't very useful to show in Storybook.
 However, sometimes it is useful to add `children` to the controls.

diff --git a/package.json b/package.json
@@ -10,13 +10,13 @@
   "private": true,
   "engines": {
     "node": "^20",
-    "npm": "^8",
+    "npm": "^10",
     "pnpm": "^9"
   },
   "volta": {
-    "node": "20.11.1",
-    "npm": "10.5.0",
-    "pnpm": "9.0.2"
+    "node": "20.13.1",
+    "npm": "10.5.2",
+    "pnpm": "9.1.1"
   },
   "workspaces": [
     "./packages/*",
@@ -26,29 +26,29 @@
   "devDependencies": {
     "@lerna-lite/cli": "3.3.3",
     "@lerna-lite/run": "3.3.3",
-    "@types/node": "20.12.7",
-    "@typescript-eslint/eslint-plugin": "7.7.1",
-    "@typescript-eslint/parser": "7.7.1",
+    "@types/node": "20.12.11",
+    "@typescript-eslint/eslint-plugin": "7.8.0",
+    "@typescript-eslint/parser": "7.8.0",
     "conventional-changelog-conventionalcommits": "7.0.2",
     "eslint": "8.57.0",
     "eslint-config-prettier": "9.1.0",
     "eslint-plugin-import": "2.29.1",
-    "eslint-plugin-jest": "28.2.0",
+    "eslint-plugin-jest": "28.5.0",
     "eslint-plugin-json": "3.1.0",
     "eslint-plugin-mdx": "3.1.5",
     "eslint-plugin-react": "7.34.1",
     "html-validate": "8.18.2",
     "husky": "9.0.11",
     "lint-staged": "15.2.2",
-    "markdownlint-cli": "0.39.0",
-    "npm-check-updates": "16.14.18",
+    "markdownlint-cli": "0.40.0",
+    "npm-check-updates": "16.14.20",
     "npm-package-json-lint": "7.1.0",
     "npm-run-all": "4.1.5",
     "plop": "4.0.1",
     "postcss": "8.4.38",
     "prettier": "3.2.5",
-    "rimraf": "5.0.5",
-    "stylelint": "16.4.0",
+    "rimraf": "5.0.7",
+    "stylelint": "16.5.0",
     "stylelint-config-standard-scss": "13.1.0",
     "stylelint-order": "6.0.4",
     "typescript": "5.4.5",

diff --git a/packages/css/package.json b/packages/css/package.json
@@ -19,7 +19,7 @@
     "clean": "rimraf dist/"
   },
   "devDependencies": {
-    "sass": "1.75.0"
+    "sass": "1.77.1"
   },
   "peerDependencies": {
     "@amsterdam/design-system-tokens": "workspace:*",

diff --git a/packages/css/src/components/breadcrumb/breadcrumb.scss b/packages/css/src/components/breadcrumb/breadcrumb.scss
@@ -41,14 +41,14 @@
 }
 
 .ams-breadcrumb__link {
-  color: var(--ams-breadcrumb-item-link-color);
-  outline-offset: var(--ams-breadcrumb-item-link-outline-offset);
-  text-decoration-line: var(--ams-breadcrumb-item-link-text-decoration-line);
-  text-decoration-thickness: var(--ams-breadcrumb-item-link-text-decoration-thickness);
-  text-underline-offset: var(--ams-breadcrumb-item-link-text-underline-offset);
+  color: var(--ams-breadcrumb-link-color);
+  outline-offset: var(--ams-breadcrumb-link-outline-offset);
+  text-decoration-line: var(--ams-breadcrumb-link-text-decoration-line);
+  text-decoration-thickness: var(--ams-breadcrumb-link-text-decoration-thickness);
+  text-underline-offset: var(--ams-breadcrumb-link-text-underline-offset);
 
   &:hover {
-    color: var(--ams-breadcrumb-item-link-hover-color);
-    text-decoration-line: var(--ams-breadcrumb-item-link-hover-text-decoration-line);
+    color: var(--ams-breadcrumb-link-hover-color);
+    text-decoration-line: var(--ams-breadcrumb-link-hover-text-decoration-line);
   }
 }
diff --git a/packages/css/src/components/button/button.scss b/packages/css/src/components/button/button.scss
@@ -15,6 +15,7 @@
   font-family: var(--ams-button-font-family);
   font-size: var(--ams-button-font-size);
   gap: var(--ams-button-gap);
+  justify-content: center;
   line-height: var(--ams-button-line-height);
   outline-offset: var(--ams-button-outline-offset);
   padding-block: var(--ams-button-padding-block);

diff --git a/packages/css/src/components/dialog/README.md b/packages/css/src/components/dialog/README.md
@@ -10,6 +10,13 @@ A Dialog allows the user to focus on one task or a piece of information by poppi
 - Use a dialog for short and non-frequent tasks.
   Consider using the main flow for regular tasks.
 
+## The order of buttons
+
+If your Dialog needs more than one button, put the one for the primary action first and the other buttons behind it.
+Sighted users will read the primary action first, in line with the natural reading order.
+The same goes for users of screen readers, who will hear the primary action first, and users of a keyboard, who will focus the primary action first.
+Also, this approach keeps the order of buttons consistent on both narrow and wide screens: if the buttons do not fit next to each other, they get stacked vertically with the primary action on top.
+
 ## Keyboard Support
 
 | key         | function                                                         |

diff --git a/packages/css/src/components/dialog/dialog.scss b/packages/css/src/components/dialog/dialog.scss
@@ -3,8 +3,6 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../../common/breakpoint";
-
 .ams-dialog {
   background-color: var(--ams-dialog-background-color);
   border: var(--ams-dialog-border);
@@ -48,11 +46,13 @@
 
 .ams-dialog__footer {
   display: flex;
-  flex-direction: column;
-  grid-gap: var(--ams-dialog-footer-gap);
+  flex-wrap: wrap; // [1]
+  gap: var(--ams-dialog-footer-gap);
+  margin-inline-end: auto; // [1]
 
-  @media screen and (min-width: $ams-breakpoint-medium) {
-    flex-direction: row;
-    justify-content: end;
+  > * {
+    flex: auto; // [1]
   }
 }
+
+// [1] This combination stacks the buttons vertically and stretches them, until they fit next to each other.
diff --git a/packages/css/src/components/field/README.md b/packages/css/src/components/field/README.md
@@ -0,0 +1,9 @@
+<!-- @license CC0-1.0 -->
+
+# Field
+
+Wraps a single input and its related elements. May indicate that the input has a validation error.
+
+## Guidelines
+
+Only use Field to wrap a single input. Use [Fieldset](/docs/components-forms-fieldset--docs) to wrap multiple inputs.
diff --git a/packages/css/src/components/field/field.scss b/packages/css/src/components/field/field.scss
@@ -0,0 +1,16 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+.ams-field {
+  break-inside: avoid;
+  display: flex;
+  flex-direction: column;
+  gap: var(--ams-field-gap);
+}
+
+.ams-field--invalid {
+  border-inline-start: var(--ams-field-invalid-border-inline-start);
+  padding-inline-start: var(--ams-field-invalid-padding-inline-start);
+}
diff --git a/packages/css/src/components/index.scss b/packages/css/src/components/index.scss
@@ -5,6 +5,7 @@
 
 /* Append here */
 @import "./file-input/file-input";
+@import "./field/field";
 @import "./select/select";
 @import "./time-input/time-input";
 @import "./date-input/date-input";

diff --git a/packages/css/src/components/link-list/link-list.scss b/packages/css/src/components/link-list/link-list.scss
@@ -26,10 +26,10 @@
   color: var(--ams-link-list-link-color);
   display: inline-flex;
   font-family: var(--ams-link-list-link-font-family);
-  font-size: var(--ams-link-list-link-medium-font-size);
+  font-size: var(--ams-link-list-link-font-size);
   font-weight: var(--ams-link-list-link-font-weight);
   gap: var(--ams-link-list-link-gap);
-  line-height: var(--ams-link-list-link-medium-line-height);
+  line-height: var(--ams-link-list-link-line-height);
   outline-offset: var(--ams-link-list-link-outline-offset);
   text-decoration-line: var(--ams-link-list-link-text-decoration-line);
   text-decoration-thickness: var(--ams-link-list-link-text-decoration-thickness);

diff --git a/packages/css/src/components/pagination/README.md b/packages/css/src/components/pagination/README.md
@@ -15,6 +15,7 @@ Pagination indicates the current page and allows users to navigate to other page
 - Redirect users to the first page if they enter a URL with a page number that doesn’t exist.
 - Pagination can be combined with a counter at the top of the page indicating “Page # of ##.”
 - Start a page with an overview list at the top after changing the page.
+- Make sure that the visible and accessible labels for the ‘previous’ and ‘next’ buttons convey the same meaning at all times – e.g. don’t update one and forget the other.
 
 ## Relevant WCAG Rules
 

diff --git a/packages/css/src/components/paragraph/paragraph.scss b/packages/css/src/components/paragraph/paragraph.scss
@@ -13,9 +13,9 @@
 .ams-paragraph {
   color: var(--ams-paragraph-color);
   font-family: var(--ams-paragraph-font-family);
-  font-size: var(--ams-paragraph-medium-font-size);
+  font-size: var(--ams-paragraph-font-size);
   font-weight: var(--ams-paragraph-font-weight);
-  line-height: var(--ams-paragraph-medium-line-height);
+  line-height: var(--ams-paragraph-line-height);
 
   @include text-rendering;
   @include reset;

diff --git a/packages/css/src/components/search-field/search-field.scss b/packages/css/src/components/search-field/search-field.scss
@@ -27,12 +27,12 @@
   font-family: var(--ams-search-field-input-font-family);
   font-size: var(--ams-search-field-input-font-size);
   font-weight: var(--ams-search-field-input-font-weight);
+  inline-size: 100%;
   line-height: var(--ams-search-field-input-line-height);
   outline-offset: var(--ams-search-field-input-outline-offset);
   padding-block: var(--ams-search-field-input-padding-block);
   padding-inline: var(--ams-search-field-input-padding-inline);
   touch-action: manipulation;
-  width: 100%;
 
   @include text-rendering;
   @include reset-input;
@@ -53,10 +53,10 @@
 .ams-search-field__input::-webkit-search-cancel-button {
   appearance: none;
   background-image: var(--ams-search-field-input-cancel-button-background-image);
+  block-size: var(--ams-search-field-input-cancel-button-block-size);
   cursor: pointer;
-  height: var(--ams-search-field-input-cancel-button-height);
+  inline-size: var(--ams-search-field-input-cancel-button-inline-size);
   margin-inline-start: 0.5rem;
-  width: var(--ams-search-field-input-cancel-button-width);
 }
 
 @mixin reset-button {

diff --git a/packages/css/src/components/select/select.scss b/packages/css/src/components/select/select.scss
@@ -16,8 +16,8 @@
   font-family: var(--ams-select-font-family);
   font-size: var(--ams-select-font-size);
   font-weight: var(--ams-select-font-weight);
+  inline-size: 100%;
   line-height: var(--ams-select-line-height);
-  max-inline-size: 100%;
   outline-offset: var(--ams-select-outline-offset);
   padding-block: var(--ams-select-padding-block);
   padding-inline: var(--ams-select-padding-inline);

diff --git a/packages/css/src/components/text-area/text-area.scss b/packages/css/src/components/text-area/text-area.scss
@@ -18,14 +18,14 @@
   font-family: var(--ams-text-area-font-family);
   font-size: var(--ams-text-area-font-size);
   font-weight: var(--ams-text-area-font-weight);
+  inline-size: 100%;
   line-height: var(--ams-text-area-line-height);
-  max-width: 100%;
-  min-height: var(--ams-text-area-min-height);
+  max-inline-size: 100%; // This prevents overflow when using the `cols` prop
+  min-block-size: var(--ams-text-area-min-block-size);
   outline-offset: var(--ams-text-area-outline-offset);
   padding-block: var(--ams-text-area-padding-block);
   padding-inline: var(--ams-text-area-padding-inline);
   touch-action: manipulation;
-  width: 100%;
 
   @include text-rendering;
   @include reset;
@@ -69,5 +69,5 @@
 }
 
 .ams-text-area--cols {
-  width: auto;
+  inline-size: auto;
 }
diff --git a/packages/css/src/components/text-input/text-input.scss b/packages/css/src/components/text-input/text-input.scss
@@ -18,12 +18,12 @@
   font-family: var(--ams-text-input-font-family);
   font-size: var(--ams-text-input-font-size);
   font-weight: var(--ams-text-input-font-weight);
+  inline-size: 100%;
   line-height: var(--ams-text-input-line-height);
   outline-offset: var(--ams-text-input-outline-offset);
   padding-block: var(--ams-text-input-padding-block);
   padding-inline: var(--ams-text-input-padding-inline);
   touch-action: manipulation;
-  width: 100%;
 
   @include text-rendering;
   @include reset;