@warkypublic/svelix 0.2.1 → 0.2.3

package/README.md

@@ -32,8 +32,11 @@ import { Button, Former, Gridler } from '@warkypublic/svelix';
 | `ButtonCtrl`, `IconButtonCtrl` | Button and icon-button form controls |
 | `TextInputCtrl`, `TextAreaCtrl`, `PasswordInputCtrl` | Text input controls |
 | `NumberInputCtrl`, `NativeSelectCtrl` | Number and select controls |
-| `SwitchCtrl`, `DateTimeCtrl` | Toggle and date/time picker controls |
-| `InlineWrapper` | Inline layout wrapper for form controls |
+| `CheckBoxCtrl`, `SwitchCtrl` | Checkbox and toggle controls; `CheckBoxCtrl` supports checkbox or switch presentation and boolean, integer, or string values |
+| `FileInputCtrl` | Single-file picker with a compact file-type or image thumbnail, filename, and size |
+| `JsonCtrl` | JSON editor control with a dialog editor and preview |
+| `DateTimeCtrl` | Date/time picker control |
+| `CtrlFieldShell`, `InlineWrapper` | Field shell and inline layout wrapper for form controls |
 
 ### Data Grids
 | Export | Description |
@@ -59,6 +62,10 @@ import { Button, Former, Gridler } from '@warkypublic/svelix';
 | Export | Description |
 |---|---|
 | `ContentEditor` | Rich content editor (Carta Markdown + Monaco) |
+| `TextEditor`, `MarkdownViewer`, `MonacoEditor` | Text, Markdown, and code editing components |
+| `CollaboraEditor`, `Office365Editor` | Office document editor integrations |
+| `ImageViewer`, `AudioPlayer`, `VideoPlayer`, `PdfViewer` | File media and PDF viewers |
+| `EmailViewer`, `ZipViewer`, `UnknownFile` | Fallback file viewers |
 
 ### Trees
 | Export | Description |
@@ -98,6 +105,7 @@ Extended architecture and implementation docs are published with the package und
 node_modules/@warkypublic/svelix/llm/README.md
 node_modules/@warkypublic/svelix/llm/ARCHITECTURE.md
 node_modules/@warkypublic/svelix/llm/COMPONENT_GUIDE.md
