@kouji-ui/components 0.1.1

package/src/kbd/kbd.ts

@@ -0,0 +1,123 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, input } from '@angular/core';
+import { KJ_SIZE_PRESET, KJ_KBD_SIZE_PRESET, KjKbd } from '@kouji-ui/core';
+
+/**
+ * Styled wrapper around the headless `KjKbd` directive.
+ *
+ * Renders an inner `<kbd kjKbd>` so the native `<kbd>` semantic is preserved
+ * (HTML AAM maps `<kbd>` to `role="generic"`; AT typically announces the
+ * element's text content directly, with a "key" prefix in verbose modes —
+ * which is exactly the right read for a keyboard-shortcut visual). The wrapper
+ * itself is layout-invisible (`display: contents`) so a kbd inline-flowed in
+ * prose does not introduce an extra block-level box that would break baseline
+ * alignment with surrounding text.
+ *
+ * **Composition note.** Per the analysis, the directive is composed by
+ * applying `kjKbd` to the inner `<kbd>` rather than via the wrapper's own
+ * `hostDirectives`. The directive must run on the visible kbd element so the
+ * `data-size` reflection (and any future host bindings) land where theme CSS
+ * expects them, not on the `display: contents` outer `<kj-kbd>` custom
+ * element.
+ *
+ * **No variant.** Kbd is tonally neutral — there is no "destructive kbd" or
+ * "primary kbd". A future design language wanting e.g. a "deprecated shortcut"
+ * tone can fold in via a CSS-only `[data-deprecated="true"]` attribute without
+ * API churn.
+ *
+ * **Size preset.** The wrapper provides `KJ_SIZE_PRESET` with the four-value
+ * `xs / sm / md / lg` scale (default `md`). Inline-with-prose kbds genuinely
+ * want sub-`sm`; this is the one component in the library that legitimately
+ * extends below the standard `[sm, md, lg]` baseline.
+ *
+ * @example
+ * ```html
+ * <kj-kbd>Enter</kj-kbd>
+ * <kj-kbd kjSize="xs">⌘</kj-kbd>
+ * <kj-kbd kjKbdAriaLabel="Command">⌘</kj-kbd>
+ * ```
+ * @doc-example Default
+ *   A single keyboard key rendered inline with prose — anchors the chrome.
+ *   @doc-file kbd.example.ts
+ * @doc-example Usage
+ *   Common kbd shapes — sizes, glyph keys with aria-labels, and a combo.
+ *   @doc-file kbd.usage.example.ts
+ * @doc-example Combo
+ *   Sibling `<kj-kbd>` elements joined by a literal "+" glyph.
+ *   @doc-file kbd.combo.example.ts
+ * @doc-example Sizes
+ *   `xs` / `sm` / `md` / `lg` — the only library component that goes below `sm`.
+ *   @doc-file kbd.sizes.example.ts
+ * @doc-example In a tooltip
+ *   Tooltip body wraps a shortcut hint with `<kj-kbd>`.
+ *   @doc-file kbd.in-tooltip.example.ts
+ *
+ * @doc-keyboard
+ *   None — kbd is purely visual. The element is non-interactive and does not participate in tab order.
+ *
+ * @doc-aria
+ *   aria-label  — When [kjKbdAriaLabel] is set, forwarded to the inner <kbd> for glyph keys (⌘, ⌥, ⇧, ↵)
+ *   data-size   — Mirrors [kjSize] (xs/sm/md/lg) for theme CSS
+ *
+ * @doc-touch
+ *   Kbd is a label, not a target — no 44 px requirement. When embedded in
+ *   an actionable control (button / link), the parent owns the touch
+ *   surface.
+ *
+ * @doc-a11y
+ *   Uses the semantic `<kbd>` element underneath so AT reads the text content
+ *   directly. Only set `[kjKbdAriaLabel]` when the visible glyph is unicode
+ *   the screen reader cannot pronounce — for `Enter`, `Ctrl`, `K`, the
+ *   default text content is the right read.
+ *
+ * @doc-related tooltip,command-palette,badge
+ *
+ * @doc-css-var
+ *   --kj-kbd-bg           — Background fill of the key cap. Defaults to --kj-bg-surface.
+ *   --kj-kbd-fg           — Foreground (glyph) color.
+ *   --kj-kbd-border-color — Border color. Bumped at xs for contrast.
+ *   --kj-kbd-border-width — Border thickness. Inherits --kj-border.
+ *   --kj-kbd-radius       — Corner radius. Inherits --kj-radius-selector.
+ *   --kj-kbd-padding-x    — Horizontal padding inside the cap. Sizes override.
+ *   --kj-kbd-padding-y    — Vertical padding inside the cap. Sizes override.
+ *   --kj-kbd-font         — Font family. Defaults to --kj-font-mono.
+ *   --kj-kbd-font-size    — Font size. Sizes (xs/sm/md/lg) override.
+ *
+ * @doc-category Library/Data display
+ * @doc
+ * @doc-name kbd
+ * @doc-description Themed keyboard key label with size variants and an aria-label override for symbol glyphs.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-kbd',
+  standalone: true,
+  imports: [KjKbd],
+  template: `<kbd
+    kjKbd
+    class="kj-kbd"
+    [kjSize]="kjSize()"
+    [attr.aria-label]="kjKbdAriaLabel() ?? null"
+  ><ng-content /></kbd>`,
+  styleUrl: './kbd.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { style: 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  providers: [{ provide: KJ_SIZE_PRESET, useValue: KJ_KBD_SIZE_PRESET }],
+})
+export class KjKbdComponent {
+  /** Size preset. Validated against `KJ_KBD_SIZE_PRESET` (`xs` / `sm` / `md` / `lg`). */
+  readonly kjSize = input<'xs' | 'sm' | 'md' | 'lg'>('md');
+
+  /**
+   * Optional override for the host's accessible name. Use only when the
+   * visible text is a unicode glyph (`⌘`, `⌥`, `↵`, `⇧`, `⌫`, `⎋`, `⇥`, `⏎`)
+   * that AT does not pronounce sensibly. Forwards to `[attr.aria-label]` on
+   * the inner `<kbd>`. The default — the host's text content — is the right
+   * read for plain-text kbds (`Enter`, `Ctrl`, `K`).
+   *
+   * The directive does not declare a duplicate input for this; the wrapper is
+   * allowed to set host attributes the directive does not own, the same way a
+   * consumer using `[kjKbd]` directly is.
+   */
+  readonly kjKbdAriaLabel = input<string | undefined>(undefined);
+}

