@pixerate/editor 0.146.0 → 0.147.0

package/dist/gradient/model.d.cts

@@ -0,0 +1,94 @@
+import { type ColorScheme, type ColorValue } from '../color/index.cjs';
+import type { Gradient, GradientStop } from './types.cjs';
+/** Formula matching gradientMidpointRemap from vector/gradient.ts */
+export declare function gradientMidpointRemap(u: number, m: number): number;
+/**
+ * Normalises an arbitrary gradient input into a validated Gradient object.
+ * Returns `{ gradient: Gradient }` or `{ error: string }`.
+ */
+export declare function normalizeGradient(input: unknown): {
+    gradient: Gradient;
+} | {
+    error: string;
+};
+/**
+ * Creates a Gradient with evenly spaced stops from an array of colors or options.
+ */
+export declare function createGradient(colorsOrOptions?: readonly string[] | (Partial<Gradient> & {
+    stops?: readonly GradientStop[] | readonly string[];
+}), options?: Partial<Omit<Gradient, 'stops'>>): Gradient;
+/**
+ * Helper to check if a colour value represents a dual colour (light-dark string or DualColor object).
+ */
+export declare function isDualColorValue(val: unknown): boolean;
+/**
+ * Checks whether any stop in the gradient has a dual colour (`light-dark()`).
+ */
+export declare function isDualGradient(g: Gradient): boolean;
+/**
+ * Resolves a gradient for a specific ColorScheme ('light' or 'dark').
+ */
+export declare function resolveGradient(g: Gradient, scheme: ColorScheme): Gradient;
+/**
+ * Samples a gradient at t (0–1), returning a hex colour string.
+ */
+export declare function sampleGradient(g: Gradient, t: number, scheme?: ColorScheme): string;
+/**
+ * Inserts a new stop at the given offset.
+ * When colour is omitted, samples the gradient at that offset.
+ */
+export declare function insertGradientStop(g: Gradient, offset: number, color?: string): {
+    gradient: Gradient;
+    stop: GradientStop;
+};
+/**
+ * Updates a gradient stop by id. Throws sentence error if id not found.
+ */
+export declare function updateGradientStop(g: Gradient, id: string, patch: {
+    offset?: number;
+    color?: string;
+    midpoint?: number;
+}): Gradient;
+/**
+ * Removes a gradient stop by id. Refuses to go below 2 stops.
+ */
+export declare function removeGradientStop(g: Gradient, id: string): Gradient;
+/**
+ * Reverses gradient stops (offsets become 1 - offset, midpoints become 1 - midpoint).
+ */
+export declare function reverseGradient(g: Gradient): Gradient;
+/**
+ * Distributes stops evenly between 0 and 1 while preserving order.
+ */
+export declare function distributeGradientStops(g: Gradient): Gradient;
+/**
+ * Formats a Gradient into standard CSS.
+ */
+export declare function gradientToCss(g: Gradient): string;
+/**
+ * Fallback CSS gradient for legacy engines: expanded sRGB stops with no hints and no light-dark.
+ */
+export declare function gradientToCssFallback(g: Gradient, steps?: number, scheme?: ColorScheme): string;
+/**
+ * Parses CSS linear-gradient, radial-gradient, conic-gradient strings.
+ * Returns null if invalid or unsupported.
+ */
+export declare function parseCssGradient(css: string): Gradient | null;
+/**
+ * Generates an SVG `<linearGradient>` or `<radialGradient>` element string with sampled stops.
+ */
+export declare function gradientToSvgDef(g: Gradient, id: string, scheme?: ColorScheme): string;
+/**
+ * Checks a gradient for issues (too close, out of sRGB, banding) and lowest text contrast.
+ */
+export declare function checkGradient(g: Gradient, options?: {
+    surface?: ColorValue;
+    text?: ColorValue;
+}): {
+    issues: string[];
+    lowestTextContrast?: number | {
+        light: number;
+        dark: number;
+    };
+};
+export declare const GRADIENT_PRESETS: Readonly<Record<string, Gradient>>;

package/dist/gradient/model.d.ts

