@pie-players/pie-tool-calculator-desmos 0.3.75 → 1.0.0-beta.0

package/README.md

@@ -1,38 +1,75 @@
-# Desmos Calculator Tool
+# @pie-players/pie-tool-calculator-desmos
 
-Calculator custom element backed by the Desmos provider for PIE assessment
-player flows. It is a thin compatibility entry for
-`@pie-players/pie-tool-calculator-shared/calculator-element`, which holds the
-Desmos-specific layout rules. The toolkit's calculator tool config selects the
-provider the element mounts.
+A compatibility entry that registers `<pie-tool-calculator>`, the assessment
+toolkit's provider-neutral calculator element. Importing it has the same effect
+as importing `@pie-players/pie-tool-calculator-shared/calculator-element`; the
+`desmos` in the name is historical. The element mounts whichever adapter the
+toolkit's `tools.providers.calculator` selects, [Desmos](../calculator-desmos/README.md),
+[GeoGebra](../calculator-geogebra/README.md) or [Cortex](../calculator-cortex/README.md),
+as [Calculator providers](../default-tool-loaders/README.md#calculator-providers)
+describes.
 
-## Usage
+The toolkit's packaged tool set loads the same element on demand and skips the
+load when the tag is already defined, so a toolkit host needs this package only
+to register the element ahead of that load, for example in an eager bundle.
+
+## Installation
+
+```bash
+bun add @pie-players/pie-tool-calculator-desmos
+```
 
-Import the package to register `<pie-tool-calculator>`:
+## Usage
 
 ```ts
 import "@pie-players/pie-tool-calculator-desmos";
 ```
 
+The toolkit's calculator registration creates the element in the item toolbar's
+overlay and sets its type, allowed types and `calculatorConfig`. A host that
+places the element itself puts it inside a section or item player running the
+toolkit: the element reads the toolkit runtime context and mounts nothing
+without a toolkit coordinator.
+
 ```html
 <pie-tool-calculator
-  visible="true"
+  visible
   tool-id="calculator"
   calculator-type="scientific"
 ></pie-tool-calculator>
 ```
 
-## Props
+## Attributes and properties
 
-| Prop | Type | Default | Description |
+| Property | Attribute | Default | Purpose |
 | --- | --- | --- | --- |
-| `visible` | `boolean` | `false` | Controls whether the calculator is visible. |
-| `toolId` | `string` | `calculator` | Tool instance id; its base tool id is the id the toolkit registers the calculator provider under. |
-| `calculatorType` | `string` | package default | Requested calculator mode. |
-| `availableTypes` | `string[]` | package default | Calculator modes the host allows. |
-| `calculatorConfig` | `CalculatorProviderConfig` | `{}` | Provider-neutral options plus implementation-owned `settings`. |
+| `visible` | `visible` | `false` | Mounts the calculator while true and destroys it when false. `"false"`, `"0"`, `"off"` and `"no"` read as false. |
+| `toolId` | `tool-id` | `"calculator"` | Tool instance id. The element resolves the provider under its base tool id, the id without the toolkit's `:<level>:<scopeId>` suffix. |
+| `calculatorType` | `calculator-type` | `"basic"` | `basic`, `scientific` or `graphing`. A type outside `availableTypes` falls back to the first allowed type. |
+| `availableTypes` | `available-types` | All three types | Allowed types. The attribute takes a JSON array; the property also accepts a comma-separated string. Unknown values are dropped. |
+| `calculatorConfig` | — | `{}` | `CalculatorProviderConfig` passed to `createCalculator()`. The toolkit sets it from the calculator tool config: `settings`, `restrictedMode`, `locale` and `theme`. |
+
+## Behavior
+
+The element renders without a shadow root. On mount it calls the toolkit
+coordinator's `ensureProviderReady()` for the base tool id, creates a provider
+instance, and creates the calculator in its container. A change to the tool id,
+effective type or `calculatorConfig` remounts the calculator, and so does a tool
+config update that replaces the provider. When the provider declares an
+attribution, the element renders it as a link below the calculator. A failed
+mount shows "Calculator failed to initialize." with the error message.
+
+The element does not persist calculator state; hiding it destroys the
+calculator. Hosts that save and restore state drive an adapter directly through
+the [`@pie-players/pie-calculator`](../calculator/README.md) contract.
+
+## Exports
+
+The entry exports the type `CalculatorType` from `@pie-players/pie-calculator`.
 
-## Related Documentation
+## Related documentation
 
-- [Calculator providers](../default-tool-loaders/src/calculator-providers/README.md)
+- [Calculator providers](../default-tool-loaders/README.md#calculator-providers)
+- [`@pie-players/pie-tool-calculator-inline-desmos`](../tool-calculator-inline-desmos/README.md),
+  the item-header button that opens this calculator
 - [Tools and accommodations architecture](../../docs/tools-and-accomodations/architecture.md)

package/custom-elements.json

@@ -0,0 +1,21 @@
+{
+	"schemaVersion": "2.1.0",
+	"modules": [
+		{
+			"kind": "javascript-module",
+			"path": "dist/pie-tool-calculator.js",
+			"declarations": [],
+			"exports": [
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-tool-calculator",
+					"declaration": {
+						"name": "CalculatorElement",
+						"module": "dist/calculator-element.js",
+						"package": "@pie-players/pie-tool-calculator-shared"
+					}
+				}
+			]
+		}
+	]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-tool-calculator-desmos",
-	"version": "0.3.75",
+	"version": "1.0.0-beta.0",
 	"type": "module",
 	"description": "Calculator tool for PIE assessment player",
 	"repository": {
@@ -25,8 +25,10 @@
 			"import": "./dist/pie-tool-calculator.js"
 		}
 	},
+	"customElements": "custom-elements.json",
 	"files": [
 		"dist",
+		"custom-elements.json",
 		"README.md"
 	],
 	"scripts": {
@@ -41,17 +43,16 @@
 	"unpkg": "./dist/pie-tool-calculator.js",
 	"jsdelivr": "./dist/pie-tool-calculator.js",
 	"dependencies": {
-		"@pie-players/pie-calculator": "0.3.75",
-		"@pie-players/pie-tool-calculator-shared": "0.3.75"
+		"@pie-players/pie-calculator": "1.0.0-beta.0",
+		"@pie-players/pie-tool-calculator-shared": "1.0.0-beta.0"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.15",
-		"@pie-players/pie-calculator-desmos": "0.3.75",
 		"@sveltejs/vite-plugin-svelte": "^7.3.1",
 		"svelte": "^5.57.1",
 		"svelte-check": "^4.7.6",
 		"typescript": "^5.9.3",
-		"vite": "^8.3.2",
+		"vite": "^8.3.3",
 		"vite-plugin-dts": "^5.1.2"
 	},
 	"homepage": "https://github.com/pie-framework/pie-players/tree/master/packages/tool-calculator-desmos#readme",