@semiont/react-ui 0.2.30 → 0.2.31

package/src/integrations/css-modules-helper.tsx

@@ -0,0 +1,223 @@
+/**
+ * CSS Modules Helper for Semiont Components
+ *
+ * This helper provides utilities for integrating Semiont components
+ * with CSS Modules while preserving the data-attribute architecture.
+ */
+
+import React from 'react';
+import { clsx } from 'clsx';
+
+/**
+ * Creates a className builder for Semiont components with CSS Modules
+ *
+ * @param styles - The CSS Modules styles object
+ * @param baseClass - The base Semiont class name (e.g., 'semiont-button')
+ * @returns A function that builds the className string
+ */
+export function createSemiontClassName(
+  styles: Record<string, string>,
+  baseClass: string
+) {
+  return function buildClassName(
+    dataAttributes: Record<string, string | boolean | undefined>,
+    additionalClasses?: string
+  ): string {
+    const classes = [baseClass];
+
+    // Map the base class to its CSS Module equivalent if it exists
+    if (styles[baseClass]) {
+      classes.push(styles[baseClass]);
+    }
+
+    // Add any additional classes
+    if (additionalClasses) {
+      classes.push(additionalClasses);
+    }
+
+    return clsx(...classes);
+  };
+}
+
+/**
+ * Helper to generate data attributes object from component props
+ *
+ * @param props - Component props
+ * @returns Data attributes object
+ */
+export function generateDataAttributes(props: {
+  variant?: string;
+  size?: string;
+  loading?: boolean;
+  fullWidth?: boolean;
+  iconOnly?: boolean;
+  active?: boolean;
+  disabled?: boolean;
+  orientation?: string;
+  attached?: boolean;
+  spacing?: string;
+  [key: string]: any;
+}): Record<string, string | undefined> {
+  return {
+    'data-variant': props.variant,
+    'data-size': props.size,
+    'data-loading': props.loading ? 'true' : undefined,
+    'data-full-width': props.fullWidth ? 'true' : undefined,
+    'data-icon-only': props.iconOnly ? 'true' : undefined,
+    'data-active': props.active ? 'true' : undefined,
+    'data-disabled': props.disabled ? 'true' : undefined,
+    'data-orientation': props.orientation,
+    'data-attached': props.attached ? 'true' : undefined,
+    'data-spacing': props.attached ? undefined : props.spacing,
+  };
+}
+
+/**
+ * Merges data attributes into props object
+ *
+ * @param props - Original props
+ * @param dataAttributes - Data attributes to merge
+ * @returns Merged props object
+ */
+export function mergeDataAttributes<T extends Record<string, any>>(
+  props: T,
+  dataAttributes: Record<string, string | undefined>
+): T {
+  const merged = { ...props } as any;
+
+  Object.entries(dataAttributes).forEach(([key, value]) => {
+    if (value !== undefined) {
+      merged[key] = value;
+    }
+  });
+
+  return merged as T;
+}
+
+/**
+ * Example wrapper component for CSS Modules integration
+ *
+ * Usage:
+ * ```tsx
+ * import styles from './CustomButton.module.css';
+ * import { Button } from '@semiont/react-ui';
+ * import { withCSSModules } from '@semiont/react-ui/integrations';
+ *
+ * const CustomButton = withCSSModules(Button, styles, 'button');
+ * ```
+ */
+export function withCSSModules<P extends { className?: string }>(
+  Component: React.ComponentType<P>,
+  styles: Record<string, string>,
+  baseClassName: string
+) {
+  return function WrappedComponent(props: P) {
+    const className = clsx(
+      baseClassName,
+      styles[baseClassName],
+      props.className
+    );
+
+    return <Component {...props} className={className} />;
+  };
+}
+
+/**
+ * CSS Modules configuration helper for build tools
+ *
+ * This provides the necessary configuration for CSS Modules
+ * to work with Semiont's data-attribute selectors
+ */
+export const cssModulesConfig = {
+  // PostCSS config for CSS Modules
+  postcss: {
+    plugins: [
+      // Preserve data-attribute selectors
+      {
+        postcssPlugin: 'preserve-data-attributes',
+        Once(root: any) {
+          root.walkRules((rule: any) => {
+            // Don't hash data-attribute selectors
+            if (rule.selector.includes('[data-')) {
+              rule.selector = rule.selector.replace(
+                /\.([a-zA-Z][a-zA-Z0-9-_]*)/g,
+                (match: string, className: string) => {
+                  // Keep the class name but mark it as global
+                  return `:global(.${className})`;
+                }
+              );
+            }
+          });
+        },
+      },
+    ],
+  },
+
+  // Webpack config for CSS Modules
+  webpack: {
+    cssLoader: {
+      modules: {
+        // Custom naming for CSS Modules
+        localIdentName: '[name]__[local]___[hash:base64:5]',
+        // Preserve data-attribute selectors
+        getLocalIdent: (
+          context: any,
+          localIdentName: string,
+          localName: string
+        ) => {
+          // Don't hash Semiont base classes
+          if (localName.startsWith('semiont-')) {
+            return localName;
+          }
+          // Use default hashing for other classes
+          return null;
+        },
+      },
+    },
+  },
+
+  // Vite config for CSS Modules
+  vite: {
+    css: {
+      modules: {
+        // Custom naming for CSS Modules
+        generateScopedName: '[name]__[local]___[hash:base64:5]',
+        // Preserve specific selectors
+        scopeBehaviour: 'local' as const,
+        // Global patterns
+        globalModulePaths: [/semiont-.*\.css$/],
+      },
+    },
+  },
+};
+
+/**
+ * Type definitions for CSS Modules with Semiont components
+ */
+export interface SemiontCSSModules {
+  button?: string;
+  'button-content'?: string;
+  'button-icon'?: string;
+  'button-icon-left'?: string;
+  'button-icon-right'?: string;
+  'button-spinner'?: string;
+  'button-group'?: string;
+  [key: string]: string | undefined;
+}
+
+/**
+ * Helper to type CSS Modules imports
+ *
+ * Usage:
+ * ```tsx
+ * import { defineCSSModules } from '@semiont/react-ui/integrations';
+ * import rawStyles from './Button.module.css';
+ *
+ * const styles = defineCSSModules<SemiontCSSModules>(rawStyles);
+ * ```
+ */
+export function defineCSSModules<T extends SemiontCSSModules>(
+  styles: Record<string, string>
+): T {
+  return styles as T;
+}

