@nice2dev/icons 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,4 +1,37 @@
-# Changelog
+# @nice2dev/icons — Changelog
+
+All notable changes to the icon library.
+
+## [1.0.1] — 2026-03-25
+
+### Added (FAZA 1.4)
+
+- **Decorative icon styles** — 6 icon wrapper components with SVG/CSS animations:
+  - `NtdIconFloral` 🌸 — botanical vines, leaves, flowers with draw + bloom animation
+  - `NtdIconFestive` 🎉 — confetti, stars, sparkles with burst-from-center + twinkle
+  - `NtdIconNeon` 💡 — multi-layer glow (CSS drop-shadow) with neon flicker
+  - `NtdIconSketch` ✏️ — hand-drawn effect (SVG feTurbulence) with scribble overlay
+  - `NtdIconWatercolor` 🎨 — soft paint blobs with aquarelle effect
+  - `NtdIconCosmic` ✨ — stars, nebula, constellation lines with slow rotation
+  - `NtdIconSteampunk` ⚙️ — gears, pipes, rivets with rotation + steam
+  - `NtdIconFrost` ❄️ — ice crystals, snowflakes, glow halo
+  - `NtdIconPixel` 👾 — pixel brackets, scanline sweep, glitch displacement
+  - `NtdIconOrganic` 🧀 — cell membranes, floating bubbles
+  - `NtdIconGeometric` 🔷 — rotating rings, diamond corners
+- Each supports `animate`, `duration`, `intensity` (subtle/normal/dense), custom colors
+- Storybook stories with interactive controls
+
+---
+
+## [1.0.0] — 2025-06-01
+
+Initial production release.
+
+- 300+ multi-color SVG icons across 28 categories
+- 4 size variants (16/20/24/32)
+- 65+ icon animations
+- `NiceIconPicker` component
+- Automatic icon sprite generation
 
 All notable changes to `@nice2dev/icons` will be documented in this file.
 
