@devopness/ui-react 2.145.1 → 2.147.0

package/README.md

@@ -2,8 +2,6 @@
 
 The official Devopness UI components for React
 
-<!-- TODO: enable this section once package is available in npm registry
-
 ## Usage
 
 ### Install/Upgrade
@@ -18,7 +16,15 @@ npm install @devopness/ui-react
 yarn add @devopness/ui-react
 ```
 
- -->
+## ✍️ <a id="contributing"></a>Contributing
+
+Improvements and contributions are highly encouraged! 🙏👊
+
+See the [contributing guide](../../../CONTRIBUTING.md) for details on how to participate.
+
+All communication and contributions to Devopness projects are subject to the [Devopness Code of Conduct](../../../CODE_OF_CONDUCT.md).
+
+Not yet ready to contribute but do like the project? Support Devopness with a ⭐!
 
 ## Dependencies
 

package/dist/colors/getColor.d.ts

@@ -1,4 +1,4 @@
-import { Flatten } from './types';
+import { Flatten, OpacityFromFloatToHex } from './types';
 declare const colors: {
     readonly amber: {
         readonly 800: "#a39015";
@@ -123,5 +123,24 @@ type Color = keyof ColorToHexMapper;
  * @param name Color name on format <color>.<shade>
  */
 declare const getColor: <TColor extends Color>(name: TColor) => ColorToHexMapper[TColor];
+/**
+ * Adds opacity suffix to colors
+ *
+ * @param color string in hexadecimal format #rrggbb
+ *
+ * @param opacity number in range 0.0 to 1.0
+ *
+ * This methods transform opacity from number to a hexadecimal (16) color alpha component, meaning
+ * a number between 0 and ff (255) in base 16
+ *
+ * @returns color with added opacity information #rrggbbaa
+ *
+ * @example
+ *
+ * > getOpacity(#fff1e0, 0.5) // => #fff1e07f, 7f == 0.5
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color#a}
+ */
+declare const getOpacity: <HexColor extends ColorToHexMapper[Color], Opacity extends number>(color: HexColor, opacity: Opacity) => Exclude<HexColor, `#${string}`> | `${Extract<HexColor, `#${string}`>}${Opacity extends keyof OpacityFromFloatToHex ? OpacityFromFloatToHex[Opacity] : "00" | "19" | "33" | "4c" | "66" | "7f" | "99" | "b2" | "cc" | "e5" | "ff" | "01" | "02" | "03" | "04" | "05" | "06" | "07" | "08" | "09" | "0a" | "0b" | "0c" | "0d" | "0e" | "0f" | "10" | "11" | "12" | "13" | "14" | "15" | "16" | "17" | "18" | "1a" | "1b" | "1c" | "1d" | "1e" | "1f" | "20" | "21" | "22" | "23" | "24" | "25" | "26" | "27" | "28" | "29" | "2a" | "2b" | "2c" | "2d" | "2e" | "2f" | "30" | "31" | "32" | "34" | "35" | "36" | "37" | "38" | "39" | "3a" | "3b" | "3c" | "3d" | "3e" | "3f" | "40" | "41" | "42" | "43" | "44" | "45" | "46" | "47" | "48" | "49" | "4a" | "4b" | "4d" | "4e" | "4f" | "50" | "51" | "52" | "53" | "54" | "55" | "56" | "57" | "58" | "59" | "5a" | "5b" | "5c" | "5d" | "5e" | "5f" | "60" | "61" | "62" | "63" | "64" | "65" | "67" | "68" | "69" | "6a" | "6b" | "6c" | "6d" | "6e" | "6f" | "70" | "71" | "72" | "73" | "74" | "75" | "76" | "77" | "78" | "79" | "7a" | "7b" | "7c" | "7d" | "7e" | "80" | "81" | "82" | "83" | "84" | "85" | "86" | "87" | "88" | "89" | "8a" | "8b" | "8c" | "8d" | "8e" | "8f" | "90" | "91" | "92" | "93" | "94" | "95" | "96" | "97" | "98" | "9a" | "9b" | "9c" | "9d" | "9e" | "9f" | "a0" | "a1" | "a2" | "a3" | "a4" | "a5" | "a6" | "a7" | "a8" | "a9" | "aa" | "ab" | "ac" | "ad" | "ae" | "af" | "b0" | "b1" | "b3" | "b4" | "b5" | "b6" | "b7" | "b8" | "b9" | "ba" | "bb" | "bc" | "bd" | "be" | "bf" | "c0" | "c1" | "c2" | "c3" | "c4" | "c5" | "c6" | "c7" | "c8" | "c9" | "ca" | "cb" | "cd" | "ce" | "cf" | "d0" | "d1" | "d2" | "d3" | "d4" | "d5" | "d6" | "d7" | "d8" | "d9" | "da" | "db" | "dc" | "dd" | "de" | "df" | "e0" | "e1" | "e2" | "e3" | "e4" | "e6" | "e7" | "e8" | "e9" | "ea" | "eb" | "ec" | "ed" | "ee" | "ef" | "f0" | "f1" | "f2" | "f3" | "f4" | "f5" | "f6" | "f7" | "f8" | "f9" | "fa" | "fb" | "fc" | "fd" | "fe"}`;
 export type { Color };
