@kushagradhawan/kookie-blocks 0.1.16 → 0.1.18

package/src/components/docs/docs-page.tsx

@@ -0,0 +1,99 @@
+import React from 'react';
+import { Flex, Box, Separator, Container, Text, Link } from '@kushagradhawan/kookie-ui';
+import { DocsPageHeader } from './docs-page-header.js';
+import type { DocsPageMeta } from './types.js';
+
+export interface DocsPageProps {
+  children: React.ReactNode;
+  /** Page metadata for header */
+  meta?: DocsPageMeta;
+  /** Optional table of contents element */
+  tableOfContents?: React.ReactNode;
+  /** Content max width */
+  maxWidth?: string | number;
+  /** Page padding */
+  padding?: '3' | '4' | '5' | '6' | '7' | '8' | '9';
+  /** Optional header actions */
+  headerActions?: React.ReactNode;
+  /** Custom header element (overrides meta-based header) */
+  header?: React.ReactNode;
+  /** Show footer with copyright */
+  showFooter?: boolean;
+  /** Footer copyright holder */
+  footerCopyright?: {
+    name: string;
+    url?: string;
+  };
+  /** GitHub repo URL for footer */
+  githubUrl?: string;
+}
+
+export function DocsPage({
+  children,
+  meta,
+  tableOfContents,
+  maxWidth = '48rem',
+  padding = '6',
+  headerActions,
+  header,
+  showFooter = false,
+  footerCopyright,
+  githubUrl,
+}: DocsPageProps) {
+  const currentYear = new Date().getFullYear();
+  const showHeader = header || meta;
+
+  return (
+    <Flex my="6" gap={{ initial: '6', md: '6' }} align="start" direction={{ initial: 'column', lg: 'row' }}>
+      {/* Main content area */}
+      <Flex direction="column" gap="6" p={{ initial: '2', sm: '4' }} flexGrow="1" style={{ minWidth: 0 }}>
+        <Container size="2" style={{ minWidth: 0 }} data-content-area>
+          <Box p="4" width="100%">
+            <Flex direction="column" gap="8" width="100%">
+              {/* Page Header */}
+              {header ? header : meta && <DocsPageHeader meta={meta} actions={headerActions} />}
+
+              {showHeader && <Separator size="4" />}
+
+              <Flex direction="column" gap="0" width="100%">
+                {children}
+              </Flex>
+            </Flex>
+
+            {showFooter && (
+              <Flex align="center" justify="center" width="100%" pt="8">
+                <Text size="2" color="gray" align="center">
+                  © {currentYear}{' '}
+                  {footerCopyright?.url ? (
+                    <Link href={footerCopyright.url} target="_blank" rel="noreferrer">
+                      {footerCopyright.name}
+                    </Link>
+                  ) : (
+                    footerCopyright?.name || 'Your Company'
+                  )}
+                  . Licensed under MIT.
+                  {githubUrl && (
+                    <>
+                      {' '}
+                      <Link href={githubUrl} target="_blank" rel="noreferrer">
+                        GitHub
+                      </Link>
+                      .
+                    </>
+                  )}
+                </Text>
+              </Flex>
+            )}
+          </Box>
+        </Container>
+      </Flex>
+
+      {/* Table of Contents */}
+      {tableOfContents && (
+        <Box style={{ width: '240px', minWidth: '160px' }} position="sticky" top="200px" display={{ initial: 'none', lg: 'block' }}>
+          {tableOfContents}
+        </Box>
+      )}
+    </Flex>
+  );
+}

package/src/components/docs/docs-shell.tsx

