@marianmeres/stuic 3.152.0 → 3.154.0

package/dist/components/FieldsBuilder/index.css

@@ -0,0 +1,187 @@
+/* ============================================================================
+   FIELDS BUILDER COMPONENT TOKENS
+   Override globally: :root { --stuic-fields-builder-row-border: red; }
+   Override locally:  <FieldsBuilder style="--stuic-fields-builder-chip-bg: ..." />
+   ============================================================================ */
+
+/* prettier-ignore */
+:root {
+	--stuic-fields-builder-row-border: var(--stuic-color-border);
+	--stuic-fields-builder-row-toggle-bg-hover: var(--stuic-color-muted);
+	--stuic-fields-builder-key-text: var(--stuic-color-muted-foreground);
+	--stuic-fields-builder-chip-bg: var(--stuic-color-muted);
+	--stuic-fields-builder-chip-text: var(--stuic-color-muted-foreground);
+	--stuic-fields-builder-muted-text: var(--stuic-color-muted-foreground);
+	--stuic-fields-builder-warning-text: var(--stuic-color-surface-warning-foreground);
+	--stuic-fields-builder-error-text: var(--stuic-color-destructive);
+	--stuic-fields-builder-drop-indicator-color: var(--stuic-color-primary);
+	--stuic-fields-builder-drop-indicator-height: 2px;
+	--stuic-fields-builder-row-opacity-dragging: 0.4;
+	--stuic-fields-builder-row-opacity-deleted: 0.55;
+	--stuic-fields-builder-preview-border: var(--stuic-color-border);
+}
+
+@layer components {
+	/* =============================================================================
+	   ROWS
+	   ============================================================================= */
+
+	.stuic-fields-builder .fb-row-divider {
+		border-top: 1px solid var(--stuic-fields-builder-row-border);
+	}
+
+	.stuic-fields-builder .fb-row[data-dragging] {
+		opacity: var(--stuic-fields-builder-row-opacity-dragging);
+	}
+
+	.stuic-fields-builder .fb-row[data-drop-position="before"] {
+		box-shadow: inset 0 var(--stuic-fields-builder-drop-indicator-height) 0
+			var(--stuic-fields-builder-drop-indicator-color);
+	}
+
+	.stuic-fields-builder .fb-row[data-drop-position="after"] {
+		box-shadow: inset 0 calc(-1 * var(--stuic-fields-builder-drop-indicator-height)) 0
+			var(--stuic-fields-builder-drop-indicator-color);
+	}
+
+	.stuic-fields-builder .fb-row-deleted .fb-row-header {
+		opacity: var(--stuic-fields-builder-row-opacity-deleted);
+	}
+
+	.stuic-fields-builder .fb-row-deleted .fb-row-label {
+		text-decoration: line-through;
+	}
+
+	/* =============================================================================
+	   ROW HEADER
+	   ============================================================================= */
+
+	.stuic-fields-builder .fb-row-header {
+		padding-block: calc(var(--spacing) * 1);
+	}
+
+	.stuic-fields-builder .fb-row-toggle {
+		padding: calc(var(--spacing) * 1.5) calc(var(--spacing) * 1);
+		transition: background var(--stuic-transition);
+	}
+
+	.stuic-fields-builder .fb-row-toggle:hover:not(:disabled) {
+		background: var(--stuic-fields-builder-row-toggle-bg-hover);
+	}
+
+	.stuic-fields-builder .fb-row-toggle:disabled {
+		cursor: default;
+	}
+
+	.stuic-fields-builder .fb-row-label {
+		font-weight: 500;
+	}
+
+	.stuic-fields-builder .fb-row-required {
+		opacity: 0.5;
+	}
+
+	.stuic-fields-builder .fb-key {
+		font-family: var(--font-mono);
+		font-size: var(--text-xs);
+		color: var(--stuic-fields-builder-key-text);
+	}
+
+	.stuic-fields-builder .fb-chip {
+		background: var(--stuic-fields-builder-chip-bg);
+		color: var(--stuic-fields-builder-chip-text);
+		font-size: var(--text-xs);
+		padding: calc(var(--spacing) * 0.5) calc(var(--spacing) * 1.5);
+		border-radius: var(--stuic-fields-builder-chip-radius, var(--stuic-radius));
+		white-space: nowrap;
+	}
+
+	.stuic-fields-builder .fb-chip-warning {
+		color: var(--stuic-fields-builder-warning-text);
+	}
+
+	.stuic-fields-builder .fb-chevron {
+		opacity: 0.5;
+	}
+
+	.stuic-fields-builder .fb-handle {
+		cursor: grab;
+		opacity: 0.4;
+		touch-action: none;
+	}
+
+	.stuic-fields-builder .fb-handle:hover {
+		opacity: 1;
+	}
+
+	.stuic-fields-builder .fb-handle-spacer {
+		width: 16px;
+	}
+
+	/* =============================================================================
+	   ROW BODY (expanded editor)
+	   ============================================================================= */
+
+	.stuic-fields-builder .fb-row-body {
+		display: flex;
+		flex-direction: column;
+		gap: calc(var(--spacing) * 3);
+		padding: calc(var(--spacing) * 1) calc(var(--spacing) * 2) calc(var(--spacing) * 3)
+			calc(var(--spacing) * 2);
+	}
+
+	.stuic-fields-builder .fb-sub-label {
+		display: block;
+		font-size: var(--text-xs);
+		font-weight: 500;
+		color: var(--stuic-fields-builder-muted-text);
+		margin-bottom: calc(var(--spacing) * 0.5);
+	}
+
+	.stuic-fields-builder .fb-hint {
+		color: var(--stuic-fields-builder-muted-text);
+	}
+
+	.stuic-fields-builder .fb-error-text {
+		color: var(--stuic-fields-builder-error-text);
+	}
+
+	.stuic-fields-builder .fb-warning-text {
+		color: var(--stuic-fields-builder-warning-text);
+	}
+
+	.stuic-fields-builder .fb-advanced-toggle {
+		color: var(--stuic-fields-builder-muted-text);
+		transition: color var(--stuic-transition);
+	}
+
+	.stuic-fields-builder .fb-advanced-toggle:hover {
+		color: var(--stuic-color-foreground);
+	}
+
+	/* =============================================================================
+	   OPTIONS EDITOR
+	   ============================================================================= */
+
+	.stuic-fields-builder .fb-option-divider {
+		border-top: 1px dashed var(--stuic-fields-builder-row-border);
+	}
+
+	/* =============================================================================
+	   PREVIEW PANE
+	   ============================================================================= */
+
+	.stuic-fields-builder .fb-preview-side {
+		border-left: 1px solid var(--stuic-fields-builder-preview-border);
+	}
+
+	.stuic-fields-builder .fb-preview-below {
+		border-top: 1px solid var(--stuic-fields-builder-preview-border);
+	}
+
+	.stuic-fields-builder .fb-preview-title {
+		color: var(--stuic-fields-builder-muted-text);
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+	}
+}

