npm - @neynar/ui - Versions diffs - 0.3.1 → 0.5.0 - Mend

@neynar/ui 0.3.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1860) hide show

package/src/components/neynar/color-mode/color-mode-initializer.tsx ADDED Viewed

@@ -0,0 +1,78 @@
+"use client";
+import { useColorMode } from "./use-color-mode";
+/**
+ * Color mode initialization script (internal).
+ *
+ * For Vite/static HTML apps, copy this script into your index.html <head>.
+ * See docs/integrations/vite.md for the full script to copy.
+ */
+const colorModeScript = `(function() {
+  try {
+    var cookie = document.cookie.match(/color-mode=([^;]*)/) || document.cookie.match(/theme=([^;]*)/);
+    var stored = cookie ? JSON.parse(decodeURIComponent(cookie[1])) : null;
+    var preference = stored ? stored.preference : 'system';
+    var mode = preference === 'system'
+      ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
+      : preference;
+    if (mode === 'dark') {
+      document.documentElement.classList.add('dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+    }
+    document.documentElement.style.colorScheme = mode;
+  } catch (e) {
+    document.documentElement.classList.remove('dark');
+    document.documentElement.style.colorScheme = 'light';
+  }
+})();`;
+/**
+ * ColorModeInitializer - Prevents flash of unstyled content (FOUC) during color mode initialization
+ *
+ * A React component that injects the color mode initialization script into the page.
+ * Use this in SSR frameworks like Next.js where React controls the document.
+ *
+ * **For Vite/static HTML apps:** This component won't prevent FOUC because React
+ * renders after first paint. Instead, copy the initialization script directly into
+ * your `index.html` `<head>`. See the Vite integration guide for the full script.
+ *
+ * @component
+ * @example Next.js App Router
+ * ```tsx
+ * // app/layout.tsx
+ * import { ColorModeInitializer } from "@neynar/ui/color-mode";
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html lang="en" suppressHydrationWarning>
+ *       <head>
+ *         <ColorModeInitializer />
+ *       </head>
+ *       <body>{children}</body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ *
+ * @example Vite - copy script to index.html instead
+ * ```html
+ * <!-- See docs/integrations/vite.md for the full script to copy -->
+ * <head>
+ *   <script>
+ *     (function() {
+ *       // ... color mode initialization script
+ *     })();
+ *   </script>
+ * </head>
+ * ```
+ *
+ * @see {@link useColorMode} - Hook for runtime color mode management
+ * @see {@link ColorModeToggle} - UI component for user color mode switching
+ * @since 1.0.0
+ */
+export function ColorModeInitializer() {
+  useColorMode();
+  return <script dangerouslySetInnerHTML={{ __html: colorModeScript }} />;
+}

package/src/components/neynar/color-mode/color-mode-toggle.tsx ADDED Viewed

