@mark1russell7/visuals 0.3.4 → 0.3.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -13,7 +13,7 @@ The package has eight entries and two style sheets:
13
13
  - The file `/scrubber.css` is the style sheet of the scrubber.
14
14
  - The entry `/labels` has the labels of a stage: a short text next to a point, as an element of the page. It needs a browser.
15
15
  - The file `/labels.css` is the style sheet of the labels.
16
- - The entry `/graph` has the camera of a flat picture, for example a graph of boxes and edges. It does not need `three`.
16
+ - The entry `/graph` has the stage of a flat picture, for example a graph of boxes and edges. It does not need `three`.
17
17
 
18
18
  ## Install
19
19
 
@@ -474,7 +474,81 @@ stage?.refresh();
474
474
  ## A flat picture
475
475
 
476
476
  The entry `/graph` is for a flat picture that a person moves and zooms, for example a graph of boxes and edges.
477
- This version has the maths of its camera, its pointers and its keys. Each function is pure, so a test in Node.js uses it.
477
+ It has a stage on a canvas, and the content for a picture of a layout.
478
+ It has the maths of its camera, its pointers and its keys too. It imports no `three`.
479
+
480
+ ```ts
481
+ import { aimRects, createPictureStage, type PictureContent } from "@mark1russell7/visuals/graph";
482
+
483
+ interface Box {
484
+ readonly id: string;
485
+ readonly x: number;
486
+ readonly y: number;
487
+ readonly w: number;
488
+ readonly h: number;
489
+ }
490
+
491
+ const first: Box = { id: "a", x: 0, y: 0, w: 160, h: 60 };
492
+ const boxes: readonly Box[] = [first, { id: "b", x: 240, y: 120, w: 160, h: 60 }];
493
+
494
+ // A content draws in CSS pixels. The view of the frame has the zoom and the position of the picture.
495
+ const content: PictureContent<Box, { readonly box: string; readonly selected: string }> = {
496
+ bounds: { x: 0, y: 0, w: 400, h: 180 },
497
+ has: (record) => boxes.some((box) => box.id === record),
498
+ pick: ({ point }) => {
499
+ const box = boxes.find((b) => point.x >= b.x && point.x <= b.x + b.w && point.y >= b.y && point.y <= b.y + b.h);
500
+ return box === undefined ? undefined : { record: box.id, value: box };
501
+ },
502
+ draw(context, { view }, theme, highlight) {
503
+ context.translate(view.x, view.y);
504
+ context.scale(view.k, view.k);
505
+ for (const box of boxes) {
506
+ context.fillStyle = highlight(box.id) === 0 ? theme.box : theme.selected;
507
+ context.fillRect(box.x, box.y, box.w, box.h);
508
+ }
509
+ return false;
510
+ },
511
+ };
512
+
513
+ const stage = createPictureStage(document.body, {
514
+ content,
515
+ theme: { box: "#c8d0d8", selected: "#2f6fd0" },
516
+ label: "Two boxes",
517
+ views: { first: aimRects([first], { least: 0.6 }) },
518
+ keys: { f: "first" },
519
+ onSelect: (box) => console.log(box?.id),
520
+ });
521
+ stage?.setView("first");
522
+ ```
523
+
524
+ The stage fills its container, so give the container a size. `createPictureStage` gives `undefined` when the browser gives no 2D context.
525
+
526
+ - A drag moves the picture. The wheel, two fingers and a double click change the zoom at the pointer.
527
+ - A click selects the record below the pointer, and `onSelect` gets its value. `onHover` gets the record below a mouse or a pen.
528
+ - The wheel moves the page until a person uses the picture. Set `wheel` to `always` for a picture that fills the page.
529
+ - A view is an aim: a function that gives the view for a picture and a screen.
530
+ - `aimAll` shows all of the picture, and `aimRects` shows a group of boxes. `aimReveal` moves the camera only for a selection that is out of view.
531
+ - The stage asks the aim again after a change of the size, until a person moves the picture.
532
+ - A part of the picture stays in view: `keepRect` keeps 64 pixels of it in the free area.
533
+ - A very large picture gets a smaller least zoom from `zoomLimitsFor`, so a person can show all of it.
534
+ - `setInsets` tells the stage which parts of the picture the page covers. Each view uses the free area.
535
+ - `stackPictureContents` makes one content from layers, for example boxes below routes below labels.
536
+ - The stage makes a picture only after a change. A content that continues to change gives true from `draw`.
537
+ - A person who asks for less motion gets each view immediately.
538
+
539
+ | Function of the stage | What it does |
540
+ | --- | --- |
541
+ | `setContent` | It shows a different content, and disposes the old content. |
542
+ | `setTheme` | It changes the colors. |
543
+ | `setView` | It moves the camera to a view: a name of the options, or an aim. |
544
+ | `setInsets` | It sets the parts of the picture that the page covers. |
545
+ | `zoomBy` | It changes the zoom by a factor at the middle of the free area, for the buttons of a page. |
546
+ | `view`, `area` | They give the view of the camera, and the free area. |
547
+ | `highlight`, `select` | They highlight records by their names, and select one record. |
548
+ | `refresh` | It makes a new picture after a change of the content. |
549
+ | `dispose` | It removes the canvas, and disposes the content. |
550
+
551
+ The maths of the camera are pure functions, so a test in Node.js uses them:
478
552
 
