figureone 0.15.10 → 1.0.0

package/types/js/figure/FigureCollections/Text.d.ts

@@ -0,0 +1,307 @@
+import type { TypeParsablePoint, TypeParsableBuffer, TypeParsableBorder } from '../../tools/g2';
+import type { OBJ_Font, OBJ_Font_Fixed, TypeColor } from '../../tools/types';
+import type FigureCollections from './FigureCollections';
+import type { EQN_EquationElements, EQN_Forms } from '../Equation/Equation';
+import type { TypeEquationPhrase } from '../Equation/EquationFunctions';
+import { Equation } from '../Equation/Equation';
+import type { OBJ_Collection } from '../FigurePrimitives/FigurePrimitiveTypes';
+/**
+ * Formatted Text line definition object.
+ *
+ * Used to define a line of text in {@link OBJ_FormattedText}.
+ *
+ * @property {string} [text] string representing a line of text
+ * @property {OBJ_Font} [font] line specific default font
+ * @property {number} [lineSpace] line specific separation from top of
+ * previous line to baseline of this line
+ * @property {number} [baselineSpace] line specific separation from baseline of
+ * this previous line to baseline of this line
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_TextLineDefinition = {
+    text: string;
+    font?: OBJ_Font;
+    lineSpace?: number;
+    baselineSpace?: number;
+};
+/**
+ * Text modifier definition object.
+ *
+ * Used to define the modifiers of a string within a formatted text element
+ * {@link OBJ_FormattedText}.
+ *
+ * @property {string} [text] text to replace `modifierId` with - if `undefined`
+ * then `modifierId` is used
+ * @property {TypeParsablePoint} [offset] text offset
+ * @property {OBJ_Font} [font] font changes for modified text
+ * @property {boolean} [inLine] `false` if modified text should not contribute
+ * to line layout (default: `true`)
+ * @property {string | function(): void} [onClick] function to execute on click
+ * within the `touchBorder` of the modified text
+ * @property {TypeParsableBuffer | boolean} [touch] use `true` to enable touch
+ * or a buffer to enable touch and define the touchBorder (`false`)
+ * buffer (`TypeParsableBuffer`) around the rectangle (default: `'0'`)
+ * @property {number} [space] additional space to right of text
+ * @property {TypeEquationPhrase} [eqn] use this to replace the text with an
+ * equation defined by an equation phrase - when using eqn the `font` property
+ * will be ignored
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_TextModifiersDefinition = {
+    text?: string;
+    offset?: TypeParsablePoint;
+    inLine?: boolean;
+    font?: OBJ_Font;
+    touch?: boolean | TypeParsableBuffer;
+    onClick?: string | (() => void);
+    space?: number;
+    eqn?: TypeEquationPhrase;
+};
+/**
+ * {@link FormattedText} options object that extends {@link OBJ_Collection}
+ * options object (without `parent`).
+ *
+ * ![](./apiassets/ftext1.png)
+ *
+ * ![](./apiassets/ftext2.png)
+ *
+ * ![](./apiassets/ftext3.png)
+ *
+ * ![](./apiassets/ftext4.gif)
+ *
+ * ![](./apiassets/ftext5.png)
+ *
+ * ![](./apiassets/ftext6.gif)
+ *
+ * Formatted text allows:
+ *   - Use of more than one font
+ *   - Multi-line text
+ *   - Embedded equations
+ *   - Interactivity on select strings
+ *
+ * If `text` is defined as an array of strings of line definition objects, then
+ * each element of the array will be a new line of text.
+ *
+ * All text will be laid out with the default font (or default line font if a
+ * line definition object is used).
+ *
+ * To modify the font of portions of text within a line, surround the text to
+ * modify with '|' characters. The string surrounded by the '|' characters will
+ * then be a unique identifier that can be referenced in the `modifiers`
+ * property which will then allow for replacing that text with some other text,
+ * changing the font of the text, changing the touchability of the text and/or
+ * replacing the text with an embedded equation.
+ *
+ * If a string is surrounded by '|' characters but not defined in `modifiers`
+ * then that string will have the formmating of the `accent` property applied
+ * to it.
+ *
+ * @property {Array<string | OBJ_TextLineDefinition> | string} [text] array of
+ * line strings - single string is single line only.
+ * @property {OBJ_TextModifiersDefinition} [modifiers] modifier definitions
+ * @property {OBJ_Font} [font] Default font to use in lines
+ * @property {TypeParsableBuffer} [defaultTextTouchBorder] default buffer for
+ * `touch` property in {@link OBJ_TextModifiersDefinition}
+ * @property {EQN_EquationElements} [elements] equation elements to use within
+ * the equation phrases defined in `modifiers`
+ * @property {'left' | 'right' | 'center} [justify] justification of lines
+ * (`left`)
+ * @property {number} [lineSpace] Space between ascent of each line with
+ * descent of previous line (`font.size * 0.5`)
+ * @property {number} [baselineSpace] Space between baselines of lines. This
+ * will override `lineSpace` for all lines including individual line settings
+ * (`undefined`)
+ * @property {'left' | 'right' | 'center'} [xAlign] horizontal alignment of
+ * lines with `position` (`left`)
+ * @property {'bottom' | 'baseline' | 'middle' | 'top'} [yAlign] vertical
+ * alignment of lines with `position` (`baseline`)
+ * @property {TypeParsableBuffer | TypeParsableBorder | 'children' | 'rect' | number} [border]
+ * border used for keeping shape within limits (`'draw'`)
+ * @property {TypeParsableBuffer | TypeParsableBorder | 'border' | 'children' | 'rect' | number} [touchBorder]
+ * border used for determining shape was touched. `number` and `'rect'` use
+ * the the points in `'buffer'` to calculate the bounding rects (`'buffer'`).
+ * @property {OBJ_Font} [accent] default modifier for accented text without a
+ * specific modification. By default accented text will be italic.
+ *
+ * @extends OBJ_Collection
+ *
+ * @see To test examples, append them to the
+ * <a href="#drawing-boilerplate">boilerplate</a>
+ *
+ * // Accent a word
+ * figure.add({
+ *   make: 'ftext',
+ *   text: 'Hello |World|',
+ * });
+ *
+ * @example
+ * // Multi-line center justified
+ * figure.add({
+ *   make: 'ftext',
+ *   text: ['First line', 'Second line'],
+ *   justify: 'center',
+ * });
+ *
+ * @example
+ * // Modifiers
+ * figure.add({
+ *   make: 'ftext',
+ *   text: ['|First| |line|', 'Second |line2|'],
+ *   modifiers: {
+ *     First: { font: { underline: 'true', color: [0, 0.7, 0.7, 1] } },
+ *     line: { font: { color: [0, 0, 1, 1] } },
+ *     line2: { text: 'line', font: { color: [0, 0.7, 0, 1], style: 'italic' } },
+ *   },
+ * });
+ *
+ * @example
+ * // Interactive words in formatted text
+ * figure.add({
+ *   make: 'ftext',
+ *   text: 'Touch |here| or |here2|',
+ *   modifiers: {
+ *     here: {
+ *       font: { underline: true, color: [0, 0, 1, 1] },
+ *       touch: 0.1,
+ *       onClick: () => console.log('here 1'),
+ *     },
+ *     here2: {
+ *       text: 'here',
+ *       font: { underline: true, color: [0, 0.8, 0, 1] },
+ *       touch: 0.1,
+ *       onClick: () => console.log('here 2'),
+ *     },
+ *   },
+ *   xAlign: 'center',
+ * });
+ *
+ * @example
+ * // Embedded equation (inline form definition)
+ * figure.add({
+ *   make: 'ftext',
+ *   text: '|root2| is irrational',
+ *   modifiers: {
+ *     root2: { eqn: { root: ['radical', '2'] } },
+ *   },
+ *   xAlign: 'center',
+ * });
+ *
+ * @example
+ * // Embedded equation with defined, touchable elements
+ * figure.add({
+ *   name: 't',
+ *   make: 'ftext',
+ *   text: ['A fraction is |fraction|', 'Touch it!'],
+ *   modifiers: {
+ *     fraction: {
+ *       eqn: {
+ *         scale: [{ frac: ['num', 'v', 'den'] }, 0.7],
+ *       },
+ *       offset: [0, 0.2],
+ *       touch: 0.1,
+ *       onClick: () => figure.get('t').pulse({
+ *         elements: ['num', 'den', 'v'],
+ *         centerOn: 'v',
+ *         xAlign: 'left',
+ *         scale: 1.3,
+ *       }),
+ *       space: 0.3,
+ *     },
+ *   },
+ *   elements: {
+ *     num: 'numerator',
+ *     den: { text: 'denominator', color: [0, 0, 1, 1], style: 'italic' },
+ *     v: { symbol: 'vinculum' },
+ *   },
+ *   xAlign: 'center',
+ * });
+ * @interface
+ * @group Text
+ */
+export type OBJ_FormattedText = {
+    text?: Array<string | OBJ_TextLineDefinition> | string;
+    modifiers?: OBJ_TextModifiersDefinition | {
+        eqn?: TypeEquationPhrase;
+    };
+    elements?: EQN_EquationElements;
+    font?: OBJ_Font;
+    defaultTextTouchBorder?: TypeParsableBuffer;
+    justify?: 'left' | 'center' | 'right';
+    lineSpace?: number;
+    baselineSpace?: number;
+    xAlign?: 'left' | 'right' | 'center';
+    yAlign?: 'bottom' | 'baseline' | 'middle' | 'top';
+    border?: TypeParsableBuffer | TypeParsableBorder | 'children' | 'rect' | number;
+    touchBorder?: TypeParsableBuffer | TypeParsableBorder | 'border' | 'children' | 'rect' | number;
+    accent?: OBJ_Font;
+} & OBJ_Collection;
+declare class CollectionsText extends Equation {
+    _eqn: Equation;
+    font: OBJ_Font_Fixed;
+    accent: OBJ_Font;
+    justify: 'left' | 'right' | 'center';
+    lineSpace: number | null;
+    lines: Array<Record<string, any>>;
+    modifiers: Record<string, any>;
+    baselineSpace: number | null;
+    defaultTextTouchBorder: TypeParsableBuffer;
+    xAlign: 'left' | 'right' | 'center';
+    yAlign: 'bottom' | 'top' | 'middle' | 'baseline';
+    touchCounter: number;
+    /**
+     * @hideconstructor
+     */
+    constructor(collections: FigureCollections, optionsIn: Record<string, any>);
+    fontUpdated(): void;
+    setText(optionsIn: OBJ_FormattedText): void;
+    updateElements(elems: {
+        [elementName: string]: {
+            text: string;
+            font: {
+                size: number;
+                family: string;
+                weight: string;
+                style: string;
+                color: TypeColor;
+            };
+            touchBorder?: TypeParsableBuffer;
+            onClick?: string | (() => void);
+        };
+    }): boolean;
+    updateForms(forms: EQN_Forms, reform: boolean): boolean;
+    splitLines(linesIn: Array<Record<string, any> | string> | string): void;
+    createEquation(): {
+        name: string;
+        make: string;
+        color: TypeColor;
+        font: OBJ_Font_Fixed;
+        textFont: OBJ_Font_Fixed;
+        scale: number;
+        elements: Record<string, any>;
+        forms: {
+            base: {
+                lines: {
+                    content: any[];
+                    justify: "left" | "right" | "center";
+                    lineSpace: number | null;
+                    baselineSpace: number | null;
+                };
+            };
+        };
+    } | {
+        name: string;
+        make: string;
+        color: TypeColor;
+        font: OBJ_Font_Fixed;
+        textFont: OBJ_Font_Fixed;
+        scale: number;
+        elements: Record<string, any>;
+        forms: {
+            base: never[];
+        };
+    };
+    createLine(line: Record<string, any>, lineIndex: number): Record<string, any>[];
+}
+export default CollectionsText;

