@k3-universe/react-kit 0.0.1 → 0.0.2

package/src/kit/builder/form/components/FormBuilder.tsx

@@ -4,7 +4,7 @@ import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
 import { cn } from '../../../../shadcn/lib/utils';
 import { Button } from '../../../../shadcn/ui/button';
-import { FormField } from './FormField';
+import { FormBuilderField } from './FormBuilderField';
 import SectionBuilder from '../../section/SectionBuilder';
 import type { SectionLayout, SectionGridOptions, SectionFlexOptions, SectionNode } from '../../section/types';
 import { AutocompleteFetcher, AutocompleteOption } from '../../../components/autocomplete/types';
@@ -70,6 +70,10 @@ export interface FormBuilderFieldConfig {
     value: any;
   }; // For conditional field visibility
   hidden?: boolean; // Declarative hide
+  // Label placement control across inputs
+  labelPlacement?: 'stacked' | 'inline' | 'hidden';
+  // Wrapper container className (applies to the field wrapper, not the input)
+  wrapperClassName?: string;
 }
 
 export interface FormBuilderSectionConfig {
@@ -108,6 +112,8 @@ export interface FormBuilderProps {
   actionsClassName?: string;
   showActions?: boolean;
   customActions?: React.ReactNode;
+  // UI: show a separator line above action buttons
+  showActionsSeparator?: boolean;
 }
 
 export function FormBuilder({
@@ -127,6 +133,7 @@ export function FormBuilder({
   actionsClassName,
   showActions = true,
   customActions,
+  showActionsSeparator = true,
 }: FormBuilderProps) {
   // Generate schema from field configs if not provided
   const generatedSchema = useMemo(() => {
@@ -309,18 +316,27 @@ export function FormBuilder({
 
   const { control, handleSubmit, reset, setValue, getValues, watch } = form;
 
-  // Watch all form values for dependencies
-  const watchedValues = watch();
+  // Determine if any field dependencies are declared
+  const hasDependencies = useMemo(() => {
+    return sections.some((section) =>
+      section.fields?.some((f) => Array.isArray(f.dependencies) && f.dependencies.length > 0),
+    );
+  }, [sections]);
+
+  // Only watch values when there are dependencies to respond to
+  // This prevents unnecessary re-renders that can cause focus loss
+  const emptyWatchedValues = useMemo(() => ({} as Record<string, any>), []);
+  const watchedValues = hasDependencies ? watch() : emptyWatchedValues;
 
   // Handle field dependencies
   const handleFieldDependencies = useCallback(
     (field: FormBuilderFieldConfig) => {
-      if (!field.dependencies) return {};
+      if (!hasDependencies || !field.dependencies) return {};
 
       const result: { disabled?: boolean; hidden?: boolean } = {};
 
       field.dependencies.forEach((dep) => {
-        const dependentValue = watchedValues[dep.field];
+        const dependentValue = (watchedValues as Record<string, any>)[dep.field];
         const conditionMet = dep.condition(dependentValue);
 
         switch (dep.action) {
@@ -350,7 +366,7 @@ export function FormBuilder({
 
       return result;
     },
-    [watchedValues, setValue, getValues],
+    [hasDependencies, watchedValues, setValue, getValues],
   );
 
   // Handle field change with custom onChange
@@ -387,7 +403,7 @@ export function FormBuilder({
         id: section.id ?? `section-${sectionIndex}`,
         title: section.title,
         subtitle: section.description,
-        variant: section.variant ?? 'card',
+        variant: section.variant ?? 'plain',
         className: section.className,
         layout: section.layout ?? 'grid',
         grid: section.grid ?? { cols: 1, mdCols: 2, gap: 'gap-4' },
@@ -403,9 +419,10 @@ export function FormBuilder({
             return {
               key: field.name,
               span: { base: 1, md: spanMd },
+              className: field.wrapperClassName,
               hidden: field.hidden,
               content: (
-                <FormField
+                <FormBuilderField
                   key={field.name}
                   field={{ ...field, disabled: field.disabled || fieldState.disabled }}
                   control={control}
@@ -430,7 +447,14 @@ export function FormBuilder({
         <SectionBuilder sections={sectionNodes} />
 
         {showActions && (
-          <div className={cn('flex flex-col sm:flex-row gap-3 pt-6 border-t', actionsClassName)}>
+          <div
+            className={cn(
+              'flex flex-col sm:flex-row gap-3',
+              showActionsSeparator && 'pt-6',
+              showActionsSeparator && 'border-t',
+              actionsClassName,
+            )}
+          >
             <Button type="submit" disabled={isSubmitting} className="sm:order-last">
               {isSubmitting ? 'Submitting...' : submitLabel}
             </Button>
@@ -442,7 +466,7 @@ export function FormBuilder({
             )}
 
             {onReset && (
-              <Button type="button" variant="ghost" onClick={handleReset} disabled={isSubmitting}>
+              <Button type="button" variant="outline" onClick={handleReset} disabled={isSubmitting}>
                 {resetLabel}
               </Button>
             )}

package/src/kit/builder/form/components/{FormActions.tsx → FormBuilderActions.tsx}

@@ -2,7 +2,7 @@ import React from 'react';
 import { Button } from '../../../../shadcn/ui/button';
 import { cn } from '../../../../shadcn/lib/utils';
 
-export interface FormActionsProps {
+export interface FormBuilderActionsProps {
   onSubmit?: () => void;
   onCancel?: () => void;
   onReset?: () => void;
@@ -19,7 +19,7 @@ export interface FormActionsProps {
   resetButtonProps?: React.ComponentProps<typeof Button>;
 }
 
-export function FormActions({
+export function FormBuilderActions({
   onSubmit,
   onCancel,
   onReset,
@@ -34,7 +34,7 @@ export function FormActions({
   submitButtonProps,
   cancelButtonProps,
   resetButtonProps,
-}: FormActionsProps) {
+}: FormBuilderActionsProps) {
   return (
     <div className={cn('flex items-center justify-end space-x-4', className)}>
       {customActions}

package/src/kit/builder/form/components/{FormField.tsx → FormBuilderField.tsx}

@@ -14,7 +14,7 @@ import { FormBuilderFieldConfig } from './FormBuilder';
 import { Autocomplete } from '../../../components/autocomplete/Autocomplete';
 import type { AutocompleteOption } from '../../../components/autocomplete/types';
 
-export interface FormFieldProps {
+export interface FormBuilderFieldProps {
   field: FormBuilderFieldConfig;
   control: Control<any>;
   onChange?: (value: any) => void;
@@ -22,7 +22,7 @@ export interface FormFieldProps {
   parentPath?: string;
 }
 
-export function FormField({ field, control, onChange, onFieldChange, parentPath }: FormFieldProps) {
+export function FormBuilderField({ field, control, onChange, onFieldChange, parentPath }: FormBuilderFieldProps) {
   const fieldPath = parentPath ? `${parentPath}.${field.name}` : field.name;
   const NULL_SENTINEL = '__NULL__';
 
@@ -130,7 +130,39 @@ export function FormField({ field, control, onChange, onFieldChange, parentPath
         );
       }
 
-      case 'checkbox':
+      case 'checkbox': {
+        const placement = field.labelPlacement ?? 'inline';
+        if (placement === 'stacked') {
+          const labelId = `${fieldPath}-label`;
+          return (
+            <div className="space-y-2">
+              <Label id={labelId} className="text-sm font-medium">
+                {field.label}
+                {field.required && <span className="text-destructive ml-1">*</span>}
+              </Label>
+              <Checkbox
+                aria-labelledby={labelId}
+                id={fieldPath}
+                checked={controllerField.value || false}
+                onCheckedChange={handleChange}
+                disabled={field.disabled}
+                className={cn(error && 'border-destructive', field.className)}
+              />
+            </div>
+          );
+        }
+        if (placement === 'hidden') {
+          return (
+            <Checkbox
+              id={fieldPath}
+              checked={controllerField.value || false}
+              onCheckedChange={handleChange}
+              disabled={field.disabled}
+              className={cn(error && 'border-destructive', field.className)}
+            />
+          );
+        }
+        // inline (default)
         return (
           <div className="flex items-center space-x-2">
             <Checkbox
@@ -142,9 +174,11 @@ export function FormField({ field, control, onChange, onFieldChange, parentPath
             />
             <Label htmlFor={fieldPath} className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70">
               {field.label}
+              {field.required && <span className="text-destructive ml-1">*</span>}
             </Label>
           </div>
         );
+      }
 
       case 'radio': {
         const toUiValue = (val: unknown) => (val === null || val === undefined ? NULL_SENTINEL : String(val));
@@ -213,7 +247,7 @@ export function FormField({ field, control, onChange, onFieldChange, parentPath
         <CardContent className="space-y-4">
           <div className="grid gap-4 md:grid-cols-2">
             {field.fields.map(subField => (
-              <FormField
+              <FormBuilderField
                 key={subField.name}
                 field={subField}
                 control={control}
@@ -306,7 +340,7 @@ export function FormField({ field, control, onChange, onFieldChange, parentPath
                 <CardContent>
                   {field.fields && field.fields.length === 1 ? (
                     // Single field array
-                    <FormField
+                    <FormBuilderField
                       field={{
                         ...field.fields[0],
                         name: field.fields[0].name,
@@ -320,7 +354,7 @@ export function FormField({ field, control, onChange, onFieldChange, parentPath
                     // Object array
                     <div className="grid gap-4 md:grid-cols-2">
                       {field.fields.map(subField => (
-                        <FormField
+                        <FormBuilderField
                           key={subField.name}
                           field={subField}
                           control={control}
@@ -360,7 +394,7 @@ export function FormField({ field, control, onChange, onFieldChange, parentPath
     return renderArrayField();
   }
 
-  // For checkbox, we don't need the label wrapper since it's handled internally
+  // For checkbox, label may be inline/stacked/hidden handled inside renderBasicField
   if (field.type === 'checkbox') {
     return (
       <div className={cn('space-y-2', field.gridCols && `md:col-span-${field.gridCols}`)}>
@@ -375,6 +409,43 @@ export function FormField({ field, control, onChange, onFieldChange, parentPath
     );
   }
 
+  // Non-checkbox fields: support labelPlacement
+  const placement = field.labelPlacement ?? 'stacked';
+  if (placement === 'hidden') {
+    return (
+      <div className={cn('space-y-2', field.gridCols && `md:col-span-${field.gridCols}`)}>
+        {renderBasicField()}
+        {field.description && (
+          <p className="text-sm text-muted-foreground">{field.description}</p>
+        )}
+        {error && (
+          <p className="text-sm text-destructive">{error.message}</p>
+        )}
+      </div>
+    );
+  }
+
+  if (placement === 'inline') {
+    return (
+      <div className={cn('space-y-1', field.gridCols && `md:col-span-${field.gridCols}`)}>
+        <div className="flex items-center gap-2">
+          <Label htmlFor={fieldPath} className="text-sm font-medium">
+            {field.label}
+            {field.required && <span className="text-destructive ml-1">*</span>}
+          </Label>
+          {renderBasicField()}
+        </div>
+        {field.description && (
+          <p className="text-sm text-muted-foreground">{field.description}</p>
+        )}
+        {error && (
+          <p className="text-sm text-destructive">{error.message}</p>
+        )}
+      </div>
+    );
+  }
+
+  // stacked (default)
   return (
     <div className={cn('space-y-2', field.gridCols && `md:col-span-${field.gridCols}`)}>
       <Label htmlFor={fieldPath} className="text-sm font-medium">
@@ -392,4 +463,4 @@ export function FormField({ field, control, onChange, onFieldChange, parentPath
   );
 }
 
-export default FormField;
+export default FormBuilderField;

package/src/kit/builder/form/components/index.ts

@@ -1,4 +1,3 @@
-export * from './FormActions';
+export * from './FormBuilderActions';
 export * from './FormBuilder';
-export * from './FormField';
-export * from './FormSection';
+export * from './FormBuilderField';

package/src/kit/builder/section/SectionBuilder.tsx

@@ -1,6 +1,7 @@
 import { memo } from 'react';
 import { cn } from '../../../shadcn/lib/utils';
-import { FormSection } from '../form/components/FormSection';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '../../../shadcn/ui/card';
+import { Separator } from '../../../shadcn/ui/separator';
 import type { SectionBuilderProps, SectionLeaf, SectionNode } from './types';
 
 // Tailwind-safe literal class maps (1-12)
@@ -176,15 +177,71 @@ function SectionNodeRenderer({ node, renderLeaf }: { node: SectionNode; renderLe
   const layout = node.layout ?? 'grid';
   const containerClass = layout === 'grid' ? gridClasses(node.grid) : flexClasses(node.flex);
 
+  // Local presentational container replacing FormBuilderSection
+  const SectionContainer = ({ children }: { children: React.ReactNode }) => {
+    const title = node.title;
+    const description = node.subtitle;
+    const variant = node.variant ?? 'card';
+    const className = node.className;
+    const headerClassName = node.headerClassName;
+    const contentClassName = node.contentClassName;
+
+    const renderHeader = () => {
+      if (!title && !description) return null;
+      return (
+        <div className={cn('space-y-1', headerClassName)}>
+          {title && <h3 className="text-lg font-medium leading-none">{title}</h3>}
+          {description && <p className="text-sm text-muted-foreground">{description}</p>}
+        </div>
+      );
+    };
+
+    const renderContent = () => (
+      <div className={cn('space-y-4', contentClassName)}>
+        {children}
+      </div>
+    );
+
+    switch (variant) {
+      case 'card':
+        return (
+          <Card className={className}>
+            {(title || description) && (
+              <CardHeader>
+                {title && <CardTitle>{title}</CardTitle>}
+                {description && <CardDescription>{description}</CardDescription>}
+              </CardHeader>
+            )}
+            <CardContent>
+              {renderContent()}
+            </CardContent>
+          </Card>
+        );
+      case 'separator':
+        return (
+          <div className={cn('space-y-6', className)}>
+            {(title || description) && (
+              <>
+                {renderHeader()}
+                <Separator />
+              </>
+            )}
+            {renderContent()}
+          </div>
+        );
+      case 'plain':
+      default:
+        return (
+          <div className={cn('space-y-6', className)}>
+            {renderHeader()}
+            {renderContent()}
+          </div>
+        );
+    }
+  };
+
   return (
-    <FormSection
-      title={node.title}
-      description={node.subtitle}
-      variant={node.variant ?? 'card'}
-      className={node.className}
-      headerClassName={node.headerClassName}
-      contentClassName={node.contentClassName}
-    >
+    <SectionContainer>
       <div className={containerClass}>
         {(node.children ?? []).map((child) => {
           if (isLeaf(child)) {
@@ -198,7 +255,7 @@ function SectionNodeRenderer({ node, renderLeaf }: { node: SectionNode; renderLe
           );
         })}
       </div>
-    </FormSection>
+    </SectionContainer>
   );
 }
 

package/src/kit/components/autocomplete/types.ts

@@ -6,7 +6,7 @@ export type AutocompleteOption = {
 export type AutocompleteFetchParams = {
   search: string
   cursor?: string | number | null
-  page?: number
+  page: number
   pageSize: number
 }
 

package/src/kit/layouts/admin/components/AdminLayout.tsx

@@ -22,7 +22,7 @@ import {
   Circle,
 } from 'lucide-react';
 
-import { Outlet, useLocation, Link } from '@tanstack/react-router';
+import { useLocation, Link } from '@tanstack/react-router';
 import { Fragment, useState, useCallback } from 'react';
 import ThemeToggle from './ThemeToggle';
 import { useAdminSidebarMenu } from '../hooks/menu';
@@ -214,7 +214,6 @@ function AdminLayoutContent({
         </header>
         <main className="flex flex-1 flex-col gap-4 p-4">
           {children}
-          <Outlet />
         </main>
       </SidebarInset>
       </div>

package/src/kit/layouts/admin/hooks/menu.ts

@@ -21,6 +21,6 @@ export function useAdminSidebarMenu() {
 }
 
 export function useAdminSidebarMenuRegistration() {
-  const { registerGroup, registerItem, clear } = useAdminSidebarMenu();
-  return { registerGroup, registerItem, clear };
+  const { setGroups, registerGroup, registerItem, clear } = useAdminSidebarMenu();
+  return { setGroups, registerGroup, registerItem, clear };
 }

package/src/kit/providers/ThemeProvider.tsx

@@ -1,11 +1,15 @@
-import { createContext, use, useEffect, useState } from 'react';
+import { createContext, use, useEffect } from 'react';
+import {
+  ThemeProvider as NextThemesProvider,
+  useTheme as useNextThemes,
+} from 'next-themes';
 
 type Theme = 'dark' | 'light' | 'system';
 
 type ThemeProviderProps = {
   children: React.ReactNode;
-  defaultTheme?: Theme;
-  storageKey?: string;
+  defaultTheme?: Theme; // maps to next-themes defaultTheme
+  storageKey?: string; // maps to next-themes storageKey
 };
 
 type ThemeProviderState = {
@@ -26,51 +30,47 @@ export function ThemeProvider({
   storageKey = 'vite-ui-theme',
   ...props
 }: ThemeProviderProps) {
-  const [theme, setTheme] = useState<Theme>(
-    () => (localStorage.getItem(storageKey) as Theme) || defaultTheme,
+  return (
+    <NextThemesProvider
+      attribute="class"
+      defaultTheme={defaultTheme}
+      storageKey={storageKey}
+      enableSystem
+      disableTransitionOnChange
+    >
+      <ThemeBridge {...props}>{children}</ThemeBridge>
+    </NextThemesProvider>
   );
+}
 
-  // On first mount, if there is no saved preference or it's 'system' and
-  // the app provides a concrete default (e.g., 'light'), apply it.
-  useEffect(() => {
-    const stored = localStorage.getItem(storageKey) as Theme | null;
-    if ((!stored || stored === 'system') && defaultTheme !== 'system') {
-      localStorage.setItem(storageKey, defaultTheme);
-      setTheme(defaultTheme);
-    }
-  }, []);
+function ThemeBridge({ children, ...props }: { children: React.ReactNode }) {
+  const { theme, resolvedTheme, setTheme } = useNextThemes();
 
+  // Mirror resolved theme to data-theme and color-scheme for CSS/Tailwind consumers
   useEffect(() => {
-    const root = window.document.documentElement;
-    const body = window.document.body;
-    const app = window.document.getElementById('app');
-    root.classList.remove('light', 'dark');
-    body.classList.remove('light', 'dark');
-    app?.classList.remove('light', 'dark');
+    if (typeof document === 'undefined') return;
+    const root = document.documentElement;
+    const body = document.body;
+    const app = document.getElementById('app');
+    const resolved = (resolvedTheme as 'light' | 'dark') ?? 'light';
 
-    const resolved = (() => {
-      if (theme === 'system') {
-        return window.matchMedia('(prefers-color-scheme: dark)').matches
-          ? 'dark'
-          : 'light';
-      }
-      return theme;
-    })();
+    // data-theme + color-scheme for CSS variables and form controls
+    root.setAttribute('data-theme', resolved);
+    root.style.colorScheme = resolved;
 
+    // Ensure class-based dark mode works across html, body, and #app
+    const opposite = resolved === 'dark' ? 'light' : 'dark';
+    root.classList.remove(opposite);
+    body.classList.remove(opposite);
+    app?.classList.remove(opposite);
     root.classList.add(resolved);
     body.classList.add(resolved);
     app?.classList.add(resolved);
-    root.style.colorScheme = resolved;
-    // Important for Tailwind v4 @theme dark support
-    root.setAttribute('data-theme', resolved);
-  }, [theme]);
+  }, [resolvedTheme]);
 
-  const value = {
-    theme,
-    setTheme: (theme: Theme) => {
-      localStorage.setItem(storageKey, theme);
-      setTheme(theme);
-    },
+  const value: ThemeProviderState = {
+    theme: (theme as Theme) ?? 'system',
+    setTheme: (t: Theme) => setTheme(t),
   };
 
   return (

package/src/stories/kit/layouts/admin/AdminLayout.Basic.stories.tsx

@@ -4,6 +4,7 @@ import AdminLayout from '../../../../kit/layouts/admin/components/AdminLayout';
 import { ThemeProvider } from '../../../../kit/providers/ThemeProvider';
 import { useAdminSidebarMenuRegistration } from '../../../../kit/layouts/admin/hooks/menu';
 import {
+  Outlet,
   RouterProvider,
   createRootRoute,
   createRoute,
@@ -43,6 +44,7 @@ function App(props: AdminLayoutStoryProps) {
       <ThemeProvider>
         <AdminLayout {...props}>
           <RegisterMenus />
+          <Outlet />
         </AdminLayout>
       </ThemeProvider>
     ),

package/src/stories/kit/layouts/admin/AdminLayout.Collapsible.stories.tsx

@@ -4,6 +4,7 @@ import AdminLayout from '../../../../kit/layouts/admin/components/AdminLayout';
 import { ThemeProvider } from '../../../../kit/providers/ThemeProvider';
 import { useAdminSidebarMenuRegistration } from '../../../../kit/layouts/admin/hooks/menu';
 import {
+  Outlet,
   RouterProvider,
   createRootRoute,
   createRoute,
@@ -41,6 +42,7 @@ function App(props: AdminLayoutStoryProps) {
       <ThemeProvider>
         <AdminLayout {...props}>
           <RegisterMenus />
+          <Outlet />
         </AdminLayout>
       </ThemeProvider>
     ),

package/src/stories/kit/layouts/admin/AdminLayout.Complex.stories.tsx

@@ -4,6 +4,7 @@ import AdminLayout from '../../../../kit/layouts/admin/components/AdminLayout';
 import { ThemeProvider } from '../../../../kit/providers/ThemeProvider';
 import { useAdminSidebarMenuRegistration } from '../../../../kit/layouts/admin/hooks/menu';
 import {
+  Outlet,
   RouterProvider,
   createRootRoute,
   createRoute,
@@ -102,6 +103,7 @@ function App(props: AdminLayoutStoryProps) {
       <ThemeProvider>
         <AdminLayout {...props}>
           <RegisterComplexMenus />
+          <Outlet />
         </AdminLayout>
       </ThemeProvider>
     ),

package/src/stories/kit/layouts/admin/AdminLayout.CustomSidebarHeaderComponent.stories.tsx

@@ -4,6 +4,7 @@ import AdminLayout from '../../../../kit/layouts/admin/components/AdminLayout';
 import { ThemeProvider } from '../../../../kit/providers/ThemeProvider';
 import { useAdminSidebarMenuRegistration } from '../../../../kit/layouts/admin/hooks/menu';
 import {
+  Outlet,
   RouterProvider,
   createRootRoute,
   createRoute,
@@ -37,6 +38,7 @@ function App(props: AdminLayoutStoryProps) {
       <ThemeProvider>
         <AdminLayout {...props}>
           <RegisterMenus />
+          <Outlet />
         </AdminLayout>
       </ThemeProvider>
     ),

package/src/stories/kit/layouts/admin/AdminLayout.CustomSidebarTitleAndIcon.stories.tsx

@@ -4,6 +4,7 @@ import AdminLayout from '../../../../kit/layouts/admin/components/AdminLayout';
 import { ThemeProvider } from '../../../../kit/providers/ThemeProvider';
 import { useAdminSidebarMenuRegistration } from '../../../../kit/layouts/admin/hooks/menu';
 import {
+  Outlet,
   RouterProvider,
   createRootRoute,
   createRoute,
@@ -37,6 +38,7 @@ function App(props: AdminLayoutStoryProps) {
       <ThemeProvider>
         <AdminLayout {...props}>
           <RegisterMenus />
+          <Outlet />
         </AdminLayout>
       </ThemeProvider>
     ),

package/src/stories/kit/layouts/admin/AdminLayout.HeaderSlots.stories.tsx

@@ -4,6 +4,7 @@ import AdminLayout from '../../../../kit/layouts/admin/components/AdminLayout';
 import { ThemeProvider } from '../../../../kit/providers/ThemeProvider';
 import { useAdminSidebarMenuRegistration } from '../../../../kit/layouts/admin/hooks/menu';
 import {
+  Outlet,
   RouterProvider,
   createRootRoute,
   createRoute,
@@ -37,6 +38,7 @@ function App(props: AdminLayoutStoryProps) {
       <ThemeProvider>
         <AdminLayout {...props}>
           <RegisterMenus />
+          <Outlet />
         </AdminLayout>
       </ThemeProvider>
     ),