@kouji-ui/components 0.1.1 → 0.1.2

package/src/kbd/kbd.ts

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

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

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

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

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

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

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

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

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

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

package/src/link/link.css

@@ -1,104 +0,0 @@
-/* ─────────────────────────────────────────────────────────────
-   .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

@@ -1,98 +0,0 @@
-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>`;
-  },
-};