package/types/js/figure/FigureCollections/Toggle.d.ts

@@ -0,0 +1,185 @@
+import type { TypeParsablePoint, Point } from '../../tools/g2';
+import { FigureElementCollection, FigureElementPrimitive } from '../Element';
+import type { OBJ_Collection } from '../FigurePrimitives/FigurePrimitiveTypes';
+import type { TypeColor, OBJ_Font } from '../../tools/types';
+import type FigureCollections from './FigureCollections';
+import EquationLabel from './EquationLabel';
+import type { EQN_Equation, Equation } from '../Equation/Equation';
+import type { TypeLabelSubLocation } from './EquationLabel';
+/**
+ * Collections toggle label options object.
+ *
+ * A toggle switch can be annotated with a label using the `text` property and can be:
+ * - text (`string`, `Array<string>`)
+ * - an equation (`Equation`, `EQN_Equation`)
+ *
+ * In all cases, an actual {@link Equation} is created as the label. The
+ * equation can have multiple forms, which can be set using the `showForm`
+ * method.
+ *
+ * If `text`: `string`, then an equation with a single form named `base` will
+ * be created with a single element being the string text.
+ *
+ * If `text`: `Array<string>`, then an equation with a form for each element
+ * of the array is created. Each form is named '0', '1', '2'... corresponding
+ * with the index of the array. Each form is has a single element, being the
+ * text at that index.
+ *
+ * Use `text`: `Equation` or `EQN_Equation` to create completely custom
+ * equations with any forms desirable.
+ *
+ *
+ * @see {@link COL_Toggle}
+ *
+ * @property {null | string | Array<string> | Equation | EQN_Equation } text
+ * @property {TypeParsablePoint} [offset] offset to default loation
+ * @property {TypeLabelSubLocation} [location] location of label relative to
+ * toggle
+ * @property {number} [scale] size of the label
+ * @property {TypeColor} [color]
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_ToggleLabel = {
+    text: null | string | Array<string> | Equation | EQN_Equation;
+    offset?: TypeParsablePoint;
+    location?: TypeLabelSubLocation;
+    scale?: number;
+    color?: TypeColor;
+};
+/**
+ * Border of circle or bar of toggle.
+ *
+ * @property {width} [number] border width
+ * @property {color} [TypeColor] border color
+ * @see {@link OBJ_Toggle}
+ * @interface
+ * @group Misc Shapes
+ */
+export type OBJ_ToggleBorder = {
+    width?: number;
+    color?: TypeColor;
+};
+/**
+ * {@link CollectionsToggle} options object that extends {@link OBJ_Collection}
+ * options object (without `parent`).
+ *
+ * @property {number} [width] toggle width
+ * @property {number} [height] toggle height
+ * @property {number} [barHeight] height of toggle bar showing on
+ * or off
+ * @property {number} [sides] number of sides in curves (`20`)
+ * @property {'dark' | 'light'} [theme] selects default colors for a light or
+ * dark switch (`dark`)
+ * @property {TypeColor} [colorOff] toggle off color
+ * @property {TypeColor} [colorOn] toggle on color (`[0, 1, 0, 1]`)
+ * @property {OBJ_ToggleBorder} [circleBorder] border around circle (defaults to on
+ * where width is half the figure's default line width)
+ * @property {OBJ_ToggleBorder} [barBorder] border around bar
+ * (defaults to off - width = 0)
+ * @property {OBJ_ToggleLabel} [label]
+
+ * @extends OBJ_Collection
+ * @interface
+ * @group 2D Shape Collections
+ */
+export type COL_Toggle = {
+    width?: number;
+    height?: number;
+    barHeight?: number;
+    sides?: number;
+    theme?: 'dark' | 'light';
+    colorOff?: TypeColor;
+    colorOn?: TypeColor;
+    circleBorder?: OBJ_ToggleBorder;
+    barBorder?: OBJ_ToggleBorder;
+    label?: OBJ_ToggleLabel;
+} & OBJ_Collection;
+declare class ToggleLabel extends EquationLabel {
+    offset: Point;
+    location: TypeLabelSubLocation;
+    constructor(collections: FigureCollections, labelText: string | Equation | EQN_Equation | Array<string>, color: TypeColor, offset: TypeParsablePoint, location?: TypeLabelSubLocation, scale?: number, font?: OBJ_Font | null | undefined);
+}
+/**
+ * {@link FigureElementCollection} representing a toggle switch.
+ *
+ * ![](./apiassets/toggle.gif)
+ *
+ * The toggle switch can be turned on or off.
+ *
+  * Notifications - The notification manager property `notifications` will
+ * publish the following events:
+ * - `toggle`: switch is changed - `true` will be passed if the switch is
+ *    changed to on, and `false` will be passed if the switch is changed to off
+ * - `on`: switch is changed to on
+ * - `off`: switch is changed to off
+ *
+ * See {@link COL_Toggle} for setup options.
+ *
+ * To test examples below, append them to the
+ * <a href="#drawing-boilerplate">boilerplate</a>
+ *
+ * @example
+ * // Simple toggle switch with notification causing a console statement
+ * const toggle = figure.add({
+ *   make: 'collections.toggle',
+ *   label: {
+ *     text: 'Control',
+ *     location: 'bottom',
+ *     scale: 0.6,
+ *   },
+ * });
+ *
+ * toggle.notifications.add('toggle', (state) => {
+ *   state ? console.log('on') : console.log('off');
+ * });
+ * @group 2D Shape Collections
+ */
+declare class CollectionsToggle extends FigureElementCollection {
+    _circ: FigureElementPrimitive;
+    _bar: FigureElementPrimitive;
+    _circBorder: FigureElementPrimitive | null;
+    _barBorder: FigureElementPrimitive | null;
+    label: ToggleLabel | null;
+    _label: FigureElementPrimitive | null;
+    width: number;
+    height: number;
+    colorOn: TypeColor;
+    colorOff: TypeColor;
+    /**
+     * @hideconstructor
+     */
+    constructor(collections: FigureCollections, optionsIn: COL_Toggle);
+    /**
+     * Turn switch on.
+     * @param {boolean} `true` to send `'toggle'` and `'on'` notifications
+     */
+    on(notify?: boolean): void;
+    /**
+     * Turn switch off.
+     * @param {boolean} `true` to send `'toggle'` and `'off'` notifications
+     */
+    off(notify?: boolean): void;
+    /**
+     * `true` if switch is on.
+     * @return {boolean}
+     */
+    isOn(): any;
+    /**
+     * `true` if switch is off.
+     * @return {boolean}
+     */
+    isOff(): boolean;
+    /**
+     * Toggle switch.
+     */
+    toggle(): void;
+    fontUpdated(): void;
+    updateLabel(): void;
+    /**
+     * Change label text.
+     * @param {string} text text to change to
+     */
+    setLabel(text: string): void;
+}
+export default CollectionsToggle;