@lostgradient/cinder 0.3.0 → 0.4.0

package/src/components/run-step-timeline/run-step-timeline.types.ts

@@ -9,12 +9,13 @@ import type { HTMLAttributes } from 'svelte/elements';
  * component does not encode product-specific status vocabulary.
  *
  * - `pending`   — not yet started; waiting in the queue.
- * - `running`   — currently executing; only one step should be running.
+ * - `running`   — currently executing within its lane.
  * - `succeeded` — completed successfully.
  * - `failed`    — completed with a terminal error.
  * - `cancelled` — was stopped before it could complete.
  * - `skipped`   — bypassed intentionally (e.g. conditional branch).
  * - `retrying`  — a prior attempt failed; a new attempt is in progress.
+ * - `waiting_approval` — paused on required approval; can continue afterward.
  */
 export type RunStepStatus =
   | 'pending'
@@ -23,7 +24,8 @@ export type RunStepStatus =
   | 'failed'
   | 'cancelled'
   | 'skipped'
-  | 'retrying';
+  | 'retrying'
+  | 'waiting_approval';
 
 /**
  * A single expandable detail section attached to a step.
@@ -38,6 +40,17 @@ export type RunStepDetail = {
   content: string;
 };
 
+/**
+ * Navigable reference attached to a step.
+ * Rendered with cinder's Link component.
+ */
+export type RunStepLink = {
+  /** Destination URL for the step link. */
+  href: string;
+  /** Visible text for the step link. */
+  label: string;
+};
+
 /**
  * One step in a RunStepTimeline.
  */
