@seedgrid/fe-components 2026.6.7 → 2026.7.0

package/dist/inputs/SgPeriodSelector.js

@@ -0,0 +1,368 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from "react";
+import { Controller } from "react-hook-form";
+import { resolveFieldError } from "../rhf";
+import { cn } from "../layout/sgDocking";
+import { SgCombobox } from "./SgCombobox";
+import { SgInputDate } from "./SgInputDate";
+/**
+ * Presets temporais pre-definidos para filtros de relatorios/dashboards.
+ * O valor de cada membro e igual ao seu nome (string) para trafegar bem em
+ * fontes de dados, JSON e no id de item do SgCombobox.
+ */
+export var PeriodPreset;
+(function (PeriodPreset) {
+    PeriodPreset["ALL"] = "ALL";
+    PeriodPreset["CUSTOM"] = "CUSTOM";
+    PeriodPreset["TODAY"] = "TODAY";
+    PeriodPreset["YESTERDAY"] = "YESTERDAY";
+    PeriodPreset["TOMORROW"] = "TOMORROW";
+    PeriodPreset["THIS_WEEK"] = "THIS_WEEK";
+    PeriodPreset["THIS_QUINZENA"] = "THIS_QUINZENA";
+    PeriodPreset["THIS_MONTH"] = "THIS_MONTH";
+    PeriodPreset["THIS_QUARTER"] = "THIS_QUARTER";
+    PeriodPreset["THIS_SEMESTER"] = "THIS_SEMESTER";
+    PeriodPreset["THIS_YEAR"] = "THIS_YEAR";
+    PeriodPreset["LAST_WEEK"] = "LAST_WEEK";
+    PeriodPreset["LAST_QUINZENA"] = "LAST_QUINZENA";
+    PeriodPreset["LAST_MONTH"] = "LAST_MONTH";
+    PeriodPreset["LAST_QUARTER"] = "LAST_QUARTER";
+    PeriodPreset["LAST_SEMESTER"] = "LAST_SEMESTER";
+    PeriodPreset["LAST_YEAR"] = "LAST_YEAR";
+    PeriodPreset["NEXT_WEEK"] = "NEXT_WEEK";
+    PeriodPreset["NEXT_QUINZENA"] = "NEXT_QUINZENA";
+    PeriodPreset["NEXT_MONTH"] = "NEXT_MONTH";
+    PeriodPreset["NEXT_QUARTER"] = "NEXT_QUARTER";
+    PeriodPreset["NEXT_SEMESTER"] = "NEXT_SEMESTER";
+    PeriodPreset["NEXT_YEAR"] = "NEXT_YEAR";
+})(PeriodPreset || (PeriodPreset = {}));
+const PERIOD_PRESET_LABELS = {
+    [PeriodPreset.ALL]: { "pt-BR": "Todos", "en-US": "All", es: "Todos", "pt-PT": "Todos", fr: "Tous" },
+    [PeriodPreset.CUSTOM]: { "pt-BR": "Periodo", "en-US": "Custom period", es: "Periodo", "pt-PT": "Periodo", fr: "Periode" },
+    [PeriodPreset.TODAY]: { "pt-BR": "Hoje", "en-US": "Today", es: "Hoy", "pt-PT": "Hoje", fr: "Aujourd'hui" },
+    [PeriodPreset.YESTERDAY]: { "pt-BR": "Ontem", "en-US": "Yesterday", es: "Ayer", "pt-PT": "Ontem", fr: "Hier" },
+    [PeriodPreset.TOMORROW]: { "pt-BR": "Amanha", "en-US": "Tomorrow", es: "Manana", "pt-PT": "Amanha", fr: "Demain" },
+    [PeriodPreset.THIS_WEEK]: { "pt-BR": "Esta semana", "en-US": "This week", es: "Esta semana", "pt-PT": "Esta semana", fr: "Cette semaine" },
+    [PeriodPreset.THIS_QUINZENA]: { "pt-BR": "Esta quinzena", "en-US": "This fortnight", es: "Esta quincena", "pt-PT": "Esta quinzena", fr: "Cette quinzaine" },
+    [PeriodPreset.THIS_MONTH]: { "pt-BR": "Este mes", "en-US": "This month", es: "Este mes", "pt-PT": "Este mes", fr: "Ce mois" },
+    [PeriodPreset.THIS_QUARTER]: { "pt-BR": "Este trimestre", "en-US": "This quarter", es: "Este trimestre", "pt-PT": "Este trimestre", fr: "Ce trimestre" },
+    [PeriodPreset.THIS_SEMESTER]: { "pt-BR": "Este semestre", "en-US": "This semester", es: "Este semestre", "pt-PT": "Este semestre", fr: "Ce semestre" },
+    [PeriodPreset.THIS_YEAR]: { "pt-BR": "Este ano", "en-US": "This year", es: "Este ano", "pt-PT": "Este ano", fr: "Cette annee" },
+    [PeriodPreset.LAST_WEEK]: { "pt-BR": "Semana passada", "en-US": "Last week", es: "Semana pasada", "pt-PT": "Semana passada", fr: "Semaine derniere" },
+    [PeriodPreset.LAST_QUINZENA]: { "pt-BR": "Quinzena passada", "en-US": "Last fortnight", es: "Quincena pasada", "pt-PT": "Quinzena passada", fr: "Quinzaine derniere" },
+    [PeriodPreset.LAST_MONTH]: { "pt-BR": "Mes passado", "en-US": "Last month", es: "Mes pasado", "pt-PT": "Mes passado", fr: "Mois dernier" },
+    [PeriodPreset.LAST_QUARTER]: { "pt-BR": "Trimestre passado", "en-US": "Last quarter", es: "Trimestre pasado", "pt-PT": "Trimestre passado", fr: "Trimestre dernier" },
+    [PeriodPreset.LAST_SEMESTER]: { "pt-BR": "Semestre passado", "en-US": "Last semester", es: "Semestre pasado", "pt-PT": "Semestre passado", fr: "Semestre dernier" },
+    [PeriodPreset.LAST_YEAR]: { "pt-BR": "Ano passado", "en-US": "Last year", es: "Ano pasado", "pt-PT": "Ano passado", fr: "Annee derniere" },
+    [PeriodPreset.NEXT_WEEK]: { "pt-BR": "Proxima semana", "en-US": "Next week", es: "Proxima semana", "pt-PT": "Proxima semana", fr: "Semaine prochaine" },
+    [PeriodPreset.NEXT_QUINZENA]: { "pt-BR": "Proxima quinzena", "en-US": "Next fortnight", es: "Proxima quincena", "pt-PT": "Proxima quinzena", fr: "Quinzaine prochaine" },
+    [PeriodPreset.NEXT_MONTH]: { "pt-BR": "Proximo mes", "en-US": "Next month", es: "Proximo mes", "pt-PT": "Proximo mes", fr: "Mois prochain" },
+    [PeriodPreset.NEXT_QUARTER]: { "pt-BR": "Proximo trimestre", "en-US": "Next quarter", es: "Proximo trimestre", "pt-PT": "Proximo trimestre", fr: "Trimestre prochain" },
+    [PeriodPreset.NEXT_SEMESTER]: { "pt-BR": "Proximo semestre", "en-US": "Next semester", es: "Proximo semestre", "pt-PT": "Proximo semestre", fr: "Semestre prochain" },
+    [PeriodPreset.NEXT_YEAR]: { "pt-BR": "Proximo ano", "en-US": "Next year", es: "Proximo ano", "pt-PT": "Proximo ano", fr: "Annee prochaine" }
+};
+const GROUP_LABELS = {
+    current: { "pt-BR": "Atuais", "en-US": "Current", es: "Actuales", "pt-PT": "Atuais", fr: "Actuels" },
+    future: { "pt-BR": "Futuros", "en-US": "Future", es: "Futuros", "pt-PT": "Futuros", fr: "Futurs" },
+    past: { "pt-BR": "Passados", "en-US": "Past", es: "Pasados", "pt-PT": "Passados", fr: "Passes" }
+};
+function pickLocale(map, locale) {
+    return map[locale] ?? map["pt-BR"] ?? Object.values(map)[0] ?? "";
+}
+export function periodPresetLabel(preset, locale = "pt-BR") {
+    return pickLocale(PERIOD_PRESET_LABELS[preset], locale);
+}
+/* ------------------------------------------------------------------ */
+/* PeriodResolver — logica pura, sem React                             */
+/* ------------------------------------------------------------------ */
+function startOfDay(d) {
+    return new Date(d.getFullYear(), d.getMonth(), d.getDate(), 0, 0, 0, 0);
+}
+function endOfDay(d) {
+    // Fim = ultimo instante do dia (23:59:59.999), inclusivo.
+    return new Date(d.getFullYear(), d.getMonth(), d.getDate(), 23, 59, 59, 999);
+}
+function lastDayOfMonth(year, month) {
+    return new Date(year, month + 1, 0).getDate();
+}
+function dayBounds(ref) {
+    return { start: startOfDay(ref), end: endOfDay(ref) };
+}
+/** Semana de calendario com inicio na SEGUNDA-FEIRA (documentado). */
+function weekBounds(ref) {
+    const day = ref.getDay(); // 0=domingo .. 6=sabado
+    const daysSinceMonday = (day + 6) % 7;
+    const start = new Date(ref.getFullYear(), ref.getMonth(), ref.getDate() - daysSinceMonday);
+    const end = new Date(start.getFullYear(), start.getMonth(), start.getDate() + 6);
+    return { start: startOfDay(start), end: endOfDay(end) };
+}
+/**
+ * Quinzena de CALENDARIO (nao 15 dias corridos):
+ * dia 1..15 (primeira quinzena) e dia 16..ultimo dia do mes (segunda quinzena).
+ */
+function quinzenaBounds(ref) {
+    const year = ref.getFullYear();
+    const month = ref.getMonth();
+    if (ref.getDate() <= 15) {
+        return { start: startOfDay(new Date(year, month, 1)), end: endOfDay(new Date(year, month, 15)) };
+    }
+    return {
+        start: startOfDay(new Date(year, month, 16)),
+        end: endOfDay(new Date(year, month, lastDayOfMonth(year, month)))
+    };
+}
+/** Desloca `ref` por `delta` quinzenas de calendario, podendo cruzar meses. */
+function shiftQuinzena(ref, delta) {
+    const half = ref.getDate() <= 15 ? 0 : 1;
+    const monthIndex = ref.getFullYear() * 12 + ref.getMonth();
+    const absHalf = monthIndex * 2 + half + delta;
+    const newMonthIndex = Math.floor(absHalf / 2);
+    const newHalf = absHalf - newMonthIndex * 2;
+    const newYear = Math.floor(newMonthIndex / 12);
+    const newMonth = newMonthIndex - newYear * 12;
+    // Dia representativo dentro da quinzena alvo (5 -> 1a metade, 20 -> 2a metade).
+    return new Date(newYear, newMonth, newHalf === 0 ? 5 : 20);
+}
+function monthBounds(ref) {
+    const year = ref.getFullYear();
+    const month = ref.getMonth();
+    return {
+        start: startOfDay(new Date(year, month, 1)),
+        end: endOfDay(new Date(year, month, lastDayOfMonth(year, month)))
+    };
+}
+/** Trimestre de calendario: Jan-Mar, Abr-Jun, Jul-Set, Out-Dez. */
+function quarterBounds(ref) {
+    const year = ref.getFullYear();
+    const startMonth = Math.floor(ref.getMonth() / 3) * 3;
+    const endMonth = startMonth + 2;
+    return {
+        start: startOfDay(new Date(year, startMonth, 1)),
+        end: endOfDay(new Date(year, endMonth, lastDayOfMonth(year, endMonth)))
+    };
+}
+/** Semestre de calendario: Jan-Jun ou Jul-Dez. */
+function semesterBounds(ref) {
+    const year = ref.getFullYear();
+    const startMonth = ref.getMonth() < 6 ? 0 : 6;
+    const endMonth = startMonth + 5;
+    return {
+        start: startOfDay(new Date(year, startMonth, 1)),
+        end: endOfDay(new Date(year, endMonth, lastDayOfMonth(year, endMonth)))
+    };
+}
+function yearBounds(ref) {
+    const year = ref.getFullYear();
+    return { start: startOfDay(new Date(year, 0, 1)), end: endOfDay(new Date(year, 11, 31)) };
+}
+function addDays(ref, days) {
+    return new Date(ref.getFullYear(), ref.getMonth(), ref.getDate() + days);
+}
+function addMonths(ref, months) {
+    // Usa dia 15 para evitar overflow (ex.: 31 -> mes sem dia 31).
+    return new Date(ref.getFullYear(), ref.getMonth() + months, 15);
+}
+function boundsFor(preset, ref) {
+    switch (preset) {
+        case PeriodPreset.ALL:
+        case PeriodPreset.CUSTOM:
+            return null;
+        case PeriodPreset.TODAY:
+            return dayBounds(ref);
+        case PeriodPreset.YESTERDAY:
+            return dayBounds(addDays(ref, -1));
+        case PeriodPreset.TOMORROW:
+            return dayBounds(addDays(ref, 1));
+        case PeriodPreset.THIS_WEEK:
+            return weekBounds(ref);
+        case PeriodPreset.LAST_WEEK:
+            return weekBounds(addDays(ref, -7));
+        case PeriodPreset.NEXT_WEEK:
+            return weekBounds(addDays(ref, 7));
+        case PeriodPreset.THIS_QUINZENA:
+            return quinzenaBounds(ref);
+        case PeriodPreset.LAST_QUINZENA:
+            return quinzenaBounds(shiftQuinzena(ref, -1));
+        case PeriodPreset.NEXT_QUINZENA:
+            return quinzenaBounds(shiftQuinzena(ref, 1));
+        case PeriodPreset.THIS_MONTH:
+            return monthBounds(ref);
+        case PeriodPreset.LAST_MONTH:
+            return monthBounds(addMonths(ref, -1));
+        case PeriodPreset.NEXT_MONTH:
+            return monthBounds(addMonths(ref, 1));
+        case PeriodPreset.THIS_QUARTER:
+            return quarterBounds(ref);
+        case PeriodPreset.LAST_QUARTER:
+            return quarterBounds(addMonths(ref, -3));
+        case PeriodPreset.NEXT_QUARTER:
+            return quarterBounds(addMonths(ref, 3));
+        case PeriodPreset.THIS_SEMESTER:
+            return semesterBounds(ref);
+        case PeriodPreset.LAST_SEMESTER:
+            return semesterBounds(addMonths(ref, -6));
+        case PeriodPreset.NEXT_SEMESTER:
+            return semesterBounds(addMonths(ref, 6));
+        case PeriodPreset.THIS_YEAR:
+            return yearBounds(ref);
+        case PeriodPreset.LAST_YEAR:
+            return yearBounds(new Date(ref.getFullYear() - 1, ref.getMonth(), 15));
+        case PeriodPreset.NEXT_YEAR:
+            return yearBounds(new Date(ref.getFullYear() + 1, ref.getMonth(), 15));
+        default:
+            return null;
+    }
+}
+/**
+ * Resolve um preset temporal para um intervalo real de datas.
+ *
+ * Convencoes:
+ * - Semana inicia na SEGUNDA-FEIRA.
+ * - Quinzena e de calendario (dia 1..15 e 16..fim do mes), nao 15 dias corridos.
+ * - startDate = 00:00:00.000 local; endDate = 23:59:59.999 local (inclusivo).
+ * - ALL/CUSTOM retornam datas nulas.
+ * - minDate/maxDate (options) fazem clamp do intervalo resolvido.
+ */
+export function resolvePeriod(preset, ref = new Date(), options = {}) {
+    const locale = options.locale ?? "pt-BR";
+    const label = periodPresetLabel(preset, locale);
+    const bounds = boundsFor(preset, ref);
+    if (!bounds) {
+        return { preset, label, startDate: null, endDate: null };
+    }
+    let { start, end } = bounds;
+    if (options.minDate && start.getTime() < options.minDate.getTime()) {
+        start = new Date(options.minDate.getTime());
+    }
+    if (options.maxDate && end.getTime() > options.maxDate.getTime()) {
+        end = new Date(options.maxDate.getTime());
+    }
+    return { preset, label, startDate: start, endDate: end };
+}
+/* ------------------------------------------------------------------ */
+/* Montagem das opcoes da UI a partir dos flags permit*                */
+/* ------------------------------------------------------------------ */
+const CURRENT_PRESETS = [
+    PeriodPreset.THIS_YEAR,
+    PeriodPreset.THIS_SEMESTER,
+    PeriodPreset.THIS_QUARTER,
+    PeriodPreset.THIS_MONTH,
+    PeriodPreset.THIS_QUINZENA,
+    PeriodPreset.THIS_WEEK,
+    PeriodPreset.TODAY,
+    PeriodPreset.YESTERDAY
+];
+const FUTURE_PRESETS = [
+    PeriodPreset.TOMORROW,
+    PeriodPreset.NEXT_WEEK,
+    PeriodPreset.NEXT_QUINZENA,
+    PeriodPreset.NEXT_MONTH,
+    PeriodPreset.NEXT_QUARTER,
+    PeriodPreset.NEXT_SEMESTER,
+    PeriodPreset.NEXT_YEAR
+];
+const PAST_PRESETS = [
+    PeriodPreset.LAST_WEEK,
+    PeriodPreset.LAST_QUINZENA,
+    PeriodPreset.LAST_MONTH,
+    PeriodPreset.LAST_QUARTER,
+    PeriodPreset.LAST_SEMESTER,
+    PeriodPreset.LAST_YEAR
+];
+export function buildPeriodOptions(config, locale = "pt-BR") {
+    const options = [];
+    const push = (preset, group) => {
+        options.push({ id: preset, label: periodPresetLabel(preset, locale), group });
+    };
+    if (config.permitAll)
+        push(PeriodPreset.ALL, "");
+    if (config.allowCustomPeriod)
+        push(PeriodPreset.CUSTOM, "");
+    if (config.permitCurrent) {
+        const g = pickLocale(GROUP_LABELS.current, locale);
+        CURRENT_PRESETS.forEach((p) => push(p, g));
+    }
+    if (config.permitFuture) {
+        const g = pickLocale(GROUP_LABELS.future, locale);
+        FUTURE_PRESETS.forEach((p) => push(p, g));
+    }
+    if (config.permitPast) {
+        const g = pickLocale(GROUP_LABELS.past, locale);
+        PAST_PRESETS.forEach((p) => push(p, g));
+    }
+    return options;
+}
+/* ------------------------------------------------------------------ */
+/* Componente                                                          */
+/* ------------------------------------------------------------------ */
+function toIsoDate(d) {
+    if (!d)
+        return "";
+    const year = d.getFullYear();
+    const month = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}
+function parseIsoDate(value) {
+    if (!value)
+        return null;
+    const [y, m, d] = value.split("-").map((part) => Number(part));
+    if (!y || !m || !d)
+        return null;
+    return new Date(y, m - 1, d);
+}
+function SgPeriodSelectorBase(props) {
+    const { id = "sg-period-selector", label, value, onChange, permitPast = true, permitCurrent = true, permitFuture = true, permitAll = true, allowCustomPeriod = true, locale = "pt-BR", disabled, required, minDate, maxDate, referenceDate, className, error } = props;
+    const isControlled = value !== undefined;
+    const [internalPreset, setInternalPreset] = React.useState(value ?? null);
+    const selectedPreset = isControlled ? value ?? null : internalPreset;
+    const [customStart, setCustomStart] = React.useState(null);
+    const [customEnd, setCustomEnd] = React.useState(null);
+    const options = React.useMemo(() => buildPeriodOptions({ permitAll, allowCustomPeriod, permitCurrent, permitFuture, permitPast }, locale), [permitAll, allowCustomPeriod, permitCurrent, permitFuture, permitPast, locale]);
+    const resolveOptions = React.useMemo(() => ({ minDate, maxDate, locale }), [minDate, maxDate, locale]);
+    const emitCustom = React.useCallback((start, end) => {
+        onChange?.({
+            preset: PeriodPreset.CUSTOM,
+            label: periodPresetLabel(PeriodPreset.CUSTOM, locale),
+            startDate: start ? new Date(start.getFullYear(), start.getMonth(), start.getDate(), 0, 0, 0, 0) : null,
+            endDate: end ? new Date(end.getFullYear(), end.getMonth(), end.getDate(), 23, 59, 59, 999) : null
+        });
+    }, [locale, onChange]);
+    const handleValueChange = React.useCallback((raw) => {
+        if (raw == null || raw === "") {
+            if (!isControlled)
+                setInternalPreset(null);
+            return;
+        }
+        const preset = String(raw);
+        if (!isControlled)
+            setInternalPreset(preset);
+        if (preset === PeriodPreset.CUSTOM) {
+            // Emite CUSTOM com o que houver preenchido no mini range (pode ser nulo).
+            emitCustom(customStart, customEnd);
+            return;
+        }
+        onChange?.(resolvePeriod(preset, referenceDate ?? new Date(), resolveOptions));
+    }, [customEnd, customStart, emitCustom, isControlled, onChange, referenceDate, resolveOptions]);
+    const showCustomRange = allowCustomPeriod && selectedPreset === PeriodPreset.CUSTOM;
+    return (_jsxs("div", { className: cn("w-full max-w-[18rem]", className), children: [_jsx(SgCombobox, { id: id, label: label, source: options, value: selectedPreset ?? null, grouped: true, openOnFocus: true, enabled: disabled ? false : undefined, required: required, error: error, renderGroupHeader: (group) => group ? (_jsx("div", { className: "mt-2 border-b border-border pb-1.5 text-center text-[11px] font-bold uppercase tracking-wider text-muted-foreground", children: group })) : null, onValueChange: handleValueChange }), showCustomRange ? (_jsxs("div", { className: "mt-2 grid grid-cols-1 gap-2", children: [_jsx(SgInputDate, { id: `${id}-custom-start`, inputProps: { value: toIsoDate(customStart) }, minDate: minDate, maxDate: maxDate, enabled: disabled ? false : undefined, onChange: (next) => {
+                            const parsed = parseIsoDate(next);
+                            setCustomStart(parsed);
+                            emitCustom(parsed, customEnd);
+                        } }), _jsx(SgInputDate, { id: `${id}-custom-end`, inputProps: { value: toIsoDate(customEnd) }, minDate: minDate, maxDate: maxDate, enabled: disabled ? false : undefined, onChange: (next) => {
+                            const parsed = parseIsoDate(next);
+                            setCustomEnd(parsed);
+                            emitCustom(customStart, parsed);
+                        } })] })) : null] }));
+}
+export function SgPeriodSelector(props) {
+    const { control, name, rules, ...rest } = props;
+    if (control && name) {
+        return (_jsx(Controller, { name: name, control: control, rules: rules, render: ({ field, fieldState }) => (_jsx(SgPeriodSelectorBase, { ...rest, error: resolveFieldError(rest.error, fieldState.error?.message), value: field.value ?? undefined, onChange: (period) => {
+                    field.onChange(period.preset);
+                    rest.onChange?.(period);
+                } })) }));
+    }
+    return _jsx(SgPeriodSelectorBase, { ...rest });
+}

