@tldraw/tlschema 4.6.0-next.20de11b7e238 → 4.6.0-next.241e87d4700a

package/src/styles/TLDashStyle.ts

@@ -35,7 +35,7 @@ import { StyleProp } from './StyleProp'
  */
 export const DefaultDashStyle = StyleProp.defineEnum('tldraw:dash', {
 	defaultValue: 'draw',
-	values: ['draw', 'solid', 'dashed', 'dotted'],
+	values: ['draw', 'solid', 'dashed', 'dotted', 'none'],
 })
 
 /**

package/src/styles/TLFontFace.ts

@@ -0,0 +1,65 @@
+/**
+ * Represents the `src` property of a {@link TLFontFace}.
+ * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src | `src`} for details of the properties here.
+ * @public
+ */
+export interface TLFontFaceSource {
+	/**
+	 * A URL from which to load the font. If the value here is a key in
+	 * {@link tldraw#TLEditorAssetUrls.fonts}, the value from there will be used instead.
+	 */
+	url: string
+	format?: string
+	tech?: string
+}
+
+/**
+ * A font face that can be used in the editor. The properties of this are largely the same as the
+ * ones in the
+ * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face | css `@font-face` rule}.
+ * @public
+ */
+export interface TLFontFace {
+	/**
+	 * How this font can be referred to in CSS.
+	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-family | `font-family`}.
+	 */
+	readonly family: string
+	/**
+	 * The source of the font. This
+	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src | `src`}.
+	 */
+	readonly src: TLFontFaceSource
+	/**
+	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/ascent-override | `ascent-override`}.
+	 */
+	readonly ascentOverride?: string
+	/**
+	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/descent-override | `descent-override`}.
+	 */
+	readonly descentOverride?: string
+	/**
+	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-stretch | `font-stretch`}.
+	 */
+	readonly stretch?: string
+	/**
+	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-style | `font-style`}.
+	 */
+	readonly style?: string
+	/**
+	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-weight | `font-weight`}.
+	 */
+	readonly weight?: string
+	/**
+	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-feature-settings | `font-feature-settings`}.
+	 */
+	readonly featureSettings?: string
+	/**
+	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/line-gap-override | `line-gap-override`}.
+	 */
+	readonly lineGapOverride?: string
+	/**
+	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range | `unicode-range`}.
+	 */
+	readonly unicodeRange?: string
+}

package/src/styles/TLFontStyle.ts

@@ -1,5 +1,5 @@
-import { T } from '@tldraw/validate'
 import { StyleProp } from './StyleProp'
+import { TLThemeFont, TLThemeFonts, TLThemes } from './TLTheme'
 
 /**
  * Default font style property used by tldraw shapes for text styling.
@@ -39,8 +39,8 @@ export const DefaultFontStyle = StyleProp.defineEnum('tldraw:font', {
 })
 
 /**
- * Type representing a default font style value.
- * This is a union type of all available font style options.
+ * The names of all available font styles, derived from {@link TLThemeFonts}.
+ * Extend {@link TLThemeFonts} to add custom font names.
  *
  * @example
  * ```ts
@@ -60,7 +60,7 @@ export const DefaultFontStyle = StyleProp.defineEnum('tldraw:font', {
  *
  * @public
  */
