@indodev/toolkit 0.1.4 → 0.2.0

package/dist/text/index.d.ts

@@ -0,0 +1,284 @@
+export { C as CompareOptions, E as ExtractOptions, j as SanitizeOptions, S as SlugifyOptions, T as TitleCaseOptions, k as TruncateOptions, c as capitalize, h as compareStrings, d as contractAbbreviation, e as expandAbbreviation, g as extractWords, n as normalizeWhitespace, r as removeAccents, b as sanitize, i as similarity, s as slugify, a as toSentenceCase, t as toTitleCase, f as truncate } from '../compare-B1MKSOWV.js';
+
+/**
+ * ============================================================================
+ * INDONESIAN TEXT UTILITIES - CONSTANTS
+ * ============================================================================
+ *
+ * This file contains constants for Indonesian and English text processing:
+ * - LOWERCASE_WORDS: Particles that stay lowercase in title case
+ * - ACRONYMS: Abbreviations that stay UPPERCASE in title case
+ * - ABBREVIATIONS: Full expansions of common Indonesian abbreviations
+ *
+ * ============================================================================
+ * MAINTENANCE GUIDE
+ * ============================================================================
+ *
+ * ## How to Add New Entries
+ *
+ * ### 1. LOWERCASE_WORDS (Particles)
+ *
+ * Add words that should remain lowercase in title case (except when first word).
+ *
+ * **Indonesian Grammar Rules (PUEBI):**
+ * - Prepositions: di, ke, dari, untuk, dengan, pada, dalam, etc.
+ * - Conjunctions: dan, atau, tetapi, serta, maupun, etc.
+ * - Articles/particles: yang, sebagai, adalah, akan, telah, etc.
+ *
+ * **English Grammar Rules (Chicago Manual of Style):**
+ * - Articles: a, an, the
+ * - Conjunctions: and, or, but, nor, for, yet, so
+ * - Short prepositions (<5 letters): at, by, in, of, on, to, up, etc.
+ *
+ * **Example Addition:**
+ * ```typescript
+ * export const LOWERCASE_WORDS = [
+ *   // ... existing entries
+ *   'bagi',      // Indonesian: for/to (preposition)
+ *   'antara',    // Indonesian: between (preposition)
+ *   'into',      // English: preposition
+ * ] as const;
+ * ```
+ *
+ * **Testing:** Add test case in `toTitleCase.test.ts`:
+ * ```typescript
+ * it('keeps "bagi" lowercase in middle', () => {
+ *   expect(toTitleCase('buku bagi pemula')).toBe('Buku bagi Pemula');
+ * });
+ * ```
+ *
+ * ### 2. ACRONYMS (Always Uppercase)
+ *
+ * Add abbreviations that should always appear in UPPERCASE.
+ *
+ * **Categories:**
+ * - Government & Military: TNI, POLRI, KPK, DPR, etc.
+ * - Business Entities: PT, CV, BUMN, etc.
+ * - Banks: BCA, BRI, BNI, etc.
+ * - Services: BPJS, PLN, KTP, SIM, etc.
+ * - Technology: IT, AI, API, SEO, etc.
+ * - Education: UI, ITB, UGM, etc.
+ * - International: UN, WHO, NATO, ASEAN, etc.
+ *
+ * **Validation Checklist:**
+ * ✅ Is it commonly written in ALL CAPS?
+ * ✅ Is it an official acronym (not just shortened word)?
+ * ✅ Will it look wrong if title-cased (e.g., "Pt" instead of "PT")?
+ *
+ * **Example Addition:**
+ * ```typescript
+ * export const ACRONYMS = [
+ *   // ... existing entries
+ *   'OJK',      // Otoritas Jasa Keuangan
+ *   'BI',       // Bank Indonesia
+ *   'NASA',     // National Aeronautics and Space Administration
+ * ] as const;
+ * ```
+ *
+ * **Testing:** Add test case in `toTitleCase.test.ts`:
+ * ```typescript
+ * it('preserves OJK uppercase', () => {
+ *   expect(toTitleCase('ojk indonesia')).toBe('OJK Indonesia');
+ * });
+ * ```
+ *
+ * ### 3. ABBREVIATIONS (Expansion Mapping)
+ *
+ * Add abbreviation → full form mappings for `expandAbbreviation()` function.
+ *
+ * **Categories (use comment headers):**
+ * - Address: Jl., Gg., Kec., Kab., etc.
+ * - Academic Titles: Dr., Ir., Prof., S.H., M.M., etc.
+ * - Honorifics: Bpk., Yth., H., Hj., etc.
+ * - Organizations: PT., CV., UD., etc.
+ * - Common: dst., dll., a.n., etc.
+ * - Contact Info: Tlp., HP., Fax, etc.
+ * - Days/Months: Sen., Jan., Feb., etc.
+ * - Units: kg., km., lt., etc.
+ *
+ * **Key Format Rules:**
+ * - Include period if commonly written: `'Jl.'` not `'Jl'`
+ * - Use proper capitalization: `'Jalan'` not `'jalan'`
+ * - Keep it concise: Full form only, no explanations
+ *
+ * **Example Addition:**
+ * ```typescript
+ * export const ABBREVIATIONS: Record<string, string> = {
+ *   // ... existing entries
+ *
+ *   // ========== New Category Example ==========
+ *   'Apt.': 'Apartemen',
+ *   'Ruko': 'Rumah Toko',
+ *   'Rukan': 'Rumah Kantor',
+ * };
+ * ```
+ *
+ * **Testing:** Add test case in `abbreviation.test.ts`:
+ * ```typescript
+ * it('expands Apt. to Apartemen', () => {
+ *   expect(expandAbbreviation('Apt. Sudirman'))
+ *     .toBe('Apartemen Sudirman');
+ * });
+ * ```
+ *
+ * ============================================================================
+ * DATA SOURCES & REFERENCES
+ * ============================================================================
+ *
+ * When adding new entries, refer to these authoritative sources:
+ *
+ * **Indonesian Language:**
+ * - PUEBI (Pedoman Umum Ejaan Bahasa Indonesia)
+ *   https://puebi.js.org/
+ *
+ * - KBBI (Kamus Besar Bahasa Indonesia)
+ *   https://kbbi.kemdikbud.go.id/
+ *
+ * - Wikipedia Indonesia - Daftar Singkatan
+ *   https://id.wikipedia.org/wiki/Daftar_singkatan_di_Indonesia
+ *
+ * **English Language:**
+ * - Chicago Manual of Style (Title Case Rules)
+ *   https://www.chicagomanualofstyle.org/
+ *
+ * - AP Stylebook
+ *   https://www.apstylebook.com/
+ *
+ * **Government & Official:**
+ * - Kemendagri (addresses, administrative divisions)
+ *   https://www.kemendagri.go.id/
+ *
+ * - Kemenkumham (business entities)
+ *   https://www.kemenkumham.go.id/
+ *
+ * - Kemendikbud (education, degrees)
+ *   https://www.kemdikbud.go.id/
+ *
+ * ============================================================================
+ * CONTRIBUTION GUIDELINES
+ * ============================================================================
+ *
+ * **Before Adding:**
+ * 1. ✅ Check if entry already exists (Ctrl+F)
+ * 2. ✅ Verify spelling from official sources
+ * 3. ✅ Ensure it's commonly used (not obscure)
+ * 4. ✅ Choose correct category/section
+ *
+ * **After Adding:**
+ * 1. ✅ Add corresponding test case
+ * 2. ✅ Run tests: `npm test constants`
+ * 3. ✅ Update this file's documentation if needed
+ * 4. ✅ Add source reference in PR description
+ *
+ * **PR Template:**
+ * ```
+ * ### Added Constants
+ *
+ * **Type:** [LOWERCASE_WORDS | ACRONYMS | ABBREVIATIONS]
+ *
+ * **Entries:**
+ * - `OJK` - Otoritas Jasa Keuangan
+ * - `BI` - Bank Indonesia
+ *
+ * **Source:** https://www.ojk.go.id/
+ *
+ * **Test Coverage:** ✅ Added in toTitleCase.test.ts line 245
+ *
+ * **Rationale:**
+ * Commonly used financial regulatory bodies in Indonesian context.
+ * ```
+ *
+ * ============================================================================
+ * COMMON PITFALLS TO AVOID
+ * ============================================================================
+ *
+ * ❌ **Don't add brand-specific styling** (e.g., "iPhone" → keep user control)
+ * ❌ **Don't add regional dialects** (stick to standard Indonesian/English)
+ * ❌ **Don't add context-dependent acronyms** (e.g., "UI" = both User Interface & Universitas Indonesia)
+ * ❌ **Don't add very rare/obscure terms** (focus on common usage)
+ * ❌ **Don't forget the period** in ABBREVIATIONS (e.g., use `'Dr.'` not `'Dr'`)
+ * ❌ **Don't mix singular/plural** in ABBREVIATIONS (choose one consistently)
+ *
+ * ✅ **Do keep entries alphabetically sorted** within categories
+ * ✅ **Do use proper capitalization** in expanded forms
+ * ✅ **Do add comments** for non-obvious entries
+ * ✅ **Do verify against official sources** before adding
+ * ✅ **Do write test cases** for new additions
+ *
+ * ============================================================================
+ * FUTURE EXTENSIBILITY
+ * ============================================================================
+ *
+ * **Planned Enhancements:**
+ *
+ * 1. **External Data Source Support:**
+ *    ```typescript
+ *    import customAcronyms from './data/custom-acronyms.json';
+ *    export const ACRONYMS = [...DEFAULT_ACRONYMS, ...customAcronyms];
+ *    ```
+ *
+ * 2. **Context-Aware Acronyms:**
+ *    ```typescript
+ *    export const CONTEXT_ACRONYMS = {
+ *      'UI': {
+ *        tech: 'UI',         // User Interface
+ *        education: 'UI',    // Universitas Indonesia
+ *      }
+ *    };
+ *    ```
+ *
+ * 3. **Locale-Specific Sets:**
+ *    ```typescript
+ *    export const LOWERCASE_WORDS = {
+ *      id: [...], // Indonesian
+ *      en: [...], // English
+ *      mixed: [...], // Combined (default)
+ *    };
+ *    ```
+ *
+ * 4. **Dynamic Loading:**
+ *    ```typescript
+ *    // Load additional acronyms from user config
+ *    export async function loadCustomConstants(url: string) {
+ *      const data = await fetch(url).then(r => r.json());
+ *      return [...ACRONYMS, ...data.acronyms];
+ *    }
+ *    ```
+ *
+ * ============================================================================
+ * VERSIONING & CHANGELOG
+ * ============================================================================
+ *
+ * Track major additions here:
+ *
+ * - v0.2.0 (2024-12-18): Initial comprehensive dataset
+ *   - 50+ Indonesian particles
+ *   - 150+ acronyms (Indonesian + International)
+ *   - 80+ abbreviation mappings
+ *
+ * - v0.2.1 (TBD): Add financial sector acronyms (OJK, BI, etc.)
+ * - v0.2.2 (TBD): Add technology company acronyms
+ *
+ * ============================================================================
+ */
+/**
+ * Indonesian and English lowercase particles
+ * These words remain lowercase in title case (except when first word)
+ *
+ * Based on:
+ * - Indonesian grammar (PUEBI)
+ * - English title case rules (Chicago Manual of Style)
+ */
+declare const LOWERCASE_WORDS: readonly ["di", "ke", "dari", "pada", "dalam", "untuk", "dengan", "oleh", "kepada", "terhadap", "tentang", "tanpa", "hingga", "sampai", "sejak", "menuju", "melalui", "dan", "atau", "tetapi", "namun", "serta", "maupun", "melainkan", "sedangkan", "yang", "sebagai", "adalah", "ialah", "yaitu", "bahwa", "akan", "telah", "sudah", "belum", "a", "an", "the", "and", "or", "but", "nor", "for", "yet", "so", "as", "at", "by", "in", "of", "on", "to", "up", "via", "per", "off", "out"];
+/**
+ * Indonesian and international acronyms
+ * These always remain UPPERCASE in title case
+ */
+declare const ACRONYMS: readonly ["DKI", "DIY", "TNI", "POLRI", "ABRI", "MPR", "DPR", "KPK", "BIN", "PT", "CV", "UD", "PD", "Tbk", "BUMN", "BUMD", "BCA", "BRI", "BNI", "BTN", "BSI", "BPD", "KTP", "NIK", "NPWP", "SIM", "STNK", "BPJS", "KIS", "KIP", "PKH", "PLN", "PDAM", "PGN", "KAI", "MRT", "LRT", "PBB", "PPh", "PPN", "BPHTB", "UI", "ITB", "UGM", "IPB", "ITS", "UNPAD", "UNDIP", "UNAIR", "UNS", "S.Pd", "S.H", "S.E", "S.T", "S.Kom", "S.Si", "S.Sos", "M.Pd", "M.M", "M.T", "M.Kom", "ATM", "POS", "SMS", "GPS", "WiFi", "USB", "PIN", "OTP", "QR", "IT", "AI", "ML", "API", "UI", "UX", "SEO", "SaaS", "CRM", "ERP", "CEO", "CFO", "CTO", "COO", "CMO", "HR", "PR", "VP", "GM", "UN", "WHO", "UNESCO", "NATO", "ASEAN", "APEC", "WTO", "IMF", "ICU", "ER", "MRI", "CT", "DNA", "RNA", "HIV", "AIDS", "COVID", "KM", "CM", "MM", "KG", "RPM", "MPH", "KPH", "IPO", "ATM", "ROI", "GDP", "VAT"];
+/**
+ * Indonesian abbreviations mapping
+ * Organized by category for maintainability
+ */
+declare const ABBREVIATIONS: Record<string, string>;
+
+export { ABBREVIATIONS, ACRONYMS, LOWERCASE_WORDS };