@@ -68,6 +81,71 @@ export type RunStep = {
    * Displayed when greater than 1.
    */
   attemptCount?: number | undefined;
+  /**
+   * Number of actions associated with this step.
+   * Displayed when greater than 0.
+   */
+  actionsCount?: number | undefined;
+  /**
+   * Optional determinate progress value between 0 and `progressMax`.
+   * When supplied, a Progress bar is rendered for the step.
+   */
+  progress?: number | undefined;
+  /**
+   * Maximum value for the progress bar. Defaults to 100.
+   */
+  progressMax?: number | undefined;
+  /**
+   * Expandable detail panels (logs, payloads, errors) shown inline.
+   */
+  details?: RunStepDetail[] | undefined;
+  /**
+   * Optional link to logs, traces, or a step detail route.
+   */
+  link?: RunStepLink | undefined;
+  /**
+   * Nested child-workflow steps rendered as indented lanes.
+   */
+  children?: RunStep[] | undefined;
+};
+
+/**
+ * Schema generator surface for one top-level step.
+ * Public `RunStep` stays recursive; this finite shape keeps JSON Schema generation bounded.
+ * @schemaObject
+ */
+export type RunStepTimelineSchemaStep = {
+  /** Stable identity; used as the keyed list identity. */
+  id: string;
+  /** Display label for this step. */
+  label: string;
+  /** Generic execution state. */
+  status: RunStepStatus;
+  /**
+   * ISO datetime string for when this step started.
+   * Absent for pending steps.
+   */
+  startTime?: string | undefined;
+  /**
+   * ISO datetime string for when this step ended.
+   * Absent for pending and running steps.
+   */
+  endTime?: string | undefined;
+  /**
+   * Human-readable duration string, e.g. "1m 23s".
+   * Absent for pending steps.
+   */
+  duration?: string | undefined;
+  /**
+   * Number of attempts made so far, including any retries.
+   * Displayed when greater than 1.
+   */
+  attemptCount?: number | undefined;
+  /**
+   * Number of actions associated with this step.
+   * Displayed when greater than 0.
+   */
+  actionsCount?: number | undefined;
   /**
    * Optional determinate progress value between 0 and `progressMax`.
    * When supplied, a Progress bar is rendered for the step.
@@ -81,6 +159,115 @@ export type RunStep = {
    * Expandable detail panels (logs, payloads, errors) shown inline.
    */
   details?: RunStepDetail[] | undefined;
+  /**
+   * Optional link to logs, traces, or a step detail route.
+   */
+  link?: RunStepLink | undefined;
+  /**
+   * Schema-bounded nested child-workflow steps.
+   */
+  children?: RunStepTimelineSchemaChildStep[] | undefined;
+};
+
+/**
+ * Schema generator surface for one nested child step rendered at depth 1.
+ * @schemaObject
+ */
+export type RunStepTimelineSchemaChildStep = {
+  /** Stable identity; used as the keyed list identity. */
+  id: string;
+  /** Display label for this step. */
+  label: string;
+  /** Generic execution state. */
+  status: RunStepStatus;
+  /** ISO datetime string for when this step started. */
+  startTime?: string | undefined;
+  /** ISO datetime string for when this step ended. */
+  endTime?: string | undefined;
+  /** Human-readable duration string, e.g. "1m 23s". */
+  duration?: string | undefined;
+  /** Number of attempts made so far, including any retries. */
+  attemptCount?: number | undefined;
+  /** Number of actions associated with this step. */
+  actionsCount?: number | undefined;
+  /** Optional determinate progress value between 0 and `progressMax`. */
+  progress?: number | undefined;
+  /** Maximum value for the progress bar. Defaults to 100. */
+  progressMax?: number | undefined;
+  /** Expandable detail panels (logs, payloads, errors) shown inline. */
+  details?: RunStepDetail[] | undefined;
+  /** Optional link to logs, traces, or a step detail route. */
+  link?: RunStepLink | undefined;
+  /**
+   * Nested child-workflow steps rendered at depth 2.
+   */
+  children?: RunStepTimelineSchemaGrandchildStep[] | undefined;
+};
+
+/**
+ * Schema generator surface for one nested child step rendered at depth 2.
+ * @schemaObject
+ */
+export type RunStepTimelineSchemaGrandchildStep = {
+  /** Stable identity; used as the keyed list identity. */
+  id: string;
+  /** Display label for this step. */
+  label: string;
+  /** Generic execution state. */
+  status: RunStepStatus;
+  /** ISO datetime string for when this step started. */
+  startTime?: string | undefined;
+  /** ISO datetime string for when this step ended. */
+  endTime?: string | undefined;
+  /** Human-readable duration string, e.g. "1m 23s". */
+  duration?: string | undefined;
+  /** Number of attempts made so far, including any retries. */
+  attemptCount?: number | undefined;
+  /** Number of actions associated with this step. */
+  actionsCount?: number | undefined;
+  /** Optional determinate progress value between 0 and `progressMax`. */
+  progress?: number | undefined;
+  /** Maximum value for the progress bar. Defaults to 100. */
+  progressMax?: number | undefined;
+  /** Expandable detail panels (logs, payloads, errors) shown inline. */
+  details?: RunStepDetail[] | undefined;
+  /** Optional link to logs, traces, or a step detail route. */
+  link?: RunStepLink | undefined;
+  /**
+   * Nested child-workflow steps rendered at depth 3.
+   */
+  children?: RunStepTimelineSchemaGreatGrandchildStep[] | undefined;
+};
+
+/**
+ * Schema generator surface for one nested child step rendered at depth 3.
+ * @schemaObject
+ */
+export type RunStepTimelineSchemaGreatGrandchildStep = {
+  /** Stable identity; used as the keyed list identity. */
+  id: string;
+  /** Display label for this step. */
+  label: string;
+  /** Generic execution state. */
+  status: RunStepStatus;
+  /** ISO datetime string for when this step started. */
+  startTime?: string | undefined;
+  /** ISO datetime string for when this step ended. */
+  endTime?: string | undefined;
+  /** Human-readable duration string, e.g. "1m 23s". */
+  duration?: string | undefined;
+  /** Number of attempts made so far, including any retries. */
+  attemptCount?: number | undefined;
+  /** Number of actions associated with this step. */
+  actionsCount?: number | undefined;
+  /** Optional determinate progress value between 0 and `progressMax`. */
+  progress?: number | undefined;
+  /** Maximum value for the progress bar. Defaults to 100. */
+  progressMax?: number | undefined;
+  /** Expandable detail panels (logs, payloads, errors) shown inline. */
+  details?: RunStepDetail[] | undefined;
+  /** Optional link to logs, traces, or a step detail route. */
+  link?: RunStepLink | undefined;
 };
 
 /**
@@ -115,7 +302,7 @@ export interface RunStepTimelineSchemaProps {
    * Ordered list of steps to render.
    * @schemaObject
    */
-  steps: RunStep[];
+  steps: RunStepTimelineSchemaStep[];
   /** Accessible label for the timeline list. */
   label?: string | undefined;
   /** Additional CSS classes applied to the root element. */

package/src/components/schema-form/README.md

@@ -1,6 +1,6 @@
 # SchemaForm
 
-Render an accessible form from a JSON Schema object or Standard Schema validator and submit one validated value.
+Render an accessible form from a JSON Schema object and submit one validated value.
 
 ## Usage
 
@@ -31,14 +31,14 @@ Render an accessible form from a JSON Schema object or Standard Schema validator
 
 <!-- generated:props:start -->
 
