@nikala-ui/core 0.0.0-nightly.bb5956a

package/src/registry/index.ts

@@ -0,0 +1,50 @@
+// src/registry/index.ts
+
+/**
+ * Represents a single file within a component registry item.
+ */
+export interface RegistryFile {
+  /** The target relative path where the file will be placed in the user's project (e.g., "ui/button.tsx") */
+  path: string;
+  /** The full raw text content of the file */
+  content: string;
+  /** The category type of the file */
+  type: "registry:ui" | "registry:util" | "registry:hook";
+}
+
+/**
+ * Represents the complete manifest structure for a single Nikala UI component.
+ */
+export interface RegistryItem {
+  /** The unique identifier name of the component (e.g., "button") */
+  name: string;
+  /** Display title for CLI prompts and documentation */
+  title: string;
+  /** Short summary describing the component */
+  description: string;
+  /** Component category type */
+  type: "registry:ui";
+  /** Required NPM dependencies to be installed automatically (e.g., ["clsx", "tailwind-merge"]) */
+  dependencies?: string[];
+  /** Internal Nikala UI component dependencies required by this component (e.g., ["button"]) */
+  registryDependencies?: string[];
+  /** Array of code files comprising this component */
+  files: RegistryFile[];
+}
+
+/**
+ * Lightweight metadata structure used for the central registry index list.
+ */
+export interface RegistryIndexItem {
+  name: string;
+  title: string;
+  description: string;
+  type: "registry:ui";
+  dependencies?: string[];
+  registryDependencies?: string[];
+}
+
+/**
+ * Type alias for the central registry index manifest.
+ */
+export type RegistryIndex = RegistryIndexItem[];

package/src/registry/metadata.ts

