@canonical/react-components 1.7.3 → 1.9.0

package/dist/components/CustomSelect/CustomSelect.d.ts

@@ -0,0 +1,36 @@
+import type { MutableRefObject, ReactNode } from "react";
+import { ClassName, PropsWithSpread } from "../../types";
+import { FieldProps } from "../Field";
+import { Position } from "../ContextualMenu";
+import { CustomSelectOption } from "./CustomSelectDropdown";
+import "./CustomSelect.scss";
+export type SelectRef = MutableRefObject<{
+    open: () => void;
+    close: () => void;
+    isOpen: boolean;
+    focus: () => void;
+} | undefined>;
+export type Props = PropsWithSpread<FieldProps, {
+    value: string;
+    options: CustomSelectOption[];
+    onChange: (value: string) => void;
+    onSearch?: (value: string) => void;
+    id?: string | null;
+    name?: string;
+    disabled?: boolean;
+    wrapperClassName?: ClassName;
+    toggleClassName?: ClassName;
+    dropdownClassName?: string;
+    searchable?: "auto" | "always" | "never";
+    takeFocus?: boolean;
+    header?: ReactNode;
+    selectRef?: SelectRef;
+    initialPosition?: Position;
+}>;
+/**
+ * This is a [React](https://reactjs.org/) component that extends from the Vanilla [Select](https://vanillaframework.io/docs/base/forms#select) element.
+ *
+ * The aim of this component is to provide a select component with customisable options and a dropdown menu, whilst maintaining accessibility and usability.
+ */
+declare const CustomSelect: ({ value, options, onChange, onSearch, id, name, disabled, success, error, help, wrapperClassName, toggleClassName, dropdownClassName, searchable, takeFocus, header, selectRef, initialPosition, ...fieldProps }: Props) => JSX.Element;
+export default CustomSelect;

package/dist/components/CustomSelect/CustomSelect.js

