@spaceinvoices/react-ui 0.4.8 → 0.4.11

package/README.md

@@ -1,19 +1,25 @@
-# @spaceinvoices/react-ui - Space Invoices Component Library
+# @spaceinvoices/react-ui - Space Invoices React UI Kit
 
-> **Pre-built React components for the Space Invoices API**
+> **Copy-paste React UI for the Space Invoices API**
 
-70+ components for building invoicing applications with the Space Invoices API. Includes forms, tables, dashboard charts, and more - all designed to be copied into your project for full customization.
+50+ installable components for building invoicing applications with the Space Invoices API. Includes forms, tables, dashboard charts, and more - all designed to be copied into your project for full customization.
 
 ## Philosophy
 
-These components are **designed to be copied**, not installed as a package:
+This package is a **CLI installer and source registry**, not a conventional runtime component library. The intended flow is:
+
+1. initialize your app with the CLI
+2. add only the components you need
+3. own the copied source inside your app
+
+These components are **designed to be copied**, not imported from `node_modules` at runtime:
 
 - **Full ownership** - Modify freely without breaking changes
 - **Complete customization** - Change behavior and structure
 - **No version conflicts** - You control when to update
 - **Zero lock-in** - Components work standalone in your codebase
 
-**Note**: Components are built on **shadcn/ui primitives**. Bring your own shadcn/ui components or use any alternative. The `components/ui/` folder is included as reference only.
+**Note**: Components are built on **shadcn/ui primitives**. Bring your own shadcn/ui components or use any alternative. The CLI can copy compatible `components/ui/` primitives when needed, but teams using their own design system can swap those imports after install.
 
 ## Quick Start (CLI - Recommended)
 
@@ -36,6 +42,7 @@ The CLI will:
 - Create `spaceinvoices.json` config with your preferred paths
 - Install required dependencies (`@spaceinvoices/js-sdk`, `@tanstack/react-query`)
 - Copy essential files (SDK provider, utilities)
+ - Copy generated Zod schemas when installed components depend on them
 - Transform import paths to match your project structure
 - Install npm dependencies for each component
 
@@ -101,7 +108,10 @@ cp -r react-ui/src/components/customers/ your-project/src/components/space-invoi
 cp -r react-ui/src/components/table/ your-project/src/components/space-invoices/
 # ... add more as needed
 
-# DON'T copy components/ui/ - use shadcn/ui instead
+# Include generated schemas if you use form components
+cp -r react-ui/src/generated/ your-project/src/generated/
+
+# Optional: skip components/ui/ if you already use shadcn/ui or your own primitives
 ```
 
 ### 4. Update Import Paths
@@ -158,9 +168,13 @@ src/components/
 └── table/              # Generic data table infrastructure
 ```
 
-### UI Primitives (Reference Only)
+### UI Primitives (Optional)
+
+The `components/ui/` folder contains shadcn/ui-style components. You can:
 
