@mhmo91/schmancy 0.10.24 → 0.10.25

package/types/src/directives/art/types.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Art Directive Types
+ *
+ * Type definitions for the art directive animation system.
+ */
+import type { ParticlePool } from './particle-pool';
+export type ArtEffect = 'funkhaus' | 'samwa' | 'howl' | 'error' | 'snow' | 'starfield';
+export interface ArtOptions {
+    name: ArtEffect;
+    color: string;
+    /** Animation intensity: 0 = none, 0.5 = subtle, 1 = full (default: 1) */
+    intensity?: number;
+    /** Animation speed multiplier: 0.5 = half speed, 1 = normal, 2 = double (default: 1) */
+    speed?: number;
+}
+export interface Particle<T extends SVGElement = SVGElement> {
+    element: T;
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    life: number;
+    rotation?: number;
+    scale?: number;
+    phase?: number;
+}
+/** Extended physics particle used by samwa + snow effects. */
+export interface FallingParticle {
+    element: SVGPathElement;
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    life: number;
+    rotation: number;
+    phase: number;
+    sizeIndex: number;
+    depthIndex: number;
+    tumbleDirection: number;
+    flutterAmplitude: number;
+    flutterFrequency: number;
+    spawnTime: number;
+}
+export interface ArtState {
+    effect: ArtEffect;
+    color: string;
+    intensity: number;
+    speed: number;
+    element: HTMLElement;
+    overlayElement?: HTMLElement;
+    animationId?: number;
+    isVisible: boolean;
+    observer?: IntersectionObserver;
+    funkhaus?: {
+        panes: Array<{
+            element: SVGRectElement;
+            diagonalIndex: number;
+        }>;
+        maxDiagonal: number;
+        startTime: number;
+    };
+    samwa?: {
+        leafPool: ParticlePool<SVGPathElement>;
+        fallingLeaves: FallingParticle[];
+        windStrength: number;
+        windDirection: number;
+        lastWindTime: number;
+        lastLeafSpawn: number;
+        startTime: number;
+    };
+    howl?: {
+        gears: Array<{
+            element: SVGElement;
+            speed: number;
+        }>;
+        sparkles: Array<{
+            element: SVGPathElement;
+            baseX: number;
+            baseY: number;
+            phase: number;
+            speed: number;
+        }>;
+        steamPool: ParticlePool<SVGCircleElement>;
+        steamParticles: Particle<SVGCircleElement>[];
+        wisps: SVGPathElement[];
+        crystals: Array<{
+            element: SVGPolygonElement;
+            baseX: number;
+            baseY: number;
+            phase: number;
+            rotSpeed: number;
+        }>;
+        lastSteamSpawn: number;
+        startTime: number;
+    };
+    error?: {
+        edges: SVGRectElement[];
+        staticParticles: Array<{
+            element: SVGCircleElement;
+            edge: number;
+        }>;
+        boltPool: ParticlePool<SVGPathElement>;
+        lightningBolts: Particle<SVGPathElement>[];
+        lastLightningSpawn: number;
+        startTime: number;
+    };
+    snow?: {
+        snowflakePool: ParticlePool<SVGPathElement>;
+        fallingSnowflakes: FallingParticle[];
+        windStrength: number;
+        windDirection: number;
+        windPhase: number;
+        lastWindGust: number;
+        lastSpawn: number;
+        startTime: number;
+    };
+    starfield?: {
+        groups: Array<{
+            element: HTMLDivElement;
+            appearDelay: number;
+            twinkleDuration: number;
+            twinkleDelay: number;
+        }>;
+        startTime: number;
+    };
+}

package/types/src/directives/art/utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared DOM/SVG creation utilities for art effects.
+ */
+export declare function createOverlayContainer(className: string): HTMLDivElement;
+export declare function createSVG(): SVGSVGElement;

