@kiwa-test/component 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cardene777
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -20,25 +20,53 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  COMPONENT_AXIS_TO_EVENTS: () => COMPONENT_AXIS_TO_EVENTS,
   addHandler: () => addHandler,
   appendChild: () => appendChild,
+  applyOptimisticUpdate: () => applyOptimisticUpdate,
+  assertAnimation: () => assertAnimation,
+  assertMode: () => assertMode,
+  beginRscRender: () => beginRscRender,
   buildButton: () => buildButton,
   buildCard: () => buildCard,
   buildForm: () => buildForm,
   buildInput: () => buildInput,
   buildModal: () => buildModal,
+  captureErrorBoundary: () => captureErrorBoundary,
+  collectFidelityCoverage: () => collectFidelityCoverage,
+  completeRscRender: () => completeRscRender,
+  completeSelectiveHydration: () => completeSelectiveHydration,
   componentFixtures: () => componentFixtures,
   createCanvas: () => createCanvas,
   createChromaticVisualMock: () => createChromaticVisualMock,
   createNode: () => createNode,
   createPlaywrightCTMock: () => createPlaywrightCTMock,
   createStoryRegistry: () => createStoryRegistry,
+  enableProgressiveEnhancement: () => enableProgressiveEnhancement,
+  enterSuspenseBoundary: () => enterSuspenseBoundary,
+  failRscRender: () => failRscRender,
   findByRole: () => findByRole,
   findByText: () => findByText,
+  finishElementTransition: () => finishElementTransition,
   fireEvent: () => fireEvent,
   hashMarkup: () => hashMarkup,
+  markFormStatusPending: () => markFormStatusPending,
+  markSuspensePending: () => markSuspensePending,
+  providerEventName: () => providerEventName,
   query: () => query,
-  renderMarkup: () => renderMarkup
+  rejectFormAction: () => rejectFormAction,
+  renderMarkup: () => renderMarkup,
+  resolveAllModes: () => resolveAllModes,
+  resolveFormAction: () => resolveFormAction,
+  resolveMode: () => resolveMode,
+  startDocumentTransition: () => startDocumentTransition,
+  startElementTransition: () => startElementTransition,
+  startFormActionSession: () => startFormActionSession,
+  startProgressiveHydration: () => startProgressiveHydration,
+  startRscHarness: () => startRscHarness,
+  startStreamingSsr: () => startStreamingSsr,
+  startViewTransitionSession: () => startViewTransitionSession,
+  streamHtmlChunk: () => streamHtmlChunk
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -777,26 +805,490 @@ var componentFixtures = {
   Modal: buildModal,
   Card: buildCard
 };
