@brightlocal/ui-components 3.0.0 → 3.1.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 (105) hide show
  1. package/README.md +2 -1
  2. package/component-meta.json +90 -19
  3. package/deprecations.json +113 -3
  4. package/dist/accordion.cjs +1 -1
  5. package/dist/accordion.d.ts +36 -0
  6. package/dist/accordion.d.ts.map +1 -1
  7. package/dist/accordion.js +74 -61
  8. package/dist/blocks/empty-state.cjs +1 -1
  9. package/dist/blocks/empty-state.d.ts.map +1 -1
  10. package/dist/blocks/empty-state.js +41 -49
  11. package/dist/button-group.cjs +1 -0
  12. package/dist/button-group.d.ts +36 -0
  13. package/dist/button-group.d.ts.map +1 -0
  14. package/dist/button-group.js +47 -0
  15. package/dist/button.cjs +1 -1
  16. package/dist/button.js +1 -1
  17. package/dist/card.cjs +1 -1
  18. package/dist/card.d.ts +20 -2
  19. package/dist/card.d.ts.map +1 -1
  20. package/dist/card.js +83 -75
  21. package/dist/chart.cjs +2 -2
  22. package/dist/chart.d.ts +40 -12
  23. package/dist/chart.d.ts.map +1 -1
  24. package/dist/chart.js +86 -71
  25. package/dist/chip.cjs +1 -1
  26. package/dist/chip.d.ts +38 -4
  27. package/dist/chip.d.ts.map +1 -1
  28. package/dist/chip.js +95 -81
  29. package/dist/command.cjs +1 -1
  30. package/dist/command.d.ts +23 -1
  31. package/dist/command.d.ts.map +1 -1
  32. package/dist/command.js +250 -224
  33. package/dist/data-table.cjs +1 -1
  34. package/dist/data-table.d.ts +32 -1
  35. package/dist/data-table.d.ts.map +1 -1
  36. package/dist/data-table.js +340 -330
  37. package/dist/date-picker.cjs +1 -1
  38. package/dist/date-picker.d.ts +13 -5
  39. package/dist/date-picker.d.ts.map +1 -1
  40. package/dist/date-picker.js +54 -53
  41. package/dist/field.cjs +1 -1
  42. package/dist/field.d.ts +8 -1
  43. package/dist/field.d.ts.map +1 -1
  44. package/dist/field.js +79 -52
  45. package/dist/global-layout.cjs +1 -1
  46. package/dist/global-layout.d.ts +105 -13
  47. package/dist/global-layout.d.ts.map +1 -1
  48. package/dist/global-layout.js +146 -129
  49. package/dist/grid.d.ts +2 -2
  50. package/dist/hooks/use-mobile.cjs +1 -0
  51. package/dist/hooks/use-mobile.js +8 -0
  52. package/dist/index.cjs +1 -1
  53. package/dist/index.d.ts +1 -0
  54. package/dist/index.d.ts.map +1 -1
  55. package/dist/index.js +547 -538
  56. package/dist/input-password.cjs +1 -1
  57. package/dist/input-password.d.ts +17 -9
  58. package/dist/input-password.d.ts.map +1 -1
  59. package/dist/input-password.js +26 -25
  60. package/dist/lib/empty-chip.cjs +1 -0
  61. package/dist/lib/empty-chip.d.ts +4 -0
  62. package/dist/lib/empty-chip.d.ts.map +1 -0
  63. package/dist/lib/empty-chip.js +13 -0
  64. package/dist/pagination.cjs +1 -1
  65. package/dist/pagination.d.ts +3 -0
  66. package/dist/pagination.d.ts.map +1 -1
  67. package/dist/pagination.js +57 -57
  68. package/dist/scroll-area.cjs +1 -1
  69. package/dist/scroll-area.d.ts +15 -6
  70. package/dist/scroll-area.d.ts.map +1 -1
  71. package/dist/scroll-area.js +38 -36
  72. package/dist/select.cjs +2 -2
  73. package/dist/select.d.ts +13 -2
  74. package/dist/select.d.ts.map +1 -1
  75. package/dist/select.js +87 -83
  76. package/dist/typography-heading.cjs +1 -1
  77. package/dist/typography-heading.d.ts +13 -0
  78. package/dist/typography-heading.d.ts.map +1 -1
  79. package/dist/typography-heading.js +32 -21
  80. package/dist/typography-text.cjs +1 -1
  81. package/dist/typography-text.d.ts +14 -0
  82. package/dist/typography-text.d.ts.map +1 -1
  83. package/dist/typography-text.js +35 -24
  84. package/package.json +1 -1
  85. package/src/blocks/empty-state.tsx +9 -21
  86. package/src/components/accordion.tsx +82 -27
  87. package/src/components/button-group.tsx +112 -0
  88. package/src/components/button.tsx +1 -1
  89. package/src/components/card.tsx +38 -3
  90. package/src/components/chart.tsx +63 -18
  91. package/src/components/chip.tsx +83 -10
  92. package/src/components/command.tsx +55 -3
  93. package/src/components/data-table.tsx +67 -7
  94. package/src/components/date-picker.tsx +18 -7
  95. package/src/components/field.tsx +81 -12
  96. package/src/components/global-layout.tsx +176 -38
  97. package/src/components/grid.tsx +2 -2
  98. package/src/components/input-password.tsx +23 -11
  99. package/src/components/pagination.tsx +10 -3
  100. package/src/components/scroll-area.tsx +23 -10
  101. package/src/components/select.tsx +30 -6
  102. package/src/components/typography-heading.tsx +24 -0
  103. package/src/components/typography-text.tsx +26 -1
  104. package/src/index.ts +1 -0
  105. package/src/lib/empty-chip.ts +24 -0
