@eccenca/gui-elements 23.2.0-rc.0 → 23.2.0-rc.1

package/src/components/Select/Select.stories.tsx

@@ -1,35 +1,64 @@
 import React from "react";
-import { ComponentStory, ComponentMeta } from "@storybook/react";
 import { loremIpsum } from "react-lorem-ipsum";
+import { Meta, StoryFn } from "@storybook/react";
 
-import {
-  Select,
-  Button,
-  MenuItem,
-} from "../../index";
+import { helpersArgTypes } from "../../../.storybook/helpers";
+import { Button, MenuItem, Select } from "../../index";
 
 export default {
-  title: "Forms/Select",
-  component: Select,
-  argTypes: {
-  },
-} as ComponentMeta<typeof Select>;
+    title: "Forms/Select",
+    component: Select,
+    argTypes: {
+        icon: {
+            ...helpersArgTypes.exampleIcon,
+        },
+        rightIcon: {
+            ...helpersArgTypes.exampleIcon,
+        },
+    },
+} as Meta<typeof Select>;
 
-const Template: ComponentStory<typeof Select> = (args) => (
-    <Select {...args}>
-        <Button alignText="left" text="Select an element" fill outlined rightIcon="toggler-showmore"/>
-    </Select>
-);
+const Template: StoryFn<typeof Select> = (args) => <Select {...args} />;
 
 export const Default = Template.bind({});
 Default.args = {
     items: loremIpsum({ p: 1, avgSentencesPerParagraph: 5, random: false })
         .toString()
         .split(".")
-        .map((item) => { return { label: item }}),
+        .map((item) => {
+            return { label: item };
+        }),
     itemRenderer: (item, props) => {
-        return <MenuItem text={item.label} />
+        return <MenuItem text={item.label} title={item.label} />;
     },
     fill: true,
-    filterable: false,
-}
+    // placeholder: loremIpsum({ p: 1, avgSentencesPerParagraph: 5, random: false })
+};
+
+/**
+ * A controlled select target is used by adding `children` elements to `<Select />` directly.
+ * Properties like `text`, `placeholder`, `onClearanceHandler` and `onClearanceText` won't be evaluated then.
+ */
+export const ControlledTarget = Template.bind({});
+ControlledTarget.args = {
+    ...Default.args,
+    fill: false,
+    children: <Button text="Controlled select target" intent="primary" />,
+};
+
+/**
+ * If the selection is not mandatory it is suggested to add an option letting the user reset the select value.
+ * `onClearanceHandler` follows the pattern to add a button on the right side of the element.
+ * An alternate way would be to add an additional select item to reset the value but this could come with a few usablity issues:
+ * user do not see it when the options are filtered, or the "empty" select option leads to the pre-selected option, etc.
+ */
+export const ClearanceOption = Template.bind({});
+ClearanceOption.args = {
+    ...Default.args,
+    text: "Example selection",
+    onClearanceText: "Reset the selection",
+    //onClearanceHandler: false,
+    onClearanceHandler: () => {
+        alert("Reset now.");
+    },
+};

package/src/components/Select/Select.tsx

@@ -1,38 +1,113 @@
 import React from "react";
-import {
-    Select2 as BlueprintSelect,
-    Select2Props as BlueprintSelectProps,
-} from "@blueprintjs/select";
-import { ContextOverlayProps } from "./../../index";
+import { Select2 as BlueprintSelect, Select2Props as BlueprintSelectProps } from "@blueprintjs/select";
 
-/**
- * FIXME: Currently we only route the original element through.
- * We should add here basic elemeents and processes for target and selections, etc.
- */
+import { CLASSPREFIX as eccgui } from "../../configuration/constants";
 