package/src/kbd/kbd.usage.example.ts

@@ -0,0 +1,38 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { KjKbdComponent } from './kbd';
+
+/**
+ * Common kbd usages — sizes for inline-with-prose, a glyph key with an
+ * aria-label override, and a combo shortcut.
+ */
+@Component({
+  selector: 'kj-kbd-usage-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjKbdComponent],
+  styles: [`
+    :host { display: flex; flex-direction: column; gap: var(--kj-space-md); max-width: 60ch; }
+    p { line-height: 1.6; margin: 0; }
+  `],
+  template: `
+    <p>
+      Sizes inline with prose:
+      <kj-kbd kjSize="xs">⌘</kj-kbd>
+      <kj-kbd kjSize="sm">Shift</kj-kbd>
+      <kj-kbd kjSize="md">Enter</kj-kbd>
+      <kj-kbd kjSize="lg">Esc</kj-kbd>
+    </p>
+
+    <p>
+      Glyph keys with aria-labels for AT:
+      <kj-kbd kjKbdAriaLabel="Command">⌘</kj-kbd>
+      <kj-kbd kjKbdAriaLabel="Option">⌥</kj-kbd>
+      <kj-kbd kjKbdAriaLabel="Shift">⇧</kj-kbd>
+    </p>
+
+    <p>
+      Combo: press <kj-kbd>Ctrl</kj-kbd> + <kj-kbd>K</kj-kbd> to focus search.
+    </p>
+  `,
+})
+export class KjKbdUsageExample {}

package/src/link/_examples/index.ts

@@ -0,0 +1,8 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { KjLinkDisabledExample } from './link.disabled.example';
+export { KjLinkExample } from './link.example';
+export { KjLinkExternalExample } from './link.external.example';
+export { KjLinkInProseExample } from './link.in-prose.example';
+export { KjLinkSizesExample } from './link.sizes.example';
+export { KjLinkVariantsExample } from './link.variants.example';

