@primer/components 0.0.0-202111023745 → 0.0.0-2021111122934

package/lib/src/ActionList/Header.d.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+import { SxProp } from '../sx';
+/**
+ * Contract for props passed to the `Header` component.
+ */
+export interface HeaderProps extends React.ComponentPropsWithoutRef<'div'>, SxProp {
+    /**
+     * Style variations. Usage is discretionary.
+     *
+     * - `"filled"` - Superimposed on a background, offset from nearby content
+     * - `"subtle"` - Relatively less offset from nearby content
+     */
+    variant?: 'subtle' | 'filled';
+    /**
+     * Primary text which names a `Group`.
+     */
+    title: string;
+    /**
+     * Secondary text which provides additional information about a `Group`.
+     */
+    auxiliaryText?: string;
+}
+export declare const StyledHeader: import("styled-components").StyledComponent<"div", any, {
+    variant: HeaderProps['variant'];
+} & SxProp, never>;
+/**
+ * Displays the name and description of a `Group`.
+ */
+export declare function Header({ variant, title, auxiliaryText, children: _children, ...props }: HeaderProps): JSX.Element;

package/lib/src/ActionList/Item.d.ts

@@ -0,0 +1,98 @@
+import { IconProps } from '@primer/octicons-react';
+import React from 'react';
+import { SxProp } from '../sx';
+import { ItemInput } from './List';
+import { ForwardRefComponent as PolymorphicForwardRefComponent } from '@radix-ui/react-polymorphic';
+import { AriaRole } from '../utils/types';
+/**
+ * Contract for props passed to the `Item` component.
+ */
+export interface ItemProps extends SxProp {
+    /**
+     * Primary text which names an `Item`.
+     */
+    text?: string;
+    /**
+     * Secondary text which provides additional information about an `Item`.
+     */
+    description?: string;
+    /**
+     * Secondary text style variations. Usage is discretionary.
+     *
+     * - `"inline"` - Secondary text is positioned beside primary text.
+     * - `"block"` - Secondary text is positioned below primary text.
+     */
+    descriptionVariant?: 'inline' | 'block';
+    /**
+     * Icon (or similar) positioned before `Item` text.
+     */
+    leadingVisual?: React.FunctionComponent<IconProps>;
+    /**
+     * @deprecated Use `trailingVisual` instead
+     * Icon (or similar) positioned after `Item` text.
+     */
+    trailingIcon?: React.FunctionComponent<IconProps>;
+    /**
+     * @deprecated Use `trailingVisual` instead
+     * Text positioned after `Item` text and optional trailing icon.
+     */
+    trailingText?: string;
+    /**
+     * Icon or text positioned after `Item` text.
+     */
+    trailingVisual?: React.ReactNode;
+    /**
+     * Style variations associated with various `Item` types.
+     *
+     * - `"default"` - An action `Item`.
+     * - `"danger"` - A destructive action `Item`.
+     */
+    variant?: 'default' | 'danger';
+    /**
+     * Whether to display a divider above the `Item` when it does not follow a `Header` or `Divider`.
+     */
+    showDivider?: boolean;
+    /**
+     * For `Item`s which can be selected, whether the `Item` is currently selected.
+     */
+    selected?: boolean;
+    /**
+     *  For `Item`s which can be selected, whether `multiple` `Item`s or a `single` `Item` can be selected
+     */
+    selectionVariant?: 'single' | 'multiple';
+    /**
+     * Designates the group that an item belongs to.
+     */
+    groupId?: string;
+    /**
+     * Items that are disabled can not be clicked, selected, or navigated through.
+     */
+    disabled?: boolean;
+    /**
+     * Callback that will trigger both on click selection and keyboard selection.
+     */
+    onAction?: (item: ItemProps, event: React.MouseEvent<HTMLDivElement> | React.KeyboardEvent<HTMLDivElement>) => void;
+    /**
+     * An id associated with this item.  Should be unique between items
+     */
+    id?: number | string;
+    /**
+     * Node to be included inside the item before the text.
+     */
+    children?: React.ReactNode;
+    /**
+     * The ARIA role describing the function of `List` component. `option` is a common value.
+     */
+    role?: AriaRole;
+    /**
+     * An item to pass back in the `onAction` callback, meant as
+     */
+    item?: ItemInput;
+}
+export declare const TextContainer: import("styled-components").StyledComponent<"span", any, {
+    dangerouslySetInnerHtml?: React.DOMAttributes<HTMLDivElement>['dangerouslySetInnerHTML'];
+}, never>;
+/**
+ * An actionable or selectable `Item` with an optional icon and description.
+ */
+export declare const Item: PolymorphicForwardRefComponent<"div", ItemProps>;

