grainjs 1.0.1 → 1.1.0

package/lib/styled.ts

@@ -1,87 +1,85 @@
+// Use the browser globals in a way that allows replacing them with mocks in tests.
+import {G} from './browserGlobals';
+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 cls;        // Helper like dom.cls(), but which prefixes classes by className.
+}
+
+export type DomCreateFunc<R, Args extends IDomArgs<R> = IDomArgs<R>> = (...args: Args) => R;
+
 /**
  * In-code styling for DOM components, inspired by Reacts Styled Components.
  *
  * Usage:
- *    const title = styled('h1', `
- *      font-size: 1.5em;
- *      text-align: center;
- *      color: palevioletred;
- *    `);
- *
- *    const wrapper = styled('section', `
- *      padding: 4em;
- *      background: papayawhip;
- *    `);
- *
- *    wrapper(title('Hello world'))
- *
- * This generates class names for title and wrapper, adds the styles to the document on first use,
- * and the result is equivalent to:
- *
- *    dom(`section.${wrapper.className}`, dom(`h1.${title.className}`, 'Hello world'));
- *
- * Calls to styled() should happen at the top level, at import time, in order to register all
+ * ```ts
+ * const cssTitle = styled('h1', `
+ *   font-size: 1.5em;
+ *   text-align: center;
+ *   color: palevioletred;
+ * `);
+ *
+ * const cssWrapper = styled('section', `
+ *   padding: 4em;
+ *   background: papayawhip;
+ * `);
+ *
+ * cssWrapper(cssTitle('Hello world'))
+ * ```
+ *
+ * This generates class names for `cssTitle` and `cssWrapper`, adds the styles to the document on
+ * first use, and the result is equivalent to:
+ * ```ts
+ * dom(`section.${cssWrapper.className}`, dom(`h1.${cssTitle.className}`, 'Hello world'));
+ * ```
+ *
+ * What `styled(tag)` returns is a function that takes the same arguments `...args` as
+ * `dom(tag, ...args)`. In particular, you may call it with all the arguments that
+ * [`dom()`](#dom) takes: content, DOM methods, event handlers, etc.
+ *
+ * Calls to `styled()` should happen at the top level, at import time, in order to register all
  * styles upfront. Actual work happens the first time a style is needed to create an element.
- * Calling styled() elsewhere than at top level is wasteful and bad for performance.
- *
- * You may create a style that modifies an existing styled() or other component, e.g.
+ * Calling `styled()` elsewhere than at top level is wasteful and bad for performance.
  *
- *    const title2 = styled(title, `font-size: 1rem; color: red;`);
+ * You may create a style that modifies an existing `styled()` or other component, e.g.
+ * ```ts
+ * const cssTitle2 = styled(cssTitle, `font-size: 1rem; color: red;`);
+ * ```
  *
- * Calling title2('Foo') becomes equivalent to dom(`h1.${title.className}.${title2.className}`).
+ * Now calling `cssTitle2('Foo')` becomes equivalent to
+ * `dom('h1', {className: cssTitle.className + ' ' + cssTitle2.className})`.
  *
  * Styles may incorporate other related styles by nesting them under the main one as follows:
- *
- *     const myButton = styled('button', `
- *       border-radius: 0.5rem;
- *       border: 1px solid grey;
- *       font-size: 1rem;
- *
- *       &:active {
- *         background: lightblue;
- *       }
- *       &-small {
- *         font-size: 0.6rem;
- *       }
- *     `);
+ * ```ts
+ * const myButton = styled('button', `
+ *   border-radius: 0.5rem;
+ *   border: 1px solid grey;
+ *   font-size: 1rem;
+ *
+ *   &:active {
+ *     background: lightblue;
+ *   }
+ *   &-small {
+ *     font-size: 0.6rem;
+ *   }
+ * `);
+ * ```
  *
  * In nested styles, ampersand (&) gets replaced with the generated .className of the main element.
  *
- * The resulting styled component provides a .cls() helper to simplify using prefixed classes. It
- * behaves as dom.cls(), but prefixes the class names with the generated className of the main
+ * The resulting styled component provides a `.cls()` helper to simplify using prefixed classes. It
+ * behaves as `dom.cls()`, but prefixes the class names with the generated className of the main
  * element. E.g. for the example above,
+ * ```ts
+ * myButton(myButton.cls('-small'), 'Test')
+ * ```
  *
- *      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;
- *    `);
+ * creates a button with both the `myButton` style above, and the style specified under "&-small".
  */
