@itwin/itwinui-react 5.0.0-alpha.0 → 5.0.0-alpha.10

package/dist/bricks/DropdownMenu.js

@@ -1,11 +1,24 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import cx from "classnames";
-import * as Ariakit from "@ariakit/react";
-import * as ListItem from "./ListItem.js";
+import * as ListItem from "./~utils.ListItem.js";
 import { Button } from "./Button.js";
-import { DisclosureArrow } from "./Icon.js";
-import { supportsPopover } from "./~utils.js";
+import { Kbd } from "./Kbd.js";
+import { Checkmark, DisclosureArrow, Icon } from "./Icon.js";
+import {
+  forwardRef
+} from "./~utils.js";
+import { usePopoverApi } from "./~hooks.js";
+import {
+  MenuProvider,
+  useMenuContext,
+  Menu,
+  MenuButton,
+  MenuItem,
+  MenuItemCheckbox
+} from "@ariakit/react/menu";
+import { useStoreState } from "@ariakit/react/store";
+import { predefinedSymbols } from "./Kbd.internal.js";
 function DropdownMenu(props) {
   const {
     children,
@@ -14,21 +27,9 @@ function DropdownMenu(props) {
     setOpen: setOpenProp,
     defaultOpen: defaultOpenProp
   } = props;
-  const store = Ariakit.useMenuStore();
-  const open = Ariakit.useStoreState(store, (store2) => store2.open);
-  const popover = Ariakit.useStoreState(store, (store2) => store2.popoverElement);
-  React.useEffect(
-    function syncPopoverWithOpenState() {
-      if (popover?.isConnected) {
-        popover?.togglePopover?.(open);
-      }
-    },
-    [open, popover]
-  );
   return /* @__PURE__ */ jsx(
-    Ariakit.MenuProvider,
+    MenuProvider,
     {
-      store,
       placement,
       defaultOpen: defaultOpenProp,
       open: openProp,
@@ -37,49 +38,140 @@ function DropdownMenu(props) {
     }
   );
 }
-const DropdownMenuContent = React.forwardRef((props, forwardedRef) => {
-  return /* @__PURE__ */ jsx(
-    Ariakit.Menu,
-    {
-      portal: !supportsPopover,
-      unmountOnHide: true,
-      ...props,
-      style: { zIndex: supportsPopover ? void 0 : 9999, ...props.style },
-      wrapperProps: { popover: "manual" },
-      className: cx("\u{1F95D}-dropdown-menu", props.className),
-      ref: forwardedRef
-    }
-  );
-});
-const DropdownMenuButton = React.forwardRef((props, forwardedRef) => {
-  const { accessibleWhenDisabled = true, children, ...rest } = props;
+const DropdownMenuContent = forwardRef(
+  (props, forwardedRef) => {
+    const popover = usePopoverApi(useMenuContext());
+    return /* @__PURE__ */ jsx(
+      Menu,
+      {
+        portal: popover.portal,
+        unmountOnHide: true,
+        ...props,
+        gutter: 4,
+        style: { ...popover.style, ...props.style },
+        wrapperProps: popover.wrapperProps,
+        className: cx("\u{1F95D}-dropdown-menu", props.className),
+        ref: forwardedRef
+      }
+    );
+  }
+);
+const DropdownMenuButton = forwardRef(
+  (props, forwardedRef) => {
+    const { accessibleWhenDisabled = true, children, ...rest } = props;
+    const open = useStoreState(useMenuContext(), (state) => state?.open);
+    return /* @__PURE__ */ jsx(
+      MenuButton,
+      {
+        accessibleWhenDisabled: true,
+        render: /* @__PURE__ */ jsxs(Button, { accessibleWhenDisabled, children: [
+          children,
+          /* @__PURE__ */ jsx(DisclosureArrow, {})
+        ] }),
+        ...rest,
+        className: cx("\u{1F95D}-dropdown-menu-button", props.className),
+        "data-has-popover-open": open || void 0,
+        ref: forwardedRef
+      }
+    );
+  }
+);
+const DropdownMenuItem = forwardRef(
+  (props, forwardedRef) => {
+    const { label, shortcuts, icon, ...rest } = props;
+    return /* @__PURE__ */ jsxs(
+      MenuItem,
+      {
+        accessibleWhenDisabled: true,
+        ...rest,
+        render: /* @__PURE__ */ jsx(ListItem.Root, { render: props.render }),
+        className: cx("\u{1F95D}-dropdown-menu-item", props.className),
+        ref: forwardedRef,
+        children: [
+          icon ? /* @__PURE__ */ jsx(DropdownMenuIcon, { icon }) : null,
+          /* @__PURE__ */ jsx(ListItem.Content, { children: label }),
+          shortcuts ? /* @__PURE__ */ jsx(DropdownMenuItemShortcuts, { shortcuts }) : null
+        ]
+      }
+    );
+  }
+);
+const DropdownMenuItemShortcuts = forwardRef((props, forwardedRef) => {
+  const { shortcuts, ...rest } = props;
+  const shortcutKeys = React.useMemo(() => {
+    return shortcuts.split("+").map((key) => ({
+      key: key.trim(),
+      isSymbol: key in predefinedSymbols
+    }));
+  }, [shortcuts]);
   return /* @__PURE__ */ jsx(
-    Ariakit.MenuButton,
+    ListItem.Decoration,
     {
-      accessibleWhenDisabled: true,
-      render: /* @__PURE__ */ jsxs(Button, { accessibleWhenDisabled, children: [
-        children,
-        /* @__PURE__ */ jsx(DisclosureArrow, {})
-      ] }),
       ...rest,
-      className: cx("\u{1F95D}-dropdown-menu-button", props.className),
-      ref: forwardedRef
+      className: cx("\u{1F95D}-dropdown-menu-item-shortcuts", props.className),
+      ref: forwardedRef,
+      children: shortcutKeys.map(({ key, isSymbol }, index) => {
+        if (isSymbol) {
+          return /* @__PURE__ */ jsx(
+            Kbd,
+            {
+              variant: "ghost",
+              symbol: key
+            },
+            `${key + index}`
+          );
+        }
+        return /* @__PURE__ */ jsx(Kbd, { variant: "ghost", children: key }, `${key + index}`);
+      })
     }
   );
 });
-const DropdownMenuItem = React.forwardRef((props, forwardedRef) => {
-  return /* @__PURE__ */ jsx(
-    Ariakit.MenuItem,
+const DropdownMenuIcon = forwardRef(
+  (props, forwardedRef) => {
+    const { icon, ...rest } = props;
+    return /* @__PURE__ */ jsx(
+      ListItem.Decoration,
+      {
+        render: /* @__PURE__ */ jsx(
+          Icon,
+          {
+            href: typeof icon === "string" ? icon : void 0,
+            render: React.isValidElement(icon) ? icon : void 0
+          }
+        ),
+        ...rest,
+        ref: forwardedRef
+      }
+    );
+  }
+);
+const DropdownMenuCheckboxItem = forwardRef((props, forwardedRef) => {
+  const { label, icon, ...rest } = props;
+  return /* @__PURE__ */ jsxs(
+    MenuItemCheckbox,
     {
       accessibleWhenDisabled: true,
-      ...props,
+      value: props.defaultChecked ? "on" : void 0,
+      ...rest,
       render: /* @__PURE__ */ jsx(ListItem.Root, { render: props.render }),
-      ref: forwardedRef
+      className: cx("\u{1F95D}-dropdown-menu-item", props.className),
+      ref: forwardedRef,
+      children: [
+        icon ? /* @__PURE__ */ jsx(DropdownMenuIcon, { icon }) : null,
+        /* @__PURE__ */ jsx(ListItem.Content, { children: label }),
+        /* @__PURE__ */ jsx(
+          ListItem.Decoration,
+          {
+            render: /* @__PURE__ */ jsx(Checkmark, { className: "\u{1F95D}-dropdown-menu-checkmark" })
+          }
+        )
+      ]
     }
   );
 });
 export {
   DropdownMenuButton as Button,
+  DropdownMenuCheckboxItem as CheckboxItem,
   DropdownMenuContent as Content,
   DropdownMenuItem as Item,
   DropdownMenu as Root

package/dist/bricks/Field.d.ts

@@ -1,11 +1,53 @@
 import * as React from "react";
-import type { BaseProps } from "./~utils.js";
+import { useCollectionStore, type CollectionItemProps } from "@ariakit/react/collection";
+import { type BaseProps } from "./~utils.js";
 interface FieldProps extends BaseProps {
     /**
      * Allows overriding the default block layout for text controls.
      */
     layout?: "inline";
 }
-export declare const Field: React.ForwardRefExoticComponent<FieldProps & React.RefAttributes<HTMLDivElement>>;
-export declare function useFieldId(): string | undefined;
+/**
+ * A container for form controls. It manages ID associations provides a consistent layout and spacing.
+ *
+ * Example:
+ * ```tsx
+ * <Field>
+ *   <Label>Label</Label>
+ *   <TextBox.Input />
+ * </Field>
+ * ```
+ *
+ * Supports a `layout` prop, which can be set to `inline` to align the label and control horizontally.
+ *
+ * Should contain a `Label` component paired with a form control. Supported form controls include:
+ * - `TextBox.Input`
+ * - `TextBox.Textarea`
+ * - `Checkbox`
+ * - `Radio`
+ * - `Switch`
+ */
+export declare const Field: React.ForwardRefExoticComponent<FieldProps & React.RefAttributes<HTMLElement | HTMLDivElement>>;
+type CollectionStoreItem = NonNullable<ReturnType<ReturnType<typeof useCollectionStore>["item"]>>;
+interface FieldCollectionStoreItem extends CollectionStoreItem {
+    /** The type of field element being tracked */
+    elementType: "label" | "control" | "description";
+    /** If a control, the type of control. */
+    controlType?: "textlike" | "checkable";
+}
+interface FieldCollectionItemControlProps extends Pick<CollectionItemProps, "render" | "id"> {
+    type: FieldCollectionStoreItem["controlType"];
+}
+/**
+ * An element tracked as a control in the `Field`’s collection.
+ */
+export declare function FieldControl(props: FieldCollectionItemControlProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * An element tracked as a label in the `Field`’s collection.
+ */
+export declare function FieldLabel(props: Pick<CollectionItemProps, "render">): import("react/jsx-runtime").JSX.Element;
+/**
+ * An element tracked as a description in the `Field`’s collection.
+ */
+export declare function FieldDescription(props: Pick<CollectionItemProps, "render" | "id">): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/bricks/Field.js

@@ -1,27 +1,127 @@
 import { jsx } from "react/jsx-runtime";
 import * as React from "react";
-import * as Ariakit from "@ariakit/react";
 import cx from "classnames";
-const Field = React.forwardRef(
-  (props, forwardedRef) => {
-    const fieldId = React.useId();
-    const { className, layout, ...rest } = props;
-    return /* @__PURE__ */ jsx(FieldIdContext.Provider, { value: fieldId, children: /* @__PURE__ */ jsx(
-      Ariakit.Role,
-      {
-        ...rest,
-        className: cx("\u{1F95D}-field", className),
-        "data-kiwi-layout": layout,
-        ref: forwardedRef
-      }
-    ) });
-  }
-);
-const FieldIdContext = React.createContext(void 0);
-function useFieldId() {
-  return React.useContext(FieldIdContext);
+import { Role } from "@ariakit/react/role";
+import {
+  useCollectionStore,
+  Collection,
+  useCollectionContext,
+  CollectionItem
+} from "@ariakit/react/collection";
+import { useStoreState } from "@ariakit/react/store";
+import { forwardRef } from "./~utils.js";
+const Field = forwardRef((props, forwardedRef) => {
+  const { layout, ...rest } = props;
+  return /* @__PURE__ */ jsx(
+    FieldCollection,
+    {
+      render: /* @__PURE__ */ jsx(
+        Role.div,
+        {
+          ...rest,
+          className: cx("\u{1F95D}-field", props.className),
+          "data-kiwi-layout": layout,
+          ref: forwardedRef
+        }
+      )
+    }
+  );
+});
+function FieldCollection(props) {
+  const fieldElementCollection = useCollectionStore({
+    defaultItems: []
+  });
+  const renderedItems = useStoreState(fieldElementCollection, "renderedItems");
+  const [controlType, controlIndex] = React.useMemo(() => {
+    const controlIndex2 = renderedItems.findIndex(
+      (item) => item.elementType === "control"
+    );
+    return [renderedItems[controlIndex2]?.controlType, controlIndex2];
+  }, [renderedItems]);
+  const labelPlacement = React.useMemo(() => {
+    const labelIndex = renderedItems.findIndex(
+      (item) => item.elementType === "label"
+    );
+    if (controlIndex === -1 || labelIndex === -1) return;
+    return labelIndex < controlIndex ? "before" : "after";
+  }, [renderedItems, controlIndex]);
+  return /* @__PURE__ */ jsx(
+    Collection,
+    {
+      ...props,
+      store: fieldElementCollection,
+      "data-kiwi-label-placement": labelPlacement,
+      "data-kiwi-control-type": controlType
+    }
+  );
+}
+function FieldControl(props) {
+  const store = useCollectionContext();
+  const generatedId = React.useId();
+  const { id = store ? generatedId : void 0, type, ...rest } = props;
+  const renderedItems = useStoreState(store, "renderedItems");
+  const describedBy = React.useMemo(() => {
+    const idRefList = renderedItems?.filter(
+      (item) => item.elementType === "description"
+    )?.map((item) => item.id).join(" ");
+    return idRefList || void 0;
+  }, [renderedItems]);
+  const getData = React.useCallback(
+    (data) => ({
+      ...data,
+      elementType: "control",
+      controlType: type
+    }),
+    [type]
+  );
+  return /* @__PURE__ */ jsx(
+    CollectionItem,
+    {
+      id,
+      getItem: getData,
+      render: /* @__PURE__ */ jsx(Role, { ...rest, "aria-describedby": describedBy })
+    }
+  );
+}
+function FieldLabel(props) {
+  const store = useCollectionContext();
+  const renderedItems = useStoreState(store, "renderedItems");
+  const fieldId = React.useMemo(
+    () => renderedItems?.find(
+      (item) => item.elementType === "control"
+    )?.id,
+    [renderedItems]
+  );
+  const getData = React.useCallback(
+    (data) => ({
+      ...data,
+      elementType: "label"
+    }),
+    []
+  );
+  return /* @__PURE__ */ jsx(
+    CollectionItem,
+    {
+      getItem: getData,
+      render: /* @__PURE__ */ jsx(Role.label, { ...props, htmlFor: fieldId })
+    }
+  );
+}
+function FieldDescription(props) {
+  const generatedId = React.useId();
+  const { id = generatedId, ...rest } = props;
+  const getData = React.useCallback(
+    (data) => ({
+      ...data,
+      elementType: "description"
+    }),
+    []
+  );
+  return /* @__PURE__ */ jsx(CollectionItem, { ...rest, id, getItem: getData });
 }
 export {
   Field,
-  useFieldId
+  FieldControl,
+  FieldDescription,
+  FieldLabel
 };

package/dist/bricks/Icon.d.ts

@@ -1,17 +1,36 @@
 import * as React from "react";
-import type { BaseProps } from "./~utils.js";
+import { type BaseProps } from "./~utils.js";
 interface IconProps extends Omit<BaseProps<"svg">, "children"> {
-    /** URL of the symbol sprite. */
+    /**
+     * URL of the symbol sprite.
+     *
+     * Should be a URL to an `.svg` file from `@itwin/itwinui-icons`.
+     */
     href?: string;
-    /** Size of the icon. Defaults to `regular`. */
+    /**
+     * Size of the icon. This affects the icon's physical dimensions, as well as the
+     * actual SVG contents (different sizes might have different fidelity).
+     *
+     * Defaults to `"regular"` (16px) and can be optionally set to `"large"` (24px).
+     */
     size?: "regular" | "large";
+    /**
+     * Alternative text describing the icon.
+     *
+     * When this prop is passed, the SVG gets rendered as `role="img"` and labelled
+     * using the provided text.
+     *
+     * This prop is not required if the icon is purely decorative. By default, the icon
+     * will be hidden from the accessibility tree.
+     */
+    alt?: string;
 }
 /**
  * Icon component that provides fill and sizing to the SVGs from `@itwin/itwinui-icons`.
  * It uses an external symbol sprite to render the icon based on the specified `size`.
  *
  * ```tsx
- * const arrowIcon = new URL("@itwin/itwinui-icons/icons/arrow.svg", import.meta.url).href;
+ * const arrowIcon = new URL("@itwin/itwinui-icons/arrow.svg", import.meta.url).href;
  * <Icon href={arrowIcon} />
  * ```
  *
@@ -21,9 +40,15 @@ interface IconProps extends Omit<BaseProps<"svg">, "children"> {
  * <Icon render={<svg><path d="…" fill="currentColor" /></svg>} />
  * ```
  *
- * **Note**: This component is meant to be used with decorative icons, so it adds `aria-hidden` by default.
+ * By default, this component assumes that the icon is decorative, so it adds `aria-hidden` by default.
+ *
+ * If the icon is semantically meaningful, the `alt` prop can be used to provide alternative text.
+ *
+ * ```tsx
+ * <Icon href={…} alt="Help" />
+ * ```
  */
-export declare const Icon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<SVGSVGElement>>;
+export declare const Icon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<HTMLElement | SVGSVGElement>>;
 interface DisclosureArrowProps extends Omit<BaseProps<"svg">, "children"> {
     /**
      * Which direction should the arrow point towards?
@@ -31,5 +56,11 @@ interface DisclosureArrowProps extends Omit<BaseProps<"svg">, "children"> {
      */
     direction?: "down" | "right";
 }
-export declare const DisclosureArrow: React.ForwardRefExoticComponent<DisclosureArrowProps & React.RefAttributes<SVGSVGElement>>;
+export declare const DisclosureArrow: React.ForwardRefExoticComponent<DisclosureArrowProps & React.RefAttributes<HTMLElement | SVGSVGElement>>;
+interface CheckmarkProps extends Omit<BaseProps<"svg">, "children"> {
+}
+export declare const Checkmark: React.ForwardRefExoticComponent<CheckmarkProps & React.RefAttributes<HTMLElement | SVGSVGElement>>;
+interface DismissProps extends Omit<BaseProps<"svg">, "children"> {
+}
+export declare const Dismiss: React.ForwardRefExoticComponent<DismissProps & React.RefAttributes<HTMLElement | SVGSVGElement>>;
 export {};

package/dist/bricks/Icon.js

@@ -1,59 +1,120 @@
 import { jsx } from "react/jsx-runtime";
 import * as React from "react";
 import cx from "classnames";
-import * as Ariakit from "@ariakit/react";
-const Icon = React.forwardRef(
+import { Role } from "@ariakit/react/role";
+import { forwardRef } from "./~utils.js";
+const Icon = forwardRef((props, forwardedRef) => {
+  const { href, size, alt, ...rest } = props;
+  const isDecorative = !alt;
+  return /* @__PURE__ */ jsx(
+    Role.svg,
+    {
+      "aria-hidden": isDecorative ? "true" : void 0,
+      role: isDecorative ? void 0 : "img",
+      "aria-label": isDecorative ? void 0 : alt,
+      ...rest,
+      "data-kiwi-size": size,
+      className: cx("\u{1F95D}-icon", props.className),
+      ref: forwardedRef,
+      children: href ? /* @__PURE__ */ jsx("use", { href: toIconHref(href, size) }) : null
+    }
+  );
+});
+function toIconHref(href, size) {
+  const separator = href.includes("#") ? "--" : "#";
+  const suffix = toIconId(size);
+  return `${href}${separator}${suffix}`;
+}
+function toIconId(size) {
+  if (size === "large") return "icon-large";
+  return "icon";
+}
+const DisclosureArrow = forwardRef(
   (props, forwardedRef) => {
-    const { href, size = "regular", ...rest } = props;
-    const iconId = toIconId(size);
+    const { direction = "down", ...rest } = props;
+    const path = React.useMemo(() => {
+      switch (direction) {
+        case "down":
+          return /* @__PURE__ */ jsx("path", { d: "M8 10 5 7h6l-3 3Z" });
+        case "right":
+          return /* @__PURE__ */ jsx("path", { d: "M7 11V5l3 3-3 3Z" });
+      }
+    }, [direction]);
     return /* @__PURE__ */ jsx(
-      Ariakit.Role.svg,
+      Icon,
       {
-        "data-kiwi-size": size,
-        "aria-hidden": true,
         ...rest,
-        className: cx("\u{1F95D}-icon", props.className),
-        ref: forwardedRef,
-        children: /* @__PURE__ */ jsx("use", { href: `${props.href}#${iconId}` })
+        render: /* @__PURE__ */ jsx(
+          Role.svg,
+          {
+            width: "16",
+            height: "16",
+            fill: "currentColor",
+            viewBox: "0 0 16 16",
+            render: props.render,
+            children: path
+          }
+        ),
+        className: cx("\u{1F95D}-disclosure-arrow", props.className),
+        ref: forwardedRef
+      }
+    );
+  }
+);
+const Checkmark = forwardRef(
+  (props, forwardedRef) => {
+    return /* @__PURE__ */ jsx(
+      Icon,
+      {
+        ...props,
+        render: /* @__PURE__ */ jsx(
+          Role.svg,
+          {
+            width: "16",
+            height: "16",
+            fill: "currentColor",
+            viewBox: "0 0 16 16",
+            render: props.render,
+            children: /* @__PURE__ */ jsx(
+              "path",
+              {
+                fillRule: "evenodd",
+                d: "M13.854 4.146a.5.5 0 0 1 0 .708l-7 7a.5.5 0 0 1-.708 0l-3-3a.5.5 0 1 1 .708-.708L6.5 10.793l6.646-6.647a.5.5 0 0 1 .708 0Z",
+                clipRule: "evenodd"
+              }
+            )
+          }
+        ),
+        ref: forwardedRef
+      }
+    );
+  }
+);
+const Dismiss = forwardRef(
+  (props, forwardedRef) => {
+    return /* @__PURE__ */ jsx(
+      Icon,
+      {
+        ...props,
+        render: /* @__PURE__ */ jsx(
+          Role.svg,
+          {
+            width: "16",
+            height: "16",
+            viewBox: "0 0 16 16",
+            fill: "currentColor",
+            render: props.render,
+            children: /* @__PURE__ */ jsx("path", { d: "M4.853 4.146a.5.5 0 1 0-.707.708L7.293 8l-3.147 3.146a.5.5 0 0 0 .707.708L8 8.707l3.146 3.147a.5.5 0 0 0 .707-.708L8.707 8l3.146-3.146a.5.5 0 1 0-.707-.708L8 7.293 4.853 4.146Z" })
+          }
+        ),
+        ref: forwardedRef
       }
     );
   }
 );
-function toIconId(size) {
-  if (size === "large") return "icon-large";
-  return "icon";
-}
-const DisclosureArrow = React.forwardRef((props, forwardedRef) => {
-  const { direction = "down", ...rest } = props;
-  const path = React.useMemo(() => {
-    switch (direction) {
-      case "down":
-        return /* @__PURE__ */ jsx("path", { d: "M8 10 5 7h6l-3 3Z" });
-      case "right":
-        return /* @__PURE__ */ jsx("path", { d: "M7 11V5l3 3-3 3Z" });
-    }
-  }, [direction]);
-  return /* @__PURE__ */ jsx(
-    Icon,
-    {
-      ...rest,
-      render: /* @__PURE__ */ jsx(
-        Ariakit.Role.svg,
-        {
-          width: "16",
-          height: "16",
-          fill: "currentColor",
-          viewBox: "0 0 16 16",
-          render: props.render,
-          children: path
-        }
-      ),
-      className: cx("\u{1F95D}-disclosure-arrow", props.className),
-      ref: forwardedRef
-    }
-  );
-});
 export {
+  Checkmark,
   DisclosureArrow,
+  Dismiss,
   Icon
 };