@knymbus/voxel-ui 1.0.0

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@knymbus/voxel-ui",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./tabs": {
+      "import": "./dist/components/tabs/index.js",
+      "types": "./dist/components/tabs/index.d.ts"
+    },
+    "./resizable": {
+      "import": "./dist/components/resizable/index.js",
+      "types": "./dist/components/resizable/index.d.ts"
+    },
+    "./button":{
+      "import": "./dist/components/button/index.js",
+      "types":"./dist/components/button/index.d.ts"
+    },
+    "./icons":{
+      "import": "./dist/components/icons/index.js",
+      "types":"./dist/components/icons/index.d.ts"
+    },
+    "./search":{
+      "import": "./dist/components/search/index.js",
+      "types":"./dist/components/search/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
+    "publish": "npm publish --access public",
+    "publish:patch": "npm version patch && npm publish --access public",
+    "publish:minor": "npm version minor && npm publish --access public"
+  },
+  "peerDependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "zustand": "^5.0.14"
+  },
+  "keywords": [],
+  "author": "Ovel Heslop <kayheslop@gmail.com>",
+  "license": "ISC",
+  "type": "commonjs",
+  "description": "",
+  "dependencies": {
+    "@storybook/addon-vitest": "^10.4.6",
+    "@storybook/react": "^10.4.6",
+    "@storybook/react-vite": "^10.4.6",
+    "@tailwindcss/vite": "^4.3.2",
+    "@types/node": "^26.0.1",
+    "@types/react": "^19.2.17",
+    "@vitejs/plugin-react": "^6.0.3",
+    "@vitest/browser-playwright": "^4.1.9",
+    "storybook": "^10.4.6",
+    "tailwindcss": "^4.3.2",
+    "typescript": "^6.0.3",
+    "vite": "^8.1.0",
+    "vite-plugin-dts": "^5.0.3"
+  }
+}

package/src/components/button/Button.stories.tsx

@@ -0,0 +1,70 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button } from './Button';
+import { Close, Terminal } from '../icons'
+
+// Mock Lucide-shaped functional layout components components interfaces
+const TerminalIcon = (props: { className?: string }) => <svg className={props.className} fill="none" stroke="currentColor" strokeWidth="2" viewBox="0 0 24 24"><path strokeLinecap="round" strokeLinejoin="round" d="M8 9l3 3-3 3m5 0h3M5 20h14a2 2 0 002-2V6a2 2 0 00-2-2H5a2 2 0 00-2 2v12a2 2 0 002 2z" /></svg>;
+const TrashIcon = (props: { className?: string }) => <svg className={props.className} fill="none" stroke="currentColor" strokeWidth="2" viewBox="0 0 24 24"><path strokeLinecap="round" strokeLinejoin="round" d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16" /></svg>;
+const ChevronRight = (props: { className?: string }) => <svg className={props.className} fill="none" stroke="currentColor" strokeWidth="2" viewBox="0 0 24 24"><path strokeLinecap="round" strokeLinejoin="round" d="M9 5l7 7-7 7" /></svg>;
+
+const meta: Meta<typeof Button> = {
+    title: 'Inputs/VoxelButtonUnion',
+    component: Button,
+    parameters: {
+        layout: 'centered',
+    },
+};
+export default meta;
+
+export const EnterpriseButtonShowcase: StoryObj<typeof Button> = {
+    render: () => (
+        <div className="p-6 bg-vsc-sidebar border border-vsc-border rounded-md space-y-6 max-w-2xl select-none text-vsc-text">
+
+            {/* Colors Section */}
+            <div className="space-y-2">
+                <p className="text-[10px] font-bold text-vsc-muted uppercase tracking-wider">Color Themes Mapping</p>
+                <div className="flex flex-wrap items-center gap-3">
+                    <Button color="primary">Commit Data</Button>
+                    <Button color="secondary">Secondary Box</Button>
+                    <Button color="ghost">Ghost Actions</Button>
+                    <Button color="danger" startIcon={TrashIcon}>Purge Log</Button>
+                    <Button color="vsc" startIcon={Terminal}>Console</Button>
+                </div>
+            </div>
+
+            {/* Sizing Rows */}
+            <div className="space-y-2">
+                <p className="text-[10px] font-bold text-vsc-muted uppercase tracking-wider">Functional Scaling Size Matrix</p>
+                <div className="flex flex-wrap items-end gap-3">
+                    <Button size="xs" color="primary">Extra Small (xs)</Button>
+                    <Button size="sm" color="primary">Small (sm)</Button>
+                    <Button size="md" color="primary">Default (md)</Button>
+                    <Button size="lg" color="primary">Large (lg)</Button>
+                </div>
+            </div>
+
+            {/* Icon Only Variants (Union Type Safe) */}
+            <div className="space-y-2">
+                <p className="text-[10px] font-bold text-vsc-muted uppercase tracking-wider">Icon-Only Variants (Strictly Restricted Type Union)</p>
+                <div className="flex flex-wrap items-center gap-3">
+                    <Button iconOnly={true} icon={Terminal} size="xs" color="vsc" />
+                    <Button iconOnly={true} icon={Terminal} size="sm" color="secondary" />
+                    <Button iconOnly={true} icon={Close} size="sm" color="secondary" />
+                    <Button iconOnly={true} icon={TrashIcon} size="md" color="danger" />
+                    <Button iconOnly={true} icon={ChevronRight} size="lg" color="primary" />
+                </div>
+            </div>
+
+            {/* Disabled States Verification */}
+            <div className="space-y-2">
+                <p className="text-[10px] font-bold text-vsc-muted uppercase tracking-wider">Disabled Guardrail Verification</p>
+                <div className="flex flex-wrap items-center gap-3">
+                    <Button color="primary" disabled startIcon={Terminal}>Locked Commit</Button>
+                    <Button iconOnly={true} icon={Terminal} size="md" color="secondary" disabled />
+                </div>
+            </div>
+
+        </div>
+    ),
+};

