@foormjs/vue 0.2.4 → 0.2.5

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@foormjs/vue",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "@foormjs/vue",
-  "main": "dist/index.js",
+  "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "sideEffects": false,
@@ -11,14 +11,19 @@
     "./package.json": "./package.json",
     "./styles": "./dist/style.css",
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.umd.cjs",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.cjs"
     }
   },
   "type": "module",
+  "bin": {
+    "setup-skills": "./scripts/setup-skills.js"
+  },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "scripts/setup-skills.js"
   ],
   "repository": {
     "type": "git",
@@ -26,8 +31,6 @@
     "directory": "packages/vue"
   },
   "keywords": [
-    "foorm",
-    "foormjs",
     "foorm",
     "foormjs",
     "forms",
@@ -40,29 +43,29 @@
   },
   "homepage": "https://github.com/foormjs/foormjs/tree/main/packages/vue#readme",
   "dependencies": {
-    "vue": "^3.5.28",
-    "vuiless-forms": "^0.0.3",
-    "@foormjs/atscript": "^0.2.4",
-    "foorm": "^0.2.4"
+    "@foormjs/atscript": "^0.2.5",
+    "@foormjs/composables": "^0.2.5"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.8",
-    "@atscript/typescript": "^0.1.8"
+    "@atscript/core": "^0.1.22",
+    "@atscript/typescript": "^0.1.22",
+    "vue": "^3.5.0"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.8",
-    "@atscript/typescript": "^0.1.8",
+    "@atscript/core": "^0.1.22",
+    "@atscript/typescript": "^0.1.22",
     "@playwright/test": "^1.58.2",
+    "vue": "^3.5.28",
     "@tsconfig/node20": "^20.1.9",
-    "@types/node": "^20.19.33",
-    "@vitejs/plugin-vue": "^5.2.4",
-    "@vue/tsconfig": "^0.5.1",
-    "npm-run-all2": "^6.2.6",
-    "typescript": "~5.4.5",
-    "unplugin-atscript": "^0.1.8",
-    "vite": "^5.4.21",
-    "vite-plugin-dts": "^3.9.1",
-    "vue-tsc": "^2.2.12"
+    "@types/node": "^22.15.33",
+    "@vitejs/plugin-vue": "^6.0.4",
+    "@vue/tsconfig": "^0.8.1",
+    "npm-run-all2": "^8.0.4",
+    "typescript": "~5.9.3",
+    "unplugin-atscript": "^0.1.22",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vue-tsc": "^3.2.4"
   },
   "scripts": {
     "dev": "vite",
@@ -71,6 +74,7 @@
     "build-only": "vite build",
     "type-check": "vue-tsc --build --force",
     "pub": "pnpm publish --access public --no-git-checks",
-    "test:e2e": "playwright test"
+    "test:e2e": "playwright test",
+    "setup-skills": "node ./scripts/setup-skills.js"
   }
 }

