@kouji-ui/components 0.1.1

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

@@ -0,0 +1,348 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  booleanAttribute,
+  computed,
+  inject,
+  input,
+} from '@angular/core';
+import {
+  KjTreeSelect,
+  KjTreeSelectContent,
+  KjTreeSelectNode,
+  KjTreeSelectToggle,
+  KjTreeSelectTrigger,
+  type KjTreeNode,
+} from '@kouji-ui/core';
+
+// ── Flat-tree projection ──────────────────────────────────────────────────────
+
+/**
+ * Internal flat row produced by walking the tree. The wrapper renders a flat
+ * list rather than nested DOM to avoid recursive component issues; indentation
+ * is applied via `padding-inline-start`.
+ */
+interface FlatNode {
+  node: KjTreeNode;
+  level: number;
+  size: number;
+  pos: number;
+  hasChildren: boolean;
+  /** Path of ancestor values — used to determine visibility when ancestors collapse. */
+  ancestorValues: readonly unknown[];
+}
+
+/** Walk the tree into a flat array. All nodes are included; visibility is
+ * determined at render time by checking ancestor expansion state. */
+function flattenTree(
+  nodes: readonly KjTreeNode[],
+  level = 1,
+  ancestors: readonly unknown[] = [],
+): FlatNode[] {
+  const result: FlatNode[] = [];
+  const size = nodes.length;
+  nodes.forEach((node, i) => {
+    const hasChildren = !!(node.children && node.children.length > 0);
+    result.push({
+      node,
+      level,
+      size,
+      pos: i + 1,
+      hasChildren,
+      ancestorValues: ancestors,
+    });
+    if (hasChildren && node.children) {
+      result.push(
+        ...flattenTree(node.children as readonly KjTreeNode[], level + 1, [...ancestors, node.value]),
+      );
+    }
+  });
+  return result;
+}
+
+/**
+ * Single styled tree node row for `<kj-tree-select>`. Renders an optional
+ * expand/collapse toggle, a checkbox in multi mode, indentation based on
+ * nesting level, and the node label.
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name tree-select
+ */
+@Component({
+  selector: 'kj-tree-select-node',
+  standalone: true,
+  imports: [KjTreeSelectNode, KjTreeSelectToggle],
+  template: `
+    <div
+      kjTreeSelectNode
+      [kjValue]="value()"
+      [kjLabel]="label()"
+      [kjNodeLevel]="level()"
+      [kjNodeSize]="size()"
+      [kjNodePos]="pos()"
+      [kjDisabled]="disabled()"
+      [kjHasChildren]="hasChildren()"
+      class="kj-tree-select-node"
+      [style.padding-inline-start.rem]="(level() - 1) * 1.25 + 0.75"
+    >
+      @if (hasChildren()) {
+        <button
+          type="button"
+          kjTreeSelectToggle
+          class="kj-tree-select-toggle"
+          aria-hidden="true"
+          tabindex="-1"
+        >
+          <span class="kj-tree-select-toggle-icon"></span>
+        </button>
+      } @else {
+        <span class="kj-tree-select-indent" aria-hidden="true"></span>
+      }
+      @if (multiMode()) {
+        <span class="kj-tree-select-checkbox" aria-hidden="true"></span>
+      }
+      <span class="kj-tree-select-label"><ng-content /></span>
+    </div>
+  `,
+  encapsulation: ViewEncapsulation.None,
+  host: { style: 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjTreeSelectNodeComponent {
+  /** The value this node represents. */
+  readonly value = input.required<unknown>();
+  /** Display label for type-ahead. */
+  readonly label = input<string>('');
+  /** Nesting depth (1-based). */
+  readonly level = input<number>(1);
+  /** Number of siblings at this level. */
+  readonly size = input<number>(1);
+  /** 1-based position among siblings. */
+  readonly pos = input<number>(1);
+  /** Whether the node is disabled. */
+  readonly disabled = input(false, { transform: booleanAttribute });
+  /** Whether the node has children (branch). */
+  readonly hasChildren = input(false, { transform: booleanAttribute });
+  /** Whether the tree is in multi-select mode (renders a checkbox). */
+  readonly multiMode = input(false, { transform: booleanAttribute });
+}
+
+/**
+ * Styled wrapper around the headless `KjTreeSelect` directive family.
+ *
+ * Renders the trigger button showing the selected value label (single mode)
+ * or a count of selected items (multiple mode), and a dropdown tree panel
+ * containing all nodes. Tree data is passed via `[kjNodes]`.
+ *
+ * The component projects the recursive tree into a flat rendered list, using
+ * CSS indentation (`padding-inline-start`) for visual hierarchy — avoiding
+ * recursive component issues while remaining fully accessible via ARIA
+ * `aria-level`, `aria-setsize`, and `aria-posinset` attributes.
+ *
+ * Collapsed branches' children are hidden via `display:none`; all nodes
+ * remain in the DOM to preserve ARIA tree structure.
+ *
+ * @example
+ * ```html
+ * <kj-tree-select [kjNodes]="categories" [(kjValue)]="selected" />
+ * ```
+ *
+ * @doc-example Default
+ *   The default playground — single-select tree with collapsed branches.
+ *   @doc-file tree-select.example.ts
+ * @doc-example Usage
+ *   A walkthrough of the most common tree-select usages — single-select with a
+ *   readout, multi-select with a count, and pre-expanded branches on mount.
+ *   @doc-file tree-select.usage.example.ts
+ * @doc-example Multi-select
+ *   `kjSelectionMode="multiple"` renders a checkbox per row and emits an array.
+ *   @doc-file tree-select.multi.example.ts
+ * @doc-example Pre-expanded
+ *   `[(kjExpandedKeys)]` seeds the open branches on mount.
+ *   @doc-file tree-select.expanded.example.ts
+ * @doc-example In a field
+ *   Compose under `<kj-field>` for label / error / hint association.
+ *   @doc-file tree-select.field.example.ts
+ * @doc-example Disabled
+ *   `[disabled]="true"` removes the trigger from the tab order.
+ *   @doc-file tree-select.disabled.example.ts
+ *
+ * @doc-keyboard
+ *   Enter|Space  — Opens the panel from the trigger; selects the focused node when open
+ *   ArrowDown    — Moves focus to the next visible node
+ *   ArrowUp      — Moves focus to the previous visible node
+ *   ArrowRight   — Expands the focused branch (or moves into its children)
+ *   ArrowLeft    — Collapses the focused branch (or moves to its parent)
+ *   Home|End     — Jumps to the first/last visible node
+ *   Escape       — Closes the panel and returns focus to the trigger
+ *   Type-ahead   — Letters/digits jump to the next matching visible label
+ *
+ * @doc-aria
+ *   role="combobox"   — applied to the trigger button
+ *   role="tree"       — applied to the panel content
+ *   role="treeitem"   — applied to each rendered node
+ *   aria-level / setsize / posinset — wired per node for AT tree semantics
+ *   aria-expanded     — set on branch nodes; mirrors expansion state
+ *   aria-selected     — set on selected nodes
+ *   aria-multiselectable — set on the tree when in multi mode
+ *   data-multi        — Mirrors multi-mode on the host for CSS hooks
+ *
+ * @doc-touch
+ *   Trigger and rows default to a 40px hit area at `md` density. For touch-first
+ *   surfaces, bump the parent's density token to reach the WCAG 2.5.5 floor.
+ *
+ * @doc-a11y
+ *   Implements the WAI-ARIA Tree APG pattern. All nodes stay in the DOM with
+ *   `[hidden]` toggling visibility so the ARIA tree structure (`aria-setsize`,
+ *   `aria-level`, `aria-posinset`) is stable across collapse/expand. Focus is
+ *   restored to the trigger when the panel closes.
+ *
+ * @doc-related select,cascade-select,combobox
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name tree-select
+ * @doc-description Themed dropdown that surfaces a hierarchical tree of options with single or multi-select and arrow-key navigation.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-tree-select',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjTreeSelect,
+      inputs: [
+        'kjNodes',
+        'kjSelectionMode',
+        'kjValue',
+        'kjExpandedKeys',
+      ],
+      outputs: [
+        'kjValueChange',
+        'kjExpandedKeysChange',
+        'kjNodeSelect',
+        'kjNodeExpand',
+        'kjNodeCollapse',
+      ],
+    },
+  ],
+  imports: [KjTreeSelectTrigger, KjTreeSelectContent, KjTreeSelectNodeComponent],
+  template: `
+    <button
+      type="button"
+      kjTreeSelectTrigger
+      #trig="kjTreeSelectTrigger"
+      class="kj-tree-select-trigger"
+      [attr.aria-label]="ariaLabel() || null"
+      [disabled]="disabled() || null"
+    >
+      <span class="kj-tree-select-trigger-label">{{ displayLabel() }}</span>
+      <span class="kj-tree-select-caret" aria-hidden="true">▾</span>
+    </button>
+    <kj-tree-select-content [kjFor]="trig" class="kj-tree-select-panel">
+      @for (row of flatNodes(); track row.node.value) {
+        <kj-tree-select-node
+          [value]="row.node.value"
+          [label]="row.node.label"
+          [level]="row.level"
+          [size]="row.size"
+          [pos]="row.pos"
+          [disabled]="!!row.node.disabled"
+          [hasChildren]="row.hasChildren"
+          [multiMode]="ts.selectionMode() === 'multiple'"
+          [hidden]="isRowHidden(row)"
+        >{{ row.node.label }}</kj-tree-select-node>
+      }
+      @if (flatNodes().length === 0) {
+        <div class="kj-tree-select-empty">No options</div>
+      }
+    </kj-tree-select-content>
+  `,
+  styleUrl: './tree-select.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-tree-select',
+    '[attr.data-disabled]': "disabled() ? '' : null",
+    '[attr.data-multi]': "ts.selectionMode() === 'multiple' ? '' : null",
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjTreeSelectComponent {
+  /** Placeholder text shown when nothing is selected. */
+  readonly placeholder = input<string>('Select…');
+
+  /** Whether the trigger is disabled. */
+  readonly disabled = input(false, { transform: booleanAttribute });
+
+  /**
+   * Optional resolver for value → display label in the trigger. When omitted
+   * the component searches the `kjNodes` tree by value. Falls back to
+   * `String(value)` for primitives.
+   */
+  readonly getLabel = input<(value: unknown) => string | undefined>(
+    () => undefined,
+  );
+
+  /** Optional ARIA label for the trigger when no visible label exists. */
+  readonly ariaLabel = input<string | undefined>(undefined);
+
+  /** @internal — reference to the headless root directive. */
+  readonly ts = inject(KjTreeSelect);
+
+  /**
+   * @internal — flat projected list of all tree nodes for rendering.
+   * Children of collapsed branches are still in the list but have `[hidden]`
+   * applied to keep them out of the visual and tab order.
+   */
+  readonly flatNodes = computed<FlatNode[]>(() =>
+    flattenTree(this.ts.nodes() as readonly KjTreeNode[]),
+  );
+
+  /**
+   * @internal — whether a row's ancestors include any collapsed branch, making
+   * this row invisible. Reads `expandedValues` signal so Angular tracks it.
+   */
+  isRowHidden(row: FlatNode): boolean {
+    if (row.ancestorValues.length === 0) return false;
+    const expanded = this.ts.expandedValues();
+    // If any ancestor value is NOT expanded, the row is hidden
+    for (const ancestorValue of row.ancestorValues) {
+      if (!expanded.has(ancestorValue)) return true;
+    }
+    return false;
+  }
+
+  /** @internal — display label shown in the trigger button. */
+  readonly displayLabel = computed(() => {
+    const mode = this.ts.selectionMode();
+    const raw = this.ts.value();
+    const selected: readonly unknown[] = Array.isArray(raw)
+      ? raw
+      : raw === null || raw === undefined
+        ? []
+        : [raw];
+    if (selected.length === 0) return this.placeholder();
+    if (mode === 'multiple') {
+      return `${selected.length} selected`;
+    }
+    // Single mode: look up label from the flat node list
+    const val = selected[0];
+    const customLabel = this.getLabel()(val);
+    if (customLabel !== undefined) return customLabel;
+    const found = this._findLabel(val, this.ts.nodes() as readonly KjTreeNode[]);
+    return found ?? String(val);
+  });
+
+  private _findLabel(value: unknown, nodes: readonly KjTreeNode[]): string | undefined {
+    for (const node of nodes) {
+      if (node.value === value) return node.label;
+      if (node.children) {
+        const found = this._findLabel(value, node.children);
+        if (found !== undefined) return found;
+      }
+    }
+    return undefined;
+  }
+}

package/src/typography/_examples/index.ts

@@ -0,0 +1,9 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { KjTypographyBlockquoteExample } from './typography.blockquote.example';
+export { KjTypographyCodeExample } from './typography.code.example';
+export { KjTypographyExample } from './typography.example';
+export { KjTypographyLeadExample } from './typography.lead.example';
+export { KjTypographyMutedExample } from './typography.muted.example';
+export { KjTypographyTruncateExample } from './typography.truncate.example';
+export { KjTypographyUsageExample } from './typography.usage.example';

package/src/typography/_examples/typography.blockquote.example.ts

@@ -0,0 +1,34 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjBlockquote } from '@kouji-ui/core';
+
+/**
+ * Blockquote example using the `kjBlockquote` directive.
+ *
+ * Reflects `data-tone="blockquote"` on a `<blockquote>` host. Useful when the
+ * blockquote sits outside a `kj-prose` container — for example a testimonial
+ * pulled into a marketing-page hero — and still needs the kouji left-rule,
+ * italic, and indent treatment.
+ */
+@Component({
+  selector: 'kj-typography-blockquote-example',
+  standalone: true,
+  imports: [KjBlockquote],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <figure>
+      <blockquote kjBlockquote>
+        Atlas turned our quarterly planning from a five-day rite of passage into a single afternoon.
+        The whole team finally agrees on what we are — and are not — shipping next quarter.
+      </blockquote>
+      <figcaption>— Priya Raman, Director of Engineering, Northwind</figcaption>
+    </figure>
+  `,
+})
+export class KjTypographyBlockquoteExample {}

package/src/typography/_examples/typography.code.example.ts

@@ -0,0 +1,32 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjCode } from '@kouji-ui/core';
+
+/**
+ * Inline code example using the `kjCode` directive.
+ *
+ * Reflects `data-tone="code"` on a `<code>` host so the kouji type system
+ * applies the inline code styling (mono font, subtle background, padding)
+ * outside a `kj-prose` container, where it would otherwise apply
+ * automatically.
+ */
+@Component({
+  selector: 'kj-typography-code-example',
+  standalone: true,
+  imports: [KjCode],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <p>
+      Run <code kjCode>npm install &#64;kouji-ui/core</code> to install the headless directives,
+      then import the prose stylesheet from
+      <code kjCode>&#64;kouji-ui/core/typography/prose.css</code>.
+    </p>
+  `,
+})
+export class KjTypographyCodeExample {}

package/src/typography/_examples/typography.example.ts

@@ -0,0 +1,42 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+
+/**
+ * Default usage example for the kouji typography surface.
+ *
+ * Shows the `kj-prose` CSS container in action: drop the class on a wrapping
+ * `<article>` and every descendant flow element (headings, paragraphs, lists,
+ * blockquote, inline code) is restyled by the kouji type system.
+ */
+@Component({
+  selector: 'kj-typography-example',
+  standalone: true,
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <article class="kj-prose">
+      <h1>Roadmap planning, in plain prose</h1>
+      <h2>Why a prose container</h2>
+      <p>
+        The <code>kj-prose</code> class restyles every descendant flow element according to the
+        kouji type system, so authored content reads cleanly without per-element wiring.
+      </p>
+      <h3>What it covers</h3>
+      <ul>
+        <li>Headings <code>h1</code> through <code>h6</code></li>
+        <li>Paragraphs, lists, definition lists</li>
+        <li>Blockquotes, inline code, anchors</li>
+      </ul>
+      <blockquote>
+        Good prose styling stays out of the way until you need it — and then it does the right thing
+        without per-paragraph configuration.
+      </blockquote>
+    </article>
+  `,
+})
+export class KjTypographyExample {}

package/src/typography/_examples/typography.lead.example.ts

@@ -0,0 +1,37 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjLead } from '@kouji-ui/core';
+
+/**
+ * Lead paragraph example using the `kjLead` directive.
+ *
+ * Marks the opening paragraph of a section with a slightly larger size and a
+ * softer tone via `data-tone="lead"`. The directive keeps lead semantics
+ * paragraph-bound and warns in dev mode when applied to a non-`<p>` host.
+ */
+@Component({
+  selector: 'kj-typography-lead-example',
+  standalone: true,
+  imports: [KjLead],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <article>
+      <h1>Atlas — quarterly roadmap planning</h1>
+      <p kjLead>
+        Atlas helps engineering teams plan quarterly roadmaps with shared context, calibrated
+        estimates, and a clean handoff to delivery.
+      </p>
+      <p>
+        The lead paragraph anchors the section's tone; the body paragraphs below carry the
+        supporting detail at the regular reading size.
+      </p>
+    </article>
+  `,
+})
+export class KjTypographyLeadExample {}

package/src/typography/_examples/typography.muted.example.ts

@@ -0,0 +1,27 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjMuted } from '@kouji-ui/core';
+
+/**
+ * Muted text example using the `kjMuted` directive.
+ *
+ * Reflects `data-tone="muted"` on the host so theme CSS keys off it; the
+ * directive owns no styling itself. Use for secondary metadata that should
+ * read at a lower visual weight while still meeting AAA contrast.
+ */
+@Component({
+  selector: 'kj-typography-muted-example',
+  standalone: true,
+  imports: [KjMuted],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <p>Last updated <span kjMuted>3 minutes ago</span> by <span kjMuted>Jamie Cole</span>.</p>
+  `,
+})
+export class KjTypographyMutedExample {}

package/src/typography/_examples/typography.truncate.example.ts

@@ -0,0 +1,41 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjTruncate } from '@kouji-ui/core';
+
+/**
+ * Multi-line truncate example using the `kjTruncate` directive.
+ *
+ * Clamps the host's text content to a fixed number of lines via
+ * `data-truncate="N"`. After first render the directive injects a
+ * normalised `[title]` attribute (when the consumer has not supplied
+ * `title` or `aria-label`) so sighted-but-zoomed users can still read the
+ * full text on hover.
+ */
+@Component({
+  selector: 'kj-typography-truncate-example',
+  standalone: true,
+  imports: [KjTruncate],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+      .card {
+        max-width: 28rem;
+        padding: var(--kj-space-md);
+        border-radius: var(--kj-radius-md);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <article class="card">
+      <h3>Atlas — quarterly planning</h3>
+      <p [kjTruncate]="2">
+        Atlas helps engineering teams plan quarterly roadmaps with shared context, calibrated
+        estimates, and a clean handoff to delivery — so every team starts the quarter aligned on
+        what is shipping, what is deferred, and why.
+      </p>
+    </article>
+  `,
+})
+export class KjTypographyTruncateExample {}

package/src/typography/_examples/typography.usage.example.ts

@@ -0,0 +1,44 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjLead, KjMuted, KjCode, KjBlockquote, KjTruncate } from '@kouji-ui/core';
+
+/**
+ * A walkthrough of the most common typography usages — a `.kj-prose` container,
+ * a `kjLead` opening paragraph, inline `kjCode`, a `kjMuted` aside, a
+ * `kjBlockquote` pulled quote, and a `[kjTruncate]="2"` clamped block.
+ */
+@Component({
+  selector: 'kj-typography-usage-example',
+  standalone: true,
+  imports: [KjLead, KjMuted, KjCode, KjBlockquote, KjTruncate],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <article class="kj-prose">
+      <h1>Roadmap planning, in plain prose</h1>
+      <p kjLead>
+        The kouji typography system styles authored content without per-element wiring — drop the
+        prose class and write.
+      </p>
+      <p>
+        Use <code kjCode>kjLead</code> for the opening paragraph, <code kjCode>kjMuted</code> for
+        secondary copy, and <code kjCode>kjTruncate</code> when a block must clamp.
+      </p>
+      <blockquote kjBlockquote>
+        Good prose styling stays out of the way until you need it.
+      </blockquote>
+      <p [kjTruncate]="2">
+        The full sentence is preserved in the accessibility tree even when the visual clamp hides
+        the overflow — screen readers still get the complete content, only the visible glyphs are
+        clipped at the line count you specify.
+      </p>
+      <p><span kjMuted>Last updated 3 minutes ago.</span></p>
+    </article>
+  `,
+})
+export class KjTypographyUsageExample {}

package/src/typography/index.ts

@@ -0,0 +1,8 @@
+// Typography surface — directives only, no wrapper components.
+// Per the analysis, Typography ships no `<kj-h1>` / `<kj-prose>` Angular
+// components: the CSS class `kj-prose` plus five attribute directives are
+// the entire surface. The components package re-exports the directives
+// from `@kouji-ui/core` for ergonomic consumption alongside the rest of
+// the library, and ships the `kj-prose` stylesheet via the package's
+// stylesheet pipeline.
+export { KjLead, KjMuted, KjCode, KjBlockquote, KjTruncate } from '@kouji-ui/core';