@primer/primitives 11.4.0-rc.f798df25 → 11.4.1-rc.4e2d1de5

package/dist/build/transformers/utilities/parseDimension.js

@@ -0,0 +1,31 @@
+/**
+ * @description Parses and validates a dimension value in W3C DTCG object format
+ * @param input - The dimension value in W3C object format { value: number, unit: "px" | "rem" | "em" }
+ * @returns Validated DimensionTokenValue
+ * @throws Error if the input is not a valid W3C dimension object
+ *
+ * W3C DTCG format: { value: 16, unit: "px" }
+ * @note `em` is not in the W3C spec but is supported for practical use
+ * @link https://www.designtokens.org/tr/drafts/format/#dimension
+ */
+export const parseDimension = (input) => {
+    // Runtime validation for W3C DTCG object format
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (typeof input !== 'object' || input === null) {
+        throw new Error(`Invalid dimension value: ${JSON.stringify(input)} - must be a W3C DTCG dimension object with "value" and "unit" properties`);
+    }
+    const inputObj = input;
+    if (!('value' in inputObj) || !('unit' in inputObj)) {
+        throw new Error(`Invalid dimension value: ${JSON.stringify(input)} - must be a W3C DTCG dimension object with "value" and "unit" properties`);
+    }
+    const { value, unit } = input;
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`Invalid dimension value: ${JSON.stringify(input)} - value must be a finite number`);
+    }
+    // Runtime check - unit could be invalid at runtime even if types say otherwise
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (unit !== 'px' && unit !== 'rem' && unit !== 'em') {
+        throw new Error(`Invalid dimension unit: ${String(unit)} - must be "px", "rem", or "em"`);
+    }
+    return { value, unit };
+};

package/dist/build/types/dimensionTokenValue.d.ts

@@ -0,0 +1,9 @@
+/**
+ * W3C DTCG dimension token value format
+ * @link https://www.designtokens.org/tr/drafts/format/#dimension
+ * @note `em` is not in the W3C spec but is supported for practical use
+ */
+export type DimensionTokenValue = {
+  value: number
+  unit: 'px' | 'rem' | 'em'
+}

package/dist/css/base/motion/motion.css

@@ -11,8 +11,9 @@
   --base-duration-700: 700ms;
   --base-duration-800: 800ms;
   --base-duration-900: 900ms;
-  --base-easing-easeIn: cubic-bezier(0.7, 0.1, 0.75, 0.9); /** Ideal for movement that starts on the page and ends off the page. */
-  --base-easing-easeInOut: cubic-bezier(0.6, 0, 0.2, 1); /** Ideal for movement that starts and ends on the page. */
-  --base-easing-easeOut: cubic-bezier(0.3, 0.8, 0.6, 1); /** Ideal for movement that starts off the page and ends on the page. */
-  --base-easing-linear: cubic-bezier(0, 0, 1, 1); /** Ideal for non-movement properties, like opacity or background color. */
+  --base-easing-ease: cubic-bezier(0.25, 0.1, 0.25, 1); /** CSS default easing. Use for hover state changes and micro-interactions. */
+  --base-easing-easeIn: cubic-bezier(0.7, 0.1, 0.75, 0.9); /** Accelerating motion. Use for elements exiting the viewport (moving off-screen). */
+  --base-easing-easeInOut: cubic-bezier(0.6, 0, 0.2, 1); /** Smooth acceleration and deceleration. Use for elements moving or morphing within the viewport. */
+  --base-easing-easeOut: cubic-bezier(0.3, 0.8, 0.6, 1); /** Decelerating motion. Use for elements entering the viewport or appearing on screen. */
+  --base-easing-linear: cubic-bezier(0, 0, 1, 1); /** Constant motion with no acceleration. Use for continuous animations like progress bars or loaders. */
 }

package/dist/css/functional/size/border.css

