Rename applyBlur to showBlurredChildren for semantic clarity

akcho · akcho · commit 428eb33efb3c · 2025-10-19T12:51:42.000-07:00
Breaking change: Rename the applyBlur prop to showBlurredChildren in both
PaywallGate and AuthGate components. The new name better conveys the prop's
purpose of controlling whether blurred children are shown behind the gate overlay.

Changes:
- Update prop name in PaywallGate and AuthGate TypeScript interfaces
- Update all documentation and examples to use showBlurredChildren
- Update demo app to use the new prop name
- Add migration notes to CHANGELOG
- Bump package version to 0.3.0
- Remove npm downloads badge from README files
diff --git a/README.md b/README.md
@@ -1,7 +1,6 @@
 # Milkie
 
 [![npm version](https://img.shields.io/npm/v/@milkie/react.svg)](https://www.npmjs.com/package/@milkie/react)
-[![npm downloads](https://img.shields.io/npm/dm/@milkie/react.svg)](https://www.npmjs.com/package/@milkie/react)
 [![license](https://img.shields.io/npm/l/@milkie/react.svg)](https://github.com/akcho/milkie/blob/main/LICENSE)
 
 > Drop-in paywall infrastructure for Next.js apps
diff --git a/demo/app/dashboard/billing/page.tsx b/demo/app/dashboard/billing/page.tsx
@@ -7,11 +7,13 @@ import { ImplementationTip } from "@/components/implementation-tip";
 import { PageHeader } from "@/components/page-header";
 import { useCheckout } from "@/hooks/use-checkout";
 import { useCancelSubscription } from "@/hooks/use-cancel-subscription";
+import { useIsMobile } from "@/hooks/use-is-mobile";
 
 export default function BillingPage() {
   const { status, email, hasAccess, checkSubscription } = usePaywall();
   const { startCheckout, isCheckingOut } = useCheckout();
   const { cancelSubscription, isCanceling } = useCancelSubscription();
+  const isMobile = useIsMobile();
 
   const handleSubscribe = () => {
     if (!email) return;
@@ -24,7 +26,7 @@ export default function BillingPage() {
   };
 
   return (
-    <AuthGate>
+    <AuthGate showBlurredChildren={!isMobile}>
       <div className="space-y-8 max-w-3xl mx-auto">
         <PageHeader
           title="Billing"
diff --git a/demo/app/dashboard/page.tsx b/demo/app/dashboard/page.tsx
@@ -31,7 +31,7 @@ export default function DashboardPage() {
   const isMobile = useIsMobile();
 
   return (
-    <PaywallGate applyBlur={!isMobile}>
+    <PaywallGate showBlurredChildren={!isMobile}>
       <div className="space-y-8 max-w-5xl mx-auto">
         <PageHeader
           title="Dashboard"
diff --git a/demo/app/dashboard/settings/page.tsx b/demo/app/dashboard/settings/page.tsx
@@ -5,12 +5,14 @@ import { ImplementationTip } from "@/components/implementation-tip";
 import { PageHeader } from "@/components/page-header";
 import { AccountSettingsCard } from "./components/account-settings-card";
 import { useSettings } from "@/hooks/use-settings";
+import { useIsMobile } from "@/hooks/use-is-mobile";
 
 export default function SettingsPage() {
   const { isSaving, isSigningOut, handleSave, handleSignOut } = useSettings();
+  const isMobile = useIsMobile();
 
   return (
-    <AuthGate>
+    <AuthGate showBlurredChildren={!isMobile}>
       <div className="space-y-8 max-w-3xl mx-auto">
         <PageHeader
           title="Settings"
diff --git a/demo/app/metered/components/article-view.tsx b/demo/app/metered/components/article-view.tsx
@@ -56,7 +56,7 @@ export function ArticleView({ article, canView, onBack }: ArticleViewProps) {
                 subtitle="Subscribe for unlimited access to all premium content"
                 subscribeButtonText="Get unlimited access"
                 overlayClassName="py-8"
-                applyBlur={!isMobile}
+                showBlurredChildren={!isMobile}
                 position="top"
               >
                 <ArticleContent />
diff --git a/docs/AUTH_INTEGRATION.md b/docs/AUTH_INTEGRATION.md
@@ -223,7 +223,7 @@ Both components support extensive customization:
   subscribeButtonText="Subscribe now"
   signInUrl="/signin"
   showBranding={true} // Show "Powered by milkie" footer
-  applyBlur={true} // Show blurred content preview
+  showBlurredChildren={true} // Show blurred content preview
   overlayClassName="pt-8" // Custom overlay positioning
   onSignIn={() => {
     // Custom sign-in logic
diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -67,10 +67,10 @@ PaywallGate renders your protected content in the background with a `blur-sm` ef
 
 ### Q: Can I disable the blur effect?
 
-Yes! Use `applyBlur={false}`:
+Yes! Use `showBlurredChildren={false}`:
 
 ```tsx
-<PaywallGate applyBlur={false}>
+<PaywallGate showBlurredChildren={false}>
   <PremiumContent /> {/* Paywall card shown inline without blur */}
 </PaywallGate>
 ```
diff --git a/docs/reference/best-practices.md b/docs/reference/best-practices.md
@@ -298,7 +298,7 @@ export default function ArticlePage() {
   return (
     <PaywallGate
       position="top"
-      applyBlur={!isMobile}
+      showBlurredChildren={!isMobile}
     >
       <LongNewsArticle />
     </PaywallGate>
diff --git a/docs/reference/customization.md b/docs/reference/customization.md
@@ -22,7 +22,7 @@ All available props for customizing the paywall experience:
   onToast={(message, type) => toast[type](message)}
   // Visual customization
   showBranding={false}
-  applyBlur={false}
+  showBlurredChildren={false}
   overlayClassName="pt-8"
   position="top"
 >
@@ -52,12 +52,12 @@ All available props for customizing the paywall experience:
 
 ### Visual Props
 
-| Prop               | Type                  | Default    | Description                             |
-| ------------------ | --------------------- | ---------- | --------------------------------------- |
-| `showBranding`     | `boolean`             | true       | Show "Powered by milkie" footer         |
-| `applyBlur`        | `boolean`             | true       | Show blurred content preview            |
-| `overlayClassName` | `string`              | ""         | Custom className for overlay element    |
-| `position`         | `"center" \| "top"`   | `"center"` | Vertical position of paywall card       |
+| Prop                   | Type                  | Default    | Description                             |
+| ---------------------- | --------------------- | ---------- | --------------------------------------- |
+| `showBranding`         | `boolean`             | true       | Show "Powered by milkie" footer         |
+| `showBlurredChildren`  | `boolean`             | true       | Show blurred content preview            |
+| `overlayClassName`     | `string`              | ""         | Custom className for overlay element    |
+| `position`             | `"center" \| "top"`   | `"center"` | Vertical position of paywall card       |
 
 ## Visual Design Features
 
@@ -81,7 +81,7 @@ PaywallGate renders protected content behind the overlay with a blur effect:
 **Disable blur:**
 
 ```tsx
-<PaywallGate applyBlur={false}>
+<PaywallGate showBlurredChildren={false}>
   <PremiumContent /> {/* Paywall card shown inline without blur */}
 </PaywallGate>
 ```
@@ -304,7 +304,7 @@ export default function ArticlePage() {
   return (
     <PaywallGate
       position="top"
-      applyBlur={!isMobile}
+      showBlurredChildren={!isMobile}
     >
       <LongNewsArticle />
     </PaywallGate>
diff --git a/packages/react/CHANGELOG.md b/packages/react/CHANGELOG.md
@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2025-10-19
+
+### Changed
+
+- Enhanced `AuthGate` documentation in package README with complete props list including `showBlurredChildren`, `onSignIn`, and `signInButtonText`
+- Added inline card example to AuthGate component README
+
+---
+
+## [0.2.0] - 2025-10-19
+
+### Breaking Changes
+
+- **BREAKING:** Renamed `applyBlur` prop to `showBlurredChildren` in both `PaywallGate` and `AuthGate` components for better semantic clarity
+  - Migration: Replace all instances of `applyBlur={value}` with `showBlurredChildren={value}` in your code
+  - The prop controls whether blurred content is shown behind the gate overlay (default: true)
+  - This change affects both `PaywallGate` and `AuthGate` components
+
+### Changed
+
+- Updated all documentation and examples to use `showBlurredChildren` prop
+- Updated TypeScript definitions to reflect the new prop name
+
+---
+
 ## [0.1.0] - 2025-10-19
 
 Initial release of Milkie - Stripe-powered paywall SDK for Next.js apps.
@@ -20,7 +45,7 @@ Initial release of Milkie - Stripe-powered paywall SDK for Next.js apps.
 - Error handling with retry capability
 - Loading states with skeleton loaders
 - Optional toast notification integration
-- `applyBlur` prop to control blur effect (enabled by default)
+- `showBlurredChildren` prop to control blur effect (enabled by default)
 - `position` prop for vertical card positioning ("center" or "top")
 - Full TypeScript support with comprehensive JSDoc documentation
 
diff --git a/packages/react/README.md b/packages/react/README.md
@@ -1,7 +1,6 @@
 # @milkie/react
 
 [![npm version](https://img.shields.io/npm/v/@milkie/react.svg)](https://www.npmjs.com/package/@milkie/react)
-[![npm downloads](https://img.shields.io/npm/dm/@milkie/react.svg)](https://www.npmjs.com/package/@milkie/react)
 [![license](https://img.shields.io/npm/l/@milkie/react.svg)](https://github.com/akcho/milkie/blob/main/LICENSE)
 
 > Stripe-powered paywall SDK for Next.js apps
@@ -137,7 +136,7 @@ Gate content behind a subscription paywall with built-in checkout flow.
 - `subscribeButtonText?: string` - Subscribe button text
 - `showBranding?: boolean` - Show "Powered by milkie" (default: true)
 - `onSignIn?: () => void` - Custom sign-in handler
-- `applyBlur?: boolean` - Show blurred content preview (default: true)
+- `showBlurredChildren?: boolean` - Show blurred content preview (default: true)
 - `position?: "center" | "top"` - Vertical card position (default: "center")
 
 **Basic usage:**
@@ -178,8 +177,11 @@ Gate content that requires sign-in but NOT an active subscription.
 
 - `children: ReactNode` - Content requiring authentication
 - `signInUrl?: string` - Where to redirect for sign-in (default: `/signin`)
+- `onSignIn?: () => void` - Custom sign-in handler
 - `title?: string` - Sign-in card title
 - `subtitle?: string` - Sign-in card subtitle
+- `signInButtonText?: string` - Sign-in button text
+- `showBlurredChildren?: boolean` - Show blurred content preview (default: true)
 - `position?: "center" | "top"` - Vertical card position (default: "center")
 
 **Usage:**
diff --git a/packages/react/package.json b/packages/react/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@milkie/react",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Drop-in paywall infrastructure for Next.js apps",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
diff --git a/packages/react/src/auth-gate/README.md b/packages/react/src/auth-gate/README.md
@@ -48,6 +48,7 @@ All props are optional except `children`. Key props:
 - `signInUrl` - URL to redirect for sign-in (default: `/signin`)
 - `onSignIn` - Custom sign-in handler
 - `signInButtonText` - Customize button label
+- `showBlurredChildren` - Show blurred content preview (default: true)
 - `overlayClassName` - Custom Tailwind classes for card positioning
 - `position` - Vertical card position: `"center"` (default) or `"top"`
 
@@ -142,6 +143,16 @@ import { signIn } from "next-auth/react";
 </AuthGate>;
 ```
 
+### 6. Inline Card (No Blur)
+
+Show the auth card inline without blurred content:
+
+```tsx
+<AuthGate showBlurredChildren={false}>
+  <ProtectedContent /> {/* Auth card shown inline without blur */}
+</AuthGate>
+```
+
 ### 7. Layout-Level Gating
 
 ```tsx
diff --git a/packages/react/src/auth-gate/index.tsx b/packages/react/src/auth-gate/index.tsx
@@ -17,6 +17,7 @@ import { handleSignInRedirect } from "../utils";
  * @property {string} [title="Sign in required"] - Heading text displayed on the authentication overlay
  * @property {string} [subtitle="Please sign in to access this content."] - Subtitle text displayed on the authentication overlay
  * @property {string} [signInButtonText="Sign in"] - Label for the sign-in button
+ * @property {boolean} [showBlurredChildren=true] - When true, shows blurred content preview behind auth card; when false, shows auth card inline
  * @property {string} [overlayClassName] - Optional className to apply to the overlay element (e.g., "pt-8" to add top padding)
  * @property {"center" | "top"} [position="center"] - Vertical position of the auth card: "center" for middle, "top" for top alignment
  *
@@ -53,6 +54,7 @@ interface AuthGateProps {
   title?: string;
   subtitle?: string;
   signInButtonText?: string;
+  showBlurredChildren?: boolean;
   overlayClassName?: string;
   position?: "center" | "top";
 }
@@ -120,6 +122,7 @@ export function AuthGate({
   title = "Sign in required",
   subtitle = "Please sign in to access this content.",
   signInButtonText = "Sign in",
+  showBlurredChildren = true,
   overlayClassName,
   position = "center",
 }: AuthGateProps) {
@@ -145,16 +148,24 @@ export function AuthGate({
     }
   };
 
+  const authCard = (
+    <AuthCard
+      title={title}
+      subtitle={subtitle}
+      signInButtonText={signInButtonText}
+      onSignIn={handleSignIn}
+    />
+  );
+
+  // When blur is disabled, just show the auth card inline
+  if (!showBlurredChildren) {
+    return <div className="py-8">{authCard}</div>;
+  }
+
+  // Default: show with blur effect
   return (
     <OverlayGrid
-      overlay={
-        <AuthCard
-          title={title}
-          subtitle={subtitle}
-          signInButtonText={signInButtonText}
-          onSignIn={handleSignIn}
-        />
-      }
+      overlay={authCard}
       overlayClassName={overlayClassName}
       position={position}
     >
diff --git a/packages/react/src/paywall-gate/README.md b/packages/react/src/paywall-gate/README.md
@@ -12,7 +12,7 @@ The `PaywallGate` component is the primary building block for implementing subsc
 - **Built-in Checkout Flow**: Stripe checkout integration out of the box
 - **Flexible Display Modes**:
   - Blurred content preview (default)
-  - Inline paywall card (with `applyBlur={false}`)
+  - Inline paywall card (with `showBlurredChildren={false}`)
   - Fully custom UI (with `customUi` prop)
 - **Smart Error Handling**: Network errors, checkout failures, with retry capability
 - **Loading States**: Skeleton loaders while checking subscription status
@@ -49,7 +49,7 @@ All props are optional except `children`. Key props:
 - `children` - Premium content to protect (required)
 - `title`, `subtitle` - Customize paywall messaging
 - `customUi` - Replace default UI entirely
-- `applyBlur` - Show blurred content preview (default: true)
+- `showBlurredChildren` - Show blurred content preview (default: true)
 - `onCheckout` - Custom checkout handler
 - `onToast` - Toast notification callback
 - `showBranding` - Toggle "Powered by milkie" footer
@@ -121,7 +121,7 @@ import { signIn } from "next-auth/react";
   icon={<Crown className="h-12 w-12 text-yellow-500" />}
   title="Premium Members Only"
   onSignIn={() => signIn()}
-  applyBlur={false} // No blur effect
+  showBlurredChildren={false} // No blur effect
 >
   <PremiumContent />
 </PaywallGate>;
diff --git a/packages/react/src/paywall-gate/index.tsx b/packages/react/src/paywall-gate/index.tsx
@@ -24,7 +24,7 @@ import { handleCheckoutProcess, redirectToCheckout } from "./utils";
  * @property {(email: string) => Promise<{ url: string }>} [onCheckout] - Custom checkout handler that returns a Stripe checkout URL
  * @property {(message: string, type: "success" | "error") => void} [onToast] - Callback to display toast notifications for checkout errors
  * @property {boolean} [showBranding=true] - Whether to show "Powered by milkie" footer in the paywall card
- * @property {boolean} [applyBlur=true] - When true, shows blurred content preview behind paywall card
+ * @property {boolean} [showBlurredChildren=true] - When true, shows blurred content preview behind paywall card
  * @property {string} [overlayClassName] - Optional className to apply to the overlay element (e.g., "pt-8" to add top padding)
  * @property {"center" | "top"} [position="center"] - Vertical position of the paywall card: "center" for middle, "top" for top alignment
  *
@@ -46,7 +46,7 @@ import { handleCheckoutProcess, redirectToCheckout } from "./utils";
  *
  * @example
  * // Without blur effect
- * <PaywallGate applyBlur={false}>
+ * <PaywallGate showBlurredChildren={false}>
  *   <PremiumContent />
  * </PaywallGate>
  *
@@ -77,7 +77,7 @@ interface PaywallGateProps {
   onCheckout?: (email: string) => Promise<{ url: string }>;
   onToast?: (message: string, type: "success" | "error") => void;
   showBranding?: boolean;
-  applyBlur?: boolean;
+  showBlurredChildren?: boolean;
   overlayClassName?: string;
   position?: "center" | "top";
 }
@@ -152,7 +152,7 @@ export function PaywallGate({
   onCheckout,
   onToast,
   showBranding = true,
-  applyBlur = true,
+  showBlurredChildren = true,
   overlayClassName,
   position = "center",
 }: PaywallGateProps) {
@@ -225,7 +225,7 @@ export function PaywallGate({
   );
 
   // When blur is disabled, just show the paywall card inline
-  if (!applyBlur) {
+  if (!showBlurredChildren) {
     return <div className="py-8">{paywallCard}</div>;
   }
 

Original file line number	Diff line number	Diff line change
`@@ -56,7 +56,7 @@ export function ArticleView({ article, canView, onBack }: ArticleViewProps) {`
`56`	`56`	`subtitle="Subscribe for unlimited access to all premium content"`
`57`	`57`	`subscribeButtonText="Get unlimited access"`
`58`	`58`	`overlayClassName="py-8"`
`59`		`- applyBlur={!isMobile}`
	`59`	`+ showBlurredChildren={!isMobile}`
`60`	`60`	`position="top"`
`61`	`61`	`>`
`62`	`62`	`<ArticleContent />`
Original file line number	Diff line number	Diff line change
`@@ -298,7 +298,7 @@ export default function ArticlePage() {`
`298`	`298`	`return (`
`299`	`299`	`<PaywallGate`
`300`	`300`	`position="top"`
`301`		`- applyBlur={!isMobile}`
	`301`	`+ showBlurredChildren={!isMobile}`
`302`	`302`	`>`
`303`	`303`	`<LongNewsArticle />`
`304`	`304`	`</PaywallGate>`