@vegastack/design 0.3.2 → 0.4.0

package/dist/create-animated-icon.d.cts

@@ -0,0 +1,210 @@
+import * as motion_react from 'motion/react';
+import { motion, Variants, Transition, useAnimation } from 'motion/react';
+import * as React from 'react';
+
+/**
+ * Motion's imperative controls. `motion` does not export a public name for this
+ * type (`LegacyAnimationControls` lives in `motion-dom` and is not re-exported),
+ * so it is derived from the hook that produces it.
+ */
+type AnimatedIconControls = ReturnType<typeof useAnimation>;
+/** A variant label or an explicit target — whatever `controls.start()` accepts. */
+type AnimatedIconDefinition = Parameters<AnimatedIconControls["start"]>[0];
+/** The per-call transition override `controls.start()` accepts as its 2nd argument. */
+type AnimatedIconTransition = Parameters<AnimatedIconControls["start"]>[1];
+/**
+ * Motion's own prop types, taken from a Motion element rather than restated, so
+ * a spec can never declare something Motion would reject. (`initial` is
+ * deliberately narrower than a start() definition: it takes no variant resolver.)
+ */
+type MotionElementProps = React.ComponentProps<typeof motion.svg>;
+type AnimatedIconInitial = MotionElementProps["initial"];
+type AnimatedIconTarget = MotionElementProps["animate"];
+type AnimatedIconExit = MotionElementProps["exit"];
+/**
+ * The root renders as either `svg` or `motion.svg`, so a style must satisfy
+ * both: plain CSS plus Motion's transform-origin shorthands.
+ */
+type AnimatedIconStyle = React.CSSProperties & NonNullable<MotionElementProps["style"]>;
+/**
+ * The imperative handle every animated icon exposes on its ref — drive the
+ * animation programmatically instead of (or in addition to) hover/focus.
+ */
+interface AnimatedIconHandle {
+    startAnimation: () => void;
+    stopAnimation: () => void;
+}
+/**
+ * The choreography context handed to a spec's `start`/`stop`. Every timing
+ * primitive an icon may need is here, so an icon module never touches React.
+ */
+interface AnimatedIconChoreography {
+    /**
+     * Look up a control group by name; no argument gives the primary group. A
+     * function rather than a record so a group is never `possibly undefined` at
+     * the call site — the factory creates exactly the groups the spec declares.
+     */
+    control: (group?: string) => AnimatedIconControls;
+    /**
+     * The live `(prefers-reduced-motion: reduce)` preference, with an explicit
+     * `<MotionConfig reducedMotion>` override applied.
+     */
+    shouldReduceMotion: boolean;
+    /**
+     * Play a definition. A no-op that also halts the control when reduced motion
+     * is requested. Never rejects — an interrupted animation resolves.
+     */
+    run: (control: AnimatedIconControls, definition: AnimatedIconDefinition, transition?: AnimatedIconTransition) => Promise<void>;
+    /**
+     * Return to a resting definition. Under reduced motion the target is applied
+     * instantly instead of being animated to.
+     */
+    reset: (control: AnimatedIconControls, definition: AnimatedIconDefinition, transition?: AnimatedIconTransition) => Promise<void>;
+    /** Halt a control and snap it to a definition, with no animation, ever. */
+    set: (control: AnimatedIconControls, definition: AnimatedIconDefinition) => void;
+    /**
+     * Schedule deferred work. Every pending task is cancelled when the animation
+     * stops and when the icon unmounts, so an icon never leaks a timer.
+     */
+    after: (delayMs: number, task: () => void) => void;
+    /**
+     * Per-instance scratch for choreography that needs to remember something
+     * between calls — a re-entrancy latch, say. Persists for the icon's lifetime.
+     */
+    flags: Record<string, unknown>;
+}
+/** Every SVG element an icon may draw, plus its Motion counterpart. */
+declare const TAGS: {
+    readonly circle: "circle";
+    readonly defs: "defs";
+    readonly ellipse: "ellipse";
+    readonly g: "g";
+    readonly line: "line";
+    readonly path: "path";
+    readonly pattern: "pattern";
+    readonly polygon: "polygon";
+    readonly polyline: "polyline";
+    readonly rect: "rect";
+    readonly text: "text";
+    readonly "motion.circle": motion_react.ForwardRefComponent<SVGCircleElement, motion_react.SVGMotionProps<SVGCircleElement>>;
+    readonly "motion.ellipse": motion_react.ForwardRefComponent<SVGEllipseElement, motion_react.SVGMotionProps<SVGEllipseElement>>;
+    readonly "motion.g": motion_react.ForwardRefComponent<SVGGElement, motion_react.SVGMotionProps<SVGGElement>>;
+    readonly "motion.line": motion_react.ForwardRefComponent<SVGLineElement, motion_react.SVGMotionProps<SVGLineElement>>;
+    readonly "motion.path": motion_react.ForwardRefComponent<SVGPathElement, motion_react.SVGMotionProps<SVGPathElement>>;
+    readonly "motion.pattern": motion_react.ForwardRefComponent<SVGPatternElement, motion_react.SVGMotionProps<SVGPatternElement>>;
+    readonly "motion.polygon": motion_react.ForwardRefComponent<SVGPolygonElement, motion_react.SVGMotionProps<SVGPolygonElement>>;
+    readonly "motion.polyline": motion_react.ForwardRefComponent<SVGPolylineElement, motion_react.SVGMotionProps<SVGPolylineElement>>;
+    readonly "motion.rect": motion_react.ForwardRefComponent<SVGRectElement, motion_react.SVGMotionProps<SVGRectElement>>;
+    readonly "motion.text": motion_react.ForwardRefComponent<SVGTextElement, motion_react.SVGMotionProps<SVGTextElement>>;
+};
+type AnimatedIconTag = keyof typeof TAGS;
+/**
+ * A single drawn node. Static SVG attributes sit flat alongside the spec keys,
+ * so one element is one line; {@link ANIMATED_ICON_RESERVED_KEYS} is the set the
+ * factory consumes rather than forwarding to the DOM.
+ */
+interface AnimatedIconNodeBase {
+    tag: AnimatedIconTag;
+    /** Motion's style type, which adds transform-origin shorthands to CSS. */
+    style?: AnimatedIconStyle;
+    className?: string;
+    variants?: Variants;
+    initial?: AnimatedIconInitial;
+    /**
+     * A literal animation target. When omitted, a `motion.*` node is driven by
+     * its control group unless `inherit` says otherwise.
+     */
+    animate?: AnimatedIconTarget;
+    exit?: AnimatedIconExit;
+    transition?: Transition;
+    /** Passed to a variant resolver — an index, a delay, or a small offset. */
+    custom?: unknown;
+    /** Control group driving this node. Defaults to `default`. */
+    group?: string;
+    /**
+     * Bind no control: the node takes its state from Motion's variant propagation
+     * down the tree, from a presence mount, or from nothing at all.
+     */
+    inherit?: boolean;
+    children?: AnimatedIconChild[];
+    /** Text content, for the one icon that draws a glyph. */
+    text?: string;
+}
+/**
+ * A node plus its flat static SVG attributes. The intersection (rather than an
+ * index signature on the interface) keeps every declared key precisely typed.
+ */
+type AnimatedIconNode = AnimatedIconNodeBase & {
+    [attribute: string]: unknown;
+};
+/** A bare string is a static `<path d="…"/>` — the commonest node by far. */
+type AnimatedIconChild = string | AnimatedIconNode;
+/** Spec keys the factory consumes; everything else is an SVG attribute. */
+declare const ANIMATED_ICON_RESERVED_KEYS: Set<string>;
+/**
+ * A mount/unmount swap: `active` nodes are mounted while the animation runs,
+ * `rest` nodes while it does not, with Motion's exit animations in between.
+ */
+interface AnimatedIconPresence {
+    tag: "presence";
+    active: AnimatedIconChild[];
+    rest: AnimatedIconChild[];
+}
+/** The root `<svg>`. Only deviations from the lucide defaults need stating. */
+interface AnimatedIconRoot extends Omit<AnimatedIconNodeBase, "tag" | "children"> {
+    tag?: "svg" | "motion.svg";
+    viewBox?: string;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: string | number;
+    strokeLinecap?: "round" | "butt" | "square";
+    strokeLinejoin?: "round" | "miter" | "bevel";
+    overflow?: string;
+}
+/** The complete description of one animated icon. */
+interface AnimatedIconSpec {
+    /** The component's `displayName`, e.g. `BellIcon`. */
+    name: string;
+    /** Root `<svg>` overrides and, when the whole icon animates, its motion props. */
+    svg?: AnimatedIconRoot;
+    /** The drawn tree, in paint order. */
+    elements: (AnimatedIconChild | AnimatedIconPresence)[];
+    /** Extra control groups beyond `default`, in a stable order. */
+    groups?: readonly string[];
+    /** Non-default play choreography. Defaults to `run(default, "animate")`. */
+    start?: (choreography: AnimatedIconChoreography) => void | Promise<void>;
+    /** Non-default rest choreography. Defaults to `reset(default, "normal")`. */
+    stop?: (choreography: AnimatedIconChoreography) => void | Promise<void>;
+}
+interface AnimatedIconOwnProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "ref"> {
+    /** Any CSS length. Defaults to the `--icon-default` role token. */
+    size?: number | string;
+    ref?: React.Ref<AnimatedIconHandle>;
+}
+/** The component shape `createAnimatedIcon` returns. */
+type AnimatedIconComponentType = ((props: AnimatedIconOwnProps) => React.JSX.Element) & {
+    displayName: string;
+};
+/**
+ * `createAnimatedIcon` — the single controller behind every mirrored
+ * `lucide-animated` icon. The factory owns the animation controls, the
+ * reduced-motion contract, the multi-input trigger rules, the imperative
+ * handle, and the host element; an icon module owns only its geometry and,
+ * where upstream choreography is not the default play/rest pair, its
+ * `start`/`stop`.
+ *
+ * Trigger rules, unchanged from the per-icon controllers they replace:
+ * hover plays on fine pointers, a pointer-down plays on touch, focus plays and
+ * blur rests, and every trigger is suppressed once a consumer attaches a ref
+ * (the icon is then under imperative control).
+ *
+ * @example
+ * export const BellIcon = createAnimatedIcon({
+ *   name: "BellIcon",
+ *   svg: { tag: "motion.svg", variants: SVG_VARIANTS },
+ *   elements: [{ tag: "path", attrs: { d: "M6 8a6 6 0 0 1 12 0…" } }],
+ * });
+ */
+declare function createAnimatedIcon(spec: AnimatedIconSpec): AnimatedIconComponentType;
+
+export { ANIMATED_ICON_RESERVED_KEYS, type AnimatedIconChild, type AnimatedIconChoreography, type AnimatedIconComponentType, type AnimatedIconControls, type AnimatedIconDefinition, type AnimatedIconExit, type AnimatedIconHandle, type AnimatedIconInitial, type AnimatedIconNode, type AnimatedIconOwnProps, type AnimatedIconPresence, type AnimatedIconRoot, type AnimatedIconSpec, type AnimatedIconStyle, type AnimatedIconTag, type AnimatedIconTarget, type AnimatedIconTransition, createAnimatedIcon };

