@knymbus/voxel-ui 1.0.0

package/src/components/tabs/TabButtonGroup.tsx

@@ -0,0 +1,82 @@
+import React, { useState, useEffect, useRef } from 'react';
+import { useTab } from './useTab';
+import { TabVariant } from './types';
+import TabButton from './TabButton'; // Imported to execute type-checking audits
+
+interface TabButtonGroupProps {
+  children: React.ReactNode;
+  variant?: TabVariant;
+  scopeName?: string;
+}
+
+export default function TabButtonGroup({ 
+  children, 
+  variant = 'underline', 
+  scopeName = 'default' 
+}: TabButtonGroupProps) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const { activeTab } = useTab(scopeName);
+  
+  const [lineStyles, setLineStyles] = useState<React.CSSProperties>({ left: 0, width: 0, opacity: 0 });
+  const [hoveredId, setHoveredId] = useState<string | null>(null);
+
+  // --- STRICT CHILDREN SUB-COMPONENT VALIDATION ENGINE LOOP ---
+  const validatedChildren = React.Children.map(children, (child) => {
+    if (!React.isValidElement(child)) return null;
+
+    // Verify if the child component reference maps directly to our TabButton signature
+    if (child.type !== TabButton) {
+      console.warn(
+        `[Voxel UI Validation Warning]: TabButtonGroup scope "${scopeName}" only accepts sub-children elements of type <TabButton />. Ignored invalid component node.`
+      );
+      return null;
+    }
+    return child;
+  });
+
+  useEffect(() => {
+    if (variant !== 'sliding-underline' || !containerRef.current) return;
+
+    const targetId = hoveredId || activeTab || 'tab1'; 
+    const targetElement = containerRef.current.querySelector(`[data-id="${targetId}"]`) as HTMLElement;
+
+    if (targetElement) {
+      setLineStyles({
+        left: `${targetElement.offsetLeft}px`,
+        width: `${targetElement.offsetWidth}px`,
+        opacity: 1,
+        backgroundColor: hoveredId && hoveredId !== activeTab ? 'var(--color-vsc-text)' : 'var(--color-vsc-accent)'
+      });
+    }
+  }, [activeTab, hoveredId, variant]);
+
+  const containerClasses = {
+    underline: 'flex items-center space-x-2 border-b border-vsc-border w-full bg-vsc-bg pb-[1px]',
+    'sliding-underline': 'relative flex items-center border-b border-vsc-border w-full bg-vsc-bg pb-[2px]',
+    pill: 'flex items-center space-x-1.5 p-1 bg-vsc-sidebar rounded-full w-fit',
+    vscode: 'flex items-center h-9 bg-vsc-sidebar border-b border-vsc-border w-full overflow-hidden',
+    ghost: 'flex items-center space-x-1 p-1 bg-vsc-bg-input border border-vsc-border rounded'
+  }[variant];
+
+  return (
+    <div 
+      ref={containerRef}
+      onMouseOver={(e) => {
+        const btn = (e.target as HTMLElement).closest('[data-id]');
+        if (btn) setHoveredId(btn.getAttribute('data-id'));
+      }}
+      onMouseLeave={() => setHoveredId(null)}
+      className={`${containerClasses} select-none`}
+    >
+      {/* Render exclusively the type-validated sub-nodes collection array */}
+      {validatedChildren}
+
+      {variant === 'sliding-underline' && (
+        <div 
+          className="absolute bottom-0 h-0.5 rounded-t transition-all duration-200 ease-out pointer-events-none z-20"
+          style={lineStyles}
+        />
+      )}
+    </div>
+  );
+}

package/src/components/tabs/TabPanel.tsx