package/src/components/button/Button.tsx

@@ -0,0 +1,108 @@
+import React, { forwardRef } from 'react';
+
+// Define specialized type contract templates for our Lucide icon objects interfaces
+export type LucideIcon = React.ComponentType<{ className?: string }>;
+
+export type ButtonColor = "primary" | "secondary" | "ghost" | "danger" | "vsc";
+export type ButtonSize = "xs" | "sm" | "md" | "lg";
+
+// 1. Shared icon size map exposed for standalone use across the library
+export const buttonIconSizes: Record<ButtonSize, string> = {
+  xs: "w-3 h-3",
+  sm: "w-3.5 h-3.5",
+  md: "w-4 h-4",
+  lg: "w-5 h-5",
+};
+
+interface ButtonIconProps extends React.SVGProps<SVGSVGElement> {
+  icon: LucideIcon;
+  size?: ButtonSize;
+}
+
+// 2. Standalone ButtonIcon component UI
+export const ButtonIcon = ({ icon: Icon, size = "sm", className = "", ...props }: ButtonIconProps) => {
+  const sizeClass = buttonIconSizes[size];
+  return <Icon className={`${sizeClass} ${className}`.trim()} {...props} />;
+};
+
+interface BaseButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  size?: ButtonSize;
+  color?: ButtonColor;
+  startIcon?: LucideIcon;
+  endIcon?: LucideIcon;
+}
+
+interface IconButtonProps extends BaseButtonProps {
+  iconOnly: true;
+  icon: LucideIcon;
+  children?: never; // Explicitly compile-ban children text fields during icon-only layouts
+}
+
+interface StandardButtonProps extends BaseButtonProps {
+  iconOnly?: false;
+  icon?: never;
+  children: React.ReactNode;
+}
+
+export type ButtonProps = IconButtonProps | StandardButtonProps;
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>((props, ref) => {
+  const {
+    size = "sm",
+    color = "vsc",
+    iconOnly = false,
+    startIcon,
+    endIcon,
+    className = "",
+    disabled,
+    ...rest
+  } = props;
+
+  // Harmonized styling sheets mapped to your Tailwind v4 VS Code variable design tokens
+  const colorStyles: Record<ButtonColor, string> = {
+    primary: "bg-vsc-accent text-vsc-button-text hover:bg-vsc-accent-hover border border-transparent focus:border-vsc-accent/50",
+    secondary: "bg-vsc-bg border border-vsc-border text-vsc-text hover:bg-vsc-hover focus:border-vsc-accent",
+    ghost: "bg-transparent border border-transparent text-vsc-muted hover:bg-vsc-hover/40 hover:text-vsc-text focus:border-vsc-border",
+    danger: "bg-rose-500/10 border border-rose-500/20 text-rose-500 hover:bg-rose-500/20 focus:border-rose-500/50",
+    vsc: "bg-transparent text-vsc-text border border-transparent opacity-55 hover:opacity-100 hover:bg-vsc-hover focus:border-vsc-hover/50",
+  };
+
+  const sizeStyles: Record<ButtonSize, string> = {
+    xs: iconOnly ? "p-1 rounded-sm h-5 w-5" : "px-2 py-0.5 text-[10px] rounded-sm gap-1 h-5.5",
+    sm: iconOnly ? "p-1.5 rounded-md h-7 w-7" : "px-3 py-1.5 text-xs rounded-md gap-1.5 h-7.5",
+    md: iconOnly ? "p-2 rounded-md h-9 w-9" : "px-4 py-2 text-sm rounded-md gap-2 h-9",
+    lg: iconOnly ? "p-3 rounded-lg h-11 w-11" : "px-5 py-2.5 text-base rounded-lg gap-2.5 h-11",
+  };
+
+  const baseClasses = `
+    inline-flex items-center justify-center font-sans font-medium select-none 
+    outline-none focus:ring-0 cursor-pointer 
+    disabled:opacity-40 disabled:cursor-not-allowed disabled:transform-none disabled:active:scale-100 disabled:pointer-events-none
+    transition-all duration-150 cubic-bezier(0.34, 1.56, 0.64, 1)
+    active:scale-95 active:duration-75
+  `.trim();
+
+  const dynamicClasses = `${baseClasses} ${colorStyles[color]} ${sizeStyles[size]} ${className}`;
+
+  if (iconOnly) {
+    const iconOnlyElement = (props as IconButtonProps).icon;
+    return (
+      <button ref={ref} disabled={disabled} className={dynamicClasses} {...rest}>
+        <ButtonIcon icon={iconOnlyElement} size={size} />
+      </button>
+    );
+  }
+
+  return (
+    <button ref={ref} disabled={disabled} className={dynamicClasses} {...rest}>
+      {startIcon && <ButtonIcon icon={startIcon} size={size} />}
+      <span>{props.children}</span>
+      {endIcon && <ButtonIcon icon={endIcon} size={size} />}
+    </button>
+  );
+});
+
+Button.displayName = "Button";
+
+
+export default Button

