torch-glare 2.4.4 → 2.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 (147) hide show
  1. package/apps/lib/components/DataViews/{badgeAdapter.ts → badge.ts} +2 -2
  2. package/apps/lib/components/DataViews/cell.tsx +324 -0
  3. package/apps/lib/components/DataViews/context.ts +144 -0
  4. package/apps/lib/components/DataViews/data-views.tsx +383 -0
  5. package/apps/lib/components/DataViews/filters/children.tsx +98 -0
  6. package/apps/lib/components/DataViews/filters/custom.tsx +34 -0
  7. package/apps/lib/components/DataViews/filters/filters.tsx +163 -0
  8. package/apps/lib/components/DataViews/filters/index.ts +4 -0
  9. package/apps/lib/components/DataViews/filters/labelled.tsx +20 -0
  10. package/apps/lib/components/DataViews/filters/presets.tsx +65 -0
  11. package/apps/lib/components/DataViews/filters/summary.tsx +65 -0
  12. package/apps/lib/components/DataViews/filters/sync.tsx +35 -0
  13. package/apps/lib/components/DataViews/filters/values.ts +173 -0
  14. package/apps/lib/components/DataViews/header.tsx +217 -0
  15. package/apps/lib/components/DataViews/hooks/index.ts +5 -0
  16. package/apps/lib/components/DataViews/hooks/useActiveRow.ts +22 -0
  17. package/apps/lib/components/DataViews/hooks/useControllable.ts +52 -0
  18. package/apps/lib/components/DataViews/index.ts +74 -26
  19. package/apps/lib/components/DataViews/panel/columns.tsx +153 -0
  20. package/apps/lib/components/DataViews/panel/controls.tsx +106 -0
  21. package/apps/lib/components/DataViews/panel/index.ts +3 -0
  22. package/apps/lib/components/DataViews/panel/panel.tsx +164 -0
  23. package/apps/lib/components/DataViews/panel/saved-views.tsx +67 -0
  24. package/apps/lib/components/DataViews/panel/section.tsx +79 -0
  25. package/apps/lib/components/DataViews/panel/sort.tsx +42 -0
  26. package/apps/lib/components/DataViews/panel/tab.tsx +31 -0
  27. package/apps/lib/components/DataViews/slots.ts +63 -0
  28. package/apps/lib/components/DataViews/states.tsx +38 -0
  29. package/apps/lib/components/DataViews/types.ts +485 -178
  30. package/apps/lib/components/DataViews/views/board-view.tsx +379 -0
  31. package/apps/lib/components/DataViews/views/card-rows.tsx +36 -0
  32. package/apps/lib/components/DataViews/views/inbox-view.tsx +257 -0
  33. package/apps/lib/components/DataViews/views/pane-views.tsx +192 -0
  34. package/apps/lib/components/DataViews/views/table-view.tsx +426 -0
  35. package/apps/lib/components/DataViews/views/tree-view.tsx +365 -0
  36. package/apps/lib/components/FormBuilder/context.ts +20 -6
  37. package/apps/lib/components/FormBuilder/field-kind.ts +28 -0
  38. package/apps/lib/components/FormBuilder/fields/DateField.tsx +3 -3
  39. package/apps/lib/components/FormBuilder/fields/FieldShell.tsx +7 -6
  40. package/apps/lib/components/FormBuilder/fields/PhoneField.tsx +30 -4
  41. package/apps/lib/components/FormBuilder/fields/SelectField.tsx +7 -7
  42. package/apps/lib/components/FormBuilder/fields/TableField.tsx +80 -52
  43. package/apps/lib/components/FormBuilder/fields/TextField.tsx +9 -9
  44. package/apps/lib/components/FormBuilder/form-builder.tsx +66 -6
  45. package/apps/lib/components/FormBuilder/index.ts +3 -1
  46. package/apps/lib/components/FormBuilder/types.ts +40 -0
  47. package/apps/lib/components/Input.tsx +3 -0
  48. package/apps/lib/components/SearchableTable.tsx +5 -4
  49. package/apps/lib/components/SectionBlock.tsx +58 -11
  50. package/apps/lib/components/Select.tsx +3 -1
  51. package/apps/lib/components/TabSwitch.tsx +16 -4
  52. package/apps/lib/components/Table.tsx +265 -67
  53. package/apps/lib/components/TreeFolder/TreeFolder.tsx +6 -3
  54. package/apps/lib/components/TreeFolder/TreeFolderRow.tsx +16 -14
  55. package/apps/lib/components/TreeFolder/index.ts +1 -1
  56. package/apps/lib/components/TreeFolder/useTreeFolderDnD.ts +70 -207
  57. package/apps/lib/hooks/useDragDrop.tsx +365 -0
  58. package/apps/lib/hooks/useInfiniteScroll.ts +108 -0
  59. package/apps/lib/registry.json +159 -4
  60. package/apps/lib/tsconfig.tsbuildinfo +1 -1
  61. package/apps/lib/utils/dataViews/path.ts +67 -0
  62. package/apps/lib/utils/dataViews/query.ts +73 -0
  63. package/apps/lib/utils/dataViews/types.ts +187 -0
  64. package/docs/components/breadcrumb.md +1 -1
  65. package/docs/components/button-group.md +1 -1
  66. package/docs/components/button.md +1 -1
  67. package/docs/components/card.md +1 -1
  68. package/docs/components/checkbox.md +1 -1
  69. package/docs/components/data-views/backend-response.md +324 -0
  70. package/docs/components/data-views/examples/a11y-rtl.md +250 -0
  71. package/docs/components/data-views/examples/api-orders-route.md +130 -0
  72. package/docs/components/data-views/examples/fields.md +362 -0
  73. package/docs/components/data-views/examples/filters.md +308 -0
  74. package/docs/components/data-views/examples/inbox-routing.md +218 -0
  75. package/docs/components/data-views/examples/index.md +29 -0
  76. package/docs/components/data-views/examples/overview.md +244 -0
  77. package/docs/components/data-views/examples/panel.md +212 -0
  78. package/docs/components/data-views/examples/scale.md +231 -0
  79. package/docs/components/data-views/examples/server-side.md +210 -0
  80. package/docs/components/data-views/examples/state.md +250 -0
  81. package/docs/components/data-views/examples/tree-custom.md +388 -0
  82. package/docs/components/data-views/examples/view-registry.md +313 -0
  83. package/docs/components/data-views/examples/views.md +534 -0
  84. package/docs/components/data-views/guide.md +405 -0
  85. package/docs/components/data-views/index.md +1504 -0
  86. package/docs/components/data-views/migration.md +79 -0
  87. package/docs/components/date-picker.md +0 -1
  88. package/docs/components/form-builder.md +19 -8
  89. package/docs/components/form-renderer.md +2 -1
  90. package/docs/components/form.md +1 -1
  91. package/docs/components/input-field.md +1 -1
  92. package/docs/components/input-otp.md +1 -1
  93. package/docs/components/input.md +1 -1
  94. package/docs/components/labeled-check-box.md +1 -1
  95. package/docs/components/labeled-radio.md +1 -1
  96. package/docs/components/radio-card.md +1 -1
  97. package/docs/components/radio.md +1 -1
  98. package/docs/components/search-field.md +1 -1
  99. package/docs/components/section-block.md +79 -3
  100. package/docs/components/select.md +1 -1
  101. package/docs/components/simple-select.md +1 -1
  102. package/docs/components/switch.md +1 -1
  103. package/docs/components/tab-switch.md +1 -1
  104. package/docs/components/table.md +45 -8
  105. package/docs/components/text-editor.md +1 -1
  106. package/docs/components/textarea.md +1 -1
  107. package/docs/components/toggle-button.md +1 -1
  108. package/docs/components/toggle.md +1 -1
  109. package/docs/components/tree-folder.md +110 -0
  110. package/docs/how-to/forms-with-form-builder.md +6 -4
  111. package/docs/reference/components.md +16 -6
  112. package/docs/tutorials/component-composition.md +11 -13
  113. package/package.json +3 -2
  114. package/apps/lib/components/DataViews/DataViewRadio.tsx +0 -49
  115. package/apps/lib/components/DataViews/DataViewsConfigPanel.tsx +0 -393
  116. package/apps/lib/components/DataViews/DataViewsHeader.tsx +0 -207
  117. package/apps/lib/components/DataViews/DataViewsLayout.tsx +0 -332
  118. package/apps/lib/components/DataViews/FilterPanel.tsx +0 -493
  119. package/apps/lib/components/DataViews/HeaderSearch.tsx +0 -93
  120. package/apps/lib/components/DataViews/InboxView.tsx +0 -463
  121. package/apps/lib/components/DataViews/InboxViewCard.tsx +0 -127
  122. package/apps/lib/components/DataViews/KanbanView.tsx +0 -336
  123. package/apps/lib/components/DataViews/PanelControls.tsx +0 -39
  124. package/apps/lib/components/DataViews/SettingsPanel.tsx +0 -279
  125. package/apps/lib/components/DataViews/TableView.tsx +0 -212
  126. package/apps/lib/components/DataViews/TreeView.tsx +0 -364
  127. package/apps/lib/components/DataViews/fieldRenderers.tsx +0 -299
  128. package/apps/lib/components/DataViews/filters/DatePickerRangeFilter.tsx +0 -87
  129. package/apps/lib/components/DataViews/filters/DateRangePopover.tsx +0 -120
  130. package/apps/lib/components/DataViews/filters/PresetChips.tsx +0 -45
  131. package/apps/lib/components/DataViews/filters/RangeSliderWithInputs.tsx +0 -165
  132. package/apps/lib/components/DataViews/tree/TreeDrawer.tsx +0 -50
  133. package/apps/lib/components/DataViews/tree/TreeSidebar.tsx +0 -74
  134. package/apps/lib/hooks/useDataViewsState.ts +0 -175
  135. package/apps/lib/utils/dataViews/columnUtils.ts +0 -132
  136. package/apps/lib/utils/dataViews/fieldUtils.ts +0 -197
  137. package/apps/lib/utils/dataViews/nestedDataUtils.tsx +0 -371
  138. package/apps/lib/utils/dataViews/pathUtils.ts +0 -139
  139. package/apps/lib/utils/dataViews/rangeUtils.ts +0 -234
  140. package/apps/lib/utils/dataViews/treeUtils.ts +0 -396
  141. package/docs/components/data-views-config-panel.md +0 -208
  142. package/docs/components/data-views-layout.md +0 -291
  143. package/docs/components/inbox-view.md +0 -170
  144. package/docs/components/kanban-view.md +0 -135
  145. package/docs/components/table-view.md +0 -141
  146. package/docs/components/tree-view.md +0 -147
  147. package/docs/how-to/data-views-from-backend-response.md +0 -194
