@edubeam/plot 0.0.0-stage → 0.2.0
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/CHANGELOG.md +88 -0
- package/LICENSE +674 -0
- package/README.md +386 -2
- package/dist/components/DiagramStack.vue.d.ts +18 -0
- package/dist/components/StructurePlot.vue.d.ts +18 -0
- package/dist/components/texts.d.ts +24 -0
- package/dist/components/theme.d.ts +16 -0
- package/dist/components/types.d.ts +117 -0
- package/dist/core/fromSolver.d.ts +12 -0
- package/dist/core/layout.d.ts +23 -0
- package/dist/core/model.d.ts +135 -0
- package/dist/core/polynomial.d.ts +72 -0
- package/dist/core/readout.d.ts +48 -0
- package/dist/core/scene.d.ts +248 -0
- package/dist/core/stack.d.ts +56 -0
- package/dist/core/structure.d.ts +86 -0
- package/dist/core/supports.d.ts +50 -0
- package/dist/core/svg.d.ts +50 -0
- package/dist/core/units.d.ts +30 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.js +3257 -0
- package/dist/index.js.map +1 -0
- package/dist/plugin.d.ts +6 -0
- package/package.json +90 -4
package/README.md
CHANGED
|
@@ -1,3 +1,387 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @edubeam/plot
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Vue 3 components that draw plane structures and their analysis results as SVG: members, supports, loads, reactions,
|
|
4
|
+
the normal force, shear force and bending moment diagrams, and the deformed shape. The structure is solved by
|
|
5
|
+
[@edubeam/fem](https://github.com/EduBeamApp/fem), the finite element solver behind [EduBeam](https://www.edubeam.app).
|
|
6
|
+
|
|
7
|
+
Documentation and live examples: <https://www.edubeam.app/plot>
|
|
8
|
+
|
|
9
|
+
<!-- TODO: add screenshots once they have a public URL to load from. -->
|
|
10
|
+
|
|
11
|
+
- **`StructurePlot`** draws any plane frame, beam or truss, fitted to the width of its box. A compact mode makes
|
|
12
|
+
readable thumbnails, and independent layers let a figure build up step by step without moving.
|
|
13
|
+
- **`DiagramStack`** draws the stacked textbook figure: a beam with its loads, and its V(x), M(x) and w(x) diagrams
|
|
14
|
+
beneath it on one x axis. It has a reading cursor and an optional point load the reader can drag.
|
|
15
|
+
- **Exact results.** Each member's internal forces and deflection are stored as the polynomials they are, split at
|
|
16
|
+
point loads. Steps are drawn as true verticals, extremes are found exactly, and curves are drawn as exact Béziers.
|
|
17
|
+
- **Real pixel sizes.** Text, symbols and line weights stay the same size whatever the size of the model, so a plot
|
|
18
|
+
stays legible on a phone.
|
|
19
|
+
- **Standalone.** It needs only Vue and @edubeam/fem, with no UI framework, store or i18n library. Colours come from CSS
|
|
20
|
+
custom properties, so it follows the page's light and dark themes.
|
|
21
|
+
|
|
22
|
+
## Install
|
|
23
|
+
|
|
24
|
+
`vue` (3.5 or later) and `@edubeam/fem`, the solver, are peer dependencies:
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
npm install @edubeam/plot @edubeam/fem vue
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The package is ESM only and ships its own TypeScript types. It needs no stylesheet import: the few CSS rules a plot
|
|
31
|
+
uses are inlined into each SVG.
|
|
32
|
+
|
|
33
|
+
## Quick start
|
|
34
|
+
|
|
35
|
+
Build and solve a model with @edubeam/fem (SI units throughout: m, N, Pa), then hand the solver to a component:
|
|
36
|
+
|
|
37
|
+
```vue
|
|
38
|
+
<script setup lang="ts">
|
|
39
|
+
import { markRaw } from 'vue';
|
|
40
|
+
import { DofID, LinearStaticSolver } from '@edubeam/fem';
|
|
41
|
+
import { DiagramStack, StructurePlot } from '@edubeam/plot';
|
|
42
|
+
|
|
43
|
+
// A 6 m simply supported beam under 12 kN/m
|
|
44
|
+
const solver = new LinearStaticSolver();
|
|
45
|
+
solver.domain.createMaterial(1, { e: 210e9, g: 81e9, alpha: 12e-6, d: 7850 });
|
|
46
|
+
solver.domain.createCrossSection(1, { a: 28.5e-4, iy: 1943e-8, h: 0.2, k: 1 });
|
|
47
|
+
solver.domain.createNode(1, [0, 0, 0], [DofID.Dx, DofID.Dz]); // pin
|
|
48
|
+
solver.domain.createNode(2, [6, 0, 0], [DofID.Dz]); // roller
|
|
49
|
+
solver.domain.createBeam2D(1, [1, 2], 1, 1);
|
|
50
|
+
solver.loadCases[0].createBeamElementUniformEdgeLoad(1, [0, 12e3], true); // 12 kN/m, downward
|
|
51
|
+
solver.solve();
|
|
52
|
+
|
|
53
|
+
// The solver is read, never watched: markRaw keeps Vue from making it deeply reactive.
|
|
54
|
+
const beam = markRaw(solver);
|
|
55
|
+
</script>
|
|
56
|
+
|
|
57
|
+
<template>
|
|
58
|
+
<StructurePlot :solver="beam" :layers="['members', 'supports', 'loads', 'reactions', 'M']" />
|
|
59
|
+
<DiagramStack :solver="beam" />
|
|
60
|
+
</template>
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The plot shows the 36 kN reactions and the 54 kNm moment at mid-span, hanging below the beam on the tension side.
|
|
64
|
+
|
|
65
|
+
The model follows the solver's axes: x to the right, z down. A downward load is a positive `fz`, and a sagging moment is
|
|
66
|
+
positive. After changing a solver in place, pass a new one or bump the `revision` prop to redraw.
|
|
67
|
+
|
|
68
|
+
## StructurePlot
|
|
69
|
+
|
|
70
|
+
```vue
|
|
71
|
+
<StructurePlot :solver="solver" compact :height="200" />
|
|
72
|
+
<StructurePlot :model="model" :layers="['members', 'supports', 'N']" result-label-mode="axis" />
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
The plot measures its container with a `ResizeObserver` and lays out at that width, in real pixels. Without a fixed
|
|
76
|
+
`height`, the height follows the drawing, up to `maxHeight`.
|
|
77
|
+
|
|
78
|
+
### Props
|
|
79
|
+
|
|
80
|
+
| Prop | Type | Default | Description |
|
|
81
|
+
| --------------------- | -------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
82
|
+
| `solver` | `Solver` from `@edubeam/fem` | none | A solver. Results are drawn once its load case is solved. |
|
|
83
|
+
| `model` | `PlotModel` | none | Or the plain data `modelFromSolver` makes, for example prepared at build time. Takes precedence over `solver`. |
|
|
84
|
+
| `loadCase` | `number` | `0` | Index into `solver.loadCases`. |
|
|
85
|
+
| `revision` | `number` | `0` | Change it to redraw a solver that was changed in place. |
|
|
86
|
+
| `layers` | `PlotLayer[]` | see below | What to draw. |
|
|
87
|
+
| `reserve` | `PlotLayer[]` | `layers` | Layers to make room for. See [Layers and reserve](#layers-and-reserve). |
|
|
88
|
+
| `compact` | `boolean` | `false` | Thumbnail drawing. See [Compact mode](#compact-mode). |
|
|
89
|
+
| `resultLabelMode` | `'horizontal' \| 'axis'` | `'horizontal'` | Diagram values upright, or turned to run along their ordinate, across the member. |
|
|
90
|
+
| `reserveLabelModes` | `ResultLabelMode[]` | none | Label modes to make room for besides the current one, so switching `resultLabelMode` moves only the labels. |
|
|
91
|
+
| `momentOnTensionSide` | `boolean` | `true` | M on the tension side, as drawn in most of Europe. `false` draws it on the compression side. |
|
|
92
|
+
| `units` | `Partial<Units>` | kN, kNm, kN/m, m, mm, mrad, K | Display units. See [Units and number formats](#units-and-number-formats). |
|
|
93
|
+
| `numberFormat` | `Intl.NumberFormat` | English, at most one decimal | Formats every number. |
|
|
94
|
+
| `colors` | `Partial<PlotColors>` | none | Colour overrides. See [Theming](#theming). |
|
|
95
|
+
| `width` | `number` | `640`, compact `400` | Width in px before the box is measured, used when rendering on the server. |
|
|
96
|
+
| `height` | `number` | none | Fixed height in px. |
|
|
97
|
+
| `maxHeight` | `number` | `max(320, 0.75 × width)`, compact none | Upper bound for the automatic height. |
|
|
98
|
+
| `padding` | `number` | `6` | Space around the drawing, px. |
|
|
99
|
+
| `fontSize` | `number` | `13`, compact `11.5` | Text size, px. |
|
|
100
|
+
| `diagramSize` | `number` | `48`, compact `26` | Length of the largest diagram ordinate, px. |
|
|
101
|
+
| `deformedSize` | `number` | `30`, compact `18` | Largest displacement on the deformed shape, px. |
|
|
102
|
+
| `diagramScale` | `Partial<Record<ResultLayer, number>>` | none | Fixed px per SI unit for a result, to draw several plots at one scale. Overrides `diagramSize` or `deformedSize` for that result. |
|
|
103
|
+
| `animate` | `boolean` | `true` | Fade layers in and draw members from end to end when they appear. Always off under `prefers-reduced-motion`. |
|
|
104
|
+
| `hover` | `boolean` | `false` | Read values off the member under the pointer. See [Reading values](#reading-values). |
|
|
105
|
+
| `title` | `string` | a description of what is shown | Accessible name of the figure. |
|
|
106
|
+
|
|
107
|
+
### Layers and reserve
|
|
108
|
+
|
|
109
|
+
A layer is one of `nodes`, `nodeLabels`, `dimensions`, `members`, `supports`, `loads`, `reactions`, and the results
|
|
110
|
+
`N`, `V`, `M` and `w` (the deformed shape).
|
|
111
|
+
|
|
112
|
+
Without `layers`, a plot draws members, supports, loads and reactions, plus one result chosen for the structure:
|
|
113
|
+
|
|
114
|
+
- `M` for beams and frames
|
|
115
|
+
- `N` for a truss, where every member is pinned at both ends or bending is negligible beside the axial forces
|
|
116
|
+
- `w` when nothing carries a force, as in a beam free to expand under a temperature load
|
|
117
|
+
|
|
118
|
+
The fit is computed for every layer in `reserve` as well as those in `layers`. Layers that are reserved but not shown
|
|
119
|
+
are drawn hidden. So a figure that builds up in stages keeps its layout, and each new layer fades in where it belongs:
|
|
120
|
+
|
|
121
|
+
```vue
|
|
122
|
+
<script setup lang="ts">
|
|
123
|
+
const stages: PlotLayer[][] = [
|
|
124
|
+
['nodes', 'nodeLabels', 'dimensions'],
|
|
125
|
+
['nodes', 'nodeLabels', 'members'],
|
|
126
|
+
['nodes', 'nodeLabels', 'members', 'supports', 'loads'],
|
|
127
|
+
['nodes', 'nodeLabels', 'members', 'supports', 'loads', 'reactions', 'M'],
|
|
128
|
+
];
|
|
129
|
+
const all = [...new Set(stages.flat())];
|
|
130
|
+
</script>
|
|
131
|
+
|
|
132
|
+
<template>
|
|
133
|
+
<StructurePlot :solver="frame" :layers="stages[step]" :reserve="all" />
|
|
134
|
+
</template>
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Each layer is a `<g class="ebp-layer ebp-layer-{name}">`, and gets `ebp-on` when shown. The transitions are plain CSS
|
|
138
|
+
on those classes, so a page can restyle them.
|
|
139
|
+
|
|
140
|
+
### Diagram values
|
|
141
|
+
|
|
142
|
+
Every value is written just beyond the tip of the ordinate it denotes:
|
|
143
|
+
|
|
144
|
+
- An extreme of a member's diagram is labelled.
|
|
145
|
+
- A rigid corner is labelled once, at the tip of the member with more room around it.
|
|
146
|
+
- A step, under a point load or over a support, shows both its values.
|
|
147
|
+
- A truss shows each bar's force once, along the bar, coloured by sign: tension and compression.
|
|
148
|
+
|
|
149
|
+
A label that would overlap another label, a member or an arrow tries other places at the same tip. If none is free,
|
|
150
|
+
the label is left out, and the fit never reserves room for labels that were left out. Truss bar forces are the
|
|
151
|
+
exception, because a reader cannot work out a missing one. A bar force slides along its bar, flips to the other side,
|
|
152
|
+
shrinks to 10 px and drops its unit, in that order, before it is ever left out.
|
|
153
|
+
|
|
154
|
+
With `resultLabelMode="axis"`, values are turned to run along their ordinates, as the EduBeam app draws them. Give
|
|
155
|
+
`reserveLabelModes` (for example `['horizontal', 'axis']`) when the reader can switch modes, so the drawing doesn't
|
|
156
|
+
move when they do.
|
|
157
|
+
|
|
158
|
+
### Compact mode
|
|
159
|
+
|
|
160
|
+
For thumbnails and gallery tiles of about 400 × 200 px:
|
|
161
|
+
|
|
162
|
+
- smaller symbols and 11.5 px text
|
|
163
|
+
- at most two values per member, the largest
|
|
164
|
+
- loads and reactions as arrows with their magnitudes
|
|
165
|
+
|
|
166
|
+
The default layers still apply, so a tile shows one result.
|
|
167
|
+
|
|
168
|
+
### Reading values
|
|
169
|
+
|
|
170
|
+
With `hover`, the plot shows the values of the shown results at the member point under the pointer. A pill reads, for
|
|
171
|
+
example, `M = 54 kNm`. At a step it shows both sides: `V = 13.3 → −6.7 kN`.
|
|
172
|
+
|
|
173
|
+
The `readout` event carries the same values as data: `{ member, x, px, py, values }`, where each of `values.N`, `V`,
|
|
174
|
+
`M` and `w` is `{ left, right }` in SI units. The event sends `null` when the pointer leaves.
|
|
175
|
+
|
|
176
|
+
## DiagramStack
|
|
177
|
+
|
|
178
|
+
```vue
|
|
179
|
+
<script setup lang="ts">
|
|
180
|
+
const at = ref(3.2);
|
|
181
|
+
const solver = computed(() => markRaw(solveBeamWithLoadAt(at.value)));
|
|
182
|
+
</script>
|
|
183
|
+
|
|
184
|
+
<template>
|
|
185
|
+
<DiagramStack v-model:load-at="at" :solver="solver" :ranges="envelope" />
|
|
186
|
+
</template>
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
The members must form one horizontal line, drawn left to right. Any other line is refused with an error, because the
|
|
190
|
+
figure's x axis is the beam's.
|
|
191
|
+
|
|
192
|
+
### Props
|
|
193
|
+
|
|
194
|
+
| Prop | Type | Default | Description |
|
|
195
|
+
| -------------- | ---------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
196
|
+
| `solver` | `Solver` from `@edubeam/fem` | none | The solved beam. |
|
|
197
|
+
| `model` | `PlotModel` | none | Or plain data from `modelFromSolver`. |
|
|
198
|
+
| `loadCase` | `number` | `0` | Index into `solver.loadCases`. |
|
|
199
|
+
| `revision` | `number` | `0` | Change it to redraw a solver that was changed in place. |
|
|
200
|
+
| `members` | `string[]` | all members | The members of the beam line. |
|
|
201
|
+
| `rows` | `('N' \| 'V' \| 'M' \| 'w')[]` | `['V', 'M', 'w']` | Diagram rows, top to bottom. |
|
|
202
|
+
| `loadRow` | `boolean` | `true` | The beam with its supports, loads and reactions above the rows. |
|
|
203
|
+
| `ranges` | `Partial<Record<row, [min, max]>>` | each row's own range | Value range per row, in SI units. A fixed range keeps a row's scale while a load moves. |
|
|
204
|
+
| `rowHeights` | `Partial<Record<row, number>>` | N 100, V 116, M 128, w 76 (smaller on a phone) | Row heights, px. |
|
|
205
|
+
| `maxHeight` | `number` | none | Rows shrink, to 60 % at most, so the figure fits this height. Text keeps its size. |
|
|
206
|
+
| `units` | `Partial<Units>` | kN, kNm, mm | Display units. |
|
|
207
|
+
| `numberFormat` | `Intl.NumberFormat` | English, at most one decimal | Formats every number. |
|
|
208
|
+
| `colors` | `Partial<PlotColors>` | none | Colour overrides. |
|
|
209
|
+
| `width` | `number` | `720` | Width in px before the box is measured, used when rendering on the server. |
|
|
210
|
+
| `fontSize` | `number` | `12.5` | Text size, px. |
|
|
211
|
+
| `hover` | `boolean` | `true` | The reading cursor. |
|
|
212
|
+
| `loadAt` | `number` | none | Position in metres of a point load the reader may drag. Use it with `v-model:load-at`. |
|
|
213
|
+
| `loadLabel` | `string` | `P = …` | Text beside the draggable load. |
|
|
214
|
+
| `loadStep` | `number` | `0.05` | The drag rounds to this step, in metres, and the arrow keys move by it. |
|
|
215
|
+
| `title` | `string` | a description of the rows | Accessible name of the figure. |
|
|
216
|
+
|
|
217
|
+
### The reading cursor
|
|
218
|
+
|
|
219
|
+
Moving the pointer over the rows shows a cursor across all of them, with the value of each row in a pill beside its
|
|
220
|
+
point. Within 8 px of a step (a point load, a support) the cursor snaps to it, and V shows both values, as in
|
|
221
|
+
`7.2 → −12.8 kN`. The `readout` event carries `{ x, values }`, with `{ left, right }` per row in SI units.
|
|
222
|
+
|
|
223
|
+
### A draggable load
|
|
224
|
+
|
|
225
|
+
With `v-model:load-at`, the point load at that position is drawn with a grip. Dragging anywhere on the load row moves
|
|
226
|
+
it. The component only reports the new position: re-solve the beam with the load there and pass the new solver back.
|
|
227
|
+
To keep a row's scale while the load moves, set `ranges` to the envelope over every load position. The diagrams then
|
|
228
|
+
grow and shrink as the load moves, instead of rescaling.
|
|
229
|
+
|
|
230
|
+
## Types and the plugin
|
|
231
|
+
|
|
232
|
+
The props and events of both components are exported, so a page can type its own wrappers around them:
|
|
233
|
+
`StructurePlotProps`, `StructurePlotEmits`, `DiagramStackProps`, `DiagramStackEmits` and `StackReadout`, as well as
|
|
234
|
+
`PlotLayer`, `ResultLabelMode`, `PlotModel` and the other types the props use.
|
|
235
|
+
|
|
236
|
+
```ts
|
|
237
|
+
import type { PlotLayer, StructurePlotProps } from '@edubeam/plot';
|
|
238
|
+
|
|
239
|
+
const figure: StructurePlotProps = { layers: ['members', 'supports', 'M'] satisfies PlotLayer[], compact: true };
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
To register both components globally instead of importing them where they are used:
|
|
243
|
+
|
|
244
|
+
```ts
|
|
245
|
+
import { EduBeamPlot } from '@edubeam/plot';
|
|
246
|
+
|
|
247
|
+
app.use(EduBeamPlot); // <StructurePlot> and <DiagramStack> in every template
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Named imports keep a bundle smaller: a page that imports only `StructurePlot` gets neither `DiagramStack` nor the
|
|
251
|
+
plugin, and one that imports only `modelFromSolver` gets no component code at all.
|
|
252
|
+
|
|
253
|
+
## Functions
|
|
254
|
+
|
|
255
|
+
Everything the components draw comes from pure, framework-free functions, exported for custom figures and for
|
|
256
|
+
preparing data ahead of time:
|
|
257
|
+
|
|
258
|
+
- **`modelFromSolver(solver, { loadCase })`** reads a solver into a `PlotModel`. The model holds geometry,
|
|
259
|
+
supports, loads, reactions, and each member's `N`, `V`, `M`, `u` and `w` as piecewise polynomials along the member.
|
|
260
|
+
It is plain, JSON-serialisable data, so a site can solve at build time and ship only the result.
|
|
261
|
+
- **Piecewise polynomials:** `valueAt(pw, x, 'left' | 'right')`, `slopeAt`, `extremes`, `innerBreaks`,
|
|
262
|
+
`pieceExtrema`, `pieceDegree`, `pieceToBeziers`, `fitPiece` and `maxAbs`.
|
|
263
|
+
- **Readouts:** `readMember(results, x, snap)` returns the results at a point, both sides of a step included.
|
|
264
|
+
`readoutAt(model, transform, px, py, reach)` finds the member under a screen point, and `formatReadout` writes a
|
|
265
|
+
readout as text.
|
|
266
|
+
- **Beam lines:** `beamLine(model, members?)`, `lineDiagram(model, line, row)`, `rowPeaks` and `rowRange`, for
|
|
267
|
+
building your own stacked figure.
|
|
268
|
+
- **Drawing:**
|
|
269
|
+
- `buildStructureScene(model, options)` returns the drawing as items: model points with offsets in screen pixels.
|
|
270
|
+
- `fitScene` fits them to a box.
|
|
271
|
+
- `placeLabels` and `resolveScene` turn them into SVG path data and placed labels.
|
|
272
|
+
- `supportKind` and `supportPlacement` name and orient support symbols.
|
|
273
|
+
- `defaultResultLayer` picks the result a thumbnail shows.
|
|
274
|
+
- **Units:** `formatQuantity`, `formatNumber`, `KN_UNITS`, `SI_UNITS` and `resolveUnits`.
|
|
275
|
+
|
|
276
|
+
## Theming
|
|
277
|
+
|
|
278
|
+
Colours come from CSS custom properties on the page, so a site's light and dark themes apply as they are. Where a page
|
|
279
|
+
defines none, CSS system colours stand in, which follow the page's `color-scheme`.
|
|
280
|
+
|
|
281
|
+
| Used for | Custom property | Fallback |
|
|
282
|
+
| ------------------------- | -------------------------------------------- | ------------ |
|
|
283
|
+
| Members, supports, text | `--figure-ink`, then `--ink` | `CanvasText` |
|
|
284
|
+
| Background, label halos | `--paper` | `Canvas` |
|
|
285
|
+
| Dimension lines, axes | `--muted` | `GrayText` |
|
|
286
|
+
| Nodes, the draggable load | `--brand` | `#4f46e5` |
|
|
287
|
+
| Normal force | `--color-normal` | `#2222ff` |
|
|
288
|
+
| Shear force | `--color-shear` | `#00af00` |
|
|
289
|
+
| Bending moment | `--color-moment` | `#ff2222` |
|
|
290
|
+
| Deformed shape, w | `--figure-ink`, then `--ink` | `CanvasText` |
|
|
291
|
+
| Loads | `--color-load` | `#ff8700` |
|
|
292
|
+
| Reactions | `--color-reaction` | `#a020f0` |
|
|
293
|
+
| Truss bars in tension | `--color-tension`, then `--color-moment` | `#ff2222` |
|
|
294
|
+
| Truss bars in compression | `--color-compression`, then `--color-normal` | `#2222ff` |
|
|
295
|
+
| Font | `--ebp-font`, then `--font-sans` | `inherit` |
|
|
296
|
+
|
|
297
|
+
The `colors` prop overrides any of these for one plot, by tone name: `ink`, `paper`, `muted`, `brand`, `normal`,
|
|
298
|
+
`shear`, `moment`, `deformed`, `load`, `reaction`, `tension` and `compression`.
|
|
299
|
+
|
|
300
|
+
```vue
|
|
301
|
+
<StructurePlot :solver="solver" :colors="{ moment: '#c00', paper: 'transparent' }" />
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
For dark mode, set the properties for the dark theme as usual:
|
|
305
|
+
|
|
306
|
+
```css
|
|
307
|
+
.dark {
|
|
308
|
+
--ink: #eef;
|
|
309
|
+
--paper: #0b0d1f;
|
|
310
|
+
}
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
Labels get a halo in the background colour, so they stay legible over hatching. Row names such as V(x) are set in
|
|
314
|
+
KaTeX's fonts when the page loads them, and fall back to a serif otherwise.
|
|
315
|
+
|
|
316
|
+
## Units and number formats
|
|
317
|
+
|
|
318
|
+
Values are SI everywhere inside, and are converted only for display. The default units are kN, kNm, kN/m, m, mm, mrad
|
|
319
|
+
and K. Override any of them with a symbol and a scale (display value = SI value × scale):
|
|
320
|
+
|
|
321
|
+
```vue
|
|
322
|
+
<StructurePlot
|
|
323
|
+
:solver="solver"
|
|
324
|
+
:units="{ force: { symbol: 'N', scale: 1 }, displacement: { symbol: 'm', scale: 1 } }"
|
|
325
|
+
/>
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
`SI_UNITS` and `KN_UNITS` are exported as starting points.
|
|
329
|
+
|
|
330
|
+
Numbers go through an `Intl.NumberFormat`. The default is English with at most one decimal. Pass your own to match
|
|
331
|
+
the page's language:
|
|
332
|
+
|
|
333
|
+
```vue
|
|
334
|
+
<StructurePlot :solver="solver" :number-format="new Intl.NumberFormat('cs', { maximumFractionDigits: 2 })" />
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
Minus signs are written as a true minus (−), and a value that rounds to zero never shows as −0.
|
|
338
|
+
|
|
339
|
+
## Server rendering, accessibility and scrolling
|
|
340
|
+
|
|
341
|
+
- **Server rendering.** Both components render on the server, for example in Nuxt with prerendering. Nothing touches
|
|
342
|
+
`window` before mounting, and ids come from Vue's `useId`, so two plots on one page never share an id. The first
|
|
343
|
+
render uses the `width` prop. Once mounted, the plot measures its box and lays out again at that width.
|
|
344
|
+
- **Accessibility.**
|
|
345
|
+
- Each figure is labelled by an SVG `<title>`, set from the `title` prop or describing what is shown.
|
|
346
|
+
- Layers that are reserved but hidden are `aria-hidden`.
|
|
347
|
+
- The draggable load in `DiagramStack` is a focusable `role="slider"` with its value range and position. The arrow
|
|
348
|
+
keys move it by `loadStep`, Page Up and Page Down by 1 m, and Home and End to the ends of the beam. Keyboard focus
|
|
349
|
+
shows a ring around its grip.
|
|
350
|
+
- Under `prefers-reduced-motion`, nothing animates.
|
|
351
|
+
- **Scrolling and taps.**
|
|
352
|
+
- A plot never captures the mouse wheel or touch gestures. A static plot (`StructurePlot` without `hover`)
|
|
353
|
+
attaches no event listeners at all, so the page scrolls over it and taps reach links around it.
|
|
354
|
+
- With `hover`, or with a draggable load, the component listens to pointer events only. It sets
|
|
355
|
+
`touch-action: pan-y pinch-zoom`, so vertical scrolling and zooming still work over it.
|
|
356
|
+
|
|
357
|
+
## Browser support
|
|
358
|
+
|
|
359
|
+
The build targets Vite's default, `baseline-widely-available`: Chrome and Edge 107, Firefox 104, Safari 16 and later.
|
|
360
|
+
The plots use `ResizeObserver`, CSS custom properties in SVG, and `paint-order` for label halos. Development and the
|
|
361
|
+
screenshot checks run in Chromium.
|
|
362
|
+
|
|
363
|
+
## Development
|
|
364
|
+
|
|
365
|
+
```sh
|
|
366
|
+
npm install
|
|
367
|
+
npm run dev # the playground: textbook cases, the app's examples, staged figures
|
|
368
|
+
npm run test:run # Vitest: closed-form checks, layout and labels, the components in happy-dom and on the server
|
|
369
|
+
npm run coverage # the same, with coverage; thresholds in vite.config.ts
|
|
370
|
+
npm run lint # oxlint, with its TypeScript, Vue, import, unicorn and Vitest rules
|
|
371
|
+
npm run format # oxfmt (format:check only checks)
|
|
372
|
+
npm run typecheck # vue-tsc, strict
|
|
373
|
+
npm run build # dist/: the library bundle and its .d.ts files
|
|
374
|
+
npm run check # all of the above as CI runs them, plus publint and are-the-types-wrong
|
|
375
|
+
npm run release -- patch --dry-run # see RELEASING.md
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
Source: <https://github.com/EduBeamApp/plot>. Report bugs and ideas in its
|
|
379
|
+
[issues](https://github.com/EduBeamApp/plot/issues).
|
|
380
|
+
|
|
381
|
+
## Author
|
|
382
|
+
|
|
383
|
+
Jan Voříšek ([github.com/janvorisek](https://github.com/janvorisek)), author of EduBeam.
|
|
384
|
+
|
|
385
|
+
## License
|
|
386
|
+
|
|
387
|
+
[GPL-3.0](./LICENSE), © 2026 Jan Voříšek.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { type StackRow } from '../core/stack.js';
|
|
2
|
+
import type { DiagramStackProps } from './types.js';
|
|
3
|
+
declare const __VLS_export: import("vue").DefineComponent<DiagramStackProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
|
|
4
|
+
readout: (value: import("./types.js").StackReadout | null) => any;
|
|
5
|
+
"update:loadAt": (at: number) => any;
|
|
6
|
+
}, string, import("vue").PublicProps, Readonly<DiagramStackProps> & Readonly<{
|
|
7
|
+
onReadout?: ((value: import("./types.js").StackReadout | null) => any) | undefined;
|
|
8
|
+
"onUpdate:loadAt"?: ((at: number) => any) | undefined;
|
|
9
|
+
}>, {
|
|
10
|
+
loadCase: number;
|
|
11
|
+
revision: number;
|
|
12
|
+
hover: boolean;
|
|
13
|
+
rows: readonly StackRow[];
|
|
14
|
+
loadRow: boolean;
|
|
15
|
+
loadStep: number;
|
|
16
|
+
}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
|
|
17
|
+
declare const _default: typeof __VLS_export;
|
|
18
|
+
export default _default;
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { type Readout } from '../core/readout.js';
|
|
2
|
+
import type { StructurePlotProps } from './types.js';
|
|
3
|
+
declare const __VLS_export: import("vue").DefineComponent<StructurePlotProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
|
|
4
|
+
readout: (value: Readout | null) => any;
|
|
5
|
+
}, string, import("vue").PublicProps, Readonly<StructurePlotProps> & Readonly<{
|
|
6
|
+
onReadout?: ((value: Readout | null) => any) | undefined;
|
|
7
|
+
}>, {
|
|
8
|
+
compact: boolean;
|
|
9
|
+
momentOnTensionSide: boolean;
|
|
10
|
+
resultLabelMode: import("../index.js").ResultLabelMode;
|
|
11
|
+
loadCase: number;
|
|
12
|
+
revision: number;
|
|
13
|
+
padding: number;
|
|
14
|
+
animate: boolean;
|
|
15
|
+
hover: boolean;
|
|
16
|
+
}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
|
|
17
|
+
declare const _default: typeof __VLS_export;
|
|
18
|
+
export default _default;
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The few words the components say for themselves, to screen readers: the figure's accessible name,
|
|
3
|
+
* a diagram stack's, and the movable load's slider. English unless an app provides its own:
|
|
4
|
+
* `app.provide(PLOT_TEXTS, { structure: (layers) => … })`, or a ref of such an object to follow a
|
|
5
|
+
* language switch. A page's `title` prop still wins over `structure`.
|
|
6
|
+
*/
|
|
7
|
+
import { type ComputedRef, type InjectionKey, type Ref } from 'vue';
|
|
8
|
+
import { type PlotLayer, type TemperatureSymbols } from '../core/structure.js';
|
|
9
|
+
export interface PlotTexts {
|
|
10
|
+
/** A structure plot's accessible name, from the layers it shows, in paint order. */
|
|
11
|
+
readonly structure: (shown: readonly PlotLayer[]) => string;
|
|
12
|
+
/** A diagram stack's accessible name, from the rows it shows beneath the beam. */
|
|
13
|
+
readonly stack: (rows: readonly ('N' | 'V' | 'M' | 'w')[]) => string;
|
|
14
|
+
/** The temperature load's symbols drawn on a figure, as the app the figure belongs to writes them. */
|
|
15
|
+
readonly temperature: TemperatureSymbols;
|
|
16
|
+
/** The movable load's slider, named after the load's own label ("20 kN"). */
|
|
17
|
+
readonly loadHandle: (load: string) => string;
|
|
18
|
+
/** The slider's position in words, the distance already formatted ("3.20"). */
|
|
19
|
+
readonly loadPosition: (metres: string) => string;
|
|
20
|
+
}
|
|
21
|
+
export declare const DEFAULT_PLOT_TEXTS: PlotTexts;
|
|
22
|
+
export declare const PLOT_TEXTS: InjectionKey<Partial<PlotTexts> | Ref<Partial<PlotTexts>>>;
|
|
23
|
+
/** The texts in effect: the app's where it gives them, English for the rest. */
|
|
24
|
+
export declare const usePlotTexts: () => ComputedRef<PlotTexts>;
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Colours and the few rules a plot needs. Colours come from the page's custom properties - the
|
|
3
|
+
* names the EduBeam website already defines - so its light and dark themes apply as they are;
|
|
4
|
+
* system colours stand in on a page that defines none.
|
|
5
|
+
*/
|
|
6
|
+
import type { Tone } from '../core/scene.js';
|
|
7
|
+
export type PlotColors = Record<Tone | 'paper', string>;
|
|
8
|
+
export declare const DEFAULT_COLORS: PlotColors;
|
|
9
|
+
/** Custom properties for the root element: the defaults, with any colour the caller overrides. */
|
|
10
|
+
export declare const toneVars: (colors?: Partial<PlotColors>) => Record<string, string>;
|
|
11
|
+
/**
|
|
12
|
+
* Inlined into each SVG rather than shipped as a stylesheet, so a plot needs no CSS import and
|
|
13
|
+
* renders the same on the server. Its colours stay CSS custom properties of the page: for a file,
|
|
14
|
+
* use `structureSvg`. Every class is `ebp-` prefixed; a page can restyle them, e.g. the timing.
|
|
15
|
+
*/
|
|
16
|
+
export declare const PLOT_CSS: string;
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The components' props and events, exported so a page can type its own wrappers around them.
|
|
3
|
+
*/
|
|
4
|
+
import type { Solver } from '@edubeam/fem';
|
|
5
|
+
import type { PlotModel } from '../core/model.js';
|
|
6
|
+
import type { Readout } from '../core/readout.js';
|
|
7
|
+
import type { StackRow } from '../core/stack.js';
|
|
8
|
+
import type { PlotLayer, ReactionLabels, ResultLabelMode, ResultLayer } from '../core/structure.js';
|
|
9
|
+
import type { Units } from '../core/units.js';
|
|
10
|
+
import type { PlotColors } from './theme.js';
|
|
11
|
+
export interface StructurePlotProps {
|
|
12
|
+
/** A ts-fem solver; solved, to show results. Pass a new one (or bump `revision`) after a change. */
|
|
13
|
+
solver?: Solver;
|
|
14
|
+
/** Or the plain data `modelFromSolver` makes, e.g. prepared at build time. */
|
|
15
|
+
model?: PlotModel;
|
|
16
|
+
loadCase?: number;
|
|
17
|
+
/** Change it to redraw a solver that was changed in place. */
|
|
18
|
+
revision?: number;
|
|
19
|
+
/** What to draw. Default: members, supports, loads, reactions and one result chosen for the structure. */
|
|
20
|
+
layers?: readonly PlotLayer[];
|
|
21
|
+
/** What to make room for; defaults to `layers`. Give the last stage's layers for a figure that builds up. */
|
|
22
|
+
reserve?: readonly PlotLayer[];
|
|
23
|
+
/** Thumbnail drawing: smaller symbols, two values per member at most, magnitudes only. */
|
|
24
|
+
compact?: boolean;
|
|
25
|
+
units?: Partial<Units>;
|
|
26
|
+
numberFormat?: Intl.NumberFormat;
|
|
27
|
+
colors?: Partial<PlotColors>;
|
|
28
|
+
/** Width before the box is measured (server rendering), px. */
|
|
29
|
+
width?: number;
|
|
30
|
+
/** Fixed height, px. Without it the height follows the drawing, up to `maxHeight`. */
|
|
31
|
+
height?: number;
|
|
32
|
+
maxHeight?: number;
|
|
33
|
+
padding?: number;
|
|
34
|
+
fontSize?: number;
|
|
35
|
+
/** Largest diagram ordinate, px. */
|
|
36
|
+
diagramSize?: number;
|
|
37
|
+
/** Largest displacement on the deformed shape, px. */
|
|
38
|
+
deformedSize?: number;
|
|
39
|
+
/** px per SI unit for a result, to draw several plots at one scale. */
|
|
40
|
+
diagramScale?: Partial<Record<ResultLayer, number>>;
|
|
41
|
+
momentOnTensionSide?: boolean;
|
|
42
|
+
/** Values upright, or turned to run along their ordinate across the member (`axis`), as in the app. */
|
|
43
|
+
resultLabelMode?: ResultLabelMode;
|
|
44
|
+
/**
|
|
45
|
+
* `names` draws the reactions as the unknowns of an exercise: an arrow for every restrained
|
|
46
|
+
* direction, pointing the way it counts as positive, named (A with subscript x) instead of sized.
|
|
47
|
+
*/
|
|
48
|
+
reactionLabels?: ReactionLabels;
|
|
49
|
+
/**
|
|
50
|
+
* Label styles to make room for besides the current one, so switching `resultLabelMode` moves
|
|
51
|
+
* only the labels, not the drawing - as `reserve` does for layers.
|
|
52
|
+
*/
|
|
53
|
+
reserveLabelModes?: readonly ResultLabelMode[];
|
|
54
|
+
/**
|
|
55
|
+
* Reaction label styles to make room for besides `reactionLabels`, so an exercise that turns into
|
|
56
|
+
* its solution (`'names'` to `'values'`) keeps its drawing where it is.
|
|
57
|
+
*/
|
|
58
|
+
reserveReactionLabels?: readonly ReactionLabels[];
|
|
59
|
+
/** Fade layers in and draw members on. Always off under prefers-reduced-motion. */
|
|
60
|
+
animate?: boolean;
|
|
61
|
+
/** Read values off the members under the pointer. Off, the plot takes no pointer input at all. */
|
|
62
|
+
hover?: boolean;
|
|
63
|
+
/** Accessible name. */
|
|
64
|
+
title?: string;
|
|
65
|
+
}
|
|
66
|
+
export interface StructurePlotEmits {
|
|
67
|
+
/** The member point under the pointer and its results there, with `hover`; null when it leaves. */
|
|
68
|
+
readout: [value: Readout | null];
|
|
69
|
+
}
|
|
70
|
+
/** One row's value at the cursor: either side of a step, equal elsewhere (SI units). */
|
|
71
|
+
export interface StackReadout {
|
|
72
|
+
/** Metres along the beam line. */
|
|
73
|
+
readonly x: number;
|
|
74
|
+
readonly values: Partial<Record<StackRow, {
|
|
75
|
+
readonly left: number;
|
|
76
|
+
readonly right: number;
|
|
77
|
+
}>>;
|
|
78
|
+
}
|
|
79
|
+
export interface DiagramStackProps {
|
|
80
|
+
solver?: Solver;
|
|
81
|
+
model?: PlotModel;
|
|
82
|
+
loadCase?: number;
|
|
83
|
+
revision?: number;
|
|
84
|
+
/** The members of the beam line; all members by default. They must form one horizontal line. */
|
|
85
|
+
members?: readonly string[];
|
|
86
|
+
/** Diagram rows, top to bottom. */
|
|
87
|
+
rows?: readonly StackRow[];
|
|
88
|
+
/** The beam with its supports, loads and reactions above the rows. */
|
|
89
|
+
loadRow?: boolean;
|
|
90
|
+
/** Value range (SI) per row, to keep a row's scale while a load moves; by default each row's own. */
|
|
91
|
+
ranges?: Partial<Record<StackRow, readonly [number, number]>>;
|
|
92
|
+
/** Row heights, px, before scaling to `maxHeight`. */
|
|
93
|
+
rowHeights?: Partial<Record<StackRow, number>>;
|
|
94
|
+
/** Rows shrink (to 60 % at most) so the whole figure fits this height. Text keeps its size. */
|
|
95
|
+
maxHeight?: number;
|
|
96
|
+
units?: Partial<Units>;
|
|
97
|
+
numberFormat?: Intl.NumberFormat;
|
|
98
|
+
colors?: Partial<PlotColors>;
|
|
99
|
+
/** Width before the box is measured (server rendering), px. */
|
|
100
|
+
width?: number;
|
|
101
|
+
fontSize?: number;
|
|
102
|
+
/** Read the rows under the pointer. Off, the figure takes no pointer input. */
|
|
103
|
+
hover?: boolean;
|
|
104
|
+
/** Line position (m) of a point load the reader may drag; leave out for a fixed figure. */
|
|
105
|
+
loadAt?: number;
|
|
106
|
+
/** Text beside the draggable load; by default "P = …". */
|
|
107
|
+
loadLabel?: string;
|
|
108
|
+
/** The drag rounds to this step, m; arrow keys move by it. */
|
|
109
|
+
loadStep?: number;
|
|
110
|
+
title?: string;
|
|
111
|
+
}
|
|
112
|
+
export interface DiagramStackEmits {
|
|
113
|
+
/** The draggable load's new position, metres along the line: `v-model:load-at`. */
|
|
114
|
+
'update:loadAt': [at: number];
|
|
115
|
+
/** The cursor's values across the rows; null when the pointer leaves. */
|
|
116
|
+
readout: [value: StackReadout | null];
|
|
117
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Turns a solver from @edubeam/fem into the plain PlotModel: geometry, supports, loads, and - when the load
|
|
3
|
+
* case is solved - the reactions and every member's results as exact piecewise polynomials.
|
|
4
|
+
*/
|
|
5
|
+
import { type Solver } from '@edubeam/fem';
|
|
6
|
+
import type { PlotModel } from './model.js';
|
|
7
|
+
export interface FromSolverOptions {
|
|
8
|
+
/** Index into `solver.loadCases`. */
|
|
9
|
+
readonly loadCase?: number;
|
|
10
|
+
}
|
|
11
|
+
/** Reads a solver into plain data. Results are included only for a solved load case. */
|
|
12
|
+
export declare const modelFromSolver: (solver: Solver, options?: FromSolverOptions) => PlotModel;
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Laying a structure out in a box: the one routine behind both `StructurePlot` and `structureSvg`,
|
|
3
|
+
* so a figure on a page and the same figure saved as a file are drawn alike.
|
|
4
|
+
*/
|
|
5
|
+
import type { PlotModel } from './model.js';
|
|
6
|
+
import { type Fit, type FitBox, type ResolvedScene, type SceneItem } from './scene.js';
|
|
7
|
+
import { type PlotLayer, type ReactionLabels, type ResultLabelMode, type StructureSceneOptions } from './structure.js';
|
|
8
|
+
export interface StructureLayout {
|
|
9
|
+
readonly fit: Fit;
|
|
10
|
+
readonly items: readonly SceneItem[];
|
|
11
|
+
readonly resolved: ResolvedScene;
|
|
12
|
+
}
|
|
13
|
+
/** Results shown one at a time make room for each other's labels but never fight over places. */
|
|
14
|
+
export declare const alternativeResultGroups: (shown: ReadonlySet<PlotLayer>) => ReadonlySet<string>;
|
|
15
|
+
/**
|
|
16
|
+
* Fit with every label, see which survive, then fit again on those: a label that is dropped for
|
|
17
|
+
* crowding does not shrink the structure. The last pass may bring back any label that now fits.
|
|
18
|
+
*
|
|
19
|
+
* `options.layers` are the layers laid out (everything that may be shown); `shown` those on show.
|
|
20
|
+
* `labelModes` are the label styles to make room for, so switching between them moves nothing;
|
|
21
|
+
* `reactionLabels` the same for the reactions' names and values (an exercise and its solution).
|
|
22
|
+
*/
|
|
23
|
+
export declare const layoutStructure: (model: PlotModel, options: Omit<StructureSceneOptions, "scale">, box: FitBox, shown?: ReadonlySet<PlotLayer>, labelModes?: readonly ResultLabelMode[], reactionLabels?: readonly ReactionLabels[]) => StructureLayout;
|