@bytefaceinc/web-lang 0.1.1

package/docs/language-guide.md

@@ -0,0 +1,945 @@
+# WEB Language Guide
+
+WEB is a small declarative UI language that compiles `.web` source into HTML and CSS.
+
+Run the compiler with:
+
+```bash
+node compiler.js
+```
+
+That legacy script mode reads `layout.web` from the current directory and writes `index.html` plus `styles.css`.
+
+You can also use the CLI to compile any `.web` file next to its source:
+
+```bash
+web home.web
+web home
+web .
+web ./code/*
+```
+
+CLI mode writes matching outputs such as `home.html` and `home.css`.
+
+## Recommended Build Order
+
+WEB is easiest to use in this sequence:
+
+1. Define the HTML structure.
+2. Add a `define { ... }` block for variables, semantic types, and shared style inheritance.
+3. Add HTML attributes plus any top-level `::head` and `::script` blocks.
+4. Add states and animations with `::pseudo` blocks.
+5. Add responsive rules with `::media`.
+6. Use `raw` only for CSS that WEB does not express yet.
+
+## 1. Structure and HTML Output
+
+Start by setting up one optional `define { ... }` block for shared declarations.
+
+### Define block
+
+All variables, semantic type declarations, and CSS inheritance declarations must live inside a single top-level `define { ... }` block.
+
+```web
+define {
+  @pageWidth = "960px";
+  Button actionButton;
+  actionButton primaryButton;
+  primaryButton extends actionButton;
+}
+```
+
+Rules:
+
+- `define { ... }` is optional, but required if you use variables, type declarations, or style inheritance
+- it must appear before rules
+- only one `define { ... }` block is allowed
+- only variables, type declarations, and style inheritance are allowed inside it
+
+### Type declarations
+
+Use this form:
+
+```web
+define {
+  BaseType NewType;
+}
+```
+
+Example:
+
+```web
+define {
+  Button actionButton;
+  actionButton primaryButton;
+  Main pageMain;
+  Section heroSection;
+  Paragraph heroCopy;
+}
+```
+
+Rules:
+
+- declarations live inside `define { ... }`
+- types can inherit from other declared types
+- the resolved base type decides which HTML tag is generated
+
+Type declarations do not copy CSS. If you want one WEB object or class to inherit another object's styles, use `extends` inside `define { ... }`.
+
+### Supported HTML mapping
+
+WEB does not let you write raw HTML tags directly. It infers them from the resolved base type.
+
+Common built-in mappings:
+
+- `Button` -> `<button>`
+- `Heading`, `Heading1`, `H1` -> `<h1>`
+- `Heading2`, `H2` -> `<h2>`
+- `Heading3`, `H3` -> `<h3>`
+- `Heading4`, `H4` -> `<h4>`
+- `Heading5`, `H5` -> `<h5>`
+- `Heading6`, `H6` -> `<h6>`
+- `Paragraph`, `Text` -> `<p>`
+- `Span` -> `<span>`
+- `Section` -> `<section>`
+- `Main` -> `<main>`
+- `Header` -> `<header>`
+- `Footer` -> `<footer>`
+- `Nav`, `Navigation` -> `<nav>`
+- `Article` -> `<article>`
+- `Aside` -> `<aside>`
+- `Figure` -> `<figure>`
+- `FigureCaption`, `FigCaption` -> `<figcaption>`
+- `Link`, `Anchor` -> `<a>`
+- `Picture` -> `<picture>`
+- `Source` -> `<source>`
+- `Image`, `Img` -> `<img>`
+- `Video` -> `<video>`
+- `Audio` -> `<audio>`
+- `Form` -> `<form>`
+- `Label` -> `<label>`
+- `Dialog` -> `<dialog>`
+- `Details` -> `<details>`
+- `Summary` -> `<summary>`
+- `Input` -> `<input>`
+- `TextArea` -> `<textarea>`
+- `Select` -> `<select>`
+- `Option` -> `<option>`
+- `List`, `UnorderedList`, `BulletList` -> `<ul>`
+- `OrderedList`, `NumberedList` -> `<ol>`
+- `ListItem` -> `<li>`
+- `Table` -> `<table>`
+- `TableHead` -> `<thead>`
+- `TableBody` -> `<tbody>`
+- `TableFoot` -> `<tfoot>`
+- `TableRow` -> `<tr>`
+- `TableHeaderCell` -> `<th>`
+- `TableCell` -> `<td>`
+- `Code` -> `<code>`
+- `Pre`, `Preformatted` -> `<pre>`
+- `Strong` -> `<strong>`
+- `Em`, `Emphasis` -> `<em>`
+- `LineBreak`, `Br` -> `<br>`
+- anything else -> `<div>`
+
+Void elements such as `Image`, `Input`, `LineBreak`, and `Source` cannot contain children or content.
+
+### Dot notation
+
+Dot notation builds hierarchy directly from the path.
+
+```web
+heroSection.primaryButton.textContent = "Launch";
+heroSection.primaryButton.padding = "14px 18px";
+```
+
+That produces a `primaryButton` inside `heroSection`.
+
+### Nested blocks
+
+Nested blocks are syntax sugar for the same structure.
+
+```web
+pageMain {
+  heroSection {
+    primaryButton {
+      textContent = "Launch";
+      padding = "14px 18px";
+    }
+  }
+}
+```
+
+These forms are equivalent:
+
+```web
+pageMain.heroSection.primaryButton.textContent = "Launch";
+```
+
+```web
+pageMain {
+  heroSection {
+    primaryButton {
+      textContent = "Launch";
+    }
+  }
+}
+```
+
+Dot notation blocks are also supported:
+
+```web
+pageMain.heroSection {
+  primaryButton {
+    textContent = "Launch";
+  }
+}
+```
+
+### Global style blocks
+
+Two special top-level blocks map directly to global CSS selectors:
+
+```web
+* {
+  boxSizing = "border-box";
+}
+
+html {
+  background = "#101522";
+  color = "#f7f6ff";
+}
+```
+
+That compiles to:
+
+```css
+* {
+  box-sizing: border-box;
+}
+
+html {
+  background: #101522;
+  color: #f7f6ff;
+}
+```
+
+Rules:
+
+- `* { ... }` and `html { ... }` are CSS-only global selector blocks
+- they do not create HTML nodes
+- they must be declared at the top level
+- they are also allowed inside a top-level `::media` block
+- nested `html { ... }` inside an element block is not allowed
+
+### Content properties
+
+WEB has three reserved properties:
+
+- `textContent`
+- `innerHTML`
+- `raw`
+
+`textContent` inserts escaped text:
+
+```web
+heroSection.heroCopy.textContent = "Safe plain text";
+```
+
+`innerHTML` inserts raw HTML:
+
+```web
+heroSection.heroCopy.innerHTML = "Read the <strong>docs</strong>.";
+```
+
+### HTML attributes with `::attrs`
+
+Use `::attrs { ... }` when you want real HTML attributes on a normal WEB node.
+
+```web
+docsLink {
+  textContent = "Docs";
+
+  ::attrs {
+    href = "/docs";
+    target = "_blank";
+    rel = "noreferrer";
+    ariaLabel = "Open docs";
+  }
+}
+```
+
+Rules:
+
+- `::attrs` must be nested directly inside an element block
+- attribute names use camelCase in WEB and compile to kebab-case in HTML
+- `disabled = true;` emits a bare boolean attribute
+- `open = true;` is useful for tags like `Dialog` and `Details`
+- `false`, `null`, and `undefined` omit the attribute
+- `class` and `style` are not allowed in `::attrs`
+- `::attrs` is not allowed inside `styles { ... }`, pseudo blocks, or media blocks
+
+### Head tags with `::head`
+
+Use `::head { ... }` when you want to add `meta` and `link` tags directly to the document `<head>`.
+
+```web
+::head {
+  meta {
+    name = "description";
+    content = "Landing page built in WEB.";
+  }
+
+  link {
+    rel = "help";
+    href = "compiler.md";
+    type = "text/markdown";
+  }
+}
+```
+
+That compiles to entries like:
+
+```html
+<meta name="description" content="Landing page built in WEB.">
+<link rel="help" href="compiler.md" type="text/markdown">
+```
+
+Rules:
+
+- `::head` must be declared at the top level
+- it does not participate in CSS generation
+- it only supports `meta { ... }` and `link { ... }` entries
+- `meta` and `link` entries only support direct HTML attribute assignments
+- attribute names use camelCase in WEB and compile to kebab-case in HTML
+- custom head entries are inserted into `<head>` after the compiler’s default charset, viewport, title, and stylesheet tags
+
+### Script tags with `::script`
+
+Use `::script { ... }` when you want the compiler to emit a literal `<script></script>` tag.
+
+```web
+::script {
+  src = "/assets/app.js";
+  defer = "true";
+
+  code {
+    function helloWorld () {
+      alert("hello world");
+    }
+  }
+}
+```
+
+That compiles to:
+
+```html
+<script src="/assets/app.js" defer="true">
+  function helloWorld () {
+    alert("hello world");
+  }
+</script>
+```
+
+Rules:
+
+- `::script` must be declared at the top level
+- it does not participate in CSS generation
+- it supports direct HTML attribute assignments like `src = "/app.js";`
+- it supports one optional `code { ... }` block for inline script content
+- the `code { ... }` body is copied into the output script tag as raw text
+- script blocks render near the end of `<body>` after normal WEB nodes
+- `defer = true;` emits a bare boolean attribute, while `defer = "true";` emits `defer="true"`
+
+### JavaScript injection
+
+WEB supports compile-time JavaScript values with:
+
+```web
+heroSection.heroCopy.textContent = js`
+  let count = 3;
+  let output = "";
+
+  for (let i = 0; i < count; i += 1) {
+    output += `Hello ${i} `;
+  }
+
+  return output;
+`;
+```
+
+How it works:
+
+- the compiler wraps the contents in a function and executes it at compile time
+- the final result is inserted into the generated output
+- errors are rendered inline as text instead of crashing the compiler
+
+### JavaScript result order
+
+WEB resolves a `js` block in this order:
+
+1. an explicit `return`
+2. text accumulated through `emit(value)`
+3. the last top-level declared variable inside the `js` block
+4. an empty string
+
+Example:
+
+```web
+heroSection.heroCopy.textContent = js`
+  emit("Hello ");
+  emit("world");
+`;
+```
+
+### Structured fragment output
+
+When `innerHTML` is used with `js`, the `js` block may return structured fragment nodes instead of raw tag strings.
+
+Helpers available inside `js` blocks:
+
+- `node(typeName, className?, options?)`
+- `el(...)` as an alias for `node(...)`
+- `fragment(children)`
+- `text(value)`
+- `html(value)`
+
+Supported `node(...)` options:
+
+- `textContent`
+- `innerHTML`
+- `children`
+- `style`
+- `attributes`
+
+Use `::attrs { ... }` for normal WEB nodes. Use `node(..., { attributes: ... })` only for nodes generated inside `js`.
+
+Example:
+
+```web
+featureGrid.innerHTML = js`
+  const cards = [
+    { title: "Readable", copy: "Less tag-heavy JS output." },
+    { title: "Loop-friendly", copy: "Still generated at compile time." },
+  ];
+
+  return cards.map((card) =>
+    node("Article", "featureCard", {
+      children: [
+        node("Heading3", "featureTitle", { textContent: card.title }),
+        node("Paragraph", "featureCopy", { textContent: card.copy }),
+      ],
+    })
+  );
+`;
+```
+
+This keeps loops and conditional logic in JavaScript while still avoiding explicit raw HTML tags in the source.
+
+## 2. Basic Styling and Positioning
+
+Once the structure exists, add normal CSS properties directly in WEB.
+
+### Property assignments
+
+Any non-reserved property becomes CSS.
+
+```web
+heroSection {
+  display = "grid";
+  gap = "18px";
+  padding = "32px";
+  backgroundColor = "#101522";
+}
+```
+
+Compiles to:
+
+```css
+.heroSection {
+  display: grid;
+  gap: 18px;
+  padding: 32px;
+  background-color: #101522;
+}
+```
+
+Rules:
+
+- CSS property names should be written in camelCase
+- the compiler converts them to kebab-case in `styles.css`
+- later assignments for the same property on the same rule win
+
+### Values
+
+WEB accepts these value types:
+
+- quoted strings: `"grid"`
+- numbers: `1`, `0.95`, `-10`
+- percentages: `50%`
+- bare identifiers: `none`, `auto`, `inherit`
+- variable references: `@pageWidth`
+- template literals: `` `...` ``
+- JavaScript inject blocks: `` js`...` ``
+
+Examples:
+
+```web
+heroSection.opacity = 0.95;
+heroSection.width = 100%;
+heroSection.display = grid;
+heroSection.border = @borderRule;
+```
+
+### Variables
+
+Use variables inside `define { ... }` to avoid repeating primitive values.
+
+```web
+define {
+  @pageWidth = "960px";
+  @panelRadius = "24px";
+  @borderRule = "1px solid #dde5ee";
+}
+```
+
+Then reuse them:
+
+```web
+pageMain.width = @pageWidth;
+heroSection.border = @borderRule;
+```
+
+Rules:
+
+- variable names must start with `@`
+- variables must be declared inside `define { ... }`
+- variables can reference other variables
+- variables only support simple values, not `js` blocks
+
+### Style inheritance
+
+Use `extends` inside `define { ... }` when you want one WEB name to inherit another name's CSS.
+
+Syntax:
+
+```web
+define {
+  storeCard extends card;
+}
+```
+
+Example:
+
+```web
+define {
+  Article card;
+  card storeCard;
+  storeCard extends card;
+}
+
+card {
+  padding = "20px";
+  borderRadius = "20px";
+  background = "#eef3ff";
+}
+
+storeCard {
+  background = "#ffffff";
+}
+```
+
+This means:
+
+- `storeCard` inherits the CSS generated for `card`
+- `storeCard` keeps its own explicit styles too
+- explicit styles on `storeCard` win over inherited styles from `card`
+
+Rules:
+
+- style inheritance declarations must be declared inside `define { ... }`
+- style inheritance is CSS-only and does not change HTML tag inference
+- style inheritance is transitive
+- circular style inheritance is not allowed
+- closer ancestors win over farther ancestors
+- explicit styles on the derived name win over inherited styles, even if the base rule appears later in the file
+
+What gets inherited:
+
+- normal property assignments
+- nested descendant rules
+- `styles { ... }` selectors
+- pseudo blocks
+- media-query blocks
+- `raw` blocks anchored to the inherited selector
+
+If you also want the derived object to share the same semantic HTML tag, combine type inheritance and style inheritance:
+
+```web
+define {
+  Article card;
+  card storeCard;
+  storeCard extends card;
+}
+```
+
+### Style scopes
+
+Use `styles { ... }` when you want CSS selectors without creating matching HTML nodes.
+
+This is especially useful for classes returned from `innerHTML = js\`...\``.
+
+```web
+featureGrid {
+  innerHTML = js`
+    return node("Article", ["featureCard", "featureCardCool"], {
+      children: [
+        node("Heading3", ["featureTitle", "featureTitleCool"], {
+          textContent: "Readable",
+        }),
+        node("Paragraph", "featureCopy", {
+          textContent: "Styled from outer WEB syntax.",
+        }),
+      ],
+    });
+  `;
+
+  styles {
+    featureCard {
+      padding = "20px";
+      borderRadius = "20px";
+    }
+
+    featureCardCool {
+      background = "linear-gradient(180deg, #ffffff 0%, #eef6ff 100%)";
+    }
+
+    featureTitleCool {
+      color = "#225fbe";
+    }
+
+    featureCopy {
+      color = "#596780";
+    }
+  }
+}
+```
+
+Rules:
+
+- `styles { ... }` emits descendant CSS selectors
+- it does not create matching HTML nodes
+- `textContent` and `innerHTML` are not allowed inside `styles`
+- `raw` is still allowed inside `styles`
+
+### Selector generation
+
+WEB maps paths to descendant class selectors.
+
+```web
+pageMain.heroSection.primaryButton.backgroundColor = "#ff7070";
+```
+
+Compiles to:
+
+```css
+.pageMain .heroSection .primaryButton {
+  background-color: #ff7070;
+}
+```
+
+## 3. Pseudo Selectors and Animations
+
+WEB now has a first-class pseudo system.
+
+### Pseudo selector syntax
+
+All pseudo selectors are written with a `::` prefix in WEB.
+
+Example:
+
+```web
+benefitCard {
+  background = "blue";
+
+  ::hover {
+    background = "red";
+  }
+}
+```
+
+Compiles to:
+
+```css
+.benefitCard {
+  background: blue;
+}
+
+.benefitCard:hover {
+  background: red;
+}
+```
+
+### Mapping rules
+
+WEB normalizes pseudo names like this:
+
+- pseudo-classes compile to a single colon in CSS
+- pseudo-elements compile to a double colon in CSS
+- camelCase pseudo names are converted to kebab-case
+
+Examples:
+
+- `::hover` -> `:hover`
+- `::focusWithin` -> `:focus-within`
+- `::nthChild(2n + 1)` -> `:nth-child(2n + 1)`
+- `::before` -> `::before`
+- `::firstLetter` -> `::first-letter`
+
+### Nested descendant rules
+
+Pseudo blocks stay attached to the scope where they are declared.
+
+```web
+benefitCard {
+  icon {
+    opacity = 0.4;
+  }
+
+  ::hover {
+    icon {
+      opacity = 1;
+    }
+  }
+}
+```
+
+Compiles to:
+
+```css
+.benefitCard .icon {
+  opacity: 0.4;
+}
+
+.benefitCard:hover .icon {
+  opacity: 1;
+}
+```
+
+### Pseudo selectors inside style scopes
+
+Pseudo blocks also work inside `styles { ... }`.
+
+```web
+fragmentMount {
+  styles {
+    card {
+      padding = "12px";
+
+      ::hover {
+        background = "#dbe7ff";
+      }
+    }
+  }
+}
+```
+
+### `::keyframes`
+
+Animations use a top-level `::keyframes` block.
+
+Example:
+
+```web
+card {
+  animation = "slideIn 3s";
+}
+
+::keyframes slideIn {
+  from {
+    opacity = 0;
+    transform = "translateY(16px)";
+  }
+
+  60% {
+    opacity = 1;
+  }
+
+  to {
+    opacity = 1;
+    transform = "translateY(0)";
+  }
+}
+```
+
+Compiles to:
+
+```css
+.card {
+  animation: slideIn 3s;
+}
+
+@keyframes slideIn {
+  from {
+    opacity: 0;
+    transform: translateY(16px);
+  }
+
+  60% {
+    opacity: 1;
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+```
+
+Rules:
+
+- `::keyframes` must be declared at the top level
+- `::keyframes` cannot be nested inside element blocks or `styles { ... }`
+- keyframe stages support `from`, `to`, and percentages like `50%`
+- keyframe stages accept normal CSS property assignments
+
+Invalid:
+
+```web
+card {
+  ::keyframes slideIn {
+    from {
+      opacity = 0;
+    }
+  }
+}
+```
+
+## 4. Media Queries
+
+Media queries use the same `::` syntax.
+
+### Nested media rules
+
+```web
+benefitCard {
+  padding = "20px";
+
+  ::media (max-width: 700px) {
+    padding = "14px";
+  }
+}
+```
+
+Compiles to:
+
+```css
+.benefitCard {
+  padding: 20px;
+}
+
+@media (max-width: 700px) {
+  .benefitCard {
+    padding: 14px;
+  }
+}
+```
+
+### Top-level media blocks
+
+You can also wrap whole rule groups:
+
+```web
+::media (max-width: 700px) {
+  pageMain {
+    gap = "18px";
+  }
+
+  pageMain.heroSection {
+    padding = "20px";
+  }
+}
+```
+
+### Combining media and pseudo selectors
+
+Media blocks and pseudo blocks can be combined.
+
+```web
+button {
+  ::media (max-width: 700px) {
+    ::hover {
+      background = "#2d5cff";
+    }
+  }
+}
+```
+
+This compiles to:
+
+```css
+@media (max-width: 700px) {
+  .button:hover {
+    background: #2d5cff;
+  }
+}
+```
+
+Rules:
+
+- `::media` accepts normal CSS media query text after the keyword
+- media query conditions should be written in normal CSS syntax such as `max-width`, not camelCase
+- media blocks only support CSS properties, selector blocks, pseudo blocks, `styles { ... }`, and `raw`
+- `textContent`, `innerHTML`, type declarations, and variable declarations are not allowed inside media blocks
+
+## 5. Raw CSS Escape Hatch
+
+`raw` still exists for CSS that WEB does not express yet.
+
+Example:
+
+```web
+heroSection.primaryButton.raw = `
+  transition: transform 0.3s ease;
+  &:hover {
+    transform: scale(1.05);
+  }
+`;
+```
+
+Use `raw` when you need:
+
+- CSS selectors that WEB does not model yet
+- at-rules other than `::media` and `::keyframes`
+- complex CSS text that is easier to paste directly
+
+`raw` supports:
+
+- normal declarations
+- nested selectors using `&`
+- at-rules such as `@supports`
+
+For new code, prefer:
+
+- normal property assignments first
+- `styles { ... }` for selector-only styling
+- `::pseudo` blocks for states and pseudo-elements
+- `::media` for responsive rules
+
+## Comments
+
+WEB supports:
+
+- line comments with `//`
+- block comments with `/* ... */`
+
+## JavaScript Safety
+
+JavaScript injection is designed not to crash the compiler.
+
+- runtime errors are rendered inline as text
+- syntax errors are rendered inline as text
+- timed-out scripts are rendered inline as text
+- when `innerHTML` generation fails, the error is still escaped as text rather than inserted as raw HTML
+
+JavaScript blocks currently run with a 1-second timeout.