@f-ewald/components 1.40.3 → 1.42.2

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 (100) hide show
  1. package/README.md +14 -4
  2. package/custom-elements.json +2017 -131
  3. package/dist/app-shell.js +1 -1
  4. package/dist/app-shell.js.map +1 -1
  5. package/dist/blink-cursor.d.ts +27 -0
  6. package/dist/blink-cursor.d.ts.map +1 -0
  7. package/dist/blink-cursor.js +78 -0
  8. package/dist/blink-cursor.js.map +1 -0
  9. package/dist/code-diff.d.ts +41 -0
  10. package/dist/code-diff.d.ts.map +1 -0
  11. package/dist/code-diff.js +161 -0
  12. package/dist/code-diff.js.map +1 -0
  13. package/dist/comment-label.d.ts +26 -0
  14. package/dist/comment-label.d.ts.map +1 -0
  15. package/dist/comment-label.js +81 -0
  16. package/dist/comment-label.js.map +1 -0
  17. package/dist/confirm-dialog.d.ts +12 -6
  18. package/dist/confirm-dialog.d.ts.map +1 -1
  19. package/dist/confirm-dialog.js +50 -88
  20. package/dist/confirm-dialog.js.map +1 -1
  21. package/dist/dag-graph.d.ts +161 -0
  22. package/dist/dag-graph.d.ts.map +1 -0
  23. package/dist/dag-graph.js +724 -0
  24. package/dist/dag-graph.js.map +1 -0
  25. package/dist/icons.d.ts +16 -0
  26. package/dist/icons.d.ts.map +1 -1
  27. package/dist/icons.js +16 -0
  28. package/dist/icons.js.map +1 -1
  29. package/dist/index.d.ts +9 -1
  30. package/dist/index.d.ts.map +1 -1
  31. package/dist/index.js +9 -1
  32. package/dist/index.js.map +1 -1
  33. package/dist/mcp-server.js +1 -1
  34. package/dist/mcp-server.js.map +1 -1
  35. package/dist/modal-dialog.d.ts +16 -13
  36. package/dist/modal-dialog.d.ts.map +1 -1
  37. package/dist/modal-dialog.js +69 -104
  38. package/dist/modal-dialog.js.map +1 -1
  39. package/dist/photo-gallery.js +1 -1
  40. package/dist/photo-gallery.js.map +1 -1
  41. package/dist/price-history-chart.js +1 -1
  42. package/dist/price-history-chart.js.map +1 -1
  43. package/dist/progress-bar.d.ts.map +1 -1
  44. package/dist/progress-bar.js +23 -17
  45. package/dist/progress-bar.js.map +1 -1
  46. package/dist/slide-panel.d.ts +3 -3
  47. package/dist/slide-panel.d.ts.map +1 -1
  48. package/dist/slide-panel.js +38 -22
  49. package/dist/slide-panel.js.map +1 -1
  50. package/dist/stat-strip.d.ts +30 -0
  51. package/dist/stat-strip.d.ts.map +1 -0
  52. package/dist/stat-strip.js +111 -0
  53. package/dist/stat-strip.js.map +1 -0
  54. package/dist/step-ladder.d.ts +46 -0
  55. package/dist/step-ladder.d.ts.map +1 -0
  56. package/dist/step-ladder.js +175 -0
  57. package/dist/step-ladder.js.map +1 -0
  58. package/dist/terminal-block.d.ts +45 -0
  59. package/dist/terminal-block.d.ts.map +1 -0
  60. package/dist/terminal-block.js +113 -0
  61. package/dist/terminal-block.js.map +1 -0
  62. package/dist/toast-notification.d.ts +7 -0
  63. package/dist/toast-notification.d.ts.map +1 -1
  64. package/dist/toast-notification.js +34 -0
  65. package/dist/toast-notification.js.map +1 -1
  66. package/dist/tokens.css +64 -1
  67. package/dist/tokens.d.ts +58 -0
  68. package/dist/tokens.d.ts.map +1 -1
  69. package/dist/tokens.js +145 -0
  70. package/dist/tokens.js.map +1 -1
  71. package/dist/ui-button.js +2 -2
  72. package/dist/ui-button.js.map +1 -1
  73. package/dist/utils/dag-layout.d.ts +60 -0
  74. package/dist/utils/dag-layout.d.ts.map +1 -0
  75. package/dist/utils/dag-layout.js +80 -0
  76. package/dist/utils/dag-layout.js.map +1 -0
  77. package/dist/window-chrome.d.ts +34 -0
  78. package/dist/window-chrome.d.ts.map +1 -0
  79. package/dist/window-chrome.js +141 -0
  80. package/dist/window-chrome.js.map +1 -0
  81. package/docs/app-shell.md +1 -1
  82. package/docs/blink-cursor.md +45 -0
  83. package/docs/code-diff.md +64 -0
  84. package/docs/comment-label.md +49 -0
  85. package/docs/confirm-dialog.md +4 -3
  86. package/docs/dag-graph.md +101 -0
  87. package/docs/design-language.md +43 -21
  88. package/docs/icons.md +8 -0
  89. package/docs/layouts/marketing-landing.md +102 -0
  90. package/docs/modal-dialog.md +9 -9
  91. package/docs/photo-gallery.md +1 -1
  92. package/docs/price-history-chart.md +1 -0
  93. package/docs/slide-panel.md +2 -2
  94. package/docs/stat-strip.md +57 -0
  95. package/docs/step-ladder.md +63 -0
  96. package/docs/terminal-block.md +69 -0
  97. package/docs/ui-button.md +2 -0
  98. package/docs/window-chrome.md +64 -0
  99. package/llms.txt +282 -18
  100. package/package.json +2 -1
