@allons-y/webc-code-sample 0.1.0-beta.1 → 0.1.0-beta.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 (3) hide show
  1. package/README.md +19 -14
  2. package/llms.txt +70 -0
  3. package/package.json +7 -6
package/README.md CHANGED
@@ -1,9 +1,11 @@
1
1
  # @allons-y/webc-code-sample
2
2
 
3
- Part of [Norn](https://github.com/allonsy-studio/webc-resources#readme). `norn-code-block` WebC component with build-time syntax highlighting. Shiki runs at build; the browser receives token ranges for the CSS Custom Highlight API and a copy button, with no highlighter shipped.
3
+ Part of [Norn](https://github.com/allonsy-studio/webc-resources#readme). `norn-code-block` WebC component with build-time syntax highlighting. Shiki runs at build; the browser receives token ranges for the CSS Custom Highlight API & a copy button, with no highlighter shipped.
4
4
 
5
5
  See it in the [component preview](https://allonsy-studio.github.io/webc-resources/).
6
6
 
7
+ Using an AI coding agent? Point it at [`llms.txt`](llms.txt): the rules for calling & styling the components, & a reference of every prop, slot, & token.
8
+
7
9
  ## Status
8
10
 
9
11
  Beta. Versions are `0.1.0-beta.N` until 1.0.
@@ -16,11 +18,11 @@ npm install --save-dev @11ty/eleventy @11ty/eleventy-plugin-webc @allons-y/webc-
16
18
 
17
19
  Node 22 or later. Evergreen browsers from about 2024. Features newer than that, such as the CSS Custom Highlight API, degrade gracefully: the code stays readable plain text.
18
20
 
19
- The package registers nothing itself. It is an optional peer dependency of `@allons-y/webc-patterns`: with it installed, the Norn plugin registers `norn-code-block`, the `nornTokenRanges` helper, and the Markdown add-on, and the Norn layouts show their samples with it. The copy button is the patterns package's `norn-copy-button`.
21
+ The package registers nothing itself. It is an optional peer dependency of `@allons-y/webc-patterns`: with it installed, the Norn plugin registers `norn-code-block`, the `nornTokenRanges` helper, & the Markdown add-on, & the Norn layouts show their samples with it. The copy button is the patterns package's `norn-copy-button`.
20
22
 
21
23
  ## Usage
22
24
 
23
- Install it beside the patterns package and add the Norn plugin (or a theme that adds it, such as `@allons-y/webc-oss-site`). There is nothing else to register:
25
+ Install it beside the patterns package & add the Norn plugin (or a theme that adds it, such as `@allons-y/webc-oss-site`). There is nothing else to register:
24
26
 
25
27
  ```js
26
28
  import norn from "@allons-y/webc-patterns/plugin";
@@ -32,7 +34,7 @@ export default function (config) {
32
34
  }
33
35
  ```
34
36
 
35
- Without the Norn plugin, add `codeBlock` to the project's own WebC `components` list beside `patterns()` from `@allons-y/webc-patterns`, and register `tokenRanges` as `nornTokenRanges`. Without `patterns()` in the list, `norn-copy-button` is an unknown tag and the code blocks render with no copy button and no error.
37
+ Without the Norn plugin, add `codeBlock` to the project's own WebC `components` list beside `patterns()` from `@allons-y/webc-patterns`, & register `tokenRanges` as `nornTokenRanges`. Without `patterns()` in the list, `norn-copy-button` is an unknown tag & the code blocks render with no copy button & no error.
36
38
 
37
39
  Call the component from a WebC page. Props take the `@` prefix:
38
40
 
@@ -50,11 +52,11 @@ import { highlightFences } from "@allons-y/webc-code-sample/markdown";
50
52
  config.amendLibrary("md", highlightFences);
51
53
  ```
52
54
 
53
- Each fence renders as the `<norn-code-block>` an author would write, with the fence's first word as `@language`. The add-on fills no slots, so the labels and button texts come from the component's fallbacks, as in Translating below. The fence's tag is compiled by WebC, so the page's layout renders the Markdown content with `@html="content"`. Every Norn layout does, and `norn-base` does for a Markdown page that uses it directly.
55
+ Each fence renders as the `<norn-code-block>` an author would write, with the fence's first word as `@language`. The add-on fills no slots, so the labels & button texts come from the component's fallbacks, as in Translating below. The fence's tag is compiled by WebC, so the page's layout renders the Markdown content with `@html="content"`. Every Norn layout does, & `norn-base` does for a Markdown page that uses it directly.
54
56
 
55
57
  ### Translating
56
58
 
57
- Every string a visitor sees or hears is content in the page, in a named slot, hidden until the script uses it: slot `label` names the code when there is no caption, `copy-label` names the copy button (`{name}` stands in for the code's name, filled in by the script), and `copy`, `copied`, and `failed` are the button's texts:
59
+ Every string a visitor sees or hears is content in the page, in a named slot, hidden until the script uses it: slot `label` names the code when there is no caption, `copy-label` names the copy button (`{name}` stands in for the code's name, filled in by the script), & `copy`, `copied`, & `failed` are the button's texts:
58
60
 
59
61
  ```html
60
62
  <norn-code-block @language="sh" @code="npm install">
@@ -64,13 +66,13 @@ Every string a visitor sees or hears is content in the page, in a named slot, hi
64
66
  </norn-code-block>
65
67
  ```
66
68
 
67
- An empty slot falls back to the site's strings from the patterns package's `componentStrings`, under `norn-code-block` (`label`, with `{language}` for the language, and `copy-label`) and `norn-copy-button` (`copy`, `copied`, `failed`), then to English. That covers Markdown fences too: `highlightFences` writes no slots of its own.
69
+ An empty slot falls back to the site's strings from the patterns package's `componentStrings`, under `norn-code-block` (`label`, with `{language}` for the language, & `copy-label`) & `norn-copy-button` (`copy`, `copied`, `failed`), then to English. That covers Markdown fences too: `highlightFences` writes no slots of its own.
68
70
 
69
71
  ### Layout requirements
70
72
 
71
73
  The Norn layouts meet these. A layout of the project's own:
72
74
 
73
- - Links the page's bundles from the layout head, with `webc:keep` on both tags. WebC removes `<link>` and `<script src>` without it. `norn-head` does this.
75
+ - Links the page's bundles from the layout head, with `webc:keep` on both tags. WebC removes `<link>` & `<script src>` without it. `norn-head` does this.
74
76
 
75
77
  ```html
76
78
  <link rel="stylesheet" :href="getBundleFileUrl('css')" webc:keep />
@@ -78,11 +80,11 @@ The Norn layouts meet these. A layout of the project's own:
78
80
  ```
79
81
 
80
82
  - Sets `markdownTemplateEngine: false`, or the default Liquid pass rewrites `{{ }}` inside fences.
81
- - Drops the `href=""` and `src=""` tags a page with no bundles is left with: `webc:if` can't guard them, because the URL resolves after render. The Norn plugin registers `dropEmptyBundleTags` from the patterns package as a transform for this.
83
+ - Drops the `href=""` & `src=""` tags a page with no bundles is left with: `webc:if` can't guard them, because the URL resolves after render. The Norn plugin registers `dropEmptyBundleTags` from the patterns package as a transform for this.
82
84
 
83
85
  ### Without JavaScript
84
86
 
85
- The code stays readable plain text, and is not a tab stop: the script makes it a named, focusable region only while it scrolls sideways. The highlight colors need the CSS Custom Highlight API and a script. The copy button is an icon over the top end corner of the code, which names itself when the pointer or focus is on it, and needs a script and the Clipboard API, which browsers expose only on secure origins (HTTPS or localhost): elsewhere it stays hidden. The code always reads left to right, in a right-to-left page too. The script registers `norn-code-block` as a custom element, so a sample added to the page later is enhanced too.
87
+ The code stays readable plain text, & is not a tab stop: the script makes it a named, focusable region only while it scrolls sideways. The highlight colors need the CSS Custom Highlight API & a script. The copy button is an icon over the top end corner of the code, which names itself when the pointer or focus is on it, & needs a script & the Clipboard API, which browsers expose only on secure origins (HTTPS or localhost): elsewhere it stays hidden. The code always reads left to right, in a right-to-left page too. The script registers `norn-code-block` as a custom element, so a sample added to the page later is enhanced too.
86
88
 
87
89
  ### Customizing
88
90
 
@@ -96,8 +98,8 @@ The sample reads shared tokens only, each falling back to its default compiled i
96
98
 
97
99
  | Token | Controls |
98
100
  | --- | --- |
99
- | `--norn-surface-code`, `--norn-text-base` | Surface and text colors |
100
- | `--norn-ui-border-radius`, `--norn-space-m` | Corner radius and inner spacing |
101
+ | `--norn-surface-code`, `--norn-text-base` | Surface & text colors |
102
+ | `--norn-ui-border-radius`, `--norn-space-m` | Corner radius & inner spacing |
101
103
  | `--norn-font-mono` | Font stack |
102
104
  | `--norn-code-comment`, `--norn-code-string`, `--norn-code-keyword`, `--norn-code-function`, `--norn-code-number`, `--norn-code-flag` | Syntax colors |
103
105
 
@@ -106,7 +108,7 @@ The sample reads shared tokens only, each falling back to its default compiled i
106
108
  | Export | Purpose |
107
109
  | --- | --- |
108
110
  | `codeBlock` | Absolute path to `components/norn-code-block.webc` |
109
- | `tokenRanges(code, language)` | Shiki tokens as the compact JSON that `data-tokens` carries, or undefined with no tokens: `[groups, numbers]`, the group names once each, then three whole numbers per range, the group's index in `groups`, the gap from the end of the range before (from 0 for the first), and the length: `[["keyword","string"],[0,0,5,1,3,4]]` is `keyword` from 0 to 5 and `string` from 8 to 12. The ranges are character offsets in order, and none overlaps the next. The groups are `comment`, `string`, `keyword`, `function`, `number`, `flag`, and `punctuation`. For `sh`, `bash`, `shell`, and `shell-session`, the command is a `function`, its subcommand a `keyword`, a flag a `flag`, and an argument a `string`. The plugin registers it as `nornTokenRanges` |
111
+ | `tokenRanges(code, language)` | Shiki tokens as the compact JSON that `data-tokens` carries, or undefined with no tokens: `[groups, numbers]`, the group names once each, then three whole numbers per range, the group's index in `groups`, the gap from the end of the range before (from 0 for the first), & the length: `[["keyword","string"],[0,0,5,1,3,4]]` is `keyword` from 0 to 5 & `string` from 8 to 12. The ranges are character offsets in order, & none overlaps the next. The groups are `comment`, `string`, `keyword`, `function`, `number`, `flag`, & `punctuation`. For `sh`, `bash`, `shell`, & `shell-session`, the command is a `function`, its subcommand a `keyword`, a flag a `flag`, & an argument a `string`. The plugin registers it as `nornTokenRanges` |
110
112
  | `decodeRanges(value)` | Reads a `tokenRanges` string back into `[group, start, end][]` character offsets. Undefined reads as `[]`; any other value that is not the compact form throws a `TypeError` that says what is wrong |
111
113
  | `loadLanguages(...languages)` | Adds Shiki language registrations beyond the defaults (`bash`, `css`, `diff`, `html`, `javascript`, `json`, `markdown`, `typescript`, `yaml`), such as `import rust from "@shikijs/langs/rust"`. Call it once, before the build highlights code |
112
114
 
@@ -114,7 +116,10 @@ The sample reads shared tokens only, each falling back to its default compiled i
114
116
 
115
117
  ## License
116
118
 
117
- [MPL-2.0](LICENSE): use freely, modify as needed; changes to MPL-licensed files should be shared back under the same license.
119
+ > [MPL-2.0](LICENSE): use freely, modify as needed; changes to MPL-licensed files
120
+ > should be shared back under the same license.
121
+
122
+ ---
118
123
 
119
124
  <p align="center">
120
125
  <a href="https://allons-y.studio">
package/llms.txt ADDED
@@ -0,0 +1,70 @@
1
+ # @allons-y/webc-code-sample
2
+
3
+ > `norn-code-block`: a WebC code sample highlighted at build time. Shiki runs during the build. The browser gets token ranges for the CSS Custom Highlight API and a copy button, and no highlighter. The reference at the end is generated from the component source.
4
+
5
+ ## What you are working with
6
+
7
+ - One component, `norn-code-block`, and one Markdown add-on, `highlightFences`.
8
+ - It is an optional peer of `@allons-y/webc-patterns`. Installed beside it, the Norn plugin registers the component, the `nornTokenRanges` helper, and the add-on, and the Norn layouts show their code with it. Without it, the plugin registers a plain `norn-code-block` that renders `<pre><code>`, so every call site works either way.
9
+ - It registers nothing itself. Do not add it to a project's WebC `components` list when the Norn plugin is in use.
10
+
11
+ ## Use it
12
+
13
+ ```html
14
+ <norn-code-block @language="js" @caption="example.js" @code="const answer = 42;"></norn-code-block>
15
+ ```
16
+
17
+ - Props take the `@` prefix. `@code` is required and holds the code as a string. `@language`, `@caption`, and `@chrome` are optional. The component has no default slot for code.
18
+ - In Markdown, a fenced block becomes a `norn-code-block` with the fence's first word as `@language`. Write fences as normal.
19
+ - Every visitor-facing text is a named slot: `label` (names the code when there is no caption), `copy-label` (names the button; `{name}` stands for the code's name), `copy`, `copied`, `failed`. An empty slot falls back to the site's `componentStrings`, then English.
20
+
21
+ ```html
22
+ <norn-code-block @language="sh" @code="npm install">
23
+ <span slot="label">Commande d'installation</span>
24
+ <span slot="copy">Copier</span>
25
+ </norn-code-block>
26
+ ```
27
+
28
+ ## Rules
29
+
30
+ - An unknown or empty language renders plain, readable text with no highlighting. Use `loadLanguages` from the package to register more Shiki languages at build time.
31
+ - Theme the colors with the shared tokens (`--norn-code-keyword`, `--norn-code-string`, `--norn-code-flag`, and the rest of the `code` group) in the project's own stylesheet. The component has no custom property of its own.
32
+ - `@chrome="terminal"` frames the code with a flat header bar for the caption. It is a prop, not a custom property.
33
+ - `data-tokens` is an implementation detail: a compact group table plus integer triples. Read it with `decodeRanges` if you must. Do not write it by hand.
34
+ - Highlighting needs the CSS Custom Highlight API. A browser without it shows the code as plain text.
35
+
36
+ ## Where to look next
37
+
38
+ - README: install, usage without the Norn plugin, translating, layout requirements.
39
+ - Component preview: https://allonsy-studio.github.io/webc-resources/
40
+
41
+ ## Reference
42
+
43
+ Generated from the component sources and their CSF files. Do not edit by hand: run `yarn llms`.
44
+
45
+ ### Component components
46
+
47
+ A self-contained element: a link, a code block, a lockup.
48
+
49
+ #### norn-code-block
50
+
51
+ Tag: `<norn-code-block>`.
52
+
53
+ Code sample tokenized at build time. Its script registers `norn-code-block` as a custom element that adds the highlight colors; without the script the markup is the whole sample. A compact `norn-copy-button` from `@allons-y/webc-patterns` sits over the top end corner of the code, as its icon until the pointer or focus is on it, and copies the code without any leading `$ ` prompts. While the button shows, the code scrolls in an area that stops short of it, so no code runs beneath it. A caption, when there is one, sits above the code. The code reads left to right in any page direction. While the code scrolls sideways, the script makes it a tab stop, so a keyboard can scroll it. Shell samples (`sh`, `bash`, `shell`, `shell-session`) color the command, its subcommand, its flags, and its arguments apart. Needs `tokenRanges` registered as the `nornTokenRanges` JavaScript function, and the patterns package's components. The names and the copy button's texts are in the page, hidden: the script names the code while it scrolls, and shows the button. Each falls back to the site's `componentStrings`, under `norn-code-block` for `label` and `copy-label` and under `norn-copy-button` for the rest, then English.
54
+
55
+ Props:
56
+
57
+ - `code` (string, required): The code to show.
58
+ - `language` (string, optional): A language Shiki has loaded: the defaults or one added with `loadLanguages`. Unknown or empty renders plain text.
59
+ - `caption` (string, optional): Also names the code and its copy button.
60
+ - `chrome` (string, optional, one of `terminal`): `terminal` frames the code with a header bar for the caption. Without it the code sits on its surface with the caption above.
61
+
62
+ Slots:
63
+
64
+ - `label`: The code's name without a caption, as one element. Falls back to "{language} code", with the language filled in, or "code" with no language.
65
+ - `copy-label`: The copy button's name, with `{name}` for the code's name, as one element. Falls back to "Copy {name} to clipboard".
66
+ - `copy`: The copy button's text. Falls back to "Copy".
67
+ - `copied`: The copy button's text after a copy. Falls back to "Copied".
68
+ - `failed`: The copy button's text when the copy fails. Falls back to "Copy failed".
69
+
70
+ Global tokens it reads: `--norn-ui-border-radius`, `--norn-ui-icon-s`, `--norn-surface-raised`, `--norn-surface-code`, `--norn-text-base`, `--norn-text-muted`, `--norn-font-mono`, `--norn-font-size-s`, `--norn-code-comment`, `--norn-code-string`, `--norn-code-keyword`, `--norn-code-function`, `--norn-code-number`, `--norn-code-flag`, `--norn-space-2xs`, `--norn-space-xs`, `--norn-space-s`, `--norn-space-m`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@allons-y/webc-code-sample",
3
- "version": "0.1.0-beta.1",
3
+ "version": "0.1.0-beta.4",
4
4
  "description": "WebC code sample component with build-time syntax highlighting and no highlighter shipped to the browser.",
5
5
  "license": "MPL-2.0",
6
6
  "author": "Cassondra Roberts <castastrophe@users.noreply.github.com> (https://allons-y.studio)",
@@ -29,13 +29,14 @@
29
29
  "markdown.js",
30
30
  "tokenize.js",
31
31
  "LICENSE",
32
- "README.md"
32
+ "README.md",
33
+ "llms.txt"
33
34
  ],
34
35
  "scripts": {
35
36
  "prepack": "node ../../scripts/build-components.js webc-code-sample"
36
37
  },
37
38
  "devDependencies": {
38
- "markdown-it": "^15.0.2"
39
+ "markdown-it": "^15.0.3"
39
40
  },
40
41
  "peerDependencies": {
41
42
  "@11ty/eleventy": "^3.0.0",
@@ -48,10 +49,10 @@
48
49
  "11ty"
49
50
  ],
50
51
  "engines": {
51
- "node": ">=22"
52
+ "node": ">=24"
52
53
  },
53
54
  "dependencies": {
54
- "@shikijs/langs": "^4.5.0",
55
- "shiki": "^4.5.0"
55
+ "@shikijs/langs": "^4.6.0",
56
+ "shiki": "^4.6.0"
56
57
  }
57
58
  }