@bettertui/shared 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026, Localfirstai Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# @bettertui/shared
+
+**Type-only package. Zero runtime code.** The shared vocabulary used by every other package.
+
+## Exports
+
+Types: `NodeId`, `Point`, `Size`, `Rect`, `FlexDirection`, `JustifyContent`, `AlignItems`, `AlignSelf`, `Position`, `Sizing`, `Overflow`, `Padding`, `Margin`, `Inset`, `Gap`, `LayoutConstraints`, `KeyEvent`, `KeyEventSource`, `KeyEventType`, `MouseButton`, `MouseEvent`, `ColorValue`, `Style`, `BorderStyleKind`, `BorderStyle`, `Display`, `FlexWrap`, `ThemeColors`, `ThemeSpacing`, `Theme`, `ValidationError`, `ValidationResult`
+
+Constants: `COLOR_REGEX`, `RGB_REGEX`, `RGBA_REGEX`, `NAMED_COLORS`, `DEFAULT_THEME`, `VALID_ALIGN_ITEMS`, `VALID_ALIGN_SELVES`, `VALID_FLEX_DIRECTIONS`, `VALID_FLEX_WRAPS`, `VALID_JUSTIFY_CONTENTS`, `VALID_OVERFLOWS`, `VALID_POSITIONS`
+
+Functions: `generateId()`, `isValidColor(value)`, `mergeTheme(base, override)`, `validate(layout, style)`, `validateLayoutConstraints(layout)`, `validateStyle(style)`, `warnIfInvalid(layout, style, context?)`
+
+Widget types: `TimelineOptions`, `TweenConfig`
+
+## Notes
+
+- This is the leaf of the dependency graph — depends on nothing internal
+- `@bettertui/core` and `@bettertui/react` re-export these types; consumers should import from those packages (shared is an internal package)

package/index.d.mts