@@ -0,0 +1,141 @@
1
+ var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
2
+ var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
3
+ if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
4
+ else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
5
+ return c > 3 && r && Object.defineProperty(target, key, r), r;
6
+ };
7
+ import { LitElement, css, html, nothing } from "lit";
8
+ import { customElement, property } from "lit/decorators.js";
9
+ import { tokens } from "./tokens.js";
10
+ /**
11
+ * Sticky editor/terminal-style chrome bar for the top edge of a page or panel:
12
+ * three decorative traffic-light dots, a filename-style label, and a
13
+ * right-aligned actions slot for controls such as a theme toggle.
14
+ *
15
+ * The text property is named `label` rather than `title`, matching
16
+ * `page-header`'s text-property precedent and avoiding confusion with the
17
+ * global HTML `title` tooltip attribute. The dots are purely decorative, are
18
+ * hidden from assistive technology, and reuse the semantic `--ui-danger`,
19
+ * `--ui-warning`, and `--ui-success` tokens rather than introducing
20
+ * chrome-only colors.
21
+ *
22
+ * It sticks with `position: sticky; top: 0`, so callers must place it at the
23
+ * top of the element that actually scrolls. Its `z-index: 1` is a deliberate
24
+ * plain literal: just enough to keep the bar above in-flow content as it
25
+ * sticks, while staying far below the shared overlay stack (dialogs/popovers
26
+ * start at 100), so it does not participate in `utils/layer-stack.ts`.
27
+ *
28
+ * @element window-chrome
29
+ * @slot actions - Optional right-aligned controls such as theme or view toggles.
30
+ */
31
+ let WindowChrome = class WindowChrome extends LitElement {
32
+ constructor() {
33
+ super(...arguments);
34
+ /** Filename-style text shown beside the decorative dots. */
35
+ this.label = "";
36
+ }
37
+ static { this.styles = [
38
+ tokens,
39
+ css `
40
+ :host {
41
+ display: block;
42
+ position: sticky;
43
+ top: 0;
44
+ z-index: 1;
45
+ box-sizing: border-box;
46
+ border-bottom: var(--ui-border-width, 1px) solid var(--ui-border, #e2e8f0);
47
+ background: var(--ui-surface-muted, #f8fafc);
48
+ font-family: var(
49
+ --ui-font,
50
+ ui-sans-serif,
51
+ system-ui,
52
+ sans-serif,
53
+ "Apple Color Emoji",
54
+ "Segoe UI Emoji",
55
+ "Segoe UI Symbol",
56
+ "Noto Color Emoji"
57
+ );
58
+ }
59
+ .chrome {
60
+ display: flex;
61
+ align-items: center;
62
+ gap: 0.5rem;
63
+ min-width: 0;
64
+ padding: 0.5rem 0.75rem;
65
+ }
66
+ .leading {
67
+ display: flex;
68
+ align-items: center;
69
+ gap: 0.5rem;
70
+ min-width: 0;
71
+ flex: 1 1 auto;
72
+ }
73
+ .dots {
74
+ display: inline-flex;
75
+ align-items: center;
76
+ gap: 0.25rem;
77
+ flex: 0 0 auto;
78
+ }
79
+ .dot {
80
+ width: 0.75rem;
81
+ height: 0.75rem;
82
+ border-radius: var(--ui-radius-circle, 50%);
83
+ flex: 0 0 auto;
84
+ }
85
+ .dot.danger {
86
+ background: var(--ui-danger, #dc2626);
87
+ }
88
+ .dot.warning {
89
+ background: var(--ui-warning, #d97706);
90
+ }
91
+ .dot.success {
92
+ background: var(--ui-success, #16a34a);
93
+ }
94
+ .label {
95
+ min-width: 0;
96
+ overflow: hidden;
97
+ text-overflow: ellipsis;
98
+ white-space: nowrap;
99
+ font-family: var(--ui-font-mono, ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace);
100
+ font-size: var(--ui-font-size-sm, 0.75rem);
101
+ font-weight: var(--ui-font-weight-regular, 400);
102
+ line-height: var(--ui-line-height-tight, 1.25);
103
+ color: var(--ui-text-muted, #64748b);
104
+ }
105
+ .actions {
106
+ display: flex;
107
+ align-items: center;
108
+ margin-left: auto;
109
+ flex: 0 0 auto;
110
+ }
111
+ @media (forced-colors: active) {
112
+ :host {
113
+ border-bottom-color: CanvasText;
114
+ }
115
+ }
116
+ `,
117
+ ]; }
118
+ render() {
119
+ return html `
120
+ <div class="chrome">
121
+ <div class="leading">
122
+ <span class="dots" aria-hidden="true">
123
+ <span class="dot danger"></span>
124
+ <span class="dot warning"></span>
125
+ <span class="dot success"></span>
126
+ </span>
127
+ ${this.label ? html `<span class="label">${this.label}</span>` : nothing}
128
+ </div>
129
+ <div class="actions"><slot name="actions"></slot></div>
130
+ </div>
131
+ `;
132
+ }
133
+ };
134
+ __decorate([
135
+ property()
136
+ ], WindowChrome.prototype, "label", void 0);
137
+ WindowChrome = __decorate([
138
+ customElement("window-chrome")
139
+ ], WindowChrome);
140
+ export { WindowChrome };
141
+ //# sourceMappingURL=window-chrome.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"window-chrome.js","sourceRoot":"","sources":["../src/window-chrome.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;GAoBG;AAEI,IAAM,YAAY,GAAlB,MAAM,YAAa,SAAQ,UAAU;IAArC;;QACL,4DAA4D;QAChD,UAAK,GAAG,EAAE,CAAC;IAmGzB,CAAC;aAjGiB,WAAM,GAAG;QACvB,MAAM;QACN,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA6EF;KACF,AAhFqB,CAgFpB;IAEO,MAAM;QACb,OAAO,IAAI,CAAA;;;;;;;;YAQH,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAA,uBAAuB,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO;;;;KAI5E,CAAC;IACJ,CAAC;CACF,CAAA;AAnGa;IAAX,QAAQ,EAAE;2CAAY;AAFZ,YAAY;IADxB,aAAa,CAAC,eAAe,CAAC;GAClB,YAAY,CAqGxB","sourcesContent":["import { LitElement, css, html, nothing } from \"lit\";\nimport { customElement, property } from \"lit/decorators.js\";\nimport { tokens } from \"./tokens.js\";\n\n/**\n * Sticky editor/terminal-style chrome bar for the top edge of a page or panel:\n * three decorative traffic-light dots, a filename-style label, and a\n * right-aligned actions slot for controls such as a theme toggle.\n *\n * The text property is named `label` rather than `title`, matching\n * `page-header`'s text-property precedent and avoiding confusion with the\n * global HTML `title` tooltip attribute. The dots are purely decorative, are\n * hidden from assistive technology, and reuse the semantic `--ui-danger`,\n * `--ui-warning`, and `--ui-success` tokens rather than introducing\n * chrome-only colors.\n *\n * It sticks with `position: sticky; top: 0`, so callers must place it at the\n * top of the element that actually scrolls. Its `z-index: 1` is a deliberate\n * plain literal: just enough to keep the bar above in-flow content as it\n * sticks, while staying far below the shared overlay stack (dialogs/popovers\n * start at 100), so it does not participate in `utils/layer-stack.ts`.\n *\n * @element window-chrome\n * @slot actions - Optional right-aligned controls such as theme or view toggles.\n */\n@customElement(\"window-chrome\")\nexport class WindowChrome extends LitElement {\n /** Filename-style text shown beside the decorative dots. */\n @property() label = \"\";\n\n static override styles = [\n tokens,\n css`\n :host {\n display: block;\n position: sticky;\n top: 0;\n z-index: 1;\n box-sizing: border-box;\n border-bottom: var(--ui-border-width, 1px) solid var(--ui-border, #e2e8f0);\n background: var(--ui-surface-muted, #f8fafc);\n font-family: var(\n --ui-font,\n ui-sans-serif,\n system-ui,\n sans-serif,\n \"Apple Color Emoji\",\n \"Segoe UI Emoji\",\n \"Segoe UI Symbol\",\n \"Noto Color Emoji\"\n );\n }\n .chrome {\n display: flex;\n align-items: center;\n gap: 0.5rem;\n min-width: 0;\n padding: 0.5rem 0.75rem;\n }\n .leading {\n display: flex;\n align-items: center;\n gap: 0.5rem;\n min-width: 0;\n flex: 1 1 auto;\n }\n .dots {\n display: inline-flex;\n align-items: center;\n gap: 0.25rem;\n flex: 0 0 auto;\n }\n .dot {\n width: 0.75rem;\n height: 0.75rem;\n border-radius: var(--ui-radius-circle, 50%);\n flex: 0 0 auto;\n }\n .dot.danger {\n background: var(--ui-danger, #dc2626);\n }\n .dot.warning {\n background: var(--ui-warning, #d97706);\n }\n .dot.success {\n background: var(--ui-success, #16a34a);\n }\n .label {\n min-width: 0;\n overflow: hidden;\n text-overflow: ellipsis;\n white-space: nowrap;\n font-family: var(--ui-font-mono, ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace);\n font-size: var(--ui-font-size-sm, 0.75rem);\n font-weight: var(--ui-font-weight-regular, 400);\n line-height: var(--ui-line-height-tight, 1.25);\n color: var(--ui-text-muted, #64748b);\n }\n .actions {\n display: flex;\n align-items: center;\n margin-left: auto;\n flex: 0 0 auto;\n }\n @media (forced-colors: active) {\n :host {\n border-bottom-color: CanvasText;\n }\n }\n `,\n ];\n\n override render() {\n return html`\n <div class=\"chrome\">\n <div class=\"leading\">\n <span class=\"dots\" aria-hidden=\"true\">\n <span class=\"dot danger\"></span>\n <span class=\"dot warning\"></span>\n <span class=\"dot success\"></span>\n </span>\n ${this.label ? html`<span class=\"label\">${this.label}</span>` : nothing}\n </div>\n <div class=\"actions\"><slot name=\"actions\"></slot></div>\n </div>\n `;\n }\n}\n\ndeclare global {\n interface HTMLElementTagNameMap {\n \"window-chrome\": WindowChrome;\n }\n}\n"]}
package/docs/app-shell.md CHANGED
@@ -105,7 +105,6 @@ _None._
105
105
  | `--ui-focus-ring` |