@@ -0,0 +1,167 @@
+export interface ComponentMeta {
+  title: string;
+  description: string;
+  dependencies?: string[];
+  registryDependencies?: string[];
+}
+
+/**
+ * Static metadata configuration for all registered Nikala UI components.
+ * Extend this record when adding new TSX components.
+ */
+export const COMPONENT_METADATA: Record<string, ComponentMeta> = {
+  button: {
+    title: "Button",
+    description: "An interactive button component with variant and size options.",
+    dependencies: ["clsx", "tailwind-merge", "class-variance-authority"],
+  },
+  input: {
+    title: "Input",
+    description: "A standard text input field with styling variants.",
+    dependencies: ["clsx", "tailwind-merge"],
+  },
+  card: {
+    title: "Card",
+    description: "A versatile container component with header, content, and footer sections.",
+    dependencies: ["clsx", "tailwind-merge"],
+  },
+  badge: {
+    title: "Badge",
+    description: "A small badge component for status indicators and tags.",
+    dependencies: ["clsx", "tailwind-merge", "class-variance-authority"],
+  },
+  avatar: {
+    title: "Avatar",
+    description: "An image element with fallback representation for representing users.",
+    dependencies: ["clsx", "tailwind-merge"],
+  },
+  separator: {
+    title: "Separator",
+    description: "Visually or semantically separates content horizontally or vertically.",
+    dependencies: ["clsx", "tailwind-merge"],
+  },
+  textarea: {
+    title: "Textarea",
+    description: "A multi-line text input field with responsive focus styles.",
+    dependencies: ["clsx", "tailwind-merge"],
+  },
+  label: {
+    title: "Label",
+    description: "Accessible caption label for form controls and inputs.",
+    dependencies: ["clsx", "tailwind-merge", "class-variance-authority"],
+  },
+  skeleton: {
+    title: "Skeleton",
+    description: "Renders an animated pulse loading placeholder for content loading states.",
+    dependencies: ["clsx", "tailwind-merge"],
+  },
+  switch: {
+    title: "Switch",
+    description: "A control that allows the user to toggle between checked and unchecked states.",
+    dependencies: ["clsx", "tailwind-merge"],
+  },
+  checkbox: {
+    title: "Checkbox",
+    description: "A control that allows the user to toggle between checked and unchecked options.",
+    dependencies: ["clsx", "tailwind-merge"],
+  },
+  "radio-group": {
+    title: "Radio Group",
+    description: "A set of checkable buttons built on Kobalte primitives where only one button can be checked at a time.",
+    dependencies: ["clsx", "tailwind-merge", "@kobalte/core"],
+  },
+  select: {
+    title: "Select",
+    description: "Displays a list of options for the user to pick from, built on Kobalte primitives.",
+    dependencies: ["clsx", "tailwind-merge", "@kobalte/core"],
+  },
+  tabs: {
+    title: "Tabs",
+    description: "A set of layered sections of content displayed one at a time.",
+    dependencies: ["clsx", "tailwind-merge"],
+  },
+  accordion: {
+    title: "Accordion",
+    description: "A vertically stacked set of interactive headings built on Kobalte primitives.",
+    dependencies: ["clsx", "tailwind-merge", "@kobalte/core"],
+  },
+  breadcrumb: {
+    title: "Breadcrumb",
+    description: "Displays the path to the current resource using a hierarchy of links.",
+    dependencies: ["clsx", "tailwind-merge"],
+  },
+  alert: {
+    title: "Alert",
+    description: "Displays a callout banner for user feedback with variants, dismiss button, and timer.",
+    dependencies: ["clsx", "tailwind-merge", "class-variance-authority"],
+  },
+  dialog: {
+    title: "Dialog",
+    description: "A modal window overlaying the main content, built on Kobalte primitives with blur and outside-click options.",
+    dependencies: ["clsx", "tailwind-merge", "@kobalte/core"],
+  },
+  sheet: {
+    title: "Sheet / Drawer",
+    description: "Extends the dialog component to display content that slides in from screen edges.",
+    dependencies: ["clsx", "tailwind-merge", "class-variance-authority", "@kobalte/core"],
+  },
+  "dropdown-menu": {
+    title: "Dropdown Menu",
+    description: "Displays a menu to the user—such as a set of actions or functions—triggered by a button or avatar.",
+    dependencies: ["clsx", "tailwind-merge", "@kobalte/core"],
+  },
+  "theme-manager": {
+    title: "Theme Manager",
+    description: "Zero-dependency ThemeProvider and ThemeToggle component for switching light, dark, and system themes.",
+    dependencies: ["clsx", "tailwind-merge", "@kobalte/core", "lucide-solid"],
+    registryDependencies: ["button", "dropdown-menu"],
+  },
+  banner: {
+    title: "Banner",
+    description: "An announcement banner with sticky positioning, dismissal persistence, auto-hide timer, Lucide icons, and variant styles.",
+    dependencies: ["clsx", "tailwind-merge", "class-variance-authority", "lucide-solid"],
+  },
+  list: {
+    title: "List / List Item",
+    description: "Compound list components supporting icons, avatars, titles, subtitles, hotkey badges, chevron indicators, and interactive links.",
+    dependencies: ["clsx", "tailwind-merge", "class-variance-authority", "lucide-solid", "@kobalte/core"],
+  },
+  kbd: {
+    title: "Kbd (Keyboard Key)",
+    description: "Keyboard key and shortcut group indicators for displaying hotkeys.",
+    dependencies: ["clsx", "tailwind-merge", "class-variance-authority"],
+  },
+  "input-group": {
+    title: "Input Group",
+    description: "Compound input wrapper for combining text inputs with prefix and suffix addons.",
+    dependencies: ["clsx", "tailwind-merge", "class-variance-authority"],
+    registryDependencies: ["kbd"],
+  },
+  command: {
+    title: "Command / Command Palette",
+    description: "Fast, accessible command palette and search modal built on Kobalte Dialog primitives with auto-filtering.",
+    dependencies: [
+      "clsx",
+      "tailwind-merge",
+      "class-variance-authority",
+      "lucide-solid",
+      "@kobalte/core",
+    ],
+    registryDependencies: ["kbd", "input-group", "list"],
+  },
+  toast: {
+    title: "Toast / Sonner",
+    description: "A succinct message displayed temporarily in a toast region, built on Kobalte primitives.",
+    dependencies: ["clsx", "tailwind-merge", "class-variance-authority", "lucide-solid", "@kobalte/core"],
+  },
+  tooltip: {
+    title: "Tooltip",
+    description: "A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it, built on Kobalte primitives.",
+    dependencies: ["clsx", "tailwind-merge", "@kobalte/core"],
+  },
+  popover: {
+    title: "Popover",
+    description: "Displays rich content in a portal layer triggered by a button, built on Kobalte primitives.",
+    dependencies: ["clsx", "tailwind-merge", "@kobalte/core", "lucide-solid"],
+  },
+};

package/src/registry/providers/theme-provider.tsx

