@seedgrid/fe-components 2026.8.4 → 2026.8.6

package/dist/inputs/SgYearPartSelector.meta.js

@@ -0,0 +1,93 @@
+export const sgMeta = {
+    version: "0.1",
+    componentId: "form.input.yearPartSelector",
+    package: "@seedgrid/fe-components",
+    exportName: "SgYearPartSelector",
+    slug: "sg-year-part-selector",
+    displayName: "SgYearPartSelector",
+    category: "input",
+    subcategory: "period",
+    description: "Seletor de recorte de ano: o usuario escolhe ANO + RECORTE (semestre, trimestre ou bimestre) + FATIA, e o componente resolve para um intervalo real e fechado de datas. E' o irmao ABSOLUTO do SgPeriodSelector: aquele resolve presets RELATIVOS a hoje (\"este semestre\"), este resolve um recorte fixo de um ano civil informado (\"o 1o semestre DE 2024\"), que nao muda de significado com a passagem do tempo.",
+    tags: ["form", "period", "year", "semester", "quarter", "bimester", "date-range", "filter", "report", "rhf"],
+    capabilities: [
+        "single-selection",
+        "date-resolution",
+        "absolute-period",
+        "year-range-limits",
+        "kind-filtering",
+        "part-clamping",
+        "leap-year-safe"
+    ],
+    fieldSemantics: ["dateRange", "periodFilter", "fiscalPeriod", "structuredChoice", "year"],
+    props: [
+        { name: "id", type: "string", default: "sg-year-part-selector", description: "Prefixo dos ids dos tres controles internos (ano, recorte, fatia). Nao e' o id de um campo unico: o componente monta tres.", semanticRole: "data", bindable: false },
+        { name: "label", type: "string", description: "Rotulo exibido ao usuario.", semanticRole: "label", bindable: true },
+        { name: "value", type: "YearPartValue", description: "Recorte selecionado no modo controlado: { year, kind, part }, com part em base 1 (1..2 no semestre, 1..4 no trimestre, 1..6 no bimestre).", semanticRole: "value", bindable: true },
+        { name: "onChange", type: "(resolved: ResolvedYearPart) => void", description: "Callback com o recorte ja resolvido: value, label e o intervalo fechado startDate/endDate. As datas NUNCA vem nulas, diferente do ResolvedPeriod do SgPeriodSelector.", semanticRole: "event", bindable: false },
+        { name: "allowedKinds", type: "YearPartKind[]", default: ["SEMESTER", "QUARTER", "BIMESTER"], description: "Recortes oferecidos no combo. Reduza a lista quando o dominio so' aceita um deles (fechamento trimestral, por exemplo); com um unico item o combo de recorte deixa de fazer sentido na tela.", semanticRole: "behavior", bindable: true },
+        { name: "minYear", type: "number", default: "ano corrente - 30", description: "Primeiro ano oferecido na lista de anos.", semanticRole: "behavior", bindable: true },
+        { name: "maxYear", type: "number", default: "ano corrente + 10", description: "Ultimo ano oferecido na lista de anos.", semanticRole: "behavior", bindable: true },
+        { name: "locale", type: "string", default: "pt-BR", description: "Locale dos rotulos de recorte e fatia. A sigla entre parenteses acompanha o idioma: Q1..Q4 em pt-BR e en-US, T1..T4 em es, fr e pt-PT; bimestre nao tem sigla e sai sem parenteses.", semanticRole: "behavior", bindable: true },
+        { name: "disabled", type: "boolean", default: false, description: "Desabilita os tres combos (ano, recorte e fatia).", semanticRole: "behavior", bindable: true },
+        { name: "required", type: "boolean", default: false, description: "Marca o campo como obrigatorio.", semanticRole: "validation", bindable: true },
+        { name: "className", type: "string", description: "Classes extras aplicadas ao container do campo.", semanticRole: "appearance", bindable: false }
+    ],
+    states: ["default", "focused", "open", "disabled", "required", "error"],
+    showcase: {
+        route: "/components/sg-year-part-selector",
+        hasPlayground: true,
+        hasPropsTable: true
+    },
+    sdui: {
+        rendererType: "field.yearPartSelector",
+        acceptsDataBinding: true,
+        defaultProps: {
+            allowedKinds: ["SEMESTER", "QUARTER", "BIMESTER"],
+            locale: "pt-BR",
+            disabled: false,
+            required: false
+        }
+    }
+};
+export const aiHints = {
+    version: "0.1",
+    preferredUseCases: [
+        "Filtro de relatorio em que o periodo e' um recorte ABSOLUTO de um ano informado: \"1o semestre de 2024\", \"Q3 de 2023\", \"4o bimestre de 2025\".",
+        "Comparacao entre anos: mesma fatia, ano diferente (Q1/2024 contra Q1/2025).",
+        "Fechamentos periodicos (contabil, fiscal, apuracao de metas) que sempre caem em semestre, trimestre ou bimestre cheios.",
+        "Consultas a periodos historicos, em que o usuario sabe o ano e a fatia mas nao a data exata de inicio e fim."
+    ],
+    avoidUseCases: [
+        "Periodo relativo a hoje (\"este mes\", \"ultimo trimestre\", \"ultimos 30 dias\"); use SgPeriodSelector, que reavalia a regra a cada abertura da tela.",
+        "Intervalo arbitrario que nao respeita as bordas do recorte (05/03 a 17/08); use um date range ou o modo customizado do SgPeriodSelector.",
+        "Recorte mensal isolado ou semana; este componente so' fatia o ano em 2, 4 ou 6 partes iguais.",
+        "Selecao de uma unica data; prefira SgInputDate.",
+        "Selecao apenas do ano, sem fatia; um combo simples resolve."
+    ],
+    synonyms: [
+        "year part selector",
+        "seletor de recorte de ano",
+        "seletor de semestre",
+        "seletor de trimestre",
+        "seletor de bimestre",
+        "quarter picker",
+        "semester picker",
+        "half-year selector",
+        "fiscal period selector",
+        "periodo do ano"
+    ],
+    relatedEntityFields: ["ano", "exercicio", "semestre", "trimestre", "bimestre", "competencia", "periodoApuracao", "dataInicio", "dataFim"],
+    compositionHints: [
+        "Usar como filtro superior de SgDatatable e de graficos comparativos entre anos.",
+        "Colocar dentro de SgToolBar ou de um SgPanel de filtros, ao lado dos demais recortes.",
+        "Quando a tela precisa dos dois modos, ofereca SgPeriodSelector para o relativo e SgYearPartSelector para o absoluto; os dois entregam startDate/endDate no mesmo formato, entao o consumidor trata os dois com o mesmo codigo.",
+        "Ao trocar o recorte, a fatia fora de faixa cai para a primeira (clampYearPart); nao e' preciso tratar isso no consumidor."
+    ],
+    rankingSignals: {
+        freeText: 0,
+        structuredChoice: 0.9,
+        date: 0.9,
+        number: 0.3,
+        denseLayout: 0.6
+    }
+};

