// Type definitions for svg-sprite // Project: https://github.com/jkphl/svg-sprite // Definitions by: Qubo // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped /// /// /// declare module "svg-sprite" { import File = require('vinyl'); import winston = require('winston'); namespace sprite { interface SVGSpriterConstructor extends NodeJS.EventEmitter { /** * The spriter's constructor (always the entry point) * @param config Main configuration for the spriting process */ new(config: Config): SVGSpriter; } interface SVGSpriter { /** * Registering source SVG files * @param file Absolute path to the SVG file or a vinyl file object carrying all the necessary values (the following arguments are ignored then). * @param name The "local" part of the file path, possibly including subdirectories which will get traversed to CSS selectors using the shape.id.separator configuration option. * @param svg SVG file content. */ add(file: string|File, name: string, svg: string): SVGSpriter; /** * Registering source SVG files * @param file Absolute path to the SVG file or a vinyl file object carrying all the necessary values (the following arguments are ignored then). */ add(file: File): SVGSpriter; /** * Triggering the sprite compilation * @param config Configuration object setting the output mode parameters for a single compilation run. If omitted, the mode property of the main configuration used for the constructor will be used. * @param callback Callback triggered when the compilation has finished. */ compile(config: Config, callback: CompileCallback): SVGSpriter; /** * Triggering the sprite compilation * @param callback Callback triggered when the compilation has finished. */ compile(callback: CompileCallback): void; /** * Accessing the intermediate SVG resources * @param dest Base directory for the SVG files in case the will be written to disk. * @param callback Callback triggered when the shapes are available. */ getShapes(dest: string, callback: GetShapesCallback): void; } interface Config { /** * Main output directory * @default '.' */ dest?: string; /** * Logging verbosity or custom logger */ log?: string|winston.LoggerInstance; /** * SVG shape configuration */ shape?: Shape; /** * Sprite SVG options */ svg?: Svg; /** * Custom templating variables */ variables?: any; /** * Output mode configurations */ mode?: Mode; } /** * All settings affecting the SVG shapes of the sprite */ interface Shape { /** * SVG shape ID related options */ id?: { /** * Separator for directory name traversal */ separator?: string; /** * SVG shape ID generator callback */ generator?: string|((svg: string) => string); /** * File name separator for shape states (e.g. ':hover') */ pseudo?: string; /** * Whitespace replacement for shape IDs */ whitespace?: string; }; /** * Dimension related options */ dimension?: { /** * Max. shape width */ maxWidth?: number; /** * Max. shape height */ maxHeight?: number; /** * Floating point precision */ precision?: number; /** * Width and height attributes on embedded shapes */ attributes?: boolean; }; /** * Spacing related options */ spacing?: { /** * Padding around all shapes */ padding?: number|number[]; /** * Padding strategy (similar to CSS `box-sizing`) */ box?: string; }; /** * List of transformations / optimizations */ transform?: (string|CustomConfigurationTransform|CustomCallbackTransform)[]; /** * Path to YAML file with meta / accessibility data */ meta?: string; /** * Path to YAML file with extended alignment data */ align?: string; /** * Output directory for optimized intermediate SVG shapes */ dest?: string; } /** * Pre-defined shape transformation with custom configuration */ interface CustomConfigurationTransform { [transformationName: string]: { plugins?: { [transformationName: string]: boolean }[]; } } /** * Custom callback transformation */ interface CustomCallbackTransform { [transformationName: string]: { /** * Custom callback transformation * @param shape SVG shape object * @param sprite SVG spriter * @param callback Callback */ (shape: any, sprite: SVGSpriter, callback: Function): any; } } interface Svg { /** * Output an XML declaration at the very beginning of each compiled sprite. * If you provide a non-empty string here, it will be used one-to-one as declaration (e.g. ). * If you set this to TRUE, *svg-sprite* will look at the registered shapes for an XML declaration and use the first one it can find. * @default true */ xmlDeclaration?: boolean|string; /** * Include a declaration in each compiled sprite. If you provide a non-empty string here, * it will be used one-to-one as declaration (e.g. ). * If you set this to TRUE, *svg-sprite* will look at the registered shapes for a DOCTYPE declaration and use the first one it can find. * @default true */ doctypeDeclaration?: boolean|string; /** * In order to avoid ID clashes, the default behavior is to namespace all IDs in the source SVGs before compiling them into a sprite. * Each ID is prepended with a unique string. In some situations, it might be desirable to disable ID namespacing, e.g. when you want to script the resulting sprite. * Just set svg.namespaceIDs to FALSE then and be aware that you might also want to disable SVGO's ID minification (shape.transform.svgo.plugins: [{cleanupIDs: false}]). * @default true */ namespaceIDs?: boolean; /** * In order to avoid CSS class name ambiguities, the default behavior is to namespace CSS class names in the source SVGs before compiling them into a sprite. * Each class name is prepended with a unique string. Disable this option to keep the class names untouched. * @default true */ namespaceClassnames?: boolean; /** * If truthy, width and height attributes will be set on the sprite's element (where applicable). * @default true */ dimensionAttributes?: boolean; /** * Shorthand for applying custom attributes to the outermost element. * Please be aware that certain attributes (e.g. viewBox) will be calculated dynamically and override custom rootAttributes in any case. */ rootAttributes?: any; /** * Floating point precision for CSS positioning values (defaults to -1 meaning highest possible precision). */ precision?: number; /** * Callback (or list of callbacks) that will be applied to the resulting SVG sprites as global [post-processing transformation](#svg-sprite-customization). * transform: Function∣Array */ transform?: SvgTransformer|SvgTransformer[]; } interface SvgTransformer { /** * Custom sprite SVG transformation * @param svg Sprite SVG * @return Processed SVG */ (svg: string): string; } interface Mode { css?: CssAndViewSpecificModeConfig|boolean; view?: CssAndViewSpecificModeConfig|boolean; defs?: DefsAndSymbolSpecificModeConfig|boolean; symbol?: DefsAndSymbolSpecificModeConfig|boolean; stack?: ModeConfig|boolean; [customConfigName: string]: ModeConfig; } interface ModeConfig { /** * Base directory for sprite and CSS file output. If not absolute, the path will be resolved using the main output directory (see global dest option). * @default "" */ dest?: string; /** * Used for prefixing the [shape ID](#shape-ids) during CSS selector construction. If the value is empty, * no prefix will be used. The prefix may contain the placeholder "%s" (e.g. ".svg %s-svg"), * which will then get replaced by the shape ID. Please be aware that "%" is a special character * in this context and that you'll have to escape it by another percent sign ("%%") in case you want * to output it to your stylesheets (e.g. for a [Sass placeholder selector](http://sass-lang.com/documentation/file.SASS_REFERENCE.html#placeholder_selectors_)). * @default ".svg-%s" */ prefix?: string; /** * A non-empty string value will trigger the creation of additional CSS rules specifying the dimensions of each shape in the sprite. * The string will be used as suffix to mode..prefix during CSS selector construction and may contain the placeholder "%s", * which will get replaced by the value of mode..prefix. * A boolean TRUE will cause the dimensions to be included directly into each shape's CSS rule (only available for «css» and «view» sprites). * @default "-dims" */ dimensions?: string|boolean; /** * SVG sprite path and file name, relative to the mode..dest directory. * You may omit the file extension, in which case it will be set to ".svg" automatically. * @default "svg/sprite..svg" */ sprite?: string; /** * Add a content based hash to the name of the sprite file so that clients reliably reload the sprite * when it's content changes («cache busting»). Defaults to false except for «css» and «view» sprites. * @default true∣false */ bust?: boolean; /** * Collection of [stylesheet rendering configurations](#rendering-configurations). * The keys are used as file extensions as well as file return keys. At present, * there are default templates for the file extensions css ([CSS](http://www.w3.org/Style/CSS/)), * scss ([Sass](http://sass-lang.com/)), less ([Less](http://lesscss.org/)) and styl ([Stylus](http://learnboost.github.io/stylus/)), * which all reside in the directory tmpl/css. Example: {css: true, scss: {dest: '_sprite.scss'}} * @default {} */ render?: { [key: string]: RenderingConfiguration|boolean }; /** * Enabling this will trigger the creation of an HTML document demoing the usage of the sprite. Please see below for details on [rendering configurations](#rendering-configurations). * @default false */ example?: RenderingConfiguration|boolean; /** * Specify svg-sprite which output mode to use with this configuration */ mode?: string; } interface RenderingConfiguration { /** * HTML document Mustache template * @default "tmpl//sprite.html" */ template?: string; /** * HTML document destination * @default "sprite..html" */ dest?: string; } interface CssAndViewSpecificModeConfig extends ModeConfig { /** * The arrangement of the shapes within the sprite. Might be "vertical", "horizontal", "diagonal" or "packed" * (with the latter being the most compact type). It depends on your project which layout is best for you. * @default "packed" */ layout?: string; /** * If given and not empty, this will be the selector name of a CSS rule commonly specifying the background-image * and background-repeat properties for all the shapes in the sprite (thus saving some bytes by not unnecessarily repeating them for each shape) */ common?: string; /** * If given and not empty, a mixin with this name will be added to supporting output formats (e.g. Sass, LESS, Stylus), * specifying the background-image and background-repeat properties for all the shapes in the sprite. * You may use it for creating custom CSS within @media rules. The mixin acts much like the common rule. * In fact, you can even combine the two - if both are enabled, the common rule will use the mixin internally. */ mixin?: string; } interface DefsAndSymbolSpecificModeConfig extends ModeConfig { /** * If you want to embed the sprite into your HTML source, you will want to set this to true * in order to prevent the creation of SVG namespace declarations and to set some other attributes for effectively hiding the library sprite. * @default false */ inline?: boolean; } interface CompileCallback { (error: Error, result: any, data: any): any; } interface GetShapesCallback { (error: Error, result: File[]): any; } } var sprite: sprite.SVGSpriterConstructor; export = sprite; }