@aglyn/besigner-ui 1.0.0-beta.143

package/src/lib/components/custom-css-form.component.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type * as Aglyn from '@aglyn/aglyn';
+import type { SxBreakpoint } from '../utils/responsive-sx';
+/** Parses `prop: value;` CSS declarations into a JSS record (AGL-332). */
+export declare function parseCssDeclarations(css: string): Record<string, string>;
+/**
+ * The scalar declarations the Builder rows and the CSS tab show for `sx`,
+ * named in the Styles panel's own spelling (AGL-2390).
+ *
+ * MUI honours two names for the same declaration, and every other control
+ * in this panel is named for the CSS longhand (AGL-2207). Listing the raw
+ * keys made this form the one place that said `bgcolor` where the Colors
+ * group said `backgroundColor` and BoxStyler said `paddingTop` — the same
+ * node, two vocabularies, and the author with no way to tell that the two
+ * rows were one declaration. The expansion is a pure renaming of what
+ * already renders (order preserved, non-atomic values left alone), and it
+ * is what makes the row's × and the CSS tab's clear reach the key that is
+ * actually painting.
+ *
+ * The JSS tab deliberately does NOT go through here: it edits the stored
+ * document verbatim, which is the escape hatch for everything the named
+ * controls cannot express.
+ */
+export declare function customCssDeclarations(sx: Record<string, any> | undefined, breakpoint: SxBreakpoint | null): Array<{
+    property: string;
+    value: string;
+}>;
+/** Serializes scalar sx entries into CSS declarations for the CSS tab. */
+export declare function serializeCssDeclarations(sx: Record<string, any> | undefined, breakpoint: SxBreakpoint | null): string;
+/**
+ * The declaration(s) one named property writes, in the panel's spelling.
+ *
+ * The property field is free-solo and the CSS tab takes any declaration, so
+ * an author can type `bgcolor` or `py` at any time — this form is the one
+ * seam in the product where a fresh alias can still enter a document. It
+ * resolves the name the same way {@link expandSxAliases} resolves a stored
+ * one, so what the author typed and what the panel reads back agree.
+ *
+ * A value the expansion cannot carry per-side — `p: '10px 20px'`, the CSS
+ * shorthand's own syntax — keeps the name the author gave it rather than
+ * being copied onto four longhands CSS would drop. Clearing always expands,
+ * because a cleared alias has to take every longhand it was painting with
+ * it.
+ */
+export declare function canonicalCssPartial(property: string, value: string | undefined): Record<string, unknown>;
+/**
+ * Applies custom-CSS edits to `sx` — the write both the Builder rows and
+ * the CSS tab's Apply go through (AGL-2390).
+ *
+ * Routed through the Styles panel's own write seam so this form cannot
+ * drift from it again: {@link applyStylePartialToSx} expands the alias keys
+ * the edit COLLIDES with before writing, which is what makes clearing a
+ * declaration actually clear (deleting `backgroundColor` while a `bgcolor`
+ * underneath keeps painting is AGL-2207's sharper failure) and what stops a
+ * write leaving two spellings of one declaration in the record.
+ *
+ * Scheme-agnostic (`null`): this form has always written the base slice,
+ * and the dark-preview scoping belongs to the named color fields.
+ */
+export declare function applyCustomCssEdits(sx: Record<string, any> | undefined, edits: Record<string, string | undefined>, breakpoint: SxBreakpoint | null): Record<string, any>;
+/** Drops every pending draft — test seam, and a hard reset for the canvas. */
+export declare function resetPendingCustomCssDrafts(): void;
+/**
+ * Why a JSS buffer cannot be applied, or `null` when it is ready
+ * (AGL-2486). Rendered live as the author types, so "nothing happened when
+ * I pressed Apply" is never the first sign that the text does not parse.
+ *
+ * Mid-edit JSON is TRANSIENTLY invalid by nature — `{"a": 1,` is what every
+ * new property looks like a keystroke before it is finished — so this is a
+ * hint, never a block on typing and never a reason to touch the document.
+ *
+ * An empty buffer is called out rather than treated as `{}`: `JSON.parse`
+ * would need a fallback to accept it at all, and silently reading "" as
+ * "delete every style on this element" is the most destructive thing this
+ * panel could do with an accidental Select-All. Clearing all styles stays
+ * available, spelled `{}`, which nobody types by accident.
+ */
+export declare function jsonDraftProblem(text: string): string | null;
+export interface CustomCssFormProps {
+    node?: Aglyn.NodeSchema;
+    /** Active artboard breakpoint; builder/CSS edits scope to it (AGL-333). */
+    breakpoint: SxBreakpoint | null;
+    /**
+     * Which `styleOverrides` slice to edit on a component instance
+     * (AGL-1332) — the Styles panel's current style target. Ignored for a
+     * plain node; defaults to the component root.
+     */
+    overrideKey?: string;
+}
+/**
+ * Custom CSS for the selected element's `sx` (AGL-332): a friendly
+ * builder (property + value rows), a raw CSS mode, and a raw JSS/JSON
+ * mode. Builder and CSS edits respect the active breakpoint scope; the
+ * JSON mode edits the full sx document (including responsive objects and
+ * nested selectors) verbatim.
+ */
+export declare const CustomCssForm: ((props: CustomCssFormProps) => import("react").JSX.Element) & {
+    displayName: string;
+};
+export default CustomCssForm;