@glint/template 0.9.0 → 0.9.3

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

@@ -1,3 +1,4 @@
+import { AttrValue, ContentValue } from '..';
 import {
   AcceptsBlocks,
   AnyContext,
@@ -8,18 +9,18 @@ import {
   Invokable,
   TemplateContext,
 } from '../integration';
-import { ElementForTagName, EmittableValue } from './types';
+import { ElementForTagName } from './types';
 
 /*
- * Emits the given value to the DOM. This corresponds to a mustache
- * statement either at the top level:
+ * Emits the given value as top-level content to the DOM. This:
  *
- *     {{value}}
- *     {{value foo=bar}}
- *     <div data-x={{value foo=bar}}>
- *     <div data-x="hello {{value foo=bar}}">
+ *     Hello, {{world}}
+ *
+ * Would produce code like:
+ *
+ *     emitContent(resolveOrReturn(value)({}))
  */
-export declare function emitValue(value: AcceptsBlocks<{}, any> | EmittableValue): void;
+export declare function emitContent(value: ContentValue): void;
 
 /*
  * Emits an element of the given name, providing a value to the
@@ -63,16 +64,36 @@ export declare function emitComponent<T extends AcceptsBlocks<any, any>>(
   blockParams: T extends AcceptsBlocks<infer Yields, any> ? Required<Yields> : any;
 };
 
-/**
- * Acts as a top-level wrapper for translated template bodies. The given
- * callback accepts a template context value as well as an instance of the
+/*
+ * Wraps a template body that appears as a standalone expression and is therefore not
+ * associated with any backing value.
+ *
+ * The given callback accepts a template context value as well as an instance of the
  * environment's DSL export.
  */
-export declare function template<
+export declare function templateExpression<
   Signature extends AnyFunction = (args: EmptyObject) => AcceptsBlocks<EmptyObject>,
   Context extends AnyContext = TemplateContext<void, EmptyObject, EmptyObject, void>
 >(f: (𝚪: Context, χ: never) => void): new () => Invokable<Signature> & HasContext<Context>;
 
+/*
+ * Wraps a template body that's backed by a known value (typically a class), either
+ * via a `.hbs` association to a default export or via embedding e.g. with `<template>`.
+ *
+ * The given callback accepts a template context value as well as an instance of the
+ * environment's DSL export.
+ *
+ * Note that this signature is structured carefully to trigger TypeScript's higher-order function
+ * type inference so that any type parameters on the given backing value (if it's a class) will
+ * be preserved and reflected in the template body. Both the `Args` type and the constructor return
+ * value are necessary for this, despite the fact that we don't actually do anything with those
+ * types (see https://github.com/microsoft/TypeScript/pull/30215).
+ */
+export declare function templateForBackingValue<Args extends unknown[], Context extends AnyContext>(
+  backingValue: abstract new (...args: Args) => HasContext<Context>,
+  body: (𝚪: Context, χ: never) => void
+): abstract new () => unknown;
+
 /*
  * Used in template bodies to encode a `{{yield}}` statement.
  *
@@ -82,10 +103,10 @@ export declare function template<
  *
  *     yieldToBlock(𝚪, 'name', foo, bar);
  */
-export declare function yieldToBlock<Context extends AnyContext, K extends keyof Context['yields']>(
+export declare function yieldToBlock<Context extends AnyContext, K extends keyof Context['blocks']>(
   𝚪: Context,
   to: K,
-  ...values: NonNullable<Context['yields'][K]>
+  ...values: NonNullable<Context['blocks'][K]>
 ): void;
 
 /*
@@ -106,7 +127,7 @@ export declare function applySplattributes<
  *     <div foo={{bar}}></div>
  *     <AnotherComponent foo={{bar}} />
  */
-export declare function applyAttributes(element: Element, attrs: Record<string, unknown>): void;
+export declare function applyAttributes(element: Element, attrs: Record<string, AttrValue>): void;
 
 /*
  * Applies a modifier to an element or component.

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

@@ -1,4 +1,4 @@
-import { EmptyObject, HasContext } from '@glint/template/-private/integration';
+import { EmptyObject } from '@glint/template/-private/integration';
 
 type Constructor<T> = abstract new (...args: never[]) => T;
 
@@ -19,22 +19,3 @@ export type ElementForTagName<Name extends string> = Name extends keyof HTMLElem
   : Name extends keyof SVGElementTagNameMap
   ? SVGElementTagNameMap[Name]
   : Element;
-
-/**
- * Given the constructor or instance type of a component backing class, produces the appropriate
- * `TemplateContext` type for its template.
- */
-export type ResolveContext<T> = T extends HasContext<infer Context>
-  ? Context
-  : T extends Constructor<HasContext<infer Context>>
-  ? Context
-  : unknown;
-
-// This encompasses both @glimmer/runtime and @ember/template's notion of `SafeString`s,
-// and this coverage is tested in `emit-value.test.ts`.
-type SafeString = { toHTML(): string };
-
-/**
- * Represents values that can safely be emitted into the DOM i.e. as `<span>{{value}}</span>`.
- */
-export type EmittableValue = SafeString | Element | string | number | boolean | null | void;

package/-private/index.d.ts

@@ -8,6 +8,36 @@ import {
 } from './integration';
 import { ExpandSignature } from '@glimmer/component/-private/component';
 
+/**
+ * Any value that can be safely emitted into the DOM as top-level content,
+ * i.e. as `<div>{{value}}</div>`.
+ *
+ * This includes primitives like strings, numbers and booleans; "nothing"
+ * values like `null` and `undefined`; DOM nodes; and blockless curly
+ * component invocations.
+ */
+export type ContentValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | void
+  | SafeString
+  | Node
+  | ArglessCurlyComponent;
+
+/**
+ * Any value that can be safely set as an HTML attribute on a DOM node.
+ * This includes strings, numbers, booleans and `null`/`undefined`.
+ *
+ * Note that this does not include functions, as writing something like
+ * `onclick={{this.handleClick}}` in a template ultimately relies on
+ * fallback behavior in the VM to set the `onclick` property, and is
+ * better performed using the `{{on}}` modifier.
+ */
+export type AttrValue = string | number | boolean | null | undefined | SafeString;
+
 /**
  * A value that is invokable like a component in a template. In an
  * appropriate Glint environment, subclasses of `EmberComponent` and
@@ -112,3 +142,13 @@ type InvokableArgs<S> = [
   named: GuardEmpty<Get<Get<S, 'Args'>, 'Named'>>,
   ...positional: Constrain<Get<Get<S, 'Args'>, 'Positional'>, Array<unknown>, []>
 ];
+
+// This encompasses both @glimmer/runtime and @ember/template's notion of `SafeString`s,
+// and this coverage is tested in `emit-content.test.ts`.
+type SafeString = { toHTML(): string };
+
+// `{{foo}}` becomes `emitContent(resolveOrReturn(foo)({})`, which means if `foo`
+// is a component that accepts no args, then this is a valid invocation.
+type ArglessCurlyComponent = AcceptsBlocks<{}, any>;
+
+export {};

package/-private/integration.d.ts

@@ -2,6 +2,9 @@
 // module exports the symbols and types necessary to declare a class or
 // other entity as integrating with Glint's template system.
 
+import { EmptyObject } from '@glimmer/component/-private/component';
+export { EmptyObject };
+
 /** Any function, which is the tighest bound we can put on an object's `[Invoke]` field. */
 export type AnyFunction = (...params: any) => any;
 
@@ -23,8 +26,7 @@ export type HasContext<T extends AnyContext = AnyContext> = { [Context]: T };
 // These shenanigans are necessary to get TS to report when named args
 // are passed to a signature that doesn't expect any, because `{}` is
 // special-cased in the type system not to trigger EPC.
-declare const EmptyObject: unique symbol;
-export type EmptyObject = { [EmptyObject]?: void };
+
 export type GuardEmpty<T> = T extends any ? (keyof T extends never ? EmptyObject : T) : never;
 
 declare const Element: unique symbol;
@@ -47,10 +49,10 @@ export type AcceptsBlocks<BlockImpls, El = null> = {
  * Determines the type of `this` and any `@arg`s used in a template,
  * as well as valid `{{yield}}` invocations and `...attributes` usage.
  */
-export type TemplateContext<This, Args, Yields, Element> = {
+export type TemplateContext<This, Args, Blocks, Element> = {
   this: This;
   args: Args;
-  yields: Yields;
+  blocks: Blocks;
   element: Element;
 };
 

package/-private/keywords/in-element.d.ts

@@ -1,5 +1,10 @@
 import { AcceptsBlocks, DirectInvokable } from '../integration';
 
 export type InElementKeyword = DirectInvokable<{
-  (args: { insertBefore?: null | undefined }, element: Element): AcceptsBlocks<{ default: [] }>;
+  (
+    args: {
+      insertBefore?: null | undefined;
+    },
+    element: ShadowRoot | Element
+  ): AcceptsBlocks<{ default: [] }>;
 }>;

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@glint/template",
-  "version": "0.9.0",
+  "version": "0.9.3",
   "repository": "typed-ember/glint",
   "description": "Type definitions to back typechecking for Glimmer templates",
   "license": "MIT",
   "author": "Dan Freeman (https://github.com/dfreeman)",
   "types": "-private/index.d.ts",
   "scripts": {
-    "lint": "eslint . --max-warnings 0 && prettier --check .",
     "test": "tsc --project __tests__"
   },
   "files": [
@@ -20,7 +19,7 @@
   },
   "devDependencies": {
     "@glimmer/component": "^1.1.2",
-    "@glimmerx/component": "^0.4.2",
+    "@glimmerx/component": "^0.6.7",
     "@types/ember__component": "~4.0.8",
     "expect-type": "0.11.0",
     "sums-up": "^2.1.0"