package/dist/inputs/SgPeriodSelector.meta.d.ts

@@ -0,0 +1,4 @@
+import type { SgAiHintsV0, SgMetaV0 } from "../ai-meta/types";
+export declare const sgMeta: SgMetaV0;
+export declare const aiHints: SgAiHintsV0;
+//# sourceMappingURL=SgPeriodSelector.meta.d.ts.map

package/dist/inputs/SgPeriodSelector.meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SgPeriodSelector.meta.d.ts","sourceRoot":"","sources":["../../src/inputs/SgPeriodSelector.meta.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE9D,eAAO,MAAM,MAAM,EAAE,QAmCpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WAmBrB,CAAC"}

package/dist/inputs/SgPeriodSelector.meta.js

@@ -0,0 +1,55 @@
+export const sgMeta = {
+    version: "0.1",
+    componentId: "form.input.periodSelector",
+    package: "@seedgrid/fe-components",
+    exportName: "SgPeriodSelector",
+    slug: "sg-period-selector",
+    displayName: "SgPeriodSelector",
+    category: "input",
+    subcategory: "period",
+    description: "Seletor de periodos pre-definidos (Este mes, Ultimo trimestre, etc.) que resolve a regra temporal para um intervalo real de datas.",
+    tags: ["form", "period", "date-range", "filter", "report", "rhf"],
+    capabilities: ["single-selection", "grouped-results", "date-resolution", "custom-range"],
+    fieldSemantics: ["dateRange", "periodFilter", "structuredChoice"],
+    props: [
+        { name: "id", type: "string", description: "Identificador unico do campo.", semanticRole: "data", bindable: false },
+        { name: "label", type: "string", description: "Rotulo exibido ao usuario.", semanticRole: "label", bindable: true },
+        { name: "value", type: "PeriodPreset", description: "Preset selecionado (modo controlado).", semanticRole: "value", bindable: true },
+        { name: "onChange", type: "(period: ResolvedPeriod) => void", description: "Callback com o preset e intervalo resolvido.", semanticRole: "event", bindable: false },
+        { name: "permitPast", type: "boolean", default: true, description: "Habilita o grupo de periodos passados.", semanticRole: "behavior", bindable: true },
+        { name: "permitCurrent", type: "boolean", default: true, description: "Habilita o grupo de periodos atuais.", semanticRole: "behavior", bindable: true },
+        { name: "permitFuture", type: "boolean", default: true, description: "Habilita o grupo de periodos futuros.", semanticRole: "behavior", bindable: true },
+        { name: "permitAll", type: "boolean", default: true, description: "Habilita a opcao Todos (sem limites de data).", semanticRole: "behavior", bindable: true },
+        { name: "allowCustomPeriod", type: "boolean", default: true, description: "Habilita a opcao Periodo (intervalo customizado).", semanticRole: "behavior", bindable: true },
+        { name: "locale", type: "string", default: "pt-BR", description: "Locale usado nos labels e formatacao.", semanticRole: "behavior", bindable: true },
+        { name: "minDate", type: "Date", description: "Limite inferior aplicado como clamp no intervalo.", semanticRole: "behavior", bindable: true },
+        { name: "maxDate", type: "Date", description: "Limite superior aplicado como clamp no intervalo.", semanticRole: "behavior", bindable: true }
+    ],
+    states: ["default", "focused", "open", "disabled", "error", "custom-range"],
+    showcase: { route: "/components/sg-period-selector", hasPlayground: false, hasPropsTable: true },
+    sdui: {
+        rendererType: "field.periodSelector",
+        acceptsDataBinding: true,
+        defaultProps: { permitPast: true, permitCurrent: true, permitFuture: true, permitAll: true, allowCustomPeriod: true, locale: "pt-BR" }
+    }
+};
+export const aiHints = {
+    version: "0.1",
+    preferredUseCases: [
+        "Filtros de periodo em relatorios, dashboards e telas financeiras.",
+        "Escolha rapida de intervalos recorrentes (Este mes, Ultimo trimestre, Este ano).",
+        "Substituir dois date pickers quando a maioria dos filtros e por regra temporal."
+    ],
+    avoidUseCases: [
+        "Selecao de uma unica data especifica; prefira SgInputDate.",
+        "Intervalos totalmente arbitrarios sem presets; use um date range dedicado.",
+        "Selecao de horario/hora do dia."
+    ],
+    synonyms: ["period selector", "date range preset", "seletor de periodo", "filtro de periodo", "period filter"],
+    relatedEntityFields: ["periodo", "dataInicio", "dataFim", "competencia", "vencimento"],
+    compositionHints: [
+        "Combinar com SgDatatable e graficos como filtro superior.",
+        "Usar dentro de SgToolBar ou SgPanel de filtros."
+    ],
+    rankingSignals: { freeText: 0, structuredChoice: 0.85, date: 0.95, number: 0, denseLayout: 0.7 }
+};