package/dist/create-animated-icon.d.ts

@@ -0,0 +1,210 @@
+import * as motion_react from 'motion/react';
+import { motion, Variants, Transition, useAnimation } from 'motion/react';
+import * as React from 'react';
+
+/**
+ * Motion's imperative controls. `motion` does not export a public name for this
+ * type (`LegacyAnimationControls` lives in `motion-dom` and is not re-exported),
+ * so it is derived from the hook that produces it.
+ */
+type AnimatedIconControls = ReturnType<typeof useAnimation>;
+/** A variant label or an explicit target — whatever `controls.start()` accepts. */
+type AnimatedIconDefinition = Parameters<AnimatedIconControls["start"]>[0];
+/** The per-call transition override `controls.start()` accepts as its 2nd argument. */
+type AnimatedIconTransition = Parameters<AnimatedIconControls["start"]>[1];
+/**
+ * Motion's own prop types, taken from a Motion element rather than restated, so
+ * a spec can never declare something Motion would reject. (`initial` is
+ * deliberately narrower than a start() definition: it takes no variant resolver.)
+ */
+type MotionElementProps = React.ComponentProps<typeof motion.svg>;
+type AnimatedIconInitial = MotionElementProps["initial"];
+type AnimatedIconTarget = MotionElementProps["animate"];
+type AnimatedIconExit = MotionElementProps["exit"];
+/**
+ * The root renders as either `svg` or `motion.svg`, so a style must satisfy
+ * both: plain CSS plus Motion's transform-origin shorthands.
+ */
+type AnimatedIconStyle = React.CSSProperties & NonNullable<MotionElementProps["style"]>;
+/**
+ * The imperative handle every animated icon exposes on its ref — drive the
+ * animation programmatically instead of (or in addition to) hover/focus.
+ */
+interface AnimatedIconHandle {
+    startAnimation: () => void;
+    stopAnimation: () => void;
+}
+/**
+ * The choreography context handed to a spec's `start`/`stop`. Every timing
+ * primitive an icon may need is here, so an icon module never touches React.
+ */
+interface AnimatedIconChoreography {
+    /**
+     * Look up a control group by name; no argument gives the primary group. A
+     * function rather than a record so a group is never `possibly undefined` at
+     * the call site — the factory creates exactly the groups the spec declares.
+     */
+    control: (group?: string) => AnimatedIconControls;
+    /**
+     * The live `(prefers-reduced-motion: reduce)` preference, with an explicit
+     * `<MotionConfig reducedMotion>` override applied.
+     */
+    shouldReduceMotion: boolean;
+    /**
+     * Play a definition. A no-op that also halts the control when reduced motion
+     * is requested. Never rejects — an interrupted animation resolves.
+     */
+    run: (control: AnimatedIconControls, definition: AnimatedIconDefinition, transition?: AnimatedIconTransition) => Promise<void>;
+    /**
+     * Return to a resting definition. Under reduced motion the target is applied
+     * instantly instead of being animated to.
+     */
+    reset: (control: AnimatedIconControls, definition: AnimatedIconDefinition, transition?: AnimatedIconTransition) => Promise<void>;
+    /** Halt a control and snap it to a definition, with no animation, ever. */
+    set: (control: AnimatedIconControls, definition: AnimatedIconDefinition) => void;
+    /**
+     * Schedule deferred work. Every pending task is cancelled when the animation
+     * stops and when the icon unmounts, so an icon never leaks a timer.
+     */
+    after: (delayMs: number, task: () => void) => void;
+    /**
+     * Per-instance scratch for choreography that needs to remember something
+     * between calls — a re-entrancy latch, say. Persists for the icon's lifetime.
+     */
+    flags: Record<string, unknown>;
+}
+/** Every SVG element an icon may draw, plus its Motion counterpart. */
+declare const TAGS: {
+    readonly circle: "circle";
+    readonly defs: "defs";
+    readonly ellipse: "ellipse";
+    readonly g: "g";
+    readonly line: "line";
+    readonly path: "path";
+    readonly pattern: "pattern";
+    readonly polygon: "polygon";
+    readonly polyline: "polyline";
+    readonly rect: "rect";
+    readonly text: "text";
+    readonly "motion.circle": motion_react.ForwardRefComponent<SVGCircleElement, motion_react.SVGMotionProps<SVGCircleElement>>;
+    readonly "motion.ellipse": motion_react.ForwardRefComponent<SVGEllipseElement, motion_react.SVGMotionProps<SVGEllipseElement>>;
+    readonly "motion.g": motion_react.ForwardRefComponent<SVGGElement, motion_react.SVGMotionProps<SVGGElement>>;
+    readonly "motion.line": motion_react.ForwardRefComponent<SVGLineElement, motion_react.SVGMotionProps<SVGLineElement>>;
+    readonly "motion.path": motion_react.ForwardRefComponent<SVGPathElement, motion_react.SVGMotionProps<SVGPathElement>>;
+    readonly "motion.pattern": motion_react.ForwardRefComponent<SVGPatternElement, motion_react.SVGMotionProps<SVGPatternElement>>;
+    readonly "motion.polygon": motion_react.ForwardRefComponent<SVGPolygonElement, motion_react.SVGMotionProps<SVGPolygonElement>>;
+    readonly "motion.polyline": motion_react.ForwardRefComponent<SVGPolylineElement, motion_react.SVGMotionProps<SVGPolylineElement>>;
+    readonly "motion.rect": motion_react.ForwardRefComponent<SVGRectElement, motion_react.SVGMotionProps<SVGRectElement>>;
+    readonly "motion.text": motion_react.ForwardRefComponent<SVGTextElement, motion_react.SVGMotionProps<SVGTextElement>>;
+};
+type AnimatedIconTag = keyof typeof TAGS;
+/**
+ * A single drawn node. Static SVG attributes sit flat alongside the spec keys,
+ * so one element is one line; {@link ANIMATED_ICON_RESERVED_KEYS} is the set the
+ * factory consumes rather than forwarding to the DOM.
+ */
+interface AnimatedIconNodeBase {
+    tag: AnimatedIconTag;
+    /** Motion's style type, which adds transform-origin shorthands to CSS. */
+    style?: AnimatedIconStyle;
+    className?: string;
+    variants?: Variants;
+    initial?: AnimatedIconInitial;
+    /**
+     * A literal animation target. When omitted, a `motion.*` node is driven by
+     * its control group unless `inherit` says otherwise.
+     */
+    animate?: AnimatedIconTarget;
+    exit?: AnimatedIconExit;
+    transition?: Transition;
+    /** Passed to a variant resolver — an index, a delay, or a small offset. */
+    custom?: unknown;
+    /** Control group driving this node. Defaults to `default`. */
+    group?: string;
+    /**
+     * Bind no control: the node takes its state from Motion's variant propagation
+     * down the tree, from a presence mount, or from nothing at all.
+     */
+    inherit?: boolean;
+    children?: AnimatedIconChild[];
+    /** Text content, for the one icon that draws a glyph. */
+    text?: string;
+}
+/**
+ * A node plus its flat static SVG attributes. The intersection (rather than an
+ * index signature on the interface) keeps every declared key precisely typed.
+ */
+type AnimatedIconNode = AnimatedIconNodeBase & {
+    [attribute: string]: unknown;
+};
+/** A bare string is a static `<path d="…"/>` — the commonest node by far. */
+type AnimatedIconChild = string | AnimatedIconNode;
+/** Spec keys the factory consumes; everything else is an SVG attribute. */
+declare const ANIMATED_ICON_RESERVED_KEYS: Set<string>;
+/**
+ * A mount/unmount swap: `active` nodes are mounted while the animation runs,
+ * `rest` nodes while it does not, with Motion's exit animations in between.
+ */
+interface AnimatedIconPresence {
+    tag: "presence";
+    active: AnimatedIconChild[];
+    rest: AnimatedIconChild[];
+}
+/** The root `<svg>`. Only deviations from the lucide defaults need stating. */
+interface AnimatedIconRoot extends Omit<AnimatedIconNodeBase, "tag" | "children"> {
+    tag?: "svg" | "motion.svg";
+    viewBox?: string;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: string | number;
+    strokeLinecap?: "round" | "butt" | "square";
+    strokeLinejoin?: "round" | "miter" | "bevel";
+    overflow?: string;
+}
+/** The complete description of one animated icon. */
+interface AnimatedIconSpec {
+    /** The component's `displayName`, e.g. `BellIcon`. */
+    name: string;
+    /** Root `<svg>` overrides and, when the whole icon animates, its motion props. */
+    svg?: AnimatedIconRoot;
+    /** The drawn tree, in paint order. */
+    elements: (AnimatedIconChild | AnimatedIconPresence)[];
+    /** Extra control groups beyond `default`, in a stable order. */
+    groups?: readonly string[];
+    /** Non-default play choreography. Defaults to `run(default, "animate")`. */
+    start?: (choreography: AnimatedIconChoreography) => void | Promise<void>;
+    /** Non-default rest choreography. Defaults to `reset(default, "normal")`. */
+    stop?: (choreography: AnimatedIconChoreography) => void | Promise<void>;
+}
+interface AnimatedIconOwnProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "ref"> {
+    /** Any CSS length. Defaults to the `--icon-default` role token. */
+    size?: number | string;
+    ref?: React.Ref<AnimatedIconHandle>;
+}
+/** The component shape `createAnimatedIcon` returns. */
+type AnimatedIconComponentType = ((props: AnimatedIconOwnProps) => React.JSX.Element) & {
+    displayName: string;
+};
+/**
+ * `createAnimatedIcon` — the single controller behind every mirrored
+ * `lucide-animated` icon. The factory owns the animation controls, the
+ * reduced-motion contract, the multi-input trigger rules, the imperative
+ * handle, and the host element; an icon module owns only its geometry and,
+ * where upstream choreography is not the default play/rest pair, its
+ * `start`/`stop`.
+ *
+ * Trigger rules, unchanged from the per-icon controllers they replace:
+ * hover plays on fine pointers, a pointer-down plays on touch, focus plays and
+ * blur rests, and every trigger is suppressed once a consumer attaches a ref
+ * (the icon is then under imperative control).
+ *
+ * @example
+ * export const BellIcon = createAnimatedIcon({
+ *   name: "BellIcon",
+ *   svg: { tag: "motion.svg", variants: SVG_VARIANTS },
+ *   elements: [{ tag: "path", attrs: { d: "M6 8a6 6 0 0 1 12 0…" } }],
+ * });
+ */
+declare function createAnimatedIcon(spec: AnimatedIconSpec): AnimatedIconComponentType;
+
+export { ANIMATED_ICON_RESERVED_KEYS, type AnimatedIconChild, type AnimatedIconChoreography, type AnimatedIconComponentType, type AnimatedIconControls, type AnimatedIconDefinition, type AnimatedIconExit, type AnimatedIconHandle, type AnimatedIconInitial, type AnimatedIconNode, type AnimatedIconOwnProps, type AnimatedIconPresence, type AnimatedIconRoot, type AnimatedIconSpec, type AnimatedIconStyle, type AnimatedIconTag, type AnimatedIconTarget, type AnimatedIconTransition, createAnimatedIcon };