inkbridge 0.1.0-beta.2 → 0.1.0-beta.21

package/src/design-system/story-diagnostics.ts

@@ -0,0 +1,80 @@
+import type { ComponentDef, ComponentStory, LayoutInfo } from '../components';
+import { RENDER_ENGINE_VERSION } from '../render-engine-version';
+import { hasNodeChildren } from './frame-utils';
+import { normalizeLayoutClasses } from './story-layout';
+
+/**
+ * Per-story inspection metadata written to the Story Layout frame as Figma
+ * plugin data. Surfaced by the `Debug Selection` plugin command — read from
+ * `inkbridge:story-scan` (scanner output snapshot) and `inkbridge:story-render`
+ * (render-time decisions) so you can answer "why did this story render the
+ * way it did?" without reattaching a debugger.
+ *
+ * Pure side-effect: writes string-encoded summaries; tolerates `setPluginData`
+ * unavailability or throws (the diagnostics path must never crash a render).
+ */
+
+function getStoryTreeRootTag(story: ComponentStory): string {
+  const root = story && story.jsxTree;
+  if (!root || root.type !== 'element') return '';
+  return String(root.tagName || '');
+}
+
+function getStoryTreeRootChildCount(story: ComponentStory): number {
+  const root = story && story.jsxTree;
+  if (!root || !Array.isArray(root.children)) return 0;
+  return root.children.length;
+}
+
+function summarizeLayoutClasses(classes: string[] | undefined, maxLength: number): string {
+  const joined = Array.isArray(classes) ? classes.join(' ') : '';
+  if (joined.length <= maxLength) return joined;
+  return joined.slice(0, maxLength);
+}
+
+export function setStoryRenderDiagnostics(
+  layout: LayoutInfo,
+  def: ComponentDef,
+  story: ComponentStory,
+  mode: string,
+  added: number,
+  usedStoryTree: boolean
+): void {
+  if (!layout || typeof layout.setPluginData !== 'function') return;
+  try {
+    const storyName = String(story && story.name ? story.name : '');
+    const defName = String(def && def.name ? def.name : '');
+    const instances = Array.isArray(story && story.instances) ? story.instances.length : 0;
+    const layoutClasses = normalizeLayoutClasses(story && story.layoutClasses);
+    const scanSummary = [
+      'jsx=' + (story && story.jsxTree ? '1' : '0'),
+      'root=' + getStoryTreeRootTag(story),
+      'rootChildren=' + String(getStoryTreeRootChildCount(story)),
+      'instances=' + String(instances),
+      'layout=' + summarizeLayoutClasses(layoutClasses, 120),
+    ].join(';');
+    const renderSummary = [
+      'mode=' + mode,
+      'added=' + String(added),
+      'treeSelected=' + (usedStoryTree ? '1' : '0'),
+      'children=' + (hasNodeChildren(layout) ? String(layout.children.length) : '0'),
+      'engine=' + RENDER_ENGINE_VERSION,
+    ].join(';');
+
+    layout.setPluginData('inkbridge:story-name', storyName);
+    layout.setPluginData('inkbridge:story-def', defName);
+    layout.setPluginData('inkbridge:story-scan', scanSummary);
+    layout.setPluginData('inkbridge:story-render', renderSummary);
+  } catch (_err) {
+    // Ignore diagnostics write failures.
+  }
+}
+
+// Exported for the regression fixture so the pure helpers can be tested in
+// isolation. Not used outside this module's `setStoryRenderDiagnostics` in
+// runtime code; the test boundary is the only consumer.
+export const _internal = {
+  getStoryTreeRootTag,
+  getStoryTreeRootChildCount,
+  summarizeLayoutClasses,
+};

package/src/design-system/story-dimensioning.ts

