@ops-ai/astro-feature-flags-toggly 1.0.0

package/dist/components/Feature.astro

@@ -0,0 +1,79 @@
+---
+/**
+ * Feature - Server-rendered feature flag component for Astro
+ * 
+ * This component evaluates feature flags on the server side during SSR/SSG.
+ * Use this for content that should be evaluated at build time or on each request.
+ * 
+ * @example
+ * ```astro
+ * <Feature flag="new-dashboard">
+ *   <p>This content is only shown when the feature is enabled</p>
+ * </Feature>
+ * ```
+ * 
+ * @example Multiple flags with 'any' requirement
+ * ```astro
+ * <Feature flags={['feature1', 'feature2']} requirement="any">
+ *   <p>Shown if at least one feature is enabled</p>
+ * </Feature>
+ * ```
+ * 
+ * @example With fallback content
+ * ```astro
+ * <Feature flag="beta-feature">
+ *   <p>Beta content</p>
+ *   <div slot="fallback">
+ *     <p>Beta feature not available yet</p>
+ *   </div>
+ * </Feature>
+ * ```
+ */
+
+interface Props {
+  /** Single feature flag key to check */
+  flag?: string;
+  /** Multiple feature flag keys to check */
+  flags?: string[];
+  /** Requirement for multiple flags: 'all' or 'any' (default: 'all') */
+  requirement?: 'all' | 'any';
+  /** If true, negates the result (default: false) */
+  negate?: boolean;
+}
+
+const { flag, flags, requirement = 'all', negate = false } = Astro.props;
+
+// Get Toggly client from Astro.locals
+const toggly = Astro.locals.toggly;
+
+if (!toggly) {
+  console.warn(
+    '[Toggly Feature] Client not found in Astro.locals. ' +
+    'Make sure the Toggly integration is properly configured.'
+  );
+}
+
+// Build feature keys array
+const flagKeys: string[] = [];
+if (flag) {
+  flagKeys.push(flag);
+}
+if (flags && Array.isArray(flags)) {
+  flagKeys.push(...flags);
+}
+
+// Evaluate feature gate
+let isEnabled = false;
+if (toggly && flagKeys.length > 0) {
+  try {
+    isEnabled = await toggly.evaluateGate(flagKeys, requirement, negate);
+  } catch (error) {
+    console.error('[Toggly Feature] Error evaluating feature gate:', error);
+    isEnabled = false;
+  }
+}
+---
+
+{isEnabled ? <slot /> : <slot name="fallback" />}
+
+

package/dist/components/FeatureClient.astro