-| Prop          | Type       | Required | Default | Description                                                                                                                                                   |
-| ------------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`       | `string`   | no       | —       | Custom class merged with `.cinder-schema-form`.                                                                                                               |
-| `name`        | `string`   | no       | —       | Name of the hidden serialized output field. Defaults to `value`.                                                                                              |
-| `submitLabel` | `string`   | no       | —       | Label for the built-in submit button. Defaults to `Submit`.                                                                                                   |
-| `onsubmit`    | `(opaque)` | no       | —       | Called after validation passes with the schema-conformant output value. Not expressible in JSON Schema; see the component types for the signature.            |
-| `schema`      | `(opaque)` | yes      | —       | JSON Schema object or Standard Schema object used to render and validate the form. Not expressible in JSON Schema; see the component types for the signature. |
-| `value`       | `(opaque)` | no       | —       | Initial form value. Missing fields are seeded from the schema where possible. Not expressible in JSON Schema; see the component types for the signature.      |
+| Prop          | Type       | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`       | `string`   | no       | —       | Custom class merged with `.cinder-schema-form`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `name`        | `string`   | no       | —       | Name of the hidden serialized output field. Defaults to `value`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `submitLabel` | `string`   | no       | —       | Label for the built-in submit button. Defaults to `Submit`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `onsubmit`    | `(opaque)` | no       | —       | Called after validation passes with the schema-conformant output value. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `schema`      | `(opaque)` | yes      | —       | JSON Schema object used to render and validate the form. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `value`       | `(opaque)` | no       | —       | Initial form value. Missing fields are seeded from the schema where possible. **Seed-only — value changes do not reset form state.** After mount the consumer owns the form state. Changing `value` with the same `schema` does NOT reset the form (formValue, errors, rawDrafts). Only changing `schema` causes a remount and resets form state. This is intentional: the form is an editing surface and resetting it on every external value change would silently discard in-progress user edits. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/schema-form/index.ts

@@ -8,7 +8,6 @@ export type {
   SchemaFormOutput,
   SchemaFormProps,
   SchemaFormSchema,
-  SchemaFormStandardSchema,
   SchemaFormSubmitHandler,
 } from './schema-form.types.ts';
 export { SchemaForm };

package/src/components/schema-form/schema-form-async.fixture.ts

@@ -0,0 +1,101 @@
+/// <reference lib="dom" />
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { tick } from 'svelte';
+
+import { setupHappyDom } from '../../test/happy-dom.ts';
+
+setupHappyDom();
+
+function deferred<T>() {
+  let deferredResolve!: (value: T) => void;
+  let deferredReject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((resolve, reject) => {
+    deferredResolve = resolve;
+    deferredReject = reject;
+  });
+  return { promise, resolve: deferredResolve, reject: deferredReject };
+}
+
+let pendingValidation = deferred<unknown>();
+
+void mock.module('ajv/dist/2020.js', () => ({
+  default: class MockAjv2020 {
+    compile() {
+      return (value: unknown) => pendingValidation.promise.then(() => value);
+    }
+  },
+}));
+
+const { cleanup, fireEvent, render, screen } = await import('@testing-library/svelte');
+const { default: SchemaForm } = await import('./schema-form.svelte');
+
+async function flush(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+function formFrom(container: HTMLElement): HTMLFormElement {
+  const form = container.querySelector('form');
+  expect(form).toBeInstanceOf(HTMLFormElement);
+  if (!(form instanceof HTMLFormElement)) throw new TypeError('Expected SchemaForm form.');
+  return form;
+}
+
+describe('SchemaForm async JSON Schema validation fixture', () => {
+  afterEach(() => {
+    cleanup();
+    pendingValidation = deferred<unknown>();
+  });
+
+  test('awaits async submit validation and freezes edits until it resolves', async () => {
+    const submitted: unknown[] = [];
+    const { container } = render(SchemaForm, {
+      props: {
+        schema: {
+          $async: true,
+          type: 'object',
+          properties: { name: { type: 'string', title: 'Name' } },
+          required: ['name'],
+        },
+        value: { name: 'Ada' },
+        onsubmit: (value: unknown) => {
+          submitted.push(value);
+        },
+      },
+    });
+    await flush();
+
+    const input = screen.getByLabelText(/Name/);
+    const form = formFrom(container);
+    const event = new Event('submit', { bubbles: true, cancelable: true });
+    form.dispatchEvent(event);
+    await tick();
+
+    const submittingButton = screen.getByRole('button', { name: 'Validating...' });
+    try {
+      expect(submittingButton).toBeInstanceOf(HTMLButtonElement);
+      expect(input).toBeInstanceOf(HTMLInputElement);
+      if (!(submittingButton instanceof HTMLButtonElement)) {
+        throw new TypeError('Expected SchemaForm submit button.');
+      }
+      if (!(input instanceof HTMLInputElement)) throw new TypeError('Expected SchemaForm input.');
+
+      expect(event.defaultPrevented).toBe(true);
+      expect(submittingButton.disabled).toBe(true);
+      expect(input.disabled).toBe(true);
+
+      await fireEvent.input(input, { target: { value: 'Grace' } });
+    } finally {
+      pendingValidation.resolve({});
+      await flush();
+      await flush();
+    }
+
+    expect(submitted).toEqual([{ name: 'Ada' }]);
+    const readyButton = screen.getByRole('button', { name: 'Submit' });
+    expect(readyButton).toBeInstanceOf(HTMLButtonElement);
+    if (!(readyButton instanceof HTMLButtonElement)) {
+      throw new TypeError('Expected SchemaForm ready submit button.');
+    }
+    expect(readyButton.disabled).toBe(false);
+  });
+});