@kouji-ui/components 0.1.1

package/src/color-picker/_examples/color-picker.with-presets.example.ts

@@ -0,0 +1,45 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { KjColorPickerComponent } from '../color-picker';
+import type { KjColorPreset } from '@kouji-ui/core';
+
+/**
+ * Color-picker with a brand-palette preset row.
+ */
+@Component({
+  selector: 'kj-color-picker-with-presets-example',
+  standalone: true,
+  imports: [KjColorPickerComponent, FormsModule],
+  styles: [
+    `
+      :host {
+        display: flex;
+        gap: var(--kj-space-md);
+        align-items: center;
+        min-height: 320px;
+      }
+      code {
+        font: 0.8125rem/1 var(--kj-font-mono, monospace);
+        color: var(--kj-fg-muted);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-color-picker [(ngModel)]="hex" [kjPresets]="palette" />
+    <code>{{ hex() }}</code>
+  `,
+})
+export class KjColorPickerWithPresetsExample {
+  readonly hex = signal('#3b82f6');
+  readonly palette: readonly KjColorPreset[] = [
+    { value: '#ef4444', label: 'Brand red' },
+    { value: '#f97316', label: 'Brand orange' },
+    { value: '#eab308', label: 'Brand yellow' },
+    { value: '#22c55e', label: 'Brand green' },
+    { value: '#06b6d4', label: 'Brand teal' },
+    { value: '#3b82f6', label: 'Brand blue' },
+    { value: '#8b5cf6', label: 'Brand violet' },
+    { value: '#ec4899', label: 'Brand pink' },
+  ];
+}

package/src/color-picker/_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 { KjColorPickerAlphaExample } from './color-picker.alpha.example';
+export { KjColorPickerExample } from './color-picker.example';
+export { KjColorPickerHexInputExample } from './color-picker.hex-input.example';
+export { KjColorPickerInFormExample } from './color-picker.in-form.example';
+export { KjColorPickerUsageExample } from './color-picker.usage.example';
+export { KjColorPickerWithPresetsExample } from './color-picker.with-presets.example';

package/src/color-picker/color-picker.css

@@ -0,0 +1,183 @@
+@layer kj.component {
+  .kj-color-picker {
+    position: relative;
+    display: inline-block;
+  }
+
+  .kj-color-picker-trigger {
+    /* WCAG 2.5.5 — replaces the existing 44×32 native swatch that fails AAA. */
+    width: 44px;
+    height: 44px;
+    padding: 0;
+    border: var(--kj-border) solid var(--kj-border-default);
+    border-radius: var(--kj-radius-field);
+    cursor: pointer;
+    /* Checkerboard backdrop for translucent colors. The current color is
+       layered on top via the inline style hook. */
+    background:
+      linear-gradient(var(--kj-color-picker-current, #000), var(--kj-color-picker-current, #000)),
+      conic-gradient(#ccc 25%, #fff 0 50%, #ccc 0 75%, #fff 0) 0 0 / 12px 12px;
+  }
+  .kj-color-picker-trigger[data-disabled] {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+  .kj-color-picker-trigger:focus-visible {
+    outline: 2px solid var(--kj-border-focus);
+    outline-offset: 2px;
+  }
+
+  .kj-color-picker-panel {
+    box-sizing: border-box;
+    z-index: 1000;
+    width: 280px;
+    padding: var(--kj-space-md);
+    background: var(--kj-bg-body);
+    border: var(--kj-border) solid var(--kj-border-default);
+    border-radius: var(--kj-radius-field);
+    box-shadow: var(--kj-shadow-md);
+    display: flex;
+    flex-direction: column;
+    gap: var(--kj-space-sm);
+    color: var(--kj-fg-default);
+  }
+  .kj-color-picker-panel[hidden] { display: none; }
+
+  /* 2-axis sat/value rectangle. Hue passed through as a hsl() wedge,
+     a horizontal white→saturated-color gradient, and a vertical
+     transparent→black gradient, layered to produce the standard square. */
+  .kj-color-picker-area {
+    position: relative;
+    width: 100%;
+    height: 160px;
+    border-radius: 4px;
+    cursor: crosshair;
+    background:
+      linear-gradient(to top, #000, transparent),
+      linear-gradient(to right, #fff, hsl(var(--kj-color-picker-hue, 0), 100%, 50%));
+    touch-action: none;
+  }
+  .kj-color-picker-area:focus-visible {
+    outline: 2px solid var(--kj-border-focus);
+    outline-offset: 2px;
+  }
+  .kj-color-picker-area::after {
+    content: '';
+    position: absolute;
+    width: 14px;
+    height: 14px;
+    margin: -7px 0 0 -7px;
+    /* Saturation drives x; (1 - value) drives y so visually high y = low value. */
+    left: calc(var(--kj-color-picker-x, 0) * 100%);
+    top: calc((1 - var(--kj-color-picker-y, 0)) * 100%);
+    border: 2px solid #fff;
+    box-shadow: 0 0 0 1px #000, 0 0 4px rgb(0 0 0 / 0.4);
+    border-radius: 50%;
+    pointer-events: none;
+  }
+
+  .kj-color-picker-hue-slider,
+  .kj-color-picker-alpha-slider {
+    width: 100%;
+    height: 16px;
+    margin: 0;
+    -webkit-appearance: none;
+    appearance: none;
+    background: transparent;
+    cursor: pointer;
+  }
+  .kj-color-picker-hue-slider::-webkit-slider-runnable-track {
+    height: 12px;
+    border-radius: 6px;
+    background: linear-gradient(to right,
+      #ff0000, #ffff00, #00ff00, #00ffff, #0000ff, #ff00ff, #ff0000);
+  }
+  .kj-color-picker-hue-slider::-moz-range-track {
+    height: 12px;
+    border-radius: 6px;
+    background: linear-gradient(to right,
+      #ff0000, #ffff00, #00ff00, #00ffff, #0000ff, #ff00ff, #ff0000);
+  }
+  .kj-color-picker-alpha-slider::-webkit-slider-runnable-track {
+    height: 12px;
+    border-radius: 6px;
+    background:
+      linear-gradient(to right, transparent, var(--kj-color-picker-current, #000)),
+      conic-gradient(#ccc 25%, #fff 0 50%, #ccc 0 75%, #fff 0) 0 0 / 8px 8px;
+  }
+  .kj-color-picker-alpha-slider::-moz-range-track {
+    height: 12px;
+    border-radius: 6px;
+    background:
+      linear-gradient(to right, transparent, var(--kj-color-picker-current, #000)),
+      conic-gradient(#ccc 25%, #fff 0 50%, #ccc 0 75%, #fff 0) 0 0 / 8px 8px;
+  }
+  .kj-color-picker-hue-slider::-webkit-slider-thumb,
+  .kj-color-picker-alpha-slider::-webkit-slider-thumb {
+    -webkit-appearance: none;
+    appearance: none;
+    width: 14px;
+    height: 14px;
+    border-radius: 50%;
+    background: #fff;
+    border: 2px solid #000;
+    margin-top: -1px;
+  }
+  .kj-color-picker-hue-slider::-moz-range-thumb,
+  .kj-color-picker-alpha-slider::-moz-range-thumb {
+    width: 14px;
+    height: 14px;
+    border-radius: 50%;
+    background: #fff;
+    border: 2px solid #000;
+  }
+  .kj-color-picker-hue-slider:focus-visible,
+  .kj-color-picker-alpha-slider:focus-visible {
+    outline: 2px solid var(--kj-border-focus);
+    outline-offset: 2px;
+  }
+
+  .kj-color-picker-input {
+    width: 100%;
+    box-sizing: border-box;
+    padding: var(--kj-space-xs) var(--kj-space-sm);
+    border: var(--kj-border) solid var(--kj-border-default);
+    border-radius: var(--kj-radius-field);
+    background: var(--kj-bg-body);
+    color: var(--kj-fg-default);
+    font: 0.8125rem var(--kj-font-mono, monospace);
+  }
+  .kj-color-picker-input[aria-invalid="true"] {
+    border-color: var(--kj-border-danger, #ef4444);
+  }
+
+  .kj-color-picker-presets {
+    display: grid;
+    grid-template-columns: repeat(8, 1fr);
+    gap: 6px;
+  }
+  .kj-color-picker-preset {
+    width: 24px;
+    height: 24px;
+    padding: 0;
+    border: var(--kj-border) solid var(--kj-border-default);
+    border-radius: 4px;
+    cursor: pointer;
+  }
+  .kj-color-picker-preset[aria-selected="true"] {
+    outline: 2px solid var(--kj-border-focus);
+    outline-offset: 1px;
+  }
+  .kj-color-picker-preset:focus-visible {
+    outline: 2px solid var(--kj-border-focus);
+    outline-offset: 2px;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .kj-color-picker-panel,
+    .kj-color-picker-trigger,
+    .kj-color-picker-area::after {
+      transition: none !important;
+    }
+  }
+}

package/src/color-picker/color-picker.playground.ts

@@ -0,0 +1,83 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { KjColorPickerComponent } from './color-picker';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Knobs cover the wire format, the
+ * presence of the alpha slider, the inline hex input, the disabled posture,
+ * and a seed color so the swatch label tracks the picker value.
+ */
+const value = signal('#b8f500');
+const format = signal<'hex' | 'rgb' | 'hsl'>('hex');
+const showAlpha = signal(false);
+const showHexInput = signal(true);
+const disabled = signal(false);
+const invalid = signal(false);
+
+@Component({
+  selector: 'kj-color-picker-playground',
+  standalone: true,
+  imports: [KjColorPickerComponent, FormsModule],
+  styles: [`
+    :host { display: flex; gap: var(--kj-space-md); align-items: center; }
+    code { font: 0.8125rem/1 var(--kj-font-mono, monospace); color: var(--kj-fg-muted); }
+  `],
+  template: `
+    <kj-color-picker
+      [(ngModel)]="value"
+      [kjFormat]="format()"
+      [kjShowAlpha]="showAlpha()"
+      [kjShowHexInput]="showHexInput()"
+      [kjDisabled]="disabled()"
+      [kjInvalid]="invalid()"
+    />
+    <code>{{ value() }}</code>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjColorPickerPlaygroundDemo {
+  protected readonly value = value;
+  protected readonly format = format;
+  protected readonly showAlpha = showAlpha;
+  protected readonly showHexInput = showHexInput;
+  protected readonly disabled = disabled;
+  protected readonly invalid = invalid;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjColorPickerPlaygroundDemo,
+  state: {
+    value: value as unknown as ReturnType<typeof signal>,
+    format: format as unknown as ReturnType<typeof signal>,
+    showAlpha: showAlpha as unknown as ReturnType<typeof signal>,
+    showHexInput: showHexInput as unknown as ReturnType<typeof signal>,
+    disabled: disabled as unknown as ReturnType<typeof signal>,
+    invalid: invalid as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'chips', name: 'format', label: 'format', options: ['hex', 'rgb', 'hsl'] },
+    { kind: 'text', name: 'value', label: 'value' },
+    { kind: 'toggle', name: 'showAlpha', label: 'alpha slider' },
+    { kind: 'toggle', name: 'showHexInput', label: 'hex input' },
+    { kind: 'toggle', name: 'invalid', label: 'invalid' },
+    { kind: 'toggle', name: 'disabled', label: 'disabled' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      value: string;
+      format: string;
+      showAlpha: boolean;
+      showHexInput: boolean;
+      disabled: boolean;
+      invalid: boolean;
+    };
+    const attrs: string[] = [`kjFormat="${s.format}"`];
+    if (s.showAlpha) attrs.push('[kjShowAlpha]="true"');
+    if (!s.showHexInput) attrs.push('[kjShowHexInput]="false"');
+    if (s.invalid) attrs.push('[kjInvalid]="true"');
+    if (s.disabled) attrs.push('[kjDisabled]="true"');
+    attrs.push('[(ngModel)]="color"');
+    return `<kj-color-picker\n  ${attrs.join('\n  ')}\n/>`;
+  },
+};

package/src/color-picker/color-picker.spec.ts

@@ -0,0 +1,94 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { render, fireEvent } from '@testing-library/angular';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { KjColorPickerComponent } from './color-picker';
+import type { KjColorPreset } from '@kouji-ui/core';
+
+expect.extend(toHaveNoViolations);
+
+@Component({
+  standalone: true,
+  imports: [KjColorPickerComponent, FormsModule],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-color-picker [(ngModel)]="hex" [kjShowAlpha]="showAlpha()" [kjPresets]="presets()" />
+  `,
+})
+class HostComponent {
+  readonly hex = signal('#ff0000');
+  readonly showAlpha = signal(false);
+  readonly presets = signal<readonly KjColorPreset[]>([]);
+}
+
+describe('KjColorPickerComponent', () => {
+  it('renders the trigger button', async () => {
+    const { container } = await render(HostComponent);
+    expect(container.querySelector('.kj-color-picker-trigger')).toBeInTheDocument();
+  });
+
+  it('panel is hidden until trigger clicked', async () => {
+    const { container } = await render(HostComponent);
+    const panel = container.querySelector('.kj-color-picker-panel')!;
+    expect(panel).toHaveAttribute('hidden', '');
+    fireEvent.click(container.querySelector('.kj-color-picker-trigger')!);
+    expect(panel).not.toHaveAttribute('hidden');
+  });
+
+  it('hex input is mounted by default', async () => {
+    const { container } = await render(HostComponent);
+    fireEvent.click(container.querySelector('.kj-color-picker-trigger')!);
+    expect(container.querySelector('.kj-color-picker-input')).toBeInTheDocument();
+  });
+
+  it('alpha slider hidden when kjShowAlpha is false', async () => {
+    const { container, fixture } = await render(HostComponent);
+    fireEvent.click(container.querySelector('.kj-color-picker-trigger')!);
+    expect(container.querySelector('.kj-color-picker-alpha-slider')).toBeNull();
+    fixture.componentInstance.showAlpha.set(true);
+    fixture.detectChanges();
+    expect(container.querySelector('.kj-color-picker-alpha-slider')).toBeInTheDocument();
+  });
+
+  it('preset listbox renders one option per preset', async () => {
+    const { container, fixture } = await render(HostComponent);
+    fixture.componentInstance.presets.set([
+      { value: '#ff0000', label: 'Red' },
+      { value: '#00ff00', label: 'Green' },
+    ]);
+    fixture.detectChanges();
+    fireEvent.click(container.querySelector('.kj-color-picker-trigger')!);
+    fixture.detectChanges();
+    const options = container.querySelectorAll('.kj-color-picker-preset');
+    expect(options.length).toBe(2);
+  });
+
+  it('clicking a preset updates the bound value', async () => {
+    const { container, fixture } = await render(HostComponent);
+    fixture.componentInstance.presets.set([{ value: '#00ff00', label: 'Green' }]);
+    fixture.detectChanges();
+    fireEvent.click(container.querySelector('.kj-color-picker-trigger')!);
+    fixture.detectChanges();
+    fireEvent.click(container.querySelector('.kj-color-picker-preset')!);
+    fixture.detectChanges();
+    expect(fixture.componentInstance.hex()).toBe('#00ff00');
+  });
+
+  it('passes axe audit when closed', async () => {
+    const { container } = await render(HostComponent);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it('passes axe audit when open with alpha and presets', async () => {
+    const { container, fixture } = await render(HostComponent);
+    fixture.componentInstance.showAlpha.set(true);
+    fixture.componentInstance.presets.set([
+      { value: '#ff0000', label: 'Red' },
+      { value: '#00ff00', label: 'Green' },
+    ]);
+    fixture.detectChanges();
+    fireEvent.click(container.querySelector('.kj-color-picker-trigger')!);
+    fixture.detectChanges();
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/color-picker/color-picker.ts

@@ -0,0 +1,234 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewChild,
+  ViewEncapsulation,
+  booleanAttribute,
+  input,
+  output,
+} from '@angular/core';
+import { NG_VALUE_ACCESSOR, type ControlValueAccessor } from '@angular/forms';
+import {
+  KjColorPicker,
+  KjColorPickerAlphaSlider,
+  KjColorPickerArea,
+  KjColorPickerHueSlider,
+  KjColorPickerInput,
+  KjColorPickerPanel,
+  KjColorPickerTrigger,
+  type KjColorFormat,
+  type KjColorPreset,
+  type KjColorValue,
+} from '@kouji-ui/core';
+
+/**
+ * Styled color-picker. Wraps the headless `KjColorPicker` family with a
+ * popover panel containing the saturation/value area, hue slider,
+ * optional alpha slider, hex input, and preset palette.
+ *
+ * Two-way bind through Angular forms:
+ *
+ * ```html
+ * <kj-color-picker [(ngModel)]="brand" kjFormat="hex" kjShowAlpha />
+ * ```
+ *
+ * @doc-example Default
+ *   Hex output, no alpha, no presets — the simplest two-way binding.
+ *   @doc-file color-picker.example.ts
+ * @doc-example Usage
+ *   A walkthrough of the most common color-picker usages — hex output, an
+ *   alpha channel, brand presets, and Angular forms.
+ *   @doc-file color-picker.usage.example.ts
+ * @doc-example With presets
+ *   A brand palette projected via `[kjPresets]` for one-click selection.
+ *   @doc-file color-picker.with-presets.example.ts
+ * @doc-example With alpha
+ *   `kjShowAlpha` mounts the alpha slider and switches to 8-char hex output.
+ *   @doc-file color-picker.alpha.example.ts
+ * @doc-example Hex input
+ *   The free-form hex text input inside the panel, validated on Enter / blur.
+ *   @doc-file color-picker.hex-input.example.ts
+ * @doc-example In a form
+ *   Bound via `[formControl]` inside a reactive form alongside other fields.
+ *   @doc-file color-picker.in-form.example.ts
+ *
+ * @doc-keyboard
+ *   Enter|Space — Opens the panel from the swatch trigger
+ *   ArrowLeft|ArrowRight — Steps the hue or alpha slider when focused
+ *   ArrowUp|ArrowDown    — Steps the saturation/value crosshair when the area is focused
+ *   Tab                  — Moves focus into and through the panel; cycles back to the trigger
+ *   Escape               — Closes the panel and restores focus to the trigger
+ *
+ * @doc-aria
+ *   aria-label    — Provided on the trigger; override with `[kjAriaLabel]`
+ *   aria-haspopup — "dialog" on the trigger button
+ *   aria-expanded — Reflects open / closed state on the trigger
+ *   aria-invalid  — Reflected on the panel hex input when the typed value fails to parse
+ *   role          — "listbox" on the preset row; "option" + `aria-selected` per swatch
+ *
+ * @doc-css-var
+ *   --kj-color-picker-current — Hex of the currently-selected color (no alpha). Used to paint the trigger swatch and the alpha-slider gradient.
+ *
+ * @doc-touch
+ *   The trigger swatch is 44×44px — meets WCAG 2.5.5 out of the box. Preset
+ *   chips are 24×24px and rely on the inline-control exception inside the
+ *   panel.
+ *
+ * @doc-a11y
+ *   The picker is a real combobox + popover — the trigger button has
+ *   `aria-haspopup="dialog"` and `aria-expanded`, the panel is mounted on the
+ *   body to escape clipping, and focus returns to the trigger on close.
+ *   `ControlValueAccessor` is wired so `[(ngModel)]` and `[formControl]` work
+ *   directly on `<kj-color-picker>` — the inner directive owns the canonical
+ *   accessor and we delegate.
+ *
+ * @doc-related input,form,field
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name color-picker
+ * @doc-description Themed color picker with saturation canvas, hue and alpha sliders, hex input, and preset swatches.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-color-picker',
+  standalone: true,
+  imports: [
+    KjColorPicker,
+    KjColorPickerTrigger,
+    KjColorPickerPanel,
+    KjColorPickerArea,
+    KjColorPickerHueSlider,
+    KjColorPickerAlphaSlider,
+    KjColorPickerInput,
+  ],
+  providers: [
+    {
+      provide: NG_VALUE_ACCESSOR,
+      useExisting: KjColorPickerComponent,
+      multi: true,
+    },
+  ],
+  template: `
+    <div
+      kjColorPicker
+      #root="kjColorPicker"
+      [kjFormat]="kjFormat()"
+      [kjShowAlpha]="kjShowAlpha()"
+      [kjAlwaysEmitAlpha]="kjAlwaysEmitAlpha()"
+      [kjPresets]="kjPresets()"
+      [kjInvalid]="kjInvalid()"
+      [kjAriaLabel]="kjAriaLabel()"
+      [kjDisabled]="kjDisabled()"
+      (kjOpenChange)="kjOpenChange.emit($event)"
+      (kjCommit)="kjCommit.emit($event)"
+    >
+      <button
+        type="button"
+        kjColorPickerTrigger
+        class="kj-color-picker-trigger"
+        aria-label="Open color picker"
+      ></button>
+      <div kjColorPickerPanel class="kj-color-picker-panel">
+        <div kjColorPickerArea class="kj-color-picker-area"></div>
+        <input kjColorPickerHueSlider class="kj-color-picker-hue-slider" />
+        @if (kjShowAlpha()) {
+          <input
+            kjColorPickerAlphaSlider
+            class="kj-color-picker-alpha-slider"
+            [style.--kj-color-picker-current]="opaqueCurrent(root)"
+          />
+        }
+        @if (kjShowHexInput()) {
+          <input kjColorPickerInput class="kj-color-picker-input" />
+        }
+        @if (kjPresets().length > 0) {
+          <div role="listbox" aria-label="Preset colors" class="kj-color-picker-presets">
+            @for (preset of kjPresets(); track preset.value) {
+              <button
+                type="button"
+                role="option"
+                class="kj-color-picker-preset"
+                [attr.aria-label]="preset.label ?? preset.value"
+                [attr.aria-selected]="preset.value.toLowerCase() === root.hex().toLowerCase() ? 'true' : 'false'"
+                [style.background]="preset.value"
+                (click)="selectPreset(root, preset)"
+              ></button>
+            }
+          </div>
+        }
+      </div>
+    </div>
+  `,
+  styleUrl: './color-picker.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-color-picker',
+    style: 'display: inline-block;',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjColorPickerComponent implements ControlValueAccessor {
+  /** Output format. Default `'hex'`. */
+  readonly kjFormat = input<KjColorFormat>('hex');
+  /** Mount the alpha slider and switch to 8-char hex output when α<1. */
+  readonly kjShowAlpha = input(false, { transform: booleanAttribute });
+  /** Force 8-char hex output even when α=1. */
+  readonly kjAlwaysEmitAlpha = input(false);
+  /** Brand-palette preset swatches. Empty array hides the preset row. */
+  readonly kjPresets = input<readonly KjColorPreset[]>([]);
+  /** Touched-gated invalid posture; mirrors `KjInput`. */
+  readonly kjInvalid = input(false);
+  /** Override the default "Color picker" name on the trigger. */
+  readonly kjAriaLabel = input<string>('');
+  /** Mirror the headless `KjDisabled` posture. */
+  readonly kjDisabled = input(false);
+  /** Show or hide the hex text input within the default panel layout. */
+  readonly kjShowHexInput = input<boolean>(true);
+
+  /** Fires when the panel transitions between open and closed. */
+  readonly kjOpenChange = output<boolean>();
+  /** Fires when the user commits a color (panel close, hex Enter, preset click). */
+  readonly kjCommit = output<KjColorValue>();
+
+  @ViewChild(KjColorPicker, { static: true })
+  protected innerPicker?: KjColorPicker;
+
+  /**
+   * Opaque-only current hex (no alpha digits). Used as the alpha-slider
+   * track's gradient end-stop so users see "current → transparent" at full
+   * saturation regardless of the active alpha value.
+   */
+  protected opaqueCurrent(root: KjColorPicker): string {
+    const rgb = root.rgb();
+    const toHex = (n: number) => Math.round(Math.max(0, Math.min(255, n)))
+      .toString(16).padStart(2, '0');
+    return `#${toHex(rgb.r)}${toHex(rgb.g)}${toHex(rgb.b)}`;
+  }
+
+  /** @internal */
+  protected selectPreset(root: KjColorPicker, preset: KjColorPreset): void {
+    root.setHex(preset.value);
+  }
+
+  // ── ControlValueAccessor ──────────────────────────────────────────
+  // Re-expose the inner directive's CVA so consumers can bind `[formControl]`
+  // / `[(ngModel)]` directly on `<kj-color-picker>`. The inner KjFormControl
+  // is the canonical accessor — we just delegate.
+
+  writeValue(val: unknown): void {
+    this.innerPicker?.formCtrl.writeValue(val);
+  }
+  registerOnChange(fn: (value: unknown) => void): void {
+    this.innerPicker?.formCtrl.registerOnChange(fn);
+  }
+  registerOnTouched(fn: () => void): void {
+    this.innerPicker?.formCtrl.registerOnTouched(fn);
+  }
+  setDisabledState(isDisabled: boolean): void {
+    this.innerPicker?.formCtrl.setDisabledState(isDisabled);
+  }
+}
+
+// Re-export types so consumers don't need a second import path.
+export type { KjColorFormat, KjColorPreset, KjColorValue };

package/src/color-picker/index.ts

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