origam 0.3.10 → 2.2.1

package/dist/src/utils/Commons/color.util.cjs

@@ -24,17 +24,27 @@ exports.darken = darken;
 exports.getContrast = getContrast;
 exports.getForeground = getForeground;
 exports.getLuma = getLuma;
+exports.intentBgExpr = intentBgExpr;
+exports.intentFgExpr = intentFgExpr;
+exports.intentTokenBase = intentTokenBase;
 exports.isCssColor = isCssColor;
+exports.isIntent = isIntent;
 exports.isParsableColor = isParsableColor;
+exports.isUtilityIntent = isUtilityIntent;
 exports.lighten = lighten;
 exports.parseColor = parseColor;
 exports.parseGradient = parseGradient;
 exports.parseHex = parseHex;
+exports.rawBgExprWithState = rawBgExprWithState;
 exports.toHex = toHex;
+exports.tokenForegroundForIntent = tokenForegroundForIntent;
+exports.tokenStylesForIntent = tokenStylesForIntent;
+exports.warnLegacyColor = warnLegacyColor;
 var _consts = require("../../consts/index.cjs");
-var _utils = require("../../utils/index.cjs");
+var _commons = require("./commons.util.cjs");
+var _console = require("./console.util.cjs");
 function isCssColor(color) {
-  return !!color && /^(#|var\(--|(rgb|hsl)a?\()/.test(color);
+  return !!color && (/^(#|var\(--|(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\()/i.test(color) || _consts.CSS_NAMED_COLORS.has(color.toLowerCase()));
 }
 function isParsableColor(color) {
   return isCssColor(color) && !/^((rgb|hsl)a?\()?var\(--/.test(color);
@@ -42,7 +52,7 @@ function isParsableColor(color) {
 function parseColor(color) {
   if (typeof color === "number") {
     if (isNaN(color) || color < 0 || color > 16777215) {
-      (0, _utils.consoleWarn)(`'${color}' is not a valid hex color`);
+      (0, _console.consoleWarn)(`'${color}' is not a valid hex color`);
     }
     return {
       r: (color & 16711680) >> 16,
@@ -70,19 +80,19 @@ function parseColor(color) {
     if ([3, 4].includes(hex.length)) {
       hex = hex.split("").map(char => char + char).join("");
     } else if (![6, 8].includes(hex.length)) {
-      (0, _utils.consoleWarn)(`'${color}' is not a valid hex(a) color`);
+      (0, _console.consoleWarn)(`'${color}' is not a valid hex(a) color`);
     }
-    const integer = (0, _utils.int)(hex, 16);
+    const integer = (0, _commons.int)(hex, 16);
     if (isNaN(integer) || integer < 0 || integer > 4294967295) {
-      (0, _utils.consoleWarn)(`'${color}' is not a valid hex(a) color`);
+      (0, _console.consoleWarn)(`'${color}' is not a valid hex(a) color`);
     }
     return HexToRGB(hex);
   } else if (typeof color === "object") {
-    if ((0, _utils.has)(color, ["r", "g", "b"])) {
+    if ((0, _commons.has)(color, ["r", "g", "b"])) {
       return color;
-    } else if ((0, _utils.has)(color, ["h", "s", "l"])) {
+    } else if ((0, _commons.has)(color, ["h", "s", "l"])) {
       return HSVtoRGB(HSLtoHSV(color));
-    } else if ((0, _utils.has)(color, ["h", "s", "v"])) {
+    } else if ((0, _commons.has)(color, ["h", "s", "v"])) {
       return HSVtoRGB(color);
     }
   }
@@ -186,7 +196,7 @@ function RGBtoHex({
 }
 function HexToRGB(hex) {
   hex = parseHex(hex);
-  const [r, g, b, a] = (0, _utils.chunk)(hex, 2).map(c => (0, _utils.int)(c, 16));
+  const [r, g, b, a] = (0, _commons.chunk)(hex, 2).map(c => (0, _commons.int)(c, 16));
   const alpha = a === void 0 ? a : a / 255;
   return {
     r,
@@ -230,7 +240,7 @@ function parseHex(hex) {
     hex = hex.split("").map(x => x + x).join("");
   }
   if (hex.length !== 6) {
-    hex = (0, _utils.padEnd)((0, _utils.padEnd)(hex, 6), 8, "F");
+    hex = (0, _commons.padEnd)((0, _commons.padEnd)(hex, 6), 8, "F");
   }
   return hex;
 }
@@ -279,7 +289,7 @@ function XyzToRgb(xyz) {
   const transform = _consts.SRGB_FORWARD_TRANSFORM;
   const matrix = _consts.SRGB_FORWARD_MATRIX;
   for (let i = 0; i < 3; ++i) {
-    rgb[i] = Math.round((0, _utils.clamp)(transform(matrix[i][0] * xyz[0] + matrix[i][1] * xyz[1] + matrix[i][2] * xyz[2])) * 255);
+    rgb[i] = Math.round((0, _commons.clamp)(transform(matrix[i][0] * xyz[0] + matrix[i][1] * xyz[1] + matrix[i][2] * xyz[2])) * 255);
   }
   return {
     r: rgb[0],
@@ -334,4 +344,63 @@ function APCAcontrast(text, background) {
     outputContrast = SAPC > -_consts.LO_CLIP ? 0 : SAPC > -_consts.LO_CON_THRESH ? SAPC - SAPC * _consts.LO_CON_FACTOR * _consts.LO_CON_OFFSET : SAPC + _consts.LO_CON_OFFSET;
   }
   return outputContrast * 100;
+}
+function isIntent(v) {
+  return typeof v === "string" && _consts.COLOR_INTENTS.has(v);
+}
+function isUtilityIntent(v) {
+  return typeof v === "string" && _consts.COLOR_UTILITY_INTENTS.has(v);
+}
+function intentTokenBase(intent) {
+  if (intent === "neutral") return "action--secondary";
+  if (intent === "success" || intent === "warning" || intent === "danger" || intent === "info") {
+    return `feedback--${intent}`;
+  }
+  return `action--${intent}`;
+}
+function intentBgExpr(intent, role) {
+  const base = intentTokenBase(intent);
+  const baseVar = `var(--origam-color__${base}---bg)`;
+  if (role === "default") return baseVar;
+  if (role === "disabled") return `var(--origam-color__${base}---bgDisabled)`;
+  const pct = role === "hover" ? _consts.COLOR_HOVER_MIX_PCT : _consts.COLOR_ACTIVE_MIX_PCT;
+  const slot = role === "hover" ? "bgHover" : "bgActive";
+  return `var(--origam-color__${base}---${slot}, color-mix(in srgb, ${baseVar}, black ${pct}%))`;
+}
+function intentFgExpr(intent, role) {
+  const base = intentTokenBase(intent);
+  const slot = role === "disabled" ? "fgDisabled" : "fg";
+  return `var(--origam-color__${base}---${slot})`;
+}
+function tokenStylesForIntent(intent, role = "default") {
+  return {
+    "background-color": intentBgExpr(intent, role),
+    color: intentFgExpr(intent, role)
+  };
+}
+function rawBgExprWithState(raw, role) {
+  if (role === "default") return raw;
+  if (role === "disabled") return raw;
+  const pct = role === "hover" ? _consts.COLOR_HOVER_MIX_PCT : _consts.COLOR_ACTIVE_MIX_PCT;
+  return `color-mix(in srgb, ${raw}, black ${pct}%)`;
+}
+function tokenForegroundForIntent(intent) {
+  if (intent === "neutral" || intent === "secondary") {
+    return "var(--origam-color__action--secondary---fg)";
+  }
+  if (intent === "ghost") {
+    return "var(--origam-color__action--ghost---fg)";
+  }
+  if (intent === "success" || intent === "warning" || intent === "danger" || intent === "info") {
+    return `var(--origam-color__feedback--${intent}---fgSubtle)`;
+  }
+  return `var(--origam-color__action--${intent}---fgSubtle)`;
+}
+const _warnedColorKeys = /* @__PURE__ */new Set();
+function warnLegacyColor(kind, value) {
+  if (typeof console === "undefined") return;
+  const key = `${kind}::${value}`;
+  if (_warnedColorKeys.has(key)) return;
+  _warnedColorKeys.add(key);
+  console.warn(`[origam] received a raw color for prop "${kind}" (value: ${value}). Pass a TIntent ('primary' | 'success' | 'warning' | 'danger' | 'info' | 'secondary' | 'ghost' | 'neutral') or use a :style binding for one-off custom colors. Raw color support is deprecated and will be removed in v3.0.0.`);
 }

package/dist/src/utils/Commons/color.util.d.ts

@@ -1,29 +1,276 @@
-import type { TColorType, THex, THSLA, THSVA, TLAB, TRGBA, TXYZ } from '../../types';
+import type { TBgFgRole, TColor, TColorType, THex, THSLA, THSVA, TIntent, TLAB, TRGBA, TXYZ } from '../../types';
+/**
+ * Recognise any string the CSS engine treats as a colour:
+ *   - hex (`#abc`, `#aabbcc`, `#aabbccdd`)
+ *   - functional notation (`rgb()`, `rgba()`, `hsl()`, `hsla()`,
+ *     `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, `color()`)
+ *   - CSS variable (`var(--…)`)
+ *   - one of the 148 named colours OR a CSS-wide keyword
+ *     (`transparent`, `currentColor`, `inherit`, …)
+ */
 export declare function isCssColor(color?: string | null | false): boolean;
+/**
+ * Is parsable color.
+ *
+ * @param color …
+ * @returns …
+ */
 export declare function isParsableColor(color: string): boolean;
+/**
+ * Parse color.
+ *
+ * @param color …
+ * @returns …
+ */
 export declare function parseColor(color: TColorType): TRGBA;
+/**
+ * Get foreground.
+ *
+ * @param color …
+ */
 export declare function getForeground(color: TColorType): "#fff" | "#000";
+/**
+ * Hs lto rgb.
+ *
+ * @param hsla …
+ * @returns …
+ */
 export declare function HSLtoRGB(hsla: THSLA): TRGBA;
+/**
+ * Rg bto hsv.
+ *
+ * @param rgba …
+ * @returns …
+ */
 export declare function RGBtoHSV(rgba: TRGBA): THSVA;
+/**
+ * Hs vto hsl.
+ *
+ * @param hsva …
+ * @returns …
+ */
 export declare function HSVtoHSL(hsva: THSVA): THSLA;
+/**
+ * Hs lto hsv.
+ *
+ * @param hsl …
+ * @returns …
+ */
 export declare function HSLtoHSV(hsl: THSLA): THSVA;
+/**
+ * Rg bto css.
+ *
+ * @param options …
+ * @returns …
+ */
 export declare function RGBtoCSS({ r, g, b, a }: TRGBA): string;
+/**
+ * Hs vto css.
+ *
+ * @param hsva …
+ * @returns …
+ */
 export declare function HSVtoCSS(hsva: THSVA): string;
+/**
+ * To hex.
+ *
+ * @param v …
+ */
 export declare function toHex(v: number): string;
+/**
+ * Rg bto hex.
+ *
+ * @param options …
+ * @returns …
+ */
 export declare function RGBtoHex({ r, g, b, a }: TRGBA): THex;
+/**
+ * Hex to rgb.
+ *
+ * @param hex …
+ * @returns …
+ */
 export declare function HexToRGB(hex: THex): TRGBA;
+/**
+ * Hex to hsv.
+ *
+ * @param hex …
+ * @returns …
+ */
 export declare function HexToHSV(hex: THex): THSVA;
+/**
+ * Hs vto hex.
+ *
+ * @param hsva …
+ * @returns …
+ */
 export declare function HSVtoHex(hsva: THSVA): THex;
+/**
+ * Hs vto rgb.
+ *
+ * @param hsva …
+ * @returns …
+ */
 export declare function HSVtoRGB(hsva: THSVA): TRGBA;
+/**
+ * Parse hex.
+ *
+ * @param hex …
+ * @returns …
+ */
 export declare function parseHex(hex: string): THex;
+/**
+ * Lighten.
+ *
+ * @param value  …
+ * @param amount …
+ * @returns …
+ */
 export declare function lighten(value: TRGBA, amount: number): TRGBA;
+/**
+ * Darken.
+ *
+ * @param value  …
+ * @param amount …
+ * @returns …
+ */
 export declare function darken(value: TRGBA, amount: number): TRGBA;
+/**
+ * Get contrast.
+ *
+ * @param first  …
+ * @param second …
+ */
 export declare function getContrast(first: TColorType, second: TColorType): number;
+/**
+ * Get luma.
+ *
+ * @param color …
+ */
 export declare function getLuma(color: TColorType): number;
+/**
+ * Parse gradient.
+ *
+ * @param gradient …
+ * @param colors   …
+ */
 export declare function parseGradient(gradient: string, colors: Record<string, Record<string, string>>): string;
+/**
+ * Class to hex.
+ *
+ * @param color  …
+ * @param colors …
+ * @returns …
+ */
 export declare function classToHex(color: string, colors: Record<string, Record<string, string>>): string;
+/**
+ * Xyz to rgb.
+ *
+ * @param xyz …
+ * @returns …
+ */
 export declare function XyzToRgb(xyz: TXYZ): TRGBA;
+/**
+ * Rgbto xyz.
+ *
+ * @param options …
+ * @returns …
+ */
 export declare function RgbtoXyz({ r, g, b }: TRGBA): TXYZ;
+/**
+ * Xyzto lab.
+ *
+ * @param xyz …
+ * @returns …
+ */
 export declare function XyztoLab(xyz: TXYZ): TLAB;
+/**
+ * Labto xyz.
+ *
+ * @param lab …
+ * @returns …
+ */
 export declare function LabtoXyz(lab: TLAB): TXYZ;
+/**
+ * Apc acontrast.
+ *
+ * @param text       …
+ * @param background …
+ */
 export declare function APCAcontrast(text: TRGBA, background: TRGBA): number;
+/**
+ * Type guard: is `v` a known semantic intent?
+ */
+export declare function isIntent(v: TColor | TIntent | null | undefined): v is TIntent;
+/**
+ * Type guard: is `v` an intent for which a global utility class ships
+ * (`.origam--bg-<intent>` / `.origam--color-<intent>`)? `ghost` is
+ * intentionally excluded — the design system does not ship
+ * `.origam--bg-ghost`.
+ */
+export declare function isUtilityIntent(v: TColor | TIntent | null | undefined): v is TIntent;
+/**
+ * Resolve the token-base prefix (BEM block + modifier, without the
+ * `--origam-color__` / `---<prop>` envelope) for a given intent.
+ * Drives every other helper below:
+ *
+ *   'neutral'  → 'action--secondary'
+ *   'primary'  → 'action--primary'
+ *   'success'  → 'feedback--success'
+ *   'danger'   → 'feedback--danger'
+ *   …
+ *
+ * Consumed as ``var(--origam-color__${base}---${slot})`` — the BEM
+ * grammar matches the rest of the token namespace (`__` between
+ * domain and block, `--` between block and modifier, `---` before the
+ * property/slot).
+ */
+export declare function intentTokenBase(intent: TIntent): string;
+/**
+ * Emit a state-aware bg expression for an intent:
+ *
+ *   • `default`  → `var(--…-bg)`
+ *   • `hover`    → `var(--…-bgHover, color-mix(in srgb, var(--…-bg), black 20%))`
+ *   • `active`   → `var(--…-bgActive, color-mix(in srgb, var(--…-bg), black 30%))`
+ *   • `disabled` → `var(--…-bgDisabled)`
+ */
+export declare function intentBgExpr(intent: TIntent, role: TBgFgRole): string;
+/**
+ * Foreground stays the same hue across hover / active by design — we
+ * darken the surface around the text, the text itself keeps the
+ * WCAG-paired contrast token.
+ */
+export declare function intentFgExpr(intent: TIntent, role: TBgFgRole): string;
+/**
+ * Build the CSS-vars override map for an intent (foreground + background)
+ * for a given interaction state.
+ */
+export declare function tokenStylesForIntent(intent: TIntent, role?: TBgFgRole): Record<string, string>;
+/**
+ * Derive a state-aware bg from a raw CSS color value (hex/rgb/etc.) via
+ * `color-mix`. Used in the legacy raw-color path so consumers passing
+ * `bgColor="#abcdef"` still get a hover/active darken (matches the
+ * intent path's behaviour, just without the token cascade).
+ */
+export declare function rawBgExprWithState(raw: string, role: TBgFgRole): string;
+/**
+ * Resolve the **foreground-only** colour for an intent — the token used
+ * when the consumer says `color="primary"` and expects the *text itself*
+ * to be primary-coloured (no surface implied).
+ *
+ * This is NOT the same as `tokenStylesForIntent(...).color`:
+ *   - That one returns the WCAG-contrasted text colour to put ON TOP of
+ *     the matching `bg` token (typically white on a dark surface).
+ *   - This helper returns the `fgSubtle` rung — a darker shade of the
+ *     intent itself, designed for "coloured text on a light surface".
+ *
+ * Falls back gracefully on intents without a `fgSubtle` rung
+ * (`secondary`, `ghost`, `neutral`).
+ */
+export declare function tokenForegroundForIntent(intent: TIntent): string;
+/**
+ * Warn (once per prop / value) that the consumer passed a raw CSS color
+ * to a prop where the design system expects a `TIntent`. Raw color
+ * support is deprecated and will be removed in v3.0.0.
+ */
+export declare function warnLegacyColor(kind: 'color' | 'bgColor' | 'hoverColor' | 'hoverBgColor' | 'activeColor' | 'activeBgColor', value: string): void;

package/dist/src/utils/Commons/color.util.js

@@ -4,9 +4,14 @@ import {
   BLK_THRS,
   CIELAB_FORWARD_TRANSFORM,
   CIELAB_REVERSE_TRANSFORM,
+  COLOR_ACTIVE_MIX_PCT,
   COLOR_DELTA_Y_MIN,
+  COLOR_HOVER_MIX_PCT,
+  COLOR_INTENTS,
   COLOR_MAPPERS,
+  COLOR_UTILITY_INTENTS,
   CSS_COLOR_REGEX,
+  CSS_NAMED_COLORS,
   GCO,
   LO_CLIP,
   LO_CON_FACTOR,
@@ -25,9 +30,10 @@ import {
   SRGB_REVERSE_MATRIX,
   SRGB_REVERSE_TRANSFORM
 } from "../../consts/index.js";
-import { chunk, clamp, consoleWarn, has, int, padEnd } from "../../utils/index.js";
+import { chunk, clamp, has, int, padEnd } from "./commons.util.js";
+import { consoleWarn } from "./console.util.js";
 export function isCssColor(color) {
-  return !!color && /^(#|var\(--|(rgb|hsl)a?\()/.test(color);
+  return !!color && (/^(#|var\(--|(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\()/i.test(color) || CSS_NAMED_COLORS.has(color.toLowerCase()));
 }
 export function isParsableColor(color) {
   return isCssColor(color) && !/^((rgb|hsl)a?\()?var\(--/.test(color);
@@ -279,3 +285,64 @@ export function APCAcontrast(text, background) {
   }
   return outputContrast * 100;
 }
+export function isIntent(v) {
+  return typeof v === "string" && COLOR_INTENTS.has(v);
+}
+export function isUtilityIntent(v) {
+  return typeof v === "string" && COLOR_UTILITY_INTENTS.has(v);
+}
+export function intentTokenBase(intent) {
+  if (intent === "neutral") return "action--secondary";
+  if (intent === "success" || intent === "warning" || intent === "danger" || intent === "info") {
+    return `feedback--${intent}`;
+  }
+  return `action--${intent}`;
+}
+export function intentBgExpr(intent, role) {
+  const base = intentTokenBase(intent);
+  const baseVar = `var(--origam-color__${base}---bg)`;
+  if (role === "default") return baseVar;
+  if (role === "disabled") return `var(--origam-color__${base}---bgDisabled)`;
+  const pct = role === "hover" ? COLOR_HOVER_MIX_PCT : COLOR_ACTIVE_MIX_PCT;
+  const slot = role === "hover" ? "bgHover" : "bgActive";
+  return `var(--origam-color__${base}---${slot}, color-mix(in srgb, ${baseVar}, black ${pct}%))`;
+}
+export function intentFgExpr(intent, role) {
+  const base = intentTokenBase(intent);
+  const slot = role === "disabled" ? "fgDisabled" : "fg";
+  return `var(--origam-color__${base}---${slot})`;
+}
+export function tokenStylesForIntent(intent, role = "default") {
+  return {
+    "background-color": intentBgExpr(intent, role),
+    color: intentFgExpr(intent, role)
+  };
+}
+export function rawBgExprWithState(raw, role) {
+  if (role === "default") return raw;
+  if (role === "disabled") return raw;
+  const pct = role === "hover" ? COLOR_HOVER_MIX_PCT : COLOR_ACTIVE_MIX_PCT;
+  return `color-mix(in srgb, ${raw}, black ${pct}%)`;
+}
+export function tokenForegroundForIntent(intent) {
+  if (intent === "neutral" || intent === "secondary") {
+    return "var(--origam-color__action--secondary---fg)";
+  }
+  if (intent === "ghost") {
+    return "var(--origam-color__action--ghost---fg)";
+  }
+  if (intent === "success" || intent === "warning" || intent === "danger" || intent === "info") {
+    return `var(--origam-color__feedback--${intent}---fgSubtle)`;
+  }
+  return `var(--origam-color__action--${intent}---fgSubtle)`;
+}
+const _warnedColorKeys = /* @__PURE__ */ new Set();
+export function warnLegacyColor(kind, value) {
+  if (typeof console === "undefined") return;
+  const key = `${kind}::${value}`;
+  if (_warnedColorKeys.has(key)) return;
+  _warnedColorKeys.add(key);
+  console.warn(
+    `[origam] received a raw color for prop "${kind}" (value: ${value}). Pass a TIntent ('primary' | 'success' | 'warning' | 'danger' | 'info' | 'secondary' | 'ghost' | 'neutral') or use a :style binding for one-off custom colors. Raw color support is deprecated and will be removed in v3.0.0.`
+  );
+}