@@ -0,0 +1,44 @@
+import React, { useState, useEffect } from 'react';
+import { useTabListContext } from './TabPanelList';
+
+interface TabPanelProps {
+  children: React.ReactNode;
+  id: string;        
+  persist?: boolean; 
+}
+
+export default function TabPanel({ children, id, persist = false }: TabPanelProps) {
+  const { activeTabId } = useTabListContext();
+  const isCurrent = activeTabId === id;
+  
+  const [hasRenderedOnce, setHasRenderedOnce] = useState<boolean>(false);
+
+  useEffect(() => {
+    if (isCurrent && !hasRenderedOnce) {
+      setHasRenderedOnce(true);
+    }
+  }, [isCurrent, hasRenderedOnce]);
+
+  if (!hasRenderedOnce) return null;
+  if (!persist && !isCurrent) return null;
+
+  return (
+    <div
+      className={`absolute inset-0 w-full h-full bg-vsc-bg transition-all duration-300 ease-in-out ${
+        isCurrent
+          ? 'opacity-100 scale-100 z-10 pointer-events-auto visible'
+          : 'opacity-0 scale-[0.99] z-0 pointer-events-none invisible delay-75'
+      }`}
+    >
+      {/* 
+        Inner layout wrapper applies a micro-blur and fine opacity mask cross-fade 
+        to ensure background elements never clip through transparent gaps during transitions.
+      */}
+      <div className={`w-full h-full transition-opacity duration-300 ${
+        isCurrent ? 'opacity-100' : 'opacity-0'
+      }`}>
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/components/tabs/TabPanelList.tsx

@@ -0,0 +1,31 @@
+import React, { useEffect, createContext, useContext } from 'react';
+import { useTab } from './useTab';
+
+interface TabPanelListProps {
+  children: React.ReactNode;
+  targetScopeName: string; // Ties this structural list panel block to a named useTab hook loop
+  defaultValue: string;    // Initial focus viewport tab on render
+}
+
+const TabListContext = createContext<{ activeTabId: string | undefined }>({ activeTabId: undefined });
+
+export const useTabListContext = () => useContext(TabListContext);
+
+export default function TabPanelList({ children, targetScopeName, defaultValue }: TabPanelListProps) {
+  const { activeTab, registerDefault } = useTab(targetScopeName);
+
+  // Initialize defaultValue into state if it's the first execution pass
+  useEffect(() => {
+    registerDefault(defaultValue);
+  }, [defaultValue, registerDefault]);
+
+  const activeTabId = activeTab || defaultValue;
+
+  return (
+    <TabListContext.Provider value={{ activeTabId }}>
+      <div className="relative w-full h-full min-h-0 flex-1 overflow-hidden bg-vsc-bg">
+        {children}
+      </div>
+    </TabListContext.Provider>
+  );
+}

package/src/components/tabs/Tabs.stories.tsx

@@ -0,0 +1,71 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import TabPanelList from './TabPanelList';
+import TabPanel from './TabPanel';
+import TabButtonGroup from './TabButtonGroup';
+import TabButton from './TabButton';
+
+const meta: Meta = {
+  title: 'Navigation/VoxelTabsSuite',
+  parameters: {
+    layout: 'padded',
+  },
+};
+export default meta;
+
+// Mock SVG icons to test start/end positioning layout slots
+const BoxIcon = () => <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M20 7l-8-4-8 4m16 0l-8 4m8-4v10l-8 4m0-10L4 7m8 4v10M4 7v10l8 4" /></svg>;
+const CheckIcon = () => <svg className="w-3 h-3 text-emerald-500" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M5 13l4 4L19 7" /></svg>;
+const CrossIcon = () => <svg className="w-3 h-3 text-rose-500" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M6 18L18 6M6 6l12 12" /></svg>;
+
+const VariantSandboxShowcase = ({ variant }: { variant: 'underline' | 'pill' | 'vscode' | 'ghost' | 'sliding-underline' }) => {
+  const scopeId = `scope_variant_${variant}`;
+  
+  return (
+    <div className="space-y-3 p-4 border border-vsc-border rounded bg-vsc-bg max-w-2xl mb-6 shadow-sm">
+      <div className="text-[10px] font-bold text-vsc-muted uppercase tracking-wider">
+        Style Profile Variant: <span className="text-vsc-accent">{variant}</span>
+      </div>
+
+      {/* Render the core active button groups panel elements */}
+      <TabButtonGroup variant={variant}>
+        <TabButton id="tab1" scopeName={scopeId} variant={variant} startIcon={<BoxIcon />}>
+          Manifest Data Cargo
+        </TabButton>
+        <TabButton id="tab2" scopeName={scopeId} variant={variant} endIcon={<CheckIcon />}>
+          Delivered Queue
+        </TabButton>
+        <TabButton id="tab3" scopeName={scopeId} variant={variant} endIcon={<CrossIcon />}>
+          Exceptions
+        </TabButton>
+      </TabButtonGroup>
+
+      {/* Render matching core content canvas wrappers */}
+      <div className="h-24 relative border border-vsc-border rounded-sm bg-vsc-bg-input p-3 overflow-hidden">
+        <TabPanelList targetScopeName={scopeId} defaultValue="tab1">
+          <TabPanel id="tab1" persist={true}>
+            <p className="text-xs text-vsc-text">📦 <b>Voxel Panel Alpha:</b> Staged database manifest streams active. Core inputs remain cached securely in background channels.</p>
+          </TabPanel>
+          <TabPanel id="tab2" persist={false}>
+            <p className="text-xs text-vsc-text">✨ <b>Voxel Panel Beta:</b> Real-time delivered telemetry nodes parsing clean. Data refreshes instantly on blur cycles.</p>
+          </TabPanel>
+          <TabPanel id="tab3" persist={false}>
+            <p className="text-xs text-vsc-text">⚠️ <b>Voxel Panel Gamma:</b> 3 logistics exceptions flagged across custom terminal checks loops corridors.</p>
+          </TabPanel>
+        </TabPanelList>
+      </div>
+    </div>
+  );
+};
+
+export const CombinedVoxelSuiteDemo: StoryObj = {
+  render: () => (
+    <div className="p-2 space-y-4 bg-vsc-sidebar min-h-screen">
+      <VariantSandboxShowcase variant="underline" />
+      <VariantSandboxShowcase variant="sliding-underline" />
+      <VariantSandboxShowcase variant="pill" />
+      <VariantSandboxShowcase variant="vscode" />
+      <VariantSandboxShowcase variant="ghost" />
+    </div>
+  ),
+};

package/src/components/tabs/index.ts

@@ -0,0 +1,5 @@
+export { default as TabPanelList } from './TabPanelList';
+export { default as TabPanel } from './TabPanel';
+export { default as TabButton } from './TabButton';
+export { useTab } from './useTab';
+export * from './types';

package/src/components/tabs/types.ts

@@ -0,0 +1,10 @@
+export type TabVariant = 'underline' | 'pill' | 'vscode' | 'ghost' | 'sliding-underline';
+
+export interface TabButtonProps {
+  id: string;
+  scopeName: string;
+  children: React.ReactNode;
+  variant?: TabVariant;
+  startIcon?: React.ReactNode;
+  endIcon?: React.ReactNode;
+}

package/src/components/tabs/useTab.ts

@@ -0,0 +1,33 @@
+import { create } from 'zustand';
+
+interface TabStateRegistry {
+  activeTabs: Record<string, string>; // Maps named scopes to their current active tab id
+  setActiveTab: (scopeName: string, tabId: string) => void;
+  initializeTab: (scopeName: string, defaultTabId: string) => void;
+}
+
+// Global lightweight store to handle cross-component communication links effortlessly
+const useTabStore = create<TabStateRegistry>((set) => ({
+  activeTabs: {},
+  setActiveTab: (scopeName, tabId) => 
+    set((state) => ({
+      activeTabs: { ...state.activeTabs, [scopeName]: tabId }
+    })),
+  initializeTab: (scopeName, defaultTabId) =>
+    set((state) => {
+      if (state.activeTabs[scopeName]) return {}; // Don't wipe state if already initialized
+      return { activeTabs: { ...state.activeTabs, [scopeName]: defaultTabId } };
+    })
+}));
+
+export function useTab(scopeName: string) {
+  const activeTab = useTabStore((state) => state.activeTabs[scopeName]);
+  const setActiveTab = useTabStore((state) => state.setActiveTab);
+  const initializeTab = useTabStore((state) => state.initializeTab);
+
+  return {
+    activeTab,
+    changeTab: (tabId: string) => setActiveTab(scopeName, tabId),
+    registerDefault: (defaultTabId: string) => initializeTab(scopeName, defaultTabId)
+  };
+}

package/src/index.css

@@ -0,0 +1,35 @@
+@import "tailwindcss"; 
+
+
+/* 🎛️ Tailwind v4 Theme Extension Configuration Panel */
+@theme {
+  --color-vsc-bg: #ffffff;
+  --color-vsc-sidebar: #f3f3f3;
+  --color-vsc-border: #e4e4e7;
+  --color-vsc-accent: #007acc;
+  --color-vsc-accent-hover: #0062a3;
+  --color-vsc-hover: #e8e8e8;
+  --color-vsc-text: #333333;
+  
+  --color-vsc-button-text: #ffffff;
+  --color-vsc-muted: #6a737d;
+  --color-vsc-bg-input: #f6f8fa;
+}
+
+/* ==========================================================================
+   DARK MODE OVERRIDES (Triggers when parent layout has the ".dark" class)
+   ========================================================================== */
+@layer base {
+  .dark {
+    --color-vsc-bg: #1e1e1e;
+    --color-vsc-sidebar: #252526;
+    --color-vsc-border: #3c3c3c;
+    --color-vsc-accent: #007acc;
+    --color-vsc-accent-hover: #0062a3;
+    --color-vsc-hover: #2a2d2e;
+    --color-vsc-text: #cccccc;
+
+    --color-vsc-muted: #8b949e;
+    --color-vsc-bg-input: #1f1f1f;
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './components/resizable';
+export * from './components/tabs';
+export * from './components/button';
+export * from './components/icons'
+export * from './components/search';

package/src/vite-env.d.ts

@@ -0,0 +1,5 @@
+// Explicitly declare that standard and nested style sheets are valid asset modules
+declare module '*.css' {
+  const content: Record<string, string>;
+  export default content;
+}

package/tsconfig.json

@@ -0,0 +1,47 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": [
+      "DOM",
+      "DOM.Iterable",
+      "ES2022"
+    ],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    /* 🔬 Bundler & Composable Resolution Tuning */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": false,
+    "declaration": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true, // Overridden by tsc in build scripts to output standalone declarations (.d.ts)
+    "jsx": "react-jsx",
+    /* 🛡️ Strict Quality Guardrails */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "types": [
+      "node",
+      "vite/client"
+    ],
+    "ignoreDeprecations": "6.0",
+    /* 📦 Library Path Mapping Fallbacks */
+    "baseUrl": ".",
+    "paths": {
+      "@/*": [
+        "src/*"
+      ]
+    }
+  },
+  "include": [
+    "src"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.stories.tsx",
+    "**/*.test.ts"
+  ]
+}

package/vite.config.ts

@@ -0,0 +1,64 @@
+/// <reference types="vitest/config" />
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import dts from 'vite-plugin-dts';
+import { resolve } from 'path';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';
+import { playwright } from '@vitest/browser-playwright';
+const dirname = typeof __dirname !== 'undefined' ? __dirname : path.dirname(fileURLToPath(import.meta.url));
+import tailwindcss from '@tailwindcss/vite';
+
+// More info at: https://storybook.js.org/docs/next/writing-tests/integrations/vitest-addon
+export default defineConfig({
+  plugins: [
+    tailwindcss(),
+    react(),
+    // Auto-generates independent TypeScript type declaration files (.d.ts) matching paths
+    dts({
+      insertTypesEntry: true,
+      include: ['src']
+    })],
+  build: {
+    lib: {
+      entry: {
+        index: resolve(__dirname, 'src/index.ts'),
+        'components/tabs/index': resolve(__dirname, 'src/components/tabs/index.ts'),
+        'components/resizable/index': resolve(__dirname, 'src/components/resizable/index.ts')
+      },
+      formats: ['es'] // Output strictly as modern ES Modules for dead-code elimination (tree-shaking)
+    },
+    rollupOptions: {
+      // Externalize react dependencies so they aren't bundled directly into your code copies
+      external: ['react', 'react-dom', 'zustand'],
+      output: {
+        assetFileNames: 'assets/[name].[ext]',
+        entryFileNames: '[name].js',
+        chunkFileNames: 'chunks/[name]-[hash].js'
+      }
+    }
+  },
+  test: {
+    projects: [{
+      extends: true,
+      plugins: [
+        // The plugin will run tests for the stories defined in your Storybook config
+        // See options at: https://storybook.js.org/docs/next/writing-tests/integrations/vitest-addon#storybooktest
+        storybookTest({
+          configDir: path.join(dirname, '.storybook')
+        })],
+      test: {
+        name: 'storybook',
+        browser: {
+          enabled: true,
+          headless: true,
+          provider: playwright({}),
+          instances: [{
+            browser: 'chromium'
+          }]
+        }
+      }
+    }]
+  }
+});

package/vitest.shims.d.ts

@@ -0,0 +1 @@
+/// <reference types="@vitest/browser-playwright" />