package/src/components/button/ButtonGroup.stories.tsx

@@ -0,0 +1,63 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import ButtonGroup from './ButtonGroup';
+import { Button } from './Button';
+
+// Mock icons
+const PlayIcon = (props: { className?: string }) => <svg className={props.className} fill="none" stroke="currentColor" strokeWidth="2" viewBox="0 0 24 24"><path strokeLinecap="round" strokeLinejoin="round" d="M14.752 11.168l-3.197-2.132A1 1 0 0010 9.87v4.263a1 1 0 001.555.832l3.197-2.132a1 1 0 000-1.664z" /><path strokeLinecap="round" strokeLinejoin="round" d="M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg>;
+const DebugIcon = (props: { className?: string }) => <svg className={props.className} fill="none" stroke="currentColor" strokeWidth="2" viewBox="0 0 24 24"><path strokeLinecap="round" strokeLinejoin="round" d="M12 6V4m0 2a2 2 0 100 4m0-4a2 2 0 110 4m-6 8a2 2 0 100-4m0 4a2 2 0 110-4m0 4v2m0-6V4m6 6v10m6-2a2 2 0 100-4m0 4a2 2 0 110-4m0 4v2m0-6V4" /></svg>;
+const SettingsIcon = (props: { className?: string }) => <svg className={props.className} fill="none" stroke="currentColor" strokeWidth="2" viewBox="0 0 24 24"><path strokeLinecap="round" strokeLinejoin="round" d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z" /><path strokeLinecap="round" strokeLinejoin="round" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" /></svg>;
+const ChevronDown = (props: { className?: string }) => (
+  <svg className={props.className} fill="none" stroke="currentColor" strokeWidth="2.5" viewBox="0 0 24 24">
+    <path strokeLinecap="round" strokeLinejoin="round" d="M19 9l-7 7-7-7" />
+  </svg>
+);
+
+const meta: Meta<typeof ButtonGroup> = {
+  title: 'Inputs/VoxelButtonGroupAdvanced',
+  component: ButtonGroup,
+  parameters: {
+    layout: 'centered',
+  },
+};
+export default meta;
+
+export const AdvancedGroupSandbox: StoryObj<typeof ButtonGroup> = {
+  render: () => (
+    <div className="p-6 bg-vsc-bg border border-vsc-border rounded-md space-y-6 w-96 text-vsc-text">
+      
+      {/* 1. High-Fidelity Floating Ghost Toolbar (No outer borders, clean margins) */}
+      <div className="space-y-1.5">
+        <p className="text-[10px] font-bold text-vsc-muted uppercase tracking-wider">VS Code Style Floating Ghost Tray</p>
+        <div className="flex items-center justify-between bg-vsc-sidebar border border-vsc-border p-1 rounded-sm w-full">
+          <span className="text-xs font-mono text-vsc-muted pl-2">terminal.log</span>
+          <ButtonGroup variant="ghost" orientation="horizontal">
+            <Button iconOnly icon={PlayIcon} size="xs" title="Run Execution Pipeline" />
+            <Button iconOnly icon={DebugIcon} size="xs" title="Toggle Breakpoint Debugger" />
+            <Button iconOnly icon={SettingsIcon} size="xs" title="Configure Console Prefs" />
+          </ButtonGroup>
+        </div>
+      </div>
+
+      {/* 2. Custom Padding Spacing Gap Layout (Horizontal) */}
+      <div className="space-y-1.5">
+        <p className="text-[10px] font-bold text-vsc-muted uppercase tracking-wider">Horizontal Layout with 8px Padding Gap</p>
+        <ButtonGroup orientation="horizontal" gap={8}>
+          <Button color="primary" size="sm">Execute</Button>
+          <Button color="secondary" size="sm">Hold</Button>
+          <Button color="danger" size="sm">Abort</Button>
+        </ButtonGroup>
+      </div>
+
+      {/* 3. Custom Padding Spacing Gap Layout (Vertical) */}
+      <div className="space-y-1.5">
+        <p className="text-[10px] font-bold text-vsc-muted uppercase tracking-wider">Vertical Layout with 6px Padding Gap</p>
+        <ButtonGroup orientation="vertical" gap={6}>
+          <Button color="secondary" size="sm" startIcon={PlayIcon}>Initialize Channel</Button>
+          <Button color="secondary" size="sm" startIcon={SettingsIcon}>Hardware Override</Button>
+        </ButtonGroup>
+      </div>
+
+    </div>
+  ),
+};