package/src/link/_examples/link.disabled.example.ts

@@ -0,0 +1,23 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjLinkComponent } from '../link';
+
+@Component({
+  selector: 'kj-link-disabled-example',
+  standalone: true,
+  imports: [KjLinkComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        gap: var(--kj-space-lg);
+        flex-wrap: wrap;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-link kjHref="/active" kjUnderline="always">Active link</kj-link>
+    <kj-link kjHref="/disabled" [kjDisabled]="true" kjUnderline="always"> Disabled link </kj-link>
+  `,
+})
+export class KjLinkDisabledExample {}

package/src/link/_examples/link.example.ts

@@ -0,0 +1,26 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjLinkComponent } from '../link';
+
+/**
+ * Default usage example for KjLinkComponent.
+ * Rendered live in the docs and as code in the example panel.
+ */
+@Component({
+  selector: 'kj-link-example',
+  standalone: true,
+  imports: [KjLinkComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <p>
+      Visit <kj-link kjHref="/about">our about page</kj-link> for more information about kouji-ui.
+    </p>
+  `,
+})
+export class KjLinkExample {}

package/src/link/_examples/link.external.example.ts

@@ -0,0 +1,33 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjLinkComponent } from '../link';
+
+@Component({
+  selector: 'kj-link-external-example',
+  standalone: true,
+  imports: [KjLinkComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <p>
+      Auto-detected from <code>target="_blank"</code>:
+      <kj-link kjHref="https://example.com" kjTarget="_blank" kjUnderline="always">
+        example.com </kj-link
+      >.
+    </p>
+    <p>
+      Explicit <code>kjExternal</code> for cross-origin URLs without <code>target="_blank"</code>:
+      <kj-link kjHref="https://docs.example.com" [kjExternal]="true" kjUnderline="always">
+        Docs </kj-link
+      >.
+    </p>
+  `,
+})
+export class KjLinkExternalExample {}

package/src/link/_examples/link.in-prose.example.ts

@@ -0,0 +1,36 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjLinkComponent } from '../link';
+
+@Component({
+  selector: 'kj-link-in-prose-example',
+  standalone: true,
+  imports: [KjLinkComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+      p {
+        max-width: 60ch;
+        line-height: 1.6;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <p>
+      kouji-ui ships a small, opinionated set of components. Read the
+      <kj-link kjHref="/docs" kjUnderline="always">documentation</kj-link>
+      to get started, browse the
+      <kj-link
+        kjHref="https://github.com/kouji-dev/kouji-ui"
+        kjTarget="_blank"
+        kjUnderline="always"
+      >
+        source on GitHub </kj-link
+      >, or try the <kj-link kjHref="/playground" kjUnderline="always">live playground</kj-link>.
+      Inline links sit naturally inside the text flow without breaking the baseline.
+    </p>
+  `,
+})
+export class KjLinkInProseExample {}

package/src/link/_examples/link.sizes.example.ts

@@ -0,0 +1,28 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjLinkComponent } from '../link';
+
+@Component({
+  selector: 'kj-link-sizes-example',
+  standalone: true,
+  imports: [KjLinkComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-link kjHref="/x" kjSize="sm" kjUnderline="always">Small link</kj-link>
+    <kj-link kjHref="/x" kjSize="md" kjUnderline="always">Medium link</kj-link>
+    <kj-link kjHref="/x" kjSize="lg" kjUnderline="always">Large link</kj-link>
+    <p style="font-size: 1.25rem;">
+      Inherits the surrounding text size:
+      <kj-link kjHref="/x" kjSize="inherit">inline link</kj-link>.
+    </p>
+  `,
+})
+export class KjLinkSizesExample {}

package/src/link/_examples/link.variants.example.ts

@@ -0,0 +1,25 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjLinkComponent } from '../link';
+
+@Component({
+  selector: 'kj-link-variants-example',
+  standalone: true,
+  imports: [KjLinkComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        gap: var(--kj-space-lg);
+        flex-wrap: wrap;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-link kjHref="/x" kjVariant="primary" kjUnderline="always">Primary</kj-link>
+    <kj-link kjHref="/x" kjVariant="secondary" kjUnderline="always">Secondary</kj-link>
+    <kj-link kjHref="/x" kjVariant="muted" kjUnderline="always">Muted</kj-link>
+    <kj-link kjHref="/x" kjVariant="destructive" kjUnderline="always">Destructive</kj-link>
+  `,
+})
+export class KjLinkVariantsExample {}

package/src/link/index.ts

@@ -0,0 +1 @@
+export * from './link';

package/src/link/link.css

@@ -0,0 +1,104 @@
+/* ─────────────────────────────────────────────────────────────
+   .kj-link — component-layer tokens + structural CSS
+   Tokens default to shared-layer values from @kouji-ui/themes.
+   Variants / sizes / states retarget the component tokens; the
+   structural rules below are the only place raw var(--kj-link-*)
+   is read.
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-link {
+    /* component knobs — themes / users can override any of these */
+    --kj-link-fg:               var(--kj-fg-primary);
+    --kj-link-hover-fg:         color-mix(in oklch, var(--kj-fg-primary), black 8%);
+    --kj-link-visited-fg:       var(--kj-fg-accent);
+    --kj-link-decoration:       underline;
+    --kj-link-underline-offset: 3px;
+    --kj-link-font-size:        inherit;
+    --kj-link-radius:           var(--kj-radius-field, 0.25rem);
+
+    /* the only place raw var(--kj-link-*) is read */
+    color: var(--kj-link-fg);
+    text-decoration: var(--kj-link-decoration);
+    text-underline-offset: var(--kj-link-underline-offset);
+    font-size: var(--kj-link-font-size);
+    border-radius: var(--kj-link-radius);
+    cursor: pointer;
+    transition: color var(--kj-transition), text-decoration-color var(--kj-transition);
+  }
+
+  .kj-link:hover {
+    color: var(--kj-link-hover-fg);
+  }
+
+  .kj-link:visited {
+    color: var(--kj-link-visited-fg);
+  }
+
+  .kj-link:focus-visible {
+    outline: 2px solid var(--kj-fg-primary);
+    outline-offset: 2px;
+  }
+
+  /* ── Underline modes ────────────────────────────────────────── */
+  .kj-link[data-underline="always"] { --kj-link-decoration: underline; }
+  .kj-link[data-underline="hover"]  { --kj-link-decoration: none; }
+  .kj-link[data-underline="hover"]:hover,
+  .kj-link[data-underline="hover"]:focus-visible { --kj-link-decoration: underline; }
+  .kj-link[data-underline="none"]   { --kj-link-decoration: none; }
+
+  /* ── Variants ───────────────────────────────────────────────── */
+  .kj-link[data-variant="primary"] {
+    --kj-link-fg: var(--kj-fg-primary);
+    --kj-link-hover-fg: color-mix(in oklab, var(--kj-fg-primary) 80%, var(--kj-fg-default));
+  }
+
+  .kj-link[data-variant="secondary"] {
+    --kj-link-fg: var(--kj-fg-accent);
+    --kj-link-hover-fg: color-mix(in oklab, var(--kj-fg-accent) 80%, var(--kj-fg-default));
+  }
+
+  .kj-link[data-variant="muted"] {
+    --kj-link-fg: color-mix(in oklab, var(--kj-fg-default) 70%, transparent);
+    --kj-link-hover-fg: var(--kj-fg-default);
+  }
+
+  .kj-link[data-variant="destructive"] {
+    --kj-link-fg: var(--kj-fg-danger);
+    --kj-link-hover-fg: color-mix(in oklab, var(--kj-fg-danger) 80%, var(--kj-fg-default));
+  }
+
+  /* ── Sizes ──────────────────────────────────────────────────── */
+  .kj-link[data-size="sm"]      { --kj-link-font-size: 0.8125rem; }
+  .kj-link[data-size="md"]      { --kj-link-font-size: 0.9375rem; }
+  .kj-link[data-size="lg"]      { --kj-link-font-size: 1.0625rem; }
+  .kj-link[data-size="inherit"] { --kj-link-font-size: inherit; }
+
+  /* ── External-link icon (sighted-user story) ───────────────── */
+  .kj-link[data-external="true"]::after {
+    content: "";
+    display: inline-block;
+    width: 0.75em;
+    height: 0.75em;
+    margin-inline-start: 0.25em;
+    background-color: currentColor;
+    /* Mask is a tiny "arrow leaving box" glyph; aria-hidden by virtue of CSS. */
+    -webkit-mask: var(
+      --kj-link-external-icon,
+      url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><path fill='none' stroke='currentColor' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round' d='M9 3h4v4M13 3 7 9M11 9v4H3V5h4'/></svg>")
+    ) center / contain no-repeat;
+    mask: var(
+      --kj-link-external-icon,
+      url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><path fill='none' stroke='currentColor' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round' d='M9 3h4v4M13 3 7 9M11 9v4H3V5h4'/></svg>")
+    ) center / contain no-repeat;
+    vertical-align: -0.05em;
+  }
+
+  /* ── Disabled state ─────────────────────────────────────────── */
+  .kj-link[aria-disabled="true"],
+  .kj-link[data-disabled] {
+    opacity: 0.5;
+    cursor: not-allowed;
+    text-decoration: none;
+  }
+}

