@gridui/data-explorer 1.3.0 → 1.4.0

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.
Files changed (39) hide show
  1. package/README.md +66 -1
  2. package/dist/data-explorer/data-explorer.d.ts +1 -6
  3. package/dist/data-explorer-bulk-actions/data-explorer-bulk-actions.d.ts +4 -2
  4. package/dist/data-explorer-column-visibility/data-explorer-column-visibility.d.ts +5 -0
  5. package/dist/data-explorer-filter-control/data-explorer-filter-control.d.ts +5 -0
  6. package/dist/data-explorer-filters/data-explorer-filters.d.ts +5 -0
  7. package/dist/data-explorer-pagination/data-explorer-pagination.d.ts +4 -2
  8. package/dist/data-explorer-provider/data-explorer-provider.d.ts +7 -0
  9. package/dist/data-explorer-search/data-explorer-search.d.ts +5 -0
  10. package/dist/data-explorer-sort/data-explorer-sort.d.ts +5 -0
  11. package/dist/data-explorer-table/data-explorer-table.d.ts +4 -2
  12. package/dist/data-explorer-toolbar/data-explorer-toolbar.d.ts +5 -9
  13. package/dist/data-explorer-view/data-explorer-view.d.ts +6 -0
  14. package/dist/index.d.ts +17 -0
  15. package/dist/index.js +314 -372
  16. package/dist/index.js.map +4 -4
  17. package/dist/shared/controller.d.ts +26 -0
  18. package/dist/shared/explorer-context.d.ts +126 -77
  19. package/dist/shared/explorer-options.d.ts +22 -18
  20. package/dist/shared/labels.d.ts +2 -0
  21. package/dist/styles.css +1 -0
  22. package/docs/catalog.json +98 -1
  23. package/docs/reference/README.md +7 -0
  24. package/docs/reference/data-explorer-bulk-actions.md +4 -0
  25. package/docs/reference/data-explorer-column-visibility.md +27 -0
  26. package/docs/reference/data-explorer-filter-control.md +27 -0
  27. package/docs/reference/data-explorer-filters.md +23 -0
  28. package/docs/reference/data-explorer-pagination.md +4 -0
  29. package/docs/reference/data-explorer-provider.md +97 -0
  30. package/docs/reference/data-explorer-search.md +27 -0
  31. package/docs/reference/data-explorer-sort.md +27 -0
  32. package/docs/reference/data-explorer-table.md +4 -0
  33. package/docs/reference/data-explorer-toolbar.md +6 -0
  34. package/docs/reference/data-explorer-view.md +59 -0
  35. package/docs/reference/data-explorer.md +1 -1
  36. package/package.json +13 -13
  37. /package/dist/{data-explorer-toolbar → data-explorer-filters}/filter-editor.d.ts +0 -0
  38. /package/dist/{data-explorer → data-explorer-view}/style.d.ts +0 -0
  39. /package/dist/{data-explorer-toolbar/style.d.ts → shared/label-style.d.ts} +0 -0
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @gridui/data-explorer
2
2
 
