runeforge 0.0.57 → 0.0.58

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/Field.svelte

@@ -1,6 +1,7 @@
 <script lang="ts" generics="T extends object = Record<string, unknown>">
 	import { onMount } from 'svelte';
 	import Avatar from '../Avatar.svelte';
+	import Button from '../form/Button.svelte';
 	import Label from '../form/Label.svelte';
 	import Select from '../form/Select.svelte';
 	import MultiSelect from '../form/MultiSelect.svelte';
@@ -72,6 +73,9 @@
 		typeof field.hidden === 'function' ? field.hidden(record) : !!field.hidden
 	);
 	const isMultiValued = $derived(field.type === 'multiselect' || field.type === 'tree');
+	const fieldActions = $derived(
+		(field.actions ?? []).filter((action) => action.condition?.(record) ?? true)
+	);
 
 	// cally's `change` event doesn't bubble, so the usual `onchange={...}` prop
 	// never fires — Svelte 5 delegates events like `change` to a listener on
@@ -224,12 +228,36 @@
 			</div>
 		{/if}
 
-		<Label
-			text={labelText}
-			for={field.attribute}
-			capitalize={true}
-			required={fieldRequired && !readonly}
-		/>
+		<div class="flex items-center justify-between gap-2">
+			<Label
+				text={labelText}
+				for={field.attribute}
+				capitalize={true}
+				required={fieldRequired && !readonly}
+			/>
+			{#if !readonly && fieldActions.length > 0}
+				<div class="flex items-center gap-1">
+					{#each fieldActions as action (action.label)}
+						<Button
+							type="button"
+							variant="ghost"
+							class={['btn-xs', action.class]}
+							title={action.label}
+							onclick={() =>
+								action.run(record[field.attribute], record, (attribute, value) => {
+									record[attribute] = value;
+								})}
+						>
+							{#if action.icon}
+								{@const Icon = action.icon}
+								<Icon class="size-4" />
+							{/if}
+							{action.label}
+						</Button>
+					{/each}
+				</div>
+			{/if}
+		</div>
 
 		{#if field.type === 'boolean'}
 			<input

package/dist/components/crud/utils/resolution.js

@@ -68,10 +68,12 @@ export function buildFieldDefinitions(meta, data, excludedFlag, excluded) {
         minLength: m.minLength,
         maxLength: m.maxLength,
         pattern: m.pattern,
+        validate: m.validate,
         rows: m.rows,
         fields: m.fields ? buildFieldDefinitions(m.fields, data, excludedFlag, new Set()) : undefined,
         itemLabel: m.itemLabel,
         defaultExpanded: m.defaultExpanded,
-        row: m.row
+        row: m.row,
+        actions: m.actions
     }));
 }

package/dist/components/crud/utils/validation.js

@@ -22,6 +22,11 @@ export function validateAll(fields, formData, strings) {
             if (required && (!Array.isArray(items) || items.length === 0)) {
                 errors[field.attribute] = strings.required(fieldLabel(field));
             }
+            if (!errors[field.attribute] && field.validate) {
+                const message = field.validate(items, record);
+                if (message)
+                    errors[field.attribute] = message;
+            }
             continue;
         }
         const val = String(formData.get(field.attribute) ?? '').trim();
@@ -57,6 +62,11 @@ export function validateAll(fields, formData, strings) {
                 errors[field.attribute] = strings.pattern(fieldLabel(field));
             }
         }
+        if (!errors[field.attribute] && field.validate) {
+            const message = field.validate(val, record);
+            if (message)
+                errors[field.attribute] = message;
+        }
     }
     return errors;
 }

package/dist/components/crud/views/Create.svelte

@@ -78,35 +78,37 @@
 
 <div class="flex flex-col gap-6">
 
