@tonyfreed/card-core/README.md

Core components and types for Ildex card system

# Ildex Card Core

Core components and types for the Ildex card system.

> **Current Status**: This package is in active development. The Profile and Links sections are implemented and ready for use. Additional sections and features are planned for future releases.

## Installation

```bash
npm install @tonyfreed/card-core
```

**Note**: This package requires FontAwesome dependencies for the Links section. Install them separately:

```bash
npm install @fortawesome/react-fontawesome @fortawesome/free-brands-svg-icons @fortawesome/free-solid-svg-icons
```

**Current Version:** 0.1.8

## Usage

### Basic Setup

```tsx
import { CardProvider, useCard, createCard } from '@tonyfreed/card-core';

// Create a card with profile data
const myCard = createCard('account-123', 'my-card', {
  name: { en: 'John Doe', he: 'ג\'ון דו' },
  title: { en: 'Software Developer', he: 'מפתח תוכנה' },
  description: { en: 'Building amazing apps', he: 'בונה אפליקציות מדהימות' }
});

function App() {
  return (
    <CardProvider initialCard={myCard}>
      <MyCardComponent />
    </CardProvider>
  );
}

function MyCardComponent() {
  const { card, language, updateProfile } = useCard();
  
  return (
    <div>
      <h1>{card?.profile.name[language]}</h1>
      <p>{card?.profile.title?.[language]}</p>
    </div>
  );
}
```

### CSS Exports

This package provides several ways to handle styling:

#### 1. Import Section-Specific Styles

```css
/* Import profile section styles */
@import '@tonyfreed/card-core/sections/profile/styles.css';
```

```tsx
// Or import in your JavaScript/TypeScript
import '@tonyfreed/card-core/sections/profile/styles.css';
```

**Note**: Currently available sections: `profile`, `links`. Additional sections will be added in future versions.

#### 2. Generate CSS Programmatically

```tsx
import { generateThemeCSS, generateResponsiveCSS, defaultTheme } from '@tonyfreed/card-core';

// Generate basic theme CSS
const css = generateThemeCSS(defaultTheme);

// Generate responsive CSS with custom breakpoints
const responsiveCSS = generateResponsiveCSS(defaultTheme, {
  mobile: '0px',
  tablet: '640px',
  desktop: '1024px'
});

// Inject into your app
const style = document.createElement('style');
style.textContent = responsiveCSS;
document.head.appendChild(style);
```

#### 3. Use Section Components

```tsx
import { ProfileSection, LinksSection, createCard } from '@tonyfreed/card-core';

const myProfile = {
  name: { en: 'John Doe', he: 'ג\'ון דו' },
  title: { en: 'Software Developer', he: 'מפתח תוכנה' },
  description: { en: 'Building amazing apps', he: 'בונה אפליקציות מדהימות' },
  profileImageURL: 'https://example.com/profile.jpg'
};

const myLinks = [
  {
    id: '1',
    media: 'LINKEDIN' as const,
    url: 'https://linkedin.com/in/johndoe',
    title: { en: 'LinkedIn Profile', he: 'פרופיל לינקדאין' }
  },
  {
    id: '2',
    media: 'GITHUB' as const,
    url: 'https://github.com/johndoe',
    title: { en: 'GitHub', he: 'גיטהאב' }
  }
];

function MyCard() {
  return (
    <div>
      <ProfileSection profile={myProfile} language="en" />
      <LinksSection links={myLinks} />
    </div>
  );
}
```

#### 4. Use CSS Variables in Your Components

```scss
/* Your component styles */
.profile-card {
  padding: var(--spacing-medium);
  background: var(--color-background);
  color: var(--color-text);
  font-family: var(--font-family);
  border-radius: var(--border-radius);
  box-shadow: var(--shadow-medium);
  
  /* Mobile-first responsive design */
  display: flex;
  flex-direction: column;
  
  @media (min-width: var(--breakpoint-tablet)) {
    flex-direction: row;
    padding: var(--spacing-large);
  }
  
  @media (min-width: var(--breakpoint-desktop)) {
    max-width: 1024px;
    margin: 0 auto;
  }
}

.profile-name {
  font-size: var(--font-size-medium);
  
  @media (min-width: var(--breakpoint-tablet)) {
    font-size: var(--font-size-large);
  }
  
  @media (min-width: var(--breakpoint-desktop)) {
    font-size: var(--font-size-heading);
  }
}
```

