kumo-svelte 0.1.0-beta.0

package/src/command-line/commands/add.ts

@@ -0,0 +1,112 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { readConfig } from '../utils/config.js';
+import { findPackageFile, packageRootFrom } from '../utils/paths.js';
+import { loadRegistry } from '../utils/registry.js';
+import { transformImports } from '../utils/transformer.js';
+
+function getBlocksSourcePath() {
+  const root = packageRootFrom(import.meta.url);
+  const candidates = [
+    join(root, 'src', 'blocks'),
+    join(root, 'dist', 'blocks-source'),
+    join(root, 'blocks-source')
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  const registryPath = findPackageFile(import.meta.url, 'ai/component-registry.json');
+  if (registryPath) {
+    const fromRegistry = resolve(dirname(registryPath), '..', 'src', 'blocks');
+    if (existsSync(fromRegistry)) return fromRegistry;
+  }
+
+  throw new Error('Blocks source directory not found. The package may be corrupted.');
+}
+
+async function confirm(message: string): Promise<boolean> {
+  if (!process.stdin.isTTY) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await rl.question(`${message} (y/n): `);
+  rl.close();
+  return answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes';
+}
+
+export async function add(blockName?: string): Promise<void> {
+  if (!blockName) {
+    console.error('Error: Block name is required.');
+    console.log('');
+    console.log('Usage: kumo-svelte add <block-name>');
+    console.log('Run "kumo-svelte blocks" to see available blocks.');
+    process.exit(1);
+  }
+
+  const config = readConfig();
+  if (!config) {
+    console.error('Error: kumo.json not found. Run "kumo-svelte init" first.');
+    process.exit(1);
+  }
+
+  const registry = loadRegistry(import.meta.url);
+  const block =
+    registry.blocks?.[blockName] ??
+    Object.values(registry.blocks ?? {}).find((item) => item.name.toLowerCase() === blockName.toLowerCase());
+
+  if (!block) {
+    console.error(`Error: Block '${blockName}' not found.`);
+    console.log('Run "kumo-svelte blocks" to see available blocks.');
+    process.exit(1);
+  }
+
+  const blocksSourcePath = getBlocksSourcePath();
+  const projectRoot = process.cwd();
+  const targetDir = join(projectRoot, config.blocksDir);
+
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+    console.log(`Created directory: ${config.blocksDir}`);
+  }
+
+  const blockExists = block.files.some((file) => existsSync(join(targetDir, file)));
+  if (blockExists) {
+    console.log(`Block '${block.name}' already exists in ${config.blocksDir}`);
+    const shouldOverwrite = await confirm('Do you want to overwrite it?');
+    if (!shouldOverwrite) {
+      console.log('Installation cancelled.');
+      return;
+    }
+  }
+
+  console.log(`Installing block: ${block.name}`);
+
+  for (const file of block.files) {
+    const sourcePath = resolve(blocksSourcePath, file);
+    const targetPath = resolve(targetDir, file);
+    const relativeSource = relative(blocksSourcePath, sourcePath);
+    const relativeTarget = relative(targetDir, targetPath);
+
+    if (relativeSource.startsWith('..') || relativeSource.startsWith('/') || isAbsolute(relativeSource)) {
+      console.error(`Error: Invalid source path for file: ${file}`);
+      process.exit(1);
+    }
+
+    if (relativeTarget.startsWith('..') || relativeTarget.startsWith('/') || isAbsolute(relativeTarget)) {
+      console.error(`Error: Invalid target path for file: ${file}`);
+      process.exit(1);
+    }
+
+    mkdirSync(dirname(targetPath), { recursive: true });
+    const content = transformImports(readFileSync(sourcePath, 'utf-8'));
+    writeFileSync(targetPath, content, 'utf-8');
+    console.log(`  ${join(config.blocksDir, file)}`);
+  }
+
+  console.log('');
+  console.log(`Installed ${block.name}.`);
+  if (block.dependencies?.length) {
+    console.log(`Uses: ${block.dependencies.join(', ')}`);
+  }
+}

package/src/command-line/commands/ai.ts

