@canvas-commons/2d 0.2.0

package/src/lib/partials/Filter.ts

@@ -0,0 +1,185 @@
+import {
+  createSignal,
+  map,
+  SignalValue,
+  SimpleSignal,
+  transformScalar,
+} from '@canvas-commons/core';
+
+/**
+ * All possible CSS filter names.
+ *
+ * @internal
+ */
+export type FilterName =
+  | 'invert'
+  | 'sepia'
+  | 'grayscale'
+  | 'brightness'
+  | 'contrast'
+  | 'saturate'
+  | 'hue'
+  | 'blur';
+
+/**
+ * Definitions of all possible CSS filters.
+ *
+ * @internal
+ */
+export const FILTERS: Record<string, Partial<FilterProps>> = {
+  invert: {
+    name: 'invert',
+  },
+  sepia: {
+    name: 'sepia',
+  },
+  grayscale: {
+    name: 'grayscale',
+  },
+  brightness: {
+    name: 'brightness',
+    default: 1,
+  },
+  contrast: {
+    name: 'contrast',
+    default: 1,
+  },
+  saturate: {
+    name: 'saturate',
+    default: 1,
+  },
+  hue: {
+    name: 'hue-rotate',
+    unit: 'deg',
+    scale: 1,
+  },
+  blur: {
+    name: 'blur',
+    transform: true,
+    unit: 'px',
+    scale: 1,
+  },
+};
+
+/**
+ * A unified abstraction for all CSS filters.
+ */
+export interface FilterProps {
+  name: string;
+  value: SignalValue<number>;
+  unit: string;
+  scale: number;
+  transform: boolean;
+  default: number;
+}
+
+export class Filter {
+  public get name() {
+    return this.props.name;
+  }
+
+  public get default() {
+    return this.props.default;
+  }
+
+  public readonly value: SimpleSignal<number, Filter>;
+  private readonly props: FilterProps;
+
+  public constructor(props: Partial<FilterProps>) {
+    this.props = {
+      name: 'invert',
+      default: 0,
+      unit: '%',
+      scale: 100,
+      transform: false,
+      ...props,
+      value: props.value ?? props.default ?? 0,
+    };
+    this.value = createSignal(this.props.value, map, this);
+  }
+
+  public isActive() {
+    return this.value() !== this.props.default;
+  }
+
+  public serialize(matrix: DOMMatrix): string {
+    let value = this.value();
+    if (this.props.transform) {
+      value = transformScalar(value, matrix);
+    }
+
+    return `${this.props.name}(${value * this.props.scale}${this.props.unit})`;
+  }
+}
+
+/**
+ * Create an {@link https://developer.mozilla.org/en-US/docs/Web/CSS/filter-function/invert | invert} filter.
+ *
+ * @param value - The value of the filter.
+ */
+export function invert(value?: SignalValue<number>) {
+  return new Filter({...FILTERS.invert, value});
+}
+
+/**
+ * Create a {@link https://developer.mozilla.org/en-US/docs/Web/CSS/filter-function/sepia | sepia} filter.
+ *
+ * @param value - The value of the filter.
+ */
+export function sepia(value?: SignalValue<number>) {
+  return new Filter({...FILTERS.sepia, value});
+}
+
+/**
+ * Create a {@link https://developer.mozilla.org/en-US/docs/Web/CSS/filter-function/grayscale | grayscale} filter.
+ *
+ * @param value - The value of the filter.
+ */
+export function grayscale(value?: SignalValue<number>) {
+  return new Filter({...FILTERS.grayscale, value});
+}
+
+/**
+ * Create a {@link https://developer.mozilla.org/en-US/docs/Web/CSS/filter-function/brightness | brightness} filter.
+ *
+ * @param value - The value of the filter.
+ */
+export function brightness(value?: SignalValue<number>) {
+  return new Filter({...FILTERS.brightness, value});
+}
+
+/**
+ * Create a {@link https://developer.mozilla.org/en-US/docs/Web/CSS/filter-function/contrast | contrast} filter.
+ *
+ * @param value - The value of the filter.
+ */
+export function contrast(value?: SignalValue<number>) {
+  return new Filter({...FILTERS.contrast, value});
+}
+
+/**
+ * Create a {@link https://developer.mozilla.org/en-US/docs/Web/CSS/filter-function/saturate | saturate} filter.
+ *
+ * @param value - The value of the filter.
+ */
+export function saturate(value?: SignalValue<number>) {
+  return new Filter({...FILTERS.saturate, value});
+}
+
+/**
+ * Create a {@link https://developer.mozilla.org/en-US/docs/Web/CSS/filter-function/hue-rotate | hue} filter.
+ *
+ * @param value - The value of the filter in degrees.
+ */
+export function hue(value?: SignalValue<number>) {
+  return new Filter({...FILTERS.hue, value});
+}
+
+/**
+ * Create a {@link https://developer.mozilla.org/en-US/docs/Web/CSS/filter-function/blur | blur} filter.
+ *
+ * @param value - The value of the filter in pixels.
+ */
+export function blur(value?: SignalValue<number>) {
+  return new Filter({...FILTERS.blur, value});
+}

