origam 0.3.10 → 2.3.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.`
+  );
+}

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

@@ -1,56 +1,332 @@
 import { ComponentInternalInstance, ComponentPublicInstance, ComputedGetter, InjectionKey, MaybeRef, ToRefs, VNode, VNodeChild } from 'vue';
 import { TClientPosition, TFn, TFocusLocation, TNotAUnion, TSelectItemKey, TTemplateRef, TWrapInArrayResult } from '../../types';
+/**
+ * Convert to unit.
+ *
+ * @param str  …
+ * @param unit …
+ * @returns …
+ */
 export declare function convertToUnit(str: number, unit?: string): string;
 export declare function convertToUnit(str: string | number | null | undefined, unit?: string): string | undefined;
+/**
+ * Ref element.
+ *
+ * @param obj …
+ * @returns …
+ */
 export declare function refElement(obj?: ComponentPublicInstance<any> | HTMLElement): HTMLElement | undefined;
+/**
+ * To kebab case.
+ *
+ * @param str …
+ */
 export declare function toKebabCase(str?: string): string;
 export declare namespace toKebabCase {
     var cache: Map<string, string>;
 }
+/**
+ * Find children with provide.
+ *
+ * @param key   …
+ * @param vnode …
+ * @returns …
+ */
 export declare function findChildrenWithProvide(key: InjectionKey<any> | symbol, vnode?: VNodeChild): Array<ComponentInternalInstance>;
+/**
+ * Destruct computed.
+ *
+ * @param getter …
+ * @returns …
+ */
 export declare function destructComputed<T extends object>(getter: ComputedGetter<T & TNotAUnion<T>>): ToRefs<T>;
+/**
+ * Pad end.
+ *
+ * @param str    …
+ * @param length …
+ * @param char   …
+ */
 export declare function padEnd(str: string, length: number, char?: string): string;
+/**
+ * Pad start.
+ *
+ * @param str    …
+ * @param length …
+ * @param char   …
+ */
 export declare function padStart(str: string, length: number, char?: string): string;
+/**
+ * Clamp.
+ *
+ * @param value …
+ * @param min   …
+ * @param max   …
+ */
 export declare function clamp(value: number, min?: number, max?: number): number;
+/**
+ * Int.
+ *
+ * @param value …
+ * @param radix …
+ * @returns …
+ */
 export declare function int(value: string | number, radix?: number): number;
+/**
+ * Get decimals.
+ *
+ * @param value …
+ */
 export declare function getDecimals(value: number): number;
+/**
+ * Round to.
+ *
+ * @param value  …
+ * @param places …
+ */
 export declare function roundTo(value: number, places?: number): number;
+/**
+ * Chunk.
+ *
+ * @param str  …
+ * @param size …
+ */
 export declare function chunk(str: string, size?: number): string[];
+/**
+ * Has.
+ *
+ * @param obj …
+ * @param key …
+ * @returns …
+ */
 export declare function has<T extends string>(obj: object, key: Array<T>): obj is Record<T, unknown>;
+/**
+ * Oops.
+ *
+ * @returns …
+ */
 export declare function oops(): never;
+/**
+ * Noop.
+ */
 export declare function noop(): void;
+/**
+ * Debounce.
+ *
+ * @param fn …
+ */
 export declare function debounce(fn: (...args: any[]) => void, delay: MaybeRef<number>): {
     (...args: any[]): void;
     clear(): void;
     immediate: (...args: any[]) => void;
 };
+/**
+ * Deep equal.
+ *
+ * @param a …
+ * @param b …
+ * @returns …
+ */
 export declare function deepEqual(a: any, b: any): boolean;
+/**
+ * Get property from item.
+ *
+ * @param item     …
+ * @param property …
+ * @param fallback …
+ * @returns …
+ */
 export declare function getPropertyFromItem(item: any, property: TSelectItemKey, fallback?: any): any;
+/**
+ * Get object value by path.
+ *
+ * @param obj      …
+ * @param path     …
+ * @param fallback …
+ * @returns …
+ */
 export declare function getObjectValueByPath(obj: any, path?: string | null, fallback?: any): any;
+/**
+ * Get nested value.
+ *
+ * @param obj      …
+ * @param path     …
+ * @param fallback …
+ * @returns …
+ */
 export declare function getNestedValue(obj: any, path: Array<(string | number)>, fallback?: any): any;
+/**
+ * Keys.
+ *
+ * @param o …
+ */
 export declare function keys<O extends Record<string, unknown>>(o: O): (keyof O)[];
+/**
+ * Omit.
+ *
+ * @param obj     …
+ * @param exclude …
+ * @returns …
+ */
 export declare function omit<T extends object, U extends Extract<keyof T, string>>(obj: T, exclude: Array<U>): Omit<T, U>;
+/**
+ * Only.
+ *
+ * @param obj     …
+ * @param include …
+ * @returns …
+ */
 export declare function only<T extends object, U extends Extract<keyof T, string>>(obj: T, include: Array<U>): Pick<T, U>;
+/**
+ * Pick.
+ *
+ * @param obj   …
+ * @param paths …
+ * @returns …
+ */
 export declare function pick<T extends object, U extends Extract<keyof T, string>>(obj: T, paths: Array<U>): Pick<T, U>;
+/**
+ * Pick with rest.
+ *
+ * @param obj     …
+ * @param paths   …
+ * @param exclude …
+ * @returns …
+ */
 export declare function pickWithRest<T extends object, U extends Extract<keyof T, string>, E extends Extract<keyof T, string>>(obj: T, paths: Array<(U | RegExp)>, exclude?: Array<E>): [yes: Partial<T>, no: Partial<T>];
+/**
+ * Focus child.
+ *
+ * @param el       …
+ * @param location …
+ */
 export declare function focusChild(el: Element, location?: TFocusLocation): void;
+/**
+ * Focusable children.
+ *
+ * @param el               …
+ * @param filterByTabIndex …
+ */
 export declare function focusableChildren(el: Element, filterByTabIndex?: boolean): Array<HTMLElement>;
+/**
+ * Get next element.
+ *
+ * @param elements  …
+ * @param location  …
+ * @param condition …
+ */
 export declare function getNextElement(elements: Array<HTMLElement>, location?: 'next' | 'prev', condition?: (el: HTMLElement) => boolean): any;
+/**
+ * Human readable file size.
+ *
+ * @param bytes …
+ * @param base  …
+ * @returns …
+ */
 export declare function humanReadableFileSize(bytes: number, base?: 1000 | 1024): string;
+/**
+ * Has event.
+ *
+ * @param props …
+ * @param name  …
+ */
 export declare function hasEvent(props: Record<string, any>, name: string): boolean;
+/**
+ * Flatten fragments.
+ *
+ * @param nodes …
+ * @returns …
+ */
 export declare function flattenFragments(nodes: Array<VNode>): Array<VNode>;
+/**
+ * Is object.
+ *
+ * @param obj …
+ * @returns …
+ */
 export declare function isObject(obj: any): obj is object;
+/**
+ * Merge deep.
+ *
+ * @param source  …
+ * @param target  …
+ * @param arrayFn …
+ */
 export declare function mergeDeep(source?: Record<string, unknown>, target?: Record<string, unknown>, arrayFn?: (a: Array<unknown>, b: Array<unknown>) => Array<unknown>): Record<string, unknown>;
+/**
+ * Defer.
+ *
+ * @param timeout …
+ * @param cb      …
+ */
 export declare function defer(timeout: number, cb: () => void): () => void;
+/**
+ * Matches selector.
+ *
+ * @param el       …
+ * @param selector …
+ * @returns …
+ */
 export declare function matchesSelector(el: Element | undefined, selector: string): boolean | null;
+/**
+ * Is on.
+ *
+ * @param key …
+ */
 export declare function isOn(key: string): boolean;
+/**
+ * Event name.
+ *
+ * @param propName …
+ */
 export declare function eventName(propName: string): string;
+/**
+ * Wrap in array.
+ *
+ * @param v …
+ * @returns …
+ */
 export declare function wrapInArray<T>(v: T | null | undefined): TWrapInArrayResult<T>;
+/**
+ * Template ref.
+ */
 export declare function templateRef(): TTemplateRef;
+/**
+ * Get position.
+ *
+ * @param e        …
+ * @param position …
+ * @returns …
+ */
 export declare function getPosition(e: MouseEvent | TouchEvent, position: TClientPosition): number;
+/**
+ * Add window listener.
+ *
+ * @param event                 …
+ * @param listener              …
+ * @param onUnmountedCleanupFns …
+ */
 export declare function addWindowListener(event: string, listener: EventListenerOrEventListenerObject, onUnmountedCleanupFns?: any): () => void;
+/**
+ * Is empty.
+ *
+ * @param val …
+ * @returns …
+ */
 export declare function isEmpty(val: any): boolean;
+/**
+ * Create range.
+ *
+ * @param length …
+ * @param start  …
+ * @returns …
+ */
 export declare function createRange(length: number, start?: number): number[];
+/**
+ * Get event coordinates.
+ *
+ * @param e …
+ */
 export declare function getEventCoordinates(e: MouseEvent | TouchEvent): {
     clientX: number;
     clientY: number;
@@ -69,4 +345,13 @@ export declare function tryOnMounted(fn: TFn, sync?: boolean, target?: any): voi
  * @param fn
  */
 export declare function tryOnScopeDispose(fn: TFn): boolean;
+/**
+ * Normalize.
+ *
+ * @param number          …
+ * @param currentScaleMin …
+ * @param currentScaleMax …
+ * @param newScaleMin     …
+ * @param newScaleMax     …
+ */
 export declare function normalize(number: number, currentScaleMin: number, currentScaleMax: number, newScaleMin?: number, newScaleMax?: number): number;