@@ -0,0 +1,208 @@
+import {
+  createContext,
+  createEffect,
+  createSignal,
+  onCleanup,
+  onMount,
+  useContext,
+  type ParentComponent,
+  type Accessor,
+} from "solid-js";
+
+export type Theme = "light" | "dark" | "system";
+export type AccentColor = "wine" | "violet" | "sky" | "emerald" | "rose" | "amber" | "zinc";
+export type Radius = "0" | "0.3" | "0.5" | "0.75" | "1.0";
+
+export interface ThemeProviderProps {
+  /** Initial default theme mode if no saved preference is found in localStorage */
+  defaultTheme?: Theme;
+  /** Initial default accent color override if needed */
+  defaultAccent?: AccentColor;
+  /** Initial default border radius override if needed */
+  defaultRadius?: Radius;
+  /** Key used to store theme preferences in localStorage */
+  storageKey?: string;
+}
+
+const ACCENT_COLORS: Record<
+  AccentColor,
+  { light: string; dark: string; lightFg: string; darkFg: string }
+> = {
+  wine: { light: "#722f37", dark: "#9e3b47", lightFg: "#ffffff", darkFg: "#ffffff" },
+  violet: { light: "#7c3aed", dark: "#8b5cf6", lightFg: "#ffffff", darkFg: "#ffffff" },
+  sky: { light: "#0284c7", dark: "#38bdf8", lightFg: "#ffffff", darkFg: "#0f172a" },
+  emerald: { light: "#059669", dark: "#34d399", lightFg: "#ffffff", darkFg: "#052e16" },
+  rose: { light: "#e11d48", dark: "#fb7185", lightFg: "#ffffff", darkFg: "#ffffff" },
+  amber: { light: "#d97706", dark: "#fbbf24", lightFg: "#ffffff", darkFg: "#111827" },
+  zinc: { light: "#18181b", dark: "#fafafa", lightFg: "#fafafa", darkFg: "#18181b" },
+};
+
+interface ThemeProviderContextValue {
+  theme: Accessor<Theme>;
+  setTheme: (theme: Theme) => void;
+  accent: Accessor<AccentColor | undefined>;
+  setAccent: (accent: AccentColor) => void;
+  radius: Accessor<Radius | undefined>;
+  setRadius: (radius: Radius) => void;
+}
+
+const ThemeProviderContext = createContext<ThemeProviderContextValue>();
+
+/**
+ * Context provider managing application theme state (light/dark/system), accent colors, and border radius.
+ */
+export const ThemeProvider: ParentComponent<ThemeProviderProps> = (props) => {
+  const storageKey = props.storageKey || "nikala-theme";
+  const defaultTheme = props.defaultTheme || "system";
+
+  // Safely read saved values from localStorage without forcing unnecessary fallbacks
+  const getInitialTheme = (): Theme => {
+    if (typeof window === "undefined") return defaultTheme;
+    try {
+      const saved = localStorage.getItem(`${storageKey}-mode`);
+      if (saved === "light" || saved === "dark" || saved === "system") return saved;
+    } catch { }
+    return defaultTheme;
+  };
+
+  const getInitialAccent = (): AccentColor | undefined => {
+    if (typeof window === "undefined") return props.defaultAccent;
+    try {
+      const saved = localStorage.getItem(`${storageKey}-accent`);
+      if (saved && ACCENT_COLORS[saved as AccentColor]) return saved as AccentColor;
+    } catch { }
+    return props.defaultAccent;
+  };
+
+  const getInitialRadius = (): Radius | undefined => {
+    if (typeof window === "undefined") return props.defaultRadius;
+    try {
+      const saved = localStorage.getItem(`${storageKey}-radius`);
+      if (saved) return saved as Radius;
+    } catch { }
+    return props.defaultRadius;
+  };
+
+  const [theme, setThemeSignal] = createSignal<Theme>(getInitialTheme());
+  const [accent, setAccentSignal] = createSignal<AccentColor | undefined>(getInitialAccent());
+  const [radius, setRadiusSignal] = createSignal<Radius | undefined>(getInitialRadius());
+
+  // Applies classes and CSS custom properties when custom overrides are explicitly set
+  const applyTheme = (
+    targetTheme: Theme,
+    currentAccent: AccentColor | undefined,
+    currentRadius: Radius | undefined
+  ) => {
+    if (typeof window === "undefined") return;
+
+    const root = document.documentElement;
+    root.classList.remove("light", "dark");
+
+    let resolvedDark = false;
+    if (targetTheme === "system") {
+      resolvedDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+      root.classList.add(resolvedDark ? "dark" : "light");
+    } else {
+      resolvedDark = targetTheme === "dark";
+      root.classList.add(targetTheme);
+    }
+
+    // Override --primary CSS variables ONLY if explicitly chosen
+    if (currentAccent && ACCENT_COLORS[currentAccent]) {
+      const accentData = ACCENT_COLORS[currentAccent];
+      const primaryHex = resolvedDark ? accentData.dark : accentData.light;
+      const primaryFgHex = resolvedDark ? accentData.darkFg : accentData.lightFg;
+
+      root.style.setProperty("--primary", primaryHex);
+      root.style.setProperty("--primary-foreground", primaryFgHex);
+    }
+
+    // Override --radius CSS variable ONLY if explicitly chosen
+    if (currentRadius) {
+      root.style.setProperty("--radius", `${currentRadius}rem`);
+    }
+  };
+
+  // Reactively apply theme updates and store preferences in localStorage
+  createEffect(() => {
+    const t = theme();
+    const a = accent();
+    const r = radius();
+
+    applyTheme(t, a, r);
+
+    if (typeof window !== "undefined") {
+      try {
+        localStorage.setItem(`${storageKey}-mode`, t);
+        if (a) localStorage.setItem(`${storageKey}-accent`, a);
+        if (r) localStorage.setItem(`${storageKey}-radius`, r);
+      } catch { }
+    }
+  });
+
+  onMount(() => {
+    if (typeof window === "undefined") return;
+
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+
+    const handleSystemChange = (e: MediaQueryListEvent) => {
+      if (theme() === "system") {
+        const root = document.documentElement;
+        root.classList.remove("light", "dark");
+        root.classList.add(e.matches ? "dark" : "light");
+
+        const currentAccent = accent();
+        if (currentAccent && ACCENT_COLORS[currentAccent]) {
+          const accentData = ACCENT_COLORS[currentAccent];
+          const primaryHex = e.matches ? accentData.dark : accentData.light;
+          const primaryFgHex = e.matches ? accentData.darkFg : accentData.lightFg;
+
+          root.style.setProperty("--primary", primaryHex);
+          root.style.setProperty("--primary-foreground", primaryFgHex);
+        }
+      }
+    };
+
+    if (mediaQuery.addEventListener) {
+      mediaQuery.addEventListener("change", handleSystemChange);
+    } else if ("addListener" in mediaQuery) {
+      (mediaQuery as any).addListener(handleSystemChange);
+    }
+
+    onCleanup(() => {
+      if (mediaQuery.removeEventListener) {
+        mediaQuery.removeEventListener("change", handleSystemChange);
+      } else if ("removeListener" in mediaQuery) {
+        (mediaQuery as any).removeListener(handleSystemChange);
+      }
+    });
+  });
+
+  const value: ThemeProviderContextValue = {
+    theme,
+    setTheme: (newTheme: Theme) => setThemeSignal(newTheme),
+    accent,
+    setAccent: (newAccent: AccentColor) => setAccentSignal(newAccent),
+    radius,
+    setRadius: (newRadius: Radius) => setRadiusSignal(newRadius),
+  };
+
+  return (
+    <ThemeProviderContext.Provider value={value}>
+      {props.children}
+    </ThemeProviderContext.Provider>
+  );
+};
+
+/**
+ * Accesses Nikala UI theme state, accent colors, border radius, and update functions.
+ */
+export function useTheme(): ThemeProviderContextValue {
+  const context = useContext(ThemeProviderContext);
+  if (!context) {
+    throw new Error("useTheme must be used within a ThemeProvider");
+  }
+  return context;
+}
+
+export { ThemeScript, type ThemeScriptProps } from "./theme-script";