package/src/lib/partials/Gradient.ts

@@ -0,0 +1,103 @@
+import {
+  Color,
+  PossibleColor,
+  PossibleVector2,
+  SignalValue,
+  SimpleSignal,
+  Vector2Signal,
+  unwrap,
+} from '@canvas-commons/core';
+import {computed} from '../decorators/computed';
+import {initial, initializeSignals, signal} from '../decorators/signal';
+import {vector2Signal} from '../decorators/vector2Signal';
+
+export type GradientType = 'linear' | 'conic' | 'radial';
+
+export interface GradientStop {
+  offset: SignalValue<number>;
+  color: SignalValue<PossibleColor>;
+}
+
+export interface GradientProps {
+  type?: SignalValue<GradientType>;
+  fromX?: SignalValue<number>;
+  fromY?: SignalValue<number>;
+  from?: SignalValue<PossibleVector2>;
+  toX?: SignalValue<number>;
+  toY?: SignalValue<number>;
+  to?: SignalValue<PossibleVector2>;
+  angle?: SignalValue<number>;
+  fromRadius?: SignalValue<number>;
+  toRadius?: SignalValue<number>;
+  stops?: GradientStop[];
+}
+
+export class Gradient {
+  @initial('linear')
+  @signal()
+  declare public readonly type: SimpleSignal<GradientType, this>;
+
+  @vector2Signal('from')
+  declare public readonly from: Vector2Signal<this>;
+
+  @vector2Signal('to')
+  declare public readonly to: Vector2Signal<this>;
+
+  @initial(0)
+  @signal()
+  declare public readonly angle: SimpleSignal<number, this>;
+  @initial(0)
+  @signal()
+  declare public readonly fromRadius: SimpleSignal<number, this>;
+  @initial(0)
+  @signal()
+  declare public readonly toRadius: SimpleSignal<number, this>;
+  @initial([])
+  @signal()
+  declare public readonly stops: SimpleSignal<GradientStop[], this>;
+
+  public constructor(props: GradientProps) {
+    initializeSignals(this, props);
+  }
+
+  @computed()
+  public canvasGradient(context: CanvasRenderingContext2D): CanvasGradient {
+    let gradient: CanvasGradient;
+    switch (this.type()) {
+      case 'linear':
+        gradient = context.createLinearGradient(
+          this.from.x(),
+          this.from.y(),
+          this.to.x(),
+          this.to.y(),
+        );
+        break;
+      case 'conic':
+        gradient = context.createConicGradient(
+          this.angle(),
+          this.from.x(),
+          this.from.y(),
+        );
+        break;
+      case 'radial':
+        gradient = context.createRadialGradient(
+          this.from.x(),
+          this.from.y(),
+          this.fromRadius(),
+          this.to.x(),
+          this.to.y(),
+          this.toRadius(),
+        );
+        break;
+    }
+
+    for (const {offset, color} of this.stops()) {
+      gradient.addColorStop(
+        unwrap(offset),
+        new Color(unwrap(color)).serialize(),
+      );
+    }
+
+    return gradient;
+  }
+}

