@ariaui/shadow 0.1.4 → 0.1.6

package/dist/index.d.cts

@@ -0,0 +1,287 @@
+import { OklchColor } from '@ariaui/color';
+
+/**
+ * A single layer of a box-shadow.
+ *
+ * Color is stored as a structured `OklchColor` from `@ariaui/color`,
+ * enabling programmatic manipulation (opacity, hue, lightness).
+ */
+interface ShadowLayer {
+    /** Horizontal offset, e.g. `"0px"` */
+    readonly offsetX: string;
+    /** Vertical offset, e.g. `"4px"` */
+    readonly offsetY: string;
+    /** Blur radius, e.g. `"6px"` */
+    readonly blur: string;
+    /** Spread radius, e.g. `"-1px"` */
+    readonly spread: string;
+    /** Layer color as an OKLCH color object */
+    readonly color: OklchColor;
+    /** Whether this is an inset shadow */
+    readonly inset: boolean;
+}
+/**
+ * A composite shadow made of one or more layers.
+ */
+interface Shadow {
+    readonly layers: readonly ShadowLayer[];
+}
+/**
+ * Focus ring configuration.
+ *
+ * Produces a double box-shadow: inner gap ring (`bgColor`) +
+ * outer colored ring (`ringColor`).
+ */
+interface FocusRing {
+    /** Ring stroke width, e.g. `"2px"` */
+    readonly ringWidth: string;
+    /** Gap between element edge and ring, e.g. `"2px"` */
+    readonly ringOffset: string;
+    /** Ring color */
+    readonly ringColor: OklchColor;
+    /** Gap color (usually the page background) */
+    readonly bgColor: OklchColor;
+}
+/** Named elevation levels matching the token shadow sizes. */
+type ElevationLevel = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+/**
+ * Configuration for creating a custom elevation scale.
+ */
+interface ElevationConfig {
+    /** Shadow base color (default: black `{ l: 0, c: 0, h: 0, alpha: 1 }`) */
+    readonly color?: OklchColor;
+    /** Multiply all layer alphas (e.g. 1.5 for dark mode) */
+    readonly alphaMultiplier?: number;
+}
+
+/**
+ * Parse a CSS `box-shadow` value into a `Shadow` object.
+ *
+ * Supports multiple comma-separated layers, `inset` keyword,
+ * and common color formats: `rgba()`, `oklch()`, hex, and named colors.
+ *
+ * @example
+ * parseShadow("0px 1px 2px 0px rgba(0,0,0,0.05)")
+ * parseShadow("inset 0 2px 4px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06)")
+ */
+declare function parseShadow(css: string): Shadow;
+/**
+ * Parse a single box-shadow layer string into a `ShadowLayer`.
+ *
+ * @example
+ * parseLayer("0px 4px 6px -1px rgba(0,0,0,0.1)")
+ * parseLayer("inset 0 2px 4px 0px oklch(0% 0 0 / 0.08)")
+ */
+declare function parseLayer(css: string): ShadowLayer;
+
+/**
+ * Create a shadow layer with sensible defaults.
+ *
+ * @example
+ * createLayer({ offsetY: "4px", blur: "6px", color: { l: 0, c: 0, h: 0, alpha: 0.1 } })
+ */
+declare function createLayer(config?: Partial<ShadowLayer>): ShadowLayer;
+/**
+ * Scale a layer's geometry (offsets, blur, spread) by a factor.
+ * Color and inset are preserved.
+ *
+ * @example
+ * scaleLayer(layer, 2)  // doubles all offsets, blur, and spread
+ */
+declare function scaleLayer(layer: ShadowLayer, factor: number): ShadowLayer;
+/**
+ * Replace the color of a layer.
+ */
+declare function setLayerColor(layer: ShadowLayer, color: OklchColor): ShadowLayer;
+/**
+ * Set the alpha (opacity) of a layer's color.
+ */
+declare function setLayerOpacity(layer: ShadowLayer, alpha: number): ShadowLayer;
+/**
+ * Shift a layer's offset.
+ *
+ * @example
+ * offsetLayer(layer, { x: "2px", y: "4px" })
+ */
+declare function offsetLayer(layer: ShadowLayer, offset: {
+    x?: string;
+    y?: string;
+}): ShadowLayer;
+/**
+ * Toggle or set the inset flag.
+ */
+declare function insetLayer(layer: ShadowLayer, inset?: boolean): ShadowLayer;
+
+/**
+ * Create a `Shadow` from one or more layers.
+ *
+ * @example
+ * createShadow(
+ *   createLayer({ offsetY: "1px", blur: "2px" }),
+ *   createLayer({ offsetY: "4px", blur: "6px", spread: "-1px" }),
+ * )
+ */
+declare function createShadow(...layers: ShadowLayer[]): Shadow;
+/**
+ * Append a layer to a shadow.
+ */
+declare function addLayer(shadow: Shadow, layer: ShadowLayer): Shadow;
+/**
+ * Remove a layer by index.
+ */
+declare function removeLayer(shadow: Shadow, index: number): Shadow;
+/**
+ * Merge multiple shadows by concatenating all their layers.
+ *
+ * @example
+ * mergeShadows(cardShadow, hoverShadow)
+ */
+declare function mergeShadows(...shadows: Shadow[]): Shadow;
+/**
+ * Scale all layers' geometry uniformly.
+ *
+ * @example
+ * scaleShadow(shadow, 1.5)  // 50% larger offsets/blur/spread
+ */
+declare function scaleShadow(shadow: Shadow, factor: number): Shadow;
+/**
+ * Recolor all layers of a shadow.
+ *
+ * Preserves each layer's original alpha by default. Pass `preserveAlpha: false`
+ * to use the new color's alpha for all layers.
+ */
+declare function colorShadow(shadow: Shadow, color: OklchColor, preserveAlpha?: boolean): Shadow;
+/**
+ * Multiply all layer alphas by a factor.
+ *
+ * Useful for dark-mode adjustments (e.g. `multiplyAlpha(shadow, 1.5)`).
+ */
+declare function multiplyAlpha(shadow: Shadow, factor: number): Shadow;
+
+/**
+ * Pre-defined elevation presets matching the token shadow geometry
+ * with concrete black shadow colors (light-mode alphas).
+ */
+declare const ELEVATION_PRESETS: Record<ElevationLevel, Shadow>;
+/**
+ * Create a custom elevation scale with a different base color
+ * and/or alpha multiplier.
+ *
+ * @example
+ * // Dark mode: 1.5× stronger shadows
+ * createElevationScale({ alphaMultiplier: 1.5 })
+ *
+ * // Branded shadows
+ * createElevationScale({ color: { l: 0.541, c: 0.247, h: 293, alpha: 1 } })
+ */
+declare function createElevationScale(config?: ElevationConfig): Record<ElevationLevel, Shadow>;
+/**
+ * Interpolate between two shadows by index-matching layers.
+ *
+ * Only the minimum number of layers (from either shadow) is interpolated.
+ * Extra layers are dropped.
+ *
+ * Interpolates: offsets, blur, spread (px values) and color alpha.
+ * Color L/C/H are interpolated linearly.
+ *
+ * @param from - Starting shadow
+ * @param to   - Ending shadow
+ * @param t    - Interpolation factor, 0 = `from`, 1 = `to`
+ */
+declare function interpolateElevation(from: Shadow, to: Shadow, t: number): Shadow;
+/**
+ * Step up or down one elevation level.
+ *
+ * @example
+ * stepElevation("sm", "up")   // → "md"
+ * stepElevation("xs", "down") // → "none"
+ * stepElevation("3xl", "up")  // → "3xl" (clamped)
+ */
+declare function stepElevation(current: ElevationLevel, direction: "up" | "down"): ElevationLevel;
+/**
+ * Get the ordered list of elevation levels.
+ */
+declare function getElevationLevels(): readonly ElevationLevel[];
+
+/**
+ * Create a focus ring as a `Shadow` object.
+ *
+ * Produces a double box-shadow:
+ * 1. Inner gap ring (bgColor) at `ringOffset` spread
+ * 2. Outer colored ring at `ringOffset + ringWidth` spread
+ *
+ * Both use zero offset/blur (pure spread shadows) to create crisp rings.
+ *
+ * @example
+ * createFocusRing()
+ * createFocusRing({ ringColor: { l: 0.541, c: 0.247, h: 293, alpha: 1 } })
+ */
+declare function createFocusRing(config?: Partial<FocusRing>): Shadow;
+/**
+ * Create an error-variant focus ring as a `Shadow` object.
+ */
+declare function createErrorRing(config?: Partial<FocusRing>): Shadow;
+/**
+ * Build a focus ring `Shadow` from a complete `FocusRing` configuration.
+ *
+ * Returns a two-layer shadow:
+ * - Layer 0: background gap ring
+ * - Layer 1: colored outer ring
+ */
+declare function buildRing(config: FocusRing): Shadow;
+/**
+ * Combine a shadow with a focus ring.
+ *
+ * The ring layers are prepended so they render below the shadow layers
+ * in the box-shadow stacking order.
+ *
+ * @example
+ * withFocusRing(cardShadow, createFocusRing())
+ */
+declare function withFocusRing(shadow: Shadow, ring: Shadow): Shadow;
+/**
+ * Create a custom ring with arbitrary color.
+ *
+ * Shorthand for `createFocusRing({ ringColor })`.
+ */
+declare function colorRing(ringColor: OklchColor): Shadow;
+
+/**
+ * Format a single `ShadowLayer` as a CSS box-shadow layer string.
+ *
+ * @example
+ * layerToString(layer) // → "0px 4px 6px -1px oklch(0% 0 0 / 0.102)"
+ */
+declare function layerToString(layer: ShadowLayer): string;
+/**
+ * Format a `Shadow` as a CSS `box-shadow` value.
+ *
+ * @example
+ * toBoxShadow(shadow) // → "0px 1px 3px 0px oklch(...), 0px 1px 2px -1px oklch(...)"
+ */
+declare function toBoxShadow(shadow: Shadow): string;
+/**
+ * Format a `Shadow` as a React `CSSProperties`-compatible object.
+ *
+ * @example
+ * toCSSProperties(shadow) // → { boxShadow: "0px 4px 6px -1px oklch(...)" }
+ */
+declare function toCSSProperties(shadow: Shadow): {
+    boxShadow: string;
+};
+/**
+ * Format a `Shadow` as a Tailwind CSS arbitrary shadow class.
+ *
+ * @example
+ * toTailwindClass(shadow) // → "shadow-[0px_4px_6px_-1px_oklch(0%_0_0/0.1)]"
+ */
+declare function toTailwindClass(shadow: Shadow): string;
+/**
+ * Format a `Shadow` as a CSS declaration block.
+ *
+ * @example
+ * toCSSDeclaration(shadow) // → "box-shadow: 0px 4px 6px -1px oklch(...);"
+ */
+declare function toCSSDeclaration(shadow: Shadow): string;
+
+export { ELEVATION_PRESETS, type ElevationConfig, type ElevationLevel, type FocusRing, type Shadow, type ShadowLayer, addLayer, buildRing, colorRing, colorShadow, createElevationScale, createErrorRing, createFocusRing, createLayer, createShadow, getElevationLevels, insetLayer, interpolateElevation, layerToString, mergeShadows, multiplyAlpha, offsetLayer, parseLayer, parseShadow, removeLayer, scaleLayer, scaleShadow, setLayerColor, setLayerOpacity, stepElevation, toBoxShadow, toCSSDeclaration, toCSSProperties, toTailwindClass, withFocusRing };

