grainjs 0.1.0 → 1.0.2

package/lib/domevent.ts

@@ -39,10 +39,14 @@
  *    let lis = domevent.onElem(elem, 'mouseup', e => { lis.dispose(); other_work(); });
  */
 
-import {DomElementMethod} from './_domImpl';
 import {IDisposable} from './dispose';
+import {DomElementMethod, DomMethod} from './domImpl';
 
-export type EventCB = (this: void, event: Event, elem: Element) => void;
+export type EventName = keyof HTMLElementEventMap;
+export type EventType<E extends EventName|string> = E extends EventName ? HTMLElementEventMap[E] : Event;
+
+export type EventCB<E extends Event = Event, T extends EventTarget = EventTarget> =
+  (this: void, event: E, elem: T) => void;
 
 function _findMatch(inner: Element, outer: Element, selector: string): Element|null {
   for (let el: Element|null = inner; el && el !== outer; el = el.parentElement) {
@@ -53,18 +57,18 @@ function _findMatch(inner: Element, outer: Element, selector: string): Element|n
   return null;
 }
 
-class DomEventListener implements EventListenerObject, IDisposable {
-  constructor(protected elem: EventTarget,
+class DomEventListener<E extends Event, T extends EventTarget> implements EventListenerObject, IDisposable {
+  constructor(protected elem: T,
               protected eventType: string,
-              protected callback: EventCB,
+              protected callback: EventCB<E, T>,
               protected useCapture: boolean,
               protected selector?: string) {
     this.elem.addEventListener(this.eventType, this, this.useCapture);
   }
 
-  public handleEvent(event: Event) {
+  public handleEvent(event: E) {
     const cb = this.callback;
-    cb(event, this.elem as Element);
+    cb(event, this.elem);
   }
 
   public dispose() {
@@ -72,8 +76,8 @@ class DomEventListener implements EventListenerObject, IDisposable {
   }
 }
 
-class DomEventMatchListener extends DomEventListener {
-  public handleEvent(event: Event) {
+class DomEventMatchListener<E extends Event> extends DomEventListener<E, EventTarget> {
+  public handleEvent(event: E) {
     const elem = _findMatch(event.target as Element, this.elem as Element, this.selector!);
     if (elem) {
       const cb = this.callback;
@@ -92,11 +96,13 @@ class DomEventMatchListener extends DomEventListener {
  *    rarely be useful (e.g. JQuery doesn't even offer it as an option).
  * @returns {Object} Listener object whose .dispose() method will remove the event listener.
  */
-export function onElem(elem: EventTarget, eventType: string, callback: EventCB,
-                       {useCapture = false} = {}): IDisposable {
+export function onElem<E extends EventName|string, T extends EventTarget>(
+  elem: T, eventType: E, callback: EventCB<EventType<E>, T>, {useCapture = false} = {}): IDisposable {
   return new DomEventListener(elem, eventType, callback, useCapture);
 }
-export function on(eventType: string, callback: EventCB, {useCapture = false} = {}): DomElementMethod {
+
+export function on<E extends EventName|string, T extends EventTarget>(
+  eventType: E, callback: EventCB<EventType<E>, T>, {useCapture = false} = {}): DomMethod<T> {
   // tslint:disable-next-line:no-unused-expression
   return (elem) => { new DomEventListener(elem, eventType, callback, useCapture); };
 }
@@ -126,27 +132,58 @@ export function onMatch(selector: string, eventType: string, callback: EventCB,
   return (elem) => { new DomEventMatchListener(elem, eventType, callback, useCapture, selector); };
 }
 
+export type KeyEventType = 'keypress' | 'keyup' | 'keydown';
+
+export interface IKeyHandlers<T extends HTMLElement = HTMLElement> {
+  [key: string]: (this: void, ev: KeyboardEvent, elem: T) => void;
+}
+
 /**
- * Listen to key presses, with specified per-key callbacks. The `onKeyPress()` variant takes no
- * `elem` argument, and may be used as an argument to dom().
- *
+ * Listen to key events (typically 'keydown' or 'keypress'), with specified per-key callbacks.
  * Key names are listed at https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values
  *
+ * Methods onKeyPress() and onKeyDown() are intended to be used as arguments to dom().
+ *
+ * By default, handled events are stopped from bubbling with stopPropagation() and
+ * preventDefault(). If, however, you register a key with a "$" suffix (i.e. "Enter$" instead of
+ * "Enter"), then the event is allowed to bubble normally.
+ *
+ * When this handler is set on an element, we automatically ensure that tabindex attribute is set,
+ * to allow this element to receive keyboard events.
+ *
  * For example:
  *
  *    dom('input', ...
- *      dom.onKeyPress({
+ *      dom.onKeyDown({
  *        Enter: (e, elem) => console.log("Enter pressed"),
  *        Escape: (e, elem) => console.log("Escape pressed"),
+ *        Delete$: (e, elem) => console.log("Delete pressed, will bubble"),
  *      })
  *    )
  */
-export function onKeyPressElem(elem: EventTarget, callbacks: {[key: string]: EventCB}): IDisposable {
-  return onElem(elem, 'keypress', (e, _elem) => {
-    const cb = callbacks[(e as KeyboardEvent).key];
-    if (cb) { cb(e, _elem); }
+export function onKeyElem<T extends HTMLElement>(
+  elem: T, evType: KeyEventType, keyHandlers: IKeyHandlers<T>,
+): IDisposable {
+  if (!(elem.tabIndex >= 0)) {                    // If tabIndex property is undefined or -1,
+    elem.setAttribute('tabindex', '-1');          // Set tabIndex attribute to make the element focusable.
+  }
+  return onElem(elem, evType, (ev, _elem) => {
+    const plainHandler = keyHandlers[ev.key];
+    const handler = plainHandler || keyHandlers[ev.key + '$'];
+    if (handler) {
+      if (plainHandler!) {
+        ev.stopPropagation();
+        ev.preventDefault();
+      }
+      handler(ev, _elem);
+    }
   });
 }
-export function onKeyPress(callbacks: {[key: string]: EventCB}): DomElementMethod {
-  return (elem) => { onKeyPressElem(elem, callbacks); };
+
+export function onKeyPress<T extends HTMLElement>(keyHandlers: IKeyHandlers<T>): DomMethod<T> {
+  return (elem) => { onKeyElem(elem, 'keypress', keyHandlers); };
+}
+
+export function onKeyDown<T extends HTMLElement>(keyHandlers: IKeyHandlers<T>): DomMethod<T> {
+  return (elem) => { onKeyElem(elem, 'keydown', keyHandlers); };
 }

package/lib/emit.ts

@@ -116,7 +116,8 @@ export class Emitter extends LLink {
    * Sets the single callback that would get called when a listener is added or removed.
    * @param {Function} changeCB(hasListeners): Function to call after a listener is added or
    *    removed. It's called with a boolean indicating whether this Emitter has any listeners.
-   *    Pass in `null` to unset the callback.
+   *    Pass in `null` to unset the callback. Note that it can be called multiple times in a row
+   *    with hasListeners `true`.
    */
   public setChangeCB(changeCB: ChangeCB, optContext?: any): void {
     this._changeCB = changeCB || _noop;

package/lib/kowrap.ts

@@ -19,10 +19,12 @@
  * knockout as a dependency of grainjs.
  *
  * In both cases, calling fromKo/toKo twice on the same observable will return the same wrapper,
- * and subscriptions and disposal are appropriately set up to make usage seamless.
+ * and subscriptions and disposal are appropriately set up to make usage seamless. In particular,
+ * the returned wrapper should not be disposed; it's tied to the lifetime of the wrapped object.
  */
 
-import {observable, Observable} from './observable';
+import {domDisposeHooks} from './domDispose';
+import {bundleChanges, Observable} from './observable';
 
 // Implementation note. Both wrappers are implemented in the same way.
 //
@@ -31,31 +33,69 @@ import {observable, Observable} from './observable';
 // be garbage-collected once it has no listeners AND the underlying observable is disposed or
 // unreferenced.
 
-export interface IKnockoutObservable<T> {
+export interface IKnockoutObservable<T> extends IKnockoutReadObservable<T> {
   (val: T): void;
+}
+
+export interface IKnockoutReadObservable<T> {
+  (): T;
   peek(): T;
   subscribe(callback: (newValue: T) => void, target?: any, event?: "change"): any;
+  getSubscriptionsCount(): number;
 }
 
+// Inference from Knockout observable gets very tricky because ko.Observable includes the function
+// signature `(val: T) => any` from which type `any` gets inferred. We can infer the correct type
+// with this helper.
+export type InferKoType<KObs extends IKnockoutReadObservable<any>> =
+  KObs extends {peek(): infer T} ? T : never;
+
 const fromKoWrappers: WeakMap<IKnockoutObservable<any>, Observable<any>> = new WeakMap();
 const toKoWrappers: WeakMap<Observable<any>, IKnockoutObservable<any>> = new WeakMap();
 
 /**
  * Returns a Grain.js observable which mirrors a Knockout observable.
+ *
+ * Do not dispose this wrapper, as it is shared by all code using koObs, and its lifetime is tied
+ * to the lifetime of koObs. If unused, it consumes minimal resources, and should get garbage
+ * collected along with koObs.
+ */
+export function fromKo<KObs extends IKnockoutObservable<any>>(koObs: KObs): Observable<InferKoType<KObs>> {
+  return fromKoWrappers.get(koObs) || fromKoWrappers.set(koObs, new KoWrapObs(koObs)).get(koObs)!;
+}
+
+/**
+ * An Observable that wraps a Knockout observable, created via fromKo(). It keeps minimal overhead
+ * when unused by only subscribing to the wrapped observable while it itself has subscriptions.
+ *
+ * This way, when unused, the only reference is from the wrapper to the wrapped object. KoWrapObs
+ * should not be disposed; its lifetime is tied to that of the wrapped object.
  */
-export function fromKo<T>(koObservable: IKnockoutObservable<T>): Observable<T> {
-  const prevObs = fromKoWrappers.get(koObservable);
-  if (prevObs) {
-    return prevObs;
+export class KoWrapObs<T> extends Observable<T> {
+  private _koSub: any = null;
+
+  constructor(private _koObs: IKnockoutObservable<T>) {
+    super(_koObs.peek());
+    this.setListenerChangeCB((hasListeners) => {
+      if (!hasListeners) {
+        this._koSub.dispose();
+        this._koSub = null;
+      } else if (!this._koSub) {
+        // TODO this is a little hack, really, BaseObservable should expose a way to set the value
+        // directly by derived classes, i.e. a protected setter.
+        (this as any)._value = this._koObs.peek();
+        this._koSub = this._koObs.subscribe((val) => this.setAndTrigger(val));
+      }
+    });
   }
-  const newObs = observable(koObservable.peek());
-  fromKoWrappers.set(koObservable, newObs);
-  koObservable.subscribe((val) => newObs.set(val));
-  return newObs;
+  public get(): T { return this._koObs.peek(); }
+  public set(value: T): void { bundleChanges(() => this._koObs(value)); }
+  public dispose(): void { throw new Error("KoWrapObs should not be disposed"); }
 }
 
 export interface IKnockoutModule {
   observable<T>(value: T): IKnockoutObservable<T>;
+  cleanNode(node: Node): void;
 }
 
 /**
@@ -71,3 +111,61 @@ export function toKo<T>(knockout: IKnockoutModule, grainObs: Observable<T>): IKn
   grainObs.addListener((val) => newKoObs(val));
   return newKoObs;
 }
+
+// Marker for when knockout-disposal integration has already been setup.
+let koDisposalIsSetup = false;
+
+/**
+ * Set up integration between grainjs and knockout disposal. Knockout does cleanup using
+ * ko.removeNode / ko.cleanNode (it also takes care of JQuery cleanup if needed). GrainJS does
+ * cleanup using dom.domDispose(). By default these don't know about each other.
+ *
+ * If you mix the two libraries, however, disposing an element may need to trigger disposers
+ * registered by either library.
+ *
+ * This method ensures that this happens.
+ *
+ * Note: grainjs disposes text nodes too, but nothing relies on it. When disposal is triggered via
+ * knockout, we are forced to rely on knockout's node traversal which ignores text nodes.
+ */
+export function setupKoDisposal(ko: IKnockoutModule) {
+  // Ensure we don't do the setup more than once, or things will get called multiple times.
+  if (koDisposalIsSetup) { return; }
+  koDisposalIsSetup = true;
+
+  const koDomNodeDisposal = (ko as any).utils.domNodeDisposal;
+
+  // Knockout by default has an external-data-cleanup func set to cleanup JQuery. Whatever it is
+  // set to, we will continue calling it, and also will call grainjs domDisposeNode.
+  const origKoCleanExternalData = koDomNodeDisposal.cleanExternalData;
+
+  // The original function called by grainjs to clean nodes recursively. We'll override it.
+  const origGrainDisposeRecursive = domDisposeHooks.disposeRecursive;
+
+  // New function called by knockout to do extra cleanup. Now calls grainjs single-node cleanup.
+  // (In knockout, we can only override single-node cleanup.)
+  function newKoCleanExternalData(node: Node) {
+    origKoCleanExternalData(node);
+    domDisposeHooks.disposeNode(node);
+  }
+
+  // Function called by grainjs to clean nodes recursively. We override the recursive cleanup
+  // function to call the recursive knockout cleanup (letting knockout do the dom traversal it
+  // normally does).
+  function newGrainDisposeRecursive(node: Node) {
+    origGrainDisposeRecursive(node);
+
+    // While doing knockout cleanup, do NOT have it call grainjs cleanup too, as that would cause
+    // multiple unnecessary traversals of DOM.
+    koDomNodeDisposal.cleanExternalData = origKoCleanExternalData;
+    try {
+      ko.cleanNode(node);
+    } finally {
+      koDomNodeDisposal.cleanExternalData = newKoCleanExternalData;
+    }
+  }
+
+  // Use knockout and grainjs hooks to actually set the new cleanup functions.
+  koDomNodeDisposal.cleanExternalData = newKoCleanExternalData;
+  domDisposeHooks.disposeRecursive = newGrainDisposeRecursive;
+}

package/lib/obsArray.ts

@@ -31,7 +31,7 @@
  * ownership of those disposables that are added to it as array elements.
  */
 
-import {IDisposable, IDisposableOwner, setDisposeOwner} from './dispose';
+import {IDisposable, IDisposableOwnerT, setDisposeOwner} from './dispose';
 import {Listener} from './emit';
 import {BaseObservable, Observable} from './observable';
 import {subscribe, Subscription} from './subscribe';
@@ -291,7 +291,7 @@ export function computedArray<T, U>(
  * The returned observable has an additional .setLive(bool) method. While set to false, the
  * observable will not be adjusted as the array changes, except to keep it valid.
  */
-export function makeLiveIndex<T>(owner: IDisposableOwner|null, obsArr: ObsArray<T>,
+export function makeLiveIndex<T>(owner: IDisposableOwnerT<LiveIndex>|null, obsArr: ObsArray<T>,
                                  initialIndex: number = 0): LiveIndex {
   return setDisposeOwner(owner, new LiveIndex(obsArr, initialIndex));
 }

package/lib/observable.ts

@@ -22,7 +22,7 @@
  */
 
 import {compute, DepItem} from './_computed_queue';
-import {IDisposable, IDisposableOwnerT} from './dispose';
+import {IDisposable, IDisposableOwnerT, setDisposeOwner} from './dispose';
 import {Emitter, Listener} from './emit';
 
 export {bundleChanges} from './_computed_queue';
@@ -90,7 +90,8 @@ export class BaseObservable<T> {
    * previously-set such callback.
    * @param {Function} changeCB(hasListeners): Function to call after a listener is added or
    *    removed. It's called with a boolean indicating whether this observable has any listeners.
-   *    Pass in `null` to unset the callback.
+   *    Pass in `null` to unset the callback. Note that it can be called multiple times in a row
+   *    with hasListeners `true`.
    */
   public setListenerChangeCB(changeCB: (hasListeners: boolean) => void, optContext?: any): void {
     this._onChange.setChangeCB(changeCB, optContext);
@@ -143,6 +144,13 @@ export class Observable<T> extends BaseObservable<T> implements IDisposableOwner
     return obs;
   }
 
+  /**
+   * Creates a new Observable with the given initial value, and owned by owner.
+   */
+  public static create<T>(owner: IDisposableOwnerT<Observable<T>>|null, value: T): Observable<T> {
+    return setDisposeOwner(owner, new Observable<T>(value));
+  }
+
   private _owned?: T & IDisposable = undefined;
 
   /**

package/lib/pureComputed.ts

@@ -11,15 +11,16 @@
  */
 
 import {DepItem} from './_computed_queue';
-import {Observable} from './observable';
-import {ISubscribable, Subscription, UseCB} from './subscribe';
+import {IKnockoutReadObservable} from './kowrap';
+import {BaseObservable, Observable} from './observable';
+import {ISubscribable, ISubscribableObs, Subscription, UseCB} from './subscribe';
 
 function _noWrite(): never {
   throw new Error("Can't write to non-writable pureComputed");
 }
 
-function _useFunc<T>(obs: Observable<T>): T {
-  return obs.get();
+function _useFunc<T>(obs: BaseObservable<T>|IKnockoutReadObservable<T>): T {
+  return ('get' in obs) ? obs.get() : obs.peek();
 }
 
 // Constant empty array, which we use to avoid allocating new read-only empty arrays.
@@ -29,7 +30,7 @@ export class PureComputed<T> extends Observable<T> {
   private _callback: (use: UseCB, ...args: any[]) => T;
   private _write: (value: T) => void;
   private _sub: Subscription|null;
-  private readonly _dependencies: ReadonlyArray<ISubscribable>;
+  private readonly _dependencies: ReadonlyArray<ISubscribableObs>;
   private _inCall: boolean;
 
   /**
@@ -57,7 +58,7 @@ export class PureComputed<T> extends Observable<T> {
       // _inCall member prevents infinite recursion.
       this._inCall = true;
       try {
-        const readArgs: any[] = [_useFunc];
+        const readArgs: [UseCB, ...any[]] = [_useFunc];
         // Note that this attempts to optimize for speed.
         for (let i = 0, len = this._dependencies.length; i < len; i++) {
           readArgs[i + 1] = this._dependencies[i].get();

package/lib/styled.ts

@@ -54,32 +54,38 @@
  *      myButton(myButton.cls('-small'), 'Test')
  *
  * creates a button with both the myButton style above, and the style specified under "&-small".
+ *
+ * Animations with @keyframes may be created with a unique name by using the keyframes() helper:
+ *
+ *    const rotate360 = keyframes(`
+ *      from { transform: rotate(0deg); }
+ *      to { transform: rotate(360deg); }
+ *    `);
+ *
+ *    const Rotate = styled('div', `
+ *      display: inline-block;
+ *      animation: ${rotate360} 2s linear infinite;
+ *    `);
  */
 
 // Use the browser globals in a way that allows replacing them with mocks in tests.
 import {G} from './browserGlobals';
-import {dom, DomElementArg, DomElementMethod} from './dom';
-
-export type DomCreateFunc0<R> = (...args: DomElementArg[]) => R;
-export type DomCreateFunc1<R, T> = (a: T, ...args: DomElementArg[]) => R;
-export type DomCreateFunc2<R, T, U> = (a: T, b: U, ...args: DomElementArg[]) => R;
-export type DomCreateFunc3<R, T, U, W> = (a: T, b: U, c: W, ...args: DomElementArg[]) => R;
+import {dom, IDomArgs, TagElem, TagName} from './domImpl';
+import {cls, clsPrefix} from './domMethods';
 
 // The value returned by styled() matches the input (first argument), and also implements IClsName
 // interface.
 export interface IClsName {
   className: string;      // Name of the generated class.
-  cls: typeof dom.cls;    // Helper like dom.cls(), but which prefixes classes by className.
+  cls: typeof cls;        // Helper like dom.cls(), but which prefixes classes by className.
 }
 
+export type DomCreateFunc<R, Args extends IDomArgs<R> = IDomArgs<R>> = (...args: Args) => R;
+
 // See module documentation for details.
-export function styled<R>(tag: string, styles: string): DomCreateFunc0<Element> & IClsName;
-export function styled<R>(creator: DomCreateFunc0<R>, styles: string): DomCreateFunc0<R> & IClsName;
-export function styled<R, T>(creator: DomCreateFunc1<R, T>, styles: string): DomCreateFunc1<R, T> & IClsName;
-export function styled<R, T, U>(
-  creator: DomCreateFunc2<R, T, U>, styles: string): DomCreateFunc2<R, T, U> & IClsName;
-export function styled<R, T, U, W>(
-  creator: DomCreateFunc3<R, T, U, W>, styles: string): DomCreateFunc3<R, T, U, W> & IClsName;
+export function styled<Tag extends TagName>(tag: Tag, styles: string): DomCreateFunc<TagElem<Tag>> & IClsName;
+export function styled<Args extends any[], R extends Element>(
+  creator: (...args: Args) => R, styles: string): typeof creator & IClsName;
 export function styled(creator: any, styles: string): IClsName {
   // Note that we intentionally minimize the work done when styled() is called; it's better to do
   // any needed work on first use. That's when we will actually build the css rules.
@@ -88,45 +94,54 @@ export function styled(creator: any, styles: string): IClsName {
   // Creator function reflects the input, with only the addition of style.use() at the end. Note
   // that it needs to be at the end because creator() might take special initial arguments.
   const newCreator = (typeof creator === 'string') ?
-    (...args: DomElementArg[]) => dom(creator, ...args, style.use()) :
-    (...args: any[]) => creator(...args, style.use());
+    (...args: any[]) => style.addToElem(dom(creator, ...args)) :
+    (...args: any[]) => style.addToElem(creator(...args));
   return Object.assign(newCreator, {
     className: style.className,
-    cls: dom.clsPrefix.bind(null, style.className),
+    cls: clsPrefix.bind(null, style.className),
   });
 }
 
+// Keyframes produces simply a string with the generated name. Note that these does not support
+// nesting or ampersand (&) handling, since these would be difficult and are entirely unneeded.
+export function keyframes(styles: string): string {
+  return (new KeyframePiece(styles)).className;
+}
+
 function createCssRules(className: string, styles: string) {
-  const nestedRules: string[] = [];
-
-  // Parse out nested styles. Replacing them by empty string in the main section, and add them to
-  // nestedRules array to be joined up at the end. Replace & with .className.
-  const mainRules = styles.replace(/([^;]*)\s*{([^}]*)\s*}/g, (match, selector, rules) => {
-    const fullSelector = selector.replace(/&/g, '.' + className);
-    nestedRules.push(`${fullSelector} {${rules}}`);
-    return '';
-  });
+  // The first time we encounter a nested section, we know which are the "main" rules, and can
+  // wrap them appropriately.
+  const nestedStart = styles.search(/[^;]*\{/);
+  const mainRules = nestedStart < 0 ? styles : styles.slice(0, nestedStart);
+  const nestedRules = nestedStart < 0 ? "" : styles.slice(nestedStart);
+
+  // At the end, replace all occurrences of & with ".className".
+  return `& {${mainRules}\n}\n${nestedRules}`.replace(/&/g, className);
+}
+
+// Used by getNextStyleNum when running without a global window object (e.g. in tests).
+const _global = {};
 
-  // Actual styles to include into the generated stylesheet.
-  return `.${className} {${mainRules}}\n` + nestedRules.join('\n');
+// Keep the counter for next class attached to the global window object rather than be a library
+// global. This way if by some chance multiple instance of grainjs are loaded into the page, it
+// still works without overwriting class names (which would be extremely confusing).
+function getNextStyleNum() {
+  const g: any = G.window || _global;
+  return g._grainNextStyleNum = (g._grainNextStyleNum || 0) + 1;
 }
 
 class StylePiece {
-  // Index of next auto-generated css class name.
-  private static _next: number = 1;
-
   // Set of all StylePieces created but not yet mounted.
   private static _unmounted = new Set<StylePiece>();
 
-  // Generate a new css class name.
-  private static _nextClassName() { return `_grain${this._next++}`; }
+  // Generate a new css class name. The suffix ensures that names like "&2" can't cause a conflict.
+  private static _nextClassName() { return `_grain${getNextStyleNum()}_`; }
 
   // Mount all unmounted StylePieces, and clear the _unmounted map.
   private static _mountAll(): void {
-    const sheet = Array.from(this._unmounted, (p) => createCssRules(p.className, p._styles))
-    .join('\n\n');
+    const sheet: string = Array.from(this._unmounted, (p) => p._createRules()).join("\n\n");
 
-    G.document.head.appendChild(dom('style', sheet));
+    G.document.head!.appendChild(dom('style', sheet));
     for (const piece of this._unmounted) {
       piece._mounted = true;
     }
@@ -136,13 +151,24 @@ class StylePiece {
   public readonly className: string;
   private _mounted: boolean = false;
 
-  constructor(private _styles: string) {
+  constructor(protected _styles: string) {
     this.className = StylePiece._nextClassName();
     StylePiece._unmounted.add(this);
   }
 
-  public use(): DomElementMethod {
+  public addToElem<T extends Element>(elem: T): T {
     if (!this._mounted) { StylePiece._mountAll(); }
-    return (elem) => { elem.classList.add(this.className); };
+    elem.classList.add(this.className);
+    return elem;
+  }
+
+  protected _createRules(): string {
+    return createCssRules('.' + this.className, this._styles);
+  }
+}
+
+class KeyframePiece extends StylePiece {
+  protected _createRules(): string {
+    return `@keyframes ${this.className} {${this._styles}}`;
   }
 }

package/lib/subscribe.ts

@@ -19,17 +19,31 @@
  */
 
 import {DepItem} from './_computed_queue';
+import {IDisposableOwner} from './dispose';
 import {Listener} from './emit';
+import {fromKo, IKnockoutReadObservable} from './kowrap';
 import {BaseObservable as Obs} from './observable';
 
-export interface ISubscribable {
+export interface ISubscribableObs {
   _getDepItem(): DepItem|null;
   addListener(callback: (val: any, prev: any) => void, optContext?: object): Listener;
   get(): any;
 }
 
+export type ISubscribable = ISubscribableObs | IKnockoutReadObservable<any>;
+
+// Type inference from the simpler Obs<T>|IKnockoutReadObservable<T> does not always produce
+// correct T for ko.Observable. The formula below is a workaround. See also InferKoType in kowrap.
+export type InferUseType<TObs extends Obs<any>|IKnockoutReadObservable<any>> =
+  TObs extends Obs<infer T> ? T :
+  TObs extends {peek(): infer U} ? U : never;
+
 // The generic type for the use() function that callbacks get.
-export type UseCB = <T>(obs: Obs<T>) => T;
+export type UseCB = <TObs extends Obs<any>|IKnockoutReadObservable<any>>(obs: TObs) => InferUseType<TObs>;
+
+export interface UseCBOwner extends UseCB {    // tslint:disable-line:interface-name
+  owner: IDisposableOwner;
+}
 
 interface IListenerWithInUse extends Listener {
   _inUse: boolean;
@@ -40,9 +54,9 @@ const emptyArray: ReadonlyArray<any> = [];
 
 export class Subscription {
   private readonly _depItem: DepItem;
-  private readonly _dependencies: ReadonlyArray<ISubscribable>;
+  private readonly _dependencies: ReadonlyArray<ISubscribableObs>;
   private readonly _depListeners: ReadonlyArray<Listener>;
-  private _dynDeps: Map<ISubscribable, IListenerWithInUse>;
+  private _dynDeps: Map<ISubscribableObs, IListenerWithInUse>;
   private _callback: (use: UseCB, ...args: any[]) => void;
   private _useFunc: UseCB;
 
@@ -59,7 +73,7 @@ export class Subscription {
     this._callback = callback;
     this._useFunc = this._useDependency.bind(this);
     if (owner) {
-      (this._useFunc as any).owner = owner;
+      (this._useFunc as UseCBOwner).owner = owner;
     }
 
     this._evaluate();
@@ -85,7 +99,8 @@ export class Subscription {
    * subscription to `obs` if one doesn't yet exist.
    * @param {Observable} obs: The observable being used as a dependency.
    */
-  private _useDependency(obs: ISubscribable) {
+  private _useDependency(_obs: ISubscribable) {
+    const obs = ('_getDepItem' in _obs) ? _obs : fromKo(_obs);
     let listener = this._dynDeps.get(obs);
     if (!listener) {
       listener = this._subscribeTo(obs) as IListenerWithInUse;
@@ -105,7 +120,7 @@ export class Subscription {
     if (this._callback === null) { return; }      // Means this Subscription has been disposed.
     try {
       // Note that this is faster than using .map().
-      const readArgs = [this._useFunc];
+      const readArgs: [UseCB, ...any[]] = [this._useFunc];
       for (let i = 0, len = this._dependencies.length; i < len; i++) {
         readArgs[i + 1] = this._dependencies[i].get();
         this._depItem.useDep(this._dependencies[i]._getDepItem());
@@ -130,7 +145,8 @@ export class Subscription {
    * @param {Observable} obs: The observable to subscribe to.
    * @returns {Listener} Listener object.
    */
-  private _subscribeTo(obs: ISubscribable) {
+  private _subscribeTo(_obs: ISubscribable) {
+    const obs = ('_getDepItem' in _obs) ? _obs : fromKo(_obs);
     return obs.addListener(this._enqueue, this);
   }