-export { getColor };
+export { getColor, getOpacity };

package/dist/colors/index.d.ts

@@ -1,2 +1 @@
 export * from './getColor';
-export * from './types';

package/dist/colors/types.d.ts

@@ -20,4 +20,22 @@ type Flatten<T extends object> = object extends T ? object : {
 } extends Record<keyof T, (y: infer O) => void> ? O extends infer _ ? {
     [K in keyof O]: O[K];
 } : never : never;
-export type { Flatten };
+/**
+ * Maps opacity values in range [begin=0,end=1,step=0.1] to Hexadecimal
+ */
+type OpacityFromFloatToHex = {
+    0: '00';
+    0.1: '19';
+    0.2: '33';
+    0.3: '4c';
+    0.4: '66';
+    0.5: '7f';
+    0.6: '99';
+    0.7: 'b2';
+    0.8: 'cc';
+    0.9: 'e5';
+    1: 'ff';
+};
+/** Represents a digit of a Hexadecimal value, base 16 */
+type HexDigit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 'a' | 'b' | 'c' | 'd' | 'e' | 'f';
+export type { Flatten, OpacityFromFloatToHex, HexDigit };

package/dist/components/Buttons/Button/Button.d.ts

@@ -1,6 +1,6 @@
 import { ButtonHTMLAttributes } from 'react';