package/dist/components/FieldsBuilder/index.d.ts

@@ -0,0 +1,5 @@
+export { default as FieldsBuilder, type Props as FieldsBuilderProps, } from "./FieldsBuilder.svelte";
+export type { FieldDef, FieldLock, FieldOptionDef, FieldTypeDef, FieldTypeExtraDef, LocalizedText, } from "./types.js";
+export { DEFAULT_FIELD_TYPES as FIELDS_BUILDER_DEFAULT_TYPES, DEFAULT_KEY_PATTERN as FIELDS_BUILDER_DEFAULT_KEY_PATTERN, getLocalizedText, slugifyKey, uniqueKey, validateFieldDefs, type FieldDefRowErrors, type FieldDefsValidationResult, type ValidateFieldDefsOptions, } from "./utils.js";
+export { createFieldsBuilderT, FIELDS_BUILDER_MESSAGES_EN, type FieldsBuilderMessageKey, type FieldsBuilderMessages, } from "./i18n.js";
+export { FIELDS_BUILDER_MESSAGES_SK, FIELDS_BUILDER_DEFAULT_TYPES_SK, } from "./i18n-sk.js";

package/dist/components/FieldsBuilder/index.js

@@ -0,0 +1,4 @@
+export { default as FieldsBuilder, } from "./FieldsBuilder.svelte";
+export { DEFAULT_FIELD_TYPES as FIELDS_BUILDER_DEFAULT_TYPES, DEFAULT_KEY_PATTERN as FIELDS_BUILDER_DEFAULT_KEY_PATTERN, getLocalizedText, slugifyKey, uniqueKey, validateFieldDefs, } from "./utils.js";
+export { createFieldsBuilderT, FIELDS_BUILDER_MESSAGES_EN, } from "./i18n.js";
+export { FIELDS_BUILDER_MESSAGES_SK, FIELDS_BUILDER_DEFAULT_TYPES_SK, } from "./i18n-sk.js";

