@djangocfg/ui-tools 2.1.412 → 2.1.413

package/src/tools/data/Listbox/parts/ListboxGroup.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { useComposedRefs } from "@djangocfg/ui-core/lib";
+import { cn } from "@djangocfg/ui-core/lib";
+import type { ListboxGroupProps, ListboxGroupLabelProps } from "../types";
+
+const GROUP_NAME = "ListboxGroup";
+const GROUP_LABEL_NAME = "ListboxGroupLabel";
+
+interface ListboxGroupContextValue {
+  id: string;
+  labelId: string;
+}
+
+const ListboxGroupContext = React.createContext<ListboxGroupContextValue | null>(null);
+ListboxGroupContext.displayName = GROUP_NAME;
+
+function useListboxGroupContext(name: string) {
+  const context = React.useContext(ListboxGroupContext);
+  if (!context) {
+    throw new Error(`\`${name}\` must be used within \`${GROUP_NAME}\``);
+  }
+  return context;
+}
+
+const ListboxGroup = React.forwardRef<HTMLDivElement, ListboxGroupProps>(
+  (props, forwardedRef) => {
+    const { asChild, className, ...groupProps } = props;
+    const id = React.useId();
+    const labelId = React.useId();
+
+    const groupContextValue = React.useMemo(() => ({ id, labelId }), [id, labelId]);
+    const GroupPrimitive = asChild ? Slot : "div";
+
+    return (
+      <ListboxGroupContext.Provider value={groupContextValue}>
+        <GroupPrimitive
+          role="group"
+          id={id}
+          aria-labelledby={labelId}
+          className={cn("", className)}
+          {...groupProps}
+          ref={forwardedRef}
+        />
+      </ListboxGroupContext.Provider>
+    );
+  },
+);
+ListboxGroup.displayName = GROUP_NAME;
+
+const ListboxGroupLabel = React.forwardRef<HTMLDivElement, ListboxGroupLabelProps>(
+  (props, forwardedRef) => {
+    const { asChild, className, ...labelProps } = props;
+    const groupContext = useListboxGroupContext(GROUP_LABEL_NAME);
+    const LabelPrimitive = asChild ? Slot : "div";
+
+    return (
+      <LabelPrimitive
+        id={groupContext.labelId}
+        className={cn("px-2 py-1.5 text-sm font-semibold text-muted-foreground", className)}
+        {...labelProps}
+        ref={forwardedRef}
+      />
+    );
+  },
+);
+ListboxGroupLabel.displayName = GROUP_LABEL_NAME;
+
+export { ListboxGroup, ListboxGroupLabel, useListboxGroupContext, ListboxGroupContext };

package/src/tools/data/Listbox/parts/ListboxItem.tsx

