@iconify/tools 3.0.3 → 3.0.4

package/lib/export/directory.d.ts

@@ -0,0 +1,25 @@
+import { IconSet } from '../icon-set/index.js';
+import { ExportTargetOptions } from './helpers/prepare.js';
+import '@iconify/types';
+import '@iconify/utils/lib/customisations/defaults';
+import '../icon-set/types.js';
+import '../svg/index.js';
+import '@iconify/utils/lib/icon-set/tree';
+
+/**
+ * Options
+ */
+interface ExportToDirectoryOptions extends ExportTargetOptions {
+    autoHeight?: boolean;
+    includeAliases?: boolean;
+    includeChars?: boolean;
+    log?: boolean;
+}
+/**
+ * Export icon set to directory
+ *
+ * Returns list of stored files
+ */
+declare function exportToDirectory(iconSet: IconSet, options: ExportToDirectoryOptions): Promise<string[]>;
+
+export { ExportToDirectoryOptions, exportToDirectory };

package/lib/export/helpers/custom-files.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Options
+ */
+interface ExportOptionsWithCustomFiles {
+    customFiles?: Record<string, string | Record<string, unknown> | null>;
+}
+/**
+ * Write custom files
+ */
+declare function exportCustomFiles(dir: string, options: ExportOptionsWithCustomFiles, result?: Set<string>): Promise<void>;
+
+export { ExportOptionsWithCustomFiles, exportCustomFiles };

package/lib/export/helpers/prepare.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Common options for all functions that export to directory
+ */
+interface ExportTargetOptions {
+    target: string;
+    cleanup?: boolean;
+}
+/**
+ * Normalize directory
+ */
+declare function normalizeDir(dir: string): string;
+/**
+ * Prepare directory for export
+ *
+ * Also normalizes directory and returns normalized value
+ */
+declare function prepareDirectoryForExport(options: ExportTargetOptions): Promise<string>;
+
+export { ExportTargetOptions, normalizeDir, prepareDirectoryForExport };

package/lib/export/helpers/types-version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Get current version of Iconify Types package
+ */
+declare function getTypesVersion(): Promise<string>;
+
+export { getTypesVersion };

package/lib/export/icon-package.d.ts

@@ -0,0 +1,25 @@
+import { IconSet } from '../icon-set/index.js';
+import { ExportTargetOptions } from './helpers/prepare.js';
+import { ExportOptionsWithCustomFiles } from './helpers/custom-files.js';
+import '@iconify/types';
+import '@iconify/utils/lib/customisations/defaults';
+import '../icon-set/types.js';
+import '../svg/index.js';
+import '@iconify/utils/lib/icon-set/tree';
+
+/**
+ * Options
+ */
+interface ExportIconPackageOptions extends ExportTargetOptions, ExportOptionsWithCustomFiles {
+    package?: Record<string, unknown>;
+    module?: boolean;
+    typesContent?: string;
+}
+/**
+ * Export icon set as single icon packages
+ *
+ * Used for exporting `@iconify-icons/{prefix}` packages
+ */
+declare function exportIconPackage(iconSet: IconSet, options: ExportIconPackageOptions): Promise<string[]>;
+
+export { ExportIconPackageOptions, exportIconPackage };

package/lib/export/json-package.d.ts

@@ -0,0 +1,23 @@
+import { IconSet } from '../icon-set/index.js';
+import { ExportTargetOptions } from './helpers/prepare.js';
+import { ExportOptionsWithCustomFiles } from './helpers/custom-files.js';
+import '@iconify/types';
+import '@iconify/utils/lib/customisations/defaults';
+import '../icon-set/types.js';
+import '../svg/index.js';
+import '@iconify/utils/lib/icon-set/tree';
+
+/**
+ * Options
+ */
+interface ExportJSONPackageOptions extends ExportTargetOptions, ExportOptionsWithCustomFiles {
+    package?: Record<string, unknown>;
+}
+/**
+ * Export icon set as JSON package
+ *
+ * Used for exporting `@iconify-json/{prefix}` packages
+ */
+declare function exportJSONPackage(iconSet: IconSet, options: ExportJSONPackageOptions): Promise<string[]>;
+
+export { ExportJSONPackageOptions, exportJSONPackage };