package/dist/inputs/yearPart.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Recorte de um ano civil em fatias de tamanho igual: semestre (2), trimestre (4) e bimestre (6).
+ *
+ * Existe para o mesmo fim do SgPeriodSelector — resolver uma REGRA temporal para um intervalo real
+ * de datas — mas para a pergunta que ele nao responde: "o 1o semestre DE 2024", e nao "este
+ * semestre". Preset e' relativo a hoje; aqui o usuario escolhe ano e fatia.
+ *
+ * Modulo separado do componente porque isto e' aritmetica de calendario pura: da' para testar sem
+ * DOM (ver tests/year-part-resolver.test.mjs), que e' onde os erros de virada de mes/ano moram.
+ */
+export declare enum YearPartKind {
+    SEMESTER = "SEMESTER",
+    QUARTER = "QUARTER",
+    BIMESTER = "BIMESTER"
+}
+export type YearPartValue = {
+    year: number;
+    kind: YearPartKind;
+    /** Fatia dentro do ano, base 1: 1..2 no semestre, 1..4 no trimestre, 1..6 no bimestre. */
+    part: number;
+};
+/**
+ * Espelha o formato de ResolvedPeriod (do SgPeriodSelector) de proposito: quem consome os dois
+ * seletores — o filtro de relatorio, por exemplo — trata os dois com o mesmo codigo. A diferenca e'
+ * que aqui as datas NUNCA sao nulas: todo recorte de ano resolve para um intervalo fechado.
+ */
+export type ResolvedYearPart = {
+    value: YearPartValue;
+    label: string;
+    startDate: Date;
+    endDate: Date;
+};
+/** Quantas fatias cabem no ano para este recorte. */
+export declare function yearPartCount(kind: YearPartKind): number;
+/** Quantos meses tem cada fatia deste recorte: 6, 3 ou 2. */
+export declare function yearPartMonths(kind: YearPartKind): number;
+/** Nome do recorte no locale pedido ("Trimestre", "Quarter"). */
+export declare function yearPartKindLabel(kind: YearPartKind, locale?: string): string;
+/**
+ * Rotulo de uma fatia: "Trimestre 1 (Q1)", "Semestre 2 (S2)", "Bimestre 3".
+ *
+ * O numero vem DEPOIS do nome porque a forma ordinal ("1o trimestre") exigiria o indicador
+ * ordinal, que esta' fora do ASCII que esta familia de componentes usa nos rotulos.
+ */
+export declare function yearPartLabel(kind: YearPartKind, part: number, locale?: string): string;
+/** Opcoes prontas para o combo da fatia, ja no locale pedido. */
+export declare function yearPartOptions(kind: YearPartKind, locale?: string): {
+    value: number;
+    label: string;
+}[];
+/** A fatia existe neste recorte? */
+export declare function isValidYearPart(kind: YearPartKind, part: number): boolean;
+/**
+ * Ao trocar o recorte, a fatia escolhida pode nao existir mais (estava no Q4 e virou semestre, que
+ * so' tem 2). Mantem a fatia quando ela couber, e cai na primeira quando nao couber — em vez de
+ * deixar um valor selecionado sem opcao correspondente na tela.
+ */
+export declare function clampYearPart(kind: YearPartKind, part: number): number;
+/**
+ * Resolve o recorte para o intervalo fechado de datas.
+ *
+ * O ultimo dia sai de `new Date(ano, primeiroMesDaProximaFatia, 0)`: dia zero e' o ultimo dia do
+ * mes anterior, entao fevereiro devolve 29 em ano bissexto sem nenhuma tabela de dias por mes.
+ *
+ * Lanca quando a fatia nao existe no recorte — numero errado aqui vira intervalo errado no
+ * relatorio, e intervalo errado com cara de certo e' pior que erro na cara.
+ */
+export declare function resolveYearPart(value: YearPartValue, locale?: string): ResolvedYearPart;
+/** Em que fatia do recorte esta data cai. Util para posicionar o seletor no periodo corrente. */
+export declare function yearPartOf(date: Date, kind: YearPartKind): YearPartValue;
+//# sourceMappingURL=yearPart.d.ts.map

