@snowcone-app/canvas 0.30.0 → 0.32.0

package/dist/types/index.d.ts

@@ -63,6 +63,25 @@ export interface FlagTransformData {
     /** Container width for text layout */
     width: number;
 }
+/**
+ * Color adjustments for image elements. Each channel is a multiplier where
+ * `1` is neutral (no change); the canonical neutral state is the ABSENCE of
+ * the `adjustments` object (omit = neutral, never `{1, 1, 1}`).
+ *
+ * Semantics match the CSS Filter Effects spec functions `brightness()`,
+ * `contrast()` and `saturate()`, applied in that order to the SOURCE bitmap
+ * before crop / flip / border-radius compositing. The math lives in
+ * `rendering/image-adjustments.ts` and is shared verbatim by the live
+ * renderer and the export worker, so live and exported pixels always match.
+ */
+export interface ImageAdjustments {
+    /** Brightness multiplier — 1 neutral, 0 black, > 1 brighter. */
+    brightness: number;
+    /** Contrast multiplier — 1 neutral, 0 solid grey, > 1 punchier. */
+    contrast: number;
+    /** Saturation multiplier — 1 neutral, 0 grayscale, > 1 more vivid. */
+    saturation: number;
+}
 export interface ImageTransformData {
     type: 'image';
     width: number;
@@ -74,6 +93,8 @@ export interface ImageTransformData {
     flipHorizontal: boolean;
     flipVertical: boolean;
     borderRadius: number;
+    /** Brightness/contrast/saturation — omitted when neutral. See {@link ImageAdjustments}. */
+    adjustments?: ImageAdjustments;
 }
 export interface GroupTransformData {
     type: 'group';
@@ -82,6 +103,43 @@ export interface ArtboardTransformData {
     type: 'artboard';
 }
 export type ShapeType = 'rectangle' | 'circle' | 'ellipse' | 'triangle' | 'polygon' | 'star' | 'line';
+/** One color stop on a gradient fill. `offset` is 0..1 along the gradient line. */
+export interface GradientStop {
+    offset: number;
+    color: string;
+}
+/**
+ * Shape fill — a discriminated union so an invalid mix (e.g. a "gradient
+ * enabled" flag with no stops) is unrepresentable.
+ *
+ * - `solid` — a single CSS color.
+ * - `linear` — CSS-like angle semantics: `0` = up (bottom → top),
+ *   `90` = right (left → right), increasing clockwise. The gradient line is
+ *   sized to the shape's local bounds exactly like CSS `linear-gradient`
+ *   (line length = |w·sin θ| + |h·cos θ|), so offset 0/1 land on the
+ *   shape's edges at every angle.
+ * - `radial` — centered on the shape, radius = farthest corner
+ *   (√(w² + h²) / 2), matching CSS `radial-gradient(circle farthest-corner)`.
+ *
+ * Gradients need ≥ 2 stops with offsets in 0..1 — violations throw
+ * `E_INVALID_FILL` at every write boundary (constructor, `updateElement`
+ * patch), dev AND prod.
+ *
+ * Back-compat: when `fill` is absent, the legacy `fillColor` string renders
+ * as a solid fill (it is the wire format of every saved design). When both
+ * are present, `fill` wins.
+ */
+export type ShapeFill = {
+    type: 'solid';
+    color: string;
+} | {
+    type: 'linear';
+    angle: number;
+    stops: GradientStop[];
+} | {
+    type: 'radial';
+    stops: GradientStop[];
+};
 export interface ShapeTransformData {
     type: 'shape';
     shapeType: ShapeType;
@@ -93,8 +151,17 @@ export interface ShapeTransformData {
     sides?: number;
     points?: number;
     innerRadius?: number;
+    /**
+     * Legacy solid fill color. Still the default write path for solid fills;
+     * ignored when `fill` is present.
+     */
     fillColor?: string;
     fillOpacity?: number;
+    /**
+     * Rich fill (solid or gradient). Wins over `fillColor` when present —
+     * see {@link ShapeFill} for angle/geometry semantics and validation.
+     */
+    fill?: ShapeFill;
 }
 /**
  * Path point types define how curve handles behave
@@ -154,7 +221,16 @@ export interface TransformStartData {
     childrenStartData?: TransformStartData[];
     [key: string]: unknown;
 }
-export type BlendMode = 'normal' | 'knockout' | 'clip';
+/**
+ * Standard blend modes — map 1:1 to canvas `globalCompositeOperation` values.
+ * The element composites AS A UNIT onto the layers below it (Photoshop layer
+ * semantics), handled by LayerEffectsRenderer in both the live renderer and
+ * the export worker.
+ */
+export type StandardBlendMode = 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten';
+/** All standard blend modes, in UI display order. */
+export declare const STANDARD_BLEND_MODES: readonly StandardBlendMode[];
+export type BlendMode = 'normal' | 'knockout' | 'clip' | StandardBlendMode;
 export type CompositingScope = 'group' | 'artboard';
 export type KnockoutScope = CompositingScope;
 export interface CompositingConfig {
@@ -174,6 +250,25 @@ export interface StrokeConfig {
     opacity?: number;
     feather?: number;
 }
+/**
+ * Drop shadow cast by an element's final silhouette (after masks, stroke,
+ * distress). All distances are WORLD-SPACE pixels — the shadow scales with
+ * canvas zoom and export resolution exactly like the element content does
+ * (it is artwork, not zoom-invariant chrome).
+ */
+export interface ShadowConfig {
+    enabled: boolean;
+    /** Any CSS color (hex, rgb(a), named). Alpha multiplies with `opacity`. */
+    color: string;
+    /** Blur radius in world-space px (>= 0) */
+    blur: number;
+    /** Horizontal offset in world-space px (positive = right) */
+    offsetX: number;
+    /** Vertical offset in world-space px (positive = down) */
+    offsetY: number;
+    /** Shadow strength 0-1 (default 1), multiplies the color's own alpha */
+    opacity?: number;
+}
 /**
  * Rendering context metadata passed to renderers
  * Used to customize rendering behavior for specific contexts (e.g., knockout, export, preview)
@@ -439,6 +534,7 @@ export interface BaseElementConfig {
     stroke?: StrokeConfig;
     masks?: MaskDefinition[];
     distressEffect?: DistressEffect;
+    shadow?: ShadowConfig;
     name?: string;
     visible?: boolean;
     locked?: boolean;
@@ -767,6 +863,14 @@ export declare function isPathTransform(data: AnyTransformData): data is PathTra
 export declare function hasStroke(config: AnyElementConfig): boolean;
 export declare function hasMasks(config: AnyElementConfig): boolean;
 export declare function isKnockout(config: AnyElementConfig): boolean;
+/**
+ * Standard blend mode type guard. Narrows a BlendMode (or raw string from
+ * serialized JSON) to the modes that map 1:1 onto globalCompositeOperation.
+ * 'normal', 'knockout', 'clip' and undefined are all NOT standard blend modes
+ * — knockout/clip keep their special compositing path untouched.
+ */
+export declare function isStandardBlendMode(mode: BlendMode | string | undefined | null): mode is StandardBlendMode;
+export declare function hasShadow(config: AnyElementConfig): boolean;
 export declare function hasDistressEffect(config: AnyElementConfig): boolean;
 /**
  * Categories of errors that can occur within the canvas.

package/dist/types/public.d.ts

@@ -16,7 +16,8 @@ export type { TransformType, AnyTransformData, CustomTransformData, DistortTrans
 export type { AnyElementConfig, BaseElementConfig, BaseTextElementConfig, TextOnlyElementConfig, CustomElementConfig, DistortElementConfig, CircleElementConfig, LeanElementConfig, ArchElementConfig, AscendElementConfig, WaveElementConfig, FlagElementConfig, ImageElementConfig, GroupElementConfig, ShapeElementConfig, PathElementConfig, } from './index.js';
 export type { ArtboardConfig as ArtboardElementConfig, ArtboardBackgroundType, ClipShape, } from './index.js';
 export type { BoundingBox, Point, ResizeAnchor, } from './index.js';
-export type { BlendMode, KnockoutScope, KnockoutConfig, StrokeConfig, MaskType, MaskDefinition, DistressStyle, DistressEffect, } from './index.js';
+export type { BlendMode, StandardBlendMode, KnockoutScope, KnockoutConfig, StrokeConfig, ShadowConfig, MaskType, MaskDefinition, DistressStyle, DistressEffect, } from './index.js';
+export { STANDARD_BLEND_MODES } from './index.js';
 export type { TextAlign, CharacterStyle, TextSpan, GlyphOverride, GlyphAlternate, OpenTypeFeatures, } from './index.js';
 export { RichText } from './index.js';
 export type { ShapeType, } from './index.js';
@@ -27,5 +28,5 @@ export type { CanvasError, CanvasErrorCategory, } from './index.js';
 export type { Theme } from '../contexts/ThemeContext.js';
 export { isTextElementConfig, isImageElementConfig, isCustomElementConfig, isCircleElementConfig, isLeanElementConfig, isArchElementConfig, isAscendElementConfig, isWaveElementConfig, isFlagElementConfig, isGroupElementConfig, isShapeElementConfig, isPathElementConfig, } from './index.js';
 export { isCustomTransform, isDistortTransform, isCircleTransform, isLeanTransform, isArchTransform, isAscendTransform, isWaveTransform, isFlagTransform, isImageTransform, isGroupTransform, isArtboardTransform, isShapeTransform, isPathTransform, } from './index.js';
-export { hasStroke, hasMasks, isKnockout, hasDistressEffect, } from './index.js';
+export { hasStroke, hasMasks, isKnockout, hasDistressEffect, hasShadow, isStandardBlendMode, } from './index.js';
 export { isTextElement, isImageElement, isGroupElement, isShapeElement, isPathElement, } from './guards.js';