laif-ds 0.2.42 → 0.2.44

package/dist/index.d.ts

@@ -42,6 +42,7 @@ import * as RechartsPrimitive from 'recharts';
 import { RefAttributes } from 'react';
 import { RefObject } from 'react';
 import * as ResizablePrimitive from 'react-resizable-panels';
+import { Row } from '@tanstack/react-table';
 import * as ScrollAreaPrimitive from '@radix-ui/react-scroll-area';
 import * as SelectPrimitive from '@radix-ui/react-select';
 import * as SeparatorPrimitive from '@radix-ui/react-separator';
@@ -356,6 +357,23 @@ export declare const badgeVariants: (props?: ({
 
 declare type BarItemDataType = RepeatDataType | NoRepeatDataType;
 
+/**
+ * Base configuration for all column types
+ * - accessorKey: optional, type-safe key from TData (supports nested paths like "user.name")
+ * - id: optional, auto-generated if not provided (allows multiple columns with same accessor)
+ * - cell: can receive either value (if accessorKey provided) or just row (if no accessorKey)
+ */
+declare interface BaseColumnConfig<TData> {
+    id?: string;
+    accessorKey?: DeepKeys<TData>;
+    header: string;
+    sortable?: boolean;
+    filterable?: boolean;
+    searchable?: boolean;
+    pinned?: "left" | "right";
+    cell?: (value: any, row: TData, tableRow: Row<TData>) => React.ReactNode;
+}
+
 declare type BaseProps = {
     options: AppSelectOption[];
     placeholder?: string;
@@ -770,6 +788,286 @@ declare type CopyButtonProps = {
     copyMessage?: string;
 };
 
+/**
+ * Creates an action column (not sortable/filterable/searchable)
+ * @example
+ * createActionColumn<Person>({
+ *   id: "actions",
+ *   header: "Azioni",
+ *   pinned: "right",
+ *   cell: (row) => <Button>Edit {row.name}</Button>
+ * })
+ */
+export declare function createActionColumn<TData>(config: {
+    id: string;
+    header: string;
+    pinned?: "left" | "right";
+    cell: (row: TData) => React.ReactNode;
+}): ColumnDef<TData>;
+
+/**
+ * Creates a boolean column with sensible defaults
+ * @example
+ * createBooleanColumn<Person>({
+ *   accessorKey: "is_active",
+ *   header: "Attivo",
+ *   filterable: true,
+ *   cell: (value) => value ? "✓" : "✗"
+ * })
+ */
+export declare function createBooleanColumn<TData>(config: BaseColumnConfig<TData>): ColumnDef<TData>;
+
+/**
+ * Creates a boolean filter badge
+ * @example
+ * createBooleanFilter("is_active", "Attivo", "checked")
+ */
+export declare function createBooleanFilter(columnId: string, columnAccessorKey: string, columnLabel: string, operator: "checked" | "unchecked" | "eq" | "ne", value?: boolean): DataTableBadgeFilter;
+
+/**
+ * Creates a computed column with a specific type (allows filtering/sorting based on computed value)
+ * Useful when you want to compute a value from row data but still have type-specific filtering
+ * @example
+ * // Age in months (computed from age)
+ * createComputedColumn<Person>({
+ *   id: "age_months",
+ *   header: "Età (mesi)",
+ *   type: "number",
+ *   cell: (row) => row.age * 12,
+ *   sortable: true
+ * })
+ */
+export declare function createComputedColumn<TData>(config: {
+    id?: string;
+    header: string;
+    type: "string" | "number" | "boolean" | "date" | "datetime";
+    cell: (row: TData) => React.ReactNode;
+    pinned?: "left" | "right";
+    sortable?: boolean;
+    filterable?: boolean;
+    searchable?: boolean;
+}): ColumnDef<TData>;
+
+/**
+ * Creates a date column with sensible defaults
+ * @example
+ * createDateColumn<Person>({
+ *   accessorKey: "birth_date",
+ *   header: "Data di nascita",
+ *   sortable: true,
+ *   filterable: true
+ * })
+ */
+export declare function createDateColumn<TData>(config: BaseColumnConfig<TData>): ColumnDef<TData>;
+
+/**
+ * Creates a date filter badge
+ * @example
+ * createDateFilter("birth_date", "Data di nascita", "date_after", "2000-01-01")
+ */
+export declare function createDateFilter(columnId: string, columnAccessorKey: string, columnLabel: string, operator: "eq" | "date_before" | "date_after" | "eq_null" | "n_eq_null", value?: string): DataTableBadgeFilter;
+
+/**
+ * Creates a datetime column with sensible defaults
+ * @example
+ * createDateTimeColumn<Person>({
+ *   accessorKey: "created_at",
+ *   header: "Data creazione",
+ *   sortable: true,
+ *   filterable: true
+ * })
+ */
+export declare function createDateTimeColumn<TData>(config: BaseColumnConfig<TData>): ColumnDef<TData>;
+
+/**
+ * Creates a datetime filter badge
+ * @example
+ * createDateTimeFilter("created_at", "Data creazione", "date_time_after", "2024-01-01T00:00:00")
+ */
+export declare function createDateTimeFilter(columnId: string, columnAccessorKey: string, columnLabel: string, operator: "date_time_before" | "date_time_after" | "eq_null" | "n_eq_null", value?: string): DataTableBadgeFilter;
+
+/**
+ * Creates a display-only column (no data binding, for computed/derived values)
+ * @example
+ * // Computed full name column
+ * createDisplayColumn<Person>({
+ *   id: "full_name",
+ *   header: "Nome Completo",
+ *   cell: (row) => `${row.firstName} ${row.lastName}`,
+ *   searchable: true  // Can make it searchable if needed
+ * })
+ *
+ * // Status badge column
+ * createDisplayColumn<Person>({
+ *   id: "status_badge",
+ *   header: "Stato",
+ *   cell: (row) => <Badge color={row.is_active ? "green" : "red"}>{row.status}</Badge>
+ * })
+ */
+export declare function createDisplayColumn<TData>(config: {
+    id?: string;
+    header: string;
+    cell: (row: TData) => React.ReactNode;
+    pinned?: "left" | "right";
+    searchable?: boolean;
+}): ColumnDef<TData>;
+
+/**
+ * Creates a filter badge with auto-generated ID
+ * @example
+ * createFilterBadge({
+ *   columnId: "name",
+ *   columnLabel: "Nome",
+ *   columnType: "string",
+ *   columnAccessorKey: "name",
+ *   operator: "like",
+ *   value: "John"
+ * })
+ */
+export declare function createFilterBadge(config: FilterBadgeConfig): DataTableBadgeFilter;
+
+/**
+ * Creates multiple filter badges at once
+ * @example
+ * createFilterBadges([
+ *   { columnId: "name", columnLabel: "Nome", columnType: "string", operator: "like", value: "John" },
+ *   { columnId: "age", columnLabel: "Età", columnType: "number", operator: "gt", value: 25 }
+ * ])
+ */
+export declare function createFilterBadges(configs: FilterBadgeConfig[]): DataTableBadgeFilter[];
+
+/**
+ * Creates initial state configuration for DataTable
+ * @example
+ * createInitialState({
+ *   filters: [createStringFilter("name", "Nome", "like", "John")],
+ *   searchbarFilter: "active users",
+ *   sorting: [{ column: "name", order: "asc" }],
+ *   pagination: { pageIndex: 0, pageSize: 20 }
+ * })
+ */
+export declare function createInitialState(config: InitialStateConfig): DataTableState;
+
+/**
+ * Creates a list filter badge
+ * @example
+ * createListFilter("role", "Ruolo", "list_single_select", "array_overlap", ["Admin"], roleOptions)
+ */
+export declare function createListFilter(columnId: string, columnAccessorKey: string, columnLabel: string, columnType: "list_single_select" | "list_multi_select", operator: "array_overlap" | "n_array_overlap" | "eq_null" | "n_eq_null", value?: Array<string | number>, listOptions?: AppSelectOption[]): DataTableBadgeFilter;
+
+/**
+ * Creates a multi select list column (array where user can select multiple values)
+ * @example
+ * createMultiSelectColumn<Person>({
+ *   accessorKey: "tags",
+ *   header: "Tags",
+ *   options: ["frontend", "backend", "devops"],
+ *   filterable: true
+ * })
+ */
+export declare function createMultiSelectColumn<TData>(config: ListColumnConfig<TData>): ColumnDef<TData>;
+
+/**
+ * Creates a number column with sensible defaults
+ * @example
+ * createNumberColumn<Person>({
+ *   accessorKey: "age",
+ *   header: "Età",
+ *   sortable: true,
+ *   filterable: true
+ * })
+ *
+ * // Display-only computed column
+ * createNumberColumn<Person>({
+ *   id: "age_in_months",
+ *   header: "Età (mesi)",
+ *   cell: (_, row) => row.age * 12
+ * })
+ */
+export declare function createNumberColumn<TData>(config: BaseColumnConfig<TData>): ColumnDef<TData>;
+
+/**
+ * Creates a number filter badge
+ * @example
+ * createNumberFilter("age", "Età", "gt", 25)
+ */
+export declare function createNumberFilter(columnId: string, columnAccessorKey: string, columnLabel: string, operator: "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "eq_null" | "n_eq_null", value?: number): DataTableBadgeFilter;
+
+/**
+ * Creates a single select list column (array where user can select one value)
+ * @example
+ * createSingleSelectColumn<Person>({
+ *   accessorKey: "role",
+ *   header: "Ruolo",
+ *   options: ["Admin", "User", "Guest"],
+ *   filterable: true
+ * })
+ */
+export declare function createSingleSelectColumn<TData>(config: ListColumnConfig<TData>): ColumnDef<TData>;
+
+/**
+ * Creates sorting configuration
+ * @example
+ * createSorting([
+ *   { column: "name", order: "asc" },
+ *   { column: "age", order: "desc" }
+ * ])
+ */
+export declare function createSorting(sorts: Array<{
+    column: string;
+    order: "asc" | "desc";
+}>): DataTableSorting;
+
+/**
+ * Creates a string column with sensible defaults
+ * @example
+ * // Data-bound column
+ * createStringColumn<Person>({
+ *   accessorKey: "name",
+ *   header: "Nome",
+ *   sortable: true,
+ *   filterable: true
+ * })
+ *
+ * // Nested object path (supports dot notation, including nullable/optional objects)
+ * createStringColumn<Person>({
+ *   accessorKey: "address.city",
+ *   header: "Città",
+ *   sortable: true,
+ *   filterable: true
+ * })
+ *
+ * // Nullable nested object (e.g., item?: PricingItem | null)
+ * createStringColumn<Order>({
+ *   accessorKey: "item.cod_master_pu",
+ *   header: "Master PU",
+ *   sortable: true
+ * })
+ *
+ * // Multiple columns with same accessor (use unique IDs)
+ * createStringColumn<Person>({
+ *   id: "name_display",
+ *   accessorKey: "name",
+ *   header: "Nome (Display)",
+ *   cell: (value) => <strong>{value}</strong>
+ * })
+ *
+ * // Display-only column (no accessorKey)
+ * createStringColumn<Person>({
+ *   id: "custom_display",
+ *   header: "Custom",
+ *   cell: (_, row) => `${row.firstName} ${row.lastName}`
+ * })
+ */
+export declare function createStringColumn<TData>(config: BaseColumnConfig<TData>): ColumnDef<TData>;
+
+/**
+ * Creates a string filter badge
+ * @example
+ * createStringFilter("name", "Nome", "like", "John")
+ */
+export declare function createStringFilter(columnId: string, columnAccessorKey: string, columnLabel: string, operator: "like" | "n_like" | "starts_with" | "ends_with" | "eq" | "ne" | "eq_null" | "n_eq_null", value?: string): DataTableBadgeFilter;
+
 export declare interface CrossTableCell {
     render?: (fromId: string, toId: string, id?: string) => ReactNode;
     value?: number | string | null;
@@ -876,7 +1174,7 @@ export declare enum DataRepeatTypes {
     MONTH = "MONTH"
 }
 
-export declare function DataTable<TData, TValue>({ columns, data, loading, emptyComponent, className, rowSelection, onRowSelectionChange, checkable, onCheckedRowsChange, actions, hidePagination, hideActionsRow, i18n, maxSortedColumns, initialState, serverMode: isServerSide, serverConfig: resolvedServerConfig, disableAutoPageSize, }: DataTableProps<TData, TValue>): JSX.Element;
+export declare function DataTable<TData, TValue>({ columns, data, loading, emptyComponent, className, rowSelection, onRowSelectionChange, checkable, onCheckedRowsChange, actions, customComponentsLeft, customComponentsRight, hidePagination, hideActionsRow, i18n, maxSortedColumns, initialState, serverMode: isServerSide, serverConfig: resolvedServerConfig, disableAutoPageSize, }: DataTableProps<TData, TValue>): JSX.Element;
 
 export declare interface DataTableActions {
     label: string;
@@ -896,6 +1194,7 @@ declare interface DataTableAndGroup {
 export declare interface DataTableBadgeFilter {
     id: string;
     columnId: string;
+    columnAccessorKey: string;
     columnLabel: string;
     columnType: IColumnType;
     operator: FilterOperator;
@@ -1053,6 +1352,8 @@ export declare interface DataTableProps<TData, TValue> {
     checkable?: boolean;
     onCheckedRowsChange?: (checkedRows: TData[]) => void;
     actions?: DataTableActions[];
+    customComponentsLeft?: ReactNode;
+    customComponentsRight?: ReactNode;
     hidePagination?: boolean;
     hideActionsRow?: boolean;
     i18n?: DataTableI18n;
@@ -1101,6 +1402,15 @@ export declare interface DatePickerProps {
     customCalendarProps?: React_2.ComponentProps<typeof Calendar>;
 }
 
+/**
+ * Type helper to extract all possible deep paths from an object type
+ * Supports nested properties with dot notation (e.g., "user.name", "address.city")
+ * Handles nullable and optional nested objects (e.g., "item?.cod_master_pu")
+ */
+declare type DeepKeys<T> = T extends object ? {
+    [K in keyof T & string]: NonNullable<T[K]> extends object ? NonNullable<T[K]> extends any[] ? `${K}` : `${K}` | `${K}.${DeepKeys<NonNullable<T[K]>>}` : `${K}`;
+}[keyof T & string] : never;
+
 export declare function Dialog({ ...props }: React_2.ComponentProps<typeof DialogPrimitive.Root>): JSX.Element;
 
 export declare function DialogContent({ className, children, size, closeOnOverlay, ...props }: React_2.ComponentProps<typeof DialogPrimitive.Content> & {
@@ -1194,6 +1504,16 @@ declare interface FileUploaderProps {
     maxFiles?: number;
 }
 
+declare interface FilterBadgeConfig {
+    columnId: string;
+    columnAccessorKey: string;
+    columnLabel: string;
+    columnType: IColumnType;
+    operator: FilterOperator;
+    value?: string | number | boolean | Array<string | number>;
+    listOptions?: AppSelectOption[];
+}
+
 declare type FilterOperator = "array_overlap" | "checked" | "date_after" | "date_before" | "date_time_after" | "date_time_before" | "ends_with" | "eq" | "eq_null" | "ge" | "gt" | "le" | "like" | "lt" | "n_array_overlap" | "n_eq_null" | "n_like" | "ne" | "starts_with" | "unchecked";
 
 export declare const Form: <TFieldValues extends FieldValues, TContext = any, TTransformedValues = TFieldValues>(props: FormProviderProps<TFieldValues, TContext, TTransformedValues>) => React_2.JSX.Element;
@@ -1283,6 +1603,13 @@ declare type GanttProps = {
     treeTitle?: string;
 };
 
+/**
+ * Extracts column IDs from column definitions
+ * @example
+ * getColumnIds(columns) // ["name", "email", "age", "actions"]
+ */
+export declare function getColumnIds<TData>(columns: ColumnDef<TData>[]): string[];
+
 export declare const hexContrast: (hex: string) => string;
 
 export declare const hexToRgba: (hex: string, alpha: number) => string;
@@ -1296,6 +1623,7 @@ export declare function HoverCardTrigger({ ...props }: React_2.ComponentProps<ty
 declare interface IAdvancedFilterCondition {
     id: string;
     columnId: string;
+    columnAccessorKey: string;
     columnLabel: string;
     columnType: IColumnType;
     operator: FilterOperator;
@@ -1352,6 +1680,19 @@ declare interface IFilterState {
     searchbarFilter?: string;
 }
 
+declare interface InitialStateConfig {
+    filters?: DataTableBadgeFilter[];
+    searchbarFilter?: string;
+    sorting?: Array<{
+        column: string;
+        order: "asc" | "desc";
+    }>;
+    pagination?: {
+        pageIndex: number;
+        pageSize: number;
+    };
+}
+
 export declare const Input: React_2.ForwardRefExoticComponent<Omit<InputProps, "ref"> & React_2.RefAttributes<HTMLInputElement>>;
 
 export declare function InputOTP({ className, containerClassName, ...props }: React_2.ComponentProps<typeof OTPInput> & {
@@ -1413,8 +1754,20 @@ declare interface InterruptPromptProps {
     close: () => void;
 }
 
+/**
+ * Validates if a filter operator is valid for a column type
+ * @example
+ * isValidOperatorForType("like", "string") // true
+ * isValidOperatorForType("like", "number") // false
+ */
+export declare function isValidOperatorForType(operator: FilterOperator, columnType: IColumnType): boolean;
+
 export declare function Label({ className, ...props }: React_2.ComponentProps<typeof LabelPrimitive.Root>): JSX.Element;
 
+declare interface ListColumnConfig<TData> extends BaseColumnConfig<TData> {
+    options: string[] | AppSelectOption[];
+}
+
 declare type LogicalOperator = "AND" | "OR";
 
 export declare function MarkdownRenderer({ children }: MarkdownRendererProps): JSX.Element;
@@ -1714,6 +2067,16 @@ declare interface PartialToolCall {
     toolName: string;
 }
 
+/**
+ * Creates a pinned version of existing columns
+ * @example
+ * pinColumns(columns, { left: ["name", "email"], right: ["actions"] })
+ */
+export declare function pinColumns<TData>(columns: ColumnDef<TData>[], pinConfig: {
+    left?: string[];
+    right?: string[];
+}): ColumnDef<TData>[];
+
 export declare function Popover({ ...props }: React_2.ComponentProps<typeof PopoverPrimitive.Root>): JSX.Element;
 
 export declare function PopoverContent({ className, align, sideOffset, container, ...props }: React_2.ComponentProps<typeof PopoverPrimitive.Content> & {
@@ -2022,6 +2385,17 @@ declare interface SourcePart {
     type: "source";
 }
 
+export declare function Spinner({ size, variant, className, ...props }: SpinnerProps): JSX.Element;
+
+export declare interface SpinnerProps extends React_2.ComponentProps<"svg"> {
+    size?: SpinnerSize | number;
+    variant?: SpinnerVariant;
+}
+
+export declare type SpinnerSize = "xxs" | "xs" | "sm" | "md" | "lg" | "xl" | "xxl";
+
+export declare type SpinnerVariant = "default" | "destructive" | "primary" | "secondary";
+
 declare type StepIndicators = {
     active?: React_2.ReactNode;
     completed?: React_2.ReactNode;
@@ -2156,6 +2530,22 @@ declare const tooltipVariants: (props?: ({
     variant?: "primary" | "card" | null | undefined;
 } & ClassProp) | undefined) => string;
 
+/**
+ * Converts string array to AppSelectOption array
+ * @example
+ * toSelectOptions(["Admin", "User", "Guest"])
+ * // Returns: [{ value: "Admin", label: "Admin" }, ...]
+ */
+export declare function toSelectOptions(values: string[]): AppSelectOption[];
+
+/**
+ * Converts array of objects to AppSelectOption array
+ * @example
+ * toSelectOptionsFromObjects(users, "id", "name")
+ * // Returns: [{ value: user.id, label: user.name }, ...]
+ */
+export declare function toSelectOptionsFromObjects<T>(items: T[], valueKey: keyof T, labelKey: keyof T): AppSelectOption[];
+
 declare type TransformedDataType<T> = {
     [P in keyof T as Exclude<P, "children">]: T[P];
 };
@@ -2171,6 +2561,13 @@ export declare interface TypoProps extends React_2.HTMLAttributes<HTMLElement> {
 
 declare type TypoVariant = "hero-title" | "title" | "subtitle" | "body" | "body-bold" | "caption" | "overline" | "button" | "small" | "h1" | "h2" | "h3" | "h4" | "h5";
 
+/**
+ * Updates list options for a specific column in columns array
+ * @example
+ * updateColumnListOptions(columns, "role", ["Admin", "User", "Guest"])
+ */
+export declare function updateColumnListOptions<TData>(columns: ColumnDef<TData>[], columnAccessorKey: string, options: string[] | AppSelectOption[]): ColumnDef<TData>[];
+
 export declare function useAudioRecording({ transcribeAudio, onTranscriptionComplete, }: UseAudioRecordingOptions): {
     isListening: boolean;
     isSpeechSupported: boolean;