tessl/npm-keystone-ui--core

Core design system components and utilities for KeystoneJS applications

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Emotion Integration

Name: tessl/npm-keystone-ui--core
Author: tessl

@keystone-ui/core provides re-exported Emotion functions to ensure consistent CSS-in-JS usage across the KeystoneJS ecosystem. These re-exports guarantee version compatibility and provide a single import source for Emotion functionality.

Capabilities

CSS Styling Function

Core CSS-in-JS styling function for creating dynamic styles with full TypeScript support.

/**
 * CSS-in-JS styling function from @emotion/react
 * @param template - Template literal with CSS styles
 * @param args - Interpolated values and functions
 * @returns Serialized CSS styles for use with css prop
 */
function css(template: TemplateStringsArray, ...args: any[]): SerializedStyles;

/**
 * CSS styling function for object-based styles
 * @param styles - CSS styles as JavaScript object
 * @returns Serialized CSS styles for use with css prop
 */
function css(styles: CSSObject): SerializedStyles;

Usage Examples:

import { css, useTheme } from "@keystone-ui/core";

// Template literal styles
const buttonStyles = css`
  padding: 12px 24px;
  border-radius: 6px;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  border: none;
  cursor: pointer;
  
  &:hover {
    transform: translateY(-2px);
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  }
`;

// Object-based styles with theme integration
function ThemedButton() {
  const theme = useTheme();
  
  const styles = css({
    padding: theme.spacing.medium,
    backgroundColor: theme.colors.linkColor,
    color: theme.colors.background,
    borderRadius: theme.radii.small,
    border: 'none',
    fontFamily: theme.typography.fontFamily.body,
    fontSize: theme.typography.fontSize.medium,
    fontWeight: theme.typography.fontWeight.medium,
    cursor: 'pointer',
    
    '&:hover': {
      backgroundColor: theme.colors.linkHoverColor,
    },
    
    '&:focus': {
      outline: 'none',
      boxShadow: `0 0 0 2px ${theme.colors.focusRing}`,
    }
  });
  
  return <button css={styles}>Themed Button</button>;
}

// Dynamic styles with interpolation
const getDynamicStyles = (isActive: boolean, theme: Theme) => css`
  color: ${isActive ? theme.colors.linkColor : theme.colors.foreground};
  font-weight: ${isActive ? theme.typography.fontWeight.bold : theme.typography.fontWeight.regular};
  
  ${isActive && `
    &::after {
      content: '';
      position: absolute;
      bottom: -2px;
      left: 0;
      right: 0;
      height: 2px;
      background: ${theme.colors.linkColor};
    }
  `}
`;

JSX Pragma

JSX pragma function required for Emotion's CSS-in-JS functionality in older JSX runtime configurations.

/**
 * JSX pragma function for Emotion CSS-in-JS support
 * @param type - React element type
 * @param props - Element props including css prop
 * @param children - Child elements
 * @returns React element with Emotion styles applied
 */
function jsx(type: any, props: any, ...children: any[]): any;

Usage Examples:

/** @jsxRuntime classic */
/** @jsx jsx */
import { jsx, css } from "@keystone-ui/core";

// Component using jsx pragma (legacy)
function LegacyComponent() {
  return (
    <div css={css`
      padding: 16px;
      background: #f5f5f5;
    `}>
      Content with Emotion styles
    </div>
  );
}

// Modern usage with automatic JSX runtime (recommended)
import { css } from "@keystone-ui/core";

function ModernComponent() {
  return (
    <div css={css`
      padding: 16px;
      background: #f5f5f5;
    `}>
      Content with Emotion styles
    </div>
  );
}

CSS Keyframes Animation

Function for creating CSS keyframe animations with Emotion.

/**
 * Creates CSS keyframes for animations
 * @param template - Template literal with keyframe definitions
 * @param args - Interpolated values
 * @returns Keyframes object for use in animation properties
 */
function keyframes(template: TemplateStringsArray, ...args: any[]): Keyframes;

/**
 * Creates CSS keyframes from object definition
 * @param keyframeObject - Object with keyframe percentages and styles
 * @returns Keyframes object for use in animation properties
 */
function keyframes(keyframeObject: Record<string, CSSObject>): Keyframes;

Usage Examples:

import { keyframes, css, useTheme } from "@keystone-ui/core";

// Fade in animation
const fadeIn = keyframes`
  from {
    opacity: 0;
    transform: translateY(20px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
`;

// Pulse animation with theme colors
function PulseLoader() {
  const theme = useTheme();
  
  const pulse = keyframes`
    0%, 100% {
      background-color: ${theme.colors.linkColor};
      transform: scale(1);
    }
    50% {
      background-color: ${theme.colors.linkHoverColor};
      transform: scale(1.1);
    }
  `;
  
  const styles = css`
    width: 40px;
    height: 40px;
    border-radius: 50%;
    animation: ${pulse} 1.5s ease-in-out infinite;
  `;
  
  return <div css={styles} />;
}

// Object-based keyframes
const slideIn = keyframes({
  '0%': {
    transform: 'translateX(-100%)',
    opacity: 0
  },
  '100%': {
    transform: 'translateX(0)',
    opacity: 1
  }
});

const slideInStyles = css`
  animation: ${slideIn} 0.3s ease-out;
`;

Global Styles Component

Component for applying global CSS styles to the entire application.

/**
 * Component for injecting global CSS styles
 * @param props - Global styles configuration
 * @returns JSX element that applies global styles
 */
function Global(props: GlobalProps): JSX.Element;

interface GlobalProps {
  /** CSS styles to apply globally */
  styles: CSSObject | SerializedStyles | string;
}

