AIS Components #

Overview #

AIS Components is a component library built by ITS - Administrative Information Systems (AIS) at the University of Iowa. Its purpose is to streamline the development of user interfaces by AIS developers allowing them to build modern, accessible, and branded web applications.

Started in 2022, AIS Components is built on top of the modern web platform. Foundational technologies include modern JavaScript (e.g. ES modules and async/await), web components (Vue 3), ESM bundling (ViteJS), utility-first CSS (Tailwind CSS), and modern CSS layout techniques (i.e. Grid and Flexbox). Together these technologies provide a new level of capabilities and developer experience for AIS applications.

Finally, AIS Components implements the ideas and guidance from the UI Brand Manual and the UI Design System (UIDS). These patterns allow our developers to build applications that are familiar to users across campus and blend smoothly with other campus tools.

Installation #

AIS Components is published as a node module for bundled applications and as a UMD module for including the components directly on a page. Additionally, consumers need to include the library's stylesheet.

NPM #

The ais-components module is published in the @ais-public package respository, which is hosted in GitLab. To install the module, you must have NodeJS and a package manager installed. Node includes the Node Package Manager (NPM), but AIS also makes extensive use of the Yarn (v1) package manager.

JavaScript build tools that can take advantage of the NPM module include ViteJS and NuxtJS (which is built on top of Vite). Legacy option include the Vue CLI and WebPack. For stand-alone applications we strongly recommend developers use Nuxt along with our ais-nuxt module. Nuxt provides the best integration and application development experience. Vite is great for smaller efforts and may make sense when integrating with existing projects.

Configure AIS repository #

To install the package, you must tell Node where to find our repository. This configuration will be written to your .npmrc file. This is necessary even if you are using yarn.

# Check if @ais-public registry is set
npm config get @ais-public:registry

# If it is undefined, write it to your .npmrc file with:
npm config set @ais-public:registry=https://gitlab.com/api/v4/projects/39953646/packages/npm/

Install NPM package #

yarn add @ais-public/ais-components

Import component #

Once you have the library installed, you can import the components as you would any other ES module.

<script setup>
  import {AisButton} from '@ais-public/ais-components'
</script>

<template>
  <AisButton>Example Button</AisButton>
</template>

Import stylesheets & fonts #

To render the components properly, you also need to import the library's stylesheets and fonts. Please consult the example-vite project for a working example. The following examples provide a general sense of the needed configuration.

// Tailwind reset + Component CSS
import '@ais-public/ais-components/ais-components.css'

// Brand fonts
// Fonts must be copied into your project and served from the site's root url
// The fonts are bundled with the library and can be copied out of node_modules.
import '@ais-public/ais-components/uids-fonts.css'

Depending on your situation, there are several caveats to keep in mind. One, if you're using the component library alongside another stylesheet (e.g. MAUI or Bootstrap), there can be style conflicts. In this case, we recommend trying the lite version of the styles. This removes one level of potential conflicts.

// Component CSS + No Tailwind reset
import '@ais-public/ais-components/lite.css'

The second caveat involves the situation where your application has a Tailwind installation, and you are linking to ais-components.css. Even though both solutions are built on Tailwind there are still potential conflicts caused by differences in the Tailwind configurations and the order the styles are applied.

The optimal CSS environment for the component library is when the library styles and application styles are built into a single stylesheet based on our tailwind configuration. The Nuxt module handles this automatically. Please consult the universal-stylesheet branch of the exmple-vite project for details

Package consumers #

AIS developers can find example consumer apps in our GitLab.

• Nuxt3 consumer
• Vite consumer

Nuxt Module #

Nuxt developers should use the ais-nuxt module, which encapsulates the configuration necessary for using ais-components with Nuxt. See the README for installation instructions and for details regarding Nuxt configuration.

UMD #

AIS Components also offers a UMD build, which allows the library's components to be used through a <script> tag on an html page. This allows the components to be used in projects that don't include a Javascript build process. AIS developers can find an example UMD consumer in our GitLab.

Import library resources #

<script src="https://cdnjs.cloudflare.com/ajax/libs/vue/3.2.31/vue.global.min.js"></script>
<script src="./lib/ais-components.umd.js"></script>
<link href="./lib/ais-components.css" rel="stylesheet">

Vue application #

<script>
  const ref = Vue.ref
  const computed = Vue.computed

  const App = {
    setup() {
      const name = ref('Christopher Murray')
      ...
      return { name, ... }
    }
  }

  const app = Vue.createApp(App)
  app.component('ais-brand-bar', aisComponents.AisBrandBar)
  ...
  app.mount('#app')
</script>

Template #

<div id="app">
  <div class="site">
    <ais-brand-bar site="UMD Consumer"></ais-brand-bar>
    ...
  </div>
</div>

When using components directly in the DOM (and not in a compiled template), you must remember a few caveats:

• Use kebab case -- that is <ais-brand-bar> not <AisBrandBar>
• Use closing tags -- that is <ais-brand-bar></ais-brand-bar> not <ais-brand-bar />

Resources #

• Guide
• Components
• Cookbook