@primitiv-ui/react 0.1.38 → 0.1.40

package/src/MillerColumns/types.ts

@@ -1,252 +0,0 @@
-import { ComponentProps, KeyboardEvent, ReactNode, Ref } from "react";
-
-import type { Direction } from "../DirectionProvider/types";
-
-/**
- * Shared base for both {@link MillerColumnsRootProps} variants — the native
- * `<div>` attributes (minus `ref`, which the strip owns internally, and
- * `dir`, narrowed below to the {@link Direction} union).
- */
-export type MillerColumnsRootBaseProps = Omit<
-  ComponentProps<"div">,
-  "ref" | "defaultValue" | "dir"
-> & {
-  /**
-   * Reading direction. Under `"rtl"` the horizontal arrow pair is
-   * mirrored — ArrowLeft steps *into* a branch's child column and
-   * ArrowRight walks back out — so navigation follows the visual order.
-   * Inherited from a `DirectionProvider` ancestor when omitted.
-   * @default "ltr"
-   */
-  dir?: Direction;
-  /**
-   * The strip's tree, authored recursively: root
-   * {@link MillerColumnsColumnProps | Column(s)} whose branch
-   * {@link MillerColumnsItemProps | Items} nest further Columns, plus an
-   * optional trailing {@link MillerColumnsPreviewPanelProps | PreviewPanel}.
-   * There is no `items` data prop — the JSX *is* the data.
-   */
-  children: ReactNode;
-};
-
-/**
- * Uncontrolled variant of {@link MillerColumnsRootProps}: the component owns
- * the selection path. Pass `defaultValue` (or omit it to start empty).
- */
-export type MillerColumnsRootUncontrolledProps = MillerColumnsRootBaseProps & {
-  /** Initial selection path on first render, root column first (e.g.
-   * `["docs", "guides"]`). The component owns the path thereafter. */
-  defaultValue?: string[];
-  /** Forbidden in uncontrolled mode — use `defaultValue` instead. */
-  value?: never;
-  /** Forbidden in uncontrolled mode — pass `value` + `onValueChange` to
-   * control the component. */
-  onValueChange?: never;
-};
-
-/**
- * Controlled variant of {@link MillerColumnsRootProps}: the parent owns the
- * selection path. Pass `value` and `onValueChange` together.
- */
-export type MillerColumnsRootControlledProps = MillerColumnsRootBaseProps & {
-  /** Forbidden in controlled mode — use `value` instead. */
-  defaultValue?: never;
-  /** The controlled selection path, root column first. Must be kept in sync
-   * by the parent via `onValueChange`. */
-  value: string[];
-  /** Called with the new selection path whenever the selection changes.
-   * Required in controlled mode. */
-  onValueChange: (path: string[]) => void;
-};
-
-/**
- * Props for {@link MillerColumnsRoot | `MillerColumns.Root`}.
- *
- * Resolves to either {@link MillerColumnsRootUncontrolledProps} or
- * {@link MillerColumnsRootControlledProps} — only one shape is accepted by
- * TypeScript at a time.
- */
-export type MillerColumnsRootProps =
-  | MillerColumnsRootUncontrolledProps
-  | MillerColumnsRootControlledProps;
-
-/**
- * Props for {@link MillerColumnsColumn | `MillerColumns.Column`}, a single
- * vertical list. Rendered element is portal-projected into the Root strip.
- */
-export type MillerColumnsColumnProps = ComponentProps<"div"> & {
-  /** The column's {@link MillerColumnsItemProps | Items} and, optionally, a
-   * {@link MillerColumnsResizeHandleProps | ResizeHandle}. Optional: a
-   * childless branch legitimately opens an empty column, which carries
-   * `data-empty` for the styling layer. */
-  children?: ReactNode;
-};
-
-/**
- * Props for {@link MillerColumnsItem | `MillerColumns.Item`}, a single
- * selectable node within a column.
- *
- * Generic over the rendered element type so `asChild` consumers can type
- * the forwarded `ref` (e.g. `MillerColumns.Item<HTMLAnchorElement>`).
- */
-export type MillerColumnsItemProps<T extends HTMLElement = HTMLDivElement> =
-  Omit<ComponentProps<"div">, "ref"> & {
-    /** Stable identifier used to match this item against the selection path.
-     * The item is selected when the path entry at its depth equals `value`. */
-    value: string;
-    /**
-     * When `true`, the item renders `aria-disabled` / `data-disabled` and is
-     * skipped by roving navigation — it cannot be selected, focused, or
-     * activated.
-     * @default false
-     */
-    disabled?: boolean;
-    /**
-     * Render the cell as a single consumer-supplied child element (e.g. an
-     * `<a>`) instead of the default `<div>`, merging the treeitem ARIA,
-     * handlers, and ref onto it via the {@link Slot} pattern. Any nested
-     * `<MillerColumns.Column>` remains a sibling of the cell element.
-     * @default false
-     */
-    asChild?: boolean;
-    /** The cell content and, for a branch item, a single nested
-     * `<MillerColumns.Column>` (split out by `partitionItemChildren`). */
-    children: ReactNode;
-    /** Forwarded to the rendered element. Defaults to `HTMLDivElement`; when
-     * using `asChild`, specify the child's element type. Composed with the
-     * library's internal ref. */
-    ref?: Ref<T>;
-  };
-
-/**
- * Props for {@link MillerColumnsItemIndicator | `MillerColumns.ItemIndicator`},
- * the branch chevron affordance (renders nothing for leaf items).
- */
-export type MillerColumnsItemIndicatorProps = ComponentProps<"span"> & {
-  /** The glyph to render (e.g. `▸`). Optional. */
-  children?: ReactNode;
-};
-
-/**
- * Props for {@link MillerColumnsResizeHandle | `MillerColumns.ResizeHandle`},
- * the drag-to-resize separator for its containing column.
- */
-export type MillerColumnsResizeHandleProps = ComponentProps<"div"> & {
-  /**
-   * Smallest width the column can be dragged or stepped to, in pixels.
-   * Also published as `aria-valuemin`.
-   * @default 0
-   */
-  minWidth?: number;
-  /**
-   * Largest width the column can be dragged or stepped to, in pixels.
-   * Published as `aria-valuemax` when finite; left unbounded by default,
-   * in which case the attribute is omitted.
-   * @default Infinity
-   */
-  maxWidth?: number;
-  /**
-   * Pixels moved per arrow-key press.
-   * @default 10
-   */
-  step?: number;
-};
-
-/**
- * Props for {@link MillerColumnsPreviewPanel | `MillerColumns.PreviewPanel`},
- * the trailing preview pane.
- */
-export type MillerColumnsPreviewPanelProps = ComponentProps<"div"> & {
-  /** The preview content for the current selection (typically driven by
-   * {@link useMillerColumnsSelection}). */
-  children?: ReactNode;
-  /**
-   * Keep the panel mounted regardless of the selection, instead of following
-   * Finder's rule (a preview only where a selected *leaf* would open a child
-   * column). Use it for a persistent inspector, or to animate the panel in
-   * and out.
-   * @default false
-   */
-  forceMount?: boolean;
-};
-
-/** The current selection, as returned by `useMillerColumnsSelection`. */
-export type MillerColumnsSelection = {
-  /** The full active path — selected item ids, root column first. */
-  path: string[];
-  /** The deepest selected item id, or `undefined` when nothing is selected. */
-  selectedValue: string | undefined;
-};
-
-/** Metadata recorded for each registered item, used for column navigation. */
-export type MillerColumnsItemMeta = {
-  /** The item's stable identifier. */
-  value: string;
-  /** Whether the item is disabled. */
-  disabled: boolean;
-};
-
-/** A depth + value pair locating an item within the strip. */
-export type MillerColumnsItemAddress = {
-  /** The zero-based column depth. */
-  depth: number;
-  /** The item's stable identifier. */
-  value: string;
-};
-
-/** Value shared through the root MillerColumns context. */
-export type MillerColumnsContextValue = {
-  /** The resolved reading direction — the `dir` prop, else the inherited one. */
-  dir: Direction;
-  /** Portal slots keyed by column depth. */
-  slots: Map<number, HTMLElement>;
-  /** Per-depth column widths set via the resize handle. */
-  columnWidths: Map<number, number>;
-  /** Record a column's width at the given depth. */
-  setColumnWidth: (depth: number, width: number) => void;
-  /** The active selection path. */
-  activePath: string[];
-  /** Select the item at the given depth and value. */
-  select: (depth: number, value: string) => void;
-  /** Register (or unregister, with a `null` element) an item. */
-  registerItem: (
-    depth: number,
-    value: string,
-    element: HTMLElement | null,
-    disabled: boolean,
-    hasChildren: boolean,
-  ) => void;
-  /** Whether the deepest selected item is a leaf — Finder's rule for whether a
-   * preview occupies the slot after it. `false` when nothing is selected. */
-  terminalIsLeaf: boolean;
-  /** Get the registered items for a column. */
-  getColumnItems: (depth: number) => MillerColumnsItemMeta[];
-  /** Read a registered item's rendered cell text, for typeahead matching. */
-  getItemLabel: (depth: number, value: string) => string;
-  /** Move focus to the given item. */
-  focusItem: (depth: number, value: string) => void;
-  /** Focus the first item in a column; returns whether one was focused. */
-  focusFirstInColumn: (depth: number) => boolean;
-  /** Request that focus move into the given column. */
-  requestColumnFocus: (depth: number) => void;
-  /** The currently active (focused) item, if any. */
-  activeItem: MillerColumnsItemAddress | null;
-  /** Set the active (focused) item. */
-  setActiveItem: (item: MillerColumnsItemAddress) => void;
-  /** Printable-character typeahead, scoped to the focused item's column. */
-  handleTypeahead: (event: KeyboardEvent<HTMLElement>) => void;
-};
-
-/** Value shared through a column's context. */
-export type MillerColumnsColumnContextValue = {
-  /** The column's zero-based depth. */
-  depth: number;
-};
-
-/** Value shared through an item's context. */
-export type MillerColumnsItemContextValue = {
-  /** Whether this item is on the active path. */
-  selected: boolean;
-  /** Whether this item has a nested child column. */
-  hasChildren: boolean;
-};