package/lib/src/ActionList/List.d.ts

@@ -0,0 +1,88 @@
+import React, { Key } from 'react';
+import type { AriaRole } from '../utils/types';
+import { Group, GroupProps } from './Group';
+import { ItemProps } from './Item';
+import { Merge } from '../utils/types/Merge';
+declare type RenderItemFn = (props: ItemProps) => React.ReactElement;
+export declare type ItemInput = Merge<React.ComponentPropsWithoutRef<'div'>, ItemProps> | ((Partial<ItemProps> & {
+    renderItem: RenderItemFn;
+}) & {
+    key?: Key;
+});
+/**
+ * Contract for props passed to the `List` component.
+ */
+export interface ListPropsBase {
+    /**
+     * A collection of `Item` props and `Item`-level custom `Item` renderers.
+     */
+    items: ItemInput[];
+    /**
+     * The ARIA role describing the function of `List` component. `listbox` is a common value.
+     */
+    role?: AriaRole;
+    /**
+     * id to attach to the base DOM node of the list
+     */
+    id?: string;
+    /**
+     * A `List`-level custom `Item` renderer. Every `Item` within this `List`
+     * without a `Group`-level or `Item`-level custom `Item` renderer will be
+     * rendered using this function component.
+     */
+    renderItem?: RenderItemFn;
+    /**
+     * A `List`-level custom `Group` renderer. Every `Group` within this `List`
+     * without a `Group`-level custom `Item` renderer will be rendered using
+     * this function component.
+     */
+    renderGroup?: typeof Group;
+    /**
+     * Style variations. Usage is discretionary.
+     *
+     * - `"inset"` - `List` children are offset (vertically and horizontally) from `List`’s edges
+     * - `"full"` - `List` children are flush (vertically and horizontally) with `List` edges
+     */
+    variant?: 'inset' | 'full';
+    /**
+     *  For `Item`s which can be selected, whether `multiple` `Item`s or a `single` `Item` can be selected
+     */
+    selectionVariant?: 'single' | 'multiple';
+    /**
+     * Whether to display a divider above each `Item` in this `List` when it does not follow a `Header` or `Divider`.
+     */
+    showItemDividers?: boolean;
+}
+/**
+ * Contract for props passed to the `List` component, when its `Item`s are collected in `Group`s.
+ */
+export interface GroupedListProps extends ListPropsBase {
+    /**
+     * A collection of `Group` props (except `items`), plus a unique group identifier
+     * and `Group`-level custom `Item` or `Group` renderers.
+     */
+    groupMetadata: ((Omit<GroupProps, 'items'> | Omit<Partial<GroupProps> & {
+        renderItem?: RenderItemFn;
+        renderGroup?: typeof Group;
+    }, 'items'>) & {
+        groupId: string;
+    })[];
+    /**
+     * A collection of `Item` props, plus associated group identifiers
+     * and `Item`-level custom `Item` renderers.
+     */
+    items: ((ItemProps | (Partial<ItemProps> & {
+        renderItem: RenderItemFn;
+    })) & {
+        groupId: string;
+    })[];
+}
+/**
+ * Contract for props passed to the `List` component.
+ */
+export declare type ListProps = ListPropsBase | GroupedListProps;
+/**
+ * Lists `Item`s, either grouped or ungrouped, with a `Divider` between each `Group`.
+ */
+export declare const List: React.ForwardRefExoticComponent<ListProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/lib/src/ActionList/index.d.ts