package/src/components/button/ButtonGroup.tsx

@@ -0,0 +1,62 @@
+import React from 'react';
+
+export type GroupOrientation = 'horizontal' | 'vertical';
+export type GroupVariant = 'default' | 'ghost';
+
+interface ButtonGroupProps {
+  children: React.ReactNode;
+  orientation?: GroupOrientation;
+  variant?: GroupVariant;
+  gap?: number; // Custom distance padding spacing metric in pixels
+  className?: string;
+}
+
+export default function ButtonGroup({
+  children,
+  orientation = 'horizontal',
+  variant = 'default',
+  gap = 0,
+  className = ''
+}: ButtonGroupProps) {
+  
+  const baseClasses = "inline-flex bg-transparent rounded-sm select-none isolation-auto";
+  const isHorizontal = orientation === 'horizontal';
+  const hasGap = gap > 0;
+
+  // 1. Configure the core structural orientation layout flow axis
+  const orientationClass = isHorizontal ? 'flex-row' : 'flex-col';
+
+  // 2. Configure dense overlapping border adjustments only if elements are touching (gap === 0)
+  let structuralClasses = '';
+  if (!hasGap && variant === 'default') {
+    structuralClasses = isHorizontal
+      ? '[&>button:not(:first-child)]:-ml-[1px] [&>button:first-child]:rounded-l-sm [&>button:last-child]:rounded-r-sm [&>button:not(:first-child):not(:last-child)]:rounded-none'
+      : '[&>button:not(:first-child)]:-mt-[1px] [&>button:first-child]:rounded-t-sm [&>button:last-child]:rounded-b-sm [&>button:not(:first-child):not(:last-child)]:rounded-none';
+  } else if (hasGap) {
+    // Gracefully preserve default corner curves if items use independent grid spacing margins
+    structuralClasses = '[&>button]:rounded-sm';
+  }
+
+  // 3. Dynamically intercept sub-children buttons style attributes if variant is set to ghost
+  const processedChildren = React.Children.map(children, (child) => {
+    if (React.isValidElement(child) && variant === 'ghost') {
+      // Force individual child button components to drop colors and adopt ghost profiles implicitly
+      return React.cloneElement(child as React.ReactElement<any>, { color: 'ghost' });
+    }
+    return child;
+  });
+
+  // Calculate pixel spacing overrides using native inline CSS variables parameters
+  const inlineStyles: React.CSSProperties = hasGap ? {
+    gap: `${gap}px`
+  } : {};
+
+  return (
+    <div 
+      className={`${baseClasses} ${orientationClass} ${structuralClasses} ${className}`.trim()}
+      style={inlineStyles}
+    >
+      {processedChildren}
+    </div>
+  );
+}

