@nikala-ui/docs 0.12.0

package/dist/vendor/core-src/registry/components/ui/api-table.tsx

@@ -0,0 +1,117 @@
+import {
+  splitProps,
+  For,
+  Show,
+  type JSX,
+  type Component,
+} from "solid-js";
+import { SectionHeading } from "@/components/ui/section-heading";
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableRow,
+  TableHead,
+  TableCell,
+} from "@/components/ui/table";
+import { cn } from "@/lib/cn";
+
+export interface ApiTableItem {
+  /** Property, attribute, or method name */
+  prop: string;
+  /** TypeScript type definition string */
+  type: string;
+  /** Default value if optional */
+  default?: string;
+  /** Detailed description of purpose and usage */
+  description: string;
+  /** Whether the property is strictly required */
+  required?: boolean;
+}
+
+export interface ApiTableProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  /** Title header for this API section (e.g. component or interface name) */
+  title?: string;
+  /** Subtitle or explanatory note */
+  description?: string;
+  /** Badge label next to the title (defaults to "Props") */
+  badge?: string;
+  /** List of API properties to render in the table */
+  items: ApiTableItem[];
+  class?: string;
+}
+
+/**
+ * Clean, structured API reference table component composed from Table and Badge primitives.
+ */
+export const ApiTable: Component<ApiTableProps> = (props) => {
+  const [local, rest] = splitProps(props, [
+    "title",
+    "description",
+    "badge",
+    "items",
+    "class",
+  ]);
+
+  return (
+    <div class={cn("my-6 space-y-3", local.class)} {...rest}>
+      {/* Header */}
+      <Show when={local.title}>
+        <SectionHeading
+          variant="compact"
+          title={local.title!}
+          badge={local.badge || "Props"}
+          description={local.description}
+        />
+      </Show>
+
+      {/* Responsive Table Container Composed from Nikala Table Primitives */}
+      <div class="rounded-lg border border-border bg-card/50 shadow-2xs overflow-hidden">
+        <Table class="text-xs">
+          <TableHeader class="bg-muted/40 font-mono text-[11px] uppercase tracking-wider text-muted-foreground select-none">
+            <TableRow class="hover:bg-transparent">
+              <TableHead class="h-9 px-4 font-semibold">Prop</TableHead>
+              <TableHead class="h-9 px-4 font-semibold">Type</TableHead>
+              <TableHead class="h-9 px-4 font-semibold">Default</TableHead>
+              <TableHead class="h-9 px-4 font-semibold">Description</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody class="font-mono text-xs">
+            <For each={local.items}>
+              {(item) => (
+                <TableRow class="transition-colors hover:bg-muted/20">
+                  <TableCell class="px-4 py-3 font-semibold text-primary">
+                    <span class="inline-flex items-center gap-1">
+                      {item.prop}
+                      <Show when={item.required}>
+                        <span class="text-rose-500 font-bold" title="Required">*</span>
+                      </Show>
+                    </span>
+                  </TableCell>
+                  <TableCell class="px-4 py-3 text-muted-foreground">
+                    <code class="rounded-md bg-muted px-1.5 py-0.5 font-mono text-[11px] text-foreground">
+                      {item.type}
+                    </code>
+                  </TableCell>
+                  <TableCell class="px-4 py-3 text-muted-foreground">
+                    <Show
+                      when={item.default}
+                      fallback={<span class="text-muted-foreground/40 font-mono">-</span>}
+                    >
+                      <code class="rounded-md bg-muted/60 px-1 py-0.5 font-mono text-[11px]">
+                        {item.default}
+                      </code>
+                    </Show>
+                  </TableCell>
+                  <TableCell class="px-4 py-3 font-sans font-normal leading-relaxed text-muted-foreground">
+                    {item.description}
+                  </TableCell>
+                </TableRow>
+              )}
+            </For>
+          </TableBody>
+        </Table>
+      </div>
+    </div>
+  );
+};

package/dist/vendor/core-src/registry/components/ui/aspect-ratio.tsx

