@pie-players/pie-tool-calculator-inline-desmos 0.3.74 → 1.0.0-beta.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.
Files changed (4) hide show
  1. package/README.md +78 -112
  2. package/custom-elements.json +124 -0
  3. package/dist/tool-calculator-inline.js +863 -807
  4. package/package.json +9 -7
package/README.md CHANGED
@@ -1,139 +1,105 @@
1
1
  # @pie-players/pie-tool-calculator-inline-desmos
2
2
 
3
- Inline calculator toggle button for PIE assessment player question headers.
3
+ `<pie-tool-calculator-inline>` is a button for an item header that opens and
4
+ closes the calculator the item toolbar renders. It is provider-neutral: the
5
+ toolkit's `tools.providers.calculator` picks the adapter, and the `desmos` in
6
+ the package name is historical. The button adds no calculator of its own. It
7
+ opens the toolbar's `<pie-tool-calculator>`
8
+ ([`@pie-players/pie-tool-calculator-desmos`](../tool-calculator-desmos/README.md))
9
+ through the toolkit's tool request path, so the item's tool policy governs both
10
+ and the button and toolbar stay in step. The packaged tool set does not include
11
+ this element.
4
12
 
5
- ## Overview
13
+ The element has an open shadow root and bundles the shared inline surface from
14
+ `@pie-players/pie-tool-calculator-shared`.
6
15
 
7
- `<pie-tool-calculator-inline>` is a toggle button for the calculator an item
8
- toolbar renders. It wraps the provider-neutral inline surface from
9
- `@pie-players/pie-tool-calculator-shared`, which the GeoGebra and Cortex inline
10
- packages share.
16
+ ## Installation
11
17
 
12
- ## Features
13
-
14
- - **Web Component** - Custom element with an open shadow root
15
- - **Toolkit context** - Takes its ToolCoordinator from the toolkit runtime context and its item from the enclosing item shell
16
- - **Shared state** - Opens the item toolbar's calculator instance, so the button and the toolbar stay in step
17
- - **Size Variants** - Supports sm, md, lg button sizes
18
- - **WCAG 2.2 Level AA** - Fully accessible with proper ARIA attributes
19
- - **Material Design Icon** - Calculator icon from Material Design
18
+ ```bash
19
+ bun add @pie-players/pie-tool-calculator-inline-desmos
20
+ ```
20
21
 
21
22
  ## Usage
22
23
 
23
- The element renders inside `<pie-item-shell>` under `<pie-assessment-toolkit>`.
24
- The toolkit runtime context supplies the ToolCoordinator and the shell supplies
25
- the item; section players provide both.
24
+ The element renders inside `<pie-item-scope>` under `<pie-assessment-toolkit>`:
25
+ the toolkit runtime context supplies the tool coordinator and the item shell
26
+ supplies the item. Section players provide both.
26
27
 
27
- ```javascript
28
- import '@pie-players/pie-tool-calculator-inline-desmos';
28
+ ```ts
29
+ import "@pie-players/pie-tool-calculator-inline-desmos";
29
30
 
30
- // itemHeader: an element inside <pie-item-shell>
31
- const calculatorButton = document.createElement('pie-tool-calculator-inline');
32
- calculatorButton.setAttribute('calculator-type', 'scientific');
31
+ // itemHeader: an element inside <pie-item-scope>
32
+ const calculatorButton = document.createElement("pie-tool-calculator-inline");
33
+ calculatorButton.setAttribute("calculator-type", "scientific");
33
34
  itemHeader.append(calculatorButton);
