@kouji-ui/core 0.0.4 → 0.1.1

package/src/avatar/avatar.ts

@@ -1,26 +1,39 @@
-import { Directive, InjectionToken, inject, signal } from '@angular/core';
+import { Directive, InjectionToken, inject, signal } from '@angular/core';
 
 export interface KjAvatarContext { imageLoaded: ReturnType<typeof signal<boolean>>; }
 export const KJ_AVATAR = new InjectionToken<KjAvatarContext>('KjAvatar');
 
 /**
  * Container for avatar. Tracks image load state.
+ *
+ * Compose `[kjAvatar]` with `[kjAvatarImage]` and `[kjAvatarFallback]` onto any
+ * elements to toggle visibility between the image and the fallback
+ * automatically when the image fails or is still loading. No styling attached.
+ *
  * @example `<span kjAvatar><img kjAvatarImage src="..." alt="..." /><span kjAvatarFallback>JD</span></span>`
- * @category Core/Display
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name avatar
+ * @doc-description Unstyled avatar container that swaps between an image and a fallback when loading or failing.
+ * @doc-is-main
  */
 @Directive({ selector: '[kjAvatar]', standalone: true, providers: [{ provide: KJ_AVATAR, useExisting: KjAvatar }] })
 export class KjAvatar implements KjAvatarContext { readonly imageLoaded = signal(false); }
 
 /**
  * Image element within a `[kjAvatar]` container.
- * @category Core/Display
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name avatar
  */
 @Directive({ selector: '[kjAvatarImage]', standalone: true, host: { '(load)': 'ctx.imageLoaded.set(true)', '(error)': 'ctx.imageLoaded.set(false)', '[attr.data-loaded]': 'ctx.imageLoaded() ? "" : null' } })
 export class KjAvatarImage { readonly ctx = inject(KJ_AVATAR); }
 
 /**
  * Fallback shown when image is unavailable.
- * @category Core/Display
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name avatar
  */
 @Directive({ selector: '[kjAvatarFallback]', standalone: true, host: { '[attr.data-visible]': '!ctx.imageLoaded() ? "" : null' } })
 export class KjAvatarFallback { readonly ctx = inject(KJ_AVATAR); }

package/src/avatar/index.ts

@@ -1 +1,11 @@
-export { KjAvatar, KjAvatarImage, KjAvatarFallback, KJ_AVATAR } from './avatar';
+export { KjAvatar, KjAvatarImage, KjAvatarFallback, KJ_AVATAR } from './avatar';
+export {
+  KjAvatarGroup,
+  type KjAvatarGroupAriaLabelFormat,
+} from './avatar-group';
+export {
+  KJ_AVATAR_GROUP,
+  type KjAvatarGroupContext,
+  type KjAvatarGroupDirection,
+  type KjAvatarShape,
+} from './avatar-group.context';

package/src/badge/badge.spec.ts

@@ -13,6 +13,14 @@ describe('KjBadge', () => {
     const { container } = await render(`<span kjBadge>Beta</span>`, { imports: [KjBadge] });
     expect(container.querySelector('span')).toHaveAttribute('data-variant', 'default');
   });