-  <Header
-    title={labelMany}
-    breadcrumbs={[
-      { label: labelMany, icon: entityIcon, link: { href: '#', onclick: (e) => { e.preventDefault(); onCancel?.(); } }, prominent: true },
-      { label: creation.label ?? labelOne, icon: icons.create },
-    ]}
-  />
-
-  {#if successMessage}
-    <div role="alert" class="alert alert-success">
-      <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12.75 11.25 15 15 9.75M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" />
-      </svg>
-      <span class="text-sm">{successMessage}</span>
-    </div>
-  {/if}
-
-  {#if errorEntries.length > 0}
-    <div role="alert" class="alert alert-error">
-      <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 14l2-2m0 0l2-2m-2 2l-2-2m2 2l2 2m7-2a9 9 0 11-18 0 9 9 0 0118 0z" />
-      </svg>
-      <ul class="list-disc list-inside text-sm">
-        {#each errorEntries as [key, msg] (key)}
-          <li>{msg}</li>
-        {/each}
-      </ul>
-    </div>
-  {/if}
+  <div class="sticky-header sticky z-10 flex flex-col gap-6 bg-base-100 pb-2">
+    <Header
+      title={labelMany}
+      breadcrumbs={[
+        { label: labelMany, icon: entityIcon, link: { href: '#', onclick: (e) => { e.preventDefault(); onCancel?.(); } }, prominent: true },
+        { label: creation.label ?? labelOne, icon: icons.create },
+      ]}
+    />
+
+    {#if successMessage}
+      <div role="alert" class="alert alert-success">
+        <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12.75 11.25 15 15 9.75M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" />
+        </svg>
+        <span class="text-sm">{successMessage}</span>
+      </div>
+    {/if}
+
+    {#if errorEntries.length > 0}
+      <div role="alert" class="alert alert-error">
+        <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 14l2-2m0 0l2-2m-2 2l-2-2m2 2l2 2m7-2a9 9 0 11-18 0 9 9 0 0118 0z" />
+        </svg>
+        <ul class="list-disc list-inside text-sm">
+          {#each errorEntries as [key, msg] (key)}
+            <li>{msg}</li>
+          {/each}
+        </ul>
+      </div>
+    {/if}
+  </div>
 
   <form
     method="POST"
@@ -229,4 +231,8 @@
   form {
     max-width: var(--runeforge-form-max-width, 32rem);
   }
+
+  .sticky-header {
+    top: var(--runeforge-sticky-header-top, 0);
+  }
 </style>

package/dist/components/crud/views/Read.svelte

@@ -67,13 +67,15 @@
 
 <div class="flex flex-col gap-6">
 
-  <Header
-    title={labelMany}
-    breadcrumbs={[
-      { label: labelMany, icon: entityIcon, link: { href: '#', onclick: (e) => { e.preventDefault(); onCancel?.(); } }, prominent: true },
-      { label: read.label ?? labelOne, icon: icons.view },
-    ]}
-  />
+  <div class="sticky-header sticky z-10 bg-base-100 pb-2">
+    <Header
+      title={labelMany}
+      breadcrumbs={[
+        { label: labelMany, icon: entityIcon, link: { href: '#', onclick: (e) => { e.preventDefault(); onCancel?.(); } }, prominent: true },
+        { label: read.label ?? labelOne, icon: icons.view },
+      ]}
+    />
+  </div>
 
   <div class="fields-panel mx-auto flex w-full flex-col gap-4 px-4">
     {#each groups as group, i (group.title ?? `_ungrouped_${i}`)}
@@ -121,4 +123,8 @@
   .fields-panel {
     max-width: var(--runeforge-form-max-width, 32rem);
   }
+
+  .sticky-header {
+    top: var(--runeforge-sticky-header-top, 0);
+  }
 </style>

package/dist/components/crud/views/Update.svelte

@@ -80,26 +80,28 @@
 
 <div class="flex flex-col gap-6">
 
-  <Header
-    title={labelMany}
-    breadcrumbs={[
-      { label: labelMany, icon: entityIcon, link: { href: '#', onclick: (e) => { e.preventDefault(); onCancel?.(); } }, prominent: true },
-      { label: update.label ?? labelOne, icon: icons.edit },
-    ]}
-  />
-
-  {#if errorEntries.length > 0}
-    <div role="alert" class="alert alert-error">
-      <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 14l2-2m0 0l2-2m-2 2l-2-2m2 2l2 2m7-2a9 9 0 11-18 0 9 9 0 0118 0z" />
-      </svg>
-      <ul class="list-disc list-inside text-sm">
-        {#each errorEntries as [key, msg] (key)}
-          <li>{msg}</li>
-        {/each}
-      </ul>
-    </div>
-  {/if}
+  <div class="sticky-header sticky z-10 flex flex-col gap-6 bg-base-100 pb-2">
+    <Header
+      title={labelMany}
+      breadcrumbs={[
+        { label: labelMany, icon: entityIcon, link: { href: '#', onclick: (e) => { e.preventDefault(); onCancel?.(); } }, prominent: true },
+        { label: update.label ?? labelOne, icon: icons.edit },
+      ]}
+    />
+
+    {#if errorEntries.length > 0}
+      <div role="alert" class="alert alert-error">
+        <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 14l2-2m0 0l2-2m-2 2l-2-2m2 2l2 2m7-2a9 9 0 11-18 0 9 9 0 0118 0z" />
+        </svg>
+        <ul class="list-disc list-inside text-sm">
+          {#each errorEntries as [key, msg] (key)}
+            <li>{msg}</li>
+          {/each}
+        </ul>
+      </div>
+    {/if}
+  </div>
 
   <form
     method="POST"
@@ -205,4 +207,8 @@
   form {
     max-width: var(--runeforge-form-max-width, 32rem);
   }
+
+  .sticky-header {
+    top: var(--runeforge-sticky-header-top, 0);
+  }
 </style>

package/dist/types/attribute.d.ts

@@ -34,6 +34,24 @@ export type SeedResolver = (instance: any) => unknown;
 /** Embedded fields only: renders a short summary for one item in the list.
  * Falls back to a dash-joined summary of the item's sub-field values. */
 export type EmbeddedItemLabelResolver = (item: Record<string, unknown>) => string;
+export type ValidateResolver = (value: unknown, record: Record<string, unknown>) => string | undefined;
+/** Sets a field's value from within a `FieldButtonAction.run` callback —
+ * usually the same field the button sits next to, but any sibling attribute
+ * works too. */
+export type FieldSetter = (attribute: string, value: unknown) => void;
+/** A button rendered next to a field's label that runs entirely client-side
+ * — no submit, no request — instead of persisting a model attribute of its
+ * own. See `AttributeMetadata.actions`. */
+export type FieldButtonAction = {
+    label: string;
+    icon?: any;
+    class?: string;
+    /** Hide the button in certain conditions. Re-evaluated live, same as `disabled`. */
+    condition?: (record: Record<string, unknown>) => boolean;
+    /** Receives the field's current value, the form's full draft record, and a
+     * setter to write back into this field (or a sibling one). */
+    run: (value: unknown, record: Record<string, unknown>, setField: FieldSetter) => void;
+};
 export type AttributeMetadata = {
     label?: string;
     type?: AttributeType;
@@ -91,6 +109,15 @@ export type AttributeMetadata = {
     minLength?: number;
     maxLength?: number;
     pattern?: string;
+    /** Custom validation, run after this field's built-in rules
+     * (required/min/max/minLength/maxLength/pattern) pass, and only when none
+     * of them already failed. Receives the field's submitted value and the
+     * full draft record (including sibling fields currently in the form), so
+     * the same hook covers a lone-field rule and a cross-field rule alike —
+     * e.g. an `extension_date` that must be later than the record's
+     * `submission_date`. Return an error message, or `undefined` when the
+     * value is valid. */
+    validate?: ValidateResolver;
     /** Textarea fields only: the HTML `rows` attribute, controlling height. */
     rows?: number;
     /** Embedded fields only: schema for each item added through the "+" modal. */
@@ -103,4 +130,8 @@ export type AttributeMetadata = {
      * stacked on mobile — see the Field rows section. Only merges fields that
      * are also in the same `groupedAs` bucket (or both ungrouped). */
     row?: string;
+    /** Extra buttons rendered next to this field's label — e.g. a "Capitalize"
+     * button that transforms the field's own value client-side. See "Field
+     * actions" in the README. */
+    actions?: FieldButtonAction[];
 };

package/dist/types/crud.d.ts

@@ -1,6 +1,6 @@
 import type { Component } from 'svelte';
 import type { FullAutoFill } from 'svelte/elements';
-import type { AttributeType, SearchResolver, RequiredResolver, SelectOption } from './attribute.js';
+import type { AttributeType, SearchResolver, RequiredResolver, SelectOption, FieldButtonAction } from './attribute.js';
 import type { CellComponent, CellFormatter, SortableModule, TableQuery } from './table.js';
 import type { XlsxModule } from '../components/table/export.js';
 export type ColumnDefinition<T extends object = Record<string, unknown>> = {
@@ -46,6 +46,8 @@ export interface FieldDefinition<T extends object = Record<string, unknown>> {
     minLength?: number;
     maxLength?: number;
     pattern?: string;
+    /** See `AttributeMetadata.validate`. */
+    validate?: (value: unknown, record: Record<string, unknown>) => string | undefined;
     /** Textarea fields only: the HTML `rows` attribute, controlling height. */
     rows?: number;
     /** Embedded fields only: sub-field definitions for each item, built from
@@ -57,6 +59,8 @@ export interface FieldDefinition<T extends object = Record<string, unknown>> {
     defaultExpanded?: boolean;
     /** Fields sharing the same `row` string render side by side. */
     row?: string;
+    /** See `AttributeMetadata.actions`. */
+    actions?: FieldButtonAction[];
 }
 /** A create-form button whose visibility, label and styling can all be
  * overridden — `enabled` falls back to the button's own default (see

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runeforge",
-  "version": "0.0.57",
+  "version": "0.0.58",
   "description": "SvelteKit toolkit for building metadata-driven CRUD interfaces with tables, forms, and actions",
   "license": "MIT",
   "author": "Ezequiel Puerta",