@@ -0,0 +1,17 @@
+/// <reference types="react" />
+import { Group } from './Group';
+import { Divider } from './Divider';
+export type { ListProps as ActionListProps } from './List';
+export type { GroupProps } from './Group';
+export type { ItemProps } from './Item';
+/**
+ * Collection of list-related components.
+ */
+export declare const ActionList: import("react").ForwardRefExoticComponent<import("./List").ListProps & import("react").RefAttributes<HTMLDivElement>> & {
+    /** Collects related `Items` in an `ActionList`. */
+    Group: typeof Group;
+    /** An actionable or selectable `Item` with an optional icon and description. */
+    Item: import("@radix-ui/react-polymorphic").ForwardRefComponent<"div", import("./Item").ItemProps>;
+    /** Visually separates `Item`s or `Group`s in an `ActionList`. */
+    Divider: typeof Divider;
+};

package/lib/src/ActionList2/Description.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { SxProp } from '../sx';
+export declare type DescriptionProps = {
+    /**
+     * Secondary text style variations.
+     *
+     * - `"inline"` - Secondary text is positioned beside primary text.
+     * - `"block"` - Secondary text is positioned below primary text.
+     */
+    variant?: 'inline' | 'block';
+} & SxProp;
+export declare const Description: React.FC<DescriptionProps>;

package/lib/src/ActionList2/Divider.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="react" />
+/**
+ * Visually separates `Item`s or `Group`s in an `ActionList`.
+ */
+export declare function Divider(): JSX.Element;

package/lib/src/ActionList2/Group.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import { SxProp } from '../sx';
+import { ListProps } from './List';
+import { AriaRole } from '../utils/types';
+export declare type GroupProps = {
+    /**
+     * Style variations. Usage is discretionary.
+     *
+     * - `"filled"` - Superimposed on a background, offset from nearby content
+     * - `"subtle"` - Relatively less offset from nearby content
+     */
+    variant?: 'subtle' | 'filled';
+    /**
+     * Primary text which names a `Group`.
+     */
+    title?: string;
+    /**
+     * Secondary text which provides additional information about a `Group`.
+     */
+    auxiliaryText?: string;
+    /**
+     * The ARIA role describing the function of the list inside `Group` component. `listbox` or `menu` are a common values.
+     */
+    role?: AriaRole;
+} & SxProp & {
+    /**
+     * Whether multiple Items or a single Item can be selected in the Group. Overrides value on ActionList root.
+     */
+    selectionVariant?: ListProps['selectionVariant'] | false;
+};
+declare type ContextProps = Pick<GroupProps, 'selectionVariant'>;
+export declare const GroupContext: React.Context<ContextProps>;
+export declare const Group: React.FC<GroupProps>;
+export declare type HeaderProps = Pick<GroupProps, 'variant' | 'title' | 'auxiliaryText'> & {
+    labelId: string;
+};
+export {};

package/lib/src/ActionList2/Item.d.ts

