@kouji-ui/core 0.0.4 → 0.1.1

package/src/tabs/tabs.ts

@@ -1,130 +1,364 @@
-import { Directive, computed, inject, input, model } from '@angular/core';
-import { KJ_TABS, KjTabsContext } from './tabs.context';
+import {
+  computed,
+  Directive,
+  effect,
+  ElementRef,
+  inject,
+  input,
+  model,
+  OnDestroy,
+  OnInit,
+  output,
+  signal,
+  Signal,
+  untracked,
+} from '@angular/core';
+import { KjRovingTabindex, KjRovingTabindexItemDirective } from '../a11y/roving-tabindex';
+import { KjDisabled } from '../primitives/interaction/disabled';
+import { KjFocusRing } from '../primitives/interaction/focus-ring';
+import {
+  KJ_TABS,
+  KjTabsActivationMode,
+  KjTabsContext,
+  KjTabsOrientation,
+} from './tabs.context';
+
+let kjTabsSeedCounter = 0;
+function nextSeed(): string {
+  // Try crypto.randomUUID where available (browser, jsdom 22+, node 19+).
+  // Fall back to a counter so SSR / older environments still produce a stable string.
+  const cryptoLike = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
+  if (cryptoLike?.randomUUID) return cryptoLike.randomUUID().slice(0, 8);
+  return `kj${(++kjTabsSeedCounter).toString(36)}`;
+}
 
 /**
- * Root tabs container. Manages active tab value.
+ * Root tabs container. Owns the active value, orientation, activation mode,
+ * and the registration list of child tabs/panels. Provides `KJ_TABS` to its
+ * descendants for ARIA wiring and selection coordination.
+ *
  * @example
  * ```html
- * <div kjTabs [(kjTabsValue)]="activeTab"><div kjTabList>...</div></div>
+ * <div kjTabs [(kjValue)]="active" kjOrientation="horizontal" kjActivationMode="automatic">
+ *   <div kjTabList>
+ *     <button kjTab kjTabValue="overview">Overview</button>
+ *     <button kjTab kjTabValue="billing">Billing</button>
+ *   </div>
+ *   <div kjTabPanel kjPanelValue="overview">…</div>
+ *   <div kjTabPanel kjPanelValue="billing">…</div>
+ * </div>
  * ```
+ * @doc-category Core/Navigation
  * @doc
- *  @doc-file tabs.example.ts
- *    ```typescript
- *       import { Component, signal } from '@angular/core';
- *       import { KjTabs, KjTabList, KjTab, KjTabPanel } from '@kouji-ui/core';
- *
- *       @Component({
- *         standalone: true,
- *         imports: [KjTabs, KjTabList, KjTab, KjTabPanel],
- *         styles: [`
- *           .tabs { background: #0c0c0c; padding: 2rem; }
- *           [kjTabList] { display: flex; border-bottom: 1px solid #1e1e1e; margin-bottom: 1.5rem; }
- *           [kjTab] { background: none; border: none; border-bottom: 2px solid transparent; color: #555; font-family: 'JetBrains Mono', monospace; font-size: 0.875rem; padding: 0.625rem 1.25rem; cursor: pointer; transition: color 0.15s, border-color 0.15s; margin-bottom: -1px; }
- *           [kjTab][aria-selected="true"] { color: #f0ede6; border-bottom-color: #b8f500; }
- *           [kjTab]:hover { color: #f0ede6; }
- *           [kjTabPanel] { color: #666; font-family: 'JetBrains Mono', monospace; font-size: 0.875rem; line-height: 1.6; }
- *           [hidden] { display: none; }
- *         `],
- *         template: `
- *           <div class="tabs">
- *             <div kjTabs [(kjTabsValue)]="activeTab" aria-label="Example tabs">
- *               <div kjTabList>
- *                 <button kjTab [kjTabValue]="'tab1'">Overview</button>
- *                 <button kjTab [kjTabValue]="'tab2'">API</button>
- *                 <button kjTab [kjTabValue]="'tab3'">Examples</button>
- *               </div>
- *               <div kjTabPanel [kjPanelFor]="'tab1'">The overview tab content goes here.</div>
- *               <div kjTabPanel [kjPanelFor]="'tab2'">API reference content goes here.</div>
- *               <div kjTabPanel [kjPanelFor]="'tab3'">Code examples go here.</div>
- *             </div>
- *           </div>
- *         `,
- *       })
- *       export class TabsExampleComponent {
- *         activeTab = signal('tab1');
- *       }
- *    ```
- * @category Core/Navigation
+ * @doc-name tabs
+ * @doc-description Unstyled tabs root with active-value, orientation, and activation mode for tab and panel children.
+ * @doc-is-main
  */
 @Directive({
   selector: '[kjTabs]',
   standalone: true,
   providers: [{ provide: KJ_TABS, useExisting: KjTabs }],
+  host: {
+    '[attr.data-orientation]': 'kjOrientation()',
+  },
 })
 export class KjTabs implements KjTabsContext {
-  /** Two-way bound active tab value. */
-  kjTabsValue = model<string>('');
+  /** Two-way bound active tab value. String-keyed; `''` means "no tab active yet". */
+  readonly kjValue = model<string>('');
+
+  /** Tabs orientation. Drives `aria-orientation` on the tablist and the arrow-key axis. */
+  readonly kjOrientation = input<KjTabsOrientation>('horizontal');
+
+  /**
+   * Activation mode per WAI-ARIA APG.
+   * - `'automatic'` (default): focus moves and the focused tab is activated immediately.
+   * - `'manual'`: focus moves only; Enter or Space activates the focused tab.
+   */
+  readonly kjActivationMode = input<KjTabsActivationMode>('automatic');
+
+  /** Read-only view of the active tab value. */
+  readonly value: Signal<string> = this.kjValue.asReadonly();
+
+  /** Read-only view of the orientation. */
+  readonly orientation: Signal<KjTabsOrientation> = this.kjOrientation;
+
+  /** Read-only view of the activation mode. */
+  readonly activationMode: Signal<KjTabsActivationMode> = this.kjActivationMode;
+
+  private readonly idSeed = nextSeed();
+
+  /** @internal Map of value → registered tab; keeps document order via insertion. */
+  private readonly _tabs = signal<readonly KjTab[]>([]);
+
+  /** Public read-only registration list, in document order. */
+  readonly tabs = this._tabs.asReadonly();
+
+  /** Currently resolved active tab (may be undefined when value matches no tab). */
+  readonly activeTab = computed<KjTab | undefined>(() =>
+    this._tabs().find((t) => t.kjTabValue() === this.kjValue()),
+  );
 
-  /** Read-only signal of the current active tab value. */
-  readonly value = this.kjTabsValue.asReadonly();
+  constructor() {
+    // Default-value reconciliation: when kjValue is unset (`''`) and at least one
+    // non-disabled tab is registered, activate the first non-disabled tab.
+    effect(() => {
+      const list = this._tabs();
+      const current = this.kjValue();
+      if (current === '' && list.length > 0) {
+        const first = untracked(() => list.find((t) => !t.kjTabDisabled()) ?? list[0]);
+        if (first) {
+          // Defer to avoid writing during a parent change-detection pass.
+          queueMicrotask(() => {
+            if (this.kjValue() === '') this.kjValue.set(first.kjTabValue());
+          });
+        }
+      }
+    });
+  }
+
+  /** @internal Called by `KjTab.ngOnInit` to register itself in document order. */
+  register(tab: KjTab): void {
+    this._tabs.update((list) => (list.includes(tab) ? list : [...list, tab]));
+  }
+
+  /** @internal Called by `KjTab` on destroy. */
+  unregister(tab: KjTab): void {
+    this._tabs.update((list) => list.filter((t) => t !== tab));
+  }
+
+  /** Returns whether the tab/panel pair for `value` is the active one. */
+  isActive(value: string): boolean {
+    return this.kjValue() === value;
+  }
+
+  /** Stable id for the tab element associated with `value`. */
+  tabId(value: string): string {
+    return `kj-tab-${value}-${this.idSeed}`;
+  }
+
+  /** Stable id for the panel element associated with `value`. */
+  panelId(value: string): string {
+    return `kj-panel-${value}-${this.idSeed}`;
+  }
+
+  /** Activates the tab/panel pair for `value`. No-op if the matching tab is disabled. */
+  select(value: string): void {
+    const target = this._tabs().find((t) => t.kjTabValue() === value);
+    if (target?.kjTabDisabled()) return;
+    if (this.kjValue() !== value) this.kjValue.set(value);
+  }
+
+  /** Imperative: advance to the next non-disabled tab. Clamps at the end. */
+  next(): void {
+    const list = this._tabs();
+    const idx = list.findIndex((t) => t.kjTabValue() === this.kjValue());
+    for (let i = idx + 1; i < list.length; i++) {
+      if (!list[i].kjTabDisabled()) {
+        this.select(list[i].kjTabValue());
+        return;
+      }
+    }
+  }
 
-  /** Activates the tab with the given value. */
-  activate(val: string): void {
-    this.kjTabsValue.set(val);
+  /** Imperative: advance to the previous non-disabled tab. Clamps at the start. */
+  previous(): void {
+    const list = this._tabs();
+    const idx = list.findIndex((t) => t.kjTabValue() === this.kjValue());
+    for (let i = idx - 1; i >= 0; i--) {
+      if (!list[i].kjTabDisabled()) {
+        this.select(list[i].kjTabValue());
+        return;
+      }
+    }
   }
 }
 
 /**
- * Container for tab triggers. Sets `role="tablist"`.
- * @category Core/Navigation
+ * Tab list container. Hosts `role="tablist"` + `aria-orientation` and composes
+ * `KjRovingTabindex` to manage the single-tab-stop arrow-key navigation.
+ *
+ * Orientation is read from the parent `KJ_TABS` context and forwarded to the
+ * roving primitive through its `kjRovingOrientation` input via a host binding
+ * on the exposed input.
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name tabs
  */
 @Directive({
   selector: '[kjTabList]',
   standalone: true,
-  host: { role: 'tablist' },
+  hostDirectives: [KjRovingTabindex],
+  host: {
+    '[attr.role]': '"tablist"',
+    '[attr.aria-orientation]': 'tabs.orientation()',
+    '[attr.data-orientation]': 'tabs.orientation()',
+  },
 })
-export class KjTabList {}
+export class KjTabList implements OnInit, OnDestroy {
+  /** @internal */
+  readonly tabs = inject(KJ_TABS);
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  private readonly keydownFilter = (event: KeyboardEvent): void => {
+    const orientation = this.tabs.orientation();
+    if (orientation === 'horizontal') {
+      if (event.key === 'ArrowUp' || event.key === 'ArrowDown') {
+        // Off-axis: prevent the composed KjRovingTabindex from acting.
+        event.stopImmediatePropagation();
+      }
+    } else if (orientation === 'vertical') {
+      if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
+        event.stopImmediatePropagation();
+      }
+    }
+  };
+
+  ngOnInit(): void {
+    // Capture phase + `addEventListener` directly on the host: this listener
+    // fires before the composed KjRovingTabindex's `(keydown)` host binding,
+    // so we can swallow off-axis arrow keys per the parent KjTabs orientation
+    // (the WAI-ARIA APG contract for tab strips).
+    this.el.nativeElement.addEventListener('keydown', this.keydownFilter, true);
+  }
+
+  ngOnDestroy(): void {
+    this.el.nativeElement.removeEventListener('keydown', this.keydownFilter, true);
+  }
+}
 
 /**
- * Individual tab trigger. Sets `role="tab"` and manages `aria-selected`.
- * @example `<button kjTab [kjTabValue]="'profile'">Profile</button>`
- * @category Core/Navigation
+ * Tab trigger. Hosts `role="tab"` + the ARIA wiring (`aria-selected`,
+ * `aria-controls`, `id`) and composes `KjRovingTabindexItem`, `KjFocusRing`
+ * and `KjDisabled`. Click activates the tab; Enter/Space activate (always
+ * honoured, required in manual mode); Delete fires `kjClose` when
+ * `kjClosable` is true.
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name tabs
  */
 @Directive({
   selector: '[kjTab]',
   standalone: true,
+  hostDirectives: [KjRovingTabindexItemDirective, KjFocusRing, KjDisabled],
   host: {
-    role: 'tab',
-    '[attr.aria-selected]': 'active().toString()',
-    '[attr.data-active]': 'active() ? "" : null',
-    '[attr.tabindex]': 'active() ? "0" : "-1"',
-    '(click)': 'activate()',
+    '[attr.role]': '"tab"',
+    '[attr.id]': 'tabs.tabId(kjTabValue())',
+    '[attr.aria-controls]': 'tabs.panelId(kjTabValue())',
+    '[attr.aria-selected]': 'isActive() ? "true" : "false"',
+    '[attr.aria-disabled]': 'kjTabDisabled() ? "true" : null',
+    '[attr.data-state]': 'isActive() ? "active" : "inactive"',
+    '[attr.data-disabled]': 'kjTabDisabled() ? "" : null',
+    '(click)': 'onClick()',
+    '(keydown)': 'onKeydown($event)',
+    '(focus)': 'onFocus()',
   },
 })