-export interface SelectProps<T> extends Omit<
-    BlueprintSelectProps<T>,
-    "popoverTargetProps" | "popoverContentProps" | "popoverProps" | "popoverRef"
-> {
+import { Button, ButtonProps, ContextOverlayProps, Icon, OverflowText } from "./../../index";
+
+export interface SelectProps<T>
+    extends Omit<BlueprintSelectProps<T>, "popoverTargetProps" | "popoverContentProps" | "popoverProps" | "popoverRef">,
+        Pick<ButtonProps, "icon" | "rightIcon"> {
+    /**
+     * Textual representation of the the selected value.
+     * This is displayed if the select target is not controlled directly via `children` elements.
+     */
+    text?: string;
+    /**
+     * Placeholder text displayed for selects without defined `text`.
+     * This is displayed if the select target is not controlled directly via `children` elements.
+     */
+    placeholder?: string;
     /**
      * Props to spread to `ContextOverlay` that is used to display the dropdown.
      */
-    contextOverlayProps?: Partial<Omit<ContextOverlayProps, "content" | "defaultIsOpen" | "disabled" | "fill" | "renderTarget" | "targetTagName">>
+    contextOverlayProps?: Partial<
+        Omit<ContextOverlayProps, "content" | "defaultIsOpen" | "disabled" | "fill" | "renderTarget" | "targetTagName">
+    >;
+    /**
+     * Event handler to reset search input.
+     * Only works with the uncontrolled default select target.
+     * If set then `rightElement` is automatically set with an action button to trigger the handler.
+     */
+    onClearanceHandler?: () => void;
+    /**
+     * Tooltip to show for the clear button.
+     * Only works with the uncontrolled default select target.
+     */
+    onClearanceText?: string;
 }
 
 /**
  * Create a Select box without the HTML select element.
  * It is possible to filter options, as well as to add new options if necessary.
+ *
+ * **Use this input element when the value is primarily selected from a defined set of elements.**
  */
-export function Select<T>({contextOverlayProps, ...otherSelectProps}: SelectProps<T>) {
+export function Select<T>({
+    contextOverlayProps,
+    className,
+    children,
+    text,
+    placeholder = "Select item ...",
+    icon,
+    rightIcon,
+    onClearanceHandler,
+    inputProps,
+    onClearanceText = "Reset selection",
+    ...otherSelectProps
+}: SelectProps<T>) {
     return (
         <BlueprintSelect<T>
-            popoverProps={{ minimal: true, ...contextOverlayProps}}
+            popoverProps={{
+                minimal: true,
+                matchTargetWidth: otherSelectProps.fill ?? false,
+                ...contextOverlayProps,
+            }}
+            inputProps={{
+                round: true,
+                ...inputProps,
+            }}
+            className={`${eccgui}-select` + (className ? ` ${className}` : "")}
             {...otherSelectProps}
-        />
+        >
+            {children ?? (
+                <Button
+                    text={text ? <OverflowText>{text}</OverflowText> : <OverflowText>{placeholder}</OverflowText>}
+                    alignText="left"
+                    outlined
+                    fill={otherSelectProps.fill ?? false}
+                    disabled={otherSelectProps.disabled ?? false}
+                    icon={icon}
+                    rightIcon={
+                        <>
+                            {onClearanceHandler && text && (
+                                <Icon
+                                    name="operation-clear"
+                                    tooltipText={onClearanceText ? onClearanceText : undefined}
+                                    onClick={(e) => {
+                                        e.stopPropagation();
+                                        onClearanceHandler();
+                                    }}
+                                />
+                            )}
+                            {typeof rightIcon === "string" ? (
+                                <Icon name={rightIcon} />
+                            ) : (
+                                rightIcon ?? <Icon name={"toggler-caretdown"} />
+                            )}
+                        </>
+                    }
+                />
+            )}
+        </BlueprintSelect>
     );
 }
 
-Select.ofType = BlueprintSelect.ofType;
+/** @deprecated: instead of `const MySelect = Select.ofType<MyType>()` use directly `<Select<MyType> {...props} />` */
+function ofType<U>() {
+    return (props: SelectProps<U>) => <Select<U> {...props} />;
+}
+
+Select.ofType = ofType;
 
 export default Select;

package/src/components/Select/_select.scss

@@ -2,7 +2,19 @@
 
 .#{$ns}-select-popover {
     .#{$ns}-menu {
-        max-height: unset;
         max-width: unset;
+        max-height: unset;
+    }
+}
+
+.#{$eccgui}-select {
+    display: inline-block;
+
+    &.#{$ns}-fill {
+        display: block;
+    }
+
+    .#{$eccgui}-button {
+        max-width: 100%;
     }
 }

