opus-toolkit-components 1.5.9 → 1.6.1

package/lib/opus-components.main.js

@@ -1122,26 +1122,58 @@ const jsx_runtime_namespaceObject = require("react/jsx-runtime");
 
 
 const statusClasses = {
-  primary: 'bg-[--color-primary-btn] text-[--color-white]',
-  danger: 'bg-[--color-util-red] text-[--color-white]',
-  warning: 'bg-[--color-util-amber] text-[--color-white]',
-  success: 'bg-[--color-util-green] text-[--color-white]',
-  info: 'bg-[--color-util-blue] text-[--color-white]',
-  notice: 'bg-[--color-util-yellow] text-[--color-black]'
+  primary: "bg-[--color-primary-btn] text-[--color-white]",
+  danger: "bg-[--color-util-red] text-[--color-white]",
+  warning: "bg-[--color-util-amber] text-[--color-white]",
+  success: "bg-[--color-util-green] text-[--color-white]",
+  info: "bg-[--color-util-blue] text-[--color-white]",
+  notice: "bg-[--color-util-yellow] text-[--color-black]"
 };
+
+/**
+ * Allowed pill status values.
+ * @typedef {'primary'|'danger'|'warning'|'success'|'info'|'notice'} PillStatus
+ */
+
+/**
+ * Icon component type — any valid SVG React component.
+ * @typedef {(props: React.SVGProps<SVGSVGElement>) => JSX.Element} IconComponent
+ */
+
+/**
+ * Props for the Pill component.
+ *
+ * @typedef {Object} PillProps
+ * @property {string} [text='']
+ *   Text displayed inside the pill.
+ *
+ * @property {PillStatus} [status='info']
+ *   Determines visual colors of the pill.
+ *
+ * @property {string} [className]
+ *   Additional class names.
+ *
+ * @property {IconComponent} [icon]
+ *   Optional icon displayed before the text.
+ */
+
+/**
+ * @param {PillProps & React.HTMLAttributes<HTMLSpanElement>} props
+ */
+
 const Pill = _ref => {
   let {
-    text = '',
-    status = 'info',
-    className = '',
+    text = "",
+    status = "info",
+    className = "",
     icon: Icon
   } = _ref;
-  const baseClasses = 'inline-flex items-center gap-1 text-xs font-medium px-3 py-1 rounded-full';
+  const baseClasses = "inline-flex items-center gap-1 text-xs font-medium px-3 py-1 rounded-full";
   const statusClass = statusClasses[status] || statusClasses.info;
   return /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsxs)("span", {
     className: "".concat(baseClasses, " ").concat(statusClass, " ").concat(className),
     children: [Icon && /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(Icon, {
-      className: "w-4 h-4"
+      className: "h-4 w-4"
     }), text]
   });
 };
@@ -1193,6 +1225,50 @@ const elementMap = {
   caption: "span",
   label: "label"
 };
+
+/**
+ * Allowed typographical variants for the Text component.
+ * @typedef {'h1'|'h2'|'h3'|'h4'|'h5'|'h6'|'body'|'small'|'caption'|'label'} TextVariant
+ */
+
+/**
+ * Polymorphic HTML element types supported in `as`.
+ * @typedef {keyof JSX.IntrinsicElements | React.ComponentType<any>} TextAs
+ */
+
+/**
+ * Props for the Text component.
+ *
+ * @typedef {Object} TextProps
+ *
+ * @property {TextVariant} [variant='body']
+ *   Controls the typography style.
+ *
+ * @property {TextAs} [as]
+ *   Optional override for the underlying HTML element.
+ *
+ * @property {string} [className]
+ *   Extra CSS classes.
+ *
+ * @property {string} [color='text-[--color-text-strong]']
+ *   Tailwind/text color classes.
+ *
+ * @property {React.ReactNode} [children]
+ *   Text content.
+ *
+ * @property {string} [name]
+ *   Name used to generate `data-cy`.
+ *
+ * @property {string} [dataCy]
+ *   Optional override for auto-generated data-cy attribute.
+ */
+
+/**
+ * Text component with typography variants and polymorphic rendering.
+ *
+ * @param {TextProps & React.HTMLAttributes<HTMLElement>} props
+ */
+
 function Text(_ref) {
   let {
       variant = "body",
@@ -1222,6 +1298,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 +4266,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 +4417,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 +4475,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 +4577,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 +4589,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 +4618,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
         })
