@stratakit/structures 0.1.0 → 0.1.1

package/dist/DropdownMenu.d.ts

@@ -0,0 +1,113 @@
+import * as React from "react";
+import type { MenuItemCheckboxProps, MenuProviderProps } from "@ariakit/react/menu";
+import type { PredefinedSymbol } from "@stratakit/bricks/secret-internals";
+import type { AnyString, BaseProps, FocusableProps } from "@stratakit/foundations/secret-internals";
+interface DropdownMenuProps extends Pick<MenuProviderProps, "children" | "placement" | "open" | "setOpen" | "defaultOpen"> {
+}
+/**
+ * A dropdown menu displays a list of actions or commands when the menu button is clicked.
+ *
+ * `DropdownMenu` is a compound component with subcomponents exposed for different parts.
+ *
+ * Example:
+ * ```tsx
+ * <DropdownMenu.Root>
+ *   <DropdownMenu.Button>Actions</DropdownMenu.Button>
+ *
+ *   <DropdownMenu.Content>
+ *     <DropdownMenu.Item label="Add" />
+ *     <DropdownMenu.Item label="Edit" />
+ *     <DropdownMenu.Item label="Delete" />
+ *   </DropdownMenu.Content>
+ * </DropdownMenu.Root>
+ * ```
+ *
+ * **Note**: `DropdownMenu` should not be used for navigation; it is only intended for actions.
+ */
+declare function DropdownMenuRoot(props: DropdownMenuProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DropdownMenuRoot {
+    var displayName: string;
+}
+interface DropdownMenuContentProps extends FocusableProps {
+}
+/**
+ * The actual "menu" portion containing the items shown within the dropdown.
+ *
+ * Should be used as a child of `DropdownMenu.Root`.
+ */
+declare const DropdownMenuContent: React.ForwardRefExoticComponent<DropdownMenuContentProps & React.RefAttributes<HTMLDivElement | HTMLElement>>;
+interface DropdownMenuButtonProps extends FocusableProps<"button"> {
+}
+/**
+ * The button that triggers the dropdown menu to open.  Should be used as a child of `DropdownMenu.Root`.
+ *
+ * Example:
+ * ```tsx
+ * <DropdownMenu.Button>Actions</DropdownMenu.Button>
+ * ```
+ *
+ * By default it will render a solid `Button` with a disclosure arrow. This can be
+ * customized by passing a `render` prop.
+ *
+ * ```tsx
+ * <DropdownMenu.Button
+ *   render={<IconButton variant="ghost" label="More" icon={<Icon href={…} />}  />}
+ * />
+ * ```
+ */
+declare const DropdownMenuButton: React.ForwardRefExoticComponent<DropdownMenuButtonProps & React.RefAttributes<HTMLElement | HTMLButtonElement>>;
+interface DropdownMenuItemProps extends Omit<FocusableProps<"button">, "children">, Partial<Pick<DropdownMenuItemShortcutsProps, "shortcuts"> & Pick<DropdownMenuIconProps, "icon">> {
+    /** The primary text label for the menu-item. */
+    label: React.ReactNode;
+    /** Dot shown on the right end of the menu-item. Value will be used as accessible description. */
+    unstable_dot?: string;
+}
+/**
+ * A single menu item within the dropdown menu. Should be used as a child of `DropdownMenu.Content`.
+ *
+ * Example:
+ * ```tsx
+ * <DropdownMenu.Item label="Add" />
+ * <DropdownMenu.Item label="Edit" />
+ * ```
+ */
+declare const DropdownMenuItem: React.ForwardRefExoticComponent<DropdownMenuItemProps & React.RefAttributes<HTMLElement | HTMLButtonElement>>;
+interface DropdownMenuItemShortcutsProps extends Omit<BaseProps<"span">, "children"> {
+    /**
+     * A string defining the keyboard shortcut(s) associated with the menu item.
+     *
+     * ```tsx
+     * shortcuts="S" // A single key shortcut
+     * ```
+     *
+     * Multiple keys should be separated by the `+` character. If one of the keys is
+     * recognized as a symbol name or a modifier key, it will be displayed as a symbol.
+     *
+     * ```tsx
+     * shortcuts="Control+Enter" // A multi-key shortcut, displayed as "Ctrl ⏎"
+     * ```
+     */
+    shortcuts: AnyString | `${PredefinedSymbol}+${AnyString}`;
+}
+interface DropdownMenuIconProps extends BaseProps<"svg"> {
+    /**
+     * An optional icon displayed before the menu-item label.
+     *
+     * Can be a URL of an SVG from the `@stratakit/icons` package,
+     * or a custom JSX icon.
+     */
+    icon?: string | React.JSX.Element;
+}
+interface DropdownMenuCheckboxItemProps extends Omit<FocusableProps<"button">, "onChange" | "children" | "name">, Pick<MenuItemCheckboxProps, "defaultChecked" | "checked" | "onChange" | "name" | "value">, Pick<DropdownMenuItemProps, "label" | "icon"> {
+}
+/**
+ * A single menu item within the dropdown menu. Should be used as a child of `DropdownMenu.Content`.
+ *
+ * Example:
+ * ```tsx
+ * <DropdownMenu.CheckboxItem name="add" label="Add" />
+ * <DropdownMenu.CheckboxItem name="edit" label="Edit" />
+ * ```
+ */
+declare const DropdownMenuCheckboxItem: React.ForwardRefExoticComponent<DropdownMenuCheckboxItemProps & React.RefAttributes<HTMLElement | HTMLButtonElement>>;
+export { DropdownMenuRoot as Root, DropdownMenuButton as Button, DropdownMenuContent as Content, DropdownMenuItem as Item, DropdownMenuCheckboxItem as CheckboxItem, };

package/dist/DropdownMenu.js

@@ -0,0 +1,228 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Button as ButtonAk } from "@ariakit/react/button";
+import {
+  Menu,
+  MenuButton,
+  MenuItem,
+  MenuItemCheckbox,
+  MenuProvider,
+  useMenuContext
+} from "@ariakit/react/menu";
+import { usePopoverContext } from "@ariakit/react/popover";
+import { useStoreState } from "@ariakit/react/store";
+import { Button, Kbd } from "@stratakit/bricks";
+import {
+  DisclosureArrow,
+  Dot,
+  predefinedSymbols
+} from "@stratakit/bricks/secret-internals";
+import { Icon } from "@stratakit/foundations";
+import {
+  forwardRef,
+  usePopoverApi
+} from "@stratakit/foundations/secret-internals";
+import cx from "classnames";
+import * as React from "react";
+import * as ListItem from "./~utils.ListItem.js";
+import { Checkmark } from "./~utils.icons.js";
+function DropdownMenuRoot(props) {
+  const {
+    children,
+    placement,
+    open: openProp,
+    setOpen: setOpenProp,
+    defaultOpen: defaultOpenProp
+  } = props;
+  return /* @__PURE__ */ jsx(
+    MenuProvider,
+    {
+      placement,
+      defaultOpen: defaultOpenProp,
+      open: openProp,
+      setOpen: setOpenProp,
+      popover: usePopoverContext(),
+      children
+    }
+  );
+}
+const DropdownMenuContent = forwardRef(
+  (props, forwardedRef) => {
+    const popover = usePopoverApi(useMenuContext());
+    return /* @__PURE__ */ jsx(
+      Menu,
+      {
+        portal: true,
+        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, unstable_dot, ...rest } = props;
+    const dotId = React.useId();
+    return /* @__PURE__ */ jsxs(
+      MenuItem,
+      {
+        accessibleWhenDisabled: true,
+        render: /* @__PURE__ */ jsx(
+          ListItem.Root,
+          {
+            render: /* @__PURE__ */ jsx(
+              ButtonAk,
+              {
+                accessibleWhenDisabled: true,
+                "aria-describedby": dotId,
+                ...rest,
+                className: cx("\u{1F95D}-dropdown-menu-item", props.className),
+                ref: forwardedRef
+              }
+            )
+          }
+        ),
+        children: [
+          icon ? /* @__PURE__ */ jsx(DropdownMenuIcon, { icon }) : null,
+          /* @__PURE__ */ jsx(ListItem.Content, { render: /* @__PURE__ */ jsx("span", {}), children: label }),
+          shortcuts ? /* @__PURE__ */ jsx(DropdownMenuItemShortcuts, { shortcuts }) : null,
+          unstable_dot ? /* @__PURE__ */ jsx(
+            ListItem.Decoration,
+            {
+              render: /* @__PURE__ */ jsx(Dot, { id: dotId, className: "\u{1F95D}-dropdown-menu-item-dot", children: unstable_dot })
+            }
+          ) : 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(
+    ListItem.Decoration,
+    {
+      render: /* @__PURE__ */ jsx("span", {}),
+      ...rest,
+      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 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,
+    defaultChecked,
+    checked,
+    onChange,
+    name,
+    value = defaultChecked ? "on" : void 0,
+    // For defaultChecked to work
+    ...rest
+  } = props;
+  return /* @__PURE__ */ jsxs(
+    MenuItemCheckbox,
+    {
+      accessibleWhenDisabled: true,
+      defaultChecked,
+      checked,
+      name,
+      value,
+      onChange,
+      render: /* @__PURE__ */ jsx(
+        ListItem.Root,
+        {
+          render: /* @__PURE__ */ jsx(
+            ButtonAk,
+            {
+              accessibleWhenDisabled: true,
+              ...rest,
+              className: cx("\u{1F95D}-dropdown-menu-item", props.className),
+              ref: forwardedRef
+            }
+          )
+        }
+      ),
+      children: [
+        icon ? /* @__PURE__ */ jsx(DropdownMenuIcon, { icon }) : null,
+        /* @__PURE__ */ jsx(ListItem.Content, { render: /* @__PURE__ */ jsx("span", {}), 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,
+  DropdownMenuRoot as Root
+};

package/dist/ErrorRegion.d.ts

@@ -0,0 +1,83 @@
+import * as React from "react";
+import type { BaseProps } from "@stratakit/foundations/secret-internals";
+interface ErrorRegionRootProps extends Omit<BaseProps, "children"> {
+    /**
+     * Label for the error header, usually indicating the number of errors displayed.
+     * By default this is used as a name of the region navigational landmark, however an explicit `aria-label` or `aria-labelledby` is strongly suggested.
+     *
+     * Use `undefined` if you don't want to display errors rather than conditionally rendering the component.
+     */
+    label?: React.ReactNode;
+    /**
+     * A list of error items where each item describes an individual error. Must be a list of `ErrorRegion.Item` components.
+     */
+    items?: React.ReactNode;
+    /**
+     * The controlled expanded state of the error.
+     */
+    expanded?: boolean;
+    /**
+     * Callback fired when the error is expanded.
+     *
+     * Should be used with the `expanded` prop.
+     */
+    onExpandedChange?: (expanded: boolean) => void;
+}
+/**
+ * A collapsible region that displays a list of error messages, which might originate from another
+ * component, such as `Tree`.
+ *
+ * This component is rendered as a [region landmark](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/region.html)
+ * and should be labelled either using `label` or `aria-label`/`aria-labelledby`. Changes to the `label` prop will be
+ * announced communicated using a [live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions).
+ *
+ * Example:
+ * ```tsx
+ * <ErrorRegion.Root
+ *   label="3 issues found"
+ *   items={
+ *     <>
+ *       <ErrorRegion.Item message="…" />
+ *       <ErrorRegion.Item message="…" />
+ *       <ErrorRegion.Item message="…" />
+ *     </>
+ *   }
+ * />
+ */
+declare const ErrorRegionRoot: React.ForwardRefExoticComponent<ErrorRegionRootProps & React.RefAttributes<HTMLDivElement | HTMLElement>>;
+interface ErrorRegionItemProps extends Omit<BaseProps, "children"> {
+    /**
+     * The error message. Consumers might consider using `Anchor` component to link to the associated element in the UI.
+     */
+    message?: React.ReactNode;
+    /**
+     * The `id` of the message node which can be used to semantically associate the error item with the related UI item i.e. `Tree.Item`.
+     */
+    messageId?: string;
+    /**
+     * The actions available for this item. Must be a list of anchors, each rendered as a button using `<Anchor render={<button />} />`.
+     */
+    actions?: React.ReactNode;
+}
+/**
+ * An individual error item within the `ErrorRegion` component. It displays an error message and optional actions.
+ *
+ * The `messageId` prop can be used to semantically associate the error item with the related UI item, such as a `Tree.Item`.
+ *
+ * Example:
+ * ```tsx
+ * <ErrorRegion.Item
+ *   message={<>Something went wrong with <Anchor href="item-10001">Item 10001</Anchor>.</>}
+ *   messageId="item-10001-error"
+ *   actions={<Button>Retry</Button>}
+ * />
+ *
+ * <Tree.Item
+ *   id="item-10001"
+ *   label="Item 10001"
+ *   error="item-10001-error"
+ * />
+ * ```
+ */
+declare const ErrorRegionItem: React.ForwardRefExoticComponent<ErrorRegionItemProps & React.RefAttributes<HTMLDivElement | HTMLElement>>;
+export { ErrorRegionRoot as Root, ErrorRegionItem as Item };

package/dist/ErrorRegion.js

@@ -0,0 +1,162 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import {
+  Collection,
+  CollectionItem,
+  useCollectionStore
+} from "@ariakit/react/collection";
+import {
+  Dialog,
+  DialogDisclosure,
+  DialogProvider
+} from "@ariakit/react/dialog";
+import { Role } from "@ariakit/react/role";
+import { useStoreState } from "@ariakit/react/store";
+import { Button, Text, VisuallyHidden } from "@stratakit/bricks";
+import { IconButtonPresentation } from "@stratakit/bricks/secret-internals";
+import {
+  forwardRef,
+  useControlledState
+} from "@stratakit/foundations/secret-internals";
+import cx from "classnames";
+import * as React from "react";
+import { ChevronDown, StatusIcon } from "./~utils.icons.js";
+const ErrorRegionRoot = forwardRef(
+  (props, forwardedRef) => {
+    const { label, items, expanded, onExpandedChange, ...rest } = props;
+    const labelId = React.useId();
+    const sectionLabelledBy = props["aria-labelledby"] ?? (props["aria-label"] ? void 0 : labelId);
+    const [open, setOpen] = useControlledState(
+      false,
+      expanded,
+      onExpandedChange
+    );
+    const containerRef = React.useRef(null);
+    const pulse = () => {
+      const el = containerRef.current;
+      if (!el) return;
+      const id = "--\u{1F95D}error-region-pulse";
+      const animations = el.getAnimations({ subtree: true });
+      if (animations.find((animation) => animation.id === id)) return;
+      el.animate(
+        [
+          {
+            boxShadow: "0 0 0 0 var(--ids-color-border-attention-base)",
+            opacity: 1
+          },
+          {
+            boxShadow: "0 0 15px 2px var(--ids-color-border-attention-base)",
+            opacity: 0.7,
+            offset: 0.5
+          },
+          {
+            boxShadow: "0 0 0 0 var(--ids-color-border-attention-base)",
+            opacity: 1
+          }
+        ],
+        {
+          id,
+          duration: 600,
+          easing: "cubic-bezier(0.4, 0, 0.2, 1)",
+          pseudoElement: "::before"
+        }
+      );
+    };
+    const store = useCollectionStore({
+      setItems: (newItems) => {
+        const prevItemsSet = new Set(prevItems.map((item) => item.id));
+        const addedItems = newItems.filter(
+          (item) => !prevItemsSet.has(item.id)
+        );
+        if (addedItems.length === 0) return;
+        pulse();
+        setLiveLabel(label);
+      }
+    });
+    const prevItems = useStoreState(store, "items");
+    const [liveLabel, setLiveLabel] = React.useState(label);
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(VisuallyHidden, { "aria-live": "polite", "aria-atomic": true, children: liveLabel === label ? liveLabel : void 0 }),
+      /* @__PURE__ */ jsx(DialogProvider, { open, setOpen, children: /* @__PURE__ */ jsx(
+        Role.section,
+        {
+          ...rest,
+          "aria-labelledby": sectionLabelledBy,
+          className: cx("\u{1F95D}-error-region", props.className),
+          "data-kiwi-visible": !!label,
+          "data-kiwi-expanded": open,
+          ref: forwardedRef,
+          children: /* @__PURE__ */ jsxs("div", { className: "\u{1F95D}-error-region-container", ref: containerRef, children: [
+            /* @__PURE__ */ jsxs(
+              DialogDisclosure,
+              {
+                className: "\u{1F95D}-error-region-header",
+                render: /* @__PURE__ */ jsx(Button, { variant: "ghost" }),
+                children: [
+                  /* @__PURE__ */ jsx(StatusIcon, { tone: "attention", className: "\u{1F95D}-error-region-icon" }),
+                  /* @__PURE__ */ jsx(
+                    Text,
+                    {
+                      render: /* @__PURE__ */ jsx("span", {}),
+                      id: labelId,
+                      className: "\u{1F95D}-error-region-label",
+                      variant: "body-sm",
+                      children: label
+                    }
+                  ),
+                  /* @__PURE__ */ jsx(IconButtonPresentation, { inert: true, variant: "ghost", children: /* @__PURE__ */ jsx(ChevronDown, {}) })
+                ]
+              }
+            ),
+            /* @__PURE__ */ jsx(
+              Dialog,
+              {
+                className: "\u{1F95D}-error-region-dialog",
+                portal: false,
+                modal: false,
+                autoFocusOnShow: false,
+                "aria-labelledby": labelId,
+                children: /* @__PURE__ */ jsx(
+                  Collection,
+                  {
+                    store,
+                    className: "\u{1F95D}-error-region-items",
+                    role: "list",
+                    children: items
+                  }
+                )
+              }
+            )
+          ] })
+        }
+      ) })
+    ] });
+  }
+);
+const ErrorRegionItem = forwardRef(
+  (props, forwardedRef) => {
+    const generatedId = React.useId();
+    const {
+      message,
+      messageId = `${generatedId}-message`,
+      actions,
+      ...rest
+    } = props;
+    return /* @__PURE__ */ jsxs(
+      CollectionItem,
+      {
+        ...rest,
+        role: "listitem",
+        className: cx("\u{1F95D}-error-region-item", props.className),
+        ref: forwardedRef,
+        children: [
+          /* @__PURE__ */ jsx(Text, { id: messageId, variant: "body-sm", children: message }),
+          /* @__PURE__ */ jsx("div", { className: "\u{1F95D}-error-region-item-actions", children: actions })
+        ]
+      }
+    );
+  }
+);
+export {
+  ErrorRegionItem as Item,
+  ErrorRegionRoot as Root
+};