@@ -0,0 +1,31 @@
+import { splitProps, type Component, type JSX } from "solid-js";
+import { cn } from "@/lib/cn";
+
+export interface AspectRatioProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  ratio?: number;
+  class?: string;
+  children?: JSX.Element;
+}
+
+/**
+ * Nikala UI AspectRatio Component.
+ * Displays content within a specific aspect ratio (e.g. 16/9, 4/3, 1/1) using CSS aspect-ratio.
+ */
+export const AspectRatio: Component<AspectRatioProps> = (props) => {
+  const [local, rest] = splitProps(props, ["ratio", "class", "children", "style"]);
+
+  const computedRatio = () => (local.ratio !== undefined ? local.ratio : 16 / 9);
+
+  return (
+    <div
+      class={cn("relative w-full overflow-hidden", local.class)}
+      style={{
+        "aspect-ratio": `${computedRatio()}`,
+        ...(typeof local.style === "object" ? local.style : {}),
+      }}
+      {...rest}
+    >
+      {local.children}
+    </div>
+  );
+};

package/dist/vendor/core-src/registry/components/ui/avatar.tsx

@@ -0,0 +1,114 @@
+import {
+  createSignal,
+  createEffect,
+  Show,
+  splitProps,
+  type Component,
+  type JSX,
+} from "solid-js";
+import { cn } from "@/lib/cn";
+
+export interface AvatarProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  class?: string;
+}
+
+/**
+ * Root Avatar container component.
+ */
+export const Avatar: Component<AvatarProps> = (props) => {
+  const [local, rest] = splitProps(props, ["class"]);
+
+  return (
+    <div
+      class={cn(
+        "relative flex h-10 w-10 shrink-0 overflow-hidden rounded-lg border border-border bg-muted",
+        local.class
+      )}
+      {...rest}
+    />
+  );
+};
+
+export interface AvatarImageProps
+  extends JSX.ImgHTMLAttributes<HTMLImageElement> {
+  class?: string;
+}
+
+/**
+ * Image element for the Avatar component with background status loader.
+ */
+export const AvatarImage: Component<AvatarImageProps> = (props) => {
+  const [local, rest] = splitProps(props, [
+    "class",
+    "src",
+    "alt",
+    "onLoad",
+    "onError",
+  ]);
+  const [status, setStatus] = createSignal<"loading" | "loaded" | "error">(
+    "loading"
+  );
+
+  /* Pre-test image loading in background JS to prevent native broken icon flashes */
+  createEffect(() => {
+    const src = local.src;
+    if (!src) {
+      setStatus("error");
+      return;
+    }
+
+    const img = new Image();
+    img.src = src;
+    img.onload = () => setStatus("loaded");
+    img.onerror = () => setStatus("error");
+  });
+
+  const handleLoad: JSX.EventHandlerUnion<HTMLImageElement, Event> = (e) => {
+    setStatus("loaded");
+    if (typeof local.onLoad === "function") {
+      (local.onLoad as (e: Event) => void)(e);
+    }
+  };
+
+  const handleError: JSX.EventHandlerUnion<HTMLImageElement, Event> = (e) => {
+    setStatus("error");
+    if (typeof local.onError === "function") {
+      (local.onError as (e: Event) => void)(e);
+    }
+  };
+
+  return (
+    <Show when={status() === "loaded"}>
+      <img
+        src={local.src}
+        alt={local.alt}
+        class={cn("aspect-square h-full w-full object-cover", local.class)}
+        onLoad={handleLoad}
+        onError={handleError}
+        {...rest}
+      />
+    </Show>
+  );
+};
+
+export interface AvatarFallbackProps
+  extends JSX.HTMLAttributes<HTMLDivElement> {
+  class?: string;
+}
+
+/**
+ * Fallback container for rendering initials or icons when avatar image is missing/broken.
+ */
+export const AvatarFallback: Component<AvatarFallbackProps> = (props) => {
+  const [local, rest] = splitProps(props, ["class"]);
+
+  return (
+    <div
+      class={cn(
+        "flex h-full w-full items-center justify-center bg-muted text-sm font-medium text-muted-foreground select-none",
+        local.class
+      )}
+      {...rest}
+    />
+  );
+};