479
553
  ```ts
480
554
  import { fitRect, freeArea, toPicture, viewBetween, zoomView } from "@mark1russell7/visuals/graph";
@@ -499,6 +573,10 @@ A view has the zoom `k` and the screen position of the origin of the picture. A
499
573
  | `pinchView` | The view after the two pointers of a pinch move. Each pointer keeps its point of the picture. |
500
574
  | `freeArea` | The part of a picture that the page does not cover. A camera shows a selection there. |
501
575
  | `fitRect` | The view that shows a rectangle in an area, as large as the area permits. |
576
+ | `zoomLimitsFor` | The limits of the zoom for a picture, with a least zoom that shows all of it. |
577
+ | `keepRect` | The view that keeps a part of a rectangle in an area, so a person cannot lose the picture. |
578
+ | `aimAll`, `aimRects`, `aimReveal` | The aims of a stage: all of the picture, a group of boxes, and a selection. |
579
+ | `stackPictureContents` | One content from a list of contents. The last content is on top. |
502
580
  | `frameRects` | The view for the first rectangle of a list that the area shows at a least zoom or more. |
503
581
  | `showsRect` | True when a view shows all of a rectangle in an area. |
504
582
  | `revealRects` | The view that shows a selection. It is the view of the camera when the selection is in view, so the camera stays. |
@@ -538,6 +616,90 @@ canvas.addEventListener("pointerup", (event) => {
538
616
  - `frameRects` gets the bounds of groups of boxes, the largest group first. It takes the first group that a person can read.
539
617
  - The zoom stays in `ZOOM_LIMITS`. Each function with a zoom takes different limits as a parameter.
540
618
 
619
+ ## The picture of a layout
620
+
621
+ `createPictureContent` makes the content of a flat stage from a picture of `@mark1russell7/layout-contract`: its boxes, its routes and its labels.
622
+ A layout engine gives the picture. The content draws the picture, and it does not change it.
623
+
624
+ ```ts
625
+ import { PICTURE_SCHEMA, pathOf, type LayoutPicture } from "@mark1russell7/layout-contract";
626
+ import { LIGHT_PICTURE_THEME, createPictureContent, createPictureStage, plainLooks } from "@mark1russell7/visuals/graph";
627
+
628
+ const picture: LayoutPicture = {
629
+ schema: PICTURE_SCHEMA,
630
+ boxes: [
631
+ { id: "card", x: 0, y: 0, w: 200, h: 100 },
632
+ { id: "row", parent: "card", x: 10, y: 30, w: 180, h: 25 },
633
+ { id: "topic", x: 300, y: 20, w: 60, h: 60, shape: { kind: "circle", cx: 30, cy: 30, r: 30 } },
634
+ ],
635
+ routes: [
636
+ {
637
+ id: "link",
638
+ source: "row",
639
+ target: "topic",
640
+ path: pathOf([
641
+ { x: 190, y: 42 },
642
+ { x: 300, y: 50 },
643
+ ]),
644
+ },
645
+ ],
646
+ labels: [{ id: "name", box: "card", x: 10, y: 6, w: 100, h: 18, lines: ["Card"], lineHeight: 18, font: "13px sans-serif" }],
647
+ };
648
+
649
+ const content = createPictureContent(picture, { looks: plainLooks({ end: { shape: "arrow", size: 8 } }) });
650
+ const stage = createPictureStage(document.body, {
651
+ content,
652
+ theme: LIGHT_PICTURE_THEME,
653
+ label: "A card and a topic",
654
+ onSelect: (record) => console.log(record?.id),
655
+ });
656
+
657
+ // A new layout gives a new picture. The stage shows it after a refresh.
658
+ content.setPicture({ ...picture, routes: [] });
659
+ stage?.refresh();
660
+ ```
661
+
662
+ - The looks give the colors, the lines and the signs of each record. `plainLooks` gives the looks of a plain picture.
663
+ - `LIGHT_PICTURE_THEME` and `DARK_PICTURE_THEME` are the themes of the plain looks.
664
+ - A look gets the state of its record: its highlight, its focus level, the zoom, and if the box has children.
665
+ - A look of `undefined` hides a record. A hidden box takes its labels with it, and a person cannot point at it.
666
+ - A box is a rectangle with round corners, a circle, an ellipse or a polygon. Its look can add a ring off its border, and small signs.
667
+ - A route is a path of lines, curves and arcs. Its look can add an arrow or a dot at each end.
668
+ - A label has the lines and the place that the layout gives. The content breaks no line.
669
+ - In `plainLooks`, a text that is too small to read becomes bars. A text below `SMALLEST_BAR_LINE` pixels goes.
670
+ - At the zoom 1 or less, the lines and the signs keep their size on the screen. Above it, they grow with the boxes.
671
+ - The selected record and the records at it stay clear. Each other record has less color, and the colors change in a short time.
672
+ - `setFocus` sets the records of the focus from the page. The option `focus: "none"` stops the focus of the selection.
673
+ - A person points at the top box below the pointer. A box with no child comes before the box around it.
674
+ - The option `picks` tells which records a person can point at, for example the routes too.
675
+ - The content makes shapes only for the records in view.
676
+ - `setPicture` shows a different picture. Start `refresh` of the stage after it.
677
+
678
+ The parts of the content are pure functions. A test in Node.js examines a picture with no canvas:
679
+
680
+ ```ts
681
+ import { LIGHT_PICTURE_THEME, focusOf, indexPicture, paintPicture, pickRecord, plainLooks } from "@mark1russell7/visuals/graph";
682
+
683
+ const index = indexPicture(picture);
684
+ pickRecord(index, { x: 50, y: 40 })?.id; // => "row"
685
+
686
+ // The focus of the row has the row, its card, the link and the topic.
687
+ const focus = focusOf(index, ["row"]);
688
+ const shapes = paintPicture(index, plainLooks(), LIGHT_PICTURE_THEME, { zoom: 1, highlight: () => 0, focus });
689
+ shapes.length; // => 5: the card, its name, the link, the row and the topic
690
+ ```
691
+
692
+ | Function | What it gives |
693
+ | --- | --- |
694
+ | `indexPicture` | The tables of a picture: each record by its id, the children of each box, and the routes and the labels of each record. |
695
+ | `focusOf`, `boxFocus`, `routeFocus` | The focus of a list of records, and the focus level of a box or a route. `FOCUS_OPACITY` has the color share of each level. |
696
+ | `pickRecord`, `boxDistance` | The record at a point of the picture, and the distance from a point to the shape of a box. |
697
+ | `routeLine` | The path of a route as a line of points, with its bounds. |
698
+ | `plainLooks`, `lookUnit` | The looks of a plain picture, and the size of one unit of a look at a zoom. |
699
+ | `paintPicture` | The paint list of a picture: its shapes as plain data, in the order of the paint. |
700
+ | `drawShapes` | The drawing of a paint list on a 2D context, in the view of a camera. |
701
+ | `recordKey`, `boxState`, `routeState` | The key of a record for the function `fade` of a paint, and the state of a record for its look. |
702
+
541
703
  ## The camera maths
542
704
 
543
705
  The entry `.` has pure functions. A page with no WebGL 2 and a test in Node.js use the same functions as the stage.
package/build/globe.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { r as StageContent } from "./stage-DmFfah2e.js";
2
- import { C as ViewAngles, d as StageView, t as StageTheme } from "./theme-3EGbXXoP.js";
1
+ import { r as StageContent } from "./stage-D8JVM6wZ.js";
2
+ import { _ as ViewAngles, a as StageView, t as StageTheme } from "./theme-DBbBlCbC.js";
3
3
  import { Raycaster } from "three";
4
4
  import { LatLon, Region } from "@mark1russell7/geo";
5
5
  import { Point3 } from "@mark1russell7/layout-contract";