opus-toolkit-components 1.5.8 → 1.6.0

package/lib/opus-components.main.js

@@ -1222,6 +1222,56 @@ function Text(_ref) {
 
 
 
+/**
+ * @typedef {Object} AccordionProps
+ *
+ * @property {string | React.ReactNode} title
+ *   Title rendered inside the header.
+ *
+ * @property {Function} [handleToggle]
+ *   Optional external toggle handler called with (index).
+ *
+ * @property {number} [activeIndex]
+ *   Controlled active index. If provided, the accordion becomes controlled.
+ *
+ * @property {number} index
+ *   This accordion's position in a list.
+ *
+ * @property {boolean} [isPreview]
+ *   If true, accordion goes into preview mode.
+ *
+ * @property {boolean} [isLocked]
+ *   If true, accordion cannot toggle.
+ *
+ * @property {Function} [onExitPreview]
+ *   Callback fired when exiting preview mode.
+ *
+ * @property {React.ReactNode} content
+ *   Accordion expanded content.
+ *
+ * @property {React.ReactNode} [preview]
+ *   Rendered when in preview mode and not active.
+ *
+ * @property {boolean} [isPill]
+ *   Whether to show a status pill.
+ *
+ * @property {string} [pillText]
+ *   Label inside the pill.
+ *
+ * @property {'success'|'warning'|'error'|'info'|string} [pillStatus]
+ *   Visual status for the pill.
+ *
+ * @property {React.ReactNode} [pillIcon]
+ *   Optional icon inside the pill.
+ *
+ * @property {boolean} [disabled]
+ *   Disables interaction with the accordion.
+ */
+
+/**
+ * @param {AccordionProps} props
+ */
+
 const Accordion = _ref => {
   let {
     title,
@@ -4140,7 +4190,82 @@ function AiTwotoneWarning (props) {
 
  // Import a spinner icon
 
-// test 2 for Husky
+
+/**
+ * @typedef {'primary'|'secondary'|'tertiary'|'outline'|'destructive'} ButtonRank
+ */
+
+/**
+ * @typedef {'default'|'disabled'} ButtonState
+ */
+
+/**
+ * @typedef {'sm'|'md'|'lg'|'xl'|string} ButtonSize
+ *  (Supports custom tailwind text sizes too)
+ */
+
+/**
+ * Icon component type from react-icons or your own components
+ * @typedef {(props: React.SVGProps<SVGSVGElement>) => JSX.Element} IconComponent
+ */
+
+/**
+ * @typedef {Object} ButtonProps
+ *
+ * @property {'button'|'submit'|'reset'} [type]
+ *   Native button type.
+ *
+ * @property {ButtonRank} [rank]
+ *   Visual rank: primary, secondary, etc.
+ *
+ * @property {ButtonState} [state]
+ *   Current state (default, disabled).
+ *
+ * @property {string} [text]
+ *   Text shown inside the button (ignored when isSaving is true).
+ *
+ * @property {ButtonSize} [size]
+ *   Tailwind text size (sm, md, lg, xl).
+ *
+ * @property {string} [name]
+ *   Standard HTML name attribute + for data-cy.
+ *
+ * @property {string} [dataCy]
+ *   Override for auto-generated test selector.
+ *
+ * @property {number} [tabIndex]
+ *
+ * @property {boolean} [isFullWidth]
+ *   Expand to full container width.
+ *
+ * @property {IconComponent} [icon]
+ *   Optional icon component (left or right).
+ *
+ * @property {'left'|'right'} [iconPosition]
+ *   Position of icon.
+ *
+ * @property {boolean} [isIconAnimated]
+ *   Enables subtle translate animation on hover.
+ *
+ * @property {boolean} [isSaving]
+ *   Shows a spinner and disables all interaction.
+ *
+ * @property {string} [savingText]
+ *   Text shown when isSaving = true.
+ *
+ * @property {string} [className]
+ *   Extra custom classes.
+ *
+ * @property {string} [title]
+ *   Adds accessible label / tooltip.
+ *
+ * @property {(event: React.MouseEvent<HTMLButtonElement>) => void} [onClick]
+ *   Click handler. Not called during saving or disabled state.
+ */
+
+/**
+ * @param {ButtonProps & React.ButtonHTMLAttributes<HTMLButtonElement>} props
+ */
 
 function Button(_ref) {
   let {
@@ -4216,24 +4341,49 @@ function clsx_r(e){var t,f,n="";if("string"==typeof e||"number"==typeof e)n+=e;e
 
 
 
+/**
+ * The visual intent / theme of the Card.
+ * @typedef {'default'|'info'|'warning'|'success'|'error'|'brand'|'brandSecondary'} CardIntent
+ */
+
+/**
+ * Props for the Card component.
+ *
+ * @typedef {Object} CardProps
+ * @property {CardIntent} [intent]
+ *   Controls the background + text color theme of the card.
+ *
+ * @property {string} [className]
+ *   Additional custom class names.
+ *
+ * @property {React.ReactNode} [children]
+ *   Card content.
+ */
+
+/**
+ * Card component with typed JSDoc for TS autocomplete.
+ *
+ * @param {CardProps & React.HTMLAttributes<HTMLDivElement>} props
+ */
+
 function Card(_ref) {
   let {
     intent,
-    className = '',
+    className = "",
     children
   } = _ref;
   // Theme override
   const intentClasses = {
-    default: 'bg-[--color-primary-bg] text-[--color-text-weak]',
-    info: 'bg-[--color-util-blue-200] text-[--color-black] border-[--color-util-blue]',
-    warning: 'bg-[--color-util-yellow-200] text-[--color-black] border-[--color-util-yellow]',
-    success: 'bg-[--color-util-green-200] text-[--color-black] border-[--color-util-green]',
-    error: 'bg-[--color-util-red-200] text-[--color-text-black] border-[--color-util-red]',
-    brand: 'bg-[--color-brand-primary] text-[--color-white]',
-    brandSecondary: 'bg-[--color-brand-secondary] text-[--color-white]'
+    default: "bg-[--color-primary-bg] text-[--color-text-weak]",
+    info: "bg-[--color-util-blue-200] text-[--color-black] border-[--color-util-blue]",
+    warning: "bg-[--color-util-yellow-200] text-[--color-black] border-[--color-util-yellow]",
+    success: "bg-[--color-util-green-200] text-[--color-black] border-[--color-util-green]",
+    error: "bg-[--color-util-red-200] text-[--color-text-black] border-[--color-util-red]",
+    brand: "bg-[--color-brand-primary] text-[--color-white]",
+    brandSecondary: "bg-[--color-brand-secondary] text-[--color-white]"
   };
-  const resolvedIntent = intent || 'default';
-  const cardClasses = dist_clsx('p-5', 'rounded-lg', 'shadow-lg', 'border-2 border-solid border-[--color-stroke]', intentClasses[resolvedIntent], className);
+  const resolvedIntent = intent || "default";
+  const cardClasses = dist_clsx("p-5", "rounded-lg", "shadow-lg", "border-2 border-solid border-[--color-stroke]", intentClasses[resolvedIntent], className);
   return /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("div", {
     className: cardClasses,
     children: children
@@ -4249,22 +4399,93 @@ function Input_toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var
 
 
 
+/**
+ * Icon component type — any React component that renders an SVG.
+ * @typedef {(props: React.SVGProps<SVGSVGElement>) => JSX.Element} IconComponent
+ */
+
+/**
+ * Custom component type for supplementary UI below input.
+ * Must be a React component.
+ * @typedef {(props: any) => JSX.Element} CustomComponent
+ */
+
+/**
+ * Input component props.
+ *
+ * @typedef {Object} InputProps
+ *
+ * @property {string} label
+ *   Label displayed above the input.
+ *
+ * @property {string} [placeholder]
+ *
+ * @property {'text'|'email'|'password'|'number'|'search'|'tel'|'url'|'date'|'datetime-local'|'month'|'time'|'week'|string} [type]
+ *   HTML input type.
+ *
+ * @property {string|number} [tabIndex]
+ *
+ * @property {string} [title]
+ *
+ * @property {string} [name]
+ *
+ * @property {boolean} [isValid]
+ *   Whether the field is valid — shows error text if false.
+ *
+ * @property {string} [errorMessage]
+ *
+ * @property {(event: React.ChangeEvent<HTMLInputElement>) => void} [onChange]
+ *   Change handler using your preferred full event signature.
+ *
+ * @property {string} [className]
+ *
+ * @property {string|number} [value]
+ *
+ * @property {IconComponent} [Icon]
+ *
+ * @property {'left'|'right'} [iconPosition]
+ *   Icon placement inside the input.
+ *
+ * @property {boolean} [isAnimated]
+ *   Enables focus animation on the icon.
+ *
+ * @property {boolean} [required]
+ *
+ * @property {boolean} [disabled]
+ *
+ * @property {boolean} [shouldRenderCustomComponent]
+ *
+ * @property {CustomComponent} [customComponent]
+ *
+ * @property {Object<string, any>} [customComponentProps]
+ *
+ * @property {string} [dataCy]
+ *   Override for auto-generated test selector.
+ */
+
+/**
+ * ForwardRef Input component with complete JSDoc typings.
+ *
+ * @param {InputProps & React.InputHTMLAttributes<HTMLInputElement>} props
+ * @param {React.Ref<HTMLInputElement>} ref
+ */
+
 const Input = /*#__PURE__*/(0,external_commonjs_react_commonjs2_react_amd_react_root_React_.forwardRef)((_ref, ref) => {
   let {
     label,
     placeholder,
-    type = 'text',
-    tabIndex = '',
-    title = '',
+    type = "text",
+    tabIndex = "",
+    title = "",
     name,
     isValid = true,
     errorMessage = "".concat(label, " is required"),
     onChange,
-    className = '',
+    className = "",
     value,
     Icon,
     // Icon component
-    iconPosition = 'left',
+    iconPosition = "left",
     // Icon position: left or right
     isAnimated = false,
     // Add animation class when focused
@@ -4280,10 +4501,10 @@ const Input = /*#__PURE__*/(0,external_commonjs_react_commonjs2_react_amd_react_
     // New disabled prop
     dataCy
   } = _ref;
-  const inputClasses = "".concat(className, " flex items-center rounded-md bg-[--color-input-bg] border ").concat(isValid ? 'border-[--color-stroke]' : 'border-utilRed1000', " text-md font-normal text-[--color-text-strong] ").concat(disabled ? 'opacity-50 cursor-not-allowed' : '');
-  const iconClasses = "h-5 w-5 ".concat(isAnimated ? 'transition-transform duration-200 group-focus-within:scale-125' : '', " text-[--color-text-weak]");
+  const inputClasses = "".concat(className, " flex items-center rounded-md bg-[--color-input-bg] border ").concat(isValid ? "border-[--color-stroke]" : "border-utilRed1000", " text-md font-normal text-[--color-text-strong] ").concat(disabled ? "opacity-50 cursor-not-allowed" : "");
+  const iconClasses = "h-5 w-5 ".concat(isAnimated ? "transition-transform duration-200 group-focus-within:scale-125" : "", " text-[--color-text-weak]");
   return /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsxs)("div", {
-    className: "flex flex-col mb-4",
+    className: "mb-4 flex flex-col",
     children: [/*#__PURE__*/(0,jsx_runtime_namespaceObject.jsxs)(Text, {
       as: "label",
       variant: "label",
@@ -4292,20 +4513,20 @@ const Input = /*#__PURE__*/(0,external_commonjs_react_commonjs2_react_amd_react_
       children: [label, required && /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(Text, {
         as: "span",
         variant: "small",
-        className: "text-[--color-util-red] ml-1",
+        className: "ml-1 text-[--color-util-red]",
         children: "*"
       })]
     }), /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsxs)("div", {
       className: "".concat(inputClasses, " relative"),
-      children: [Icon && iconPosition === 'left' && /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("span", {
-        className: "absolute left-3 flex items-center pointer-events-none",
+      children: [Icon && iconPosition === "left" && /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("span", {
+        className: "pointer-events-none absolute left-3 flex items-center",
         children: /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(Icon, {
           className: iconClasses
         })
       }), /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("input", {
         id: name,
         ref: ref,
-        className: "w-full ".concat(Icon ? iconPosition === 'left' ? 'pl-10' : 'pr-10' : '', " bg-[--color-input-bg] border-none focus:ring-0 focus:outline-none rounded-md py-2 px-3"),
+        className: "w-full ".concat(Icon ? iconPosition === "left" ? "pl-10" : "pr-10" : "", " rounded-md border-none bg-[--color-input-bg] px-3 py-2 focus:outline-none focus:ring-0"),
         type: type,
         name: name,
         placeholder: placeholder,
@@ -4321,8 +4542,8 @@ const Input = /*#__PURE__*/(0,external_commonjs_react_commonjs2_react_amd_react_
         }),
         "aria-invalid": !isValid,
         "aria-describedby": !isValid ? "".concat(name, "-error") : undefined
-      }), Icon && iconPosition === 'right' && /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("span", {
-        className: "absolute right-3 flex items-center pointer-events-none",
+      }), Icon && iconPosition === "right" && /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("span", {
+        className: "pointer-events-none absolute right-3 flex items-center",
         children: /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(Icon, {
           className: iconClasses
         })
@@ -22416,11 +22637,12 @@ function SidebarGroup(_ref) {
     }), /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("div", {
       className: "ml-10 mt-1 overflow-hidden transition-all duration-300 ease-in-out ".concat(expanded && open ? "max-h-96 opacity-100" : "max-h-0 opacity-0"),
       children: menu.children.map(child => /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(SidebarItem, {
+        // composite unique key
         menu: child,
         open: open,
         active: activeItem === child.key,
         onClick: () => onItemClick(child.key)
-      }, child.key))
+      }, "child-".concat(child.key, "-").concat(child.path)))
     })]
   });
 }
@@ -22605,17 +22827,19 @@ function Sidebar(_ref) {
         }), /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("div", {
           className: "menu-item-container",
           children: menus.map(menu => menu.children ? /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(SidebarGroup, {
+            // composite key
             menu: menu,
             open: open,
             activeItem: activeItem,
             onItemClick: onItemClick,
             toggleSidebar: setOpen
-          }, menu.key) : /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(SidebarItem, {
+          }, "group-".concat(menu.key, "-").concat(menu.name)) : /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(SidebarItem, {
+            // composite key
             menu: menu,
             open: open,
             active: activeItem === menu.key,
             onClick: () => onItemClick(menu.key)
-          }, menu.key))
+          }, "item-".concat(menu.key, "-").concat(menu.name)))
         })]
       }), /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(SidebarProfile, {
         user: user,