@timcast/ui

Reusable React/Next.js UI components, data mappers, and Tailwind presets used across Timcast experiences. The package ships prebuilt bundles (dist/) and generated TypeScript definitions so teams can consume the library or contribute new primitives.

Installation

• Requires react@^19, react-dom@^19, and next@^15 as peer dependencies.
• Install with your preferred package manager:

pnpm add @timcast/ui           # recommended
# or
npm install @timcast/ui
# or
yarn add @timcast/ui

• Import the distributed CSS from anywhere in your app's bootstrap (e.g. app/layout.tsx or _app.tsx):

import '@timcast/ui/styles.css';
// Optional: granularity via
// import '@timcast/ui/styles/master.css';
// import '@timcast/ui/styles/tokens.css';

• Components target Tailwind CSS 4.1. If you need preset tokens, consume the Tailwind preset export:

// tailwind.config.ts
import { defineConfig } from 'tailwindcss';
import preset from '@timcast/ui/tailwind-preset';

export default defineConfig({
	presets: [preset],
});

Quick Start

import { Button } from '@timcast/ui';

export function Example() {
	return <Button variant="primary">Click me</Button>;
}

See Storybook for the full catalogue of components and usage patterns.

Local Development

Prerequisites

• Node.js 20.x (LTS) or newer
• pnpm 9.x (aligns with the existing pnpm-lock.yaml)

Initial Setup

git clone https://github.com/Timcast-Media-Group/tmg-ui.git
cd tmg-ui
pnpm install
# Optional: Point to a different API origin for generated types
set NEXT_PUBLIC_API_BASE_URL=https://api2.timcast.com/api  # Windows Powershell
# or: export NEXT_PUBLIC_API_BASE_URL=...
pnpm generate-types       # pulls OpenAPI specs and writes src/types/*
pnpm build                # typechecks + bundles to dist/

• The generate-types script downloads OpenAPI definitions for auth, cms, and settings modules. Regenerate after backend contract changes or if src/types/ is missing.
• If the public API is unreachable, you can run module-specific scripts such as pnpm generate-types:auth once connectivity is restored.

Day-to-Day Commands

| Action | Command | Notes | | ------------------ | -------------------------- | ------------------------------------------ | | Watch builds | pnpm dev | Runs tsup --watch for live rebuilds | | Storybook | pnpm storybook | Launches Storybook at http://localhost:6006 | | Build Storybook | pnpm build-storybook | Outputs static Storybook to storybook-static/ | | Run all tests | pnpm test | npm test also works; runs every Vitest project with coverage | | Component unit tests | pnpm test:unit | npm run test:unit / pnpm test:unit:watch for watch mode | | Storybook tests | pnpm test:storybook | npm run test:storybook; leverages Vitest Storybook plugin | | Type checking | pnpm typecheck | tsc --noEmit | | Production bundle | pnpm build | Generates ES/CJS bundles and declaration files |

Repository Layout (Highlights)

• src/components/** - React components grouped by domain (auth, video, products, etc.).
• src/types/** - Hand-authored and auto-generated API contracts.
• src/styles/** - CSS entry points and Tailwind preset exports.
• scripts/generate-types.js - OpenAPI-to-TypeScript generator used by the generate-types* scripts.
• .storybook/** - Storybook configuration, mocks, and decorators.

Contributing Workflow

1. Create a feature branch.
2. Implement changes and, when relevant, regenerate types.
3. Validate locally (pnpm typecheck, pnpm test, pnpm build, pnpm storybook).
4. Add a Changeset (pnpm changeset) before opening a PR if the package needs a version bump.

Refer to docs/workflows_guide.md for CI/CD specifics and publishing details.

Documentation

• docs/components_overview.md - Domain component reference (hero, navigation, auth, products, content, video).
• docs/runtime_overview.md - Context providers, cached utilities, and style preset master reference.
• docs/ui_primitives.md - Radix-based UI primitives and their variants.
• docs/types_reference.md - Generated API models, product helpers, and auth port contracts.
• docs/methodology.md - Repeatable playbook for adding documentation updates.
• docs/testing_reference.md - Current automated test coverage and execution commands.