@@ -0,0 +1,145 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _classnames = _interopRequireDefault(require("classnames"));
+var _react = _interopRequireWildcard(require("react"));
+var _Field = _interopRequireDefault(require("../Field"));
+var _ContextualMenu = _interopRequireDefault(require("../ContextualMenu"));
+var _hooks = require("../../hooks");
+var _CustomSelectDropdown = _interopRequireWildcard(require("./CustomSelectDropdown"));
+require("./CustomSelect.scss");
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
+/**
+ * This is a [React](https://reactjs.org/) component that extends from the Vanilla [Select](https://vanillaframework.io/docs/base/forms#select) element.
+ *
+ * The aim of this component is to provide a select component with customisable options and a dropdown menu, whilst maintaining accessibility and usability.
+ */
+const CustomSelect = _ref => {
+  let {
+    value,
+    options,
+    onChange,
+    onSearch,
+    id,
+    name,
+    disabled,
+    success,
+    error,
+    help,
+    wrapperClassName,
+    toggleClassName,
+    dropdownClassName,
+    searchable = "auto",
+    takeFocus,
+    header,
+    selectRef,
+    initialPosition = "left",
+    ...fieldProps
+  } = _ref;
+  const [isOpen, setIsOpen] = (0, _react.useState)(false);
+  const validationId = (0, _react.useId)();
+  const defaultSelectId = (0, _react.useId)();
+  const selectId = id || defaultSelectId;
+  const helpId = (0, _react.useId)();
+  const hasError = !!error;
+
+  // Close the dropdown when the browser tab is hidden
+  const onBrowserTabHidden = () => {
+    if (document.visibilityState === "hidden") {
+      setIsOpen(false);
+    }
+  };
+  (0, _hooks.useListener)(window, onBrowserTabHidden, "visibilitychange");
+
+  // Close the dropdown when the browser window loses focus
+  (0, _hooks.useListener)(window, () => setIsOpen(false), "blur");
+  (0, _react.useImperativeHandle)(selectRef, () => ({
+    open: () => {
+      var _document$getElementB;
+      setIsOpen(true);
+      (_document$getElementB = document.getElementById(selectId)) === null || _document$getElementB === void 0 || _document$getElementB.focus();
+    },
+    focus: () => {
+      var _document$getElementB2;
+      return (_document$getElementB2 = document.getElementById(selectId)) === null || _document$getElementB2 === void 0 ? void 0 : _document$getElementB2.focus();
+    },
+    close: setIsOpen.bind(null, false),
+    isOpen: isOpen
+  }), [isOpen, selectId]);
+  (0, _react.useEffect)(() => {
+    if (takeFocus) {
+      const toggleButton = document.getElementById(selectId);
+      toggleButton === null || toggleButton === void 0 || toggleButton.focus();
+    }
+  }, [takeFocus, selectId]);
+  const selectedOption = options.find(option => option.value === value);
+  const toggleLabel = /*#__PURE__*/_react.default.createElement("span", {
+    className: "toggle-label u-truncate"
+  }, selectedOption ? (0, _CustomSelectDropdown.getOptionText)(selectedOption) : "Select an option");
+  const handleSelect = value => {
+    var _document$getElementB3;
+    (_document$getElementB3 = document.getElementById(selectId)) === null || _document$getElementB3 === void 0 || _document$getElementB3.focus();
+    setIsOpen(false);
+    onChange(value);
+  };
+  return /*#__PURE__*/_react.default.createElement(_Field.default, _extends({}, fieldProps, {
+    className: (0, _classnames.default)("p-custom-select", wrapperClassName),
+    error: error,
+    forId: selectId,
+    help: help,
+    helpId: helpId,
+    isSelect: true,
+    success: success,
+    validationId: validationId
+  }), /*#__PURE__*/_react.default.createElement(_ContextualMenu.default, {
+    "aria-describedby": [help ? helpId : null, success ? validationId : null].filter(Boolean).join(" "),
+    "aria-errormessage": hasError ? validationId : undefined,
+    "aria-invalid": hasError,
+    toggleClassName: (0, _classnames.default)("p-custom-select__toggle", "p-form-validation__input", toggleClassName, {
+      active: isOpen
+    }),
+    toggleLabel: toggleLabel,
+    visible: isOpen,
+    onToggleMenu: open => {
+      // Handle syncing the state when toggling the menu from within the
+      // contextual menu component e.g. when clicking outside.
+      if (open !== isOpen) {
+        setIsOpen(open);
+      }
+    },
+    toggleProps: {
+      id: selectId,
+      disabled: disabled,
+      // tabIndex is set to -1 when disabled to prevent keyboard navigation to the select toggle
+      tabIndex: disabled ? -1 : 0
+    },
+    className: "p-custom-select__wrapper",
+    dropdownClassName: dropdownClassName,
+    style: {
+      width: "100%"
+    },
+    autoAdjust: true,
+    position: initialPosition
+  }, close => /*#__PURE__*/_react.default.createElement(_CustomSelectDropdown.default, {
+    searchable: searchable,
+    onSearch: onSearch,
+    name: name || "",
+    options: options || [],
+    onSelect: handleSelect,
+    onClose: () => {
+      var _document$getElementB4;
+      // When pressing ESC to close the dropdown, we keep focus on the toggle button
+      close();
+      (_document$getElementB4 = document.getElementById(selectId)) === null || _document$getElementB4 === void 0 || _document$getElementB4.focus();
+    },
+    header: header,
+    toggleId: selectId
+  })));
+};
+var _default = exports.default = CustomSelect;

package/dist/components/CustomSelect/CustomSelect.scss

