@nice2dev/icons 1.0.0 → 1.0.3

package/dist/types/design-tokens.d.ts

@@ -0,0 +1,281 @@
+/**
+ * @file design-tokens.ts
+ * @description Design Tokens Integration for @nice2dev/icons
+ *
+ * Provides Style Dictionary compatible design tokens for icon styling.
+ * Supports auto-generation from design systems and custom token sources.
+ *
+ * @example
+ * ```ts
+ * // Generate tokens for Style Dictionary
+ * import { generateIconTokens, createTokensConfig } from '@nice2dev/icons/design-tokens';
+ *
+ * const tokens = generateIconTokens({
+ *   prefix: 'ntd',
+ *   namespace: 'icon',
+ *   colorTokens: {
+ *     primary: '{color.brand.500}',
+ *     secondary: '{color.gray.400}',
+ *   },
+ * });
+ *
+ * // tokens.json output
+ * ```
+ *
+ * @version 1.0.0
+ * @since 2026-03
+ * @license MIT
+ */
+/**
+ * Token value with metadata
+ */
+export interface DesignToken {
+    value: string | number;
+    type?: string;
+    description?: string;
+    deprecated?: boolean;
+    original?: {
+        value: string;
+    };
+    $extensions?: {
+        'org.nice2dev.icons'?: {
+            cssVariable?: string;
+            tailwindClass?: string;
+        };
+    };
+}
+/**
+ * Token group structure
+ */
+export interface TokenGroup {
+    [key: string]: DesignToken | TokenGroup;
+}
+/**
+ * Configuration for generating icon tokens
+ */
+export interface IconTokensConfig {
+    /** Token prefix (e.g., 'ntd') */
+    prefix?: string;
+    /** Token namespace (e.g., 'icon') */
+    namespace?: string;
+    /** Color tokens mapping */
+    colorTokens?: {
+        primary?: string;
+        secondary?: string;
+        accent?: string;
+        success?: string;
+        warning?: string;
+        error?: string;
+        info?: string;
+        muted?: string;
+    };
+    /** Size tokens mapping */
+    sizeTokens?: {
+        xs?: string | number;
+        sm?: string | number;
+        md?: string | number;
+        lg?: string | number;
+        xl?: string | number;
+        '2xl'?: string | number;
+    };
+    /** Stroke width tokens */
+    strokeTokens?: {
+        thin?: string | number;
+        normal?: string | number;
+        medium?: string | number;
+        thick?: string | number;
+        bold?: string | number;
+    };
+    /** Include animations tokens */
+    includeAnimations?: boolean;
+    /** Include variant tokens */
+    includeVariants?: boolean;
+}
+/**
+ * Style Dictionary format config
+ */
+export interface StyleDictionaryConfig {
+    source: string[];
+    platforms: {
+        [platform: string]: {
+            transformGroup?: string;
+            buildPath: string;
+            files: Array<{
+                destination: string;
+                format: string;
+                filter?: {
+                    attributes: {
+                        category: string;
+                    };
+                };
+            }>;
+        };
+    };
+}
+/**
+ * Default icon size tokens
+ */
+export declare const DEFAULT_SIZE_TOKENS: {
+    readonly xs: "0.75rem";
+    readonly sm: "1rem";
+    readonly md: "1.5rem";
+    readonly lg: "2rem";
+    readonly xl: "3rem";
+    readonly '2xl': "4rem";
+};
+/**
+ * Default icon color tokens
+ */
+export declare const DEFAULT_COLOR_TOKENS: {
+    readonly primary: "#3b82f6";
+    readonly secondary: "#64748b";
+    readonly accent: "#8b5cf6";
+    readonly success: "#22c55e";
+    readonly warning: "#f59e0b";
+    readonly error: "#ef4444";
+    readonly info: "#06b6d4";
+    readonly muted: "#9ca3af";
+};
+/**
+ * Default stroke width tokens
+ */
+export declare const DEFAULT_STROKE_TOKENS: {
+    readonly thin: "1";
+    readonly normal: "1.5";
+    readonly medium: "2";
+    readonly thick: "2.5";
+    readonly bold: "3";
+};
+/**
+ * Default animation tokens
+ */
+export declare const DEFAULT_ANIMATION_TOKENS: {
+    readonly duration: {
+        readonly instant: "0ms";
+        readonly fast: "150ms";
+        readonly normal: "300ms";
+        readonly slow: "500ms";
+        readonly slower: "1000ms";
+    };
+    readonly easing: {
+        readonly linear: "linear";
+        readonly easeIn: "cubic-bezier(0.4, 0, 1, 1)";
+        readonly easeOut: "cubic-bezier(0, 0, 0.2, 1)";
+        readonly easeInOut: "cubic-bezier(0.4, 0, 0.2, 1)";
+        readonly spring: "cubic-bezier(0.175, 0.885, 0.32, 1.275)";
+    };
+};
+/**
+ * Generates Style Dictionary compatible design tokens for icons.
+ *
+ * @param config - Token configuration
+ * @returns Token group object ready for Style Dictionary
+ *
+ * @example
+ * ```ts
+ * const tokens = generateIconTokens({
+ *   prefix: 'ntd',
+ *   colorTokens: {
+ *     primary: '{color.brand.500}',
+ *   },
+ * });
+ *
+ * // Output:
+ * // {
+ * //   ntd: {
+ * //     icon: {
+ * //       size: { md: { value: '1.5rem', type: 'dimension' } },
+ * //       color: { primary: { value: '{color.brand.500}', type: 'color' } },
+ * //     }
+ * //   }
+ * // }
+ * ```
+ */
+export declare function generateIconTokens(config?: IconTokensConfig): TokenGroup;
+/**
+ * Creates a Style Dictionary configuration for icon tokens.
+ *
+ * @param options - Configuration options
+ * @returns Style Dictionary config object
+ */
+export declare function createStyleDictionaryConfig(options?: {
+    sourcePath?: string;
+    outputPath?: string;
+    platforms?: string[];
+}): StyleDictionaryConfig;
+/**
+ * Generates CSS custom properties from icon tokens.
+ *
+ * @param tokens - Token group
+ * @param selector - CSS selector (default: ':root')
+ * @returns CSS string with custom properties
+ */
+export declare function generateCSSVariables(tokens: TokenGroup, selector?: string): string;
+/**
+ * Generates Tailwind CSS config from icon tokens.
+ *
+ * @param tokens - Token group
+ * @returns Tailwind config extend object
+ */
+export declare function generateTailwindConfig(tokens: TokenGroup): {
+    colors: Record<string, string>;
+    spacing: Record<string, string>;
+    strokeWidth: Record<string, string>;
+};
+/**
+ * Converts icon tokens to Figma Tokens format.
+ * Compatible with the Figma Tokens plugin.
+ *
+ * @param tokens - Token group
+ * @returns Figma Tokens compatible object
+ */
+export declare function toFigmaTokens(tokens: TokenGroup): Record<string, unknown>;
+declare const _default: {
+    generateIconTokens: typeof generateIconTokens;
+    createStyleDictionaryConfig: typeof createStyleDictionaryConfig;
+    generateCSSVariables: typeof generateCSSVariables;
+    generateTailwindConfig: typeof generateTailwindConfig;
+    toFigmaTokens: typeof toFigmaTokens;
+    DEFAULT_SIZE_TOKENS: {
+        readonly xs: "0.75rem";
+        readonly sm: "1rem";
+        readonly md: "1.5rem";
+        readonly lg: "2rem";
+        readonly xl: "3rem";
+        readonly '2xl': "4rem";
+    };
+    DEFAULT_COLOR_TOKENS: {
+        readonly primary: "#3b82f6";
+        readonly secondary: "#64748b";
+        readonly accent: "#8b5cf6";
+        readonly success: "#22c55e";
+        readonly warning: "#f59e0b";
+        readonly error: "#ef4444";
+        readonly info: "#06b6d4";
+        readonly muted: "#9ca3af";
+    };
+    DEFAULT_STROKE_TOKENS: {
+        readonly thin: "1";
+        readonly normal: "1.5";
+        readonly medium: "2";
+        readonly thick: "2.5";
+        readonly bold: "3";
+    };
+    DEFAULT_ANIMATION_TOKENS: {
+        readonly duration: {
+            readonly instant: "0ms";
+            readonly fast: "150ms";
+            readonly normal: "300ms";
+            readonly slow: "500ms";
+            readonly slower: "1000ms";
+        };
+        readonly easing: {
+            readonly linear: "linear";
+            readonly easeIn: "cubic-bezier(0.4, 0, 1, 1)";
+            readonly easeOut: "cubic-bezier(0, 0, 0.2, 1)";
+            readonly easeInOut: "cubic-bezier(0.4, 0, 0.2, 1)";
+            readonly spring: "cubic-bezier(0.175, 0.885, 0.32, 1.275)";
+        };
+    };
+};
+export default _default;