package/src/lib/partials/Pattern.ts

@@ -0,0 +1,35 @@
+import {SimpleSignal} from '@canvas-commons/core';
+import {computed} from '../decorators/computed';
+import {initial, initializeSignals, signal} from '../decorators/signal';
+
+export type CanvasRepetition =
+  | null
+  | 'repeat'
+  | 'repeat-x'
+  | 'repeat-y'
+  | 'no-repeat';
+
+// TODO Support custom transformation matrices
+export interface PatternProps {
+  image: CanvasImageSource;
+  repetition?: CanvasRepetition;
+}
+
+export class Pattern {
+  @signal()
+  declare public readonly image: SimpleSignal<CanvasImageSource, this>;
+  @initial(null)
+  @signal()
+  declare public readonly repetition: SimpleSignal<CanvasRepetition, this>;
+
+  public constructor(props: PatternProps) {
+    initializeSignals(this, props);
+  }
+
+  @computed()
+  public canvasPattern(
+    context: CanvasRenderingContext2D,
+  ): CanvasPattern | null {
+    return context.createPattern(this.image(), this.repetition());
+  }
+}

package/src/lib/partials/RoughConfig.ts

@@ -0,0 +1,180 @@
+/**
+ * Rough.js integration types for Canvas Commons
+ *
+ * @remarks
+ * These types define the configuration options for rendering shapes with
+ * a hand-drawn, sketchy appearance using Rough.js.
+ */
+
+/**
+ * Fill style options for rough shapes.
+ *
+ * @remarks
+ * - `hachure`: Parallel lines filling the shape (default)
+ * - `solid`: Solid fill with slight irregularity
+ * - `zigzag`: Zigzag pattern filling
+ * - `cross-hatch`: Crossed parallel lines
+ * - `dots`: Dotted pattern filling
+ * - `dashed`: Dashed lines filling
+ * - `zigzag-line`: Zigzag lines filling
+ */
+export type RoughFillStyle =
+  | 'hachure'
+  | 'solid'
+  | 'zigzag'
+  | 'cross-hatch'
+  | 'dots'
+  | 'dashed'
+  | 'zigzag-line';
+
+/**
+ * Configuration options for rough rendering.
+ *
+ * @remarks
+ * These options control the appearance of the hand-drawn style.
+ * All numeric values can be animated using signals.
+ */
+export interface RoughConfig {
+  /**
+   * Numerical value indicating how rough the drawing is.
+   *
+   * @remarks
+   * A value of 0 will produce a smooth shape, while higher values
+   * introduce more irregularity. Typical range is 0-10.
+   *
+   * @defaultValue 1
+   */
+  roughness: number;
+
+  /**
+   * Controls the curve deviation from a straight line.
+   *
+   * @remarks
+   * A value of 0 will cause lines to be perfectly straight.
+   * Higher values introduce more curvature.
+   *
+   * @defaultValue 1
+   */
+  bowing: number;
+
+  /**
+   * Seed for the random number generator.
+   *
+   * @remarks
+   * Using the same seed produces consistent results, which is useful
+   * for reproducible animations.
+   */
+  seed?: number;
+
+  /**
+   * Fill style for the shape.
+   *
+   * @defaultValue 'hachure'
+   */
+  fillStyle: RoughFillStyle;
+
+  /**
+   * Thickness of the lines used for filling.
+   *
+   * @remarks
+   * Only applicable for hachure, cross-hatch, and similar fill styles.
+   *
+   * @defaultValue Half of strokeWidth, or 1
+   */
+  fillWeight?: number;
+
+  /**
+   * Angle of the hachure lines in degrees.
+   *
+   * @remarks
+   * Only applicable for hachure and cross-hatch fill styles.
+   *
+   * @defaultValue -41
+   */
+  hachureAngle: number;
+
+  /**
+   * Gap between hachure lines in pixels.
+   *
+   * @remarks
+   * Only applicable for hachure, cross-hatch, and similar fill styles.
+   *
+   * @defaultValue 4 times strokeWidth
+   */
+  hachureGap: number;
+
+  /**
+   * Curve tightness for hachure lines.
+   *
+   * @remarks
+   * Lower values create more curved hachure lines.
+   *
+   * @defaultValue 0.95
+   */
+  curveStepCount?: number;
+
+  /**
+   * Simplification tolerance for paths.
+   *
+   * @remarks
+   * Higher values simplify the path more aggressively.
+   *
+   * @defaultValue 0
+   */
+  simplification?: number;
+
+  /**
+   * Whether to disable multi-stroke rendering.
+   *
+   * @remarks
+   * By default, Rough.js renders strokes with multiple lines for a
+   * more sketchy appearance. Set to true to use a single stroke.
+   *
+   * @defaultValue false
+   */
+  disableMultiStroke?: boolean;
+
+  /**
+   * Whether to disable multi-stroke fill.
+   *
+   * @remarks
+   * By default, Rough.js renders fills with multiple passes.
+   * Set to true to use a single fill pass.
+   *
+   * @defaultValue false
+   */
+  disableMultiStrokeFill?: boolean;
+}
+
+/**
+ * Partial rough configuration with defaults applied.
+ */
+export type PartialRoughConfig = Partial<RoughConfig>;
+
+/**
+ * Get default rough configuration.
+ *
+ * @returns Default configuration values
+ */
+export function getDefaultRoughConfig(): RoughConfig {
+  return {
+    roughness: 1,
+    bowing: 1,
+    fillStyle: 'hachure',
+    hachureAngle: -41,
+    hachureGap: 4,
+  };
+}
+
+/**
+ * Merge partial rough configuration with defaults.
+ *
+ * @param config - Partial configuration to merge
+ * @returns Complete configuration with defaults applied
+ */
+export function mergeRoughConfig(config: PartialRoughConfig): RoughConfig {
+  return {
+    ...getDefaultRoughConfig(),
+    ...config,
+  };
+}