@@ -0,0 +1,82 @@
+@use "sass:map";
+@import "vanilla-framework";
+@include vf-b-placeholders; // Vanilla base placeholders to extend from
+
+.p-custom-select {
+  @include vf-b-forms;
+
+  // style copied directly from vanilla-framework for the select element
+  .p-custom-select__toggle {
+    @include vf-icon-chevron-themed;
+    @extend %vf-input-elements;
+
+    // stylelint-disable property-no-vendor-prefix
+    -moz-appearance: none;
+    -webkit-appearance: none;
+    appearance: none;
+    // stylelint-enable property-no-vendor-prefix
+    background-position: right calc(map-get($grid-margin-widths, default) / 2)
+      center;
+    background-repeat: no-repeat;
+    background-size: map-get($icon-sizes, default);
+    border-top: none;
+    box-shadow: none;
+    min-height: map-get($line-heights, default-text);
+    padding-right: calc($default-icon-size + 2 * $sph--small);
+    text-indent: 0.01px;
+
+    &:hover {
+      cursor: pointer;
+    }
+
+    // this emulates the highlight effect when the select is focused
+    // without crowding the content with a border
+    &.active,
+    &:focus {
+      box-shadow: inset 0 0 0 3px $color-focus;
+    }
+
+    .toggle-label {
+      display: flow-root;
+      text-align: left;
+      width: 100%;
+    }
+  }
+}
+
+.p-custom-select__dropdown {
+  background-color: $colors--theme--background-alt;
+  box-shadow: $box-shadow--deep;
+  outline: none;
+  position: relative;
+
+  .p-custom-select__option {
+    background-color: $colors--theme--background-alt;
+    font-weight: $font-weight-regular-text;
+    padding: $sph--x-small $sph--small;
+
+    &.highlight {
+      // browser default styling for options when hovered
+      background-color: #06c;
+      cursor: pointer;
+
+      // make sure that if an option is highlighted, its text is white for good contrast
+      * {
+        color: white;
+      }
+    }
+  }
+
+  .p-custom-select__search {
+    background-color: $colors--theme--background-alt;
+    padding: $sph--x-small;
+    padding-bottom: $sph--small;
+    position: sticky;
+    top: 0;
+  }
+
+  .p-list {
+    max-height: 30rem;
+    overflow: auto;
+  }
+}

package/dist/components/CustomSelect/CustomSelect.stories.d.ts

@@ -0,0 +1,28 @@
+import { Meta, StoryObj } from "@storybook/react/*";
+import CustomSelect from "./CustomSelect";
+import { ComponentProps } from "react";
+type StoryProps = ComponentProps<typeof CustomSelect>;
+declare const meta: Meta<StoryProps>;
+export default meta;
+type Story = StoryObj<StoryProps>;
+/**
+ * If `label` is of `string` type. You do not have to do anything extra to render it.
+ */
+export declare const StandardOptions: Story;
+/**
+ * If `label` is of `ReactNode` type. You can render custom content.
+ * In this case, the `text` property for each option is required and is used for display in the toggle, search and sort functionalities.
+ */
+export declare const CustomOptions: Story;
+/**
+ * For each option, if `disabled` is set to `true`, the option will be disabled.
+ */
+export declare const DisabledOptions: Story;
+/**
+ * Search is enabled by default when there are 5 or more options.
+ */
+export declare const AutoSearchable: Story;
+/**
+ * Search can be enabled manually by setting `searchable` to `always`.
+ */
+export declare const ManualSearchable: Story;

package/dist/components/CustomSelect/CustomSelect.stories.js

