1 | declare module '@ember/-internals/glimmer/lib/helper' {
|
2 | /**
|
3 | @module @ember/component
|
4 | */
|
5 | import { FrameworkObject } from '@ember/object/-internals';
|
6 | import type { Arguments, HelperManager } from '@glimmer/interfaces';
|
7 | import type { DirtyableTag } from '@glimmer/validator';
|
8 | export const RECOMPUTE_TAG: unique symbol;
|
9 | type GetOr<T, K, Else> = K extends keyof T ? T[K] : Else;
|
10 | type Args<S> = GetOr<S, 'Args', {}>;
|
11 | type DefaultPositional = unknown[];
|
12 | type Positional<S> = GetOr<Args<S>, 'Positional', DefaultPositional>;
|
13 | type Named<S> = GetOr<Args<S>, 'Named', object>;
|
14 | type Return<S> = GetOr<S, 'Return', unknown>;
|
15 | export interface HelperFactory<T> {
|
16 | isHelperFactory: true;
|
17 | create(): T;
|
18 | }
|
19 | export interface HelperInstance<S> {
|
20 | compute(positional: Positional<S>, named: Named<S>): Return<S>;
|
21 | destroy(): void;
|
22 | [RECOMPUTE_TAG]: DirtyableTag;
|
23 | }
|
24 | const IS_CLASSIC_HELPER: unique symbol;
|
25 | export interface SimpleHelper<S> {
|
26 | compute: (positional: Positional<S>, named: Named<S>) => Return<S>;
|
27 | }
|
28 | const SIGNATURE: unique symbol;
|
29 | /**
|
30 | Ember Helpers are functions that can compute values, and are used in templates.
|
31 | For example, this code calls a helper named `format-currency`:
|
32 |
|
33 | ```app/templates/application.hbs
|
34 | <Cost @cents={{230}} />
|
35 | ```
|
36 |
|
37 | ```app/components/cost.hbs
|
38 | <div>{{format-currency @cents currency="$"}}</div>
|
39 | ```
|
40 |
|
41 | Additionally a helper can be called as a nested helper.
|
42 | In this example, we show the formatted currency value if the `showMoney`
|
43 | named argument is truthy.
|
44 |
|
45 | ```handlebars
|
46 | {{if @showMoney (format-currency @cents currency="$")}}
|
47 | ```
|
48 |
|
49 | Helpers defined using a class must provide a `compute` function. For example:
|
50 |
|
51 | ```app/helpers/format-currency.js
|
52 | import Helper from '@ember/component/helper';
|
53 |
|
54 | export default class extends Helper {
|
55 | compute([cents], { currency }) {
|
56 | return `${currency}${cents * 0.01}`;
|
57 | }
|
58 | }
|
59 | ```
|
60 |
|
61 | Each time the input to a helper changes, the `compute` function will be
|
62 | called again.
|
63 |
|
64 | As instances, these helpers also have access to the container and will accept
|
65 | injected dependencies.
|
66 |
|
67 | Additionally, class helpers can call `recompute` to force a new computation.
|
68 |
|
69 | @class Helper
|
70 | @extends CoreObject
|
71 | @public
|
72 | @since 1.13.0
|
73 | */
|
74 | export default interface Helper<S = unknown> {
|
75 | /**
|
76 | Override this function when writing a class-based helper.
|
77 |
|
78 | @method compute
|
79 | @param {Array} positional The positional arguments to the helper
|
80 | @param {Object} named The named arguments to the helper
|
81 | @public
|
82 | @since 1.13.0
|
83 | */
|
84 | compute(positional: Positional<S>, named: Named<S>): Return<S>;
|
85 | }
|
86 | export default class Helper<S = unknown> extends FrameworkObject {
|
87 | static isHelperFactory: boolean;
|
88 | static [IS_CLASSIC_HELPER]: boolean;
|
89 | /** @deprecated */
|
90 | static helper: typeof helper;
|
91 | [RECOMPUTE_TAG]: DirtyableTag;
|
92 | private [SIGNATURE];
|
93 | init(properties: object | undefined): void;
|
94 | /**
|
95 | On a class-based helper, it may be useful to force a recomputation of that
|
96 | helpers value. This is akin to `rerender` on a component.
|
97 |
|
98 | For example, this component will rerender when the `currentUser` on a
|
99 | session service changes:
|
100 |
|
101 | ```app/helpers/current-user-email.js
|
102 | import Helper from '@ember/component/helper'
|
103 | import { service } from '@ember/service'
|
104 | import { observer } from '@ember/object'
|
105 |
|
106 | export default Helper.extend({
|
107 | session: service(),
|
108 |
|
109 | onNewUser: observer('session.currentUser', function() {
|
110 | this.recompute();
|
111 | }),
|
112 |
|
113 | compute() {
|
114 | return this.get('session.currentUser.email');
|
115 | }
|
116 | });
|
117 | ```
|
118 |
|
119 | @method recompute
|
120 | @public
|
121 | @since 1.13.0
|
122 | */
|
123 | recompute(): void;
|
124 | }
|
125 | export function isClassicHelper(obj: object): boolean;
|
126 | export const CLASSIC_HELPER_MANAGER:
|
127 | | import('@glimmer/interfaces').Helper<object>
|
128 | | import('@glimmer/manager').CustomHelperManager<object>;
|
129 | class Wrapper<S = unknown> implements HelperFactory<SimpleHelper<S>> {
|
130 | compute: (positional: Positional<S>, named: Named<S>) => Return<S>;
|
131 | readonly isHelperFactory = true;
|
132 | constructor(compute: (positional: Positional<S>, named: Named<S>) => Return<S>);
|
133 | create(): SimpleHelper<S>;
|
134 | }
|
135 | class SimpleClassicHelperManager implements HelperManager<() => unknown> {
|
136 | capabilities: import('@glimmer/interfaces').HelperCapabilities;
|
137 | createHelper(definition: Wrapper, args: Arguments): () => unknown;
|
138 | getValue(fn: () => unknown): unknown;
|
139 | getDebugName(definition: Wrapper): string;
|
140 | }
|
141 | export const SIMPLE_CLASSIC_HELPER_MANAGER: SimpleClassicHelperManager;
|
142 | /**
|
143 | * The type of a function-based helper.
|
144 | *
|
145 | * @note This is *not* user-constructible: it is exported only so that the type
|
146 | * returned by the `helper` function can be named (and indeed can be exported
|
147 | * like `export default helper(...)` safely).
|
148 | */
|
149 | export type FunctionBasedHelper<S> = abstract new () => FunctionBasedHelperInstance<S>;
|
150 | export abstract class FunctionBasedHelperInstance<S> extends Helper<S> {
|
151 | protected abstract __concrete__: never;
|
152 | }
|
153 | /**
|
154 | In many cases it is not necessary to use the full `Helper` class.
|
155 | The `helper` method create pure-function helpers without instances.
|
156 | For example:
|
157 |
|
158 | ```app/helpers/format-currency.js
|
159 | import { helper } from '@ember/component/helper';
|
160 |
|
161 | export default helper(function([cents], {currency}) {
|
162 | return `${currency}${cents * 0.01}`;
|
163 | });
|
164 | ```
|
165 |
|
166 | @static
|
167 | @param {Function} helper The helper function
|
168 | @method helper
|
169 | @for @ember/component/helper
|
170 | @public
|
171 | @since 1.13.0
|
172 | */
|
173 | export function helper<P extends DefaultPositional, N extends object, R = unknown>(
|
174 | helperFn: (positional: P, named: N) => R
|
175 | ): FunctionBasedHelper<{
|
176 | Args: {
|
177 | Positional: P;
|
178 | Named: N;
|
179 | };
|
180 | Return: R;
|
181 | }>;
|
182 | export function helper<S>(
|
183 | helperFn: (positional: Positional<S>, named: Named<S>) => Return<S>
|
184 | ): FunctionBasedHelper<S>;
|
185 | export {};
|
186 | }
|