package/lib/icon-set/index.d.ts

@@ -0,0 +1,161 @@
+import { IconifyInfo, IconifyJSON } from '@iconify/types';
+import { IconifyIconCustomisations } from '@iconify/utils/lib/customisations/defaults';
+import { IconSetIconEntry, IconCategory, IconSetIconType, IconSetAsyncForEachCallback, IconSetSyncForEachCallback, ResolvedIconifyIcon, CommonIconProps, CheckThemeResult } from './types.js';
+import { SVG } from '../svg/index.js';
+import { ParentIconsTree } from '@iconify/utils/lib/icon-set/tree';
+
+/**
+ * Sort theme keys: long keys first
+ *
+ * Applies changes to parameter, but also returns it
+ */
+declare function sortThemeKeys(keys: string[]): string[];
+/**
+ * Export icon set
+ */
+declare class IconSet {
+    /**
+     * Properties. You can write directly to almost any property, but avoid writing to
+     * 'entries' and 'categories' properties, there are functions for that.
+     */
+    prefix: string;
+    lastModified: number;
+    entries: Record<string, IconSetIconEntry>;
+    info: IconifyInfo | undefined;
+    categories: Set<IconCategory>;
+    prefixes: Record<string, string>;
+    suffixes: Record<string, string>;
+    /**
+     * Load icon set
+     */
+    constructor(data: IconifyJSON);
+    /**
+     * Load icon set
+     */
+    load(data: IconifyJSON): void;
+    /**
+     * Update last modification time
+     */
+    updateLastModified(value?: number): void;
+    /**
+     * List icons
+     */
+    list(types?: IconSetIconType[]): string[];
+    /**
+     * forEach function to loop through all entries.
+     * Supports asynchronous callbacks.
+     *
+     * Callback should return false to stop loop.
+     */
+    forEach(callback: IconSetAsyncForEachCallback, types?: IconSetIconType[]): Promise<void>;
+    /**
+     * Synchronous version of forEach function to loop through all entries.
+     *
+     * Callback should return false to stop loop.
+     */
+    forEachSync(callback: IconSetSyncForEachCallback, types?: IconSetIconType[]): void;
+    /**
+     * Get parent icons tree
+     *
+     * Returns parent icons list for each icon, null if failed to resolve.
+     * In parent icons list, first element is a direct parent, last is icon. Does not include item.
+     *
+     * Examples:
+     *   'alias3': ['alias2', 'alias1', 'icon']
+     * 	 'icon': []
+     * 	 'bad-icon': null
+     */
+    getTree(names?: string[]): ParentIconsTree;
+    /**
+     * Resolve icon
+     */
+    resolve(name: string, full: false): ResolvedIconifyIcon | null;
+    resolve(name: string): ResolvedIconifyIcon | null;
+    resolve(name: string, full: true): Required<ResolvedIconifyIcon> | null;
+    /**
+     * Generate HTML
+     */
+    toString(name: string, customisations?: IconifyIconCustomisations): string | null;
+    /**
+     * Get SVG instance for icon
+     */
+    toSVG(name: string): SVG | null;
+    /**
+     * Export icon set
+     */
+    export(validate?: boolean): IconifyJSON;
+    /**
+     * Get characters map
+     */
+    chars(names?: string[]): Record<string, string>;
+    /**
+     * Filter icons
+     */
+    _filter(callback: (name: string, item: IconSetIconEntry, icon?: ResolvedIconifyIcon) => boolean): string[];
+    /**
+     * Count icons
+     */
+    count(): number;
+    /**
+     * Find category by title
+     */
+    findCategory(title: string, add: boolean): IconCategory | null;
+    /**
+     * Count icons in category, remove category if empty
+     *
+     * Hidden icons and aliases do not count
+     */
+    listCategory(category: IconCategory | string): string[] | null;
+    /**
+     * Check if icon exists
+     */
+    exists(name: string): boolean;
+    /**
+     * Remove icons. Returns number of removed icons
+     *
+     * If removeDependencies is a string, it represents new parent for all aliases of removed icon. New parent cannot be alias or variation.
+     */
+    remove(name: string, removeDependencies?: boolean | string): number;
+    /**
+     * Remove icon
+     */
+    rename(oldName: string, newName: string): boolean;
+    /**
+     * Add/update item
+     */
+    setItem(name: string, item: IconSetIconEntry): boolean;
+    /**
+     * Add/update icon
+     */
+    setIcon(name: string, icon: ResolvedIconifyIcon): boolean;
+    /**
+     * Add/update alias without props
+     */
+    setAlias(name: string, parent: string): boolean;
+    /**
+     * Add/update alias with props
+     */
+    setVariation(name: string, parent: string, props: CommonIconProps): boolean;
+    /**
+     * Icon from SVG. Updates old icon if it exists
+     */
+    fromSVG(name: string, svg: SVG): boolean;
+    /**
+     * Add or remove character for icon
+     */
+    toggleCharacter(iconName: string, char: string, add: boolean): boolean;
+    /**
+     * Add or remove category for icon
+     */
+    toggleCategory(iconName: string, category: string, add: boolean): boolean;
+    /**
+     * Find icons that belong to theme
+     */
+    checkTheme(prefix: boolean): CheckThemeResult;
+}
+/**
+ * Create blank icon set
+ */
+declare function blankIconSet(prefix: string): IconSet;
+
+export { IconSet, blankIconSet, sortThemeKeys };

