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

npm install @tonyfreed/card-core

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

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

Current Version: 0.1.8

Usage

Basic Setup

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

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

// 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

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

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

/* 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:

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

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

You can customize breakpoints when generating responsive CSS:

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

Custom Themes

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

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