@@ -0,0 +1,151 @@
+"use client";
+
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { useComposedRefs } from "@djangocfg/ui-core/lib";
+import { composeEventHandlers } from "@djangocfg/ui-core/lib";
+import { cn } from "@djangocfg/ui-core/lib";
+import { useListboxContext, useListboxState } from "../context/ListboxProvider";
+import { ListboxGroupContext } from "./ListboxGroup";
+import type { ListboxItemProps, ListboxItemIndicatorProps } from "../types";
+
+const ITEM_NAME = "ListboxItem";
+const ITEM_INDICATOR_NAME = "ListboxItemIndicator";
+
+const ListboxItemContext = React.createContext<{ isSelected: boolean } | null>(null);
+ListboxItemContext.displayName = ITEM_NAME;
+
+function useListboxItemContext(name: string) {
+  const context = React.useContext(ListboxItemContext);
+  if (!context) {
+    throw new Error(`\`${name}\` must be used within \`${ITEM_NAME}\``);
+  }
+  return context;
+}
+
+const useIsomorphicLayoutEffect = typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect;
+
+const ListboxItem = React.forwardRef<HTMLDivElement, ListboxItemProps>(
+  (props, forwardedRef) => {
+    const { asChild, value, disabled = false, onSelect, className, ...itemProps } = props;
+    const context = useListboxContext(ITEM_NAME);
+    const groupContext = React.useContext(ListboxGroupContext);
+    const itemRef = React.useRef<HTMLDivElement>(null);
+    const composedRef = useComposedRefs(itemRef, forwardedRef);
+
+    const isSelected = useListboxState((state) => state.selectedValues.has(value));
+    const isHighlighted = useListboxState((state) => state.highlightedValue === value);
+    const isDisabled = disabled || context.disabled;
+
+    useIsomorphicLayoutEffect(() => {
+      if (value === "") {
+        throw new Error(`${ITEM_NAME} value cannot be an empty string`);
+      }
+      return context.onItemRegister(
+        { ref: itemRef, value, disabled: isDisabled, onSelect },
+        groupContext?.id,
+      );
+    }, [value, isDisabled, context.onItemRegister, groupContext?.id, onSelect]);
+
+    const onBlur = React.useCallback(() => {
+      context.onItemBlur();
+    }, [context.onItemBlur]);
+
+    const onClick = React.useCallback(
+      (event: React.MouseEvent) => {
+        if (!isDisabled) {
+          const isMultipleSelectionKey =
+            context.multiple && (context.multiple === true || event.ctrlKey || event.metaKey);
+          context.onItemSelect(value, isMultipleSelectionKey);
+        }
+      },
+      [context.onItemSelect, value, isDisabled, context.multiple],
+    );
+
+    const onFocus = React.useCallback(() => {
+      if (!isDisabled) {
+        context.onItemFocus(value);
+        context.onItemHighlight(value);
+      }
+    }, [context.onItemFocus, context.onItemHighlight, isDisabled, value]);
+
+    const onKeyDown = React.useCallback(
+      (event: React.KeyboardEvent) => {
+        if (event.key === "Tab") {
+          if (!event.shiftKey) {
+            context.onItemBlur();
+          }
+          return;
+        }
+      },
+      [context.onItemBlur],
+    );
+
+    const onPointerLeave = React.useCallback(() => {
+      context.onItemHighlight(null);
+    }, [context.onItemHighlight]);
+
+    const onPointerMove = React.useCallback(() => {
+      if (!isDisabled) {
+        context.onItemHighlight(value);
+      }
+    }, [context.onItemHighlight, isDisabled, value]);
+
+    const ItemPrimitive = asChild ? Slot : "div";
+
+    const itemContextValue = React.useMemo(() => ({ isSelected }), [isSelected]);
+
+    return (
+      <ListboxItemContext.Provider value={itemContextValue}>
+        <ItemPrimitive
+          role="option"
+          aria-selected={isSelected}
+          data-selected={isSelected ? "" : undefined}
+          data-highlighted={isHighlighted ? "" : undefined}
+          data-disabled={isDisabled ? "" : undefined}
+          tabIndex={isDisabled ? undefined : -1}
+          className={cn(
+            "relative flex cursor-pointer items-center rounded-sm px-2 py-1.5 text-sm outline-none transition-colors",
+            "hover:bg-accent hover:text-accent-foreground",
+            "focus:bg-accent focus:text-accent-foreground",
+            isSelected && "bg-accent text-accent-foreground",
+            isDisabled && "pointer-events-none opacity-50",
+            className,
+          )}
+          {...itemProps}
+          ref={composedRef}
+          onClick={composeEventHandlers(itemProps.onClick, onClick)}
+          onFocus={composeEventHandlers(itemProps.onFocus, onFocus)}
+          onBlur={composeEventHandlers(itemProps.onBlur, onBlur)}
+          onKeyDown={composeEventHandlers(itemProps.onKeyDown, onKeyDown)}
+          onPointerLeave={composeEventHandlers(itemProps.onPointerLeave, onPointerLeave)}
+          onPointerMove={composeEventHandlers(itemProps.onPointerMove, onPointerMove)}
+        />
+      </ListboxItemContext.Provider>
+    );
+  },
+);
+ListboxItem.displayName = ITEM_NAME;
+
+const ListboxItemIndicator = React.forwardRef<HTMLSpanElement, ListboxItemIndicatorProps>(
+  (props, forwardedRef) => {
+    const { forceMount = false, asChild, className, ...indicatorProps } = props;
+    const itemContext = useListboxItemContext(ITEM_INDICATOR_NAME);
+
+    if (!forceMount && !itemContext.isSelected) return null;
+
+    const IndicatorPrimitive = asChild ? Slot : "span";
+
+    return (
+      <IndicatorPrimitive
+        aria-hidden="true"
+        className={cn("mr-2 inline-flex size-4 items-center justify-center", className)}
+        {...indicatorProps}
+        ref={forwardedRef}
+      />
+    );
+  },
+);
+ListboxItemIndicator.displayName = ITEM_INDICATOR_NAME;
+
+export { ListboxItem, ListboxItemIndicator, useListboxItemContext, ListboxItemContext };