package/lib/icon-set/match.d.ts

@@ -0,0 +1,14 @@
+import { FullIconifyIcon } from '@iconify/utils/lib/icon/defaults';
+import { IconSet } from './index.js';
+import '@iconify/types';
+import '@iconify/utils/lib/customisations/defaults';
+import './types.js';
+import '../svg/index.js';
+import '@iconify/utils/lib/icon-set/tree';
+
+/**
+ * Find matching icon in icon set
+ */
+declare function findMatchingIcon(iconSet: IconSet, icon: FullIconifyIcon): string | null;
+
+export { findMatchingIcon };

package/lib/icon-set/merge.d.ts

@@ -0,0 +1,13 @@
+import { IconSet } from './index.js';
+import '@iconify/types';
+import '@iconify/utils/lib/customisations/defaults';
+import './types.js';
+import '../svg/index.js';
+import '@iconify/utils/lib/icon-set/tree';
+
+/**
+ * Merge icon sets
+ */
+declare function mergeIconSets(oldIcons: IconSet, newIcons: IconSet): IconSet;
+
+export { mergeIconSets };

package/lib/icon-set/modified.d.ts

@@ -0,0 +1,15 @@
+import { IconSet } from './index.js';
+import '@iconify/types';
+import '@iconify/utils/lib/customisations/defaults';
+import './types.js';
+import '../svg/index.js';
+import '@iconify/utils/lib/icon-set/tree';
+
+/**
+ * Check if icons in an icon set were updated.
+ *
+ * This function checks only icons, not metadata. It also ignores icon visibility.
+ */
+declare function hasIconDataBeenModified(set1: IconSet, set2: IconSet): boolean;
+
+export { hasIconDataBeenModified };

package/lib/icon-set/props.d.ts

@@ -0,0 +1,13 @@
+import { CommonIconProps } from './types.js';
+import '@iconify/types';
+
+/**
+ * Common properties for icon and alias
+ */
+declare const defaultCommonProps: Required<CommonIconProps>;
+/**
+ * Filter icon props: copies properties, removing undefined and default entries
+ */
+declare function filterProps(data: CommonIconProps, reference: CommonIconProps, compareDefaultValues: boolean): CommonIconProps;
+
+export { defaultCommonProps, filterProps };

package/lib/icon-set/tags.d.ts

@@ -0,0 +1,22 @@
+import { IconSet } from './index.js';
+import '@iconify/types';
+import '@iconify/utils/lib/customisations/defaults';
+import './types.js';
+import '../svg/index.js';
+import '@iconify/utils/lib/icon-set/tree';
+
+declare const paletteTags: {
+    monotone: string;
+    palette: string;
+};
+declare const sizeTags: {
+    square: string;
+    gridPrefix: string;
+    heightPrefix: string;
+};
+/**
+ * Add tags to icon set
+ */
+declare function addTagsToIconSet(iconSet: IconSet, customTags?: string[]): string[];
+
+export { addTagsToIconSet, paletteTags, sizeTags };

