Skip to content

Commit b9b56c5

Browse files
b3008claude
b3008
and
claude
committed
Add DOM API documentation to all Storybook stories
Each element's story now documents its public methods, getters/setters, and custom events in the autodocs component description. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 0cb0e3f commit b9b56c5

53 files changed

Lines changed: 732 additions & 340 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎src/stories/AffectGrid.stories.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,33 @@ import { html } from "lit";
44
const meta = {
55
title: "Response Items/Affect Grid",
66
tags: ["autodocs"],
7+
parameters: {
8+
docs: {
9+
description: {
10+
component: [
11+
"A 2D grid for measuring affect along two dimensions (e.g., valence and arousal). Based on Russell, Weiss & Mendelsohn (1989).",
12+
"",
13+
"### DOM API",
14+
"",
15+
"```js",
16+
"const grid = document.querySelector('aa-affect-grid');",
17+
"```",
18+
"",
19+
"| Method / Property | Returns | Description |",
20+
"|---|---|---|",
21+
"| `grid.value` | `[number, number] \\| null` | Get or set the selected `[x, y]` coordinates |",
22+
"| `grid.x` | `number \\| null` | Get the selected x coordinate (horizontal axis) |",
23+
"| `grid.y` | `number \\| null` | Get the selected y coordinate (vertical axis) |",
24+
"",
25+
"### Events",
26+
"",
27+
"| Event | Description |",
28+
"|---|---|",
29+
"| `change` | Fired when a cell is selected |",
30+
].join("\n"),
31+
},
32+
},
33+
},
734
argTypes: {
835
rows: { control: { type: "number", min: 1, max: 20 } },
936
columns: { control: { type: "number", min: 1, max: 20 } },

‎src/stories/Checkboxes.stories.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,32 @@ import { html } from "lit";
44
const meta = {
55
title: "Response Items/Checkboxes",
66
tags: ["autodocs"],
7+
parameters: {
8+
docs: {
9+
description: {
10+
component: [
11+
"A multi-select checkbox group. Contains `<aa-choice-item>` children.",
12+
"",
13+
"### DOM API",
14+
"",
15+
"```js",
16+
"const checkboxes = document.querySelector('aa-checkboxes');",
17+
"```",
18+
"",
19+
"| Method / Property | Returns | Description |",
20+
"|---|---|---|",
21+
"| `checkboxes.value` | `(string \\| null)[]` | Array of checked values (`null` for unchecked items) |",
22+
"| `checkboxes.toJSON()` | `object` | JSON representation including child items |",
23+
"",
24+
"### Events",
25+
"",
26+
"| Event | Detail | Description |",
27+
"|---|---|---|",
28+
"| `change` | `{ value }` | Fired when any checkbox is toggled |",
29+
].join("\n"),
30+
},
31+
},
32+
},
733
argTypes: {
834
horizontal: { control: "boolean" },
935
},

‎src/stories/Choose.stories.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,30 @@ const meta = {
2323
render: () => html`${unsafeHTML(sourceCode)}`,
2424
parameters: {
2525
docs: {
26+
description: {
27+
component: [
28+
"Conditional branching element. Evaluates `<aa-when>` test expressions against session memory and instantiates the first matching branch, or `<aa-otherwise>` if none match.",
29+
"",
30+
"### DOM API",
31+
"",
32+
"```js",
33+
"const choose = document.querySelector('aa-choose');",
34+
"```",
35+
"",
36+
"| Method | Returns | Description |",
37+
"|---|---|---|",
38+
"| `choose.evaluate(element)` | `any` | Evaluates the `test` attribute of the given `<aa-when>` element |",
39+
"| `choose.evaluateTestExpression(expr)` | `any` | Evaluates a test expression string against session memory |",
40+
"| `choose.replaceExpressionIdentifiersWithValues(expr)` | `string` | Substitutes variable names in an expression with their values from memory |",
41+
"",
42+
"### Child Elements",
43+
"",
44+
"| Element | Attribute | Description |",
45+
"|---|---|---|",
46+
"| `<aa-when>` | `test` | JavaScript expression evaluated against session memory (e.g., `score >= 90`) |",
47+
"| `<aa-otherwise>` | — | Fallback branch if no `<aa-when>` matches |",
48+
].join("\n"),
49+
},
2650
source: { code: sourceCode, language: "html" },
2751
},
2852
},

‎src/stories/FunctionRandom.stories.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,22 @@ const meta = {
3030
},
3131
parameters: {
3232
docs: {
33+
description: {
34+
component: [
35+
"Generates a random integer between `min` and `max` (inclusive) and stores it in session memory. Removes itself from the DOM after generating (unless `debug` is set).",
36+
"",
37+
"### DOM API",
38+
"",
39+
"```js",
40+
"const fn = document.querySelector('aa-function-random');",
41+
"```",
42+
"",
43+
"| Method / Property | Returns | Description |",
44+
"|---|---|---|",
45+
"| `fn.value` | `number` | The generated random integer (read after element is connected) |",
46+
"| `fn.getRandomInt(min, max)` | `number` | Generate a random integer in `[min, max]` range |",
47+
].join("\n"),
48+
},
3349
source: {
3450
code: `<aa-function-random name="randomValue" min="1" max="100"></aa-function-random>`,
3551
language: "html",

‎src/stories/Label.stories.ts‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,24 @@ import { html } from "lit";
44
const meta = {
55
title: "UI/Label",
66
tags: ["autodocs"],
7+
parameters: {
8+
docs: {
9+
description: {
10+
component: [
11+
"A styled text label for displaying questions or instructions. Uses a `<slot>` to render its content.",
12+
"",
13+
"### DOM API",
14+
"",
15+
"This element is a pure display component with no custom methods or events. Set content via innerHTML:",
16+
"",
17+
"```js",
18+
"const label = document.querySelector('aa-label');",
19+
"label.innerHTML = 'New question text';",
20+
"```",
21+
].join("\n"),
22+
},
23+
},
24+
},
725
argTypes: {
826
text: { control: "text" },
927
},

‎src/stories/LikertScale.stories.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,32 @@ import { html } from "lit";
44
const meta = {
55
title: "Response Items/Likert Scale",
66
tags: ["autodocs"],
7+
parameters: {
8+
docs: {
9+
description: {
10+
component: [
11+
"A Likert rating scale with configurable number of items, labels, and numbering.",
12+
"",
13+
"### DOM API",
14+
"",
15+
"```js",
16+
"const scale = document.querySelector('aa-likert-scale');",
17+
"```",
18+
"",
19+
"| Method / Property | Returns | Description |",
20+
"|---|---|---|",
21+
"| `scale.value` | `string` | The currently selected radio value |",
22+
"| `scale.arrangeLabels()` | `void` | Re-renders and positions the scale labels |",
23+
"",
24+
"### Events",
25+
"",
26+
"| Event | Description |",
27+
"|---|---|",
28+
"| `change` | Fired when a radio option is selected |",
29+
].join("\n"),
30+
},
31+
},
32+
},
733
argTypes: {
834
items: { control: "number" },
935
startItem: { control: "number" },

‎src/stories/MultipleChoice.stories.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,33 @@ import { html } from "lit";
44
const meta = {
55
title: "Response Items/Multiple Choice",
66
tags: ["autodocs"],
7+
parameters: {
8+
docs: {
9+
description: {
10+
component: [
11+
"A single-select radio group. Contains `<aa-choice-item>` children.",
12+
"",
13+
"### DOM API",
14+
"",
15+
"```js",
16+
"const mc = document.querySelector('aa-multiple-choice');",
17+
"```",
18+
"",
19+
"| Method / Property | Returns | Description |",
20+
"|---|---|---|",
21+
"| `mc.value` | `string \\| undefined` | Get or set the selected value |",
22+
"| `mc.updateState(checkedNode)` | `void` | Update internal state when an item changes |",
23+
"| `mc.getValueOfSelectedItem()` | `string \\| undefined` | Returns the value of the currently selected item |",
24+
"",
25+
"### Events",
26+
"",
27+
"| Event | Detail | Description |",
28+
"|---|---|---|",
29+
"| `change` | `{ value }` | Fired when the selected item changes |",
30+
].join("\n"),
31+
},
32+
},
33+
},
734
argTypes: {
835
horizontal: { control: "boolean" },
936
},

‎src/stories/Screen.stories.ts‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,40 @@ import { html } from "lit";
44
const meta = {
55
title: "UI/Screen",
66
tags: ["autodocs"],
7+
parameters: {
8+
docs: {
9+
description: {
10+
component: [
11+
"A container that collects values from its child response items and provides a submit button.",
12+
"",
13+
"### DOM API",
14+
"",
15+
"```js",
16+
"const screen = document.querySelector('aa-screen');",
17+
"```",
18+
"",
19+
"| Method / Property | Returns | Description |",
20+
"|---|---|---|",
21+
"| `screen.value` | `Promise<AAScreenValue>` | Collects all child response values with metadata |",
22+
"| `screen.collectValues()` | `Promise<AAScreenValue>` | Explicitly collect all child values |",
23+
"| `screen.valueWithKey()` | `Promise<object>` | Returns values keyed by child element name |",
24+
"| `screen.hide()` | `void` | Hides the screen and stops child sequences |",
25+
"| `screen.show()` | `void` | Shows the screen |",
26+
"| `screen.automate()` | `void` | Auto-fills child inputs and triggers submit |",
27+
"| `screen.submitButtonClick()` | `Promise<void>` | Programmatically click the submit button |",
28+
"| `screen.hasChildrenThatRequireResponse()` | `Promise<Element[]>` | Returns required child elements that have no value |",
29+
"| `screen.getAAChildren(node)` | `Element[]` | Gets AA custom element children |",
30+
"",
31+
"### Events",
32+
"",
33+
"| Event | Detail | Description |",
34+
"|---|---|---|",
35+
"| `valueSubmit` | `AAScreenValueSubmitEventDetail` | Fired when the screen is submitted with collected values |",
36+
"| `endEvent` | — | Fired after submit completes |",
37+
].join("\n"),
38+
},
39+
},
40+
},
741
argTypes: {
842
submitButtonText: { control: "text" },
943
submitButtonHidden: { control: "boolean" },

‎src/stories/Sequence.stories.ts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,34 @@ const meta = {
2323
render: () => html`${unsafeHTML(defaultSource)}`,
2424
parameters: {
2525
docs: {
26+
description: {
27+
component: [
28+
"Steps through its children one at a time. Each child dispatches `endEvent` to advance to the next. Commonly wraps `<aa-screen>` elements.",
29+
"",
30+
"### DOM API",
31+
"",
32+
"```js",
33+
"const seq = document.querySelector('aa-sequence');",
34+
"```",
35+
"",
36+
"| Method | Returns | Description |",
37+
"|---|---|---|",
38+
"| `seq.init()` | `void` | Initialize the sequence (hides all children) |",
39+
"| `seq.start()` | `void` | Start the sequence from the first child |",
40+
"| `seq.stop()` | `void` | Stop the sequence |",
41+
"| `seq.next(name?)` | `Promise<void>` | Advance to the next child, or jump to a named child |",
42+
"",
43+
"### Events",
44+
"",
45+
"| Event | Description |",
46+
"|---|---|",
47+
"| `endEvent` | Fired when the sequence completes (all children done) |",
48+
"",
49+
"### Related: `<aa-jump>`",
50+
"",
51+
"Use `<aa-jump goto=\"stepName\">` inside a sequence to jump to a named child element.",
52+
].join("\n"),
53+
},
2654
source: { code: defaultSource, language: "html" },
2755
},
2856
},

‎src/stories/Session.stories.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,37 @@ const meta = {
2626
render: () => html`${unsafeHTML(sourceCode)}`,
2727
parameters: {
2828
docs: {
29+
description: {
30+
component: [
31+
"The top-level container for an assessment. Manages session identity, memory, and data collection. Wraps its content in a `<template>` that is cloned and instantiated on `run()`.",
32+
"",
33+
"### DOM API",
34+
"",
35+
"```js",
36+
"const session = document.querySelector('aa-session');",
37+
"```",
38+
"",
39+
"| Method / Property | Returns | Description |",
40+
"|---|---|---|",
41+
"| `session.run()` | `void` | Clone the template and attach children to begin the session |",
42+
"| `session.getData(name)` | `any` | Retrieve a value from session memory |",
43+
"| `session.setData(name, value)` | `void` | Store a value in session memory |",
44+
"| `session.getDataDump()` | `Storage` | Return all data stored in session memory |",
45+
"| `session.originalChildNodes` | `NodeList` | Access the original template children |",
46+
"| `session.sessionId` | `string` | UUID identifying this session instance |",
47+
"| `session.sessionTime` | `number` | Timestamp (ms) when the session started |",
48+
"| `session.toJSON()` | `object` | JSON representation of the session and its template |",
49+
"| `session.toJSL()` | `string` | JSL (JavaScript Literal) representation |",
50+
"",
51+
"### Events",
52+
"",
53+
"| Event | Detail | Description |",
54+
"|---|---|---|",
55+
"| `sessionReady` | — | Fired when the session has initialized |",
56+
"| `sessionInputSubmit` | `{ input: AASessionInput }` | Fired on each screen submission with session-level metadata |",
57+
"| `sessionEndEvent` | `'sessionEnd'` | Fired when the session completes |",
58+
].join("\n"),
59+
},
2960
source: { code: sourceCode, language: "html" },
3061
},
3162
},

0 commit comments

Comments
 (0)