@@ -4400,33 +4697,79 @@ var datepicker_update = injectStylesIntoStyleTag_default()(datepicker/* default
 
 
 
+/**
+ * Custom change event type used by your date components.
+ * @typedef {{ target: { name: string, value: string } }} DatePickerChangeEvent
+ */
+
+/**
+ * Props for DatePicker.
+ *
+ * @typedef {Object} DatePickerProps
+ *
+ * @property {string} [initialDate]
+ *   Initial date value (ISO or human-readable). Converted internally.
+ *
+ * @property {string} [label]
+ *   Label above the input.
+ *
+ * @property {boolean} [isValid]
+ *   Controls validation styles + error message display.
+ *
+ * @property {string} [errorMessage]
+ *   Message shown when isValid = false.
+ *
+ * @property {string} [name]
+ *   Input field name and event target name.
+ *
+ * @property {(event: DatePickerChangeEvent) => void} [onChange]
+ *   Custom event format with `event.target.name` & `event.target.value` in ISO.
+ *
+ * @property {string} [value]
+ *   External controlled value (ISO or slash-format). Normalized automatically.
+ *
+ * @property {string} [className]
+ *
+ * @property {string} [title]
+ *
+ * @property {boolean} [required]
+ *
+ * @property {string} [dataCy]
+ *
+ * @property {boolean} [disabled]
+ */
+
+/**
+ * @param {DatePickerProps & React.HTMLAttributes<HTMLDivElement>} props
+ */
+
 function DatePicker(_ref) {
   let {
-    initialDate = '',
-    label = 'Select a Date:',
+    initialDate = "",
+    label = "Select a Date:",
     isValid = true,
-    errorMessage = 'Error message',
-    name = 'date',
+    errorMessage = "Error message",
+    name = "date",
     onChange,
     value,
-    className = '',
-    title = '',
+    className = "",
+    title = "",
     required = false,
     dataCy,
     disabled = false
   } = _ref;
-  const [selectedDate, setSelectedDate] = (0,external_commonjs_react_commonjs2_react_amd_react_root_React_.useState)('');
+  const [selectedDate, setSelectedDate] = (0,external_commonjs_react_commonjs2_react_amd_react_root_React_.useState)("");
   const inputRef = (0,external_commonjs_react_commonjs2_react_amd_react_root_React_.useRef)(null);
   const normalizeToInputFormat = dateString => {
-    if (!dateString) return '';
-    const [datePart] = dateString.split(' '); // Remove time if present
+    if (!dateString) return "";
+    const [datePart] = dateString.split(" "); // Remove time if present
 
     if (/^\d{4}-\d{2}-\d{2}$/.test(datePart)) {
       return datePart; // Already ISO format
     }
-    const parts = datePart.split('/');
-    if (parts.length !== 3) return '';
-    const [part1, part2, part3] = parts.map(p => p.padStart(2, '0'));
+    const parts = datePart.split("/");
+    if (parts.length !== 3) return "";
+    const [part1, part2, part3] = parts.map(p => p.padStart(2, "0"));
     if (parseInt(part1, 10) > 12) {
       // Assume dd/MM/yyyy
       const [day, month, year] = [part1, part2, part3];
@@ -4461,14 +4804,14 @@ function DatePicker(_ref) {
     }
   };
   return /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsxs)("div", {
-    className: "relative flex flex-col mb-4",
+    className: "relative mb-4 flex flex-col",
     children: [/*#__PURE__*/(0,jsx_runtime_namespaceObject.jsxs)(Text, {
       as: "label",
       variant: "label",
       htmlFor: name,
       className: "mb-1",
       children: [label, required && /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("span", {
-        className: "text-[--color-util-red] ml-1",
+        className: "ml-1 text-[--color-util-red]",
         children: "*"
       })]
     }), /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("input", {
@@ -4487,15 +4830,15 @@ function DatePicker(_ref) {
       }),
       "aria-invalid": !isValid,
       "aria-describedby": !isValid ? "".concat(name, "-error") : undefined,
-      className: "w-full py-2 px-3 pr-10 rounded-md bg-[--color-input-bg] border ".concat(isValid ? 'border-[--color-stroke]' : 'border-[--color-util-red]', " text-md font-normal text-[--color-text-strong] ").concat(disabled ? 'opacity-50 cursor-not-allowed' : '', " ").concat(className)
+      className: "w-full rounded-md border bg-[--color-input-bg] px-3 py-2 pr-10 ".concat(isValid ? "border-[--color-stroke]" : "border-[--color-util-red]", " text-md font-normal text-[--color-text-strong] ").concat(disabled ? "cursor-not-allowed opacity-50" : "", " ").concat(className)
     }), /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("button", {
       type: "button",
       onClick: handleIconClick,
-      className: "absolute top-1/2 mt-1 right-3 transform datepicker-icon-button",
+      className: "datepicker-icon-button absolute right-3 top-1/2 mt-1 transform",
       "aria-label": "Open date picker",
       disabled: disabled,
       children: /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(esm_CalendarIcon, {
-        className: "w-5 h-5 ".concat(disabled ? 'text-[--color-text-disabled]' : 'text-[--color-text-weak] hover:text-[--color-primary-btn-hover]', " transition")
+        className: "h-5 w-5 ".concat(disabled ? "text-[--color-text-disabled]" : "text-[--color-text-weak] hover:text-[--color-primary-btn-hover]", " transition")
       })
     }), !isValid && /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(Text, {
       as: "span",
@@ -4511,6 +4854,60 @@ function DatePicker(_ref) {
 
 
 
+/**
+ * A single radio option.
+ * @typedef {Object} RadioOption
+ * @property {string|number} value
+ * @property {string} label
+ */
+
+/**
+ * Custom event format used by your form components.
+ * @typedef {{ target: { name: string, value: string|number } }} RadioChangeEvent
+ */
+
+/**
+ * Props for the RadioButton component.
+ *
+ * @typedef {Object} RadioButtonProps
+ *
+ * @property {string} label
+ *   Form label above the radio group.
+ *
+ * @property {RadioOption[]} [options]
+ *   Array of selectable radio items.
+ *
+ * @property {string} name
+ *   Name of the radio group (required for grouping).
+ *
+ * @property {string|number} [value]
+ *   Currently selected value.
+ *
+ * @property {(event: RadioChangeEvent) => void} [onChange]
+ *   Custom event handler following your design system.
+ *
+ * @property {string} [className]
+ *
+ * @property {string|number} [tabIndex]
+ *
+ * @property {string} [title]
+ *
+ * @property {boolean} [isValid]
+ *   Controls error message + styles.
+ *
+ * @property {string} [errorMessage]
+ *
+ * @property {boolean} [required]
+ *
+ * @property {string} [dataCy]
+ *
+ * @property {boolean} [disabled]
+ */
+
+/**
+ * @param {RadioButtonProps & React.HTMLAttributes<HTMLDivElement>} props
+ */
+
 const RadioButton = _ref => {
   let {
     label,
@@ -4605,6 +5002,49 @@ RadioButton.displayName = "RadioButton";
 
 
 
+/**
+ * Custom change event format used across your form components.
+ * Matches your Input / Dropdown / DatePicker pattern.
+ *
+ * @typedef {{ target: { name: string, value: boolean } }} CheckboxChangeEvent
+ */
+
+/**
+ * Props for Checkbox.
+ *
+ * @typedef {Object} CheckboxProps
+ *
+ * @property {string} label
+ *   Label displayed next to the checkbox.
+ *
+ * @property {string} name
+ *   Name used in the emitted onChange event.
+ *
+ * @property {(event: CheckboxChangeEvent) => void} [onChange]
+ *   Receives `{ target: { name, value } }`.
+ *
+ * @property {boolean} [value]
+ *   Whether the checkbox is checked.
+ *
+ * @property {boolean} [isValid]
+ *   Controls error styling.
+ *
+ * @property {string} [errorMessage]
+ *   Error text shown below the checkbox.
+ *
+ * @property {boolean} [disabled]
+ *   Prevents user interaction.
+ *
+ * @property {string} [title]
+ *
+ * @property {string} [dataCy]
+ *   Override test selector.
+ */
+
+/**
+ * @param {CheckboxProps & React.HTMLAttributes<HTMLDivElement>} props
+ */
+
 function Checkbox(_ref) {
   let {
     label,
@@ -4612,7 +5052,7 @@ function Checkbox(_ref) {
     onChange,
     value = false,
     isValid = true,
-    errorMessage = '',
+    errorMessage = "",
     disabled = false,
     title,
     dataCy
@@ -4621,7 +5061,7 @@ function Checkbox(_ref) {
   const errorId = "".concat(id, "-error");
   const showError = !isValid && errorMessage;
   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)("div", {
       className: "flex items-center",
       children: [/*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("input", {
@@ -4640,9 +5080,9 @@ function Checkbox(_ref) {
         "aria-describedby": showError ? errorId : undefined,
         "aria-disabled": disabled,
         style: {
-          accentColor: 'var(--color-primary-btn)'
+          accentColor: "var(--color-primary-btn)"
         },
-        className: "\n            mr-2 \n            rounded-sm\n            ".concat(disabled ? 'opacity-50 cursor-not-allowed' : 'cursor-pointer')
+        className: "mr-2 rounded-sm ".concat(disabled ? "cursor-not-allowed opacity-50" : "cursor-pointer")
       }), /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(Text, {
         variant: "label",
         as: "label",
@@ -4653,7 +5093,7 @@ function Checkbox(_ref) {
       id: errorId,
       variant: "small",
       as: "span",
-      className: "text-[--color-util-red] mt-1",
+      className: "mt-1 text-[--color-util-red]",
       children: errorMessage
     })]
   });
@@ -4691,37 +5131,87 @@ var table_update = injectStylesIntoStyleTag_default()(table/* default */.A, tabl
 
 
 
+/**
+ * A column definition for the table.
+ *
+ * @typedef {Object} TableColumn
+ * @property {string} key
+ *   The key used to read the row value.
+ *
+ * @property {string} header
+ *   The column header text.
+ *
+ * @property {(row: any) => React.ReactNode} [render]
+ *   Optional custom renderer for this column.
+ */
+
+/**
+ * Props for the Table component.
+ *
+ * @typedef {Object} TableProps
+ *
+ * @property {TableColumn[]} [data=[]]
+ *   Array of column definitions.
+ *
+ * @property {any[]} [rows=[]]
+ *   Array of row objects. Row shape is flexible.
+ *
+ * @property {string} [className='']
+ *   Extra classes for the outer wrapper.
+ *
+ * @property {string} [rowClassName='']
+ *   Classes applied to each table row.
+ *
+ * @property {string} [cellClassName='']
+ *   Classes applied to each table cell.
+ *
+ * @property {string} [headRowClassName='']
+ *   Classes for the `<thead>` row.
+ *
+ * @property {string} [headCellClassName='']
+ *   Classes for header `<th>` cells.
+ *
+ * @property {(row: any, index: number) => string|number} [rowKeyExtractor]
+ *   Extractor for row key (defaults to index).
+ */
+
+/**
+ * Responsive Table with JSDoc types.
+ *
+ * @param {TableProps & React.HTMLAttributes<HTMLDivElement>} props
+ */
+
 function Table(_ref) {
   let {
     data = [],
     rows = [],
-    className = '',
-    rowClassName = '',
-    cellClassName = '',
-    headRowClassName = '',
-    headCellClassName = '',
+    className = "",
+    rowClassName = "",
+    cellClassName = "",
+    headRowClassName = "",
+    headCellClassName = "",
     rowKeyExtractor = (row, index) => index
   } = _ref;
   return /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("div", {
     className: "wrapper w-full ".concat(className),
     children: /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsxs)("table", {
-      className: "\r min-w-full \r table-auto \r text-left \r border-collapse \r table",
+      className: "table min-w-full table-auto border-collapse text-left",
       children: [/*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("thead", {
         className: "hidden sm:table-header-group",
         children: /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("tr", {
           className: "bg-[--color-table-head-bg] ".concat(headRowClassName),
           children: data.map(column => /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("th", {
-            className: "\n                  border-b border-[--color-stroke] \n                  py-2 px-4 \n                  text-sm font-normal text-[--color-table-head-txt] ".concat(headCellClassName),
+            className: "border-b border-[--color-stroke] px-4 py-2 text-sm font-normal text-[--color-table-head-txt] ".concat(headCellClassName),
             children: column.header
           }, column.key))
         })
       }), /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("tbody", {
         children: rows.map((row, index) => {
-          const backgroundClass = index % 2 === 0 ? 'bg-[--color-table-row-bg-even]' : 'bg-[--color-table-row-bg-odd]';
+          const backgroundClass = index % 2 === 0 ? "bg-[--color-table-row-bg-even]" : "bg-[--color-table-row-bg-odd]";
           return /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("tr", {
-            className: "block \n                  sm:table-row \n                  mb-4 sm:mb-0 \n                  rounded-lg sm:rounded-none \n                  border sm:border-0 border-[--color-stroke] \n                  p-4 sm:p-0 \n                  shadow-sm sm:shadow-none \n                  hover:bg-[--color-table-row-bg-hover] ".concat(backgroundClass, " ").concat(rowClassName),
+            className: "mb-4 block rounded-lg border border-[--color-stroke] p-4 shadow-sm hover:bg-[--color-table-row-bg-hover] sm:mb-0 sm:table-row sm:rounded-none sm:border-0 sm:p-0 sm:shadow-none ".concat(backgroundClass, " ").concat(rowClassName),
             children: data.map(column => /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("td", {
-              className: "\n                      block sm:table-cell \n                      lg:px-4 lg:py-2 \n                      text-sm text-[--color-text-weak] ".concat(cellClassName),
+              className: "block text-sm text-[--color-text-weak] sm:table-cell lg:px-4 lg:py-2 ".concat(cellClassName),
               "data-label": column.header,
               children: column.render ? column.render(row) : row[column.key]
             }, column.key))
@@ -13279,21 +13769,83 @@ const esm_ChevronDownIcon_ForwardRef = /*#__PURE__*/ external_commonjs_react_com
 
 
 
+/**
+ * @typedef {Object} DropdownItem
+ * @property {string} label
+ * @property {string|number} value
+ */
+
+/**
+ * Icon component type — any React SVG component.
+ * @typedef {(props: React.SVGProps<SVGSVGElement>) => JSX.Element} IconComponent
+ */
+
+/**
+ * Custom event type emitted by your onChange (matching your pattern).
+ * @typedef {{ target: { name: string, value: string|number } }} DropdownChangeEvent
+ */
+
+/**
+ * @typedef {Object} DropdownProps
+ *
+ * @property {DropdownItem[]} [items]
+ *   Array of dropdown options.
+ *
+ * @property {string} [label]
+ *   Label above the dropdown.
+ *
+ * @property {boolean} [isValid]
+ *   Whether the field is valid.
+ *
+ * @property {boolean} [required]
+ *   Whether a * is appended.
+ *
+ * @property {string} [placeholder]
+ *
+ * @property {string} [name]
+ *
+ * @property {string} [className]
+ *
+ * @property {string} [title]
+ *
+ * @property {string|number} [tabIndex]
+ *
+ * @property {(event: DropdownChangeEvent) => void} [onChange]
+ *   Uses your preferred event signature: `event.target.name` / `event.target.value`.
+ *
+ * @property {string|number} [value]
+ *   Selected item value.
+ *
+ * @property {IconComponent} [Icon]
+ *   Optional decorative icon.
+ *
+ * @property {string} [errorMessage]
+ *
+ * @property {boolean} [disabled]
+ *
+ * @property {string} [dataCy]
+ *   Override for auto-generated data-cy attribute.
+ */
+
+/**
+ * @param {DropdownProps & React.HTMLAttributes<HTMLDivElement>} props
+ */
+
 function Dropdown(_ref) {
   let {
     items = [],
-    label = 'Test Label',
+    label = "Test Label",
     isValid = true,
     required = false,
-    placeholder = 'Example Placeholder',
+    placeholder = "Example Placeholder",
     name,
-    className = '',
-    title = '',
-    tabIndex = '',
+    className = "",
+    title = "",
+    tabIndex = "",
     onChange,
     value,
     Icon,
-    errorMessage = 'This field is required',
+    errorMessage = "This field is required",
     disabled = false,
     dataCy
   } = _ref;
@@ -13302,7 +13854,7 @@ function Dropdown(_ref) {
     const newSelectedItem = items.find(item => item.value === value) || null;
     setSelectedItem(newSelectedItem);
   }, [value, items]);
-  const inputClasses = "inline-flex w-full justify-between items-center rounded-md bg-[--color-input-bg] text-md font-normal border p-2 text-[--color-text-strong] ".concat(isValid ? 'border-[--color-stroke]' : 'border-utilRed1000', " ").concat(disabled ? 'opacity-50 cursor-not-allowed' : '');
+  const inputClasses = "inline-flex w-full justify-between items-center rounded-md bg-[--color-input-bg] text-md font-normal border p-2 text-[--color-text-strong] ".concat(isValid ? "border-[--color-stroke]" : "border-utilRed1000", " ").concat(disabled ? "opacity-50 cursor-not-allowed" : "");
   const handleSelect = item => {
     if (disabled) return;
     setSelectedItem(item);
@@ -13315,7 +13867,7 @@ function Dropdown(_ref) {
     onChange === null || onChange === void 0 || onChange(event);
   };
   return /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsxs)("div", {
-    className: "flex flex-col mb-4 ".concat(className),
+    className: "mb-4 flex flex-col ".concat(className),
     children: [/*#__PURE__*/(0,jsx_runtime_namespaceObject.jsxs)(Text, {
       as: "label",
       variant: "label",
@@ -13354,10 +13906,10 @@ function Dropdown(_ref) {
               })]
             }), /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(solid_esm_ChevronDownIcon, {
               "aria-hidden": "true",
-              className: "ml-3 mr-1 h-5 w-5 text-[--color-text-strong] bg-transparent transition-transform duration-200 ".concat(open ? 'rotate-180' : 'rotate-0')
+              className: "ml-3 mr-1 h-5 w-5 bg-transparent text-[--color-text-strong] transition-transform duration-200 ".concat(open ? "rotate-180" : "rotate-0")
             })]
           }), !disabled && /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(yt, {
-            className: "\r absolute \r left-0 \r z-10 \r mt-2 \r w-[100%] \r origin-top-right \r rounded-md \r bg-[--color-primary-bg] \r shadow-lg \r ring-1 \r ring-[--color-stroke] \r ring-opacity-1 \r focus:outline-none \r max-h-48 \r overflow-y-auto\r ",
+            className: "ring-opacity-1 absolute left-0 z-10 mt-2 max-h-48 w-[100%] origin-top-right overflow-y-auto rounded-md bg-[--color-primary-bg] shadow-lg ring-1 ring-[--color-stroke] focus:outline-none",
             children: /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("div", {
               className: "py-1",
               children: items.map((item, index) => /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(gt, {
@@ -13368,7 +13920,7 @@ function Dropdown(_ref) {
                   return /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)("button", {
                     type: "button",
                     onClick: () => handleSelect(item),
-                    className: "block w-full px-4 py-2 text-left text-sm text-[--color-text-strong] ".concat(active ? 'bg-[--color-input-bg]' : ''),
+                    className: "block w-full px-4 py-2 text-left text-sm text-[--color-text-strong] ".concat(active ? "bg-[--color-input-bg]" : ""),
                     children: item.label
                   });
                 }
@@ -13381,7 +13933,7 @@ function Dropdown(_ref) {
       as: "span",
       variant: "small",
       id: "".concat(name, "-error"),
-      className: "text-[--color-util-red] mt-1",
+      className: "mt-1 text-[--color-util-red]",
       children: errorMessage
     })]
   });
@@ -13429,6 +13981,30 @@ var c247_icon_only_2x_png_default = /*#__PURE__*/__webpack_require__.n(c247_icon
 
 
 
+/**
+ * Props for the Navbar component.
+ *
+ * @typedef {Object} NavbarProps
+ *
+ * @property {React.ReactNode} [children]
+ *   Content displayed on the right side of the navbar.
+ *
+ * @property {string} [logo]
+ *   Custom logo URL. Defaults to toolkit logos.
+ *
+ * @property {string} [className]
+ *   Extra class names for the navbar wrapper.
+ *
+ * @property {string} [maxWidth="1200px"]
+ *   Max width of the inner content container.
+ */
+
+/**
+ * Responsive Navbar with optional custom logo and region for child content.
+ *
+ * @param {NavbarProps & React.HTMLAttributes<HTMLElement>} props
+ */
+
 const Navbar = _ref => {
   let {
     children,
@@ -13468,12 +14044,36 @@ var c247_loader_gif_default = /*#__PURE__*/__webpack_require__.n(c247_loader_gif
 // In production, it's better to let the parent control rendering to keep Loader focused on UI.
 // This change would improve testability, flexibility, and follow React best practices.
 
+/**
+ * Props for the Loader component.
+ *
+ * @typedef {Object} LoaderProps
+ *
+ * @property {boolean} isLoading
+ *   Determines whether the loader is visible.
+ *
+ * @property {string} [loaderText='loading...']
+ *   Optional text displayed beneath the spinner.
+ *
+ * @property {React.ReactNode} [customLoader]
+ *   Custom loader element (replaces default GIF).
+ *
+ * @property {string} [className]
+ *   Extra class names applied to the outer container.
+ */
+
+/**
+ * Loader overlay that covers the entire screen.
+ *
+ * @param {LoaderProps & React.HTMLAttributes<HTMLDivElement>} props
+ */
+
 function Loader(_ref) {
   let {
     isLoading,
-    loaderText = 'loading...',
+    loaderText = "loading...",
     customLoader,
-    className = ''
+    className = ""
   } = _ref;
   return isLoading && /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsxs)("div", {
     className: "fixed inset-0 z-50 flex items-center justify-center",
@@ -13523,6 +14123,46 @@ const XMarkIcon_ForwardRef = /*#__PURE__*/ external_commonjs_react_commonjs2_rea
 
 
 
+/**
+ * Props for the Modal component.
+ *
+ * @typedef {Object} ModalProps
+ *
+ * @property {boolean} isOpen
+ *   Whether the modal is visible.
+ *
+ * @property {() => void} [onClose]
+ *   Callback fired when the modal requests to close (Escape key or close button).
+ *
+ * @property {boolean} [isLoading]
+ *   Shows a loader overlay inside the modal content.
+ *
+ * @property {string} [loaderText]
+ *   Text passed to the loader when isLoading = true.
+ *
+ * @property {React.ReactNode} [header]
+ *   Content rendered in the modal header.
+ *
+ * @property {React.ReactNode} [body]
+ *   Content rendered in the modal body.
+ *
+ * @property {React.ReactNode} [footer]
+ *   Content rendered in the modal footer.
+ *
+ * @property {string} [className]
+ *   Additional classes for the modal container.
+ *
+ * @property {string} [footerClassName]
+ *
+ * @property {string} [headerClassName]
+ */
+
+/**
+ * Modal component written in JavaScript but fully typed using JSDoc.
+ *
+ * @param {ModalProps & React.HTMLAttributes<HTMLDivElement>} props
+ */
+
 const Modal = _ref => {
   let {
     isOpen,
@@ -22290,15 +22930,62 @@ const C247Tasks = props => /*#__PURE__*/(0,jsx_runtime_namespaceObject.jsx)(task
 
 
 
-/**
- * Generic Icon component supporting HeroIcons and C247 icons.
- *
- * Props:
- * - name: string - icon name
- * - library: 'hero' | 'c247' (default: 'hero')
- * - size: number (default: 24)
- * - className: string
- * - color: string
+/**
+ * All valid keys for heroicons.
+ * @typedef {keyof typeof HeroIcons} HeroIconName
+ */
+
+/**
+ * All valid keys for your custom C247 icons.
+ * @typedef {keyof typeof C247Icons} C247IconName
+ */
+
+/**
+ * Allowed icon name type (union of dynamic keys).
+ * @typedef {HeroIconName | C247IconName} IconName
+ */
+
+/**
+ * Which icon library to use.
+ * @typedef {'hero'|'c247'} IconLibrary
+ */
+
+/**
+ * Props for the generic Icon component.
+ *
+ * @typedef {Object} IconProps
+ *
+ * @property {IconName} name
+ *   The dynamic icon name to render.
+ *
+ * @property {IconLibrary} [library='hero']
+ *   Which icon set to render from.
+ *
+ * @property {number} [size=18]
+ *   Icon size in pixels.
+ *
+ * @property {string} [className]
+ *   Extra classes for styling.
+ *
+ * @property {string} [color]
+ *   Optional CSS color override.
+ */
+
+/**
+ * Generic Icon component supporting HeroIcons and C247 icons.
+ *
+ * @param {IconProps & React.SVGProps<SVGSVGElement>} props
+ */
+
+/**
+ * Generic Icon component supporting HeroIcons and C247 icons.
+ *
+ * Props:
+ * - name: string - icon name
+ * - library: 'hero' | 'c247' (default: 'hero')
+ * - size: number (default: 24)
+ * - className: string
+ * - color: string
  */
 
 const Icon = _ref => {
@@ -22333,6 +23020,48 @@ function SidebarItem_objectWithoutPropertiesLoose(r, e) { if (null == r) return
 
 
 
+/**
+ * Icon props (importing from your Icon component typedef).
+ * @typedef {import('../Icon/Icon').IconProps} IconProps
+ */
+
+/**
+ * A sidebar leaf item (no children).
+ * @typedef {Object} SidebarItemMenu
+ * @property {string|number} key
+ * @property {string} name
+ * @property {string} [path]
+ * @property {string} [href]
+ * @property {IconProps} [iconProps]
+ */
+
+/**
+ * Props for SidebarItem.
+ *
+ * @typedef {Object} SidebarItemProps
+ *
+ * @property {SidebarItemMenu} menu
+ *   The menu item to render.
+ *
+ * @property {boolean} open
+ *   Whether the sidebar is expanded.
+ *
+ * @property {boolean} [active=false]
+ *   Whether this item is currently active.
+ *
+ * @property {keyof JSX.IntrinsicElements | React.ComponentType<any>} [as='div']
+ *   Polymorphic wrapper: div, a, button, Link, etc.
+ *
+ * @property {() => void} [onClick]
+ *   Fired when the item is clicked.
+ */
+
+/**
+ * Fully typed SidebarItem component.
+ *
+ * @param {SidebarItemProps & React.HTMLAttributes<HTMLElement>} props
+ */
+
 function SidebarItem(_ref) {
   let {
       menu,
@@ -22379,6 +23108,57 @@ function SidebarGroup_toPrimitive(t, r) { if ("object" != typeof t || !t) return
 
 
 
+/**
+ * Icon props used by your dynamic Icon component (optional).
+ * @typedef {import('../Icon/Icon').IconProps} IconProps
+ */
+
+/**
+ * A single child menu item.
+ * @typedef {Object} SidebarChild
+ * @property {string|number} key
+ * @property {string} name
+ * @property {string} [path]
+ * @property {string} [href]
+ * @property {IconProps} [iconProps]
+ */
+
+/**
+ * Sidebar group object containing children.
+ * @typedef {Object} SidebarGroupMenu
+ * @property {string|number} key
+ * @property {string} name
+ * @property {SidebarChild[]} children
+ * @property {IconProps} [iconProps]
+ */
+
+/**
+ * Props for SidebarGroup component.
+ *
+ * @typedef {Object} SidebarGroupProps
+ *
+ * @property {SidebarGroupMenu} menu
+ *   The group menu containing children.
+ *
+ * @property {boolean} open
+ *   Whether the sidebar is currently expanded.
+ *
+ * @property {string|number|null} activeItem
+ *   The currently selected menu item key.
+ *
+ * @property {(key: string|number) => void} onItemClick
+ *   Handler fired when a child item is selected.
+ *
+ * @property {(open: boolean) => void} toggleSidebar
+ *   Used to open the sidebar when clicking a group.
+ */
+
+/**
+ * Fully typed SidebarGroup component.
+ *
+ * @param {SidebarGroupProps & React.HTMLAttributes<HTMLDivElement>} props
+ */
+
 function SidebarGroup(_ref) {
   let {
     menu,
@@ -22459,6 +23239,31 @@ function Link(_ref) {
 
 
 
+/**
+ * Shape of the user object
+ * @typedef {Object} ProfileCardUser
+ * @property {string} name
+ * @property {string} role
+ */
+
+/**
+ * Props for ProfileCard.
+ *
+ * @typedef {Object} ProfileCardProps
+ *
+ * @property {ProfileCardUser} user
+ *   The user object containing name + role.
+ *
+ * @property {string} [href]
+ *   If provided, the card becomes a link instead of a div.
+ */
+
+/**
+ * ProfileCard with polymorphic wrapper (Link or div).
+ *
+ * @param {ProfileCardProps & React.HTMLAttributes<HTMLDivElement>} props
+ */
+
 function ProfileCard(_ref) {
   let {
     user,
@@ -22546,6 +23351,68 @@ var sidebar_update = injectStylesIntoStyleTag_default()(sidebar/* default */.A,
 
 
 
+/**
+ * A single menu item (no children).
+ * @typedef {Object} SidebarMenuItem
+ * @property {string|number} key
+ * @property {string} name
+ * @property {string} [icon]        // optional icon name depending on your app
+ * @property {string} [href]        // optional link target
+ */
+
+/**
+ * A grouped menu entry with children.
+ * @typedef {Object} SidebarMenuGroup
+ * @property {string|number} key
+ * @property {string} name
+ * @property {SidebarMenuItem[]} children
+ */
+
+/**
+ * A full menu entry (either group or leaf item).
+ * @typedef {SidebarMenuItem | SidebarMenuGroup} SidebarMenu
+ */
+
+/**
+ * Minimal shape expected for SidebarProfile.
+ * @typedef {Object} SidebarUser
+ * @property {string|number} id
+ * @property {string} name
+ * @property {string} role
+ * @property {string} [avatar]   // optional depending on your design
+ */
+
+/**
+ * Props for Sidebar.
+ *
+ * @typedef {Object} SidebarProps
+ *
+ * @property {SidebarMenu[]} menus
+ *   All sidebar menu items (groups + items).
+ *
+ * @property {SidebarUser} user
+ *   The current logged-in user.
+ *
+ * @property {string|number|null} [activeItem]
+ *   Key of the currently selected item.
+ *
+ * @property {(key: string|number) => void} [onItemClick]
+ *   Fired when a menu item is clicked.
+ *
+ * @property {string} [logo]
+ *   Optional logo override.
+ *
+ * @property {string} [searchValue='']
+ *
+ * @property {(value: string) => void} [onSearchChange]
+ */
+
+/**
+ * Fully typed Sidebar component.
+ *
+ * @param {SidebarProps & React.HTMLAttributes<HTMLDivElement>} props
+ */
+
 function Sidebar(_ref) {
   let {
     menus,