@carbon/vue 2.45.1 → 3.0.5-alpha.0

package/README.md

@@ -1,4 +1,4 @@
-# carbon-components-vue
+# @carbon/vue-3
 
 <p align="center">
   <a href="https://github.com/carbon-design-system/carbon/blob/master/LICENSE">
@@ -18,10 +18,6 @@
 > Vue implementation of the Carbon Design System
 > A collection of [Carbon Components](https://github.com/carbon-design-system/carbon-components) implemented using <img src="https://vuejs.org/images/logo.png" width="20" alt="Vue logo"> [Vue.js](https://vuejs.org/).
 
-<div style="text-align: center">
-  <img src="/docs/AtCarbonVue2.png" alt="@carbon/vue">
-</div>
-
 ## Carbon Vue library - A Carbon Community Project
 
 The [library](http://vue.carbondesignsystem.com/) provides front-end developers & engineers a collection of reusable Vue components to build websites and user interfaces. Adopting the library enables developers to use consistent markup, styles, and behavior in prototype and production work.
@@ -30,275 +26,49 @@ The [library](http://vue.carbondesignsystem.com/) provides front-end developers
 
 As a community project contributions are not only welcome, but essential for the maintenance and growth of this project.
 
-## Changelog
-
-See [CHANGELOG.md](CHANGELOG.md)
-
-## Current Components
-
-View available Vue.js components [here](http://vue.carbondesignsystem.com). Usage information is available when you click the blue `?` icon in the top right corner of the selected component.
-
-See [component status pages](https://www.carbondesignsystem.com/component-status) for the status of each component.
-
-## Development
-
-Please refer to the [Contribution Guidelines](../../.github/CONTRIBUTING.md) before starting any work.
-
-## Contributing
-
-Fork this repository, create a new branch, and submit a pull request to this repository. The PR will be used as part of a review process.
-
-NOTE: PR titles need to conform to sematic versioning pattern described <https://github.com/amannn/action-semantic-pull-request>
-
-e.g.
-Examples for valid PR titles:
-
-- fix: Correct typo.
-- feat: Add support for Node 12.
-- refactor!: Drop support for Node 6.
-- feat(ui): Add Button component.
-
-## Usage
-
-### General
-
-The components do not import any of the carbon styles themselves. Use the SCSS or CSS from carbon-components to provide the styling.
-
-- In your main js file (where you include Vue) you can include the styles wholesale: `import "carbon-components/css/carbon-components.min.css";`
-- You can also use the unpkg cdn to bring in the styles wholesale: unpkg.com/carbon-components/css/carbon-components.min.css aliases the latest minified css file.
-- If you prefer to build the SCSS, in the `<style>` tag of your top-level component you can include the styles wholesale: `@import "~carbon-components/scss/globals/scss/styles.scss";`
-- Check out the [Carbon Design System developers](https://www.carbondesignsystem.com/getting-started/developers/vanilla) page for information on including individual component styles into your project.
-
-### List of Available Components
-
-View the available Carbon Vue components [here](http://vue.carbondesignsystem.com). Usage information is in the notes tab.
-
-## Getting Started
-
-### Quick Start (Vue CLI)
-
-Assuming we're starting with a new project through the [Vue CLI](https://cli.vuejs.org/) (not with the plain Vue Webpack template, which might not work):
-
-```sh
-> vue create newprojectname
-Vue CLI v3.7.0
-? Please pick a preset: Manually select features
-? Check the features needed for your project: Babel, CSS Pre-processors
-? Pick a CSS pre-processor (PostCSS, Autoprefixer and CSS Modules are supported by default): Sass/SCSS (with node-
-sass)
-? Where do you prefer placing config for Babel, PostCSS, ESLint, etc.? In package.json
-? Save this as a preset for future projects? No
-```
-
-Using Yarn
-
-```sh
-$ yarn add @carbon/vue
-```
-
-Or npm
-
-```sh
-$ npm install --save @carbon/vue
-```
-
-In src/main.js add the following to include the carbon styles and components.
-
-```js
-import 'carbon-components/css/carbon-components.css';
-import CarbonComponentsVue from '@carbon/vue/src/index';
-Vue.use(CarbonComponentsVue);
-```
-
-Replace the contents of src/components/HelloWorld.vue with the following
-
-```html
-<template>
-  <div class="sample">
-    <h1>Example use of @carbon/vue</h1>
-    <cv-text-input label="Who are you?" v-model="yourName" placeholder="your name" />
-    <cv-button @click="onClick">Hello {{yourName}}</cv-button>
-    <cv-modal :visible="visible" @modal-hidden="modalClosed">
-      <template slot="title">Welcome to @carbon/vue {{yourName}}</template>
-      <template slot="content">
-        <p>
-          Lorem ipsum dolor sit amet, consectetur adipisicing elit, seed do eiusmod tempor incididunt ut labore et
-          dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
-          commodo consequat.
-        </p>
-      </template>
-    </cv-modal>
-  </div>
-</template>
-
-<script>
-  export default {
-    name: 'HelloWorld',
-    data() {
-      return {
-        yourName: '',
-        visible: false,
-      };
-    },
-    methods: {
-      onClick() {
-        this.visible = true;
-      },
-      modalClosed() {
-        this.visible = false;
-      },
-    },
-  };
-</script>
-
-<style>
-  .sample {
-    display: flex;
-    flex-direction: column;
-    justify-content: center;
-    align-items: center;
-    max-width: 600px;
-    margin: 5% auto;
-  }
-
-  .cv-text-input {
-    margin: 30px 0;
-  }
-</style>
-```
-
-That's it! Now start the server and start building.
-
-Using Yarn
-
-```sh
-$ yarn serve
-```
-
-Or npm
-
-```sh
-$ npm serve
-```
-
-### Install
-
-Run the following command using [Yarn](https://yarnpkg.com/en/):
-
-```bash
-yarn add @carbon/vue
-```
-
-If you prefer [npm](https://www.npmjs.com/), use the following command instead:
-
-```bash
-npm install --save @carbon/vue
-```
-
-NOTE: [current-script-polyfill](https://www.npmjs.com/package/current-script-polyfill) is required for older browsers (_e.g._ IE11)
-
-### Using the component library
-
-In your main js file (where you include Vue):
-
-```javascript
-import CarbonComponentsVue from '@carbon/vue';
-Vue.use(CarbonComponentsVue);
-```
-
-The above lines will register all the core components. You can register only the components you need if you prefer:
-
-```
-Vue.use(CarbonComponentsVue, ['CvButton', 'CvTag']);
-```
-
-### Using the components directly or individually
-
-You can import the component source either for all core components or for the individual components you need.
-
-To import all the core components:
-
-```javascript
-import CarbonComponentsVue from '@carbon/vue/src/index';
-Vue.use(CarbonComponentsVue);
-```
-
-To import individual components:
+### Vue 3 Guidance
 
-```javascript
-<script>
-...
-import { CvButton } from '@carbon/vue';
-...
-components: {
-  CvButton,
-},
-...
-</script>
-```
+We are actively working on components for Vue 3 and would love to get your help with this. If you want to contribute follow this guidance:
 
-Alternataively from source:
+1. Fork this repo and checkout the `vNext` branch
+2. Look to see which components have not yet been implemented. You can do this by comparing the components listed in the [Carbon React storybook](https://react.carbondesignsystem.com/?path=/story/getting-started-welcome--welcome) with the components in the `src/components` directory.
+3. When you find a component that interests you, look in the open issue list to see if someone else might already be working on it. Look for issues with a "V3 - Vue3" label. A "dibs" issue will have that label and a title of "[component name] work in progress" so for example "**CvDatePicker work in progress**".
+4. If no one else is already working on it, create an issue and label it as above.
+   - Work on the component and create a PR when you are ready.
+   - Components are expected to be implemented as [single file components](https://vuejs.org/guide/scaling-up/sfc.html) using the Vue [composition api](https://vuejs.org/guide/extras/composition-api-faq.html). See `CvCheckbox` as an example. The Vue 2 components use the options API.
+   - You should reference the existing Vue 2 component while developing the code. The existing components often have the community enhancements that need to be maintained.
+   - You should reference the DOM in the React components storybook and be sure to include any accessibility improvements that might be there.
+   - You should provide a story and test case for the component. For example:
+     ```
+     src/components/CvCheckbox/CvCheckbox.stories.js
+     src/components/CvCheckbox/CvCheckbox.vue
+     src/components/CvCheckbox/__tests__/CvCheckbox.spec.js
+     src/components/CvCheckbox/index.js
+     ```
+   - If you have question tag @davidnixon in your issue and let me know how I can help.
 
-```javascript
-<script>
-...
-import { CvButton } from '@carbon/vue/src';
-...
-components: {
-  CvButton,
-},
-...
-</script>
-```
+### Changelog
 
-or
+[CHANGELOG.md](./packages/core/CHANGELOG.md)
 
-```javascript
-<script>
-...
-import { CvButton } from '@carbon/vue/src/components/cv-button';
-...
-components: {
-  CvButton,
-},
-...
-</script>
-```
+## Getting started
 
-or
+[Usage and getting started instructions](./packages/core/README.md#getting-started) for @carbon/vue.
 
-```javascript
-<script>
-...
-import CvButton from '@carbon/vue/src/components/cv-button/cv-button';
-...
-components: {
-  CvButton,
-},
-...
-</script>
-```
+### List of available components
 
-Note: to import the component source you will need to ensure that Babel can process the source. We recommend the Babel preset `@vue/app`. If @carbon/vue is installed as a dependency in a `node_modules` folder or similar, you may need to enable Babel to process the source files, for example with the following lines, or similar, inside the `webpack.config.js` file:
+View available Vue Components [here](http://vue.carbondesignsystem.com). Usage information is available in the notes provided with each story.
 
-```javascript
-{
-  test: /\.js$/,
-  loader: 'babel-loader',
-  include: [path.resolve(__dirname, 'node_modules/@carbon'), path.resolve(__dirname, 'src')]
-}
-```
+## Building and publishing
 
-### Using the components from unkpg
+The following steps will build and publish the packages:
 
-In your html file, no need to babel.
+- clone or download the repo;
+- run `yarn` to install dependencies and bootstrap the packages;
+- run `yarn build` to build all the packages including the storybook;
 
-```html
-<script src="https://unpkg.com/vue@latest" />
-<script src="https://unpkg.com/@carbon/vue" />
-<script>
-Vue.use(window['carbon-vue'].default);
-<script>
+If you just want to build an individual package you can limit the scope:
+`yarn build --scope @carbon/vue`
+`yarn build --scope storybook`
 
-. . . <cv-button>Hello</cv-button>
-```
+To start the storybook in a local server use `yarn start`.