@kouji-ui/components 0.1.1

package/src/typography/typography.playground.ts

@@ -0,0 +1,101 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjLead, KjMuted, KjCode, KjBlockquote, KjTruncate } from '@kouji-ui/core';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Knobs select which typographic
+ * sample to show inside a `.kj-prose` container.
+ */
+const sample = signal<'prose' | 'lead' | 'muted' | 'code' | 'blockquote' | 'truncate'>('prose');
+const truncateLines = signal<1 | 2 | 3>(2);
+
+@Component({
+  selector: 'kj-typography-playground',
+  standalone: true,
+  imports: [KjLead, KjMuted, KjCode, KjBlockquote, KjTruncate],
+  template: `
+    <article class="kj-prose">
+      @switch (sample()) {
+        @case ('prose') {
+          <h1>kouji typography</h1>
+          <p>
+            Drop the <code>.kj-prose</code> container around any flow content and
+            every descendant heading, paragraph, list, and inline element is
+            restyled by the kouji type system.
+          </p>
+        }
+        @case ('lead') {
+          <p kjLead>
+            A lead-in paragraph carries softer tone and a touch more size — used
+            once near the top of an article.
+          </p>
+        }
+        @case ('muted') {
+          <p><span kjMuted>Last updated 3 minutes ago.</span></p>
+        }
+        @case ('code') {
+          <p>Install with <code kjCode>pnpm add &#64;kouji-ui/components</code> and import the directive.</p>
+        }
+        @case ('blockquote') {
+          <blockquote kjBlockquote>
+            Typography is the craft of endowing human language with a durable visual form.
+          </blockquote>
+        }
+        @case ('truncate') {
+          <p [kjTruncate]="truncateLines()">
+            A long line of body copy that gets clamped to the requested number of
+            lines via the line-clamp tokens — useful inside cards, list rows, and
+            other constrained layouts where overflow matters more than full
+            disclosure.
+          </p>
+        }
+      }
+    </article>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjTypographyPlaygroundDemo {
+  protected readonly sample = sample;
+  protected readonly truncateLines = truncateLines;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjTypographyPlaygroundDemo,
+  state: {
+    sample: sample as unknown as ReturnType<typeof signal>,
+    truncateLines: truncateLines as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    {
+      kind: 'chips',
+      name: 'sample',
+      label: 'sample',
+      options: ['prose', 'lead', 'muted', 'code', 'blockquote', 'truncate'],
+    },
+    { kind: 'chips', name: 'truncateLines', label: 'truncate lines', options: [1, 2, 3] },
+  ],
+  snippet: (values) => {
+    const s = values as { sample: string; truncateLines: number };
+    let body: string;
+    switch (s.sample) {
+      case 'lead':
+        body = `  <p kjLead>A lead-in paragraph carries softer tone and a touch more size.</p>`;
+        break;
+      case 'muted':
+        body = `  <p><span kjMuted>Last updated 3 minutes ago.</span></p>`;
+        break;
+      case 'code':
+        body = `  <p>Install with <code kjCode>pnpm add &#64;kouji-ui/components</code>.</p>`;
+        break;
+      case 'blockquote':
+        body = `  <blockquote kjBlockquote>Typography is the craft of endowing language with form.</blockquote>`;
+        break;
+      case 'truncate':
+        body = `  <p [kjTruncate]="${s.truncateLines}">A long line of body copy clamped to ${s.truncateLines} line${s.truncateLines === 1 ? '' : 's'}.</p>`;
+        break;
+      default:
+        body = `  <h1>kouji typography</h1>\n  <p>Drop <code>.kj-prose</code> around flow content to apply the type system.</p>`;
+    }
+    return `<article class="kj-prose">\n${body}\n</article>`;
+  },
+};

package/src/typography/typography.spec.ts