package/dist/index.d.ts

@@ -0,0 +1,287 @@
+import { OklchColor } from '@ariaui/color';
+
+/**
+ * A single layer of a box-shadow.
+ *
+ * Color is stored as a structured `OklchColor` from `@ariaui/color`,
+ * enabling programmatic manipulation (opacity, hue, lightness).
+ */
+interface ShadowLayer {
+    /** Horizontal offset, e.g. `"0px"` */
+    readonly offsetX: string;
+    /** Vertical offset, e.g. `"4px"` */
+    readonly offsetY: string;
+    /** Blur radius, e.g. `"6px"` */
+    readonly blur: string;
+    /** Spread radius, e.g. `"-1px"` */
+    readonly spread: string;
+    /** Layer color as an OKLCH color object */
+    readonly color: OklchColor;
+    /** Whether this is an inset shadow */
+    readonly inset: boolean;
+}
+/**
+ * A composite shadow made of one or more layers.
+ */
+interface Shadow {
+    readonly layers: readonly ShadowLayer[];
+}
+/**
+ * Focus ring configuration.
+ *
+ * Produces a double box-shadow: inner gap ring (`bgColor`) +
+ * outer colored ring (`ringColor`).
+ */
+interface FocusRing {
+    /** Ring stroke width, e.g. `"2px"` */
+    readonly ringWidth: string;
+    /** Gap between element edge and ring, e.g. `"2px"` */
+    readonly ringOffset: string;
+    /** Ring color */
+    readonly ringColor: OklchColor;
+    /** Gap color (usually the page background) */
+    readonly bgColor: OklchColor;
+}
+/** Named elevation levels matching the token shadow sizes. */
+type ElevationLevel = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+/**
+ * Configuration for creating a custom elevation scale.
+ */
+interface ElevationConfig {
+    /** Shadow base color (default: black `{ l: 0, c: 0, h: 0, alpha: 1 }`) */
+    readonly color?: OklchColor;
+    /** Multiply all layer alphas (e.g. 1.5 for dark mode) */
+    readonly alphaMultiplier?: number;
+}
+
+/**
+ * Parse a CSS `box-shadow` value into a `Shadow` object.
+ *
+ * Supports multiple comma-separated layers, `inset` keyword,
+ * and common color formats: `rgba()`, `oklch()`, hex, and named colors.
+ *
+ * @example
+ * parseShadow("0px 1px 2px 0px rgba(0,0,0,0.05)")
+ * parseShadow("inset 0 2px 4px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06)")
+ */
+declare function parseShadow(css: string): Shadow;
+/**
+ * Parse a single box-shadow layer string into a `ShadowLayer`.
+ *
+ * @example
+ * parseLayer("0px 4px 6px -1px rgba(0,0,0,0.1)")
+ * parseLayer("inset 0 2px 4px 0px oklch(0% 0 0 / 0.08)")
+ */
+declare function parseLayer(css: string): ShadowLayer;
+
+/**
+ * Create a shadow layer with sensible defaults.
+ *
+ * @example
+ * createLayer({ offsetY: "4px", blur: "6px", color: { l: 0, c: 0, h: 0, alpha: 0.1 } })
+ */
+declare function createLayer(config?: Partial<ShadowLayer>): ShadowLayer;
+/**
+ * Scale a layer's geometry (offsets, blur, spread) by a factor.
+ * Color and inset are preserved.
+ *
+ * @example
+ * scaleLayer(layer, 2)  // doubles all offsets, blur, and spread
+ */
+declare function scaleLayer(layer: ShadowLayer, factor: number): ShadowLayer;
+/**
+ * Replace the color of a layer.
+ */
+declare function setLayerColor(layer: ShadowLayer, color: OklchColor): ShadowLayer;
+/**
+ * Set the alpha (opacity) of a layer's color.
+ */
+declare function setLayerOpacity(layer: ShadowLayer, alpha: number): ShadowLayer;
+/**
+ * Shift a layer's offset.
+ *
+ * @example
+ * offsetLayer(layer, { x: "2px", y: "4px" })
+ */
+declare function offsetLayer(layer: ShadowLayer, offset: {
+    x?: string;
+    y?: string;
+}): ShadowLayer;
+/**
+ * Toggle or set the inset flag.
+ */
+declare function insetLayer(layer: ShadowLayer, inset?: boolean): ShadowLayer;
+
+/**
+ * Create a `Shadow` from one or more layers.
+ *
+ * @example
+ * createShadow(
+ *   createLayer({ offsetY: "1px", blur: "2px" }),
+ *   createLayer({ offsetY: "4px", blur: "6px", spread: "-1px" }),
+ * )
+ */
+declare function createShadow(...layers: ShadowLayer[]): Shadow;
+/**
+ * Append a layer to a shadow.
+ */
+declare function addLayer(shadow: Shadow, layer: ShadowLayer): Shadow;
+/**
+ * Remove a layer by index.
+ */
+declare function removeLayer(shadow: Shadow, index: number): Shadow;
+/**
+ * Merge multiple shadows by concatenating all their layers.
+ *
+ * @example
+ * mergeShadows(cardShadow, hoverShadow)
+ */
+declare function mergeShadows(...shadows: Shadow[]): Shadow;
+/**
+ * Scale all layers' geometry uniformly.
+ *
+ * @example
+ * scaleShadow(shadow, 1.5)  // 50% larger offsets/blur/spread
+ */
+declare function scaleShadow(shadow: Shadow, factor: number): Shadow;
+/**
+ * Recolor all layers of a shadow.
+ *
+ * Preserves each layer's original alpha by default. Pass `preserveAlpha: false`
+ * to use the new color's alpha for all layers.
+ */
+declare function colorShadow(shadow: Shadow, color: OklchColor, preserveAlpha?: boolean): Shadow;
+/**
+ * Multiply all layer alphas by a factor.
+ *
+ * Useful for dark-mode adjustments (e.g. `multiplyAlpha(shadow, 1.5)`).
+ */
+declare function multiplyAlpha(shadow: Shadow, factor: number): Shadow;
+
+/**
+ * Pre-defined elevation presets matching the token shadow geometry
+ * with concrete black shadow colors (light-mode alphas).
+ */
+declare const ELEVATION_PRESETS: Record<ElevationLevel, Shadow>;
+/**
+ * Create a custom elevation scale with a different base color
+ * and/or alpha multiplier.
+ *
+ * @example
+ * // Dark mode: 1.5× stronger shadows
+ * createElevationScale({ alphaMultiplier: 1.5 })
+ *
+ * // Branded shadows
+ * createElevationScale({ color: { l: 0.541, c: 0.247, h: 293, alpha: 1 } })
+ */
+declare function createElevationScale(config?: ElevationConfig): Record<ElevationLevel, Shadow>;
+/**
+ * Interpolate between two shadows by index-matching layers.
+ *
+ * Only the minimum number of layers (from either shadow) is interpolated.
+ * Extra layers are dropped.
+ *
+ * Interpolates: offsets, blur, spread (px values) and color alpha.
+ * Color L/C/H are interpolated linearly.
+ *
+ * @param from - Starting shadow
+ * @param to   - Ending shadow
+ * @param t    - Interpolation factor, 0 = `from`, 1 = `to`
+ */
+declare function interpolateElevation(from: Shadow, to: Shadow, t: number): Shadow;
+/**
+ * Step up or down one elevation level.
+ *
+ * @example
+ * stepElevation("sm", "up")   // → "md"
+ * stepElevation("xs", "down") // → "none"
+ * stepElevation("3xl", "up")  // → "3xl" (clamped)
+ */
+declare function stepElevation(current: ElevationLevel, direction: "up" | "down"): ElevationLevel;
+/**
+ * Get the ordered list of elevation levels.
+ */
+declare function getElevationLevels(): readonly ElevationLevel[];
+
+/**
+ * Create a focus ring as a `Shadow` object.
+ *
+ * Produces a double box-shadow:
+ * 1. Inner gap ring (bgColor) at `ringOffset` spread
+ * 2. Outer colored ring at `ringOffset + ringWidth` spread
+ *
+ * Both use zero offset/blur (pure spread shadows) to create crisp rings.
+ *
+ * @example
+ * createFocusRing()
+ * createFocusRing({ ringColor: { l: 0.541, c: 0.247, h: 293, alpha: 1 } })
+ */
+declare function createFocusRing(config?: Partial<FocusRing>): Shadow;
+/**
+ * Create an error-variant focus ring as a `Shadow` object.
+ */
+declare function createErrorRing(config?: Partial<FocusRing>): Shadow;
+/**
+ * Build a focus ring `Shadow` from a complete `FocusRing` configuration.
+ *
+ * Returns a two-layer shadow:
+ * - Layer 0: background gap ring
+ * - Layer 1: colored outer ring
+ */
+declare function buildRing(config: FocusRing): Shadow;
+/**
+ * Combine a shadow with a focus ring.
+ *
+ * The ring layers are prepended so they render below the shadow layers
+ * in the box-shadow stacking order.
+ *
+ * @example
+ * withFocusRing(cardShadow, createFocusRing())
+ */
+declare function withFocusRing(shadow: Shadow, ring: Shadow): Shadow;
+/**
+ * Create a custom ring with arbitrary color.
+ *
+ * Shorthand for `createFocusRing({ ringColor })`.
+ */
+declare function colorRing(ringColor: OklchColor): Shadow;
+
+/**
+ * Format a single `ShadowLayer` as a CSS box-shadow layer string.
+ *
+ * @example
+ * layerToString(layer) // → "0px 4px 6px -1px oklch(0% 0 0 / 0.102)"
+ */
+declare function layerToString(layer: ShadowLayer): string;
+/**
+ * Format a `Shadow` as a CSS `box-shadow` value.
+ *
+ * @example
+ * toBoxShadow(shadow) // → "0px 1px 3px 0px oklch(...), 0px 1px 2px -1px oklch(...)"
+ */
+declare function toBoxShadow(shadow: Shadow): string;
+/**
+ * Format a `Shadow` as a React `CSSProperties`-compatible object.
+ *
+ * @example
+ * toCSSProperties(shadow) // → { boxShadow: "0px 4px 6px -1px oklch(...)" }
+ */
+declare function toCSSProperties(shadow: Shadow): {
+    boxShadow: string;
+};
+/**
+ * Format a `Shadow` as a Tailwind CSS arbitrary shadow class.
+ *
+ * @example
+ * toTailwindClass(shadow) // → "shadow-[0px_4px_6px_-1px_oklch(0%_0_0/0.1)]"
+ */
+declare function toTailwindClass(shadow: Shadow): string;
+/**
+ * Format a `Shadow` as a CSS declaration block.
+ *
+ * @example
+ * toCSSDeclaration(shadow) // → "box-shadow: 0px 4px 6px -1px oklch(...);"
+ */
+declare function toCSSDeclaration(shadow: Shadow): string;
+
+export { ELEVATION_PRESETS, type ElevationConfig, type ElevationLevel, type FocusRing, type Shadow, type ShadowLayer, addLayer, buildRing, colorRing, colorShadow, createElevationScale, createErrorRing, createFocusRing, createLayer, createShadow, getElevationLevels, insetLayer, interpolateElevation, layerToString, mergeShadows, multiplyAlpha, offsetLayer, parseLayer, parseShadow, removeLayer, scaleLayer, scaleShadow, setLayerColor, setLayerOpacity, stepElevation, toBoxShadow, toCSSDeclaration, toCSSProperties, toTailwindClass, withFocusRing };

