@se-studio/core-ui

Shared React UI component library with Tailwind CSS v4 and CMS infrastructure for SE Studio applications.

Features

• React 19 - Built with the latest React
• TypeScript - Full type safety
• CMS Infrastructure - Complete system for mapping Contentful content to React components
• Tailwind CSS v4 - Modern utility-first CSS framework with custom breakpoints
• Visual Components - Optimized image, video, and animation components
• Rich Text Rendering - RTF (Rich Text Field) support with embedded content
• Tree-shakeable - Import only what you need
• Dual exports - ESM and CJS support
• Fully tested - Comprehensive test coverage with Vitest

Installation

pnpm add @se-studio/core-ui

Quick Start

Basic Component Usage

import { Visual } from '@se-studio/core-ui';
import type { IAsset } from '@se-studio/core-data-types';

const image: IAsset = {
  src: 'https://images.ctfassets.net/...',
  alt: 'Hero image',
  width: 1920,
  height: 1080
};

export default function MyPage() {
  return <Visual image={image} className="w-full h-auto" />;
}

CMS Infrastructure Usage

For content-driven applications, use the CMS infrastructure:

import { CmsContent } from '@se-studio/core-ui';
import { contentfulPageRest } from '@se-studio/contentful-rest-api';

// Fetch page from Contentful
const page = await contentfulPageRest(config, 'home');

// Automatically render the correct components
export default function Page() {
  return <CmsContent content={page} config={rendererConfig} />;
}

See the CMS Infrastructure Guide for detailed documentation.

Using Tailwind Configuration

Import the Tailwind configuration in your tailwind.config.ts:

import baseConfig from '@se-studio/core-ui/tailwind-config';
import type { Config } from 'tailwindcss';

const config: Config = {
  ...baseConfig,
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@se-studio/core-ui/dist/**/*.{js,jsx}',
  ],
  // Add your customizations here
};

export default config;

Importing Styles

In your Next.js app layout or root component:

import '@se-studio/core-ui/styles';

Analytics Integration

Core UI ships analytics primitives but intentionally does not select a vendor. Wrap your app with AnalyticsProvider and pass an adapter that implements the AnalyticsAdapter interface.

import { AnalyticsProvider, ConsoleAnalyticsAdapter } from '@se-studio/core-ui';

const analyticsAdapter = new ConsoleAnalyticsAdapter(); // example adapter

export function AppProviders({ children }: { children: React.ReactNode }) {
  return <AnalyticsProvider adapter={analyticsAdapter}>{children}</AnalyticsProvider>;
}

Use the useAnalytics hook anywhere within the provider to trigger events:

import { useAnalytics } from '@se-studio/core-ui';

export function NewsletterCta() {
  const { trackClick } = useAnalytics();

  return (
    <button
      type="button"
      onClick={() =>
        trackClick('Button', 'Sign up', {
          page_title: 'Home',
          page_type: 'landing',
          slug: 'home',
        })
      }
    >
      Sign up
    </button>
  );
}

The provided ConsoleAnalyticsAdapter simply logs events for development and documentation purposes. Each project should supply an adapter that forwards events to its analytics platform of choice.

Components

CMS Infrastructure Components

CmsContent

Main component for rendering CMS content with automatic component mapping.

Props:

• content - Page or entry content from Contentful
• config - CmsRendererConfig - Component and collection mapping configuration
• context? - Optional context data to pass to components

Example:

import { CmsContent } from '@se-studio/core-ui';

<CmsContent content={page} config={rendererConfig} />

CmsComponent

Renders individual CMS components with type-based routing.

Props:

• component - Component data from Contentful
• config - Component mapping configuration
• context? - Optional context

CmsCollection

Renders CMS collections (arrays of components) with type-based routing.

Props:

• collection - Array of components from Contentful
• config - Collection mapping configuration
• context? - Optional context

Visual Components

Visual

Optimized image/video component with Next.js Image integration.

Props:

• image - IAsset - Image data with src, alt, width, height
• video? - IAsset - Optional video data
• animation? - IAsset - Optional animation/Lottie data
• className? - Additional CSS classes
• priority? - Enable priority loading for above-the-fold content
• fill? - Use Next.js Image fill mode

Example:

import { Visual } from '@se-studio/core-ui';

<Visual
  image={imageData}
  className="w-full h-auto"
  priority
/>

Rich Text Components

RTF (Rich Text Field)

Renders Contentful rich text with support for embedded entries and assets.

Props:

• document - Contentful rich text document
• embeddedComponents? - Configuration for embedded components
• embeddedCollections? - Configuration for embedded collections

Example:

import { RTF } from '@se-studio/core-ui';

<RTF
  document={richTextField}
  embeddedComponents={componentConfig}
/>

Utility Components

UnusedChecker

Development utility to detect unused CMS content types in your configuration.

Props:

