chore: consolidate new foundation and archive v1 (#1495)

v1/packages/mosaic/framework/skills/vue/references/script-setup-macros.md

@@ -0,0 +1,216 @@
+---
+name: script-setup-macros
+description: Vue 3 script setup syntax and compiler macros for defining props, emits, models, and more
+---
+
+# Script Setup & Macros
+
+`<script setup>` is the recommended syntax for Vue SFCs with Composition API. It provides better runtime performance and IDE type inference.
+
+## Basic Syntax
+
+```vue
+<script setup lang="ts">
+// Top-level bindings are exposed to template
+import { ref } from 'vue';
+import MyComponent from './MyComponent.vue';
+
+const count = ref(0);
+const increment = () => count.value++;
+</script>
+
+<template>
+  <button @click="increment">{{ count }}</button>
+  <MyComponent />
+</template>
+```
+
+## defineProps
+
+Declare component props with full TypeScript support.
+
+```ts
+// Type-based declaration (recommended)
+const props = defineProps<{
+  title: string;
+  count?: number;
+  items: string[];
+}>();
+
+// With defaults (Vue 3.5+)
+const { title, count = 0 } = defineProps<{
+  title: string;
+  count?: number;
+}>();
+
+// With defaults (Vue 3.4 and below)
+const props = withDefaults(
+  defineProps<{
+    title: string;
+    items?: string[];
+  }>(),
+  {
+    items: () => [], // Use factory for arrays/objects
+  },
+);
+```
+
+## defineEmits
+
+Declare emitted events with typed payloads.
+
+```ts
+// Named tuple syntax (recommended)
+const emit = defineEmits<{
+  update: [value: string];
+  change: [id: number, name: string];
+  close: [];
+}>();
+
+emit('update', 'new value');
+emit('change', 1, 'name');
+emit('close');
+```
+
+## defineModel
+
+Two-way binding prop consumed via `v-model`. Available in Vue 3.4+.
+
+```ts
+// Basic usage - creates "modelValue" prop
+const model = defineModel<string>();
+model.value = 'hello'; // Emits "update:modelValue"
+
+// Named model - consumed via v-model:name
+const count = defineModel<number>('count', { default: 0 });
+
+// With modifiers
+const [value, modifiers] = defineModel<string>();
+if (modifiers.trim) {
+  // Handle trim modifier
+}
+
+// With transformers
+const [value, modifiers] = defineModel({
+  get(val) {
+    return val?.toLowerCase();
+  },
+  set(val) {
+    return modifiers.trim ? val?.trim() : val;
+  },
+});
+```
+
+Parent usage:
+
+```vue
+<Child v-model="name" />
+<Child v-model:count="total" />
+<Child v-model.trim="text" />
+```
+
+## defineExpose
+
+Explicitly expose properties to parent via template refs. Components are closed by default.
+
+```ts
+import { ref } from 'vue';
+
+const count = ref(0);
+const reset = () => {
+  count.value = 0;
+};
+
+defineExpose({
+  count,
+  reset,
+});
+```
+
+Parent access:
+
+```ts
+const childRef = ref<{ count: number; reset: () => void }>();
+childRef.value?.reset();
+```
+
+## defineOptions
+
+Declare component options without a separate `<script>` block. Available in Vue 3.3+.
+
+```ts
+defineOptions({
+  inheritAttrs: false,
+  name: 'CustomName',
+});
+```
+
+## defineSlots
+
+Provide type hints for slot props. Available in Vue 3.3+.
+
+```ts
+const slots = defineSlots<{
+  default(props: { item: string; index: number }): any;
+  header(props: { title: string }): any;
+}>();
+```
+
+## Generic Components
+
+Declare generic type parameters using the `generic` attribute.
+
+```vue
+<script setup lang="ts" generic="T extends string | number">
+defineProps<{
+  items: T[];
+  selected: T;
+}>();
+</script>
+```
+
+Multiple generics with constraints:
+
+```vue
+<script setup lang="ts" generic="T, U extends Record<string, T>">
+import type { Item } from './types';
+defineProps<{
+  data: U;
+  key: keyof U;
+}>();
+</script>
+```
+
+## Local Custom Directives
+
+Use `vNameOfDirective` naming convention.
+
+```ts
+const vFocus = {
+  mounted: (el: HTMLElement) => el.focus(),
+};
+
+// Or import and rename
+import { myDirective as vMyDirective } from './directives';
+```
+
+```vue
+<template>
+  <input v-focus />
+</template>
+```
+
+## Top-level await
+
+Use `await` directly in `<script setup>`. The component becomes async and must be used with `<Suspense>`.
+
+```vue
+<script setup lang="ts">
+const data = await fetch('/api/data').then((r) => r.json());
+</script>
+```
+
+<!--
+Source references:
+- https://vuejs.org/api/sfc-script-setup.html
+-->