Skip to content

Commit 3f82cb1

Browse files
hhfrancoishhfrancois
committed
first commit
0 parents  commit 3f82cb1

14 files changed

Lines changed: 3675 additions & 0 deletions

‎.gitignore‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Build output
5+
dist/
6+
7+
# Coverage
8+
coverage/
9+
10+
# IDE
11+
.idea/
12+
.vscode/
13+
*.swp
14+
*.swo
15+
*~
16+
17+
# OS
18+
.DS_Store
19+
Thumbs.db
20+
21+
# Logs
22+
*.log
23+
npm-debug.log*
24+
25+
# Test output
26+
test-results/
27+
28+
# Temporary files
29+
*.tmp
30+
*.temp
31+
/documentation
32+
/referentiels

‎CLAUDE.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# CLAUDE.md - Interactive Code Web Component
2+
3+
This file provides guidance to Claude Code when working with this repository.
4+
5+
## Interaction Rules
6+
7+
- **Answer questions first**: When the user asks questions, ALWAYS answer them before starting any implementation.
8+
- **Confirm understanding**: When the user proposes an idea or asks for feedback, respond with analysis and clarification questions before implementing.
9+
- **Be conversational**: Treat discussions as a dialogue, not as immediate action items.
10+
11+
## Code Style Guidelines
12+
13+
- **Comments in code**: Always in English
14+
- **Communication with user**: In French
15+
- **Variable/function names**: In English (standard convention)
16+
- **Indentation**: 2 spaces (not tabs)
17+
18+
## Project Overview
19+
20+
**@softwarity/interactive-code** is a Web Component for displaying syntax-highlighted code with interactive bindings. It allows users to click on values in code snippets to edit them directly.
21+
22+
### Key Features
23+
24+
1. **Syntax Highlighting**: HTML, SCSS, TypeScript, Shell
25+
2. **Interactive Bindings**: Click-to-edit values in code
26+
3. **Multiple Binding Types**: boolean, number, string, select, color, comment
27+
4. **Framework Agnostic**: Works with any framework or vanilla JS
28+
5. **Shadow DOM**: Encapsulated styles
29+
30+
### File Structure
31+
32+
```
33+
src/
34+
├── index.ts # Entry point, registers custom elements
35+
├── code-binding.element.ts # <code-binding> custom element
36+
└── interactive-code.element.ts # <interactive-code> custom element
37+
38+
demo/
39+
└── index.html # Demo page (uses component to document itself)
40+
```
41+
42+
### Binding Types
43+
44+
| Type | Description |
45+
|------|-------------|
46+
| `boolean` | Click to toggle true/false |
47+
| `number` | Click to edit, supports min/max/step |
48+
| `string` | Click to edit text |
49+
| `select` | Toggle (2 options) or dropdown (3+) |
50+
| `color` | Opens native color picker |
51+
| `comment` | Checkbox to comment/uncomment line |
52+
| `readonly` | Display only |
53+
54+
### Template Syntax
55+
56+
Use `${key}` in the template to mark where bindings should appear:
57+
58+
```html
59+
<interactive-code language="scss">
60+
<textarea>
61+
:root {
62+
--width: ${width}px;
63+
}
64+
</textarea>
65+
<code-binding key="width" type="number" value="72"></code-binding>
66+
</interactive-code>
67+
```
68+
69+
### Content Sources
70+
71+
The component can get its template from:
72+
1. `<textarea>` child (recommended - content preserved as raw text)
73+
2. `<template>` child (alternative)
74+
3. `code` property (programmatic)
75+
76+
### Events
77+
78+
`<code-binding>` emits a `change` event when its value changes:
79+
80+
```javascript
81+
element.addEventListener('change', (e) => {
82+
console.log('New value:', e.detail);
83+
});
84+
```
85+
86+
## Development Commands
87+
88+
```bash
89+
npm run dev # Start dev server with HMR (opens demo/index.html)
90+
npm run build # Build for production
91+
npm run typecheck # TypeScript type checking
92+
```
93+
94+
## Architecture Notes
95+
96+
### Shadow DOM
97+
98+
`<interactive-code>` uses Shadow DOM for style encapsulation. The styles are injected via `getStyles()` method.
99+
100+
### MutationObserver
101+
102+
The component uses MutationObserver to handle framework timing issues (e.g., Angular content projection). It waits for child elements to be available before rendering.
103+
104+
### Internal Change Flag
105+
106+
The `_internalChange` flag prevents infinite loops when updating values:
107+
- External changes (from `<code-binding>`) trigger a full re-render
108+
- Internal changes (from inline inputs) update only the display without re-render
109+
110+
### Marker System
111+
112+
When rendering, bindings are replaced with temporary markers (`__BINDING_0__`, etc.) before syntax highlighting, then restored after. This prevents the highlighter from corrupting binding HTML.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 Softwarity
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# @softwarity/interactive-code
2+
3+
A Web Component for displaying syntax-highlighted code with interactive bindings. Perfect for documentation, tutorials, and live demos.
4+
5+
## Features
6+
7+
- **Syntax Highlighting**: HTML, SCSS, TypeScript, and Shell
8+
- **Interactive Bindings**: Click to edit values directly in the code
9+
- **Multiple Types**: boolean, number, string, select, color, comment
10+
- **Framework Agnostic**: Works with Angular, React, Vue, or vanilla JS
11+
- **Zero Dependencies**: Pure Web Components
12+
13+
## Installation
14+
15+
```bash
16+
npm install @softwarity/interactive-code
17+
```
18+
19+
## Usage
20+
21+
```typescript
22+
import '@softwarity/interactive-code';
23+
```
24+
25+
```html
26+
<interactive-code language="scss">
27+
<textarea>
28+
:root {
29+
--width: ${width}px;
30+
--enabled: ${enabled};
31+
}
32+
</textarea>
33+
<code-binding key="width" type="number" value="72" min="48" max="120"></code-binding>
34+
<code-binding key="enabled" type="boolean" value="true"></code-binding>
35+
</interactive-code>
36+
```
37+
38+
## Binding Types
39+
40+
| Type | Description | Interaction |
41+
|------|-------------|-------------|
42+
| `boolean` | true/false value | Click to toggle |
43+
| `number` | Numeric value | Click to edit, supports min/max/step |
44+
| `string` | Text value | Click to edit |
45+
| `select` | Option from list | Click to toggle (2 options) or dropdown (3+) |
46+
| `color` | Color value | Click to open color picker |
47+
| `comment` | Line toggle | Checkbox to comment/uncomment line |
48+
| `readonly` | Display only | No interaction |
49+
50+
## API
51+
52+
### `<interactive-code>`
53+
54+
| Attribute | Type | Description |
55+
|-----------|------|-------------|
56+
| `language` | `'html' \| 'scss' \| 'typescript' \| 'shell'` | Syntax highlighting language |
57+
58+
| Property | Type | Description |
59+
|----------|------|-------------|
60+
| `code` | `string \| null` | Set code content programmatically |
61+
62+
### `<code-binding>`
63+
64+
| Attribute | Type | Description |
65+
|-----------|------|-------------|
66+
| `key` | `string` | Binding identifier (matches `${key}` in template) |
67+
| `type` | `BindingType` | Type of binding |
68+
| `value` | `any` | Initial value |
69+
| `disabled` | `boolean` | Disable editing |
70+
| `min` | `number` | Minimum value (for `number` type) |
71+
| `max` | `number` | Maximum value (for `number` type) |
72+
| `step` | `number` | Step increment (for `number` type) |
73+
| `options` | `string` | Comma-separated options (for `select` type) |
74+
75+
| Event | Description |
76+
|-------|-------------|
77+
| `change` | Fired when value changes |
78+
79+
**Inline handler:** Use `onchange` attribute where `e` is the new value directly:
80+
81+
```html
82+
<code-binding key="checked" type="boolean" value="true"
83+
onchange="document.getElementById('preview').checked = e"></code-binding>
84+
```
85+
86+
**addEventListener:** Use `e.target.value` or `e.detail`:
87+
88+
```javascript
89+
binding.addEventListener('change', (e) => {
90+
preview.checked = e.target.value;
91+
});
92+
```
93+
94+
## Examples
95+
96+
### Boolean Toggle
97+
98+
```html
99+
<interactive-code language="html">
100+
<textarea>
101+
<nav [autoCollapse]="${autoCollapse}">...</nav>
102+
</textarea>
103+
<code-binding key="autoCollapse" type="boolean" value="true"></code-binding>
104+
</interactive-code>
105+
```
106+
107+
### Number with Constraints
108+
109+
```html
110+
<interactive-code language="scss">
111+
<textarea>
112+
:root {
113+
--width: ${width}px;
114+
}
115+
</textarea>
116+
<code-binding key="width" type="number" value="72" min="48" max="120" step="4"></code-binding>
117+
</interactive-code>
118+
```
119+
120+
### Color Picker
121+
122+
```html
123+
<interactive-code language="scss">
124+
<textarea>
125+
:root {
126+
--primary: ${primary};
127+
}
128+
</textarea>
129+
<code-binding key="primary" type="color" value="#6750a4"></code-binding>
130+
</interactive-code>
131+
```
132+
133+
### Comment Toggle (Line Enable/Disable)
134+
135+
```html
136+
<interactive-code language="scss">
137+
<textarea>
138+
:root {
139+
${enableWidth}--custom-width: 280px;
140+
}
141+
</textarea>
142+
<code-binding key="enableWidth" type="comment" value="true"></code-binding>
143+
</interactive-code>
144+
```
145+
146+
## CSS Customization
147+
148+
The component supports CSS custom properties for styling:
149+
150+
| Property | Default | Description |
151+
|----------|---------|-------------|
152+
| `--code-bg` | `#1e1e1e` | Background color of the code block |
153+
| `--code-border-radius` | `8px` | Border radius of the code block |
154+
155+
```css
156+
interactive-code {
157+
--code-bg: #282c34;
158+
--code-border-radius: 4px;
159+
}
160+
```
161+
162+
## Development
163+
164+
```bash
165+
# Install dependencies
166+
npm install
167+
168+
# Start dev server
169+
npm run dev
170+
171+
# Build for production
172+
npm run build
173+
```
174+
175+
## License
176+
177+
MIT - [Softwarity](https://www.softwarity.io/)

‎demo/favicon.ico‎

262 KB
Binary file not shown.

0 commit comments

Comments
 (0)