package/dist/inputs/useSgMultiSelect.d.ts

@@ -0,0 +1,48 @@
+import React from "react";
+export type SgMultiSelectOptionValue = string | number;
+export type SgMultiSelectOption = {
+    label: string;
+    value: SgMultiSelectOptionValue;
+    disabled?: boolean;
+};
+export declare function valueEquals(left: SgMultiSelectOptionValue, right: SgMultiSelectOptionValue): boolean;
+export type UseSgMultiSelectParams = {
+    options: SgMultiSelectOption[];
+    value?: SgMultiSelectOptionValue[];
+    onChange?: (value: SgMultiSelectOptionValue[]) => void;
+    searchable?: boolean;
+    maxSelected?: number;
+    isDisabled: boolean;
+    borderRadius?: number | string;
+};
+/**
+ * Logica compartilhada entre SgMultiSelect e SgMultiSelectChips: estado de
+ * abertura, selecao, busca, posicionamento do dropdown via portal e navegacao
+ * por teclado. Os componentes apenas renderizam o trigger e reaproveitam o
+ * dropdown a partir do que este hook expoe.
+ */
+export declare function useSgMultiSelect(params: UseSgMultiSelectParams): {
+    readonly wrapperRef: React.RefObject<HTMLDivElement | null>;
+    readonly inputRef: React.RefObject<HTMLInputElement | null>;
+    readonly dropdownRef: React.RefObject<HTMLDivElement | null>;
+    readonly searchRef: React.RefObject<HTMLInputElement | null>;
+    readonly ignoreBlurRef: React.RefObject<boolean>;
+    readonly open: boolean;
+    readonly activeIndex: number;
+    readonly query: string;
+    readonly dropdownStyle: React.CSSProperties;
+    readonly resolvedValue: SgMultiSelectOptionValue[];
+    readonly selectedLabels: string[];
+    readonly selectedOptions: SgMultiSelectOption[];
+    readonly visibleOptions: SgMultiSelectOption[];
+    readonly setQuery: React.Dispatch<React.SetStateAction<string>>;
+    readonly setActiveIndex: React.Dispatch<React.SetStateAction<number>>;
+    readonly isSelected: (optionValue: SgMultiSelectOptionValue) => boolean;
+    readonly toggleOption: (option: SgMultiSelectOption) => void;
+    readonly removeValue: (optionValue: SgMultiSelectOptionValue) => void;
+    readonly clearSelection: () => void;
+    readonly closeDropdown: () => void;
+    readonly openDropdown: () => void;
+    readonly handleListKeyDown: (event: React.KeyboardEvent) => void;
+};
+//# sourceMappingURL=useSgMultiSelect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSgMultiSelect.d.ts","sourceRoot":"","sources":["../../src/inputs/useSgMultiSelect.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvD,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,wBAAwB,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,wBAAgB,WAAW,CAAC,IAAI,EAAE,wBAAwB,EAAE,KAAK,EAAE,wBAAwB,WAE1F;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,KAAK,CAAC,EAAE,wBAAwB,EAAE,CAAC;IACnC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,wBAAwB,EAAE,KAAK,IAAI,CAAC;IACvD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB;;;;;;;;;;;;;;;;uCAyB7C,wBAAwB;oCA6C7B,mBAAmB;wCAgBd,wBAAwB;;;;wCA4E9B,KAAK,CAAC,aAAa;EAiE9B"}