Merge pull request #30 from thisisthepy/work/notebook-spellings

Docs: Record how the notebook's convenience spellings are written

Author: b-re-w

PROJECT.md

@@ -106,8 +106,7 @@ python3 tools/check_guide.py                     # 가이드: HTML 파싱, 링
 
 1. **`test/` 디렉터리** — 2023–2024 Kotlin Multiplatform 샘플. 유지 / 이동 / 삭제 중 무엇인지.
    결정 전까지 손대지 않는다.
-2. **노트북식 편의 표기** — 소문자 `modifier` 인스턴스, `DefaultIcons`, ARGB 정수 색,
-   `Spacer(start=..., top=...)`.
+2. **코루틴 스코프** — 노트북이 import 하는 `DefaultCoroutineScope`·`MainCoroutineScope`.
 3. **`pythonx/compose/lite/release/`** 의 Windows 바이너리·jar 97 개와 빈 `material3/*.py` 28 개,
    서브모듈 `native` 의 처리.
 4. **`pythonx-map.toml` 의 이중 표기** — `pythonx.compose.layout` 과
@@ -124,6 +123,9 @@ python3 tools/check_guide.py                     # 가이드: HTML 파싱, 링
 - **`Column`·`Row`·`Spacer`** 는 `pythonx.compose.material3` 와 `pythonx.compose.layout` 양쪽에서
   import 된다.
 - **정렬 상수** 는 `Alignment.End` 와 `Alignment.Horizontal.End` 둘 다 지원한다.
+- 소문자 `modifier` 는 두지 않는다(`Modifier` 로 쓴다). ARGB 정수 색은 받지 않는다
+  (`Color(0xFFFF0000)`). `Spacer(start=...)` 는 지원하지 않는다(`Modifier.padding`). `DefaultIcons` 는
+  `Icons.Default` 의 alias(python-multiplatform #37 뒤). — `docs/INTENT.md` §5.4–5.7
 - 합성된 `pythonx` 를 전제한 테스트·독스트링은 #7 에서 정리했다.
 
 ## 8. 관련 저장소

docs/INTENT.md

@@ -123,9 +123,8 @@ types — even though the runtime resolves bindings on demand.
 
 These are recorded so that `docs/SPEC.md` does not settle them by accident.
 
-1. **Convenience spellings** the notebook uses that Kotlin does not have: a module-level
-   `modifier` instance, `DefaultIcons`, `DefaultCoroutineScope` / `MainCoroutineScope`, numeric
-   ARGB colours (`color=0xFFFF0000`), and `Spacer(start=..., top=...)`.
+1. **Coroutine scopes** the notebook imports, `DefaultCoroutineScope` / `MainCoroutineScope`.
+   (The other convenience spellings are decided, §5.4–5.7.)
 2. **The `test/` directory** — a 2023–2024 Kotlin Multiplatform sample (`pycomposeui`). Whether it
    is kept, moved, or removed is the maintainer's decision.
 
@@ -153,4 +152,13 @@ them.
 3. **Alignment constants in both spellings:** Kotlin's flat `Alignment.End`, and the notebook's
    grouping by type, `Alignment.Horizontal.End` (in Kotlin `Alignment.End` *is* an
    `Alignment.Horizontal`).
-
+4. **No lower-case `modifier`.** In Kotlin the empty modifier *is* `Modifier` (its companion); the
+   lower-case instance was the 2024 implementation's second name, and the archived design already
+   concluded to drop it. The notebook's `modifier=modifier` is written `modifier=Modifier`.
+5. **Colours are explicit.** A raw integer is not accepted for a `Color` parameter (`Color` packs
+   several fields into one value, so a number would decode as something else). The notebook's
+   `color=0xFFFF0000` is written `color=Color(0xFFFF0000)`, through Kotlin's own `Color` factory.
+6. **No parameters Kotlin does not have.** `Spacer(start=..., top=...)` is not supported; the
+   intent is written `Spacer(modifier=Modifier.padding(...))`.
+7. **`DefaultIcons` is `Icons.Default`,** served by name once the binder walks
+   `material-icons-core` (python-multiplatform #37).

docs/SPEC.md

@@ -245,9 +245,11 @@ name)` (python-multiplatform #36; issue #9).
 | Name | Notebook use | Note |
 |---|---|---|
 | `remember_saveable` | imported from `pythonx.compose.runtime`; state read/written with `getValue()` / `setValue()` | INTENT §5.1: Pythonic attribute access instead of the accessors |
-| `DefaultCoroutineScope`, `MainCoroutineScope` | imported from `pythonx.compose.runtime` | |
-| `DefaultIcons` | `DefaultIcons.Add()` | needs `Icon` (S5.3) |
-| `modifier` | lower-case instance from `pythonx.compose.ui` | INTENT §4 open question 1 |
+| `DefaultCoroutineScope`, `MainCoroutineScope` | imported from `pythonx.compose.runtime` | INTENT §4.1, open |
+| `DefaultIcons` | `DefaultIcons.Add()` | INTENT §5.7: `Icons.Default` by alias, once python-multiplatform #37 binds `material-icons-core` |
+| `modifier` | lower-case instance from `pythonx.compose.ui` | INTENT §5.4: not provided; written `Modifier` |
+| `color=0xFFFF0000` | ARGB integer for a colour | INTENT §5.5: not accepted; written `Color(0xFFFF0000)` |
+| `Spacer(start=..., top=...)` | spacing parameters | INTENT §5.6: not supported; written `Spacer(modifier=Modifier.padding(...))` |
 | `Column`, `Row`, `Spacer` | imported from `pythonx.compose.material3` | INTENT §5.2: served from both, by the manifest's `[aliases]` (`tests/test_chain.py::ManifestAliases`); render proof pending (#9) |
 | `Card`, `Button`, `Text`, `TextField` | as above | S5.2 |
 | `main.App`, `App.update(...)` | live screen replacement from a cell | INTENT §5.1: a declared root that a redefinition replaces, no update function (issue #11) |