package/lib/icon-set/types.d.ts

@@ -0,0 +1,75 @@
+import { ExtendedIconifyIcon, ExtendedIconifyAlias, IconifyOptional, IconifyIcon } from '@iconify/types';
+
+/**
+ * Category item
+ */
+interface IconCategory {
+    title: string;
+    count: number;
+}
+/**
+ * Get common properties: IconifyOptional + APIIconAttributes
+ */
+type CommonProps<A, B> = {
+    [K in keyof A & keyof B]?: A[K] extends B[K] ? A[K] : never;
+};
+type CommonIconProps = CommonProps<ExtendedIconifyIcon, ExtendedIconifyAlias>;
+/**
+ * Exclude IconifyOptional from CommonIconProps
+ */
+type ExtraIconProps = Omit<CommonIconProps, keyof IconifyOptional>;
+/**
+ * Partials
+ */
+interface IconWithChars {
+    chars: Set<string>;
+}
+interface IconWithPropsData extends IconWithChars {
+    props: CommonIconProps;
+}
+interface IconWithCategories {
+    categories: Set<IconCategory>;
+}
+interface IconParentData {
+    parent: string;
+}
+/**
+ * Icon types
+ */
+interface IconSetIcon extends IconWithPropsData, IconWithCategories {
+    type: 'icon';
+    body: string;
+}
+interface IconSetIconAlias extends IconWithChars, IconParentData {
+    type: 'alias';
+}
+interface IconSetIconVariation extends IconWithPropsData, IconParentData {
+    type: 'variation';
+}
+/**
+ * All icon types
+ */
+type IconSetIconEntry = IconSetIcon | IconSetIconAlias | IconSetIconVariation;
+type IconSetIconType = IconSetIconEntry['type'];
+/**
+ * Full icon with extra stuff
+ */
+interface ResolvedIconifyIcon extends IconifyIcon, ExtraIconProps {
+}
+/**
+ * Result for checking theme: list of names for each theme
+ */
+interface CheckThemeResult {
+    valid: Record<string, string[]>;
+    invalid: string[];
+}
+/**
+ * Callback for forEach functions
+ *
+ * Return false to stop loop
+ */
+type IconSetForEachCallbackResult = void | false;
+type IconSetAsyncForEachCallback = (name: string, type: IconSetIconEntry['type']) => Promise<IconSetForEachCallbackResult> | IconSetForEachCallbackResult;
+type IconSetSyncForEachCallback = (name: string, type: IconSetIconEntry['type']) => IconSetForEachCallbackResult;
+
+export { CheckThemeResult, CommonIconProps, ExtraIconProps, IconCategory, IconParentData, IconSetAsyncForEachCallback, IconSetIcon, IconSetIconAlias, IconSetIconEntry, IconSetIconType, IconSetIconVariation, IconSetSyncForEachCallback, IconWithCategories, IconWithChars, IconWithPropsData, ResolvedIconifyIcon };

package/lib/import/directory.d.ts

