@ui-sdk/react 0.0.0-stage → 0.1.0-beta.1

package/dist/trigger-menu.d.ts

@@ -0,0 +1,83 @@
+import { type TriggerMenuContentProps, type TriggerMenuContentState, type TriggerMenuData, type TriggerMenuEmptyState, type TriggerMenuHintState, type TriggerMenuItemProps, type TriggerMenuItemState, type TriggerMenuOptions, type TriggerMenuStatusState } from "@ui-sdk/core/trigger-menu";
+import * as React from "react";
+import { type PartProps } from "./use-primitive.js";
+type Clashing = "value" | "defaultValue" | "onChange" | "onSelect";
+/**
+ * The props of `TriggerMenu`.
+ * @stable
+ */
+type TriggerMenuProps<T = string> = TriggerMenuOptions<T> & {
+    children?: React.ReactNode;
+};
+/**
+ * Suggestions opened by a trigger like `@` or `/` in text. Inside a TokenInput
+ * it uses that editor; otherwise render a TriggerMenuInput, or pass `editor`.
+ * @stable
+ */
+declare function TriggerMenu<T = string>({ children, container, editor, ...options }: TriggerMenuProps<T>): React.JSX.Element;
+/**
+ * The text field the menu suggests into: a `<textarea>`, or an `<input>` through `render`.
+ * @stable
+ */
+declare const TriggerMenuInput: import("./use-primitive.js").PartComponent<import("@ui-sdk/core/trigger-menu").TriggerMenuPrimitive, "input", "textarea">;
+/**
+ * The popup that holds the suggestions, anchored at the caret.
+ * @stable
+ */
+declare function TriggerMenuContent({ side, align, sideOffset, alignOffset, collisionPadding, arrowPadding, anchor, keepMounted, container, children, ...props }: PartProps<"div", TriggerMenuContentState> & TriggerMenuContentProps): React.JSX.Element | null;
+/**
+ * The listbox. Without children, it renders the current trigger's items, filtered.
+ * @stable
+ */
+declare function TriggerMenuList({ children, ...props }: PartProps<"div", TriggerMenuContentState>): React.JSX.Element | null;
+/**
+ * A suggestion. Choosing it inserts it into the text.
+ * @stable
+ */
+declare const TriggerMenuItem: <T = string>(props: Omit<PartProps<"div", TriggerMenuItemState>, Clashing> & TriggerMenuItemProps<T>) => React.ReactNode;
+/**
+ * An icon inside a suggestion. Screen readers, typeahead and filtering skip it, and `mirror` flips
+ * it in right-to-left text.
+ * @stable
+ */
+declare const TriggerMenuItemIcon: import("./use-primitive.js").PartComponent<import("@ui-sdk/core/trigger-menu").TriggerMenuPrimitive, "item-icon", "span">;
+/**
+ * A group of items, named by its `TriggerMenuGroupLabel`.
+ * @stable
+ */
+declare const TriggerMenuGroup: import("./use-primitive.js").PartComponent<import("@ui-sdk/core/trigger-menu").TriggerMenuPrimitive, "group", "div">;
+/**
+ * The group's heading, which names the group.
+ * @stable
+ */
+declare const TriggerMenuGroupLabel: import("./use-primitive.js").PartComponent<import("@ui-sdk/core/trigger-menu").TriggerMenuPrimitive, "group-label", "div">;
+/**
+ * A line between items or groups, hidden from screen readers.
+ * @stable
+ */
+declare const TriggerMenuSeparator: import("./use-primitive.js").PartComponent<import("@ui-sdk/core/trigger-menu").TriggerMenuPrimitive, "separator", "div">;
+/**
+ * Shown while no item matches. Rendering it keeps the menu open with no matches; without it, the menu closes until something matches.
+ * @stable
+ */
+declare function TriggerMenuEmpty({ children, ...props }: PartProps<"div", TriggerMenuEmptyState>): React.JSX.Element | null;
+/**
+ * A polite status, outside the popup. Without children, it says the count and the keys once typing pauses.
+ * @stable
+ */
+declare function TriggerMenuStatus(props: PartProps<"div", TriggerMenuStatusState>): React.JSX.Element | null;
+/**
+ * Ghost text at the caret for the arguments still to type, like `<name>`. Without children, the hints.
+ * @stable
+ */
+declare function TriggerMenuHint(props: PartProps<"span", TriggerMenuHintState>): React.JSX.Element | null;
+/**
+ * Renders data items. Used by data menus, and available for custom layouts.
+ * @stable
+ */
+declare function TriggerMenuItems({ items }: {
+    items: TriggerMenuData<any>;
+}): React.JSX.Element;
+export { createTriggerMenuController, textFieldAdapter, } from "@ui-sdk/core/trigger-menu";
+export type { EditorChange, EditorReplaceOptions, ListFilter, ListItem, ListSeparator, TextEditorAdapter, TextRange, TextRect, Token, TokenInsert, TriggerAfter, TriggerArgument, TriggerBoundary, TriggerDefinition, TriggerItemsLoader, TriggerMatch, TriggerMenuApi, TriggerMenuChangeOptions, TriggerMenuContentProps, TriggerMenuContentState, TriggerMenuController, TriggerMenuData, TriggerMenuDataGroup, TriggerMenuDataItem, TriggerMenuDismissReason, TriggerMenuEmptyState, TriggerMenuHintState, TriggerMenuInputState, TriggerMenuItemIconProps, TriggerMenuItemIconState, TriggerMenuItemProps, TriggerMenuItemState, TriggerMenuOpenChangeReason, TriggerMenuOptions, TriggerMenuPrimitive, TriggerMenuQueryChangeReason, TriggerMenuSelectDetails, TriggerMenuStatusState, TriggerRule, } from "@ui-sdk/core/trigger-menu";
+export { TriggerMenu, TriggerMenuContent, TriggerMenuEmpty, TriggerMenuGroup, TriggerMenuGroupLabel, TriggerMenuHint, TriggerMenuInput, TriggerMenuItem, TriggerMenuItemIcon, TriggerMenuItems, TriggerMenuList, type TriggerMenuProps, TriggerMenuSeparator, TriggerMenuStatus, };