-
-// Use the browser globals in a way that allows replacing them with mocks in tests.
-import {G} from './browserGlobals';
-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 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<Tag extends TagName>(tag: Tag, styles: string): DomCreateFunc<TagElem<Tag>> & IClsName;
 export function styled<Args extends any[], R extends Element>(
@@ -102,8 +100,24 @@ export function styled(creator: any, styles: string): IClsName {
   });
 }
 
-// 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.
+/**
+ * Animations with `@keyframes` may be created with a unique name by using the keyframes() helper:
+ * ```ts
+ * const rotate360 = keyframes(`
+ *   from { transform: rotate(0deg); }
+ *   to { transform: rotate(360deg); }
+ * `);
+ *
+ * const Rotate = styled('div', `
+ *   display: inline-block;
+ *   animation: ${rotate360} 2s linear infinite;
+ * `);
+ * ```
+ *
+ * This function returns simply a string with the generated name. Note that keyframes do not
+ * support nesting or ampersand (&) handling, like `styled()` does, since these would be difficult
+ * and are entirely unneeded.
+ */
 export function keyframes(styles: string): string {
   return (new KeyframePiece(styles)).className;
 }

package/lib/subscribe.ts

@@ -1,23 +1,3 @@
-/**
- * subscribe.js implements subscriptions to several observables at once.
- *
- * E.g. if we have some existing observables (which may be instances of `computed`),
- * we can subscribe to them explicitly:
- *    let obs1 = observable(5), obs2 = observable(12);
- *    subscribe(obs1, obs2, (use, v1, v2) => console.log(v1, v2));
- *
- * or implicitly by using `use(obs)` function, which allows dynamic subscriptions:
- *    subscribe(use => console.log(use(obs1), use(obs2)));
- *
- * In either case, if obs1 or obs2 is changed, the callbacks will get called automatically.
- *
- * Creating a subscription allows any number of dependencies to be specified explicitly, and their
- * values will be passed to the callback(). These may be combined with automatic dependencies
- * detected using use(). Note that constructor dependencies have less overhead.
- *
- *    subscribe(...deps, ((use, ...depValues) => READ_CALLBACK));
- */
-
 import {DepItem} from './_computed_queue';
 import {IDisposableOwner} from './dispose';
 import {Listener} from './emit';
