@talex-touch/utils 1.0.14 → 1.0.16

package/common/utils.ts

@@ -0,0 +1,160 @@
+/**
+ * Delays execution for a given amount of milliseconds.
+ *
+ * @param time - Time to sleep in milliseconds.
+ * @returns A promise that resolves with the same time value after the delay.
+ *
+ * @example
+ * ```ts
+ * await sleep(1000); // Waits for 1 second
+ * ```
+ */
+export async function sleep(time: number): Promise<number> {
+    return new Promise(resolve => setTimeout(() => resolve(time), time))
+}
+
+/**
+ * Encodes any string into a `bigint` by converting each character's char code
+ * into a relative offset based on the minimum char code in the string.
+ *
+ * Format: `{minCharCode}000{paddedOffsetPairs}`
+ *
+ * @param str - Any input string to encode.
+ * @returns A BigInt representation of the input string.
+ *
+ * @example
+ * ```ts
+ * const encoded = anyStr2Num("abc"); // e.g., 970000000102
+ * ```
+ */
+export function anyStr2Num(str: string): bigint {
+    const codes = Array.from(str).map(ch => ch.charCodeAt(0))
+    const minCode = Math.min(...codes)
+
+    const encoded = codes
+        .map(code => (code - minCode).toString().padStart(2, '0'))
+        .join('')
+
+    return BigInt(`${minCode}000${encoded}`)
+}
+
+/**
+ * Decodes a BigInt back into the original string.
+ * Assumes the format produced by `anyStr2Num`.
+ *
+ * @param num - The BigInt to decode.
+ * @returns The original decoded string.
+ *
+ * @example
+ * ```ts
+ * const decoded = num2anyStr(970000000102n); // returns "abc"
+ * ```
+ */
+export function num2anyStr(num: bigint): string {
+    const [baseStr, encoded] = num.toString().split('000')
+    const base = Number(baseStr)
+
+    let result = ''
+    for (let i = 0; i < encoded.length; i += 2) {
+        const offset = Number(encoded.slice(i, i + 2))
+        result += String.fromCharCode(base + offset)
+    }
+
+    return result
+}
+
+const LOCALHOST_KEYS = ['localhost', '127.0.0.1']
+
+/**
+ * Determines whether a given URL string points to localhost.
+ *
+ * @param urlStr - The full URL string to check.
+ * @returns `true` if the URL hostname is `localhost` or `127.0.0.1`, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * isLocalhostUrl("http://localhost:3000"); // true
+ * isLocalhostUrl("https://example.com");   // false
+ * ```
+ */
+export function isLocalhostUrl(urlStr: string): boolean {
+    return LOCALHOST_KEYS.includes(new URL(urlStr).hostname)
+}
+
+/**
+ * Serializes a value to JSON, throwing a detailed error on the first unsupported value (like a function, DOM node, symbol, etc.).
+ * Reports the exact path to the error.
+ *
+ * @param value - Any JS value.
+ * @returns The JSON string if serialization succeeds.
+ * @throws Error if an unsupported value is found (reports path and type).
+ */
+export function structuredStrictStringify(value: unknown): string {
+  const seen = new WeakMap<object, string>();
+  const badTypes = [
+    'symbol'
+  ];
+  // Support Map/Set, but not Error, DOM, Proxy, WeakMap, WeakSet
+  function getType(val: any): string {
+    if (val === null) return 'null';
+    if (Array.isArray(val)) return 'Array';
+    if (typeof Document !== 'undefined') {
+      if (val instanceof Node) return 'DOMNode';
+    }
+    if (val instanceof Error) return 'Error';
+    if (val instanceof WeakMap) return 'WeakMap';
+    if (val instanceof WeakSet) return 'WeakSet';
+    if (typeof val === 'object' && val !== null && val.constructor?.name === 'Proxy') return 'Proxy';
+    if (typeof val === 'bigint') return 'BigInt';
+    return typeof val;
+  }
+
+  function serialize(val: any, path: string): any {
+    const type = getType(val);
+    // Block disallowed/unsafe types and edge cases for structured-clone
+    if (badTypes.includes(typeof val) || type === 'DOMNode' || type === 'Error' || type === 'Proxy' || type === 'WeakMap' || type === 'WeakSet' || type === 'BigInt') {
+      throw new Error(`Cannot serialize property at path "${path}": type "${type}"`);
+    }
+    // JSON doesn't support undefined, skip it for values in objects, preserve in arrays as null
+    if (typeof val === 'undefined') return null;
+    // Simple value
+    if (
+      val === null ||
+      typeof val === 'number' ||
+      typeof val === 'boolean' ||
+      typeof val === 'string'
+    ) return val;
+    // Cycle check
+    if (typeof val === 'object') {
+      if (seen.has(val)) {
+        return `[Circular ~${seen.get(val)}]`; // You could just throw if you dislike this fallback!
+      }
+      seen.set(val, path);
+      if (Array.isArray(val)) {
+        return val.map((item, idx) => serialize(item, `${path}[${idx}]`));
+      }
+      if (val instanceof Date) {
+        return val.toISOString();
+      }
+      if (val instanceof Map) {
+        const obj: Record<string, any> = {};
+        for (const [k, v] of val.entries()) {
+          obj[typeof k === 'string' ? k : JSON.stringify(k)] = serialize(v, `${path}[Map(${typeof k === 'string' ? k : JSON.stringify(k)})]`);
+        }
+        return obj;
+      }
+      if (val instanceof Set) {
+        return Array.from(val).map((item, idx) => serialize(item, `${path}[SetEntry${idx}]`));
+      }
+      // General object
+      const res: any = {};
+      for (const key of Object.keys(val)) {
+        res[key] = serialize(val[key], `${path}.${key}`);
+      }
+      return res;
+    }
+    throw new Error(`Cannot serialize property at path "${path}": unknown type`);
+  }
+
+  return JSON.stringify(serialize(value, 'root'));
+}

