@xlfont/load 1.0.12 → 2.0.0

package/README.md

@@ -15,7 +15,7 @@ This is a javascript project based on nodeJS / npm. After installing node / npm,
     npm install --save @xlfont/load
 
 
-## xl-font subsetting generator
+## xlfont subsetting generator
 
 use `npx xfl` to subset fonts with `xfl`:
 
@@ -54,45 +54,80 @@ Generally speaking, the steps of font subsetting by `xfl` are as following:
  - dump unicode / subset mapping to `charmap.txt`. also keep the original font as `all.ttf`.
 
 
-## xl-font subset loader
+## xlfont subset loader
 
 include the locally installed dist files or from cdn:
 
-    <script src="path-to/xfl.js"></script>
+    <script src="path-to/xfl-js"></script>
 
 
 Then, load desired font:
 
-    xfl.load("path-to-subset-font-folder").then(function(font) {
+    xfl.load({path: "path-to-subset-font-folder"}).then(function(font) {
         ...
     });
 
 Sync font based on given text:
 
-    xfl.load("path-to-subset-font-folder").then(function(font) {
+    xfl.load({path: "path-to-subset-font-folder"}).then(function(font) {
         font.sync("含有這些字的字型子集會被載入。Subset containgin glyphs from these chars will be loaded.");
     });
 
 
+## xfl API
 
-Font object API:
+ - `load(opt)`: load specified font. cache used fonts to save bandwidth and memory.
+   - `opt` can either be:
+     - a string to the specified font, or object as option
+     - an object passed directly to `xlfont` constructor.
+   - return a promise resolving to a `xlfont` object.
+ - `update()`: refresh necessary CSS in document to reflect font status changes.
+
+
+## xlfont Constructor
+
+Besides loading from `xfl.load`, you can also manually construct a `xlfont` object. `xlfont` is the interface to accessing specific font ( including normal font or subsetted xlfont ), with constructor options as below:
+
+ - `path`: path to font.
+ - `ext`: optional. font file extension ( `ttf`, `woff`, etc )
+   - if omitted, calculated from `path`.
+   - if not available ( either in `ext` or `path` ), default to `woff` and consider this font as a xlfont.
+ - `name`: font name. if omitted, use normalized `path` as font name.
+ - `isXl`: true if this is a xlfont. if omitted, decided by `ext`. 
+ - `doMerge`: should subsetted merged by frontend JS before using to enhacen UX. default false
+ - `useWorker`: use web worker for font merging. default false. When specified, can be an object with following:
+   - `opentype-url`: required `opentype.js` url.
+      - context of worker is in Object URL, so relative URL is not support.
+      - use `document.location` to prevent from hardcoding domain.
+ - `style`: font style ( e.g., `normal`, `italic` ). default `normal`.
+ - `weight`: font weight ( e.g., `400`, `500`, etc ). default `400`.
+
+
+## xlfont Object API
 
  - `init()`: init this font object. `xfl.load` will do this job for you.
  - `sync(text)`: load fonts based on given text.
- - `getotf()`: return `opentype.Font` from `opentype.js`.
+ - `getotf()`: return a promise, resolved to `opentype.Font` from `opentype.js`.
    - `opentype.js` is required for this method
    - `fetchAll()` will be called by this method.
+ - `getPath(opt)`: return a promise resolving to opentype.js' `Path` object based on opt with following fields:
+   - `text`: text to render. default ''
+   - `x`: x offset of the rendered text. default 0
+   - `y`: y offset of the rendered text. default 0
+   - `fontSize`: size of the rendered text. default 48
+ - `hasChar(c)`: return if code point of the given character `c` is available in this font.
+   - return true / false: available or not available
+   - return undefined: not sure before synced
  - `fetchAll()`: by default `xfl` use CSS to load fonts. `fecthAll()` fetch all subset fonts with JS again.
  - `name`: font name which can be used in CSS `font-family` property.
  - `className`: a CSS class name which its `font-family` is assigned to this font.
 
 
-## availabel xl-fonts
+## availabel xlfonts
 
-While this is a tool for composing and using xl-font, we also prepare a set of xl-fonts so you can use them directly with `xfl.js`. All fonts are released under `SIL-Open Font License 1.1` or similar open licenses. Checkout the following repo for more information:
-
-    https://github.com/xlfont/cjk/
+While this is a tool for composing and using xlfont, we also prepare a set of xlfonts so you can use them directly with `xfl.js`. All fonts are released under `SIL-Open Font License 1.1` or similar open licenses. Checkout repo list of the Github organization of `@xlfont` for more information:
 
+    https://github.com/xlfont/
 
 
 ## Todo
@@ -115,9 +150,10 @@ While this is a tool for composing and using xl-font, we also prepare a set of x
    - parsed from content of `https://www.ling.upenn.edu/courses/Spring_2003/ling538/UnicodeRanges.html`
    - content of the above link is from `http://www.unicode.org/charts/`
 
+
 ## Font Subsetting Consideration
 
-According to *[SIL's OFL FAQ](https://scripts.sil.org/cms/scripts/page.php?item_id=OFL-FAQ_web#b4b7db21)* and *[Web Fonts and Reserved Font Names](https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL_web_fonts_and_RFNs#33301a9c)*, Subsetting a font is considered *modification* of that font. This is permitted by *Open Font License (OFL)*, but OFL requires that modified versions must not use RFNs (Reserved Font Names) without separate permission.
+According to [*SIL's OFL FAQ*](https://scripts.sil.org/cms/scripts/page.php?item_id=OFL-FAQ_web#b4b7db21) and [*Web Fonts and Reserved Font Names*](https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL_web_fonts_and_RFNs#33301a9c), Subsetting a font is considered *modification* of that font. This is permitted by *Open Font License (OFL)*, but OFL requires that modified versions must not use RFNs (Reserved Font Names) without separate permission.
 
 However, once FE (Functional Equivalence) is preserved, then it's very likely that the original author would feel that the optimized font is a good and reasonable equivalent, and that the main purposes of the RFN mechanism - avoids collisions, protects authors. minimizes support, encourages derivatives - continue to be met.
 

package/bin/build.js

@@ -7,7 +7,7 @@
   opentype = require('@plotdb/opentype.js');
   yargs = require('yargs');
   path = require('path');
-  colors = require('colors');
+  colors = require('@plotdb/colors');
   progress = require('progress');
   ttf2woff2 = require('ttf2woff2');
   ttf2woff = require('ttf2woff');

package/bin/meta.js

@@ -3,7 +3,7 @@
   var fs, path, colors, yargs, opentype, lib, allRanges, argv, file, all, multiline;
   fs = require('fs');
   path = require('path');
-  colors = require('colors');
+  colors = require('@plotdb/colors');
   yargs = require('yargs');
   opentype = require('@plotdb/opentype.js');
   lib = path.dirname(fs.realpathSync(__filename));