@@ -0,0 +1,70 @@
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, test } from 'vitest';
+import {
+  KjTypographyExample,
+  KjTypographyLeadExample,
+  KjTypographyMutedExample,
+  KjTypographyCodeExample,
+  KjTypographyBlockquoteExample,
+  KjTypographyTruncateExample,
+} from './_examples';
+
+/**
+ * Smoke tests for the Typography live-preview examples. The component-side
+ * surface is just re-exports + examples (no wrapper component to unit-test);
+ * we verify the examples render and the directive host attributes land where
+ * theme CSS expects them.
+ */
+async function flushAfterNextRender(): Promise<void> {
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+describe('Typography examples', () => {
+  test('prose container example renders with the kj-prose class', () => {
+    const fixture = TestBed.createComponent(KjTypographyExample);
+    fixture.detectChanges();
+    const article = fixture.nativeElement.querySelector('article.kj-prose');
+    expect(article).not.toBeNull();
+    expect(fixture.nativeElement.querySelector('h1')?.textContent).toMatch(/Roadmap/i);
+    expect(fixture.nativeElement.querySelector('blockquote')).not.toBeNull();
+  });
+
+  test('lead example reflects data-tone="lead" on the <p> host', () => {
+    const fixture = TestBed.createComponent(KjTypographyLeadExample);
+    fixture.detectChanges();
+    const lead = fixture.nativeElement.querySelector('p[data-tone="lead"]');
+    expect(lead).not.toBeNull();
+  });
+
+  test('muted example reflects data-tone="muted" on each <span> host', () => {
+    const fixture = TestBed.createComponent(KjTypographyMutedExample);
+    fixture.detectChanges();
+    const mutedNodes = fixture.nativeElement.querySelectorAll('span[data-tone="muted"]');
+    expect(mutedNodes.length).toBe(2);
+  });
+
+  test('code example reflects data-tone="code" on each <code> host', () => {
+    const fixture = TestBed.createComponent(KjTypographyCodeExample);
+    fixture.detectChanges();
+    const codeNodes = fixture.nativeElement.querySelectorAll('code[data-tone="code"]');
+    expect(codeNodes.length).toBe(2);
+  });
+
+  test('blockquote example reflects data-tone="blockquote" on the host', () => {
+    const fixture = TestBed.createComponent(KjTypographyBlockquoteExample);
+    fixture.detectChanges();
+    const bq = fixture.nativeElement.querySelector('blockquote[data-tone="blockquote"]');
+    expect(bq).not.toBeNull();
+  });
+
+  test('truncate example reflects data-truncate="2" and injects [title]', async () => {
+    const fixture = TestBed.createComponent(KjTypographyTruncateExample);
+    fixture.detectChanges();
+    await flushAfterNextRender();
+    const clamped = fixture.nativeElement.querySelector('p[data-truncate="2"]');
+    expect(clamped).not.toBeNull();
+    expect(clamped?.getAttribute('title')).toMatch(/Atlas/);
+  });
+});

package/src/typography/typography.ts

@@ -0,0 +1,105 @@
+import { Directive } from '@angular/core';
+
+/**
+ * Documentation marker for the kouji typography surface.
+ *
+ * Typography ships **no wrapper components**. The user-facing surface is:
+ *
+ * - The `kj-prose` CSS class (applied to a wrapping container) which restyles
+ *   every descendant flow element according to the kouji type system.
+ * - Five attribute directives — `kjLead`, `kjMuted`, `kjCode`, `kjBlockquote`,
+ *   `kjTruncate` — that reflect `data-tone` / `data-truncate` host attributes
+ *   so the same styling applies whether the consumer used the directive,
+ *   hand-typed `data-tone="muted"` on a span, or wrapped a subtree in
+ *   `.kj-prose`.
+ *
+ * This class exists **only** to host the live-preview examples and category
+ * metadata for the docs extractor. It exposes no template, selector behaviour,
+ * inputs, or outputs — and is never meant to be applied in consumer code.
+ * Consumers import the directives directly via the package barrel.
+ *
+ * @example
+ * ```html
+ * <article class="kj-prose">
+ *   <h1>Heading</h1>
+ *   <p kjLead>Lead-in paragraph.</p>
+ *   <p>Body copy with <code kjCode>npm install</code> inline.</p>
+ *   <blockquote kjBlockquote>Pulled-out quotation.</blockquote>
+ *   <p [kjTruncate]="2">A long line that should clamp to two lines.</p>
+ *   <p><span kjMuted>Last updated 3 minutes ago.</span></p>
+ * </article>
+ * ```
+ * @doc-example Prose container
+ *   The default playground — drop `.kj-prose` on an `<article>` to restyle
+ *   every descendant flow element with the kouji type system.
+ *   @doc-file typography.example.ts
+ * @doc-example Usage
+ *   A walkthrough of the most common typography usages — prose container,
+ *   `kjLead` paragraph, `kjMuted` aside, inline `kjCode`, and a `kjTruncate`
+ *   block clamped to two lines.
+ *   @doc-file typography.usage.example.ts
+ * @doc-example Lead paragraph
+ *   `kjLead` reflects `data-tone="lead"` on a paragraph — softer tone, larger size.
+ *   @doc-file typography.lead.example.ts
+ * @doc-example Muted text
+ *   `kjMuted` reflects `data-tone="muted"` — dims the foreground for secondary copy.
+ *   @doc-file typography.muted.example.ts
+ * @doc-example Inline code
+ *   `kjCode` styles inline `<code>` runs with the mono token + a subtle surface.
+ *   @doc-file typography.code.example.ts
+ * @doc-example Blockquote
+ *   `kjBlockquote` applies the pull-quote treatment to a `<blockquote>`.
+ *   @doc-file typography.blockquote.example.ts
+ * @doc-example Truncate (multi-line)
+ *   `[kjTruncate]="n"` clamps text to `n` lines via the line-clamp tokens.
+ *   @doc-file typography.truncate.example.ts
+ *
+ * @doc-keyboard
+ *   — — Typography is non-interactive. Inline `<a>` anchors keep native
+ *     Tab / Enter behaviour from the browser.
+ *
+ * @doc-aria
+ *   data-tone     — Reflected by `kjLead` / `kjMuted` so the same styling
+ *                   applies whether the consumer used the directive or
+ *                   hand-typed the attribute on a span
+ *   data-truncate — Reflected by `kjTruncate` with the line count, e.g. "2"
+ *
+ * @doc-touch
+ *   — — Non-interactive surface. Inline links inherit the page's link tokens
+ *     which meet the 24×24 / 44×44 floors per theme.
+ *
+ * @doc-a11y
+ *   The directives carry no role or focus — they're purely visual. Headings
+ *   inside `.kj-prose` keep their native `<h1>`–`<h6>` semantics so AT users
+ *   can navigate by heading level. `kjTruncate` does not hide content from
+ *   AT — the full text remains in the accessibility tree, only the visual
+ *   clamp applies.
+ *
+ * @doc-related card,field,divider
+ *
+ * @doc-css-var
+ *   --kj-prose-fg           — Default foreground (body copy) inside `.kj-prose`.
+ *   --kj-prose-fg-muted     — Foreground for `kjMuted` runs and secondary copy.
+ *   --kj-prose-link         — Link color inside prose blocks.
+ *   --kj-prose-code-bg      — Background for inline `kjCode` runs.
+ *   --kj-prose-code-fg      — Foreground for inline `kjCode` runs.
+ *   --kj-prose-quote-border — Left rule color on `kjBlockquote`.
+ *   --kj-prose-h1-size      — Font size for `<h1>` inside `.kj-prose`.
+ *   --kj-prose-h2-size      — Font size for `<h2>` inside `.kj-prose`.
+ *   --kj-prose-h3-size      — Font size for `<h3>` inside `.kj-prose`.
+ *   --kj-prose-line-height  — Line height for body copy inside `.kj-prose`.
+ *   --kj-prose-measure      — Maximum line length (CSS `max-width`) for prose blocks.
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name typography
+ * @doc-description Themed typography system for prose containers and individual lead, muted, code, quote, and truncate text.
+ * @doc-is-main
+ */
+@Directive({
+  // Selector is intentionally namespaced so it never matches consumer
+  // markup. The class is a docs-only marker; no behaviour is wired.
+  selector: '[kjTypographyDocsMarker]',
+  standalone: true,
+})
+export class KjTypographyDocs {}

package/tsconfig.lib.json

@@ -0,0 +1,25 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/lib",
+    "declaration": true,
+    "declarationMap": true,
+    "types": [],
+    "baseUrl": ".",
+    "paths": {
+      "@kouji-ui/core": ["../../dist/kj-core/types/kouji-ui-core"]
+    }
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["**/*.spec.ts"],
+  "angularCompilerOptions": {
+    "extendedDiagnostics": {
+      "checks": {
+        "nullishCoalescingNotNullable": "suppress",
+        "optionalChainNotNullable": "suppress"
+      }
+    }
+  }
+}

