npm.io
3.4.0 • Published 8h ago

@tempots/core

Licence
Apache-2.0
Version
3.4.0
Deps
0
Size
148 kB
Vulns
0
Weekly
0
Stars
15

@tempots/core

npm version license codecov CI

Core types and utilities for multi-context Tempo framework.

Overview

@tempots/core provides the foundational types and utilities that are shared across all Tempo rendering contexts (DOM, ThreeJS, Konva, PixiJS, etc.). This package enables a consistent programming model across different rendering targets while maintaining strong type safety.

Installation

pnpm add @tempots/core

Core Concepts

Renderable

A Renderable is an object that can be rendered into a specific context. It has two properties:

  • type: A symbol for runtime type checking
  • render(ctx): A method that renders content and returns a cleanup function
import { Renderable, RenderContext, Clear } from '@tempots/core'

const MY_TYPE = Symbol('MY_RENDERABLE')

const myRenderable: Renderable<RenderContext, typeof MY_TYPE> = {
  type: MY_TYPE,
  render: (ctx) => {
    // Render logic here
    return (removeTree) => {
      // Cleanup logic here
    }
  }
}
RenderContext

The base interface for all rendering contexts. Context-specific implementations (DOM, ThreeJS, etc.) extend this interface with their own methods.

interface RenderContext {
  clear(removeTree: boolean): void
}
HierarchicalContext

Extended interface for contexts that support hierarchical rendering with ordered children. Provides the makeRef() method for creating reference markers that preserve insertion points.

interface HierarchicalContext extends RenderContext {
  makeRef(): this
}
Clear

A function that cleans up rendered content. The removeTree parameter indicates whether to remove the entire tree or just event listeners and subscriptions.

type Clear = (removeTree: boolean) => void
TNode

A flexible type representing any content that can be rendered:

type TNode<CTX extends RenderContext, TType extends symbol> =
  | Renderable<CTX, TType>
  | Value<string>
  | Value<number>
  | Value<boolean>
  | Signal<string | Nil>
  | Signal<number | Nil>
  | Signal<boolean | Nil>
  | undefined
  | null
  | Renderable<CTX, TType>[]

Signals containing null or undefined values render as empty text (equivalent to '').

Value

Represents a value that can be either static or reactive (a Signal):

type Value<T> = T | Signal<T>

API

createRenderable

Creates a renderable object from a render function and type symbol.

import { createRenderable } from '@tempots/core'

const MY_TYPE = Symbol('MY_RENDERABLE')

const myComponent = createRenderable(MY_TYPE, (ctx) => {
  // Render logic
  return (removeTree) => {
    // Cleanup logic
  }
})
makeProviderMark

Creates a unique symbol for dependency injection.

import { makeProviderMark } from '@tempots/core'

interface UserService {
  getUser(id: string): Promise<User>
}

const USER_SERVICE = makeProviderMark<UserService>('UserService')

Usage with Context-Specific Packages

This package is typically used indirectly through context-specific packages like @tempots/dom, @tempots/three, etc. Those packages provide higher-level APIs built on these core types.

Example: DOM Context
// In @tempots/dom
import { createRenderable, type Renderable } from '@tempots/core'
import type { DOMContext } from './dom-context'

export const DOM_RENDERABLE_TYPE = Symbol('DOM_RENDERABLE')
export type DOMRenderable = Renderable<DOMContext, typeof DOM_RENDERABLE_TYPE>

export function domRenderable(
  renderFn: (ctx: DOMContext) => Clear
): DOMRenderable {
  return createRenderable(DOM_RENDERABLE_TYPE, renderFn)
}
Example: ThreeJS Context
// In @tempots/three
import { createRenderable, type Renderable } from '@tempots/core'
import type { ThreeContext } from './three-context'

export const THREE_RENDERABLE_TYPE = Symbol('THREE_RENDERABLE')
export type ThreeRenderable = Renderable<ThreeContext, typeof THREE_RENDERABLE_TYPE>

export function threeRenderable(
  renderFn: (ctx: ThreeContext) => Clear
): ThreeRenderable {
  return createRenderable(THREE_RENDERABLE_TYPE, renderFn)
}

Type Safety

The symbol-based branding system ensures compile-time type safety:

// ✅ Valid: DOM renderable in DOM context
html.div(html.span('Hello'))

// ❌ Invalid: ThreeJS renderable in DOM context
html.div(mesh.box({ width: 1, height: 1, depth: 1 }))
// Type error: ThreeRenderable is not assignable to DOMNode

License

Apache-2.0

Contributing

See the main Tempo repository for contribution guidelines.

Keywords