package/dist/trigger-menu.js

@@ -0,0 +1,167 @@
+"use client";
+// src/trigger-menu.tsx
+import {
+  triggerMenu as triggerMenuPrimitive
+} from "@ui-sdk/core/trigger-menu";
+import * as React from "react";
+import { hasChild, Placed, usePlaceContent, usePlacedContent } from "./children.js";
+import { EditorContext } from "./editor-context.js";
+import {
+  renderPopup,
+  useControllerEntry,
+  useOwnContainer,
+  usePopupContainer
+} from "./popup.js";
+import { ListItems } from "./list-items.js";
+import {
+  createParts,
+  HandleScope,
+  useHandle,
+  usePart,
+  usePrimitive
+} from "./use-primitive.js";
+import {
+  createTriggerMenuController,
+  textFieldAdapter
+} from "@ui-sdk/core/trigger-menu";
+import { jsx, jsxs } from "react/jsx-runtime";
+var parts = createParts(triggerMenuPrimitive, {
+  input: "textarea",
+  item: "div",
+  "item-icon": "span",
+  group: "div",
+  "group-label": "div",
+  separator: "div"
+});
+var ContainerContext = React.createContext(void 0);
+function useTriggerMenu() {
+  return useHandle(triggerMenuPrimitive);
+}
+function TriggerMenu({
+  children,
+  container,
+  editor,
+  ...options
+}) {
+  const inherited = React.useContext(EditorContext);
+  const menu = usePrimitive(triggerMenuPrimitive, {
+    ...options,
+    editor: editor ?? inherited
+  });
+  useControllerEntry(options.controller, menu);
+  const found = hasChild(children, TriggerMenuContent);
+  const [placed, place] = usePlacedContent(!found);
+  const own = placed || found;
+  return /* @__PURE__ */ jsx(HandleScope, { handle: menu, children: /* @__PURE__ */ jsxs(ContainerContext.Provider, { value: container, children: [
+    /* @__PURE__ */ jsx(Placed, { value: place, children }),
+    /* @__PURE__ */ jsx(Placed, { value: null, children: !own && /* @__PURE__ */ jsx(TriggerMenuContent, {}) })
+  ] }) });
+}
+var TriggerMenuInput = parts.Input;
+function TriggerMenuContent({
+  side,
+  align,
+  sideOffset,
+  alignOffset,
+  collisionPadding,
+  arrowPadding,
+  anchor,
+  keepMounted,
+  container,
+  children,
+  ...props
+}) {
+  usePlaceContent();
+  const target = usePopupContainer(useOwnContainer(container, ContainerContext));
+  const content = {
+    side,
+    align,
+    sideOffset,
+    alignOffset,
+    collisionPadding,
+    arrowPadding,
+    anchor,
+    keepMounted
+  };
+  const body = children ?? /* @__PURE__ */ jsx(TriggerMenuList, {});
+  const element = usePart(triggerMenuPrimitive, "content", content, {
+    ...props,
+    children: body
+  });
+  return element && renderPopup(element, target);
+}
+function TriggerMenuList({
+  children = listItems,
+  ...props
+}) {
+  return usePart(triggerMenuPrimitive, "list", {}, { ...props, children });
+}
+var listItems = (state) => /* @__PURE__ */ jsx(TriggerMenuItems, { items: state.items });
+var TriggerMenuItem = parts.Item;
+var TriggerMenuItemIcon = parts.ItemIcon;
+var TriggerMenuGroup = parts.Group;
+var TriggerMenuGroupLabel = parts.GroupLabel;
+var TriggerMenuSeparator = parts.Separator;
+function TriggerMenuEmpty({
+  children,
+  ...props
+}) {
+  const content = (state) => typeof children === "function" ? children(state) : state.empty ? children : null;
+  return usePart(
+    triggerMenuPrimitive,
+    "empty",
+    {},
+    { ...props, children: content }
+  );
+}
+function TriggerMenuStatus(props) {
+  return usePart(
+    triggerMenuPrimitive,
+    "status",
+    { text: props.children === void 0 },
+    props
+  );
+}
+function TriggerMenuHint(props) {
+  return usePart(
+    triggerMenuPrimitive,
+    "hint",
+    { text: props.children === void 0 },
+    props,
+    "span"
+  );
+}
+function TriggerMenuItems({ items }) {
+  const menu = useTriggerMenu();
+  return /* @__PURE__ */ jsx(
+    ListItems,
+    {
+      items,
+      parts: listParts,
+      keyOf: menu.api.internal.keyOf
+    }
+  );
+}
+var listParts = {
+  Item: TriggerMenuItem,
+  Group: TriggerMenuGroup,
+  GroupLabel: TriggerMenuGroupLabel,
+  Separator: TriggerMenuSeparator
+};
+export {
+  TriggerMenu,
+  TriggerMenuContent,
+  TriggerMenuEmpty,
+  TriggerMenuGroup,
+  TriggerMenuGroupLabel,
+  TriggerMenuHint,
+  TriggerMenuInput,
+  TriggerMenuItem,
+  TriggerMenuItemIcon,
+  TriggerMenuItems,
+  TriggerMenuList,
+  TriggerMenuSeparator,
+  TriggerMenuStatus,
+  createTriggerMenuController,
+  textFieldAdapter
+};