106
106
  | `--ui-font-size-sm` |
107
107
  | `--ui-line-height-tight` |
108
- | `--ui-on-accent` |
109
108
  | `--ui-overlay` |
110
109
  | `--ui-radius-sm` |
111
110
  | `--ui-shadow` |
@@ -114,3 +113,4 @@ _None._
114
113
  | `--ui-surface-muted` |
115
114
  | `--ui-text-muted` |
116
115
  | `--ui-tooltip` |
116
+ | `--ui-tooltip-text` |
@@ -0,0 +1,45 @@
1
+ # `<blink-cursor>`
2
+
3
+ A small inline blinking cursor glyph for terminal- or editor-styled
4
+ headings, prompts, and status lines. It renders its own decorative
5
+ character so consumers can append it directly to adjacent text while
6
+ inheriting the surrounding typography.
7
+
8
+ The cursor uses the shared `--ui-primary` accent color so it reads as an
9
+ active insertion point across themes. Change `char` to swap the glyph (for
10
+ example `|` or `▋`). Under `prefers-reduced-motion` the blink stops and the
11
+ cursor remains visible.
12
+
13
+ ## Install
14
+
15
+ ```js
16
+ import "@f-ewald/components/blink-cursor.js";
17
+ ```
18
+
19
+ ## Usage
20
+
21
+ ```html
22
+ <h1>ponytail<blink-cursor></blink-cursor></h1>
23
+ <p>~/ponytail &#10095; <blink-cursor char="|"></blink-cursor></p>
24
+ ```
25
+
26
+ ## Attributes / properties
27
+
28
+ | Property | Attribute | Type | Default | Description |
29
+ | --- | --- | --- | --- | --- |
30
+ | `char` | `char` | `string` | `"▋"` | Character shown for the cursor; any single character or short string such as `|` or `▋` works. |
31
+
32
+ ## Events
33
+
34
+ _None._
35
+
36
+ ## Slots
37
+
38
+ _None._
39
+
40
+ ## CSS custom properties
41
+
42
+ | Custom property |
43
+ | --- |
44
+ | `--ui-line-height-glyph` |
45
+ | `--ui-primary` |
@@ -0,0 +1,64 @@
1
+ # `<code-diff>`
2
+
3
+ A compact, read-only code diff viewer: a bordered panel with a header bar
4
+ for `filename` and `stat`, followed by a numbered `<pre>` listing of
5
+ `lines`. Each CodeDiffLine renders as `"add"`, `"del"`, or
6
+ `"context"` with fixed `"+ "` / `"- "` / `" "` prefixes so the diff
7
+ remains understandable even when color is unavailable.
8
+
9
+ Added and removed rows reuse `--ui-success` / `--ui-danger` for their text
10
+ and low-alpha background washes, while the shell itself reuses
11
+ `--ui-font-mono`, `--ui-border`, and `--ui-surface`. The caller owns the
12
+ data shape entirely: `filename` and `stat` are passed through verbatim, and
13
+ `lines` is a flat ordered array of `{ type, text }` objects.
14
+
15
+ ## Install
16
+
17
+ ```js
18
+ import "@f-ewald/components/code-diff.js";
19
+ ```
20
+
21
+ ## Usage
22
+
23
+ ```html
24
+ <code-diff filename="cache.py" stat="&minus;48 +1"></code-diff>
25
+ <script type="module">
26
+ document.querySelector("code-diff").lines = [
27
+ { type: "del", text: "class CacheManager:" },
28
+ { type: "add", text: "@lru_cache(maxsize=1000)" },
29
+ ];
30
+ </script>
31
+ ```
32
+
33
+ ## Attributes / properties
34
+
35
+ | Property | Attribute | Type | Default | Description |
36
+ | --- | --- | --- | --- | --- |
37
+ | `filename` | `filename` | `string` | `""` | The filename shown in the header bar's left side. |
38
+ | `stat` | `stat` | `string` | `""` | The caller-supplied stat summary shown in the header bar's right side. |
39
+ | `lines` | `lines` | `CodeDiffLine[]` | `[]` | Ordered diff lines, each rendered with its type-driven prefix and styling. |
40
+
41
+ ## Events
42
+
43
+ _None._
44
+
45
+ ## Slots
46
+
47
+ _None._
48
+
49
+ ## CSS custom properties
50
+
51
+ | Custom property |
52
+ | --- |
53
+ | `--ui-border` |
54
+ | `--ui-border-width` |
55
+ | `--ui-danger` |
56
+ | `--ui-font-mono` |
57
+ | `--ui-font-size-sm` |
58
+ | `--ui-line-height-normal` |
59
+ | `--ui-numeric` |
60
+ | `--ui-radius` |
61
+ | `--ui-success` |
62
+ | `--ui-surface` |
63
+ | `--ui-text` |
64
+ | `--ui-text-muted` |
@@ -0,0 +1,49 @@
1
+ # `<comment-label>`
2
+
3
+ A code-comment-style eyebrow line for section chrome in terminal- or
4
+ editor-themed pages. It renders a colored comment marker (`##` by default)
5
+ before muted slotted text, so `<comment-label>the_whole_idea</comment-label>`
6
+ reads like a short section kicker. Set `prefix="//"` and `italic` for a
7
+ closing or footer quote line that keeps the marker upright while the message
8
+ itself turns italic.
9
+
10
+ ## Install
11
+
12
+ ```js
13
+ import "@f-ewald/components/comment-label.js";
14
+ ```
15
+
16
+ ## Usage
17
+
18
+ ```html
19
+ <comment-label>the_whole_idea</comment-label>
20
+ <comment-label prefix="//" italic>the best code is the code never written.</comment-label>
21
+ ```
22
+
23
+ ## Attributes / properties
24
+
25
+ | Property | Attribute | Type | Default | Description |
26
+ | --- | --- | --- | --- | --- |
27
+ | `prefix` | `prefix` | `string` | `"##"` | Comment marker rendered before the slotted label text. |
28
+ | `italic` | `italic` | `boolean` | `false` | Renders the slotted label text in italics while leaving the prefix upright. |
29
+
30
+ ## Events
31
+
32
+ _None._
33
+
34
+ ## Slots
35
+
36
+ _None._
37
+
38
+ ## CSS custom properties
39
+
40
+ | Custom property |
41
+ | --- |
42
+ | `--ui-font-mono` |
43
+ | `--ui-font-size-sm` |
44
+ | `--ui-font-weight-semibold` |
45
+ | `--ui-label-transform` |
46
+ | `--ui-line-height-tight` |
47
+ | `--ui-primary` |
48
+ | `--ui-text-muted` |
49
+ | `--ui-tracking-wide` |
@@ -1,8 +1,9 @@
1
1
  # `<confirm-dialog>`