package/src/components/SuggestField/SuggestField.stories.tsx

@@ -0,0 +1,99 @@
+import React from "react";
+import { Meta, StoryFn } from "@storybook/react";
+
+import { highlighterUtils, SuggestField, SuggestFieldProps, suggestFieldUtils } from "../../index";
+
+const SuggestFieldStory: Meta<typeof SuggestField> = {
+    title: "Forms/SuggestField",
+    component: SuggestField,
+    argTypes: {},
+};
+
+const Template: StoryFn<typeof SuggestField> = (args) => <SuggestField {...args}></SuggestField>;
+
+// Renders string values as string
+const defaultRenderer = (item: string) => item;
+
+export const Default = Template.bind({});
+const defaultArgs: SuggestFieldProps<string, string> = {
+    itemRenderer: (item: string) => `Rendered item: ${item}`,
+    itemValueRenderer: (item: string) => `Selected item: ${item}`,
+    itemValueString: (item: string) => `Query: ${item}`,
+    onSearch: (query: string) => {
+        const multiWord = highlighterUtils.extractSearchWords(query, true);
+        return ["search item A", "search element B", "search object C"].filter((word) =>
+            highlighterUtils.matchesAllWords(word.toLowerCase(), multiWord)
+        );
+    },
+    onChange: (elem) => {
+        console.log(`Entry '${elem}' selected!`);
+    },
+    itemValueSelector: defaultRenderer,
+    noResultText: "No result",
+    //fill: false,
+    onlyDropdownWithQuery: true,
+};
+Default.args = defaultArgs;
+
+/**
+ * Display always the dropdown after the element has the focus.
+ * Do not wait until the query input was startet.
+ */
+export const DropdownOnFocus = Template.bind({});
+const dropdownOnFocus: SuggestFieldProps<string, string> = {
+    ...defaultArgs,
+    onlyDropdownWithQuery: false,
+};
+DropdownOnFocus.args = dropdownOnFocus;
+
+/**
+ * Changes the search query for the selected item, e.g. when the rendered item text should be different from the query finding this item.
+ */
+export const AdaptQueryAfterSelection = Template.bind({});
+const adaptQueryAfterSelection: SuggestFieldProps<string, string> = {
+    ...defaultArgs,
+    resetQueryToValue: (selectedValue: string) => selectedValue,
+};
+AdaptQueryAfterSelection.args = adaptQueryAfterSelection;
+
+/**
+ * Allows to reset a selection.
+ */
+export const AllowReset = Template.bind({});
+const resetSelection: SuggestFieldProps<string, string> = {
+    ...defaultArgs,
+    reset: {
+        resetValue: "",
+        resetButtonText: "Clear selected value",
+        resettableValue: (_value: string) => true,
+    },
+};
+AllowReset.args = resetSelection;
+
+export const AllowCustomValues = Template.bind({});
+const allowCustomValues: SuggestFieldProps<string, string> = {
+    ...defaultArgs,
+    createNewItem: {
+        itemRenderer: suggestFieldUtils.createNewItemRendererFactory(
+            (query: string) => `Create new item: ${query}`,
+            "item-add-artefact"
+        ),
+        itemFromQuery: (item) => item,
+    },
+};
+AllowCustomValues.args = allowCustomValues;
+
+/**
+ * Changes the search query for the selected item, e.g. when the rendered item text should be different from the query finding this item.
+ */
+export const ReadOnlyState = Template.bind({});
+const readOnlyState: SuggestFieldProps<string, string> = {
+    ...defaultArgs,
+    initialValue: "search item B",
+    inputProps: {
+        readOnly: true,
+    },
+};
+ReadOnlyState.args = readOnlyState;
+
+export default SuggestFieldStory;

