diff --git a/types/desmos/desmos-tests.ts b/types/desmos/desmos-tests.ts index 9420ab2c95fc10..702bc9a2785ec1 100644 --- a/types/desmos/desmos-tests.ts +++ b/types/desmos/desmos-tests.ts @@ -1,6 +1,15 @@ +// 2D Graphing Calculator +// ————————————————————————————————————————————————————————————————————— + const elt = document.getElementById("calculator") as HTMLDivElement; const calculator = Desmos.GraphingCalculator(elt); -calculator.setExpression({ id: "graph1", latex: "y=x^2" }); + +// Set expression +calculator.setExpression({ id: "graph1", type: "expression", latex: "y=x^2" }); +// Set note +calculator.setExpression({ id: "graph2", type: "text", text: "Desmos is cool!" }); +// Set table +calculator.setExpression({ id: "graph3", type: "table", columns: [] }); // Save the current state of a calculator instance const state = calculator.getState(); @@ -95,11 +104,16 @@ calculator.setExpression({ id: "m", latex: "m=3" }); // Inequality to shade a circle at the origin calculator.setExpression({ id: "circle1", latex: "x^2 + y^2 < 1" }); -// Restrict the slider for the m variable to the integers from 1 to 10 +// Set slider bounds calculator.setExpression({ id: "m", sliderBounds: { min: 1, max: 10, step: 1 }, }); +// Omit slider step +calculator.setExpression({ + id: "m", + sliderBounds: { min: 1, max: 10 }, +}); // Table with three columns. Note that the first two columns have explicitly // specified values, and the third column is computed from the first. @@ -118,6 +132,19 @@ calculator.setExpression({ ], }); +// Observe helper expressions +var a = calculator.HelperExpression({ latex: "a" }); + +a.observe("numericValue", function() { + console.log(a.numericValue); +}); + +var L = calculator.HelperExpression({ latex: "L" }); + +L.observe("listValue", function() { + console.log(L.listValue); +}); + // Set the x axis to have arrows on both ends calculator.updateSettings({ xAxisArrowMode: Desmos.AxisArrowModes.BOTH }); @@ -163,7 +190,15 @@ document.addEventListener("mousemove", (evt) => { ); }); -// Add three different observers to the 'xAxisLabel' property +// Observe change +calculator.observeEvent("change", function(eventName, event) { + console.log("Change occurred"); + if (event.isUserInitiated) { + // throttledSave(); + } +}); + +// Add three different observers to the "xAxisLabel" property calculator.settings.observe("xAxisLabel.foo", () => {}); calculator.settings.observe("xAxisLabel.bar", () => {}); calculator.settings.observe("xAxisLabel.baz", () => {}); @@ -192,13 +227,6 @@ calculator.setExpression({ color: calculator.colors.customBlue, }); -// Text expression -calculator.setExpression({ - type: "text", - id: "4", - text: "Hello World", -}); - // Make a dashed line calculator.setExpression({ id: "line", @@ -241,7 +269,7 @@ calculator.updateSettings({ fontSize: Desmos.FontSizes.LARGE }); calculator.updateSettings({ fontSize: 11 }); // Inspect available languages -Desmos.supportedLanguages; // ['es', 'fr'] +Desmos.supportedLanguages; // ["es", "fr"] // Set a calculator instance to French calculator.updateSettings({ language: "fr" }); @@ -262,15 +290,23 @@ Desmos.enabledFeatures.GraphingCalculator && !Desmos.enabledFeatures.GeometryCalculator && !Desmos.enabledFeatures.ScientificCalculator; +// Four-Function Calculator +// ————————————————————————————————————————————————————————————————————— + const elt1 = document.getElementById( "four-function-calculator", ) as HTMLDivElement; const fourFunctionCalculator = Desmos.FourFunctionCalculator(elt1); +// Scientific Calculator +// ————————————————————————————————————————————————————————————————————— + const elt2 = document.getElementById("scientific-calculator") as HTMLDivElement; const scientificCalculator = Desmos.ScientificCalculator(elt2); -// 3d calculator +// 3D Graphing Calculator +// ————————————————————————————————————————————————————————————————————— + const elt3 = document.getElementById("calculator-3d") as HTMLDivElement; const calculator3d = Desmos.Calculator3D(elt3); @@ -280,7 +316,9 @@ calculator3d.setExpression({ color: Desmos.Colors.BLUE, }); -// geometry calculator +// Geometry Calculator +// ————————————————————————————————————————————————————————————————————— + const eltGeometry = document.getElementById( "calculator-geometry", ) as HTMLDivElement; diff --git a/types/desmos/index.d.ts b/types/desmos/index.d.ts index b4ccb4dc270354..fe5a754598873f 100644 --- a/types/desmos/index.d.ts +++ b/types/desmos/index.d.ts @@ -16,15 +16,14 @@ declare namespace Desmos { const supportedLanguages: string[]; /** - * The AxisArrowMode specifies whether arrows should be drawn at one or both ends of the x or y axes. It is specified - * separately for the x and y axes through the xAxisArrowMode and yAxisArrowMode graph settings. - * The default value for both axes is Desmos.AxisArrowMode.NONE. + * The AxisArrowMode specifies whether arrows should be drawn at one or both ends of the x or y axes. It is specified separately for the x and y axes through the xAxisArrowMode and yAxisArrowMode graph settings. The default value for both axes is Desmos.AxisArrowMode.NONE. */ const AxisArrowModes: { NONE: "NONE"; POSITIVE: "POSITIVE"; BOTH: "BOTH"; }; + /** * Default list of colors */ @@ -36,14 +35,13 @@ declare namespace Desmos { ORANGE: "#fa7e19"; BLACK: "#000000"; }; + /** - * The dragMode of a point determines whether it can be changed by dragging in the x direction, the y direction, - * both, or neither. - * In addition, a point may have its dragMode set to Desmos.DragModes.AUTO, in which case the normal calculator rules - * for determining point behavior will be applied. For example, a point whose coordinates are both slider variables would - * be draggable in both the x and y directions. - * The dragMode of a table column determines the behavior of the points represented by the column. The dragMode is only applicable - * to explicitly specified column values, and has no effect on computed column values. + * The dragMode of a point determines whether it can be changed by dragging in the x direction, the y direction, both, or neither. + * + * In addition, a point may have its dragMode set to Desmos.DragModes.AUTO, in which case the normal calculator rules for determining point behavior will be applied. For example, a point whose coordinates are both slider variables would be draggable in both the x and y directions. + * + * The dragMode of a table column determines the behavior of the points represented by the column. The dragMode is only applicable to explicitly specified column values, and has no effect on computed column values. */ const DragModes: { X: "X"; @@ -66,9 +64,10 @@ declare namespace Desmos { /** * The labelOrientation property specifies the desired position of a point's label, relative to the point itself. - * This will override the calculator's default behavior of trying to position labels in such a way as to maintain legibility. To restore this behavior, - * set the value back to Desmos.LabelOrientations.DEFAULT. - * The default value is Desmos.LabelOrientations.DEFAULT. + * + * This will override the calculator's default behavior of trying to position labels in such a way as to maintain legibility. To restore this behavior, set the value back to `Desmos.LabelOrientations.DEFAULT`. + * + * The default value is `Desmos.LabelOrientations.DEFAULT`. */ const LabelOrientations: { ABOVE: "ABOVE"; @@ -111,6 +110,7 @@ declare namespace Desmos { * @default true */ links?: boolean; + /** * Picks the extra function(s) that appear in the top bar. Maximum 2, minimum 1. * @default ["sqrt"] @@ -118,46 +118,55 @@ declare namespace Desmos { additionalFunctions?: | ("exponent" | "percent" | "fraction" | "sqrt") | ReadonlyArray<"exponent" | "percent" | "fraction" | "sqrt">; + /** * Base font size. * @default 16 */ fontSize?: number; + /** * Display the calculator with an inverted color scheme. * @default false */ invertedColors?: boolean; + /** * Display the settings menu. * @default true */ settingsMenu?: boolean; + /** * Language. See the Languages section for more information. * @default "en" */ language?: string; + /** * Set the input and output Braille code for persons using refreshable Braille displays. * @default "none" */ brailleMode?: "nemeth" | "ueb" | "none"; + /** * Allow users to write six-dot Braille characters using the Home Row keys (S, D, F, J, K, and L). Requires that brailleMode be 'nemeth' or 'ueb'. * @default false */ sixKeyInput?: boolean; + /** * Display the calculator in a larger font. * @default false */ projectorMode?: boolean; + /** * When true, users are able to toggle between decimal and fraction output in evaluations if Desmos detects a good rational approximation. * @default false */ decimalToFraction?: boolean; + /** * Limit the size of an expression to 100 characters. * @default false @@ -221,70 +230,84 @@ declare namespace Desmos { * @default true */ links?: boolean; + /** * Display the keypad in QWERTY layout (false shows an alphabetical layout) * @default true */ qwertyKeyboard?: boolean; + /** * When true, trig functions assume arguments are in degrees. Otherwise, arguments are assumed to be in radians. * @default false */ degreeMode?: boolean; + /** * Base font size. * @default 16 */ fontSize?: number; + /** * Display the calculator with an inverted color scheme. * @default false */ invertedColors?: boolean; + /** * Display the settings menu. * @default true */ settingsMenu?: boolean; + /** * Language. See the Languages section for more information. * @default "en" */ language?: string; + /** * Set the input and output Braille code for persons using refreshable Braille displays. */ brailleMode?: "nemeth" | "ueb" | "none"; + /** * Allow users to write six-dot Braille characters using the Home Row keys (S, D, F, J, K, and L). Requires that brailleMode be 'nemeth' or 'ueb'. * @default false */ sixKeyInput?: boolean; + /** * Allows the user to export a Braille rendering of the expression list. Requires that brailleMode be 'nemeth' or 'ueb'. * @default true */ brailleExpressionDownload?: boolean; + /** * Display the calculator in a larger font. * @default false */ projectorMode?: boolean; + /** * When true, users are able to toggle between decimal and fraction output in evaluations if Desmos detects a good rational approximation. * @default true */ decimalToFraction?: boolean; + /** * Limit the size of an expression to 100 characters * @default false */ capExpressionSize?: boolean; + /** * Allow function definition, i.e. f(x) = 2x * @default true */ functionDefinition?: boolean; + /** * Determine whether the calculator should automatically resize whenever there are changes to element's dimensions. If set to false * you will need to explicitly call .resize() in certain situations. See .resize(). @@ -330,8 +353,7 @@ declare namespace Desmos { interface Calculator { // methods /** - * Similar to GraphingCalculator.screenshot, but asynchronous. Rather than returning a PNG data URI directly, - * callback will be called with the either a URI string or SVG string as its argument. + * Similar to GraphingCalculator.screenshot, but asynchronous. Rather than returning a PNG data URI directly, callback will be called with the either a URI string or SVG string as its argument. */ asyncScreenshot( opts: Parameters[0] & { @@ -340,17 +362,18 @@ declare namespace Desmos { * @default "png" */ format?: "png" | "svg"; + /** * Determines the strategy for computing the viewport visible in the screenshot. * @default "contain" */ mode?: "contain" | "stretch" | "preserveX" | "preserveY"; + /** - * An object representing desired viewport bounds. The current viewport value will be used for any omitted property, - * but note that you cannot specify top without bottom or left without right. Passing invalid bounds will log a warning - * to the console and use the current viewport bounds in their entirety. + * An object representing desired viewport bounds. The current viewport value will be used for any omitted property, but note that you cannot specify top without bottom or left without right. Passing invalid bounds will log a warning to the console and use the current viewport bounds in their entirety. */ mathBounds?: Parameters[0]; + /** * Determines whether to include point labels in the captured image. * @default false @@ -365,64 +388,82 @@ declare namespace Desmos { * Clear the undo/redo history. Does not affect the current state. */ clearHistory(): void; + /** - * Destroy the GraphingCalculator instance, unbind event listeners, and free resources. This method should be called - * whenever a calculator's container element is removed from the DOM. Attempting to call methods on a GraphingCalculator object after it has been destroyed - * will result in a no-op and log a warning to the console. + * Destroy the GraphingCalculator instance, unbind event listeners, and free resources. This method should be called whenever a calculator's container element is removed from the DOM. Attempting to call methods on a GraphingCalculator object after it has been destroyed will result in a no-op and log a warning to the console. */ destroy(): void; /** - * Focus the first expression in the expressions list. Note that the first expression isn't focused by default - * because if the calculator is embedded in a page that can be scrolled, the browser will typically scroll the focused expression into view - * at page load time, which may not be desirable. + * Focus the first expression in the expressions list. Note that the first expression isn't focused by default because if the calculator is embedded in a page that can be scrolled, the browser will typically scroll the focused expression into view at page load time, which may not be desirable. */ focusFirstExpression(): void; + /** * Returns a representation of the current expressions list as an array. */ getExpressions(): ExpressionState[]; + /** - * Returns a javascript object representing the current state of the calculator. Use in conjunction with GraphingCalculator.setState to save and restore calculator states. - * The return value of GraphingCalculator.getState may be serialized to a string using JSON.stringify. - * Warning: Calculator states should be treated as opaque values. Manipulating states directly may produce a result that cannot be loaded by GraphingCalculator.setState. + * Returns a JavaScript object representing the current state of the calculator. Use in conjunction with `GraphingCalculator.setState` to save and restore calculator states. The return value of `GraphingCalculator.getState` may be serialized to a string using `JSON.stringify`. + * + * *Warning*: Calculator states should be treated as opaque values. Manipulating states directly may produce a result that cannot be loaded by `GraphingCalculator.setState`. */ getState(): GraphState; + /** * Whether or not the current viewport projection is uniform with respect to both axes (i.e., the mathematical aspect ratio is square). */ isProjectionUniform(): boolean; + /** * Convert math coordinates to pixel coordinates. */ mathToPixels< C extends { x: number } | { y: number } | { x: number; y: number }, >(coords: C): C; + /** * Update the settings.randomSeed property to a new random value. */ newRandomSeed(): void; observe(eventName: string, callback: () => void): void; + /** - * The 'change' event is emitted by the calculator whenever any change occurs that will affect the persisted state of the calculator. - * This applies to any changes caused either by direct user interaction, or by calls to API methods. - * Observing the 'change' event allows implementing periodic saving of a user's work without the need for polling. + * The `'change'` event is emitted by the calculator whenever any change occurs that will affect the persisted state of the calculator. This applies to any changes caused either by direct user interaction, or by calls to API methods. + * + * Observing the `'change'` event allows implementing periodic saving of a user's work without the need for polling. + * + * The callback provided to `observeEvent` is called with two parameters: the name of the event (e.g. `'change'`) and an `event` object containing a boolean isUserInitiated property. The value of `event.isUserInitiated` is `true` if the change that triggered the event was caused by a user interacting with the graph, and `false` otherwise (e.g. if the change is due to an API call like `calculator.setExpression()`). */ - observeEvent(eventName: string, callback: () => void): void; + observeEvent( + eventName: "change" | "graphReset" | string, + callback: (eventName: "change" | "graphReset" | string, event: { isUserInitiated: boolean }) => void, + ): void; + // NOTE: Desmos API hardcodes "change", but elsewhere also documents a `graphReset` event (it's very confusing). Leaving `| string` fallback since presumably they intend to expose more events in future. + + /** + * Remove all observers added by `GraphingCalculator.observeEvent('change')`. For finer control over removing observers, see the section on {@link https://www.desmos.com/api/v1.12/docs/index.html#managing-observers managing observers}. + */ + unobserveEvent(eventName: string): void; + /** * Convert pixel coordinates to math coordinates. */ pixelsToMath< C extends { x: number } | { y: number } | { x: number; y: number }, >(coords: C): C; + /** * Advance to the next state in the undo/redo history, if available. */ redo(): void; + /** * Remove an expression from the expressions list. */ removeExpression(expression_state: { id: string }): void; + /** * Remove several expressions from the expressions list. */ @@ -431,15 +472,17 @@ declare namespace Desmos { id: string; }>, ): void; + /** * Remove the selected expression. Returns the id of the expression that was removed, or undefined if no expression was selected. */ removeSelected(): string; + /** - * Resize the calculator to fill its container. This will happen automatically unless the autosize constructor option is set to false. - * In that case, this method must be called whenever the dimensions of the calculator's container element change, and whenever the container element is added to or removed from the DOM. + * Resize the calculator to fill its container. This will happen automatically unless the autosize constructor option is set to false. In that case, this method must be called whenever the dimensions of the calculator's container element change, and whenever the container element is added to or removed from the DOM. */ resize(): void; + /** * Returns an image of the current graphpaper in the form of a PNG data URI. You can use the returned data URI directly in the src attribute of an image. * To save the data as a traditional image file, you can parse the data and base64 decode it. @@ -449,21 +492,25 @@ declare namespace Desmos { * Width of the screenshot in pixels. Defaults to current width of graphaper. */ width?: number; + /** * Height of the screenshot in pixels. Defaults to current height of graphpaper in pixels. */ height?: number; + /** * Oversampling factor. Larger values are useful for producing images that will look good on high pixel density ("retina") screens. * @default 1 */ targetPixelRatio?: number; + /** * Determines whether to override the default behavior of stripping out the axis numbers from small images. Only relevant if opts.width or opts.height is less than 256px. * @default false */ preserveAxisNumbers?: boolean; }): string; + /** * Reset the calculator to a blank state. */ @@ -474,20 +521,36 @@ declare namespace Desmos { */ allowUndo?: boolean; }): void; + /** * Replace the calculator's "Delete All" button (under the "Edit List" menu) with a "Reset" button that will reset the calculator to the state * represented by obj. Also, if a default state is set, the "home" zoom button will reset the zoom to the viewport associated with the default state instead of the usual Desmos default * (roughly from -10 to 10, centered at the origin). If the showResetButtonOnGraphpaper option is true, a small reset button will appear on the graphpaper. */ setDefaultState(obj: GraphState): void; + /** - * This will update or create a mathematical expression. + * This will update or create a mathematical expression. `expression_state` should be an object which represents a single expression. Different types of expressions can be specified using the `type` property of `expression_state`, which must be either `text`, `expression` or `table`. If no `type` property is explicitly specified, the type defaults to `expression`. + * + * This function does not return any value. */ setExpression(expression: ExpressionState): void; + /** - * This function will attempt to create expressions for each element in the array. + * `expression_states` should be an array, and each element should be a valid argument for `GraphingCalculator.setExpression()` + * + * This function will attempt to create expressions for each element in the array, and is equivalent to + * + * ```ts + * expression_states.forEach(function (expression_state) { + * calculator.setExpression(expression_state); + * }); + * ``` + * + * This function does not return any value. */ setExpressions(expressions: readonly ExpressionState[]): void; + /** * Updates the math coordinates of the graphpaper bounds. * If invalid bounds are provided, the graphpaper bounds will not be changed. @@ -498,6 +561,7 @@ declare namespace Desmos { bottom?: number; top?: number; }): void; + /** * Reset the calculator to a state previously saved using GraphingCalculator.getState. */ @@ -509,6 +573,7 @@ declare namespace Desmos { * @default false */ allowUndo?: boolean; + /** * Remap colors in the saved state to those in the current Calculator.colors object. See the Colors section. * @default false @@ -516,15 +581,12 @@ declare namespace Desmos { remapColors?: boolean; }, ): void; + /** * Return to the previous state in the undo/redo history, if available. */ undo(): void; unobserve(eventName: string): void; - /** - * Remove all observers added by GraphingCalculator.observeEvent('change'). For finer control over removing observers, see the section on managing observers. - */ - unobserveEvent(eventName: string): void; /** * Updates any of the properties allowed in the constructor. Only properties that are present will be changed. @@ -536,14 +598,7 @@ declare namespace Desmos { */ updateSettings(settings: GraphConfiguration & GraphSettings): void; - HelperExpression(expression: ExpressionState): { - listValue: number[]; - numericValue: number; - observe( - eventName: "numericValue" | "listValue" | string, - callback: () => void, - ): void; - }; + HelperExpression(expression: ExpressionState): HelperExpressionState; // properties /** @@ -552,6 +607,7 @@ declare namespace Desmos { colors: { [key: string]: string; }; + /** * An observable object containing information about the calculator's analysis of each expression. */ @@ -561,18 +617,22 @@ declare namespace Desmos { * Does the expression represent something that can be plotted? */ isGraphable: boolean; + /** * Does the expression result in an evaluation error? */ isError: boolean; + /** * The (localized) error message, if any */ errorMessage?: string; + /** * Is evaluation information displayed in the expressions list? */ evaluationDisplayed?: boolean; + /** * Numeric value(s) */ @@ -636,416 +696,676 @@ declare namespace Desmos { supportedLanguages: string[]; } - type ExpressionState = - | { - type?: "text"; + interface Expression { + type?: "expression"; + + /** + * Following {@link https://www.desmos.com/api/v1.12/docs/index.html#document-expressions Desmos Expressions}. + */ + latex?: string; + + /** + * Hex color. See {@link https://www.desmos.com/api/v1.12/docs/#document-colors Colors}. + * Default will cycle through 6 default colors. + */ + color?: string; + + /** + * Sets the line drawing style of curves or point lists. + * See {@link https://www.desmos.com/api/v1.12/docs/#document-styles} Styles. + */ + lineStyle?: keyof typeof Styles; + + /** + * Determines width of lines in pixels. May be any positive number, or a LaTeX string that evaluates to a positive number. + * @default 2.5 + */ + lineWidth?: number | string; + + /** + * Determines opacity of lines. May be a number between `0` and `1`, or a LaTeX string that evaluates to a number between `0` and `1`. + * @default 0.9 + */ + lineOpacity?: number | string; + + /** + * Sets the point drawing style of point lists. + * See {@link https://www.desmos.com/api/v1.12/docs/#document-styles Styles}. + */ + pointStyle?: keyof typeof Styles; + + /** + * Determines diameter of points in pixels. May be any positive number, or a LaTeX string that evaluates to a positive number. + * @default 9 + */ + pointSize?: number | string; + + /** + * Determines opacity of points. May be a number between `0` and `1`, or a LaTeX string that evaluates to a number between `0` and `1`. + * @default 0.9 + */ + pointOpacity?: number | string; + + /** + * Determines opacity of the interior of a polygon or parametric curve. May be a number between `0` and `1`, or a LaTeX string that evaluates to a number between `0` and `1`. + * @default 0.4 + */ + fillOpacity?: number | string; + + /** + * Determines whether points are plotted for point lists. + */ + points?: boolean; + + /** + * Determines whether line segments are plotted for point lists. + */ + lines?: boolean; + + /** + * Determines whether a polygon or parametric curve has its interior shaded. + */ + fill?: boolean; + + /** + * Determines whether the graph is drawn. + * @default false + */ + hidden?: boolean; + + /** + * Determines whether the expression should appear in the expressions list. Does not affect graph visibility. + * @default false + */ + secret?: boolean; + + /** + * Sets bounds of slider expressions. If `step` is omitted, `''`, or `undefined`, the slider will be continuously adjustable. + */ + sliderBounds?: { + min: number | string; + max: number | string; + step?: number | string; + }; + + /** + * Determines whether the expression should animate, if it is a slider. + * @default false + */ + playing?: boolean; + /** + * Sets bounds of parametric curves. + */ + parametricDomain?: { + min: number | string; + max: number | string; + }; + + /** + * Sets bounds of polar curves. + */ + polarDomain?: { + min: number | string; + max: number | string; + }; + + /** + * Should be a valid property name for a JavaScript object (letters, numbers, and `_`). + */ + id?: string; + + /** + * Sets the drag mode of a point. See {@link https://www.desmos.com/api/v1.12/docs/index.html#document-drag-modes Drag Modes}. + * @default DragModes.AUTO + */ + dragMode?: keyof typeof DragModes; + + /** + * . Sets the text label of a point. If a label is set to the empty string then the point's default label (its coordinates) will be applied. + */ + label?: string; + + /** + * Sets the visibility of a point's text label. + */ + showLabel?: boolean; + + /** + * Specifies the text size of a point's label as a LaTeX string, which, when computed, multiplies the standard label font size of 110% of the system font size. + * @default "1" + */ + labelSize?: keyof typeof LabelSizes; + + /** + * Sets the desired position of a point's text label. See {@link https://www.desmos.com/api/v1.12/docs/index.html#document-label-orientations LabelOrientations}. + */ + labelOrientation?: keyof typeof LabelOrientations; + } + + interface Table { + type: "table"; + + /** + * Array of Table Columns. + */ + columns: ReadonlyArray<{ + /** + * Variable or computed expression used in the column header. + */ + latex: string; + + /** + * Array of LaTeX strings. Need not be specified in the case of computed table columns. + */ + values?: string[]; /** - * The text content of the note. - * @default "" + * Hex color. See Colors. Default will cycle through 6 default colors. */ - text?: string; + color?: string; /** - * Should be a valid property name for a javascript object (letters, numbers, and _). + * Determines if graph is drawn. + * @default false */ - id?: string; - } - | { - type?: "expression"; + hidden?: boolean; + /** - * Following {@link https://www.desmos.com/api/v1.11/docs/index.html#document-expressions Desmos Expressions}. + * Determines whether points are plotted. */ - latex?: string; + points?: boolean; + /** - * Hex color. See {@link https://www.desmos.com/api/v1.11/docs/#document-colors Colors}. - * Default will cycle through 6 default colors. + * Determines whether line segments are plotted. */ - color?: string; + lines?: boolean; + /** - * Sets the line drawing style of curves or point lists. - * See {@link https://www.desmos.com/api/v1.11/docs/#document-styles} Styles. + * Sets the drawing style for line segments. See Styles. */ lineStyle?: keyof typeof Styles; + /** * Determines width of lines in pixels. May be any positive number, or a LaTeX string that evaluates to a positive number. * @default 2.5 */ lineWidth?: number | string; + /** * Determines opacity of lines. May be a number between 0 and 1, or a LaTeX string that evaluates to a number between 0 and 1. * @default 0.9 */ lineOpacity?: number | string; + /** - * Sets the point drawing style of point lists. - * See {@link https://www.desmos.com/api/v1.11/docs/#document-styles} Styles. + * Sets the drawing style for points. See Styles. */ pointStyle?: keyof typeof Styles; + /** * Determines diameter of points in pixels. May be any positive number, or a LaTeX string that evaluates to a positive number. * @default 9 */ pointSize?: number | string; + /** * Determines opacity of points. May be a number between 0 and 1, or a LaTeX string that evaluates to a number between 0 and 1. * @default 0.9 */ pointOpacity?: number | string; + /** - * Determines opacity of the interior of a polygon or parametric curve. May be a number between 0 and 1, or a LaTeX string that evaluates to a number between 0 and 1. Defaults to 0.4. - */ - fillOpacity?: number | string; - /** - * Determines whether points are plotted for point lists. - */ - points?: boolean; - /** - * Determines whether line segments are plotted for point lists. - */ - lines?: boolean; - /** - * Determines whether a polygon or parametric curve has its interior shaded. - */ - fill?: boolean; - /** - * Determines whether the graph is drawn. Defaults to false. - */ - hidden?: boolean; - /** - * Determines whether the expression should appear in the expressions list. Does not affect graph visibility. - * @default false - */ - secret?: boolean; - /** - * Sets bounds of slider expressions. If step is omitted, '', or undefined, the slider will be continuously adjustable. See note below. - */ - sliderBounds?: { - min: number | string; - max: number | string; - step: number | string; - }; - /** - * Sets bounds of parametric curves. See note below. - */ - parametricDomain?: { - min: number | string; - max: number | string; - }; - /** - * Sets bounds of polar curves. See note below. - */ - polarDomain?: { - min: number | string; - max: number | string; - }; - /** - * Should be a valid property name for a javascript object (letters, numbers, and _). - */ - id?: string; - /** - * Sets the drag mode of a point. See Drag Modes. Defaults to DragModes.AUTO. + * See Drag Modes. Defaults to DragModes.NONE. */ dragMode?: keyof typeof DragModes; - /** - * . Sets the text label of a point. If a label is set to the empty string then the point's default label (its coordinates) will be applied. - */ - label?: string; - /** - * Sets the visibility of a point's text label. - */ - showLabel?: boolean; - /** - * Sets the size of a point's text label. See LabelSizes. - */ - labelSize?: keyof typeof LabelSizes; - /** - * Sets the desired position of a point's text label. See LabelOrientations. - */ - labelOrientation?: keyof typeof LabelOrientations; - } - | { - type: "table"; - /** - * Array of Table Columns. - */ - columns: ReadonlyArray<{ - /** - * Variable or computed expression used in the column header. - */ - latex: string; - /** - * Array of LaTeX strings. Need not be specified in the case of computed table columns. - */ - values?: string[]; - /** - * Hex color. See Colors. Default will cycle through 6 default colors. - */ - color?: string; - /** - * Determines if graph is drawn. - * @default false - */ - hidden?: boolean; - /** - * Determines whether points are plotted. - */ - points?: boolean; - /** - * Determines whether line segments are plotted. - */ - lines?: boolean; - /** - * Sets the drawing style for line segments. See Styles. - */ - lineStyle?: keyof typeof Styles; - /** - * Determines width of lines in pixels. May be any positive number, or a LaTeX string that evaluates to a positive number. - * @default 2.5 - */ - lineWidth?: number | string; - /** - * Determines opacity of lines. May be a number between 0 and 1, or a LaTeX string that evaluates to a number between 0 and 1. - * @default 0.9 - */ - lineOpacity?: number | string; - /** - * Sets the drawing style for points. See Styles. - */ - pointStyle?: keyof typeof Styles; - /** - * Determines diameter of points in pixels. May be any positive number, or a LaTeX string that evaluates to a positive number. - * @default 9 - */ - pointSize?: number | string; - /** - * Determines opacity of points. May be a number between 0 and 1, or a LaTeX string that evaluates to a number between 0 and 1. - * @default 0.9 - */ - pointOpacity?: number | string; - /** - * See Drag Modes. Defaults to DragModes.NONE. - */ - dragMode?: keyof typeof DragModes; - }>; - id?: string; - }; + }>; - interface GraphConfiguration { /** - * Show the onscreen keypad. - * @default true + * Should be a valid property name for a JavaScript object (letters, numbers, and `_`). */ - keypad?: boolean; + id?: string; + } + + interface Note { + type: "text"; + + /** + * The text content of the note. + * @default "" + */ + text?: string; + + /** + * Should be a valid property name for a JavaScript object (letters, numbers, and `_`). + */ + id?: string; + } + + type ExpressionState = Expression | Table | Note; + + /** + * In addition to normal expressions that show up in the calculator's expressions list, you can create "helper expressions" that are evaluated like normal expressions, but don't show up in the expressions list. Helper expressions are useful for monitoring and reacting to what a user is doing with an embedded calculator. Every `calculator` object has a `HelperExpression` constructor for adding helper expressions to that `calculator`. + * + * ```ts + * var calculator = Desmos.GraphingCalculator(elt); + * + * calculator.setExpression({ id: 'a-slider', latex: 'a=1' }); + * var a = calculator.HelperExpression({ latex: 'a' }); + * + * calculator.setExpression({ id: 'list', latex: 'L=[1, 2, 3]' }); + * var L = calculator.HelperExpression({ latex: 'L' }); + * ``` + * + * Helper expressions have two observable properties: `numericValue` for expressions that evaluate to a number, and `listValue` for expressions that evaluate to a list. They are updated whenever the expression changes. + */ + interface HelperExpressionState { + listValue: number[]; + numericValue: number; + + observe( + eventName: "numericValue" | "listValue" | string, + callback: () => void, + ): void; + } + + interface GraphConfiguration { /** * Show the graphpaper * @default true */ graphpaper?: boolean; + /** * Show the expressions list * @default true */ expressions?: boolean; + /** - * Show the settings wrench, for changing graph display + * Show the settings wrench, for changing graph display. See {@link https://www.desmos.com/api/v1.12/docs/index.html#document-accessibility Accessibility Notes}. * @default true */ settingsMenu?: boolean; + /** * Show onscreen zoom buttons * @default true */ zoomButtons?: boolean; + + /** + * Show the onscreen keypad + * @default true + */ + keypad?: boolean; + /** - * If a default state is set, show an onscreen reset button + * When `false`, the keypad will start out minimized, and the user needs to manually open it. When true, the onscreen keypad will be opened anytime focus is in a math input. Note: this option is ignored if we detect that the user is on a touch device. In that case, the keypad is always activated. + * + * @default false + */ + keypadActivated?: boolean; + + /** + * If a {@link https://www.desmos.com/api/v1.12/docs/index.html#GraphingCalculator.setDefaultState default state} is set, show an onscreen reset button * @default false */ showResetButtonOnGraphpaper?: boolean; + /** * Show the bar on top of the expressions list * @default true */ expressionsTopbar?: boolean; + /** * Show Points of Interest (POIs) as gray dots that can be clicked on * @default true */ pointsOfInterest?: boolean; + /** * Allow tracing curves to inspect coordinates, and showing point coordinates when clicked * @default true */ trace?: boolean; + /** * Add a subtle 1px gray border around the entire calculator * @default true */ border?: boolean; + /** * Disable user panning and zooming graphpaper * @default false */ lockViewport?: boolean; + /** * Collapse the expressions list * @default false */ expressionsCollapsed?: boolean; + /** - * Limit the size of an expression to 100 characters + * Limit the size of an expression to 500 LaTeX tokens and a maximum nesting depth of 30 * @default false */ capExpressionSize?: boolean; + + /** + * Enable features intended for content authoring. See {@link https://www.desmos.com/api/v1.12/docs/index.html#document-author-features the section on Author Features}. + * @default false + */ + authorFeatures?: boolean; + + // FIXME not explicitly listed in docs? is this implicit? /** * Allow creating secret folders * @default false */ administerSecretFolders?: boolean; + /** * Allow adding images * @default true */ images?: boolean; + /** - * Specify custom processing for user-uploaded images. See Image Uploads for more details. + * Specify custom processing for user-uploaded images. See {@link https://www.desmos.com/api/v1.12/docs/index.html#document-image-uploads Image Uploads} for more details. * @param file comment for stuff */ imageUploadCallback?( file: File, cb: (err: Error, url: string) => void, ): void; + /** * Allow the creation of folders in the expressions list * @default true */ folders?: boolean; + /** * Allow the creation of text notes in the expressions list * @default true */ notes?: boolean; + /** * Allow the creation of sliders in the expressions list * @default true */ sliders?: boolean; + + /** + * Allow the use of {@link https://help.desmos.com/hc/en-us/articles/4407725009165-Actions Actions}. May be `true`, `false`, or `'auto'`. When `true` or `false`, actions are completely enabled or disabled. When `'auto'`, actions are enabled, but some associated UI is only displayed after the user enters a valid action. In a future API version, `'auto'` may become a synonym for `true`. + */ + actions?: boolean | "auto"; + /** - * Allow hyperlinks in notes/folders, and links to help documentation in the expressions list (e.g. regressions with negative R2 values or plots with unresolved detail) + * Allow the use of {@link https://help.desmos.com/hc/en-us/articles/12349196836749-Substitution "with" substitutions} and {@link https://help.desmos.com/hc/en-us/articles/4407889068557-Lists list comprehensions} + * @default true + */ + substitutions?: boolean; + + /** + * Allow hyperlinks in notes/folders, and links to help documentation in the expressions list (e.g. regressions with negative R² values or plots with unresolved detail) * @default true */ links?: boolean; + /** - * Display the keypad in QWERTY layout (false shows an alphabetical layout) + * Display the keypad in QWERTY layout (`false` shows an alphabetical layout) * @default true */ qwertyKeyboard?: boolean; + /** * Enable/disable functions related to univariate data visualizations, statistical distributions, and hypothesis testing * @default true */ distributions?: boolean; + /** * Show a restricted menu of available functions * @default false */ restrictedFunctions?: boolean; + /** - * Force distance and midpoint functions to be enabled, even if restrictedFunctions is set to true. In that case the geometry functions will also be added to the the "Misc" keypad + * Force `distance` and `midpoint` functions to be enabled, even if `restrictedFunctions` is set to `true`. In that case the geometry functions will also be added to the the "Misc" keypad * @default false */ forceEnableGeometryFunctions?: boolean; + + /** + * When false, calculus operations (derivatives and integrals) are disabled. + * @default true + */ + calculus?: boolean; + /** * Paste a valid desmos graph URL to import that graph * @default false */ pasteGraphLink?: boolean; + + /** + * If a graph is opened with a playing slider or ticker, and the user has set a browser preference of "prefers reduced motion," this will pause any animations and show a cover allowing the user to opt in to the animations. + * @default false + */ + showReducedMotionCover?: boolean; + /** * Paste validly formatted table data to create a table up to 50 rows * @default true */ pasteTableData?: boolean; + /** - * When true, clearing the graph through the UI or calling setBlank() will leave the calculator in degreeMode. Note that, if a default state is set, - * resetting the graph through the UI will result in the calculator's degreeMode matching the mode of that state, regardless of this option. - * @default false + * When `true`, clearing the graph through the UI or calling `setBlank()` will leave the calculator in `degreeMode`. Note that, if a {@link https://www.desmos.com/api/v1.12/docs/index.html#GraphingCalculator.setDefaultState default state} is set, resetting the graph through the UI will result in the calculator's `degreeMode` matching the mode of that state, regardless of this option. + * @default degreeMode */ clearIntoDegreeMode?: boolean; + /** - * The color palette that the calculator will cycle through. See the Colors section. + * The color palette that the calculator will cycle through. See the {@link https://www.desmos.com/api/v1.12/docs/index.html#document-colors Colors section}. + * @default Desmos.Colors */ colors?: { [key: string]: string }; + /** - * Determine whether the calculator should automatically resize whenever there are changes to element's dimensions. If set to false you will need to - * explicitly call .resize() in certain situations. See .resize(). + * Determine whether the calculator should automatically resize whenever there are changes to element's dimensions. If set to `false` you will need to explicitly call `.resize()` in certain situations. See {@link https://www.desmos.com/api/v1.12/docs/index.html#document-layout `.resize()`}. * @default true */ autosize?: boolean; + /** * Determine whether the calculator should plot inequalities * @default true */ plotInequalities?: boolean; + /** * Determine whether the calculator should plot implicit equations and inequalities * @default true */ plotImplicits?: boolean; + /** * Determine whether the calculator should plot single-variable implicit equations * @default true */ plotSingleVariableImplicitEquations?: boolean; + /** * When true, fonts and line thicknesses are increased to aid legibility. * @default false */ projectorMode?: boolean; + /** - * When true, users are able to toggle between decimal and fraction output in evaluations if Desmos detects a good rational approximation. + * When `true`, users are able to toggle between decimal and fraction output in evaluations if Desmos detects a good rational approximation. * @default true */ decimalToFraction?: boolean; + /** * Base font size. * @default 16 */ fontSize?: number; + /** - * Display the calculator with an inverted color scheme. + * Inverts every displayed color (including API colors, below, and plotted colors). This is no longer recommended. * @default false */ invertedColors?: boolean; + + /** + * When `false`, hides the "Reverse Contrast" checkbox from the settings menu. See {@link https://www.desmos.com/api/v1.12/docs/index.html#document-accessibility Accessibility Notes}. + * @default true + */ + invertedColorsControl?: boolean; + + /** + * ***Beta*** Set the background color of the calculator. Must be a 3- or 6-character hex color (e.g. `#cde` or `#ffaaaa`). This feature is a work in progress. + * @default "#fff" + */ + backgroundColor?: string; + + /** + * ***Beta*** Set the text color of the calculator. Must be a 3- or 6-character hex color (e.g. `#000` or `#001111`). This feature is a work in progress. + * @default "#000" + */ + textColor?: string; + + /** + * ***Beta*** Set the accent color used for interactive UI elements such as buttons and focus outlines. Must be a 3- or 6-character hex color (e.g. `#000` or `#001111`). This feature is a work in progress. + * @default "#000" + */ + accentColor?: string; + /** - * Language. See the https://www.desmos.com/api/v1.11/docs/index.html#document-languages for more information. + * Language. See the {@link https://www.desmos.com/api/v1.11/docs/index.html#document-languages Languages section} for more information. * @default "en" */ language?: string; + /** - * none' Set the input and output Braille code for persons using refreshable Braille displays. Valid options are 'nemeth', 'ueb', or 'none'. + * Set the input and output Braille code for persons using refreshable Braille displays. * @default "none" */ brailleMode?: "nemeth" | "ueb" | "none"; + /** * Allow users to write six-dot Braille characters using the Home Row keys (S, D, F, J, K, and L). Requires that brailleMode be 'nemeth' or 'ueb'. * @default false */ sixKeyInput?: boolean; + /** - * Show Braille controls in the settings menu and enable shortcut keys for switching between Braille modes. + * Show Braille controls in the settings menu and enable shortcut keys for switching between Braille modes. See {@link https://www.desmos.com/api/v1.12/docs/index.html#document-accessibility Accessibility Notes}. * @default true */ brailleControls?: boolean; + + /** + * Permit the calculator to generate sound, including using the {@link https://help.desmos.com/hc/en-us/articles/21373904717197-Tone tone method} and in Audio Trace. See {@link https://www.desmos.com/api/v1.12/docs/index.html#document-accessibility Accessibility Notes}. + * @default true + */ + audio?: boolean; + + /** + * Manually set a description for the graph canvas (which replaces the automatically generated text we create). Set to an empty string to remove the description entirely, or undefined to restore the generated text. See {@link https://www.desmos.com/api/v1.12/docs/index.html#document-accessibility Accessibility Notes}. + */ + graphDescription?: string; + /** - * When true, tables and distributions will display an icon that allows the user to automatically snap the viewport to appropriate bounds for viewing that expression. + * When `true`, tables and distributions will display an icon that allows the user to automatically snap the viewport to appropriate bounds for viewing that expression. * @default true */ zoomFit?: boolean; + /** - * When true, all linearizable regression models will have log mode enabled by default, and the checkbox used to toggle log mode will be hidden from the expression interface. + * When `true`, all linearizable regression models will have log mode enabled by default, and the checkbox used to toggle log mode will be hidden from the expression interface. See {@link https://help.desmos.com/hc/en-us/articles/204349605-Log-Mode this support article} for more information. * @default false */ forceLogModeRegressions?: boolean; + + /** + * When `true`, all linearizable regression models will have log mode enabled by default, but, unlike `forceLogModeRegressions`, the checkbox used to toggle log mode will be visible from the expression interface. See {@link https://help.desmos.com/hc/en-us/articles/204349605-Log-Mode this support article} for more information. + * @default false + */ + defaultLogModeRegressions?: boolean; + + /** + * When `true`, users can create arbitrary regression models using expression syntax. See {@link https://help.desmos.com/hc/en-us/articles/4406972958733-Regressions this article on regressions}. + * @default true + */ + customRegressions?: boolean; + + /** + * When `true`, users can create regressions from a fixed menu of model options from the table column interface. See {@link https://help.desmos.com/hc/en-us/articles/4406972958733-Regressions this article on regressions}. + * @default true + */ + regressionTemplates?: boolean; + + /** + * When `true`, the option to use {@link https://help.desmos.com/hc/en-us/articles/15276544054413-Set-an-Axis-to-a-Logarithmic-Scale logarithmic axis scales} is enabled. + * @default true + */ + logScales?: boolean; + + /** + * When `true`, the {@link https://help.desmos.com/hc/en-us/articles/21373904717197-Tone tone command} is enabled. + * @default true + */ + tone?: boolean; + + /** + * When `true`, the syntax for {@link https://help.desmos.com/hc/en-us/articles/21819040155917-Generalizing-for-Lists-and-Intervals interval comprehensions} is enabled. + * @default true + */ + intervalComprehensions?: boolean; + + /** + * Globally mute or unmute sound generated by the calculator's built-in `tone()` function. See {@link https://www.desmos.com/api/v1.12/docs/index.html#document-tone the section on tones}. + * @default true + */ + muted?: boolean; + + /** + * Enable the "Complex Mode" toggle in the Settings Menu. See {@link https://help.desmos.com/hc/en-us/articles/31103542590733-Complex-Numbers section on complex numbers}. + * @default true + */ + allowComplex?: boolean; + + /** + * Specify how the calculator reports object positions to screen readers. Valid options are 'coordinates', 'percents', or 'default'. If set to 'default', objects will be reported in terms of X and Y coordinates if eeither X or Y axis is visible. If both axes are hidden, positions are reported as percentages from the viewport's top and left edges. + * @default 'default' + */ + reportPosition?: "coordinates" | "percents" | "default"; + + /** + * When `true`, show a button next to expression evaluations that copies the evaluation LaTeX to the system clipboard. Optionally, it is possible to define a callback that provides custom copy logic, e.g., for an application that manages its own clipboard. See `onEvaluationCopyClick`. + * @default false + */ + showEvaluationCopyButtons?: boolean; + + /** + * A function `(string) -> void` that will be invoked when the user clicks an expression evaluation's copy button (see above) with the evaluation LaTeX as its argument. The default implementation copies to the system clipboard. + */ + onEvaluationCopyClick?: (latex: string) => void; + + /** + * When `true`, allow the use of recursive functions. See {@link https://help.desmos.com/hc/en-us/articles/25917735966989-Recursion the article on recursion} for more information. + * @default true + */ + recursion?: boolean; } interface GraphSettings { @@ -1054,81 +1374,97 @@ declare namespace Desmos { * @default false */ degreeMode?: boolean; + /** * Show or hide grid lines on the graph paper. * @default true */ showGrid?: boolean; + /** * When true, use a polar grid. Otherwise, use cartesian grid. * @default false */ polarMode?: boolean; + /** * Show or hide the x axis. * @default true */ showXAxis?: boolean; + /** * Show or hide the y axis. * @default true */ showYAxis?: boolean; + /** * Show or hide numeric tick labels on the x axis. * @default true */ xAxisNumbers?: boolean; + /** * Show or hide numeric tick labels on the y axis. * @default true */ yAxisNumbers?: boolean; + /** * Show or hide numeric tick labels at successive angles. Only relevant when polarMode is true. * @default true */ polarNumbers?: boolean; + /** * Spacing between numeric ticks on the x axis. Will be ignored if set too small to display. When set to 0, tick spacing is chosen automatically. * @default 0 */ xAxisStep?: number; + /** * Spacing between numeric ticks on the y axis. Will be ignored if set too small to display. When set to 0, tick spacing is chosen automatically. * @default 0 */ yAxisStep?: number; + /** * Subdivisions between ticks on the x axis. Must be an integer between 0 and 5. 1 means that only the major grid lines will be shown. When set to 0, subdivisions are chosen automatically. * @default 0 */ xAxisMinorSubdivisions?: number; + /** * Subdivisions between ticks on the y axis. Must be an integer between 0 and 5. 1 means that only the major grid lines will be shown. When set to 0, subdivisions are chosen automatically. * @default 0 */ yAxisMinorSubdivisions?: number; + /** * Determines whether to place arrows at one or both ends of the x axis. See Axis Arrow Modes. * @default "NONE" */ xAxisArrowMode?: keyof typeof AxisArrowModes; + /** * Determines whether to place arrows at one or both ends of the y axis. See Axis Arrow Modes. * @default "NONE" */ yAxisArrowMode?: keyof typeof AxisArrowModes; + /** * Label placed below the x axis. * @default "" */ xAxisLabel?: string; + /** * Label placed beside the y axis. * @default "" */ yAxisLabel?: string; + /** * Global random seed used for generating values from the calculator's built-in random() function. See the section on random seeds below. * @default "" diff --git a/types/desmos/package.json b/types/desmos/package.json index d7565c1187e979..2251bdca66290b 100644 --- a/types/desmos/package.json +++ b/types/desmos/package.json @@ -1,13 +1,13 @@ { "private": true, "name": "@types/desmos", - "version": "1.11.9999", - "projects": ["https://www.desmos.com/api/v1.11/docs/"], + "version": "1.12.9999", + "projects": ["https://www.desmos.com/api/v1.12/docs/"], "devDependencies": { "@types/desmos": "workspace:." }, "nonNpm": "conflict", - "nonNpmDescription": "Desmos graphing calculator API (https://www.desmos.com/api/v1.11/docs/).\nThese types are for use with the Desmos API loaded via