@api-client/ui 0.5.57 → 0.6.0

package/INSTRUCTIONS.md

@@ -0,0 +1,141 @@
+# Project Instructions
+
+This project is a UI component library `@api-client/ui` built with [Lit](https://lit.dev/).
+
+## Getting Started
+
+1.  **Install Dependencies**:
+    ```bash
+    npm install
+    ```
+
+## Development Commands
+
+*   **Start Dev Server**:
+    ```bash
+    npm run dev
+    ```
+    Starts the development server using `@web/dev-server` and watches for changes. Serves the `demo` folder found at `demo/index.html`.
+
+*   **Build Project**:
+    ```bash
+    npm run build
+    ```
+    Compiles TypeScript and copies assets. generated output resides in `build/src/`. Uses `wireit` for caching.
+
+*   **Run Tests**:
+    ```bash
+    npm test
+    ```
+    Runs tests using `@web/test-runner` with Playwright (Chromium).
+    To target a single file: `npm test -- --files=".tmp/test/**/MyComponent.test.js"`
+
+*   **Watch Tests**:
+    ```bash
+    npm run test:watch
+    ```
+
+*   **Lint & Format**:
+    ```bash
+    npm run lint
+    npm run format
+    ```
+
+*   **Releasing**:
+    See [RELEASE.md](./RELEASE.md) and [RELEASE_SETUP.md](./RELEASE_SETUP.md).
+
+## Architecture & Core Concepts
+
+**Application → Activities → Fragments** (Mirrors Android Lifecycle)
+- **Lifecycle**: Created → Attached → Started → Resumed → Paused → Stopped → Detached → Destroyed.
+- **Key Files** (`src/core/`):
+    - `Application.ts`: Top-level container, owns `ActivityManager`.
+    - `Activity.ts`: Screen-level logic + fragment orchestration.
+    - `Fragment.ts`: Reusable UI segments. **Never assume global singletons.**
+- **Rule**: Always use manager APIs (`addFragment`, `showFragment`) rather than manual DOM manipulation.
+
+## Component & Folder Conventions
+
+- **Paths**:
+    - `src/md/`: Base Material-style components.
+    - `src/elements/`: Business / composite elements.
+- **Structure**: `component/` directory containing:
+    - `internals/`: Base class logic.
+    - `YourThing.ts`: Public element file registration (`@customElement`).
+    - `*.styles.ts`: Styles.
+- **Registration**: Do NOT use the legacy `src/define/` folder. Register in the public element file.
+- **Exports**: Add new exports explicitly to `src/index.ts`.
+
+## Lit Patterns (Enforced)
+
+- **State**: Use `@property` for public API, `@state` for internal reactive state.
+- **Initialization**: Initialize boolean props in the constructor.
+- **Order**: constructor → lifecycle overrides → helpers → render methods.
+- **DOM Querying**: Use `@query` for internal DOM, `@queryAssignedElements` for slots.
+- **Styles**: Import from sibling `*.styles.ts`. Assign `static styles` only on the final registered class, not in `internals/` base classes.
+- **Theming**: Expose style hooks with `part` attributes; prefer CSS vars for theming.
+
+## Interaction & Intent System
+
+Use **Intent Events** for navigation and cross-component actions. Do not reference Activities directly.
+
+```ts
+this.dispatchEvent(new CustomEvent('startactivity', {
+  detail: { intent: { action: 'user.profile', data: { id } } }
+}));
+```
+
+Activities listen for these events to decide fragment transitions.
+
+## State Management
+
+- **Controllers**: Reusable logic lives in `src/controllers/` (e.g., `ActionController`, `LiveDataController`).
+- **Guidelines**:
+    - Compose controllers rather than duplicating state wiring.
+    - Keep side-effects isolated.
+    - Document expected lifecycle usage.
+
+## Styling & MD3
+
+- Use **MD3 tokens** via CSS custom properties.
+- No ad-hoc color literals.
+- Use `this._internals.states.add('--error')` instead of custom class names for component states where feasible.
+- Component-specific tokens go in component styles; do not put global resets there.
+
+## Testing Norms
+
+- **Location**: Co-locate tests under `test/` mirroring source paths.
+- **Helpers**: Use `test/helpers/` and `window.testUtils`.
+- **Async**: After validating a property change, ALWAYS `await el.updateComplete`.
+- **Assertions**: Prefer Chai Assert API.
+
+## Workflow: Adding a New Component
+
+1.  **Create Directory**: Under `src/md/` or `src/elements/`.
+2.  **Base Logic**: `internals/YourThingBase.ts`.
+3.  **Styles**: `YourThing.styles.ts`.
+4.  **Registration**: `YourThing.ts`:
+    ```ts
+    @customElement('ui-your-thing')
+    export class UiYourThing extends YourThingBase { static override styles = [styles] }
+    ```
+5.  **Export**: Add to `src/index.ts`.
+6.  **Demo**: Add to `demo/[category]/your-thing/`.
+7.  **Test**: Add to `test/`.
+
+## Common Pitfalls
+
+- Direct DOM mutation of fragments (use manager).
+- Adding styles to the base class (must live on registered element).
+- Using stale legacy `define/` patterns.
+- Skipping `await el.updateComplete` in tests.
+- Hard-coded colors instead of tokens.
+
+## External Dependencies
+
+- Models come from `@api-client/core`.
+- `monaco-editor` is ISOLATED in `src/elements/code-editor/`. Do not import it elsewhere.
+
+## Wireit
+
+This project uses [wireit](https://github.com/google/wireit) for script dependency management and caching.

package/build/src/builders/DialogBuilder.d.ts

@@ -0,0 +1,245 @@
+import type { Activity } from '../core/Activity.js';
+import type { Fragment } from '../core/Fragment.js';
+import { UiDialogElement } from '../md/dialog/ui-dialog.js';
+import '../md/dialog/ui-dialog.js';
+export type RenderAs = 'message' | 'error' | 'picker';
+export interface ActionOptions {
+    /**
+     * The label to show on the action button.
+     * Default labels are `OK` for the positive action and `Cancel` for the negative action.
+     */
+    label?: string;
+    /**
+     * When set it sets the value on the action button.
+     */
+    value?: string;
+    /**
+     * The action to call when the action is triggered.
+     * @param value Optional value returned by the dialog.
+     */
+    action?: (value?: unknown) => void;
+}
+export interface PositiveActionOptions extends ActionOptions {
+    /**
+     * The type of the button. Default is `submit`.
+     * If set to `button`, the dialog will not close on click.
+     */
+    type?: 'submit' | 'button';
+}
+/**
+ * Options for unsaved changes detection
+ */
+export interface UnsavedChangesOptions {
+    /**
+     * Function that returns true if there are unsaved changes
+     */
+    hasUnsavedChanges: () => boolean;
+    /**
+     * Title for the unsaved changes warning dialog
+     */
+    warningTitle?: string;
+    /**
+     * Message for the unsaved changes warning dialog
+     */
+    warningMessage?: string;
+    /**
+     * Label for the "Discard Changes" button
+     */
+    discardLabel?: string;
+    /**
+     * Label for the "Keep Editing" button
+     */
+    keepEditingLabel?: string;
+}
+/**
+ * A programmatic access to the dialog UI.
+ * It hook ups to the `Activity` lifecycle methods to control the dialog.
+ * When the activity is destroyed, the dialog is destroyed along with it.
+ * When the activity is paused, the dialog is hidden, but not removed from the DOM.
+ * The dialog then becomes visible again when the activity resumes.
+ */
+export declare class DialogBuilder {
+    private parent?;
+    /**
+     * The title of the dialog.
+     */
+    static title: string | undefined;
+    /**
+     * The title of the dialog.
+     * When set, it takes precedence over the static title.
+     */
+    protected title: string | undefined;
+    /**
+     * The description of the dialog.
+     * It is not used by default, but can be set to add custom content.
+     */
+    protected description: string | undefined;
+    /**
+     * The positive action that closes the dialog.
+     * It is not used by default, but can be set to add custom actions.
+     */
+    protected positiveAction: PositiveActionOptions | undefined;
+    /**
+     * The negative action that closes the dialog.
+     * It is not used by default, but can be set to add custom actions.
+     */
+    protected negativeAction: ActionOptions | undefined;
+    /**
+     * The body of the dialog. It is not used by default, but can be set to add custom content.
+     */
+    protected body: HTMLElement | undefined;
+    /**
+     * The CSS classes to add to the dialog element.
+     * It is not used by default, but can be set to add custom classes.
+     */
+    protected classes: string[] | undefined;
+    /**
+     * When rendered, it sets the corresponding class name to the dialog.
+     */
+    protected renderAs: RenderAs;
+    /**
+     * The root element to render the dialog into.
+     * By default the dialog is rendered into the document body.
+     */
+    protected renderRoot?: HTMLElement | undefined;
+    /**
+     * When set to true, the dialog will be rendered as a modal dialog.
+     */
+    protected modal: boolean | undefined;
+    /**
+     * The dialog element that is created by this builder.
+     */
+    dialog?: UiDialogElement;
+    /**
+     * Options for unsaved changes detection
+     */
+    protected unsavedChangesOptions?: UnsavedChangesOptions;
+    /**
+     * Reference to the unsaved changes warning dialog
+     */
+    unsavedChangesDialog?: DialogBuilder;
+    /**
+     * Creates a new dialog builder.
+     * @param parent The parent activity or fragment that the dialog is associated with.
+     * It will listen to the activity lifecycle events to control the dialog visibility.
+     * When not provided, the dialog will not be controlled by the activity lifecycle.
+     */
+    constructor(parent?: Activity | Fragment | undefined);
+    /**
+     * Sets the dialog title.
+     * @param title The title of the dialog to set. Undefined/empty to clear.
+     * @returns The instance of this class for chaining.
+     */
+    setTitle(title?: string): this;
+    /**
+     * Sets the dialog description.
+     * @param title The value to to set. Undefined/empty to clear.
+     * @returns The instance of this class for chaining.
+     */
+    setDescription(description: string): this;
+    /**
+     * Sets the positive action that closes the dialog.
+     *
+     * @param action The action to call when the positive action is triggered.
+     * @param label The label of the positive button. Default to "OK"
+     * @returns The instance of this class for chaining.
+     */
+    setPositiveAction(options?: PositiveActionOptions): this;
+    /**
+     * Sets the negative action that closes the dialog.
+     *
+     * @param action The action to call when the negative action is triggered.
+     * @param label The label of the negative button. Default to "Cancel"
+     * @returns The instance of this class for chaining.
+     */
+    setNegativeAction(options?: ActionOptions): this;
+    /**
+     * By default, the dialog is rendered as a message dialog. Set to a different type to
+     * change the rendering.
+     *
+     * @param renderAs The value for the type of the dialog.
+     * @returns The instance of this class for chaining.
+     */
+    setRenderAs(renderAs: RenderAs): this;
+    /**
+     * Sets up unsaved changes detection for the dialog.
+     * When the user tries to close the dialog with unsaved changes, a warning dialog will be shown.
+     * @param options Configuration for unsaved changes detection
+     * @returns The instance of this class for chaining.
+     */
+    setUnsavedChangesDetection(options: UnsavedChangesOptions): this;
+    /**
+     * Adds custom CSS classes to the dialog element.
+     * These classes will be added to the dialog element when it is created.
+     *
+     * @param classes The CSS classes to add to the dialog element.
+     * @returns The instance of this class for chaining.
+     */
+    setClasses(classes: string[]): this;
+    /**
+     * Sets the body of the dialog. It is not used by default, but can be set to add custom content.
+     * The body will be added to the dialog element.
+     *
+     * @param body The body element to set.
+     * @returns The instance of this class for chaining.
+     */
+    setBody(body: HTMLElement): this;
+    /**
+     * Sets the root element to render the dialog into.
+     * By default the dialog is rendered into the document body.
+     *
+     * @param renderRoot The root element to render the dialog into.
+     * @returns The instance of this class for chaining.
+     */
+    setRenderRoot(renderRoot: HTMLElement): this;
+    /**
+     * Sets the dialog to be modal.
+     * When set to true, the dialog will be rendered as a modal dialog.
+     * The dialog will block interaction with the rest of the page until it is closed.
+     *
+     * @param modal When true, the dialog will be rendered as a modal dialog.
+     * @returns The instance of this class for chaining.
+     */
+    setModal(modal: boolean): this;
+    /**
+     * Creates the dialog and returns the instance of it.
+     * The dialog is not yet added to the DOM nor it is opened.
+     *
+     * @returns The instance of the dialog class.
+     */
+    build(): UiDialogElement;
+    /**
+     * Creates the dialog by calling the `build()` function,
+     * sets the `dialog` property, appends it to the body,
+     * and finally opens the dialog as modal.
+     *
+     * This method does not return `this` as you can't manipulate the dialog anymore.
+     */
+    open(): void;
+    /**
+     * Closes the dialog. The dialog behaves like the a negative action was triggered.
+     */
+    close(): void;
+    private handleActivityDestroy;
+    private handleActivityPause;
+    private handleActivityResume;
+    /**
+     * Handles the cancelable 'closing' event to check for unsaved changes
+     */
+    private handleDialogClosing;
+    /**
+     * Shows a warning dialog when there are unsaved changes
+     */
+    showUnsavedChangesWarning(): void;
+    /**
+     * Forces the dialog to close without checking for unsaved changes
+     */
+    protected forceClose(): void;
+    protected handleDialogClosed(event: Event): void;
+    /**
+     * Removes the dialog from the DOM and removes all listeners.
+     * The dialog does not call any lifecycle methods.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=DialogBuilder.d.ts.map

package/build/src/builders/DialogBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DialogBuilder.d.ts","sourceRoot":"","sources":["../../../src/builders/DialogBuilder.ts"],"names":[],"mappings":"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"}