@@ -0,0 +1,272 @@
+import {
+  extractLeadingContainerMaxWidthFromTree,
+  splitClassName,
+  treeHasFullWidth,
+  type JsxElement,
+  type JsxNode,
+} from '../tailwind';
+import type { ComponentStory, LayoutInfo } from '../components';
+import {
+  extractFixedWidth,
+  extractGridBreakpointWidth,
+  extractGridColumns,
+  extractMaxWidth,
+} from '../layout';
+import {
+  defaultGridWidth,
+  extractGridBreakpointWidthFromTree,
+  extractGridColumnsFromTree,
+} from './story-layout';
+import { resolvePortalAwareStoryTree } from './portal-handling';
+import type { StoryBuilderContext } from './story-builder-context';
+
+// Components whose root is `md:hidden` (or larger-breakpoint-hidden) are
+// mobile-only designs. At the default ~900px width their flex/justify-between
+// layout spreads content across an empty frame. Render such components at a
+// mobile width so the design is legible.
+export const MOBILE_ONLY_DEFAULT_WIDTH = 360;
+
+// Viewport-anchored stories (Sheet drawers, full-page shells, dialogs) use
+// `h-full` / `h-screen` to anchor against a viewport that doesn't exist in
+// Figma auto-layout. Without a synthetic height the container hugs content
+// and descendant `flex-1` siblings collapse to 0. Detect the pattern at the
+// story root and pin a reasonable design height so the vertical grow cascade
+// lights up. Two preset heights cover the common shapes.
+export const VIEWPORT_HEIGHTS = {
+  DRAWER: 700,
+  FULL_PAGE: 900,
+} as const;
+
+/**
+ * Walks the leading single-child spine of a JSX tree and collects classes so a
+ * decorator-wrapped component (common in Storybook stories) still exposes its
+ * intended root behaviour. Stops after 4 levels or at the first multi-child
+ * fan-out — those branches are the body, not the spine.
+ */
+export function collectLeadingSpineClasses(node: JsxNode, out: string[]): void {
+  let current: JsxNode | undefined = node;
+  let depth = 0;
+  while (current && current.type === 'element' && depth < 4) {
+    const el = current as JsxElement;
+    const cls = el.props && el.props.className;
+    if (typeof cls === 'string') {
+      const list = splitClassName(cls);
+      for (let i = 0; i < list.length; i++) out.push(list[i]);
+    }
+    const children = el.children || [];
+    if (children.length !== 1 || !children[0] || children[0].type !== 'element') break;
+    current = children[0];
+    depth++;
+  }
+}
+
+/**
+ * Depth-limited descendant scan for a single Tailwind class. Used by the
+ * viewport-pattern detector to confirm a descendant `flex-1` exists before
+ * pinning a drawer height — without `flex-1` the height pin would just
+ * stretch a fixed-height container with no grow cascade to fill it.
+ */
+export function treeHasDescendantClass(node: JsxNode, cls: string, depth: number = 0): boolean {
+  if (!node || typeof node !== 'object' || depth > 6) return false;
+  if (node.type === 'element') {
+    const el = node as JsxElement;
+    if (el.props && typeof el.props.className === 'string') {
+      const list = splitClassName(el.props.className);
+      if (list.indexOf(cls) !== -1) return true;
+    }
+    const children = Array.isArray(el.children) ? el.children : [];
+    for (let i = 0; i < children.length; i++) {
+      if (treeHasDescendantClass(children[i], cls, depth + 1)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Detects portal-mounted nodes that anchor to viewport height. Required because
+ * Sheet/Drawer content is rendered into a portal subtree — its `h-full` /
+ * `inset-y-0` classes don't show up on the story's own spine.
+ */
+export function treeHasPortalWithFullHeight(node: JsxNode, depth: number = 0): boolean {
+  if (!node || typeof node !== 'object' || depth > 8) return false;
+  if (node.type === 'element') {
+    const el = node as JsxElement;
+    if (el.props && el.props.__fromPortal) {
+      const cls = el.props.className;
+      if (typeof cls === 'string') {
+        const list = splitClassName(cls);
+        if (list.indexOf('h-full') !== -1 || list.indexOf('h-screen') !== -1 || list.indexOf('inset-y-0') !== -1) {
+          if (treeHasDescendantClass(el, 'flex-1')) return true;
+        }
+      }
+    }
+    const children = Array.isArray(el.children) ? el.children : [];
+    for (let i = 0; i < children.length; i++) {
+      if (treeHasPortalWithFullHeight(children[i], depth + 1)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Returns a synthetic viewport height when the story root needs a fixed
+ * primary axis to make `h-full` / `flex-1` children render correctly:
+ *  - `h-screen` / `min-h-screen` on the spine → FULL_PAGE (900)
+ *  - `h-full` + vertical flex + descendant `flex-1` on the spine → DRAWER (700)
+ *  - A portal-mounted node with `h-full` (or `inset-y-0`) + descendant
+ *    `flex-1` (Sheet / Drawer content) → DRAWER (700)
+ * Returns null when the story does not need viewport anchoring.
+ */
+export function detectViewportHeightPattern(story: ComponentStory, layoutClasses: string[]): number | null {
+  // Portal-filter the tree the same way the renderer does: closed stories drop
+  // the portal subtree, so a `Sheet` default (closed) shouldn't be detected as
+  // a drawer — only its `defaultOpen` sibling should.
+  const tree = story && story.jsxTree ? resolvePortalAwareStoryTree(story.jsxTree) : null;
+
+  const spineClasses: string[] = [];
+  if (tree) collectLeadingSpineClasses(tree, spineClasses);
+  for (let i = 0; i < layoutClasses.length; i++) spineClasses.push(layoutClasses[i]);
+
+  for (let i = 0; i < spineClasses.length; i++) {
+    const cls = spineClasses[i];
+    if (cls === 'h-screen' || cls === 'min-h-screen') return VIEWPORT_HEIGHTS.FULL_PAGE;
+  }
+
+  const spineHasHFull = spineClasses.indexOf('h-full') !== -1;
+  const spineHasFlexCol = spineClasses.indexOf('flex-col') !== -1;
+  const treeHasFlexOne = tree ? treeHasDescendantClass(tree, 'flex-1') : false;
+  if (spineHasHFull && spineHasFlexCol && treeHasFlexOne) return VIEWPORT_HEIGHTS.DRAWER;
+
+  if (tree && treeHasPortalWithFullHeight(tree)) return VIEWPORT_HEIGHTS.DRAWER;
+
+  return null;
+}
+
+/**
+ * Returns the mobile width when the story root carries a `{bp}:hidden` class —
+ * the design is intended to render only at mobile width and would look broken
+ * at the default 900px.
+ */
+export function mobileOnlyRootWidth(story: ComponentStory, layoutClasses: string[]): number | null {
+  const rootClasses: string[] = [];
+  if (story && story.jsxTree) collectLeadingSpineClasses(story.jsxTree, rootClasses);
+  for (let i = 0; i < layoutClasses.length; i++) rootClasses.push(layoutClasses[i]);
+  for (let i = 0; i < rootClasses.length; i++) {
+    const cls = rootClasses[i];
+    // Match `sm:hidden`, `md:hidden`, `lg:hidden`, `xl:hidden`, `2xl:hidden`.
+    if (/^(sm|md|lg|xl|2xl):hidden$/.test(cls)) return MOBILE_ONLY_DEFAULT_WIDTH;
+  }
+  return null;
+}
+
+/**
+ * Resolves the desktop width of the Story Layout frame and applies it. Picks
+ * between an explicit fixed-width class, a tree-derived max-width, grid-cols
+ * minimums, mobile-only overrides, and the generic 900px fallback in priority
+ * order. The `viewportWidth` parameter overrides everything (used by
+ * responsive previews to size at a specific breakpoint).
+ */
+export function resolveStoryLayoutWidth(
+  story: ComponentStory,
+  layout: LayoutInfo,
+  layoutClasses: string[],
+  ctx: StoryBuilderContext,
+  viewportWidth?: number
+): number {
+  const fixedWidth = extractFixedWidth(layoutClasses);
+  const maxWidthFromLayout = extractMaxWidth(layoutClasses);
+  const maxWidthFromTree = extractLeadingContainerMaxWidthFromTree(story.jsxTree);
+  const constrainedMaxWidth = (
+    maxWidthFromLayout != null && maxWidthFromTree != null
+      ? Math.min(maxWidthFromLayout, maxWidthFromTree)
+      : (maxWidthFromTree != null ? maxWidthFromTree : maxWidthFromLayout)
+  );
+  const mobileOnlyWidth = mobileOnlyRootWidth(story, layoutClasses);
+  const fallbackWidth = !fixedWidth && story.jsxTree && treeHasFullWidth(story.jsxTree, null, {
+    getComponentDefByName: ctx.getComponentDefByName,
+    normalizeComponentDef: ctx.normalizeComponentDef,
+    hasWidthHintInClasses: ctx.hasWidthHintInClasses,
+    propsContainWidthHint: ctx.propsContainWidthHint,
+  })
+    ? (constrainedMaxWidth || 900)
+    : null;
+  let effectiveWidth = fixedWidth || fallbackWidth;
+  const treeGridCols = story.jsxTree ? extractGridColumnsFromTree(story.jsxTree) : null;
+  const treeGridMinWidth = story.jsxTree ? extractGridBreakpointWidthFromTree(story.jsxTree) : null;
+  const layoutGridCols = extractGridColumns(layoutClasses);
+  const layoutGridMinWidth = extractGridBreakpointWidth(layoutClasses);
+  const gridCols = layoutGridCols || treeGridCols;
+  if (!effectiveWidth && gridCols) {
+    effectiveWidth = defaultGridWidth(gridCols);
+  } else if (effectiveWidth && layoutGridCols) {
+    const minGridWidth = defaultGridWidth(layoutGridCols);
+    if (effectiveWidth < minGridWidth) {
+      effectiveWidth = minGridWidth;
+    }
+  }
+  const gridMinWidth = Math.max(layoutGridMinWidth || 0, treeGridMinWidth || 0);
+  if (gridMinWidth > 0) {
+    if (!effectiveWidth || effectiveWidth < gridMinWidth) {
+      effectiveWidth = gridMinWidth;
+    }
+  }
+  if (!effectiveWidth) {
+    effectiveWidth = mobileOnlyWidth != null ? mobileOnlyWidth : 900;
+  } else if (mobileOnlyWidth != null && !fixedWidth && constrainedMaxWidth == null && !gridCols && !gridMinWidth) {
+    // Mobile-only components with only `w-full` on a decorator would otherwise
+    // inherit the generic 900px fallback via treeHasFullWidth. Clamp them to
+    // the mobile default so the design renders at its intended width.
+    effectiveWidth = mobileOnlyWidth;
+  }
+  if (viewportWidth != null && Number.isFinite(viewportWidth) && viewportWidth > 0) {
+    effectiveWidth = viewportWidth;
+  }
+  if (effectiveWidth) {
+    layout.resize(effectiveWidth, layout.height);
+    if (layout.layoutMode === 'HORIZONTAL') {
+      layout.primaryAxisSizingMode = 'FIXED';
+    } else {
+      layout.counterAxisSizingMode = 'FIXED';
+    }
+    if (!ctx.hasExplicitHeight(layoutClasses)) {
+      // Keep natural content-driven height in responsive previews.
+      // Forcing a transient 1px height can leave complex portal content
+      // (e.g. Dialog panels) visually clipped after layout settles.
+      if (layout.layoutMode === 'HORIZONTAL') {
+        layout.counterAxisSizingMode = 'AUTO';
+      } else {
+        layout.primaryAxisSizingMode = 'AUTO';
+      }
+    }
+  }
+  return effectiveWidth;
+}
+
+/**
+ * Pin the Story Layout's primary-axis height for viewport-anchored stories so
+ * `h-full` / `flex-1` descendants render at their intended sizes. Mirror of
+ * `resolveStoryLayoutWidth` on the primary axis.
+ */
+export function resolveStoryLayoutHeight(
+  story: ComponentStory,
+  layout: LayoutInfo,
+  layoutClasses: string[],
+  ctx: StoryBuilderContext
+): number | null {
+  if (ctx.hasExplicitHeight(layoutClasses)) return null;
+  const height = detectViewportHeightPattern(story, layoutClasses);
+  if (height == null) return null;
+  try {
+    layout.resize(layout.width, height);
+    if (layout.layoutMode === 'VERTICAL') {
+      layout.primaryAxisSizingMode = 'FIXED';
+    } else if (layout.layoutMode === 'HORIZONTAL') {
+      layout.counterAxisSizingMode = 'FIXED';
+    } else if ('primaryAxisSizingMode' in layout) {
+      layout.primaryAxisSizingMode = 'FIXED';
+    }
+  } catch (_err) {
+    // ignore resize errors
+  }
+  return height;
+}