@kouji-ui/core 0.0.4 → 0.1.1

package/src/tree-select/tree-select.context.ts

@@ -0,0 +1,63 @@
+import { InjectionToken, Signal } from '@angular/core';
+
+/**
+ * A single node in a tree structure. Nodes may carry an arbitrary value
+ * of type `T`, a display label, an optional disabled flag, and optional
+ * child nodes (making the node a branch rather than a leaf).
+ */
+export interface KjTreeNode<T = unknown> {
+  /** The value represented by this node. Used for selection and identity. */
+  readonly value: T;
+  /** Human-readable display label shown in the tree. */
+  readonly label: string;
+  /** When `true`, the node cannot be selected or expanded by the user. */
+  readonly disabled?: boolean;
+  /** Child nodes. When present and non-empty, this node is a branch. */
+  readonly children?: readonly KjTreeNode<T>[];
+}
+
+/**
+ * Context interface exposed by `KjTreeSelect` to descendant directives
+ * (panel, nodes, toggle buttons) via the `KJ_TREE_SELECT` injection token.
+ *
+ * Selection state (current value, membership checks, toggles) is **not**
+ * part of this context — it lives on the shared `KjSelectionModel`
+ * provided by the root and consumed by `KjListItem` via the
+ * `KJ_LIST_NAVIGATOR_CONFIG` plumbing. This interface only carries the
+ * **tree-specific** surface: node data, expansion state, and the public
+ * `selectionMode` input value (used by panel ARIA to drive
+ * `aria-multiselectable`).
+ *
+ * Open/close state lives on the overlay primitives and is not part of this
+ * context — descendants that need it inject `KjOverlayController` directly.
+ */
+export interface KjTreeSelectContext<T = unknown> {
+  /** Stable id for the panel element (used for `aria-controls`). */
+  readonly panelId: string;
+  /** Current selection mode: `'single'` or `'multiple'`. */
+  readonly selectionMode: Signal<'single' | 'multiple'>;
+  /** Set of node IDs that are currently expanded. */
+  readonly expandedIds: Signal<ReadonlySet<string>>;
+  /** Set of node **values** that are currently expanded. */
+  readonly expandedValues: Signal<ReadonlySet<unknown>>;
+  /** The full tree data. */
+  readonly nodes: Signal<readonly KjTreeNode<T>[]>;
+
+  /**
+   * Toggle expand/collapse for the given node DOM id. Does nothing for leaf
+   * nodes (those without children).
+   */
+  toggleNode(nodeId: string): void;
+  /**
+   * Toggle expand/collapse for a node identified by its **value**. Used by
+   * wrapper components that track expansion by value rather than by DOM id.
+   */
+  toggleNodeByValue(value: T): void;
+  /** Returns `true` when the node with the given DOM id is expanded. */
+  isExpanded(nodeId: string): boolean;
+  /** Returns `true` when the given value is in the expanded values set. */
+  isValueExpanded(value: T): boolean;
+}
+
+/** Injection token providing the nearest `KjTreeSelect` context to descendants. */
+export const KJ_TREE_SELECT = new InjectionToken<KjTreeSelectContext>('KjTreeSelect');

package/src/tree-select/tree-select.spec.ts