• config - Your CMS renderer configuration
• pages - Array of pages to check against
• allowedUnused? - Array of content types allowed to be unused

Example:

import { UnusedChecker } from '@se-studio/core-ui';

<UnusedChecker
  config={rendererConfig}
  pages={allPages}
/>

Animation & Monitoring Components

ClientMonitor

Monitors page elements for scroll-based animations and visibility tracking. Automatically tracks elements with data-component attributes, videos, and Lottie animations using IntersectionObserver.

Props:

• defaultThreshold? - Number (0-1) - Default intersection threshold for triggering animations (default: 0.2)
• enableDebug? - Boolean - Enable debug logging in development mode (default: false)

Example:

import { ClientMonitor } from '@se-studio/core-ui';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <ClientMonitor defaultThreshold={0.2} enableDebug={false} />
        {children}
      </body>
    </html>
  );
}

How it works:

• Automatically finds and observes all elements with data-component attributes
• Tracks video elements for play/pause based on visibility
• Tracks Lottie animation elements for play/pause based on visibility
• Sets data-seen="true" and data-visible="true" attributes on elements when they enter the viewport
• Uses scroll progress calculation for tall elements that exceed viewport height

Excluding components from animation:

To exclude a component from animation tracking, add the data-exclude-animation attribute:

<div data-component="MyComponent" data-exclude-animation>
  {/* This component will not be tracked by ClientMonitor */}
  {/* It will not receive data-seen or data-visible attributes */}
</div>

Custom thresholds:

You can set a custom intersection threshold for individual elements using the data-intersection-threshold attribute:

<div data-component="MyComponent" data-intersection-threshold="0.5">
  {/* This component will trigger when 50% visible */}
</div>

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Build the library
pnpm build

# Type check
pnpm type-check

# Lint
pnpm lint

Tailwind Configuration

Custom Breakpoints

The library includes custom breakpoints optimized for modern responsive design:

• tablet: 768px
• laptop: 1024px
• desktop: 1440px

Use them in your Tailwind classes:

<div className="hidden tablet:block laptop:grid laptop:grid-cols-2 desktop:grid-cols-3">
  {/* Content */}
</div>

Typography Utilities

Custom typography styles are available:

• text-h1 - Heading 1 style
• text-h2 - Heading 2 style
• text-h3 - Heading 3 style
• text-h4 - Heading 4 style
• text-body - Body text style
• text-body-sm - Small body text

Configuration System

The package exports several configuration utilities:

createCmsRendererConfig

Creates a type-safe CMS renderer configuration:

import { createCmsRendererConfig } from '@se-studio/core-ui';

const config = createCmsRendererConfig({
  components: {
    heroSection: HeroComponent,
    featureSection: FeatureComponent
  },
  collections: {
    cardGrid: CardGridCollection
  }
});

mergeCmsRendererConfig

Merges multiple configurations (useful for environment-specific or preview mode configs):

import { mergeCmsRendererConfig } from '@se-studio/core-ui';

const previewConfig = mergeCmsRendererConfig(
  baseConfig,
  previewOverrides
);

API Reference

Main Exports

Components

• CmsContent - Main component for rendering CMS content with automatic component mapping
• CmsComponent - Renders individual CMS components with type-based routing
• CmsCollection - Renders CMS collections (arrays of components)
• Visual - Optimized image/video/animation component with Next.js Image integration
• RTF - Renders Contentful rich text with support for embedded entries and assets
• UnusedChecker - Development utility to detect unused CMS content types

Hooks

• useAnalytics - Hook for accessing analytics functions (trackEvent, trackPage, trackClick)
• useClickTracking - Hook for tracking click events with analytics
• useDocumentVisible - Hook for tracking document visibility

Utilities

• buildPageMetadata - Generates Next.js metadata object from CMS page model
• handleCmsError - Error handling utility for CMS operations
• extractComponentInfo - Extract specific component information fields
• extractCollectionInfo - Extract specific collection information fields
• extractPageContext - Extract specific page context fields
• cn - Utility function for merging Tailwind CSS classes

Types

• CmsRendererConfig - Complete renderer configuration type
• ComponentRenderer<T> - Type for component renderer functions
• CollectionRenderer<T> - Type for collection renderer functions
• ComponentConfig<T> - Type-safe component configuration
• CollectionConfig<T> - Type-safe collection configuration

For detailed JSDoc documentation on all exports, see the TypeScript declaration files (.d.ts) in the package.

Advanced Usage

For advanced CMS infrastructure usage, including:

• Configuration composition patterns
• Embeddable components
• Context passing
• Type-safe prop extraction
• Preview mode setup

See the CMS Infrastructure Guide.

Examples

Check out the example-pointme app for a complete implementation using all core-ui features.

Learn More

• CMS Infrastructure Guide - Comprehensive guide to the CMS system
• Core Data Types - Shared TypeScript types
• Contentful REST API - API client for Contentful

License

MIT