package/src/MillerColumns/useMillerColumnsSelection.ts

@@ -1,31 +0,0 @@
-import { useMillerColumnsContext } from "./hooks/index.ts";
-
-import type { MillerColumnsSelection } from "./types";
-
-/**
- * Reads the current MillerColumns selection — the active path and the
- * deepest selected item id.
- *
- * Intended for consumer content rendered inside a `MillerColumns.Root`
- * (typically within a `MillerColumns.PreviewPanel`) that needs to know
- * what is selected without owning the selection state itself. Works for
- * both controlled and uncontrolled roots.
- *
- * Throws when called outside a `MillerColumns.Root`.
- *
- * @example
- * ```tsx
- * function FilePreview() {
- *   const { selectedValue } = useMillerColumnsSelection();
- *   return selectedValue ? <Preview id={selectedValue} /> : null;
- * }
- * ```
- */
-export function useMillerColumnsSelection(): MillerColumnsSelection {
-  const { activePath } = useMillerColumnsContext();
-
-  return {
-    path: activePath,
-    selectedValue: activePath.at(-1),
-  };
-}

package/src/MillerColumns/utils.ts

@@ -1,141 +0,0 @@
-import {
-  Children,
-  cloneElement,
-  Fragment,
-  isValidElement,
-  ReactElement,
-  ReactNode,
-} from "react";
-
-import { MillerColumnsColumn } from "./MillerColumns";
-
-/**
- * Produces the next active path when an item at `depth` with id `value`
- * is selected: keeps the columns shallower than `depth` untouched,
- * appends `value`, and drops everything deeper (those columns close).
- */
-export function selectAtDepth(
-  path: string[],
-  depth: number,
-  value: string,
-): string[] {
-  return [...path.slice(0, depth), value];
-}
-
-/**
- * Splits a props bag into its `aria-*` entries and everything else.
- *
- * `Root` renders two elements — a plain strip container and the inner
- * `role="tree"` widget — so one props bag has two possible homes. ARIA
- * belongs on the widget (an `aria-label` must name the tree, not its
- * scroll container); `className`, `id`, `style` and the rest belong on
- * the container the consumer actually lays out.
- */
-export function partitionAriaProps(props: Record<string, unknown>): {
-  aria: Record<string, unknown>;
-  rest: Record<string, unknown>;
-} {
-  const aria: Record<string, unknown> = {};
-  const rest: Record<string, unknown> = {};
-
-  for (const [key, value] of Object.entries(props)) {
-    if (key.startsWith("aria-")) {
-      aria[key] = value;
-    } else {
-      rest[key] = value;
-    }
-  }
-
-  return { aria, rest };
-}
-
-/**
- * Marker a styling layer sets on a component that renders a `MillerColumns`
- * part, so this module recognises the wrapper as that part.
- *
- * `Item` inspects its children **before** rendering them, so it sees the
- * wrapper component rather than the `MillerColumns.Column` the wrapper
- * returns. Without a marker a wrapped child column is mis-read as cell
- * content: the item stops being a branch (no `aria-expanded`, no chevron, no
- * ArrowRight) and — worse — the column projects into whatever depth slot
- * happens to be open, so selecting *one* branch reveals *every* sibling's
- * children at once.
- *
- * ```tsx
- * function StyledColumn(props: MillerColumnsColumnProps) {
- *   return <MillerColumns.Column {...props} className="column" />;
- * }
- * StyledColumn[MILLER_COLUMNS_PART] = "column";
- * ```
- */
-export const MILLER_COLUMNS_PART: "__primitivMillerColumnsPart" =
-  "__primitivMillerColumnsPart";
-
-/** The part names {@link MILLER_COLUMNS_PART} accepts. */
-export type MillerColumnsPartName = "column";
-
-/** Read a component's {@link MILLER_COLUMNS_PART} marker, if it declares one. */
-function millerColumnsPartOf(
-  type: unknown,
-): MillerColumnsPartName | undefined {
-  return (type as Record<string, MillerColumnsPartName | undefined> | null)?.[
-    MILLER_COLUMNS_PART
-  ];
-}
-
-/**
- * Whether `node` is a `MillerColumns.Column` element — either the part itself,
- * or a component that marks itself as standing in for it (see
- * {@link MILLER_COLUMNS_PART}).
- */
-export function isColumnElement(node: ReactNode): node is ReactElement {
-  return (
-    isValidElement(node) &&
-    (node.type === MillerColumnsColumn ||
-      millerColumnsPartOf(node.type) === "column")
-  );
-}
-
-/**
- * Splits an `Item`'s children into its cell content and its single
- * optional nested `<MillerColumns.Column>`.
- *
- * The child column is matched however deeply it is wrapped in
- * fragments, since `Children.toArray` does not descend into fragments —
- * so `{cond ? <><Indicator/><Column/></> : null}` is partitioned the
- * same as a bare `<Column/>`. Cell entries are re-keyed because
- * unwrapping fragments can collide the keys `Children.toArray` assigns.
- */
-export function partitionItemChildren(children: ReactNode): {
-  cell: ReactNode[];
-  column: ReactElement | null;
-} {
-  const cell: ReactNode[] = [];
-  let column: ReactElement | null = null;
-
-  const visit = (nodes: ReactNode): void => {
-    for (const child of Children.toArray(nodes)) {
-      if (isColumnElement(child)) {
-        if (column !== null) {
-          throw new Error(
-            "A MillerColumns.Item may contain at most one nested <MillerColumns.Column>.",
-          );
-        }
-        column = child;
-      } else if (isValidElement(child) && child.type === Fragment) {
-        visit((child.props as { children?: ReactNode }).children);
-      } else {
-        cell.push(child);
-      }
-    }
-  };
-
-  visit(children);
-
-  return {
-    cell: cell.map((node, index) =>
-      isValidElement(node) ? cloneElement(node, { key: `mc-${index}` }) : node,
-    ),
-    column,
-  };
-}