@kraft.stitch/angular 0.0.3 → 0.0.4-beta.1

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,41 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm run build
+      - name: Publish stable release
+        if: ${{ !github.event.release.prerelease }}
+        run: npm publish --access public
+
+      - name: Publish pre-release
+        if: ${{ github.event.release.prerelease }}
+        run: npm publish --access public --tag beta
+     # - run: npm publish ./dist --access public

package/README.md

@@ -94,8 +94,4 @@ Your feedback, suggestions, and contributions help improve KSPack.
 
 **Made with ❤️ by @kraft.stitch**
 
----
-
-## Keywords
 
-Angular, React, UI Components, Design System, Component Library, Forms, Navigation, Layout, Notifications, Inputs, Dropdowns, Calendars, TypeScript, 

package/ng-package.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://raw.githubusercontent.com/ng-packagr/ng-packagr/main/ng-package.schema.json",
+  "dest": "dist",
+  "allowedNonPeerDependencies": [
+    "@kraft.stitch/core"
+  ],
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  }
+}

package/package.json

@@ -1,30 +1,39 @@
 {
   "name": "@kraft.stitch/angular",
-  "version": "0.0.3",
+  "version": "0.0.4-beta.1",
   "description": "Hand-written Angular wrapper for the <ks-button> Stencil custom element from @kraft.stitch/core — proof-of-concept for the WebComponents wrapper pattern (core in Stencil, framework-idiomatic Input/Output/DI in the wrapper).",
   "license": "MIT",
-  "main": "src/public-api.ts",
-  "types": "src/public-api.ts",
-  "peerDependencies": {
+  "keywords": [
+    "ks-ui",
+    "kraft-stitch",
+    "ui",
+    "ui-components",
+    "component-library",
+    "design-system",
+    "web-components",
+    "stencil",
+    "angular",
+    "react"
+  ],
+  "scripts": {
+    "build": "ng-packagr -p ng-package.json",
+    "pack": "npm run build && cd dist && npm pack"
+  },
+  "peerDependencies": { 
     "@angular/core": "^21.2.0 || ^22.0.0",
     "@angular/common": "^21.2.0 || ^22.0.0",
     "@angular/forms": "^21.2.0 || ^22.0.0"
   },
   "dependencies": {
-    "@kraft.stitch/core": "^0.0.2",
-    "tslib": "^2.3.0"
+    "@kraft.stitch/core": "^0.0.3"
   },
-  "sideEffects": false,
-  "module": "fesm2022/kraft.stitch-angular.mjs",
-  "typings": "types/kraft.stitch-angular.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./types/kraft.stitch-angular.d.ts",
-      "default": "./fesm2022/kraft.stitch-angular.mjs"
-    }
+  "devDependencies": {
+    "@angular/common": "^21.2.0",
+    "@angular/compiler-cli": "^21.2.0",
+    "@angular/core": "^21.2.0",
+    "@angular/forms": "^21.2.0",
+    "ng-packagr": "^21.2.0",
+    "typescript": "~5.9.2"
   },
-  "type": "module"
-}
+  "sideEffects": false
+}

package/src/lib/Buttons/button/button.ts

