@atscript/ui 0.1.58

package/dist/plugin.cjs

@@ -0,0 +1,515 @@
+let _atscript_core = require("@atscript/core");
+//#region src/plugin/annotations.ts
+const BUILTIN_TYPES = [
+	"text",
+	"password",
+	"number",
+	"decimal",
+	"select",
+	"textarea",
+	"checkbox",
+	"radio",
+	"date",
+	"datetime",
+	"time",
+	"paragraph",
+	"action"
+];
+const COL_SPAN_VALUES = [
+	"1",
+	"2",
+	"3",
+	"4",
+	"5",
+	"6",
+	"7",
+	"8",
+	"9",
+	"10",
+	"11",
+	"12",
+	"full",
+	"half",
+	"third"
+];
+const ROW_SPAN_VALUES = [
+	"1",
+	"2",
+	"3",
+	"4",
+	"5",
+	"6"
+];
+/**
+* Static `@ui.*` annotation specs registered by the `@atscript/ui` plugin.
+*
+* Namespace contract (see Decision 1 in design.md):
+* - `ui.<key>`        — explicit cross-surface shared (`type`)
+* - `ui.form.<key>`   — form-only static
+* - `ui.table.<key>`  — table-only static
+* - `ui.dict.<key>`   — value-help annotations
+* - `ui.array.<key>`  — array control annotations
+*
+* The dynamic `ui.form.fn.*` / `ui.table.fn.*` and `ui.form.validate` specs
+* are declared by `@atscript/ui-fns`.
+*/
+const uiAnnotations = { ui: {
+	type: new _atscript_core.AnnotationSpec({
+		description: "Cell + input renderer type override applied to whichever surface lacks its own override (`ui.form.type` / `ui.table.type`). Built-in types: " + BUILTIN_TYPES.join(", ") + ". Consumers may dispatch additional custom types via the renderer registry — the argument is intentionally open-ended.\n\n**Example:**\n```atscript\n@ui.type \"currency\"\namount: number\n```\n",
+		nodeType: ["prop", "type"],
+		argument: {
+			name: "type",
+			type: "string",
+			description: "The renderer type used by both form input and table cell unless overridden."
+		}
+	}),
+	form: {
+		placeholder: new _atscript_core.AnnotationSpec({
+			description: "Defines **placeholder text** for UI input fields.\n\n**Example:**\n```atscript\n@ui.form.placeholder \"Enter your name\"\nname: string\n```\n",
+			nodeType: ["prop", "type"],
+			argument: {
+				name: "text",
+				type: "string",
+				description: "The placeholder text to display in UI input fields."
+			}
+		}),
+		hint: new _atscript_core.AnnotationSpec({
+			description: "Provides **help text or tooltip** displayed near the field in UI forms.\n\n**Example:**\n```atscript\n@ui.form.hint \"Must be a valid business email\"\nemail: string.email\n```\n",
+			nodeType: ["prop", "type"],
+			argument: {
+				name: "text",
+				type: "string",
+				description: "Help text or tooltip content."
+			}
+		}),
+		classes: new _atscript_core.AnnotationSpec({
+			description: "Adds **CSS class names** to the rendered field. Multiple `@ui.form.classes` annotations are appended.\n\n**Example:**\n```atscript\n@ui.form.classes \"text-bold\"\n@ui.form.classes \"mt-4\"\ntitle: string\n```\n",
+			nodeType: [
+				"prop",
+				"type",
+				"interface"
+			],
+			multiple: true,
+			mergeStrategy: "append",
+			argument: {
+				name: "names",
+				type: "string",
+				description: "One or more CSS class names (space-separated)."
+			}
+		}),
+		styles: new _atscript_core.AnnotationSpec({
+			description: "Adds **inline CSS styles** to the rendered field. Multiple `@ui.form.styles` annotations are appended.\n\n**Example:**\n```atscript\n@ui.form.styles \"color: red\"\n@ui.form.styles \"font-weight: bold\"\nwarning: string\n```\n",
+			nodeType: [
+				"prop",
+				"type",
+				"interface"
+			],
+			multiple: true,
+			mergeStrategy: "append",
+			argument: {
+				name: "css",
+				type: "string",
+				description: "CSS style declarations (semicolon-separated)."
+			}
+		}),
+		autocomplete: new _atscript_core.AnnotationSpec({
+			description: "Provides an **autocomplete hint** for the rendered input field.\n\n**Example:**\n```atscript\n@ui.form.autocomplete \"email\"\nemail: string.email\n```\n",
+			nodeType: ["prop", "type"],
+			argument: {
+				name: "value",
+				type: "string",
+				description: "HTML autocomplete attribute value."
+			}
+		}),
+		disabled: new _atscript_core.AnnotationSpec({
+			description: "Statically mark this field as disabled in the form.",
+			nodeType: ["prop", "type"]
+		}),
+		options: new _atscript_core.AnnotationSpec({
+			description: "Static option for select/radio fields. Repeat for each option. Label is the display text, value is the key (defaults to label).",
+			nodeType: ["prop", "type"],
+			multiple: true,
+			mergeStrategy: "replace",
+			argument: [{
+				name: "label",
+				type: "string",
+				description: "Display label for the option"
+			}, {
+				name: "value",
+				type: "string",
+				optional: true,
+				description: "Value/key for the option (defaults to label if omitted)"
+			}]
+		}),
+		order: new _atscript_core.AnnotationSpec({
+			description: "Explicit form-field ordering (lower values render first).",
+			nodeType: ["prop", "type"],
+			argument: {
+				name: "order",
+				type: "number",
+				description: "Numeric order (lower = earlier)"
+			}
+		}),
+		type: new _atscript_core.AnnotationSpec({
+			description: "Form input type override. Wins over the shared `@ui.type` for this prop's form input. Built-in types: " + BUILTIN_TYPES.join(", ") + ". Consumers may register additional types in the form types map; the argument is intentionally open-ended.",
+			nodeType: ["prop", "type"],
+			argument: {
+				name: "type",
+				type: "string",
+				description: "The input type used by `<as-field>` for this prop."
+			}
+		}),
+		component: new _atscript_core.AnnotationSpec({
+			description: "Named component override for the form-side renderer.",
+			nodeType: [
+				"prop",
+				"interface",
+				"type"
+			],
+			argument: {
+				name: "name",
+				type: "string",
+				description: "Component name from the form components registry"
+			}
+		}),
+		hidden: new _atscript_core.AnnotationSpec({
+			description: "Statically hide this field in the form.",
+			nodeType: ["prop", "type"]
+		}),
+		attr: new _atscript_core.AnnotationSpec({
+			description: "Custom attribute or component prop applied to the form input. Repeat for each attr. Passed via v-bind.",
+			nodeType: ["prop", "type"],
+			multiple: true,
+			mergeStrategy: "replace",
+			argument: [{
+				name: "name",
+				type: "string",
+				description: "Attribute/prop name (e.g., \"data-testid\", \"variant\", \"size\")"
+			}, {
+				name: "value",
+				type: "string",
+				description: "Static value (string, number, boolean, or undefined)"
+			}]
+		}),
+		grid: {
+			colSpan: new _atscript_core.AnnotationSpec({
+				description: "Grid column span for the field in auto-generated forms. Accepts numeric strings `\"1\"` to `\"12\"` or aliases `\"full\"` (12), `\"half\"` (6), `\"third\"` (4). Optional second argument applies inside narrow containers (≤480px); defaults to `\"full\"` when omitted.\n\n**Example:**\n```atscript\n@ui.form.grid.colSpan \"6\", \"12\"  // half-width desktop, full-width narrow\nfirstName: string\n```\n",
+				nodeType: ["prop", "type"],
+				argument: [{
+					name: "desktop",
+					type: "string",
+					description: "Column span for non-narrow containers. \"1\"-\"12\", \"full\", \"half\", or \"third\".",
+					values: COL_SPAN_VALUES
+				}, {
+					name: "narrow",
+					type: "string",
+					optional: true,
+					description: "Column span for containers ≤480px wide. Defaults to \"full\".",
+					values: COL_SPAN_VALUES
+				}]
+			}),
+			rowSpan: new _atscript_core.AnnotationSpec({
+				description: "Grid row span for the field. Accepts numeric strings `\"1\"` to `\"6\"`. Optional second argument applies inside narrow containers (≤480px); defaults to `\"1\"` when omitted.\n\n**Example:**\n```atscript\n@ui.form.grid.rowSpan \"2\"\nbio: string\n```\n",
+				nodeType: ["prop", "type"],
+				argument: [{
+					name: "desktop",
+					type: "string",
+					description: "Row span for non-narrow containers. \"1\"-\"6\".",
+					values: ROW_SPAN_VALUES
+				}, {
+					name: "narrow",
+					type: "string",
+					optional: true,
+					description: "Row span for containers ≤480px wide. Defaults to \"1\".",
+					values: ROW_SPAN_VALUES
+				}]
+			})
+		},
+		submit: { text: new _atscript_core.AnnotationSpec({
+			description: "Static submit button text.",
+			nodeType: ["interface", "type"],
+			argument: {
+				name: "text",
+				type: "string",
+				description: "Submit button label"
+			}
+		}) },
+		label: { singular: new _atscript_core.AnnotationSpec({
+			description: "Singular label form for an array field. Used by AsArray to render \"Add <singular>\" / \"Remove <singular>\" / per-item \"#N\"-suffixed labels. When omitted, the array falls back to `'item'`.\n\n**Example:**\n```atscript\n@meta.label 'Phone numbers'\n@ui.form.label.singular 'phone number'\nphones: string[]\n```\n",
+			nodeType: ["prop", "type"],
+			argument: {
+				name: "singular",
+				type: "string",
+				description: "Singular label, e.g. \"phone number\" for a `phones` field."
+			}
+		}) },
+		action: new _atscript_core.AnnotationSpec({
+			description: "Form action button for this field.",
+			nodeType: ["prop", "type"],
+			argument: [{
+				name: "id",
+				type: "string",
+				description: "The action name emitted on trigger"
+			}, {
+				name: "label",
+				type: "string",
+				optional: true,
+				description: "Display label for the action (falls back to @meta.label)"
+			}]
+		}),
+		prefix: {
+			$self: new _atscript_core.AnnotationSpec({
+				description: "Literal **prefix adornment** rendered before the input value. Works on all default inputs (`AsInput`, `AsNumber`, `AsDecimal`). When set on a field that also carries `@db.amount.currency*`, the explicit prefix wins — currency only contributes a prefix when no explicit one is present.\n\n**Example:**\n```atscript\n@ui.form.prefix \"+1\"\nphone: string\n```\n",
+				nodeType: ["prop", "type"],
+				argument: {
+					name: "value",
+					type: "string",
+					description: "Literal text to display before the input value."
+				}
+			}),
+			ref: new _atscript_core.AnnotationSpec({
+				description: "**Sibling-field reference** for the prefix adornment. The string argument is the name of another field on the same parent whose value will be displayed as the prefix at runtime. `@ui.form.prefix` wins over `@ui.form.prefix.ref` when both are present.\n\n**Example:**\n```atscript\ncountryCode: string\n@ui.form.prefix.ref \"countryCode\"\nphone: string\n```\n",
+				nodeType: ["prop", "type"],
+				argument: {
+					name: "field",
+					type: "string",
+					description: "Name of a sibling field whose value drives the prefix."
+				}
+			}),
+			icon: new _atscript_core.AnnotationSpec({
+				description: "**Icon adornment** rendered to the left of the input (further out than `@ui.form.prefix` text). The argument is a CSS class that paints the glyph — typically a UnoCSS preset-icons utility like `i-mdi-mail` or a custom registry alias. The consumer is responsible for ensuring the class is reachable (safelist / preset / shortcut). Combined order: `[prefix-icon][prefix-text][input]`.\n\n**Example:**\n```atscript\n@ui.form.prefix.icon \"i-mdi-mail\"\nemail: string.email\n```\n",
+				nodeType: ["prop", "type"],
+				argument: {
+					name: "class",
+					type: "string",
+					description: "CSS class painting the icon glyph. Consumer manages safelist / preset coverage."
+				}
+			})
+		},
+		suffix: {
+			$self: new _atscript_core.AnnotationSpec({
+				description: "Literal **suffix adornment** rendered after the input value. Works on all default inputs. When set on a field that also carries `@db.unit*`, the explicit suffix wins — unit code only contributes a suffix when no explicit one is present.\n\n**Example:**\n```atscript\n@ui.form.suffix \"/hr\"\nrate: number\n```\n",
+				nodeType: ["prop", "type"],
+				argument: {
+					name: "value",
+					type: "string",
+					description: "Literal text to display after the input value."
+				}
+			}),
+			ref: new _atscript_core.AnnotationSpec({
+				description: "**Sibling-field reference** for the suffix adornment. The string argument is the name of another field on the same parent whose value will be displayed as the suffix at runtime. `@ui.form.suffix` wins over `@ui.form.suffix.ref` when both are present.\n\n**Example:**\n```atscript\nunit: 'kg' | 'lb'\n@ui.form.suffix.ref \"unit\"\nweight: number\n```\n",
+				nodeType: ["prop", "type"],
+				argument: {
+					name: "field",
+					type: "string",
+					description: "Name of a sibling field whose value drives the suffix."
+				}
+			}),
+			icon: new _atscript_core.AnnotationSpec({
+				description: "**Icon adornment** rendered to the right of the input (further out than `@ui.form.suffix` text). The argument is a CSS class that paints the glyph — typically a UnoCSS preset-icons utility like `i-mdi-mail` or a custom registry alias. The consumer is responsible for ensuring the class is reachable (safelist / preset / shortcut). Combined order: `[input][suffix-text][suffix-icon]`.\n\n**Example:**\n```atscript\n@ui.form.suffix.icon \"i-mdi-check\"\ncode: string\n```\n",
+				nodeType: ["prop", "type"],
+				argument: {
+					name: "class",
+					type: "string",
+					description: "CSS class painting the icon glyph. Consumer manages safelist / preset coverage."
+				}
+			})
+		}
+	},
+	table: {
+		width: new _atscript_core.AnnotationSpec({
+			description: "Sets the **default column width** for this field when rendered in a table. Accepts any CSS width string (e.g. `120px`, `12em`, `20ch`). The user can still resize the column manually; double-click on the resize handle auto-fits to content; the column-menu Reset entry returns to this value.\n\n**Example:**\n```atscript\n@ui.table.width \"240px\"\ndescription: string\n```\n",
+			nodeType: ["prop", "type"],
+			argument: {
+				name: "width",
+				type: "string",
+				description: "CSS width for the column (e.g. '120px', '15em', '20ch')."
+			}
+		}),
+		component: new _atscript_core.AnnotationSpec({
+			description: "Named component override for the table-cell renderer.",
+			nodeType: [
+				"prop",
+				"interface",
+				"type"
+			],
+			argument: {
+				name: "name",
+				type: "string",
+				description: "Component name from the table components registry"
+			}
+		}),
+		hidden: new _atscript_core.AnnotationSpec({
+			description: "Hide this column by default in the table.",
+			nodeType: ["prop", "type"]
+		}),
+		attr: new _atscript_core.AnnotationSpec({
+			description: "Custom attribute or component prop applied to the rendered `<td>`. Repeat for each attr. Passed via v-bind.",
+			nodeType: ["prop", "type"],
+			multiple: true,
+			mergeStrategy: "replace",
+			argument: [{
+				name: "name",
+				type: "string",
+				description: "Attribute/prop name (e.g., \"title\", \"data-row\", \"aria-label\")"
+			}, {
+				name: "value",
+				type: "string",
+				description: "Static value applied to the cell."
+			}]
+		}),
+		classes: new _atscript_core.AnnotationSpec({
+			description: "CSS classes applied to the rendered `<td>` for this column's cells. Multiple `@ui.table.classes` annotations are appended.\n\n**Example:**\n```atscript\n@ui.table.classes \"font-bold\"\n@ui.table.classes \"text-right\"\namount: number\n```\n",
+			nodeType: [
+				"prop",
+				"type",
+				"interface"
+			],
+			multiple: true,
+			mergeStrategy: "append",
+			argument: {
+				name: "names",
+				type: "string",
+				description: "One or more CSS class names (space-separated)."
+			}
+		}),
+		styles: new _atscript_core.AnnotationSpec({
+			description: "Inline CSS styles applied to the rendered `<td>` for this column's cells. Multiple `@ui.table.styles` annotations are appended.\n\n**Example:**\n```atscript\n@ui.table.styles \"padding-left: 12px\"\ndescription: string\n```\n",
+			nodeType: [
+				"prop",
+				"type",
+				"interface"
+			],
+			multiple: true,
+			mergeStrategy: "append",
+			argument: {
+				name: "css",
+				type: "string",
+				description: "CSS style declarations (semicolon-separated)."
+			}
+		}),
+		type: new _atscript_core.AnnotationSpec({
+			description: "Cell renderer type override. Wins over the shared `@ui.type` for this prop's table cell. Built-in types: " + BUILTIN_TYPES.join(", ") + ". Consumers may register additional types in the table types map; the argument is intentionally open-ended.",
+			nodeType: ["prop", "type"],
+			argument: {
+				name: "type",
+				type: "string",
+				description: "The cell renderer type dispatched via the table types map."
+			}
+		}),
+		order: new _atscript_core.AnnotationSpec({
+			description: "Initial column ordering — lower values appear first; user-driven runtime reorder still mutates table state's `columnNames`.",
+			nodeType: ["prop", "type"],
+			argument: {
+				name: "order",
+				type: "number",
+				description: "Numeric order (lower = earlier)"
+			}
+		})
+	},
+	dict: {
+		label: new _atscript_core.AnnotationSpec({
+			description: "Marks this field as the primary display label when the table is used as a value-help dictionary",
+			nodeType: ["prop"]
+		}),
+		descr: new _atscript_core.AnnotationSpec({
+			description: "Marks this field as the secondary description in value-help display",
+			nodeType: ["prop"]
+		}),
+		attr: new _atscript_core.AnnotationSpec({
+			description: "Marks this field as an additional attribute column in table-mode value help",
+			nodeType: ["prop"],
+			multiple: true,
+			mergeStrategy: "append"
+		}),
+		filterable: new _atscript_core.AnnotationSpec({
+			description: "Marks this field as filterable in the value-help picker UI. Surfaced via `meta.fields[name].filterable` on value-help `/meta` responses.",
+			nodeType: ["prop"]
+		}),
+		sortable: new _atscript_core.AnnotationSpec({
+			description: "Marks this field as sortable in the value-help picker UI. Surfaced via `meta.fields[name].sortable` on value-help `/meta` responses.",
+			nodeType: ["prop"]
+		}),
+		searchable: new _atscript_core.AnnotationSpec({
+			description: "Marks a prop as participating in `$search`, or — on an interface — marks every `string` prop on the target as searchable. Surfaced via `meta.searchable` on value-help `/meta` responses.",
+			nodeType: ["prop", "interface"]
+		})
+	},
+	array: {
+		add: { label: new _atscript_core.AnnotationSpec({
+			description: "Label for the add-item button (default: \"Add item\")",
+			nodeType: ["prop"],
+			argument: {
+				name: "label",
+				type: "string",
+				description: "Button label text"
+			}
+		}) },
+		remove: { label: new _atscript_core.AnnotationSpec({
+			description: "Label for the remove-item button (default: \"Remove\")",
+			nodeType: ["prop"],
+			argument: {
+				name: "label",
+				type: "string",
+				description: "Button label text"
+			}
+		}) }
+	}
+} };
+//#endregion
+//#region src/plugin/primitives.ts
+/**
+* UI primitive types for atscript `.as` files.
+*
+* These register `ui.paragraph`, `ui.action`, `ui.select`, `ui.radio`, and `ui.checkbox`
+* as first-class types usable in interface property definitions.
+*/
+const uiPrimitives = { ui: {
+	type: "phantom",
+	isContainer: true,
+	documentation: "Non-data UI elements for form rendering",
+	extensions: {
+		action: { documentation: "Form action button — not a data field, excluded from form data. Use with @ui.form.action to define alternate submit actions." },
+		paragraph: { documentation: "Read-only paragraph text — rendered as static content, not an input field. Use @meta.default for static text or @ui.form.fn.value for computed text." },
+		select: {
+			type: "string",
+			documentation: "Dropdown select field. Use @ui.form.options to define static choices or @ui.form.fn.options for computed choices."
+		},
+		radio: {
+			type: "string",
+			documentation: "Radio button group. Use @ui.form.options to define static choices or @ui.form.fn.options for computed choices."
+		},
+		checkbox: {
+			type: "boolean",
+			documentation: "Single boolean checkbox toggle."
+		}
+	}
+} };
+//#endregion
+//#region src/plugin.ts
+/**
+* ATScript plugin that registers static UI annotations (`@ui.*`)
+* and UI primitive types (`ui.select`, `ui.radio`, etc.).
+*
+* Install in your `atscript.config.ts`:
+* ```ts
+* import uiPlugin from '@atscript/ui/plugin'
+*
+* export default {
+*   plugins: [uiPlugin()],
+* }
+* ```
+*/
+function uiPlugin() {
+	return {
+		name: "ui",
+		config() {
+			return {
+				primitives: uiPrimitives,
+				annotations: uiAnnotations
+			};
+		}
+	};
+}
+//#endregion
+module.exports = uiPlugin;