-import { getColor } from 'src/colors';
-import { Icon } from 'src/icons';
+import { getColor } from '../../../colors';
+import { Icon } from '../../../icons';
 type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
     /**
      * By default the button component is 34px high, the "typeSize" property contains

package/dist/components/Primitives/Dropdown/Dropdown.d.ts

@@ -0,0 +1,165 @@
+import { default as React } from 'react';
+import { PopoverOrigin } from '@mui/material/Popover';
+import { InjectedProps as PopupStateProps } from 'material-ui-popup-state';
+import { Color } from '../../../colors';
+import { ButtonProps } from '../../Buttons';
+import { IconProps } from '../Icon';
+import { TooltipProps } from '../Tooltip';
+import { Unwrap } from '../../types';
+type DropdownOptionIcon = Unwrap<Partial<Pick<IconProps, 'name' | 'size'>> & Pick<React.CSSProperties, 'backgroundColor' | 'color'>> & {
+    icon: true;
+};
+type DropdownOptionLetter = Unwrap<Pick<React.CSSProperties, 'backgroundColor' | 'color'>> & {
+    icon?: never;
+};
+type DropdownOption = {
+    /**
+     * Add separator from previous options
+     */
+    brokenSequence?: boolean;
+    /**
+     * Option Badge configuration
+     *
+     * An option badge can be an icon or the label's first letter
+     */
+    badge?: DropdownOptionIcon | DropdownOptionLetter;
+    /**
+     * Option description
+     */
+    label?: string;
+    /**
+     * Highlight option
+     */
+    isActive?: boolean;
+    /**
+     * Background Color to use when option is active
+     */
+    activeBackgroundColor?: Color;
+    /**
+     * Event handler called when this option is clicked.
+     */
+    onClick?: () => null;
+    /**
+     * Transforms label to a Link and point user to this url
+     *
+     * @see {Link}
+     */
+    url?: string;
+    /**
+     * Disables option
+     */
+    isDisabled?: boolean;
+    /**
+     * Tooltip's title
+     *
+     * @see {Tooltip}
+     */
+    tooltip?: TooltipProps['title'];
+    /**
+     * Label text color
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/color}
+     */
+    color?: Color;
+};
+type DropdownSharedProps = {
+    /**
+     * This is the point on the anchor where the popover's
+     * `anchorEl` will attach to. This is not used when the
+     * anchorReference is 'anchorPosition'.
+     *
+     * Options:
+     * vertical: [top, center, bottom];
+     * horizontal: [left, center, right].
+     *
+     * help: https://mui.com/material-ui/react-popover/#anchor-playground
+     */
+    anchorOrigin?: PopoverOrigin;
+    /**
+     * This is the point on the popover which
+     * will attach to the anchor's origin.
+     *
+     * Options:
+     * vertical: [top, center, bottom, x(px)];
+     * horizontal: [left, center, right, x(px)].
+     *
+     * help: https://mui.com/material-ui/react-popover/#anchor-playground
+     */
+    transformOrigin?: PopoverOrigin;
+    /**
+     * The unique id to identify the dropdown anchor element.
+     */
+    id: string;
+    /**
+     * Options listed in the Dropdown menu popup.
+     *
+     * @see {DropdownOption}
+     */
+    options: DropdownOption[] | undefined;
+    /**
+     * Event handler called when the dropdown is opened or closed.
+     */
+    onToggle?: (popupState: PopupStateProps) => void;
+    /**
+     * Event handler called when a dropdown option is selected.
+     *
+     * This prop can be overriden using option.onClick
+     *
+     * @see {DropdownOption}
+     */
+    onSelect?: (itemClicked: DropdownOption) => void;
+    /**
+     * Tooltip's title
+     *
+     * @see {Tooltip}
+     */
+    tooltip?: TooltipProps['title'];
+};
+type DropdownVariationButtonProps = DropdownSharedProps & {
+    /**
+     * Anchors dropdown to Button
+     *
+     * @see {Button}
+     */
+    anchorType: 'button';
+    /**
+     * Hide dropdown arrow icon
+     */
+    hideDropdownIcon?: boolean;
+    /**
+     * Hide dropdown label text
+     */
+    hideLabel?: boolean;
+    /**
+     * Button properties
+     *
+     * @see {Button}
+     */
+    buttonProps?: ButtonProps;
+    /**
+     * Button label
+     *
+     * Default value: 'Open Popover'
+     */
+    label?: string | React.JSX.Element;
+    content?: never;
+};
+type DropdownVariationContainerProps = DropdownSharedProps & {
+    /**
+     * Anchors dropdown to React.ReactNode content element
+     *
+     * @see {React.ReactNode}
+     */
+    anchorType: 'content';
+    /**
+     * Element to be used as anchor, to toggle dropdown when clicked.
+     */
+    content: React.ReactNode;
+};
+type DropdownProps = DropdownVariationContainerProps | DropdownVariationButtonProps;
+/**
+ * Display a menu with a list of options
+ */
+declare const Dropdown: ({ onToggle, onSelect, content, anchorType, ...props }: DropdownProps) => import("react/jsx-runtime").JSX.Element;
+export type { DropdownOption, DropdownProps };
+export { Dropdown };

package/dist/components/Primitives/Dropdown/Dropdown.styled.d.ts

