@starasia/admin 8.2.9 → 8.3.0

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

@@ -24,6 +24,7 @@ interface MobileFilterBarProps {
     pagination?: PaginationMeta;
     perPageKey: string;
     pageSizeOptions: number[];
+    defaultPerPage: number;
     showPagination: boolean;
     showResultCount: boolean;
     showPageSize: boolean;

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

@@ -0,0 +1,39 @@
+import { FilterFieldConfig } from '../types';
+
+export interface UseFilterBarControlsOptions {
+    /** Katalog filter yang SAMA dengan yang dipakai `<FilterBar>`. */
+    filterConfigs: FilterFieldConfig[];
+    /** Mirror key URL FilterBar (default sama dgn FilterBar). */
+    filterKey?: string;
+    activeFilterKey?: string;
+    pageKey?: string;
+    searchKey?: string;
+}
+export interface FilterBarControls {
+    /** Set nilai filter (replace). Array kosong / `[]` → hapus filter. */
+    set: (key: string, value: string | string[]) => void;
+    /** Tambah/lepas satu nilai (cocok untuk klik kartu shortcut). */
+    toggle: (key: string, value: string) => void;
+    /** Hapus filter ini sepenuhnya (nilai + pill). */
+    clear: (key: string) => void;
+    /** Reset semua filter + search. */
+    clearAll: () => void;
+    /** Apakah `value` sedang aktif pada filter `key` (untuk styling kartu aktif). */
+    isActive: (key: string, value: string) => boolean;
+    /** Nilai-nilai aktif sekarang pada filter `key`. */
+    values: (key: string) => string[];
+    /** Ada filter aktif (apa pun). */
+    hasActiveFilter: boolean;
+}
+/**
+ * Kontrol filter dari LUAR `<FilterBar>` — untuk shortcut/quick-filter
+ * (mis. summary card status yang saat diklik memfilter tabel).
+ *
+ * Sumber kebenaran sama dengan FilterBar: URL. Jadi begitu helper ini menulis,
+ * pill FilterBar, tabel, dan `useFilterBarApiParams` ikut otomatis — tanpa
+ * lifting state. Companion arah-tulis dari `useFilterBarApiParams` (arah-baca).
+ *
+ * Khusus untuk filter select-type (`dropdown` / `dropdown-multiple` /
+ * `checkbox-multiple` / `radio`). Field lain (date) diabaikan.
+ */
+export declare const useFilterBarControls: ({ filterConfigs, filterKey, activeFilterKey, pageKey, searchKey }: UseFilterBarControlsOptions) => FilterBarControls;

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

@@ -3,7 +3,7 @@ import { FilterStorageAdapter } from '../types';
 interface UseLastFilterStateOptions {
     scopeId?: string;
     storage: FilterStorageAdapter;
-    /** URL params to snapshot (e.g. [activeFilterKey, filterKey, perPageKey]). */
+    /** URL params to snapshot (e.g. [activeFilterKey, filterKey, pageKey]). */
     snapshotKeys: string[];
     /** Opt-out toggle (default true when scopeId is provided). */
     enabled?: boolean;
@@ -11,17 +11,20 @@ interface UseLastFilterStateOptions {
 /**
  * Persists the latest filter URL params per scope, so link-based back
  * navigation (which drops the query string) still restores the previous
- * filters on remount. URL always wins — restoration only kicks in when the
- * URL has none of the snapshot keys.
+ * filters. URL always wins.
  *
- * - **Autosave**: writes to `localStorage[filterbar:last:{scopeId}]` on every
- *   `searchParams` change.
- * - **Autorestore**: on mount, hydrates the URL from storage if empty.
- * - **`clear()`**: removes the snapshot; call this from Reset so the user's
- *   explicit reset isn't undone on the next navigation back.
+ * NOTE: restore-ke-URL TIDAK dilakukan di sini — dikoordinasikan oleh
+ * `useUrlHydration` (satu `setSearchParams` gabungan) supaya tidak bentrok
+ * dengan restore perPage. Hook ini hanya autosave + expose `read()` + `clear()`.
+ *
+ * - **Autosave**: writes to `filterbar:last:{scopeId}` on every URL change.
+ *   Snapshot KOSONG tidak ditulis (agar tidak menghapus snapshot saat URL
+ *   kosong transient / pindah route).
+ * - **`clear()`**: removes the snapshot (dipanggil dari Reset).
  */
 export declare function useLastFilterState({ scopeId, storage, snapshotKeys, enabled }: UseLastFilterStateOptions): {
     enabled: boolean;
+    read: () => Record<string, string> | null;
     clear: () => void;
 };
 export {};

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

@@ -0,0 +1,23 @@
+import { FilterStorageAdapter } from '../types';
+
+interface UsePerPagePrefOptions {
+    scopeId?: string;
+    storage: FilterStorageAdapter;
+    perPageKey: string;
+    /** When provided, the restored value is validated against this list. */
+    pageSizeOptions?: number[];
+    /** Opt-out toggle (default true when scopeId is provided). */
+    enabled?: boolean;
+}
+/**
+ * Persists the rows-per-page choice independently of the filter snapshot.
+ *
+ * UI preference — NOT wiped by Reset. Restore-ke-URL dikoordinasikan oleh
+ * `useUrlHydration`; hook ini hanya autosave + expose `read()` + `clear()`.
+ */
+export declare function usePerPagePref({ scopeId, storage, perPageKey, pageSizeOptions, enabled }: UsePerPagePrefOptions): {
+    enabled: boolean;
+    read: () => string | null;
+    clear: () => void;
+};
+export {};

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

@@ -0,0 +1,23 @@
+interface UseUrlHydrationOptions {
+    enabled: boolean;
+    /** Keys yang dianggap "filter snapshot" (mis. [filters, filter, page]). */
+    snapshotKeys: string[];
+    perPageKey: string;
+    /** Snapshot filter tersimpan (atau null). */
+    readSnapshot: () => Record<string, string> | null;
+    /** Page size tersimpan (string) atau null. */
+    readPerPage: () => string | null;
+}
+/**
+ * Hidrasi URL dari preferensi tersimpan. Restore filter-snapshot & perPage
+ * digabung lewat micro-batcher → tidak saling menimpa, dan tahan banting untuk
+ * >1 FilterBar dalam satu halaman.
+ *
+ * Jalan saat "tiba" di halaman: mount ATAU `location.pathname` berubah (navigasi
+ * balik), jadi halaman yang di-keep-alive router tetap ter-restore tanpa hard
+ * refresh. Di-gate ke perubahan pathname agar TIDAK loop saat user mengubah
+ * filter di halaman yang sama. URL selalu menang (key yang sudah ada di URL
+ * tidak ditimpa).
+ */
+export declare function useUrlHydration({ enabled, snapshotKeys, perPageKey, readSnapshot, readPerPage }: UseUrlHydrationOptions): void;
+export {};

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

@@ -1,5 +1,6 @@
 export { FilterBar } from './FilterBar';
 export { useFilterBarApiParams, type UseFilterBarApiParamsOptions, type FilterBarApiParams } from './hooks/useFilterBarApiParams';
+export { useFilterBarControls, type UseFilterBarControlsOptions, type FilterBarControls } from './hooks/useFilterBarControls';
 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

@@ -132,6 +132,12 @@ export interface FilterBarProps {
     perPageKey?: string;
     /** Page-size choices. Default `[10, 25, 50, 100]`. */
     pageSizeOptions?: number[];
+    /**
+     * Initial page size used when the URL (and the persisted preference under
+     * `savedViews.scopeId`) is empty. Defaults to `pageSizeOptions[0]`, so
+     * `pageSizeOptions={[25, 50, 100]}` naturally defaults to 25.
+     */
+    defaultPerPage?: number;
     showPagination?: boolean;
     showResultCount?: boolean;
     /** Show the rows-per-page selector. Default `true`. */
@@ -146,15 +152,24 @@ export interface FilterBarProps {
      * `onColumnsChange`. `frozenKey` & field lain di luar order/hidden diabaikan.
      */
     columnsState?: Partial<ColumnPrefState>;
-    /** Enable named saved views. `scopeId` namespaces persisted data per table. */
+    /**
+     * Namespace persistensi per tabel — dipakai untuk column prefs, last-filter
+     * snapshot, perPage, & saved views. WAJIB diisi agar fitur persist aktif.
+     * Boleh juga lewat `savedViews.scopeId` (kompatibilitas lama); kalau dua-duanya
+     * ada, prop top-level ini menang.
+     */
+    scopeId?: string;
+    /**
+     * Saved views. `enabled` mengontrol tampil/sembunyinya tombol Saved Views.
+     * `scopeId` di sini opsional & deprecated — pakai prop `scopeId` top-level.
+     */
     savedViews?: {
         enabled?: boolean;
-        scopeId: string;
+        scopeId?: string;
     };
     /**
      * Auto-restore the last applied filter state when the URL has no filter
-     * params (e.g. link-based back navigation). Requires `savedViews.scopeId`.
-     * Default `true`.
+     * params (e.g. link-based back navigation). Requires `scopeId`. Default `true`.
      */
     persistLastState?: boolean;
     /** Persistence adapter (default: localStorage via @starasia/storage). */

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

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

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

@@ -1,4 +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;
+export declare const TableLayout: <T>({ columns, data, getRowKey, size, resizable, widthStorageKey, columnState, onColumnStateChange, columnMenu, sort, defaultSort, onSortChange, height, mobileLayout, mobileBreakpoint, groupSeparator, summary, emptyState, rowActions, }: TableLayoutProps<T>) => React.JSX.Element;

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

@@ -1,4 +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';
+export type { TableLayoutProps, TableLayoutColumn, TableLayoutAlign, TableLayoutColumnState, TableLayoutCellProps, TableLayoutSort, TableLayoutSortDirection, TableLayoutRowAction } from './types';

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

@@ -1,6 +1,32 @@
 import { ReactNode } from 'react';
 import { IconName } from '@starasia/icon';
 
+export interface TableLayoutRowAction<T> {
+    key: string;
+    /** icon dari @starasia/icon (opsional) */
+    icon?: IconName;
+    /** teks tombol (mobile + kebab) + aria-label */
+    label: string;
+    /** Tooltip saat hover tombol. Default tidak ada tooltip — harus diset eksplisit. */
+    tooltip?: string;
+    /** Tampilkan teks label di sebelah icon (default false = icon only) */
+    showLabel?: boolean;
+    onClick: (row: T, index: number) => void;
+    /** return true → action tidak tampil untuk row ini */
+    hidden?: (row: T) => boolean;
+    /** return true → tombol dinonaktifkan */
+    disabled?: (row: T) => boolean;
+    /**
+     * Variant Button dari @starasia/button (default 'tertiary').
+     * Gunakan 'tertiary' untuk aksi normal, sesuaikan untuk aksi utama/destruktif.
+     */
+    variant?: 'primary' | 'secondary' | 'tertiary' | 'outline' | 'link';
+    /**
+     * Tone/warna Button dari @starasia/button.
+     * Contoh: 'error' untuk hapus, 'success' untuk approve.
+     */
+    tone?: 'brand' | 'error' | 'success' | 'info' | 'neutral' | 'warning';
+}
 export type TableLayoutAlign = 'left' | 'center' | 'right';
 export type TableLayoutSortDirection = 'asc' | 'desc';
 export interface TableLayoutSort {
@@ -88,6 +114,13 @@ export interface TableLayoutProps<T> {
     columns: TableLayoutColumn<T>[];
     /** baris data (wajib) */
     data: T[];
+    /**
+     * Action buttons per baris — muncul sebagai overlay di atas row saat hover
+     * (Desktop/pointer: tersembunyi, fade-in saat hover · Touch: selalu terlihat).
+     * ≤ 5 visible action → icon buttons inline.
+     * > 5 visible action → kebab menu ⋮.
+     */
+    rowActions?: TableLayoutRowAction<T>[];
     /** key unik per row; default pakai index */
     getRowKey?: (row: T, index: number) => string | number;
     /** padding scale, diteruskan ke primitif Table (default 'md') */