@starasia/admin 8.0.2 → 8.0.3

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

@@ -0,0 +1,14 @@
+import { default as React } from 'react';
+import { FilterBarProps } from './types';
+
+/**
+ * FilterBar — horizontal data-table toolbar.
+ *
+ * All-in-one: reads/writes filter + pagination state directly from the URL
+ * (via `useRouteInfo`), persists saved views & column prefs through a swappable
+ * storage adapter. Successor to `AdvanceFilterBar`.
+ *
+ * Layout — left: Add Filter + pills + Reset; right: result count + page size +
+ * pager + search + saved views + columns.
+ */
+export declare const FilterBar: React.FC<FilterBarProps>;

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

@@ -0,0 +1,15 @@
+import { default as React } from 'react';
+import { FilterFieldConfig } from '../types';
+
+interface AddFilterMenuProps {
+    configs: FilterFieldConfig[];
+    activeKeys: string[];
+    onToggle: (key: string) => void;
+    hasActiveFilter?: boolean;
+}
+/**
+ * The ⚙ Filter button → a menu listing the filter catalog. Selecting an item
+ * toggles its pill on the bar (the menu stays open for multi-add).
+ */
+export declare const AddFilterMenu: React.FC<AddFilterMenuProps>;
+export {};

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

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+import { OrderedColumn } from '../hooks/useColumnPrefs';
+
+interface ColumnCustomizerProps {
+    columns: OrderedColumn[];
+    allVisible: boolean;
+    onToggle: (key: string) => void;
+    onReorder: (from: number, to: number) => void;
+    onSetAllHidden: (hidden: boolean) => void;
+}
+/**
+ * "Customize Column Table" panel — visibility toggles + hand-rolled HTML5
+ * drag-reorder (zero-dependency). Keyboard fallback: focus a row's drag handle
+ * and use ↑/↓ to move it.
+ */
+export declare const ColumnCustomizer: React.FC<ColumnCustomizerProps>;
+export {};

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

@@ -0,0 +1,14 @@
+import { default as React } from 'react';
+import { FilterFieldConfig } from '../types';
+
+interface FilterPillsProps {
+    activeKeys: string[];
+    configByKey: Record<string, FilterFieldConfig>;
+    getValue: (field: FilterFieldConfig) => unknown;
+    setValue: (field: FilterFieldConfig, value: unknown) => void;
+    clearValue: (key: string) => void;
+    removeFilter: (key: string) => void;
+}
+/** Renders the active filter pills, dispatching each to its editor by type. */
+export declare const FilterPills: React.FC<FilterPillsProps>;
+export {};

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

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+import { Pagination as PaginationMeta } from '../../TableSection/types';
+
+interface PaginationClusterProps {
+    pagination?: PaginationMeta;
+    pageKey?: string;
+    perPageKey?: string;
+    pageSizeOptions?: number[];
+    defaultPerPage?: number;
+    showResultCount?: boolean;
+    showPagination?: boolean;
+}
+/**
+ * Right-cluster pagination controls — mirrors `TableSection/Footer` semantics
+ * (URL `?page`/`?perPage`, same range math), laid out per the FilterBar Figma:
+ * result count → page-size (Menu) → pager.
+ */
+export declare const PaginationCluster: React.FC<PaginationClusterProps>;
+export {};

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

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+import { SavedView } from '../types';
+
+interface SavedViewsProps {
+    views: SavedView[];
+    onApply: (view: SavedView) => void;
+    onDelete: (id: string) => void;
+    onSave: (name: string) => void;
+}
+/** Saved-views menu: apply / delete existing views, and save the current one. */
+export declare const SavedViews: React.FC<SavedViewsProps>;
+export {};

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

@@ -0,0 +1,21 @@
+import { default as React } from 'react';
+
+interface SearchBoxProps {
+    searchKey?: string;
+    filterKey?: string;
+    pageKey?: string;
+    placeholder?: string;
+    /** Single-key shortcut that focuses search. Default `/`. */
+    shortcut?: string;
+}
+/**
+ * Search control that animates open from an icon button. The input is always
+ * mounted so the wrapper can transition its width smoothly; the search icon
+ * lives in the input's `leftIcon` while expanded (no separate icon then).
+ *
+ * Behavior: clicking the icon (or the `/` shortcut) expands + focuses. On blur,
+ * it collapses **only when empty** — a non-empty search stays expanded. The
+ * term is written into the `?filter` blob (debounced, also resets the page).
+ */
+export declare const SearchBox: React.FC<SearchBoxProps>;
+export {};