34
35
  ```
35
36
 
36
- The calculator it opens is the item toolbar's: the toolkit's tool configuration
37
- places `calculator` in the item toolbar and names its provider, and the item
38
- toolbar renders that calculator. The button adds no calculator of its own, so
39
- an item whose tool policy leaves the calculator out has nothing for it to open.
37
+ The toolkit's tool configuration places `calculator` in the item toolbar and
38
+ names its provider. The button is enabled once the runtime context supplies a
39
+ tool coordinator and the target toolbar renders the calculator
40
+ (`canRequestTool`). It is disabled while the item's tool policy leaves the
41
+ calculator out or the calculator module failed to load, and re-checks when
42
+ toolbars register or the policy changes.
40
43
 
41
- ### Props
44
+ ## Attributes
42
45
 
43
- #### Attributes (String)
46
+ | Attribute | Default | Purpose |
47
+ | --- | --- | --- |
48
+ | `target-tool-id` | `""` | Scoped id of the calculator to toggle, `<toolId>:<section\|item\|passage>:<scopeId>`. Empty resolves the enclosing item's calculator, `calculator:item:<id>` with the item's canonical id, else its id. Set it only to toggle another toolbar's calculator. |
49
+ | `calculator-type` | `"basic"` | The type the button requests and names in its label and announcements. A type outside `available-types` falls back to `basic`. |
50
+ | `available-types` | `"basic,scientific,graphing"` | Comma-separated types the opened calculator offers, together with `calculator-type`. |
51
+ | `size` | `"md"` | `sm`, `md` or `lg`. |
44
52
 
45
- - `target-tool-id` - Coordinator tool id the button toggles (default: `''`). Empty resolves the enclosing item's calculator, `calculator:item:<itemId>`; set it only to toggle a calculator registered under another id
46
- - `calculator-type` - Calculator type named in the button's label and announcements (default: `'basic'`); a type outside `available-types` falls back to `'basic'`
47
- - `available-types` - Comma-separated list of calculator types (default: `'basic,scientific,graphing'`)
48
- - `size` - Button size: `'sm' | 'md' | 'lg'` (default: `'md'`)
49
-
50
- The button is disabled until the toolkit runtime context supplies a
51
- ToolCoordinator and a target resolves. With no item shell and no
52
- `target-tool-id`, it stays disabled and logs a console warning.
53
+ Each attribute has a camelCase property of the same name. When no target
54
+ resolves, because the button sits outside an item shell or `target-tool-id` is
55
+ not a scoped id, the button stays disabled and logs a console warning after one
56
+ second.
53
57
 
54
58
  ## Toggle behavior
55
59
 
56
- 1. The button resolves its target from the item shell context: `calculator:item:<canonicalItemId or itemId>`, the id the item toolbar uses.
57
- 2. A click registers that id with the coordinator if the toolbar has not yet, then calls `toggleTool`.
58
- 3. The item toolbar renders or hides its calculator from the coordinator's visibility state.
59
- 4. `aria-pressed`, the active style and a status announcement follow the target's visibility, including changes made from the toolbar.
60
+ 1. A click on a closed calculator sends a tool request for the target's tool
61
+ id, level and scope (`requestTool`) with the button's type and available
62
+ types as render params, and the toolbar shows its calculator with them.
63
+ 2. A click on an open calculator hides it.
64
+ 3. `aria-pressed` and the active style follow the target's visibility,
65
+ including changes made from the toolbar.
60
66
 
61
67
  ## Accessibility
62
68
 
63
- - **WCAG 2.2 Level AA compliant**
64
- - **Keyboard accessible** - Full keyboard navigation support
65
- - **Focus indicators** - Clear focus states (2.4.7, 2.4.13)
66
- - **ARIA attributes** - `aria-label`, `aria-pressed`
67
- - **Screen reader announcements** - Status changes announced
68
- - **Reduced motion** - Respects `prefers-reduced-motion`
69
- - **Touch targets** - Minimum 44px touch target (2.5.2)
70
-
71
- ## Size Variants
72
-
73
- ### Small (`sm`)
74
- - Visual size: 1.5rem × 1.5rem
75
- - Touch target: 44px × 44px (with padding)
76
- - Icon: 1rem × 1rem
69
+ - A native `<button>` whose `aria-label` and `title` name the calculator type,
70
+ with `aria-pressed` for the open state.
71
+ - A polite live region announces each open and close the button makes, per
72
+ calculator type.
73
+ - A 2px focus outline with a 2px offset (WCAG 2.4.7).
74
+ - Every size is at least 24×24 CSS px (WCAG 2.5.8).
75
+ - `prefers-reduced-motion` turns the transitions off.
77
76
 
78
- ### Medium (`md`) - Default
79
- - Size: 2rem × 2rem
80
- - Icon: 1.25rem × 1.25rem
77
+ ## Size variants
81
78
 
82
- ### Large (`lg`)
83
- - Size: 2.5rem × 2.5rem
84
- - Icon: 1.5rem × 1.5rem
79
+ | Size | Button | Icon |
80
+ | --- | --- | --- |
81
+ | `sm` | 1.5rem × 1.5rem | 1rem × 1rem |
82
+ | `md` (default) | 2rem × 2rem | 1.25rem × 1.25rem |
83
+ | `lg` | 2.5rem × 2.5rem | 1.5rem × 1.5rem |
85
84
 
86
85
  ## Styling
87
86
 
88
- The component uses CSS custom properties for theming:
89
-
90
- ```css
91
- --pie-border: Border color (default: #ccc)
92
- --pie-button-background-color: Button fill, ahead of --pie-button-bg
93
- --pie-button-bg: Button fill (default: theme button surface)
94
- --pie-text: Text color (default: #333)
95
- --pie-button-hover-background-color: Hover fill, ahead of --pie-button-hover-bg
96
- --pie-button-hover-bg: Hover fill (default: theme hover surface)
97
- --pie-tool-trigger-active-background: Active/open button background
98
- --pie-tool-trigger-active-color: Active/open button foreground
99
- --pie-tool-trigger-active-border-color: Active/open button border
100
- ```
101
-
102
- The trigger fills itself from the button tokens. `--pie-background` is the page
103
- token and the base light theme ships it transparent, so a host that sets it does
104
- not change this button; set `--pie-button-bg`, or `--pie-button-background-color`
105
- for this control alone.
106
-
107
- Hosts should prefer the `--pie-tool-trigger-active-*` variables when styling the
108
- calculator button's active/open state instead of overriding broad semantic tokens
109
- such as `--pie-primary`. If these variables are unset, the button preserves the
110
- existing filled active look using `--pie-primary` and `--pie-primary-dark`
111
- fallbacks. Hosts remain responsible for maintaining WCAG AA
112
- foreground/background contrast when overriding active trigger colors.
113
-
114
- ## Development
115
-
116
- ```bash
117
- # Install dependencies
118
- bun install
119
-
120
- # Build
121
- bun run build
122
-
123
- # Watch mode
124
- bun run dev
125
-
126
- # Type check
127
- bun run typecheck
128
-
129
- # Lint
130
- bun run lint
131
- ```
132
-
133
- ## Dependencies
134
-
135
- - `@pie-players/pie-assessment-toolkit` - Toolkit contexts and scoped tool ids
136
-
137
- ## License
138
-
139
- MIT
87
+ | Token | Use | Fallback |
88
+ | --- | --- | --- |
89
+ | `--pie-button-background-color` | Fill of this control | `--pie-button-bg`, then `--pie-white`, `#fff` |
90
+ | `--pie-button-hover-background-color` | Hover fill of this control | `--pie-button-hover-bg`, then `--pie-secondary-background`, `#f5f5f5` |
91
+ | `--pie-tool-trigger-active-background` | Open-state fill | `--pie-primary`; on hover `--pie-primary-dark` |
92
+ | `--pie-tool-trigger-active-border-color` | Open-state border | `--pie-primary` |
93
+ | `--pie-tool-trigger-active-color` | Open-state foreground and icon | White |
94
+ | `--pie-border` | Border | `#ccc` |
95
+ | `--pie-text` | Foreground | `#333` |
96
+ | `--pie-button-focus-outline` | Focus outline | `#0066cc` |
97
+ | `--pie-button-hover-color` | Icon on hover while closed | `#667eea` |
98
+
99
+ The first five are registered `component-public` tokens; the others are
100
+ canonical semantic tokens. The fill does not read `--pie-background`, the page
101
+ token a host may point at its own backdrop: set `--pie-button-bg` for every
102
+ button, or `--pie-button-background-color` for this control alone. Hosts style
103
+ the open state through the `--pie-tool-trigger-active-*` tokens, which leave
104
+ `--pie-primary` untouched elsewhere, and keep WCAG AA contrast between the
105
+ foreground and background they set.
package/custom-elements.json ADDED
@@ -0,0 +1,124 @@
1
+ {
2
+ "schemaVersion": "2.1.0",
3
+ "modules": [
4
+ {
5
+ "kind": "javascript-module",
6
+ "path": "dist/tool-calculator-inline.js",
7
+ "declarations": [
8
+ {
9
+ "kind": "class",
10
+ "description": "Calculator toggle button for an item header inside `<pie-item-scope>`. It opens and closes the calculator the item toolbar renders, through the toolkit coordinator's tool requests, and reflects that calculator's visibility in `aria-pressed`; `target-tool-id` points it at another toolbar's calculator. It stays disabled until the runtime context supplies a tool coordinator and the target toolbar renders a calculator.",
11
+ "name": "ToolCalculatorInline",
12
+ "tagName": "pie-tool-calculator-inline",
13
+ "customElement": true,
14
+ "members": [
15
+ {
16
+ "kind": "field",
17
+ "name": "targetToolId",
18
+ "type": {
19
+ "text": "string"
20
+ },
21
+ "default": "''",
22
+ "attribute": "target-tool-id"
23
+ },
24
+ {
25
+ "kind": "field",
26
+ "name": "calculatorType",
27
+ "type": {
28
+ "text": "string"
29
+ },
30
+ "default": "'basic'",
31
+ "attribute": "calculator-type"
32
+ },
33
+ {
34
+ "kind": "field",
35
+ "name": "availableTypes",
36
+ "type": {
37
+ "text": "string"
38
+ },
39
+ "default": "'basic,scientific,graphing'",
40
+ "attribute": "available-types"
41
+ },
42
+ {
43
+ "kind": "field",
44
+ "name": "size",
45
+ "type": {
46
+ "text": "'sm' | 'md' | 'lg'"
47
+ },
48
+ "default": "'md'",
49
+ "attribute": "size"
50
+ }
51
+ ],
52
+ "attributes": [
53
+ {
54
+ "name": "target-tool-id",
55
+ "type": {
56
+ "text": "string"
57
+ },
58
+ "default": "''",
59
+ "fieldName": "targetToolId"
60
+ },
61
+ {
62
+ "name": "calculator-type",
63
+ "type": {
64
+ "text": "string"
65
+ },
66
+ "default": "'basic'",
67
+ "fieldName": "calculatorType"
68
+ },
69
+ {
70
+ "name": "available-types",
71
+ "type": {
72
+ "text": "string"
73
+ },
74
+ "default": "'basic,scientific,graphing'",
75
+ "fieldName": "availableTypes"
76
+ },
77
+ {
78
+ "name": "size",
79
+ "type": {
80
+ "text": "string"
81
+ },
82
+ "default": "'md'",
83
+ "fieldName": "size"
84
+ }
85
+ ],
86
+ "cssProperties": [
87
+ {
88
+ "name": "--pie-button-background-color",
89
+ "description": "Compatibility alias retained for TTS inline button backgrounds; implementations must fall back through canonical --pie-button-bg before broad surface tokens."
90
+ },
91
+ {
92
+ "name": "--pie-button-hover-background-color",
93
+ "description": "Compatibility alias retained for calculator inline button hover backgrounds; implementations must fall back through canonical --pie-button-hover-bg before broad surface tokens."
94
+ },
95
+ {
96
+ "name": "--pie-tool-trigger-active-background",
97
+ "description": "Component trigger active/open background hook; falls back through existing semantic tokens and must preserve WCAG contrast when overridden by hosts."
98
+ },
99
+ {
100
+ "name": "--pie-tool-trigger-active-border-color",
101
+ "description": "Component trigger active/open border hook; falls back through existing semantic tokens."
102
+ },
103
+ {
104
+ "name": "--pie-tool-trigger-active-color",
105
+ "description": "Component trigger active/open foreground hook; hosts are responsible for preserving contrast with the active trigger background."
106
+ }
107
+ ],
108
+ "x-pie": {
109
+ "shadow": "open"
110
+ }
111
+ }
112
+ ],
113
+ "exports": [
114
+ {
115
+ "kind": "custom-element-definition",
116
+ "name": "pie-tool-calculator-inline",
117
+ "declaration": {
118
+ "name": "ToolCalculatorInline"
119
+ }
120
+ }
121
+ ]
122
+ }
123
+ ]
124
+ }