package/dist/components/FieldsBuilder/types.d.ts

@@ -0,0 +1,76 @@
+import type { Snippet } from "svelte";
+/** A localized string: either one plain string, or a per-language map. */
+export type LocalizedText = string | Record<string, string>;
+/** A single option of a choice-like field type (one declaring `supportsOptions`). */
+export interface FieldOptionDef {
+    /** Machine value, unique within the field's options. */
+    value: string;
+    label: LocalizedText;
+}
+/** What the user may NOT change on a field. Absent flag = editable. */
+export interface FieldLock {
+    key?: boolean;
+    type?: boolean;
+    required?: boolean;
+    options?: boolean;
+    /** Cannot be removed from the list. */
+    delete?: boolean;
+    /** Cannot be dragged, and other fields cannot be moved past it. */
+    reorder?: boolean;
+}
+/**
+ * One field definition — the unit of the `FieldsBuilder` value. The component
+ * emits an ordered `FieldDef[]`; what the list is compiled into (a form, a
+ * schema, a template...) is entirely the consumer's business.
+ */
+export interface FieldDef {
+    /** Machine key. Unique within the list. */
+    key: string;
+    /** One of the `types` palette entries' `type`. */
+    type: string;
+    label: LocalizedText;
+    description?: LocalizedText;
+    required?: boolean;
+    /**
+     * Edited and validated only for palette entries declaring
+     * `supportsOptions`. NOTE: when a field's type is changed away from a
+     * choice type, existing `options` are deliberately RETAINED on the def
+     * (never silently drop data; switching back restores them) — consumers
+     * compiling the list should ignore `options` on non-choice types.
+     */
+    options?: FieldOptionDef[];
+    /**
+     * Per-type extra flags, driven by the palette entry's `extras`. An open bag
+     * on purpose — the component never interprets these, it only renders a
+     * control per declared extra and round-trips the value.
+     */
+    extras?: Record<string, unknown>;
+    /** What the user may NOT change. Absent = fully editable. */
+    lock?: FieldLock;
+}
+/** An extra per-field control declared by a palette entry (v1: booleans only). */
+export interface FieldTypeExtraDef {
+    /** Stored under `FieldDef.extras[key]`. */
+    key: string;
+    label: LocalizedText;
+    description?: LocalizedText;
+    /** v1: booleans only (rendered as a checkbox). */
+    type: "boolean";
+    default?: boolean;
+}
+/** One entry of the type palette (the `types` prop). */
+export interface FieldTypeDef {
+    /** Stored in `FieldDef.type`. */
+    type: string;
+    /** Shown in the type picker. */
+    label: LocalizedText;
+    description?: LocalizedText;
+    /** Icon html string (e.g. from `@marianmeres/icons-fns`) or a snippet. */
+    icon?: string | Snippet;
+    /** Renders the option editor and allows `FieldDef.options`. */
+    supportsOptions?: boolean;
+    /** Extra per-field controls, rendered into `FieldDef.extras[key]`. */
+    extras?: FieldTypeExtraDef[];
+    /** Optional live preview of a single field of this type. */
+    preview?: Snippet<[FieldDef]>;
+}

package/dist/components/FieldsBuilder/types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/FieldsBuilder/utils.d.ts

