Support user generated custom native JS classes.

pkg/js/lib/js.dart

+// Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/**
+ * The js library allows Dart library authors to export their APIs to JavaScript
+ * and to define Dart interfaces for JavaScript objects.
+ */
+library js;
+
+export 'dart:js' show allowInterop, allowInteropCaptureThis;
+
+// XXX this is a hack. remove.
+export 'dart:js' show registerJsInterfaces;
+
+/// A metadata annotation that indicates that a Library, Class, or member is
+/// implemented directly in JavaScript. All external members of a class or
+/// library with this annotation implicitly have it as well.
+///
+/// Specifying [name] customizes the JavaScript name to use. By default the
+/// dart name is used. It is not valid to specify a custom [name] for class
+/// instance members.
+///
+/// Example 1:
+///
+///     @Js('google.maps')
+///     library maps
+///
+///     external Map get map;
+///
+///     @Js("LatLng")
+///     class Location {
+///       external Location(num lat, num lng);
+///     }
+///
+///     @Js()
+///     class Map {
+///       external Map(Location location);
+///       external Location getLocation();
+///     }
+///
+/// In this example the top level map getter will invoke the JavaScript getter
+///     google.maps.map
+/// Calls to the Map constructor will be translated to calls to the JavaScript
+///     new google.maps.Map(location)
+/// Calls to the Location constructor willbe translated to calls to the
+/// JavaScript
+///     new google.maps.LatLng(lat, lng)
+/// because a custom JavaScript name for the Location class.
+/// In general, we recommend against using custom JavaScript names whenever
+/// possible as it is easier for users if the JavaScript names and Dart names
+/// are consistent.
+///
+/// Example 2:
+///     library utils;
+///
+///     @Js("JSON.stringify")
+///     external String stringify(obj);
+///
+///     @Js()
+///     void debugger();
+///
+/// In this example no custom JavaScript namespace is specified.
+/// Calls to debugger map to calls to JavaScript
+///     self.debugger()
+/// Calls to stringify map to calls to
+///     JSON.stringify(obj)
+class Js {
+  final String name;
+  const Js([this.name]);
+}