package/scripts/setup-skills.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/* prettier-ignore */
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const SKILL_NAME = 'foormjs-vue'
+const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
+
+if (!fs.existsSync(SKILL_SRC)) {
+  console.error(`No skills found at ${SKILL_SRC}`)
+  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
+  process.exit(1)
+}
+
+const AGENTS = {
+  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
+  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
+  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
+  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
+  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
+}
+
+const args = process.argv.slice(2)
+const isGlobal = args.includes('--global') || args.includes('-g')
+const isPostinstall = args.includes('--postinstall')
+let installed = 0, skipped = 0
+const installedDirs = []
+
+for (const [agentName, cfg] of Object.entries(AGENTS)) {
+  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
+  const agentRootDir = path.dirname(cfg.global) // Check if the agent has ever been installed globally
+
+  // In postinstall mode: silently skip agents that aren't set up globally
+  if (isPostinstall || isGlobal) {
+    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
+  }
+
+  const dest = path.join(targetBase, SKILL_NAME)
+  try {
+    fs.mkdirSync(dest, { recursive: true })
+    fs.cpSync(SKILL_SRC, dest, { recursive: true })
+    console.log(`✅  ${agentName}: installed to ${dest}`)
+    installed++
+    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
+  } catch (err) {
+    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
+  }
+}
+
+// Add locally-installed skill dirs to .gitignore
+if (!isGlobal && installedDirs.length > 0) {
+  const gitignorePath = path.join(process.cwd(), '.gitignore')
+  let gitignoreContent = ''
+  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
+  const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
+  if (linesToAdd.length > 0) {
+    const hasHeader = gitignoreContent.includes('# AI agent skills')
+    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
+      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
+      + linesToAdd.join('\n') + '\n'
+    fs.appendFileSync(gitignorePath, block)
+    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
+  }
+}
+
+if (installed === 0 && isPostinstall) {
+  // Silence is fine — no agents present, nothing to do
+} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
+  console.log('No agent directories detected. Try --global or run without it for project-local install.')
+} else if (installed === 0) {
+  console.log('Nothing installed. Run without --global to install project-locally.')
+} else {
+  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
+}

package/skills/foormjs-vue/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: foormjs-vue
+description: '@foormjs/vue — Vue 3 form rendering via OoForm. Use when building forms with OoForm component, creating custom type components or named components, using useFoormArray/useFoormUnion composables, or working with the types/components props.'
+---
+
+# @foormjs/vue
+
+Vue 3 form rendering powered by OoForm. You provide a `types` map (field type → Vue component) and optionally a `components` map (name → Vue component), and OoForm renders the entire form tree through a unified OoField renderer.
+
+## How to use this skill
+
+Read the domain file that matches the task. Do not load all files — only what you need.
+
+| Domain                     | File                                         | Load when...                                                                                                                                             |
+| -------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| OoForm setup & API         | [core.md](core.md)                           | Setting up OoForm, `types` vs `components` props, events, slots, `useFoorm`, `createDefaultTypes`, validation timing                                     |
+| Creating custom components | [custom-components.md](custom-components.md) | Building custom type components for any field kind — responsibility matrix, `TFoormComponentProps`, complete examples for leaf/structural/phantom fields |
+| Array & union composables  | [composables.md](composables.md)             | `useFoormArray`, `useFoormUnion`, `useConsumeUnionContext`, `formatIndexedLabel`                                                                         |
+| Rendering architecture     | [rendering.md](rendering.md)                 | OoField internals, component resolution, nesting levels, provide/inject keys, allStatic optimization                                                     |
+| Default components         | [defaults.md](defaults.md)                   | Built-in OoInput, OoSelect, OoObject, OoArray, OoUnion — what each renders, internal helpers, overriding patterns                                        |
+
+## Quick reference
+
+```ts
+import { OoForm, useFoorm, createDefaultTypes } from '@foormjs/vue'
+import type { TFoormComponentProps, TFoormTypeComponents } from '@foormjs/vue'
+
+const { def, formData } = useFoorm(MyForm)
+
+// Use defaults
+const types = createDefaultTypes()
+
+// Or override specific types
+const types = { ...createDefaultTypes(), text: MyInput, select: MySelect }
+```
+
+```vue
+<OoForm
+  :def="def"
+  :form-data="formData"
+  :types="types"
+  :components="{ StarRating: MyStarRating }"
+  @submit="onSubmit"
+  @change="onChange"
+/>
+```
+
+**Two ways to provide custom components:**
+
+- `types` prop — maps field type strings (`@foorm.type` or auto-inferred) to components. Every field always has a type.
+- `components` prop — maps named components (`@foorm.component`) to components. Per-field override, takes priority over `types`.
+
+**Writing `.as` form schemas:** Forms are defined in `.as` files with `@foorm.*` annotations. See the `@foormjs/atscript` skill's `schema.md` for the full guide — field types, validation, options, arrays, unions, nested groups, computed properties.

package/skills/foormjs-vue/composables.md