package/src/components/button/SplitActionButton.tsx

@@ -0,0 +1,116 @@
+import { useState, useRef, useEffect } from 'react';
+import { Button, ButtonIcon } from './Button';
+import { SplitActionButtonProps } from './split-types';
+
+// Simple inner ChevronDown vector icon utility to match your signature
+const ChevronDownIcon = (props: { className?: string }) => (
+  <svg className={props.className} fill="none" stroke="currentColor" strokeWidth="2.5" viewBox="0 0 24 24">
+    <path strokeLinecap="round" strokeLinejoin="round" d="M19 9l-7 7-7-7" />
+  </svg>
+);
+
+export default function SplitActionButton({
+  children,
+  color = 'primary',
+  size = 'sm',
+  startIcon,
+  onMainActionClick,
+  menuItems,
+  className = ''
+}: SplitActionButtonProps) {
+  const [isOpen, setIsOpen] = useState<boolean>(false);
+  const containerRef = useRef<HTMLDivElement | null>(null);
+
+  // Auto-close menu drawer container panel if agent clicks outside the node frame
+  useEffect(() => {
+    const handleOutsideClick = (e: MouseEvent) => {
+      if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
+        setIsOpen(false);
+      }
+    };
+    if (isOpen) window.addEventListener('mousedown', handleOutsideClick);
+    return () => window.removeEventListener('mousedown', handleOutsideClick);
+  }, [isOpen]);
+
+  // High-fidelity sizing height-matching configuration maps overrides
+  const heightStyles = {
+    xs: { height: '22px', menuTop: '26px' },
+    sm: { height: '30px', menuTop: '34px' },
+    md: { height: '36px', menuTop: '40px' },
+    lg: { height: '44px', menuTop: '48px' }
+  }[size];
+
+  // Separator divider line colors dependent upon active color tokens
+  const separatorColor = color === 'primary' 
+    ? 'bg-vsc-accent-hover/60' 
+    : 'bg-vsc-border';
+
+  return (
+    <div 
+      ref={containerRef} 
+      className={`relative inline-flex items-center rounded-sm select-none isolation-auto ${className}`.trim()}
+      style={{ height: heightStyles.height }}
+    >
+      {/* 
+        1. Left Element: Primary Core Action Text Button.
+           Forces inner-right corners to flat 0 to resolve rounding gaps.
+      */}
+      <Button
+        color={color}
+        size={size}
+        startIcon={startIcon}
+        onClick={onMainActionClick}
+        className="rounded-r-none! h-full border-r-0"
+      >
+        {children}
+      </Button>
+
+      {/* 
+        2. Middle Element: High-Density Absolute Separator Dividing Line.
+           Bypasses border collisions cleanly.
+      */}
+      <div className={`w-px h-3/5 pointer-events-none z-20 ${separatorColor}`} />
+
+      {/* 
+        3. Right Element: Dropdown Arrow Icon Control Switch.
+           Forces inner-left corners to flat 0 to link cleanly to text block.
+      */}
+      <button
+        onClick={() => setIsOpen(!isOpen)}
+        className={`h-full flex items-center justify-center transition-all duration-150 focus:outline-none border-none outline-none rounded-l-none! cursor-pointer ${
+          color === 'primary' 
+            ? 'bg-vsc-accent text-vsc-button-text hover:bg-vsc-accent-hover' 
+            : color === 'secondary'
+              ? 'bg-vsc-bg border border-vsc-sidebar border-l-0 text-vsc-text hover:bg-vsc-hover'
+              : 'bg-transparent text-vsc-muted hover:bg-vsc-hover/40 hover:text-vsc-text'
+        } ${
+          size === 'xs' ? 'w-5 rounded-r-sm' : size === 'sm' ? 'w-7 rounded-r-md' : size === 'md' ? 'w-9 rounded-r-md' : 'w-11 rounded-r-lg'
+        }`}
+      >
+        <ChevronDownIcon className={`w-3.5 h-3.5 transition-transform duration-200 ${isOpen ? 'rotate-180' : ''}`} />
+      </button>
+
+      {/* 
+        4. Floating Options Drawer Menu Panel.
+           Renders absolutely using high z-index stacking rules.
+      */}
+      {isOpen && (
+        <div 
+          className="absolute left-0 w-48 bg-vsc-sidebar border border-vsc-border rounded shadow-xl z-50 p-1 flex flex-col font-sans text-xs text-vsc-text animate-in fade-in slide-in-from-top-2 duration-150"
+          style={{ top: heightStyles.menuTop }}
+        >
+          {menuItems.map((item) => (
+            <button
+              key={item.id}
+              onClick={() => { item.onClick(); setIsOpen(false); }}
+              className="w-full flex items-center gap-2 p-2 hover:bg-vsc-hover text-left rounded-sm border-none bg-transparent text-vsc-text hover:text-white cursor-pointer"
+            >
+              {item.startIcon && <ButtonIcon icon={item.startIcon} size="xs" className="opacity-70" />}
+              <span className="truncate">{item.label}</span>
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/button/SplitButton.stories.tsx

@@ -0,0 +1,55 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import SplitActionButton from './SplitActionButton';
+import { SplitActionMenuItem } from './split-types';
+
+const DocumentIcon = (props: { className?: string }) => <svg className={props.className} fill="none" stroke="currentColor" strokeWidth="2" viewBox="0 0 24 24"><path strokeLinecap="round" strokeLinejoin="round" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" /></svg>;
+const FolderIcon = (props: { className?: string }) => <svg className={props.className} fill="none" stroke="currentColor" strokeWidth="2" viewBox="0 0 24 24"><path strokeLinecap="round" strokeLinejoin="round" d="M3 7v10a2 2 0 002 2h14a2 2 0 002-2V9a2 2 0 00-2-2h-6l-2-2H5a2 2 0 00-2 2z" /></svg>;
+
+const meta: Meta<typeof SplitActionButton> = {
+    title: 'Inputs/VoxelSplitActionButton',
+    component: SplitActionButton,
+    parameters: {
+        layout: 'centered',
+    },
+};
+export default meta;
+
+const SAMPLE_MENU_ITEMS: SplitActionMenuItem[] = [
+    { id: 'new_file', label: 'Create Flat text file (.txt)', startIcon: DocumentIcon, onClick: () => alert('New text file staged!') },
+    { id: 'new_folder', label: 'Create Directory node', startIcon: FolderIcon, onClick: () => alert('New folder tree compiled!') }
+];
+
+export const SplitActionShowcaseSandbox: StoryObj<typeof SplitActionButton> = {
+    render: () => (
+        <div className="p-12 bg-vsc-sidebar border border-vsc-border rounded-md space-y-8 min-w-125 h-64 flex flex-col justify-start items-center select-none">
+
+            {/* Primary Split Menu (Vsc Accent Theme) */}
+            <div className="flex flex-col items-center gap-2">
+                <p className="text-[10px] font-bold text-vsc-muted uppercase tracking-wider">Primary Theme Split Profile</p>
+                <SplitActionButton
+                    color="primary"
+                    size="sm"
+                    onMainActionClick={() => alert('Primary Action Executed: Generating Default Manifest CSV!')}
+                    menuItems={SAMPLE_MENU_ITEMS}
+                >
+                    New Manifest File
+                </SplitActionButton>
+            </div>
+
+            {/* Secondary Split Menu (Matte Border Toolbar Theme) */}
+            <div className="flex flex-col items-center gap-2">
+                <p className="text-[10px] font-bold text-vsc-muted uppercase tracking-wider">Secondary Matte Toolbar Split Profile</p>
+                <SplitActionButton
+                    color="secondary"
+                    size="md"
+                    onMainActionClick={() => alert('Secondary Action Triggered!')}
+                    menuItems={SAMPLE_MENU_ITEMS}
+                >
+                    Options Explorer
+                </SplitActionButton>
+            </div>
+
+        </div>
+    ),
+};

package/src/components/button/index.ts

@@ -0,0 +1,7 @@
+export { default as Button } from './Button';
+export { default as ButtonGroup } from './ButtonGroup';
+export { default as SplitActionButton } from './SplitActionButton';
+
+// Types
+export * from './split-types';
+export * from './types';

package/src/components/button/split-types.ts

@@ -0,0 +1,18 @@
+import { LucideIcon, ButtonColor, ButtonSize } from './Button';
+
+export interface SplitActionMenuItem {
+  id: string;
+  label: string;
+  startIcon?: LucideIcon;
+  onClick: () => void;
+}
+
+export interface SplitActionButtonProps {
+  children: React.ReactNode;
+  color?: ButtonColor;
+  size?: ButtonSize;
+  startIcon?: LucideIcon;
+  onMainActionClick: () => void;
+  menuItems: SplitActionMenuItem[];
+  className?: string;
+}

package/src/components/button/types.ts

@@ -0,0 +1,10 @@
+export type ButtonVariant = 'primary' | 'secondary' | 'accent' | 'ghost' | 'danger';
+export type ButtonSize = 'xs' | 'sm' | 'md' | 'lg';
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  startIcon?: React.ReactNode;
+  endIcon?: React.ReactNode;
+  fullWidth?: boolean;
+}

package/src/components/icons/AddIcon.tsx

@@ -0,0 +1,10 @@
+import { IconProps } from "./types";
+
+export default function AddIcon({ size = 16, className = '', ...props }: IconProps) {
+  return (
+    <svg xmlns="http://w3.org" width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" className={`shrink-0 select-none ${className}`.trim()} {...props}>
+      <line x1="12" y1="5" x2="12" y2="19" />
+      <line x1="5" y1="12" x2="19" y2="12" />
+    </svg>
+  );
+}

package/src/components/icons/BlankDocIcon.tsx

@@ -0,0 +1,10 @@
+import { IconProps } from "./types";
+
+export default function BlankDocIcon({ size = 16, className = '', ...props }: IconProps) {
+  return (
+    <svg xmlns="http://w3.org" width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.2" strokeLinecap="round" strokeLinejoin="round" className={`shrink-0 select-none ${className}`.trim()} {...props}>
+      <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" />
+      <polyline points="14 2 14 8 20 8" />
+    </svg>
+  );
+}

package/src/components/icons/ChatIcon.tsx

@@ -0,0 +1,9 @@
+import { IconProps } from "./types";
+
+export default function ChatIcon({ size = 16, className = '', ...props }: IconProps) {
+  return (
+    <svg xmlns="http://w3.org" width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.2" strokeLinecap="round" strokeLinejoin="round" className={`shrink-0 select-none ${className}`.trim()} {...props}>
+      <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
+    </svg>
+  );
+}

package/src/components/icons/ChevronDownIcon.tsx

@@ -0,0 +1,9 @@
+import { IconProps } from "./types";
+
+export default function ChevronDownIcon({ size = 16, className = '', ...props }: IconProps) {
+  return (
+    <svg xmlns="http://w3.org" width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" className={`shrink-0 select-none ${className}`.trim()} {...props}>
+      <polyline points="6 9 12 15 18 9" />
+    </svg>
+  );
+}

package/src/components/icons/CloseIcon.tsx

@@ -0,0 +1,23 @@
+
+import { IconProps } from './types';
+
+export default function CloseIcon({ size = 16, className = '', ...props }: IconProps) {
+  return (
+    <svg
+      xmlns="http://w3.org"
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2.5" // Thicker stroke weight to guarantee sharp visibility on high-DPI/Retina screens
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={`shrink-0 select-none ${className}`.trim()}
+      {...props}
+    >
+      <line x1="18" y1="6" x2="6" y2="18" />
+      <line x1="6" y1="6" x2="18" y2="18" />
+    </svg>
+  );
+}