@gridui/data-explorer 1.0.3 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,7 +3,22 @@
3
3
  Dashboard family. Public API: `DataExplorer`, `DataExplorerColumn`, `DataExplorerFilter`, `DataExplorerProps`, `DataExplorerRow`, `DataExplorerState`, `DataExplorerValue`.
4
4
 
5
5
  Import components from `@gridui/data-explorer` and load `@gridui/data-explorer/styles.css` after Theme.
6
- Load styles for any composed dependency used by this family. Applications own routes, labels, state persistence, and branding.
6
+ Load the complete family stylesheet set in dependency order:
7
+ ```css
8
+ @import "@gridui/theme/styles.css";
9
+ @import "@gridui/button/styles.css";
10
+ @import "@gridui/form/styles.css";
11
+ @import "@gridui/choice/styles.css";
12
+ @import "@gridui/grid/styles.css";
13
+ @import "@gridui/overlay/styles.css";
14
+ @import "@gridui/input/styles.css";
15
+ @import "@gridui/dropdown-menu/styles.css";
16
+ @import "@gridui/select/styles.css";
17
+ @import "@gridui/table/styles.css";
18
+ @import "@gridui/data-explorer/styles.css";
19
+ ```
20
+
21
+ Applications own routes, labels, state persistence, and branding.
7
22
 
