feat(F-136): completed feature

project/src/shared/tests/text.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import { toTitleCase } from '../text.js';
+
+describe('toTitleCase', () => {
+  it('returns empty string unchanged', () => {
+    expect(toTitleCase('')).toBe('');
+  });
+
+  it('title-cases a single ALL-CAPS word', () => {
+    expect(toTitleCase('BIOCOP')).toBe('Biocop');
+    expect(toTitleCase('LAMBERTS')).toBe('Lamberts');
+    expect(toTitleCase('SOLGAR')).toBe('Solgar');
+  });
+
+  it('title-cases a multi-word ALL-CAPS string with spaces', () => {
+    expect(toTitleCase('EL GRANERO INTEGRAL')).toBe('El Granero Integral');
+    expect(toTitleCase('COMPLEMENTOS Y NUTRICIÓN')).toBe('Complementos y Nutrición');
+    expect(toTitleCase('LA FINESTRA SUL CIELO')).toBe('La Finestra Sul Cielo');
+    expect(toTitleCase('DULCES LISSEN')).toBe('Dulces Lissen');
+  });
+
+  it('preserves dots as word boundaries (A.VOGEL → A.Vogel)', () => {
+    expect(toTitleCase('A.VOGEL')).toBe('A.Vogel');
+  });
+
+  it('preserves hyphens as word boundaries (DAS-BROT → Das-Brot)', () => {
+    expect(toTitleCase('DAS-BROT')).toBe('Das-Brot');
+  });
+
+  it('preserves ampersands as word boundaries (TEA & INFUSIONS → Tea & Infusions)', () => {
+    expect(toTitleCase('TEA & INFUSIONS')).toBe('Tea & Infusions');
+  });
+
+  it('handles Spanish accented characters (NUTRICIÓN → Nutrición)', () => {
+    expect(toTitleCase('COMPLEMENTOS Y NUTRICIÓN')).toBe('Complementos y Nutrición');
+  });
+
+  it('is idempotent on already Title-Cased strings', () => {
+    expect(toTitleCase('La Finestra Sul Cielo')).toBe('La Finestra Sul Cielo');
+    expect(toTitleCase('A.Vogel')).toBe('A.Vogel');
+    expect(toTitleCase('El Granero Integral')).toBe('El Granero Integral');
+    expect(toTitleCase(toTitleCase('A.VOGEL'))).toBe('A.Vogel');
+  });
+
+  it('leaves mixed-case strings unchanged (BioSana)', () => {
+    expect(toTitleCase('BioSana')).toBe('BioSana');
+  });
+
+  it('does not corrupt digits or other non-letter characters in words', () => {
+    expect(toTitleCase('500 KILOS')).toBe('500 Kilos');
+  });
+
+  it('handles multiple consecutive separators', () => {
+    expect(toTitleCase('FOO  BAR')).toBe('Foo  Bar');
+    expect(toTitleCase('A..VOGEL')).toBe('A..Vogel');
+  });
+
+  it('handles a string that is only separators', () => {
+    expect(toTitleCase('   ')).toBe('   ');
+    expect(toTitleCase('---')).toBe('---');
+  });
+
+  it('keeps single-letter conjunction lowercase (y/e/o/u) when not first', () => {
+    expect(toTitleCase('AGUA Y SAL')).toBe('Agua y Sal');
+    expect(toTitleCase('PADRE E HIJO')).toBe('Padre e Hijo');
+    expect(toTitleCase('SIETE O NUEVE')).toBe('Siete o Nueve');
+  });
+
+  it('keeps single-letter conjunction capitalized when it IS the first word', () => {
+    expect(toTitleCase('Y HIRVIO')).toBe('Y Hirvio');
+  });
+
+  it('does not lowercase non-conjunction single-letter words', () => {
+    expect(toTitleCase('A SIDE B')).toBe('A Side B');
+  });
+});

project/src/shared/text.ts

@@ -0,0 +1,64 @@
+/**
+ * Pure string utilities shared across modules.
+ */
+
+/**
+ * Spanish single-letter conjunctions that stay lowercase in Title Case,
+ * except when they are the first word of the string.
+ *
+ * Standard Spanish typography rule (RAE): preposiciones y conjunciones
+ * (a, con, de, e, en, o, por, u, y…) van en minúscula salvo que sean la
+ * primera palabra. Single-letter conjunctions are included here so a
+ * "Y" between two words renders correctly.
+ */
+const LOWERCASE_WORDS = new Set(['y', 'e', 'o', 'u']);
+
+/**
+ * Convert a brand/category name to Title Case.
+ *
+ * Splits on word boundaries (space, hyphen, dot, ampersand, slash) and
+ * uppercases the first letter of each word, lowercasing the rest of the
+ * word. Punctuation and whitespace separators are preserved verbatim.
+ *
+ * Behavior:
+ * - If the input is ALL-CAPS (every letter is uppercase and at least one
+ *   is lowercase-equivalent), each word is Title Cased and Spanish
+ *   single-letter conjunctions (y/e/o/u) are lowercased unless they
+ *   are the first word.
+ * - If the input has mixed case (e.g. "BioSana"), it is returned
+ *   unchanged. This makes the function idempotent for re-application:
+ *   a Title-Cased string is a fixed point, and a mixed-case string is
+ *   not what we're trying to fix.
+ * - Empty string → empty string.
+ *
+ * @example
+ * toTitleCase('A.VOGEL')                    // 'A.Vogel'
+ * toTitleCase('BIOCOP')                     // 'Biocop'
+ * toTitleCase('EL GRANERO INTEGRAL')        // 'El Granero Integral'
+ * toTitleCase('COMPLEMENTOS Y NUTRICIÓN')   // 'Complementos y Nutrición'
+ * toTitleCase('DULCES LISSEN')              // 'Dulces Lissen'
+ * toTitleCase('La Finestra Sul Cielo')      // 'La Finestra Sul Cielo' (unchanged)
+ * toTitleCase('BioSana')                     // 'BioSana' (unchanged)
+ * toTitleCase('')                            // ''
+ */
+export function toTitleCase(input: string): string {
+  if (!input) return input;
+  // Only transform strings that are entirely uppercase. A mixed-case string
+  // is treated as already-formatted and returned verbatim.
+  if (input !== input.toUpperCase() || input === input.toLowerCase()) {
+    return input;
+  }
+  // Split keeping the delimiters so we can reconstruct the string verbatim.
+  const parts = input.split(/([\s.\-/&]+)/g);
+  let isFirstWord = true;
+  return parts
+    .map((part) => {
+      if (/^[\s.\-/&]+$/.test(part)) return part;
+      if (part.length === 0) return part;
+      const lower = part.toLocaleLowerCase('es-ES');
+      if (!isFirstWord && LOWERCASE_WORDS.has(lower)) return lower;
+      isFirstWord = false;
+      return part.charAt(0).toLocaleUpperCase('es-ES') + part.slice(1).toLocaleLowerCase('es-ES');
+    })
+    .join('');
+}