@kekonic/diagrams-element 1.0.0-rc.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kekonic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# @kekonic/diagrams-element
+
+Lit web components for embedding KDiagram diagrams in any page — no React required.
+
+## Install
+
+```bash
+pnpm add @kekonic/diagrams-element @kekonic/diagrams
+```
+
+Import the element once in your bundled app:
+
+```ts
+import "@kekonic/diagrams-element";
+```
+
+The component carries its diagram styles. Import `@kekonic/diagrams/theme.css` only for host
+CSS variable overrides. For a no-build HTML page, load the package through an ESM CDN; browsers do
+not resolve bare npm package names or `node_modules` URLs directly.
+
+## `<k-diagram>`
+
+```html
+<k-diagram id="checkout" theme="auto" height="420"></k-diagram>
+
+<script type="module">
+  const diagram = document.querySelector("#checkout");
+  diagram.source = `diagram {
+    direction LR
+    api: gateway "API"
+    checkout: service "Checkout"
+    api -> checkout
+  }`;
+</script>
+```
+
+Assign multiline source through the JavaScript property rather than escaping it into an HTML
+attribute.
+
+### No-build CDN
+
+Import the published package directly in a modern browser:
+
+```html
+<k-diagram id="checkout" theme="auto" height="420"></k-diagram>
+
+<script type="module">
+  import "https://esm.sh/@kekonic/diagrams-element@x.y.z";
+
+  const diagram = document.querySelector("#checkout");
+  diagram.source = `diagram {
+    api: gateway "API"
+    checkout: service "Checkout"
+    api -> checkout
+  }`;
+</script>
+```
+
+Replace `x.y.z` with the package version you have chosen and pin it in CDN URLs. Prefer an installed
+dependency and lockfile for application builds.
+
+### Attributes / properties
+
+| Name                 | Type                                        | Default  | Notes                                              |
+| -------------------- | ------------------------------------------- | -------- | -------------------------------------------------- |
+| `source`             | string                                      | `""`     | KDiagram source. Updates call `controller.update`. |
+| `theme`              | `"dark"` \| `"light"` \| `"auto"` \| string | `"auto"` | `"auto"` follows `html[data-theme]`.               |
+| `height`             | string \| number                            | `420`    | Viewport height (`px` if number).                  |
+| `frameless`          | boolean                                     | `false`  | Remove the host border and panel background.       |
+| `show-theme-toggle`  | boolean                                     | `true`   | Set `"false"` to hide.                             |
+| `show-view-controls` | boolean                                     | `true`   | Zoom / fit / fullscreen.                           |
+| `show-stats`         | boolean                                     | `false`  | Compact layout stats badge.                        |
+| `animation-controls` | boolean                                     | `true`   | Playback controls when animations exist.           |
+| `animation`          | string                                      | first    | Preferred animation name or ID.                    |
+| `autoplay`           | boolean                                     | `false`  | Begin playback after the first render.             |
+| `loop`               | boolean                                     | `false`  | Loop the selected animation.                       |
+
+### Methods
+
+| Method                   | Notes                                   |
+| ------------------------ | --------------------------------------- |
+| `fit()`                  | Fit diagram to the viewport             |
+| `zoomIn()` / `zoomOut()` | View controls                           |
+| `resetView()`            | Reset pan/zoom                          |
+| `ready()`                | Resolves when the first render finishes |
+
+Same controller as `KDiagram.renderToElement` — pan, zoom, and theme swaps without remounting.
+Built-in controls fade after brief pointer or keyboard inactivity, like video-player controls. They
+return on activity and remain visible while a control has keyboard focus.
+
+Use `frameless` for a diagram that should sit directly in a page composition. It removes the host
+border and panel background without changing control settings.
+
+Docs: [Web component](https://diagrams.kekonic.com/publish/web-component/).

package/dist/index.d.mts

@@ -0,0 +1,129 @@
+import { LitElement, PropertyValues, TemplateResult } from "lit";
+import { InteractiveRenderOptions, InteractiveRenderOptions as InteractiveRenderOptions$1, ThemeMode, ThemeMode as ThemeMode$1 } from "@kekonic/diagrams";
+
+//#region src/k-diagram.d.ts
+/**
+ * Interactive Kekonic Diagrams diagram as a Lit custom element.
+ * Wraps `KDiagram.renderToElement` — pan/zoom, theme, live `source` updates.
+ */
+declare class KDiagramElement extends LitElement {
+  #private;
+  static properties: {
+    source: {
+      type: StringConstructor;
+    };
+    theme: {
+      type: StringConstructor;
+    };
+    height: {};
+    frameless: {
+      type: BooleanConstructor;
+      converter: {
+        fromAttribute: (value: string | null) => boolean;
+        toAttribute: (value: boolean) => "false" | "";
+      };
+      reflect: boolean;
+    };
+    showThemeToggle: {
+      type: BooleanConstructor;
+      attribute: string;
+      converter: {
+        fromAttribute: (value: string | null) => boolean;
+        toAttribute: (value: boolean) => "false" | "";
+      };
+    };
+    showViewControls: {
+      type: BooleanConstructor;
+      attribute: string;
+      converter: {
+        fromAttribute: (value: string | null) => boolean;
+        toAttribute: (value: boolean) => "false" | "";
+      };
+    };
+    showStats: {
+      type: BooleanConstructor;
+      attribute: string;
+      converter: {
+        fromAttribute: (value: string | null) => boolean;
+        toAttribute: (value: boolean) => "false" | "";
+      };
+    };
+    showAnimationControls: {
+      type: BooleanConstructor;
+      attribute: string;
+      converter: {
+        fromAttribute: (value: string | null) => boolean;
+        toAttribute: (value: boolean) => "false" | "";
+      };
+    };
+    autoplay: {
+      type: BooleanConstructor;
+      converter: {
+        fromAttribute: (value: string | null) => boolean;
+        toAttribute: (value: boolean) => "false" | "";
+      };
+    };
+    animationLoop: {
+      type: BooleanConstructor;
+      attribute: string;
+      converter: {
+        fromAttribute: (value: string | null) => boolean;
+        toAttribute: (value: boolean) => "false" | "";
+      };
+    };
+    animation: {
+      type: StringConstructor;
+    };
+    options: {
+      attribute: boolean;
+    };
+  };
+  static styles: import("lit").CSSResult;
+  source: string;
+  theme: ThemeMode$1 | "auto";
+  height: string | number;
+  /** Remove the host border and panel background for ambient or page-level compositions. */
+  frameless: boolean;
+  showThemeToggle: boolean;
+  showViewControls: boolean;
+  showStats: boolean;
+  /** Animation chrome when an animation exists (auto or authored). Default on. */
+  showAnimationControls: boolean;
+  autoplay: boolean;
+  animationLoop: boolean;
+  /** Preferred authored animation name or id. */
+  animation: string;
+  options?: Omit<InteractiveRenderOptions$1, "theme">;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  firstUpdated(): void;
+  updated(changed: PropertyValues): void;
+  /** Resolves when the first interactive render finishes. */
+  ready(): Promise<void>;
+  fit(): void;
+  zoomIn(): void;
+  zoomOut(): void;
+  resetView(): void;
+  /** Interactive animation controller (auto path or authored blocks). */
+  get animations(): import("@kekonic/diagrams-core").AnimationController | undefined;
+  /**
+   * Re-apply the current theme name (picks up `registerTheme` token updates
+   * even when the theme id is unchanged).
+   */
+  refreshTheme(): Promise<void>;
+  render(): TemplateResult<1>;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    "k-diagram": KDiagramElement;
+  }
+}
+//#endregion
+//#region src/index.d.ts
+/** Tag name for `<k-diagram>`. */
+declare const K_DIAGRAM_TAG = "k-diagram";
+/** Register `<k-diagram>` (idempotent). Called on package import. */
+declare function registerKDiagramElements(): void;
+//#endregion
+export { type InteractiveRenderOptions, KDiagramElement, K_DIAGRAM_TAG, type ThemeMode, registerKDiagramElements };
+//# sourceMappingURL=index.d.mts.map