@se-studio/core-data-types

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

Installation

# 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

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
  • download?: IDownloadAsset - Optional downloadable asset (e.g. PDF)

• 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 (project adds componentType)
• IBaseCollection - Base interface for collection content models (project adds collectionType)
• IBaseExternalComponent - Base interface for external component models (project adds externalComponentType)
  • Contentful field name is externalComponentType, not externalType — the latter is never set at runtime
• 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.

Article authors

Articles support an ordered authors array (first = primary). During CMS migration, legacy single author is still populated as authors[0].

• getArticleAuthors(article) - All authors in display order (deduped by id)
• getPrimaryArticleAuthor(article) - First author, if any
• formatArticleAuthorNames(article) - Comma-separated byline for search and markdown
• normalizeResolvedArticleAuthors(authorsFromCms, legacyAuthorFromCms) - Used by Contentful converters: non-empty authors wins, else legacy author

Prefer these helpers over reading article.author directly in app or package code.

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
  • Tag / tag type show?: boolean - Visual display on cards and detail pages only (false hides; unset = visible). Distinct from hidden and indexed on IInternalLink
  • date?: string - Publication date
  • authors?: ReadonlyArray<IPersonLink> - Ordered authors (first = primary)
  • author?: IPersonLink - Primary author (authors[0]); legacy CMS field during transition
  • externalLink?: string | null - Supplementary external URL (e.g. DOI or publisher link). On IArticleLink, href is the internal detail URL when the article has article-level body content (topContent, content, or bottomContent on the article entry; article-type articlePageTopContent does not count); external-only articles use externalLink as href.
  • 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
• IListCard - Slim list-row DTO (id, href, title, optional subtitle, date, primaryTag, colours, featured visual, icon). Not a replacement for IArticleLink (detail / sitemap / markdown). Map with articleLinkToListCard from @se-studio/core-ui/server. visual / icon are for RSC cards, not client island props; do not pass IArticleLink[] into client islands.
• 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:

# 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:

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