@lucasbernardosn/ts-utils 0.3.0 → 0.5.0

package/README.md

@@ -24,6 +24,7 @@ import { getInitials, isDeepEqual, type DeepPartial } from '@lucasbernardosn/ts-
 | ------ | -------- |
 | `composeEventHandlers` | Junta vários handlers num só, chamados em sequência com os mesmos argumentos; os `undefined` são ignorados |
 | `createSplitProps` | Separa um objeto de props em dois pela lista de chaves, que precisa cobrir todas as chaves do tipo pedido |
+| `getHighlightChunks` | Divide um texto em trechos que casam ou não com a busca (sem acento nem caixa), no formato `{ text, match }`, para destacar o que casou |
 | `getInitials` | As iniciais de um nome, em maiúsculas: a do primeiro e a do último nome |
 | `isDeepEqual` | Igualdade estrutural, inclusive de `Map`, `Set`, `Date`, `RegExp` e arrays tipados |
 | `isNotNullish` | Guard que tira `null` e `undefined` do tipo, para usar no `filter` |

package/dist/index.d.ts

@@ -21,9 +21,10 @@ import { UnknownArray, UnknownFunction, UnknownLooseValue, UnknownObject, Unknow
 import { ValueOf } from "./types/value-of.js";
 import { composeEventHandlers } from "./utils/compose-event-handlers.js";
 import { createSplitProps } from "./utils/create-split-props.js";
+import { GetHighlightChunksOptions, HighlightChunk, getHighlightChunks } from "./utils/get-highlight-chunks.js";
 import { getInitials } from "./utils/get-initials.js";
 import { isDeepEqual } from "./utils/is-deep-equal.js";
 import { isNotNullish } from "./utils/is-not-nullish.js";
 import { mergeBooleansAnd, mergeBooleansOr } from "./utils/merge-booleans.js";
 import { PascalCase, toPascalCase } from "./utils/to-pascal-case.js";
-export { AnyArray, AnyFunction, AnyLooseValue, AnyObject, AnyType, ArrayElement, DeepKeys, DeepKeysFlat, DeepPartial, DeepReadonly, DeepValue, EnsureString, KeysOfType, MergeOverride, NonEmptyArray, Nullish, OmitByValue, Optional, PascalCase, PickByValue, Recompose, RequiredExcept, SerializableValue, StrictEmptyObject, UnknownArray, UnknownFunction, UnknownLooseValue, UnknownObject, UnknownType, ValueOf, composeEventHandlers, createSplitProps, getInitials, isDeepEqual, isNotNullish, mergeBooleansAnd, mergeBooleansOr, sleep, toPascalCase };
+export { AnyArray, AnyFunction, AnyLooseValue, AnyObject, AnyType, ArrayElement, DeepKeys, DeepKeysFlat, DeepPartial, DeepReadonly, DeepValue, EnsureString, GetHighlightChunksOptions, HighlightChunk, KeysOfType, MergeOverride, NonEmptyArray, Nullish, OmitByValue, Optional, PascalCase, PickByValue, Recompose, RequiredExcept, SerializableValue, StrictEmptyObject, UnknownArray, UnknownFunction, UnknownLooseValue, UnknownObject, UnknownType, ValueOf, composeEventHandlers, createSplitProps, getHighlightChunks, getInitials, isDeepEqual, isNotNullish, mergeBooleansAnd, mergeBooleansOr, sleep, toPascalCase };

package/dist/index.js

@@ -1,9 +1,10 @@
 import { sleep } from "./dev/sleep.js";
 import { composeEventHandlers } from "./utils/compose-event-handlers.js";
 import { createSplitProps } from "./utils/create-split-props.js";
+import { getHighlightChunks } from "./utils/get-highlight-chunks.js";
 import { getInitials } from "./utils/get-initials.js";
 import { isDeepEqual } from "./utils/is-deep-equal.js";
 import { isNotNullish } from "./utils/is-not-nullish.js";
 import { mergeBooleansAnd, mergeBooleansOr } from "./utils/merge-booleans.js";
 import { toPascalCase } from "./utils/to-pascal-case.js";
-export { composeEventHandlers, createSplitProps, getInitials, isDeepEqual, isNotNullish, mergeBooleansAnd, mergeBooleansOr, sleep, toPascalCase };
+export { composeEventHandlers, createSplitProps, getHighlightChunks, getInitials, isDeepEqual, isNotNullish, mergeBooleansAnd, mergeBooleansOr, sleep, toPascalCase };

package/dist/utils/get-highlight-chunks.d.ts

@@ -0,0 +1,38 @@
+//#region src/utils/get-highlight-chunks.d.ts
+/**
+ * Trecho de um texto: `match` diz se ele casou com a busca.
+ */
+export type HighlightChunk = {
+  text: string;
+  match: boolean;
+};
+export type GetHighlightChunksOptions = {
+  /** Texto original, que é fatiado em trechos. */
+  text: string;
+  /** Um termo ou uma lista de termos. Cada um é buscado inteiro, como um trecho contínuo. */
+  query: string | readonly string[];
+};
+/**
+ * Divide o texto em trechos que casam ou não com a busca, para destacar os que casam.
+ *
+ * A regra é a do filtro do `Command` e do `useFilter` do Base UI: a busca inteira é um trecho
+ * contínuo (não é quebrada em palavras), sem diferenciar acento nem caixa. Os trechos saem do texto
+ * original, com o acento e a caixa que ele tem: `comissao` em `Comissão de vendas` marca
+ * `Comissão`. Comparar o texto cru marcaria nada, e normalizar o texto antes de fatiar devolveria
+ * o texto sem acento.
+ *
+ * Com uma lista, as ocorrências de todos os termos são juntas, e as que se sobrepõem ou encostam
+ * viram um trecho só. Busca vazia (ou só espaços) devolve o texto inteiro, sem destaque. Não há
+ * trecho vazio, e trechos vizinhos nunca têm o mesmo `match`. O formato é o do
+ * `@zag-js/highlight-word`.
+ *
+ * @example
+ * getHighlightChunks({ text: 'Comissão de vendas', query: 'comissao' })
+ * // [{ text: 'Comissão', match: true }, { text: ' de vendas', match: false }]
+ */
+export declare const getHighlightChunks: (options: GetHighlightChunksOptions) => {
+  text: string;
+  match: boolean;
+}[];
+//#endregion
+//# sourceMappingURL=get-highlight-chunks.d.ts.map

package/dist/utils/get-highlight-chunks.js

@@ -0,0 +1,107 @@
+//#region src/utils/get-highlight-chunks.ts
+const COMBINING_MARKS = /\p{M}/gu;
+const normalizeCharacter = (character) => character.normalize("NFD").replace(COMBINING_MARKS, "").toLocaleLowerCase("pt-BR");
+/**
+* Normaliza o texto caractere a caractere e guarda, para cada posição do texto normalizado, onde o
+* caractere de origem começa e termina no texto original.
+*/
+const normalizeWithMap = (text) => {
+	const starts = [];
+	const ends = [];
+	let normalized = "";
+	let index = 0;
+	for (const character of text) {
+		const end = index + character.length;
+		const normalizedCharacter = normalizeCharacter(character);
+		if (normalizedCharacter === "") {
+			const previousStart = starts.at(-1);
+			for (let position = ends.length - 1; position >= 0; position -= 1) {
+				if (starts[position] !== previousStart) break;
+				ends[position] = end;
+			}
+		} else {
+			/** Uma entrada por unidade UTF-16, porque o `indexOf` devolve posições assim. */
+			starts.push(...new Array(normalizedCharacter.length).fill(index));
+			ends.push(...new Array(normalizedCharacter.length).fill(end));
+			normalized += normalizedCharacter;
+		}
+		index = end;
+	}
+	return {
+		normalized,
+		starts,
+		ends
+	};
+};
+const normalizeQuery = (term) => Array.from(term.trim(), normalizeCharacter).join("");
+/**
+* Divide o texto em trechos que casam ou não com a busca, para destacar os que casam.
+*
+* A regra é a do filtro do `Command` e do `useFilter` do Base UI: a busca inteira é um trecho
+* contínuo (não é quebrada em palavras), sem diferenciar acento nem caixa. Os trechos saem do texto
+* original, com o acento e a caixa que ele tem: `comissao` em `Comissão de vendas` marca
+* `Comissão`. Comparar o texto cru marcaria nada, e normalizar o texto antes de fatiar devolveria
+* o texto sem acento.
+*
+* Com uma lista, as ocorrências de todos os termos são juntas, e as que se sobrepõem ou encostam
+* viram um trecho só. Busca vazia (ou só espaços) devolve o texto inteiro, sem destaque. Não há
+* trecho vazio, e trechos vizinhos nunca têm o mesmo `match`. O formato é o do
+* `@zag-js/highlight-word`.
+*
+* @example
+* getHighlightChunks({ text: 'Comissão de vendas', query: 'comissao' })
+* // [{ text: 'Comissão', match: true }, { text: ' de vendas', match: false }]
+*/
+const getHighlightChunks = (options) => {
+	const { text, query } = options;
+	const terms = (typeof query === "string" ? [query] : query).map(normalizeQuery).filter((term) => term !== "");
+	if (text === "" || terms.length === 0) return text === "" ? [] : [{
+		text,
+		match: false
+	}];
+	const { normalized, starts, ends } = normalizeWithMap(text);
+	const ranges = [];
+	for (const term of terms) {
+		let from = 0;
+		while (from <= normalized.length - term.length) {
+			const found = normalized.indexOf(term, from);
+			if (found === -1) break;
+			const start = starts[found];
+			const end = ends[found + term.length - 1];
+			if (start !== void 0 && end !== void 0) ranges.push({
+				start,
+				end
+			});
+			from = found + term.length;
+		}
+	}
+	ranges.sort((a, b) => a.start - b.start || a.end - b.end);
+	const merged = [];
+	for (const range of ranges) {
+		const last = merged.at(-1);
+		if (last !== void 0 && range.start <= last.end) last.end = Math.max(last.end, range.end);
+		else merged.push({ ...range });
+	}
+	const chunks = [];
+	let cursor = 0;
+	for (const range of merged) {
+		if (range.start > cursor) chunks.push({
+			text: text.slice(cursor, range.start),
+			match: false
+		});
+		chunks.push({
+			text: text.slice(range.start, range.end),
+			match: true
+		});
+		cursor = range.end;
+	}
+	if (cursor < text.length) chunks.push({
+		text: text.slice(cursor),
+		match: false
+	});
+	return chunks;
+};
+//#endregion
+export { getHighlightChunks };
+
+//# sourceMappingURL=get-highlight-chunks.js.map

package/dist/utils/get-highlight-chunks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-highlight-chunks.js","names":[],"sources":["../../src/utils/get-highlight-chunks.ts"],"sourcesContent":["/**\n * Trecho de um texto: `match` diz se ele casou com a busca.\n */\nexport type HighlightChunk = {\n  text: string;\n  match: boolean;\n};\n\nexport type GetHighlightChunksOptions = {\n  /** Texto original, que é fatiado em trechos. */\n  text: string;\n  /** Um termo ou uma lista de termos. Cada um é buscado inteiro, como um trecho contínuo. */\n  query: string | readonly string[];\n};\n\ntype Range = { start: number; end: number };\n\nconst COMBINING_MARKS = /\\p{M}/gu;\n\nconst normalizeCharacter = (character: string) =>\n  character\n    .normalize('NFD')\n    .replace(COMBINING_MARKS, '')\n    .toLocaleLowerCase('pt-BR');\n\n/**\n * Normaliza o texto caractere a caractere e guarda, para cada posição do texto normalizado, onde o\n * caractere de origem começa e termina no texto original.\n */\nconst normalizeWithMap = (text: string) => {\n  const starts: number[] = [];\n  const ends: number[] = [];\n  let normalized = '';\n  let index = 0;\n\n  for (const character of text) {\n    const end = index + character.length;\n    const normalizedCharacter = normalizeCharacter(character);\n\n    if (normalizedCharacter === '') {\n      // Marca combinante solta (texto em NFD): gruda no caractere anterior.\n      const previousStart = starts.at(-1);\n\n      for (let position = ends.length - 1; position >= 0; position -= 1) {\n        if (starts[position] !== previousStart) {\n          break;\n        }\n\n        ends[position] = end;\n      }\n    } else {\n      /** Uma entrada por unidade UTF-16, porque o `indexOf` devolve posições assim. */\n      starts.push(...new Array<number>(normalizedCharacter.length).fill(index));\n      ends.push(...new Array<number>(normalizedCharacter.length).fill(end));\n      normalized += normalizedCharacter;\n    }\n\n    index = end;\n  }\n\n  return { normalized, starts, ends };\n};\n\nconst normalizeQuery = (term: string) =>\n  Array.from(term.trim(), normalizeCharacter).join('');\n\n/**\n * Divide o texto em trechos que casam ou não com a busca, para destacar os que casam.\n *\n * A regra é a do filtro do `Command` e do `useFilter` do Base UI: a busca inteira é um trecho\n * contínuo (não é quebrada em palavras), sem diferenciar acento nem caixa. Os trechos saem do texto\n * original, com o acento e a caixa que ele tem: `comissao` em `Comissão de vendas` marca\n * `Comissão`. Comparar o texto cru marcaria nada, e normalizar o texto antes de fatiar devolveria\n * o texto sem acento.\n *\n * Com uma lista, as ocorrências de todos os termos são juntas, e as que se sobrepõem ou encostam\n * viram um trecho só. Busca vazia (ou só espaços) devolve o texto inteiro, sem destaque. Não há\n * trecho vazio, e trechos vizinhos nunca têm o mesmo `match`. O formato é o do\n * `@zag-js/highlight-word`.\n *\n * @example\n * getHighlightChunks({ text: 'Comissão de vendas', query: 'comissao' })\n * // [{ text: 'Comissão', match: true }, { text: ' de vendas', match: false }]\n */\nexport const getHighlightChunks = (options: GetHighlightChunksOptions) => {\n  const { text, query } = options;\n\n  const terms = (typeof query === 'string' ? [query] : query)\n    .map(normalizeQuery)\n    .filter((term) => term !== '');\n\n  if (text === '' || terms.length === 0) {\n    return text === '' ? [] : [{ text, match: false }];\n  }\n\n  const { normalized, starts, ends } = normalizeWithMap(text);\n\n  const ranges: Range[] = [];\n\n  for (const term of terms) {\n    let from = 0;\n\n    while (from <= normalized.length - term.length) {\n      const found = normalized.indexOf(term, from);\n\n      if (found === -1) {\n        break;\n      }\n\n      const start = starts[found];\n      const end = ends[found + term.length - 1];\n\n      if (start !== undefined && end !== undefined) {\n        ranges.push({ start, end });\n      }\n\n      from = found + term.length;\n    }\n  }\n\n  ranges.sort((a, b) => a.start - b.start || a.end - b.end);\n\n  const merged: Range[] = [];\n\n  for (const range of ranges) {\n    const last = merged.at(-1);\n\n    if (last !== undefined && range.start <= last.end) {\n      last.end = Math.max(last.end, range.end);\n    } else {\n      merged.push({ ...range });\n    }\n  }\n\n  const chunks: HighlightChunk[] = [];\n  let cursor = 0;\n\n  for (const range of merged) {\n    if (range.start > cursor) {\n      chunks.push({ text: text.slice(cursor, range.start), match: false });\n    }\n\n    chunks.push({ text: text.slice(range.start, range.end), match: true });\n    cursor = range.end;\n  }\n\n  if (cursor < text.length) {\n    chunks.push({ text: text.slice(cursor), match: false });\n  }\n\n  return chunks;\n};\n"],"mappings":";AAiBA,MAAM,kBAAkB;AAExB,MAAM,sBAAsB,cAC1B,UACG,UAAU,KAAK,CAAC,CAChB,QAAQ,iBAAiB,EAAE,CAAC,CAC5B,kBAAkB,OAAO;;;;;AAM9B,MAAM,oBAAoB,SAAiB;CACzC,MAAM,SAAmB,CAAC;CAC1B,MAAM,OAAiB,CAAC;CACxB,IAAI,aAAa;CACjB,IAAI,QAAQ;CAEZ,KAAK,MAAM,aAAa,MAAM;EAC5B,MAAM,MAAM,QAAQ,UAAU;EAC9B,MAAM,sBAAsB,mBAAmB,SAAS;EAExD,IAAI,wBAAwB,IAAI;GAE9B,MAAM,gBAAgB,OAAO,GAAG,EAAE;GAElC,KAAK,IAAI,WAAW,KAAK,SAAS,GAAG,YAAY,GAAG,YAAY,GAAG;IACjE,IAAI,OAAO,cAAc,eACvB;IAGF,KAAK,YAAY;GACnB;EACF,OAAO;;GAEL,OAAO,KAAK,GAAG,IAAI,MAAc,oBAAoB,MAAM,CAAC,CAAC,KAAK,KAAK,CAAC;GACxE,KAAK,KAAK,GAAG,IAAI,MAAc,oBAAoB,MAAM,CAAC,CAAC,KAAK,GAAG,CAAC;GACpE,cAAc;EAChB;EAEA,QAAQ;CACV;CAEA,OAAO;EAAE;EAAY;EAAQ;CAAK;AACpC;AAEA,MAAM,kBAAkB,SACtB,MAAM,KAAK,KAAK,KAAK,GAAG,kBAAkB,CAAC,CAAC,KAAK,EAAE;;;;;;;;;;;;;;;;;;;AAoBrD,MAAa,sBAAsB,YAAuC;CACxE,MAAM,EAAE,MAAM,UAAU;CAExB,MAAM,SAAS,OAAO,UAAU,WAAW,CAAC,KAAK,IAAI,MAAA,CAClD,IAAI,cAAc,CAAC,CACnB,QAAQ,SAAS,SAAS,EAAE;CAE/B,IAAI,SAAS,MAAM,MAAM,WAAW,GAClC,OAAO,SAAS,KAAK,CAAC,IAAI,CAAC;EAAE;EAAM,OAAO;CAAM,CAAC;CAGnD,MAAM,EAAE,YAAY,QAAQ,SAAS,iBAAiB,IAAI;CAE1D,MAAM,SAAkB,CAAC;CAEzB,KAAK,MAAM,QAAQ,OAAO;EACxB,IAAI,OAAO;EAEX,OAAO,QAAQ,WAAW,SAAS,KAAK,QAAQ;GAC9C,MAAM,QAAQ,WAAW,QAAQ,MAAM,IAAI;GAE3C,IAAI,UAAU,IACZ;GAGF,MAAM,QAAQ,OAAO;GACrB,MAAM,MAAM,KAAK,QAAQ,KAAK,SAAS;GAEvC,IAAI,UAAU,KAAA,KAAa,QAAQ,KAAA,GACjC,OAAO,KAAK;IAAE;IAAO;GAAI,CAAC;GAG5B,OAAO,QAAQ,KAAK;EACtB;CACF;CAEA,OAAO,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG;CAExD,MAAM,SAAkB,CAAC;CAEzB,KAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,OAAO,OAAO,GAAG,EAAE;EAEzB,IAAI,SAAS,KAAA,KAAa,MAAM,SAAS,KAAK,KAC5C,KAAK,MAAM,KAAK,IAAI,KAAK,KAAK,MAAM,GAAG;OAEvC,OAAO,KAAK,EAAE,GAAG,MAAM,CAAC;CAE5B;CAEA,MAAM,SAA2B,CAAC;CAClC,IAAI,SAAS;CAEb,KAAK,MAAM,SAAS,QAAQ;EAC1B,IAAI,MAAM,QAAQ,QAChB,OAAO,KAAK;GAAE,MAAM,KAAK,MAAM,QAAQ,MAAM,KAAK;GAAG,OAAO;EAAM,CAAC;EAGrE,OAAO,KAAK;GAAE,MAAM,KAAK,MAAM,MAAM,OAAO,MAAM,GAAG;GAAG,OAAO;EAAK,CAAC;EACrE,SAAS,MAAM;CACjB;CAEA,IAAI,SAAS,KAAK,QAChB,OAAO,KAAK;EAAE,MAAM,KAAK,MAAM,MAAM;EAAG,OAAO;CAAM,CAAC;CAGxD,OAAO;AACT"}

package/dist/utils/index.d.ts

@@ -1,8 +1,9 @@
 import { composeEventHandlers } from "./compose-event-handlers.js";
 import { createSplitProps } from "./create-split-props.js";
+import { GetHighlightChunksOptions, HighlightChunk, getHighlightChunks } from "./get-highlight-chunks.js";
 import { getInitials } from "./get-initials.js";
 import { isDeepEqual } from "./is-deep-equal.js";
 import { isNotNullish } from "./is-not-nullish.js";
 import { mergeBooleansAnd, mergeBooleansOr } from "./merge-booleans.js";
 import { PascalCase, toPascalCase } from "./to-pascal-case.js";
-export { PascalCase, composeEventHandlers, createSplitProps, getInitials, isDeepEqual, isNotNullish, mergeBooleansAnd, mergeBooleansOr, toPascalCase };
+export { GetHighlightChunksOptions, HighlightChunk, PascalCase, composeEventHandlers, createSplitProps, getHighlightChunks, getInitials, isDeepEqual, isNotNullish, mergeBooleansAnd, mergeBooleansOr, toPascalCase };

package/dist/utils/index.js

@@ -1,8 +1,9 @@
 import { composeEventHandlers } from "./compose-event-handlers.js";
 import { createSplitProps } from "./create-split-props.js";
+import { getHighlightChunks } from "./get-highlight-chunks.js";
 import { getInitials } from "./get-initials.js";
 import { isDeepEqual } from "./is-deep-equal.js";
 import { isNotNullish } from "./is-not-nullish.js";
 import { mergeBooleansAnd, mergeBooleansOr } from "./merge-booleans.js";
 import { toPascalCase } from "./to-pascal-case.js";
-export { composeEventHandlers, createSplitProps, getInitials, isDeepEqual, isNotNullish, mergeBooleansAnd, mergeBooleansOr, toPascalCase };
+export { composeEventHandlers, createSplitProps, getHighlightChunks, getInitials, isDeepEqual, isNotNullish, mergeBooleansAnd, mergeBooleansOr, toPascalCase };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lucasbernardosn/ts-utils",
-  "version": "0.3.0",
-  "description": "TypeScript utilities and type helpers, framework-agnostic.",
+  "version": "0.5.0",
+  "description": "Funções e helpers de tipo em TypeScript puro, sem React e sem dependências.",
   "type": "module",
   "exports": {
     ".": {
@@ -22,6 +22,11 @@
     "dist"
   ],
   "sideEffects": false,
+  "keywords": [
+    "typescript",
+    "utils",
+    "type-helpers"
+  ],
   "license": "MIT",
   "publishConfig": {
     "access": "public"