package/src/tools/data/Listbox/parts/index.ts

@@ -0,0 +1,12 @@
+"use client";
+
+export {
+  ListboxGroup,
+  ListboxGroupLabel,
+  useListboxGroupContext,
+} from "./ListboxGroup";
+export {
+  ListboxItem,
+  ListboxItemIndicator,
+  useListboxItemContext,
+} from "./ListboxItem";

package/src/tools/data/Listbox/types.ts

@@ -0,0 +1,98 @@
+"use client";
+
+import * as React from "react";
+
+export type ListboxValue<Multiple extends boolean = false> = Multiple extends true
+  ? string[]
+  : string;
+
+export interface ListboxState {
+  selectedValues: Set<string>;
+  focusedValue: string | null;
+  highlightedValue: string | null;
+}
+
+export type StoreListener = () => void;
+export type StoreStateSelector<T> = (state: ListboxState) => T;
+
+export interface ListboxStore {
+  onSubscribe: (callback: StoreListener) => () => void;
+  getSnapshot: () => ListboxState;
+  onStateChange: <K extends keyof ListboxState>(
+    key: K,
+    value: ListboxState[K],
+    silent?: boolean,
+  ) => void;
+  onEmit: () => void;
+  onSelectedStateChange: (value: string, multiple?: boolean) => void;
+  onClearSelection: () => void;
+  onHighlightedValueChange: (value: string | null) => void;
+}
+
+export interface ItemData {
+  value: string;
+  disabled?: boolean;
+  onSelect?: (value: string) => void;
+}
+
+export type ItemElement = HTMLDivElement;
+
+export interface CollectionItem extends ItemData {
+  ref: React.RefObject<ItemElement | null>;
+}
+
+export type CollectionItemMap = Map<
+  React.RefObject<ItemElement | null>,
+  CollectionItem
+>;
+
+export type CollectionGroupMap = Map<string, Set<React.RefObject<ItemElement | null>>>;
+
+export interface ListboxContextValue<Multiple extends boolean = false> {
+  store: ListboxStore;
+  onItemRegister: (item: CollectionItem, groupId?: string) => () => void;
+  onItemSelect: (value: string, isMultipleEvent?: boolean) => void;
+  onItemFocus: (value: string) => void;
+  onItemBlur: () => void;
+  onItemHighlight: (value: string | null) => void;
+  dir: "ltr" | "rtl";
+  disabled: boolean;
+  multiple: Multiple;
+}
+
+export interface ListboxRootProps<Multiple extends boolean = false>
+  extends React.ComponentPropsWithoutRef<"div"> {
+  defaultValue?: ListboxValue<Multiple>;
+  value?: ListboxValue<Multiple>;
+  onValueChange?: (value: ListboxValue<Multiple>) => void;
+  dir?: "ltr" | "rtl";
+  asChild?: boolean;
+  disabled?: boolean;
+  loop?: boolean;
+  multiple?: Multiple;
+  virtual?: boolean;
+  orientation?: "horizontal" | "vertical" | "mixed";
+  name?: string;
+}
+
+export interface ListboxGroupProps extends React.ComponentPropsWithoutRef<"div"> {
+  asChild?: boolean;
+}
+
+export interface ListboxGroupLabelProps extends React.ComponentPropsWithoutRef<"div"> {
+  asChild?: boolean;
+}
+
+export interface ListboxItemProps
+  extends Omit<React.ComponentPropsWithoutRef<"div">, "onSelect"> {
+  value: string;
+  disabled?: boolean;
+  asChild?: boolean;
+  onSelect?: (value: string) => void;
+}
+
+export interface ListboxItemIndicatorProps
+  extends React.ComponentPropsWithoutRef<"span"> {
+  forceMount?: boolean;
+  asChild?: boolean;
+}

