@aleph-alpha/ui-library 1.0.0 → 1.2.0

package/README.md

@@ -1,11 +1,137 @@
 # UI Library
 
-> 📘 **[View Storybook](https://urban-broccoli-l1okew7.pages.github.io/)** | Previews are automatically deployed for each PR.
+📘 **[View Storybook](https://urban-broccoli-l1okew7.pages.github.io/ui-library)**
+
+## Installation
+
+```bash
+pnpm add @aleph-alpha/ui-library
+```
+
+### Required Peer Dependencies
+
+```bash
+pnpm add -D unocss @unocss/preset-wind4 @unocss/reset unocss-preset-animations unocss-preset-shadcn
+```
+
+## Usage
+
+### 1. Configure UnoCSS
+
+The library exports a helper function `getUiLibraryContentConfig()` to simplify UnoCSS configuration:
+
+```typescript
+// uno.config.ts
+import { defineConfig } from 'unocss'
+import { getUiLibraryContentConfig } from '@aleph-alpha/ui-library/config'
+import presetWind from '@unocss/preset-wind4'
+import presetAnimations from 'unocss-preset-animations'
+import presetShadcn from 'unocss-preset-shadcn'
+
+export default defineConfig({
+  ...getUiLibraryContentConfig(),
+  presets: [
+    presetWind(),
+    presetAnimations(),
+    presetShadcn({ color: 'neutral' }),
+  ],
+})
+```
+
+### 2. Configure Vite
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import UnoCSS from 'unocss/vite'
+
+export default defineConfig({
+  plugins: [vue(), UnoCSS()],
+})
+```
+
+### 3. Import Styles
+
+```typescript
+// main.ts
+import '@unocss/reset/tailwind.css'
+import 'virtual:uno.css'
+
+import { createApp } from 'vue'
+import App from './App.vue'
+
+createApp(App).mount('#app')
+```
+
+### 4. Use Components
+
+```vue
+<script setup lang="ts">
+import { UiButton, UiBadge } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiButton>Click me</UiButton>
+  <UiBadge variant="secondary">New</UiBadge>
+</template>
+```
+
+### Using with @aleph-alpha/ds-components-vue
+
+If you're using both `ui-library` and `ds-components-vue`, configure UnoCSS to include both:
+
+> **⚠️ Important:** Do NOT add `presetWind()` or `presetAnimations()` separately when using `presetsAlephAlpha()`. The DS presets already include these utilities. Adding them again from different packages causes style conflicts.
+
+```typescript
+// uno.config.ts
+import { defineConfig } from 'unocss'
+import { presetsAlephAlpha, getDesignSystemContentPathConfig } from '@aleph-alpha/config-css'
+import { presetAlephAlphaIcons } from '@aleph-alpha/ds-icons'
+import { getUiLibraryContentConfig } from '@aleph-alpha/ui-library/config'
+import presetShadcn from 'unocss-preset-shadcn'
+
+const uiLibraryConfig = getUiLibraryContentConfig()
+const dsConfig = getDesignSystemContentPathConfig('vue')
+
+export default defineConfig({
+  presets: [
+    // DS presets (already includes presetWind + presetAnimations)
+    ...presetsAlephAlpha(),
+    presetAlephAlphaIcons(),
+    // UI Library preset (for shadcn CSS variables only)
+    presetShadcn({ color: 'neutral' }),
+  ],
+  content: {
+    filesystem: [
+      ...(uiLibraryConfig.content.filesystem || []),
+      ...(dsConfig.content?.filesystem || []),
+    ],
+    pipeline: {
+      include: [
+        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
+        'src/**/*.{js,ts,vue}',
+        'node_modules/@aleph-alpha/ui-library/**/*.js',
+        'node_modules/@aleph-alpha/ds-components-vue/**/*.{js,ts}',
+      ],
+    },
+  },
+})
+```
+
+## External Resources
+
+- [shadcn-vue](https://www.shadcn-vue.com/) — The component library we build upon
+- [Reka UI](https://reka-ui.com/) — Underlying accessible primitives
+- [TanStack Table](https://tanstack.com/table/latest) — Headless table library (used in UiDataTable)
+- [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/) — Accessibility patterns guide
+- [WCAG 2.2](https://www.w3.org/TR/WCAG22/) — Web accessibility guidelines
 
 ## Documentation
 
 - [Architecture](./docs/ARCHITECTURE.md) — Component structure and design decisions
 - [Contribution Guidelines](./docs/CONTRIBUTION_GUIDELINES.md) — Accessibility requirements and patterns
+- [Storybook Guidelines](./docs/STORYBOOK.md) — Story patterns and guidelines
 - [Testing Strategy](./docs/TESTING.md) — What we test and where
 
 ## Getting Started
@@ -35,6 +161,7 @@ We follow the [Conventional Commits](https://www.conventionalcommits.org/) speci
 ```
 
 **Types:**
+
 - `feat`: A new feature
 - `fix`: A bug fix
 - `docs`: Documentation only changes
@@ -45,6 +172,7 @@ We follow the [Conventional Commits](https://www.conventionalcommits.org/) speci
 - `chore`: Changes to the build process or auxiliary tools
 
 **Examples:**
+
 ```bash
 git commit -m "feat(button): add loading state"
 git commit -m "fix(dropdown): resolve keyboard navigation issue"
@@ -60,6 +188,7 @@ pnpm dlx shadcn-vue@latest add [component]
 ```
 
 Example:
+
 ```bash
 pnpm dlx shadcn-vue@latest add tooltip
 ```
@@ -68,11 +197,11 @@ Please refer to [CONTRIBUTION_GUIDELINES.md](./docs/CONTRIBUTION_GUIDELINES.md)
 
 ## Testing
 
-| Command | Purpose |
-|---------|---------|
-| `pnpm test` | Run unit tests |
+| Command               | Purpose                             |
+| --------------------- | ----------------------------------- |
+| `pnpm test`           | Run unit tests                      |
 | `pnpm test:storybook` | Run Storybook + accessibility tests |
-| `pnpm lint` | Run linting including a11y rules |
+| `pnpm lint`           | Run linting including a11y rules    |
 
 See [Testing Strategy](./docs/TESTING.md) for details on what we test and where.
 
@@ -81,6 +210,7 @@ See [Testing Strategy](./docs/TESTING.md) for details on what we test and where.
 This project uses `nx affected` in pre-commit hooks to ensure code quality. Because `lint` and `test` targets depend on `build`, commits might hang if the build cache is cold.
 
 ### If commit hangs:
+
 Run a full build to populate the cache before committing:
 
 ```bash
@@ -90,8 +220,11 @@ pnpm nx run-many --target=build --all
 Then try committing again. The pre-commit hook will hit the cache and finish quickly.
 
 ### Quick unblock (Emergency only)
+
 If you need to bypass hooks:
+
 ```sh
 git commit -m "Your message" --no-verify
 ```
+
 Use this sparingly and ensure CI passes.

package/config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * UnoCSS content configuration for scanning ui-library components.
+ */
+export declare const getUiLibraryContentConfig: () => {
+  content: {
+    filesystem: string[];
+    pipeline: {
+      include: (RegExp | string)[];
+    };
+  };
+};

package/config.js

@@ -0,0 +1,18 @@
+/**
+ * UnoCSS content configuration for scanning ui-library components.
+ */
+export const getUiLibraryContentConfig = () => ({
+  content: {
+    filesystem: ['node_modules/@aleph-alpha/ui-library/dist/**/*.js'],
+    // NOTE: pipeline.include is NOT redundant with filesystem.
+    // filesystem = where to find files, pipeline.include = which files to extract classes from.
+    // Both are required for UnoCSS to properly scan node_modules.
+    pipeline: {
+      include: [
+        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
+        'src/**/*.{js,ts,vue}',
+        'node_modules/@aleph-alpha/ui-library/**/*.js',
+      ],
+    },
+  },
+});