package/src/registry/providers/theme-script.tsx

@@ -0,0 +1,58 @@
+import { type Component } from "solid-js";
+
+export interface ThemeScriptProps {
+  /** Storage key namespace used in localStorage (default: "nikala-theme") */
+  storageKey?: string;
+  /** Initial default theme mode if no saved preference exists (default: "system") */
+  defaultTheme?: "light" | "dark" | "system";
+  /** Initial default primary accent color if no saved preference exists */
+  defaultAccent?: string;
+  /** Initial default border radius if no saved preference exists */
+  defaultRadius?: string;
+}
+
+/**
+ * Pre-hydration inline script executed synchronously before DOM paint to prevent theme flickering (anti-FOUC).
+ */
+export const ThemeScript: Component<ThemeScriptProps> = (props) => {
+  const key = props.storageKey || "nikala-theme";
+  const defTheme = props.defaultTheme || "system";
+  const defAccent = props.defaultAccent || "";
+  const defRadius = props.defaultRadius || "";
+
+  const scriptText = `(function(){try{
+  var key = '${key}';
+  var mode = localStorage.getItem(key + '-mode') || '${defTheme}';
+  var accent = localStorage.getItem(key + '-accent') || '${defAccent}';
+  var radius = localStorage.getItem(key + '-radius') || '${defRadius}';
+
+  var isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+  var resolvedDark = mode === 'dark' || (mode === 'system' && isDark);
+
+  var root = document.documentElement;
+  root.classList.remove('light', 'dark');
+  root.classList.add(resolvedDark ? 'dark' : 'light');
+  root.style.colorScheme = resolvedDark ? 'dark' : 'light';
+
+  var colorMap = {
+    wine: resolvedDark ? '#9e3b47' : '#722f37',
+    violet: resolvedDark ? '#8b5cf6' : '#7c3aed',
+    sky: resolvedDark ? '#38bdf8' : '#0284c7',
+    emerald: resolvedDark ? '#34d399' : '#059669',
+    rose: resolvedDark ? '#fb7185' : '#e11d48',
+    amber: resolvedDark ? '#fbbf24' : '#d97706',
+    zinc: resolvedDark ? '#fafafa' : '#18181b'
+  };
+
+  if (accent && colorMap[accent]) {
+    root.style.setProperty('--primary', colorMap[accent]);
+  }
+
+  if (radius) {
+    var radVal = radius.endsWith('rem') ? radius : radius + 'rem';
+    root.style.setProperty('--radius', radVal);
+  }
+}catch(e){}})();`;
+
+  return <script innerHTML={scriptText} />;
+};