@@ -0,0 +1,66 @@
+import type { FieldDef, FieldTypeDef, LocalizedText } from "./types.js";
+/** Default machine-key policy: lowercase snake_case, starts with a letter, max 63 chars. */
+export declare const DEFAULT_KEY_PATTERN: RegExp;
+export declare const DEFAULT_KEY_MAX_LENGTH = 63;
+/** Minimal translate signature the pure helpers below need. */
+export type FieldsBuilderTranslate = (key: string, values?: Record<string, string | number>) => string;
+/**
+ * Read the display text of a `LocalizedText`: the string itself, the preferred
+ * language's entry, or the first non-empty entry as a fallback.
+ */
+export declare function getLocalizedText(text: LocalizedText | null | undefined, preferredLanguage?: string): string;
+/**
+ * Derive a machine key from a human label: transliterates diacritics
+ * (`Ročník` → `rocnik`), lowercases, collapses everything else to `_`. A slug
+ * not starting with a letter is prefixed with `f_` (`2024` → `f_2024`) so the
+ * result always satisfies `DEFAULT_KEY_PATTERN`.
+ */
+export declare function slugifyKey(input: string, maxLength?: number): string;
+/**
+ * Make `base` unique against `isTaken` by suffixing `_2`, `_3`, ... The base is
+ * truncated when a suffixed candidate would exceed `maxLength`.
+ */
+export declare function uniqueKey(base: string, isTaken: (key: string) => boolean, maxLength?: number): string;
+export declare function isKeyReserved(key: string, reservedKeys?: string[] | ((key: string) => boolean)): boolean;
+export interface FieldDefRowErrors {
+    label?: string;
+    key?: string;
+    options?: string;
+}
+export interface FieldDefsValidationResult {
+    valid: boolean;
+    /** First error found — the component-level summary message. Empty when valid. */
+    message: string;
+    /** Index-aligned with the input defs. `null` = row has no errors. */
+    rowErrors: (FieldDefRowErrors | null)[];
+}
+export interface ValidateFieldDefsOptions {
+    /**
+     * The type palette. When provided, defs with a `type` not present here are
+     * treated as unknown: they are NOT validated (they round-trip untouched and
+     * must never block the rest of the list), but their keys still count toward
+     * uniqueness.
+     */
+    types?: Pick<FieldTypeDef, "type" | "supportsOptions">[];
+    keyPattern?: RegExp;
+    keyMaxLength?: number;
+    reservedKeys?: string[] | ((key: string) => boolean);
+    maxFields?: number;
+    defaultLanguage?: string;
+    /** Translator for the error messages; defaults to returning the message key. */
+    t?: FieldsBuilderTranslate;
+}
+/**
+ * Validate a list of field defs: label non-empty, key present/pattern/length/
+ * unique/not-reserved, choice types have at least one option with non-empty
+ * unique values, `maxFields` not exceeded.
+ *
+ * This is client-side convenience only — a consumer persisting the list MUST
+ * re-validate server-side; this function is not a security boundary.
+ */
+export declare function validateFieldDefs(defs: FieldDef[], opts?: ValidateFieldDefsOptions): FieldDefsValidationResult;
+/**
+ * A small general-purpose palette — handy for demos and for consumers with no
+ * opinion. `types` is a required prop, so nobody gets this by accident.
+ */
+export declare const DEFAULT_FIELD_TYPES: FieldTypeDef[];

package/dist/components/FieldsBuilder/utils.js