package/types/src/directives/battery.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Futuristic Battery Fill Directive
+ *
+ * A next-gen energy indicator with holographic effects, scan lines, and sci-fi aesthetics.
+ *
+ * @example
+ * ```ts
+ * html`<div ${futureCell({ percent: 75, variant: 'cyber' })}>POWER CORE</div>`
+ * html`<div ${futureCell({ percent: 50, variant: 'hologram' })}>ENERGY CELL</div>`
+ * ```
+ */
+import { AsyncDirective } from 'lit/async-directive.js';
+import type { ElementPart } from 'lit';
+export type FutureCellVariant = 'cyber' | 'hologram' | 'plasma' | 'quantum' | 'matrix' | 'neon' | 'success' | 'warning' | 'danger';
+export interface FutureCellOptions {
+    /** Fill percentage (0-100+) */
+    percent: number;
+    /** Visual variant */
+    variant?: FutureCellVariant;
+    /** Auto-select variant based on inventory status (≥80% = success/green, 50-79% = warning/yellow, <50% = danger/red) */
+    autoVariant?: boolean;
+    /** Custom accent color */
+    accentColor?: string;
+    /** Show digital readout */
+    showReadout?: boolean;
+    /** Show scan lines */
+    showScanLines?: boolean;
+    /** Show particles */
+    showParticles?: boolean;
+    /** Show hexagonal grid */
+    showGrid?: boolean;
+    /** Show glitch effects */
+    showGlitch?: boolean;
+    /** Intensity of effects (0-1) */
+    intensity?: number;
+    /** Animation speed multiplier */
+    speed?: number;
+    /** Enable critical state animations (when low or overfill) */
+    criticalEffects?: boolean;
+    /** Glass container effect */
+    glassEffect?: boolean;
+    /** Animation duration for fill transitions (ms) */
+    duration?: number;
+}
+declare class FutureCellDirective extends AsyncDirective {
+    private element;
+    private container;
+    private fillElement;
+    private energyWave;
+    private scanLine;
+    private particlesCanvas;
+    private particlesCtx;
+    private hexGrid;
+    private readout;
+    private dataStreams;
+    private glitchLayer;
+    private styleElement;
+    private options;
+    private variant;
+    private currentVariantName;
+    private particles;
+    private animationFrame;
+    private lastTime;
+    private currentPercent;
+    private originalStyles;
+    private resizeObserver;
+    /** Effective speed scales with fill %: low fill = calm, high fill = vivid */
+    private getEffectiveSpeed;
+    render(_options: FutureCellOptions): symbol;
+    update(part: ElementPart, [options]: [FutureCellOptions]): symbol;
+    private storeOriginalStyles;
+    private setupElement;
+    private createStructure;
+    private createFill;
+    private createEnergyWave;
+    private createHexGrid;
+    private createHexPattern;
+    private createScanLines;
+    private createParticles;
+    private resizeCanvas;
+    private setupResizeObserver;
+    private initParticles;
+    private spawnParticle;
+    private createDataStreams;
+    private createGlitchLayer;
+    private createReadout;
+    private updateColors;
+    private startAnimation;
+    private animate;
+    private updateParticles;
+    private hexToRGBA;
+    private updateFill;
+    disconnected(): void;
+}
+export declare const futureCell: (_options: FutureCellOptions) => import("lit-html/directive").DirectiveResult<typeof FutureCellDirective>;
+export {};

package/types/src/directives/beta.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Beta directive — gates content behind a configurable predicate.
+ *
+ * The consumer app registers a predicate (e.g. "user belongs to internal org")
+ * via `setBetaPredicate(...)`. Until then, `isBeta()` returns `false` and the
+ * directive renders the fallback.
+ *
+ * Usage:
+ * ```typescript
+ * import { beta, setBetaPredicate } from '@mhmo91/schmancy'
+ *
+ * // App boot — wire the predicate
+ * setBetaPredicate(() => currentUser.email.endsWith('@example.com'))
+ *
+ * // Templates — renders nothing for non-beta users
+ * ${beta(html`<my-beta-feature></my-beta-feature>`)}
+ *
+ * // With fallback
+ * ${beta(html`<beta-ui></beta-ui>`, html`<coming-soon></coming-soon>`)}
+ *
+ * // Imperative check
+ * if (isBeta()) { ... }
+ * ```
+ */
+import { nothing, type TemplateResult } from 'lit';
+type Content = TemplateResult | typeof nothing | string | unknown;
+/** Register a predicate that decides whether the current user has beta access. */
+export declare function setBetaPredicate(fn: () => boolean): void;
+/** Returns true if the current user has beta access. */
+export declare function isBeta(): boolean;
+/** Render content only for beta users, otherwise render fallback (default: nothing). */
+export declare function beta(content: Content, fallback?: Content): Content;
+export {};

package/types/src/directives/fill.d.ts