-export type TLDefaultFontStyle = T.TypeOf<typeof DefaultFontStyle>
+export type TLDefaultFontStyle = keyof TLThemeFonts & string
 
 /**
  * Mapping of font style names to their corresponding CSS font-family declarations.
@@ -86,3 +86,52 @@ export const DefaultFontFamilies = {
 	serif: "'tldraw_serif', serif",
 	mono: "'tldraw_mono', monospace",
 }
+
+/** @internal */
+export function isFontEntry(value: unknown): value is TLThemeFont {
+	return typeof value === 'object' && value !== null && 'fontFamily' in value
+}
+
+/**
+ * Scan theme definitions and sync font registrations to match.
+ * A font entry is any key in `TLThemeFonts` whose value is a {@link TLThemeFont}
+ * object (i.e. has a `fontFamily` property).
+ *
+ * Fonts present in themes but not yet registered will be added.
+ * Fonts currently registered but absent from all themes will be removed.
+ *
+ * @public
+ */
+export function registerFontsFromThemes(definitions: TLThemes): void {
+	const fontNames = new Set<string>()
+	for (const def of Object.values(definitions)) {
+		if (!def.fonts) continue
+		for (const [key, value] of Object.entries(def.fonts)) {
+			if (isFontEntry(value)) {
+				fontNames.add(key)
+			}
+		}
+	}
+
+	const toAdd = [...fontNames].filter((v) => !DefaultFontStyle.values.includes(v as any))
+	if (toAdd.length > 0) {
+		DefaultFontStyle.addValues(...(toAdd as any))
+	}
+
+	const toRemove = DefaultFontStyle.values.filter((v) => !fontNames.has(v as string))
+	if (toRemove.length > 0) {
+		DefaultFontStyle.removeValues(...toRemove)
+	}
+
+	if (process.env.NODE_ENV !== 'production') {
+		for (const def of Object.values(definitions)) {
+			for (const font of fontNames) {
+				if (!def.fonts || !(font in def.fonts)) {
+					console.warn(
+						`Theme '${def.id}' is missing font '${font}'. Shapes using this font won't render correctly in this theme.`
+					)
+				}
+			}
+		}
+	}
+}

package/src/styles/TLTheme.ts