@@ -0,0 +1,94 @@
+import { type ColorScheme, type ColorValue } from '../color/index.js';
+import type { Gradient, GradientStop } from './types.js';
+/** Formula matching gradientMidpointRemap from vector/gradient.ts */
+export declare function gradientMidpointRemap(u: number, m: number): number;
+/**
+ * Normalises an arbitrary gradient input into a validated Gradient object.
+ * Returns `{ gradient: Gradient }` or `{ error: string }`.
+ */
+export declare function normalizeGradient(input: unknown): {
+    gradient: Gradient;
+} | {
+    error: string;
+};
+/**
+ * Creates a Gradient with evenly spaced stops from an array of colors or options.
+ */
+export declare function createGradient(colorsOrOptions?: readonly string[] | (Partial<Gradient> & {
+    stops?: readonly GradientStop[] | readonly string[];
+}), options?: Partial<Omit<Gradient, 'stops'>>): Gradient;
+/**
+ * Helper to check if a colour value represents a dual colour (light-dark string or DualColor object).
+ */
+export declare function isDualColorValue(val: unknown): boolean;
+/**
+ * Checks whether any stop in the gradient has a dual colour (`light-dark()`).
+ */
+export declare function isDualGradient(g: Gradient): boolean;
+/**
+ * Resolves a gradient for a specific ColorScheme ('light' or 'dark').
+ */
+export declare function resolveGradient(g: Gradient, scheme: ColorScheme): Gradient;
+/**
+ * Samples a gradient at t (0–1), returning a hex colour string.
+ */
+export declare function sampleGradient(g: Gradient, t: number, scheme?: ColorScheme): string;
+/**
+ * Inserts a new stop at the given offset.
+ * When colour is omitted, samples the gradient at that offset.
+ */
+export declare function insertGradientStop(g: Gradient, offset: number, color?: string): {
+    gradient: Gradient;
+    stop: GradientStop;
+};
+/**
+ * Updates a gradient stop by id. Throws sentence error if id not found.
+ */
+export declare function updateGradientStop(g: Gradient, id: string, patch: {
+    offset?: number;
+    color?: string;
+    midpoint?: number;
+}): Gradient;
+/**
+ * Removes a gradient stop by id. Refuses to go below 2 stops.
+ */
+export declare function removeGradientStop(g: Gradient, id: string): Gradient;
+/**
+ * Reverses gradient stops (offsets become 1 - offset, midpoints become 1 - midpoint).
+ */
+export declare function reverseGradient(g: Gradient): Gradient;
+/**
+ * Distributes stops evenly between 0 and 1 while preserving order.
+ */
+export declare function distributeGradientStops(g: Gradient): Gradient;
+/**
+ * Formats a Gradient into standard CSS.
+ */
+export declare function gradientToCss(g: Gradient): string;
+/**
+ * Fallback CSS gradient for legacy engines: expanded sRGB stops with no hints and no light-dark.
+ */
+export declare function gradientToCssFallback(g: Gradient, steps?: number, scheme?: ColorScheme): string;
+/**
+ * Parses CSS linear-gradient, radial-gradient, conic-gradient strings.
+ * Returns null if invalid or unsupported.
+ */
+export declare function parseCssGradient(css: string): Gradient | null;
+/**
+ * Generates an SVG `<linearGradient>` or `<radialGradient>` element string with sampled stops.
+ */
+export declare function gradientToSvgDef(g: Gradient, id: string, scheme?: ColorScheme): string;
+/**
+ * Checks a gradient for issues (too close, out of sRGB, banding) and lowest text contrast.
+ */
+export declare function checkGradient(g: Gradient, options?: {
+    surface?: ColorValue;
+    text?: ColorValue;
+}): {
+    issues: string[];
+    lowestTextContrast?: number | {
+        light: number;
+        dark: number;
+    };
+};
+export declare const GRADIENT_PRESETS: Readonly<Record<string, Gradient>>;

package/dist/gradient/tools.d.cts

@@ -0,0 +1,11 @@
+import type { AgentToolProvider } from '../tools/registry.cjs';
+import { type GradientController } from './controller.cjs';
+export interface GradientToolProviderOptions {
+    /** Provider id (unique per registry). Default `gradient`. */
+    id?: string;
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
+    namespace?: string;
+    /** Read-only reason string or boolean, or getter. Write tools are suppressed if read-only. */
+    readOnly?: boolean | string | (() => boolean | string);
+}
+export declare function createGradientToolProvider(controller: GradientController, options?: GradientToolProviderOptions): AgentToolProvider;

package/dist/gradient/tools.d.ts

