@offorte/show-doc 0.0.2 → 0.0.4

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 (8) hide show
  1. package/README.md +82 -16
  2. package/custom-elements.json +90 -4
  3. package/dist/showdoc-mermaid.js +23739 -23987
  4. package/dist/showdoc.js +263 -578
  5. package/dist/types/components/shw-code.d.ts +19 -2
  6. package/dist/types/components/shw-collapsible.d.ts +7 -1
  7. package/package.json +2 -2
  8. package/skills/show-doc/SKILL.md +127 -36
package/dist/types/components/shw-code.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { LitElement } from "lit";
2
+ import "./shw-markdown";
2
3
  /**
3
- * Shows a syntax-highlighted code block with an optional filename.
4
+ * Shows code or a supplied unified diff, with optional source line numbers and notes.
4
5
  *
5
6
  * @element shw-code
6
7
  */
@@ -13,12 +14,28 @@ export declare class ShwCode extends LitElement {
13
14
  language: {
14
15
  type: StringConstructor;
15
16
  };
17
+ lineNumbers: {
18
+ type: BooleanConstructor;
19
+ attribute: string;
20
+ };
21
+ highlight: {
22
+ type: StringConstructor;
23
+ };
24
+ annotations: {
25
+ type: StringConstructor;
26
+ };
16
27
  };
17
28
  static styles: import("lit").CSSResult[];
18
29
  /** Optional filename shown above the code. */
19
30
  filename: string;
20
- /** Syntax language. Supported values are html, js, ts, and json. */
31
+ /** Syntax language: html, js, ts, json, or diff for a supplied unified diff. */
21
32
  language: string;
33
+ /** Show 1-based positions in the displayed source, including diff headers. */
34
+ lineNumbers: boolean;
35
+ /** Source lines to emphasize, for example 2,4-6. */
36
+ highlight: string;
37
+ /** JSON array of { start, end?, text } notes. Text is safe Markdown; lines are 1-based. */
38
+ annotations: string;
22
39
  protected render(): import("lit").TemplateResult<1>;
23
40
  }
