@kiwa-test/component 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -531,4 +531,201 @@ declare const buildCard: ComponentRender<CardArgs>;
 /** 全 component の render function を 1 record にまとめる (test 一括登録用)。 */
 declare const componentFixtures: Record<string, ComponentRender<Record<string, unknown>>>;
 
-export { type A11yViolation, type ButtonArgs, type CanvasElement, type CardArgs, type ChromaticConfig, type ChromaticVisualMock, type ComponentLocator, type ComponentProvider, type ComponentRender, type FormArgs, type FormField, type InputArgs, type MockEvent, type MockNode, type ModalArgs, type NodeLocator, type NodeOptions, type PlayContext, type PlaywrightCTMock, type StoryEntry, type StoryMeta, type StoryMountResult, type StoryObj, type StoryParameters, type StoryPlayResult, type StoryRegistry, type VisualBaseline, type VisualDiff, type VisualReviewAction, type VisualReviewEntry, addHandler, appendChild, buildButton, buildCard, buildForm, buildInput, buildModal, componentFixtures, createCanvas, createChromaticVisualMock, createNode, createPlaywrightCTMock, createStoryRegistry, findByRole, findByText, fireEvent, hashMarkup, query, renderMarkup };
+/**
+ * Advanced component semantics — target-neutral axis SSOT.
+ *
+ * The component package spans Storybook 8, Playwright Component Testing, and
+ * Chromatic. These helpers model the observable semantics without importing
+ * any of those runtimes, so the same axis can be replayed against each target.
+ */
+type ComponentTarget = 'storybook8' | 'playwright-ct' | 'chromatic';
+type ComponentAxis = 'rsc-harness' | 'streaming-ssr' | 'view-transitions' | 'form-action-advanced' | 'react-19-actions' | 'islands-architecture';
+type NeutralEventName = 'rsc.render_started' | 'rsc.suspense_boundary' | 'rsc.html_chunk_streamed' | 'rsc.render_completed' | 'ssr.suspense_pending' | 'ssr.error_boundary_captured' | 'ssr.progressive_hydration_started' | 'ssr.selective_hydration_completed' | 'transition.element_started' | 'transition.element_finished' | 'transition.document_started' | 'transition.animation_asserted' | 'form.status_pending' | 'form.optimistic_applied' | 'form.progressive_enhanced' | 'form.action_resolved' | 'action.state_initialized' | 'action.transition_pending' | 'action.optimistic_committed' | 'action.resolved' | 'islands.registered' | 'islands.hydration_started' | 'islands.interactive_ready' | 'islands.static_boundary_asserted';
+interface AxisStep<TState extends string> {
+    neutralEvent: NeutralEventName;
+    providerEvent: string;
+    state: TState;
+    amountCents: number;
+    metadata: Record<string, string | number | boolean>;
+}
+declare function providerEventName(target: ComponentTarget, neutral: NeutralEventName): string;
+
+type RscHarnessState = 'idle' | 'rendering' | 'suspended' | 'streaming' | 'completed' | 'errored';
+interface RscHarnessSession {
+    target: ComponentTarget;
+    componentId: string;
+    state: RscHarnessState;
+    chunks: string[];
+    suspenseFallback: string | null;
+    history: AxisStep<RscHarnessState>[];
+    error: string | null;
+}
+declare function startRscHarness(input: {
+    target: ComponentTarget;
+    componentId: string;
+    suspenseFallback?: string;
+}): RscHarnessSession;
+declare function beginRscRender(session: RscHarnessSession): AxisStep<RscHarnessState>;
+declare function enterSuspenseBoundary(session: RscHarnessSession, fallback?: string): AxisStep<RscHarnessState>;
+declare function streamHtmlChunk(session: RscHarnessSession, chunk: string): AxisStep<RscHarnessState>;
+declare function completeRscRender(session: RscHarnessSession): AxisStep<RscHarnessState>;
+declare function failRscRender(session: RscHarnessSession, error: Error | string): AxisStep<RscHarnessState>;
+
+type StreamingSsrState = 'idle' | 'suspense-pending' | 'error-captured' | 'progressive-hydrating' | 'selective-hydrated';
+interface StreamingSsrSession {
+    target: ComponentTarget;
+    routeId: string;
+    state: StreamingSsrState;
+    pendingBoundaries: Set<string>;
+    hydratedBoundaries: Set<string>;
+    errors: Array<{
+        boundaryId: string;
+        message: string;
+    }>;
+    history: AxisStep<StreamingSsrState>[];
+}
+declare function startStreamingSsr(input: {
+    target: ComponentTarget;
+    routeId: string;
+}): StreamingSsrSession;
+declare function markSuspensePending(session: StreamingSsrSession, boundaryId: string): AxisStep<StreamingSsrState>;
+declare function captureErrorBoundary(session: StreamingSsrSession, input: {
+    boundaryId: string;
+    error: Error | string;
+    recoverable?: boolean;
+}): AxisStep<StreamingSsrState>;
+declare function startProgressiveHydration(session: StreamingSsrSession, boundaryId: string): AxisStep<StreamingSsrState>;
+declare function completeSelectiveHydration(session: StreamingSsrSession, boundaryId: string): AxisStep<StreamingSsrState>;
+
+type ViewTransitionState = 'idle' | 'element-transitioning' | 'document-transitioning' | 'asserted' | 'finished';
+interface ViewTransitionSession {
+    target: ComponentTarget;
+    transitionId: string;
+    state: ViewTransitionState;
+    activeElements: Set<string>;
+    documentTransition: string | null;
+    assertions: string[];
+    history: AxisStep<ViewTransitionState>[];
+}
+declare function startViewTransitionSession(input: {
+    target: ComponentTarget;
+    transitionId: string;
+}): ViewTransitionSession;
+declare function startElementTransition(session: ViewTransitionSession, input: {
+    elementId: string;
+    from: string;
+    to: string;
+}): AxisStep<ViewTransitionState>;
+declare function finishElementTransition(session: ViewTransitionSession, elementId: string): AxisStep<ViewTransitionState>;
+declare function startDocumentTransition(session: ViewTransitionSession, input: {
+    name: string;
+    fromUrl: string;
+    toUrl: string;
+}): AxisStep<ViewTransitionState>;
+declare function assertAnimation(session: ViewTransitionSession, input: {
+    assertionId: string;
+    durationMs: number;
+    easing?: string;
+}): AxisStep<ViewTransitionState>;
+
+type FormActionState = 'idle' | 'pending' | 'optimistic' | 'enhanced' | 'resolved' | 'rejected';
+interface FormActionSession<TForm extends Record<string, unknown> = Record<string, unknown>> {
+    target: ComponentTarget;
+    formId: string;
+    state: FormActionState;
+    form: TForm;
+    optimisticPatches: Array<Partial<TForm>>;
+    enhanced: boolean;
+    history: AxisStep<FormActionState>[];
+    error: string | null;
+}
+declare function startFormActionSession<TForm extends Record<string, unknown>>(input: {
+    target: ComponentTarget;
+    formId: string;
+    initial: TForm;
+}): FormActionSession<TForm>;
+declare function markFormStatusPending<TForm extends Record<string, unknown>>(session: FormActionSession<TForm>, submitter: string): AxisStep<FormActionState>;
+declare function applyOptimisticUpdate$1<TForm extends Record<string, unknown>>(session: FormActionSession<TForm>, patch: Partial<TForm>): AxisStep<FormActionState>;
+declare function enableProgressiveEnhancement<TForm extends Record<string, unknown>>(session: FormActionSession<TForm>, input: {
+    method?: 'post' | 'get';
+    actionUrl: string;
+}): AxisStep<FormActionState>;
+declare function resolveFormAction<TForm extends Record<string, unknown>>(session: FormActionSession<TForm>, result: Partial<TForm>): AxisStep<FormActionState>;
+declare function rejectFormAction<TForm extends Record<string, unknown>>(session: FormActionSession<TForm>, error: Error | string): AxisStep<FormActionState>;
+
+interface FidelityRow {
+    provider: ComponentTarget;
+    axis: ComponentAxis;
+    neutralEvents: NeutralEventName[];
+    providerEvents: string[];
+}
+interface FidelityCoverage {
+    providers: ComponentTarget[];
+    axes: ComponentAxis[];
+    rows: FidelityRow[];
+}
+declare const COMPONENT_AXIS_TO_EVENTS: Record<ComponentAxis, NeutralEventName[]>;
+declare function collectFidelityCoverage(providers?: ComponentTarget[]): FidelityCoverage;
+
+/**
+ * v1.49 react-19-actions axis — useActionState + useOptimistic + useFormStatus
+ * を統合した React 19 Actions API の deterministic state machine。
+ */
+type ReactActionsState = 'idle' | 'transition-pending' | 'optimistic-committed' | 'resolved';
+interface ReactActionsSession {
+    target: ComponentTarget;
+    actionId: string;
+    state: ReactActionsState;
+    pendingCount: number;
+    optimisticValues: string[];
+    resolvedValue: string | null;
+    history: AxisStep<ReactActionsState>[];
+}
+declare function initializeReactActions(input: {
+    target: ComponentTarget;
+    actionId: string;
+}): ReactActionsSession;
+declare function beginActionTransition(session: ReactActionsSession): AxisStep<ReactActionsState>;
+declare function applyOptimisticUpdate(session: ReactActionsSession, optimisticValue: string): AxisStep<ReactActionsState>;
+declare function resolveAction(session: ReactActionsSession, resolvedValue: string): AxisStep<ReactActionsState>;
+
+/**
+ * v1.49 islands-architecture axis — Astro / Deno Fresh / Solid Start の
+ * Islands architecture (partial hydration + selective interactivity) を
+ * target-neutral に扱う state machine。
+ */
+type IslandsState = 'idle' | 'registered' | 'hydrating' | 'interactive' | 'static-verified';
+interface IslandSpec {
+    islandId: string;
+    loadStrategy: 'load' | 'idle' | 'visible' | 'media' | 'only';
+    interactiveBoundary: boolean;
+}
+interface IslandsSession {
+    target: ComponentTarget;
+    routeId: string;
+    islands: IslandSpec[];
+    state: IslandsState;
+    hydratedIslandIds: string[];
+    staticBoundaryIds: string[];
+    history: AxisStep<IslandsState>[];
+}
+declare function bootstrapIslandsRoute(input: {
+    target: ComponentTarget;
+    routeId: string;
+}): IslandsSession;
+declare function registerIsland(session: IslandsSession, island: IslandSpec): AxisStep<IslandsState>;
+declare function beginIslandHydration(session: IslandsSession, islandId: string): AxisStep<IslandsState>;
+declare function markIslandInteractive(session: IslandsSession, islandId: string): AxisStep<IslandsState>;
+declare function assertStaticBoundary(session: IslandsSession, boundaryId: string): AxisStep<IslandsState>;
+
+type KiwaTestMode = 'mock' | 'real';
+interface ResolvedMode {
+    mode: KiwaTestMode;
+    provider: ComponentTarget;
+    reason: 'default-mock' | 'kiwa-mode-real' | 'missing-key' | 'invalid-mode';
+}
+declare function resolveMode(provider: ComponentTarget, env?: Record<string, string | undefined>): ResolvedMode;
+declare function resolveAllModes(env?: Record<string, string | undefined>): ResolvedMode[];
+declare function assertMode(provider: ComponentTarget, expected: KiwaTestMode, env?: Record<string, string | undefined>): void;
+
+export { type A11yViolation, type AxisStep, type ButtonArgs, COMPONENT_AXIS_TO_EVENTS, type CanvasElement, type CardArgs, type ChromaticConfig, type ChromaticVisualMock, type ComponentAxis, type ComponentLocator, type ComponentProvider, type ComponentRender, type ComponentTarget, type FidelityCoverage, type FidelityRow, type FormActionSession, type FormActionState, type FormArgs, type FormField, type InputArgs, type IslandSpec, type IslandsSession, type IslandsState, type KiwaTestMode, type MockEvent, type MockNode, type ModalArgs, type NeutralEventName, type NodeLocator, type NodeOptions, type PlayContext, type PlaywrightCTMock, type ReactActionsSession, type ReactActionsState, type ResolvedMode, type RscHarnessSession, type RscHarnessState, type StoryEntry, type StoryMeta, type StoryMountResult, type StoryObj, type StoryParameters, type StoryPlayResult, type StoryRegistry, type StreamingSsrSession, type StreamingSsrState, type ViewTransitionSession, type ViewTransitionState, type VisualBaseline, type VisualDiff, type VisualReviewAction, type VisualReviewEntry, addHandler, appendChild, applyOptimisticUpdate$1 as applyOptimisticUpdate, applyOptimisticUpdate as applyReactActionOptimistic, assertAnimation, assertMode, assertStaticBoundary, beginActionTransition, beginIslandHydration, beginRscRender, bootstrapIslandsRoute, buildButton, buildCard, buildForm, buildInput, buildModal, captureErrorBoundary, collectFidelityCoverage, completeRscRender, completeSelectiveHydration, componentFixtures, createCanvas, createChromaticVisualMock, createNode, createPlaywrightCTMock, createStoryRegistry, enableProgressiveEnhancement, enterSuspenseBoundary, failRscRender, findByRole, findByText, finishElementTransition, fireEvent, hashMarkup, initializeReactActions, markFormStatusPending, markIslandInteractive, markSuspensePending, providerEventName, query, registerIsland, rejectFormAction, renderMarkup, resolveAction, resolveAllModes, resolveFormAction, resolveMode, startDocumentTransition, startElementTransition, startFormActionSession, startProgressiveHydration, startRscHarness, startStreamingSsr, startViewTransitionSession, streamHtmlChunk };