3
- Data family. Public API: `DataExplorer`, `DataExplorerToolbar`, `DataExplorerBulkActions`, `DataExplorerTable`, `DataExplorerPagination`, `DataExplorerColumn`, `DataExplorerFilter`, `DataExplorerProps`, `DataExplorerRow`, `DataExplorerState`, `DataExplorerValue`.
3
+ Data family. Public API: `DataExplorerProvider`, `DataExplorerView`, `useDataExplorer`, `DataExplorerSearch`, `DataExplorerFilterControl`, `DataExplorerSort`, `DataExplorerColumnVisibility`, `DataExplorerFilters`, `DataExplorer`, `DataExplorerToolbar`, `DataExplorerBulkActions`, `DataExplorerTable`, `DataExplorerPagination`, `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
6
  Load the complete family stylesheet set in dependency order:
@@ -90,3 +90,68 @@ query serialization and persistence remain application responsibilities.
90
90
  DataExplorerTable accepts DataTable's independent rowLines, columnLines, density,
91
91
  headerSurface, rowHeaderSurface and striped presentation options. Controlled
92
92
  selectedIds also drive row highlighting; sorting and pagination keep record IDs.
93
+
94
+
95
+ ## Compose controls and layout independently
96
+
97
+ `DataExplorer` remains the default composition with its existing required `labels`.
98
+ For a custom arrangement, `DataExplorerProvider` owns the same controlled local
99
+ state without rendering an element or requiring labels for unused features.
100
+ `DataExplorerView` is an optional section and Grid frame; use application markup
101
+ instead when that frame is not needed.
102
+
103
+ ```tsx
104
+ <DataExplorerProvider
105
+ rows={rows}
106
+ columns={columns}
107
+ state={state}
108
+ onStateChange={setState}
109
+ >
110
+ <DataExplorerView label="Projects">
111
+ <DataExplorerToolbar>
112
+ <DataExplorerSearch label="Find projects" />
113
+ <ProjectSummary />
114
+ </DataExplorerToolbar>
115
+ <DataExplorerTable labels={{ table: "Projects", empty: "No projects" }} />
116
+ <DataExplorerPagination labels={{
117
+ previous: "Previous", next: "Next",
118
+ page: (page, pages, total) => `${page} / ${pages}, ${total} projects`,
119
+ }} />
120
+ </DataExplorerView>
121
+ </DataExplorerProvider>
122
+ ```
123
+
124
+ `useDataExplorer()` supplies the accepted `state`, `busy`, `columns`,
125
+ `visibleColumns`, paged `view`, valid `selectedRowIds`/`selectedRowIdSet`,
126
+ `pageIds` and `selectedPageCount`. Custom controls use `setQuery`,
127
+ `setFilterValue`, `setSort` and `setFilters` to reset paging consistently.
128
+ `updateState` applies a partial state change; `updateSelection` removes missing
129
+ and duplicate IDs. All commands ignore changes while busy, and controlled
130
+ consumers can reject requests. The hook requires a provider or `DataExplorer`.
131
+
132
+ ```tsx
133
+ function ProjectSummary() {
134
+ const { view, setQuery } = useDataExplorer();
135
+ return <button type="button" onClick={() => setQuery("")}>
136
+ {view.total} projects
137
+ </button>;
138
+ }
139
+ ```
140
+
141
+ The toolbar's default rendering composes Search, FilterControl, Sort, ColumnVisibility
142
+ and Filters. Passing toolbar children replaces that default, so consumers can
143
+ reorder or omit individual controls. Search receives `label`; FilterControl receives
144
+ `allLabel`; Sort receives its own `sort`, `unsorted`, `ascending` and `descending`
145
+ labels. ColumnVisibility and Filters consume their optional feature configuration
146
+ and accept local label overrides. They render nothing when the feature is absent.
147
+
148
+ Table, Pagination and BulkActions accept local `labels` for their own controls.
149
+ A provider may also supply partial `labels` as shared defaults. A rendered part
150
+ requires its actual labels; no placeholder translations are invented. Selection
151
+ labels are required only when selection controls render. Custom providers retain
152
+ the same complete in-memory dataset contract; they do not add remote pagination.
153
+
154
+ Column sizing composes the shared pointer session from React-utils. Capture
155
+ loss, Escape, window blur, pointer cancellation and becoming busy restore the
156
+ starting width. Unmount only releases resources and preserves the last emitted
157
+ width. Column geometry and RTL-aware keyboard behavior remain Explorer-owned.
@@ -1,10 +1,5 @@
1
- /**
2
- * @author WMXPY
3
- * @package Data Explorer
4
- * @namespace DataExplorer
5
- * @description Data Explorer
6
- */
7
1
  import type { ExplorerOptions } from "../shared/explorer-options";
8
2
  import type { ComponentPropsWithRef, FC } from "react";
9
3
  export type DataExplorerProps = ComponentPropsWithRef<"section"> & ExplorerOptions;
4
+ /** The original ready-to-use composition remains a convenience over the parts. */
10
5
  export declare const DataExplorer: FC<DataExplorerProps>;
@@ -4,7 +4,9 @@
4
4
  * @namespace DataExplorerBulkActions
5
5
  * @description Data Explorer Bulk Actions
6
6
  */
7
- import type { ExplorerPartOptions } from "../shared/explorer-options";
7
+ import type { DataExplorerLabels, ExplorerPartOptions } from "../shared/explorer-options";
8
8
  import type { FC } from "react";
9
- export type DataExplorerBulkActionsProps = ExplorerPartOptions;
9
+ export type DataExplorerBulkActionsProps = ExplorerPartOptions & {
10
+ readonly labels?: Pick<DataExplorerLabels, "selectPage" | "selected">;
11
+ };
10
12
  export declare const DataExplorerBulkActions: FC<DataExplorerBulkActionsProps>;
@@ -0,0 +1,5 @@
1
+ import type { ExplorerPartOptions } from "../shared/explorer-options";
2
+ export type DataExplorerColumnVisibilityProps = ExplorerPartOptions & {
3
+ readonly label?: string;
4
+ };
5
+ export declare function DataExplorerColumnVisibility({ label, className }: DataExplorerColumnVisibilityProps): import("react").JSX.Element | null;
@@ -0,0 +1,5 @@
1
+ import type { ExplorerPartOptions } from "../shared/explorer-options";
2
+ export type DataExplorerFilterControlProps = ExplorerPartOptions & {
3
+ readonly allLabel: string;
4
+ };
5
+ export declare function DataExplorerFilterControl({ allLabel, className }: DataExplorerFilterControlProps): import("react").JSX.Element | null;
@@ -0,0 +1,5 @@
1
+ import type { DataExplorerFiltering } from "../shared/features";
2
+ export type DataExplorerFiltersProps = {
3
+ readonly labels?: DataExplorerFiltering["labels"];
4
+ };
5
+ export declare function DataExplorerFilters({ labels }: DataExplorerFiltersProps): import("react").JSX.Element | null;
@@ -4,7 +4,9 @@
4
4
  * @namespace DataExplorerPagination
5
5
  * @description Data Explorer Pagination
6
6
  */
7
- import type { ExplorerPartOptions } from "../shared/explorer-options";
7
+ import type { DataExplorerLabels, ExplorerPartOptions } from "../shared/explorer-options";
8
8
  import type { FC } from "react";
9
- export type DataExplorerPaginationProps = ExplorerPartOptions;
9
+ export type DataExplorerPaginationProps = ExplorerPartOptions & {
10
+ readonly labels?: Pick<DataExplorerLabels, "previous" | "next" | "page">;
11
+ };
10
12
  export declare const DataExplorerPagination: FC<DataExplorerPaginationProps>;
@@ -0,0 +1,7 @@
1
+ import type { DataExplorerOptions } from "../shared/explorer-options";
2
+ import type { ReactNode } from "react";
3
+ export type DataExplorerProviderProps = DataExplorerOptions & {
4
+ readonly children?: ReactNode;
5
+ };
6
+ /** Own dataset coordination without adding DOM, labels or layout requirements. */
7
+ export declare function DataExplorerProvider({ children, ...options }: DataExplorerProviderProps): import("react").JSX.Element;
@@ -0,0 +1,5 @@
1
+ import type { ExplorerPartOptions } from "../shared/explorer-options";
2
+ export type DataExplorerSearchProps = ExplorerPartOptions & {
3
+ readonly label: string;
4
+ };
5
+ export declare function DataExplorerSearch({ label, className }: DataExplorerSearchProps): import("react").JSX.Element;
@@ -0,0 +1,5 @@
1
+ import type { DataExplorerLabels, ExplorerPartOptions } from "../shared/explorer-options";
2
+ export type DataExplorerSortProps = ExplorerPartOptions & {
3
+ readonly labels: Pick<DataExplorerLabels, "sort" | "unsorted" | "ascending" | "descending">;
4
+ };
5
+ export declare function DataExplorerSort({ labels, className }: DataExplorerSortProps): import("react").JSX.Element;
@@ -4,8 +4,10 @@
4
4
  * @namespace DataExplorerTable
5
5
  * @description Data Explorer Table
6
6
  */
7
- import type { ExplorerPartOptions } from "../shared/explorer-options";
7
+ import type { DataExplorerLabels, ExplorerPartOptions } from "../shared/explorer-options";
8
8
  import { type DataTablePresentation } from "@gridui/table";
9
9
  import { type FC } from "react";
10
- export type DataExplorerTableProps = ExplorerPartOptions & DataTablePresentation;
10
+ export type DataExplorerTableProps = ExplorerPartOptions & DataTablePresentation & {
11
+ readonly labels?: Pick<DataExplorerLabels, "table" | "empty"> & Partial<Pick<DataExplorerLabels, "selection" | "selectRow">>;
12
+ };
11
13
  export declare const DataExplorerTable: FC<DataExplorerTableProps>;
@@ -1,10 +1,6 @@
1
- /**
2
- * @author WMXPY
3
- * @package Data Explorer
4
- * @namespace DataExplorerToolbar
5
- * @description Data Explorer Toolbar
6
- */
7
1
  import type { ExplorerPartOptions } from "../shared/explorer-options";
8
- import type { FC } from "react";
9
- export type DataExplorerToolbarProps = ExplorerPartOptions;
10
- export declare const DataExplorerToolbar: FC<DataExplorerToolbarProps>;
2
+ import type { ReactNode } from "react";
3
+ export type DataExplorerToolbarProps = ExplorerPartOptions & {
4
+ readonly children?: ReactNode;
5
+ };
6
+ export declare function DataExplorerToolbar({ className, children }: DataExplorerToolbarProps): import("react").JSX.Element;
@@ -0,0 +1,6 @@
1
+ import type { ComponentPropsWithRef } from "react";
2
+ export type DataExplorerViewProps = ComponentPropsWithRef<"section"> & {
3
+ readonly label: string;
4
+ };
5
+ /** Optional frame; the provider and custom controls do not depend on it. */
6
+ export declare function DataExplorerView({ label, className, children, ...rest }: DataExplorerViewProps): import("react").JSX.Element;
package/dist/index.d.ts CHANGED
@@ -21,3 +21,20 @@ export type { DataExplorerRow } from "./shared/model";
21
21
  export type { DataExplorerState } from "./shared/model";
22
22
  export type { DataExplorerValue } from "./shared/model";
23
23
  export type { DataExplorerCondition, DataExplorerFilterDefinition, DataExplorerFilterOperator } from "./shared/model";
24
+ export type { DataExplorerProviderProps } from "./data-explorer-provider/data-explorer-provider";
25
+ export { DataExplorerProvider } from "./data-explorer-provider/data-explorer-provider";
26
+ export type { DataExplorerViewProps } from "./data-explorer-view/data-explorer-view";
27
+ export { DataExplorerView } from "./data-explorer-view/data-explorer-view";
28
+ export type { DataExplorerSearchProps } from "./data-explorer-search/data-explorer-search";
29
+ export { DataExplorerSearch } from "./data-explorer-search/data-explorer-search";
30
+ export type { DataExplorerFilterControlProps } from "./data-explorer-filter-control/data-explorer-filter-control";
31
+ export { DataExplorerFilterControl } from "./data-explorer-filter-control/data-explorer-filter-control";
32
+ export type { DataExplorerSortProps } from "./data-explorer-sort/data-explorer-sort";
33
+ export { DataExplorerSort } from "./data-explorer-sort/data-explorer-sort";
34
+ export type { DataExplorerColumnVisibilityProps } from "./data-explorer-column-visibility/data-explorer-column-visibility";
35
+ export { DataExplorerColumnVisibility } from "./data-explorer-column-visibility/data-explorer-column-visibility";
36
+ export type { DataExplorerFiltersProps } from "./data-explorer-filters/data-explorer-filters";
37
+ export { DataExplorerFilters } from "./data-explorer-filters/data-explorer-filters";
38
+ export type { DataExplorerController } from "./shared/controller";
39
+ export type { DataExplorerLabels, DataExplorerOptions } from "./shared/explorer-options";
40
+ export { useDataExplorer } from "./shared/explorer-context";