Roll Observatory packages and add a roll script

charted/lib/selection/selection.dart

-/*
- * Copyright 2014 Google Inc. All rights reserved.
- *
- * Use of this source code is governed by a BSD-style
- * license that can be found in the LICENSE file or at
- * https://developers.google.com/open-source/licenses/bsd
- */
-/*
- * TODO(prsd): Document library
- */
-library charted.selection;
-
-import "dart:html" show Element, Event, document;
-import "dart:math" as math;
-import "package:charted/core/utils.dart";
-import "package:charted/selection/transition.dart";
-
-part "selection_scope.dart";
-part "src/selection_impl.dart";
-
-/**
- * Callback to access key value from a given data object. During the process
- * of binding data to Elements, the key values are used to match Elements
- * that have previously bound data
- */
-typedef SelectionKeyFunction(datum);
-
-/**
- * Callback for all DOM related operations - The first parameter [datum] is
- * the piece of data associated with the node, [ei] is the index of the
- * element in it's group and [c] is the context to which the data is
- * associated to.
- */
-typedef E SelectionCallback<E>(datum, int index, Element element);
-
-/** Callback used to access a value from a datum */
-typedef E SelectionValueAccessor<E>(datum, int index);
-
-/** Create a ChartedCallback that always returns [val] */
-SelectionCallback toCallback(val) => (datum, index, element) => val;
-
-/** Create a ChartedValueAccessor that always returns [val] */
-SelectionValueAccessor toValueAccessor(val) => (datum, index) => val;
-
-/**
- * [Selection] is a collection of elements - this collection defines
- * operators that can be applied on all elements of the collection.
- *
- * All operators accept parameters either as a constant value or a callback
- * function (typically using the named parameters "val" and "fn"). These
- * operators, when invoked with the callback function, the function is
- * called once per element and is passed the "data" associated, the "index"
- * and the element itself.
- */
-abstract class Selection {
-  /**
-   * Collection of groups - A selection when created by calling [selectAll]
-   * on an existing [Selection], could contain more than one group.
-   */
-  Iterable<SelectionGroup> groups;
-
-  /**
-   * Scope of this selection that manages the element, data associations for
-   * all elements in this selection (and the sub-selections)
-   */
-  SelectionScope get scope;
-
-  /** Indicates if this selection is empty */
-  bool get isEmpty;
-
-  /** Number of elements in this selection */
-  int get length;
-
-  /** First non-null element in this selection, if any. */
-  Element get first;
-
-  /**
-   * Creates and returns a new [Selection] containing the first element
-   * matching [selector] under each element in the current selection.
-   *
-   * If an element does not have a matching descendant, a placeholder is used
-   * in it's position - thus being able to match the indices of elements in
-   * the current and the created sub-selection.
-   *
-   * Any data bound to elements in this selection is inherited by the
-   * selected descendants.
-   */
-  Selection select(String selector);
-
-  /**
-   * Same as [select], but calls [fn] for each non-null element in the
-   * selection (with data associated to the element, index of the element in
-   * it's group and the element itself) to get the selected element that will
-   * be selected.
-   */
-  Selection selectWithCallback(SelectionCallback<Element> fn);
-
-  /**
-   * Creates and returns a new [Selection] containing all elements matching
-   * [selector] under each element in the current selection.
-   *
-   * The resulting [Selection] is nested with elements from current selection
-   * as parents and the selected descendants grouped by elements in the
-   * current selection.  When no descendants match the selector, the
-   * collection of selected elements in a group is empty.
-   *
-   * Data bound to the elements is not automatically inherited by the
-   * selected descendants.
-   */
-  Selection selectAll(String selector);
-
-  /**
-   * Same as [selectAll], but calls [fn] for each non-null element in the
-   * selection (with data associated to the element, index of the element in
-   * it's group and the element itself) to get a collection of selected
-   * elements that will be part of the new selection.
-   */
-  Selection selectAllWithCallback(SelectionCallback<Iterable<Element>> fn);
-
-  /**
-   * Sets the attribute [name] on all elements when [val] is not null.
-   * Removes the attribute when [val] is null.
-   */
-  void attr(String name, val);
-
-  /**
-   * Same as [attr], but calls [fn] for each non-null element in the
-   * selection (with data associated to the element, index of the element in
-   * it's group and the element itself) to get the value of the attribute.
-   */
-  void attrWithCallback(String name, SelectionCallback fn);
-
-  /**
-   * Ensures presence of a class when [val] is true.  Ensures that the class
-   * isn't present if [val] is false.
-   */
-  void classed(String name, [bool val = true]);
-
-  /**
-   * Same as [classed], but calls [fn] for each non-null element in the
-   * selection (with data associated to the element, index of the element in
-   * it's group and the element itself) to get the boolean value that
-   * indicates if the class must be added or removed.
-   */
-  void classedWithCallback(String name, SelectionCallback<bool> fn);
-
-  /** Sets CSS [property] to [val] on all elements in the selection. */
-  void style(String property, val, {String priority});
-
-  /**
-   * Same as [style], but calls [fn] for each non-null element in the
-   * selection (with data associated to the element, index of the element in
-   * it's group and the element itself) to get the value of the property.
-   */
-  void styleWithCallback(String property,
-      SelectionCallback<String> fn, {String priority});
-
-  /**
-   * Sets textContent of all elements in the selection to [val]. A side-effect
-   * of this call is that any children of these elements will not be part of
-   * the DOM anymore.
-   */
-  void text(String val);
-
-  /**
-   * Same as [text], but calls [fn] for each non-null element in
-   * the selection (with data associated to the element, index of the
-   * element in it's group and the element itself) to get the text content
-   */
-  void textWithCallback(SelectionCallback<String> fn);
-
-  /**
-   * Sets innerHtml of all elements in the selection to [val]. A side-effect
-   * of this call is that any children of these elements will not be part of
-   * the DOM anymore.
-   */
-  void html(String val);
-
-  /**
-   * Same as [html], but calls [fn] for each non-null element in
-   * the selection (with data associated to the element, index of the
-   * element in it's group and the element itself) to get the html content
-   */
-  void htmlWithCallback(SelectionCallback<String> fn);
-
-  /**
-   * Appends a new child element to each element in the selection.
-   *
-   * Returns a [Selection] containing the newly created elements. As with
-   * [select], any data bound to the elements in this selection is inherited
-   * by the new elements.
-   */
-  Selection append(String tag);
-
-  /**
-   * Same as [append], but calls [fn] for each non-null element in the
-   * selection (with data associated to the element, index of the element in
-   * it's group and the element itself) to get the element to be appended.
-   */
-  Selection appendWithCallback(SelectionCallback<Element> fn);
-
-  /**
-   * Inserts a child node to each element in the selection before the first
-   * element matching [before] or before the element returned by [beforeFn].
-   *
-   * Returns a [Selection] containing the newly created elements. As with
-   * [select], any data bound to the elements in this selection is inherited
-   * by the new elements.
-   */
-  Selection insert(String tag,
-      {String before, SelectionCallback<Element> beforeFn});
-
-  /**
-   * Same as [insert], but calls [fn] for each non-null element in the
-   * selection (with data associated to the element, index of the element in
-   * it's group and the element itself) to get the element to be inserted.
-   */
-  Selection insertWithCallback(SelectionCallback<Element> fn,
-      {String before, SelectionCallback<Element> beforeFn});
-
-  /** Removes all selected elements from the DOM */
-  void remove();
-
-  /** Calls [fn] on each element in this selection */
-  void each(SelectionCallback fn);
-
-  /**
-   * Adds or removes an event [listener] to each element in the selection for
-   * the specified [type] (Eg: "mouseclick", "mousedown")
-   *
-   * Any existing listener of the same type will be removed.  To register
-   * multiple listener for the same event type, the [type] can be suffixed
-   * with a namespace. (Eg: "mouseclick.foo", "mousedown.bar")
-   *
-   * When [listener] is null, any existing listener of the same type and in
-   * the same namespace will be removed (Eg: Using "mouseclick.foo" as type
-   * will only remove listeners for "mouseclick.foo" and not "mouseclick.bar")
-   *
-   * To remove listeners of an event type in all namespaces, prefix the type
-   * with a "." (Eg: ".mouseclick" will remove "mouseclick.bar",
-   * "mouseclick .foo" and all other mouseclick event listeners)
-   *
-   * To summarize, [type] can be any DOM event type optionally in the format
-   * "event.namespace" where event is the DOM event type and namespace is
-   * used to distinguish between added listeners.
-   *
-   * When [listener] is called, it is passed the current value associated with
-   * the element.  Please note that index passed to the listener contains a
-   * value as it was at the time of adding the listener.
-   */
-  void on(String type, [SelectionCallback listener, bool capture]);
-
-  /**
-   * Associates data with the selected elements.
-   * Computes the enter, update and exit selections.
-   */
-  DataSelection data(Iterable vals, [SelectionKeyFunction keyFn]);
-
-  /**
-   * Same as [data], but calls [fn] for each non-null element in the
-   * selection (with data associated to the element, index of the element in
-   * it's group and the element itself) to get the data to be set on the
-   * current element.
-   */
-  DataSelection dataWithCallback(
-      SelectionCallback<Iterable> fn, [SelectionKeyFunction keyFn]);
-
-  /**
-   * Associates data with all the elements - no join is performed. Unlike
-   * [data], this does not compute the enter, update and exit selections.
-   */
-  void datum(Iterable vals);
-
-  /**
-   * Same as [datum], but calls [fn] for each non-null element in the
-   * selection (with data associated to the element, index of the element in
-   * it's group and the element itself) to get the data to be set on the
-   * current element.
-   */
-  void datumWithCallback(SelectionCallback<Iterable> fn);
-
-  /**
-   * Starts a transition for the current selection. Transitions behave much
-   * like selections, except operators animate smoothly over time rather than
-   * applying instantaneously.
-   */
-  Transition transition();
-}
-
-
-/*
- * Group of elements in the selection.
- * Each selection may contain more than one group of elements.
- */
-abstract class SelectionGroup {
-  Iterable<Element> elements;
-  Element parent;
-}
-
-
-/**
- * [EnterSelection] is a sub-selection that represents missing elements of a
- * selection - an element is considered missing when there is data and no
- * corresponding element in a selection.
- */
-abstract class EnterSelection {
-  /**
-   * Indicate if this selection is empty
-   * See [Selection.isEmpty] for more information.
-   */
-  bool get isEmpty;
-
-  /** [DataSelection] that corresponds to this selection. */
-  DataSelection get update;
-
-  /**
-   * Appends an element to all elements in this selection and return
-   * [Selection] containing the newly added elements.
-   *
-   * See [Selection.append] for more information.
-   * The new nodes are merged into the [DataSelection]
-   */
-  Selection append(String tag);
-
-  /**
-   * Same as [append] but calls [fn] to get the element to be appended.
-   * See [Selection.appendWithCallback] for more information.
-   */
-  Selection appendWithCallback(SelectionCallback<Element> fn);
-
-  /**
-   * Insert a child node to each element in the selection and return
-   * [Selection] containing the newly added elements.
-   *
-   * See [Selection.insert] for more information.
-   * The new nodes are merged into the [UpdateSelection]
-   */
-  Selection insert(String tag,
-      {String before, SelectionCallback<Element> beforeFn});
-
-  /**
-   * Same as [insert] but calls [fn] to get the element to be inserted.
-   * See [Selection.insertWithCallback] for more information.
-   */
-  Selection insertWithCallback(SelectionCallback<Element> fn,
-      {String before, SelectionCallback<Element> beforeFn});
-
-  /**
-   * For each element in the current selection, select exactly one
-   * descendant and return [Selection] containing the selected elements.
-   *
-   * See [Selection.select] for more information.
-   */
-  Selection select(String selector);
-
-  /**
-   * Same as [select] but calls [fn] to get the element to be inserted.
-   * See [Selection.selectWithCallback] for more information.
-   */
-  Selection selectWithCallback(SelectionCallback<Element> fn);
-}
-
-/*
- * [ExitSelection] is a sub-selection that represents elements that don't
- * have data associated to them.
- */
-abstract class ExitSelection extends Selection {
-  DataSelection get update;
-}
-
-/*
- * Selection that consists elements in the selection that aren't part of
- * [EnterSelection] or the [ExitSelection]
- *
- * An [UpdateSelection] is only available after data() is attached and is
- * currently exactly the same as [Selection] itself.
- */
-abstract class DataSelection extends Selection {
-  /**
-   * A view of the current selection that contains a collection of data
-   * elements which weren't associated with an element in the DOM.
-   */
-  EnterSelection get enter;
-
-  /**
-   * A view of the current selection containing elements that don't have data
-   * associated with them.
-   */
-  ExitSelection get exit;
-}