-The `components/ui/` folder contains shadcn/ui-style components. **Don't copy these** - use shadcn/ui directly:
+- let the CLI install compatible primitives for you
+- use shadcn/ui directly
+- swap to your own component library after copying the feature components
 
 ```bash
 npx shadcn@latest add button input form table dialog select
@@ -175,6 +189,8 @@ src/
 ├── providers/
 │   ├── sdk-provider.tsx       # SDK context (required)
 │   └── entities-provider.tsx  # Active entity context (required)
+├── generated/
+│   └── schemas/               # Generated Zod schemas used by form components
 ├── hooks/
 │   └── *.ts                   # Shared hooks
 └── lib/

package/cli/dist/index.js

@@ -5,7 +5,7 @@ import { Command } from "commander";
 
 // cli/src/commands/init.ts
 import fs4 from "fs";
-import path4 from "path";
+import path5 from "path";
 import prompts from "prompts";
 
 // cli/src/utils/config.ts
@@ -19,7 +19,8 @@ var DEFAULT_CONFIG = {
     ui: "@/components/ui",
     lib: "@/lib",
     hooks: "@/hooks",
-    providers: "@/providers"
+    providers: "@/providers",
+    generated: "@/generated"
   }
 };
 function getConfigPath(cwd = process.cwd()) {
@@ -44,6 +45,20 @@ function writeConfig(config, cwd = process.cwd()) {
   const configPath = getConfigPath(cwd);
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
 }
+function resolveAliasPath(alias, cwd = process.cwd()) {
+  if (path.isAbsolute(alias)) {
+    return alias;
+  }
+  if (alias.startsWith("@/")) {
+    const srcPath = path.join(cwd, "src", alias.slice(2));
+    const rootPath = path.join(cwd, alias.slice(2));
+    if (fs.existsSync(path.join(cwd, "src"))) {
+      return srcPath;
+    }
+    return rootPath;
+  }
+  return path.join(cwd, alias);
+}
 
 // cli/src/utils/installer.ts
 import { spawn } from "child_process";
@@ -268,6 +283,7 @@ function getComponentsByCategory(registry) {
 }
 
 // cli/src/utils/transformer.ts
+import path4 from "path";
 function transformImports(source, config) {
   let result = source;
   const replacements = [
@@ -280,7 +296,9 @@ function transformImports(source, config) {
     // Lib utilities: @/ui/lib/ -> config.aliases.lib/
     [/@\/ui\/lib\//g, `${config.aliases.lib}/`],
     // Hooks: @/ui/hooks/ -> config.aliases.hooks/
-    [/@\/ui\/hooks\//g, `${config.aliases.hooks}/`]
+    [/@\/ui\/hooks\//g, `${config.aliases.hooks}/`],
+    // Generated helpers: @/ui/generated/ -> config.aliases.generated/
+    [/@\/ui\/generated\//g, `${config.aliases.generated}/`]
   ];
   for (const [pattern, replacement] of replacements) {
     result = result.replace(pattern, replacement);
@@ -318,6 +336,12 @@ function getDestinationPath(sourcePath, config) {
       category: "hooks"
     };
   }
+  if (sourcePath.startsWith("generated/")) {
+    return {
+      destPath: sourcePath.replace("generated/", ""),
+      category: "generated"
+    };
+  }
   return {
     destPath: sourcePath,
     category: "components"
@@ -326,13 +350,7 @@ function getDestinationPath(sourcePath, config) {
 function getFullDestinationPath(sourcePath, config, basePath) {
   const { destPath, category } = getDestinationPath(sourcePath, config);
   const alias = config.aliases[category];
-  let relativePath;
-  if (alias.startsWith("@/")) {
-    relativePath = alias.slice(2);
-  } else {
-    relativePath = alias;
-  }
-  return `${basePath}/src/${relativePath}/${destPath}`;
+  return path4.join(resolveAliasPath(alias, basePath), destPath);
 }
 
 // cli/src/commands/init.ts
@@ -397,6 +415,12 @@ async function init(options = {}) {
         name: "providers",
         message: "Where should providers be installed?",
         initial: DEFAULT_CONFIG.aliases.providers
+      },
+      {
+        type: "text",
+        name: "generated",
+        message: "Where should generated helpers (schemas) be installed?",
+        initial: DEFAULT_CONFIG.aliases.generated
       }
     ]);
     if (!answers.components) {
@@ -410,7 +434,8 @@ async function init(options = {}) {
         ui: answers.ui,
         lib: answers.lib,
         hooks: answers.hooks,
-        providers: answers.providers
+        providers: answers.providers,
+        generated: answers.generated
       }
     };
   }
@@ -431,16 +456,11 @@ async function init(options = {}) {
       config.aliases.ui,
       config.aliases.lib,
       config.aliases.hooks,
-      config.aliases.providers
+      config.aliases.providers,
+      config.aliases.generated
     ];
     for (const alias of directories) {
-      let dirPath;
-      if (alias.startsWith("@/")) {
-        dirPath = path4.join(cwd, "src", alias.slice(2));
-      } else {
-        dirPath = path4.join(cwd, alias);
-      }
-      fs4.mkdirSync(dirPath, { recursive: true });
+      fs4.mkdirSync(resolveAliasPath(alias, cwd), { recursive: true });
     }
     dirSpinner.succeed("Created directories");
   } catch (error) {
@@ -454,7 +474,7 @@ async function init(options = {}) {
       const content = await fetchFile(filePath);
       const transformed = transformImports(content, config);
       const destPath = getFullDestinationPath(filePath, config, cwd);
-      fs4.mkdirSync(path4.dirname(destPath), { recursive: true });
+      fs4.mkdirSync(path5.dirname(destPath), { recursive: true });
       fs4.writeFileSync(destPath, transformed);
     }
     filesSpinner.succeed(`Copied ${ESSENTIAL_FILES.length} essential files`);
@@ -488,7 +508,7 @@ async function init(options = {}) {
 
 // cli/src/commands/add.ts
 import fs5 from "fs";
-import path5 from "path";
+import path6 from "path";
 import prompts2 from "prompts";
 
 // cli/src/utils/resolver.ts
@@ -614,6 +634,31 @@ function getInstallSummary(resolved) {
   };
 }
 
+// cli/src/utils/file-dependencies.ts
+var GENERATED_IMPORT_PATTERN = /from\s+["']@\/ui\/generated\/schemas(?:\/([^"']+))?["']/g;
+var GENERATED_EXPORT_PATTERN = /from\s+['"]\.\/([^'"]+)['"]/g;
+function normalizeGeneratedPath(subpath) {
+  return `generated/schemas/${subpath.replace(/\.ts$/, "")}.ts`;
+}
+function getRegistryManagedDependencies(filePath, source) {
+  const dependencies = /* @__PURE__ */ new Set();
+  if (filePath === "generated/schemas/index.ts") {
+    for (const match of source.matchAll(GENERATED_EXPORT_PATTERN)) {
+      dependencies.add(normalizeGeneratedPath(match[1]));
+    }
+    return [...dependencies];
+  }
+  for (const match of source.matchAll(GENERATED_IMPORT_PATTERN)) {
+    const subpath = match[1];
+    if (subpath) {
+      dependencies.add(normalizeGeneratedPath(subpath));
+      continue;
+    }
+    dependencies.add("generated/schemas/index.ts");
+  }
+  return [...dependencies];
+}
+
 // cli/src/commands/add.ts
 async function add(componentNames, options = {}) {
   const cwd = options.cwd ?? process.cwd();
@@ -674,6 +719,7 @@ async function add(componentNames, options = {}) {
     resolveSpinner.fail("Failed to resolve dependencies");
     throw error;
   }
+  const fileContents = await collectRegistryFiles(resolved.allFiles);
   const summary = getInstallSummary(resolved);
   logger.break();
   logger.info("The following will be installed:");
@@ -692,7 +738,7 @@ async function add(componentNames, options = {}) {
       `  ${highlight("npm packages:")} ${summary.npmPackages.join(", ")}`
     );
   }
-  logger.log(`  ${highlight("Files:")} ${summary.fileCount} files`);
+  logger.log(`  ${highlight("Files:")} ${fileContents.size} files`);
   if (!options.yes) {
     logger.break();
     const { proceed } = await prompts2({
@@ -712,12 +758,11 @@ async function add(componentNames, options = {}) {
   const existingFiles = [];
   const filesToWrite = [];
   try {
-    for (const filePath of resolved.allFiles) {
+    for (const [filePath, content] of fileContents) {
       const destPath = getFullDestinationPath(filePath, config, cwd);
       if (fs5.existsSync(destPath)) {
         existingFiles.push(destPath);
       }
-      const content = await fetchFile(filePath);
       const transformed = transformImports(content, config);
       filesToWrite.push({ path: destPath, content: transformed });
     }
@@ -753,7 +798,7 @@ async function add(componentNames, options = {}) {
   }
   try {
     for (const { path: filePath, content } of filesToWrite) {
-      fs5.mkdirSync(path5.dirname(filePath), { recursive: true });
+      fs5.mkdirSync(path6.dirname(filePath), { recursive: true });
       fs5.writeFileSync(filePath, content);
     }
     filesSpinner.succeed(`Installed ${filesToWrite.length} files`);
@@ -780,6 +825,24 @@ async function add(componentNames, options = {}) {
   logger.success("Components installed successfully!");
   logger.break();
 }
+async function collectRegistryFiles(initialFiles) {
+  const pending = [...initialFiles];
+  const contents = /* @__PURE__ */ new Map();
+  while (pending.length > 0) {
+    const filePath = pending.shift();
+    if (!filePath || contents.has(filePath)) {
+      continue;
+    }
+    const content = await fetchFile(filePath);
+    contents.set(filePath, content);
+    for (const dependency of getRegistryManagedDependencies(filePath, content)) {
+      if (!contents.has(dependency)) {
+        pending.push(dependency);
+      }
+    }
+  }
+  return contents;
+}
 async function selectComponents(registry) {
   const byCategory = getComponentsByCategory(registry);
   const choices = [];
@@ -870,7 +933,7 @@ async function list(options = {}) {
 
 // cli/src/index.ts
 var program = new Command();
-program.name("spaceinvoices-ui").description("CLI for adding Space Invoices React UI components to your project").version("0.4.8");
+program.name("spaceinvoices-ui").description("CLI for adding Space Invoices React UI components to your project").version("0.4.11");
 program.option("--local <path>", "Use local registry from specified path (for development)");
 program.command("init").description("Initialize Space Invoices UI in your project").option("-y, --yes", "Skip prompts and use defaults").option("-f, --force", "Overwrite existing configuration").option("--cwd <path>", "Working directory (defaults to current directory)").action(async (options) => {
   const globalOpts = program.opts();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spaceinvoices/react-ui",
   "type": "module",
-  "version": "0.4.8",
+  "version": "0.4.11",
   "private": false,
   "license": "MIT",
   "description": "Space Invoices UI components - copy-paste distribution with CLI support",
@@ -78,6 +78,9 @@
     "zod": "^4.1.12"
   },
   "devDependencies": {
+    "@happy-dom/global-registrator": "^20.8.3",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@types/bun": "latest",
     "@types/prompts": "^2.4.9",
     "@types/react": "^19.1.0",

package/spaceinvoices.schema.json

@@ -12,7 +12,7 @@
     "aliases": {
       "type": "object",
       "description": "Path aliases for component installation",
-      "required": ["components", "ui", "lib", "hooks", "providers"],
+      "required": ["components", "ui", "lib", "hooks", "providers", "generated"],
       "properties": {
         "components": {
           "type": "string",
@@ -38,6 +38,11 @@
           "type": "string",
           "description": "Path alias for React providers (e.g., @/providers)",
           "default": "@/providers"
+        },
+        "generated": {
+          "type": "string",
+          "description": "Path alias for generated helpers such as Zod schemas (e.g., @/generated)",
+          "default": "@/generated"
         }
       },
       "additionalProperties": false

package/src/common/autocomplete.tsx

@@ -14,6 +14,9 @@ type AutocompleteProps = {
   value?: string;
   onValueChange?: (value: string) => void;
   onBlur?: (event: React.FocusEvent<HTMLInputElement>) => void; // Added onBlur prop
+  onCommitUnselectedInput?: (value: string) => void;
+  commitUnselectedOnBlur?: boolean;
+  committedDisplayValue?: string;
   placeholder?: string;
   emptyText?: string;
   className?: string;
@@ -22,6 +25,8 @@ type AutocompleteProps = {
   onSearch?: (value: string) => void;
   searchValue?: string;
   displayValue?: string;
+  inputTestId?: string;
+  inputRef?: React.Ref<HTMLInputElement>;
 };
 
 export function Autocomplete({
@@ -29,6 +34,9 @@ export function Autocomplete({
   value,
   onValueChange,
   onBlur: onBlurProp, // Destructure the new onBlur prop
+  onCommitUnselectedInput,
+  commitUnselectedOnBlur = false,
+  committedDisplayValue,
   placeholder = "Type to search...",
   emptyText = "No results found.",
   className,
@@ -37,10 +45,16 @@ export function Autocomplete({
   onSearch,
   searchValue: externalSearchValue,
   displayValue,
+  inputTestId,
+  inputRef: externalInputRef,
 }: AutocompleteProps) {
   const [open, setOpen] = React.useState(false);
   const [internalSearchValue, setInternalSearchValue] = React.useState("");
   const inputRef = React.useRef<HTMLInputElement>(null);
+  const suppressAutoOpenRef = React.useRef(false);
+  const blurCloseRef = React.useRef(false);
+  const focusOpenRef = React.useRef(false);
+  const selectedValueRef = React.useRef<string | null>(null);
 
   const searchValue = externalSearchValue ?? internalSearchValue;
   // Show displayValue when not typing, otherwise show what user is typing
@@ -48,6 +62,7 @@ export function Autocomplete({
 
   const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
     const value = e.target.value;
+    suppressAutoOpenRef.current = false;
     setInternalSearchValue(value);
     onSearch?.(value);
 
@@ -59,22 +74,38 @@ export function Autocomplete({
 
   // Close popover when options become empty, open when they appear
   React.useEffect(() => {
+    if (!displayValue && !value) {
+      suppressAutoOpenRef.current = false;
+    }
+
     if (options.length === 0) {
       setOpen(false);
+    } else if (suppressAutoOpenRef.current) {
+      return;
     } else if (document.activeElement === inputRef.current && searchValue) {
       setOpen(true);
     }
-  }, [options.length, searchValue]);
+  }, [displayValue, options.length, searchValue, value]);
 
   const handleSelect = (selectedValue: string) => {
+    selectedValueRef.current = selectedValue;
+    suppressAutoOpenRef.current = true;
     onValueChange?.(selectedValue);
     setOpen(false);
   };
 
   const handleInputFocus = () => {
+    if (!displayValue) {
+      suppressAutoOpenRef.current = false;
+    }
+    if (suppressAutoOpenRef.current) return;
     // Only open popover on focus if there's no displayValue (no customer selected)
     if (!displayValue && options.length > 0) {
+      focusOpenRef.current = true;
       setOpen(true);
+      requestAnimationFrame(() => {
+        focusOpenRef.current = false;
+      });
     }
   };
 
@@ -84,8 +115,30 @@ export function Autocomplete({
     if (relatedTarget?.closest('[role="dialog"]')) {
       return;
     }
-    // Close after a short delay to allow click events to fire
-    setTimeout(() => setOpen(false), 200);
+
+    const typedValue = searchValue?.trim();
+    const shouldCommitTypedValue =
+      !!typedValue &&
+      typedValue !== displayValue &&
+      selectedValueRef.current == null &&
+      commitUnselectedOnBlur &&
+      !!onCommitUnselectedInput;
+
+    if (shouldCommitTypedValue) {
+      onCommitUnselectedInput(typedValue);
+    } else if (selectedValueRef.current == null) {
+      const restoredValue = committedDisplayValue ?? displayValue ?? "";
+      setInternalSearchValue("");
+      onSearch?.(restoredValue);
+    }
+
+    blurCloseRef.current = true;
+    suppressAutoOpenRef.current = false;
+    setOpen(false);
+    requestAnimationFrame(() => {
+      blurCloseRef.current = false;
+      selectedValueRef.current = null;
+    });
 
     onBlurProp?.(e); // Call the passed onBlur prop after internal logic
   };
@@ -98,8 +151,10 @@ export function Autocomplete({
 
   // Handle popover open/close - prevent closing when input is focused
   const handleOpenChange = (newOpen: boolean) => {
-    if (!newOpen && document.activeElement === inputRef.current) {
-      // Don't close if the input still has focus (user clicked on input)
+    if (!newOpen && focusOpenRef.current) {
+      return;
+    }
+    if (!newOpen && document.activeElement === inputRef.current && !blurCloseRef.current) {
       return;
     }
     setOpen(newOpen);
@@ -108,7 +163,14 @@ export function Autocomplete({
   return (
     <Popover.Root open={open} onOpenChange={handleOpenChange}>
       <Input
-        ref={inputRef}
+        ref={(node) => {
+          inputRef.current = node;
+          if (typeof externalInputRef === "function") {
+            externalInputRef(node);
+          } else if (externalInputRef) {
+            (externalInputRef as React.MutableRefObject<HTMLInputElement | null>).current = node;
+          }
+        }}
         value={inputValue}
         onChange={handleInputChange}
         onFocus={handleInputFocus}
@@ -118,6 +180,7 @@ export function Autocomplete({
         className={className}
         disabled={disabled}
         autoComplete="off"
+        data-testid={inputTestId}
       />
       <Popover.Portal>
         <Popover.Positioner anchor={inputRef} align="start" sideOffset={4} className="isolate z-50">