npm package: @se-studio/core-data-types
Description: Core TypeScript type definitions for SE Studio content models
Latest version: 1.0.125

# @se-studio/core-data-types

Core TypeScript type definitions for SE Studio content models and shared types across the monorepo.

## Installation

```bash
# pnpm
pnpm add @se-studio/core-data-types

# npm
npm install @se-studio/core-data-types

# yarn
yarn add @se-studio/core-data-types
```

## Usage

```typescript
import type { IPage, ISeoMetadata, IAsset, DeepPartial } from '@se-studio/core-data-types';

// Use the page interface
const page: IPage = {
  id: 'page-123',
  slug: 'about-us',
  title: 'About Us',
  seo: {
    title: 'About Us - SE Studio',
    description: 'Learn more about SE Studio',
  },
};

// Use utility types
type PartialPage = DeepPartial<IPage>;
```

## API Reference

### Content Model Types

#### Pages
- **`IBasePage`** - Base interface for page content models
  - Extends `IBaseModel` with page-specific properties
  - `type: 'Page'` - Content type discriminator
  - `isHomePage: boolean` - Whether this is the home page
  - `contents?: ReadonlyArray<ITyped>` - Page content sections
  - `tags?: ReadonlyArray<IInternalLink>` - Tags associated with the page
  - `structuredData?: ReadonlyArray<unknown>` - Optional structured data

- **`PageLink`** - Page link type (metadata without full content)

#### Articles
- **`IBaseArticle`** - Base interface for article content models
  - `type: 'Article'` - Content type discriminator
  - `articleType?: IInternalLink` - Link to the article type
  - `contents?: ReadonlyArray<ITyped>` - Article content sections
  - `tags?: ReadonlyArray<IInternalLink>` - Tags associated with the article

- **`IBaseArticleType`** - Base interface for article type content models
  - `type: 'Article type'` - Content type discriminator
  - `indexPageContent?: ReadonlyArray<ITyped>` - Content for index page
  - `searchPageContent?: ReadonlyArray<ITyped>` - Content for search page

#### Components & Collections
- **`IBaseComponent`** - Base interface for component content models
- **`IBaseCollection`** - Base interface for collection content models
- **`IBaseExternalComponent`** - Base interface for external component models
- **`IBaseHtmlComponent`** - Raw HTML/CSS/JS component entries (`type: 'HtmlComponent'`)

#### Utilities

- **`orderContentWithHtmlHeroFirst(contents)`** - Stable sort so `HtmlComponent` items with `isHero: true` render (and export to markdown) before siblings in the same array.

#### Visual/Asset Types
- **`IVisual`** - Union type for visual content (Image | Video | Animation)
- **`IImage`** - Image types (Picture | SvgImage | SvgData)
- **`IPicture`** - Raster image (`type: 'Picture'`); optional `blurDataURL` for Next.js blur placeholders (set at conversion time)
- **`IVideo`** - Video content type
- **`IAnimation`** - Animation/Lottie content type
- **`IResponsiveVisual`** - Responsive visual with breakpoint configuration

#### Link Types
- **`ILinkProps`** - Base link properties (includes optional `accessibilityLabel` for screen readers)
- **`IInternalLink`** - Internal link to CMS content
- **`IArticleLink`** - Article link (extends `IInternalLink`)
  - `internalType: 'Article'`
  - `articleType?: IArticleTypeLink` - The article's type (e.g. blog, case study)
  - `primaryTag?: ITagLink` - First tag on the article
  - `date?: string` - Publication date
  - `author?: IPersonLink` - Optional author
  - `externalLink?: string | null` - Override href with an external URL
  - `download?: IDownloadAsset` - Optional downloadable asset
  - `subtitle?: string` - Article subtitle (e.g. customer name for case studies)
  - `visuals?: ReadonlyArray<IVisual>` - Additional visuals beyond the featured image; used for article browser / gallery views
- **`IExternalLink`** - External link
- **`IDownloadLink`** - Download link
- **`IBlankLink`** - Blank link (no href)

#### Context Types
- **`IPageContext`** - Page context with links to related content
- **`IContentContext`** - Content context for component rendering
- **`IAnalyticsContext`** - Analytics context for tracking. Optional `dnt?: boolean`: when true, YouTube/Vimeo embeds use privacy options (nocookie domain, dnt=1).

### Type Guard Functions

- **`isPage(content)`** - Check if content is a page
- **`isArticle(content)`** - Check if content is an article
- **`isArticleType(content)`** - Check if content is an article type
- **`isComponent(content)`** - Check if content is a component
- **`isCollection(content)`** - Check if content is a collection
- **`isHtmlComponent(content)`** - Check if content is an HTML component entry
- **`isInternalLink(link)`** - Check if link is internal
- **`isExternalLink(link)`** - Check if link is external
- **`isDownloadLink(link)`** - Check if link is a download link
- **`isImage(visual)`** - Check if visual is an image
- **`isVideo(visual)`** - Check if visual is a video
- **`isAnimation(visual)`** - Check if visual is an animation

### Utility Types

- **`DeepPartial<T>`** - Makes all nested properties optional (recursive)
- **`Prettify<T>`** - Improves type readability in IDE tooltips

For detailed JSDoc documentation on all types and functions, see the TypeScript declaration files (`.d.ts`) in the package.

## Development

This package is part of the SE Studio monorepo. To work on this package:

```bash
# Install dependencies
pnpm install

# Build the package
pnpm build

# Run tests
pnpm test

# Type check
pnpm type-check

# Run linting
pnpm lint
```

## Extending Types

These types serve as a foundation and should be extended based on your actual Contentful content model:

```typescript
import type { IPage } from '@se-studio/core-data-types';

// Extend the base page type with your custom fields
interface ICustomPage extends IPage {
  hero: {
    title: string;
    image: IAsset;
  };
  content: RichTextContent;
}
```

## Future Additions

This package currently contains placeholder types. As the content model evolves, additional types will be added for:

- Component types (Hero, CTA, etc.)
- Rich text content structures
- Navigation structures
- Blog/Article types
- And more...

## License

MIT

## Repository

[https://github.com/Something-Else-Studio/se-core-product](https://github.com/Something-Else-Studio/se-core-product)