@kouji-ui/components 0.1.1

package/src/overlay-badge/_examples/overlay-badge.dot.example.ts

@@ -0,0 +1,28 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjButtonComponent } from '../../button/button';
+import { KjOverlayBadgeComponent } from '../overlay-badge';
+
+/**
+ * Presence-dot mode. The badge ignores `kjValue` / `kjMaxValue` and renders
+ * a fixed-size dot. Useful for "new content" pips and online-status markers
+ * where the count itself is not meaningful.
+ */
+@Component({
+  selector: 'kj-overlay-badge-dot-example',
+  standalone: true,
+  imports: [KjOverlayBadgeComponent, KjButtonComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-overlay-badge [kjDot]="true" kjVariant="destructive" kjDescription="New activity">
+      <kj-button kjVariant="secondary">Inbox</kj-button>
+    </kj-overlay-badge>
+  `,
+})
+export class KjOverlayBadgeDotExample {}

package/src/overlay-badge/_examples/overlay-badge.example.ts

@@ -0,0 +1,34 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjButtonComponent } from '../../button/button';
+import { KjOverlayBadgeComponent } from '../overlay-badge';
+
+/**
+ * Default usage example for KjOverlayBadgeComponent.
+ * Notification bell with an unread count and an accessible description so
+ * AT hears "Notifications, 4 unread".
+ */
+@Component({
+  selector: 'kj-overlay-badge-example',
+  standalone: true,
+  imports: [KjOverlayBadgeComponent, KjButtonComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-overlay-badge [kjValue]="4" kjVariant="destructive" kjDescription="4 unread notifications">
+      <kj-button kjSize="icon" kjAriaLabel="Notifications">
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+          <path
+            d="M12 22a2 2 0 0 0 2-2h-4a2 2 0 0 0 2 2Zm6-6V11a6 6 0 0 0-5-5.91V4a1 1 0 0 0-2 0v1.09A6 6 0 0 0 6 11v5l-2 2v1h16v-1Z"
+          />
+        </svg>
+      </kj-button>
+    </kj-overlay-badge>
+  `,
+})
+export class KjOverlayBadgeExample {}

package/src/overlay-badge/_examples/overlay-badge.on-avatar.example.ts

@@ -0,0 +1,38 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjAvatarComponent } from '../../avatar/avatar';
+import { KjOverlayBadgeComponent } from '../overlay-badge';
+
+/**
+ * Status overlay on `<kj-avatar>`. Demonstrates the canonical anchor — a
+ * presence dot in the bottom-end corner with a `kjDescription` so AT
+ * announces "Avatar, Online" rather than just the avatar's accessible name.
+ */
+@Component({
+  selector: 'kj-overlay-badge-on-avatar-example',
+  standalone: true,
+  imports: [KjOverlayBadgeComponent, KjAvatarComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        gap: var(--kj-space-xl);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-overlay-badge [kjDot]="true" kjPosition="bottom-end" kjDescription="Online">
+      <kj-avatar content="AB" alt="Alex Brown" />
+    </kj-overlay-badge>
+
+    <kj-overlay-badge
+      [kjDot]="true"
+      kjPosition="bottom-end"
+      kjVariant="secondary"
+      kjDescription="Away"
+    >
+      <kj-avatar content="JM" alt="Jamie Morgan" />
+    </kj-overlay-badge>
+  `,
+})
+export class KjOverlayBadgeOnAvatarExample {}

package/src/overlay-badge/_examples/overlay-badge.positions.example.ts

@@ -0,0 +1,39 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjButtonComponent } from '../../button/button';
+import { KjOverlayBadgeComponent } from '../overlay-badge';
+
+/**
+ * The four logical-corner positions. `start` / `end` keywords flip in RTL
+ * via CSS logical properties — no JS bidi reads.
+ */
+@Component({
+  selector: 'kj-overlay-badge-positions-example',
+  standalone: true,
+  imports: [KjOverlayBadgeComponent, KjButtonComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--kj-space-2xl);
+        padding: var(--kj-space-2xl);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-overlay-badge [kjValue]="3" kjPosition="top-end" kjDescription="3 unread">
+      <kj-button kjVariant="secondary">top-end</kj-button>
+    </kj-overlay-badge>
+    <kj-overlay-badge [kjValue]="3" kjPosition="top-start" kjDescription="3 unread">
+      <kj-button kjVariant="secondary">top-start</kj-button>
+    </kj-overlay-badge>
+    <kj-overlay-badge [kjValue]="3" kjPosition="bottom-end" kjDescription="3 unread">
+      <kj-button kjVariant="secondary">bottom-end</kj-button>
+    </kj-overlay-badge>
+    <kj-overlay-badge [kjValue]="3" kjPosition="bottom-start" kjDescription="3 unread">
+      <kj-button kjVariant="secondary">bottom-start</kj-button>
+    </kj-overlay-badge>
+  `,
+})
+export class KjOverlayBadgePositionsExample {}

package/src/overlay-badge/index.ts

@@ -0,0 +1 @@
+export * from './overlay-badge';

package/src/overlay-badge/overlay-badge.css

@@ -0,0 +1,118 @@
+@layer kj.component {
+  .kj-overlay-badge-anchor {
+    /* The anchor is also the positioning context. `position: relative` is
+       inline-style-bound by `KjOverlayBadge`; we add the inline-flex layout
+       here so projected anchors keep their inline rhythm. */
+    display: inline-flex;
+    vertical-align: middle;
+  }
+
+  .kj-overlay-badge {
+    /* Visual chrome inherited from <kj-badge>. We re-apply the same token
+       set here so the slot renders identically whether the consumer uses
+       <kj-overlay-badge> or projects a manual <span kjOverlayBadgeContent>. */
+    --kj-badge-bg:           var(--kj-bg-primary);
+    --kj-badge-fg:           var(--kj-fg-on-primary);
+    --kj-badge-border-color: transparent;
+    --kj-badge-radius:       var(--kj-radius-selector);
+    --kj-badge-padding-x:    var(--kj-space-sm);
+    --kj-badge-padding-y:    0.125rem;
+    --kj-badge-font-size:    0.6875rem;
+
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-width: 1.25rem;
+    height: 1.25rem;
+    background: var(--kj-badge-bg);
+    color: var(--kj-badge-fg);
+    border: var(--kj-border) solid var(--kj-badge-border-color);
+    border-radius: var(--kj-badge-radius);
+    padding: var(--kj-badge-padding-y) var(--kj-badge-padding-x);
+    font: var(--kj-badge-font-size) / 1 var(--kj-font-sans);
+    font-weight: 600;
+
+    /* 2px halo against the anchor for WCAG 1.4.11 non-text contrast — the
+       badge is a small element sitting on top of arbitrary surfaces. */
+    box-shadow: 0 0 0 2px var(--kj-bg-body);
+
+    /* Logical-property positioning so RTL flips for free. The translate
+       pulls the badge half-out of the anchor at each corner — keeps the
+       majority of the chip visible above an avatar's overflow mask, etc. */
+    inset-block-start: auto;
+    inset-block-end:   auto;
+    inset-inline-start: auto;
+    inset-inline-end:   auto;
+  }
+
+  /* Variant overrides — mirror <kj-badge>'s data-variant rules. */
+  .kj-overlay-badge[data-variant="secondary"] {
+    --kj-badge-bg: var(--kj-bg-surface);
+    --kj-badge-fg: var(--kj-fg-default);
+  }
+  .kj-overlay-badge[data-variant="destructive"] {
+    --kj-badge-bg: var(--kj-bg-danger);
+    --kj-badge-fg: var(--kj-fg-on-danger);
+  }
+  .kj-overlay-badge[data-variant="outline"] {
+    --kj-badge-bg: transparent;
+    --kj-badge-fg: var(--kj-fg-default);
+    --kj-badge-border-color: var(--kj-border-default);
+  }
+
+  /* Sizes. */
+  .kj-overlay-badge[data-size="sm"] {
+    min-width: 1rem;
+    height: 1rem;
+    --kj-badge-font-size: 0.625rem;
+    --kj-badge-padding-x: 0.25rem;
+  }
+  .kj-overlay-badge[data-size="lg"] {
+    min-width: 1.5rem;
+    height: 1.5rem;
+    --kj-badge-font-size: 0.75rem;
+    --kj-badge-padding-x: 0.5rem;
+  }
+
+  /* Dot mode — fixed 0.5rem circle, no padding, no min-width. */
+  .kj-overlay-badge[data-dot] {
+    min-width: 0;
+    width: 0.625rem;
+    height: 0.625rem;
+    padding: 0;
+    border-radius: 9999px;
+  }
+  .kj-overlay-badge[data-dot][data-size="sm"] { width: 0.5rem;  height: 0.5rem; }
+  .kj-overlay-badge[data-dot][data-size="lg"] { width: 0.75rem; height: 0.75rem; }
+
+  /* Logical-corner placement. RTL flips automatically because we use
+     inline-start / inline-end. */
+  .kj-overlay-badge[data-position="top-end"] {
+    inset-block-start: 0;
+    inset-inline-end: 0;
+    transform: translate(50%, -50%);
+  }
+  .kj-overlay-badge[data-position="top-start"] {
+    inset-block-start: 0;
+    inset-inline-start: 0;
+    transform: translate(-50%, -50%);
+  }
+  .kj-overlay-badge[data-position="bottom-end"] {
+    inset-block-end: 0;
+    inset-inline-end: 0;
+    transform: translate(50%, 50%);
+  }
+  .kj-overlay-badge[data-position="bottom-start"] {
+    inset-block-end: 0;
+    inset-inline-start: 0;
+    transform: translate(-50%, 50%);
+  }
+
+  /* RTL inverts the inline-axis translation so the badge stays outside the
+     anchor's edge rather than tucking inward. Logical insets handle the
+     position itself; only the translate sign needs flipping. */
+  [dir="rtl"] .kj-overlay-badge[data-position="top-end"]    { transform: translate(-50%, -50%); }
+  [dir="rtl"] .kj-overlay-badge[data-position="top-start"]  { transform: translate(50%,  -50%); }
+  [dir="rtl"] .kj-overlay-badge[data-position="bottom-end"] { transform: translate(-50%, 50%); }
+  [dir="rtl"] .kj-overlay-badge[data-position="bottom-start"] { transform: translate(50%, 50%); }
+}

package/src/overlay-badge/overlay-badge.playground.ts

@@ -0,0 +1,92 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjOverlayBadgeComponent } from './overlay-badge';
+import { KjButtonComponent } from '../button/button';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+type KjOverlayBadgePosition = 'top-end' | 'top-start' | 'bottom-end' | 'bottom-start';
+type KjOverlayBadgeVariant = 'default' | 'secondary' | 'destructive' | 'outline';
+type KjOverlayBadgeSize = 'sm' | 'md' | 'lg';
+
+const badgeValue = signal<number>(4);
+const variant = signal<KjOverlayBadgeVariant>('destructive');
+const size = signal<KjOverlayBadgeSize>('md');
+const position = signal<KjOverlayBadgePosition>('top-end');
+const dot = signal(false);
+const hidden = signal(false);
+
+@Component({
+  selector: 'kj-overlay-badge-playground',
+  standalone: true,
+  imports: [KjOverlayBadgeComponent, KjButtonComponent],
+  template: `
+    <kj-overlay-badge
+      [kjValue]="badgeValue()"
+      [kjVariant]="variant()"
+      [kjSize]="size()"
+      [kjPosition]="position()"
+      [kjDot]="dot()"
+      [kjHidden]="hidden()"
+      kjDescription="Unread notifications"
+    >
+      <kj-button kjVariant="outline">Inbox</kj-button>
+    </kj-overlay-badge>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjOverlayBadgePlaygroundDemo {
+  protected readonly badgeValue = badgeValue;
+  protected readonly variant = variant;
+  protected readonly size = size;
+  protected readonly position = position;
+  protected readonly dot = dot;
+  protected readonly hidden = hidden;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjOverlayBadgePlaygroundDemo,
+  state: {
+    badgeValue: badgeValue as unknown as ReturnType<typeof signal>,
+    variant: variant as unknown as ReturnType<typeof signal>,
+    size: size as unknown as ReturnType<typeof signal>,
+    position: position as unknown as ReturnType<typeof signal>,
+    dot: dot as unknown as ReturnType<typeof signal>,
+    hidden: hidden as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'number', name: 'badgeValue', label: 'value', min: 0, max: 999 },
+    {
+      kind: 'chips',
+      name: 'variant',
+      label: 'variant',
+      options: ['default', 'secondary', 'destructive', 'outline'],
+    },
+    { kind: 'chips', name: 'size', label: 'size', options: ['sm', 'md', 'lg'] },
+    {
+      kind: 'chips',
+      name: 'position',
+      label: 'position',
+      options: ['top-end', 'top-start', 'bottom-end', 'bottom-start'],
+    },
+    { kind: 'toggle', name: 'dot', label: 'dot' },
+    { kind: 'toggle', name: 'hidden', label: 'hidden' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      badgeValue: number;
+      variant: string;
+      size: string;
+      position: string;
+      dot: boolean;
+      hidden: boolean;
+    };
+    const attrs: string[] = [];
+    if (!s.dot) attrs.push(`[kjValue]="${s.badgeValue}"`);
+    attrs.push(`kjVariant="${s.variant}"`);
+    attrs.push(`kjSize="${s.size}"`);
+    attrs.push(`kjPosition="${s.position}"`);
+    if (s.dot) attrs.push('[kjDot]="true"');
+    if (s.hidden) attrs.push('[kjHidden]="true"');
+    attrs.push('kjDescription="Unread notifications"');
+    return `<kj-overlay-badge\n  ${attrs.join('\n  ')}\n>\n  <kj-button kjVariant="outline">Inbox</kj-button>\n</kj-overlay-badge>`;
+  },
+};

package/src/overlay-badge/overlay-badge.spec.ts

@@ -0,0 +1,174 @@
+import { Component, signal } from '@angular/core';
+import { render } from '@testing-library/angular';
+import { describe, expect, it } from 'vitest';
+
+import { KjOverlayBadgeComponent } from './overlay-badge';
+
+const imports = [KjOverlayBadgeComponent];
+
+/** Resolve the badge slot rendered inside a `<kj-overlay-badge>` host. */
+function slot(container: HTMLElement): HTMLElement {
+  const el = container.querySelector<HTMLElement>('[kjOverlayBadgeContent]');
+  if (!el) throw new Error('expected a [kjOverlayBadgeContent] slot');
+  return el;
+}
+
+/** Resolve the wrapper host element. */
+function host(container: HTMLElement): HTMLElement {
+  const el = container.querySelector<HTMLElement>('kj-overlay-badge');
+  if (!el) throw new Error('expected a <kj-overlay-badge> host');
+  return el;
+}
+
+describe('KjOverlayBadgeComponent (wrapper)', () => {
+  describe('anchor wrapper', () => {
+    it('applies position:relative on the anchor host (from KjOverlayBadge)', async () => {
+      const { container } = await render(
+        `<kj-overlay-badge [kjValue]="1" kjDescription="1 new"><span>Bell</span></kj-overlay-badge>`,
+        { imports },
+      );
+      // The hostDirective `KjOverlayBadge` inline-binds position: relative
+      // on its host element — which here is <kj-overlay-badge>.
+      expect(host(container).style.position).toBe('relative');
+    });
+
+    it('reflects kjPosition through to the slot data-position', async () => {
+      const { container } = await render(
+        `<kj-overlay-badge [kjValue]="1" kjPosition="bottom-start" kjDescription="1 new"><span>Bell</span></kj-overlay-badge>`,
+        { imports },
+      );
+      expect(slot(container).getAttribute('data-position')).toBe('bottom-start');
+    });
+
+    it('defaults position to top-end on the slot', async () => {
+      const { container } = await render(
+        `<kj-overlay-badge [kjValue]="1" kjDescription="1 new"><span>Bell</span></kj-overlay-badge>`,
+        { imports },
+      );
+      expect(slot(container).getAttribute('data-position')).toBe('top-end');
+    });
+  });
+
+  describe('content child composes badge', () => {
+    it('forwards kjVariant onto the slot via KjBadge.kjBadgeVariant (data-variant)', async () => {
+      const { container } = await render(
+        `<kj-overlay-badge [kjValue]="2" kjVariant="destructive" kjDescription="2 unread">
+           <span>Bell</span>
+         </kj-overlay-badge>`,
+        { imports },
+      );
+      expect(slot(container).getAttribute('data-variant')).toBe('destructive');
+    });
+
+    it('renders the truncated displayValue (99+) for values above kjMaxValue', async () => {
+      const { container } = await render(
+        `<kj-overlay-badge [kjValue]="248" kjDescription="lots"><span>X</span></kj-overlay-badge>`,
+        { imports },
+      );
+      expect(slot(container).textContent?.trim()).toBe('99+');
+    });
+
+    it('renders the raw value when below kjMaxValue', async () => {
+      const { container } = await render(
+        `<kj-overlay-badge [kjValue]="7" kjDescription="7 new"><span>X</span></kj-overlay-badge>`,
+        { imports },
+      );
+      expect(slot(container).textContent?.trim()).toBe('7');
+    });
+
+    it('reflects data-dot when kjDot is true and skips the value text', async () => {
+      const { container } = await render(
+        `<kj-overlay-badge [kjDot]="true" [kjValue]="9" kjDescription="online"><span>X</span></kj-overlay-badge>`,
+        { imports },
+      );
+      const s = slot(container);
+      expect(s.getAttribute('data-dot')).toBe('');
+      expect(s.textContent?.trim()).toBe('');
+    });
+
+    it('omits the slot when kjHidden is true', async () => {
+      const { container } = await render(
+        `<kj-overlay-badge [kjValue]="3" [kjHidden]="true" kjDescription="3 new"><span>X</span></kj-overlay-badge>`,
+        { imports },
+      );
+      expect(container.querySelector('[kjOverlayBadgeContent]')).toBeNull();
+      expect(host(container).getAttribute('data-hidden')).toBe('');
+    });
+
+    it('omits the slot when kjValue is null and not in dot mode', async () => {
+      const { container } = await render(
+        `<kj-overlay-badge kjDescription="none"><span>X</span></kj-overlay-badge>`,
+        { imports },
+      );
+      expect(container.querySelector('[kjOverlayBadgeContent]')).toBeNull();
+    });
+  });
+
+  describe('description merges into aria-describedby', () => {
+    it('appends the visually-hidden description id onto the anchor host', async () => {
+      const { container } = await render(
+        `<kj-overlay-badge [kjValue]="4" kjDescription="4 unread"><span>Bell</span></kj-overlay-badge>`,
+        { imports },
+      );
+      const wrapper = host(container);
+      const ids = wrapper.getAttribute('aria-describedby')?.split(/\s+/u) ?? [];
+      expect(ids).toHaveLength(1);
+      expect(ids[0]).toMatch(/^kj-overlay-badge-\d+-desc$/u);
+
+      // The visually-hidden span actually exists with that id.
+      const desc = container.querySelector(`#${ids[0]}`);
+      expect(desc?.textContent?.trim()).toBe('4 unread');
+    });
+
+    it('preserves existing aria-describedby ids while appending the description id', async () => {
+      const { container } = await render(
+        `<kj-overlay-badge
+           aria-describedby="hint err"
+           [kjValue]="1"
+           kjDescription="1 unread"
+         ><span>Bell</span></kj-overlay-badge>
+         <span id="hint">Hint</span>
+         <span id="err">Error</span>`,
+        { imports },
+      );
+      const ids = host(container).getAttribute('aria-describedby')!.split(/\s+/u);
+      expect(ids[0]).toBe('hint');
+      expect(ids[1]).toBe('err');
+      expect(ids[2]).toMatch(/^kj-overlay-badge-\d+-desc$/u);
+    });
+
+    it('skips the describedby merge in decorative mode', async () => {
+      const { container } = await render(
+        `<kj-overlay-badge [kjValue]="1" [kjDecorative]="true" kjDescription="ignored"><span>X</span></kj-overlay-badge>`,
+        { imports },
+      );
+      expect(host(container).hasAttribute('aria-describedby')).toBe(false);
+      // Slot is aria-hidden in decorative mode.
+      expect(slot(container).getAttribute('aria-hidden')).toBe('true');
+    });
+
+    it('drops the description id when description becomes empty', async () => {
+      @Component({
+        standalone: true,
+        imports,
+        template: `
+          <kj-overlay-badge [kjValue]="1" [kjDescription]="desc()">
+            <span>Bell</span>
+          </kj-overlay-badge>
+        `,
+      })
+      class Host {
+        readonly desc = signal<string | undefined>('1 unread');
+      }
+
+      const { fixture } = await render(Host);
+      const wrapper = fixture.nativeElement.querySelector('kj-overlay-badge') as HTMLElement;
+      expect(wrapper.getAttribute('aria-describedby')).toMatch(/^kj-overlay-badge-\d+-desc$/u);
+
+      fixture.componentInstance.desc.set(undefined);
+      fixture.detectChanges();
+
+      expect(wrapper.hasAttribute('aria-describedby')).toBe(false);
+    });
+  });
+});