@falcondev-oss/nuxt-layers-base 0.40.1 → 0.40.2

package/app/utils/define-setup-component.ts

@@ -1,6 +1,6 @@
-/* eslint-disable ts/no-empty-object-type */
-import type { AllUnionFields, UnionToTuple } from 'type-fest'
+import type { AllUnionFields, Simplify } from 'type-fest'
 import type {
+  Attrs,
   ComponentOptionsMixin,
   CreateComponentPublicInstanceWithMixins,
   EmitsToProps,
@@ -8,13 +8,17 @@ import type {
   PublicProps,
   RenderFunction,
   SetupContext,
-  Slots as SlotOptions,
   SlotsType,
 } from 'vue'
+import { defineComponent } from 'vue'
 
 declare module 'vue' {
   interface ComponentCustomProps {
-    vSlots?: SlotOptions
+    // Deliberately loose: this only makes `vSlots` an accepted prop name on every
+    // component. `Slots` would reject it for any component whose slots are declared as an
+    // interface without an index signature (most of @nuxt/ui). The real check is the
+    // `vSlots()` helper below, which types the object against the target's own slots.
+    vSlots?: Record<string, any>
   }
 }
 
@@ -22,6 +26,18 @@ interface ComponentTypes {
   props?: Record<string, any>
   emits?: ObjectEmitsOptions
   slots?: Record<string, any>
+  /**
+   * Prop names to register when they are deliberately fewer than `keyof props`; the rest
+   * arrive as `attrs`. See `docs/agents/vue-to-tsx-migration.md` for when that is right.
+   */
+  propKeys?: string
+  /**
+   * What `ctx.expose()` publishes, so parents holding a template ref see it.
+   *
+   * `expose()` alone only works at runtime; without this the instance type has no trace
+   * of it and `ref.value.selectDate()` is a type error at every call site.
+   */
+  expose?: Record<string, any>
 }
 
 /**
@@ -35,15 +51,38 @@ type Field<T extends ComponentTypes, K extends keyof ComponentTypes> = K extends
   : {}
 
 /**
- * Keys of `T` as a readonly tuple, or `readonly []` when `T` has no keys.
+ * Every key of `T`, flattened across union members. `never` when `T` has no keys,
+ * which makes `readonly Keys<T>[]` accept only `[]`.
+ */
+type Keys<T> = [keyof T] extends [never] ? never : Extract<keyof AllUnionFields<T>, string>
+
+/** The runtime prop names: `propKeys` when declared, the keys of `props` otherwise. */
+type PropKeys<T extends ComponentTypes> = 'propKeys' extends keyof T
+  ? Extract<NonNullable<T['propKeys']>, string>
+  : Keys<Field<T, 'props'>>
+
+/** Props not registered in `propKeys` arrive through `attrs` with Vue's `unknown` index signature. */
+type AttrProps<T extends ComponentTypes> = Simplify<Omit<Field<T, 'props'>, PropKeys<T>> & Attrs>
+
+type EmitKeys<T extends ComponentTypes> = Keys<Field<T, 'emits'>>
+
+/** The shape no array satisfies; generic so the alias head names the missing keys. */
+type MissingEntries<K extends string> = { readonly [P in K]: true }
+
+/**
+ * `unknown` when `Given` covers every key in `All`, otherwise an object that no array
+ * satisfies. Intersected onto the `props`/`emits` parameter it turns a forgotten key
+ * into an error that names the key.
  *
- * `keyof {}` is `never` and `UnionToTuple<never>` resolves to `never` (not `[]`),
- * so the empty case is guarded explicitly. Without it an empty `props`/`emits`
- * declaration (e.g. `emits: {}`) poisons inference of the surrounding options object.
+ * Deliberately *not* `UnionToTuple`: that fixes an order which TypeScript derives from
+ * union member order, an implementation detail that shifts when unrelated declarations
+ * move. A component would compile today and demand a reshuffled array tomorrow.
  */
-type KeysTuple<T> = [keyof T] extends [never]
-  ? readonly []
-  : Readonly<UnionToTuple<keyof AllUnionFields<T>>>
+export type Exhaustive<All extends string, Given extends readonly string[]> = [
+  Exclude<All, Given[number]>,
+] extends [never]
+  ? unknown
+  : MissingEntries<Exclude<All, Given[number]>>
 
 /**
  * Vue's own `emit` type (`SetupContext<E>['emit']`) for declared emits, but an empty
@@ -57,12 +96,23 @@ type StrictEmitFn<E extends ObjectEmitsOptions> = [keyof E] extends [never]
 
 /** Runtime config for a component, derived from its declared types `T`. */
 interface SetupConfig<T extends ComponentTypes> {
-  props: KeysTuple<Field<T, 'props'>>
-  emits: KeysTuple<Field<T, 'emits'>>
+  /**
+   * The component's name, as Vue Devtools and warning traces show it.
+   *
+   * Without it every component built here reports as `<Setup>`, because the setup
+   * function it is derived from is anonymous.
+   */
+  name?: string
+  /** Vue's `inheritAttrs`. Set to `false` to place `ctx.attrs` yourself. */
+  inheritAttrs?: boolean
   setup: (
     props: Field<T, 'props'> & EmitsToProps<Field<T, 'emits'>>,
-    ctx: Omit<SetupContext<Field<T, 'emits'>, SlotsType<Partial<Field<T, 'slots'>>>>, 'emit'> & {
+    ctx: Omit<
+      SetupContext<Field<T, 'emits'>, SlotsType<Partial<Field<T, 'slots'>>>>,
+      'emit' | 'attrs'
+    > & {
       emit: StrictEmitFn<Field<T, 'emits'>>
+      attrs: AttrProps<T>
     },
   ) => RenderFunction | Promise<RenderFunction>
 }
@@ -72,7 +122,10 @@ interface SetupConfig<T extends ComponentTypes> {
 // be returned as a raw object literal. The key is a readable string so bypassing it
 // reports `Property '"use the options() helper"' is missing`.
 type OptionsBrand = { readonly ['use the options() helper']: true }
-type ViaOptions<T extends ComponentTypes> = SetupConfig<T> & OptionsBrand
+type ViaOptions<T extends ComponentTypes> = SetupConfig<T> & {
+  props: readonly PropKeys<T>[]
+  emits: readonly EmitKeys<T>[]
+} & OptionsBrand
 
 // `defineSetupComponent`'s callback must return an `options()` result. This shape is
 // intentionally independent of `T`: `options()` already validated everything and typed
@@ -81,52 +134,55 @@ type ViaOptions<T extends ComponentTypes> = SetupConfig<T> & OptionsBrand
 type LooseSetupConfig = {
   props: readonly string[]
   emits: readonly string[]
+  name?: string
+  inheritAttrs?: boolean
   setup: (...args: any) => any
 } & OptionsBrand
 
-/**
- * Validates the runtime `config` against the declared types `_` and types `setup`.
- *
- * `_` binds the declared types `T`, so `config` is checked as a plain argument (not as
- * an inferred callback return) — which means key mismatches are reported locally, right
- * on the offending `props`/`emits`/`setup` property.
- */
-export function options<const T extends ComponentTypes>(
+/** `_` binds `T`, so key mismatches are reported on the offending config property. */
+export function options<
+  const T extends ComponentTypes,
+  const P extends readonly PropKeys<T>[],
+  const E extends readonly EmitKeys<T>[],
+>(
   _: T,
-  config: SetupConfig<T>,
+  config: SetupConfig<T> & {
+    props: P & Exhaustive<PropKeys<T>, P>
+    emits: E & Exhaustive<EmitKeys<T>, E>
+  },
 ): ViaOptions<T> {
-  return config as ViaOptions<T>
+  return config as unknown as ViaOptions<T>
 }
 
 export function defineSetupComponent<const T extends ComponentTypes>(
   options_: (opts: T) => LooseSetupConfig,
-): new (
-  props: Field<T, 'props'>,
-) => CreateComponentPublicInstanceWithMixins<
+): new (props: Field<T, 'props'>) => CreateComponentPublicInstanceWithMixins<
   Field<T, 'props'> & EmitsToProps<Field<T, 'emits'>>,
-  {},
+  Field<T, 'expose'>,
   {},
   {},
   {},
   ComponentOptionsMixin,
   ComponentOptionsMixin,
   Field<T, 'emits'>,
-  PublicProps & { vSlots?: Field<T, 'slots'> },
+  // `Partial`, to match `SlotsType<Partial<...>>` below and the partial type `vSlots()`
+  PublicProps & { vSlots?: Partial<Field<T, 'slots'>> },
   {},
   false,
   {},
   SlotsType<Partial<Field<T, 'slots'>>>
 > {
-  // eslint-disable-next-line ts/no-unsafe-argument
+  // oxlint-disable-next-line typescript/no-unsafe-argument
   const opts = options_({} as any)
-  // eslint-disable-next-line ts/no-unsafe-return, ts/no-unsafe-argument
+  // oxlint-disable-next-line typescript/no-unsafe-return, typescript/no-unsafe-argument
   return defineComponent(opts.setup as any, {
     props: opts.props as unknown as string[],
     emits: opts.emits as unknown as string[],
+    name: opts.name,
+    inheritAttrs: opts.inheritAttrs,
   }) as any
 }
 
-// https://github.com/vuejs/language-tools/blob/master/packages/component-type-helpers/index.ts
 type ComponentSlots<T> = T extends new (...args: any) => { $slots: infer S }
   ? NonNullable<S>
   : T extends (props: any, ctx: { slots: infer S; attrs: any; emit: any }, ...args: any) => any
@@ -136,3 +192,33 @@ type ComponentSlots<T> = T extends new (...args: any) => { $slots: infer S }
 export function vSlots<C>(component: C, slots: ComponentSlots<C>) {
   return slots
 }
+
+/**
+ * Vue's short emit declaration (`{ change: [event: Event] }`) rewritten as the call
+ * signatures `ComponentTypes['emits']` expects. Component libraries ship the short form,
+ * so a wrapper forwarding their emits would otherwise have to restate every signature.
+ */
+export type AsEmits<E> = {
+  [K in keyof E]: E[K] extends readonly any[] ? (...args: E[K]) => void : never
+}
+
+/**
+ * A reusable, exhaustively checked list of the prop names of `T`.
+ *
+ * `defineSetupComponent` needs every prop spelled out at runtime, which is pure
+ * repetition for the many wrapper components that re-declare a shared props type
+ * (`FormGroupProps`, `GenericInputProps`, ...). Declare the list once here and spread
+ * it into `options({ props: [...] })`; the spread keeps the literal types, so the
+ * component's own exhaustiveness check still applies.
+ *
+ * ```ts
+ * export const formGroupPropNames = propNames<FormGroupProps>()(['label', 'help'])
+ * // ...
+ * props: [...formGroupPropNames, 'field']
+ * ```
+ */
+export function propNames<T>() {
+  return <const P extends readonly Extract<keyof T, string>[]>(
+    names: P & Exhaustive<Extract<keyof T, string>, P>,
+  ): P => names
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@falcondev-oss/nuxt-layers-base",
   "type": "module",
-  "version": "0.40.1",
+  "version": "0.40.2",
   "description": "Nuxt layer with lots of useful helpers and @nuxt/ui components",
   "license": "MIT",
   "repository": {