@@ -25,6 +5,7 @@ import {fromKo, IKnockoutReadObservable} from './kowrap';
 import {BaseObservable as Obs} from './observable';
 
 export interface ISubscribableObs {
+  /** @internal */
   _getDepItem(): DepItem|null;
   addListener(callback: (val: any, prev: any) => void, optContext?: object): Listener;
   get(): any;
@@ -52,6 +33,31 @@ interface IListenerWithInUse extends Listener {
 // Constant empty array, which we use to avoid allocating new read-only empty arrays.
 const emptyArray: ReadonlyArray<any> = [];
 
+/**
+ * `Subscription` allows subscribing to several observables at once. It's the foundation for a
+ * `Computed`, but may also be used directly.
+ *
+ * E.g. if we have some existing observables (which may be instances of `Computed`),
+ * we can subscribe to them explicitly:
+ * ```ts
+ * const obs1 = observable(5), obs2 = observable(12);
+ * subscribe(obs1, obs2, (use, v1, v2) => console.log(v1, v2));
+ * ```
+ *
+ * or implicitly by using `use(obs)` function, which allows dynamic subscriptions:
+ * ```ts
+ * subscribe(use => console.log(use(obs1), use(obs2)));
+ * ```
+ *
+ * In either case, if `obs1` or `obs2` is changed, the callbacks will get called automatically.
+ *
+ * Creating a subscription allows any number of dependencies to be specified explicitly, and their
+ * values will be passed to the `callback`. These may be combined with automatic dependencies
+ * detected using `use()`. Note that constructor dependencies have less overhead.
+ * ```ts
+ * subscribe(...deps, ((use, ...depValues) => READ_CALLBACK));
+ * ```
+ */
 export class Subscription {
   private readonly _depItem: DepItem;
   private readonly _dependencies: ReadonlyArray<ISubscribableObs>;
@@ -60,11 +66,9 @@ export class Subscription {
   private _callback: (use: UseCB, ...args: any[]) => void;
   private _useFunc: UseCB;
 
-  /**
-   * Internal constructor for a Subscription. You should use subscribe() function instead.
-   * The last owner argument is used by computed() to make itself available as the .owner property
-   * of the 'use' function that gets passed to the callback.
-   */
+  // Internal constructor for a Subscription. You should use subscribe() function instead.
+  // The last owner argument is used by computed() to make itself available as the .owner property
+  // of the 'use' function that gets passed to the callback.
   constructor(callback: (use: UseCB, ...args: any[]) => void, dependencies: ReadonlyArray<ISubscribable>, owner?: any) {
     this._depItem = new DepItem(this._evaluate, this);
     this._dependencies = dependencies.length > 0 ? dependencies : emptyArray;
@@ -90,14 +94,14 @@ export class Subscription {
 
   /**
    * For use by computed(): returns this subscription's hook into the _computed_queue.
+   * @internal
    */
   public _getDepItem(): DepItem { return this._depItem; }
 
   /**
-   * @private
    * Gets called when the callback calls `use(obs)` for an observable. It creates a
    * subscription to `obs` if one doesn't yet exist.
-   * @param {Observable} obs: The observable being used as a dependency.
+   * @param obs - The observable being used as a dependency.
    */
   private _useDependency(_obs: ISubscribable) {
     const obs = ('_getDepItem' in _obs) ? _obs : fromKo(_obs);
@@ -112,7 +116,6 @@ export class Subscription {
   }
 
   /**
-   * @private
    * Calls the callback() with appropriate args, and updates subscriptions when it is done.
    * I.e. adds dynamic subscriptions created via `use(obs)`, and disposes those no longer used.
    */
@@ -140,10 +143,9 @@ export class Subscription {
   }
 
   /**
-   * @private
    * Subscribes this computed to another observable that it depends on.
-   * @param {Observable} obs: The observable to subscribe to.
-   * @returns {Listener} Listener object.
+   * @param obs - The observable to subscribe to.
+   * @returns Listener object.
    */
   private _subscribeTo(_obs: ISubscribable) {
     const obs = ('_getDepItem' in _obs) ? _obs : fromKo(_obs);
@@ -151,7 +153,6 @@ export class Subscription {
   }
 
   /**
-   * @private
    * Adds this item to the recompute queue.
    */
   private _enqueue() {
@@ -160,9 +161,14 @@ export class Subscription {
 }
 
 /**
- * This is the type-checking interface for subscribe(), which allows TypeScript to do helpful
- * type-checking when using it. We can only support a fixed number of argumnets (explicit
- * dependencies), but 5 should almost always be enough.
+ * Creates a new Subscription.
+ * @param observables - The initial params, of which there may be zero or more, are
+ *    observables on which this computed depends. When any of them change, the `callback`
+ *    will be called with the values of these observables as arguments.
+ * @param callback - will be called with arguments `(use, ...values)`, i.e. the
+ *    `use` function and values for all of the `...observables` that precede this argument.
+ *    This callback is called immediately, and whenever any dependency changes.
+ * @returns The new `Subscription` which may be disposed to unsubscribe.
  */
 export function subscribe(cb: (use: UseCB) => void): Subscription;
 
@@ -186,16 +192,6 @@ export function subscribe<A, B, C, D, E>(
     a: Obs<A>, b: Obs<B>, c: Obs<C>, d: Obs<D>, e: Obs<E>,
     cb: (use: UseCB, a: A, b: B, c: C, d: D, e: E) => void): Subscription;
 
-/**
- * Creates a new Subscription.
- * @param {Observable} ...observables: The initial params, of which there may be zero or more, are
- *    observables on which this computed depends. When any of them change, the callback()
- *    will be called with the values of these observables as arguments.
- * @param {Function} callback: will be called with arguments (use, ...values), i.e. the
- *    `use` function and values for all of the ...observables that precede this argument.
- *    This callback is called immediately, and whenever any dependency changes.
- * @returns {Subscription} The new subscription which may be disposed to unsubscribe.
- */
 export function subscribe(...args: any[]): Subscription {
   const cb = args.pop();
   // The cast helps ensure that Observable is compatible with ISubscribable abstraction that we use.

package/lib/util.ts

@@ -1,3 +1,4 @@
+/* eslint-disable prefer-spread */
 
 /**
  * Returns f such that f() calls func(...boundArgs), i.e. optimizes `() => func(...boundArgs)`.

package/lib/widgets/input.ts

@@ -19,13 +19,15 @@ export interface IInputOptions {
  * number, tel.
  *
  * Note that every change to the observable will affect the input element, but not every change to
- * the input element will affect the observable. Specifically, unless {onInput: true} is set, the
+ * the input element will affect the observable. Specifically, unless `{onInput: true}` is set, the
  * visible content may differ from the observable until the element loses focus or Enter is hit.
  *
  * Example usage:
+ * ```
  *    input(obs, {}, {type: 'text', placeholder: 'Your name...'});
  *    input(obs, {isValid: isValidObs}, {type: 'email', placeholder: 'Your email...'});
  *    input(obs, {onInput: true}, {type: 'text'});
+ * ```
  */
 export function input(
   obs: Observable<string>, options: IInputOptions, ...args: IDomArgs<HTMLInputElement>

package/lib/widgets/select.ts

@@ -24,7 +24,7 @@ function getOptionValue<T>(option: IOption<T>): T {
 /**
  * Creates a select dropdown widget. The observable `obs` reflects the value of the selected
  * option, and `optionArray` is an array (regular or observable) of option values and labels.
- * These may be either strings, or {label, value, disabled} objects.
+ * These may be either strings, or `{label, value, disabled}` objects.
  *
  * The type of value may be any type at all; it is opaque to this widget.
  *
@@ -32,6 +32,7 @@ function getOptionValue<T>(option: IOption<T>): T {
  * label that the select box will show, blank by default.
  *
  * Usage:
+ * ```
  *    const fruit = observable("apple");
  *    select(fruit, ["apple", "banana", "mango"]);
  *
@@ -42,6 +43,7 @@ function getOptionValue<T>(option: IOption<T>): T {
  *      {value: 21, label: "Eve"},
  *    ]);
  *    select(employee, employees, {defLabel: "Select employee:"});
+ * ```
  */
 export function select<T>(obs: Observable<T>, optionArray: MaybeObsArray<IOption<T>>,
                           options: {defLabel?: string} = {}) {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "grainjs",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "JS library from Grist Labs",
   "main": "dist/cjs/index",
   "module": "dist/esm/index",
-  "types": "dist/cjs/index",
+  "types": "dist/cjs/index.d.ts",
   "scripts": {
     "build": "bash build.sh",
     "watch": "tsc -w",
@@ -16,8 +16,12 @@
     "test-browser-headless": "MOCHA_WEBDRIVER_ARGS='--no-sandbox --disable-gpu' MOCHA_WEBDRIVER_HEADLESS=1 mocha 'test/browser/*.{js,ts}'",
     "test-browser": "mocha 'test/browser/*.{js,ts}'",
     "test-browser-debug": "mocha --bail --no-exit 'test/browser/*.{js,ts}'",
-    "test-types": "dtslint --onlyTestTsNext --expectOnly test/types",
-    "prepack": "npm run build && npm test"
+    "test-types": "tsd --files 'test/types/**/*.ts'",
+    "prepack": "npm run build && npm test",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:build-api": "tsc -p tsconfig/tsconfig.es2015.cjs.json && api-extractor run --local --verbose && node scripts/generate-api-md.js",
+    "docs:preview": "vitepress preview docs"
   },
   "keywords": [
     "grist",
@@ -44,6 +48,11 @@
   },
   "homepage": "https://github.com/gristlabs/grainjs#readme",
   "nyc": {
+    "reporter": [
+      "html",
+      "text",
+      "lcov"
+    ],
     "extension": [
       ".ts"
     ],
@@ -55,41 +64,42 @@
     "owner": "gristlabs",
     "repo": "grainjs"
   },
-  "dependencies": {},
   "devDependencies": {
-    "@types/chai": "^4.1.2",
-    "@types/chai-as-promised": "^7.1.0",
-    "@types/jsdom": "^12.2.0",
-    "@types/lodash": "^4.14.100",
-    "@types/mocha": "^5.2.5",
-    "@types/node": "^11.13.8",
-    "@types/selenium-webdriver": "^4.0.0",
-    "@types/sinon": "^7.0.11",
-    "@types/webpack-dev-server": "^3.1.5",
-    "browserify": "^16.2.3",
-    "chai": "^4.1.0",
-    "chai-as-promised": "^7.1.1",
-    "chromedriver": "^74.0.0",
-    "create-react-app": "^3.0.0",
-    "dtslint": "^0.7.1",
-    "fastpriorityqueue": "^0.6.1",
-    "geckodriver": "^1.11.0",
-    "jsdom": "15.0.0",
-    "knockout": "^3.5.0",
-    "lodash": "^4.17.15",
-    "mocha": "^6.1.4",
-    "mocha-webdriver": "^0.1.13",
-    "nyc": "^14.0.0",
-    "selenium-webdriver": "^4.0.0-alpha.1",
-    "sinon": "^7.1.0",
-    "ts-loader": "^5.2.2",
-    "ts-node": "^8.1.0",
-    "tslint": "^5.11.0",
-    "typescript": "~3.4.5",
-    "typescript-tslint-plugin": "^0.3.1",
+    "@microsoft/api-extractor": "^7.55.1",
+    "@types/chai": "^4.2.18",
+    "@types/chai-as-promised": "^7.1.4",
+    "@types/jsdom": "^16.2.11",
+    "@types/lodash": "^4.14.170",
+    "@types/mocha": "^8.2.2",
+    "@types/node": "^22",
+    "@types/selenium-webdriver": "^4.0.13",
+    "@types/sinon": "^21.0.0",
+    "chai": "^6.2.1",
+    "chai-as-promised": "^8.0.2",
+    "esbuild": "^0.27.2",
+    "eslint": "^9.39.2",
+    "fastpriorityqueue": "^0.7.5",
+    "jsdom": "27.3.0",
+    "knockout": "^3.5.1",
+    "lodash": "^4.17.21",
+    "markdown-it-multimd-table": "^4.2.3",
+    "mocha": "^11.7.5",
+    "mocha-webdriver": "^0.3.4",
+    "nyc": "^17.1.0",
+    "selenium-webdriver": "^4.38.0",
+    "sinon": "^21.0.0",
+    "ts-loader": "^9.2.3",
+    "ts-node": "^10.9.2",
+    "tsd": "^0.27.0",
+    "typescript": "^4",
+    "typescript-eslint": "^8.50.0",
+    "typescript-tslint-plugin": "^1.0.1",
     "uglify-es": "^3.2.0",
-    "webpack": "^4.15.1",
-    "webpack-cli": "^3.0.8",
-    "webpack-dev-server": "^3.3.1"
+    "vitepress": "^1.6.4",
+    "webpack": "^5.104.0",
+    "webpack-dev-server": "^5.2.2"
+  },
+  "overrides": {
+    "esbuild": "^0.27.2"
   }
 }