@@ -0,0 +1,361 @@
+//#region src/types/layout.types.d.ts
+/** Direction of the main axis in a flex layout. */
+type FlexDirection = "row" | "column" | "row-reverse" | "column-reverse";
+/** Alignment of children along the main axis. */
+type JustifyContent = "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | "space-evenly";
+/** Alignment of children along the cross axis. */
+type AlignItems = "flex-start" | "center" | "flex-end" | "stretch" | "baseline";
+/** Alignment of multiple lines along the cross axis (multi-line flex containers). */
+type AlignContent = "flex-start" | "center" | "flex-end" | "stretch" | "space-between" | "space-around";
+/** Alignment of a single child along the cross axis, overriding AlignItems. */
+type AlignSelf = "flex-start" | "center" | "flex-end" | "stretch" | "baseline";
+/** Positioning strategy for a layout node. */
+type Position = "relative" | "absolute";
+/** A dimension value — number for fixed columns/rows, string for percentage or calc. */
+type Sizing = number | string;
+/** Behavior when content overflows the container bounds. */
+type Overflow = "visible" | "hidden" | "scroll";
+/** Flex wrap behavior. */
+type FlexWrap = "nowrap" | "wrap";
+/** Display mode. */
+type Display = "flex" | "none";
+/** Shorthand for all four padding sides. */
+interface Padding {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
+/** Shorthand for all four margin sides. */
+interface Margin {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
+/** Shorthand for all four inset offsets (used with absolute positioning). */
+interface Inset {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
+/** Row and column gap values for flex layouts. */
+interface Gap {
+  row?: number;
+  column?: number;
+}
+/** All layout-affecting properties for a UI node. */
+interface LayoutConstraints {
+  display?: Display;
+  flexDirection?: FlexDirection;
+  justifyContent?: JustifyContent;
+  alignItems?: AlignItems;
+  alignSelf?: AlignSelf;
+  flexWrap?: FlexWrap;
+  alignContent?: AlignContent;
+  flexGrow?: number;
+  flexShrink?: number;
+  flexBasis?: Sizing;
+  gap?: number | Gap;
+  padding?: number | Padding;
+  paddingTop?: number;
+  paddingRight?: number;
+  paddingBottom?: number;
+  paddingLeft?: number;
+  margin?: number | Margin;
+  marginTop?: number;
+  marginRight?: number;
+  marginBottom?: number;
+  marginLeft?: number;
+  width?: Sizing;
+  height?: Sizing;
+  minWidth?: Sizing;
+  maxWidth?: Sizing;
+  minHeight?: Sizing;
+  maxHeight?: Sizing;
+  position?: Position;
+  inset?: Inset;
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+  zIndex?: number;
+  visible?: boolean;
+  overflow?: Overflow;
+  /** Layout space reserved for a border (0 or 1 cell per side, used with border-box sizing). */
+  borderTop?: number;
+  borderRight?: number;
+  borderBottom?: number;
+  borderLeft?: number;
+}
+//#endregion
+//#region src/types/events.types.d.ts
+/** Event type for keyboard events. */
+type KeyEventType = "press" | "repeat" | "release";
+/** Source of a keyboard event. */
+type KeyEventSource = "raw" | "kitty";
+/** Mouse button identifier. */
+type MouseButton = "left" | "right" | "middle" | "none" | "scroll_up" | "scroll_down";
+/** A keyboard event from the terminal. */
+interface KeyEvent {
+  /** The key value (e.g. "a", "Enter", "Escape") */
+  key: string;
+  /** Physical key code (e.g. "KeyA", "Enter") */
+  code: string;
+  /** Whether Ctrl was held */
+  ctrl: boolean;
+  /** Whether Shift was held */
+  shift: boolean;
+  /** Whether Alt was held */
+  alt: boolean;
+  /** Whether Meta (Cmd/Windows) was held */
+  meta: boolean;
+  /** Event type: press, repeat, or release */
+  eventType: KeyEventType;
+  /** Source of the event: raw terminal or Kitty keyboard protocol */
+  source: KeyEventSource;
+  /** Whether Super (Cmd/Windows) was held */
+  super?: boolean;
+  /** Whether Hyper was held */
+  hyper?: boolean;
+  /** Whether CapsLock was active */
+  capsLock?: boolean;
+  /** Whether NumLock was active */
+  numLock?: boolean;
+  /** Base layout codepoint for layout-independent shortcut matching */
+  baseCode?: number;
+  /** Whether this is a repeated keypress */
+  repeated?: boolean;
+}
+/** A mouse event from the terminal. */
+interface MouseEvent {
+  button: MouseButton;
+  /** Terminal-grid position where the event occurred */
+  position: {
+    x: number;
+    y: number;
+  };
+  ctrl: boolean;
+  shift: boolean;
+  alt: boolean;
+}
+//#endregion
+//#region src/types/style.types.d.ts
+/** A CSS-like color value: named color, hex, rgb(), or rgba(). */
+type ColorValue = string;
+/** Visual style properties for a UI node. */
+interface Style {
+  /** Foreground (text) color */
+  fg?: ColorValue;
+  /** Background color */
+  bg?: ColorValue;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  dim?: boolean;
+  strikethrough?: boolean;
+  /** Swap foreground and background colors */
+  inverse?: boolean;
+  /** Text alignment */
+  textAlign?: "left" | "center" | "right" | "justify";
+}
+/** All possible border visual styles. */
+type BorderStyleKind = "none" | "solid" | "dashed" | "dotted" | "double";
+/** Border visual configuration. */
+interface BorderStyle {
+  style: BorderStyleKind;
+  /** Border foreground color */
+  fg?: ColorValue;
+}
+//#endregion
+//#region src/types/theme.types.d.ts
+/** Semantic color slots used by a Theme. Matches the Rust engine's ThemeColors struct. */
+interface ThemeColors {
+  /** Primary background for the entire application */
+  background: string;
+  /** Default surface background for containers */
+  surface: string;
+  /** Elevated surface with higher emphasis */
+  surfaceHigh: string;
+  /** Lower-emphasis surface for subtle backgrounds */
+  surfaceLow: string;
+  /** Primary brand color for interactive elements */
+  primary: string;
+  /** Text on primary backgrounds */
+  primaryForeground: string;
+  /** Secondary brand accent */
+  secondary: string;
+  /** Text on secondary backgrounds */
+  secondaryForeground: string;
+  /** Primary text color */
+  text: string;
+  /** Muted text for less prominent content */
+  textMuted: string;
+  /** Dimmed text for placeholders and disabled state */
+  textDim: string;
+  /** Default border color */
+  border: string;
+  /** Border color for focused/active elements */
+  borderFocused: string;
+  /** Accent color for highlights and call-to-actions */
+  accent: string;
+  /** Text on accent backgrounds */
+  accentForeground: string;
+  /** Error/semantic red */
+  error: string;
+  /** Warning/semantic yellow */
+  warning: string;
+  /** Success/semantic green */
+  success: string;
+  /** Info/semantic blue */
+  info: string;
+  /** Scrollbar track background */
+  scrollbar: string;
+  /** Scrollbar thumb (draggable handle) */
+  scrollbarThumb: string;
+}
+/** Spacing scale tokens. Maps to the Rust engine's ThemeSpacing struct. */
+interface ThemeSpacing {
+  none: number;
+  xxs: number;
+  xs: number;
+  sm: number;
+  md: number;
+  lg: number;
+  xl: number;
+  xxl: number;
+}
+/** A complete theme definition. Mirrors the Rust engine's Theme struct exactly. */
+interface Theme {
+  /** Human-readable theme identifier (e.g. "dark", "light") */
+  name: string;
+  colors: ThemeColors;
+  spacing: ThemeSpacing;
+  borders: BorderStyle;
+}
+//#endregion
+//#region src/types/validation.types.d.ts
+/** Describes a single validation failure. */
+interface ValidationError {
+  /** The name of the property that failed validation */
+  field: string;
+  /** Human-readable description of the failure */
+  message: string;
+}
+/** Aggregated result of running validations. */
+interface ValidationResult {
+  /** Whether all validations passed */
+  valid: boolean;
+  /** List of individual validation errors (empty when valid) */
+  errors: ValidationError[];
+}
+//#endregion
+//#region src/consts.d.ts
+/**
+ * The default dark theme.
+ * Values match the Rust engine's `Theme::dark()` output exactly.
+ * Used as the base when no user theme is provided.
+ */
+declare const DEFAULT_THEME: Theme;
+/** Matches hex color strings: #RGB, #RRGGBB, or #RRGGBBAA. */
+declare const COLOR_REGEX: RegExp;
+/** Matches rgb() CSS color strings. */
+declare const RGB_REGEX: RegExp;
+/** Matches rgba() CSS color strings. */
+declare const RGBA_REGEX: RegExp;
+/** Set of CSS named colors supported by the terminal renderer. */
+declare const NAMED_COLORS: Set<string>;
+/** All valid values for FlexDirection. */
+declare const VALID_FLEX_DIRECTIONS: readonly ["row", "column", "row-reverse", "column-reverse"];
+/** All valid values for JustifyContent. */
+declare const VALID_JUSTIFY_CONTENTS: readonly ["flex-start", "center", "flex-end", "space-between", "space-around", "space-evenly"];
+/** All valid values for AlignItems. */
+declare const VALID_ALIGN_ITEMS: readonly ["flex-start", "center", "flex-end", "stretch", "baseline"];
+/** All valid values for AlignSelf. */
+declare const VALID_ALIGN_SELVES: readonly ["flex-start", "center", "flex-end", "stretch", "baseline"];
+/** All valid values for Position. */
+declare const VALID_POSITIONS: readonly ["relative", "absolute"];
+/** All valid values for Overflow. */
+declare const VALID_OVERFLOWS: readonly ["visible", "hidden", "scroll"];
+/** All valid values for flex-wrap. */
+declare const VALID_FLEX_WRAPS: readonly ["nowrap", "wrap"];
+//#endregion
+//#region src/utils.d.ts
+/**
+ * Deep-merge a partial theme into a base theme.
+ * Only the provided keys in each subsection are overridden;
+ * missing keys fall through to the base.
+ *
+ * @param base - The fallback theme (usually DEFAULT_THEME).
+ * @param overrides - Partial theme values to merge in.
+ * @returns A new Theme with overrides applied.
+ */
+declare function mergeTheme(base: Theme, overrides: Partial<Theme>): Theme;
+/**
+ * Check whether a string is a valid CSS-like color value.
+ * Supports named colors, hex (#RGB/#RRGGBB/#RRGGBBAA), rgb(), and rgba().
+ *
+ * @param color - The color string to validate.
+ * @returns True if the color is recognized as valid.
+ */
+declare function isValidColor(color: ColorValue): boolean;
+/**
+ * Validate layout constraint values.
+ * Checks numeric fields for finiteness, percentage strings for valid range,
+ * and enum fields for allowed values.
+ *
+ * @param layout - A partial LayoutConstraints object to validate.
+ * @returns An array of validation errors (empty if valid).
+ */
+declare function validateLayoutConstraints(layout: Partial<LayoutConstraints>): ValidationError[];
+/**
+ * Validate style property values.
+ * Currently checks foreground and background colors.
+ *
+ * @param style - A partial Style object to validate.
+ * @returns An array of validation errors (empty if valid).
+ */
+declare function validateStyle(style: Partial<Style>): ValidationError[];
+/**
+ * Run both layout and style validation, returning an aggregated result.
+ *
+ * @param layout - Optional partial LayoutConstraints to validate.
+ * @param style - Optional partial Style to validate.
+ * @returns A ValidationResult with combined errors.
+ */
+declare function validate(layout?: Partial<LayoutConstraints>, style?: Partial<Style>): ValidationResult;
+/**
+ * Validate props and log a warning to the console if invalid.
+ * No-op in production builds.
+ *
+ * @param layout - Optional partial LayoutConstraints to check.
+ * @param style - Optional partial Style to check.
+ * @param componentName - Optional component name for the warning message.
+ */
+declare function warnIfInvalid(layout?: Partial<LayoutConstraints>, style?: Partial<Style>, componentName?: string): void;
+/**
+ * Generate a unique identifier string.
+ * Each call increments an internal counter and returns the next value.
+ *
+ * @returns A monotonically increasing unique ID string.
+ */
+declare function generateId(): string;
+//#endregion
+//#region src/widget.types.d.ts
+interface TimelineOptions {
+  duration?: number;
+  looping?: boolean;
+  autoPlay?: boolean;
+  onComplete?: () => void;
+}
+interface TweenConfig {
+  from: number;
+  to: number;
+  duration: number;
+  startTime?: number;
+  easing?: string;
+}
+//#endregion
+export { type AlignItems, type AlignSelf, type BorderStyle, type BorderStyleKind, COLOR_REGEX, type ColorValue, DEFAULT_THEME, type Display, type FlexDirection, type FlexWrap, type Gap, type Inset, type JustifyContent, type KeyEvent, type KeyEventSource, type KeyEventType, type LayoutConstraints, type Margin, type MouseButton, type MouseEvent, NAMED_COLORS, type Overflow, type Padding, type Position, RGBA_REGEX, RGB_REGEX, type Sizing, type Style, type Theme, type ThemeColors, type ThemeSpacing, type TimelineOptions, type TweenConfig, VALID_ALIGN_ITEMS, VALID_ALIGN_SELVES, VALID_FLEX_DIRECTIONS, VALID_FLEX_WRAPS, VALID_JUSTIFY_CONTENTS, VALID_OVERFLOWS, VALID_POSITIONS, type ValidationError, type ValidationResult, generateId, isValidColor, mergeTheme, validate, validateLayoutConstraints, validateStyle, warnIfInvalid };
+//# sourceMappingURL=index.d.mts.map

package/index.mjs

@@ -0,0 +1,299 @@
+//#region src/consts.ts
+/**
+* The default dark theme.
+* Values match the Rust engine's `Theme::dark()` output exactly.
+* Used as the base when no user theme is provided.
+*/
+const DEFAULT_THEME = {
+	name: "dark",
+	colors: {
+		background: "#1e1e28",
+		surface: "#1e1e28",
+		surfaceHigh: "#282837",
+		surfaceLow: "#14141c",
+		primary: "#648cdc",
+		primaryForeground: "#ffffff",
+		secondary: "#8c64c8",
+		secondaryForeground: "#ffffff",
+		text: "#dcdce6",
+		textMuted: "#8c8ca0",
+		textDim: "#5a5a69",
+		border: "#3c3c50",
+		borderFocused: "#648cdc",
+		accent: "#50c8a0",
+		accentForeground: "#ffffff",
+		error: "#dc5050",
+		warning: "#dcb43c",
+		success: "#50c878",
+		info: "#50a0dc",
+		scrollbar: "#323241",
+		scrollbarThumb: "#646482"
+	},
+	spacing: {
+		none: 0,
+		xxs: 1,
+		xs: 2,
+		sm: 4,
+		md: 8,
+		lg: 12,
+		xl: 16,
+		xxl: 24
+	},
+	borders: {
+		style: "solid",
+		fg: "#3c3c50"
+	}
+};
+/** Matches hex color strings: #RGB, #RRGGBB, or #RRGGBBAA. */
+const COLOR_REGEX = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+/** Matches rgb() CSS color strings. */
+const RGB_REGEX = /^rgb\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*\)$/;
+/** Matches rgba() CSS color strings. */
+const RGBA_REGEX = /^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*[\d.]+\s*\)$/;
+/** Set of CSS named colors supported by the terminal renderer. */
+const NAMED_COLORS = /* @__PURE__ */ new Set([
+	"black",
+	"white",
+	"red",
+	"green",
+	"blue",
+	"yellow",
+	"cyan",
+	"magenta",
+	"gray",
+	"grey",
+	"transparent"
+]);
+/** All valid values for FlexDirection. */
+const VALID_FLEX_DIRECTIONS = [
+	"row",
+	"column",
+	"row-reverse",
+	"column-reverse"
+];
+/** All valid values for JustifyContent. */
+const VALID_JUSTIFY_CONTENTS = [
+	"flex-start",
+	"center",
+	"flex-end",
+	"space-between",
+	"space-around",
+	"space-evenly"
+];
+/** All valid values for AlignItems. */
+const VALID_ALIGN_ITEMS = [
+	"flex-start",
+	"center",
+	"flex-end",
+	"stretch",
+	"baseline"
+];
+/** All valid values for AlignSelf. */
+const VALID_ALIGN_SELVES = [
+	"flex-start",
+	"center",
+	"flex-end",
+	"stretch",
+	"baseline"
+];
+/** All valid values for Position. */
+const VALID_POSITIONS = ["relative", "absolute"];
+/** All valid values for Overflow. */
+const VALID_OVERFLOWS = [
+	"visible",
+	"hidden",
+	"scroll"
+];
+/** All valid values for flex-wrap. */
+const VALID_FLEX_WRAPS = ["nowrap", "wrap"];
+//#endregion
+//#region src/utils.ts
+/**
+* Deep-merge a partial theme into a base theme.
+* Only the provided keys in each subsection are overridden;
+* missing keys fall through to the base.
+*
+* @param base - The fallback theme (usually DEFAULT_THEME).
+* @param overrides - Partial theme values to merge in.
+* @returns A new Theme with overrides applied.
+*/
+function mergeTheme(base, overrides) {
+	return {
+		...base,
+		...overrides,
+		colors: {
+			...base.colors,
+			...overrides.colors
+		},
+		spacing: {
+			...base.spacing,
+			...overrides.spacing
+		},
+		borders: {
+			...base.borders,
+			...overrides.borders
+		}
+	};
+}
+/**
+* Check whether a string is a valid CSS-like color value.
+* Supports named colors, hex (#RGB/#RRGGBB/#RRGGBBAA), rgb(), and rgba().
+*
+* @param color - The color string to validate.
+* @returns True if the color is recognized as valid.
+*/
+function isValidColor(color) {
+	if (NAMED_COLORS.has(color.toLowerCase())) return true;
+	if (COLOR_REGEX.test(color)) return true;
+	if (RGB_REGEX.test(color)) return true;
+	if (RGBA_REGEX.test(color)) return true;
+	return false;
+}
+/**
+* Validate layout constraint values.
+* Checks numeric fields for finiteness, percentage strings for valid range,
+* and enum fields for allowed values.
+*
+* @param layout - A partial LayoutConstraints object to validate.
+* @returns An array of validation errors (empty if valid).
+*/
+function validateLayoutConstraints(layout) {
+	const errors = [];
+	for (const field of [
+		"flexGrow",
+		"flexShrink",
+		"padding",
+		"margin",
+		"width",
+		"height",
+		"minWidth",
+		"maxWidth",
+		"minHeight",
+		"maxHeight",
+		"top",
+		"right",
+		"bottom",
+		"left",
+		"zIndex"
+	]) {
+		const value = layout[field];
+		if (value !== void 0 && typeof value === "number") {
+			if (Number.isNaN(value) || !Number.isFinite(value)) errors.push({
+				field,
+				message: `${field} must be a finite number`
+			});
+		}
+	}
+	for (const field of [
+		"width",
+		"height",
+		"minWidth",
+		"maxWidth",
+		"minHeight",
+		"maxHeight"
+	]) {
+		const value = layout[field];
+		if (typeof value === "string") if (!value.endsWith("%")) errors.push({
+			field,
+			message: `${field} string value must be a percentage (e.g., "50%")`
+		});
+		else {
+			const num = Number.parseFloat(value);
+			if (Number.isNaN(num) || num < 0 || num > 100) errors.push({
+				field,
+				message: `${field} percentage must be between 0% and 100%`
+			});
+		}
+	}
+	if (layout.flexDirection !== void 0 && !VALID_FLEX_DIRECTIONS.includes(layout.flexDirection)) errors.push({
+		field: "flexDirection",
+		message: `flexDirection must be one of: ${VALID_FLEX_DIRECTIONS.join(", ")}`
+	});
+	if (layout.justifyContent !== void 0 && !VALID_JUSTIFY_CONTENTS.includes(layout.justifyContent)) errors.push({
+		field: "justifyContent",
+		message: `justifyContent must be one of: ${VALID_JUSTIFY_CONTENTS.join(", ")}`
+	});
+	if (layout.alignItems !== void 0 && !VALID_ALIGN_ITEMS.includes(layout.alignItems)) errors.push({
+		field: "alignItems",
+		message: `alignItems must be one of: ${VALID_ALIGN_ITEMS.join(", ")}`
+	});
+	if (layout.alignSelf !== void 0 && !VALID_ALIGN_SELVES.includes(layout.alignSelf)) errors.push({
+		field: "alignSelf",
+		message: `alignSelf must be one of: ${VALID_ALIGN_SELVES.join(", ")}`
+	});
+	if (layout.position !== void 0 && !VALID_POSITIONS.includes(layout.position)) errors.push({
+		field: "position",
+		message: `position must be one of: ${VALID_POSITIONS.join(", ")}`
+	});
+	if (layout.overflow !== void 0 && !VALID_OVERFLOWS.includes(layout.overflow)) errors.push({
+		field: "overflow",
+		message: `overflow must be one of: ${VALID_OVERFLOWS.join(", ")}`
+	});
+	if (layout.flexWrap !== void 0 && !VALID_FLEX_WRAPS.includes(layout.flexWrap)) errors.push({
+		field: "flexWrap",
+		message: `flexWrap must be one of: ${VALID_FLEX_WRAPS.join(", ")}`
+	});
+	return errors;
+}
+/**
+* Validate style property values.
+* Currently checks foreground and background colors.
+*
+* @param style - A partial Style object to validate.
+* @returns An array of validation errors (empty if valid).
+*/
+function validateStyle(style) {
+	const errors = [];
+	if (style.fg !== void 0 && !isValidColor(style.fg)) errors.push({
+		field: "fg",
+		message: `Invalid foreground color: ${style.fg}`
+	});
+	if (style.bg !== void 0 && !isValidColor(style.bg)) errors.push({
+		field: "bg",
+		message: `Invalid background color: ${style.bg}`
+	});
+	return errors;
+}
+/**
+* Run both layout and style validation, returning an aggregated result.
+*
+* @param layout - Optional partial LayoutConstraints to validate.
+* @param style - Optional partial Style to validate.
+* @returns A ValidationResult with combined errors.
+*/
+function validate(layout, style) {
+	const errors = [];
+	if (layout) errors.push(...validateLayoutConstraints(layout));
+	if (style) errors.push(...validateStyle(style));
+	return {
+		valid: errors.length === 0,
+		errors
+	};
+}
+/**
+* Validate props and log a warning to the console if invalid.
+* No-op in production builds.
+*
+* @param layout - Optional partial LayoutConstraints to check.
+* @param style - Optional partial Style to check.
+* @param componentName - Optional component name for the warning message.
+*/
+function warnIfInvalid(layout, style, componentName) {
+	if (process.env["NODE_ENV"] === "production") return;
+	const result = validate(layout, style);
+	if (!result.valid) console.warn(`[${componentName ?? "Component"}] Invalid props:`, result.errors);
+}
+let nextId = 0;
+/**
+* Generate a unique identifier string.
+* Each call increments an internal counter and returns the next value.
+*
+* @returns A monotonically increasing unique ID string.
+*/
+function generateId() {
+	return `${nextId++}`;
+}
+//#endregion
+export { COLOR_REGEX, DEFAULT_THEME, NAMED_COLORS, RGBA_REGEX, RGB_REGEX, VALID_ALIGN_ITEMS, VALID_ALIGN_SELVES, VALID_FLEX_DIRECTIONS, VALID_FLEX_WRAPS, VALID_JUSTIFY_CONTENTS, VALID_OVERFLOWS, VALID_POSITIONS, generateId, isValidColor, mergeTheme, validate, validateLayoutConstraints, validateStyle, warnIfInvalid };
+
+//# sourceMappingURL=index.mjs.map

package/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/consts.ts","../src/utils.ts"],"sourcesContent":["import type { Theme } from \"./types\";\n\n/**\n * The default dark theme.\n * Values match the Rust engine's `Theme::dark()` output exactly.\n * Used as the base when no user theme is provided.\n */\nexport const DEFAULT_THEME: Theme = {\n  name: \"dark\",\n  colors: {\n    background: \"#1e1e28\",\n    surface: \"#1e1e28\",\n    surfaceHigh: \"#282837\",\n    surfaceLow: \"#14141c\",\n    primary: \"#648cdc\",\n    primaryForeground: \"#ffffff\",\n    secondary: \"#8c64c8\",\n    secondaryForeground: \"#ffffff\",\n    text: \"#dcdce6\",\n    textMuted: \"#8c8ca0\",\n    textDim: \"#5a5a69\",\n    border: \"#3c3c50\",\n    borderFocused: \"#648cdc\",\n    accent: \"#50c8a0\",\n    accentForeground: \"#ffffff\",\n    error: \"#dc5050\",\n    warning: \"#dcb43c\",\n    success: \"#50c878\",\n    info: \"#50a0dc\",\n    scrollbar: \"#323241\",\n    scrollbarThumb: \"#646482\",\n  },\n  spacing: {\n    none: 0,\n    xxs: 1,\n    xs: 2,\n    sm: 4,\n    md: 8,\n    lg: 12,\n    xl: 16,\n    xxl: 24,\n  },\n  borders: {\n    style: \"solid\",\n    fg: \"#3c3c50\",\n  },\n};\n\n/** Matches hex color strings: #RGB, #RRGGBB, or #RRGGBBAA. */\nexport const COLOR_REGEX = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;\n\n/** Matches rgb() CSS color strings. */\nexport const RGB_REGEX = /^rgb\\(\\s*\\d+\\s*,\\s*\\d+\\s*,\\s*\\d+\\s*\\)$/;\n\n/** Matches rgba() CSS color strings. */\nexport const RGBA_REGEX = /^rgba\\(\\s*\\d+\\s*,\\s*\\d+\\s*,\\s*\\d+\\s*,\\s*[\\d.]+\\s*\\)$/;\n\n/** Set of CSS named colors supported by the terminal renderer. */\nexport const NAMED_COLORS = new Set([\n  \"black\",\n  \"white\",\n  \"red\",\n  \"green\",\n  \"blue\",\n  \"yellow\",\n  \"cyan\",\n  \"magenta\",\n  \"gray\",\n  \"grey\",\n  \"transparent\",\n]);\n\n/** All valid values for FlexDirection. */\nexport const VALID_FLEX_DIRECTIONS = [\"row\", \"column\", \"row-reverse\", \"column-reverse\"] as const;\n\n/** All valid values for JustifyContent. */\nexport const VALID_JUSTIFY_CONTENTS = [\n  \"flex-start\",\n  \"center\",\n  \"flex-end\",\n  \"space-between\",\n  \"space-around\",\n  \"space-evenly\",\n] as const;\n\n/** All valid values for AlignItems. */\nexport const VALID_ALIGN_ITEMS = [\n  \"flex-start\",\n  \"center\",\n  \"flex-end\",\n  \"stretch\",\n  \"baseline\",\n] as const;\n\n/** All valid values for AlignSelf. */\nexport const VALID_ALIGN_SELVES = [\n  \"flex-start\",\n  \"center\",\n  \"flex-end\",\n  \"stretch\",\n  \"baseline\",\n] as const;\n\n/** All valid values for Position. */\nexport const VALID_POSITIONS = [\"relative\", \"absolute\"] as const;\n\n/** All valid values for Overflow. */\nexport const VALID_OVERFLOWS = [\"visible\", \"hidden\", \"scroll\"] as const;\n\n/** All valid values for flex-wrap. */\nexport const VALID_FLEX_WRAPS = [\"nowrap\", \"wrap\"] as const;\n","import {\n  COLOR_REGEX,\n  NAMED_COLORS,\n  RGBA_REGEX,\n  RGB_REGEX,\n  VALID_ALIGN_ITEMS,\n  VALID_ALIGN_SELVES,\n  VALID_FLEX_DIRECTIONS,\n  VALID_FLEX_WRAPS,\n  VALID_JUSTIFY_CONTENTS,\n  VALID_OVERFLOWS,\n  VALID_POSITIONS,\n} from \"./consts\";\nimport type {\n  ColorValue,\n  LayoutConstraints,\n  Style,\n  Theme,\n  ValidationError,\n  ValidationResult,\n} from \"./types\";\n\n/**\n * Deep-merge a partial theme into a base theme.\n * Only the provided keys in each subsection are overridden;\n * missing keys fall through to the base.\n *\n * @param base - The fallback theme (usually DEFAULT_THEME).\n * @param overrides - Partial theme values to merge in.\n * @returns A new Theme with overrides applied.\n */\nexport function mergeTheme(base: Theme, overrides: Partial<Theme>): Theme {\n  return {\n    ...base,\n    ...overrides,\n    colors: { ...base.colors, ...overrides.colors },\n    spacing: { ...base.spacing, ...overrides.spacing },\n    borders: { ...base.borders, ...overrides.borders },\n  };\n}\n\n/**\n * Check whether a string is a valid CSS-like color value.\n * Supports named colors, hex (#RGB/#RRGGBB/#RRGGBBAA), rgb(), and rgba().\n *\n * @param color - The color string to validate.\n * @returns True if the color is recognized as valid.\n */\nexport function isValidColor(color: ColorValue): boolean {\n  if (NAMED_COLORS.has(color.toLowerCase())) return true;\n  if (COLOR_REGEX.test(color)) return true;\n  if (RGB_REGEX.test(color)) return true;\n  if (RGBA_REGEX.test(color)) return true;\n  return false;\n}\n\n/**\n * Validate layout constraint values.\n * Checks numeric fields for finiteness, percentage strings for valid range,\n * and enum fields for allowed values.\n *\n * @param layout - A partial LayoutConstraints object to validate.\n * @returns An array of validation errors (empty if valid).\n */\nexport function validateLayoutConstraints(layout: Partial<LayoutConstraints>): ValidationError[] {\n  const errors: ValidationError[] = [];\n\n  const numericFields = [\n    \"flexGrow\",\n    \"flexShrink\",\n    \"padding\",\n    \"margin\",\n    \"width\",\n    \"height\",\n    \"minWidth\",\n    \"maxWidth\",\n    \"minHeight\",\n    \"maxHeight\",\n    \"top\",\n    \"right\",\n    \"bottom\",\n    \"left\",\n    \"zIndex\",\n  ] as const;\n\n  for (const field of numericFields) {\n    const value = layout[field];\n    if (value !== undefined && typeof value === \"number\") {\n      if (Number.isNaN(value) || !Number.isFinite(value)) {\n        errors.push({ field, message: `${field} must be a finite number` });\n      }\n    }\n  }\n\n  const percentageFields = [\n    \"width\",\n    \"height\",\n    \"minWidth\",\n    \"maxWidth\",\n    \"minHeight\",\n    \"maxHeight\",\n  ] as const;\n  for (const field of percentageFields) {\n    const value = layout[field];\n    if (typeof value === \"string\") {\n      if (!value.endsWith(\"%\")) {\n        errors.push({ field, message: `${field} string value must be a percentage (e.g., \"50%\")` });\n      } else {\n        const num = Number.parseFloat(value);\n        if (Number.isNaN(num) || num < 0 || num > 100) {\n          errors.push({ field, message: `${field} percentage must be between 0% and 100%` });\n        }\n      }\n    }\n  }\n\n  if (\n    layout.flexDirection !== undefined &&\n    !VALID_FLEX_DIRECTIONS.includes(layout.flexDirection as (typeof VALID_FLEX_DIRECTIONS)[number])\n  ) {\n    errors.push({\n      field: \"flexDirection\",\n      message: `flexDirection must be one of: ${VALID_FLEX_DIRECTIONS.join(\", \")}`,\n    });\n  }\n\n  if (\n    layout.justifyContent !== undefined &&\n    !VALID_JUSTIFY_CONTENTS.includes(\n      layout.justifyContent as (typeof VALID_JUSTIFY_CONTENTS)[number],\n    )\n  ) {\n    errors.push({\n      field: \"justifyContent\",\n      message: `justifyContent must be one of: ${VALID_JUSTIFY_CONTENTS.join(\", \")}`,\n    });\n  }\n\n  if (\n    layout.alignItems !== undefined &&\n    !VALID_ALIGN_ITEMS.includes(layout.alignItems as (typeof VALID_ALIGN_ITEMS)[number])\n  ) {\n    errors.push({\n      field: \"alignItems\",\n      message: `alignItems must be one of: ${VALID_ALIGN_ITEMS.join(\", \")}`,\n    });\n  }\n\n  if (\n    layout.alignSelf !== undefined &&\n    !VALID_ALIGN_SELVES.includes(layout.alignSelf as (typeof VALID_ALIGN_SELVES)[number])\n  ) {\n    errors.push({\n      field: \"alignSelf\",\n      message: `alignSelf must be one of: ${VALID_ALIGN_SELVES.join(\", \")}`,\n    });\n  }\n\n  if (\n    layout.position !== undefined &&\n    !VALID_POSITIONS.includes(layout.position as (typeof VALID_POSITIONS)[number])\n  ) {\n    errors.push({\n      field: \"position\",\n      message: `position must be one of: ${VALID_POSITIONS.join(\", \")}`,\n    });\n  }\n\n  if (\n    layout.overflow !== undefined &&\n    !VALID_OVERFLOWS.includes(layout.overflow as (typeof VALID_OVERFLOWS)[number])\n  ) {\n    errors.push({\n      field: \"overflow\",\n      message: `overflow must be one of: ${VALID_OVERFLOWS.join(\", \")}`,\n    });\n  }\n\n  if (\n    layout.flexWrap !== undefined &&\n    !VALID_FLEX_WRAPS.includes(layout.flexWrap as (typeof VALID_FLEX_WRAPS)[number])\n  ) {\n    errors.push({\n      field: \"flexWrap\",\n      message: `flexWrap must be one of: ${VALID_FLEX_WRAPS.join(\", \")}`,\n    });\n  }\n\n  return errors;\n}\n\n/**\n * Validate style property values.\n * Currently checks foreground and background colors.\n *\n * @param style - A partial Style object to validate.\n * @returns An array of validation errors (empty if valid).\n */\nexport function validateStyle(style: Partial<Style>): ValidationError[] {\n  const errors: ValidationError[] = [];\n\n  if (style.fg !== undefined && !isValidColor(style.fg)) {\n    errors.push({ field: \"fg\", message: `Invalid foreground color: ${style.fg}` });\n  }\n\n  if (style.bg !== undefined && !isValidColor(style.bg)) {\n    errors.push({ field: \"bg\", message: `Invalid background color: ${style.bg}` });\n  }\n\n  return errors;\n}\n\n/**\n * Run both layout and style validation, returning an aggregated result.\n *\n * @param layout - Optional partial LayoutConstraints to validate.\n * @param style - Optional partial Style to validate.\n * @returns A ValidationResult with combined errors.\n */\nexport function validate(\n  layout?: Partial<LayoutConstraints>,\n  style?: Partial<Style>,\n): ValidationResult {\n  const errors: ValidationError[] = [];\n\n  if (layout) {\n    errors.push(...validateLayoutConstraints(layout));\n  }\n\n  if (style) {\n    errors.push(...validateStyle(style));\n  }\n\n  return {\n    valid: errors.length === 0,\n    errors,\n  };\n}\n\n/**\n * Validate props and log a warning to the console if invalid.\n * No-op in production builds.\n *\n * @param layout - Optional partial LayoutConstraints to check.\n * @param style - Optional partial Style to check.\n * @param componentName - Optional component name for the warning message.\n */\nexport function warnIfInvalid(\n  layout?: Partial<LayoutConstraints>,\n  style?: Partial<Style>,\n  componentName?: string,\n): void {\n  if (process.env[\"NODE_ENV\"] === \"production\") return;\n\n  const result = validate(layout, style);\n  if (!result.valid) {\n    const name = componentName ?? \"Component\";\n    console.warn(`[${name}] Invalid props:`, result.errors);\n  }\n}\n\nlet nextId = 0;\n\n/**\n * Generate a unique identifier string.\n * Each call increments an internal counter and returns the next value.\n *\n * @returns A monotonically increasing unique ID string.\n */\nexport function generateId(): string {\n  return `${nextId++}`;\n}\n"],"mappings":";;;;;;AAOA,MAAa,gBAAuB;CAClC,MAAM;CACN,QAAQ;EACN,YAAY;EACZ,SAAS;EACT,aAAa;EACb,YAAY;EACZ,SAAS;EACT,mBAAmB;EACnB,WAAW;EACX,qBAAqB;EACrB,MAAM;EACN,WAAW;EACX,SAAS;EACT,QAAQ;EACR,eAAe;EACf,QAAQ;EACR,kBAAkB;EAClB,OAAO;EACP,SAAS;EACT,SAAS;EACT,MAAM;EACN,WAAW;EACX,gBAAgB;CAClB;CACA,SAAS;EACP,MAAM;EACN,KAAK;EACL,IAAI;EACJ,IAAI;EACJ,IAAI;EACJ,IAAI;EACJ,IAAI;EACJ,KAAK;CACP;CACA,SAAS;EACP,OAAO;EACP,IAAI;CACN;AACF;;AAGA,MAAa,cAAc;;AAG3B,MAAa,YAAY;;AAGzB,MAAa,aAAa;;AAG1B,MAAa,+BAAe,IAAI,IAAI;CAClC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;;AAGD,MAAa,wBAAwB;CAAC;CAAO;CAAU;CAAe;AAAgB;;AAGtF,MAAa,yBAAyB;CACpC;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAa,oBAAoB;CAC/B;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAa,qBAAqB;CAChC;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAa,kBAAkB,CAAC,YAAY,UAAU;;AAGtD,MAAa,kBAAkB;CAAC;CAAW;CAAU;AAAQ;;AAG7D,MAAa,mBAAmB,CAAC,UAAU,MAAM;;;;;;;;;;;;AC/EjD,SAAgB,WAAW,MAAa,WAAkC;CACxE,OAAO;EACL,GAAG;EACH,GAAG;EACH,QAAQ;GAAE,GAAG,KAAK;GAAQ,GAAG,UAAU;EAAO;EAC9C,SAAS;GAAE,GAAG,KAAK;GAAS,GAAG,UAAU;EAAQ;EACjD,SAAS;GAAE,GAAG,KAAK;GAAS,GAAG,UAAU;EAAQ;CACnD;AACF;;;;;;;;AASA,SAAgB,aAAa,OAA4B;CACvD,IAAI,aAAa,IAAI,MAAM,YAAY,CAAC,GAAG,OAAO;CAClD,IAAI,YAAY,KAAK,KAAK,GAAG,OAAO;CACpC,IAAI,UAAU,KAAK,KAAK,GAAG,OAAO;CAClC,IAAI,WAAW,KAAK,KAAK,GAAG,OAAO;CACnC,OAAO;AACT;;;;;;;;;AAUA,SAAgB,0BAA0B,QAAuD;CAC/F,MAAM,SAA4B,CAAC;CAoBnC,KAAK,MAAM,SAAS;EAjBlB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CAG8B,GAAG;EACjC,MAAM,QAAQ,OAAO;EACrB,IAAI,UAAU,KAAA,KAAa,OAAO,UAAU;OACtC,OAAO,MAAM,KAAK,KAAK,CAAC,OAAO,SAAS,KAAK,GAC/C,OAAO,KAAK;IAAE;IAAO,SAAS,GAAG,MAAM;GAA0B,CAAC;EAAA;CAGxE;CAUA,KAAK,MAAM,SAAS;EAPlB;EACA;EACA;EACA;EACA;EACA;CAEiC,GAAG;EACpC,MAAM,QAAQ,OAAO;EACrB,IAAI,OAAO,UAAU,UACnB,IAAI,CAAC,MAAM,SAAS,GAAG,GACrB,OAAO,KAAK;GAAE;GAAO,SAAS,GAAG,MAAM;EAAkD,CAAC;OACrF;GACL,MAAM,MAAM,OAAO,WAAW,KAAK;GACnC,IAAI,OAAO,MAAM,GAAG,KAAK,MAAM,KAAK,MAAM,KACxC,OAAO,KAAK;IAAE;IAAO,SAAS,GAAG,MAAM;GAAyC,CAAC;EAErF;CAEJ;CAEA,IACE,OAAO,kBAAkB,KAAA,KACzB,CAAC,sBAAsB,SAAS,OAAO,aAAuD,GAE9F,OAAO,KAAK;EACV,OAAO;EACP,SAAS,iCAAiC,sBAAsB,KAAK,IAAI;CAC3E,CAAC;CAGH,IACE,OAAO,mBAAmB,KAAA,KAC1B,CAAC,uBAAuB,SACtB,OAAO,cACT,GAEA,OAAO,KAAK;EACV,OAAO;EACP,SAAS,kCAAkC,uBAAuB,KAAK,IAAI;CAC7E,CAAC;CAGH,IACE,OAAO,eAAe,KAAA,KACtB,CAAC,kBAAkB,SAAS,OAAO,UAAgD,GAEnF,OAAO,KAAK;EACV,OAAO;EACP,SAAS,8BAA8B,kBAAkB,KAAK,IAAI;CACpE,CAAC;CAGH,IACE,OAAO,cAAc,KAAA,KACrB,CAAC,mBAAmB,SAAS,OAAO,SAAgD,GAEpF,OAAO,KAAK;EACV,OAAO;EACP,SAAS,6BAA6B,mBAAmB,KAAK,IAAI;CACpE,CAAC;CAGH,IACE,OAAO,aAAa,KAAA,KACpB,CAAC,gBAAgB,SAAS,OAAO,QAA4C,GAE7E,OAAO,KAAK;EACV,OAAO;EACP,SAAS,4BAA4B,gBAAgB,KAAK,IAAI;CAChE,CAAC;CAGH,IACE,OAAO,aAAa,KAAA,KACpB,CAAC,gBAAgB,SAAS,OAAO,QAA4C,GAE7E,OAAO,KAAK;EACV,OAAO;EACP,SAAS,4BAA4B,gBAAgB,KAAK,IAAI;CAChE,CAAC;CAGH,IACE,OAAO,aAAa,KAAA,KACpB,CAAC,iBAAiB,SAAS,OAAO,QAA6C,GAE/E,OAAO,KAAK;EACV,OAAO;EACP,SAAS,4BAA4B,iBAAiB,KAAK,IAAI;CACjE,CAAC;CAGH,OAAO;AACT;;;;;;;;AASA,SAAgB,cAAc,OAA0C;CACtE,MAAM,SAA4B,CAAC;CAEnC,IAAI,MAAM,OAAO,KAAA,KAAa,CAAC,aAAa,MAAM,EAAE,GAClD,OAAO,KAAK;EAAE,OAAO;EAAM,SAAS,6BAA6B,MAAM;CAAK,CAAC;CAG/E,IAAI,MAAM,OAAO,KAAA,KAAa,CAAC,aAAa,MAAM,EAAE,GAClD,OAAO,KAAK;EAAE,OAAO;EAAM,SAAS,6BAA6B,MAAM;CAAK,CAAC;CAG/E,OAAO;AACT;;;;;;;;AASA,SAAgB,SACd,QACA,OACkB;CAClB,MAAM,SAA4B,CAAC;CAEnC,IAAI,QACF,OAAO,KAAK,GAAG,0BAA0B,MAAM,CAAC;CAGlD,IAAI,OACF,OAAO,KAAK,GAAG,cAAc,KAAK,CAAC;CAGrC,OAAO;EACL,OAAO,OAAO,WAAW;EACzB;CACF;AACF;;;;;;;;;AAUA,SAAgB,cACd,QACA,OACA,eACM;CACN,IAAI,QAAQ,IAAI,gBAAgB,cAAc;CAE9C,MAAM,SAAS,SAAS,QAAQ,KAAK;CACrC,IAAI,CAAC,OAAO,OAEV,QAAQ,KAAK,IADA,iBAAiB,YACR,mBAAmB,OAAO,MAAM;AAE1D;AAEA,IAAI,SAAS;;;;;;;AAQb,SAAgB,aAAqB;CACnC,OAAO,GAAG;AACZ"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@bettertui/shared",
+  "version": "0.1.0",
+  "description": "Shared type definitions and protocols for the BetterTUI terminal UI framework",
+  "keywords": [
+    "types",
+    "tui",
+    "terminal",
+    "protocol",
+    "definitions"
+  ],
+  "license": "MIT",
+  "author": "SOUMITRO-SAHA <soumitrosahaofficial@gmail.com>",
+  "homepage": "https://github.com/bettertui/bettertui/tree/main/packages/shared#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bettertui/bettertui.git",
+    "directory": "packages/shared"
+  },
+  "bugs": {
+    "url": "https://github.com/bettertui/bettertui/issues"
+  },
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "type": "module",
+  "main": "./index.mjs",
+  "module": "./index.mjs",
+  "types": "./index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./index.d.mts",
+      "import": "./index.mjs"
+    }
+  }
+}