package/core-box/README.md

@@ -0,0 +1,218 @@
+# Core Box Package
+
+The Core Box package provides unified type definitions and utility functions for the Talex Touch search box system. This package contains the foundational types and tools used across the entire project for search result management and plugin integration.
+
+## Features
+
+### 🎯 Unified Type System
+- **ISearchItem**: Universal search result item interface
+- **IRenderConfig**: Flexible rendering configuration with multiple modes
+- **IDataItem**: Extended interface for data processing results
+- **IAppItem**: Specialized interface for application results
+- **IFileItem**: Specialized interface for file results
+- **IFeatureItem**: Specialized interface for plugin feature results
+
+### 🎨 Render Modes
+The package supports multiple rendering modes for search results:
+
+- **STANDARD**: Default text-based rendering
+- **URL**: URL rendering - loads and displays remote URL content
+- **HTML**: Rich HTML content rendering
+- **JAVASCRIPT**: JavaScript code with syntax highlighting
+- **JSX**: React JSX component rendering
+- **VUE_SFC**: Vue Single File Component rendering
+
+### 🛠️ Utility Functions
+Comprehensive set of utility functions for creating and managing search results:
+
+- `SearchUtils.createSearchItem()`: Create basic search items
+- `SearchUtils.createDataItem()`: Create data processing results
+- `SearchUtils.createAppItem()`: Create application results
+- `SearchUtils.createFileItem()`: Create file results
+- `SearchUtils.createFeatureItem()`: Create plugin feature results
+- `SearchUtils.createErrorItem()`: Create error state items
+- `SearchUtils.sortByPriority()`: Sort results by relevance
+- `SearchUtils.removeDuplicates()`: Remove duplicate results
+- `SearchUtils.filterByConfidence()`: Filter by confidence score
+- `SearchUtils.groupByPluginType()`: Group results by type
+
+## Usage Examples
+
+### Basic Search Item
+```typescript
+import { SearchUtils, RenderMode } from '@talex-touch/utils';
+
+const basicItem = SearchUtils.createSearchItem({
+  name: "My Feature",
+  desc: "A useful plugin feature",
+  pluginName: "my-plugin",
+  keyWords: ["feature", "utility"],
+  render: {
+    mode: RenderMode.STANDARD
+  }
+});
+```
+
+### Data Processing Result
+```typescript
+const dataItem = SearchUtils.createDataItem({
+  name: "Translation Result",
+  desc: "English to Chinese translation",
+  pluginName: "translator",
+  source: "google-translate",
+  dataType: "translation",
+  originalData: "Hello World",
+  processedData: "你好世界",
+  confidence: 95,
+  duration: 120,
+  render: {
+    mode: RenderMode.STANDARD
+  }
+});
+```
+
+### HTML Rendering
+```typescript
+const htmlItem = SearchUtils.createSearchItem({
+  name: "Rich Content",
+  desc: "HTML formatted result",
+  pluginName: "content-plugin",
+  render: {
+    mode: RenderMode.HTML,
+    content: "<div><h3>Title</h3><p>Content</p></div>",
+    options: {
+      trusted: true,
+      className: "custom-content"
+    }
+  }
+});
+```
+
+### Code Rendering
+```typescript
+const codeItem = SearchUtils.createDataItem({
+  name: "JavaScript Function",
+  desc: "Generated code snippet",
+  pluginName: "code-generator",
+  dataType: "javascript",
+  processedData: "function hello() { return 'world'; }",
+  render: {
+    mode: RenderMode.JAVASCRIPT,
+    content: "function hello() { return 'world'; }",
+    options: {
+      syntaxHighlight: true,
+      showLineNumbers: true,
+      theme: "dark"
+    }
+  }
+});
+```
+
+### URL Rendering with Preview
+```typescript
+const urlItem = SearchUtils.createSearchItem({
+  name: "GitHub Repository",
+  desc: "Talex Touch project",
+  pluginName: "web-search",
+  render: {
+    mode: RenderMode.URL,
+    content: "https://github.com/talex-touch/talex-touch", // The actual URL to load
+    preview: {
+      enabled: true,
+      title: "Talex Touch",                                // Preview metadata
+      description: "Modern desktop application framework", // Preview description
+      image: "https://github.com/talex-touch.png"         // Preview image
+    }
+  }
+});
+```
+
+**Note**:
+- `content`: The remote URL that will be loaded and displayed
+- `preview`: Metadata shown before/alongside the loaded URL content
+
+## Type Definitions
+
+### ISearchItem
+The core interface for all search results:
+
+```typescript
+interface ISearchItem {
+  name: string;                    // Display name
+  desc: string;                    // Description
+  icon: IPluginIcon;              // Icon configuration
+  push: boolean;                   // Push mode support
+  names: string[];                 // Searchable names
+  keyWords: string[];             // Search keywords
+  pluginType: string;             // Plugin type
+  type: string;                   // General type
+  value: string;                  // Associated value
+  render?: IRenderConfig;         // Render configuration
+  // ... additional properties
+}
+```
+
+### IRenderConfig
+Configuration for custom rendering:
+
+```typescript
+interface IRenderConfig {
+  mode: RenderMode;               // Rendering mode
+  content?: string;               // Content to render
+  options?: {                     // Render options
+    syntaxHighlight?: boolean;
+    theme?: string;
+    showLineNumbers?: boolean;
+    className?: string;
+    style?: Record<string, string>;
+    trusted?: boolean;
+  };
+  preview?: {                     // URL preview config
+    enabled?: boolean;
+    image?: string;
+    title?: string;
+    description?: string;
+  };
+}
+```
+
+## Integration
+
+This package is automatically exported from `@talex-touch/utils`:
+
+```typescript
+import { 
+  ISearchItem, 
+  IDataItem, 
+  SearchUtils, 
+  RenderMode 
+} from '@talex-touch/utils';
+```
+
+## Best Practices
+
+1. **Always specify render mode**: Even for standard rendering, explicitly set the render mode
+2. **Use appropriate specialized interfaces**: Use IDataItem for data processing, IAppItem for applications, etc.
+3. **Include confidence scores**: For data processing results, always include confidence levels
+4. **Sanitize HTML content**: When using HTML render mode, ensure content is safe
+5. **Provide meaningful keywords**: Include relevant search terms in the keyWords array
+6. **Use consistent naming**: Follow established naming conventions for plugin types
+
+## Migration Guide
+
+If you're migrating from the old type system:
+
+1. Replace `ITranslationItem` with `IDataItem`
+2. Update render configurations to use the new `IRenderConfig` interface
+3. Use `SearchUtils` functions instead of manual object creation
+4. Update import paths to use `@talex-touch/utils`
+
+## Contributing
+
+When adding new types or utilities:
+
+1. Add comprehensive TSDoc comments in English
+2. Include usage examples in documentation
+3. Follow the established naming conventions
+4. Add appropriate unit tests
+5. Update this README with new features

package/core-box/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Core Box Package
+ * Search box core functionality package
+ */
+
+export * from './search';
+export * from './types';