+node_modules/@warkypublic/svelix/llm/FORMER_CONTROLLERS.md
 ```
 
 ## Development

package/dist/components/Boxer/Boxer.svelte

@@ -405,6 +405,9 @@ function onOptionPointerDown(e, index) {
 function syncInsideDialogFlag() {
 	insideDialog = !!anchorEl?.closest("dialog, [role=\"dialog\"]");
 }
+function isSvgIcon(value) {
+	return value?.trimStart?.().startsWith?.("<svg");
+}
 // Public API via bind:this
 export function clear() {
 	onClear();
@@ -625,6 +628,14 @@ $effect(() => {
                         type="checkbox"
                       />
                     {/if}
+                    {#if item?.icon}
+                      {#if isSvgIcon(item.icon)}
+                        <!-- eslint-disable-next-line svelte/no-at-html-tags -->
+                        <span class="size-4 flex items-center shrink-0">{@html item.icon}</span>
+                      {:else}
+                        <span class="shrink-0">{item.icon}</span>
+                      {/if}
+                    {/if}
                     <span>{item?.label}</span>
                   </div>
                 {/each}

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

@@ -42,6 +42,8 @@ export type BoxerItem = {
     [key: string]: any;
     label: string;
     value: any;
+    /** Optional icon rendered before the label in the dropdown list. Accepts an SVG string (rendered raw) or plain text/emoji. */
+    icon?: string;
 };
 export interface BoxerProps {
     /** Server adapter (ResolveSpec or HeaderSpec). Automatically sets `dataSource` to `'server'` when provided. */

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

@@ -1,2 +1,14 @@
 export { default as ContentEditor } from './ContentEditor.svelte';
+export { default as AudioPlayer } from './subcomponents/AudioPlayer.svelte';
+export { default as CollaboraEditor } from './subcomponents/CollaboraEditor.svelte';
+export { default as EmailViewer } from './subcomponents/EmailViewer.svelte';
+export { default as ImageViewer } from './subcomponents/ImageViewer.svelte';
+export { default as MarkdownViewer } from './subcomponents/MarkdownViewer.svelte';
+export { default as MonacoEditor } from './subcomponents/MonacoEditor.svelte';
+export { default as Office365Editor } from './subcomponents/Office365Editor.svelte';
+export { default as PdfViewer } from './subcomponents/PdfViewer.svelte';
+export { default as TextEditor } from './subcomponents/TextEditor.svelte';
+export { default as UnknownFile } from './subcomponents/UnknownFile.svelte';
+export { default as VideoPlayer } from './subcomponents/VideoPlayer.svelte';
+export { default as ZipViewer } from './subcomponents/ZipViewer.svelte';
 export * from './types.js';

package/dist/components/ContentEditor/index.js

@@ -1,2 +1,14 @@
 export { default as ContentEditor } from './ContentEditor.svelte';
+export { default as AudioPlayer } from './subcomponents/AudioPlayer.svelte';
+export { default as CollaboraEditor } from './subcomponents/CollaboraEditor.svelte';
+export { default as EmailViewer } from './subcomponents/EmailViewer.svelte';
+export { default as ImageViewer } from './subcomponents/ImageViewer.svelte';
+export { default as MarkdownViewer } from './subcomponents/MarkdownViewer.svelte';
+export { default as MonacoEditor } from './subcomponents/MonacoEditor.svelte';
+export { default as Office365Editor } from './subcomponents/Office365Editor.svelte';
+export { default as PdfViewer } from './subcomponents/PdfViewer.svelte';
+export { default as TextEditor } from './subcomponents/TextEditor.svelte';
+export { default as UnknownFile } from './subcomponents/UnknownFile.svelte';
+export { default as VideoPlayer } from './subcomponents/VideoPlayer.svelte';
+export { default as ZipViewer } from './subcomponents/ZipViewer.svelte';
 export * from './types.js';

package/dist/components/FormerControllers/CheckBoxCtrl.svelte

@@ -0,0 +1,77 @@
+<script lang="ts">import { makeFieldId } from "./utils";
+let { checked = $bindable(false), dataFormat = "boolean", disabled, error, label, name, onchange, required, sid, tooltip, type = "checkbox" } = $props();
+const id = $derived(makeFieldId(name, sid));
+const errorId = $derived(`${id}-error`);
+const inputChecked = $derived(toBoolean(checked, dataFormat));
+function toBoolean(value, format) {
+	if (format === "integer") return value === 1;
+	if (format === "string") {
+		return typeof value === "string" && [
+			"1",
+			"true",
+			"yes"
+		].includes(value.trim().toLowerCase());
+	}
+	return value === true;
+}
+function formatValue(value) {
+	if (dataFormat === "integer") return value ? 1 : 0;
+	if (dataFormat === "string") return value ? "true" : "false";
+	return value;
+}
+function handleChange(event) {
+	checked = formatValue(event.currentTarget.checked);
+	onchange?.(checked);
+}
+</script>
+
+<div class="flex flex-col gap-1" title={tooltip}>
+	{#if type === 'switch'}
+		<label class="flex w-fit cursor-pointer items-center gap-2" for={id}>
+			<input
+				{id}
+				{disabled}
+				{name}
+				{required}
+				aria-describedby={error ? errorId : undefined}
+				aria-invalid={!!error}
+				aria-checked={inputChecked}
+				checked={inputChecked}
+				class="peer sr-only"
+				role="switch"
+				type="checkbox"
+				onchange={handleChange}
+			/>
+			<span
+				aria-hidden="true"
+				class="flex h-6 w-10 items-center rounded-full bg-surface-300-700 p-0.5 transition-colors peer-checked:[&>span]:translate-x-4 peer-checked:bg-primary-500 peer-disabled:cursor-not-allowed peer-disabled:opacity-50 peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:outline-primary-500"
+			>
+				<span class="size-5 rounded-full bg-surface-50 transition-transform"></span>
+			</span>
+			{#if label}
+				<span class="label text-sm">{label}{#if required}<span class="text-error-500">*</span>{/if}</span>
+			{/if}
+		</label>
+	{:else}
+		<div class="flex items-center gap-2">
+			<input
+				{id}
+				{disabled}
+				{name}
+				{required}
+				aria-describedby={error ? errorId : undefined}
+				aria-invalid={!!error}
+				checked={inputChecked}
+				class="checkbox"
+				type="checkbox"
+				onchange={handleChange}
+			/>
+			{#if label}
+				<label class="label text-sm" for={id}>{label}{#if required}<span class="text-error-500">*</span>{/if}</label>
+			{/if}
+		</div>
+	{/if}
+	{#if error}
+		<p class="text-error-500 text-xs" id={errorId}>{error}</p>
+	{/if}
+</div>

package/dist/components/FormerControllers/CheckBoxCtrl.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { CtrlBaseProps } from './types';
+export type CheckBoxCtrlValue = boolean | 0 | 1 | string | null;
+export interface Props extends Omit<CtrlBaseProps, 'placeholder'> {
+    checked?: CheckBoxCtrlValue;
+    dataFormat?: 'boolean' | 'integer' | 'string';
+    onchange?: (checked: CheckBoxCtrlValue) => void;
+    type?: 'checkbox' | 'switch';
+}
+declare const CheckBoxCtrl: import("svelte").Component<Props, {}, "checked">;
+type CheckBoxCtrl = ReturnType<typeof CheckBoxCtrl>;
+export default CheckBoxCtrl;

package/dist/components/FormerControllers/FileInputCtrl.svelte

@@ -0,0 +1,106 @@
+<script lang="ts">import CtrlFieldShell from "./CtrlFieldShell.svelte";
+import { makeFieldId } from "./utils";
+let { accept, disabled, error, label, name, onchange, required, sid, tooltip, value = $bindable(null) } = $props();
+let imageUrl = $state(null);
+const id = $derived(makeFieldId(name, sid));
+const isImage = $derived(value?.type.startsWith("image/") ?? false);
+const fileType = $derived(getFileType(value));
+$effect(() => {
+	if (!value || !isImage) {
+		imageUrl = null;
+		return;
+	}
+	const url = URL.createObjectURL(value);
+	imageUrl = url;
+	return () => URL.revokeObjectURL(url);
+});
+function handleChange(event) {
+	value = event.currentTarget.files?.[0] ?? null;
+	onchange?.(value);
+}
+function getFileType(file) {
+	if (!file) return "FILE";
+	if (file.type.startsWith("image/")) return "IMG";
+	if (file.type.startsWith("video/")) return "VID";
+	if (file.type.startsWith("audio/")) return "AUD";
+	if (file.type === "application/pdf") return "PDF";
+	const extension = file.name.split(".").pop()?.toLowerCase();
+	if ([
+		"doc",
+		"docx",
+		"odt",
+		"rtf"
+	].includes(extension ?? "")) return "DOC";
+	if ([
+		"xls",
+		"xlsx",
+		"ods",
+		"csv"
+	].includes(extension ?? "")) return "SHEET";
+	if ([
+		"ppt",
+		"pptx",
+		"odp"
+	].includes(extension ?? "")) return "SLIDE";
+	if ([
+		"zip",
+		"rar",
+		"7z",
+		"tar",
+		"gz"
+	].includes(extension ?? "")) return "ZIP";
+	if ([
+		"txt",
+		"md",
+		"json",
+		"xml",
+		"yaml",
+		"yml",
+		"js",
+		"ts",
+		"css",
+		"html"
+	].includes(extension ?? "")) {
+		return "TEXT";
+	}
+	return extension?.slice(0, 5).toUpperCase() || "FILE";
+}
+function formatSize(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+</script>
+
+<CtrlFieldShell {error} {id} {label} {required} {tooltip}>
+	<div class="flex min-w-0 items-center gap-3 rounded-container-token border border-surface-200-800 bg-surface-50-900 p-2">
+		<input {accept} {disabled} {id} {name} {required} class="sr-only" type="file" onchange={handleChange} />
+		{#if imageUrl && value}
+			<img alt={`Preview of ${value.name}`} class="size-9 shrink-0 rounded object-cover" src={imageUrl} />
+		{:else}
+			<div
+				aria-label={`${fileType} file preview`}
+				class="flex size-9 shrink-0 items-center justify-center rounded bg-primary-100-900 text-center text-[10px] font-bold tracking-wide text-primary-700-300"
+				role="img"
+			>
+				{fileType}
+			</div>
+		{/if}
+		<div class="min-w-0 flex-1">
+			{#if value}
+				<p class="truncate text-sm font-medium" title={value.name}>{value.name}</p>
+				<p class="text-xs text-surface-500-400">{formatSize(value.size)}</p>
+			{:else}
+				<p class="truncate text-sm text-surface-500-400">No file selected</p>
+			{/if}
+		</div>
+		<label
+			class="btn preset-outlined-primary-500 shrink-0"
+			class:cursor-not-allowed={disabled}
+			class:opacity-50={disabled}
+			for={id}
+		>
+			{value ? 'Replace file' : 'Choose file'}
+		</label>
+	</div>
+</CtrlFieldShell>

package/dist/components/FormerControllers/FileInputCtrl.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { CtrlBaseProps } from './types';
+export interface Props extends Omit<CtrlBaseProps, 'placeholder'> {
+    accept?: string;
+    onchange?: (value: File | null) => void;
+    value?: File | null;
+}
+declare const FileInputCtrl: import("svelte").Component<Props, {}, "value">;
+type FileInputCtrl = ReturnType<typeof FileInputCtrl>;
+export default FileInputCtrl;

package/dist/components/FormerControllers/InlineWrapper.svelte

@@ -16,13 +16,13 @@ const showWarningIcon = $derived(!error && !!required && isEmpty);
 	<div class="flex flex-nowrap gap-0">
 			{#if labelWidth && (label || promptArea)}
 				<div
-					class="flex items-center px-3 border border-surface-300 dark:border-surface-600 rounded-l bg-surface-100 dark:bg-surface-800"
+					class="flex items-center px-3 bg-primary-100-900 text-primary-950-50 select-none"
 					style:min-width={labelWidth}
 				>
 					{#if promptArea}
 						{@render promptArea()}
 					{:else if typeof label === 'string'}
-						<span class="inline-flex items-center gap-1.5 text-xs font-medium text-surface-700 dark:text-surface-300">
+						<span class="inline-flex items-center gap-1.5 text-xs font-medium">
 							{label}{#if required && isEmpty}<span class="text-error-500">*</span>{/if}
 							{#if showErrorIcon}
 								<IconAlertCircle size={14} class="text-error-500" />

package/dist/components/FormerControllers/JsonCtrl/JsonCtrl.svelte

@@ -0,0 +1,61 @@
+<script lang="ts">import CtrlFieldShell from "../CtrlFieldShell.svelte";
+import { makeFieldId } from "../utils";
+import { iconEyeSvg } from "../../Icons/strings";
+import JsonCtrlEditorDialog from "./JsonCtrlEditorDialog.svelte";
+let { disabled, error, label, name, onchange, required, sid, tooltip, value = $bindable(undefined) } = $props();
+const id = $derived(makeFieldId(name, sid));
+let dialogOpen = $state(false);
+const preview = $derived.by(() => {
+	if (value === undefined) return {
+		text: "Empty",
+		empty: true
+	};
+	try {
+		const text = JSON.stringify(value);
+		return {
+			text: text.length > 80 ? `${text.slice(0, 80)}…` : text,
+			empty: false
+		};
+	} catch {
+		return {
+			text: "(unserializable)",
+			empty: true
+		};
+	}
+});
+function openDialog() {
+	if (disabled) return;
+	dialogOpen = true;
+}
+function handleSave(parsed) {
+	value = parsed;
+	onchange?.(parsed);
+}
+</script>
+
+<CtrlFieldShell {error} {id} {label} {required} {tooltip}>
+  <button
+    {id}
+    {disabled}
+    class="input flex items-center justify-between gap-2 text-left"
+    class:input-error={!!error}
+    type="button"
+    onclick={openDialog}
+  >
+    <code
+      class="truncate text-xs font-mono"
+      class:text-surface-500={preview.empty}
+    >{preview.text}</code>
+    <span class="shrink-0 flex items-center" aria-hidden="true">
+      <!-- eslint-disable-next-line svelte/no-at-html-tags -->
+      {@html iconEyeSvg}
+    </span>
+  </button>
+</CtrlFieldShell>
+
+<JsonCtrlEditorDialog
+  bind:open={dialogOpen}
+  {label}
+  {value}
+  onsave={handleSave}
+/>

package/dist/components/FormerControllers/JsonCtrl/JsonCtrl.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { CtrlBaseProps } from '../types';
+export interface Props extends CtrlBaseProps {
+    onchange?: (value: unknown) => void;
+    value?: unknown;
+}
+declare const JsonCtrl: import("svelte").Component<Props, {}, "value">;
+type JsonCtrl = ReturnType<typeof JsonCtrl>;
+export default JsonCtrl;

package/dist/components/FormerControllers/JsonCtrl/JsonCtrlEditorDialog.svelte

@@ -0,0 +1,72 @@
+<script lang="ts">import { Dialog, Portal } from "@skeletonlabs/skeleton-svelte";
+import { createOverlayZIndex } from "../../Former/formerOverlayHelpers.svelte";
+import JsonCtrlMonaco from "./JsonCtrlMonaco.svelte";
+let { label, open = $bindable(false), value, onsave } = $props();
+let draftText = $state("");
+let parseError = $state(undefined);
+let wasOpen = false;
+$effect(() => {
+	if (open && !wasOpen) {
+		draftText = JSON.stringify(value ?? null, null, 2);
+		parseError = undefined;
+	}
+	wasOpen = open;
+});
+const overlayZ = createOverlayZIndex("dialog", () => open);
+function handleSave() {
+	try {
+		const parsed = draftText.trim() === "" ? null : JSON.parse(draftText);
+		parseError = undefined;
+		onsave?.(parsed);
+		open = false;
+	} catch (err) {
+		parseError = err instanceof Error ? err.message : "Invalid JSON";
+	}
+}
+function handleCancel() {
+	open = false;
+}
+</script>
+
+<Dialog
+  open={open}
+  onOpenChange={(e) => {
+    open = e.open;
+  }}
+  closeOnInteractOutside={false}
+  modal
+>
+  <Portal>
+    <Dialog.Backdrop
+      class="fixed inset-0 bg-black/50 backdrop-blur-sm"
+      style={`z-index:${overlayZ.backdropZ};`}
+    />
+    <Dialog.Positioner class="fixed inset-0 flex" style={`z-index:${overlayZ.contentZ};`}>
+      <Dialog.Content class="bg-surface-100-900 shadow-2xl w-full h-full flex flex-col overflow-hidden">
+        <header class="flex items-center justify-between px-6 pt-5 pb-4 border-b border-surface-300-600 shrink-0">
+          <Dialog.Title class="text-lg font-semibold">{label ? `Edit ${label}` : 'Edit JSON'}</Dialog.Title>
+          <Dialog.CloseTrigger class="btn-icon btn-icon-sm preset-tonal" aria-label="Close dialog" onclick={handleCancel}>
+            ✕
+          </Dialog.CloseTrigger>
+        </header>
+
+        <div class="flex-1 min-h-0 overflow-hidden p-4">
+          <JsonCtrlMonaco value={draftText} onchange={(text) => (draftText = text)} height="100%" />
+        </div>
+
+        {#if parseError}
+          <p class="text-error-500 text-xs px-6 pb-2" role="alert">{parseError}</p>
+        {/if}
+
+        <div class="flex items-center justify-end gap-2 p-4 border-t border-surface-300-600 shrink-0">
+          <button class="btn preset-filled-secondary-500" type="button" onclick={handleCancel}>
+            ✕ Cancel
+          </button>
+          <button class="btn preset-filled-primary-500" type="button" onclick={handleSave}>
+            💾 Save
+          </button>
+        </div>
+      </Dialog.Content>
+    </Dialog.Positioner>
+  </Portal>
+</Dialog>

package/dist/components/FormerControllers/JsonCtrl/JsonCtrlEditorDialog.svelte.d.ts

@@ -0,0 +1,9 @@
+export interface Props {
+    label?: string;
+    open?: boolean;
+    value?: unknown;
+    onsave?: (value: unknown) => void;
+}
+declare const JsonCtrlEditorDialog: import("svelte").Component<Props, {}, "open">;
+type JsonCtrlEditorDialog = ReturnType<typeof JsonCtrlEditorDialog>;
+export default JsonCtrlEditorDialog;

package/dist/components/FormerControllers/JsonCtrl/JsonCtrlMonaco.svelte

@@ -0,0 +1,45 @@
+<script lang="ts">import { onMount } from "svelte";
+import * as monaco from "monaco-editor";
+import { watchSkeletonDarkMode } from "../../ContentEditor/utils";
+let { value, height = "320px", onchange } = $props();
+let container = $state(undefined);
+let editor;
+let changeGuard = false;
+let isDark = $state(false);
+onMount(() => {
+	const stopWatchingTheme = watchSkeletonDarkMode(container, (nextIsDark) => {
+		isDark = nextIsDark;
+	});
+	if (!container) return;
+	editor = monaco.editor.create(container, {
+		value,
+		language: "json",
+		theme: isDark ? "vs-dark" : "vs",
+		automaticLayout: true,
+		minimap: { enabled: false }
+	});
+	const createdEditor = editor;
+	createdEditor.onDidChangeModelContent(() => {
+		if (changeGuard) return;
+		onchange?.(createdEditor.getValue());
+	});
+	return () => {
+		stopWatchingTheme();
+		editor?.dispose();
+		editor = undefined;
+	};
+});
+// Sync external value changes (e.g. dialog re-opened with different data) into the editor.
+$effect(() => {
+	const next = value;
+	if (!editor || editor.getValue() === next) return;
+	changeGuard = true;
+	editor.setValue(next);
+	changeGuard = false;
+});
+$effect(() => {
+	monaco.editor.setTheme(isDark ? "vs-dark" : "vs");
+});
+</script>
+
+<div bind:this={container} style="width: 100%; height: {height};"></div>

package/dist/components/FormerControllers/JsonCtrl/JsonCtrlMonaco.svelte.d.ts

@@ -0,0 +1,8 @@
+export interface Props {
+    value: string;
+    height?: string;
+    onchange?: (text: string) => void;
+}
+declare const JsonCtrlMonaco: import("svelte").Component<Props, {}, "">;
+type JsonCtrlMonaco = ReturnType<typeof JsonCtrlMonaco>;
+export default JsonCtrlMonaco;

package/dist/components/FormerControllers/JsonCtrl/index.d.ts

@@ -0,0 +1 @@
+export { default as JsonCtrl } from './JsonCtrl.svelte';

package/dist/components/FormerControllers/JsonCtrl/index.js

@@ -0,0 +1 @@
+export { default as JsonCtrl } from './JsonCtrl.svelte';

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

@@ -1,8 +1,11 @@
 export { default as ButtonCtrl } from './ButtonCtrl.svelte';
+export { default as CheckBoxCtrl } from './CheckBoxCtrl.svelte';
 export { default as CtrlFieldShell } from './CtrlFieldShell.svelte';
 export { DateTimeCtrl } from './DateTimeCtrl/index';
+export { default as FileInputCtrl } from './FileInputCtrl.svelte';
 export { default as IconButtonCtrl } from './IconButtonCtrl.svelte';
 export { default as InlineWrapper } from './InlineWrapper.svelte';
+export { JsonCtrl } from './JsonCtrl/index';
 export { default as NativeSelectCtrl } from './NativeSelectCtrl.svelte';
 export { default as NumberInputCtrl } from './NumberInputCtrl.svelte';
 export { default as PasswordInputCtrl } from './PasswordInputCtrl.svelte';

package/dist/components/FormerControllers/index.js

@@ -1,8 +1,11 @@
 export { default as ButtonCtrl } from './ButtonCtrl.svelte';
+export { default as CheckBoxCtrl } from './CheckBoxCtrl.svelte';
 export { default as CtrlFieldShell } from './CtrlFieldShell.svelte';
 export { DateTimeCtrl } from './DateTimeCtrl/index';
+export { default as FileInputCtrl } from './FileInputCtrl.svelte';
 export { default as IconButtonCtrl } from './IconButtonCtrl.svelte';
 export { default as InlineWrapper } from './InlineWrapper.svelte';
+export { JsonCtrl } from './JsonCtrl/index';
 export { default as NativeSelectCtrl } from './NativeSelectCtrl.svelte';
 export { default as NumberInputCtrl } from './NumberInputCtrl.svelte';
 export { default as PasswordInputCtrl } from './PasswordInputCtrl.svelte';

package/dist/components/Icons/IconEye.svelte

@@ -0,0 +1,6 @@
+<script lang="ts">const { size = 16, class: cls = "" } = $props();
+</script>
+<svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class={cls} aria-hidden="true">
+  <path d="M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7Z"/>
+  <circle cx="12" cy="12" r="3"/>
+</svg>

package/dist/components/Icons/IconEye.svelte.d.ts

@@ -0,0 +1,7 @@
+interface Props {
+    size?: number;
+    class?: string;
+}
+declare const IconEye: import("svelte").Component<Props, {}, "">;
+type IconEye = ReturnType<typeof IconEye>;
+export default IconEye;

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

@@ -4,6 +4,7 @@ export { default as IconAlertTriangle } from './IconAlertTriangle.svelte';
 export { default as IconCamera } from './IconCamera.svelte';
 export { default as IconClose } from './IconClose.svelte';
 export { default as IconEdit } from './IconEdit.svelte';
+export { default as IconEye } from './IconEye.svelte';
 export { default as IconFilter } from './IconFilter.svelte';
 export { default as IconSearch } from './IconSearch.svelte';
 export { default as IconSort } from './IconSort.svelte';

package/dist/components/Icons/index.js

@@ -4,6 +4,7 @@ export { default as IconAlertTriangle } from './IconAlertTriangle.svelte';
 export { default as IconCamera } from './IconCamera.svelte';
 export { default as IconClose } from './IconClose.svelte';
 export { default as IconEdit } from './IconEdit.svelte';
+export { default as IconEye } from './IconEye.svelte';
 export { default as IconFilter } from './IconFilter.svelte';
 export { default as IconSearch } from './IconSearch.svelte';
 export { default as IconSort } from './IconSort.svelte';

package/dist/components/Icons/strings.d.ts

@@ -9,3 +9,4 @@ export declare const iconFilterSvg = "<svg width=\"16\" height=\"16\" viewBox=\"
 export declare const iconCameraSvg = "<svg width=\"16\" height=\"16\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\" style=\"flex-shrink:0\" aria-hidden=\"true\"><path d=\"M14.5 4h-5L7 7H4a2 2 0 0 0-2 2v9a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2V9a2 2 0 0 0-2-2h-3l-2.5-3z\"/><circle cx=\"12\" cy=\"13\" r=\"3\"/></svg>";
 export declare const iconSortAscSvg = "<svg width=\"16\" height=\"16\" viewBox=\"0 0 24 24\" fill=\"currentColor\" style=\"flex-shrink:0\" aria-hidden=\"true\"><path d=\"M7 14l5-5 5 5H7z\"/></svg>";
 export declare const iconSortDescSvg = "<svg width=\"16\" height=\"16\" viewBox=\"0 0 24 24\" fill=\"currentColor\" style=\"flex-shrink:0\" aria-hidden=\"true\"><path d=\"M7 10l5 5 5-5H7z\"/></svg>";
+export declare const iconEyeSvg = "<svg width=\"16\" height=\"16\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\" style=\"flex-shrink:0\" aria-hidden=\"true\"><path d=\"M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7Z\"/><circle cx=\"12\" cy=\"12\" r=\"3\"/></svg>";

package/dist/components/Icons/strings.js

@@ -13,3 +13,4 @@ export const iconFilterSvg = `<svg ${F}><path d="M3 5a1 1 0 0 1 1-1h16a1 1 0 0 1
 export const iconCameraSvg = `<svg ${S}><path d="M14.5 4h-5L7 7H4a2 2 0 0 0-2 2v9a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2V9a2 2 0 0 0-2-2h-3l-2.5-3z"/><circle cx="12" cy="13" r="3"/></svg>`;
 export const iconSortAscSvg = `<svg ${F}><path d="M7 14l5-5 5 5H7z"/></svg>`;
 export const iconSortDescSvg = `<svg ${F}><path d="M7 10l5 5 5-5H7z"/></svg>`;
