diff --git a/packages/vue2/README.md b/packages/vue2/README.md deleted file mode 120000 index fe840054..00000000 --- a/packages/vue2/README.md +++ /dev/null @@ -1 +0,0 @@ -../../README.md \ No newline at end of file diff --git a/packages/vue2/README.md b/packages/vue2/README.md new file mode 100644 index 00000000..8d700411 --- /dev/null +++ b/packages/vue2/README.md @@ -0,0 +1,280 @@ +# Lume + +[![PR workflow](https://github.com/Adyen/lume/actions/workflows/pr.yml/badge.svg)](https://github.com/Adyen/lume/actions/workflows/pr.yml) +[![MIT License](https://img.shields.io/badge/license-MIT)](https://github.com/Adyen/lume/blob/main/LICENSE) +[![Netlify Status](https://api.netlify.com/api/v1/badges/a6c48bc7-b4d2-4be4-ad36-cbd353ab4f07/deploy-status)](https://app.netlify.com/sites/adyen-lume/deploys) + +Lume is a combination of a set of design guidelines for creating data visualizations that tell stories, and a component library that implements them, built for Vue applications. + +> **Note:** Lume ships **two** packages - one that is compatible with Vue 2.7, and another, with Vue 3. The second is published as **`@adyen/lume-vue3`**. Our examples import the Vue 2.7-compatible version, but if you're using Vue 3, just update the import name. + +**[Design guidelines (Website)](https://lumedataviz.com/)** + +- [About](#about) +- [Getting started](#getting-started) +- [Development](#development) +- [Contacts](#contacts) + +## About + +### What's different about Lume + +🧑‍🎨 Backed by strong data visualization design principles, guidelines and patterns +🖼️ Leverages Vue for SVG rendering and reactivity +📦 Available for both Vue 2.7 and 3 + +### Stack + +#### Dependencies + +- [D3.js](https://d3js.org/) for calculations +- [Vue](https://vuejs.org/) for rendering +- [Popper.js](https://popper.js.org/) for tooltip functionality + +#### Dev stack + +- [pnpm](https://pnpm.io/) for package management +- [Vite](https://vitejs.dev/) and [Webpack](https://webpack.js.org/) for bundling +- [Sass](https://sass-lang.com/) for complex/reusable styling +- [TypeScript](https://www.typescriptlang.org/) for type checking +- [TypeScript ESLint](https://typescript-eslint.io/) for linting _(with the help of [eslint-plugin-vue](https://eslint.vuejs.org/))_ +- [Storybook](https://storybook.js.org/) for developing/showcasing components +- [Vitest](https://vitest.dev/) for unit testing + +## Getting started + +### Installation + +To install Lume, run the following command: + +#### Vue 2.7+ + +```shell +$ npm install @adyen/lume +``` + +#### Vue 3 + +```shell +$ npm install @adyen/lume-vue3 +``` + +### Components + +You can import Lume components to your Vue app: + +```ts +// SFC + + + + + +``` + +#### Sass (SFC) + +```vue + + + + + + + + +``` + +#### Sass (with overrides) + +```vue + + + + + + +``` + +## Development + +You can clone this repo and use `pnpm` to install dependencies. We use Storybook to develop our features. + +### Docker + +To run the app inside a Docker container: + +1. Create a `.env` file with your Docker image URL: + ```shell + $ echo DOCKER_IMAGE={YOUR_IMAGE_HERE} >> .env + ``` +2. Start your container: + ```shell + $ docker compose up -d + ``` +3. Attach to it in your terminal: + ```shell + $ docker attach lume + ``` +4. Install `pnpm`: + ```shell + $ npm i -g pnpm + ``` +5. (Optional, depends on your Docker image) Add the npm global directory to the `PATH` variable: + ```shell + $ export PATH="${PATH}:/root/local/bin" + ``` + +### About Vue versions + +Lume ships two packages, one for each Vue version (2 and 3). + +Development is done in Vue 3, keeping in mind that the same source code must work the same way on both Vue versions, so some of the new Vue 3 APIs are restricted, unless provided with a fallback. + +#### Storybook + +Storybook is available by running the following command: + +```shell +$ pnpm run storybook +``` + +Every chart component should have its own `.stories` file, and it will be automatically loaded onto the Storybook manager. + +##### Available addons + +- [`addon-essentials`](https://www.npmjs.com/package/@storybook/addon-essentials) +- [`addon-storysource`](https://www.npmjs.com/package/@storybook/addon-storysource) +- [`addon-a11y`](https://www.npmjs.com/package/@storybook/addon-a11y) + +### Releasing + +To generate a release: + +1. Create a release branch and push it as upstream: + ```shell + $ git checkout -b release-[VERSION] && git push -u origin release-[VERSION] + ``` +2. Run the release command: + ```shell + $ npm run release + ``` +3. Create a PR for the release branch. +4. After it's merged, publish the GitHub release. This will then publish the new release in NPM. + +This will prompt you with an interactive CLI to create a new version, tag, changelog entry and release. + +### Roadmap + +| Feature | Status | +| ----------------------------------------- | ------ | +| **Charts** | | +| Alluvial (sankey) diagram | ✅ | +| Single bar chart | ✅ | +| Grouped bar chart | ✅ | +| Stacked bar chart | ✅ | +| Horizontal orientation for all bar charts | ✅ | +| Line chart | ✅ | +| Sparkline chart | ✅ | +| **Features** | | +| A11y colors | 🚧 | +| A11y guidelines & impl. | ❌ | +| Dark theme | ❌ | +| Select dataset in legend | ❌ | + +✅ - Done +🚧 - WIP +❌ - To do + +## Contacts + +### Maintainers + +- Govind Srinidhi | [@govind-srinidhi](https://github.com/govind-srinidhi) +- Joao Santos | [@joao-m-santos](https://github.com/joao-m-santos) + +### Contributors + +- Lucas van Heerikhuizen | [@Lucas1981](https://github.com/Lucas1981) +- Vivian Joseph | [@vivy27](https://github.com/vivy27) diff --git a/packages/vue3/README.md b/packages/vue3/README.md deleted file mode 120000 index fe840054..00000000 --- a/packages/vue3/README.md +++ /dev/null @@ -1 +0,0 @@ -../../README.md \ No newline at end of file diff --git a/packages/vue3/README.md b/packages/vue3/README.md new file mode 100644 index 00000000..8d700411 --- /dev/null +++ b/packages/vue3/README.md @@ -0,0 +1,280 @@ +# Lume + +[![PR workflow](https://github.com/Adyen/lume/actions/workflows/pr.yml/badge.svg)](https://github.com/Adyen/lume/actions/workflows/pr.yml) +[![MIT License](https://img.shields.io/badge/license-MIT)](https://github.com/Adyen/lume/blob/main/LICENSE) +[![Netlify Status](https://api.netlify.com/api/v1/badges/a6c48bc7-b4d2-4be4-ad36-cbd353ab4f07/deploy-status)](https://app.netlify.com/sites/adyen-lume/deploys) + +Lume is a combination of a set of design guidelines for creating data visualizations that tell stories, and a component library that implements them, built for Vue applications. + +> **Note:** Lume ships **two** packages - one that is compatible with Vue 2.7, and another, with Vue 3. The second is published as **`@adyen/lume-vue3`**. Our examples import the Vue 2.7-compatible version, but if you're using Vue 3, just update the import name. + +**[Design guidelines (Website)](https://lumedataviz.com/)** + +- [About](#about) +- [Getting started](#getting-started) +- [Development](#development) +- [Contacts](#contacts) + +## About + +### What's different about Lume + +🧑‍🎨 Backed by strong data visualization design principles, guidelines and patterns +🖼️ Leverages Vue for SVG rendering and reactivity +📦 Available for both Vue 2.7 and 3 + +### Stack + +#### Dependencies + +- [D3.js](https://d3js.org/) for calculations +- [Vue](https://vuejs.org/) for rendering +- [Popper.js](https://popper.js.org/) for tooltip functionality + +#### Dev stack + +- [pnpm](https://pnpm.io/) for package management +- [Vite](https://vitejs.dev/) and [Webpack](https://webpack.js.org/) for bundling +- [Sass](https://sass-lang.com/) for complex/reusable styling +- [TypeScript](https://www.typescriptlang.org/) for type checking +- [TypeScript ESLint](https://typescript-eslint.io/) for linting _(with the help of [eslint-plugin-vue](https://eslint.vuejs.org/))_ +- [Storybook](https://storybook.js.org/) for developing/showcasing components +- [Vitest](https://vitest.dev/) for unit testing + +## Getting started + +### Installation + +To install Lume, run the following command: + +#### Vue 2.7+ + +```shell +$ npm install @adyen/lume +``` + +#### Vue 3 + +```shell +$ npm install @adyen/lume-vue3 +``` + +### Components + +You can import Lume components to your Vue app: + +```ts +// SFC + + + + + +``` + +#### Sass (SFC) + +```vue + + + + + + + + +``` + +#### Sass (with overrides) + +```vue + + + + + + +``` + +## Development + +You can clone this repo and use `pnpm` to install dependencies. We use Storybook to develop our features. + +### Docker + +To run the app inside a Docker container: + +1. Create a `.env` file with your Docker image URL: + ```shell + $ echo DOCKER_IMAGE={YOUR_IMAGE_HERE} >> .env + ``` +2. Start your container: + ```shell + $ docker compose up -d + ``` +3. Attach to it in your terminal: + ```shell + $ docker attach lume + ``` +4. Install `pnpm`: + ```shell + $ npm i -g pnpm + ``` +5. (Optional, depends on your Docker image) Add the npm global directory to the `PATH` variable: + ```shell + $ export PATH="${PATH}:/root/local/bin" + ``` + +### About Vue versions + +Lume ships two packages, one for each Vue version (2 and 3). + +Development is done in Vue 3, keeping in mind that the same source code must work the same way on both Vue versions, so some of the new Vue 3 APIs are restricted, unless provided with a fallback. + +#### Storybook + +Storybook is available by running the following command: + +```shell +$ pnpm run storybook +``` + +Every chart component should have its own `.stories` file, and it will be automatically loaded onto the Storybook manager. + +##### Available addons + +- [`addon-essentials`](https://www.npmjs.com/package/@storybook/addon-essentials) +- [`addon-storysource`](https://www.npmjs.com/package/@storybook/addon-storysource) +- [`addon-a11y`](https://www.npmjs.com/package/@storybook/addon-a11y) + +### Releasing + +To generate a release: + +1. Create a release branch and push it as upstream: + ```shell + $ git checkout -b release-[VERSION] && git push -u origin release-[VERSION] + ``` +2. Run the release command: + ```shell + $ npm run release + ``` +3. Create a PR for the release branch. +4. After it's merged, publish the GitHub release. This will then publish the new release in NPM. + +This will prompt you with an interactive CLI to create a new version, tag, changelog entry and release. + +### Roadmap + +| Feature | Status | +| ----------------------------------------- | ------ | +| **Charts** | | +| Alluvial (sankey) diagram | ✅ | +| Single bar chart | ✅ | +| Grouped bar chart | ✅ | +| Stacked bar chart | ✅ | +| Horizontal orientation for all bar charts | ✅ | +| Line chart | ✅ | +| Sparkline chart | ✅ | +| **Features** | | +| A11y colors | 🚧 | +| A11y guidelines & impl. | ❌ | +| Dark theme | ❌ | +| Select dataset in legend | ❌ | + +✅ - Done +🚧 - WIP +❌ - To do + +## Contacts + +### Maintainers + +- Govind Srinidhi | [@govind-srinidhi](https://github.com/govind-srinidhi) +- Joao Santos | [@joao-m-santos](https://github.com/joao-m-santos) + +### Contributors + +- Lucas van Heerikhuizen | [@Lucas1981](https://github.com/Lucas1981) +- Vivian Joseph | [@vivy27](https://github.com/vivy27)