@@ -0,0 +1,63 @@
+import React from 'react';
+import { ForwardRefComponent as PolymorphicForwardRefComponent } from '@radix-ui/react-polymorphic';
+import { SxProp } from '../sx';
+import { AriaRole } from '../utils/types';
+export declare const getVariantStyles: (variant: ItemProps['variant'], disabled: ItemProps['disabled']) => {
+    color: string;
+    iconColor: string;
+    annotationColor: string;
+    hoverColor?: undefined;
+} | {
+    color: string;
+    iconColor: string;
+    annotationColor: string;
+    hoverColor: string;
+};
+export declare type ItemProps = {
+    /**
+     * Primary content for an Item
+     */
+    children?: React.ReactNode;
+    /**
+     * Callback that will trigger both on click selection and keyboard selection.
+     */
+    onSelect?: (event: React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement>) => void;
+    /**
+     * Is the `Item` is currently selected?
+     */
+    selected?: boolean;
+    /**
+     * Style variations associated with various `Item` types.
+     *
+     * - `"default"` - An action `Item`.
+     * - `"danger"` - A destructive action `Item`.
+     */
+    variant?: 'default' | 'danger';
+    /**
+     * Items that are disabled can not be clicked, selected, or navigated through.
+     */
+    disabled?: boolean;
+    /**
+     * The ARIA role describing the function of `Item` component. `option` is a common value.
+     */
+    role?: AriaRole;
+    /**
+     * id to attach to the root element of the Item
+     */
+    id?: string;
+    /**
+     * Private API for use internally only. Used by LinkItem to wrap contents in an anchor
+     */
+    _PrivateItemWrapper?: React.FC;
+} & SxProp;
+declare const Slot: React.FC<{
+    name: "LeadingVisual" | "InlineDescription" | "BlockDescription" | "TrailingVisual";
+    children: React.ReactNode;
+}>;
+export { Slot };
+export declare type ItemContext = Pick<ItemProps, 'variant' | 'disabled'> & {
+    inlineDescriptionId: string;
+    blockDescriptionId: string;
+};
+export declare const TEXT_ROW_HEIGHT = "20px";
+export declare const Item: PolymorphicForwardRefComponent<"li", ItemProps>;

package/lib/src/ActionList2/LinkItem.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import { ForwardRefComponent as PolymorphicForwardRefComponent } from '@radix-ui/react-polymorphic';
+import { ItemProps } from './Item';
+declare type LinkProps = {
+    download?: string;
+    href?: string;
+    hrefLang?: string;
+    media?: string;
+    ping?: string;
+    rel?: string;
+    target?: string;
+    type?: string;
+    referrerPolicy?: React.AnchorHTMLAttributes<HTMLAnchorElement>['referrerPolicy'];
+};
+declare type LinkItemProps = Pick<ItemProps, 'children' | 'sx'> & LinkProps;
+export declare const LinkItem: PolymorphicForwardRefComponent<"a", LinkItemProps>;
+export {};

package/lib/src/ActionList2/List.d.ts

@@ -0,0 +1,26 @@
+import React from 'react';
+import { ForwardRefComponent as PolymorphicForwardRefComponent } from '@radix-ui/react-polymorphic';
+import { SxProp } from '../sx';
+import { AriaRole } from '../utils/types';
+export declare type ListProps = {
+    /**
+     * `inset` children are offset (vertically and horizontally) from `List`’s edges, `full` children are flush (vertically and horizontally) with `List` edges
+     */
+    variant?: 'inset' | 'full';
+    /**
+     * Whether multiple Items or a single Item can be selected.
+     */
+    selectionVariant?: 'single' | 'multiple';
+    /**
+     * Display a divider above each `Item` in this `List` when it does not follow a `Header` or `Divider`.
+     */
+    showDividers?: boolean;
+    /**
+     * The ARIA role describing the function of `List` component. `listbox` or `menu` are a common values.
+     */
+    role?: AriaRole;
+} & SxProp;
+declare type ContextProps = Pick<ListProps, 'variant' | 'selectionVariant' | 'showDividers'>;
+export declare const ListContext: React.Context<ContextProps>;
+export declare const List: PolymorphicForwardRefComponent<"ul", ListProps>;
+export {};

package/lib/src/ActionList2/Selection.d.ts

@@ -0,0 +1,5 @@
+import React from 'react';
+import { ItemProps } from './Item';
+declare type SelectionProps = Pick<ItemProps, 'selected'>;
+export declare const Selection: React.FC<SelectionProps>;
+export {};