package/src/lib/partials/ShaderConfig.ts

@@ -0,0 +1,122 @@
+import {
+  experimentalLog,
+  SignalValue,
+  useLogger,
+  useScene,
+  WebGLConvertible,
+} from '@canvas-commons/core';
+import {Node} from '../components';
+
+/**
+ * Describes a shader program used to apply effects to nodes.
+ *
+ * @experimental
+ */
+export interface ShaderConfig {
+  /**
+   * The source code of the fragment shader.
+   *
+   * @example
+   * ```glsl
+   * #version 300 es
+   * precision highp float;
+   *
+   * #include "@canvas-commons/core/shaders/common.glsl"
+   *
+   * void main() {
+   *     out_color = texture(core_source_tx, source_uv);
+   * }
+   * ```
+   */
+  fragment: string;
+
+  /**
+   * Custom uniforms to be passed to the shader.
+   *
+   * @remarks
+   * The keys of this object will be used as the uniform names.
+   * The values can be either a number or an array of numbers.
+   * The following table shows how the values will be mapped to GLSL types.
+   *
+   * | TypeScript                         | GLSL    |
+   * | ---------------------------------- | ------- |
+   * | `number`                           | `float` |
+   * | `[number, number]`                 | `vec2`  |
+   * | `[number, number, number]`         | `vec3`  |
+   * | `[number, number, number, number]` | `vec4`  |
+   *
+   * @example
+   * ```ts
+   * const shader = {
+   *   // ...
+   *   uniforms: {
+   *     my_value: () => 1,
+   *     my_vector: [1, 2, 3],
+   *   },
+   * };
+   * ```
+   *
+   * ```glsl
+   * uniform float my_value;
+   * uniform vec3 my_vector;
+   * ```
+   */
+  uniforms?: Record<string, SignalValue<number | number[] | WebGLConvertible>>;
+
+  /**
+   * A custom hook run before the shader is used.
+   *
+   * @remarks
+   * Gives you low-level access to the WebGL context and the shader program.
+   *
+   * @param gl - WebGL context.
+   * @param program - The shader program.
+   */
+  setup?: (gl: WebGL2RenderingContext, program: WebGLProgram) => void;
+
+  /**
+   * A custom hook run after the shader is used.
+   *
+   * @remarks
+   * Gives you low-level access to the WebGL context and the shader program.
+   * Can be used to clean up resources created in the {@link setup} hook.
+   *
+   * @param gl - WebGL context.
+   * @param program - The shader program.
+   */
+  teardown?: (gl: WebGL2RenderingContext, program: WebGLProgram) => void;
+}
+
+export type PossibleShaderConfig =
+  | (ShaderConfig | string)[]
+  | ShaderConfig
+  | string
+  | null;
+
+export function parseShader(
+  this: Node,
+  value: PossibleShaderConfig,
+): ShaderConfig[] {
+  let result: ShaderConfig[];
+  if (!value) {
+    result = [];
+  } else if (typeof value === 'string') {
+    result = [{fragment: value}];
+  } else if (Array.isArray(value)) {
+    result = value.map(item =>
+      typeof item === 'string' ? {fragment: item} : item,
+    );
+  } else {
+    result = [value];
+  }
+
+  if (!useScene().experimentalFeatures && result.length > 0) {
+    result = [];
+    useLogger().log({
+      ...experimentalLog(`Node uses experimental shaders.`),
+      inspect: this.key,
+    });
+  }
+
+  return result;
+}

