microboard-temp 0.6.5 → 0.7.0

package/dist/esm/node.js

@@ -1392,6 +1392,184 @@ var require_css_escape = __commonJS((exports, module) => {
   });
 });
 
+// src/Color/ColorValue.ts
+var SEMANTIC_COLOR_IDS = [
+  "contrastNeutral",
+  "contrastGray",
+  "contrastRed",
+  "contrastOrange",
+  "contrastYellow",
+  "contrastGreen",
+  "contrastTeal",
+  "contrastBlue",
+  "contrastPurple",
+  "contrastPink",
+  "contrastBrown"
+];
+var semanticColor = (id) => ({
+  type: "semantic",
+  id
+});
+var fixedColor = (value) => ({
+  type: "fixed",
+  value
+});
+function coerceColorValue(value) {
+  if (typeof value === "string")
+    return fixedColor(value);
+  return value;
+}
+function coerceOptionalColorValue(value) {
+  if (value === undefined)
+    return;
+  return coerceColorValue(value);
+}
+// src/Color/ContrastPalette.ts
+var CONTRAST_PALETTE = {
+  contrastNeutral: {
+    id: "contrastNeutral",
+    label: "Neutral",
+    light: "rgb(245, 246, 248)",
+    dark: "rgb(20, 21, 26)",
+    contrastRatio: 17.2
+  },
+  contrastGray: {
+    id: "contrastGray",
+    label: "Gray",
+    light: "rgb(224, 225, 229)",
+    dark: "rgb(55, 58, 70)",
+    contrastRatio: 8.6
+  },
+  contrastRed: {
+    id: "contrastRed",
+    label: "Red",
+    light: "rgb(255, 215, 210)",
+    dark: "rgb(120, 10, 10)",
+    contrastRatio: 8.5
+  },
+  contrastOrange: {
+    id: "contrastOrange",
+    label: "Orange",
+    light: "rgb(255, 229, 195)",
+    dark: "rgb(110, 44, 0)",
+    contrastRatio: 8.4
+  },
+  contrastYellow: {
+    id: "contrastYellow",
+    label: "Yellow",
+    light: "rgb(255, 249, 185)",
+    dark: "rgb(89, 71, 0)",
+    contrastRatio: 8.3
+  },
+  contrastGreen: {
+    id: "contrastGreen",
+    label: "Green",
+    light: "rgb(193, 243, 179)",
+    dark: "rgb(0, 74, 22)",
+    contrastRatio: 8.4
+  },
+  contrastTeal: {
+    id: "contrastTeal",
+    label: "Teal",
+    light: "rgb(176, 243, 240)",
+    dark: "rgb(0, 68, 64)",
+    contrastRatio: 8.8
+  },
+  contrastBlue: {
+    id: "contrastBlue",
+    label: "Blue",
+    light: "rgb(208, 222, 255)",
+    dark: "rgb(15, 42, 148)",
+    contrastRatio: 8.7
+  },
+  contrastPurple: {
+    id: "contrastPurple",
+    label: "Purple",
+    light: "rgb(232, 210, 255)",
+    dark: "rgb(62, 0, 132)",
+    contrastRatio: 9.8
+  },
+  contrastPink: {
+    id: "contrastPink",
+    label: "Pink",
+    light: "rgb(255, 212, 228)",
+    dark: "rgb(120, 0, 55)",
+    contrastRatio: 8.5
+  },
+  contrastBrown: {
+    id: "contrastBrown",
+    label: "Brown",
+    light: "rgb(242, 224, 200)",
+    dark: "rgb(74, 33, 0)",
+    contrastRatio: 10.7
+  }
+};
+var CONTRAST_PALETTE_LIST = [
+  CONTRAST_PALETTE.contrastNeutral,
+  CONTRAST_PALETTE.contrastGray,
+  CONTRAST_PALETTE.contrastRed,
+  CONTRAST_PALETTE.contrastOrange,
+  CONTRAST_PALETTE.contrastYellow,
+  CONTRAST_PALETTE.contrastGreen,
+  CONTRAST_PALETTE.contrastTeal,
+  CONTRAST_PALETTE.contrastBlue,
+  CONTRAST_PALETTE.contrastPurple,
+  CONTRAST_PALETTE.contrastPink,
+  CONTRAST_PALETTE.contrastBrown
+];
+// src/Color/resolveColor.ts
+function resolveColor(value, theme, role) {
+  if (typeof value === "string")
+    return value;
+  if (value.type === "fixed") {
+    return value.value;
+  }
+  const pair = CONTRAST_PALETTE[value.id];
+  const lightMode = theme === "light";
+  if (role === "background") {
+    return lightMode ? pair.light : pair.dark;
+  } else {
+    return lightMode ? pair.dark : pair.light;
+  }
+}
+function resolvePairedForeground(background, theme) {
+  if (background.type === "semantic") {
+    return resolveColor(background, theme, "foreground");
+  }
+  return theme === "light" ? CONTRAST_PALETTE.contrastNeutral.dark : CONTRAST_PALETTE.contrastNeutral.light;
+}
+// src/Color/colorUtils.ts
+function srgbChannelToLinear(channel) {
+  const c = channel / 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+function relativeLuminance(r, g, b) {
+  return 0.2126 * srgbChannelToLinear(r) + 0.7152 * srgbChannelToLinear(g) + 0.0722 * srgbChannelToLinear(b);
+}
+function contrastRatio(lum1, lum2) {
+  const lighter = Math.max(lum1, lum2);
+  const darker = Math.min(lum1, lum2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+function meetsWCAG_AA(ratio) {
+  return ratio >= 4.5;
+}
+function meetsWCAG_AAA(ratio) {
+  return ratio >= 7;
+}
+function parseCssRgb(css) {
+  const m = css.match(/rgba?\(\s*(\d+(?:\.\d+)?)\s*,\s*(\d+(?:\.\d+)?)\s*,\s*(\d+(?:\.\d+)?)/);
+  if (!m)
+    return null;
+  return [parseFloat(m[1]), parseFloat(m[2]), parseFloat(m[3])];
+}
+function cssContrastRatio(css1, css2) {
+  const rgb1 = parseCssRgb(css1);
+  const rgb2 = parseCssRgb(css2);
+  if (!rgb1 || !rgb2)
+    return null;
+  return contrastRatio(relativeLuminance(...rgb1), relativeLuminance(...rgb2));
+}
 // src/BoardCommand.ts
 class BoardCommand {
   board;
@@ -1985,12 +2163,14 @@ class Mbr {
   }
   render(context) {
     const { ctx } = context;
-    if (this.backgroundColor !== "none") {
-      ctx.fillStyle = this.backgroundColor;
+    const resolvedBg = typeof this.backgroundColor === "string" ? this.backgroundColor : resolveColor(this.backgroundColor, "light", "background");
+    const resolvedBorder = typeof this.borderColor === "string" ? this.borderColor : resolveColor(this.borderColor, "light", "foreground");
+    if (resolvedBg !== "none") {
+      ctx.fillStyle = resolvedBg;
       ctx.fillRect(this.left, this.top, this.getWidth(), this.getHeight());
     }
     if (this.strokeWidth) {
-      ctx.strokeStyle = this.borderColor;
+      ctx.strokeStyle = resolvedBorder;
       ctx.lineWidth = this.strokeWidth;
       ctx.setLineDash([]);
       ctx.strokeRect(this.left, this.top, this.getWidth(), this.getHeight());
@@ -7549,6 +7729,7 @@ var conf = {
     plus: "Plus",
     plusAI: "PlusAI"
   },
+  theme: "light",
   EVENTS_PUBLISH_INTERVAL: 100,
   EVENTS_RESEND_INTERVAL: 1000,
   SELECTION_COLOR: "rgb(71, 120, 245)",
@@ -39510,7 +39691,7 @@ class Connector2 extends BaseItem {
     this.endPointerStyle = endPointerStyle;
     this.transformation = new Transformation(this.id, this.board.events);
     this.linkTo = new LinkTo(this.id, this.board.events);
-    this.lineColor = lineColor ?? CONNECTOR_COLOR;
+    this.lineColor = lineColor ?? fixedColor(CONNECTOR_COLOR);
     this.lineWidth = lineWidth ?? CONNECTOR_LINE_WIDTH;
     this.borderStyle = strokeStyle ?? CONNECTOR_BORDER_STYLE;
     this.text = new RichText(board, this.getMbr(), this.id, new Transformation, this.linkTo, conf.i18n.t("connector.textPlaceholder", {
@@ -40017,7 +40198,7 @@ class Connector2 extends BaseItem {
     div.style.transformOrigin = "left top";
     div.style.transform = `translate(${translateX}px, ${translateY}px) scale(${scaleX}, ${scaleY})`;
     div.style.position = "absolute";
-    div.setAttribute("data-line-color", this.lineColor);
+    div.setAttribute("data-line-color", resolveColor(this.lineColor, conf.theme, "foreground"));
     div.setAttribute("data-line-width", this.lineWidth.toString());
     div.setAttribute("data-line-style", this.lineStyle);
     div.setAttribute("data-border-style", this.borderStyle);
@@ -40113,7 +40294,9 @@ class Connector2 extends BaseItem {
     this.startPointerStyle = data.startPointerStyle ?? this.startPointerStyle;
     this.endPointerStyle = data.endPointerStyle ?? this.endPointerStyle;
     this.lineStyle = data.lineStyle ?? this.lineStyle;
-    this.lineColor = data.lineColor ?? this.lineColor;
+    if (data.lineColor != null) {
+      this.lineColor = coerceColorValue(data.lineColor);
+    }
     this.lineWidth = data.lineWidth ?? this.lineWidth;
     this.borderStyle = data.borderStyle ?? this.borderStyle;
     if (data.transformation) {
@@ -40206,16 +40389,17 @@ class Connector2 extends BaseItem {
     const endPoint = this.endPoint;
     this.lines = getLine(this.lineStyle, startPoint, endPoint, this.middlePoint).addConnectedItemType(this.itemType);
     this.startPointer = getStartPointer(startPoint, this.startPointerStyle, this.lineStyle, this.lines, this.lineWidth * 0.1 + 0.2);
-    this.startPointer.path.setBorderColor(this.lineColor);
+    const resolvedLineColor = resolveColor(this.lineColor, conf.theme, "foreground");
+    this.startPointer.path.setBorderColor(resolvedLineColor);
     this.startPointer.path.setBorderWidth(this.lineWidth);
-    this.startPointer.path.setBackgroundColor(this.lineColor);
+    this.startPointer.path.setBackgroundColor(resolvedLineColor);
     this.endPointer = getEndPointer(endPoint, this.endPointerStyle, this.lineStyle, this.lines, this.lineWidth * 0.1 + 0.2);
-    this.endPointer.path.setBorderColor(this.lineColor);
+    this.endPointer.path.setBorderColor(resolvedLineColor);
     this.endPointer.path.setBorderWidth(this.lineWidth);
-    this.endPointer.path.setBackgroundColor(this.lineColor);
+    this.endPointer.path.setBackgroundColor(resolvedLineColor);
     this.offsetLines();
     this.lines.setBorderWidth(this.lineWidth);
-    this.lines.setBorderColor(this.lineColor);
+    this.lines.setBorderColor(resolvedLineColor);
     this.lines.setBorderStyle(this.borderStyle);
     this.updateTitle();
   }
@@ -40321,7 +40505,7 @@ class ConnectorData2 {
   startPointerStyle = "None";
   endPointerStyle = "ArrowThin";
   lineStyle = "straight";
-  lineColor = "";
+  lineColor = fixedColor(CONNECTOR_COLOR);
   linkTo;
   lineWidth = 1;
   borderStyle = "solid";
@@ -41014,7 +41198,7 @@ class DefaultShapeData {
   text;
   linkTo;
   itemType = "Shape";
-  constructor(shapeType = "Rectangle", backgroundColor = "none", backgroundOpacity = 1, borderColor = conf.SHAPE_DEFAULT_STROKE_COLOR, borderOpacity = 1, borderStyle = "solid", borderWidth = 1, transformation = new DefaultTransformationData, text5 = new DefaultRichTextData, linkTo) {
+  constructor(shapeType = "Rectangle", backgroundColor = fixedColor("none"), backgroundOpacity = 1, borderColor = fixedColor(conf.SHAPE_DEFAULT_STROKE_COLOR), borderOpacity = 1, borderStyle = "solid", borderWidth = 1, transformation = new DefaultTransformationData, text5 = new DefaultRichTextData, linkTo) {
     this.shapeType = shapeType;
     this.backgroundColor = backgroundColor;
     this.backgroundOpacity = backgroundOpacity;
@@ -41882,9 +42066,13 @@ class Shape extends BaseItem {
     if (data.linkTo) {
       this.linkTo.deserialize(data.linkTo);
     }
-    this.backgroundColor = data.backgroundColor ?? this.backgroundColor;
+    if (data.backgroundColor != null) {
+      this.backgroundColor = coerceColorValue(data.backgroundColor);
+    }
     this.backgroundOpacity = data.backgroundOpacity ?? this.backgroundOpacity;
-    this.borderColor = data.borderColor ?? this.borderColor;
+    if (data.borderColor != null) {
+      this.borderColor = coerceColorValue(data.borderColor);
+    }
     this.borderOpacity = data.borderOpacity ?? this.borderOpacity;
     this.borderStyle = data.borderStyle ?? this.borderStyle;
     this.borderWidth = data.borderWidth ?? this.borderWidth;
@@ -41991,7 +42179,7 @@ class Shape extends BaseItem {
   }
   applyBackgroundColor(backgroundColor) {
     this.backgroundColor = backgroundColor;
-    this.path.setBackgroundColor(backgroundColor);
+    this.path.setBackgroundColor(resolveColor(backgroundColor, conf.theme, "background"));
   }
   setBackgroundColor(backgroundColor) {
     this.emit({
@@ -42027,7 +42215,7 @@ class Shape extends BaseItem {
   }
   applyBorderColor(borderColor) {
     this.borderColor = borderColor;
-    this.path.setBorderColor(borderColor);
+    this.path.setBorderColor(resolveColor(borderColor, conf.theme, "foreground"));
   }
   setBorderColor(borderColor) {
     this.emit({
@@ -42286,7 +42474,7 @@ class StickerData {
   linkTo;
   text;
   itemType = "Sticker";
-  constructor(backgroundColor = stickerColors["Sky Blue"], transformation = new DefaultTransformationData, linkTo, text5 = new DefaultRichTextData([], "center", undefined)) {
+  constructor(backgroundColor = fixedColor(stickerColors["Sky Blue"]), transformation = new DefaultTransformationData, linkTo, text5 = new DefaultRichTextData([], "center", undefined)) {
     this.backgroundColor = backgroundColor;
     this.transformation = transformation;
     this.linkTo = linkTo;
@@ -42398,7 +42586,9 @@ class Sticker extends BaseItem {
     };
   }
   deserialize(data) {
-    this.backgroundColor = data.backgroundColor ?? this.backgroundColor;
+    if (data.backgroundColor != null) {
+      this.backgroundColor = coerceColorValue(data.backgroundColor);
+    }
     if (data.transformation) {
       this.transformation.deserialize(data.transformation);
     }
@@ -42422,7 +42612,7 @@ class Sticker extends BaseItem {
     this.stickerPath.transform(this.transformation.toMatrix());
     this.text.setContainer(this.textContainer.copy());
     this.textContainer.transform(this.transformation.toMatrix());
-    this.stickerPath.setBackgroundColor(this.backgroundColor);
+    this.stickerPath.setBackgroundColor(resolveColor(this.backgroundColor, conf.theme, "background"));
     this.saveStickerData();
   }
   setId(id) {
@@ -42466,7 +42656,7 @@ class Sticker extends BaseItem {
   }
   applyBackgroundColor(backgroundColor) {
     this.backgroundColor = backgroundColor;
-    this.stickerPath.setBackgroundColor(backgroundColor);
+    this.stickerPath.setBackgroundColor(resolveColor(backgroundColor, conf.theme, "background"));
   }
   setBackgroundColor(backgroundColor) {
     this.emit({
@@ -42529,7 +42719,7 @@ class Sticker extends BaseItem {
     const unscaledWidth = itemMbr.getWidth() / scaleX;
     const unscaledHeight = height2 / scaleY;
     div.id = this.getId();
-    div.style.backgroundColor = this.backgroundColor;
+    div.style.backgroundColor = resolveColor(this.backgroundColor, conf.theme, "background");
     div.style.width = `${unscaledWidth}px`;
     div.style.height = `${unscaledHeight}px`;
     div.style.transformOrigin = "top left";
@@ -42803,7 +42993,7 @@ class DefaultFrameData {
   canChangeRatio;
   linkTo;
   itemType = "Frame";
-  constructor(shapeType = "Custom", backgroundColor = FRAME_FILL_COLOR, backgroundOpacity = 1, borderColor = FRAME_BORDER_COLOR, borderOpacity = 0.08, borderStyle = "solid", borderWidth = 0.2, transformation = new DefaultTransformationData, children = [], text5 = new DefaultRichTextData([], "top", 600), canChangeRatio = true, linkTo) {
+  constructor(shapeType = "Custom", backgroundColor = fixedColor(FRAME_FILL_COLOR), backgroundOpacity = 1, borderColor = fixedColor(FRAME_BORDER_COLOR), borderOpacity = 0.08, borderStyle = "solid", borderWidth = 0.2, transformation = new DefaultTransformationData, children = [], text5 = new DefaultRichTextData([], "top", 600), canChangeRatio = true, linkTo) {
     this.shapeType = shapeType;
     this.backgroundColor = backgroundColor;
     this.backgroundOpacity = backgroundOpacity;
@@ -43011,9 +43201,13 @@ class Frame2 extends BaseItem {
       this.initPath();
     }
     this.linkTo.deserialize(data.linkTo);
-    this.backgroundColor = data.backgroundColor ?? this.backgroundColor;
+    if (data.backgroundColor != null) {
+      this.backgroundColor = coerceColorValue(data.backgroundColor);
+    }
     this.backgroundOpacity = data.backgroundOpacity ?? this.backgroundOpacity;
-    this.borderColor = data.borderColor ?? this.borderColor;
+    if (data.borderColor != null) {
+      this.borderColor = coerceColorValue(data.borderColor);
+    }
     this.borderOpacity = data.borderOpacity ?? this.borderOpacity;
     this.borderStyle = data.borderStyle ?? this.borderStyle;
     this.borderWidth = data.borderWidth ?? this.borderWidth;
@@ -43051,9 +43245,9 @@ class Frame2 extends BaseItem {
       this.path.transform(this.transformation.toMatrix());
       this.textContainer.transform(this.transformation.toMatrix());
     }
-    this.path.setBackgroundColor(this.backgroundColor);
+    this.path.setBackgroundColor(resolveColor(this.backgroundColor, conf.theme, "background"));
     this.path.setBackgroundOpacity(this.backgroundOpacity);
-    this.path.setBorderColor(this.borderColor);
+    this.path.setBorderColor(resolveColor(this.borderColor, conf.theme, "foreground"));
     this.path.setBorderWidth(this.borderWidth);
     this.path.setBorderStyle(this.borderStyle);
     this.path.setBorderOpacity(this.borderOpacity);
@@ -43204,7 +43398,7 @@ class Frame2 extends BaseItem {
   }
   applyBackgroundColor(backgroundColor) {
     this.backgroundColor = backgroundColor;
-    this.path.setBackgroundColor(backgroundColor);
+    this.path.setBackgroundColor(resolveColor(backgroundColor, conf.theme, "background"));
   }
   setBackgroundColor(backgroundColor) {
     this.emit({
@@ -43276,9 +43470,9 @@ class Frame2 extends BaseItem {
   renderHTML(documentFactory) {
     const div = documentFactory.createElement("frame-item");
     div.id = this.getId();
-    div.style.backgroundColor = this.backgroundColor;
+    div.style.backgroundColor = resolveColor(this.backgroundColor, conf.theme, "background");
     div.style.opacity = this.backgroundOpacity.toString();
-    div.style.borderColor = this.borderColor;
+    div.style.borderColor = resolveColor(this.borderColor, conf.theme, "foreground");
     div.style.borderWidth = `${this.borderWidth}px`;
     div.style.borderStyle = this.borderStyle;
     const { translateX, translateY, scaleX, scaleY } = this.transformation.getMatrixData();
@@ -44914,6 +45108,7 @@ class Drawing extends BaseItem {
   lines = [];
   linkTo;
   strokeWidth = 1;
+  borderColor = fixedColor(conf.PEN_DEFAULT_COLOR);
   borderStyle = "solid";
   linePattern = scalePatterns(this.strokeWidth)[this.borderStyle];
   borderOpacity = 1;
@@ -44959,7 +45154,7 @@ class Drawing extends BaseItem {
     this.linkTo.deserialize(data.linkTo);
     this.optimizePoints();
     this.transformation.deserialize(data.transformation);
-    this.borderColor = data.strokeStyle;
+    this.borderColor = coerceColorValue(data.strokeStyle);
     this.strokeWidth = data.strokeWidth;
     this.updateGeometry();
     return this;
@@ -45067,7 +45262,7 @@ class Drawing extends BaseItem {
     }
     const ctx = context.ctx;
     ctx.save();
-    ctx.strokeStyle = this.borderColor;
+    ctx.strokeStyle = resolveColor(this.borderColor, conf.theme, "foreground");
     ctx.lineWidth = this.strokeWidth;
     ctx.lineCap = "round";
     ctx.setLineDash(this.linePattern);
@@ -45094,7 +45289,7 @@ class Drawing extends BaseItem {
     svg3.setAttribute("style", "position: absolute; overflow: visible;");
     const pathElement = documentFactory.createElementNS("http://www.w3.org/2000/svg", "path");
     pathElement.setAttribute("d", this.getPathData());
-    pathElement.setAttribute("stroke", this.borderColor);
+    pathElement.setAttribute("stroke", resolveColor(this.borderColor, conf.theme, "foreground"));
     pathElement.setAttribute("stroke-width", `${this.strokeWidth}`);
     pathElement.setAttribute("fill", "none");
     svg3.appendChild(pathElement);
@@ -45187,7 +45382,7 @@ class Drawing extends BaseItem {
       case "Drawing":
         switch (op.method) {
           case "setStrokeColor":
-            this.borderColor = op.color;
+            this.borderColor = coerceColorValue(op.color);
             break;
           case "setStrokeWidth":
             this.strokeWidth = op.width;
@@ -59740,12 +59935,17 @@ export {
   tempStorage,
   tagByType,
   stickerColors,
+  srgbChannelToLinear,
   sha256,
+  semanticColor,
   scalePatterns,
   scaleElementBy,
   rgbToRgba,
+  resolvePairedForeground,
+  resolveColor,
   resizeAndConvertToPng,
   resetElementScale,
+  relativeLuminance,
   registerItem,
   quickAddItem,
   prepareVideo,
@@ -59754,8 +59954,11 @@ export {
   positionRelatively,
   positionAbsolutely,
   parsersHTML,
+  parseCssRgb,
   omitDefaultProperties,
   messageRouter,
+  meetsWCAG_AAA,
+  meetsWCAG_AA,
   itemValidators,
   itemFactories,
   isShallowSimilarTo,
@@ -59782,14 +59985,19 @@ export {
   getControlPointData,
   getBlobFromDataURL,
   forceNumberIntoInterval,
+  fixedColor,
   fileTosha256,
   exportBoardSnapshot,
   editModeHotkeyRegistry,
   decodeHtml,
   defaultCursors as cursors,
+  cssContrastRatio,
   createVideoItem,
   createEvents,
+  contrastRatio,
   conf,
+  coerceOptionalColorValue,
+  coerceColorValue,
   checkHotkeys,
   catmullRomInterpolate,
   captureFrame,
@@ -59815,6 +60023,7 @@ export {
   STEP_STROKE_WIDTH,
   SHAPE_LAST_TYPE_KEY,
   SHAPES_CATEGORIES,
+  SEMANTIC_COLOR_IDS,
   RichText,
   QuadraticBezier,
   Presence,
@@ -59866,6 +60075,8 @@ export {
   Camera,
   CURSORS_IDLE_CLEANUP_DELAY,
   CURSORS_ANIMATION_DURATION,
+  CONTRAST_PALETTE_LIST,
+  CONTRAST_PALETTE,
   CONTEXT_NODE_HIGHLIGHT_COLOR,
   CONNECTOR_POINTER_TYPES,
   BoardSelection,

package/dist/types/Color/ColorValue.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The two display modes. Items using semantic colors automatically adapt
+ * their light/dark variants based on this setting.
+ */
+export type Theme = 'light' | 'dark';
+/**
+ * Which role a color plays in a light/dark pair.
+ * - 'background' → the item's fill / container surface
+ * - 'foreground' → text, strokes, icons drawn on top of the background
+ */
+export type ColorRole = 'background' | 'foreground';
+/**
+ * All semantic color identifiers. Each ID maps to a ContrastPair in the
+ * palette — a light variant and a dark variant that together achieve ≥4.5:1
+ * WCAG AA contrast when used as a background/foreground pair.
+ */
+export declare const SEMANTIC_COLOR_IDS: readonly ["contrastNeutral", "contrastGray", "contrastRed", "contrastOrange", "contrastYellow", "contrastGreen", "contrastTeal", "contrastBlue", "contrastPurple", "contrastPink", "contrastBrown"];
+export type SemanticColorId = (typeof SEMANTIC_COLOR_IDS)[number];
+/**
+ * A theme-aware color that resolves to its light or dark variant at render
+ * time based on the active Theme. Using semantic colors guarantees ≥4.5:1
+ * contrast between any background/foreground pair from the same ID.
+ */
+export interface SemanticColor {
+    readonly type: 'semantic';
+    readonly id: SemanticColorId;
+}
+/**
+ * A literal CSS color string (`rgb(…)`, `#rrggbb`, `rgba(…)`, `"none"`).
+ * Fixed colors do not react to theme changes — they preserve user intent for
+ * branding or artistic purposes.
+ */
+export interface FixedColor {
+    readonly type: 'fixed';
+    readonly value: string;
+}
+/**
+ * The unified color value type used by all item data interfaces.
+ * Replaces the previous bare `string` color fields.
+ */
+export type ColorValue = SemanticColor | FixedColor;
+export declare const semanticColor: (id: SemanticColorId) => SemanticColor;
+export declare const fixedColor: (value: string) => FixedColor;
+/**
+ * Coerce a legacy serialized string or an already-typed ColorValue into a
+ * ColorValue. Strings become FixedColor so that existing boards load without
+ * modification.
+ */
+export declare function coerceColorValue(value: string | ColorValue): ColorValue;
+/**
+ * Coerce a legacy serialized string or ColorValue, allowing undefined
+ * (returns undefined when input is undefined).
+ */
+export declare function coerceOptionalColorValue(value: string | ColorValue | undefined): ColorValue | undefined;

package/dist/types/Color/ContrastPalette.d.ts

@@ -0,0 +1,45 @@
+import { SemanticColorId } from './ColorValue';
+/**
+ * A precomputed pair of sRGB colours for a single semantic ID.
+ *
+ * Light/dark mode rendering rules:
+ *   - Light mode  → `light` = background surface, `dark` = foreground/text
+ *   - Dark mode   → `dark`  = background surface, `light` = foreground/text
+ *
+ * Every pair has been verified to meet WCAG 2.1 AAA (≥7:1 contrast ratio)
+ * between its `light` and `dark` variants.
+ *
+ * CIELAB hue coordinates (a*, b*) are kept consistent between variants so
+ * that the perceptual hue identity is preserved across themes.
+ */
+export interface ContrastPair {
+    readonly id: SemanticColorId;
+    /** Human-readable label for palette UIs. */
+    readonly label: string;
+    /** Light variant — high lightness, used as background in light mode. */
+    readonly light: string;
+    /** Dark variant — low lightness, used as background in dark mode. */
+    readonly dark: string;
+    /**
+     * Pre-verified WCAG contrast ratio between `light` and `dark`.
+     * All values are ≥7.0 (AAA). Stored for fast assertion in tests and
+     * for display in accessibility auditing UIs.
+     */
+    readonly contrastRatio: number;
+}
+/**
+ * The canonical semantic colour palette.
+ *
+ * Values were derived from CIELAB (preserving a*, b* per hue family while
+ * varying L* to ~90 for light and ~22 for dark) and converted to sRGB.
+ * Each pair's contrast ratio was computed via the WCAG relative-luminance
+ * formula and rounded down to one decimal place.
+ *
+ * Yellow/orange dark variants appear brownish — this is intentional.  The
+ * yellow family cannot produce a dark counterpart that is both accessible
+ * (≥4.5:1) *and* looks saturated yellow; a warm brown is the closest
+ * perceptually coherent accessible dark.
+ */
+export declare const CONTRAST_PALETTE: Record<SemanticColorId, ContrastPair>;
+/** Ordered list of semantic colour pairs for display in palette UIs. */
+export declare const CONTRAST_PALETTE_LIST: ContrastPair[];

package/dist/types/Color/colorUtils.d.ts

@@ -0,0 +1,32 @@
+/**
+ * WCAG 2.1 color-contrast utilities.
+ *
+ * All calculations follow the W3C specification:
+ * https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+ */
+/** Convert a single sRGB channel value (0–255) to linear light. */
+export declare function srgbChannelToLinear(channel: number): number;
+/**
+ * Relative luminance of an sRGB colour (channels 0–255).
+ * Returns a value in [0, 1] where 0 = black, 1 = white.
+ */
+export declare function relativeLuminance(r: number, g: number, b: number): number;
+/**
+ * WCAG contrast ratio between two relative luminance values.
+ * Returns a value ≥1 (1 = no contrast, 21 = black on white).
+ */
+export declare function contrastRatio(lum1: number, lum2: number): number;
+/** Returns true if the contrast ratio meets WCAG 2.1 AA (≥4.5:1). */
+export declare function meetsWCAG_AA(ratio: number): boolean;
+/** Returns true if the contrast ratio meets WCAG 2.1 AAA (≥7:1). */
+export declare function meetsWCAG_AAA(ratio: number): boolean;
+/**
+ * Parse an `rgb(r, g, b)` or `rgba(r, g, b, a)` CSS string.
+ * Returns `[r, g, b]` channels in [0, 255], or `null` if unparseable.
+ */
+export declare function parseCssRgb(css: string): [number, number, number] | null;
+/**
+ * Compute the WCAG contrast ratio between two CSS `rgb(…)` strings.
+ * Returns `null` if either string cannot be parsed.
+ */
+export declare function cssContrastRatio(css1: string, css2: string): number | null;

package/dist/types/Color/index.d.ts

@@ -0,0 +1,6 @@
+export type { Theme, ColorRole, SemanticColorId, SemanticColor, FixedColor, ColorValue } from './ColorValue';
+export { SEMANTIC_COLOR_IDS, semanticColor, fixedColor, coerceColorValue, coerceOptionalColorValue } from './ColorValue';
+export type { ContrastPair } from './ContrastPalette';
+export { CONTRAST_PALETTE, CONTRAST_PALETTE_LIST } from './ContrastPalette';
+export { resolveColor, resolvePairedForeground } from './resolveColor';
+export { srgbChannelToLinear, relativeLuminance, contrastRatio, meetsWCAG_AA, meetsWCAG_AAA, parseCssRgb, cssContrastRatio, } from './colorUtils';