package/lib/src/ActionList2/Visuals.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import { SxProp } from '../sx';
+declare type VisualProps = SxProp & React.HTMLAttributes<HTMLSpanElement>;
+export declare const LeadingVisualContainer: React.FC<VisualProps>;
+export declare type LeadingVisualProps = VisualProps;
+export declare const LeadingVisual: React.FC<VisualProps>;
+export declare type TrailingVisualProps = VisualProps;
+export declare const TrailingVisual: React.FC<VisualProps>;
+export {};

package/lib/src/ActionList2/index.d.ts

@@ -0,0 +1,36 @@
+/// <reference types="react" />
+import { Divider } from './Divider';
+export type { ListProps as ActionListProps } from './List';
+export type { GroupProps } from './Group';
+export type { ItemProps } from './Item';
+export type { DescriptionProps } from './Description';
+export type { LeadingVisualProps, TrailingVisualProps } from './Visuals';
+/**
+ * Collection of list-related components.
+ */
+export declare const ActionList: import("@radix-ui/react-polymorphic").ForwardRefComponent<"ul", import("./List").ListProps> & {
+    /** Collects related `Items` in an `ActionList`. */
+    Group: import("react").FC<import("./Group").GroupProps>;
+    /** An actionable or selectable `Item` */
+    Item: import("@radix-ui/react-polymorphic").ForwardRefComponent<"li", import("./Item").ItemProps>;
+    /** A `Item` that renders a full-size anchor inside ListItem */
+    LinkItem: import("@radix-ui/react-polymorphic").ForwardRefComponent<"a", Pick<import("./Item").ItemProps, "children" | "sx"> & {
+        download?: string | undefined;
+        href?: string | undefined;
+        hrefLang?: string | undefined;
+        media?: string | undefined;
+        ping?: string | undefined;
+        rel?: string | undefined;
+        target?: string | undefined;
+        type?: string | undefined;
+        referrerPolicy?: import("react").HTMLAttributeReferrerPolicy | undefined;
+    }>;
+    /** Visually separates `Item`s or `Group`s in an `ActionList`. */
+    Divider: typeof Divider;
+    /** Secondary text which provides additional information about an `Item`. */
+    Description: import("react").FC<import("./Description").DescriptionProps>;
+    /** Icon (or similar) positioned before `Item` text. */
+    LeadingVisual: import("react").FC<import("../sx").SxProp & import("react").HTMLAttributes<HTMLSpanElement>>;
+    /** Icon (or similar) positioned after `Item` text. */
+    TrailingVisual: import("react").FC<import("../sx").SxProp & import("react").HTMLAttributes<HTMLSpanElement>>;
+};

package/lib/src/ActionMenu.d.ts

@@ -0,0 +1,40 @@
+import { GroupedListProps, ListPropsBase } from './ActionList/List';
+import { ItemProps } from './ActionList/Item';
+import { Divider } from './ActionList/Divider';
+import React from 'react';
+import { OverlayProps } from './Overlay';
+import { AnchoredOverlayWrapperAnchorProps } from './AnchoredOverlay/AnchoredOverlay';
+interface ActionMenuBaseProps extends Partial<Omit<GroupedListProps, keyof ListPropsBase>>, ListPropsBase {
+    /**
+     * Content that is passed into the renderAnchor component, which is a button by default.
+     */
+    anchorContent?: React.ReactNode;
+    /**
+     * A callback that triggers both on clicks and keyboard events. This callback will be overridden by item level `onAction` callbacks.
+     */
+    onAction?: (props: ItemProps, event?: React.MouseEvent<HTMLDivElement> | React.KeyboardEvent<HTMLDivElement>) => void;
+    /**
+     * If defined, will control the open/closed state of the overlay. Must be used in conjuction with `setOpen`.
+     */
+    open?: boolean;
+    /**
+     * If defined, will control the open/closed state of the overlay. Must be used in conjuction with `open`.
+     */
+    setOpen?: (s: boolean) => void;
+    /**
+     * Props to be spread on the internal `Overlay` component.
+     */
+    overlayProps?: Partial<OverlayProps>;
+}
+export declare type ActionMenuProps = ActionMenuBaseProps & AnchoredOverlayWrapperAnchorProps;
+export declare const ActionMenu: {
+    ({ anchorContent, renderAnchor, anchorRef: externalAnchorRef, onAction, open, setOpen, overlayProps, items, ...listProps }: ActionMenuProps): JSX.Element;
+    displayName: string;
+} & {
+    Divider: typeof Divider;
+    Item: {
+        (props: ItemProps): JSX.Element;
+        displayName: string;
+    };
+};
+export {};