package/src/components/SuggestField/SuggestField.tsx

@@ -0,0 +1,28 @@
+import React from "react";
+
+import { CLASSPREFIX as eccgui } from "../../configuration/constants";
+import { AutoCompleteField, AutoCompleteFieldProps } from "../AutocompleteField/AutoCompleteField";
+
+export type SuggestFieldProps<T, UPDATE_VALUE> = AutoCompleteFieldProps<T, UPDATE_VALUE>;
+
+/**
+ * A component with the appearance of an input field that allows to select and optionally create new items.
+ * It shows suggestions for the entered text from which the user can select any option.
+ * It has the following fixed behavior:
+ *
+ * - When not focused, a different representation of the item value can be shown, e.g. the label of the value.
+ * - When changing an existing item the input text is set to the original value in order to be able to edit the original value.
+ * - When for a specific input text, the only item returns is the currently set item itself, all items are shown below it, to make
+ *   clear that there are still other items to choose from.
+ * - The suggestions are fetched with a short delay, so not too many unnecessary requests are fired.
+ * - Items where itemRenderer returns a string have a default representation, i.e. highlighting of search words, active flag etc.
+ */
+export function SuggestField<T, UPDATE_VALUE>({ className, ...otherProps }: SuggestFieldProps<T, UPDATE_VALUE>) {
+    // Currently this works only as an alias element for `AutoCompleteField`.
+    return (
+        <AutoCompleteField<T, UPDATE_VALUE>
+            className={`${eccgui}-suggestfield` + (className ? ` ${className}` : "")}
+            {...otherProps}
+        />
+    );
+}

package/src/components/SuggestField/index.ts

@@ -0,0 +1,5 @@
+import { createNewItemRendererFactory } from "./../AutocompleteField/autoCompleteFieldUtils";
+export * from "./SuggestField";
+export const suggestFieldUtils = {
+    createNewItemRendererFactory,
+};

package/src/components/TagInput/taginput.scss

@@ -1,7 +1,21 @@
 @import "~@blueprintjs/core/src/components/tag-input/tag-input";
 
 .#{$ns}-tag-input {
+    display: inline-flex;
+
+    &.#{$ns}-input {
+        height: auto;
+        min-height: $eccgui-size-textfield-height-regular;
+        padding-right: ($pt-button-height - $pt-button-height-small) * 0.5;
+    }
+
     .#{$eccgui}-spinner--position-inline {
         height: $pt-button-height-small;
     }
+
+    .#{$eccgui}-button {
+        min-width: $pt-button-height-small;
+        min-height: $pt-button-height-small;
+        margin: ($pt-button-height - $pt-button-height-small) * 0.5 0 0 0;
+    }
 }

package/src/components/index.scss

@@ -26,9 +26,9 @@
 @import "./Structure/titles";
 @import "./Table/table";
 @import "./Tabs/tabs";
-@import "./TagInput/taginput";
 @import "./Tag/tag";
 @import "./TextField/textfield";
+@import "./TagInput/taginput";
 @import "./Toolbar/toolbar";
 @import "./Tooltip/tooltip";
 @import "./Tree/tree";

package/src/components/index.ts

@@ -1,7 +1,9 @@
 export * from "./Accordion";
 export * from "./Application";
 export * from "./AutocompleteField";
+export * from "./SuggestField";
 export * from "./AutoSuggestion";
+export * from "./CodeAutocompleteField";
 export * from "./Badge/Badge";
 export * from "./Breadcrumb";
 export * from "./Button/Button";
@@ -21,6 +23,7 @@ export * from "./Link/Link";
 export * from "./List/List";
 export * from "./Menu";
 export * from "./MultiSelect/MultiSelect";
+export * from "./MultiSuggestField/MultiSuggestField";
 export * from "./Notification";
 export * from "./NumericInput/NumericInput";
 export * from "./OverviewItem";