+export const iconEyeSvg = `<svg ${S}><path d="M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7Z"/><circle cx="12" cy="12" r="3"/></svg>`;

package/llm/FORMER_CONTROLLERS.md

@@ -0,0 +1,190 @@
+# Svelix Components Quick Reference
+
+This reference lists every Svelte component exported from the package root. Import components
+from `@warkypublic/svelix`; adapters, stores, utility functions, and types are documented in
+[ARCHITECTURE.md](./ARCHITECTURE.md) and [COMPONENT_GUIDE.md](./COMPONENT_GUIDE.md).
+
+## Import Pattern
+
+```svelte
+<script lang="ts">
+  import {
+    Button,
+    CheckBoxCtrl,
+    FileInputCtrl,
+    Former,
+    JsonCtrl,
+    TextInputCtrl,
+    VTree
+  } from '@warkypublic/svelix';
+</script>
+```
+
+## Form Controllers
+
+Most field controllers accept `label`, `name`, `disabled`, `error`, `required`, `sid`, and
+`tooltip`. Use `bind:value` or `bind:checked` when the component supports it. Use `onchange`
+when form state needs to be updated manually.
+
+| Component | Use |
+|---|---|
+| `TextInputCtrl` | Single-line text input; set `type` for email, URL, and other native input types. |
+| `TextAreaCtrl` | Multi-line text input; set `rows` as needed. |
+| `PasswordInputCtrl` | Password input with a visibility toggle. |
+| `NumberInputCtrl` | Numeric input with `min`, `max`, and `step`. |
+| `NativeSelectCtrl` | Native select; `options` accepts strings or `{ label, value }` objects. |
+| `DateTimeCtrl` | Date, time, or datetime picker; configure `mode`, constraints, and formats. |
+| `CheckBoxCtrl` | Checkbox or switch with boolean, integer, or string serialization. |
+| `SwitchCtrl` | Basic boolean checkbox-style toggle. |
+| `FileInputCtrl` | Single-file picker with file-type/image preview, name, and size. |
+| `JsonCtrl` | JSON value preview with a dialog editor. |
+| `ButtonCtrl` | Form action button. |
+| `IconButtonCtrl` | Compact icon action button. |
+| `CtrlFieldShell` | Label, required marker, tooltip, and error wrapper for custom controls. |
+| `InlineWrapper` | Places a field with optional left and right content in an inline row. |
+
+## CheckBoxCtrl
+
+`CheckBoxCtrl` renders a checkbox by default. Set `type="switch"` for a switch presentation.
+The bound `checked` value uses `dataFormat="boolean"` by default.
+
+```svelte
+<script lang="ts">
+  let enabled = $state(false);
+  let published = $state<0 | 1 | null>(null);
+  let verified = $state<string | null>(null);
+</script>
+
+<CheckBoxCtrl bind:checked={enabled} label="Enable notifications" name="notifications" />
+
+<CheckBoxCtrl
+  bind:checked={published}
+  dataFormat="integer"
+  label="Published"
+  name="published"
+  type="switch"
+/>
+
+<CheckBoxCtrl
+  bind:checked={verified}
+  dataFormat="string"
+  label="Verified"
+  name="verified"
+/>
+```
+
+Formats:
+
+- `boolean`: reads and writes `true` / `false`.
+- `integer`: reads `1`, `0`, or `null`; writes `1` / `0` after user interaction.
+- `string`: reads `1`, `true`, `yes`, `0`, `false`, `no`, or `null` case-insensitively; writes
+  `"true"` / `"false"` after user interaction.
+
+## FileInputCtrl
+
+`FileInputCtrl` manages one `File`. Its compact row shows an image thumbnail or file-type badge,
+the filename and size, and a choose/replace button.
+
+```svelte
+<script lang="ts">
+  let attachment = $state<File | null>(null);
+</script>
+
+<FileInputCtrl
+  bind:value={attachment}
+  accept="image/*,application/pdf"
+  label="Attachment"
+  name="attachment"
+  required
+/>
+```
+
+Use `onchange={(file) => { ... }}` when the selected file must be copied into external form
+state. `value` is `File | null`.
+
+## JsonCtrl
+
+`JsonCtrl` displays a compact JSON preview and opens a dialog editor. Bind arbitrary JSON-safe
+data through `value`.
+
+```svelte
+<script lang="ts">
+  let metadata = $state<unknown>({ status: 'draft' });
+</script>
+
+<JsonCtrl bind:value={metadata} label="Metadata" name="metadata" />
+```
+
+Use `onchange={(value) => { ... }}` when updating parent form state manually.
+
+## Form Containers
+
+| Component | Use |
+|---|---|
+| `Former` | Form state and CRUD lifecycle container. Supply fields through its `children` snippet. |
+| `FormerModal` | `Former` rendered in a modal. |
+| `FormerDrawer` | `Former` rendered in a side drawer. |
+| `FormerButtonArea` | Standard save, delete, cancel, and keep-open action area. |
+
+Use `bind:values`, `request`, `onAPICall`, and the `children(state)` snippet with `Former`.
+For state helpers, use `createFormerState`; for data adapters, use `FormerResolveSpecAPI` or
+`FormerRestHeadSpecAPI`.
+
+## Content Editors And Viewers
+
+`ContentEditor` selects a viewer/editor from `filename` and `contentType`. Use a subcomponent
+directly only when the file type is already known.
+
+| Component | Use |
+|---|---|
+| `ContentEditor` | Routes a file to the appropriate editor or viewer. |
+| `TextEditor` | Plain text editing. |
+| `MarkdownViewer` | Markdown display/editing with Carta. |
+| `MonacoEditor` | Source-code editing with Monaco. |
+| `CollaboraEditor` | Collabora office-document integration. |
+| `Office365Editor` | Office 365 document integration. |
+| `ImageViewer` | Image display. |
+| `AudioPlayer` | Audio playback. |
+| `VideoPlayer` | Video playback. |
+| `PdfViewer` | PDF display. |
+| `EmailViewer` | Email-file fallback viewer. |
+| `ZipViewer` | Archive-file fallback viewer. |
+| `UnknownFile` | Metadata and binary-header fallback viewer. |
+
+## Data And Selection Components
+
+| Component | Use |
+|---|---|
+| `Gridler` | Canvas-backed grid for large data sets, selection, editing, sorting, and filtering. |
+| `GridlerFull` | Full grid workflow with paging, searching, menus, and Former integration. |
+| `SvarkGrid` | SVAR grid alternative with column mapping and context menus. |
+| `CardGrid` | Filterable and sortable card collection. |
+| `DefaultCard` | Default card renderer for `CardGrid`. |
+| `CardGridFilterPanel` | Filter controls for `CardGrid`. |
+| `Boxer` | Lookup/select field backed by client or server data. |
+| `BoxerTarget` | Renders a selected Boxer value target. |
+| `VTree` | Virtualized hierarchical tree. |
+
+Use the corresponding `*ResolveSpecAdapter` or `*RestHeaderSpecAdapter` only when connecting
+`Gridler`, `SvarkGrid`, or `Boxer` to a supported data source.
+
+## Layout, Feedback, And Utilities
+
+| Component | Use |
+|---|---|
+| `Button` | General-purpose base button. |
+| `Portal` | Renders children outside the current DOM subtree. |
+| `ErrorBoundary` | Displays a fallback when child rendering fails. |
+| `BetterMenu` | Enhanced menu/dropdown control. |
+| `MenuRenderer` | Renders BetterMenu items when composing a custom menu. |
+| `GlobalStateStoreProvider` | Provides the global state store to descendants. |
+| `CaptureScreenshotComponent` | UI component for screenshot capture. |
+
+Use `createBetterMenuStore`, `useGlobalStateStoreContext`, `CaptureScreen`, and `overlayStack`
+for their related non-component APIs.
+
+## Icons
+
+The package exports `IconAdd`, `IconAlertCircle`, `IconAlertTriangle`, `IconCamera`, `IconClose`,
+`IconEdit`, `IconEye`, `IconFilter`, `IconSearch`, `IconSort`, and `IconTrash`. Each is a Svelte
+component that accepts `size` and `class` props.

