@djangocfg/ui-core 2.1.556 → 2.1.558

package/src/hooks/dom/useHighlight.ts

@@ -0,0 +1,68 @@
+"use client"
+
+import * as React from 'react'
+
+/**
+ * The active-row state for a cmdk list inside a popover, and the scroll that
+ * has to accompany it.
+ *
+ * Two things are going on, and neither works alone:
+ *
+ * 1. **The highlight is controlled.** cmdk otherwise activates the FIRST row,
+ *    so a picker with a selection opens showing the top of the list rather than
+ *    the value it holds. `onValueChange` is mandatory with a controlled value —
+ *    cmdk then stores nothing itself and delegates every move to the caller, so
+ *    omitting it freezes the arrow keys.
+ *
+ * 2. **Opening has to scroll.** cmdk schedules its own `scrollIntoView` when
+ *    the value changes, but the popover keeps its list MOUNTED between opens
+ *    (`sameNodeAcrossOpens: true`), so on the second open nothing re-mounts and
+ *    nothing re-scrolls; on the first, the value is set before 252 rows have
+ *    finished registering and there is nothing to scroll to yet. Measured both
+ *    ways: selection at index 84, `scrollTop` 0. So the scroll is driven from
+ *    the OPEN transition, after a paint, rather than left to the library.
+ *
+ * Ongoing arrow-key movement stays cmdk's own job; this only handles the jump
+ * that opening owes the user.
+ *
+ * ```tsx
+ * const highlight = useHighlight(open, value)
+ * <Command value={highlight.value} onValueChange={highlight.setValue}>
+ *   <CommandList ref={highlight.listRef}>…</CommandList>
+ * </Command>
+ * ```
+ */
+export function useHighlight(open: boolean, selected: string | null | undefined) {
+  const [value, setValue] = React.useState("")
+  const listRef = React.useRef<HTMLDivElement | null>(null)
+
+  // `selected` is read through a ref so that changing the selection does not
+  // re-run the open effect — only the open transition itself should scroll.
+  const selectedRef = React.useRef(selected)
+  selectedRef.current = selected
+
+  React.useEffect(() => {
+    if (!open) return
+    setValue(selectedRef.current ?? "")
+  }, [open])
+
+  // Deliberately NOT `requestAnimationFrame`: a background tab never runs one,
+  // so a popover opened in an inactive window would stay parked at the top
+  // (this is how the bug first showed up — `document.hidden` and no scroll).
+  // A layout effect keyed on the resolved highlight runs as soon as React has
+  // committed the rows, in any tab, and before the browser paints.
+  React.useLayoutEffect(() => {
+    if (!open || !value) return
+    const list = listRef.current
+    if (!list) return
+
+    // The row is found by VALUE rather than by `aria-selected`, which cmdk sets
+    // in its own scheduled pass — by then this effect has already run.
+    const row = list.querySelector(
+      `[cmdk-item][data-value="${CSS.escape(value)}"]`
+    )
+    row?.scrollIntoView({ block: 'nearest' })
+  }, [open, value])
+
+  return { value, setValue, listRef }
+}

package/src/styles/css/presets/dense.css

@@ -15,6 +15,18 @@
   --radius-2xl: calc(0.25rem + 8px);
   --radius-3xl: calc(0.25rem + 12px);
   --radius-4xl: calc(0.25rem + 16px);
