@apollion-dsi/core 5.3.0 → 5.5.0

package/lib/utils/mask.d.ts

@@ -1,19 +1,19 @@
 /**
- * Mapa de posição → caractere literal de uma máscara.
+ * Map of position → literal character of a mask.
  *
- * As chaves são índices da string final de saída onde o caractere literal
- * (`.`, `-`, `/`, etc.) deve ser inserido antes do próximo dígito.
+ * The keys are indices of the final output string where the literal
+ * character (`.`, `-`, `/`, etc.) must be inserted before the next digit.
  */
 type MaskChars = {
     [index: number]: string;
 };
 /**
- * Cria uma função que aplica uma máscara a uma string de dígitos.
+ * Creates a function that applies a mask to a digit string.
  *
- * A função retornada filtra dígitos do input, percorre na ordem aplicando os
- * literais armazenados em `maskChars` e trunca em `maxLength`. É a forma
- * mais barata de mascarar (sem regex), usada nas máscaras de Input da
- * Apollion.
+ * The returned function filters digits from the input, walks them in order
+ * applying the literals stored in `maskChars` and truncates at `maxLength`.
+ * It is the cheapest way to mask (no regex), used by Apollion's Input
+ * masks.
  *
  * @example
  * ```ts
@@ -23,11 +23,11 @@ type MaskChars = {
  */
 export declare const maskContructor: (maskChars: MaskChars, maxLength: number) => (numberToBeFormated: string) => string;
 /**
- * Compila uma string-template em uma função de máscara pronta para uso.
+ * Compiles a template string into a ready-to-use mask function.
  *
- * Convenção: `0` é placeholder de dígito; qualquer outro caractere é literal.
- * O resultado é equivalente a `maskContructor` mas dispensa montar o mapa
- * manualmente.
+ * Convention: `0` is a digit placeholder; any other character is a literal.
+ * The result is equivalent to `maskContructor` but skips assembling the map
+ * manually.
  *
  * @example
  * ```ts

package/lib/utils/object.d.ts

@@ -1,16 +1,17 @@
 /**
- * União dos tipos dos valores de um objeto.
+ * Union of an object's value types.
  *
- * Equivalente ao operador `T[keyof T]` — fica num alias por legibilidade nos
- * tipos de helpers que iteram sobre objetos.
+ * Equivalent to the `T[keyof T]` operator — kept as an alias for readability
+ * in the types of helpers that iterate over objects.
  */
 export type ValueOf<T> = T[keyof T];
 /**
- * Aplica uma função em cada chave do objeto, preservando as chaves no
- * resultado.
+ * Applies a function to each key of the object, preserving the keys in the
+ * result.
  *
- * Análogo ao `R.mapObjIndexed` do Ramda — útil para transformar valores de
- * um dicionário (ex.: tokens de cor) sem reescrever o reducer toda vez.
+ * Analogous to Ramda's `R.mapObjIndexed` — useful for transforming
+ * dictionary values (e.g. color tokens) without rewriting the reducer every
+ * time.
  *
  * @example
  * ```ts
@@ -22,11 +23,11 @@ export declare function mapObjIndexed<T, V>(fn: (val: ValueOf<T>, key?: string,
     [key: string]: V;
 };
 /**
- * Acessa um valor aninhado por path (string com pontos ou array de chaves).
+ * Accesses a nested value by path (dot-separated string or array of keys).
  *
- * Se o resultado final for um objeto e `optionalKey` for informado, devolve
- * `result[optionalKey]` em vez do próprio objeto — açúcar para acessar
- * valores como `theme.colors.primary.main` em uma só chamada.
+ * If the final result is an object and `optionalKey` is provided, it returns
+ * `result[optionalKey]` instead of the object itself — sugar for accessing
+ * values like `theme.colors.primary.main` in a single call.
  *
  * @example
  * ```ts
@@ -36,26 +37,27 @@ export declare function mapObjIndexed<T, V>(fn: (val: ValueOf<T>, key?: string,
  */
 export declare function getValue(key: string | string[], obj: any, optionalKey?: string): any;
 /**
- * Memoiza uma função por **todos** os argumentos.
+ * Memoizes a function by **all** of its arguments.
  *
- * Antes a chave era só `args[0]`, e isso não era uma limitação teórica:
+ * Previously the key was only `args[0]`, and that was not a theoretical
+ * limitation:
  *
- * - `getContrastColor(color, colorbase?)` — chamadas com o mesmo `color` e
- *   `colorbase` diferentes devolviam o resultado da primeira. Contaminação
- *   silenciosa no sistema de contraste.
- * - `inputSizeProps(size, theme)` — trocar de tema não invalidava nada.
- * - `readableColor(color, background, minRatio)` ficou **fora** do cache de
- *   propósito (ver o comentário em `Colors.helpers.ts`), justamente porque o
- *   resultado depende do `background`. Era o memoize que estava errado, não a
- *   decisão de cachear — e é o caminho quente: até 25 iterações de
- *   `parse`+`formatHex`+`wcagContrast` por elemento renderizado.
+ * - `getContrastColor(color, colorbase?)` — calls with the same `color` and
+ *   different `colorbase` returned the first call's result. Silent
+ *   contamination in the contrast system.
+ * - `inputSizeProps(size, theme)` — switching themes invalidated nothing.
+ * - `readableColor(color, background, minRatio)` was left **out** of the
+ *   cache on purpose (see the comment in `Colors.helpers.ts`), precisely
+ *   because the result depends on the `background`. The memoize was what was
+ *   wrong, not the decision to cache — and it is the hot path: up to 25
+ *   iterations of `parse`+`formatHex`+`wcagContrast` per rendered element.
  *
- * Primitivos entram na chave por valor (com o tipo junto, para `1` não colidir
- * com `'1'`); objetos entram por identidade via `WeakMap`.
+ * Primitives enter the key by value (with the type attached, so `1` does not
+ * collide with `'1'`); objects enter by identity via `WeakMap`.
  *
- * Usa `Map`, não objeto literal: a versão anterior testava
- * `cache[key] === undefined`, então uma função que retornasse `undefined`
- * nunca era cacheada — e chaves como `constructor` colidiam com o protótipo.
+ * Uses `Map`, not an object literal: the previous version tested
+ * `cache[key] === undefined`, so a function returning `undefined` was never
+ * cached — and keys like `constructor` collided with the prototype.
  *
  * @example
  * ```ts

package/lib/utils/typeUtils.d.ts

@@ -1,19 +1,20 @@
 /**
- * Helper interno: gera um objeto onde toda chave de `T` que NÃO está em `U`
- * é opcional e `never`.
+ * Internal helper: generates an object where every key of `T` that is NOT
+ * in `U` is optional and `never`.
  *
- * É a peça que torna o `XOR` funcional — combinando duas instâncias de
- * `Without` é possível modelar "ou um, ou o outro, nunca os dois".
+ * It's the piece that makes `XOR` work — combining two instances of
+ * `Without` makes it possible to model "either one, or the other, never both".
  */
 type Without<T, U> = {
     [P in Exclude<keyof T, keyof U>]?: never;
 };
 /**
- * Tipo "exclusivo ou": exige que o consumidor forneça as props de `T` OU as
- * props de `U`, nunca uma mistura das duas.
+ * "Exclusive or" type: requires the consumer to provide the props of `T`
+ * OR the props of `U`, never a mix of both.
  *
- * Útil para componentes que aceitam duas APIs incompatíveis (ex.: um campo
- * "controlled" via `value`+`onChange` ou "uncontrolled" via `defaultValue`).
+ * Useful for components that accept two incompatible APIs (e.g., a
+ * "controlled" field via `value`+`onChange` or "uncontrolled" via
+ * `defaultValue`).
  *
  * @example
  * ```ts
@@ -23,16 +24,16 @@ type Without<T, U> = {
  *
  * const a: Props = { value: 'x', onChange: () => {} };   // ok
  * const b: Props = { defaultValue: 'x' };                // ok
- * const c: Props = { value: 'x', defaultValue: 'x' };    // erro
+ * const c: Props = { value: 'x', defaultValue: 'x' };    // error
  * ```
  */
 export type XOR<T, U> = T | U extends any ? (Without<T, U> & U) | (Without<U, T> & T) : T | U;
 /**
- * Helper interno: filtra apenas as chaves literais ("conhecidas") de um tipo,
- * removendo chaves indexadas (`[k: string]: ...` ou `[k: number]: ...`).
+ * Internal helper: filters only the literal ("known") keys of a type,
+ * removing indexed keys (`[k: string]: ...` or `[k: number]: ...`).
  *
- * Necessário porque `keyof T` em TS inclui index signatures, o que polui
- * `Pick<T, keyof T>` quando se quer só as propriedades nomeadas.
+ * Necessary because `keyof T` in TS includes index signatures, which
+ * pollutes `Pick<T, keyof T>` when you only want the named properties.
  */
 type KnownKeys<T> = {
     [K in keyof T]: string extends K ? never : number extends K ? never : K;
@@ -40,10 +41,11 @@ type KnownKeys<T> = {
     [_ in keyof T]: infer U;
 } ? U : never;
 /**
- * Pega apenas as propriedades nomeadas (não-índice) de um objeto.
+ * Picks only the named (non-index) properties of an object.
  *
- * Útil para inferir o "shape conhecido" de tipos como `React.CSSProperties`
- * ou `JSX.IntrinsicElements[...]` que carregam index signatures escondidos.
+ * Useful for inferring the "known shape" of types like
+ * `React.CSSProperties` or `JSX.IntrinsicElements[...]` that carry hidden
+ * index signatures.
  */
 export type RequiredOnly<T extends Record<any, any>> = Pick<T, KnownKeys<T>>;
 export {};

package/lib/utils/utils.d.ts

@@ -1,76 +1,76 @@
 /**
- * Hook que emite um aviso de depreciação UMA única vez por nome de API.
+ * Hook that emits a deprecation warning ONCE per API name.
  *
- * Usa uma flag em `$window` para garantir que cada `name` só dispare um
- * `LOGGER.warn` por sessão do navegador, mesmo se o componente desmontar e
- * remontar várias vezes. Só roda em desenvolvimento.
+ * Uses a flag on `$window` to guarantee that each `name` only triggers one
+ * `LOGGER.warn` per browser session, even if the component unmounts and
+ * remounts several times. Runs in development only.
  *
  * @example
  * ```tsx
  * function OldComponent() {
- *   useDeprecated('OldComponent', 'Use NewComponent em vez disso.');
+ *   useDeprecated('OldComponent', 'Use NewComponent instead.');
  *   return <NewComponent />;
  * }
  * ```
  */
 export declare function useDeprecated(name: string, message?: string): void;
 /**
- * Converte um valor numérico para string em pixels; passa strings adiante.
+ * Converts a numeric value to a pixel string; passes strings through.
  *
- * Retorna `0` quando o valor é falsy — comum em handlers que aceitam
+ * Returns `0` when the value is falsy — common in handlers that accept
  * `number | string | undefined`.
  */
 export declare function toPixel(prop?: number | string): string | 0;
 /**
- * Garante que o valor seja um array.
+ * Guarantees the value is an array.
  *
- * Se já é array, retorna; senão, envolve em um array de 1 elemento. Útil
- * para normalizar props que aceitam "uma coisa OU várias coisas".
+ * If it already is one, returns it; otherwise wraps it in a 1-element array.
+ * Useful for normalizing props that accept "one thing OR many things".
  */
 export declare function toArray(obj: any): any[];
-/** Type guard: o valor é uma função invocável? */
+/** Type guard: is the value a callable function? */
 export declare function isFunction(fn: any): fn is Function;
-/** Type guard: o valor é um objeto não-nulo (inclui arrays)? */
+/** Type guard: is the value a non-null object (arrays included)? */
 export declare function isObject(obj: any): boolean;
-/** Combina `isObject` + checagem de chaves para detectar `{}`. */
+/** Combines `isObject` + key check to detect `{}`. */
 export declare function isObjectEmpty(obj: any): boolean;
 /**
- * Type guard: o valor é uma string?
+ * Type guard: is the value a string?
  *
- * Usa o truque `Object.prototype.toString.call(...)` para também aceitar
- * `String` (objeto envoltório), embora seja caso raríssimo.
+ * Uses the `Object.prototype.toString.call(...)` trick to also accept
+ * `String` (wrapper object), although that is an extremely rare case.
  */
 export declare function isString(obj: any): boolean;
-/** Verifica se o valor é um array vazio. */
+/** Checks whether the value is an empty array. */
 export declare function isEmptyArray(value?: any): boolean;
 /**
- * Heurística para detectar um `SyntheticEvent` de input.
+ * Heuristic to detect an input `SyntheticEvent`.
  *
- * Olha apenas para o `target` (objeto não-nulo) — é o suficiente para
- * distinguir, em handlers genéricos, se chegou um evento ou um valor cru.
+ * Looks only at the `target` (non-null object) — enough to distinguish, in
+ * generic handlers, whether an event or a raw value arrived.
  */
 export declare function isInputEvent(value: any): boolean;
 /**
- * Faz parse de uma string HTML usando `DOMParser` e devolve a coleção do
- * elemento alvo.
+ * Parses an HTML string using `DOMParser` and returns the collection of the
+ * target element.
  *
- * Só funciona no browser — não use em SSR.
+ * Browser-only — do not use in SSR.
  */
 export declare function parseHtmlString(domString: string, element: string): HTMLCollection;
 /**
- * Converte uma `HTMLCollection` em árvore React equivalente.
+ * Converts an `HTMLCollection` into the equivalent React tree.
  *
- * Itera recursivamente, copia atributos (exceto `class`/`style`, descartados
- * para evitar conflito com o styling controlado da Apollion) e respeita
- * conteúdo de texto. Devolve um único elemento se houver apenas um filho.
+ * Iterates recursively, copies attributes (except `class`/`style`, discarded
+ * to avoid conflicts with Apollion's controlled styling) and respects text
+ * content. Returns a single element when there is only one child.
  */
 export declare function domToReact(nodes: HTMLCollection): React.ReactNode;
 /**
- * Achata recursivamente um conjunto variádico de argumentos (arrays
- * aninhados em qualquer profundidade) em um único array.
+ * Recursively flattens a variadic argument set (arrays nested at any depth)
+ * into a single array.
  *
- * Equivalente a um `Array.prototype.flat(Infinity)` aplicado sobre
- * `[...args]`, mas com a vantagem de aceitar argumentos soltos.
+ * Equivalent to `Array.prototype.flat(Infinity)` applied over `[...args]`,
+ * but with the advantage of accepting loose arguments.
  *
  * @example
  * ```ts

package/lib/utils/window.d.ts

@@ -1,22 +1,22 @@
 /**
- * `true` quando o módulo está rodando num ambiente com `document` (browser ou
- * jsdom). Usado como guarda em SSR para evitar erros do tipo
+ * `true` when the module is running in an environment with `document`
+ * (browser or jsdom). Used as an SSR guard to avoid errors like
  * "`document is not defined`".
  */
 export declare const canuseDom: boolean;
 /**
- * Referência ao `window` global quando disponível; `undefined` em SSR.
+ * Reference to the global `window` when available; `undefined` in SSR.
  *
- * É calculado uma vez no carregamento do módulo — preferimos esta referência
- * a `globalThis.window` porque mantém um único ponto de checagem de
- * disponibilidade e ajuda na narrowing dos consumidores.
+ * Computed once at module load — we prefer this reference over
+ * `globalThis.window` because it keeps a single point of availability
+ * checking and helps narrowing for consumers.
  */
 export declare const $window: Window & typeof globalThis;
 /**
- * Referência ao `document.body` quando disponível; `undefined` em SSR.
+ * Reference to `document.body` when available; `undefined` in SSR.
  *
- * O cast para `HTMLElement` simplifica o uso em chamadas como `appendChild`,
- * com a contrapartida de exigir do consumidor checar `canuseDom` antes em
- * código que rode no servidor.
+ * The cast to `HTMLElement` simplifies use in calls like `appendChild`, at
+ * the cost of requiring the consumer to check `canuseDom` first in code
+ * that runs on the server.
  */
 export declare const $documentBody: HTMLElement;

package/lib/vendors/Culori/component.d.ts

@@ -1,28 +1,28 @@
 /**
- * Superfície de manipulação perceptual de cor do DS.
+ * The DS's perceptual color manipulation surface.
  *
- * Até a F6b (pente fino v5.0.0) este arquivo era um re-export tipado de
- * `culori`. Agora re-exporta o **motor próprio** (`./engine.ts`): um porte
- * bit-exato do subconjunto de culori@4.0.2 que o DS realmente usa —
- * ~44 KB de dependência a menos em todo subpath que toca cor.
+ * Until F6b (v5.0.0 fine-tooth-comb audit) this file was a typed re-export of
+ * `culori`. It now re-exports the **own color engine** (`./engine.ts`): a
+ * bit-exact port of the culori@4.0.2 subset the DS actually uses —
+ * ~44 KB less dependency in every subpath that touches color.
  *
- * A superfície pública é IDÊNTICA à anterior (mesmos nomes, mesmas
- * semânticas, mesmos valores de saída):
+ * The public surface is IDENTICAL to the previous one (same names, same
+ * semantics, same output values):
  * - `parse(input)` — parse hex/CSS color string → color object
  * - `formatHex(color)` — color object → 6-digit hex string
  * - `interpolate(colors, mode)` — perceptual lerp interpolator factory
- *   (mode `'oklch'` para palette generation; `fixupHueShorter` embutido)
+ *   (mode `'oklch'` for palette generation; `fixupHueShorter` built in)
  * - `wcagContrast(a, b)` / `wcagLuminance(c)` — WCAG 2.x
  * - `converter(mode)` — color space converter factory
  *
- * Duas provas mecânicas garantem a equivalência — ver `./parity.test.ts`
- * (snapshots gerados com o culori real) e `./parity.differential.test.ts`
- * (sweep denso contra o culori real, hoje devDependency).
+ * Two mechanical proofs guarantee the equivalence — see `./parity.test.ts`
+ * (snapshots generated with the real culori) and `./parity.differential.test.ts`
+ * (dense sweep against the real culori, now a devDependency).
  *
- * Voltar para o culori, se um dia for preciso, é reverter ESTE arquivo para
- * `export { ... } from 'culori'` e restaurar a dependency — um arquivo.
+ * Going back to culori, should it ever be needed, means reverting THIS file
+ * to `export { ... } from 'culori'` and restoring the dependency — one file.
  *
- * @see ./engine.ts (implementação + gap de parse documentado)
+ * @see ./engine.ts (implementation + documented parse gap)
  * @see ./README.md
  * @see ../../../docs/adr/ADR-016-motor-de-cor-proprio.md
  * @see ../../../docs/adr/ADR-006-v4-oklch-dimension-token-split.md §3.10 §6 S2

package/lib/vendors/Culori/engine.d.ts

@@ -1,41 +1,41 @@
 /**
- * Motor de cor próprio do DS — substitui a dependência de runtime `culori`.
+ * The DS's own color engine — replaces the `culori` runtime dependency.
  *
- * ## Por que existe (F6b / APOLLION-CULORI-FLOOR)
+ * ## Why it exists (F6b / APOLLION-CULORI-FLOOR)
  *
- * `culori` custava ~44 KB em todo subpath que toca cor — o piso de bundle
- * apontado no pente fino v5.0.0. A superfície realmente usada pelo DS é
- * mínima: `parse`, `converter('rgb'|'oklch'|'lrgb')`, `interpolate(_, 'oklch')`,
- * `formatHex`, `wcagContrast`/`wcagLuminance`. Este arquivo porta EXATAMENTE
- * esse subconjunto.
+ * `culori` cost ~44 KB in every subpath that touches color — the bundle floor
+ * flagged in the v5.0.0 fine-tooth-comb audit. The surface the DS actually
+ * uses is minimal: `parse`, `converter('rgb'|'oklch'|'lrgb')`, `interpolate(_, 'oklch')`,
+ * `formatHex`, `wcagContrast`/`wcagLuminance`. This file ports EXACTLY
+ * that subset.
  *
- * ## Contrato de bit-exatidão
+ * ## Bit-exactness contract
  *
- * Isto é um **porte**, não uma reimplementação de cabeça: cada função replica
- * o algoritmo, as constantes e a ORDEM DAS OPERAÇÕES de ponto flutuante do
- * `culori@4.0.2` (os arquivos de origem estão anotados por função). Duas
- * provas mecânicas guardam o contrato:
+ * This is a **port**, not a from-scratch reimplementation: each function
+ * replicates the algorithm, the constants and the floating-point ORDER OF
+ * OPERATIONS of `culori@4.0.2` (the source files are annotated per function).
+ * Two mechanical proofs guard the contract:
  *
- * 1. `parity.test.ts` — snapshots gerados com o culori REAL antes do swap;
- *    esta implementação tem que reproduzi-los sem regenerar nada.
- * 2. `parity.differential.test.ts` — sweep denso comparando este motor com o
- *    culori real (devDependency) por igualdade estrita, incluindo -0 e
- *    canais `undefined`.
+ * 1. `parity.test.ts` — snapshots generated with the REAL culori before the
+ *    swap; this implementation must reproduce them without regenerating anything.
+ * 2. `parity.differential.test.ts` — dense sweep comparing this engine against
+ *    the real culori (devDependency) under strict equality, including -0 and
+ *    `undefined` channels.
  *
- * Por isso: NÃO "otimize" rotas de conversão (ex.: oklch→lrgb passa por rgb
- * de propósito, porque é a rota que o culori usa), NÃO troque a ordem de
- * somas, NÃO arredonde diferente.
+ * Therefore: do NOT "optimize" conversion routes (e.g. oklch→lrgb goes
+ * through rgb on purpose, because that is the route culori uses), do NOT
+ * reorder sums, do NOT round differently.
  *
- * ## Gap de parse (documentado, decisão consciente)
+ * ## Parse gap (documented, conscious decision)
  *
- * O culori parseia a sintaxe CSS Color 4 completa (`rgb(255 0 0 / 50%)`,
- * `oklch(…)`, `lab(…)`, `color(…)`) via um tokenizer de ~500 linhas. O DS
- * absorve apenas: hex 3/4/6/8, `rgb()/rgba()` legacy, `hsl()/hsla()` legacy,
- * cores nomeadas e `transparent` — todos os formatos que circulam em runtime
- * (o ciclo interno do DS é 100% hex). Sintaxe moderna → `undefined`, o mesmo
- * caminho de qualquer cor inválida, que todos os call sites já guardam.
+ * culori parses the full CSS Color 4 syntax (`rgb(255 0 0 / 50%)`,
+ * `oklch(…)`, `lab(…)`, `color(…)`) via a ~500-line tokenizer. The DS
+ * absorbs only: hex 3/4/6/8, legacy `rgb()/rgba()`, legacy `hsl()/hsla()`,
+ * named colors and `transparent` — all the formats that circulate at runtime
+ * (the DS's internal cycle is 100% hex). Modern syntax → `undefined`, the
+ * same path as any invalid color, which every call site already guards.
  *
- * ## Licença
+ * ## License
  *
  * Portions ported from culori v4.0.2 — MIT License, Copyright (c) 2018
  * Dan Burzo. https://github.com/Evercoder/culori
@@ -84,29 +84,29 @@ interface TargetByMode {
     oklch: Oklch;
 }
 /**
- * Parse de string CSS → color object. Origem: culori src/parse.js (a função
- * pública; os parsers modernos não foram portados — ver gap no cabeçalho).
+ * CSS string parse → color object. Source: culori src/parse.js (the public
+ * function; the modern parsers were not ported — see gap in the header).
  */
 export declare const parse: (color: unknown) => Color | undefined;
 /**
- * Fábrica de conversor de espaço de cor. Origem: culori src/converter.js.
- * Targets absorvidos: `rgb`, `lrgb`, `oklab`, `oklch` (o DS usa rgb/oklch
- * em runtime e lrgb via `wcagLuminance`).
+ * Color space converter factory. Source: culori src/converter.js.
+ * Absorbed targets: `rgb`, `lrgb`, `oklab`, `oklch` (the DS uses rgb/oklch
+ * at runtime and lrgb via `wcagLuminance`).
  */
 export declare const converter: <M extends TargetMode>(mode?: M) => (color: Color | string | undefined) => TargetByMode[M] | undefined;
-/** Color object (ou string) → hex 6 dígitos. Origem: culori formatHex. */
+/** Color object (or string) → 6-digit hex. Source: culori formatHex. */
 export declare const formatHex: (color: Color | string | undefined) => string | undefined;
-/** Luminância relativa WCAG 2.x. Lança TypeError em cor inválida (como o culori). */
+/** WCAG 2.x relative luminance. Throws TypeError on an invalid color (like culori). */
 export declare const wcagLuminance: (color: Color | string) => number;
-/** Razão de contraste WCAG 2.x. Origem: culori src/wcag.js `contrast`. */
+/** WCAG 2.x contrast ratio. Source: culori src/wcag.js `contrast`. */
 export declare const wcagContrast: (a: Color | string, b: Color | string) => number;
 type InterpolateMode = 'rgb' | 'oklab' | 'oklch';
 /**
- * Fábrica de interpolador perceptual. Origem: culori src/interpolate/interpolate.js.
+ * Perceptual interpolator factory. Source: culori src/interpolate/interpolate.js.
  *
- * Absorvido: array de stops de COR (string ou objeto) + modo. Positions
- * (`[color, 0.3]`), hints numéricos e easings NÃO foram absorvidos — o DS
- * nunca os usou; passar um stop assim lança em vez de degradar em silêncio.
+ * Absorbed: array of COLOR stops (string or object) + mode. Positions
+ * (`[color, 0.3]`), numeric hints and easings were NOT absorbed — the DS
+ * never used them; passing such a stop throws instead of degrading silently.
  */
 export declare const interpolate: (colors: ReadonlyArray<Color | string>, mode?: InterpolateMode) => ((t: number) => TargetByMode[Extract<InterpolateMode, TargetMode>] | Color);
 export {};

package/lib/vendors/Culori/interface.d.ts

@@ -1,8 +1,8 @@
 /**
- * Contrato ideal do DS sobre manipulação perceptual de cor.
+ * The DS's ideal contract for perceptual color manipulation.
  *
- * O motor opera em color objects (o modelo herdado do culori). Tipos
- * exportados para casos onde helpers internos precisam tipar:
+ * The engine operates on color objects (the model inherited from culori).
+ * Types exported for cases where internal helpers need typing:
  * - `Color` — generic color object union (RGB/HSL/OKLch/etc).
  * - `Oklch` — specific OKLch color shape (`{ mode: 'oklch', l, c, h }`).
  *
@@ -13,12 +13,12 @@ export type { Color, Hsl, Lrgb, Oklab, Oklch, Rgb } from './engine';
 /**
  * DS-owned helper signature: OKLch perceptual lerp wrapper.
  *
- * Migra de `Color(a).mix(b, t).hex()` (RGB lerp, color@5) para
+ * Migrates from `Color(a).mix(b, t).hex()` (RGB lerp, color@5) to
  * `interpolate([a, b], 'oklch')(t)` + `formatHex` (OKLch lerp, culori).
  *
- * Spike validation: branch `spike/culori-oklch-lerp-parity` confirmou
- * 0 unexpected regressions em 68 deltas. Greyscale ramp 19× mais uniforme
- * em OKLAB L space.
+ * Spike validation: branch `spike/culori-oklch-lerp-parity` confirmed
+ * 0 unexpected regressions across 68 deltas. Greyscale ramp 19× more uniform
+ * in OKLAB L space.
  *
  * @param a - hex string (e.g. `'#003750'`)
  * @param b - hex string

package/lib/vendors/Culori/named.d.ts

@@ -1,8 +1,8 @@
 /**
- * Tabela de cores nomeadas CSS — transcrição mecânica de
- * `culori@4.0.2/src/colors/named.js` (MIT © 2018 Dan Burzo), gerada por
- * script na F6b para eliminar risco de typo. 148 entradas.
+ * CSS named colors table — mechanical transcription of
+ * `culori@4.0.2/src/colors/named.js` (MIT © 2018 Dan Burzo), generated by
+ * script in F6b to eliminate typo risk. 148 entries.
  *
- * Vive num arquivo próprio para o motor (`engine.ts`) ficar legível.
+ * Lives in its own file so the engine (`engine.ts`) stays readable.
  */
 export declare const named: Record<string, number>;

package/lib/vendors/DateFns/component.d.ts

@@ -1,27 +1,28 @@
 /**
- * Re-export tipado da surface absorvida de `date-fns` v4.
+ * Typed re-export of the absorbed surface of `date-fns` v4.
  *
- * Surface absorvida pelo DS:
+ * Surface absorbed by the DS:
  *
  * Format/parse:
- * - `format`     — `Date → string` com pattern + locale. Usado em
- *   `form/InputDate` para `displayFormat`.
- * - `parse`      — `string → Date` com pattern + locale. Disponível para
- *   consumers que ingerem datas em formato não-ISO (ex.: vindo de API
- *   legado). Consumers importam direto do vendor; não há re-export DS-owned.
- * - `parseISO`   — `string → Date` apenas para ISO `yyyy-MM-dd[Thh:mm:ss]`.
- *   Faster path do `form/InputDate` (value interno é sempre ISO).
- * - `isValid`    — `Date → boolean`. Guarda runtime contra `Invalid Date`
- *   antes de formatar.
+ * - `format`     — `Date → string` with pattern + locale. Used in
+ *   `form/InputDate` for `displayFormat`.
+ * - `parse`      — `string → Date` with pattern + locale. Available for
+ *   consumers ingesting dates in non-ISO formats (e.g. coming from a
+ *   legacy API). Consumers import straight from the vendor; there is no
+ *   DS-owned re-export.
+ * - `parseISO`   — `string → Date` only for ISO `yyyy-MM-dd[Thh:mm:ss]`.
+ *   Faster path of `form/InputDate` (internal value is always ISO).
+ * - `isValid`    — `Date → boolean`. Runtime guard against `Invalid Date`
+ *   before formatting.
  *
  * Locales:
  * - `ptBR` — `elements/Calendar` (default), `form/InputDate` (default).
- * - `enUS` — Storybook locale demos + tests determinísticos
+ * - `enUS` — Storybook locale demos + deterministic tests
  *   (`aria-label` ICU-version-agnostic).
  *
- * `date-fns@4.x` é o sucessor de `date-fns@3` — tree-shakeable, ESM-first,
- * sem mutação de Date. DS importa apenas o necessário para o
- * Calendar/InputDate; bundle real ~3 KB gzip.
+ * `date-fns@4.x` is the successor of `date-fns@3` — tree-shakeable,
+ * ESM-first, no Date mutation. The DS imports only what is needed for
+ * Calendar/InputDate; real bundle ~3 KB gzip.
  *
  * @see ./README.md
  * @see ADR-004 §3.1 (vendor isolation convention)