@stonecrop/aform 0.31.0 → 0.33.0

package/src/types/index.ts

@@ -1,333 +0,0 @@
-import type {
-	ColumnSchema,
-	FieldValidation,
-	GetRecordsOptions,
-	GetRecordsResult,
-	TableViewConfig,
-	ValueField,
-} from '@stonecrop/schema'
-
-// ---------------------------------------------------------------------------
-// InteractionMode — canonical home is @stonecrop/schema
-// ---------------------------------------------------------------------------
-
-/**
- * Controls the level of user interaction for a field, container, or table.
- * `'edit'` — interactive; `'read'` — non-interactive with form chrome;
- * `'display'` — non-interactive plain-text rendering.
- * @public
- */
-export type { InteractionMode } from '@stonecrop/schema'
-
-// ---------------------------------------------------------------------------
-// ResolvedField — the output-space type that AForm consumes
-//
-// Usually produced by resolveSchema() from an authoring-space DoctypeField[].
-// It may also be hand-authored, for view chrome that has no backing doctype
-// (see Desktop.vue's doctype list) — annotate such literals with `satisfies
-// ResolvedTable`/`satisfies ResolvedField` so they stay checked.
-//
-// Authoring space and output space are NOT interchangeable. The trap is tables:
-// an authoring TableField carries its columns under `columns`, while resolveSchema
-// renames that key to `schema` (registry.ts) because `schema` is the ATable prop
-// that runs schemaToColumns(). Hand-authoring `columns` here — or feeding an
-// authoring-space field straight to AForm — produces a field AForm does not
-// recognise as a table.
-// ---------------------------------------------------------------------------
-
-/**
- * A resolved scalar field. Derived from ValueField with `cardinality` omitted
- * (consumed by resolveSchema) and an optional `doctype` added for unresolved Link fields.
- * @public
- */
-export type ResolvedScalar = Omit<ValueField, 'cardinality'> & {
-	/** Doctype slug for unresolved Link fields — added by resolveSchema when AFormLink is available */
-	doctype?: string
-}
-
-/**
- * A resolved Link field with cardinality `one` or `atMostOne` — embedded as a nested form.
- * @public
- */
-export interface ResolvedLink {
-	/** Discriminator */
-	kind: 'link'
-	/** Field identifier */
-	fieldname: string
-	/** Component to render; defaults to `'AForm'` */
-	component: string
-	/** Human-readable label */
-	label?: string
-	/** Interaction mode */
-	mode?: import('@stonecrop/schema').InteractionMode
-	/** Resolved child fields */
-	schema: ResolvedField[]
-	/** Preserved from the original ValueField */
-	required?: boolean
-	/** Preserved from the original ValueField */
-	readOnly?: boolean
-	/** Preserved from the original ValueField */
-	hidden?: boolean
-	/** Preserved from the original ValueField */
-	default?: unknown
-	/** Preserved from the original ValueField */
-	validation?: FieldValidation
-}
-
-/**
- * A resolved table — either from a Link with `noneOrMany`/`atLeastOne` cardinality,
- * or from an inline TableField. ATable receives columns via `:schema` (ColumnSchema[])
- * and row data via `:rows` from formData at render time.
- *
- * Note the key rename: an authoring `TableField` declares its columns under `columns`;
- * `resolveSchema` moves them to `schema` here, because `schema` is the ATable prop that
- * runs `schemaToColumns()` (ATable's own `columns` prop means already-converted
- * `TableColumn[]`). A hand-authored table must therefore use `schema`, not `columns`.
- *
- * Rows are never part of the schema. AForm sources them from the data model at
- * `dataModel[fieldname]`, so a `rows` key placed on this object is ignored.
- * @public
- */
-export interface ResolvedTable {
-	/** Discriminator */
-	kind: 'table'
-	/** Field identifier */
-	fieldname: string
-	/** Component to render; defaults to `'ATable'` */
-	component: string
-	/** Human-readable label */
-	label?: string
-	/** Interaction mode for all cells */
-	mode?: import('@stonecrop/schema').InteractionMode
-	/** Column definitions — passed to ATable's `:schema` prop */
-	schema: ColumnSchema[]
-	/** View configuration — always present; defaults to `{ view: 'list' }` */
-	config: TableViewConfig
-	/** Preserved from the original ValueField or TableField */
-	required?: boolean
-	/** Preserved from the original ValueField or TableField */
-	readOnly?: boolean
-	/** Preserved from the original ValueField or TableField */
-	hidden?: boolean
-	/** Preserved from the original ValueField or TableField */
-	default?: unknown
-	/** Preserved from the original ValueField or TableField */
-	validation?: FieldValidation
-	/** When set, ATable fetches list pages through this callback (server paging). */
-	getRecords?: (options?: GetRecordsOptions) => Promise<GetRecordsResult>
-	/** When this changes, ATable refetches from offset 0. */
-	sourceKey?: string
-}
-
-/**
- * A resolved fieldset — groups child fields inside an AFieldset component.
- * @public
- */
-export interface ResolvedFieldset {
-	/** Discriminator */
-	kind: 'fieldset'
-	/** Field identifier */
-	fieldname: string
-	/** Component to render; defaults to `'AFieldset'` */
-	component?: string
-	/** Human-readable label for the legend */
-	label?: string
-	/** Whether the fieldset can be collapsed */
-	collapsible?: boolean
-	/** Interaction mode for all children */
-	mode?: import('@stonecrop/schema').InteractionMode
-	/** Resolved child fields */
-	schema: ResolvedField[]
-}
-
-/**
- * The discriminated union of all resolved field types — what AForm consumes,
- * usually after `resolveSchema()` has transformed the authoring `DoctypeField[]`,
- * but also valid hand-authored for view chrome with no backing doctype.
- * Narrowed by `kind`: `'field'` | `'link'` | `'table'` | `'fieldset'`.
- *
- * `kind` is required — AForm dispatches on it alone and does not infer a field's
- * type from its structure.
- * @public
- */
-export type ResolvedField = ResolvedScalar | ResolvedLink | ResolvedTable | ResolvedFieldset
-
-// ---------------------------------------------------------------------------
-// Utility types
-// ---------------------------------------------------------------------------
-
-/**
- * Defined props for AForm components
- * @public
- */
-export type ComponentProps = {
-	/**
-	 * The schema object to pass to the component
-	 * @public
-	 */
-	schema?: ResolvedField
-
-	/**
-	 * The label to display in the component
-	 * @public
-	 */
-	label?: string
-
-	// TODO: add docstring
-	selectRange?: boolean
-
-	/**
-	 * The mask to apply to inputs inside the component. Accepts either a plain
-	 * mask string (e.g. `"(###) ###-####"`) or a stringified arrow function that
-	 * receives `locale` and returns a mask string
-	 * (e.g. `"(locale) => locale === 'en-US' ? '(###) ###-####' : '####-######'"`).
-	 * @public
-	 */
-	mask?: string
-
-	/**
-	 * Indicate whether input is required for text and/or select elements inside the component
-	 * @public
-	 */
-	required?: boolean
-
-	/**
-	 * The rendering mode for the component
-	 * @public
-	 */
-	mode?: import('@stonecrop/schema').InteractionMode
-
-	/**
-	 * Set a unique identifier for elements inside the component
-	 * @public
-	 */
-	uuid?: string
-
-	/**
-	 * Validation options for elements inside the component
-	 * @public
-	 */
-	validation?: {
-		/**
-		 * The error message to display when validation fails
-		 * @public
-		 */
-		errorMessage: string
-
-		[key: string]: any
-	}
-
-	/**
-	 * Inline validation error messages to display on this field. Fed by the host
-	 * (e.g. mapped from the core validation store) — the renderer stays dumb and just
-	 * shows what it is given. Takes precedence over the static `validation.errorMessage`.
-	 * @public
-	 */
-	errors?: string[]
-}
-
-/**
- * The value shape for AFormLink — a linked document reference with optional display text
- * @public
- */
-export interface AFormLinkValue {
-	/** The FK/linked document ID. `id: 0` is a valid ID. */
-	id: string | number
-	/** Display text shown in the input. Falls back to `String(id)` if omitted. */
-	displayText?: string
-	/** Additional properties passed through to the underlying input component */
-	[extra: string]: any
-}
-
-/**
- * What AFormLink accepts as its `v-model`.
- *
- * Wider than {@link AFormLinkValue} because a link is as often bound straight to its FK column as
- * to a resolved reference: a record loaded from the DB carries the raw scalar, and a parent bound
- * to that column coerces every update it receives back to a scalar. The component reads through
- * `linkId`/`linkDisplayText`/`asLinkValue`, so all three shapes render and resolve identically.
- *
- * Emitting is narrower — AFormLink always writes back an {@link AFormLinkValue}.
- * @public
- */
-export type AFormLinkModelValue = AFormLinkValue | string | number
-
-/**
- * Navigation contract for AFormLink. Provide via `provide('aformLinkNavigator', ...)` in the app plugin.
- * @public
- */
-export interface AFormLinkNavigator {
-	/** Navigate to the linked document. Implementation is app-defined. */
-	navigate(doctype: string, id: string | number): void
-}
-
-/**
- * The value shape for AQuantityInput — a quantity paired with its unit of measure, plus the
- * derived stock-equivalent quantity/UOM. `conversionFactor` is carried on the value so it
- * round-trips with the record even though it is never shown in the UI.
- * @public
- */
-export interface QuantityValue {
-	/** The entered quantity, in `uom` units */
-	qty: number
-	/** Unit of measure the user entered `qty` in */
-	uom: string
-	/** `qty` converted into `stockUom` units — `qty * conversionFactor` */
-	stockQty: number
-	/** The item's base/stock unit of measure — fixed, not user-editable */
-	stockUom: string
-	/** Multiplier from `uom` to `stockUom` — hidden from the UI, drives `stockQty` */
-	conversionFactor: number
-}
-
-/**
- * Type-specific configuration for AQuantityInput, passed via the field's `options` property.
- * @public
- */
-export interface QuantityOptions {
-	/** Dropdown choices for the `uom` field */
-	uoms?: string[]
-	/** The item's base/stock unit of measure — fixed, not user-editable */
-	stockUom?: string
-	/** Conversion factor lookup for each non-stock UOM, relative to `stockUom` (which is implicitly `1`) */
-	conversionFactors?: Record<string, number>
-}
-
-/**
- * The value shape for ACurrencyInput — an amount paired with its currency (an
- * {@link AFormLinkValue} FK reference), plus the derived base-currency-equivalent amount.
- * `exchangeRate` is carried on the value so it round-trips with the record even though it is
- * never directly edited by the user.
- * @public
- */
-export interface CurrencyValue {
-	/** The entered amount, in `currency` units */
-	amount: number
-	/** FK reference to the Currency doctype the user entered `amount` in */
-	currency: AFormLinkValue
-	/** `amount` converted into `baseCurrency` units — `amount * exchangeRate` */
-	baseAmount: number
-	/** The record's base currency — fixed, not user-editable */
-	baseCurrency: AFormLinkValue
-	/** Multiplier from `currency` to `baseCurrency` — hidden from the UI, drives `baseAmount` */
-	exchangeRate: number
-}
-
-/**
- * Type-specific configuration for ACurrencyInput, passed via the field's `options` property.
- * @public
- */
-export interface CurrencyOptions {
-	/** Currency doctype name, used for FK resolution via `aformLinkResolver`. The currency picker is embedded, so it renders no navigate button. */
-	doctype?: string
-	/** The record's base currency — fixed, not user-editable. A bare id resolves to displayText via `aformLinkResolver`. */
-	baseCurrency?: AFormLinkValue | string
-	/** Exchange rate lookup for each non-base currency id, relative to `baseCurrency` (which is implicitly `1`) */
-	exchangeRates?: Record<string, number>
-	/** Decimal places to round the derived `baseAmount` to — the base currency's scale (JPY carries 0, most carry 2, KWD 3). Applies only to `baseAmount`; the entered `amount` is left as typed. Omit to round only enough to shed binary floating-point noise, which never discards a digit the rate actually produced. A non-integer or out-of-range value falls back to that default. */
-	precision?: number
-	/** Search function backing the `currency` autocomplete dropdown — see AFormLink's `filterFunction` */
-	filterFunction?: string | ((search: string) => AFormLinkValue[] | Promise<AFormLinkValue[]>)
-	/** Whether `filterFunction` results should show a loading state — see AFormLink's `isAsync` */
-	isAsync?: boolean
-}

