gospelo-iconcraft-react 0.2.0 → 0.3.1

package/README.md

@@ -10,6 +10,21 @@ npm install gospelo-iconcraft-react
 
 ## Quick Start
 
+### Factory Pattern (Recommended)
+
+```tsx
+import { IconCraftFactory, IconCraftView } from 'gospelo-iconcraft-react';
+
+const factory = new IconCraftFactory({ mode: 'wax', shapeColor: '#6366f1' });
+const icon = factory.create('<svg>...</svg>');
+
+function App() {
+  return <IconCraftView instance={icon} />;
+}
+```
+
+### Simple Usage
+
 ```tsx
 import { IconCraftShape } from 'gospelo-iconcraft-react';
 
@@ -26,9 +41,106 @@ function App() {
 
 ## Components
 
-### `<IconCraftShape>` (Recommended)
+### `<IconCraftView>` (Recommended)
 
-Modern component with full feature support.
+Instance-based component with rotation dial, reticle, and animation support. Works with `IconCraftFactory` / `IconCraftInstance`.
+
+```tsx
+import { IconCraftFactory, IconCraftView } from 'gospelo-iconcraft-react';
+
+const factory = new IconCraftFactory({
+  mode: 'jelly',
+  shapeColor: '#10b981',
+  size: 120,
+});
+
+const icon = factory.create('<svg>...</svg>');
+
+<IconCraftView
+  instance={icon}
+  animation="bounce"
+  showRotationDial
+  onRotationChange={(deg) => console.log(deg)}
+  dialPreset={dialPresetDotted}
+  showReticle
+  reticlePreset={reticlePresetCross}
+/>
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `instance` | `IconCraftInstance` | required | Icon instance from factory |
+| `animation` | `AnimationType \| AnimationOptions` | - | Animation preset or config |
+| `animationTarget` | `'shape' \| 'icon' \| 'both'` | `'both'` | Animation target |
+| `animateOnHover` | `boolean` | `false` | Trigger animation on hover |
+| `showRotationDial` | `boolean` | `false` | Show rotation dial overlay |
+| `onRotationChange` | `(deg: number) => void` | - | Rotation change callback |
+| `rotationSnap` | `number` | `5` | Snap angle in degrees |
+| `dialPreset` | `DialPreset` | `dialPresetDotted` | Dial visual preset |
+| `showReticle` | `boolean` | `false` | Show center reticle |
+| `reticlePreset` | `ReticlePreset` | - | Reticle visual preset |
+| `renderRing` | `(props: DialRingProps) => ReactNode` | - | Custom ring renderer |
+| `renderNotch` | `(props: DialNotchProps) => ReactNode` | - | Custom notch renderer |
+| `renderLabel` | `(props: DialLabelProps) => ReactNode` | - | Custom label renderer |
+| `renderReticle` | `(props: ReticleProps) => ReactNode` | - | Custom reticle renderer |
+| `zIndex` | `number` | - | Z-index for layering |
+| `className` | `string` | - | CSS class |
+| `style` | `CSSProperties` | - | Inline styles |
+| `onClick` | `() => void` | - | Click handler |
+
+### Dial Presets
+
+10 built-in dial presets for the rotation dial appearance:
+
+```tsx
+import { dialPresets, dialPresetDotted } from 'gospelo-iconcraft-react';
+
+// Use by name
+<IconCraftView instance={icon} showRotationDial dialPreset={dialPresets.dotted} />
+
+// Available presets
+// dialPresets.dotted   - Dotted circle ring (default)
+// dialPresets.dashed   - Dashed circle ring
+// dialPresets.solid    - Solid circle ring
+// dialPresets.ticks    - Tick marks around the ring
+// dialPresets.double   - Double circle ring
+// dialPresets.crosshair - Crosshair style
+// dialPresets.minimal  - Minimal style
+// dialPresets.needle   - Needle indicator
+// dialPresets.bar      - Bar indicator
+// dialPresets.arrow    - Arrow indicator
+```
+
+### Reticle Presets
+
+3 built-in reticle presets for center overlay:
+
+```tsx
+import { reticlePresets, reticlePresetCross } from 'gospelo-iconcraft-react';
+
+<IconCraftView instance={icon} showReticle reticlePreset={reticlePresets.cross} />
+
+// Available presets
+// reticlePresets.cross    - Crosshair reticle
+// reticlePresets.bullseye - Bullseye target reticle
+// reticlePresets.globe    - Globe/sphere reticle
+```
+
+### CSS Variables
+
+The dial and reticle color can be customized via CSS variable:
+
+```css
+:root {
+  --iconcraft-dial-color: #0071e3; /* default */
+}
+```
+
+### `<IconCraftShape>`
+
+Standalone component with full feature support (no factory needed).
 
 ```tsx
 import { IconCraftShape } from 'gospelo-iconcraft-react';
@@ -58,6 +170,7 @@ import { IconCraftShape } from 'gospelo-iconcraft-react';
 | `height` | `number \| string` | - | Height |
 | `shadow` | `boolean` | `true` | Show drop shadow |
 | `highlight` | `boolean` | `true` | Show highlight effect |
+| `rotation` | `number` | `0` | Icon rotation in degrees (0-360). Shape follows rotated icon. |
 | `animation` | `AnimationType \| AnimationOptions` | - | Animation preset or config |
 | `animateOnHover` | `boolean` | `false` | Trigger animation on hover |
 | `offset` | `number` | `20` | Contour offset |
@@ -69,18 +182,26 @@ import { IconCraftShape } from 'gospelo-iconcraft-react';
 | `onError` | `(error) => void` | - | Called on error |
 | `onClick` | `() => void` | - | Click handler |
 
-### `<IconCraft>` (Legacy)
+## Factory Pattern
 
-Original component for backwards compatibility.
+`IconCraftFactory` creates reusable `IconCraftInstance` objects with shared configuration:
 
 ```tsx