package/dist/plugin.d.cts

@@ -0,0 +1,18 @@
+import { TAtscriptPlugin } from "@atscript/core";
+
+//#region src/plugin.d.ts
+/**
+ * ATScript plugin that registers static UI annotations (`@ui.*`)
+ * and UI primitive types (`ui.select`, `ui.radio`, etc.).
+ *
+ * Install in your `atscript.config.ts`:
+ * ```ts
+ * import uiPlugin from '@atscript/ui/plugin'
+ *
+ * export default {
+ *   plugins: [uiPlugin()],
+ * }
+ * ```
+ */
+declare function uiPlugin(): TAtscriptPlugin;
+export = uiPlugin;

package/dist/plugin.d.mts

@@ -0,0 +1,19 @@
+import { TAtscriptPlugin } from "@atscript/core";
+
+//#region src/plugin.d.ts
+/**
+ * ATScript plugin that registers static UI annotations (`@ui.*`)
+ * and UI primitive types (`ui.select`, `ui.radio`, etc.).
+ *
+ * Install in your `atscript.config.ts`:
+ * ```ts
+ * import uiPlugin from '@atscript/ui/plugin'
+ *
+ * export default {
+ *   plugins: [uiPlugin()],
+ * }
+ * ```
+ */
+declare function uiPlugin(): TAtscriptPlugin;
+//#endregion
+export { uiPlugin as default };