@sanmid/flux 0.1.5 → 0.1.9

package/dist/index.d.cts

@@ -0,0 +1,240 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type DesignEditorProps = {
+    /**
+     * When true, the editor mounts in production builds.
+     * Default is **development only** (`process.env.NODE_ENV === "development"`).
+     */
+    force?: boolean;
+    /**
+     * Classic margin / border / padding overlay bands on the selected node.
+     * Default **false** — only the mint selection ring is shown unless you opt in.
+     */
+    showBoxModel?: boolean;
+    /**
+     * When the overlay is active, block default actions on interactive page nodes (buttons, links, inputs, …)
+     * via capture-phase listeners. Opt-in for host apps (e.g. playgrounds); default **false**.
+     */
+    blockPageInteractions?: boolean;
+};
+/**
+ * Visual design editor overlay. **Does not render in production** unless `force` is set.
+ */
+declare function DesignEditor({ force, showBoxModel, blockPageInteractions, }: DesignEditorProps): react_jsx_runtime.JSX.Element | null;
+
+/** Persisted for copy prompt after a successful DOM reorder. */
+type FluxStructuralReorder = {
+    type: "reorder";
+    containerSelector: string;
+    containerComponents: string[];
+    originalOrder: string[];
+    newOrder: string[];
+    childrenType: "array" | "static";
+    containerSourceFile: {
+        fileName: string;
+        lineNumber: number;
+        columnNumber?: number;
+    } | null;
+    childSources?: {
+        label: string;
+        sourceFile: {
+            fileName: string;
+            lineNumber: number;
+            columnNumber?: number;
+        };
+    }[];
+    timestamp: number;
+};
+
+/**
+ * Live preview engine using Constructable Stylesheets when supported,
+ * otherwise a single <style> tag in document.head.
+ *
+ * Applies CSS changes without mutating the host element's inline styles.
+ */
+interface AppliedRule {
+    selector: string;
+    property: string;
+    value: string;
+}
+declare class PreviewEngine {
+    private sheet;
+    private fallbackStyle;
+    private rules;
+    private attached;
+    constructor();
+    attach(): void;
+    detach(): void;
+    applyChange(selector: string, property: string, value: string): void;
+    removeChange(selector: string, property: string): void;
+    removeAllChanges(selector: string): void;
+    clearAll(): void;
+    getChanges(): readonly AppliedRule[];
+    /** Last preview value applied for this selector + property (e.g. `100%` when Fill), or undefined. */
+    getPreviewValue(selector: string, property: string): string | undefined;
+    destroy(): void;
+    private flush;
+}
+/**
+ * Generate a unique CSS selector for an element using @medv/finder.
+ * Falls back to a manual path if finder throws (e.g., SVG elements).
+ */
+declare function getUniqueSelector(el: Element): string;
+/**
+ * `parent > :nth-child(n)` so preview rules (e.g. `order`) target the exact direct child.
+ * Finder-only selectors often collide for sibling elements; this stays stable for flex/grid children.
+ */
+declare function getDirectChildSelector(parent: Element, child: Element): string;
+/**
+ * Selector used for {@link PreviewEngine} rules. Verifies each candidate with
+ * `querySelectorAll(sel).length === 1` and that node is `el`, so injected rules
+ * cannot hit multiple elements (e.g. all `button`s). Last resort: a temporary
+ * `data-flux-preview-target` id — call {@link removePreviewTargetAttribute} when deselecting.
+ */
+declare function getReliableSelectorForPreview(el: Element): {
+    selector: string;
+    usedAttrFallback: boolean;
+};
+declare function removePreviewTargetAttribute(el: Element | null | undefined): void;
+
+interface StyleSnapshot {
+    fontFamily: string;
+    fontSize: string;
+    fontWeight: string;
+    lineHeight: string;
+    letterSpacing: string;
+    color: string;
+    textAlign: string;
+    width: string;
+    height: string;
+    padding: string;
+    margin: string;
+    paddingTop: string;
+    paddingRight: string;
+    paddingBottom: string;
+    paddingLeft: string;
+    marginTop: string;
+    marginRight: string;
+    marginBottom: string;
+    marginLeft: string;
+    /** CSS `position` (static, relative, absolute, fixed, sticky). */
+    position: string;
+    /** Inset offsets for positioned layout (`top` / `right` / `bottom` / `left`). */
+    top: string;
+    right: string;
+    bottom: string;
+    left: string;
+    /** CSS `align-self` — item alignment in flex/grid. */
+    alignSelf: string;
+    /** CSS `justify-self` — grid item alignment on row axis. */
+    justifySelf: string;
+    overflow: string;
+    display: string;
+    flexDirection: string;
+    justifyContent: string;
+    alignItems: string;
+    gap: string;
+    rowGap: string;
+    columnGap: string;
+    gridTemplateColumns: string;
+    gridTemplateRows: string;
+    backgroundColor: string;
+    /** Computed `background-image` (gradients count as fill for `hasFill`-style checks). */
+    backgroundImage: string;
+    borderTopWidth: string;
+    borderRightWidth: string;
+    borderBottomWidth: string;
+    borderLeftWidth: string;
+    borderTopLeftRadius: string;
+    borderTopRightRadius: string;
+    borderBottomRightRadius: string;
+    borderBottomLeftRadius: string;
+    borderTopColor: string;
+    borderRightColor: string;
+    borderBottomColor: string;
+    borderLeftColor: string;
+    borderTopStyle: string;
+    borderRightStyle: string;
+    borderBottomStyle: string;
+    borderLeftStyle: string;
+    borderColor: string;
+    borderRadius: string;
+    borderStyle: string;
+    boxShadow: string;
+    opacity: string;
+}
+type DesignEditorElement = Element & {
+    style: CSSStyleDeclaration;
+};
+declare function isStyleableElement(target: EventTarget | null): target is DesignEditorElement;
+declare function getComputedSnapshot(el: Element): StyleSnapshot;
+declare function getElementPath(el: Element): string;
+declare function getElementSelector(el: Element): string;
+
+/**
+ * Border-box dimensions in viewport CSS pixels, rounded for the overlay label.
+ */
+declare function formatSelectionDimensions(width: number, height: number): string;
+
+/**
+ * React fiber traversal for extracting component hierarchy and source file locations.
+ * Works with React 18+ dev builds that attach `__reactFiber$` to DOM nodes.
+ */
+interface ReactComponentInfo {
+    components: string[];
+    sourceFile: {
+        fileName: string;
+        lineNumber: number;
+        columnNumber?: number;
+    } | null;
+}
+declare function getExactSourceLocation(el: Element): string | null;
+declare function getReactComponentStack(el: Element): string | null;
+declare function getReactComponentInfo(el: Element): ReactComponentInfo;
+
+/**
+ * Lazy token scanner — walks document.styleSheets to discover CSS custom properties
+ * and utility class tokens. Scans on-demand per category, cached until stylesheet count changes.
+ */
+type TokenCategory = "colors" | "spacing" | "typography" | "borders" | "effects" | "layout";
+type CssFramework = "tailwind" | "css-modules" | "custom" | "unknown";
+interface DesignToken {
+    className: string;
+    property: string;
+    value: string;
+    category: TokenCategory;
+}
+interface CssVariable {
+    name: string;
+    value: string;
+    category: TokenCategory;
+}
+interface TokenScanResult {
+    tokens: DesignToken[];
+    variables: CssVariable[];
+    framework: CssFramework;
+}
+declare function scanTokens(): TokenScanResult;
+/** One-line summary for AI prompts (design-token preamble). */
+declare function summarizeTokenSystem(): string | null;
+declare function detectFramework(): CssFramework;
+declare function getTokensForProperty(cssProperty: string): DesignToken[];
+declare function getVariablesForProperty(cssProperty: string): CssVariable[];
+/**
+ * Variables that appear in real CSS rules for this property first, then category fallback.
+ */
+declare function getVariablesForPropertySmart(cssPropertyKebab: string): CssVariable[];
+
+/**
+ * Maps CSS property names (kebab-case) to custom property names that appear
+ * in stylesheet values via var(--name), so pickers can prefer vars actually
+ * used for that property in the host app.
+ */
+declare function invalidateVariableUsageCache(): void;
+/** Custom property names (--foo) that appear in rules for this CSS property. */
+declare function getVariablesUsedForCssProperty(kebabProperty: string): string[];
+
+/** Collect `font-family` values from parsed stylesheets (best-effort; skips cross-origin). */
+declare function scanStylesheetFontFamilies(): string[];
+
+export { type CssFramework, type CssVariable, DesignEditor, type DesignEditorElement, type DesignEditorProps, type DesignToken, type FluxStructuralReorder, PreviewEngine, type ReactComponentInfo, type StyleSnapshot, type TokenCategory, type TokenScanResult, detectFramework, formatSelectionDimensions, getComputedSnapshot, getDirectChildSelector, getElementPath, getElementSelector, getExactSourceLocation, getReactComponentInfo, getReactComponentStack, getReliableSelectorForPreview, getTokensForProperty, getUniqueSelector, getVariablesForProperty, getVariablesForPropertySmart, getVariablesUsedForCssProperty, invalidateVariableUsageCache, isStyleableElement, removePreviewTargetAttribute, scanStylesheetFontFamilies, scanTokens, summarizeTokenSystem };