2
2
 
3
- Reusable confirmation dialog: overlay + centered card with a slotted body,
4
- an optional error line, and Cancel/Confirm actions. Instant `display:none`
5
- → `display:flex` toggle (no transitions). Fires `confirm`/`cancel`
3
+ Reusable confirmation dialog: a native modal `<dialog>` (top layer, inert
4
+ page behind it, built-in focus containment) with a slotted body, an
5
+ optional error line, and Cancel/Confirm actions. Instant open/close (no
6
+ transitions). Fires `confirm`/`cancel`
6
7
  (bubbling, composed) instead of owning any deletion logic itself —
7
8
  callers stay in charge of the request. Set `size="sm"` for compact
8
9
  actions one step below the default, matching `ui-button`'s `sm` size.
@@ -0,0 +1,101 @@
1
+ # `<dag-graph>`
2
+
3
+ Interactive layered drawing of a directed graph — dependencies, pipelines, or any node-link data.
4
+
5
+ Nodes are placed in layers (via dagre) so edges flow left to right (or top to bottom with
6
+ `direction="TB"`); cycles are allowed, and the edges closing them are drawn dashed and point backward.
7
+ Each node is a compact card sized to its label, with an optional icon, color, and border style from
8
+ `kinds`. The whole graph is shown when it fits at a readable zoom; otherwise the selected node is centered at
9
+ 100%. Drag to pan; pinch or Ctrl/⌘ + wheel to zoom (a plain wheel scrolls the page). With keyboard
10
+ focus on the graph, arrow keys pan, `+`/`-` zoom, and `0` fits the graph. Clicking a node, or pressing
11
+ Enter/Space on it, selects it. A toolbar in the top-right corner offers the `controls` you enable.
12
+
13
+ Set `static` to present a fixed picture: the graph is always fitted into view, panning and zooming
14
+ are off, and the toolbar is hidden; nodes can still be selected.
15
+
16
+ Colors can be changed with these custom properties: `--dag-node-background`, `--dag-node-text`,
17
+ `--dag-edge-color`, `--dag-selected-color`, and `--dag-highlight-color`; `--dag-graph-height` sets the
18
+ height (default `24rem`).
19
+
20
+ ## Install
21
+
22
+ ```js
23
+ import "@f-ewald/components/dag-graph.js";
24
+ ```
25
+
26
+ ## Usage
27
+
28
+ ```html
29
+ <dag-graph legend selected="web"></dag-graph>
30
+ <script type="module">
31
+ import { iconBookOpen, iconCube, iconServer } from "@f-ewald/components/icons.js";
32
+ const graph = document.querySelector("dag-graph");
33
+ graph.kinds = {
34
+ service: { label: "Service", icon: iconServer, color: "#4269d0" },
35
+ library: { label: "Library", icon: iconBookOpen, color: "#3ca951" },
36
+ package: { label: "External package", icon: iconCube, color: "#9498a0", dashed: true },
37
+ };
38
+ graph.nodes = [
39
+ { id: "web", label: "web", kind: "service" },
40
+ { id: "auth", label: "auth-lib", kind: "library" },
41
+ { id: "requests", label: "requests", kind: "package" },
42
+ ];
43
+ graph.edges = [
44
+ { source: "web", target: "auth" },
45
+ { source: "auth", target: "requests" },
46
+ ];
47
+ graph.addEventListener("node-select", (e) => console.log(e.detail.id));
48
+ </script>
49
+ ```
50
+
51
+ ## Attributes / properties
52
+
53
+ | Property | Attribute | Type | Default | Description |
54
+ | --- | --- | --- | --- | --- |
55
+ | `nodes` | `nodes` | `DagNode[]` | `[]` | Nodes to draw. |
56
+ | `edges` | `edges` | `DagEdge[]` | `[]` | Directed edges between `nodes`; edges with an unknown endpoint or to the node itself are ignored. |
57
+ | `kinds` | _(JS property only)_ | `Record<string, DagNodeKind>` | `{}` | Presentation per node `kind`: legend label, color, icon, and border style. |
58
+ | `selected` | `selected` | `string | null` | `null` | Id of the selected node. Selecting a node updates it; when it changes to a node outside the visible area, the view follows. |
59
+ | `direction` | `direction` | `DagDirection` | `"LR"` | Layer direction: `LR` (left to right) or `TB` (top to bottom). |
60
+ | `label` | `label` | `string` | `"Directed graph"` | Accessible name of the graph; the node and edge counts are appended. |
61
+ | `legend` | `legend` | `boolean` | `false` | Shows a legend of `kinds` below the graph. |
62
+ | `controls` | `controls` | `string` | `"zoom fit center"` | Space-separated toolbar controls to show: any of `zoom`, `fit`, `center`, and `direction`, in that order. An empty value hides the toolbar. |
63
+ | `isStatic` | `static` | `boolean` | `false` | Presents a static picture: always fitted, with panning, zooming, and the toolbar turned off. |
64
+
65
+ ## Events
66
+
67
+ | Event | Description |
68
+ | --- | --- |
69
+ | `direction-change` | The toolbar's direction control flipped `direction`; `detail` is `{ direction }`. |
70
+ | `node-select` | A node was clicked or activated with the keyboard; `detail` is `{ id }`. |
71
+
72
+ ## Slots
73
+
74
+ _None._
75
+
76
+ ## CSS custom properties
77
+
78
+ | Custom property |
79
+ | --- |
80
+ | `--ui-border` |
81
+ | `--ui-border-width` |
82
+ | `--ui-button-highlight` |
83
+ | `--ui-button-secondary-background` |
84
+ | `--ui-button-secondary-border` |
85
+ | `--ui-button-secondary-gloss-end` |
86
+ | `--ui-button-secondary-gloss-start` |
87
+ | `--ui-danger` |
88
+ | `--ui-focus-ring` |
89
+ | `--ui-font` |
90
+ | `--ui-font-size` |
91
+ | `--ui-font-size-sm` |
92
+ | `--ui-font-size-xs` |
93
+ | `--ui-primary` |
94
+ | `--ui-radius` |
95
+ | `--ui-radius-sm` |
96
+ | `--ui-shadow` |
97
+ | `--ui-surface` |
98
+ | `--ui-surface-muted` |
99
+ | `--ui-text` |
100
+ | `--ui-text-muted` |
101
+ | `--ui-warning` |
@@ -24,29 +24,41 @@ defines the details used when creating or reviewing components.
24
24
  - Themes are single-valued and mutually exclusive, selected by `data-theme` on
