Skip to content

Commit d576812

Browse files
iroybotlinioiroybotlinio
committed
chore: added readme to storybook, moved phpmd script to .githooks, added microdata.yaml
1 parent a20cc97 commit d576812

5 files changed

Lines changed: 215 additions & 2 deletions

File tree

‎.githooks/pre-commit‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ fi
148148
# fi
149149

150150
# PHPMD - PHP Mess Detector
151-
source ./bin/phpmd.sh
151+
source ./.githooks/pre-commit.d/phpmd.sh
152152

153153
# Run composer audit locally
154154
printf "${YELLOW}Composer Audit${NC}\n"

bin/phpmd.sh renamed to .githooks/pre-commit.d/phpmd.sh

File renamed without changes.

‎docs/phpmd.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,4 @@ layout: home
1313
## Design
1414

1515

16-
Tue Nov 4 10:56:44 AM CET 2025
16+
Fri Nov 7 09:23:21 AM CET 2025

‎src/Resources/specifications/microdata.yaml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Microdata attributes for semantic HTML elements
2+
# See: https://html.spec.whatwg.org/multipage/microdata.html
3+
# Used for embedding machine-readable data using vocabularies like Schema.org
4+
5+
# Microdata applies to most elements, excluding:
6+
# - Non-semantic void elements: br, wbr, hr
7+
# - Metadata infrastructure: base, head, html
8+
# - Script/style: script, style, noscript
9+
# - Resource definitions: param, source, track
10+
# - Link metadata (has its own mechanism): link
11+
'/^(?!base|br|head|hr|html|link|noscript|param|script|source|style|track|wbr$)[a-z][a-z0-9]*$/':
12+
attributes:
13+
itemscope:
14+
description: 'Creates a new item scope. This is a boolean attribute that indicates the element contains microdata.'
15+
type: boolean
16+
defaultValue: false
17+
itemtype:
18+
description: 'Specifies the URL of the vocabulary that will be used to define item properties in the data structure. Only valid when itemscope is present. Common values include Schema.org types like https://schema.org/Article, https://schema.org/Person, https://schema.org/Product, etc.'
19+
type: string
20+
itemprop:
21+
description: 'Adds a property to an item. The value can be a string or a reference to another item. This attribute can be used on elements within an itemscope to define properties, or independently to add properties to an ancestor item scope.'
22+
type: string
23+
itemid:
24+
description: 'Provides a global identifier (URL) for the item. Only valid when both itemscope and itemtype are present on the same element.'
25+
type: string
26+
itemref:
27+
description: 'References additional elements (by their IDs) to include in the item scope. Provide a space-separated list of element IDs. Only meaningful when itemscope is present.'
28+
type: string