@@ -0,0 +1,144 @@
+---
+/**
+ * FeatureClient - Client-side hydrated feature flag component
+ * 
+ * This component evaluates feature flags on the client side using Astro islands.
+ * Use this when you need dynamic, client-side feature flag evaluation or when
+ * you want to update the UI based on flag changes without a page reload.
+ * 
+ * @example Basic usage with client:load
+ * ```astro
+ * <FeatureClient flag="new-feature" client="load">
+ *   <p>This content hydrates and checks the flag on the client</p>
+ * </FeatureClient>
+ * ```
+ * 
+ * @example With client:visible for lazy loading
+ * ```astro
+ * <FeatureClient flag="beta-widget" client="visible">
+ *   <BetaWidget />
+ * </FeatureClient>
+ * ```
+ * 
+ * @example With fallback
+ * ```astro
+ * <FeatureClient flag="premium-feature" client="load">
+ *   <PremiumContent />
+ *   <div slot="fallback">
+ *     <p>Upgrade to access premium features</p>
+ *   </div>
+ * </FeatureClient>
+ * ```
+ */
+
+interface Props {
+  /** Feature flag key to check */
+  flag: string;
+  /** Hydration strategy: 'load', 'idle', or 'visible' (default: 'load') */
+  client?: 'load' | 'idle' | 'visible';
+  /** Requirement for multiple flags: 'all' or 'any' (default: 'all') */
+  requirement?: 'all' | 'any';
+  /** If true, negates the result (default: false) */
+  negate?: boolean;
+}
+
+const { flag, client = 'load', requirement = 'all', negate = false } = Astro.props;
+---
+
+<div
+  data-toggly-feature={flag}
+  data-toggly-requirement={requirement}
+  data-toggly-negate={negate}
+  data-toggly-hydrate={client}
+  class="toggly-feature-client"
+>
+  <div data-toggly-content>
+    <slot />
+  </div>
+  <div data-toggly-fallback style="display: none;">
+    <slot name="fallback" />
+  </div>
+</div>
+
+<script>
+  import { $flags, $isReady } from '@ops-ai/astro-feature-flags-toggly/client/store';
+
+  // Hydrate all FeatureClient components
+  function hydrateFeatureClients() {
+    const elements = document.querySelectorAll<HTMLElement>('.toggly-feature-client');
+
+    elements.forEach((element) => {
+      const flag = element.dataset.togglyFeature;
+      const requirement = (element.dataset.togglyRequirement as 'all' | 'any') || 'all';
+      const negate = element.dataset.togglyNegate === 'true';
+
+      if (!flag) return;
+
+      const content = element.querySelector<HTMLElement>('[data-toggly-content]');
+      const fallback = element.querySelector<HTMLElement>('[data-toggly-fallback]');
+
+      if (!content || !fallback) return;
+
+      // Subscribe to flags changes
+      const unsubscribe = $flags.subscribe((flags) => {
+        // Wait for flags to be ready
+        const ready = $isReady.get();
+        if (!ready) return;
+
+        // Evaluate flag
+        const flagKeys = flag.split(',').map((k) => k.trim());
+        let isEnabled: boolean;
+
+        if (requirement === 'any') {
+          isEnabled = flagKeys.some((key) => flags[key] === true);
+        } else {
+          isEnabled = flagKeys.every((key) => flags[key] === true);
+        }
+
+        if (negate) {
+          isEnabled = !isEnabled;
+        }
+
+        // Show/hide content based on flag
+        if (isEnabled) {
+          content.style.display = '';
+          fallback.style.display = 'none';
+        } else {
+          content.style.display = 'none';
+          fallback.style.display = '';
+        }
+      });
+
+      // Store unsubscribe function for cleanup
+      (element as any).__togglyUnsubscribe = unsubscribe;
+    });
+  }
+
+  // Hydrate on page load
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', hydrateFeatureClients);
+  } else {
+    hydrateFeatureClients();
+  }
+
+  // Re-hydrate on navigation (for view transitions)
+  document.addEventListener('astro:page-load', hydrateFeatureClients);
+
+  // Cleanup on navigation
+  document.addEventListener('astro:before-swap', () => {
+    document.querySelectorAll('.toggly-feature-client').forEach((element) => {
+      const unsubscribe = (element as any).__togglyUnsubscribe;
+      if (unsubscribe) {
+        unsubscribe();
+      }
+    });
+  });
+</script>
+
+<style>
+  .toggly-feature-client {
+    display: contents;
+  }
+</style>
+
+

package/dist/frameworks/react/Feature.d.ts