25
25
  `<html>`: `dark` and `light` force one of the two flat palettes, `gradient`
26
26
  glosses buttons and toasts, `metro` squares corners and flattens shadows over
27
- a blue accent, and `blueprint` restyles the palette as a monospace technical
27
+ a blue accent, `blueprint` restyles the palette as a monospace technical
28
28
  spec sheet — ink on paper, one pure-blue accent, square corners, and
29
- structure carried by 1.5px hairline rules instead of shadows. `dark` aside,
30
- each is layered on the light palette and
31
- must be excluded from `tokens.css`'s `prefers-color-scheme: dark` media query
32
- — that selector outranks a bare `[data-theme]`, so a missing exclusion yields
33
- a half-dark hybrid rather than an outright failure. Adding a theme therefore
34
- means adding it to `lightThemes` in `generate-tokens-css.mjs`, which derives
35
- both the block and the exclusion from that one list.
29
+ structure carried by 1.5px hairline rules instead of shadows — and
30
+ `developer-dark`/`developer-light` restyle it as a monospace editor/terminal
31
+ theme — a near-black warm palette (or its light counterpart) with one green
32
+ accent, small (not squared) corners, and chrome micro-labels left in
33
+ sentence case rather than shouted.
34
+ `dark`/`developer-dark` aside, each is layered on the light palette and must
35
+ be excluded from `tokens.css`'s `prefers-color-scheme: dark` media query —
36
+ that selector outranks a bare `[data-theme]`, so a missing exclusion yields
37
+ a half-dark hybrid rather than an outright failure. Adding a theme layered on
38
+ the light palette therefore means adding it to `lightThemes` in
39
+ `generate-tokens-css.mjs`, which derives both the block and the exclusion
40
+ from that one list. Adding a second *true dark* theme (like
41
+ `developer-dark`) instead means adding it to `darkThemes`, which layers the
42
+ theme's overrides over `darkTokenValues` and needs no such exclusion, since
43
+ its own `[data-theme]` block already outranks the bare `:root` the media
44
+ query types into regardless of the reader's OS preference.
36
45
  - Colors are the normal subject of a theme. Three other axes are themeable, each