package/lib/src/AnchoredOverlay/AnchoredOverlay.d.ts

@@ -0,0 +1,62 @@
+import React from 'react';
+import { OverlayProps } from '../Overlay';
+import { FocusTrapHookSettings } from '../hooks/useFocusTrap';
+import { FocusZoneHookSettings } from '../hooks/useFocusZone';
+import { PositionSettings } from '../behaviors/anchoredPosition';
+interface AnchoredOverlayPropsWithAnchor {
+    /**
+     * A custom function component used to render the anchor element.
+     * Will receive the selected text as `children` prop when an item is activated.
+     */
+    renderAnchor: <T extends React.HTMLAttributes<HTMLElement>>(props: T) => JSX.Element;
+    /**
+     * An override to the internal ref that will be spread on to the renderAnchor
+     */
+    anchorRef?: React.RefObject<HTMLElement>;
+}
+interface AnchoredOverlayPropsWithoutAnchor {
+    /**
+     * A custom function component used to render the anchor element.
+     * When renderAnchor is null, an anchorRef is required.
+     */
+    renderAnchor: null;
+    /**
+     * An override to the internal renderAnchor ref that will be used to position the overlay.
+     * When renderAnchor is null this can be used to make an anchor that is detached from ActionMenu.
+     */
+    anchorRef: React.RefObject<HTMLElement>;
+}
+export declare type AnchoredOverlayWrapperAnchorProps = Partial<AnchoredOverlayPropsWithAnchor> | AnchoredOverlayPropsWithoutAnchor;
+interface AnchoredOverlayBaseProps extends Pick<OverlayProps, 'height' | 'width'> {
+    /**
+     * Determines whether the overlay portion of the component should be shown or not
+     */
+    open: boolean;
+    /**
+     * A callback which is called whenever the overlay is currently closed and an "open gesture" is detected.
+     */
+    onOpen?: (gesture: 'anchor-click' | 'anchor-key-press') => unknown;
+    /**
+     * A callback which is called whenever the overlay is currently open and a "close gesture" is detected.
+     */
+    onClose?: (gesture: 'anchor-click' | 'click-outside' | 'escape') => unknown;
+    /**
+     * Props to be spread on the internal `Overlay` component.
+     */
+    overlayProps?: Partial<OverlayProps>;
+    /**
+     * Settings to apply to the Focus Zone on the internal `Overlay` component.
+     */
+    focusTrapSettings?: Partial<FocusTrapHookSettings>;
+    /**
+     * Settings to apply to the Focus Zone on the internal `Overlay` component.
+     */
+    focusZoneSettings?: Partial<FocusZoneHookSettings>;
+}
+export declare type AnchoredOverlayProps = AnchoredOverlayBaseProps & (AnchoredOverlayPropsWithAnchor | AnchoredOverlayPropsWithoutAnchor) & Partial<Pick<PositionSettings, 'align' | 'side'>>;
+/**
+ * An `AnchoredOverlay` provides an anchor that will open a floating overlay positioned relative to the anchor.
+ * The overlay can be opened and navigated using keyboard or mouse.
+ */
+export declare const AnchoredOverlay: React.FC<AnchoredOverlayProps>;
+export {};

package/lib/src/AnchoredOverlay/index.d.ts

@@ -0,0 +1,2 @@
+export { AnchoredOverlay } from './AnchoredOverlay';
+export type { AnchoredOverlayProps } from './AnchoredOverlay';