@@ -0,0 +1,17 @@
+import { DropdownOption } from './Dropdown';
+import { Color } from '../../../colors';
+type StyledProps = {
+    brokenSequence?: boolean;
+    backgroundColor?: string;
+    isActive?: boolean;
+    disabled?: boolean | undefined;
+    color?: Color;
+} & Partial<Pick<DropdownOption, 'activeBackgroundColor'>>;
+declare const MenuContainer: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components/dist/types').Substitute<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, StyledProps>> & string;
+declare const MenuOption: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components/dist/types').Substitute<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, StyledProps>> & string;
+declare const Text: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components/dist/types').Substitute<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, StyledProps>> & string;
+declare const ContentBadge: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components/dist/types').Substitute<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, StyledProps>> & string;
+declare const ClickableContainer: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components/dist/types').Substitute<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, StyledProps>> & string;
+declare const Grid: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components/dist/types').Substitute<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, StyledProps>> & string;
+declare const Wrapper: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components/dist/types').Substitute<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, StyledProps>> & string;
+export { MenuContainer, MenuOption, Text, ContentBadge, ClickableContainer, Grid, Wrapper, };

package/dist/components/Primitives/Dropdown/index.d.ts

@@ -0,0 +1 @@
+export * from './Dropdown';

package/dist/components/Primitives/Icon/Icon.d.ts

@@ -0,0 +1,44 @@
+import { HTMLAttributes } from 'react';
+import { Color } from '../../../colors';
+import { Icon as IconName } from '../../../icons';
+type IconProps = {
+    /**
+     * Defines which icon to render from Devopness UI Icons
+     *
+     * @see iconLoader
+     */
+    name: IconName | undefined;
+    /** Defines element height and width */
+    size?: number;
+    /**
+     * Defines element foreground/fill color
+     *
+     * https://developer.mozilla.org/en-US/docs/Web/CSS/color
+     * https://developer.mozilla.org/en-US/docs/Web/CSS/fill
+     *
+     * @see {getColor}
+     */
+    color?: Color;
+    /**
+     * Defines the degree to which content behind an element is hidden; is a number in the range 0.0 to 1.0
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/opacity}
+     */
+    opacity?: number;
+    /**
+     * Defines a string value that labels the current element
+     *
+     * Uses name as fallback, if prop is undefined
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label}
+     */
+    ariaLabel?: HTMLAttributes<HTMLOrSVGImageElement>['aria-label'];
+};
+/**
+ * Loads icon from iconLoader
+ *
+ * @see {@link src/icons/iconLoader.tsx:iconLoader}
+ */
+declare const Icon: (props: IconProps) => import("react").JSX.Element;
+export type { IconProps };
+export { Icon };

package/dist/components/Primitives/Icon/index.d.ts

@@ -0,0 +1 @@
+export * from './Icon';

package/dist/components/Primitives/Link/Link.d.ts

@@ -0,0 +1,51 @@
+import { HTMLProps, default as React } from 'react';
+import { Color } from '../../../colors';
+import { IconProps } from '../Icon';
+import { Unwrap } from '../../types';
+type LinkProps = Omit<HTMLProps<HTMLAnchorElement>, 'href' | 'target' | 'color' | 'ref' | 'as'> & {
+    /**
+     * Defines element foreground color
+     *
+     * https://developer.mozilla.org/en-US/docs/Web/CSS/color
+     * https://developer.mozilla.org/en-US/docs/Web/CSS/fill
+     *
+     * @see {getColor}
+     */
+    color?: Color;
+    /**
+     * The URL that the hyperlink points to.
+     *
+     * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href
+     */
+    to?: HTMLProps<HTMLAnchorElement>['href'];
+    /**
+     * Where to display the linked URL.
+     *
+     * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target
+     */
+    target?: '_blank' | '_self';
+    /**
+     * Icon's Props
+     *
+     * @see {Icon}
+     */
+    iconProps?: Unwrap<Omit<IconProps, 'name'>>;
+    /**
+     * Hides default underline when the element is visible
+     */
+    hideUnderline?: boolean;
+    /**
+     * Hides underline when hovering the element
+     */
+    hideUnderlineOnHover?: boolean;
+    /**
+     * Hides External URL Icon
+     */
+    hideExternalUrlIcon?: boolean;
+};
+/**
+ * Display a hyperlink to other application pages or external resources
+ */
+declare const Link: ({ target, children, color, rel, to: href, hideUnderline, hideUnderlineOnHover, hideExternalUrlIcon, iconProps, ...props }: React.PropsWithChildren<LinkProps>) => import("react/jsx-runtime").JSX.Element;
+export type { LinkProps };
+export { Link };