@@ -0,0 +1,152 @@
+// Side-effect import: registers the `ks-button` tag in the browser's
+// CustomElementRegistry (via Stencil's `auto-define-custom-elements`
+// behavior in `core/stencil.config.ts`). Nothing in THIS file renders the
+// button — see the class doc comment below for exactly what does.
+import '@kraft.stitch/core/dist/components/ks-button.js';
+
+import { ChangeDetectionStrategy, Component, DestroyRef, ElementRef, effect, inject, input, output } from '@angular/core';
+import type { KsBaseSize, KsVariant } from '@kraft.stitch/core';
+
+/** DOM shape of the real `<ks-button>` custom element, typed for the wrapper. */
+type KsButtonElement = HTMLElement & {
+  icon: string;
+  name: string;
+  variant: KsVariant;
+  size: KsBaseSize;
+  isRounded: boolean;
+  disabled: boolean;
+};
+
+/**
+ * Angular wrapper around the `<ks-button>` Stencil custom element.
+ *
+ * ## How this actually renders a button (no markup lives in this file)
+ *
+ * 1. A parent template writes `<ks-button name="Save" (ksClick)="save()">`.
+ * 2. Angular's renderer creates that host node with
+ *    `document.createElement('ks-button')`. Because the side-effect import
+ *    above already ran `customElements.define('ks-button', ...)`, the
+ *    **browser itself** immediately upgrades that node into an instance of
+ *    Stencil's compiled `KsButton` class — this is standard Custom Elements
+ *    behavior, nothing Angular-specific.
+ * 3. That upgrade runs Stencil's `connectedCallback` → `render()`, which
+ *    injects the real `<button>…</button>` markup as children of the host
+ *    node. This happens **regardless of Angular** — it's the same thing
+ *    that would happen if you dropped `<ks-button>` in a plain HTML file.
+ * 4. `KsButtonComponent` (this class) is a *second, independent* thing
+ *    attached to that same host node — Angular doesn't care that the node
+ *    is also a custom element instance. Its only job is translation:
+ *    push signal-input values onto the element's real DOM properties, and
+ *    re-emit the native `clicked` DOM event as an Angular `output()`.
+ *
+ * `template: ''` (no `<ng-content>`) is intentional: `ks-button`'s Stencil
+ * `render()` has no `<slot>`, so there is nothing to project — content
+ * written between `<ks-button>` tags wouldn't be displayed by the real
+ * component anyway. Content projection would only make sense here if the
+ * wrapped Stencil component actually declared a `<slot>`.
+ *
+ * ## Why the output is called `ksClick`, NOT `clicked`
+ *
+ * `<ks-button>` (the Stencil element) dispatches a **native** DOM
+ * `CustomEvent` literally named `clicked` on the host node. It is tempting
+ * to expose the wrapper's own output using that exact same name so the
+ * public API "mirrors" the native event — but doing so creates a **name
+ * collision** that makes the event fire twice from a parent template such
+ * as `<ks-button (clicked)="log($event)">`:
+ *
+ * For *any* event binding in a template, Ivy's `ɵɵlistener` instruction
+ * does two things whenever the bound name also happens to match a
+ * directive/component **output** on that element (`tNode.outputs[name]`):
+ * 1. It subscribes the template's handler to that output (`output.emit()`
+ *    calls it).
+ * 2. It **also** attaches a genuine `addEventListener(name, …)` straight
+ *    onto the host DOM node for that same literal name, independent of
+ *    step 1 — Ivy can't know whether the name is "just" an output or also
+ *    a real DOM event some element in the tree might dispatch, so it wires
+ *    both to be safe.
+ *
+ * If the output were named `clicked`, both of those fire for the *same*
+ * underlying interaction here: (1) our own `this.ksClick.emit(...)` call
+ * below invokes the template handler once, and (2) the raw native
+ * `clicked` `CustomEvent` that `<ks-button>` dispatches on the host node
+ * is picked up by Ivy's own native listener from step 2 and invokes the
+ * *same* template handler a second time — with a different, unwrapped
+ * event object. (An earlier attempt at fixing this used
+ * `@HostListener('clicked', ['$event'])`, which hits the same
+ * `tNode.outputs['clicked']` check and instead causes *infinite emit
+ * recursion*, since the host listener itself becomes a subscriber of the
+ * output it emits on.)
+ *
+ * Naming the output `ksClick` (no relation to any real DOM event name)
+ * removes the collision entirely: a parent writes
+ * `<ks-button (ksClick)="log($event)">`, Ivy subscribes that to our
+ * output, and the phantom native `addEventListener('ksClick', …)` it also
+ * attaches never fires because no such DOM event exists. Only the manual
+ * `addEventListener('clicked', …)` below — on the *internal* native event
+ * name, never referenced in any template — observes the real click and
+ * re-emits it once through `ksClick`. (This mirrors how libraries like
+ * Ionic prefix outputs, e.g. `ionChange` instead of `change`, for exactly
+ * this reason.)
+ */
+@Component({
+  selector: 'ks-button',
+  standalone: true,
+  template: '',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KsButtonComponent {
+  private readonly el: KsButtonElement;
+
+  /** Icon class string (e.g. Material Icon or Font Awesome class) */
+  readonly icon = input('');
+
+  /** Button label text */
+  readonly name = input('');
+
+  /** Visual style variant */
+  readonly variant = input<KsVariant>('brand');
+
+  /** Size */
+  readonly size = input<KsBaseSize>('md');
+
+  /** Renders the button with fully-rounded pill corners */
+  readonly isRounded = input(false);
+
+  /** Disables the button */
+  readonly disabled = input(false);
+
+  /**
+   * Emits the `MouseEvent` from the native `clicked` `CustomEvent`
+   * dispatched by `<ks-button>`. Deliberately NOT named `clicked` — see
+   * the class doc comment above for why that would fire this event twice.
+   */
+  readonly ksClick = output<MouseEvent>();
+
+  constructor(ref: ElementRef<KsButtonElement>) {
+    this.el = ref.nativeElement;
+
+    // Each signal input gets its own effect so only the properties that
+    // actually changed are written back to the DOM. Stencil's own
+    // `@Prop()` watchers take it from there and re-render the button.
+    effect(() => (this.el.icon = this.icon()));
+    effect(() => (this.el.name = this.name()));
+    effect(() => (this.el.variant = this.variant()));
+    effect(() => (this.el.size = this.size()));
+    effect(() => (this.el.isRounded = this.isRounded()));
+    effect(() => (this.el.disabled = this.disabled()));
+
+    // Attached manually (NOT `@HostListener`) to the *internal* native
+    // event name `clicked`, which is never referenced by name in any
+    // Angular template (`ksClick` is what templates bind to instead) — so
+    // there is no `tNode.outputs` name collision for Ivy to double-wire.
+    // zone.js's patched `addEventListener` means this still runs inside
+    // the Angular zone, so no manual `NgZone.run()` is needed, and change
+    // detection still runs after `emit()` below.
+    const onNativeClicked = (event: Event): void => {
+      this.ksClick.emit((event as CustomEvent<MouseEvent>).detail);
+      event.preventDefault();
+    };
+    this.el.addEventListener('clicked', onNativeClicked);
+    inject(DestroyRef).onDestroy(() => this.el.removeEventListener('clicked', onNativeClicked));
+  }
+}

package/src/lib/Buttons/button-group/button-group.ts

@@ -0,0 +1,129 @@
+// Side-effect import: registers the `ks-button-group` tag in the browser's
+// CustomElementRegistry — see `button/button.ts` for the full explanation of
+// this pattern (Stencil owns rendering, this class only translates
+// Angular-idiomatic Input/Output into DOM property writes + event listeners).
+import '@kraft.stitch/core/dist/components/ks-button-group.js';
+
+import { ChangeDetectionStrategy, Component, DestroyRef, ElementRef, effect, inject, input, output } from '@angular/core';
+import type { KsBaseSize, KsBaseVariant } from '@kraft.stitch/core';
+
+/**
+ * Mirrors `KsButtonGroupItem` exported by
+ * `core/src/components/Buttons/button-group/button-group.tsx`.
+ *
+ * Duplicated here (instead of importing it from `@kraft.stitch/core`) because that
+ * package's root barrel (`core/src/index.ts`) is still being assembled and
+ * does not yet reliably re-export every per-component type — only the
+ * shared enums in `ks-ui.types` (`KsBaseSize`, `KsBaseVariant`, `KsVariant`,
+ * imported below) are stable to depend on today. Keep this in sync with the
+ * Stencil source if its shape changes.
+ */
+export interface KsButtonGroupItem {
+  key: string;
+  label?: string;
+  icon?: string;
+  disabled?: boolean;
+}
+
+export type KsButtonGroupDisplayStyle = 'default' | 'switch';
+
+/** DOM shape of the real `<ks-button-group>` custom element, typed for the wrapper. */
+type KsButtonGroupElement = HTMLElement & {
+  buttons: KsButtonGroupItem[];
+  variant: KsBaseVariant;
+  size: KsBaseSize;
+  displayStyle: KsButtonGroupDisplayStyle;
+  multi: boolean;
+  selectable: boolean;
+  disabled: boolean;
+};
+
+/**
+ * Angular wrapper around the `<ks-button-group>` Stencil custom element.
+ *
+ * `template: ''` — the Stencil `render()` for this element has no `<slot>`,
+ * so there is nothing for this wrapper to project; every button is
+ * generated from the `buttons` input.
+ *
+ * ## Output naming
+ * The native element dispatches DOM `CustomEvent`s named `clicked` and
+ * `selectionChanged`. Both outputs below are renamed with a `ks` prefix
+ * (`ksClick`, `ksSelectionChange`) rather than reusing those exact strings.
+ * Doing so is required, not just cosmetic: for a template binding such as
+ * `<ks-button-group (clicked)="...">`, Angular's `ɵɵlistener` instruction
+ * *always* attaches a raw `addEventListener('clicked', …)` to the host
+ * element in addition to subscribing to a same-named component output —
+ * this is unconditional for element nodes (see
+ * `packages/core/src/render3/instructions/listener.ts` →
+ * `listenerInternal`), not something a custom-elements schema can opt out
+ * of. With a same-named output, the parent handler would therefore run
+ * *twice* per interaction — once via our own unwrapped `.emit()` call, once
+ * via Angular's own raw listener receiving the untouched `CustomEvent`
+ * (defeating the "no `event.detail`" requirement). Prefixing every output
+ * with `ks` guarantees the literal name never matches a real DOM event, so
+ * only our manual listener (below) ever observes it. See `button/button.ts`
+ * for the original write-up of this same issue.
+ */
+@Component({
+  selector: 'ks-button-group',
+  standalone: true,
+  template: '',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KsButtonGroupComponent {
+  private readonly el: KsButtonGroupElement;
+
+  /** The buttons to render */
+  readonly buttons = input<KsButtonGroupItem[]>([]);
+
+  /** Visual variant */
+  readonly variant = input<KsBaseVariant>('brand');
+
+  /** Size */
+  readonly size = input<KsBaseSize>('md');
+
+  /** Display style: 'default' (filled/outlined) or 'switch' (pill toggle) */
+  readonly displayStyle = input<KsButtonGroupDisplayStyle>('default');
+
+  /** Allow multiple selected buttons (toggle mode) */
+  readonly multi = input(false);
+
+  /** Toggle/selection mode — shows active state on click */
+  readonly selectable = input(false);
+
+  /** Disables the entire group */
+  readonly disabled = input(false);
+
+  /** Emits the clicked button's `key`. From the native `clicked` event. */
+  readonly ksClick = output<string>();
+
+  /** Emits the current selection when `selectable`. From the native `selectionChanged` event. */
+  readonly ksSelectionChange = output<string[]>();
+
+  constructor(ref: ElementRef<KsButtonGroupElement>) {
+    this.el = ref.nativeElement;
+
+    effect(() => (this.el.buttons = this.buttons()));
+    effect(() => (this.el.variant = this.variant()));
+    effect(() => (this.el.size = this.size()));
+    effect(() => (this.el.displayStyle = this.displayStyle()));
+    effect(() => (this.el.multi = this.multi()));
+    effect(() => (this.el.selectable = this.selectable()));
+    effect(() => (this.el.disabled = this.disabled()));
+
+    const onNativeClicked = (event: Event): void => {
+      this.ksClick.emit((event as CustomEvent<string>).detail);
+    };
+    const onNativeSelectionChanged = (event: Event): void => {
+      this.ksSelectionChange.emit((event as CustomEvent<string[]>).detail);
+    };
+
+    this.el.addEventListener('clicked', onNativeClicked);
+    this.el.addEventListener('selectionChanged', onNativeSelectionChanged);
+
+    inject(DestroyRef).onDestroy(() => {
+      this.el.removeEventListener('clicked', onNativeClicked);
+      this.el.removeEventListener('selectionChanged', onNativeSelectionChanged);
+    });
+  }
+}

package/src/lib/Buttons/chips/chips.ts

@@ -0,0 +1,131 @@
+// Side-effect import: registers the `ks-chips` tag — see `button/button.ts`
+// for the full explanation of this pattern.
+import '@kraft.stitch/core/dist/components/ks-chips.js';
+
+import { ChangeDetectionStrategy, Component, DestroyRef, ElementRef, effect, inject, input, output } from '@angular/core';
+import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
+import type { KsBaseSize } from '@kraft.stitch/core';
+
+/**
+ * Mirrors `KsChipOption` exported by
+ * `core/src/components/Buttons/chips/chips.tsx`. Duplicated locally — see
+ * the note in `button-group/button-group.ts` on why component-specific
+ * shapes aren't imported from `@kraft.stitch/core`'s root barrel yet.
+ */
+export interface KsChipOption {
+  value: string | number;
+  label: string;
+  icon?: string;
+  disabled?: boolean;
+}
+
+export type KsChipsValue = (string | number) | (string | number)[] | null;
+
+/** DOM shape of the real `<ks-chips>` custom element, typed for the wrapper. */
+type KsChipsElement = HTMLElement & {
+  options: KsChipOption[];
+  multi: boolean;
+  label: string;
+  size: KsBaseSize;
+  isRounded: boolean;
+  disabled: boolean;
+  value: KsChipsValue;
+  writeValue(val: KsChipsValue): Promise<void>;
+};
+
+/**
+ * Angular wrapper around the `<ks-chips>` Stencil custom element.
+ *
+ * ## Two-way binding
+ * The Stencil source's own doc comment says Angular forms integration
+ * (`ngModel`/`formControl`) would be "provided later by the generated
+ * output-target wrappers" — this is that wrapper. Rather than trying to
+ * reuse Angular's `[(value)]` banana-box sugar (which would require an
+ * output literally named `valueChange`, colliding with the native
+ * `valueChange` `CustomEvent` the element already dispatches — see
+ * `button/button.ts` for why that double-fires), two-way binding is
+ * implemented the idiomatic Angular way: `ControlValueAccessor`. Bind with
+ * `[(ngModel)]="fruit"` or `formControlName="fruit"` and it Just Works,
+ * because `NgModel`/`FormControlDirective` talk to `writeValue` /
+ * `registerOnChange` directly through DI — no template event-name matching
+ * involved, so there's no collision to worry about.
+ *
+ * For plain (non-forms) two-way use, bind explicitly instead:
+ * `[value]="fruit" (ksValueChange)="fruit = $event"`.
+ *
+ * `template: ''` — no `<slot>` in the wrapped Stencil render, nothing to project.
+ */
+@Component({
+  selector: 'ks-chips',
+  standalone: true,
+  template: '',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  providers: [{ provide: NG_VALUE_ACCESSOR, useExisting: KsChipsComponent, multi: true }],
+})
+export class KsChipsComponent implements ControlValueAccessor {
+  private readonly el: KsChipsElement;
+  private onChange: (value: KsChipsValue) => void = () => {};
+  private onTouched: () => void = () => {};
+
+  /** Full list of chip options */
+  readonly options = input<KsChipOption[]>([]);
+
+  /** Allow selecting multiple chips */
+  readonly multi = input(false);
+
+  /** Field label */
+  readonly label = input('');
+
+  /** Size */
+  readonly size = input<KsBaseSize>('md');
+
+  /** Renders chips with fully-rounded pill corners */
+  readonly isRounded = input(true);
+
+  /** Disabled state */
+  readonly disabled = input(false);
+
+  /** Initial/controlled value for plain (non-forms) usage. Prefer `[(ngModel)]` / `formControlName` when inside a form. */
+  readonly value = input<KsChipsValue>(null);
+
+  /** Emits the newly-selected value(s). From the native `valueChange` event. */
+  readonly ksValueChange = output<KsChipsValue>();
+
+  constructor(ref: ElementRef<KsChipsElement>) {
+    this.el = ref.nativeElement;
+
+    effect(() => (this.el.options = this.options()));
+    effect(() => (this.el.multi = this.multi()));
+    effect(() => (this.el.label = this.label()));
+    effect(() => (this.el.size = this.size()));
+    effect(() => (this.el.isRounded = this.isRounded()));
+    effect(() => (this.el.disabled = this.disabled()));
+    effect(() => void this.el.writeValue(this.value()));
+
+    const onNativeValueChange = (event: Event): void => {
+      const detail = (event as CustomEvent<KsChipsValue>).detail;
+      this.ksValueChange.emit(detail);
+      this.onChange(detail);
+      this.onTouched();
+    };
+    this.el.addEventListener('valueChange', onNativeValueChange);
+    inject(DestroyRef).onDestroy(() => this.el.removeEventListener('valueChange', onNativeValueChange));
+  }
+
+  /** `ControlValueAccessor` — called by `ngModel`/`formControl` to push a value in. */
+  writeValue(value: KsChipsValue): void {
+    void this.el.writeValue(value ?? null);
+  }
+
+  registerOnChange(fn: (value: KsChipsValue) => void): void {
+    this.onChange = fn;
+  }
+
+  registerOnTouched(fn: () => void): void {
+    this.onTouched = fn;
+  }
+
+  setDisabledState(isDisabled: boolean): void {
+    this.el.disabled = isDisabled;
+  }
+}

package/src/lib/Buttons/fab/fab.ts

@@ -0,0 +1,96 @@
+// Side-effect import: registers the `ks-fab` tag — see `button/button.ts`
+// for the full explanation of this pattern.
+import '@kraft.stitch/core/dist/components/ks-fab.js';
+
+import { ChangeDetectionStrategy, Component, DestroyRef, ElementRef, effect, inject, input, output } from '@angular/core';
+import type { KsBaseSize, KsBaseVariant } from '@kraft.stitch/core';
+
+/**
+ * Mirrors `KsFabAction` / `KsFabPosition` exported by
+ * `core/src/components/Buttons/fab/fab.tsx`. Duplicated locally — see the
+ * note in `button-group/button-group.ts` for why.
+ */
+export interface KsFabAction {
+  key: string;
+  icon: string;
+  label?: string;
+  variant?: KsBaseVariant;
+}
+
+export type KsFabPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+
+/** DOM shape of the real `<ks-fab>` custom element, typed for the wrapper. */
+type KsFabElement = HTMLElement & {
+  icon: string;
+  label: string;
+  variant: KsBaseVariant;
+  size: KsBaseSize;
+  actions: KsFabAction[];
+  disabled: boolean;
+  position: KsFabPosition;
+  appendToParent: boolean;
+};
+
+/**
+ * Angular wrapper around the `<ks-fab>` Stencil custom element.
+ *
+ * `ksClick` is renamed away from the native `clicked` event name for the
+ * same double-fire reason documented in `button/button.ts` and
+ * `button-group/button-group.ts`. `template: ''` — no `<slot>` in the
+ * wrapped Stencil render.
+ */
+@Component({
+  selector: 'ks-fab',
+  standalone: true,
+  template: '',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KsFabComponent {
+  private readonly el: KsFabElement;
+
+  /** Icon for the main FAB button */
+  readonly icon = input('');
+
+  /** Accessible label / tooltip */
+  readonly label = input('');
+
+  /** Variant */
+  readonly variant = input<KsBaseVariant>('brand');
+
+  /** Size */
+  readonly size = input<KsBaseSize>('md');
+
+  /** Speed-dial actions shown on expand */
+  readonly actions = input<KsFabAction[]>([]);
+
+  /** Disabled */
+  readonly disabled = input(false);
+
+  /** Corner to anchor the FAB inside its nearest positioned container */
+  readonly position = input<KsFabPosition>('bottom-right');
+
+  /** When true (default), positions `absolute` inside the nearest positioned ancestor; when false, `fixed` to the viewport */
+  readonly appendToParent = input(true);
+
+  /** Emits `'main'` for the main button, or a speed-dial action's `key`. From the native `clicked` event. */
+  readonly ksClick = output<string>();
+
+  constructor(ref: ElementRef<KsFabElement>) {
+    this.el = ref.nativeElement;
+
+    effect(() => (this.el.icon = this.icon()));
+    effect(() => (this.el.label = this.label()));
+    effect(() => (this.el.variant = this.variant()));
+    effect(() => (this.el.size = this.size()));
+    effect(() => (this.el.actions = this.actions()));
+    effect(() => (this.el.disabled = this.disabled()));
+    effect(() => (this.el.position = this.position()));
+    effect(() => (this.el.appendToParent = this.appendToParent()));
+
+    const onNativeClicked = (event: Event): void => {
+      this.ksClick.emit((event as CustomEvent<string>).detail);
+    };
+    this.el.addEventListener('clicked', onNativeClicked);
+    inject(DestroyRef).onDestroy(() => this.el.removeEventListener('clicked', onNativeClicked));
+  }
+}