package/dist/index.js

@@ -0,0 +1,64 @@
+import {
+  ELEVATION_PRESETS,
+  addLayer,
+  buildRing,
+  colorRing,
+  colorShadow,
+  createElevationScale,
+  createErrorRing,
+  createFocusRing,
+  createLayer,
+  createShadow,
+  getElevationLevels,
+  insetLayer,
+  interpolateElevation,
+  layerToString,
+  mergeShadows,
+  multiplyAlpha,
+  offsetLayer,
+  parseLayer,
+  parseShadow,
+  removeLayer,
+  scaleLayer,
+  scaleShadow,
+  setLayerColor,
+  setLayerOpacity,
+  stepElevation,
+  toBoxShadow,
+  toCSSDeclaration,
+  toCSSProperties,
+  toTailwindClass,
+  withFocusRing
+} from "./chunk-TCSURVQN.js";
+export {
+  ELEVATION_PRESETS,
+  addLayer,
+  buildRing,
+  colorRing,
+  colorShadow,
+  createElevationScale,
+  createErrorRing,
+  createFocusRing,
+  createLayer,
+  createShadow,
+  getElevationLevels,
+  insetLayer,
+  interpolateElevation,
+  layerToString,
+  mergeShadows,
+  multiplyAlpha,
+  offsetLayer,
+  parseLayer,
+  parseShadow,
+  removeLayer,
+  scaleLayer,
+  scaleShadow,
+  setLayerColor,
+  setLayerOpacity,
+  stepElevation,
+  toBoxShadow,
+  toCSSDeclaration,
+  toCSSProperties,
+  toTailwindClass,
+  withFocusRing
+};