@gridui/data-explorer 1.3.0 → 1.5.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 (41) hide show
  1. package/README.md +79 -12
  2. package/dist/data-explorer/data-explorer.d.ts +1 -0
  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 +11 -0
  5. package/dist/data-explorer-filter-control/data-explorer-filter-control.d.ts +11 -0
  6. package/dist/data-explorer-filters/data-explorer-filters.d.ts +11 -0
  7. package/dist/{data-explorer-toolbar → data-explorer-filters}/filter-editor.d.ts +1 -1
  8. package/dist/data-explorer-pagination/data-explorer-pagination.d.ts +4 -2
  9. package/dist/data-explorer-provider/data-explorer-provider.d.ts +13 -0
  10. package/dist/data-explorer-search/data-explorer-search.d.ts +11 -0
  11. package/dist/data-explorer-sort/data-explorer-sort.d.ts +11 -0
  12. package/dist/data-explorer-table/data-explorer-table.d.ts +4 -2
  13. package/dist/data-explorer-toolbar/data-explorer-toolbar.d.ts +5 -3
  14. package/dist/data-explorer-view/data-explorer-view.d.ts +12 -0
  15. package/dist/{data-explorer → data-explorer-view}/style.d.ts +1 -1
  16. package/dist/index.d.ts +17 -0
  17. package/dist/index.js +314 -372
  18. package/dist/index.js.map +4 -4
  19. package/dist/shared/controller.d.ts +32 -0
  20. package/dist/shared/explorer-context.d.ts +126 -71
  21. package/dist/shared/explorer-options.d.ts +22 -18
  22. package/dist/{data-explorer-toolbar/style.d.ts → shared/label-style.d.ts} +2 -2
  23. package/dist/shared/labels.d.ts +8 -0
  24. package/dist/styled.js +8 -0
  25. package/dist/styles.css +2911 -0
  26. package/dist/styles.local.css +114 -0
  27. package/docs/catalog.json +99 -1
  28. package/docs/reference/README.md +7 -0
  29. package/docs/reference/data-explorer-bulk-actions.md +4 -0
  30. package/docs/reference/data-explorer-column-visibility.md +27 -0
  31. package/docs/reference/data-explorer-filter-control.md +27 -0
  32. package/docs/reference/data-explorer-filters.md +23 -0
  33. package/docs/reference/data-explorer-pagination.md +4 -0
  34. package/docs/reference/data-explorer-provider.md +97 -0
  35. package/docs/reference/data-explorer-search.md +27 -0
  36. package/docs/reference/data-explorer-sort.md +27 -0
  37. package/docs/reference/data-explorer-table.md +4 -0
  38. package/docs/reference/data-explorer-toolbar.md +6 -0
  39. package/docs/reference/data-explorer-view.md +59 -0
  40. package/docs/reference/data-explorer.md +1 -1
  41. package/package.json +33 -15
package/README.md CHANGED
@@ -1,27 +1,29 @@
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
- Load the complete family stylesheet set in dependency order:
6
+ Load Theme and the self-contained family stylesheet:
7
7
  ```css
8
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
9
  @import "@gridui/data-explorer/styles.css";
10
+ @import "@gridui/dropdown-menu/styles.css"; // Required when composing DropdownMenu.
19
11
  ```
20
12
 
21
13
  Applications own routes, labels, state persistence, and branding.
22
14
 
23
15
  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-data/data-explorer/.changeset/history).
24
16
 
17
+ ## Styles
18
+
19
+ Load Theme once. Use `@gridui/data-explorer/styled` for automatic component CSS in
20
+ CSS-aware bundlers, or keep the CSS-free root import and load `@gridui/data-explorer/styles.css`.
21
+ Both entries expose the same root API. The standalone stylesheet includes component
22
+ dependency styles; Theme/reset remain separate. See the
23
+ [integration guide](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/docs/usage/integration.md)
24
+ for static HTML loading, SSR limits, and avoiding duplicate CSS.
25
+
26
+
25
27
  ## Data exploration and supporting APIs
26
28
 
27
29
  DataExplorer belongs to Data because it coordinates generic dataset exploration