package/dist/components/Primitives/Link/Link.styled.d.ts

@@ -0,0 +1,6 @@
+type StyledLinkProps = {
+    $showUnderline: boolean;
+    $showUnderlineOnHover: boolean;
+};
+declare const StyledLink: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components/dist/types').Substitute<import('react').DetailedHTMLProps<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, StyledLinkProps>> & string;
+export { StyledLink };

package/dist/components/Primitives/Link/index.d.ts

@@ -0,0 +1 @@
+export * from './Link';

package/dist/components/Primitives/Tooltip/Tooltip.d.ts

@@ -1,8 +1,9 @@
 import { TooltipProps } from '@mui/material/Tooltip';
+import { Unwrap } from '../../types';
 type Nullable<T extends object> = {
     [K in keyof T]: T[K] | null | undefined;
 };
-type TooltipComponentProps = {
+type TooltipComponentProps = Unwrap<{
     /**
      * Tooltip reference element.
      */
@@ -35,7 +36,8 @@ type TooltipComponentProps = {
      * in the controlled way
      */
     open?: boolean;
-} & Omit<TooltipProps, 'title' | 'children'> & Nullable<Pick<TooltipProps, 'title'>>;
+} & Omit<TooltipProps, 'title' | 'children'> & Nullable<Pick<TooltipProps, 'title'>>>;
 /** Display informative text when users hover over a child element */
 declare const Tooltip: ({ disableHover, enableOnlyWithEllipsisPoints, title, children, ...props }: TooltipComponentProps) => import("react/jsx-runtime").JSX.Element;
+export type { TooltipComponentProps as TooltipProps };
 export { Tooltip };

package/dist/components/Primitives/index.d.ts

@@ -1 +1,5 @@
+export * from './Dropdown';
+export type { IconProps } from './Icon';
+export { Icon as IconComponent } from './Icon';
+export * from './Link';
 export * from './Tooltip';

package/dist/components/helpers.d.ts

@@ -0,0 +1,10 @@
+type ConditionalWrapperProps = {
+    condition: boolean;
+    wrapper: (children: React.ReactNode) => React.ReactNode;
+    children: React.ReactNode;
+};
+/**
+ * Wraps children if a condition is met
+ */
+declare const ConditionalWrapper: ({ condition, wrapper, children, }: ConditionalWrapperProps) => import('react').ReactNode;
+export { ConditionalWrapper };

package/dist/components/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Unwrap<T>
+ *
+ * Construct a type with the all properties of T without intersections.
+ * This makes the hover overlay and the story generated type description more readable.
+ *
+ * @example Both types below are equivalent
+ *
+ * type Intersected = { a: string; } & { b: number; } & { c: boolean; }
+ * //   ^? { a: string; } & { b: number; } & { c: boolean; }
+ * type UnwrappedIntersected = Unwrap<Intersected>
+ * //   ^? { a: string; b: number; c: boolean; }
+ *
+ * @example Both types below are equivalent
+ *
+ * type PickFromTwoTypes = Pick<Intersected, 'a' | 'b'> & Pick<Intersected, 'c'>
+ * //   ^? Pick<Intersected, 'a' | 'b'> & Pick<Intersected, 'c'>
+ * type UnwrappedPickFromTwoTypes = Unwrap<PickFromTwoTypes>
+ * //   ^? { a: string; b: number; c: boolean; }
+ *
+ * Code obtained from Total TypeScript: https://www.totaltypescript.com/concepts/the-prettify-helper
+ * Source code from mattpocock @ https://github.com/mattpocock
+ */
+type Unwrap<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export type { Unwrap };