@payfit/unity-themes 1.0.0 → 1.1.0

package/dist/esm/utils/tailwind-variants.js

@@ -0,0 +1,9 @@
+import { createTV as r } from "tailwind-variants";
+import { twMergeConfig as e } from "./merge-config.js";
+const m = r({
+  twMerge: !0,
+  twMergeConfig: e
+});
+export {
+  m as uyTv
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payfit/unity-themes",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "main": "./dist/esm/index.js",
   "types": "./dist/esm/index.d.ts",
   "style": "./dist/css/unity.css",
@@ -31,11 +31,11 @@
     "@payfit/hr-app-eslint": "0.0.0-use.local",
     "@payfit/hr-apps-tsconfigs": "0.0.0-use.local",
     "@payfit/vite-configs": "0.0.0-use.local",
-    "@storybook/addon-a11y": "9.1.3",
-    "@storybook/addon-docs": "9.1.3",
-    "@storybook/addon-links": "9.1.3",
-    "@storybook/addon-vitest": "9.1.3",
-    "@storybook/react-vite": "9.1.3",
+    "@storybook/addon-a11y": "9.1.5",
+    "@storybook/addon-docs": "9.1.5",
+    "@storybook/addon-links": "9.1.5",
+    "@storybook/addon-vitest": "9.1.5",
+    "@storybook/react-vite": "9.1.5",
     "@storybook/test-runner": "0.23.0",
     "@tailwindcss/vite": "4.1.11",
     "@types/lodash": "4.14.202",
@@ -51,9 +51,9 @@
     "prettier": "3.1.0",
     "react": "18.3.1",
     "react-dom": "18.3.1",
-    "storybook": "9.1.3",
+    "storybook": "9.1.5",
     "tsx": "4.17.0",
-    "typescript": "5.7.3",
+    "typescript": "5.9.2",
     "vite": "6.3.5",
     "vitest": "3.2.4"
   },
@@ -68,6 +68,7 @@
     "colorjs.io": "0.5.2",
     "style-dictionary": "5.0.0",
     "tailwind-merge": "3.3.1",
+    "tailwind-variants": "2.1.0",
     "tailwindcss": "4.1.11"
   }
 }

package/src/index.ts

@@ -1 +1,7 @@
+// Core utilities
+export * from './utils/cn'
 export * from './utils/tailwind-merge'
+export * from './utils/tailwind-variants'
+
+// Configuration (for advanced users)
+export { twMergeConfig } from './utils/merge-config'

package/src/scripts/file-headers/unity.ts