package/dist/types/figmaSync.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @file figmaSync.ts
+ * @description Bidirectional sync between Figma design files and the codebase.
+ *
+ * - Sync changes from Figma → codebase (import new/updated icons)
+ * - Push code changes → Figma (export updated icons to Figma)
+ * - Version tracking (track which version of icon is in Figma vs code)
+ * - Conflict detection (detect when both sides changed)
+ *
+ * This module provides the data structures and logic for syncing.
+ * The actual Figma API calls are delegated to callbacks so this
+ * module can work with any Figma plugin or REST API implementation.
+ *
+ * @example
+ * ```tsx
+ * const manager = createFigmaSyncManager({
+ *   fetchFromFigma: async () => figmaIcons,
+ *   pushToFigma: async (icons) => { ... },
+ *   getLocalIcons: () => localIcons,
+ *   onConflict: (diff) => 'prefer-local',
+ * });
+ *
+ * // Pull changes from Figma
+ * const result = await manager.pull();
+ *
+ * // Push changes to Figma
+ * const pushResult = await manager.push();
+ *
+ * // Full bidirectional sync
+ * const syncResult = await manager.sync();
+ * ```
+ */
+/** Sync direction for a single icon. */
+export type FigmaSyncDirection = 'figma-to-code' | 'code-to-figma' | 'both' | 'none';
+/** Represents a tracked icon with version info. */
+export interface FigmaTrackedIcon {
+    /** Icon name (e.g. 'NtdHome') */
+    name: string;
+    /** SVG path data (d attribute) */
+    svgPaths: string[];
+    /** ViewBox */
+    viewBox: string;
+    /** Version hash (content hash for change detection) */
+    hash: string;
+    /** Last sync timestamp */
+    lastSynced?: number;
+    /** Icon variant */
+    variant?: string;
+    /** Figma node ID (if known) */
+    figmaNodeId?: string;
+    /** Category */
+    category?: string;
+}
+/** Diff between Figma and local icon. */
+export interface FigmaIconDiff {
+    /** Icon name */
+    name: string;
+    /** Change type */
+    status: 'added' | 'modified' | 'deleted' | 'conflict' | 'unchanged';
+    /** Direction of change */
+    direction: FigmaSyncDirection;
+    /** Local version (if exists) */
+    local?: FigmaTrackedIcon;
+    /** Figma version (if exists) */
+    figma?: FigmaTrackedIcon;
+    /** Previous synced hash (for conflict detection) */
+    lastSyncedHash?: string;
+}
+/** Configuration for the sync manager. */
+export interface FigmaSyncConfig {
+    /** Fetch all icons from Figma (plugin API or REST) */
+    fetchFromFigma: () => Promise<FigmaTrackedIcon[]>;
+    /** Push icons to Figma */
+    pushToFigma: (icons: FigmaTrackedIcon[]) => Promise<void>;
+    /** Get all local icons */
+    getLocalIcons: () => FigmaTrackedIcon[];
+    /** Conflict resolution strategy */
+    onConflict?: (diff: FigmaIconDiff) => 'prefer-local' | 'prefer-figma' | 'skip';
+    /** Persistent storage for sync state */
+    storage?: FigmaSyncStorage;
+}
+/** Persistent storage interface for sync metadata. */
+interface FigmaSyncStorage {
+    get: (key: string) => string | null;
+    set: (key: string, value: string) => void;
+}
+/** Result of a sync operation. */
+export interface FigmaSyncResult {
+    /** Icons pulled from Figma */
+    pulled: FigmaIconDiff[];
+    /** Icons pushed to Figma */
+    pushed: FigmaIconDiff[];
+    /** Conflicts detected */
+    conflicts: FigmaIconDiff[];
+    /** Skipped icons */
+    skipped: FigmaIconDiff[];
+    /** Total sync time in ms */
+    duration: number;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Computes a diff between two sets of tracked icons.
+ *
+ * @param localIcons - Icons in the codebase
+ * @param figmaIcons - Icons in Figma
+ * @param syncState - Previously synced hashes (for conflict detection)
+ * @returns Array of diffs
+ */
+export declare function diffIconSets(localIcons: FigmaTrackedIcon[], figmaIcons: FigmaTrackedIcon[], syncState?: Map<string, string>): FigmaIconDiff[];
+/**
+ * Creates a FigmaSyncManager for bidirectional icon synchronization.
+ */
+export declare function createFigmaSyncManager(config: FigmaSyncConfig): FigmaSyncManager;
+export declare class FigmaSyncManager {
+    private config;
+    private syncState;
+    constructor(config: FigmaSyncConfig);
+    /** Pull changes from Figma → codebase. */
+    pull(): Promise<FigmaSyncResult>;
+    /** Push changes from codebase → Figma. */
+    push(): Promise<FigmaSyncResult>;
+    /** Full bidirectional sync. */
+    sync(): Promise<FigmaSyncResult>;
+    /** Get current diff without making changes. */
+    diff(): Promise<FigmaIconDiff[]>;
+    /** Get sync history from storage. */
+    getSyncState(): Map<string, string>;
+    /** Reset sync state (forces full re-sync on next operation). */
+    resetSyncState(): void;
+    private updateSyncHash;
+    private loadSyncState;
+    private saveSyncState;
+}
+export {};