diff --git a/.assets/powered-by-vercel.svg b/.assets/powered-by-vercel.svg deleted file mode 100644 index a7528066..00000000 --- a/.assets/powered-by-vercel.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cf586828..9b759e9c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,52 +1,81 @@ # Contributing +Note: before submitting a pull request (PR), it is recommended to first [file an issue](https://github.com/IBM/carbon-components-svelte/issues). + ## Prerequisites -This project uses Node.js and Yarn. +This project requires Node.js (version 12 or greater) and Yarn (version 1 or greater). -- [Node.js](https://nodejs.org/en/download/package-manager/#macos) (version >=12) -- [Yarn](https://yarnpkg.com/en/docs/install#mac-stable) +- [Node.js](https://nodejs.org/en/download/package-manager/) +- [Yarn](https://classic.yarnpkg.com/en/docs/install) -## Fork and Clone +## Project set-up Fork the repo and clone your fork: -```bash +```sh git clone cd carbon-components-svelte ``` -Set the original repo as the upstream: +Set the original repository as the upstream: -```bash +```sh git remote add upstream git@github.com:IBM/carbon-components-svelte.git # verify that the upstream is added git remote -v ``` -## Install +### Install Install the project dependencies: -```bash +```sh +# carbon-components-svelte/ yarn install ``` ---- +## Documentation set-up -## Workflow +Component documentation is located in the `docs` folder. The website is built using svite, routify, and MDsveX. You will need to create a symbolic project link in order to see live changes reflected when developing locally. -### Develop +First, create a symbolic link at the root of the project folder: -This project uses Storybook for UI development and "live" documentation. - -Run the following command to start the Storybook: - -```bash -yarn start +```sh +# carbon-components-svelte/ +yarn link ``` -#### Component Format +Go into the `docs` folder: + +```sh +cd docs +``` + +Link `"carbon-components-svelte"`: + +```sh +yarn link "carbon-components-svelte" +yarn install +``` + +If linked correctly, any change to a component in the `src` folder should be reflected in the `docs` site. + +--- + +## Development workflow + +Preview changes to components from the `src` folder in the documentation website located in `docs/`. + +In the `docs` folder, run: + +```sh +yarn dev +``` + +The site should be served at `http://localhost:3000/` (or the next available port). + +### Component Format Each component should adopt the following structure: @@ -55,27 +84,55 @@ src/Component │ └───Component.svelte // main component └───Component.Skeleton.svelte // Skeleton component (if any) -└───Component.Story.svelte // wrapper for individual stories -└───Component.stories.js // Storybook stories └───index.js // export components (e.g. `Component.svelte`, `Component.Skeleton.svelte`) ``` +### Editing a component + +If adding or editing an exported component prop, be sure to annotate its value using [JSDoc](https://jsdoc.app/) conventions. + +```js +/** + * Set to `true` to disable the tab + * @type {boolean} [disabled=false] + */ +export let disabled = false; +``` + +### Creating a component + +First, [submit an issue](https://github.com/IBM/carbon-components-svelte/issues). + +If creating a new component, don't forget it from `src/index.js`: + +```diff +export { CopyButton } from "./CopyButton"; +export { ComboBox } from "./ComboBox"; ++ export { FixedComboBox } from "./FixedComboBox"; +export { + ComposedModal, + ModalHeader, + ModalBody, + ModalFooter, +} from "./ComposedModal"; +``` + ### Build -#### Component Library +Verify that you can build the library by running the following command at the project root: -To build the component library, run `yarn build`. +```sh +# carbon-components-svelte/ +yarn prepack +``` -The library should be compiled in two formats: +This does several things: -- **ES**: `lib/index.mjs` -- **UMD**: `lib/index.js` - -#### Storybook - -To build the Storybook, run `yarn build`. - -The Storybook should be outputted to the `storybook-static` folder. +- uses `node-sass` to pre-compile CSS StyleSheets in the `css` folder +- uses Rollup to bundle the Svelte components in `src` in ESM/UMD formats; emitted to `lib` +- uses a Rollup plugin to: + - generate component documentation in Markdown format (`COMPONENT_INDEX.md`) + - generate TypeScript definitions (`types/index.d.ts`) ## Submit a Pull Request @@ -83,7 +140,7 @@ The Storybook should be outputted to the `storybook-static` folder. Before submitting a pull request, make sure your fork is up to date with the latest upstream changes. -```bash +```sh git fetch upstream git checkout master git merge upstream/master diff --git a/README.md b/README.md index 9d250359..d2278ea8 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![NPM][npm]][npm-url] [![Build][build]][build-badge] -Deploys by Vercel +Deploys by Vercel ## [Documentation](http://ibm.biz/carbon-svelte) diff --git a/docs/package.json b/docs/package.json index 94eb08e7..8ffcc4d0 100644 --- a/docs/package.json +++ b/docs/package.json @@ -16,7 +16,8 @@ "fs-extra": "^9.0.1", "mdsvex": "^0.8.8", "npm-run-all": "^4.1.5", - "playwright": "^1.4.2", + "playwright-aws-lambda": "^0.6.0", + "playwright-core": "^1.4.2", "polka": "^0.5.2", "prettier": "^2.1.2", "prettier-plugin-svelte": "^1.4.0", diff --git a/docs/scripts/postbuild.js b/docs/scripts/postbuild.js index b6b49b45..69b3bcd5 100644 --- a/docs/scripts/postbuild.js +++ b/docs/scripts/postbuild.js @@ -1,6 +1,6 @@ const sirv = require("sirv"); const polka = require("polka"); -const { chromium } = require("playwright"); +const playwright = require("playwright-aws-lambda"); const fs = require("fs-extra"); const path = require("path"); @@ -41,7 +41,7 @@ const app = polka() process.exit(1); } - const browser = await chromium.launch(); + const browser = await playwright.launchChromium({ headless: true }); const context = await browser.newContext(); const page = await context.newPage(); diff --git a/docs/yarn.lock b/docs/yarn.lock index a6e6e7fd..95abe922 100644 --- a/docs/yarn.lock +++ b/docs/yarn.lock @@ -548,6 +548,11 @@ balanced-match@^1.0.0: resolved "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.0.tgz#89b4d199ab2bee49de164ea02b89ce462d71b767" integrity sha1-ibTRmasr7kneFk6gK4nORi1xt2c= +base64-js@^1.0.2: + version "1.3.1" + resolved "https://registry.npmjs.org/base64-js/-/base64-js-1.3.1.tgz#58ece8cb75dd07e71ed08c736abc5fac4dbf8df1" + integrity sha512-mLQ4i2QO1ytvGWFWmcngKO//JXAQueZvwEKtjgQFM4jIK0kU+ytMfplL8j+n5mspOfjHwoAg+9yhb7BwAHm36g== + bcrypt-pbkdf@^1.0.0: version "1.0.2" resolved "https://registry.npmjs.org/bcrypt-pbkdf/-/bcrypt-pbkdf-1.0.2.tgz#a4301d389b6a43f9b67ff3ca11a3f6637e360e9e" @@ -565,6 +570,15 @@ binary-extensions@^2.0.0: resolved "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.1.0.tgz#30fa40c9e7fe07dbc895678cd287024dea241dd9" integrity sha512-1Yj8h9Q+QDF5FzhMs/c9+6UntbD5MkRfRwac8DoEm9ZfUBZ7tZ55YcGVAzEe4bXsdQHEk+s9S5wsOKVdZrw0tQ== +bl@^4.0.3: + version "4.0.3" + resolved "https://registry.npmjs.org/bl/-/bl-4.0.3.tgz#12d6287adc29080e22a705e5764b2a9522cdc489" + integrity sha512-fs4G6/Hu4/EE+F75J8DuN/0IpQqNjAdC7aEQv7Qt8MHGUH7Ckv2MwTEEeN9QehD0pfIDkMI1bkHYkKy7xHyKIg== + dependencies: + buffer "^5.5.0" + inherits "^2.0.4" + readable-stream "^3.4.0" + bluebird@^3.7.2: version "3.7.2" resolved "https://registry.npmjs.org/bluebird/-/bluebird-3.7.2.tgz#9f229c15be272454ffa973ace0dbee79a1b0c36f" @@ -623,6 +637,14 @@ buffer-from@^1.0.0: resolved "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.1.tgz#32713bc028f75c02fdb710d7c7bcec1f2c6070ef" integrity sha512-MQcXEUbCKtEo7bhqEs6560Hyd4XaovZlO/k9V3hjVUF/zwW7KBVdSK4gIt/bzwS9MbR5qob+F5jusZsb0YQK2A== +buffer@^5.5.0: + version "5.6.0" + resolved "https://registry.npmjs.org/buffer/-/buffer-5.6.0.tgz#a31749dc7d81d84db08abf937b6b8c4033f62786" + integrity sha512-/gDYp/UtU0eA1ys8bOs9J6a+E/KWIY+DZ+Q2WESNUA0jFRsJOc0SNUO6xJ5SGA1xueg3NL65W6s+NY5l9cunuw== + dependencies: + base64-js "^1.0.2" + ieee754 "^1.1.4" + bufferutil@^4.0.1: version "4.0.1" resolved "https://registry.npmjs.org/bufferutil/-/bufferutil-4.0.1.tgz#3a177e8e5819a1243fe16b63a199951a7ad8d4a7" @@ -738,6 +760,11 @@ chokidar@^3.0.0, chokidar@^3.3.1: optionalDependencies: fsevents "~2.1.2" +chownr@^1.1.1: + version "1.1.4" + resolved "https://registry.npmjs.org/chownr/-/chownr-1.1.4.tgz#6fc9d7b42d32a583596337666e7d08084da2cc6b" + integrity sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg== + clean-css@^4.2.3: version "4.2.3" resolved "https://registry.npmjs.org/clean-css/-/clean-css-4.2.3.tgz#507b5de7d97b48ee53d84adb0160ff6216380f78" @@ -1142,7 +1169,7 @@ encodeurl@^1.0.2, encodeurl@~1.0.2: resolved "https://registry.npmjs.org/encodeurl/-/encodeurl-1.0.2.tgz#ad3ff4c86ec2d029322f5a02c3a9a606c95b3f59" integrity sha1-rT/0yG7C0CkyL1oCw6mmBslbP1k= -end-of-stream@^1.1.0: +end-of-stream@^1.1.0, end-of-stream@^1.4.1: version "1.4.4" resolved "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.4.tgz#5ae64a5f45057baf3626ec14da0ca5e4b2431eb0" integrity sha512-+uw1inIHVPQoaVuHzRyXd21icM+cnt4CzD5rW+NC1wjOUSTOs+Te7FOv7AhN7vS9x/oIyhLP5PR1H+phQAHu5Q== @@ -1488,6 +1515,11 @@ fresh@0.5.2, fresh@~0.5.2: resolved "https://registry.npmjs.org/fresh/-/fresh-0.5.2.tgz#3d8cadd90d976569fa835ab1f8e4b23a105605a7" integrity sha1-PYyt2Q2XZWn6g1qx+OSyOhBWBac= +fs-constants@^1.0.0: + version "1.0.0" + resolved "https://registry.npmjs.org/fs-constants/-/fs-constants-1.0.0.tgz#6be0de9be998ce16af8afc24497b9ee9b7ccd9ad" + integrity sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow== + fs-extra@^9.0.0, fs-extra@^9.0.1: version "9.0.1" resolved "https://registry.npmjs.org/fs-extra/-/fs-extra-9.0.1.tgz#910da0062437ba4c39fedd863f1675ccfefcb9fc" @@ -1750,6 +1782,11 @@ icss-utils@^4.0.0, icss-utils@^4.1.1: dependencies: postcss "^7.0.14" +ieee754@^1.1.4: + version "1.1.13" + resolved "https://registry.npmjs.org/ieee754/-/ieee754-1.1.13.tgz#ec168558e95aa181fd87d37f55c32bbcb6708b84" + integrity sha512-4vf7I2LYV/HaWerSo3XmlMkp5eZ83i+/CDluXi/IGTs/O1sejBNhTtnxzmRZfvOUqj7lZjqHkeTvpgSFDlWZTg== + ignore@^5.1.4: version "5.1.8" resolved "https://registry.npmjs.org/ignore/-/ignore-5.1.8.tgz#f150a8b50a34289b33e22f5889abd4d8016f0e57" @@ -1790,7 +1827,7 @@ inflight@^1.0.4: once "^1.3.0" wrappy "1" -inherits@2, inherits@2.0.4: +inherits@2, inherits@2.0.4, inherits@^2.0.3, inherits@^2.0.4: version "2.0.4" resolved "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz#0fa2c64f932917c3433a0ded55363aae37416b7c" integrity sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ== @@ -2164,6 +2201,13 @@ koa@^2.11.0: type-is "^1.6.16" vary "^1.1.2" +lambdafs@^1.3.0: + version "1.3.0" + resolved "https://registry.npmjs.org/lambdafs/-/lambdafs-1.3.0.tgz#7e369cedc9a09623bb365fa99a1113c2ab2fc7ae" + integrity sha512-HqRPmEgtkTW4sCYDUjTEuTGkjCHuLvtZU8iM8GkhD7SpjW4AJJbBk86YU4K43sWGuW5Vmzp1lVCx4ab/kJsuBw== + dependencies: + tar-fs "^2.0.0" + levn@~0.3.0: version "0.3.0" resolved "https://registry.npmjs.org/levn/-/levn-0.3.0.tgz#3b09924edf9f083c0490fdd4c0bc4421e04764ee" @@ -2351,6 +2395,11 @@ minimist@^1.2.0, minimist@^1.2.5: resolved "https://registry.npmjs.org/minimist/-/minimist-1.2.5.tgz#67d66014b66a6a8aaa0c083c5fd58df4e4e97602" integrity sha512-FM9nNUYrRBAELZQT3xeZQ7fmMOBg6nWNmJKTcgsJeaLstP/UODVpGsr5OhXhhXg6f+qtJ8uiZ+PUxkDWcgIXLw== +mkdirp-classic@^0.5.2: + version "0.5.3" + resolved "https://registry.npmjs.org/mkdirp-classic/-/mkdirp-classic-0.5.3.tgz#fa10c9115cc6d8865be221ba47ee9bed78601113" + integrity sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A== + ms@2.0.0: version "2.0.0" resolved "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz#5608aeadfc00be6c2901df5f9861788de0d597c8" @@ -2684,10 +2733,17 @@ pify@^3.0.0: resolved "https://registry.npmjs.org/pify/-/pify-3.0.0.tgz#e5a4acd2c101fdf3d9a4d07f0dbc4db49dd28176" integrity sha1-5aSs0sEB/fPZpNB/DbxNtJ3SgXY= -playwright@^1.4.2: +playwright-aws-lambda@^0.6.0: + version "0.6.0" + resolved "https://registry.npmjs.org/playwright-aws-lambda/-/playwright-aws-lambda-0.6.0.tgz#3ce1db2011384a92740a557dc6b7deb277560cbb" + integrity sha512-lu3XYrI0NDMZ4P9pZBEDSnuwVl7EQKtSRPioGQbSoG3c8hJt71H5EynaBGjXVDdgeRz9HPgwajHv3Ed7kW59Jw== + dependencies: + lambdafs "^1.3.0" + +playwright-core@^1.4.2: version "1.4.2" - resolved "https://registry.npmjs.org/playwright/-/playwright-1.4.2.tgz#84dac641ff7af9f465e367e01fde8a8f1cc274bf" - integrity sha512-qiQHrhU4JBxup9JoGZff6hdFL2VrD+ae5QLELGHwRq/vYNQFeJF10Z3ENnQ6hWJmG+YnpfzgoBvX+cUg4WHwTw== + resolved "https://registry.npmjs.org/playwright-core/-/playwright-core-1.4.2.tgz#e364c06d5fc4a0a4289a7a93ad994de723e0575f" + integrity sha512-YXDhBti5hADm8daZ2Js4vmAIqhIW4fwXI6aXrY4JlbLy+OacdDInkcxqKc56RQxGNFH6hwylrwe7hdBifLp4MA== dependencies: debug "^4.1.1" extract-zip "^2.0.1" @@ -2943,6 +2999,15 @@ read-pkg@^3.0.0: normalize-package-data "^2.3.2" path-type "^3.0.0" +readable-stream@^3.1.1, readable-stream@^3.4.0: + version "3.6.0" + resolved "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.0.tgz#337bbda3adc0706bd3e024426a286d4b4b2c9198" + integrity sha512-BViHy7LKeTz4oNnkcLJ+lVSL6vpiFeX6/d3oSH8zCW7UxP2onchk+vTGB143xuFjHS3deTgkKoXXymXqymiIdA== + dependencies: + inherits "^2.0.3" + string_decoder "^1.1.1" + util-deprecate "^1.0.1" + readdirp@^3.3.0, readdirp@~3.4.0: version "3.4.0" resolved "https://registry.npmjs.org/readdirp/-/readdirp-3.4.0.tgz#9fdccdf9e9155805449221ac645e8303ab5b9ada" @@ -3151,7 +3216,7 @@ safe-buffer@5.1.2, safe-buffer@~5.1.1: resolved "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz#991ec69d296e0313747d59bdfd2b745c35f8828d" integrity sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g== -safe-buffer@^5.0.1, safe-buffer@^5.1.0, safe-buffer@^5.1.2: +safe-buffer@^5.0.1, safe-buffer@^5.1.0, safe-buffer@^5.1.2, safe-buffer@~5.2.0: version "5.2.1" resolved "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz#1eaf9fa9bdb1fdd4ec75f58f9cdb4e6b7827eec6" integrity sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ== @@ -3411,6 +3476,13 @@ string.prototype.trimstart@^1.0.1: define-properties "^1.1.3" es-abstract "^1.17.5" +string_decoder@^1.1.1: + version "1.3.0" + resolved "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz#42f114594a46cf1a8e30b0a84f56c78c3edac21e" + integrity sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA== + dependencies: + safe-buffer "~5.2.0" + strip-ansi@^6.0.0: version "6.0.0" resolved "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.0.tgz#0b1571dd7669ccd4f3e06e14ef1eed26225ae532" @@ -3504,6 +3576,27 @@ symbol-tree@^3.2.4: resolved "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz#430637d248ba77e078883951fb9aa0eed7c63fa2" integrity sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw== +tar-fs@^2.0.0: + version "2.1.0" + resolved "https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.0.tgz#d1cdd121ab465ee0eb9ccde2d35049d3f3daf0d5" + integrity sha512-9uW5iDvrIMCVpvasdFHW0wJPez0K4JnMZtsuIeDI7HyMGJNxmDZDOCQROr7lXyS+iL/QMpj07qcjGYTSdRFXUg== + dependencies: + chownr "^1.1.1" + mkdirp-classic "^0.5.2" + pump "^3.0.0" + tar-stream "^2.0.0" + +tar-stream@^2.0.0: + version "2.1.4" + resolved "https://registry.npmjs.org/tar-stream/-/tar-stream-2.1.4.tgz#c4fb1a11eb0da29b893a5b25476397ba2d053bfa" + integrity sha512-o3pS2zlG4gxr67GmFYBLlq+dM8gyRGUOvsrHclSkvtVtQbjV0s/+ZE8OpICbaj8clrX3tjeHngYGP7rweaBnuw== + dependencies: + bl "^4.0.3" + end-of-stream "^1.4.1" + fs-constants "^1.0.0" + inherits "^2.0.3" + readable-stream "^3.1.1" + terser@^4.6.2: version "4.8.0" resolved "https://registry.npmjs.org/terser/-/terser-4.8.0.tgz#63056343d7c70bb29f3af665865a46fe03a0df17" @@ -3675,7 +3768,7 @@ utf-8-validate@^5.0.2: dependencies: node-gyp-build "~3.7.0" -util-deprecate@^1.0.2: +util-deprecate@^1.0.1, util-deprecate@^1.0.2: version "1.0.2" resolved "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz#450d4dc9fa70de732762fbd2d4a28981419a0ccf" integrity sha1-RQ1Nyfpw3nMnYvvS1KKJgUGaDM8=