+
+// src/semantics/types.ts
+var dialect = {
+  storybook8: {
+    "rsc.render_started": "storybook.play.start",
+    "rsc.suspense_boundary": "storybook.suspense.fallback",
+    "rsc.html_chunk_streamed": "storybook.stream.chunk",
+    "rsc.render_completed": "storybook.play.done",
+    "ssr.suspense_pending": "storybook.suspense.pending",
+    "ssr.error_boundary_captured": "storybook.error.boundary",
+    "ssr.progressive_hydration_started": "storybook.hydration.progressive",
+    "ssr.selective_hydration_completed": "storybook.hydration.selective",
+    "transition.element_started": "storybook.transition.element.start",
+    "transition.element_finished": "storybook.transition.element.finish",
+    "transition.document_started": "storybook.transition.document.start",
+    "transition.animation_asserted": "storybook.animation.assert",
+    "form.status_pending": "storybook.form.pending",
+    "form.optimistic_applied": "storybook.form.optimistic",
+    "form.progressive_enhanced": "storybook.form.enhanced",
+    "form.action_resolved": "storybook.form.resolved"
+  },
+  "playwright-ct": {
+    "rsc.render_started": "pwct.mount.rsc.start",
+    "rsc.suspense_boundary": "pwct.locator.suspense.fallback",
+    "rsc.html_chunk_streamed": "pwct.response.chunk",
+    "rsc.render_completed": "pwct.mount.rsc.done",
+    "ssr.suspense_pending": "pwct.suspense.pending",
+    "ssr.error_boundary_captured": "pwct.error.boundary",
+    "ssr.progressive_hydration_started": "pwct.hydration.progressive",
+    "ssr.selective_hydration_completed": "pwct.hydration.selective",
+    "transition.element_started": "pwct.transition.element.start",
+    "transition.element_finished": "pwct.transition.element.finish",
+    "transition.document_started": "pwct.transition.document.start",
+    "transition.animation_asserted": "pwct.animation.assert",
+    "form.status_pending": "pwct.form.pending",
+    "form.optimistic_applied": "pwct.form.optimistic",
+    "form.progressive_enhanced": "pwct.form.enhanced",
+    "form.action_resolved": "pwct.form.resolved"
+  },
+  chromatic: {
+    "rsc.render_started": "chromatic.capture.rsc.start",
+    "rsc.suspense_boundary": "chromatic.capture.suspense",
+    "rsc.html_chunk_streamed": "chromatic.capture.chunk",
+    "rsc.render_completed": "chromatic.capture.rsc.done",
+    "ssr.suspense_pending": "chromatic.suspense.pending",
+    "ssr.error_boundary_captured": "chromatic.error.snapshot",
+    "ssr.progressive_hydration_started": "chromatic.hydration.progressive",
+    "ssr.selective_hydration_completed": "chromatic.hydration.selective",
+    "transition.element_started": "chromatic.transition.element.start",
+    "transition.element_finished": "chromatic.transition.element.finish",
+    "transition.document_started": "chromatic.transition.document.start",
+    "transition.animation_asserted": "chromatic.animation.assert",
+    "form.status_pending": "chromatic.form.pending",
+    "form.optimistic_applied": "chromatic.form.optimistic",
+    "form.progressive_enhanced": "chromatic.form.enhanced",
+    "form.action_resolved": "chromatic.form.resolved"
+  }
+};
+function providerEventName(target, neutral) {
+  return dialect[target][neutral] ?? neutral;
+}
+
+// src/semantics/rsc-harness.ts
+function startRscHarness(input) {
+  if (input.componentId.length === 0) {
+    throw new Error("startRscHarness: componentId must not be empty");
+  }
+  return {
+    target: input.target,
+    componentId: input.componentId,
+    state: "idle",
+    chunks: [],
+    suspenseFallback: input.suspenseFallback ?? null,
+    history: [],
+    error: null
+  };
+}
+function beginRscRender(session) {
+  if (session.state !== "idle") {
+    throw new Error(`beginRscRender: session is ${session.state}, not idle`);
+  }
+  session.state = "rendering";
+  return emit(session, "rsc.render_started", { componentId: session.componentId });
+}
+function enterSuspenseBoundary(session, fallback = session.suspenseFallback ?? '<template data-suspense="pending"></template>') {
+  if (session.state !== "rendering") {
+    throw new Error(`enterSuspenseBoundary: session is ${session.state}, not rendering`);
+  }
+  session.state = "suspended";
+  session.suspenseFallback = fallback;
+  return emit(session, "rsc.suspense_boundary", { fallback });
+}
+function streamHtmlChunk(session, chunk) {
+  if (session.state !== "rendering" && session.state !== "suspended" && session.state !== "streaming") {
+    throw new Error(`streamHtmlChunk: session is ${session.state}, cannot stream`);
+  }
+  if (chunk.length === 0) {
+    throw new Error("streamHtmlChunk: chunk must not be empty");
+  }
+  session.state = "streaming";
+  session.chunks.push(chunk);
+  return emit(session, "rsc.html_chunk_streamed", {
+    chunk,
+    chunkIndex: session.chunks.length - 1,
+    bytes: chunk.length
+  });
+}
+function completeRscRender(session) {
+  if (session.state !== "rendering" && session.state !== "suspended" && session.state !== "streaming") {
+    throw new Error(`completeRscRender: session is ${session.state}, cannot complete`);
+  }
+  session.state = "completed";
+  return emit(session, "rsc.render_completed", {
+    chunkCount: session.chunks.length,
+    html: session.chunks.join("")
+  });
+}
+function failRscRender(session, error) {
+  if (session.state === "completed") {
+    throw new Error("failRscRender: completed session cannot fail");
+  }
+  session.state = "errored";
+  session.error = typeof error === "string" ? error : error.message;
+  return emit(session, "ssr.error_boundary_captured", {
+    componentId: session.componentId,
+    error: session.error
+  });
+}
+function emit(session, neutralEvent, metadata) {
+  const step = {
+    neutralEvent,
+    providerEvent: providerEventName(session.target, neutralEvent),
+    state: session.state,
+    amountCents: 0,
+    metadata: { target: session.target, ...metadata }
+  };
+  session.history.push(step);
+  return step;
+}
+
+// src/semantics/streaming-ssr.ts
+function startStreamingSsr(input) {
+  if (input.routeId.length === 0) {
+    throw new Error("startStreamingSsr: routeId must not be empty");
+  }
+  return {
+    target: input.target,
+    routeId: input.routeId,
+    state: "idle",
+    pendingBoundaries: /* @__PURE__ */ new Set(),
+    hydratedBoundaries: /* @__PURE__ */ new Set(),
+    errors: [],
+    history: []
+  };
+}
+function markSuspensePending(session, boundaryId) {
+  assertBoundaryId(boundaryId);
+  session.state = "suspense-pending";
+  session.pendingBoundaries.add(boundaryId);
+  return emit2(session, "ssr.suspense_pending", { boundaryId, pendingCount: session.pendingBoundaries.size });
+}
+function captureErrorBoundary(session, input) {
+  assertBoundaryId(input.boundaryId);
+  const message = typeof input.error === "string" ? input.error : input.error.message;
+  session.state = "error-captured";
+  session.errors.push({ boundaryId: input.boundaryId, message });
+  if (input.recoverable === false) {
+    session.pendingBoundaries.delete(input.boundaryId);
+  }
+  return emit2(session, "ssr.error_boundary_captured", {
+    boundaryId: input.boundaryId,
+    message,
+    recoverable: input.recoverable ?? true
+  });
+}
+function startProgressiveHydration(session, boundaryId) {
+  assertBoundaryId(boundaryId);
+  if (!session.pendingBoundaries.has(boundaryId)) {
+    throw new Error(`startProgressiveHydration: ${boundaryId} is not pending`);
+  }
+  session.state = "progressive-hydrating";
+  return emit2(session, "ssr.progressive_hydration_started", { boundaryId });
+}
+function completeSelectiveHydration(session, boundaryId) {
+  assertBoundaryId(boundaryId);
+  if (!session.pendingBoundaries.has(boundaryId)) {
+    throw new Error(`completeSelectiveHydration: ${boundaryId} is not pending`);
+  }
+  session.pendingBoundaries.delete(boundaryId);
+  session.hydratedBoundaries.add(boundaryId);
+  session.state = "selective-hydrated";
+  return emit2(session, "ssr.selective_hydration_completed", {
+    boundaryId,
+    hydratedCount: session.hydratedBoundaries.size,
+    remainingPending: session.pendingBoundaries.size
+  });
+}
+function assertBoundaryId(boundaryId) {
+  if (boundaryId.length === 0) {
+    throw new Error("boundaryId must not be empty");
+  }
+}
+function emit2(session, neutralEvent, metadata) {
+  const step = {
+    neutralEvent,
+    providerEvent: providerEventName(session.target, neutralEvent),
+    state: session.state,
+    amountCents: 0,
+    metadata: { target: session.target, routeId: session.routeId, ...metadata }
+  };
+  session.history.push(step);
+  return step;
+}
+
+// src/semantics/view-transitions.ts
+function startViewTransitionSession(input) {
+  if (input.transitionId.length === 0) {
+    throw new Error("startViewTransitionSession: transitionId must not be empty");
+  }
+  return {
+    target: input.target,
+    transitionId: input.transitionId,
+    state: "idle",
+    activeElements: /* @__PURE__ */ new Set(),
+    documentTransition: null,
+    assertions: [],
+    history: []
+  };
+}
+function startElementTransition(session, input) {
+  if (input.elementId.length === 0) {
+    throw new Error("startElementTransition: elementId must not be empty");
+  }
+  session.state = "element-transitioning";
+  session.activeElements.add(input.elementId);
+  return emit3(session, "transition.element_started", input);
+}
+function finishElementTransition(session, elementId) {
+  if (!session.activeElements.has(elementId)) {
+    throw new Error(`finishElementTransition: ${elementId} is not active`);
+  }
+  session.activeElements.delete(elementId);
+  session.state = session.activeElements.size === 0 ? "finished" : "element-transitioning";
+  return emit3(session, "transition.element_finished", {
+    elementId,
+    remaining: session.activeElements.size
+  });
+}
+function startDocumentTransition(session, input) {
+  if (input.name.length === 0) {
+    throw new Error("startDocumentTransition: name must not be empty");
+  }
+  session.state = "document-transitioning";
+  session.documentTransition = input.name;
+  return emit3(session, "transition.document_started", input);
+}
+function assertAnimation(session, input) {
+  if (input.durationMs < 0) {
+    throw new Error("assertAnimation: durationMs must be >= 0");
+  }
+  session.state = "asserted";
+  session.assertions.push(input.assertionId);
+  return emit3(session, "transition.animation_asserted", {
+    assertionId: input.assertionId,
+    durationMs: input.durationMs,
+    easing: input.easing ?? "linear"
+  });
+}
+function emit3(session, neutralEvent, metadata) {
+  const step = {
+    neutralEvent,
+    providerEvent: providerEventName(session.target, neutralEvent),
+    state: session.state,
+    amountCents: 0,
+    metadata: { target: session.target, transitionId: session.transitionId, ...metadata }
+  };
+  session.history.push(step);
+  return step;
+}
+
+// src/semantics/form-action-advanced.ts
+function startFormActionSession(input) {
+  if (input.formId.length === 0) {
+    throw new Error("startFormActionSession: formId must not be empty");
+  }
+  return {
+    target: input.target,
+    formId: input.formId,
+    state: "idle",
+    form: { ...input.initial },
+    optimisticPatches: [],
+    enhanced: false,
+    history: [],
+    error: null
+  };
+}
+function markFormStatusPending(session, submitter) {
+  if (session.state === "pending") {
+    throw new Error("markFormStatusPending: form is already pending");
+  }
+  session.state = "pending";
+  return emit4(session, "form.status_pending", { submitter });
+}
+function applyOptimisticUpdate(session, patch) {
+  if (session.state !== "pending" && session.state !== "optimistic") {
+    throw new Error(`applyOptimisticUpdate: session is ${session.state}, not pending`);
+  }
+  session.state = "optimistic";
+  session.optimisticPatches.push(patch);
+  session.form = { ...session.form, ...patch };
+  return emit4(session, "form.optimistic_applied", {
+    patchKeys: Object.keys(patch).join(","),
+    patchCount: session.optimisticPatches.length
+  });
+}
+function enableProgressiveEnhancement(session, input) {
+  if (input.actionUrl.length === 0) {
+    throw new Error("enableProgressiveEnhancement: actionUrl must not be empty");
+  }
+  session.enhanced = true;
+  session.state = "enhanced";
+  return emit4(session, "form.progressive_enhanced", {
+    method: input.method ?? "post",
+    actionUrl: input.actionUrl
+  });
+}
+function resolveFormAction(session, result) {
+  if (session.state === "idle") {
+    throw new Error("resolveFormAction: action was not submitted");
+  }
+  session.state = "resolved";
+  session.form = { ...session.form, ...result };
+  return emit4(session, "form.action_resolved", {
+    resultKeys: Object.keys(result).join(","),
+    enhanced: session.enhanced
+  });
+}
+function rejectFormAction(session, error) {
+  if (session.state === "resolved") {
+    throw new Error("rejectFormAction: resolved action cannot reject");
+  }
+  session.state = "rejected";
+  session.error = typeof error === "string" ? error : error.message;
+  return emit4(session, "form.action_resolved", {
+    rejected: true,
+    error: session.error
+  });
+}
+function emit4(session, neutralEvent, metadata) {
+  const step = {
+    neutralEvent,
+    providerEvent: providerEventName(session.target, neutralEvent),
+    state: session.state,
+    amountCents: 0,
+    metadata: { target: session.target, formId: session.formId, ...metadata }
+  };
+  session.history.push(step);
+  return step;
+}
+
+// src/semantics/fidelity.ts
+var COMPONENT_AXIS_TO_EVENTS = {
+  "rsc-harness": [
+    "rsc.render_started",
+    "rsc.suspense_boundary",
+    "rsc.html_chunk_streamed",
+    "rsc.render_completed"
+  ],
+  "streaming-ssr": [
+    "ssr.suspense_pending",
+    "ssr.error_boundary_captured",
+    "ssr.progressive_hydration_started",
+    "ssr.selective_hydration_completed"
+  ],
+  "view-transitions": [
+    "transition.element_started",
+    "transition.element_finished",
+    "transition.document_started",
+    "transition.animation_asserted"
+  ],
+  "form-action-advanced": [
+    "form.status_pending",
+    "form.optimistic_applied",
+    "form.progressive_enhanced",
+    "form.action_resolved"
+  ]
+};
+function collectFidelityCoverage(providers = ["storybook8", "playwright-ct", "chromatic"]) {
+  const axes = Object.keys(COMPONENT_AXIS_TO_EVENTS);
+  const rows = [];
+  for (const provider of providers) {
+    for (const axis of axes) {
+      const neutralEvents = COMPONENT_AXIS_TO_EVENTS[axis];
+      rows.push({
+        provider,
+        axis,
+        neutralEvents,
+        providerEvents: neutralEvents.map((event) => providerEventName(provider, event))
+      });
+    }
+  }
+  return { providers, axes, rows };
+}
+
+// src/real-driver.ts
+var TARGET_KEY_ENV = {
+  storybook8: "STORYBOOK_URL",
+  "playwright-ct": "PLAYWRIGHT_CT_URL",
+  chromatic: "CHROMATIC_TOKEN"
+};
+function resolveMode(provider, env = process.env) {
+  const rawMode = env.KIWA_MODE?.toLowerCase();
+  if (rawMode !== void 0 && rawMode !== "real" && rawMode !== "mock") {
+    return { provider, mode: "mock", reason: "invalid-mode" };
+  }
+  if (rawMode !== "real") {
+    return { provider, mode: "mock", reason: "default-mock" };
+  }
+  const keyValue = env[TARGET_KEY_ENV[provider]];
+  if (typeof keyValue !== "string" || keyValue.length === 0) {
+    return { provider, mode: "mock", reason: "missing-key" };
+  }
+  return { provider, mode: "real", reason: "kiwa-mode-real" };
+}
+function resolveAllModes(env = process.env) {
+  const providers = ["storybook8", "playwright-ct", "chromatic"];
+  return providers.map((provider) => resolveMode(provider, env));
+}
+function assertMode(provider, expected, env = process.env) {
+  const resolved = resolveMode(provider, env);
+  if (resolved.mode !== expected) {
+    throw new Error(
+      `expected ${provider} in ${expected} mode but resolved ${resolved.mode} (${resolved.reason})`
+    );
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  COMPONENT_AXIS_TO_EVENTS,
   addHandler,
   appendChild,
+  applyOptimisticUpdate,
+  assertAnimation,
+  assertMode,
+  beginRscRender,
   buildButton,
   buildCard,
   buildForm,
   buildInput,
   buildModal,
+  captureErrorBoundary,
+  collectFidelityCoverage,
+  completeRscRender,
+  completeSelectiveHydration,
   componentFixtures,
   createCanvas,
   createChromaticVisualMock,
   createNode,
   createPlaywrightCTMock,
   createStoryRegistry,
+  enableProgressiveEnhancement,
+  enterSuspenseBoundary,
+  failRscRender,
   findByRole,
   findByText,
+  finishElementTransition,
   fireEvent,
   hashMarkup,
+  markFormStatusPending,
+  markSuspensePending,
+  providerEventName,
   query,
-  renderMarkup
+  rejectFormAction,
+  renderMarkup,
+  resolveAllModes,
+  resolveFormAction,
+  resolveMode,
+  startDocumentTransition,
+  startElementTransition,
+  startFormActionSession,
+  startProgressiveHydration,
+  startRscHarness,
+  startStreamingSsr,
+  startViewTransitionSession,
+  streamHtmlChunk
 });
 //# sourceMappingURL=index.cjs.map