fix(cli): improve description for events & outline experimental compo…

…nents (#6625)

.storybook/components/DocsHeader.module.css

@@ -35,3 +35,17 @@
 .infoTable td[data-import-cell='true'] {
   padding-inline-end: 2.5rem;
 }
+
+.titleRow {
+  padding-block-end: 0.5rem;
+}
+
+.titleRow :global(.sbdocs-title) {
+  margin-bottom: 0;
+}
+
+.experimentalLabel {
+  font-size: var(--sapObjectHeader_Title_SnappedFontSize);
+  margin-inline-start: 0.25rem;
+  align-self: flex-end;
+}

.storybook/components/DocsHeader.tsx

@@ -49,6 +49,7 @@ interface InfoTableProps {
   subComponents?: string[];
   mergeSubComponents?: boolean;
   isChart?: boolean;
+  experimental?: boolean;
 }
 
 export const InfoTable = ({ since, subComponents, mergeSubComponents }: InfoTableProps) => {
@@ -128,11 +129,12 @@ export const InfoTable = ({ since, subComponents, mergeSubComponents }: InfoTabl
   );
 };
 
-export const DocsHeader = ({ since, subComponents, mergeSubComponents, isChart }: InfoTableProps) => {
+export const DocsHeader = ({ since, subComponents, mergeSubComponents, isChart, experimental }: InfoTableProps) => {
   return (
     <ThemeProvider>
-      <FlexBox alignItems={FlexBoxAlignItems.Center}>
+      <FlexBox alignItems={FlexBoxAlignItems.Center} className={classes.titleRow}>
         <Title />
+        {experimental && <Label className={classes.experimentalLabel}>experimental</Label>}
         <span style={{ flexGrow: 1 }} />
         <Links />
       </FlexBox>

.storybook/manager-head.html

@@ -50,6 +50,15 @@
   input:not(:checked) ~ span:first-of-type {
     background-color: transparent !important;
   }
+
+  /*experimental components */
+  #data-display-table::after,
+  #inputs-tokenizer::after,
+  #layouts-floorplans-form::after,
+  #charts-timelinechart::after {
+    content: '(experimental)';
+    overflow: hidden;
+  }
 </style>
 
 <script data-ui5-config type="application/json">

.storybook/preview-head.html

@@ -83,6 +83,27 @@
     position: static;
   }
 
+  /* table in props description (table in ArgsTable) */
+  .docblock-argstable-body table {
+    max-width: 10rem;
+    table-layout: fixed;
+    border-collapse: collapse;
+    border-spacing: 1px;
+    text-align: center;
+  }
+  .docblock-argstable-body table th {
+    background-color: #eceff1;
+    color: #2e3438 !important;
+    border: 1px solid #dededf !important;
+    padding: 0px !important;
+    padding-block: 0.125rem !important;
+  }
+  .docblock-argstable-body table td {
+    border: 1px solid #dededf !important;
+    padding: 0px !important;
+    padding-block: 0.125rem !important;
+  }
+
   /* TODO remove this workaround as soon as https://github.com/storybookjs/storybook/issues/20497 is fixed */
   .docs-story > div > div[scale] {
     min-height: 20px;

packages/charts/src/components/TimelineChart/TimeLineChart.mdx

@@ -6,7 +6,7 @@ import { TimelineChartAnnotation } from './TimelineChartAnnotation';
 
 <Meta of={ComponentStories} />
 
-<DocsHeader isChart since="1.10.0" />
+<DocsHeader isChart since="1.10.0" experimental />
 
 <Canvas of={ComponentStories.Default} />
 

packages/charts/src/components/TimelineChart/TimeLineChart.stories.tsx

@@ -6,7 +6,7 @@ import { TimelineChart } from './TimelineChart.js';
 import { TimelineChartAnnotation } from './TimelineChartAnnotation.js';
 
 const meta = {
-  title: 'TimelineChart (experimental)',
+  title: 'TimelineChart',
   component: TimelineChart,
   argTypes: {
     dataset: {

packages/cli/src/scripts/create-wrappers/ComponentRenderer.ts

@@ -14,6 +14,7 @@ export class ComponentRenderer extends AbstractRenderer {
   private note: string = '';
   private isAbstract: boolean = false;
   private since: string | undefined;
+  private isExperimental: boolean | string | undefined = false;
 
   setAttributes(attrs: CEM.ClassField[]) {
     this.attributes.push(...attrs);
@@ -50,6 +51,11 @@ export class ComponentRenderer extends AbstractRenderer {
     return this;
   }
 
+  setIsExperimental(value?: boolean | string) {
+    this.isExperimental = value;
+    return this;
+  }
+
   prepare(context: WebComponentWrapper) {
     context.exportSet.add(context.componentName);
   }
@@ -64,10 +70,13 @@ export class ComponentRenderer extends AbstractRenderer {
       comment += ` *\n`;
       comment += ` * @since [${this.since}](https://github.com/SAP/ui5-webcomponents/releases/tag/v${this.since}) of __${context.packageName}__.\n`;
     }
-
     if (this.isAbstract) {
       comment += ' * @abstract\n';
     }
+    if (this.isExperimental) {
+      comment += ` * @experimental${typeof this.isExperimental === 'string' ? ` ${this.isExperimental}` : ''}\n`;
+    }
+
     comment += '*/';
 
     const component = dedent`

packages/cli/src/scripts/create-wrappers/PropTypesRenderer.ts

@@ -114,6 +114,15 @@ export class PropTypesRenderer extends AbstractRenderer {
             descriptionParts.push(` * @deprecated`);
           }
         }
+        if (
+          Object.prototype.hasOwnProperty.call(event, '_ui5Bubbles') ||
+          Object.prototype.hasOwnProperty.call(event, '_ui5Cancelable')
+        ) {
+          descriptionParts.push(` *`);
+          descriptionParts.push(`* | cancelable | bubbles |`);
+          descriptionParts.push(`* | :--------: | :-----: |`);
+          descriptionParts.push(`* | ${event._ui5Cancelable ? '✅' : '❌'}|${event._ui5Bubbles ? '✅' : '❌'}|`);
+        }
 
         const domRef = `${context.componentName}DomRef`;
         let eventType = '(event: unknown) => void;';

packages/cli/src/scripts/create-wrappers/main.ts

@@ -66,6 +66,7 @@ export default async function createWrappers(packageName: string, outDir: string
         .setNote(options.additionalComponentNote ?? '')
         .setIsAbstract(declaration._ui5abstract ?? false)
         .setSince(declaration._ui5since)
+        .setIsExperimental(declaration._ui5experimental)
     );
     wrapper.addRenderer(new ExportsRenderer());
 

packages/compat/src/components/Table/index.tsx

@@ -175,18 +175,30 @@ interface TablePropTypes
    * **Note:** The event will be fired if `growing` is set to `Button` or `Scroll`.
    *
    * **Note:** Available since [v2.0.0](https://github.com/SAP/ui5-webcomponents/releases/tag/v2.0.0) of **@ui5/webcomponents-compat**.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onLoadMore?: (event: Ui5CustomEvent<TableDomRef>) => void;
 
   /**
    * Fired when `TableColumn` is shown as a pop-in instead of hiding it.
    *
    * **Note:** Available since [v2.0.0](https://github.com/SAP/ui5-webcomponents/releases/tag/v2.0.0) of **@ui5/webcomponents-compat**.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onPopinChange?: (event: Ui5CustomEvent<TableDomRef, TablePopinChangeEventDetail>) => void;
 
   /**
    * Fired when a row in `Active` mode is clicked or `Enter` key is pressed.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onRowClick?: (event: Ui5CustomEvent<TableDomRef, TableRowClickEventDetail>) => void;
 
@@ -195,6 +207,10 @@ interface TablePropTypes
    * in `SingleSelect` and `MultiSelect` modes.
    *
    * **Note:** Available since [v2.0.0](https://github.com/SAP/ui5-webcomponents/releases/tag/v2.0.0) of **@ui5/webcomponents-compat**.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onSelectionChange?: (event: Ui5CustomEvent<TableDomRef, TableSelectionChangeEventDetail>) => void;
 }

packages/main/src/webComponents/AvatarGroup/index.tsx

@@ -74,12 +74,20 @@ interface AvatarGroupPropTypes
   /**
    * Fired when the component is activated either with a
    * click/tap or by using the Enter or Space key.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onClick?: (event: Ui5CustomEvent<AvatarGroupDomRef, AvatarGroupClickEventDetail>) => void;
 
   /**
    * Fired when the count of visible `Avatar` elements in the
    * component has changed
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onOverflow?: (event: Ui5CustomEvent<AvatarGroupDomRef>) => void;
 }

packages/main/src/webComponents/BarcodeScannerDialog/index.tsx

@@ -65,16 +65,28 @@ interface BarcodeScannerDialogPropTypes
    * Fired when the user closes the component.
    *
    * **Note:** Available since [v2.0.0](https://github.com/SAP/ui5-webcomponents/releases/tag/v2.0.0) of **@ui5/webcomponents-fiori**.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onClose?: (event: Ui5CustomEvent<BarcodeScannerDialogDomRef>) => void;
 
   /**
    * Fires when the scan fails with error.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onScanError?: (event: Ui5CustomEvent<BarcodeScannerDialogDomRef, BarcodeScannerDialogScanErrorEventDetail>) => void;
 
   /**
    * Fires when the scan is completed successfuuly.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onScanSuccess?: (
     event: Ui5CustomEvent<BarcodeScannerDialogDomRef, BarcodeScannerDialogScanSuccessEventDetail>

packages/main/src/webComponents/Breadcrumbs/index.tsx

@@ -43,6 +43,10 @@ interface BreadcrumbsPropTypes
    * **Note:** You can prevent browser location change by calling `event.preventDefault()`.
    *
    * **Note:** Call `event.preventDefault()` inside the handler of this event to prevent its default action/s.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ✅|✅|
    */
   onItemClick?: (event: Ui5CustomEvent<BreadcrumbsDomRef, BreadcrumbsItemClickEventDetail>) => void;
 }

packages/main/src/webComponents/Button/index.tsx

@@ -136,6 +136,10 @@ interface ButtonPropTypes extends ButtonAttributes, Omit<CommonProps, keyof Butt
    *
    * **Note:** The event will not be fired if the `disabled`
    * property is set to `true`.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onClick?: MouseEventHandler<ButtonDomRef>;
 }

packages/main/src/webComponents/Calendar/index.tsx

@@ -118,6 +118,10 @@ interface CalendarPropTypes
    * create instances of `CalendarDate` for the newly selected dates. In that case you should do this manually.
    *
    * **Note:** Call `event.preventDefault()` inside the handler of this event to prevent its default action/s.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ✅|✅|
    */
   onSelectionChange?: (event: Ui5CustomEvent<CalendarDomRef, CalendarSelectionChangeEventDetail>) => void;
 }

packages/main/src/webComponents/CardHeader/index.tsx

@@ -61,6 +61,10 @@ interface CardHeaderPropTypes
    * Fired when the component is activated by mouse/tap or by using the Enter or Space key.
    *
    * **Note:** The event would be fired only if the `interactive` property is set to true.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onClick?: (event: Ui5CustomEvent<CardHeaderDomRef>) => void;
 }

packages/main/src/webComponents/Carousel/index.tsx

@@ -135,6 +135,10 @@ interface CarouselPropTypes
    * Fired whenever the page changes due to user interaction,
    * when the user clicks on the navigation arrows or while resizing,
    * based on the `items-per-page` property.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onNavigate?: (event: Ui5CustomEvent<CarouselDomRef, CarouselNavigateEventDetail>) => void;
 }

packages/main/src/webComponents/CheckBox/index.tsx

@@ -122,6 +122,10 @@ interface CheckBoxPropTypes extends CheckBoxAttributes, Omit<CommonProps, keyof
    * Fired when the component checked state changes.
    *
    * **Note:** Call `event.preventDefault()` inside the handler of this event to prevent its default action/s.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ✅|✅|
    */
   onChange?: (event: Ui5CustomEvent<CheckBoxDomRef>) => void;
 }

packages/main/src/webComponents/ColorPalette/index.tsx

@@ -17,6 +17,10 @@ interface ColorPalettePropTypes extends ColorPaletteAttributes, Omit<CommonProps
   children?: ReactNode | ReactNode[];
   /**
    * Fired when the user selects a color.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onItemClick?: (event: Ui5CustomEvent<ColorPaletteDomRef, ColorPaletteItemClickEventDetail>) => void;
 }

packages/main/src/webComponents/ColorPalettePopover/index.tsx

@@ -67,11 +67,19 @@ interface ColorPalettePopoverPropTypes
    * Fired when the `ColorPalettePopover` is closed due to user interaction.
    *
    * **Note:** Available since [v1.21.0](https://github.com/SAP/ui5-webcomponents/releases/tag/v1.21.0) of **@ui5/webcomponents**.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onClose?: (event: Ui5CustomEvent<ColorPalettePopoverDomRef>) => void;
 
   /**
    * Fired when the user selects a color.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onItemClick?: (event: Ui5CustomEvent<ColorPalettePopoverDomRef, ColorPalettePopoverItemClickEventDetail>) => void;
 }

packages/main/src/webComponents/ColorPicker/index.tsx

@@ -31,6 +31,10 @@ interface ColorPickerPropTypes
     Omit<CommonProps, keyof ColorPickerAttributes | 'onChange'> {
   /**
    * Fired when the the selected color is changed
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onChange?: (event: Ui5CustomEvent<ColorPickerDomRef>) => void;
 }

packages/main/src/webComponents/ComboBox/index.tsx

@@ -149,18 +149,30 @@ interface ComboBoxPropTypes
   valueStateMessage?: UI5WCSlotsNode;
   /**
    * Fired when the input operation has finished by pressing Enter, focusout or an item is selected.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onChange?: (event: Ui5CustomEvent<ComboBoxDomRef>) => void;
 
   /**
    * Fired when typing in input or clear icon is pressed.
    *
    * **Note:** filterValue property is updated, input is changed.
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onInput?: (event: Ui5CustomEvent<ComboBoxDomRef>) => void;
 
   /**
    * Fired when selection is changed by user interaction
+   *
+   * | cancelable | bubbles |
+   * | :--------: | :-----: |
+   * | ❌|✅|
    */
   onSelectionChange?: (event: Ui5CustomEvent<ComboBoxDomRef, ComboBoxSelectionChangeEventDetail>) => void;
 }