package/dist/use-primitive.d.ts

@@ -0,0 +1,178 @@
+import type { OptionsOf, Primitive, PrimitiveInstance, PropsOf, SlotName, StateOf, TypesOf } from "@ui-sdk/core";
+import { type PrimitiveGeneric } from "@ui-sdk/core/renderer";
+import * as React from "react";
+import { mergeProps, mergeRefs, renderElement, type RenderProp } from "./render-element.js";
+/**
+ * What `usePrimitive` returns, and what a component's context holds: one object for the instance's life.
+ * @stable
+ */
+type PrimitiveHandle<P extends Primitive> = {
+    /** The primitive it's an instance of. */
+    primitive: P;
+    /** The core instance `usePrimitive` made, with its `get()`, `part()` and `api`. In render, read `state` instead of its `get()`, which shows only what React has committed. */
+    instance: ReturnType<P>;
+    /** The state this render shows. Reading it doesn't subscribe; a part's `render` and class name functions get the state they render. */
+    readonly state: TypesOf<P>["state"];
+    /** The methods its definition declares, like Tabs' `setValue`. */
+    api: TypesOf<P>["api"];
+};
+/**
+ * Creates an instance of a primitive for this component, keeps its options
+ * current on every render, and destroys it when the component leaves. Render
+ * its root with `usePart`, which shares the instance with the parts inside.
+ *
+ * @example
+ * function ConfirmButton({ onConfirm, ...props }: PartProps<"button", ConfirmButtonState> & { onConfirm?: () => void }) {
+ *   const button = usePrimitive(confirmButton, { onConfirm })
+ *   return usePart(button, "root", {}, props, "button")
+ * }
+ * @stable
+ */
+declare function usePrimitive<P extends Primitive>(primitive: P, options: OptionsOf<P>): PrimitiveHandle<P>;
+type Outer = {
+    instance: PrimitiveInstance;
+};
+declare function reading<F extends (...args: never[]) => unknown>(handle: Outer, read: F): F;
+declare function extendHandle<H extends {
+    instance: PrimitiveInstance;
+}, E extends object>(handle: H, extra: E): H & E;
+declare function presentIn<P extends Primitive, S extends SlotName<P>>(handle: PrimitiveHandle<P>, name: S, props?: PropsOf<P, S>): boolean;
+declare function slotIn<P extends Primitive, S extends SlotName<P>>(handle: PrimitiveHandle<P>, name: S, props?: PropsOf<P, S>, user?: Record<string, any>): Record<string, any>;
+declare function readIn<I extends PrimitiveInstance, T>(handle: {
+    instance: I;
+}, read: (state: I["types"]["state"]) => T, around?: Record<string, object>): T;
+/**
+ * Props every part takes: its element's props, `render`, and class names and
+ * styles that may be functions of the part's state.
+ * @stable
+ */
+type PartProps<Tag extends keyof React.JSX.IntrinsicElements, State = {}> = Omit<React.ComponentProps<Tag>, "className" | "style" | "children"> & {
+    /** Class names, or a function of the part's state that returns them. */
+    className?: string | ((state: State) => string | undefined);
+    /** Styles, or a function of the part's state that returns them. */
+    style?: React.CSSProperties | ((state: State) => React.CSSProperties | undefined);
+    /** Renders your own element: one that receives the part's props, or a function of the props and the state. */
+    render?: RenderProp<State>;
+    /** Content, or a function of the part's state that returns it. */
+    children?: React.ReactNode | ((state: State) => React.ReactNode);
+};
+/**
+ * Shares an instance with the parts inside, for a root that renders no
+ * element of its own, like a popover's.
+ */
+declare function HandleScope({ handle, children, }: {
+    handle: PrimitiveHandle<Primitive>;
+    children?: React.ReactNode;
+}): React.JSX.Element;
+/** The nearest instance of a primitive, or undefined outside its root, like a toggle's group. */
+declare function useNearest<P extends Primitive>(primitive: P): PrimitiveHandle<P> | undefined;
+/** The nearest instance of a primitive, for a part written by hand that calls its api. */
+declare function useHandle<P extends Primitive>(primitive: P): PrimitiveHandle<P>;
+type PartState<P extends Primitive, S extends SlotName<P>> = unknown extends StateOf<P, S> ? {} : StateOf<P, S>;
+/**
+ * Renders one part of a primitive written by hand: its element, with the
+ * slot's attributes and handlers merged into `props`, re-rendered when what
+ * it shows changes, or nothing while the slot says it isn't present.
+ * `handle` is `usePrimitive`'s, or the primitive, whose nearest instance it
+ * uses. Given `usePrimitive`'s handle, the parts inside the element find that
+ * instance.
+ *
+ * @example
+ * function RatingStar({ value, ...props }: PartProps<"button", RatingStarState> & { value: string }) {
+ *   return usePart(rating, "star", { value }, props, "button")
+ * }
+ * @stable
+ */
+declare function usePart<P extends Primitive, S extends SlotName<P>, T extends Tag = "div">(handle: P | PrimitiveHandle<P>, slot: S, slotProps: PropsOf<P, S>, props?: PartProps<T, PartState<P, S>>, tag?: T): React.JSX.Element | null;
+type Pascal<Name extends string> = Name extends `${infer Head}-${infer Tail}` ? `${Capitalize<Head>}${Pascal<Tail>}` : Capitalize<Name>;
+type Tag = keyof React.JSX.IntrinsicElements;
+type ElementProps<T extends Tag, State, Named> = Omit<PartProps<T, State>, keyof Named>;
+type Props<Named, State, T extends Tag> = Named & ElementProps<T, State, Named>;
+type RootSlot<P extends Primitive> = "root" & SlotName<P>;
+type GenericOf<P> = P extends {
+    generic?: infer G extends PrimitiveGeneric;
+} ? G : never;
+type Applied<G, T, U> = G & {
+    T: T;
+    U: U;
+};
+type DefaultOf<G extends PrimitiveGeneric, K extends "T" | "U"> = G extends {
+    defaults: Record<K, infer D>;
+} ? D & G[K] : G[K];
+type OptionsIn<P extends Primitive, A> = [A] extends [never] ? OptionsOf<P> : A extends {
+    options: infer O;
+} ? O : OptionsOf<P>;
+type StateIn<P extends Primitive, S extends SlotName<P>, A> = [A] extends [
+    never
+] ? StateOf<P, S> : A extends {
+    state: Record<S, infer State>;
+} ? State : StateOf<P, S>;
+type PropsIn<P extends Primitive, S extends SlotName<P>, A> = [A] extends [
+    never
+] ? PropsOf<P, S> : A extends {
+    props: Record<S, infer Named>;
+} ? Named : PropsOf<P, S>;
+type RootOf<P extends Primitive, T extends Tag | undefined> = [
+    GenericOf<P>
+] extends [never] ? (props: RootPropsIn<P, never, T>) => React.ReactElement | null : <A extends GenericOf<P>["T"] = DefaultOf<GenericOf<P>, "T">, B extends GenericOf<P>["U"] = DefaultOf<GenericOf<P>, "U">>(props: GenericRootProps<P, Applied<GenericOf<P>, A, B>, T>) => React.ReactElement | null;
+type GenericRootProps<P extends Primitive, A extends PrimitiveGeneric, T extends Tag | undefined> = T extends Tag ? Props<A["options"] & PropsOf<P, RootSlot<P>>, StateIn<P, RootSlot<P>, A>, T> : A["options"] & {
+    children?: React.ReactNode;
+};
+type RootPropsIn<P extends Primitive, A, T extends Tag | undefined> = T extends Tag ? Props<OptionsIn<P, A> & PropsIn<P, RootSlot<P>, A>, StateIn<P, RootSlot<P>, A>, T> : OptionsIn<P, A> & {
+    children?: React.ReactNode;
+};
+type PartOf<P extends Primitive, S extends SlotName<P>, T extends Tag> = [
+    GenericOf<P>
+] extends [never] ? PartComponent<P, S, T> : GenericOf<P> extends {
+    props: Record<S, unknown>;
+} ? GenericPartComponent<P, S, T> : PartComponent<P, S, T>;
+/**
+ * A part's component, from `createParts`: the props of slot `S` of primitive
+ * `P` rendered as a `T`.
+ * @stable
+ */
+interface PartComponent<P extends Primitive, S extends SlotName<P>, T extends Tag> {
+    (props: Props<PropsOf<P, S>, [
+        GenericOf<P>
+    ] extends [never] ? StateOf<P, S> : StateIn<P, S, GenericOf<P>>, T>): React.ReactElement | null;
+}
+/**
+ * A part's component whose props take the primitive's type parameter, like an
+ * item's `value`, from `createParts`.
+ * @stable
+ */
+interface GenericPartComponent<P extends Primitive, S extends SlotName<P>, T extends Tag> {
+    <A extends GenericOf<P>["T"] = DefaultOf<GenericOf<P>, "T">>(props: Props<(Applied<GenericOf<P>, A, unknown>["props"] & Record<S, unknown>)[S], StateIn<P, S, Applied<GenericOf<P>, A, unknown>>, T>): React.ReactElement | null;
+}
+/**
+ * The components `createParts` makes: `Root`, and one per tagged slot, named in Pascal case.
+ * @stable
+ */
+type Parts<P extends Primitive, Tags extends {
+    [S in SlotName<P>]?: Tag;
+}> = {
+    Root: RootOf<P, Tags extends {
+        root: Tag;
+    } ? Tags["root"] : undefined>;
+} & {
+    [S in keyof TypesOf<P>["slots"] as S extends Exclude<keyof Tags, "root"> & string ? Pascal<S> : never]: PartOf<P, S & SlotName<P>, NonNullable<Tags[S & keyof Tags]> & Tag>;
+};
+/**
+ * Every part of a primitive as a component, typed from it. `Root` makes the
+ * instance from the primitive's options and shares it with the parts inside
+ * it. Each slot named in `tags` becomes a component that renders that tag,
+ * named in Pascal case, like `TabIcon` for `tab-icon`. Without a `root` tag,
+ * `Root` renders only its children. Every part takes `render`, and class
+ * names, styles and children that may be functions of its state.
+ *
+ * @example
+ * const { Root: Playlist, Track: PlaylistTrack } = createParts(playlist, { root: "ul", track: "li" })
+ * @stable
+ */
+declare function createParts<P extends Primitive, Tags extends {
+    [S in SlotName<P>]?: Tag;
+}>(primitive: P, tags: Tags): Parts<P, Tags>;
+/** The props of the part of `slot` around the one rendering, like an option's inside its group. */
+declare function useAround<P extends Primitive>(primitive: P, slot: SlotName<P>): Record<string, unknown> | undefined;
+declare function sharesProps(primitive: Primitive, slot: string): void;
+export { createParts, extendHandle, HandleScope, mergeProps, mergeRefs, type GenericPartComponent, type PartComponent, type PartProps, type Parts, presentIn, type PrimitiveHandle, readIn, reading, renderElement, type RenderProp, sharesProps, slotIn, useHandle, useAround, useNearest, usePart, usePrimitive, };