@kitn.ai/ui 0.16.0 → 0.18.0

package/src/components/tasks-card.tsx

@@ -8,17 +8,20 @@ import {
   createMemo,
   createEffect,
   on,
+  onMount,
   ErrorBoundary,
   createUniqueId,
 } from 'solid-js';
 import { cn } from '../utils/cn';
 import { Button } from '../ui/button';
+import { ProgressBar } from '../ui/progress-bar';
 import { Card } from './card';
+import { DismissedStub } from './dismissed-stub';
 import type { CardEnvelope, CardEvent, CardHost, CardResolution } from '../primitives/card-contract';
 import { useCardResolution } from './use-card-resolution';
 import { emitCardEvent } from '../primitives/card-routing';
 import { useCardHost } from '../primitives/card-host';
-import { Check } from 'lucide-solid';
+import { Check, Circle, CircleCheck, X } from 'lucide-solid';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types (tasks.schema.json) — see src/primitives/card-schemas/tasks.schema.json
@@ -33,7 +36,15 @@ export interface TasksTask {
 }
 
 export interface TasksCardData {
-  mode?: 'select'; // future: 'select' | 'progress'
+  /**
+   * `select` (default) = checkbox rows + a confirm button that emits the contract
+   * `submit`. `progress` = an onboarding/checklist look: a header `done / total`
+   * count, circular indicators, per-item title + muted description, and NO confirm
+   * button (checking a row is itself the terminal action). Both share the same
+   * selection model (toggle by id, the `max` gate, `kai-value-change`); `progress`
+   * is purely a presentational variant.
+   */
+  mode?: 'select' | 'progress';
   heading?: string;
   tasks: TasksTask[]; // >=1
   selectAll?: boolean;
@@ -41,6 +52,7 @@ export interface TasksCardData {
   allowEmpty?: boolean;
   min?: number;
   max?: number;
+  dismissible?: boolean; // show a close affordance that emits `dismiss`
 }
 
 export interface TasksCardResult {
@@ -121,6 +133,16 @@ export function showSelectAll(data: TasksCardData, tasks: TasksTask[]): boolean
   return true;
 }
 
+/** Whether the card is in the onboarding-checklist `progress` look (no confirm). */
+export function isProgressMode(data: TasksCardData): boolean {
+  return data.mode === 'progress';
+}
+
+/** The header progress count (`done` checked / `total` rows) for `progress` mode. */
+export function progressCount(tasks: TasksTask[], selected: Set<string>): { done: number; total: number } {
+  return { done: tasks.filter((t) => selected.has(t.id)).length, total: tasks.length };
+}
+
 /** Whether confirm is enabled for the current selection count. */
 export function canConfirm(data: TasksCardData, count: number): boolean {
   const min = data.min ?? (data.allowEmpty ? 0 : 1);
@@ -147,6 +169,24 @@ export function confirmReason(data: TasksCardData, count: number): string | unde
 // The <TasksCard> component.
 // ─────────────────────────────────────────────────────────────────────────────
 
+/** Imperative handle exposed via `controllerRef` — surfaces the tasks card's latent
+ *  selection model (set the checked ids, toggle one, confirm, focus the group,
+ *  dismiss/reopen) so the `<kai-tasks>` facade can forward them as instance methods. */
+export interface TasksCardController {
+  /** Set the checked ids (local-only, no emit), respecting disabled/max. No arg = select all toggleable rows. */
+  select(taskIds?: string[]): void;
+  /** Toggle one task by id, honoring the max gate. */
+  toggle(taskId: string, checked?: boolean): void;
+  /** Confirm the current selection (only when allowed) — emits `submit` + resolves. */
+  send(): void;
+  /** Focus the task group (select-all checkbox if shown, else the first row). */
+  focus(options?: FocusOptions): void;
+  /** Trigger the dismiss path (emit `dismiss` + collapse to the re-openable stub). */
+  dismiss(): void;
+  /** Re-open a dismissed card from its stub (emit `reopen`). */
+  reopen(): void;
+}
+
 export interface TasksCardProps {
   /** The tasks definition (CardEnvelope.data). */
   data?: TasksCardData;
@@ -162,6 +202,20 @@ export interface TasksCardProps {
   class?: string;
   /** When set, render the chromed read-only summary instead of the interactive controls. */
   resolution?: CardResolution;
+  /** Controlled selection (task ids) — when set, this wins over internal state. */
+  value?: string[];
+  /** Uncontrolled initial selection (task ids), overlaying per-task `checked`. */
+  defaultValue?: string[];
+  /** Freeze the whole list + Confirm. */
+  disabled?: boolean;
+  /** Display-only: rows can't be toggled and show the default cursor (no pointer,
+   *  no hover background, no focus ring). Keeps the visual content as-is — this only
+   *  drops the interactive affordances + a11y exposure. */
+  readonly?: boolean;
+  /** Fires on every selection change with the selected ids (distinct from submit). */
+  onValueChange?: (payload: { value: string[] }) => void;
+  /** Receive the imperative controller once mounted. */
+  controllerRef?: (controller: TasksCardController) => void;
 }
 
 const DEFAULT_DATA: TasksCardData = { tasks: [] };
@@ -175,7 +229,10 @@ const DEFAULT_DATA: TasksCardData = { tasks: [] };
  */
 export function TasksCard(props: TasksCardProps): JSX.Element {
   const merged = mergeProps({ cardId: 'kai-tasks' }, props);
-  const [local] = splitProps(merged, ['data', 'cardId', 'heading', 'host', 'hostElement', 'class', 'resolution']);
+  const [local] = splitProps(merged, [
+    'data', 'cardId', 'heading', 'host', 'hostElement', 'class', 'resolution',
+    'value', 'defaultValue', 'disabled', 'readonly', 'onValueChange', 'controllerRef',
+  ]);
 
   const ctxHost = useCardHost();
   const uid = createUniqueId();
@@ -196,16 +253,37 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
 
   const res = useCardResolution({ prop: () => local.resolution, data: () => local.data });
 
-  // Seed selection from the tasks' initial checked state when a NEW definition arrives.
+  // Only ids that exist in the current task list (drop unknown ids defensively).
+  const validIds = (ids: string[]): string[] => {
+    const known = new Set(tasks().map((t) => t.id));
+    return ids.filter((id) => known.has(id));
+  };
+
+  // Seed selection from `value` (controlled) > `defaultValue` > per-task `checked`,
+  // when a NEW definition arrives.
   createEffect(
     on(
       () => local.data,
       () => {
-        setSelected(new Set(initialSelected(tasks())));
+        const seedIds = local.value ?? local.defaultValue ?? initialSelected(tasks());
+        setSelected(new Set(validIds(seedIds)));
       },
     ),
   );
 
+  // Controlled selection: when the consumer drives `value`, mirror it into the set
+  // (the controlled prop wins). Deferred so mount's seed runs first.
+  createEffect(on(() => local.value, (v) => {
+    if (!v) return;
+    setSelected(new Set(validIds(v)));
+  }, { defer: true }));
+
+  // Fire the live change signal whenever the selection set changes (distinct from
+  // the terminal submit). Deferred so the initial seed doesn't emit.
+  createEffect(on(selected, (s) => {
+    local.onValueChange?.({ value: selectedInOrder(tasks(), s) });
+  }, { defer: true }));
+
   // ready / error lifecycle emits.
   createEffect(
     on(valid, (ok) => {
@@ -214,28 +292,41 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
     }),
   );
 
+  const groupDisabled = (): boolean => local.disabled === true;
+  // Display-only: block all toggling/confirm and drop the interactive affordances,
+  // without the dimmed/`disabled` look.
+  const readOnly = (): boolean => local.readonly === true;
+
   const count = createMemo(() => selected().size);
+  // `progress` mode = the onboarding-checklist look: a header `done / total`
+  // count, circular indicators, no confirm button. Same selection model.
+  const progress = createMemo(() => isProgressMode(data()));
+  const progressN = createMemo(() => progressCount(tasks(), selected()));
   const confirmLabel = () => data().confirmLabel ?? 'Confirm';
   const masterState = createMemo(() => selectAllState(tasks(), selected()));
   const showMaster = createMemo(() => showSelectAll(data(), tasks()));
   const reason = createMemo(() => confirmReason(data(), count()));
-  const confirmEnabled = createMemo(() => canConfirm(data(), count()) && !res.isResolved());
+  const confirmEnabled = createMemo(() => canConfirm(data(), count()) && !res.isResolved() && !groupDisabled() && !readOnly());
 
-  const toggle = (id: string, on: boolean): void => {
-    if (res.isResolved()) return;
-    const next = new Set(selected());
+  // Apply one id to a selection set, honoring the max gate (mutates+returns `next`).
+  const applyToggle = (next: Set<string>, id: string, on: boolean): Set<string> => {
     if (on) {
       // Respect max: block adding past max.
-      if (isMaxReached(data(), next.size) && !next.has(id)) return;
+      if (isMaxReached(data(), next.size) && !next.has(id)) return next;
       next.add(id);
     } else {
       next.delete(id);
     }
-    setSelected(next);
+    return next;
+  };
+
+  const toggle = (id: string, on: boolean): void => {
+    if (res.isResolved() || groupDisabled() || readOnly()) return;
+    setSelected(applyToggle(new Set(selected()), id, on));
   };
 
   const toggleAll = (on: boolean): void => {
-    if (res.isResolved()) return;
+    if (res.isResolved() || groupDisabled() || readOnly()) return;
     const next = new Set(selected());
     for (const id of toggleableIds(tasks())) {
       if (on) next.add(id);
@@ -251,11 +342,58 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
     res.setLocal({ kind: 'submit', data: result });
   };
 
-  // Surface the resolved state for host styling.
+  // Dismiss: emit `dismiss` AND optimistically flip to a `dismissed` resolution so
+  // the card collapses to its re-openable stub immediately.
+  const onDismiss = (): void => {
+    if (res.isResolved()) return;
+    emit({ kind: 'dismiss', cardId: local.cardId });
+    res.setLocal({ kind: 'dismissed' });
+  };
+  const onReopen = (): void => emit({ kind: 'reopen', cardId: local.cardId });
+
+  // Imperative controller (Pattern C): hand the facade a handle over the tasks
+  // card's latent selection model. select sets the checked ids local-only (no
+  // submit); toggle drives one row; send confirms (same path as Confirm); focus
+  // targets the group; dismiss/reopen drive the stub.
+  onMount(() => {
+    local.controllerRef?.({
+      select: (taskIds) => {
+        if (res.isResolved() || groupDisabled() || readOnly()) return;
+        if (taskIds === undefined) { toggleAll(true); return; }
+        // Build the set fresh, honoring max + disabled per id (skip disabled rows).
+        const next = new Set<string>();
+        const toggleable = new Set(toggleableIds(tasks()));
+        for (const id of validIds(taskIds)) {
+          if (!toggleable.has(id)) continue; // skip per-task-disabled rows
+          applyToggle(next, id, true);
+        }
+        setSelected(next);
+      },
+      toggle: (taskId, checked) => {
+        // No explicit `checked` → flip the current state.
+        const on = checked ?? !selected().has(taskId);
+        toggle(taskId, on);
+      },
+      send: () => onConfirm(),
+      focus: (options) => {
+        const root = local.hostElement?.shadowRoot ?? document;
+        const group = root.querySelector<HTMLElement>('[role="group"]');
+        // Prefer the select-all checkbox (it's the first labelled input), else the
+        // first row's checkbox; fall back to the group container itself.
+        const firstInput = group?.querySelector<HTMLElement>('input[type="checkbox"]');
+        (firstInput ?? group)?.focus(options);
+      },
+      dismiss: () => onDismiss(),
+      reopen: () => onReopen(),
+    });
+  });
+
+  // Surface the resolved state for host styling. Only a `submit` resolution is the
+  // "submitted" state; a deferred `dismissed` (or `expired`) is not.
   createEffect(() => {
     const el = local.hostElement;
     if (!el) return;
-    if (res.isResolved()) el.setAttribute('data-kai-resolved', 'submitted');
+    if (res.resolution()?.kind === 'submit') el.setAttribute('data-kai-resolved', 'submitted');
     else el.removeAttribute('data-kai-resolved');
   });
 
@@ -271,6 +409,9 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
 
   const reasonId = `kai-tl-reason-${uid}`;
   const countId = `kai-tl-count-${uid}`;
+  const progressCountId = `kai-tl-progress-${uid}`;
+  const progressHeadingId = `kai-tl-heading-${uid}`;
+  const headingText = () => local.heading ?? local.data?.heading;
 
   return (
     <Show when={valid()} fallback={<Card heading={local.heading} errorMessage={errorMessage()} />}>
@@ -280,11 +421,33 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
           return <Card heading={local.heading} errorMessage="The card failed to render." />;
         }}
       >
+        <Show
+          when={!res.isDeferred()}
+          fallback={
+            <DismissedStub type={TASKS_CARD_TYPE} title={local.heading ?? local.data?.heading} onReopen={onReopen} />
+          }
+        >
         <Card
-          heading={local.heading ?? local.data?.heading}
+          // In `progress` mode the heading + count render as a custom in-body row
+          // (so the count can sit right-aligned beside the heading), so the Card
+          // chrome's own heading is suppressed.
+          heading={progress() ? undefined : headingText()}
           actions={
-            res.isResolved() ? undefined : (
+            // `progress` mode is confirm-less: checking a row IS the action.
+            // `readonly` is display-only, so there's no confirm/dismiss row either.
+            progress() || res.isResolved() || readOnly() ? undefined : (
               <div class="flex w-full flex-wrap items-center justify-between gap-2">
+                <Show when={local.data?.dismissible === true}>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon-sm"
+                    aria-label="Dismiss"
+                    onClick={onDismiss}
+                  >
+                    <X size={16} aria-hidden="true" />
+                  </Button>
+                </Show>
                 <span id={countId} aria-live="polite" class="text-xs text-muted-foreground">
                   {count()} selected
                 </span>
@@ -311,9 +474,31 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
             when={!res.isResolved()}
             fallback={<TasksResolved summary={resolvedSummary()!} optimistic={res.isOptimistic()} />}
           >
+            <Show when={progress()}>
+              <ProgressChecklist
+                heading={headingText()}
+                headingId={progressHeadingId}
+                countId={progressCountId}
+                done={progressN().done}
+                total={progressN().total}
+                tasks={tasks()}
+                uid={uid}
+                isChecked={(id) => selected().has(id)}
+                isBlocked={(task) =>
+                  groupDisabled() || task.disabled === true ||
+                  (!selected().has(task.id) && isMaxReached(data(), count()))
+                }
+                onToggle={(id, on) => toggle(id, on)}
+                groupClass={local.class}
+                maxNote={data().max !== undefined ? data().max : undefined}
+                readonly={readOnly()}
+              />
+            </Show>
+            <Show when={!progress()}>
             <div
               role="group"
               aria-label={local.heading ?? local.data?.heading ?? 'Tasks'}
+              aria-readonly={readOnly() ? 'true' : undefined}
               class={cn('flex flex-col', local.class)}
               onKeyDown={(e) => {
                 // Enter anywhere in the card (off a checkbox) confirms when enabled.
@@ -330,16 +515,20 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
                     return (
                       <label
                         class={cn(
-                          'flex cursor-pointer items-center gap-3 px-3 py-2.5 text-sm font-medium transition-colors',
+                          'flex items-center gap-3 px-3 py-2.5 text-sm font-medium transition-colors',
+                          readOnly() ? 'cursor-default' : 'cursor-pointer',
                           masterState() === 'checked'
                             ? 'bg-accent text-accent-foreground'
-                            : 'text-foreground hover:bg-muted/50',
+                            : readOnly()
+                              ? 'text-foreground'
+                              : 'text-foreground hover:bg-muted/50',
                         )}
                       >
                         <input
                           type="checkbox"
                           class="kai-checkbox"
                           checked={masterState() === 'checked'}
+                          disabled={groupDisabled() || readOnly()}
                           aria-checked={indeterminate() ? 'mixed' : masterState() === 'checked'}
                           ref={(el) => {
                             createEffect(() => {
@@ -358,15 +547,17 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
                   {(task) => {
                     const checked = () => selected().has(task.id);
                     const blocked = () =>
-                      task.disabled || (!checked() && isMaxReached(data(), count()));
+                      groupDisabled() || task.disabled || (!checked() && isMaxReached(data(), count()));
                     const descId = `kai-tl-desc-${uid}-${task.id}`;
                     return (
                       <label
                         class={cn(
                           'flex items-start gap-3 px-3 py-2.5 text-sm transition-colors',
-                          blocked()
-                            ? 'cursor-not-allowed opacity-60'
-                            : 'cursor-pointer hover:bg-muted/50',
+                          readOnly()
+                            ? 'cursor-default'
+                            : blocked()
+                              ? 'cursor-not-allowed opacity-60'
+                              : 'cursor-pointer hover:bg-muted/50',
                           checked() && !blocked()
                             ? 'bg-accent font-medium text-accent-foreground'
                             : 'text-foreground',
@@ -377,7 +568,7 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
                           type="checkbox"
                           class="kai-checkbox mt-0.5"
                           checked={checked()}
-                          disabled={blocked()}
+                          disabled={blocked() || readOnly()}
                           aria-disabled={blocked() ? 'true' : undefined}
                           aria-describedby={task.description ? descId : undefined}
                           onChange={(e) => toggle(task.id, e.currentTarget.checked)}
@@ -400,13 +591,173 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
                 <p class="pt-1 text-xs text-muted-foreground">Up to {data().max} selected.</p>
               </Show>
             </div>
+            </Show>
           </Show>
         </Card>
+        </Show>
       </ErrorBoundary>
     </Show>
   );
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Onboarding-checklist (`mode: 'progress'`) presenter: a header `done / total`
+// count + circular indicators + per-item title/description, no confirm button.
+// Drives the same selection model, where toggling a row IS the action.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function ProgressChecklist(props: {
+  heading?: string;
+  headingId: string;
+  countId: string;
+  done: number;
+  total: number;
+  tasks: TasksTask[];
+  uid: string;
+  isChecked: (id: string) => boolean;
+  isBlocked: (task: TasksTask) => boolean;
+  onToggle: (id: string, on: boolean) => void;
+  groupClass?: string;
+  maxNote?: number;
+  /** Display-only: rows aren't focusable/toggleable and show the default cursor. */
+  readonly?: boolean;
+}): JSX.Element {
+  return (
+    <div class={cn('flex flex-col gap-3', props.groupClass)}>
+      <Show when={props.heading}>
+        <div class="flex items-center justify-between gap-3">
+          <span id={props.headingId} class="text-sm font-medium text-foreground">
+            {props.heading}
+          </span>
+          <span
+            id={props.countId}
+            aria-live="polite"
+            class="shrink-0 text-sm font-medium tabular-nums text-muted-foreground"
+          >
+            {props.done} / {props.total}
+          </span>
+        </div>
+      </Show>
+
+      {/* Thin progress bar under the heading: filled to done / total. Named off the
+          checklist heading (no duplicate caption), or a generic label when headless. */}
+      <ProgressBar
+        value={props.done}
+        max={props.total}
+        tone="success"
+        aria-labelledby={props.heading ? props.headingId : undefined}
+        aria-label={props.heading ? undefined : 'Task progress'}
+      />
+
+      <ul
+        aria-labelledby={props.heading ? props.headingId : undefined}
+        aria-label={props.heading ? undefined : 'Checklist'}
+        aria-readonly={props.readonly ? 'true' : undefined}
+        class="flex flex-col gap-1"
+      >
+        <For each={props.tasks}>
+          {(task) => {
+            const checked = () => props.isChecked(task.id);
+            const blocked = () => props.isBlocked(task);
+            const descId = `kai-tl-pdesc-${props.uid}-${task.id}`;
+            return (
+              <li>
+                <label
+                  class={cn(
+                    'group flex items-start gap-3 rounded-lg px-2.5 py-2 text-sm transition-colors',
+                    // Keyboard focus ring (kit standard, inset so it stays within the
+                    // row). focus-visible only, so a mouse click that parks focus on the
+                    // row doesn't leave a noisy persistent outline — and it makes a
+                    // Tab-focused completed row's open description perceivable. Dropped
+                    // entirely when readonly (the row isn't focusable then).
+                    !props.readonly &&
+                      'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring',
+                    props.readonly
+                      ? 'cursor-default'
+                      : blocked()
+                        ? 'cursor-not-allowed opacity-60'
+                        : 'cursor-pointer hover:bg-muted/50',
+                  )}
+                  data-task-id={task.id}
+                  // Completed rows hide their description until hover/focus, so make the
+                  // row itself focusable to drive the focus-reveal (group-focus-within).
+                  // Incomplete rows — and every row when readonly — stay unfocusable.
+                  // Expose the label + description to AT.
+                  tabindex={!props.readonly && checked() ? 0 : undefined}
+                  aria-label={checked() ? task.label : undefined}
+                  aria-describedby={checked() && task.description ? descId : undefined}
+                >
+                  <input
+                    type="checkbox"
+                    class="sr-only"
+                    checked={checked()}
+                    disabled={blocked() || props.readonly}
+                    aria-disabled={blocked() ? 'true' : undefined}
+                    aria-describedby={task.description ? descId : undefined}
+                    onChange={(e) => props.onToggle(task.id, e.currentTarget.checked)}
+                  />
+                  <span
+                    class={cn(
+                      'mt-0.5 shrink-0 text-muted-foreground',
+                      // Completed rows: the check gently scales on hover.
+                      checked() && 'motion-safe:transition-transform motion-safe:group-hover:scale-110',
+                    )}
+                    aria-hidden="true"
+                  >
+                    <Show
+                      when={checked()}
+                      fallback={<Circle size={18} />}
+                    >
+                      <CircleCheck size={18} class="text-foreground" />
+                    </Show>
+                  </span>
+                  <span class="flex min-w-0 flex-col gap-0.5">
+                    <span
+                      class={cn(
+                        'font-medium text-foreground',
+                        // Completed: strike through + muted, brightening on hover.
+                        checked() && 'line-through opacity-70 motion-safe:transition-opacity motion-safe:group-hover:opacity-100',
+                      )}
+                    >
+                      {task.label}
+                    </span>
+                    <Show when={task.description}>
+                      <Show
+                        when={checked()}
+                        fallback={
+                          <span id={descId} class="text-xs font-normal text-muted-foreground">
+                            {task.description}
+                          </span>
+                        }
+                      >
+                        {/* Completed: collapse the description and reveal it on hover or
+                            keyboard focus via the grid-rows height trick. Height-collapse
+                            keeps the text in the DOM + a11y tree (unlike display:none). */}
+                        <div class="grid grid-rows-[0fr] group-hover:grid-rows-[1fr] group-focus-within:grid-rows-[1fr] motion-safe:transition-[grid-template-rows] motion-safe:duration-200">
+                          <span
+                            id={descId}
+                            class="overflow-hidden text-xs font-normal text-muted-foreground opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 motion-safe:transition-opacity"
+                          >
+                            {task.description}
+                          </span>
+                        </div>
+                      </Show>
+                    </Show>
+                  </span>
+                </label>
+              </li>
+            );
+          }}
+        </For>
+      </ul>
+
+      <Show when={props.maxNote !== undefined}>
+        <p class="text-xs text-muted-foreground">Up to {props.maxNote} selected.</p>
+      </Show>
+    </div>
+  );
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Read-only resolved summary presenter.
 // ─────────────────────────────────────────────────────────────────────────────