24
41
  declare global {
package/dist/types/components/shw-collapsible.d.ts CHANGED
@@ -1,13 +1,17 @@
1
1
  import { LitElement } from "lit";
2
2
  import "./shw-markdown";
3
3
  /**
4
- * Hides optional Markdown details behind a native disclosure control.
4
+ * Hides optional Markdown or child document blocks behind a native disclosure control.
5
5
  *
6
6
  * @element shw-collapsible
7
+ * @slot - Document blocks when content="blocks".
7
8
  */
8
9
  export declare class ShwCollapsible extends LitElement {
9
10
  #private;
10
11
  static properties: {
12
+ content: {
13
+ type: StringConstructor;
14
+ };
11
15
  open: {
12
16
  type: BooleanConstructor;
13
17
  reflect: boolean;
@@ -21,6 +25,8 @@ export declare class ShwCollapsible extends LitElement {
21
25
  open: boolean;
22
26
  /** Label for the disclosure control. */
23
27
  summary: string;
28
+ /** Body input: Markdown text by default, or slotted document blocks. */
29
+ content: "markdown" | "blocks";
24
30
  protected render(): import("lit").TemplateResult<1>;
25
31
  }
26
32
  declare global {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@offorte/show-doc",
3
- "version": "0.0.2",
3
+ "version": "0.0.4",
4
4
  "description": "Agent skill and web components for polished, human-readable HTML documents.",
5
5
  "keywords": [
6
6
  "documentation",
@@ -57,7 +57,7 @@
57
57
  "access": "public"
58
58
  },
59
59
  "scripts": {
60
- "dev": "vite --host 127.0.0.1",
60
+ "dev": "vite --host 127.0.0.1 --open /demo/",
61
61
  "serve": "pnpm build && node scripts/prepare-preview.mjs && vite preview --host 127.0.0.1 --port 4173 --strictPort --outDir .preview",
62
62
  "build": "vite build && vite build --mode mermaid && tsc -p tsconfig.build.json",
63
63
  "check:build": "node scripts/check-build.mjs",
package/skills/show-doc/SKILL.md CHANGED
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  name: show-doc
3
- description: Create compact, readable standalone HTML documents with versioned Offorte ShowDoc components and Markdown when a human-facing artifact needs more visual structure than normal prose.
3
+ description: Create compact, readable standalone HTML documents with Offorte ShowDoc components and Markdown when a human-facing artifact needs more visual structure than normal prose.
4
4
  metadata:
5
- version: "0.0.2" # x-release-please-version
5
+ version: "0.0.4" # x-release-please-version
6
6
  ---
7
7
 
8
8
  # ShowDoc
@@ -13,10 +13,13 @@ chat Markdown. Do not use it for dashboards, forms, or application-like tools.
13
13
 
14
14
  ## Output contract
15
15
 
16
- Create one HTML file. Use this skill's exact `metadata.version` in the CDN URL. Use the complete
17
- starting point below when the document does not need Mermaid:
16
+ Create one HTML file. Use `@latest` in the CDN URL by default. This loads the latest published
17
+ release, so an existing document can receive runtime updates. If the user needs a fixed result,
18
+ use an exact published version instead. The skill's `metadata.version` identifies the skill
19
+ release; it does not select the default runtime version.
18
20
 
19
- <!-- x-release-please-start-version -->
21
+ Documents use light mode by default, regardless of the system theme. Use the complete starting
22
+ point below when the document does not need Mermaid:
20
23
 
21
24
  ```html
22
25
  <!doctype html>
@@ -26,20 +29,23 @@ starting point below when the document does not need Mermaid:
26
29
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
27
30
  <script
28
31
  type="module"
29
- src="https://cdn.jsdelivr.net/npm/@offorte/show-doc@0.0.2/dist/showdoc.js"
32
+ src="https://cdn.jsdelivr.net/npm/@offorte/show-doc@latest/dist/showdoc.js"
30
33
  ></script>
31
- <title>Release decision</title>
34
+ <title>Retry plan</title>
32
35
  </head>
33
36
  <body>
34
37
  <shw-doc>
35
- <shw-header heading="Release decision" eyebrow="Review">
36
- The current build passed all required checks.
38
+ <shw-header heading="A safer retry" eyebrow="Implementation plan">
39
+ Preserve the draft when a temporary connection error interrupts a save.
37
40
  </shw-header>
38
41
 
39
- <shw-summary>The release is **approved**. Complete these two steps.</shw-summary>
42
+ <shw-summary heading="Proposal">Keep the draft and let the user retry.</shw-summary>
40
43
 
41
44
  <shw-section heading="Next steps">
42
- <shw-steps> 1. Publish the package. 2. Confirm the production version. </shw-steps>
45
+ <shw-steps>
46
+ 1. Keep the current draft after a failed save. 2. Check that a successful retry saves it
47
+ once.
48
+ </shw-steps>
43
49
  </shw-section>
44
50
  </shw-doc>
45
51
  </body>
@@ -51,12 +57,10 @@ If the document uses Mermaid, replace the script in the starting point with the
51
57
  ```html
52
58
  <script
53
59
  type="module"
54
- src="https://cdn.jsdelivr.net/npm/@offorte/show-doc@0.0.2/dist/showdoc-mermaid.js"
60
+ src="https://cdn.jsdelivr.net/npm/@offorte/show-doc@latest/dist/showdoc-mermaid.js"
55
61
  ></script>
56
62
  ```
57
63
 
58
- <!-- x-release-please-end -->
59
-
60
64
  Use only one script. The Mermaid bundle contains all core components.
61
65
 
62
66
  Use normal document metadata. Wrap the visible document in one `shw-doc`. Do not add inline
@@ -68,27 +72,28 @@ available. Return the exact file path.
68
72
 
69
73
  ## Component chooser
70
74
 
71
- | Element | Compact API | Use |
72
- | ----------------- | ------------------------------------ | ------------------------------------------------ |
73
- | `shw-doc` | - | The one page canvas. |
74
- | `shw-header` | `heading`, `eyebrow?` | The one title and short Markdown lead. |
75
- | `shw-summary` | `heading?` | The answer before the evidence. |
76
- | `shw-section` | `heading?`, `intro?`, `level?` | A topic with an automatic divider. |
77
- | `shw-markdown` | - | Normal prose, lists, links, tasks, and headings. |
78
- | `shw-mermaid` | `label?` | A diagram from Mermaid source. |
79
- | `shw-grid` | `columns?` | Two to four sibling blocks to compare. |
80
- | `shw-card` | `heading?`, `label?`, `tone?` | One grouped idea, choice, or status. |
81
- | `shw-badge` | `tone?` | A short standalone state or category. |
82
- | `shw-callout` | `heading?`, `tone?` | One message that needs attention. |
83
- | `shw-stat` | `label`, `value`, `change?`, `tone?` | One prominent metric or result. |
84
- | `shw-steps` | - | A process from numbered Markdown lines. |
85
- | `shw-code` | `filename?`, `language?` | Highlighted HTML, JS, TS, or JSON. |
86
- | `shw-table` | `caption?` | Row and column data from pipe text. |
87
- | `shw-figure` | `caption?` | An image, inline SVG, or diagram. |
88
- | `shw-collapsible` | `summary?`, `open?` | Evidence or detail most readers can skip. |
75
+ | Element | Compact API | Use |
76
+ | ----------------- | ----------------------------------------------------------------------- | ------------------------------------------------ |
77
+ | `shw-doc` | - | The one page canvas. |
78
+ | `shw-header` | `heading`, `eyebrow?` | The one title and short Markdown lead. |
79
+ | `shw-summary` | `heading?` | The answer before the evidence. |
80
+ | `shw-section` | `heading?`, `intro?`, `level?` | A topic with an automatic divider. |
81
+ | `shw-markdown` | - | Normal prose, lists, links, tasks, and headings. |
82
+ | `shw-mermaid` | `label?` | A diagram from Mermaid source. |
83
+ | `shw-grid` | `columns?` | Two to four sibling blocks to compare. |
84
+ | `shw-card` | `heading?`, `label?`, `tone?` | One grouped idea, choice, or status. |
85
+ | `shw-badge` | `tone?` | A short standalone state or category. |
86
+ | `shw-callout` | `heading?`, `tone?` | One message that needs attention. |
87
+ | `shw-stat` | `label`, `value`, `change?`, `tone?` | One prominent metric or result. |
88
+ | `shw-steps` | - | A process from numbered Markdown lines. |
89
+ | `shw-code` | `filename?`, `language?`, `line-numbers?`, `highlight?`, `annotations?` | Code, supplied diffs, and notes tied to lines. |
90
+ | `shw-table` | `caption?` | Row and column data from pipe text. |
91
+ | `shw-figure` | `caption?` | An image, inline SVG, or diagram. |
92
+ | `shw-collapsible` | `summary?`, `open?`, `content?` | Optional Markdown or child document blocks. |
89
93
 
90
94
  Defaults reduce source. A summary heading is `Summary`. A section level is `2`. Grid columns are
91
- `2`. A collapsible summary is `Details`. Default tone is `neutral`, except callouts use `info`.
95
+ `2`. A collapsible summary is `Details`, and its content mode is `markdown`. Default tone is
96
+ `neutral`, except callouts use `info`.
92
97
 
93
98
  Tones are `info`, `success`, `warning`, `danger`, and `neutral`. Use them only when the meaning helps
94
99
  the reader.
@@ -99,8 +104,8 @@ the reader.
99
104
  - Start with `shw-header`. Add `shw-summary` when readers need the answer first.
100
105
  - Use Markdown for the story. Add a component only when it gives meaning or layout.
101
106
  - Use `shw-steps` for a simple sequence. Write each step as `1. ...`, `2. ...`, and so on.
102
- - Use `shw-code` without `language` for pseudocode, call trees, component trees, file trees, and
103
- structural diffs. Set `language` only for highlighted HTML, JS, TS, or JSON source.
107
+ - Use `shw-code` without `language` for pseudocode and structural trees. Use `html`, `js`, `ts`, or
108
+ `json` for syntax highlighting. Use `diff` for a supplied unified patch.
104
109
  - Use `shw-mermaid` when relationships, branches, data flow, or participant interactions matter.
105
110
  - Put two or three comparable cards or stats in `shw-grid`.
106
111
  - Use a table only for aligned data. Table body cells support Markdown.
@@ -110,10 +115,96 @@ the reader.
110
115
  Use more than one visual form only when each one answers a different question. Do not turn every
111
116
  paragraph into a card. Do not use a callout as decoration.
112
117
 
118
+ ## Give the document a visual rhythm
119
+
120
+ For a substantial document, choose a useful central visual: a comparison, a flow, a change excerpt,
121
+ or a small set of real metrics. Build the explanation around it. Alternate readable prose with
122
+ focused visuals and compact evidence instead of repeating the same grid of cards in every section.
123
+
124
+ - Use the header eyebrow for context and a short title for the main idea.
125
+ - Keep prose narrow. Give code, wide tables, and diagrams a full section when they need space.
126
+ - Use grids for comparable short items. Stack wide screenshots and long code excerpts.
127
+ - Label comparisons explicitly: current/proposed, before/after, or option names. Use the same
128
+ capture size and scale for screenshots. Keep unchanged context visible.
129
+ - Put the purpose of a code excerpt or diagram immediately above it. Use a figure caption for
130
+ the visual's scope, source, or limitation.
131
+ - Use the default theme and semantic tones. The components provide accent details and subtle
132
+ surface contrast. Do not invent metrics, statuses, icons, or decorative panels to fill space.
133
+
134
+ ## Plan and recap recipes
135
+
136
+ These are starting points. Omit sections that do not help with the actual task.
137
+
138
+ **Implementation plan:** Start with the proposed outcome and the reason. Show current/proposed
139
+ behavior with two cards in a grid, or use a Mermaid diagram for relationships. Use sections inside
140
+ a grid when each side needs several child components. Record the chosen direction separately from
141
+ open questions. Use steps for the work sequence; name the expected result and check for each step.
142
+ Put supporting source and rejected alternatives in disclosures.
143
+
144
+ **Change recap:** Start with what changed and who it affects. Show a small real diff or matched
145
+ before/after figures when comparison helps. Explain the important lines with a few annotations.
146
+ Use a table for checks, observed results, and remaining gaps. Keep blockers visible. Put long logs
147
+ and secondary evidence in disclosures.
148
+
149
+ Use source facts for filenames, code, fields, and results. Label proposals, inferred UI sketches,
150
+ and illustrative examples. Distinguish **implemented** from **verified**. Name which checks ran;
151
+ never turn a suggested check or an unchecked box into a passed result.
152
+
153
+ ## Rich expandable detail
154
+
155
+ Use `content="blocks"` to place other ShowDoc components inside a disclosure. Wrap prose in
156
+ `shw-markdown` in this mode. Keep Markdown text as the default for a simple note.
157
+
158
+ <!-- prettier-ignore -->
159
+ ```html
160
+ <shw-collapsible summary="Inspect the evidence" content="blocks">
161
+ <shw-code filename="save.ts" language="ts">await save(draft);</shw-code>
162
+ <shw-table caption="Verification record">
163
+ Check | Result
164
+ Retry after a failed save | Not run
165
+ </shw-table>
166
+ </shw-collapsible>
167
+ ```
168
+
169
+ ## Code changes and annotations
170
+
171
+ ShowDoc displays supplied source. It does not fetch files, compute a diff, or verify a claim.
172
+ Use `language="diff"` for unified diff text. Preserve its headers and `+`, `-`, and space prefixes.
173
+ Do not use a diff when a short after-only example explains the change better.
174
+
175
+ Use `line-numbers` when referring to code lines. `highlight="2,4-6"` emphasizes selected lines.
176
+ `annotations` is a JSON array with `start`, optional `end`, and Markdown `text`. Notes stay visible
177
+ below the code. Use a few notes to explain intent, consequences, or a subtle constraint.
178
+
179
+ All line references are **1-based positions in the displayed excerpt**, including diff headers.
180
+ They are not repository line numbers. Count after removing the outer blank lines and common
181
+ indentation. Invalid JSON or out-of-range references produce a visible authoring message; correct
182
+ that message before sharing the document.
183
+
184
+ <!-- prettier-ignore -->
185
+ ```html
186
+ <shw-code
187
+ filename="save.ts"
188
+ language="ts"
189
+ line-numbers
190
+ highlight="2"
191
+ annotations='[{"start":2,"text":"Keep the draft available until the save succeeds."}]'
192
+ >
193
+ async function saveDraft(draft) {
194
+ await save(draft);
195
+ clearDraft();
196
+ }
197
+ </shw-code>
198
+ ```
199
+
200
+ In single-quoted JSON attributes, encode an apostrophe as `&#39;`. Encode `&` as `&amp;` and literal
201
+ `<` as `&lt;`. Use JSON escapes for double quotes inside note text.
202
+
113
203
  ## Source rules
114
204
 
115
205
  Keep the HTML shallow. Markdown-rendering components read their text content. Do not nest a
116
- component inside their Markdown.
206
+ component inside their Markdown. Layout components and a collapsible with `content="blocks"`
207
+ accept child components.
117
208
 
118
209
  Blank lines create paragraphs. Task lists use `- [ ]` and `- [x]`. Strikethrough uses `~~text~~`.
119
210
  Start optional Markdown headings at `##`. `shw-header` already creates the single `h1`.