37
46
  introduced by exactly one theme and each defaulting to the behavior that
38
47
  predates it:
39
- - **Shape** — `metro` and `blueprint` set every `--ui-radius*` to `0`.
48
+ - **Shape** — `metro` and `blueprint` set every `--ui-radius*` to `0`;
49
+ `developer-dark`/`developer-light` set `--ui-radius`/`--ui-radius-sm` to a
50
+ small but non-zero step (`0.25rem`/`0.125rem`) rather than squaring them.
40
51
  - **Border weight** — `--ui-border-width` (`1px`), which `blueprint` takes to
41
52
  `1.5px`. Every genuine surface or control border reads it; see "Borders"
42
53
  below for what is deliberately excluded.
43
54
  - **Label case** — `--ui-label-transform` (`none`), which `blueprint` takes to
44
- `uppercase`, and `--ui-numeric` (`normal`), which it takes to
45
- `tabular-nums`.
55
+ `uppercase`, and `--ui-numeric` (`normal`), which `blueprint` and
56
+ `developer-dark`/`developer-light` take to `tabular-nums`.
46
57
  - **Type family** — `--ui-font` only. `blueprint` retargets it to a monospace
47
- stack led by "Space Mono", which falls through to the system mono stack when
48
- no webfont is loaded, so the theme still renders correctly with zero
49
- external CSS.
58
+ stack led by "Space Mono", and `developer-dark`/`developer-light` retarget
59
+ it to one led by "JetBrains Mono" — both fall through to the system mono
60
+ stack when no webfont is loaded, so the theme still renders correctly with
61
+ zero external CSS.
50
62
  Type *metrics* — size, weight, line height, tracking — are never themed in any