@@ -0,0 +1,12 @@
+import { readFileSync } from 'node:fs';
+import { findPackageFile } from '../utils/paths.js';
+
+export function ai(): void {
+  const usagePath = findPackageFile(import.meta.url, 'ai/USAGE.md');
+  if (!usagePath) {
+    console.error('Could not read ai/USAGE.md from the installed kumo-svelte package.');
+    process.exit(1);
+  }
+
+  console.log(readFileSync(usagePath, 'utf-8'));
+}

package/src/command-line/commands/blocks.ts

@@ -0,0 +1,34 @@
+import { loadRegistry } from '../utils/registry.js';
+
+export function blocks(): void {
+  const registry = loadRegistry(import.meta.url);
+  const entries = Object.values(registry.blocks ?? {});
+
+  if (entries.length === 0) {
+    console.log('No blocks available in this version.');
+    return;
+  }
+
+  console.log(`Kumo Svelte Blocks (${entries.length} total)`);
+  console.log('');
+
+  const categories = new Map();
+  for (const block of entries) {
+    const list = categories.get(block.category) ?? [];
+    list.push(block);
+    categories.set(block.category, list);
+  }
+
+  for (const [category, categoryBlocks] of categories) {
+    console.log(category);
+    for (const block of categoryBlocks) {
+      console.log(`  ${block.name.padEnd(18)} ${block.description}`);
+      if (block.dependencies?.length) {
+        console.log(`  ${''.padEnd(18)} depends on: ${block.dependencies.join(', ')}`);
+      }
+    }
+    console.log('');
+  }
+
+  console.log('Install with: kumo-svelte add <BlockName>');
+}

package/src/command-line/commands/doc.ts

@@ -0,0 +1,60 @@
+import { formatComponentName, loadRegistry, type RegistryComponent } from '../utils/registry.js';
+
+function printComponent(component: RegistryComponent): void {
+  console.log(`# ${component.name}`);
+  console.log('');
+  console.log(component.description);
+  console.log('');
+  console.log(`Category: ${component.category}`);
+  console.log(`Import: import { ${component.name} } from 'kumo-svelte';`);
+
+  if (component.sourceFile) {
+    console.log(`Source: ${component.sourceFile}`);
+  }
+
+  if (component.props?.length) {
+    console.log('');
+    console.log('Props:');
+    for (const prop of component.props) {
+      const required = prop.required ? ' required' : '';
+      const description = prop.description ? ` - ${prop.description}` : '';
+      console.log(`  ${prop.name}: ${prop.type}${required}${description}`);
+    }
+  }
+
+  if (component.examples?.length) {
+    console.log('');
+    console.log('Examples:');
+    for (const example of component.examples) {
+      console.log(`  ${example.title}`);
+    }
+  }
+}
+
+export function doc(componentName?: string): void {
+  const registry = loadRegistry(import.meta.url);
+
+  if (!componentName) {
+    for (const component of Object.values(registry.components ?? {})) {
+      printComponent(component);
+      console.log('\n---\n');
+    }
+    console.log('Use "kumo-svelte doc <ComponentName>" for detailed docs');
+    return;
+  }
+
+  const normalized = formatComponentName(componentName);
+  const component =
+    registry.components?.[normalized] ??
+    Object.values(registry.components ?? {}).find(
+      (item) => item.name.toLowerCase() === componentName.toLowerCase()
+    );
+
+  if (!component) {
+    console.error(`Component '${componentName}' not found.`);
+    console.log('Run "kumo-svelte ls" to see available components.');
+    process.exit(1);
+  }
+
+  printComponent(component);
+}

package/src/command-line/commands/init.ts

@@ -0,0 +1,26 @@
+import { createInterface } from 'node:readline/promises';
+import { configExists, DEFAULT_CONFIG, writeConfig } from '../utils/config.js';
+
+async function ask(question: string, defaultValue: string): Promise<string> {
+  if (!process.stdin.isTTY) return defaultValue;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await rl.question(`${question} (${defaultValue}): `);
+  rl.close();
+  return answer.trim() || defaultValue;
+}
+
+export async function init(): Promise<void> {
+  if (configExists()) {
+    console.log('kumo.json already exists.');
+    return;
+  }
+
+  const blocksDir = await ask('Where should blocks be installed?', DEFAULT_CONFIG.blocksDir);
+  writeConfig({ blocksDir });
+
+  console.log('Created kumo.json');
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Run "kumo-svelte blocks" to see available blocks');
+  console.log('  2. Run "kumo-svelte add <BlockName>" to install a block');
+}