package/src/utils/badge.ts

@@ -1,94 +0,0 @@
-import type { BadgeDescriptor, FieldOptions } from '@stonecrop/schema'
-import { isBadgeDescriptor, lookupBadge } from '@stonecrop/schema'
-
-import { deserializeFunction } from './deserialize'
-
-/**
- * Row context passed to badge `format` functions in form fields.
- * @public
- */
-export type BadgeFormatContext = {
-	record?: Record<string, unknown>
-	row?: Record<string, unknown>
-}
-
-/**
- * Badge-aware field `format` function signature.
- * @public
- */
-export type BadgeFormatFn = (value: unknown, context: BadgeFormatContext) => string | BadgeDescriptor
-
-/**
- * Resolve a field value to a badge descriptor using format (if present) then options map.
- * @public
- */
-export function resolveFieldBadge(
-	value: unknown,
-	options: FieldOptions | undefined,
-	format: string | BadgeFormatFn | undefined,
-	context: BadgeFormatContext = {}
-): BadgeDescriptor | undefined {
-	if (format) {
-		let formatted: unknown
-		if (typeof format === 'function') {
-			formatted = format(value, context)
-		} else {
-			const formatFn = deserializeFunction<BadgeFormatFn>(format)
-			formatted = formatFn(value, context)
-		}
-		if (isBadgeDescriptor(formatted)) {
-			const label = formatted.label.trim()
-			return label ? formatted : undefined
-		}
-		if (typeof formatted === 'string' && formatted !== '') {
-			return lookupBadge(options, formatted) ?? { label: formatted, variant: 'neutral' }
-		}
-	}
-
-	const key = badgeLookupKey(value)
-	if (key === undefined) return undefined
-	return lookupBadge(options, key)
-}
-
-/**
- * Stored choice value as an options-map key. Only primitives can match a declared choice, so
- * anything else yields undefined rather than the '[object Object]' that String() would produce.
- */
-function badgeLookupKey(value: unknown): string | undefined {
-	switch (typeof value) {
-		case 'string':
-			return value === '' ? undefined : value
-		case 'number':
-		case 'boolean':
-		case 'bigint':
-			return String(value)
-		default:
-			return undefined
-	}
-}
-
-const BADGE_VARIANTS = new Set<string>(['neutral', 'success', 'warning', 'danger', 'brand'])
-
-/**
- * CSS custom properties for input-accent styling on a native input.
- * @public
- */
-export function badgeInputAccentStyle(descriptor: BadgeDescriptor | undefined): Record<string, string> | undefined {
-	if (!descriptor?.label?.trim()) return undefined
-	const variant = descriptor.variant ?? 'neutral'
-	if (descriptor.color) {
-		return {
-			borderLeftWidth: '4px',
-			borderLeftStyle: 'solid',
-			borderLeftColor: descriptor.color,
-			paddingLeft: 'calc(1ch - 4px)',
-		}
-	}
-	if (!BADGE_VARIANTS.has(variant)) return undefined
-	return {
-		borderLeftWidth: '4px',
-		borderLeftStyle: 'solid',
-		borderLeftColor: `var(--sc-badge-${variant}-accent)`,
-		paddingLeft: 'calc(1ch - 4px)',
-	}
-}