+  /* Type scale — a notch tighter than every other preset, which is the whole
+     point of this one. It previously set radii and colours only, so "dense"
+     rendered text at exactly the same size as the rest: the name promised a
+     density the tokens never delivered.
+     In `:root` only; a size does not change with the theme. */
+  --font-size-base: 0.75rem;
+  --font-size-sm: 0.6875rem;
+  --font-size-xs: 0.625rem;
+  --font-size-lg: 0.875rem;
+  --font-size-xl: 1rem;
+  --line-height-base: 1.4;
+
 }
 
 .dark {

package/src/styles/css/presets/ios.css

@@ -57,6 +57,18 @@
   --radius-2xl: calc(0.75rem + 8px);
   --radius-3xl: calc(0.75rem + 12px);
   --radius-4xl: calc(0.75rem + 16px);
+  /* Type scale. Lives in `:root` only — a size is not a colour and does not
+     change with the theme; `macos`/`windows` duplicate it into `.dark`, which
+     is two places to edit for one value.
+     Without these a preset silently inherits base.css (14px body / 13px
+     `text-sm`) while `macos` renders 13/12, so the same component measured a
+     pixel apart depending on which preset an app loaded. */
+  --font-size-base: 0.8125rem;
+  --font-size-sm: 0.75rem;
+  --font-size-xs: 0.6875rem;
+  --font-size-lg: 0.9375rem;
+  --font-size-xl: 1.0625rem;
+
 }
 
 .dark {

package/src/styles/css/presets/soft.css

@@ -23,6 +23,18 @@
   --radius-2xl: calc(1rem + 8px);
   --radius-3xl: calc(1rem + 12px);
   --radius-4xl: calc(1rem + 16px);
+  /* Type scale. Lives in `:root` only — a size is not a colour and does not
+     change with the theme; `macos`/`windows` duplicate it into `.dark`, which
+     is two places to edit for one value.
+     Without these a preset silently inherits base.css (14px body / 13px
+     `text-sm`) while `macos` renders 13/12, so the same component measured a
+     pixel apart depending on which preset an app loaded. */
+  --font-size-base: 0.8125rem;
+  --font-size-sm: 0.75rem;
+  --font-size-xs: 0.6875rem;
+  --font-size-lg: 0.9375rem;
+  --font-size-xl: 1.0625rem;
+
 }
 
 .dark {

package/src/styles/css/utilities/filter-bar.css

@@ -0,0 +1,61 @@
+/**
+ * A row of filter controls, and the pills in it.
+ *
+ * The row owns the height. Every control in it — a pill, a select, a sort menu —
+ * reads `--filter-control-h`, which is what stops a caller restyling somebody
+ * else's component to make one row line up. Both product frontends were doing
+ * exactly that: one overrode `SelectTrigger`, the other `Button size="sm"`.
+ */
+.filter-bar {
+  /* Named so a host can set the row's density once, here, rather than per
+     control. 38px is the height both frontends independently arrived at. */
+  --filter-control-h: 2.375rem;
+
+  container-type: inline-size;
+  container-name: filter-bar;
+
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+/* Horizontal scroll instead of wrapping, for a row that must stay one line. */
+.filter-bar[data-overflow="scroll"] {
+  flex-wrap: nowrap;
+  overflow-x: auto;
+  overscroll-behavior-x: contain;
+  scrollbar-width: none;
+}
+
+.filter-bar[data-overflow="scroll"]::-webkit-scrollbar {
+  display: none;
+}
+
+.filter-bar[data-overflow="scroll"] > * {
+  flex: none;
+}
+
+/**
+ * The label inside a pill, and the rule that hides it.
+ *
+ * It collapses when the ROW runs out of room, not when the window does: a
+ * toolbar in a narrow column on a wide monitor has the same problem as a phone,
+ * and a viewport media query answers neither. Hiding it is `display: none`
+ * rather than the `clip-path: inset(50%)` both projects used — that trick keeps
+ * the text in the accessibility tree while removing it from sight, which reads
+ * fine and measures wrong. The button carries an `aria-label` instead, so the
+ * name survives the collapse by design rather than by accident.
+ *
+ * A pill showing a CHOSEN value keeps its label: "SUV" is the answer, and an
+ * icon alone cannot say which question it answered.
+ */
+@container filter-bar (max-width: 32rem) {
+  .filter-pill:not([data-answered="true"]) .filter-pill-label {
+    display: none;
+  }
+
+  .filter-pill:not([data-answered="true"]) {
+    padding-inline: 0.625rem;
+  }
+}

package/src/styles/css/utilities/overlay.css

@@ -22,3 +22,81 @@
   backdrop-filter: blur(var(--overlay-blur, 0px));
   -webkit-backdrop-filter: blur(var(--overlay-blur, 0px));
 }
+
+/**
+ * The scrolling list inside a popover — a combobox's options, a command menu's
+ * results, any panel long enough to need a limit.
+ *
+ * It is a ROLE, not a size. The 300px ceiling is what reads comfortably; the
+ * real constraint is the gap the popover has to the edge of the window, which
+ * Radix publishes as `--radix-popover-content-available-height` on the content
+ * element. Taking the smaller of the two is what keeps a list opened near the
+ * bottom of the screen from flipping above its trigger and being clipped by the
+ * viewport — the failure this class exists to prevent.
+ *
+ * Outside a popover the Radix variable is unset and the fallback leaves the
+ * plain ceiling, so the class is safe anywhere.
+ *
+ * Override `--popover-scroll-max` (per theme, or on one instance) to raise or
+ * lower the ceiling; the viewport clamp always still applies.
+ *
+ * It must sit on the element that ACTUALLY SCROLLS — for cmdk that is
+ * `CommandList`, whose highlight moves by `scrollIntoView({block:'nearest'})`
+ * and therefore acts on the nearest scrollable ancestor. Capping a wrapper
+ * instead hands the scrolling to a container cmdk cannot see, and the arrow
+ * keys walk the highlight out of view.
+ *
+ * Plain CSS rather than a JIT-scanned utility, for the same reason as
+ * `.bg-overlay` above: it must compile no matter whose source the Tailwind
+ * content scan covers.
+ */
+.popover-scroll-region {
+  /* The VIEWPORT clamp deliberately lives on the panel (`.popover-panel`), not
+     here: this element is only part of the panel, and capping it alone lets the
+     siblings above it — a search input, a header — push the panel past the edge
+     anyway. Measured: available 193px, list 193px, panel 236px, top −35px.
+     Here the job is only the comfortable ceiling plus the actual scrolling;
+     `min-height: 0` is what lets the flex parent shrink it below its content
+     when the viewport, not the ceiling, is the binding constraint. */
+  max-height: var(--popover-scroll-max, 18.75rem);
+  min-height: 0;
+  overflow-y: auto;
+  overflow-x: hidden;
+  overscroll-behavior: contain;
+}
+
+/**
+ * The part of a snapped drawer that is actually on screen.
+ *
+ * With snap points the panel is FULL height and vaul slides it down to the
+ * active point, so everything below that point sits under the bottom edge of
+ * the window. A footer pinned with `mt-auto` therefore pins itself to the
+ * bottom of the PANEL — measured 344px below the viewport, unreachable even
+ * with the body scrolled to its end, which is what made a drawer's submit
+ * button impossible to reach.
+ *
+ * `--snap-point-height` is vaul's offset — how much of the panel is hidden —
+ * so the visible height is what remains. Constraining the content column to it
+ * puts the footer back at the edge the reader can see, at every snap point,
+ * with no JavaScript following the drag.
+ */
+.drawer-snap-viewport {
+  display: flex;
+  flex-direction: column;
+  height: calc(100% - var(--snap-point-height, 0px));
+  min-height: 0;
+}
+
+/**
+ * A popover panel that must never grow past the window.
+ *
+ * `PopoverContent` carries this by default. The height Radix publishes already
+ * accounts for `collisionPadding`, so the panel keeps its gap from the edge,
+ * and the column layout lets a `.popover-scroll-region` child absorb whatever
+ * is left after fixed siblings (search field, footer) have taken their share.
+ */
+.popover-panel {
+  display: flex;
+  flex-direction: column;
+  max-height: var(--radix-popover-content-available-height, none);
+}

package/src/styles/css/utilities/tabs.css

@@ -0,0 +1,53 @@
+/**
+ * The sliding indicator behind a segmented tab list.
+ *
+ * One pill that travels to the selected tab, rather than a highlight that
+ * disappears from one tab and reappears on the next. The movement is what
+ * carries the meaning: these options are mutually exclusive, and the pill is
+ * the single thing being moved between them.
+ *
+ * Position and size arrive as `--tab-indicator-x` / `--tab-indicator-w`, which
+ * the list measures from the active trigger — tabs here are labelled with real
+ * words and are never equal width, so a fixed `--step` (the usual CSS-only
+ * trick) would drift the moment a label changed. Only `transform` and `width`
+ * animate, so the pill stays on the compositor.
+ *
+ * The indicator is a pseudo-element on the LIST rather than a background on the
+ * trigger: a background cannot animate between two different elements, which is
+ * exactly why the default variant popped instead of sliding.
+ */
+.tabs-sliding {
+  position: relative;
+  isolation: isolate;
+}
+
+.tabs-sliding::before {
+  content: "";
+  position: absolute;
+  z-index: -1;
+  top: var(--tab-indicator-inset, 0.25rem);
+  bottom: var(--tab-indicator-inset, 0.25rem);
+  left: 0;
+  width: var(--tab-indicator-w, 0);
+  transform: translate3d(var(--tab-indicator-x, 0), 0, 0);
+  border-radius: var(--tab-indicator-radius, var(--radius-sm));
+  background: var(--tab-indicator-bg, var(--background));
+  box-shadow: var(--tab-indicator-shadow, 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1));
+  transition:
+    transform 260ms cubic-bezier(0.32, 0.72, 0, 1),
+    width 260ms cubic-bezier(0.32, 0.72, 0, 1);
+}
+
+/* Before the first measurement the pill has no width, so there is nothing to
+   see travelling in from the left edge on mount. */
+.tabs-sliding[data-tab-indicator="idle"]::before {
+  opacity: 0;
+}
+
+/* A reader who has asked for less motion gets the destination, not the
+   journey — the pill still marks the right tab, it simply stops sliding. */
+@media (prefers-reduced-motion: reduce) {
+  .tabs-sliding::before {
+    transition: none;
+  }
+}

package/src/styles/css/utilities.css

@@ -12,6 +12,8 @@
 @import './utilities/controls.css';
 @import './utilities/datetime-field.css';
 @import './utilities/step.css';
+@import './utilities/filter-bar.css';
+@import './utilities/tabs.css';
 @import './utilities/animations.css';
 @import './utilities/glass.css';
 @import './utilities/marquee.css';