origam 2.7.3 → 2.8.0

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

@@ -1,3 +1,4 @@
+import type { TColor, TDirectionBoth } from '../../types';
 /**
  * Format border styles var.
  *
@@ -5,3 +6,61 @@
  * @param type   …
  */
 export declare function formatBorderStylesVar(values: Array<string>, type: string): string[];
+/**
+ * Parse a single per-side border value (`borderTop` / `borderRight` /
+ * `borderBottom` / `borderLeft`, issue #215) into width / style / color
+ * facets.
+ *
+ * Reuses `BORDER_REGEX` — the SAME grammar the global `border` shorthand
+ * parses in `useBorder` — so a value like `"2px dashed red"` resolves
+ * consistently with what `border="2px dashed red"` would produce. Unlike
+ * the global shorthand (which can distribute 1/2/4 values across several
+ * positions, see `formatBorderStylesVar`), a per-side value always
+ * describes exactly ONE side, so each facet resolves to a single token.
+ *
+ * Mirrors the global string-parsing defaults in `useBorder`: an omitted
+ * style defaults to `solid`, an omitted color defaults to `currentColor`
+ * (a bare width alone would otherwise paint nothing — `border-style`
+ * defaults to `none` per the CSS spec). Unlike the global path, an
+ * entirely unparsable / empty value returns `null` instead of emitting
+ * blank declarations — the caller skips emission rather than pushing
+ * `border-top-width: ` onto the style array.
+ */
+export declare function parseBorderPositionValue(value: string): {
+    width: string;
+    style: string;
+    color: string;
+} | null;
+/**
+ * Format the width/style/color facets resolved by `parseBorderPositionValue`
+ * into PHYSICAL per-side CSS declarations (`border-{position}-{type}`).
+ *
+ * Deliberately physical (not logical, unlike `formatBorderStylesVar`'s
+ * 2/4-value output for the global `border` shorthand) — `borderTop` /
+ * `borderRight` / `borderBottom` / `borderLeft` are already named
+ * physically on `IBorderProps`, so the emitted CSS property stays
+ * physical too: no logical/physical mismatch for the consumer to
+ * mentally translate.
+ */
+export declare function formatBorderPositionStylesVar(position: TDirectionBoth, facets: {
+    width?: string;
+    style?: string;
+    color?: string;
+}): Array<string>;
+/**
+ * Resolve a {@link TColor} value (semantic intent | raw CSS color |
+ * gradient | falsy opt-out) into a single CSS color for a
+ * `border-{side}-color` declaration (issue #215's `borderTopColor` /
+ * `borderRightColor` / `borderBottomColor` / `borderLeftColor`).
+ *
+ * A border is a STROKE, not a filled surface — so an intent resolves via
+ * `tokenForegroundForIntent`, the SAME token family the `color` prop
+ * (foreground-only) uses, rather than a background token.
+ *
+ * Gradients are NOT supported: native CSS `border-color` has no gradient
+ * form (only `border-image` does, which is a different, unrelated CSS
+ * property and out of scope for this ticket). A gradient value is
+ * silently ignored — this is documented on `IBorderProps` so it's not a
+ * silent surprise.
+ */
+export declare function resolveBorderSideColor(value: TColor): string | null;

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

