@pie-players/pie-tool-calculator-inline-desmos 0.3.75 → 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 +77 -113
  2. package/custom-elements.json +124 -0
  3. package/dist/tool-calculator-inline.js +306 -294
  4. package/package.json +8 -6
package/README.md CHANGED
@@ -1,141 +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 through the toolkit's tool request path, so the button and the toolbar stay in step and policy applies to both
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-scope>` 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
31
  // itemHeader: an element inside <pie-item-scope>
31
- const calculatorButton = document.createElement('pie-tool-calculator-inline');
32
- calculatorButton.setAttribute('calculator-type', 'scientific');
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 and is
39
- disabled while the toolbar does not render one, as when the item's tool policy
40
- leaves the calculator out or its module failed to load.
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.
41
43
 
42
- ### Props
44
+ ## Attributes
43
45
 
44
- #### 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`. |
45
52
 
46
- - `target-tool-id` - Scoped id of the calculator the button toggles, `<toolId>:<section|item|passage>:<scopeId>` (default: `''`). Empty resolves the enclosing item's calculator, `calculator:item:<itemId>`; set it only to toggle another toolbar's calculator
47
- - `calculator-type` - Calculator type named in the button's label and announcements (default: `'basic'`); a type outside `available-types` falls back to `'basic'`
48
- - `available-types` - Comma-separated list of calculator types (default: `'basic,scientific,graphing'`)
49
- - `size` - Button size: `'sm' | 'md' | 'lg'` (default: `'md'`)
50
-
51
- The button is disabled until the toolkit runtime context supplies a
52
- ToolCoordinator and the target toolbar renders the calculator. With no item
53
- shell and no valid `target-tool-id`, it stays disabled and logs a console
54
- 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.
55
57
 
56
58
  ## Toggle behavior
57
59
 
58
- 1. The button resolves its target from the item shell context: the item toolbar for `<canonicalItemId or itemId>`, which shows the calculator as `calculator:item:<id>`.
59
- 2. It asks the toolkit coordinator whether a tool request for `calculator` at that level and scope reaches a toolbar (`canRequestTool`), and re-asks when toolbars register or policy changes.
60
- 3. A click on a closed calculator sends the request (`requestTool`), and the toolbar shows its calculator; a click on an open one hides it.
61
- 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.
62
66
 
63
67
  ## Accessibility
64
68
 
65
- - **WCAG 2.2 Level AA compliant**
66
- - **Keyboard accessible** - Full keyboard navigation support
67
- - **Focus indicators** - Clear focus states (2.4.7, 2.4.13)
68
- - **ARIA attributes** - `aria-label`, `aria-pressed`
69
- - **Screen reader announcements** - Status changes announced
70
- - **Reduced motion** - Respects `prefers-reduced-motion`
71
- - **Touch targets** - Minimum 44px touch target (2.5.2)
72
-
73
- ## Size Variants
74
-
75
- ### Small (`sm`)
76
- - Visual size: 1.5rem × 1.5rem
77
- - Touch target: 44px × 44px (with padding)
78
- - 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.
79
76
 
80
- ### Medium (`md`) - Default
81
- - Size: 2rem × 2rem
82
- - Icon: 1.25rem × 1.25rem
77
+ ## Size variants
83
78
 
84
- ### Large (`lg`)
85
- - Size: 2.5rem × 2.5rem
86
- - 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 |
87
84
 
88
85
  ## Styling
89
86
 
90
- The component uses CSS custom properties for theming:
91
-
92
- ```css
93
- --pie-border: Border color (default: #ccc)
94
- --pie-button-background-color: Button fill, ahead of --pie-button-bg
95
- --pie-button-bg: Button fill (default: theme button surface)
96
- --pie-text: Text color (default: #333)
97
- --pie-button-hover-background-color: Hover fill, ahead of --pie-button-hover-bg
98
- --pie-button-hover-bg: Hover fill (default: theme hover surface)
99
- --pie-tool-trigger-active-background: Active/open button background
100
- --pie-tool-trigger-active-color: Active/open button foreground
101
- --pie-tool-trigger-active-border-color: Active/open button border
102
- ```
103
-
104
- The trigger fills itself from the button tokens. `--pie-background` is the page
105
- token and the base light theme ships it transparent, so a host that sets it does
106
- not change this button; set `--pie-button-bg`, or `--pie-button-background-color`
107
- for this control alone.
108
-
109
- Hosts should prefer the `--pie-tool-trigger-active-*` variables when styling the
110
- calculator button's active/open state instead of overriding broad semantic tokens
111
- such as `--pie-primary`. If these variables are unset, the button preserves the
112
- existing filled active look using `--pie-primary` and `--pie-primary-dark`
113
- fallbacks. Hosts remain responsible for maintaining WCAG AA
114
- foreground/background contrast when overriding active trigger colors.
115
-
116
- ## Development
117
-
118
- ```bash
119
- # Install dependencies
120
- bun install
121
-
122
- # Build
123
- bun run build
124
-
125
- # Watch mode
126
- bun run dev
127
-
128
- # Type check
129
- bun run typecheck
130
-
131
- # Lint
132
- bun run lint
133
- ```
134
-
135
- ## Dependencies
136
-
137
- - `@pie-players/pie-assessment-toolkit` - Toolkit contexts and scoped tool ids
138
-
139
- ## License
140
-
141
- 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
+ }