package/src/utils/columns.ts

@@ -1,38 +0,0 @@
-import type { ColumnSchema } from '@stonecrop/schema'
-
-import type { ResolvedField } from '../types'
-
-/**
- * The resolved fields that can be columns in a list or table view, in declaration order.
- *
- * A cell renders one value, so only `kind: 'field'` qualifies. The other three kinds are
- * containers: a `fieldset` groups fields for layout and has no value of its own, while a `link`
- * and a `table` hold a nested record and an array of them. Neither has a `cellComponent`, so a
- * container reaching `ACell` falls through to plain-text rendering and stringifies its children —
- * no error and no log, just a wrong column.
- *
- * A fieldset's *children* are real columns, so it is flattened rather than dropped; losing them is
- * the same silent defect in the other direction.
- *
- * One definition, called by both consumers: `Registry.buildTableConfig` (a child table's columns,
- * from its target's resolved schema) and Desktop's records list. Re-deriving it at either call
- * site produced exactly one of the two failures above at each.
- *
- * @param fields - resolved fields, as produced by `resolveSchema`
- * @returns column definitions, with the `kind` discriminator stripped
- * @public
- */
-export function resolvedFieldsToColumns(fields: readonly ResolvedField[]): ColumnSchema[] {
-	const columns: ColumnSchema[] = []
-
-	for (const field of fields) {
-		if (field.kind === 'fieldset') {
-			columns.push(...resolvedFieldsToColumns(field.schema))
-		} else if (field.kind === 'field') {
-			const { kind: _kind, ...column } = field
-			columns.push(column)
-		}
-	}
-
-	return columns
-}

package/src/utils/deserialize.ts

@@ -1,20 +0,0 @@
-/**
- * Deserializes a stringified function expression into a typed callable.
- *
- * Throws if the string cannot be parsed as a function (SyntaxError) or if the
- * resulting expression is not callable (TypeError), or if the expression references
- * an undefined variable (ReferenceError). Callers are responsible for try/catch.
- *
- * @example
- * ```ts
- * const fn = deserializeFunction<(x: number) => number>('(x) => x * 2')
- * fn(5) // 10
- * ```
- * @public
- */
-// T is intentionally a caller-supplied return type — this utility is unsafe by design (Function constructor).
-// oxlint-disable-next-line typescript/no-unnecessary-type-parameters
-export function deserializeFunction<T extends (...args: any[]) => any>(source: string): T {
-	// oxlint-disable-next-line typescript/no-unsafe-type-assertion, typescript/no-implied-eval
-	return Function(`"use strict"; return (${source})`)() as T
-}