@@ -0,0 +1,240 @@
+import type { TLFontFace } from './TLFontFace'
+
+/**
+ * Defines the color variants available for each color in the default theme.
+ * Each color has multiple variants for different use cases like fills, strokes,
+ * patterns, and UI elements like frames and notes.
+ *
+ * @example
+ * ```ts
+ * import { TLDefaultColor } from '@tldraw/tlschema'
+ *
+ * const blueColor: TLDefaultColor = {
+ *   solid: '#4465e9',
+ *   semi: '#dce1f8',
+ *   pattern: '#6681ee',
+ *   fill: '#4465e9',
+ *   // ... other variants
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface TLDefaultColor {
+	solid: string
+	semi: string
+	pattern: string
+	fill: string // usually same as solid
+	linedFill: string // usually slightly lighter than fill
+	frameHeadingStroke: string
+	frameHeadingFill: string
+	frameStroke: string
+	frameFill: string
+	frameText: string
+	noteFill: string
+	noteText: string
+	highlightSrgb: string
+	highlightP3: string
+}
+
+/**
+ * The color palette for a theme. Contains base UI colors (as strings) and
+ * named shape colors (as {@link TLDefaultColor} objects).
+ *
+ * Extend this interface via module augmentation to add custom colors:
+ *
+ * @example
+ * ```ts
+ * declare module '@tldraw/tlschema' {
+ *   interface TLThemeColors {
+ *     pink: TLDefaultColor
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface TLThemeDefaultColors {
+	text: string
+	background: string
+	negativeSpace: string
+	solid: string
+	cursor: string
+	noteBorder: string
+	black: TLDefaultColor
+	grey: TLDefaultColor
+	'light-violet': TLDefaultColor
+	violet: TLDefaultColor
+	blue: TLDefaultColor
+	'light-blue': TLDefaultColor
+	yellow: TLDefaultColor
+	orange: TLDefaultColor
+	green: TLDefaultColor
+	'light-green': TLDefaultColor
+	'light-red': TLDefaultColor
+	red: TLDefaultColor
+	white: TLDefaultColor
+}
+
+/**
+ * A font definition within a theme. Maps a font style name to a CSS font-family
+ * declaration and optional font face descriptors for loading.
+ *
+ * @example
+ * ```ts
+ * import { TLThemeFont } from '@tldraw/tlschema'
+ *
+ * const customSans: TLThemeFont = {
+ *   fontFamily: "'Inter', sans-serif",
+ *   faces: [
+ *     { family: 'Inter', src: { url: 'https://example.com/Inter-Regular.woff2', format: 'woff2' }, weight: 'normal' },
+ *     { family: 'Inter', src: { url: 'https://example.com/Inter-Bold.woff2', format: 'woff2' }, weight: 'bold' },
+ *   ]
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface TLThemeFont {
+	/** CSS font-family declaration, e.g. `"'Inter', sans-serif"` */
+	fontFamily: string
+	/** Font face definitions for loading. Omit for system fonts that don't need loading. */
+	faces?: TLFontFace[]
+	/**
+	 * Icon for the style panel. Accepts a string icon ID (resolved via `assetUrls.icons`)
+	 * or a React element (`TLUiIconJsx`). Defaults to the built-in icon for known fonts,
+	 * or `'font-draw'` for custom fonts.
+	 */
+	icon?: unknown
+}
+
+/**
+ * The font palette for a theme. Contains named font definitions mapping font style
+ * names to their CSS font-family strings and font face descriptors.
+ *
+ * Extend this interface via module augmentation to add custom fonts:
+ *
+ * @example
+ * ```ts
+ * declare module '@tldraw/tlschema' {
+ *   interface TLThemeFonts {
+ *     cursive: TLThemeFont
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface TLThemeFonts {
+	draw: TLThemeFont
+	sans: TLThemeFont
+	serif: TLThemeFont
+	mono: TLThemeFont
+}
+
+/**
+ * Augment this interface to remove built-in palette colors from themes.
+ * Each key you add will be omitted from {@link TLThemeColors}.
+ *
+ * @example
+ * ```ts
+ * declare module '@tldraw/tlschema' {
+ *   interface TLRemovedDefaultThemeColors {
+ *     'light-violet': true
+ *     'light-blue': true
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+// oxlint-disable-next-line typescript/no-empty-object-type
+export interface TLRemovedDefaultThemeColors {}
+
+/**
+ * Keys in {@link TLThemeDefaultColors} that are required UI infrastructure colors
+ * and cannot be removed via {@link TLRemovedDefaultThemeColors}.
+ *
+ * @public
+ */
+export type TLThemeUiColorKeys =
+	| 'text'
+	| 'background'
+	| 'negativeSpace'
+	| 'solid'
+	| 'cursor'
+	| 'noteBorder'
+
+/**
+ * A color palette for one color mode. UI colors are always required.
+ * Palette colors removed via {@link TLRemovedDefaultThemeColors} are omitted.
+ *
+ * @public
+ */
+export type TLThemeColors = Pick<TLThemeDefaultColors, TLThemeUiColorKeys> &
+	Omit<TLThemeDefaultColors, TLThemeUiColorKeys | keyof TLRemovedDefaultThemeColors>
+
+/**
+ * A theme definition containing shared properties and color/font palettes for
+ * both light and dark modes.
+ *
+ * To remove palette colors from themes, augment {@link TLRemovedDefaultThemeColors}.
+ * UI colors (`text`, `background`, `negativeSpace`, `solid`, `cursor`, `noteBorder`)
+ * are always required.
+ *
+ * @example
+ * ```ts
+ * const myTheme: TLTheme = {
+ *   id: 'custom',
+ *   fontSize: 16,
+ *   lineHeight: 1.35,
+ *   strokeWidth: 2,
+ *   fonts: DEFAULT_THEME.fonts,
+ *   colors: {
+ *     light: { ... },
+ *     dark: { ... },
+ *   },
+ * }
+ * editor.updateTheme(myTheme)
+ * ```
+ *
+ * @public
+ */
+export interface TLTheme {
+	/** Unique identifier for this theme. Used as the key in the theme registry. */
+	id: TLThemeId
+	/** Base font size in pixels. Shape font sizes are derived by multiplying this value. */
+	fontSize: number
+	/** Base line height multiplier. */
+	lineHeight: number
+	/** Base stroke width in pixels. Shape stroke widths are derived by multiplying this value. */
+	strokeWidth: number
+	/** Font definitions. Individual fonts may be absent if removed by a custom theme. */
+	fonts: TLThemeFonts
+	colors: {
+		light: TLThemeColors
+		dark: TLThemeColors
+	}
+}
+
+/**
+ * A registry of available themes. Extend this interface via module
+ * augmentation to register custom themes for type-safe theme IDs.
+ *
+ * @example
+ * ```ts
+ * declare module '@tldraw/tlschema' {
+ *   interface TLThemes {
+ *     corporate: TLTheme
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface TLThemes {
+	default: TLTheme
+}
+
+/** @public */
+export type TLThemeId = keyof TLThemes & string