@@ -0,0 +1,153 @@
+/** Default machine-key policy: lowercase snake_case, starts with a letter, max 63 chars. */
+export const DEFAULT_KEY_PATTERN = /^[a-z][a-z0-9_]{0,62}$/;
+export const DEFAULT_KEY_MAX_LENGTH = 63;
+/**
+ * Read the display text of a `LocalizedText`: the string itself, the preferred
+ * language's entry, or the first non-empty entry as a fallback.
+ */
+export function getLocalizedText(text, preferredLanguage) {
+    if (text == null)
+        return "";
+    if (typeof text === "string")
+        return text;
+    if (preferredLanguage && text[preferredLanguage])
+        return text[preferredLanguage];
+    for (const v of Object.values(text))
+        if (v)
+            return v;
+    return "";
+}
+/**
+ * Derive a machine key from a human label: transliterates diacritics
+ * (`Ročník` → `rocnik`), lowercases, collapses everything else to `_`. A slug
+ * not starting with a letter is prefixed with `f_` (`2024` → `f_2024`) so the
+ * result always satisfies `DEFAULT_KEY_PATTERN`.
+ */
+export function slugifyKey(input, maxLength = DEFAULT_KEY_MAX_LENGTH) {
+    let s = (input ?? "")
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (s && !/^[a-z]/.test(s))
+        s = `f_${s}`;
+    if (maxLength > 0 && s.length > maxLength) {
+        s = s.slice(0, maxLength).replace(/_+$/, "");
+    }
+    return s;
+}
+/**
+ * Make `base` unique against `isTaken` by suffixing `_2`, `_3`, ... The base is
+ * truncated when a suffixed candidate would exceed `maxLength`.
+ */
+export function uniqueKey(base, isTaken, maxLength = DEFAULT_KEY_MAX_LENGTH) {
+    if (!base || !isTaken(base))
+        return base;
+    for (let i = 2; i < 1_000; i++) {
+        const suffix = `_${i}`;
+        let candidate = base + suffix;
+        if (maxLength > 0 && candidate.length > maxLength) {
+            candidate = base.slice(0, maxLength - suffix.length).replace(/_+$/, "") + suffix;
+        }
+        if (!isTaken(candidate))
+            return candidate;
+    }
+    return base;
+}
+export function isKeyReserved(key, reservedKeys) {
+    if (!reservedKeys)
+        return false;
+    return typeof reservedKeys === "function"
+        ? !!reservedKeys(key)
+        : reservedKeys.includes(key);
+}
+/**
+ * Validate a list of field defs: label non-empty, key present/pattern/length/
+ * unique/not-reserved, choice types have at least one option with non-empty
+ * unique values, `maxFields` not exceeded.
+ *
+ * This is client-side convenience only — a consumer persisting the list MUST
+ * re-validate server-side; this function is not a security boundary.
+ */
+export function validateFieldDefs(defs, opts = {}) {
+    const t = opts.t ?? ((k) => k);
+    const keyPattern = opts.keyPattern ?? DEFAULT_KEY_PATTERN;
+    const keyMaxLength = opts.keyMaxLength ?? DEFAULT_KEY_MAX_LENGTH;
+    const typeMap = opts.types ? new Map(opts.types.map((td) => [td.type, td])) : null;
+    const rowErrors = defs.map(() => null);
+    const put = (i, field, msg) => {
+        rowErrors[i] ??= {};
+        rowErrors[i][field] ??= msg;
+    };
+    // keys of ALL defs (incl. unknown types) occupy the key space
+    const keyCounts = new Map();
+    for (const d of defs) {
+        const k = (d.key ?? "").trim();
+        if (k)
+            keyCounts.set(k, (keyCounts.get(k) ?? 0) + 1);
+    }
+    defs.forEach((d, i) => {
+        // unknown type: keep as-is, do not block (see the doc comment above)
+        if (typeMap && !typeMap.has(d.type))
+            return;
+        if (!getLocalizedText(d.label, opts.defaultLanguage).trim()) {
+            put(i, "label", t("err_label_required"));
+        }
+        // presence is checked trimmed, but pattern/length run on the RAW key —
+        // a whitespace-padded key must fail here, not at the consumer's gate
+        const k = d.key ?? "";
+        if (!k.trim()) {
+            put(i, "key", t("err_key_required"));
+        }
+        else {
+            if (k.length > keyMaxLength) {
+                put(i, "key", t("err_key_maxlength", { max: keyMaxLength }));
+            }
+            else if (!keyPattern.test(k)) {
+                put(i, "key", t("err_key_pattern"));
+            }
+            if ((keyCounts.get(k.trim()) ?? 0) > 1)
+                put(i, "key", t("err_key_duplicate"));
+            if (isKeyReserved(k, opts.reservedKeys))
+                put(i, "key", t("err_key_reserved"));
+        }
+        if (typeMap?.get(d.type)?.supportsOptions) {
+            const options = d.options ?? [];
+            const values = options.map((o) => (o.value ?? "").trim());
+            if (!options.length) {
+                put(i, "options", t("err_options_required"));
+            }
+            else if (values.some((v) => !v)) {
+                put(i, "options", t("err_option_value_required"));
+            }
+            else if (new Set(values).size !== values.length) {
+                put(i, "options", t("err_option_value_duplicate"));
+            }
+        }
+    });
+    let message = rowErrors.find(Boolean)
+        ? Object.values(rowErrors.find(Boolean))[0]
+        : "";
+    if (!message && opts.maxFields && defs.length > opts.maxFields) {
+        message = t("err_max_fields", { max: opts.maxFields });
+    }
+    return { valid: !message, message, rowErrors };
+}
+/**
+ * A small general-purpose palette — handy for demos and for consumers with no
+ * opinion. `types` is a required prop, so nobody gets this by accident.
+ */
+export const DEFAULT_FIELD_TYPES = [
+    { type: "text", label: "Text", description: "A single line of text" },
+    { type: "longtext", label: "Long text", description: "Multiple lines of text" },
+    { type: "number", label: "Number", description: "A numeric value" },
+    { type: "checkbox", label: "Yes / no", description: "A single on/off checkbox" },
+    {
+        type: "select",
+        label: "Choice",
+        description: "Pick one from a list of choices",
+        supportsOptions: true,
+    },
+    { type: "date", label: "Date", description: "A calendar date" },
+];