@@ -113,12 +146,141 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.1.0] - 2026-03-19
+
+### Added
+
+#### New Icon Categories (~420 total icons)
+- **Sustainability & Eco Icons** (15 icons in `sustainability.tsx`):
+  - Recycling: `NtdRecycle`, `NtdCompost`, `NtdTrashSort`
+  - Renewable Energy: `NtdSolarPanel`, `NtdWindTurbine`, `NtdEvCharger`, `NtdHydropower`
+  - Carbon & Climate: `NtdCarbonFootprint`, `NtdCo2`, `NtdNetZero`
+  - Eco Labels: `NtdEcoFriendly`, `NtdOrganic`, `NtdBiodegradable`
+  - Nature: `NtdPlantTree`, `NtdWildlife`
+
+- **Accessibility Icons** (13 icons in `accessibility.tsx`):
+  - Universal: `NtdAccessibility`, `NtdWheelchair`, `NtdBlind`
+  - Sensory: `NtdDeaf`, `NtdSignLanguage`, `NtdBraille`, `NtdAudioDescription`, `NtdClosedCaptions`
+  - Cognitive: `NtdDyslexia`, `NtdEasyRead`
+  - Assistive Tech: `NtdScreenReader`, `NtdHearingAid`, `NtdAssistiveTech`
+
+- **Legal & Compliance Icons** (13 icons in `legal.tsx`):
+  - Documents: `NtdContract`, `NtdLegalDocument`, `NtdTermsOfService`
+  - Privacy: `NtdPrivacyPolicy`, `NtdGdpr`, `NtdCcpa`, `NtdCookieConsent`
+  - IP: `NtdCopyright`, `NtdTrademark`, `NtdPatent`
+  - Compliance: `NtdCompliance`, `NtdCertified`, `NtdAudit`
+
+#### Exports
+- Grouped exports: `sustainabilityIcons`, `accessibilityIcons`, `legalIcons`
+
+---
+
+## [1.2.0] - 2026-03-20
+
+### Added
+
+#### FAZA 4 — Developer Experience
+
+- **TypeScript Autocomplete Enhancement** (`src/variantProps.ts`):
+  - Discriminated union type `VariantIconProps` with per-variant narrowing
+  - 8 strict prop types: `SolidIconProps`, `OutlineIconProps`, `DuotoneIconProps`, `FlatIconProps`, `SharpIconProps`, `RoundedIconProps`, `MiniIconProps`, `ThreeDIconProps`
+  - Type guard functions: `isSolidProps()`, `isOutlineProps()`, `isDuotoneProps()`, `isFlatProps()`, `isSharpProps()`, `isRoundedProps()`, `isMiniProps()`, `isThreeDProps()`
+  - `toIconProps()` — safe cast from discriminated union to `NtdIconProps`
+
+- **Tree-shaking Audit & Report** (`scripts/tree-shaking-audit.mjs`):
+  - Circular dependency detection with graph traversal
+  - Per-icon ESM bundle size analysis
+  - Verbose mode with detailed breakdown
+  - JSON report output (`--output reports/treeshaking-report.json`)
+  - npm scripts: `audit:treeshaking`, `audit:treeshaking:verbose`
+
+- **Icon Usage Analytics** (`src/iconAnalytics.tsx`):
+  - `createIconAnalyticsProvider()` — React context factory for usage tracking
+  - `useIconAnalytics()` — hook for tracking icon renders
+  - `IconAnalyticsDashboard` — built-in dashboard with top icons, usage stats, recommendations
+  - `IconAnalyticsReport` type with most-used, least-used, unused icon lists
+  - Optional per-icon `location` tracking
+
+#### FAZA 5 — Advanced Animations
+
+- **Path Morphing Animations** (`src/NtdStateMorph.tsx`):
+  - `<NtdStateMorph>` — stateful SVG morphing between named states (e.g. empty → filled)
+  - `MorphStateMap` — declarative state → path mapping
+  - `useStateMorph()` hook for programmatic control
+  - `StateMorphHandle` ref API (play, reverse, goTo)
+  - Configurable easing, duration, liquid/fluid transitions
+
+- **Lottie Integration** (`src/lottieIntegration.tsx`):
+  - `<NtdLottieIcon>` — render Lottie JSON animations as icon-sized components
+  - `lottieToIcon()` — convert Lottie animation data to an `NtdIcon`-compatible component
+  - `exportToLottie()` — export SVG icon with animation to Lottie JSON format
+  - `LottieAnimationData`, `LottieExportOptions` types
+
+- **Particle Effects** (`src/particleEffects.tsx`):
+  - `<NtdParticleIcon>` — canvas-based particle effects triggered by icon events
+  - Built-in presets: `confetti`, `sparkles`, `smoke`, `dust`
+  - `ParticleConfig` for custom effect tuning (count, velocity, gravity, colors, lifetime)
+  - Trigger modes: `click`, `hover`, `mount`, `manual`
+
+#### FAZA 6 — Integrations
+
+- **Figma Bidirectional Sync** (`src/figmaSync.ts`):
+  - `FigmaSyncManager` class for two-way Figma ↔ codebase sync
+  - `createFigmaSyncManager()` factory with `FigmaSyncConfig`
+  - `diffIconSets()` — detect added/removed/modified icons between Figma and codebase
+  - `FigmaIconDiff` type with change tracking
+  - `FigmaSyncDirection`: `push` (code → Figma), `pull` (Figma → code), `both`
+  - Version tracking and conflict detection
+
+#### Infrastructure
+
+- **Visual Regression Testing** (Chromatic):
+  - `chromatic.config.json` with auto-accept on main, onlyChanged optimization
+  - npm scripts: `test:visual`, `test:visual:ci`
+  - Azure DevOps pipeline integration (`chromatic` step in Build stage)
+
+- **Changelog Generation** (conventional-changelog):
+  - `conventional-changelog-cli` + `conventional-changelog-angular` configured
+  - npm scripts: `changelog` (incremental), `changelog:first` (full), `version` (auto-update on version bump)
+
+- **Auto-publish to npm** (Azure DevOps):
+  - Already handled by existing pipeline — publishes all changed `@nice2dev/*` packages on merge to main
+  - Change detection per-package via git diff
+
+---
+
+## [1.3.0] - 2026-06-16
+
+### Added
+
+#### New Components
+- `NtdIconBadge` — icon with notification/count badge overlay
+- `NtdIconMorph` — icon-to-icon morphing transition component
+
+#### Framework Integration
+- `headless-ui.tsx` — headless (unstyled) icon component for custom styling
+- `client.tsx` — client-side icon component with hydration support
+- `rsc.tsx` — React Server Component compatible icon
+- `tailwind-plugin.ts` — Tailwind CSS plugin for icon utilities (`icon-sm`, `icon-lg`, etc.)
+
+#### Design System
+- `design-tokens.ts` — design token definitions for icon sizing, spacing, and colors
+- `resolver.ts` — icon resolver for dynamic icon loading by name
+- `utilities.tsx` — icon utility components and helpers
+- `micro-interactions.tsx` — micro-interaction presets for icon hover/click feedback
+
+#### New Icon Categories
+- `ai.tsx` — AI/ML icons (neural network, brain, robot, etc.)
+- `brand.tsx` — brand/logo icons
+- `education.tsx` — education icons (graduation, book, school, etc.)
+- `fun.tsx` — fun/entertainment icons
+- `gaming.tsx` — gaming icons (controller, dice, trophy, etc.)
+- `realestate.tsx` — real estate icons (house, building, key, etc.)
+- `science.tsx` — science icons (microscope, atom, flask, etc.)
+
+---
+
 ## [Unreleased]
 
 ### Planned