package/dist/inputs/yearPart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yearPart.d.ts","sourceRoot":"","sources":["../../src/inputs/yearPart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,oBAAY,YAAY;IACtB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,QAAQ,aAAa;CACtB;AASD,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,aAAa,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;CACf,CAAC;AA8BF,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAExD;AAED,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAEzD;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,SAAU,GAAG,MAAM,CAE9E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,SAAU,GAAG,MAAM,CAOxF;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,SAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,CAKxG;AAED,oCAAoC;AACpC,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,SAAU,GAAG,gBAAgB,CAuBxF;AAED,iGAAiG;AACjG,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAMxE"}

package/dist/inputs/yearPart.js

@@ -0,0 +1,123 @@
+/**
+ * Recorte de um ano civil em fatias de tamanho igual: semestre (2), trimestre (4) e bimestre (6).
+ *
+ * Existe para o mesmo fim do SgPeriodSelector — resolver uma REGRA temporal para um intervalo real
+ * de datas — mas para a pergunta que ele nao responde: "o 1o semestre DE 2024", e nao "este
+ * semestre". Preset e' relativo a hoje; aqui o usuario escolhe ano e fatia.
+ *
+ * Modulo separado do componente porque isto e' aritmetica de calendario pura: da' para testar sem
+ * DOM (ver tests/year-part-resolver.test.mjs), que e' onde os erros de virada de mes/ano moram.
+ */
+export var YearPartKind;
+(function (YearPartKind) {
+    YearPartKind["SEMESTER"] = "SEMESTER";
+    YearPartKind["QUARTER"] = "QUARTER";
+    YearPartKind["BIMESTER"] = "BIMESTER";
+})(YearPartKind || (YearPartKind = {}));
+/** Quantas fatias o ano tem em cada recorte. */
+const PART_COUNT = {
+    [YearPartKind.SEMESTER]: 2,
+    [YearPartKind.QUARTER]: 4,
+    [YearPartKind.BIMESTER]: 6
+};
+/** Nome do recorte — e' o que aparece no combo que escolhe entre semestre/trimestre/bimestre. */
+const KIND_LABELS = {
+    [YearPartKind.SEMESTER]: { "pt-BR": "Semestre", "en-US": "Half-year", es: "Semestre", "pt-PT": "Semestre", fr: "Semestre" },
+    [YearPartKind.QUARTER]: { "pt-BR": "Trimestre", "en-US": "Quarter", es: "Trimestre", "pt-PT": "Trimestre", fr: "Trimestre" },
+    [YearPartKind.BIMESTER]: { "pt-BR": "Bimestre", "en-US": "Bimester", es: "Bimestre", "pt-PT": "Bimestre", fr: "Bimestre" }
+};
+/**
+ * Sigla da fatia, entre parenteses. NAO e' a inicial do nome traduzido: trimestre e' "Q" no
+ * portugues do Brasil e no ingles (Q1..Q4, vindo do business em ingles) mas "T" em espanhol,
+ * frances e portugues europeu, onde ninguem diz Q1. Bimestre nao tem sigla consagrada em lingua
+ * nenhuma — fica sem parenteses em vez de inventar uma.
+ */
+const PART_ABBR = {
+    [YearPartKind.SEMESTER]: { "pt-BR": "S", "en-US": "H", es: "S", "pt-PT": "S", fr: "S" },
+    [YearPartKind.QUARTER]: { "pt-BR": "Q", "en-US": "Q", es: "T", "pt-PT": "T", fr: "T" }
+};
+function pickLocale(map, locale) {
+    return map[locale] ?? map["pt-BR"] ?? Object.values(map)[0] ?? "";
+}
+/** Quantas fatias cabem no ano para este recorte. */
+export function yearPartCount(kind) {
+    return PART_COUNT[kind];
+}
+/** Quantos meses tem cada fatia deste recorte: 6, 3 ou 2. */
+export function yearPartMonths(kind) {
+    return 12 / PART_COUNT[kind];
+}
+/** Nome do recorte no locale pedido ("Trimestre", "Quarter"). */
+export function yearPartKindLabel(kind, locale = "pt-BR") {
+    return pickLocale(KIND_LABELS[kind], locale);
+}
+/**
+ * Rotulo de uma fatia: "Trimestre 1 (Q1)", "Semestre 2 (S2)", "Bimestre 3".
+ *
+ * O numero vem DEPOIS do nome porque a forma ordinal ("1o trimestre") exigiria o indicador
+ * ordinal, que esta' fora do ASCII que esta familia de componentes usa nos rotulos.
+ */
+export function yearPartLabel(kind, part, locale = "pt-BR") {
+    const name = yearPartKindLabel(kind, locale);
+    const abbrMap = PART_ABBR[kind];
+    if (!abbrMap) {
+        return `${name} ${part}`;
+    }
+    return `${name} ${part} (${pickLocale(abbrMap, locale)}${part})`;
+}
+/** Opcoes prontas para o combo da fatia, ja no locale pedido. */
+export function yearPartOptions(kind, locale = "pt-BR") {
+    return Array.from({ length: PART_COUNT[kind] }, (_, index) => ({
+        value: index + 1,
+        label: yearPartLabel(kind, index + 1, locale)
+    }));
+}
+/** A fatia existe neste recorte? */
+export function isValidYearPart(kind, part) {
+    return Number.isInteger(part) && part >= 1 && part <= PART_COUNT[kind];
+}
+/**
+ * Ao trocar o recorte, a fatia escolhida pode nao existir mais (estava no Q4 e virou semestre, que
+ * so' tem 2). Mantem a fatia quando ela couber, e cai na primeira quando nao couber — em vez de
+ * deixar um valor selecionado sem opcao correspondente na tela.
+ */
+export function clampYearPart(kind, part) {
+    return isValidYearPart(kind, part) ? part : 1;
+}
+/**
+ * Resolve o recorte para o intervalo fechado de datas.
+ *
+ * O ultimo dia sai de `new Date(ano, primeiroMesDaProximaFatia, 0)`: dia zero e' o ultimo dia do
+ * mes anterior, entao fevereiro devolve 29 em ano bissexto sem nenhuma tabela de dias por mes.
+ *
+ * Lanca quando a fatia nao existe no recorte — numero errado aqui vira intervalo errado no
+ * relatorio, e intervalo errado com cara de certo e' pior que erro na cara.
+ */
+export function resolveYearPart(value, locale = "pt-BR") {
+    const { year, kind, part } = value;
+    if (!Number.isInteger(year)) {
+        throw new RangeError(`Ano invalido: ${year}`);
+    }
+    if (!isValidYearPart(kind, part)) {
+        throw new RangeError(`Fatia ${part} nao existe em ${kind} (validas: 1..${PART_COUNT[kind]})`);
+    }
+    const months = yearPartMonths(kind);
+    const startMonth = (part - 1) * months;
+    return {
+        value: { year, kind, part },
+        label: yearPartLabel(kind, part, locale),
+        startDate: new Date(year, startMonth, 1, 0, 0, 0, 0),
+        // Dia zero do mes SEGUINTE a' fatia = ultimo dia da fatia, e fevereiro devolve 29 em ano
+        // bissexto sem nenhuma tabela de dias por mes. Fecha em 23:59:59.999 como o resolvePeriod:
+        // intervalo que termina a' meia-noite perde o ultimo dia inteiro num BETWEEN com hora.
+        endDate: new Date(year, startMonth + months, 0, 23, 59, 59, 999)
+    };
+}
+/** Em que fatia do recorte esta data cai. Util para posicionar o seletor no periodo corrente. */
+export function yearPartOf(date, kind) {
+    return {
+        year: date.getFullYear(),
+        kind,
+        part: Math.floor(date.getMonth() / yearPartMonths(kind)) + 1
+    };
+}