package/dist/components/FilterBar/components/pills/DatePill.d.ts

@@ -0,0 +1,15 @@
+import { default as React } from 'react';
+import { DateFilterField, DateRangeFilterField } from '../../types';
+
+interface DatePillProps {
+    field: DateFilterField | DateRangeFilterField;
+    value: Date | {
+        from: Date;
+        to: Date;
+    } | undefined;
+    onChange: (v: unknown) => void;
+    onClear: () => void;
+}
+/** Date / date-range pill backed by `StarasiaDate` (input-trigger mode). */
+export declare const DatePill: React.FC<DatePillProps>;
+export {};

package/dist/components/FilterBar/components/pills/SelectPill.d.ts

@@ -0,0 +1,21 @@
+import { default as React } from 'react';
+import { SelectFilterField, PersonFilterField } from '../../types';
+
+interface SelectPillProps {
+    field: SelectFilterField | PersonFilterField;
+    value: {
+        label: string;
+        value: string;
+    }[];
+    onChange: (v: {
+        label: string;
+        value: string;
+    }[]) => void;
+}
+/**
+ * Select pill — covers `dropdown` (single), `dropdown-multiple`, `radio`
+ * (single) and `person` (searchable multi). Backed by `@starasia/dropdown`,
+ * which renders the checkbox list / search seen in the Figma "Default Filter".
+ */
+export declare const SelectPill: React.FC<SelectPillProps>;
+export {};

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

@@ -0,0 +1,28 @@
+import { ColumnConfig, ColumnPrefState, FilterStorageAdapter } from '../types';
+
+interface UseColumnPrefsOptions {
+    columns: ColumnConfig[];
+    scopeId?: string;
+    storage: FilterStorageAdapter;
+    onColumnsChange?: (state: ColumnPrefState) => void;
+}
+export interface OrderedColumn extends ColumnConfig {
+    visible: boolean;
+}
+/**
+ * Column visibility + ordering state for the Customize Column panel.
+ * Persists to the storage adapter (namespaced by `scopeId`) and notifies the
+ * 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): {
+    state: ColumnPrefState;
+    orderedColumns: OrderedColumn[];
+    allVisible: boolean;
+    toggleVisibility: (key: string) => void;
+    reorder: (from: number, to: number) => void;
+    setAllHidden: (hidden: boolean) => void;
+    reset: () => void;
+    applyState: (next: ColumnPrefState) => void;
+};
+export {};

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

@@ -0,0 +1,31 @@
+import { FilterFieldConfig } from '../types';
+
+interface UseFilterUrlOptions {
+    configs: FilterFieldConfig[];
+    filterKey?: string;
+    activeFilterKey?: string;
+    pageKey?: string;
+    searchKey?: string;
+}
+/**
+ * Single source of truth for filter state in the URL.
+ *
+ * - Active pills: `?filters=key1,key2` (comma list), unioned with any keys
+ *   already present in the value blob (so a shared/saved URL restores pills).
+ * - Values: `?filter={...}` JSON-blob via the reused `AdvanceFilterBar/utils`.
+ */
+export declare function useFilterUrl({ configs, filterKey, activeFilterKey, pageKey, searchKey }: UseFilterUrlOptions): {
+    activeKeys: string[];
+    configByKey: {
+        [k: string]: FilterFieldConfig;
+    };
+    hasActiveFilter: boolean;
+    addFilter: (key: string) => void;
+    removeFilter: (key: string) => void;
+    toggleFilter: (key: string) => void;
+    getValue: (field: FilterFieldConfig) => unknown;
+    setValue: (field: FilterFieldConfig, value: unknown) => void;
+    clearValue: (key: string) => void;
+    clearAll: () => void;
+};
+export {};

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

