@ciwergrp/nuxid 1.0.2-release

package/README.md

@@ -0,0 +1,119 @@
+# Kiban – Nuxt Essentials
+
+Kiban bundles a handful of productivity helpers for Nuxt projects: icon defaults, lodash auto-imports, Element Plus validation helpers, and a flexible form composable. Enable the pieces you need and keep the rest off.
+
+## Quick start
+
+Install and register the module:
+
+```bash
+pnpm add kiban
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['kiban'],
+  kiban: {
+    // lodash, validator, icon, and form are enabled by default
+  },
+})
+```
+
+## Features
+
+- **Icon defaults** (`@nuxt/icon` dependency): component name `KIcon`, size `1.25em`, base class `align-middle inline-block text-current`, mode `svg`. Override via `kiban.icon`, or disable with `kiban.icon = false`.
+- **Lodash auto-imports**: imports from `lodash-es` with prefix `ki` (e.g. `kiDebounce`), skips prefix for names starting with `is`. Configure with:
+  - `enabled` (default `true`)
+  - `prefix` (`false | string`, default `'ki'`)
+  - `prefixSkip` (`string | string[] | false`, default `'is'`)
+  - `upperAfterPrefix` (`boolean`, default `true`)
+  - `exclude` (`string[]`)
+  - `alias` (`Array<[from, to]>`)
+- **Validator helpers**: Element Plus friendly `createValidationRules` plus `ValidationRule` and `ValidationOptions` types. Auto-imported when enabled.
+- **Form composable**: `useForm` wraps `$fetch`, handles `processing`, `errors`, `response`, and builds `FormData` automatically (or always when `alwaysFormData: true`). Auto-imported when enabled.
+
+## Usage snippets
+
+**Lodash example**
+
+```ts
+const result = kiDebounce(() => console.log('hello'), 200)
+```
+
+**Validator example**
+
+```ts
+const rules = createValidationRules(
+  {
+    email: ['required', 'email'],
+    password: ['required', 'min:8'],
+  },
+  formState,
+)
+```
+
+**Form example**
+
+```ts
+const form = useForm({ name: '', avatar: null }, { alwaysFormData: false })
+
+await form.post('/api/profile')
+
+if (form.errors) {
+  console.error(form.errors)
+}
+```
+
+## Configuration reference
+
+```ts
+export default defineNuxtConfig({
+  modules: ['kiban'],
+  kiban: {
+    icon: {
+      enabled: true,
+      componentName: 'KIcon',
+      size: '1.25em',
+      class: 'align-middle inline-block text-current',
+      mode: 'svg',
+      provider: undefined,
+      collections: undefined,
+      aliases: undefined,
+      fallbacks: undefined,
+      extend: undefined,
+    },
+    lodash: {
+      enabled: true,
+      prefix: 'ki',
+      prefixSkip: 'is',
+      upperAfterPrefix: true,
+      exclude: [],
+      alias: [],
+    },
+    validator: {
+      enabled: true,
+    },
+    form: {
+      enabled: true,
+    },
+  },
+})
+```
+
+Disable any feature by setting it to `false` (e.g. `kiban: { lodash: false }`).
+
+## Development
+
+```bash
+pnpm install
+pnpm run dev:prepare    # generate stubs for module + playground
+pnpm run dev            # playground with local module
+pnpm run dev:build      # production-like build of playground
+pnpm run lint
+pnpm run test
+pnpm run test:types
+pnpm run prepack        # build distributable into dist/
+```
+
+Playground lives in `playground/`. Module entry is at `src/module.ts`; runtime code under `src/runtime`; features under `src/features`.