@@ -0,0 +1,215 @@
+"use client";
+import { useEffect, useState } from "react";
+import { Monitor, Moon, Sun } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { useColorMode } from "./use-color-mode";
+import { cn } from "@/lib/utils";
+// Map regular sizes to icon sizes for when showLabel is false
+const iconSizeMap = {
+  xs: "icon-xs",
+  sm: "icon-sm",
+  default: "icon",
+  lg: "icon-lg",
+} as const;
+// Icon sizes that scale with button size
+const iconClassMap = {
+  xs: "size-3",
+  sm: "size-3.5",
+  default: "size-4",
+  lg: "size-5",
+} as const;
+// Text sizes that scale with button size
+const textClassMap = {
+  xs: "text-xs",
+  sm: "text-sm",
+  default: "text-base",
+  lg: "text-lg",
+} as const;
+type ColorModeToggleSize = "xs" | "sm" | "default" | "lg";
+type ColorModeToggleProps = {
+  /**
+   * Button size - when showLabel is false, renders as a square icon button
+   * @default "default"
+   */
+  size?: ColorModeToggleSize;
+  /**
+   * Whether to show the current color mode name as text next to the icon
+   * @default false
+   */
+  showLabel?: boolean;
+  /**
+   * Alignment of the dropdown menu relative to the trigger button
+   * @default "end"
+   */
+  align?: "start" | "center" | "end";
+} & Omit<React.ComponentProps<typeof Button>, "size">;
+/**
+ * ColorModeToggle - A zero-configuration color mode switcher with system, light, and dark modes
+ *
+ * A completely self-contained color mode toggle component that provides an intuitive dropdown
+ * interface for switching between system preference, light mode, and dark mode. Works
+ * immediately without any provider setup, context configuration, or additional dependencies.
+ *
+ * Built on top of Base UI components (Button + DropdownMenu) with the Neynar useColorMode
+ * hook for state management. Handles color mode persistence via cookies, system preference
+ * detection, real-time system changes, and synchronization across multiple instances.
+ *
+ * **Zero Configuration Design:**
+ * Just import and use - no providers, no setup, no configuration required. The component
+ * handles all color mode management internally and provides a complete solution out of the box.
+ *
+ * @example Basic usage (most common - icon button)
+ * ```tsx
+ * import { ColorModeToggle } from "@neynar/ui/color-mode";
+ *
+ * // Just drop it in! Works immediately with zero setup
+ * function Header() {
+ *   return (
+ *     <header className="flex items-center justify-between p-4">
+ *       <Logo />
+ *       <ColorModeToggle />
+ *     </header>
+ *   );
+ * }
+ * ```
+ *
+ * @example With text labels for better UX
+ * ```tsx
+ * // Show current color mode name next to icon
+ * <ColorModeToggle size="default" showLabel />
+ *
+ * // In a settings panel
+ * <div className="space-y-4">
+ *   <h3>Appearance</h3>
+ *   <div className="flex items-center justify-between">
+ *     <span>Color Mode</span>
+ *     <ColorModeToggle size="sm" showLabel />
+ *   </div>
+ * </div>
+ * ```
+ *
+ * @example Different visual variants
+ * ```tsx
+ * // Ghost button for minimalist toolbars
+ * <ColorModeToggle variant="ghost" />
+ *
+ * // Secondary style for subtle integration
+ * <ColorModeToggle variant="secondary" size="sm" />
+ *
+ * // Outline style (default) for clear boundaries
+ * <ColorModeToggle variant="outline" size="lg" />
+ * ```
+ *
+ * @param variant - Visual style variant inherited from Button component (default: "outline")
+ * @param size - Button size: xs, sm, default, lg. Renders as icon button when showLabel is false (default: "default")
+ * @param className - Additional CSS classes for custom styling
+ * @param showLabel - Whether to show color mode name text. When false, renders as square icon button (default: false)
+ * @param align - Dropdown menu alignment relative to trigger button (default: "end")
+ *
+ * @features
+ * - **Zero Configuration**: Import and use immediately - no setup required
+ * - **System Detection**: Automatically follows OS dark/light preference changes
+ * - **Perfect Persistence**: Color mode choice saved via cookies for SSR compatibility
+ * - **Multi-Instance Sync**: Multiple toggles stay perfectly synchronized
+ * - **Real-Time Updates**: Responds to system color mode changes while app is running
+ * - **Smooth Transitions**: CSS-based mode switching with no flash of wrong content
+ * - **Accessibility First**: Full keyboard navigation and screen reader support
+ * - **Touch Optimized**: Works perfectly on mobile and tablet devices
+ * - **Framework Agnostic**: Works with Next.js, Vite, Create React App, etc.
+ *
+ * @accessibility
+ * - **Keyboard Navigation**: Full support for Enter, Space, and Arrow keys
+ * - **Screen Reader Support**: Proper ARIA labels and role announcements
+ * - **Focus Management**: Visible focus indicators meeting WCAG 2.1 AA standards
+ * - **State Communication**: Current selection clearly indicated with checkmarks
+ *
+ * @see {@link useColorMode} - The underlying color mode management hook with event-driven architecture
+ * @see {@link ColorModeScript} - Component for FOUC prevention (required in root layout)
+ * @since 1.0.0
+ */
+function ColorModeToggle({
+  variant = "outline",
+  size = "default",
+  className,
+  showLabel = false,
+  align = "end",
+  ...props
+}: ColorModeToggleProps) {
+  // Use icon size when no label, regular size when label is shown
+  const buttonSize = showLabel ? size : iconSizeMap[size];
+  const iconClass = iconClassMap[size];
+  const textClass = textClassMap[size];
+  const { preference, setPreference } = useColorMode();
+  // Track hydration to prevent mismatch between server/client rendering.
+  // This runs once after hydration to signal we can show client-specific values.
+  const [mounted, setMounted] = useState(false);
+  // eslint-disable-next-line react-hooks/set-state-in-effect -- Intentional: standard hydration detection pattern
+  useEffect(() => setMounted(true), []);
+  // Simple icons and labels - no configuration needed
+  const items = [
+    { mode: "system" as const, Icon: Monitor, label: "System" },
+    { mode: "light" as const, Icon: Sun, label: "Light" },
+    { mode: "dark" as const, Icon: Moon, label: "Dark" },
+  ];
+  // Get current item based on preference, not resolved mode
+  // Before hydration, always show "system" to match server render
+  const currentItem = mounted
+    ? items.find((item) => item.mode === preference) || items[0]
+    : items[0]; // Always "system" on server
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger
+        render={
+          <Button
+            variant={variant}
+            size={buttonSize}
+            className={cn(className)}
+            suppressHydrationWarning
+            {...props}
+          >
+            {currentItem && <currentItem.Icon className={iconClass} />}
+            {showLabel && (
+              <span className={textClass}>{currentItem?.label}</span>
+            )}
+            <span className="sr-only">Toggle color mode</span>
+          </Button>
+        }
+      />
+      <DropdownMenuContent align={align}>
+        {items.map((item) => (
+          <DropdownMenuItem
+            key={item.mode}
+            onClick={() => setPreference(item.mode)}
+            className="flex items-center gap-2"
+          >
+            <item.Icon className="size-4" />
+            <span>{item.label}</span>
+            {preference === item.mode && (
+              <span className="ml-auto text-xs opacity-60">✓</span>
+            )}
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+export { ColorModeToggle, type ColorModeToggleProps, type ColorModeToggleSize };

package/src/components/neynar/color-mode/index.ts ADDED Viewed

@@ -0,0 +1,3 @@
+export { ColorModeInitializer } from "./color-mode-initializer";
+export { ColorModeToggle } from "./color-mode-toggle";
+export { useColorMode, type ColorModePreference } from "./use-color-mode";

package/src/components/neynar/color-mode/stories/color-mode-toggle.stories.tsx ADDED Viewed

@@ -0,0 +1,342 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { BellIcon, SearchIcon, UserIcon, MenuIcon } from "lucide-react";
+import { ColorModeToggle } from "../color-mode-toggle";
+import { Button } from "@/components/ui/button";
+const meta: Meta<typeof ColorModeToggle> = {
+  title: "Theming/Components/ColorModeToggle",
+  component: ColorModeToggle,
+  parameters: {
+    layout: "centered",
+  },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["default", "outline", "secondary", "ghost"],
+      description: "Visual style variant",
+    },
+    size: {
+      control: "select",
+      options: ["xs", "sm", "default", "lg"],
+      description: "Button size (renders as icon when showLabel is false)",
+    },
+    showLabel: {
+      control: "boolean",
+      description: "Show color mode name label",
+    },
+    align: {
+      control: "select",
+      options: ["start", "center", "end"],
+      description: "Dropdown menu alignment",
+    },
+  },
+};
+export default meta;
+type Story = StoryObj<typeof ColorModeToggle>;
+/**
+ * Dashboard Header - A realistic scenario showing ColorModeToggle
+ * in a typical application header with other controls.
+ */
+export const InContext: Story = {
+  parameters: {
+    layout: "padded",
+  },
+  render: () => {
+    function DashboardHeader() {
+      return (
+        <div className="w-full max-w-4xl space-y-6">
+          {/* Main Header */}
+          <header className="border-border bg-card flex items-center justify-between rounded-lg border p-4">
+            <div className="flex items-center gap-4">
+              <div className="bg-primary text-primary-foreground flex size-8 items-center justify-center rounded-lg font-bold">
+                N
+              </div>
+              <span className="font-semibold">Neynar Dashboard</span>
+            </div>
+            <div className="flex items-center gap-2">
+              <Button variant="ghost" size="icon">
+                <SearchIcon className="size-4" />
+              </Button>
+              <Button variant="ghost" size="icon">
+                <BellIcon className="size-4" />
+              </Button>
+              <ColorModeToggle />
+              <Button variant="ghost" size="icon">
+                <UserIcon className="size-4" />
+              </Button>
+            </div>
+          </header>
+          {/* Settings Panel Example */}
+          <div className="border-border bg-card rounded-lg border p-6 space-y-6">
+            <div>
+              <h2 className="text-lg font-semibold">Appearance Settings</h2>
+              <p className="text-muted-foreground text-sm">
+                Customize how Neynar looks on your device.
+              </p>
+            </div>
+            <div className="space-y-4">
+              <div className="flex items-center justify-between py-3 border-b">
+                <div>
+                  <p className="font-medium">Color Mode</p>
+                  <p className="text-muted-foreground text-sm">
+                    Select your preferred color scheme.
+                  </p>
+                </div>
+                <ColorModeToggle size="default" showLabel />
+              </div>
+              <div className="flex items-center justify-between py-3 border-b">
+                <div>
+                  <p className="font-medium">Compact Mode</p>
+                  <p className="text-muted-foreground text-sm">
+                    Reduce spacing for denser layouts.
+                  </p>
+                </div>
+                <Button variant="outline" size="sm">
+                  Enable
+                </Button>
+              </div>
+            </div>
+          </div>
+          {/* Mobile Header Example */}
+          <div className="border-border bg-card rounded-lg border p-4">
+            <div className="flex items-center justify-between">
+              <Button variant="ghost" size="icon">
+                <MenuIcon className="size-5" />
+              </Button>
+              <span className="font-semibold">Mobile View</span>
+              <div className="flex items-center gap-1">
+                <ColorModeToggle variant="ghost" size="sm" />
+                <Button variant="ghost" size="icon-sm">
+                  <UserIcon className="size-4" />
+                </Button>
+              </div>
+            </div>
+          </div>
+        </div>
+      );
+    }
+    return <DashboardHeader />;
+  },
+};
+/**
+ * Complete design system reference showing all ColorModeToggle variants and configurations.
+ */
+export const Variants: Story = {
+  parameters: {
+    layout: "padded",
+  },
+  render: () => (
+    <div className="w-full max-w-4xl space-y-10">
+      {/* Visual Variants */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Visual Variants</h3>
+          <p className="text-muted-foreground text-sm">
+            Different button styles for different contexts.
+          </p>
+        </div>
+        <div className="flex flex-wrap items-center gap-4">
+          <div className="text-center space-y-2">
+            <ColorModeToggle variant="outline" />
+            <p className="text-muted-foreground text-xs">outline (default)</p>
+          </div>
+          <div className="text-center space-y-2">
+            <ColorModeToggle variant="default" />
+            <p className="text-muted-foreground text-xs">default</p>
+          </div>
+          <div className="text-center space-y-2">
+            <ColorModeToggle variant="secondary" />
+            <p className="text-muted-foreground text-xs">secondary</p>
+          </div>
+          <div className="text-center space-y-2">
+            <ColorModeToggle variant="ghost" />
+            <p className="text-muted-foreground text-xs">ghost</p>
+          </div>
+        </div>
+      </section>
+      {/* Sizes */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Sizes</h3>
+          <p className="text-muted-foreground text-sm">
+            All sizes render as icon buttons by default (no label).
+          </p>
+        </div>
+        <div className="flex flex-wrap items-center gap-4">
+          <div className="text-center space-y-2">
+            <ColorModeToggle size="xs" />
+            <p className="text-muted-foreground text-xs">xs</p>
+          </div>
+          <div className="text-center space-y-2">
+            <ColorModeToggle size="sm" />
+            <p className="text-muted-foreground text-xs">sm</p>
+          </div>
+          <div className="text-center space-y-2">
+            <ColorModeToggle size="default" />
+            <p className="text-muted-foreground text-xs">default</p>
+          </div>
+          <div className="text-center space-y-2">
+            <ColorModeToggle size="lg" />
+            <p className="text-muted-foreground text-xs">lg</p>
+          </div>
+        </div>
+      </section>
+      {/* With Labels */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">With Labels</h3>
+          <p className="text-muted-foreground text-sm">
+            Show current color mode name for better UX in settings panels.
+          </p>
+        </div>
+        <div className="flex flex-wrap items-center gap-4">
+          <div className="text-center space-y-2">
+            <ColorModeToggle size="sm" showLabel />
+            <p className="text-muted-foreground text-xs">sm + showLabel</p>
+          </div>
+          <div className="text-center space-y-2">
+            <ColorModeToggle size="default" showLabel />
+            <p className="text-muted-foreground text-xs">default + showLabel</p>
+          </div>
+          <div className="text-center space-y-2">
+            <ColorModeToggle size="lg" showLabel />
+            <p className="text-muted-foreground text-xs">lg + showLabel</p>
+          </div>
+        </div>
+      </section>
+      {/* Menu Alignment */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Menu Alignment</h3>
+          <p className="text-muted-foreground text-sm">
+            Control dropdown position relative to trigger.
+          </p>
+        </div>
+        <div className="flex justify-between max-w-md">
+          <div className="text-center space-y-2">
+            <ColorModeToggle align="start" />
+            <p className="text-muted-foreground text-xs">start</p>
+          </div>
+          <div className="text-center space-y-2">
+            <ColorModeToggle align="center" />
+            <p className="text-muted-foreground text-xs">center</p>
+          </div>
+          <div className="text-center space-y-2">
+            <ColorModeToggle align="end" />
+            <p className="text-muted-foreground text-xs">end (default)</p>
+          </div>
+        </div>
+      </section>
+      {/* Common Use Cases */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Common Use Cases</h3>
+          <p className="text-muted-foreground text-sm">
+            Recommended configurations for typical scenarios.
+          </p>
+        </div>
+        <div className="space-y-4">
+          <div className="border rounded-lg p-4 flex items-center justify-between">
+            <div>
+              <p className="font-medium">Header / Toolbar</p>
+              <p className="text-muted-foreground text-sm">
+                Compact icon button
+              </p>
+            </div>
+            <div className="flex items-center gap-2 bg-muted/50 rounded-lg p-2">
+              <Button variant="ghost" size="icon-sm">
+                <SearchIcon className="size-4" />
+              </Button>
+              <ColorModeToggle variant="ghost" size="sm" />
+              <Button variant="ghost" size="icon-sm">
+                <UserIcon className="size-4" />
+              </Button>
+            </div>
+          </div>
+          <div className="border rounded-lg p-4 flex items-center justify-between">
+            <div>
+              <p className="font-medium">Settings Panel</p>
+              <p className="text-muted-foreground text-sm">
+                Button with label for clarity
+              </p>
+            </div>
+            <ColorModeToggle variant="outline" showLabel />
+          </div>
+          <div className="border rounded-lg p-4 flex items-center justify-between">
+            <div>
+              <p className="font-medium">Floating Action</p>
+              <p className="text-muted-foreground text-sm">
+                Prominent standalone button
+              </p>
+            </div>
+            <ColorModeToggle variant="default" />
+          </div>
+        </div>
+      </section>
+      {/* Feature Highlights */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Features</h3>
+          <p className="text-muted-foreground text-sm">
+            Built-in capabilities that work automatically.
+          </p>
+        </div>
+        <div className="grid md:grid-cols-2 gap-4">
+          <div className="border rounded-lg p-4">
+            <p className="font-medium">Zero Configuration</p>
+            <p className="text-muted-foreground text-sm">
+              Just import and use - no providers or setup required.
+            </p>
+          </div>
+          <div className="border rounded-lg p-4">
+            <p className="font-medium">System Detection</p>
+            <p className="text-muted-foreground text-sm">
+              Follows OS dark/light preference automatically.
+            </p>
+          </div>
+          <div className="border rounded-lg p-4">
+            <p className="font-medium">Cookie Persistence</p>
+            <p className="text-muted-foreground text-sm">
+              Color mode choice saved for SSR compatibility.
+            </p>
+          </div>
+          <div className="border rounded-lg p-4">
+            <p className="font-medium">Multi-Instance Sync</p>
+            <p className="text-muted-foreground text-sm">
+              Multiple toggles stay perfectly synchronized.
+            </p>
+          </div>
+        </div>
+      </section>
+    </div>
+  ),
+};
+/**
+ * Interactive playground for testing ColorModeToggle props.
+ */
+export const Interactive: Story = {
+  args: {
+    variant: "outline",
+    size: "default",
+    showLabel: false,
+    align: "end",
+  },
+};