@@ -0,0 +1,51 @@
+import { IconSet } from '../icon-set/index.js';
+import { CleanupSVGOptions } from '../svg/cleanup.js';
+import '@iconify/types';
+import '@iconify/utils/lib/customisations/defaults';
+import '../icon-set/types.js';
+import '../svg/index.js';
+import '@iconify/utils/lib/icon-set/tree';
+import '../svg/cleanup/bad-tags.js';
+
+/**
+ * Entry for file
+ */
+interface ImportDirectoryFileEntry {
+    path: string;
+    subdir: string;
+    file: string;
+    ext: string;
+}
+/**
+ * Callback to get keyword for icon based on file name
+ *
+ * Returns:
+ * - string for new keyword
+ * - undefined to skip icon
+ *
+ * Callback can be asynchronous
+ */
+type ImportDirectoryKeywordCallbackResult = string | undefined;
+type Callback<T> = (file: ImportDirectoryFileEntry, defaultKeyword: string, iconSet: IconSet) => T;
+type AsyncCallback<T> = Callback<T | Promise<T>>;
+type ImportDirectoryKeywordCallback = AsyncCallback<ImportDirectoryKeywordCallbackResult>;
+type ImportDirectoryKeywordSyncCallback = Callback<ImportDirectoryKeywordCallbackResult>;
+/**
+ * Options
+ */
+interface ImportDirectoryOptions<K> extends CleanupSVGOptions {
+    prefix?: string;
+    includeSubDirs?: boolean;
+    keyword?: K;
+    ignoreImportErrors?: boolean;
+}
+/**
+ * Import all icons from directory
+ */
+declare function importDirectory(path: string, options?: ImportDirectoryOptions<ImportDirectoryKeywordCallback>): Promise<IconSet>;
+/**
+ * Import all icons from directory synchronously
+ */
+declare function importDirectorySync(path: string, options?: ImportDirectoryOptions<ImportDirectoryKeywordSyncCallback>): IconSet;
+
+export { ImportDirectoryFileEntry, ImportDirectoryKeywordCallback, ImportDirectoryKeywordSyncCallback, importDirectory, importDirectorySync };

package/lib/import/figma/index.d.ts

@@ -0,0 +1,19 @@
+import { DocumentNotModified } from '../../download/types/modified.js';
+import { FigmaIfModifiedSinceOption, FigmaImportOptions } from './types/options.js';
+import { FigmaImportResult } from './types/result.js';
+import '../../icon-set/index.js';
+import '@iconify/types';
+import '@iconify/utils/lib/customisations/defaults';
+import '../../icon-set/types.js';
+import '../../svg/index.js';
+import '@iconify/utils/lib/icon-set/tree';
+import './types/nodes.js';
+import './types/api.js';
+
+/**
+ * Import icon set from Figma
+ */
+declare function importFromFigma<T extends FigmaIfModifiedSinceOption & FigmaImportOptions>(options: T): Promise<FigmaImportResult | DocumentNotModified>;
+declare function importFromFigma(options: FigmaImportOptions): Promise<FigmaImportResult>;
+
+export { importFromFigma };

package/lib/import/figma/nodes.d.ts

@@ -0,0 +1,17 @@
+import { FigmaDocument } from './types/api.js';
+import { FigmaGetIconNodesOptions } from './types/options.js';
+import { FigmaNodesImportResult } from './types/result.js';
+import '../../icon-set/index.js';
+import '@iconify/types';
+import '@iconify/utils/lib/customisations/defaults';
+import '../../icon-set/types.js';
+import '../../svg/index.js';
+import '@iconify/utils/lib/icon-set/tree';
+import './types/nodes.js';
+
+/**
+ * Get node ids for icons
+ */
+declare function getFigmaIconNodes(document: FigmaDocument, options: FigmaGetIconNodesOptions): FigmaNodesImportResult;
+
+export { getFigmaIconNodes };

package/lib/import/figma/query.d.ts

@@ -0,0 +1,28 @@
+import { APICacheOptions } from '../../download/api/types.js';
+import { DocumentNotModified } from '../../download/types/modified.js';
+import { FigmaDocument } from './types/api.js';
+import { FigmaIfModifiedSinceOption, FigmaFilesQueryOptions, FigmaImagesQueryOptions } from './types/options.js';
+import { FigmaNodesImportResult } from './types/result.js';
+import '../../icon-set/index.js';
+import '@iconify/types';
+import '@iconify/utils/lib/customisations/defaults';
+import '../../icon-set/types.js';
+import '../../svg/index.js';
+import '@iconify/utils/lib/icon-set/tree';
+import './types/nodes.js';
+
+/**
+ * Get Figma files
+ */
+declare function figmaFilesQuery<T extends FigmaIfModifiedSinceOption & FigmaFilesQueryOptions>(options: T, cache?: APICacheOptions): Promise<FigmaDocument | DocumentNotModified>;
+declare function figmaFilesQuery(options: FigmaFilesQueryOptions, cache?: APICacheOptions): Promise<FigmaDocument>;
+/**
+ * Generate all images
+ */
+declare function figmaImagesQuery(options: FigmaImagesQueryOptions, nodes: FigmaNodesImportResult, cache?: APICacheOptions): Promise<FigmaNodesImportResult>;
+/**
+ * Download all images
+ */
+declare function figmaDownloadImages(nodes: FigmaNodesImportResult, cache?: APICacheOptions): Promise<FigmaNodesImportResult>;
+
+export { figmaDownloadImages, figmaFilesQuery, figmaImagesQuery };