@@ -0,0 +1,114 @@
+'use client';
+
+import React, { useState } from 'react';
+import { Shell, Flex, IconButton } from '@kushagradhawan/kookie-ui';
+import { DocsSidebar } from './docs-sidebar.js';
+import type { DocsNavigationConfig, DocsLogoConfig } from './types.js';
+
+export interface DocsShellProps {
+  children: React.ReactNode;
+  /** Navigation configuration */
+  navigation: DocsNavigationConfig;
+  /** Logo configuration */
+  logo?: DocsLogoConfig;
+  /** Optional header actions (dark mode toggle, github link, etc.) */
+  headerActions?: React.ReactNode;
+  /** Optional sidebar footer content */
+  sidebarFooter?: React.ReactNode;
+  /** Shell height */
+  height?: 'full' | 'auto' | string | number;
+  /** Sidebar thin size (when collapsed) */
+  sidebarThinSize?: number;
+  /** Whether sidebar is resizable */
+  sidebarResizable?: boolean;
+  /** Mobile trigger icon */
+  mobileTriggerIcon?: React.ReactNode;
+  /** Current pathname for active state detection */
+  pathname?: string;
+  /** Link component to use (defaults to 'a') */
+  linkComponent?: React.ComponentType<{ href: string; children: React.ReactNode; prefetch?: boolean; 'aria-label'?: string }>;
+}
+
+export function DocsShell({
+  children,
+  navigation,
+  logo,
+  headerActions,
+  sidebarFooter,
+  height,
+  sidebarThinSize = 80,
+  sidebarResizable = true,
+  mobileTriggerIcon,
+  pathname = '',
+  linkComponent,
+}: DocsShellProps) {
+  const [sidebarPresentation, setSidebarPresentation] = useState<'thin' | 'expanded'>('expanded');
+
+  // Combine headerActions with sidebarFooter
+  const footerContent = sidebarFooter || headerActions ? (
+    <Flex gap="2" align="center">
+      {headerActions}
+      {sidebarFooter}
+    </Flex>
+  ) : undefined;
+
+  return (
+    <Shell.Root height={height}>
+      <Shell.Sidebar
+        toggleModes="single"
+        thinSize={sidebarThinSize}
+        resizable={sidebarResizable}
+        defaultState={{ initial: 'collapsed', sm: 'expanded' }}
+        onStateChange={(state) => setSidebarPresentation(state === 'thin' ? 'thin' : 'expanded')}
+        presentation={{ initial: 'overlay', sm: 'fixed' }}
+      >
+        <DocsSidebar
+          navigation={navigation}
+          logo={logo}
+          presentation={sidebarPresentation}
+          footer={footerContent}
+          pathname={pathname}
+          linkComponent={linkComponent}
+        />
+      </Shell.Sidebar>
+
+      <Shell.Content>
+        {/* Mobile trigger */}
+        <Flex
+          display={{ initial: 'flex', sm: 'none' }}
+          position="fixed"
+          top="4"
+          left="4"
+          align="center"
+          justify="center"
+          width="auto"
+          height="auto"
+          style={{ zIndex: 999 }}
+        >
+          <IconButton variant="ghost" size="3" highContrast color="gray" asChild>
+            <Shell.Trigger target="sidebar">
+              {mobileTriggerIcon || (
+                <svg
+                  width="16"
+                  height="16"
+                  viewBox="0 0 16 16"
+                  fill="none"
+                  xmlns="http://www.w3.org/2000/svg"
+                >
+                  <path
+                    d="M2 4h12M2 8h12M2 12h12"
+                    stroke="currentColor"
+                    strokeWidth="1.5"
+                    strokeLinecap="round"
+                  />
+                </svg>
+              )}
+            </Shell.Trigger>
+          </IconButton>
+        </Flex>
+
+        {children}
+      </Shell.Content>
+    </Shell.Root>
+  );
+}

package/src/components/docs/docs-sidebar.tsx

