@starasia/admin 8.2.7 → 8.2.9

package/dist/components/FilterBar/components/MobileFilterBar.d.ts

@@ -0,0 +1,51 @@
+import { default as React } from 'react';
+import { FilterFieldConfig, SavedView } from '../types';
+import { OrderedColumn } from '../hooks/useColumnPrefs';
+import { Pagination as PaginationMeta } from '../../TableSection/types';
+
+interface MobileFilterBarProps {
+    withPadding: boolean;
+    configs: FilterFieldConfig[];
+    activeKeys: string[];
+    configByKey: Record<string, FilterFieldConfig>;
+    hasActiveFilter: boolean;
+    toggleFilter: (key: string) => void;
+    removeFilter: (key: string) => void;
+    getValue: (field: FilterFieldConfig) => unknown;
+    setValue: (field: FilterFieldConfig, value: unknown) => void;
+    clearValue: (key: string) => void;
+    onReset: () => void;
+    searchable: boolean;
+    searchKey: string;
+    filterKey: string;
+    pageKey: string;
+    searchPlaceholder: string;
+    searchShortcut: string;
+    pagination?: PaginationMeta;
+    perPageKey: string;
+    pageSizeOptions: number[];
+    showPagination: boolean;
+    showResultCount: boolean;
+    showPageSize: boolean;
+    hasColumns: boolean;
+    orderedColumns: OrderedColumn[];
+    allVisible: boolean;
+    onToggleVisibility: (key: string) => void;
+    onReorder: (from: number, to: number) => void;
+    onSetAllHidden: (hidden: boolean) => void;
+    showSavedViews: boolean;
+    savedViews: SavedView[];
+    onApplyView: (view: SavedView) => void;
+    onDeleteView: (id: string) => void;
+    onSaveView: (name: string) => void;
+}
+/**
+ * Mobile (<768px) variant of FilterBar. Replaces the horizontal toolbar with a
+ * two-row layout: a tight toolbar (search icon-toggle + "Filter (N)" trigger +
+ * saved views + columns + more) and a compact pagination row below.
+ *
+ * The filter pills + add-filter catalog move into a bottom `Drawer` opened by
+ * the Filter button. Page-size selection moves into the "More" overflow menu.
+ */
+export declare const MobileFilterBar: React.FC<MobileFilterBarProps>;
+export {};

package/dist/components/FilterBar/components/MobileFilterDrawer.d.ts

@@ -0,0 +1,25 @@
+import { default as React } from 'react';
+import { FilterFieldConfig } from '../types';
+
+interface MobileFilterDrawerProps {
+    isOpen: boolean;
+    onClose: () => void;
+    configs: FilterFieldConfig[];
+    activeKeys: string[];
+    configByKey: Record<string, FilterFieldConfig>;
+    hasActiveFilter: boolean;
+    onToggle: (key: string) => void;
+    onReset: () => void;
+    getValue: (field: FilterFieldConfig) => unknown;
+    setValue: (field: FilterFieldConfig, value: unknown) => void;
+    clearValue: (key: string) => void;
+    removeFilter: (key: string) => void;
+}
+/**
+ * Bottom drawer that consolidates the filter UX for mobile: active pills
+ * (stacked vertically) at the top, followed by the full filter catalog as a
+ * toggleable list. Reuses `FilterPills` so each pill keeps its native editor
+ * popover — the popover floats over the drawer when tapped.
+ */
+export declare const MobileFilterDrawer: React.FC<MobileFilterDrawerProps>;
+export {};

package/dist/components/FilterBar/components/MobileMoreMenu.d.ts

@@ -0,0 +1,16 @@
+import { default as React } from 'react';
+
+interface MobileMoreMenuProps {
+    perPageKey: string;
+    pageKey: string;
+    pageSizeOptions: number[];
+    defaultPerPage?: number;
+    showPageSize: boolean;
+}
+/**
+ * Mobile-only "More" menu — overflow surface for the secondary toolbar
+ * affordances that don't fit on a narrow screen. For now this is just the
+ * page-size selector; saved-views / columns stay as their own icon buttons.
+ */
+export declare const MobileMoreMenu: React.FC<MobileMoreMenuProps>;
+export {};

package/dist/components/FilterBar/hooks/useColumnPrefs.d.ts