@@ -0,0 +1,11 @@
+import type { AgentToolProvider } from '../tools/registry.js';
+import { type GradientController } from './controller.js';
+export interface GradientToolProviderOptions {
+    /** Provider id (unique per registry). Default `gradient`. */
+    id?: string;
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
+    namespace?: string;
+    /** Read-only reason string or boolean, or getter. Write tools are suppressed if read-only. */
+    readOnly?: boolean | string | (() => boolean | string);
+}
+export declare function createGradientToolProvider(controller: GradientController, options?: GradientToolProviderOptions): AgentToolProvider;

package/dist/gradient/types.d.cts

@@ -0,0 +1,44 @@
+/**
+ * CSS-shaped gradient model types.
+ *
+ * Gradients are opt-in: `@pixerate/editor/color` never imports gradient code.
+ */
+export type GradientType = 'linear' | 'radial' | 'conic';
+export type GradientInterpolation = 'srgb' | 'srgb-linear' | 'oklab' | 'oklch';
+export interface GradientStop {
+    /** Stable id, unique within the gradient (e.g. "s1"). Assigned by the model when missing. */
+    id: string;
+    /** 0–1 along the gradient. */
+    offset: number;
+    /**
+     * Any CSS colour, or a dual colour as `light-dark(a, b)` (Phase 5). Stored normalised by
+     * `normalizeGradient`: hex, or `light-dark(#a, #b)` when the halves differ.
+     */
+    color: string;
+    /** 0.05–0.95: where between this stop and the next the colours are half mixed (default 0.5, CSS colour hint). */
+    midpoint?: number;
+}
+export interface Gradient {
+    type: GradientType;
+    stops: GradientStop[];
+    /** Linear and conic: degrees, CSS convention (0 = to top, 90 = to right, default 180 = to bottom). */
+    angle?: number;
+    /** Radial and conic: centre, 0–1 of the box (default 0.5, 0.5). */
+    center?: {
+        x: number;
+        y: number;
+    };
+    /** Radial: 'circle' or 'ellipse' (default 'ellipse', CSS farthest-corner). */
+    shape?: 'circle' | 'ellipse';
+    /** Default 'oklab'. */
+    interpolation?: GradientInterpolation;
+    /** Repeat the stop pattern (CSS repeating-*-gradient). Default false. */
+    repeating?: boolean;
+}
+export type GradientShape = 'circle' | 'ellipse';
+export interface GradientCheckOptions {
+    surface?: string;
+    text?: string;
+    fontSize?: number;
+    bold?: boolean;
+}

package/dist/gradient/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * CSS-shaped gradient model types.
+ *
+ * Gradients are opt-in: `@pixerate/editor/color` never imports gradient code.
+ */
+export type GradientType = 'linear' | 'radial' | 'conic';
+export type GradientInterpolation = 'srgb' | 'srgb-linear' | 'oklab' | 'oklch';
+export interface GradientStop {
+    /** Stable id, unique within the gradient (e.g. "s1"). Assigned by the model when missing. */
+    id: string;
+    /** 0–1 along the gradient. */
+    offset: number;
+    /**
+     * Any CSS colour, or a dual colour as `light-dark(a, b)` (Phase 5). Stored normalised by
+     * `normalizeGradient`: hex, or `light-dark(#a, #b)` when the halves differ.
+     */
+    color: string;
+    /** 0.05–0.95: where between this stop and the next the colours are half mixed (default 0.5, CSS colour hint). */
+    midpoint?: number;
+}
+export interface Gradient {
+    type: GradientType;
+    stops: GradientStop[];
+    /** Linear and conic: degrees, CSS convention (0 = to top, 90 = to right, default 180 = to bottom). */
+    angle?: number;
+    /** Radial and conic: centre, 0–1 of the box (default 0.5, 0.5). */
+    center?: {
+        x: number;
+        y: number;
+    };
+    /** Radial: 'circle' or 'ellipse' (default 'ellipse', CSS farthest-corner). */
+    shape?: 'circle' | 'ellipse';
+    /** Default 'oklab'. */
+    interpolation?: GradientInterpolation;
+    /** Repeat the stop pattern (CSS repeating-*-gradient). Default false. */
+    repeating?: boolean;
+}
+export type GradientShape = 'circle' | 'ellipse';
+export interface GradientCheckOptions {
+    surface?: string;
+    text?: string;
+    fontSize?: number;
+    bold?: boolean;
+}