@@ -0,0 +1,180 @@
+'use client';
+
+import React, { isValidElement } from 'react';
+import { Sidebar, Flex, Avatar } from '@kushagradhawan/kookie-ui';
+import { HugeiconsIcon } from '@hugeicons/react';
+import type { DocsNavigationConfig, DocsLogoConfig } from './types.js';
+
+// HugeIcons IconSvgObject type - readonly array of tuples with tag name and attributes
+type IconSvgObject = readonly (readonly [string, { readonly [key: string]: string | number }])[];
+
+type AccentColor =
+  | 'gray'
+  | 'gold'
+  | 'bronze'
+  | 'brown'
+  | 'yellow'
+  | 'amber'
+  | 'orange'
+  | 'tomato'
+  | 'red'
+  | 'ruby'
+  | 'crimson'
+  | 'pink'
+  | 'plum'
+  | 'purple'
+  | 'violet'
+  | 'iris'
+  | 'indigo'
+  | 'blue'
+  | 'cyan'
+  | 'teal'
+  | 'jade'
+  | 'green'
+  | 'grass'
+  | 'lime'
+  | 'mint'
+  | 'sky';
+
+export interface DocsSidebarProps {
+  /** Navigation configuration */
+  navigation: DocsNavigationConfig;
+  /** Logo configuration */
+  logo?: DocsLogoConfig;
+  /** Presentation mode from parent Shell */
+  presentation?: 'thin' | 'expanded';
+  /** Footer content */
+  footer?: React.ReactNode;
+  /** Sidebar size */
+  size?: '1' | '2';
+  /** Sidebar variant */
+  variant?: 'soft' | 'outline' | 'surface' | 'ghost';
+  /** Menu item variant */
+  menuVariant?: 'solid' | 'soft';
+  /** Accent color */
+  color?: AccentColor;
+  /** Current pathname for active state detection */
+  pathname?: string;
+  /** Link component to use (defaults to 'a') */
+  linkComponent?: React.ComponentType<{ href: string; children: React.ReactNode; prefetch?: boolean; 'aria-label'?: string }>;
+}
+
+export function DocsSidebar({
+  navigation,
+  logo,
+  presentation = 'expanded',
+  footer,
+  size = '2',
+  variant = 'soft',
+  menuVariant = 'soft',
+  color = 'gray',
+  pathname = '',
+  linkComponent: LinkComponent = 'a' as any,
+}: DocsSidebarProps) {
+
+  // Helper to check if icon is HugeIcons IconSvgObject format
+  const isIconSvgObject = (icon: unknown): icon is IconSvgObject => {
+    return Array.isArray(icon) && icon.length > 0 && Array.isArray(icon[0]);
+  };
+
+  // Helper to render icon
+  const renderIcon = (icon: React.ComponentType<{ className?: string }> | React.ReactNode | IconSvgObject) => {
+    if (!icon) return null;
+    if (isValidElement(icon)) return icon;
+    // Handle HugeIcons IconSvgObject format
+    if (isIconSvgObject(icon)) {
+      return <HugeiconsIcon icon={icon} size={16} />;
+    }
+    if (typeof icon === 'function') {
+      const IconComponent = icon as React.ComponentType<{ className?: string }>;
+      return <IconComponent />;
+    }
+    return null;
+  };
+
+  return (
+    <Sidebar.Root
+      size={size}
+      variant={variant}
+      color={color}
+      menuVariant={menuVariant}
+      presentation={presentation}
+    >
+      {logo && (
+        <Sidebar.Header>
+          <Flex justify="between" align="center" width="100%">
+            <LinkComponent href={logo.href || '/'} aria-label={logo.alt || 'Home'}>
+              <Flex align="center" gap="2">
+                <Avatar fallback={logo.alt?.[0] || 'K'} size="2" src={logo.src} />
+              </Flex>
+            </LinkComponent>
+          </Flex>
+        </Sidebar.Header>
+      )}
+
+      <Sidebar.Content>
+        <Sidebar.Menu>
+          {navigation.groups.map((group) => (
+            <Sidebar.Group key={group.label}>
+              <Sidebar.GroupLabel>{group.label}</Sidebar.GroupLabel>
+              <Sidebar.GroupContent>
+                {group.items.map((item) => {
+                  // Check if this item or any nested item is active
+                  const hasNestedItems = item.items && item.items.length > 0;
+                  const isNestedActive = hasNestedItems
+                    ? item.items!.some((subItem) => pathname === subItem.href)
+                    : false;
+
+                  if (hasNestedItems) {
+                    return (
+                      <Sidebar.MenuItem key={item.href}>
+                        <Sidebar.MenuSub defaultOpen={isNestedActive}>
+                          <Sidebar.MenuSubTrigger>
+                            {renderIcon(item.icon)}
+                            {item.title}
+                          </Sidebar.MenuSubTrigger>
+                          <Sidebar.MenuSubContent>
+                            {item.items!.map((subItem) => (
+                              <Sidebar.MenuButton
+                                asChild
+                                key={subItem.href}
+                                isActive={pathname === subItem.href}
+                              >
+                                <LinkComponent href={subItem.href}>
+                                  {renderIcon(subItem.icon)}
+                                  <span className="rt-SidebarMenuLabel">{subItem.title}</span>
+                                </LinkComponent>
+                              </Sidebar.MenuButton>
+                            ))}
+                          </Sidebar.MenuSubContent>
+                        </Sidebar.MenuSub>
+                      </Sidebar.MenuItem>
+                    );
+                  }
+
+                  // Regular menu item
+                  return (
+                    <Sidebar.MenuItem key={item.href}>
+                      <Sidebar.MenuButton
+                        asChild
+                        isActive={pathname === item.href}
+                        badge={item.badge}
+                      >
+                        <LinkComponent href={item.href}>
+                          {renderIcon(item.icon)}
+                          <span className="rt-SidebarMenuLabel">{item.title}</span>
+                        </LinkComponent>
+                      </Sidebar.MenuButton>
+                    </Sidebar.MenuItem>
+                  );
+                })}
+              </Sidebar.GroupContent>
+            </Sidebar.Group>
+          ))}
+        </Sidebar.Menu>
+      </Sidebar.Content>
+
+      {footer && <Sidebar.Footer>{footer}</Sidebar.Footer>}
+    </Sidebar.Root>
+  );
+}