package/bin/kiban.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const args = process.argv.slice(2);
+
+function printHelp() {
+  console.log('\nkiban - helper wrapper for console scripts\n');
+  console.log('Usage: pnpm kiban <command> [options]\n');
+  console.log('Commands:');
+  console.log('  make:request <name>    Interactive generator for request validation files');
+  console.log('\nUse `pnpm kiban <command> --help` for more information.\n');
+}
+
+if (args.length === 0) {
+  printHelp();
+  process.exit(0);
+}
+
+const [command, ...rest] = args;
+
+if (command === 'make:request') {
+  const scriptPath = path.join(__dirname, '../console/request.mjs');
+  const child = spawn(process.execPath, [scriptPath, ...rest], {
+    stdio: 'inherit',
+  });
+
+  child.on('exit', code => process.exit(code ?? 0));
+}
+else if (command === '--help' || command === '-h') {
+  printHelp();
+}
+else {
+  console.error(`Unknown command: ${command}`);
+  printHelp();
+  process.exit(1);
+}

package/console/request.mjs

@@ -0,0 +1,337 @@
+import { exec } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { cwd } from 'node:process';
+import { checkbox, confirm, input } from '@inquirer/prompts';
+
+const colors = {
+  reset: '\x1B[0m',
+  cyan: '\x1B[36m',
+  yellow: '\x1B[33m',
+  green: '\x1B[32m',
+  red: '\x1B[31m',
+  dim: '\x1B[2m',
+};
+
+const availableRules = [
+  'required',
+  'string',
+  'nullable',
+  'email',
+  'alpha',
+  'alpha_num',
+  'alpha_dash',
+  'numeric',
+  'integer',
+  'date',
+  'min',
+  'max',
+  'same',
+  'different',
+  'gt',
+  'gte',
+  'lt',
+  'lte',
+  'starts_with',
+  'ends_with',
+];
+
+const parameterizedRules = new Set([
+  'min',
+  'max',
+  'same',
+  'different',
+  'gt',
+  'gte',
+  'lt',
+  'lte',
+  'starts_with',
+  'ends_with',
+  'regex',
+]);
+
+function toCamelCase(str) {
+  return str.replace(/[-_\s]+(.)?/g, (_match, c) => (c ? c.toUpperCase() : '')).replace(/^\w/, c => c.toLowerCase());
+}
+
+function getTemplate(name, definitions) {
+  const definitionsString = Object.entries(definitions)
+    .map(([field, rules]) => `    ${field}: [${rules.map(r => `'${r}'`).join(', ')}],`)
+    .join('\n');
+
+  return `import type { ValidationRule, ValidationOptions } from 'kiban' // Adjust this import path if needed
+import { createValidationRules } from 'kiban' // Adjust this import path if needed
+// import { useI18n } from 'vue-i18n' // Uncomment if you use i18n
+
+/**
+ * Validation rules for the ${name} request.
+ *
+ * @param form - The reactive form object.
+ * @returns A fully compatible Element Plus FormRules object.
+ */
+export function ${name}Request(form: Record<string, any>) {
+  // const { t } = useI18n() // Uncomment if you use i18n
+
+  /**
+   * The validation rules for the request.
+   */
+  const definitions: Record<string, ValidationRule[] | { rules: ValidationRule[], sometimes: (data: Record<string, any>) => boolean }> = {
+${definitionsString}
+
+  }
+
+  /**
+   * The validation options.
+   */
+  const options: ValidationOptions = {
+    /**
+     * Custom friendly names for fields in error messages.
+     *
+     * email: t('attributes.email'),
+     * password: t('attributes.password'),
+     */
+    attributes: {
+      //
+    },
+
+    /**
+     * Custom messages for specific validation rules.
+     *
+     * 'email.required': 'You must provide an email address.'
+     * 'password.min': 'Your password is too short.'
+     */
+    messages: {
+      //
+    },
+
+    /**
+     * A hook to transform data before validation.
+     *
+     * data.email = data.email.trim().toLowerCase()
+     * return data
+     */
+    prepareForValidation: (data) => {
+      return data
+    },
+
+    /**
+     * An authorization check before validation runs.
+     *
+     * () => user.can('update-profile')
+     */
+    authorize: () => {
+      return true
+    },
+  }
+
+  return createValidationRules(definitions, form, options)
+}
+`;
+}
+
+function displayHeader(title) {
+  const width = title.length + 4;
+  const border = '─'.repeat(width);
+  console.log(`┌${border}┐`);
+  console.log(`│  ${colors.cyan}${title}${colors.reset}  │`);
+  console.log(`└${border}┘\n`);
+}
+
+function loadPrefixFromProjectConfig() {
+  const candidates = [
+    'kiban.mjs',
+    'kiban.cjs',
+    'kiban.js',
+    'kiban.ts',
+    'kiban.json',
+    'kiban.config.json',
+    'artisan.mjs',
+    'artisan.cjs',
+    'artisan.js',
+    'artisan.ts',
+    'artisan.json',
+    'artisan.config.json',
+    'package.json',
+  ];
+
+  for (const file of candidates) {
+    const p = path.join(cwd(), file);
+    if (!fs.existsSync(p)) {
+      continue;
+    }
+
+    try {
+      if (file.endsWith('.json')) {
+        const raw = fs.readFileSync(p, 'utf8');
+        const obj = JSON.parse(raw);
+        if (file === 'package.json') {
+          if (obj?.kiban && typeof obj.kiban.prefix === 'string') {
+            return obj.kiban.prefix;
+          }
+          if (obj?.artisan && typeof obj.artisan.prefix === 'string') {
+            return obj.artisan.prefix;
+          }
+        }
+        if (typeof obj?.prefix === 'string') {
+          return obj.prefix;
+        }
+      }
+
+      if (file.endsWith('.js') || file.endsWith('.mjs') || file.endsWith('.cjs') || file.endsWith('.ts')) {
+        const raw = fs.readFileSync(p, 'utf8');
+        const m = raw.match(/prefix\s*:\s*['"`]([^'"`]+)['"`]/);
+        if (m && m[1] !== undefined) {
+          return m[1];
+        }
+        const mEmpty = raw.match(/prefix\s*:\s*['"`]['"`]/);
+        if (mEmpty) {
+          return '';
+        }
+      }
+    }
+    catch (err) {
+      console.error(`${colors.red}Failed to read config ${file}: ${err.message}${colors.reset}`);
+    }
+  }
+
+  return undefined;
+}
+
+function runLinter(filePath) {
+  console.log(`\n${colors.dim}Running linter...${colors.reset}`);
+  const command = `npx eslint --fix "${filePath}"`;
+
+  exec(command, (error, _stdout, stderr) => {
+    if (error) {
+      console.error(`\n${colors.red}Error running linter on ${filePath}: ${error.message}${colors.reset}`);
+      if (stderr) {
+        console.error(stderr);
+      }
+    }
+    else {
+      console.log(`${colors.green}✅ Linter finished successfully for: ${colors.dim}${filePath}${colors.reset}`);
+    }
+  });
+}
+
+async function run() {
+  const globalArgs = process.argv.slice(2);
+  if (globalArgs.includes('--help') || globalArgs.includes('-h')) {
+    console.log('\nUsage: pnpm kiban make:request [options]\n');
+    console.log('Options:');
+    console.log('  -p, --prefix <dir>    Override the target prefix (default: project\'s config or \'app\')');
+    console.log('  -h, --help            Show this help message\n');
+    console.log('Examples:');
+    console.log('  pnpm kiban make:request login --prefix=src\n');
+    return;
+  }
+
+  console.clear();
+  displayHeader('Create New Request File');
+
+  const name = await input({
+    message: 'What is the name of the request?',
+    validate: value => (value ? true : 'Name is required.'),
+  });
+
+  const fieldsAnswer = await input({
+    message: 'List the fields to add (comma-separated):',
+  });
+  const fields = fieldsAnswer.split(',').map(f => f.trim()).filter(Boolean);
+
+  if (fields.length === 0) {
+    console.log(`\n${colors.dim}No fields provided. Exiting.${colors.reset}`);
+    return;
+  }
+
+  const finalDefinitions = {};
+  for (const field of fields) {
+    const selectedRules = await checkbox({
+      message: `Select validation rules for "${field}":`,
+      choices: availableRules.map(rule => ({ name: rule, value: rule })),
+      theme: {
+        icon: {
+          checked: `${colors.green}☑${colors.reset}`,
+          unchecked: '☐',
+        },
+      },
+    });
+
+    const processedRules = [];
+    for (const rule of selectedRules) {
+      if (parameterizedRules.has(rule)) {
+        const param = await input({ message: `Enter parameter for "${rule}":` });
+        processedRules.push(`${rule}:${param}`);
+      }
+      else {
+        processedRules.push(rule);
+      }
+    }
+    finalDefinitions[field] = processedRules;
+  }
+
+  const camelCaseName = toCamelCase(name);
+  const fileName = `${camelCaseName}Request.ts`;
+
+  const argv = process.argv.slice(2);
+  let cliPrefix;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--prefix=')) {
+      cliPrefix = a.split('=')[1];
+      break;
+    }
+    if (a === '--prefix' && argv[i + 1] !== undefined) {
+      cliPrefix = argv[i + 1];
+      break;
+    }
+    if (a.startsWith('-p=')) {
+      cliPrefix = a.split('=')[1];
+      break;
+    }
+    if (a === '-p' && argv[i + 1] !== undefined) {
+      cliPrefix = argv[i + 1];
+      break;
+    }
+  }
+
+  const configuredPrefix = loadPrefixFromProjectConfig();
+  const prefix = cliPrefix !== undefined ? cliPrefix : (typeof configuredPrefix === 'string' ? configuredPrefix : 'app');
+
+  const baseDir = prefix === '' ? cwd() : path.join(cwd(), prefix);
+  const targetDir = path.join(baseDir, 'requests');
+  const targetPath = path.join(targetDir, fileName);
+
+  const shownPrefix = prefix === '' ? '(project root)' : prefix;
+  console.log(`${colors.dim}Using prefix: ${colors.cyan}${shownPrefix}${colors.reset} -> ${colors.dim}${path.relative(cwd(), targetDir) || '.'}${colors.reset}`);
+
+  const writeFileAndLint = () => {
+    const fileContent = getTemplate(camelCaseName, finalDefinitions).trim();
+    fs.writeFileSync(targetPath, fileContent, 'utf8');
+    console.log(`\n${colors.green}✅ Success! Created/updated request file at: ${colors.dim}${path.relative(cwd(), targetPath)}${colors.reset}`);
+    runLinter(targetPath);
+  };
+
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  if (fs.existsSync(targetPath)) {
+    const overwrite = await confirm({
+      message: 'File already exists. Overwrite?',
+      default: false,
+    });
+
+    if (overwrite) {
+      writeFileAndLint();
+    }
+    else {
+      console.log(`\n${colors.dim}Operation cancelled.${colors.reset}`);
+    }
+  }
+  else {
+    writeFileAndLint();
+  }
+}
+
+run();