-- Figma / Sketch export plugin
-- PNG sprite-sheet generation
-- Icon font generation (TTF/WOFF2)
-- Rollup plugin for tree-shaking analysis
-- CDN standalone build
-- Visual regression testing (Chromatic/Percy)
+- Visual regression baseline capture (requires `CHROMATIC_PROJECT_TOKEN` in Azure DevOps)

package/README.md

@@ -574,8 +574,253 @@ Entry points in `package.json`:
 - `types` → `dist/types/index.d.ts`
 
 ---
+## React Server Components (RSC)
 
-## License
+Use icons in Server Components without "use client":
+
+```tsx
+// In a Server Component (app/page.tsx)
+import { createIconRSC } from '@nice2dev/icons/rsc';
+
+// Create RSC-compatible icon
+const HomeIcon = createIconRSC({
+  displayName: 'HomeIcon',
+  paths: { /* ... */ }
+});
+
+export default function Page() {
+  return <HomeIcon size="md" primaryColor="#3b82f6" />;
+}
+```
+
+### RSC vs Client Exports
+
+| Import Path | Use Case |
+|-------------|----------|
+| `@nice2dev/icons` | Standard usage (includes animations, color scheme detection) |
+| `@nice2dev/icons/rsc` | Server Components (no hooks, streaming-friendly) |
+| `@nice2dev/icons/client` | Client-only features ("use client" directive) |
+
+### RSC Utilities
+
+```tsx
+import { renderIconToString, isRSCIcon, wrapAsRSC } from '@nice2dev/icons/rsc';
+
+// Render to SVG string (for SSR/email)
+const svgString = renderIconToString(MyIcon, { size: 'lg' });
+
+// Check if icon is RSC-compatible
+isRSCIcon(MyIcon); // true/false
+
+// Wrap existing icon for RSC
+const MyIconRSC = wrapAsRSC(MyIcon);
+```
+
+---
+
+## Design Tokens
+
+Generate Style Dictionary compatible design tokens for your design system:
+
+```tsx
+import {
+  generateIconTokens,
+  generateCSSVariables,
+  generateTailwindConfig,
+  toFigmaTokens,
+} from '@nice2dev/icons/design-tokens';
+
+// Generate tokens with custom configuration
+const tokens = generateIconTokens({
+  prefix: 'myapp',
+  namespace: 'icon',
+  colorTokens: {
+    primary: '#6366f1',
+    secondary: '#a5b4fc',
+  },
+  sizeTokens: {
+    sm: '14px',
+    md: '20px',
+    lg: '28px',
+  },
+});
+
+// Generate CSS variables
+const css = generateCSSVariables(tokens);
+// :root {
+//   --myapp-icon-size-sm: 14px;
+//   --myapp-icon-color-primary: #6366f1;
+//   ...
+// }
+
+// Generate Tailwind config
+const tailwindConfig = generateTailwindConfig(tokens);
+
+// Export for Figma Tokens plugin
+const figmaTokens = toFigmaTokens(tokens);
+```
+
+### Default Token Values
+
+| Category | Tokens |
+|----------|--------|
+| Sizes | `xs` (12px), `sm` (16px), `md` (24px), `lg` (32px), `xl` (48px), `2xl` (64px) |
+| Colors | `primary`, `secondary`, `accent`, `success`, `warning`, `error`, `info`, `muted` |
+| Strokes | `thin` (1), `normal` (1.5), `medium` (2), `thick` (2.5), `bold` (3) |
+
+---
+
+## Headless UI / shadcn/ui Integration
+
+Seamless integration with Radix UI, Headless UI, and shadcn/ui:
+
+```tsx
+import { NtdSettings, NtdChevronDown } from '@nice2dev/icons';
+import {
+  forwardRefIcon,
+  createRadixIcon,
+  withRadixState,
+  shadcnIconClasses,
+} from '@nice2dev/icons/headless-ui';
+
+// Create ref-compatible icon for Radix asChild pattern
+const SettingsIcon = forwardRefIcon(NtdSettings);
+
+// Icon with Radix-compatible defaults
+const SearchIcon = createRadixIcon(NtdSearch, {
+  className: 'text-muted-foreground',
+});
+
+// State-aware icon (rotates on data-state="open")
+const ChevronIcon = withRadixState(NtdChevronDown);
+
+// Use with shadcn/ui Button
+<Button>
+  <SettingsIcon className={shadcnIconClasses.buttonLeft} />
+  Settings
+</Button>
+```
+
+### shadcn/ui Class Presets
 