package/dist/css/frame.css

@@ -0,0 +1,109 @@
+/* ============================================================================
+   RATIO-LOCKED FRAME (letterbox)
+
+   Lock a box to an aspect ratio, size it to whichever axis binds first, centre
+   it, and let the leftover space become letterboxing.
+
+   See docs/domains/css-presets.md for the classes, the token contract and the
+   decision tree, and docs/RATIO_LOCKED_FRAME.md for the recipes and the measured
+   gotcha list — the CSS here is nine declarations; the knowledge is the deliverable.
+
+   LAYERED (unlike the `.scrollbar-thin` / `.stuic-safe-area-*` utilities at the
+   end of index.css) because these are opt-in layout presets a consumer puts on
+   their OWN element and WILL tweak: Tailwind emits
+   `@layer theme, base, components, utilities`, so a utility always wins —
+   `class="stuic-frame h-dvh overflow-y-auto bg-white"` overrides everything
+   below. That is the escape hatch, by design.
+
+   This preset deliberately ships NO background, NO containment, NO scroll
+   container and NO letterbox-bars class: `grid`, `overflow-hidden`,
+   `fixed inset-0`, `bg-*`, `contain-layout`, `contain-paint`, `@container-size`
+   and `overflow-y-auto` are all Tailwind v4 utilities (stuic already requires
+   Tailwind v4). Only the sizing formula is ours, because it is the only part
+   Tailwind cannot express.
+   ============================================================================ */
+
+@layer components {
+	/* The ratio-locked box. Centres itself in a block, grid or flex parent
+	   (`margin: auto` centres both axes in grid/flex; in normal flow the block-
+	   axis autos compute to 0 and it behaves as `margin-inline: auto`).
+
+	   One parent shape is NOT safe: a flex COLUMN. The ratio-derived height becomes
+	   the flex base size and `min-height: 0` below removes the floor that would stop
+	   it shrinking, so the frame silently goes off-ratio (measured 400x740, r=0.5405,
+	   where a grid parent gives 400x800, r=0.5). Add `shrink-0`. See G22.
+
+	   Why min() and not `max-width:100%; max-height:100%; aspect-ratio:R` — the
+	   formulation everyone tries first: `max-*` never GROWS a box, so in a
+	   centred grid/flex parent an empty frame measures 0x0, and one with content
+	   shrink-wraps that content and overflows the parent. The ratio usually
+	   survives; the SIZE is what's wrong. (There is a working `max-*` variant —
+	   it needs a positioned parent — see Recipe D in the docs.)
+
+	   `aspect-ratio` supplies the height, so the frame is ratio-locked at every
+	   viewport, with bars on exactly one axis. Deriving the width from the
+	   height and then letting `aspect-ratio` derive the height back is not
+	   circular: `width` is resolved first, `aspect-ratio` only ever fills an
+	   `auto` axis.
+
+	   `min-height: 0` and `overflow: hidden` are load-bearing for the ratio, not
+	   cosmetics: a grid/flex item's automatic minimum size overrides
+	   `aspect-ratio` outright, so a tall child stretches an otherwise correct
+	   frame off-ratio. Either one alone fixes it; both are set so a consumer's
+	   `overflow-visible` stays survivable. */
+	.stuic-frame {
+		width: var(
+			--stuic-frame-width,
+			min(100vw, calc(100dvh * (var(--stuic-frame-aspect-ratio, 1))))
+		);
+
+		/* `auto` = ratio-locked (the default). Any explicit length here WINS over
+		   `aspect-ratio` unconditionally — that is the supported way to opt into
+		   "fill the height, derive the width" inside a bail-out media query, with
+		   no `!important` and no specificity game. */
+		height: var(--stuic-frame-height, auto);
+
+		aspect-ratio: var(--stuic-frame-aspect-ratio, 1);
+		min-height: 0;
+		margin: auto;
+		overflow: hidden;
+	}
+
+	/* Opt-in: size against the nearest ANCESTOR query container instead of the
+	   viewport — the nested case (a frame under a header, inside a flex column).
+	   Combine with `.stuic-frame`; this rule must stay AFTER it in source order,
+	   since both declare `width` at equal specificity.
+
+	   REQUIRES an ancestor with `container-type: size` (Tailwind:
+	   `@container-size`). `inline-size` is NOT enough: `cqh` then falls THROUGH
+	   to the next container, or silently to the small viewport, and you get a
+	   ratio-correct but wrongly-scaled frame that overflows its parent and
+	   tracks the window as you resize. Same failure with no container ancestor
+	   at all. Size containment is safe here precisely because this frame's own
+	   height is always determined. */
+	.stuic-frame-cq {
+		width: var(
+			--stuic-frame-width,
+			min(100cqw, calc(100cqh * (var(--stuic-frame-aspect-ratio, 1))))
+		);
+	}
+
+	/* Re-align a VIEWPORT-space element onto the frame's column: a top-layer
+	   `<dialog>`, or an overlay portalled to `<body>` (stuic's popover /
+	   spotlight / dimBehind default to `document.body` — pass their `container`
+	   option instead where you can).
+
+	   The whole fallback expression is repeated on purpose. Nothing declares
+	   `--stuic-frame-width`, so a bare `var(--stuic-frame-width)` would be
+	   invalid-at-computed-value-time -> `width: auto` -> silently full-bleed. */
+	.stuic-frame-col {
+		width: min(
+			100%,
+			var(
+				--stuic-frame-width,
+				min(100vw, calc(100dvh * (var(--stuic-frame-aspect-ratio, 1))))
+			)
+		);
+		margin-inline: auto;
+	}
+}