@@ -0,0 +1,189 @@
+# Array & Union Composables — @foormjs/vue
+
+> `useFoormArray`, `useFoormUnion`, `useConsumeUnionContext`, `formatIndexedLabel`, and `useDropdown`.
+
+## useFoormArray
+
+Manages array field state: stable keys, add/remove with constraints, per-index field caching, and union variant support.
+
+```ts
+import { useFoormArray } from '@foormjs/vue'
+import type { FoormArrayFieldDef } from '@foormjs/atscript'
+import { isArrayField } from '@foormjs/atscript'
+import { computed } from 'vue'
+
+const arrayField = isArrayField(props.field!) ? (props.field as FoormArrayFieldDef) : undefined
+
+const {
+  arrayValue, // ComputedRef<unknown[]> — current array items
+  itemKeys, // string[] (reactive) — stable keys for v-for
+  getItemField, // (index: number) => FoormFieldDef
+  isUnion, // boolean — items are union types?
+  unionVariants, // FoormUnionVariant[] — variants (if union)
+  addItem, // (variantIndex?: number) => void
+  removeItem, // (index: number) => void
+  canAdd, // ComputedRef<boolean> — respects @expect.maxLength
+  canRemove, // ComputedRef<boolean> — respects @expect.minLength
+  addLabel, // string — from @foorm.array.add.label
+  removeLabel, // string — from @foorm.array.remove.label
+} = useFoormArray(
+  arrayField!,
+  computed(() => props.disabled ?? false)
+)
+```
+
+**Parameters:**
+
+- `field: FoormArrayFieldDef` — array field definition (use type guard first)
+- `disabled?: ComputedRef<boolean>` — reactive disabled state
+
+**Key behaviors:**
+
+- `itemKeys` — stable string keys for Vue `v-for` tracking; auto-synced on array mutations
+- `getItemField(index)` — returns a `FoormFieldDef` for the item at index; caches and reuses across calls
+- `addItem(variantIndex?)` — for non-union arrays, pass `0`; for union arrays, pass the variant index
+- `removeItem(index)` — removes item and its key; invalidates cached field defs
+- `canAdd` / `canRemove` — computed from `@expect.maxLength` / `@expect.minLength`
+- Emits `'array-add'` and `'array-remove'` change events via injected `__foorm_change_handler`
+
+**Union arrays:**
+
+- `isUnion` is `true` when the array item type is a union
+- `unionVariants` lists available variants
+- `addItem(variantIndex)` creates a new item from the selected variant via `createItemData(variant)`
+
+## useFoormUnion
+
+Manages union variant state with data stashing — switching away saves data, switching back restores it.
+
+```ts
+import { useFoormUnion } from '@foormjs/vue'
+
+const {
+  unionField, // ComputedRef<FoormUnionFieldDef | undefined>
+  hasMultipleVariants, // ComputedRef<boolean>
+  localUnionIndex, // Ref<number> — current variant index
+  currentVariant, // ComputedRef<FoormUnionVariant>
+  innerField, // ComputedRef<FoormFieldDef | undefined>
+  changeVariant, // (newIndex: number) => void
+  optionalEnabled, // ComputedRef<boolean>
+  dropdownRef, // Ref<HTMLElement | null> — for variant picker dropdown
+  isOpen, // Ref<boolean> — dropdown open state
+  toggle, // () => void — toggle dropdown
+  select, // (callback) => void — select and close
+  handleNaClick, // () => void — handle N/A click for optional unions
+} = useFoormUnion(props)
+```
+
+**Parameters:**
+
+- `props: TFoormComponentProps` — the union component's props
+
+**Key behaviors:**
+
+- **Data stashing:** when switching from variant A to B, A's data is saved; switching back restores it
+- **Variant detection:** auto-detects the initial variant from existing data using `detectUnionVariant()`
+- **Provides `__foorm_union` context:** `{ variants, currentIndex, changeVariant }` — consumed by child components (e.g., inline variant picker in headers)
+- **Emits `'union-switch'`** change event when variant changes
+- **Dropdown state** (`dropdownRef`, `isOpen`, `toggle`, `select`) — for optional N/A variant picker UI
+
+## useConsumeUnionContext
+
+Reads the `__foorm_union` injection and immediately clears it. Prevents nested children from inheriting stale union context.
+
+```ts
+import { useConsumeUnionContext } from '@foormjs/vue'
+
+const unionCtx = useConsumeUnionContext()
+// unionCtx?.variants     — FoormUnionVariant[]
+// unionCtx?.currentIndex — Ref<number>
+// unionCtx?.changeVariant — (index: number) => void
+```
+
+**Must call in:** custom object, array, tuple, and field shell components. Without this, deeply nested components would incorrectly see a parent union's context.
+
+**Return type: `TFoormUnionContext | undefined`**
+
+```ts
+interface TFoormUnionContext {
+  variants: FoormUnionVariant[]
+  currentIndex: Ref<number>
+  changeVariant: (index: number) => void
+}
+```
+
+## formatIndexedLabel
+
+Formats a label with an array index prefix.
+
+```ts
+import { formatIndexedLabel } from '@foormjs/vue'
+
+formatIndexedLabel('Address', 0) // "Address #1"
+formatIndexedLabel('Address', 2) // "Address #3"
+formatIndexedLabel(undefined, 0) // "#1"
+formatIndexedLabel('Name', undefined) // "Name"
+formatIndexedLabel(undefined, undefined) // undefined
+```
+
+Used by default OoObject and OoFieldShell components for array item labels.
+
+## Common Patterns
+
+### Pattern: Custom array with drag-and-drop
+
+```vue
+<script setup lang="ts">
+import type { TFoormComponentProps } from '@foormjs/vue'
+import type { FoormArrayFieldDef } from '@foormjs/atscript'
+import { isArrayField } from '@foormjs/atscript'
+import { OoField, useFoormArray } from '@foormjs/vue'
+import { computed } from 'vue'
+
+const props = defineProps<TFoormComponentProps>()
+const arrayField = isArrayField(props.field!) ? (props.field as FoormArrayFieldDef) : undefined
+
+const {
+  arrayValue,
+  itemKeys,
+  getItemField,
+  addItem,
+  removeItem,
+  canAdd,
+  canRemove,
+  addLabel,
+  removeLabel,
+} = useFoormArray(
+  arrayField!,
+  computed(() => props.disabled ?? false)
+)
+
+// Your drag-and-drop logic here — reorder arrayValue items and itemKeys
+</script>
+```
+
+### Pattern: Union with inline variant picker in object header
+
+The default `OoUnion` provides `__foorm_union` context. The default `OoStructuredHeader` (used by `OoObject`) consumes it to render a variant picker dropdown. For custom components, use `useConsumeUnionContext()`:
+
+```vue
+<script setup lang="ts">
+import { useConsumeUnionContext } from '@foormjs/vue'
+
+const unionCtx = useConsumeUnionContext()
+
+// Render a variant picker if unionCtx is present
+// unionCtx.variants — show as dropdown
+// unionCtx.changeVariant(index) — switch variant
+// unionCtx.currentIndex — highlight active
+</script>
+```
+
+## Gotchas
+
+- `useFoormArray` must receive a `FoormArrayFieldDef` — always use `isArrayField()` type guard first
+- `itemKeys` is a reactive array, not a ref — it mutates in place
+- `getItemField(index)` caches field defs — after `removeItem`, cached entries at removed indices are invalidated
+- `changeVariant()` in `useFoormUnion` triggers data stashing — don't manually modify form data before/after
+- `useConsumeUnionContext()` has a side effect: it `provide`s `undefined` for `__foorm_union` to clear the injection for children. Always call it even if you don't use the return value.
+- `addItem()` for non-union arrays always takes `0` as the variant index argument