runeforge 0.0.57 → 0.0.59

package/README.md

@@ -164,9 +164,12 @@ Responsive overrides work too:
 | `--runeforge-breadcrumb-font-size` | `0.875rem` | Breadcrumb label text size |
 | `--runeforge-breadcrumb-icon-size` | `1rem` | Breadcrumb icon width and height |
 | `--runeforge-tree-max-height` | `24rem` | Max height of a `tree` field before it scrolls internally |
+| `--runeforge-sticky-header-top` | `0` | Offset of the sticky title/breadcrumbs/alert block in Create, Update, and Read views — raise it if your app already has its own sticky top bar taking up space |
 
 Modal sizing (see [Shared Components](#shared-components)) is set per-instance via props rather than a CSS variable.
 
+The title, breadcrumbs and any error/success alert at the top of the Create, Update and Read views stay pinned (`position: sticky`) to the top of the nearest scrolling ancestor, so they — and a validation error that just appeared — stay visible while a long form scrolls underneath. Set `--runeforge-sticky-header-top` if that ancestor already has its own fixed/sticky bar above this block.
+
 ---
 
 ## Configuration
@@ -364,6 +367,8 @@ Every entry in an `InterfaceMetadata<T>` object is an `AttributeMetadata` — a
 | `integer` | `boolean` | `number` | Rejects non-whole numbers |
 | `minLength` / `maxLength` | `number` | text-like | Character-count validation |
 | `pattern` | `string` | text-like | Regex the value must match (`new RegExp(pattern)`) |
+| `validate` | `(value, record) => string \| undefined` | all | Custom validation, including cross-field rules — see [Validation](#validation) |
+| `actions` | `FieldButtonAction[]` | all | Extra buttons rendered next to the field's label — see [Field actions](#field-actions) |
 | `disabled` | `(record) => boolean` | all | Conditionally disables the input — see [Conditional fields](#conditional-fields) |
 | `hidden` | `boolean \| (record) => boolean` | all | Conditionally removes the field from the form entirely — not rendered, not validated, not submitted — see [Conditional fields](#conditional-fields) |
 | `groupedAs` | `string` | all | Visually groups fields under a titled section — see [Field grouping](#field-grouping) |
@@ -428,6 +433,27 @@ quantity: {
 
 The label's required marker and the submit-time check both re-evaluate the same way `disabled` does — see [Conditional fields](#conditional-fields).
 
+For anything the built-in rules above don't cover — including a rule that depends on another field, not just this one — pass `validate`. It runs after this field's built-in rules pass (and is skipped if one of them already failed), and receives both the field's own value and the full draft record, so the same hook covers a lone-field rule and a cross-field one alike:
+
+```ts
+submissionDate: {
+  label: 'Submission date',
+  type: AttributeType.datetime,
+},
+extensionDate: {
+  label: 'Extension date',
+  type: AttributeType.datetime,
+  validate: (value, record) =>
+    typeof value === 'string' &&
+    typeof record.submissionDate === 'string' &&
+    value <= record.submissionDate
+      ? 'Extension date must be later than the submission date'
+      : undefined,
+},
+```
+
+There's deliberately no separate, form-wide validation hook — every error belongs to the field whose value is wrong, even when the rule reads a sibling's value to decide that, so a per-field `validate` is all that's needed.
+
 > [!TIP]
 > Client-side validation is a UX nicety, not a security boundary — always re-validate in your form actions.
 
@@ -476,6 +502,31 @@ cardExpiry: {
 
 Switching `paymentMethod` between `card` and `cash` swaps which fields are present, live, in the same create/edit view — no separate step or modal needed to collect the payment-specific details.
 
+### Field actions
+
+`actions` renders one or more buttons next to a field's label, for a client-side transform that doesn't belong to any field of its own — nothing is submitted, nothing hits the server, the button just runs synchronously and updates the form. Useful for things like normalizing free text as the user types it:
+
+```ts
+import Edit from './icons/Edit.svelte';
+
+description: {
+  label: 'Description',
+  type: AttributeType.textarea,
+  actions: [
+    {
+      label: 'Capitalize',
+      icon: Edit,
+      run: (value, record, setField) => {
+        const str = String(value ?? '');
+        setField('description', str ? str[0].toUpperCase() + str.slice(1).toLowerCase() : str);
+      },
+    },
+  ],
+},
+```
+
+`run` receives the field's current value, the form's full draft record, and a `setField(attribute, value)` setter — which can just as well target a sibling attribute instead of the field the button sits next to. `icon` is a Svelte component, same convention as [custom row actions](#custom-row-actions). `condition` hides the button in certain conditions, re-evaluated live like `disabled`. Actions never render in the read-only view.
+
 ### Field grouping
 
 Fields sharing the same `groupedAs` string render together inside a titled `fieldset`, at the position of the group's first field. Fields without `groupedAs` keep the original flat layout.

package/dist/components/crud/EmbeddedField.svelte

@@ -1,4 +1,5 @@
 <script lang="ts" generics="T extends object = Record<string, unknown>">
+	import { untrack } from 'svelte';
 	import Field from './Field.svelte';
 	import Button from '../form/Button.svelte';
 	import Modal from '../Modal.svelte';
@@ -6,7 +7,7 @@
 	import { fieldLabel } from './utils/misc.js';
 	import { validateAll } from './utils/validation.js';
 	import { groupFields } from './utils/grouping.js';
-	import type { FieldDefinition } from '../../types/crud.js';
+	import type { FieldDefinition } from '../../types/crud/fields.js';
 	import { getStrings } from '../../i18n/context.js';
 
 	const strings = getStrings();
@@ -17,6 +18,11 @@
 		readonly = false
 	}: {
 		field: FieldDefinition<T>;
+		/** The record that owns this embedded field (the form record for a
+		 * top-level embedded field, or the outer item's draft for one nested
+		 * inside another embedded field) — passed through to each sub-field's
+		 * `hidden`/`disabled`/`required`/`dependentOptions` as their `parent`
+		 * argument, and to `field.revalidate` as its own parent argument. */
 		record?: Record<string, unknown>;
 		readonly?: boolean;
 	} = $props();
@@ -25,6 +31,28 @@
 	const subGroups = $derived(groupFields(subFields));
 	const items = $derived((record[field.attribute] as Record<string, unknown>[] | undefined) ?? []);
 
+	// Re-derives the embedded list right after `field.dependsOn` changes value
+	// on the parent record — e.g. dropping items that no longer apply once a
+	// sibling "owner kind" select flips — instead of leaving them stale until
+	// the user happens to touch this field again. Scoped to exactly that one
+	// parent attribute: reading it is this effect's only tracked dependency,
+	// and everything else (including its own write to `record[field.attribute]`)
+	// runs inside `untrack` so the effect never re-triggers itself.
+	$effect(() => {
+		if (!field.dependsOn || !field.revalidate) return;
+		// Read (only) to register as this effect's sole tracked dependency —
+		// everything that actually acts on it happens inside untrack() below,
+		// so the effect reruns exactly when this one value changes and never
+		// because of its own write to record[field.attribute].
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
+		const dependencyValue = record[field.dependsOn];
+		untrack(() => {
+			const current = (record[field.attribute] as Record<string, unknown>[] | undefined) ?? [];
+			const next = field.revalidate!(current, record);
+			if (next !== current) record[field.attribute] = next;
+		});
+	});
+
 	let modalOpen = $state(false);
 	// null while adding a new item; the item's index while editing an existing
 	// one, so saveItem knows whether to append or replace in place.
@@ -141,11 +169,11 @@
 								{#if row.length > 1}
 									<div class="flex flex-col gap-4 md:flex-row">
 										{#each row as f (f.attribute)}
-											<Field field={f} bind:record={draft} error={draftErrors[f.attribute] ?? ''} class="md:min-w-0 md:flex-1" />
+											<Field field={f} bind:record={draft} parentRecord={record} error={draftErrors[f.attribute] ?? ''} class="md:min-w-0 md:flex-1" />
 										{/each}
 									</div>
 								{:else}
-									<Field field={row[0]} bind:record={draft} error={draftErrors[row[0].attribute] ?? ''} />
+									<Field field={row[0]} bind:record={draft} parentRecord={record} error={draftErrors[row[0].attribute] ?? ''} />
 								{/if}
 							{/each}
 						</div>
@@ -155,11 +183,11 @@
 						{#if row.length > 1}
 							<div class="flex flex-col gap-4 md:flex-row">
 								{#each row as f (f.attribute)}
-									<Field field={f} bind:record={draft} error={draftErrors[f.attribute] ?? ''} class="md:min-w-0 md:flex-1" />
+									<Field field={f} bind:record={draft} parentRecord={record} error={draftErrors[f.attribute] ?? ''} class="md:min-w-0 md:flex-1" />
 								{/each}
 							</div>
 						{:else}
-							<Field field={row[0]} bind:record={draft} error={draftErrors[row[0].attribute] ?? ''} />
+							<Field field={row[0]} bind:record={draft} parentRecord={record} error={draftErrors[row[0].attribute] ?? ''} />
 						{/if}
 					{/each}
 				{/if}

package/dist/components/crud/EmbeddedField.svelte.d.ts

@@ -1,7 +1,12 @@
-import type { FieldDefinition } from '../../types/crud.js';
+import type { FieldDefinition } from '../../types/crud/fields.js';
 declare function $$render<T extends object = Record<string, unknown>>(): {
     props: {
         field: FieldDefinition<T>;
+        /** The record that owns this embedded field (the form record for a
+         * top-level embedded field, or the outer item's draft for one nested
+         * inside another embedded field) — passed through to each sub-field's
+         * `hidden`/`disabled`/`required`/`dependentOptions` as their `parent`
+         * argument, and to `field.revalidate` as its own parent argument. */
         record?: Record<string, unknown>;
         readonly?: boolean;
     };