package/lib/import/figma/types/api.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Basic document structure
+ */
+interface FigmaBoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface BaseFigmaNode {
+    id: string;
+    name: string;
+}
+interface GenericFigmaNode extends BaseFigmaNode {
+    type: string;
+    children?: FigmaNode[];
+}
+interface IconFigmaNode extends BaseFigmaNode {
+    type: 'FRAME' | 'COMPONENT' | 'INSTANCE';
+    clipsContent?: boolean;
+    absoluteBoundingBox?: FigmaBoundingBox;
+    children: FigmaNode[];
+}
+interface FigmaDocumentNode extends BaseFigmaNode {
+    type: 'DOCUMENT';
+    children: FigmaNode[];
+}
+type FigmaNode = GenericFigmaNode | IconFigmaNode;
+/**
+ * Document response from API
+ */
+interface FigmaDocument {
+    document: FigmaDocumentNode;
+    name: string;
+    version: string;
+    lastModified: string;
+    thumbnailUrl: string;
+    role: string;
+    editorType: 'figma' | 'figjam';
+}
+interface FigmaAPIError {
+    status: number;
+    err: string;
+}
+/**
+ * Result for retrieved icons
+ */
+interface FigmaAPIImagesResponse {
+    err?: string | null;
+    images: Record<string, string | null>;
+}
+
+export { FigmaAPIError, FigmaAPIImagesResponse, FigmaDocument, FigmaDocumentNode, FigmaNode, IconFigmaNode };

package/lib/import/figma/types/nodes.d.ts

@@ -0,0 +1,43 @@
+import { IconFigmaNode, FigmaDocument } from './api.js';
+import { FigmaNodesImportResult, FigmaIconNode } from './result.js';
+import '../../../icon-set/index.js';
+import '@iconify/types';
+import '@iconify/utils/lib/customisations/defaults';
+import '../../../icon-set/types.js';
+import '../../../svg/index.js';
+import '@iconify/utils/lib/icon-set/tree';
+
+type FigmaImportParentNodeType = 'CANVAS' | 'FRAME' | 'GROUP' | 'SECTION';
+type FigmaImportIconNodeType = IconFigmaNode['type'];
+/**
+ * Node information passed to callback
+ */
+interface FigmaParentNodeData {
+    id: string;
+    type: FigmaImportParentNodeType;
+    name: string;
+}
+interface FigmaImportNodeData {
+    id: string;
+    type: FigmaImportIconNodeType;
+    name: string;
+    width: number;
+    height: number;
+    parents: FigmaParentNodeData[];
+}
+/**
+ * Callback to check if node needs to be checked for icons
+ *
+ * Used to speed up processing by eleminating pages, frames and groups that do not need processing
+ */
+type FigmaImportParentNodeFilter = (node: FigmaParentNodeData[], document: FigmaDocument) => boolean;
+/**
+ * Check if node is an icon.
+ *
+ * Returns icon name on success, null or undefined if not should be ignored.
+ * Function can also return FigmaIconNode object, where it can put extra properties that can be used later
+ */
+type FigmaIconNodeWithKeyword = Partial<FigmaIconNode> & Pick<FigmaIconNode, 'keyword'>;
+type FigmaImportNodeFilter = (node: FigmaImportNodeData, nodes: FigmaNodesImportResult, document: FigmaDocument) => string | FigmaIconNodeWithKeyword | null | undefined;
+
+export { FigmaImportIconNodeType, FigmaImportNodeData, FigmaImportNodeFilter, FigmaImportParentNodeFilter, FigmaImportParentNodeType, FigmaParentNodeData };