package/src/command-line/commands/ls.ts

@@ -0,0 +1,24 @@
+import { loadRegistry } from '../utils/registry.js';
+
+export function ls(): void {
+  const registry = loadRegistry(import.meta.url);
+  const components = Object.values(registry.components ?? {});
+
+  console.log(`Kumo Svelte Components (${components.length} total)`);
+  console.log('');
+
+  const categories = new Map();
+  for (const component of components) {
+    const list = categories.get(component.category) ?? [];
+    list.push(component);
+    categories.set(component.category, list);
+  }
+
+  for (const [category, items] of categories) {
+    console.log(category);
+    for (const component of items) {
+      console.log(`  ${component.name.padEnd(22)} ${component.description}`);
+    }
+    console.log('');
+  }
+}

package/src/command-line/commands/migrate.ts

@@ -0,0 +1,59 @@
+const PENDING_MIGRATIONS: Record<string, string> = {};
+
+const MIGRATE_HELP = `
+Kumo Svelte token migration helper
+
+Usage:
+  kumo-svelte migrate             Output token rename map as JSON
+  kumo-svelte migrate --classes   Output class-level mappings
+  kumo-svelte migrate --to-old    Reverse migration direction
+  kumo-svelte migrate --help      Show this help
+`;
+
+function generateClassMap(): Record<string, string> {
+  const classes: Record<string, string> = {};
+  for (const [oldToken, newToken] of Object.entries(PENDING_MIGRATIONS)) {
+    for (const prefix of ['bg', 'text', 'border', 'ring', 'from', 'via', 'to', 'fill', 'stroke']) {
+      classes[`${prefix}-${oldToken}`] = `${prefix}-${newToken}`;
+    }
+  }
+  return classes;
+}
+
+export function migrate(args: string[]): void {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(MIGRATE_HELP.trim());
+    return;
+  }
+
+  if (Object.keys(PENDING_MIGRATIONS).length === 0) {
+    console.log('No pending token migrations.');
+    console.log('');
+    console.log('Your codebase is up to date with the current Kumo Svelte version.');
+    return;
+  }
+
+  const classes = generateClassMap();
+  if (args.includes('--classes')) {
+    for (const [from, to] of Object.entries(classes)) {
+      console.log(`${from} -> ${to}`);
+    }
+    return;
+  }
+
+  console.log(
+    JSON.stringify(
+      {
+        meta: {
+          description: 'Kumo Svelte token class name migration map',
+          direction: args.includes('--to-old') ? 'to-old' : 'to-new',
+          generatedAt: new Date().toISOString()
+        },
+        tokens: PENDING_MIGRATIONS,
+        classes
+      },
+      null,
+      2
+    )
+  );
+}

package/src/command-line/utils/config.ts