@@ -0,0 +1,132 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.StandardOptions = exports.ManualSearchable = exports.DisabledOptions = exports.CustomOptions = exports.AutoSearchable = void 0;
+var _CustomSelect = _interopRequireDefault(require("./CustomSelect"));
+var _react = _interopRequireWildcard(require("react"));
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
+const generateStandardOptions = num => Array(num).fill(null).map((_, i) => ({
+  value: "option-".concat(i + 1),
+  label: "Option ".concat(i + 1),
+  text: "Option ".concat(i + 1),
+  disabled: false
+}));
+const generateCustomOptions = () => {
+  return [{
+    value: "smile",
+    label: /*#__PURE__*/_react.default.createElement("div", null, "\uD83D\uDE00"),
+    text: "Smile",
+    disabled: false
+  }, {
+    value: "grin",
+    label: /*#__PURE__*/_react.default.createElement("div", null, "\uD83D\uDE01"),
+    text: "Grin",
+    disabled: false
+  }, {
+    value: "cry",
+    label: /*#__PURE__*/_react.default.createElement("div", null, "\uD83D\uDE2D"),
+    text: "Cry",
+    disabled: false
+  }, {
+    value: "angry",
+    label: /*#__PURE__*/_react.default.createElement("div", null, "\uD83D\uDE21"),
+    text: "Angry",
+    disabled: false
+  }, {
+    value: "sad",
+    label: /*#__PURE__*/_react.default.createElement("div", null, "\uD83D\uDE22"),
+    text: "Sad",
+    disabled: false
+  }];
+};
+const Template = _ref => {
+  let {
+    ...props
+  } = _ref;
+  const [selected, setSelected] = (0, _react.useState)(props.value || "");
+  return /*#__PURE__*/_react.default.createElement(_CustomSelect.default, _extends({}, props, {
+    value: selected,
+    onChange: value => setSelected(value)
+  }));
+};
+const meta = {
+  component: _CustomSelect.default,
+  render: Template,
+  tags: ["autodocs"],
+  args: {
+    name: "customSelect",
+    label: "Custom Select",
+    searchable: "auto",
+    initialPosition: "left"
+  },
+  argTypes: {
+    searchable: {
+      options: ["auto", "always", "never"],
+      control: {
+        type: "select"
+      }
+    },
+    initialPosition: {
+      options: ["left", "right"],
+      control: {
+        type: "select"
+      }
+    }
+  }
+};
+var _default = exports.default = meta;
+/**
+ * If `label` is of `string` type. You do not have to do anything extra to render it.
+ */
+const StandardOptions = exports.StandardOptions = {
+  args: {
+    options: generateStandardOptions(10)
+  }
+};
+
+/**
+ * If `label` is of `ReactNode` type. You can render custom content.
+ * In this case, the `text` property for each option is required and is used for display in the toggle, search and sort functionalities.
+ */
+const CustomOptions = exports.CustomOptions = {
+  args: {
+    options: generateCustomOptions()
+  }
+};
+
+/**
+ * For each option, if `disabled` is set to `true`, the option will be disabled.
+ */
+const DisabledOptions = exports.DisabledOptions = {
+  args: {
+    options: generateStandardOptions(5).map((option, i) => ({
+      ...option,
+      disabled: i % 2 === 0
+    }))
+  }
+};
+
+/**
+ * Search is enabled by default when there are 5 or more options.
+ */
+const AutoSearchable = exports.AutoSearchable = {
+  args: {
+    options: generateStandardOptions(5),
+    searchable: "auto"
+  }
+};
+
+/**
+ * Search can be enabled manually by setting `searchable` to `always`.
+ */
+const ManualSearchable = exports.ManualSearchable = {
+  args: {
+    options: generateStandardOptions(4),
+    searchable: "always"
+  }
+};

package/dist/components/CustomSelect/CustomSelect.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/CustomSelect/CustomSelectDropdown/CustomSelectDropdown.d.ts

@@ -0,0 +1,25 @@
+import { FC, LiHTMLAttributes, ReactNode } from "react";
+export type CustomSelectOption = LiHTMLAttributes<HTMLLIElement> & {
+    value: string;
+    label: ReactNode;
+    text?: string;
+    disabled?: boolean;
+};
+export type Props = {
+    searchable?: "auto" | "always" | "never";
+    name: string;
+    options: CustomSelectOption[];
+    onSelect: (value: string) => void;
+    onSearch?: (value: string) => void;
+    onClose: () => void;
+    header?: ReactNode;
+    toggleId: string;
+};
+export declare const adjustDropdownHeightBelow: (dropdown: HTMLUListElement) => void;
+export declare const adjustDropdownHeightAbove: (dropdown: HTMLUListElement, search: HTMLInputElement | null) => void;
+export declare const dropdownIsAbove: (dropdown: HTMLUListElement) => boolean;
+export declare const adjustDropdownHeight: (dropdown: HTMLUListElement | null, search: HTMLInputElement | null) => void;
+export declare const getNearestParentsZIndex: (element: HTMLElement | null) => string;
+export declare const getOptionText: (option: CustomSelectOption) => string;
+declare const CustomSelectDropdown: FC<Props>;
+export default CustomSelectDropdown;