package/dist/module.d.mts

@@ -0,0 +1,188 @@
+import * as _nuxt_schema from '@nuxt/schema';
+export * from '../dist/runtime/form.js';
+export { default as useForm } from '../dist/runtime/form.js';
+export * from '../dist/runtime/validator.js';
+export * from '../dist/runtime/helper/index.js';
+
+interface LodashOptions {
+    /**
+     * Enable lodash auto-imports
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * Prefix applied to each import (set `false` to disable)
+     * @default 'use'
+     */
+    prefix: false | string;
+    /**
+     * Skip prefix for names starting with these strings (set `false` to disable)
+     * @default 'is'
+     */
+    prefixSkip: string | string[] | false;
+    /**
+     * Uppercase first letter after the prefix
+     * @default true
+     */
+    upperAfterPrefix: boolean;
+    /**
+     * Extra lodash functions to exclude
+     */
+    exclude: string[];
+    /**
+     * Function aliases as [from, to]
+     */
+    alias: Array<[string, string]>;
+}
+type LodashFeatureInput = boolean | Partial<LodashOptions> | undefined;
+
+interface ValidatorOptions {
+    /**
+     * Enable validator helpers and auto-imports
+     * @default true
+     */
+    enabled: boolean;
+}
+type ValidatorFeatureInput = boolean | Partial<ValidatorOptions> | undefined;
+
+interface IconOptionConfig {
+    /**
+     * Default component name
+     * @default 'KIcon'
+     */
+    componentName: string;
+    /**
+     * Default icon size
+     * @default '1.25em'
+     */
+    size: string;
+    /**
+     * Default class applied to the icon component
+     */
+    class?: string;
+    /**
+     * Render mode for @nuxt/icon
+     * @default 'svg'
+     */
+    mode?: 'svg' | 'css';
+    /**
+     * Custom Iconify provider URL
+     */
+    provider?: string;
+    /**
+     * Custom icon collections
+     */
+    collections?: Record<string, any>;
+    /**
+     * Aliases for icon names
+     */
+    aliases?: Record<string, string>;
+    /**
+     * Fallback icons to try
+     */
+    fallbacks?: string[];
+    /**
+     * Extra options passed directly to @nuxt/icon
+     */
+    extend?: Record<string, any>;
+}
+interface IconOptions {
+    /**
+     * Enable the icon feature
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * Options passed through to @nuxt/icon
+     */
+    config?: IconOptionConfig;
+}
+type IconFeatureInput = boolean | Partial<IconOptions> | undefined;
+
+interface FormOptions {
+    /**
+     * Enable form composable auto-import
+     * @default true
+     */
+    enabled: boolean;
+}
+type FormFeatureInput = boolean | Partial<FormOptions> | undefined;
+
+interface ElementPlusOptions {
+    /**
+     * Enable Element Plus Nuxt module
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * Options passed through to @element-plus/nuxt
+     */
+    config: Record<string, any>;
+}
+type ElementPlusFeatureInput = boolean | Partial<ElementPlusOptions> | Record<string, any> | undefined;
+
+interface HelperOptions {
+    /**
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * Helper configuration
+     */
+    config?: {
+        /**
+         * Choose either fluent factory (`number().abbreviate()`) or prefixed functions (`numberAbbreviate()`, etc.)
+         * @default 'factory'
+         */
+        style?: 'factory' | 'prefix';
+        /**
+         * Locale lookup source
+         * @default 'cookie'
+         */
+        localeSource?: 'cookie' | 'localStorage' | 'query';
+        /**
+         * Key name for locale lookup
+         * @default 'lang'
+         */
+        localeKey?: string;
+        /**
+         * Fallback locale when none is found
+         * @default 'en'
+         */
+        localeFallback?: string;
+        /**
+         * Default currency code
+         * @default 'USD'
+         */
+        defaultCurrency?: string;
+    };
+}
+type HelperFeatureInput = boolean | Partial<HelperOptions> | undefined;
+
+interface PiniaOptions {
+    /**
+     * Enable Pinia integration
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * Directories to auto-import stores from (relative to `srcDir`)
+     * @default ['stores']
+     */
+    storesDirs: string[];
+}
+type PiniaFeatureInput = boolean | Partial<PiniaOptions> | undefined;
+
+interface ModuleOptions {
+    lodash?: LodashFeatureInput;
+    validator?: ValidatorFeatureInput;
+    icon?: IconFeatureInput;
+    form?: FormFeatureInput;
+    elementPlus?: ElementPlusFeatureInput;
+    helper?: HelperFeatureInput;
+    pinia?: PiniaFeatureInput;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "nuxid",
+  "configKey": "kiban",
+  "version": "1.0.2-release",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}