Usage Examples:

import { Global, css, useTheme } from "@keystone-ui/core";

// Global reset styles
function GlobalReset() {
  return (
    <Global
      styles={css`
        * {
          box-sizing: border-box;
        }
        
        body {
          margin: 0;
          padding: 0;
        }
        
        h1, h2, h3, h4, h5, h6 {
          margin: 0;
        }
      `}
    />
  );
}

// Theme-based global styles
function ThemedGlobalStyles() {
  const theme = useTheme();
  
  return (
    <Global
      styles={{
        body: {
          fontFamily: theme.typography.fontFamily.body,
          fontSize: theme.typography.fontSize.medium,
          lineHeight: theme.typography.leading.base,
          color: theme.colors.foreground,
          backgroundColor: theme.colors.background
        },
        
        'h1, h2, h3, h4, h5, h6': {
          fontFamily: theme.typography.fontFamily.heading,
          color: theme.colors.foregroundMuted
        },
        
        'a': {
          color: theme.colors.linkColor,
          '&:hover': {
            color: theme.colors.linkHoverColor
          }
        }
      }}
    />
  );
}

ClassNames Render Prop Component

Component providing render prop pattern for dynamic CSS class generation.

/**
 * Render prop component for dynamic class name generation
 * @param props - ClassNames render prop configuration
 * @returns Result of children render function
 */
function ClassNames(props: ClassNamesProps): ReactNode;

interface ClassNamesProps {
  /** Render function receiving class name utilities */
  children: (utilities: ClassNameUtilities) => ReactNode;
}

interface ClassNameUtilities {
  /** Function to generate CSS class names from styles */
  css: (...styles: (CSSObject | SerializedStyles)[]) => string;
  /** CSS styling function */
  cx: typeof css;
}

Usage Examples:

import { ClassNames, useTheme } from "@keystone-ui/core";

// Dynamic class names with conditional styling
function ConditionalButton({ variant, isActive }) {
  const theme = useTheme();
  
  return (
    <ClassNames>
      {({ css, cx }) => (
        <button
          className={cx(
            css({
              padding: theme.spacing.medium,
              border: 'none',
              borderRadius: theme.radii.small,
              fontFamily: theme.typography.fontFamily.body,
              cursor: 'pointer'
            }),
            
            variant === 'primary' && css({
              backgroundColor: theme.colors.linkColor,
              color: theme.colors.background
            }),
            
            variant === 'secondary' && css({
              backgroundColor: theme.colors.backgroundMuted,
              color: theme.colors.foreground,
              border: `1px solid ${theme.colors.border}`
            }),
            
            isActive && css({
              transform: 'scale(0.95)',
              opacity: 0.8
            })
          )}
        >
          Dynamic Button
        </button>
      )}
    </ClassNames>
  );
}

// Integration with external class libraries
function StyledComponent({ className }) {
  return (
    <ClassNames>
      {({ css, cx }) => (
        <div
          className={cx(
            className, // External classes
            css`      // Emotion styles
              padding: 16px;
              margin: 8px;
            `
          )}
        >
          Combined styling
        </div>
      )}
    </ClassNames>
  );
}

TypeScript Integration

All Emotion functions include full TypeScript support with proper type inference:

import { css, keyframes, Theme } from "@keystone-ui/core";

// Type-safe theme usage
const createThemedStyles = (theme: Theme) => css({
  color: theme.colors.foreground,     // ✓ Type-safe
  fontSize: theme.typography.fontSize.large, // ✓ Type-safe
  // invalidProperty: theme.nonexistent    // ✗ TypeScript error
});

// Typed keyframes
const typedAnimation: Keyframes = keyframes`
  from { opacity: 0; }
  to { opacity: 1; }
`;

// Template literals with interpolation
const dynamicStyles = (isVisible: boolean) => css`
  opacity: ${isVisible ? 1 : 0};
  transition: opacity 0.2s ease;
`;

Performance Considerations

Style Caching

Emotion automatically caches generated styles for optimal performance:

// Styles are cached by their serialized form
const cachedStyles = css`
  color: red;
  font-size: 16px;
`;

// Reusing the same styles won't regenerate CSS
const sameStyles = css`
  color: red;
  font-size: 16px;
`; // Uses cached version

Bundle Size Optimization

The re-exported functions help minimize bundle size by ensuring only one Emotion version is included in the final bundle.

Server-Side Rendering

All Emotion functions are fully compatible with server-side rendering when used within the @keystone-ui/core ecosystem.

CSS Normalization

Normalize Styles

Pre-built CSS normalization styles for consistent cross-browser rendering.

/**
 * CSS normalization styles based on normalize.css v8.0.1
 * Provides consistent default styling across browsers
 */
const normalize: SerializedStyles;

Usage Examples:

import { normalize, Global } from "@keystone-ui/core";

// Apply normalize globally
function App() {
  return (
    <>
      <Global styles={normalize} />
      <div>Your app content with normalized styles</div>
    </>
  );
}

// Combine with custom global styles
function AppWithCustomGlobals() {
  return (
    <>
      <Global styles={[
        normalize,
        css`
          body {
            font-family: system-ui, sans-serif;
            line-height: 1.6;
          }
          
          * {
            box-sizing: border-box;
          }
        `
      ]} />
      <div>Your app content</div>
    </>
  );
}

// Use with Core component (recommended)
import { Core } from "@keystone-ui/core";

function AppWithCore() {
  return (
    <Core>
      {/* Core component automatically includes normalize when includeNormalize=true */}
      <div>Your app content</div>
    </Core>
  );
}

The normalize styles include: