@kouji-ui/components 0.1.1 → 0.1.2

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

@@ -1,348 +0,0 @@
-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

@@ -1,9 +0,0 @@
-// 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

@@ -1,34 +0,0 @@
-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

@@ -1,32 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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

@@ -1,37 +0,0 @@
-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

@@ -1,27 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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

@@ -1,44 +0,0 @@
-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

@@ -1,8 +0,0 @@
-// 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';