package/dist/index.css

@@ -80,6 +80,7 @@ In practice:
 @import "./components/DismissibleMessage/index.css";
 @import "./components/DropdownMenu/index.css";
 @import "./components/EmailVerifyForm/index.css";
+@import "./components/FieldsBuilder/index.css";
 @import "./components/Float/index.css";
 @import "./components/H/index.css";
 @import "./components/Header/index.css";
@@ -118,6 +119,9 @@ In practice:
 @import "./actions/spotlight/index.css";
 @import "./actions/tooltip/index.css";
 
+/* Layout preset CSS (classes only, no component) */
+@import "./css/frame.css";
+
 /* Base styles for STUIC components */
 @layer base {
 	button:not(:disabled),

package/dist/index.d.ts

@@ -45,6 +45,7 @@ export * from "./components/DismissibleMessage/index.js";
 export * from "./components/Drawer/index.js";
 export * from "./components/DropdownMenu/index.js";
 export * from "./components/EmailVerifyForm/index.js";
+export * from "./components/FieldsBuilder/index.js";
 export * from "./components/Float/index.js";
 export * from "./components/H/index.js";
 export * from "./components/Header/index.js";

package/dist/index.js

@@ -51,6 +51,7 @@ export * from "./components/DismissibleMessage/index.js";
 export * from "./components/Drawer/index.js";
 export * from "./components/DropdownMenu/index.js";
 export * from "./components/EmailVerifyForm/index.js";
+export * from "./components/FieldsBuilder/index.js";
 export * from "./components/Float/index.js";
 export * from "./components/H/index.js";
 export * from "./components/Header/index.js";