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

package/src/tailwind/jsx-utils.ts

@@ -0,0 +1,319 @@
+import { type JsxNode, type JsxElement, splitClassName } from './node-ir';
+import { type ComponentDef } from './class-utils';
+import { extractMaxWidth } from '../layout';
+import { getClassesForBreakpoint, hasSignificantResponsiveChanges } from './responsive-analyzer';
+import { isFrameworkAdapterDroppedTag } from '../framework-adapters';
+
+/**
+ * Recursively collect every Tailwind class string from a JSX tree.
+ *
+ * Elements that the framework adapter will unconditionally drop at render
+ * time (e.g. `ScrollAreaPrimitive.Scrollbar` and friends) are skipped —
+ * including their subtree. Otherwise classes that never reach Figma
+ * (Scrollbar's `sm:bg-black/60`) would falsely trip pre-render scans like
+ * `treeHasResponsiveClasses`, producing duplicate-content Responsive
+ * previews on stories that are static at every breakpoint post-adapter.
+ */
+export function collectTreeClasses(node: JsxNode | undefined, output: string[]): void {
+  if (!node) return;
+  if (node.type === 'element') {
+    const el = node as JsxElement;
+    if (isFrameworkAdapterDroppedTag(el.tagName)) return;
+    const className = el.props && el.props.className ? String(el.props.className) : '';
+    if (className) {
+      const list = splitClassName(className);
+      for (let i = 0; i < list.length; i++) output.push(list[i]);
+    }
+    const children = el.children || [];
+    for (let i = 0; i < children.length; i++) {
+      collectTreeClasses(children[i], output);
+    }
+  }
+}
+
+/**
+ * Returns true when the tree contains classes that produce visible layout
+ * differences at responsive breakpoints.
+ */
+export function treeHasResponsiveClasses(node: JsxNode | undefined): boolean {
+  const list: string[] = [];
+  collectTreeClasses(node, list);
+  return list.length > 0 && hasSignificantResponsiveChanges(list);
+}
+
+/**
+ * Remap every class in a className string to its breakpoint-specific override.
+ * Ensures that bare `grid` classes are paired with `grid-cols-1` if no column
+ * count was specified for this breakpoint.
+ */
+export function mapClassNameForBreakpoint(value: string | undefined, breakpoint: string): string | undefined {
+  if (!value) return value;
+  const list = splitClassName(value);
+  if (list.length === 0) return value;
+  const mapped = getClassesForBreakpoint(list, breakpoint);
+  let hasGrid = false;
+  let hasGridCols = false;
+  for (let i = 0; i < mapped.length; i++) {
+    const cls = mapped[i];
+    if (cls === 'grid' || cls === 'inline-grid') hasGrid = true;
+    if (cls.startsWith('grid-cols-')) hasGridCols = true;
+  }
+  // Only inject grid-cols-1 when the original class list had responsive grid-cols
+  // variants (e.g. sm:grid-cols-3) that were stripped for this breakpoint.
+  // Without this guard, vertical-stack `grid` containers (like DialogContent) get
+  // grid-cols-1 injected, which flips their layoutMode to HORIZONTAL and causes
+  // resize code to lock the frame height at a wrong value, clipping content.
+  if (hasGrid && !hasGridCols) {
+    const hadResponsiveGridCols = list.some(cls => /^(?:sm|md|lg|xl|2xl):grid-cols-/.test(cls));
+    if (hadResponsiveGridCols) mapped.push('grid-cols-1');
+  }
+  return mapped.join(' ');
+}
+
+/**
+ * Deep-clone a JSX node, remapping all className values for a given breakpoint.
+ */
+export function cloneJsxNodeForBreakpoint(node: JsxNode, breakpoint: string): JsxNode {
+  if (!node || node.type !== 'element') return node;
+  const el = node as JsxElement;
+  const nextProps = el.props ? Object.assign({}, el.props) : {};
+  if (nextProps.className) {
+    nextProps.className = mapClassNameForBreakpoint(String(nextProps.className), breakpoint) || '';
+  }
+  const nextChildren: JsxNode[] = [];
+  const children = el.children || [];
+  for (let i = 0; i < children.length; i++) {
+    nextChildren.push(cloneJsxNodeForBreakpoint(children[i], breakpoint));
+  }
+  return Object.assign({}, el, { props: nextProps, children: nextChildren });
+}
+
+/**
+ * Walk the JSX tree and return the first explicit `grid-cols-N` value found,
+ * or 1 if a grid layout is declared without a column count, or null when no
+ * grid layout is present.
+ */
+export function extractGridColsFromTree(node: JsxNode | undefined): number | null {
+  if (!node || node.type !== 'element') return null;
+  const el = node as JsxElement;
+  const className = el.props && el.props.className ? String(el.props.className) : '';
+  const list = className ? splitClassName(className) : [];
+  let hasGrid = false;
+  for (let i = 0; i < list.length; i++) {
+    const cls = list[i];
+    if (cls === 'grid' || cls === 'inline-grid') hasGrid = true;
+    const match = cls.match(/^grid-cols-(\d+)$/);
+    if (match) return parseInt(match[1], 10);
+  }
+  const children = el.children || [];
+  for (let i = 0; i < children.length; i++) {
+    const found = extractGridColsFromTree(children[i]);
+    if (found != null) return found;
+  }
+  return hasGrid ? 1 : null;
+}
+
+/**
+ * Read only the root node's grid column intent. This avoids accidentally
+ * inheriting nested `grid-cols-*` from descendants (for example form rows in
+ * dialog content) when sizing top-level responsive preview containers.
+ */
+export function extractRootGridColsFromTree(node: JsxNode | undefined): number | null {
+  if (!node || node.type !== 'element') return null;
+  const el = node as JsxElement;
+  const className = el.props && el.props.className ? String(el.props.className) : '';
+  const list = className ? splitClassName(className) : [];
+  let hasGrid = false;
+  for (let i = 0; i < list.length; i++) {
+    const cls = list[i];
+    if (cls === 'grid' || cls === 'inline-grid') hasGrid = true;
+    const match = cls.match(/^grid-cols-(\d+)$/);
+    if (match) return parseInt(match[1], 10);
+  }
+  return hasGrid ? 1 : null;
+}
+
+/**
+ * Walk down the leading single-child spine of the JSX tree and return the
+ * tightest `max-w-*` constraint where `w-full` is also set on the same node.
+ * Returns null when no constrained full-width container is found.
+ */
+export function extractLeadingContainerMaxWidthFromTree(node: JsxNode | undefined): number | null {
+  let current: JsxNode | undefined = node;
+  let constrainedWidth: number | null = null;
+
+  while (current && current.type === 'element') {
+    const element = current as JsxElement;
+    const className = element.props && element.props.className ? String(element.props.className) : '';
+    const classes = className ? splitClassName(className) : [];
+    const hasFullWidth = classes.indexOf('w-full') !== -1;
+    const maxWidth = extractMaxWidth(classes);
+
+    if (hasFullWidth && maxWidth != null) {
+      constrainedWidth = constrainedWidth == null ? maxWidth : Math.min(constrainedWidth, maxWidth);
+    }
+
+    const children = element.children || [];
+    if (children.length !== 1 || !children[0] || children[0].type !== 'element') {
+      break;
+    }
+    current = children[0];
+  }
+
+  return constrainedWidth;
+}
+
+/**
+ * Propagate child-wildcard utility classes (`*:X`, `sm:*:X`, etc.) from a node
+ * to all of its direct element children, then remove them from the parent.
+ *
+ * This mirrors the CSS default where `align-items: stretch` (implicit in flex)
+ * makes children fill the cross-axis. A developer writing `*:w-full sm:*:w-auto`
+ * on a flex-col container intends each child to be full-width at mobile and
+ * auto-width at sm+. The Figma renderer already handles `w-full` and `sm:w-auto`
+ * on individual nodes, so we only need to propagate them down.
+ *
+ * Operates recursively over the whole tree so nested containers are handled too.
+ */
+export function propagateChildSelectorClasses(node: JsxNode): JsxNode {
+  if (!node || node.type !== 'element') return node;
+  const el = node as JsxElement;
+  const className: string = el.props && el.props.className ? String(el.props.className) : '';
+  const classes = className ? splitClassName(className) : [];
+
+  // Collect *:X and bp:*:X classes, convert to the class that should be added to children.
+  // e.g. `*:w-full` → `w-full`, `sm:*:w-auto` → `sm:w-auto`
+  const rawPropagate: string[] = [];
+  const keepOnParent: string[] = [];
+  for (let i = 0; i < classes.length; i++) {
+    const cls = classes[i];
+    // bare `*:X`
+    const bareMatch = cls.match(/^\*:(.+)$/);
+    if (bareMatch) {
+      rawPropagate.push(bareMatch[1]);
+      continue;
+    }
+    // `bp:*:X`
+    const bpMatch = cls.match(/^([a-z0-9]+):\*:(.+)$/);
+    if (bpMatch) {
+      rawPropagate.push(bpMatch[1] + ':' + bpMatch[2]);
+      continue;
+    }
+    keepOnParent.push(cls);
+  }
+
+  // Deduplicate by Tailwind property prefix (last-wins, mirrors CSS cascade).
+  // This ensures that when mapClassNameForBreakpoint produces both *:w-full (base)
+  // and *:w-auto (from sm:*:w-auto at sm breakpoint), only w-auto is propagated —
+  // avoiding the w-full STRETCH from silently beating the later w-auto.
+  const lastByPrefix = new Map<string, string>();
+  for (let i = 0; i < rawPropagate.length; i++) {
+    const cls = rawPropagate[i];
+    // Strip any breakpoint prefix before extracting the property prefix.
+    const utilityPart = cls.replace(/^[a-z0-9]+:/, '');
+    const dashIdx = utilityPart.indexOf('-');
+    const prefix = dashIdx > 0 ? utilityPart.slice(0, dashIdx) : utilityPart;
+    lastByPrefix.set(prefix, cls);
+  }
+  const toPropagate = Array.from(lastByPrefix.values());
+
+  // Recursively process children first, then inject propagated classes
+  const nextChildren: JsxNode[] = [];
+  const children = el.children || [];
+  for (let i = 0; i < children.length; i++) {
+    let child = propagateChildSelectorClasses(children[i]);
+    if (toPropagate.length > 0 && child && child.type === 'element') {
+      const childEl = child as JsxElement;
+      const childClass: string = childEl.props && childEl.props.className
+        ? String(childEl.props.className)
+        : '';
+      const merged = toPropagate.join(' ') + (childClass ? ' ' + childClass : '');
+      child = Object.assign({}, childEl, {
+        props: Object.assign({}, childEl.props || {}, { className: merged }),
+      });
+    }
+    nextChildren.push(child);
+  }
+
+  const nextClassName = keepOnParent.join(' ');
+  return Object.assign({}, el, {
+    props: Object.assign({}, el.props || {}, { className: nextClassName }),
+    children: nextChildren,
+  });
+}
+
+/**
+ * Deduplicate a list of classes and return them joined as a single string.
+ * Preserves first-occurrence order.
+ */
+export function uniqueClassSignature(classes: string[] | undefined): string {
+  const seen: Record<string, boolean> = {};
+  const output: string[] = [];
+  const list = classes || [];
+  for (let i = 0; i < list.length; i++) {
+    const cls = list[i];
+    if (!cls || seen[cls]) continue;
+    seen[cls] = true;
+    output.push(cls);
+  }
+  return output.join(' ');
+}
+
+/**
+ * Produce a stable, deduplicated string signature of all classes in a JSX tree.
+ * Used for hashing / change detection.
+ */
+export function treeClassSignature(node: JsxNode | undefined): string {
+  const classes: string[] = [];
+  collectTreeClasses(node, classes);
+  return uniqueClassSignature(classes);
+}
+
+/**
+ * Assemble the final class list for one variant of a CVA component definition,
+ * combining base classes + per-variant classes + any extra className prop.
+ */
+export function buildCvaClassesForVariant(
+  def: ComponentDef,
+  props: Record<string, string>,
+  primaryKey: string,
+  primaryValue: string
+): string[] {
+  const classes: string[] = [];
+  if (def && def.baseClasses) {
+    for (let i = 0; i < def.baseClasses.length; i++) classes.push(def.baseClasses[i]);
+  }
+  const variants = def && def.variants ? def.variants : {};
+  const variantKeys = Object.keys(variants);
+  for (let i = 0; i < variantKeys.length; i++) {
+    const key = variantKeys[i];
+    let value: string | null = null;
+    if (key === primaryKey) {
+      value = primaryValue;
+    } else if (props && props[key]) {
+      value = props[key];
+    } else if (def && def.defaultVariants && def.defaultVariants[key]) {
+      value = def.defaultVariants[key];
+    } else if (variants[key] && variants[key][0]) {
+      value = variants[key][0];
+    }
+    if (value && def.variantClasses && def.variantClasses[key] && def.variantClasses[key][value]) {
+      const variantClasses = def.variantClasses[key][value];
+      for (let j = 0; j < variantClasses.length; j++) classes.push(variantClasses[j]);
+    }
+  }
+  const extra = splitClassName(props && props.className);
+  for (let i = 0; i < extra.length; i++) classes.push(extra[i]);
+  return classes;
+}
+
+/**
+ * Return the pixel width to use for a responsive preview frame.
+ * Falls back to a mobile-first 390 px when the breakpoint has no registered
+ * min-width or the breakpoint is 'base'.
+ */
+export function getResponsivePreviewWidth(breakpointName: string, minWidth: number): number {
+  if (breakpointName === 'base') return 390;
+  if (Number.isFinite(minWidth) && minWidth > 0) return minWidth;
+  return 390;
+}

