@makigamestudio/ui-core 0.1.7 → 0.3.0

package/types/makigamestudio-ui-core.d.ts

@@ -1,5 +1,5 @@
 import * as _angular_core from '@angular/core';
-import { ElementRef } from '@angular/core';
+import { ElementRef, Signal } from '@angular/core';
 
 /**
  * TestInterface - Example interface exported from ui-core library.
@@ -50,6 +50,224 @@ declare class TestClass implements TestInterface {
     toJSON(): TestInterface;
 }
 
+/**
+ * @file Action button configuration interface
+ * @description Configuration options for styling and behavior of action buttons
+ */
+/**
+ * Configuration interface for action button styling and behavior.
+ *
+ * @example
+ * ```typescript
+ * const config: ActionButtonConfig = {
+ *   fill: 'outline',
+ *   size: 'small',
+ *   color: 'primary',
+ *   shape: 'round'
+ * };
+ * ```
+ */
+interface ActionButtonConfig {
+    /**
+     * The fill style of the button.
+     * - `'clear'`: Transparent background
+     * - `'outline'`: Transparent background with border
+     * - `'solid'`: Filled background (default Ionic behavior)
+     * - `'default'`: Uses Ionic default
+     */
+    readonly fill?: 'clear' | 'outline' | 'solid' | 'default';
+    /**
+     * The size of the button.
+     * - `'small'`: Smaller button
+     * - `'default'`: Standard size
+     * - `'large'`: Larger button
+     */
+    readonly size?: 'small' | 'default' | 'large';
+    /**
+     * The color of the button. Can be an Ionic color name
+     * (primary, secondary, tertiary, success, warning, danger, light, medium, dark)
+     * or a custom color defined in your theme.
+     */
+    readonly color?: string;
+    /**
+     * The shape of the button.
+     * - `'round'`: Fully rounded corners
+     */
+    readonly shape?: 'round';
+    /**
+     * How the button should expand to fill its container.
+     * - `'block'`: Full width with rounded corners
+     * - `'full'`: Full width with square corners
+     */
+    readonly expand?: 'block' | 'full';
+    /**
+     * Whether the button is disabled.
+     */
+    readonly disabled?: boolean;
+    /**
+     * Whether to use a stronger font weight.
+     */
+    readonly strong?: boolean;
+    /**
+     * Whether to hide the dropdown chevron icon for dropdown type buttons.
+     * Only applies when `type` is `ActionButtonType.Dropdown`.
+     * @default false
+     */
+    readonly hideDropdownIcon?: boolean;
+}
+
+/**
+ * @file Action button type enumeration
+ * @description Defines the display types for action buttons
+ */
+/**
+ * Enumeration of action button display types.
+ *
+ * @example
+ * ```typescript
+ * const button: ActionButton = {
+ *   id: 'save-btn',
+ *   label: 'Save',
+ *   type: ActionButtonType.Default,
+ *   handler: () => console.log('Saved!')
+ * };
+ * ```
+ */
+declare enum ActionButtonType {
+    /**
+     * Standard button with label and optional icon.
+     */
+    Default = "default",
+    /**
+     * Button displaying only an icon, no label.
+     */
+    IconOnly = "icon-only",
+    /**
+     * Button that opens a dropdown popover with child actions.
+     */
+    Dropdown = "dropdown"
+}
+
+/**
+ * @file Action button interface
+ * @description Main interface for configuring action buttons
+ */
+
+/**
+ * Interface representing an action button configuration.
+ *
+ * @typeParam T - The type of data passed to the handler function. Defaults to `void`.
+ *
+ * @example
+ * ```typescript
+ * // Simple button
+ * const saveButton: ActionButton = {
+ *   id: 'save',
+ *   label: 'Save',
+ *   icon: 'saveOutline',
+ *   type: ActionButtonType.Default,
+ *   handler: () => console.log('Saved!')
+ * };
+ *
+ * // Async button with auto-loading
+ * const submitButton: ActionButton = {
+ *   id: 'submit',
+ *   label: 'Submit',
+ *   type: ActionButtonType.Default,
+ *   handler: async () => {
+ *     await api.submit();
+ *   }
+ * };
+ *
+ * // Dropdown button with children
+ * const menuButton: ActionButton = {
+ *   id: 'menu',
+ *   label: 'Actions',
+ *   type: ActionButtonType.Dropdown,
+ *   handler: () => {}, // Not called for dropdowns
+ *   children: [
+ *     { id: 'edit', label: 'Edit', type: ActionButtonType.Default, handler: () => edit() },
+ *     { id: 'delete', label: 'Delete', type: ActionButtonType.Default, handler: () => delete() }
+ *   ]
+ * };
+ *
+ * // Button with generic data parameter
+ * const itemButton: ActionButton<Item> = {
+ *   id: 'select',
+ *   label: 'Select',
+ *   type: ActionButtonType.Default,
+ *   handler: (item) => selectItem(item)
+ * };
+ * ```
+ */
+interface ActionButton<T = void> {
+    /**
+     * Unique identifier for the button.
+     */
+    readonly id: string;
+    /**
+     * Icon name to display in the button.
+     * Should be an Ionicon name registered with `addIcons()`.
+     */
+    readonly icon?: string;
+    /**
+     * Text label to display in the button.
+     * Required for `Default` type, optional for `IconOnly` and `Dropdown`.
+     */
+    readonly label?: string;
+    /**
+     * Handler function called when the button is clicked.
+     * Can be synchronous or asynchronous. For async handlers,
+     * the component will automatically manage the loading state.
+     *
+     * @param data - Optional data parameter of type T
+     * @returns void or Promise<void>
+     */
+    readonly handler: (data?: T) => void | Promise<void>;
+    /**
+     * External loading state. When true, the button shows a loading spinner.
+     * The component also manages an internal loading state for async handlers.
+     * The button shows loading if either this or the internal state is true.
+     */
+    readonly loading?: boolean;
+    /**
+     * Controls whether to display the loading spinner when the button is in a loading state.
+     * Defaults to `true` if not specified.
+     *
+     * When `false`, the button will still be disabled during loading, but the spinner will not be shown.
+     * This is useful when you want to indicate loading state without replacing the button's visual content.
+     *
+     * For dropdown buttons, this also controls loading state propagation from children:
+     * - If both parent and child have `showLoadingSpinner !== false`, the parent will show a spinner when ANY child is loading.
+     * - The parent dropdown remains clickable even when showing inherited child loading state.
+     *
+     * @default true
+     */
+    readonly showLoadingSpinner?: boolean;
+    /**
+     * Child action buttons for dropdown menus.
+     * Only used when `type` is `ActionButtonType.Dropdown`.
+     */
+    readonly children?: readonly ActionButton<T>[];
+    /**
+     * The display type of the button.
+     */
+    readonly type: ActionButtonType;
+    /**
+     * Optional configuration for button styling.
+     */
+    readonly config?: ActionButtonConfig;
+    /**
+     * Accessible label for screen readers.
+     * Recommended for `IconOnly` buttons.
+     */
+    readonly ariaLabel?: string;
+    /**
+     * Tooltip text shown on hover.
+     */
+    readonly tooltip?: string;
+}
+
 /**
  * TestService - Example service using Angular Signals for reactive state management.
  * Provided in root, demonstrating singleton service pattern with signal-based state.
@@ -140,5 +358,249 @@ declare class TestCardComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<TestCardComponent, "maki-test-card", never, { "item": { "alias": "item"; "required": true; "isSignal": true; }; "showActions": { "alias": "showActions"; "required": false; "isSignal": true; }; }, { "itemClick": "itemClick"; "editClick": "editClick"; "deleteClick": "deleteClick"; }, never, never, true, never>;
 }
 
-export { TestCardComponent, TestClass, TestService };
-export type { TestInterface };
+/**
+ * Component that renders a list of action buttons for use in popovers/dropdowns.
+ *
+ * This component is designed to be used as the content of an `ion-popover`
+ * created via `PopoverController`. When a button is selected, it dismisses
+ * the popover and returns the selected button.
+ *
+ * @example
+ * ```typescript
+ * // Used internally by maki-button for dropdowns
+ * // Can also be used standalone:
+ * const popover = await popoverCtrl.create({
+ *   component: ActionButtonListComponent,
+ *   componentProps: { buttons: myButtons },
+ *   event: clickEvent
+ * });
+ * await popover.present();
+ *
+ * const { data } = await popover.onDidDismiss();
+ * if (data) {
+ *   data.handler();
+ * }
+ * ```
+ *
+ * @usageNotes
+ * ### Inputs
+ * - `buttons` (required): Array of `ActionButton` objects to display
+ *
+ * ### Outputs
+ * - `buttonSelect`: Emits the selected `ActionButton` when clicked
+ */
+declare class ActionButtonListComponent {
+    /**
+     * Reference to ActionButtonType.Dropdown for template comparison.
+     * @internal
+     */
+    protected readonly dropdownType = ActionButtonType.Dropdown;
+    /**
+     * Popover controller for dismissing the popover when an item is selected.
+     */
+    private readonly popoverCtrl;
+    /**
+     * Internal signal to store buttons passed via componentProps.
+     * PopoverController.create() sets properties directly, bypassing signal inputs.
+     */
+    private readonly _buttonsFromProps;
+    /**
+     * Internal signal to store the Set of currently loading child button IDs.
+     */
+    private readonly _loadingChildIdsFromProps;
+    /**
+     * The list of action buttons to display (when used via template binding).
+     */
+    readonly buttons: _angular_core.InputSignal<readonly ActionButton<void>[]>;
+    /**
+     * Computed button list that works with both signal input and componentProps.
+     * PopoverController passes buttons as a direct property, not through Angular's input system.
+     */
+    protected readonly buttonList: () => readonly ActionButton[];
+    /**
+     * Setter to capture buttons passed via PopoverController.create({ componentProps }).
+     * This is called when Ionic sets the property directly on the component instance.
+     */
+    set buttonsFromPopover(value: readonly ActionButton[]);
+    /**
+     * Setter to capture loading child IDs signal passed via PopoverController.create({ componentProps }).
+     */
+    set loadingChildIds(value: Signal<ReadonlySet<string>>);
+    /**
+     * Checks if a specific button is currently loading.
+     */
+    protected isButtonLoading(button: ActionButton): boolean;
+    /**
+     * Emits when a button is selected from the list.
+     */
+    readonly buttonSelect: _angular_core.OutputEmitterRef<ActionButton<void>>;
+    constructor();
+    /**
+     * Handles click on a button item.
+     * Emits the selected button and dismisses the popover.
+     *
+     * @param button - The clicked action button
+     */
+    protected onButtonClick(button: ActionButton): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ActionButtonListComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ActionButtonListComponent, "maki-action-button-list", never, { "buttons": { "alias": "buttons"; "required": false; "isSignal": true; }; }, { "buttonSelect": "buttonSelect"; }, never, never, true, never>;
+}
+
+/**
+ * A configurable button component that renders an `ion-button` based on
+ * an `ActionButton` configuration object.
+ *
+ * Features:
+ * - Three display types: Default (label + icon), IconOnly, and Dropdown
+ * - Automatic loading state management for async handlers
+ * - Dropdown support via PopoverController with child actions
+ * - Full Ionic button styling configuration (fill, size, color, shape, expand)
+ * - Automatic chevron icon for dropdown buttons
+ *
+ * @example
+ * ```html
+ * <!-- Simple button -->
+ * <maki-button [button]="saveButton" />
+ *
+ * <!-- Icon-only button -->
+ * <maki-button [button]="iconButton" />
+ *
+ * <!-- Dropdown button -->
+ * <maki-button [button]="menuButton" />
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In your component
+ * saveButton: ActionButton = {
+ *   id: 'save',
+ *   label: 'Save',
+ *   icon: 'saveOutline',
+ *   type: ActionButtonType.Default,
+ *   config: { fill: 'solid', color: 'primary' },
+ *   handler: async () => {
+ *     await this.saveData();
+ *   }
+ * };
+ *
+ * menuButton: ActionButton = {
+ *   id: 'menu',
+ *   label: 'Actions',
+ *   type: ActionButtonType.Dropdown,
+ *   handler: () => {},
+ *   children: [
+ *     { id: 'edit', label: 'Edit', icon: 'createOutline', type: ActionButtonType.Default, handler: () => this.edit() },
+ *     { id: 'delete', label: 'Delete', icon: 'trashOutline', type: ActionButtonType.Default, handler: () => this.delete() }
+ *   ]
+ * };
+ * ```
+ *
+ * @usageNotes
+ * ### Inputs
+ * - `button` (required): The `ActionButton` configuration object
+ *
+ * ### Outputs
+ * - `buttonClick`: Emits the button configuration when clicked (for non-dropdown buttons)
+ * - `childSelect`: Emits the selected child button (for dropdown buttons)
+ *
+ * ### Loading State
+ * The component automatically manages loading state for async handlers.
+ * When a handler returns a Promise, the button shows a spinner until it resolves/rejects.
+ * You can also manually control loading via the `button.loading` property.
+ *
+ * ### Dropdown Behavior
+ * For `ActionButtonType.Dropdown`, clicking the button opens an `ion-popover`
+ * containing an `ActionButtonListComponent` with the child buttons.
+ * When a child is selected, its handler is executed and `childSelect` is emitted.
+ */
+declare class ButtonComponent {
+    /**
+     * Popover controller for creating dropdown popovers.
+     */
+    private readonly popoverCtrl;
+    /**
+     * Internal loading state for async handler execution.
+     */
+    private readonly _isLoading;
+    /**
+     * Set of child button IDs that are currently loading (for dropdowns).
+     * Tracks multiple concurrent loading operations.
+     */
+    private readonly _loadingChildIds;
+    /**
+     * The action button configuration.
+     */
+    readonly button: _angular_core.InputSignal<ActionButton<void>>;
+    /**
+     * Emits when the button is clicked (for non-dropdown buttons).
+     * Emits the button configuration that was clicked.
+     */
+    readonly buttonClick: _angular_core.OutputEmitterRef<ActionButton<void>>;
+    /**
+     * Emits when a child button is selected from a dropdown.
+     * Only emits for `ActionButtonType.Dropdown` buttons.
+     */
+    readonly childSelect: _angular_core.OutputEmitterRef<ActionButton<void>>;
+    /**
+     * Checks if any child button is in a loading state and has showLoadingSpinner enabled.
+     */
+    private readonly hasLoadingChild;
+    /**
+     * Combined loading state from external prop, internal async state, and child loading.
+     * Returns true if:
+     * - Internal loading state is active, OR
+     * - External loading prop is true, OR
+     * - Any child is loading AND parent has showLoadingSpinner !== false
+     */
+    readonly isLoading: _angular_core.Signal<boolean>;
+    /**
+     * Whether to display the loading spinner.
+     * Shows spinner only if button is loading AND showLoadingSpinner is not false.
+     */
+    readonly showLoadingSpinner: _angular_core.Signal<boolean>;
+    /**
+     * Whether the button is disabled.
+     * - Non-dropdown buttons: Disabled when loading or explicitly disabled in config
+     * - Dropdown buttons: Only disabled when explicitly disabled in config or when parent itself is loading
+     *   (not disabled by inherited child loading - user can still open dropdown to see loading children)
+     */
+    readonly isDisabled: _angular_core.Signal<boolean>;
+    /**
+     * Determines the slot for the icon based on button type and label presence.
+     */
+    readonly iconSlot: _angular_core.Signal<"icon-only" | "start">;
+    /**
+     * Whether to show the label text.
+     */
+    readonly showLabel: _angular_core.Signal<string | false | undefined>;
+    /**
+     * Whether to show the dropdown chevron icon.
+     */
+    readonly showDropdownIcon: _angular_core.Signal<boolean>;
+    constructor();
+    /**
+     * Handles button click events.
+     * For dropdown buttons, opens a popover with child actions.
+     * For other buttons, executes the handler with auto-loading management.
+     *
+     * @param event - The click event
+     */
+    protected onClick(event: Event): Promise<void>;
+    /**
+     * Opens a dropdown popover with child action buttons.
+     *
+     * @param event - The triggering click event for popover positioning
+     */
+    private openDropdown;
+    /**
+     * Executes a button's handler with automatic loading state management.
+     *
+     * @param btn - The button whose handler to execute
+     */
+    private executeHandler;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ButtonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ButtonComponent, "maki-button", never, { "button": { "alias": "button"; "required": true; "isSignal": true; }; }, { "buttonClick": "buttonClick"; "childSelect": "childSelect"; }, never, never, true, never>;
+}
+
+export { ActionButtonListComponent, ActionButtonType, ButtonComponent, TestCardComponent, TestClass, TestService };
+export type { ActionButton, ActionButtonConfig, TestInterface };