-export class KjTab {
-  private readonly ctx = inject(KJ_TABS);
+export class KjTab implements OnInit, OnDestroy {
+  /** @internal */
+  readonly tabs = inject(KJ_TABS) as KjTabs;
+  /** @internal Native host element. */
+  readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  /** Required string key wiring this tab to its corresponding panel. */
+  readonly kjTabValue = input.required<string>();
+
+  /** When true, the tab cannot be activated but remains in the focus ring. */
+  readonly kjTabDisabled = input<boolean>(false);
 
-  /** The value this tab represents. */
-  kjTabValue = input.required<string>();
+  /** When true, Delete on the focused tab fires `kjClose`. */
+  readonly kjClosable = input<boolean>(false);
 
-  /** Whether this tab is currently active. */
-  readonly active = computed(() => this.ctx.value() === this.kjTabValue());
+  /** Fires when the user closes this tab (Delete key). Emits the tab's value. */
+  readonly kjClose = output<string>();
 
-  /** Activates this tab by updating the shared context. */
-  activate(): void {
-    this.ctx.activate(this.kjTabValue());
+  /** Whether this tab is the currently active one. */
+  readonly isActive = computed(() => this.tabs.isActive(this.kjTabValue()));
+
+  ngOnInit(): void {
+    this.tabs.register(this);
+  }
+
+  ngOnDestroy(): void {
+    this.tabs.unregister(this);
+  }
+
+  /** @internal Click handler. */
+  onClick(): void {
+    if (this.kjTabDisabled()) return;
+    this.tabs.select(this.kjTabValue());
+  }
+
+  /** @internal Focus handler — activates immediately in `automatic` mode. */
+  onFocus(): void {
+    if (this.kjTabDisabled()) return;
+    if (this.tabs.activationMode() === 'automatic') {
+      this.tabs.select(this.kjTabValue());
+    }
+  }
+
+  /** @internal Keydown — Enter/Space activate (always honoured); Delete closes when closable. */
+  onKeydown(event: KeyboardEvent): void {
+    if (event.key === 'Enter' || event.key === ' ' || event.key === 'Spacebar') {
+      if (this.kjTabDisabled()) return;
+      event.preventDefault();
+      this.tabs.select(this.kjTabValue());
+      return;
+    }
+    if (event.key === 'Delete' && this.kjClosable()) {
+      event.preventDefault();
+      this.kjClose.emit(this.kjTabValue());
+      return;
+    }
   }
 }
 
 /**
- * Tab panel content. Hidden when not active.
- * @example `<div kjTabPanel [kjPanelFor]="'profile'">Profile content</div>`
- * @category Core/Navigation
+ * Tab panel. Hosts `role="tabpanel"` + `aria-labelledby` + `id` + `hidden`.
+ * Tracks first-activation history via `mounted`: it flips `true` on first
+ * activation and stays `true` thereafter, so consumers can gate the
+ * projected content with `@if (panel.mounted())` to implement the
+ * lazy-then-persistent mount posture from the analysis.
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name tabs
  */
 @Directive({
   selector: '[kjTabPanel]',
   standalone: true,
+  exportAs: 'kjTabPanel',
   host: {
-    role: 'tabpanel',
-    '[attr.hidden]': 'hidden() ? "" : null',
+    '[attr.role]': '"tabpanel"',
+    '[attr.id]': 'tabs.panelId(kjPanelValue())',
+    '[attr.aria-labelledby]': 'tabs.tabId(kjPanelValue())',
+    '[attr.hidden]': 'isActive() ? null : ""',
+    '[attr.data-state]': 'isActive() ? "active" : "inactive"',
   },
 })
 export class KjTabPanel {
-  private readonly ctx = inject(KJ_TABS);
+  /** @internal */
+  readonly tabs = inject(KJ_TABS);
+
+  /** Required string key wiring this panel to its corresponding tab. */
+  readonly kjPanelValue = input.required<string>();
 
-  /** The tab value this panel corresponds to. */
-  kjPanelFor = input.required<string>();
+  /** Whether this panel is the active one. */
+  readonly isActive = computed(() => this.tabs.isActive(this.kjPanelValue()));
 
-  /** Whether this panel is currently hidden. */
-  readonly hidden = computed(() => this.ctx.value() !== this.kjPanelFor());
+  private readonly _mounted = signal(false);
+
+  /**
+   * `true` after this panel has been activated at least once. Consumers wrap
+   * the panel's projected content in `@if (panel.mounted())` to mount the
+   * content lazily on first activation and keep it mounted thereafter.
+   */
+  readonly mounted = this._mounted.asReadonly();
+
+  constructor() {
+    effect(() => {
+      if (this.isActive() && !this._mounted()) this._mounted.set(true);
+    });
+  }
 }

package/src/tag/config.ts

@@ -0,0 +1,53 @@
+import { InjectionToken, Provider } from '@angular/core';
+
+/** Preset configuration consumed by `KjTag` via `bindPresets`. */
+export interface KjTagConfig {
+  variants: string[];
+  sizes: string[];
+  defaults: { variant: string; size: string };
+}
+
+/**
+ * Default Tag presets shipped by kouji-ui. Variant list is intentionally
+ * kept in lock-step with `KjBadge` (see analysis §"Variant parity with
+ * Badge") — a non-interactive Tag and a Badge with the same `kjVariant`
+ * must look identical.
+ */
+export const KJ_TAG_DEFAULTS: KjTagConfig = {
+  variants: [
+    'default',
+    'primary',
+    'secondary',
+    'success',
+    'warning',
+    'danger',
+    'info',
+    'outline',
+    'ghost',
+  ],
+  sizes: ['xs', 'sm', 'md', 'lg'],
+  defaults: { variant: 'default', size: 'md' },
+};
+
+/**
+ * DI token for the active Tag presets. Default factory yields
+ * `KJ_TAG_DEFAULTS`. Override via `provideKjTag(...)` at the application
+ * scope or at a component scope.
+ */
+export const KJ_TAG_CONFIG = new InjectionToken<KjTagConfig>('kj.tag.config', {
+  factory: () => KJ_TAG_DEFAULTS,
+});
+
+/**
+ * Configures the Tag presets for the enclosing injector. Replaces (does
+ * not merge) `variants` and `sizes`; spread `KJ_TAG_DEFAULTS.variants` to
+ * extend.
+ */
+export function provideKjTag(config: Partial<KjTagConfig>): Provider[] {
+  return [
+    {
+      provide: KJ_TAG_CONFIG,
+      useValue: { ...KJ_TAG_DEFAULTS, ...config },
+    },
+  ];
+}

package/src/tag/index.ts

@@ -0,0 +1,7 @@
+export { KjTag } from './tag';
+export { KjTagRemove } from './tag-remove';
+export { KjTagList } from './tag-list';
+export { KJ_TAG, KJ_TAG_LIST } from './tag.context';
+export type { KjTagContext, KjTagListContext, KjTagListRole } from './tag.context';
+export { KJ_TAG_CONFIG, KJ_TAG_DEFAULTS, provideKjTag } from './config';
+export type { KjTagConfig } from './config';

package/src/tag/tag-list.ts

@@ -0,0 +1,76 @@
+import { Directive, Signal, computed, input } from '@angular/core';
+import { KjRovingTabindex } from '../a11y/roving-tabindex';
+import { KJ_TAG_LIST, KjTagListContext, KjTagListRole } from './tag.context';
+
+/**
+ * Optional container that coordinates a group of `KjTag` chips. Provides
+ * the chip-group keyboard story (roving tabindex via `KjRovingTabindex`)
+ * and the ARIA wiring for the `listbox` / `grid` / `group` shapes called
+ * out in the analysis.
+ *
+ * Standalone tags work fine without this container — the container is the
+ * opt-in surface that turns a pile of independent chips into a single
+ * keyboardable composite.
+ *
+ * @example
+ * ```html
+ * <div kjTagList kjTagListRole="listbox" [kjTagListMultiple]="true" aria-label="Filters">
+ *   <span kjTag kjTagSelectable>One</span>
+ *   <span kjTag kjTagSelectable>Two</span>
+ * </div>
+ * ```
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name tag
+ */
+@Directive({
+  selector: '[kjTagList]',
+  standalone: true,
+  providers: [{ provide: KJ_TAG_LIST, useExisting: KjTagList }],
+  hostDirectives: [
+    { directive: KjRovingTabindex, inputs: ['kjRovingOrientation: kjTagListOrientation'] },
+  ],
+  host: {
+    '[attr.role]': 'kjTagListRole()',
+    '[attr.aria-orientation]': 'ariaOrientation()',
+    '[attr.aria-multiselectable]': 'ariaMultiSelectable()',
+    '[attr.aria-disabled]': 'kjTagListDisabled() ? "true" : null',
+    '[attr.tabindex]': 'kjTagListRole() !== "group" ? "-1" : null',
+  },
+})
+export class KjTagList implements KjTagListContext {
+  /** Container ARIA role — drives chip role selection (option / row / none). */
+  readonly kjTagListRole = input<KjTagListRole>('group');
+
+  /** Roving tabindex axis. Forwarded to `KjRovingTabindex`. */
+  readonly kjTagListOrientation = input<'horizontal' | 'vertical' | 'both'>('horizontal');
+
+  /** Only meaningful in `listbox` mode. Drives `aria-multiselectable`. */
+  readonly kjTagListMultiple = input(false);
+
+  /** Cascading disabled flag. Each chip's effective disabled OR-merges this. */
+  readonly kjTagListDisabled = input(false);
+
+  /** Read-only role view used by `KjTag` to compute its own role. */
+  readonly role: Signal<KjTagListRole> = this.kjTagListRole;
+
+  /** Read-only disabled view used by `KjTag` to merge into its effective disabled. */
+  readonly disabled: Signal<boolean> = this.kjTagListDisabled;
+
+  /** Read-only multi-selectable view (listbox-only meaning). */
+  readonly multiple: Signal<boolean> = this.kjTagListMultiple;
+
+  /** Only emit `aria-orientation` when the container has a real role. */
+  protected readonly ariaOrientation = computed<string | null>(() => {
+    if (this.kjTagListRole() === 'group') return null;
+    return this.kjTagListOrientation() === 'both'
+      ? 'horizontal'
+      : this.kjTagListOrientation();
+  });
+
+  /** `aria-multiselectable` only set in listbox mode. */
+  protected readonly ariaMultiSelectable = computed<string | null>(() => {
+    if (this.kjTagListRole() !== 'listbox') return null;
+    return this.kjTagListMultiple() ? 'true' : 'false';
+  });
+}

package/src/tag/tag-remove.ts

@@ -0,0 +1,61 @@
+import { Directive, computed, inject, input } from '@angular/core';
+import { KjButton } from '../button/button';
+import { KJ_TAG } from './tag.context';
+
+/**
+ * Trailing remove control for a `KjTag`. Composes `KjButton` so the remove
+ * action inherits native `<button>` semantics, ARIA-disabled handling,
+ * capture-phase click suppression, and the focus ring — there is no second
+ * keyboard / a11y story to maintain.
+ *
+ * The accessible name is derived automatically from the parent tag's
+ * projected text content (`"Remove {label}"`) via a `MutationObserver` on
+ * `KjTag`. Override with `kjTagRemoveLabel` when the auto-derived name is
+ * insufficient (e.g. icon-only tag, custom phrasing).
+ *
+ * @example
+ * ```html
+ * <span kjTag>
+ *   Acme
+ *   <button kjTagRemove>×</button>
+ * </span>
+ * ```
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name tag
+ */
+@Directive({
+  selector: '[kjTagRemove]',
+  standalone: true,
+  hostDirectives: [KjButton],
+  host: {
+    'type': 'button',
+    '[attr.aria-label]': 'effectiveLabel()',
+    '(click)': 'onClick($event)',
+  },
+})
+export class KjTagRemove {
+  private readonly tag = inject(KJ_TAG);
+
+  /** Override the auto-derived `aria-label` for the remove button. */
+  readonly kjTagRemoveLabel = input<string | undefined>(undefined);
+
+  /** Computed accessible name: explicit override wins, else `"Remove {label}"`. */
+  protected readonly effectiveLabel = computed<string>(() => {
+    const override = this.kjTagRemoveLabel();
+    if (override) return override;
+    const label = this.tag.textContent();
+    return label ? `Remove ${label}` : 'Remove';
+  });
+
+  /** @internal Click handler — fires the parent tag's `(kjTagRemoved)`. */
+  onClick(event: Event): void {
+    if (this.tag.disabled()) {
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      return;
+    }
+    event.stopPropagation();
+    this.tag.remove();
+  }
+}

package/src/tag/tag.context.ts

@@ -0,0 +1,36 @@
+import { InjectionToken, Signal } from '@angular/core';
+
+/**
+ * Public context exposed by `KjTag` to its descendants (notably
+ * `KjTagRemove`). Mirrors the minimal surface called out in the analysis:
+ * three signals + a `remove()` callback.
+ */
+export interface KjTagContext {
+  /** Live read of the projected text content (label) for the tag. */
+  readonly textContent: Signal<string>;
+  /** Whether the tag is currently selected (selectable shape only). */
+  readonly selected: Signal<boolean>;
+  /** Whether the tag is disabled (own + inherited from `KjTagList`). */
+  readonly disabled: Signal<boolean>;
+  /** Triggers removal: emits the parent's `(kjTagRemoved)` output. */
+  remove(): void;
+}
+
+/** Role that a `KjTagList` container exposes. Drives chip role selection. */
+export type KjTagListRole = 'listbox' | 'grid' | 'group';
+
+/** Public context exposed by `KjTagList` so nested tags can self-configure. */
+export interface KjTagListContext {
+  /** Active container role; chips read this to compute their own role. */
+  readonly role: Signal<KjTagListRole>;
+  /** Whether the entire tag list is disabled (cascades into chips). */
+  readonly disabled: Signal<boolean>;
+  /** Whether the listbox container allows multi-selection. */
+  readonly multiple: Signal<boolean>;
+}
+
+/** Injection token providing the parent `KjTag` to projected children. */
+export const KJ_TAG = new InjectionToken<KjTagContext>('KjTag');
+
+/** Injection token providing the optional `KjTagList` container. */
+export const KJ_TAG_LIST = new InjectionToken<KjTagListContext>('KjTagList');