@glint/template 0.7.2 → 0.7.5

package/-private/dsl/resolve.d.ts

@@ -33,7 +33,7 @@ import { ResolveOrReturn } from './types';
 
 export declare function resolve<T extends DirectInvokable>(item: T): T[typeof InvokeDirect];
 export declare function resolve<Args extends unknown[], Instance extends Invokable>(
-  item: (new (...args: Args) => Instance) | null | undefined
+  item: (abstract new (...args: Args) => Instance) | null | undefined
 ): (...args: Parameters<Instance[typeof Invoke]>) => ReturnType<Instance[typeof Invoke]>;
 
 /*

package/-private/dsl/types.d.ts

@@ -1,6 +1,6 @@
 import { EmptyObject, HasContext } from '@glint/template/-private/integration';
 
-type Constructor<T> = new (...args: any) => T;
+type Constructor<T> = abstract new (...args: never[]) => T;
 
 /**
  * A utility for constructing the type of an environment's `resolveOrReturn` from

package/-private/index.d.ts

@@ -0,0 +1,114 @@
+import {
+  AcceptsBlocks,
+  AnyFunction,
+  BoundModifier,
+  EmptyObject,
+  FlattenBlockParams,
+  Invokable,
+} from './integration';
+import { ExpandSignature } from '@glimmer/component/dist/types/addon/-private/component';
+
+/**
+ * A value that is invokable like a component in a template. In an
+ * appropriate Glint environment, subclasses of `EmberComponent` and
+ * `GlimmerComponent` are examples of `ComponentLike` values, as are
+ * the values returned from the `{{component}}` helper.
+ *
+ * The `S` signature paramter here is of the same form as the one
+ * accepted by both the Ember and Glimmer `Component` base classes.
+ */
+export type ComponentLike<S = unknown> = InvokableConstructor<
+  (
+    named: ExpandSignature<S>['Args']['Named'],
+    ...positional: ExpandSignature<S>['Args']['Positional']
+  ) => AcceptsBlocks<
+    FlattenBlockParams<ExpandSignature<S>['Blocks']>,
+    ExpandSignature<S>['Element']
+  >
+>;
+
+/**
+ * A value that is invokable like a helper in a template. Notably,
+ * subclasses of `Helper` and the return value of `helper()` from
+ * `@ember/component/helper` are both `HelperLike` in an appropriate
+ * Glint environment.
+ *
+ * The `S` signature parameter here is of the same form as the one
+ * accepted by `Helper` and `helper`.
+ */
+export type HelperLike<S = unknown> = InvokableConstructor<
+  (...args: InvokableArgs<S>) => Get<S, 'Return', unknown>
+>;
+
+/**
+ * A value that is invokable like a modifier in a template. Notably,
+ * subclasses of `Modifier` and the return value of `modifier()` from
+ * `ember-modifier` are both `ModifierLike` in an appropriate Glint
+ * environment.
+ *
+ * The `S` signature parameter here is of the same form as the ones
+ * accepted by `Modifier` and `modifier`.
+ */
+export type ModifierLike<S = unknown> = InvokableConstructor<
+  (...args: InvokableArgs<S>) => BoundModifier<Constrain<Get<S, 'Element'>, Element>>
+>;
+
+/**
+ * Given a `ComponentLike`, `HelperLike` or `ModifierLike` value
+ * along with a union representing named args that have been
+ * pre-bound, this helper returns the same item back, but with those
+ * named arguments made optional.
+ *
+ * This is typically useful in conjunction with something like the
+ * `{{component}}` helper; for instance, if you wrote this in a
+ * template:
+ *
+ * ```handlebars
+ * {{yield (component MyComponent message="Hello")}}
+ * ```
+ *
+ * Consumers of that yielded value would be able to invoke the
+ * component without having to provide a value for `@message`
+ * themselves. You could represent this in your signature as:
+ *
+ * ```ts
+ * Blocks: {
+ *   default: [WithBoundArgs<typeof MyComponent, 'message'>];
+ * };
+ * ```
+ *
+ * If you had instead just written `default: [typeof MyComponent]`,
+ * consumers would still be obligated to provide a `@message`
+ * arg when invoking the yielded component.
+ */
+export type WithBoundArgs<
+  T extends InvokableConstructor<AnyFunction>,
+  BoundArgs extends NamedArgNames<T>
+> = T extends InvokableConstructor<
+  (named: infer Named, ...positional: infer Positional) => infer Result
+>
+  ? InvokableConstructor<
+      (
+        named: Omit<Named, BoundArgs> & Partial<Pick<Named, BoundArgs & keyof Named>>,
+        ...positional: Positional
+      ) => Result
+    >
+  : never;
+
+type InvokableConstructor<F extends AnyFunction> = abstract new (...args: any) => Invokable<F>;
+type NamedArgNames<T extends InvokableConstructor<AnyFunction>> = T extends InvokableConstructor<
+  (named: infer Named, ...positional: any) => any
+>
+  ? keyof Named
+  : never;
+
+type Get<T, K, Otherwise = unknown> = K extends keyof T ? T[K] : Otherwise;
+type Constrain<T, Constraint, Otherwise = Constraint> = T extends Constraint ? T : Otherwise;
+
+// We use the imported `ExpandSignature` for component signatures, as they have
+// different layers of possible shorthand, but modifiers and helpers only have
+// one structure they can specify their args in, so this utility is sufficient.
+type InvokableArgs<S> = [
+  named: Get<Get<S, 'Args'>, 'Named', EmptyObject>,
+  ...positional: Constrain<Get<Get<S, 'Args'>, 'Positional'>, Array<unknown>, []>
+];

package/-private/integration.d.ts

@@ -37,8 +37,8 @@ export type BoundModifier<El extends Element> = { [Modifier]: (el: El) => void }
  * Denotes that the associated entity may be invoked with the given
  * blocks, yielding params of the appropriate type.
  */
-export type AcceptsBlocks<BlockImpls, El extends Element | null = null> = {
-  [Element]: El;
+export type AcceptsBlocks<BlockImpls, El = null> = {
+  [Element]: El extends Element ? El : null;
   (blocks: BlockImpls): { [Blocks]: true };
 };
 
@@ -52,3 +52,17 @@ export type TemplateContext<This, Args, Yields, Element> = {
   yields: Yields;
   element: Element;
 };
+
+// This is a workaround for the fact that @glimmer/component initially shipped
+// with a bug that causes blocks to expand as `{ default: { Positional: [] } }` rather
+// thatn `{ default: { Params: { Positional: [] } } }`. Once a fix is released,
+// we can require at least that version starting in Glint 0.8 and drop this wrapper.
+type MaybeBlockParams<T> = T | { Params: T };
+
+/**
+ * Flattens the fully expanded signature format for Blocks down to a mapping from
+ * each block name to a corresponding tuple of parameter types.
+ */
+export type FlattenBlockParams<T> = {
+  [K in keyof T]: T[K] extends MaybeBlockParams<{ Positional: infer U }> ? U : T[K];
+};

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@glint/template",
-  "version": "0.7.2",
+  "version": "0.7.5",
   "repository": "typed-ember/glint",
   "description": "Type definitions to back typechecking for Glimmer templates",
   "license": "MIT",
   "author": "Dan Freeman (https://github.com/dfreeman)",
-  "types": "index.d.ts",
+  "types": "-private/index.d.ts",
   "scripts": {
     "lint": "eslint . --max-warnings 0 && prettier --check .",
     "test": "tsc --project __tests__"