meno-core 1.0.48 → 1.0.49

package/lib/shared/cssProperties.test.ts

@@ -2,12 +2,32 @@ import { describe, test, expect } from 'bun:test';
 import {
   CSS_PROPERTIES,
   CSS_PROPERTIES_DEFINITION,
+  CSS_PROPERTY_GROUPS,
   filterCSSProperties,
   getPropertyValues,
   filterPropertyValues,
-  getPropertyType
+  getPropertyType,
+  VISUAL_MODE_PROPERTIES,
+  isVisualModeProperty,
+  VISUAL_MODE_RULES,
+  isVisualModeRowVisible,
+  type VisualModeRuleContext,
+  UNITLESS_PROPERTIES,
+  appendsPxByDefault,
 } from './cssProperties';
 
+const baseCtx: VisualModeRuleContext = {
+  display: 'block',
+  parentDisplay: 'block',
+  position: 'static',
+  tagName: 'div',
+  hasPaddingLonghand: false,
+  hasMarginLonghand: false,
+  hasBackgroundImage: false,
+};
+const ctx = (overrides: Partial<VisualModeRuleContext> = {}): VisualModeRuleContext =>
+  ({ ...baseCtx, ...overrides });
+
 describe('cssProperties', () => {
   describe('CSS_PROPERTIES', () => {
     test('is an array of property names', () => {
@@ -249,4 +269,230 @@ describe('cssProperties', () => {
       expect(getPropertyType('padding')).toBe('string');
     });
   });
+
+  describe('VISUAL_MODE_PROPERTIES', () => {
+    test('contains common Webflow-style groups', () => {
+      expect(VISUAL_MODE_PROPERTIES['Layout']).toContain('display');
+      expect(VISUAL_MODE_PROPERTIES['Spacing']).toContain('padding');
+      expect(VISUAL_MODE_PROPERTIES['Typography']).toContain('fontSize');
+    });
+
+    test('every group name maps to a known CSS_PROPERTY_GROUPS group', () => {
+      for (const groupName of Object.keys(VISUAL_MODE_PROPERTIES)) {
+        expect(CSS_PROPERTY_GROUPS[groupName]).toBeDefined();
+      }
+    });
+
+    test('every property in VISUAL_MODE_PROPERTIES belongs to its declared group in CSS_PROPERTY_GROUPS', () => {
+      for (const [groupName, props] of Object.entries(VISUAL_MODE_PROPERTIES)) {
+        for (const prop of props) {
+          expect(CSS_PROPERTY_GROUPS[groupName]).toContain(prop);
+        }
+      }
+    });
+  });
+
+  describe('isVisualModeProperty', () => {
+    test('returns true for properties listed in VISUAL_MODE_PROPERTIES', () => {
+      expect(isVisualModeProperty('display')).toBe(true);
+      expect(isVisualModeProperty('padding')).toBe(true);
+      expect(isVisualModeProperty('color')).toBe(true);
+    });
+
+    test('returns false for properties not in VISUAL_MODE_PROPERTIES', () => {
+      expect(isVisualModeProperty('gridTemplateRows')).toBe(false);
+      expect(isVisualModeProperty('clipPath')).toBe(false);
+      expect(isVisualModeProperty('nonExistent')).toBe(false);
+    });
+  });
+
+  describe('VISUAL_MODE_RULES — flex/grid container props', () => {
+    test('flexDirection visible only when display is flex/inline-flex', () => {
+      expect(VISUAL_MODE_RULES.flexDirection(ctx({ display: 'flex' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.flexDirection(ctx({ display: 'inline-flex' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.flexDirection(ctx({ display: 'block' }))).toBe(false);
+      expect(VISUAL_MODE_RULES.flexDirection(ctx({ display: 'grid' }))).toBe(false);
+    });
+
+    test('justifyContent visible for flex AND grid', () => {
+      expect(VISUAL_MODE_RULES.justifyContent(ctx({ display: 'flex' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.justifyContent(ctx({ display: 'grid' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.justifyContent(ctx({ display: 'block' }))).toBe(false);
+    });
+
+    test('gridTemplateColumns visible only for grid/inline-grid', () => {
+      expect(VISUAL_MODE_RULES.gridTemplateColumns(ctx({ display: 'grid' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.gridTemplateColumns(ctx({ display: 'inline-grid' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.gridTemplateColumns(ctx({ display: 'flex' }))).toBe(false);
+      expect(VISUAL_MODE_RULES.gridTemplateColumns(ctx({ display: 'block' }))).toBe(false);
+    });
+
+    test('gap visible for both flex and grid containers', () => {
+      expect(VISUAL_MODE_RULES.gap(ctx({ display: 'flex' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.gap(ctx({ display: 'grid' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.gap(ctx({ display: 'block' }))).toBe(false);
+    });
+  });
+
+  describe('VISUAL_MODE_RULES — flex/grid item props (parent display)', () => {
+    test('flexGrow visible only when parent is flex', () => {
+      expect(VISUAL_MODE_RULES.flexGrow(ctx({ parentDisplay: 'flex' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.flexGrow(ctx({ parentDisplay: 'inline-flex' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.flexGrow(ctx({ parentDisplay: 'block' }))).toBe(false);
+      expect(VISUAL_MODE_RULES.flexGrow(ctx({ parentDisplay: 'grid' }))).toBe(false);
+    });
+
+    test('gridArea visible only when parent is grid', () => {
+      expect(VISUAL_MODE_RULES.gridArea(ctx({ parentDisplay: 'grid' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.gridArea(ctx({ parentDisplay: 'inline-grid' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.gridArea(ctx({ parentDisplay: 'flex' }))).toBe(false);
+      expect(VISUAL_MODE_RULES.gridArea(ctx({ parentDisplay: 'block' }))).toBe(false);
+    });
+
+    test('alignSelf visible when parent is flex OR grid', () => {
+      expect(VISUAL_MODE_RULES.alignSelf(ctx({ parentDisplay: 'flex' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.alignSelf(ctx({ parentDisplay: 'grid' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.alignSelf(ctx({ parentDisplay: 'block' }))).toBe(false);
+    });
+
+    test('item rules ignore own display — only parent display matters', () => {
+      // Element has display:block but parent is flex → flexGrow still visible.
+      expect(VISUAL_MODE_RULES.flexGrow(ctx({ display: 'block', parentDisplay: 'flex' }))).toBe(true);
+      // Element has display:flex but parent is block → flexGrow hidden.
+      expect(VISUAL_MODE_RULES.flexGrow(ctx({ display: 'flex', parentDisplay: 'block' }))).toBe(false);
+    });
+  });
+
+  describe('VISUAL_MODE_RULES — position-dependent', () => {
+    test('top/right/bottom/left/zIndex hidden when position is static', () => {
+      const c = ctx({ position: 'static' });
+      expect(VISUAL_MODE_RULES.top(c)).toBe(false);
+      expect(VISUAL_MODE_RULES.right(c)).toBe(false);
+      expect(VISUAL_MODE_RULES.bottom(c)).toBe(false);
+      expect(VISUAL_MODE_RULES.left(c)).toBe(false);
+      expect(VISUAL_MODE_RULES.zIndex(c)).toBe(false);
+    });
+
+    test('top/right/bottom/left/zIndex visible when position is non-static', () => {
+      for (const position of ['relative', 'absolute', 'fixed', 'sticky']) {
+        const c = ctx({ position });
+        expect(VISUAL_MODE_RULES.top(c)).toBe(true);
+        expect(VISUAL_MODE_RULES.zIndex(c)).toBe(true);
+      }
+    });
+  });
+
+  describe('VISUAL_MODE_RULES — tag-based', () => {
+    test('objectFit visible only for img/video', () => {
+      expect(VISUAL_MODE_RULES.objectFit(ctx({ tagName: 'img' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.objectFit(ctx({ tagName: 'video' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.objectFit(ctx({ tagName: 'div' }))).toBe(false);
+    });
+
+    test('listStyle visible only for ul/ol/li', () => {
+      expect(VISUAL_MODE_RULES.listStyle(ctx({ tagName: 'ul' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.listStyle(ctx({ tagName: 'ol' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.listStyle(ctx({ tagName: 'li' }))).toBe(true);
+      expect(VISUAL_MODE_RULES.listStyle(ctx({ tagName: 'div' }))).toBe(false);
+    });
+  });
+
+  describe('VISUAL_MODE_RULES — padding/margin shorthand-vs-longhand toggle', () => {
+    test('padding shown when no longhand set; longhands hidden', () => {
+      const c = ctx({ hasPaddingLonghand: false });
+      expect(VISUAL_MODE_RULES.padding(c)).toBe(true);
+      expect(VISUAL_MODE_RULES.paddingTop(c)).toBe(false);
+      expect(VISUAL_MODE_RULES.paddingRight(c)).toBe(false);
+      expect(VISUAL_MODE_RULES.paddingBottom(c)).toBe(false);
+      expect(VISUAL_MODE_RULES.paddingLeft(c)).toBe(false);
+    });
+
+    test('padding hidden when any longhand set; longhands shown', () => {
+      const c = ctx({ hasPaddingLonghand: true });
+      expect(VISUAL_MODE_RULES.padding(c)).toBe(false);
+      expect(VISUAL_MODE_RULES.paddingTop(c)).toBe(true);
+      expect(VISUAL_MODE_RULES.paddingRight(c)).toBe(true);
+      expect(VISUAL_MODE_RULES.paddingBottom(c)).toBe(true);
+      expect(VISUAL_MODE_RULES.paddingLeft(c)).toBe(true);
+    });
+
+    test('margin mirrors padding behavior', () => {
+      const noLong = ctx({ hasMarginLonghand: false });
+      expect(VISUAL_MODE_RULES.margin(noLong)).toBe(true);
+      expect(VISUAL_MODE_RULES.marginTop(noLong)).toBe(false);
+      const withLong = ctx({ hasMarginLonghand: true });
+      expect(VISUAL_MODE_RULES.margin(withLong)).toBe(false);
+      expect(VISUAL_MODE_RULES.marginTop(withLong)).toBe(true);
+    });
+  });
+
+  describe('isVisualModeRowVisible', () => {
+    test('returns true for properties without a rule', () => {
+      // width has no rule entry → always visible regardless of context.
+      expect(isVisualModeRowVisible('width', ctx())).toBe(true);
+      expect(isVisualModeRowVisible('color', ctx())).toBe(true);
+      expect(isVisualModeRowVisible('nonExistentProp', ctx())).toBe(true);
+    });
+
+    test('delegates to the rule for known properties', () => {
+      expect(isVisualModeRowVisible('flexDirection', ctx({ display: 'flex' }))).toBe(true);
+      expect(isVisualModeRowVisible('flexDirection', ctx({ display: 'block' }))).toBe(false);
+      expect(isVisualModeRowVisible('top', ctx({ position: 'absolute' }))).toBe(true);
+      expect(isVisualModeRowVisible('top', ctx({ position: 'static' }))).toBe(false);
+    });
+  });
+
+  describe('UNITLESS_PROPERTIES', () => {
+    test('contains the canonical unitless props', () => {
+      expect(UNITLESS_PROPERTIES.has('fontWeight')).toBe(true);
+      expect(UNITLESS_PROPERTIES.has('lineHeight')).toBe(true);
+      expect(UNITLESS_PROPERTIES.has('opacity')).toBe(true);
+      expect(UNITLESS_PROPERTIES.has('zIndex')).toBe(true);
+      expect(UNITLESS_PROPERTIES.has('flexGrow')).toBe(true);
+      expect(UNITLESS_PROPERTIES.has('order')).toBe(true);
+      expect(UNITLESS_PROPERTIES.has('aspectRatio')).toBe(true);
+    });
+
+    test('does not contain length-accepting props', () => {
+      expect(UNITLESS_PROPERTIES.has('width')).toBe(false);
+      expect(UNITLESS_PROPERTIES.has('padding')).toBe(false);
+      expect(UNITLESS_PROPERTIES.has('fontSize')).toBe(false);
+    });
+  });
+
+  describe('appendsPxByDefault', () => {
+    test('returns true for length-accepting props', () => {
+      expect(appendsPxByDefault('width')).toBe(true);
+      expect(appendsPxByDefault('height')).toBe(true);
+      expect(appendsPxByDefault('padding')).toBe(true);
+      expect(appendsPxByDefault('paddingTop')).toBe(true);
+      expect(appendsPxByDefault('margin')).toBe(true);
+      expect(appendsPxByDefault('gap')).toBe(true);
+      expect(appendsPxByDefault('fontSize')).toBe(true);
+      expect(appendsPxByDefault('borderRadius')).toBe(true);
+      expect(appendsPxByDefault('top')).toBe(true);
+      expect(appendsPxByDefault('left')).toBe(true);
+    });
+
+    test('returns false for unitless props', () => {
+      expect(appendsPxByDefault('lineHeight')).toBe(false);
+      expect(appendsPxByDefault('fontWeight')).toBe(false);
+      expect(appendsPxByDefault('opacity')).toBe(false);
+      expect(appendsPxByDefault('zIndex')).toBe(false);
+      expect(appendsPxByDefault('flexGrow')).toBe(false);
+      expect(appendsPxByDefault('order')).toBe(false);
+      expect(appendsPxByDefault('aspectRatio')).toBe(false);
+    });
+
+    test('returns false for keyword-only (select / boolean) props', () => {
+      expect(appendsPxByDefault('display')).toBe(false);
+      expect(appendsPxByDefault('position')).toBe(false);
+      expect(appendsPxByDefault('borderStyle')).toBe(false);
+    });
+
+    test('defaults to true for properties without a recognized unitless / keyword type', () => {
+      expect(appendsPxByDefault('inset')).toBe(true);
+      expect(appendsPxByDefault('someUnknownNewCSSProperty')).toBe(true);
+    });
+  });
 });

package/lib/shared/cssProperties.ts

@@ -421,14 +421,15 @@ function getPropertyPriority(property: string): number {
  * Order determines display order in the UI
  */
 export const CSS_PROPERTY_GROUPS: Record<string, string[]> = {
-  'Layout': ['display', 'position', 'top', 'right', 'bottom', 'left', 'inset', 'zIndex'],
-  'Dimensions': ['width', 'height', 'minWidth', 'maxWidth', 'minHeight', 'maxHeight', 'aspectRatio'],
-  'Spacing': ['margin', 'marginTop', 'marginRight', 'marginBottom', 'marginLeft', 'padding', 'paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft', 'gap', 'rowGap', 'columnGap'],
-  'Flexbox': ['flex', 'flexDirection', 'flexWrap', 'flexFlow', 'justifyContent', 'alignItems', 'alignContent', 'alignSelf', 'flexGrow', 'flexShrink', 'flexBasis', 'order'],
+  'Layout': ['display'],
+  'Spacing': ['margin', 'marginTop', 'marginRight', 'marginBottom', 'marginLeft', 'padding', 'paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft'],
+  'Size': ['width', 'height', 'minWidth', 'maxWidth', 'minHeight', 'maxHeight', 'aspectRatio'],
+  'Position': ['position', 'top', 'right', 'bottom', 'left', 'inset', 'zIndex'],
+  'Flexbox': ['flex', 'flexDirection', 'flexWrap', 'flexFlow', 'justifyContent', 'alignItems', 'alignContent', 'gap', 'rowGap', 'columnGap', 'alignSelf', 'flexGrow', 'flexShrink', 'flexBasis', 'order'],
   'Grid': ['grid', 'gridTemplateColumns', 'gridTemplateRows', 'gridTemplateAreas', 'gridGap', 'gridColumn', 'gridRow', 'gridArea', 'gridAutoFlow', 'gridAutoColumns', 'gridAutoRows', 'justifyItems', 'justifySelf', 'placeContent', 'placeItems', 'placeSelf'],
-  'Typography': ['fontSize', 'fontWeight', 'fontFamily', 'fontStyle', 'lineHeight', 'textAlign', 'textDecoration', 'textTransform', 'letterSpacing', 'wordSpacing', 'wordBreak', 'overflowWrap', 'textIndent', 'verticalAlign', 'color'],
+  'Typography': ['fontWeight', 'fontSize', 'fontFamily', 'fontStyle', 'lineHeight', 'color', 'textAlign', 'textDecoration', 'textTransform', 'letterSpacing', 'wordSpacing', 'wordBreak', 'overflowWrap', 'textIndent', 'verticalAlign'],
   'Background': ['background', 'backgroundColor', 'backgroundImage', 'backgroundSize', 'backgroundPosition', 'backgroundRepeat', 'opacity'],
-  'Borders': ['border', 'borderWidth', 'borderStyle', 'borderColor', 'borderTop', 'borderRight', 'borderBottom', 'borderLeft', 'borderRadius', 'borderTopLeftRadius', 'borderTopRightRadius', 'borderBottomLeftRadius', 'borderBottomRightRadius'],
+  'Borders': ['borderRadius', 'borderTopLeftRadius', 'borderTopRightRadius', 'borderBottomLeftRadius', 'borderBottomRightRadius', 'border', 'borderWidth', 'borderStyle', 'borderColor', 'borderTop', 'borderRight', 'borderBottom', 'borderLeft'],
   'Outline': ['outline', 'outlineWidth', 'outlineStyle', 'outlineColor', 'outlineOffset'],
   'Effects': ['boxShadow', 'textShadow', 'filter', 'backdropFilter', 'transform', 'transformOrigin', 'transition', 'animation', 'backfaceVisibility', 'mixBlendMode', 'clipPath'],
   'Overflow': ['overflow', 'overflowX', 'overflowY', 'whiteSpace', 'textOverflow', 'visibility', 'content'],
@@ -452,6 +453,165 @@ export function getPropertyGroup(propertyName: string): string {
   return 'Other';
 }
 
+/**
+ * Subset of CSS properties shown as "always-visible" rows in the visual style
+ * editor mode (Webflow-like). Each property here renders even when unset, so
+ * the user can see at a glance which properties are available and click an
+ * empty row to start typing a value.
+ *
+ * Keys must be group names from CSS_PROPERTY_GROUPS so the visual editor can
+ * reuse the same group headers as list mode.
+ */
+export const VISUAL_MODE_PROPERTIES: Record<string, string[]> = {
+  'Layout': ['display'],
+  'Grid': ['gridTemplateColumns'],
+  'Flexbox': ['flexDirection', 'flexWrap', 'justifyContent', 'alignItems', 'gap', 'flexGrow', 'flexShrink', 'flexBasis'],
+  'Spacing': ['margin', 'marginTop', 'marginRight', 'marginBottom', 'marginLeft', 'padding', 'paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft'],
+  'Size': ['width', 'height', 'minWidth', 'minHeight', 'maxWidth', 'maxHeight'],
+  'Position': ['position', 'top', 'right', 'bottom', 'left', 'zIndex'],
+  'Typography': ['fontFamily', 'fontWeight', 'fontSize', 'lineHeight', 'color', 'letterSpacing', 'textAlign', 'textTransform', 'textDecoration'],
+  'Background': ['backgroundColor', 'backgroundImage', 'backgroundSize', 'backgroundPosition', 'backgroundRepeat', 'opacity'],
+  'Borders': ['borderRadius', 'borderWidth', 'borderStyle', 'borderColor'],
+  'Effects': ['boxShadow', 'transform', 'transition', 'filter'],
+  'Overflow': ['overflow', 'whiteSpace'],
+  'Interaction': ['cursor', 'pointerEvents'],
+};
+
+const VISUAL_MODE_PROPERTIES_SET = new Set(
+  Object.values(VISUAL_MODE_PROPERTIES).flat()
+);
+
+/**
+ * True if `prop` belongs to the always-visible visual-mode list.
+ */
+export function isVisualModeProperty(prop: string): boolean {
+  return VISUAL_MODE_PROPERTIES_SET.has(prop);
+}
+
+/**
+ * Context used by visual-mode visibility rules. Captures everything a rule
+ * needs to decide whether a property row is meaningful for the currently
+ * selected element. Built once per render in `StyleEditor`.
+ */
+export interface VisualModeRuleContext {
+  /** Effective `display` of the selected element — getComputedStyle().display
+   *  with declared (instance/inherited/effective) merge as fallback when the
+   *  iframe hasn't loaded yet. Defaults to 'block'. */
+  display: string;
+  /** Effective `display` of the DOM parent — used for flex/grid item props
+   *  whose applicability depends on the parent's layout mode. '' when no
+   *  parent is reachable (root element, iframe missing). */
+  parentDisplay: string;
+  /** Effective `position` of the selected element. Defaults to 'static'. */
+  position: string;
+  /** Lowercase HTML tag name of the selected element ('div', 'img', 'ul'…). */
+  tagName: string;
+  /** True if any of paddingTop / paddingRight / paddingBottom / paddingLeft
+   *  is set anywhere in the cascade (instance + inherited + effective).
+   *  When true, the panel shows the four longhand rows and hides `padding`. */
+  hasPaddingLonghand: boolean;
+  /** Same as `hasPaddingLonghand` for the four `margin*` longhands. */
+  hasMarginLonghand: boolean;
+  /** True if `backgroundImage` (or the `background` shorthand) is set anywhere
+   *  in the cascade. Drives visibility of background-image-only properties
+   *  like `backgroundPosition` / `backgroundSize` / `backgroundRepeat`. */
+  hasBackgroundImage: boolean;
+}
+
+export type VisualModeRule = (ctx: VisualModeRuleContext) => boolean;
+
+const isFlexDisplay = (d: string) => d === 'flex' || d === 'inline-flex';
+const isGridDisplay = (d: string) => d === 'grid' || d === 'inline-grid';
+const isListTag = (t: string) => t === 'ul' || t === 'ol' || t === 'li';
+const isMediaTag = (t: string) => t === 'img' || t === 'video';
+
+/**
+ * Visibility rules for the visual-mode style panel. Each entry is a predicate
+ * that returns true when the row should be rendered for the current element
+ * context. Properties without an entry are always visible. Properties that
+ * are *explicitly set* on the element bypass these rules (the explicit-value
+ * override is enforced by the caller, not here).
+ */
+export const VISUAL_MODE_RULES: Record<string, VisualModeRule> = {
+  // Flex/Grid CONTAINER props — own display must be flex/grid.
+  flexDirection:       ctx => isFlexDisplay(ctx.display),
+  flexWrap:            ctx => isFlexDisplay(ctx.display),
+  justifyContent:      ctx => isFlexDisplay(ctx.display) || isGridDisplay(ctx.display),
+  alignItems:          ctx => isFlexDisplay(ctx.display) || isGridDisplay(ctx.display),
+  alignContent:        ctx => isFlexDisplay(ctx.display) || isGridDisplay(ctx.display),
+  gap:                 ctx => isFlexDisplay(ctx.display) || isGridDisplay(ctx.display),
+  rowGap:              ctx => isFlexDisplay(ctx.display) || isGridDisplay(ctx.display),
+  columnGap:           ctx => isFlexDisplay(ctx.display) || isGridDisplay(ctx.display),
+  gridTemplateColumns: ctx => isGridDisplay(ctx.display),
+  gridTemplateRows:    ctx => isGridDisplay(ctx.display),
+  gridTemplateAreas:   ctx => isGridDisplay(ctx.display),
+  gridGap:             ctx => isGridDisplay(ctx.display),
+  gridAutoFlow:        ctx => isGridDisplay(ctx.display),
+  gridAutoColumns:     ctx => isGridDisplay(ctx.display),
+  gridAutoRows:        ctx => isGridDisplay(ctx.display),
+  justifyItems:        ctx => isGridDisplay(ctx.display),
+  placeItems:          ctx => isGridDisplay(ctx.display),
+  placeContent:        ctx => isGridDisplay(ctx.display),
+
+  // Flex/Grid ITEM props — PARENT display must be flex/grid.
+  flex:        ctx => isFlexDisplay(ctx.parentDisplay),
+  flexFlow:    ctx => isFlexDisplay(ctx.parentDisplay),
+  flexGrow:    ctx => isFlexDisplay(ctx.parentDisplay),
+  flexShrink:  ctx => isFlexDisplay(ctx.parentDisplay),
+  flexBasis:   ctx => isFlexDisplay(ctx.parentDisplay),
+  alignSelf:   ctx => isFlexDisplay(ctx.parentDisplay) || isGridDisplay(ctx.parentDisplay),
+  justifySelf: ctx => isGridDisplay(ctx.parentDisplay),
+  placeSelf:   ctx => isGridDisplay(ctx.parentDisplay),
+  order:       ctx => isFlexDisplay(ctx.parentDisplay) || isGridDisplay(ctx.parentDisplay),
+  gridArea:    ctx => isGridDisplay(ctx.parentDisplay),
+  gridColumn:  ctx => isGridDisplay(ctx.parentDisplay),
+  gridRow:     ctx => isGridDisplay(ctx.parentDisplay),
+
+  // Position-dependent inset properties.
+  top:    ctx => ctx.position !== 'static',
+  right:  ctx => ctx.position !== 'static',
+  bottom: ctx => ctx.position !== 'static',
+  left:   ctx => ctx.position !== 'static',
+  inset:  ctx => ctx.position !== 'static',
+  zIndex: ctx => ctx.position !== 'static',
+
+  // Tag-based.
+  objectFit:         ctx => isMediaTag(ctx.tagName),
+  objectPosition:    ctx => isMediaTag(ctx.tagName),
+  listStyle:         ctx => isListTag(ctx.tagName),
+  listStyleType:     ctx => isListTag(ctx.tagName),
+  listStylePosition: ctx => isListTag(ctx.tagName),
+
+  // Padding/margin shorthand-vs-longhand auto-toggle.
+  // When ANY longhand is set, hide shorthand; otherwise hide longhands.
+  padding:       ctx => !ctx.hasPaddingLonghand,
+  paddingTop:    ctx => ctx.hasPaddingLonghand,
+  paddingRight:  ctx => ctx.hasPaddingLonghand,
+  paddingBottom: ctx => ctx.hasPaddingLonghand,
+  paddingLeft:   ctx => ctx.hasPaddingLonghand,
+  margin:        ctx => !ctx.hasMarginLonghand,
+  marginTop:     ctx => ctx.hasMarginLonghand,
+  marginRight:   ctx => ctx.hasMarginLonghand,
+  marginBottom:  ctx => ctx.hasMarginLonghand,
+  marginLeft:    ctx => ctx.hasMarginLonghand,
+
+  // Background-image-only props — meaningless without a background image.
+  backgroundPosition: ctx => ctx.hasBackgroundImage,
+  backgroundSize:     ctx => ctx.hasBackgroundImage,
+  backgroundRepeat:   ctx => ctx.hasBackgroundImage,
+};
+
+/**
+ * True if `prop` should be visible in the visual-mode panel given `ctx`.
+ * Properties without an entry in `VISUAL_MODE_RULES` default to visible.
+ * Callers are responsible for the explicit-value override (a property that
+ * the user has set must remain visible regardless of the rule outcome).
+ */
+export function isVisualModeRowVisible(prop: string, ctx: VisualModeRuleContext): boolean {
+  const rule = VISUAL_MODE_RULES[prop];
+  return rule ? rule(ctx) : true;
+}
+
 /**
  * Check if property matches the abbreviation pattern
  * For example, "bC" matches "backgroundColor" (b→b, C→C capital letter)
@@ -563,3 +723,33 @@ export function filterPropertyValues(propertyName: string, input: string): strin
 export function getPropertyType(propertyName: string): 'string' | 'select' | 'boolean' | 'number' | undefined {
   return CSS_PROPERTIES_DEFINITION[propertyName]?.type;
 }
+
+/**
+ * CSS properties whose numeric values are unitless by spec — `font-weight: 400`,
+ * `line-height: 1.5`, `opacity: 0.8`, `z-index: 10`, etc. The auto-px commit
+ * normalizer must NOT append `px` to bare numbers for these.
+ */
+export const UNITLESS_PROPERTIES: ReadonlySet<string> = new Set([
+  'fontWeight', 'lineHeight',
+  'opacity', 'fillOpacity', 'strokeOpacity', 'stopOpacity',
+  'zIndex', 'order',
+  'flexGrow', 'flexShrink', 'flex',
+  'columnCount', 'columns', 'tabSize', 'orphans', 'widows',
+  'gridRow', 'gridColumn', 'gridRowStart', 'gridRowEnd',
+  'gridColumnStart', 'gridColumnEnd',
+  'animationIterationCount',
+  'aspectRatio',
+  'scale',
+]);
+
+/**
+ * Whether bare numeric values for `propertyName` should be treated as pixels at
+ * commit time (e.g. typing `52` for `width` becomes `52px`). Unitless props,
+ * `select`/`boolean` keyword props, and existing `number`-typed entries return false.
+ */
+export function appendsPxByDefault(propertyName: string): boolean {
+  if (UNITLESS_PROPERTIES.has(propertyName)) return false;
+  const def = CSS_PROPERTIES_DEFINITION[propertyName];
+  if (def?.type === 'select' || def?.type === 'boolean' || def?.type === 'number') return false;
+  return true;
+}

package/lib/shared/interfaces/contentProvider.ts

@@ -99,26 +99,59 @@ export interface CMSSchemaInfo {
  * CMS Provider Interface
  * Abstracts CMS data loading from the underlying storage mechanism
  * (follows same pattern as PageProvider)
+ *
+ * Draft model: each item may have a published version (`{filename}.json`)
+ * and/or a draft version (`{filename}.draft.json`). The published-facing
+ * methods (`getItems`, `getItemByFilename`, `getItemBySlug`, `getItemById`)
+ * return ONLY published items. Draft access goes through the `*Draft`
+ * methods. SSR and the static export must never read drafts.
  */
 export interface CMSProvider {
   /** Load all CMS schemas (extracted from page files with source: 'cms') */
   getAllSchemas(): Promise<Map<string, CMSSchemaInfo>>;
 
-  /** Load all items for a collection */
+  /** Load all PUBLISHED items for a collection */
   getItems(collection: string): Promise<CMSItem[]>;
 
-  /** Get single item by filename (stable identifier) */
+  /** Get single PUBLISHED item by filename (stable identifier) */
   getItemByFilename(collection: string, filename: string): Promise<CMSItem | null>;
 
-  /** Get single item by slug (backward compat - maps to filename lookup) */
+  /** Get single PUBLISHED item by slug (backward compat - maps to filename lookup) */
   getItemBySlug(collection: string, slug: string): Promise<CMSItem | null>;
 
-  /** Get single item by ID */
+  /** Get single PUBLISHED item by ID */
   getItemById(collection: string, id: string): Promise<CMSItem | null>;
 
-  /** Save item (for editor) - saves to cms/<collection>/<_filename>.json */
+  /** Save item (published) - writes to cms/<collection>/<_filename>.json */
   saveItem(collection: string, item: CMSItem): Promise<void>;
 
-  /** Delete item by filename */
+  /**
+   * Delete item by filename. Removes both the published file and any
+   * accompanying draft file.
+   */
   deleteItem(collection: string, filename: string): Promise<void>;
+
+  // ---- Draft-version methods --------------------------------------------
+
+  /** Get the draft version of an item, or null if no draft exists */
+  getDraft(collection: string, filename: string): Promise<CMSItem | null>;
+
+  /** List all drafts in a collection (used by Studio item list for badges) */
+  getAllDrafts(collection: string): Promise<CMSItem[]>;
+
+  /** Whether a draft file exists for the given filename */
+  hasDraft(collection: string, filename: string): Promise<boolean>;
+
+  /** Save the draft version of an item to cms/<collection>/<_filename>.draft.json */
+  saveDraft(collection: string, item: CMSItem): Promise<void>;
+
+  /** Discard the draft version of an item (no-op if no draft exists) */
+  discardDraft(collection: string, filename: string): Promise<void>;
+
+  /**
+   * Promote a draft to published. Reads `{filename}.draft.json`, writes its
+   * content to `{filename}.json`, then removes the draft file.
+   * Returns the newly published item. Throws if no draft exists.
+   */
+  publishDraft(collection: string, filename: string): Promise<CMSItem>;
 }

package/lib/shared/pathSecurity.ts

@@ -93,3 +93,19 @@ export const SAFE_IDENTIFIER_REGEX = /^[a-zA-Z0-9_-]+$/;
 export function isValidIdentifier(name: string): boolean {
   return SAFE_IDENTIFIER_REGEX.test(name);
 }
+
+/**
+ * Suffix used for CMS draft files: `{filename}.draft.json`. The provider must
+ * never accept user-supplied filenames ending in `.draft`, because that would
+ * clash with the draft-suffix convention and let a user shadow another item's
+ * draft file.
+ */
+export const CMS_DRAFT_SUFFIX = '.draft';
+
+/**
+ * True when a user-supplied CMS filename collides with the reserved `.draft`
+ * suffix. Use as a hard reject in CMS provider write paths.
+ */
+export function isReservedDraftFilename(filename: string): boolean {
+  return filename.endsWith(CMS_DRAFT_SUFFIX);
+}