diff --git a/.eslintrc b/.eslintrc index 7627ac8eed9..0c9c8c46cd7 100644 --- a/.eslintrc +++ b/.eslintrc @@ -1,8 +1,9 @@ { - "extends": ["wesbos"], + "extends": ["carbon"], "globals": { "fathom": "readonly" }, + "root": true, "rules": { "react/prop-types": 0, "react/destructuring-assignment": 0, diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 69a934dde44..449e1574f9a 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,11 +1,8 @@ -# Default to the system team -* @carbon-design-system/developers-system +# Default to system one design and one dev +* @carbon-design-system/developers-system @carbon-design-system/design *.conf @vpicone -# If updating content (mdx) opt for systems team -*.mdx @carbon-design-system/developers-system @carbon-design-system/content - # Vikki Paterson is code owner for Experimental IDE patterns src/pages/community/patterns/create-flows/* @vikkipaterson src/pages/community/patterns/delete-pattern/* @vikkipaterson @@ -29,7 +26,7 @@ src/pages/community/patterns/login-pattern/* @lukefirth src/pages/data-visualization/* @theiliad @natashadecoste # Cal Smith for Angular tutorial -/src/pages/tutorial/angular/* @cal-smith +/src/pages/tutorial/angular/* @zvonimirfras # Lee Chase for Vue tutorial /src/pages/tutorial/vue/* @lee-chase diff --git a/.github/workflows/add-to-project.yml b/.github/workflows/add-to-project.yml new file mode 100644 index 00000000000..98c40c9dc97 --- /dev/null +++ b/.github/workflows/add-to-project.yml @@ -0,0 +1,11 @@ +name: Add To Project + +on: + issues: + types: [opened, labeled] + +jobs: + issue-triage: + uses: carbon-design-system/carbon/.github/workflows/add-to-project.yml@main + secrets: + ADD_TO_PROJECT_PAT: ${{ secrets.ADD_TO_PROJECT_PAT }} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 00000000000..0c66e073c7f --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,34 @@ +name: ci +on: + push: + branches: + - main + pull_request: + branches: + - main +jobs: + format: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Use Node.js 16.x + uses: actions/setup-node@v2.4.1 + with: + node-version: '16.x' + - name: Install dependencies + run: yarn install --frozen-lockfile + - name: Check formatting of project files + run: yarn format:check + + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Use Node.js 16.x + uses: actions/setup-node@v2.4.1 + with: + node-version: '16.x' + - name: Install dependencies + run: yarn install --frozen-lockfile + - name: Lint JavaScript files + run: yarn lint:js diff --git a/.github/workflows/dco.yml b/.github/workflows/dco.yml index 1ee3e7bd936..a15c09176d1 100644 --- a/.github/workflows/dco.yml +++ b/.github/workflows/dco.yml @@ -11,7 +11,7 @@ jobs: steps: - name: "DCO Assistant" if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the DCO document and I hereby sign the DCO.') || github.event_name == 'pull_request_target' - uses: cla-assistant/github-action@v2.1.2-beta + uses: cla-assistant/github-action@v2.2.0 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} PERSONAL_ACCESS_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }} @@ -28,4 +28,4 @@ jobs: custom-pr-sign-comment: "I have read the DCO document and I hereby sign the DCO." custom-allsigned-prcomment: "All contributors have signed the DCO." lock-pullrequest-aftermerge: false - use-dco-flag: true \ No newline at end of file + use-dco-flag: true diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index f3d1bc78e86..65f24186c6a 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -1,5 +1,9 @@ name: Deployment status +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + on: workflow_dispatch: inputs: @@ -10,35 +14,45 @@ on: - main jobs: - build: - runs-on: macos-latest - + gh-pages: + if: github.repository == 'carbon-design-system/carbon-website' + runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - name: Use Node.js 14.x - uses: actions/setup-node@v2-beta + - uses: actions/checkout@v3 + - name: Use Node.js 16.x + uses: actions/setup-node@v3 with: - node-version: 14.x - + node-version: 16.x - name: Install packages run: yarn install --frozen-lockfile --network-timeout 300000 - + - name: Gatsby Cache Folder + uses: actions/cache@v3 + id: gatsby-cache-folder + with: + path: .cache + key: ${{ runner.os }}-cache-gatsby + restore-keys: | + ${{ runner.os }}-cache-gatsby + - name: Gatsby Public Folder + uses: actions/cache@v3 + id: gatsby-public-folder + with: + path: public/ + key: ${{ runner.os }}-public-gatsby + restore-keys: | + ${{ runner.os }}-public-gatsby - name: Build site run: yarn build:clean - - - name: Install IBM Cloud CLI - run: curl -fsSL https://clis.cloud.ibm.com/install/osx | sh - - - name: Install Cloud Foundry CLI - run: ibmcloud cf install -v 6.51.0 - - - name: Login to ibmcloud env: - API_KEY: ${{ secrets.API_KEY }} - run: - ibmcloud login -a "https://cloud.ibm.com" -u apikey -p "$API_KEY" -o - "carbon-design-system" -s "production" -r "us-south" - - - name: Deploy website + GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES: true + NODE_ENV: production + CI: true + - name: Add CNAME record + run: | + echo 'carbondesignsystem.com' > public/CNAME + - name: Deploy run: | - ibmcloud cf v3-zdt-push carbon-website -b https://github.com/cloudfoundry/nginx-buildpack.git + git remote set-url origin https://git:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git + npx gh-pages -d public -u "github-actions " + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/issue-triage.yml b/.github/workflows/issue-triage.yml new file mode 100644 index 00000000000..7bff43ed743 --- /dev/null +++ b/.github/workflows/issue-triage.yml @@ -0,0 +1,12 @@ +name: Issue Triage +on: + issues: + types: [opened] + issue_comment: + types: [created] +jobs: + issue-triage: + uses: carbon-design-system/carbon/.github/workflows/issue-triage.yml@main + secrets: + APP_ID: ${{ secrets.APP_ID }} + APP_PRIVATE_KEY: ${{ secrets.APP_PRIVATE_KEY }} diff --git a/.github/workflows/platform-content-sync.yml b/.github/workflows/platform-content-sync.yml new file mode 100644 index 00000000000..efce1cdb40d --- /dev/null +++ b/.github/workflows/platform-content-sync.yml @@ -0,0 +1,29 @@ +name: Sync content with platform + +on: + push: + branches: + - 'main' + paths: + - '**.mdx' + +jobs: + create_issue: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + repository: carbon-design-system/carbon-platform + ref: main + - name: Generate token + uses: tibdex/github-app-token@v1 + id: generate_token + with: + app_id: ${{ secrets.APP_ID }} + private_key: ${{ secrets.APP_PRIVATE_KEY }} + - name: Create issue on platform repo + run: | + gh issue create --title "[Content sync]: carbon-website" --label "role: dev πŸ€–" --label "service: web-app 🌎" --body 'A pull request on carbon-website was just merged. It contains .mdx content changes that may need to be synced to platform: + - ${{ github.event.compare }}' + env: + GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }} diff --git a/.github/workflows/sync-platform-branch.yml b/.github/workflows/sync-platform-branch.yml new file mode 100644 index 00000000000..d6e79e538e4 --- /dev/null +++ b/.github/workflows/sync-platform-branch.yml @@ -0,0 +1,58 @@ +name: Sync Platform Branch +on: + schedule: + # Runs on Fridays 6:00 UTC (-6 CT, -5 EST) + # β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ minute (0 - 59) + # β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ hour (0 - 23) + # β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ day of the month (1 - 31) + # β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ month (1 - 12 or JAN-DEC) + # β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ day of the week (0 - 6 or SUN-SAT) + # β”‚ β”‚ β”‚ β”‚ β”‚ + # β”‚ β”‚ β”‚ β”‚ β”‚ + # β”‚ β”‚ β”‚ β”‚ β”‚ + - cron: 0 6 * * 5 + + # Enable running this workflow manually from the Actions tab + workflow_dispatch: # Allow for running this manually. + +jobs: + sync-branches: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Create PR branch πŸ€– + run: | + git branch carbon-platform-sync + git push origin carbon-platform-sync + + - name: Create Pull Request + uses: actions/github-script@v6 + with: + script: | + const { repo, owner } = context.repo; + const result = await github.rest.pulls.create({ + title: 'Sync carbon-platform branch', + owner, + repo, + head: 'carbon-platform-sync', + base: 'carbon-platform', + body: [ + 'Platform Sync, pulling in new content from main into carbon-platform branch', + 'This PR is auto-generated by [actions/github-script](https://github.com/actions/github-script).', + "**Note**: It’s ok for the CI cheks to fail on this PR, this code is not runnable due to the platform changes" + ].join('\n') + }); + github.rest.issues.addLabels({ + owner, + repo, + issue_number: result.data.number, + labels: ['status: enable automerge 🟠', 'status: ready for review πŸ‘€'] + }); + github.rest.pulls.requestReviewers({ + owner, + repo, + pull_number: result.data.number, + reviewers: ['francinelucca', 'andreancardona', 'alisonjoseph'] + }); diff --git a/.gitignore b/.gitignore index 505c0fd84d5..58f53ae7bf4 100644 --- a/.gitignore +++ b/.gitignore @@ -102,8 +102,11 @@ public # Vscode settings .vscode/settings.json +# Jetbrains +.idea + # Build timestamp build-timestamp .now -.vercel \ No newline at end of file +.vercel diff --git a/.kodiak.toml b/.kodiak.toml index 505f9188836..8c7026011d4 100644 --- a/.kodiak.toml +++ b/.kodiak.toml @@ -2,5 +2,6 @@ version = 1 [merge] -automerge_label = "status: ready to merge πŸŽ‰" +automerge_label = ["status: ready to merge πŸŽ‰", "status: enable automerge 🟠"] +notify_on_conflict = "false" method = "squash" diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 00000000000..5edcff03642 --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +v16 \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index b32dadb0809..00000000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "editor.formatOnSave": true, - "[javascript]": { - "editor.formatOnSave": false - }, - "[javascriptreact]": { - "editor.formatOnSave": false - }, - "prettier.disableLanguages": ["javascript", "javascriptreact"], - "editor.codeActionsOnSave": { - "source.fixAll.eslint": true - } -} diff --git a/conf.d/rewrite.conf b/conf.d/rewrite.conf index c966c4a8a15..e347e76e4c3 100644 --- a/conf.d/rewrite.conf +++ b/conf.d/rewrite.conf @@ -44,3 +44,7 @@ rewrite /tutorial/vue/(.*) /developing/vue-tutorial/\$1 permanent; # Data-visualization rewrite /data-visualization/basic-charts/ /data-visualization/simple-charts/ permanent; rewrite /data-visualization/advanced-charts/ /data-visualization/complex-charts/ permanent; + +#v11 +rewrite https://v11.carbondesignsystem.com/migrating/guide/\$1 /migrating/guide/\$1 permanent; +rewrite /whats-happening/v11-release /migrating/guide/\$1 permanent; \ No newline at end of file diff --git a/gatsby-browser.js b/gatsby-browser.js index 767df1cbb4b..e848af3b2be 100644 --- a/gatsby-browser.js +++ b/gatsby-browser.js @@ -1,2 +1 @@ -/* eslint-disable import/prefer-default-export */ import './src/styles/index.scss'; diff --git a/gatsby-config.js b/gatsby-config.js index 0f22031db3c..8d6822d2c88 100644 --- a/gatsby-config.js +++ b/gatsby-config.js @@ -9,11 +9,6 @@ module.exports = { keywords: 'IBM, design, system, Carbon, design system, Bluemix, styleguide, style, guide, components, library, pattern, kit, component, cloud', }, - flags: { - PRESERVE_WEBPACK_CACHE: true, - FAST_DEV: true, - FAST_REFRESH: true, - }, plugins: [ { resolve: 'gatsby-source-filesystem', @@ -54,6 +49,10 @@ module.exports = { baseUrl: 'https://github.com/carbon-design-system/carbon-website', subDirectory: '', }, + mediumAccount: 'carbondesign', + theme: { + homepage: 'white', + }, }, }, { @@ -78,5 +77,6 @@ module.exports = { }, }, 'gatsby-plugin-remove-serviceworker', + 'gatsby-plugin-meta-redirect', ], }; diff --git a/gatsby-node.js b/gatsby-node.js index 5f3aaca591d..d4834afc2c2 100644 --- a/gatsby-node.js +++ b/gatsby-node.js @@ -7,7 +7,7 @@ exports.onCreateWebpackConfig = ({ actions, getConfig }) => { rules: [ { test: /\.md$/, - loaders: ['html-loader', 'markdown-loader'], + use: ['html-loader', 'markdown-loader'], }, { test: /\.html$/, @@ -34,3 +34,46 @@ exports.onCreateWebpackConfig = ({ actions, getConfig }) => { }); } }; + +exports.createPages = ({ actions }) => { + const { createRedirect } = actions; + + // Community index + createRedirect({ + fromPath: '/community/components', + toPath: '/community/component-index', + isPermanent: true, + }); + createRedirect({ + fromPath: '/community/contribute-a-component', + toPath: '/community/component-index', + isPermanent: true, + }); + + // Developing + createRedirect({ + fromPath: '/resources', + toPath: '/developing/developer-resources', + isPermanent: true, + }); + createRedirect({ + fromPath: '/tutorial/react/overview', + toPath: '/developing/react-tutorial/overview', + isPermanent: true, + }); + createRedirect({ + fromPath: '/tutorial/angular/overview', + toPath: '/developing/angular-tutorial/overview', + isPermanent: true, + }); + createRedirect({ + fromPath: '/tutorial/vue/overview', + toPath: '/developing/vue-tutorial/overview', + isPermanent: true, + }); + createRedirect({ + fromPath: '/guidelines/typography/styling-strategies', + toPath: '/guidelines/typography/style-strategies', + isPermanent: true, + }); +}; diff --git a/gatsby-ssr.js b/gatsby-ssr.js index e2223c71f2b..2c8cebab045 100644 --- a/gatsby-ssr.js +++ b/gatsby-ssr.js @@ -1,16 +1,45 @@ -/* eslint-disable import/prefer-default-export */ import React from 'react'; -import ogimage from './src/images/ogimage.png'; -export const onRenderBody = ({ setHeadComponents }) => { +export const onRenderBody = ({ setHeadComponents, setPostBodyComponents }) => { + const script = ` + if(!window) window = {}; + window.idaPageIsSPA = false; + window.digitalData = { + page: { + category: { + primaryCategory: 'DESIGN', + }, + pageInfo: { + ibm: { + siteID: 'CARBON_DESIGN_SYSTEM_WWW', + country: 'US', + industry: 'Design', + owner: 'carbon@us.ibm.com', + }, + }, + }, + }`; + setHeadComponents([ - , + , + , + , + , + , , - , + , { key="twitter:site" content="@_carbondesign" />, + , - - -``` - -Once you load `carbon-components.js` via ` + + + +``` + +These are the list of available components via CDN: + +- accordion.min.js +- breadcrumb.min.js +- button.min.js +- checkbox.min.js +- code-snippet.min.js +- combo-box.min.js +- content-switcher.min.js +- copy-button.min.js +- data-table.min.js +- date-picker.min.js +- dropdown.min.js +- file-uploader.min.js +- floating-menu.min.js +- form.min.js +- inline-loading.min.js +- input.min.js +- link.min.js +- list.min.js +- loading.min.js +- modal.min.js +- multi-select.min.js +- notification.min.js +- number-input.min.js +- overflow-menu.min.js +- pagination.min.js +- progress-indicator.min.js +- radio-button.min.js +- search.min.js +- select.min.js +- skeleton-placeholder.min.js +- skeleton-text.min.js +- skip-to-content.min.js +- slider.min.js +- structured-list.min.js +- tabs.min.js +- tag.min.js +- textarea.min.js +- tile.min.js +- toggle.min.js +- tooltip.min.js +- ui-shell.min.js + +To use the right-to-left (RTL) version of the artifacts, change the file +extention from `.min.js` to `.rtl.min.js`. For example: + +```html + + + + + +``` + +#### Basic usage + +The CDN artifacts define the custom elements for the browser, so they can be +directly used once the script tag has been added to the page. For example: + +```html + + + + + + + +
+ + Option 1 + Option 2 + Option 3 + Option 4 + Option 5 + +
+ + +``` + +Our example at [CodeSandbox](https://codesandbox.io) shows usage with only CDN +artifacts: + +[![Edit carbon-web-components](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/github/carbon-design-system/carbon-web-components/tree/main/examples/codesandbox/cdn) + +### Using ES imports + +#### How to install + To install `carbon-web-components` in your project, you will need to run the following command using [npm](https://www.npmjs.com/): @@ -73,11 +204,11 @@ instead: yarn add carbon-web-components carbon-components lit-html lit-element ``` -### Basic usage +#### Basic usage Our example at [CodeSandbox](https://codesandbox.io) shows the most basic usage: -[![Edit carbon-web-components](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/github/carbon-design-system/carbon-web-components/tree/master/examples/codesandbox/basic) +[![Edit carbon-web-components](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/github/carbon-design-system/carbon-web-components/tree/main/examples/codesandbox/basic) The first thing you need to do is **set up a module bundler** to resolve ECMAScript `import`s. The above example uses [Webpack](https://webpack.js.org) @@ -87,8 +218,7 @@ Once you set up a module bundler, you can start importing our component modules, for example: ```javascript -import 'carbon-web-components/es/components/dropdown/dropdown.js'; -import 'carbon-web-components/es/components/dropdown/dropdown-item.js'; +import 'carbon-web-components/es/components/dropdown/index.js'; ``` Once you've imported the component modules, you can use our components in the @@ -104,45 +234,6 @@ same manner as native HTML tags, for example: ``` -If you just want to try our components for demonstrations and so on, you can use -CDNs that support module mapping (for example, [JSPM](https://jspm.org)). With -CDNs, you can import just our modules in ` - - - -
- - Option 1 - Option 2 - Option 3 - Option 4 - Option 5 - -
- - -``` - ### List of available components View available web components diff --git a/src/pages/developing/get-started.mdx b/src/pages/developing/get-started.mdx index bf8523759eb..d0b853dc471 100644 --- a/src/pages/developing/get-started.mdx +++ b/src/pages/developing/get-started.mdx @@ -26,10 +26,11 @@ checklist of everything you need to get up and running. ### Install your framework of choice -The Carbon Design System is built React first. We also support core parts of the -system in vanilla JS, Angular, Vue, and Svelte and offer guidelines for other -frameworks. Head over to [Frameworks](/developing/frameworks/react) for all the -information you need to get started. +The Carbon Design System is built React first, with official support for Web +Components. We also support core parts of the system in vanilla JS, Angular, +Vue, and Svelte and offer guidelines for other frameworks. Head over to +[Frameworks](/developing/frameworks/react) for all the information you need to +get started. ### Check out our developer resources @@ -38,12 +39,11 @@ as well as our GitHub repos and Storybooks for your framework of choice. ## Additional guidance -### Take a tutorial, earn a badge +### Take a tutorial We offer tutorials in Angular, React, and Vue to guide you in creating an app with the Carbon Design System. We’ll teach you the ins and outs of using Carbon -components, and introduce web development best practices along the way. Everyone -who completes the tutorial will earn an IBM digital badge. +components, and introduce web development best practices along the way. diff --git a/src/pages/developing/react-tutorial/faq.mdx b/src/pages/developing/react-tutorial/faq.mdx new file mode 100644 index 00000000000..2db1ce72f1e --- /dev/null +++ b/src/pages/developing/react-tutorial/faq.mdx @@ -0,0 +1,78 @@ +--- +title: FAQs +description: + Welcome to Carbon! This tutorial will guide you in creating a React app with + the Carbon Design System. +tabs: + [ + 'Overview', + 'Step 1', + 'Step 2', + 'Step 3', + 'Step 4', + 'Step 5', + 'Wrapping up', + 'FAQ', + ] +--- + +### I am getting an error that says `failed to find manifest for cf`. What do I do? + +- The 5th step assumes your spaces are in the US South region. To successfully + deploy, you might need to update the region code (e.g. + `api.[REGION].cf.cloud.ibm.com`) to the region where your spaces were created, + or create a space in the US South region. + +- If you don't have an org, create one + [here](https://cloud.ibm.com/account/cloud-foundry). + - In the top nav go to Manage > Account > Account resources > Cloud Foundry + orgs + - The name you give it doesn't matter, just take note of the region you + select, and use that region's API endpoint (e.g. + `api.[REGION].cf.cloud.ibm.com`) + - Find regions and endpoints + [here](https://cloud.ibm.com/docs/cloud-foundry-public?topic=cloud-foundry-public-endpoints). + +### I am getting an error that says `yarn lockfile missing`. How do I fix this? + +- This error can occur when the `yarn.lock` file is either missing or differs + from the one used in the tutorial step. To fix this, you can go to the Github + branch for the step you are on, find the `yarn.lock` file, and copy that file + into your working directory. You may need to delete your `node_modules` folder + and run `yarn` afterwards. + +### I am getting a `yarn offline cache` error. How do I fix this? + +- Try running + `rm -rf .yarn-offline-mirror node_modules && yarn cache clean && yarn install` + and push up any changes. If this still does not work, ensure your `yarn.lock` + file matches the one at the start of the tutorial step + +### When will my PR be reviewed? + +- If your PR is passing, it will automatically get approved and closed by a bot. + After it's closed, you can move on to the next step. + +- If your PR is failing, try out the troubleshooting tips on this page first to + fix it. If it's still failing, reach out for help in our slack channel + `#carbon-react` or tag `@carbon-design-system/developers` in a comment on your + PR for help. + +### How can I show others my completion status? + +- Proof of your completion of the tutorial can be seen by filtering the PR list + to show your five PRs with the `status: approved` label. + +- You can filter the pull request list to show only pull requests authored by + your username. Replace `YOURUSERNAMEHERE` with your username in the following + link: + + - https://github.com/carbon-design-system/carbon-tutorial/pulls?q=author%3AYOURUSERNAMEHERE + +### Other troubleshooting tips + +- We updated the `react-scripts` dependency to `v5.0.1`. Pull from `upstream` + and run `yarn` or `npm install` to update your remote branch. +- You no longer need the `.env` with the updated `react-scripts` dependency. If + you are up to date, you can delete that file (previously at the root level). +- Run `yarn format` and commit any changes made. diff --git a/src/pages/developing/react-tutorial/overview.mdx b/src/pages/developing/react-tutorial/overview.mdx index 914f694f83a..9d040077b64 100644 --- a/src/pages/developing/react-tutorial/overview.mdx +++ b/src/pages/developing/react-tutorial/overview.mdx @@ -4,7 +4,16 @@ description: Welcome to Carbon! This tutorial will guide you in creating a React app with the Carbon Design System. tabs: - ['Overview', 'Step 1', 'Step 2', 'Step 3', 'Step 4', 'Step 5', 'Wrapping up'] + [ + 'Overview', + 'Step 1', + 'Step 2', + 'Step 3', + 'Step 4', + 'Step 5', + 'Wrapping up', + 'FAQ', + ] --- import Preview from 'components/Preview'; diff --git a/src/pages/developing/react-tutorial/step-1.mdx b/src/pages/developing/react-tutorial/step-1.mdx index 4d314feb99a..cf8215986b9 100644 --- a/src/pages/developing/react-tutorial/step-1.mdx +++ b/src/pages/developing/react-tutorial/step-1.mdx @@ -4,7 +4,16 @@ description: Welcome to Carbon! This tutorial will guide you in creating a React app with the Carbon Design System. tabs: - ['Overview', 'Step 1', 'Step 2', 'Step 3', 'Step 4', 'Step 5', 'Wrapping up'] + [ + 'Overview', + 'Step 1', + 'Step 2', + 'Step 3', + 'Step 4', + 'Step 5', + 'Wrapping up', + 'FAQ', + ] --- import Preview from 'components/Preview'; @@ -32,13 +41,13 @@ navigate between pages. ## Preview -A [preview](https://react-step-2--carbon-tutorial.netlify.com) of what you will -build: +A [preview](https://v11-react-step-2--carbon-tutorial.netlify.com) of what you +will build: ```html path=src/App.js
- Hello Carbon! Well, not quite yet. This is the starting point for the Carbon tutorial. + Hello Carbon! Well, not quite yet. This is the starting point for the Carbon + tutorial.
``` - with: - -```html path=src/App.js +```jsx path=src/App.js ``` - Congratulations, you've imported your first component! You should see a Carbon styled button on the page. @@ -249,7 +241,7 @@ Next, in `app.scss`, we'll import our `TutorialHeader` styles. Your file should now look like this: ```scss path=src/app.scss -@import './components/TutorialHeader/tutorial-header.scss'; +@use './components/TutorialHeader/tutorial-header'; ``` ### Import and export the header @@ -280,7 +272,7 @@ import { SideNav, SideNavItems, HeaderSideNavItems, -} from 'carbon-components-react'; +} from '@carbon/react'; const TutorialHeader = () => ( ( + isPersistent={false} + > Repositories @@ -319,9 +312,9 @@ export default TutorialHeader; -**Note:** you can find a description of the different components used UI Shell -in our -[carbon-components-react](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/UIShell) +**Note:** you can find a description of the different components used in the UI +Shell in our +[@carbon/react](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/UIShell) package. @@ -336,16 +329,11 @@ straight to the main content. ### Import icons -Now let's import the icons from our `@carbon/icons-react` elements package. In -the `TutorialHeader.js` file, we need to import each individual icon we will -use. +Now let's import the icons. In the `TutorialHeader.js` file, we need to import +each individual icon we will use. ```javascript path=src/components/TutorialHeader/TutorialHeader.js -import { - AppSwitcher20, - Notification20, - UserAvatar20, -} from '@carbon/icons-react'; +import { Switcher, Notification, UserAvatar } from '@carbon/react/icons'; ``` Then we need to add the `HeaderGlobalAction` component inside of the @@ -358,16 +346,16 @@ header a user can make. Replace: With: -```html path=src/components/TutorialHeader/TutorialHeader.js +```jsx path=src/components/TutorialHeader/TutorialHeader.js - - + + - - + + - - + + ``` @@ -380,7 +368,7 @@ Next we'll render our UI Shell by importing our `TutorialHeader` component and ```javascript path=src/App.js import React, { Component } from 'react'; import './app.scss'; -import { Button, Content } from 'carbon-components-react'; +import { Button, Content } from '@carbon/react'; import TutorialHeader from './components/TutorialHeader'; ``` @@ -444,9 +432,9 @@ src/content/RepoPage Next, we'll import our content Sass files in `app.scss`, like so: ```scss path=src/app.scss -@import './components/TutorialHeader/tutorial-header.scss'; -@import './content/LandingPage/landing-page.scss'; -@import './content/RepoPage/repo-page.scss'; +@use './components/TutorialHeader/tutorial-header'; +@use './content/LandingPage/landing-page'; +@use './content/RepoPage/repo-page'; ``` ### Import and export content pages @@ -553,14 +541,12 @@ the Button import). Now inside `Content` we'll add the following: - -```html path=src/App.js +```jsx path=src/App.js ``` - After that we need to do a couple quick fixes to the UI Shell to have it work with the React router. @@ -591,7 +577,64 @@ Do the same with the components that contain `href="/repos"`, updating them to: ``` You should now have a working header that routes to different pages without full -page reload! +page reload! However, our page does not match the design specs. We need to +change the header theme to `g100` to match the specs. + +In `App.js` we will add inline theming for our navigation. First, we need to +import our new `Theme` component. + +```javascript path=src/App.js +import { Content, Theme } from '@carbon/react'; +``` + +Then, we will wrap `Theme` around our header, and set the zoned theme using the +`theme` prop, which accepts one of four strings: `"white"`, `"g10"`, `"g90"` or +`"g100"`. + +```javascript path=src/App.js +<> + + + + + + + + + + +``` + +You might have noticed that the landing and repo page content disappeared. This +is because we now have a wrapper around the UI Shell, and the spacing is off. To +fix this, we'll add the following override in `index.scss` below our style +import: + +```scss path=src/index.scss +.cds--content { + margin-top: 3rem; +} +``` + +We have one last thing to fix before we're done. Because we changed the header +theme to dark, the `` tooltips are now light instead of +dark, and when you scroll the page, it blends into the content. To fix this, +we'll add some overriding styles in `_tutorial-header.scss`: + +```scss path=src/components/TutorialHeader/_tutorial-header.scss +@use '@carbon/react/scss/colors'; + +// overriding header tooltip bg color +// because the navigation is dark themed while the content is white +// which means the dark theme tooltip bg blends into the white content bg +.cds--header__global .cds--popover-content { + background-color: colors.$gray-20; +} + +.cds--header__global .cds--popover-caret { + background-color: colors.$gray-20; +} +``` ## Submit pull request @@ -629,18 +672,18 @@ git add --all && git commit -m "feat(tutorial): complete step 1" -**Note:** You'll notice that your commit includes binaries in the -`.yarn-offline-mirror` folder. That's expected as the repository is configured -to run [Yarn offline](https://yarnpkg.com/blog/2016/11/24/offline-mirror) for -more reliable builds. Future tutorial steps that don't install new packages -won't have `.yarn-offline-mirror` commit changes. +**Note:** You'll notice that your commit includes binaries in the `.yarn/cache` +folder. That's expected as the repository is configured to run +[Yarn offline](https://yarnpkg.com/blog/2016/11/24/offline-mirror) for more +reliable builds. Future tutorial steps that don't install new packages won't +have `.yarn/cache` commit changes. Then, push to your repository: ```bash -git push origin react-step-1 +git push origin v11-react-step-1 ``` @@ -660,8 +703,8 @@ over HTTPS. **Note:** If you receive a `non-fast-forward` error, it's likely that your forked repository is behind the original repository and needs to be updated. This can happen if the tutorial was updated after you began working on it. To -fix, run `git pull upstream react-step-1` to merge the changes into your branch, -then you can try pushing again. Or, you can +fix, run `git pull upstream v11-react-step-1` to merge the changes into your +branch, then you can try pushing again. Or, you can [manually merge](https://help.github.com/en/articles/syncing-a-fork) in the upstream changes. @@ -672,7 +715,7 @@ upstream changes. Finally, visit [carbon-tutorial](https://github.com/carbon-design-system/carbon-tutorial) to "Compare & pull request". In doing so, make sure that you are comparing to -`react-step-1` into `base: react-step-1`. Take notice of the +`v11-react-step-1` into `base: v11-react-step-1`. Take notice of the [Netlify](https://www.netlify.com) bot that deploys a preview of your PR every time that you push new commits. These previews can be shared and viewed by anybody to assist the PR review process. diff --git a/src/pages/developing/react-tutorial/step-2.mdx b/src/pages/developing/react-tutorial/step-2.mdx index 63199cd94d4..66578d0c461 100644 --- a/src/pages/developing/react-tutorial/step-2.mdx +++ b/src/pages/developing/react-tutorial/step-2.mdx @@ -4,7 +4,16 @@ description: Welcome to Carbon! This tutorial will guide you in creating a React app with the Carbon Design System. tabs: - ['Overview', 'Step 1', 'Step 2', 'Step 3', 'Step 4', 'Step 5', 'Wrapping up'] + [ + 'Overview', + 'Step 1', + 'Step 2', + 'Step 3', + 'Step 4', + 'Step 5', + 'Wrapping up', + 'FAQ', + ] --- import Preview from 'components/Preview'; @@ -20,7 +29,6 @@ Carbon components. Fork, clone and branch -Install grid Add landing page grid Build landing page Style landing page @@ -39,11 +47,11 @@ build: ## Fork, clone and branch @@ -62,7 +70,7 @@ step's starting point. ```bash git fetch upstream -git checkout -b react-step-2 upstream/react-step-2 +git checkout -b v11-react-step-2 upstream/v11-react-step-2 ``` @@ -95,7 +103,7 @@ You should see something similar to where the Before we get started with this step, we'll be adding some components that require IE11 polyfills. As shown in the -[Carbon React documentation](https://github.com/carbon-design-system/carbon/blob/main/packages/react/.storybook/polyfills.js), +[Carbon React documentation](https://github.com/carbon-design-system/carbon/blob/v10/packages/react/.storybook/polyfills.js), go ahead and add these imports to the top of the root `index.js`. They aren't all needed, but we'll add them all to play it safe for the duration of the tutorial. @@ -117,46 +125,18 @@ dependency. -## Install grid - -In our last step we added our styles, component and icon packages. Now that -we're building the pages with grid, we need to install one more Carbon package. -Stop your development environment (`CTRL-C`) and: - -```bash -yarn add @carbon/grid@10.17.0 -``` - -In `index.scss`, we need to configure our grid to use 16 columns instead of the -default 12 columns. We do this by adding `grid-columns-16: true` in our -`$feature-flags`. - -```scss path=src/index.scss -$feature-flags: ( - grid-columns-16: true, -); -``` - - - -**Note:** The feature flag needs to come before the Carbon `styles.scss` import. - - - -Run `yarn start` so we can begin building. - ## Add landing page grid Let's add our grid elements to `LandingPage.js`. -In order to use the grid, we need to wrap everything in a -`
`. We can continue to make rows by adding a -`
` inside the grid, as well as make columns within -those rows by adding `
`. +In order to use the grid, we need to wrap everything in a ``. Because +we're building with the new CSS Grid, we won't be using typical rows. We'll use +a combination of `` and nested subgrids to create our layout. -Our column sizes are specified by the number of columns they'll be spanning. If -we use `bx--col-lg-4`, it means it'll span 4 of the 16 columns. If we use -`bx--col-lg-8` it means it'll span 8 of the 16 columns, and so on. +The CSS Grid is a 16 column grid. We will specify the span of a `` using +the `sm`, `md`, and `lg` props. For example, `` +means the column will span 2/4 columns at the small breakpoint, 8/8 columns at +the medium breakpoint, 8/16 columns at the large breakpoint. We've included the designs for this tutorial app in the `design.sketch` file found as a top-level file in the `carbon-tutorial` repository. But, if you don't @@ -173,6 +153,12 @@ screenshots. +First, we need to import our grid components at the top of `LandingPage.js`: + +```javascript path=src/content/LandingPage/LandingPage.js +import { Grid, Column } from '@carbon/react'; +``` + We'll break this down into three rows. The first row with the gray background doesn't appear to need any columns. The second row with the white background looks like it has two columns of different widths. The third row with the gray @@ -180,36 +166,46 @@ background looks like it has four columns of equal width. We'll make rows like so: -```javascript path=src/content/LandingPage/LandingPage.js +```jsx path=src/content/LandingPage/LandingPage.js return ( -
-
-
1
-
-
-
7/16
-
8/16
-
-
-
1/4
-
1/4
-
1/4
-
1/4
-
-
+ + + 1 + + + + + 7/16 + + + 8/16 + + + + + + + 1/4 + + + 1/4 + + + 1/4 + + + 1/4 + + + + ); ``` -We added a class of `bx--grid--full-width` to the grid container since our rows -need to expand the whole page without any margins. We also added some custom -classes like `landing-page`, `landing-page__banner`, `landing-page__r2`, etc., -which we will use later. - -Also, take notice of the second row. The tab content only covers 7 columns at -this large viewport to prevent overly-large line lengths, so we needed to add a -1 column offset `bx--offset-lg-1` to second column to fill the full 16 columns -in the grid. Then, both of those columns have `bx--col-md-4` classes so they are -of equal width at medium-sized viewports. +We added a prop of `fullWidth` to the main grid container since our rows need to +expand the whole page without any margins. We also added some custom classes +like `landing-page`, `landing-page__banner`, `landing-page__r2`, etc., which we +will use later. ## Build landing page @@ -217,28 +213,26 @@ We'll start adding HTML elements and components by row. ### First row -In our first row we'll need a `BreadCrumb` component. First, let's import the +In our first row we'll need a `Breadcrumb` component. First, let's import the components we need. Because we'll be importing several components for this page, -we'll import them directly from the `carbon-components-react` package instead of -the direct path for each one. +we'll import them directly from the `@carbon/react` package instead of the +direct path for each one. ```javascript path=src/content/LandingPage/LandingPage.js -import { Breadcrumb, BreadcrumbItem } from 'carbon-components-react'; +import { Breadcrumb, BreadcrumbItem, Grid, Column } from '@carbon/react'; ``` We can now add our component to the first row, along with a header, like so: -```html path=src/content/LandingPage/LandingPage.js -
-
- - - Getting started - - -

Design & build with Carbon

-
-
+```jsx path=src/content/LandingPage/LandingPage.js + + + + Getting started + + +

Design & build with Carbon

+ ``` You may notice that the styles look off. Don't worry, we'll fix these later. @@ -246,7 +240,7 @@ You may notice that the styles look off. Don't worry, we'll fix these later. ### Second row In our second row we'll need `Tabs` and `Button` components. We'll update the -`carbon-components-react` import to: +`@carbon/react` import to: ```javascript path=src/content/LandingPage/LandingPage.js import { @@ -255,116 +249,126 @@ import { Button, Tabs, Tab, -} from 'carbon-components-react'; + TabList, + TabPanels, + TabPanel, + Grid, + Column, +} from '@carbon/react'; ``` -Before we can render the tabs, we need to add some props for the component after -the import. These example props came from the -[React Tabs Story](http://react.carbondesignsystem.com/?selectedKind=Tabs) in -Storybook. - -```javascript path=src/content/LandingPage/LandingPage.js -const props = { - tabs: { - selected: 0, - role: 'navigation', - }, - tab: { - role: 'presentation', - tabIndex: 0, - }, -}; -``` - -Modify the second row to use the `Tab` component. - -```html path=src/content/LandingPage/LandingPage.js -
-
- - -
-
-
7/16
-
- 8/16 -
-
-
- - -
-
-
- Rapidly build beautiful and accessible experiences. The Carbon kit - contains all resources you need to get started. -
-
-
- - -
-
-
- Carbon provides styles and components in Vanilla, React, Angular, - and Vue for anyone building on the web. -
-
-
- - -
-
-``` +Modify the second row to use the `Tabs` components. **Note:** We're using the grid for the page layout, but we also need to apply the grid within the tab content. When doing so, make sure the nested grid has -the expected `grid` > `row` > `col` DOM structure. +the expected `Grid` > `Column` DOM structure. Nested grids are officially +supported with our CSS Grid. If you are using `FlexGrid`, subgrid is not +supported. -Hold up! If you were to run -[DAP](https://www.ibm.com/able/dynamic-assessment-plug-in.html) to check for +```jsx path=src/content/LandingPage/LandingPage.js + + + + About + Design + Develop + + + + + +

What is Carbon?

+

+ Carbon is IBM’s open-source design system for digital products and + experiences. With the IBM Design Language as its foundation, the + system consists of working code, design tools and resources, human + interface guidelines, and a vibrant community of contributors. +

+ + + + IMAGE WILL GO HERE + + + + + + + Rapidly build beautiful and accessible experiences. The Carbon kit + contains all resources you need to get started. + + + + + + + Carbon provides styles and components in Vanilla, React, Angular, + and Vue for anyone building on the web. + + + + + + +``` + +The `` is the tab navigation, and the `` contains each tab +content. You'll notice that within each ``, we nested another `` +and ``. This is because the parent column +`` is acting as a +faux row, and each tab within that row contains the actual column content. When +nesting columns, you must always wrap the nested group within another ``. + +Hold up! If you were to run the +[Equal Access Toolkit](https://www.ibm.com/able/toolkit) to check for accessibility violations, you'd see `Multiple navigation landmarks must have unique labels specified with aria-label or aria-labelledby` because both the `Breadcrumb` and `Tabs` components use `