8
23
  See [component ownership](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/docs/component-ownership.md) and [release history](https://github.com/sudo-ui/GridUI-React-Monorepo/tree/main/packages-dashboard/data-explorer/.changeset/history).
9
24
 
@@ -30,3 +45,41 @@ separate Split regions, so their separators also belong to Grid.
30
45
  Toolbar fields use a single flex sizing declaration with a 10rem basis and wrap
31
46
  to the available container width. Loading other family styles afterward does not
32
47
  reset that basis or compress Select labels into character-wide columns.
48
+
49
+ ## Optional controlled features
50
+
51
+ Existing search, sorting, single filtering, pagination and page selection keep
52
+ their defaults. New features are opt-in and use the same native table and styles.
53
+
54
+ - `columnSettings: { hiddenKeys, onHiddenKeysChange, label }` adds a native
55
+ disclosure with column visibility checkboxes. The last visible column cannot
56
+ be hidden. Hidden columns remain searchable and sortable because the full
57
+ declared schema still owns query semantics. Omitting this config shows all columns.
58
+ Stable column identities preserve state in surviving custom cells when other
59
+ columns are hidden or reordered; a hidden column unmounts its own cells.
60
+ - `columnSizing: { widths, onWidthsChange, resizeLabel }` adds resize handles to
61
+ headers. Each handle supports pointer capture, RTL-aware arrow keys (10px,
62
+ Shift for 50px), Home/End, and separator value semantics. Pointer cancellation, unexpected capture loss, or becoming busy
63
+ restores the starting width. IME key processing never changes a column width. Applications persist the controlled width map.
64
+ - Columns accept pixel `width`, `minWidth`, `maxWidth` and logical `sticky`
65
+ (`start` or `end`). Defaults are 200px, 80px and 1200px. Explicit widths or
66
+ resizing use fixed table geometry; pinned offsets include preceding pinned
67
+ columns and recompute after hiding or resizing. Other tables retain fluid sizing.
68
+ - `details: { expandedIds, onExpandedIdsChange, render, columnLabel, expandLabel,
69
+ collapseLabel }` adds expansion buttons and full-width detail rows. IDs refer
70
+ to records, so selection/expansion survives sorting and pagination. Applications
71
+ own detail requests, loading content and error recovery.
72
+ - `filtering: { definitions, labels }` adds multiple AND conditions in
73
+ `state.filters`. Definitions specify `key`, `label`, `type` (`text`, `number`,
74
+ `enum`) and optional enum options. Labels include `add`, `remove(index)`,
75
+ `field`, `operator`, `value` and every supported operator label. Conditions
76
+ have a unique `id`, field `key`, `operator` and optional scalar `value`.
77
+ Operators are `contains`, `equals`, `not-equals`, `greater-than`, `less-than`,
78
+ and `empty`. Numeric comparisons require finite numbers; equals is exact,
79
+ contains is normalized and case-insensitive, and empty matches null/missing/
80
+ empty text. An incomplete value is ignored until entered. Changing filters
81
+ returns to page one. This is an in-memory filter editor, not a query language
82
+ or a backend request planner.
83
+
84
+ All optional feature labels are caller-owned. Remote paging, authorization,
85
+ query serialization and persistence remain application responsibilities.
@@ -0,0 +1,16 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Data Explorer
4
+ * @namespace DataExplorer
5
+ * @description Column Resize Handle
6
+ */
7
+ import { type DataExplorerColumn } from "./model";
8
+ import { type FC } from "react";
9
+ export type ColumnResizeHandleProps = {
10
+ readonly column: DataExplorerColumn;
11
+ readonly width: number;
12
+ readonly label: string;
13
+ readonly disabled: boolean;
14
+ readonly onChange: (width: number) => void;
15
+ };
16
+ export declare const ColumnResizeHandle: FC<ColumnResizeHandleProps>;
@@ -4,6 +4,7 @@
4
4
  * @namespace DataExplorer
5
5
  * @description Data Explorer
6
6
  */
7
+ import type { DataExplorerColumnSettings, DataExplorerColumnSizing, DataExplorerDetails, DataExplorerFiltering } from "./features";
7
8
  import { type DataExplorerColumn, type DataExplorerFilter, type DataExplorerRow, type DataExplorerState, type DataExplorerValue } from "./model";
8
9
  import { type ComponentPropsWithRef, type FC, type ReactNode } from "react";
9
10
  export type DataExplorerProps = Omit<ComponentPropsWithRef<"section">, "children"> & {
@@ -12,6 +13,10 @@ export type DataExplorerProps = Omit<ComponentPropsWithRef<"section">, "children
12
13
  readonly state: DataExplorerState;
13
14
  readonly onStateChange: (state: DataExplorerState) => void;
14
15
  readonly filter?: DataExplorerFilter;
16
+ readonly columnSettings?: DataExplorerColumnSettings;
17
+ readonly columnSizing?: DataExplorerColumnSizing;
18
+ readonly details?: DataExplorerDetails;
19
+ readonly filtering?: DataExplorerFiltering;
15
20
  readonly pageSize?: number;
16
21
  readonly selectedIds?: readonly string[];
17
22
  readonly onSelectionChange?: (ids: readonly string[]) => void;
@@ -0,0 +1,37 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Data Explorer
4
+ * @namespace DataExplorer
5
+ * @description Features
6
+ */
7
+ import type { DataExplorerColumn, DataExplorerFilterDefinition, DataExplorerFilterOperator, DataExplorerRow } from "./model";
8
+ import type { ReactNode } from "react";
9
+ export type DataExplorerColumnSettings = {
10
+ readonly hiddenKeys: readonly string[];
11
+ readonly onHiddenKeysChange: (keys: readonly string[]) => void;
12
+ readonly label: string;
13
+ };
14
+ export type DataExplorerColumnSizing = {
15
+ readonly widths: Readonly<Record<string, number>>;
16
+ readonly onWidthsChange: (widths: Readonly<Record<string, number>>) => void;
17
+ readonly resizeLabel: (column: DataExplorerColumn) => string;
18
+ };
19
+ export type DataExplorerDetails = {
20
+ readonly expandedIds: readonly string[];
21
+ readonly onExpandedIdsChange: (ids: readonly string[]) => void;
22
+ readonly render: (row: DataExplorerRow) => ReactNode;
23
+ readonly columnLabel: string;
24
+ readonly expandLabel: (row: DataExplorerRow) => string;
25
+ readonly collapseLabel: (row: DataExplorerRow) => string;
26
+ };
27
+ export type DataExplorerFiltering = {
28
+ readonly definitions: readonly DataExplorerFilterDefinition[];
29
+ readonly labels: {
30
+ readonly add: string;
31
+ readonly remove: (index: number) => string;
32
+ readonly field: string;
33
+ readonly operator: string;
34
+ readonly value: string;
35
+ readonly operators: Readonly<Record<DataExplorerFilterOperator, string>>;
36
+ };
37
+ };
@@ -0,0 +1,16 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Data Explorer
4
+ * @namespace DataExplorer
5
+ * @description Filter Editor
6
+ */
7
+ import type { DataExplorerFiltering } from "./features";
8
+ import type { DataExplorerCondition } from "./model";
9
+ import { type FC } from "react";
10
+ export type FilterEditorProps = {
11
+ readonly filtering: DataExplorerFiltering;
12
+ readonly conditions: readonly DataExplorerCondition[];
13
+ readonly disabled: boolean;
14
+ readonly onChange: (conditions: readonly DataExplorerCondition[]) => void;
15
+ };
16
+ export declare const FilterEditor: FC<FilterEditorProps>;
@@ -13,6 +13,10 @@ export type DataExplorerColumn = {
13
13
  readonly key: string;
14
14
  readonly label: string;
15
15
  readonly numeric?: boolean;
16
+ readonly width?: number;
17
+ readonly minWidth?: number;
18
+ readonly maxWidth?: number;
19
+ readonly sticky?: "start" | "end";
16
20
  };
17
21
  export type DataExplorerState = {
18
22
  readonly query: string;
@@ -22,6 +26,7 @@ export type DataExplorerState = {
22
26
  readonly direction: "ascending" | "descending";
23
27
  } | null;
24
28
  readonly page: number;
29
+ readonly filters?: readonly DataExplorerCondition[];
25
30
  };
26
31
  export type DataExplorerFilter = {
27
32
  readonly key: string;
@@ -38,3 +43,21 @@ export declare const selectExplorerRows: (rows: readonly DataExplorerRow[], colu
38
43
  pageCount: number;
39
44
  };
40
45
  export declare const selectExplorerPage: (selectedIds: readonly string[], pageIds: readonly string[], checked: boolean) => string[];
46
+ export type DataExplorerFilterOperator = "contains" | "equals" | "not-equals" | "greater-than" | "less-than" | "empty";
47
+ export type DataExplorerCondition = {
48
+ readonly id: string;
49
+ readonly key: string;
50
+ readonly operator: DataExplorerFilterOperator;
51
+ readonly value?: string | number;
52
+ };
53
+ export type DataExplorerFilterDefinition = {
54
+ readonly key: string;
55
+ readonly label: string;
56
+ readonly type: "text" | "number" | "enum";
57
+ readonly options?: readonly {
58
+ readonly value: string;
59
+ readonly label: string;
60
+ }[];
61
+ };
62
+ export declare const matchesExplorerCondition: (row: DataExplorerRow, condition: DataExplorerCondition) => boolean;
63
+ export declare const resolveExplorerWidth: (column: DataExplorerColumn, width?: number) => number;
package/dist/index.d.ts CHANGED
@@ -6,8 +6,10 @@
6
6
  */
7
7
  export type { DataExplorerProps } from "./data-explorer/data-explorer";
8
8
  export { DataExplorer } from "./data-explorer/data-explorer";
9
+ export type { DataExplorerColumnSettings, DataExplorerColumnSizing, DataExplorerDetails, DataExplorerFiltering } from "./data-explorer/features";
9
10
  export type { DataExplorerColumn } from "./data-explorer/model";
10
11
  export type { DataExplorerFilter } from "./data-explorer/model";
11
12
  export type { DataExplorerRow } from "./data-explorer/model";
12
13
  export type { DataExplorerState } from "./data-explorer/model";
13
14
  export type { DataExplorerValue } from "./data-explorer/model";
15
+ export type { DataExplorerCondition, DataExplorerFilterDefinition, DataExplorerFilterOperator } from "./data-explorer/model";