@dcodegroup-au/dsg-vue/README.md

Front-end Vue/Tailwind DSG for UntitledUI.

<img src=".github/docs/dsg-logo.png" align="center" style="border:none !important" />

<br />

<h1 align="center" style="border:none !important">
  DCODE Style Guide (DSG) - Vue
</h1>

<!-- <div align="center">

  <a href="https://www.npmjs.com/package/vite-plugin-laravel-translations">![npm](https://img.shields.io/npm/v/vite-plugin-laravel-translations)</a>
  <a href="">![Last Commit](https://img.shields.io/github/last-commit/DCODE-GROUP/dsg-vue)</a>
  <a href="">![npm Total Downloads](https://img.shields.io/npm/dt/vite-plugin-laravel-translations)</a>
  <a href="https://snyk.io/advisor/npm-package/vite-plugin-laravel-translations">![Vulnerabilities](https://img.shields.io/snyk/vulnerabilities/github/dcodegroup/vite-plugin-laravel-translations)</a>
  <a href="https://github.com/DCODE-GROUP/dsg-vue/issues">![Issues](https://img.shields.io/github/issues/dcodegroup/vite-plugin-laravel-translations)</a>
  <a href="">![npm peer dependency version](https://img.shields.io/npm/dependency-version/vite-plugin-laravel-translations/peer/vue)</a>

</div> -->

<br />

<p align="center">
  DCODE/Digital Style Guide (DSG) - Front-end Vue 3/TailwindCSS package for UntitledUI, written in Typescript and Vue format. This package is an extensible set of Tailwind Plugins and Vue components that match UntitledUI Figma design systems. To get started, view the <a href="https://dcode-group.github.io/dsg-vue/">Storybook documentation</a>.
</p>


<br />
<hr />
<br />

## Install

<br/>

### NPM Package

For standard Vue 3 project installations, you can install the `dsg-vue` package using any of the following commands below.

```sh
pnpm i -D @dcodegroup-au/dsg-vue
```
<br/>

### GitHub Repository

```sh
pnpm i -D https://github.com/DCODE-GROUP/dsg-vue#main
```
<br/>

### Local Directory

```sh
pnpm i -D /path/to/dsg-vue
```

<br />
<hr />
<br />

### (Optional) Vue 2 Compatibility

For projects that still have Vue 2 components, you can install extra dependencies to ensure compatibility. For more information view the <a href="https://v3-migration.vuejs.org/migration-build.html">migration build here</a>.


#### Step #1: Install NPM Packages
```sh
# Install: Vue 3 & Compatibility Libraries
pnpm i @vue/compat vue

# Install: Vue 3 Compiler
pnpm i -D @vue/comopiler-sfc

# Remove: Vue 2 Template Compiler
pnpm remove vue-template-compiler
```

#### Step #2: Update Build Configuration to use `@vue/compat`

##### Webpack Configurations
```js
// webpack.config.js
module.exports = {
  resolve: {
    alias: {
      vue: '@vue/compat'
    }
  },
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: 'vue-loader',
        options: {
          compilerOptions: {
            compatConfig: {
              MODE: 2
            }
          }
        }
      }
    ]
  }
}
```

##### Vite Configurations
```js
// vite.config.ts
import { defineConfig, UserConfig } from "vite";

export default defineConfig(({ command, mode }) => {
  return {
    resolve: {
      alias: {
        vue: '@vue/compat'
      }
    },
    plugins: [
      vue({
        template: {
          compilerOptions: {
            compatConfig: {
              MODE: 2
            }
          }
        }
      })
    ]
  } satisfies UserConfig;
});
```

<br />
<hr />
<br />

## Usage: Tailwind Configuration

To configure the Tailwind CSS portion of the package, you will need to create a `tailwind.config.ts` file in the root of your project. Then you will need to extend the `dsg-vue` Tailwind configurations/plugins to match your project Figma/design guidelines.

<br />

```js
// # Import: Types
import type { Config } from "tailwindcss";

// # Import: DSG Tailwind Plugin
import { DsgTailwindPlugin, DsgColourConfig, DsgFontFamilyConfig } from '@dcodegroup-au/dsg-vue/tailwind';

// # Extend: DSG Color Config
const ColourPalette = {
  ...DsgColourConfig,
};

// # Extend: DSG Font Family Config
const FontFamily = {
  ...DsgFontFamilyConfig,
};

export default {
  content: ['./src/**/*.{vue,js,ts,jsx,tsx}', './demo/**/*.{vue,js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: ColourPalette,
      fontFamily: FontFamily,
    },
  },
  plugins: [...DsgTailwindPlugin],
} satisfies Config;
```

<br />
<hr />
<br />

## Usage: Vue Components

To use the Vue components within the package, you will need to import them directly into your Vue components. The components are exported as named exports from the `dsg-vue` package.


```vue
<template>
  <div>
    <DsgInput
      label="Email Address"
      type="email"
      placeholder="jane.doe@example.org"
      name="email"
      classes="form-input username"
      icon="mail-01"
      tool-tip="This is your username or email address."
      :has-tooltip="true"
      autocomplete="false"
      ref="forms.email"
    />
    <DsgButton 
      label="Login"
      type="submit"
      width="full"
      :preventDefault="true"
      theme="brand"
      aria-label="This is an aria-label"
      classes=""
      @button-clicked="loginClicked"
    />
  </div>
</template>

<script setup lang="ts">
// # Import: DSG Vue Components
import { DsgButton, DsgInput } from '@dcodegroup-au/dsg-vue';

</script>
```

<br/>

View more on each component in the <a href="https://dcode-group.github.io/dsg-vue/">Storybook documentation</a>.

<br />
<hr />
<br />

## Usage: CSS

To import the styling generated from the `dsg-vue` package, ensure you import the CSS file into your main entry file (e.g. `main.ts`, `app.ts`, `index.ts`). This will ensure that the Tailwind CSS classes and the DSG Vue components are styled correctly.


```typescript
// # main.ts / app.ts / index.ts

// # Import: Vue
import { createApp } from 'vue';

// # Import: DSG Vue CSS (NPM Install)
import '@dcodegroup-au/dsg-vue/dsg-vue.css';

// # Import: DSG Vue CSS (GitHub/Local Install)
import 'dsg-vue/dsg-vue.css';
```

<br />
<hr />
<br />

## Tailwind Plugin/Component

The `dsg-vue` package contains a set of Tailwind CSS plugins and components that allow you to extend the TailwindCSS default theme and also overrides certain classes to have styles matching the UntitledUI design system; always refer to the Figma Design as the source of truth.

<br />

### Tailwind Plugins

Within the `dsgTailwind` export, you will find a list of Tailwind CSS plugins that are used to extend the default Tailwind CSS theme. These plugins are used to add additional classes to the Tailwind CSS framework that match the UntitledUI design system. This includes:

- `DsgRadiusPlugin`
- `DsgTypographyPlugin`
- `DsgGradientPlugin`
- `DsgBackdropBlurPlugin`
- `DsgShadowsPlugin`
- `DsgFocusRingsPlugin`

To exclude or only use specific plugins, you can import them directly from the `dsg-vue` package and add them to the `plugins` array in the `tailwind.config.ts` file instead of using the `dsgTailwind` export as shown above.

<br />

<b><i>NOTE: Each of the individual plugins are not extensible/customisable and are only used to add classes to the Tailwind CSS framework.</i></b>

<br />

### Tailwind Components

Within the package, there are also two extensible components that house the theme configurations as exports for customisation. These components are:

- `DsgColours`
- `DsgFontFamily`

To extend these components, you can import them directly from the `dsg-vue` package and add them to the `theme` object in the `tailwind.config.ts` file as shown above.


<br />
<hr />
<br />

## UntitledUI - Figma Design System

The `dsg-vue` package is built to match the UntitledUI Figma design system. Each project should have a design system setup based off `UntitledUI` which serves as the source of truth for design. Reach out to designers or relevant person for access.

For more information on the base Design System Template check out Figma folder for the designated project or at the following link:

- <a href="https://www.figma.com/design/T06aUcOseXpSG6HzgjrlLP/%E2%9D%96-PREVIEW-%E2%9D%96-Untitled-UI-%E2%80%93-PRO-VARIABLES-(v6.0)">UntitledUI - Pro Version Demo</a>