@@ -200,13 +200,37 @@ function ChartStyle({ id, config }: { id: string; config: ChartConfig }) {
200
200
  // Chart Tooltip
201
201
  // ============================================================================
202
202
 
203
+ /**
204
+ * A single entry of the Recharts tooltip payload, as `ChartTooltipContent`
205
+ * receives it. This is the `item` argument given to `formatter` and the
206
+ * element type of the `payload` arrays given to `formatter` and
207
+ * `labelFormatter`, so consumers can read e.g. `item.color` or
208
+ * `item.payload` without hand-rolled narrowing.
209
+ */
210
+ interface ChartTooltipPayloadItem {
211
+ /** The series `dataKey` this row belongs to. */
212
+ dataKey?: string | number;
213
+ /** The row's value. `undefined` when the datum carries no value. */
214
+ value?: number | string;
215
+ /** The series name Recharts resolves for this row. */
216
+ name?: string;
217
+ /** The series stroke colour Recharts injects. */
218
+ color?: string;
219
+ /** The series fill colour Recharts injects (bars, pie slices). */
220
+ fill?: string;
221
+ /** The underlying data point for this row. */
222
+ payload: Record<string, unknown>;
223
+ }
224
+
203
225
  /**
204
226
  * Whether a tooltip row has a value worth printing. Zero is a real value and
205
227
  * must render; NaN/Infinity (a dataKey over a non-numeric field, a ratio with
206
228
  * a zero denominator) and blank strings have nothing to show, so the value
207
229
  * slot stays empty rather than reading "NaN".
208
230
  */
209
- function isRenderableValue(value: unknown): boolean {
231
+ function isRenderableValue(
232
+ value: number | string | null | undefined
233
+ ): value is number | string {
210
234
  if (value == null || value === "") {
211
235
  return false;
212
236
  }
@@ -250,17 +274,33 @@ interface ChartTooltipContentProps
250
274
  ChartTooltipProps,
251
275
  "hideLabel" | "hideIndicator" | "indicator" | "nameKey" | "labelKey"
252
276
  > {
253
- /** Custom label formatter function */
254
- labelFormatter?: (value: unknown, payload: unknown[]) => React.ReactNode;
277
+ /**
278
+ * Custom label formatter function.
279
+ * @param value - The resolved tooltip label (the config label when one
280
+ * matches, otherwise the raw axis label).
281
+ * @param payload - The tooltip payload entries for the hovered datum.
282
+ */
283
+ labelFormatter?: (
284
+ value: React.ReactNode,
285
+ payload: ChartTooltipPayloadItem[]
286
+ ) => React.ReactNode;
255
287
  /** Additional CSS class for the label */
256
288
  labelClassName?: string;
257
- /** Custom value formatter function */
289
+ /**
290
+ * Custom value formatter function. Replaces the default row (indicator,
291
+ * name, and value) for every entry with a renderable value.
292
+ * @param value - The entry's value (`0` is real data and is passed through).
293
+ * @param name - The entry's series name.
294
+ * @param item - The full payload entry (colour, dataKey, data point, …).
295
+ * @param index - The entry's index within the tooltip payload.
296
+ * @param payload - All payload entries for the hovered datum.
297
+ */
258
298
  formatter?: (
259
- value: unknown,
299
+ value: number | string,
260
300
  name: string,
261
- item: unknown,
301
+ item: ChartTooltipPayloadItem,
262
302
  index: number,
263
- payload: unknown[]
303
+ payload: ChartTooltipPayloadItem[]
264
304
  ) => React.ReactNode;
265
305
  }
266
306
 
@@ -283,13 +323,7 @@ function ChartTooltipContent({
283
323
  labelKey,
284
324
  }: ChartTooltipContentProps & {
285
325
  active?: boolean;
286
- payload?: Array<{
287
- dataKey: string;
288
- value: number | string;
289
- name?: string;
290
- color?: string;
291
- payload: Record<string, unknown>;
292
- }>;
326
+ payload?: ChartTooltipPayloadItem[];
293
327
  label?: string;
294
328
  color?: string;
295
329
  }) {
@@ -363,8 +397,9 @@ function ChartTooltipContent({
363
397
  "[&>svg]:text-muted-foreground flex w-full flex-wrap items-stretch gap-2",
364
398
  indicator === "dot" && "items-center"
365
399
  )}
400
+ data-slot="chart-tooltip-item"
366
401
  >
367
- {formatter && isRenderableValue(item?.value) && item.name ? (
402
+ {formatter && isRenderableValue(item.value) && item.name ? (
368
403
  formatter(item.value, item.name, item, index, payload)
369
404
  ) : (
370
405
  <>
@@ -392,20 +427,29 @@ function ChartTooltipContent({
392
427
  />
393
428
  )
394
429
  )}
430
+ {/* gap-2 keeps the name and value apart once the row grows
431
+ wider than the tooltip min-width, where justify-between
432
+ alone would render them flush together (DS-897). */}
395
433
  <div
396
434
  className={cn(
397
- "flex flex-1 justify-between leading-none",
435
+ "flex flex-1 justify-between gap-2 leading-none",
398
436
  nestLabel ? "items-end" : "items-center"
399
437
  )}
400
438
  >
401
439
  <div className="grid gap-1.5">
402
440
  {nestLabel ? tooltipLabel : null}
403
- <span className="text-muted-foreground">
441
+ <span
442
+ className="text-muted-foreground"
443
+ data-slot="chart-tooltip-item-name"
444
+ >
404
445
  {itemConfig?.label || item.name}
405
446
  </span>
406
447
  </div>
407
448
  {isRenderableValue(item.value) && (
408
- <span className="text-foreground tabular-nums">
449
+ <span
450
+ className="text-foreground tabular-nums"
451
+ data-slot="chart-tooltip-item-value"
452
+ >
409
453
  {typeof item.value === "number"
410
454
  ? item.value.toLocaleString()
411
455
  : item.value}
@@ -1164,6 +1208,7 @@ export type {
1164
1208
  ChartContainerProps,
1165
1209
  ChartTooltipProps,
1166
1210
  ChartTooltipContentProps,
1211
+ ChartTooltipPayloadItem,
1167
1212
  ChartLegendProps,
1168
1213
  ChartLegendContentProps,
1169
1214
  ChartDotProps,
@@ -18,6 +18,25 @@ import {
18
18
  */
19
19
  type ChipSize = "md" | "lg";
20
20
 
21
+ /**
22
+ * The event a chip removal hands to `onRemove`: a mouse event from the
23
+ * delete button, or a keyboard event from Backspace/Delete on the chip root.
24
+ */
25
+ type ChipRemoveEvent =
26
+ | React.MouseEvent<HTMLButtonElement>
27
+ | React.KeyboardEvent<HTMLDivElement>;
28
+
29
+ /**
30
+ * Removal callback. Declared with the bivariance hack — the same shape React
31
+ * uses for its own event handlers — so handlers annotated against the
32
+ * pre-keyboard, mouse-only contract
33
+ * (`(event: React.MouseEvent<HTMLButtonElement>) => void`) stay assignable
34
+ * under strict function-parameter checking (DS-949).
35
+ */
36
+ type ChipRemoveHandler = {
37
+ bivarianceHack(event: ChipRemoveEvent): void;
38
+ }["bivarianceHack"];
39
+
21
40
  const chipVariants = cva(
22
41
  [
23
42
  // Base styles
@@ -39,7 +58,7 @@ const chipVariants = cva(
39
58
  // Hover state
40
59
  "hover:bg-secondary/80",
41
60
  // Focus state - direct focus on chip (for keyboard navigation)
42
- "focus:outline-none",
61
+ "outline-none",
43
62
  "focus-visible:shadow-default",
44
63
  // Disabled state
45
64
  "disabled:pointer-events-none",
@@ -119,9 +138,10 @@ interface ChipProps extends Omit<React.ComponentProps<"div">, "children"> {
119
138
  */
120
139
  disabled?: boolean;
121
140
  /**
122
- * Callback when delete button is clicked
141
+ * Callback when the chip is removed — via the delete button (click) or
142
+ * the keyboard (Backspace/Delete while the chip is focused).
123
143
  */
124
- onRemove?: (event: React.MouseEvent<HTMLButtonElement>) => void;
144
+ onRemove?: ChipRemoveHandler;
125
145
  /**
126
146
  * Data hook for automated testing (required)
127
147
  */
@@ -146,15 +166,33 @@ interface ChipProps extends Omit<React.ComponentProps<"div">, "children"> {
146
166
  loadingLabel?: string;
147
167
  /**
148
168
  * Accessible label for the remove button.
149
- * Supports `{name}` placeholder for interpolation.
169
+ * Supports `{name}` placeholder for interpolation. The default `{name}` is
170
+ * derived from string or number children; for a JSX label, pass this prop
171
+ * with the resolved name.
150
172
  * @default "Remove {name}"
151
173
  */
152
174
  removeAriaLabel?: string;
175
+ /**
176
+ * Accessible label for the chip itself while it is keyboard-removable
177
+ * (focusable, with the Backspace/Delete removal hint).
178
+ * Supports `{name}` placeholder for interpolation. The default `{name}` is
179
+ * derived from string or number children; for a JSX label, pass this prop
180
+ * with the resolved name.
181
+ * @default "{name}, press Delete to remove"
182
+ */
183
+ removableAriaLabel?: string;
153
184
  }
154
185
 
155
186
  /**
156
187
  * Chip component for displaying removable tags or selections.
157
188
  * Used for filter selections, tag lists, and multi-select values.
189
+ *
190
+ * A removable chip is a single tab stop: the chip itself takes focus and
191
+ * Backspace/Delete removes it (DS-949). The delete button stays mouse-only
192
+ * (`tabIndex={-1}`) so each chip costs one tab stop, not two. When a removal
193
+ * unmounts the focused chip, the consumer hands focus onward per the
194
+ * Filtering pattern's cascade: source control → filter trigger → results
195
+ * region — never `<body>`.
158
196
  */
159
197
  const Chip = React.forwardRef<HTMLDivElement, ChipProps>(
160
198
  (
@@ -171,12 +209,32 @@ const Chip = React.forwardRef<HTMLDivElement, ChipProps>(
171
209
  maxWidth = 200,
172
210
  loadingLabel,
173
211
  removeAriaLabel,
212
+ removableAriaLabel,
213
+ onKeyDown,
174
214
  ...props
175
215
  },
176
216
  ref
177
217
  ) => {
178
218
  const isDisabled = disabled || loading;
179
219
  const iconSize = size === "lg" ? 16 : 14;
220
+ // The {name} fallback is derived from plain-text children only; a JSX
221
+ // label must supply removeAriaLabel/removableAriaLabel itself.
222
+ const chipName =
223
+ typeof children === "string" || typeof children === "number"
224
+ ? String(children)
225
+ : "chip";
226
+ const removable = onRemove !== undefined && !isDisabled;
227
+
228
+ const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
229
+ onKeyDown?.(event);
230
+ // A composing parent (InputChip's roving focus) that already handled
231
+ // the key marks it consumed via preventDefault.
232
+ if (event.defaultPrevented || !removable) return;
233
+ if (event.key === "Backspace" || event.key === "Delete") {
234
+ event.preventDefault();
235
+ onRemove(event);
236
+ }
237
+ };
180
238
  const labelRef = React.useRef<HTMLSpanElement>(null);
181
239
  const [isTruncated, setIsTruncated] = React.useState(false);
182
240
 
@@ -206,14 +264,32 @@ const Chip = React.forwardRef<HTMLDivElement, ChipProps>(
206
264
  );
207
265
 
208
266
  return (
267
+ /* Keyboard removal lives on the chip root: when removable it carries
268
+ role="group" and tabIndex=0 below — the rule can't see the
269
+ conditional role. */
270
+ // eslint-disable-next-line jsx-a11y/no-static-element-interactions
209
271
  <div
210
272
  ref={ref}
211
273
  aria-disabled={isDisabled ? "true" : undefined}
274
+ // Keyboard-removable chips are focusable and announce the removal
275
+ // hint. A composing parent (InputChip) overrides all three via
276
+ // props — the spread below wins.
277
+ aria-label={
278
+ removable
279
+ ? (removableAriaLabel ?? "{name}, press Delete to remove").replace(
280
+ "{name}",
281
+ chipName
282
+ )
283
+ : undefined
284
+ }
212
285
  className={cn(chipVariants({ size }), className)}
213
286
  data-hook={dataHook}
214
287
  data-slot="chip"
215
288
  data-tracking-el={trackingEl}
216
289
  data-tracking-label={trackingLabel}
290
+ role={removable ? "group" : undefined}
291
+ tabIndex={removable ? 0 : undefined}
292
+ onKeyDown={handleKeyDown}
217
293
  {...props}
218
294
  >
219
295
  {isTruncated ? (
@@ -241,11 +317,8 @@ const Chip = React.forwardRef<HTMLDivElement, ChipProps>(
241
317
  <button
242
318
  aria-label={
243
319
  removeAriaLabel
244
- ? removeAriaLabel.replace(
245
- "{name}",
246
- typeof children === "string" ? children : "chip"
247
- )
248
- : `Remove ${typeof children === "string" ? children : "chip"}`
320
+ ? removeAriaLabel.replace("{name}", chipName)
321
+ : `Remove ${chipName}`
249
322
  }
250
323
  className={cn(chipDeleteButtonVariants({ size }))}
251
324
  data-slot="chip-delete"
@@ -266,4 +339,4 @@ const Chip = React.forwardRef<HTMLDivElement, ChipProps>(
266
339
  Chip.displayName = "Chip";
267
340
 
268
341
  export { Chip, chipVariants };
269
- export type { ChipProps, ChipSize };
342
+ export type { ChipProps, ChipRemoveEvent, ChipRemoveHandler, ChipSize };
@@ -10,6 +10,8 @@ import { Button } from "@brightlocal/ui-components/button";
10
10
  import { cn } from "@brightlocal/ui-components/lib/utils";
11
11
  import { useDevWarning } from "@brightlocal/ui-components/lib/use-dev-warning";
12
12
 
13
+ import { emptyChipStyles } from "../lib/empty-chip";
14
+
13
15
  /* -------------------------------------------------------------------------------------------------
14
16
  * Command Context — shared state between CommandInput and CommandVirtualList
15
17
  * -----------------------------------------------------------------------------------------------*/
@@ -328,15 +330,37 @@ export interface CommandEmptyProps extends React.ComponentProps<
328
330
  * Data hook for automated testing
329
331
  */
330
332
  dataHook?: string;
333
+ /**
334
+ * Icon shown in the muted chip above the message — the same chip as
335
+ * EmptyState, so the popover form matches the card and page forms
336
+ * (Patterns/Empty States). Decorative; the message carries the state.
337
+ */
338
+ icon?: React.ReactNode;
339
+ /**
340
+ * One quiet muted line under the message, e.g. "Try a different search."
341
+ */
342
+ description?: React.ReactNode;
331
343
  }
332
344
 
333
345
  /**
334
- * Empty state displayed when no results are found.
346
+ * Empty state displayed when no results are found. Plain `children` render
347
+ * the one-line form; pass `icon` and/or `description` for the compact form
348
+ * the Empty States pattern uses at popover scope — never hand-roll it.
349
+ *
350
+ * @example
351
+ * ```tsx
352
+ * <CommandEmpty
353
+ * description="Try a different search."
354
+ * icon={<SearchX />}
355
+ * >
356
+ * No locations match “{search}”
357
+ * </CommandEmpty>
358
+ * ```
335
359
  */
336
360
  const CommandEmpty = React.forwardRef<
337
361
  React.ComponentRef<typeof CommandPrimitive.Empty>,
338
362
  CommandEmptyProps
339
- >(({ dataHook, ...props }, ref) => {
363
+ >(({ children, dataHook, description, icon, ...props }, ref) => {
340
364
  // cmdk hardcodes role="presentation" after spreading props, so we
341
365
  // override it via a callback ref to satisfy the listbox a11y contract
342
366
  // (role="listbox" requires option or group children).
@@ -358,7 +382,35 @@ const CommandEmpty = React.forwardRef<
358
382
  data-hook={dataHook}
359
383
  data-slot="command-empty"
360
384
  {...props}
361
- />
385
+ >
386
+ {icon || description ? (
387
+ /* The compact form. Inside role="option" the content is
388
+ presentational, so the message stays a plain line — never a
389
+ heading — and the chip is aria-hidden. */
390
+ <div className="flex flex-col items-center gap-1 px-4">
391
+ {icon ? (
392
+ <span
393
+ aria-hidden="true"
394
+ className={cn(emptyChipStyles(), "mb-1")}
395
+ data-slot="command-empty-icon"
396
+ >
397
+ {icon}
398
+ </span>
399
+ ) : null}
400
+ <p data-slot="command-empty-message">{children}</p>
401
+ {description ? (
402
+ <p
403
+ className="text-muted-foreground"
404
+ data-slot="command-empty-description"
405
+ >
406
+ {description}
407
+ </p>
408
+ ) : null}
409
+ </div>
410
+ ) : (
411
+ children
412
+ )}
413
+ </CommandPrimitive.Empty>
362
414
  );
363
415
  });
364
416
  CommandEmpty.displayName = "CommandEmpty";
@@ -60,6 +60,7 @@ import {
60
60
  } from "@brightlocal/icons";
61
61
 
62
62
  import { cn } from "@brightlocal/ui-components/lib/utils";
63
+ import { useIsBelowBreakpoint } from "@brightlocal/ui-components/hooks/use-breakpoint";
63
64
  import { Button } from "./button";
64
65
  import { Checkbox } from "./checkbox";
65
66
  import { InputGroup, InputGroupAddon, InputGroupInput } from "./input-group";
@@ -1052,6 +1053,20 @@ export interface DataTableColumnHeaderProps<
1052
1053
  * Falls back to a non-interactive label when the column is not sortable.
1053
1054
  * Otherwise renders a ghost button that toggles sort on click, with an
1054
1055
  * accessible label describing the current sort state.
1056
+ *
1057
+ * **First-click direction:** clicking an unsorted column starts ascending
1058
+ * (A–Z, lowest first). Numeric columns (counts, rates, scores) usually want
1059
+ * highest-first on the first click — opt in per column with TanStack's
1060
+ * `sortDescFirst` on the column def:
1061
+ *
1062
+ * ```tsx
1063
+ * { accessorKey: "score", sortDescFirst: true, header: ... }
1064
+ * ```
1065
+ *
1066
+ * Only an explicit `sortDescFirst` is honoured — TanStack's automatic
1067
+ * "numbers sort descending first" detection is deliberately not consulted,
1068
+ * so tables that do not opt in keep first-click-ascending. Once a column is
1069
+ * sorted, clicking again reverses the direction as before.
1055
1070
  */
1056
1071
  export function DataTableColumnHeader<TData, TValue>({
1057
1072
  column,
@@ -1083,6 +1098,14 @@ export function DataTableColumnHeader<TData, TValue>({
1083
1098
  }
1084
1099
 
1085
1100
  const sortState = column.getIsSorted();
1101
+ // First click on an unsorted column follows the column def's explicit
1102
+ // `sortDescFirst`; later clicks reverse the current direction. TanStack's
1103
+ // `getFirstSortDir()` is not used here — its automatic numeric detection
1104
+ // would silently flip existing tables to descending-first (DS-953).
1105
+ const nextSortDesc =
1106
+ sortState === false
1107
+ ? column.columnDef.sortDescFirst === true
1108
+ : sortState === "asc";
1086
1109
  const sortLabel = getSortLabel
1087
1110
  ? getSortLabel(title, sortState)
1088
1111
  : sortState === "desc"
@@ -1109,7 +1132,7 @@ export function DataTableColumnHeader<TData, TValue>({
1109
1132
  dataHook={dataHook || `column-header-${column.id}`}
1110
1133
  size="sm"
1111
1134
  variant="ghost"
1112
- onClick={() => column.toggleSorting(sortState === "asc")}
1135
+ onClick={() => column.toggleSorting(nextSortDesc)}
1113
1136
  >
1114
1137
  <span aria-hidden="true">{title}</span>
1115
1138
  <span
@@ -1369,6 +1392,8 @@ export interface DataTablePaginationRowCountProps {
1369
1392
  *
1370
1393
  * Renders "start–end of total" by default. Pass `renderText` for i18n-friendly
1371
1394
  * custom text with full control over wording, pluralization, and order.
1395
+ * Renders nothing below the `sm` viewport breakpoint — on small screens the
1396
+ * label is removed so the page buttons get the full width (DS-998).
1372
1397
  *
1373
1398
  * Must be rendered inside `<DataTablePagination>`.
1374
1399
  */
@@ -1377,8 +1402,14 @@ function DataTablePaginationRowCount({
1377
1402
  className,
1378
1403
  }: DataTablePaginationRowCountProps) {
1379
1404
  const { info } = useDataTablePaginationContext();
1405
+ const isMobile = useIsBelowBreakpoint("sm");
1380
1406
  const { startRow, endRow, totalRows, pageIndex, pageSize } = info;
1381
1407
 
1408
+ // Below `sm` the label is removed so the page buttons get the full width
1409
+ // and centre (DS-998) — same rule as the default layout and
1410
+ // `PaginationControls`.
1411
+ if (isMobile) return null;
1412
+
1382
1413
  const content = renderText
1383
1414
  ? renderText({ startRow, endRow, totalRows, pageIndex, pageSize })
1384
1415
  : totalRows === 0
@@ -1389,7 +1420,10 @@ function DataTablePaginationRowCount({
1389
1420
 
1390
1421
  return (
1391
1422
  <span
1392
- className={cn("text-body-sm text-muted-foreground", className)}
1423
+ className={cn(
1424
+ "text-body-sm text-muted-foreground whitespace-nowrap",
1425
+ className
1426
+ )}
1393
1427
  data-slot="data-table-pagination-row-count"
1394
1428
  >
1395
1429
  {content}
@@ -1417,7 +1451,8 @@ export interface DataTablePaginationNavProps {
1417
1451
  *
1418
1452
  * Renders previous/next buttons and page links. Renders nothing when there
1419
1453
  * is at most one page — navigation controls are noise when there is nowhere
1420
- * to navigate. Must be rendered inside `<DataTablePagination>`.
1454
+ * to navigate. Below the `sm` viewport breakpoint the buttons centre in the
1455
+ * available width (DS-998). Must be rendered inside `<DataTablePagination>`.
1421
1456
  */
1422
1457
  function DataTablePaginationNav({
1423
1458
  ariaLabel = "Table pagination",
@@ -1425,6 +1460,7 @@ function DataTablePaginationNav({
1425
1460
  className,
1426
1461
  }: DataTablePaginationNavProps) {
1427
1462
  const { info } = useDataTablePaginationContext();
1463
+ const isMobile = useIsBelowBreakpoint("sm");
1428
1464
 
1429
1465
  const paginationItems = usePagination({
1430
1466
  page: info.currentPage,
@@ -1438,7 +1474,9 @@ function DataTablePaginationNav({
1438
1474
  return (
1439
1475
  <Pagination
1440
1476
  ariaLabel={ariaLabel}
1441
- className={cn("mx-0 w-auto justify-end", className)}
1477
+ // Below `sm` keep the base centred layout (the row count is removed
1478
+ // there); at `sm` and up hug the content and align right.
1479
+ className={cn(!isMobile && "mx-0 w-auto justify-end", className)}
1442
1480
  dataHook={dataHook ?? "pagination-nav"}
1443
1481
  >
1444
1482
  <PaginationContent>
@@ -1551,6 +1589,20 @@ export interface DataTablePaginationProps<TData> {
1551
1589
  * row count and the nav are empty, the component renders nothing — no
1552
1590
  * consumer render gate needed.
1553
1591
  *
1592
+ * **Responsive behaviour:** below the `sm` viewport breakpoint the row-count
1593
+ * label is removed and the page buttons centre in the available width — the
1594
+ * same rule `PaginationControls` follows for its caption. This applies to
1595
+ * both layouts: the default row count and `DataTablePaginationRowCount`
1596
+ * render nothing below `sm`, and `DataTablePaginationNav` centres itself.
1597
+ * From `sm` up the bar wraps inside narrow containers: when the row count
1598
+ * and the page buttons no longer fit on one line, the buttons move to their
1599
+ * own line below the row count — no consumer layout classes needed. The row
1600
+ * of page buttons itself does not wrap or shrink, so the **minimum supported
1601
+ * container width** is the width of the button row: **300px** below the `sm`
1602
+ * viewport breakpoint (compact five-slot list) and **388px** from `sm` up
1603
+ * (seven-slot list). Narrower containers than that are outside the
1604
+ * component's supported range (DS-998).
1605
+ *
1554
1606
  * **Compositional mode** (with children): acts as a context provider.
1555
1607
  * Compose `DataTablePaginationRowCount` and `DataTablePaginationNav`
1556
1608
  * in any order/layout.
@@ -1588,6 +1640,7 @@ export function DataTablePagination<TData>({
1588
1640
  children,
1589
1641
  }: DataTablePaginationProps<TData>) {
1590
1642
  const info = useDataTablePagination(table);
1643
+ const isMobile = useIsBelowBreakpoint("sm");
1591
1644
 
1592
1645
  const contextValue = React.useMemo<DataTablePaginationContextValue>(
1593
1646
  () => ({ info }),
@@ -1605,7 +1658,10 @@ export function DataTablePagination<TData>({
1605
1658
  return (
1606
1659
  <DataTablePaginationContext.Provider value={contextValue}>
1607
1660
  <div
1608
- className={cn("flex w-full items-center gap-4", className)}
1661
+ className={cn(
1662
+ "flex w-full flex-wrap items-center gap-x-4 gap-y-2",
1663
+ className
1664
+ )}
1609
1665
  {...wrapperDataAttrs}
1610
1666
  >
1611
1667
  {children}
@@ -1615,6 +1671,9 @@ export function DataTablePagination<TData>({
1615
1671
  }
1616
1672
 
1617
1673
  const rowCountContent = (() => {
1674
+ // Below `sm` the label is removed so the page buttons get the full width
1675
+ // and centre (DS-998).
1676
+ if (isMobile) return null;
1618
1677
  if (!showRowCount) return null;
1619
1678
  if (renderRowCount === null) return null;
1620
1679
  if (renderRowCount) {
@@ -1638,19 +1697,20 @@ export function DataTablePagination<TData>({
1638
1697
  <DataTablePaginationContext.Provider value={contextValue}>
1639
1698
  <div
1640
1699
  className={cn(
1641
- "flex min-h-9 w-full items-center gap-4",
1700
+ "flex min-h-9 w-full flex-wrap items-center gap-x-4 gap-y-2",
1642
1701
  rowCountContent != null ? "justify-between" : "justify-end",
1643
1702
  className
1644
1703
  )}
1645
1704
  {...wrapperDataAttrs}
1646
1705
  >
1647
1706
  {rowCountContent != null && (
1648
- <span className="text-body-sm text-muted-foreground">
1707
+ <span className="text-body-sm text-muted-foreground whitespace-nowrap">
1649
1708
  {rowCountContent}
1650
1709
  </span>
1651
1710
  )}
1652
1711
  <DataTablePaginationNav
1653
1712
  ariaLabel={ariaLabel}
1713
+ className="grow"
1654
1714
  dataHook={`${dataHook}-nav`}
1655
1715
  />
1656
1716
  </div>
@@ -77,17 +77,17 @@ function useDatePickerContext() {
77
77
  const context = React.useContext(DatePickerContext);
78
78
  if (!context) {
79
79
  throw new Error(
80
- "DatePicker compound components must be used within DatePickerRoot"
80
+ "DatePicker compound components must be used within DatePicker"
81
81
  );
82
82
  }
83
83
  return context;
84
84
  }
85
85
 
86
86
  // ============================================================================
87
- // DatePickerRoot
87
+ // DatePicker (root)
88
88
  // ============================================================================
89
89
 
90
- export interface DatePickerRootProps {
90
+ export interface DatePickerProps {
91
91
  /**
92
92
  * Data hook for automated testing (REQUIRED)
93
93
  */
@@ -155,9 +155,9 @@ export interface DatePickerRootProps {
155
155
  }
156
156
 
157
157
  /**
158
- * DatePickerRoot - Root component that provides context for all DatePicker parts
158
+ * DatePicker - Root component that provides context for all DatePicker parts
159
159
  */
160
- function DatePickerRoot({
160
+ function DatePicker({
161
161
  children,
162
162
  dataHook,
163
163
  trackingEl,
@@ -173,7 +173,7 @@ function DatePickerRoot({
173
173
  open: controlledOpen,
174
174
  onOpenChange,
175
175
  defaultOpen = false,
176
- }: DatePickerRootProps) {
176
+ }: DatePickerProps) {
177
177
  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen);
178
178
 
179
179
  const isControlled = controlledOpen !== undefined;
@@ -235,7 +235,17 @@ function DatePickerRoot({
235
235
  );
236
236
  }
237
237
 
238
- DatePickerRoot.displayName = "DatePickerRoot";
238
+ DatePicker.displayName = "DatePicker";
239
+
240
+ /**
241
+ * @deprecated Use `DatePicker` instead — family roots are bare names (DS-853).
242
+ */
243
+ const DatePickerRoot = DatePicker;
244
+
245
+ /**
246
+ * @deprecated Use `DatePickerProps` instead — family roots are bare names (DS-853).
247
+ */
248
+ export type DatePickerRootProps = DatePickerProps;
239
249
 
240
250
  // ============================================================================
241
251
  // DatePickerTrigger
@@ -594,6 +604,7 @@ DatePickerPresets.displayName = "DatePickerPresets";
594
604
  // ============================================================================
595
605
 
596
606
  export {
607
+ DatePicker,
597
608
  DatePickerRoot,
598
609
  DatePickerTrigger,
599
610
  DatePickerContent,