package/src/registry/providers/theme-transitions.ts

@@ -0,0 +1,108 @@
+export type ThemeEffect = "none" | "circular" | "fade";
+
+/**
+ * Injects required CSS view-transition pseudo-element styles to prevent browser mix-blend artifacts.
+ */
+function ensureTransitionStyles() {
+  if (typeof document === "undefined") return;
+  const styleId = "nikala-view-transition-styles";
+  if (!document.getElementById(styleId)) {
+    const style = document.createElement("style");
+    style.id = styleId;
+    style.textContent = `
+      ::view-transition-old(root),
+      ::view-transition-new(root) {
+        animation: none;
+        mix-blend-mode: normal;
+      }
+      ::view-transition-old(root) {
+        z-index: 1;
+      }
+      ::view-transition-new(root) {
+        z-index: 9999;
+      }
+    `;
+    document.head.appendChild(style);
+  }
+}
+
+/**
+ * Executes a theme change with the specified transition effect using the Web View Transitions API.
+ *
+ * @param effect - Desired transition animation ("none", "circular", "fade")
+ * @param event - Mouse or Pointer event to calculate transition center coordinates
+ * @param updateThemeCallback - Callback function performing the actual theme state change
+ */
+export function runThemeTransition(
+  effect: ThemeEffect = "none",
+  event: MouseEvent | undefined,
+  updateThemeCallback: () => void
+) {
+  // Safe fallback if View Transitions API is unsupported or user prefers reduced motion
+  if (
+    effect === "none" ||
+    typeof document === "undefined" ||
+    !(document as any).startViewTransition ||
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  ) {
+    updateThemeCallback();
+    return;
+  }
+
+  ensureTransitionStyles();
+
+  // Circular expanding ripple transition originating from click coordinates
+  if (effect === "circular" && event) {
+    const x = event.clientX;
+    const y = event.clientY;
+
+    const endRadius = Math.hypot(
+      Math.max(x, window.innerWidth - x),
+      Math.max(y, window.innerHeight - y)
+    );
+
+    const transition = (document as any).startViewTransition(() => {
+      updateThemeCallback();
+    });
+
+    transition.ready.then(() => {
+      document.documentElement.animate(
+        {
+          clipPath: [
+            `circle(0px at ${x}px ${y}px)`,
+            `circle(${endRadius}px at ${x}px ${y}px)`,
+          ],
+        },
+        {
+          duration: 500,
+          easing: "ease-in-out",
+          pseudoElement: "::view-transition-new(root)",
+        }
+      );
+    });
+    return;
+  }
+
+  // Smooth opacity fade view transition
+  if (effect === "fade") {
+    const transition = (document as any).startViewTransition(() => {
+      updateThemeCallback();
+    });
+
+    transition.ready.then(() => {
+      document.documentElement.animate(
+        {
+          opacity: [0, 1],
+        },
+        {
+          duration: 350,
+          easing: "ease-in-out",
+          pseudoElement: "::view-transition-new(root)",
+        }
+      );
+    });
+    return;
+  }
+
+  updateThemeCallback();
+}