@tldraw/tlschema 4.1.0-next.542f014c3fac → 4.1.0-next.9f145d10c7d0

package/src/styles/TLColorStyle.ts

@@ -2,7 +2,24 @@ import { Expand } from '@tldraw/utils'
 import { T } from '@tldraw/validate'
 import { StyleProp } from './StyleProp'
 
-/** @public */
+/**
+ * Array of default color names available in tldraw's color palette.
+ * These colors form the basis for the default color style system and are available
+ * in both light and dark theme variants.
+ *
+ * @example
+ * ```ts
+ * import { defaultColorNames } from '@tldraw/tlschema'
+ *
+ * // Create a color picker with all default colors
+ * const colorOptions = defaultColorNames.map(color => ({
+ *   name: color,
+ *   value: color
+ * }))
+ * ```
+ *
+ * @public
+ */
 export const defaultColorNames = [
 	'black',
 	'grey',
@@ -19,7 +36,26 @@ export const defaultColorNames = [
 	'white',
 ] as const
 
-/** @public */
+/**
+ * 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 { TLDefaultColorThemeColor } from '@tldraw/tlschema'
+ *
+ * const blueColor: TLDefaultColorThemeColor = {
+ *   solid: '#4465e9',
+ *   semi: '#dce1f8',
+ *   pattern: '#6681ee',
+ *   fill: '#4465e9',
+ *   // ... other variants
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface TLDefaultColorThemeColor {
 	solid: string
 	semi: string
@@ -36,7 +72,27 @@ export interface TLDefaultColorThemeColor {
 	highlightP3: string
 }
 
-/** @public */
+/**
+ * Complete color theme definition containing all colors and their variants
+ * for either light or dark mode. Includes base theme properties and all
+ * default colors with their respective color variants.
+ *
+ * @example
+ * ```ts
+ * import { TLDefaultColorTheme } from '@tldraw/tlschema'
+ *
+ * const customTheme: TLDefaultColorTheme = {
+ *   id: 'light',
+ *   text: '#000000',
+ *   background: '#ffffff',
+ *   solid: '#fcfffe',
+ *   black: { solid: '#000000', semi: '#cccccc', ... },
+ *   // ... other colors
+ * }
+ * ```
+ *
+ * @public
+ */
 export type TLDefaultColorTheme = Expand<
 	{
 		id: 'light' | 'dark'
@@ -46,7 +102,26 @@ export type TLDefaultColorTheme = Expand<
 	} & Record<(typeof defaultColorNames)[number], TLDefaultColorThemeColor>
 >
 
-/** @public */
+/**
+ * Complete color palette containing both light and dark theme definitions.
+ * This object provides the full color system used by tldraw's default themes,
+ * including all color variants and theme-specific adjustments.
+ *
+ * @example
+ * ```ts
+ * import { DefaultColorThemePalette } from '@tldraw/tlschema'
+ *
+ * // Get the dark theme colors
+ * const darkTheme = DefaultColorThemePalette.darkMode
+ * const redColor = darkTheme.red.solid // '#e03131'
+ *
+ * // Access light theme colors
+ * const lightTheme = DefaultColorThemePalette.lightMode
+ * const blueColor = lightTheme.blue.fill // '#4465e9'
+ * ```
+ *
+ * @public
+ */
 export const DefaultColorThemePalette: {
 	lightMode: TLDefaultColorTheme
 	darkMode: TLDefaultColorTheme
@@ -456,36 +531,179 @@ export const DefaultColorThemePalette: {
 	},
 }
 
-/** @public */
+/**
+ * Returns the appropriate default color theme based on the dark mode preference.
+ *
+ * @param opts - Configuration options
+ *   - isDarkMode - Whether to return the dark theme (true) or light theme (false)
+ * @returns The corresponding TLDefaultColorTheme (light or dark)
+ *
+ * @example
+ * ```ts
+ * import { getDefaultColorTheme } from '@tldraw/tlschema'
+ *
+ * // Get light theme
+ * const lightTheme = getDefaultColorTheme({ isDarkMode: false })
+ *
+ * // Get dark theme
+ * const darkTheme = getDefaultColorTheme({ isDarkMode: true })
+ *
+ * // Use with editor
+ * const theme = getDefaultColorTheme({ isDarkMode: window.matchMedia('(prefers-color-scheme: dark)').matches })
+ * ```
+ *
+ * @public
+ */
 export function getDefaultColorTheme(opts: { isDarkMode: boolean }): TLDefaultColorTheme {
 	return opts.isDarkMode ? DefaultColorThemePalette.darkMode : DefaultColorThemePalette.lightMode
 }
 
-/** @public */
+/**
+ * Default color style property used by tldraw shapes for their primary color.
+ * This style prop allows shapes to use any of the default color names and
+ * automatically saves the last used value for new shapes.
+ *
+ * @example
+ * ```ts
+ * import { DefaultColorStyle } from '@tldraw/tlschema'
+ *
+ * // Use in shape props definition
+ * interface MyShapeProps {
+ *   color: typeof DefaultColorStyle
+ *   // other props...
+ * }
+ *
+ * // Set color on a shape
+ * const shape = {
+ *   // ... other properties
+ *   props: {
+ *     color: 'red' as const,
+ *     // ... other props
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export const DefaultColorStyle = StyleProp.defineEnum('tldraw:color', {
 	defaultValue: 'black',
 	values: defaultColorNames,
 })
 
-/** @public */
+/**
+ * Default label color style property used for text labels on shapes.
+ * This is separate from the main color style to allow different colors
+ * for shape fills/strokes versus their text labels.
+ *
+ * @example
+ * ```ts
+ * import { DefaultLabelColorStyle } from '@tldraw/tlschema'
+ *
+ * // Use in shape props definition
+ * interface MyShapeProps {
+ *   labelColor: typeof DefaultLabelColorStyle
+ *   // other props...
+ * }
+ *
+ * // Create a shape with different fill and label colors
+ * const shape = {
+ *   // ... other properties
+ *   props: {
+ *     color: 'blue' as const,
+ *     labelColor: 'white' as const,
+ *     // ... other props
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export const DefaultLabelColorStyle = StyleProp.defineEnum('tldraw:labelColor', {
 	defaultValue: 'black',
 	values: defaultColorNames,
 })
 
-/** @public */
+/**
+ * Type representing a default color style value.
+ * This is a union type of all available default color names.
+ *
+ * @example
+ * ```ts
+ * import { TLDefaultColorStyle } from '@tldraw/tlschema'
+ *
+ * // Valid color values
+ * const redColor: TLDefaultColorStyle = 'red'
+ * const blueColor: TLDefaultColorStyle = 'blue'
+ *
+ * // Type guard usage
+ * function isValidColor(color: string): color is TLDefaultColorStyle {
+ *   return ['black', 'red', 'blue'].includes(color as TLDefaultColorStyle)
+ * }
+ * ```
+ *
+ * @public
+ */
 export type TLDefaultColorStyle = T.TypeOf<typeof DefaultColorStyle>
 
 const defaultColorNamesSet = new Set(defaultColorNames)
 
-/** @public */
+/**
+ * Type guard to check if a color value is one of the default theme colors.
+ * Useful for determining if a color can be looked up in the theme palette.
+ *
+ * @param color - The color value to check
+ * @returns True if the color is a default theme color, false otherwise
+ *
+ * @example
+ * ```ts
+ * import { isDefaultThemeColor, TLDefaultColorStyle } from '@tldraw/tlschema'
+ *
+ * const color: TLDefaultColorStyle = 'red'
+ *
+ * if (isDefaultThemeColor(color)) {
+ *   // color is guaranteed to be a default theme color
+ *   console.log(`${color} is a default theme color`)
+ * } else {
+ *   // color might be a custom hex value or other format
+ *   console.log(`${color} is a custom color`)
+ * }
+ * ```
+ *
+ * @public
+ */
 export function isDefaultThemeColor(
 	color: TLDefaultColorStyle
 ): color is (typeof defaultColorNames)[number] {
 	return defaultColorNamesSet.has(color as (typeof defaultColorNames)[number])
 }
 
-/** @public */
+/**
+ * Resolves a color style value to its actual CSS color string for a given theme and variant.
+ * If the color is not a default theme color, returns the color value as-is.
+ *
+ * @param theme - The color theme to use for resolution
+ * @param color - The color style value to resolve
+ * @param variant - Which variant of the color to return (solid, fill, pattern, etc.)
+ * @returns The CSS color string for the specified color and variant
+ *
+ * @example
+ * ```ts
+ * import { getColorValue, getDefaultColorTheme } from '@tldraw/tlschema'
+ *
+ * const theme = getDefaultColorTheme({ isDarkMode: false })
+ *
+ * // Get the solid variant of red
+ * const redSolid = getColorValue(theme, 'red', 'solid') // '#e03131'
+ *
+ * // Get the fill variant of blue
+ * const blueFill = getColorValue(theme, 'blue', 'fill') // '#4465e9'
+ *
+ * // Custom color passes through unchanged
+ * const customColor = getColorValue(theme, '#ff0000', 'solid') // '#ff0000'
+ * ```
+ *
+ * @public
+ */
 export function getColorValue(
 	theme: TLDefaultColorTheme,
 	color: TLDefaultColorStyle,

package/src/styles/TLDashStyle.ts

@@ -1,11 +1,63 @@
 import { T } from '@tldraw/validate'
 import { StyleProp } from './StyleProp'
 
-/** @public */
+/**
+ * Default dash style property used by tldraw shapes for line styling.
+ * Controls how shape outlines and lines are rendered with different dash patterns.
+ *
+ * Available values:
+ * - `draw` - Hand-drawn, sketchy line style
+ * - `solid` - Continuous solid line
+ * - `dashed` - Evenly spaced dashes
+ * - `dotted` - Evenly spaced dots
+ *
+ * @example
+ * ```ts
+ * import { DefaultDashStyle } from '@tldraw/tlschema'
+ *
+ * // Use in shape props definition
+ * interface MyShapeProps {
+ *   dash: typeof DefaultDashStyle
+ *   // other props...
+ * }
+ *
+ * // Create a shape with dashed outline
+ * const shape = {
+ *   // ... other properties
+ *   props: {
+ *     dash: 'dashed' as const,
+ *     // ... other props
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export const DefaultDashStyle = StyleProp.defineEnum('tldraw:dash', {
 	defaultValue: 'draw',
 	values: ['draw', 'solid', 'dashed', 'dotted'],
 })
 
-/** @public */
+/**
+ * Type representing a default dash style value.
+ * This is a union type of all available dash style options.
+ *
+ * @example
+ * ```ts
+ * import { TLDefaultDashStyle } from '@tldraw/tlschema'
+ *
+ * // Valid dash style values
+ * const drawStyle: TLDefaultDashStyle = 'draw'
+ * const solidStyle: TLDefaultDashStyle = 'solid'
+ * const dashedStyle: TLDefaultDashStyle = 'dashed'
+ * const dottedStyle: TLDefaultDashStyle = 'dotted'
+ *
+ * // Use in a function parameter
+ * function setShapeDash(dash: TLDefaultDashStyle) {
+ *   // Apply dash style to shape
+ * }
+ * ```
+ *
+ * @public
+ */
 export type TLDefaultDashStyle = T.TypeOf<typeof DefaultDashStyle>

package/src/styles/TLFillStyle.ts

@@ -1,11 +1,63 @@
 import { T } from '@tldraw/validate'
 import { StyleProp } from './StyleProp'
 
-/** @public */
+/**
+ * Default fill style property used by tldraw shapes for interior styling.
+ * Controls how the inside of shapes are filled or left empty.
+ *
+ * Available values:
+ * - `none` - No fill, shape interior is transparent
+ * - `semi` - Semi-transparent fill using the shape's color
+ * - `solid` - Solid fill using the shape's color
+ * - `pattern` - Crosshatch pattern fill using the shape's color
+ * - `fill` - Alternative solid fill variant
+ *
+ * @example
+ * ```ts
+ * import { DefaultFillStyle } from '@tldraw/tlschema'
+ *
+ * // Use in shape props definition
+ * interface MyShapeProps {
+ *   fill: typeof DefaultFillStyle
+ *   // other props...
+ * }
+ *
+ * // Create a shape with solid fill
+ * const shape = {
+ *   // ... other properties
+ *   props: {
+ *     fill: 'solid' as const,
+ *     // ... other props
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export const DefaultFillStyle = StyleProp.defineEnum('tldraw:fill', {
 	defaultValue: 'none',
 	values: ['none', 'semi', 'solid', 'pattern', 'fill'],
 })
 
-/** @public */
+/**
+ * Type representing a default fill style value.
+ * This is a union type of all available fill style options.
+ *
+ * @example
+ * ```ts
+ * import { TLDefaultFillStyle } from '@tldraw/tlschema'
+ *
+ * // Valid fill style values
+ * const noFill: TLDefaultFillStyle = 'none'
+ * const solidFill: TLDefaultFillStyle = 'solid'
+ * const patternFill: TLDefaultFillStyle = 'pattern'
+ *
+ * // Use in a function parameter
+ * function setShapeFill(fill: TLDefaultFillStyle) {
+ *   // Apply fill style to shape
+ * }
+ * ```
+ *
+ * @public
+ */
 export type TLDefaultFillStyle = T.TypeOf<typeof DefaultFillStyle>

package/src/styles/TLFontStyle.ts

@@ -1,16 +1,85 @@
 import { T } from '@tldraw/validate'
 import { StyleProp } from './StyleProp'
 
-/** @public */
+/**
+ * Default font style property used by tldraw shapes for text styling.
+ * Controls which typeface is used for text content within shapes.
+ *
+ * Available values:
+ * - `draw` - Hand-drawn, sketchy font style
+ * - `sans` - Clean sans-serif font
+ * - `serif` - Traditional serif font
+ * - `mono` - Monospace font for code-like text
+ *
+ * @example
+ * ```ts
+ * import { DefaultFontStyle } from '@tldraw/tlschema'
+ *
+ * // Use in shape props definition
+ * interface MyTextShapeProps {
+ *   font: typeof DefaultFontStyle
+ *   // other props...
+ * }
+ *
+ * // Create a text shape with monospace font
+ * const textShape = {
+ *   // ... other properties
+ *   props: {
+ *     font: 'mono' as const,
+ *     // ... other props
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export const DefaultFontStyle = StyleProp.defineEnum('tldraw:font', {
 	defaultValue: 'draw',
 	values: ['draw', 'sans', 'serif', 'mono'],
 })
 
-/** @public */
+/**
+ * Type representing a default font style value.
+ * This is a union type of all available font style options.
+ *
+ * @example
+ * ```ts
+ * import { TLDefaultFontStyle } from '@tldraw/tlschema'
+ *
+ * // Valid font style values
+ * const drawFont: TLDefaultFontStyle = 'draw'
+ * const sansFont: TLDefaultFontStyle = 'sans'
+ * const serifFont: TLDefaultFontStyle = 'serif'
+ * const monoFont: TLDefaultFontStyle = 'mono'
+ *
+ * // Use in a function parameter
+ * function setTextFont(font: TLDefaultFontStyle) {
+ *   // Apply font style to text
+ * }
+ * ```
+ *
+ * @public
+ */
 export type TLDefaultFontStyle = T.TypeOf<typeof DefaultFontStyle>
 
-/** @public */
+/**
+ * Mapping of font style names to their corresponding CSS font-family declarations.
+ * These are the actual CSS font families used when rendering text with each font style.
+ *
+ * @example
+ * ```ts
+ * import { DefaultFontFamilies, TLDefaultFontStyle } from '@tldraw/tlschema'
+ *
+ * // Get CSS font family for a font style
+ * const fontStyle: TLDefaultFontStyle = 'mono'
+ * const cssFamily = DefaultFontFamilies[fontStyle] // "'tldraw_mono', monospace"
+ *
+ * // Apply to DOM element
+ * element.style.fontFamily = DefaultFontFamilies.sans
+ * ```
+ *
+ * @public
+ */
 export const DefaultFontFamilies = {
 	draw: "'tldraw_draw', sans-serif",
 	sans: "'tldraw_sans', sans-serif",

package/src/styles/TLHorizontalAlignStyle.ts

@@ -1,11 +1,64 @@
 import { T } from '@tldraw/validate'
 import { StyleProp } from './StyleProp'
 
-/** @public */
+/**
+ * Default horizontal alignment style property used by tldraw shapes for text positioning.
+ * Controls how text content is horizontally aligned within shape boundaries.
+ *
+ * Available values:
+ * - `start` - Align text to the start (left in LTR, right in RTL)
+ * - `middle` - Center text horizontally
+ * - `end` - Align text to the end (right in LTR, left in RTL)
+ * - `start-legacy` - Legacy start alignment (deprecated)
+ * - `end-legacy` - Legacy end alignment (deprecated)
+ * - `middle-legacy` - Legacy middle alignment (deprecated)
+ *
+ * @example
+ * ```ts
+ * import { DefaultHorizontalAlignStyle } from '@tldraw/tlschema'
+ *
+ * // Use in shape props definition
+ * interface MyTextShapeProps {
+ *   align: typeof DefaultHorizontalAlignStyle
+ *   // other props...
+ * }
+ *
+ * // Create a shape with center-aligned text
+ * const textShape = {
+ *   // ... other properties
+ *   props: {
+ *     align: 'middle' as const,
+ *     // ... other props
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export const DefaultHorizontalAlignStyle = StyleProp.defineEnum('tldraw:horizontalAlign', {
 	defaultValue: 'middle',
 	values: ['start', 'middle', 'end', 'start-legacy', 'end-legacy', 'middle-legacy'],
 })
 
-/** @public */
+/**
+ * Type representing a default horizontal alignment style value.
+ * This is a union type of all available horizontal alignment options.
+ *
+ * @example
+ * ```ts
+ * import { TLDefaultHorizontalAlignStyle } from '@tldraw/tlschema'
+ *
+ * // Valid horizontal alignment values
+ * const leftAlign: TLDefaultHorizontalAlignStyle = 'start'
+ * const centerAlign: TLDefaultHorizontalAlignStyle = 'middle'
+ * const rightAlign: TLDefaultHorizontalAlignStyle = 'end'
+ *
+ * // Use in a function parameter
+ * function setTextAlignment(align: TLDefaultHorizontalAlignStyle) {
+ *   // Apply horizontal alignment to text
+ * }
+ * ```
+ *
+ * @public
+ */
 export type TLDefaultHorizontalAlignStyle = T.TypeOf<typeof DefaultHorizontalAlignStyle>

package/src/styles/TLSizeStyle.ts

@@ -1,11 +1,63 @@
 import { T } from '@tldraw/validate'
 import { StyleProp } from './StyleProp'
 
-/** @public */
+/**
+ * Default size style property used by tldraw shapes for scaling visual elements.
+ * Controls the relative size of shape elements like stroke width, text size, and other proportional features.
+ *
+ * Available values:
+ * - `s` - Small size
+ * - `m` - Medium size (default)
+ * - `l` - Large size
+ * - `xl` - Extra large size
+ *
+ * @example
+ * ```ts
+ * import { DefaultSizeStyle } from '@tldraw/tlschema'
+ *
+ * // Use in shape props definition
+ * interface MyShapeProps {
+ *   size: typeof DefaultSizeStyle
+ *   // other props...
+ * }
+ *
+ * // Create a shape with large size
+ * const shape = {
+ *   // ... other properties
+ *   props: {
+ *     size: 'l' as const,
+ *     // ... other props
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export const DefaultSizeStyle = StyleProp.defineEnum('tldraw:size', {
 	defaultValue: 'm',
 	values: ['s', 'm', 'l', 'xl'],
 })
 
-/** @public */
+/**
+ * Type representing a default size style value.
+ * This is a union type of all available size options.
+ *
+ * @example
+ * ```ts
+ * import { TLDefaultSizeStyle } from '@tldraw/tlschema'
+ *
+ * // Valid size values
+ * const smallSize: TLDefaultSizeStyle = 's'
+ * const mediumSize: TLDefaultSizeStyle = 'm'
+ * const largeSize: TLDefaultSizeStyle = 'l'
+ * const extraLargeSize: TLDefaultSizeStyle = 'xl'
+ *
+ * // Use in a function parameter
+ * function setShapeSize(size: TLDefaultSizeStyle) {
+ *   // Apply size style to shape
+ * }
+ * ```
+ *
+ * @public
+ */
 export type TLDefaultSizeStyle = T.TypeOf<typeof DefaultSizeStyle>