### Responsive Design

The package includes mobile-first responsive design support with the following default breakpoints:

- **Mobile**: Default styles (0px+)
- **Tablet**: 640px+ (customizable)
- **Desktop**: 1024px+ (customizable)

Use the CSS variables in your media queries:

```scss
@media (min-width: var(--breakpoint-tablet)) {
  /* Tablet styles */
}

@media (min-width: var(--breakpoint-desktop)) {
  /* Desktop styles */
}
```

You can customize breakpoints when generating responsive CSS:

```tsx
const responsiveCSS = generateResponsiveCSS(defaultTheme, {
  mobile: '0px',
  tablet: '768px',    // Custom tablet breakpoint
  desktop: '1200px'   // Custom desktop breakpoint
});
```

### Custom Themes

```tsx
import { CardProvider, defaultTheme, mergeTheme } from '@tonyfreed/card-core';

const customTheme = mergeTheme(defaultTheme, {
  colors: {
    primary: '#10b981',
    secondary: '#6b7280'
  }
});

function App() {
  return (
    <CardProvider initialCard={myCard} initialTheme={customTheme}>
      {/* Your components */}
    </CardProvider>
  );
}
```

## API Reference

### Components

- **`CardProvider`** - Main context provider that manages card state, theme, and language
  - Props: `initialCard?: Card`, `initialTheme?: ThemeConfig`, `initialLanguage?: Language`
- **`useCard`** - Hook to access card context and state management functions
  - Returns: `CardContextValue` with card data and update functions
- **`ProfileSection`** - Profile display component with responsive design
  - Props: `profile?: Profile`, `language?: Language`
- **`LinksSection`** - Social media links display component with FontAwesome icons
  - Props: `links: Links[]`

### Utilities

- **`createCard(accountId, slug, profile?, config?)`** - Create a new card instance with default values
- **`validateCard(card)`** - Validate card data structure
- **`generateThemeCSS(theme)`** - Generate CSS custom properties from theme
- **`generateResponsiveCSS(theme, breakpoints?)`** - Generate responsive CSS with breakpoints
- **`mergeTheme(base, overrides)`** - Merge theme configurations

### Types

- **`Card`** - Main card interface with id, profile, config, and status
- **`Profile`** - Profile data interface with multilingual support (en, ru, he)
- **`ThemeConfig`** - Theme configuration with colors, typography, spacing, etc.
- **`Language`** - Supported languages: `'en' | 'ru' | 'he'`
- **`Links`** - Social media links interface with media type and multilingual titles
- **`Media`** - Supported media types: `'FACEBOOK' | 'INSTAGRAM' | 'LINKEDIN' | 'TWITTER' | 'YOUTUBE' | 'WEBSITE' | 'OTHER'`
- **`CardConfig`** - Card configuration interface
- **`CardContextValue`** - Context value interface for useCard hook
- **`SectionProps`** - Props interface for section components

## Development

```bash
npm install
npm run dev          # Watch mode development build
npm run build        # Production build
npm run test         # Run tests
npm run lint         # Lint code
npm run lint:fix     # Fix linting issues
npm run format       # Format code with Prettier
npm run type-check   # TypeScript type checking
```

### Available Scripts

- **`build`** - Build the library and update exports
- **`dev`** - Development build with watch mode
- **`test`** - Run Vitest test suite
- **`lint`** - ESLint code checking
- **`format`** - Prettier code formatting
- **`type-check`** - TypeScript type validation
- **`update-exports`** - Update package.json exports for new sections

### Project Structure

```
src/
├── index.ts              # Main exports
├── CardProvider.tsx      # Main context provider
├── types.ts              # Type definitions
├── themes.ts             # Default theme configuration
├── utils.ts              # Utility functions
└── sections/             # Section components
    ├── index.ts          # Section exports
    ├── profile/          # Profile section
    │   ├── index.ts
    │   ├── ProfileSection.tsx
    │   ├── types.ts
    │   └── styles.css
    └── links/            # Links section
        ├── index.ts
        ├── LinksSection.tsx
        ├── types.ts
        └── styles.css
```