rip-lang 3.16.0 → 3.16.1

package/docs/RIP-TYPES.md

@@ -59,10 +59,7 @@ Both compile to identical JavaScript.
 |-------|---------|---------|
 | `::` | Type annotation | `count:: number = 0` |
 | `type` | Type alias | `type ID = number` |
-| `?` | Optional value (`T \| undefined`) | `email:: string?` |
-| `??` | Nullable value (`T \| null \| undefined`) | `middle:: string??` |
-| `!` | Non-nullable (`NonNullable<T>`) | `id:: ID!` |
-| `?:` | Optional property | `email?: string` |
+| `?::` | Optional parameter / field / prop | `email?:: string` |
 | `\|` | Union member | `"a" \| "b" \| "c"` |
 | `=>` | Function type arrow | `(a: number) => string` |
 | `<T>` | Generic parameter | `Container<T>` |
@@ -284,106 +281,78 @@ type Dictionary = {
 
 ## Optionality Modifiers
 
-Lightweight suffix operators that map directly to TypeScript unions.
+Rip uses a single optionality marker: `?` placed on the **name**
+(parameter, type-alias field, structural field, or component prop)
+**before** the `::` annotation sigil. There are no `T?` / `T??` / `T!`
+type-suffix operators — write `T | undefined`, `T | null | undefined`,
+or `NonNullable<T>` directly when you need them.
 
-### Optional: `T?`
-
-Indicates a value may be undefined.
+### Optional Parameter / Field: `name?:: T`
 
 ```coffee
-email:: string?
-callback:: Function?
-```
-
-**Emits:**
-
-```ts
-email: string | undefined
-callback: Function | undefined
-```
+def greet(name?:: string):: void
+  console.log "hello #{name ?? 'world'}"
 
-### Nullable Optional: `T??`
-
-Indicates a value may be null or undefined.
-
-```coffee
-middle:: string??
-cache:: Map<string, any>??
+type User =
+  id:: number
+  name:: string
+  email?:: string      # Optional field — may be absent
 ```
 
 **Emits:**
 
 ```ts
-middle: string | null | undefined
-cache: Map<string, any> | null | undefined
-```
-
-### Non-Nullable: `T!`
+function greet(name?: string): void { ... }
 
-Asserts a value is never null or undefined.
-
-```coffee
-id:: ID!
-user:: User!
+type User = {
+  id: number;
+  name: string;
+  email?: string;
+};
 ```
 
-**Emits:**
-
-```ts
-id: NonNullable<ID>
-user: NonNullable<User>
-```
+### Component Props: `@prop?:: T [:= default]`
 
-### In Function Signatures
+A `?` on a component prop name marks it optional in the generated
+constructor type. A `:=` default is purely a runtime initializer — it
+does NOT make the prop optional on its own. The three canonical shapes:
 
 ```coffee
-def findUser(id:: number):: User?
-  db.find(id) or undefined
-
-def getUser(id:: number):: User!
-  db.find(id) ?? throw new Error "Not found"
-
-def updateUser(id:: number, email:: string??):: boolean
-  ...
+export Counter = component
+  @value::  number              # required, no default
+  @step?::  number              # optional, no default
+  @label?:: string := "Count"   # optional with default
 ```
 
 **Emits:**
 
 ```ts
-function findUser(id: number): User | undefined { ... }
-function getUser(id: number): NonNullable<User> { ... }
-function updateUser(id: number, email: string | null | undefined): boolean { ... }
+export declare class Counter {
+  constructor(props: {
+    value: number;
+    step?: number;
+    label?: string;
+  });
+}
 ```
 
-### Optional Properties
+Writing `@prop:: T := V` (typed, defaulted, no `?`) declares a
+**required prop with a default** — the parent must still pass it. To
+make a prop optional, add `?` to the name.
 
-In structural types, `?` after the property name makes it optional (the
-property itself may be absent), distinct from value optionality:
+### Expressing Value Optionality
 
-```coffee
-type User =
-  id: number
-  name: string
-  email?: string      # Optional property — may be absent
-  phone?: string?     # Optional property that can also be undefined when present
-```
-
-**Emits:**
+When the **value** itself needs to permit `undefined` or `null`, write
+the union explicitly:
 
-```ts
-type User = {
-  id: number;
-  name: string;
-  email?: string;
-  phone?: string | undefined;
-};
+```coffee
+email::  string | undefined
+middle:: string | null | undefined
+id::     NonNullable<ID>
 ```
 
-### Key Distinction
-
-- `email?: string` — property may be absent
-- `email:: string?` — value may be undefined
-- `email?: string??` — property may be absent, value may be null or undefined
+This is the same form TypeScript uses, so the emitted DTS is a
+character-for-character match.
 
 ---
 
@@ -647,18 +616,20 @@ Types are optional and gradual:
 
 ### Project Level
 
-Configure via `rip.json` or the `"rip"` key in `package.json`:
+Configure via the `"rip"` key in `package.json`:
 
 ```json
 {
   "strict": true,
+  "checkAll": true,
   "exclude": ["vendor/**", "legacy/**"]
 }
 ```
 
 | Key | Purpose |
 |-----|--------|
-| `strict` | Enable strict mode for `rip check` (default: `false`) |
+| `strict` | Enable TS strict family for `rip check` (default: `false`) |
+| `checkAll` | Type-check every non-`@nocheck` `.rip` file, not just annotated ones (default: `false`) |
 | `exclude` | Glob patterns for files to skip during `rip check` |
 
 ### File Level
@@ -1153,9 +1124,10 @@ collection — the token itself is the answer:
 
 **Other special cases:**
 
-- **`?` / `??` / `!` suffixes**: These modify the type. When they appear
-  unspaced after an identifier at depth 0, they are part of the type:
-  `string?` → `"string?"`, `ID!` → `"ID!"`.
+- **`?` on names**: When `?` appears unspaced **before** a `::` annotation
+  on a parameter, field, or component prop name, the lexer marks the name
+  token as optional (`data.optional = true`). This is the sole optionality
+  marker — there are no `?` / `??` / `!` suffixes on type expressions.
 - **Generic `<>` vs comparison**: Inside a type context (after `::`), always
   treat `<` as opening a generic bracket. The type context is unambiguous
   because we are already inside a `::` collection.
@@ -1341,12 +1313,12 @@ syntax into standard TypeScript:
 | Rip syntax | TypeScript equivalent |
 |-----------|---------------------|
 | `::` | `:` (annotation sigil to type separator) |
-| `T?` | `T \| undefined` |
-| `T??` | `T \| null \| undefined` |
-| `T!` | `NonNullable<T>` |
+| `name?::` | `name?:` (optional parameter / field / prop) |
 
 Function type expressions use `=>` directly (same as TypeScript), so no
-arrow conversion is needed.
+arrow conversion is needed. Value-level optionality is written with
+explicit unions (`T | undefined`, `T | null`, `NonNullable<T>`) — there
+are no type-suffix operators.
 
 The function returns a `.d.ts` string. Declarations without type
 annotations are skipped — only annotated code appears in the output.
@@ -1774,29 +1746,28 @@ Type annotations never affect `let` vs `const` in `.js` output:
 
 ### Edge Cases
 
-#### Optionality Suffixes in Types
+#### Optionality Marker on Names
 
-The `?`, `??`, and `!` suffixes appear unspaced after the type name:
+A `?` placed unspaced **before** the `::` annotation on a parameter,
+field, or component prop name marks the name as optional:
 
 ```coffee
-email:: string?       # → type = "string?"
-middle:: string??     # → type = "string??"
-id:: ID!              # → type = "ID!"
-```
-
-In `rewriteTypes()`, when collecting type tokens, if the next token is `?`,
-`??`, or `!` and is **not spaced** from the previous token, include it as
-part of the type string.
+def fetch(url:: string, opts?:: RequestInit):: Response
+  ...
 
-The `emitTypes()` function expands these suffixes into standard TypeScript:
+type User =
+  id::    number
+  email?:: string   # optional field
+```
 
-| Rip suffix | TypeScript equivalent |
-|-----------|---------------------|
-| `T?` | `T \| undefined` |
-| `T??` | `T \| null \| undefined` |
-| `T!` | `NonNullable<T>` |
+In the lexer, when `?` appears immediately before `::`, it is stripped
+from the stream and `data.optional = true` is set on the preceding
+name token. `emitTypes()` reads that flag and emits `name?:` instead of
+`name:` in the generated TypeScript.
 
-See §1.6 for the full Rip-to-TypeScript conversion table (including `::` → `:`).
+Value-level optionality is expressed with explicit unions — there are
+no `T?` / `T??` / `T!` type-suffix operators. See §1.6 for the full
+Rip-to-TypeScript conversion table.
 
 #### File-Level Type Directives
 

package/docs/demo/README.md

@@ -6,7 +6,7 @@ The canonical "everything in one file" demo of the Rip App framework. Six compon
 
 ```
 docs/demo/
-├── components/
+├── routes/
 │   ├── _layout.rip   — root layout with nav + error boundary
 │   ├── index.rip     — Home page (file-based routing: / → index.rip)
 │   ├── counter.rip   — reactive state, := / ~> persistence to stash
@@ -22,7 +22,8 @@ docs/demo/
 ```bash
 bun run bundle:demo
 # wraps:
-# bun scripts/bundle-app.js docs/demo -o docs/example/index.json -t "Rip App Demo"
+# bun scripts/bundle-app.js docs/demo/routes --prefix _route --css docs/demo/css \
+#   -o docs/example/index.json -t "Rip App Demo"
 ```
 
 Output: `docs/example/index.json` — a single ~17 KB file containing every component's raw `.rip` source plus all CSS, ready to ship to any static host. The launcher at `docs/example/index.html` fetches it once and runs the whole app from memory: no bundler, no build step, no per-component network requests.
@@ -38,6 +39,6 @@ Then `<script type="text/rip">launch bundle: bundle</script>` mounts everything.
 
 ## Iterating
 
-Edit any `.rip` file under `components/`, then re-run `bun run bundle:demo` to refresh the bundled JSON. The launcher HTML at `docs/example/` will pick up the new bundle on next load.
+Edit any `.rip` file under `routes/`, then re-run `bun run bundle:demo` to refresh the bundled JSON. The launcher HTML at `docs/example/` will pick up the new bundle on next load.
 
 CSS is concatenated alphabetically by filename. Add `.css` files under `css/` to extend the design.