-import { IconCraft } from 'gospelo-iconcraft-react';
+import { IconCraftFactory } from 'gospelo-iconcraft-react';
 
-<IconCraft
-  svgContent="<svg>...</svg>"
-  mode="wax"
-  baseColor="#6366f1"
-/>
+const factory = new IconCraftFactory({
+  mode: 'wax',
+  shapeColor: '#6366f1',
+  iconStyle: 'emboss',
+  size: 100,
+});
+
+// Create multiple icons with same config
+const icon1 = factory.create('<svg>...</svg>');
+const icon2 = factory.create('<svg>...</svg>');
+
+// Update config after creation
+icon1.config.update({ shapeColor: '#10b981', rotation: 45 });
 ```
 
 ## Shape Modes
@@ -243,6 +364,15 @@ import type {
   AnimationOptions,
   IconCraftResult,
   IconCraftShapeProps,
+  IconCraftViewProps,
+  DialPreset,
+  DialPresetName,
+  ReticlePreset,
+  ReticlePresetName,
+  DialRingProps,
+  DialNotchProps,
+  DialLabelProps,
+  ReticleProps,
 } from 'gospelo-iconcraft-react';
 ```
 

package/dist/index.d.ts

@@ -88,6 +88,7 @@ interface IconCraftResult {
     svg_paths: SvgPaths | null;
     emboss_svg: string | null;
     icon_paths: EmbossIconData | null;
+    rotation: number;
 }
 interface IconCraftShapeProps {
     /** SVG content string or URL */
@@ -104,6 +105,8 @@ interface IconCraftShapeProps {
     shadow?: boolean;
     /** Show highlight effect */
     highlight?: boolean;
+    /** Icon rotation in degrees (0-360). Applied at WASM level so shape follows rotated icon. */
+    rotation?: number;
     /** Contour offset (default: 20) */
     offset?: number;
     /** Rasterization resolution (default: 256) */
@@ -157,6 +160,7 @@ interface IconCraftConfigOptions {
     offset?: number;
     resolution?: number;
     simplify?: number;
+    rotation?: number;
     size?: number | string;
     width?: number | string;
     height?: number | string;
@@ -182,6 +186,7 @@ declare class IconCraftConfig {
     readonly offset: number;
     readonly resolution: number;
     readonly simplify: number;
+    readonly rotation: number;
     readonly size: number | string;
     readonly width?: number | string;
     readonly height?: number | string;
@@ -202,6 +207,7 @@ declare class IconCraftConfig {
         simplify: number;
         includeIcon: boolean;
         shapeColor: string;
+        rotation: number;
     };
     /**
      * スタイル用のサイズを取得
@@ -328,6 +334,7 @@ interface WasmGenerateParams {
     simplify: number;
     includeIcon: boolean;
     shapeColor: string;
+    rotation?: number;
 }
 /**
  * WASMマネージャー（Singleton）
@@ -446,6 +453,70 @@ declare class IconCraftRegistry {
  */
 declare const globalRegistry: IconCraftRegistry;
 
+/**
+ * Dial preset definition
+ */
+interface DialPreset {
+    name: string;
+    renderRing: (props: DialRingProps) => React.ReactNode;
+    renderNotch: (props: DialNotchProps) => React.ReactNode;
+    renderLabel?: (props: DialLabelProps) => React.ReactNode;
+}
+/** Default: dashed ring with circle notch */
+declare const dialPresetDashed: DialPreset;
+/** Solid thin ring with diamond notch */
+declare const dialPresetSolid: DialPreset;
+/** Tick marks ring with arrow notch */
+declare const dialPresetTicks: DialPreset;
+/** Dotted ring with square notch */
+declare const dialPresetDotted: DialPreset;
+/** Double ring with pill-shaped notch */
+declare const dialPresetDouble: DialPreset;
+/** Crosshair style with + shaped notch */
+declare const dialPresetCrosshair: DialPreset;
+/** Minimal: only quarter arcs with triangle notch */
+declare const dialPresetMinimal: DialPreset;
+/** Needle: dashed ring with elongated needle notch */
+declare const dialPresetNeedle: DialPreset;
+/** Bar: solid ring with rounded bar notch */
+declare const dialPresetBar: DialPreset;
+/** Arrow: tick ring with arrow-head notch */
+declare const dialPresetArrow: DialPreset;
+/** All presets for easy iteration */
+declare const dialPresets: {
+    readonly dotted: DialPreset;
+    readonly dashed: DialPreset;
+    readonly solid: DialPreset;
+    readonly ticks: DialPreset;
+    readonly double: DialPreset;
+    readonly crosshair: DialPreset;
+    readonly minimal: DialPreset;
+    readonly needle: DialPreset;
+    readonly bar: DialPreset;
+    readonly arrow: DialPreset;
+};
+type DialPresetName = keyof typeof dialPresets;
+/**
+ * Reticle preset definition
+ */
+interface ReticlePreset {
+    name: string;
+    render: (props: ReticleProps) => React.ReactNode;
+}
+/** Cross: back=bottom+right arms, front=top+left arms + center dot */
+declare const reticlePresetCross: ReticlePreset;
+/** Bullseye: circle + center dot */
+declare const reticlePresetBullseye: ReticlePreset;
+/** Globe: wireframe sphere — all lines split into back (far side) and front (near side) */
+declare const reticlePresetGlobe: ReticlePreset;
+/** All reticle presets */
+declare const reticlePresets: {
+    readonly cross: ReticlePreset;
+    readonly bullseye: ReticlePreset;
+    readonly globe: ReticlePreset;
+};
+type ReticlePresetName = keyof typeof reticlePresets;
+
 interface IconCraftViewProps {
     /** IconCraftInstance */
     instance: IconCraftInstance;
@@ -472,6 +543,54 @@ interface IconCraftViewProps {
     onLoad?: () => void;
     /** Error callback */
     onError?: (error: string) => void;
+    /** Show rotation dial overlay */
+    showRotationDial?: boolean;
+    /** Rotation change callback (called on mouseup with final degree) */
+    onRotationChange?: (deg: number) => void;
+    /** Snap angle in degrees (default: 5) */
+    rotationSnap?: number;
+    /** Custom ring SVG renderer */
+    renderRing?: (props: DialRingProps) => React.ReactNode;
+    /** Custom notch SVG renderer */
+    renderNotch?: (props: DialNotchProps) => React.ReactNode;
+    /** Custom label SVG renderer */
+    renderLabel?: (props: DialLabelProps) => React.ReactNode;
+    /** Dial preset object (overrides renderRing/renderNotch/renderLabel) */
+    dialPreset?: DialPreset;
+    /** Show center reticle */
+    showReticle?: boolean;
+    /** Custom reticle SVG renderer */
+    renderReticle?: (props: ReticleProps) => React.ReactNode;
+    /** Reticle preset object (overrides renderReticle) */
+    reticlePreset?: ReticlePreset;
+}
+/** Props passed to custom reticle renderer */
+interface ReticleProps {
+    cx: number;
+    cy: number;
+    size: number;
+    /** Which layer is being rendered: 'back' (behind icon) or 'front' (above icon) */
+    layer: 'back' | 'front';
+}
+/** Props passed to custom ring renderer */
+interface DialRingProps {
+    cx: number;
+    cy: number;
+    radius: number;
+}
+/** Props passed to custom notch renderer */
+interface DialNotchProps {
+    x: number;
+    y: number;
+    /** Current angle in degrees (0 = top) */
+    degrees: number;
+    onMouseDown: (e: React.MouseEvent) => void;
+}
+/** Props passed to custom label renderer */
+interface DialLabelProps {
+    x: number;
+    y: number;
+    degrees: number;
 }
 /**
  * IconCraftView - インスタンスからSVGを表示するコンポーネント
@@ -484,7 +603,7 @@ interface IconCraftViewProps {
  * <IconCraftView instance={icon} zIndex={10} />
  * ```
  */
-declare function IconCraftView({ instance, animation, animationTarget, animateOnHover, zIndex, className, style, onClick, onLoad, onError, }: IconCraftViewProps): react_jsx_runtime.JSX.Element | null;
+declare function IconCraftView({ instance, animation, animationTarget, animateOnHover, zIndex, className, style, onClick, onLoad, onError, showRotationDial, onRotationChange, rotationSnap, renderRing: renderRingProp, renderNotch: renderNotchProp, renderLabel: renderLabelProp, dialPreset, showReticle, renderReticle: renderReticleProp, reticlePreset, }: IconCraftViewProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * IconCraftSimple Props
@@ -570,7 +689,7 @@ declare function IconCraftSimple({ src, mode, iconStyle, iconColor, shapeColor,
  * />
  * ```
  */
-declare function IconCraftShape({ svg, mode, shapeColor, iconStyle, shadow: _shadow, highlight: _highlight, offset, resolution, simplify, width, height, size, animation, animateOnHover, className, style, onLoad, onError, onClick, }: IconCraftShapeProps): react_jsx_runtime.JSX.Element | null;
+declare function IconCraftShape({ svg, mode, shapeColor, iconStyle, shadow: _shadow, highlight: _highlight, offset, resolution, simplify, rotation, width, height, size, animation, animateOnHover, className, style, onLoad, onError, onClick, }: IconCraftShapeProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * Legacy IconCraft component
@@ -859,6 +978,8 @@ interface UseIconCraftOptions {
     resolution?: number;
     /** Polygon simplification epsilon */
     simplify?: number;
+    /** Icon rotation in degrees (0-360) */
+    rotation?: number;
     /** Auto-generate on mount/change */
     autoGenerate?: boolean;
 }
@@ -1033,6 +1154,8 @@ interface IconBackupData {
     zIndex?: number;
     /** アイコンの色（オプション） */
     iconColor?: string;
+    /** 回転角度（オプション） */
+    rotation?: number;
     /** アニメーション（オプション） */
     animation?: AnimationType;
     /** カスタムメタデータ（オプション） */
@@ -1108,4 +1231,4 @@ declare function parseBackup(json: string): IconCraftBackup | null;
  */
 declare function loadBackupFromFile(file: File): Promise<IconCraftBackup | null>;
 
-export { type AnimationOptions, type AnimationTarget, type AnimationType, BACKUP_VERSION, type BackupValidationResult, type BuiltInAnimationType, type ColorPalette, type CreateBackupOptions, type CustomAnimationDefinition, type CustomAnimationRegistry, DEFAULT_CONFIG, DEFAULT_METADATA, type EmbossIconData, type EmbossPath, type IconBackupData, IconCraft, type IconCraftBackup, IconCraftConfig, type IconCraftConfigOptions, type IconCraftContextValue, type IconCraftDispatcher, type IconCraftEvent, type IconCraftEventFilter, type IconCraftEventHandler, type IconCraftEventType, IconCraftFactory, IconCraftInstance, type IconCraftMetadata, type IconCraftProps, IconCraftProvider, type IconCraftProviderProps, IconCraftRegistry, type IconCraftResult, IconCraftShape, type IconCraftShapeProps, IconCraftSimple, type IconCraftSimpleProps, type IconCraftStoreActions, type IconCraftStoreState, IconCraftView, type IconCraftViewProps, type IconLayout, type IconStyle, type ShapeMode, type SvgPaths, type TransformOriginCustom, type TransformOriginPreset, type TransformOriginValue, type UseIconCraftCreateOptions, type UseIconCraftReturn$1 as UseIconCraftInstanceReturn, type UseIconCraftOptions, type UseIconCraftReturn, type UseIconCraftSelectionReturn, type WasmGenerateParams, WasmManager, animationDefaults, createBackup, createDispatcher, defaultFactory, downloadBackup, exportBackup, generateIconId, getAnimationDefaults, getAnimationName, getAnimationStyle, getCustomAnimation, getKeyframes, getTimestampFromId, getTransformOrigin, globalRegistry, injectKeyframes, keyframes, loadBackupFromFile, parseAnimationOptions, parseBackup, registerAnimation, useIconCraft, useIconCraftContext, useIconCraftCreate, useIconCraftEvent, useIconCraft$1 as useIconCraftInstance, useIconCraftSelection, useIconCraftStore, useLegacyIconCraft, validateBackup };
+export { type AnimationOptions, type AnimationTarget, type AnimationType, BACKUP_VERSION, type BackupValidationResult, type BuiltInAnimationType, type ColorPalette, type CreateBackupOptions, type CustomAnimationDefinition, type CustomAnimationRegistry, DEFAULT_CONFIG, DEFAULT_METADATA, type DialLabelProps, type DialNotchProps, type DialPreset, type DialPresetName, type DialRingProps, type EmbossIconData, type EmbossPath, type IconBackupData, IconCraft, type IconCraftBackup, IconCraftConfig, type IconCraftConfigOptions, type IconCraftContextValue, type IconCraftDispatcher, type IconCraftEvent, type IconCraftEventFilter, type IconCraftEventHandler, type IconCraftEventType, IconCraftFactory, IconCraftInstance, type IconCraftMetadata, type IconCraftProps, IconCraftProvider, type IconCraftProviderProps, IconCraftRegistry, type IconCraftResult, IconCraftShape, type IconCraftShapeProps, IconCraftSimple, type IconCraftSimpleProps, type IconCraftStoreActions, type IconCraftStoreState, IconCraftView, type IconCraftViewProps, type IconLayout, type IconStyle, type ReticlePreset, type ReticlePresetName, type ReticleProps, type ShapeMode, type SvgPaths, type TransformOriginCustom, type TransformOriginPreset, type TransformOriginValue, type UseIconCraftCreateOptions, type UseIconCraftReturn$1 as UseIconCraftInstanceReturn, type UseIconCraftOptions, type UseIconCraftReturn, type UseIconCraftSelectionReturn, type WasmGenerateParams, WasmManager, animationDefaults, createBackup, createDispatcher, defaultFactory, dialPresetArrow, dialPresetBar, dialPresetCrosshair, dialPresetDashed, dialPresetDotted, dialPresetDouble, dialPresetMinimal, dialPresetNeedle, dialPresetSolid, dialPresetTicks, dialPresets, downloadBackup, exportBackup, generateIconId, getAnimationDefaults, getAnimationName, getAnimationStyle, getCustomAnimation, getKeyframes, getTimestampFromId, getTransformOrigin, globalRegistry, injectKeyframes, keyframes, loadBackupFromFile, parseAnimationOptions, parseBackup, registerAnimation, reticlePresetBullseye, reticlePresetCross, reticlePresetGlobe, reticlePresets, useIconCraft, useIconCraftContext, useIconCraftCreate, useIconCraftEvent, useIconCraft$1 as useIconCraftInstance, useIconCraftSelection, useIconCraftStore, useLegacyIconCraft, validateBackup };