@@ -0,0 +1,34 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const DEFAULT_CONFIG = {
+  blocksDir: 'src/components/kumo',
+  version: '1.0.0'
+};
+
+export type KumoConfig = typeof DEFAULT_CONFIG;
+
+export function readConfig(projectRoot = process.cwd()): KumoConfig | null {
+  const configPath = join(projectRoot, 'kumo.json');
+  if (!existsSync(configPath)) return null;
+
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    return { ...DEFAULT_CONFIG, ...config };
+  } catch (error) {
+    throw new Error(
+      `Failed to parse kumo.json: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
+    );
+  }
+}
+
+export function writeConfig(config: Partial<KumoConfig>, projectRoot = process.cwd()) {
+  const configPath = join(projectRoot, 'kumo.json');
+  const content = JSON.stringify({ ...DEFAULT_CONFIG, ...config }, null, 2) + '\n';
+  writeFileSync(configPath, content, 'utf-8');
+}
+
+export function configExists(projectRoot = process.cwd()): boolean {
+  return existsSync(join(projectRoot, 'kumo.json'));
+}

package/src/command-line/utils/paths.ts

@@ -0,0 +1,33 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function packageRootFrom(metaUrl: string): string {
+  const currentDir = dirname(fileURLToPath(metaUrl));
+  const candidates = [
+    join(currentDir, '..', '..', '..'),
+    join(currentDir, '..', '..'),
+    process.cwd()
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(join(candidate, 'package.json'))) return candidate;
+  }
+
+  return candidates[0];
+}
+
+export function findPackageFile(metaUrl: string, relativePath: string): string | null {
+  const root = packageRootFrom(metaUrl);
+  const candidates = [
+    join(root, relativePath),
+    join(root, 'dist', relativePath),
+    join(root, 'src', relativePath)
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  return null;
+}

package/src/command-line/utils/registry.ts

@@ -0,0 +1,48 @@
+import { readFileSync } from 'node:fs';
+import { findPackageFile } from './paths.js';
+
+export type RegistryProp = {
+  name: string;
+  type: string;
+  required?: boolean;
+  description?: string;
+};
+
+export type RegistryExample = {
+  title: string;
+};
+
+export type RegistryComponent = {
+  name: string;
+  description: string;
+  category: string;
+  sourceFile?: string;
+  props?: RegistryProp[];
+  examples?: RegistryExample[];
+};
+
+export type RegistryBlock = {
+  name: string;
+  description: string;
+  category: string;
+  files: string[];
+  dependencies?: string[];
+};
+
+export type ComponentRegistry = {
+  components?: Record<string, RegistryComponent>;
+  blocks?: Record<string, RegistryBlock>;
+};
+
+export function loadRegistry(metaUrl = import.meta.url): ComponentRegistry {
+  const registryPath = findPackageFile(metaUrl, 'ai/component-registry.json');
+  if (!registryPath) {
+    throw new Error('component-registry.json not found.');
+  }
+
+  return JSON.parse(readFileSync(registryPath, 'utf-8')) as ComponentRegistry;
+}
+
+export function formatComponentName(name: string): string {
+  return String(name).replace(/[\s_-]+(.)?/g, (_, char) => (char ? char.toUpperCase() : ''));
+}

package/src/command-line/utils/transformer.ts

@@ -0,0 +1,16 @@
+const PACKAGE_NAME = 'kumo-svelte';
+
+function shouldTransform(path: string): boolean {
+  return (
+    path.startsWith('$lib/components/') ||
+    path.startsWith('$lib/utils/') ||
+    (path.startsWith('../') && (path.includes('/components/') || path.includes('/utils/')))
+  );
+}
+
+export function transformImports(content: string): string {
+  return content.replace(
+    /from\s+["'](?:(?:\.\.\/)+(?:components|utils)\/[^"']+|\$lib\/(?:components|utils)\/[^"']+)["'];?/g,
+    `from '${PACKAGE_NAME}';`
+  );
+}

package/src/lib/components/autocomplete/Autocomplete.svelte

@@ -0,0 +1,128 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import Field from '$lib/components/field/Field.svelte';
+  import { cn } from '$lib/utils/cn';
+  import {
+    normalizeAutocompleteItem,
+    setAutocompleteContext,
+    type AutocompleteItem,
+    type AutocompleteSize,
+    type NormalizedAutocompleteItem
+  } from './context';
+
+  type FieldError = string | { message?: string; match?: boolean };
+
+  export interface Props {
+    children?: Snippet;
+    class?: string;
+    items?: AutocompleteItem[];
+    value?: string;
+    defaultValue?: string;
+    open?: boolean;
+    size?: AutocompleteSize;
+    label?: string | Snippet;
+    description?: string | Snippet;
+    error?: FieldError;
+    required?: boolean;
+    filter?: ((item: AutocompleteItem, query: string) => boolean) | null;
+    onValueChange?: (value: string) => void;
+    onOpenChange?: (open: boolean) => void;
+    [key: string]: unknown;
+  }
+
+  let {
+    children,
+    class: className,
+    items = [],
+    defaultValue,
+    value = $bindable(defaultValue ?? ''),
+    open = $bindable(false),
+    size = 'base',
+    label,
+    description,
+    error,
+    required,
+    filter,
+    onValueChange,
+    onOpenChange,
+    ...rest
+  }: Props = $props();
+
+  let query = $state(value);
+
+  const normalizedItems = $derived(items.map(normalizeAutocompleteItem));
+  const errorMessage = $derived(
+    typeof error === 'string' ? error : error?.match === false ? undefined : error?.message
+  );
+  const filteredItems = $derived.by<NormalizedAutocompleteItem[]>(() => {
+    const term = query.trim().toLowerCase();
+    if (!term) return normalizedItems;
+    if (filter === null) return normalizedItems;
+
+    return normalizedItems.filter((item) => {
+      if (filter) return filter(item.raw, query);
+      return item.label.toLowerCase().includes(term) || item.value.toLowerCase().includes(term);
+    });
+  });
+
+  function select(item: NormalizedAutocompleteItem) {
+    if (item.disabled) return;
+    value = item.value;
+    query = item.label;
+    open = false;
+    onValueChange?.(item.value);
+    onOpenChange?.(false);
+  }
+
+  setAutocompleteContext({
+    get items() {
+      return normalizedItems;
+    },
+    get filteredItems() {
+      return filteredItems;
+    },
+    get query() {
+      return query;
+    },
+    set query(nextQuery: string) {
+      query = nextQuery;
+      value = nextQuery;
+      onValueChange?.(nextQuery);
+    },
+    get value() {
+      return value;
+    },
+    set value(nextValue: string) {
+      value = nextValue;
+      onValueChange?.(nextValue);
+    },
+    get open() {
+      return open;
+    },
+    set open(nextOpen: boolean) {
+      open = nextOpen;
+      onOpenChange?.(nextOpen);
+    },
+    get size() {
+      return size;
+    },
+    get invalid() {
+      return Boolean(errorMessage);
+    },
+    select
+  });
+</script>
+
+{#snippet control()}
+  <div class={cn('relative w-full', className)} {...rest}>
+    {@render children?.()}
+  </div>
+{/snippet}
+
+{#if label || description || errorMessage}
+  <Field {label} {description} error={errorMessage} {required}>
+    {@render control()}
+  </Field>
+{:else}
+  {@render control()}
+{/if}

package/src/lib/components/autocomplete/AutocompleteCollection.svelte

@@ -0,0 +1,20 @@
+<script lang="ts">
+  import type { ItemSnippet } from './context';
+  import { getAutocompleteGroupContext } from './context';
+  import { cn } from '$lib/utils/cn';
+
+  export interface Props {
+    children?: ItemSnippet;
+    class?: string;
+    [key: string]: unknown;
+  }
+
+  let { children, class: className, ...rest }: Props = $props();
+  const context = getAutocompleteGroupContext();
+</script>
+
+<div class={cn('contents', className)} {...rest}>
+  {#each context?.items ?? [] as item (item.value)}
+    {@render children?.(item.raw)}
+  {/each}
+</div>

package/src/lib/components/autocomplete/AutocompleteContent.svelte

@@ -0,0 +1,26 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { getAutocompleteContext } from './context';
+  import { cn } from '$lib/utils/cn';
+
+  export interface Props {
+    children?: Snippet;
+    class?: string;
+    [key: string]: unknown;
+  }
+
+  let { children, class: className, ...rest }: Props = $props();
+  const context = getAutocompleteContext('Autocomplete.Content');
+</script>
+
+{#if context.open && context.filteredItems.length}
+  <div
+    class={cn(
+      'absolute z-50 mt-1 flex max-h-96 min-w-full flex-col overflow-hidden rounded-lg bg-kumo-control py-1.5 text-kumo-default shadow-lg ring ring-kumo-line',
+      className
+    )}
+    {...rest}
+  >
+    {@render children?.()}
+  </div>
+{/if}

package/src/lib/components/autocomplete/AutocompleteGroup.svelte

@@ -0,0 +1,32 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import {
+    normalizeAutocompleteItem,
+    setAutocompleteGroupContext,
+    type AutocompleteItem
+  } from './context';
+  import { cn } from '$lib/utils/cn';
+
+  export interface Props {
+    children?: Snippet;
+    class?: string;
+    items?: AutocompleteItem[];
+    [key: string]: unknown;
+  }
+
+  let { children, class: className, items = [], ...rest }: Props = $props();
+  const normalizedItems = $derived(items.map(normalizeAutocompleteItem));
+
+  setAutocompleteGroupContext({
+    get items() {
+      return normalizedItems;
+    }
+  });
+</script>
+
+<div
+  class={cn('mt-2 border-t border-kumo-line pt-2 first:mt-0 first:border-t-0 first:pt-0', className)}
+  {...rest}
+>
+  {@render children?.()}
+</div>