package/llm/README.md

@@ -7,6 +7,7 @@ This folder contains AI-readable documentation that ships with the package.
 - [ARCHITECTURE.md](./ARCHITECTURE.md)
 - [SETUP.md](./SETUP.md)
 - [COMPONENT_GUIDE.md](./COMPONENT_GUIDE.md)
+- [FORMER_CONTROLLERS.md](./FORMER_CONTROLLERS.md) - quick reference for public components and controls
 - [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md)
 - [ROADMAP.md](./ROADMAP.md)
 - [ESLINT_GUIDE.md](./ESLINT_GUIDE.md)
@@ -118,5 +119,7 @@ When `@warkypublic/svelix` is installed, this documentation is available at:
 - `node_modules/@warkypublic/svelix/llm/README.md`
 - `node_modules/@warkypublic/svelix/llm/ARCHITECTURE.md`
 - `node_modules/@warkypublic/svelix/llm/SETUP.md`
+- `node_modules/@warkypublic/svelix/llm/FORMER_CONTROLLERS.md`
 
-Package subpath access is also exported for `@warkypublic/svelix/llm/*`.
+Package subpath access is exported for `@warkypublic/svelix/llm/*`, including the direct
+`@warkypublic/svelix/llm/components` and `@warkypublic/svelix/llm/former-controllers` references.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warkypublic/svelix",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Svelte 5 component library with Skeleton UI and Tailwind CSS",
   "license": "Apache-2.0",
   "exports": {
@@ -9,6 +9,8 @@
       "svelte": "./dist/index.js"
     },
     "./llm": "./llm/README.md",
+    "./llm/components": "./llm/FORMER_CONTROLLERS.md",
+    "./llm/former-controllers": "./llm/FORMER_CONTROLLERS.md",
     "./llm/*": "./llm/*",
     "./css/tailwind-source.css": "./dist/css/tailwind-source.css",
     "./css/*.css": "./dist/css/*.css",