@@ -1,16 +1,11 @@
 :root {
-  --borderRadius-full: 624.9375rem; /** Use this border radius for pill shaped elements */
-  --borderRadius-large: 0.75rem;
-  --borderRadius-medium: 0.375rem;
-  --borderRadius-small: 0.1875rem;
-  --borderWidth-thick: 0.125rem;
-  --borderWidth-thicker: 0.25rem;
-  --borderWidth-thin: 0.0625rem;
-  --outline-focus-offset: -0.125rem;
-  --outline-focus-width: 0.125rem;
-  --borderRadius-default: var(--borderRadius-medium);
-  --borderWidth-default: var(--borderWidth-thin);
-  --boxShadow-thick: inset 0 0 0 var(--borderWidth-thick);
-  --boxShadow-thicker: inset 0 0 0 var(--borderWidth-thicker);
-  --boxShadow-thin: inset 0 0 0 var(--borderWidth-thin); /** Thin shadow for borders */
+  --borderWidth-thick: 0.125rem; /** Thick 2px border for emphasis. Use for focus indicators, selected states, or to emphasize important boundaries */
+  --borderWidth-thicker: 0.25rem; /** Extra thick 4px border for maximum emphasis. Use sparingly for high-contrast focus indicators or critical visual separators */
+  --borderWidth-thin: 0.0625rem; /** Standard 1px border width. Use for most borders, dividers, and outlines throughout the interface */
+  --outline-focus-offset: -0.125rem; /** Focus outline offset (-2px). Negative value creates an inset outline for keyboard focus indicators, ensuring the focus ring stays within the element bounds */
+  --outline-focus-width: 0.125rem; /** Focus outline width (2px). Standard width for keyboard focus indicators to meet WCAG 2.4.7 accessibility requirements */
+  --borderWidth-default: var(--borderWidth-thin); /** Default border width for most UI elements. Alias of borderWidth.thin (1px) */
+  --boxShadow-thick: inset 0 0 0 var(--borderWidth-thick); /** Thick shadow (2px) used instead of a border for emphasis without layout shift */
+  --boxShadow-thicker: inset 0 0 0 var(--borderWidth-thicker); /** Thickest shadow (4px) used for high emphasis borders without layout shift. Use sparingly for maximum visual impact */
+  --boxShadow-thin: inset 0 0 0 var(--borderWidth-thin); /** Thin shadow used instead of a border to prevent layout shift */
 }

package/dist/css/functional/size/radius.css

@@ -0,0 +1,7 @@
+:root {
+  --borderRadius-full: 624.9375rem; /** Use this border radius for pill shaped elements */
+  --borderRadius-large: 0.75rem; /** Large border radius (12px). Use for larger containers, dialogs, or when more visual softness is desired. Always use this for buttons. */
+  --borderRadius-medium: 0.375rem; /** Medium border radius (6px). The default choice for most buttons, cards, and containers */
+  --borderRadius-small: 0.1875rem; /** Small border radius (3px). Use for small variants of components or small UI elements like badges, tags, or anything below 16px in height */
+  --borderRadius-default: var(--borderRadius-medium); /** Default border radius for most UI elements. Alias of borderRadius.medium (6px). Use when in doubt */
+}

package/dist/css/functional/size/size-coarse.css

@@ -1,7 +1,7 @@
 @media (pointer: coarse) {
   :root {
-    --control-minTarget-auto: 2.75rem;
-    --controlStack-medium-gap-auto: 0.75rem;
-    --controlStack-small-gap-auto: 1rem;
+    --control-minTarget-auto: 2.75rem; /** Minimum touch target size for coarse pointer devices (touch screens) */
+    --controlStack-medium-gap-auto: 0.75rem; /** Gap between stacked controls in medium density layouts for touch devices */
+    --controlStack-small-gap-auto: 1rem; /** Gap between stacked controls in small density layouts for touch devices */
   }
 }

package/dist/css/functional/size/size-fine.css

@@ -1,7 +1,7 @@
 @media (pointer: fine) {
   :root {
-    --control-minTarget-auto: 1rem;
-    --controlStack-medium-gap-auto: 0.5rem;
-    --controlStack-small-gap-auto: 0.5rem;
+    --control-minTarget-auto: 1rem; /** Minimum target size for fine pointer devices (mouse) */
+    --controlStack-medium-gap-auto: 0.5rem; /** Gap between stacked controls in medium density layouts for mouse interfaces */
+    --controlStack-small-gap-auto: 0.5rem; /** Gap between stacked controls in small density layouts for mouse interfaces */
   }
 }

package/dist/css/functional/size/viewport.css

@@ -1,6 +1,6 @@
 @custom-media --viewportRange-landscape (orientation: landscape);
 @custom-media --viewportRange-narrow (max-width: calc(48rem - 0.02px));
-@custom-media --viewportRange-narrowLandscape (max-width: calc(63.25rem - 0.02px) and (max-height: calc(34rem - 0.02px)) and (orientation: landscape));
+@custom-media --viewportRange-narrowLandscape ((max-width: calc(63.25rem - 0.02px)) and (max-height: calc(34rem - 0.02px)) and (orientation: landscape));
 @custom-media --viewportRange-portrait (orientation: portrait);
 @custom-media --viewportRange-regular (min-width: 48rem);
 @custom-media --viewportRange-wide (min-width: 87.5rem);