@@ -0,0 +1,26 @@
+import { ColumnPrefState, FilterStorageAdapter, SavedView } from '../types';
+
+interface UseSavedViewsOptions {
+    scopeId?: string;
+    storage: FilterStorageAdapter;
+    /** URL params captured into a view snapshot (filters, filter blob, perPage…). */
+    snapshotKeys: string[];
+    pageKey?: string;
+    /** Capture the current column prefs at save time. */
+    getColumns?: () => ColumnPrefState;
+    /** Apply column prefs when a view is restored. */
+    applyColumns?: (state: ColumnPrefState) => void;
+}
+/**
+ * Named saved views = persisted snapshots of the relevant URL params (+ column
+ * prefs). Applying a view hydrates the URL (and columns), so the rest of the
+ * bar reacts automatically.
+ */
+export declare function useSavedViews({ scopeId, storage, snapshotKeys, pageKey, getColumns, applyColumns }: UseSavedViewsOptions): {
+    enabled: boolean;
+    views: SavedView[];
+    saveView: (name: string) => void;
+    deleteView: (id: string) => void;
+    applyView: (view: SavedView) => void;
+};
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * Focus/open search when a single-key shortcut (default `/`) is pressed —
+ * ignored while the user is typing in another field.
+ */
+export declare function useSearchShortcut(key: string, onTrigger: () => void, enabled?: boolean): void;

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

@@ -0,0 +1,3 @@
+export { FilterBar } from './FilterBar';
+export { localStorageAdapter, storageKeys } from './utils/storage-adapter';
+export type { FilterBarProps, FilterFieldConfig, FilterFieldType, SelectFilterField, PersonFilterField, DateFilterField, DateRangeFilterField, ColumnConfig, ColumnPrefState, SavedView, FilterStorageAdapter } from './types';

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

@@ -0,0 +1,124 @@
+import { ReactNode } from 'react';
+import { Pagination } from '../TableSection/types';
+
+/**
+ * Filter field catalog.
+ *
+ * `type` mirrors the `InputType` union consumed by `AdvanceFilterBar/utils`
+ * (`handleChangeFilter`, `getValuesFilter`, …) so the JSON-blob URL encoding
+ * (`?filter={...}`) is reused as-is. `key` is the param name inside that blob.
+ */
+export type FilterFieldType = 'date' | 'date-range' | 'dropdown' | 'dropdown-multiple' | 'radio' | 'person';
+interface BaseFilterField {
+    /** Stable key — used as the field name inside the `?filter` blob. */
+    key: string;
+    /** Label shown in the Add Filter menu and on the active pill. */
+    label: string;
+    /** Optional leading icon (IconName via <Icon/> or any node). */
+    icon?: ReactNode;
+    /** When true the pill cannot be removed once added. */
+    locked?: boolean;
+}
+export interface SelectFilterField extends BaseFilterField {
+    type: 'dropdown' | 'dropdown-multiple' | 'radio';
+    options: {
+        label: string;
+        value: string;
+    }[];
+    searchable?: boolean;
+    isLoading?: boolean;
+    onSearch?: (q: string) => void;
+}
+export interface PersonFilterField extends BaseFilterField {
+    type: 'person';
+    options: {
+        label: string;
+        value: string;
+        description?: string;
+        avatar?: ReactNode;
+    }[];
+    searchable?: boolean;
+    isLoading?: boolean;
+    onSearch?: (q: string) => void;
+}
+export interface DateFilterField extends BaseFilterField {
+    type: 'date';
+    mode?: 'days' | 'months' | 'years';
+}
+export interface DateRangeFilterField extends BaseFilterField {
+    type: 'date-range';
+}
+export type FilterFieldConfig = SelectFilterField | PersonFilterField | DateFilterField | DateRangeFilterField;
+/** A single column entry fed to the Customize Column panel. */
+export interface ColumnConfig {
+    key: string;
+    title: string;
+    icon?: ReactNode;
+    /** Locked columns can't be hidden or reordered. */
+    locked?: boolean;
+}
+/** Visibility + ordering state emitted by the Customize Column panel. */
+export interface ColumnPrefState {
+    /** Ordered column keys (full order, including hidden). */
+    order: string[];
+    /** Keys that are currently hidden. */
+    hidden: string[];
+}
+/** A named, persisted snapshot of filter + column state. */
+export interface SavedView {
+    id: string;
+    name: string;
+    /** Snapshot of the relevant URL params (filters, filter, perPage, sort). */
+    query: Record<string, string>;
+    columns?: ColumnPrefState;
+    createdAt: number;
+}
+/**
+ * Pluggable persistence for saved views & column prefs.
+ * Default impl is localStorage-backed (`localStorageAdapter`); swap for a
+ * backend-backed adapter via the FilterBar `storage` prop.
+ */
+export interface FilterStorageAdapter {
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T): void;
+    remove(key: string): void;
+}
+export interface FilterBarProps {
+    /** Catalog of filters offered in the Add Filter menu. */
+    filterConfigs?: FilterFieldConfig[];
+    /** URL param holding the JSON-blob of filter values. Default `'filter'`. */
+    filterKey?: string;
+    /** URL param holding the comma list of active pill keys. Default `'filters'`. */
+    activeFilterKey?: string;
+    /** URL param for the current page. Default `'page'`. */
+    pageKey?: string;
+    /** Show the expandable search control. */
+    searchable?: boolean;
+    /** Field name for search (inside the `?filter` blob). Default `'q'`. */
+    searchKey?: string;
+    searchPlaceholder?: string;
+    /** Single-key shortcut that focuses search. Default `'/'`. */
+    searchShortcut?: string;
+    /** Pagination meta from the API (drives result count + pager). */
+    pagination?: Pagination;
+    /** URL param for page size. Default `'perPage'`. */
+    perPageKey?: string;
+    /** Page-size choices. Default `[10, 25, 50, 100]`. */
+    pageSizeOptions?: number[];
+    showPagination?: boolean;
+    showResultCount?: boolean;
+    /** Columns shown in the Customize Column panel. */
+    columns?: ColumnConfig[];
+    /** Emitted when visibility/order changes — consumer applies to its table. */
+    onColumnsChange?: (state: ColumnPrefState) => void;
+    /** Enable named saved views. `scopeId` namespaces persisted data per table. */
+    savedViews?: {
+        enabled?: boolean;
+        scopeId: string;
+    };
+    /** Persistence adapter (default: localStorage via @starasia/storage). */
+    storage?: FilterStorageAdapter;
+    /** Called after a full reset (clears filters + search). */
+    onReset?: () => void;
+}
+export {};

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