package/src/integrations/styled-components-theme.ts

@@ -0,0 +1,405 @@
+/**
+ * Styled Components Theme for Semiont Components
+ *
+ * This provides a complete theme object and utilities for using
+ * Semiont components with styled-components or emotion.
+ */
+
+import { tokens } from '../design-tokens';
+import { css, DefaultTheme } from 'styled-components';
+
+/**
+ * Semiont theme object for styled-components
+ */
+export const semiontTheme: DefaultTheme = {
+  colors: {
+    ...tokens.colors,
+    // Flatten semantic colors for easier access
+    error: tokens.colors.semantic.error,
+    errorLight: tokens.colors.semantic.errorLight,
+    errorDark: tokens.colors.semantic.errorDark,
+    warning: tokens.colors.semantic.warning,
+    warningLight: tokens.colors.semantic.warningLight,
+    warningDark: tokens.colors.semantic.warningDark,
+    success: tokens.colors.semantic.success,
+    successLight: tokens.colors.semantic.successLight,
+    successDark: tokens.colors.semantic.successDark,
+    info: tokens.colors.semantic.info,
+    infoLight: tokens.colors.semantic.infoLight,
+    infoDark: tokens.colors.semantic.infoDark,
+  },
+  spacing: tokens.spacing,
+  typography: tokens.typography,
+  borderRadius: tokens.borderRadius,
+  shadows: tokens.shadows,
+  transitions: tokens.transitions,
+  breakpoints: tokens.breakpoints,
+};
+
+/**
+ * Type augmentation for styled-components DefaultTheme
+ */
+declare module 'styled-components' {
+  export interface DefaultTheme {
+    colors: typeof tokens.colors & {
+      error: string;
+      errorLight: string;
+      errorDark: string;
+      warning: string;
+      warningLight: string;
+      warningDark: string;
+      success: string;
+      successLight: string;
+      successDark: string;
+      info: string;
+      infoLight: string;
+      infoDark: string;
+    };
+    spacing: typeof tokens.spacing;
+    typography: typeof tokens.typography;
+    borderRadius: typeof tokens.borderRadius;
+    shadows: typeof tokens.shadows;
+    transitions: typeof tokens.transitions;
+    breakpoints: typeof tokens.breakpoints;
+  }
+}
+
+/**
+ * CSS mixins for common component patterns
+ */
+export const semiontMixins = {
+  /**
+   * Button base styles
+   */
+  buttonBase: css`
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    font-family: ${props => props.theme.typography.fontFamily.sans};
+    font-weight: ${props => props.theme.typography.fontWeight.medium};
+    line-height: ${props => props.theme.typography.lineHeight.snug};
+    border: none;
+    outline: none;
+    cursor: pointer;
+    transition: all ${props => props.theme.transitions.duration.base} ${props => props.theme.transitions.timing.ease};
+    user-select: none;
+    white-space: nowrap;
+    text-decoration: none;
+
+    &:focus-visible {
+      outline: 2px solid ${props => props.theme.colors.primary[500]};
+      outline-offset: 2px;
+    }
+
+    &:disabled,
+    &[data-disabled="true"] {
+      cursor: not-allowed;
+      opacity: 0.5;
+    }
+  `,
+
+  /**
+   * Button variant styles
+   */
+  buttonVariant: (variant: string) => css`
+    ${variant === 'primary' && css`
+      background-color: ${props => props.theme.colors.primary[500]};
+      color: ${props => props.theme.colors.neutral[0]};
+
+      &:hover:not(:disabled):not([data-disabled="true"]) {
+        background-color: ${props => props.theme.colors.primary[600]};
+      }
+
+      &:active:not(:disabled):not([data-disabled="true"]),
+      &[data-active="true"]:not(:disabled):not([data-disabled="true"]) {
+        background-color: ${props => props.theme.colors.primary[700]};
+      }
+    `}
+
+    ${variant === 'secondary' && css`
+      background-color: ${props => props.theme.colors.neutral[100]};
+      color: ${props => props.theme.colors.neutral[900]};
+
+      &:hover:not(:disabled):not([data-disabled="true"]) {
+        background-color: ${props => props.theme.colors.neutral[200]};
+      }
+
+      &:active:not(:disabled):not([data-disabled="true"]),
+      &[data-active="true"]:not(:disabled):not([data-disabled="true"]) {
+        background-color: ${props => props.theme.colors.neutral[300]};
+      }
+    `}
+
+    ${variant === 'tertiary' && css`
+      background-color: transparent;
+      color: ${props => props.theme.colors.primary[600]};
+      box-shadow: inset 0 0 0 1px ${props => props.theme.colors.primary[200]};
+
+      &:hover:not(:disabled):not([data-disabled="true"]) {
+        background-color: ${props => props.theme.colors.primary[50]};
+        box-shadow: inset 0 0 0 1px ${props => props.theme.colors.primary[300]};
+      }
+
+      &:active:not(:disabled):not([data-disabled="true"]),
+      &[data-active="true"]:not(:disabled):not([data-disabled="true"]) {
+        background-color: ${props => props.theme.colors.primary[100]};
+        box-shadow: inset 0 0 0 1px ${props => props.theme.colors.primary[400]};
+      }
+    `}
+
+    ${variant === 'danger' && css`
+      background-color: ${props => props.theme.colors.error};
+      color: ${props => props.theme.colors.neutral[0]};
+
+      &:hover:not(:disabled):not([data-disabled="true"]) {
+        background-color: ${props => props.theme.colors.errorDark};
+      }
+
+      &:active:not(:disabled):not([data-disabled="true"]),
+      &[data-active="true"]:not(:disabled):not([data-disabled="true"]) {
+        background-color: ${props => props.theme.colors.errorDark};
+        filter: brightness(0.9);
+      }
+    `}
+
+    ${variant === 'warning' && css`
+      background-color: ${props => props.theme.colors.warning};
+      color: ${props => props.theme.colors.neutral[900]};
+
+      &:hover:not(:disabled):not([data-disabled="true"]) {
+        background-color: ${props => props.theme.colors.warningDark};
+      }
+
+      &:active:not(:disabled):not([data-disabled="true"]),
+      &[data-active="true"]:not(:disabled):not([data-disabled="true"]) {
+        background-color: ${props => props.theme.colors.warningDark};
+        filter: brightness(0.9);
+      }
+    `}
+
+    ${variant === 'ghost' && css`
+      background-color: transparent;
+      color: ${props => props.theme.colors.text.primary};
+
+      &:hover:not(:disabled):not([data-disabled="true"]) {
+        background-color: ${props => props.theme.colors.neutral[100]};
+      }
+
+      &:active:not(:disabled):not([data-disabled="true"]),
+      &[data-active="true"]:not(:disabled):not([data-disabled="true"]) {
+        background-color: ${props => props.theme.colors.neutral[200]};
+      }
+    `}
+  `,
+
+  /**
+   * Button size styles
+   */
+  buttonSize: (size: string) => css`
+    ${size === 'xs' && css`
+      padding: ${props => props.theme.spacing.xs} ${props => props.theme.spacing.sm};
+      font-size: ${props => props.theme.typography.fontSize.xs};
+      border-radius: ${props => props.theme.borderRadius.sm};
+      min-height: 1.75rem;
+    `}
+
+    ${size === 'sm' && css`
+      padding: ${props => props.theme.spacing.xs} ${props => props.theme.spacing.md};
+      font-size: ${props => props.theme.typography.fontSize.sm};
+      border-radius: ${props => props.theme.borderRadius.base};
+      min-height: 2rem;
+    `}
+
+    ${size === 'md' && css`
+      padding: ${props => props.theme.spacing.sm} ${props => props.theme.spacing.lg};
+      font-size: ${props => props.theme.typography.fontSize.base};
+      border-radius: ${props => props.theme.borderRadius.md};
+      min-height: 2.5rem;
+    `}
+
+    ${size === 'lg' && css`
+      padding: ${props => props.theme.spacing.sm} ${props => props.theme.spacing.xl};
+      font-size: ${props => props.theme.typography.fontSize.lg};
+      border-radius: ${props => props.theme.borderRadius.md};
+      min-height: 3rem;
+    `}
+
+    ${size === 'xl' && css`
+      padding: ${props => props.theme.spacing.md} ${props => props.theme.spacing['2xl']};
+      font-size: ${props => props.theme.typography.fontSize.xl};
+      border-radius: ${props => props.theme.borderRadius.lg};
+      min-height: 3.5rem;
+    `}
+  `,
+
+  /**
+   * Focus ring styles
+   */
+  focusRing: (color?: string) => css`
+    &:focus-visible {
+      outline: 2px solid ${props => color || props.theme.colors.primary[500]};
+      outline-offset: 2px;
+    }
+  `,
+
+  /**
+   * Truncate text with ellipsis
+   */
+  truncate: css`
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  `,
+
+  /**
+   * Screen reader only
+   */
+  srOnly: css`
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border-width: 0;
+  `,
+
+  /**
+   * Responsive media query helpers
+   */
+  media: {
+    sm: (styles: any) => css`
+      @media (min-width: ${props => props.theme.breakpoints.sm}) {
+        ${styles}
+      }
+    `,
+    md: (styles: any) => css`
+      @media (min-width: ${props => props.theme.breakpoints.md}) {
+        ${styles}
+      }
+    `,
+    lg: (styles: any) => css`
+      @media (min-width: ${props => props.theme.breakpoints.lg}) {
+        ${styles}
+      }
+    `,
+    xl: (styles: any) => css`
+      @media (min-width: ${props => props.theme.breakpoints.xl}) {
+        ${styles}
+      }
+    `,
+    '2xl': (styles: any) => css`
+      @media (min-width: ${props => props.theme.breakpoints['2xl']}) {
+        ${styles}
+      }
+    `,
+  },
+};
+
+/**
+ * Global styles for Semiont components
+ */
+export const SemiontGlobalStyles = css`
+  /* Import CSS variables */
+  :root {
+    /* Primary colors */
+    ${Object.entries(tokens.colors.primary).map(([key, value]) =>
+      `--semiont-color-primary-${key}: ${value};`
+    ).join('\n')}
+
+    /* Secondary colors */
+    ${Object.entries(tokens.colors.secondary).map(([key, value]) =>
+      `--semiont-color-secondary-${key}: ${value};`
+    ).join('\n')}
+
+    /* Neutral colors */
+    ${Object.entries(tokens.colors.neutral).map(([key, value]) =>
+      `--semiont-color-neutral-${key}: ${value};`
+    ).join('\n')}
+
+    /* Semantic colors */
+    ${Object.entries(tokens.colors.semantic).map(([key, value]) => {
+      const kebabKey = key.replace(/([A-Z])/g, '-$1').toLowerCase();
+      return `--semiont-color-${kebabKey}: ${value};`;
+    }).join('\n')}
+
+    /* Spacing */
+    ${Object.entries(tokens.spacing).map(([key, value]) =>
+      `--semiont-spacing-${key}: ${value};`
+    ).join('\n')}
+
+    /* Typography */
+    --semiont-font-sans: ${tokens.typography.fontFamily.sans};
+    --semiont-font-mono: ${tokens.typography.fontFamily.mono};
+
+    /* Font sizes */
+    ${Object.entries(tokens.typography.fontSize).map(([key, value]) =>
+      `--semiont-text-${key}: ${value};`
+    ).join('\n')}
+
+    /* Font weights */
+    ${Object.entries(tokens.typography.fontWeight).map(([key, value]) =>
+      `--semiont-font-${key}: ${value};`
+    ).join('\n')}
+
+    /* Border radius */
+    ${Object.entries(tokens.borderRadius).map(([key, value]) =>
+      `--semiont-radius-${key}: ${value};`
+    ).join('\n')}
+
+    /* Shadows */
+    ${Object.entries(tokens.shadows).map(([key, value]) =>
+      `--semiont-shadow-${key}: ${value};`
+    ).join('\n')}
+
+    /* Transitions */
+    ${Object.entries(tokens.transitions.duration).map(([key, value]) =>
+      `--semiont-duration-${key}: ${value};`
+    ).join('\n')}
+  }
+`;
+
+/**
+ * Helper function to create styled Semiont components
+ *
+ * Usage:
+ * ```tsx
+ * import styled from 'styled-components';
+ * import { createStyledSemiontButton } from '@semiont/react-ui/integrations';
+ *
+ * const StyledButton = createStyledSemiontButton(styled);
+ * ```
+ */
+export function createStyledSemiontButton(styled: any) {
+  return styled.button.attrs((props: any) => ({
+    'data-variant': props.variant,
+    'data-size': props.size,
+    'data-loading': props.loading ? 'true' : undefined,
+    'data-full-width': props.fullWidth ? 'true' : undefined,
+    'data-icon-only': props.iconOnly ? 'true' : undefined,
+    'data-active': props.active ? 'true' : undefined,
+    'data-disabled': props.disabled ? 'true' : undefined,
+    className: `semiont-button ${props.className || ''}`.trim(),
+  }))`
+    ${semiontMixins.buttonBase}
+    ${(props: any) => semiontMixins.buttonVariant(props.variant || 'primary')}
+    ${(props: any) => semiontMixins.buttonSize(props.size || 'md')}
+
+    ${(props: any) => props.fullWidth && css`
+      width: 100%;
+    `}
+
+    ${(props: any) => props.loading && css`
+      pointer-events: none;
+      opacity: 0.75;
+    `}
+
+    ${(props: any) => props.iconOnly && css`
+      padding: ${props.theme.spacing.sm};
+      aspect-ratio: 1;
+    `}
+  `;
+}