‎templates/storybook/README.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# Storybook HTML5 Element Stories
2+
3+
**Compatible with Storybook v8+ (tested with v10)**
4+
5+
A comprehensive collection of auto-generated Storybook stories for all HTML5 elements, providing interactive documentation and testing capabilities for web components and HTML elements.
6+
7+
## 🚀 Quick Start - Drop-in Solution
8+
9+
Getting started is incredibly simple:
10+
11+
1. **Create or open your Storybook project**
12+
```bash
13+
npx storybook@latest init
14+
```
15+
16+
2. **Drop in the templates**
17+
- Copy the `storybook` folder to your storybook folder
18+
- Rename it to `stories` (or your configured stories directory)
19+
20+
3. **Done!**
21+
- Start Storybook: `npm run storybook`
22+
- All HTML5 elements are now available in your Storybook
23+
24+
That's it! No configuration needed. All stories are ready to use immediately.
25+
26+
## 📁 Structure
27+
28+
```
29+
storybook/
30+
├── inline/ # Inline elements (a, span, strong, etc.)
31+
│ ├── a.stories.js
32+
│ ├── abbr.stories.js
33+
│ └── ...
34+
├── block/ # Block elements (div, section, article, etc.)
35+
│ ├── article.stories.js
36+
│ ├── aside.stories.js
37+
│ └── ...
38+
├── void/ # Void/self-closing elements (img, input, meta, etc.)
39+
│ ├── img.stories.js
40+
│ ├── input.stories.js
41+
│ └── ...
42+
└── composed/ # Composed examples showing valid parent-child relationships
43+
├── form.composed.stories.js
44+
├── table.composed.stories.js
45+
└── ...
46+
```
47+
48+
## ✨ Features
49+
50+
### Complete HTML5 Coverage
51+
- **113 HTML5 elements** with full documentation
52+
- All **global attributes** (id, class, data-*, aria-*, etc.)
53+
- **Element-specific attributes** with proper types and validation
54+
- **Enum attributes** with dropdown selectors showing all valid values
55+
- **ARIA support** with all applicable ARIA attributes
56+
57+
### Interactive Controls
58+
Every story includes Storybook controls for:
59+
- **Text inputs** for string attributes
60+
- **Number inputs** for numeric attributes
61+
- **Boolean toggles** for true/false attributes
62+
- **Select dropdowns** for enum values (with empty option)
63+
- **Object editors** for data-* attributes
64+
65+
### Composed Examples
66+
The `composed/` folder contains **17 sophisticated examples** demonstrating:
67+
- **Valid parent-child relationships** based on HTML5 content model
68+
- **Realistic usage patterns** (forms with inputs, tables with rows, lists with items)
69+
- **Priority elements** showing the most common children
70+
- **Proper nesting** respecting uniqueness constraints (`uniquePerParent`)
71+
72+
Examples include:
73+
- `form.composed.stories.js` - Forms with fieldsets, inputs, buttons
74+
- `table.composed.stories.js` - Tables with caption, colgroups, tbody, rows
75+
- `head.composed.stories.js` - Head with title, meta, link, script elements
76+
- `figure.composed.stories.js` - Figures with images and captions
77+
- `ul.composed.stories.js`, `ol.composed.stories.js` - Lists with items
78+
- And more...
79+
80+
## 🎯 Advantages
81+
82+
### For Developers
83+
- **Zero Configuration** - Drop in and start using immediately
84+
- **Type Safety** - All attributes properly typed and validated
85+
- **Autocomplete** - Full IDE support through JSDoc comments
86+
- **Reusable Components** - Import and use Default stories in your own components
87+
- **Learning Tool** - Explore HTML5 elements and their attributes interactively
88+
89+
### For Teams
90+
- **Single Source of Truth** - One place to see all HTML5 capabilities
91+
- **Consistency** - Standardized documentation across all elements
92+
- **Accessibility** - All ARIA attributes included and documented
93+
- **Quality Assurance** - Test elements with different attribute combinations
94+
- **Onboarding** - New team members can learn HTML5 quickly
95+
96+
### For Design Systems
97+
- **Foundation** - Build your design system on top of semantic HTML
98+
- **Customization** - Extend stories with your own variants
99+
- **Documentation** - Use as base documentation for your components
100+
- **Testing** - Validate your CSS against all HTML5 elements
101+
- **Visual Regression** - Test styling across all element types
102+
103+
## 🔧 Customization
104+
105+
### Using Stories in Your Components
106+
107+
Import and use the Default stories to compose your own:
108+
109+
```javascript
110+
import * as ButtonStories from './inline/button.stories.js';
111+
import * as InputStories from './void/input.stories.js';
112+
113+
export const MyForm = {
114+
render: () => {
115+
const form = document.createElement('form');
116+
117+
const input = InputStories.Default.render(InputStories.Default.args);
118+
const button = ButtonStories.Default.render(ButtonStories.Default.args);
119+
120+
form.appendChild(input);
121+
form.appendChild(button);
122+
123+
return form;
124+
}
125+
};
126+
```
127+
128+
### Extending Stories
129+
130+
Add your own variants by importing the element stories:
131+
132+
```javascript
133+
import Anchor from './inline/a.stories.js';
134+
135+
export const InlineButton = {
136+
...Anchor,
137+
args: {
138+
...Anchor.args,
139+
role: 'button',
140+
}
141+
};
142+
```
143+
144+
## 🎨 Styling
145+
146+
All stories use semantic HTML without inline styles, making them perfect for:
147+
- **CSS framework testing** (Bootstrap, Tailwind, PicoCSS, etc.)
148+
- **Custom design systems**
149+
- **Accessibility testing**
150+
They are intended to form the basis of your own design system. You make them your own by creating organisms and molecules on top of these atomic elements - including custom styles as needed.
151+
152+
## 🔍 Content Model Validation
153+
154+
Some HTML elements need to be seen in their content model context to be meaningful. The `composed/` folder provides stories that demonstrate valid parent-child relationships according to HTML5 specifications.
155+
Composed stories follow HTML5 content model rules:
156+
- Only **valid children** are included (based on `$parentOf` metadata)
157+
- **Unique elements** appear only once (title, base, etc.)
158+
159+
## 🚦 Compatibility
160+
161+
- **Storybook**: v8, v9, v10+
162+
- **Browsers**: All modern browsers (ES6+)
163+
- **Frameworks**: Framework-agnostic (vanilla JavaScript)
164+
- **Build Tools**: Works with Webpack, Vite, etc.
165+
166+
## 📝 Generated Code
167+
168+
All stories are **auto-generated** from:
169+
- HTML5 schema YAML files
170+
- PHP Element classes with metadata
171+
- Content model relationships (`$childOf`, `$parentOf`)
172+
- Global and element-specific attributes
173+
174+
**Do not edit the generated files manually** - they will be overwritten. Instead:
175+
1. Modify the source specifications
176+
2. Regenerate using: `php bin/ext-html generate:composed storybook templates/storybook`
177+
178+
To regenerate stories:
179+
```bash
180+
# Generate all element stories
181+
php bin/ext-html generate:all storybook templates/storybook
182+
183+
# Generate only composed examples
184+
php bin/ext-html generate:composed storybook templates/storybook --overwrite-existing=true
185+
```

0 commit comments

Comments
 (0)