York SU Website Components

A comprehensive Vue.js component library for the University of York Students' Union website. This repository serves as both a development environment and component distribution system, providing reusable UI components built as Vue Custom Elements that can be used across the York SU digital ecosystem.

✨ Features

• Vue Custom Elements: Components exported as web components for maximum compatibility
• Storybook Integration: Interactive component documentation and testing environment
• Automated Deployment: Continuous deployment to Cloudflare R2 for seamless integration
• Design System: Consistent UI components following York SU branding guidelines
• Accessibility First: Built with accessibility standards in mind

🚀 Quick Start

Prerequisites

• Node.js (version 22 LTS)
• npm (comes with Node.js)

Installation

1. Clone the repository:

   git clone https://github.com/YUSU-Dev/Vue-3-Components.git
   cd Vue-3-Components

2. Install dependencies:

   npm ci

3. Start the development environment:

   npm run storybook

   This will launch Storybook at http://localhost:6006 where you can view and interact with all components.

Development Workflow

• npm run storybook - Start Storybook development server
• npm run dev - Start local development server
• npm run build - Build production-ready components
• npm run build-css - Build Tailwind CSS styles
• npm run new -- -c component-name - Generate a new component
• npm run new -- -p page-name - Generate a new page
• npm run test-storybook - Run Storybook tests

📁 Project Structure

src/
├── components/          # Reusable UI components
│   ├── button/
│   │   ├── button.ce.vue       # Vue component file
│   │   ├── button.component.js # Component registration
│   │   └── button.stories.js   # Storybook stories
│   └── [other components]/
├── pages/              # Full page components
├── docs/               # Documentation files
└── _common/            # Shared utilities and helpers

🎨 Component Development

Creating a New Component

Use our CLI tool to quickly scaffold a new component:

npm run new -- -c my-component

This creates:

• my-component.ce.vue - The Vue component
• my-component.component.js - Component registration
• my-component.stories.js - Storybook stories

Component Guidelines

• Use kebab-case for all file and directory names
• Vue files must end with .ce.vue (Custom Element)
• Follow the Options API pattern for Vue components
• Include comprehensive Storybook stories for each component
• Ensure components are accessible and follow WCAG guidelines

Example Component Structure

<!-- button.ce.vue -->
<template>
  <button class="btn" :class="variant" @click="handleClick">
    <slot></slot>
  </button>
</template>

<script>
export default {
  name: "Button",
  props: {
    variant: {
      type: String,
      default: "primary",
      validator: (value) => ["primary", "secondary"].includes(value),
    },
  },
  methods: {
    handleClick(event) {
      this.$emit("click", event);
    },
  },
};
</script>

🌐 Usage on York SU Website

Components are automatically deployed to https://assets.yorksu.org when changes are merged to the main branch.

Adding Components to Your Site

1. Include the component script:

   <script src="https://assets.yorksu.org/components/button.js"></script>

2. Use the component in your HTML:

   <york-su-button variant="primary">Click me</york-su-button>

For detailed integration instructions, visit our Storybook documentation.

🛠️ Development Tools

• Vue 3 with Options API
• Tailwind CSS for styling
• Storybook for component development and documentation
• ESLint & Prettier for code quality
• Rollup for bundling
• Husky for git hooks

📖 Documentation

• Storybook - Interactive component documentation
• Contributing Guide - Technical contribution guidelines
• Style Guide - Design system guidelines

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for detailed instructions.

Quick Contributing Steps

1. Check existing issues
2. Fork the repository
3. Create a feature branch
4. Make your changes
5. Add/update tests and stories
6. Submit a pull request

Coding Standards

• Use npm for dependency management
• Write Vue components using the Options API
• Export components as Custom Elements
• Follow kebab-case naming conventions
• Include comprehensive Storybook stories
• Ensure accessibility compliance

🎯 Project Goals

This component library aims to:

• Provide consistent UI components across York SU digital properties
• Improve development efficiency through reusable components
• Maintain high accessibility and usability standards
• Enable rapid prototyping and development
• Foster collaboration between teams

🔧 Troubleshooting

Common Issues

Storybook won't start:

• Ensure Node.js version 22 LTS is installed
• Clear npm cache: npm cache clean --force
• Delete node_modules and run npm ci

Components not updating:

• Check if you're editing the .ce.vue file (not .vue)
• Ensure component is properly registered in the .component.js file
• Restart Storybook after making changes

Build failures:

• Check ESLint errors: npx eslint src/
• Verify all imports are correct
• Ensure Tailwind classes are valid

Getting Help

• 🎮 SU Digital CoP Discord
• 📧 Email: it@yorksu.org
• 🐛 GitHub Issues

🔒 Security

If you've found a vulnerability, we want to know so that we can fix it. Our security policy tells you how to do this.

📄 License

Copyright © 2024 University of York Students' Union

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the License.