@@ -1,3 +1,7 @@
+import { BORDER_REGEX } from "../../consts/index.js";
+import { isEmpty } from "./commons.util.js";
+import { isCssColor, isIntent, tokenForegroundForIntent } from "./color.util.js";
+import { isGradient } from "./gradient.util.js";
 export function formatBorderStylesVar(values, type) {
   const styles = [];
   switch (values.length) {
@@ -17,3 +21,28 @@ export function formatBorderStylesVar(values, type) {
   }
   return styles;
 }
+export function parseBorderPositionValue(value) {
+  const match = BORDER_REGEX.exec(value)?.groups;
+  if (!match) return null;
+  const width = String(match.width ?? "").trim();
+  let style = String(match.style ?? "").trim();
+  let color = String(match.color ?? "").trim();
+  if (isEmpty(width) && isEmpty(style) && isEmpty(color)) return null;
+  if (isEmpty(style)) style = "solid";
+  if (isEmpty(color)) color = "currentColor";
+  return { width, style, color };
+}
+export function formatBorderPositionStylesVar(position, facets) {
+  const styles = [];
+  if (!isEmpty(facets.width)) styles.push(`border-${position}-width: ${facets.width}`);
+  if (!isEmpty(facets.style)) styles.push(`border-${position}-style: ${facets.style}`);
+  if (!isEmpty(facets.color)) styles.push(`border-${position}-color: ${facets.color}`);
+  return styles;
+}
+export function resolveBorderSideColor(value) {
+  if (!value) return null;
+  if (isGradient(value)) return null;
+  if (isIntent(value)) return tokenForegroundForIntent(value);
+  if (typeof value === "string" && isCssColor(value)) return value;
+  return null;
+}

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

@@ -39,6 +39,7 @@ exports.rawBgExprWithState = rawBgExprWithState;
 exports.toHex = toHex;
 exports.tokenForegroundForIntent = tokenForegroundForIntent;
 exports.tokenStylesForIntent = tokenStylesForIntent;
+exports.warnDeprecatedProp = warnDeprecatedProp;
 exports.warnLegacyColor = warnLegacyColor;
 var _consts = require("../../consts/index.cjs");
 var _commons = require("./commons.util.cjs");
@@ -405,4 +406,12 @@ function warnLegacyColor(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.`);
+}
+const _warnedDeprecatedPropKeys = /* @__PURE__ */new Set();
+function warnDeprecatedProp(component, oldProp, newProp, removalVersion = "v3.0.0") {
+  if (typeof console === "undefined") return;
+  const key = `${component}::${oldProp}->${newProp}`;
+  if (_warnedDeprecatedPropKeys.has(key)) return;
+  _warnedDeprecatedPropKeys.add(key);
+  console.warn(`[origam] <${component}> prop "${oldProp}" is deprecated \u2014 use "${newProp}" instead. "${oldProp}" keeps working as an alias and will be removed in ${removalVersion}.`);
 }

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

@@ -274,3 +274,10 @@ export declare function tokenForegroundForIntent(intent: TIntent): string;
  * 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;
+/**
+ * Warn (once per component / old-prop) that the consumer passed a
+ * deprecated prop name where the design system now expects the renamed
+ * one. The deprecated prop keeps working (alias) until the removal
+ * version.
+ */
+export declare function warnDeprecatedProp(component: string, oldProp: string, newProp: string, removalVersion?: string): void;

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

@@ -348,3 +348,13 @@ export function warnLegacyColor(kind, value) {
     `[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.`
   );
 }
+const _warnedDeprecatedPropKeys = /* @__PURE__ */ new Set();
+export function warnDeprecatedProp(component, oldProp, newProp, removalVersion = "v3.0.0") {
+  if (typeof console === "undefined") return;
+  const key = `${component}::${oldProp}->${newProp}`;
+  if (_warnedDeprecatedPropKeys.has(key)) return;
+  _warnedDeprecatedPropKeys.add(key);
+  console.warn(
+    `[origam] <${component}> prop "${oldProp}" is deprecated \u2014 use "${newProp}" instead. "${oldProp}" keeps working as an alias and will be removed in ${removalVersion}.`
+  );
+}

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

@@ -4,7 +4,12 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.formatElevationStyle = formatElevationStyle;
+exports.isCustomBoxShadow = isCustomBoxShadow;
+var _consts = require("../../consts/index.cjs");
 var _utils = require("../../utils/index.cjs");
+function isCustomBoxShadow(value) {
+  return _consts.CUSTOM_BOX_SHADOW_REGEX.test(value.trim());
+}
 function formatElevationStyle(elevation = 0, bgColor) {
   const blurRadius = (0, _utils.roundTo)((0, _utils.normalize)(elevation * 0.04, 0, 1, 0, 16), 1);
   const offsetX = (0, _utils.roundTo)((0, _utils.normalize)(elevation * 0.04, 0, 1, 0, 8), 1);

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

@@ -1,4 +1,14 @@
 import type { TColor } from "../../types";
+/**
+ * Whether a string is a free-form custom `box-shadow` value (not an
+ * origam-native rung name, not a Material 0..24 number) that should be
+ * emitted verbatim as an inline `box-shadow` declaration. Mirrors
+ * `isCustomBorderRadius` (`rounded.util.ts`) — same permissive,
+ * signal-based detection instead of a strict grammar parser.
+ *
+ * @param value …
+ */
+export declare function isCustomBoxShadow(value: string): boolean;
 /**
  * @deprecated Since v0.4 — replaced by the `--origam-shadow-{xs|sm|md|lg|xl}`
  *   design tokens generated from `tokens/primitive.json`. The new

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

@@ -1,4 +1,8 @@
+import { CUSTOM_BOX_SHADOW_REGEX } from "../../consts/index.js";
 import { convertToUnit, HSVtoHSL, isParsableColor, normalize, parseColor, RGBtoHSV, roundTo } from "../../utils/index.js";
+export function isCustomBoxShadow(value) {
+  return CUSTOM_BOX_SHADOW_REGEX.test(value.trim());
+}
 export function formatElevationStyle(elevation = 0, bgColor) {
   const blurRadius = roundTo(normalize(elevation * 0.04, 0, 1, 0, 16), 1);
   const offsetX = roundTo(normalize(elevation * 0.04, 0, 1, 0, 8), 1);

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

@@ -10,6 +10,10 @@ function formatMarginStylesVar(values) {
     case 1:
       styles.push(`margin: ${values[0]}`);
       break;
+    case 2:
+      styles.push(`margin-block: ${values[0]}`);
+      styles.push(`margin-inline: ${values[1]}`);
+      break;
     case 4:
       styles.push(`margin-block-start: ${values[0]}`);
       styles.push(`margin-block-end: ${values[2]}`);

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

@@ -1,6 +1,28 @@
 /**
  * Format margin styles var.
  *
- * @param values …
+ * Accepts 1, 2 or 4 space-separated values (mirrors `formatPaddingStylesVar`):
+ * - **1 value** — shorthand `margin: <v0>`.
+ * - **2 values** — `margin-block: <v0>` (top+bottom) / `margin-inline: <v1>` (left+right).
+ * - **4 values** — logical per-side, see the order note below.
+ *
+ * ⚠️ **4-value order is `Haut/Gauche/Bas/Droite` (Top/Left/Bottom/Right),
+ * NOT the CSS clockwise shorthand order (Top/Right/Bottom/Left).**
+ * This is an **intentional DS convention** (arbitrated in issue #216), not a
+ * bug: values are grouped **by logical axis** (block first, then inline),
+ * which keeps the mapping RTL-safe —
+ * `values[0]` → `margin-block-start`  (top)
+ * `values[1]` → `margin-inline-start` (left in LTR)
+ * `values[2]` → `margin-block-end`    (bottom)
+ * `values[3]` → `margin-inline-end`   (right in LTR)
+ *
+ * Example — do NOT assume CSS clockwise order:
+ * ```ts
+ * // '8px 16px 24px 32px' → top=8px, LEFT=16px, bottom=24px, RIGHT=32px
+ * // (native CSS `margin: 8px 16px 24px 32px` would mean top=8/right=16/bottom=24/left=32 — different!)
+ * formatMarginStylesVar(['8px', '16px', '24px', '32px'])
+ * ```
+ *
+ * @param values Array of 1, 2 or 4 CSS length/keyword strings.
  */
 export declare function formatMarginStylesVar(values: Array<string>): string[];

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

@@ -4,6 +4,10 @@ export function formatMarginStylesVar(values) {
     case 1:
       styles.push(`margin: ${values[0]}`);
       break;
+    case 2:
+      styles.push(`margin-block: ${values[0]}`);
+      styles.push(`margin-inline: ${values[1]}`);
+      break;
     case 4:
       styles.push(`margin-block-start: ${values[0]}`);
       styles.push(`margin-block-end: ${values[2]}`);

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

@@ -1,6 +1,28 @@
 /**
  * Format padding styles var.
  *
- * @param values …
+ * Accepts 1, 2 or 4 space-separated values (mirrors `formatMarginStylesVar`):
+ * - **1 value** — shorthand `padding: <v0>`.
+ * - **2 values** — `padding-block: <v0>` (top+bottom) / `padding-inline: <v1>` (left+right).
+ * - **4 values** — logical per-side, see the order note below.
+ *
+ * ⚠️ **4-value order is `Haut/Gauche/Bas/Droite` (Top/Left/Bottom/Right),
+ * NOT the CSS clockwise shorthand order (Top/Right/Bottom/Left).**
+ * This is an **intentional DS convention** (arbitrated in issue #216), not a
+ * bug: values are grouped **by logical axis** (block first, then inline),
+ * which keeps the mapping RTL-safe —
+ * `values[0]` → `padding-block-start`  (top)
+ * `values[1]` → `padding-inline-start` (left in LTR)
+ * `values[2]` → `padding-block-end`    (bottom)
+ * `values[3]` → `padding-inline-end`   (right in LTR)
+ *
+ * Example — do NOT assume CSS clockwise order:
+ * ```ts
+ * // '8px 16px 24px 32px' → top=8px, LEFT=16px, bottom=24px, RIGHT=32px
+ * // (native CSS `padding: 8px 16px 24px 32px` would mean top=8/right=16/bottom=24/left=32 — different!)
+ * formatPaddingStylesVar(['8px', '16px', '24px', '32px'])
+ * ```
+ *
+ * @param values Array of 1, 2 or 4 CSS length/keyword strings.
  */
 export declare function formatPaddingStylesVar(values: Array<string>): string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "origam",
-  "version": "2.7.3",
+  "version": "2.8.0",
   "type": "module",
   "description": "origam — a Vue 3 design system with multi-theme design tokens, CSS-first components and TypeScript types.",
   "keywords": [