@@ -0,0 +1,15 @@
+import { FilterStorageAdapter } from '../types';
+
+/**
+ * Default persistence adapter backed by `@starasia/storage` (SecureStorage →
+ * localStorage). Saved views and column prefs flow through this.
+ *
+ * Swap for a backend-backed adapter by passing a custom `FilterStorageAdapter`
+ * to the FilterBar `storage` prop — the rest of the component is agnostic.
+ */
+export declare const localStorageAdapter: FilterStorageAdapter;
+/** Namespaced storage keys so multiple tables don't collide. */
+export declare const storageKeys: {
+    columns: (scopeId: string) => string;
+    savedViews: (scopeId: string) => string;
+};

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

@@ -1,6 +1,6 @@
 import { BoxProps } from '@starasia/box';
 import { PropsWithChildren, ReactNode, default as React } from 'react';
-import { IBadges } from '@starasia/badges';
+import { IBadge } from '@starasia/badges';
 import { IconName } from '@starasia/icon/dist/types';
 import { ButtonProps } from '@starasia/button/dist/types';
 
@@ -24,9 +24,9 @@ interface ActionProps {
 interface SubHeaderProps {
     /** Content of this header row. */
     content: ReactNode;
-    /** CSS `order` for positioning this row within the page column (header / subHeaders / body). Negative values move it above the main header. */
+    /** CSS `order` within the header region. Negative values render this row above the main header; positive values below it (but always above the page body). */
     order?: number;
-    /** Show the subtle bottom border (same style as the main header). Defaults to `true`. */
+    /** Show the subtle bottom border (same style as the main header). Defaults to `true`. When `false`, the row's bottom padding is dropped too so the stack stays tight. */
     borderBottom?: boolean;
 }
 export interface PageLayoutProps extends PropsWithChildren {
@@ -44,7 +44,7 @@ export interface PageLayoutProps extends PropsWithChildren {
     subHeaders?: SubHeaderProps[];
     backButton?: BackButtonProps;
     action?: ActionProps[] | React.ReactNode;
-    titleTagProps?: Omit<IBadges, "text" | "border" | "size">;
+    titleTagProps?: Omit<IBadge, "text" | "border" | "size">;
     containerProps?: Omit<BoxProps, "variant" | "gap">;
     headerProps?: Omit<BoxProps, "gap">;
 }

package/dist/components/index.d.ts

@@ -11,6 +11,7 @@ export * from './Pressable';
 export * from './RightDrawer';
 export * from './Section';
 export * from './AdvanceFilterBar';
+export * from './FilterBar';
 export * from './TableSection';
 export * from './EachUtils';
 export * from './DecisionWrapper';