package/src/tools/data/Masonry/README.md

@@ -0,0 +1,79 @@
+# Masonry
+
+Virtualised Pinterest-style masonry grid. Items of arbitrary heights are
+placed into N columns; each new item lands in the currently-shortest
+column. Window-scroll virtualised — only items within the scroll
+overscan are mounted, so the layout scales to thousands of tiles.
+
+```tsx
+import { Masonry, MasonryItem } from '@djangocfg/ui-tools/masonry';
+
+<Masonry columnCount={3} gap={12}>
+  {items.map((item) => (
+    <MasonryItem key={item.id} className="rounded-md border bg-card p-4">
+      <h4>{item.title}</h4>
+      <p>{item.body}</p>
+    </MasonryItem>
+  ))}
+</Masonry>
+```
+
+## Picking the column model
+
+Pass **either** `columnCount` **or** `columnWidth` — not both.
+
+| Mode | Use when | Behaviour |
+| --- | --- | --- |
+| `columnCount={n}` | You want exactly N columns regardless of width | Column width = `(container - gaps) / n` |
+| `columnWidth={px}` | You want responsive columns | Column count = `floor(container / (px + gap))`, clamped to `maxColumnCount` |
+
+Defaults: `columnWidth=200`, `gap=12`, `overscan=2` (viewports above and below the visible area).
+
+## Rules of use
+
+These come from the window-scroll virtualisation model. Violating them produces an empty or zero-height grid.
+
+1. **Do not wrap `<Masonry>` in a fixed-height ancestor.** It measures `document.documentElement` and `window.scrollY`. Putting it inside `height: 600px; overflow: auto` makes it think the viewport is 600px and breaks scroll detection. If you need a scrollable region, use a non-virtualised CSS-columns grid instead.
+2. **Do not put inline `height` on `<MasonryItem>` children.** The item's content drives measurement via `ResizeObserver`; an inline height stops the observer from reflecting the real layout.
+3. **`fallback` is optional but recommended.** Without it Masonry renders a built-in muted skeleton on the first paint (before items are measured). Pass `fallback={<MySkeleton />}` if you want a specific look.
+
+## Props
+
+```ts
+interface MasonryProps {
+  // Layout
+  columnCount?: number;            // fixed N
+  columnWidth?: number;            // responsive (default 200)
+  maxColumnCount?: number;         // upper bound when columnWidth is used
+  gap?: number | { row: number; column: number };  // default 12
+  linear?: boolean;                // round-robin instead of shortest-column
+
+  // Measurement
+  itemHeight?: number;             // estimate for un-measured items (default 300)
+  defaultWidth?: number;           // SSR fallback width
+  defaultHeight?: number;          // SSR fallback height
+  overscan?: number;               // viewports above/below to render (default 2)
+
+  // Perf
+  scrollFps?: number;              // scroll listener throttle (default 12)
+
+  // UI
+  fallback?: React.ReactNode;      // first-paint placeholder (auto-skeleton if omitted)
+
+  // Standard div props
+  className?: string;
+  style?: React.CSSProperties;
+  asChild?: boolean;
+}
+```
+
+## When *not* to use this
+
+- **You need scrollable-container masonry** (modal, sidebar, side-by-side panes). This component virtualises against `window`. Use a CSS `column-count` grid or a different lib.
+- **You have ≤ 30 items.** Virtualisation overhead isn't worth it — a plain CSS multi-column layout is simpler and SSR-friendly:
+  ```tsx
+  <div className="columns-3 gap-3 [&>*]:break-inside-avoid">
+    {items.map((it) => <Card key={it.id}>…</Card>)}
+  </div>
+  ```
+- **You need drag-and-drop reordering.** Not supported. Pair with `@dnd-kit` on top of an unvirtualised grid instead.