package/src/components/docs/index.ts

@@ -0,0 +1,16 @@
+// Types
+export type {
+  DocsNavigationItem,
+  DocsNavigationGroup,
+  DocsNavigationConfig,
+  DocsPageMeta,
+  DocsLogoConfig,
+  TocItem,
+} from './types.js';
+
+// Components
+export { TableOfContents } from './table-of-contents.js';
+export { DocsSidebar } from './docs-sidebar.js';
+export { DocsPageHeader } from './docs-page-header.js';
+export { DocsPage } from './docs-page.js';
+export { DocsShell } from './docs-shell.js';

package/src/components/docs/table-of-contents.tsx

@@ -0,0 +1,157 @@
+'use client';
+
+import React, { useEffect, useState, useCallback, useRef, memo } from 'react';
+import { Box, Text, Link, Flex } from '@kushagradhawan/kookie-ui';
+import type { TocItem } from './types.js';
+
+// Generate slug from heading text
+const generateSlug = (text: string): string => {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .trim();
+};
+
+export interface TableOfContentsProps {
+  className?: string;
+  /** Heading levels to include (default: [2]) */
+  levels?: number[];
+  /** Title shown above TOC (default: "On this page") */
+  title?: string;
+  /** Optional wrapper for the TOC content */
+  renderContainer?: (tocContent: React.ReactNode) => React.ReactNode | null;
+}
+
+export const TableOfContents = memo(function TableOfContents({
+  className,
+  levels = [2],
+  title = 'On this page',
+  renderContainer,
+}: TableOfContentsProps) {
+  const [toc, setToc] = useState<TocItem[]>([]);
+  const [activeId, setActiveId] = useState<string>('');
+  const observerRef = useRef<IntersectionObserver | null>(null);
+  const rafIdRef = useRef<number | null>(null);
+  const timeoutIdRef = useRef<number | null>(null);
+
+  const extractHeadings = useCallback(() => {
+    rafIdRef.current = requestAnimationFrame(() => {
+      const contentArea = document.querySelector('[data-content-area]');
+      if (!contentArea) return;
+
+      // Build selector from levels
+      const selector = levels.map((l) => `h${l}`).join(', ');
+      const headingElements = Array.from(contentArea.querySelectorAll(selector));
+
+      const headings = headingElements
+        .map((heading) => {
+          const text = heading.textContent || '';
+          let id = heading.id;
+
+          if (!id && text) {
+            id = generateSlug(text);
+            heading.id = id;
+          }
+
+          return {
+            id,
+            text,
+            level: parseInt(heading.tagName.charAt(1)),
+          };
+        })
+        .filter((item) => item.id && item.text);
+
+      setToc(headings);
+
+      // Disconnect any previous observer
+      if (observerRef.current) {
+        observerRef.current.disconnect();
+        observerRef.current = null;
+      }
+
+      if (headings.length > 0) {
+        const observer = new IntersectionObserver(
+          (entries) => {
+            entries.forEach((entry) => {
+              if (entry.isIntersecting) {
+                setActiveId(entry.target.id);
+              }
+            });
+          },
+          { rootMargin: '-20% 0% -35% 0%' }
+        );
+
+        headings.forEach(({ id }) => {
+          const element = document.getElementById(id);
+          if (element) observer.observe(element);
+        });
+
+        observerRef.current = observer;
+      }
+    });
+  }, [levels]);
+
+  useEffect(() => {
+    // Initial extraction with delay for DOM readiness
+    timeoutIdRef.current = window.setTimeout(() => {
+      extractHeadings();
+    }, 100);
+
+    return () => {
+      if (timeoutIdRef.current) {
+        clearTimeout(timeoutIdRef.current);
+        timeoutIdRef.current = null;
+      }
+      if (rafIdRef.current) {
+        cancelAnimationFrame(rafIdRef.current);
+        rafIdRef.current = null;
+      }
+      if (observerRef.current) {
+        observerRef.current.disconnect();
+        observerRef.current = null;
+      }
+    };
+  }, [extractHeadings]);
+
+  const getLinkStyle = useCallback(
+    (level: number): React.CSSProperties => ({
+      display: 'block',
+      whiteSpace: 'nowrap',
+      overflow: 'hidden',
+      textOverflow: 'ellipsis',
+      paddingLeft: level > 2 ? `${(level - 2) * 12}px` : '0',
+    }),
+    []
+  );
+
+  if (toc.length === 0) return null;
+
+  const tocContent = (
+    <Flex direction="column" gap="3" className={className}>
+      <Text size="1" weight="medium" color="gray">
+        {title}
+      </Text>
+      <Flex direction="column" gap="2">
+        {toc.map((item) => (
+          <Link
+            key={item.id}
+            color="gray"
+            highContrast={activeId === item.id}
+            size="1"
+            href={`#${item.id}`}
+            style={getLinkStyle(item.level)}
+          >
+            {item.text}
+          </Link>
+        ))}
+      </Flex>
+    </Flex>
+  );
+
+  if (renderContainer) {
+    return renderContainer(tocContent);
+  }
+
+  return tocContent;
+});