@@ -0,0 +1,86 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+interface FeatureProps {
+    /** Single feature flag key to check */
+    flag?: string;
+    /** Multiple feature flag keys to check */
+    flags?: string[];
+    /** Requirement for multiple flags: 'all' or 'any' (default: 'all') */
+    requirement?: 'all' | 'any';
+    /** If true, negates the result (default: false) */
+    negate?: boolean;
+    /** Content to render when flag is enabled */
+    children: ReactNode;
+    /** Content to render when flag is disabled (optional) */
+    fallback?: ReactNode;
+}
+/**
+ * Feature - React component for conditional rendering based on feature flags
+ *
+ * @example
+ * ```tsx
+ * <Feature flag="new-dashboard">
+ *   <Dashboard />
+ * </Feature>
+ * ```
+ *
+ * @example Multiple flags with 'any' requirement
+ * ```tsx
+ * <Feature flags={['feature1', 'feature2']} requirement="any">
+ *   <Content />
+ * </Feature>
+ * ```
+ *
+ * @example With fallback
+ * ```tsx
+ * <Feature flag="premium-feature" fallback={<UpgradePrompt />}>
+ *   <PremiumContent />
+ * </Feature>
+ * ```
+ */
+declare function Feature({ flag, flags, requirement, negate, children, fallback, }: FeatureProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to check if a feature flag is enabled
+ *
+ * @param flagKey - Feature flag key to check
+ * @param defaultValue - Default value if flag not found (default: false)
+ * @returns Object with enabled state and ready state
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { enabled, isReady } = useFeatureFlag('new-dashboard');
+ *
+ *   if (!isReady) return <Loading />;
+ *   if (!enabled) return <OldDashboard />;
+ *   return <NewDashboard />;
+ * }
+ * ```
+ */
+declare function useFeatureFlag(flagKey: string, defaultValue?: boolean): {
+    enabled: boolean;
+    isReady: boolean;
+};
+/**
+ * Hook to check if multiple feature flags are enabled
+ *
+ * @param flagKeys - Array of feature flag keys to check
+ * @param requirement - 'all' or 'any' (default: 'all')
+ * @param negate - If true, negates the result (default: false)
+ * @returns Object with enabled state and ready state
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { enabled } = useFeatureGate(['feature1', 'feature2'], 'any');
+ *   return enabled ? <NewFeatures /> : <OldFeatures />;
+ * }
+ * ```
+ */
+declare function useFeatureGate(flagKeys: string[], requirement?: 'all' | 'any', negate?: boolean): {
+    enabled: boolean;
+    isReady: boolean;
+};
+
+export { Feature, type FeatureProps, Feature as default, useFeatureFlag, useFeatureGate };

package/dist/frameworks/react/Feature.js

@@ -0,0 +1,14 @@
+import {
+  Feature,
+  Feature_default,
+  useFeatureFlag,
+  useFeatureGate
+} from "../../chunk-XCJSQJHR.js";
+import "../../chunk-FK633ULF.js";
+export {
+  Feature,
+  Feature_default as default,
+  useFeatureFlag,
+  useFeatureGate
+};
+//# sourceMappingURL=Feature.js.map

package/dist/frameworks/react/Feature.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/frameworks/react/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Feature, FeatureProps, useFeatureFlag, useFeatureGate } from './Feature.js';
+import 'react/jsx-runtime';
+import 'react';

package/dist/frameworks/react/index.js

@@ -0,0 +1,12 @@
+import {
+  Feature,
+  useFeatureFlag,
+  useFeatureGate
+} from "../../chunk-XCJSQJHR.js";
+import "../../chunk-FK633ULF.js";
+export {
+  Feature,
+  useFeatureFlag,
+  useFeatureGate
+};
+//# sourceMappingURL=index.js.map

package/dist/frameworks/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/frameworks/svelte/Feature.svelte