+  it('sets data-dot attribute when kjBadgeDot is true', async () => {
+    const { container } = await render(`<span kjBadge [kjBadgeDot]="true">Active</span>`, { imports: [KjBadge] });
+    expect(container.querySelector('span')).toHaveAttribute('data-dot', '');
+  });
+  it('omits data-dot attribute by default', async () => {
+    const { container } = await render(`<span kjBadge>Beta</span>`, { imports: [KjBadge] });
+    expect(container.querySelector('span')).not.toHaveAttribute('data-dot');
+  });
   it('passes axe audit', async () => {
     const { container } = await render(`<span kjBadge>Beta</span>`, { imports: [KjBadge] });
     expect(await axe(container)).toHaveNoViolations();

package/src/badge/badge.ts

@@ -1,14 +1,35 @@
-import { Directive, input } from '@angular/core';
+import { Directive, booleanAttribute, input } from '@angular/core';
 
 export type KjBadgeVariant = 'default' | 'secondary' | 'destructive' | 'outline';
 
 /**
  * Marks an element as a badge via data attributes.
+ *
+ * Apply `[kjBadge]` to any inline element to reflect a `data-variant` attribute
+ * that theme CSS reads — choose from `default`, `secondary`, `destructive`, or
+ * `outline` without adding any wrapper markup. No styling is attached.
+ *
+ * Set `kjBadgeDot` to reflect a `data-dot` attribute for theme CSS to render a
+ * leading status indicator.
+ *
  * @example `<span kjBadge [kjBadgeVariant]="'destructive'">Critical</span>`
- * @category Core/Display
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name badge
+ * @doc-description Marks an inline element as a badge with a variant data attribute that theme CSS picks up.
+ * @doc-is-main
  */
-@Directive({ selector: '[kjBadge]', standalone: true, host: { '[attr.data-variant]': 'kjBadgeVariant()' } })
+@Directive({
+  selector: '[kjBadge]',
+  standalone: true,
+  host: {
+    '[attr.data-variant]': 'kjBadgeVariant()',
+    '[attr.data-dot]': 'kjBadgeDot() ? "" : null',
+  },
+})
 export class KjBadge {
   /** The visual variant of the badge. Defaults to `'default'`. */
   kjBadgeVariant = input<KjBadgeVariant>('default');
+  /** Reflects `data-dot` so theme CSS can render a leading status dot. Defaults to `false`. */
+  kjBadgeDot = input(false, { transform: booleanAttribute });
 }

package/src/breadcrumb/breadcrumb-current.ts

@@ -0,0 +1,38 @@
+import { Directive, OnDestroy, inject } from '@angular/core';
+import { KJ_BREADCRUMB } from './breadcrumb.context';
+
+/**
+ * The terminal "current page" cell. Emits `aria-current="page"` and
+ * registers with the parent so auto-current detection knows to step aside.
+ *
+ * The element is text — not focusable, not an anchor. Place inside the last
+ * `<li kjBreadcrumbItem>` to mark the current page explicitly.
+ *
+ * @example
+ * ```html
+ * <span kjBreadcrumbCurrent>Data</span>
+ * ```
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name breadcrumb
+ */
+@Directive({
+  selector: 'span[kjBreadcrumbCurrent], [kjBreadcrumbCurrent]',
+  standalone: true,
+  host: {
+    '[attr.aria-current]': '"page"',
+    '[attr.data-breadcrumb-current]': '""',
+  },
+})
+export class KjBreadcrumbCurrent implements OnDestroy {
+  private readonly root = inject(KJ_BREADCRUMB);
+
+  constructor() {
+    this.root.registerCurrent();
+  }
+
+  ngOnDestroy(): void {
+    this.root.unregisterCurrent();
+  }
+}

package/src/breadcrumb/breadcrumb-ellipsis.ts

@@ -0,0 +1,71 @@
+import {
+  Directive,
+  booleanAttribute,
+  computed,
+  inject,
+  input,
+} from '@angular/core';
+import { KjFocusRing } from '../primitives';
+import { KJ_BREADCRUMB } from './breadcrumb.context';
+import { KJ_BREADCRUMB_CONFIG } from './config';
+
+/**
+ * Overflow indicator rendered in place of truncated middle crumbs.
+ *
+ * - In `'truncate'` overflow mode: behaves like a static glyph,
+ *   `aria-hidden="true"`.
+ * - In `'menu'` overflow mode: an interactive cell with
+ *   `aria-haspopup="true"`. Consumers wire a `KjDropdownMenu` to the host
+ *   to expose the hidden crumbs as menu items.
+ *
+ * Visible only when there are hidden crumbs (`ctx.hiddenIndices().length > 0`).
+ * The host wrapper component conditionally renders the directive based on
+ * this signal.
+ *
+ * @example
+ * ```html
+ * <li kjBreadcrumbItem><span kjBreadcrumbEllipsis>…</span></li>
+ * ```
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name breadcrumb
+ */
+@Directive({
+  selector: '[kjBreadcrumbEllipsis]',
+  standalone: true,
+  hostDirectives: [KjFocusRing],
+  host: {
+    '[attr.aria-hidden]': 'isAriaHidden() ? "true" : null',
+    '[attr.aria-label]': 'computedAriaLabel()',
+    '[attr.aria-haspopup]': 'isMenu() ? "true" : null',
+    '[attr.data-overflow]': 'ctx.overflow()',
+    '[attr.data-hidden-count]': 'hiddenCount()',
+  },
+})
+export class KjBreadcrumbEllipsis {
+  /** @internal */
+  readonly ctx = inject(KJ_BREADCRUMB);
+  private readonly config = inject(KJ_BREADCRUMB_CONFIG);
+
+  /**
+   * Mirrors a disabled bundle (currently advisory — the ellipsis menu
+   * trigger composes `KjDropdownMenu` separately when wired by the
+   * consumer).
+   */
+  readonly kjDisabled = input<boolean, unknown>(false, { transform: booleanAttribute });
+
+  /** Number of hidden crumbs the ellipsis represents. */
+  readonly hiddenCount = computed(() => this.ctx.hiddenIndices().length);
+
+  /** Whether the ellipsis is in menu (interactive) mode. */
+  readonly isMenu = computed(() => this.ctx.overflow() === 'menu');
+
+  /** Whether the ellipsis is purely decorative (truncate mode). */
+  readonly isAriaHidden = computed(() => !this.isMenu());
+
+  /** `aria-label` value — null in truncate mode (the cell is decorative). */
+  readonly computedAriaLabel = computed(() =>
+    this.isMenu() ? this.config.ellipsisLabel(this.hiddenCount()) : null,
+  );
+}

package/src/breadcrumb/breadcrumb-item.ts

@@ -0,0 +1,41 @@
+import { Directive, OnDestroy, inject } from '@angular/core';
+import { KJ_BREADCRUMB, KjBreadcrumbItemContext } from './breadcrumb.context';
+
+/**
+ * A single crumb cell. Registers itself with the parent breadcrumb on
+ * construction (capturing its index) and exposes a `current` signal derived
+ * from "am I last + no explicit current cell?".
+ *
+ * Selector restricted to `<li>` to keep the list semantics clean.
+ *
+ * @example
+ * ```html
+ * <li kjBreadcrumbItem>…</li>
+ * ```
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name breadcrumb
+ */
+@Directive({
+  selector: '[kjBreadcrumbItem]',
+  standalone: true,
+  host: {
+    '[attr.data-hidden]': 'context.hidden() ? "" : null',
+    '[attr.aria-current]': 'context.current() ? "page" : null',
+  },
+})
+export class KjBreadcrumbItem implements OnDestroy {
+  private readonly root = inject(KJ_BREADCRUMB);
+
+  /** Public context (index, current, hidden) for this item. */
+  readonly context: KjBreadcrumbItemContext;
+
+  constructor() {
+    this.context = this.root.registerItem();
+  }
+
+  ngOnDestroy(): void {
+    this.root.unregisterItem(this.context);
+  }
+}

package/src/breadcrumb/breadcrumb-link.ts

@@ -0,0 +1,44 @@
+import { Directive, inject } from '@angular/core';
+import { KjLink } from '../link/link';
+import { KJ_BREADCRUMB } from './breadcrumb.context';
+
+/**
+ * Per-crumb anchor. Composes `KjLink` via `hostDirectives` so the per-crumb
+ * `<a>` inherits external-link `rel` plumbing, focus-ring composition, and
+ * disabled-link enforcement.
+ *
+ * The directive deliberately does **not** forward `KjLink`'s own inputs onto
+ * its own selector — the components-package wrapper (`<kj-breadcrumb-link>`)
+ * is the authoring surface for those, and consumers driving the directive
+ * directly can apply `kjLink` inputs on the same element (since `KjLink` is
+ * composed via `hostDirectives`, the inputs land on it through the host).
+ *
+ * The wrapper applies breadcrumb defaults: `muted` variant, `sm` size,
+ * `hover` underline.
+ *
+ * @example
+ * ```html
+ * <a kjBreadcrumbLink href="/library">Library</a>
+ * ```
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name breadcrumb
+ */
+@Directive({
+  selector: 'a[kjBreadcrumbLink], [kjBreadcrumbLink]',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjLink,
+      inputs: ['kjUnderline', 'kjExternal', 'kjDisabled'],
+    },
+  ],
+  host: {
+    '[attr.data-breadcrumb-link]': '""',
+  },
+})
+export class KjBreadcrumbLink {
+  /** @internal */
+  readonly ctx = inject(KJ_BREADCRUMB);
+}

