@combeenation/custom-code-sdk 0.0.1-alpha12 → 0.0.1-alpha13

package/dist/index.d.ts

@@ -8,6 +8,13 @@ export declare class Button {
     #private;
     readonly id: CtrlId;
     constructor(id: CtrlId);
+    /**
+     * See {@link CustomControl.onRendered} for detailed information on what you can do with this listener and what it is
+     * not meant for.
+     *
+     * Also see {@link OnRenderedCallback} for important information regarding the `element` which is passed to the
+     * callback.
+     */
     onRendered(callback: OnRenderedCallback<HTMLButtonElement>): CallbackUnsubscribeOption;
     onClick(callback: OnClickCallback): CallbackUnsubscribeOption;
     setVisible(visible: boolean): Promise<void>;
@@ -25,6 +32,7 @@ export declare namespace CbnSdk {
         fireAnalyticsEvent,
         getAssetPaths,
         getParentPageUrl,
+        onParentPageEvent,
         navigateToLogin,
         onAnyCmpValueChanged,
         redirectParentPage,
@@ -54,6 +62,13 @@ export declare class Checkbox {
     #private;
     readonly id: CtrlId;
     constructor(id: CtrlId);
+    /**
+     * See {@link CustomControl.onRendered} for detailed information on what you can do with this listener and what it is
+     * not meant for.
+     *
+     * Also see {@link OnRenderedCallback} for important information regarding the `element` which is passed to the
+     * callback.
+     */
     onRendered(callback: OnRenderedCallback<HTMLLabelElement>): CallbackUnsubscribeOption;
     setVisible(visible: boolean): Promise<void>;
 }
@@ -98,8 +113,126 @@ export declare class Collapsible {
     #private;
     readonly id: CtrlId;
     constructor(id: CtrlId);
+    /**
+     * See {@link CustomControl.onRendered} for detailed information on what you can do with this listener and what it is
+     * not meant for.
+     *
+     * Also see {@link OnRenderedCallback} for important information regarding the `element` which is passed to the
+     * callback.
+     */
+    onRendered(callback: OnRenderedCallback<HTMLDivElement>): CallbackUnsubscribeOption;
+    setVisible(visible: boolean): Promise<void>;
+}
+
+export declare class Combobox<TValue extends NonNullable<DataListValue>> {
+    #private;
+    readonly id: CtrlId;
+    constructor(id: CtrlId);
+    /**
+     * See {@link CustomControlV1.onRendered} for detailed information on what you can do with this listener and what it
+     * is not meant for.
+     *
+     * Also see {@link OnRenderedCallback} for important information regarding the `element` which is passed to the
+     * callback.
+     */
     onRendered(callback: OnRenderedCallback<HTMLDivElement>): CallbackUnsubscribeOption;
+    /**
+     * See {@link CustomControlV1.onRendered} for detailed information on what you can do with this listener and what it
+     * is not meant for. Most of the information there also applies to `onItemRendered`.
+     *
+     * Also see {@link OnRenderedCallback} for important information regarding the `element` which is passed to the
+     * callback which also applies here.
+     *
+     * @param callback Callback function which is given the rendered HTML element and the corresponding item data.
+     *
+     *                 Typical usage for type safe access to the item data where `IProductsTable` is the auto generated
+     *                 type of the table component from which the combobox entries are populated:
+     *
+     *                 ```ts
+     *                 combobox.onItemRendered<IProductsTable[number]>((el, itemData) => { ... })
+     *                 ```
+     */
+    onItemRendered<TItemData>(callback: (element: HTMLDivElement, itemData: TItemData) => void): CallbackUnsubscribeOption;
+    /**
+     * See {@link CustomControlV1.onRendered} for detailed information on what you can do with this listener and what it
+     * is not meant for. Most of the information there also applies to `onValueItemRendered`.
+     *
+     * Also see {@link OnRenderedCallback} for important information regarding the `element` which is passed to the
+     * callback which also applies here.
+     *
+     * @param callback Callback function which is given the rendered HTML element and the corresponding item data of the
+     *                 currently selected value item shown in the trigger.
+     *
+     *                 Typical usage for type safe access to the item data where `IProductsTable` is the auto generated
+     *                 type of the table component from which the combobox entries are populated:
+     *
+     *                 ```ts
+     *                 combobox.onValueItemRendered<IProductsTable[number]>((el, itemData) => { ... })
+     *                 ```
+     */
+    onValueItemRendered<TItemData>(callback: (element: HTMLDivElement, itemData: TItemData) => void): CallbackUnsubscribeOption;
+    /**
+     * See {@link CustomControlV1.onRendered} for detailed information on what you can do with this listener and what it
+     * is not meant for. Most of the information there also applies to `onGroupHeaderRendered`.
+     *
+     * Also see {@link OnRenderedCallback} for important information regarding the `element` which is passed to the
+     * callback which also applies here.
+     *
+     * @param callback Callback function which is given the rendered HTML element and the corresponding group data.
+     *
+     *                 Typical usage for type safe access to the group data where `IProductGroupsTable` is the auto
+     *                 generated type of the table component from which the combobox groups are populated:
+     *
+     *                 ```ts
+     *                 combobox.onGroupHeaderRendered<IProductGroupsTable[number]>((el, groupData) => { ... })
+     *                 ```
+     */
+    onGroupHeaderRendered<TGroupData>(callback: (element: HTMLDivElement, groupData: TGroupData) => void): CallbackUnsubscribeOption;
+    /**
+     * Fires when the selection is committed which is:
+     *   - in single select mode: when the popup closes (or when an option is clicked).
+     *   - in multi select mode: immediately on every selection change.
+     *
+     * @param callback Callback function which is given the raw selection value/keys and the corresponding item data of
+     *                 all the selected items.
+     *
+     *                 Typical usage for type safe access to the item data where `IProductsTable` is the auto generated
+     *                 type of the table component from which the combobox entries are populated:
+     *
+     *                 ```ts
+     *                 // Single selection:
+     *                 combobox.onValueChange<IProductsTable[number]>((value, valueItemData) => { ... })
+     *
+     *                 // Multi selection:
+     *                 combobox.onValueChange<IProductsTable>((value, valueItemData) => { ... })
+     *                 ```
+     */
+    onValueChange<TItemData extends TValue extends any[] ? any[] : any>(callback: (value: TValue | undefined, valueItemData: TItemData | undefined) => void): CallbackUnsubscribeOption;
+    /**
+     * Registers a callback that fires when a combobox item is clicked.
+     *
+     * - Fires **before** `onValueChange`.
+     * - Fires even when the clicked item is already selected.
+     *
+     * @param callback Callback function which is given the item data of the clicked item and the raw mouse event.
+     *
+     *                 Typical usage for type safe access to the item data where `IProductsTable` is the auto generated
+     *                 type of the table component from which the combobox entries are populated:
+     *
+     *                 ```ts
+     *                 combobox.onItemClicked<IProductsTable[number]>((itemData, event) => { ... })
+     *                 ```
+     */
+    onItemClicked<TItemData>(callback: (itemData: TItemData, event: MouseEvent) => void): CallbackUnsubscribeOption;
     setVisible(visible: boolean): Promise<void>;
+    /**
+     * Sets the entries (data items) displayed by the combobox. Existing entries are overwritten.
+     */
+    setEntries(entries: TemplateData[]): void;
+    /**
+     * Sets the group data used to render the group headers of the combobox. Existing group data is overwritten.
+     */
+    setGroupData(groupData: TemplateData[]): void;
 }
 
 /**
@@ -317,6 +450,10 @@ export declare class CustomControl {
      *
      * !!! Important !!!
      *
+     * See {@link OnRenderedCallback} for important information regarding the `element` which is passed to the callback.
+     *
+     * !!! Important !!!
+     *
      * This is **not** meant to be used for manipulating the rendered content of the control besides simple,
      * non-structural/-behavioral changes like adding CSS classes or data attributes etc.
      *
@@ -335,12 +472,99 @@ export declare class CustomControl {
  */
 declare type CustomCtrlRenderFn = (element: HTMLDivElement, rawHtml: string | undefined) => void | Promise<void>;
 
-export declare class Dataview {
+/**
+ * The actual value which comes from the entries data and which is converted to `DataListHtmlValue` before being passed
+ * to the DOM elements.
+ */
+declare type DataListValue = string | string[] | number | number[] | undefined;
+
+export declare class Dataview<TValue extends NonNullable<DataListValue>> {
     #private;
     readonly id: CtrlId;
     constructor(id: CtrlId);
+    /**
+     * See {@link CustomControl.onRendered} for detailed information on what you can do with this listener and what it is
+     * not meant for.
+     *
+     * Also see {@link OnRenderedCallback} for important information regarding the `element` which is passed to the
+     * callback.
+     */
     onRendered(callback: OnRenderedCallback<HTMLDivElement>): CallbackUnsubscribeOption;
+    /**
+     * See {@link CustomControl.onRendered} for detailed information on what you can do with this listener and what it is
+     * not meant for. Most of the information there also applies to `onItemRendered`.
+     *
+     * Also see {@link OnRenderedCallback} for important information regarding the `element` which is passed to the
+     * callback which also applies here.
+     *
+     * @param callback Callback function which is given the rendered HTML element and the corresponding item data.
+     *
+     *                 Typical usage for type safe access to the item data where `IProductsTable` is the auto generated
+     *                 type of the table component from which the dataview entries are populated:
+     *
+     *                 ```ts
+     *                 dataview.onItemRendered<IProductsTable[number]>(el, itemData) => { ... }
+     *                 ```
+     */
+    onItemRendered<TItemData>(callback: (element: HTMLDivElement, itemData: TItemData) => void): CallbackUnsubscribeOption;
+    /**
+     * See {@link CustomControl.onRendered} for detailed information on what you can do with this listener and what it is
+     * not meant for. Most of the information there also applies to `onGroupHeaderRendered`.
+     *
+     * Also see {@link OnRenderedCallback} for important information regarding the `element` which is passed to the
+     * callback which also applies here.
+     *
+     * @param callback Callback function which is given the rendered HTML element and the corresponding group data.
+     *
+     *                 Typical usage for type safe access to the group data where `IProductGroupsTable` is the auto
+     *                 generated type of the table component from which the dataview groups are populated:
+     *
+     *                 ```ts
+     *                 dataview.onGroupHeaderRendered<IProductGroupsTable[number]>((el, groupData) => { ... })
+     *                 ```
+     */
+    onGroupHeaderRendered<TGroupData>(callback: (element: HTMLDivElement, groupData: TGroupData) => void): CallbackUnsubscribeOption;
+    /**
+     * @param callback Callback function which is given the raw selection value/keys and the corresponding item data of
+     *                 all the selected items.
+     *
+     *                 Typical usage for type safe access to the item data where `IProductsTable` is the auto generated
+     *                 type of the table component from which the dataview entries are populated:
+     *
+     *                 ```ts
+     *                 // Single selection list:
+     *                 dataview.onValueChange<IProductsTable[number]>(value, valueItemData) => { ... }
+     *
+     *                 // Multi selection list:
+     *                 dataview.onValueChange<IProductsTable>(value, valueItemData) => { ... }
+     *                 ```
+     */
+    onValueChange<TItemData extends TValue extends any[] ? any[] : any>(callback: (value: TValue | undefined, valueItemData: TItemData | undefined) => void): CallbackUnsubscribeOption;
+    /**
+     * Registers a callback that fires when a datalist item is clicked.
+     *
+     * - Fires **before** `onValueChange`.
+     * - Fires even when the clicked item is already selected.
+     *
+     * @param callback Callback function which is given the item data of rendered item and the raw mouse event.
+     *
+     *                 Typical usage for type safe access to the item data where `IProductsTable` is the auto generated
+     *                 type of the table component from which the dataview entries are populated:
+     *
+     *                 ```ts
+     *                 dataview.onItemClicked<IProductsTable[number]>(itemData, event) => { ... }
+     *                 ```
+     */
+    onItemClicked<TItemData>(callback: (itemData: TItemData, event: MouseEvent) => void): CallbackUnsubscribeOption;
     setVisible(visible: boolean): Promise<void>;
+    /**
+     * Sets the entries (data items) displayed by the dataview. Existing entries are overwritten.
+     */
+    setEntries(entries: TemplateData[]): void;
+    /**
+     * Sets the group data used to render the group headers of the dataview. Existing group data is overwritten.
+     */
+    setGroupData(groupData: TemplateData[]): void;
 }
 
 export declare type DocumentConvertTask = {
@@ -476,6 +700,13 @@ export declare class Input {
     #private;
     readonly id: CtrlId;
     constructor(id: CtrlId);
+    /**
+     * See {@link CustomControl.onRendered} for detailed information on what you can do with this listener and what it is
+     * not meant for.
+     *
+     * Also see {@link OnRenderedCallback} for important information regarding the `element` which is passed to the
+     * callback.
+     */
     onRendered(callback: OnRenderedCallback<HTMLDivElement>): CallbackUnsubscribeOption;
     setVisible(visible: boolean): Promise<void>;
 }
@@ -541,12 +772,54 @@ export declare const onAnyCmpValueChanged: <TInput extends ValueComponent>(liste
 
 declare type OnClickCallback = () => void;
 
+/**
+ * Registers a callback for events from the parent page.\
+ * The parent page can send those events by calling `Combeenation.sendEventToConfigurator`.
+ */
+export declare const onParentPageEvent: (callback: (type: "success" | "error", data: unknown) => void) => CallbackUnsubscribeOption;
+
+/**
+ * @param element The rendered DOM element.
+ *
+ *                !!! Important !!!
+ *
+ *                This can either be a newly created element or the same, reused element which was already passed to a
+ *                previous `onRendered` callback invocation.
+ *
+ *                What does this mean?
+ *                - When registering event listener, avoid `element.addEventListener` but use the form
+ *                  `element.onclick = ...` instead.
+ *                - Be careful when using API like `MutationObserver` on the element and ensure to not register multiple
+ *                  observer on the same element over time.
+ *                - Be careful when binding/using the element in external libraries which might use `addEventListener`
+ *                  or things like `MutationObserver` internally (e.g. DnD libraries etc.).
+ *                - If you **need to** use `addEventListener` etc. e.g. because you have to use a library which uses it
+ *                  internally, make sure to manually check whether the element was already processed/initialized in a
+ *                  previous `onRendered` invocation or not.
+ *
+ *                  E.g. something like this:
+ *
+ *                  ```ts
+ *                  dataview.onRendered((element) => {
+ *                    if (element.dataset.wasVisited) return;
+ *                    element.dataset.wasVisited = 'true';
+ *
+ *                    // -> Safely use `element.addEventListener` or `dndManager.init(element)` etc.
+ *                  });
+ */
 declare type OnRenderedCallback<T extends HTMLElement = HTMLElement> = (element: T) => void;
 
 export declare class Panel {
     #private;
     readonly id: CtrlId;
     constructor(id: CtrlId);
+    /**
+     * See {@link CustomControl.onRendered} for detailed information on what you can do with this listener and what it is
+     * not meant for.
+     *
+     * Also see {@link OnRenderedCallback} for important information regarding the `element` which is passed to the
+     * callback.
+     */
     onRendered(callback: OnRenderedCallback<HTMLDivElement>): CallbackUnsubscribeOption;
     setVisible(visible: boolean): Promise<void>;
 }
@@ -829,10 +1102,23 @@ declare type SyncCmpValuesStore<TCmps extends Record<CmpName, ValueComponent>> =
     [K in keyof TCmps & CmpName]: TCmps[K] extends ValueComponent<any, infer TValue, any> ? TValue | undefined : never;
 };
 
+/**
+ * The raw data passed to the corresponding liquid template (e.g. to a datalist item template or a group header
+ * template etc.)
+ */
+declare type TemplateData = Record<string, unknown>;
+
 declare class Text_2 {
     #private;
     readonly id: CtrlId;
     constructor(id: CtrlId);
+    /**
+     * See {@link CustomControl.onRendered} for detailed information on what you can do with this listener and what it is
+     * not meant for.
+     *
+     * Also see {@link OnRenderedCallback} for important information regarding the `element` which is passed to the
+     * callback.
+     */
     onRendered(callback: OnRenderedCallback<HTMLSpanElement>): CallbackUnsubscribeOption;
     setVisible(visible: boolean): Promise<void>;
     setText(text: string): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combeenation/custom-code-sdk",
-  "version": "0.0.1-alpha12",
+  "version": "0.0.1-alpha13",
   "description": "Combeenation custom code SDK package",
   "keywords": [],
   "homepage": "",
@@ -20,7 +20,7 @@
     "pack": "npm run build:clean && npm pack",
     "pub:alpha": "npm run build:clean && npm publish --tag alpha",
     "pub:beta": "npm run build:clean && npm publish --tag beta",
-    "pub:final": "npm run build:clean && npm publish --tag latest",
+    "pub:final": "npm run build:clean && npm publish",
     "pub:rc": "npm run build:clean && npm publish --tag rc",
     "ts:check": "tsc --noEmit --incremental --preserveWatchOutput --pretty",
     "ts:watch": "npm run ts:check -- --watch"
@@ -30,14 +30,15 @@
   },
   "devDependencies": {
     "@combeenation/configurator-client": "*",
+    "@microsoft/api-extractor": "7.58.7",
     "@repo/std-configs": "*",
     "@repo/std-lib": "*",
-    "typescript": "5.8.2",
-    "vite": "6.2.1",
-    "vite-plugin-dts": "4.5.4"
+    "typescript": "6.0.3",
+    "unplugin-dts": "1.0.1",
+    "vite": "8.0.14"
   },
   "@comment dependencies": [
-    "All our external (!) sub dependencies shall be included in `vite.config.ts:rollupOptions.external`.",
+    "All our external (!) sub dependencies shall be included in `vite.config.ts:rolldownOptions.external`.",
     "See comment there for more details on why."
   ],
   "@comment devDependencies": {
@@ -48,7 +49,7 @@
       "",
       "Listing it as `devDependencies` prevents the package from showing up in the builts package's `package.json` and",
       "Vite embeds the required code from the dependency directly into our built package as long as it is not listed",
-      "in Vite's `rollupOptions.external`.",
+      "in Vite's `rolldownOptions.external`.",
       "",
       "In theory, we could list it as a normal dependency and pin it to a published version but that makes dev life",
       "much harder e.g. when locally testing changes to the `custom-code-sdk` in a consuming project.",