package/src/link/link.playground.ts

@@ -0,0 +1,98 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjLinkComponent } from './link';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Variant, size, underline mode,
+ * external-link affordance, and disabled state cover every directive input
+ * the wrapper forwards.
+ */
+const variant = signal<'primary' | 'muted' | 'destructive'>('primary');
+const size = signal<'sm' | 'md' | 'lg' | 'inherit'>('inherit');
+const underline = signal<'always' | 'hover' | 'none'>('hover');
+const external = signal(false);
+const disabled = signal(false);
+const label = signal('Read the docs');
+const href = signal('/docs');
+
+@Component({
+  selector: 'kj-link-playground',
+  standalone: true,
+  imports: [KjLinkComponent],
+  template: `
+    <kj-link
+      [kjHref]="href()"
+      [kjVariant]="variant()"
+      [kjSize]="size()"
+      [kjUnderline]="underline()"
+      [kjExternal]="external()"
+      [kjDisabled]="disabled()"
+      [kjTarget]="external() ? '_blank' : undefined"
+    >{{ label() }}</kj-link>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjLinkPlaygroundDemo {
+  protected readonly variant = variant;
+  protected readonly size = size;
+  protected readonly underline = underline;
+  protected readonly external = external;
+  protected readonly disabled = disabled;
+  protected readonly label = label;
+  protected readonly href = href;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjLinkPlaygroundDemo,
+  state: {
+    variant: variant as unknown as ReturnType<typeof signal>,
+    size: size as unknown as ReturnType<typeof signal>,
+    underline: underline as unknown as ReturnType<typeof signal>,
+    external: external as unknown as ReturnType<typeof signal>,
+    disabled: disabled as unknown as ReturnType<typeof signal>,
+    label: label as unknown as ReturnType<typeof signal>,
+    href: href as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    {
+      kind: 'chips',
+      name: 'variant',
+      label: 'variant',
+      options: ['primary', 'muted', 'destructive'],
+    },
+    { kind: 'chips', name: 'size', label: 'size', options: ['sm', 'md', 'lg', 'inherit'] },
+    {
+      kind: 'chips',
+      name: 'underline',
+      label: 'underline',
+      options: ['always', 'hover', 'none'],
+    },
+    { kind: 'text', name: 'label', label: 'label' },
+    { kind: 'text', name: 'href', label: 'href' },
+    { kind: 'toggle', name: 'external', label: 'external' },
+    { kind: 'toggle', name: 'disabled', label: 'disabled' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      variant: string;
+      size: string;
+      underline: string;
+      external: boolean;
+      disabled: boolean;
+      label: string;
+      href: string;
+    };
+    const attrs: string[] = [
+      `kjHref="${s.href}"`,
+      `kjVariant="${s.variant}"`,
+      `kjSize="${s.size}"`,
+      `kjUnderline="${s.underline}"`,
+    ];
+    if (s.external) {
+      attrs.push('[kjExternal]="true"');
+      attrs.push('kjTarget="_blank"');
+    }
+    if (s.disabled) attrs.push('[kjDisabled]="true"');
+    return `<kj-link\n  ${attrs.join('\n  ')}\n>${s.label}</kj-link>`;
+  },
+};