@@ -0,0 +1,75 @@
+<script lang="ts">
+/**
+ * Svelte Feature Component for Astro Islands
+ * 
+ * Use this component in Svelte islands within Astro for client-side feature flagging.
+ * Integrates with nanostores for reactive state management.
+ * 
+ * @example
+ * ```svelte
+ * <Feature flag="new-dashboard">
+ *   <Dashboard />
+ * </Feature>
+ * ```
+ * 
+ * @example Multiple flags with 'any' requirement
+ * ```svelte
+ * <Feature flags={['feature1', 'feature2']} requirement="any">
+ *   <Content />
+ * </Feature>
+ * ```
+ * 
+ * @example With fallback
+ * ```svelte
+ * <Feature flag="premium-feature">
+ *   <PremiumContent />
+ *   <svelte:fragment slot="fallback">
+ *     <UpgradePrompt />
+ *   </svelte:fragment>
+ * </Feature>
+ * ```
+ */
+
+import { $flags, $isReady } from '../../client/store.js';
+
+export let flag: string | undefined = undefined;
+export let flags: string[] | undefined = undefined;
+export let requirement: 'all' | 'any' = 'all';
+export let negate: boolean = false;
+
+// Reactively compute whether the feature is enabled
+$: flagKeys = (() => {
+  const keys: string[] = [];
+  if (flag) keys.push(flag);
+  if (flags && Array.isArray(flags)) keys.push(...flags);
+  return keys;
+})();
+
+$: isEnabled = (() => {
+  if (flagKeys.length === 0) {
+    return !negate;
+  }
+
+  let enabled: boolean;
+
+  if (requirement === 'any') {
+    enabled = flagKeys.some((key) => $flags[key] === true);
+  } else {
+    enabled = flagKeys.every((key) => $flags[key] === true);
+  }
+
+  if (negate) {
+    enabled = !enabled;
+  }
+
+  return enabled;
+})();
+</script>
+
+{#if $isReady && isEnabled}
+  <slot />
+{:else}
+  <slot name="fallback" />
+{/if}
+
+

package/dist/frameworks/svelte/stores.d.ts

@@ -0,0 +1,54 @@
+import * as svelte_store from 'svelte/store';
+export { $flags as flags, $isReady as isReady } from '../../client/store.js';
+import 'nanostores';
+import '../../index-S3g0i0FH.js';
+
+/**
+ * Create a derived store for a specific feature flag
+ *
+ * @param flagKey - Feature flag key to check
+ * @param defaultValue - Default value if flag not found (default: false)
+ * @returns Svelte-compatible derived store
+ *
+ * @example
+ * ```svelte
+ * <script>
+ * import { featureFlag } from '@ops-ai/astro-feature-flags-toggly/svelte';
+ *
+ * const newDashboard = featureFlag('new-dashboard');
+ * </script>
+ *
+ * {#if $newDashboard}
+ *   <NewDashboard />
+ * {:else}
+ *   <OldDashboard />
+ * {/if}
+ * ```
+ */
+declare function featureFlag(flagKey: string, defaultValue?: boolean): svelte_store.Readable<boolean>;
+/**
+ * Create a derived store that evaluates multiple feature flags
+ *
+ * @param flagKeys - Array of feature flag keys to check
+ * @param requirement - 'all' or 'any' (default: 'all')
+ * @param negate - If true, negates the result (default: false)
+ * @returns Svelte-compatible derived store
+ *
+ * @example
+ * ```svelte
+ * <script>
+ * import { featureGate } from '@ops-ai/astro-feature-flags-toggly/svelte';
+ *
+ * const hasAnyFeature = featureGate(['feature1', 'feature2'], 'any');
+ * </script>
+ *
+ * {#if $hasAnyFeature}
+ *   <NewFeatures />
+ * {:else}
+ *   <OldFeatures />
+ * {/if}
+ * ```
+ */
+declare function featureGate(flagKeys: string[], requirement?: 'all' | 'any', negate?: boolean): svelte_store.Readable<boolean>;
+
+export { featureFlag, featureGate };

package/dist/frameworks/svelte/stores.js

@@ -0,0 +1,34 @@
+import {
+  $flags,
+  $isReady
+} from "../../chunk-FK633ULF.js";
+
+// src/frameworks/svelte/stores.ts
+import { derived } from "svelte/store";
+function featureFlag(flagKey, defaultValue = false) {
+  return derived($flags, ($flags2) => $flags2[flagKey] ?? defaultValue);
+}
+function featureGate(flagKeys, requirement = "all", negate = false) {
+  return derived($flags, ($flags2) => {
+    if (flagKeys.length === 0) {
+      return !negate;
+    }
+    let isEnabled;
+    if (requirement === "any") {
+      isEnabled = flagKeys.some((key) => $flags2[key] === true);
+    } else {
+      isEnabled = flagKeys.every((key) => $flags2[key] === true);
+    }
+    if (negate) {
+      isEnabled = !isEnabled;
+    }
+    return isEnabled;
+  });
+}
+export {
+  featureFlag,
+  featureGate,
+  $flags as flags,
+  $isReady as isReady
+};
+//# sourceMappingURL=stores.js.map

package/dist/frameworks/svelte/stores.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/frameworks/svelte/stores.ts"],"sourcesContent":["/**\n * Svelte-specific store utilities for Toggly\n * \n * Re-exports nanostores for easy use in Svelte components\n */\n\nimport { derived } from 'svelte/store';\nimport { $flags, $isReady } from '../../client/store.js';\n\n/**\n * Create a derived store for a specific feature flag\n * \n * @param flagKey - Feature flag key to check\n * @param defaultValue - Default value if flag not found (default: false)\n * @returns Svelte-compatible derived store\n * \n * @example\n * ```svelte\n * <script>\n * import { featureFlag } from '@ops-ai/astro-feature-flags-toggly/svelte';\n * \n * const newDashboard = featureFlag('new-dashboard');\n * </script>\n * \n * {#if $newDashboard}\n *   <NewDashboard />\n * {:else}\n *   <OldDashboard />\n * {/if}\n * ```\n */\nexport function featureFlag(flagKey: string, defaultValue: boolean = false) {\n  return derived($flags, ($flags) => $flags[flagKey] ?? defaultValue);\n}\n\n/**\n * Create a derived store that evaluates multiple feature flags\n * \n * @param flagKeys - Array of feature flag keys to check\n * @param requirement - 'all' or 'any' (default: 'all')\n * @param negate - If true, negates the result (default: false)\n * @returns Svelte-compatible derived store\n * \n * @example\n * ```svelte\n * <script>\n * import { featureGate } from '@ops-ai/astro-feature-flags-toggly/svelte';\n * \n * const hasAnyFeature = featureGate(['feature1', 'feature2'], 'any');\n * </script>\n * \n * {#if $hasAnyFeature}\n *   <NewFeatures />\n * {:else}\n *   <OldFeatures />\n * {/if}\n * ```\n */\nexport function featureGate(\n  flagKeys: string[],\n  requirement: 'all' | 'any' = 'all',\n  negate: boolean = false\n) {\n  return derived($flags, ($flags) => {\n    if (flagKeys.length === 0) {\n      return !negate;\n    }\n\n    let isEnabled: boolean;\n\n    if (requirement === 'any') {\n      isEnabled = flagKeys.some((key) => $flags[key] === true);\n    } else {\n      isEnabled = flagKeys.every((key) => $flags[key] === true);\n    }\n\n    if (negate) {\n      isEnabled = !isEnabled;\n    }\n\n    return isEnabled;\n  });\n}\n\n// Re-export base stores for direct use\nexport { $flags as flags, $isReady as isReady };\n\n\n"],"mappings":";;;;;;AAMA,SAAS,eAAe;AAyBjB,SAAS,YAAY,SAAiB,eAAwB,OAAO;AAC1E,SAAO,QAAQ,QAAQ,CAACA,YAAWA,QAAO,OAAO,KAAK,YAAY;AACpE;AAyBO,SAAS,YACd,UACA,cAA6B,OAC7B,SAAkB,OAClB;AACA,SAAO,QAAQ,QAAQ,CAACA,YAAW;AACjC,QAAI,SAAS,WAAW,GAAG;AACzB,aAAO,CAAC;AAAA,IACV;AAEA,QAAI;AAEJ,QAAI,gBAAgB,OAAO;AACzB,kBAAY,SAAS,KAAK,CAAC,QAAQA,QAAO,GAAG,MAAM,IAAI;AAAA,IACzD,OAAO;AACL,kBAAY,SAAS,MAAM,CAAC,QAAQA,QAAO,GAAG,MAAM,IAAI;AAAA,IAC1D;AAEA,QAAI,QAAQ;AACV,kBAAY,CAAC;AAAA,IACf;AAEA,WAAO;AAAA,EACT,CAAC;AACH;","names":["$flags"]}

package/dist/frameworks/vue/Feature.vue

@@ -0,0 +1,93 @@
+<template>
+  <slot v-if="isReady && isEnabled" />
+  <slot v-else name="fallback" />
+</template>
+
+<script setup lang="ts">
+/**
+ * Vue Feature Component for Astro Islands
+ * 
+ * Use this component in Vue islands within Astro for client-side feature flagging.
+ * Integrates with nanostores for reactive state management.
+ * 
+ * @example
+ * ```vue
+ * <Feature flag="new-dashboard">
+ *   <Dashboard />
+ * </Feature>
+ * ```
+ * 
+ * @example Multiple flags with 'any' requirement
+ * ```vue
+ * <Feature :flags="['feature1', 'feature2']" requirement="any">
+ *   <Content />
+ * </Feature>
+ * ```
+ * 
+ * @example With fallback
+ * ```vue
+ * <Feature flag="premium-feature">
+ *   <PremiumContent />
+ *   <template #fallback>
+ *     <UpgradePrompt />
+ *   </template>
+ * </Feature>
+ * ```
+ */
+
+import { computed } from 'vue';
+import { useStore } from '@nanostores/vue';
+import { $flags, $isReady } from '../../client/store.js';
+
+export interface FeatureProps {
+  /** Single feature flag key to check */
+  flag?: string;
+  /** Multiple feature flag keys to check */
+  flags?: string[];
+  /** Requirement for multiple flags: 'all' or 'any' (default: 'all') */
+  requirement?: 'all' | 'any';
+  /** If true, negates the result (default: false) */
+  negate?: boolean;
+}
+
+const props = withDefaults(defineProps<FeatureProps>(), {
+  requirement: 'all',
+  negate: false,
+});
+
+const allFlags = useStore($flags);
+const isReady = useStore($isReady);
+
+const isEnabled = computed(() => {
+  // Build flag keys array
+  const flagKeys: string[] = [];
+  if (props.flag) {
+    flagKeys.push(props.flag);
+  }
+  if (props.flags && Array.isArray(props.flags)) {
+    flagKeys.push(...props.flags);
+  }
+
+  // No flags specified
+  if (flagKeys.length === 0) {
+    return !props.negate;
+  }
+
+  // Evaluate flags
+  let enabled: boolean;
+
+  if (props.requirement === 'any') {
+    enabled = flagKeys.some((key) => allFlags.value[key] === true);
+  } else {
+    enabled = flagKeys.every((key) => allFlags.value[key] === true);
+  }
+
+  if (props.negate) {
+    enabled = !enabled;
+  }
+
+  return enabled;
+});
+</script>
+
+

package/dist/frameworks/vue/composables.d.ts

@@ -0,0 +1,56 @@
+import { Ref } from 'vue';
+
+/**
+ * Vue Composables for Toggly
+ */
+
+/**
+ * Hook to check if a feature flag is enabled
+ *
+ * @param flagKey - Feature flag key to check
+ * @param defaultValue - Default value if flag not found (default: false)
+ * @returns Object with enabled state and ready state
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const { enabled, isReady } = useFeatureFlag('new-dashboard');
+ * </script>
+ *
+ * <template>
+ *   <Loading v-if="!isReady" />
+ *   <NewDashboard v-else-if="enabled" />
+ *   <OldDashboard v-else />
+ * </template>
+ * ```
+ */
+declare function useFeatureFlag(flagKey: string, defaultValue?: boolean): {
+    enabled: Readonly<Ref<boolean>>;
+    isReady: Readonly<Ref<boolean>>;
+};
+/**
+ * Hook to check if multiple feature flags are enabled
+ *
+ * @param flagKeys - Array of feature flag keys to check
+ * @param requirement - 'all' or 'any' (default: 'all')
+ * @param negate - If true, negates the result (default: false)
+ * @returns Object with enabled state and ready state
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const { enabled } = useFeatureGate(['feature1', 'feature2'], 'any');
+ * </script>
+ *
+ * <template>
+ *   <NewFeatures v-if="enabled" />
+ *   <OldFeatures v-else />
+ * </template>
+ * ```
+ */
+declare function useFeatureGate(flagKeys: string[], requirement?: 'all' | 'any', negate?: boolean): {
+    enabled: Readonly<Ref<boolean>>;
+    isReady: Readonly<Ref<boolean>>;
+};
+
+export { useFeatureFlag, useFeatureGate };