package/src/{node-ir.ts → tailwind/node-ir.ts}

@@ -1,4 +1,7 @@
-import { parseColor, type RGB } from './colors';
+import { parseColor, type RGB } from '../tokens';
+import type { ComponentDef } from '../components/scanner-types';
+import { applyFrameworkAdapters } from '../framework-adapters';
+import { mergeMissing, resolveValuePercents } from './adapter-utils';
 
 // ---------------------------------------------------------------------------
 // JSX tree types
@@ -73,9 +76,9 @@ export type NodeIR =
   | NodeIRRing;
 
 export type NodeIRHelpers = {
-  getComponentDefByName: (name: string) => any | null;
-  normalizeComponentDef: (raw: any) => any;
-  getCompoundClasses: (def: any, tagName: string) => string[];
+  getComponentDefByName: (name: string) => ComponentDef | null;
+  normalizeComponentDef: (raw: ComponentDef) => ComponentDef;
+  getCompoundClasses: (def: ComponentDef, tagName: string) => string[];
   mergeClasses: (base: string[], extra: string[]) => string[];
 };
 
@@ -85,10 +88,22 @@ export type NodeIRHelpers = {
 
 export function splitClassName(value?: string): string[] {
   if (!value) return [];
-  return String(value)
-    .split(/\s+/)
-    .map(c => c.replace(/^!/, '').replace(/!$/, ''))
-    .filter(Boolean);
+  const out: string[] = [];
+  for (const raw of String(value).split(/\s+/)) {
+    const cleaned = raw.replace(/^!/, '').replace(/!$/, '');
+    if (!cleaned) continue;
+    // `size-full` is Tailwind shorthand for `w-full h-full`. Expand it here
+    // so every downstream parser/check that already understands w-full and
+    // h-full handles size-full automatically — no parallel code path. The
+    // numeric `size-N` form has its own dedicated handler in sizing.ts and
+    // is intentionally left alone.
+    if (cleaned === 'size-full') {
+      out.push('w-full', 'h-full');
+      continue;
+    }
+    out.push(cleaned);
+  }
+  return out;
 }
 
 export function resolveNodeIR(node: JsxNode): NodeIR | null {
@@ -140,7 +155,16 @@ export function applyNodeTransforms(
   colorGroup: Record<string, string>,
   helpers: NodeIRHelpers
 ): NodeIR {
-  let next = flattenComponentNodes(node, null, helpers);
+  // Framework adapters run FIRST so the injected classes flow through the
+  // flatten merge (a wrapper compound's class list and the adapter's
+  // slot-injected classes end up on the same element) and through every
+  // downstream transform without parallel handling.
+  let next = applyFrameworkAdapters(node);
+  next = flattenComponentNodes(next, null, helpers);
+  // Native HTML input rewrites run BEFORE the visual transforms (space,
+  // divide, ring) so the synthetic tree they emit flows through the rest
+  // of the pipeline as ordinary div + Tailwind classes.
+  next = transformInputNodes(next);
   next = transformSpaceNodes(next);
   next = transformDivideNodes(next, colorGroup);
   next = transformRingNodes(next, colorGroup);
@@ -157,7 +181,7 @@ export function isElementLikeNode(node: NodeIR): node is NodeIRElement | NodeIRC
 
 function flattenComponentNodes(
   node: NodeIR,
-  parentCompoundDef: any | null,
+  parentCompoundDef: ComponentDef | null,
   helpers: NodeIRHelpers
 ): NodeIR {
   if (node.kind === 'text' || node.kind === 'divider') {
@@ -229,6 +253,173 @@ function flattenComponentNodes(
   });
 }
 
+// ---------------------------------------------------------------------------
+// Native HTML input rewrites
+//
+// Some `<input>` types have no built-in className-driven appearance that
+// Figma can render — most notably `type="range"`, which is a custom
+// browser widget (track + thumb). The default input branch in
+// `ui-builder.ts` reads `value` / `defaultValue` / `placeholder` and
+// emits a text node — fine for text/number/email, useless (or worse,
+// stalling) for range. This transform rewrites those special cases at
+// the IR-transform stage into a synthetic Tailwind tree the existing
+// pipeline already knows how to render.
+//
+// Currently handles: `type="range"`. Extend the dispatcher in
+// `transformInputNodes` when other types need similar treatment (e.g.
+// checkbox / radio with `checked` driving a visual indicator).
+// ---------------------------------------------------------------------------
+
+export function transformInputNodes(node: NodeIR): NodeIR {
+  if (node.kind === 'text' || node.kind === 'divider') {
+    return node;
+  }
+
+  if (node.kind === 'fragment') {
+    return recurseFragment(node, transformInputNodes);
+  }
+
+  if (node.kind === 'ring') {
+    const nextChild = transformInputNodes(node.child);
+    return nextChild === node.child ? node : Object.assign({}, node, { child: nextChild });
+  }
+
+  // Recurse first so any nested `<input>` is rewritten before its parent
+  // decides what to do with it. Preserve object identity when no
+  // descendant changed (keeps `NODE_LAYOUT_CACHE` warm).
+  let childrenChanged = false;
+  const nextChildren: NodeIR[] = [];
+  for (const child of node.children) {
+    const next = transformInputNodes(child);
+    if (next !== child) childrenChanged = true;
+    nextChildren.push(next);
+  }
+  const recursed: NodeIR = childrenChanged
+    ? (Object.assign({}, node, { children: nextChildren }) as NodeIR)
+    : node;
+
+  if (recursed.kind !== 'element') return recursed;
+  if (recursed.tagLower !== 'input') return recursed;
+  const type = (recursed.props && recursed.props.type) || '';
+  if (type !== 'range') return recursed;
+
+  return buildRangeSliderTree(recursed as NodeIRElement);
+}
+
+function recurseFragment(
+  frag: NodeIRFragment,
+  fn: (n: NodeIR) => NodeIR,
+): NodeIR {
+  let changed = false;
+  const next: NodeIR[] = [];
+  for (const c of frag.children) {
+    const r = fn(c);
+    if (r !== c) changed = true;
+    next.push(r);
+  }
+  return changed ? Object.assign({}, frag, { children: next }) : frag;
+}
+
+/**
+ * Rewrite `<input type="range" min=N max=M value=V disabled? className=...>`
+ * into a styled `<div>` tree mirroring the shape that shadcn Slider's
+ * adapter already produces (and which the renderer is known to handle):
+ *
+ *   wrapper (relative flex h-4 items-center, consumer classes preserved)
+ *     └── track  (flow child: h-1.5 w-full rounded-full overflow-hidden bg-secondary)
+ *           └── filled (flow child of track: h-full rounded-full bg-primary w-[N%])
+ *     └── thumb  (absolute sibling of track: size-4 rounded-full -translate-x-1/2 left-[N%])
+ *
+ * Why mirror shadcn's structure (track as flow child, thumb as absolute
+ * sibling)? An all-absolute-children wrapper has no flow content to size
+ * against — deferred-layout passes can stall trying to resolve a 0-content
+ * frame with `flex items-center`. The shadcn Slider already navigates this
+ * by making Track a flow child of Control; we copy that pattern.
+ *
+ * Vertical centering of the thumb comes from `flex items-center` on the
+ * wrapper combined with the thumb's static position (size-4 = wrapper
+ * height) — no `top-1/2 -translate-y-1/2` needed.
+ *
+ * Geometry: `pct = ((value - min) / (max - min)) * 100`. See
+ * `resolveValuePercents` in `./adapter-utils.ts`.
+ */
+function buildRangeSliderTree(input: NodeIRElement): NodeIR {
+  const props = input.props || {};
+  const rawValue = props.value ?? props.defaultValue;
+  const pcts = resolveValuePercents(rawValue, props.min, props.max);
+  const pct = pcts[0] ?? 0;
+  const isDisabled = props.disabled !== undefined && props.disabled !== 'false';
+
+  // Preserve sizing-related classes from the consumer (`w-full`, `w-[Npx]`,
+  // `max-w-*`) onto the wrapper. Visual / state classes that applied to the
+  // native widget shape (`accent-primary`, focus rings) are kept but
+  // typically no-ops on the synthetic div.
+  const wrapperExtras = ['relative', 'flex', 'h-4', 'items-center'];
+  if (isDisabled) wrapperExtras.push('opacity-50');
+  const wrapperClasses = mergeMissing(input.classes, wrapperExtras);
+
+  const filled: NodeIR = makeRangeChild('div', [
+    'h-full',
+    'rounded-full',
+    'bg-primary',
+    `w-[${formatPercent(pct)}%]`,
+  ]);
+
+  const track: NodeIRElement = {
+    kind: 'element',
+    tagName: 'div',
+    tagLower: 'div',
+    props: {},
+    classes: [
+      'h-1.5',
+      'w-full',
+      'rounded-full',
+      'overflow-hidden',
+      'bg-secondary',
+    ],
+    children: [filled],
+  };
+
+  const thumb: NodeIR = makeRangeChild('div', [
+    'absolute',
+    'size-4',
+    'rounded-full',
+    'border-2',
+    'border-primary',
+    'bg-background',
+    '-translate-x-1/2',
+    `left-[${formatPercent(pct)}%]`,
+  ]);
+
+  return {
+    kind: 'element',
+    tagName: 'div',
+    tagLower: 'div',
+    props: {},
+    classes: wrapperClasses,
+    children: [track, thumb],
+  };
+}
+
+function makeRangeChild(tag: string, classes: string[]): NodeIRElement {
+  return {
+    kind: 'element',
+    tagName: tag,
+    tagLower: tag,
+    props: {},
+    classes,
+    children: [],
+  };
+}
+
+function formatPercent(pct: number): string {
+  // Two-decimal precision keeps thumb placement visually correct for
+  // common (min, max, value) triples without bloating the class name.
+  // `Number.toFixed` always renders fixed decimals; trim trailing zeros.
+  const fixed = pct.toFixed(2);
+  return fixed.replace(/\.?0+$/, '') || '0';
+}
+
 function transformSpaceNodes(node: NodeIR): NodeIR {
   if (node.kind === 'text' || node.kind === 'divider') {
     return node;
@@ -479,38 +670,35 @@ function parseRingTokens(
   let opacity: number | null = null;
   let offsetWidth: number | null = null;
   let offsetColor: RGB | null = null;
-  let sawRing = false;
+  let sawRingWidth = false;
 
   for (const raw of classes) {
     if (raw === 'ring') {
-      sawRing = true;
+      sawRingWidth = true;
       width = width == null ? 3 : width;
       continue;
     }
     const widthMatch = raw.match(/^ring-(\d+)$/);
     if (widthMatch) {
-      sawRing = true;
+      sawRingWidth = true;
       width = parseInt(widthMatch[1], 10);
       continue;
     }
     const bracketMatch = raw.match(/^ring-\[(\d+(?:\.\d+)?)px\]$/);
     if (bracketMatch) {
-      sawRing = true;
+      sawRingWidth = true;
       width = parseFloat(bracketMatch[1]);
       continue;
     }
     const opacityMatch = raw.match(/^ring-opacity-(\d+)$/);
     if (opacityMatch) {
-      sawRing = true;
       opacity = Math.max(0, Math.min(1, parseInt(opacityMatch[1], 10) / 100));
       continue;
     }
     if (raw === 'ring-inset') {
-      sawRing = true;
       continue;
     }
     if (raw.startsWith('ring-offset-')) {
-      sawRing = true;
       const offsetRaw = raw.slice('ring-offset-'.length);
       const offsetBracket = offsetRaw.match(/^\[(.+)\]$/);
       if (offsetBracket) {
@@ -530,7 +718,6 @@ function parseRingTokens(
       continue;
     }
     if (raw.startsWith('ring-')) {
-      sawRing = true;
       const tokenRaw = raw.slice('ring-'.length);
       const parts = tokenRaw.split('/');
       const token = parts[0];
@@ -548,7 +735,9 @@ function parseRingTokens(
     }
   }
 
-  if (!sawRing) return null;
+  // Tailwind ring modifiers like `ring-offset-*`, `ring-opacity-*`, and `ring-<color>`
+  // do not render a ring by themselves — they only modify an existing ring width.
+  if (!sawRingWidth) return null;
 
   if (width == null) width = 3;
   if (!color) {

package/src/{responsive-analyzer.ts → tailwind/responsive-analyzer.ts}

@@ -49,12 +49,18 @@ function splitResponsiveClass(cls: string): { bucket: string; utility: string |
   }
 
   if (responsiveVariants.length === 0) {
-    if (remainingVariants.length > 0) return null;
+    // Non-responsive variants like *:, hover:, focus: — keep the original class
+    // string in the base bucket so it appears at every breakpoint.
+    if (remainingVariants.length > 0) return { bucket: 'base', utility: cls };
     return { bucket: 'base', utility: utility };
   }
 
-  if (remainingVariants.length > 0) return null;
   const bucket = responsiveVariants[responsiveVariants.length - 1];
+  if (remainingVariants.length > 0) {
+    // Mixed e.g. sm:*:w-auto — strip the responsive prefix but preserve the
+    // remaining variants so the output is *:w-auto at the sm bucket.
+    return { bucket: bucket, utility: remainingVariants.join(':') + ':' + utility };
+  }
   return { bucket: bucket, utility: utility };
 }
 
@@ -78,6 +84,30 @@ function buildResponsiveBuckets(classes: string[]): Record<string, string[]> {
   return buckets;
 }
 
+const DISPLAY_UTILITIES = new Set([
+  'hidden', 'block', 'inline-block', 'inline', 'flex', 'inline-flex',
+  'grid', 'inline-grid', 'table', 'inline-table', 'contents', 'list-item',
+  'flow-root', 'table-row', 'table-cell', 'table-caption', 'table-column',
+  'table-column-group', 'table-footer-group', 'table-header-group',
+  'table-row-group',
+]);
+
+/**
+ * Returns true when the given class set resolves to `display: none` at the
+ * target breakpoint, after the base → sm → md → … cascade. Used to skip
+ * responsive-preview tiles where the component is hidden (e.g. md:hidden).
+ */
+export function isHiddenAtBreakpoint(classes: string[], breakpoint: string): boolean {
+  const effective = getClassesForBreakpoint(classes, breakpoint);
+  let lastDisplay: string | null = null;
+  for (let i = 0; i < effective.length; i++) {
+    const cls = effective[i];
+    const bare = cls.charAt(0) === '!' ? cls.slice(1) : cls;
+    if (DISPLAY_UTILITIES.has(bare)) lastDisplay = bare;
+  }
+  return lastDisplay === 'hidden';
+}
+
 export function extractBreakpointsFromClasses(classes: string[]): BreakpointInfo[] {
   const buckets = buildResponsiveBuckets(classes);
   const hasResponsive = BREAKPOINT_ORDER.some(bp => (buckets[bp] && buckets[bp].length > 0));