@streamscloud/kit 0.2.42 → 0.9.1

package/dist/ui/file-uploader/cmp.file-uploader.svelte

@@ -0,0 +1,210 @@
+<script lang="ts">import { FileValidator } from '../../core/files';
+import { Icon } from '../icon';
+import IconArrowUpload from '@fluentui/svg-icons/icons/arrow_upload_24_regular.svg?raw';
+const { multiple = false, validationRules, disabled = false, title = '', description = '', on } = $props();
+// Auto-derive the native picker `accept` from any Mime-style rule that exposes its accept
+// string. Single source of truth — consumer writes the MIME pattern once on the rule.
+const accept = $derived(validationRules
+    ?.map((r) => r.accept)
+    .filter((a) => !!a)
+    .join(',') ?? '');
+let inputRef = $state.raw(undefined);
+let dragOver = $state(false);
+// Snapshot of MIME types captured at dragenter — DataTransfer.files is empty during drag
+// (browser security), but DataTransfer.items exposes `{kind, type}` per item so we can
+// soft-validate against `accept` before drop and tint the zone red on mismatch.
+let dragItems = $state.raw([]);
+// Soft-validation during drag: we only have MIME types (not filenames), so accept-tokens
+// starting with `.` (extensions) can't be checked here — defer them to drop. We also defer
+// when item.type is empty (some sources don't set MIME).
+const dragInvalid = $derived.by(() => {
+    if (!dragOver || !accept || dragItems.length === 0) {
+        return false;
+    }
+    const mimeTokens = accept
+        .split(',')
+        .map((s) => s.trim().toLowerCase())
+        .filter((t) => t && !t.startsWith('.'));
+    if (mimeTokens.length === 0) {
+        return false;
+    }
+    return dragItems.some((item) => {
+        if (item.kind !== 'file' || !item.type) {
+            return false;
+        }
+        const fileType = item.type.toLowerCase();
+        return !mimeTokens.some((t) => (t.endsWith('/*') ? fileType.startsWith(t.slice(0, -1)) : fileType === t));
+    });
+});
+const ingest = async (incoming) => {
+    let arr = Array.from(incoming);
+    // multiple=false → silently take only the first file (no rejection event).
+    if (!multiple && arr.length > 1) {
+        arr = [arr[0]];
+    }
+    const results = validationRules && validationRules.length > 0
+        ? await FileValidator.validateMany(arr, validationRules)
+        : arr.map((file) => ({ file, isValid: true, errors: [] }));
+    on?.select?.(results);
+};
+const handleInput = (e) => {
+    const t = e.target;
+    if (!t.files) {
+        return;
+    }
+    ingest(t.files);
+    t.value = '';
+};
+const handleDragEnter = (e) => {
+    e.preventDefault();
+    if (disabled) {
+        return;
+    }
+    dragOver = true;
+    if (e.dataTransfer?.items && e.dataTransfer.items.length > 0) {
+        dragItems = Array.from(e.dataTransfer.items).map((i) => ({ kind: i.kind, type: i.type }));
+    }
+};
+const handleDragLeave = (e) => {
+    e.preventDefault();
+    dragOver = false;
+    // Keep `dragItems` until drop — clearing here can race with browser-fired phantom
+    // dragleave/dragenter sequences and cause the invalid-state class to flicker off.
+};
+const handleDragOver = (e) => {
+    e.preventDefault();
+    if (e.dataTransfer) {
+        e.dataTransfer.dropEffect = 'copy';
+    }
+};
+const handleDrop = (e) => {
+    e.preventDefault();
+    dragOver = false;
+    dragItems = [];
+    if (disabled || !e.dataTransfer?.files) {
+        return;
+    }
+    ingest(e.dataTransfer.files);
+};
+</script>
+
+<div class="file-uploader" class:file-uploader--disabled={disabled}>
+  <button
+    type="button"
+    class="file-uploader__zone"
+    class:file-uploader__zone--drag={dragOver && !dragInvalid}
+    class:file-uploader__zone--drag-invalid={dragOver && dragInvalid}
+    disabled={disabled}
+    onclick={() => inputRef?.click()}
+    ondragenter={handleDragEnter}
+    ondragleave={handleDragLeave}
+    ondragover={handleDragOver}
+    ondrop={handleDrop}>
+    <span class="file-uploader__icon" aria-hidden="true">
+      <Icon src={IconArrowUpload} />
+    </span>
+    {#if title}<span class="file-uploader__title">{title}</span>{/if}
+    {#if description}<span class="file-uploader__desc">{description}</span>{/if}
+    <input bind:this={inputRef} class="file-uploader__input" type="file" multiple={multiple} accept={accept} disabled={disabled} onchange={handleInput} />
+  </button>
+</div>
+
+<!--
+@component
+Drag-and-drop or click-to-select file zone. **Pure selector** — picks files, runs optional
+`validationRules`, and emits `on.select(FileValidationResult[])`. The consumer reads
+`isValid` / `errors` per result and decides what to do (toast, queue into an
+`UploadMediaStore`, etc.). The cmp renders neither error UI nor progress visuals — compose
+those externally next to the dropzone (e.g. `<FileRow>` / `<FileUploadProgress>` driven by
+`store.files`).
+
+The native picker filter + drag-over visual hint are derived from any `FileRules.Mime(...)`
+rule's `accept` — pass it once via the rule, the cmp wires both. During drag-over, files
+whose MIME does not match paint the zone with the danger color before drop (soft-validation
+via `DataTransfer.items` — extension-only accept tokens defer to drop).
+
+### CSS Custom Properties
+| Property | Description | Default |
+|---|---|---|
+| `--sc-kit--file-uploader--background` | Drop-zone background | `var(--sc-kit--color--bg--field-alt)` |
+| `--sc-kit--file-uploader--background--drag` | Background during valid drag-over / hover | `var(--sc-kit--color--accent--softer)` |
+| `--sc-kit--file-uploader--background--drag-invalid` | Background when a dragged file's MIME does not match the Mime rule | `var(--sc-kit--color--danger--soft)` |
+| `--sc-kit--file-uploader--border-color` | Dashed border color (idle) | `var(--sc-kit--color--border--strong)` |
+| `--sc-kit--file-uploader--border-color--drag` | Dashed border color during valid drag-over / hover | `var(--sc-kit--color--accent)` |
+| `--sc-kit--file-uploader--border-color--drag-invalid` | Dashed border color when dragged file's MIME does not match the Mime rule | `var(--sc-kit--color--danger)` |
+| `--sc-kit--file-uploader--border-radius` | Drop-zone radius | `var(--sc-kit--radius--lg)` |
+| `--sc-kit--file-uploader--padding` | Inner padding | `var(--sc-kit--space--6)` |
+| `--sc-kit--file-uploader--icon--color` | Icon color | `var(--sc-kit--color--text--muted)` |
+| `--sc-kit--file-uploader--title--color` | Title color | `var(--sc-kit--color--text--primary)` |
+| `--sc-kit--file-uploader--description--color` | Description color | `var(--sc-kit--color--text--muted)` |
+-->
+
+<style>.file-uploader {
+  display: block;
+  width: 100%;
+}
+.file-uploader__zone {
+  --_fu--background: var(--sc-kit--file-uploader--background, var(--sc-kit--color--bg--field-alt));
+  --_fu--background-drag: var(--sc-kit--file-uploader--background--drag, var(--sc-kit--color--accent--softer));
+  --_fu--background-drag-invalid: var(--sc-kit--file-uploader--background--drag-invalid, var(--sc-kit--color--danger--soft));
+  --_fu--border-color: var(--sc-kit--file-uploader--border-color, var(--sc-kit--color--border--strong));
+  --_fu--border-color-drag: var(--sc-kit--file-uploader--border-color--drag, var(--sc-kit--color--accent));
+  --_fu--border-color-drag-invalid: var(--sc-kit--file-uploader--border-color--drag-invalid, var(--sc-kit--color--danger));
+  --_fu--border-radius: var(--sc-kit--file-uploader--border-radius, var(--sc-kit--radius--lg));
+  --_fu--padding: var(--sc-kit--file-uploader--padding, var(--sc-kit--space--6));
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--sc-kit--space--1);
+  text-align: center;
+  width: 100%;
+  padding: var(--_fu--padding);
+  background: var(--_fu--background);
+  border: 1.5px dashed var(--_fu--border-color);
+  border-radius: var(--_fu--border-radius);
+  color: var(--sc-kit--color--text--primary);
+  font-family: inherit;
+  cursor: pointer;
+  transition: background-color var(--sc-kit--duration--base) var(--sc-kit--ease--default), border-color var(--sc-kit--duration--base) var(--sc-kit--ease--default);
+}
+.file-uploader__zone:hover:not(:disabled), .file-uploader__zone--drag {
+  background: var(--_fu--background-drag);
+  border-color: var(--_fu--border-color-drag);
+}
+.file-uploader__zone--drag-invalid {
+  background: var(--_fu--background-drag-invalid);
+  border-color: var(--_fu--border-color-drag-invalid);
+  cursor: not-allowed;
+}
+.file-uploader__zone:disabled {
+  cursor: default;
+  opacity: 0.6;
+}
+.file-uploader__zone:focus-visible {
+  outline: 2px solid var(--sc-kit--color--border--focus);
+  outline-offset: 2px;
+}
+.file-uploader__icon, .file-uploader__title, .file-uploader__desc {
+  pointer-events: none;
+}
+.file-uploader__icon {
+  --sc-kit--icon--color: var(--sc-kit--file-uploader--icon--color, var(--sc-kit--color--text--muted));
+  --sc-kit--icon--size: var(--sc-kit--font-size--2xl);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin-bottom: var(--sc-kit--space--2);
+}
+.file-uploader__title {
+  font-size: var(--sc-kit--font-size--md);
+  font-weight: var(--sc-kit--font-weight--medium);
+  color: var(--sc-kit--file-uploader--title--color, var(--sc-kit--color--text--primary));
+}
+.file-uploader__desc {
+  font-size: var(--sc-kit--font-size--sm);
+  color: var(--sc-kit--file-uploader--description--color, var(--sc-kit--color--text--muted));
+}
+.file-uploader__input {
+  display: none;
+}</style>

package/dist/ui/file-uploader/cmp.file-uploader.svelte.d.ts

@@ -0,0 +1,56 @@
+import type { FileValidationResult, FileValidationRule } from '../../core/files';
+type Props = {
+    /** Allow multi-file selection. @default false */
+    multiple?: boolean;
+    /**
+     * Validation rules applied to each picked / dropped file. The native picker filter and
+     * drag-over visual hint are auto-derived from any `FileRules.Mime(...)` rule's `accept`
+     * — pass it once via the rule, the cmp wires the rest.
+     */
+    validationRules?: FileValidationRule[];
+    disabled?: boolean;
+    /** Headline shown inside the drop zone. */
+    title?: string;
+    /** Supporting text shown below the headline. */
+    description?: string;
+    on?: {
+        /**
+         * Fires after picker / drop with one `FileValidationResult` per file. Consumer reads
+         * `isValid` / `errors` per result and decides what to do (toast errors, queue valid
+         * files into an `UploadMediaStore`, etc.). The cmp does NOT render any error UI or
+         * progress visuals — those are composed externally next to the dropzone.
+         */
+        select?: (results: FileValidationResult[]) => void;
+    };
+};
+/**
+ * Drag-and-drop or click-to-select file zone. **Pure selector** — picks files, runs optional
+ * `validationRules`, and emits `on.select(FileValidationResult[])`. The consumer reads
+ * `isValid` / `errors` per result and decides what to do (toast, queue into an
+ * `UploadMediaStore`, etc.). The cmp renders neither error UI nor progress visuals — compose
+ * those externally next to the dropzone (e.g. `<FileRow>` / `<FileUploadProgress>` driven by
+ * `store.files`).
+ *
+ * The native picker filter + drag-over visual hint are derived from any `FileRules.Mime(...)`
+ * rule's `accept` — pass it once via the rule, the cmp wires both. During drag-over, files
+ * whose MIME does not match paint the zone with the danger color before drop (soft-validation
+ * via `DataTransfer.items` — extension-only accept tokens defer to drop).
+ *
+ * ### CSS Custom Properties
+ * | Property | Description | Default |
+ * |---|---|---|
+ * | `--sc-kit--file-uploader--background` | Drop-zone background | `var(--sc-kit--color--bg--field-alt)` |
+ * | `--sc-kit--file-uploader--background--drag` | Background during valid drag-over / hover | `var(--sc-kit--color--accent--softer)` |
+ * | `--sc-kit--file-uploader--background--drag-invalid` | Background when a dragged file's MIME does not match the Mime rule | `var(--sc-kit--color--danger--soft)` |
+ * | `--sc-kit--file-uploader--border-color` | Dashed border color (idle) | `var(--sc-kit--color--border--strong)` |
+ * | `--sc-kit--file-uploader--border-color--drag` | Dashed border color during valid drag-over / hover | `var(--sc-kit--color--accent)` |
+ * | `--sc-kit--file-uploader--border-color--drag-invalid` | Dashed border color when dragged file's MIME does not match the Mime rule | `var(--sc-kit--color--danger)` |
+ * | `--sc-kit--file-uploader--border-radius` | Drop-zone radius | `var(--sc-kit--radius--lg)` |
+ * | `--sc-kit--file-uploader--padding` | Inner padding | `var(--sc-kit--space--6)` |
+ * | `--sc-kit--file-uploader--icon--color` | Icon color | `var(--sc-kit--color--text--muted)` |
+ * | `--sc-kit--file-uploader--title--color` | Title color | `var(--sc-kit--color--text--primary)` |
+ * | `--sc-kit--file-uploader--description--color` | Description color | `var(--sc-kit--color--text--muted)` |
+ */
+declare const Cmp: import("svelte").Component<Props, {}, "">;
+type Cmp = ReturnType<typeof Cmp>;
+export default Cmp;

package/dist/ui/file-uploader/file-type-colors.d.ts

@@ -0,0 +1,3 @@
+export declare const fileTypeColors: Record<string, string>;
+export declare const fileTypeFromName: (name: string) => string;
+export declare const fileTypeColor: (type: string) => string;

package/dist/ui/file-uploader/file-type-colors.js

@@ -0,0 +1,38 @@
+// Stamp colors for file-type extensions (used by FileUploadProgress). Distinct from the
+// project-wide semantic palette — these are per-extension brand-ish tints that map filename
+// extensions to a stable color. Override per-instance via the `--sc-kit--file-upload-progress--accent`
+// CSS variable.
+export const fileTypeColors = {
+    pdf: '#e15554',
+    doc: '#144ab0',
+    docx: '#144ab0',
+    xls: '#10b981',
+    xlsx: '#10b981',
+    csv: '#10b981',
+    ppt: '#e0772e',
+    pptx: '#e0772e',
+    zip: '#f5a623',
+    rar: '#f5a623',
+    fig: '#1abc9c',
+    sketch: '#fdb022',
+    png: '#8b5cf6',
+    jpg: '#8b5cf6',
+    jpeg: '#8b5cf6',
+    gif: '#8b5cf6',
+    svg: '#7c3aed',
+    mp4: '#ec4899',
+    mov: '#ec4899',
+    mp3: '#f97066',
+    wav: '#f97066',
+    txt: '#6b7280',
+    md: '#6b7280',
+    json: '#7c3aed',
+    html: '#e0772e',
+    js: '#eab308',
+    ts: '#3178c6'
+};
+export const fileTypeFromName = (name) => {
+    const dot = name.lastIndexOf('.');
+    return dot >= 0 ? name.slice(dot + 1).toLowerCase() : '';
+};
+export const fileTypeColor = (type) => fileTypeColors[type.toLowerCase()] ?? '#6b7280';

package/dist/ui/file-uploader/file-uploader-localization.d.ts

@@ -0,0 +1,4 @@
+export declare class FileUploaderLocalization {
+    get uploadingHint(): string;
+    removeAria(name: string): string;
+}

package/dist/ui/file-uploader/file-uploader-localization.js

@@ -0,0 +1,19 @@
+import { AppLocale } from '../../core/locale';
+const loc = {
+    uploadingHint: {
+        en: 'uploading…',
+        no: 'laster opp…'
+    },
+    removeAria: {
+        en: 'Remove {name}',
+        no: 'Fjern {name}'
+    }
+};
+export class FileUploaderLocalization {
+    get uploadingHint() {
+        return loc.uploadingHint[AppLocale.current];
+    }
+    removeAria(name) {
+        return loc.removeAria[AppLocale.current].replace('{name}', name);
+    }
+}

package/dist/ui/file-uploader/index.d.ts

@@ -0,0 +1,6 @@
+export { default as FileRow } from './cmp.file-row.svelte';
+export { default as FileUploader } from './cmp.file-uploader.svelte';
+export { default as FileUploadProgress } from './cmp.file-upload-progress.svelte';
+export { FileUploaderLocalization } from './file-uploader-localization';
+export { fileTypeColor, fileTypeColors, fileTypeFromName } from './file-type-colors';
+export { toUploadingFile } from './to-uploading-file';

package/dist/ui/file-uploader/index.js

@@ -0,0 +1,6 @@
+export { default as FileRow } from './cmp.file-row.svelte';
+export { default as FileUploader } from './cmp.file-uploader.svelte';
+export { default as FileUploadProgress } from './cmp.file-upload-progress.svelte';
+export { FileUploaderLocalization } from './file-uploader-localization';
+export { fileTypeColor, fileTypeColors, fileTypeFromName } from './file-type-colors';
+export { toUploadingFile } from './to-uploading-file';

package/dist/ui/file-uploader/to-uploading-file.d.ts

@@ -0,0 +1,7 @@
+import type { UploadingFile, UploadingFileStatus } from '../../core/files';
+/**
+ * Wrap a raw `File` into an `UploadingFile` for ad-hoc rendering with `FileRow` /
+ * `FileUploadProgress` (e.g. static read-only file lists, mocks in stories). Defaults to
+ * `status: 'success'` and `progress: 1` — i.e. "already complete, just show me".
+ */
+export declare const toUploadingFile: (file: File, status?: UploadingFileStatus) => UploadingFile;

package/dist/ui/file-uploader/to-uploading-file.js

@@ -0,0 +1,12 @@
+import { nanoid } from 'nanoid';
+/**
+ * Wrap a raw `File` into an `UploadingFile` for ad-hoc rendering with `FileRow` /
+ * `FileUploadProgress` (e.g. static read-only file lists, mocks in stories). Defaults to
+ * `status: 'success'` and `progress: 1` — i.e. "already complete, just show me".
+ */
+export const toUploadingFile = (file, status = 'success') => ({
+    id: nanoid(),
+    file,
+    progress: status === 'success' ? 1 : 0,
+    status
+});

package/dist/ui/form-field/cmp.form-field-validatable.svelte

@@ -0,0 +1,42 @@
+<script lang="ts" generics="T extends Record<string, unknown>, K extends keyof T & string">import { Validatable } from '../validatable';
+import { default as FormField } from './cmp.form-field.svelte';
+let { handler, name, label, required = false, validateOn, debounceMs, disableTouchedTracking, on, children } = $props();
+</script>
+
+<FormField label={label} required={required}>
+  <Validatable
+    handler={handler}
+    name={name}
+    validateOn={validateOn}
+    debounceMs={debounceMs}
+    disableTouchedTracking={disableTouchedTracking}
+    on={on}
+    children={children} />
+</FormField>
+
+<!--
+@component
+FormFieldValidatable — convenience wrapper that composes `<FormField>` and `<Validatable>` in a single component. Reduces the 3-level nesting (FormField → Validatable → Input) to a flat callsite when you need both a label and validation binding.
+
+### Usage
+```svelte
+<FormFieldValidatable {handler} name="email" label="Email" required>
+  {#snippet children(field)}
+    <Input {...field} type="email" placeholder="you@example.com" />
+  {/snippet}
+</FormFieldValidatable>
+```
+
+Identical visual output to:
+```svelte
+<FormField label="Email" required>
+  <Validatable {handler} name="email">
+    {#snippet children(field)}
+      <Input {...field} type="email" placeholder="you@example.com" />
+    {/snippet}
+  </Validatable>
+</FormField>
+```
+
+Both `FormField`'s label/required and `Validatable`'s no-jump error slot apply unchanged — this cmp adds no styling, just collapses the wiring.
+-->

package/dist/ui/form-field/cmp.form-field-validatable.svelte.d.ts

@@ -0,0 +1,75 @@
+import type { FormValidationHandler } from '../../core/validation';
+import { type FieldBinding, type ValidateOnEvent } from '../validatable';
+import type { Snippet } from 'svelte';
+declare function $$render<T extends Record<string, unknown>, K extends keyof T & string>(): {
+    props: {
+        /** Form validation handler instance. */
+        handler: FormValidationHandler<T>;
+        /** Field name in the form handler. */
+        name: K;
+        /** Label rendered above the input. String renders as text; Snippet allows extra content (e.g. tooltip icon) next to the text. */
+        label?: string | Snippet;
+        /** Appends a danger-colored `*` to the label. */
+        required?: boolean;
+        /** Which events trigger validation. Forwarded to `<Validatable>`. @default ['input', 'change', 'blur'] */
+        validateOn?: ValidateOnEvent[];
+        /** Debounce validator calls in ms. Forwarded to `<Validatable>`. @default 0 */
+        debounceMs?: number;
+        /** Show errors before the field has been touched. Forwarded to `<Validatable>`. @default false */
+        disableTouchedTracking?: boolean;
+        /** Extra consumer callbacks. Forwarded to `<Validatable>`. */
+        on?: {
+            input?: (value: T[K]) => void;
+            change?: (value: T[K]) => void;
+            blur?: () => void;
+        };
+        /** Receives the wired `FieldBinding<T[K]>` — spread or wire onto the kit input. */
+        children: Snippet<[FieldBinding<T[K]>]>;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends Record<string, unknown>, K extends keyof T & string> {
+    props(): ReturnType<typeof $$render<T, K>>['props'];
+    events(): ReturnType<typeof $$render<T, K>>['events'];
+    slots(): ReturnType<typeof $$render<T, K>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends Record<string, unknown>, K extends keyof T & string>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T, K>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T, K>['props']>, ReturnType<__sveltets_Render<T, K>['events']>, ReturnType<__sveltets_Render<T, K>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T, K>['bindings']>;
+    } & ReturnType<__sveltets_Render<T, K>['exports']>;
+    <T extends Record<string, unknown>, K extends keyof T & string>(internal: unknown, props: ReturnType<__sveltets_Render<T, K>['props']> & {}): ReturnType<__sveltets_Render<T, K>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any, any>['bindings']>;
+}
+/**
+ * FormFieldValidatable — convenience wrapper that composes `<FormField>` and `<Validatable>` in a single component. Reduces the 3-level nesting (FormField → Validatable → Input) to a flat callsite when you need both a label and validation binding.
+ *
+ * ### Usage
+ * ```svelte
+ * <FormFieldValidatable {handler} name="email" label="Email" required>
+ * {#snippet children(field)}
+ *   <Input {...field} type="email" placeholder="you@example.com" />
+ * {/snippet}
+ * </FormFieldValidatable>
+ * ```
+ *
+ * Identical visual output to:
+ * ```svelte
+ * <FormField label="Email" required>
+ * <Validatable {handler} name="email">
+ *   {#snippet children(field)}
+ *     <Input {...field} type="email" placeholder="you@example.com" />
+ *   {/snippet}
+ * </Validatable>
+ * </FormField>
+ * ```
+ *
+ * Both `FormField`'s label/required and `Validatable`'s no-jump error slot apply unchanged — this cmp adds no styling, just collapses the wiring.
+ */
+declare const Cmp: $$IsomorphicComponent;
+type Cmp<T extends Record<string, unknown>, K extends keyof T & string> = InstanceType<typeof Cmp<T, K>>;
+export default Cmp;

package/dist/ui/form-field/cmp.form-field.svelte

@@ -0,0 +1,55 @@
+<script lang="ts">let { label, required = false, children } = $props();
+const isLabelString = $derived(typeof label === 'string');
+export {};
+</script>
+
+<label class="form-field">
+  {#if label}
+    <span class="form-field__label">
+      {#if isLabelString}
+        {label}
+      {:else}
+        {@render (label as Snippet)()}
+      {/if}
+      {#if required}<span class="form-field__required" aria-hidden="true">*</span>{/if}
+    </span>
+  {/if}
+
+  {@render children()}
+</label>
+
+<!--
+@component
+FormField — pure layout shell: optional label (string or snippet) above an input slot. The root is a `<label>` element, so the first labelable form control inside is automatically associated via HTML's implicit-association rule — no id wiring required. Does NOT render errors or helper text; pair with `Validatable` for that.
+
+### CSS Custom Properties
+| Property | Description | Default |
+|---|---|---|
+| `--sc-kit--form-field--gap` | Vertical gap between label and the input slot | `0.375rem` (6px) |
+| `--sc-kit--form-field--label--color` | Label text color | `--sc-kit--color--text--primary` |
+| `--sc-kit--form-field--label--font-size` | Label font size | `--sc-kit--font-size--sm` |
+| `--sc-kit--form-field--label--font-weight` | Label font weight | `--sc-kit--font-weight--medium` |
+| `--sc-kit--form-field--required--color` | Required `*` color | `--sc-kit--color--danger` |
+-->
+
+<style>.form-field {
+  --_ff--gap: var(--sc-kit--form-field--gap, 0.375rem);
+  --_ff--label-color: var(--sc-kit--form-field--label--color, var(--sc-kit--color--text--primary));
+  --_ff--label-font-size: var(--sc-kit--form-field--label--font-size, var(--sc-kit--font-size--sm));
+  --_ff--label-font-weight: var(--sc-kit--form-field--label--font-weight, var(--sc-kit--font-weight--medium));
+  --_ff--required-color: var(--sc-kit--form-field--required--color, var(--sc-kit--color--danger));
+  display: flex;
+  flex-direction: column;
+  gap: var(--_ff--gap);
+}
+.form-field__label {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  color: var(--_ff--label-color);
+  font-size: var(--_ff--label-font-size);
+  font-weight: var(--_ff--label-font-weight);
+}
+.form-field__required {
+  color: var(--_ff--required-color);
+}</style>

package/dist/ui/form-field/cmp.form-field.svelte.d.ts

@@ -0,0 +1,24 @@
+import type { Snippet } from 'svelte';
+type Props = {
+    /** Label rendered above the input. String renders as text; Snippet allows extra content (e.g. tooltip icon) next to the text. */
+    label?: string | Snippet;
+    /** Appends a danger-colored `*` to the label. Purely visual — does not enforce anything. */
+    required?: boolean;
+    /** Input slot. The wrapping `<label>` implicitly associates with the first labelable control inside (HTML standard), so no id wiring is needed. */
+    children: Snippet;
+};
+/**
+ * FormField — pure layout shell: optional label (string or snippet) above an input slot. The root is a `<label>` element, so the first labelable form control inside is automatically associated via HTML's implicit-association rule — no id wiring required. Does NOT render errors or helper text; pair with `Validatable` for that.
+ *
+ * ### CSS Custom Properties
+ * | Property | Description | Default |
+ * |---|---|---|
+ * | `--sc-kit--form-field--gap` | Vertical gap between label and the input slot | `0.375rem` (6px) |
+ * | `--sc-kit--form-field--label--color` | Label text color | `--sc-kit--color--text--primary` |
+ * | `--sc-kit--form-field--label--font-size` | Label font size | `--sc-kit--font-size--sm` |
+ * | `--sc-kit--form-field--label--font-weight` | Label font weight | `--sc-kit--font-weight--medium` |
+ * | `--sc-kit--form-field--required--color` | Required `*` color | `--sc-kit--color--danger` |
+ */
+declare const Cmp: import("svelte").Component<Props, {}, "">;
+type Cmp = ReturnType<typeof Cmp>;
+export default Cmp;

package/dist/ui/form-field/index.d.ts

@@ -0,0 +1,2 @@
+export { default as FormField } from './cmp.form-field.svelte';
+export { default as FormFieldValidatable } from './cmp.form-field-validatable.svelte';

package/dist/ui/form-field/index.js

@@ -0,0 +1,2 @@
+export { default as FormField } from './cmp.form-field.svelte';
+export { default as FormFieldValidatable } from './cmp.form-field-validatable.svelte';