package/src/breadcrumb/breadcrumb-list.ts

@@ -0,0 +1,42 @@
+import { Directive, inject, input } from '@angular/core';
+import { KJ_BREADCRUMB } from './breadcrumb.context';
+
+/**
+ * The breadcrumb's ordered list. Selector restricted to `<ol>` to enforce
+ * ordered-list semantics (a `<ul>` will not match).
+ *
+ * Reads the parent's `hasExplicitSeparators` and `overflow` signals to
+ * reflect data attributes that key the CSS layer:
+ * - `data-explicit-separators=""` suppresses the auto pseudo-element.
+ * - `data-overflow="truncate|menu|none"` mirrors the root's overflow mode.
+ * - `data-wrap="wrap|no-wrap|truncate"` reflects this directive's wrap input.
+ *
+ * @example
+ * ```html
+ * <ol kjBreadcrumbList>…</ol>
+ * ```
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name breadcrumb
+ */
+@Directive({
+  selector: '[kjBreadcrumbList]',
+  standalone: true,
+  host: {
+    '[attr.data-explicit-separators]': 'ctx.hasExplicitSeparators() ? "" : null',
+    '[attr.data-overflow]': 'ctx.overflow()',
+    '[attr.data-wrap]': 'kjWrap()',
+  },
+})
+export class KjBreadcrumbList {
+  /** @internal */
+  readonly ctx = inject(KJ_BREADCRUMB);
+
+  /**
+   * Wrapping policy. `'no-wrap'` keeps the row single-line (the truncation
+   * does the long-path work); `'wrap'` allows the row to break across
+   * lines; `'truncate'` reserved for future ellipsis-by-CSS support.
+   */
+  readonly kjWrap = input<'wrap' | 'no-wrap' | 'truncate'>('no-wrap');
+}