@@ -10,18 +10,12 @@ import { ElementPart } from 'lit/directive.js';
  * the box; inner scroll containers (apply `overflowWithin()` on the
  * appropriate cell) handle scrolling.
  *
- * Layout is the consumer's responsibility — apply Tailwind classes
- * (`grid grid-cols-[auto_1fr] grid-rows-[1fr]`, `flex`, etc.) on the same
- * element to express the layout. The directive provides the definite-pixel
- * box; the consumer decides how it's divided.
- *
- * Cascade-independent — measurement is taken in viewport coordinates
- * rather than computed from CSS, so the directive works regardless of
- * what the element's ancestors declare.
- *
  * Reactive sources: window/visualViewport resize + scroll, orientation
  * change, iOS keyboard focus-out, parent/element ResizeObserver, theme
- * fullscreen toggle, theme bottom offset (safe-area / nav-bar reservation).
+ * fullscreen toggle, theme bottom offset. Updates are frame-aligned via
+ * `auditTime(0, animationFrameScheduler)` — the latest emission of any
+ * source applies once per paint, so the box tracks continuous resize
+ * drags without missing the final state.
  *
  * @example sidebar + main
  *   <app-shell
@@ -35,7 +29,6 @@ import { ElementPart } from 'lit/directive.js';
 declare class Fill extends AsyncDirective {
     private element;
     private disconnecting$;
-    private apply;
     private subscribe;
     render(): void;
     update(part: ElementPart): void;

package/types/src/directives/fyi.d.ts

@@ -0,0 +1,76 @@
+/**
+ * FYI Directive — cute animated emoji indicators.
+ *
+ * Shows adorable emoji indicators with timing control, position options, and
+ * animation styles. Perfect for subtle hints, onboarding nudges, or playful UI
+ * feedback.
+ *
+ * **Overlay-aware**: Waits for sheets/dialogs to close before showing.
+ * **Requires emoji**: Without an emoji, this directive has no visible effect.
+ * For shimmer effects, use `nebula()` (header) or `<schmancy-fancy>` (cards).
+ *
+ * ## Cleanup pattern (Lit AsyncDirective)
+ *
+ * - `disconnected()`: releases all resources when the directive leaves use.
+ * - `reconnected()`: restores working state when the directive returns to use.
+ * - `isConnected`: checked before subscribing to prevent memory leaks.
+ *
+ * @see https://lit.dev/docs/templates/custom-directives/#async-directives
+ *
+ * @example
+ * ```ts
+ * // Basic emoji hint
+ * html`<button ${fyi('☝️')}>Select folder</button>`
+ *
+ * // Emoji with position
+ * html`<button ${fyi({ emoji: '☝️', position: 'bottom' })}>Select folder</button>`
+ *
+ * // Full options
+ * html`<button ${fyi({
+ *   emoji: '🎉',
+ *   position: 'bottom',
+ *   showAfter: 500,
+ *   hideAfter: 3000,
+ *   animation: 'bounce',
+ * })}>Celebrate!</button>`
+ * ```
+ */
+import { AsyncDirective } from 'lit/async-directive.js';
+import type { ElementPart } from 'lit';
+export type FyiPosition = 'auto' | 'top' | 'bottom' | 'left' | 'right';
+export type FyiAnimation = 'point' | 'bounce' | 'pulse' | 'none';
+export interface FyiOptions {
+    /** The emoji to display (omit for shimmer-only mode) */
+    emoji?: string;
+    /** Where to position the indicator (default: 'auto') */
+    position?: FyiPosition;
+    /** Delay in ms before showing (default: 0) */
+    showAfter?: number;
+    /** Duration in ms before auto-hiding (omit to stay visible) */
+    hideAfter?: number;
+    /** Animation type (default: 'point') */
+    animation?: FyiAnimation;
+    /** Duration of one shimmer cycle in ms (default: 3000) */
+    shimmerDuration?: number;
+}
+declare class FyiDirective extends AsyncDirective {
+    private state;
+    private destroy$;
+    private subscriptions;
+    render(_options?: FyiOptions): symbol;
+    update(part: ElementPart, [options]: [FyiOptions?]): symbol;
+    private scheduleShow;
+    private waitForOverlaysClear;
+    private show;
+    private applyAnimation;
+    private getPointingKeyframes;
+    private scheduleHide;
+    private hide;
+    private restoreStyles;
+    private getPositionTransform;
+    private cleanup;
+    disconnected(): void;
+    reconnected(): void;
+}
+export declare const fyi: (_options?: FyiOptions) => import("lit-html/directive").DirectiveResult<typeof FyiDirective>;
+export {};

package/types/src/directives/hummingbird.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Hummingbird Directive - Realistic hummingbird flight animation
+ *
+ * PERFORMANCE OPTIMIZATIONS:
+ * 1. Use CSS transforms only (GPU-accelerated, no layout/paint)
+ * 2. will-change hints for compositor optimization
+ * 3. Single RAF loop, no nested animations
+ * 4. Minimize DOM operations
+ * 5. Pre-calculate values where possible
+ * 6. Use CSS animations for constant motion (wing blur)
+ *
+ * Based on scientific research:
+ * - Wing beat ~43Hz (PMC3311889)
+ * - Forward speed 13 m/s / 30mph (Britannica)
+ * - Figure-8 hover pattern (Royal Society)
+ *
+ * ANIMATION STATES (State Machine):
+ * - idle: waiting for delay
+ * - flying: moving between waypoints
+ * - hovering: figure-8 pattern at waypoint
+ * - spiraling: approaching black hole
+ * - absorbed: being sucked into black hole
+ * - done: cleanup complete
+ */
+import { AsyncDirective } from 'lit/async-directive.js';
+import type { ElementPart } from 'lit';
+/**
+ * Element reference for waypoints/target:
+ * - CSS selector (e.g., '#app-card-melanie', '.my-class') - event-based discovery
+ * - Component tag name (e.g., 'schmancy-fancy') - event-based discovery
+ * - HTMLElement reference directly
+ */
+type ElementRef = string | HTMLElement;
+/** Waypoint with optional duration control */
+interface Waypoint {
+    ref: ElementRef;
+    duration?: number;
+}
+interface HummingbirdOptions {
+    /** Waypoints the bird visits in sequence */
+    waypoints?: (ElementRef | Waypoint)[];
+    /** Where the bird returns home (triggers black hole effect). If omitted, bird fades out after last waypoint. */
+    home?: ElementRef;
+    /** Delay before starting flight (ms) */
+    delay?: number;
+    /** Whether the hummingbird should be playing. When false, cleans up and pauses. Defaults to true. */
+    playing?: boolean;
+    /** Show animated connection lines between visited waypoints. Defaults to false. */
+    showConnections?: boolean;
+}
+declare class HummingbirdDirective extends AsyncDirective {
+    private state$;
+    private destroyed$;
+    private visible$;
+    private bird;
+    private blackHole;
+    private particles;
+    private trailCanvas;
+    private trailCtx;
+    private lastTrailPos;
+    private rafId;
+    private context;
+    private element;
+    private options;
+    private hasHome;
+    /**
+     * Convert viewport coordinates to host-relative coordinates.
+     * getBoundingClientRect() returns viewport coords; we subtract the host's rect.
+     */
+    private toHostRelative;
+    render(_options?: boolean | HummingbirdOptions): symbol;
+    update(part: ElementPart, [options]: [boolean | HummingbirdOptions | undefined]): symbol;
+    private initStateMachine;
+    private handleStateTransition;
+    private createBird;
+    /** Current bird color — empty until `discoverInitialColor()` resolves a theme color. */
+    private currentColor;
+    /**
+     * Discover initial theme color from nearest schmancy-theme.
+     * Dispatches event FROM the host element so it bubbles up to nearest theme.
+     */
+    private discoverInitialColor;
+    /**
+     * Discover and update bird color based on current destination's theme.
+     * Dispatches event FROM the destination element so it bubbles to its nearest theme.
+     */
+    private updateBirdColor;
+    /**
+     * Discover all waypoint elements and return their positions with element references.
+     * Supports both simple ElementRef and Waypoint objects with duration.
+     * Uses RxJS forkJoin for parallel discovery.
+     */
+    private discoverWaypoints;
+    /**
+     * Discover a single element by reference using event-based discovery.
+     * - HTMLElement: return directly
+     * - String (CSS selector or component tag): use discover() service
+     */
+    private discoverElement;
+    /**
+     * Get position from an element reference (includes element for theme discovery).
+     * Target uses center position (for black hole effect).
+     */
+    private getPosition;
+    /**
+     * Update all destination positions from their stored element references.
+     * Called on window resize/scroll to keep positions accurate.
+     */
+    private updateDestinationPositions;
+    private startAnimationLoop;
+    private tickFlying;
+    /** Active shimmer overlay for current waypoint */
+    private shimmerOverlay;
+    private shimmerAnimation;
+    /** Active pulse rings for current waypoint */
+    private pulseRings;
+    private tickHovering;
+    /**
+ * Check if an element is sufficiently visible (opacity > 0.5 and not hidden)
+ * Uses 0.5 threshold to wait for CSS transitions to be halfway done
+ */
+    private isElementVisible;
+    /** Check if element is within the viewport bounds (with padding so bird doesn't fly to edges) */
+    private isInViewport;
+    /**
+     * Show shimmer effect on an element (similar to fyi directive)
+     */
+    private showShimmer;
+    /**
+     * Hide and cleanup shimmer effect
+     */
+    private hideShimmer;
+    /**
+     * Fade out bird gracefully (when no home defined)
+     */
+    private fadeOutBird;
+    /**
+     * Fade out bird and all visual elements gracefully before cleanup (when playing becomes false)
+     */
+    private fadeOutAndCleanup;
+    /**
+     * Show expanding pulse rings at position (like ripple/wave effect)
+     */
+    private showPulseRings;
+    private tickSpiraling;
+    /** Store home element for distortion effect */
+    private homeElement;
+    /**
+     * Start gravitational shake/wobble effect on the home element during absorption
+     */
+    private startHostDistortion;
+    private tickAbsorbed;
+    /** Additional visual elements for enhanced blackhole */
+    private accretionDisks;
+    private lensingRing;
+    private eventHorizon;
+    private createBlackHole;
+    private addParticles;
+    private collapseBlackHole;
+    /**
+     * Create the canvas for real-time trail rendering
+     */
+    private ensureTrailCanvas;
+    /**
+     * Draw trail segment from last position to current position
+     */
+    private drawTrail;
+    /**
+     * Reset trail position (called when starting new flight segment)
+     */
+    private resetTrail;
+    /**
+     * Fade out the entire trail canvas
+     */
+    private fadeTrail;
+    private cleanup;
+    disconnected(): void;
+}
+export declare const hummingbird: (_options?: boolean | HummingbirdOptions) => import("lit-html/directive").DirectiveResult<typeof HummingbirdDirective>;
+export {};

package/types/src/directives/index.d.ts

@@ -1,4 +1,8 @@
 export * from './animate-text';
+export * from './ai-badge';
+export * from './art';
+export * from './battery';
+export * from './beta';
 export * from './color';
 export * from './confirm-click';
 export * from './cursor-glow';
@@ -6,15 +10,20 @@ export * from './cycle-text';
 export * from './depth-of-field';
 export * from './drag';
 export * from './fill';
+export * from './fyi';
 export * from './gravity';
+export * from './hummingbird';
 export * from './intersect';
 export * from './layout';
 export * from './liquid';
 export * from './living-border';
 export * from './long-press';
 export * from './magnetic';
+export * from './missed-punch';
 export * from './nebula';
 export * from './reduced-motion';
 export * from './reveal';
 export * from './ripple';
 export * from './overflow-within';
+export * from './urgent';
+export * from './working-snake';

package/types/src/directives/missed-punch.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Missed Punch directive — shattering glass effect for incomplete attendance.
+ *
+ * Renders an animated shattering/fragmenting overlay when an employee has only
+ * one punch on a past date, indicating they forgot to punch out.
+ *
+ * Visual: glass shards/fragments flying outward with a crack pattern.
+ */
+import type { ElementPart } from 'lit';
+import { AsyncDirective } from 'lit/async-directive.js';
+export interface MissedPunchOptions {
+    active: boolean;
+    color?: string;
+    width?: number;
+}
+declare class MissedPunchDirective extends AsyncDirective {
+    private state;
+    render(_options: MissedPunchOptions): symbol;
+    update(part: ElementPart, [options]: [MissedPunchOptions]): symbol;
+    private createOverlay;
+    private generateShardPoints;
+    private setupVisibilityObserver;
+    private startAnimation;
+    private cleanup;
+    disconnected(): void;
+}
+export declare const missedPunch: (_options: MissedPunchOptions) => import("lit-html/directive").DirectiveResult<typeof MissedPunchDirective>;
+export {};