package/dist/vendor/core-src/registry/components/ui/badge.tsx

@@ -0,0 +1,56 @@
+import { splitProps, type Component, type JSX } from "solid-js";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/cn";
+
+/**
+ * Class variance authority configuration for badge styling variants.
+ */
+export const badgeVariants = cva(
+  "inline-flex items-center rounded-md border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2",
+  {
+    variants: {
+      variant: {
+        default:
+          "border-transparent bg-primary text-primary-foreground shadow hover:bg-primary/80",
+        secondary:
+          "border-transparent bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        destructive:
+          "border-transparent bg-destructive text-destructive-foreground shadow hover:bg-destructive/80",
+        outline:
+          "text-foreground border-border",
+        success:
+          "border-transparent bg-green-600 text-zinc-50 shadow-sm hover:bg-green-600/90 dark:bg-green-900 dark:text-zinc-50 dark:hover:bg-green-900/90",
+        warning:
+          "border-transparent bg-yellow-600 text-zinc-50 shadow-sm hover:bg-yellow-600/90 dark:bg-yellow-900 dark:text-zinc-50 dark:hover:bg-yellow-900/90",
+        info:
+          "border-transparent bg-blue-600 text-zinc-50 shadow-sm hover:bg-blue-600/90 dark:bg-blue-900 dark:text-zinc-50 dark:hover:bg-blue-900/90",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+);
+
+/**
+ * Props interface for the Badge component extending standard HTML div attributes.
+ */
+export interface BadgeProps
+  extends JSX.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof badgeVariants> {
+  class?: string;
+}
+
+/**
+ * Nikala UI Badge component built for SolidJS with Tailwind CSS v4 styling.
+ */
+export const Badge: Component<BadgeProps> = (props) => {
+  // Use splitProps to preserve SolidJS reactivity
+  const [local, rest] = splitProps(props, ["variant", "class", "children"]);
+
+  return (
+    <div class={cn(badgeVariants({ variant: local.variant }), local.class)} {...rest}>
+      {local.children}
+    </div>
+  );
+};

package/dist/vendor/core-src/registry/components/ui/banner.tsx

@@ -0,0 +1,187 @@
+// src/components/ui/banner.tsx
+import {
+  createSignal,
+  onMount,
+  onCleanup,
+  Show,
+  splitProps,
+  type Component,
+  type JSX,
+} from "solid-js";
+import { Dynamic } from "solid-js/web";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Info, AlertTriangle, CheckCircle, AlertCircle, X } from "lucide-solid";
+import { cn } from "@/lib/cn";
+
+export const bannerVariants = cva(
+  "relative flex w-full items-center justify-between gap-3 px-4 py-2.5 text-sm transition-all duration-300 ease-in-out",
+  {
+    variants: {
+      variant: {
+        default:
+          "bg-zinc-900 text-zinc-50 dark:bg-zinc-100 dark:text-zinc-900",
+        warning:
+          "bg-amber-500/15 text-amber-900 border-b border-amber-500/20 dark:text-amber-200",
+        info:
+          "bg-sky-500/15 text-sky-900 border-b border-sky-500/20 dark:text-sky-200",
+        success:
+          "bg-emerald-500/15 text-emerald-900 border-b border-emerald-500/20 dark:text-emerald-200",
+        destructive:
+          "bg-rose-500/15 text-rose-900 border-b border-rose-500/20 dark:text-rose-200",
+      },
+      sticky: {
+        true: "sticky top-0 z-50 backdrop-blur-sm",
+        false: "relative",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      sticky: false,
+    },
+  }
+);
+
+export interface BannerProps
+  extends JSX.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof bannerVariants> {
+  dismissible?: boolean;
+  autoHideDelay?: number;
+  storageKey?: string;
+  showIcon?: boolean;
+  icon?: Component<{ class?: string }>;
+  link?: string;
+  linkText?: string;
+  linkTarget?: string;
+  onDismiss?: () => void;
+  class?: string;
+}
+
+/**
+ * Nikala UI Banner Component.
+ */
+export const Banner: Component<BannerProps> = (props) => {
+  const [local, rest] = splitProps(props, [
+    "variant",
+    "sticky",
+    "dismissible",
+    "autoHideDelay",
+    "storageKey",
+    "showIcon",
+    "icon",
+    "link",
+    "linkText",
+    "linkTarget",
+    "onDismiss",
+    "class",
+    "children",
+  ]);
+
+  const [visible, setVisible] = createSignal(true);
+  let timerId: ReturnType<typeof setTimeout> | undefined;
+
+  onMount(() => {
+    if (local.storageKey) {
+      try {
+        const isDismissed = localStorage.getItem(local.storageKey);
+        if (isDismissed === "true") {
+          setVisible(false);
+          return;
+        }
+      } catch (e) { }
+    }
+
+    if (local.autoHideDelay && local.autoHideDelay > 0) {
+      timerId = setTimeout(() => {
+        handleDismiss();
+      }, local.autoHideDelay);
+    }
+  });
+
+  onCleanup(() => {
+    if (timerId) clearTimeout(timerId);
+  });
+
+  const handleDismiss = () => {
+    setVisible(false);
+
+    if (local.storageKey) {
+      try {
+        localStorage.setItem(local.storageKey, "true");
+      } catch (e) {}
+    }
+
+    if (typeof local.onDismiss === "function") {
+      local.onDismiss();
+    }
+  };
+
+  /* Default icon selector based on banner variant */
+  const getDefaultIcon = () => {
+    switch (local.variant) {
+      case "warning":
+        return AlertTriangle;
+      case "success":
+        return CheckCircle;
+      case "destructive":
+        return AlertCircle;
+      default:
+        return Info;
+    }
+  };
+
+  const activeIcon = () => local.icon || getDefaultIcon();
+  const shouldShowIcon = () => local.showIcon !== false;
+  const shouldBeDismissible = () => local.dismissible !== false;
+
+  return (
+    <Show when={visible()}>
+      <div
+        class={cn(
+          bannerVariants({ variant: local.variant, sticky: local.sticky }),
+          local.class
+        )}
+        {...rest}
+      >
+        <div class="flex flex-1 items-center justify-center gap-2 text-center sm:text-left">
+          {/* Dynamic Lucide Icon */}
+          <Show when={shouldShowIcon()}>
+            <span class="inline-flex shrink-0 items-center justify-center">
+              <Dynamic component={activeIcon()} class="h-4 w-4 opacity-80" />
+            </span>
+          </Show>
+
+          {/* Text Content */}
+          <div class="flex-1 text-xs font-medium sm:text-sm">
+            {local.children}
+          </div>
+
+          {/* Action Link */}
+          <Show when={local.link}>
+            <div class="shrink-0">
+              <a
+                href={local.link}
+                target={local.linkTarget || "_blank"}
+                rel="noreferrer"
+                class="underline font-semibold hover:opacity-80 transition-opacity"
+              >
+                {local.linkText || "Learn more"}
+              </a>
+            </div>
+          </Show>
+        </div>
+
+        {/* Close Button */}
+        <Show when={shouldBeDismissible()}>
+          <button
+            type="button"
+            onClick={handleDismiss}
+            class="shrink-0 rounded-md p-1 opacity-70 transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring"
+            aria-label="Dismiss banner"
+          >
+            <X class="h-4 w-4" />
+          </button>
+        </Show>
+      </div>
+    </Show>
+  );
+};

package/dist/vendor/core-src/registry/components/ui/breadcrumb.tsx

@@ -0,0 +1,136 @@
+import { splitProps, type Component, type JSX } from "solid-js";
+import { cn } from "@/lib/cn";
+
+export interface BreadcrumbProps extends JSX.HTMLAttributes<HTMLElement> {
+  class?: string;
+}
+
+/**
+ * Root navigation container for the Nikala UI Breadcrumb hierarchy.
+ */
+export const Breadcrumb: Component<BreadcrumbProps> = (props) => {
+  const [local, rest] = splitProps(props, ["class"]);
+  return <nav aria-label="breadcrumb" class={cn("relative w-full", local.class)} {...rest} />;
+};
+
+export interface BreadcrumbListProps extends JSX.HTMLAttributes<HTMLOListElement> {
+  class?: string;
+}
+
+/**
+ * Ordered list container housing all breadcrumb path items.
+ */
+export const BreadcrumbList: Component<BreadcrumbListProps> = (props) => {
+  const [local, rest] = splitProps(props, ["class"]);
+  return (
+    <ol
+      class={cn(
+        "flex flex-wrap items-center gap-1.5 text-sm text-muted-foreground break-words sm:gap-2.5",
+        local.class
+      )}
+      {...rest}
+    />
+  );
+};
+
+export interface BreadcrumbItemProps extends JSX.HTMLAttributes<HTMLLIElement> {
+  class?: string;
+}
+
+/**
+ * Individual list item element wrapper in the breadcrumb hierarchy.
+ */
+export const BreadcrumbItem: Component<BreadcrumbItemProps> = (props) => {
+  const [local, rest] = splitProps(props, ["class"]);
+  return <li class={cn("inline-flex items-center gap-1.5", local.class)} {...rest} />;
+};
+
+export interface BreadcrumbLinkProps extends JSX.AnchorHTMLAttributes<HTMLAnchorElement> {
+  class?: string;
+}
+
+/**
+ * Clickable breadcrumb trail link element.
+ */
+export const BreadcrumbLink: Component<BreadcrumbLinkProps> = (props) => {
+  const [local, rest] = splitProps(props, ["class"]);
+  return (
+    <a
+      class={cn(
+        "transition-colors hover:text-foreground underline-offset-4 hover:underline",
+        local.class
+      )}
+      {...rest}
+    />
+  );
+};
+
+export interface BreadcrumbPageProps extends JSX.HTMLAttributes<HTMLSpanElement> {
+  class?: string;
+}
+
+/**
+ * Non-clickable active page indicator in breadcrumb hierarchy.
+ */
+export const BreadcrumbPage: Component<BreadcrumbPageProps> = (props) => {
+  const [local, rest] = splitProps(props, ["class"]);
+  return (
+    <span
+      role="link"
+      aria-disabled="true"
+      aria-current="page"
+      class={cn("font-normal text-foreground", local.class)}
+      {...rest}
+    />
+  );
+};
+
+export interface BreadcrumbSeparatorProps extends JSX.HTMLAttributes<HTMLLIElement> {
+  class?: string;
+}
+
+/**
+ * Visual separator icon rendered between breadcrumb path links.
+ */
+export const BreadcrumbSeparator: Component<BreadcrumbSeparatorProps> = (props) => {
+  const [local, rest] = splitProps(props, ["class", "children"]);
+  return (
+    <li
+      role="presentation"
+      aria-hidden="true"
+      class={cn("[&>svg]:size-3.5 text-muted-foreground", local.class)}
+      {...rest}
+    >
+      {local.children || (
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <path stroke-linecap="round" stroke-linejoin="round" d="M9 5l7 7-7 7" />
+        </svg>
+      )}
+    </li>
+  );
+};
+
+export interface BreadcrumbEllipsisProps extends JSX.HTMLAttributes<HTMLSpanElement> {
+  class?: string;
+}
+
+/**
+ * Ellipsis element representing truncated intermediate breadcrumb items.
+ */
+export const BreadcrumbEllipsis: Component<BreadcrumbEllipsisProps> = (props) => {
+  const [local, rest] = splitProps(props, ["class"]);
+  return (
+    <span
+      role="presentation"
+      aria-hidden="true"
+      class={cn("flex h-9 w-9 items-center justify-center text-muted-foreground", local.class)}
+      {...rest}
+    >
+      <svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <circle cx="12" cy="12" r="1" />
+        <circle cx="19" cy="12" r="1" />
+        <circle cx="5" cy="12" r="1" />
+      </svg>
+    </span>
+  );
+};