package/src/breadcrumb/breadcrumb-separator.ts

@@ -0,0 +1,45 @@
+import { Directive, OnDestroy, inject } from '@angular/core';
+import { KJ_BREADCRUMB } from './breadcrumb.context';
+
+/**
+ * Optional explicit separator cell. Used when a CSS pseudo-element will not
+ * do — typically for an icon (SVG) separator that needs `currentColor`,
+ * `width`, and `height` plumbing the pseudo-element cannot deliver.
+ *
+ * Registers with the parent so the auto separator (CSS `::before`) is
+ * suppressed via the `data-explicit-separators=""` attribute on the list.
+ *
+ * Selector restricted to `<li>` so the list semantics stay clean
+ * (every direct child of `<ol>` must be `<li>`); the directive sets
+ * `role="presentation"` and `aria-hidden="true"` so AT does not announce
+ * the separator as a list item.
+ *
+ * @example
+ * ```html
+ * <li kjBreadcrumbSeparator><svg>…chevron…</svg></li>
+ * ```
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name breadcrumb
+ */
+@Directive({
+  selector: '[kjBreadcrumbSeparator]',
+  standalone: true,
+  host: {
+    'role': 'presentation',
+    '[attr.aria-hidden]': '"true"',
+    '[attr.data-breadcrumb-separator]': '""',
+  },
+})
+export class KjBreadcrumbSeparator implements OnDestroy {
+  private readonly root = inject(KJ_BREADCRUMB);
+
+  constructor() {
+    this.root.registerSeparator();
+  }
+
+  ngOnDestroy(): void {
+    this.root.unregisterSeparator();
+  }
+}

package/src/breadcrumb/breadcrumb.context.ts

@@ -0,0 +1,45 @@
+import { InjectionToken, Signal } from '@angular/core';
+
+/** Public-facing token interface representing a registered crumb item. */
+export interface KjBreadcrumbItemContext {
+  /** Index of the item among registered items (0-based, document order). */
+  readonly index: Signal<number>;
+  /** Whether this item is currently the "current page" cell. */
+  readonly current: Signal<boolean>;
+  /** Whether this item is hidden by truncation. */
+  readonly hidden: Signal<boolean>;
+}
+
+/** Public-facing token interface representing the root breadcrumb. */
+export interface KjBreadcrumbContext {
+  /** Configured separator glyph (or `undefined` to use the CSS default). */
+  readonly separator: Signal<string | undefined>;
+  /** `kjMaxItems` — `0` or `Infinity` disables truncation. */
+  readonly maxItems: Signal<number>;
+  /** Active overflow mode. */
+  readonly overflow: Signal<'truncate' | 'menu' | 'none'>;
+  /** Read-only count of registered items. */
+  readonly itemCount: Signal<number>;
+  /** Read-only count of registered explicit current cells. */
+  readonly currentCount: Signal<number>;
+  /** Indices that should render visibly. */
+  readonly visibleIndices: Signal<readonly number[]>;
+  /** Indices that should be hidden by truncation. */
+  readonly hiddenIndices: Signal<readonly number[]>;
+  /** Whether the consumer has rendered explicit `<li kjBreadcrumbSeparator>` cells. */
+  readonly hasExplicitSeparators: Signal<boolean>;
+
+  /** Register a freshly-created item directive; returns its assigned index signal. */
+  registerItem(): KjBreadcrumbItemContext;
+  /** Unregister an item directive (called from `ngOnDestroy`). */
+  unregisterItem(item: KjBreadcrumbItemContext): void;
+  /** Register / unregister an explicit current cell. */
+  registerCurrent(): void;
+  unregisterCurrent(): void;
+  /** Register / unregister an explicit separator cell. */
+  registerSeparator(): void;
+  unregisterSeparator(): void;
+}
+
+/** Injection token for the root `KjBreadcrumb` directive context. */
+export const KJ_BREADCRUMB = new InjectionToken<KjBreadcrumbContext>('KjBreadcrumb');