@@ -36,7 +38,7 @@ Standalone [InlineNotice](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/
36
38
  [Breadcrumb/Pagination](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/docs/usage/navigation.md) come from their Core families.
37
39
 
38
40
  Grid owns the structural seams between the header, content, selection toolbar,
39
- and footer through `Split`. Load `@gridui/grid/styles.css` before this family.
41
+ and footer through `Split`. Grid styles are included in this family stylesheet.
40
42
 
41
43
  DataTable receives `blockEdges="none"` and `inlineEdges="none"`: the enclosing
42
44
  Explorer frame and Grid regions own those edges. Table retains internal column,
@@ -90,3 +92,68 @@ query serialization and persistence remain application responsibilities.
90
92
  DataExplorerTable accepts DataTable's independent rowLines, columnLines, density,
91
93
  headerSurface, rowHeaderSurface and striped presentation options. Controlled
92
94
  selectedIds also drive row highlighting; sorting and pagination keep record IDs.
95
+
96
+
97
+ ## Compose controls and layout independently
98
+
99
+ `DataExplorer` remains the default composition with its existing required `labels`.
100
+ For a custom arrangement, `DataExplorerProvider` owns the same controlled local
101
+ state without rendering an element or requiring labels for unused features.
102
+ `DataExplorerView` is an optional section and Grid frame; use application markup
103
+ instead when that frame is not needed.
104
+
105
+ ```tsx
106
+ <DataExplorerProvider
107
+ rows={rows}
108
+ columns={columns}
109
+ state={state}
110
+ onStateChange={setState}
111
+ >
112
+ <DataExplorerView label="Projects">
113
+ <DataExplorerToolbar>
114
+ <DataExplorerSearch label="Find projects" />
115
+ <ProjectSummary />
116
+ </DataExplorerToolbar>
117
+ <DataExplorerTable labels={{ table: "Projects", empty: "No projects" }} />
118
+ <DataExplorerPagination labels={{
119
+ previous: "Previous", next: "Next",
120
+ page: (page, pages, total) => `${page} / ${pages}, ${total} projects`,
121
+ }} />
122
+ </DataExplorerView>
123
+ </DataExplorerProvider>
124
+ ```
125
+
126
+ `useDataExplorer()` supplies the accepted `state`, `busy`, `columns`,
127
+ `visibleColumns`, paged `view`, valid `selectedRowIds`/`selectedRowIdSet`,
128
+ `pageIds` and `selectedPageCount`. Custom controls use `setQuery`,
129
+ `setFilterValue`, `setSort` and `setFilters` to reset paging consistently.
130
+ `updateState` applies a partial state change; `updateSelection` removes missing
131
+ and duplicate IDs. All commands ignore changes while busy, and controlled
132
+ consumers can reject requests. The hook requires a provider or `DataExplorer`.
133
+
134
+ ```tsx
135
+ function ProjectSummary() {
136
+ const { view, setQuery } = useDataExplorer();
137
+ return <button type="button" onClick={() => setQuery("")}>
138
+ {view.total} projects
139
+ </button>;
140
+ }
141
+ ```
142
+
143
+ The toolbar's default rendering composes Search, FilterControl, Sort, ColumnVisibility
144
+ and Filters. Passing toolbar children replaces that default, so consumers can
145
+ reorder or omit individual controls. Search receives `label`; FilterControl receives
146
+ `allLabel`; Sort receives its own `sort`, `unsorted`, `ascending` and `descending`
147
+ labels. ColumnVisibility and Filters consume their optional feature configuration
148
+ and accept local label overrides. They render nothing when the feature is absent.
149
+
150
+ Table, Pagination and BulkActions accept local `labels` for their own controls.
151
+ A provider may also supply partial `labels` as shared defaults. A rendered part
152
+ requires its actual labels; no placeholder translations are invented. Selection
153
+ labels are required only when selection controls render. Custom providers retain
154
+ the same complete in-memory dataset contract; they do not add remote pagination.
155
+
156
+ Column sizing composes the shared pointer session from React-utils. Capture
157
+ loss, Escape, window blur, pointer cancellation and becoming busy restore the
158
+ starting width. Unmount only releases resources and preserves the last emitted
159
+ width. Column geometry and RTL-aware keyboard behavior remain Explorer-owned.
@@ -7,4 +7,5 @@
7
7
  import type { ExplorerOptions } from "../shared/explorer-options";
8
8
  import type { ComponentPropsWithRef, FC } from "react";
9
9
  export type DataExplorerProps = ComponentPropsWithRef<"section"> & ExplorerOptions;
10
+ /** The original ready-to-use composition remains a convenience over the parts. */
10
11
  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,11 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Data Explorer
4
+ * @namespace DataExplorerColumnVisibility
5
+ * @description Data Explorer Column Visibility
6
+ */
7
+ import type { ExplorerPartOptions } from "../shared/explorer-options";
8
+ export type DataExplorerColumnVisibilityProps = ExplorerPartOptions & {
9
+ readonly label?: string;
10
+ };
11
+ export declare function DataExplorerColumnVisibility({ label, className }: DataExplorerColumnVisibilityProps): import("react").JSX.Element | null;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Data Explorer
4
+ * @namespace DataExplorerFilterControl
5
+ * @description Data Explorer Filter Control
6
+ */
7
+ import type { ExplorerPartOptions } from "../shared/explorer-options";
8
+ export type DataExplorerFilterControlProps = ExplorerPartOptions & {
9
+ readonly allLabel: string;
10
+ };
11
+ export declare function DataExplorerFilterControl({ allLabel, className }: DataExplorerFilterControlProps): import("react").JSX.Element | null;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Data Explorer
4
+ * @namespace DataExplorerFilters
5
+ * @description Data Explorer Filters
6
+ */
7
+ import type { DataExplorerFiltering } from "../shared/features";
8
+ export type DataExplorerFiltersProps = {
9
+ readonly labels?: DataExplorerFiltering["labels"];
10
+ };
11
+ export declare function DataExplorerFilters({ labels }: DataExplorerFiltersProps): import("react").JSX.Element | null;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * @author WMXPY
3
3
  * @package Data Explorer
4
- * @namespace DataExplorerToolbar
4
+ * @namespace DataExplorerFilters
5
5
  * @description Filter Editor
6
6
  */
7
7
  import type { DataExplorerFiltering } from "../shared/features";
@@ -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,13 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Data Explorer
4
+ * @namespace DataExplorerProvider
5
+ * @description Data Explorer Provider
6
+ */
7
+ import type { DataExplorerOptions } from "../shared/explorer-options";
8
+ import type { ReactNode } from "react";
9
+ export type DataExplorerProviderProps = DataExplorerOptions & {
10
+ readonly children?: ReactNode;
11
+ };
12
+ /** Own dataset coordination without adding DOM, labels or layout requirements. */
13
+ export declare function DataExplorerProvider({ children, ...options }: DataExplorerProviderProps): import("react").JSX.Element;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Data Explorer
4
+ * @namespace DataExplorerSearch
5
+ * @description Data Explorer Search
6
+ */
7
+ import type { ExplorerPartOptions } from "../shared/explorer-options";
8
+ export type DataExplorerSearchProps = ExplorerPartOptions & {
9
+ readonly label: string;
10
+ };
11
+ export declare function DataExplorerSearch({ label, className }: DataExplorerSearchProps): import("react").JSX.Element;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Data Explorer
4
+ * @namespace DataExplorerSort
5
+ * @description Data Explorer Sort
6
+ */
7
+ import type { DataExplorerLabels, ExplorerPartOptions } from "../shared/explorer-options";
8
+ export type DataExplorerSortProps = ExplorerPartOptions & {
9
+ readonly labels: Pick<DataExplorerLabels, "sort" | "unsorted" | "ascending" | "descending">;
10
+ };
11
+ 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>;
@@ -5,6 +5,8 @@
5
5
  * @description Data Explorer Toolbar
6
6
  */
7
7
  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>;
8
+ import type { ReactNode } from "react";
9
+ export type DataExplorerToolbarProps = ExplorerPartOptions & {
10
+ readonly children?: ReactNode;
11
+ };
12
+ export declare function DataExplorerToolbar({ className, children }: DataExplorerToolbarProps): import("react").JSX.Element;
@@ -0,0 +1,12 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Data Explorer
4
+ * @namespace DataExplorerView
5
+ * @description Data Explorer View
6
+ */
7
+ import type { ComponentPropsWithRef } from "react";
8
+ export type DataExplorerViewProps = ComponentPropsWithRef<"section"> & {
9
+ readonly label: string;
10
+ };
11
+ /** Optional frame; the provider and custom controls do not depend on it. */
12
+ export declare function DataExplorerView({ label, className, children, ...rest }: DataExplorerViewProps): import("react").JSX.Element;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * @author WMXPY
3
3
  * @package Data Explorer
4
- * @namespace DataExplorer
4
+ * @namespace DataExplorerView
5
5
  * @description Style
6
6
  */
7
7
  export declare const explorerStyles: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
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";