package/tsconfig.lib.prod.json

@@ -0,0 +1,17 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "./tsconfig.lib.json",
+  "compilerOptions": {
+    "declarationMap": false
+  },
+  "angularCompilerOptions": {
+    "compilationMode": "partial",
+    "extendedDiagnostics": {
+      "checks": {
+        "nullishCoalescingNotNullable": "suppress",
+        "optionalChainNotNullable": "suppress"
+      }
+    }
+  }
+}

package/tsconfig.spec.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/spec",
+    "types": ["vitest/globals"]
+  },
+  "include": ["src/**/*.d.ts", "src/**/*.spec.ts"],
+  "angularCompilerOptions": {
+    "extendedDiagnostics": {
+      "checks": {
+        "nullishCoalescingNotNullable": "suppress",
+        "optionalChainNotNullable": "suppress"
+      }
+    }
+  }
+}

package/vite.config.ts

@@ -0,0 +1,33 @@
+import { defineProject } from 'vitest/config';
+import angular from '@analogjs/vite-plugin-angular';
+import { resolve } from 'node:path';
+
+export default defineProject({
+  plugins: [angular()],
+  resolve: {
+    alias: [
+      { find: /^@kouji-ui\/core\/(.*)$/, replacement: resolve(__dirname, '../core/src/$1') },
+      { find: '@kouji-ui/core', replacement: resolve(__dirname, '../core/src/public-api.ts') },
+    ],
+  },
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['src/test-setup.ts'],
+    include: ['src/**/*.spec.ts'],
+    reporters: ['default'],
+    // Threads beat forks on Windows; isolate:false reuses jsdom + Angular
+    // TestBed env per worker across files.
+    pool: 'threads',
+    isolate: false,
+    fileParallelism: true,
+    minWorkers: 1,
+    maxWorkers: 2,
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.spec.ts', 'src/test-setup.ts'],
+    },
+  },
+});