@@ -0,0 +1,433 @@
+import { render, fireEvent } from '@testing-library/angular';
+import { By } from '@angular/platform-browser';
+import { toHaveNoViolations } from 'jest-axe';
+import { afterEach } from 'vitest';
+import {
+  KjTreeSelect,
+  KjTreeSelectNode,
+  KjTreeSelectToggle,
+} from './tree-select';
+import { KjTreeSelectTrigger } from './tree-select-trigger';
+import { KjTreeSelectContent } from './tree-select-content';
+import { KJ_LIST_NAVIGATOR_CONFIG } from '../primitives/list';
+
+expect.extend(toHaveNoViolations);
+
+// Sweep portalled overlay wrappers between tests. The body-portal
+// mount strategy detaches them on overlay close, but if a test ends
+// while the panel is still open the wrapper survives in `document.body`
+// and pollutes subsequent `document.querySelector` calls.
+afterEach(() => {
+  document
+    .querySelectorAll('.kj-overlay-wrapper, .kj-overlay-container')
+    .forEach(w => w.remove());
+});
+
+const imports = [
+  KjTreeSelect,
+  KjTreeSelectTrigger,
+  KjTreeSelectContent,
+  KjTreeSelectNode,
+  KjTreeSelectToggle,
+];
+
+// The overlay uses the body-portal mount strategy, so on open the panel
+// (and all of its tree-node children) move from the test `container`
+// into a per-overlay wrapper inside `document.body`. Pre-open queries
+// happily use the test `container`; post-open queries must scope to
+// `document` (or fall back to `container` when the portal is closed).
+const q = (sel: string): Element | null =>
+  document.querySelector(sel) ?? null;
+const qa = (sel: string): NodeListOf<Element> => document.querySelectorAll(sel);
+
+// ── Base single-select template ──────────────────────────────────────────────
+
+const singleTemplate = `
+  <div kjTreeSelect [(kjValue)]="selected">
+    <button kjTreeSelectTrigger #t="kjTreeSelectTrigger">Choose</button>
+    <kj-tree-select-content [kjFor]="t">
+      <div
+        kjTreeSelectNode
+        [kjValue]="'fruits'"
+        kjLabel="Fruits"
+        [kjHasChildren]="true"
+        [kjNodeLevel]="1" [kjNodeSize]="2" [kjNodePos]="1"
+      >
+        <button kjTreeSelectToggle type="button">▶</button>
+        <span>Fruits</span>
+        <div
+          kjTreeSelectNode
+          [kjValue]="'apple'"
+          kjLabel="Apple"
+          [kjNodeLevel]="2" [kjNodeSize]="2" [kjNodePos]="1"
+        >Apple</div>
+        <div
+          kjTreeSelectNode
+          [kjValue]="'banana'"
+          kjLabel="Banana"
+          [kjNodeLevel]="2" [kjNodeSize]="2" [kjNodePos]="2"
+        >Banana</div>
+      </div>
+      <div
+        kjTreeSelectNode
+        [kjValue]="'veggies'"
+        kjLabel="Vegetables"
+        [kjNodeLevel]="1" [kjNodeSize]="2" [kjNodePos]="2"
+      >Vegetables</div>
+    </kj-tree-select-content>
+  </div>
+`;
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe('KjTreeSelect – panel visibility', () => {
+  it('panel is hidden by default', async () => {
+    const { container } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    expect(container.querySelector('kj-tree-select-content')).toHaveAttribute('hidden', '');
+  });
+
+  it('clicking the trigger opens the panel', async () => {
+    const { container } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    fireEvent.click(container.querySelector('[kjTreeSelectTrigger]')!);
+    // Panel is portalled to body on open — query via `document`.
+    expect(q('kj-tree-select-content')).not.toHaveAttribute('hidden');
+  });
+
+  it('aria-expanded on trigger reflects open state', async () => {
+    const { container } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    const trigger = container.querySelector('[kjTreeSelectTrigger]')!;
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    fireEvent.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('Escape closes the panel', async () => {
+    const { container } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    fireEvent.click(container.querySelector('[kjTreeSelectTrigger]')!);
+    fireEvent.keyDown(document, { key: 'Escape' });
+    // `KjOverlayController.close` schedules its DOM teardown inside a
+    // requestAnimationFrame (so consumers can animate close transitions
+    // without panicking the state machine). Wait one RAF before we
+    // assert on the final `hidden` attribute. Once closed, the panel
+    // is detached/hidden regardless of which parent currently holds
+    // it — query against `document` so the assertion stays
+    // intent-preserving.
+    await new Promise<void>(r => requestAnimationFrame(() => r()));
+    expect(q('kj-tree-select-content')).toHaveAttribute('hidden', '');
+  });
+});
+
+describe('KjTreeSelect – trigger ARIA', () => {
+  it('trigger has role="combobox" and aria-haspopup="tree"', async () => {
+    const { container } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    const trigger = container.querySelector('[kjTreeSelectTrigger]')!;
+    expect(trigger).toHaveAttribute('role', 'combobox');
+    expect(trigger).toHaveAttribute('aria-haspopup', 'tree');
+  });
+});
+
+describe('KjTreeSelect – panel ARIA', () => {
+  it('panel has role="tree"', async () => {
+    const { container } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    expect(container.querySelector('kj-tree-select-content')).toHaveAttribute('role', 'tree');
+  });
+
+  it('nodes carry role="treeitem"', async () => {
+    const { container } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    const nodes = container.querySelectorAll('[kjTreeSelectNode]');
+    nodes.forEach(n => expect(n).toHaveAttribute('role', 'treeitem'));
+  });
+
+  it('branch node has aria-expanded="false" when collapsed', async () => {
+    const { container } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    const branchNode = container.querySelector('[kjTreeSelectNode][data-has-children="true"]')!;
+    expect(branchNode).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('node host element has an id minted by the composed KjListItem', async () => {
+    const { container } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    const node = container.querySelector('[kjTreeSelectNode]')!;
+    // KjListItem auto-mints `kj-list-item-N` ids unless an `id` is
+    // already set on the host element.
+    expect(node.id).toMatch(/^kj-list-item-\d+$/);
+  });
+});
+
+describe('KjTreeSelect – expand / collapse', () => {
+  it('clicking the toggle button expands the branch node', async () => {
+    const { container } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    fireEvent.click(container.querySelector('[kjTreeSelectTrigger]')!);
+    const toggle = q('[kjTreeSelectToggle]')!;
+    fireEvent.click(toggle);
+    const branchNode = q('[kjTreeSelectNode][data-has-children="true"]')!;
+    expect(branchNode).toHaveAttribute('aria-expanded', 'true');
+    expect(branchNode).toHaveAttribute('data-expanded', 'true');
+  });
+
+  it('clicking toggle again collapses the branch', async () => {
+    const { container } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    fireEvent.click(container.querySelector('[kjTreeSelectTrigger]')!);
+    const toggle = q('[kjTreeSelectToggle]')!;
+    fireEvent.click(toggle);
+    fireEvent.click(toggle);
+    const branchNode = q('[kjTreeSelectNode][data-has-children="true"]')!;
+    expect(branchNode).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('toggle click does not select the branch node', async () => {
+    const { container, fixture } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    fireEvent.click(container.querySelector('[kjTreeSelectTrigger]')!);
+    const toggle = q('[kjTreeSelectToggle]')!;
+    fireEvent.click(toggle);
+    fixture.detectChanges();
+    expect(q('kj-tree-select-content')).not.toHaveAttribute('hidden');
+  });
+});
+
+describe('KjTreeSelect – single selection', () => {
+  it('clicking a leaf node selects it and closes the panel', async () => {
+    const { container, fixture } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    fireEvent.click(container.querySelector('[kjTreeSelectTrigger]')!);
+    const leafNode = q('[kjTreeSelectNode][aria-level="2"]')!;
+    // Capture the node's id before activation so we can find it again
+    // post-close (panel may be portalled back to its original slot, or
+    // remain in the body wrapper — `document.querySelector` covers
+    // both placements).
+    const leafId = leafNode.id;
+    fireEvent.click(leafNode);
+    fixture.detectChanges();
+    // `KjOverlayController.close` schedules its DOM teardown inside a
+    // requestAnimationFrame — wait one RAF before asserting on
+    // `hidden`.
+    await new Promise<void>(r => requestAnimationFrame(() => r()));
+    expect(q('kj-tree-select-content')).toHaveAttribute('hidden', '');
+    const refoundLeaf = q(`#${leafId}`)!;
+    expect(refoundLeaf).toHaveAttribute('aria-selected', 'true');
+    expect(refoundLeaf).toHaveAttribute('data-selected', '');
+  });
+
+  it('aria-selected="false" on unselected nodes', async () => {
+    const { container } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    const nodes = container.querySelectorAll('[kjTreeSelectNode]');
+    nodes.forEach(n => expect(n).toHaveAttribute('aria-selected', 'false'));
+  });
+
+  it('clicking a different node updates the selection', async () => {
+    const { container, fixture } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    fireEvent.click(container.querySelector('[kjTreeSelectTrigger]')!);
+    const initial = qa('[kjTreeSelectNode][aria-level="2"]');
+    const firstId = initial[0].id;
+    const secondId = initial[1].id;
+    fireEvent.click(initial[0]);
+    fixture.detectChanges();
+
+    fireEvent.click(container.querySelector('[kjTreeSelectTrigger]')!);
+    fixture.detectChanges();
+    expect(q(`#${firstId}`)).toHaveAttribute('aria-selected', 'true');
+    expect(q(`#${secondId}`)).toHaveAttribute('aria-selected', 'false');
+  });
+});
+
+describe('KjTreeSelect – multi selection', () => {
+  const multiTemplate = `
+    <div kjTreeSelect [(kjValue)]="selected" kjSelectionMode="multiple">
+      <button kjTreeSelectTrigger #t="kjTreeSelectTrigger">Choose</button>
+      <kj-tree-select-content [kjFor]="t">
+        <div kjTreeSelectNode [kjValue]="'a'" kjLabel="A" [kjNodeLevel]="1" [kjNodeSize]="3" [kjNodePos]="1">A</div>
+        <div kjTreeSelectNode [kjValue]="'b'" kjLabel="B" [kjNodeLevel]="1" [kjNodeSize]="3" [kjNodePos]="2">B</div>
+        <div kjTreeSelectNode [kjValue]="'c'" kjLabel="C" [kjNodeLevel]="1" [kjNodeSize]="3" [kjNodePos]="3">C</div>
+      </kj-tree-select-content>
+    </div>
+  `;
+
+  it('panel stays open after selecting a node', async () => {
+    const { container } = await render(multiTemplate, {
+      imports,
+      componentProperties: { selected: [] },
+    });
+    fireEvent.click(container.querySelector('[kjTreeSelectTrigger]')!);
+    const nodes = qa('[kjTreeSelectNode]');
+    fireEvent.click(nodes[0]);
+    expect(q('kj-tree-select-content')).not.toHaveAttribute('hidden');
+  });
+
+  it('panel has aria-multiselectable="true"', async () => {
+    const { container } = await render(multiTemplate, {
+      imports,
+      componentProperties: { selected: [] },
+    });
+    expect(container.querySelector('kj-tree-select-content')).toHaveAttribute(
+      'aria-multiselectable', 'true',
+    );
+  });
+
+  it('selecting multiple nodes accumulates the selection', async () => {
+    const { container, fixture } = await render(multiTemplate, {
+      imports,
+      componentProperties: { selected: [] },
+    });
+    fireEvent.click(container.querySelector('[kjTreeSelectTrigger]')!);
+    const nodes = qa('[kjTreeSelectNode]');
+    fireEvent.click(nodes[0]);
+    fireEvent.click(nodes[2]);
+    fixture.detectChanges();
+    expect(nodes[0]).toHaveAttribute('aria-selected', 'true');
+    expect(nodes[1]).toHaveAttribute('aria-selected', 'false');
+    expect(nodes[2]).toHaveAttribute('aria-selected', 'true');
+  });
+
+  it('clicking a selected node deselects it', async () => {
+    const { container, fixture } = await render(multiTemplate, {
+      imports,
+      componentProperties: { selected: [] },
+    });
+    fireEvent.click(container.querySelector('[kjTreeSelectTrigger]')!);
+    const nodes = qa('[kjTreeSelectNode]');
+    fireEvent.click(nodes[0]);
+    fireEvent.click(nodes[0]);
+    fixture.detectChanges();
+    expect(nodes[0]).toHaveAttribute('aria-selected', 'false');
+  });
+
+  it('single mode panel does not have aria-multiselectable', async () => {
+    const { container } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    const panel = container.querySelector('kj-tree-select-content')!;
+    expect(panel).not.toHaveAttribute('aria-multiselectable');
+  });
+});
+
+describe('KjTreeSelect – disabled node', () => {
+  const disabledTemplate = `
+    <div kjTreeSelect [(kjValue)]="selected">
+      <button kjTreeSelectTrigger #t="kjTreeSelectTrigger">Choose</button>
+      <kj-tree-select-content [kjFor]="t">
+        <div kjTreeSelectNode [kjValue]="'x'" kjLabel="X" kjDisabled [kjNodeLevel]="1" [kjNodeSize]="1" [kjNodePos]="1">X</div>
+      </kj-tree-select-content>
+    </div>
+  `;
+
+  it('disabled node has aria-disabled="true"', async () => {
+    const { container } = await render(disabledTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    const node = container.querySelector('[kjTreeSelectNode]')!;
+    expect(node).toHaveAttribute('aria-disabled', 'true');
+  });
+
+  it('disabled node does not change the selection when clicked', async () => {
+    const { container, fixture } = await render(disabledTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    fireEvent.click(container.querySelector('[kjTreeSelectTrigger]')!);
+    const node = q('[kjTreeSelectNode]')!;
+    fireEvent.click(node);
+    fixture.detectChanges();
+    expect(node).toHaveAttribute('aria-selected', 'false');
+  });
+});
+
+describe('KjTreeSelect – KjListNavigatorConfig integration', () => {
+  it('provides KJ_LIST_NAVIGATOR_CONFIG that reads/writes the kjValue model', async () => {
+    const { fixture } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    const rootDe = fixture.debugElement.query(By.directive(KjTreeSelect));
+    const cfg = rootDe.injector.get(KJ_LIST_NAVIGATOR_CONFIG);
+    expect(cfg.value).toBeDefined();
+    cfg.value!.set('apple');
+    fixture.detectChanges();
+    expect((fixture.componentInstance as { selected: unknown }).selected).toBe('apple');
+  });
+});
+
+describe('KjTreeSelect – keyboard navigation', () => {
+  // Post-Task-4: Up/Down/Home/End/Enter/Space/type-ahead are owned by
+  // the composed `KjListNavigator`; tree-specific ArrowLeft/Right stay
+  // on `KjTreeSelectContent`. Roving DOM focus is wired by the content
+  // component via a local effect on `KjListNavigator.activeId` plus a
+  // `KJ_LIST_FOCUS_MODE` provider override (Angular's
+  // `hostDirectives.inputs` cannot statically push `'roving'` into the
+  // navigator's input signal). Net effect for these tests: keyboard
+  // moves `activeId` → DOM focus follows → `activeElement` matches.
+  it('ArrowDown on the panel moves focus to the first node', async () => {
+    const { container } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    fireEvent.click(container.querySelector('[kjTreeSelectTrigger]')!);
+    const panel = q('kj-tree-select-content')!;
+    fireEvent.keyDown(panel, { key: 'ArrowDown' });
+    const nodes = qa('[kjTreeSelectNode]');
+    expect(document.activeElement).toBe(nodes[0]);
+  });
+
+  it('Enter on focused node selects it', async () => {
+    const { container, fixture } = await render(singleTemplate, {
+      imports,
+      componentProperties: { selected: undefined },
+    });
+    fireEvent.click(container.querySelector('[kjTreeSelectTrigger]')!);
+    const leafNode = q('[kjTreeSelectNode][aria-level="2"]')!;
+    const leafId = leafNode.id;
+    fireEvent.keyDown(leafNode, { key: 'Enter' });
+    fixture.detectChanges();
+    // Enter routes through the content keydown handler, which calls
+    // `node.click()` — `KjListItem`'s `(click)` runs `_activate` →
+    // `KjSelectionModel.toggle` → root `afterSelect` closes the panel
+    // (single mode). Look up by id via `document` so we don't depend
+    // on whether the panel has been re-parented yet.
+    const refoundLeaf = q(`#${leafId}`)!;
+    expect(refoundLeaf).toHaveAttribute('aria-selected', 'true');
+  });
+});

package/src/tree-select/tree-select.ts

@@ -0,0 +1,2 @@
+export { KjTreeSelect } from './tree-select-root';
+export { KjTreeSelectNode, KjTreeSelectToggle } from './tree-select-node';

package/src/typography/blockquote.ts

@@ -0,0 +1,57 @@
+import {
+  Directive,
+  ElementRef,
+  afterNextRender,
+  inject,
+  isDevMode,
+} from '@angular/core';
+
+/**
+ * Applies kouji's blockquote tone — left rule, italic, indent — to a
+ * `<blockquote>` element. Reflects `data-tone="blockquote"`. Useful when
+ * the blockquote sits *outside* a `kj-prose` container (the prose container
+ * styles its own `<blockquote>` descendants automatically).
+ *
+ * Recommended host is `<blockquote>` to preserve native semantics; applied
+ * to a non-`<blockquote>` host the directive emits a dev-mode warning but
+ * does not enforce the tag.
+ *
+ * @example
+ * ```html
+ * <blockquote kjBlockquote>
+ *   "kouji-ui shipped on the day they said it would."
+ * </blockquote>
+ * ```
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name typography
+ * @doc-description Styles a standalone blockquote outside a prose container with the kouji quotation tone.
+ * @doc-is-main
+ */
+@Directive({
+  selector: '[kjBlockquote]',
+  standalone: true,
+  exportAs: 'kjBlockquote',
+  host: {
+    '[attr.data-tone]': '"blockquote"',
+  },
+})
+export class KjBlockquote {
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  constructor() {
+    if (isDevMode()) {
+      afterNextRender(() => {
+        const host = this.el.nativeElement;
+        if (host.tagName?.toLowerCase() !== 'blockquote') {
+          console.warn(
+            `[kj] kjBlockquote applied to <${host.tagName?.toLowerCase()}>. ` +
+              `Recommended host element is <blockquote> for native semantics ` +
+              `(WCAG 1.3.1 / 4.1.2). Apply only to non-blockquote elements ` +
+              `when you have a specific styling reason.`,
+          );
+        }
+      });
+    }
+  }
+}

package/src/typography/code.ts

@@ -0,0 +1,53 @@
+import {
+  Directive,
+  ElementRef,
+  afterNextRender,
+  inject,
+  isDevMode,
+} from '@angular/core';
+
+/**
+ * Marks an inline `<code>` element with kouji's inline-code tone — monospace
+ * font, subtle background fill, and inline padding. Reflects
+ * `data-tone="code"`. The directive does not handle multi-line `<pre><code>`
+ * blocks; those are styled by the prose container's `pre code` selector or
+ * by a consumer-wired syntax highlighter.
+ *
+ * Recommended host is `<code>` to preserve native semantics; applying
+ * `[kjCode]` to a different element is dev-mode warned but not enforced.
+ *
+ * @example
+ * ```html
+ * <p>Run <code kjCode>npm install @kouji-ui/core</code> to install.</p>
+ * ```
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name typography
+ */
+@Directive({
+  selector: '[kjCode]',
+  standalone: true,
+  exportAs: 'kjCode',
+  host: {
+    '[attr.data-tone]': '"code"',
+  },
+})
+export class KjCode {
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  constructor() {
+    if (isDevMode()) {
+      afterNextRender(() => {
+        const host = this.el.nativeElement;
+        if (host.tagName?.toLowerCase() !== 'code') {
+          console.warn(
+            `[kj] kjCode applied to <${host.tagName?.toLowerCase()}>. ` +
+              `Recommended host element is <code> for native semantics ` +
+              `(WCAG 1.3.1 / 4.1.2). Apply only to non-code elements when ` +
+              `you have a specific styling reason.`,
+          );
+        }
+      });
+    }
+  }
+}

package/src/typography/index.ts

@@ -0,0 +1,22 @@
+export { KjLead } from './lead';
+export { KjMuted } from './muted';
+export { KjCode } from './code';
+export { KjBlockquote } from './blockquote';
+export { KjTruncate } from './truncate';
+
+/**
+ * Resolvable path to the kouji prose stylesheet. Consumers import the CSS
+ * once at the application root:
+ *
+ * ```ts
+ * import { KJ_PROSE_CSS_PATH } from '@kouji-ui/core';
+ * // or import the file directly:
+ * import '@kouji-ui/core/typography/prose.css';
+ * ```
+ *
+ * The path is exposed as a string so build tools can locate the file via
+ * `require.resolve(KJ_PROSE_CSS_PATH)` when programmatic resolution is
+ * needed (for example, when wiring the stylesheet into a docs-site
+ * pipeline).
+ */
+export const KJ_PROSE_CSS_PATH = '@kouji-ui/core/typography/prose.css';

package/src/typography/lead.ts

@@ -0,0 +1,49 @@
+import {
+  Directive,
+  ElementRef,
+  afterNextRender,
+  inject,
+  isDevMode,
+} from '@angular/core';
+
+/**
+ * Marks a paragraph as the lead-in paragraph for a section — slightly larger
+ * size with a softer tone. Reflects `data-tone="lead"` so theme CSS keys off
+ * it; the directive owns no styling itself.
+ *
+ * Lead semantics are paragraph-bound; applied to a non-`<p>` host the
+ * directive emits a dev-mode warning but does not enforce the tag.
+ *
+ * @example
+ * ```html
+ * <p kjLead>Atlas helps engineering teams plan quarterly roadmaps.</p>
+ * ```
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name typography
+ */
+@Directive({
+  selector: '[kjLead]',
+  standalone: true,
+  exportAs: 'kjLead',
+  host: {
+    '[attr.data-tone]': '"lead"',
+  },
+})
+export class KjLead {
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  constructor() {
+    if (isDevMode()) {
+      afterNextRender(() => {
+        const host = this.el.nativeElement;
+        if (host.tagName?.toLowerCase() !== 'p') {
+          console.warn(
+            `[kj] kjLead applied to <${host.tagName?.toLowerCase()}>. ` +
+              `Lead semantics are paragraph-bound; recommended host is <p>.`,
+          );
+        }
+      });
+    }
+  }
+}