@aleph-alpha/ui-library 1.1.0 → 1.2.0

package/README.md

@@ -2,10 +2,127 @@
 
 📘 **[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
-- [Radix Vue](https://www.radix-vue.com/) — Underlying accessible primitives
+- [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

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',
+      ],
+    },
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aleph-alpha/ui-library",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/system/lib.js",
@@ -10,10 +10,16 @@
       "types": "./dist/system/index.d.ts",
       "import": "./dist/system/lib.js"
     },
+    "./config": {
+      "types": "./config.d.ts",
+      "import": "./config.js"
+    },
     "./tailwind.preset": "./tailwind.preset.js"
   },
   "files": [
     "dist/system",
+    "config.js",
+    "config.d.ts",
     "tailwind.preset.js"
   ],
   "description": "Next-gen UI Library for Vue.js projects.",