-MIT © NiceToDev
+```ts
+shadcnIconClasses = {
+  button: 'h-4 w-4',
+  buttonLeft: 'mr-2 h-4 w-4',
+  buttonRight: 'ml-2 h-4 w-4',
+  sm: 'h-3.5 w-3.5',
+  lg: 'h-5 w-5',
+  iconOnly: 'h-4 w-4',
+  nav: 'h-4 w-4 shrink-0',
+  dropdown: 'mr-2 h-4 w-4',
+  spinner: 'h-4 w-4 animate-spin',
+  // ...
+}
+```
+
+### Dynamic Class Generation
+
+```tsx
+import { getIconClassName } from '@nice2dev/icons/headless-ui';
+
+getIconClassName({ size: 'lg', variant: 'muted' });
+// → 'h-5 w-5 text-muted-foreground'
+
+getIconClassName({ interactive: true, spinning: true });
+// → 'h-4 w-4 transition-colors hover:text-foreground cursor-pointer animate-spin'
+```
+
+---
+
+## Utilities & Hooks
+
+Powerful utilities for advanced icon management:
+
+```tsx
+import {
+  useIcon,
+  useReducedMotion,
+  preloadIcons,
+  registerIcon,
+  getIconFromRegistry,
+  withReducedMotionProps,
+  createAccessibleIconProps,
+  isIconComponent,
+  isValidIconName,
+  useBatchIcons
+} from '@nice2dev/icons/utilities';
+
+// Dynamic icon loading with suspense support
+function DynamicIcon({ name }: { name: string }) {
+  const { icon: Icon, loading, error } = useIcon(name);
+  
+  if (loading) return <span>Loading...</span>;
+  if (error) return <span>Icon not found</span>;
+  if (!Icon) return null;
+  
+  return <Icon className="w-6 h-6" />;
+}
+
+// Respect user's reduced motion preference
+function AnimatedIcon() {
+  const prefersReducedMotion = useReducedMotion();
+  
+  return (
+    <NtdSpinner 
+      className={prefersReducedMotion ? '' : 'animate-spin'} 
+    />
+  );
+}
+
+// Preload icons for better performance
+useEffect(() => {
+  preloadIcons(['NtdHome', 'NtdUser', 'NtdSettings']);
+}, []);
+
+// Icon registry for custom icons
+registerIcon('MyCustomIcon', MyCustomIconComponent);
+const CustomIcon = getIconFromRegistry('MyCustomIcon');
+
+// Accessibility helpers
+const a11yProps = createAccessibleIconProps('Search', true);
+// → { role: 'img', 'aria-label': 'Search' }
+
+// Type guards
+if (isIconComponent(SomeComponent)) {
+  // TypeScript knows it's an icon
+}
+
+// Batch loading multiple icons
+const { icons, loading, errors } = useBatchIcons(['NtdHome', 'NtdUser']);
+```
+
+---
+
+## CLI Tool
+
+Preview, list, search and export icons from the command line:
+
+```bash
+# Preview icon in browser
+npx @nice2dev/icons preview NtdHome
+
+# List all icons
+npx @nice2dev/icons list
+
+# List icons in a category
+npx @nice2dev/icons list --category=ui
+
+# Search icons
+npx @nice2dev/icons search "arrow"
+
+# Export icons
+npx @nice2dev/icons export --format=svg --icons=NtdHome,NtdUser
+
+# Show icon info
+npx @nice2dev/icons info NtdHeart
+```
+
+---
+## License
 
+MIT © NiceToDev