From 46a54d32162aec7c58f304df1fdb66b15f7d02f7 Mon Sep 17 00:00:00 2001 From: Ivaylo Gochkov Date: Wed, 18 Dec 2013 00:03:12 +0100 Subject: [PATCH 1/5] Initial version Work is still in progress! --- README.md | 3 +- typeahead/typeahead-tests.ts | 72 +++++++++++++++++++ typeahead/typeahead.d.ts | 129 +++++++++++++++++++++++++++++++++++ 3 files changed, 203 insertions(+), 1 deletion(-) create mode 100644 typeahead/typeahead-tests.ts create mode 100644 typeahead/typeahead.d.ts diff --git a/README.md b/README.md index 7e305efe3..6f72a9e36 100755 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -DefinitelyTyped [![Build Status](https://travis-ci.org/borisyankov/DefinitelyTyped.png?branch=master)](https://travis-ci.org/borisyankov/DefinitelyTyped) +DefinitelyTyped [![Build Status](https://travis-ci.org/borisyankov/DefinitelyTyped.png?branch=master)](https://travis-ci.org/borisyankov/DefinitelyTyped) =============== The repository for *high quality* TypeScript type definitions. @@ -231,6 +231,7 @@ List of Definitions * [TweenJS](http://www.createjs.com/#!/TweenJS) (by [Pedro Ferreira](https://bitbucket.org/drk4)) * [tween.js](https://github.com/sole/tween.js/) (by [Adam R. Smith](https://github.com/sunetos)) * [twitter-bootstrap-wizard](https://github.com/VinceG/twitter-bootstrap-wizard) (by [Blake Niemyjski](https://github.com/niemyjski)) +* [Typeahead.js](http://twitter.github.io/typeahead.js) (by [Ivaylo Gochkov](https://github.com/igochkov)) * [Ubuntu Unity Web API](https://launchpad.net/libunity-webapps) (by [John Vrbanac](https://github.com/jmvrbanac)) * [Underscore.js](http://underscorejs.org/) (by [Boris Yankov](https://github.com/borisyankov)) * [Underscore.js (Typed)](http://underscorejs.org/) (by [Josh Baldwin](https://github.com/jbaldwin/)) diff --git a/typeahead/typeahead-tests.ts b/typeahead/typeahead-tests.ts new file mode 100644 index 000000000..ee41ea3f5 --- /dev/null +++ b/typeahead/typeahead-tests.ts @@ -0,0 +1,72 @@ +/// +/// + +// +// Examples from http://twitter.github.com/typeahead.js/examples +// + +// Countries +// Prefetches data, stores it in localStorage, and searches it on the client +$('.example-countries .typeahead').typeahead({ + name: 'countries', + prefetch: '../data/countries.json', + limit: 10 +}); + +// Open Source Projects by Twitter +// Defines a custom template and template engine for rendering suggestions +//$('.example-twitter-oss .typeahead').typeahead({ +// name: 'twitter-oss', +// prefetch: '../data/repos.json', +// template: [ +// '

{{language}}

', +// '

{{name}}

', +// '

{{description}}

' +// ].join(''), +// engine: Hogan +//}); + +// Arabic Phrases +// Hardcoded list showing Right - To - Left(RTL) support +$('.example-arabic .typeahead').typeahead({ + name: 'arabic', + local: [ + "الإنجليزية", + "نعم", + "لا", + "مرحبا", + "کيف الحال؟", + "أهلا", + "مع السلامة", + "لا أتكلم العربية", + "لا أفهم", + "أنا جائع" + ] +}); + +// NBA and NHL Teams +// Two datasets that are prefetched, stored, and searched on the client +$('.example-sports .typeahead').typeahead([ + { + name: 'nba-teams', + prefetch: '../data/nba.json', + header: '

NBA Teams

' + }, + { + name: 'nhl-teams', + prefetch: '../data/nhl.json', + header: '

NHL Teams

' + } +]); + +// Best Picture Winners +// Prefetches some data then relies on remote requests for suggestions when prefetched data is insufficient +//$('.example-films .typeahead').typeahead([ +// { +// name: 'best-picture-winners', +// remote: '../data/films/queries/%QUERY.json', +// prefetch: '../data/films/post_1960.json', +// template: '

{{value}} – {{year}}

', +// engine: Hogan +// } +//]); \ No newline at end of file diff --git a/typeahead/typeahead.d.ts b/typeahead/typeahead.d.ts new file mode 100644 index 000000000..f4baec0e6 --- /dev/null +++ b/typeahead/typeahead.d.ts @@ -0,0 +1,129 @@ +// Type definitions for Twitter's typeahead.js 0.9.3 +// Project: http://twitter.github.io/typeahead.js/ +// Definitions by: Ivaylo Gochkov +// Definitions: https://github.com/borisyankov/DefinitelyTyped + +/// + +declare module Twitter.Typeahead { + /** + * A dataset is an object that defines a set of data that hydrates + * suggestions. Typeaheads can be backed by multiple datasets. + * Given a query, a typeahead instance will inspect its backing + * datasets and display relevant suggestions to the end-user. + */ + interface Dataset { + /** + * The string used to identify the dataset. Used by typeahead.js + * to cache intelligently. + */ + name: string; + /** + * The key used to access the value of the datum in the datum object. + * Defaults to value. + */ + valueKey?: string; + /** + * The max number of suggestions from the dataset to display + * for a given query. Defaults to 5. + */ + limit?: number; + /** + * The template used to render suggestions. Can be a string or + * a precompiled template. If not provided, suggestions will render + * as their value contained in a

element (i.e.

value

). + */ + template?: any; + /** + * The template engine used to compile/render template if it is a + * string. Any engine can use used as long as it adheres to the + * expected API. Required if template is a string. + */ + engine?: string; + /** + * The header rendered before suggestions in the dropdown menu. + * Can be either a DOM element or HTML. + */ + header?: any; + /** + * The footer rendered after suggestions in the dropdown menu. + * Can be either a DOM element or HTML. + */ + footer?: any; + /** + * An array of {Twitter.Typeahead.Datum}. + */ + local?: any[]; + /** + * Can be a URL to a JSON file containing an array of datums or, + * if more configurability is needed, a prefetch options object + * {Twitter.Typeahead.PrefetchOptions}. + */ + prefetch?: any; + /** + * Can be a URL to fetch suggestions from when the data provided by + * local and prefetch is insufficient or, if more configurability is + * needed, a remote options object {Twitter.Typeahead.RemoteOptions}. + */ + remote?: any; + } + + interface PrefetchOptions { + url: string; + ttl?: number; + filter?: (parsedResponse: any) => Datum[]; + } + + interface RemoteOptions { + url: string; + dataType?: string; + cache?: boolean; + timeout?: number; + wildcard?: string; + replace?: (url: string, uriEncodedQuery: string) => string; + rateLimitFn?: any; // debounce or trottle + rateLimitWait?: number; + maxParallelRequests?: number; + beforeSend?: (jqXhr: JQueryXHR, settings: JQueryAjaxSettings) => void; + filter?: (parsedResponse: any) => Datum[]; + } + + interface Datum { + value: string; + tokens: string[]; + } + + interface TypeaheadStatic { + VERSION: string; + utils: TypeaheadUtils; + } + + interface TypeaheadUtils { + debounce: (func: any, wait: number, immediate: boolean) => any; + throttle: (func: any, wait: number) => any; + } +} + +interface JQuery { + /** + * Turns an input[type="text"] element into a typeahead. + * + * @constructor + * @param dataset Single dataset + */ + typeahead(dataset: Twitter.Typeahead.Dataset): JQuery; + + /** + * Turns an input[type="text"] element into a typeahead. + * + * @constructor + * @param dataset Array of datasets + */ + typeahead(datasets: Twitter.Typeahead.Dataset[]): JQuery; + + typeahead(methodName: string): JQuery; + typeahead(methodName: 'destroy'): JQuery; + typeahead(methodName: 'setQuery'): JQuery; +} + +declare var typeahead: Twitter.Typeahead.TypeaheadStatic; \ No newline at end of file From 2f03c505f9456010b168d1f0b9c6930a5cc92d98 Mon Sep 17 00:00:00 2001 From: Ivaylo Gochkov Date: Wed, 18 Dec 2013 11:37:24 +0100 Subject: [PATCH 2/5] JSDoc comments completed --- typeahead/typeahead.d.ts | 197 +++++++++++++++++++++++++++++++-------- 1 file changed, 157 insertions(+), 40 deletions(-) diff --git a/typeahead/typeahead.d.ts b/typeahead/typeahead.d.ts index f4baec0e6..4db093e01 100644 --- a/typeahead/typeahead.d.ts +++ b/typeahead/typeahead.d.ts @@ -3,7 +3,54 @@ // Definitions by: Ivaylo Gochkov // Definitions: https://github.com/borisyankov/DefinitelyTyped -/// +/// + +interface JQuery { + /** + * Turns an input[type="text"] element into a typeahead. + * + * @constructor + * @param dataset Single dataset + */ + typeahead(dataset: Twitter.Typeahead.Dataset): JQuery; + + /** + * Turns an input[type="text"] element into a typeahead. + * + * @constructor + * @param dataset Array of datasets + */ + typeahead(datasets: Twitter.Typeahead.Dataset[]): JQuery; + + /** + * Destroys previously initialized typeaheads. This entails reverting + * DOM modifications and removing event handlers. + * + * @constructor + * @param methodName Method 'destroy' + */ + typeahead(methodName: 'destroy'): JQuery; + + /** + * Sets the current query of the typeahead. This is always preferable to + * using $("input.typeahead").val(query), which will result in unexpected + * behavior. To clear the query, simply set it to an empty string. + * + * @constructor + * @param methodName Method 'setQuery' + * @param query The query to be set + */ + typeahead(methodName: 'setQuery', query: string): JQuery; + + /** + * Accommodates the destroy and setQuery overloads. + * + * @constructor + * @param methodName Method name ('destroy' or 'setQuery') + * @param query The query to be set in case method 'setQuery' is used. + */ + typeahead(methodName: string, query: string): JQuery; +} declare module Twitter.Typeahead { /** @@ -51,79 +98,149 @@ declare module Twitter.Typeahead { */ footer?: any; /** - * An array of {Twitter.Typeahead.Datum}. + * An array of datums or strings. */ local?: any[]; /** * Can be a URL to a JSON file containing an array of datums or, - * if more configurability is needed, a prefetch options object - * {Twitter.Typeahead.PrefetchOptions}. + * if more configurability is needed, a prefetch options object. */ prefetch?: any; /** * Can be a URL to fetch suggestions from when the data provided by * local and prefetch is insufficient or, if more configurability is - * needed, a remote options object {Twitter.Typeahead.RemoteOptions}. + * needed, a remote options object. */ remote?: any; } + /** + * Prefetched data is fetched and processed on initialization. + * If the browser supports localStorage, the processed data will be cached + * there to prevent additional network requests on subsequent page loads. + */ interface PrefetchOptions { + /** + * A URL to a JSON file containing an array of datums. Required. + */ url: string; + + /** + * The time (in milliseconds) the prefetched data should be cached + * in localStorage. Defaults to 86400000 (1 day). + */ ttl?: number; + + /** + * A function that transforms the response body into an array of datums. + * + * @param parsedResponse Response body + */ filter?: (parsedResponse: any) => Datum[]; } + /** + * Remote data is only used when the data provided by local and prefetch + * is insufficient. In order to prevent an obscene number of requests + * being made to remote endpoint, typeahead.js rate-limits remote requests. + */ interface RemoteOptions { + /** + * A URL to make requests to when the data provided by local and + * prefetch is insufficient. Required. + */ url: string; + + /** + * The type of data you're expecting from the server. Defaults to json. + * @see http://api.jquery.com/jQuery.ajax/ for more info. + */ dataType?: string; + + /** + * Determines whether or not the browser will cache responses. + * @see http://api.jquery.com/jQuery.ajax/ for more info. + */ cache?: boolean; + + /** + * Sets a timeout for requests. + * @see http://api.jquery.com/jQuery.ajax/ for more info. + */ timeout?: number; + + /** + * The pattern in url that will be replaced with the user's query + * when a request is made. Defaults to %QUERY. + */ wildcard?: string; + + /** + * Overrides the request URL. If set, no wildcard substitution will + * be performed on url. + * + * @param url Replacement URL + * @param uriEncodedQuery Encoded query + * @returns A valid URL + */ replace?: (url: string, uriEncodedQuery: string) => string; - rateLimitFn?: any; // debounce or trottle + + /** + * The function used for rate-limiting network requests. + * Can be either 'debounce' or 'throttle'. Defaults to 'debounce'. + */ + rateLimitFn?: string; + + /** + * The time interval in milliseconds that will be used by rateLimitFn. + * Defaults to 300. + */ rateLimitWait?: number; + + /** + * The max number of parallel requests typeahead.js can have pending. + * Defaults to 6. + */ maxParallelRequests?: number; + + /** + * A pre-request callback. Can be used to set custom headers. + * @see http://api.jquery.com/jQuery.ajax/ for more info. + */ beforeSend?: (jqXhr: JQueryXHR, settings: JQueryAjaxSettings) => void; + + /** + * Transforms the response body into an array of datums. + * + * @param parsedResponse Response body + */ filter?: (parsedResponse: any) => Datum[]; } + /** + * The individual units that compose datasets are called datums. + * The canonical form of a datum is an object with a value property and + * a tokens property. + * + * For ease of use, datums can also be represented as a string. + * Strings found in place of datum objects are implicitly converted + * to a datum object. + * + * When datums are rendered as suggestions, the datum object is the + * context passed to the template engine. This means if you include any + * arbitrary properties in datum objects, those properties will be + * available to the template used to render suggestions. + */ interface Datum { + /** + * The string that represents the underlying value of the datum + */ value: string; + + /** + * A collection of single-word strings that aid typeahead.js in + * matching datums with a given query. + */ tokens: string[]; } - - interface TypeaheadStatic { - VERSION: string; - utils: TypeaheadUtils; - } - - interface TypeaheadUtils { - debounce: (func: any, wait: number, immediate: boolean) => any; - throttle: (func: any, wait: number) => any; - } } - -interface JQuery { - /** - * Turns an input[type="text"] element into a typeahead. - * - * @constructor - * @param dataset Single dataset - */ - typeahead(dataset: Twitter.Typeahead.Dataset): JQuery; - - /** - * Turns an input[type="text"] element into a typeahead. - * - * @constructor - * @param dataset Array of datasets - */ - typeahead(datasets: Twitter.Typeahead.Dataset[]): JQuery; - - typeahead(methodName: string): JQuery; - typeahead(methodName: 'destroy'): JQuery; - typeahead(methodName: 'setQuery'): JQuery; -} - -declare var typeahead: Twitter.Typeahead.TypeaheadStatic; \ No newline at end of file From 984598314f4a0081c7207fa114cf9edb35fc5662 Mon Sep 17 00:00:00 2001 From: Ivaylo Gochkov Date: Wed, 18 Dec 2013 12:08:02 +0100 Subject: [PATCH 3/5] Hogan variable Declared Hogan variable to mock Hogan template engine definitions. --- typeahead/typeahead-tests.ts | 39 ++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/typeahead/typeahead-tests.ts b/typeahead/typeahead-tests.ts index ee41ea3f5..dee467e0f 100644 --- a/typeahead/typeahead-tests.ts +++ b/typeahead/typeahead-tests.ts @@ -4,6 +4,7 @@ // // Examples from http://twitter.github.com/typeahead.js/examples // +declare var Hogan: any; // Countries // Prefetches data, stores it in localStorage, and searches it on the client @@ -15,16 +16,16 @@ $('.example-countries .typeahead').typeahead({ // Open Source Projects by Twitter // Defines a custom template and template engine for rendering suggestions -//$('.example-twitter-oss .typeahead').typeahead({ -// name: 'twitter-oss', -// prefetch: '../data/repos.json', -// template: [ -// '

{{language}}

', -// '

{{name}}

', -// '

{{description}}

' -// ].join(''), -// engine: Hogan -//}); +$('.example-twitter-oss .typeahead').typeahead({ + name: 'twitter-oss', + prefetch: '../data/repos.json', + template: [ + '

{{language}}

', + '

{{name}}

', + '

{{description}}

' + ].join(''), + engine: Hogan +}); // Arabic Phrases // Hardcoded list showing Right - To - Left(RTL) support @@ -61,12 +62,12 @@ $('.example-sports .typeahead').typeahead([ // Best Picture Winners // Prefetches some data then relies on remote requests for suggestions when prefetched data is insufficient -//$('.example-films .typeahead').typeahead([ -// { -// name: 'best-picture-winners', -// remote: '../data/films/queries/%QUERY.json', -// prefetch: '../data/films/post_1960.json', -// template: '

{{value}} – {{year}}

', -// engine: Hogan -// } -//]); \ No newline at end of file +$('.example-films .typeahead').typeahead([ + { + name: 'best-picture-winners', + remote: '../data/films/queries/%QUERY.json', + prefetch: '../data/films/post_1960.json', + template: '

{{value}} – {{year}}

', + engine: Hogan + } +]); From f324e429886dc2163e0083b391266705d0c3d50d Mon Sep 17 00:00:00 2001 From: Ivaylo Gochkov Date: Wed, 18 Dec 2013 12:39:13 +0100 Subject: [PATCH 4/5] Reference path correction --- typeahead/typeahead.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/typeahead/typeahead.d.ts b/typeahead/typeahead.d.ts index 4db093e01..8d4050c94 100644 --- a/typeahead/typeahead.d.ts +++ b/typeahead/typeahead.d.ts @@ -3,7 +3,7 @@ // Definitions by: Ivaylo Gochkov // Definitions: https://github.com/borisyankov/DefinitelyTyped -/// +/// interface JQuery { /** From 27127b9bb8e2ef11ddd725b6a4a02f9afb003d7e Mon Sep 17 00:00:00 2001 From: Ivaylo Gochkov Date: Wed, 18 Dec 2013 12:44:24 +0100 Subject: [PATCH 5/5] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6f72a9e36..77f8c05ac 100755 --- a/README.md +++ b/README.md @@ -231,7 +231,7 @@ List of Definitions * [TweenJS](http://www.createjs.com/#!/TweenJS) (by [Pedro Ferreira](https://bitbucket.org/drk4)) * [tween.js](https://github.com/sole/tween.js/) (by [Adam R. Smith](https://github.com/sunetos)) * [twitter-bootstrap-wizard](https://github.com/VinceG/twitter-bootstrap-wizard) (by [Blake Niemyjski](https://github.com/niemyjski)) -* [Typeahead.js](http://twitter.github.io/typeahead.js) (by [Ivaylo Gochkov](https://github.com/igochkov)) +* [Twitter Typeahead](http://twitter.github.io/typeahead.js) (by [Ivaylo Gochkov](https://github.com/igochkov)) * [Ubuntu Unity Web API](https://launchpad.net/libunity-webapps) (by [John Vrbanac](https://github.com/jmvrbanac)) * [Underscore.js](http://underscorejs.org/) (by [Boris Yankov](https://github.com/borisyankov)) * [Underscore.js (Typed)](http://underscorejs.org/) (by [Josh Baldwin](https://github.com/jbaldwin/))