@@ -0,0 +1,20 @@
1
+ "use client";
2
+
3
+ import React from "react";
4
+
5
+ /** A label above a bare control, since `FieldSection` is exactly what "bare" removes. */
6
+ export function Labelled({ label, children }: { label?: React.ReactNode; children: React.ReactNode }) {
7
+ return (
8
+ // `flex-1` is what makes a control fill the width it was given rather than sitting at its
9
+ // minimum with dead space beside it — one per line in the 260px rail, sharing the line evenly
10
+ // in anything wider. `min-w` stays as the floor that decides where the parent wraps.
11
+ <div className="flex min-w-[180px] flex-1 flex-col gap-1">
12
+ {label && (
13
+ <span className="typography-body-small-regular text-content-presentation-global-secondary">
14
+ {label}
15
+ </span>
16
+ )}
17
+ {children}
18
+ </div>
19
+ );
20
+ }
@@ -0,0 +1,65 @@
1
+ "use client";
2
+
3
+ import { useFormContext } from "react-hook-form";
4
+ import { cn } from "../../../utils/cn";
5
+ import type { FilterFieldDescriptor, NumberPreset } from "../../../utils/dataViews/types";
6
+ import { useDataViewsFilters } from "../context";
7
+ import { datePresets, numberPresets, toName } from "./values";
8
+ import type { FilterPresetsProps } from "../types";
9
+
10
+ /** Look up what `Filters` learned about a path, so a sibling control can target it. */
11
+ function useDescriptor(path: string): FilterFieldDescriptor | undefined {
12
+ const { filterFields } = useDataViewsFilters();
13
+ return filterFields.find((f) => f.path === path);
14
+ }
15
+
16
+
17
+ /**
18
+ * `DataViews.Filters.Presets` — named shortcuts for the field named in `for`.
19
+ *
20
+ * FormBuilder has no field for this, and it is not a filter of its own: it writes into a sibling's
21
+ * value. Numeric presets fill the side they do not name from that slider's bounds, so
22
+ * `{ label: "$5k+", min: 5000 }` means "5,000 to the top" rather than "5,000 to 100".
23
+ */
24
+ export function Presets({ for: path, items, className }: FilterPresetsProps) {
25
+ const form = useFormContext();
26
+ const field = useDescriptor(path);
27
+ const name = toName(path);
28
+
29
+ if (!field) return null;
30
+
31
+ const shortcuts =
32
+ field.kind === "date"
33
+ ? datePresets(items).map((preset) => ({
34
+ label: preset.label,
35
+ apply: () =>
36
+ form.setValue(name, {
37
+ from: preset.from ? new Date(preset.from) : undefined,
38
+ to: preset.to ? new Date(preset.to) : undefined,
39
+ }),
40
+ }))
41
+ : numberPresets(items).map((preset: NumberPreset) => ({
42
+ label: preset.label,
43
+ apply: () => form.setValue(name, [preset.min ?? field.min ?? 0, preset.max ?? field.max ?? 100]),
44
+ }));
45
+
46
+ if (shortcuts.length === 0) return null;
47
+
48
+ return (
49
+ <div className={cn("flex flex-wrap gap-1", className)}>
50
+ {shortcuts.map((preset) => (
51
+ <button
52
+ key={preset.label}
53
+ type="button"
54
+ onClick={preset.apply}
55
+ className={cn(
56
+ "typography-body-small-regular rounded-[4px] px-2 py-[2px] transition-colors",
57
+ "text-content-presentation-global-secondary hover:bg-background-presentation-action-hover",
58
+ )}
59
+ >
60
+ {preset.label}
61
+ </button>
62
+ ))}
63
+ </div>
64
+ );
65
+ }
@@ -0,0 +1,65 @@
1
+ "use client";
2
+
3
+ import { cn } from "../../../utils/cn";
4
+ import { formatPathLabel } from "../../../utils/dataViews/path";
5
+ import type { FilterValue } from "../../../utils/dataViews/types";
6
+ import { useDataViewsFilters, useDataViewsView } from "../context";
7
+
8
+ /**
9
+ * `DataViews.Filters.Summary` — the active filters as removable chips. Useful when the controls
10
+ * themselves live in the panel and you still want the current query visible above the rows.
11
+ *
12
+ * Its labels come from the same descriptors `Filters` reads off its children — the **root** collects
13
+ * those as well, so this works wherever it is rendered, including as `Filters`' sibling. A path no
14
+ * control covers falls back to a label derived from the path.
15
+ */
16
+ export function Summary({ className }: { className?: string }) {
17
+ const { filters, setFilters, filterFields } = useDataViewsFilters();
18
+ const { search, setSearch } = useDataViewsView();
19
+ const entries = Object.entries(filters);
20
+
21
+ if (entries.length === 0 && !search) return null;
22
+
23
+ const chip = cn(
24
+ "typography-body-small-regular flex items-center gap-1 rounded-[6px] px-2 py-[2px]",
25
+ "bg-background-presentation-action-selected text-content-presentation-global-primary",
26
+ );
27
+
28
+ const describe = (path: string, value: FilterValue) => {
29
+ const label = filterFields.find((f) => f.path === path)?.label ?? formatPathLabel(path);
30
+ if (Array.isArray(value)) return `${label}: ${value.join(", ")}`;
31
+ if (value.kind === "number") return `${label}: ${value.min ?? "…"}–${value.max ?? "…"}`;
32
+ return `${label}: ${value.from ?? "…"} → ${value.to ?? "…"}`;
33
+ };
34
+
35
+ return (
36
+ <div className={cn("flex flex-wrap items-center gap-2", className)}>
37
+ {/* The search term narrows the result set exactly as a filter does, so it belongs in the
38
+ summary of what is currently narrowing it — and it has to be clearable from here too. */}
39
+ {search && (
40
+ <span className={chip}>
41
+ {`Search: ${search}`}
42
+ <button type="button" aria-label="Clear search" onClick={() => setSearch("")}>
43
+ <i className="ri-close-line text-[12px]" />
44
+ </button>
45
+ </span>
46
+ )}
47
+ {entries.map(([path, value]) => (
48
+ <span key={path} className={chip}>
49
+ {describe(path, value)}
50
+ <button
51
+ type="button"
52
+ aria-label={`Remove ${path} filter`}
53
+ onClick={() => {
54
+ const copy = { ...filters };
55
+ delete copy[path];
56
+ setFilters(copy);
57
+ }}
58
+ >
59
+ <i className="ri-close-line text-[12px]" />
60
+ </button>
61
+ </span>
62
+ ))}
63
+ </div>
64
+ );
65
+ }
@@ -0,0 +1,35 @@
1
+ "use client";
2
+
3
+ import { useEffect, useRef } from "react";
4
+ import { useWatch } from "react-hook-form";
5
+ import type { FilterFieldDescriptor } from "../../../utils/dataViews/types";
6
+ import { useDataViewsFilters } from "../context";
7
+ import { sameFilters, toFilterState } from "./values";
8
+
9
+ /**
10
+ * Pushes what the user typed back out as `onValueChange`.
11
+ *
12
+ * Debounced, and guarded by an equality check: without both, `watch` → emit → new `values` →
13
+ * re-render is a loop that swallows keystrokes mid-type.
14
+ */
15
+ export function Sync({ fields }: { fields: readonly FilterFieldDescriptor[] }) {
16
+ const { setFilters, filters } = useDataViewsFilters();
17
+ const watched = useWatch();
18
+
19
+ // Read the current filters through a ref so the effect does not re-run just because the parent
20
+ // handed back a new (equal) object.
21
+ const latest = useRef(filters);
22
+ latest.current = filters;
23
+
24
+ useEffect(() => {
25
+ const timer = setTimeout(() => {
26
+ // Merged onto the current state, not derived from scratch — these controls own only their
27
+ // own paths. Anything else (a `Filters.Custom` value, a key the caller supplied) survives.
28
+ const next = toFilterState(watched as Record<string, unknown>, fields, latest.current);
29
+ if (!sameFilters(next, latest.current)) setFilters(next);
30
+ }, 200);
31
+ return () => clearTimeout(timer);
32
+ }, [watched, fields, setFilters]);
33
+
34
+ return null;
35
+ }
@@ -0,0 +1,173 @@
1
+ import type {
2
+ DatePreset,
3
+ FilterFieldDescriptor,
4
+ FilterState,
5
+ FilterValue,
6
+ NumberPreset,
7
+ Preset,
8
+ } from "../../../utils/dataViews/types";
9
+
10
+ /**
11
+ * Translating between `FilterState` (what you receive) and react-hook-form values (what the
12
+ * inputs speak). Pure functions, no React — the fiddly half of `Filters` is here so the component
13
+ * itself stays readable, and so this is testable without rendering anything.
14
+ */
15
+
16
+ /**
17
+ * RHF reads `.` in a field name as object nesting, so a filter on `customer.name` would arrive as
18
+ * `{ customer: { name: … } }`. Names are escaped on the way in and unescaped on the way out.
19
+ */
20
+ export const toName = (path: string) => path.replace(/\./g, "__");
21
+
22
+ const isRange = (v: FilterValue | undefined): v is Exclude<FilterValue, string[]> =>
23
+ !!v && !Array.isArray(v);
24
+
25
+ /** `FilterState` → the values the inputs want. */
26
+ export function toFormValues(
27
+ filters: FilterState,
28
+ fields: readonly FilterFieldDescriptor[],
29
+ ): Record<string, unknown> {
30
+ const out: Record<string, unknown> = {};
31
+
32
+ for (const field of fields) {
33
+ const value = filters[field.path];
34
+ const name = toName(field.path);
35
+
36
+ switch (field.kind) {
37
+ case "choice": {
38
+ const selected = Array.isArray(value) ? value : [];
39
+ out[name] = field.single ? (selected[0] ?? "") : selected;
40
+ break;
41
+ }
42
+ case "number": {
43
+ const lo = field.min ?? 0;
44
+ const hi = field.max ?? 100;
45
+ const range = isRange(value) && value.kind === "number" ? value : undefined;
46
+ out[name] = [range?.min ?? lo, range?.max ?? hi];
47
+ break;
48
+ }
49
+ case "date": {
50
+ const range = isRange(value) && value.kind === "date" ? value : undefined;
51
+ out[name] = {
52
+ from: range?.from ? new Date(range.from) : undefined,
53
+ to: range?.to ? new Date(range.to) : undefined,
54
+ };
55
+ break;
56
+ }
57
+ case "text":
58
+ out[name] = Array.isArray(value) ? (value[0] ?? "") : "";
59
+ break;
60
+ }
61
+ }
62
+
63
+ return out;
64
+ }
65
+
66
+ /**
67
+ * `YYYY-MM-DD` in the **user's** timezone.
68
+ *
69
+ * `toISOString()` converts to UTC first, so someone east of UTC picking "today" in the calendar
70
+ * would emit yesterday's date — an off-by-one-day filter that only reproduces in some timezones.
71
+ */
72
+ const iso = (d: unknown) => {
73
+ const date = d instanceof Date ? d : d ? new Date(String(d)) : null;
74
+ if (!date || Number.isNaN(date.getTime())) return undefined;
75
+ const pad = (n: number) => String(n).padStart(2, "0");
76
+ return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
77
+ };
78
+
79
+ /**
80
+ * The inputs' values → `FilterState`.
81
+ *
82
+ * A control at its neutral position produces **no key at all** rather than an empty one. That
83
+ * matters: the emitted query is a request to go and fetch, and `{ total: { min: 0, max: 100 } }`
84
+ * when the slider has never been touched would narrow a query that the user never narrowed.
85
+ *
86
+ * `previous` is merged rather than replaced, and this is load-bearing: these `fields` own only
87
+ * their own paths. `Filters.Custom` writes straight into `FilterState`, and a caller's initial
88
+ * `filters` may carry keys no control was declared for. Rebuilding the state from `fields` alone
89
+ * would silently drop both the moment any control changed.
90
+ */
91
+ export function toFilterState(
92
+ values: Record<string, unknown>,
93
+ fields: readonly FilterFieldDescriptor[],
94
+ previous: FilterState = {},
95
+ ): FilterState {
96
+ const owned = new Set(fields.map((f) => f.path));
97
+ const out: FilterState = {};
98
+ for (const [path, value] of Object.entries(previous)) {
99
+ if (!owned.has(path)) out[path] = value;
100
+ }
101
+
102
+ for (const field of fields) {
103
+ const raw = values[toName(field.path)];
104
+
105
+ switch (field.kind) {
106
+ case "choice": {
107
+ const selected =
108
+ field.single
109
+ ? raw
110
+ ? [String(raw)]
111
+ : []
112
+ : Array.isArray(raw)
113
+ ? raw.map(String)
114
+ : [];
115
+ if (selected.length > 0) out[field.path] = selected;
116
+ break;
117
+ }
118
+ case "number": {
119
+ if (!Array.isArray(raw)) break;
120
+ const lo = field.min ?? 0;
121
+ const hi = field.max ?? 100;
122
+ const [min, max] = raw as number[];
123
+ // Untouched means "no constraint", not "everything".
124
+ if (min === lo && max === hi) break;
125
+ out[field.path] = { kind: "number", min, max };
126
+ break;
127
+ }
128
+ case "date": {
129
+ const range = (raw ?? {}) as { from?: unknown; to?: unknown };
130
+ const from = iso(range.from);
131
+ const to = iso(range.to);
132
+ if (from || to) out[field.path] = { kind: "date", from, to };
133
+ break;
134
+ }
135
+ case "text": {
136
+ const text = typeof raw === "string" ? raw.trim() : "";
137
+ if (text) out[field.path] = [text];
138
+ break;
139
+ }
140
+ }
141
+ }
142
+
143
+ return out;
144
+ }
145
+
146
+ /**
147
+ * Whether two filter states are the same. Used to break the `watch` → `onChange` → new `values`
148
+ * → re-render loop that otherwise eats keystrokes: if nothing actually changed, nothing is
149
+ * emitted.
150
+ */
151
+ export function sameFilters(a: FilterState, b: FilterState): boolean {
152
+ const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
153
+ for (const key of keys) {
154
+ const x = a[key];
155
+ const y = b[key];
156
+ if (x === undefined || y === undefined) return false;
157
+ if (Array.isArray(x) !== Array.isArray(y)) return false;
158
+ if (Array.isArray(x) && Array.isArray(y)) {
159
+ if (x.length !== y.length || x.some((v, i) => v !== y[i])) return false;
160
+ } else if (JSON.stringify(x) !== JSON.stringify(y)) {
161
+ return false;
162
+ }
163
+ }
164
+ return true;
165
+ }
166
+
167
+ /** The numeric shortcuts out of a mixed `presets` list. */
168
+ export const numberPresets = (presets?: readonly Preset[]): NumberPreset[] =>
169
+ (presets ?? []).filter((p): p is NumberPreset => "min" in p || "max" in p);
170
+
171
+ /** The date shortcuts out of a mixed `presets` list. */
172
+ export const datePresets = (presets?: readonly Preset[]): DatePreset[] =>
173
+ (presets ?? []).filter((p): p is DatePreset => "from" in p || "to" in p);
@@ -0,0 +1,217 @@
1
+ "use client";
2
+
3
+ import React, { useEffect, useRef, useState } from "react";
4
+ import { Search as SearchIcon, Settings } from "lucide-react";
5
+ import { cn } from "../../utils/cn";
6
+ import { Button } from "../Button";
7
+ import { TabSwitch, type TabSwitchOption } from "../TabSwitch";
8
+ import { useDataViewsPanel, useDataViewsView } from "./context";
9
+ import { markHeader } from "./slots";
10
+ import type {
11
+ ActionsProps,
12
+ HeaderProps,
13
+ PanelToggleProps,
14
+ SearchProps,
15
+ ViewSwitchProps,
16
+ } from "./types";
17
+
18
+ /**
19
+ * The bar above the views — 52px, black, always dark.
20
+ *
21
+ * `data-theme="dark"` is deliberate and scoped to the bar: it makes the child Buttons and the
22
+ * view switcher resolve dark tokens so they read correctly against the black, even when the host
23
+ * app runs light. It must not wrap the content below, which stays in the host theme.
24
+ *
25
+ * ```tsx
26
+ * <DataViews.Header title="Orders">
27
+ * <DataViews.ViewSwitch />
28
+ * <DataViews.Search />
29
+ * <DataViews.Actions><Button>New</Button></DataViews.Actions>
30
+ * <DataViews.PanelToggle />
31
+ * </DataViews.Header>
32
+ * ```
33
+ */
34
+ export function Header({ title, children, className }: HeaderProps) {
35
+ return (
36
+ <div
37
+ data-theme="dark"
38
+ className={cn(
39
+ // 40px and no background of its own, per Figma's `Body-HeaderBar-1.0`. The bar has never
40
+ // needed one: the root shell already paints black behind it.
41
+ "flex h-[40px] w-full shrink-0 items-center gap-2 rounded-[12px]",
42
+ className,
43
+ )}
44
+ >
45
+ {title !== undefined && (
46
+ <>
47
+ <div className="flex h-9 shrink-0 items-center gap-2 rounded-[12px] border border-[#434446] bg-[#252729] px-[10px]">
48
+ <span className="text-[28px] font-[510] uppercase leading-[1.19] text-white">
49
+ {title}
50
+ </span>
51
+ </div>
52
+ {/* `border/presentation/global/primary`, not the pill's `#434446` — the design uses two
53
+ different greys here, and the divider is the darker one. */}
54
+ <div className="h-5 w-px shrink-0 rounded-[4px] bg-[#2c2d2e]" />
55
+ </>
56
+ )}
57
+ {children}
58
+ </div>
59
+ );
60
+ }
61
+
62
+ markHeader(Header);
63
+
64
+ /**
65
+ * Switches between the views you rendered. The options come from the view registry, so this stays
66
+ * in sync by construction — there is no list to keep updated.
67
+ *
68
+ * It takes the remaining width, which is what pushes `Actions` and the panel toggle to the end of
69
+ * the bar. Renders nothing when fewer than two views are registered: a switcher with one option
70
+ * is noise.
71
+ *
72
+ */
73
+ export function ViewSwitch({ className }: ViewSwitchProps) {
74
+ const { views, view, setView } = useDataViewsView();
75
+
76
+ if (views.length < 2) return <div className="flex-1" />;
77
+
78
+ const options: TabSwitchOption[] = views.map((v) => ({
79
+ value: v.id,
80
+ label: v.label,
81
+ icon: v.icon,
82
+ }));
83
+
84
+ return (
85
+ <div className={cn("flex flex-1 items-center gap-2", className)}>
86
+ <TabSwitch theme="dark" options={options} value={view} onValueChange={setView} />
87
+ </div>
88
+ );
89
+ }
90
+
91
+ /**
92
+ * The search box — an icon button that expands into a field.
93
+ *
94
+ * It only reports what was typed: typing puts a `search` in the query and `onQueryChange` is
95
+ * where you go and fetch. DataViews never matches rows against this string.
96
+ */
97
+ export function Search({ placeholder = "Search...", className }: SearchProps) {
98
+ const { search, setSearch } = useDataViewsView();
99
+ const [open, setOpen] = useState(false);
100
+ const inputRef = useRef<HTMLInputElement>(null);
101
+ const wrapRef = useRef<HTMLDivElement>(null);
102
+
103
+ useEffect(() => {
104
+ if (open) inputRef.current?.focus();
105
+ }, [open]);
106
+
107
+ const clearAndCollapse = () => {
108
+ setSearch("");
109
+ setOpen(false);
110
+ };
111
+
112
+ useEffect(() => {
113
+ if (!open) return;
114
+ const onDown = (e: MouseEvent) => {
115
+ if (wrapRef.current?.contains(e.target as Node)) return;
116
+ // Collapsing on an outside click would throw away an active query — only close when the
117
+ // field is empty.
118
+ if (!search) setOpen(false);
119
+ };
120
+ document.addEventListener("mousedown", onDown);
121
+ return () => document.removeEventListener("mousedown", onDown);
122
+ }, [open, search]);
123
+
124
+ if (!open) {
125
+ return (
126
+ <Button
127
+ variant="BluContStyle"
128
+ size="M"
129
+ buttonType="icon"
130
+ aria-label="Open search"
131
+ onClick={() => setOpen(true)}
132
+ className={cn(
133
+ "border-border-presentation-global-primary shrink-0 rounded-[6px] border",
134
+ className,
135
+ )}
136
+ >
137
+ <SearchIcon className="h-[18px] w-[18px]" />
138
+ </Button>
139
+ );
140
+ }
141
+
142
+ return (
143
+ <div
144
+ ref={wrapRef}
145
+ className={cn(
146
+ "relative flex h-[28px] w-[260px] shrink-0 items-center justify-center rounded-[6px]",
147
+ "border-border-presentation-state-focus bg-background-presentation-form-field-primary border px-1",
148
+ "shadow-[0_1px_6px_0_rgba(0,0,0,0.30)] transition-all duration-150 ease-in-out",
149
+ className,
150
+ )}
151
+ >
152
+ <input
153
+ ref={inputRef}
154
+ type="text"
155
+ size={1}
156
+ value={search}
157
+ placeholder={placeholder}
158
+ onChange={(e) => setSearch(e.target.value)}
159
+ onKeyDown={(e) => {
160
+ if (e.key === "Escape") clearAndCollapse();
161
+ }}
162
+ className="placeholder:text-content-presentation-global-tertiary min-w-0 flex-1 bg-transparent text-[14px] leading-none text-white caret-[#1E7AFE] focus:outline-none"
163
+ />
164
+ <button
165
+ type="button"
166
+ aria-label="Clear search"
167
+ onClick={clearAndCollapse}
168
+ className="flex shrink-0 items-center justify-center self-stretch px-1"
169
+ >
170
+ <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="none">
171
+ <path
172
+ d="M7.99992 14.6666C4.31802 14.6666 1.33325 11.6818 1.33325 7.99992C1.33325 4.31802 4.31802 1.33325 7.99992 1.33325C11.6818 1.33325 14.6666 4.31802 14.6666 7.99992C14.6666 11.6818 11.6818 14.6666 7.99992 14.6666ZM7.99992 7.05712L6.1143 5.17149L5.17149 6.1143L7.05712 7.99992L5.17149 9.88552L6.1143 10.8283L7.99992 8.94272L9.88552 10.8283L10.8283 9.88552L8.94272 7.99992L10.8283 6.1143L9.88552 5.17149L7.99992 7.05712Z"
173
+ fill="white"
174
+ />
175
+ </svg>
176
+ </button>
177
+ </div>
178
+ );
179
+ }
180
+
181
+ /**
182
+ * A slot for your own buttons, so they line up with the rest of the header.
183
+ *
184
+ * The convention is `<Button variant="BluColStyle" size="M">` — the solid `#005ecc` Figma uses
185
+ * for the bar's action. `Search` and `PanelToggle` beside it stay ghost on purpose: they are
186
+ * toggles, and three solid pills on black would stop them reading as such. A toggle of your own
187
+ * belongs here too, with `BluColStyle` for its on state.
188
+ *
189
+ * Not enforced. Cloning the children to force a variant would override a caller who deliberately
190
+ * wants a destructive button here, and would fight their `className`.
191
+ */
192
+ export function Actions({ children, className }: ActionsProps) {
193
+ return <div className={cn("flex shrink-0 items-center gap-2", className)}>{children}</div>;
194
+ }
195
+
196
+ /**
197
+ * Opens `DataViews.Panel`. It hides itself while the panel is open — the panel has its own close
198
+ * control, so keeping this one visible would be a second way to do the same thing.
199
+ */
200
+ export function PanelToggle({ children, className }: PanelToggleProps) {
201
+ const { open, setOpen } = useDataViewsPanel();
202
+
203
+ if (open) return null;
204
+
205
+ return (
206
+ <Button
207
+ variant="BluContStyle"
208
+ size="M"
209
+ onClick={() => setOpen(true)}
210
+ aria-expanded={open}
211
+ className={cn("gap-[6px] rounded-[6px] px-[14px] text-[16px] font-[510]", className)}
212
+ >
213
+ <Settings className="h-[18px] w-[18px]" />
214
+ {children ?? "Filter & Config."}
215
+ </Button>
216
+ );
217
+ }
@@ -0,0 +1,5 @@
1
+ // DataViews' own hooks. The drag hook is not here: `TreeFolder` needs it too, and a shared
2
+ // component cannot import from inside DataViews without inverting the dependency — it lives in
3
+ // `lib/hooks/useDragDrop.tsx`.
4
+ export { useActiveRow } from "./useActiveRow";
5
+ export { useControllable } from "./useControllable";
@@ -0,0 +1,22 @@
1
+ "use client";
2
+
3
+ import type { Row } from "../../../utils/dataViews/types";
4
+ import { useDataViewsData, useDataViewsView } from "../context";
5
+
6
+ /**
7
+ * The row the inbox (or board, or tree) has open, ready to render in a detail pane. Returns
8
+ * `null` when nothing is selected.
9
+ *
10
+ * ```tsx
11
+ * function Detail() {
12
+ * const row = useActiveRow();
13
+ * return row ? <h2>{row.subject}</h2> : null;
14
+ * }
15
+ * ```
16
+ */
17
+ export function useActiveRow(): Row | null {
18
+ const { rows, getRowId } = useDataViewsData();
19
+ const { activeId } = useDataViewsView();
20
+ if (activeId === null) return null;
21
+ return rows.find((row, i) => getRowId(row, i) === activeId) ?? null;
22
+ }
@@ -0,0 +1,52 @@
1
+ "use client";
2
+
3
+ import { useCallback, useRef, useState } from "react";
4
+
5
+ /**
6
+ * One controlled/uncontrolled pair, written once.
7
+ *
8
+ * Pass `value` to control it; omit `value` to let the component keep its own. `onChange` fires
9
+ * either way, so a consumer can observe without taking ownership.
10
+ *
11
+ * `set` accepts an updater, because the thing this now holds — the query — is patched rather than
12
+ * replaced: changing a filter has to read the page it is resetting.
13
+ */
14
+ export function useControllable<T>(
15
+ value: T | undefined,
16
+ onChange: ((next: T) => void) | undefined,
17
+ fallback: T,
18
+ ): [T, (next: T | ((prev: T) => T)) => void] {
19
+ const [internal, setInternal] = useState<T>(fallback);
20
+
21
+ // `value !== undefined` decides the mode. Latch the first answer so a consumer that
22
+ // accidentally flips between the two gets a warning-free, stable component rather than
23
+ // React's "changing an uncontrolled input to controlled" class of bug.
24
+ const controlledRef = useRef(value !== undefined);
25
+ const isControlled = controlledRef.current;
26
+
27
+ const current = isControlled ? (value as T) : internal;
28
+
29
+ /**
30
+ * The value an updater builds on.
31
+ *
32
+ * Reset to `current` on every render, and advanced *synchronously* by `set` — so two patches in
33
+ * one tick chain instead of racing. Without that, restoring a saved view (which puts back the
34
+ * sort and the filters one after the other) silently drops the first: both would read the value
35
+ * from the last render, and the second would win.
36
+ */
37
+ const pendingRef = useRef(current);
38
+ pendingRef.current = current;
39
+
40
+ const set = useCallback(
41
+ (next: T | ((prev: T) => T)) => {
42
+ const resolved =
43
+ typeof next === "function" ? (next as (prev: T) => T)(pendingRef.current) : next;
44
+ pendingRef.current = resolved;
45
+ if (!controlledRef.current) setInternal(resolved);
46
+ onChange?.(resolved);
47
+ },
48
+ [onChange],
49
+ );
50
+
51
+ return [current, set];
52
+ }