@vscode/component-explorer 0.1.1-18 → 0.1.1-19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vscode/component-explorer",
-  "version": "0.1.1-18",
+  "version": "0.1.1-19",
   "type": "module",
   "repository": {
     "type": "git",

package/dist/index-DnRcKk60.js

@@ -1,61 +0,0 @@
-const u = Symbol.for("@vscode/component-explorer/singleFixture/v1"), f = Symbol.for("@vscode/component-explorer/fixtureGroup/v1"), a = Symbol.for("@vscode/component-explorer/fixtureVariants/v1");
-function d(e) {
-  return {
-    [u]: !0,
-    _options: e
-  };
-}
-function p(e) {
-  return {
-    [f]: !0,
-    _entries: e
-  };
-}
-function l(e) {
-  return {
-    [a]: !0,
-    _variants: e
-  };
-}
-const c = Promise.resolve();
-function x(e) {
-  const o = e();
-  return {
-    ready: c,
-    dispose: () => {
-      typeof o == "function" ? o() : o && typeof o.dispose == "function" && o.dispose();
-    }
-  };
-}
-function y(e, o) {
-  let r, t = !1;
-  function n() {
-    return e.aborted;
-  }
-  const s = (async () => {
-    if (n())
-      throw new DOMException("Render aborted", "AbortError");
-    if (r = await o(), (n() || t) && (i(), n()))
-      throw new DOMException("Render aborted", "AbortError");
-  })();
-  function i() {
-    typeof r == "function" ? r() : r && typeof r.dispose == "function" && r.dispose(), r = void 0;
-  }
-  return {
-    ready: s,
-    dispose: () => {
-      t = !0, i();
-    }
-  };
-}
-export {
-  a,
-  y as b,
-  p as c,
-  d,
-  l as e,
-  f,
-  x as g,
-  u as s
-};
-//# sourceMappingURL=index-DnRcKk60.js.map

package/dist/index-DnRcKk60.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-DnRcKk60.js","sources":["../src/core/fixtureApi.ts"],"sourcesContent":["/**\n * Public Fixture API\n * \n * This module is the public API for defining fixtures.\n * It's designed to be stable across versions - projects can use a different\n * @vscode/component-explorer version than the explorer viewer uses.\n * \n * Use Symbol.for() instead of Symbol() so the same symbol is shared across\n * different versions of this package.\n *\n * @module fixtureApi\n */\n\n// ============================================================================\n// Types for fixture definition (re-exported for convenience)\n// ============================================================================\n\n/**\n * Disposable resource that can be cleaned up.\n */\nexport interface IDisposable {\n  dispose(): void;\n}\n\n/** @deprecated Use IDisposable instead */\nexport type Disposable = IDisposable;\n\n/**\n * Result of a render operation.\n * Supports both sync and async rendering with cancellation.\n * All fields are optional for simple use cases.\n */\nexport interface RenderResult {\n  /**\n   * Resolves when the component is fully rendered and ready.\n   * For sync renders, this can be omitted (treated as immediately ready).\n   * Rejects if the render is aborted via the AbortSignal.\n   */\n  readonly ready?: Promise<void>;\n  \n  /**\n   * Cleanup function. Called when the fixture is unmounted.\n   * Can be omitted if no cleanup is needed.\n   */\n  dispose?(): void;\n}\n\n/**\n * What the render function can return.\n * - undefined: no cleanup needed, immediately ready\n * - RenderResult: object with optional ready/dispose\n * - Promise<...>: async render that resolves to undefined or RenderResult\n */\nexport type RenderReturn = RenderResult | undefined | void | Promise<RenderResult | undefined | void>;\n\n/**\n * Context passed to the render function.\n */\nexport interface RenderContext {\n  /** Property values based on the property schema */\n  readonly props: Record<string, unknown>;\n  /** AbortSignal for cancellation; check signal.aborted or listen to 'abort' event */\n  readonly signal: AbortSignal;\n}\n\n/**\n * Style definition for shadow DOM injection.\n */\nexport type StyleDefinition =\n  | { readonly type: 'css'; readonly content: string }\n  | { readonly type: 'url'; readonly href: string }\n  | { readonly type: 'adopted'; readonly sheet: CSSStyleSheet };\n\n/**\n * Display mode for a component.\n */\nexport type DisplayMode = PageMode | ComponentMode;\n\n/**\n * Page mode - component fills a viewport with device presets.\n */\nexport interface PageMode {\n  readonly type: 'page';\n  readonly viewports: ViewportPreset[];\n}\n\n/**\n * Component mode - renders at natural size.\n */\nexport interface ComponentMode {\n  readonly type: 'component';\n}\n\n/**\n * Viewport preset - either a named preset or custom dimensions.\n */\nexport type ViewportPreset =\n  | ViewportPresetName\n  | { readonly name: string; readonly width: number; readonly height: number };\n\nexport type ViewportPresetName = 'mobile' | 'tablet' | 'desktop';\n\n/**\n * Schema for a component property.\n */\nexport type PropertySchema =\n  | BooleanProperty\n  | StringProperty\n  | NumberProperty\n  | EnumProperty;\n\nexport interface BooleanProperty {\n  readonly type: 'boolean';\n  readonly name: string;\n  readonly defaultValue: boolean;\n  readonly description?: string;\n}\n\nexport interface StringProperty {\n  readonly type: 'string';\n  readonly name: string;\n  readonly defaultValue: string;\n  readonly description?: string;\n  readonly multiline?: boolean;\n}\n\nexport interface NumberProperty {\n  readonly type: 'number';\n  readonly name: string;\n  readonly defaultValue: number;\n  readonly description?: string;\n  readonly min?: number;\n  readonly max?: number;\n  readonly step?: number;\n}\n\nexport interface EnumProperty {\n  readonly type: 'enum';\n  readonly name: string;\n  readonly defaultValue: string;\n  readonly description?: string;\n  readonly options: readonly string[];\n}\n\n// ============================================================================\n// Brand symbols - use Symbol.for() for cross-version compatibility\n// ============================================================================\n\n/** Brand symbol to identify single fixtures */\nexport const singleFixtureBrand = Symbol.for('@vscode/component-explorer/singleFixture/v1');\n\n/** Brand symbol to identify fixture groups */\nexport const fixtureGroupBrand = Symbol.for('@vscode/component-explorer/fixtureGroup/v1');\n\n/** Brand symbol to identify fixture variants */\nexport const fixtureVariantsBrand = Symbol.for('@vscode/component-explorer/fixtureVariants/v1');\n\n// ============================================================================\n// Define fixture options\n// ============================================================================\n\n/**\n * Options for defining a single component fixture.\n */\nexport interface DefineFixtureOptions {\n  /** Optional description for documentation */\n  description?: string;\n\n  /** How to isolate: 'iframe' for full isolation, 'shadow-dom' (default) for lighter isolation */\n  isolation?: 'iframe' | 'shadow-dom';\n\n  /** Display mode: defaults to { type: 'component' } */\n  displayMode?: DisplayMode;\n\n  /** Styles to inject (for shadow-dom isolation) */\n  styles?: StyleDefinition[];\n\n  /** Background pattern for the preview canvas: 'light' (default) or 'dark' for dark transparent pattern */\n  background?: 'light' | 'dark';\n\n  /** Property definitions */\n  properties?: PropertySchema[];\n\n  /**\n   * Render the component into the container.\n   * \n   * @param container - The DOM element to render into\n   * @param context - Render context containing props and abort signal\n   * @returns Optional RenderResult, or a Promise that resolves to one\n   */\n  render: (container: HTMLElement, context: RenderContext) => RenderReturn;\n}\n\n/** @deprecated Use DefineFixtureOptions instead */\nexport type DefineComponentOptions = DefineFixtureOptions;\n\n// ============================================================================\n// Fixture export types (opaque to the user, consumed by fixtureApiConsumer)\n// ============================================================================\n\n/**\n * A single fixture export created by defineFixture().\n */\nexport interface SingleFixtureExport {\n  readonly [singleFixtureBrand]: true;\n  readonly _options: DefineFixtureOptions;\n}\n\n/**\n * Group entry: either a single fixture, a nested group, or variants.\n */\nexport type FixtureGroupEntry = SingleFixtureExport | FixtureGroupExport | FixtureVariantsExport;\n\n/**\n * A fixture group export created by defineFixtureGroup().\n */\nexport interface FixtureGroupExport {\n  readonly [fixtureGroupBrand]: true;\n  readonly _entries: { [key: string]: FixtureGroupEntry };\n}\n\n/**\n * A fixture variants export created by defineFixtureVariants().\n */\nexport interface FixtureVariantsExport {\n  readonly [fixtureVariantsBrand]: true;\n  readonly _variants: { [key: string]: SingleFixtureExport };\n}\n\n/**\n * Fixture export type - a single fixture, a group, or variants.\n */\nexport type FixtureExport = SingleFixtureExport | FixtureGroupExport | FixtureVariantsExport;\n\n/**\n * Input for defineFixtureGroup.\n */\nexport type FixtureGroupInput = { [key: string]: FixtureGroupEntry };\n\n/**\n * Input for defineFixtureVariants (only single fixtures, no nesting).\n */\nexport type FixtureVariantsInput = { [key: string]: SingleFixtureExport };\n\n// ============================================================================\n// Define fixture functions\n// ============================================================================\n\n/**\n * Defines a single fixture.\n * \n * @example\n * ```ts\n * // Simple - no cleanup needed\n * export default defineFixture({\n *   render: (container, { props }) => {\n *     container.innerHTML = `<button>${props.label}</button>`;\n *   },\n * });\n * \n * // With cleanup\n * export default defineFixture({\n *   render: (container, { props }) => {\n *     const root = createRoot(container);\n *     root.render(<Button label={props.label} />);\n *     return { dispose: () => root.unmount() };\n *   },\n * });\n * \n * // Async render\n * export default defineFixture({\n *   render: async (container, { props, signal }) => {\n *     const data = await fetch(props.url, { signal });\n *     container.innerHTML = await data.text();\n *     return { dispose: () => { container.innerHTML = ''; } };\n *   },\n * });\n * ```\n */\nexport function defineFixture(options: DefineFixtureOptions): SingleFixtureExport {\n  return {\n    [singleFixtureBrand]: true,\n    _options: options,\n  };\n}\n\n/**\n * Defines a group of fixtures with support for nesting.\n * \n * @example\n * ```ts\n * export default defineFixtureGroup({\n *   Primary: defineFixture({\n *     render: (container) => { ... },\n *   }),\n *   Variants: defineFixtureGroup({\n *     Small: defineFixture({ ... }),\n *     Large: defineFixture({ ... }),\n *   }),\n * });\n * ```\n */\nexport function defineFixtureGroup(group: FixtureGroupInput): FixtureGroupExport {\n  return {\n    [fixtureGroupBrand]: true,\n    _entries: group,\n  };\n}\n\n/**\n * Defines a group of fixture variants (no nesting allowed).\n * Variants are rendered horizontally by default and have a distinct icon in the tree.\n * \n * @example\n * ```ts\n * export default defineFixtureGroup({\n *   Button: defineFixtureVariants({\n *     Small: defineFixture({ ... }),\n *     Medium: defineFixture({ ... }),\n *     Large: defineFixture({ ... }),\n *   }),\n * });\n * ```\n */\nexport function defineFixtureVariants(variants: FixtureVariantsInput): FixtureVariantsExport {\n  return {\n    [fixtureVariantsBrand]: true,\n    _variants: variants,\n  };\n}\n\n// ============================================================================\n// Render helpers\n// ============================================================================\n\n/** Already-resolved promise, reused for efficiency */\nconst resolvedPromise = Promise.resolve();\n\n/**\n * Helper for synchronous renders.\n * Executes the render function immediately and wraps the cleanup in a RenderResult.\n * \n * @param doRender - Function that renders synchronously and returns a cleanup function\n * @returns A RenderResult with an already-resolved ready promise\n * \n * @example\n * ```ts\n * render: (container, { props }) => syncRender(() => {\n *   const el = document.createElement('button');\n *   el.textContent = props.label;\n *   container.appendChild(el);\n *   return () => el.remove();\n * })\n * ```\n */\nexport function syncRender(doRender: () => (() => void) | IDisposable | void): RenderResult {\n  const cleanup = doRender();\n  return {\n    ready: resolvedPromise,\n    dispose: () => {\n      if (typeof cleanup === 'function') {\n        cleanup();\n      } else if (cleanup && typeof cleanup.dispose === 'function') {\n        cleanup.dispose();\n      }\n    },\n  };\n}\n\n/**\n * Helper for asynchronous renders with cancellation support.\n * \n * @param signal - AbortSignal for cancellation\n * @param doRender - Async function that renders and returns a cleanup function.\n *                   Should check signal.aborted periodically for long operations.\n * @returns A RenderResult whose ready promise rejects with AbortError if cancelled\n * \n * @example\n * ```ts\n * render: (container, { props, signal }) => asyncRender(signal, async () => {\n *   const data = await fetchData(props.url, { signal });\n *   if (signal.aborted) return;\n *   container.innerHTML = data;\n *   return () => { container.innerHTML = ''; };\n * })\n * ```\n */\nexport function asyncRender(\n  signal: AbortSignal,\n  doRender: () => Promise<(() => void) | IDisposable | void>\n): RenderResult {\n  let cleanup: (() => void) | IDisposable | void;\n  let disposed = false;\n\n  function isAborted(): boolean {\n    return signal.aborted;\n  }\n\n  const ready = (async () => {\n    if (isAborted()) {\n      throw new DOMException('Render aborted', 'AbortError');\n    }\n    cleanup = await doRender();\n    if (isAborted() || disposed) {\n      // Cleanup immediately if aborted/disposed during render\n      doCleanup();\n      if (isAborted()) {\n        throw new DOMException('Render aborted', 'AbortError');\n      }\n    }\n  })();\n\n  function doCleanup(): void {\n    if (typeof cleanup === 'function') {\n      cleanup();\n    } else if (cleanup && typeof cleanup.dispose === 'function') {\n      cleanup.dispose();\n    }\n    cleanup = undefined;\n  }\n\n  return {\n    ready,\n    dispose: () => {\n      disposed = true;\n      doCleanup();\n    },\n  };\n}\n"],"names":["singleFixtureBrand","fixtureGroupBrand","fixtureVariantsBrand","defineFixture","options","defineFixtureGroup","group","defineFixtureVariants","variants","resolvedPromise","syncRender","doRender","cleanup","asyncRender","signal","disposed","isAborted","ready","doCleanup"],"mappings":"AAqJO,MAAMA,IAAqB,OAAO,IAAI,6CAA6C,GAG7EC,IAAoB,OAAO,IAAI,4CAA4C,GAG3EC,IAAuB,OAAO,IAAI,+CAA+C;AA4HvF,SAASC,EAAcC,GAAoD;AAChF,SAAO;AAAA,IACL,CAACJ,CAAkB,GAAG;AAAA,IACtB,UAAUI;AAAA,EAAA;AAEd;AAkBO,SAASC,EAAmBC,GAA8C;AAC/E,SAAO;AAAA,IACL,CAACL,CAAiB,GAAG;AAAA,IACrB,UAAUK;AAAA,EAAA;AAEd;AAiBO,SAASC,EAAsBC,GAAuD;AAC3F,SAAO;AAAA,IACL,CAACN,CAAoB,GAAG;AAAA,IACxB,WAAWM;AAAA,EAAA;AAEf;AAOA,MAAMC,IAAkB,QAAQ,QAAA;AAmBzB,SAASC,EAAWC,GAAiE;AAC1F,QAAMC,IAAUD,EAAA;AAChB,SAAO;AAAA,IACL,OAAOF;AAAA,IACP,SAAS,MAAM;AACb,MAAI,OAAOG,KAAY,aACrBA,EAAA,IACSA,KAAW,OAAOA,EAAQ,WAAY,cAC/CA,EAAQ,QAAA;AAAA,IAEZ;AAAA,EAAA;AAEJ;AAoBO,SAASC,EACdC,GACAH,GACc;AACd,MAAIC,GACAG,IAAW;AAEf,WAASC,IAAqB;AAC5B,WAAOF,EAAO;AAAA,EAChB;AAEA,QAAMG,KAAS,YAAY;AACzB,QAAID;AACF,YAAM,IAAI,aAAa,kBAAkB,YAAY;AAGvD,QADAJ,IAAU,MAAMD,EAAA,IACZK,EAAA,KAAeD,OAEjBG,EAAA,GACIF;AACF,YAAM,IAAI,aAAa,kBAAkB,YAAY;AAAA,EAG3D,GAAA;AAEA,WAASE,IAAkB;AACzB,IAAI,OAAON,KAAY,aACrBA,EAAA,IACSA,KAAW,OAAOA,EAAQ,WAAY,cAC/CA,EAAQ,QAAA,GAEVA,IAAU;AAAA,EACZ;AAEA,SAAO;AAAA,IACL,OAAAK;AAAA,IACA,SAAS,MAAM;AACb,MAAAF,IAAW,IACXG,EAAA;AAAA,IACF;AAAA,EAAA;AAEJ;"}