@kaptures/storybook 0.0.6 → 0.1.0

package/README.md

@@ -3,7 +3,7 @@
 Typed Storybook 10 lifecycle adapter for Kapture visual review.
 
 ```bash
-bun add --dev --exact @kaptures/storybook@0.0.5
+bun add --dev --exact @kaptures/storybook@0.0.6
 ```
 
 Register the adapter in `.storybook/preview.ts` with Storybook's CSF factory API.
@@ -16,7 +16,7 @@ export default definePreview({
   addons: [kapture()],
   parameters: {
     kapture: {
-      requiredFonts: [{ text: "Visual review" }],
+      waitForFonts: true,
     },
   },
 });

package/dist/index.d.ts

@@ -10,9 +10,9 @@ interface KaptureWaitForOptions {
   state?: KaptureWaitForState;
   timeoutMs?: number;
 }
-interface KaptureRequiredFont {
-  family?: string;
-  text: string;
+interface KaptureFontAssertion {
+  family: string;
+  glyphs: string;
   style?: string;
   weight?: string | number;
 }
@@ -31,8 +31,10 @@ interface KaptureStoryParameters {
   mask?: readonly string[];
   /** Keep matching nodes visible, but ignore their interior pixels during diff. */
   ignoreSelectors?: readonly string[];
-  /** Fail capture when a required family or glyph set is unavailable. */
-  requiredFonts?: ReadonlyArray<string | KaptureRequiredFont>;
+  /** Wait for the document font set to finish loading before capture. */
+  waitForFonts?: boolean;
+  /** Fail capture when a specific font family or sampled glyph set is unavailable. */
+  fontAssertions?: ReadonlyArray<KaptureFontAssertion>;
   diff?: {
     pixel?: number;
     ratio?: number;
@@ -50,4 +52,4 @@ declare function createKapturePreviewAddon(): import("storybook/internal/csf").P
 //#region src/index.d.ts
 declare const kapture: typeof createKapturePreviewAddon;
 //#endregion
-export { type KaptureAddonTypes, type KaptureAnimation, type KaptureRequiredFont, type KaptureStoryParameters, type KaptureViewport, type KaptureWaitForOptions, type KaptureWaitForState, createKapturePreviewAddon as default, kapture };
+export { type KaptureAddonTypes, type KaptureAnimation, type KaptureFontAssertion, type KaptureStoryParameters, type KaptureViewport, type KaptureWaitForOptions, type KaptureWaitForState, createKapturePreviewAddon as default, kapture };

package/dist/index.js

@@ -1 +1 @@
-import{PLAY_FUNCTION_THREW_EXCEPTION as e,STORY_FINISHED as t,STORY_RENDER_PHASE_CHANGED as n,UNHANDLED_ERRORS_WHILE_PLAYING as r}from"storybook/internal/core-events";import{definePreviewAddon as i}from"storybook/internal/csf";import{addons as a}from"storybook/preview-api";function o(e){let t=m(e,`parameters`);return w({disabled:v(t.disabled,`disabled`),viewports:s(t.viewports),cropToViewport:v(t.cropToViewport,`cropToViewport`),delayMs:x(t.delayMs,`delayMs`),waitFor:l(t.waitFor),animation:u(t.animation),mask:p(t.mask,`mask`),ignoreSelectors:p(t.ignoreSelectors,`ignoreSelectors`),requiredFonts:t.requiredFonts===void 0?void 0:h(t.requiredFonts,`requiredFonts`).map((e,t)=>d(e,`requiredFonts[${t}]`)),diff:f(t.diff)})}function s(e){if(e===void 0)return;let t=h(e,`viewports`);if(t.length===0)throw Error(`Kapture viewports must contain at least one viewport; use disabled: true to skip`);return t.map((e,t)=>c(e,`viewports[${t}]`))}function c(e,t){let n=m(e,t);return{name:g(n.name,`${t}.name`),width:S(n.width,`${t}.width`),height:S(n.height,`${t}.height`)}}function l(e){if(e===void 0)return;if(typeof e==`string`)return g(e,`waitFor`);let t=m(e,`waitFor`),n=t.state;if(n!==void 0&&n!==`attached`&&n!==`visible`&&n!==`hidden`&&n!==`detached`)throw Error(`Invalid Kapture waitFor state: ${String(n)}`);return w({selector:g(t.selector,`waitFor.selector`),state:n,timeoutMs:x(t.timeoutMs,`waitFor.timeoutMs`)})}function u(e){if(e!==void 0)return e===`disabled`||e===`start`||e===`end`?e:{atMs:b(m(e,`animation`).atMs,`animation.atMs`)}}function d(e,t){if(typeof e==`string`)return g(e,t);let n=m(e,t),r=n.weight;if(r!==void 0&&typeof r!=`string`&&typeof r!=`number`)throw Error(`${t}.weight must be a string or number`);return w({family:_(n.family,`${t}.family`),text:g(n.text,`${t}.text`),style:_(n.style,`${t}.style`),weight:r})}function f(e){if(e===void 0)return;let t=m(e,`diff`);return w({pixel:C(t.pixel,`diff.pixel`),ratio:C(t.ratio,`diff.ratio`)})}function p(e,t){if(e!==void 0)return h(e,t).map((e,n)=>g(e,`${t}[${n}]`))}function m(e,t){if(typeof e!=`object`||!e||Array.isArray(e))throw Error(`Kapture ${t} must be an object`);return e}function h(e,t){if(!Array.isArray(e))throw Error(`Kapture ${t} must be an array`);return e}function g(e,t){if(typeof e!=`string`||!e.trim())throw Error(`Kapture ${t} must be a non-empty string`);return e}function _(e,t){return e===void 0?void 0:g(e,t)}function v(e,t){if(e!==void 0){if(typeof e!=`boolean`)throw Error(`Kapture ${t} must be a boolean`);return e}}function y(e,t){if(e!==void 0){if(typeof e!=`number`||!Number.isFinite(e))throw Error(`Kapture ${t} must be a finite number`);return e}}function b(e,t){let n=y(e,t);if(n===void 0||n<0)throw Error(`Kapture ${t} must be a non-negative number`);return n}function x(e,t){return e===void 0?void 0:b(e,t)}function S(e,t){let n=y(e,t);if(n===void 0||n<=0)throw Error(`Kapture ${t} must be positive`);return n}function C(e,t){if(e===void 0)return;let n=b(e,t);if(n>1)throw Error(`Kapture ${t} must be between 0 and 1`);return n}function w(e){return Object.fromEntries(Object.entries(e).filter(([,e])=>e!==void 0))}var T=`0.0.6`;const E={set:e=>setTimeout(e,0),clear:e=>clearTimeout(e)};function D(e,t,n=E){let r=0,i,a,o=new Map,s=[],c=()=>{a!==void 0&&n.clear(a),a=void 0},l=()=>{if(!i)return;let{configurationError:n,storybookError:r,...a}=i;t({protocolVersion:1,adapterVersion:e,state:`rendering`,...a})},u=(e,t)=>{let n={storyId:e,generation:++r,renderId:t};return o.set(n.generation,n),i=n,n},d=(r,o)=>{c(),a=n.set(()=>{if(a=void 0,!(!i||i.generation!==r.generation)&&!(r.configurationError||r.storybookError)){if(o===`error`){t({protocolVersion:1,adapterVersion:e,state:`error`,storyId:r.storyId,generation:r.generation,renderId:r.renderId,error:{kind:`storybook`,message:`Storybook failed while rendering, playing, or finishing this story.`}});return}if(r.renderId===void 0||r.parameters===void 0){t({protocolVersion:1,adapterVersion:e,state:`error`,storyId:r.storyId,generation:r.generation,renderId:r.renderId,error:{kind:`configuration`,message:`Kapture did not receive resolved story parameters before Storybook finished.`}});return}t({protocolVersion:1,adapterVersion:e,state:`ready`,storyId:r.storyId,generation:r.generation,renderId:r.renderId,parameters:r.parameters})}})};return{boot(){c(),r=0,i=void 0,o.clear(),s.length=0,t({protocolVersion:1,adapterVersion:e,state:`booting`})},startStory(e,t){return c(),(!i||i.storyId!==e||i.parameters!==void 0||i.configurationError!==void 0||i.storybookError!==void 0)&&u(e),i.parameters=t,l(),i.generation},completeStory(e,t){let n=o.get(t);!n||n.storyId!==e||n.configurationError||n.storybookError||s.includes(t)||s.push(t)},failConfiguration(n,r){c(),(!i||i.storyId!==n||i.parameters!==void 0)&&u(n),i.configurationError=r.message,t({protocolVersion:1,adapterVersion:e,state:`error`,storyId:n,generation:i.generation,renderId:i.renderId,error:{kind:`configuration`,message:r.message}})},failStorybook(n){c(),i&&(i.storybookError=n.message,t({protocolVersion:1,adapterVersion:e,state:`error`,storyId:i.storyId,generation:i.generation,renderId:i.renderId,error:{kind:`storybook`,message:n.message}}))},handlePhase(e){if(e.newPhase===`loading`){c(),u(e.storyId,e.renderId),l();return}i?.storyId===e.storyId&&(i.renderId=e.renderId)},handleFinished(e){let t=s.findIndex(t=>o.get(t)?.storyId===e.storyId),n=t<0?void 0:s.splice(t,1)[0],r=n===void 0?i:o.get(n);!r||r.storyId!==e.storyId||r.configurationError||r.storybookError||(e.status!==`success`||n!==void 0)&&d(r,e.status)},dispose(){c(),i=void 0,o.clear(),s.length=0}}}function O(e,t){try{let e=M(t,`Storybook parameters`),n=e.kapture===void 0?{}:M(e.kapture,`parameters.kapture`),r=n.viewports?.map((t,n)=>typeof t==`string`?k(t,e.viewport):A(t,n));return o({disabled:n.disabled,viewports:r,cropToViewport:n.cropToViewport,delayMs:n.delayMs,waitFor:n.waitFor,animation:n.animation,mask:n.mask,ignoreSelectors:n.ignoreSelectors,requiredFonts:n.requiredFonts,diff:n.diff})}catch(t){let n=t instanceof Error?t.message:String(t);throw Error(`Kapture story ${e}: ${n}`,{cause:t})}}function k(e,t){if(!e.trim())throw Error(`viewports entries must not be empty`);let n=M(M(M(t,`parameters.viewport`).options,`parameters.viewport.options`)[e],`viewport option ${e}`);return{name:e,width:j(n.styles?.width,`${e}.styles.width`),height:j(n.styles?.height,`${e}.styles.height`)}}function A(e,t){if(typeof e!=`object`||!e)throw Error(`viewports[${t}] must be a viewport name or object`);return{name:e.name,width:e.width,height:e.height}}function j(e,t){if(typeof e!=`string`)throw Error(`${t} must be an exact pixel dimension`);let n=/^(\d+)px$/.exec(e.trim());if(!n?.[1])throw Error(`${t} must use an exact pixel dimension such as 360px`);let r=Number(n[1]);if(r<=0)throw Error(`${t} must be positive`);return r}function M(e,t){if(typeof e!=`object`||!e||Array.isArray(e))throw Error(`${t} must be an object`);return e}function N(e){globalThis.__KAPTURE_STORYBOOK__=e}function P(){let o=D(T,N),s=new WeakMap;return i({beforeAll(){o.boot();let i=a.getChannel(),s=e=>o.handlePhase(e),c=e=>o.handleFinished(e),l=e=>o.failStorybook(F(e));return i.on(n,s),i.on(t,c),i.on(e,l),i.on(r,l),()=>{i.off(n,s),i.off(t,c),i.off(e,l),i.off(r,l),o.dispose()}},beforeEach(e){try{let t=o.startStory(e.id,O(e.id,e.parameters));s.set(e,t)}catch(t){let n=t instanceof Error?t:Error(String(t));throw o.failConfiguration(e.id,n),n}},afterEach(e){let t=s.get(e);t!==void 0&&o.completeStory(e.id,t)}})}function F(e){let t=Array.isArray(e)?e[0]:e;if(typeof t==`object`&&t&&`message`in t){let e=t.message;if(typeof e==`string`&&e.trim())return Error(`Storybook play function failed: ${e}`)}return Error(`Storybook play function failed.`)}const I=P;var L=P;export{L as default,I as kapture};
+import{PLAY_FUNCTION_THREW_EXCEPTION as e,STORY_FINISHED as t,STORY_RENDER_PHASE_CHANGED as n,UNHANDLED_ERRORS_WHILE_PLAYING as r}from"storybook/internal/core-events";import{definePreviewAddon as i}from"storybook/internal/csf";import{addons as a}from"storybook/preview-api";function o(e){let t=m(e,`parameters`);return w({disabled:v(t.disabled,`disabled`),viewports:s(t.viewports),cropToViewport:v(t.cropToViewport,`cropToViewport`),delayMs:x(t.delayMs,`delayMs`),waitFor:l(t.waitFor),animation:u(t.animation),mask:p(t.mask,`mask`),ignoreSelectors:p(t.ignoreSelectors,`ignoreSelectors`),waitForFonts:v(t.waitForFonts,`waitForFonts`),fontAssertions:t.fontAssertions===void 0?void 0:h(t.fontAssertions,`fontAssertions`).map((e,t)=>d(e,`fontAssertions[${t}]`)),diff:f(t.diff)})}function s(e){if(e===void 0)return;let t=h(e,`viewports`);if(t.length===0)throw Error(`Kapture viewports must contain at least one viewport; use disabled: true to skip`);return t.map((e,t)=>c(e,`viewports[${t}]`))}function c(e,t){let n=m(e,t);return{name:g(n.name,`${t}.name`),width:S(n.width,`${t}.width`),height:S(n.height,`${t}.height`)}}function l(e){if(e===void 0)return;if(typeof e==`string`)return g(e,`waitFor`);let t=m(e,`waitFor`),n=t.state;if(n!==void 0&&n!==`attached`&&n!==`visible`&&n!==`hidden`&&n!==`detached`)throw Error(`Invalid Kapture waitFor state: ${String(n)}`);return w({selector:g(t.selector,`waitFor.selector`),state:n,timeoutMs:x(t.timeoutMs,`waitFor.timeoutMs`)})}function u(e){if(e!==void 0)return e===`disabled`||e===`start`||e===`end`?e:{atMs:b(m(e,`animation`).atMs,`animation.atMs`)}}function d(e,t){let n=m(e,t),r=n.weight;if(r!==void 0&&typeof r!=`string`&&typeof r!=`number`)throw Error(`${t}.weight must be a string or number`);return w({family:g(n.family,`${t}.family`),glyphs:g(n.glyphs,`${t}.glyphs`),style:_(n.style,`${t}.style`),weight:r})}function f(e){if(e===void 0)return;let t=m(e,`diff`);return w({pixel:C(t.pixel,`diff.pixel`),ratio:C(t.ratio,`diff.ratio`)})}function p(e,t){if(e!==void 0)return h(e,t).map((e,n)=>g(e,`${t}[${n}]`))}function m(e,t){if(typeof e!=`object`||!e||Array.isArray(e))throw Error(`Kapture ${t} must be an object`);return e}function h(e,t){if(!Array.isArray(e))throw Error(`Kapture ${t} must be an array`);return e}function g(e,t){if(typeof e!=`string`||!e.trim())throw Error(`Kapture ${t} must be a non-empty string`);return e}function _(e,t){return e===void 0?void 0:g(e,t)}function v(e,t){if(e!==void 0){if(typeof e!=`boolean`)throw Error(`Kapture ${t} must be a boolean`);return e}}function y(e,t){if(e!==void 0){if(typeof e!=`number`||!Number.isFinite(e))throw Error(`Kapture ${t} must be a finite number`);return e}}function b(e,t){let n=y(e,t);if(n===void 0||n<0)throw Error(`Kapture ${t} must be a non-negative number`);return n}function x(e,t){return e===void 0?void 0:b(e,t)}function S(e,t){let n=y(e,t);if(n===void 0||n<=0)throw Error(`Kapture ${t} must be positive`);return n}function C(e,t){if(e===void 0)return;let n=b(e,t);if(n>1)throw Error(`Kapture ${t} must be between 0 and 1`);return n}function w(e){return Object.fromEntries(Object.entries(e).filter(([,e])=>e!==void 0))}var T=`0.1.0`;const E={set:e=>setTimeout(e,0),clear:e=>clearTimeout(e)};function D(e,t,n=E){let r=0,i,a,o=new Map,s=[],c=()=>{a!==void 0&&n.clear(a),a=void 0},l=()=>{if(!i)return;let{configurationError:n,storybookError:r,...a}=i;t({protocolVersion:2,adapterVersion:e,state:`rendering`,...a})},u=(e,t)=>{let n={storyId:e,generation:++r,renderId:t};return o.set(n.generation,n),i=n,n},d=(r,o)=>{c(),a=n.set(()=>{if(a=void 0,!(!i||i.generation!==r.generation)&&!(r.configurationError||r.storybookError)){if(o===`error`){t({protocolVersion:2,adapterVersion:e,state:`error`,storyId:r.storyId,generation:r.generation,renderId:r.renderId,error:{kind:`storybook`,message:`Storybook failed while rendering, playing, or finishing this story.`}});return}if(r.renderId===void 0||r.parameters===void 0){t({protocolVersion:2,adapterVersion:e,state:`error`,storyId:r.storyId,generation:r.generation,renderId:r.renderId,error:{kind:`configuration`,message:`Kapture did not receive resolved story parameters before Storybook finished.`}});return}t({protocolVersion:2,adapterVersion:e,state:`ready`,storyId:r.storyId,generation:r.generation,renderId:r.renderId,parameters:r.parameters})}})};return{boot(){c(),r=0,i=void 0,o.clear(),s.length=0,t({protocolVersion:2,adapterVersion:e,state:`booting`})},startStory(e,t){return c(),(!i||i.storyId!==e||i.parameters!==void 0||i.configurationError!==void 0||i.storybookError!==void 0)&&u(e),i.parameters=t,l(),i.generation},completeStory(e,t){let n=o.get(t);!n||n.storyId!==e||n.configurationError||n.storybookError||s.includes(t)||s.push(t)},failConfiguration(n,r){c(),(!i||i.storyId!==n||i.parameters!==void 0)&&u(n),i.configurationError=r.message,t({protocolVersion:2,adapterVersion:e,state:`error`,storyId:n,generation:i.generation,renderId:i.renderId,error:{kind:`configuration`,message:r.message}})},failStorybook(n){c(),i&&(i.storybookError=n.message,t({protocolVersion:2,adapterVersion:e,state:`error`,storyId:i.storyId,generation:i.generation,renderId:i.renderId,error:{kind:`storybook`,message:n.message}}))},handlePhase(e){if(e.newPhase===`loading`){c(),u(e.storyId,e.renderId),l();return}i?.storyId===e.storyId&&(i.renderId=e.renderId)},handleFinished(e){let t=s.findIndex(t=>o.get(t)?.storyId===e.storyId),n=t<0?void 0:s.splice(t,1)[0],r=n===void 0?i:o.get(n);!r||r.storyId!==e.storyId||r.configurationError||r.storybookError||(e.status!==`success`||n!==void 0)&&d(r,e.status)},dispose(){c(),i=void 0,o.clear(),s.length=0}}}function O(e,t){try{let e=M(t,`Storybook parameters`),n=e.kapture===void 0?{}:M(e.kapture,`parameters.kapture`),r=n.viewports?.map((t,n)=>typeof t==`string`?k(t,e.viewport):A(t,n));return o({disabled:n.disabled,viewports:r,cropToViewport:n.cropToViewport,delayMs:n.delayMs,waitFor:n.waitFor,animation:n.animation,mask:n.mask,ignoreSelectors:n.ignoreSelectors,waitForFonts:n.waitForFonts,fontAssertions:n.fontAssertions,diff:n.diff})}catch(t){let n=t instanceof Error?t.message:String(t);throw Error(`Kapture story ${e}: ${n}`,{cause:t})}}function k(e,t){if(!e.trim())throw Error(`viewports entries must not be empty`);let n=M(M(M(t,`parameters.viewport`).options,`parameters.viewport.options`)[e],`viewport option ${e}`);return{name:e,width:j(n.styles?.width,`${e}.styles.width`),height:j(n.styles?.height,`${e}.styles.height`)}}function A(e,t){if(typeof e!=`object`||!e)throw Error(`viewports[${t}] must be a viewport name or object`);return{name:e.name,width:e.width,height:e.height}}function j(e,t){if(typeof e!=`string`)throw Error(`${t} must be an exact pixel dimension`);let n=/^(\d+)px$/.exec(e.trim());if(!n?.[1])throw Error(`${t} must use an exact pixel dimension such as 360px`);let r=Number(n[1]);if(r<=0)throw Error(`${t} must be positive`);return r}function M(e,t){if(typeof e!=`object`||!e||Array.isArray(e))throw Error(`${t} must be an object`);return e}function N(e){globalThis.__KAPTURE_STORYBOOK__=e}function P(){let o=D(T,N),s=new WeakMap;return i({beforeAll(){o.boot();let i=a.getChannel(),s=e=>o.handlePhase(e),c=e=>o.handleFinished(e),l=e=>o.failStorybook(F(e));return i.on(n,s),i.on(t,c),i.on(e,l),i.on(r,l),()=>{i.off(n,s),i.off(t,c),i.off(e,l),i.off(r,l),o.dispose()}},beforeEach(e){try{let t=o.startStory(e.id,O(e.id,e.parameters));s.set(e,t)}catch(t){let n=t instanceof Error?t:Error(String(t));throw o.failConfiguration(e.id,n),n}},afterEach(e){let t=s.get(e);t!==void 0&&o.completeStory(e.id,t)}})}function F(e){let t=Array.isArray(e)?e[0]:e;if(typeof t==`object`&&t&&`message`in t){let e=t.message;if(typeof e==`string`&&e.trim())return Error(`Storybook play function failed: ${e}`)}return Error(`Storybook play function failed.`)}const I=P;var L=P;export{L as default,I as kapture};

package/dist/preset.d.ts

@@ -1,4 +1,4 @@
-//#region src/dependency-manifest-v1.d.ts
+//#region src/dependency-manifest.d.ts
 declare const KAPTURE_DEPENDENCY_MANIFEST_FILE = "kapture-dependencies.json";
 interface KaptureDependencyManifestV1 {
   kind: "kapture-storybook-dependencies";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaptures/storybook",
-  "version": "0.0.6",
+  "version": "0.1.0",
   "description": "Typed Storybook lifecycle adapter for Kapture visual review",
   "type": "module",
   "license": "MIT",