@@ -5,6 +5,8 @@ interface UseColumnPrefsOptions {
     scopeId?: string;
     storage: FilterStorageAdapter;
     onColumnsChange?: (state: ColumnPrefState) => void;
+    /** Controlled external state (mis. hide/freeze dari menu kolom tabel). */
+    value?: Partial<ColumnPrefState>;
 }
 export interface OrderedColumn extends ColumnConfig {
     visible: boolean;
@@ -15,7 +17,7 @@ export interface OrderedColumn extends ColumnConfig {
  * consumer via `onColumnsChange` so it can apply the result to its table.
  * Without a `scopeId` the state is session-only (still fully functional).
  */
-export declare function useColumnPrefs({ columns, scopeId, storage, onColumnsChange }: UseColumnPrefsOptions): {
+export declare function useColumnPrefs({ columns, scopeId, storage, onColumnsChange, value }: UseColumnPrefsOptions): {
     state: ColumnPrefState;
     orderedColumns: OrderedColumn[];
     allVisible: boolean;

package/dist/components/FilterBar/hooks/useFilterBarApiParams.d.ts

@@ -0,0 +1,52 @@
+import { FilterFieldConfig } from '../types';
+
+export interface UseFilterBarApiParamsOptions {
+    /** Same catalog passed to `<FilterBar>`. */
+    filterConfigs: FilterFieldConfig[];
+    /** Mirror FilterBar URL keys. */
+    filterKey?: string;
+    activeFilterKey?: string;
+    pageKey?: string;
+    perPageKey?: string;
+    searchKey?: string;
+    /** Fallback when `?page` is absent. Default 1. */
+    defaultPage?: number;
+    /** Fallback when `?perPage` is absent. Default 10. */
+    defaultPerPage?: number;
+    /**
+     * Rename output keys. Covers built-ins (`page`, `perPage`, `search`) and
+     * individual filter field keys. Example:
+     *   `{ perPage: 'limit', status: 'statusId' }`
+     */
+    paramKeys?: Record<string, string>;
+    /**
+     * Per-field custom serializer. Receives the **decoded** value
+     * (`string | string[] | Date | DateCompactValue | undefined`) and returns
+     * whatever shape the API expects. Return `undefined` to omit the key.
+     * Keyed by the filter field key (before any `paramKeys` remap).
+     */
+    serialize?: Record<string, (value: unknown) => unknown>;
+}
+export interface FilterBarApiParams {
+    /** Memoized, flat object ready to spread into a service call. */
+    params: Record<string, unknown>;
+    /** True when any filter (incl. search) is set. */
+    hasActiveFilter: boolean;
+    /** Decoded but pre-flattening values, keyed by field key — useful if a
+     *  consumer wants the `{label, value}` pairs back for display. */
+    raw: Record<string, unknown>;
+}
+/**
+ * Read FilterBar's URL state and produce a flat, API-ready params object that
+ * consumer service functions can accept directly. Drop-in for the
+ * `useQuery({ queryKey: [scope, params], queryFn: () => service.list(params) })`
+ * pattern documented in the `starasia-tanstack-query` skill.
+ *
+ * - `page` / `perPage` always present (coerced, with defaults)
+ * - `search` only when non-empty
+ * - Filter values flattened per type (single → value, multi → value[],
+ *   date → ISO string, date-compact stays raw — pair with `expandDateCompact`)
+ * - Cleared filters are omitted (no `null`, no empty array)
+ * - `paramKeys` renames output keys; `serialize` overrides default flattening
+ */
+export declare const useFilterBarApiParams: (options: UseFilterBarApiParamsOptions) => FilterBarApiParams;

package/dist/components/FilterBar/index.d.ts

@@ -1,3 +1,5 @@
 export { FilterBar } from './FilterBar';
+export { useFilterBarApiParams, type UseFilterBarApiParamsOptions, type FilterBarApiParams } from './hooks/useFilterBarApiParams';
+export { expandDateCompact, type ExpandDateCompactOptions } from './utils/expand-date-compact';
 export { localStorageAdapter, storageKeys } from './utils/storage-adapter';
 export type { FilterBarProps, FilterFieldConfig, FilterFieldType, SelectFilterField, CheckboxMultipleFilterField, DateFilterField, DateCompactFilterField, DateCompactOp, DateCompactValue, RelativeDirection, RelativePeriod, ColumnConfig, ColumnPrefState, SavedView, FilterStorageAdapter } from './types';

package/dist/components/FilterBar/types.d.ts

@@ -140,6 +140,12 @@ export interface FilterBarProps {
     columns?: ColumnConfig[];
     /** Emitted when visibility/order changes — consumer applies to its table. */
     onColumnsChange?: (state: ColumnPrefState) => void;
+    /**
+     * Controlled column state. Saat diisi, panel Customize Column ikut state ini
+     * (mis. hide/freeze dari menu kolom TableLayout) — sinkron dua arah dgn
+     * `onColumnsChange`. `frozenKey` & field lain di luar order/hidden diabaikan.
+     */
+    columnsState?: Partial<ColumnPrefState>;
     /** Enable named saved views. `scopeId` namespaces persisted data per table. */
     savedViews?: {
         enabled?: boolean;

package/dist/components/FilterBar/utils/expand-date-compact.d.ts

@@ -0,0 +1,33 @@
+import { DateCompactValue } from '../types';
+
+export interface ExpandDateCompactOptions {
+    /** Param key for the start / single date. */
+    fromKey: string;
+    /** Param key for the end of a range (only used by `is-between` and
+     *  `is-relative-to-today`). */
+    toKey: string;
+    /**
+     * Optional separate key carrying the operator. When provided:
+     * - is-empty / is-not-empty → `{ [opKey]: 'empty' | 'not-empty' }`
+     * - single-date ops (is / is-before / …) → also emits `{ [opKey]: op }`
+     *   so the API can branch on direction.
+     * When omitted, those ops produce `{}` (single-date ops still emit
+     * `{ [fromKey]: ISO }`).
+     */
+    opKey?: string;
+}
+/**
+ * Expand a `DateCompactValue` (operator + payload, as stored by the
+ * `date-compact` filter type) into a flat `Record<string, string>` ready to
+ * spread into an API params object.
+ *
+ * - `is` / `is-before` / `is-after` / `is-on-or-before` / `is-on-or-after`
+ *     → `{ [fromKey]: ISO }` (+ `{ [opKey]: op }` when `opKey` is set)
+ * - `is-between` → `{ [fromKey]: ISO, [toKey]: ISO }`
+ * - `is-relative-to-today` → resolved to absolute ISO via `computeRelativeRange`
+ *   → `{ [fromKey]: ISO, [toKey]: ISO }`
+ * - `is-empty` / `is-not-empty` → `{ [opKey]: 'empty' | 'not-empty' }` when
+ *   `opKey` is set, otherwise `{}` (caller's choice how to encode)
+ * - `undefined` value → `{}`
+ */
+export declare const expandDateCompact: (value: DateCompactValue | undefined, options: ExpandDateCompactOptions) => Record<string, string>;

package/dist/components/FilterBar/utils/relative-date.d.ts

@@ -0,0 +1,17 @@
+import { RelativeDirection, RelativePeriod } from '../types';
+
+export declare const startOfDay: (d: Date) => Date;
+export declare const shiftPeriod: (d: Date, n: number, p: RelativePeriod) => Date;
+/**
+ * Resolve a relative spec (Past 2 weeks / Next 1 month / This year …) to a
+ * concrete date range anchored at today. Shared between DatePill (preview
+ * calendar) and expandDateCompact (API param expansion).
+ */
+export declare const computeRelativeRange: (rel: {
+    direction: RelativeDirection;
+    count?: number;
+    period: RelativePeriod;
+}) => {
+    from: Date;
+    to: Date;
+};

package/dist/components/FilterBar/utils/storage-adapter.d.ts

@@ -13,4 +13,5 @@ export declare const storageKeys: {
     columns: (scopeId: string) => string;
     savedViews: (scopeId: string) => string;
     lastState: (scopeId: string) => string;
+    tableSort: (scopeId: string) => string;
 };

package/dist/components/TableLayout/ColumnMenu.d.ts

@@ -0,0 +1,15 @@
+import { default as React } from 'react';
+
+export interface ColumnMenuProps {
+    /** trigger tetap terlihat (mis. sedang di-sort / di-freeze) walau tidak hover */
+    active: boolean;
+    canSort: boolean;
+    canHide: boolean;
+    sortDir: 'asc' | 'desc' | null;
+    frozen: boolean;
+    onSort: (dir: 'asc' | 'desc') => void;
+    onClearSort: () => void;
+    onToggleFreeze: () => void;
+    onHide: () => void;
+}
+export declare const ColumnMenu: ({ active, canSort, canHide, sortDir, frozen, onSort, onClearSort, onToggleFreeze, onHide }: ColumnMenuProps) => React.JSX.Element;

package/dist/components/TableLayout/TableLayout.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { TableLayoutProps } from './types';
+
+export declare const TableLayout: <T>({ columns, data, getRowKey, size, resizable, widthStorageKey, columnState, onColumnStateChange, columnMenu, sort, defaultSort, onSortChange, height, mobileLayout, mobileBreakpoint, groupSeparator, summary, emptyState }: TableLayoutProps<T>) => React.JSX.Element;

package/dist/components/TableLayout/hooks/useTableSortApiParams.d.ts

@@ -0,0 +1,64 @@
+import { FilterStorageAdapter } from '../../FilterBar/types';
+import { TableLayoutSort } from '../types';
+
+export interface UseTableSortApiParamsOptions {
+    /** URL param holding the sort key. Default `'sortBy'`. */
+    sortKeyParam?: string;
+    /** URL param holding the sort direction. Default `'sortOrder'`. */
+    sortOrderParam?: string;
+    /** URL param for pagination — auto-reset to 1 on sort change. Default `'page'`. */
+    pageKey?: string;
+    /** Sort used when URL has no sort (and no persisted snapshot). Default `null`. */
+    defaultSort?: TableLayoutSort | null;
+    /**
+     * Rename output param keys (in `params`) without changing URL keys.
+     * Example: `{ sortBy: 'orderBy', sortOrder: 'orderDir' }` for a backend
+     * with different names. Defaults to the same names as the URL.
+     */
+    paramKeys?: {
+        sortBy?: string;
+        sortOrder?: string;
+    };
+    /**
+     * Namespace for persistence. When provided, sort is saved to storage and
+     * auto-restored when the user navigates away and comes back to a URL with
+     * no sort params (URL always wins on direct visits). Conventionally matches
+     * `FilterBar.savedViews.scopeId` so list state stays consistent.
+     */
+    scopeId?: string;
+    /**
+     * Pluggable persistence (default `localStorageAdapter`). Only used when
+     * `scopeId` is set. Same shape as `FilterBar`'s `storage` prop.
+     */
+    storage?: FilterStorageAdapter;
+}
+export interface TableSortApiParams {
+    /** Current sort, decoded from URL (or `defaultSort` when URL is empty). */
+    sort: TableLayoutSort | null;
+    /** Update sort + write to URL. Pass `null` to clear. Resets `?page` to 1
+     *  so the user lands on the first page of the newly-sorted result. */
+    setSort: (next: TableLayoutSort | null) => void;
+    /**
+     * Flat API params, ready to spread into a service call.
+     * `{ sortBy: 'createdAt', sortOrder: 'desc' }` when sort active, `{}`
+     * when not. Memoized — stable reference for tanstack `queryKey`.
+     */
+    params: Record<string, string>;
+}
+/**
+ * Persist `<TableLayout>` sort state in the URL (`?sortBy=…&sortOrder=…`) and
+ * surface a flat `{ sortBy, sortOrder }` object ready to spread into a service
+ * call — companion to `useFilterBarApiParams`.
+ *
+ * Passing the returned `onSortChange` to `<TableLayout>` flips it into
+ * **server mode** (it won't sort the data itself, it just emits — perfect
+ * when the API does the sorting). The hook resets `?page` to 1 on every
+ * sort change so the user always lands on the first page of the new order.
+ *
+ * **Persistence** (opt-in via `scopeId`): mirrors `FilterBar.useLastFilterState`.
+ * Sort is autosaved to storage on every change, and auto-restored on mount
+ * when the URL has no sort params. URL always wins on direct visits.
+ * `setSort(null)` clears both URL and storage so explicit resets aren't
+ * undone by the next back-navigation.
+ */
+export declare const useTableSortApiParams: (options?: UseTableSortApiParamsOptions) => TableSortApiParams;

package/dist/components/TableLayout/index.d.ts

@@ -0,0 +1,4 @@
+export { TableLayout } from './TableLayout';
+export { ColumnMenu } from './ColumnMenu';
+export { useTableSortApiParams, type UseTableSortApiParamsOptions, type TableSortApiParams } from './hooks/useTableSortApiParams';
+export type { TableLayoutProps, TableLayoutColumn, TableLayoutAlign, TableLayoutColumnState, TableLayoutCellProps, TableLayoutSort, TableLayoutSortDirection } from './types';

package/dist/components/TableLayout/types.d.ts

@@ -0,0 +1,149 @@
+import { ReactNode } from 'react';
+import { IconName } from '@starasia/icon';
+
+export type TableLayoutAlign = 'left' | 'center' | 'right';
+export type TableLayoutSortDirection = 'asc' | 'desc';
+export interface TableLayoutSort {
+    /** key kolom yang di-sort */
+    key: string;
+    direction: TableLayoutSortDirection;
+}
+/**
+ * Atribut span/skip untuk satu cell body (kasus merge / rowspan-colspan).
+ * Consumer yang menghitung merge-nya; TableLayout hanya menerapkan.
+ */
+export interface TableLayoutCellProps {
+    colSpan?: number;
+    rowSpan?: number;
+    /** kalau true, `<td>` tidak dirender (tertutup span dari sel lain) */
+    hidden?: boolean;
+}
+export interface TableLayoutColumn<T> {
+    /**
+     * Identitas stabil kolom — dipakai untuk hide/show & reorder.
+     * Kalau kosong, fallback ke `accessor` (string), lalu ke index.
+     */
+    key?: string;
+    /** key pada row untuk ambil nilai otomatis; abaikan kalau pakai `render` */
+    accessor?: keyof T | (string & {});
+    /** judul kolom di header */
+    title: ReactNode;
+    /** icon di sebelah kiri judul header (otomatis 16×16) */
+    icon?: IconName;
+    /** custom render isi cell; menang atas `accessor` */
+    render?: (row: T, rowIndex: number, data: T[]) => ReactNode;
+    /** perataan header + cell (default 'left') */
+    align?: TableLayoutAlign;
+    /** lebar awal kolom, mis. '200px' | 160 */
+    width?: string | number;
+    /** lebar minimum saat di-resize (px) */
+    minWidth?: number;
+    /** override resize per kolom; default ikut prop `resizable` di TableLayout */
+    resizable?: boolean;
+    /** boleh di-sort lewat menu kolom (default true bila ada accessor/sortKey) */
+    sortable?: boolean;
+    /** sumber nilai untuk sort kalau beda dari `accessor` (mis. kolom `render`) */
+    sortKey?: keyof T;
+    /** sembunyikan menu kolom (Ascending/Descending/Freeze/Hide) di kolom ini */
+    disableMenu?: boolean;
+    /** kolom terkunci — tidak bisa di-hide (item "Hide column" disembunyikan) */
+    locked?: boolean;
+    /**
+     * Jadi headline di layout mobile (judul kartu / teks utama baris collapsed).
+     * Kalau tidak ada kolom yang ditandai, fallback ke kolom pertama.
+     */
+    primary?: boolean;
+    /** sembunyikan kolom ini sepenuhnya saat layout mobile */
+    hideOnMobile?: boolean;
+    /**
+     * Grouped header: kalau diisi, kolom ini jadi GRUP (accessor/render diabaikan)
+     * dan `children` adalah leaf-column yang menyetir body. Mendukung 1 tingkat grup.
+     * Catatan: saat ada grup, resize & persist-width otomatis non-aktif.
+     */
+    children?: TableLayoutColumn<T>[];
+    /**
+     * Merge sel body (rowspan/colspan). Dipanggil per baris; kembalikan
+     * `{ colSpan, rowSpan, hidden }`. Tandai `hidden: true` pada sel yang
+     * tertutup oleh span sel lain. Diabaikan di layout mobile.
+     */
+    cellProps?: (row: T, rowIndex: number, data: T[]) => TableLayoutCellProps;
+}
+/**
+ * State visibility + urutan kolom. Bentuknya kompatibel dengan `ColumnPrefState`
+ * yang di-emit `FilterBar.onColumnsChange`, jadi bisa langsung disambungkan.
+ */
+export interface TableLayoutColumnState {
+    /** urutan key kolom (boleh subset / lengkap) */
+    order?: string[];
+    /** key kolom yang disembunyikan */
+    hidden?: string[];
+    /**
+     * Freeze "sampai kolom ini": semua leaf dari kiri s/d key ini dipin (sticky kiri).
+     * Kosong = tidak ada yang dibekukan.
+     */
+    frozenKey?: string;
+}
+export interface TableLayoutProps<T> {
+    /** definisi kolom (wajib) */
+    columns: TableLayoutColumn<T>[];
+    /** baris data (wajib) */
+    data: T[];
+    /** key unik per row; default pakai index */
+    getRowKey?: (row: T, index: number) => string | number;
+    /** padding scale, diteruskan ke primitif Table (default 'md') */
+    size?: 'sm' | 'md' | 'lg' | 'xl';
+    /** aktifkan drag-resize lebar kolom (default false) */
+    resizable?: boolean;
+    /**
+     * Kalau diisi, lebar hasil resize dipersist ke localStorage dengan key ini
+     * (lewat `useColumnWidths`) dan dipulihkan saat reload.
+     */
+    widthStorageKey?: string;
+    /**
+     * Visibility, urutan, & freeze kolom. Controlled bila diisi (sambungkan dari
+     * `FilterBar.onColumnsChange` + `onColumnStateChange`); kalau tidak, TableLayout
+     * kelola sendiri (uncontrolled).
+     */
+    columnState?: TableLayoutColumnState;
+    /** dipanggil saat hide/freeze dari menu kolom mengubah state */
+    onColumnStateChange?: (state: TableLayoutColumnState) => void;
+    /**
+     * Tampilkan menu kolom di header (Ascending, Descending, Freeze, Hide column).
+     * Muncul saat hover / saat salah satu item aktif.
+     */
+    columnMenu?: boolean;
+    /**
+     * Sort aktif (controlled). Kalau `onSortChange` diisi → mode server (TableLayout
+     * tidak mengurutkan data sendiri, hanya emit). Tanpa `onSortChange` → client-side.
+     */
+    sort?: TableLayoutSort | null;
+    /** sort awal (uncontrolled) */
+    defaultSort?: TableLayoutSort | null;
+    /** dipanggil saat sort berubah; keberadaannya mengaktifkan mode server */
+    onSortChange?: (sort: TableLayoutSort | null) => void;
+    /**
+     * Tinggi area tabel. Default: mengisi sampai bawah layar
+     * (`calc(100vh - posisiAtas)`, ikut menyesuaikan saat window di-resize).
+     * Override bebas oleh consumer, mis. '60vh' | 480 | '100%'.
+     * Area selalu scrollable (vertikal & horizontal) dan header sticky.
+     */
+    height?: string | number;
+    /**
+     * Layout saat layar < `mobileBreakpoint`:
+     * - 'cards'  : tiap row jadi kartu (label : value bertumpuk) — default
+     * - 'expand' : list ringkas (kolom `primary`) + tap untuk memuai detail
+     * - 'scroll' : tetap tabel dengan horizontal scroll
+     */
+    mobileLayout?: 'cards' | 'expand' | 'scroll';
+    /** titik switch ke layout mobile (default 'md' = < 768px) */
+    mobileBreakpoint?: 'sm' | 'md';
+    /**
+     * Baris pemisah full-width sebelum `row` (mis. grup separator "— Jakarta —").
+     * Kembalikan `null` kalau tidak ada separator untuk baris itu.
+     */
+    groupSeparator?: (row: T, index: number, prevRow: T | undefined) => ReactNode | null;
+    /** baris summary/total full-width di paling bawah body */
+    summary?: ReactNode;
+    /** ditampilkan saat `data` kosong */
+    emptyState?: ReactNode;
+}

package/dist/components/index.d.ts

@@ -13,7 +13,7 @@ export * from './Section';
 export * from './AdvanceFilterBar';
 export * from './FilterBar';
 export * from './TableSection';
-export * from './DataGrid';
+export * from './TableLayout';
 export * from './EachUtils';
 export * from './DecisionWrapper';
 export * from './Form';