@@ -14,7 +14,7 @@ export function unityFileHeader() {
  * LINKS
  * =============================================================================
  *
- * GitHub Repository: https://github.com/PayFit/hr-apps/tree/master/packages/unity/themes
+ * GitHub Repository: https://github.com/PayFit/hr-apps/blob/master/libs/shared/unity/themes
  * Documentation:     https://unity-theme.payfit.io/?path=/docs/1-introduction-1-welcome--docs
  * Issues/Support:    https://payfit.atlassian.net/jira/software/c/projects/CEEFRE/boards/623
  *

package/src/utils/cn.ts

@@ -0,0 +1,109 @@
+import { cn as cnBase } from 'tailwind-variants'
+
+import { twMergeConfig } from './merge-config'
+
+/**
+ * Internal Unity-configured class name utility function.
+ * @internal
+ */
+const uyCn = (...classes: string[]) =>
+  cnBase(...classes)({
+    twMerge: true,
+    twMergeConfig,
+  })
+
+/**
+ * Unity-configured class name utility function for merging CSS classes.
+ *
+ * This is a pre-configured version of tailwind-variants' `cn` function that includes
+ * Unity's custom tailwind-merge configuration. It automatically handles Unity's custom
+ * class names and resolves conflicts according to Unity design system rules.
+ * @param classes - CSS class names to merge
+ * @returns Merged and deduplicated class string
+ * @example
+ * ```tsx
+ * import { cn } from '@payfit/unity-themes'
+ *
+ * // Basic usage
+ * const className = cn('uy:p-200', 'uy:bg-surface-primary-default')
+ * // → 'uy:p-200 uy:bg-surface-primary-default'
+ *
+ * // Conflict resolution - last class wins
+ * const className = cn('uy:bg-surface-primary-default', 'uy:bg-surface-danger-default')
+ * // → 'uy:bg-surface-danger-default'
+ *
+ * // Conditional classes
+ * const className = cn(
+ *   'uy:px-200 uy:py-100',
+ *   isActive && 'uy:bg-surface-primary-default',
+ *   isDisabled && 'uy:bg-surface-neutral-disabled'
+ * )
+ *
+ * // With component props
+ * function Button({ variant, size, className: extraClasses, ...props }) {
+ *   return (
+ *     <button
+ *       className={cn(
+ *         'uy:px-200 uy:py-100 uy:rounded-100', // base styles
+ *         variant === 'primary' && 'uy:bg-surface-primary-default',
+ *         variant === 'secondary' && 'uy:bg-surface-neutral-default',
+ *         size === 'large' && 'uy:px-300 uy:py-150',
+ *         extraClasses // allow override
+ *       )}
+ *       {...props}
+ *     />
+ *   )
+ * }
+ * ```
+ * @description
+ * - Automatically merges conflicting Unity classes using Unity's design system rules
+ * - Supports all Unity design tokens: semantic colors, primitive colors, spacing, typography, etc.
+ * - Handles conditional classes (falsy values are ignored)
+ * - Compatible with standard Tailwind classes alongside Unity classes
+ * - Removes duplicate classes and resolves conflicts intelligently
+ * @see {@link uyMerge} for the underlying merge function
+ * @see {@link twMergeConfig} for the Unity merge configuration details
+ */
+export const cn = uyCn
+
+/**
+ * Alias for {@link cn} - Unity-configured class name utility function.
+ *
+ * This function is identical to `cn` but provides a more descriptive name
+ * for developers who prefer explicit naming conventions.
+ * @param classes - CSS class names to merge
+ * @returns Merged and deduplicated class string
+ * @example
+ * ```tsx
+ * import { classNames } from '@payfit/unity-themes'
+ *
+ * const buttonClasses = classNames(
+ *   'uy:px-200 uy:py-100',
+ *   'uy:bg-surface-primary-default',
+ *   'uy:text-content-inverted-default'
+ * )
+ * ```
+ * @see {@link cn} for detailed documentation and examples
+ */
+export const classNames = uyCn
+
+/**
+ * Alias for {@link cn} - Unity-configured class name utility function.
+ *
+ * This function is identical to `cn` but follows the naming convention
+ * popularized by the `clsx` library for developers familiar with that API.
+ * @param classes - CSS class names to merge
+ * @returns Merged and deduplicated class string
+ * @example
+ * ```tsx
+ * import { clsx } from '@payfit/unity-themes'
+ *
+ * const cardClasses = clsx(
+ *   'uy:p-300 uy:rounded-200',
+ *   'uy:bg-surface-neutral-default',
+ *   isHighlighted && 'uy:border-border-primary-default'
+ * )
+ * ```
+ * @see {@link cn} for detailed documentation and examples
+ */
+export const clsx = uyCn

package/src/utils/merge-config.ts

@@ -0,0 +1,193 @@
+import { validators } from 'tailwind-merge'
+
+// Unity spacing scale values
+const unitySpacing = [
+  '0',
+  '25',
+  '50',
+  '75',
+  '100',
+  '125',
+  '150',
+  '200',
+  '250',
+  '300',
+  '400',
+  '500',
+  '600',
+  '800',
+  '1000',
+]
+
+// Unity typography classes - actual generated class names (without -sm variants)
+const unityTypography = [
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'overline',
+  'subtitle',
+  'display-title',
+  'display-body',
+  'body',
+  'body-strong',
+  'body-small',
+  'body-small-strong',
+  'body-large',
+  'body-large-strong',
+  'action',
+  'action-small',
+  'action-large',
+]
+
+// Unity font sizes
+const unityFontSizes = [
+  '50',
+  '75',
+  '100',
+  '200',
+  '300',
+  '400',
+  '500',
+  '600',
+  '800',
+  '1000',
+  '1200',
+  '1400',
+  '1600',
+]
+
+// Unity border radius values
+const unityBorderRadius = [
+  '0',
+  '25',
+  '50',
+  '75',
+  '100',
+  '125',
+  '150',
+  '200',
+  '300',
+  '400',
+  'xs',
+  'sm',
+  'md',
+  'lg',
+  'xl',
+  'circle',
+  'pill',
+]
+
+// Unity shadow values
+const unityShadows = ['canvas', 'raising', 'floating', 'flying', 'soaring']
+
+// Custom validator for Unity colors
+const isUnityColor = (value: string): boolean => {
+  // Primitive colors: {color}-l{number}
+  if (/^[a-z]+-l\d+$/.test(value)) return true
+  // Semantic colors: {category}-{type}-{variant}(-{state})?
+  if (/^(?:canvas|surface|content|border|utility)-.+$/.test(value)) return true
+  return false
+}
+
+export const twMergeConfig = {
+  prefix: 'uy',
+  extend: {
+    classGroups: {
+      // Colors - Use pattern matching for maintainability
+      // Matches primitive colors like: grayscale-l0, red-l1, blue-l12, etc.
+      // Matches semantic colors like: surface-primary-default, content-neutral-low, border-danger-default, etc.
+      'bg-color': [{ bg: [validators.isArbitraryValue, isUnityColor] }],
+      'text-color': [{ text: [validators.isArbitraryValue, isUnityColor] }],
+      'border-color': [{ border: [validators.isArbitraryValue, isUnityColor] }],
+      'outline-color': [
+        { outline: [validators.isArbitraryValue, isUnityColor] },
+      ],
+      'ring-color': [{ ring: [validators.isArbitraryValue, isUnityColor] }],
+      'ring-offset-color': [
+        { 'ring-offset': [validators.isArbitraryValue, isUnityColor] },
+      ],
+      'divide-color': [{ divide: [validators.isArbitraryValue, isUnityColor] }],
+      'text-decoration-color': [
+        { decoration: [validators.isArbitraryValue, isUnityColor] },
+      ],
+      'gradient-color-from': [
+        { from: [validators.isArbitraryValue, isUnityColor] },
+      ],
+      'gradient-color-via': [
+        { via: [validators.isArbitraryValue, isUnityColor] },
+      ],
+      'gradient-color-to': [
+        { to: [validators.isArbitraryValue, isUnityColor] },
+      ],
+      // Spacing - Padding
+      p: [{ p: unitySpacing }],
+      px: [{ px: unitySpacing }],
+      py: [{ py: unitySpacing }],
+      ps: [{ ps: unitySpacing }],
+      pe: [{ pe: unitySpacing }],
+      pt: [{ pt: unitySpacing }],
+      pr: [{ pr: unitySpacing }],
+      pb: [{ pb: unitySpacing }],
+      pl: [{ pl: unitySpacing }],
+      // Spacing - Margin
+      m: [{ m: unitySpacing }],
+      mx: [{ mx: unitySpacing }],
+      my: [{ my: unitySpacing }],
+      ms: [{ ms: unitySpacing }],
+      me: [{ me: unitySpacing }],
+      mt: [{ mt: unitySpacing }],
+      mr: [{ mr: unitySpacing }],
+      mb: [{ mb: unitySpacing }],
+      ml: [{ ml: unitySpacing }],
+      // Spacing - Gap
+      gap: [{ gap: unitySpacing }],
+      'gap-x': [{ 'gap-x': unitySpacing }],
+      'gap-y': [{ 'gap-y': unitySpacing }],
+      // Spacing - Space between
+      'space-x': [{ 'space-x': unitySpacing }],
+      'space-y': [{ 'space-y': unitySpacing }],
+      // Spacing - Scroll padding
+      'scroll-p': [{ 'scroll-p': unitySpacing }],
+      'scroll-px': [{ 'scroll-px': unitySpacing }],
+      'scroll-py': [{ 'scroll-py': unitySpacing }],
+      'scroll-ps': [{ 'scroll-ps': unitySpacing }],
+      'scroll-pe': [{ 'scroll-pe': unitySpacing }],
+      'scroll-pt': [{ 'scroll-pt': unitySpacing }],
+      'scroll-pr': [{ 'scroll-pr': unitySpacing }],
+      'scroll-pb': [{ 'scroll-pb': unitySpacing }],
+      'scroll-pl': [{ 'scroll-pl': unitySpacing }],
+      // Spacing - Scroll margin
+      'scroll-m': [{ 'scroll-m': unitySpacing }],
+      'scroll-mx': [{ 'scroll-mx': unitySpacing }],
+      'scroll-my': [{ 'scroll-my': unitySpacing }],
+      'scroll-ms': [{ 'scroll-ms': unitySpacing }],
+      'scroll-me': [{ 'scroll-me': unitySpacing }],
+      'scroll-mt': [{ 'scroll-mt': unitySpacing }],
+      'scroll-mr': [{ 'scroll-mr': unitySpacing }],
+      'scroll-mb': [{ 'scroll-mb': unitySpacing }],
+      'scroll-ml': [{ 'scroll-ml': unitySpacing }],
+      // Typography
+      typography: [{ typography: unityTypography }],
+      'font-size': [{ text: unityFontSizes }],
+      // Border radius
+      rounded: [{ rounded: unityBorderRadius }],
+      'rounded-s': [{ 'rounded-s': unityBorderRadius }],
+      'rounded-e': [{ 'rounded-e': unityBorderRadius }],
+      'rounded-t': [{ 'rounded-t': unityBorderRadius }],
+      'rounded-r': [{ 'rounded-r': unityBorderRadius }],
+      'rounded-b': [{ 'rounded-b': unityBorderRadius }],
+      'rounded-l': [{ 'rounded-l': unityBorderRadius }],
+      'rounded-ss': [{ 'rounded-ss': unityBorderRadius }],
+      'rounded-se': [{ 'rounded-se': unityBorderRadius }],
+      'rounded-ee': [{ 'rounded-ee': unityBorderRadius }],
+      'rounded-es': [{ 'rounded-es': unityBorderRadius }],
+      'rounded-tl': [{ 'rounded-tl': unityBorderRadius }],
+      'rounded-tr': [{ 'rounded-tr': unityBorderRadius }],
+      'rounded-br': [{ 'rounded-br': unityBorderRadius }],
+      'rounded-bl': [{ 'rounded-bl': unityBorderRadius }],
+      // Shadows
+      shadow: [{ shadow: unityShadows }],
+    },
+  },
+}