package/src/lib/partials/index.ts

@@ -0,0 +1,5 @@
+export * from './Filter';
+export * from './Gradient';
+export * from './Pattern';
+export * from './RoughConfig';
+export * from './types';

package/src/lib/partials/types.ts

@@ -0,0 +1,58 @@
+import {Color, PossibleColor} from '@canvas-commons/core';
+import type {Gradient} from './Gradient';
+import type {Pattern} from './Pattern';
+
+export type FlexDirection = 'row' | 'row-reverse' | 'column' | 'column-reverse';
+
+export type FlexWrap = 'nowrap' | 'wrap' | 'wrap-reverse';
+
+export type FlexBasis =
+  | Length
+  | 'content'
+  | 'max-content'
+  | 'min-content'
+  | 'fit-content'
+  | null;
+
+export type FlexContent =
+  | 'center'
+  | 'start'
+  | 'end'
+  | 'space-between'
+  | 'space-around'
+  | 'space-evenly'
+  | 'stretch';
+
+export type FlexItems = 'center' | 'start' | 'end' | 'stretch' | 'baseline';
+
+export type TextWrap = boolean | 'pre';
+
+export type LayoutMode = boolean | null;
+
+/**
+ * Represents a length used by most layout properties.
+ *
+ * @remarks
+ * The value can be either:
+ * - `number` - the desired length in pixels
+ * - `${number}%` - a string with the desired length in percents, for example
+ *                  `'50%'`
+ */
+export type Length = number | `${number}%`;
+
+/**
+ * Represents a desired length used internally by layout Nodes.
+ *
+ * @remarks
+ * When the desired length is set to `null` it represents a default value for
+ * whatever property it describes.
+ */
+export type DesiredLength = Length | null;
+
+/**
+ * Represents a length limit used by layout properties such as `max-width`.
+ */
+export type LengthLimit = Length | null | 'max-content' | 'min-content';
+
+export type PossibleCanvasStyle = null | PossibleColor | Gradient | Pattern;
+export type CanvasStyle = null | Color | Gradient | Pattern;