package/src/components/docs/types.ts

@@ -0,0 +1,45 @@
+import type { ReactNode, ComponentType } from 'react';
+
+// HugeIcons IconSvgObject type - readonly array of tuples with tag name and attributes
+type IconSvgObject = readonly (readonly [string, { readonly [key: string]: string | number }])[];
+
+// Navigation types
+export interface DocsNavigationItem {
+  href: string;
+  title: string;
+  // Support React components, ReactNode, or HugeIcons IconSvgObject format
+  icon?: ComponentType<{ className?: string }> | ReactNode | IconSvgObject;
+  badge?: string;
+  items?: DocsNavigationItem[];
+}
+
+export interface DocsNavigationGroup {
+  label: string;
+  items: DocsNavigationItem[];
+}
+
+export interface DocsNavigationConfig {
+  groups: DocsNavigationGroup[];
+}
+
+// Page metadata types
+export interface DocsPageMeta {
+  title: string;
+  description?: string;
+  category?: string;
+  source?: string;
+}
+
+// Logo configuration
+export interface DocsLogoConfig {
+  src: string;
+  alt?: string;
+  href?: string;
+}
+
+// Table of contents types
+export interface TocItem {
+  id: string;
+  text: string;
+  level: number;
+}

package/src/components/index.ts

@@ -1,3 +1,4 @@
 export * from './code/index.js';
+export * from './docs/index.js';
 export * from './hero/index.js';
 export * from './markdown/index.js';