@aftershoot/feature-guard

A modern, flexible feature flag and toggle management library with ref-based element manipulation and decision system architecture for complex business logic.

✨ Key Features

• 🎯 Ref-based approach - Direct DOM manipulation, no wrapper components
• 🧠 Decision System - Complex business logic with multiple data sources
• 📱 Mobile-optimized tooltips - Touch-friendly floating tooltips
• ⚡ Performance optimized - resolveOne() for single feature checks
• ⚛️ React integration - Modern hooks with TypeScript support
• 🔧 Framework agnostic - Use with any JavaScript framework

🚀 Installation

npm install @aftershoot/feature-guard

📋 Quick Start

Basic Feature Toggle

import { useFeatureGuard } from '@aftershoot/feature-guard';

function PaymentButton() {
  const { featureRef } = useFeatureGuard({
    enabled: false,
    type: "disable",
    data: {
      tooltipConfig: {
        enabled: true,
        text: { defaultText: "Payment disabled by admin" }
      }
    }
  });

  return <button ref={featureRef}>Pay Now</button>;
}

Decision System for Complex Logic

import { createDecisionSystem, setSources } from '@aftershoot/feature-guard';

// Define your decision rules
const DS = createDecisionSystem<{ user: any; api: any }>();
const Decisions = DS.define({
  premiumFeature: {
    select: ({ user, api }) => user.tier === "premium" && api.enabled,
    type: (enabled) => enabled ? "show" : "blur",
    fallbackEnabled: false
  }
});

// Set global data sources
setSources(Decisions, {
  user: { tier: "free", role: "member" },
  api: { enabled: true }
});

// Use anywhere in your app
function PremiumComponent() {
  const toggle = useDecision("premiumFeature");
  const { featureRef } = useFeatureGuard(toggle);
  
  return <div ref={featureRef}>Premium Content</div>;
}

🎪 Interactive Examples

npm run storybook

View live examples with different scenarios:

• Basic toggles with API data
• Complex decision systems
• Performance comparisons
• Mobile tooltip interactions

📚 Documentation

• Usage Guide - Complete tutorials and examples
• API Reference - Function signatures and types
• Documentation Hub - Overview and architecture

🛡️ Toggle Types

• show - Feature visible and enabled
• hide - Feature completely hidden
• disable - Feature visible but disabled with tooltip
• blur - Feature visible but blurred with tooltip

⚡ Performance

Built for performance with:

• resolveOne() for single feature checks
• WeakMap cleanup for memory efficiency
• IntersectionObserver for off-screen optimization
• Debounced tooltip interactions

🔧 TypeScript Support

Full type safety with intelligent autocomplete:

type AppSources = {
  user: { tier: string; role: string };
  api: { enabled: boolean };
};

const DS = createDecisionSystem<AppSources>();
// TypeScript ensures your decision logic matches your data

🤝 Contributing

npm run build    # Build the package
npm run test     # Run tests  
npm run storybook # View examples

📜 License

MIT License - see LICENSE file.

Get started with the Usage Guide or explore API Reference