51
63
  theme: they encode hierarchy rather than style.
52
64
  - Semantic states use `primary`, `info`, `success`, `warning`, and `danger`.
@@ -99,15 +111,20 @@ defines the details used when creating or reviewing components.
99
111
 
100
112
  A themed gradient still paints over that base, so a theme overriding the
101
113
  token behaves exactly as before; only the "token contributes nothing" case
102
- changes. The layered form applies to `ui-button`'s `secondary` variant,
114
+ changes. SVG fills can't paint a CSS gradient, so SVG surfaces that act as
115
+ secondary buttons (`dag-graph`'s nodes) build an SVG `linearGradient` from
116
+ `--ui-button-secondary-gloss-start`/`-end` instead — both default to
117
+ `--ui-surface`, a flat fill, and a gradient theme sets them to its stops. The layered form applies to `ui-button`'s `secondary` variant,
103
118
  `confirm-dialog`'s Cancel, `button-group`'s unchecked segments,
104
119
  `pagination-nav`'s buttons, `radio-cards`' unchecked cards, and the floating
105
120
  `scroll-to-top`/`scroll-to-bottom`/`fullscreen-button` controls. Neither form
106
121
  applies to states that already resolve to an opaque value
107
122
  (`--ui-button-secondary-surface-muted`, `--ui-surface-muted`), nor to
108
123
  elements that draw a *line* or a *mark* rather than a surface —
109
- `content-divider`'s rule, `calendar-month`'s entry underline, and
110
- `app-sidebar`'s footer, which sits on the sidebar's own paper. Those three
124
+ `content-divider`'s rule, `calendar-month`'s entry underline,
125
+ `app-sidebar`'s footer, which sits on the sidebar's own paper, and
126
+ `step-ladder`'s rung border, which separates rows the same way
127
+ `content-divider`'s rule does. Those four
111
128
  are the allowlist in `design-tests/opaque-surfaces.spec.ts`, which walks
112
129
  every shadow root under the blueprint theme and fails on any bordered,
113
130
  see-through surface that is not one of them.
@@ -411,10 +428,15 @@ backbone, and `app-sidebar`, `action-bar`, `page-header`, `pagination-nav`, and
411
428
 
412
429
  ### Templates
413
430
 
414
- The recipes under `docs/layouts/` compose these into four pages — list-only,
415
- list + detail, detail-only, and form — and the MCP `list_layouts` /
416
- `get_layout` tools serve them. Add a page by adding a `docs/layouts/<name>.md`
417
- recipe and, ideally, a matching full-page demo under `demo/layouts/`.
431
+ The recipes under `docs/layouts/` compose these into five pages — list-only,
432
+ list + detail, detail-only, form, and marketing-landing — and the MCP
433
+ `list_layouts` / `get_layout` tools serve them. Add a page by adding a
434
+ `docs/layouts/<name>.md` recipe and, ideally, a matching full-page demo under
435
+ `demo/layouts/`. Not every recipe is an `app-shell` dashboard page:
436
+ `marketing-landing` is shell-less — a `window-chrome`-topped page built
437
+ directly from section components (`code-diff`, `step-ladder`, `stat-strip`,
438
+ `terminal-block`, etc.), for a marketing/landing-page context rather than an
439
+ authenticated app view.
418
440
 
419
441
  ## Playground and documentation
420
442
 
package/docs/icons.md CHANGED
@@ -16,6 +16,8 @@ const icon = iconPencil(16); // 16px, defaults shown below if omitted
16
16
  | --- | --- | --- |
17
17
  | `iconAcademicCap` | 18px | Education, learning, or certification-related content. |
18
18
  | `iconArrowDownTray` | 16px | Download or export actions. |
19
+ | `iconArrowLongDown` | 18px | A top-to-bottom flow or layout direction. |
20
+ | `iconArrowLongRight` | 18px | A left-to-right flow or layout direction. |
19
21
  | `iconArrowPath` | 12px | Refresh actions, or an animated busy/loading spinner. |
20
22
  | `iconArrowRight` | 12px | "Continue" or forward-progressing actions, e.g. a compact next-step arrow. |
21
23
  | `iconArrowRightOnRectangle` | 16px | Logout/sign-out actions. |
@@ -24,6 +26,7 @@ const icon = iconPencil(16); // 16px, defaults shown below if omitted
24
26
  | `iconArrowsRightLeft` | 16px | Swap, exchange, or compare actions between two items. |
25
27
  | `iconArrowTopRightOnSquare` | 16px | Links that open in a new tab/window, or navigate to an external site. |
26
28
  | `iconBars3` | 18px | A hamburger menu toggle, e.g. collapsing or opening a sidebar/nav drawer. |
29
+ | `iconBookOpen` | 20px | A library, documentation, or reading content, e.g. a library node in dag-graph. |
27
30
  | `iconCalendar` | 16px | Dates, due dates, or calendar-related metadata. |
28
31
  | `iconChatBubbleLeftRight` | 18px | Messaging, comments, or conversation-related content. |
29
32
  | `iconCheckCircle` | 16px | Success states, confirmations, or a selected-item checkmark. |
@@ -38,6 +41,7 @@ const icon = iconPencil(16); // 16px, defaults shown below if omitted
38
41
  | `iconCog` | 20px | Settings, preferences, or configuration entry points. |
39
42
  | `iconComputerDesktop` | 16px | A "system/auto" theme option, or to represent a desktop device. |
40
43
  | `iconCpuChip` | 18px | System, hardware, or technical/processing content. |
44
+ | `iconCube` | 20px | A package or self-contained artifact, e.g. an external package node in dag-graph. |
41
45
  | `iconCurrencyDollar` | 16px | Monetary values, pricing, or billing-related content. |
42
46
  | `iconDocument` | 18px | A generic file/document icon, e.g. tile-grid's default file icon. |
43
47
  | `iconEllipsisHorizontal` | 16px | Collapsed items in an inline sequence, e.g. breadcrumb-nav's truncated middle. |
@@ -56,6 +60,8 @@ const icon = iconPencil(16); // 16px, defaults shown below if omitted
56
60
  | `iconLink` | 16px | Hyperlink-related actions or a linked/associated-item indicator. |
57
61
  | `iconListBullet` | 18px | A list-view toggle, or to represent list-type content. |
58
62
  | `iconMagnifyingGlass` | 16px | Search inputs or search-triggering actions. |
63
+ | `iconMagnifyingGlassMinus` | 18px | Zoom out, e.g. dag-graph's toolbar. |
64
+ | `iconMagnifyingGlassPlus` | 18px | Zoom in, e.g. dag-graph's toolbar. |
59
65
  | `iconMap` | 16px | A map-view toggle, or to represent map/geographic content. |
60
66
  | `iconMapPin` | 16px | A location, address, or map marker. |
61
67
  | `iconMoon` | 16px | A dark-theme toggle, or to represent night/dark mode. |
@@ -66,6 +72,7 @@ const icon = iconPencil(16); // 16px, defaults shown below if omitted
66
72
  | `iconPuzzlePiece` | 18px | Plugins, integrations, or extensible/add-on features. |
67
73
  | `iconQuestionMarkCircle` | 20px | Help, tooltips, or "learn more" affordances. |
68
74
  | `iconQueueList` | 16px | Queues, backlogs, or ordered work-item lists. |
75
+ | `iconServer` | 20px | A running service or deployable, e.g. a service node in dag-graph. |
69
76
  | `iconShieldCheck` | 16px | Verified, secure, or trusted states. |
70
77
  | `iconShieldExclamation` | 16px | Security warnings, or at-risk/compromised states. |
71
78
  | `iconSignal` | 16px | Live/real-time data, connectivity strength, or a traffic-conditions toggle. |
@@ -78,5 +85,6 @@ const icon = iconPencil(16); // 16px, defaults shown below if omitted
78
85
  | `iconTrash` | 16px | Delete/remove actions, typically paired with a destructive/danger style. |
79
86
  | `iconUserCircle` | 20px | A generic user/person fallback, e.g. user-avatar's icon fallback. |
80
87
  | `iconUsers` | 18px | Teams, groups, or multi-user/collaboration content. |
88
+ | `iconViewfinderCircle` | 18px | Center or focus the view on the current selection, e.g. dag-graph's toolbar. |
81
89
  | `iconWrenchScrewdriver` | 18px | Tools, maintenance, or build/configuration actions. |
82
90
  | `iconX` | 18px | Close, dismiss, or clear (e.g. a modal, toast, or clearable input). |